@sema-agent/sdk 8.2.0 → 8.3.0

package/openapi.yaml

@@ -1453,7 +1453,7 @@ paths:
                 required: [sessionId, leafId]
                 properties:
                   sessionId: { type: string }
-                  leafId: { type: string, nullable: true, description: "null = session exists but has no entries yet." }
+                  leafId: { type: ["string", "null"], description: "null = session exists but has no entries yet." }
         '304': { description: 'Leaf unchanged since the presented ETag (no body).' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -6684,6 +6684,217 @@ components:
             and the history PULL answers the no-oracle 404 `not_found.blob`, while the REST of the sync
             surface keeps working.
 
+        # ─── S-139(sdk 8.3.0):对 server 7.60.0 的整体重对账补齐的 19 位 ───────────────────────
+        # 行号 = server 7.60.0 树的 `src/http/routes/capabilities.ts`。语义与谓词的全文在
+        # `packages/sdk/src/types.ts` 的 `Capabilities` 同名成员上(逐条亲读 server 源码转述);
+        # 这里只留 codegen 需要的形与一句定性。机械对账门 = `test/server-keyset-parity.test.ts`。
+        deviceExecutor:
+          description: >
+            device lane (capabilities.ts:162). Object OR `false` — same tri-state family as `fleet`.
+            Predicate = `deps.deviceHub` present, byte-identical to the `GET /v1/device/ws` upgrade
+            handler's mount condition. `wsPath` is deliberately on the wire (hard-coding it downstream
+            would turn a path change into a cross-repo breaking change). Device COUNT / online state are
+            deliberately NOT advertised (that is the `/v1/devices/*` admin face).
+          oneOf:
+            - type: boolean
+              enum: [false]
+            - type: object
+              required: [enabled, protocolVersion, maxInflightPerDevice, wsPath]
+              additionalProperties: true
+              properties:
+                enabled: { type: boolean, enum: [true] }
+                protocolVersion: { type: integer }
+                maxInflightPerDevice: { type: integer }
+                wsPath: { type: string }
+        memoryEngine:
+          description: >
+            Memory ENGINE posture (capabilities.ts:210 = `projectMemoryEngineCapability`). Object = the
+            memory face is really lit, `false` = dark. NOT the same thing as `memory`/`memoryWrite` (those
+            advertise the RETIRED MemoryStore HTTP verbs and stay false forever) — the engine has NO HTTP
+            verbs, so a true here does NOT mean there are memory read/write endpoints to call.
+            `vectorMode: null` = this leg has no rung indicator (the `file` engine), NOT "the rung is null".
+          oneOf:
+            - type: boolean
+              enum: [false]
+            - type: object
+              required: [backend, vectorMode]
+              additionalProperties: true
+              properties:
+                backend: { type: string, enum: [file, pg, tidb] }
+                # 🔴 openapi **3.1**:可空用 `type: [T, "null"]`,`nullable` 不是 3.1 关键字(会被静默忽略)。
+                # `null` 也必须进 enum,否则真校验器把 file 引擎的常态答判非法。
+                vectorMode: { type: ["string", "null"], enum: [native, portable, lexical, null] }
+        sql:
+          type: ["object", "null"]
+          additionalProperties: true
+          description: >
+            This deployment's SQL transaction read semantics (capabilities.ts:216 =
+            `projectSqlEngineCapability`), read back AFTER connection initialization set it — same source as
+            the operator `GET /v1/diagnostics/wiring` `sqlEngine` section. `null` = NO SQL backend here
+            (env-only worker / local file backend), NOT "could not read it". `txnMode: null` = this engine
+            has no such indicator, NOT "optimistic".
+          required: [engine, isolation, txnMode]
+          properties:
+            engine: { type: string, enum: [tidb, innodb, pg] }
+            isolation: { type: string }
+            txnMode: { type: ["string", "null"], enum: [pessimistic, null] }
+        sessionBackgroundable:
+          type: boolean
+          description: >
+            The REMOTE lane can detach (capabilities.ts:233 = `Boolean(deps.runStore)`): `POST
+            /v1/tasks/stream` with `x-detach-on-disconnect: true` survives client disconnect; come back via
+            the `X-Task-Id` response header and `GET /v1/runs/{id}` + `/events`. Deployment half only — the
+            per-request half (caller must pass `sessionId`) is not in this bit. Scope is the REMOTE lane;
+            never repurpose it to disable local backgrounding.
+        runMemoryCaptureOptOut:
+          type: boolean
+          description: >
+            `POST /v1/runs/{id}/memory/capture-optout` mid-run flip verb is present (capabilities.ts:237 =
+            `Boolean(deps.runStore)`). Absent ⇒ do not render the affordance. True only promises the
+            ENDPOINT exists, not that THIS run is live (non-live ⇒ 409 with a signposting body).
+        memoryBundle:
+          type: boolean
+          description: >
+            Governance carry-out bundle pair `POST /v1/memory/{export,import}` (operator lane) —
+            capabilities.ts:261, two conjuncts: both engine seams wired AND `operatorPrincipals` NON-EMPTY
+            (an empty roster makes those routes 403 for every identity). True does not promise the backend
+            has the bundle composite face (core then refuses loudly with `memory.export_incomplete`).
+        memoryCompliance:
+          type: boolean
+          description: >
+            Provenance / erasure compliance pair `GET /v1/memory/entries/{entryId}/provenance` and
+            `POST /v1/memory/erase` (operator lane) — capabilities.ts:273, same two-conjunct family as
+            `memoryBundle`. Deliberately NOT the same source as `memoryBundle` (a deployment can have the
+            bundle composite face without control-plane ownership, and vice versa).
+        memoryOrigin:
+          type: boolean
+          description: >
+            External-origin marking face (three routes under `/v1/memory/origin/*`, operator lane) —
+            capabilities.ts:287, same two-conjunct family. Same predicate as `memoryCompliance` TODAY but a
+            deliberately separate bit (two products; a deployment may want only one). True does not promise
+            the `GET …/external` answer is complete — there is no scope enumeration face, so an empty answer
+            must never be read as "the store is clean".
+        memoryConsolidationDriver:
+          type: boolean
+          description: >
+            Consolidation valve pair (`POST /v1/admin/memory/consolidation/run`, `GET
+            /v1/admin/memory/consolidation`, operator lane) — capabilities.ts:301. FALSE ⇒ those routes are
+            **404** (whole domain unmounted), NOT 501: do not branch on 501 here. Contrast
+            `memoryOptOutGrant`, whose false arm IS a 501.
+        memoryOptOutGrant:
+          type: boolean
+          description: >
+            memory-capture opt-out GRANT table admin (four routes under `/v1/admin/memory-optout`,
+            operator-only) — capabilities.ts:307. FALSE ⇒ **501** `capability.memory_optout_grant_required`
+            (change the deployment shape), as opposed to `memoryConsolidationDriver`'s 404 (turn the knob on).
+        permissionModeAuto:
+          type: object
+          additionalProperties: true
+          description: >
+            Default-state disclosure for `permissionMode: "auto"` (capabilities.ts:463; adjudicated by
+            `src/auto-mode-face.ts`). The parts are deliberately NOT folded into one boolean — "this binary
+            does not know auto" and "it knows auto but this box has no entitlement source" would collapse to
+            the same false, and a shell must do different things for those. `reason` is present ONLY when
+            `armed` is false; read its vocabulary as an OPEN set (server already grew it from four words to
+            six). `model` is omitted when the classifier route cannot be resolved (the server logs the
+            engine's refusal rather than 500-ing the read face). `?permissionMode=<five words>` folds the
+            caller's INTENT into the verdict; anything outside the five words is a 400
+            `request.field_invalid`.
+          # 🔴 required 只有**三位**:武装三键(intentArming / armed / reason)是 server >= 7.57.0 (S-80)
+          # 才有的,而本包的支持地板是 3.0.0 => every 7.x <= 7.56.0 server is inside the promised face and
+          # emits ONLY these three (verified verbatim against server tags v7.50.0 / v7.56.0). Requiring the
+          # arming triple would make a SUPPORTED server's legitimate response invalid.
+          required: [accepted, classifierSeat, entitlementSource]
+          properties:
+            accepted: { type: boolean, enum: [true] }
+            classifierSeat: { type: boolean }
+            entitlementSource: { type: boolean }
+            intentArming: { type: boolean, description: 'server >= 7.57.0 only. ABSENT together with `armed`/`reason` on <= 7.56.0.' }
+            armed:
+              type: boolean
+              description: >
+                server >= 7.57.0 only. Read as THREE states, not two: true = will arm; false = will not, and
+                `reason` is then present; ABSENT = an older server that does not report arming at all — never
+                fold that absence into false (it would render a 7.50 box that IS arming as "auto == default").
+            reason:
+              type: string
+              enum: [mode_not_auto, deployment_incapable, org_denied, local_denied, settings_denied, resolver_fault]
+            model: { type: string }
+        readFace:
+          type: ["string", "null"]
+          enum: [open, roots, null]
+          description: >
+            The EFFECTIVE READ containment rung this deployment explicitly declared (capabilities.ts:484 =
+            `deps.config.readFace ?? null`; env `READ_FACE` or config-center's `readFace.face` — same config
+            key, so this bit does not distinguish org-pushed from local). `null` = this deployment pinned
+            NOTHING and the engine default takes over; the server deliberately does NOT fold `null` into
+            `roots` (copying an upstream default onto the wire becomes a lie the day core changes it).
+            Minimal disclosure — the deny table itself is never on the capability face. There is NO
+            per-request `readFace` field on TaskRequest.
+        callerCwd:
+          type: boolean
+          description: >
+            Whether a caller-supplied `cwd` is actually HONORED (capabilities.ts:541 =
+            `cwdHonored(config) || deviceCwdHonored(config)`) — single-user `host` lane OR the `device` lane.
+            Byte-identical predicate to the submit-side gate in `boot/resolve-spec.ts`. Prefer this bit;
+            when absent (older worker) fall back to `projectContext` — that is the verbatim pre-bit behavior.
+        a2a:
+          type: boolean
+          description: >
+            The A2A CLIENT read face `GET /v1/sessions/{id}/a2a` exists (capabilities.ts:555, unconditional
+            `true` — like `mcp`): with no peers configured it returns an honest empty panel, so there is no
+            501 path to gate on. Deliberately a DIFFERENT predicate from `a2aInjection`.
+        a2aInjection:
+          type: boolean
+          description: >
+            This deployment HONORS a caller-supplied `body.a2aPeers` (capabilities.ts:556 =
+            `a2aInjectionHonored(config)`; three vetoes owned by `task-a2a.ts`: single-user AND `a2a`
+            unlocked AND compliance permits). FALSE is a FIELD gate, not a 4xx: the request still 200s and
+            the field is warned + ignored — EXCEPT under a config lock, where submit refuses 400
+            `config.locked_key`.
+        a2aServe:
+          type: boolean
+          description: >
+            Server-as-peer knob (capabilities.ts:564 = `config.a2aServe !== undefined`): true ⟺
+            `GET /.well-known/agent-card.json` and `POST /v1/a2a` exist; false ⟺ both 404. Scope is ROUTE
+            EXISTENCE, not "every method runs" — `message/send` / `tasks/get` additionally need a durable run
+            store (without it they answer a named JSON-RPC `-32004`).
+        agentRoster:
+          type: boolean
+          description: >
+            `GET /v1/agents/roster` background-agent roster read face (capabilities.ts:640 =
+            `Boolean(deps.backgroundAgentStore)`, byte-identical to that route's 501 gate). Scope is the
+            ENUMERATION face (content-free projection); subagent OUTPUT bodies go through
+            `/v1/runs/{id}/subagents/{handle}/output`, gated by `subagentOutput`.
+        retention:
+          type: ["object", "null"]
+          additionalProperties: true
+          description: >
+            Managed-retention deployment facts (capabilities.ts:654). `null` = the sweep lane is off
+            (default). `mode: audit-only` = it runs and judges but calls NO destructive method; `enforce` =
+            it really deletes. The predicate looks only at config because a box with `intervalSec > 0` and no
+            real executor CANNOT BOOT (`boot/retention-lane.ts` refuses at startup).
+          required: [mode, maxAgeDays]
+          properties:
+            mode: { type: string, enum: [audit-only, enforce] }
+            maxAgeDays: { type: integer }
+        workflowsGate:
+          type: object
+          additionalProperties: true
+          description: >
+            Self-orchestration denial disclosure (capabilities.ts:739). The two parts are deliberately not
+            folded: `engineCan` = core's `workflowsCapability`; `denial` = the DEPLOYMENT-level admission
+            refusal (closed set, today's only member `entitlement_resolver_absent`), `null` = this layer does
+            not refuse. Non-null means the engine is there but this deployment can grant it to NO principal
+            (half-configured) — signpost the OPERATOR, do not tell the user to retry. `denial: null` does NOT
+            mean "you are authorized" (that is per-principal). `workflows` is the PRODUCT of the two factors.
+          required: [engineCan, denial]
+          properties:
+            engineCan: { type: boolean }
+            denial:
+              type: ["string", "null"]
+              enum: [entitlement_resolver_absent, null]
+
     SkillSpec:
       type: object
       description: A per-request skill (passed as an object; core-native TaskSpec.skills shape).
@@ -10089,6 +10300,53 @@ components:
             parentToolCallId: { type: string }
             depth: { type: integer }
             agentName: { type: string }
+        # ─── S-139(sdk 8.3.0):对 server 7.60.0 的整体重对账补齐的 9 位 ────────────────────────
+        # 长 description 的单一真源在 `packages/sdk/src/resources/tool-approvals.ts` 的同名成员上;
+        # 这里只留 codegen 需要的形与硬条款一句。机械对账门 = `test/server-keyset-parity.test.ts`。
+        requiresRealApproval:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.30.0 (core 5.37, #283), "tool_approval" only, ADDITIVE: the SAFETY-class provenance
+            bit core stamps at the gate. Present (true) or ABSENT — never encoded as false. Deliberately a
+            DIFFERENT contract from the card's `risk.requiresRealApproval` (which is an always-present
+            boolean): the card form needs the durable ask store, and this key is what lets a LIVE-ONLY
+            deployment read the bit at all. Present ⇒ every automatic allowance (remembered rules,
+            bypassPermissions posture) stands down.
+        origin: { $ref: '#/components/schemas/AskOrigin' }
+        inputHasBidi:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.45.0 (E-14), "tool_approval" only, ADDITIVE: the TO-BE-EXECUTED input (`args`)
+            contains Unicode bidi control characters — what the eye reads may not be the byte order that
+            runs. DISCLOSURE bit, bytes unchanged (sanitising would change the bytes about to execute, which
+            is WORSE than not disclosing); rendering is the shell's. Present (true) or ABSENT; absence !=
+            "verified clean". Computed BEFORE the byte cap, so it can ride a frame whose `args` were omitted.
+        expiresAtMs:
+          type: integer
+          description: >
+            server >= 7.34.0 (#288), "tool_approval" only, ADDITIVE: window triple (with `expiresInMs` and
+            `serverNowMs`, same names/semantics as on ApprovalRequestFrame) so the LEGACY frame family can
+            render a countdown too. `expiresAtMs` = this ask's absolute deadline on the server clock. The
+            three keys are BORN AND ABSENT TOGETHER — any frame that gets emitted carries all three.
+        expiresInMs:
+          type: integer
+          description: 'Window triple (see expiresAtMs): max(0, expiresAtMs - serverNowMs), computed at mint time.'
+        serverNowMs:
+          type: integer
+          description: 'Window triple (see expiresAtMs): the server clock at FRAME MINT time — the countdown anchor; use it to correct local clock skew.'
+        ruleOffersAbsence: { $ref: '#/components/schemas/RuleOffersAbsence' }
+        denialLimitFallback: { $ref: '#/components/schemas/DenialLimitFallback' }
+        parked:
+          type: boolean
+          enum: [true]
+          description: >
+            server >= 7.42.0 (#329), "tool_approval_complete" ONLY, ADDITIVE: the explicit discriminator for
+            the PARK sense of `outcome: "expired"` (which is one word with three landings). Present ⇔ THIS ask
+            settled through the park route ⇒ render "moved to the background queue", not "the card died".
+            🔴 ABSENCE MUST NOT BE READ AS "really denied": a store-less deployment, a deny policy, and a
+            sibling VOIDed in a batch all emit no such key — absence only means "no park evidence".
         outcome:
           type: string
           enum: [allowed, denied, expired]
@@ -10226,6 +10484,10 @@ components:
         probeCause: { type: object, additionalProperties: true, description: 'server >= 7.17.0: structured reversibility-probe tightening cause — same shape and semantics as ToolApprovalFrame.probeCause ({code, roots:{shown,total}, further?:{shown,total}}); frame and card carry the SAME value (one narrow-read function server-side). See that key for the full contract.' }
         ruleEvidence: { type: object, additionalProperties: true, description: 'server >= 7.23.0: rule-provenance evidence — same shape and semantics as ToolApprovalFrame.ruleEvidence (each member a value or a NAMED absence word; display/reconciliation metadata, never adjudication input). Frame and card carry the SAME value. See that key for the full contract.' }
         delegation: { $ref: '#/components/schemas/ApprovalCardDelegation' }
+        # S-139(sdk 8.3.0):同 A-057.④ 的理由 —— server 早随卡投出(帧与卡同一只窄读函数 ⇒ 同值),
+        # 但本 schema 此前只在帧上公示过。长 description 的单一真源在 ToolApprovalFrame 的同名键。
+        ruleOffersAbsence: { $ref: '#/components/schemas/RuleOffersAbsence' }
+        denialLimitFallback: { $ref: '#/components/schemas/DenialLimitFallback' }
 
     RuleSuggestion:
       type: object
@@ -10248,6 +10510,69 @@ components:
           description: '`exact` = this one command only (`Bash(git status)`); `prefix` = word-boundary prefix (`Bash(git status:*)`). Closed vocabulary — an unknown value is not a candidate this contract describes; do not render it as redeemable.'
         command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
 
+    # ─── S-139(sdk 8.3.0):对 server 7.60.0 整体重对账带进来的四张型面 ───────────────────────
+    AskOrigin:
+      type: string
+      enum: [content_question, unresolvable, org_unavailable, org_rule, hook, ask_rule, denial_limit_fallback, policy]
+      description: >
+        WHO raised an ask (`ToolApprovalFrame.origin`; server >= 7.57.0 / core 7.5.0, S-125③/#564) — core's
+        `ASK_ORIGINS`, ENGINE-STAMPED at the gate (core's words: "engine-stamped at the gate, never a policy's
+        claim"), transcribed verbatim by the server, which deliberately mints no second eligibility table of
+        its own.
+
+        🔴 READ AS AN OPEN SET. The vocabulary's sole owner is core and it has grown before; branch with a
+        default arm and treat an unknown word as "unknown origin", never as "no origin".
+        🔴 NOT interchangeable with `governanceForced`: this says which KIND of authority asked, that one says
+        whether THIS DEPLOYMENT's ops governance layer is the gate — `origin: policy` covers any deployment
+        ToolPolicy's ask, so a governance-produced ask and an ordinary one look identical in this one word.
+
+    RuleOffersAbsence:
+      type: string
+      enum: [mandated, shadowed, lane_cannot_speak]
+      description: >
+        WHY `ruleOffers` is absent while the rule lane IS present (`ToolApprovalFrame.ruleOffersAbsence` and
+        `ApprovalCard.ruleOffersAbsence`; server >= 7.55.0 / core #490 fix ②, S-15). The engine names which
+        door is shut: `mandated` = this ask must be confirmed every time (🔴 this arm must NOT point the user
+        at writing a rule — a rule would not silence it, and saying so sends them into a loop); `shadowed` = a
+        rule matched but could not clear it (the machine-readable twin of `persistedRuleShadowed`);
+        `lane_cannot_speak` = the engine could mint no coverable form for this command.
+
+        Engine-side MUTUALLY EXCLUSIVE with `ruleOffers`. 🔴 ABSENCE IS NOT AN ASSERTION — it covers both
+        "there are offers" and the three structural doors, and one frame cannot tell them apart. ADVISORY
+        display metadata, NEVER adjudication input. The frame and the stored `card_json` go through the SAME
+        server-side narrow read, so both faces carry identical values; a word outside the set is treated as
+        malformed and the key is not minted at all (the server never passes an unknown word through).
+
+    DenialLimitKind:
+      type: string
+      enum: [consecutive, total]
+      description: 'Which bound tripped in a `DenialLimitFallback` — the consecutive-refusal limit or the cumulative one.'
+
+    DenialLimitFallback:
+      type: object
+      additionalProperties: false
+      required: [consecutive, total, limit, autoDenyAfterMs]
+      description: >
+        The auto-mode classifier's DENIAL-LIMIT FALLBACK card (`ToolApprovalFrame.denialLimitFallback` and
+        `ApprovalCard.denialLimitFallback`; server >= 7.57.0 / core 7.4.0 #548, S-114): the call that hit the
+        consecutive (default 3) or cumulative (default 20) refusal limit is no longer silently denied — it
+        becomes a card a HUMAN must decide. The same mint also stamps `requiresRealApproval`; the two are twins.
+
+        🔴 ALL FOUR MEMBERS ARE REQUIRED: core's shape has no optional member, so "one missing" is a bad value
+        rather than an older core, and the server drops the whole key instead of half-minting a card whose
+        counts would be misread.
+        🔴 `autoDenyAfterMs` (ms; `0` = not armed — the deployment turned the knob off, or a TOTAL-tier card
+        waits for a person) is for RENDERING THE COUNTDOWN ONLY. Never start a second timer from it: the window
+        is executed by the ENGINE, and two overlapping windows are worse than the original defect and silent.
+        🔴 ABSENCE IS NOT AN ASSERTION — the vast majority of asks are not fallback cards.
+        ⚠️ The durable (parked) leg does NOT carry this key today; the card's copy rides `card_json`, which is
+        a different leg from the parked row's `pendingAction`.
+      properties:
+        consecutive: { type: integer, description: 'Consecutive refusals at the moment the limit tripped.' }
+        total: { type: integer, description: 'Cumulative refusals at the moment the limit tripped.' }
+        limit: { $ref: '#/components/schemas/DenialLimitKind' }
+        autoDenyAfterMs: { type: integer, description: 'This card''s own auto-deny window in ms; 0 = not armed. Countdown rendering only.' }
+
     RuleOfferMatch:
       type: string
       description: >

package/package.json

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