72 lines
4.7 KiB
Markdown
72 lines
4.7 KiB
Markdown
# 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.
|