MetaCrate/docs/grid-agent-architecture.md

Grid-agent architecture foundation

The grid agent is a workspace-owned Rust library and small service binary. Its core depends on Tokio for scheduling and bounded channels. Its live-grid feature owns the existing libremetaverse composition root for grid protocol managers; the default offline graph does not compile live transports. It does not create a second login, UDP, capabilities, inventory, or world client. It contains no CLR/.NET loading, sidecar, subprocess adapter, provider SDK, native ABI, or platform-specific core path.

Ownership and bounds

AgentService::start is the sole task-creation point. It validates the complete configuration before allocating channels, calling a backend, or permitting network access. ServiceHandle then exclusively owns cancellation, both join handles, the control sender, and observable receiver.

Resource	Owner	Hard/configured bound	Backpressure/termination
Grid-event queue	coordinator receives; backend sends	8,192 / grid_event_queue	async send or cancellation
Control queue	coordinator receives; handle sends	256 / control_queue	async send; closed after stop
Observable queue	handle receives; coordinator/backend send	8,192 / observable_queue	async send or cancellation
Backend task	ServiceHandle.tasks[0]	exactly one	shared cancellation token, joined first
Coordinator task	ServiceHandle.tasks[1]	exactly one	shared cancellation token, joined second
Body / message	typed boundary owners	8 MiB / 64 KiB hard ceilings, with lower configured limits	rejected before enqueue
Conversation / tool calls	request owner	256 messages / 64 calls, with lower configured limits	rejected before request
LLM request slots	shared LlmClient semaphore	256 hard / configured concurrent requests	async acquire or cancellation
Reasoning/tool session	ToolLoop caller	32 turns / 256 calls hard, with lower configured limits	total timeout, cancellation, or supersession
Policy tools / approvals / schedules	PolicyGateway mutex	64 tools / 4,096 approval records / 1,024 scheduler grants hard	deny before opaque authorization
Principal/global resource budget	PolicyGateway time window	validated calls, zero L$, upload, inventory, movement, and build ceilings	atomic charge or stable denial
Authorized avatars	immutable AgentConfig set	1,024 hard ceiling, lower configured limit	malformed, nil, duplicate, and wildcard input rejected
Configuration / secret file	loader	64 KiB / 16 KiB	regular non-symlink file only

BoundedText and BoundedVec make message and collection ceilings part of the type. Dynamic configuration can lower these absolute ceilings but cannot raise them. Backend error text is not forwarded; observations publish a fixed bounded diagnostic.

State machine and shutdown

The explicit service states are starting -> running <-> paused -> stopping -> stopped, with failed reserved for task failure. The offline backend publishes BackendReady, after which the coordinator enters running. A shutdown control, direct handle shutdown, backend failure, closed owner queue, or handle drop triggers the same cancellation token.

Orderly shutdown first cancels, joins the backend, and then joins the coordinator. Each join has the validated shutdown timeout. A late task is aborted and awaited before return. A partially polled shutdown future only borrows each join handle, so cancelling that future leaves every task in the handle's fixed ownership slots for a retry or final drop. Dropping the handle cancels and aborts all remaining owned tasks, so no task is detached. A feature-enabled live adapter drops its LibremetaverseClientOwner last, invoking the existing client ownership shutdown.

Trust boundaries

• JSON configuration and environment text are untrusted. Unknown fields, oversized files, invalid booleans, conflicting modes, non-HTTP(S) URLs, URL fragments, malformed/noncanonical/nil UUIDs, wildcard authorization, multiline secrets, and unsafe limits fail before startup.
• SecretString and EndpointUrl are the only credential-bearing value types. Secrets are never serializable or printable. Endpoint diagnostics replace user information, passwords, and the complete query.
• Grid input crosses GridBackend only through bounded GridEvent values. The live-grid feature supplies LibremetaverseClientOwner; live implementations must own it and reuse its client and managers.
• World changes cross only WorldMutator::apply, which always receives the non-forgeable AuthorizedAction produced by PolicyGateway. Raw calls and caller-created decisions are not accepted. This issue supplies no live mutation implementation.
• LLM traffic crosses one exact configured URL through LlmClient. Redirects are refused, response bodies are bounded while streaming, bearer secrets are redacted, and provider/model discovery does not exist. Proposed calls cross ToolExecutor only after registered-name and schema validation.
• Signals and console output belong to the binary. The reusable core relies on no terminal, Unix socket, Unix signal, separator, or fixed platform path.

Dependency diagram

metacrate-grid-agent binary (portable Ctrl-C + config path)
                    |
                    v
AgentService -> bounded Tokio channels/tasks -> injected GridBackend
     |                                           |
     v                                           v
typed config/events/policy boundaries    live-grid feature boundary
     |                                           |
     +-----------------> libremetaverse-types    +--> libremetaverse::GridClient

avatar session -> bounded ToolLoop -> exact-endpoint LlmClient
                       |
                       +-> PolicyToolExecutor -> PolicyGateway
                                                   |
                                                   +-> AuthorizedToolBackend

The package has no build script or direct native dependency. The focused dependency_policy test rejects subprocess launch sites, unsafe/native ABI source, build scripts, and unreviewed direct dependency names in this package. The precise LLM compatibility and cancellation contract is documented in grid-agent-llm.md. The origin/capability matrix and opaque mutation boundary are documented in grid-agent-policy.md.