[Grid agent] Provide a portable control plane for integrated and split operation #126

New Issue

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

hugo commented

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

Objective

Provide a versioned, authenticated control plane so the agent can run headless as a service while an integrated UI or separate TUI observes and manages the same process semantics.

Protocol and transport

Define a small request/response plus event-stream protocol with explicit version negotiation, request IDs, pagination, typed errors, cancellation, and backpressure.
Support an in-process transport for integrated mode and a portable loopback TCP transport for split mode. Do not make Unix domain sockets, named pipes, Unix permissions, or terminal state part of the core API.
Bind loopback by default. Authenticate every split connection with a separate operator token stored/redacted like other secrets. Remote binding is disabled by default and requires explicit TLS plus documented threat warnings; never reuse the LLM API key or grid password.
Bound frames, connections, requests, subscriptions, queues, event rates, and idle time. Slow/disconnected clients cannot block the agent or retain unbounded history.

Management surface

Read health/readiness, grid lifecycle, current region/pose, behavior mode, queue/budget utilization, session metadata, scheduled jobs, pending approvals, and redacted recent audit events.
Pause/resume autonomy, cancel a pending action, approve/deny a bound proposal, force reconnect, expire a conversation, enable/disable an existing roaming job, inject an operator message/command, and request graceful shutdown.
Separate read-only observation from operator mutation permissions. Log every authenticated mutation and its outcome.
Never expose credentials, raw auth headers, capability URLs, unrestricted prompt contents, private hidden reasoning, or arbitrary filesystem access.

Acceptance criteria

The same conformance suite runs against in-process and TCP transports and proves equivalent semantics.
Tests cover bad versions/tokens, oversized/partial frames, replay, request cancellation, reconnect/resubscribe, slow consumers, event gaps, concurrent operators, and shutdown.
The agent remains fully functional headless with zero UI clients and responsive under a bounded event flood.
Protocol types are documented well enough for a later non-TUI client without linking internal runtime structs.

Dependencies

Depends on architecture/state types and policy. It consumes lifecycle, session, scheduler, approval, and observability APIs as those land.

## Objective Provide a versioned, authenticated control plane so the agent can run headless as a service while an integrated UI or separate TUI observes and manages the same process semantics. ## Protocol and transport - Define a small request/response plus event-stream protocol with explicit version negotiation, request IDs, pagination, typed errors, cancellation, and backpressure. - Support an in-process transport for integrated mode and a portable loopback TCP transport for split mode. Do not make Unix domain sockets, named pipes, Unix permissions, or terminal state part of the core API. - Bind loopback by default. Authenticate every split connection with a separate operator token stored/redacted like other secrets. Remote binding is disabled by default and requires explicit TLS plus documented threat warnings; never reuse the LLM API key or grid password. - Bound frames, connections, requests, subscriptions, queues, event rates, and idle time. Slow/disconnected clients cannot block the agent or retain unbounded history. ## Management surface - Read health/readiness, grid lifecycle, current region/pose, behavior mode, queue/budget utilization, session metadata, scheduled jobs, pending approvals, and redacted recent audit events. - Pause/resume autonomy, cancel a pending action, approve/deny a bound proposal, force reconnect, expire a conversation, enable/disable an existing roaming job, inject an operator message/command, and request graceful shutdown. - Separate read-only observation from operator mutation permissions. Log every authenticated mutation and its outcome. - Never expose credentials, raw auth headers, capability URLs, unrestricted prompt contents, private hidden reasoning, or arbitrary filesystem access. ## Acceptance criteria - [ ] The same conformance suite runs against in-process and TCP transports and proves equivalent semantics. - [ ] Tests cover bad versions/tokens, oversized/partial frames, replay, request cancellation, reconnect/resubscribe, slow consumers, event gaps, concurrent operators, and shutdown. - [ ] The agent remains fully functional headless with zero UI clients and responsive under a bounded event flood. - [ ] Protocol types are documented well enough for a later non-TUI client without linking internal runtime structs. ## Dependencies Depends on architecture/state types and policy. It consumes lifecycle, session, scheduler, approval, and observability APIs as those land.

hugo added this to the 14 - metacrate grid agent milestone 2026-08-17 19:31:36 +00:00

hugo added the enhancement label 2026-08-17 19:31:36 +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-18 04:29:22 +00:00

