openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: Atlas Sessions API
  version: 1.0.0-target
  summary: Remote stateful chat, conversation, artifact, and durable-agent surface.
  description: |
    Normative target contract for the complete remote Atlas chat surface. It is
    intentionally implementation-pending: it describes the public API to be
    served at the API hostname, not the browser-only or loopback implementation.
    All identifiers and timestamps are server generated. A principal can access
    only resources it owns; an inaccessible resource is reported as not_found.
    Direct connection, OAuth, workflow, automation, and routine-administration
    endpoints are deliberately outside this contract.
  license:
    name: Proprietary
servers:
  - url: https://api.trentsoftware.in
    description: Production API
x-atlas-contract-status: implementation-pending
x-atlas-target-changes:
  - The listed browser/session routes become a remote API only when the public edge enforces both Basic authentication and X-Atlas-API-Key.
  - The public surface is limited to the paths in this document; connection, OAuth, workflow, automation, and routine-administration routes remain private or absent.
  - Session admission, durable conversation snapshots, artifacts, interaction controls, and durable agent-run controls retain their existing field names while gaining this stable OpenAPI contract.
  - SSE remains replayable by sequence and exposes only the closed event union below; implementation-specific transport diagnostics and credentials are never events.
security:
  - BasicAuth: []
    AtlasApiKey: []
tags:
  - name: sessions
  - name: conversations
  - name: artifacts
  - name: agent-runs
