@sema-agent/sdk 18.1.0 → 18.2.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':
@@ -4123,8 +4152,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 +4162,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:
@@ -7469,6 +7480,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`.
@@ -9601,6 +9616,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
@@ -9779,10 +9797,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 +9822,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 +10257,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 +10274,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 +11009,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: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "18.1.0",
+  "version": "18.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",
@@ -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": "^10.1.1"
   }
 }