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:
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
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 live-grid validation
are defined in
../../docs/grid-agent-acceptance.md.