@sema-agent/sdk 15.2.0 → 15.4.0

package/openapi.yaml

@@ -677,7 +677,8 @@ paths:
         (non-owner → 404, no existence leak; missing principal → 401). All responses are synchronous ACKs; actual
         termination is async (same-replica immediate; cross-replica ≈30s via the heartbeat tick). A cancelled run
         settles to `status` failed + `errorCode` "cancelled" (NO new status — distinguish via errorCode; the UI
-        shows "cancelled", not an error). A SUSPENDED (or `needs_review`) run IS cancellable here — the server
+        shows "cancelled", not an error). From server >= 7.112.0 the cancelled terminal also carries
+        `abortCause: "cancel_verb"` (see `TaskResult.abortCause`; `errorCode` "cancelled" is unchanged). A SUSPENDED (or `needs_review`) run IS cancellable here — the server
         settles its pending checkpoint (CAS `expire`, the reaper's "≈ deny" terminal — deliberately not a
         resume, since cancel means the run dies) and THEN terminalizes the row, releasing the session claim;
         the ack is 202. (Corrected 2026-07-31: this paragraph used to say "409 — cancel it by DENYING its
@@ -1057,7 +1058,8 @@ paths:
       responses:
         '200':
           description: >
-            Queued/applied. Body `{ taskId, target, status, delivery, marker, note }` — `note` carries the
+            Queued/applied. Body `{ taskId, target, status, delivery, marker, note }` (+ `messageId` from server >= 7.111.0,
+            see `SubagentSteerReceipt`) — `note` carries the
             CC-verbatim "Message queued for delivery to <name> at its next tool round." receipt copy.
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -1074,6 +1076,18 @@ paths:
           description: 'errorCode "steer.content_too_large" — content over the per-steer cap; shorten and resend (retrying verbatim never succeeds).'
         '429': { $ref: '#/components/responses/RateLimited' } # (declared 2026-07-31) rateLimited||quotaExceeded||leaseDenied all gate this verb (routes/runs.ts)
         '501': { $ref: '#/components/responses/NotImplemented' }
+        '503':
+          description: >-
+            errorCode "steering.ledger_unavailable" (server >=7.111.0, S-966) — a subagent steer enters the same
+            user-input ledger as a run steer (ONE rule: the ledger covers an input whose receipt promised delivery and
+            whose carrying engine stream lives in a run leg of this server), written BEFORE the 200; the ledger could not
+            be written (local data root not writable / SQL unreachable). The subagent received NOTHING. Client action:
+            retry the SAME content later. SDK: `SteeringLedgerUnavailableError`. The sibling `…/resume` verb never
+            takes this arm (a resume starts a new child leg; it does not feed an in-flight queue). Before 7.111.0 this
+            verb wrote no ledger row and never answered 503 for it.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
 
   /v1/runs/{taskId}/compact:
     parameters:
@@ -7551,7 +7565,8 @@ components:
             `wiring_manifest` frame — test with `'wiringManifest' in result`, never `=== undefined`). The run's
             boot-time wiring receipt: the `wiring_manifest` frame (minted after wiring, before the first turn)
             projected by the SAME projector as the streaming leg (tenant face strips operator-only sections; an
-            explicit operator gets the full face). NOT current state — runtime roster changes ride
+            explicit operator gets the full face; server >=7.111.0 carries the self-minted `instructions` section here
+            too, same present-iff reading as `Event_wiring_manifest.instructions`). NOT current state — runtime roster changes ride
             `tool_roster_delta` frames. Shells judge a zero-tool run by `tools.count === 0`.
         terminal:
           allOf: [{ $ref: '#/components/schemas/TerminalCause' }]
@@ -7641,6 +7656,52 @@ components:
             verdict: { type: string, enum: [PASS, FAIL, PARTIAL, unverified] }
             rounds: { type: integer }
             findings: { type: array, items: { type: string } }
