@sema-agent/sdk 4.0.1 → 4.2.0

package/openapi.yaml

@@ -494,12 +494,20 @@ paths:
                     turn (FIFO), spread across turns. FORWARD-DRAFT: core's steer is harness-level today, not
                     per-call; the per-call mapping is pending D-A core.
       responses:
-        '200': { description: Steer accepted and applied. }
+        '200':
+          description: Steer accepted and APPLIED to the live run on this replica (`delivery:"applied"`).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SteerReceipt' }
         '202':
           description: >-
-            Steer accepted and QUEUED. Two shapes share this code: a live run queues to the next turn-boundary
-            drain; a durable-`suspended` run parks on its pending checkpoint
-            (`{status:"suspended", delivery:"queued"}`) and drains on resume.
+            Steer accepted and PARKED. Two shapes share this code — branch on `delivery`, not the status:
+            a durable-`suspended` run parks on its pending checkpoint (`delivery:"queued"`) and drains on resume;
+            an ALREADY-ENDED run gets a freshly-minted `task_done` checkpoint (`delivery:"parked_for_wake"`) and
+            the message is delivered only by POST /v1/sessions/{sessionId}/wake.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SteerReceipt' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -2070,7 +2078,17 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { $ref: '#/components/responses/NotFound' }
+        '404':
+          description: >
+            Owner-gate / unknown session (no existence oracle), OR — [2400] CB-2, declared 2026-08-02 — the core
+            code `checkpoint.not_found`: the pending checkpoint this decide addressed is gone. It is the ONE
+            member of the mirrored `checkpoint.*` family the server sends as a 404 rather than a 409
+            (`src/http/server.ts:2199`: `e.code === "checkpoint.not_found" ? 404 : 409`), so the SDK maps it to
+            NotFoundError while the rest of the family maps to ConflictError. Client action: refetch the inbox —
+            do not retry this decide.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
           description: >
             Either a session-CAS conflict (`ErrorResponse.activeTaskId`), OR a design/80 D-1
@@ -2078,6 +2096,20 @@ paths:
             NOT match the current pending action (TOCTOU/swap). The SDK splits these by `errorCode` into
             ConflictError vs ApprovalBindingMismatchError. binding_mismatch = SAFETY signal: refetch + re-present
             to the human, NEVER auto-retry.
+            FOURTH member ([2400] CB-2, declared 2026-08-02): `gate_not_tool_approval` — the suspension this
+            sessionId is parked on is NOT a tool-approval gate (`src/http/server.ts:1581` rejects pre-CAS when the
+            gate kind is neither `human` nor `irreversible_ask`: nothing is consumed, no model leg burns). It is
+            the THIRD member of the wrong-door guard family alongside `gate_not_resumable` (§4b) and
+            `gate_not_plan_review` (§4c) → SDK `GateNotToolApprovalError`. Client action: route by the row's
+            `gateKind` — `plan_review` → `POST /v1/assistant/tasks/{taskId}/plan_review`, `resource_limit` →
+            `POST /v1/assistant/tasks/{taskId}/resume`. Retrying the same body never succeeds.
+            FIFTH group ([2400] CB-2): the core `checkpoint.*` family the server mirrors verbatim
+            (`src/http/server.ts:2199-2206`) — `checkpoint.gate_mismatch` / `checkpoint.reopen_failed` /
+            `checkpoint.reopen_revote` / `checkpoint.already_exists` / `checkpoint.resume_aborted` /
+            `checkpoint.unsupported_version` all arrive as 409 and fall on the SDK's `checkpoint.` PREFIX family
+            (→ ConflictError, `.errorCode` carried verbatim; an OPEN set, so a future core code degrades with
+            information instead of collapsing anonymously). The one non-409 member is `checkpoint.not_found`,
+            which the same mint point sends as a 404 (see below).
             THIRD member (moved here from a documented-but-nonexistent 410, 2026-07-31): `approval_stale`
             (`errorCode`; `terminal:"resolved"` when attributable, else the key is absent) — the checkpoint is
             already terminal (someone resolved it / abandonment-TTL GC / SLA resolve-deny). Client action:
@@ -3981,6 +4013,17 @@ components:
         objective:
           type: string
           description: The task. Put per-request context here (keep `systemPrompt` stable/cacheable).
