@sema-agent/sdk 4.1.0 → 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
@@ -4776,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
@@ -6779,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:
@@ -6809,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
@@ -7728,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).
@@ -8048,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.1.0",
+  "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",