paths:
  /v1/sessions:
    post:
      tags: [sessions]
      operationId: createOrResumeSession
      summary: Create a session or resume an owned conversation.
      description: |
        Without conversationId, creates a new durable conversation and returns
        its admission snapshot. With conversationId, resumes that owned
        conversation. The API does not disclose whether a supplied foreign or
        deleted conversation existed; a new conversation is admitted instead.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            examples:
              newChat:
                value: { mode: chat }
              resume:
                value: { conversationId: '00000000-0000-4000-8000-000000000001' }
      responses:
        '201':
          description: Session admission snapshot.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SessionSnapshot' }
              examples:
                admitted:
                  value:
                    sessionId: '00000000-0000-4000-8000-000000000001'
                    mode: chat
                    runtimeReady: false
                    lastSequence: 0
                    toolNames: []
                    connectors: []
                    artifacts: []
                    messages: []
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '415': { $ref: '#/components/responses/UnsupportedMediaType' }
        '429': { $ref: '#/components/responses/CapacityUnavailable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /v1/sessions/{sessionId}:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    get:
      tags: [sessions]
      operationId: getSession
      summary: Get the current session snapshot.
      responses:
        '200':
          description: Current snapshot.
          content: { application/json: { schema: { $ref: '#/components/schemas/SessionSnapshot' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [sessions]
      operationId: deleteSession
      summary: Close the live session runtime.
      description: Closes only the live runtime. The durable conversation remains available through Conversations.
      responses:
        '204': { description: Runtime closed or already absent. }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/sessions/{sessionId}/runs:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    post:
      tags: [sessions]
      operationId: startSessionRun
      summary: Start a chat turn or steer the active durable chat run.
      description: |
        Idempotency-Key is required. Repeating the same key and request returns
        the original run with reused true. Reusing a key for different content
        is a conflict. An active durable run treats a new message as steering.
      parameters: [ { $ref: '#/components/parameters/IdempotencyKey' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StartRunRequest' }
            examples:
              prompt: { value: { message: 'Summarize my active work.' } }
      responses:
        '202':
          description: Run accepted.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RunAccepted' }
              examples:
                new: { value: { runId: '00000000-0000-4000-8000-000000000002', reused: false } }
                replay: { value: { runId: '00000000-0000-4000-8000-000000000002', reused: true } }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '400': { $ref: '#/components/responses/InvalidRunRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '429': { $ref: '#/components/responses/CapacityUnavailable' }
        '503': { $ref: '#/components/responses/ServiceUnavailable' }
  /v1/sessions/{sessionId}/steer:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    post:
      tags: [sessions]
      operationId: steerSessionRun
      summary: Queue a steering message during an active run.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/SessionMessageRequest" }, example: { message: "Prioritize the open risks." } } }
      responses:
        '202': { $ref: '#/components/responses/Accepted' }
        '400': { $ref: '#/components/responses/InvalidMessage' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/SessionIdle' }
        '429': { $ref: '#/components/responses/CapacityUnavailable' }
  /v1/sessions/{sessionId}/follow-ups:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    post:
      tags: [sessions]
      operationId: queueSessionFollowUp
      summary: Queue a follow-up message during an active run.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/SessionMessageRequest" }, example: { message: "Add the latest metrics." } } }
      responses:
        '202': { $ref: '#/components/responses/Accepted' }
        '400': { $ref: '#/components/responses/InvalidMessage' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/SessionIdle' }
        '429': { $ref: '#/components/responses/CapacityUnavailable' }
  /v1/sessions/{sessionId}/abort:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    post:
      tags: [sessions]
      operationId: abortSessionRun
      summary: Request cancellation of the active chat run.
      responses:
        '202': { $ref: '#/components/responses/Accepted' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/events:
    parameters:
      - { $ref: '#/components/parameters/SessionId' }
      - name: after
        in: query
        description: Replay events with a sequence greater than this cursor. Last-Event-ID is used when omitted.
        schema: { type: integer, minimum: 0, maximum: 9007199254740991 }
    get:
      tags: [sessions]
      operationId: streamSessionEvents
      summary: Replay and subscribe to session events.
      description: |
        A replay gap is represented by a session.snapshot event, whose sequence is
        the snapshot lastSequence. Event ids equal sequence. The stream is
        long-lived and may include SSE comments as keep-alives; comments carry no data.
      responses:
        '200':
          description: SSE stream. Each data field is one SessionEvent JSON object.
          content:
            text/event-stream:
              schema: { $ref: '#/components/schemas/SessionEvent' }
              examples:
                assistant:
                  value:
                    sessionId: '00000000-0000-4000-8000-000000000001'
                    runId: '00000000-0000-4000-8000-000000000002'
                    sequence: 12
                    timestamp: '2026-08-09T12:00:00.000Z'
                    type: assistant.updated
                    payload: { text: 'Working on it.', reasoning: '', reasoningVisibility: summary }
        '400': { $ref: '#/components/responses/InvalidEventCursor' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/SubscriberCapacityUnavailable' }
  /v1/sessions/{sessionId}/interactions/{interactionId}/responses:
    parameters:
      - { $ref: '#/components/parameters/SessionId' }
      - { $ref: '#/components/parameters/InteractionId' }
    post:
      tags: [sessions]
      operationId: respondToSessionInteraction
      summary: Answer or cancel a requested interaction.
      description: The interaction request and public question/option ids are delivered through interaction.requested SSE events.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/InteractionResponse" }, example: { type: user_interaction_response, id: "00000000-0000-4000-8000-000000000003", status: answered, answers: [ { questionId: question_1, value: option_1, label: "Yes", custom: false } ] } } }
      responses:
        '202': { $ref: '#/components/responses/Accepted' }
        '400': { $ref: '#/components/responses/InvalidInteractionResponse' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/crons:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    get:
      tags: [sessions]
      operationId: listSessionCrons
      summary: List current session-scoped schedules.
      responses:
        '200':
          description: Session-scoped cron summaries only.
          content: { application/json: { schema: { $ref: '#/components/schemas/SessionCronList' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/crons/{cronId}:
    parameters:
      - { $ref: '#/components/parameters/SessionId' }
      - { $ref: '#/components/parameters/CronId' }
    delete:
      tags: [sessions]
      operationId: deleteSessionCron
      summary: Delete a current session-scoped schedule.
      responses:
        '204': { description: Schedule deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/artifacts:
    parameters: [ { $ref: '#/components/parameters/SessionId' } ]
    get:
      tags: [artifacts]
      operationId: listSessionArtifacts
      summary: List explicitly presented generated artifacts.
      responses:
        '200':
          description: Presented generated artifacts only; internal artifacts and uploads are never exposed.
          content: { application/json: { schema: { $ref: '#/components/schemas/ArtifactList' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/artifacts/{artifactId}:
    parameters:
      - { $ref: '#/components/parameters/SessionId' }
      - { $ref: '#/components/parameters/ArtifactId' }
    delete:
      tags: [artifacts]
      operationId: deleteSessionArtifact
      summary: Delete a presented artifact.
      responses:
        '204': { description: Artifact deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/sessions/{sessionId}/artifacts/{artifactId}/content:
    parameters:
      - { $ref: '#/components/parameters/SessionId' }
      - { $ref: '#/components/parameters/ArtifactId' }
    get:
      tags: [artifacts]
      operationId: downloadSessionArtifact
      summary: Download a presented generated artifact.
      responses:
        '200':
          description: Binary artifact bytes. Content-Type is the artifact mimeType and Content-Disposition is attachment.
          headers:
            ETag: { schema: { type: string, pattern: '^"[a-f0-9]{64}"$' } }
            Content-Disposition: { schema: { type: string } }
          content:
            application/octet-stream: { schema: { type: string, contentEncoding: base64 } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/conversations:
    get:
      tags: [conversations]
      operationId: listConversations
      summary: List retained conversations for the principal.
      responses:
        '200':
          description: At most 200 summaries, ordered newest first.
          content: { application/json: { schema: { $ref: '#/components/schemas/ConversationList' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/conversations/{conversationId}:
    parameters: [ { $ref: '#/components/parameters/ConversationId' } ]
    get:
      tags: [conversations]
      operationId: getConversation
      summary: Get a durable conversation snapshot without activating a runtime.
      responses:
        '200':
          description: Durable snapshot.
          content: { application/json: { schema: { $ref: '#/components/schemas/ConversationSnapshot' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [conversations]
      operationId: renameConversation
      summary: Rename an owned conversation.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/RenameConversationRequest" }, example: { title: "Q3 planning" } } }
      responses:
        '200':
          description: Updated summary.
          content: { application/json: { schema: { $ref: '#/components/schemas/ConversationEnvelope' } } }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [conversations]
      operationId: deleteConversation
      summary: Permanently delete a durable conversation and scoped artifacts.
      description: Rejected while the conversation has an active run or linked durable routine.
      responses:
        '204': { description: Conversation and scoped artifacts deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/ConversationBusy' }
  /v1/agent-runs:
    get:
      tags: [agent-runs]
      operationId: listAgentRuns
      summary: List principal-owned durable agent runs.
      responses:
        '200':
          description: Runs ordered newest first.
          content: { application/json: { schema: { $ref: '#/components/schemas/AgentRunList' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    get:
      tags: [agent-runs]
      operationId: getAgentRun
      summary: Get a durable run and current wait or input request.
      responses:
        '200':
          description: Durable run state.
          content: { application/json: { schema: { $ref: '#/components/schemas/AgentRunDetail' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}/audit:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    get:
      tags: [agent-runs]
      operationId: listAgentRunAudit
      summary: Read the hash-chained audit record for a run.
      responses:
        '200':
          description: Audit events in ascending id order.
          content: { application/json: { schema: { $ref: '#/components/schemas/AuditEventList' } } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}/pause:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    post:
      tags: [agent-runs]
      operationId: pauseAgentRun
      summary: Request a durable pause.
      responses:
        '202': { $ref: '#/components/responses/RunAcceptedResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}/resume:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    post:
      tags: [agent-runs]
      operationId: resumeAgentRun
      summary: Resume a paused durable run.
      responses:
        '200': { $ref: '#/components/responses/RunAcceptedResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}/cancel:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    post:
      tags: [agent-runs]
      operationId: cancelAgentRun
      summary: Request durable cancellation.
      responses:
        '202': { $ref: '#/components/responses/RunAcceptedResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-runs/{runId}/retry:
    parameters: [ { $ref: '#/components/parameters/RunId' } ]
    post:
      tags: [agent-runs]
      operationId: retryAgentRun
      summary: Retry a failed or cancelled durable run.
      description: outcome_unknown runs cannot be retried until reconciliation proves the mutation outcome.
      responses:
        '200': { $ref: '#/components/responses/RunAcceptedResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/RetryConflict' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-run-waits/{waitId}/resolve:
    parameters: [ { $ref: '#/components/parameters/WaitId' } ]
    post:
      tags: [agent-runs]
      operationId: resolveAgentRunWait
      summary: Resolve an owned external durable wait.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/SessionJsonObject" }, example: { result: "confirmed" } } }
      responses:
        '200':
          description: Resolved wait.
          content: { application/json: { schema: { $ref: '#/components/schemas/WaitEnvelope' } } }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-run-approvals/{approvalId}/approve:
    parameters: [ { $ref: '#/components/parameters/ApprovalId' } ]
    post:
      tags: [agent-runs]
      operationId: approveAgentRunApproval
      summary: Approve an owned durable approval request.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/SessionJsonObject" }, example: { result: "confirmed" } } }
      responses:
        '200': { $ref: '#/components/responses/ApprovalResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
  /v1/agent-run-approvals/{approvalId}/reject:
    parameters: [ { $ref: '#/components/parameters/ApprovalId' } ]
    post:
      tags: [agent-runs]
      operationId: rejectAgentRunApproval
      summary: Reject an owned durable approval request.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/SessionJsonObject" }, example: { result: "confirmed" } } }
      responses:
        '200': { $ref: '#/components/responses/ApprovalResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '415': { $ref: "#/components/responses/UnsupportedMediaType" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '503': { $ref: '#/components/responses/DurableRunsUnavailable' }
components:
  securitySchemes:
    BasicAuth: { type: http, scheme: basic }
    AtlasApiKey: { type: apiKey, in: header, name: X-Atlas-API-Key }
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, pattern: '^[A-Za-z0-9_-]{1,128}$' }
      example: chat_turn_0001
    SessionId: { name: sessionId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    ConversationId: { name: conversationId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    RunId: { name: runId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    WaitId: { name: waitId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    ApprovalId: { name: approvalId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    InteractionId: { name: interactionId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    CronId: { name: cronId, in: path, required: true, schema: { $ref: '#/components/schemas/Uuid' } }
    ArtifactId:
      name: artifactId
      in: path
      required: true
      schema: { type: string, pattern: '^artifact_[0-9a-f-]{36}$', maxLength: 45 }
  responses:
    Accepted:
      description: Request accepted.
      content: { application/json: { schema: { $ref: '#/components/schemas/Accepted' }, example: { accepted: true } } }
    RunAcceptedResponse:
      description: Updated durable run.
      content: { application/json: { schema: { $ref: '#/components/schemas/RunEnvelope' } } }
    ApprovalResponse:
      description: Updated durable approval.
      content: { application/json: { schema: { $ref: '#/components/schemas/ApprovalEnvelope' } } }
    InvalidRequest: { description: Invalid request, JSON, or query parameters., content: { application/json: { schema: { $ref: "#/components/schemas/ErrorInvalidRequest" }, example: { error: invalid_request } } } }
    InvalidRunRequest: { description: Invalid run request or idempotency key., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorInvalidRunRequest' } } } }
    InvalidMessage: { description: Invalid bounded message., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorInvalidMessage' } } } }
    InvalidInteractionResponse: { description: Interaction is malformed, unknown, stale, or already settled., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorInvalidInteraction' } } } }
    InvalidEventCursor: { description: Event cursor is invalid., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorInvalidCursor' } } } }
    Unauthorized: { description: Authentication failed., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorUnauthorized' } } } }
    NotFound: { description: Resource is absent or not owned by the principal., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorNotFound' } } } }
    Conflict: { description: Conflicting idempotency key or busy session., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorConflict' } } } }
    RetryConflict: { description: The run cannot safely be retried., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorRetryConflict' } } } }
    SessionIdle: { description: No active run accepts a queue operation., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorSessionIdle' } } } }
    ConversationBusy: { description: Conversation has an active run or linked durable routine., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorConversationBusy' } } } }
    CapacityUnavailable: { description: A bounded queue or admission capacity is full., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorCapacity' } } } }
    SubscriberCapacityUnavailable: { description: The session has the maximum number of event subscribers., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorSubscriberCapacity' } } } }
    DurableRunsUnavailable: { description: Durable run storage is unavailable., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorDurableUnavailable' } } } }
    ServiceUnavailable: { description: A required server dependency is unavailable., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorServiceUnavailable' } } } }
    UnsupportedMediaType: { description: Content-Type must be application/json., content: { application/json: { schema: { $ref: '#/components/schemas/ErrorUnsupportedMediaType' } } } }
  schemas:
    Uuid: { type: string, format: uuid, pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' }
    Timestamp: { type: string, format: date-time }
    Sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
    SessionText: { type: string, minLength: 1, maxLength: 8000, pattern: '^[^\\u0000-\\u001f\\u007f]*$' }
    BoundedJsonValue:
      description: >-
        Bounded JSON emitted by Atlas in a tool_use input. Object members are
        intentionally open only inside this server-emitted replay payload.
      oneOf:
        - type: "null"
        - type: boolean
        - type: number
        - type: string
          maxLength: 32768
        - type: array
          maxItems: 64
          items:
            $ref: "#/components/schemas/BoundedJsonValue"
        - type: object
          maxProperties: 64
          additionalProperties:
            $ref: "#/components/schemas/BoundedJsonValue"
      x-atlas-max-json-depth: 16
      x-atlas-max-utf8-bytes: 65536
    SessionJsonObject:
      type: object
      maxProperties: 64
      additionalProperties:
        $ref: "#/components/schemas/BoundedJsonValue"
    CreateSessionRequest:
      type: object
      additionalProperties: false
      properties:
        conversationId: { $ref: '#/components/schemas/Uuid' }
        mode: { type: string, enum: [chat, workflow_authoring, workflow_execute] }
    SessionMessageRequest:
      type: object
      additionalProperties: false
      required: [message]
      properties: { message: { $ref: '#/components/schemas/SessionText' } }
    StartRunRequest:
      type: object
      additionalProperties: false
      required: [message]
      properties:
        message: { $ref: '#/components/schemas/SessionText' }
        evaluation: { $ref: '#/components/schemas/SessionJsonObject' }
    Accepted:
      type: object
      additionalProperties: false
      required: [accepted]
      properties: { accepted: { const: true } }
    RunAccepted:
      type: object
      additionalProperties: false
      required: [runId, reused]
      properties: { runId: { $ref: '#/components/schemas/Uuid' }, reused: { type: boolean } }
    ConversationMessage:
      type: object
      additionalProperties: false
      required: [sequence, role, text, createdAt, metadata]
      properties:
        sequence: { type: integer, minimum: 1, maximum: 9007199254740991 }
        role: { type: string, enum: [user, assistant] }
        text: { type: string, maxLength: 32000 }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        metadata:
          type: object
          additionalProperties: false
          properties:
            routineId: { $ref: '#/components/schemas/Uuid' }
            runId: { $ref: '#/components/schemas/Uuid' }
            name: { type: string, maxLength: 200 }
            state: { type: string, maxLength: 80 }
            artifacts: { type: array, maxItems: 32, items: { $ref: '#/components/schemas/ArtifactManifest' } }
            reasoning: { type: string, maxLength: 32000 }
            reasoningVisibility: { type: string, enum: [none, summary, full] }
    ConnectorStatus:
      type: object
      additionalProperties: false
      required: [name, state]
      properties:
        name: { type: string, minLength: 1, maxLength: 100 }
        state: { type: string, enum: [ready, degraded, unavailable] }
        version: { type: string, maxLength: 200 }
        error: { type: string, maxLength: 2000 }
        tools: { type: integer, minimum: 0, maximum: 2048 }
    SessionSnapshot:
      type: object
      additionalProperties: false
      required: [sessionId, organizationId, principalId, lastSequence, toolNames, connectors, artifacts, messages]
      properties:
        sessionId: { $ref: '#/components/schemas/Uuid' }
        mode: { type: string, enum: [chat, workflow_authoring, workflow_execute] }
        organizationId: { type: string, minLength: 1, maxLength: 200 }
        principalId: { type: string, minLength: 1, maxLength: 200 }
        runtimeReady: { type: boolean }
        activeRunId: { $ref: '#/components/schemas/Uuid' }
        lastSequence: { type: integer, minimum: 0, maximum: 9007199254740991 }
        interaction: { $ref: '#/components/schemas/InteractionRequest' }
        toolNames: { type: array, maxItems: 2048, uniqueItems: true, items: { type: string, minLength: 1, maxLength: 200 } }
        connectors: { type: array, maxItems: 128, items: { $ref: '#/components/schemas/ConnectorStatus' } }
        artifacts: { type: array, maxItems: 32, items: { $ref: '#/components/schemas/ArtifactManifest' } }
        messages: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/ConversationMessage' } }
        usage: { $ref: '#/components/schemas/WebUsageSummary' }
    ConversationSummary:
      type: object
      additionalProperties: false
      required: [id, title, messageCount, createdAt, updatedAt, backend]
      properties:
        id: { $ref: '#/components/schemas/Uuid' }
        title: { type: string, minLength: 1, maxLength: 200 }
        messageCount: { type: integer, minimum: 0, maximum: 1000000 }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        updatedAt: { $ref: '#/components/schemas/Timestamp' }
        backend: { type: string, enum: [pi, codex] }
    ConversationList:
      type: object
      additionalProperties: false
      required: [conversations]
      properties: { conversations: { type: array, maxItems: 200, items: { $ref: '#/components/schemas/ConversationSummary' } } }
    ConversationSnapshot:
      type: object
      additionalProperties: false
      required: [sessionId, lastSequence, messages, artifacts]
      properties:
        sessionId: { $ref: '#/components/schemas/Uuid' }
        lastSequence: { type: integer, minimum: 0, maximum: 9007199254740991 }
        messages: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/ConversationMessage' } }
        artifacts: { type: array, maxItems: 32, items: { $ref: '#/components/schemas/ArtifactManifest' } }
        usage: { $ref: '#/components/schemas/WebUsageSummary' }
    RenameConversationRequest:
      type: object
      additionalProperties: false
      required: [title]
      properties: { title: { type: string, minLength: 1, maxLength: 200, pattern: '.*\\S.*' } }
    ConversationEnvelope:
      type: object
      additionalProperties: false
      required: [conversation]
      properties: { conversation: { $ref: '#/components/schemas/ConversationSummary' } }
    ArtifactManifest:
      type: object
      additionalProperties: false
      required: [id, uri, kind, mimeType, filename, sha256, characters, bytes, createdAt, expiresAt, source]
      properties:
        id: { type: string, pattern: '^artifact_[0-9a-f-]{36}$', maxLength: 45 }
        uri: { type: string, pattern: '^artifact://', maxLength: 512 }
        kind: { type: string, maxLength: 40 }
        mimeType: { type: string, minLength: 1, maxLength: 200 }
        filename: { type: string, minLength: 1, maxLength: 255 }
        sha256: { $ref: '#/components/schemas/Sha256' }
        characters: { type: integer, minimum: 0, maximum: 1073741824 }
        bytes: { type: integer, minimum: 0, maximum: 536870912 }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        expiresAt: { $ref: '#/components/schemas/Timestamp' }
        source:
          type: object
          additionalProperties: false
          required: [serverName, toolName]
          properties:
            serverName: { type: string, minLength: 1, maxLength: 200 }
            toolName: { type: string, minLength: 1, maxLength: 200 }
    ArtifactList:
      type: object
      additionalProperties: false
      required: [artifacts]
      properties: { artifacts: { type: array, maxItems: 32, items: { $ref: '#/components/schemas/ArtifactManifest' } } }
    SessionCron:
      type: object
      additionalProperties: false
      required: [id, name, cron, timezone, recurring, nextRunAt, createdAt, enabled]
      properties:
        id: { $ref: '#/components/schemas/Uuid' }
        name: { type: string, minLength: 1, maxLength: 120 }
        cron: { type: string, minLength: 1, maxLength: 120 }
        timezone: { type: string, minLength: 1, maxLength: 100 }
        recurring: { type: boolean }
        nextRunAt: { $ref: '#/components/schemas/Timestamp' }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        expiresAt: { $ref: '#/components/schemas/Timestamp' }
        enabled: { type: boolean }
    SessionCronList:
      type: object
      additionalProperties: false
      required: [crons]
      properties: { crons: { type: array, maxItems: 50, items: { $ref: '#/components/schemas/SessionCron' } } }
    InteractionQuestion:
      type: object
      additionalProperties: false
      required: [id, prompt, allowOther, options]
      properties:
        id: { type: string, minLength: 1, maxLength: 100, pattern: '^question_[1-3]$' }
        label: { type: string, maxLength: 32 }
        prompt: { type: string, minLength: 1, maxLength: 500 }
        allowOther: { type: boolean }
        options:
          type: array
          minItems: 2
          maxItems: 5
          items:
            type: object
            additionalProperties: false
            required: [value, label]
            properties:
              value: { type: string, pattern: '^option_[1-5]$', maxLength: 20 }
              label: { type: string, minLength: 1, maxLength: 80 }
              description: { type: string, maxLength: 240 }
    InteractionRequest:
      type: object
      additionalProperties: false
      required: [type, id, toolCallId, questions]
      properties:
        type: { const: user_interaction_request }
        id: { $ref: '#/components/schemas/Uuid' }
        toolCallId: { type: string, minLength: 1, maxLength: 200 }
        questions: { type: array, minItems: 1, maxItems: 3, items: { $ref: '#/components/schemas/InteractionQuestion' } }
        durable: { const: true }
    InteractionResponse:
      oneOf:
        - type: object
          additionalProperties: false
          required: [type, id, status, answers]
          properties:
            type: { const: user_interaction_response }
            id: { $ref: '#/components/schemas/Uuid' }
            status: { const: answered }
            answers:
              type: array
              minItems: 1
              maxItems: 3
              items:
                type: object
                additionalProperties: false
                required: [questionId, value, label, custom]
                properties:
                  questionId: { type: string, pattern: '^question_[1-3]$', maxLength: 20 }
                  value: { type: string, minLength: 1, maxLength: 2000 }
                  label: { type: string, minLength: 1, maxLength: 2000 }
                  custom: { type: boolean }
        - type: object
          additionalProperties: false
          required: [type, id, status]
          properties:
            type: { const: user_interaction_response }
            id: { $ref: '#/components/schemas/Uuid' }
            status: { const: cancelled }
    WebUsageSummary:
      type: object
      additionalProperties: false
      required: [input, output, cacheRead, cacheWrite, totalTokens, cost, contextEstimated]
      properties:
        input: { type: integer, minimum: 0, maximum: 2000000 }
        output: { type: integer, minimum: 0, maximum: 2000000 }
        cacheRead: { type: integer, minimum: 0, maximum: 2000000 }
        cacheWrite: { type: integer, minimum: 0, maximum: 2000000 }
        totalTokens: { type: integer, minimum: 0, maximum: 8000000 }
        contextTokens: { type: integer, minimum: 0, maximum: 8000000 }
        contextEstimated: { type: boolean }
        billing: { type: string, enum: [metered, subscription] }
        cost:
          type: object
          additionalProperties: false
          required: [input, output, cacheRead, cacheWrite, total]
          properties:
            input: { type: number, minimum: 0 }
            output: { type: number, minimum: 0 }
            cacheRead: { type: number, minimum: 0 }
            cacheWrite: { type: number, minimum: 0 }
            total: { type: number, minimum: 0 }
    AgentRun:
      type: object
      additionalProperties: false
      required: [id, organizationId, principalId, conversationId, idempotencyKey, trigger, orchestration, state, input, policy, limits, usage, availableAt, attemptCount, maxAttempts, currentStepSequence, currentTurnSequence, pauseRequested, cancelRequested, createdAt, updatedAt]
      properties:
        id: { $ref: '#/components/schemas/Uuid' }
        organizationId: { type: string, minLength: 1, maxLength: 200 }
        principalId: { type: string, minLength: 1, maxLength: 200 }
        conversationId: { $ref: '#/components/schemas/Uuid' }
        idempotencyKey: { type: string, minLength: 1, maxLength: 200 }
        trigger: { type: string, enum: [chat, routine, manual, retry] }
        orchestration: { type: string, enum: [postgres, temporal] }
        state: { type: string, enum: [queued, running, waiting, input_required, paused, completed, failed, cancelled, outcome_unknown] }
        input: { $ref: '#/components/schemas/SessionJsonObject' }
        policy: { $ref: '#/components/schemas/SessionJsonObject' }
        limits: { $ref: '#/components/schemas/SessionJsonObject' }
        output: { $ref: '#/components/schemas/SessionJsonObject' }
        usage: { $ref: '#/components/schemas/SessionJsonObject' }
        availableAt: { $ref: '#/components/schemas/Timestamp' }
        attemptCount: { type: integer, minimum: 0, maximum: 100 }
        maxAttempts: { type: integer, minimum: 1, maximum: 100 }
        currentStepSequence: { type: integer, minimum: 0, maximum: 1000000 }
        currentTurnSequence: { type: integer, minimum: 0, maximum: 1000000 }
        pauseRequested: { type: boolean }
        cancelRequested: { type: boolean }
        parentRunId: { $ref: '#/components/schemas/Uuid' }
        routineId: { $ref: '#/components/schemas/Uuid' }
        temporalWorkflowId: { type: string, maxLength: 200 }
        temporalRunId: { type: string, maxLength: 200 }
        startedAt: { $ref: '#/components/schemas/Timestamp' }
        completedAt: { $ref: '#/components/schemas/Timestamp' }
        errorCode: { type: string, maxLength: 200 }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        updatedAt: { $ref: '#/components/schemas/Timestamp' }
    AgentRunList:
      type: object
      additionalProperties: false
      required: [runs]
      properties: { runs: { type: array, maxItems: 200, items: { $ref: '#/components/schemas/AgentRun' } } }
    Wake:
      type: object
      additionalProperties: false
      required: [kind]
      properties:
        kind: { type: string, enum: [timer, poll, external_event, user_input] }
        wakeAt: { $ref: '#/components/schemas/Timestamp' }
    AgentRunDetail:
      type: object
      additionalProperties: false
      required: [run]
      properties:
        run: { $ref: '#/components/schemas/AgentRun' }
        wake: { $ref: '#/components/schemas/Wake' }
        inputRequest: { $ref: '#/components/schemas/InteractionRequest' }
    RunEnvelope:
      type: object
      additionalProperties: false
      required: [run]
      properties: { run: { $ref: '#/components/schemas/AgentRun' } }
    DurableWait:
      type: object
      additionalProperties: false
      required: [id, runId, stepId, kind, state, pollPolicy, payload, createdAt]
      properties:
        id: { $ref: '#/components/schemas/Uuid' }
        runId: { $ref: '#/components/schemas/Uuid' }
        stepId: { $ref: '#/components/schemas/Uuid' }
        kind: { type: string, enum: [timer, poll, external_event, user_input] }
        state: { type: string, enum: [pending, resolved, cancelled, expired] }
        wakeAt: { $ref: '#/components/schemas/Timestamp' }
        correlationKey: { type: string, maxLength: 200 }
        pollPolicy: { $ref: '#/components/schemas/SessionJsonObject' }
        payload: { $ref: '#/components/schemas/SessionJsonObject' }
        result: { $ref: '#/components/schemas/SessionJsonObject' }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        resolvedAt: { $ref: '#/components/schemas/Timestamp' }
    WaitEnvelope:
      type: object
      additionalProperties: false
      required: [wait]
      properties: { wait: { $ref: '#/components/schemas/DurableWait' } }
    DurableApproval:
      type: object
      additionalProperties: false
      required: [id, runId, stepId, state, request, createdAt]
      properties:
        id: { $ref: '#/components/schemas/Uuid' }
        runId: { $ref: '#/components/schemas/Uuid' }
        stepId: { $ref: '#/components/schemas/Uuid' }
        state: { type: string, enum: [pending, approved, rejected, cancelled, expired] }
        request: { $ref: '#/components/schemas/SessionJsonObject' }
        response: { $ref: '#/components/schemas/SessionJsonObject' }
        expiresAt: { $ref: '#/components/schemas/Timestamp' }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
        decidedAt: { $ref: '#/components/schemas/Timestamp' }
    ApprovalEnvelope:
      type: object
      additionalProperties: false
      required: [approval]
      properties: { approval: { $ref: '#/components/schemas/DurableApproval' } }
    AuditEvent:
      type: object
      additionalProperties: false
      required: [id, runId, organizationId, principalId, type, payload, previousHash, hash, createdAt]
      properties:
        id: { type: integer, minimum: 1, maximum: 9007199254740991 }
        runId: { $ref: '#/components/schemas/Uuid' }
        organizationId: { type: string, minLength: 1, maxLength: 200 }
        principalId: { type: string, minLength: 1, maxLength: 200 }
        type: { type: string, minLength: 1, maxLength: 200 }
        payload: { $ref: '#/components/schemas/SessionJsonObject' }
        previousHash: { $ref: '#/components/schemas/Sha256' }
        hash: { $ref: '#/components/schemas/Sha256' }
        createdAt: { $ref: '#/components/schemas/Timestamp' }
    AuditEventList:
      type: object
      additionalProperties: false
      required: [events]
      properties: { events: { type: array, maxItems: 10000, items: { $ref: '#/components/schemas/AuditEvent' } } }
    SessionEvent:
      oneOf:
        - { $ref: '#/components/schemas/EventSessionCreated' }
        - { $ref: '#/components/schemas/EventSessionResumed' }
        - { $ref: '#/components/schemas/EventSessionClosed' }
        - { $ref: '#/components/schemas/EventSessionSnapshot' }
        - { $ref: '#/components/schemas/EventRunStarted' }
        - { $ref: '#/components/schemas/EventRunCompleted' }
        - { $ref: '#/components/schemas/EventRunFailed' }
        - { $ref: '#/components/schemas/EventRunAborted' }
        - { $ref: '#/components/schemas/EventRunAbortRequested' }
        - { $ref: '#/components/schemas/EventAgentStarted' }
        - { $ref: '#/components/schemas/EventAgentSettled' }
        - { $ref: '#/components/schemas/EventTurnStarted' }
        - { $ref: '#/components/schemas/EventTurnCompleted' }
        - { $ref: '#/components/schemas/EventMessageStarted' }
        - { $ref: '#/components/schemas/EventAssistantUpdated' }
        - { $ref: '#/components/schemas/EventAssistantCompleted' }
        - { $ref: '#/components/schemas/EventUserCompleted' }
        - { $ref: '#/components/schemas/EventToolStarted' }
        - { $ref: '#/components/schemas/EventToolUpdated' }
        - { $ref: '#/components/schemas/EventToolCompleted' }
        - { $ref: '#/components/schemas/EventToolFailed' }
        - { $ref: '#/components/schemas/EventQueueSteered' }
        - { $ref: '#/components/schemas/EventQueueFollowUp' }
        - { $ref: '#/components/schemas/EventInteractionRequested' }
        - { $ref: '#/components/schemas/EventInteractionResponseReceived' }
        - { $ref: '#/components/schemas/EventInteractionDismissed' }
        - { $ref: '#/components/schemas/EventArtifactCreated' }
        - { $ref: '#/components/schemas/EventArtifactDeleted' }
        - { $ref: '#/components/schemas/EventMcpError' }
        - { $ref: '#/components/schemas/EventCompactionStarted' }
        - { $ref: '#/components/schemas/EventCompactionSummary' }
        - { $ref: '#/components/schemas/EventCompactionCompleted' }
        - { $ref: '#/components/schemas/EventCompactionSkipped' }
        - { $ref: '#/components/schemas/EventCompactionFailed' }
        - { $ref: "#/components/schemas/EventDurableFailed" }
        - { $ref: "#/components/schemas/EventDurableCancelled" }
        - { $ref: "#/components/schemas/EventDurableOutcomeUnknown" }
      discriminator:
        propertyName: type
        mapping:
          session.created: "#/components/schemas/EventSessionCreated"
          session.resumed: "#/components/schemas/EventSessionResumed"
          session.closed: "#/components/schemas/EventSessionClosed"
          session.snapshot: "#/components/schemas/EventSessionSnapshot"
          run.started: "#/components/schemas/EventRunStarted"
          run.completed: "#/components/schemas/EventRunCompleted"
          run.failed: "#/components/schemas/EventRunFailed"
          run.aborted: "#/components/schemas/EventRunAborted"
          run.abort_requested: "#/components/schemas/EventRunAbortRequested"
          agent.started: "#/components/schemas/EventAgentStarted"
          agent.settled: "#/components/schemas/EventAgentSettled"
          turn.started: "#/components/schemas/EventTurnStarted"
          turn.completed: "#/components/schemas/EventTurnCompleted"
          message.started: "#/components/schemas/EventMessageStarted"
          assistant.updated: "#/components/schemas/EventAssistantUpdated"
          assistant.completed: "#/components/schemas/EventAssistantCompleted"
          user.completed: "#/components/schemas/EventUserCompleted"
          tool.started: "#/components/schemas/EventToolStarted"
          tool.updated: "#/components/schemas/EventToolUpdated"
          tool.completed: "#/components/schemas/EventToolCompleted"
          tool.failed: "#/components/schemas/EventToolFailed"
          queue.steered: "#/components/schemas/EventQueueSteered"
          queue.follow_up: "#/components/schemas/EventQueueFollowUp"
          interaction.requested: "#/components/schemas/EventInteractionRequested"
          interaction.response_received: "#/components/schemas/EventInteractionResponseReceived"
          interaction.dismissed: "#/components/schemas/EventInteractionDismissed"
          artifact.created: "#/components/schemas/EventArtifactCreated"
          artifact.deleted: "#/components/schemas/EventArtifactDeleted"
          mcp.error: "#/components/schemas/EventMcpError"
          compaction.started: "#/components/schemas/EventCompactionStarted"
          compaction.summary: "#/components/schemas/EventCompactionSummary"
          compaction.completed: "#/components/schemas/EventCompactionCompleted"
          compaction.skipped: "#/components/schemas/EventCompactionSkipped"
          compaction.failed: "#/components/schemas/EventCompactionFailed"
          durable.failed: "#/components/schemas/EventDurableFailed"
          durable.cancelled: "#/components/schemas/EventDurableCancelled"
          durable.outcome_unknown: "#/components/schemas/EventDurableOutcomeUnknown"
    EventBase:
      type: object
      additionalProperties: false
      required: [sessionId, sequence, timestamp, type, payload]
      properties:
        sessionId: { $ref: '#/components/schemas/Uuid' }
        runId: { $ref: '#/components/schemas/Uuid' }
        sequence: { type: integer, minimum: 1, maximum: 9007199254740991 }
        timestamp: { $ref: '#/components/schemas/Timestamp' }
        type: { type: string }
        payload: { type: object }
    EventSessionCreated:
      allOf:
        - { $ref: '#/components/schemas/EventBase' }
        - type: object
          properties:
            type: { const: session.created }
            payload:
              type: object
              additionalProperties: false
              required: [toolNames, connectors]
              properties:
                toolNames: { type: array, maxItems: 2048, items: { type: string, maxLength: 200 } }
                connectors: { type: array, maxItems: 128, items: { $ref: '#/components/schemas/ConnectorStatus' } }
    EventSessionResumed:
      allOf:
        - { $ref: "#/components/schemas/EventBase" }
        - type: object
          properties:
            type: { const: session.resumed }
            payload:
              type: object
              additionalProperties: false
              required: [toolNames, connectors]
              properties:
                toolNames: { type: array, maxItems: 2048, items: { type: string, maxLength: 200 } }
                connectors: { type: array, maxItems: 128, items: { $ref: "#/components/schemas/ConnectorStatus" } }
    EventSessionClosed:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: session.closed }, payload: { type: object, additionalProperties: false } } } ]
    EventSessionSnapshot:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: session.snapshot }, payload: { $ref: '#/components/schemas/SessionSnapshot' } } } ]
    EventRunStarted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: run.started }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 8000 } } } } } ]
    EventRunCompleted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: run.completed }, payload: { type: object, additionalProperties: false } } } ]
    EventRunFailed:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: run.failed }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 2000 } } } } } ]
    EventRunAborted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: run.aborted }, payload: { type: object, additionalProperties: false } } } ]
    EventRunAbortRequested:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: run.abort_requested }, payload: { type: object, additionalProperties: false } } } ]
    EventAgentStarted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: agent.started }, payload: { type: object, additionalProperties: false } } } ]
    EventAgentSettled:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: agent.settled }, payload: { type: object, additionalProperties: false } } } ]
    EventTurnStarted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: turn.started }, payload: { type: object, additionalProperties: false } } } ]
    EventTurnCompleted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: turn.completed }, payload: { type: object, additionalProperties: false } } } ]
    EventMessageStarted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: message.started }, payload: { type: object, additionalProperties: false, required: [role], properties: { role: { type: string, enum: [user, assistant, tool, custom] } } } } } ]
    EventAssistantUpdated:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: assistant.updated }, payload: { type: object, additionalProperties: false, required: [text, reasoning, reasoningVisibility], properties: { text: { type: string, maxLength: 32000 }, reasoning: { type: string, maxLength: 32000 }, reasoningVisibility: { type: string, enum: [none, summary, full] } } } } } ]
    EventAssistantCompleted:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: assistant.completed }, payload: { type: object, additionalProperties: false, required: [text, reasoning, reasoningVisibility], properties: { text: { type: string, maxLength: 32000 }, reasoning: { type: string, maxLength: 32000 }, reasoningVisibility: { type: string, enum: [none, summary, full] }, usage: { $ref: "#/components/schemas/SessionJsonObject" }, billing: { type: string, enum: [metered, subscription] }, artifacts: { type: array, maxItems: 32, items: { $ref: "#/components/schemas/ArtifactManifest" } } } } } } ]
    EventUserCompleted:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: user.completed }, payload: { type: object, additionalProperties: false, required: [text], properties: { text: { type: string, maxLength: 32000 } } } } } ]
    EventToolStarted:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: tool.started }, payload: { type: object, additionalProperties: false, required: [toolCallId, toolName, arguments], properties: { toolCallId: { type: string, minLength: 1, maxLength: 200 }, toolName: { type: string, minLength: 1, maxLength: 200 }, arguments: { type: string, maxLength: 8000 } } } } } ]
    EventToolUpdated:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: tool.updated }, payload: { type: object, additionalProperties: false, required: [toolCallId, toolName, preview], properties: { toolCallId: { type: string, minLength: 1, maxLength: 200 }, toolName: { type: string, minLength: 1, maxLength: 200 }, preview: { type: string, maxLength: 8000 } } } } } ]
    EventToolCompleted:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: tool.completed }, payload: { type: object, additionalProperties: false, required: [toolCallId, toolName, result], properties: { toolCallId: { type: string, minLength: 1, maxLength: 200 }, toolName: { type: string, minLength: 1, maxLength: 200 }, result: { type: string, maxLength: 16000 } } } } } ]
    EventToolFailed:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: tool.failed }, payload: { type: object, additionalProperties: false, required: [toolCallId, toolName, result], properties: { toolCallId: { type: string, minLength: 1, maxLength: 200 }, toolName: { type: string, minLength: 1, maxLength: 200 }, result: { type: string, maxLength: 16000 } } } } } ]
    EventQueueSteered:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: queue.steered }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 8000 } } } } } ]
    EventQueueFollowUp:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: queue.follow_up }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 8000 } } } } } ]
    EventInteractionRequested:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: interaction.requested }, payload: { $ref: '#/components/schemas/InteractionRequest' } } } ]
    EventInteractionResponseReceived:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: interaction.response_received }, payload: { type: object, additionalProperties: false, required: [id], properties: { id: { $ref: '#/components/schemas/Uuid' } } } } } ]
    EventInteractionDismissed:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: interaction.dismissed }, payload: { type: object, additionalProperties: false, required: [id, reason], properties: { id: { $ref: '#/components/schemas/Uuid' }, reason: { type: string, enum: [cancelled, timed_out, aborted, shutdown, disconnected] } } } } } ]
    EventArtifactCreated:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: artifact.created }, payload: { type: object, additionalProperties: false, required: [artifact], properties: { artifact: { $ref: '#/components/schemas/ArtifactManifest' } } } } } ]
    EventArtifactDeleted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: artifact.deleted }, payload: { type: object, additionalProperties: false, required: [artifactId], properties: { artifactId: { type: string, pattern: '^artifact_[0-9a-f-]{36}$' } } } } } ]
    EventMcpError:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: mcp.error }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 2000 } } } } } ]
    EventCompactionStarted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: compaction.started }, payload: { type: object, additionalProperties: false, required: [tokens], properties: { tokens: { type: integer, minimum: 0, maximum: 8000000 } } } } } ]
    EventCompactionSummary:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: compaction.summary }, payload: { type: object, additionalProperties: false, required: [summary], properties: { summary: { type: string, maxLength: 32000 } } } } } ]
    EventCompactionCompleted:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: compaction.completed }, payload: { type: object, additionalProperties: false, required: [before, after, removedMessages, usage], properties: { before: { type: integer, minimum: 0, maximum: 8000000 }, after: { type: integer, minimum: 0, maximum: 8000000 }, removedMessages: { type: integer, minimum: 0, maximum: 1000000 }, usage: { $ref: '#/components/schemas/SessionJsonObject' } } } } } ]
    EventCompactionSkipped:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: compaction.skipped }, payload: { type: object, additionalProperties: false, required: [reason], properties: { reason: { type: string, maxLength: 1000 } } } } } ]
    EventCompactionFailed:
      allOf: [ { $ref: '#/components/schemas/EventBase' }, { type: object, properties: { type: { const: compaction.failed }, payload: { type: object, additionalProperties: false, required: [message], properties: { message: { type: string, maxLength: 2000 } } } } } ]
    EventDurableFailed:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: durable.failed }, payload: { type: object, additionalProperties: false, required: [runId, state, message], properties: { runId: { $ref: "#/components/schemas/Uuid" }, state: { const: failed }, message: { type: string, maxLength: 2000 } } } } } ]
    EventDurableCancelled:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: durable.cancelled }, payload: { type: object, additionalProperties: false, required: [runId, state, message], properties: { runId: { $ref: "#/components/schemas/Uuid" }, state: { const: cancelled }, message: { type: string, maxLength: 2000 } } } } } ]
    EventDurableOutcomeUnknown:
      allOf: [ { $ref: "#/components/schemas/EventBase" }, { type: object, properties: { type: { const: durable.outcome_unknown }, payload: { type: object, additionalProperties: false, required: [runId, state, message], properties: { runId: { $ref: "#/components/schemas/Uuid" }, state: { const: outcome_unknown }, message: { type: string, maxLength: 2000 } } } } } ]
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required: [error]
      properties: { error: { type: string } }
    ErrorInvalidRequest: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: invalid_request } } } ] }
    ErrorInvalidRunRequest: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [invalid_message, invalid_idempotency_key] } } } ] }
    ErrorInvalidMessage: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: invalid_message } } } ] }
    ErrorInvalidInteraction: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: invalid_interaction_response } } } ] }
    ErrorInvalidCursor: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: invalid_event_cursor } } } ] }
    ErrorUnauthorized: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: unauthorized } } } ] }
    ErrorNotFound: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: not_found } } } ] }
    ErrorConflict: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [idempotency_conflict, session_busy] } } } ] }
    ErrorRetryConflict: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [reconciliation_required, attempts_exhausted, durable_run_limits_exhausted] } } } ] }
    ErrorSessionIdle: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: session_idle } } } ] }
    ErrorConversationBusy: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [conversation_busy, conversation_has_routines] } } } ] }
    ErrorCapacity: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [queue_capacity_unavailable, session_capacity_unavailable] } } } ] }
    ErrorSubscriberCapacity: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: subscriber_capacity_unavailable } } } ] }
    ErrorDurableUnavailable: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: durable_runs_unavailable } } } ] }
    ErrorServiceUnavailable: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { enum: [service_closing, durable_automation_unavailable] } } } ] }
    ErrorUnsupportedMediaType: { allOf: [ { $ref: '#/components/schemas/ErrorEnvelope' }, { type: object, properties: { error: { const: unsupported_media_type } } } ] }