+        taskId:
+          type: string
+          description: >-
+            [2400] TR-16 (declared 2026-08-02) — CALLER-MINTED uuidv7 task id: the DURABLE second tier of
+            idempotency on POST /v1/runs (`src/http/routes/runs.ts:196-217`). The `Idempotency-Key` header's
+            cache is in-memory and PER-POD, so a dispatch gateway that re-routes a retry to ANOTHER instance
+            after a network error would start a SECOND run; THIS replay reads the durable run store, so it
+            survives the re-route and a restart — it is the prerequisite for gateway failover. A hit replays the
+            original 202 receipt (`{taskId, sessionId, status}`); nothing re-runs, nothing re-bills.
+            Shape-gated: a non-uuidv7 value is 400 `request.id_invalid`. Owner-gated: a taskId owned by another
+            principal answers 409 `conflict.run_exists` (no cross-tenant id oracle). Omit ⇒ the server mints one.
         scenario: { $ref: '#/components/schemas/Scenario' }
         sessionId:
           type: string
@@ -4291,6 +4334,9 @@ components:
             [2255]① reject-shape material (server >=3.21, SSE lane): on a `conflict.session_active_run`
             rejection the stream's terminal `done` frame carries the occupying run's taskId. On wire since
             [1833] G10; registered here late. ADDITIVE / tolerate-absent — normal terminal frames omit it.
+            ⚠️ 契约调和车1 E(2026-08-02):that rejection frame is NOT a TaskResult at all — it has its own
+            schema `ActiveRunConflictDoneResult` (no taskId/sessionId/stats). These three keys stay here for
+            the POLLED shapes that may still echo them; the SSE rejection reads them off the union's other arm.
         activeTaskStatus:
           type: string
           description: >
@@ -4773,6 +4819,20 @@ components:
           description: >
             Approve-with-edit (design/37 last-wins): operator's rewritten tool args, applied AFTER the binding
             check. `boundInputHash` STILL binds the ORIGINAL input the human saw — never hash updatedInput.
+        remember:
+          type: string
+          enum: [session]
+          description: >-
+            [2400] HITL-4 (declared 2026-08-02) — the "don't ask again in this session" grant: lands a
+            per-session, per-toolName approval EXEMPTION alongside the decision (server
+            `routes/approvals-assistant.ts` reads it; the SDK has typed it since the facade audit, the spec had
+            not). It is an approval MEMORY, not a policy loosen — a deny / neverAuto always outranks it.
+            Constraints (all server-enforced): only with `decision:"approve"` (else 400
+            `request.field_conflict`); requires the D-1 binding echo in the same body (else 400
+            `remember_requires_binding`); REFUSED on a direct-door worker (400 `remember_not_in_proof` — it is
+            not inside the HMAC payload, so accepting it unsigned would be tamperable); 501 without an exemption
+            store. On the parked-background-agent leg the grant lands on the child's ROOT/HOST session (the whole
+            session tree shares it). The 200 body echoes `rememberApplied` when a store is wired.
 
     ApprovalRow:
       type: object
@@ -4881,6 +4941,16 @@ components:
                 browse: { type: boolean }
                 archive: { type: boolean }
                 maxFileBytes: { type: integer }
+        sessionEvents:
+          type: boolean
+          description: >
+            🔴 契约调和车1 H② (2026-08-02): server HAS been emitting this key (`src/http/routes/capabilities.ts:70`)
+            while both this spec and the SDK type were missing it. Gates `GET /v1/sessions/{sessionId}/events`
+            (the session-level SSE head subscription). Predicate is a THREE-way AND: a durable session-watch seam
+            plus a session store exposing BOTH `getLeafId` and `ownerOf` — the route's 501 uses the same
+            predicate, so "says yes <=> route works" holds here. False/absent => fall back to polling
+            `GET /v1/sessions/{sessionId}/head`. NOTE (server [2373]A-5): no consumer is wired to it yet — it is
+            a prepared slot, correct to gate on, wrong to read as "widely consumed".
         policy: { type: boolean, description: "`GET /v1/policy` (autonomy/permission READ side)." }
         permissionModeWrite: { type: boolean, description: "Runtime permission-mode WRITE. Advertised false by design — autonomy is CONFIG, not steer; the READ side is `policy`." }
         modelSelection: { type: boolean, description: "`model` accepted per request." }
@@ -4906,18 +4976,39 @@ components:
         askUserQuestion: { type: boolean, description: "AskUserQuestion gate is available (durable when approvals are)." }
         toolApproval: { type: boolean, description: "Tool-approval gating is active." }
         promptSuggestions: { type: boolean, description: "Follow-up prompt suggestions are generated." }
