openapi: 3.1.0
info: { title: Mosaic Tess Gateway, version: 1.0.0 }
security: [{ sessionAuth: [] }]
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 } },
        },
    }
  /api/interaction/{agentName}/transitional-capabilities:
    {
      get:
        {
          summary: Get 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: Get 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}/enroll:
    {
      post:
        {
          summary: Enroll a durable session,
          parameters:
            [
              { $ref: '#/components/parameters/agentName' },
              { $ref: '#/components/parameters/sessionId' },
              { $ref: '#/components/parameters/correlation' },
            ],
          requestBody: { $ref: '#/components/requestBodies/Enroll' },
          responses: { '200': { description: Enrolled } },
        },
    }
  /api/interaction/{agentName}/sessions/{sessionId}/attach:
    {
      post:
        {
          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/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/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 } } },
      post:
        {
          summary: Upsert preference,
          requestBody: { $ref: '#/components/requestBodies/Preference' },
          responses: { '200': { description: Preference } },
        },
    }
  /api/memory/preferences/{key}:
    {
      get:
        {
          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/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 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 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 } }
    provider: { name: provider, in: query, required: true, schema: { type: string } }
    correlation: { name: X-Correlation-Id, in: header, required: true, schema: { type: string } }
    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 },
                      },
                  },
              },
          },
      }