openapi.yaml

openapi: 3.0.3
info:
  title: claude-code-java Gateway Web API
  version: 1.0.0-draft
  description: |
    The in-process HTTP+SSE gateway serving web clients of the same instance
    (TUI keeps its own session; the gateway routes parallel headless sessions
    and mirrors every followed session).

    This contract is the authoritative alignment standard for the gateway's
    web rendering API, keeping official Claude Code stream-json wire naming
    first priority. It is the single source of truth: the SSE mirror-frame
    catalog lives in the MirrorFrame schema, not in a side document.

    Alignment strategy (two steps): this document is the standard first; code
    implementation then aligns to it.
servers:
  - url: http://127.0.0.1:{port}
    description: Loopback gateway launched by the /web command (token required)
    variables:
      port:
        default: '0'
security:
  - bearerToken: []
  - queryToken: []
tags:
  - name: Protocol
    description: The three streaming turn-submission wire formats (Anthropic/OpenAI-compatible)
  - name: Sessions
    description: Session catalog, headless open/close, message snapshots, and the SSE mirror stream
  - name: Permissions
    description: Answering pending permission asks and user questions
  - name: Settings
    description: Effective settings snapshot and per-tier settings mutations
  - name: Schedule
    description: Cron-style scheduled task management
  - name: Models
    description: The custom model catalogue shared with the /model command