+        abortCause:
+          allOf: [{ $ref: '#/components/schemas/AbortCause' }]
+          description: >
+            server >= 7.112.0 (S-947; cli L-212; contract §5.0d; additive) — the machine-readable CAUSE of a SERVER-INITIATED
+            abort, a side key beside `cancelContext` (it is NOT inside `terminal`: `terminal` is the engine's cause, and one
+            object must not have two minters). PRESENT-IFF this result IS the cancelled terminal the server minted for that
+            abort (`terminal.kind: "failed"` + `terminal.code: "cancelled"`); a server >= 7.112.0 always stamps it on the
+            cancelled terminal it mints (the mint's cause parameter is mandatory; the engine never mints `cancelled` itself).
+            🔴 It sits BESIDE the cancel code and never replaces it: the row's `errorCode` column / `terminal.code`
+            (`"cancelled"`) stays the "this is a cancel" discriminant, unchanged — this key only answers "who made it stop".
+            ABSENT (not a cancelled terminal the server minted for its own abort): a detach disconnect
+            (`x-detach-on-disconnect: true`, the server does not abort); the engine's own failure; a normal completion;
+            `POST /v1/runs/{taskId}/interrupt` (terminal `completed` + `haltedByUser`); a park (including a #241 grace park);
+            a terminal that RACED the abort (the engine finished first / failed with its own code — "fill the empty seat
+            only": code, snapshot and cause are all left off together); a resume leg cancelled BEFORE its approved action
+            started (the engine rules `resume.reopened_unstarted` and the park reopens — the run was not ended); a
+            preempt (`paused`); an orderly shutdown or a dead-holder reap.
+            🔴 A cancelled row persisted by a server before 7.112.0 has NO `abortCause` and is never back-filled: a row with
+            `errorCode: "cancelled"` and the key absent = cause NOT RECORDED — do not fold it into any word.
+            Four landings, one value: `GET /v1/runs/{taskId}` -> `result.abortCause` (beside `result.cancelContext`) ·
+            `POST /v1/tasks/stream` -> `done.result.abortCause` · the `POST /v1/tasks` 200 body, at its TOP LEVEL (the body IS
+            the result, contract §5.0c) · `GET /v1/runs/{taskId}/events` -> the `done` row's `result.abortCause`; a cancelled
+            shape with NO `done` row to land on (a disconnect after which no done was read / the leg aborted before its
+            terminal threw) lands on the `failed` row at its TOP LEVEL instead (`Event_failed.abortCause`, beside `errorCode`).
+            Two wire VALUE changes ride the same release (not new keys): a resume leg cancelled AFTER the approved action
+            started now ends `failed` + `errorCode: "cancelled"` + a `cancelContext` snapshot + `abortCause: "cancel_verb"`
+            (before 7.112.0 it ended `failed` with NO code); an interactive `POST /v1/tasks/stream` that read no `done` and
+            was NOT aborted by the server now ends with the honest failure sentence `stream ended before a terminal event`
+            (no code, no `abortCause`; before 7.112.0 it was always minted as a "client disconnected" cancelled terminal).
+
+    AbortCause:
+      type: string
+      enum: [client_disconnected, ask_park_grace_exhausted, cancel_verb]
+      description: >
+        The closed three-word vocabulary of `abortCause` (server >= 7.112.0 / S-947; contract §5.0d) — who initiated a
+        server-side abort. Each word has one real site: `client_disconnected` — a non-detach `POST /v1/tasks/stream` client
+        disconnect while no in-stream ask was pending, aborted at once ("the connection dropped, the run was aborted" — not an
+        engine error); `ask_park_grace_exhausted` — the same disconnect arm but an in-stream ask WAS pending: the server first
+        turns the ask into a park through the window-expiry path and gives the engine a bounded grace (10 s) to finish
+        parking, and the park still had not landed when the grace ran out, so the run was aborted; `cancel_verb` —
+        `POST /v1/runs/{taskId}/cancel` (the same-replica fast path, a cross-replica durable cancel flag polled by the holding
+        replica on any of the four legs — interactive stream / non-streaming / background / resume —, and a parked run the
+        verb finalizes directly; the cause is the same word). First come, first served: a leg is aborted once, and the first
+        landing names the word — a cancel verb arriving after a disconnect, or a disconnect after a cancel, never rewrites it.
+        CLOSED set, additive-only by the server's rule (a new word is a new server version in `wire-changes` AND a new SDK
+        minor, in this enum in the same batch): read an unknown word as "the server aborted this run, cause not recognised".
 
     LegacyPlaneTaskResult:
       type: object
@@ -12223,7 +12284,9 @@ components:
             the server had answered 200 `applied` (interrupt{text}: 202) but the process carrying that run died
             before the run settled; whether the run consumed them is NOT known (see `engine_notice`
             `task.user_steer_undrained{cause:"crashed"}`). Converged rows only, one row per (taskId, messageId),
-            newest 500. ABSENT = this read has nothing to report (zero rows, or the ledger could not be read —
+            newest 500. From server >=7.111.0 (S-966) the rows include SUBAGENT steers (recorded under the run on the
+            receipt; same row shape, `kind` is still only `steer`; `messageId` = the subagent steer receipt's).
+            ABSENT = this read has nothing to report (zero rows, or the ledger could not be read —
             the authoritative notice is the frame on the run stream); the `?message=` single-entry form never
             carries it.
           items:
@@ -14348,6 +14411,23 @@ components:
             (`capabilities.rewindFiles`); only a run the REQUEST word turned off cannot restore itself.
             OPEN on read: the server does not enumerate the word (a present non-string is dropped), a third word passes
             through — treat it as unknown. ABSENT = an older engine / external derivation, never "capturing".
+        instructions:
+          allOf: [{ $ref: '#/components/schemas/WiringManifestInstructions' }]
+          description: >
+            server >= 7.111.0 (S-961; cli L-910; contract appendix G.21b) — SELF-MINTED by the server (core's
+            `WiringManifest` has no such section; the server adds it beside core's own, and a core section of the
+            same name would be a compile error server-side). TENANT and OPERATOR faces alike; rides the live frame, the
+            durable ledger row and the sync receipt's `wiringManifest`. Which PROJECT-INSTRUCTION FILE the project-memory
+            loader selected on THIS leg's own prepare: the chain `CLAUDE.md` > `.claude/CLAUDE.md` > `AGENTS.md` >
+            `.claude/AGENTS.md` (first hit wins; a present-but-EMPTY `CLAUDE.md` is still the selected one and shadows
+            `AGENTS.md`), each member spelled as the chain spells it, relative to the cwd.
+            🔴 TWO MEANINGS, never fold them: the key ABSENT = this leg makes NO statement about instruction files
+            (no loader wired — `PROJECT_MEMORY_ENABLED=false`, or the multi-user `REQUIRE_PRINCIPAL=true` form —, a
+            hand-less leg, a cwd that is not a local absolute directory, a delegated subagent leg, or a server older
+            than 7.111.0) — it does NOT mean "there is no instruction file". PRESENT with `selected: []` = the leg
+            walked the chain and selected nothing. Today at most one member is sent (first hit wins); read it as a list.
+            The segment reports what the model read at this leg's prepare, not the disk now (a resume leg reports the
+            session snapshot). Not on `GET /v1/diagnostics/wiring` (a per-leg fact; the static half never mints it).
         eventId: { type: string }
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
@@ -16601,6 +16681,8 @@ components:
       type: object
       # 封闭 + 回填 `activeTaskId`(census 轴一,2026-07-30):[1833] G10 —— session 已有活跃 run 的冲突
       # 失败形会带上占用者 taskId(SDK events.ts 早已声明,spec 侧漏)。
+      # server 7.112.0(S-947;sdk 15.4.0 / K-42):+`abortCause`(没有 done 可落的取消形的成因落在本行顶层)。封闭对象不声明它,server 的真 `failed` 行对 15.3.0 spec 就是
+      # 「$ must NOT have additional properties」—— 门 6 契约套抓不到这一件,由 `test/server-7112-wire.test.ts` P2(真 `buildCancelledLedgerRow` × spec)抓。
       additionalProperties: false
       required: [type]
       properties:
@@ -16608,6 +16690,16 @@ components:
         errorCode: { type: string }
         errorMessage: { type: string }
         activeTaskId: { type: string, description: '冲突失败形:当前占着该 session 的 run —— 消费方可直接引导 cancel/attach。' }
+        abortCause:
+          allOf: [{ $ref: '#/components/schemas/AbortCause' }]
+          description: >
+            server >= 7.112.0 (S-947; contract §5.0d) — the cause of a cancelled shape that has NO `done` row to carry
+            `result.abortCause` (a disconnect after which no done was read / the leg was aborted before its terminal threw),
+            landing at this row's TOP LEVEL beside `errorCode` (the cancelled shape's `errorCode` is `"cancelled"`, unchanged).
+            Same closed words and the same present-iff gate as `TaskResult.abortCause`: PRESENT-IFF this row is the cancelled
+            shape the server minted for its own abort. A `failed` row WITHOUT `errorCode` / `abortCause` (only
+            `errorMessage`, e.g. `stream ended before a terminal event`) is an honest failure and is NOT a cancel — never
+            read it as "disconnected". A cancelled row persisted before 7.112.0 has no `abortCause` (cause not recorded).
 
     # ══════════════════════════════════════════════════════════════════════════════════════════════
     # 🔴 census 轴一(2026-07-30)补的**四个未登记臂**。它们不是「将来会有」——**今天就在 wire 上**:
@@ -17470,7 +17562,7 @@ components:
         🔴 ONE RULE FOR EVERY "EFFECTIVE HALF ONLY" KEY (sdk 9.7.0, after a codex adversarial-review [high]):
         this schema's only consumer today is `GET /v1/diagnostics/wiring`'s `static` half, and every key marked
         "effective half only" (`leg`, `ask.effective`, `configFingerprint`, `tools`, `hooks`, `lsp`,
-        `modelGate`, `autoMode`, `writeProtection`, `readDeny`, `autoConsolidation`, `fileHistory`) is ALWAYS ABSENT on that
+        `modelGate`, `autoMode`, `writeProtection`, `readDeny`, `autoConsolidation`, `fileHistory`, `instructions`) is ALWAYS ABSENT on that
         wire ⇒ THEIR ABSENCE HERE CARRIES NO INFORMATION. The per-key absence readings ("absent = not armed",
         "absent = a third state", …) hold for the LIVE FRAME (`Event_wiring_manifest`) and must not be carried
         over to this response. For the facts behind those keys: a tenant reads
@@ -17651,6 +17743,13 @@ components:
             K-24 (server >= 7.104.0 / S-724) — does this leg capture file history (`on` / `disabled`, OPEN word). EFFECTIVE
             HALF ONLY ⇒ ALWAYS ABSENT ON THIS ENDPOINT; the deployment-level reading is `capabilities.fileHistoryCapture`.
             Full per-key contract: see Event_wiring_manifest.fileHistory.
+        instructions:
+          allOf: [{ $ref: '#/components/schemas/WiringManifestInstructions' }]
+          description: >
+            server >= 7.111.0 (S-961) — SELF-MINTED by the server, PER-LEG: the instruction file the loader selected on one leg's
+            own prepare. EFFECTIVE HALF ONLY ⇒ ALWAYS ABSENT ON THIS ENDPOINT (a deployment has no per-leg selection to report).
+            🔴 DO NOT read absence here as "no instruction file" — it carries no information on this wire. Full per-key
+            contract: see Event_wiring_manifest.instructions.
     WiringManifestWriteProtection:
       # sdk 9.7.0:与 `WiringManifestMcpEntry` / `WiringManifestLspSeam` 同一条裁定 —— 同一段形被 live 帧与
       # 静态诊断面两处引用,内联就是两份会各自漂的镜像,所以具名单源。
@@ -17698,6 +17797,23 @@ components:
           enum: [true]
           description: "core's ONLY present shape — the construct gate refuses an armed-but-unrunnable state, so this is a SHAPE, not a value."
 
+    WiringManifestInstructions:
+      # S-961(server 7.111.0):与 `WiringManifestReadDeny` / `WiringManifestAutoConsolidation` 同一条裁定 —— 同一段形被 live 帧与静态诊断面两处引用,
+      # 内联就是两份会各自漂的镜像,所以具名单源(`spec-field-drift-gate` 也按「导出的 interface 必有同名 schema」逼出它)。
+      type: object
+      additionalProperties: false
+      description: >
+        The `wiring_manifest.instructions` section (server >= 7.111.0 / S-961) — SELF-MINTED by the server, not a core
+        section: which project-instruction file the project-memory loader selected on this leg's own prepare.
+        `selected` members are a CLOSED four-word set — the server's instruction-file chain (`INSTRUCTION_FILE_CHAIN`,
+        registered in its self-minted wire table `wiringInstructionsSelected`); a fifth chain member would be a new SDK minor,
+        in this enum in the same batch. The present-iff / two-meanings reading is on `Event_wiring_manifest.instructions`.
+      required: [selected]
+      properties:
+        selected:
+          type: array
+          description: 'The selected chain member(s), spelled as the chain spells them (relative to the cwd); `[]` = the chain was walked, nothing was selected.'
+          items: { type: string, enum: ['CLAUDE.md', '.claude/CLAUDE.md', 'AGENTS.md', '.claude/AGENTS.md'] }
     WiringManifestHookEntry:
       # sdk 9.5.0:与 `WiringManifestMcpEntry` 同一条裁定 —— 同一份行形被 live 帧与静态诊断面两处引用,
       # 内联就是两份会各自漂的镜像,所以一开始就具名。
@@ -18011,6 +18127,14 @@ components:
         delivery: { type: string, description: 'Literal "applied" on today''s server.' }
         note: { type: string, description: 'The CC-verbatim queued copy ("Message queued for delivery to <name>…").' }
         marker: { type: string, description: 'Engine-minted delivery marker (present on both steer and resume 200s, server 1.214+).' }
+        messageId:
+          type: string
+          description: >
+            server >= 7.111.0 (S-966) — the STEER 200 only (absent on the `…/resume` 200 and on an older server): the id of
+            this acceptance in the server's user-input ledger (uuidv7) — the SAME value a later
+            `GET /v1/sessions/{id}` `userInputUndrained[].messageId` carries should the carrying server process die
+            before the run settles. The same ledger write that guards a run steer guards a subagent steer: when it
+            cannot be written the verb answers 503 `steering.ledger_unavailable` and the subagent got nothing.
 
     SubagentOutputResult:
       type: object

package/package.json

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