@sema-agent/sdk 18.1.0 → 19.0.0

package/openapi.yaml

@@ -2416,7 +2416,23 @@ paths:
                 required: [rules]
                 properties:
                   rules: { $ref: '#/components/schemas/StoredSessionRules' }
-        '400': { $ref: '#/components/responses/BadRequest' }
+        '400':
+          description: >-
+            400 — the rules body is refused BEFORE anything is written (not one byte reaches the store). Branch on `errorCode`, never on the sentence.
+            `rules.legacy_tool_name` (server >= 7.105.0; the `rules.*` family, the SDK lands it on `BadRequestError`): a tool-name bucket (`toolAllow` / `toolDeny`) entry
+            that would be written but could never run — an engine-retired name, a `__` name without a protocol prefix, or a protocol name whose peer segment the
+            engine cannot mint. Body keys (top level; the SDK reads them from `err.extra`): `field` (which bucket), `name` (which entry), `verdict`
+            (`retired` / `unprefixed_namespace`, server >= 7.116.0; `unmintable_segment`, server >= 7.118.0), `currentName` (server >= 7.116.0; present when
+            there is a 1:1 successor), `guidance` (server >= 7.119.0; the engine judge's wording of the fix, byte for byte — carried by `retired` and
+            `unmintable_segment`, absent for `unprefixed_namespace`). 🔴 server >= 7.123.0 also lands a protocol name with an EMPTY TOOL SEGMENT
+            (`mcp__<server>__`, `a2a__<peer>__`) here, as `verdict: "unmintable_segment"`; server 7.116.0–7.122.x answered `400 request.field_invalid`
+            for it — a caller that branched on that code for this shape now branches on `rules.legacy_tool_name` (the body's `verdict` tells the shapes apart).
+            `request.field_invalid`: a bucket that is not a list of non-empty strings (a bare string, `null`, a non-string member) and — behavior change
+            in server >= 7.123.0 — an EMPTY or BLANK (whitespace-only) member, which earlier servers took in (200); the sentence is the engine's own,
+            match on the code. Also `request.id_invalid` (malformed session id) and a malformed body.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: 403 `loosen_forbidden` — a non-operator write tried to relax the rules (tighten-only).
@@ -3116,7 +3132,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ImportStaged' }
-        '400': { $ref: '#/components/responses/BadRequest' }
+        '400':
+          description: >-
+            400 — malformed input (the `policy` face is judged by the same write-door reader as `PUT /v1/sessions/{sessionId}/policy`, BEFORE any staging
+            is created, so a refused push leaves nothing behind). Branch on `errorCode`, never on the sentence. `rules.legacy_tool_name` (server >= 7.105.0):
+            a record's tool-name bucket (`toolAllow` / `toolDeny`) holds a name that could never run — an engine-retired name, a `__` name without a protocol prefix,
+            or a protocol name whose peer segment the engine cannot mint. Body keys (top level; the SDK reads them from `err.extra`): `field`, `name`, `verdict`
+            (`retired` / `unprefixed_namespace`, server >= 7.116.0; `unmintable_segment`, server >= 7.118.0), `currentName` (server >= 7.116.0, when there is a 1:1 successor),
+            `guidance` (server >= 7.119.0, the engine judge's wording; absent for `unprefixed_namespace`). 🔴 server >= 7.123.0 also lands a protocol name with an EMPTY TOOL
+            SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) here (`verdict: "unmintable_segment"`); server 7.116.0–7.122.x answered `400 request.field_invalid` for it.
+            `request.field_invalid`: a bucket that is not a list of non-empty strings and — behavior change in server >= 7.123.0 — an EMPTY or BLANK member, which earlier
+            servers took in (the sentence carries the `policy: [i].rules: ` position prefix and then the engine's own sentence; match on the code).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '409':
@@ -3233,10 +3262,11 @@ paths:
       description: >
         Frames: `meta` ({type,version,mode:"approvals-delta",pollMs}), then `synced` ({type,count}) once the
         first full snapshot has been emitted, then `pending`/`resolved` deltas; plus `heartbeat` ({type}) on the
-        keep-alive tick and a terminal `error` ({type,errorCode:"STREAM_MAX_DURATION",…}) when the 15-min cap
-        fires — or, server >= 7.122.0, `error` with `errorCode:"draining"` at the moment the instance enters drain (same code and
-        sentence as the billable-submit 503 `draining`; the server closes the stream right after the frame, reconnect to the
-        replacement instance). (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
+        keep-alive tick and an `error` ({type,errorCode:"STREAM_MAX_DURATION",…}) when the 15-min cap
+        fires (the server closes the stream; the SDK reader reconnects and tails on) — or, server >= 7.122.0, `error` with
+        `errorCode:"draining"` at the moment the instance enters drain (same code and sentence as the billable-submit 503 `draining`;
+        the server closes the stream right after the frame). After `draining` the SDK reader ENDS (shared terminal predicate): re-opening is
+        the caller's call, on its own schedule and backoff, and lands on the replacement instance. (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
         it silently drops three frame kinds it really receives.) Each data payload mirrors its SSE event name in
         `data.type` — proxy-safe dispatch. Cross-replica by
         construction (polls the SHARED checkpoint table). 15-min cap + heartbeats; a DB blip retries, never
@@ -3337,9 +3367,13 @@ paths:
         '409':
           description: >
             Either a session-CAS conflict (`ErrorResponse.activeTaskId`), OR a design/80 D-1
-            `approval_binding_mismatch` (`errorCode`, `field`: boundCallId|boundInputHash|answer — the third
-            member since core 5.7.0/RB-459: the content-ask `answer` payload was refused) — your binding does
-            NOT match the current pending action (TOCTOU/swap). The SDK splits these by `errorCode` into
+            `approval_binding_mismatch` (`errorCode`, `field`: boundCallId|boundInputHash, or absent — e.g. core's row-integrity
+            refusal, whatever engine wrote the parked row) — your binding does NOT match the current pending action (TOCTOU/swap).
+            🔴 server >= 7.124.0 ONE CODE, ONE CAUSE: this code only says "the binding changed". The content-ask `answer` cell (core 5.7.0's
+            third `field` member) now answers `resume_outcome_invalid` with `field: "answer"` (fix the answer and decide again — not
+            "refetch the coordinates"); before 7.124.0 that cell borrowed this code. The SDK reads `field` here as the closed pair of binding
+            seats (an older server's borrowed `answer` reads as absent; the raw value stays in `err.extra.field`). `retriable: true` is unchanged
+            (the card stays pending, the run row re-parks). The SDK splits these by `errorCode` into
             ConflictError vs ApprovalBindingMismatchError (the engine's own code for the same refusal, `checkpoint.invalid_outcome`,
             maps to that class too). binding_mismatch = SAFETY signal: refetch + re-present
             to the human, NEVER auto-retry. A `decidedBy: "policy"` allow on a person-required card is the OTHER `invalid_outcome`
@@ -3419,7 +3453,12 @@ paths:
             `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`,
+            information instead of collapsing anonymously). 🔴 server >= 7.124.0: the `checkpoint.unsupported_version` body carries two
+            additive keys `writerVersion` (the service version that parked the row, as recorded in the resume context) and `readerVersion`
+            (this engine) — the same rule at EVERY mint point of that code (core's mirrored code and the server's two self-minted reading-marker
+            refusals), present iff the resume context records a writer version (rows parked before 7.124.0 carry neither; equal values are still
+            sent). `writerVersion` newer than `readerVersion` ⇒ decide on that version (or a newer one), not by retrying here. SDK type
+            `CheckpointUnsupportedVersionExtra`, values at `err.extra`. 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
@@ -4123,8 +4162,9 @@ paths:
       description: >
         READ-ONLY catalog of `@mention`-pickable models. The user selects a model PER-TASK by typing `@<name>` in
         the objective body (the service allowlist-parses it; the client never re-decides). Envelope
-        `{ models, default, defaultModel }` (`default` = the deployment default model id, display-only — the
-        internal `default` alias is hidden; `defaultModel` = the same default as `{id, name?}` in one piece).
+        `{ models, default, defaultModel, droppedEntries? }` — see `ModelsResponse` (`default` = the deployment default model id,
+        display-only — the internal `default` alias is hidden; `defaultModel` = the same default as `{id, name?}` in one piece;
+        `droppedEntries` = server >= 7.123.0, the catalog entries the read leg dropped, in the same generation as `models`).
         🔴 NON-SECRET: only name/id/provider/reasoning/vision + the E4/E7 capability fields — NEVER baseUrl/apiKey/
         headers (the service strips them). Fail-safe: on error, render an empty picker (never block).
       responses:
@@ -4132,26 +4172,7 @@ paths:
           description: Model catalog (possibly empty).
           content:
             application/json:
-              schema:
-                type: object
-                # 🔴 封闭 + `defaultModel` 补登记(census 批2 第三段,2026-07-30):铸造点
-                # `routes/capabilities.ts` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
-                # 已发多版)SDK `models.list()` 的返回类型早就带,**spec 是唯一没登记的一侧** —— 生成式
-                # 消费方对它全瞎。`name` 条件(目录无命中即省略),`id` 恒在。
-                additionalProperties: false
-                required: [models, default, defaultModel]
-                properties:
-                  models:
-                    type: array
-                    items: { $ref: '#/components/schemas/ModelInfo' }
-                  default: { type: string, description: "deployment default model id (display-only; legacy id-form, byte-stable)" }
-                  defaultModel:
-                    type: object
-                    additionalProperties: false
-                    required: [id]
-                    properties:
-                      id: { type: string }
-                      name: { type: string, description: 'the catalog @handle of the default model; omitted when the catalog has no match (env single-model lane).' }
+              schema: { $ref: '#/components/schemas/ModelsResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
   /v1/elicitations/{id}/respond:
@@ -4322,7 +4343,16 @@ paths:
               schema: { $ref: '#/components/schemas/ToolApprovalRespondAck' }
         '400': { description: Malformed body (existence-independent). }
         '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Unknown/settled/expired/foreign approval (no existence oracle). }
+        '404':
+          description: >
+            Unknown/settled/expired/foreign approval (no existence oracle) — `tool_approval.not_pending`. Past the owner gate the body may carry
+            an additive `cause` (`ToolApprovalNotPendingCause`): a row-ending cause word (the card ended without a human decision — dismiss it)
+            or `unknown_or_other_replica` (this replica does not know the id — retry on another endpoint / replica). 🔴 server >= 7.124.0 retired
+            the old words `voided` / `denied` (replaced by the concrete cause word, no alias); a row with no recorded cause carries no key, and a
+            deployment without a durable ask ledger never sends it. Not-yours is byte-identical to unknown.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ToolApprovalNotPendingBody' }
         '501': { description: Live tool-approval HITL not enabled (TOOL_APPROVAL_ENABLED). }
 
   /v1/tasks/{taskId}/asks/{askId}/decision:
@@ -4391,8 +4421,8 @@ paths:
         '410':
           description: >
             The window is closed and the outcome is already cast: `gone.ask_parked` (gate coordinates in the
-            body — route to the durable gate flow) or `gone.ask` (`{state, deniedReason?}`). The two legs carry
-            DISJOINT bodies.
+            body — route to the durable gate flow) or `gone.ask` (`{state, cause?}`; server >= 7.124.0 renamed the key from `deniedReason`,
+            no alias). The two legs carry DISJOINT bodies.
           content:
             application/json:
               schema: { $ref: '#/components/schemas/AskGoneBody' }
@@ -5638,7 +5668,7 @@ paths:
         apart, hard-stops — so the platform stop timeout (Docker `stop_grace_period`, systemd `TimeoutStopSec`, k8s
         `terminationGracePeriodSeconds`) must be >= the requested deadline.
         IDENTITY — the request names WHICH instance, compared field by field (no state change on a mismatch, 409 `conflict.fleet_identity`
-        naming the field, never echoing the value): `worker` = the engine's worker name (`SEMA_REGISTRY_WORKER`; an engine without a center
+        naming the field, never echoing the value): `worker` = the engine's worker name (`SEMA_WEB_ADMIN_WORKER`, `SEMA_REGISTRY_WORKER` on servers <= 7.123.x; the authenticated `GET /v1/capabilities` `centerWiring.worker` reads the same value; an engine without a center
         lane has none, so every request mismatches); `expectedGeneration` = the fleet generation (`/health.generation`), ABSENT AGAINST ABSENT
         (omitting it is the standalone form, not a wildcard — it mismatches a fleet member); `scope` = the tenant scope, both sides read as a
         value (the engine's = env `FLEET_SCOPE`; unset on the engine and omitted in the request both read as the default scope `global`);
@@ -7469,6 +7499,10 @@ components:
             `MANUAL_MODE_SHELL_GATE=always`, write protection, governance, a hook's ask and plan-mode asks still ask (a matching `request` member then shows as `allowRuleShadowed` on the
             card). The submit gate judges only the shape (array of strings, at most 1000 entries => 400) and the NAMES (the same judge and the same sentence as `deny` / `ask`: a retired name,
             an unprefixed short name, or a protocol name whose server segment cannot be minted / is missing / is a wildcard (`mcp__*`) is a whole-request 422) — never the content.
