70 lines
4.0 KiB
Markdown
70 lines
4.0 KiB
Markdown
# 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).
|