Establish the implementation boundary and configuration contract for a compact native Rust OpenSim agent built on the existing libremetaverse APIs. This issue creates the executable/library skeleton and shared domain types that every later milestone issue uses; it must not implement provider-specific LLM logic or high-level agent features.
Required design
Add a workspace-owned grid-agent package with a small service binary and reusable library modules. Reuse libremetaverse managers instead of duplicating protocol clients.
Use Tokio tasks, bounded channels, cancellation tokens, and explicit state machines. No CLR, .NET assembly, Python/Node sidecar, subprocess protocol adapter, provider SDK, or C/C++ dependency may be introduced by the agent.
Keep all code and public/internal APIs portable across Linux, Windows, and macOS. Platform packaging may be separate, but core behavior must not depend on Unix sockets, signals, paths, or terminal facilities.
Define stable typed boundaries for grid events, normalized conversations, LLM requests/results, proposed tool calls, policy decisions, control commands, and observable events. Keep world mutation behind narrow traits so fake and live backends execute the same orchestration.
Define configuration precedence and validation. Grid credentials, login URL, authorized avatar UUIDs, timeouts, resource limits, storage paths, and behavior settings may be configurable. The LLM connection itself has exactly two required fields: an exact endpoint URL and an API key. Do not add provider names, provider presets, provider-specific base URL rewriting, model catalogs, or cloud discovery.
Treat the API key and grid password as secrets: accept environment variables and restricted secret files, represent them with redacting wrappers, and never serialize or display them.
Reject unsafe limits, non-HTTP(S) LLM URLs, malformed UUIDs, wildcard authorization, and conflicting integrated/split modes before grid login or network access.
Deliverables
Package/binary skeleton, configuration structs and example configuration with placeholders only.
Backend traits and state/event types shared by later work.
A short architecture document with task ownership, bounded queues, shutdown order, trust boundaries, and a dependency diagram.
Dependency-policy checks proving the new package remains pure Rust and does not launch subprocesses.
Acceptance criteria
Minimal configuration starts in offline/fake mode and fails fast with actionable typed errors when required live settings are absent or invalid.
LLM configuration exposes only endpoint URL and API key as connection identity; logs and Debug output redact both secrets and URL credentials/query secrets.
Every queue, body, message, collection, and background task has an explicit bound and owner.
The package compiles on the workspace MSRV and portable target checks; any Gitea workflow changes use ubuntu-latest only.
Unit tests cover precedence, redaction, URL/UUID validation, limit validation, and cancellation-safe skeleton shutdown.
Dependencies and exclusions
This is the first milestone issue. Do not implement chat behavior, tools, persistence, TUI screens, live-grid mutations, or a provider abstraction here.
## Objective
Establish the implementation boundary and configuration contract for a compact native Rust OpenSim agent built on the existing `libremetaverse` APIs. This issue creates the executable/library skeleton and shared domain types that every later milestone issue uses; it must not implement provider-specific LLM logic or high-level agent features.
## Required design
- Add a workspace-owned grid-agent package with a small service binary and reusable library modules. Reuse `libremetaverse` managers instead of duplicating protocol clients.
- Use Tokio tasks, bounded channels, cancellation tokens, and explicit state machines. No CLR, .NET assembly, Python/Node sidecar, subprocess protocol adapter, provider SDK, or C/C++ dependency may be introduced by the agent.
- Keep all code and public/internal APIs portable across Linux, Windows, and macOS. Platform packaging may be separate, but core behavior must not depend on Unix sockets, signals, paths, or terminal facilities.
- Define stable typed boundaries for grid events, normalized conversations, LLM requests/results, proposed tool calls, policy decisions, control commands, and observable events. Keep world mutation behind narrow traits so fake and live backends execute the same orchestration.
- Define configuration precedence and validation. Grid credentials, login URL, authorized avatar UUIDs, timeouts, resource limits, storage paths, and behavior settings may be configurable. The LLM connection itself has exactly two required fields: an exact endpoint URL and an API key. Do not add provider names, provider presets, provider-specific base URL rewriting, model catalogs, or cloud discovery.
- Treat the API key and grid password as secrets: accept environment variables and restricted secret files, represent them with redacting wrappers, and never serialize or display them.
- Reject unsafe limits, non-HTTP(S) LLM URLs, malformed UUIDs, wildcard authorization, and conflicting integrated/split modes before grid login or network access.
## Deliverables
- Package/binary skeleton, configuration structs and example configuration with placeholders only.
- Backend traits and state/event types shared by later work.
- A short architecture document with task ownership, bounded queues, shutdown order, trust boundaries, and a dependency diagram.
- Dependency-policy checks proving the new package remains pure Rust and does not launch subprocesses.
## Acceptance criteria
- [ ] Minimal configuration starts in offline/fake mode and fails fast with actionable typed errors when required live settings are absent or invalid.
- [ ] LLM configuration exposes only endpoint URL and API key as connection identity; logs and `Debug` output redact both secrets and URL credentials/query secrets.
- [ ] Every queue, body, message, collection, and background task has an explicit bound and owner.
- [ ] The package compiles on the workspace MSRV and portable target checks; any Gitea workflow changes use `ubuntu-latest` only.
- [ ] Unit tests cover precedence, redaction, URL/UUID validation, limit validation, and cancellation-safe skeleton shutdown.
## Dependencies and exclusions
This is the first milestone issue. Do not implement chat behavior, tools, persistence, TUI screens, live-grid mutations, or a provider abstraction here.
hugo
added this to the 14 - metacrate grid agent milestone 2026-08-17 19:31:33 +00:00
Added validated configuration precedence across JSON, restricted/bounded secret files, and environment variables. The resolved LLM connection has exactly endpoint_url and api_key.
Added redacting secret/endpoint wrappers, HTTP(S)/UUID/wildcard/mode/limit validation, three bounded queues, two explicitly owned Tokio tasks, cancellation-safe shutdown, and an offline fake backend.
Added a portable example, an offline --run-once startup/shutdown gate, architecture/trust-boundary documentation, and a source/dependency policy test that rejects subprocess/native ABI escape hatches.
Review found and fixed a mid-shutdown cancellation edge so join handles remain owned even if the shutdown future is dropped.
Verification:
cargo test --locked -p metacrate-grid-agent: 13 unit tests, 2 dependency-policy tests, and doc tests passed.
Example --check-config and --run-once both passed offline.
Package checks passed for Linux, x86_64-pc-windows-gnu, and x86_64-apple-darwin; the library also passed wasm32-unknown-unknown.
metacrate-ci-matrix dependency-audit, cargo-deny, and cargo-machete passed.
No live grid or LLM access was needed for this foundational offline issue, and no secrets were read or committed.
Implemented and pushed in commit 1e1e95a.
Summary:
- Added the workspace-owned metacrate-grid-agent library and service binary with an opt-in live-grid composition boundary that reuses libremetaverse.
- Added typed, size-bounded grid, conversation, LLM, tool, policy, control, and observable boundaries.
- Added validated configuration precedence across JSON, restricted/bounded secret files, and environment variables. The resolved LLM connection has exactly endpoint_url and api_key.
- Added redacting secret/endpoint wrappers, HTTP(S)/UUID/wildcard/mode/limit validation, three bounded queues, two explicitly owned Tokio tasks, cancellation-safe shutdown, and an offline fake backend.
- Added a portable example, an offline --run-once startup/shutdown gate, architecture/trust-boundary documentation, and a source/dependency policy test that rejects subprocess/native ABI escape hatches.
- Review found and fixed a mid-shutdown cancellation edge so join handles remain owned even if the shutdown future is dropped.
Verification:
- cargo test --locked -p metacrate-grid-agent: 13 unit tests, 2 dependency-policy tests, and doc tests passed.
- cargo clippy --locked -p metacrate-grid-agent --all-targets -- -D warnings passed.
- rustdoc with warnings denied passed.
- Example --check-config and --run-once both passed offline.
- Package checks passed for Linux, x86_64-pc-windows-gnu, and x86_64-apple-darwin; the library also passed wasm32-unknown-unknown.
- metacrate-ci-matrix dependency-audit, cargo-deny, and cargo-machete passed.
No live grid or LLM access was needed for this foundational offline issue, and no secrets were read or committed.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Objective
Establish the implementation boundary and configuration contract for a compact native Rust OpenSim agent built on the existing
libremetaverseAPIs. This issue creates the executable/library skeleton and shared domain types that every later milestone issue uses; it must not implement provider-specific LLM logic or high-level agent features.Required design
libremetaversemanagers instead of duplicating protocol clients.Deliverables
Acceptance criteria
Debugoutput redact both secrets and URL credentials/query secrets.ubuntu-latestonly.Dependencies and exclusions
This is the first milestone issue. Do not implement chat behavior, tools, persistence, TUI screens, live-grid mutations, or a provider abstraction here.
Implemented and pushed in commit
1e1e95a.Summary:
Verification:
No live grid or LLM access was needed for this foundational offline issue, and no secrets were read or committed.