-        modelUsage: { type: boolean, description: "`GET /v1/runs/:id/model-usage` (needs a run store + usage plane)." }
+        modelUsage:
+          type: boolean
+          description: >
+            Per-model usage echo is available (server `src/http/routes/capabilities.ts:197`
+            `Boolean(runStore && modelUsage)` — BOTH the durable run store and the tracker that feeds it;
+            absent either, a consumer only gets aggregate cost).
+            🔴 CORRECTED (契约调和车1 H③, 2026-08-02): this bit does NOT gate a read route — the route this
+            description used to name (`GET /v1/runs/:id/model-usage`) DOES NOT EXIST on any server (no route
+            case anywhere in the tree); probing it writes a guaranteed 404. What it really gates: the
+            `model_usage` event arm on the run stream (per-model token/cost DELTAS) and the terminal
+            `TaskStats.modelUsage` (sum across every leg).
         scheduler: { type: boolean, description: "Assistant-scheduler face is mounted." }
         sendUserFile: { type: boolean, description: "Outbound user-file delivery is wired." }
         sendUserFileLedger: { type: boolean, description: "The send-file ledger (audit of deliveries) is available." }
         excludeTools:
           type: array
           items: { type: string }
-          description: Tool names this worker will honour in a request's exclude list.
+          description: >
+            ⚠️ PHANTOM KEY — NEVER emitted by any server version (契约调和车1 H①, 2026-08-02: verified against
+            every casting site in `src/http/routes/capabilities.ts`). It is a **TaskRequest** field (submit-body
+            validation `src/http/server.ts:1358`, TaskSpec mapping `src/boot/resolve-spec.ts:588`) that was
+            mis-registered on the capability face. Reading it always yields absent. Kept (removing it is a
+            breaking change) — SCHEDULED FOR REMOVAL IN THE NEXT MAJOR.
+            Semantics, for the archive: roster TRUE-UNMOUNT — the named tools' schema bytes never reach the
+            model and the assembly manifest narrows honestly; tighten-only, unioned into every child spawn.
         deferTools:
           type: array
           items: { type: string }
-          description: Tool names that can be DEFERRED (surfaced via search rather than mounted up front).
+          description: >
+            ⚠️ PHANTOM KEY — NEVER emitted by any server version; same mis-registration as `excludeTools`, and
+            the real thing is the **TaskRequest** field of this name. SCHEDULED FOR REMOVAL IN THE NEXT MAJOR.
+            Semantics, for the archive: DEFERRED DISCLOSURE — the named MOUNTED tools ride the wire as a
+            placeholder (schema bytes out of the cache prefix) and materialize via ToolSearch on demand.
         s3PublicEndpoint:
           type: ["string", "null"]
           description: >
@@ -5895,7 +5986,20 @@ components:
       properties:
         event: { type: string, description: 'SSE event name (open set; dispatch on this).' }
         id: { type: string, description: 'The durable seq (id: line) when present — feed back as Last-Event-ID to resume. meta/heartbeat carry none.' }
-        data: { type: object, additionalProperties: true, description: 'The frame JSON data: payload (shape varies by event; permissive).' }
+        data:
+          type: object
+          additionalProperties: true
+          description: 'The frame JSON data: payload (shape varies by event; permissive).'
+          properties:
+            type:
+              type: string
+              description: >
+                契约调和车1 G(2026-08-02;server [2373]C-12, `src/trace/project.ts:763` + the meta frame at
+                `routes/trace-usage.ts:258`): the frame's own event name, DOUBLE-EMITTED inside `data`. Always
+                present on server >= 5.0.0; OPTIONAL here because the SDK's supported floor is server 3.0.0
+                (where only the `error` frame carried it). Equal to the SSE `event:` line verbatim — its reason
+                to exist is the proxy/relay case that strips the `event:` line and forwards only the data JSON,
+                where this is the only key left to dispatch on. Heartbeats (`data: {}`) carry none.
 
     PendingList:
       type: object
@@ -6732,6 +6836,13 @@ components:
         - $ref: '#/components/schemas/Event_message_committed'
         # [2373]A-2(2026-08-03,server 5.0.0):compaction_outcome 三腿同源批的 spec 半场(SDK 臂 20867e1 同批)。
         - $ref: '#/components/schemas/Event_compaction_outcome'
