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: [] }]