@sema-agent/sdk 9.0.0 → 9.2.0

package/openapi.yaml

@@ -918,6 +918,104 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  /v1/runs/{taskId}/memory/capture-optout:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+    post:
+      tags: [runs]
+      operationId: runsMemoryCaptureOptOut
+      x-status: live             # server >= 7.70.0 — the mid-run flip verb for the session memory-capture opt-out.
+      summary: Opt this SESSION out of long-term memory capture, mid-run.
+      description: >
+        "We got into something that should not be remembered." From this moment the session commits NOTHING to
+        long-term memory, already-committed contributions leave the consolidation pool, and write-root residue
+        is swept. ONE-WAY: there is no reverse verb, repeat calls are idempotent (`outcome:"existed"`), and
+        getting capture back needs a NEW session.
+        🔴 The SAME record as the `memoryCapture:"off"` submit-time declaration, reached through a second
+        ingress — so "declare it on the next submit" is the fallback for MOST refusals. It is not the answer to
+        all of them: read the per-errorCode recovery notes on the 409/503 arms below (one 409 is a PARTIAL
+        SUCCESS whose retry lane is this very verb, one names another replica, and one is a deployment-shape
+        fact the declaration hits too).
+        Owner-gated on the VERIFIED principal (a bare sessionId relay would let anyone switch off anyone's
+        memory); a non-owner gets the SAME 404 string as an unknown run (no existence oracle). The engine
+        re-adjudicates the per-principal entitlement at flip time — the service does not replicate that ruling.
+        Runs no model (not billable, no drain/roster gate); rate-limited as a mutating verb. Gate the UI entry
+        on `capabilities.runMemoryCaptureOptOut`.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false      # STRICT server-side — a mistyped key is a 400, not "no reason given".
+              properties:
+                reason: { type: string, minLength: 1, maxLength: 500, description: 'Optional one-line audit note. Does not affect the ruling.' }
+      responses:
+        '200':
+          description: Flipped — `created` on the first call, `existed` on an idempotent repeat.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryCaptureOptOutResult' }
+        '400':
+          description: >-
+            errorCode "request.body_shape" — the body must be `{}` or `{ reason }` (non-empty, at most 500
+            chars); this verb takes no other keys.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: >-
+            errorCode "memory.capture_optout_denied" — this principal's entitlement does not permit the opt-out.
+            TERMINAL: the verdict is a deployment/center fact, so retrying changes nothing.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '409':
+          description: >-
+            Four DIFFERENT situations share this status; the recovery action is per errorCode, not per status.
+            (1) "steering.not_running" — this verb needs a LIVE turn and there is none. THREE of its four causes
+            (terminal / parked / no steerable face on this replica) are fixed the same way: declare
+            `memoryCapture: "off"` on this session's next NEW submit. ⚠️ For a PARKED run that matters twice
+            over — a resumed continuation rebuilds its spec from the PERSISTED body and cannot take a new
+            declaration, so content captured until that next submit stays captured. The FOURTH cause is
+            different: when the run is live on ANOTHER replica the service says so explicitly, and the recovery
+            is to RESEND this verb to the owning replica (the next-submit declaration also works).
+            (2) "memory.capture_optout_sweep_failed" — 🔴 PARTIAL SUCCESS, not a rejection: the one-way opt-out
+            record STANDS (capture is already off) and only the residue sweep failed on named paths. A repeat
+            call IS the retry lane; leaving it un-retried leaves that named residue on the authoritative plane.
+            (3) "memory.capture_optout_unavailable" — this run mounted no memory session, so there is nothing to
+            opt out of; no action is owed.
+            (4) "config.memory_capture_unsupported" — a DEPLOYMENT-SHAPE fact (no capture record store on this
+            worker, so the record would not survive to a resume replica). 🔴 The submit-time declaration hits the
+            SAME wall on this shape — do not advertise it as the workaround; the fix is on the deployment.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '422':
+          description: 'errorCode "steering.invalid_content" — the engine refused the reason payload.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429':
+          description: >-
+            errorCode "limit.rate_exceeded" — mutating verb, rate-limited only (no quota/lease gate; it runs no
+            model). `Retry-After` (seconds) set.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }
+        '503':
+          description: >-
+            errorCode "memory.capture_optout_unpersisted" — the record could not be durably written (a store-mark
+            failure, or a failing consolidation-epoch bump). The engine REFUSES rather than holding the flip
+            in-process, so capture is still ON. RETRYABLE (the verb is idempotent).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/runs/{taskId}/subagents/{target}/output:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -2554,16 +2652,20 @@ paths:
             `POST /v1/assistant/tasks/{taskId}/resume`. Retrying the same body never succeeds.
             SEVENTH group (server >= 7.69.0 / S-185, the PARKED WORKFLOW-CHILD lane): `decide.workflow_host_unknown`
             and `decide.workflow_host_not_parked`. The pending belongs to a workflow child that parked on an