feat(grid-agent): add portable control plane (#126)

hugo commented

2026-08-18 04:29:49 +00:00

Implemented and verified in commit 962d172 (feat(grid-agent): add portable control plane (#126)).

Implementation:

Added a versioned request/response and sequenced event protocol with typed errors, request IDs, pagination, replay rejection, cancellation, bounded backpressure, atomic resubscription cursors, explicit event gaps, and redacted mutation outcomes.
Added equivalent authenticated in-process and length-prefixed JSON TCP transports, observer/operator roles, constant-time token checks, loopback-only plaintext, explicit Rustls remote mode, bounded TLS/connect/idle/write deadlines, and owned shutdown of listener/connection/request/writer tasks.
Added hard bounds for frames, connections, in-flight work, subscriptions, replay/event history, event bytes/rates, response pages, and queues; slow consumers are disconnected and zero-client flooding stays bounded.
Added the production management target for health/readiness, lifecycle, region/pose, behavior, queue/budget use, conversation metadata, jobs, approvals, and redacted audit. Mutations reach the real session, behavior, conversation, policy, and lifecycle components.
Added exact-ID cancellation for queued or executing behavior actions, including bounded registration and proof that unrelated actions are not preempted.
Added split-mode configuration with dedicated redacted control tokens; reuse of the LLM key/grid password is rejected. Non-loopback binding requires bounded DER certificate/key files and emits a startup warning.
Documented protocol v1, framing, JSON negotiation, permissions, errors, reconnection, bounds, TLS, and threat model in docs/grid-agent-control-plane.md.

Verification:

cargo test -p metacrate-grid-agent --lib: 94 passed.
Focused control-plane suite: 11 passed across in-process/TCP, covering bad versions/tokens, oversized/partial frames, replay, cancellation, separate concurrent operators, reconnect/resubscribe, slow consumers, gaps, bounded subscriptions/flooding, and shutdown.
Related compatibility tests: dependency_policy 5 passed; policy_gateway 3 passed; session_supervisor 1 passed; conversation_memory 1 passed.
cargo clippy -p metacrate-grid-agent --all-targets -- -D warnings: passed.
Rustdoc with warnings denied, cargo fmt --check, git diff --check, and cargo deny check: passed.
Live-grid binary wiring passed clippy against the API-faithful libremetaverse adapter stub. A direct full live-grid check was also attempted; this runner killed rustc while compiling the very large libremetaverse crate at its memory ceiling, before compiling the changed agent crate. No live credentials or .env contents were read or committed.

Implemented and verified in commit 962d172 (feat(grid-agent): add portable control plane (#126)). Implementation: - Added a versioned request/response and sequenced event protocol with typed errors, request IDs, pagination, replay rejection, cancellation, bounded backpressure, atomic resubscription cursors, explicit event gaps, and redacted mutation outcomes. - Added equivalent authenticated in-process and length-prefixed JSON TCP transports, observer/operator roles, constant-time token checks, loopback-only plaintext, explicit Rustls remote mode, bounded TLS/connect/idle/write deadlines, and owned shutdown of listener/connection/request/writer tasks. - Added hard bounds for frames, connections, in-flight work, subscriptions, replay/event history, event bytes/rates, response pages, and queues; slow consumers are disconnected and zero-client flooding stays bounded. - Added the production management target for health/readiness, lifecycle, region/pose, behavior, queue/budget use, conversation metadata, jobs, approvals, and redacted audit. Mutations reach the real session, behavior, conversation, policy, and lifecycle components. - Added exact-ID cancellation for queued or executing behavior actions, including bounded registration and proof that unrelated actions are not preempted. - Added split-mode configuration with dedicated redacted control tokens; reuse of the LLM key/grid password is rejected. Non-loopback binding requires bounded DER certificate/key files and emits a startup warning. - Documented protocol v1, framing, JSON negotiation, permissions, errors, reconnection, bounds, TLS, and threat model in docs/grid-agent-control-plane.md. Verification: - cargo test -p metacrate-grid-agent --lib: 94 passed. - Focused control-plane suite: 11 passed across in-process/TCP, covering bad versions/tokens, oversized/partial frames, replay, cancellation, separate concurrent operators, reconnect/resubscribe, slow consumers, gaps, bounded subscriptions/flooding, and shutdown. - Related compatibility tests: dependency_policy 5 passed; policy_gateway 3 passed; session_supervisor 1 passed; conversation_memory 1 passed. - cargo clippy -p metacrate-grid-agent --all-targets -- -D warnings: passed. - Rustdoc with warnings denied, cargo fmt --check, git diff --check, and cargo deny check: passed. - Live-grid binary wiring passed clippy against the API-faithful libremetaverse adapter stub. A direct full live-grid check was also attempted; this runner killed rustc while compiling the very large libremetaverse crate at its memory ceiling, before compiling the changed agent crate. No live credentials or .env contents were read or committed.

hugo closed this issue

2026-08-18 04:30:43 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#126