+        # [2400] ch2(SDK 4.2.0):CB-1 流控帽帧 + TR-7 durable 五臂 —— 两侧同缺,见各 schema 处的注。
+        - $ref: '#/components/schemas/Event_error'
+        - $ref: '#/components/schemas/Event_question'
+        - $ref: '#/components/schemas/Event_question_complete'
+        - $ref: '#/components/schemas/Event_elicitation'
+        - $ref: '#/components/schemas/Event_elicitation_complete'
+        - $ref: '#/components/schemas/Event_workflow_complete'
       discriminator:
         propertyName: type
         mapping:
@@ -6762,6 +6873,12 @@ components:
           needs_review: '#/components/schemas/Event_needs_review'
           message_committed: '#/components/schemas/Event_message_committed'
           compaction_outcome: '#/components/schemas/Event_compaction_outcome'
+          error: '#/components/schemas/Event_error'
+          question: '#/components/schemas/Event_question'
+          question_complete: '#/components/schemas/Event_question_complete'
+          elicitation: '#/components/schemas/Event_elicitation'
+          elicitation_complete: '#/components/schemas/Event_elicitation_complete'
+          workflow_complete: '#/components/schemas/Event_workflow_complete'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
@@ -7502,12 +7619,69 @@ components:
 
     Event_done:
       type: object
-      description: Carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4.
-      additionalProperties: false   # 封闭:帧本身只有 {type,result};`result` 内部保持开集(见 TaskResult 处的裁定注)
+      description: >
+        The stream's terminal frame. `result` is a DISCRIMINATED UNION of TWO real shapes (契约调和车1 E,
+        2026-08-02) — do NOT assume the full TaskResult:
+         · `TaskResult` — the normal terminal (output string at `.result`, stats at `.stats`), service Drift 4;
+         · `ActiveRunConflictDoneResult` — the SSE lane's REJECTION terminal: when the session already has an
+           active run, the submit's 409 is encoded as this done frame (`src/http/routes/tasks.ts:234`), and it
+           carries NO `taskId` / `sessionId` / `stats`.
+        Narrow on the presence of `stats` (required on TaskResult, absent from the conflict shape), or on
+        `errorCode === "conflict.session_active_run"`. `status` does NOT discriminate — both shapes carry it.
+      additionalProperties: false   # 封闭:帧本身只有 {type,result,replay?};`result` 内部按臂各自裁定(TaskResult 开集,冲突形封闭)
       required: [type, result]
       properties:
         type: { const: done }
-        result: { $ref: '#/components/schemas/TaskResult' }
+        result:
+          oneOf:
+            - $ref: '#/components/schemas/TaskResult'
+            - $ref: '#/components/schemas/ActiveRunConflictDoneResult'
+        replay:
+          type: boolean
+          description: >
+            契约调和车1 F(2026-08-02;server `src/http/routes/tasks.ts:71` 与 `:919` 两处铸造点)— `true`
+            marks the IDEMPOTENT-REPLAY leg: this terminal was NOT produced by a live run of your submit. Either
+            the `Idempotency-Key` hit the in-flight/settled cache (:71), or your call was deduplicated into a
+            concurrent identical submit and received no live events at all (:919). The `result` is the original
+            run's terminal, verbatim. ABSENT on every live leg (never `false`) — a UI can use it to say "replayed"
+            instead of implying the work just ran twice.
+
+    ActiveRunConflictDoneResult:
+      type: object
+      description: >
+        The SSE lane's REJECTION `done.result` (server `src/http/active-run-conflict.ts:64` `toDoneFrameResult`,
+        server >= 3.21). Same material as the 409 `conflict.session_active_run` body, minus the token-free
+        addressing rule's exceptions: a checkpoint token NEVER appears on the wire. It is NOT a TaskResult —
+        there is no run to report on, so `taskId`/`sessionId`/`stats` are structurally absent.
+      # 封闭:铸造点是一个具名 interface(`ActiveRunConflictDoneResult`),逐字挑键 —— 不是透传。
+      additionalProperties: false
+      required: [status, errorCode, errorMessage, activeTaskId]
+      properties:
+        status: { const: failed }
+        errorCode:
+          const: conflict.session_active_run
+          description: '[2373]C-1:与 409 体同一机器码 —— 流腿客户端凭它认拒绝,禁按 byte-frozen 文案匹配。'
+        errorMessage:
+          type: string
+          description: >
+            Human-readable exit route, VARIES by the occupying run's state (running => steer/cancel; parked =>
+            decide at `pendingGate.decidePath` / cancel). Display only — branch on `activeTaskStatus`/`pendingGate`.
+        activeTaskId:
+          type: [string, 'null']
+          description: 'The run occupying the session; `null` when the claim holder could not be identified.'
+        activeTaskStatus:
+          type: string
+          description: '`running` | `suspended` | `needs_review` — best-effort (absent when the store lookup degraded).'
+        pendingGate:
+          type: object
+          required: [kind, decidePath]
+          additionalProperties: false
+          description: >
+            Present when the occupying run is parked on a pending durable gate: `decidePath` is THE ONE correct
+            resume entry for its `kind` (gate-kind routed; sessionId-addressed).
+          properties:
+            kind: { type: string }
+            decidePath: { type: string }
     Event_failed:
       type: object
       # 封闭 + 回填 `activeTaskId`(census 轴一,2026-07-30):[1833] G10 —— session 已有活跃 run 的冲突
