@sema-agent/sdk 18.0.0 → 18.1.0

package/openapi.yaml

@@ -3234,7 +3234,9 @@ paths:
         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. (Corrected 2026-07-31: this list used to name only meta/pending/resolved — a consumer written to
+        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
         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
@@ -3735,8 +3737,12 @@ paths:
             `ErrorResponse`-shaped. Codes: "request.body_shape" (bad/missing `decision`, OR an unrecognised
             top-level key — server >= 7.86.0 / S-438 key closure, the body carries `unknownKeys` /
             `unsupportedKeys`) · "request.field_conflict" (`edit` without a non-empty `editedPlan`;
-            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `edit`/`reject`;
-            `permissionModeAfter` on a task that was not submitted with `permissionMode:"plan"`) ·
+            `editedPlan` present on approve/reject; `permissionModeAfter` sent with `reject`;
+            `permissionModeAfter` on a task whose stored permission mode is not `plan`) — match these two by CODE;
+            server >= 7.122.0: `approve` and `edit` both carry the plan out of plan mode and both take the key, and a
+            run's mode word has ONE source, the stored submit body (an operator `AUTONOMY=plan` task is stored as `plan`
+            and takes the key); <= 7.121.x only `approve` took it and the second conflict read "not submitted with
+            `permissionMode:"plan"`" ·
             "request.field_invalid" (non-string `reason`; `permissionModeAfter` outside the two-word closed
             set — zero widening arm) · "request.path_malformed" (a bad percent-encoded path segment —
             server >= 7.86.0 / S-430 turned that family from 500 `internal.error` into a 400 across 16 doors).
