# Daemon protocol 3. See http-api-design.md for behavioral semantics.
openapi: 3.2.1
info:
  title: Albedo daemon API
  version: 3.0.0
  summary: 'Protocol 3: typed HTTP resources and SSE.'
  description: This file owns daemon request and response shapes.
    http-api-design.md owns ordering, atomicity, retry and recovery behavior. Server and clients switch
    together; there are no legacy route aliases. Unknown request fields and duplicate JSON keys are errors.
    Unknown response fields may be ignored by clients. No operation starts or replaces a daemon. JSON
    and SSE frames are at most 1 MiB unless an extension explicitly overrides that limit. Ordinary request
    bodies are at most 64 KiB, input bodies 72,200,000 bytes and proxy bodies 32,000,000 bytes. UTF-8 and
    encoded-byte limits are described with x-max-utf8-bytes/x-max-encoded-bytes; standard schema validation
    alone does not assert them. Examples use synthetic secrets only. JSON and text responses of at least
    1 KiB, and session event streams, use Content-Encoding zstd when Accept-Encoding admits it; limits
    and ETags apply to the decoded representation. When capabilities include zstd_requests, a request
    body may use Content-Encoding zstd as one frame that declares its decoded size.
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
externalDocs:
  description: Behavior, ownership, feature coverage and verification.
  url: http-api-design.md
security:
- DaemonBearer: []
tags:
- name: server
- name: settings
- name: storage
- name: sessions
- name: models
- name: workspaces
- name: hosts
- name: auth
- name: work
- name: paperclips
- name: web-search
- name: schedule
- name: links
- name: webhooks
- name: proxy
paths:
  /server:
    get:
      operationId: getServer
      summary: Read daemon identity and capabilities
      tags:
      - server
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'
              examples:
                Server:
                  value:
                    instance_id: instance-1
                    protocol: 3
                    state: ready
                    capabilities:
                      durable_inputs: 1
                      session_replay: 1
                      collection_invalidation: 1
                      tool_progress: 1
                      storage_report: 1
                    build: example-build
                    digest: null
                    extensions:
                    - name: work
                      version: 1
                    quota: null
                    notices: []
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: No startup or replacement. Authentication and protocol failures remain actionable errors.
        Pagination is valid only with include=quota_history.
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum: [quota_history]
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
      - name: quota_provider
        in: query
        required: false
        description: Exact provider ID to filter quota history. Requires include=quota_history, quota_account, and quota_limit.
        schema:
          type: string
      - name: quota_account
        in: query
        required: false
        description: Exact account label to filter quota history. Requires include=quota_history, quota_provider, and quota_limit.
        schema:
          type: string
      - name: quota_limit
        in: query
        required: false
        description: Exact limit ID to filter quota history. Requires include=quota_history, quota_provider, and quota_account.
        schema:
          type: string
      - name: quota_since
        in: query
        required: false
        description: Filter quota history to observations at or after this RFC 3339 UTC timestamp. Requires include=quota_history and the limit filter trio.
        schema:
          $ref: '#/components/schemas/Timestamp'
  /server/shutdown:
    post:
      operationId: shutdownServer
      summary: Drain the identified daemon
      tags:
      - server
      responses:
        '202':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shutdown'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '409':
          $ref: '#/components/responses/Problem409'
      description: No automatic recovery or replay. The local launcher alone may offer replacement.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShutdownRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /settings:
    get:
      operationId: getSettings
      summary: Read shared settings or one canonical group
      tags:
      - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsRead'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Without group, return Settings and observed group validators. With group, return that
        group only; the ETag covers that representation.
      parameters:
      - name: group
        in: query
        required: false
        schema:
          type: string
          enum: [providers, mcp, extensions, capabilities, models, ui]
    patch:
      operationId: patchSettings
      summary: Atomically edit one settings group
      tags:
      - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Query group selects its corresponding schema. Omitted fields keep values. Null removes
        only nullable fields or map entries. Candidate validation precedes the complete group commit.
        No lost-response retry.
      parameters:
      - name: group
        in: query
        required: true
        schema:
          type: string
          enum: [providers, mcp, extensions, capabilities, models, ui]
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SettingsPatch'
            examples:
              ProviderSettingsPatch:
                value:
                  default_profile: personal
                  profiles:
                    personal:
                      extension: openai
                      endpoint: https://provider.example/v1
                      protocol: responses
                      model: example-model
                      effort: null
                      image_edge: null
                      account_id: null
                      project: null
                      location: null
                      api_key: synthetic-example-key
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /storage:
    get:
      operationId: getStorage
      summary: Read storage accounting
      tags:
      - storage
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageReport'
              examples:
                StorageReport:
                  value:
                    database:
                      main_file_bytes: 8192
                      wal_bytes: 0
                      page_size_bytes: 4096
                      page_count: 2
                      free_page_count: 0
                      used_bytes: 8192
                    sessions:
                      items: []
                      next: null
                      total_count: 0
                      total_estimated_content_bytes: 0
                    images:
                      count: 0
                      bytes: 0
                    files:
                      items: []
                      next: null
                      totals:
                        kernel_bytes: 0
                        backup_bytes: 0
                        other_bytes: 0
                        recent_backup_bytes: 0
                        recent_backup_count: 0
                    measured_at: '2026-10-02T14:00:00Z'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: 'Each section has its own continuation. Totals cover complete storage. Paths never
        authorize local mutation. Requires capability `storage_report: 1`.'
      parameters:
      - name: sessions_next
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PageToken'
      - name: files_next
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PageToken'
      - $ref: '#/components/parameters/Limit'
  /sessions:
    get:
      operationId: listSessions
      summary: Browse sessions or watch collection changes
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPage'
              examples:
                SessionPage:
                  value:
                    items:
                    - id: 01a0fcea-2b00-7000-8000-000000000001
                      name: New session
                      automatic_name: New session
                      workspace: /workspace/project
                      location:
                        host: null
                        user: null
                        path: /workspace/project
                        label: null
                      parent_id: null
                      root_id: 01a0fcea-2b00-7000-8000-000000000001
                      address: null
                      depth: 0
                      closed: false
                      created_at: '2026-10-02T14:00:00Z'
                      activity_at: '2026-10-02T14:00:00Z'
                      provider_profile: personal
                      model: example-model
                      effort: null
                      status:
                        phase: idle
                        run_id: null
                        interrupt_requested: false
                        blocking_reason: null
                      preview:
                        text: ''
                        transcript_count: 0
                        truncated: false
                      preferences:
                        pinned: false
                        pin_order: null
                        archived: false
                        opens: 0
                      current_progress: []
                      active_output: []
                      activity:
                        lines: []
                        output_scalars: 0
                        output_utf8_bytes: 0
                        observed_at: '2026-10-02T14:00:00Z'
                        latest_input: null
                        latest_answer: null
                      cursor:
                        generation: J6kYj6IGcXyP3eMIp-WL3A
                        sequence: 0
                    next: null
            text/event-stream:
              itemSchema:
                $ref: '#/components/schemas/CollectionSSE'
          headers:
            Vary:
              $ref: '#/components/headers/Vary'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: JSON defaults to roots, or all with parent/family. Parent and family are exclusive.
        Explicit roots with either is invalid. SSE accepts the same scope filters, excluding sort/limit/next;
        no cursor or replay. Subscribe, wait for ready, then read pages. Closure or overflow repeats this
        flow.
      parameters:
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum: [roots, all]
      - name: parent_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: family_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: workspace
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: search
        in: query
        required: false
        schema:
          type: string
          maxLength: 256
      - name: archived
        in: query
        required: false
        schema:
          type: boolean
      - name: needs_reload
        in: query
        required: false
        schema:
          type: boolean
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum: [activity, frequent]
          default: activity
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
  /sessions/{session_id}:
    get:
      operationId: getSession
      summary: Read or watch one session
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Vary:
              $ref: '#/components/headers/Vary'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRead'
              examples:
                Session:
                  value:
                    id: 01a0fcea-2b00-7000-8000-000000000001
                    name: New session
                    automatic_name: New session
                    workspace: /workspace/project
                    location:
                      host: null
                      user: null
                      path: /workspace/project
                      label: null
                    parent_id: null
                    root_id: 01a0fcea-2b00-7000-8000-000000000001
                    address: null
                    depth: 0
                    closed: false
                    created_at: '2026-10-02T14:00:00Z'
                    activity_at: '2026-10-02T14:00:00Z'
                    provider_profile: personal
                    model: example-model
                    effort: null
                    status:
                      phase: idle
                      run_id: null
                      interrupt_requested: false
                      blocking_reason: null
                    preview:
                      text: ''
                      transcript_count: 0
                      truncated: false
                    preferences:
                      pinned: false
                      pin_order: null
                      archived: false
                      opens: 0
                    current_progress: []
                    active_output: []
                    activity:
                      lines: []
                      output_scalars: 0
                      output_utf8_bytes: 0
                      observed_at: '2026-10-02T14:00:00Z'
                      latest_input: null
                      latest_answer: null
                    cursor:
                      generation: J6kYj6IGcXyP3eMIp-WL3A
                      sequence: 0
                    creation:
                      submitted:
                        kind: new
                        workspace: /workspace/project
                        name: null
                        provider_profile: null
                        model: null
                        effort: null
                      resolved:
                        workspace: /workspace/project
                        provider_profile: personal
                        model: example-model
                        effort: null
                    revision: config-1
                    family_revision: family-1
                    configuration_resource:
                      url: /sessions/01a0fcea-2b00-7000-8000-000000000001?view=configuration
                      etag: '"session-config-1"'
                      value:
                        id: 01a0fcea-2b00-7000-8000-000000000001
                        name: New session
                        workspace: /workspace/project
                        provider_profile: personal
                        model: example-model
                        effort: null
                        preferences:
                          pinned: false
                          pin_order: null
                          archived: false
                        selection:
                          extensions: {}
                          skills: {}
                          instructions: {}
                          mcp: {}
                        revision: config-1
                        family_revision: family-1
                    workspace_change: null
                    selection:
                      overrides:
                        extensions: {}
                        skills: {}
                        instructions: {}
                        mcp: {}
                      effective:
                        extensions: {}
                        skills: {}
                        instructions: {}
                        mcp: {}
                    composition:
                      desired_revision: composition-1
                      loaded_revision: null
                      needs_reload: true
                      dependencies: {}
                      quarantine: []
                      availability: {}
                    kernel:
                      instance_id: null
                      state: none
                      stage: null
                      build: null
                      stale: false
                      staleness_reasons: []
                      live_job_count: 0
                      running_jobs: []
                    pending_inputs: []
                    input_order: 0
                    usage:
                      model: null
                      observed_at: null
                      prompt_tokens: null
                      cached_prompt_tokens: null
                      cache_write_tokens: null
                      completion_tokens: null
                      total_tokens: null
                      elapsed_ms: null
                      tokens_per_second: null
                      context_window_tokens: null
                      cache_ttl_seconds: null
                      cache_fade: []
                    history:
                      items: []
                      older: null
                      newer: null
                      high_water: 0
                    glances: []
            text/event-stream:
              itemSchema:
                $ref: '#/components/schemas/SessionSSE'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: JSON defaults to complete Session. Configuration JSON excludes tail and replay parameters.
        SSE accepts tail and after_generation/after_seq, without view. Initial subscription omits both
        cursors; reconnect keeps the fully consumed pair. A missing generation requests reset. after_generation
        without after_seq is invalid. Neither auth failure nor closure starts a daemon.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [configuration]
      - name: tail
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 200
          default: 100
      - name: after_generation
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Generation'
      - name: after_seq
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Counter'
    put:
      operationId: createSession
      summary: Create a new, forked or child session
      tags:
      - sessions
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              examples:
                Session:
                  value:
                    id: 01a0fcea-2b00-7000-8000-000000000001
                    name: New session
                    automatic_name: New session
                    workspace: /workspace/project
                    location:
                      host: null
                      user: null
                      path: /workspace/project
                      label: null
                    parent_id: null
                    root_id: 01a0fcea-2b00-7000-8000-000000000001
                    address: null
                    depth: 0
                    closed: false
                    created_at: '2026-10-02T14:00:00Z'
                    activity_at: '2026-10-02T14:00:00Z'
                    provider_profile: personal
                    model: example-model
                    effort: null
                    status:
                      phase: idle
                      run_id: null
                      interrupt_requested: false
                      blocking_reason: null
                    preview:
                      text: ''
                      transcript_count: 0
                      truncated: false
                    preferences:
                      pinned: false
                      pin_order: null
                      archived: false
                      opens: 0
                    current_progress: []
                    active_output: []
                    activity:
                      lines: []
                      output_scalars: 0
                      output_utf8_bytes: 0
                      observed_at: '2026-10-02T14:00:00Z'
                      latest_input: null
                      latest_answer: null
                    cursor:
                      generation: J6kYj6IGcXyP3eMIp-WL3A
                      sequence: 0
                    creation:
                      submitted:
                        kind: new
                        workspace: /workspace/project
                        name: null
                        provider_profile: null
                        model: null
                        effort: null
                      resolved:
                        workspace: /workspace/project
                        provider_profile: personal
                        model: example-model
                        effort: null
                    revision: config-1
                    family_revision: family-1
                    configuration_resource:
                      url: /sessions/01a0fcea-2b00-7000-8000-000000000001?view=configuration
                      etag: '"session-config-1"'
                      value:
                        id: 01a0fcea-2b00-7000-8000-000000000001
                        name: New session
                        workspace: /workspace/project
                        provider_profile: personal
                        model: example-model
                        effort: null
                        preferences:
                          pinned: false
                          pin_order: null
                          archived: false
                        selection:
                          extensions: {}
                          skills: {}
                          instructions: {}
                          mcp: {}
                        revision: config-1
                        family_revision: family-1
                    workspace_change: null
                    selection:
                      overrides:
                        extensions: {}
                        skills: {}
                        instructions: {}
                        mcp: {}
                      effective:
                        extensions: {}
                        skills: {}
                        instructions: {}
                        mcp: {}
                    composition:
                      desired_revision: composition-1
                      loaded_revision: null
                      needs_reload: true
                      dependencies: {}
                      quarantine: []
                      availability: {}
                    kernel:
                      instance_id: null
                      state: none
                      stage: null
                      build: null
                      stale: false
                      staleness_reasons: []
                      live_job_count: 0
                      running_jobs: []
                    pending_inputs: []
                    input_order: 0
                    usage:
                      model: null
                      observed_at: null
                      prompt_tokens: null
                      cached_prompt_tokens: null
                      cache_write_tokens: null
                      completion_tokens: null
                      total_tokens: null
                      elapsed_ms: null
                      tokens_per_second: null
                      context_window_tokens: null
                      cache_ttl_seconds: null
                      cache_fade: []
                    history:
                      items: []
                      older: null
                      newer: null
                      high_water: 0
                    glances: []
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
        '429':
          $ref: '#/components/responses/Problem429'
      description: Session ID must be UUIDv7. If-None-Match:* is required. Retain the identity and submitted
        intent after response loss. An existing resource returns 412; GET creation.submitted proves original
        intent. Child membership and task admission commit together.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUIDv7'
      - $ref: '#/components/parameters/IfNoneMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreationRequest'
            examples:
              NewSessionRequest:
                value:
                  kind: new
                  workspace: /workspace/project
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    patch:
      operationId: patchSession
      summary: Edit configuration or move workspace
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Use the observed configuration URL and validator. Workspace is a standalone change
        with family_revision. Busy target fails before commit; busy descendants follow a committed parent
        move at idle. Other configuration fields commit together. No automatic lost-response retry.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SessionChangeRequest'
            examples:
              SessionPatch:
                value:
                  selection:
                    extensions:
                      browser: null
                    skills:
                      candidate-1: false
                  catalog_revision: discovery-1
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: deleteSession
      summary: Delete a leaf or captured subtree
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDeletion'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Leaf requires idle and no children. Subtree requires family_revision, gates new children,
        interrupts captured members and deletes deepest first. Partial outcomes are explicit. Refresh
        before confirming a new attempt; never automatically replay after transport loss.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum: [leaf, subtree]
          default: leaf
      - name: family_revision
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
  /sessions/{session_id}/visits/{visit_id}:
    put:
      operationId: recordVisit
      summary: Count one deliberate opening
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Visit'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: Visit ID is UUIDv7. Same identity increments once; reads and refreshes never count.
      parameters:
      - name: visit_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUIDv7'
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /sessions/{session_id}/inputs/{input_id}:
    put:
      operationId: putInput
      summary: Admit immutable identified input
      tags:
      - sessions
      responses:
        '202':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Input'
              examples:
                Input:
                  value:
                    id: 01a0fcea-2b00-7000-8000-000000000002
                    session_id: 01a0fcea-2b00-7000-8000-000000000001
                    kind: message
                    admission: accepted
                    http_status: 202
                    problem: null
                    accepted_at: '2026-10-02T14:00:00Z'
                    acceptance_order: 1
                    delivery: pending
                    blocking_reason: null
                    transcript_position: null
                    turn: null
                    client_id: draft-1
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '429':
          description: Retained rejection, even if capacity later clears.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                queue_full:
                  value:
                    type: about:blank
                    title: Queue full
                    status: 429
                    detail: This session already has 32 waiting inputs.
                    code: queue_full
                    decision:
                      kind: input
                      input:
                        id: 01a0fcea-2b00-7000-8000-000000000002
                        session_id: 01a0fcea-2b00-7000-8000-000000000001
                        kind: message
                        admission: rejected
                        http_status: 429
                        problem:
                          type: about:blank
                          title: Queue full
                          status: 429
                          detail: This session already has 32 waiting inputs.
                          code: queue_full
                        accepted_at: null
                        acceptance_order: null
                        delivery: null
                        blocking_reason: null
                        transcript_position: null
                        turn: null
                        client_id: draft-1
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
      description: Input ID is UUIDv7. Duplicate lookup precedes mutable validation and returns the original
        admission status with current delivery. Queue-full rejection remains rejected. No If-None-Match.
        Preserve the exact intent and identity while recovering an uncertain response.
      parameters:
      - name: input_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUIDv7'
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputRequest'
            examples:
              MessageInputRequest:
                value:
                  kind: message
                  text: Fix the parser.
                  client_id: draft-1
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    get:
      operationId: getInput
      summary: Read a durable input outcome
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Input'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: Available after session deletion. Accepted is not consumed or answered. Retain pending
        and unfinished-turn identities; terminal decisions last seven days. Unknown old UUIDv7 returns
        410, never a fresh admission.
      parameters:
      - name: input_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
  /sessions/{session_id}/inputs/{input_id}/cancel:
    post:
      operationId: cancelInput
      summary: Cancel or interrupt only this input
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputCancellation'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: Never interrupts a later unrelated turn. shared_running leaves a shared turn running;
        retry only inspects or acts on this same input.
      parameters:
      - name: input_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /sessions/{session_id}/interrupt:
    post:
      operationId: interruptSession
      summary: Interrupt a captured run and waiting prefix
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interruption'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Capture run_id and through_input_order from the installed session. Retry cannot interrupt
        a later run or cancel newer inputs.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterruptRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /sessions/{session_id}/active-output/{content_id}:
    get:
      operationId: getActiveOutputContent
      summary: Read unfinished output at a captured snapshot cutoff
      tags:
      - sessions
      description: Pages contain at most 262144 UTF-8 bytes and remain within the captured cutoff. Preserve the required snapshot query when following next.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: content_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: snapshot
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/PageToken'
      - name: next
        in: query
        schema:
          $ref: '#/components/schemas/PageToken'
      responses:
        '200':
          description: Bounded UTF-8 content page at the signed snapshot cutoff
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryContentPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '403':
          $ref: '#/components/responses/Problem403'
        '410':
          $ref: '#/components/responses/Problem410'
        '503':
          $ref: '#/components/responses/Problem503'
  /sessions/{session_id}/history:
    get:
      operationId: getHistory
      summary: Page history or fork checkpoints
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryRead'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Use only one of before/after/next. Durable positions are independent of actor replay.
        Pages are ascending and preserve complete display groups where bounded.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [entries, checkpoints]
          default: entries
      - name: before
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Counter'
      - name: after
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Counter'
      - $ref: '#/components/parameters/Next'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 100
  /sessions/{session_id}/history/{entry_id}:
    get:
      operationId: getHistoryContent
      summary: Read full content in bounded pieces
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryContentPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Follow next until null. UTF-8 pieces end at character boundaries. Reconstruct stored
        content, not shortened previews. Image fields are not paged here; their references name the
        image resource.
      parameters:
      - name: entry_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/Next'
  /sessions/{session_id}/history/{entry_id}/{field}:
    get:
      operationId: getHistoryImage
      summary: Read one image field as its own bytes
      tags:
      - sessions
      responses:
        '200':
          description: The decoded image, typed by its MIME type.
          content:
            image/png:
              schema:
                type: string
                contentMediaType: image/png
            image/jpeg:
              schema:
                type: string
                contentMediaType: image/jpeg
            image/webp:
              schema:
                type: string
                contentMediaType: image/webp
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Image references in history point here. The body is the stored image itself,
        not base64, and is never content-coded.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: entry_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: field
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
  /sessions/{session_id}/context:
    get:
      operationId: getContext
      summary: Inspect prepared context or request records
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextRead'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: 'Summary never prepares a request. Section requires snapshot_id, section_id, page and
        forbids request-pagination fields. Requests accepts after/limit/next. Stale snapshot is 410 context_changed,
        never another section. Requires capability `context: 1`.'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [summary, section, requests]
          default: summary
      - name: snapshot_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: section_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: page
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Counter'
      - name: after
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Counter'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
  /sessions/{session_id}/catalog:
    get:
      operationId: getCatalog
      summary: Discover candidates, loaded commands and pages
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Catalog'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: 'Discovery and loaded composition are separate. Reads do not reload. Continuation identifies
        its section; candidate revision guards discovery-based selection. Requires capability `catalog:
        1`.'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum: [extensions, skills, instructions, mcp, commands]
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
  /sessions/{session_id}/reload:
    post:
      operationId: reloadSession
      summary: Reload composition, models or both
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadResult'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: Session reload requires idle. Both targets return separate outcomes, preserving confirmed
        success when the other fails. Lost-response replay is not automatic.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReloadRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /sessions/{session_id}/kernel/upgrade:
    post:
      operationId: upgradeKernel
      summary: Explicitly upgrade an idle kernel
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KernelUpgradeResult'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: Stage and validate before swap. Report external jobs stopped during an unsuccessful
        upgrade; do not claim them restored. No automatic retry.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /sessions/{session_id}/compaction:
    post:
      operationId: compactSession
      summary: Compact model context while retaining history
      tags:
      - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionResult'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: Idle required. Selecting a strategy can succeed even if compaction later fails; report
        both. Full durable history stays intact. No automatic retry.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompactionRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /models:
    get:
      operationId: listModels
      summary: Read provider model metadata
      tags:
      - models
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRead'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: In catalogue view, exactly one of provider_profile/provider is required. Endpoint is allowed only with
        provider. Unknown facts are null. A manual unlisted ID remains usable. Optional model returns
        one metadata row, including cap_key, for an unlisted manual ID; unknown facts stay null.
      parameters:
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [catalogue, cache-policy]
          default: catalogue
      - name: extension
        in: query
        required: false
        description: Cache-policy matching only; defaults to the empty selector.
        schema:
          type: string
          maxLength: 256
      - name: host
        in: query
        required: false
        description: Cache-policy matching only; defaults to the empty selector.
        schema:
          type: string
          maxLength: 4096
      - name: model
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: provider_profile
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: provider
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - name: endpoint
        in: query
        required: false
        schema:
          type: string
          format: uri
          maxLength: 4096
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
  /workspaces:
    get:
      operationId: getWorkspaces
      summary: Browse recent locations or a directory
      tags:
      - workspaces
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceRead'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: 'Without location return recent workspaces. include=preview requires location. Paths
        resolve on the daemon host; cached host state does not perform SSH sign-in. Requires capability
        `workspace_browsing: 1`.'
      parameters:
      - name: location
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum: [preview]
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
  /hosts:
    get:
      operationId: listHosts
      summary: Read known SSH hosts and cached state
      tags:
      - hosts
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      parameters:
      - name: target
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
      description: 'Requires capability `host_probes: 1`.'
  /hosts/{host}/probe:
    post:
      operationId: probeHost
      summary: Start or join a host probe
      tags:
      - hosts
      responses:
        '202':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
      description: 'Coalesce repeated probes. Authentication remains an explicit operator handoff; no
        background SSH sign-in. Requires capability `host_probes: 1`.'
      parameters:
      - name: host
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /auth:
    get:
      operationId: getAuth
      summary: Read login choices and redacted accounts
      tags:
      - auth
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: 'Requires capability `provider_auth: 1`.'
  /auth/logins/{login_id}:
    put:
      operationId: createLogin
      summary: Start or recover an identified provider login
      tags:
      - auth
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Login'
              examples:
                Login:
                  value:
                    id: 01a0fcea-2b00-7000-8000-000000000003
                    provider: example-provider
                    url: https://provider.example/authorize?state=synthetic-state
                    expires_at: '2026-10-02T14:15:00Z'
                    state: waiting
                    instructions: Paste the callback URL if the browser cannot reach the daemon.
                    progress: Waiting for authorization.
                    accounts: []
                    failure: null
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '429':
          $ref: '#/components/responses/Problem429'
        '200':
          description: Existing identified flow.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Login'
      description: 'UUIDv7 identity. Compare immutable private intent inside the daemon. Duplicate returns
        existing flow, never another browser/exchange. Restart turns unfinished flows into retained daemon_restarted
        failures; a new flow needs a new ID. Requires capability `provider_auth: 1`.'
      parameters:
      - name: login_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUIDv7'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    get:
      operationId: getLogin
      summary: Inspect a provider login
      tags:
      - auth
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Login'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: 'No credential or submitted form echo. Terminal records remain fifteen minutes; unfinished
        flows expire at their provider deadline. Requires capability `provider_auth: 1`.'
      parameters:
      - name: login_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    patch:
      operationId: answerLogin
      summary: Supply manual callback or code
      tags:
      - auth
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Login'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      parameters:
      - name: login_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/LoginPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      description: 'Requires capability `provider_auth: 1`.'
    delete:
      operationId: cancelLogin
      summary: Cancel a login idempotently
      tags:
      - auth
      responses:
        '204':
          description: Successful result.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
      description: 'Cancellation stops only this flow; completed accounts remain saved. No If-Match is
        needed for identity-scoped cancellation. Requires capability `provider_auth: 1`.'
      parameters:
      - name: login_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
  /auth/accounts/{account_id}:
    delete:
      operationId: deleteAccount
      summary: Remove an unreferenced provider account
      tags:
      - auth
      responses:
        '204':
          description: Successful result.
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: 'Reject if a saved provider profile references it. Does not interrupt captured credentials
        in an active request. Account IDs are never reused. Requires capability `provider_auth: 1`.'
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
  /extensions/work/items:
    get:
      operationId: listWork
      summary: List work resources
      tags:
      - work
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Requires enabled extension work. Lists may include bounded page descriptors and glances.
      parameters:
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: createWork
      summary: Create a work resource
      tags:
      - work
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkChange'
              examples:
                WorkChange:
                  value:
                    resource:
                      url: /extensions/work/items/work-1?workspace=%2Fworkspace%2Fproject
                      etag: '"work-revision-1"'
                      value:
                        id: work-1
                        workspace: /workspace/project
                        title: Fix the parser
                        notes: ''
                        parent_id: null
                        session_id: null
                        run_id: null
                        status: open
                        revision: work-revision-1
                        created_at: '2026-10-02T14:00:00Z'
                        updated_at: '2026-10-02T14:00:00Z'
                    notification:
                      state: not_requested
                      code: null
                      detail: null
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: No automatic lost-response retry. Notification outcome does not undo a committed domain
        edit.
      parameters:
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkCreate'
            examples:
              WorkCreate:
                value:
                  title: Fix the parser
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/work/items/{item_id}:
    get:
      operationId: getWork
      summary: Read one work resource
      tags:
      - work
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
    patch:
      operationId: patchWork
      summary: Edit a work resource
      tags:
      - work
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Use the displayed item validator. Reject readonly/unknown fields. No automatic lost-response
        retry.
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/WorkPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: deleteWork
      summary: Delete a work resource
      tags:
      - work
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionDeletion'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Committed deletion remains successful if notification fails. Work items with children
        cannot be deleted.
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: notify_session_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
        description: Queue the deletion note for this session after the durable edit.
      - $ref: '#/components/parameters/IfMatch'
  /extensions/paperclips/items:
    get:
      operationId: listPaperclips
      summary: List paperclips resources
      tags:
      - paperclips
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaperclipPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Requires enabled extension paperclips. Lists may include bounded page descriptors and
        glances.
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: createPaperclips
      summary: Create a paperclips resource
      tags:
      - paperclips
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaperclipChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: No automatic lost-response retry. Notification outcome does not undo a committed domain
        edit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaperclipCreate'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/paperclips/items/{item_id}:
    get:
      operationId: getPaperclips
      summary: Read one paperclips resource
      tags:
      - paperclips
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paperclip'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    patch:
      operationId: patchPaperclips
      summary: Edit a paperclips resource
      tags:
      - paperclips
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaperclipChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Use the displayed item validator. Reject readonly/unknown fields. No automatic lost-response
        retry.
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/PaperclipPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: deletePaperclips
      summary: Delete a paperclips resource
      tags:
      - paperclips
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionDeletion'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Committed deletion remains successful if notification fails. Work items with children
        cannot be deleted.
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
  /extensions/web-search/providers:
    get:
      operationId: listWebSearchProviders
      summary: List web search providers in the order a search tries them
      tags:
      - web-search
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchProviderPage'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Requires enabled extension web-search. The global order lives in extensions.json.
  /extensions/web-search/providers/{name}:
    post:
      operationId: changeWebSearchProvider
      summary: Move a web search provider up or down, or turn it on or off
      tags:
      - web-search
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchProviderChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '404':
          $ref: '#/components/responses/Problem404'
        '405':
          $ref: '#/components/responses/Problem405'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      description: A move past either end leaves the order as it was.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSearchProviderChangeRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/schedule/jobs:
    get:
      operationId: listSchedule
      summary: List schedule resources
      tags:
      - schedule
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulePage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Requires enabled extension schedule. Lists may include bounded page descriptors and
        glances.
      parameters:
      - name: session_id
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: createSchedule
      summary: Create a schedule resource
      tags:
      - schedule
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: No automatic lost-response retry. Notification outcome does not undo a committed domain
        edit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleCreate'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/schedule/jobs/{job_id}:
    get:
      operationId: getSchedule
      summary: Read one schedule resource
      tags:
      - schedule
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleJob'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    patch:
      operationId: patchSchedule
      summary: Edit a schedule resource
      tags:
      - schedule
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Use the displayed item validator. Reject readonly/unknown fields. No automatic lost-response
        retry.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SchedulePatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: deleteSchedule
      summary: Delete a schedule resource
      tags:
      - schedule
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionDeletion'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Committed deletion remains successful if notification fails. Work items with children
        cannot be deleted.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
  /extensions/links/groups:
    get:
      operationId: getLinkGroup
      summary: Read linked membership and presence
      tags:
      - links
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LinkGroup'
                - $ref: '#/components/schemas/LinkConfiguration'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Only configuration view has the canonical membership ETag. Presence does not change
        that validator.
      parameters:
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [configuration]
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: mergeLinkGroups
      summary: Merge two observed workspace groups
      tags:
      - links
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Check both observed validators in one owner commit. Human-only; domain commit and notifications
        are separate. No automatic lost-response retry.
      parameters:
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkMerge'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: unlinkWorkspace
      summary: Remove a member from the observed group
      tags:
      - links
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Check membership at commit. Creates a singleton group; deletes no work or memory. Human-only.
      parameters:
      - name: workspace
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: member
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Workspace'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
  /extensions/webhooks/hooks:
    get:
      operationId: listHooks
      summary: List hooks without secrets
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      parameters:
      - name: session_id
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: createHook
      summary: Create a hook and disclose its secret once
      tags:
      - webhooks
      responses:
        '201':
          description: Successful result.
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookChange'
              examples:
                HookChange:
                  value:
                    resource:
                      url: /extensions/webhooks/hooks/hook-1?view=configuration
                      etag: '"hook-revision-1"'
                      value:
                        id: hook-1
                        name: ci
                        session_id: 01a0fcea-2b00-7000-8000-000000000001
                        enabled: true
                        signature_header: X-Albedo-Signature
                        signature_prefix: sha256=
                        revision: hook-revision-1
                    notification:
                      state: not_requested
                      code: null
                      detail: null
                    secret: synthetic-example-hook-secret
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      description: Default enabled=true, signature_header=X-Albedo-Signature and signature_prefix=sha256=.
        Missing secret generates one. Lost secret requires explicit rotation; never retry creation automatically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookCreate'
            examples:
              HookCreate:
                value:
                  session_id: 01a0fcea-2b00-7000-8000-000000000001
                  name: ci
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/webhooks/hooks/{hook_id}:
    get:
      operationId: getHook
      summary: Read hook state or canonical configuration
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Hook'
                - $ref: '#/components/schemas/HookConfiguration'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: ETag is present only on configuration view. Ordinary read exposes the configuration
        resource and validator plus runtime observations.
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: false
        schema:
          type: string
          enum: [configuration]
    patch:
      operationId: patchHook
      summary: Edit the observed hook configuration
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Target session and secret are not writable. Agent callers need that session permission;
        HTTP bearer clients are operators.
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/HookPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
    delete:
      operationId: deleteHook
      summary: Delete a hook while retaining accepted deliveries
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionDeletion'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: view
        in: query
        required: true
        schema:
          const: configuration
      - $ref: '#/components/parameters/IfMatch'
  /extensions/webhooks/hooks/{hook_id}/secret:
    post:
      operationId: rotateHookSecret
      summary: Rotate and disclose the hook secret once
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: If-Match is the observed hook configuration validator. Missing secret generates one.
        No automatic retry after a lost response.
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookSecretRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/webhooks/hooks/{hook_id}/deliveries:
    get:
      operationId: listHookDeliveries
      summary: Read accepted hook delivery metadata
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryPage'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Historical reads remain available after hook deletion while retained deliveries exist.
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum: [pending, delivered, all]
          default: all
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Next'
    post:
      operationId: deliverWebhook
      summary: Accept signed external data durably
      tags:
      - webhooks
      responses:
        '202':
          description: Successful result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  delivery_id:
                    $ref: '#/components/schemas/ID'
                required: [delivery_id]
                additionalProperties: false
        '400':
          $ref: '#/components/responses/Problem400'
        '403':
          description: Missing or invalid hook signature.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '429':
          $ref: '#/components/responses/Problem429'
      description: Authenticate configured HMAC-SHA256 over the exact raw body. A daemon bearer is not
        a substitute. Signature header name and prefix come from hook configuration. Same event ID and
        body returns original admission; changed body conflicts. Pending inbox limit 1000. Raw body maximum
        65536 bytes.
      parameters:
      - name: hook_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: X-Albedo-Event-Id
        in: header
        required: false
        schema:
          type: string
          pattern: ^[^\r\n]+$
          maxLength: 128
        description: Optional sender identity scoped to hook and exact body hash.
      security:
      - WebhookSignature: []
      requestBody:
        required: true
        content:
          '*/*':
            schema:
              type: string
              format: binary
              maxLength: 65536
        description: Raw bytes, not a parsed JSON requirement. Verify signature before admission.
  /extensions/webhooks/deliveries/{delivery_id}:
    get:
      operationId: getDelivery
      summary: Read an accepted delivery payload
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryDetail'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      parameters:
      - name: delivery_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
  /extensions/webhooks/permissions/{session_id}:
    get:
      operationId: getHookPermission
      summary: Read agent hook-management permission
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookPermission'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '404':
          $ref: '#/components/responses/Problem404'
      description: Absent stored permission reads false with its initial canonical validator.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    patch:
      operationId: patchHookPermission
      summary: Set agent hook-management permission
      tags:
      - webhooks
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookPermissionChange'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '404':
          $ref: '#/components/responses/Problem404'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      description: Only operator callers can grant permission. Omission retains it; turning off management
        keeps existing hooks enabled.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/HookPermissionPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/proxy/v1/models:
    get:
      operationId: listProxyModels
      summary: List saved-profile OpenAI model IDs
      tags:
      - proxy
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyModels'
        '400':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '401':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '403':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '405':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '406':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '503':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
      description: External OpenAI envelope. Bearer required unless operator explicitly configured anonymous
        loopback access.
  /extensions/proxy/v1/chat/completions:
    post:
      operationId: createProxyCompletion
      summary: Run a stateless OpenAI chat completion
      tags:
      - proxy
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyCompletion'
              examples:
                ProxyCompletion:
                  value:
                    id: completion-1
                    object: chat.completion
                    created: 1790949600
                    model: personal/example-model
                    choices:
                    - index: 0
                      message:
                        role: assistant
                        content: Hello
                      finish_reason: stop
                    usage:
                      prompt_tokens: 1
                      completion_tokens: 1
                      total_tokens: 2
            text/event-stream:
              itemSchema:
                $ref: '#/components/schemas/ProxySSE'
        '400':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '401':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '403':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '405':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '406':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '503':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '413':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
        '415':
          description: OpenAI proxy error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyError'
      description: Caller supplies full history. Tool IDs carry opaque provider state and must be echoed
        exactly. Bearer required unless anonymous loopback policy explicitly enabled. Providers apply
        only representable generation options; proxy transport documentation defines these differences.
        No automatic replay after request admission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyCompletionRequest'
            examples:
              ProxyCompletionRequest:
                value:
                  model: personal/example-model
                  messages:
                  - role: user
                    content: Hello
                  stream: true
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
  /extensions/run/sessions/{session_id}/jobs:
    get:
      operationId: listJobs
      summary: Read bounded live job observations and the jobs page
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: Known live jobs, with up to 100 summaries ordered by ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCollection'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
  /extensions/run/sessions/{session_id}/jobs/{job_id}/stop:
    post:
      operationId: stopJob
      summary: Explicitly stop one observed process group
      description: No automatic retry after response loss. Read the job collection before confirming another attempt. A successful response confirms the supervisor verdict, not just signal delivery.
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      - name: job_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The observed job's process group was stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStop'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '405':
          $ref: '#/components/responses/Problem405'
        '406':
          $ref: '#/components/responses/Problem406'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
