From 470eb911c0220982ca5eac9002aa81f3efa2db7b Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 11:00:57 -0500 Subject: [PATCH] docs(#744): add Tess API and operations guides --- docs/openapi-tess.yaml | 126 ++++++++++++++++++++ docs/tess/ADMIN-GUIDE.md | 3 + docs/tess/DEVELOPER-GUIDE.md | 3 + docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md | 8 ++ docs/tess/OPERATIONS-GUIDE.md | 3 + docs/tess/PLUGIN-GUIDE.md | 3 + docs/tess/USER-GUIDE.md | 3 + 7 files changed, 149 insertions(+) create mode 100644 docs/openapi-tess.yaml create mode 100644 docs/tess/ADMIN-GUIDE.md create mode 100644 docs/tess/DEVELOPER-GUIDE.md create mode 100644 docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md create mode 100644 docs/tess/OPERATIONS-GUIDE.md create mode 100644 docs/tess/PLUGIN-GUIDE.md create mode 100644 docs/tess/USER-GUIDE.md diff --git a/docs/openapi-tess.yaml b/docs/openapi-tess.yaml new file mode 100644 index 0000000..f170a33 --- /dev/null +++ b/docs/openapi-tess.yaml @@ -0,0 +1,126 @@ +openapi: 3.1.0 +info: { title: Mosaic Tess Gateway, version: 1.0.0 } +paths: + /api/interaction/{agentName}/sessions: + { + get: + { + summary: List authorized runtime sessions, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/provider' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: + { + '200': { description: Sessions }, + '401': { description: Auth required }, + '403': { description: Scope denied }, + }, + }, + } + /api/interaction/{agentName}/transitional-capabilities: + { + get: + { + summary: Transitional capability matrix, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/provider' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Matrix } }, + }, + } + /api/interaction/{agentName}/tree: + { + get: + { + summary: Authorized session tree, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/provider' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Tree } }, + }, + } + /api/interaction/{agentName}/sessions/{sessionId}/{operation}: + { + post: + { + summary: Enroll, + attach, + send, + stop, + or recover a durable session, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { + name: operation, + in: path, + required: true, + schema: { enum: [enroll, attach, send, stop, recover] }, + }, + { $ref: '#/components/parameters/correlation' }, + ], + requestBody: + { required: false, content: { application/json: { schema: { type: object } } } }, + responses: + { + '200': { description: Operation result }, + '403': { description: Scope or approval denied }, + }, + }, + } + /api/coord/mos/handoff: + { + post: + { + summary: Submit a Mos handoff, + parameters: [{ $ref: '#/components/parameters/correlation' }], + responses: { '200': { description: Receipt } }, + }, + } + /api/coord/mos/{handoffId}/observe: + { + get: + { + summary: Observe a handoff, + parameters: + [ + { $ref: '#/components/parameters/handoffId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Observation } }, + }, + } + /api/coord/mos/{handoffId}/result: + { + get: + { + summary: Get a handoff result, + parameters: + [ + { $ref: '#/components/parameters/handoffId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Result } }, + }, + } + /api/memory/search: + { post: { summary: Search scoped memory, responses: { '200': { description: Results } } } } +components: + securitySchemes: { sessionAuth: { type: http, scheme: bearer } } + parameters: + agentName: { name: agentName, in: path, required: true, schema: { type: string } } + sessionId: { name: sessionId, in: path, required: true, schema: { type: string } } + handoffId: { name: handoffId, in: path, required: true, schema: { type: string } } + provider: { name: provider, in: query, required: true, schema: { type: string } } + correlation: { name: X-Correlation-Id, in: header, required: true, schema: { type: string } } +security: [{ sessionAuth: [] }] diff --git a/docs/tess/ADMIN-GUIDE.md b/docs/tess/ADMIN-GUIDE.md new file mode 100644 index 0000000..2bc7b68 --- /dev/null +++ b/docs/tess/ADMIN-GUIDE.md @@ -0,0 +1,3 @@ +# Tess Administration + +Provision authenticated users, configured agent identities, providers, and approved channel bindings. Never expose service credentials in status or logs. Use health/readiness and provider status endpoints for recovery diagnostics; privileged termination remains approval-bound and auditable. diff --git a/docs/tess/DEVELOPER-GUIDE.md b/docs/tess/DEVELOPER-GUIDE.md new file mode 100644 index 0000000..dfd534a --- /dev/null +++ b/docs/tess/DEVELOPER-GUIDE.md @@ -0,0 +1,3 @@ +# Tess Developer Guide + +Interaction adapters pass only server-derived actor/tenant scope, channel, and correlation to runtime providers. Durable session state owns inbox/outbox/checkpoint recovery. Use the OpenAPI contract rather than inventing routes; unsupported provider capabilities fail closed. diff --git a/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md b/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md new file mode 100644 index 0000000..336900b --- /dev/null +++ b/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md @@ -0,0 +1,8 @@ +# TESS-M5-003 Documentation Checklist + +- [x] `openapi-tess.yaml`: authenticated interaction endpoints, Mos handoff/observe/result, memory search. +- [x] User guide: authorized session and handoff workflows. +- [x] Admin guide: provisioning, policy, health, and approval boundary. +- [x] Developer guide: scope, durable state, and provider adapter contract. +- [x] Plugin guide: replaceable-adapter, redaction, and identity-as-data rules. +- [x] Operations guide: readiness, recovery, ambiguous-effect safety, and tracing. diff --git a/docs/tess/OPERATIONS-GUIDE.md b/docs/tess/OPERATIONS-GUIDE.md new file mode 100644 index 0000000..e0a262e --- /dev/null +++ b/docs/tess/OPERATIONS-GUIDE.md @@ -0,0 +1,3 @@ +# Tess Operations and Recovery + +Check `/health/ready`, provider health, and effective policy before recovery. Recover durable sessions through the interaction recovery operation; it requeues only interrupted work and does not replay ambiguous external effects. Preserve correlation IDs for incident tracing and use Mos handoff observation/result endpoints for orchestration visibility. diff --git a/docs/tess/PLUGIN-GUIDE.md b/docs/tess/PLUGIN-GUIDE.md new file mode 100644 index 0000000..4d40348 --- /dev/null +++ b/docs/tess/PLUGIN-GUIDE.md @@ -0,0 +1,3 @@ +# Tess Plugin Authoring + +Plugins are replaceable adapters. Declare capabilities, derive scope from trusted context, preserve correlation IDs, redact before persistence/egress, and return unsupported operations as fail-closed results. Names and identities are configuration data, not literals in keys or defaults. diff --git a/docs/tess/USER-GUIDE.md b/docs/tess/USER-GUIDE.md new file mode 100644 index 0000000..62f8c7d --- /dev/null +++ b/docs/tess/USER-GUIDE.md @@ -0,0 +1,3 @@ +# Tess User Guide + +Use authenticated interaction endpoints with an `X-Correlation-Id`. List sessions, attach, send, and recover only sessions visible to your server-derived tenant scope. Stop requires a durable exact-action approval. Mos handoffs are submitted through `/api/coord/mos/handoff` and can be observed or read by receipt ID.