@@ -4668,7 +4674,8 @@ paths:
         (`LEADER_ENABLED` off) the answer depends on the server: server >= 7.116.0 mounts the route unconditionally and answers
         **501 `capability.leader_endpoint_required`** (new code; under multi-tenant the identity gate's 401 still comes first);
         <= 7.115.x did not register the route at all → the generic **404** `not_found.route`. Detect "leader unavailable" by
-        `errorCode` (or the `capabilities.leader` bit, which reads the same fact as the gate), not by the status alone.
+        `errorCode` (or the `capabilities.leader` bit — server >= 7.122.0 also reads false on a deployment whose operator runs `AUTONOMY=plan`, where a submit answers
+        422 `request.autonomy_lane_refused` instead; see `Capabilities.leader`), not by the status alone.
 
 
         🔴 IDEMPOTENCY (server >= 7.24.0): this POST now consumes the `Idempotency-Key` header — the header is
@@ -4717,6 +4724,20 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: >-
+            errorCode "request.autonomy_lane_refused" (server >= 7.122.0) — the deployment runs the operator `AUTONOMY=plan`: every task starts
+            in plan mode and leaves it only when a person approves its plan through plan review, and a leader task's workers have no plan
+            review channel, so they could neither write nor hand their plan to anyone who can approve it. REFUSED at the door, NO run created;
+            a replay with the same `Idempotency-Key` gets the same 422 (the idempotency key is not consumed). The `capabilities.leader` bit
+            reads false on such a deployment (the same judgement as this refusal) — read it, or `GET /v1/policy` `autonomy`, beforehand. Exits: submit the work as a run (`POST /v1/runs`, plan reviewed through
+            `POST /v1/assistant/tasks/{taskId}/plan_review`), or ask the operator to set `AUTONOMY=read-only` or `ask` (leader tasks run
+            there). Not the hosted-posture refusal (`request.host_posture_refused`): that one is the tenant axis, this one is the AUTONOMY
+            axis. A change to `plan` after acceptance is caught where the run is born: the 202'd run ends with the same sentence in
+            `GET /v1/leader/{leaderRunId}` `error` and no worker is started.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
           description: >-
             errorCode "conflict.leader_run_exists" (server >= 7.24.0) — your `Idempotency-Key` hit a leader run
@@ -7206,7 +7227,12 @@ components:
             `config.permission_mode_unavailable`. `bypassPermissions` RELEASES the ten releasable ask classes (server >= 7.115.0: the tenth is `unstated`, a server-tool call nobody stated)
             and DISCLOSES each (`tool_end.gate.disposition.released` + one `engine_notice` `permission.ask_released_by_mode` per (mode, class) per run);
             immune classes (deployment-authored, ask / org rules, hooks, ancestors, questions …) still ask; a write whose protection
-            cannot be judged is refused (`deniedBy: mode`). Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
+            cannot be judged is refused (`deniedBy: mode`) on the file tools — and, from server >= 7.122.0 / core 7.47.0, RELEASED on the SHELL face
+            (an eleventh class, `write_protection_unresolved`, for a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which
+            declares a write-path target; see `ModeRelease.reason`). `plan` (server >= 7.122.0): the engine's plan mode and nothing the service adds —
+            the tool table equals `default`'s, the engine mounts the plan-presenting tool, and a write or any non-read-only call is asked AT CALL TIME by the
+            engine's plan gate (a card where somebody can answer, a refusal where nobody can; a delegated sub-agent inherits plan as its ceiling); up to
+            7.121.x the service also mapped `plan` to read-only hands, withheld the delegation tool and refused `Workflow`. Request vocabulary: SIX words (server >= 7.119.0) — `dontAsk`, the engine's
             "auto-refuse" mode, is accepted and passes through verbatim: the ENGINE refuses the calls that would ask (no card, no parked row,
             `tool_end.gate.disposition = { kind: denied, deniedBy: mode, mode: dontAsk, … }`), the run ends normally, and it is never looser
             than `default`. One exception: a PreToolUse hook's OWN ask, when no other class in that ask's set backs it, is still handed to a person
@@ -7216,7 +7242,7 @@ components:
             hold for <= 7.105.0 only.
             CC-parity permission-mode INTENT — the values THIS wire's closed submit-gate accepts (the first five on server <= 7.118.x,
             plus `dontAsk` from 7.119.0 = the engine's whole mode vocabulary, `capabilities.permissionModes`). The frontend (TUI shell / web portal) carries the RAW mode; the SERVICE interprets it TIGHTEN-ONLY vs the deployment baseline:
-            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research);
+            `plan` ⇒ mount present_plan (core enablePlanMode) + read-only hands (CC EnterPlanMode research) — that is the <= 7.121.x reading; server >= 7.122.0: see the `plan` sentence in the first block;
             `default` adds the manual ask gate on non-exempt writes (scratchpad dirs / remembered session
             exemptions still auto-allow — not literally every Write/Edit); the server emits the SAME gate-policy
             for `auto` as for `default` — sending `auto` is NOT itself what arms core's auto-mode classifier; that
@@ -9077,7 +9103,16 @@ components:
         asyncRuns: { type: boolean }
         artifacts: { type: boolean }
         approvals: { type: boolean }
-        leader: { type: boolean }
+        leader:
+          type: boolean
+          description: >-
+            The `POST /v1/leader` lane. server >= 7.122.0 reads the conjunction of two facts: the leader face is mounted (`LEADER_ENABLED` etc.) AND the
+            operator entry floor takes leader submissions — the same judgement as the 422 `request.autonomy_lane_refused` at the door (a leader task's
+            workers have no plan review channel). So on a deployment whose operator runs `AUTONOMY=plan` the bit reads false and a direct submit still
+            answers 422 `request.autonomy_lane_refused`; with `AUTONOMY=read-only` / `ask` / unset the bit follows the face. A false bit from an absent face
+            answers 501 `capability.leader_endpoint_required` on submit (404 `not_found.route` on <= 7.115.x) — tell the two falses apart by the submit's
+            `errorCode`, or read `GET /v1/policy` `autonomy` beforehand. <= 7.121.x (historical reading): the bit read the face only — true on a `plan`
+            deployment, no prediction of the refusal.
         version: { type: string }
         scenarios:
           type: array
@@ -9928,13 +9963,16 @@ components:
         taskWriteFaceOpen:
           type: boolean
           description: >
-            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts:653` =
-            `taskWriteFaceRefusal(deps.config) === undefined && autonomyOverrides(deps.config.autonomy).writeFace !== "roots"`)
+            server >= 7.95.0 (S-591; value meaning refined at 7.96.0 / S-613; mint `routes/capabilities.ts` =
+            `taskWriteFaceRefusal(deps.config) === undefined && autonomyKeepsOpenWriteFace(deps.config.autonomy)` from server >= 7.122.0;
+            up to 7.121.x the right half was `autonomyOverrides(deps.config.autonomy).writeFace !== "roots"`)
             — DISCLOSURE BIT OF THE WRITE-CONTAINMENT FACE: does this deployment honour the task-level "open the write
             fence" declaration (`permissionMode:"bypassPermissions"` ⇒ `TaskSpec.writeFace:"open"`, writes outside the
             workspace roots)? `false` has two forms: (1) the hosted-posture gate refuses ⇒ sending that mode gets
-            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only|plan` ⇒ the request is
-            accepted but the write face is clamped back to roots — the declaration silently does nothing. Three states
+            `422 request.host_posture_refused`; (2) the deployment runs `AUTONOMY=read-only` ⇒ the request is
+            accepted but the write face is clamped back to roots — the declaration silently does nothing; server >= 7.122.0: `AUTONOMY=plan`
+            reads `false` too, but because the entry mode word is clamped to `plan` at admission (the engine's plan mode runs instead of
+            `bypassPermissions`; up to 7.121.x it was the same read-only-hands + roots clamp as `AUTONOMY=read-only`, and a hosted deployment answered 422 `request.host_posture_refused` where it now accepts the request into plan). Three states
             are folded into one bit on purpose: the caller has exactly one decision (send that key or not); tier and
             evidence live in the refusal body and the operator's `GET /v1/diagnostics/wiring`. It speaks ONLY for the
             write-containment cell — the other two columns of `bypassPermissions` are unaffected.
@@ -12848,8 +12886,9 @@ components:
         REQUIRED iff `decision==="edit"` (FORBIDDEN otherwise → 400).
         🔴 THE BODY KEY SET IS CLOSED (server >= 7.86.0 / S-438): an unrecognised top-level key is refused with
         400 `request.body_shape` plus the `unknownKeys` / `unsupportedKeys` machine tables — refused rather
-        than dropped, because a misspelled `permissionModeAfter` would otherwise silently leave the task
-        read-only after its plan was approved.
+        than dropped, because a misspelled `permissionModeAfter` would otherwise silently fold to `default`
+        (the task keeps asking before each write after its plan was approved) while the caller believes the
+        mode was settled.
       required: [decision]
       additionalProperties: false
       properties:
@@ -12860,18 +12899,35 @@ components:
           type: string
           enum: [default, acceptEdits]
           description: >
