@sema-agent/sdk 1.0.0 → 2.0.0

package/openapi.yaml

@@ -515,7 +515,10 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '400': { $ref: '#/components/responses/BadRequest' }
         '409':
-          description: 'errorCode "steering.not_running" — the run/subagent is settled or unknown (also: ambiguous agentName).'
+          description: >
+            errorCode "steering.not_running" — the run/subagent is settled or unknown; or
+            "steering.ambiguous_target" when more than one live subagent in this run matches the given
+            agentName (address it by parentToolCallId instead — retrying the same target never resolves).
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -701,7 +704,14 @@ paths:
         '413':
           description: 'errorCode "steer.content_too_large" — the revival prompt is over the cap (same gate as subagent steer).'
         '409':
-          description: 'core''s typed rejections verbatim as `errorCode`: resume.still_running / resume.retain_off / resume.evicted / resume.cap / resume.session_not_found (design/122 D2).'
+          description: >
+            core's typed rejections verbatim as `errorCode`: resume.retain_off / resume.evicted / resume.cap /
+            resume.session_not_found (design/122 D2), plus "steering.ambiguous_target" (>1 live subagent matches
+            the target) and "steering.still_running" — the child (or a prior resume) is STILL IN FLIGHT, so
+            revive is not yet legal: steer it instead, or wait for it to settle.
+            🔴 CORRECTION (2026-07-29, read off `src/http/routes/runs.ts` in server 3.x): the in-flight code is
+            `steering.still_running`, NOT `resume.still_running` — this line named a code the server never sends.
+            The `resume.*` family is the retain/evict/cap/session set only.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
@@ -5020,19 +5030,33 @@ components:
         "MIRRORS core CheckpointSummary,顶层 gateKind/severity,NEVER a riskDescriptor object"——
         与真实实现完全相反。真实的 `PendingCheckpoint`(service 自定义类型,不是 core 的
         `CheckpointSummary`)**没有 token 字段**(store 层注释:"deliberately NO token")、**没有
