# 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

```text
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

1. Channel: Discord now; other channels later.
2. Runtime: Pi, fleet/tmux, Hermes, Matrix/native.
3. Operator tools: fleet health, Mos handoff, GitOps wrappers, incident-safe diagnostics.
4. Memory/state: search/recent/capture, durable inbox, checkpoint, handoff, compaction recovery.
5. 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.