-            approval gate, and the deployment could not hand the decision to that workflow's HOST session (the
-            engine's only deployment-facing channel for a parked workflow ordinal is a resume of the host, which
-            then re-invokes `Workflow({resumeFromRunId})`). Both bodies carry `runId` (the WORKFLOW run) and NO
-            `taskId`. NOTHING was consumed: the child's checkpoint stays PENDING and the card is still listable
-            and re-decidable. `_host_not_parked` = the host is not currently parked awaiting this run (it may
-            have been interrupted, taking an already-delivered decision with it — the decision is not persisted
-            anywhere) → retry once it parks again, or resume that `runId` yourself. `_host_unknown` = the run
-            carries no originating session at all (a directly started `runWorkflow`, not a Workflow tool call) →
-            NO retry value, a person resumes that `runId`. SDK → DecideWorkflowHostError (`.errorCode` splits the
-            two recovery verbs, `.runId` is the handle).
+            approval gate, and the deployment could not hand the decision to that workflow's HOST session. Both
+            bodies carry `runId` (the WORKFLOW run) and NO `taskId`. NOTHING was consumed: the child's checkpoint
+            stays PENDING and the card is still listable and re-decidable. SDK → DecideWorkflowHostError (`.runId`
+            is the handle). `_host_unknown` = the run carries no originating session at all (a directly started
+            `runWorkflow`, not a Workflow tool call) → NO retry value, a person resumes that `runId`.
+            `_host_not_parked` = the host is not currently parked awaiting this run. ⚰️ RETIRED at server 7.72.0,
+            no alias, but this SDK still maps it: `SUPPORTED_SERVER_FLOOR` is 3.0.0 and this code was introduced
+            at 7.69.0, so a still-supported server in the [7.69.0, 7.72.0) window can genuinely send it, and for
+            that window the old contract holds — retry once it parks again, or resume that `runId` yourself. A
+            server >= 7.72.0 will never send this code again: that version replaced the dead end with a SECOND
+            leg that instead mints a fresh run on the same host session, so against a current server the SAME
+            decide either resumes the parked host or starts that new run (both land on the byte-identical
+            acceptance shape) — a host session already busy with another run instead answers the ordinary 409
+            `conflict.session_active_run`.
             SIXTH group (A-075.10, TIME-BASED retry-later pair): `resume.usage_window_exhausted` (#449 G1,
             core 5.60.1 — the deployment governance window on this run's ledger key is full; NOTHING was
             consumed or unpinned, the SAME token with the SAME decision redeems once the window slides) and
@@ -5232,7 +5334,9 @@ components:
       type: object
       description: >
         Common request body. `[additionalProperties]` mirrors the service passthrough — scenario-specific fields