components:
  securitySchemes:
    DaemonBearer:
      type: http
      scheme: bearer
      description: Daemon operator token, supplied out of band. Browser clients use fetch for authenticated
        JSON and SSE. No query tokens or authentication cookies.
    WebhookSignature:
      type: apiKey
      in: header
      name: X-Albedo-Signature
      description: Default header only. Each hook may configure another header and prefix. HMAC-SHA256
        over exact raw bytes; bearer is not an alternative.
  parameters:
    IfMatch:
      name: If-Match
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/ETag'
      description: Observed canonical representation validator. Wildcards and weak validators are not
        accepted.
    IfNoneMatch:
      name: If-None-Match
      in: header
      required: true
      schema:
        const: '*'
      description: Conditional creation only.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Next:
      name: next
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PageToken'
  headers:
    ETag:
      description: Opaque strong validator for the complete canonical JSON representation. Mutation envelopes
        carry their resource validator inside the body.
      schema:
        $ref: '#/components/schemas/ETag'
    Location:
      description: URL of the created resource.
      schema:
        $ref: '#/components/schemas/ResourceURL'
      required: true
    Vary:
      description: Includes Accept; browser responses also include Origin.
      schema:
        type: string
    RetryAfter:
      description: Seconds until a later new admission may succeed. Never retries an already rejected
        identified input.
      schema:
        type: integer
        minimum: 0
        maximum: 3600
    WWWAuthenticate:
      description: Bearer challenge.
      schema:
        type: string
        pattern: ^Bearer
    Allow:
      description: Allowed methods for a known path.
      schema:
        type: string
  responses:
    Problem400:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem401:
      description: Missing or invalid daemon token
      headers:
        WWWAuthenticate:
          $ref: '#/components/headers/WWWAuthenticate'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem403:
      description: Disallowed origin or caller
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem404:
      description: Unknown resource or disabled service
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem405:
      description: Method not allowed
      headers:
        Allow:
          $ref: '#/components/headers/Allow'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem406:
      description: Unsupported response media type
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem409:
      description: Conflicting intent, busy state or stale catalog
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem410:
      description: Expired identity, deletion tombstone or obsolete context
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem412:
      description: Stale representation or failed creation condition
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem413:
      description: Body too large
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem415:
      description: Unsupported request media type
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem428:
      description: Required precondition missing
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem429:
      description: Admission limit
      headers:
        RetryAfter:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem503:
      description: Unavailable owner, storage or upstream preparation
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    ID:
      type: string
      minLength: 1
      description: Opaque identity. Never infer a resource type or route from its contents.
      maxLength: 512
    UUIDv7:
      type: string
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      format: uuid
      description: Client-generated lowercase UUIDv7. Retained decisions are checked before timestamp
        expiry.
    Generation:
      type: string
      pattern: ^[A-Za-z0-9_-]{21}[AQgw]$
      description: 128 random bits encoded as unpadded base64url; new for each session actor lifetime.
    Counter:
      type: integer
      minimum: 0
      maximum: 9007199254740991
    Timestamp:
      type: string
      format: date-time
      pattern: Z$
      description: UTC RFC 3339.
    PageToken:
      type: string
      minLength: 1
      description: Opaque continuation, tied to the query and representation; never authority.
      maxLength: 4096
    ETag:
      type: string
      pattern: ^"[^"\r\n]+"$
      description: Strong opaque validator for the complete canonical representation.
      maxLength: 512
    ResourceURL:
      type: string
      pattern: ^/([^/#][^#]*)?$
      description: Daemon-relative URL, including any representation query. No foreign origin or fragment.
      maxLength: 16384
    Workspace:
      type: string
      minLength: 1
      description: Canonical daemon-host location, local or SSH. Clients do not resolve this path locally.
      maxLength: 4096
    SafeReason:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 100
        detail:
          type: string
          maxLength: 4096
      required: [code, detail]
      additionalProperties: false
    Warnings:
      type: array
      items:
        $ref: '#/components/schemas/SafeReason'
      maxItems: 100
    DynamicJSON:
      description: 'Explicit domain payload: tool arguments, tool results, provider-private state, or
        extension data. JSON values of any type are allowed; no core resource uses this as its envelope.'
    Problem:
      type: object
      properties:
        type:
          const: about:blank
        title:
          type: string
          maxLength: 256
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
          maxLength: 4096
        code:
          type: string
          minLength: 1
          maxLength: 100
        fields:
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
                maxLength: 4096
              detail:
                type: string
                maxLength: 4096
            required: [pointer, detail]
            additionalProperties: false
          maxItems: 100
        decision:
          oneOf:
          - $ref: '#/components/schemas/CreationDecision'
          - $ref: '#/components/schemas/InputDecision'
      required: [type, title, status, detail, code]
      additionalProperties: false
      examples:
      - type: about:blank
        title: Queue full
        status: 429
        detail: This session already has 32 waiting inputs.
        code: queue_full
        decision:
          kind: input
          input:
            id: 01a0fcea-2b00-7000-8000-000000000002
            session_id: 01a0fcea-2b00-7000-8000-000000000001
            kind: message
            admission: rejected
            http_status: 429
            problem:
              type: about:blank
              title: Queue full
              status: 429
              detail: This session already has 32 waiting inputs.
              code: queue_full
            accepted_at: null
            acceptance_order: null
            delivery: null
            blocking_reason: null
            transcript_position: null
            turn: null
            client_id: draft-1
    EmptyRequest:
      type: object
      properties: {}
      additionalProperties: false
    Cursor:
      type: object
      properties:
        generation:
          $ref: '#/components/schemas/Generation'
        sequence:
          $ref: '#/components/schemas/Counter'
      required: [generation, sequence]
      additionalProperties: false
    ResourceValidator:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
      required: [url, etag]
      additionalProperties: false
    Notification:
      type: object
      properties:
        state:
          type: string
          enum: [not_requested, queued, failed]
        code:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        detail:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
      required: [state, code, detail]
      additionalProperties: false
    TargetNotification:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [session_id, notification]
      additionalProperties: false
    QuotaObservation:
      type: object
      properties:
        sequence:
          $ref: '#/components/schemas/Counter'
        provider:
          $ref: '#/components/schemas/ID'
        account_id:
          $ref: '#/components/schemas/ID'
        limit_id:
          type: string
          maxLength: 256
        label:
          type: string
          maxLength: 4096
        plan:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        used_percent:
          anyOf:
          - type: number
          - type: 'null'
        window_label:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        window_seconds:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        resets_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        scope:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        status:
          type: string
          maxLength: 256
        source:
          type: string
          maxLength: 256
        error:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        observed_at:
          $ref: '#/components/schemas/Timestamp'
      required:
      - sequence
      - provider
      - account_id
      - limit_id
      - label
      - plan
      - used_percent
      - window_label
      - window_seconds
      - resets_at
      - scope
      - status
      - source
      - error
      - observed_at
      additionalProperties: false
    QuotaPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuotaObservation'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    Server:
      type: object
      properties:
        instance_id:
          $ref: '#/components/schemas/ID'
        protocol:
          const: 3
        state:
          type: string
          enum: [ready, draining]
        capabilities:
          type: object
          additionalProperties:
            type: integer
            minimum: 1
            maximum: 9007199254740991
        build:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        digest:
          type: [string, 'null']
          pattern: ^[0-9a-f]{64}$
          description: Content digest of the running code tree; update information, not attachment compatibility.
        extensions:
          type: array
          items:
            type: object
            properties:
              name:
                $ref: '#/components/schemas/ID'
              version:
                type: integer
                minimum: 1
                maximum: 9007199254740991
            required: [name, version]
            additionalProperties: false
          maxItems: 200
        quota:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/QuotaObservation'
            maxItems: 200
          - type: 'null'
        notices:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/ID'
              kind:
                type: string
                enum: [info, warning, migration]
              message:
                type: string
                maxLength: 4096
            required: [id, kind, message]
            additionalProperties: false
          maxItems: 100
        quota_history:
          $ref: '#/components/schemas/QuotaPage'
      required: [instance_id, protocol, state, capabilities, build, digest, extensions, quota, notices]
      additionalProperties: false
      examples:
      - instance_id: instance-1
        protocol: 3
        state: ready
        capabilities:
          durable_inputs: 1
          session_replay: 1
          collection_invalidation: 1
          tool_progress: 1
          storage_report: 1
        build: example-build
        digest: null
        extensions:
        - name: work
          version: 1
        quota: null
        notices: []
    ShutdownRequest:
      type: object
      properties:
        instance_id:
          $ref: '#/components/schemas/ID'
        timeout_ms:
          type: integer
          minimum: 1
          maximum: 30000
          default: 5000
      required: [instance_id]
      additionalProperties: false
    Shutdown:
      type: object
      properties:
        instance_id:
          $ref: '#/components/schemas/ID'
        state:
          const: draining
      required: [instance_id, state]
      additionalProperties: false
    ProviderProfile:
      type: object
      properties:
        extension:
          $ref: '#/components/schemas/ID'
        endpoint:
          anyOf:
          - type: string
            format: uri
            maxLength: 4096
          - type: 'null'
        protocol:
          type: string
          enum: [responses, chat_completions]
        model:
          $ref: '#/components/schemas/ID'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        image_edge:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 65536
          - type: 'null'
        account_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        project:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        location:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        has_key:
          type: boolean
      required: [extension, endpoint, protocol, model, effort, image_edge, account_id, project, location, has_key]
      additionalProperties: false
    ProviderProfilePatch:
      type: object
      properties:
        extension:
          $ref: '#/components/schemas/ID'
        endpoint:
          anyOf:
          - type: string
            format: uri
            maxLength: 4096
          - type: 'null'
        protocol:
          type: string
          enum: [responses, chat_completions]
        model:
          $ref: '#/components/schemas/ID'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        image_edge:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 65536
          - type: 'null'
        account_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        project:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        location:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        api_key:
          anyOf:
          - type: string
            minLength: 1
            writeOnly: true
            maxLength: 16384
          - type: 'null'
      description: Partial existing profile; extension and model required when creating a new map entry.
      additionalProperties: false
    ProviderSettings:
      type: object
      properties:
        default_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        profiles:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ProviderProfile'
      required: [default_profile, profiles]
      additionalProperties: false
    ProviderSettingsPatch:
      type: object
      properties:
        default_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        profiles:
          type: object
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/ProviderProfilePatch'
            - type: 'null'
      description: Removing the selected profile requires replacing or clearing default_profile in this
        same patch.
      additionalProperties: false
      examples:
      - default_profile: personal
        profiles:
          personal:
            extension: openai
            endpoint: https://provider.example/v1
            protocol: responses
            model: example-model
            effort: null
            image_edge: null
            account_id: null
            project: null
            location: null
            api_key: synthetic-example-key
    ValueSource:
      type: object
      properties:
        source:
          type: string
          enum: [literal, env]
        value:
          type: string
          maxLength: 16384
      description: For env, value is a daemon-host environment variable name.
      required: [source, value]
      additionalProperties: false
    SecretPresence:
      type: object
      properties:
        bearer_token:
          type: boolean
        environment:
          type: array
          items:
            type: string
            maxLength: 256
          maxItems: 200
        headers:
          type: array
          items:
            type: string
            maxLength: 256
          maxItems: 200
      required: [bearer_token, environment, headers]
      additionalProperties: false
    MCPDefinition:
      type: object
      properties:
        enabled:
          type: boolean
        transport:
          type: string
          enum: [stdio, http]
        command:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        arguments:
          type: array
          items:
            type: string
            maxLength: 4096
          maxItems: 200
        cwd:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        url:
          anyOf:
          - type: string
            format: uri
            maxLength: 4096
          - type: 'null'
        environment:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueSource'
        headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueSource'
        bearer_token_env_var:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        enabled_tools:
          anyOf:
          - type: array
            items:
              type: string
              maxLength: 256
            maxItems: 1000
          - type: 'null'
        disabled_tools:
          type: array
          items:
            type: string
            maxLength: 256
          maxItems: 1000
        startup_timeout_ms:
          type: integer
          minimum: 1
          maximum: 300000
        call_timeout_ms:
          type: integer
          minimum: 1
          maximum: 3600000
        secret_presence:
          $ref: '#/components/schemas/SecretPresence'
      required: [enabled, transport, command, arguments, cwd, url, environment, headers, bearer_token_env_var,
        enabled_tools, disabled_tools, startup_timeout_ms, call_timeout_ms, secret_presence]
      additionalProperties: false
    MCPSecretsPatch:
      type: object
      properties:
        bearer_token:
          anyOf:
          - type: string
            minLength: 1
            writeOnly: true
            maxLength: 16384
          - type: 'null'
        environment:
          type: object
          additionalProperties:
            anyOf:
            - type: string
              writeOnly: true
              maxLength: 16384
            - type: 'null'
        headers:
          type: object
          additionalProperties:
            anyOf:
            - type: string
              writeOnly: true
              maxLength: 16384
            - type: 'null'
      writeOnly: true
      additionalProperties: false
    MCPDefinitionPatch:
      type: object
      properties:
        enabled:
          type: boolean
        transport:
          type: string
          enum: [stdio, http]
        command:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        arguments:
          type: array
          items:
            type: string
            maxLength: 4096
          maxItems: 200
        cwd:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        url:
          anyOf:
          - type: string
            format: uri
            maxLength: 4096
          - type: 'null'
        environment:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - $ref: '#/components/schemas/ValueSource'
              - type: 'null'
          - type: 'null'
        headers:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - $ref: '#/components/schemas/ValueSource'
              - type: 'null'
          - type: 'null'
        bearer_token_env_var:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        enabled_tools:
          anyOf:
          - type: array
            items:
              type: string
              maxLength: 256
            maxItems: 1000
          - type: 'null'
        disabled_tools:
          type: array
          items:
            type: string
            maxLength: 256
          maxItems: 1000
        startup_timeout_ms:
          type: integer
          minimum: 1
          maximum: 300000
        call_timeout_ms:
          type: integer
          minimum: 1
          maximum: 3600000
        secrets:
          $ref: '#/components/schemas/MCPSecretsPatch'
      description: Partial merge patch. Public and secret sources cannot overlap. HTTP and stdio fields
        are validated against transport on the complete candidate. Public environment/header entries accept
        null removal; a null whole map clears it. Switching credential sources removes the former source
        in the same patch.
      additionalProperties: false
    MCPSettings:
      type: object
      properties:
        definitions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MCPDefinition'
      required: [definitions]
      additionalProperties: false
    MCPSettingsPatch:
      type: object
      properties:
        definitions:
          type: object
          additionalProperties:
            anyOf:
            - $ref: '#/components/schemas/MCPDefinitionPatch'
            - type: 'null'
        validate_connection:
          type: boolean
          default: true
          writeOnly: true
      description: Validate candidate connections before atomic commit unless explicitly disabled.
      additionalProperties: false
      examples:
      - validate_connection: true
        definitions:
          example:
            enabled: true
            transport: http
            url: https://tools.example/mcp
            secrets:
              bearer_token: synthetic-example-token
    ExtensionSettings:
      type: object
      properties:
        defaults:
          type: object
          additionalProperties:
            type: boolean
      required: [defaults]
      additionalProperties: false
    ExtensionSettingsPatch:
      type: object
      properties:
        defaults:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
      additionalProperties: false
    CapabilitySettings:
      type: object
      properties:
        preferences:
          type: object
          additionalProperties:
            type: boolean
      required: [preferences]
      additionalProperties: false
    CapabilitySettingsPatch:
      type: object
      properties:
        catalog_session_id:
          $ref: '#/components/schemas/ID'
        catalog_revision:
          $ref: '#/components/schemas/ID'
        choices:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
      description: Resolve candidate IDs to stable preference keys under the observed catalog revision.
      required: [catalog_session_id, catalog_revision, choices]
      additionalProperties: false
    CachePrior:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ID'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        ttl_seconds:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
        source:
          type: string
          maxLength: 256
      required: [provider, model, ttl_seconds, source]
      additionalProperties: false
    ModelSettings:
      type: object
      properties:
        raised_caps:
          type: object
          additionalProperties:
            type: boolean
        cache_ttl_priors:
          type: array
          items:
            $ref: '#/components/schemas/CachePrior'
          maxItems: 200
      required: [raised_caps, cache_ttl_priors]
      additionalProperties: false
    ModelSettingsPatch:
      type: object
      properties:
        raised_caps:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
      description: Keys are cap_key values from model metadata. True raises to the advertised maximum;
        false uses the ordinary limit; null clears the choice. A missing choice defaults to false. Only
        raised_caps is writable.
      additionalProperties: false
    UISettings:
      type: object
      properties:
        thinking:
          type: boolean
        tools:
          type: boolean
        dismissed_notices:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 1000
      required: [thinking, tools, dismissed_notices]
      additionalProperties: false
    UISettingsPatch:
      type: object
      properties:
        thinking:
          type: boolean
        tools:
          type: boolean
        dismissed_notices:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 1000
      additionalProperties: false
    ProviderSettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/ProviderSettings'
      required: [url, etag, value]
      additionalProperties: false
    MCPSettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/MCPSettings'
      required: [url, etag, value]
      additionalProperties: false
    ExtensionSettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/ExtensionSettings'
      required: [url, etag, value]
      additionalProperties: false
    CapabilitySettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/CapabilitySettings'
      required: [url, etag, value]
      additionalProperties: false
    ModelSettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/ModelSettings'
      required: [url, etag, value]
      additionalProperties: false
    UISettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/UISettings'
      required: [url, etag, value]
      additionalProperties: false
    Settings:
      type: object
      properties:
        providers:
          $ref: '#/components/schemas/ProviderSettings'
        mcp:
          $ref: '#/components/schemas/MCPSettings'
        extensions:
          $ref: '#/components/schemas/ExtensionSettings'
        capabilities:
          $ref: '#/components/schemas/CapabilitySettings'
        models:
          $ref: '#/components/schemas/ModelSettings'
        ui:
          $ref: '#/components/schemas/UISettings'
        group_resources:
          type: object
          properties:
            providers:
              $ref: '#/components/schemas/ResourceValidator'
            mcp:
              $ref: '#/components/schemas/ResourceValidator'
            extensions:
              $ref: '#/components/schemas/ResourceValidator'
            capabilities:
              $ref: '#/components/schemas/ResourceValidator'
            models:
              $ref: '#/components/schemas/ResourceValidator'
            ui:
              $ref: '#/components/schemas/ResourceValidator'
          required: [providers, mcp, extensions, capabilities, models, ui]
          additionalProperties: false
      required: [providers, mcp, extensions, capabilities, models, ui, group_resources]
      additionalProperties: false
    SettingsRead:
      oneOf:
      - $ref: '#/components/schemas/Settings'
      - $ref: '#/components/schemas/ProviderSettings'
      - $ref: '#/components/schemas/MCPSettings'
      - $ref: '#/components/schemas/ExtensionSettings'
      - $ref: '#/components/schemas/CapabilitySettings'
      - $ref: '#/components/schemas/ModelSettings'
      - $ref: '#/components/schemas/UISettings'
    SettingsPatch:
      anyOf:
      - $ref: '#/components/schemas/ProviderSettingsPatch'
      - $ref: '#/components/schemas/MCPSettingsPatch'
      - $ref: '#/components/schemas/ExtensionSettingsPatch'
      - $ref: '#/components/schemas/CapabilitySettingsPatch'
      - $ref: '#/components/schemas/ModelSettingsPatch'
      - $ref: '#/components/schemas/UISettingsPatch'
      description: The group query selects the one applicable patch schema. It is an error to send fields
        for another group.
    SettingsApplication:
      type: object
      properties:
        desired_revision:
          $ref: '#/components/schemas/ID'
        active_service_revision:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        composition_changed:
          type: boolean
          description: Whether this save changed the desired composition, so loaded sessions need a
            reload to apply it. Always false for providers, models and ui. A concurrent save to another
            composition group can make it true. GET /sessions?needs_reload=true lists the sessions.
        validation:
          type: string
          enum: [passed, skipped, not_applicable]
        warnings:
          $ref: '#/components/schemas/Warnings'
      required: [desired_revision, active_service_revision, composition_changed, validation, warnings]
      additionalProperties: false
    ProviderSettingsChange:
      type: object
      properties:
        group:
          const: providers
        resource:
          $ref: '#/components/schemas/ProviderSettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    MCPSettingsChange:
      type: object
      properties:
        group:
          const: mcp
        resource:
          $ref: '#/components/schemas/MCPSettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    ExtensionSettingsChange:
      type: object
      properties:
        group:
          const: extensions
        resource:
          $ref: '#/components/schemas/ExtensionSettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    CapabilitySettingsChange:
      type: object
      properties:
        group:
          const: capabilities
        resource:
          $ref: '#/components/schemas/CapabilitySettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    ModelSettingsChange:
      type: object
      properties:
        group:
          const: models
        resource:
          $ref: '#/components/schemas/ModelSettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    UISettingsChange:
      type: object
      properties:
        group:
          const: ui
        resource:
          $ref: '#/components/schemas/UISettingsResource'
        application:
          $ref: '#/components/schemas/SettingsApplication'
      required: [group, resource, application]
      additionalProperties: false
    SettingsChange:
      oneOf:
      - $ref: '#/components/schemas/ProviderSettingsChange'
      - $ref: '#/components/schemas/MCPSettingsChange'
      - $ref: '#/components/schemas/ExtensionSettingsChange'
      - $ref: '#/components/schemas/CapabilitySettingsChange'
      - $ref: '#/components/schemas/ModelSettingsChange'
      - $ref: '#/components/schemas/UISettingsChange'
    StorageSession:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        title:
          type: string
          maxLength: 4096
        workspace:
          $ref: '#/components/schemas/Workspace'
        created_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        activity_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        estimated_content_bytes:
          $ref: '#/components/schemas/Counter'
      required: [id, title, workspace, created_at, activity_at, estimated_content_bytes]
      additionalProperties: false
    StorageFile:
      type: object
      properties:
        path:
          type: string
          maxLength: 4096
        category:
          type: string
          enum: [kernel, backup, other]
        bytes:
          $ref: '#/components/schemas/Counter'
        modified_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        cleanup_candidate:
          type: boolean
        cleanup_reason:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [path, category, bytes, modified_at, cleanup_candidate, cleanup_reason]
      additionalProperties: false
    StorageSessionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorageSession'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        total_count:
          $ref: '#/components/schemas/Counter'
        total_estimated_content_bytes:
          $ref: '#/components/schemas/Counter'
      required: [items, next, total_count, total_estimated_content_bytes]
      additionalProperties: false
    StorageFilePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorageFile'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        totals:
          type: object
          properties:
            kernel_bytes:
              $ref: '#/components/schemas/Counter'
            backup_bytes:
              $ref: '#/components/schemas/Counter'
            other_bytes:
              $ref: '#/components/schemas/Counter'
            recent_backup_bytes:
              $ref: '#/components/schemas/Counter'
            recent_backup_count:
              $ref: '#/components/schemas/Counter'
          required: [kernel_bytes, backup_bytes, other_bytes, recent_backup_bytes, recent_backup_count]
          additionalProperties: false
      required: [items, next, totals]
      additionalProperties: false
    StorageReport:
      type: object
      properties:
        database:
          type: object
          properties:
            main_file_bytes:
              $ref: '#/components/schemas/Counter'
            wal_bytes:
              $ref: '#/components/schemas/Counter'
            page_size_bytes:
              $ref: '#/components/schemas/Counter'
            page_count:
              $ref: '#/components/schemas/Counter'
            free_page_count:
              $ref: '#/components/schemas/Counter'
            used_bytes:
              $ref: '#/components/schemas/Counter'
          required: [main_file_bytes, wal_bytes, page_size_bytes, page_count, free_page_count, used_bytes]
          additionalProperties: false
        sessions:
          $ref: '#/components/schemas/StorageSessionPage'
        images:
          type: object
          properties:
            count:
              $ref: '#/components/schemas/Counter'
            bytes:
              $ref: '#/components/schemas/Counter'
          required: [count, bytes]
          additionalProperties: false
        files:
          $ref: '#/components/schemas/StorageFilePage'
        measured_at:
          $ref: '#/components/schemas/Timestamp'
      required: [database, sessions, images, files, measured_at]
      additionalProperties: false
      examples:
      - database:
          main_file_bytes: 8192
          wal_bytes: 0
          page_size_bytes: 4096
          page_count: 2
          free_page_count: 0
          used_bytes: 8192
        sessions:
          items: []
          next: null
          total_count: 0
          total_estimated_content_bytes: 0
        images:
          count: 0
          bytes: 0
        files:
          items: []
          next: null
          totals:
            kernel_bytes: 0
            backup_bytes: 0
            other_bytes: 0
            recent_backup_bytes: 0
            recent_backup_count: 0
        measured_at: '2026-10-02T14:00:00Z'
    SessionStatus:
      type: object
      properties:
        phase:
          type: string
          enum: [idle, preparing, generating, running, interrupting, compacting]
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        interrupt_requested:
          type: boolean
        blocking_reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [phase, run_id, interrupt_requested, blocking_reason]
      additionalProperties: false
    Preview:
      type: object
      properties:
        text:
          type: string
          x-max-utf8-bytes: 1024
          maxLength: 256
        transcript_count:
          $ref: '#/components/schemas/Counter'
        truncated:
          type: boolean
      required: [text, transcript_count, truncated]
      additionalProperties: false
    SessionPreferences:
      type: object
      properties:
        pinned:
          type: boolean
        pin_order:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        archived:
          type: boolean
        opens:
          $ref: '#/components/schemas/Counter'
      required: [pinned, pin_order, archived, opens]
      additionalProperties: false
    PreferencePatch:
      type: object
      properties:
        pinned:
          type: boolean
        archived:
          type: boolean
      additionalProperties: false
    ProgressPreview:
      type: object
      properties:
        offset_scalars:
          $ref: '#/components/schemas/Counter'
        text:
          type: string
          x-max-utf8-bytes: 2048
          maxLength: 512
      required: [offset_scalars, text]
      additionalProperties: false
    ToolProgress:
      type: object
      properties:
        call_id:
          $ref: '#/components/schemas/ID'
        tool_call_id:
          anyOf:
          - type: string
            minLength: 1
            x-max-utf8-bytes: 200
            maxLength: 200
          - type: 'null'
        name:
          type: string
          minLength: 1
          x-max-utf8-bytes: 100
          maxLength: 100
        phase:
          type: string
          enum: [generating, running]
        intent:
          type: string
          enum: [read, search, list, run, unknown]
        preview:
          $ref: '#/components/schemas/ProgressPreview'
      x-max-encoded-bytes: 8192
      required: [call_id, tool_call_id, name, phase, intent]
      additionalProperties: false
      examples:
      - call_id: progress-1
        tool_call_id: null
        name: python
        phase: generating
        intent: unknown
        preview:
          offset_scalars: 0
          text: print("hello")
    AgentRequest:
      type: object
      properties:
        input_id:
          $ref: '#/components/schemas/ID'
        text:
          type: string
          maxLength: 512
      required: [input_id, text]
      additionalProperties: false
    Activity:
      type: object
      properties:
        lines:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum: [assistant, thinking, tool, input, note, error]
              text:
                type: string
                x-max-utf8-bytes: 1024
                maxLength: 256
            required: [kind, text]
            additionalProperties: false
          maxItems: 12
        output_scalars:
          $ref: '#/components/schemas/Counter'
        output_utf8_bytes:
          $ref: '#/components/schemas/Counter'
        observed_at:
          $ref: '#/components/schemas/Timestamp'
        latest_input:
          anyOf:
          - type: object
            properties:
              input_id:
                $ref: '#/components/schemas/ID'
              source:
                type: string
                enum: [chat, agent, system]
              bytes:
                $ref: '#/components/schemas/Counter'
            required: [input_id, source, bytes]
            additionalProperties: false
          - type: 'null'
        current_request:
          anyOf:
          - $ref: '#/components/schemas/AgentRequest'
          - type: 'null'
        latest_progress:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        latest_answer:
          anyOf:
          - type: object
            properties:
              message_id:
                $ref: '#/components/schemas/ID'
              bytes:
                $ref: '#/components/schemas/Counter'
            required: [message_id, bytes]
            additionalProperties: false
          - type: 'null'
      x-max-encoded-bytes: 16384
      required: [lines, output_scalars, output_utf8_bytes, observed_at, latest_input, latest_answer]
      additionalProperties: false
    SessionLocation:
      type: object
      description: Parsed workspace and daemon-resolved display label. Reading this metadata does not connect to the remote host.
      properties:
        host:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        user:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        path:
          type: string
          maxLength: 16384
        label:
          anyOf:
          - type: string
            maxLength: 8192
          - type: 'null'
      required: [host, user, path, label]
      additionalProperties: false
    SessionSummary:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        name:
          type: string
          maxLength: 4096
        automatic_name:
          type: string
          maxLength: 4096
        location:
          $ref: '#/components/schemas/SessionLocation'
        workspace:
          $ref: '#/components/schemas/Workspace'
        parent_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        root_id:
          $ref: '#/components/schemas/ID'
        address:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        depth:
          type: integer
          minimum: 0
          maximum: 1000
        closed:
          type: boolean
        created_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        activity_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        provider_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        status:
          $ref: '#/components/schemas/SessionStatus'
        preview:
          $ref: '#/components/schemas/Preview'
        preferences:
          $ref: '#/components/schemas/SessionPreferences'
        current_progress:
          type: array
          items:
            $ref: '#/components/schemas/ToolProgress'
          maxItems: 32
        activity:
          $ref: '#/components/schemas/Activity'
        cursor:
          anyOf:
          - $ref: '#/components/schemas/Cursor'
          - type: 'null'
      description: Live fields and cursor are captured together. Extra response fields may be ignored.
      required: [id, name, automatic_name, workspace, location, parent_id, root_id, address, depth, closed, created_at,
        activity_at, provider_profile, model, effort, status, preview, preferences, current_progress,
        activity, cursor]
    SessionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SessionSummary'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        family:
          type: object
          properties:
            root_id:
              $ref: '#/components/schemas/ID'
            revision:
              $ref: '#/components/schemas/ID'
          required: [root_id, revision]
          additionalProperties: false
      required: [items, next]
      additionalProperties: false
      examples:
      - items:
        - id: 01a0fcea-2b00-7000-8000-000000000001
          name: New session
          automatic_name: New session
          workspace: /workspace/project
          location:
            host: null
            user: null
            path: /workspace/project
            label: null
          parent_id: null
          root_id: 01a0fcea-2b00-7000-8000-000000000001
          address: null
          depth: 0
          closed: false
          created_at: '2026-10-02T14:00:00Z'
          activity_at: '2026-10-02T14:00:00Z'
          provider_profile: personal
          model: example-model
          effort: null
          status:
            phase: idle
            run_id: null
            interrupt_requested: false
            blocking_reason: null
          preview:
            text: ''
            transcript_count: 0
            truncated: false
          preferences:
            pinned: false
            pin_order: null
            archived: false
            opens: 0
          current_progress: []
          active_output: []
          activity:
            lines: []
            output_scalars: 0
            output_utf8_bytes: 0
            observed_at: '2026-10-02T14:00:00Z'
            latest_input: null
            latest_answer: null
          cursor:
            generation: J6kYj6IGcXyP3eMIp-WL3A
            sequence: 0
        next: null
    SelectionOverrides:
      type: object
      properties:
        extensions:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
        skills:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
        instructions:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
        mcp:
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: 'null'
      required: [extensions, skills, instructions, mcp]
      additionalProperties: false
    SelectionPatch:
      type: object
      properties:
        extensions:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - type: boolean
              - type: 'null'
          - type: 'null'
        skills:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - type: boolean
              - type: 'null'
          - type: 'null'
        instructions:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - type: boolean
              - type: 'null'
          - type: 'null'
        mcp:
          anyOf:
          - type: object
            additionalProperties:
              anyOf:
              - type: boolean
              - type: 'null'
          - type: 'null'
      description: Null map entry clears that override. Null entire map clears all overrides of that kind.
      additionalProperties: false
    SessionSelection:
      type: object
      properties:
        overrides:
          $ref: '#/components/schemas/SelectionOverrides'
        effective:
          type: object
          properties:
            extensions:
              type: object
              additionalProperties:
                type: boolean
            skills:
              type: object
              additionalProperties:
                type: boolean
            instructions:
              type: object
              additionalProperties:
                type: boolean
            mcp:
              type: object
              additionalProperties:
                type: boolean
          required: [extensions, skills, instructions, mcp]
          additionalProperties: false
      required: [overrides, effective]
      additionalProperties: false
    SessionConfiguration:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        name:
          description: Explicit name. Null shows the automatic title for a root, or the family name for a child; the session representation carries the displayed name.
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        workspace:
          $ref: '#/components/schemas/Workspace'
        provider_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        preferences:
          type: object
          properties:
            pinned:
              type: boolean
            pin_order:
              anyOf:
              - $ref: '#/components/schemas/Counter'
              - type: 'null'
            archived:
              type: boolean
          required: [pinned, pin_order, archived]
          additionalProperties: false
        selection:
          $ref: '#/components/schemas/SelectionOverrides'
        revision:
          $ref: '#/components/schemas/ID'
        family_revision:
          $ref: '#/components/schemas/ID'
      required: [id, name, workspace, provider_profile, model, effort, preferences, selection, revision,
        family_revision]
      additionalProperties: false
      examples:
      - id: 01a0fcea-2b00-7000-8000-000000000001
        name: null
        workspace: /workspace/project
        provider_profile: personal
        model: example-model
        effort: null
        preferences:
          pinned: false
          pin_order: null
          archived: false
        selection:
          extensions: {}
          skills: {}
          instructions: {}
          mcp: {}
        revision: config-1
        family_revision: family-1
    SessionConfigurationResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/SessionConfiguration'
      required: [url, etag, value]
      additionalProperties: false
    SessionPatch:
      type: object
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        provider_profile:
          $ref: '#/components/schemas/ID'
        model:
          $ref: '#/components/schemas/ID'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        preferences:
          $ref: '#/components/schemas/PreferencePatch'
        selection:
          $ref: '#/components/schemas/SelectionPatch'
        catalog_revision:
          $ref: '#/components/schemas/ID'
      description: Skill and instruction changes require catalog_revision. All fields validate and commit
        together.
      additionalProperties: false
      examples:
      - selection:
          extensions:
            browser: null
          skills:
            candidate-1: false
        catalog_revision: discovery-1
    WorkspaceMoveRequest:
      type: object
      properties:
        workspace:
          $ref: '#/components/schemas/Workspace'
        family_revision:
          $ref: '#/components/schemas/ID'
      required: [workspace, family_revision]
      additionalProperties: false
      examples:
      - workspace: /workspace/other-project
        family_revision: family-1
    SessionChangeRequest:
      oneOf:
      - $ref: '#/components/schemas/SessionPatch'
      - $ref: '#/components/schemas/WorkspaceMoveRequest'
    NewSessionRequest:
      type: object
      properties:
        kind:
          const: new
        workspace:
          $ref: '#/components/schemas/Workspace'
        name:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        provider_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [kind, workspace]
      additionalProperties: false
      examples:
      - kind: new
        workspace: /workspace/project
    NewSessionIntent:
      type: object
      properties:
        kind:
          const: new
        workspace:
          $ref: '#/components/schemas/Workspace'
        name:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        provider_profile:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [kind, workspace, name, provider_profile, model, effort]
      additionalProperties: false
    ForkSessionRequest:
      type: object
      properties:
        kind:
          const: fork
        source_session_id:
          $ref: '#/components/schemas/ID'
        checkpoint_id:
          $ref: '#/components/schemas/ID'
        name:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
      required: [kind, source_session_id, checkpoint_id]
      additionalProperties: false
    ForkSessionIntent:
      type: object
      properties:
        kind:
          const: fork
        source_session_id:
          $ref: '#/components/schemas/ID'
        checkpoint_id:
          $ref: '#/components/schemas/ID'
        name:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
      required: [kind, source_session_id, checkpoint_id, name]
      additionalProperties: false
    ChildSessionRequest:
      type: object
      properties:
        kind:
          const: child
        parent_id:
          $ref: '#/components/schemas/ID'
        address:
          type: string
          minLength: 1
          maxLength: 512
        name:
          type: string
          minLength: 1
          maxLength: 4096
        initial_input_id:
          $ref: '#/components/schemas/UUIDv7'
        task:
          type: string
          minLength: 1
          maxLength: 32768
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [kind, parent_id, address, name, initial_input_id, task]
      additionalProperties: false
    ChildSessionIntent:
      type: object
      properties:
        kind:
          const: child
        parent_id:
          $ref: '#/components/schemas/ID'
        address:
          type: string
          minLength: 1
          maxLength: 512
        name:
          type: string
          minLength: 1
          maxLength: 4096
        initial_input_id:
          $ref: '#/components/schemas/UUIDv7'
        task:
          type: string
          minLength: 1
          maxLength: 32768
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        effort:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [kind, parent_id, address, name, initial_input_id, task, model, effort]
      additionalProperties: false
    SessionCreationRequest:
      oneOf:
      - $ref: '#/components/schemas/NewSessionRequest'
      - $ref: '#/components/schemas/ForkSessionRequest'
      - $ref: '#/components/schemas/ChildSessionRequest'
    Creation:
      type: object
      properties:
        submitted:
          oneOf:
          - $ref: '#/components/schemas/NewSessionIntent'
          - $ref: '#/components/schemas/ForkSessionIntent'
          - $ref: '#/components/schemas/ChildSessionIntent'
        resolved:
          type: object
          properties:
            workspace:
              $ref: '#/components/schemas/Workspace'
            provider_profile:
              anyOf:
              - $ref: '#/components/schemas/ID'
              - type: 'null'
            model:
              anyOf:
              - $ref: '#/components/schemas/ID'
              - type: 'null'
            effort:
              anyOf:
              - type: string
                maxLength: 100
              - type: 'null'
          required: [workspace, provider_profile, model, effort]
          additionalProperties: false
      required: [submitted, resolved]
      additionalProperties: false
    CreationDecision:
      type: object
      properties:
        kind:
          const: creation
        session_id:
          $ref: '#/components/schemas/ID'
        admission:
          type: string
          enum: [accepted, rejected]
        http_status:
          type: integer
          minimum: 200
          maximum: 599
        creation:
          anyOf:
          - $ref: '#/components/schemas/Creation'
          - type: 'null'
        decided_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        deleted_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
      required: [kind, session_id, admission, http_status, creation, decided_at, deleted_at]
      additionalProperties: false
    WorkspaceChange:
      type: object
      properties:
        desired:
          $ref: '#/components/schemas/Workspace'
        active:
          $ref: '#/components/schemas/Workspace'
        state:
          type: string
          enum: [deferred, applying]
        revision:
          $ref: '#/components/schemas/ID'
      required: [desired, active, state, revision]
      additionalProperties: false
    QuarantineDiagnostic:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        reason:
          $ref: '#/components/schemas/SafeReason'
      required: [id, reason]
      additionalProperties: false
    Composition:
      type: object
      properties:
        desired_revision:
          $ref: '#/components/schemas/ID'
        loaded_revision:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        needs_reload:
          type: boolean
        dependencies:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ID'
            maxItems: 200
        quarantine:
          type: array
          items:
            $ref: '#/components/schemas/QuarantineDiagnostic'
          maxItems: 200
        availability:
          type: object
          additionalProperties:
            type: boolean
      required: [desired_revision, loaded_revision, needs_reload, dependencies, quarantine, availability]
      additionalProperties: false
    JobCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/KernelJob'
          maxItems: 100
        live_job_count:
          $ref: '#/components/schemas/Counter'
        page:
          $ref: '#/components/schemas/PageDescriptor'
      required: [items, live_job_count, page]
      additionalProperties: false
      examples:
      - items: []
        live_job_count: 0
        page:
          title: jobs
          empty_state: no background jobs running
          rows: []
          glance: null
          actions: []
          summary: 0 background jobs running
    JobStop:
      type: object
      properties:
        stopped:
          $ref: '#/components/schemas/ID'
      required: [stopped]
      additionalProperties: false
      examples:
      - stopped: job-1
    KernelJob:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        pid:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        command:
          type: string
          maxLength: 4096
        started_at:
          $ref: '#/components/schemas/Counter'
          description: Wall-clock milliseconds since the epoch when the owner recorded the
            job. Zero when unknown, which clients treat as settled work.
      required: [id, pid, command, started_at]
      additionalProperties: false
    Kernel:
      type: object
      properties:
        state:
          type: string
          enum: [none, booting, attached, reattaching, lost]
        stage:
          anyOf:
          - type: string
            enum: [staging, starting]
          - type: 'null'
        build:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        stale:
          type: boolean
        staleness_reasons:
          type: array
          items:
            $ref: '#/components/schemas/SafeReason'
          maxItems: 100
        running_jobs:
          description: Up to 100 observed live jobs, ordered by ID. Null when the kernel owner is unavailable. The count may exceed this list.
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/KernelJob'
            maxItems: 100
          - type: 'null'
        live_job_count:
          description: Observed owned jobs. Null while booting or when the kernel owner is lost.
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        instance_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
      required: [state, stage, build, stale, staleness_reasons, live_job_count, running_jobs, instance_id]
      additionalProperties: false
    Usage:
      type: object
      properties:
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        observed_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        prompt_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        cached_prompt_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        cache_write_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        completion_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        total_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        elapsed_ms:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
        tokens_per_second:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
        context_window_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        cache_ttl_seconds:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        cache_fade:
          type: array
          items:
            type: object
            properties:
              at:
                $ref: '#/components/schemas/Timestamp'
              cached_tokens:
                anyOf:
                - $ref: '#/components/schemas/Counter'
                - type: 'null'
            required: [at, cached_tokens]
            additionalProperties: false
          maxItems: 200
      required: [model, observed_at, prompt_tokens, cached_prompt_tokens, cache_write_tokens, completion_tokens,
        total_tokens, elapsed_ms, tokens_per_second, context_window_tokens, cache_ttl_seconds, cache_fade]
      additionalProperties: false
    PendingInput:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [message, continue, skill, command]
        preview:
          $ref: '#/components/schemas/Preview'
        accepted_at:
          $ref: '#/components/schemas/Timestamp'
        acceptance_order:
          $ref: '#/components/schemas/Counter'
        delivery:
          const: pending
        blocking_reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [id, kind, preview, accepted_at, acceptance_order, delivery, blocking_reason]
      additionalProperties: false
    Glance:
      type: object
      properties:
        extension:
          $ref: '#/components/schemas/ID'
        title:
          type: string
          maxLength: 256
        rows:
          type: array
          items:
            $ref: '#/components/schemas/PageRow'
          maxItems: 12
        url:
          $ref: '#/components/schemas/ResourceURL'
        data:
          $ref: '#/components/schemas/DynamicJSON'
      x-max-encoded-bytes: 8192
      required: [extension, title, rows, url]
      additionalProperties: false
    Session:
      allOf:
      - $ref: '#/components/schemas/SessionSummary'
      - type: object
        properties:
          creation:
            description: Null only for stored sessions that predate immutable creation provenance. All newly admitted creations have provenance.
            anyOf:
            - $ref: '#/components/schemas/Creation'
            - type: 'null'
          revision:
            $ref: '#/components/schemas/ID'
          family_revision:
            $ref: '#/components/schemas/ID'
          configuration_resource:
            $ref: '#/components/schemas/SessionConfigurationResource'
          workspace_change:
            anyOf:
            - $ref: '#/components/schemas/WorkspaceChange'
            - type: 'null'
          selection:
            $ref: '#/components/schemas/SessionSelection'
          composition:
            $ref: '#/components/schemas/Composition'
          kernel:
            $ref: '#/components/schemas/Kernel'
          pending_inputs:
            type: array
            items:
              $ref: '#/components/schemas/PendingInput'
            maxItems: 32
          input_order:
            $ref: '#/components/schemas/Counter'
          usage:
            $ref: '#/components/schemas/Usage'
          active_output:
            type: array
            items:
              $ref: '#/components/schemas/ActiveOutput'
            maxItems: 256
          history:
            $ref: '#/components/schemas/HistoryPage'
          glances:
            type: array
            items:
              $ref: '#/components/schemas/Glance'
            maxItems: 16
        required: [creation, revision, family_revision, configuration_resource, workspace_change, selection,
          composition, kernel, pending_inputs, input_order, usage, history, glances, active_output]
      unevaluatedProperties: false
      x-max-encoded-bytes: 1048576
      examples:
      - id: 01a0fcea-2b00-7000-8000-000000000001
        name: New session
        automatic_name: New session
        workspace: /workspace/project
        location:
          host: null
          user: null
          path: /workspace/project
          label: null
        parent_id: null
        root_id: 01a0fcea-2b00-7000-8000-000000000001
        address: null
        depth: 0
        closed: false
        created_at: '2026-10-02T14:00:00Z'
        activity_at: '2026-10-02T14:00:00Z'
        provider_profile: personal
        model: example-model
        effort: null
        status:
          phase: idle
          run_id: null
          interrupt_requested: false
          blocking_reason: null
        preview:
          text: ''
          transcript_count: 0
          truncated: false
        preferences:
          pinned: false
          pin_order: null
          archived: false
          opens: 0
        current_progress: []
        active_output: []
        activity:
          lines: []
          output_scalars: 0
          output_utf8_bytes: 0
          observed_at: '2026-10-02T14:00:00Z'
          latest_input: null
          latest_answer: null
        cursor:
          generation: J6kYj6IGcXyP3eMIp-WL3A
          sequence: 0
        creation:
          submitted:
            kind: new
            workspace: /workspace/project
            name: null
            provider_profile: null
            model: null
            effort: null
          resolved:
            workspace: /workspace/project
            provider_profile: personal
            model: example-model
            effort: null
        revision: config-1
        family_revision: family-1
        configuration_resource:
          url: /sessions/01a0fcea-2b00-7000-8000-000000000001?view=configuration
          etag: '"session-config-1"'
          value:
            id: 01a0fcea-2b00-7000-8000-000000000001
            name: New session
            workspace: /workspace/project
            provider_profile: personal
            model: example-model
            effort: null
            preferences:
              pinned: false
              pin_order: null
              archived: false
            selection:
              extensions: {}
              skills: {}
              instructions: {}
              mcp: {}
            revision: config-1
            family_revision: family-1
        workspace_change: null
        selection:
          overrides:
            extensions: {}
            skills: {}
            instructions: {}
            mcp: {}
          effective:
            extensions: {}
            skills: {}
            instructions: {}
            mcp: {}
        composition:
          desired_revision: composition-1
          loaded_revision: null
          needs_reload: true
          dependencies: {}
          quarantine: []
          availability: {}
        kernel:
          instance_id: null
          state: none
          stage: null
          build: null
          stale: false
          staleness_reasons: []
          live_job_count: 0
          running_jobs: []
        pending_inputs: []
        input_order: 0
        usage:
          model: null
          observed_at: null
          prompt_tokens: null
          cached_prompt_tokens: null
          cache_write_tokens: null
          completion_tokens: null
          total_tokens: null
          elapsed_ms: null
          tokens_per_second: null
          context_window_tokens: null
          cache_ttl_seconds: null
          cache_fade: []
        history:
          items: []
          older: null
          newer: null
          high_water: 0
        glances: []
    SessionRead:
      oneOf:
      - $ref: '#/components/schemas/Session'
      - $ref: '#/components/schemas/SessionConfiguration'
    SessionChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/SessionConfigurationResource'
        session:
          $ref: '#/components/schemas/Session'
        move:
          anyOf:
          - type: object
            properties:
              applied_count:
                $ref: '#/components/schemas/Counter'
              deferred_count:
                $ref: '#/components/schemas/Counter'
              applied_ids:
                type: array
                items:
                  $ref: '#/components/schemas/ID'
                maxItems: 200
              deferred_ids:
                type: array
                items:
                  $ref: '#/components/schemas/ID'
                maxItems: 200
              truncated:
                type: boolean
              warnings:
                $ref: '#/components/schemas/Warnings'
            required: [applied_count, deferred_count, applied_ids, deferred_ids, truncated, warnings]
            additionalProperties: false
          - type: 'null'
      required: [resource, session, move]
      additionalProperties: false
    Visit:
      type: object
      properties:
        visit_id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        opens:
          $ref: '#/components/schemas/Counter'
      required: [visit_id, session_id, opens]
      additionalProperties: false
    SessionDeletion:
      type: object
      properties:
        state:
          type: string
          enum: [complete, partial]
        deleted_count:
          $ref: '#/components/schemas/Counter'
        remaining_count:
          $ref: '#/components/schemas/Counter'
        deleted_ids:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
        remaining:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/ID'
              reason:
                $ref: '#/components/schemas/SafeReason'
            required: [id, reason]
            additionalProperties: false
          maxItems: 200
        truncated:
          type: boolean
      description: Counts cover the complete captured operation. ID lists are bounded summaries, never
        false completion. Refresh the authoritative family or known tombstones if truncated; deletion
        is never repeated to page a result.
      required: [state, deleted_count, remaining_count, deleted_ids, remaining, truncated]
      additionalProperties: false
    ImageUpload:
      type: object
      properties:
        mime_type:
          type: string
          enum: [image/png, image/jpeg, image/gif, image/webp]
        data:
          type: string
          contentEncoding: base64
      description: Strict base64; decoded dimensions and provider constraints are validated before admission.
      required: [mime_type, data]
      additionalProperties: false
    MessageInputRequest:
      type: object
      properties:
        kind:
          const: message
        text:
          type: string
          maxLength: 1048576
        images:
          type: array
          description: Attached in order; the text's numbered image markers say where each was attached.
          items:
            $ref: '#/components/schemas/ImageUpload'
          maxItems: 10
        pastes:
          type: array
          description: Pasted text the text marks by number; a long one is saved to a file the model reads.
          items:
            type: string
          maxItems: 20
        client_id:
          type: string
          maxLength: 512
      required: [kind, text]
      additionalProperties: false
      anyOf:
      - properties:
          text:
            pattern: \S
      - required: [images]
        properties:
          images:
            minItems: 1
      examples:
      - kind: message
        text: Fix the parser.
        client_id: draft-1
    ContinueInputRequest:
      type: object
      properties:
        kind:
          const: continue
        client_id:
          type: string
          maxLength: 512
      required: [kind]
      additionalProperties: false
    SkillInputRequest:
      type: object
      properties:
        kind:
          const: skill
        candidate_id:
          $ref: '#/components/schemas/ID'
        catalog_revision:
          $ref: '#/components/schemas/ID'
        arguments:
          type: string
          maxLength: 1048576
        client_id:
          type: string
          maxLength: 512
      required: [kind, candidate_id, catalog_revision, arguments]
      additionalProperties: false
    CommandInputRequest:
      type: object
      properties:
        kind:
          const: command
        command_id:
          $ref: '#/components/schemas/ID'
        arguments:
          $ref: '#/components/schemas/DynamicJSON'
        client_id:
          type: string
          maxLength: 512
      required: [kind, command_id, arguments]
      additionalProperties: false
    InputRequest:
      oneOf:
      - $ref: '#/components/schemas/MessageInputRequest'
      - $ref: '#/components/schemas/ContinueInputRequest'
      - $ref: '#/components/schemas/SkillInputRequest'
      - $ref: '#/components/schemas/CommandInputRequest'
      x-max-encoded-bytes: 72200000
    Turn:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        state:
          type: string
          enum: [running, completed, interrupted, failed, abandoned]
        started_at:
          $ref: '#/components/schemas/Timestamp'
        ended_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        outcome:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [id, state, started_at, ended_at, outcome]
      additionalProperties: false
    Input:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [message, continue, skill, command]
        admission:
          type: string
          enum: [accepted, rejected]
        http_status:
          type: integer
          minimum: 200
          maximum: 599
        problem:
          anyOf:
          - $ref: '#/components/schemas/AdmissionProblem'
          - type: 'null'
        accepted_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        acceptance_order:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        delivery:
          anyOf:
          - type: string
            enum: [pending, committed, cancelled]
          - type: 'null'
        blocking_reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        transcript_position:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        turn:
          anyOf:
          - $ref: '#/components/schemas/Turn'
          - type: 'null'
        client_id:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
      required: [id, session_id, kind, admission, http_status, problem, accepted_at, acceptance_order,
        delivery, blocking_reason, transcript_position, turn, client_id]
      additionalProperties: false
      allOf:
      - if:
          properties:
            admission:
              const: rejected
        then:
          properties:
            delivery:
              type: 'null'
            accepted_at:
              type: 'null'
            acceptance_order:
              type: 'null'
            turn:
              type: 'null'
            http_status:
              type: integer
              minimum: 400
              maximum: 599
            problem:
              $ref: '#/components/schemas/AdmissionProblem'
        else:
          properties:
            delivery:
              type: string
              enum: [pending, committed, cancelled]
            accepted_at:
              $ref: '#/components/schemas/Timestamp'
            acceptance_order:
              type: integer
              minimum: 1
              maximum: 9007199254740991
            http_status:
              const: 202
            problem:
              type: 'null'
      examples:
      - id: 01a0fcea-2b00-7000-8000-000000000002
        session_id: 01a0fcea-2b00-7000-8000-000000000001
        kind: message
        admission: accepted
        http_status: 202
        problem: null
        accepted_at: '2026-10-02T14:00:00Z'
        acceptance_order: 1
        delivery: pending
        blocking_reason: null
        transcript_position: null
        turn: null
        client_id: draft-1
    InputDecision:
      type: object
      properties:
        kind:
          const: input
        input:
          $ref: '#/components/schemas/Input'
      required: [kind, input]
      additionalProperties: false
    InputCancellation:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/Input'
        result:
          type: string
          enum: [cancelled, interrupt_requested, shared_running, not_pending]
      required: [input, result]
      additionalProperties: false
    InterruptRequest:
      type: object
      properties:
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        through_input_order:
          $ref: '#/components/schemas/Counter'
      required: [run_id, through_input_order]
      additionalProperties: false
    Interruption:
      type: object
      properties:
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        state:
          type: string
          enum: [requested, already_ended]
        cancelled_input_ids:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 32
        warnings:
          $ref: '#/components/schemas/Warnings'
      required: [run_id, state, cancelled_input_ids, warnings]
      additionalProperties: false
    ToolActivity:
      type: object
      properties:
        kind:
          type: string
          enum: [read, search, list, run, web]
        target:
          type: string
          maxLength: 1000
        detail:
          type: string
          maxLength: 16000
          description: What the person watching sees of the result, as markdown; a web search's answer and sources.
      required: [kind, target]
      additionalProperties: false
    FileDiff:
      type: object
      properties:
        path:
          type: string
          maxLength: 1000
        kind:
          const: diff
        diff:
          type: string
          maxLength: 16000
        added:
          $ref: '#/components/schemas/Counter'
        removed:
          $ref: '#/components/schemas/Counter'
      required: [path, kind, diff, added, removed]
      additionalProperties: false
    FileUnavailable:
      type: object
      properties:
        path:
          type: string
          maxLength: 1000
        kind:
          const: unavailable
        reason:
          type: string
          maxLength: 1000
      required: [path, kind, reason]
      additionalProperties: false
    ToolTrace:
      type: object
      properties:
        activities:
          type: array
          items:
            $ref: '#/components/schemas/ToolActivity'
          maxItems: 64
        changes:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FileDiff'
            - $ref: '#/components/schemas/FileUnavailable'
          maxItems: 16
        truncated:
          type: boolean
      required: [activities, changes, truncated]
      additionalProperties: false
    ActiveOutput:
      type: object
      properties:
        message_id:
          $ref: '#/components/schemas/ID'
        run_id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [text, thinking]
        bytes:
          $ref: '#/components/schemas/Counter'
        elapsed_ms:
          type: [integer, 'null']
          minimum: 0
        text:
          type: [string, 'null']
        reference:
          anyOf:
          - $ref: '#/components/schemas/ContentReference'
          - type: 'null'
      required: [message_id, run_id, kind, bytes, elapsed_ms, text, reference]
      additionalProperties: false
      description: Ordered unfinished output captured with the session cursor. Exactly one of text or reference is non-null. References retain a fixed byte cutoff through their short snapshot lease. A run retains at most 64 MiB of unfinished output across at most 256 descriptors. Inline output is limited to 64 KiB encoded; larger content uses references.
    ContentReference:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        field:
          type: string
          minLength: 1
          maxLength: 256
        bytes:
          $ref: '#/components/schemas/Counter'
      required: [url, field, bytes]
      additionalProperties: false
    ImageMetadata:
      type: object
      properties:
        mime_type:
          type: string
          maxLength: 100
        width:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        height:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        original_bytes:
          $ref: '#/components/schemas/Counter'
        reference:
          $ref: '#/components/schemas/ContentReference'
          description: Its url is the image resource, which serves the decoded bytes.
      required: [mime_type, width, height, original_bytes, reference]
      additionalProperties: false
    TextContent:
      type: object
      properties:
        kind:
          const: text
        text:
          type: string
          maxLength: 262144
      required: [kind, text]
      additionalProperties: false
    JSONContent:
      type: object
      properties:
        kind:
          const: json
        field:
          type: string
          maxLength: 256
        value:
          $ref: '#/components/schemas/DynamicJSON'
      required: [kind, field, value]
      additionalProperties: false
    ImageContent:
      type: object
      properties:
        kind:
          const: image
        image:
          $ref: '#/components/schemas/ImageMetadata'
      required: [kind, image]
      additionalProperties: false
    TraceContent:
      type: object
      properties:
        kind:
          const: trace
        trace:
          $ref: '#/components/schemas/ToolTrace'
      required: [kind, trace]
      additionalProperties: false
    ReferenceContent:
      type: object
      properties:
        kind:
          const: reference
        reference:
          $ref: '#/components/schemas/ContentReference'
      required: [kind, reference]
      additionalProperties: false
    HistoryMail:
      type: object
      properties:
        mail_id:
          $ref: '#/components/schemas/ID'
        sender_session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        sender_label:
          type: string
        kind:
          type: string
          enum: [task, message, result, unreviewed, webhook]
      required: [mail_id, sender_session_id, sender_label, kind]
      additionalProperties: false
    HistoryEntry:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        position:
          $ref: '#/components/schemas/Counter'
        kind:
          type: string
          enum: [user, assistant, thinking, tool_call, tool_result, note, continuation, compaction, image_fit]
        turn_type:
          type: string
          enum: [user, agent, webhook, scheduled, continue]
        mail:
          anyOf:
          - $ref: '#/components/schemas/HistoryMail'
          - type: 'null'
        turn_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        input_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        created_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        content:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/TextContent'
            - $ref: '#/components/schemas/JSONContent'
            - $ref: '#/components/schemas/ImageContent'
            - $ref: '#/components/schemas/TraceContent'
            - $ref: '#/components/schemas/ReferenceContent'
          maxItems: 200
        checkpoint_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        content_complete:
          type: boolean
        tool:
          anyOf:
          - type: object
            properties:
              name:
                type: string
                maxLength: 100
              tool_call_id:
                $ref: '#/components/schemas/ID'
              progress_call_id:
                anyOf:
                - $ref: '#/components/schemas/ID'
                - type: 'null'
            required: [name, tool_call_id, progress_call_id]
            additionalProperties: false
          - type: 'null'
        thinking_duration_ms:
          description: Observed thinking duration, when recorded.
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
      required: [id, position, kind, turn_id, input_id, created_at, content, checkpoint_id, content_complete,
        tool]
      additionalProperties: false
    HistoryPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/HistoryEntry'
          maxItems: 200
        older:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        newer:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        high_water:
          $ref: '#/components/schemas/Counter'
      x-max-content-bytes: 262144
      required: [items, older, newer, high_water]
      additionalProperties: false
      examples:
      - items: []
        older: null
        newer: null
        high_water: 0
    Checkpoint:
      type: object
      properties:
        position:
          $ref: '#/components/schemas/Counter'
        checkpoint_id:
          $ref: '#/components/schemas/ID'
        title:
          type: string
          maxLength: 4096
        turn_type:
          type: string
          enum: [user, continue, agent, scheduled, webhook]
        preview:
          $ref: '#/components/schemas/Preview'
      required: [position, checkpoint_id, title, turn_type, preview]
      additionalProperties: false
    CheckpointPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Checkpoint'
          maxItems: 200
        older:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        newer:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        high_water:
          $ref: '#/components/schemas/Counter'
      required: [items, older, newer, high_water]
      additionalProperties: false
    HistoryRead:
      anyOf:
      - $ref: '#/components/schemas/HistoryPage'
      - $ref: '#/components/schemas/CheckpointPage'
      description: The requested view determines the item type. Empty pages are valid for either view.
    ContentPart:
      type: object
      properties:
        field:
          type: string
          maxLength: 256
        offset_bytes:
          $ref: '#/components/schemas/Counter'
        encoding:
          type: string
          enum: [utf8]
        text:
          type: string
          maxLength: 1048576
        complete:
          type: boolean
      description: Offsets count exact stored UTF-8 bytes.
      required: [field, offset_bytes, encoding, text, complete]
      additionalProperties: false
    EntryContentPage:
      type: object
      properties:
        entry_id:
          $ref: '#/components/schemas/ID'
        parts:
          type: array
          items:
            $ref: '#/components/schemas/ContentPart'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      x-max-decoded-content-bytes: 262144
      required: [entry_id, parts, next]
      additionalProperties: false
    ContextSection:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        kind:
          type: string
          enum: [instructions, extension_context, history, tools, other]
        source:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        item_count:
          $ref: '#/components/schemas/Counter'
        utf8_bytes:
          $ref: '#/components/schemas/Counter'
        page_count:
          $ref: '#/components/schemas/Counter'
        preview:
          $ref: '#/components/schemas/Preview'
      required: [id, label, kind, source, item_count, utf8_bytes, page_count, preview]
      additionalProperties: false
    ContextSummary:
      type: object
      properties:
        state:
          type: string
          enum: [pending, ready]
        snapshot_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        captured_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        provider:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        model:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        protocol:
          anyOf:
          - type: string
            enum: [responses, chat_completions]
          - type: 'null'
        context_window_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        compaction:
          $ref: '#/components/schemas/ContextCompaction'
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ContextSection'
          maxItems: 1000
        reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [state, snapshot_id, captured_at, provider, model, protocol, context_window_tokens, compaction,
        sections, reason]
      additionalProperties: false
      allOf:
      - if:
          properties:
            state:
              const: ready
        then:
          properties:
            snapshot_id:
              $ref: '#/components/schemas/ID'
            captured_at:
              $ref: '#/components/schemas/Timestamp'
            reason:
              type: 'null'
        else:
          properties:
            snapshot_id:
              type: 'null'
            reason:
              $ref: '#/components/schemas/SafeReason'
    ContextSectionPage:
      type: object
      properties:
        snapshot_id:
          $ref: '#/components/schemas/ID'
        section_id:
          $ref: '#/components/schemas/ID'
        text:
          type: string
          x-max-utf8-bytes: 32768
          maxLength: 32768
        omitted:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        page:
          $ref: '#/components/schemas/Counter'
        page_count:
          $ref: '#/components/schemas/Counter'
      required: [snapshot_id, section_id, text, omitted, page, page_count]
      additionalProperties: false
    TokenObservation:
      type: object
      properties:
        estimated:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        observed:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        source:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
      required: [estimated, observed, source]
      additionalProperties: false
    ProviderRequestRecord:
      type: object
      properties:
        sequence:
          $ref: '#/components/schemas/Counter'
        provider:
          $ref: '#/components/schemas/ID'
        model:
          $ref: '#/components/schemas/ID'
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        started_at:
          $ref: '#/components/schemas/Timestamp'
        ended_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        prompt_tokens:
          $ref: '#/components/schemas/TokenObservation'
        completion_tokens:
          $ref: '#/components/schemas/TokenObservation'
        cached_tokens:
          $ref: '#/components/schemas/TokenObservation'
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        kind:
          type: string
          enum: [turn, summarizer, background]
        provider_profile:
          $ref: '#/components/schemas/ID'
        account_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        outcome:
          type: string
          enum: [completed, failed]
        http_status:
          anyOf:
          - type: integer
            minimum: 100
            maximum: 599
          - type: 'null'
        cache_creation_tokens:
          $ref: '#/components/schemas/TokenObservation'
        cache_write_5m_tokens:
          $ref: '#/components/schemas/TokenObservation'
        cache_write_1h_tokens:
          $ref: '#/components/schemas/TokenObservation'
        reasoning_tokens:
          $ref: '#/components/schemas/TokenObservation'
        head_hash:
          type: string
          maxLength: 128
        input_count:
          $ref: '#/components/schemas/Counter'
        replaced_input_count:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        projection_hash:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
        strategy:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        cache_marks:
          type: array
          maxItems: 200
          items:
            type: object
            properties:
              through:
                type: string
                enum: [tools, system, input]
              index:
                anyOf:
                - $ref: '#/components/schemas/Counter'
                - type: 'null'
              ttl_seconds:
                $ref: '#/components/schemas/Counter'
            required: [through, index, ttl_seconds]
            additionalProperties: false
        transcript_positions:
          type: array
          items:
            $ref: '#/components/schemas/Counter'
          maxItems: 200
      required: [sequence, provider, model, run_id, started_at, ended_at, prompt_tokens, completion_tokens,
        cached_tokens, failure, transcript_positions, kind, provider_profile, account_id, outcome,
        http_status, cache_creation_tokens, cache_write_5m_tokens, cache_write_1h_tokens, reasoning_tokens,
        head_hash, input_count, replaced_input_count, projection_hash, strategy, cache_marks]
      additionalProperties: false
    RequestRecordPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProviderRequestRecord'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    ContextRead:
      oneOf:
      - $ref: '#/components/schemas/ContextSummary'
      - $ref: '#/components/schemas/ContextSectionPage'
      - $ref: '#/components/schemas/RequestRecordPage'
    FormField:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
        label:
          type: string
          maxLength: 256
        type:
          type: string
          enum: [text, secret, boolean, choice, integer, hidden]
        required:
          type: boolean
        default:
          $ref: '#/components/schemas/DynamicJSON'
        default_binding:
          description: Prefill from the selected row or installed session, before showing the form.
          type: object
          properties:
            source:
              type: string
              enum: [row, session]
            pointer:
              type: string
              pattern: ^(|/.*)$
              maxLength: 4096
          required: [source, pointer]
          additionalProperties: false
        choices:
          type: array
          items:
            type: object
            properties:
              value:
                $ref: '#/components/schemas/DynamicJSON'
              label:
                type: string
                maxLength: 256
            required: [value, label]
            additionalProperties: false
          maxItems: 200
        minimum:
          anyOf:
          - type: number
          - type: 'null'
        maximum:
          anyOf:
          - type: number
          - type: 'null'
        description:
          type: string
          maxLength: 4096
      required: [name, label, type, required, default, choices, minimum, maximum, description]
      additionalProperties: false
    Binding:
      oneOf:
      - type: object
        properties:
          source:
            const: literal
          value:
            $ref: '#/components/schemas/DynamicJSON'
        required: [source, value]
        additionalProperties: false
      - type: object
        properties:
          source:
            type: string
            enum: [row, form, session]
          pointer:
            type: string
            pattern: ^(|/.*)$
            maxLength: 4096
        required: [source, pointer]
        additionalProperties: false
      description: JSON pointer resolves against the selected row, submitted form, or installed session
        snapshot. No expression language.
    ActionOperation:
      type: object
      properties:
        operation_id:
          type: string
          minLength: 1
          maxLength: 256
        method:
          type: string
          enum: [GET, PUT, POST, PATCH, DELETE]
        path_template:
          $ref: '#/components/schemas/ResourceURL'
        path:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Binding'
        query:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Binding'
        headers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Binding'
        body:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Binding'
          propertyNames:
            type: string
            format: json-pointer
            pattern: ^/
        success_status:
          type: integer
          enum: [200, 201]
          description: Expected synchronous JSON success status. Omitted operations accept 200 or 201 for mutations and 200 for reads.
        result_schema:
          $ref: '#/components/schemas/DynamicJSON'
      description: Operation must be declared in this contract, or the installed extension contract version.
        Bind If-Match from the displayed resource, never from a fresh read. Path, query and header map
        keys name declared parameters; body map keys are JSON pointers into the request object. Missing
        optional form values omit their bindings. result_schema is a JSON Schema 2020-12 fragment, with
        no remote schema retrieval.
      required: [operation_id, method, path_template, path, query, headers, body, result_schema]
      additionalProperties: false
    PageAction:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        keyboard_hint:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
        confirmation:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FormField'
          maxItems: 100
        operation:
          $ref: '#/components/schemas/ActionOperation'
      required: [id, label, keyboard_hint, confirmation, fields, operation]
      additionalProperties: false
    PageRow:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        text:
          type: string
          maxLength: 4096
        badge:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        tone:
          type: string
          enum: [plain, active, muted, success, warning, error]
        detail:
          anyOf:
          - type: string
            maxLength: 16384
          - type: 'null'
        resource:
          anyOf:
          - type: object
            properties:
              url:
                $ref: '#/components/schemas/ResourceURL'
              etag:
                $ref: '#/components/schemas/ETag'
              value:
                $ref: '#/components/schemas/DynamicJSON'
            required: [url, etag, value]
            additionalProperties: false
          - type: 'null'
      required: [id, text, badge, tone, detail, resource]
      additionalProperties: false
    PageDescriptor:
      type: object
      properties:
        title:
          type: string
          maxLength: 256
        empty_state:
          type: string
          maxLength: 4096
        rows:
          type: array
          items:
            $ref: '#/components/schemas/PageRow'
          maxItems: 200
        glance:
          anyOf:
          - $ref: '#/components/schemas/Glance'
          - type: 'null'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/PageAction'
          maxItems: 100
        summary:
          type: string
          maxLength: 4096
      required: [title, empty_state, rows, glance, actions, summary]
      additionalProperties: false
    CatalogCandidate:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [extension, skill, instruction, mcp]
        title:
          type: string
          maxLength: 256
        description:
          type: string
          maxLength: 4096
        source:
          type: string
          maxLength: 4096
        resolved_source:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        preference_key:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        valid:
          type: boolean
        eligible:
          type: boolean
        effective_enabled:
          type: boolean
        global_preference:
          anyOf:
          - type: boolean
          - type: 'null'
        session_override:
          anyOf:
          - type: boolean
          - type: 'null'
        shadowed_by:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        dependencies:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
        quarantined:
          type: boolean
        diagnostic:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        extension:
          description: Installed extension metadata for the inspector. Null for other candidate kinds.
          anyOf:
          - $ref: '#/components/schemas/ExtensionMetadata'
          - type: 'null'
      x-max-encoded-bytes: 65536
      required: [id, kind, title, description, source, resolved_source, preference_key, valid, eligible,
        effective_enabled, global_preference, session_override, shadowed_by, dependencies, quarantined,
        diagnostic, extension]
      additionalProperties: false
    ExtensionMetadata:
      type: object
      properties:
        context:
          type: boolean
        tools:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/ID'
        python_modules:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/ID'
        plugins:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/ID'
      required: [context, tools, python_modules, plugins]
      additionalProperties: false
    HTTPCommand:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        slash_name:
          type: string
          maxLength: 256
        description:
          type: string
          maxLength: 4096
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/FormField'
          maxItems: 100
        caller_permissions:
          type: array
          items:
            type: string
            enum: [human, model]
          maxItems: 2
        delivery:
          type: string
          enum: [read, mutation]
        operation:
          $ref: '#/components/schemas/ActionOperation'
      required: [id, slash_name, description, arguments, caller_permissions, delivery, operation]
      additionalProperties: false
    InputCommand:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        slash_name:
          type: string
          maxLength: 256
        description:
          type: string
          maxLength: 4096
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/FormField'
          maxItems: 100
        caller_permissions:
          type: array
          items:
            type: string
            enum: [human, model]
          maxItems: 2
        delivery:
          const: input
        command_id:
          $ref: '#/components/schemas/ID'
      required: [id, slash_name, description, arguments, caller_permissions, delivery, command_id]
      additionalProperties: false
    Catalog:
      type: object
      properties:
        native_commands:
          type: array
          items:
            $ref: '#/components/schemas/HTTPCommand'
          maxItems: 200
          description: Static HTTP declarations for selected extensions when no composition has
            been loaded. Reading these declarations does not prepare extensions or start a kernel.
        discovery:
          type: [object, 'null']
          properties:
            revision:
              $ref: '#/components/schemas/ID'
            workspace:
              $ref: '#/components/schemas/Workspace'
            candidates:
              type: array
              items:
                $ref: '#/components/schemas/CatalogCandidate'
              maxItems: 200
            diagnostics:
              type: array
              items:
                $ref: '#/components/schemas/SafeReason'
              maxItems: 200
            next:
              anyOf:
              - $ref: '#/components/schemas/PageToken'
              - type: 'null'
          required: [revision, workspace, candidates, diagnostics, next]
          additionalProperties: false
        discovery_failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        loaded:
          type: object
          properties:
            revision:
              anyOf:
              - $ref: '#/components/schemas/ID'
              - type: 'null'
            commands:
              type: array
              items:
                oneOf:
                - $ref: '#/components/schemas/HTTPCommand'
                - $ref: '#/components/schemas/InputCommand'
              maxItems: 200
            next:
              anyOf:
              - $ref: '#/components/schemas/PageToken'
              - type: 'null'
          required: [revision, commands, next]
          additionalProperties: false
        pages:
          type: array
          items:
            $ref: '#/components/schemas/PageDescriptor'
          maxItems: 16
      description: Pagination is independent for discovered candidates and loaded commands; next tokens
        identify their section.
      required: [discovery, discovery_failure, loaded]
      additionalProperties: false
    SessionReloadOutcome:
      type: object
      properties:
        state:
          type: string
          enum: [applied, failed, skipped]
        loaded_revision:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        restart_required:
          type: boolean
        warnings:
          $ref: '#/components/schemas/Warnings'
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [state, loaded_revision, restart_required, warnings, failure]
      additionalProperties: false
    ModelReloadOutcome:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ID'
        state:
          type: string
          enum: [refreshed, failed, skipped]
        observed_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [provider, state, observed_at, failure]
      additionalProperties: false
    CachePolicyReloadOutcome:
      type: object
      properties:
        state:
          type: string
          enum: [refreshed, failed]
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [state, failure]
      additionalProperties: false
    ReloadRequest:
      type: object
      properties:
        target:
          type: string
          enum: [session, models, both]
          default: both
      additionalProperties: false
    ReloadResult:
      type: object
      properties:
        cache_policy:
          anyOf:
          - $ref: '#/components/schemas/CachePolicyReloadOutcome'
          - type: 'null'
        session:
          anyOf:
          - $ref: '#/components/schemas/SessionReloadOutcome'
          - type: 'null'
        models:
          type: array
          items:
            $ref: '#/components/schemas/ModelReloadOutcome'
          maxItems: 200
      required: [session, models, cache_policy]
      additionalProperties: false
    KernelUpgradeResult:
      type: object
      properties:
        old_build:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        new_build:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        state:
          type: string
          enum: [upgraded, unchanged, failed]
        stopped_jobs:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/ID'
              reason:
                $ref: '#/components/schemas/SafeReason'
            required: [id, reason]
            additionalProperties: false
          maxItems: 200
        warnings:
          $ref: '#/components/schemas/Warnings'
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        old_kernel_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        new_kernel_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
      required: [old_build, new_build, state, stopped_jobs, warnings, failure, old_kernel_id, new_kernel_id]
      additionalProperties: false
    CompactionRequest:
      type: object
      properties:
        strategy:
          $ref: '#/components/schemas/ID'
      additionalProperties: false
    CompactionObservation:
      type: object
      properties:
        strategy:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        before_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        after_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        evicted_entries:
          $ref: '#/components/schemas/Counter'
        summary:
          type: string
          maxLength: 32768
      required: [strategy, before_tokens, after_tokens, evicted_entries, summary]
      additionalProperties: false
    CompactionResult:
      type: object
      properties:
        selection_applied:
          type: boolean
        effective_strategy:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        state:
          type: string
          enum: [compacted, unchanged, failed]
        observation:
          anyOf:
          - $ref: '#/components/schemas/CompactionObservation'
          - type: 'null'
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [selection_applied, effective_strategy, state, observation, failure]
      additionalProperties: false
    Model:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        efforts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                maxLength: 100
              label:
                type: string
                maxLength: 256
            required: [id, label]
            additionalProperties: false
          maxItems: 100
        default_context_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        effective_context_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        max_context_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        max_output_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        input_modalities:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 100
          maxItems: 32
        image_edge:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 65536
          - type: 'null'
        raised:
          type: boolean
        cap_key:
          $ref: '#/components/schemas/ID'
        cache_policy:
          type: object
          properties:
            ttl_seconds:
              anyOf:
              - $ref: '#/components/schemas/Counter'
              - type: 'null'
            source:
              anyOf:
              - type: string
                maxLength: 256
              - type: 'null'
          required: [ttl_seconds, source]
          additionalProperties: false
        source:
          type: string
          maxLength: 256
        observed_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
      required: [id, label, efforts, default_context_tokens, effective_context_tokens, max_context_tokens,
        max_output_tokens, input_modalities, image_edge, raised, cap_key, cache_policy, source, observed_at]
      additionalProperties: false
    CachePolicyEntry:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        layer:
          type: string
          enum:
          - default
          - remote
          - local
        match:
          type: object
          properties:
            extension:
              anyOf:
              - type: array
                items:
                  type: string
                  maxLength: 4096
                maxItems: 100
              - type: 'null'
            host:
              anyOf:
              - type: array
                items:
                  type: string
                  maxLength: 4096
                maxItems: 100
              - type: 'null'
            model:
              anyOf:
              - type: array
                items:
                  type: string
                  maxLength: 4096
                maxItems: 100
              - type: 'null'
          required:
          - extension
          - host
          - model
          additionalProperties: false
        policy:
          type: string
          enum:
          - refresh
          - fixed
          - evict
          - unknown
        clock:
          type: string
          enum:
          - request
          - response
        tiers:
          anyOf:
          - type: array
            maxItems: 32
            items:
              type: object
              properties:
                seconds:
                  $ref: '#/components/schemas/Counter'
                write:
                  anyOf:
                  - type: number
                    minimum: 0
                  - type: 'null'
              required:
              - seconds
              - write
              additionalProperties: false
          - type: 'null'
        read:
          anyOf:
          - type: number
            minimum: 0
          - type: 'null'
        survival:
          anyOf:
          - type: object
            properties:
              typical:
                $ref: '#/components/schemas/Counter'
              max:
                anyOf:
                - $ref: '#/components/schemas/Counter'
                - type: 'null'
            required:
            - typical
            - max
            additionalProperties: false
          - type: 'null'
        evidence:
          type: string
          enum:
          - documented
          - measured
          - implemented
          - folklore
          - unknown
        source:
          type: string
          maxLength: 4096
        checked:
          type: string
          maxLength: 100
        note:
          type: string
          maxLength: 16384
      required:
      - id
      - layer
      - match
      - policy
      - clock
      - tiers
      - read
      - survival
      - evidence
      - source
      - checked
      - note
      additionalProperties: false
    CachePolicyLayer:
      type: object
      properties:
        name:
          type: string
          enum:
          - default
          - remote
          - local
        path:
          type: string
          maxLength: 16384
        loaded:
          type: boolean
        error:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required:
      - name
      - path
      - loaded
      - error
      additionalProperties: false
    CachePolicyPage:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/CachePolicyEntry'
          maxItems: 200
        layers:
          type: array
          items:
            $ref: '#/components/schemas/CachePolicyLayer'
          maxItems: 3
        matched:
          anyOf:
          - $ref: '#/components/schemas/CachePolicyEntry'
          - type: 'null'
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required:
      - entries
      - layers
      - matched
      - next
      additionalProperties: false
    ModelRead:
      oneOf:
      - $ref: '#/components/schemas/ModelPage'
      - $ref: '#/components/schemas/CachePolicyPage'
    ModelPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Model'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    Host:
      type: object
      properties:
        step:
          description: Current probe progress. Null when connecting or when no probe is running.
          anyOf:
          - type: string
            enum: [staging]
          - type: 'null'
        target:
          $ref: '#/components/schemas/ID'
        state:
          type: string
          enum: [unknown, probing, ready, needs_auth, unreachable, unsupported]
        detail:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        observed_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        os:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        architecture:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        home:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        authentication:
          anyOf:
          - type: object
            properties:
              instructions:
                type: string
                maxLength: 4096
              ssh_target:
                type: string
                maxLength: 4096
              control_path:
                anyOf:
                - type: string
                  maxLength: 4096
                - type: 'null'
            required: [instructions, ssh_target, control_path]
            additionalProperties: false
          - type: 'null'
      required: [target, state, detail, observed_at, os, architecture, home, authentication]
      additionalProperties: false
    HostPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Host'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    RecentWorkspace:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Workspace'
        use_count:
          $ref: '#/components/schemas/Counter'
        activity_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
      required: [location, use_count, activity_at]
      additionalProperties: false
    RecentWorkspacePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RecentWorkspace'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    TreeChild:
      type: object
      properties:
        name:
          type: string
          maxLength: 4096
        kind:
          type: string
          enum: [file, directory, symlink]
        location:
          $ref: '#/components/schemas/Workspace'
        language:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        changed:
          $ref: '#/components/schemas/Counter'
      required: [name, kind, location, language, changed]
      additionalProperties: false
    TreeEntry:
      type: object
      properties:
        name:
          type: string
          maxLength: 4096
        kind:
          type: string
          enum: [file, directory, symlink]
        location:
          $ref: '#/components/schemas/Workspace'
        children:
          type: array
          items:
            $ref: '#/components/schemas/TreeChild'
          maxItems: 4
        more:
          $ref: '#/components/schemas/Counter'
        language:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        changed:
          $ref: '#/components/schemas/Counter'
      required: [name, kind, location, children, more, language, changed]
      additionalProperties: false
    GitFacts:
      type: object
      properties:
        kind:
          const: git
        branch:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        revision:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        dirty:
          anyOf:
          - type: boolean
          - type: 'null'
        added:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        modified:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        removed:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        root:
          $ref: '#/components/schemas/Workspace'
        changed:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        touched_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
      required: [kind, branch, revision, dirty, added, modified, removed, root, changed, touched_at]
      additionalProperties: false
    JJFacts:
      type: object
      properties:
        kind:
          const: jj
        change_id:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        revision:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
        description:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        dirty:
          anyOf:
          - type: boolean
          - type: 'null'
        conflicts:
          anyOf:
          - type: boolean
          - type: 'null'
        root:
          $ref: '#/components/schemas/Workspace'
        changed:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        touched_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        bookmark:
          anyOf:
          - type: object
            properties:
              name:
                type: string
                maxLength: 4096
              ahead:
                $ref: '#/components/schemas/Counter'
            required: [name, ahead]
            additionalProperties: false
          - type: 'null'
      required: [kind, change_id, revision, description, dirty, conflicts, root, changed, touched_at,
        bookmark]
      additionalProperties: false
    WorkspacePreview:
      type: object
      properties:
        repository:
          anyOf:
          - oneOf:
            - $ref: '#/components/schemas/GitFacts'
            - $ref: '#/components/schemas/JJFacts'
          - type: 'null'
        repository_diagnostic:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
        languages:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 256
              bytes:
                $ref: '#/components/schemas/Counter'
              share:
                type: number
                minimum: 0
                maximum: 1
              color:
                anyOf:
                - type: string
                  pattern: ^#[0-9a-fA-F]{6}$
                - type: 'null'
            required: [name, bytes, share, color]
            additionalProperties: false
          maxItems: 100
        tree:
          type: array
          items:
            $ref: '#/components/schemas/TreeEntry'
          maxItems: 12
        more:
          $ref: '#/components/schemas/Counter'
      required: [repository, repository_diagnostic, languages, tree, more]
      additionalProperties: false
    WorkspaceDirectory:
      type: object
      properties:
        directory:
          $ref: '#/components/schemas/Workspace'
        parent:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        home:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        host:
          anyOf:
          - $ref: '#/components/schemas/Host'
          - type: 'null'
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 4096
              location:
                $ref: '#/components/schemas/Workspace'
              vcs:
                anyOf:
                - type: string
                  enum: [git, jj]
                - type: 'null'
              modified_at:
                anyOf:
                - $ref: '#/components/schemas/Timestamp'
                - type: 'null'
              hidden:
                type: boolean
            required: [name, location, vcs, modified_at, hidden]
            additionalProperties: false
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        preview:
          $ref: '#/components/schemas/WorkspacePreview'
      required: [directory, parent, home, host, items, next]
      additionalProperties: false
    WorkspaceRead:
      oneOf:
      - $ref: '#/components/schemas/RecentWorkspacePage'
      - $ref: '#/components/schemas/WorkspaceDirectory'
    Account:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        provider:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        detail:
          type: string
          maxLength: 4096
        kind:
          type: string
          enum: [model, service]
          default: model
        selected_by_profiles:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
      required: [id, provider, label, detail, kind, selected_by_profiles]
      additionalProperties: false
    LoginProvider:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        detail:
          type: string
          maxLength: 4096
        kind:
          type: string
          enum: [model, service]
          default: model
        flows:
          type: array
          items:
            type: string
            enum: [browser, manual, device, form]
          maxItems: 4
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FormField'
          maxItems: 100
      required: [id, label, detail, kind, flows, fields]
      additionalProperties: false
    Auth:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/LoginProvider'
          maxItems: 200
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
          maxItems: 200
      required: [providers, accounts]
      additionalProperties: false
    LoginRequest:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ID'
        flow:
          type: string
          enum: [browser, manual, device, form]
        values:
          type: object
          additionalProperties:
            type: [string, boolean, integer]
      description: Flow defaults to the provider preferred flow. Form names, types and required values
        are checked against that provider declaration. Values are write-only.
      required: [provider, values]
      additionalProperties: false
    LoginPatch:
      type: object
      properties:
        response:
          type: string
          minLength: 1
          writeOnly: true
          maxLength: 16384
      required: [response]
      additionalProperties: false
    Login:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        provider:
          $ref: '#/components/schemas/ID'
        url:
          anyOf:
          - type: string
            format: uri
            maxLength: 4096
          - type: 'null'
        expires_at:
          $ref: '#/components/schemas/Timestamp'
        state:
          type: string
          enum: [waiting, exchanging, complete, failed, cancelled, expired]
        instructions:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
        progress:
          type: string
          maxLength: 4096
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
          maxItems: 200
        failure:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [id, provider, url, expires_at, state, instructions, progress, accounts, failure]
      additionalProperties: false
      examples:
      - id: 01a0fcea-2b00-7000-8000-000000000003
        provider: example-provider
        url: https://provider.example/authorize?state=synthetic-state
        expires_at: '2026-10-02T14:15:00Z'
        state: waiting
        instructions: Paste the callback URL if the browser cannot reach the daemon.
        progress: Waiting for authorization.
        accounts: []
        failure: null
    MailMetadata:
      type: object
      properties:
        mail_id:
          $ref: '#/components/schemas/ID'
        sender_session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        receiver_session_id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [task, message, result, unreviewed, webhook]
        bytes:
          $ref: '#/components/schemas/Counter'
        sender_label:
          anyOf:
          - type: string
            x-max-utf8-bytes: 400
            maxLength: 100
          - type: 'null'
      required: [mail_id, sender_session_id, receiver_session_id, kind, bytes, sender_label]
      additionalProperties: false
    SessionStatusEvent:
      type: object
      properties:
        type:
          const: status
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          $ref: '#/components/schemas/SessionStatus'
      required: [type, sequence, data]
      additionalProperties: false
    SessionInputEvent:
      type: object
      properties:
        type:
          const: input
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            input:
              $ref: '#/components/schemas/Input'
          required: [input]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionTextEvent:
      type: object
      properties:
        type:
          const: text
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            run_id:
              $ref: '#/components/schemas/ID'
            message_id:
              $ref: '#/components/schemas/ID'
            text:
              type: string
              maxLength: 262144
          required: [run_id, message_id, text]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionThinkingEvent:
      type: object
      properties:
        type:
          const: thinking
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            run_id:
              $ref: '#/components/schemas/ID'
            message_id:
              $ref: '#/components/schemas/ID'
            text:
              type: string
              maxLength: 262144
            elapsed_ms:
              description: Completed thinking duration, when observed.
              $ref: '#/components/schemas/Counter'
          required: [run_id, message_id, text]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionMessageEvent:
      type: object
      properties:
        type:
          const: message
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            entry:
              $ref: '#/components/schemas/HistoryEntry'
          required: [entry]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionToolProgressEvent:
      type: object
      properties:
        type:
          const: tool_progress
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            progress:
              anyOf:
              - $ref: '#/components/schemas/ToolProgress'
              - type: 'null'
          required: [progress]
          additionalProperties: false
      x-max-encoded-bytes: 8192
      required: [type, sequence, data]
      additionalProperties: false
    SessionToolEvent:
      type: object
      properties:
        type:
          const: tool
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            tool_call_id:
              $ref: '#/components/schemas/ID'
            progress_call_id:
              $ref: '#/components/schemas/ID'
            name:
              type: string
              maxLength: 100
            arguments:
              $ref: '#/components/schemas/DynamicJSON'
            result:
              $ref: '#/components/schemas/DynamicJSON'
            trace:
              anyOf:
              - $ref: '#/components/schemas/ToolTrace'
              - type: 'null'
            content_complete:
              type: boolean
            reference:
              anyOf:
              - $ref: '#/components/schemas/ContentReference'
              - type: 'null'
          required: [tool_call_id, progress_call_id, name, arguments, result, trace, content_complete,
            reference]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionNoteEvent:
      type: object
      properties:
        type:
          const: note
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            entry_id:
              $ref: '#/components/schemas/ID'
            origin:
              type: string
              maxLength: 256
            text:
              type: string
              maxLength: 262144
            mail:
              anyOf:
              - $ref: '#/components/schemas/MailMetadata'
              - type: 'null'
          required: [entry_id, origin, text, mail]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionRetryEvent:
      type: object
      properties:
        type:
          const: retry
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            run_id:
              $ref: '#/components/schemas/ID'
            attempt:
              type: integer
              minimum: 1
              maximum: 9007199254740991
            reason:
              $ref: '#/components/schemas/SafeReason'
            delay_ms:
              $ref: '#/components/schemas/Counter'
          required: [run_id, attempt, reason, delay_ms]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionUsageEvent:
      type: object
      properties:
        type:
          const: usage
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          $ref: '#/components/schemas/Usage'
      required: [type, sequence, data]
      additionalProperties: false
    SessionCommittedEvent:
      type: object
      properties:
        type:
          const: committed
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            high_water:
              $ref: '#/components/schemas/Counter'
            replaces_all_live:
              type: boolean
              description: Retire all provisional output for a model commit.
            replaces_live_ids:
              type: array
              items:
                $ref: '#/components/schemas/ID'
              maxItems: 256
          required: [high_water, replaces_live_ids, replaces_all_live]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionTurnCompletedEvent:
      type: object
      properties:
        type:
          const: turn_completed
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            run_id:
              $ref: '#/components/schemas/ID'
            state:
              type: string
              enum: [completed, interrupted, failed, abandoned]
            input_ids:
              type: array
              items:
                $ref: '#/components/schemas/ID'
              maxItems: 200
            input_count:
              $ref: '#/components/schemas/Counter'
            truncated:
              type: boolean
          required: [run_id, state, input_ids, input_count, truncated]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionCompactedEvent:
      type: object
      properties:
        type:
          const: compacted
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          $ref: '#/components/schemas/CompactionObservation'
      required: [type, sequence, data]
      additionalProperties: false
    SessionErrorEvent:
      type: object
      properties:
        type:
          const: error
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            run_id:
              anyOf:
              - $ref: '#/components/schemas/ID'
              - type: 'null'
            code:
              type: string
              maxLength: 100
            message:
              type: string
              maxLength: 4096
          required: [run_id, code, message]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionInvalidateEvent:
      type: object
      properties:
        type:
          const: invalidate
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            kind:
              type: string
              enum: [session, settings, catalog, context, extension]
            url:
              $ref: '#/components/schemas/ResourceURL'
          required: [kind, url]
          additionalProperties: false
      required: [type, sequence, data]
      additionalProperties: false
    SessionEvent:
      oneOf:
      - $ref: '#/components/schemas/SessionStatusEvent'
      - $ref: '#/components/schemas/SessionInputEvent'
      - $ref: '#/components/schemas/SessionTextEvent'
      - $ref: '#/components/schemas/SessionThinkingEvent'
      - $ref: '#/components/schemas/SessionMessageEvent'
      - $ref: '#/components/schemas/SessionToolProgressEvent'
      - $ref: '#/components/schemas/SessionToolEvent'
      - $ref: '#/components/schemas/SessionNoteEvent'
      - $ref: '#/components/schemas/SessionRetryEvent'
      - $ref: '#/components/schemas/SessionUsageEvent'
      - $ref: '#/components/schemas/SessionCommittedEvent'
      - $ref: '#/components/schemas/SessionTurnCompletedEvent'
      - $ref: '#/components/schemas/SessionCompactedEvent'
      - $ref: '#/components/schemas/SessionErrorEvent'
      - $ref: '#/components/schemas/SessionInvalidateEvent'
    ResetEvent:
      type: object
      properties:
        type:
          const: reset
        data:
          type: object
          properties:
            reason:
              type: string
              enum: [initial, generation_changed, replay_unavailable, recovery]
          required: [reason]
          additionalProperties: false
      required: [type, data]
      additionalProperties: false
    FailureEvent:
      type: object
      properties:
        type:
          const: failure
        data:
          $ref: '#/components/schemas/SafeReason'
      required: [type, data]
      additionalProperties: false
    ReplayBatch:
      type: object
      properties:
        generation:
          $ref: '#/components/schemas/Generation'
        cursor:
          $ref: '#/components/schemas/Counter'
        events:
          type: array
          items:
            $ref: '#/components/schemas/SessionEvent'
          maxItems: 256
      description: Empty keepalive keeps the last sequence. Nonempty event sequences are contiguous from
        the requested cursor.
      required: [generation, cursor, events]
      additionalProperties: false
      examples:
      - generation: J6kYj6IGcXyP3eMIp-WL3A
        cursor: 1
        events:
        - type: input
          sequence: 1
          data:
            input:
              id: 01a0fcea-2b00-7000-8000-000000000002
              session_id: 01a0fcea-2b00-7000-8000-000000000001
              kind: message
              admission: accepted
              http_status: 202
              problem: null
              accepted_at: '2026-10-02T14:00:00Z'
              acceptance_order: 1
              delivery: pending
              blocking_reason: null
              transcript_position: null
              turn: null
              client_id: draft-1
    ResetBatch:
      type: object
      properties:
        generation:
          $ref: '#/components/schemas/Generation'
        cursor:
          $ref: '#/components/schemas/Counter'
        events:
          type: array
          prefixItems:
          - $ref: '#/components/schemas/ResetEvent'
          items:
            $ref: '#/components/schemas/SessionEvent'
          minItems: 1
          maxItems: 256
        snapshot:
          $ref: '#/components/schemas/Session'
      description: Leading reset and complete snapshot. Later events, if any, follow the snapshot cursor.
        Envelope cursor advances through every delivered event.
      required: [generation, cursor, events, snapshot]
      additionalProperties: false
      examples:
      - generation: J6kYj6IGcXyP3eMIp-WL3A
        cursor: 0
        events:
        - type: reset
          data:
            reason: initial
        snapshot:
          id: 01a0fcea-2b00-7000-8000-000000000001
          name: New session
          automatic_name: New session
          workspace: /workspace/project
          location:
            host: null
            user: null
            path: /workspace/project
            label: null
          parent_id: null
          root_id: 01a0fcea-2b00-7000-8000-000000000001
          address: null
          depth: 0
          closed: false
          created_at: '2026-10-02T14:00:00Z'
          activity_at: '2026-10-02T14:00:00Z'
          provider_profile: personal
          model: example-model
          effort: null
          status:
            phase: idle
            run_id: null
            interrupt_requested: false
            blocking_reason: null
          preview:
            text: ''
            transcript_count: 0
            truncated: false
          preferences:
            pinned: false
            pin_order: null
            archived: false
            opens: 0
          current_progress: []
          active_output: []
          activity:
            lines: []
            output_scalars: 0
            output_utf8_bytes: 0
            observed_at: '2026-10-02T14:00:00Z'
            latest_input: null
            latest_answer: null
          cursor:
            generation: J6kYj6IGcXyP3eMIp-WL3A
            sequence: 0
          creation:
            submitted:
              kind: new
              workspace: /workspace/project
              name: null
              provider_profile: null
              model: null
              effort: null
            resolved:
              workspace: /workspace/project
              provider_profile: personal
              model: example-model
              effort: null
          revision: config-1
          family_revision: family-1
          configuration_resource:
            url: /sessions/01a0fcea-2b00-7000-8000-000000000001?view=configuration
            etag: '"session-config-1"'
            value:
              id: 01a0fcea-2b00-7000-8000-000000000001
              name: New session
              workspace: /workspace/project
              provider_profile: personal
              model: example-model
              effort: null
              preferences:
                pinned: false
                pin_order: null
                archived: false
              selection:
                extensions: {}
                skills: {}
                instructions: {}
                mcp: {}
              revision: config-1
              family_revision: family-1
          workspace_change: null
          selection:
            overrides:
              extensions: {}
              skills: {}
              instructions: {}
              mcp: {}
            effective:
              extensions: {}
              skills: {}
              instructions: {}
              mcp: {}
          composition:
            desired_revision: composition-1
            loaded_revision: null
            needs_reload: true
            dependencies: {}
            quarantine: []
            availability: {}
          kernel:
            instance_id: null
            state: none
            stage: null
            build: null
            stale: false
            staleness_reasons: []
            live_job_count: 0
            running_jobs: []
          pending_inputs: []
          input_order: 0
          usage:
            model: null
            observed_at: null
            prompt_tokens: null
            cached_prompt_tokens: null
            cache_write_tokens: null
            completion_tokens: null
            total_tokens: null
            elapsed_ms: null
            tokens_per_second: null
            context_window_tokens: null
            cache_ttl_seconds: null
            cache_fade: []
          history:
            items: []
            older: null
            newer: null
            high_water: 0
          glances: []
    FailureBatch:
      type: object
      properties:
        generation:
          $ref: '#/components/schemas/Generation'
        cursor:
          $ref: '#/components/schemas/Counter'
        events:
          type: array
          items:
            $ref: '#/components/schemas/FailureEvent'
          minItems: 1
          maxItems: 1
      description: Terminal failure, alone with no snapshot. It does not commit a replacement cursor.
      required: [generation, cursor, events]
      additionalProperties: false
      examples:
      - generation: J6kYj6IGcXyP3eMIp-WL3A
        cursor: 0
        events:
        - type: failure
          data:
            code: history_unavailable
            detail: Durable history could not be loaded.
    SessionBatch:
      oneOf:
      - $ref: '#/components/schemas/ReplayBatch'
      - $ref: '#/components/schemas/ResetBatch'
      - $ref: '#/components/schemas/FailureBatch'
      x-max-encoded-bytes: 1048576
    ActivityEvent:
      type: object
      properties:
        type:
          const: activity
        data:
          type: object
          properties:
            session_id:
              $ref: '#/components/schemas/ID'
            cursor:
              $ref: '#/components/schemas/Cursor'
            status:
              $ref: '#/components/schemas/SessionStatus'
            current_progress:
              type: array
              items:
                $ref: '#/components/schemas/ToolProgress'
              maxItems: 32
            activity:
              $ref: '#/components/schemas/Activity'
          required: [session_id, cursor, status, current_progress, activity]
          additionalProperties: false
      required: [type, data]
      additionalProperties: false
    CollectionInvalidateEvent:
      type: object
      properties:
        type:
          const: invalidate
        data:
          type: object
          properties:
            urls:
              type: array
              items:
                $ref: '#/components/schemas/ResourceURL'
              maxItems: 200
            session_ids:
              type: array
              items:
                $ref: '#/components/schemas/ID'
              maxItems: 200
            scope_dirty:
              type: boolean
          required: [urls, session_ids, scope_dirty]
          additionalProperties: false
      required: [type, data]
      additionalProperties: false
    CollectionMailEvent:
      type: object
      properties:
        type:
          const: mail
        data:
          $ref: '#/components/schemas/MailMetadata'
      required: [type, data]
      additionalProperties: false
    CollectionReadyEvent:
      type: object
      properties:
        type:
          const: ready
        data:
          $ref: '#/components/schemas/EmptyRequest'
      required: [type, data]
      additionalProperties: false
    CollectionResetEvent:
      type: object
      properties:
        type:
          const: reset
        data:
          type: object
          properties:
            reason:
              const: initial
          required: [reason]
          additionalProperties: false
      required: [type, data]
      additionalProperties: false
    CollectionOverflowEvent:
      type: object
      properties:
        type:
          const: overflow
        data:
          $ref: '#/components/schemas/EmptyRequest'
      required: [type, data]
      additionalProperties: false
    CollectionReadyBatch:
      type: object
      properties:
        events:
          type: array
          prefixItems:
          - $ref: '#/components/schemas/CollectionReadyEvent'
          - $ref: '#/components/schemas/CollectionResetEvent'
          items: false
          minItems: 2
          maxItems: 2
      required: [events]
      additionalProperties: false
      examples:
      - events:
        - type: ready
          data: {}
        - type: reset
          data:
            reason: initial
    CollectionBatch:
      oneOf:
      - $ref: '#/components/schemas/CollectionReadyBatch'
      - type: object
        properties:
          events:
            type: array
            items:
              oneOf:
              - $ref: '#/components/schemas/ActivityEvent'
              - $ref: '#/components/schemas/CollectionInvalidateEvent'
              - $ref: '#/components/schemas/CollectionMailEvent'
            maxItems: 256
        required: [events]
        additionalProperties: false
      - type: object
        properties:
          events:
            type: array
            items:
              $ref: '#/components/schemas/CollectionOverflowEvent'
            minItems: 1
            maxItems: 1
        required: [events]
        additionalProperties: false
      x-max-encoded-bytes: 1048576
      examples:
      - events:
        - type: activity
          data:
            session_id: 01a0fcea-2b00-7000-8000-000000000001
            cursor:
              generation: J6kYj6IGcXyP3eMIp-WL3A
              sequence: 0
            status:
              phase: idle
              run_id: null
              interrupt_requested: false
              blocking_reason: null
            current_progress: []
            active_output: []
            activity:
              lines: []
              output_scalars: 0
              output_utf8_bytes: 0
              observed_at: '2026-10-02T14:00:00Z'
              latest_input: null
              latest_answer: null
    SessionSSE:
      type: object
      properties:
        data:
          type: string
          contentMediaType: application/json
          contentSchema:
            $ref: '#/components/schemas/SessionBatch'
      description: One parsed SSE event. Decode data as JSON and validate SessionBatch separately; contentSchema
        is not asserted by ordinary JSON Schema validation. No event, id or retry fields are emitted.
      required: [data]
      additionalProperties: false
      examples:
      - data: '{"generation":"J6kYj6IGcXyP3eMIp-WL3A","cursor":0,"events":[{"type":"reset","data":{"reason":"initial"}}],"snapshot":{"id":"01a0fcea-2b00-7000-8000-000000000001","name":"New
          session","automatic_name":"New session","workspace":"/workspace/project","location":{"host":null,"user":null,"path":"/workspace/project","label":null},"parent_id":null,"root_id":"01a0fcea-2b00-7000-8000-000000000001","address":null,"depth":0,"closed":false,"created_at":"2026-10-02T14:00:00Z","activity_at":"2026-10-02T14:00:00Z","provider_profile":"personal","model":"example-model","effort":null,"status":{"phase":"idle","run_id":null,"interrupt_requested":false,"blocking_reason":null},"preview":{"text":"","transcript_count":0,"truncated":false},"preferences":{"pinned":false,"pin_order":null,"archived":false,"opens":0},"current_progress":[],"activity":{"lines":[],"output_scalars":0,"output_utf8_bytes":0,"observed_at":"2026-10-02T14:00:00Z","latest_input":null,"latest_answer":null},"cursor":{"generation":"J6kYj6IGcXyP3eMIp-WL3A","sequence":0},"creation":{"submitted":{"kind":"new","workspace":"/workspace/project","name":null,"provider_profile":null,"model":null,"effort":null},"resolved":{"workspace":"/workspace/project","provider_profile":"personal","model":"example-model","effort":null}},"revision":"config-1","family_revision":"family-1","configuration_resource":{"url":"/sessions/01a0fcea-2b00-7000-8000-000000000001?view=configuration","etag":"\"session-config-1\"","value":{"id":"01a0fcea-2b00-7000-8000-000000000001","name":"New
          session","workspace":"/workspace/project","provider_profile":"personal","model":"example-model","effort":null,"preferences":{"pinned":false,"pin_order":null,"archived":false},"selection":{"extensions":{},"skills":{},"instructions":{},"mcp":{}},"revision":"config-1","family_revision":"family-1"}},"workspace_change":null,"selection":{"overrides":{"extensions":{},"skills":{},"instructions":{},"mcp":{}},"effective":{"extensions":{},"skills":{},"instructions":{},"mcp":{}}},"composition":{"desired_revision":"composition-1","loaded_revision":null,"needs_reload":true,"dependencies":{},"quarantine":[],"availability":{}},"kernel":{"instance_id":null,"state":"none","stage":null,"build":null,"stale":false,"staleness_reasons":[],"live_job_count":0,"running_jobs":[]},"pending_inputs":[],"input_order":0,"usage":{"model":null,"observed_at":null,"prompt_tokens":null,"cached_prompt_tokens":null,"cache_write_tokens":null,"completion_tokens":null,"total_tokens":null,"elapsed_ms":null,"tokens_per_second":null,"context_window_tokens":null,"cache_ttl_seconds":null,"cache_fade":[]},"history":{"items":[],"older":null,"newer":null,"high_water":0},"glances":[]}}'
      - data: '{"generation":"J6kYj6IGcXyP3eMIp-WL3A","cursor":1,"events":[{"type":"input","sequence":1,"data":{"input":{"id":"01a0fcea-2b00-7000-8000-000000000002","session_id":"01a0fcea-2b00-7000-8000-000000000001","kind":"message","admission":"accepted","http_status":202,"problem":null,"accepted_at":"2026-10-02T14:00:00Z","acceptance_order":1,"delivery":"pending","blocking_reason":null,"transcript_position":null,"turn":null,"client_id":"draft-1"}}}]}'
    CollectionSSE:
      type: object
      properties:
        data:
          type: string
          contentMediaType: application/json
          contentSchema:
            $ref: '#/components/schemas/CollectionBatch'
      description: One parsed SSE event. Decode data as JSON and validate CollectionBatch separately;
        contentSchema is not asserted by ordinary JSON Schema validation. No event, id or retry fields
        are emitted.
      required: [data]
      additionalProperties: false
      examples:
      - data: '{"events":[{"type":"ready","data":{}},{"type":"reset","data":{"reason":"initial"}}]}'
      - data: '{"events":[{"type":"activity","data":{"session_id":"01a0fcea-2b00-7000-8000-000000000001","cursor":{"generation":"J6kYj6IGcXyP3eMIp-WL3A","sequence":0},"status":{"phase":"idle","run_id":null,"interrupt_requested":false,"blocking_reason":null},"current_progress":[],"activity":{"lines":[],"output_scalars":0,"output_utf8_bytes":0,"observed_at":"2026-10-02T14:00:00Z","latest_input":null,"latest_answer":null}}}]}'
    WorkItem:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        workspace:
          $ref: '#/components/schemas/Workspace'
        title:
          type: string
          x-max-utf8-bytes: 4096
          maxLength: 4096
        notes:
          type: string
          x-max-utf8-bytes: 32768
          maxLength: 32768
        parent_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        status:
          type: string
          enum: [open, active, blocked, done, cancelled]
        revision:
          $ref: '#/components/schemas/ID'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
      required: [id, workspace, title, notes, parent_id, session_id, run_id, status, revision, created_at,
        updated_at]
      additionalProperties: false
    WorkCreate:
      type: object
      properties:
        title:
          type: string
          x-max-utf8-bytes: 4096
          maxLength: 4096
        notes:
          type: string
          x-max-utf8-bytes: 32768
          maxLength: 32768
        parent_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        notify_session_id:
          $ref: '#/components/schemas/ID'
      required: [title]
      additionalProperties: false
      examples:
      - title: Fix the parser
    WorkPatch:
      type: object
      properties:
        title:
          type: string
          x-max-utf8-bytes: 4096
          maxLength: 4096
        notes:
          type: string
          x-max-utf8-bytes: 32768
          maxLength: 32768
        session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        run_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        status:
          type: string
          enum: [open, active, blocked, done, cancelled]
        notify_session_id:
          $ref: '#/components/schemas/ID'
      additionalProperties: false
    Paperclip:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        topic:
          type: string
          enum: [harness, workflow, bug, user, other]
        title:
          type: string
          x-max-utf8-bytes: 4096
          maxLength: 4096
        message:
          type: string
          minLength: 1
          pattern: \S
          x-max-utf8-bytes: 32768
          maxLength: 32768
        suggestion:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
        reply:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
        status:
          type: string
          enum: [open, acknowledged, resolved, dismissed]
        session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        workspace:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        resolution:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
        resolving_session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        revision:
          $ref: '#/components/schemas/ID'
      required: [id, topic, title, message, suggestion, reply, status, session_id, workspace, created_at,
        updated_at, resolution, resolving_session_id, revision]
      additionalProperties: false
    PaperclipCreate:
      type: object
      properties:
        topic:
          type: string
          enum: [harness, workflow, bug, user, other]
        title:
          type: string
          x-max-utf8-bytes: 4096
          maxLength: 4096
        message:
          type: string
          minLength: 1
          pattern: \S
          x-max-utf8-bytes: 32768
          maxLength: 32768
        suggestion:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
        session_id:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        workspace:
          anyOf:
          - $ref: '#/components/schemas/Workspace'
          - type: 'null'
      required: [message]
      additionalProperties: false
    PaperclipPatch:
      type: object
      properties:
        status:
          type: string
          enum: [acknowledged, resolved, dismissed]
        reply:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
        resolution:
          type: string
          x-max-utf8-bytes: 16384
          maxLength: 16384
      description: Reply cannot accompany resolved or dismissed status. It acknowledges the item.
      additionalProperties: false
    ScheduleJob:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [once, recurring, heartbeat]
        prompt:
          type: string
          minLength: 1
          x-max-utf8-bytes: 4096
          maxLength: 4096
        next_at:
          $ref: '#/components/schemas/Timestamp'
        every_seconds:
          anyOf:
          - type: integer
            minimum: 60
            maximum: 31536000
          - type: 'null'
        revision:
          $ref: '#/components/schemas/ID'
        created_at:
          description: Null for historical schedules that did not record creation time.
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        updated_at:
          description: Null until a historical schedule records a new update.
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
      required: [id, session_id, kind, prompt, next_at, every_seconds, revision, created_at, updated_at]
      additionalProperties: false
    ScheduleCreate:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum: [once, recurring, heartbeat]
        prompt:
          type: string
          minLength: 1
          x-max-utf8-bytes: 4096
          maxLength: 4096
        delay_seconds:
          type: integer
          minimum: 0
          maximum: 31536000
          default: 0
        every_seconds:
          type: integer
          minimum: 60
          maximum: 31536000
      required: [session_id, kind, prompt]
      additionalProperties: false
      allOf:
      - if:
          properties:
            kind:
              const: once
        then:
          not:
            required: [every_seconds]
        else:
          required: [every_seconds]
    SchedulePatch:
      type: object
      properties:
        kind:
          type: string
          enum: [once, recurring, heartbeat]
        prompt:
          type: string
          minLength: 1
          x-max-utf8-bytes: 4096
          maxLength: 4096
        delay_seconds:
          type: integer
          minimum: 0
          maximum: 31536000
        every_seconds:
          anyOf:
          - type: integer
            minimum: 60
            maximum: 31536000
          - type: 'null'
      description: 'Validate complete candidate: once has null repetition; recurring and heartbeat require
        every_seconds.'
      additionalProperties: false
    LinkConfiguration:
      type: object
      properties:
        workspace:
          $ref: '#/components/schemas/Workspace'
        group_id:
          $ref: '#/components/schemas/ID'
        members:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
          maxItems: 200
        revision:
          $ref: '#/components/schemas/ID'
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [workspace, group_id, members, revision, next]
      additionalProperties: false
    LinkConfigurationResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/LinkConfiguration'
      required: [url, etag, value]
      additionalProperties: false
    LinkGroup:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageDescriptor'
        configuration_resource:
          $ref: '#/components/schemas/LinkConfigurationResource'
        presence:
          type: array
          items:
            type: object
            properties:
              workspace:
                $ref: '#/components/schemas/Workspace'
              exists:
                description: Observed directory presence. Null for an uninspected or unreachable location.
                anyOf:
                - type: boolean
                - type: 'null'
              session_count:
                $ref: '#/components/schemas/Counter'
              host:
                anyOf:
                - $ref: '#/components/schemas/Host'
                - type: 'null'
            required: [workspace, session_count, host, exists]
            additionalProperties: false
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [configuration_resource, presence, next]
      additionalProperties: false
    LinkMerge:
      type: object
      properties:
        other_workspace:
          $ref: '#/components/schemas/Workspace'
        other_etag:
          $ref: '#/components/schemas/ETag'
      required: [other_workspace, other_etag]
      additionalProperties: false
    LinkChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/LinkConfigurationResource'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/TargetNotification'
          maxItems: 200
        notification_count:
          $ref: '#/components/schemas/Counter'
        truncated:
          type: boolean
      required: [resource, notifications, notification_count, truncated]
      additionalProperties: false
    HookConfiguration:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        name:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
          maxLength: 64
        session_id:
          $ref: '#/components/schemas/ID'
        enabled:
          type: boolean
        signature_header:
          type: string
          pattern: ^[A-Za-z0-9-]{1,64}$
          maxLength: 64
        signature_prefix:
          type: string
          pattern: ^[^\r\n]*$
          x-max-utf8-bytes: 32
          maxLength: 32
        revision:
          $ref: '#/components/schemas/ID'
      required: [id, name, session_id, enabled, signature_header, signature_prefix, revision]
      additionalProperties: false
    HookConfigurationResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/HookConfiguration'
      required: [url, etag, value]
      additionalProperties: false
    Hook:
      type: object
      properties:
        configuration_resource:
          $ref: '#/components/schemas/HookConfigurationResource'
        delivery_url:
          type: string
          format: uri
          maxLength: 4096
        pending_count:
          $ref: '#/components/schemas/Counter'
        deferral_reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [configuration_resource, delivery_url, pending_count, deferral_reason]
      additionalProperties: false
    HookCreate:
      type: object
      properties:
        name:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
          maxLength: 64
        session_id:
          $ref: '#/components/schemas/ID'
        enabled:
          type: boolean
        signature_header:
          type: string
          pattern: ^[A-Za-z0-9-]{1,64}$
          maxLength: 64
        signature_prefix:
          type: string
          pattern: ^[^\r\n]*$
          x-max-utf8-bytes: 32
          maxLength: 32
        secret:
          type: string
          minLength: 1
          writeOnly: true
          x-min-utf8-bytes: 16
          x-max-utf8-bytes: 4096
          maxLength: 4096
      required: [name, session_id]
      additionalProperties: false
      examples:
      - session_id: 01a0fcea-2b00-7000-8000-000000000001
        name: ci
    HookPatch:
      type: object
      properties:
        name:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
          maxLength: 64
        enabled:
          type: boolean
        signature_header:
          type: string
          pattern: ^[A-Za-z0-9-]{1,64}$
          maxLength: 64
        signature_prefix:
          type: string
          pattern: ^[^\r\n]*$
          x-max-utf8-bytes: 32
          maxLength: 32
      additionalProperties: false
    HookSecretRequest:
      type: object
      properties:
        secret:
          type: string
          minLength: 1
          writeOnly: true
          x-min-utf8-bytes: 16
          x-max-utf8-bytes: 4096
          maxLength: 4096
      additionalProperties: false
    HookChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/HookConfigurationResource'
        notification:
          $ref: '#/components/schemas/Notification'
        secret:
          type: string
          minLength: 1
          x-min-utf8-bytes: 16
          x-max-utf8-bytes: 4096
          maxLength: 4096
      description: Secret appears only on creation and explicit rotation, including a generated secret.
        Never present on PATCH or reads.
      required: [resource, notification]
      additionalProperties: false
      examples:
      - resource:
          url: /extensions/webhooks/hooks/hook-1?view=configuration
          etag: '"hook-revision-1"'
          value:
            id: hook-1
            name: ci
            session_id: 01a0fcea-2b00-7000-8000-000000000001
            enabled: true
            signature_header: X-Albedo-Signature
            signature_prefix: sha256=
            revision: hook-revision-1
        notification:
          state: not_requested
          code: null
          detail: null
        secret: synthetic-example-hook-secret
    HookPermission:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        agent_manage:
          type: boolean
        revision:
          $ref: '#/components/schemas/ID'
      required: [session_id, agent_manage, revision]
      additionalProperties: false
    HookPermissionPatch:
      type: object
      properties:
        agent_manage:
          type: boolean
      additionalProperties: false
    HookPermissionResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/HookPermission'
      required: [url, etag, value]
      additionalProperties: false
    HookPermissionChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/HookPermissionResource'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [resource, notification]
      additionalProperties: false
    Delivery:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        hook_id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        received_at:
          $ref: '#/components/schemas/Timestamp'
        delivered_at:
          anyOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
        attempts:
          $ref: '#/components/schemas/Counter'
        deferral_reason:
          anyOf:
          - $ref: '#/components/schemas/SafeReason'
          - type: 'null'
      required: [id, hook_id, session_id, received_at, delivered_at, attempts, deferral_reason]
    DeliveryDetail:
      allOf:
      - $ref: '#/components/schemas/Delivery'
      - type: object
        properties:
          payload:
            type: object
            properties:
              encoding:
                type: string
                enum: [utf8, base64]
              data:
                type: string
                maxLength: 90000
            required: [encoding, data]
            additionalProperties: false
        required: [payload]
    WorkResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/WorkItem'
      required: [url, etag, value]
      additionalProperties: false
    WorkChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/WorkResource'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [resource, notification]
      additionalProperties: false
      examples:
      - resource:
          url: /extensions/work/items/work-1?workspace=%2Fworkspace%2Fproject
          etag: '"work-revision-1"'
          value:
            id: work-1
            workspace: /workspace/project
            title: Fix the parser
            notes: ''
            parent_id: null
            session_id: null
            run_id: null
            status: open
            revision: work-revision-1
            created_at: '2026-10-02T14:00:00Z'
            updated_at: '2026-10-02T14:00:00Z'
        notification:
          state: not_requested
          code: null
          detail: null
    WorkPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WorkResource'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        page:
          $ref: '#/components/schemas/PageDescriptor'
        glance:
          $ref: '#/components/schemas/Glance'
      required: [items, next]
      additionalProperties: false
    PaperclipResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/Paperclip'
      required: [url, etag, value]
      additionalProperties: false
    PaperclipChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/PaperclipResource'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [resource, notification]
      additionalProperties: false
    PaperclipPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PaperclipResource'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        page:
          $ref: '#/components/schemas/PageDescriptor'
        glance:
          $ref: '#/components/schemas/Glance'
      required: [items, next]
      additionalProperties: false
    WebSearchProvider:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          maxLength: 256
        position:
          type: integer
          minimum: 1
        enabled:
          type: boolean
      required: [name, label, position, enabled]
      additionalProperties: false
    WebSearchProviderResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/WebSearchProvider'
      required: [url, etag, value]
      additionalProperties: false
    WebSearchProviderPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchProviderResource'
          maxItems: 200
        next:
          type: 'null'
        page:
          $ref: '#/components/schemas/PageDescriptor'
      required: [items, next, page]
      additionalProperties: false
    WebSearchProviderChangeRequest:
      type: object
      properties:
        change:
          type: string
          enum: [up, down, toggle]
      required: [change]
      additionalProperties: false
    WebSearchProviderChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/WebSearchProviderResource'
      required: [resource]
      additionalProperties: false
    ScheduleResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/ScheduleJob'
      required: [url, etag, value]
      additionalProperties: false
    ScheduleChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ScheduleResource'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [resource, notification]
      additionalProperties: false
    SchedulePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleResource'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
        page:
          $ref: '#/components/schemas/PageDescriptor'
        glance:
          $ref: '#/components/schemas/Glance'
      required: [items, next]
      additionalProperties: false
    HookPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Hook'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    DeliveryPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Delivery'
          maxItems: 200
        next:
          anyOf:
          - $ref: '#/components/schemas/PageToken'
          - type: 'null'
      required: [items, next]
      additionalProperties: false
    ExtensionDeletion:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        notification:
          $ref: '#/components/schemas/Notification'
      required: [id, notification]
      additionalProperties: false
    ProxyTextPart:
      type: object
      properties:
        type:
          const: text
        text:
          type: string
      required: [type, text]
      additionalProperties: false
    ProxyImagePart:
      type: object
      properties:
        type:
          const: image_url
        image_url:
          type: object
          properties:
            url:
              type: string
              pattern: ^data:image/(png|jpeg|gif|webp);base64,
            detail:
              type: string
              enum: [auto, low, high]
          required: [url]
          additionalProperties: false
      required: [type, image_url]
      additionalProperties: false
    ProxyToolCall:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 270000
        type:
          const: function
        function:
          type: object
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 256
            arguments:
              type: string
          required: [name, arguments]
          additionalProperties: false
      required: [id, type, function]
      additionalProperties: false
    ProxyMessage:
      type: object
      properties:
        role:
          type: string
          enum: [system, developer, user, assistant, tool]
        content:
          anyOf:
          - oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                - $ref: '#/components/schemas/ProxyTextPart'
                - $ref: '#/components/schemas/ProxyImagePart'
          - type: 'null'
        name:
          type: string
          maxLength: 256
        tool_call_id:
          type: string
          minLength: 1
          maxLength: 270000
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ProxyToolCall'
          maxItems: 200
        reasoning_content:
          anyOf:
          - type: string
          - type: 'null'
      description: Tool messages require tool_call_id. Only assistant messages carry tool_calls. Images
        are accepted only as user data URLs.
      required: [role]
      additionalProperties: false
    ProxyToolDefinition:
      type: object
      properties:
        type:
          const: function
        function:
          type: object
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 256
            description:
              type: string
            parameters:
              $ref: '#/components/schemas/DynamicJSON'
            strict:
              type: boolean
          required: [name]
          additionalProperties: false
      required: [type, function]
      additionalProperties: false
    ProxyCompletionRequest:
      type: object
      properties:
        model:
          type: string
          minLength: 1
          maxLength: 577
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ProxyMessage'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ProxyToolDefinition'
          maxItems: 200
        max_tokens:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        max_completion_tokens:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
            maxItems: 4
        tool_choice:
          oneOf:
          - type: string
            enum: [none, auto, required]
          - type: object
            properties:
              type:
                const: function
              function:
                type: object
                properties:
                  name:
                    type: string
                    minLength: 1
                    maxLength: 256
                required: [name]
                additionalProperties: false
            required: [type, function]
            additionalProperties: false
        parallel_tool_calls:
          type: boolean
        reasoning_effort:
          type: string
          maxLength: 100
        reasoning:
          type: object
          properties:
            effort:
              type: string
              maxLength: 100
          required: [effort]
          additionalProperties: false
        response_format:
          oneOf:
          - type: object
            properties:
              type:
                const: json_object
            required: [type]
            additionalProperties: false
          - type: object
            properties:
              type:
                const: json_schema
              json_schema:
                type: object
                properties:
                  name:
                    type: string
                    maxLength: 256
                  description:
                    type: string
                  schema:
                    $ref: '#/components/schemas/DynamicJSON'
                  strict:
                    type: boolean
                required: [name, schema]
                additionalProperties: false
            required: [type, json_schema]
            additionalProperties: false
        stream:
          type: boolean
          default: false
        stream_options:
          type: object
          properties:
            include_usage:
              type: boolean
          additionalProperties: false
      x-max-encoded-bytes: 32000000
      required: [model, messages]
      additionalProperties: false
      examples:
      - model: personal/example-model
        messages:
        - role: user
          content: Hello
        stream: true
    ProxyUsage:
      type: object
      properties:
        prompt_tokens_details:
          type: object
          properties:
            cached_tokens:
              $ref: '#/components/schemas/Counter'
          required: [cached_tokens]
          additionalProperties: false
        completion_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              $ref: '#/components/schemas/Counter'
          required: [reasoning_tokens]
          additionalProperties: false
        prompt_tokens:
          $ref: '#/components/schemas/Counter'
        completion_tokens:
          $ref: '#/components/schemas/Counter'
        total_tokens:
          $ref: '#/components/schemas/Counter'
      required: [prompt_tokens, completion_tokens, total_tokens]
      additionalProperties: false
    ProxyError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              maxLength: 4096
            type:
              type: string
              maxLength: 100
            code:
              anyOf:
              - type: string
                maxLength: 100
              - type: 'null'
            param:
              anyOf:
              - type: string
                maxLength: 256
              - type: 'null'
          required: [message, type, code, param]
          additionalProperties: false
      required: [error]
      additionalProperties: false
    ProxyCompletion:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        object:
          const: chat.completion
        created:
          $ref: '#/components/schemas/Counter'
        model:
          type: string
          maxLength: 577
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                $ref: '#/components/schemas/Counter'
              message:
                type: object
                properties:
                  role:
                    const: assistant
                  content:
                    anyOf:
                    - type: string
                    - type: 'null'
                  reasoning_content:
                    anyOf:
                    - type: string
                    - type: 'null'
                  tool_calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProxyToolCall'
                    maxItems: 200
                required: [role, content]
                additionalProperties: false
              finish_reason:
                type: string
                enum: [stop, length, tool_calls, content_filter]
            required: [index, message, finish_reason]
            additionalProperties: false
          minItems: 1
          maxItems: 1
        usage:
          anyOf:
          - $ref: '#/components/schemas/ProxyUsage'
          - type: 'null'
      required: [id, object, created, model, choices, usage]
      additionalProperties: false
      examples:
      - id: completion-1
        object: chat.completion
        created: 1790949600
        model: personal/example-model
        choices:
        - index: 0
          message:
            role: assistant
            content: Hello
          finish_reason: stop
        usage:
          prompt_tokens: 1
          completion_tokens: 1
          total_tokens: 2
    ProxyToolDelta:
      type: object
      properties:
        index:
          $ref: '#/components/schemas/Counter'
        id:
          type: string
          minLength: 1
          maxLength: 270000
        type:
          const: function
        function:
          type: object
          properties:
            name:
              type: string
              maxLength: 256
            arguments:
              type: string
          required: [name, arguments]
          additionalProperties: false
      required: [index]
      additionalProperties: false
    ProxyChunk:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        object:
          const: chat.completion.chunk
        created:
          $ref: '#/components/schemas/Counter'
        model:
          type: string
          maxLength: 577
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                $ref: '#/components/schemas/Counter'
              delta:
                type: object
                properties:
                  role:
                    const: assistant
                  content:
                    type: string
                  reasoning_content:
                    type: string
                  tool_calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProxyToolDelta'
                    maxItems: 200
                additionalProperties: false
              finish_reason:
                anyOf:
                - type: string
                  enum: [stop, length, tool_calls, content_filter]
                - type: 'null'
            required: [index, delta, finish_reason]
            additionalProperties: false
          maxItems: 1
        usage:
          anyOf:
          - $ref: '#/components/schemas/ProxyUsage'
          - type: 'null'
      required: [id, object, created, model, choices]
      additionalProperties: false
    ProxySSE:
      type: object
      properties:
        data:
          anyOf:
          - const: '[DONE]'
          - type: string
            contentMediaType: application/json
            contentSchema:
              oneOf:
              - $ref: '#/components/schemas/ProxyChunk'
              - $ref: '#/components/schemas/ProxyError'
      description: Data is a JSON chunk or error, followed by literal [DONE]. Validate decoded JSON explicitly.
      required: [data]
      additionalProperties: false
    ProxyModels:
      type: object
      properties:
        object:
          const: list
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
                maxLength: 577
              object:
                const: model
              created:
                $ref: '#/components/schemas/Counter'
              owned_by:
                type: string
                maxLength: 256
            required: [id, object, created, owned_by]
            additionalProperties: false
        errors:
          type: array
          items:
            type: object
            properties:
              profile:
                $ref: '#/components/schemas/ID'
              message:
                type: string
                maxLength: 4096
            required: [profile, message]
            additionalProperties: false
          maxItems: 200
      required: [object, data]
      additionalProperties: false
    AdmissionProblem:
      type: object
      properties:
        type:
          const: about:blank
        title:
          type: string
          maxLength: 256
        status:
          type: integer
          minimum: 400
          maximum: 599
        detail:
          type: string
          maxLength: 4096
        code:
          type: string
          minLength: 1
          maxLength: 100
        fields:
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
                maxLength: 4096
              detail:
                type: string
                maxLength: 4096
            required: [pointer, detail]
            additionalProperties: false
          maxItems: 100
      required: [type, title, status, detail, code]
      additionalProperties: false
    ContextCompaction:
      type: object
      properties:
        status:
          type: string
          enum: [not_configured, not_needed, compacted, unknown]
        strategy:
          anyOf:
          - $ref: '#/components/schemas/ID'
          - type: 'null'
        trigger_free_percent:
          anyOf:
          - type: number
            minimum: 0
            maximum: 100
          - type: 'null'
        input_limit_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        estimated_input_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        provider_input_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        provider_cached_input_tokens:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        before_items:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        after_items:
          anyOf:
          - $ref: '#/components/schemas/Counter'
          - type: 'null'
        source:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
        estimate_method:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
      required: [status, strategy, trigger_free_percent, input_limit_tokens, estimated_input_tokens, provider_input_tokens,
        provider_cached_input_tokens, before_items, after_items, source, estimate_method]
      additionalProperties: false