9.1 KiB
Tess Architecture
Purpose
Tess is the Mosaic operator interaction plane. Mos remains the coding/general fleet orchestration authority. Tess receives authorized operator intent, presents fleet/session state, delegates Mos-owned work to Mos, and exposes native Mosaic plus transitional external-agent capabilities through normalized providers.
Component Boundaries
Discord plugin ─┐
├─ authenticated ingress envelope ─> Mosaic Gateway
mosaic tess CLI ┘ │
├─ policy/approval/audit
├─ Tess durable session service (Pi GPT-5.6 Sol high)
├─ AgentRuntimeProvider registry
│ ├─ native Pi provider
│ ├─ fleet/tmux provider
│ ├─ Hermes adapter
│ └─ Matrix/native transport provider
├─ memory/state/inbox plugins
└─ Mos coordination adapter ─> Mos / fleet queue
Core Contract
AgentRuntimeProvider is separate from the existing model-completion IProviderAdapter. It normalizes external and native agent runtimes without leaking provider-specific schemas.
Required operations:
capabilities()andhealth()listSessions(scope)getSessionTree(scope)streamSession(sessionRef, cursor, scope)sendMessage(sessionRef, message, idempotencyKey, scope)attach(sessionRef, mode, scope)/detach()terminate(sessionRef, approvalRef, scope)
Every call receives an immutable, server-derived actor/tenant/channel scope and correlation ID. Caller-supplied actor IDs are forbidden. Unsupported capabilities fail closed with typed errors.
M1 Registry Boundary
@mosaicstack/agent owns the explicit AgentRuntimeProviderRegistry; duplicate provider IDs are rejected rather than replaced. Gateway owns RuntimeProviderService, which creates a frozen RuntimeScope from authenticated ActorTenantScope and trusted ingress channel/correlation metadata before every provider call. The service checks the declared provider capability before invoking a side effect and records metadata-only audit events (providerId, operation, outcome, actor/tenant/channel, correlation, and resource ID). It never records message bodies, idempotency keys, or approval references.
Termination is fail-closed: a runtime approval verifier consumes a one-time, exact action binding for the provider, session, actor, tenant, channel, and correlation ID before terminate reaches a provider. The verifier reuses the Redis-backed interaction:command-approval:* store and its expiry/delete-on-consume semantics; it has no parallel approval store. This internal service introduces no HTTP endpoint; later Discord, CLI, MCP, and provider adapters consume the same gateway boundary.
Authority Model
| Intent | Owner | Tess behavior |
|---|---|---|
| Conversation, status, retrieval, safe diagnostics | Tess | Execute within policy |
| Code/project decomposition, worker assignment, reviews, merge orchestration | Mos | Create a correlated handoff and observe result |
| Destructive, privileged, external/customer-visible action | Human approval + policy | Propose, wait for durable one-time approval, then execute idempotently |
| Provider-specific unsupported action | None | Fail closed; never emulate silently |
Session and State Model
A Tess session has stable sessionId, tenantId, ownerId, provider/runtime identity, ingress bindings, cursor, checkpoint, inbox/outbox, and idempotency records. Discord and CLI bind to the same authorized session. Ownership is verified server-side on every list/read/attach/send/terminate operation.
Valkey holds the existing short-lived, one-time command-approval records; PostgreSQL is canonical for durable session bindings, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.
M2 Durable Recovery
@mosaicstack/agent owns a transport-neutral state machine and apps/gateway provides its
PostgreSQL adapter. interaction_sessions holds immutable identity; inbox/outbox records use a
per-session unique idempotency key and transition pending → processing → processed|delivered.
Checkpoints are immutable history scoped by session and checkpoint ID: the latest checkpoint
supports compaction recovery, while a handoff always resolves the exact checkpoint it references.
Recovery requeues only interrupted inbox work; an ambiguous processing outbox record is preserved
until separately authorized reconciliation can establish its external delivery state.
Provider sends travel through the existing RuntimeProviderService with the persisted outbox
idempotency key. A normal dispatch claims exactly one outbox record and verifies its stored
correlation and channel against the server-derived request scope; it never requeues or drains
another live record. Inbox/outbox payloads and checkpoint cursor/summary pass through the existing
secret/PII redactor and AES-256-GCM sealing before persistence; decryption occurs only in the
scoped gateway repository path, and runtime audit remains metadata-only.
An external effect cannot share a database transaction. If a process dies after an effect begins
but before its terminal outbox transition, automatic recovery does not replay that ambiguous claim.
It remains processing until separately authorized reconciliation can establish delivery state;
completed effects are never redispatched. Operators can therefore restart the gateway/Pi service,
reconstruct the session, and resume pending inbox work without relying on process-local state.
Transport Strategy
- Initial: fleet/tmux provider, including exact target, socket, identity, heartbeat, and safe attach semantics.
- Forward: Matrix/native Mosaic provider using authenticated identity, idempotent transaction IDs, replay cursors, and the same contract suite.
- Discord/CLI never call tmux or Matrix directly.
Fleet/tmux Provider Boundary
TmuxFleetRuntimeProvider supports only rostered fleet peers. Its transport resolves the configured roster socket itself and verifies the exact =<agent>:0.0 pane and declared runtime command before every attach, message, or termination operation. Prefixes, unrostered session IDs, unavailable sockets, dead panes, and runtime identity mismatches fail closed; callers cannot supply a socket or raw tmux target.
The provider advertises list, tree, read-only attach, send, and terminate. List/tree/health and read attach all default-deny until a scope-aware read authority permits the operation and exact peer. Attach produces a short-lived handle bound to the immutable actor, tenant, channel, and correlation scope; it never opens a server-side terminal and rejects control mode. Fleet stream support is intentionally absent. Tess has no direct write/control authority: send and terminate default-deny until a Mos authority adapter explicitly allows the exact session and immutable scope. The gateway registry remains the audit boundary for every requested, denied, and successful provider operation, and still consumes the exact-action termination approval before the provider is invoked.
Plugin Families
- Channel: Discord now; other channels later.
- Runtime: Pi, fleet/tmux, Hermes, Matrix/native.
- Operator tools: fleet health, Mos handoff, GitOps wrappers, incident-safe diagnostics.
- Memory/state: search/recent/capture, durable inbox, checkpoint, handoff, compaction recovery.
- Migration: capability inventory, adapters, cutover, rollback, telemetry.
Deployment
Tess runs as a rostered, systemd-supervised Pi agent using GPT-5.6 Sol and high reasoning. Secrets are supplied through approved runtime secret mechanisms. Startup fails when required model, gateway identity, Discord binding, or durable-state dependencies are missing. Health reports effective model/reasoning/tool policy without credential material.
The interaction-service identity is provisioning data, not a source identifier: the roster and per-agent environment carry the chosen display/roster name into a generic systemd instance. The service rejects a name mismatch or any drift from its pinned Pi/GPT-5.6 Sol/high/operator-interaction effective policy before launch. Its policy printer exposes only those resolved safe fields.