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() and health()
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.

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 may hold ephemeral coordination state; PostgreSQL is canonical for durable session bindings, approvals, audit, checkpoints, inbox/outbox, and idempotency. Pi session files are replay sources, not cross-agent truth.

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.

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.

4.1 KiB Raw Blame History