# MetaCrate grid agent

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 an exact `llm.endpoint_url`, `llm.api_key`, and
optional `llm.model`. 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.

Persistent setup lives in the platform `config.yml` (normally
`~/.config/metacrate/config.yml` on Linux). The file contains grid/AI
connectivity and the exact privileged avatar UUID list; it is written with mode
0600 on Unix. `--preferences` opens the setup panel without starting the
service. `--import-env .env` performs a one-time import of the legacy
`GRID_*`/`OPENAPI_*` values; runtime configuration does not read `.env` or
connection environment variables. JSON files and referenced secret files are
accepted only as a legacy migration input.

Run the focused offline gate with:

```sh
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.yml --check-config
cargo run --locked -p metacrate-grid-agent -- \
  --config config/grid-agent.example.yml --run-once
```

See [`../../docs/grid-agent-architecture.md`](../../docs/grid-agent-architecture.md)
for queue/task ownership, shutdown, and trust boundaries. See
[`../../docs/grid-agent-llm.md`](../../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`](../../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`](../../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`](../../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`](../../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`](../../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`](../../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`](../../docs/grid-agent-operations.md).
Milestone acceptance, resource budgets, evidence, and live-grid validation
are defined in
[`../../docs/grid-agent-acceptance.md`](../../docs/grid-agent-acceptance.md).