@@ -7624,6 +7798,102 @@ components:
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
 
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    # [2400] 说明书审计 ch2(SDK 4.2.0)补的**六个未登记臂**:一个流控帧(CB-1/TR-6)+ 五个 HITL/workflow
+    # 帧(TR-7)。同一个盲区:`spec-union-arm-gate` 比的是 spec ↔ SDK 两侧的臂集,这六个两侧同缺 ⇒ 那道门
+    # 对它们结构性失明;抓到它们靠的是拿 server 的 `res.write("event: …")` / `append("…")` 铸造点第三方对账。
+    # ══════════════════════════════════════════════════════════════════════════════════════════════
+    Event_error:
+      type: object
+      description: >
+        STREAM-CONTROL frame, NOT a run failure (server src/http/sse-log.ts:86; the trace leg emits the same
+        shape at routes/trace-usage.ts:294). The server writes it as a NAMED frame (`event: error`) whose payload
+        echoes `type`, so both an `event:`-dispatching client and a payload-dispatching one see it.
+        🔴 Its arrival means the RUN IS STILL ALIVE — the 15-minute stream cap fired. The correct handling is to
+        RECONNECT with `Last-Event-ID` and keep reading (the durable leg stamps `id:` on every frame); rendering
+        it as a terminal would declare a live task dead. `done` / `failed` are the terminal arms; this one is not.
+        Known `errorCode`: `STREAM_MAX_DURATION` (open set — branch on the code, degrade unknown codes to the
+        generic "reconnectable stream-control signal").
+      additionalProperties: false
+      required: [type, errorCode]
+      properties:
+        type: { const: error }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION (open set).' }
+        message: { type: string }
+    Event_question:
+      type: object
+      description: >
+        AskUserQuestion OPEN frame (server src/question.ts:38 `QuestionFrame`). The live leg dispatches it by SSE
+        event name (routes/tasks.ts:677, the same out-of-band channel as `elicitation`/`tool_approval`); the
+        DURABLE leg persists it via `append(type, rest)` (src/runs.ts:498), so the same frame also replays on
+        GET /v1/runs/:id/events — that half is what this schema registers.
+        🔴 UNTRUSTED-for-display: `questions` is secret-redacted, render only, NEVER re-feed to a model.
+        `questions` absent ⇒ the payload exceeded the 16 KiB cap and was dropped (the ask headless-defaults).
+      additionalProperties: false
+      required: [type, questionId]
+      properties:
+        type: { const: question }
+        questionId: { type: string }
+        questions:
+          type: array
+          items: { $ref: '#/components/schemas/AskQuestion' }
+    Event_question_complete:
+      type: object
+      description: >
+        AskUserQuestion CLOSE frame (dialog-dismiss signal). `answered` = a human responded; `unanswered` =
+        ttl / abort / throttle released it and the model got the headless default. Cosmetic — it does not change
+        the run's status.
+      additionalProperties: false
+      required: [type, questionId]
+      properties:
+        type: { const: question_complete }
+        questionId: { type: string }
+        outcome: { type: string, enum: [answered, unanswered] }
+    Event_elicitation:
+      type: object
+      description: >
+        Inbound-MCP elicitation OPEN frame (server src/elicitation.ts:42 `ElicitationFrame`). Same two legs as
+        `question`: live dispatches by event name, the durable leg persists + replays it.
+        🔴 UNTRUSTED: `message` is fenced + secret-redacted; `requestedSchema` is an OPAQUE passthrough (never
+        interpreted/validated) and must still be fenced on display. v1 is always `mode: "form"` (url-mode is
+        rejected upstream as a phishing surface).
+      additionalProperties: false
+      required: [type, elicitationId, mcpServerName]
+      properties:
+        type: { const: elicitation }
+        elicitationId: { type: string }
+        mcpServerName: { type: string }
+        message: { type: string }
+        requestedSchema: {}
+        mode: { type: string, enum: [form] }
+    Event_elicitation_complete:
+      type: object
+      description: 'Inbound-MCP elicitation CLOSE frame; `action` is how it settled (the dialog-dismiss reason).'
+      additionalProperties: false
+      required: [type, elicitationId, mcpServerName]
+      properties:
+        type: { const: elicitation_complete }
+        elicitationId: { type: string }
+        mcpServerName: { type: string }
+        action: { type: string, enum: [accept, decline, cancel] }
+    Event_workflow_complete:
+      type: object
+      description: >
+        Out-of-band delivery of an async workflow's completion (server
+        src/orchestration/workflow-completion-inbox.ts:522). Delivery is STREAM-OPEN driven: the session's inbox
+        is drained on its NEXT leg — the sync leg writes a live frame, the bg/resume legs `append` it as a durable
+        event the tailing client replays.
+        🔴 AT-LEAST-ONCE (two-phase: the entry is acked only after a successful emit, and two legs racing the same
+        session may double-emit) — consumers MUST dedup on `runId`. `summary` is redacted free text
+        (UNTRUSTED-for-display).
+      additionalProperties: false
+      required: [type, runId, status, summary]
+      properties:
+        type: { const: workflow_complete }
+        runId: { type: string }
+        status: { type: string }
+        summary: { type: string }
+
     # ── resources/*.ts schema backfill, batch 2 (2026-07-28) — the 28-item WIRE_PENDING ratchet zeroed.
     #    Each schema below is cross-checked against the server source (file:line cited in its description
     #    or in the SDK resource JSDoc it mirrors). Wire objects are OPEN sets (additionalProperties: true).
