[Grid agent] Establish the pure-Rust architecture and configuration contract #118

New Issue

hugo · 2026-08-17T19:31:33Z

hugo commented

2026-08-17 19:31:33 +00:00

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.

## 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

hugo added the enhancement label 2026-08-17 19:31:33 +00:00

hugo referenced this issue

2026-08-17 19:32:14 +00:00

implement an AI driven agent that runs in opensim #117

hugo referenced this issue from a commit

2026-08-17 20:15:50 +00:00

feat(grid-agent): establish architecture and config (#118)

hugo commented

2026-08-17 20:16:13 +00:00

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.

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.

hugo closed this issue

2026-08-17 20:16:50 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#118