# Daemon protocol 4. See http-api-design.md for behavioral semantics.
openapi: 3.2.1
info:
  title: Albedo daemon API
  version: 4.0.0
  summary: 'Protocol 4: 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 100,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: artifacts
  - name: web-search
  - name: skills
  - name: schedule
  - name: links
  - name: webhooks
  - name: discord
  - name: proxy
  - name: terminals
  - name: transfers
paths:
  /transfers/protocol:
    get:
      operationId: getTransferProtocol
      summary: The session transfer protocol this daemon speaks
      tags:
        - transfers
      description:
        A source's preflight reads it through the relay before it exports
        anything.
      responses:
        '200':
          description: This daemon's transfer protocol.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - protocol
                properties:
                  protocol:
                    type: integer
                    minimum: 1
        '401':
          $ref: '#/components/responses/Problem401'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
  /transfers/preflight:
    get:
      operationId: getTransferPreflight
      summary: Whether a session could move to another daemon now
      tags:
        - transfers
      description:
        Answers within about ten seconds. A target out of reach, a daemon there
        that speaks another transfer protocol or can't take what the export
        would send, a session mid-turn or one that already moved is available
        false with the reason, not an error. The target is asked through its
        read-only `POST /transfers/check`. A target from before that route is
        not checked, and its staging refuses what it lacks once the move starts.
      parameters:
        - name: session_id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: target
          in: query
          required: true
          schema:
            type: string
            description: '[user@]host:/absolute/path'
      responses:
        '200':
          description: What a move there would find.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferPreflight'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
  /transfers/{transfer_id}:
    get:
      operationId: getTransfer
      summary: Read a move this daemon drives
      tags:
        - transfers
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '200':
          description: The move.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Move'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
  /sessions/{session_id}/move:
    post:
      operationId: moveSessionToDaemon
      summary:
        Move a session and its same-workspace descendants to another host's
        daemon
      tags:
        - transfers
      description:
        The source daemon drives the move to the end whether or not the client
        stays, and a restart resumes it from its state. A repeat with the same
        transfer id and target answers the move as it stands. Once active the
        sessions here are marked moved and refuse new input (409 session_moved).
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - transfer_id
                - target
              properties:
                transfer_id:
                  type: string
                  pattern: ^[0-9a-fA-F-]{8,64}$
                target:
                  type: string
                  description: '[user@]host:/absolute/path'
                profiles:
                  type: object
                  description:
                    The target profile a session runs on there, by session id,
                    for sessions whose own profile the target lacks (preflight's
                    alternatives). Part of the move; a repeat with another
                    mapping is 409 transfer_conflict. Activation fails the move
                    with profile_unavailable when a session still can't run
                    there.
                  additionalProperties:
                    type: string
      responses:
        '202':
          description: The move, started or as it stands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Move'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '422':
          $ref: '#/components/responses/Problem422'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/finish:
    post:
      operationId: finishTransfer
      summary:
        Disarm the source's bindings and finish a move waiting at its checklist
      tags:
        - transfers
      description:
        Disarms every binding the move lists (schedules and heartbeats deleted,
        webhooks answering 410 with their new url, the discord bot stopped),
        reports what this daemon delivered after the export snapshot to the
        target so it skips those, then marks the sessions moved and the move
        active. A step that fails leaves the move at checklist with that
        binding's status failed and the move's error set; a repeat goes on from
        there, and a repeat once active answers the move.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '200':
          description:
            The move after this attempt, active or still at its checklist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Move'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/export:
    post:
      operationId: exportTransfer
      summary: Export a session and its same-workspace descendants for a move
      tags:
        - transfers
      description:
        One consistent snapshot per transfer id; a repeat answers the same
        manifest. Every session in scope must be idle.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - session_id
              properties:
                session_id:
                  type: string
      responses:
        '200':
          description: The manifest the target is given.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferManifest'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
    get:
      operationId: getTransferExport
      summary: Read an export's manifest
      tags:
        - transfers
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '200':
          description: The manifest the target is given.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferManifest'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
  /transfers/{transfer_id}/export/segments/{index}:
    get:
      operationId: getTransferSegment
      summary: Read one chunk of an exported segment
      tags:
        - transfers
      description: At most 512 KiB from offset; an empty body past the end.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
        - name: index
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Raw segment bytes.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
  /transfers/{transfer_id}/import:
    put:
      operationId: stageTransfer
      summary: Stage a source's manifest, inactive
      tags:
        - transfers
      description:
        Refuses an unknown owner or table version, a session that already lives
        here, or too little free space, before any byte arrives. A repeat with
        the same manifest and workspace answers the status; another workspace is
        a conflict.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
        - name: workspace
          in: query
          required: true
          description:
            The absolute path on this host the sessions activate into.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferManifest'
      responses:
        '200':
          description: The staged transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '409':
          $ref: '#/components/responses/Problem409'
        '415':
          $ref: '#/components/responses/Problem415'
        '422':
          $ref: '#/components/responses/Problem422'
        '507':
          $ref: '#/components/responses/Problem507'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
    get:
      operationId: getTransferImport
      summary: Read a staged transfer's progress
      tags:
        - transfers
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '200':
          description: The staged transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: safe-read
    delete:
      operationId: cancelTransferImport
      summary: Cancel an import that is not live yet
      tags:
        - transfers
      description:
        Removes the rows activation applied, last segment first, then the staged
        files; poll until cancelled. Refused once the import is installing or
        active.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '202':
          description: The import, cancelling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/import/segments/{index}:
    put:
      operationId: putTransferSegment
      summary: Write one chunk of a staged segment
      tags:
        - transfers
      description:
        Offsets resume where the segment's bytes end; a repeat of bytes already
        there is accepted, different bytes are not.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
        - name: index
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: The staged transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/import/ready:
    post:
      operationId: readyTransfer
      summary: Verify every staged segment; the import stays inactive
      tags:
        - transfers
      description:
        A segment that fails its digest or framing is dropped and named, to be
        sent again.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      responses:
        '200':
          description: The staged transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/import/occurrences:
    post:
      operationId: recordTransferOccurrences
      summary:
        Record what the source delivered after its export, so this daemon skips
        it
      tags:
        - transfers
      description:
        Called by the source when it finishes a move. Each occurrence is a
        schedule (its source id and due time, in seconds), a webhook event (hook
        id and event id) or a letter (its id); a repeat records nothing twice.
        The schedule due scan, webhook intake and discord delivery skip a
        recorded occurrence.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferOccurrences'
      responses:
        '200':
          description: How many occurrences were new here.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - recorded
                properties:
                  recorded:
                    type: integer
                    minimum: 0
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/runs-there:
    post:
      operationId: checkTransferProfiles
      summary: Whether sessions moving here can run on the profiles they name
      tags:
        - transfers
      description:
        Called by a source through the relay. For each session, ok when this
        daemon has the profile and it offers the model; otherwise problem says
        which is missing and alternatives lists the profiles here offering the
        model.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRunsThereRequest'
      responses:
        '200':
          description: One answer per session, in order.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - sessions
                properties:
                  sessions:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      required:
                        - session_id
                        - ok
                        - profile
                        - model
                        - problem
                        - alternatives
                      properties:
                        session_id:
                          $ref: '#/components/schemas/ID'
                        ok:
                          type: boolean
                        profile:
                          type: string
                        model:
                          type: string
                        problem:
                          type:
                            - string
                            - 'null'
                          enum:
                            - no_profile
                            - no_model
                            - null
                        alternatives:
                          type: array
                          items:
                            type: string
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/check:
    post:
      operationId: checkTransferShape
      summary: Whether this daemon would stage rows of these shapes
      tags:
        - transfers
      description:
        Called by a source's preflight through the relay. Runs the owner, table,
        version and column checks of staging and nothing else. It reads table
        columns only, and writes no receipt, staging directory or expiry, and
        checks no free space. A daemon from before this route answers 404 or
        405, and the source then leaves the decision to staging. The 422
        problem's code is `transfer_unsupported` for an owner or table this
        build lacks, `transfer_extension_unavailable` for an extension built in
        here that failed to load, `transfer_version` for a version or column
        this daemon lacks, or `transfer_protocol` for another transfer protocol.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferShape'
      responses:
        '200':
          description: This daemon would stage rows of these shapes.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - accepted
                properties:
                  accepted:
                    type: boolean
                    const: true
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '422':
          $ref: '#/components/responses/Problem422'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /mail/forwarded:
    post:
      operationId: admitForwardedMail
      summary: Admit letters from a daemon this one's sessions moved from
      tags:
        - transfers
      description:
        Called by that daemon through its relay. Each letter is admitted once by
        its id; a repeat is acknowledged again without a copy. A sender that
        does not live here is kept with the origin daemon and host, so a reply
        goes back there.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - origin
                - host
                - letters
              properties:
                origin:
                  type: string
                  description: The sending daemon's identity.
                host:
                  type: string
                  description: The sending daemon's host name.
                letters:
                  type: array
                  items:
                    $ref: '#/components/schemas/ForwardedLetter'
      responses:
        '200':
          description: One acknowledgement per letter.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - acks
                properties:
                  acks:
                    type: array
                    items:
                      $ref: '#/components/schemas/ForwardedAck'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /mail/forwarded/collect:
    post:
      operationId: collectForwardedMail
      summary: Collect the letters waiting here for the calling daemon
      tags:
        - transfers
      description:
        A long-poll the daemon sessions moved from keeps open through its relay.
        It settles the letters the caller acknowledges (admitted, or refused,
        which bounces them to their sender here), then answers the letters
        waiting for it, holding the call until one is queued or wait_ms (at most
        five minutes) ends.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - origin
                - host
                - acks
                - wait_ms
              properties:
                origin:
                  type: string
                  description: The collecting daemon's identity.
                host:
                  type: string
                acks:
                  type: array
                  items:
                    $ref: '#/components/schemas/ForwardedAck'
                wait_ms:
                  type: integer
                  minimum: 0
      responses:
        '200':
          description: The letters waiting for the caller, possibly none.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - letters
                properties:
                  letters:
                    type: array
                    items:
                      $ref: '#/components/schemas/ForwardedLetter'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/import/family:
    post:
      operationId: recordTransferFamily
      summary: Record the relatives the moved sessions left on the source
      tags:
        - transfers
      description:
        Called by the source as the import goes live. Each stub names a moved
        session, a relative of it on the source (its parent, a child, or a
        sibling) and the name it addresses it by, so "parent" and those names
        keep resolving here to the same session ids. A repeat updates them.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - origin
                - host
                - stubs
              properties:
                origin:
                  type: string
                host:
                  type: string
                stubs:
                  type: array
                  items:
                    type: object
                    additionalProperties: false
                    required:
                      - session_id
                      - member
                      - relation
                      - name
                    properties:
                      session_id:
                        $ref: '#/components/schemas/ID'
                      member:
                        $ref: '#/components/schemas/ID'
                      relation:
                        type: string
                        enum:
                          - parent
                          - child
                          - sibling
                      name:
                        type: string
      responses:
        '200':
          description: How many stubs were recorded.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - recorded
                properties:
                  recorded:
                    type: integer
                    minimum: 0
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /extensions/agents/sessions/{session_id}/{op}:
    post:
      operationId: runMovedAgentCall
      summary: Run a handle call on a session that moved here
      tags:
        - transfers
      description:
        Called by the daemon the session moved from, through its relay, after it
        authorized the caller as it would have before the move. The body is the
        handle call's own arguments; the answer is what the call answers.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: op
          in: path
          required: true
          schema:
            type: string
            enum:
              - messages
              - search_messages
              - cancel
              - close
              - switch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The call's answer.
          content:
            application/json:
              schema: {}
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '422':
          $ref: '#/components/responses/Problem422'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /transfers/{transfer_id}/import/activate:
    post:
      operationId: activateTransfer
      summary: Make a ready import live, in bounded batches
      tags:
        - transfers
      description:
        Answers at once and goes on in the background; poll the import until its
        state is active. The sessions stay invisible and inert (stage importing)
        until one commit makes them live. A repeat answers the status and never
        applies a row twice. A row whose key this daemon already holds sends the
        import back to ready with error transfer_collision, nothing applied. A
        body names what each session runs on here; a ready import with a session
        that can't is refused with 422 profile_unavailable before anything
        applies, and the profiles it names are switched in the commit that makes
        the sessions live.
      parameters:
        - name: transfer_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F-]{8,64}$
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRunsThereRequest'
      responses:
        '202':
          description: The import, activating.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferStatus'
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '422':
          $ref: '#/components/responses/Problem422'
      x-albedo-audience: internal-transfer
      x-albedo-recovery: no-automatic-replay
  /terminals/{terminal_id}:
    get:
      operationId: attachTerminal
      summary: Upgrade to interactive pseudo-terminal session
      tags:
        - terminals
      description: 'WebSocket upgrade endpoint for an interactive terminal.
        Authenticated by the same bearer token and origin policy as other daemon
        routes.

        Binary frames carry raw terminal PTY bytes. Text frames are JSON objects
        for control commands:

        {type:"ping"}, {type:"input",data:...},
        {type:"resize",cols:...,rows:...},
        {type:"signal",signal:"SIGINT"|"SIGTERM"|...},
        {type:"restart",cols:...,rows:...}.

        Server sends {type:"ready",id,cwd,shell,cols,rows,state,exit_code} on
        attach, binary frames for terminal output (including initial scrollback
        history),

        {type:"exit",exit_code} when the shell process exits, and {type:"pong"}
        keepalives.'
      parameters:
        - name: terminal_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: cwd
          in: query
          required: false
          description: Initial working directory for the terminal session.
          schema:
            type: string
        - name: session_id
          in: query
          required: false
          description:
            Existing session ID to derive initial working directory from.
          schema:
            $ref: '#/components/schemas/ID'
        - name: cols
          in: query
          required: false
          description: Terminal column width (2-500, default 80).
          schema:
            type: integer
            minimum: 2
            maximum: 500
        - name: rows
          in: query
          required: false
          description: Terminal row height (1-200, default 24).
          schema:
            type: integer
            minimum: 1
            maximum: 200
        - name: restart
          in: query
          required: false
          description: Whether to restart an existing terminal process group.
          schema:
            type: boolean
        - name: shell
          in: query
          required: false
          description:
            Command or shell executable to run (defaults to user shell).
          schema:
            type: string
      responses:
        '101':
          description: WebSocket connection established.
        '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'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
    delete:
      operationId: closeTerminal
      summary: Explicitly close an interactive pseudo-terminal session
      tags:
        - terminals
      description:
        Terminates the pseudo-terminal process group and releases its resources.
      parameters:
        - name: terminal_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: Terminal session closed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalClose'
        '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'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /events:
    get:
      operationId: getEvents
      summary: Upgrade to multiplexed live session events
      tags:
        - sessions
      description: 'WebSocket upgrade endpoint, authenticated by the same bearer
        token and origin

        policy as other daemon routes. A socket owns at most 64 keyed follows.

        Client text frames are JSON objects:
        {key,type:"session",session_id,tail:0,

        after_generation?,after_seq?}, {key,type:"sessions",scope:"roots"},

        {key,type:"stop"}, or {type:"ping"}. Keys contain 1 to 128 UTF-8 bytes.

        Session replay and tail validation match GET /sessions/{session_id} SSE.

        Subscribing an existing key replaces that follow. after_seq accepts an

        integer or its decimal string; tail defaults to 100 and is at most 200.

        Server text frames are {key,batch:<unchanged SSE batch>}: session
        batches

        carry generation,cursor,events and optional snapshot; collection batches

        carry events. A successful send acknowledges its session cursor. A
        follow

        ending (including stop, deletion, failure or overflow) sends
        {key,end:true}.

        Invalid commands and admission refusals send
        {key,failure:{code,detail}};

        malformed commands without a usable key use an empty key. Session
        failures

        and collection overflow retain their SSE batch before the end frame.

        Ping replies and 15-second keepalives are {type:"pong"}. Commands are at

        most 4096 UTF-8 bytes; response frames are at most 1 MiB. Unsubscribe
        and

        socket closure release watches. Clients reconnect a follow with its last

        fully consumed cursor. Existing SSE routes remain available.

        '
      responses:
        '101':
          description: WebSocket connection established.
        '400':
          description: Invalid WebSocket handshake; empty response body.
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '405':
          $ref: '#/components/responses/Problem405'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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: 4
                    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
              - extensions
        - $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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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/Settings'
        '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: Return aggregate settings with canonical group resources.
      parameters: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /usage:
    get:
      operationId: getUsage
      summary: Read what the provider calls used
      tags:
        - usage
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSummary'
              examples:
                UsageSummary:
                  value:
                    generated_at: '2026-10-25T18:00:00Z'
                    utc_offset_minutes: -360
                    days:
                      - start: '2026-10-24T06:00:00Z'
                        calls: 0
                        errors: 0
                        input_tokens: 0
                        cached_input_tokens: 0
                        cache_creation_tokens: 0
                        output_tokens: 0
                        reasoning_tokens: 0
                      - start: '2026-10-25T06:00:00Z'
                        calls: 12
                        errors: 1
                        input_tokens: 48000
                        cached_input_tokens: 36000
                        cache_creation_tokens: 0
                        output_tokens: 2100
                        reasoning_tokens: 600
                    lines:
                      - profile: work
                        provider: responses:https://api.example.com/v1
                        account: null
                        model: example-model
                        calls: 12
                        errors: 1
                        input_tokens: 48000
                        cached_input_tokens: 36000
                        cache_creation_tokens: 0
                        output_tokens: 2100
                        reasoning_tokens: 600
                    scopes:
                      - provider: responses:https://api.example.com/v1
                        account: null
                    lines_truncated: false
                    scopes_truncated: false
        '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:
        'Totals come from hourly counts kept beside the request records, so they
        cost the same however long the history is and keep the use of sessions
        since deleted. Hours are UTC; in a zone that is not a whole number of
        hours from UTC the hour that straddles midnight counts in the earlier
        day. Counts are as the providers reported them, and providers differ on
        whether `input_tokens` includes `cached_input_tokens`. `provider` and
        `account` narrow the days and lines to one scope, while `scopes` always
        lists every scope the window saw. Requires capability `usage_summary:
        1`.'
      parameters:
        - name: days
          in: query
          required: false
          description: How many days to cover, the current one included.
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 7
        - name: utc_offset_minutes
          in: query
          required: false
          description:
            How far ahead of UTC the client's clock runs, which decides where
            its days begin.
          schema:
            type: integer
            minimum: -720
            maximum: 840
            default: 0
        - name: provider
          in: query
          required: false
          description:
            Count only this provider's rows, named as `lines` and `scopes` name
            it (`protocol:endpoint`). It narrows `days` and `lines`; `scopes`
            still lists every provider and account of the window. A value is
            matched exactly, percent-encoded in the query like any other (a `+`
            is a space and a literal plus is `%2B`).
          schema:
            type: string
            minLength: 1
        - name: account
          in: query
          required: false
          description:
            Count only this account's rows of `provider`, matched exactly. An
            empty value is a provider without an account pool. Without
            `provider` it is refused, because two providers can label accounts
            the same way.
          schema:
            type: string
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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
                        shell_output_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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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: acp
          in: query
          required: false
          description:
            true lists only ACP-owned sessions, false only the others. Combine
            with workspace for an exact canonical workspace match.
          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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/title-generation:
    parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    post:
      operationId: generateSessionTitle
      summary: Generate a session name from the conversation
      tags:
        - sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
      responses:
        '200':
          description:
            Name generation started. The existing name stays until completion.
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/fast-mode:
    parameters:
      - name: session_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ID'
    get:
      operationId: getFastMode
      summary: Read fast-mode state and provider capability
      tags:
        - sessions
      responses:
        '200':
          description: Current setting and capability observation.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FastMode'
        '401':
          $ref: '#/components/responses/Problem401'
        '404':
          $ref: '#/components/responses/Problem404'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
    patch:
      operationId: patchFastMode
      summary: Change session fast mode
      tags:
        - sessions
      description: 'Conditional, user-facing configuration change. Requires the
        session

        configuration ETag. Enabling is rejected unless the provider reports

        fast mode supported; unknown capability is not inferred. Disabling is

        always allowed. `toggle` inverts the state protected by If-Match;
        replaying

        a successful toggle with the old ETag is refused rather than toggling
        twice.

        This setting can affect provider billing.

        '
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              type: object
              additionalProperties: false
              required:
                - state
              properties:
                state:
                  type: string
                  enum:
                    - true
                    - false
                    - toggle
      responses:
        '200':
          description: Fast-mode state and current provider capability.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FastMode'
        '400':
          $ref: '#/components/responses/Problem400'
        '404':
          $ref: '#/components/responses/Problem404'
        '409':
          $ref: '#/components/responses/Problem409'
        '412':
          $ref: '#/components/responses/Problem412'
        '428':
          $ref: '#/components/responses/Problem428'
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
  /sessions/{session_id}:
    get:
      operationId: getSession
      summary: Read a session snapshot
      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/Session'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: tail
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 200
            default: 100
      x-albedo-audience: client
      x-albedo-recovery: safe-read
    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: []
                    shell_commands: []
                    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/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
                    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'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
      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.
      x-albedo-audience: client
      x-albedo-recovery: repeat-identical-intent
    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 the session's
        observed family revision and 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'
        - $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'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/side-questions/{question_id}:
    put:
      operationId: putSideQuestion
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: question_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SideQuestionRequest'
      responses:
        '200':
          description: Current side question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideQuestionEnvelope'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    patch:
      operationId: patchSideQuestion
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: question_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SideQuestionPatchRequest'
      responses:
        '200':
          description: Current side question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideQuestionEnvelope'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
  /sessions/{session_id}/side-questions/{question_id}/cancel:
    post:
      operationId: cancelSideQuestion
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: question_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
      responses:
        '200':
          description: Current side question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SideQuestionEnvelope'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '410':
          $ref: '#/components/responses/Problem410'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/shell-commands/{command_id}:
    put:
      operationId: putShellCommand
      summary: Admit one immutable human shell command
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: command_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      description:
        Durable admission precedes process spawn. Same identity and command
        returns the original resource before mutable checks; changed intent
        conflicts. One running command and at most 32 uncommitted outcomes per
        session. No automatic model turn. Remote workspaces are refused.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShellCommandRequest'
      responses:
        '200':
          description: Current durable shell command resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShellCommandResponse'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    get:
      operationId: getShellCommand
      summary: Read a human shell command
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: command_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      responses:
        '200':
          description: Current durable shell command resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShellCommandResponse'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/shell-commands/{command_id}/stop:
    post:
      operationId: stopShellCommand
      summary: Request termination of one human shell command
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: command_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      description:
        Stops this command process group only. Response can remain running until
        cleanup is confirmed; read the same resource for its terminal outcome.
      responses:
        '200':
          description: Current durable shell command resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShellCommandResponse'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/shell-commands/{command_id}/output:
    get:
      operationId: getShellCommandOutput
      summary: Read retained sanitized shell output
      tags:
        - sessions
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: command_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 16777216
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 4
            maximum: 65536
            default: 4000
      description:
        UTF-8 byte offsets, complete-codepoint pages, next_offset null at the
        current captured cutoff. Retained output is at most 16 MiB; no terminal
        controls are stored.
      responses:
        '200':
          description: Current durable shell command resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShellCommandOutput'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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: the session's inbox is full
                    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: the session's inbox is full
                          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'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
      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.
      x-albedo-audience: client
      x-albedo-recovery: repeat-identical-intent
      x-albedo-problem-codes:
        - invalid_request
        - identity_invalid
        - id_conflict
        - input_conflict
        - identity_expired
        - session_busy
        - session_not_found
        - request_unavailable
    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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
        - input_unknown
        - input_conflict
        - request_unavailable
  /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'
        '409':
          $ref: '#/components/responses/Problem409'
        '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. ACP
        sessions require the current attachment token.
      parameters:
        - $ref: '#/components/parameters/AttachmentTokenOptional'
        - 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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/inputs/{input_id}/hold:
    post:
      operationId: holdInput
      summary: Hold a waiting message while it is edited
      tags:
        - sessions
      responses:
        '200':
          description: Held until the lease runs out, unless asked again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputHold'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        Holds a person's typed message that still waits in the session's queue,
        or renews the hold. Neither it nor anything queued after it is read
        until the edit is saved, the hold is released, or lease_ms pass without
        another hold. 409 input_not_waiting once the session read the message or
        it was cancelled; 409 input_not_editable for any other 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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    delete:
      operationId: releaseInput
      summary: Let a held message be read as it is
      tags:
        - sessions
      responses:
        '204':
          description: Released; the message keeps its place in the queue.
        '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'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      description: Idempotent. A message that was never held is unaffected.
      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'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/inputs/{input_id}/edit:
    post:
      operationId: editInput
      summary: Put an edited message in place of a waiting one
      tags:
        - sessions
      responses:
        '200':
          description: The message as it now waits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputEdit'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        Replaces a person's typed message that still waits, keeping its id and
        its place in the queue, and releases any hold on it. 409
        input_not_waiting once the session read it or it was cancelled.
      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/MessageInputRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/acp-attachment:
    put:
      operationId: attachACPSession
      summary: Attach this ACP connection as the session's single writer
      tags:
        - sessions
      responses:
        '200':
          description:
            Attached. The cursor and active turn are one session-actor capture;
            follow the stream from the cursor to receive only later events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ACPAttachment'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        Attach or re-attach with the same token. 409 not_acp_session for a
        session created without kind acp; 409 workspace_mismatch unless
        workspace equals the session's canonical workspace exactly; 409
        attachment_held while another token holds a live lease (never stolen);
        409 session_busy when the session has an active turn and the overlay
        differs from the installed one (nothing changes); 409
        mcp_overlay_conflict for duplicate names or names already configured
        globally; 409 mcp_overlay_failed when an idle replacement could not be
        prepared (the previous overlay and attachment stay as they were). 503
        overlay_installed_reload_failed means publication succeeded but runtime
        reload failed; the replacement remains installed. 503
        overlay_update_uncertain means publication or reload was not confirmed
        within 15 seconds and may still complete. An identical reattach retries
        a failed reload. With editor-mcp enabled, publication awaiting reload
        blocks turns with 409 overlay_installed_reload_failed. A missing
        required overlay after restart blocks turns with 409
        overlay_reattach_required; the editor must resume and resupply its
        servers. An empty overlay permits daemon-driven turns after daemon
        restart, but old editor tokens are invalid. Failed setup releases a
        newly acquired lease and retains a preexisting same-token lease. An
        empty list removes only the editor overlay.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/AttachmentToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ACPAttachRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    delete:
      operationId: releaseACPSession
      summary: Release this connection's attachment
      tags:
        - sessions
      responses:
        '204':
          description:
            Released, or this token held no attachment. Accepted work keeps
            running.
        '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'
        '409':
          $ref: '#/components/responses/Problem409'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        Idempotent. Never cancels accepted inputs, the active turn, or the MCP
        overlay.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/AttachmentToken'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /sessions/{session_id}/acp-attachment/renew:
    post:
      operationId: renewACPSession
      summary: Extend this connection's attachment lease
      tags:
        - sessions
      responses:
        '204':
          description: Lease extended.
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          $ref: '#/components/responses/Problem409'
        '413':
          $ref: '#/components/responses/Problem413'
        '415':
          $ref: '#/components/responses/Problem415'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        409 attachment_lost when this token no longer holds the attachment
        (expired, released, or the daemon restarted). Renewal never re-attaches;
        the client must attach again.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/AttachmentToken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/history/content:
    get:
      operationId: getHistoryContentBatch
      summary: Read several entries' full content in one walk
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntryContentBatch'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '503':
          $ref: '#/components/responses/Problem503'
      description:
        The same parts and byte offsets as the single-entry route, for up to 200
        entries, in the order `entries` names them. Follow next until null,
        repeating entries. One page stays inside the common encoded response
        bound, so a page whose entries are mostly references costs one request
        per byte budget instead of one request per entry.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: entries
          in: query
          required: true
          description:
            Comma separated history entry ids, in display order, at most 200 of
            them, each at most 128 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 26000
        - $ref: '#/components/parameters/Next'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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. When `edge` is given and
        either dimension exceeds it, the response is scaled down so its longer
        edge equals `edge` and encoded as lossy WebP; smaller images are
        returned untouched.
      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
        - name: edge
          in: query
          required: false
          description:
            Optional longer-edge pixel bound for thumbnail previews. Images
            already within this bound are returned unchanged.
          schema:
            type: integer
            enum: [256, 512, 1024]
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/context:
    get:
      operationId: getContext
      summary: Read ContextSummary
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextSummary'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/context-window:
    get:
      operationId: getContextWindow
      summary: Read the window this session compacts against
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextWindow'
        '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:
        "The session's own window outranks the model's. Reads do not prepare a
        request, so the answer is available while the prepared context is
        pending. Requires capability `context: 1`."
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/files:
    get:
      operationId: getSessionFile
      summary: Read a text file in the session's workspace
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionFile'
        '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'
        '413':
          description:
            The file is over 1 MiB, or its JSON answer would exceed the response
            limit (`file_too_large`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '415':
          description: The file is binary or not valid UTF-8 (`file_not_text`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description:
            The gather on the workspace's host failed or answered badly
            (`workspace_unavailable`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      description:
        'Reads on the machine the workspace is on: the daemon for a local
        workspace, the host through one SSH gather for a remote one. A missing
        file, a directory or another non-regular file answers 404
        `file_not_found`; an unknown session answers 404 like other session
        routes. A remote host that is not ready answers 503
        `workspace_unavailable`, a failed gather 502. Requires capability
        `file_reading: 1`.'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: path
          in: query
          required: true
          description:
            Absolute on the workspace's machine, relative to the workspace,
            `~/...` in a local workspace, or the host-prefixed spelling `path`
            answers with.
          schema:
            type: string
            minLength: 1
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/changes:
    get:
      operationId: getSessionChanges
      summary: Read every change of the session's checkout
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutChanges'
              examples:
                CheckoutChanges:
                  value:
                    checkout:
                      kind: git
                      root: /workspace/project
                      head: 6e1f2a9
                      branch: main
                    base:
                      spec: uncommitted
                      label: HEAD
                      commit: 6e1f2a9
                    files:
                      - path: docs/guide.md
                        old_path: null
                        status: untracked
                        added: 2
                        removed: 0
                        binary: false
                        diff: 'diff --git a/docs/guide.md b/docs/guide.md

                          new file mode 100644

                          --- /dev/null

                          +++ b/docs/guide.md

                          @@ -0,0 +1,2 @@

                          +# guide

                          +read me'
                        omitted: null
                      - path: logo.png
                        old_path: null
                        status: modified
                        added: 0
                        removed: 0
                        binary: true
                        diff: null
                        omitted: binary
                      - path: src/main.go
                        old_path: src/app.go
                        status: renamed
                        added: 1
                        removed: 1
                        binary: false
                        diff: "diff --git a/src/app.go b/src/main.go\nsimilarity
                          index\
                          \ 90%\nrename from src/app.go\nrename to
                          src/main.go\nindex\
                          \ 3b18e51..a0423896 100644\n--- a/src/app.go\n+++
                          b/src/main.go\n\
                          @@ -1,3 +1,3 @@\n package main\n-// app\n+// main\n
                          func main()\
                          \ {}"
                        omitted: null
                    truncated: false
        '304':
          description:
            The answer named by `If-None-Match` is still current. No body.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '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'
        '406':
          $ref: '#/components/responses/Problem406'
        '409':
          description:
            The workspace is in no git or jj checkout (`not_a_repository`), or
            `base=upstream` has nothing to compare with (`no_upstream`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description:
            git or jj failed or is not installed (`vcs_failed`), or the gather
            on the workspace's host failed (`workspace_unavailable`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          $ref: '#/components/responses/Problem503'
        '504':
          description: The commands missed their 15 s deadline (`vcs_timeout`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      description:
        "Diffs the working copy of the checkout enclosing the session's
        workspace, on the machine the workspace is on (the daemon, or the host
        through SSH gathers). Read-only: git runs without optional locks and jj
        with `--ignore-working-copy`. `uncommitted` compares the working tree,
        staged and unstaged, with HEAD (git) or `@-` (jj); `upstream` compares
        it with the merge base of HEAD and the branch's upstream, else
        origin/HEAD, else origin/main (git), or with `fork_point(trunk() | @)`
        (jj). Untracked files that are not ignored are listed whole. A jj
        checkout colocated with git is answered by git and so includes edits jj
        has not snapshotted, listing a file new to git as `added`; one without
        git is as fresh as jj's last snapshot. Files sort by path, at most 1000
        (`truncated` past that). A diff over 256 KiB is omitted `too_large`;
        once the JSON-encoded diffs reach 768 KiB, that file and every later one
        are omitted `budget`. Binary content, and text that is not UTF-8, is
        `binary`. `diff` is null exactly when `omitted` is set; counts are
        always filled (0 for binary, and for an untracked file over 64 MiB). The
        ETag hashes the answer: `If-None-Match` with it answers 304. A missing
        workspace folder is 404 `workspace_unavailable`. Requires capability
        `checkout_changes: 1`."
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: base
          in: query
          required: false
          schema:
            type: string
            enum:
              - uncommitted
              - upstream
            default: uncommitted
        - name: If-None-Match
          in: header
          required: false
          description: The ETag of an earlier answer.
          schema:
            type: string
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
      x-albedo-problem-codes:
        - invalid_request
        - session_not_found
        - request_unavailable
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
      x-albedo-problem-codes:
        - invalid_request
        - session_not_found
        - request_unavailable
  /sessions/{session_id}/kernel/restart:
    post:
      operationId: restartKernel
      summary: Replace the session's kernel with an empty one
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KernelRestartResult'
        '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:
        Stop the running turn and cancel queued inputs as an interrupt does,
        discard the saved variables, and stop the kernel and its jobs. The
        response waits for the stop; the next turn boots an empty kernel. A stop
        that fails answers 503 kernel_restart_failed.
      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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
      x-albedo-problem-codes:
        - invalid_request
        - session_not_found
        - request_unavailable
  /sessions/{session_id}/rewind:
    post:
      operationId: rewindSession
      summary:
        Cut a session back to before a user message and keep the removed tail as
        an archived session
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewindResult'
        '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. The checkpoint must be a user message from the
        checkpoint view. The session keeps every row before it, and the full
        prior conversation is copied first into a new archived session. The
        session actor stops, so attached streams reconnect and reset. Python
        namespace and files on disk are not rewound. A requested summary is made
        before anything changes, so a failed summary leaves the session
        untouched. Requires capability `history_rewind: 1`.'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RewindRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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'
        '404':
          $ref: '#/components/responses/Problem404'
        '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: session
          in: query
          required: false
          description:
            Existing session whose selected account scopes Daybreak Blue
            support; with initial=true, a preallocated new session ID selects
            its exact future account. Without initial, an unknown or deleted
            session returns 404 session_not_found.
          schema:
            $ref: '#/components/schemas/ID'
        - name: initial
          in: query
          required: false
          description:
            true permits preview with a new future session ID; requires
            provider_profile and session. Existing session IDs are rejected.
          schema:
            type: string
            enum:
              - 'true'
        - 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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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 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
          description:
            "`preview` adds repository facts and a tree; `files` lists the
            directory's files after its directories, each item with `kind`,
            `size` and `ignored`."
          schema:
            type: string
            enum:
              - preview
              - files
              - preview,files
              - files,preview
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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`.'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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`.'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
    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`.'
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
    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'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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:
        'Signs the account out. Reject only an account that comes from the
        environment (`account_external`). A profile pinned to it by `account_id`
        goes back to automatic selection, and it leaves every `account_ids` list
        naming it; a list it empties becomes null. 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'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
    patch:
      operationId: patchAccount
      summary: Rename a saved provider account
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountPatch'
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '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:
        'Environment accounts cannot be renamed (`account_external`). Requires
        capability `provider_auth: 1`.'
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
  /auth/keys/{account_id}:
    put:
      operationId: putKeyAccount
      summary: Save an API key as a provider account
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyAccountRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '200':
          description: The same request again; the account it created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '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:
        'The client chooses the account id (a UUIDv7). Replaying the same
        request returns the account; different content at a used id is `409
        conflict`. Requires capability `provider_auth: 1`.'
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUIDv7'
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
    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'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/artifacts/items:
    get:
      operationId: listArtifacts
      summary: List artifacts, newest change first
      tags:
        - artifacts
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactPage'
        '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 artifacts. Artifacts outlive their session;
        `session_deleted` marks one whose session is gone.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
        - name: session
          in: query
          required: false
          description: Only this session's artifacts.
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/artifacts/items/{artifact_id}:
    get:
      operationId: getArtifact
      summary: Read one artifact with its versions
      tags:
        - artifacts
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactDetail'
        '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: artifact_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ArtifactID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    delete:
      operationId: deleteArtifact
      summary: Delete an artifact and every version of it
      tags:
        - artifacts
      responses:
        '204':
          description: Deleted.
        '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: artifact_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ArtifactID'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/artifacts/frame/{frame}/{version}/{path}:
    get:
      operationId: getArtifactFile
      summary: Serve one file of one artifact version
      tags:
        - artifacts
      responses:
        '200':
          description:
            The file, with its content type. An HTML file has the page bridge
            injected at the start of its head.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '302':
          description:
            The bare version path goes to its folder (`latest` to `latest/`),
            and an empty path to an entry inside a folder goes to that entry, so
            the page's relative paths resolve inside the version.
          headers:
            Location:
              description: Relative to the request.
              schema:
                type: string
        '304':
          description:
            The file named by `If-None-Match` is still the one served.
        '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:
        '`albedo web` forwards `/frame/...` here; see robot-docs/artifacts.md. A
        wrong key answers 404. `path` may contain `/`; one ending in `/` serves
        its index.html, and an empty one the entry of that version. Under
        `latest` files are `no-cache` and the bridge is told to follow; the
        files of a numbered version are immutable.'
      parameters:
        - name: frame
          in: path
          required: true
          description: The artifact's id and capability key, joined by a dot.
          schema:
            type: string
            maxLength: 128
        - name: version
          in: path
          required: true
          description: A version number, or `latest` for the newest.
          schema:
            type: string
            pattern: ^([1-9][0-9]*|latest)$
        - name: path
          in: path
          required: true
          schema:
            type: string
            maxLength: 512
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/artifacts/frame/{frame}/{version}/.albedo/state:
    post:
      operationId: saveArtifactState
      summary: Save the page's localStorage
      tags:
        - artifacts
      responses:
        '204':
          description: Saved.
        '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'
        '413':
          $ref: '#/components/responses/Problem413'
      parameters:
        - name: frame
          in: path
          required: true
          description: The artifact's id and capability key, joined by a dot.
          schema:
            type: string
            maxLength: 128
        - name: version
          in: path
          required: true
          description: A version number, or `latest` for the newest.
          schema:
            type: string
            pattern: ^([1-9][0-9]*|latest)$
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/ArtifactState'
        description:
          JSON sent as text/plain, so a sandboxed page can send it without a
          preflight.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/artifacts/frame/{frame}/{version}/.albedo/errors:
    post:
      operationId: reportArtifactError
      summary: Record a failure in the page
      tags:
        - artifacts
      responses:
        '204':
          description: Recorded.
        '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'
        '413':
          $ref: '#/components/responses/Problem413'
      parameters:
        - name: frame
          in: path
          required: true
          description: The artifact's id and capability key, joined by a dot.
          schema:
            type: string
            maxLength: 128
        - name: version
          in: path
          required: true
          description: A version number, or `latest` for the newest.
          schema:
            type: string
            pattern: ^([1-9][0-9]*|latest)$
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/ArtifactError'
        description:
          JSON sent as text/plain, so a sandboxed page can send it without a
          preflight.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/artifacts/frame/{frame}/{version}/.albedo/version:
    get:
      operationId: getArtifactLatestVersion
      summary: Wait for a newer version of an artifact
      tags:
        - artifacts
      description:
        What a page open on `latest/` in a tab of its own asks to know when to
        reload. With `after`, the daemon holds the answer until the latest
        version passes it or about 25 seconds pass; without, it answers at once.
        The version in the path only has to exist.
      responses:
        '200':
          description: The artifact's latest version.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - version
                properties:
                  version:
                    type: integer
                    minimum: 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'
        '404':
          $ref: '#/components/responses/Problem404'
      parameters:
        - name: frame
          in: path
          required: true
          description: The artifact's id and capability key, joined by a dot.
          schema:
            type: string
            maxLength: 128
        - name: version
          in: path
          required: true
          description: A version number, or `latest` for the newest.
          schema:
            type: string
            pattern: ^([1-9][0-9]*|latest)$
        - name: after
          in: query
          required: false
          description:
            The version the page shows; the answer waits for one past it.
          schema:
            type: integer
            minimum: 0
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
    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'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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.
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/skills/loads:
    get:
      operationId: listSkillLoads
      summary: List the skills a session loaded
      tags:
        - skills
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillLoadList'
        '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'
      description:
        Requires enabled extension skills. Each skill the session's model or
        user loaded, once, first loaded first; the session's sidebar glance
        lists the same.
      parameters:
        - name: session_id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
    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'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
    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'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
    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'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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'
        '410':
          $ref: '#/components/responses/Problem410'
        '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. A hook whose session moved to another daemon
        answers 410 naming the url to send to there. 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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    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.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
  /extensions/discord/bots:
    get:
      operationId: listDiscordBots
      summary: List Discord bots of every session without tokens
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordBotPage'
        '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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    post:
      operationId: createDiscordBot
      summary: Create the Discord bot of a session
      tags:
        - discord
      responses:
        '201':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordBot'
        '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:
        One bot per session (409 bot_exists). The token must have three
        dot-separated parts and is never returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscordBotCreate'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/discord/bots/{bot_id}:
    get:
      operationId: getDiscordBot
      summary: Read a Discord bot and its live state
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordBot'
        '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: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    patch:
      operationId: patchDiscordBot
      summary: Edit a Discord bot at an observed revision
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordBot'
        '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'
      description:
        A token or enabled change restarts or stops the bot process. A stale
        revision is 412 precondition_failed.
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/DiscordBotPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: extension
      x-albedo-recovery: refresh-before-edit
    delete:
      operationId: deleteDiscordBot
      summary: Delete a Discord bot and its channel and DM settings
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordDeletion'
        '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'
        '412':
          $ref: '#/components/responses/Problem412'
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: revision
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/discord/bots/{bot_id}/guilds:
    get:
      operationId: listDiscordGuilds
      summary:
        List the servers and channels the bot can see, with their delivery
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordGuildList'
        '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:
        Read live from the bot process; 503 bot_offline when the bot is not
        online.
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/discord/bots/{bot_id}/channels/{channel_id}:
    put:
      operationId: putDiscordChannel
      summary: Set how a channel reaches the session
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordChannelState'
        '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:
        Delivery off removes the channel; threads follow their parent channel.
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: channel_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscordChannelSetting'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/discord/bots/{bot_id}/dms:
    get:
      operationId: getDiscordDMs
      summary: Read the DM allow list and pending requests
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordDMs'
        '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: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/discord/bots/{bot_id}/dms/{user_id}:
    put:
      operationId: putDiscordDM
      summary: Allow a person to DM the session
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordAllowed'
        '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:
        A null name is resolved from Discord when the bot is online. Allowing
        removes a pending request.
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: user_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscordAllow'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
    delete:
      operationId: deleteDiscordDM
      summary: Remove a person from the DM allow list
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordUserDeletion'
        '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: The owner cannot be removed (400).
      parameters:
        - name: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: user_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/discord/bots/{bot_id}/requests/{user_id}:
    delete:
      operationId: deleteDiscordRequest
      summary: Dismiss a pending DM request
      tags:
        - discord
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordUserDeletion'
        '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: bot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: user_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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.
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/proxy/v1/models/{id}:
    get:
      operationId: getProxyModel
      summary: Read one saved-profile OpenAI model and its efforts
      tags:
        - proxy
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyModel'
        '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'
        '404':
          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'
      parameters:
        - name: id
          in: path
          required: true
          description:
            A `<profile>/<model>` id; its slash may be sent unescaped.
          schema:
            type: string
            minLength: 1
            maxLength: 577
      description:
        External OpenAI envelope. Bearer required unless operator explicitly
        configured anonymous loopback access.
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/run/sessions/{session_id}/jobs/recent:
    get:
      operationId: listRecentJobs
      summary: Read the kernel's jobs, running and finished
      description:
        What the session's kernel still knows of the jobs its run tool started,
        newest first, with up to 100 rows. Finished jobs stay for as long as the
        kernel keeps their output (its 64 newest). A session with no kernel has
        none.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The kernel's job book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRecordCollection'
        '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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /extensions/run/sessions/{session_id}/jobs/{job_id}/output:
    get:
      operationId: readJobOutput
      summary: Read a page of one job's output
      description:
        Pages are byte ranges cut on character boundaries, so a reader that
        continues from `next_offset` loses none of what the job wrote; a running
        job's last character waits for the page after it. Without `offset` the
        page is the end of the output. Reading never counts as the model reading
        the job's result.
      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'
        - name: offset
          in: query
          required: false
          description:
            Byte to start from. Omitted, the page ends at the end of the output.
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          required: false
          description: Most bytes in the page; four hold any character.
          schema:
            type: integer
            minimum: 4
            maximum: 65536
            default: 16384
      responses:
        '200':
          description: One page of output and the job it belongs to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobOutputPage'
        '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'
        '409':
          description:
            The page lies in output the kernel no longer keeps; read the end of
            the output instead.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          $ref: '#/components/responses/Problem503'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
  /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
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/mail/sessions/{session_id}/queue:
    get:
      operationId: readQueue
      summary: Read what waits in the session's inbox and the queue page
      description:
        Every input the session has not read yet, in the order it will read
        them, the first 200 shown. Reading never loads the session's kernel.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The queue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCollection'
        '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'
      x-albedo-audience: extension
      x-albedo-recovery: safe-read
    delete:
      operationId: clearQueue
      summary: Drop everything waiting in the session's inbox
      description:
        A person's waiting input is cancelled, as cancelling the input would.
        What the running turn already took stays with it.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The queue after the drop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCollection'
        '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
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/mail/sessions/{session_id}/queue/order:
    put:
      operationId: arrangeQueue
      summary: Put waiting inputs first, in the order given
      description:
        The listed inputs move to the front in this order; the rest keep their
        order after them. Ids that no longer wait are skipped.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The queue in its new order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCollection'
        '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: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueOrder'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/mail/sessions/{session_id}/queue/{item_id}:
    delete:
      operationId: dropQueued
      summary: Take one input out of the session's queue
      description:
        A person's input is cancelled, as cancelling the input would. Fails with
        404 `queue_item_not_found` when nothing with that id waits, including an
        input the running turn already took.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: item_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The queue after the drop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCollection'
        '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
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /extensions/mail/sessions/{session_id}/queue/{item_id}/first:
    post:
      operationId: moveQueuedFirst
      summary: Move one waiting input to the front of the queue
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: item_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      responses:
        '200':
          description: The queue in its new order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueCollection'
        '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
      x-albedo-audience: extension
      x-albedo-recovery: no-automatic-replay
  /settings/providers:
    get:
      operationId: getProviderSettings
      summary: Read providers settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderSettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchProviderSettings
      summary: Edit providers settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderSettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ProviderSettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/mcp:
    get:
      operationId: getMCPSettings
      summary: Read mcp settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPSettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchMCPSettings
      summary: Edit mcp settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPSettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/MCPSettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/extensions:
    get:
      operationId: getExtensionSettings
      summary: Read extensions settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionSettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchExtensionSettings
      summary: Edit extensions settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionSettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ExtensionSettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/extension_settings:
    get:
      operationId: getDeclaredSettings
      summary: Read extension_settings settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredSettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchDeclaredSettings
      summary: Edit extension_settings settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclaredSettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/DeclaredSettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/capabilities:
    get:
      operationId: getCapabilitySettings
      summary: Read capabilities settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilitySettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchCapabilitySettings
      summary: Edit capabilities settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilitySettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/CapabilitySettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/models:
    get:
      operationId: getModelSettings
      summary: Read models settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelSettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchModelSettings
      summary: Edit models settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelSettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ModelSettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /settings/ui:
    get:
      operationId: getUISettings
      summary: Read ui settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UISettings'
        '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: []
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
    patch:
      operationId: patchUISettings
      summary: Edit ui settings
      tags:
        - settings
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UISettingsChange'
        '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'
      parameters:
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UISettingsPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
  /sessions/{session_id}/configuration:
    get:
      operationId: getSessionConfiguration
      summary: Read session configuration
      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/SessionConfiguration'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
        - session_not_found
        - request_unavailable
    patch:
      operationId: patchSession
      summary: Edit session configuration
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionConfigurationChange'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/SessionPatch'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: refresh-before-edit
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
        - configuration_changed
        - catalog_changed
        - session_busy
        - session_not_found
        - request_unavailable
  /sessions/{session_id}/status:
    get:
      operationId: getSessionStatus
      summary: Read session status
      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/SessionStatusRead'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/events:
    get:
      operationId: watchSession
      summary: Read session events
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Vary:
              $ref: '#/components/headers/Vary'
          content:
            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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - 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'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/workspace:
    post:
      operationId: moveSessionWorkspace
      summary: Move a session 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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/IfMatch'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceMoveRequest'
        description: UTF-8 JSON; duplicate keys and unknown fields are rejected.
      x-albedo-audience: client
      x-albedo-recovery: no-automatic-replay
      x-albedo-problem-codes:
        - invalid_request
        - precondition_required
        - precondition_failed
        - configuration_changed
        - family_changed
        - workspace_invalid
        - workspace_unavailable
        - session_busy
        - session_not_found
        - request_unavailable
  /sessions/{session_id}/requests:
    get:
      operationId: getSessionRequests
      summary: Read RequestRecordPage
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRecordPage'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: after
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Counter'
        - name: since_ms
          in: query
          required: false
          description:
            Requests only. Include attempts finished at or after this Unix
            timestamp in milliseconds.
          schema:
            $ref: '#/components/schemas/Counter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/context/{snapshot_id}/sections/{section_id}:
    get:
      operationId: getContextSection
      summary: Read ContextSectionPage
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextSectionPage'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: page
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Counter'
        - name: snapshot_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - name: section_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
  /sessions/{session_id}/compactions/{action_id}:
    put:
      operationId: putCompaction
      summary: Admit identified compaction
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionReceipt'
        '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'
        '202':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionReceipt'
        '410':
          $ref: '#/components/responses/Problem410'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
        - name: action_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.
      x-albedo-audience: client
      x-albedo-recovery: repeat-identical-intent
      x-albedo-problem-codes:
        - invalid_request
        - acp_owned
        - attachment_lost
        - identity_invalid
        - id_conflict
        - identity_expired
        - session_busy
        - session_not_found
        - request_unavailable
    get:
      operationId: getCompaction
      summary: Read a compaction receipt
      tags:
        - sessions
      responses:
        '200':
          description: Successful result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactionReceipt'
        '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'
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
        - $ref: '#/components/parameters/AttachmentTokenOptional'
        - name: action_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ID'
      x-albedo-audience: client
      x-albedo-recovery: safe-read
      x-albedo-problem-codes:
        - invalid_request
        - acp_owned
        - attachment_lost
        - identity_expired
        - identity_invalid
        - compaction_unknown
        - request_unavailable
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:
    AttachmentToken:
      name: Albedo-Attachment-Token
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/AttachmentToken'
      description:
        Per-connection ACP attachment capability, generated by the client.
        Separate from the daemon bearer token; the daemon keeps only a digest in
        memory and never returns or logs it.
    AttachmentTokenOptional:
      name: Albedo-Attachment-Token
      in: header
      required: false
      schema:
        $ref: '#/components/schemas/AttachmentToken'
      description:
        Required for kind acp creation and for input or scoped cancellation in
        an ACP session. Also authorizes compaction and scoped execution
        configuration patches by an ACP attachment holder. Ordinary creation
        ignores this header. Input, scoped cancellation, compaction for ACP
        sessions, and configuration patches parse and reject malformed supplied
        values. Not part of the durable intent.
    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'
    Problem422:
      description: Unknown transfer owner, table or version
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem507:
      description: Not enough free space or staging room
      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:
    TransferPreflight:
      type: object
      additionalProperties: false
      required: [available, reason, target_daemon, bytes, sessions, runs_there]
      properties:
        available: { type: boolean }
        reason:
          type: [string, 'null']
          description: Why the move is unavailable, in words for a person.
        code:
          type: [string, 'null']
          description:
            The stable code of the refusal that makes the move unavailable, null
            when it is available or the target was out of reach. It is the code
            a move would fail with, such as `transfer_target_older` (a missing
            extension, table, version or column),
            `transfer_extension_unavailable` (an extension that failed to load
            there), `transfer_protocol`, `session_busy`, `session_moved` or
            `profile_unavailable`. Daemons before this field omit it.
        target_daemon:
          $ref: '#/components/schemas/TransferTargetDaemon'
        bytes:
          type: [integer, 'null']
          description: The move's size, when known before export.
        sessions:
          type: array
          description:
            The session and its same-workspace descendants, which move together.
          items:
            $ref: '#/components/schemas/ID'
        runs_there:
          type: array
          description:
            Whether each session can run on the target, in the order of
            sessions; empty when the target was not reached. A session that
            can't and has no alternative makes available false with its reason;
            one with alternatives leaves the pick to the client (the move's
            profiles).
          items:
            $ref: '#/components/schemas/TransferRunsThere'
    ForwardedLetter:
      type: object
      additionalProperties: false
      required: [id, recipient, sender, sender_name, kind, body]
      properties:
        id: { type: string }
        recipient:
          $ref: '#/components/schemas/ID'
        sender:
          $ref: '#/components/schemas/ID'
        sender_name: { type: string }
        kind:
          type: string
          enum: [task, request, message, result, unreviewed]
        body: { type: string }
    ForwardedAck:
      type: object
      additionalProperties: false
      required: [id, error, retry]
      properties:
        id: { type: string }
        error:
          type: [string, 'null']
          description: Why the letter was not admitted; null when it was.
        retry:
          {
            type: boolean,
            description:
              Send it again later (a full inbox) rather than bouncing it.,
          }
    TransferRunsThere:
      type: object
      additionalProperties: false
      required: [session_id, name, ok, profile, model, reason, alternatives]
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        name:
          {
            type: string,
            description: "The session's family name, else its name or title.",
          }
        ok:
          {
            type: boolean,
            description: The target has this profile and it offers this model.,
          }
        profile: { type: string }
        model: { type: string }
        reason:
          type: [string, 'null']
          description: Why it can't run there, in words for a person.
        alternatives:
          type: array
          description:
            The target's other profiles offering the model, when this one does
            not.
          items: { type: string }
    TransferShape:
      type: object
      additionalProperties: false
      required: [protocol, segments]
      description:
        What a source's export would list, without the data. Each table is a
        rows segment. An owner that carries files and no tables, but has files
        to send, is one file segment, whose owner is checked as staging checks a
        file's owner.
      properties:
        protocol: { type: integer }
        segments:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [kind, owner, name, version, columns]
            properties:
              kind: { type: string, enum: [rows, file] }
              owner: { type: string }
              name: { type: string }
              version: { type: integer }
              columns:
                type: array
                items: { type: string }
    TransferRunsThereRequest:
      type: object
      additionalProperties: false
      required: [sessions]
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/TransferSessionProfile'
        profiles:
          type: object
          description:
            Sessions to switch to another profile as they go live, session id to
            profile.
          additionalProperties: { type: string }
    TransferSessionProfile:
      type: object
      additionalProperties: false
      required: [session_id, profile, model]
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        profile: { type: string }
        model: { type: string }
    TransferTargetDaemon:
      type: object
      additionalProperties: false
      required: [host, protocol, home]
      properties:
        host: { type: string }
        protocol: { type: [integer, 'null'] }
        home: { type: [string, 'null'] }
    Move:
      type: object
      additionalProperties: false
      required:
        [
          id,
          session_id,
          target,
          state,
          reason,
          progress,
          error,
          target_session_id,
          target_home,
          lost,
          bindings,
        ]
      properties:
        id: { type: string }
        session_id:
          $ref: '#/components/schemas/ID'
        target: { type: string, description: '[user@]host:/absolute/path' }
        state:
          type: string
          enum:
            [
              checking,
              exporting,
              copying,
              activating,
              checklist,
              active,
              failed,
            ]
          description:
            At checklist the target is live and the sessions here still are too,
            until finish disarms the bindings and marks them moved.
        reason:
          type: [string, 'null']
          description:
            Why the move waits, such as a turn still running or the target out
            of reach.
        progress:
          $ref: '#/components/schemas/MoveProgress'
        error:
          anyOf:
            - $ref: '#/components/schemas/MoveError'
            - type: 'null'
        target_session_id: { type: [string, 'null'] }
        target_home: { type: [string, 'null'] }
        lost:
          type: array
          description:
            What the target could not restore, such as the python namespace.
          items: { type: string }
        bindings:
          type: array
          description: What finish disarms here, listed from checklist on.
          items:
            $ref: '#/components/schemas/MoveBinding'
    MoveBinding:
      type: object
      additionalProperties: false
      required: [kind, id, label, detail, old_url, new_url, status, error]
      properties:
        kind:
          type: string
          enum: [schedule, heartbeat, webhook, discord]
        id: { type: string }
        label: { type: string }
        detail:
          type: string
          description:
            A schedule's prompt and cadence, a webhook's name, the bot's name
            and channels.
        old_url:
          type: [string, 'null']
          description: The webhook url senders post to here.
        new_url:
          type: [string, 'null']
          description:
            The webhook url on the target to point senders at; null when the
            target has none.
        status:
          type: string
          enum: [pending, disarmed, failed]
        error:
          type: [string, 'null']
          description: Why disarming this binding failed.
    TransferOccurrences:
      type: object
      additionalProperties: false
      required: [occurrences]
      properties:
        occurrences:
          type: array
          maxItems: 10000
          items:
            $ref: '#/components/schemas/TransferOccurrence'
    TransferOccurrence:
      type: object
      additionalProperties: false
      required: [kind, origin, key]
      properties:
        kind:
          type: string
          enum: [schedule, webhook, letter]
        origin:
          type: string
          description:
            The schedule's id on the source, the hook id, or empty for a letter.
        key:
          type: string
          description:
            The due time in unix seconds, the event id, or the letter id.
        detail:
          type: [string, 'null']
          description: The delivery id the source gave a webhook event.
    MoveProgress:
      type: object
      additionalProperties: false
      required: [bytes_done, bytes_total]
      properties:
        bytes_done: { type: integer, minimum: 0 }
        bytes_total: { type: integer, minimum: 0 }
    MoveError:
      type: object
      additionalProperties: false
      required: [code, detail]
      properties:
        code:
          type: string
          description:
            Why the move failed. `transfer_target_older` is a target too old to
            take a table version or column this daemon sends; moves go only from
            an older daemon to a newer one. `transfer_unsupported` is a target
            without an extension or table this daemon sends, because it is older
            or the extension failed to load there.
            `transfer_extension_unavailable` is a target whose extension failed
            to load. The detail is the target's own refusal, naming the first
            thing it lacks.
        detail: { type: string }
    SessionMovePending:
      type: object
      additionalProperties: false
      required: [transfer_id, host]
      properties:
        transfer_id: { type: string }
        host: { type: string }
    SessionMoved:
      type: object
      additionalProperties: false
      required: [host, workspace, transfer_id, at]
      properties:
        host: { type: string }
        workspace: { type: string, description: '[user@]host:/absolute/path' }
        transfer_id: { type: string }
        at:
          $ref: '#/components/schemas/Timestamp'
    TransferManifest:
      type: object
      required:
        [protocol, id, origin, root, workspace, sessions, watermark, segments]
      properties:
        protocol: { type: integer }
        id: { type: string }
        origin: { type: string, description: The source home's identity. }
        root: { type: string }
        workspace: { type: string }
        sessions:
          type: array
          items: { type: string }
        watermark:
          {
            type: integer,
            description: The highest transcript position exported.,
          }
        segments:
          type: array
          items:
            type: object
            required: [kind, owner, name, version, columns, rows, bytes, digest]
            properties:
              kind: { type: string, enum: [rows, file] }
              owner: { type: string }
              name: { type: string }
              version: { type: integer }
              columns:
                type: array
                items: { type: string }
              rows: { type: integer }
              bytes: { type: integer }
              digest: { type: string, description: 'SHA-256, lowercase hex.' }
    TransferStatus:
      type: object
      required: [state, bytes, received, rows, session_id, home, lost, error]
      properties:
        state:
          type: string
          enum:
            [
              staging,
              ready,
              importing,
              installing,
              active,
              cancelling,
              cancelled,
            ]
          description: importing and installing are still inert; active is live.
        bytes: { type: integer }
        received:
          type: array
          items: { type: integer }
        rows:
          type: object
          required: [done, total]
          properties:
            done: { type: integer }
            total: { type: integer }
        session_id:
          {
            type: string,
            description: 'The root session, the same id as on the source.',
          }
        home: { type: string, description: This daemon's home. }
        lost:
          type: array
          items: { type: string }
          description: What could not be restored, such as "python namespace".
        error:
          type: [object, 'null']
          description: Why activation last stopped; a retry resumes it.
          required: [code, detail]
          properties:
            code: { type: string }
            detail: { type: string }
    TerminalClose:
      type: object
      required:
        - closed
      properties:
        closed:
          $ref: '#/components/schemas/ID'
      description:
        The interactive terminal session was closed and its process group ended.
      additionalProperties: false
    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: the session's inbox is full
          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: the session's inbox is full
                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
    GlobalExtension:
      type: object
      description:
        Installed extension and its resolved global default, independent of
        session overrides.
      properties:
        id:
          $ref: '#/components/schemas/ID'
        description:
          type: string
        requires:
          type: array
          items:
            $ref: '#/components/schemas/ID'
        enabled:
          type: boolean
        quarantined:
          type: boolean
        diagnostic:
          type: [string, 'null']
      required: [id, description, requires, enabled, quarantined, diagnostic]
      additionalProperties: false
    Server:
      type: object
      properties:
        instance_id:
          $ref: '#/components/schemas/ID'
        pid:
          type: integer
          minimum: 1
          maximum: 2147483647
          description:
            OS process id of the daemon VM. Clients check it against daemon.json
            when present. Absent from daemons that predate this field.
        protocol:
          const: 4
        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.
        api_digest:
          type: string
          pattern: ^[0-9a-f]{64}$
          description:
            Digest of the HTTP contract this daemon serves (docs/openapi.yaml
            without prose or examples), as cli/tools/apigen computes it. A
            client generated from a different digest may reject responses, so it
            refuses to attach and names the side to rebuild or restart. Absent
            from daemons that predate it.
        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
        extension_inventory:
          type: array
          description:
            Returned only with include=extensions. Includes disabled and
            quarantined extensions; never prepares a session.
          items:
            $ref: '#/components/schemas/GlobalExtension'
        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: 4
          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
        stop_kernels:
          type: boolean
          default: false
          description:
            End every Python kernel this daemon holds instead of leaving them
            running for the next daemon to attach to. Sessions save their
            variables first, as when they go idle; running jobs end.
      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'
        api:
          anyOf:
            - type: string
              enum: [messages, converse]
            - type: 'null'
          description:
            Bedrock API mode. Null or omission means messages; replay protocol
            is unchanged.
        endpoint:
          anyOf:
            - type: string
              format: uri
              maxLength: 4096
            - type: 'null'
        protocol:
          type: string
          enum: [responses, chat_completions]
        model:
          $ref: '#/components/schemas/ID'
        effort:
          description:
            Profile reasoning override. A supported level overrides the model
            default for inheriting sessions. Null, inherit, or default leaves
            the model default in control.
          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'
        account_ids:
          description:
            Accounts this profile uses, in order, by id. Null when it does not
            rotate. Exclusive with `account_id`; with neither, a profile uses
            one account (its saved key, the environment key, or the provider's
            selected or first account) and never switches. `rotation` says how
            the list is used.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ID'
              minItems: 1
              maxItems: 50
            - type: 'null'
        rotation:
          type: string
          enum: [failover, spread, first]
          default: failover
          description:
            How `account_ids` is used. `failover` uses the first ready account
            and moves down the list after a limit. `spread` starts each new
            session (every agent is a session) on the next ready account in turn
            and keeps it there for the session's life, so its prompt cache stays
            warm; it moves only when that account is limited or needs sign-in,
            and stays on the account it moved to. `first` uses only the first
            and waits out its limit. Ignored without `account_ids`.
        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,
          account_ids,
          rotation,
          project,
          location,
          has_key,
        ]
      additionalProperties: false
    ProviderProfilePatch:
      type: object
      properties:
        extension:
          $ref: '#/components/schemas/ID'
        api:
          type: string
          enum: [messages, converse]
          description:
            Bedrock API mode. Omission preserves an existing value; new and
            legacy profiles without a value use messages; converse selects
            streaming Converse.
        endpoint:
          anyOf:
            - type: string
              format: uri
              maxLength: 4096
            - type: 'null'
        protocol:
          type: string
          enum: [responses, chat_completions]
        model:
          $ref: '#/components/schemas/ID'
        effort:
          description:
            Profile reasoning override. A supported level overrides the model
            default for inheriting sessions. Null, inherit, or default leaves
            the model default in control.
          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'
        account_ids:
          description:
            Accounts this profile uses, in order, by id. Null when it does not
            rotate. Exclusive with `account_id`; with neither, a profile uses
            one account (its saved key, the environment key, or the provider's
            selected or first account) and never switches. `rotation` says how
            the list is used.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ID'
              minItems: 1
              maxItems: 50
            - type: 'null'
        rotation:
          type: string
          enum: [failover, spread, first]
          description:
            How `account_ids` is used. `failover` uses the first ready account
            and moves down the list after a limit. `spread` starts each new
            session (every agent is a session) on the next ready account in turn
            and keeps it there for the session's life, so its prompt cache stays
            warm; it moves only when that account is limited or needs sign-in,
            and stays on the account it moved to. `first` uses only the first
            and waits out its limit. Ignored without `account_ids`.
        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'
        renames:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ID'
          description:
            Existing profile names mapped to new ones, applied before profiles,
            which then use the new names. The saved key, default_profile and
            every session on the old name follow. An unknown old name is 409
            unknown_profile; a new name another profile already has is 409
            profile_exists.
      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
    MCPAuth:
      type: object
      description:
        A server's OAuth sign-in. none until the server asks for one;
        needs_sign_in when it asked and albedo has no usable token, signed_in,
        or signed_out after the user signed out. Start a sign-in with PUT
        /auth/logins/{login_id} and provider mcp:<server>. Tokens and client
        secrets never appear.
      properties:
        state:
          type: string
          enum: [none, needs_sign_in, signed_in, signed_out]
        account:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        scope:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
        step_up:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          description:
            The wider scope a signed-in server asked for; signing in again
            grants it.
        reason:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
        client:
          anyOf:
            - type: string
              enum: [configured, registered]
            - type: 'null'
          description:
            configured when the user set a client id, registered when albedo
            registered itself.
      required: [state, account, expires_at, scope, step_up, reason, client]
      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'
        auth:
          $ref: '#/components/schemas/MCPAuth'
      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,
          auth,
        ]
      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'
        oauth:
          type: 'null'
          description: Null signs the server out of its OAuth sign-in.
        oauth_client:
          anyOf:
            - type: object
              properties:
                client_id:
                  type: string
                  minLength: 1
                  maxLength: 1024
                client_secret:
                  anyOf:
                    - type: string
                      writeOnly: true
                      maxLength: 4096
                    - type: 'null'
              required: [client_id]
              additionalProperties: false
            - type: 'null'
          description:
            A client the user registered with the server's authorization server,
            used instead of registering albedo; null forgets it.
      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
        compact_at:
          type: object
          additionalProperties:
            type: integer
            minimum: 1
            maximum: 100000000
        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'
        compact_at:
          type: object
          additionalProperties:
            anyOf:
              - type: integer
                minimum: 1
                maximum: 100000000
              - type: 'null'
      description:
        Keys are cap_key values from model metadata. For raised_caps, true
        raises to the advertised maximum; false uses the ordinary limit; null
        clears the choice. A missing choice defaults to false. For compact_at, a
        token count is the window every session on that model compacts against,
        as long as it is below the model's window; null clears it. Only
        raised_caps and compact_at are writable.
      additionalProperties: false
    UISettings:
      type: object
      properties:
        thinking:
          type: boolean
        tools:
          type: boolean
        dismissed_notices:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 1000
        web_allow:
          description:
            Networks `albedo web` serves to besides this machine, as CIDR or an
            address whose trailing zero octets stand for any (10.0.0.0 is
            10.0.0.0/8).
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          maxItems: 64
        proxy_allow:
          description:
            Networks `albedo proxy` serves to besides this machine, as CIDR or
            an address whose trailing zero octets stand for any (10.0.0.0 is
            10.0.0.0/8).
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          maxItems: 64
      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
        web_allow:
          description:
            Networks `albedo web` serves to besides this machine, as CIDR or an
            address whose trailing zero octets stand for any (10.0.0.0 is
            10.0.0.0/8).
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          maxItems: 64
        proxy_allow:
          description:
            Networks `albedo proxy` serves to besides this machine, as CIDR or
            an address whose trailing zero octets stand for any (10.0.0.0 is
            10.0.0.0/8).
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          maxItems: 64
      additionalProperties: false
    DeclaredSetting:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 128
          description: The key in the section of extensions.json.
        label:
          type: string
          maxLength: 128
        description:
          type: string
          maxLength: 1024
        kind:
          type: string
          enum: [integer, text, limit, map, choices]
          description:
            integer takes a whole number from minimum to maximum; text takes a
            non-empty string of at most 4096 bytes; limit takes a whole number
            from minimum to maximum, or -1 for no limit; map takes an object of
            at most 64 names to text, each name 1 to 64 bytes without whitespace
            or =, each value text, and unset reads as empty; choices takes an
            object like map whose values are each one of options or a name in
            the section's options_from map, a row left out being unset.
        default:
          anyOf:
            - type: integer
            - type: string
            - type: 'null'
          description:
            What the section's owner uses while nothing is saved. Null when
            leaving the setting unset has a meaning of its own, which the
            description gives.
        minimum:
          anyOf:
            - type: integer
            - type: 'null'
          description: The smallest integer accepted; null for text and map.
        maximum:
          anyOf:
            - type: integer
            - type: 'null'
          description: The largest integer accepted; null for text and map.
        value:
          anyOf:
            - type: integer
            - type: string
            - type: object
              additionalProperties:
                type: string
              maxProperties: 64
            - type: 'null'
          description:
            The saved value, or null when nothing is saved and the default
            applies. A saved value of the wrong kind reads as null, and the
            section's problem names it.
        rows:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/DeclaredSettingRow'
            - type: 'null'
          description: The rows a choices setting offers; null for other kinds.
        options:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: The fixed choices of a choices setting.
        options_from:
          anyOf:
            - type: string
            - type: 'null'
          description:
            The map field in this section whose names are options too.
      required:
        [
          key,
          label,
          description,
          kind,
          default,
          minimum,
          maximum,
          value,
          rows,
          options,
          options_from,
        ]
      additionalProperties: false
    DeclaredSettingRow:
      type: object
      properties:
        name:
          type: string
        unset:
          type: string
          description: What leaving the row unset means.
      required: [name, unset]
      additionalProperties: false
    DeclaredSettingsSection:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ID'
          description:
            The section's key in extensions.json. The daemon's own sections take
            names no extension may have; every other section is named after the
            extension that declares it.
        label:
          type: string
          maxLength: 128
          description:
            What the section configures, for a reader who does not know who
            declares it.
        category:
          type: string
          enum: [web_search, context, agents, models_and_caching, tools]
          description:
            The part of /config the section belongs to. web_search is what
            web_search asks and where; context is how a session's context is
            kept within its window; agents is how many agents a session may
            spawn and how deep; models_and_caching is the model catalog and
            prompt cache warming; tools is what the agent drives or reaches,
            such as MCP servers, remote kernels and the desktop.
        description:
          type: string
          maxLength: 1024
        fields:
          type: array
          items:
            $ref: '#/components/schemas/DeclaredSetting'
          maxItems: 64
        problem:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
          description:
            Why the section's owner cannot use its saved section, when it
            cannot.
      required: [name, label, category, description, fields, problem]
      additionalProperties: false
    DeclaredSettings:
      type: object
      properties:
        sections:
          type: array
          items:
            $ref: '#/components/schemas/DeclaredSettingsSection'
          maxItems: 512
          description:
            The daemon's own sections, then the sections installed extensions
            declare, in registry order.
      required: [sections]
      additionalProperties: false
    DeclaredSettingsPatch:
      type: object
      properties:
        values:
          type: object
          description:
            Section name to declared key to value. A value replaces the saved
            one; null removes it so the default applies. Unknown sections,
            undeclared keys, values outside the declaration, and a section its
            owner's own check rejects are refused, and nothing is saved.
          additionalProperties:
            type: object
            additionalProperties:
              anyOf:
                - type: integer
                - type: string
                - type: object
                  additionalProperties:
                    type: string
                  maxProperties: 64
                - type: 'null'
      required: [values]
      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
    DeclaredSettingsResource:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/ResourceURL'
        etag:
          $ref: '#/components/schemas/ETag'
        value:
          $ref: '#/components/schemas/DeclaredSettings'
      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'
        extension_settings:
          $ref: '#/components/schemas/DeclaredSettings'
        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'
            extension_settings:
              $ref: '#/components/schemas/ResourceValidator'
            capabilities:
              $ref: '#/components/schemas/ResourceValidator'
            models:
              $ref: '#/components/schemas/ResourceValidator'
            ui:
              $ref: '#/components/schemas/ResourceValidator'
          required:
            [
              providers,
              mcp,
              extensions,
              extension_settings,
              capabilities,
              models,
              ui,
            ]
          additionalProperties: false
      required:
        [
          providers,
          mcp,
          extensions,
          extension_settings,
          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/DeclaredSettings'
        - $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/DeclaredSettingsPatch'
        - $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,
            extension_settings, 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
    DeclaredSettingsChange:
      type: object
      properties:
        group:
          const: extension_settings
        resource:
          $ref: '#/components/schemas/DeclaredSettingsResource'
        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/DeclaredSettingsChange'
        - $ref: '#/components/schemas/CapabilitySettingsChange'
        - $ref: '#/components/schemas/ModelSettingsChange'
        - $ref: '#/components/schemas/UISettingsChange'
    UsageDay:
      type: object
      description:
        One day of the client's, with what the provider calls used in it.
      properties:
        start:
          $ref: '#/components/schemas/Timestamp'
        calls:
          $ref: '#/components/schemas/Counter'
        errors:
          $ref: '#/components/schemas/Counter'
        input_tokens:
          $ref: '#/components/schemas/Counter'
        cached_input_tokens:
          $ref: '#/components/schemas/Counter'
        cache_creation_tokens:
          $ref: '#/components/schemas/Counter'
        output_tokens:
          $ref: '#/components/schemas/Counter'
        reasoning_tokens:
          $ref: '#/components/schemas/Counter'
      required:
        [
          start,
          calls,
          errors,
          input_tokens,
          cached_input_tokens,
          cache_creation_tokens,
          output_tokens,
          reasoning_tokens,
        ]
      additionalProperties: false
    UsageLine:
      type: object
      description:
        What one profile, account and model used over the whole window.
      properties:
        profile:
          type: string
        provider:
          type: string
        account:
          type: [string, 'null']
          description: Null for a provider without an account pool.
        model:
          type: string
        calls:
          $ref: '#/components/schemas/Counter'
        errors:
          $ref: '#/components/schemas/Counter'
        input_tokens:
          $ref: '#/components/schemas/Counter'
        cached_input_tokens:
          $ref: '#/components/schemas/Counter'
        cache_creation_tokens:
          $ref: '#/components/schemas/Counter'
        output_tokens:
          $ref: '#/components/schemas/Counter'
        reasoning_tokens:
          $ref: '#/components/schemas/Counter'
      required:
        [
          profile,
          provider,
          account,
          model,
          calls,
          errors,
          input_tokens,
          cached_input_tokens,
          cache_creation_tokens,
          output_tokens,
          reasoning_tokens,
        ]
      additionalProperties: false
    UsageScope:
      type: object
      description:
        One provider and account that used the window, named as `lines` names
        them.
      properties:
        provider:
          type: string
        account:
          type: [string, 'null']
          description: Null for a provider without an account pool.
      required: [provider, account]
      additionalProperties: false
    UsageSummary:
      type: object
      properties:
        generated_at:
          $ref: '#/components/schemas/Timestamp'
        utc_offset_minutes:
          type: integer
        days:
          type: array
          description:
            Oldest first, one for each day asked for, empty days included. A day
            counts only the rows the requested `provider` and `account` match.
          items:
            $ref: '#/components/schemas/UsageDay'
        lines:
          type: array
          description:
            Most used first, at most 100 of what the request matches;
            `lines_truncated` says more matched than are listed.
          items:
            $ref: '#/components/schemas/UsageLine'
        scopes:
          type: array
          description:
            Every provider and account with use in the window, before `provider`
            and `account` narrow the totals, so a client can offer what it is
            not showing. At most 200, sorted by provider then account.
          items:
            $ref: '#/components/schemas/UsageScope'
        lines_truncated:
          type: boolean
          description:
            Whether more profile, account and model lines matched than `lines`
            lists.
        scopes_truncated:
          type: boolean
          description:
            Whether more provider and account scopes used the window than
            `scopes` lists.
      required:
        [
          generated_at,
          utc_offset_minutes,
          days,
          lines,
          scopes,
          lines_truncated,
          scopes_truncated,
        ]
      additionalProperties: false
    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'
            shell_output_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,
              shell_output_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
              shell_output_bytes: 0
              recent_backup_bytes: 0
              recent_backup_count: 0
          measured_at: '2026-10-02T14:00:00Z'
    CompactionProgress:
      description:
        Live progress for the current compaction, not a durable transcript
        entry. Counts cover the current stage or batch, not the whole
        compaction.
      type: object
      properties:
        strategy:
          type: string
        stage:
          type: string
          enum: [preparing, summarizing, merging, notes]
        completed:
          type: integer
          minimum: 0
        total:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
        active:
          type: integer
          minimum: 0
        started_at:
          type: string
          format: date-time
      required: [strategy, stage, completed, total, started_at]
      additionalProperties: false
    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'
        compaction:
          description:
            Present while this run is preparing compacted history; absent or
            null otherwise.
          anyOf:
            - $ref: '#/components/schemas/CompactionProgress'
            - 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
        pin_before:
          description:
            Moves the session among the pinned, before this pinned session, or
            last when null. The session must be pinned, in this patch or
            already. Fails with 409 `pin_target_invalid` when the target is not
            pinned, and 400 `pin_move_unpinned` when the session is not. Only
            this session is renumbered when a number is free between its new
            neighbours; otherwise the fewest neighbours shift in the same commit
            and are named in the collection stream's `invalidate` event. A shift
            changes their ETag, not their revision, so a change already admitted
            against them still commits.
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
      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]
        title:
          anyOf:
            - type: string
              minLength: 1
              x-max-utf8-bytes: 400
              maxLength: 160
            - type: 'null'
        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
          title: 'find which go files label python cells'
          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:
        configuration_etag:
          $ref: '#/components/schemas/ETag'
        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'
        role:
          type: string
          maxLength: 512
        started_by:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        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:
          description:
            Saved reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null retains legacy unset
            behavior.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        fast:
          type: boolean
        cyber_access:
          type: [string, 'null']
          enum: [daybreak_blue, 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'
        acp:
          description:
            Present only for ACP-owned sessions. Attachment state is read
            separately from the session capture.
          $ref: '#/components/schemas/ACPState'
        moved:
          description:
            Set once the session moved to another daemon; it then refuses new
            input (409 session_moved).
          anyOf:
            - $ref: '#/components/schemas/SessionMoved'
            - type: 'null'
        move_pending:
          description:
            Set while a move of this session waits at its checklist; the session
            is still live here.
          anyOf:
            - $ref: '#/components/schemas/SessionMovePending'
            - type: 'null'
      description:
        Session live fields and cursor are captured together. ACP attachment
        metadata is read separately. Extra response fields may be ignored.
      required:
        [
          id,
          name,
          automatic_name,
          workspace,
          location,
          parent_id,
          root_id,
          address,
          depth,
          closed,
          created_at,
          activity_at,
          role,
          started_by,
          provider_profile,
          model,
          effort,
          fast,
          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
    FastMode:
      type: object
      properties:
        fast:
          type: boolean
        support:
          type: object
          properties:
            status:
              type: string
              enum: [supported, unsupported, unknown]
            mode:
              type: [string, 'null']
            source:
              type: [string, 'null']
            detail:
              type: [string, 'null']
          required: [status]
          additionalProperties: false
        message:
          type: string
      required: [fast, support, message]
      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:
          description:
            Saved reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null retains legacy unset
            behavior.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        fast:
          type: boolean
          description:
            Provider fast-mode setting; defaults off and may affect billing.
        cyber_access:
          type: [string, 'null']
          enum: [daybreak_blue, null]
          description:
            Explicit session-scoped Codex Blue intent; null sends ordinary
            requests.
        context_window:
          description:
            Tokens this session compacts against instead of the model's
            catalogued window. Null uses the model's window.
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100000000
            - 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'
      required:
        [
          id,
          name,
          workspace,
          provider_profile,
          model,
          effort,
          fast,
          preferences,
          selection,
          revision,
        ]
      additionalProperties: false
      examples:
        - id: 01a0fcea-2b00-7000-8000-000000000001
          name: null
          workspace: /workspace/project
          provider_profile: personal
          model: example-model
          effort: null
          fast: false
          preferences:
            pinned: false
            pin_order: null
            archived: false
          selection:
            extensions: {}
            skills: {}
            instructions: {}
            mcp: {}
          revision: config-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:
          description:
            Saved reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null restores legacy unset
            behavior. Omission preserves the current choice.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        fast:
          type: boolean
          description:
            Enable provider fast mode; enabling requires a supported capability
            and may affect billing.
        cyber_access:
          type: [string, 'null']
          enum: [daybreak_blue, null]
          description: Select Blue for this session; null explicitly clears it.
        context_window:
          description:
            Tokens this session compacts against instead of the model's
            catalogued window. Null uses the model's window.
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100000000
            - 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
    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:
          description:
            Initial reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null or omission uses inherit.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        context_window:
          description:
            Tokens this session compacts against instead of the model's
            catalogued window. Null uses the model's window.
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100000000
            - type: 'null'
        cyber_access:
          type: [string, 'null']
          enum: [daybreak_blue, null]
          description:
            Explicit Blue at creation; null or omission selects standard.
      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:
          description:
            Initial reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null or omission uses inherit.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        context_window:
          description:
            Tokens this session compacts against instead of the model's
            catalogued window. Null uses the model's window.
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100000000
            - type: 'null'
        cyber_access:
          type: [string, 'null']
          enum: [daybreak_blue, null]
          description:
            Explicit Blue at creation; null or omission selects standard.
      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:
          description:
            Initial reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null or omission uses inherit.
          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:
          description:
            Initial reasoning choice. inherit follows the profile override or
            model default; default bypasses the profile override. Other strings
            select an explicit supported level. Null or omission uses inherit.
          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/SideQuestionSessionRequest'
        - $ref: '#/components/schemas/ChildSessionRequest'
        - $ref: '#/components/schemas/ACPSessionRequest'
    Creation:
      type: object
      properties:
        submitted:
          oneOf:
            - $ref: '#/components/schemas/NewSessionIntent'
            - $ref: '#/components/schemas/ForkSessionIntent'
            - $ref: '#/components/schemas/SideQuestionSessionRequest'
            - $ref: '#/components/schemas/ChildSessionIntent'
            - $ref: '#/components/schemas/ACPSessionIntent'
        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
    QueueCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/QueueItem'
          maxItems: 200
        total:
          $ref: '#/components/schemas/Counter'
        limit:
          $ref: '#/components/schemas/Counter'
        page:
          $ref: '#/components/schemas/PageDescriptor'
      required: [items, total, limit, page]
      additionalProperties: false
      examples:
        - items: []
          total: 0
          limit: 1000
          page:
            title: queue
            empty_state: nothing is waiting
            rows: []
            glance: null
            actions: []
            summary: 0 inputs waiting
    QueueItem:
      type: object
      description: One input waiting in a session's inbox.
      properties:
        id:
          $ref: '#/components/schemas/ID'
        kind:
          type: string
          enum:
            [
              task,
              request,
              message,
              result,
              unreviewed,
              webhook,
              event,
              chat,
              continue,
              acp,
              shell,
              note,
              job,
            ]
        source:
          type: string
          maxLength: 256
          description: Who submitted it, as the transcript names the source.
        from:
          type: string
          maxLength: 4096
        sender_session_id:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        delivery:
          type: string
          enum: [steer, wait, alone, next_turn, attach]
          description:
            "`steer` joins a running turn at its next step, `wait` waits for the
            turn to end, `alone` takes a turn of its own, `next_turn` joins a
            running turn at its next step or rides with the next turn without
            starting one, and `attach` joins a running turn at its next step or
            is written into a resting session's transcript without a turn."
        text:
          type: string
          maxLength: 2000
        text_truncated:
          type: boolean
        editable:
          type: boolean
          description:
            A person's typed message whose text is all of it, with no images,
            files, pasted text or skills, so an edit from the queue loses
            nothing.
        images:
          type: array
          items:
            $ref: '#/components/schemas/QueueImage'
        files:
          type: array
          items:
            $ref: '#/components/schemas/QueueFile'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        position:
          $ref: '#/components/schemas/Counter'
        attempts:
          $ref: '#/components/schemas/Counter'
        last_error:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
      required:
        [
          id,
          kind,
          source,
          from,
          sender_session_id,
          delivery,
          text,
          text_truncated,
          editable,
          images,
          files,
          created_at,
          position,
          attempts,
          last_error,
        ]
      additionalProperties: false
    QueueImage:
      type: object
      properties:
        mime_type:
          type: string
          maxLength: 256
        width:
          $ref: '#/components/schemas/Counter'
        height:
          $ref: '#/components/schemas/Counter'
        bytes:
          $ref: '#/components/schemas/Counter'
      required: [mime_type, width, height, bytes]
      additionalProperties: false
    QueueFile:
      type: object
      properties:
        name:
          type: string
          maxLength: 4096
        bytes:
          $ref: '#/components/schemas/Counter'
      required: [name, bytes]
      additionalProperties: false
    QueueOrder:
      type: object
      properties:
        ids:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 1000
      required: [ids]
      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
    JobRecord:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        command:
          type: string
          maxLength: 4096
        state:
          type: string
          enum: [running, exited]
        exit_code:
          anyOf:
            - type: integer
            - type: 'null'
        timed_out:
          type: boolean
        service:
          type: boolean
          description: Started to keep running, so nothing waits on its end.
        kind:
          type: string
          enum: [command, cell]
        parent_id:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        started_at:
          $ref: '#/components/schemas/Counter'
          description: Wall-clock milliseconds since the epoch.
        ended_at:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        bytes:
          $ref: '#/components/schemas/Counter'
          description: Everything the job has written, kept or not.
      required:
        [
          id,
          command,
          state,
          exit_code,
          timed_out,
          service,
          kind,
          parent_id,
          started_at,
          ended_at,
          bytes,
        ]
      additionalProperties: false
    JobRecordCollection:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/JobRecord'
          maxItems: 100
      required: [items]
      additionalProperties: false
    JobOutputPage:
      type: object
      properties:
        job:
          $ref: '#/components/schemas/JobRecord'
        offset:
          $ref: '#/components/schemas/Counter'
          description: Byte the page starts at.
        next_offset:
          $ref: '#/components/schemas/Counter'
          description:
            Byte to continue from; equal to `offset` when there is nothing more
            yet.
        text:
          type: string
          maxLength: 65536
        source:
          anyOf:
            - type: string
              maxLength: 16384
            - type: 'null'
          description:
            Full cell source when `job.kind` is `cell`, bounded to 16384
            characters.
      required: [job, offset, next_offset, text, source]
      additionalProperties: false
    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
        kind:
          type: string
          enum: [command, cell]
        parent_id:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        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, kind, parent_id, started_at]
      additionalProperties: false
    Kernel:
      type: object
      properties:
        state:
          type: string
          enum: [none, booting, attached, reattaching, busy, 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
    Cost:
      type: object
      description:
        The amount a provider reported for one call, and the statement that the
        amount belongs to.
      properties:
        usd:
          type: number
          minimum: 0
        basis:
          type: string
          enum: [charged, counted, listed]
      required: [usd, basis]
      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'
        size:
          description: >-
            Set when the token counts are a strategy's size for a request no
            call has measured yet, such as after a compaction, rather than one
            call's own report; its parts say how much was measured and how much
            estimated.
          anyOf:
            - $ref: '#/components/schemas/Size'
            - type: 'null'
        cache_miss_tokens:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        cache_drift_tokens:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        spent:
          anyOf:
            - $ref: '#/components/schemas/Cost'
            - 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'
            side_question:
              anyOf:
                - $ref: '#/components/schemas/SideQuestion'
                - type: 'null'
            shell_commands:
              type: array
              items:
                $ref: '#/components/schemas/ShellCommand'
              maxItems: 32
            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,
              shell_commands,
            ]
      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: []
          shell_commands: []
          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/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
          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'
        - $ref: '#/components/schemas/SessionStatusRead'
    SessionStatusRead:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        cursor:
          $ref: '#/components/schemas/Cursor'
        status:
          $ref: '#/components/schemas/SessionStatus'
        kernel:
          $ref: '#/components/schemas/Kernel'
        usage:
          $ref: '#/components/schemas/Usage'
        glances:
          type: array
          items:
            $ref: '#/components/schemas/Glance'
          maxItems: 16
      description:
        The live facts a watching client keeps current, read from the session's
        own memory and its kernel, with no configuration, history, or
        composition read. Kernel job changes and glance changes also arrive on
        the session stream, so this is a safety read rather than the cadence.
      required: [id, cursor, status, kernel, usage, glances]
      additionalProperties: false
    SessionChange:
      type: object
      properties:
        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: [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
    AttachmentToken:
      type: string
      pattern: ^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$
      description:
        32 random bytes, canonical unpadded base64url (the last character
        carries no stray bits).
    ACPMCPServer:
      type: object
      description:
        Editor-supplied stdio MCP server. command is an absolute executable run
        without a shell in the session workspace; env values are literal secrets
        held only in daemon memory.
      properties:
        name:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        command:
          type: string
          minLength: 1
          maxLength: 4096
        args:
          type: array
          items:
            type: string
            maxLength: 32768
          maxItems: 256
        env:
          type: array
          description: Names must be unique; duplicates are rejected.
          items:
            $ref: '#/components/schemas/ACPEnvVariable'
          maxItems: 128
      required: [name, command, args, env]
      additionalProperties: false
    ACPEnvVariable:
      type: object
      properties:
        name:
          type: string
          pattern: ^[A-Za-z_][A-Za-z0-9_]{0,127}$
        value:
          type: string
          maxLength: 32768
      required: [name, value]
      additionalProperties: false
    ACPMCPServerIdentity:
      type: object
      description:
        Durable stand-in for an overlay server. The fingerprint is a keyed
        digest of command, args and env; literal values are never stored.
      properties:
        name:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        fingerprint:
          type: string
          pattern: ^[A-Za-z0-9_-]{43}$
      required: [name, fingerprint]
      additionalProperties: false
    ACPSessionRequest:
      type: object
      properties:
        kind:
          const: acp
        workspace:
          $ref: '#/components/schemas/Workspace'
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/ACPMCPServer'
          maxItems: 32
      required: [kind, workspace, mcp_servers]
      additionalProperties: false
      description:
        Creates an ACP-owned session. The overlay is prepared strictly before
        the creation decision commits (any server failure rejects the creation
        with 409 mcp_overlay_failed); the durable ACP marker, the initial
        attachment for the Albedo-Attachment-Token header and the overlay are
        installed before the first session preparation. Resending the identical
        request under the same session ID is the recovery path; see
        robot-docs/acp.md.
    ACPSessionIntent:
      type: object
      properties:
        kind:
          const: acp
        workspace:
          $ref: '#/components/schemas/Workspace'
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/ACPMCPServerIdentity'
          maxItems: 32
      required: [kind, workspace, mcp_servers]
      additionalProperties: false
    ACPState:
      type: object
      description:
        Present on ACP-owned sessions. Other clients may read, stop and delete
        them but not submit input or change execution.
      properties:
        attachment:
          type: string
          enum: [attached, detached]
      required: [attachment]
      additionalProperties: false
    ACPAttachRequest:
      type: object
      properties:
        workspace:
          $ref: '#/components/schemas/Workspace'
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/ACPMCPServer'
          maxItems: 32
      required: [workspace, mcp_servers]
      additionalProperties: false
    ACPLease:
      type: object
      properties:
        heartbeat_ms:
          type: integer
          minimum: 1
        lease_ms:
          type: integer
          minimum: 1
      required: [heartbeat_ms, lease_ms]
      additionalProperties: false
    ACPActiveTurn:
      type: object
      properties:
        turn_id:
          $ref: '#/components/schemas/ID'
        acp_input_id:
          description:
            The exclusive acp_prompt input of this turn, which session/cancel
            targets. Null for a turn started by system work (mail, schedule),
            which stays observable and busy but is never interrupted by the
            adapter.
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
      required: [turn_id, acp_input_id]
      additionalProperties: false
    ACPAttachment:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        lease:
          $ref: '#/components/schemas/ACPLease'
        cursor:
          $ref: '#/components/schemas/Cursor'
        active_turn:
          anyOf:
            - $ref: '#/components/schemas/ACPActiveTurn'
            - type: 'null'
        pending_input_ids:
          type: array
          description:
            Accepted ACP inputs not yet consumed, in acceptance order.
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 32
        output_boundaries:
          type: array
          description:
            For every unfinished live text or thinking message at the cursor,
            how much had streamed before it. Reconciliation only; the client
            never emits this content. Installing this capture stands in for the
            initial snapshot reset of a fresh stream.
          items:
            $ref: '#/components/schemas/ACPOutputBoundary'
          maxItems: 256
        history_cutoff:
          $ref: '#/components/schemas/Counter'
          description:
            Position of the newest durable history entry at the same capture as
            cursor and output_boundaries (0 when there is none). Entries at or
            before it are history; everything later arrives on the stream after
            cursor.
      required:
        [
          session_id,
          lease,
          cursor,
          active_turn,
          pending_input_ids,
          output_boundaries,
          history_cutoff,
        ]
      additionalProperties: false
    ACPOutputBoundary:
      type: object
      properties:
        live_id:
          $ref: '#/components/schemas/ID'
        utf8_bytes:
          type: integer
          minimum: 0
      required: [live_id, utf8_bytes]
      additionalProperties: false
    ACPTextBlock:
      type: object
      properties:
        type:
          const: text
        text:
          type: string
          maxLength: 1048576
        annotations:
          $ref: '#/components/schemas/DynamicJSON'
        meta:
          $ref: '#/components/schemas/DynamicJSON'
      required: [type, text]
      additionalProperties: false
    ACPResourceLinkBlock:
      type: object
      properties:
        type:
          const: resource_link
        uri:
          type: string
          minLength: 1
          maxLength: 8192
        name:
          type: string
          maxLength: 4096
        title:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
        description:
          anyOf:
            - type: string
              maxLength: 16384
            - type: 'null'
        mime_type:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
        size:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
        annotations:
          $ref: '#/components/schemas/DynamicJSON'
        meta:
          $ref: '#/components/schemas/DynamicJSON'
      required: [type, uri, name]
      additionalProperties: false
    ACPPromptBlock:
      oneOf:
        - $ref: '#/components/schemas/ACPTextBlock'
        - $ref: '#/components/schemas/ACPResourceLinkBlock'
    ACPPromptInputRequest:
      type: object
      properties:
        kind:
          const: acp_prompt
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/ACPPromptBlock'
          minItems: 1
          maxItems: 256
      required: [kind, blocks]
      additionalProperties: false
      description:
        Only for ACP sessions, with the attachment token. Forms its own logical
        turn; no other input joins it and it joins no other turn. Blocks keep
        their order, metadata and original URIs.
    ImageUpload:
      type: object
      properties:
        mime_type:
          type: string
          enum: [image/png, image/jpeg, 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
    FileAttachment:
      type: object
      description:
        An attached file's name and decoded size; never its saved path.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          x-max-utf8-bytes: 255
        size:
          type: integer
          minimum: 0
          maximum: 20971520
          description: Decoded bytes.
      required: [name, size]
      additionalProperties: false
    FileUpload:
      type: object
      description:
        A file for a local workspace, saved under the daemon home and exposed to
        the model by path. At most 20 MiB of decoded files per input. Remote
        workspaces refuse file uploads.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          x-max-utf8-bytes: 255
          description:
            Plain filename, without path separators, NUL, CR or LF; not dot or
            dot-dot.
        data:
          type: string
          contentEncoding: base64
      required: [name, 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
        files:
          type: array
          description:
            Local-workspace files, appended as quoted filename and saved-path
            pairs to the model's text only. The text stays as sent; history
            reports each file's name and size in HistoryEntry.files. At most 20
            MiB decoded in total.
          items:
            $ref: '#/components/schemas/FileUpload'
          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
        - required: [files]
          properties:
            files:
              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
    InputHold:
      type: object
      properties:
        lease_ms:
          type: integer
          minimum: 1
          description: How long the hold lasts unless the message is held again.
      required: [lease_ms]
      additionalProperties: false
    InputEdit:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/Input'
      required: [input]
      additionalProperties: false
    InputRequest:
      oneOf:
        - $ref: '#/components/schemas/MessageInputRequest'
        - $ref: '#/components/schemas/ContinueInputRequest'
        - $ref: '#/components/schemas/SkillInputRequest'
        - $ref: '#/components/schemas/CommandInputRequest'
        - $ref: '#/components/schemas/ACPPromptInputRequest'
      x-max-encoded-bytes: 100200000
    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, acp_prompt]
        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
    ArtifactID:
      type: string
      pattern: ^[a-z0-9]{12}$
    Artifact:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ArtifactID'
        key:
          type: string
          pattern: ^[0-9a-f]{32}$
          description:
            The capability that serves its pages,
            `/frame/{id}.{key}/{version}/{path}`.
        title:
          type: string
          maxLength: 1000
        version:
          type: integer
          minimum: 1
        versions:
          type: integer
          minimum: 1
        entry:
          type: string
          maxLength: 512
        session_id:
          $ref: '#/components/schemas/ID'
        session_name:
          type: [string, 'null']
          maxLength: 1000
        session_deleted:
          type: boolean
        workspace:
          type: string
          maxLength: 4096
        created_at:
          $ref: '#/components/schemas/Counter'
        updated_at:
          $ref: '#/components/schemas/Counter'
        bytes:
          $ref: '#/components/schemas/Counter'
      required:
        [
          id,
          key,
          title,
          version,
          versions,
          entry,
          session_id,
          session_name,
          session_deleted,
          workspace,
          created_at,
          updated_at,
          bytes,
        ]
    ArtifactPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Artifact'
          maxItems: 200
        next:
          type: [string, 'null']
          maxLength: 4096
      required: [items, next]
      additionalProperties: false
    ArtifactFile:
      type: object
      properties:
        path:
          type: string
          maxLength: 512
        size:
          $ref: '#/components/schemas/Counter'
      required: [path, size]
      additionalProperties: false
    ArtifactVersion:
      type: object
      properties:
        version:
          type: integer
          minimum: 1
        entry:
          type: string
          maxLength: 512
        created_at:
          $ref: '#/components/schemas/Counter'
        cell_id:
          type: [string, 'null']
          maxLength: 1000
        files:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactFile'
          maxItems: 2000
        bytes:
          $ref: '#/components/schemas/Counter'
      required: [version, entry, created_at, cell_id, files, bytes]
      additionalProperties: false
    ArtifactDetail:
      allOf:
        - $ref: '#/components/schemas/Artifact'
        - type: object
          properties:
            history:
              type: array
              description: Every version, newest first.
              items:
                $ref: '#/components/schemas/ArtifactVersion'
          required: [history]
    ArtifactState:
      type: object
      description: The page's localStorage.
      additionalProperties:
        type: string
    ArtifactError:
      type: object
      properties:
        message:
          type: string
          maxLength: 4000
        source:
          type: string
          maxLength: 2000
        line:
          type: integer
          minimum: 0
        column:
          type: integer
          minimum: 0
        stack:
          type: string
          maxLength: 8000
      required: [message]
      additionalProperties: false
    ToolActivity:
      type: object
      properties:
        kind:
          type: string
          enum:
            [read, search, list, run, web, display, mcp, cua, artifact, skill]
        target:
          type: string
          maxLength: 1000
        title:
          type: string
          maxLength: 1000
          description: The optional display() title.
        description:
          type: string
          maxLength: 4000
          description: The optional display() description.
        detail:
          type: string
          maxLength: 16000
          description:
            What the person watching sees of the result, as markdown; a web
            search's answer and sources, or displayed content.
        ms:
          type: integer
          minimum: 0
          description:
            How long the call took, when it ended while its cell's trace was
            open.
        ok:
          type: boolean
          description:
            Whether the call worked, when it ended while its cell's trace was
            open.
        artifact:
          type: object
          description:
            The artifact version an `artifact` activity made; its title is the
            target.
          properties:
            id:
              $ref: '#/components/schemas/ArtifactID'
            version:
              type: integer
              minimum: 1
          required: [id, version]
          additionalProperties: false
        skill:
          type: object
          description:
            Where the skill a `skill` activity loaded was found; its name is the
            target. A cell notes each skill once, when it reads the skill's
            SKILL.md from the start or runs its command.
          properties:
            scope:
              $ref: '#/components/schemas/SkillScope'
            source:
              type: string
              maxLength: 1000
              description: The installed SKILL.md path.
          required: [scope, source]
          additionalProperties: false
      required: [kind, target]
      additionalProperties: false
    SkillScope:
      type: string
      description:
        The discovery root a skill came from. Empty for a user activation
        recorded before scopes were.
      enum: [workspace, user, built-in, '']
    SkillLoad:
      type: object
      description:
        A skill a user's slash activation loaded, as the `skill` JSON part of
        that user entry.
      properties:
        name:
          type: string
        scope:
          $ref: '#/components/schemas/SkillScope'
        source:
          type: string
          description: The installed SKILL.md path.
      required: [name, scope, source]
      additionalProperties: false
    SkillLoadSummary:
      type: object
      description:
        One skill a session loaded, by the model or the user, with how often and
        when.
      properties:
        name:
          type: string
        scope:
          $ref: '#/components/schemas/SkillScope'
        source:
          type: string
          description: The installed SKILL.md path the newest load used.
        count:
          type: integer
          minimum: 1
        first_loaded_at:
          type: integer
          description: Unix seconds.
        last_loaded_at:
          type: integer
          description: Unix seconds.
      required: [name, scope, source, count, first_loaded_at, last_loaded_at]
      additionalProperties: false
    SkillLoadList:
      type: object
      properties:
        items:
          type: array
          maxItems: 256
          description: First loaded first.
          items:
            $ref: '#/components/schemas/SkillLoadSummary'
      required: [items]
      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'
        old_text:
          description:
            The whole file before the change, null when the change created it.
            Present together with new_text only when both fit the trace's
            snapshot budget.
          anyOf:
            - type: string
              maxLength: 131072
            - type: 'null'
        new_text:
          type: string
          maxLength: 131072
          description: The whole file after the change.
      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
        calls:
          type: array
          description:
            The session bindings the cell's code calls (`files.find`, `run`),
            sorted. Absent for a cell replayed from inside another.
          items:
            type: string
            maxLength: 1000
          maxItems: 64
      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
          description:
            What the value is. A user entry's `skill` value is the SkillLoad its
            slash activation loaded.
        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, request, message, result, unreviewed, webhook, event]
        external:
          type: boolean
          description:
            The letter came from outside the agents, as a webhook or an
            extension's channel.
        answer:
          type: boolean
          description: The letter is a child's answer to its parent.
      required:
        [mail_id, sender_session_id, sender_label, kind, external, answer]
      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,
              shell_command,
            ]
        turn_type:
          type: string
          enum: [user, agent, webhook, event, 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'
                title:
                  anyOf:
                    - type: string
                      maxLength: 160
                    - type: 'null'
                status:
                  type: string
                  enum: [completed, failed]
                  description:
                    Outcome of the whole call, derived from the stored result
                    exactly as the live tool event's status, so rows recorded
                    before this field have it too.
              required: [name, tool_call_id, progress_call_id, status]
              additionalProperties: false
            - type: 'null'
        phase:
          description:
            Assistant response phase. Null for legacy rows, unfinished
            responses, and non-assistant entries.
          anyOf:
            - type: string
              enum: [commentary, final]
            - type: 'null'
        thinking_duration_ms:
          description: Observed thinking duration, when recorded.
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        files:
          type: array
          description:
            Files attached to a user entry, in upload order, as recorded when
            the input was admitted. Absent when the entry has none, including
            entries recorded before file uploads. Text that resembles a file
            label is prose, not attachment metadata. Attached bytes may be
            pruned while this metadata remains.
          items:
            $ref: '#/components/schemas/FileAttachment'
          minItems: 1
          maxItems: 10
      required:
        [
          id,
          position,
          kind,
          phase,
          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, event]
        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
    EntryContentBatchPart:
      type: object
      properties:
        entry_id:
          $ref: '#/components/schemas/ID'
        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:
        One field piece of one named entry; offsets count exact stored UTF-8
        bytes.
      required: [entry_id, field, offset_bytes, encoding, text, complete]
      additionalProperties: false
    EntryContentBatch:
      type: object
      properties:
        parts:
          type: array
          items:
            $ref: '#/components/schemas/EntryContentBatchPart'
          maxItems: 200
        next:
          anyOf:
            - $ref: '#/components/schemas/PageToken'
            - type: 'null'
      x-max-decoded-content-bytes: 524288
      required: [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, title, side]
        provider_profile:
          $ref: '#/components/schemas/ID'
        account_id:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        effort:
          description:
            Resolved reasoning level sent with this provider attempt. Null means
            no explicit level was supplied. Saved choices such as inherit and
            default are resolved before recording.
          anyOf:
            - type: string
              maxLength: 256
            - 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, shared, system, input]
              index:
                anyOf:
                  - $ref: '#/components/schemas/Counter'
                  - type: 'null'
              ttl_seconds:
                $ref: '#/components/schemas/Counter'
            required: [through, index, ttl_seconds]
            additionalProperties: false
        input_chain:
          anyOf:
            - type: string
              maxLength: 65536
            - type: 'null'
        stream:
          anyOf:
            - type: object
              properties:
                first_event_ms:
                  anyOf:
                    - $ref: '#/components/schemas/Counter'
                    - type: 'null'
                events:
                  $ref: '#/components/schemas/Counter'
                thinking_bytes:
                  $ref: '#/components/schemas/Counter'
                output_bytes:
                  $ref: '#/components/schemas/Counter'
              required: [first_event_ms, events, thinking_bytes, output_bytes]
              additionalProperties: false
            - type: 'null'
        first_byte_ms:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        total_tokens:
          $ref: '#/components/schemas/TokenObservation'
        response_id:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
        model_version:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
        trace_id:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
        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,
          effort,
          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,
          input_chain,
          stream,
          first_byte_ms,
          total_tokens,
          response_id,
          model_version,
          trace_id,
        ]
      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
    ContextWindow:
      type: object
      properties:
        context_window:
          description:
            The window set for this session. Null when it uses the model's.
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        model_context_tokens:
          description:
            The model's own window, with any raised cap or context limit
            applied. Null when the catalog does not know the model.
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        effective_context_tokens:
          description: The window compaction measures against.
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        source:
          type: string
          enum: [session, model, unknown]
        message:
          type: string
          description: One sentence a client can show as it is.
      required:
        [
          context_window,
          model_context_tokens,
          effective_context_tokens,
          source,
          message,
        ]
      additionalProperties: false
    SessionFile:
      type: object
      properties:
        path:
          type: string
          description:
            Absolute location as the daemon spells it, `host:/path` for a remote
            workspace.
        size:
          $ref: '#/components/schemas/Counter'
        modified_at:
          $ref: '#/components/schemas/Timestamp'
        text:
          type: string
          description: The file's contents. At most 1 MiB of UTF-8 without NUL.
      required: [path, size, modified_at, text]
      additionalProperties: false
    ChangedFile:
      type: object
      properties:
        path:
          type: string
          maxLength: 4096
          description: Relative to the checkout root.
        old_path:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          description: Where a renamed file came from.
        status:
          type: string
          enum: [modified, added, deleted, renamed, untracked]
        added:
          $ref: '#/components/schemas/Counter'
        removed:
          $ref: '#/components/schemas/Counter'
        binary:
          type: boolean
          description: Binary content, or text that is not UTF-8.
        diff:
          anyOf:
            - type: string
            - type: 'null'
          description:
            Unified diff with git's `diff --git` and `---`/`+++` headers,
            without a trailing newline. Null exactly when `omitted` is set.
        omitted:
          anyOf:
            - type: string
              enum: [binary, too_large, budget]
            - type: 'null'
      required: [path, old_path, status, added, removed, binary, diff, omitted]
      additionalProperties: false
    CheckoutChanges:
      type: object
      properties:
        checkout:
          type: object
          properties:
            kind:
              type: string
              enum: [git, jj]
            root:
              $ref: '#/components/schemas/Workspace'
            head:
              description:
                The short HEAD commit (git) or `@`'s change id (jj); null when
                unborn.
              anyOf:
                - type: string
                  maxLength: 256
                - type: 'null'
            branch:
              description: The branch (git) or the bookmark `@` works on (jj).
              anyOf:
                - type: string
                  maxLength: 4096
                - type: 'null'
          required: [kind, root, head, branch]
          additionalProperties: false
        base:
          type: object
          properties:
            spec:
              type: string
              enum: [uncommitted, upstream]
            label:
              type: string
              maxLength: 4096
              description:
                What the working copy was compared with, such as HEAD, @-,
                origin/main or trunk().
            commit:
              description:
                The short commit compared with; null for an unborn HEAD or jj's
                root.
              anyOf:
                - type: string
                  maxLength: 256
                - type: 'null'
          required: [spec, label, commit]
          additionalProperties: false
        files:
          type: array
          items:
            $ref: '#/components/schemas/ChangedFile'
          maxItems: 1000
        truncated:
          type: boolean
          description: More files changed than are listed.
      required: [checkout, base, files, truncated]
      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, 202]
          description:
            Expected JSON admission or success status. 202 requires the
            operation's typed receipt workflow; it does not mean completed work.
            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:
        shelf:
          description: Where a client shows the extension. Presentation only.
          type: string
          enum: [memory, reach, channels, providers, builtins]
        summary:
          description:
            One line a client shows beside the name; null when the extension has
            none.
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
        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: [shelf, summary, 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
        skill_name:
          type: string
          maxLength: 64
          description:
            Canonical skill name for inline dollar-prefixed mentions. Present
            only for skill inputs.
        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:
            oneOf:
              - $ref: '#/components/schemas/HTTPCommand'
              - $ref: '#/components/schemas/InputCommand'
          maxItems: 200
          description:
            HTTP declarations and skill inputs selected by discovery when no
            composition has been loaded. Follow loaded.next for further pages.
            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
    KernelRestartResult:
      type: object
      properties:
        old_kernel_id:
          description:
            The kernel the session held when the restart began; null when it
            held none. A kernel only recorded for the session is stopped too.
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        stopped_jobs:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
        ended_cells:
          type: array
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
      required: [old_kernel_id, stopped_jobs, ended_cells]
      additionalProperties: false
    RewindRequest:
      type: object
      properties:
        checkpoint_id:
          $ref: '#/components/schemas/ID'
        summary:
          anyOf:
            - type: object
              properties:
                instructions:
                  anyOf:
                    - type: string
                      maxLength: 4096
                    - type: 'null'
              additionalProperties: false
            - type: 'null'
          description:
            Ask for a summary of the removed tail, added to the session as a
            note.
      required: [checkpoint_id]
      additionalProperties: false
    RewindResult:
      type: object
      properties:
        archive_session_id:
          $ref: '#/components/schemas/ID'
        input:
          anyOf:
            - type: string
            - type: 'null'
          description:
            The text of the removed user message, when a person wrote it.
        summary:
          anyOf:
            - type: string
              maxLength: 32768
            - type: 'null'
          description:
            The summary note added after the cut, when one was requested.
      required: [archive_session_id, input, summary]
      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:
        cyber_access:
          type: object
          properties:
            status:
              type: string
              enum: [supported, unsupported, unknown]
            detail:
              type: string
          required: [status]
          additionalProperties: false
        id:
          $ref: '#/components/schemas/ID'
        label:
          type: string
          description:
            Human-facing catalog name, or the model ID when unavailable.
          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_effort_source:
          type: string
          enum: [provider, albedo]
        default_effort:
          description:
            Known reasoning default or adapter fallback, null when unknown.
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
        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
        compact_at:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
          description:
            The window the user saved for this model, below its own; null or
            absent follows the model.
        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
              kind:
                description:
                  Only with `include=files`. A link to a file is a file.
                type: string
                enum: [directory, file]
              size:
                description:
                  Only with `include=files`. Bytes for a file, null for a
                  directory.
                anyOf:
                  - $ref: '#/components/schemas/Counter'
                  - type: 'null'
              ignored:
                description:
                  Only with `include=files`. Whether git (or a colocated jj)
                  ignores it; null outside a repository, in a jj checkout
                  without git, or when git cannot say.
                anyOf:
                  - type: boolean
                  - type: 'null'
            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, key]
          default: model
          description:
            '`key` is an API key: saved in creds.json, or read from the daemon
            environment on every request when `source` is `env`.'
        source:
          type: string
          enum: [saved, env]
          description:
            '`env` accounts are never stored and cannot be removed or renamed;
            their label names the variable, as `$OPENROUTER_API_KEY`.'
        endpoint:
          description:
            The base url a key account sends to; null for sign-in accounts.
          anyOf:
            - type: string
              format: uri
              maxLength: 4096
            - type: 'null'
        limited_until:
          description:
            When a rate or usage limit recorded against this account ends; null
            when it has room.
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        email:
          description:
            The sign-in's email when the provider reports one; null for keys,
            environment accounts, and sign-ins that carry no email. New sign-ins
            take it as their label until renamed.
          anyOf:
            - type: string
              maxLength: 320
            - type: 'null'
        plan:
          description:
            The subscription tier the provider reports for a sign-in, such as
            `Max`, `Pro` or `Plus`; null when unknown.
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
        needs_sign_in:
          type: boolean
          description:
            The saved sign-in can no longer be used (its renewal was refused, it
            was revoked, or the provider suspended it) until it is signed in
            again. Rotation skips it. Always false for keys.
        selected_by_profiles:
          type: array
          description: Profiles pinned to this account by `account_id`.
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
        rotated_by_profiles:
          type: array
          description: Profiles that list this account in `account_ids`.
          items:
            $ref: '#/components/schemas/ID'
          maxItems: 200
      required:
        [
          id,
          provider,
          label,
          detail,
          kind,
          source,
          endpoint,
          limited_until,
          email,
          plan,
          needs_sign_in,
          selected_by_profiles,
          rotated_by_profiles,
        ]
      additionalProperties: false
    KeyAccountRequest:
      type: object
      properties:
        provider:
          description:
            The profile extension the key serves, such as `openai` or
            `opencode-go`.
          $ref: '#/components/schemas/ID'
        endpoint:
          type: string
          format: uri
          maxLength: 4096
        api_key:
          type: string
          minLength: 1
          writeOnly: true
          maxLength: 16384
        label:
          type: string
          minLength: 1
          maxLength: 256
      description:
        Saves an API key as an account. A key already saved for the same
        endpoint is refused with `key_exists`; its account id is in the problem
        detail.
      required: [provider, endpoint, api_key]
      additionalProperties: false
    AccountPatch:
      type: object
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 256
      required: [label]
      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
        terms:
          anyOf:
            - $ref: '#/components/schemas/LoginTerms'
            - type: 'null'
          description:
            The provider's warning that using this sign-in outside its own apps
            breaks its terms. Clients show it before starting the sign-in, and
            once before the first message on a profile that uses the sign-in
            rather than an API key. Dismissing that once adds `id` to the ui
            group's `dismissed_notices`.
      required: [id, label, detail, kind, flows, fields, terms]
      additionalProperties: false
    LoginTerms:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        about:
          type: string
          maxLength: 256
        headline:
          type: string
          maxLength: 256
        paragraphs:
          type: array
          items:
            type: string
            maxLength: 4096
          maxItems: 8
      required: [id, about, headline, paragraphs]
      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, request, message, result, unreviewed, webhook, event]
        external:
          type: boolean
          description:
            The letter came from outside the agents, as a webhook or an
            extension's channel.
        answer:
          type: boolean
          description: The letter is a child's answer to its parent.
        notifies:
          type: boolean
          description:
            The letter is what an agent says or answers, worth telling someone
            who looked away; a brief or a request is not.
        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,
          external,
          answer,
          notifies,
          bytes,
          sender_label,
        ]
      additionalProperties: false
    SessionKernelEvent:
      type: object
      properties:
        type:
          const: kernel
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            kernel:
              $ref: '#/components/schemas/Kernel'
          required: [kernel]
          additionalProperties: false
      description:
        The kernel's job facts changed. Published only when they differ from
        what the stream last carried, so a client that keeps them needs no
        status poll.
      required: [type, sequence, data]
      additionalProperties: false
    SessionGlancesEvent:
      type: object
      properties:
        type:
          const: glances
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          type: object
          properties:
            glances:
              type: array
              items:
                $ref: '#/components/schemas/Glance'
              maxItems: 16
          required: [glances]
          additionalProperties: false
      description:
        The loaded extensions' sidebar values changed, observed at a low rate
        while a client watches the stream.
      required: [type, sequence, data]
      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
    SideQuestionRequest:
      type: object
      properties:
        question:
          type: string
          minLength: 1
          maxLength: 16384
          x-max-utf8-bytes: 16384
      required: [question]
      additionalProperties: false
    SideQuestionPatchRequest:
      type: object
      properties:
        dismissed:
          type: boolean
      required: [dismissed]
      additionalProperties: false
    SideQuestion:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDv7'
        question:
          type: string
        status:
          type: string
          enum: [running, answered, failed, cancelled]
        answer:
          type: [string, 'null']
        error:
          type: [string, 'null']
        asked_at:
          type: integer
        continuation_session_id:
          type: [string, 'null']
        dismissed:
          type: boolean
      required:
        [
          id,
          question,
          status,
          answer,
          error,
          asked_at,
          continuation_session_id,
          dismissed,
        ]
      additionalProperties: false
    SideQuestionEnvelope:
      type: object
      properties:
        side_question:
          $ref: '#/components/schemas/SideQuestion'
      required: [side_question]
      additionalProperties: false
    SessionSideQuestionEvent:
      type: object
      properties:
        type:
          const: side_question
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          $ref: '#/components/schemas/SideQuestionEnvelope'
      required: [type, sequence, data]
      additionalProperties: false
    SideQuestionSessionRequest:
      type: object
      properties:
        kind:
          const: side_question
        source_session_id:
          $ref: '#/components/schemas/ID'
        side_question_id:
          $ref: '#/components/schemas/UUIDv7'
        name:
          type: [string, 'null']
      required: [kind, source_session_id, side_question_id]
      additionalProperties: false
    ShellCommandRequest:
      type: object
      properties:
        command:
          type: string
          minLength: 1
          maxLength: 16384
          x-max-utf8-bytes: 16384
      required: [command]
      additionalProperties: false
    ShellCommand:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUIDv7'
        command:
          type: string
          maxLength: 16384
          x-max-utf8-bytes: 16384
        status:
          type: string
          enum: [running, completed, cancelled, interrupted, failed]
        exit_code:
          type: [integer, 'null']
        output:
          type: string
          maxLength: 65536
          x-max-utf8-bytes: 65536
        output_bytes:
          type: integer
          minimum: 0
          maximum: 16777216
        model_text_bytes:
          type: integer
          minimum: 0
          description:
            UTF-8 bytes in the exact model-facing receipt, before timestamping.
        truncated:
          type: boolean
        error:
          type: [string, 'null']
        history_seq:
          type: [integer, 'null']
          minimum: 1
        delivery:
          description:
            Whether this receipt was included in a model request whose response
            has started. Pending does not wake an idle agent; unknown is legacy
            tracking, detached is removed by rewind. Execution status is
            independent.
          type: string
          enum: [unknown, pending, delivered, detached]
      required:
        [
          id,
          command,
          status,
          exit_code,
          output,
          output_bytes,
          model_text_bytes,
          truncated,
          error,
          history_seq,
          delivery,
        ]
      additionalProperties: false
    ShellCommandResponse:
      type: object
      properties:
        shell_command:
          $ref: '#/components/schemas/ShellCommand'
      required: [shell_command]
      additionalProperties: false
    ShellCommandOutput:
      type: object
      properties:
        text:
          type: string
          maxLength: 65536
          x-max-utf8-bytes: 65536
        next_offset:
          type: [integer, 'null']
          minimum: 0
      required: [text, next_offset]
      additionalProperties: false
    SessionShellCommandEvent:
      type: object
      properties:
        type:
          const: shell_command
        sequence:
          $ref: '#/components/schemas/Counter'
        data:
          $ref: '#/components/schemas/ShellCommandResponse'
      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'
            replaces_live_ids:
              type: array
              description:
                Live message IDs whose streamed text this durable entry
                represents, in order, as an exact prefix. Empty when nothing of
                this entry streamed live. Always sent by daemons with capability
                acp_attachment.
              items:
                $ref: '#/components/schemas/ID'
              maxItems: 256
          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
            title:
              anyOf:
                - type: string
                  maxLength: 160
                - type: 'null'
            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'
            status:
              type: string
              enum: [completed, failed]
              description:
                Outcome of the whole call. progress_call_id equals the call_id
                of any progress for this call, is unique within the session, and
                exists even when no progress was sent. Always sent by daemons
                with capability acp_attachment.
          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/SessionShellCommandEvent'
        - $ref: '#/components/schemas/SessionSideQuestionEvent'
        - $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'
        - $ref: '#/components/schemas/SessionKernelEvent'
        - $ref: '#/components/schemas/SessionGlancesEvent'
    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: []
            shell_commands: []
            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/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
            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/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"}},"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:
          description:
            Where a sender posts this hook's deliveries; null while no webhook
            intake listener runs.
          anyOf:
            - type: string
              format: uri
              maxLength: 4096
            - type: 'null'
        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
    DiscordID:
      type: string
      minLength: 1
      maxLength: 64
      description: Discord snowflake as decimal text.
    DiscordBot:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        name:
          type: string
          minLength: 1
          maxLength: 64
        owner_id:
          $ref: '#/components/schemas/DiscordID'
        enabled:
          type: boolean
        revision:
          type: integer
          minimum: 1
        state:
          type: string
          enum: [disabled, connecting, online, reconnecting, failed]
        detail:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
        user:
          anyOf:
            - $ref: '#/components/schemas/DiscordBotUser'
            - type: 'null'
        application_id:
          anyOf:
            - $ref: '#/components/schemas/DiscordID'
            - type: 'null'
        invite_url:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
        channels:
          $ref: '#/components/schemas/Counter'
        allowed:
          $ref: '#/components/schemas/Counter'
        requests:
          $ref: '#/components/schemas/Counter'
      required:
        [
          id,
          session_id,
          name,
          owner_id,
          enabled,
          revision,
          state,
          detail,
          user,
          application_id,
          invite_url,
          channels,
          allowed,
          requests,
        ]
      additionalProperties: false
      description: A session's Discord bot. The token never leaves the daemon.
    DiscordBotUser:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/DiscordID'
        username:
          type: string
          maxLength: 256
      required: [id, username]
      additionalProperties: false
    DiscordBotPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DiscordBot'
      required: [items]
      additionalProperties: false
    DiscordBotCreate:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/ID'
        name:
          type: string
          minLength: 1
          maxLength: 64
        token:
          type: string
          minLength: 1
          maxLength: 4096
        owner_id:
          type: string
          pattern: ^[0-9]{17,20}$
      required: [session_id, name, token, owner_id]
      additionalProperties: false
    DiscordBotPatch:
      type: object
      properties:
        revision:
          type: integer
          minimum: 1
        name:
          type: string
          minLength: 1
          maxLength: 64
        token:
          type: string
          minLength: 1
          maxLength: 4096
        owner_id:
          type: string
          pattern: ^[0-9]{17,20}$
        enabled:
          type: boolean
      required: [revision]
      additionalProperties: false
    DiscordDeletion:
      type: object
      properties:
        deleted:
          $ref: '#/components/schemas/ID'
      required: [deleted]
      additionalProperties: false
    DiscordUserDeletion:
      type: object
      properties:
        deleted:
          $ref: '#/components/schemas/DiscordID'
      required: [deleted]
      additionalProperties: false
    DiscordDelivery:
      type: string
      enum: ['off', turn, tool]
      description:
        off ignores the channel; turn queues messages until the running turn
        ends; tool steers the running turn after its current tool call.
    DiscordGuildList:
      type: object
      properties:
        guilds:
          type: array
          items:
            $ref: '#/components/schemas/DiscordGuild'
      required: [guilds]
      additionalProperties: false
    DiscordGuild:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/DiscordID'
        name:
          type: string
          maxLength: 256
        channels:
          type: array
          items:
            $ref: '#/components/schemas/DiscordChannel'
      required: [id, name, channels]
      additionalProperties: false
    DiscordChannel:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/DiscordID'
        name:
          type: string
          maxLength: 256
        type:
          type: integer
          description:
            Discord channel type; 0 text, 2 voice, 4 category, 5 announcement,
            15 forum.
        parent_id:
          anyOf:
            - $ref: '#/components/schemas/DiscordID'
            - type: 'null'
        position:
          type: integer
        delivery:
          $ref: '#/components/schemas/DiscordDelivery'
        mentions_only:
          type: boolean
      required: [id, name, type, parent_id, position, delivery, mentions_only]
      additionalProperties: false
    DiscordChannelSetting:
      type: object
      properties:
        delivery:
          $ref: '#/components/schemas/DiscordDelivery'
        mentions_only:
          type: boolean
        guild_id:
          $ref: '#/components/schemas/DiscordID'
        guild_name:
          type: string
          maxLength: 256
        channel_name:
          type: string
          maxLength: 256
      required: [delivery, mentions_only]
      additionalProperties: false
    DiscordChannelState:
      type: object
      properties:
        channel_id:
          $ref: '#/components/schemas/DiscordID'
        delivery:
          $ref: '#/components/schemas/DiscordDelivery'
        mentions_only:
          type: boolean
      required: [channel_id, delivery, mentions_only]
      additionalProperties: false
    DiscordDMs:
      type: object
      properties:
        owner:
          $ref: '#/components/schemas/DiscordOwner'
        allowed:
          type: array
          items:
            $ref: '#/components/schemas/DiscordAllowed'
        requests:
          type: array
          items:
            $ref: '#/components/schemas/DiscordRequest'
          maxItems: 50
      required: [owner, allowed, requests]
      additionalProperties: false
    DiscordOwner:
      type: object
      properties:
        user_id:
          $ref: '#/components/schemas/DiscordID'
        name:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
      required: [user_id, name]
      additionalProperties: false
    DiscordAllowed:
      type: object
      properties:
        user_id:
          $ref: '#/components/schemas/DiscordID'
        name:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
        added_at:
          type: integer
          minimum: 0
          description: Unix milliseconds.
      required: [user_id, name, added_at]
      additionalProperties: false
    DiscordRequest:
      type: object
      properties:
        user_id:
          $ref: '#/components/schemas/DiscordID'
        username:
          type: string
          maxLength: 256
        preview:
          type: string
          maxLength: 200
        last_at:
          type: integer
          minimum: 0
          description: Unix milliseconds.
        count:
          type: integer
          minimum: 1
      required: [user_id, username, preview, last_at, count]
      additionalProperties: false
      description:
        Someone whose DMs were refused because they are not on the allow list.
    DiscordAllow:
      type: object
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
      required: [name]
      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:
            $ref: '#/components/schemas/ProxyModel'
        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
    ProxyModel:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 577
        object:
          const: model
        created:
          $ref: '#/components/schemas/Counter'
        owned_by:
          type: string
          maxLength: 256
        efforts:
          description:
            Nonstandard. Reasoning efforts the model takes; empty when it takes
            none.
          type: array
          items:
            type: string
      required: [id, object, created, owned_by, efforts]
      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_tokens:
          description: >-
            The size.tokens at which the active strategy compacts, as its own
            trigger decides it; null while it has no threshold.
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        input_limit_tokens:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
        size:
          description: >-
            How big the prepared request is, as its strategy measured it; null
            while the strategy has no size for it.
          anyOf:
            - $ref: '#/components/schemas/Size'
            - 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'
      required:
        [
          status,
          strategy,
          trigger_tokens,
          input_limit_tokens,
          size,
          provider_input_tokens,
          provider_cached_input_tokens,
          before_items,
          after_items,
          source,
        ]
      additionalProperties: false
    Size:
      description: >-
        How many tokens something takes, as two parts kept apart: what a
        provider measured, and what was estimated for what no provider number
        covers. tokens is their sum.
      type: object
      properties:
        tokens:
          $ref: '#/components/schemas/Counter'
        measured:
          anyOf:
            - $ref: '#/components/schemas/SizeMeasured'
            - type: 'null'
        estimated:
          anyOf:
            - $ref: '#/components/schemas/SizeEstimated'
            - type: 'null'
      required: [tokens, measured, estimated]
      additionalProperties: false
    SizeMeasured:
      description: >-
        The part of a size a provider gave: counted by its count endpoint for
        this very request, or taken from the usage it reported for earlier
        calls.
      type: object
      properties:
        tokens:
          $ref: '#/components/schemas/Counter'
        source:
          type: string
          enum: [count_endpoint, reported_usage]
      required: [tokens, source]
      additionalProperties: false
    SizeEstimated:
      description: >-
        The part of a size albedo estimated from lengths, with the correction it
        learned from the route's reported usage; null when it had none.
      type: object
      properties:
        tokens:
          $ref: '#/components/schemas/Counter'
        correction:
          anyOf:
            - $ref: '#/components/schemas/SizeCorrection'
            - type: 'null'
      required: [tokens, correction]
      additionalProperties: false
    SizeCorrection:
      description: >-
        Provider tokens per thousand estimated ones on one route and model.
        provisional is the largest ratio seen after reports reports, or the
        prior before any; calibrated is a moving average over the route's
        reports, whose number is then null.
      type: object
      properties:
        state:
          type: string
          enum: [provisional, calibrated]
        per_mille:
          $ref: '#/components/schemas/Counter'
        reports:
          anyOf:
            - $ref: '#/components/schemas/Counter'
            - type: 'null'
      required: [state, per_mille, reports]
      additionalProperties: false
    SessionConfigurationChange:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/SessionConfigurationResource'
        application:
          $ref: '#/components/schemas/ConfigurationApplication'
      required:
        - resource
        - application
      additionalProperties: false
    ConfigurationApplication:
      type: object
      properties:
        desired_revision:
          $ref: '#/components/schemas/ID'
        loaded_revision:
          anyOf:
            - $ref: '#/components/schemas/ID'
            - type: 'null'
        needs_reload:
          type: boolean
      required:
        - desired_revision
        - loaded_revision
        - needs_reload
      additionalProperties: false
    CompactionReceipt:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ID'
        session_id:
          $ref: '#/components/schemas/ID'
        state:
          type: string
          enum:
            - running
            - completed
            - interrupted
        result:
          anyOf:
            - $ref: '#/components/schemas/CompactionResult'
            - type: 'null'
      required:
        - id
        - session_id
        - state
        - result
      additionalProperties: false
