@sema-agent/sdk 6.13.0 → 6.14.0

package/openapi.yaml

@@ -4084,6 +4084,140 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
 
+  # ── design/203 §2(server 7.12.0)—— 持久权限规则的**撤销面**两口。与上面的导入两口共用部署谓词
+  # (PERMISSION_RULES_ENABLED + 规则店装配,缺一 ⇒ 501),但多一条 operator 越权域:`principal` 让一个
+  # 列了名的 operator 读或收回**任一租户**的规则。方向决定授权 —— 收回是 TIGHTENING(core removePersistedRule
+  # 头注逐字:a host may narrow on a user's behalf, it may not widen),而回收权限正是撤销面的本义。
+  # 🔴 路径**没有 :id 段**:一条规则的身份就是它的 (rule, scope) 内容对,服务端不铸行 id,所以删是按内容删。
+  /v1/rules:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [rules]
+      operationId: rulesList
+      x-status: gated            # server routes/rules.ts handleRuleList;同 cc-import 的部署谓词。SDK rules.list() 消费。
+      summary: List the rules that are LIVE under a principal (keyset-paged, cursor bound to the revision).
+      description: >
+        List the persisted allow rules currently live under one principal (tombstones already folded).
+        Ordering is deterministic — `(scope, rule)` lexicographic — because keyset paging's whole premise is
+        that the same data comes back in the same order every time. The order is decided by the server, NOT
+        by the store (core's `list()` promises none).
+
+        🔴 THE CURSOR IS BOUND TO `(rev, principal, scope)` AND A MISMATCH IS REFUSED, NOT RESET. A rule set
+        is read WHOLE, so there is no tearing WITHIN a page — tearing happens BETWEEN pages, when somebody
+        adds or removes a rule after page 1 and the keyset start now lands in a different set (silently
+        dropped or duplicated rows). Sending a cursor minted at another revision / principal / scope filter
+        gets a 400 (`request.query_invalid`, body carries the current `rev`); restart the listing without a
+        cursor. Silently starting over would let a client read page 2 as "continuing page 1" and hand a
+        governance surface a list that is both short and duplicated, with nobody the wiser.
+
+        `scope` FILTER: given but unreadable ⇒ 400, never "treated as unfiltered" — that would silently turn
+        "show me only this project" into a full listing the caller would accept as the project's list.
+        `limit` is CLAMPED (not refused) into 1..200, default 50 — a mistyped paging knob must not make a
+        governance page unopenable.
+
+        OPERATOR OVERRIDE: `principal` reads ANOTHER tenant's rules and is `OPERATOR_PRINCIPALS`-gated
+        (an EMPTY list means NOBODY — never inferred from the service token, which is a shared deployment
+        credential, not a person). Omitted, or equal to your own principal, is the ordinary self-read and
+        needs no operator standing.
+      parameters:
+        - name: principal
+          in: query
+          required: false
+          schema: { type: string, minLength: 1, maxLength: 190 }
+          description: >
+            OPERATOR-ONLY cross-tenant read. Absent (or equal to the caller's own principal) = read your own
+            rules. Anything else requires explicit OPERATOR_PRINCIPALS membership ⇒ otherwise 403
+            `auth.operator_only`. Rule text contains command shapes, so third-party reads are an information
+            disclosure and are deliberately not opened to non-operators.
+        - name: scope
+          in: query
+          required: false
+          schema: { type: string, minLength: 1 }
+          description: >
+            Filter to one scope, spelled `global` or `project:<root>` with a NON-EMPTY root. Unreadable ⇒ 400
+            `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
+            equivalent-but-differently-spelled root filters to an empty page.
+        - name: limit
+          in: query
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
+          description: 'Page size. CLAMPED into 1..200 (non-numeric / out-of-range is clamped, not refused); default 50.'
+        - name: cursor
+          in: query
+          required: false
+          schema: { type: string }
+          description: >
+            The `nextCursor` from the previous page, VERBATIM (base64url, opaque — do not parse or mint one).
+            It is bound to the revision, the principal and the scope filter it was minted on; any mismatch is
+            a 400 `request.query_invalid` carrying the current `rev`. Restart the listing without a cursor.
+      responses:
+        '200':
+          description: One page of live rules plus the store revision the page was read at.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RuleListResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.query_invalid — unreadable `scope`, unreadable `cursor`, or a cursor minted at a different (rev, principal, scope). Body carries `rev` on the revision-mismatch arm.
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — reading another principal's rules without explicit OPERATOR_PRINCIPALS membership (an EMPTY list means nobody)
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required — this deployment has no permission-rule store wired
+    delete:
+      tags: [rules]
+      operationId: rulesRevoke
+      x-status: gated            # server routes/rules.ts handleRuleRevoke;同 cc-import 的部署谓词。SDK rules.revoke() 消费。
+      summary: Revoke a persisted rule BY CONTENT — `(rule, scope)`, with no id in the path.
+      description: >
+        Revoke one persisted allow rule identified by its CONTENT pair `(rule, scope)`. There is no `:id`
+        path segment on purpose: a rule's identity IS that pair, the server mints no row id, and the engine's
+        `removePersistedRule` primitive (which this endpoint always goes through) works in observed-remove
+        form over the add dots.
+
+        🔴 IDEMPOTENT, AND DELIBERATELY NOT A 404. Revoking twice, or revoking something that was never
+        there, is `200 {status:"no-op"}` — a "did this rule ever exist?" 404 would be an existence oracle
+        (a CROSS-TENANT one under the operator override), and deletion has no business answering that
+        question. Read `status` to learn whether you removed anything.
+
+        🔴 `stillLive` IS LOAD-BEARING ON BOTH ARMS. `true` means the tombstone landed but the rule is
+        STILL live under add-wins — a fresh approval was recorded during the call. Folding that into a plain
+        200 would let a client read an INCOMPLETE revocation as complete, which is precisely what a
+        governance surface must never get wrong. The `no-op` arm carries it for the same reason: the engine
+        answers `no-op` off its initial snapshot without a read-back, so an approval landing in that window
+        leaves the rule alive while the verb says "nothing to remove". Both arms therefore ship the same key
+        set and one consumer branch reads both.
+
+        OPERATOR OVERRIDE: `principal` revokes on ANOTHER tenant's behalf, gated exactly like the read half
+        (explicit `OPERATOR_PRINCIPALS`; empty list = nobody). The direction is what makes the override
+        legitimate — revoking is TIGHTENING — but the identity test does not relax because of it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RuleRevokeRequest' }
+      responses:
+        '200':
+          description: >
+            The revocation outcome. `removed` = a tombstone was written; `no-op` = nothing matched (idempotent
+            repeat, or it was never there). BOTH arms carry `stillLive` — read it before telling a human the
+            rule is gone.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RuleRevokeResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {rule, scope, principal?}, or `scope` is not `global`/`project:<non-empty root>`
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — revoking another principal's rule without explicit OPERATOR_PRINCIPALS membership
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '503':
+          description: >
+            errorCode `state.rule_remove_failed` — the engine could not complete the removal right now. Core's
+            contract for this arm is "a read-back confirmed nothing was written, OR the read-back itself failed
+            and the outcome is undetermined" — both are RETRY-CAN-CHANGE-IT, which is why it is a 503 and not a
+            500. Retry, then reconcile with `GET /v1/rules`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
+
   # ── design/183 —— 身份收编面(form b:纯身份重绑)。operator-only 的一次性部署级动作,零模型工作。 ──
   /v1/adoption:
     parameters:
@@ -4820,6 +4954,35 @@ components:
           items: { $ref: '#/components/schemas/TaskAgentDefinition' }
           description: Per-task sub-agent definitions (roster additions scoped to this task only).
         interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
+        oneShot:
+          type: boolean
+          description: >
+            core >=5.23.0 `TaskSpec.oneShot`, server >=7.12.0 — declare that THIS SUBMISSION is one-shot: no
+            later turn exists in which an asynchronous background notification could land. The archetype is a
+            headless `sema -p` whose process exits when the turn ends.
+
+            🔴 IT GRANTS NOTHING AND GUARANTEES NOTHING — core consumes it as GUIDANCE ONLY. What changes is
+            the wording the engine gives the MODEL for `RunWorkflow` / delegation receipts: "end your turn, you
+            will be notified" (correct only when a next turn exists) becomes "block-wait via
+            `TaskOutput({block:true})`". Omitting it on a headless call is a known way to LOSE background
+            results — that is why the key exists — but sending it is **best-effort**, not a completion
+            contract: the model may ignore the instruction or run out of budget, and some legs have no poll
+            path at all. If your caller REQUIRES the results, keep your own wait/reconcile step; do not treat
+            `oneShot: true` as one. There is no tenancy gate because there is no capability to gate.
+
+            🔴 PROBE `capabilities.oneShot` BEFORE SENDING IT: the task body is an OPEN set (the server does
+            not refuse unknown keys), so a worker that does not yet consume this field accepts `oneShot: true`,
+            answers 200, and still tells the model to end its turn and await a notification the process will
+            never receive — no 400, no warning. The capability bit (server >=7.12.0) is what distinguishes the
+            two; ABSENT means the key is being ignored. Note the bit being PRESENT does not retire the
+            caller-side wait step: it proves the key is consumed, not that the results arrive.
+
+            PER-REQUEST on purpose: "does this submission expect to be continued" is a property of the
+            SUBMISSION, not of the connection it arrived on. Sibling of `interactiveTools` (the same `-p`
+            posture) and passed through identically — a boolean rides, ABSENT ⇒ the key is omitted and core's
+            default (interactive) applies. Anything that is neither absent nor a boolean is a fail-loud 400
+            `request.field_invalid` ("oneShot must be a boolean"), NOT a silent coercion. Rides the persisted
+            body onto resume legs.
         retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
         forwardSubagentEvents:
           type: boolean
@@ -5294,6 +5457,20 @@ components:
               input: { description: tool-call — redacted args. }
               callId: { type: string }
               isError: { type: boolean }
+              # 🔴 core >=5.18.1 (#187) —— 与 `Event_tool_end.settledBy` **同一个值**:server 的共享挑键器
+              # `toolResultFieldsOf`(src/trace/project.ts)同时喂 turns 面与 trace SSE 面,而写侧
+              # `toolEndEventData` 喂 durable 账本 —— 三面一个真源,所以这里的词表与那边逐字相同。
+              settledBy:
+                type: string
+                enum: [human, timeout, aborted]
+                description: >
+                  tool-result — HOW this call was settled when it went through an approval: `human` = somebody
+                  actually answered; `timeout` = the approval window elapsed; `aborted` = abort / unclonable
+                  arguments / out-of-contract. Present ONLY on the settled call.
+                  ABSENCE CARRIES NO SEMANTICS (an older worker, or a posture arm that deliberately leaves it
+                  unset — the two are indistinguishable), so absent is neither "human" nor "no approval
+                  happened". The read leg re-validates the closed set independently of the write leg, because a
+                  ledger row can come from any engine generation.
         tokens:
           type: object
           properties:
@@ -5558,9 +5735,60 @@ components:
         permissionRules:
           type: boolean
           description: >
-            The permission-rule lane (/v1/rules/cc-import/* plus the respond persistRule redemption arm)
-            is available. Server predicate = PERMISSION_RULES_ENABLED=true AND the rule store is wired
-            (default OFF => false; the revocation face is a prerequisite for enabling).
+            The permission-rule lane is available: /v1/rules/cc-import/* , the respond persistRule redemption
+            arm, and (from server 7.12.0) the GET/DELETE /v1/rules revocation face. Server predicate =
+            PERMISSION_RULES_ENABLED AND a wired rule store — the SAME predicate behind every one of those
+            endpoints' 501s, so "says yes" means all of the ones this server has actually work.
+            🔴 THE KNOB'S DEFAULT READS IN TWO SEGMENTS: default OFF (opt-in) on server <= 7.11.0, default ON
+            (opt-out) from 7.12.0, where the revocation face — the prerequisite that kept it opt-in — landed.
+            So "the operator said nothing" means OPPOSITE things across that boundary; only an explicit
+            `false` disables it. Read THIS BIT; never infer the lane's state from a knob default or a
+            version number.
+        permissionRulesRevoke:
+          type: boolean
+          description: >
+            server >=7.12.0 — the rule REVOCATION face (GET + DELETE /v1/rules) is ROUTED on this worker.
+            Same deps predicate as `permissionRules`; what carries the extra information is this key's mere
+            PRESENCE. 🔴 That is the whole point of it being a second bit rather than a tightening of the
+            first: on a <=7.11.0 worker `permissionRules` already answers true while these two routes 404, so
+            that bit cannot distinguish "the lane is off" from "this build predates the face", and its
+            published wording ("all four endpoints work") is already untrue there — you can add a bit, you
+            cannot retroactively change one. ABSENT => an older worker: expect 404 `not_found.route` from
+            `rules.list` / `rules.revoke` and hide the governance affordance. PRESENT => the routes exist
+            (whether they then answer depends on `permissionRules`, as always).
+        modeShellGateTranslation:
+          type: boolean
+          description: >
+            design/201 §3 (server >=7.12.0) — this binary CONTAINS the `permissionMode` -> `spec.shellGate`
+            translation table (bypassPermissions => off; auto/default/acceptEdits/plan => classify; no stated
+            mode => the key is not written). HARD-CODED true and landed in the SAME COMMIT as the table, so
+            "says yes <=> the translation is really there" is structural, not deps-derived — no missing
+            dependency can make it false.
+            🔴 THE PROBE MUST BE THIS BIT ON THE SERVER YOU ARE TALKING TO, NEVER YOUR OWN SHELL VERSION. A
+            shell drops its unconditional `MANUAL_MODE_SHELL_GATE` env injection on the strength of this bit;
+            keyed off the shell's own version instead, the three real deployments — new shell against an old
+            server, a replica rolled back to an older binary, a mixed-version fleet — each open a window where
+            the shell has stopped injecting and the server cannot yet translate. Absent/false ⇒ keep injecting.
+        oneShot:
+          type: boolean
+          description: >
+            server >=7.12.0 — this worker actually CONSUMES `TaskRequest.oneShot` (projects it into `TaskSpec`
+            when it is a boolean, omits the key when absent, and 400s a non-boolean). Hard-coded true: the
+            consumption depends on no optional facility. 🔴 PROBE IT BEFORE RELYING ON THE FIELD: the task
+            request body is an OPEN set, so a worker that does not consume the key still accepts it and
+            answers 200 — a headless caller would declare itself one-shot, never receive core's block-wait
+            guidance, and lose its background results with nothing on the wire to reveal it. ABSENT => the key
+            is being ignored; keep your own wait/reconcile step. (That step remains good practice even when
+            the bit is present: the field is guidance to the model, not a completion contract.)
+        outcomeLedger:
+          type: boolean
+          description: >
+            server >=7.12.0 — the `GET /v1/outcomes` mechanical-signal read aggregate (design/73 §7.2) is
+            available. Predicate mirrors the route's refusal arms exactly: a QUERYABLE ledger is wired (a
+            file-only sink writes JSONL and has no query face ⇒ 501), AND on a multi-tenant deployment the
+            operator list is non-empty (single-user has no such gate — the only user IS the operator).
+            Added because this face previously had a 501 but NO capability bit, leaving consumers to
+            trial-by-501 — the exact pattern this capability surface exists to remove.
         sharedMemory:
           type: boolean
           description: >
@@ -8134,8 +8362,35 @@ components:
             redeem it. The engine ALWAYS emits the section, so `false` is a REAL reading ("no rule lane on this
             worker"), NOT "this engine is too old". The section is optional HERE only because this spec's support
             floor is server 3.0.0, which predates it; absent = the worker never sent it.
+
+            🔴 `syncWired` / `orgGoverned` (core >=5.23.0 design/182 §9/§7, server >=7.12.0) sit in THIS
+            section — the engine deliberately did not put them in the operator-only `governance` section, and
+            the server projects all three bits on both faces. THEY WERE THE REASON THIS SECTION HAD TO BE
+            REDECLARED: this arm is `additionalProperties: false`, so a strict consumer validating a real
+            frame against the 6.13.0 spec did not "miss two fields" — the WHOLE SECTION failed validation and
+            the diagnostics surface went unreadable. Same failure family as `errorCode` on `Event_tool_end`.
           properties:
             storeWired: { type: boolean }
+            syncWired:
+              type: boolean
+              description: >
+                core >=5.23.0 (design/182 §9) — this worker merges persisted rules into the SAME consent trust
+                domain as its cross-device / transport / server-side peers. Read with `storeWired` to answer
+                "how far does this 'don't ask again' actually travel?": the same click means something wider
+                here than on a worker that keeps its rules local.
+                🔴 PRESENT-AND-FALSE IS A REAL READING — "this engine has the concept, this deployment has not
+                wired it" — NOT "too old to know". Absent (the whole key missing) is the only "did not send it"
+                signal. On server 7.12.0 this is honestly `false` everywhere: the seam exists in core, the
+                server has not wired a supplier yet.
+            orgGoverned:
+              type: boolean
+              description: >
+                core >=5.23.0 (design/182 §7) — an ORGANIZATION governance layer is armed over this rule lane.
+                Load-bearing consequence: that layer is FAIL-CLOSED, so when the org snapshot cannot be read,
+                EVERY allow is escalated into a real human approval rather than quietly honored. A shell that
+                renders "don't ask again" without reading this bit is advertising an outcome it cannot promise.
+                🔴 Same three-way reading as `syncWired`: present-and-false = concept known, not armed here;
+                absent = the worker never sent the key. Honestly `false` on server 7.12.0.
         governance:
           type: object
           additionalProperties: false
@@ -8753,6 +9008,16 @@ components:
         `rule_not_offered` — the echoed text is not among THIS ask's candidates (a stale card, or someone
         trying to mint a rule of their own).
         `rule_store_error` — the rule store wobbled. The adjudication is unaffected.
+        `rule_governance_forced` (server >=7.12.0, #204) — the gate on THIS ask came from the deployment's
+        operator governance layer, so the ask never entered the rule lane at all.
+        🔴 SPLIT FROM `rule_lane_unavailable` ON PURPOSE: that one is "one of four conjuncts failed" (no rule
+        store, no candidate, unreadable command bytes, no verified owner — two of which are per-CARD limits),
+        this one is "the lane is perfectly healthy, only THIS ask is operator-governed". Folding them would
+        erase a real distinction on the card.
+        ⚠️ NEITHER IS A DEPLOYMENT-LEVEL VERDICT. Every member of this enum describes ONE ask's outcome; the
+        note on `rule_lane_unavailable` above already says never to disable the feature globally on it, and
+        the same holds here. The one correct source for "does this worker serve rules at all" is
+        `capabilities.permissionRules`. Keep offering "don't ask again" on the next ask; just not on this one.
       enum:
         - no-candidates
         - unknown-candidate
@@ -8762,6 +9027,7 @@ components:
         - rule_input_edited
         - rule_not_offered
         - rule_store_error
+        - rule_governance_forced
 
     ApprovalRiskAxes:
       type: object
@@ -10520,6 +10786,138 @@ components:
       properties:
         result: { $ref: '#/components/schemas/CcImportResult' }
 
+    # ── design/203 §2 撤销面(server 7.12.0)—— 列举行 + 两口的 200 体 ────────────────────────────────
+    # 行形逐字段照 server `src/rules-consent.ts` 的 `PersistedRuleWireRow`(它自己逐字段照 core 的
+    # `PersistedAllowRule`,只把 `scope` 换成判别式串)。
+
+    RuleDot:
+      type: object
+      description: >
+        The immutable causal identity of ONE add — a replica identity plus a monotonic counter (core
+        `RuleDot`). Compared by IDENTITY, never by causal order: single dots minted on different replicas
+        have no order to compare. Treat it as an opaque pair; it is not a timestamp and not a sort key.
+      additionalProperties: false
+      required: [actor, counter]
+      properties:
+        actor: { type: string, description: 'The replica identity that minted this add.' }
+        counter: { type: integer, description: 'That replica''s monotonic counter at mint time. Monotonic PER ACTOR only — never comparable across actors.' }
+
+    RuleAddOrigin:
+      type: string
+      description: >
+        Where ONE add came from (core `RuleAddOrigin`). Stored PER ADD and never folded across dots — a
+        folded provenance could not follow a dot that is later deleted on its own.
+        `user` = minted from an approval card ("don't ask again"); `imported-cc` = redeemed through the
+        CC-settings import lane; `starter` = a deployment-seeded rule.
+        Closed vocabulary on the wire; read it with a default arm anyway (the owner is the engine).
+      enum: [user, imported-cc, starter]
+
+    RuleAdd:
+      type: object
+      description: >
+        ONE add of one logical rule, carrying its own dot and its own provenance (core `RuleAdd`). A rule is
+        LIVE iff at least one of its adds survives the tombstones, which is why this is a SET and not a
+        scalar: the same `(rule, scope)` can be approved several times, from different origins, at different
+        moments. Folding it to a single "addedAt" would make "did I import this or click it?" unanswerable on
+        a governance surface — which is the one place it matters.
+      additionalProperties: false
+      required: [dot, origin, createdAt]
+      properties:
+        dot: { $ref: '#/components/schemas/RuleDot' }
+        origin: { $ref: '#/components/schemas/RuleAddOrigin' }
+        createdAt: { type: string, description: 'When this ADD was recorded (engine-stamped ISO-8601). It dates the add, NOT the rule — a rule with several adds has several of these.' }
+
+    PersistedRule:
+      type: object
+      description: >
+        One LIVE persisted allow rule as `GET /v1/rules` puts it on the wire (server `PersistedRuleWireRow`).
+        Tombstones are already folded — every row here is live at `RuleListResult.rev`.
+        🔴 `scope` is the DISCRIMINANT STRING (`global` / `project:<root>`), NOT the `RuleScope` object the
+        import lane speaks: this is the exact byte sequence the revoke body wants back, so echo it VERBATIM
+        rather than re-serializing a parsed form (an equivalent-but-differently-spelled root matches nothing).
+        The rule lane is ALLOW-only; deny/ask rules are the tightening direction and never appear here.
+      additionalProperties: false
+      required: [rule, scope, tool, match, command, adds]
+      properties:
+        rule: { type: string, description: 'Canonical rule text — `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). Pass back VERBATIM to revoke.' }
+        scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` with a NON-EMPTY root. Pass back VERBATIM to revoke.' }
+        tool: { type: string, enum: [Bash], description: 'The one tool the v1 rule lane speaks for. The field exists so a later version can widen without a shape change — read it, do not assume it.' }
+        match:
+          type: string
+          enum: [exact, prefix]
+          description: '`exact` = this one command only; `prefix` = word-boundary prefix. (core reserves a `wildcard` form for v2 that no current version produces.)'
+        command: { type: string, description: 'What the matcher actually compares against, parsed out of `rule` at mint time and stored so no consumer re-parses. Trust this + `match`, not your own parse of `rule`.' }
+        adds:
+          type: array
+          description: 'Every LIVE add of this rule (see RuleAdd — a real set, deliberately not folded).'
+          items: { $ref: '#/components/schemas/RuleAdd' }
+
+    RuleListResult:
+      type: object
+      description: >
+        The 200 body of `rulesList` — one keyset page plus the revision it was read at.
+        `nextCursor` ABSENT = this was the last page (there is no empty-string sentinel). `rev` is the rule
+        bucket's OCC revision; the cursor is bound to it, so a page fetched with a stale cursor is REFUSED
+        rather than silently restarted.
+      additionalProperties: false
+      required: [rules, rev]
+      properties:
+        rules:
+          type: array
+          description: 'Live rules, ordered `(scope, rule)` lexicographic — a server-decided deterministic order, since keyset paging depends on it.'
+          items: { $ref: '#/components/schemas/PersistedRule' }
+        rev: { type: integer, description: 'The rule bucket''s OCC revision at read time. Bucket-LOCAL: two tenants each holding one rule both read `rev: 1`, so it is not a global clock and not comparable across principals.' }
+        nextCursor: { type: string, description: 'Opaque base64url cursor for the next page. ABSENT ⇒ no further pages. Pass back VERBATIM; do not parse or mint one.' }
+
+    RuleRevokeRequest:
+      type: object
+      description: >
+        The `DELETE /v1/rules` body. A rule is addressed BY CONTENT — there is no id anywhere in this face.
+        Echo `rule` and `scope` VERBATIM from the listing: both are compared as opaque bytes, so an
+        equivalent-but-differently-spelled scope root simply matches nothing (and answers a cheerful `no-op`).
+      # 封闭:server 侧 zod 是 `.strict()` —— 把 `scope` 拼成 `scopes` 的客户端应当场知道,而不是
+      # 拿到一个「删掉了 global 那条」的意外结果。
+      additionalProperties: false
+      required: [rule, scope]
+      properties:
+        rule: { type: string, minLength: 1, maxLength: 1024, description: 'The canonical rule text, VERBATIM as `RuleListResult.rules[].rule` gave it.' }
+        scope: { type: string, minLength: 1, maxLength: 1088, description: 'The scope discriminant string — `global` or `project:<root>` with a NON-EMPTY root (an empty root would match every cwd). VERBATIM as the listing gave it.' }
+        principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant revoke. Absent (or your own principal) = revoke your own rule.' }
+
+    RuleRevokeResult:
+      type: object
+      description: >
+        The 200 body of `rulesRevoke`. `removed` = a tombstone was written; `no-op` = nothing matched (an
+        idempotent repeat, or it was never there — deliberately NOT a 404, which would be an existence
+        oracle). BOTH arms carry `stillLive`, and the key set is identical on purpose so one consumer branch
+        reads both.
+      additionalProperties: false
+      required: [status, rev, stillLive]
+      properties:
+        status:
+          type: string
+          enum: [removed, "no-op"]
+          description: 'Whether this call wrote a tombstone. `no-op` says nothing about whether the rule EVER existed — do not render it as "not found".'
+        rev: { type: integer, description: 'The rule bucket''s OCC revision after the operation.' }
+        stillLive:
+          type: boolean
+          description: >
+            🔴 `true` = the rule is STILL LIVE despite this call — under add-wins, an approval recorded during
+            the operation keeps it alive. NEVER tell a human "the rule is gone" without reading this. It rides
+            the `no-op` arm too, because the engine answers `no-op` off its initial snapshot with no read-back,
+            so a concurrent approval leaves the rule alive while the verb reports nothing to remove.
+
+            🔴 THE TWO TRUTH VALUES ARE NOT EQUALLY STRONG, AND THE ASYMMETRY IS IN THE ENGINE, NOT HERE.
+            `true` is positive evidence: something was observed alive. `false` is only "no evidence it
+            survived" — on the `removed` arm the engine performs the confirming read-back inside a `catch`
+            that swallows a failure and reports `false` (core `removePersistedRule`), so a degraded store
+            yields a byte-identical `{status:"removed", stillLive:false}` to a genuinely verified removal.
+            The `no-op` arm does NOT share that hole: the server does that read-back itself and lets a failure
+            surface as a 500 rather than invent an answer. So: act on `true`; when it MATTERS that a rule is
+            really gone (an operator revoking a standing allow), confirm with `GET /v1/rules` instead of
+            treating `false` as proof. Registered upstream — an indeterminate outcome should be its own state
+            rather than folding into `false`.
+
     # ═══════════════════════════════════════════════════════════════════════════════════════════════
     # design/183 —— 身份收编(form b:纯身份重绑)。形逐字段照 server `src/adoption/wire.ts` 的 zod
     # (那份 schema 自陈是「跨仓 wire 契约,下游按字段名逐字钉围栏」)。

package/package.json

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