docs(#744): add Tess API and operations guides

2026-07-13 11:00:57 -05:00
parent 6345dbfcf2
commit 470eb911c0
7 changed files with 149 additions and 0 deletions
--- a/docs/openapi-tess.yaml
+++ 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: [] }]