This package is the bounded, provider-neutral foundation for the MetaCrate OpenSim grid agent. It contains a reusable library and the metacrate-grid-agent service binary. The default service graph is deliberately offline: it publishes a deterministic ready event, accepts control commands, and shuts down both owned tasks without contacting a grid or LLM. The library also provides the bounded exact-endpoint LLM transport and tool loop for live adapters. The live-grid feature exposes the owner for the existing libremetaverse::GridClient. Its supervised session adapter reuses that client's native NetworkManager for login, event-queue readiness, disconnect notifications, and logout instead of adding a protocol client.

The LLM connection identity has exactly two resolved fields: llm.endpoint_url and llm.api_key. The endpoint is used exactly as supplied; there are no providers, presets, base-URL rewrites, model catalogs, discovery, or provider SDKs. Debug/Display output removes API keys, grid passwords, URL user information, and URL query values. Secret wrappers are not serializable.

Configuration precedence, from lowest to highest, is built-in defaults, an optional JSON file, its referenced secret files, then environment values (an environment-referenced secret file is below a direct environment secret). Supported secret environment variables are METACRATE_AGENT_LLM_API_KEY[_FILE] and METACRATE_AGENT_GRID_PASSWORD[_FILE]. Split control uses the separate METACRATE_AGENT_CONTROL_OPERATOR_TOKEN[_FILE] and optional METACRATE_AGENT_CONTROL_OBSERVER_TOKEN[_FILE], plus METACRATE_AGENT_CONTROL_LISTEN. Secret files must be bounded regular, non-symlink UTF-8 files containing one line. Operators must restrict their OS ACLs to the service identity; the core uses only portable std::fs checks and does not assume Unix permission bits.

Run the focused offline gate with:

cargo test --locked -p metacrate-grid-agent
cargo clippy --locked -p metacrate-grid-agent --all-targets -- -D warnings
cargo run --locked -p metacrate-grid-agent -- \
  --config config/grid-agent.example.json --check-config
cargo run --locked -p metacrate-grid-agent -- \
  --config config/grid-agent.example.json --run-once

See ../../docs/grid-agent-architecture.md for queue/task ownership, shutdown, and trust boundaries. See ../../docs/grid-agent-llm.md for the LLM wire compatibility envelope, retry rules, and tool-loop safety contract. The central origin matrix, approval binding, budgets, prompt-data boundary, and opaque backend authorization are specified in ../../docs/grid-agent-policy.md. The reconnect state machine, generation fencing, offline-work contract, and shutdown deadline are specified in ../../docs/grid-agent-session.md. Per-avatar/channel expiry, compaction, redaction, optional atomic persistence, and metadata-only operator controls are specified in ../../docs/grid-agent-conversation.md. The versioned integrated/TCP protocol, roles, framing, bounds, TLS remote-mode requirements, events, and management methods are specified in ../../docs/grid-agent-control-plane.md. The unified event schema, pseudonymous correlations, bounded JSONL rotation, fixed-cardinality metrics, diagnostic-capture warning, and non-executing replay contract are specified in ../../docs/grid-agent-observability.md. The embedded/split cross-platform operator interface, keyboard controls, privacy boundary, and focused gates are documented in ../../docs/grid-agent-tui.md. The complete quick start, platform paths, systemd/Windows service operation, secret rotation, backup/upgrade/rollback, failure playbooks, resource defaults, and unsupported-operation list are in ../../docs/grid-agent-operations.md. Milestone acceptance, resource budgets, evidence, and opt-in live validation are defined in ../../docs/grid-agent-acceptance.md.