+            🔴 server >= 7.118.0: the NAME layer of the allow side moved to the engine — a retired name, an unprefixed short name or an unmintable protocol name is ACCEPTED here (no 422) and the run opens with an
+            `engine_notice` `permission.allowed_tool_not_granted` (`entries[].reason: tool_name`); the `deny` / `ask` buckets still refuse that family with a whole-request 422. 🔴 server >= 7.123.0 (core 7.48.0) also accepts a
+            protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) in this bucket (server 7.118.0–7.122.x refused it on every table). One name, three outcomes:
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name` (`verdict: unmintable_segment`).
             🔴 THE 422 SENTENCE (server >= 7.117.0): `error` starts with `request settings cannot be applied as written: ` (<= 7.116.x: a different sentence that said tighten-only — all three
             buckets share this exit, and the old head misled a caller writing a tightening rule and lied about the allow bucket). Do NOT dispatch on the sentence: it carries no code of its own, so
             `errorCode` is the status-derived coarse code `request.unprocessable`.
@@ -8298,7 +8332,16 @@ components:
           enum: ['open', closed]
           description: 'PRESENT-IFF `lease: configured`. The effective `FLEET_LEASE_FAIL_CLOSED` (default derived from `REQUIRE_PRINCIPAL`); `closed` ⇒ connection-level failures answer 503 `fleet.lease_unavailable` on every billing entry.'
         usageReport: { type: boolean, description: 'The usage-report loop is mounted (the three center pieces suffice; `FLEET_ADVERTISE_ADDRESS` not required, S-866 ④).' }
-        issuer: { type: string, enum: [explicit, fallback], description: 'Auth-bridge issuer: explicit `AUTH_BRIDGE_ISSUER` / fallback to `SEMA_REGISTRY_URL`.' }
+        issuer: { type: string, enum: [explicit, fallback], description: 'Auth-bridge issuer: explicit `AUTH_BRIDGE_ISSUER` / fallback to the center base URL (`SEMA_WEB_ADMIN_URL`; `SEMA_REGISTRY_URL` on servers <= 7.123.x).' }
+        worker:
+          type: string
+          minLength: 1
+          description: >
+            server >= 7.124.0 — the worker name this engine registers with the center (`SEMA_WEB_ADMIN_WORKER`, the same value the drain identity
+            reads), verbatim. PRESENT-IFF a name is configured AND it is disclosable (the contract's identifier rule `isDisclosableIdentity`: not in
+            identifier form / secret-shaped ⇒ treated as no name, key ABSENT, never masked). It lives only on this AUTHENTICATED face — the
+            unauthenticated `/health` deliberately does not carry it. A shell uses it to build the web session link
+            `<webBaseUrl>/chat?agent=<worker>&session=<id>` (paired with `/health.center.webBaseUrl`).
         caller:
           type: object
           additionalProperties: false
@@ -8425,6 +8468,8 @@ components:
             (log `one_time_migrations_applied` `holderDeathCodeRowsBackfilled`) and a new replica reads such a row as the code during the upgrade window,
             but the migration has a window (30 days after the release, then the write-back and the read half are deleted) — so
             "no `errorCode`" never proves "not a holder death": rows migrated late or after the window stay sentence-only.
+            The three run-death codes as ONE runtime table: schema `RunDeathVerdictCode` (closed enum) = the SDK entry export
+            `RUN_DEATH_VERDICT_CODES` — judge "this run was reaped / reclaimed" by that table; this column itself stays an open string.
         error: { type: string }
         jobId:
           type: string
@@ -9601,6 +9646,9 @@ components:
             `engine_notice` `permission.allowed_tool_not_granted`; any layer's deny / ask rule, operator `APPROVAL_REQUIRE` / `APPROVAL_NEVER_AUTO` / shell floor / write protection /
             governance, a hook's ask and plan-mode asks still ask (a matching member then shows as `allowRuleShadowed` on the card). The submit gate judges only the shape and the NAMES (retired
             name / unprefixed short name / unmintable protocol server segment => 422, at most 1000 entries => 400) — never the content.
+            🔴 server >= 7.118.0: the allow side's NAME layer moved to the engine (retired / short / unmintable names are accepted there and announced with `engine_notice` `permission.allowed_tool_not_granted`; `deny` / `ask` still 422);
+            server >= 7.123.0 also accepts a protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`) on the allow side (server 7.118.0–7.122.x refused it on every table):
+            allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name`.
             🔴 ABSENT `allowLayer` with `allowGrant` present = a 7.115.0–7.116.x server: allow is a STATEMENT (it does not clear the engine's own write gate / shell checks; a content form
             is a whole-request 422). ABSENT KEY altogether (no `settings`) = an older server (<= 7.114.x), which read `allow` as a WHITELIST (everything off the list refused) — do not put
             anything in the allow bucket there. NOT the same bit as `taskSettings.permissions` (unchanged, still a boolean: "this server accepts the `settings.permissions` face"). The
@@ -9715,7 +9763,7 @@ components:
             K-32 (server >= 7.106.0 / S-866 ②; mint = release bytes `dist/http/routes/capabilities.js`
             `centerWiring: deps.centerWiring?.(principal)`, shape owner `dist/capabilities/center-wiring.d.ts` `CenterWiring`) —
             "IS THIS ENGINE WIRED TO THE CENTER RIGHT NOW, AND IS YOUR QUOTA ENFORCED". 🔴 PRESENT-IFF wired to a center
-            (`SEMA_REGISTRY_URL`) — like `sealedKey`, a registered present-iff exception (contract appendix B.1): absence is the
+            (`SEMA_WEB_ADMIN_URL`; `SEMA_REGISTRY_URL` on servers <= 7.123.x) — like `sealedKey`, a registered present-iff exception (contract appendix B.1): absence is the
             KEY BEING ABSENT (never `null`) and has two meanings — an older server (< 7.106.0) or an engine not wired to a center
             (the same body's `version` tells them apart); under both read "this face cannot answer wiring / enforcement", NEVER
             "quota is enforced". 🔴 PER CALLER (`caller` is the verified principal's lease reading): do not cache it across
@@ -9779,10 +9827,11 @@ components:
             does not know auto" and "it knows auto but this box has no entitlement source" would collapse to
             the same false, and a shell must do different things for those. `reason` is present ONLY when
             `armed` is false; read its vocabulary as an OPEN set (server already grew it from four words to
-            six). `model` is omitted when the classifier route cannot be resolved (the server logs the
+            six, and to seven with `operator_floor` in server >= 7.123.0). `model` is omitted when the classifier route cannot be resolved (the server logs the
             engine's refusal rather than 500-ing the read face). `?permissionMode=<mode word>` folds the
             caller's INTENT into the verdict (server >= 7.119.0 takes the six words of `capabilities.permissionModes` — `dontAsk` answers
-            `armed: false` / `reason: mode_not_auto`; server <= 7.118.x takes five); anything outside the server's words is a 400
+            `armed: false` / `reason: mode_not_auto`, except on a deployment whose operator entry floor rewrites the word — `AUTONOMY=plan`, where
+            server >= 7.123.0 answers `operator_floor`, see `reason`; server <= 7.118.x takes five); anything outside the server's words is a 400
             `request.field_invalid`.
           # 🔴 required 只有**三位**:武装两键(armed / reason)是 server >= 7.57.0 (S-80)
           # 才有的,而本包的支持地板是 3.0.0 => every 7.x <= 7.56.0 server is inside the promised face and
@@ -9803,7 +9852,17 @@ components:
                 fold that absence into false (it would render a 7.50 box that IS arming as "auto == default").
             reason:
               type: string
-              enum: [mode_not_auto, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+              enum: [mode_not_auto, operator_floor, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+              description: >
+                Why `armed` is false — the server's closed SEVEN words, in judgement order (read as an open set; keep a default arm).
+                `mode_not_auto` = this request's intent (the `?permissionMode=` query word) is not `auto` and that word reaches the engine as it is.
+                `operator_floor` (server >= 7.123.0) = this deployment's operator entry floor (`AUTONOMY=plan`) rewrote the intent into another word, and that
+                word is not `auto`: the word that reaches the engine is the operator's, so the way out is the operator changing the level, NOT the word the
+                request sends. On an `AUTONOMY=plan` deployment an absent intent (answered as the `auto` intent), `auto` and any word looser than `plan` read
+                `operator_floor`; an intent that IS `plan` stays `mode_not_auto` (the word arrives as sent, not rewritten by the floor).
+                Server <= 7.122.x answers `mode_not_auto` for both cases. The rest: `deployment_incapable` = no classifier seat mounted;
+                `org_denied` = this principal's caps say auto is off and no local deny is set (the center's explicit deny, or its fail-closed refusal); `local_denied` = the local `PERMISSIONS_DISABLE_AUTO_MODE`;
+                `settings_denied` = the settings layer folds auto (run-level, not produced by this read face); `resolver_fault` = the resolver threw.
             model: { type: string }
         readFace:
           type: ["string", "null"]
@@ -10228,6 +10287,9 @@ components:
             segment cannot be minted / is missing / is a wildcard (`mcp__*`) is a 400 too, and from 7.117.0 so is a retired name / unprefixed short
             name (the name layer is judged by the same judge as the allow bucket) and a list of more than 1000 entries (top-level `skills[]` and
             `agents[].skills[]` judge identically). Probe `capabilities.skillToolLists`.
+            🔴 The name-layer 400s above hold for server 7.116.x–7.117.x only. server >= 7.118.0: the allow side's name layer moved to the engine — a retired name / unprefixed short name / unmintable protocol name is ACCEPTED here and the run opens with an
+            `engine_notice` `permission.allowed_tool_not_granted` (`entries[].reason: tool_name`); server >= 7.123.0 also accepts a protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) here (server 7.118.0–7.122.x refused it).
+            One name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name` (`disallowedTools` below is a deny side).
         disallowedTools:
           type: array
           items: { type: string }