paths:
  /v1/messages:
    post:
      tags: [Protocol]
      summary: Anthropic Messages protocol face (streaming SSE)
      description: |
        Submits one turn. The session is routed by metadata.session_id:
        absent → the active session (409 when none); a headless session id;
        or the active TUI session's own id. Responses follow the Anthropic
        streaming wire format (message_start / content_block_* / message_stop).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, messages]
              properties:
                model:
                  type: string
                stream:
                  type: boolean
                  default: true
                metadata:
                  type: object
                  properties:
                    session_id:
                      type: string
                      description: Session routing key (headless id, active TUI id, or absent)
                    user_id:
                      type: string
                      description: Idempotency key; a repeated value does not resubmit
                messages:
                  type: array
                  items:
                    $ref: '#/components/schemas/ProtocolMessage'
      responses:
        '200':
          description: SSE stream of the turn (Anthropic streaming events)
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '409': { $ref: '#/components/responses/NoActiveSession' }
        '429': { $ref: '#/components/responses/SessionBusy' }
  /v1/chat/completions:
    post:
      tags: [Protocol]
      summary: OpenAI Chat Completions protocol face (streaming SSE)
      description: Same routing and turn semantics as /v1/messages over the OpenAI wire format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, messages]
              properties:
                model: { type: string }
                stream: { type: boolean, default: true }
                metadata:
                  type: object
                  properties:
                    session_id: { type: string }
                    user_id: { type: string }
                messages:
                  type: array
                  items: { $ref: '#/components/schemas/ProtocolMessage' }
      responses:
        '200': { description: SSE stream of the turn (OpenAI wire events) }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '409': { $ref: '#/components/responses/NoActiveSession' }
        '429': { $ref: '#/components/responses/SessionBusy' }
  /v1/responses:
    post:
      tags: [Protocol]
      summary: OpenAI Responses protocol face (streaming SSE)
      description: Same routing and turn semantics as /v1/messages over the Responses wire format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, input]
              properties:
                model: { type: string }
                stream: { type: boolean, default: true }
                metadata:
                  type: object
                  properties:
                    session_id: { type: string }
                    user_id: { type: string }
                input: { $ref: '#/components/schemas/ProtocolMessage' }
      responses:
        '200': { description: SSE stream of the turn (Responses wire events) }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '409': { $ref: '#/components/responses/NoActiveSession' }
        '429': { $ref: '#/components/responses/SessionBusy' }
  /api/sessions:
    get:
      tags: [Sessions]
      summary: Full two-level session catalog (aligned with the TUI /resume picker)
      description: |
        Every project and every session on disk, not only open ones. Rows carry
        active:true for the current TUI session and headless_open:true for
        sessions routable right now without an open round-trip. Each project's
        sessions are paged to its most recent per_project rows (session_count
        keeps the total); grow the page with a larger per_project.
      parameters:
        - name: per_project
          in: query
          required: false
          schema: { type: string }
          description: Rows per project (1..1000); "all" serves every row. Defaults to 5.
      responses:
        '200':
          description: Two-level project→session listing (flat fallback when no catalog is wired)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SessionCatalog'
                  - $ref: '#/components/schemas/FlatSessionList'
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/sessions/open:
    post:
      tags: [Sessions]
      summary: Open (or resume) one parallel headless session
      description: |
        Mints a session when session_id is absent; reuses an open one; resumes
        message-level from the on-disk transcript when the id exists on disk.
        project_path defaults to the process project (cross-project support).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  type: string
                  maxLength: 256
                project_path:
                  type: string
                  description: Defaults to the process project; any existing directory for a cross-project session
      responses:
        '200':
          description: The opened session
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OpenedSession' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/SessionBusy' }
  /api/sessions/close:
    post:
      tags: [Sessions]
      summary: Close one headless session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_id]
              properties:
                session_id: { type: string }
      responses:
        '200':
          description: Closure result
          content:
            application/json:
              schema:
                type: object
                properties:
                  closed: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
  /api/sessions/{sessionId}/messages:
    get:
      tags: [Sessions]
      summary: Message snapshot for one session
      description: |
        Snapshot-first: the authoritative current message list. A reconnecting
        client pulls this once and then follows SSE increments — snapshot
        replay over HTTP. The assistant-message shape uses content[] with
        typed tool_call entries; a tool_use block pairs with its later
        tool_result block by tool use id into the entry's status/result/ready
        fields (pending when the result has not arrived). Open headless
        sessions serve live in-memory messages; other known session ids
        serve their on-disk transcript.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Message snapshot
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MessageSnapshot' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
  /api/sessions/{sessionId}/rename:
    post:
      tags: [Sessions]
      summary: Rename a session in place
      description: |
        Appends a custom-title JSONL event; confirming an unchanged title is
        deliberately allowed. Mirrors the upstream row menu's Rename action.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
      responses:
        '200':
          description: Rename result
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id: { type: string }
                  custom_title: { type: string }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '500': { $ref: '#/components/responses/SessionOperationFailed' }
  /api/sessions/{sessionId}/fork:
    post:
      tags: [Sessions]
      summary: Fork a session at its last completed turn
      description: |
        Copies the source transcript up to its last completed turn into a new
        session id. Mirrors the upstream row menu's Fork session action.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
      responses:
        '200':
          description: The forked session's id
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id: { type: string }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '500': { $ref: '#/components/responses/SessionOperationFailed' }
  /api/sessions/{sessionId}/archive:
    post:
      tags: [Sessions]
      summary: Hide a session from the default catalog listing
      description: |
        Appends a one-way archived JSONL event; the transcript itself is
        untouched. Archived sessions are filtered out of every grouping
        surface (webui and the TUI /resume picker share the same catalog).
        No unarchive endpoint exists in this pass.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Archive result
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id: { type: string }
                  archived: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '500': { $ref: '#/components/responses/SessionOperationFailed' }
  /api/sessions/{sessionId}:
    delete:
      tags: [Sessions]
      summary: Permanently delete a session
      description: |
        Deletes the session's transcript and sidecar directory from disk.
        Product-scope extension with no upstream counterpart — reuses the
        Java /resume picker's permanent-deletion capability.

        An id no session answers to is 404, not an error: two clients on the
        same catalog listing race, and the loser deleting an already-deleted
        row got the outcome it asked for. 500 is reserved for a session that
        resolved and could not be deleted.
      parameters:
        - name: sessionId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Delete result
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id: { type: string }
                  deleted: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/UnknownSession' }
        '500': { $ref: '#/components/responses/SessionOperationFailed' }
  /api/events:
    get:
      tags: [Sessions]
      summary: SSE mirror stream of every followed session
      description: |
        Server-sent events for the active TUI session plus every open headless
        session. Every frame's data JSON carries session_id. Reconnect with
        Last-Event-ID to replay the bounded ring; ?session_id= narrows to one
        conversation view. The turn.completed frame's data carries elapsed_ms
        (turn wall time), ttft_ms (time to first stream output; absent when
        the turn produced none), time (epoch ms), and turn + turn_usage (the
        durable-fold delta; the usage body's model is the turn's last-reported
        model id).
      parameters:
        - name: session_id
          in: query
          required: false
          schema: { type: string }
          description: Only frames whose session_id matches
        - name: Last-Event-ID
          in: header
          required: false
          schema: { type: string }
          description: Replay every journaled frame after this id
        - name: token
          in: query
          required: false
          schema: { type: string }
          description: Alternative to the Authorization header
      responses:
        '200':
          description: text/event-stream of mirror frames
          content:
            text/event-stream:
              schema: { $ref: '#/components/schemas/MirrorFrame' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/permissions/respond:
    post:
      tags: [Permissions]
      summary: Answer one pending permission ask or user question
      description: |
        A tool waiting at ASK blocks inside the shared interaction
        coordinator; the TUI dialog and a web client are two observers of the
        same ask — first answer wins. The request_id comes from the matching
        permission.asked frame. For AskUserQuestion asks, the chosen answers
        go back through updated_input (the rewritten tool input); feedback
        carries an optional deny reason or allow instruction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [request_id, session_id, allowed]
              properties:
                request_id:
                  type: string
                  description: The id from the matching permission.asked frame
                session_id: { type: string }
                allowed:
                  type: boolean
                  description: true = execute, false = cancel
                feedback:
                  type: string
                  description: Optional deny reason or allow instruction
                updated_input:
                  type: object
                  description: AskUserQuestion answers as the rewritten tool input
                skip:
                  type: boolean
                  description: Skip this tool call (denies with a skip-marked message)
      responses:
        '200':
          description: The ask was answered by this request
          content:
            application/json:
              schema:
                type: object
                properties:
                  responded: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409':
          description: The ask was already answered by another observer
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
  /api/settings:
    get:
      tags: [Settings]
      summary: Effective settings snapshot with per-tier source attribution
      description: |
        Merges every settings tier (user -> project -> local -> flag -> policy,
        later tiers overriding earlier) into one effective object, alongside
        the raw per-tier settings for whichever tiers are actually present on
        disk right now.
      responses:
        '200':
          description: The effective snapshot
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SettingsSnapshot' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Settings]
      summary: Apply one settings mutation, dispatched by the op field
      description: |
        Every successful mutation responds with the refreshed effective
        snapshot (same shape as GET), so the web client never has to
        re-fetch. tier is one of user|project|local; behavior is one of
        allow|deny|ask.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/UserValueOp'
                - $ref: '#/components/schemas/PermissionModeOp'
                - $ref: '#/components/schemas/PermissionRulesOp'
                - $ref: '#/components/schemas/DirectoriesOp'
      responses:
        '200':
          description: The refreshed effective snapshot
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SettingsSnapshot' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/schedule:
    get:
      tags: [Schedule]
      summary: List every scheduled (cron) task known to this process
      responses:
        '200':
          description: The task list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScheduleList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Schedule]
      summary: Create one scheduled task
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ScheduleCreateRequest' }
      responses:
        '200':
          description: The generated task id
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/schedule/{id}:
    delete:
      tags: [Schedule]
      summary: Remove one scheduled task
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/models:
    get:
      tags: [Models]
      summary: List the custom model catalogue (shared with the /model command)
      responses:
        '200':
          description: The model list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ModelList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Models]
      summary: Save (add or update) one custom model entry
      description: |
        api_key is a tri-state field: absent keeps the existing key, null
        clears it, a string sets it. api_key is never echoed back by GET.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ModelSaveRequest' }
      responses:
        '200':
          description: The refreshed model list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ModelList' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/commands:
    get:
      tags: [Commands]
      summary: List the composer menu catalogue (slash commands and skills)
      description: |
        One row per non-hidden interactive command; skills appear here too
        because they register as commands. Feeds the webui composer's "+"
        menu, mirroring dsh's host command catalog listing.
      responses:
        '200':
          description: The command list
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommandList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/session/context:
    get:
      tags: [Sessions]
      summary: One session's model selection, context usage, and session metrics
      description: |
        Feeds the webui composer's model seat, context meter, and stats
        pills (mirroring dsh's remote session model/context surface). The
        selection half lists the same /model catalogue the TUI serves
        (built-in families, custom models, allowlist-filtered); the context
        half reuses the claude-hud status-line token accounting — the
        finalized usage anchor's input-token sum over the model-resolved
        context window — so the meter and the status line show one number.
        The metrics half projects the engine's durable whole-session fold
        (the same SessionMetricsTracker fold the TUI status line renders);
        raw integers cross the wire and the client owns display formatting.

        The addressed session follows the protocol turn runner's routing:
        an open headless session id, the active TUI session's own id, or
        blank for the active TUI session. Any other known id serves its
        on-disk transcript as a read-only target (usage measured, no live
        selection — both halves render null without one).
      parameters:
        - name: session_id
          in: query
          required: false
          schema: { type: string }
          description: The session to address; absent means the active TUI session
      responses:
        '200':
          description: Selection, usage, and metrics; each half is null without a live target
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SessionContext' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Sessions]
      summary: Change one session's model or reasoning effort
      description: |
        One selection per request. Both go through the addressed session's
        live controllers — the same control path the TUI /model picker and
        Session Link endpoints drive for the TUI session, or the open
        headless session's own engine — so a web selection and a TUI
        selection of the same session stay in lockstep while sibling
        sessions keep their own choices. A running turn keeps the model it
        started with; the new choice applies to the next prompt assembly.
        The refreshed answer carries the session's metrics alongside the
        selection and usage, so a selection change never blanks the
        stats pills.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SessionContextSelectRequest' }
      responses:
        '200':
          description: The refreshed selection, usage, and metrics
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SessionContext' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/session/permission-mode:
    get:
      tags: [Sessions]
      summary: One session's live permission-mode selection
      description: |
        Feeds the webui composer's permission-mode chip — the remote
        counterpart of the TUI Shift+Tab cycle. The addressed session
        follows the same routing as /api/session/context: an open headless
        session id, the active TUI session's own id, or blank for the
        active TUI session. Any other id has no live PermissionGate to
        report and renders null.
      parameters:
        - name: session_id
          in: query
          required: false
          schema: { type: string }
          description: The session to address; absent means the active TUI session
      responses:
        '200':
          description: The current mode and selectable modes; null without a live target
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SessionPermissionModeResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Sessions]
      summary: Change one session's permission mode
      description: |
        Applies through the addressed session's live PermissionGate — the
        same control path the TUI Shift+Tab cycle and the SDK
        set_permission_mode control request drive. bypassPermissions is
        rejected (400) when the session was not launched with
        --dangerously-skip-permissions or policy disables it.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SessionPermissionModeSelectRequest' }
      responses:
        '200':
          description: The refreshed permission-mode state
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SessionPermissionModeResponse' }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/session/context/timeline:
    get:
      tags: [Sessions]
      summary: One live session's context-timeline head (dsh-context wire shape)
      description: |
        The slim head of the gateway's per-session context ledger — the
        current heuristic composition, the retained-window counts, the
        newest request's billing anchor, cost/timing totals, and the
        `detailRev` cursor an open Context tab refetches the detail on.
        Emits the camelCase `ContextTimeline` structure of dsh-context's
        `shared/types.ts` (an intentional exception to this API's
        snake_case convention, so the vendored webui helpers consume it
        unchanged; see webui/UPSTREAM.md). Only live sessions (the active
        TUI session and open headless sessions) own a ledger — any other id
        answers `timeline: null`.
      parameters:
        - $ref: '#/components/parameters/ContextSessionId'
      responses:
        '200':
          description: The head, or null for a cold session
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeline:
                    allOf: [ { $ref: '#/components/schemas/ContextTimelineHead' } ]
                    nullable: true
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/session/context/detail:
    get:
      tags: [Sessions]
      summary: One live session's context-timeline detail collections
      description: |
        The heavy collections behind the head: per-request records, context
        events, the served surface window, the removed-node archive with
        `gone` stamps, the file-operation log, the request-header epoch
        metadata, and this product's `agents[]` extension (the session's
        Task/Agent tool calls). `rev` mirrors the head's `detailRev` at the
        same fold cut (latest-wins cursor). Shape: dsh-context
        `ContextTimelineDetail` plus `headers` (`ContextHeaders`) and
        `agents`.
      parameters:
        - $ref: '#/components/parameters/ContextSessionId'
      responses:
        '200':
          description: The detail payload, or null for a cold session
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    allOf: [ { $ref: '#/components/schemas/ContextTimelineDetail' } ]
                    nullable: true
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/session/context/content:
    get:
      tags: [Sessions]
      summary: One surface node's stored content, the system prompt, or one tool definition
      description: |
        On-demand content the timeline wire deliberately omits: a node's
        bounded text by `seq`, the live system prompt (`kind=system`, joined
        and as assembler parts), one tool's description and JSON schema
        (`kind=tool&name=`), or every tool definition at once (`kind=tools`,
        the browser's header epoch). Bounded like the mirror's result excerpts
        (20k chars, truncation marker).
      parameters:
        - $ref: '#/components/parameters/ContextSessionId'
        - name: seq
          in: query
          required: false
          schema: { type: integer }
          description: The surface node's fold sequence number
        - name: kind
          in: query
          required: false
          schema: { type: string, enum: [system, tool, tools] }
          description: Header content instead of a node
        - name: name
          in: query
          required: false
          schema: { type: string }
          description: The tool name for kind=tool
      responses:
        '200':
          description: The content
          content:
            application/json:
              schema:
                type: object
                properties:
                  content: { type: object, additionalProperties: true }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/session/context/overview:
    get:
      tags: [Sessions]
      summary: Every live session's context head and daily activity ledger
      description: |
        The Context Dashboard's aggregate: one row per live session (the
        active TUI session and every open headless session) with its
        timeline head, per-local-day activity ledger (dsh-context
        `ContextActivity`), run state, and title/cwd. Transcript-only
        sessions are never listed.
      responses:
        '200':
          description: The live sessions' heads and activity
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ContextOverview' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/models/{name}:
    delete:
      tags: [Models]
      summary: Remove one custom model entry
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed: { type: boolean }
        '400': { $ref: '#/components/responses/InvalidRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: The launch token printed by the /web command
    queryToken:
      type: apiKey
      in: query
      name: token
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [type, message]
          properties:
            type:
              type: string
              description: |
                invalid_request (400: malformed JSON, missing session_id, over
                length), authentication_required (401), not_found (404: unknown
                route or session), already_responded (409: an ask another
                observer settled, or a submission with no session_id and no
                active session), api_error (429: a turn already in flight on
                this session, or the headless session limit).
            message: { type: string }
    ProtocolMessage:
      type: object
      required: [role, content]
      properties:
        role: { type: string, enum: [user, assistant] }
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type: { type: string, enum: [text, image, document] }
                  text: { type: string }
                  title:
                    type: string
                    description: Document display name; becomes the persisted file name
                  source:
                    type: object
                    required: [type, media_type, data]
                    properties:
                      type: { type: string, enum: [base64] }
                      media_type: { type: string }
                      data:
                        type: string
                        description: base64 payload; images become inline picture blocks, documents are persisted under the project and referenced by path
    SessionCatalog:
      type: object
      properties:
        projects:
          type: array
          items:
            type: object
            properties:
              project_path: { type: string }
              project_name: { type: string }
              session_count: { type: integer, description: Total sessions in the project (sessions may be a paged subset) }
              sessions:
                type: array
                items: { $ref: '#/components/schemas/SessionRow' }
    FlatSessionList:
      type: object
      properties:
        sessions:
          type: array
          items: { $ref: '#/components/schemas/SessionRow' }
    SessionRow:
      type: object
      properties:
        id: { type: string }
        summary: { type: string }
        message_count: { type: integer }
        modified_at: { type: string, format: date-time }
        git_branch: { type: string }
        cwd: { type: string }
        custom_title: { type: string }
        first_prompt: { type: string }
        active:
          type: boolean
          description: True for the current TUI session
        headless_open:
          type: boolean
          description: True when routable right now via metadata.session_id without an open round-trip
    OpenedSession:
      type: object
      properties:
        session_id: { type: string }
        project_path: { type: string }
        resumed:
          type: boolean
          description: True when the session was restored from the on-disk transcript
        headless:
          type: boolean
          description: Always true for gateway-opened sessions
    MessageSnapshot:
      type: object
      description: The authoritative current message list of one session (snapshot-first)
      properties:
        session_id: { type: string }
        messages:
          type: array
          description: User text rows and assistant content[] rows, transcript order; both kinds stamp `time` (epoch ms) for their clock labels
          items: { $ref: '#/components/schemas/AssistantMessageSnapshot' }
    AssistantMessageSnapshot:
      type: object
      description: Assistant-message snapshot shape
      properties:
        id: { type: string }
        request_id: { type: string }
        conversation_id: { type: string }
        complete: { type: boolean }
        time:
          type: integer
          description: Durable transcript timestamp as epoch ms — the turn-tail clock label fact; absent on synthetic rows
        turn:
          type: integer
          description: |
            1-based turn number this assistant row answers (a human prompt
            opens a turn). Absent on rows predating the turn annotation.
        turn_usage:
          allOf: [ { $ref: '#/components/schemas/TurnUsage' } ]
          description: This row's provider-reported token buckets; absent when the row carries no usage
        content:
          type: array
          items: { $ref: '#/components/schemas/MessageContentBlock' }
        text:
          type: string
          description: A user row's text, when it carries any (this schema also serves the user-row shape)
        images:
          type: array
          items: { $ref: '#/components/schemas/MessageImageAttachment' }
          description: Inline image attachments on a user row; absent when none
    MessageImageAttachment:
      type: object
      required: [media_type, data]
      description: One inline image, the same shape the client submits attachments in
      properties:
        media_type: { type: string, description: 'e.g. image/png, image/jpeg' }
        data: { type: string, description: Base64-encoded image bytes }
    TurnUsage:
      type: object
      description: |
        Per-turn provider token buckets, raw integers. On the snapshot path
        the row's own usage buckets; on the live turn.completed frame the
        durable-fold delta between the turn's start baseline and the fold
        after endTurn (so every step of the turn is counted exactly once).
        Display formatting is client-side.
      required:
        - uncached_input_tokens
        - output_tokens
        - cache_write_tokens
        - cache_read_tokens
        - total_tokens
      properties:
        model:
          type: string
          description: |
            The model id the turn's stream last reported (Assistant message
            model field); the usage dialog's model-route row. Absent when the
            stream never reported a model (live frame path) or the snapshot
            row carries no attribution.
        uncached_input_tokens:
          type: integer
          description: Provider input tokens (the uncached bucket)
        output_tokens:
          type: integer
        cache_write_tokens:
          type: integer
          description: Cache-creation input tokens
        cache_read_tokens:
          type: integer
          description: Cache-read input tokens
        total_tokens:
          type: integer
          description: Billed input buckets (uncached + cache write + cache read) plus output
    MessageContentBlock:
      oneOf:
        - type: object
          properties:
            type: { type: string, enum: [text] }
            text: { type: string }
        - type: object
          properties:
            type: { type: string, enum: [thinking] }
            thinking: { type: string }
        - type: object
          description: Tool call content entry
          properties:
            type: { type: string, enum: [tool_call] }
            tool:
              type: object
              properties:
                tool_use_id: { type: string }
                name: { type: string }
                args: { type: object, additionalProperties: true }
                status:
                  type: string
                  enum: [pending, stream_executing, executed, failed, cancelled, skipped]
                result: { $ref: '#/components/schemas/ToolResult' }
                ready: { type: boolean }
    ToolResult:
      type: object
      description: |
        Typed per tool family. The type discriminator is mapped from the tool
        name remembered at tool.started: Bash -> execute_command_tool_result,
        Read -> read_file_tool_result, Write -> write_to_file_tool_result,
        Edit/NotebookEdit -> replace_in_file_tool_result,
        Agent/Task -> task_tool_result, anything else or unknown ->
        tool_result. Non-text blocks (images) are not projected.
      properties:
        type:
          type: string
          description: 'e.g. execute_command_tool_result, read_file_tool_result, task_tool_result'
        data:
          type: string
          description: |
            Tool-family specific payload (stdout, file content, diff): every
            text block of the result, concatenated and bounded at 20000 chars
            with a trailing "…[truncated]" marker. The mirror is a rendering
            channel, so the on-disk transcript stays the source of truth for
            full output.
        message: { type: string }
        errorMessage:
          type: string
          description: Present only when status is failed; carries the same text as data
        errorCode:
          type: string
          description: 'Present only when status is failed (tool_error)'
        transcript_path:
          type: string
          description: Sidechain transcript of a completed sub-agent tool (Agent/Task family only)
        locations:
          type: array
          items: { type: string }
          nullable: true
          description: File path(s) produced by a Write/Edit/NotebookEdit tool call
    MirrorFrame:
      type: object
      description: |
        One frame of GET /api/events. On the wire the SSE `event:` field
        carries event, `id:` carries id (the monotonic journal cursor a client
        replays through Last-Event-ID), and `data:` carries the data body.
        Every body carries session_id so a multi-session client can route the
        frame to the right conversation view.

        A reconnect is snapshot-first: pull
        GET /api/sessions/{id}/messages for authoritative state, then take the
        delta from the cursor. The mirror is a rendering channel, so no client
        depends on having missed no frame.
      required: [event, id, data]
      properties:
        event:
          type: string
          enum:
            - session.activated
            - turn.started
            - output.text
            - output.thinking
            - tool.started
            - tool.progress
            - tool.completed
            - turn.completed
            - turn.cancelled
            - session.error
            - session.idle
            - permission.asked
            - permission.resolved
        id:
          type: integer
          format: int64
          description: Monotonic journal cursor; bounded ring replay via Last-Event-ID
        data:
          oneOf:
            - $ref: '#/components/schemas/FrameSessionActivated'
            - $ref: '#/components/schemas/FrameTurnStarted'
            - $ref: '#/components/schemas/FrameOutputText'
            - $ref: '#/components/schemas/FrameOutputThinking'
            - $ref: '#/components/schemas/FrameToolStarted'
            - $ref: '#/components/schemas/FrameToolProgress'
            - $ref: '#/components/schemas/FrameToolCompleted'
            - $ref: '#/components/schemas/FrameTurnCompleted'
            - $ref: '#/components/schemas/FrameSessionError'
            - $ref: '#/components/schemas/FrameSessionOnly'
            - $ref: '#/components/schemas/PermissionAsk'
            - $ref: '#/components/schemas/FramePermissionResolved'
    FrameSessionActivated:
      type: object
      description: The active session switched; mirrors rebind to the new id
      required: [id, message_count, origin, session_id]
      properties:
        id: { type: string, description: The activated session id (same value as session_id) }
        summary: { type: string }
        message_count: { type: integer }
        modified_at: { type: string, format: date-time }
        origin: { type: string }
        session_id: { type: string }
    FrameTurnStarted:
      type: object
      required: [display_text, permission_mode, origin, session_id]
      properties:
        display_text: { type: string, description: The prompt as echoed in the transcript }
        permission_mode: { type: string }
        origin: { type: string }
        time: { type: integer, format: int64, description: The user row's leading clock, epoch ms }
        session_id: { type: string }
        images:
          type: array
          items: { $ref: '#/components/schemas/MessageImageAttachment' }
          description: Inline image attachments pasted into this turn, chip-id order; absent when none
    FrameOutputText:
      type: object
      required: [content, session_id]
      properties:
        content: { type: string, description: One whole text block, never a delta }
        synthetic:
          type: boolean
          description: A System-message projection rather than model output
        message_id:
          type: string
          description: |
            The owning assistant step's identity — the same value the snapshot
            path serves as its assistant entry id. One assistant message
            becomes one frame per content block, so consecutive frames sharing
            this id reassemble into one assistant row. Without it a client
            cannot separate a turn's tool steps from its final answer.
            Absent on synthetic System text, which has no step of its own.
        session_id: { type: string }
    FrameOutputThinking:
      type: object
      required: [content, session_id]
      properties:
        content: { type: string, description: One whole thinking block, never a delta }
        message_id: { type: string, description: The owning assistant step's identity }
        session_id: { type: string }
    FrameToolStarted:
      type: object
      required: [name, tool_use_id, session_id]
      properties:
        name: { type: string }
        tool_use_id: { type: string }
        input: { type: object, additionalProperties: true, description: The complete tool args }
        message_id: { type: string, description: The owning assistant step's identity }
        session_id: { type: string }
    FrameToolProgress:
      type: object
      description: |
        A running tool's process channel — for the Agent/Task family this is
        the sub-agent's live output, keyed by tool_use_id; agent_id doubles as
        the sidechain transcript key.
      required: [kind, session_id]
      properties:
        tool_use_id: { type: string }
        kind: { type: string }
        agent_id: { type: string }
        prompt: { type: string }
        progress: { type: integer }
        message: { type: string }
        content: { type: string }
        session_id: { type: string }
    FrameToolCompleted:
      type: object
      required: [status, tool_use_id, result, session_id]
      properties:
        status: { type: string, enum: [completed, failed] }
        tool_use_id: { type: string }
        result: { $ref: '#/components/schemas/ToolResult' }
        session_id: { type: string }
    FrameTurnCompleted:
      type: object
      required: [done, elapsed_ms, user_cancel, session_id]
      properties:
        done: { type: boolean }
        elapsed_ms: { type: integer, format: int64, description: Turn wall time }
        user_cancel: { type: boolean }
        ttft_ms:
          type: integer
          format: int64
          description: Time to first stream output; absent when the turn produced none
        time: { type: integer, format: int64, description: The turn tail's trailing clock, epoch ms }
        turn:
          type: integer
          description: |
            1-based turn number, present when the metrics reader is wired (a
            live addressable engine). The stable key joining this live row to
            the snapshot path's per-row turn field.
        turn_usage: { $ref: '#/components/schemas/TurnUsage' }
        session_id: { type: string }
    FrameSessionError:
      type: object
      required: [message, session_id]
      properties:
        message: { type: string }
        session_id: { type: string }
    FrameSessionOnly:
      type: object
      description: Body of session.idle and turn.cancelled — no facts beyond the routing id
      required: [session_id]
      properties:
        session_id: { type: string }
    FramePermissionResolved:
      type: object
      required: [request_id, resolution, origin, session_id]
      properties:
        request_id: { type: string }
        resolution: { type: string, enum: [allowed, denied] }
        origin:
          type: string
          enum: [tui, web]
          description: Which observer answered first
        feedback: { type: string }
        session_id: { type: string }
    PermissionAsk:
      type: object
      description: |
        Body of the permission.asked frame: one tool waiting at ASK inside the
        shared interaction coordinator. The TUI dialog and every web client are
        observers of the same ask — first answer wins, and permission.resolved
        reports which origin got there.
      required: [request_id, tool, session_id]
      properties:
        request_id:
          type: string
          description: The id POST /api/permissions/respond answers (not tool_use_id)
        tool: { type: string }
        tool_use_id: { type: string }
        input: { type: object, additionalProperties: true }
        decision_reason_type: { type: string }
        decision_reason_detail: { type: string }
        suggestion_rule_content: { type: string }
        suggestion_label: { type: string }
        destructive_warning: { type: string }
        blocked_path: { type: string }
        custom_message: { type: string }
        tool_description: { type: string }
        questions:
          type: array
          description: AskUserQuestion definitions only; absent for every other tool
          items:
            type: object
            required: [question, multi_select, options]
            properties:
              question: { type: string }
              header: { type: string }
              multi_select: { type: boolean }
              options:
                type: array
                items:
                  type: object
                  required: [label]
                  properties:
                    label: { type: string }
                    description: { type: string }
        session_id: { type: string }
    SettingsSnapshot:
      type: object
      description: Merged effective settings plus per-tier source attribution
      properties:
        effective:
          type: object
          additionalProperties: true
          description: |
            The merged settings object (user -> project -> local -> flag ->
            policy, later tiers override earlier). Keys are loosely typed
            camelCase scalars (e.g. alwaysThinkingEnabled) plus a nested
            permissions object.
          properties:
            permissions:
              type: object
              properties:
                defaultMode: { type: string, nullable: true }
                disableBypassPermissionsMode: { type: string, nullable: true }
                allow: { type: array, items: { type: string } }
                deny: { type: array, items: { type: string } }
                ask: { type: array, items: { type: string } }
                additionalDirectories: { type: array, items: { type: string } }
        sources:
          type: array
          items: { $ref: '#/components/schemas/SettingsSource' }
    SettingsSource:
      type: object
      required: [source, settings]
      properties:
        source:
          type: string
          enum: [userSettings, projectSettings, localSettings, flagSettings, policySettings]
        settings:
          type: object
          additionalProperties: true
          description: The raw (pre-merge) settings object for this tier
    SettingsTier:
      type: string
      enum: [user, project, local]
    UserValueOp:
      type: object
      required: [op, key]
      properties:
        op: { type: string, enum: [userValue] }
        key: { type: string }
        value:
          description: Any JSON value; absent or null removes the key
    PermissionModeOp:
      type: object
      required: [op, tier]
      properties:
        op: { type: string, enum: [permissionMode] }
        mode:
          type: string
          nullable: true
          description: null removes the tier's permissions.defaultMode override
        tier: { $ref: '#/components/schemas/SettingsTier' }
    PermissionRulesOp:
      type: object
      required: [op, behavior, tier]
      properties:
        op: { type: string, enum: [permissionRules] }
        behavior: { type: string, enum: [allow, deny, ask] }
        rules:
          type: array
          items: { type: string }
          default: []
          description: Replaces this behavior's whole rule array for the tier
        tier: { $ref: '#/components/schemas/SettingsTier' }
    DirectoriesOp:
      type: object
      required: [op, tier]
      properties:
        op: { type: string, enum: [addDirectories, removeDirectories] }
        directories:
          type: array
          items: { type: string }
          default: []
        tier: { $ref: '#/components/schemas/SettingsTier' }
    ScheduleList:
      type: object
      properties:
        tasks:
          type: array
          items: { $ref: '#/components/schemas/ScheduleTask' }
    ScheduleTask:
      type: object
      required: [id, cron, prompt, recurring, durable, created_at]
      properties:
        id: { type: string }
        cron: { type: string }
        prompt: { type: string }
        recurring: { type: boolean }
        durable: { type: boolean }
        created_at: { type: integer, format: int64 }
        last_fired_at: { type: integer, format: int64, nullable: true }
        kind: { type: string, nullable: true }
        agent_id: { type: string, nullable: true }
        created_by_session_id: { type: string, nullable: true }
        model:
          type: string
          nullable: true
          description: Per-task model override applied at fire time; absent keeps the session model
    ScheduleCreateRequest:
      type: object
      required: [cron, prompt]
      properties:
        cron: { type: string, description: Standard 5-field cron expression }
        prompt: { type: string }
        recurring: { type: boolean, default: false }
        durable: { type: boolean, default: false }
        model:
          type: string
          nullable: true
          description: Optional per-task model override; absent keeps the session model at fire time
    ModelList:
      type: object
      properties:
        models:
          type: array
          items: { $ref: '#/components/schemas/ModelEntry' }
    CommandList:
      type: object
      properties:
        commands:
          type: array
          items: { $ref: '#/components/schemas/CommandEntry' }
    ContextTimelineHead:
      type: object
      description: |
        dsh-context `ContextTimeline` (shared/types.ts), camelCase on the
        wire: `current` composition, `counts`, `last`, `detailRev`, `cost`,
        `timing`, `systems`, plus this product's `running` flag. The
        collections (`requests`, `events`, `nodes`, `archive`) are always
        empty here — they ride the detail route.
      additionalProperties: true
      required: [ok, current, detailRev]
      properties:
        ok: { type: boolean }
        model: { type: string }
        provider: { type: string }
        contextWindow: { type: integer }
        current:
          type: object
          properties:
            system: { type: integer }
            tools: { type: integer }
            user: { type: integer }
            inject: { type: integer }
            skill: { type: integer }
            assistant: { type: integer }
            tool: { type: integer }
            total: { type: integer }
        counts:
          type: object
          properties:
            turns: { type: integer }
            steps: { type: integer }
            injects: { type: integer }
            compactions: { type: integer }
            prunes: { type: integer }
        detailRev: { type: integer }
        running: { type: boolean }
    ContextTimelineDetail:
      type: object
      description: |
        dsh-context `ContextTimelineDetail` plus `headers` (`ContextHeaders`)
        and this product's `agents[]` (Task/Agent tool calls of the session).
      additionalProperties: true
      required: [rev, requests, events, nodes, droppedNodes, archive]
      properties:
        rev: { type: integer }
        head: { $ref: '#/components/schemas/ContextTimelineHead' }
        requests: { type: array, items: { type: object, additionalProperties: true } }
        events: { type: array, items: { type: object, additionalProperties: true } }
        nodes: { type: array, items: { type: object, additionalProperties: true } }
        droppedNodes: { type: integer }
        archive: { type: array, items: { type: object, additionalProperties: true } }
        fileOps: { type: array, items: { type: object, additionalProperties: true } }
        headers: { type: object, additionalProperties: true }
        agents: { type: array, items: { type: object, additionalProperties: true } }
    ContextOverview:
      type: object
      required: [sessions, time]
      properties:
        time: { type: integer, description: Server epoch milliseconds }
        sessions:
          type: array
          items:
            type: object
            required: [id, running, timeline, activity]
            properties:
              id: { type: string }
              title: { type: string }
              cwd: { type: string }
              running: { type: boolean }
              updatedAt: { type: integer }
              timeline: { $ref: '#/components/schemas/ContextTimelineHead' }
              activity:
                type: object
                description: dsh-context `ContextActivity` — `days[YYYY-MM-DD] = {tokens, requests}`
                additionalProperties: true
    SessionContext:
      type: object
      properties:
        selection:
          allOf: [ { $ref: '#/components/schemas/ModelSelection' } ]
          nullable: true
        context:
          allOf: [ { $ref: '#/components/schemas/ContextUsage' } ]
          nullable: true
        metrics:
          allOf: [ { $ref: '#/components/schemas/SessionMetrics' } ]
          nullable: true
          description: |
            The addressed session's durable whole-session HUD fold. Null
            when the session has no live engine or its persisted event
            coverage is incomplete — a partial fold is never served as a
            session total (docs/hud-metrics-specification.md §6).
    SessionMetrics:
      type: object
      description: |
        The durable whole-log metrics fold (docs/hud-metrics-specification.md).
        Counts fold from the persisted event log; paging, compaction, and
        the visible window cannot change them. Raw integers — display
        formatting (compact tokens, percent, tok/s, durations) is
        client-side.
      required:
        - turns
        - steps
        - llm_ms
        - tool_ms
        - ttft_ms
        - ttft_steps
        - decode_ms
        - decode_tokens
        - uncached_input_tokens
        - output_tokens
        - cache_write_tokens
        - cache_read_tokens
      properties:
        turns:
          type: integer
          description: Distinct turn numbers with at least one closed step
        steps:
          type: integer
          description: Steps counted on step/end (completed, failed, cancelled, max-token steps all count)
        llm_ms:
          type: integer
          description: Summed step/start → assistant/message wall time over steps that assembled an assistant message
        tool_ms:
          type: integer
          description: Summed matched tool/call → tool/result durations; parallel durations sum and may exceed wall time
        ttft_ms:
          type: integer
          description: Summed step/start → first token over ttft_steps
        ttft_steps:
          type: integer
          description: Steps carrying a recorded TTFT; TTFT avg = ttft_ms / ttft_steps
        decode_ms:
          type: integer
          description: Summed first token → assistant/message over steps that also sample output tokens
        decode_tokens:
          type: integer
          description: Summed output tokens over the same sampled steps; tok/s = decode_tokens / (decode_ms / 1000)
        uncached_input_tokens:
          type: integer
        output_tokens:
          type: integer
        cache_write_tokens:
          type: integer
        cache_read_tokens:
          type: integer
    ModelSelection:
      type: object
      required: [current, models]
      properties:
        current: { type: string }
        models:
          type: array
          items: { $ref: '#/components/schemas/ModelChoice' }
        effort:
          type: object
          description: Present only when the model advertises reasoning effort levels
          required: [current, effective, choices]
          properties:
            current:
              type: string
              description: |
                The configured selection, or "auto" when nothing is set. May be
                "ultracode", which is a session-scoped pseudo-level rather than a
                wire value; it is never persisted.
            effective:
              type: string
              description: |
                The real level the request carries. Always one of the wire levels —
                an "ultracode" selection reports "xhigh" here, which is the level it
                folds to before reaching the model.
            choices:
              type: array
              description: |
                Selectable values: "auto" followed by the model's supported levels,
                plus "ultracode" when dynamic-workflow orchestration is available and
                the model and organization allow xhigh.
              items: { type: string }
    ModelChoice:
      type: object
      required: [name, label, default]
      properties:
        name: { type: string }
        label: { type: string }
        description: { type: string }
        default:
          type: boolean
          description: Marks the "default" row that resets the session to the launch model
    ContextUsage:
      type: object
      required: [model, context_window]
      properties:
        model: { type: string }
        context_window:
          type: integer
          description: The model-resolved window size (200k default, 1M for [1m]/opus-5, 372k for GPT 5.6)
        used_tokens:
          type: integer
          description: Present once a finalized API usage anchor exists; input-token sum per claude-hud accounting
        used_percentage:
          type: integer
          minimum: 0
          maximum: 100
          description: used_tokens * 100 / context_window, clamped
        breakdown:
          type: object
          description: |
            The heuristic composition split (dsh's contextBreakdown): token
            counts from the TUI /context analyzer's category accounting.
            Present only while an analyzer is wired; the meter then renders
            the single-reading form.
          required: [system_tokens, tools_tokens, message_tokens]
          properties:
            system_tokens:
              type: integer
              description: System prompt + memory files + custom agents + skills
            tools_tokens:
              type: integer
              description: Built-in + MCP tool definitions
            message_tokens:
              type: integer
              description: Conversation messages
    SessionContextSelectRequest:
      type: object
      properties:
        session_id:
          type: string
          description: The session to address; absent means the active TUI session
        model:
          type: string
          description: The model name to apply (a ModelChoice name)
        effort:
          type: string
          description: |
            The effort level to apply ("auto" clears the override). Must be one of
            the values the session's effort.choices currently offers, which includes
            "ultracode" when dynamic workflows are available; anything else is 400.
      description: Exactly one of model or effort must be present
    SessionPermissionModeResponse:
      type: object
      properties:
        permission_mode:
          allOf: [ { $ref: '#/components/schemas/SessionPermissionMode' } ]
          nullable: true
    SessionPermissionMode:
      type: object
      required: [current, modes, bypass_permissions_available, bypass_permissions_disabled_by_policy]
      properties:
        current: { type: string }
        modes:
          type: array
          items: { $ref: '#/components/schemas/PermissionModeChoice' }
        bypass_permissions_available:
          type: boolean
          description: False when the process was not launched with --dangerously-skip-permissions, or policy disabled it
        bypass_permissions_disabled_by_policy:
          type: boolean
          description: Distinguishes a policy-disabled bypassPermissions from a launch-flag-gated one
    PermissionModeChoice:
      type: object
      required: [value, title, short_title, symbol, color_key, available]
      properties:
        value:
          type: string
          enum: [default, plan, acceptEdits, bypassPermissions, dontAsk]
        title: { type: string }
        short_title: { type: string }
        symbol: { type: string }
        color_key: { type: string }
        available:
          type: boolean
          description: False only for bypassPermissions when unavailable; every other mode is always available
    SessionPermissionModeSelectRequest:
      type: object
      required: [mode]
      properties:
        session_id:
          type: string
          description: The session to address; absent means the active TUI session
        mode:
          type: string
          enum: [default, plan, acceptEdits, bypassPermissions, dontAsk]
    CommandEntry:
      type: object
      required: [name, kind]
      properties:
        name: { type: string }
        description: { type: string }
        argument_hint: { type: string }
        kind:
          type: string
          enum: [command, skill]
          description: skill rows are skill files projected into the command registry
    ModelEntry:
      type: object
      required: [model_name, protocol, base_url, has_api_key]
      properties:
        model_name: { type: string }
        protocol: { type: string, enum: [anthropic, chat, responses] }
        base_url: { type: string }
        has_api_key:
          type: boolean
          description: True when a key is configured; the key itself is never echoed
        headers:
          type: object
          additionalProperties: { type: string }
        context_window: { type: integer, nullable: true }
        multimodal:
          type: boolean
          nullable: true
          description: Null = unconfigured (assume multimodal); false marks a text-only endpoint whose image content routes to the configured image model
    ModelSaveRequest:
      type: object
      required: [model_name, protocol, base_url]
      properties:
        model_name: { type: string }
        protocol: { type: string, enum: [anthropic, chat, responses] }
        base_url: { type: string }
        api_key:
          type: string
          nullable: true
          description: Absent keeps the existing key, null clears it, a string sets it
        headers:
          type: object
          additionalProperties: { type: string }
        context_window: { type: integer, nullable: true }
        multimodal:
          type: boolean
          nullable: true
          description: Absent keeps the existing flag, false marks the endpoint text-only
  parameters:
    ContextSessionId:
      name: session_id
      in: query
      required: false
      schema: { type: string }
      description: The live session to address; absent means the active TUI session
  responses:
    InvalidRequest:
      description: Malformed request
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing launch token
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    UnknownSession:
      description: No session matches the id
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NoActiveSession:
      description: No metadata.session_id and no active session
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    SessionBusy:
      description: A turn is already in flight on this session, or the headless limit is reached
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: No resource matches the id
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    SessionOperationFailed:
      description: |
        The session exists and the operation failed on it — a full disk or an
        unwritable transcript, not a missing row. Deliberately distinct from
        404: the message names the underlying failure so a client can tell the
        user their conversation is intact but could not be written.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }