From 470eb911c0220982ca5eac9002aa81f3efa2db7b Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 11:00:57 -0500 Subject: [PATCH 1/4] 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. -- 2.49.1 From c9f69300a367c62dba544e5d4be409b53f2dbcab Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 11:30:26 -0500 Subject: [PATCH 2/4] docs(#744): complete Tess API contracts --- docs/openapi-tess.yaml | 276 ++++++++++++++++++++++++++++++++------- docs/tess/ADMIN-GUIDE.md | 4 +- docs/tess/USER-GUIDE.md | 4 +- 3 files changed, 232 insertions(+), 52 deletions(-) diff --git a/docs/openapi-tess.yaml b/docs/openapi-tess.yaml index f170a33..29616d8 100644 --- a/docs/openapi-tess.yaml +++ b/docs/openapi-tess.yaml @@ -1,5 +1,6 @@ openapi: 3.1.0 info: { title: Mosaic Tess Gateway, version: 1.0.0 } +security: [{ sessionAuth: [] }] paths: /api/interaction/{agentName}/sessions: { @@ -12,19 +13,14 @@ paths: { $ref: '#/components/parameters/provider' }, { $ref: '#/components/parameters/correlation' }, ], - responses: - { - '200': { description: Sessions }, - '401': { description: Auth required }, - '403': { description: Scope denied }, - }, + responses: { '200': { description: Sessions } }, }, } /api/interaction/{agentName}/transitional-capabilities: { get: { - summary: Transitional capability matrix, + summary: Get transitional capability matrix, parameters: [ { $ref: '#/components/parameters/agentName' }, @@ -38,7 +34,7 @@ paths: { get: { - summary: Authorized session tree, + summary: Get authorized session tree, parameters: [ { $ref: '#/components/parameters/agentName' }, @@ -48,79 +44,259 @@ paths: responses: { '200': { description: Tree } }, }, } - /api/interaction/{agentName}/sessions/{sessionId}/{operation}: + /api/interaction/{agentName}/sessions/{sessionId}/enroll: { post: { - summary: Enroll, - attach, - send, - stop, - or recover a durable session, + summary: Enroll 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 }, - }, + requestBody: { $ref: '#/components/requestBodies/Enroll' }, + responses: { '200': { description: Enrolled } }, }, } - /api/coord/mos/handoff: + /api/interaction/{agentName}/sessions/{sessionId}/attach: { post: { - summary: Submit a Mos handoff, - parameters: [{ $ref: '#/components/parameters/correlation' }], - responses: { '200': { description: Receipt } }, + summary: Attach to a runtime session, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { $ref: '#/components/parameters/correlation' }, + ], + requestBody: { $ref: '#/components/requestBodies/Attach' }, + responses: { '200': { description: Attachment } }, }, } - /api/coord/mos/{handoffId}/observe: + /api/interaction/{agentName}/sessions/{sessionId}/send: + { + post: + { + summary: Queue a durable provider send, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { $ref: '#/components/parameters/correlation' }, + ], + requestBody: { $ref: '#/components/requestBodies/Send' }, + responses: { '200': { description: Queued } }, + }, + } + /api/interaction/{agentName}/sessions/{sessionId}/stop: + { + post: + { + summary: Stop a session with approval, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { $ref: '#/components/parameters/correlation' }, + ], + requestBody: { $ref: '#/components/requestBodies/Stop' }, + responses: { '200': { description: Stopped }, '403': { description: Approval denied } }, + }, + } + /api/interaction/{agentName}/sessions/{sessionId}/recover: + { + post: + { + summary: Recover interrupted durable work, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Recovered } }, + }, + } + /api/memory/preferences: + { + get: { summary: List preferences, responses: { '200': { description: Preferences } } }, + post: + { + summary: Upsert preference, + requestBody: { $ref: '#/components/requestBodies/Preference' }, + responses: { '200': { description: Preference } }, + }, + } + /api/memory/preferences/{key}: { get: { - summary: Observe a handoff, - parameters: - [ - { $ref: '#/components/parameters/handoffId' }, - { $ref: '#/components/parameters/correlation' }, - ], - responses: { '200': { description: Observation } }, + summary: Get preference, + parameters: [{ $ref: '#/components/parameters/key' }], + responses: { '200': { description: Preference } }, + }, + delete: + { + summary: Delete preference, + parameters: [{ $ref: '#/components/parameters/key' }], + responses: { '204': { description: Deleted } }, }, } - /api/coord/mos/{handoffId}/result: + /api/memory/insights: + { + get: { summary: List insights, responses: { '200': { description: Insights } } }, + post: + { + summary: Create insight, + requestBody: { $ref: '#/components/requestBodies/Insight' }, + responses: { '200': { description: Insight } }, + }, + } + /api/memory/insights/{id}: { get: { - summary: Get a handoff result, - parameters: - [ - { $ref: '#/components/parameters/handoffId' }, - { $ref: '#/components/parameters/correlation' }, - ], - responses: { '200': { description: Result } }, + summary: Get insight, + parameters: [{ $ref: '#/components/parameters/id' }], + responses: { '200': { description: Insight } }, + }, + delete: + { + summary: Delete insight, + parameters: [{ $ref: '#/components/parameters/id' }], + responses: { '204': { description: Deleted } }, }, } /api/memory/search: - { post: { summary: Search scoped memory, responses: { '200': { description: Results } } } } + { + post: + { + summary: Search memory, + requestBody: { $ref: '#/components/requestBodies/Search' }, + responses: { '200': { description: Search 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: [] }] + key: { name: key, in: path, required: true, schema: { type: string } } + id: { name: id, in: path, required: true, schema: { type: string } } + requestBodies: + Enroll: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + required: [providerId, runtimeSessionId], + properties: + { providerId: { type: string }, runtimeSessionId: { type: string } }, + }, + }, + }, + } + Attach: + { + content: + { + application/json: { schema: { type: object, properties: { mode: { enum: [read] } } } }, + }, + } + Send: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + properties: { content: { type: string }, idempotencyKey: { type: string } }, + }, + }, + }, + } + Stop: + { + required: true, + content: + { + application/json: + { schema: { type: object, properties: { approvalRef: { type: string } } } }, + }, + } + Preference: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + required: [key, value], + properties: + { + key: { type: string }, + value: {}, + category: { type: string }, + source: { type: string }, + }, + }, + }, + }, + } + Insight: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + required: [content, source, category], + properties: + { + content: { type: string }, + source: { type: string }, + category: { type: string }, + metadata: { type: object }, + }, + }, + }, + }, + } + Search: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + required: [query], + properties: + { + query: { type: string }, + limit: { type: integer }, + maxDistance: { type: number }, + }, + }, + }, + }, + } diff --git a/docs/tess/ADMIN-GUIDE.md b/docs/tess/ADMIN-GUIDE.md index 2bc7b68..03b78c3 100644 --- a/docs/tess/ADMIN-GUIDE.md +++ b/docs/tess/ADMIN-GUIDE.md @@ -1,3 +1,5 @@ # 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. +Configure agent/provider identities outside client input. Verify `/health/ready` and provider health before enabling interaction clients. Every interaction request requires an authenticated actor and correlation header; tenant and owner scope are server-derived. Do not log or return service credentials. + +For an incident, preserve correlation IDs, inspect provider status and durable checkpoint/inbox/outbox state, then use the recovery endpoint. Do not retry an ambiguous external effect automatically. Stop operations require an exact one-time approval reference; provisioning or granting a broad admin capability does not replace that check. diff --git a/docs/tess/USER-GUIDE.md b/docs/tess/USER-GUIDE.md index 62f8c7d..90a85f1 100644 --- a/docs/tess/USER-GUIDE.md +++ b/docs/tess/USER-GUIDE.md @@ -1,3 +1,5 @@ # 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. +All HTTP interaction calls require authenticated session credentials and `X-Correlation-Id`. Use `GET /api/interaction/{agentName}/sessions?provider=...` to list only visible runtime sessions, then enroll with `POST .../sessions/{sessionId}/enroll` body `{providerId,runtimeSessionId}`. Attach uses `{mode:"read"}`; send uses `{content,idempotencyKey}`. Stop requires `{approvalRef}` and fails with 403 without the exact durable approval. Recovery only requeues interrupted durable work. + +Memory is user-scoped: preferences support list/get/upsert/delete; insights support list/get/create/delete; search body is `{query,limit?,maxDistance?}`. Mos work is handed off with `POST /api/coord/mos/handoff`; observe and result use the returned handoff ID. -- 2.49.1 From 7aea94e27498033a8f69a1f17c9dfe2fe83da9fc Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 12:00:27 -0500 Subject: [PATCH 3/4] docs(#744): complete Tess API coverage --- docs/openapi-tess.yaml | 56 +++++++++++++++++++++ docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md | 2 +- 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/openapi-tess.yaml b/docs/openapi-tess.yaml index 29616d8..4a3241a 100644 --- a/docs/openapi-tess.yaml +++ b/docs/openapi-tess.yaml @@ -118,6 +118,62 @@ paths: responses: { '200': { description: Recovered } }, }, } + /api/coord/mos/handoff: + { + post: + { + summary: Submit Mos handoff, + parameters: [{ $ref: '#/components/parameters/correlation' }], + responses: { '200': { description: Receipt } }, + }, + } + /api/coord/mos/{handoffId}/observe: + { + get: + { + summary: Observe Mos handoff, + parameters: + [ + { $ref: '#/components/parameters/handoffId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Observation } }, + }, + } + /api/coord/mos/{handoffId}/result: + { + get: + { + summary: Get Mos handoff result, + parameters: + [ + { $ref: '#/components/parameters/handoffId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: { '200': { description: Result } }, + }, + } + /api/interaction/{agentName}/sessions/{sessionId}/stream: + { + get: + { + summary: Stream runtime events, + parameters: + [ + { $ref: '#/components/parameters/agentName' }, + { $ref: '#/components/parameters/sessionId' }, + { $ref: '#/components/parameters/correlation' }, + ], + responses: + { + '200': + { + description: Event stream, + content: { text/event-stream: { schema: { type: string } } }, + }, + }, + }, + } /api/memory/preferences: { get: { summary: List preferences, responses: { '200': { description: Preferences } } }, diff --git a/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md b/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md index 336900b..5622d0a 100644 --- a/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md +++ b/docs/tess/M5-003-DOCUMENTATION-CHECKLIST.md @@ -1,6 +1,6 @@ # TESS-M5-003 Documentation Checklist -- [x] `openapi-tess.yaml`: authenticated interaction endpoints, Mos handoff/observe/result, memory search. +- [x] `openapi-tess.yaml`: authenticated interaction endpoints including SSE stream, Mos handoff/observe/result, and memory preferences, insights, and 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. -- 2.49.1 From 25b9d642b939014b3efd61826e7524cafc6ffc2e Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 13 Jul 2026 12:15:07 -0500 Subject: [PATCH 4/4] docs(#744): align Tess request schemas --- docs/openapi-tess.yaml | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/openapi-tess.yaml b/docs/openapi-tess.yaml index 4a3241a..c348a69 100644 --- a/docs/openapi-tess.yaml +++ b/docs/openapi-tess.yaml @@ -124,6 +124,7 @@ paths: { summary: Submit Mos handoff, parameters: [{ $ref: '#/components/parameters/correlation' }], + requestBody: { $ref: '#/components/requestBodies/MosHandoff' }, responses: { '200': { description: Receipt } }, }, } @@ -260,6 +261,28 @@ components: }, }, } + MosHandoff: + { + required: true, + content: + { + application/json: + { + schema: + { + type: object, + required: [idempotencyKey, summary], + properties: + { + idempotencyKey: { type: string }, + summary: { type: string }, + context: { type: string }, + missionId: { type: string }, + }, + }, + }, + }, + } Attach: { content: @@ -277,6 +300,7 @@ components: schema: { type: object, + required: [content, idempotencyKey], properties: { content: { type: string }, idempotencyKey: { type: string } }, }, }, @@ -288,7 +312,14 @@ components: content: { application/json: - { schema: { type: object, properties: { approvalRef: { type: string } } } }, + { + schema: + { + type: object, + required: [approvalRef], + properties: { approvalRef: { type: string } }, + }, + }, }, } Preference: @@ -323,7 +354,7 @@ components: schema: { type: object, - required: [content, source, category], + required: [content], properties: { content: { type: string }, -- 2.49.1