@@ -10242,6 +10304,8 @@ components:
             user audience, on the session stream). 🔴 The resume legs judge the stored body the same way: a parked task whose stored skill `disallowedTools` carries such an entry answers
             409 `resume_blocked_by_policy` (`blockedBy: "request.field_invalid"`, same sentence) BEFORE the claim — row and card untouched; a terminal run's `POST /v1/runs/{taskId}/steer`
             answers it before minting the wake card. Why: engine 7.41 trimmed whitespace (`"Bash "` was a working deny), engine 7.42 reads verbatim (reads as nothing). The allow side does not refuse.
+            🔴 A protocol name with an EMPTY TOOL SEGMENT (`mcp__<server>__`, `a2a__<peer>__`) is refused here (server >= 7.123.0: `error` is the engine's entry-reading sentence, `... reads as nothing (tool_name) ...`), while `allowedTools` accepts it from 7.123.0 —
+            one name, three outcomes: allow side accepts + notice, deny / ask side refuses, session-rule write doors answer `400 rules.legacy_tool_name`.
 
     McpServerSpec:
       type: object
@@ -10975,6 +11039,92 @@ components:
             `"other"`). This is the "where did those 180 404s actually land" cell. Empty object = zero failures;
             key absent = an older server.
 
+    ModelsResponse:
+      type: object
+      description: >
+        The `GET /v1/models` 200 body (the envelope; service `src/http/routes/capabilities.ts` mints the keys as literals).
+        `models` = the `@mention`-pickable catalog (`ModelInfo`); `default` = the deployment default model id (display-only, legacy id
+        form, byte-stable); `defaultModel` = the same default as `{id, name?}`; `droppedEntries` = server >= 7.123.0, ALWAYS present
+        there: the catalog entries THIS generation's read leg dropped one by one (an entry that does not pass the settings-schema
+        `ModelEntry` shape; the rest of the catalog is served as usual). ABSENT = an earlier server (<= 7.122.x) — so the key is
+        optional here (the SDK's supported server floor is 3.0.0); `[]` = the engine says nothing was dropped (also the env lane,
+        where no catalog is read), which is NOT the same as absent (the engine cannot say).
+      # 🔴 封闭 + `defaultModel` 补登记(census 批2 第三段,2026-07-30):铸造点
+      # `routes/capabilities.ts` 三键字面量。`defaultModel`([865]③ id/name 撕裂消解,server
+      # 已发多版)SDK `models.list()` 的返回类型早就带,**spec 是唯一没登记的一侧** —— 生成式
+      # 消费方对它全瞎。`name` 条件(目录无命中即省略),`id` 恒在。
+      # 18.2.0:信封升为具名 schema(此前内联在 `GET /v1/models` 的 200 上),新键 `droppedEntries`(server >= 7.123.0)挂在上面,**不进 required**。
+      additionalProperties: false
+      required: [models, default, defaultModel]
+      properties:
+        models:
+          type: array
+          items: { $ref: '#/components/schemas/ModelInfo' }
+        default: { type: string, description: "deployment default model id (display-only; legacy id-form, byte-stable)" }
+        defaultModel:
+          type: object
+          additionalProperties: false
+          required: [id]
+          properties:
+            id: { type: string }
+            name: { type: string, description: 'the catalog @handle of the default model; omitted when the catalog has no match (env single-model lane).' }
+        droppedEntries:
+          type: array
+          items: { $ref: '#/components/schemas/DroppedEntry' }
+          description: >
+            server >= 7.123.0 (settings-schema >= 10.1.0), always present there; ABSENT = an earlier server. The catalog entries the read leg
+            dropped from THIS generation (an entry that does not pass the `ModelEntry` shape) so a shell / admin panel can tell "which entry
+            I wrote did the engine not take, and why" without re-judging the schema. Rows carry an index, a closed reason word and (when
+            disclosable) a name / id — NEVER free text (the schema diagnostics, the entry value and any Record key stay in the server log).
+            🔴 SAME GENERATION as `models`: both are the two faces of one catalog generation and commit together. When a center candidate's
+            model plane is refused as a group (for example the default model is not in the catalog), or the candidate has no enabled entry at all
+            (survivors and dropped rows both count by the `enabled` each row wrote; a dropped row whose `enabled` cannot be read counts as enabled),
+            `models` and `droppedEntries` both stay on the previous generation — the key does NOT report the entries of the candidate that did not
+            land (why it did not land: `/health.modelRefusals`). So a disabled dropped entry shows up only in a catalog that has an enabled entry and whose model
+            plane landed. Different question from `/health.modelRefusals` (which names the models this box does NOT serve, with the engine's refusal code):
+            this key lists what the read leg dropped, including nameless and disabled rows.
+            Upgrade window (as it is): an on-disk LKG written by server <= 7.122.x only recorded the dropped entries that had a name AND were
+            enabled; while serving from it with the center still unreachable this key lists only those rows (possibly `[]`) and the first pull after the
+            center is reachable fills it in. An unknown `reasonCode` word reads as "dropped, reason unknown".
+
+    DroppedEntry:
+      type: object
+      description: >
+        One row of `ModelsResponse.droppedEntries` (server >= 7.123.0): a catalog entry the read leg dropped. `index` = the entry's original
+        position in the `models` array of the catalog document read this time (the local lane = its place in `config.d/models.json`; the
+        center lane = the catalog the center sent this worker) — the same coordinate as the server's `models.<index>` log line.
+        `identity` is optional: absent when none of the three keys is disclosable.
+      additionalProperties: false
+      required: [index, reasonCode]
+      properties:
+        index: { type: integer, minimum: 0 }
+        reasonCode: { $ref: '#/components/schemas/DroppedEntryReasonCode' }
+        identity: { $ref: '#/components/schemas/DroppedEntryIdentity' }
+
+    DroppedEntryReasonCode:
+      type: string
+      enum: [entry-schema-invalid, entry-key-invalid, entry-unreadable]
+      description: >
+        Why the read leg dropped a catalog entry (server >= 7.123.0). The words are settings-schema's closed `DROPPED_ENTRY_REASON_CODES`, passed through
+        verbatim (the server neither hand-copies nor rewrites them; a new word in the package is a compile error there, forcing an explicit decision).
+        `entry-schema-invalid` = the entry did not pass its own schema; `entry-key-invalid` = a Record-shaped collection's key did not pass the key schema
+        (the catalog is an array, so this word does not appear on `droppedEntries` today — keep it in the switch anyway); `entry-unreadable` = the judging
+        threw (a pathological accessor; the engine never carries what it threw). Read an unknown word as "dropped, reason unknown".
+
+    DroppedEntryIdentity:
+      type: object
+      description: >
+        The disclosable identity of a dropped entry (settings-schema's entry-identity shape). `name` / `id` appear only when they are DISCLOSABLE identifiers
+        (allow-listed characters, no secret shape, no URL userinfo — the server asks again at the exit); a non-disclosable one is simply absent, NOT masked (a masked
+        string is no longer an identity). `enabled` is the boolean the entry wrote itself (a disabled dropped entry is listed with `enabled: false`). With none of the
+        three keys the whole `identity` is absent — an empty object never reaches the wire, hence minProperties: 1.
+      additionalProperties: false
+      minProperties: 1
+      properties:
+        name: { type: string }
+        id: { type: string }
+        enabled: { type: boolean }
+
     ModelInfo:
       type: object
       description: >
@@ -16483,6 +16633,13 @@ components:
           type: string
           enum: [allowed, denied, expired]
           description: '"tool_approval_complete" only. Cosmetic dismiss reason. `expired` = TTL/abort/disconnect; what the ENGINE received for it DEPENDS on the deployment: where the design/172 ask ledger is on (server >= 7.3.0 under STREAM_APPROVAL_ENABLED) the server''s expireAsk CAS re-adjudicates the outcome to "unavailable" and the run PARKS; without that ledger the historical fail-closed DENY stands. Never derive the run''s fate from this frame.'
+        cause:
+          allOf: [{ $ref: '#/components/schemas/ApprovalSettleCause' }]
+          description: >
+            server >= 7.124.0, "tool_approval_complete" ONLY, ADDITIVE: the CAUSE of `outcome: "expired"` — one of the fourteen non-human ending
+            words (`ApprovalSettleCause`), the same word the audit settle row carries. Present ⇔ a non-human ending; a human answer
+            (`allowed` / `denied`) has none. The only HTTP face that shows the four waiting words. ABSENT is not evidence (older servers never send it);
+            the run's fate is still read from the run row / checkpoint face.
 
     # ── design/172 流内审批协议(#151)—— 已随 server 7.3.0 上线;开关 STREAM_APPROVAL_ENABLED 的默认值
     #    分两段:server ≤7.4.0 默认 OFF,≥7.5.0 默认 ON(BREAKING,见 server CHANGELOG)。──
@@ -17322,6 +17479,49 @@ components:
         first-decision echo now carries `decisionNote` when the row has one.
         Retrying the same decision can never succeed — single-winner CAS means the outcome is already cast.
 
+    RunDeathVerdictCode:
+      type: string
+      enum: [run.stalled, run.orphaned, approval.expired]
+      description: >
+        server >= 7.116.0 — the run-death verdict codes on `RunRecord.errorCode` (contract appendix A.1 (6)): `run.stalled` (heartbeat-lost reap),
+        `run.orphaned` (local-lane restart reclaim) and `approval.expired` (a run parked on an approval was reaped). None means the request was
+        wrong; the run cannot be picked up again — submit the work as a new task. The server's own `isHolderDeathVerdict` counts only the first two
+        (the holding process died before the leg finished). Branch on the code, never on the `error` sentence; absence proves nothing. SDK runtime
+        table: `RUN_DEATH_VERDICT_CODES` (same order).
+    AskRowEndingCause:
+      type: string
+      enum: [routing_failure_fail_closed, run_cancelled, run_exited, batch_aborted, batch_sibling_withdrawn, batch_bound_elsewhere, adhoc_leg_no_durable_domain, orphan_ttl_exceeded, crashed_before_park, shutdown_before_park]
+      description: >
+        server >= 7.124.0 — the ask-row subset of the approval ENDING-CAUSE table (one closed table of seventeen words; a card that ended
+        without a human decision says WHY with one word, and every read face reads the same word). These ten are the ones that land on the
+        ask row: `410 gone.ask` `cause` (grouped by `state`: `DENIED` ⇒ `routing_failure_fail_closed` only, `VOID` ⇒ the other nine) and the
+        late-answer `404 tool_approval.not_pending` `cause` (plus its own `unknown_or_other_replica`). Present ⇔ a non-human ending; a human
+        answer has no cause. The server mints from this table and filters reads through it — closed.
+    ApprovalSettleCause:
+      type: string
+      enum: [ttl_expired, broadcast_lost, stream_disconnected, undeliverable, run_cancelled, run_exited, batch_aborted, batch_sibling_withdrawn, batch_bound_elsewhere, routing_failure_fail_closed, crashed_before_park, shutdown_before_park, orphan_ttl_exceeded, adhoc_leg_no_durable_domain]
+      description: >
+        server >= 7.124.0 — the NON-HUMAN ending causes (fourteen words) carried by the live close frame `tool_approval_complete` `cause` (and the
+        audit ledger's settle rows): the ten ask-row words (`AskRowEndingCause`) plus four waiting words that never land on the ask row —
+        `ttl_expired` (the wait window ran out), `broadcast_lost` (neither frame family reached any connection), `stream_disconnected` (the
+        carrying stream dropped; forced park), `undeliverable` (persisted row unusable / identity indeterminate / hanging without a row). The three
+        decision words (`binding_changed` / `answer_invalid` / `outcome_cell_invalid`) refuse one decision, never end a card, and are not here.
+    ToolApprovalNotPendingCause:
+      type: string
+      enum: [routing_failure_fail_closed, run_cancelled, run_exited, batch_aborted, batch_sibling_withdrawn, batch_bound_elsewhere, adhoc_leg_no_durable_domain, orphan_ttl_exceeded, crashed_before_park, shutdown_before_park, unknown_or_other_replica]
+      description: >
+        The late-answer `404 tool_approval.not_pending` `cause`: the ask-row ending-cause words (the card ended without a human decision — dismiss
+        it) plus the 404-only `unknown_or_other_replica` (this replica does not know the id — retry on another endpoint / replica). server >= 7.124.0
+        retired the old words `voided` / `denied` (no alias).
+    ToolApprovalNotPendingBody:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            cause:
+              allOf: [{ $ref: '#/components/schemas/ToolApprovalNotPendingCause' }]
+              description: 'Optional, past the owner gate only. See `ToolApprovalNotPendingCause`.'
+      description: '404 body of `POST /v1/tool-approvals/{id}/respond` (`tool_approval.not_pending`).'
     AskGoneBody:
       allOf:
         - $ref: '#/components/schemas/ErrorResponse'
@@ -17330,25 +17530,21 @@ components:
             sessionId: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 1; drive the existing durable-gate flow with it.' }
             gateBoundCallId: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 2.' }
             gateBoundInputHash: { type: string, description: 'gone.ask_parked ONLY — gate reconciliation coordinate 3.' }
-            state: { type: string, enum: [DENIED, VOID], description: 'gone.ask ONLY — the terminal state. server >= 7.116.0 also mints `VOID` for "the process that held the ask is gone" (local lane restart; see `deniedReason`).' }
-            deniedReason:
-              type: string
+            state: { type: string, enum: [DENIED, VOID], description: 'gone.ask ONLY — the terminal state. server >= 7.116.0 also mints `VOID` for "the process that held the ask is gone" (local lane restart; see `cause`).' }
+            cause:
+              allOf: [{ $ref: '#/components/schemas/AskRowEndingCause' }]
               description: >
-                gone.ask ONLY — attribution, GROUPED BY `state`. `DENIED` carries the single-member deny
-                vocabulary `routing_failure_fail_closed`; `VOID` carries the separate (and growing) void
-                vocabulary, seven words today: `run_cancelled`, `batch_aborted`, `batch_bound_elsewhere`,
-                `adhoc_leg_no_durable_domain`, `orphan_ttl_exceeded` and — new in server 7.116.0 (local lane) —
-                `crashed_before_park` (the process that held the ask crashed / was killed) and `shutdown_before_park`
-                (an orderly shutdown could not settle the card inside its grace window; a fault shape, hard to build black-box).
-                The last two are the SAME word as `GET /v1/approvals` `crashConverged[].cause`; the other six were already on the wire
-                (7.3.0 / 7.55.0 / 7.108.0) and are only registered in the server's self-minted word table by 7.116.0.
-                ABSENT = the row carries no attribution. The two vocabularies never mix; the VOID one is open (read an unknown word as "the ask ended without
-                a human decision, reason unknown").
+                gone.ask ONLY — the row's ENDING CAUSE (server >= 7.124.0; the key was `deniedReason` before — renamed, no alias, the SDK reads only
+                `cause`, as `AskGoneError.endingCause`). GROUPED BY `state`: `DENIED` carries only `routing_failure_fail_closed`; `VOID` carries the
+                other nine words of the ask-row subset of the approval ending-cause table — `run_cancelled`, `run_exited`, `batch_aborted`,
+                `batch_sibling_withdrawn`, `batch_bound_elsewhere`, `adhoc_leg_no_durable_domain`, `orphan_ttl_exceeded`, `crashed_before_park` /
+                `shutdown_before_park` (the process that held the ask is gone; the SAME word as `GET /v1/approvals` `crashConverged[].cause`).
+                Present ⇔ a non-human ending; ABSENT = the row carries no recorded cause (rows written before the upgrade are not back-filled).
       description: >
         410 body. THE TWO LEGS ARE DISJOINT: `gone.ask_parked` carries exactly the three gate coordinates,
-        `gone.ask` carries exactly `{state, deniedReason?}` (no `consumerState`).
+        `gone.ask` carries exactly `{state, cause?}` (no `consumerState`; server >= 7.124.0 renamed `deniedReason` → `cause`, no alias).
         🔴 server >= 7.116.0 (local lane, `DB_BACKEND=local`): after a crash / kill and a restart on the same data root, answering the PREVIOUS
-        life's still-open card is now `410 gone.ask` with `state: "VOID"` and `deniedReason` `crashed_before_park` / `shutdown_before_park` —
+        life's still-open card is now `410 gone.ask` with `state: "VOID"` and `cause` (`deniedReason` before 7.124.0) `crashed_before_park` / `shutdown_before_park` —
         <= 7.115.x answered `200` + `consumerState: "absent"` (the run had long been reclaimed; nothing executed). An ask that was already decided
         (decided, then the process died mid-execution) is unchanged: `409 conflict.ask_decided`. SQL backends are unchanged in 7.116.0. Routing off field presence across the legs is how a
         consumer ends up driving the wrong durable gate.
@@ -17945,19 +18141,20 @@ components:
         STREAM-CONTROL frame, NOT a run failure (server src/http/sse-log.ts; the trace leg emits the same
         shape at routes/trace-usage.ts). 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` (the 15-minute cap) · `draining` (server >= 7.122.0: the instance entered drain / is being
-        replaced — each of the eight read-only subscription streams gets this frame at the moment drain begins and is then closed by the server;
-        same code and sentence as the billable-submit 503 `draining`, same reconnect protocol: reconnect with `Last-Event-ID`, the replacement
-        instance serves it; NOT a run failure; the same reason family as the cap — the server closes a stream for flow control)
-        (open set — branch on the code, degrade unknown codes to the generic "reconnectable stream-control signal").
+        🔴 NOT a run failure (neither known code) — rendering it as a run terminal would declare a live task dead (`done` / `failed` are the
+        run's terminal arms). How a reader handles it is ONE terminal predicate (SDK `isTerminalFrame`, shared by every resumable reader):
+        `STREAM_MAX_DURATION` (the 15-minute cap fired; the run is still alive) does NOT end the reader — it reconnects with `Last-Event-ID`
+        and keeps reading (the durable leg stamps `id:` on every frame). `draining` (server >= 7.122.0: the instance entered drain / is being
+        replaced — each of the eight read-only subscription streams gets this frame at the moment drain begins and at the hard-stop start, and is
+        then closed by the server; same code and sentence as the billable-submit 503 `draining`) ENDS the reader's leg: the frame is delivered,
+        then the reader stops without reconnecting — re-opening (with the last `id:`) is the caller's call, on its own schedule and backoff, and
+        lands on the replacement instance; it is a connection signal that says nothing about the run's state. Any other code ENDS the leg too
+        (open set — branch on the code, read an unknown code as "this leg ended, reason unknown").
       additionalProperties: false
       required: [type, errorCode]
       properties:
         type: { const: error }
-        errorCode: { type: string, description: 'STREAM_MAX_DURATION | draining (server >= 7.122.0) (open set).' }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION (reader resumes) | draining (server >= 7.122.0; reader leg ends) (open set; any other code ends the leg).' }
         message: { type: string }
     Event_question:
       type: object
@@ -19785,7 +19982,7 @@ components:
         draining by this deadline". See `POST /v1/admin/drain` for how the identity fields are compared.
       properties:
         actionId: { type: string, minLength: 1, description: 'Idempotency key: the same id again answers `already_draining` and changes nothing. Hand-issued actions pick their own (e.g. `manual:<uuid>`).' }
-        worker: { type: string, minLength: 1, description: The engine's worker name (`SEMA_REGISTRY_WORKER`). }
+        worker: { type: string, minLength: 1, description: "The engine's worker name (`SEMA_WEB_ADMIN_WORKER`; `SEMA_REGISTRY_WORKER` on servers <= 7.123.x)." }
         deadlineAt: { type: integer, minimum: 0, description: Epoch milliseconds by which the engine stops on its own. }
         scope: { type: string, minLength: 1, description: 'The tenant scope; omitted = the default scope `global` (compared against env `FLEET_SCOPE`, unset = `global`).' }
         expectedGeneration: { type: string, pattern: '^(0|[1-9][0-9]*)$', description: 'The fleet generation as a canonical decimal string (`/health.generation`); absent against absent — omit it only for a non-member.' }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "18.1.0",
+  "version": "19.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",
@@ -52,6 +52,6 @@
     "prepublishOnly": "rm -f tsconfig.tsbuildinfo && npm run build && npm run typecheck --workspaces=false --prefix ../.. && npm test --workspaces=false --prefix ../.. && npm run prepack"
   },
   "devDependencies": {
-    "@sema-agent/settings-schema": "^9.0.0"
+    "@sema-agent/settings-schema": "^11.2.0"
   }
 }