-        顶层 gateKind**、**没有顶层 severity**——risk 信息只在 `riskDescriptor` 对象里(§1 的
+        顶层 severity**——risk 信息只在 `riskDescriptor` 对象里(§1 的
         `CheckpointSummary`/`/v1/assistant/inbox` 才是那个有顶层 severity 标量、无 riskDescriptor
         的姊妹形状,是完全不同的端点,不要混)。按真实实现改写如下,与
         `packages/sdk/src/types.ts` 的 `PendingCheckpoint` interface(已验证与 server 实现一致)
         对齐。
+        🔴 二次纠正(2026-07-29,server 3.0.0 [1995]③):上一版里"**没有顶层 gateKind**"这句话已经
+        过期 —— 3.0.0 additive 加了顶层 `gateKind`,两个 checkpoint store(local 文件店 / SQL 店)的
+        富行投影都发它。"顶层 severity 仍然没有"那半句依旧成立,两件事不要一起读。
       required: [sessionId, scope, createdAt]
       additionalProperties: true
       properties:
         sessionId: { type: string, description: 'The decide handle: POST /v1/approvals/:sessionId/decide.' }
         scope: { type: string, description: 'Principal; "_" = submitted without one.' }
         taskId: { type: ['string', 'null'], description: 'Suspended run holding the session claim (service-pinned) — join key to trace tool-call blocks + context link.' }
-        toolName: { type: ['string', 'null'], description: Tool awaiting approval (AskUserQuestion = the question gate; riskDescriptor 无 gateKind 时的类别推断来源). }
+        toolName: { type: ['string', 'null'], description: 'Tool awaiting approval (AskUserQuestion = the question gate). NULL on every non-tool gate — read `gateKind` for the category, do NOT infer it from this.' }
         toolCallId: { type: ['string', 'null'] }
+        gateKind:
+          type: string
+          description: >
+            Which gate this row is parked on (server >=3.0.0, ADDITIVE — both checkpoint stores project it).
+            Lets a durable-recovery consumer route plan / tool / resource off the SAME queue: a plan gate takes
+            the plan_review decision, a tool gate takes /decide, a resource gate takes resume (going through the
+            wrong door yields `gate_not_resumable` / `gate_not_plan_review`).
+            🔴 OPEN SET — deliberately NOT an enum: observed values include `human`, `irreversible_ask`,
+            `plan_review`, `needs_review`, `resource_limit`, and core keeps adding. Pinning an enum would make a
+            new gate kind "not exist" for generated clients.
+            ABSENT on a pre-`gate_kind` legacy row (SQL column NULL) — degrade honestly, never assume `human`.
         input:
           description: >
             The pending tool call's args (post-hook), REDACTED + size-bounded — for a tool gate the write
@@ -5099,27 +5123,33 @@ components:
 
     InboxRow:
       description: >
-        ASSISTANT-WIRE-CONTRACT §2 — an inbox row = a CheckpointSummary + an `objective` (enriched from the
-        task ctx; `null` if unavailable).
-      allOf:
-        - $ref: '#/components/schemas/CheckpointSummary'
-        - type: object
-          properties:
-            objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
-            toolName:
-              type: ['string', 'null']
-              description: 'The gated tool, when the pause came from a tool call (null for non-tool gates).'
-            toolCallId: { type: string, description: 'The gated tool-call id.' }
-            boundCallId: { type: string, description: 'D-1 decision binding — echo it back on /decide.' }
-            boundInputHash:
-              type: string
-              description: >
-                D-1 decision binding — hash of the bound tool input. Echo on /decide so an approval cannot land on
-                a DIFFERENT call that was swapped in after the operator looked.
-            input:
-              description: >
-                REDACTED tool input for display. Untyped by design (per-tool shape) — and note the raw `toolInput`
-                is deliberately NOT on this row: the handler always strips it (along with `token`) before returning.
+        ASSISTANT-WIRE-CONTRACT §2 — an inbox row (server >=3.4.0 EXPLICIT-projection form): the §1 mirror keys
+        of a CheckpointSummary (token stripped; no rich per-tool fields) + two nullable enrichments.
+        NARROWING RECORD (2026-07-30, board [2027]->[2029]): rows used to also carry
+        toolName/toolCallId/preview/principal/sourceTaskId/contentKind (handler spread the whole projection) and
+        this spec over-declared decide bindings that never appeared on inbox wire at all. Four client repos were
+        structurally zero-consumers, so server 3.4.0 narrowed the wire and this schema follows. For the tool face
+        and decide bindings use /v1/approvals (PendingCheckpoint); for task attribution use /v1/assistant/tasks.
+      type: object
+      required: [sessionId, scope, objective, input]
+      additionalProperties: false
+      properties:
+        sessionId: { type: string, description: 'The suspended task/session id.' }
+        scope: { type: string, description: 'Multi-tenant owner scope.' }
+        createdAt: { type: number, description: 'Ask creation time (epoch ms).' }
+        gateKind:
+          type: string
+          description: 'Same open set as CheckpointSummary.gateKind.'
+          enum: [human, irreversible_ask, resource_limit, needs_review, plan_review, task_done]
+          x-open-enum: true
+        severity: { type: integer, minimum: 1, maximum: 5, description: 'Sort key; only human/irreversible_ask carry it.' }
+        spentMicroUsd: { type: number, description: 'Accumulated spend on the suspend chain (micro-USD).' }
+        deadline: { type: number, description: 'Awaiting-human SLA deadline (epoch ms).' }
+        objective: { type: ['string', 'null'], description: 'task objective, null if unavailable.' }
+        input:
+          description: >
+            REDACTED tool-args preview for display (null on gates without one, e.g. plan_review). Untyped by
+            design (per-tool shape). The raw `toolInput` is deliberately NOT on this row.
 
     InboxList:
       type: object
@@ -5609,6 +5639,18 @@ components:
             `quota_exhausted` (429 — the E4 fleet quota-LEASE budget, distinct from the cost quota).
             NOTE: budget (`budget.precall`/`budget.exceeded`) and `cancelled` are RESULT-level codes on
             TaskResult/RunRecord, NOT HTTP errors (pinned wire contract).
+            🔴 STABLE PREFIX FAMILIES (wire-contract Appendix A, criterion 3) — nine prefixes are a stable
+            COARSE branch surface, so falling back on the prefix (unknown code → look at its prefix → only then
+            at the status) is always safe: `auth.` `request.` `not_found.` `conflict.` `limit.` `capability.`
+            `feature.` `internal.` `state.`. The SDK maps each family to a typed class, so a code this SDK has
+            never seen still degrades INFORMATIVELY (e.g. a future `capability.xyz_required` already lands on
+            CapabilityUnavailableError). Family examples not named elsewhere in this document:
+            `request.payload_too_large` (413 — a field or the whole body is over the server cap; shorten and
+            resend, retrying verbatim never succeeds), `state.model_roster_pending` (503 — retry shortly),
+            `internal.cancel_not_terminalized` (500 — retry the cancel).
+            The two 501 families are deliberately NOT interchangeable: `capability.*` means this deployment did
+            not wire that surface (change the deployment / hide the entry point), `feature.*` means the surface
+            exists but its switch is off (ask an admin to turn it on).
         error: { type: string }
         errorMessage: { type: string }
         activeTaskId:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "1.0.0",
+  "version": "2.0.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",