-            server >= 7.86.0 (S-433, P1; mints `routes/approvals-assistant.ts:1021/1024/1148`) — WHICH
-            PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved. Before this key, approving a plan
-            was a BLANK CHEQUE: the plan was approved while the read-only clamp stayed on and every write kept
-            asking. `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when
-            the key is absent, so an older shell executes plans unchanged).
-            🔴 THREE 400s, each with its own code: a value outside the two-word closed set ⇒
+            server >= 7.86.0 (S-433, P1) — WHICH PERMISSION MODE THIS TASK CONTINUES IN once the plan is approved.
+            `acceptEdits` = writes stop asking; `default` = keep asking (AND is the folded value when the key is
+            absent, so an older shell executes plans unchanged). The decision writes the mode back into the task's
+            stored submit body, so every later park -> resume continues in it and never falls back to plan.
+            🔴 server >= 7.122.0 — ONE JUDGE, ONE SOURCE: plan is only the engine's `permissionMode:"plan"`. Since 7.122.0
+            the service adds no read-only clamp of its own, so there is none to lift: the tool table equals `default`'s,
+            and a write or any non-read-only call is asked (somebody can answer) or refused (nobody can) AT CALL TIME by
+            the engine's plan gate. A run's mode word has ONE source, the stored submit body; its two writers are the submit door
+            and this write-back. A decision that carries the plan out of plan mode — `approve` (the original plan) or
+            `edit` (the person's revised plan; the engine proceeds with it) — writes this key back (absent => `default`);
+            only `reject` (the review goes back to redo the plan, plan mode stays) does not. Before 7.122.0 the service
+            also mapped plan to read-only hands; this key was added in 7.86.0 because, before it, approving a plan was a
+            BLANK CHEQUE (the plan was approved while the read-only clamp stayed on and every write kept asking); and on
+            7.86.0-7.121.x `edit` + this key was a 400 while `edit` itself wrote back `plan`, the continuation still held
+            by the read-only hands. All of that is gone since 7.122.0.
+            (A deployment's `AUTONOMY=read-only` static fence is a separate thing: since 7.122.0 it is all the service's governance
+            layer re-folds on each resume, it has nothing to do with approving a plan, and approval does not lift it.)
+            🔴 THREE 400s, each with its own code (match by CODE, not by sentence — the two `request.field_conflict`
+            sentences were reworded in 7.122.0, codes unchanged): a value outside the two-word closed set =>
             `request.field_invalid` (ZERO widening arm — this bit decides whether the model has hands after
             approval, so folding a misspelling into either mode is a silent downgrade on the security axis);
-            sending it with `edit`/`reject` ⇒ `request.field_conflict` (core: those two send the plan back to be
-            redone and the read-only clamp stays — dropping it there would let the caller believe the mode was
-            settled); sending it for a task that was NOT submitted with `permissionMode:"plan"` ⇒
-            `request.field_conflict` (approving the plan lifts no read-only restriction there).
+            sending it with `reject` => `request.field_conflict`, server sentence `permissionModeAfter is only valid with a
+            decision that carries the plan out ('approve' or 'edit'; got 'reject')` (a silent drop there would let the caller
+            believe the mode was settled); sending it for a task whose STORED permission mode is not `plan` (the model
+            entered plan mode itself, so approving returns it to the mode it was in before planning) =>
+            `request.field_conflict`, server sentence `permissionModeAfter does not apply to this task: it was not
+            started in plan mode (its stored permission mode is not "plan"), so approving the plan returns it to the mode
+            it was in before planning`. A task STARTED in plan mode is one the request put there, or one an operator
+            `AUTONOMY=plan` stamped at the submit door (its stored word is `plan`): the key is accepted for both.
             ⚠️ DIRECT-DOOR deployments: this key rides the HMAC envelope's TRAILING EXTENSION OBJECT (server
             7.87.0: `{answer?, permissionModeAfter?}`, present keys in lexicographic order; 7.86.0's bare
             trailing slot is DELETED with zero double-read) ⇒ a signer must sign the new shape, and mixed
@@ -13717,6 +13773,14 @@ components:
             `writeFace: open`; read `capabilities.taskWriteFaceOpen` first); (2) server >= 7.106.0 / S-895: `inheritEnv: "all"` on a
             hosted deployment (`REQUIRE_PRINCIPAL=true`; reach = the hosted posture only; read `capabilities.projectContext` first).
             Remove the key (or send `inheritEnv: "scrub"`) and resend. Resume legs fold it into 409 `resume_blocked_by_policy`.
+            🔴 `request.autonomy_lane_refused` (422, server >= 7.122.0): the deployment's operator `AUTONOMY` does not take tasks on this LANE.
+            Today's only trigger is `AUTONOMY=plan` × `POST /v1/leader` — plan leaves plan mode only through a person approving the plan (plan
+            review), a leader task's workers have no plan review channel, so the refusal is at the door and NO run is created (a replay with the
+            same `Idempotency-Key` gets the same 422 and does not consume the key). Same family as `host_posture_refused` but a different axis:
+            that one is the hosted / tenant posture axis (remove the key and resend); this one is the AUTONOMY axis (nothing to remove — submit
+            as a run via `POST /v1/runs`, or ask the operator for `AUTONOMY=read-only` / `ask`, under which leader tasks run). Read the live
+            config: a hot change takes effect on the next request; read `GET /v1/policy` `autonomy` beforehand (the `capabilities.leader` bit
+            reads false on such a deployment).
         error: { type: string }
         errorMessage: { type: string }
         activeTaskId:
@@ -14455,7 +14519,9 @@ components:
         bypass-IMMUNE (not releasable).
         CLOSED on the gate record (screened with core `isAskClass`). `bypassPermissions` releases only the ten RELEASABLE classes
         (`transcript_write` / `rule_unreadable` / `probe` / `write_protection` / `tool_marks_mcp` / `tool_marks_a2a` /
-        `artifact_shared_read` / `mode` / `unstated` / `ordinary`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
+        `artifact_shared_read` / `mode` / `unstated` / `ordinary`) — on every face — plus, from server >= 7.122.0 / core 7.47.0, an eleventh on the SHELL
+        face only: `write_protection_unresolved` (core `releasableAskClassesFor(face)`: shell 11, other faces 10; on the file tools that class is
+        refused, `deniedBy: mode`); every other class (deployment-authored `operator_forced`, ask / org rules, hook,
         ancestor, content question, …) asks under every mode.
     ModeRelease:
       type: object
@@ -14477,8 +14543,19 @@ components:
         mandate: { $ref: '#/components/schemas/PersistedRuleMandate' }
         reason:
           type: string
-          enum: [rule_unreadable]
-          description: '`rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a security-axis fail-open direction the server discloses on its own).'
+          enum: [rule_unreadable, write_protection_unresolved]
+          description: >
+            WHAT the release went over — one word: the FIRST member (in core `MODE_RELEASE_REASONS` array order) that the ask's class
+            set holds; ABSENT when the set holds none. CLOSED set — the server screens it with core `isModeReleaseReason`, so a word
+            outside it withholds the whole `gate` from the frame (and a consumer that dispatches on the word must learn each new one).
+            `rule_unreadable` = the release went over a rule this call could not be read against (the rule store was unreadable — a
+            security-axis fail-open direction the server discloses on its own).
+            `write_protection_unresolved` (server >= 7.122.0 / core 7.47.0) = the release went over a write whose target the
+            write-protection judge could not RESOLVE (whether it lands on the protected table is unknown). It is released on the SHELL
+            face only: a caller-supplied tool whose wire name is exactly `Bash` or `Monitor` and which declares a write-path target,
+            under `bypassPermissions`; on the file tools the same unresolved write is still refused (`deniedBy: mode`). The engine's
+            own `Bash` / `Monitor` cannot mint this class and the server mounts no such tool — it comes from a caller-embedded tool of
+            those names. Before server 7.122.0 / core 7.47.0 the set was `rule_unreadable` alone.
 
     GateClassifierAttribution:
       # sdk 9.5.0:具名 —— 同一份形挂在 `GateDisposition` 的两只臂上,内联会立刻是两份会各自漂的镜像。
@@ -17871,13 +17948,16 @@ components:
         🔴 Its arrival means the RUN IS STILL ALIVE — the 15-minute stream cap fired. The correct handling is to
         RECONNECT with `Last-Event-ID` and keep reading (the durable leg stamps `id:` on every frame); rendering
         it as a terminal would declare a live task dead. `done` / `failed` are the terminal arms; this one is not.
-        Known `errorCode`: `STREAM_MAX_DURATION` (open set — branch on the code, degrade unknown codes to the
-        generic "reconnectable stream-control signal").
+        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").
       additionalProperties: false
       required: [type, errorCode]
       properties:
         type: { const: error }
-        errorCode: { type: string, description: 'STREAM_MAX_DURATION (open set).' }
+        errorCode: { type: string, description: 'STREAM_MAX_DURATION | draining (server >= 7.122.0) (open set).' }
         message: { type: string }
     Event_question:
       type: object

package/package.json

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