@@ -7944,6 +8214,40 @@ components:
         taskId: { type: string, description: 'Issuing task, when recorded. Additive / tolerate-absent.' }
         sessionId: { type: string, description: 'Issuing session, when recorded. Additive / tolerate-absent.' }
 
+    SteerPriority:
+      type: string
+      enum: [now, next, later]
+      description: >-
+        [2400] TR-4 — per-message queue priority on POST /v1/runs/{taskId}/steer. ACCEPTED + ENUM-VALIDATED
+        FAIL-LOUD (`routes/runs.ts:603`; anything else is 400 `request.field_invalid`) and echoed back on the
+        receipt, but ADVISORY today: core's steer is a single-slot last-writer-wins with no per-message priority
+        or addressable drop, so a faithful priority queue (and DELETE /v1/runs/{taskId}/queue/{messageId}) waits
+        on a core seam.
+
+    SteerReceipt:
+      type: object
+      description: >
+        [2400] TR-4 — the POST /v1/runs/{taskId}/steer receipt, DISCRIMINATED on `delivery` (three server mint
+        points meaning three different things; branch on this, NOT on the status code):
+        `applied` (200, `routes/runs.ts:648`) — injected into the run LIVE on this replica, drains at the next
+        turn boundary (`status:"running"`);
+        `queued` (202, `:641`) — the run is durably SUSPENDED, so the steer was PARKED on its pending checkpoint
+        and is injected on resume (`status:"suspended"`);
+        `parked_for_wake` (202, `:734`) — the run already ENDED; the server minted a `task_done` checkpoint and
+        parked the message on it, delivered ONLY by POST /v1/sessions/{sessionId}/wake — nothing happens until
+        the session is woken.
+        `messageId` is server-minted and stable across all three (dedup / correlation handle).
+      required: [taskId, status, delivery, messageId]
+      # 封闭:三个铸造点是逐字面量拼出来的对象(routes/runs.ts:641/648/734),不是引擎透传形。
+      additionalProperties: false
+      properties:
+        taskId: { type: string }
+        status: { type: string, description: 'The run status the server saw at delivery time (running | suspended | a terminal status).' }
+        delivery: { type: string, enum: [applied, queued, parked_for_wake] }
+        messageId: { type: string, description: 'Server-minted, stable across all three legs.' }
+        priority: { $ref: '#/components/schemas/SteerPriority' }
+        note: { type: string, description: 'Human-readable note on the two parked legs; absent on `applied`.' }
+
     SubagentSteerReceipt:
       type: object
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",