-        (code-review's `repo`/`council`/`debate`/`rounds`, etc.) ride here.
+        (code-review's `repo`/`lenses`/`rounds`, etc.) ride here. NOTE (sdk 9.1.0): `council`/`debate` used to be
+        named here as passthrough examples, but the service declares them as TOP-LEVEL typed keys and reads them
+        on two seams outside the scenario builder, so they are declared properties below.
       required: [objective]
       additionalProperties: true
       properties:
@@ -5318,6 +5422,40 @@ components:
             (mcpInjectionHonored = requirePrincipal!==true); multi-tenant ignores it (fail-closed). Merge:
             deployment/center baseline wins on name collision (caller can ADD, never SHADOW).
           items: { $ref: '#/components/schemas/McpServerSpec' }
+        a2aPeers:
+          type: array
+          maxItems: 32
+          description: >
+            Per-request A2A peers — remote agents this task may call. HONORED only on a SINGLE-USER deployment
+            that has neither locked the `a2a` key nor had `a2a_peers` denied by its compliance posture (the same
+            three-veto predicate `capabilities.a2aInjection` advertises); multi-tenant ignores the field, and a
+            LOCKED deployment refuses the whole request with 400 `config.locked_key`.
+            🔴 Declaring a peer declares an OUTBOUND WRITE channel: every skill it advertises mounts with
+            `egress:true` + `effect:"write"` (core's ruling); `toolAxes` is the caller's explicit override face.
+            🔴 A malformed entry drops the WHOLE peer (named in a warn), never "drop the bad key and keep the
+            peer": `allowSkills` is a NARROWING field whose absence means "no restriction", so a half-applied
+            entry would turn a narrowing intent into a widening. The request itself is not rejected.
+            The center/config baseline wins on a name clash (the peer name IS the tool namespace segment). Over
+            the 32-entry cap the surplus entries are DROPPED and named too — same disposition as a malformed
+            entry, not a 400.
+          items: { $ref: '#/components/schemas/A2aServerSpec' }
+        council:
+          type: boolean
+          description: >
+            The `code-review` scenario's EXPENSIVE tier — fan the review out to N parallel lenses plus an
+            arbiter (`run_council`) instead of the lead reviewing in-line. Read on TWO seams and both matter:
+            the scenario builder mounts the council tool, and spec resolution treats it as an EXPLICIT team
+            declaration (widening the task's wall-clock tenancy budget and suppressing the value router's
+            auto-escalation). Only a literal `true` counts on both seams. On other scenarios the first seam is
+            inert while the second still applies.
+        debate:
+          type: boolean
+          description: >
+            Run the L2 peer-debate rounds on top of `council`. 🔴 The two seams are ASYMMETRIC — this is not a
+            standalone switch: the scenario builder reads it only INSIDE the `council === true` branch (sending
+            `debate:true` alone produces no debate rounds), while the explicit-team predicate is
+            `council || debate` (sending it alone still widens the budget and suppresses auto-escalation).
+            Literal `true` only, same as `council`.
         resumeAt:
           type: string
           description: >
@@ -5503,6 +5641,22 @@ components:
           items: { type: string }
           description: Capability names the caller requires; the worker refuses up front rather than 501-ing mid-run.
         memoryWrite: { type: boolean, description: Allow this task to WRITE user memory (read is governed separately). }
+        memoryCapture:
+          type: string
+          enum: [off]
+          description: >
+            server >= 7.70.0 — the SESSION-level memory-capture OPT-OUT declaration: "off" means "this session
+            does not enter long-term memory". A ONE-MEMBER closed set: there is NO "on" spelling, absence is the
+            only way to say "capture as usual".
+            🔴 A DIFFERENT AXIS from `memoryWrite`: that one pauses writes for THIS run and can be flipped back
+            per run; this one is a ONE-WAY, one-shot session record (later resumes never capture, repeat
+            declarations are idempotent, and getting capture back needs a NEW session).
+            🔴 The spelling gate is loud on BOTH legs (no resume downgrade): "OFF" / a boolean / anything else
+            is a 400 `request.field_invalid` — silently dropping a privacy request as a typo is the banned
+            direction. A deployment policy that refuses this principal's opt-out answers 403
+            `memory.capture_optout_denied` (terminal). A worker older than 7.70.0 IGNORES the key silently, so
+            it is not a capability probe. Rides the persisted body onto resume legs.
+            Mid-run flip: POST /v1/runs/{taskId}/memory/capture-optout (the same record, a second ingress).
         settings:
           type: object
           description: >
@@ -7283,6 +7437,71 @@ components:
             face drops the whole server.
           additionalProperties: { $ref: '#/components/schemas/McpToolFace' }
 
+    A2aServerSpec:
+      type: object
+      description: >
+        One per-request A2A peer (`TaskRequest.a2aPeers[]`). These six keys are exactly what the service's
+        normalizer copies through — anything else on the entry never reaches the engine. `name`/`url` are
+        required; if ANY present key is malformed the WHOLE peer is dropped (and named in a warn), because a
+        half-applied entry can turn a narrowing intent into a widening.
+      required: [name, url]
+      additionalProperties: false
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: 'Stable local name; also the tool-namespace segment (`a2a__<peer>__<skill>`).'
+        url:
+          type: string
+          description: 'The peer service URL; doubles as the origin the well-known agent-card path resolves against. http(s) ONLY.'
+        cardUrl:
+          type: string
+          description: >
+            Explicit agent-card location. When set it is used ALONE (no well-known probing behind the operator's
+            back), so a malformed value drops the peer rather than falling back.
+        headers:
+          type: object
+          additionalProperties: { type: string }
+          description: 'Static headers sent on every request to this peer.'
+        principalHeader:
+          type: string
+          description: >
+            Header name the Runner injects this run's AUTHENTICATED principal into (the model can neither read
+            nor set it). Absent principal => the header is not sent; the peer must then default to deny/public.
+        allowSkills:
+          type: array
+          items: { type: string }
+          description: >
+            Allowlist of remote skill ids to mount. ⚠️ ABSENCE means "no restriction" (core's semantic), so this
+            is a NARROWING key — never express narrowing by omitting it.
+        toolAxes:
+          type: object
+          description: >
+            Per-skill safety-axis overrides keyed by the peer's REMOTE skill id. The caller is the trust root,
+            so this may LOWER the fail-closed default (`egress:true` + `effect:"write"`) as well as raise it.
+            ⚠️ Lowering `effect` WITHOUT clearing `egress` is a combination the engine refuses by design.
+          additionalProperties:
+            type: object
+            additionalProperties: false
+            properties:
+              effect: { type: string, enum: [read, write, idempotent] }
+              egress: { type: boolean }
+              irreversibility: { type: string, enum: [always, never] }
+
+    MemoryCaptureOptOutResult:
+      type: object
+      description: >
+        200 body of POST /v1/runs/{taskId}/memory/capture-optout. `outcome` is a closed two-word set:
+        `created` = this call wrote the one-way session record; `existed` = the session had already opted out
+        (idempotent replay).
+      required: [taskId, sessionId, outcome]
+      additionalProperties: false
+      properties:
+        taskId: { type: string }
+        sessionId: { type: string }
+        outcome: { type: string, enum: [created, existed] }
+
     MemoryEntryFrontmatter:
       type: object
       description: >
@@ -8597,9 +8816,16 @@ components:
         lane's 200 DO mean the engine committed the decision — one sentence ("approved and in effect") cannot be
         used for both lanes.
         (2) delivery can still be LOST: if the host run is interrupted before it re-invokes `Workflow`, the
-        decision goes with that invocation (it is not persisted anywhere) and a retry answers 409
-        `decide.workflow_host_not_parked`. Because the card was pending throughout, nothing is forged and the
-        approval can be re-decided once the host parks again.
+        decision goes with that invocation (it is not persisted anywhere); because the card was pending
+        throughout, nothing is forged. Against a server >= 7.72.0 a retry of the SAME decide succeeds — that
+        version gave this lane a second leg that mints a fresh run on the same host session when the host is not
+        currently parked, so the retry either resumes the parked host or starts that new run (byte-identical
+        acceptance shape either way; a host session already busy with another run instead answers the existing
+        `conflict.session_active_run` 409). Against a still-supported server in the [7.69.0, 7.72.0) window
+        (`SUPPORTED_SERVER_FLOOR` is 3.0.0) the retry instead answers 409 `decide.workflow_host_not_parked` —
+        retry once the host parks again, or resume that `runId` yourself. ⚰️ That code is RETIRED at 7.72.0, no
+        alias, and a current server will not send it again — but it remains a live, supported response from an
+        older server in that window, so the SDK still maps it (see `DecideWorkflowHostError`).
         The durable approval-queue projection is UNCHANGED — no key marks the workflow origin on any read face.
       required: []
       additionalProperties: false
@@ -8940,6 +9166,21 @@ components:
             one-off question. The value comes WHOLE from core (`summarizeCheckpoint` echoes it only when the
             cause is a member of the engine's set), so the server neither recomputes nor re-screens it. See
             ClassifierUnavailable for the open-`cause` rule and the three shapes absence covers.
+            RETIRED: server >= 7.72.0 (core 7.14.0 #688) never mints this key on any of the three faces; its
+            successor is `disposition.cause` on the gate record (`unavailable` / `parse_error` — a different
+            question, so an old switch does not port). Kept for servers in [7.69.0, 7.72.0) only (sdk 9.2.0).
+        ruleStoreUnreadable:
+          type: string
+          enum: [store, call]
+          description: >-
+            server >= 7.72.0 (core 7.14.0 #688 C3), ADDITIVE — WHICH HALF of the rule lane could not be read.
+            Present iff `origin === "rule_store_unavailable"`: `store` = the wired rule store could not be read
+            (look at the store / network); `call` = the store was read but THIS command could not be read against
+            the person's deny/ask rows (look at the command spelling). One `origin` word covers both facts, and
+            their recovery verbs live in different places (ops vs prompt). Carried on the live `tool_approval`
+            frame and the inbox row; the `card_json` card deliberately does NOT carry it (it travels with `origin`,
+            which is not on the card). Absence = `origin` is not that word — NOT an assertion that the rule store
+            is healthy.
 
     InboxList:
       type: object
@@ -9681,6 +9922,13 @@ components:
         - $ref: '#/components/schemas/Event_tool_approval_complete'
         - $ref: '#/components/schemas/Event_approval_request'
         - $ref: '#/components/schemas/Event_approval_revoke'
+        # sdk 9.1.0: two LIVE-leg arms the service has been emitting while neither this union nor the
+        #   SDK's declared them — `text_end` since server 7.66.0 (segment boundary; retires the idle-flush
+        #   heuristic) and `tool_roster_delta` since server 7.70.0 (run-time roster change). A generated client
+        #   had no arm to switch on and dropped both. Found by the mechanical frame-arm reconciliation gate
+        #   (server `routes/tasks.ts` mint points x this union), which now runs on every build.
+        - $ref: '#/components/schemas/Event_text_end'
+        - $ref: '#/components/schemas/Event_tool_roster_delta'
       discriminator:
         propertyName: type
         mapping:
@@ -9724,6 +9972,8 @@ components:
           tool_approval_complete: '#/components/schemas/Event_tool_approval_complete'
           approval_request: '#/components/schemas/Event_approval_request'
           approval_revoke: '#/components/schemas/Event_approval_revoke'
+          text_end: '#/components/schemas/Event_text_end'
+          tool_roster_delta: '#/components/schemas/Event_tool_roster_delta'
 
     # design/99 §E2 (SHIPPED, core TaskEventIdentity) — additive per-event identity on every CONTENT event (NOT on
     # the lifecycle arms turn_end/compacted/suspended/done/failed). eventId = uuidv7 dedup/resume handle (the durable
@@ -9813,6 +10063,27 @@ components:
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    Event_text_end:
+      type: object
+      description: >
+        LIVE stream only (server >= 7.66.0, core 5.62.0) — the END-OF-SEGMENT signal for one assistant text
+        segment. `content` is the segment's AUTHORITATIVE full text (same trust class as `text_delta`, same
+        zero content transformation). It retires the "no delta for N ms => the segment must be over" idle-flush
+        heuristic: the boundary is now stated by the engine, not guessed by a timer.
+        🔴 A TRUNCATED segment gets NO such frame (core deliberately withholds it) — "no text_end" does NOT
+        mean "the segment is still going". 🔴 The durable leg does not append it (the batched `text` event
+        carries the same final prose), so GET /v1/runs/{id}/events never replays it. Both mint points are in
+        `routes/tasks.ts`: the top stream (all four identity keys) and the forwarded sub-agent leg (first two).
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, content]
+      properties:
+        type: { const: text_end }
+        content: { type: string }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
     Event_tool_start:
       type: object
       allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
@@ -9982,6 +10253,18 @@ components:
           properties:
             kind: { const: denied }
             deniedBy: { $ref: '#/components/schemas/DeniedBy' }
+            cause:
+              type: string
+              description: >-
+                server >= 7.72.0 (core 7.14.0 #688 C-a) — the SHAPE of this deny when the auto-mode classifier was
+                the refusing layer: `unavailable` (that classifier round could not run: threw / refused / over cap)
+                or `parse_error` (it ran but answered outside the verdict contract, so the call was stopped to be
+                safe). Successor seat of the retired `classifierUnavailable` key (minted once by the engine, carried
+                on both `tool_end.gate` and `permissionDenied.gate`) — but NOT the same question as the old `cause`
+                (`error` / `timeout` answered WHY it was unavailable), so an old switch does not port. The
+                vocabulary's owner is the engine (`CLASSIFIER_DENY_CAUSES`); the server passes it through verbatim
+                — branch the two known words and keep a default arm. Absent = this deny was not a classifier-fault
+                shape (policy / person / rule refused); never read absence as "classifier healthy".
 
     GateOutcome:
       type: object
@@ -10020,7 +10303,7 @@ components:
             #   服务对缺陷记录是整条不上帧 ⇒ 词表外的值在这条 wire 上到不了消费端。审批帧那一面不判成员,
             #   所以 `AskOrigin` 本体保持真开(见该 schema 的长注)。这张 enum 是本 spec 里该词表的**唯一**
             #   执法点;core 加词时改这一处。
-            - enum: [content_question, unresolvable, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
+            - enum: [content_question, ancestor_marked, org_unavailable, org_rule, rule_store_unavailable, hook, ask_rule, denial_limit_fallback, shell_gate_tighten, safety_tighten, policy]
           description: >
             WHO ASKED. Same-present/same-absent as `settlement` (I1). CLOSED here (and only here) — see the
             enum note above.
@@ -10585,6 +10868,59 @@ components:
         parentToolCallId: { type: string }
         sourceTaskId: { type: string }
         bgAgentId: { type: string }
+    Event_tool_roster_delta:
+      type: object
+      description: >
+        A RUN-TIME roster change (server >= 7.70.0, core 7.8.0; live-only until 7.71.0, see below).
+        `wiring_manifest.tools` is the snapshot taken when this leg started; this frame is the increment after
+        it: one refresh that actually changed the roster emits EXACTLY one frame (ordered after the manifest and
+        before that refresh's own `tool_end`).
+        🔴 A `delta.fromDigest` that does not match what the consumer holds is NOT a rejection: `delta.roster`
+        is the new state regardless — record a skew and re-sync from the whole roster (only `delta.summary`
+        becomes unusable). 🔴 Half a roster never reaches the wire: the service drops the WHOLE frame when
+        core's own typebox check rejects the payload. 🔴 Durable legs (server >= 7.71.0, S-212): BOTH durable legs
+        append it too (the three legs share one mint point), so the raw replay `GET /v1/runs/{id}/events`
+        (`runs.events()`, `AgentEvent`) DOES carry it after a reconnect. What still never carries it is the
+        projected trace stream `GET /v1/tasks/{id}/stream` (`trace.stream()`, `TraceStreamEvent`, `mapTraceEvent`
+        drops it with `wiring_manifest` / `human_input`) — consumers on THAT leg keep re-syncing from the
+        `wiring_manifest.tools` snapshot. (Before 7.71.0 the frame was live-only.)
+      allOf: [{ $ref: '#/components/schemas/EventIdentity' }]
+      additionalProperties: false   # 封闭 + identity 本地镜像:见 Event_reasoning 处的长注
+      required: [type, delta]
+      properties:
+        type: { const: tool_roster_delta }
+        delta: { $ref: '#/components/schemas/ToolRosterDelta' }
+        eventId: { type: string }
+        parentToolCallId: { type: string }
+        sourceTaskId: { type: string }
+        bgAgentId: { type: string }
+    ToolRosterDelta:
+      type: object
+      description: >
+        core `ToolRosterDelta` (core 7.8.0) — the payload of `tool_roster_delta`. `roster` is the WHOLE
+        post-change roster and positions come from IT, never from `summary`; the three `summary` lists are
+        pairwise disjoint and a `changed` name's new row lives in `roster`.
+        🔴 OPEN on purpose (`additionalProperties: true`), unlike the frame that carries it. The rule: a schema is
+        CLOSED where the SERVICE builds the object key by key (every `Event_*` arm), and OPEN where the service
+        forwards a CORE-owned payload VERBATIM and keeps no key table of its own. This payload is the latter (the
+        service passes `delta` through after core's own typebox check), so closing it would turn a future core key
+        into "every legitimate frame is a violation". `ToolRoster` is closed despite the same provenance because
+        the service DOES keep a compile-time key table for it.
+      required: [fromDigest, roster, summary]
+      additionalProperties: true
+      properties:
+        fromDigest:
+          type: string
+          description: 'The digest the consumer is expected to hold. A mismatch is a SKEW (re-sync from `roster`), never a rejection.'
+        roster: { $ref: '#/components/schemas/ToolRoster' }
+        summary:
+          type: object
+          required: [added, removed, changed]
+          additionalProperties: true      # same rule as the parent — core owns this payload's key table.
+          properties:
+            added: { type: array, items: { type: string } }
+            removed: { type: array, items: { type: string } }
+            changed: { type: array, items: { type: string } }
     ToolRoster:
       type: object
       description: >
@@ -10625,7 +10961,13 @@ components:
         capabilityId: { type: string }
         effect: { type: string, enum: [read, write, idempotent] }
         egress: { type: boolean }
-        irreversibility: { type: string, enum: [always, never] }
+        irreversibility:
+          type: string
+          enum: [always, maybe, never]
+          description: >
+            core's THREE-word set (`never` / `maybe` / `always`). `maybe` is a real emitted value (e.g. a shell
+            tool under a classifying gate), so a two-word mirror rejects an entire legitimate roster and leaves
+            the consumer on stale state.
         contentOrigin: { type: string, enum: [local, execution, external] }
         family: { type: string, enum: [shell, file-read, file-write, search, web, delegate, plan, scaffold, memory, protocol, other] }
         pathTarget: { $ref: '#/components/schemas/McpToolPathTarget' }
@@ -11400,6 +11742,21 @@ components:
             server >= 7.69.0 (core 7.10.0 #616), ADDITIVE, present only when the classifier was consulted and
             could not run — WHY this ask reached a human. See ClassifierUnavailable for the open-`cause` rule and
             the three shapes absence covers.
+            RETIRED: server >= 7.72.0 (core 7.14.0 #688) never mints this key on any of the three faces; its
+            successor is `disposition.cause` on the gate record (`unavailable` / `parse_error` — a different
+            question, so an old switch does not port). Kept for servers in [7.69.0, 7.72.0) only (sdk 9.2.0).
+        ruleStoreUnreadable:
+          type: string
+          enum: [store, call]
+          description: >-
+            server >= 7.72.0 (core 7.14.0 #688 C3), ADDITIVE — WHICH HALF of the rule lane could not be read.
+            Present iff `origin === "rule_store_unavailable"`: `store` = the wired rule store could not be read
+            (look at the store / network); `call` = the store was read but THIS command could not be read against
+            the person's deny/ask rows (look at the command spelling). One `origin` word covers both facts, and
+            their recovery verbs live in different places (ops vs prompt). Carried on the live `tool_approval`
+            frame and the inbox row; the `card_json` card deliberately does NOT carry it (it travels with `origin`,
+            which is not on the card). Absence = `origin` is not that word — NOT an assertion that the rule store
+            is healthy.
     ApprovalRequestFrame:
       type: object
       description: >
@@ -11538,6 +11895,9 @@ components:
             server >= 7.69.0 (core 7.10.0 #616), ADDITIVE — WHY this ask reached a human. Frame and card carry
             the SAME value (one narrow-read function server-side). See ClassifierUnavailable for the open-`cause`
             rule and the three shapes absence covers.
+            RETIRED: server >= 7.72.0 (core 7.14.0 #688) never mints this key on any of the three faces; its
+            successor is `disposition.cause` on the gate record (`unavailable` / `parse_error` — a different
+            question, so an old switch does not port). Kept for servers in [7.69.0, 7.72.0) only (sdk 9.2.0).
 
     RuleSuggestion:
       type: object

package/package.json

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