@sema-agent/sdk 0.0.74 → 0.0.76

package/dist/health.d.ts

@@ -1,4 +1,26 @@
+/**
+ * 免构造工具(SDK 宪法例外①②收编,clay 拍 2026-07-16)—— the TWO sanctioned raw-HTTP shapes that must NOT
+ * require an AgentClient:
+ *
+ *  ① {@link probeHealth} — process-noise liveness. `/health` is the worker's UNAUTHENTICATED door
+ *     (server 1.214 server.js:296 — no token, no principal), and the probe's whole job is "is anything
+ *     alive there?" BEFORE credentials/TOFU exist (engine spawn wait-loops, port arbitration, dead-engine
+ *     triage, teardown confirmation — the shell's 6-strong probe family). Constructing a principal-first,
+ *     token-bearing client to ask that would invert the trust order, so the SDK ships the probe as a STATIC
+ *     function: zero-throw, judgement-typed, and — deliberately — sending NO credentials ever.
+ *
+ *  ② {@link engineUrl} — the single-source URL builder for the teardown last-resort raw fetch
+ *     (fire-and-forget on a dying process, where awaiting a Transport is wrong) and for anything else the
+ *     constitution grudgingly allows raw. One join semantic (identical to Transport's), so a hand-built URL
+ *     can never drift from what the client would have called.
+ *
+ * Everything ELSE goes through AgentClient — these two are the WHOLE exception surface (plus labelled
+ * contract-probe raws in tests; see the SDK constitution in the repo CLAUDE.md).
+ */
+/** The `/health` 200 body, subset-typed (server 1.214 server.js:296-320 — exact producer; open set for the
+ *  conditional fields: draining/durable/ready/restartRequired etc. appear only when true/degraded). */
 export interface EngineHealth {
+    /** "ok" on the live door — {@link probeHealth} requires it for `alive` (a 200 with anything else is `not_ok`). */
     status: string;
     version?: string;
     model?: string;
@@ -6,15 +28,24 @@ export interface EngineHealth {
     sessions?: number;
     instanceId?: string;
     dataRoot?: string;
+    /** sha256[0:16] over the engine's identity config (model/backends/dataRoot/port) — the shell's drift detector. */
     configHash?: string;
     pid?: number;
     port?: number;
     draining?: boolean;
+    /** false = model roster pending (first effective-config pull) — alive but not accepting billable submits. */
     ready?: boolean;
     storeDegraded?: boolean;
     restartRequired?: boolean;
     [k: string]: unknown;
 }
+/** Judgement-typed probe outcome. `alive` iff HTTP 200 AND `status === "ok"`; every dead arm carries WHY:
+ *  - `timeout`  — no answer inside the budget (process wedged / port filtered);
+ *  - `network`  — connect refused / DNS / TLS (nothing listening — the common "engine is down");
+ *  - `http`     — the port answered with a non-2xx (`status` = the code; something ELSE squats on the port,
+ *                 or the engine is mid-boot behind a proxy);
+ *  - `not_ok`   — 2xx but not the health contract (`status` field ≠ "ok" or unparseable body — port reuse by
+ *                 a non-engine HTTP server). */
 export type ProbeHealthResult = {
     alive: true;
     health: EngineHealth;
@@ -26,6 +57,19 @@ export type ProbeHealthResult = {
     reason: "http" | "not_ok";
     status: number;
 };
+/**
+ * Zero-throw unauthenticated liveness probe: `GET <baseUrl>/health` with a hard `timeoutMs` budget
+ * (default 2000 — process-noise cadence; pass more for slow cold boots). NEVER throws, NEVER sends
+ * credentials (TOFU discipline: nothing secret may leave before trust is established — same posture as the
+ * shell's probeEngineHealthUrl). Static on purpose: usable before/without an AgentClient (constitution
+ * exception ①).
+ */
 export declare function probeHealth(baseUrl: string, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<ProbeHealthResult>;
+/**
+ * Single-source engine URL builder (constitution exception ② — the teardown fire-and-forget raw's URL comes
+ * from HERE, never hand-concatenated). Join semantic is byte-identical to Transport's:
+ * trailing slashes are stripped off `baseUrl`, `path` is used verbatim (a missing leading `/` is added).
+ * 🔴 Path SEGMENTS are the caller's to encode (`encodeURIComponent` per segment) — this joins, it does not encode.
+ */
 export declare function engineUrl(baseUrl: string, path: string): string;
 //# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,YAAY;IAE3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AASD,MAAM,MAAM,iBAAiB,GACzB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,GAC/C;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAShE,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,SAAS,SAAO,EAChB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AAQD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;uGACuG;AACvG,MAAM,WAAW,YAAY;IAC3B,kHAAkH;IAClH,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kHAAkH;IAClH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6GAA6G;IAC7G,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;;gDAMgD;AAChD,MAAM,MAAM,iBAAiB,GACzB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,GAC/C;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,SAAS,SAAO,EAChB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D"}

package/dist/health.js

@@ -1,3 +1,29 @@
+/**
+ * 免构造工具(SDK 宪法例外①②收编,clay 拍 2026-07-16)—— the TWO sanctioned raw-HTTP shapes that must NOT
+ * require an AgentClient:
+ *
+ *  ① {@link probeHealth} — process-noise liveness. `/health` is the worker's UNAUTHENTICATED door
+ *     (server 1.214 server.js:296 — no token, no principal), and the probe's whole job is "is anything
+ *     alive there?" BEFORE credentials/TOFU exist (engine spawn wait-loops, port arbitration, dead-engine
+ *     triage, teardown confirmation — the shell's 6-strong probe family). Constructing a principal-first,
+ *     token-bearing client to ask that would invert the trust order, so the SDK ships the probe as a STATIC
+ *     function: zero-throw, judgement-typed, and — deliberately — sending NO credentials ever.
+ *
+ *  ② {@link engineUrl} — the single-source URL builder for the teardown last-resort raw fetch
+ *     (fire-and-forget on a dying process, where awaiting a Transport is wrong) and for anything else the
+ *     constitution grudgingly allows raw. One join semantic (identical to Transport's), so a hand-built URL
+ *     can never drift from what the client would have called.
+ *
+ * Everything ELSE goes through AgentClient — these two are the WHOLE exception surface (plus labelled
+ * contract-probe raws in tests; see the SDK constitution in the repo CLAUDE.md).
+ */
+/**
+ * Zero-throw unauthenticated liveness probe: `GET <baseUrl>/health` with a hard `timeoutMs` budget
+ * (default 2000 — process-noise cadence; pass more for slow cold boots). NEVER throws, NEVER sends
+ * credentials (TOFU discipline: nothing secret may leave before trust is established — same posture as the
+ * shell's probeEngineHealthUrl). Static on purpose: usable before/without an AgentClient (constitution
+ * exception ①).
+ */
 export async function probeHealth(baseUrl, timeoutMs = 2000, fetchImpl = fetch) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -24,6 +50,12 @@ export async function probeHealth(baseUrl, timeoutMs = 2000, fetchImpl = fetch)
         clearTimeout(timer);
     }
 }
+/**
+ * Single-source engine URL builder (constitution exception ② — the teardown fire-and-forget raw's URL comes
+ * from HERE, never hand-concatenated). Join semantic is byte-identical to Transport's:
+ * trailing slashes are stripped off `baseUrl`, `path` is used verbatim (a missing leading `/` is added).
+ * 🔴 Path SEGMENTS are the caller's to encode (`encodeURIComponent` per segment) — this joins, it does not encode.
+ */
 export function engineUrl(baseUrl, path) {
     const base = baseUrl.replace(/\/+$/, "");
     return path.startsWith("/") ? base + path : `${base}/${path}`;

package/dist/health.js.map

@@ -1 +1 @@
-{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AA8DA,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,SAAS,GAAG,IAAI,EAChB,YAA0B,KAAK;IAE/B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QACzG,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QACzE,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAK,IAA6B,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAChG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAoB,EAAE,CAAC;QACvD,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/G,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAQD,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAChE,CAAC"}
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqCH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,SAAS,GAAG,IAAI,EAChB,YAA0B,KAAK;IAE/B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QACzG,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QACzE,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAK,IAA6B,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAChG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAoB,EAAE,CAAC;QACvD,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/G,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAChE,CAAC"}

package/dist/idempotency.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Idempotency — auto UUID key for submit-class requests (DESIGN §2.3) + the RED LINE: a submit (POST tasks/
+ * runs) is retried ONLY when an idempotency key exists. The SDK auto-generates one, so retries are safe by
+ * default; a caller that explicitly sets `idempotencyKey: null` to disable it also LOSES auto-retry on submits.
+ * (The worker dedups by this key: same key in-flight/settled → reuse, concurrent → 409 — server-verified.)
+ */
 export declare function newIdempotencyKey(): string;
+/** Resolve the effective key: explicit string keeps it; `null` disables (and disables submit retry); undefined
+ *  → auto-generate. Returned to the transport, which sets the `Idempotency-Key` header and gates retry on it. */
 export declare function resolveIdempotencyKey(explicit: string | null | undefined): string | null;
 //# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAMA,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAID,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGxF"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;iHACiH;AACjH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGxF"}

package/dist/idempotency.js

@@ -1,6 +1,14 @@
+/**
+ * Idempotency — auto UUID key for submit-class requests (DESIGN §2.3) + the RED LINE: a submit (POST tasks/
+ * runs) is retried ONLY when an idempotency key exists. The SDK auto-generates one, so retries are safe by
+ * default; a caller that explicitly sets `idempotencyKey: null` to disable it also LOSES auto-retry on submits.
+ * (The worker dedups by this key: same key in-flight/settled → reuse, concurrent → 409 — server-verified.)
+ */
 export function newIdempotencyKey() {
     return crypto.randomUUID();
 }
+/** Resolve the effective key: explicit string keeps it; `null` disables (and disables submit retry); undefined
+ *  → auto-generate. Returned to the transport, which sets the `Idempotency-Key` header and gates retry on it. */
 export function resolveIdempotencyKey(explicit) {
     if (explicit === null)
         return null;

package/dist/idempotency.js.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAID,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,QAAQ,IAAI,iBAAiB,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;iHACiH;AACjH,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,QAAQ,IAAI,iBAAiB,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,13 @@
+/** @sema-agent/sdk — usage-plane SDK (the shared substrate for both doors). Server-side only. */
 export { AgentClient, type AgentClientConfig, type AgentAuthToken } from "./client.js";
+/** Control plane (TOB): sema-registry / config-center `/api/config/*`. A peer client (different backend +
+ *  secret) for managing the fleet config — see control-client.ts. */
 export { ControlClient, type ControlClientConfig } from "./control-client.js";
 export type { Principal, Scenario, RunStatus, TaskStats, TaskRequest, TaskAgentDefinition, TaskResult, RunReceipt, RunRecord, CancelAck, Artifact, LeaderReceipt, LeaderRecord, Capabilities, ScenarioDetail, PendingCheckpoint, SessionRecord, SkillSpec, MemoryRecord, MemoryWriteAck, TaskSummary, CheckpointGate, TraceTurn, TraceBlock, PromptManifest, PromptEpoch, SessionSummary, SessionListPage, SessionPermissionRules, StoredSessionRules, McpServerStatus, McpStatusPanel, SessionWindow, SessionMessageEnvelope, SyncEntry, SyncSnapshot, SyncAnchor, SessionRulesRecord, SessionManifest, SessionBundle, SyncRelation, SyncConflictRelation, ImportStaged, ImportCommitted, TraceStreamEvent, WorkflowStreamEvent, CheckpointSummary, InboxRow, AssistantGate, AssistantTask, PlanReviewRequest, AssistantTaskStatus, ImageIndexEntry, ImageSelectResult, ModelInfo, UsageInfo, PolicyInfo, WorkflowRunStatus, WorkflowRunSummary, WorkflowRun, WorkflowAgentRow, WorkflowActivityBeat, } from "./types.js";
+/** TOC `settings.json` — the SHARED environment-customization contract (CC-parity v1: permissions/hooks/env/model/
+ *  outputStyle). ONE schema, two wirings: TOC-local (shell adapter → local Runner) + TOB-fleet (carried to service via
+ *  {@link TaskRequest.settings}). SDK owns the CONTRACT only — no interpreter, no shell-hook runner. core/search AI
+ *  2026-06-27 / research/toc-settings-adapter/01-design.md §5①. */
 export type { SemaSettings, SettingsPermissions, SettingsHooks, SettingsHookMatcher, SettingsHookCommand, SettingsEnv, } from "./settings.js";
 export type { AgentEvent, EventIdentity, BrainStatusPhase } from "./events.js";
 export type { StampedAgentEvent } from "./sse.js";
@@ -9,25 +16,37 @@ export { MetricsResource, OutcomesResource, SendfileLinksResource, type OutcomeR
 export { BakesResource, type BakeClaim } from "./resources/images.js";
 export { type UsageAnalyticsParams, type UsageMetric, type UsageGranularity, type UsageTotals, type UsageSummary, type UsageSeries, type UsageBreakdown, type UsageDimension } from "./resources/usage.js";
 export { APIError, AuthError, RateLimitedError, QuotaExhaustedError, ScenarioNotAllowedError, BudgetExceededError, ConflictError, SyncConflictError, ApprovalStaleError, ApprovalBindingMismatchError, ApprovalConcurrentlyReopenedError, SteeringNotRunningError, SteeringInvalidContentError, PrincipalUnverifiedError, PrincipalUnboundError, ApprovalMacRequiredError, ApprovalMacInvalidError, GateNotResumableError, GateNotPlanReviewError } from "./errors.js";
+/** E4 quota deny (pinned wire shape) — structured detail on the 429 `quota_exhausted` typed error. */
 export type { QuotaExhaustedDetail } from "./errors.js";
+/** 2c session-sync — the NDJSON entry-stream truncation error + the PURE §7 relation classifier (the local peer
+ *  decides fast-forward/fork BEFORE pulling/pushing). */
 export { SyncTruncatedError } from "./sse.js";
+/** P0-2 S1 — typed heartbeat-silence watchdog error (tasks.stream / readSseFrames). Message literal is FROZEN
+ *  (`SSE: no data for ${ms}ms (heartbeat silence)`); carries `elapsedMs` for the caller's idle diagnosis. */
 export { SseIdleError } from "./sse.js";
 export { classifySyncRelationshipByIds, pushSessionBundle, pullSessionBundle, importSessionBundle } from "./sync.js";
+/** S2 会话搬运 — the peer-symmetric orchestration verbs over the sync primitives (push local↔cloud both ways). */
 export type { SessionSyncPeer, PushSessionOptions, PushSessionResult, PullSessionOptions, PulledSession } from "./sync.js";
 export { SessionSyncResource } from "./resources/session-sync.js";
 export { SideQueryResource, type SideQueryRequest, type SideQueryResult } from "./resources/side-query.js";
 export type { SubagentSteerReceipt, SubagentOutputResult, CompactAck, DetachAck } from "./resources/runs.js";
 export type { SessionGetParams } from "./resources/sessions.js";
 export type { WorkflowAgentSteerReceipt } from "./resources/workflows.js";
+/** Control-plane (sema-registry) typed errors — distinct hierarchy from the worker APIError tree. */
 export { ControlError, ControlAuthError, ControlForbiddenError, ControlNotFoundError, ControlValidationError, ControlConflictError, toControlError } from "./errors.js";
+/** Control-plane wire types (sema-registry /api/config/*). */
 export type { ConfigDomain, ControlRole, DomainRead, PutResult, BatchChange, BatchResult, ControlIssue, SchemaAll, SchemaOne, ExportResult, ConfigChange, ChangeDiff, RollbackResult, PublishedMeta, PendingPublish, PublishState, PublishResult, ApprovePublishResult, CancelPublishResult, FleetSnapshot, FleetMetrics, SchedulePlan, ScheduleApplyResult, WorkerStatuses, RollResult, RotateResult, CascadeOwnerResult, SweepResult, ControlImageEntry, ControlImageList, ImageListQuery, ImageSelectQuery, ImageSelectResolution, SecretInventory, SecretWriteResult, SecretRotateResult, SecretDeleteResult, SecretRefsResult, AuthProviderConfig, AuthProviderUpsert, AuthProvidersResult, AuthProviderUpsertResult, ControlUser, UsersResult, UserUpsertResult, UserTokenMintResult, UserTokenRevokeResult, } from "./control-types.js";
 export { newIdempotencyKey } from "./idempotency.js";
+/** SDK 宪法例外①②收编(免构造工具)— unauthenticated liveness probe + the single-source URL builder for the
+ *  teardown fire-and-forget raw. Static on purpose: usable before/without an AgentClient. */
 export { probeHealth, engineUrl } from "./health.js";
 export type { EngineHealth, ProbeHealthResult } from "./health.js";
 export type { ApprovalDecision, ApprovalStreamEvent, ApprovalExemption } from "./resources/approvals.js";
 export type { ElicitationFrame, ElicitResponse, ElicitRespondAck } from "./resources/elicitations.js";
 export type { QuestionFrame, AskQuestion, AskQuestionOption, QuestionAnswer, QuestionAnswerItem, QuestionRespondAck } from "./resources/questions.js";
 export type { ToolApprovalFrame, ToolApprovalDecision, ToolApprovalRespondAck } from "./resources/tool-approvals.js";
+/** MF-Fleet (shell-host data contract) — `client.fleet.stream()` LIVE multi-row fleet view (usage-plane;
+ *  DISTINCT from the control-plane `ControlClient.fleet`). The SDK produces frames; the consumer keeps state. */
 export { FleetResource } from "./resources/fleet.js";
 export type { FleetTaskRow, FleetWorkflowRow, FleetTaskStatus, FleetFrame, FleetMeta, FleetBgNotification } from "./resources/fleet.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,16 +1,29 @@
+/** @sema-agent/sdk — usage-plane SDK (the shared substrate for both doors). Server-side only. */
 export { AgentClient } from "./client.js";
+/** Control plane (TOB): sema-registry / config-center `/api/config/*`. A peer client (different backend +
+ *  secret) for managing the fleet config — see control-client.ts. */
 export { ControlClient } from "./control-client.js";
 export { assertNever } from "./events.js";
+// SDK 全覆盖批(2026-07-17,clay 令:server API 保证=server AI 直责):运维观测/烧制/用量分析面。
 export { MetricsResource, OutcomesResource, SendfileLinksResource } from "./resources/ops.js";
 export { BakesResource } from "./resources/images.js";
 export { APIError, AuthError, RateLimitedError, QuotaExhaustedError, ScenarioNotAllowedError, BudgetExceededError, ConflictError, SyncConflictError, ApprovalStaleError, ApprovalBindingMismatchError, ApprovalConcurrentlyReopenedError, SteeringNotRunningError, SteeringInvalidContentError, PrincipalUnverifiedError, PrincipalUnboundError, ApprovalMacRequiredError, ApprovalMacInvalidError, GateNotResumableError, GateNotPlanReviewError } from "./errors.js";
+/** 2c session-sync — the NDJSON entry-stream truncation error + the PURE §7 relation classifier (the local peer
+ *  decides fast-forward/fork BEFORE pulling/pushing). */
 export { SyncTruncatedError } from "./sse.js";
+/** P0-2 S1 — typed heartbeat-silence watchdog error (tasks.stream / readSseFrames). Message literal is FROZEN
+ *  (`SSE: no data for ${ms}ms (heartbeat silence)`); carries `elapsedMs` for the caller's idle diagnosis. */
 export { SseIdleError } from "./sse.js";
 export { classifySyncRelationshipByIds, pushSessionBundle, pullSessionBundle, importSessionBundle } from "./sync.js";
 export { SessionSyncResource } from "./resources/session-sync.js";
 export { SideQueryResource } from "./resources/side-query.js";
+/** Control-plane (sema-registry) typed errors — distinct hierarchy from the worker APIError tree. */
 export { ControlError, ControlAuthError, ControlForbiddenError, ControlNotFoundError, ControlValidationError, ControlConflictError, toControlError } from "./errors.js";
 export { newIdempotencyKey } from "./idempotency.js";
+/** SDK 宪法例外①②收编(免构造工具)— unauthenticated liveness probe + the single-source URL builder for the
+ *  teardown fire-and-forget raw. Static on purpose: usable before/without an AgentClient. */
 export { probeHealth, engineUrl } from "./health.js";
+/** MF-Fleet (shell-host data contract) — `client.fleet.stream()` LIVE multi-row fleet view (usage-plane;
+ *  DISTINCT from the control-plane `ControlClient.fleet`). The SDK produces frames; the consumer keeps state. */
 export { FleetResource } from "./resources/fleet.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAA+C,MAAM,aAAa,CAAC;AAGvF,OAAO,EAAE,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AAwB9E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAyC,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAkB,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAKvc,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAA+C,MAAM,2BAA2B,CAAC;AAK3G,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAaxK,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAE,WAAW,EAA+C,MAAM,aAAa,CAAC;AACvF;qEACqE;AACrE,OAAO,EAAE,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AAwB9E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,wEAAwE;AACxE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAyC,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAkB,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGvc;yDACyD;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C;6GAC6G;AAC7G,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAA+C,MAAM,2BAA2B,CAAC;AAI3G,qGAAqG;AACrG,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAaxK,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD;6FAC6F;AAC7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMrD;iHACiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/resources/approvals.d.ts

@@ -1,41 +1,84 @@
+/** approvals — HITL (SERVICE-CORE-CONTEXT §3.4). A run `suspended` event means a human must decide: an F4
+ *  policy gate (approve/deny a dangerous tool) or an AskUserQuestion (answer). LOAD-BEARING for web frontends
+ *  (web-native, non-expert users authorizing/answering); also usable by door A. */
 import type { Transport } from "../transport.js";
 import type { PendingCheckpoint } from "../types.js";
+/** One per-session approval exemption ("本会话不再询问", service exemptions ruling — an APPROVAL MEMORY, not a
+ *  policy loosen: deny/neverAuto always outrank it). Keyed in CANONICAL tool-name space (service
+ *  `ApprovalExemptionRow`, approval-exemption-store.ts). */
 export interface ApprovalExemption {
     toolName: string;
+    /** Principal that granted it; null = ownerless/anonymous grant. */
     grantedBy: string | null;
+    /** Epoch MS of the FIRST grant (a re-grant refreshes grantedBy, not this). */
     createdAt: number;
 }
+/** A delta event from `GET /v1/approvals/stream` (native push, service [83]). Open shape — `type` discriminates
+ *  `pending` / `resolved` / `synced` (initial) / `heartbeat`; payload fields are FORWARD-DRAFT pending service's
+ *  shape confirmation. A consumer that doesn't parse the delta can treat any non-heartbeat event
+ *  as a "changed" signal and refetch the authoritative list (`list()`). */
 export interface ApprovalStreamEvent {
     type: "pending" | "resolved" | "synced" | "heartbeat" | (string & {});
     [k: string]: unknown;
 }
 export interface ApprovalDecision {
     decision: "approve" | "deny";
+    /** For AskUserQuestion: the operator's answer. Omit for a plain F4 approve/deny. */
     answer?: unknown;
     reason?: string;
+    /** @deprecated ASSISTANT-WIRE-CONTRACT §4a:`checkpointToken` 是 server-INTERNAL,**永不**在 `/v1/approvals`
+     *  记录上 surface(server 自按 sessionId 解析);合规 client **只发 boundCallId+boundInputHash 两件套**,绝不注入
+     *  checkpointToken(可选 checkpointToken→409 approval_stale 是 deprecated legacy 路径)。字段保留仅为向后兼容编译,
+     *  不应再有来源填它(SDK 富 PendingCheckpoint 已无此字段)。 */
     checkpointToken?: string;
+    /** design/80 D-1 — action binding (TOCTOU guard). Read these TWO off the `PendingCheckpoint` the human saw
+     *  and pass them back VERBATIM; the server resolves THIS exact checkpoint, fail-closed on mismatch
+     *  (→ `ApprovalBindingMismatchError`). Omit only against a pre-D-1 worker (legacy resolve-by-sessionId).
+     *  = `toolCallId` of the action the human saw (the bound call). */
     boundCallId?: string;
+    /** Echo `PendingCheckpoint.boundInputHash` byte-for-byte — opaque, NEVER hashed/recomputed on the client. */
     boundInputHash?: string;
+    /** Approve-with-edit (design/37 last-wins): the operator's rewritten tool args, applied AFTER the binding
+     *  check. `boundInputHash` STILL binds the ORIGINAL input the human saw — never hash `updatedInput`. */
     updatedInput?: unknown;
 }
 export declare class ApprovalsResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /v1/approvals/:id — 按 id 读单条 durable 审批(server.ts:4342 实拆)。行含完整 tool-call args
+     *  (高危操作的命令/路径/内容)——owner 边界与列表面同门:operator 跨租户,其余只读本人(非本人=404
+     *  无存在性 oracle)。 */
     get(id: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Record<string, unknown>>;
+    /** GET /v1/approvals — pending checkpoints (operator-scoped; envelope key `pending`).
+     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS. */
     list(opts?: {
         signal?: AbortSignal;
     }): Promise<PendingCheckpoint[]>;
+    /** POST /v1/approvals/:sessionId/decide — resolve a suspend; the resumed run continues its stream.
+     *  Not a submit → no SDK retry (a decide must not double-act). */
     decide(sessionId: string, decision: ApprovalDecision, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
+    /** GET /v1/approvals/:sessionId/exemptions — the session's granted "don't ask again" exemptions (*  contract; envelope key `exemptions`). OWNER-GATED with a 404 (no existence oracle): non-owner AND unknown
+     *  session both 404. A worker without an exemption store backend → 501. */
     listExemptions(sessionId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<ApprovalExemption[]>;
+    /** DELETE /v1/approvals/:sessionId/exemptions/:toolName — revoke ONE exemption (the tool asks again).
+     *  contract. Idempotent at the SDK surface: `true` = revoked; `false` = the service 404'd — nothing to revoke
+     *  OR not-owner/unknown session (deliberately indistinguishable, no existence oracle). `toolName` should be the
+     *  canonical name off {@link ApprovalExemption.toolName} (the service canonicalizes, but echo what you listed). */
     revokeExemption(sessionId: string, toolName: string, opts?: {
         signal?: AbortSignal;
     }): Promise<boolean>;
+    /** GET /v1/approvals/stream — native push (SSE delta, meta `mode:"approvals-delta"`, service [83]). Replaces
+     *  BFF-side polling of `list()`. LONG-LIVED + operator-scoped: there is NO terminal event — this reconnects on
+     *  drops / heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
+     *  A non-`ok` first response (e.g. 404 on a worker without the endpoint) throws → caller falls back to polling.
+     *  FORWARD-DRAFT: event payloads pending service confirmation — consumers refetch `list()` on
+     *  any non-heartbeat event rather than trusting an unconfirmed delta shape. */
     stream(opts?: {
         signal?: AbortSignal;
     }): AsyncGenerator<ApprovalStreamEvent>;

package/dist/resources/approvals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAOrD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IAEjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAE7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAKhB,eAAe,CAAC,EAAE,MAAM,CAAC;IAKzB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAKnC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMlF,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAOnE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAWxG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAahG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBtG,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CA8BpF"}
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AAAA;;mFAEmF;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD;;4DAE4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;2EAG2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,oFAAoF;IACpF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;mDAG+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;uEAGmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;4GACwG;IACxG,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;wBAEoB;IACd,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIxF;uFACmF;IAC7E,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAKzE;sEACkE;IAC5D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9G;+EAC2E;IACrE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAStG;;;uHAGmH;IAC7G,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAc7G;;;;;mFAK+E;IACxE,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CA8BpF"}

package/dist/resources/approvals.js

@@ -5,13 +5,20 @@ export class ApprovalsResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /v1/approvals/:id — 按 id 读单条 durable 审批(server.ts:4342 实拆)。行含完整 tool-call args
+     *  (高危操作的命令/路径/内容)——owner 边界与列表面同门:operator 跨租户,其余只读本人(非本人=404
+     *  无存在性 oracle)。 */
     async get(id, opts) {
         return this.t.request({ method: "GET", path: `/v1/approvals/${encodeURIComponent(id)}`, signal: opts?.signal });
     }
+    /** GET /v1/approvals — pending checkpoints (operator-scoped; envelope key `pending`).
+     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS. */
     async list(opts) {
         const r = await this.t.request({ method: "GET", path: "/v1/approvals", signal: opts?.signal });
         return r.pending;
     }
+    /** POST /v1/approvals/:sessionId/decide — resolve a suspend; the resumed run continues its stream.
+     *  Not a submit → no SDK retry (a decide must not double-act). */
     async decide(sessionId, decision, opts) {
         return this.t.request({
             method: "POST",
@@ -20,6 +27,8 @@ export class ApprovalsResource {
             signal: opts?.signal,
         });
     }
+    /** GET /v1/approvals/:sessionId/exemptions — the session's granted "don't ask again" exemptions (*  contract; envelope key `exemptions`). OWNER-GATED with a 404 (no existence oracle): non-owner AND unknown
+     *  session both 404. A worker without an exemption store backend → 501. */
     async listExemptions(sessionId, opts) {
         const r = await this.t.request({
             method: "GET",
@@ -28,6 +37,10 @@ export class ApprovalsResource {
         });
         return r.exemptions;
     }
+    /** DELETE /v1/approvals/:sessionId/exemptions/:toolName — revoke ONE exemption (the tool asks again).
+     *  contract. Idempotent at the SDK surface: `true` = revoked; `false` = the service 404'd — nothing to revoke
+     *  OR not-owner/unknown session (deliberately indistinguishable, no existence oracle). `toolName` should be the
+     *  canonical name off {@link ApprovalExemption.toolName} (the service canonicalizes, but echo what you listed). */
     async revokeExemption(sessionId, toolName, opts) {
         try {
             await this.t.request({
@@ -43,6 +56,12 @@ export class ApprovalsResource {
             throw e;
         }
     }
+    /** GET /v1/approvals/stream — native push (SSE delta, meta `mode:"approvals-delta"`, service [83]). Replaces
+     *  BFF-side polling of `list()`. LONG-LIVED + operator-scoped: there is NO terminal event — this reconnects on
+     *  drops / heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
+     *  A non-`ok` first response (e.g. 404 on a worker without the endpoint) throws → caller falls back to polling.
+     *  FORWARD-DRAFT: event payloads pending service confirmation — consumers refetch `list()` on
+     *  any non-heartbeat event rather than trusting an unconfirmed delta shape. */
     async *stream(opts) {
         let failures = 0;
         for (;;) {
@@ -62,16 +81,17 @@ export class ApprovalsResource {
                 continue;
             }
             if (!res.ok)
-                throw toApiError(res.status, await res.json().catch(() => ({})));
+                throw toApiError(res.status, await res.json().catch(() => ({}))); // 404/4xx → caller polls
             try {
                 for await (const frame of readSseFrames(res, HEARTBEAT_GRACE_MS, opts?.signal)) {
-                    failures = 0;
+                    failures = 0; // a frame arrived = progress
                     if (!frame.data)
-                        continue;
+                        continue; // heartbeat comment
                     yield JSON.parse(frame.data);
                 }
             }
             catch {
+                // mid-stream drop or heartbeat silence → reconnect (long-lived stream has no terminal event)
             }
             finally {
                 res.body?.cancel().catch(() => { });

package/dist/resources/approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"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"}

package/dist/resources/assistant.d.ts

@@ -1,21 +1,44 @@
+/** assistant — assistant-scheduler + HITL 决策面（ASSISTANT-WIRE-CONTRACT.md, service main 6cd0164 /
+ *  core 1.110.0, LIVE on worker）。解锁 CLI 的 severity inbox(N2) / 总览抢占(N4) / plan_review(N3)。
+ *
+ *  🔴 拓扑铁律: CLI/web 前端 → BFF /api/* → `sdk(principal).assistant.*` → worker（worker token 留 BFF）。
+ *  SDK 服务端用, 不进浏览器/CLI。withPrincipal 自动重建本 resource —— BFF 的 sdk(principal).assistant.* 天然成立。
+ *
+ *  🔴 D-G 边界（§6）: 这 5 个 verb **不需要**签名证明 —— 走 owner 门（principal header, transport 已注入 x-agent-principal）。
+ *  只 /decide 要签名（approvals.decide + BFF 签, 不在本 resource）。owner 非属 → 404（无存在性 oracle）不是 403。 */
 import type { Transport } from "../transport.js";
 import type { InboxRow, AssistantTask, PlanReviewRequest, AssistantTaskStatus } from "../types.js";
 export declare class AssistantResource {
     private readonly t;
     constructor(t: Transport);
+    /** §2 GET /v1/assistant/inbox —— 单一 severity-sorted inbox（每用户视图）。operator 可用 `?owner=` 看某 owner,
+     *  否则看自己。返回行已由 core listPending 按 severity 排序 —— 消费方**不要再排**（且须容 undefined severity）。
+     *  解包 envelope `{inbox:[...]}`。owner query 在此手拼（transport.request 的 path 是裸串直拼, 无 query helper）。 */
     inbox(opts?: {
         owner?: string;
         signal?: AbortSignal;
     }): Promise<InboxRow[]>;
+    /** §3 GET /v1/assistant/tasks —— N-task 调度总览（每用户跨任务视图）。Triage 序由 core 给定（needsAttention 优先,
+     *  再 severity DESC, 再 spend DESC）—— **不要再排**。需 TiDB run store, 否则 worker 回 `{tasks:[]}`（原样透传）。 */
     tasks(opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTask[]>;
+    /** §4b POST /v1/assistant/tasks/:id/resume（:id = taskId）—— resource_limit CONTINUE。**无 body**。
+     *  非 submit → 不重试（一次决策不重放）。🔴 GATE-KIND GUARD: human/policy_ask 门 → 409 gate_not_resumable
+     *  （"continue" 绝不绕过人审, 那条路是 /decide）。owner 非属 → 404。 */
     resume(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
+    /** §4c POST /v1/assistant/tasks/:id/plan_review（:id = taskId）—— PRE-ACTION plan_review 门的 3-state 决策。
+     *  body = {decision, editedPlan?, reason?}。approve/edit/reject 全跑模型 → 计费。非 submit → 不重试。
+     *  🔴 GATE-KIND GUARD: 非 plan_review 门 → 409 gate_not_plan_review。400: 坏/缺 decision; edit 缺非空 editedPlan;
+     *  approve/reject 带 editedPlan; reason 非串。owner 非属 → 404。 */
     planReview(taskId: string, req: PlanReviewRequest, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
+    /** §4d POST /v1/assistant/tasks/:id/preempt（:id = taskId）—— 优雅 YIELD（跨副本让位, 与 runs.cancel 的 kill 相反）。
+     *  **无 body**。202 {status}（terminal → 202 no-op）。非 submit → 不重试。NOT billable。
+     *  suspended → 409; RESOURCE_SUSPEND off → 501; owner 非属 → 404。 */
     preempt(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;

package/dist/resources/assistant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assistant.d.ts","sourceRoot":"","sources":["../../src/resources/assistant.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAiB,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAyBlH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAKnC,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAmB3E,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAehE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYrF,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYjH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAO7F"}
+{"version":3,"file":"assistant.d.ts","sourceRoot":"","sources":["../../src/resources/assistant.ts"],"names":[],"mappings":"AAAA;;;;;;;+FAO+F;AAC/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAiB,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAyBlH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;wGAEoG;IAC9F,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAiBjF;sGACkG;IAC5F,KAAK,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAYtE;;4DAEwD;IAClD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ3F;;;iEAG6D;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASvH;;uEAEmE;IAC7D,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAO7F"}

package/dist/resources/assistant.js

@@ -1,3 +1,4 @@
+/** 折 null → OMIT(条件 spread,绝不写显式 undefined;exactOptionalPropertyTypes)。 */
 function normalizeGate(g) {
     return {
         kind: g.kind,
@@ -14,6 +15,9 @@ export class AssistantResource {
     constructor(t) {
         this.t = t;
     }
+    /** §2 GET /v1/assistant/inbox —— 单一 severity-sorted inbox（每用户视图）。operator 可用 `?owner=` 看某 owner,
+     *  否则看自己。返回行已由 core listPending 按 severity 排序 —— 消费方**不要再排**（且须容 undefined severity）。
+     *  解包 envelope `{inbox:[...]}`。owner query 在此手拼（transport.request 的 path 是裸串直拼, 无 query helper）。 */
     async inbox(opts) {
         const q = opts?.owner ? `?owner=${encodeURIComponent(opts.owner)}` : "";
         const r = await this.t.request({
@@ -21,11 +25,19 @@ export class AssistantResource {
             path: `/v1/assistant/inbox${q}`,
             signal: opts?.signal,
         });
+        // 🔴 severity 归一:部署的 worker 把 severity 放 riskDescriptor.severity(非顶层标量,违文档;
+        //   server.ts:1414 inbox handler 直接 spread listPending() 未走 summarizeCheckpoint)。优先顶层标量(文档/未来态),
+        //   缺则回退 riskDescriptor.severity(当前 live 态)。service 修 handler 后顶层自动接管,前向兼容。
         return r.inbox.map((row) => row.severity == null && row.riskDescriptor?.severity != null
             ? { ...row, severity: row.riskDescriptor.severity }
             : row);
     }
+    /** §3 GET /v1/assistant/tasks —— N-task 调度总览（每用户跨任务视图）。Triage 序由 core 给定（needsAttention 优先,
+     *  再 severity DESC, 再 spend DESC）—— **不要再排**。需 TiDB run store, 否则 worker 回 `{tasks:[]}`（原样透传）。 */
     async tasks(opts) {
+        // wire gate 的 severity/spentMicroUsd/deadline 形如 `4 | null`(§3),但 AssistantGate 把它们规约为 `?:number`
+        //   (缺/null 都容忍, OMIT 优先)。这里把 null 折成 OMIT —— 否则 raw 透传会把 wire 的 null 漏进 `?:number` 字段,
+        //   违反 exactOptionalPropertyTypes 的契约(消费方按 `number | undefined` 用,绝不该见 null)。
         const r = await this.t.request({
             method: "GET",
             path: "/v1/assistant/tasks",
@@ -33,6 +45,9 @@ export class AssistantResource {
         });
         return r.tasks.map((t) => normalizeTask(t));
     }
+    /** §4b POST /v1/assistant/tasks/:id/resume（:id = taskId）—— resource_limit CONTINUE。**无 body**。
+     *  非 submit → 不重试（一次决策不重放）。🔴 GATE-KIND GUARD: human/policy_ask 门 → 409 gate_not_resumable
+     *  （"continue" 绝不绕过人审, 那条路是 /decide）。owner 非属 → 404。 */
     async resume(taskId, opts) {
         return this.t.request({
             method: "POST",
@@ -40,6 +55,10 @@ export class AssistantResource {
             signal: opts?.signal,
         });
     }
+    /** §4c POST /v1/assistant/tasks/:id/plan_review（:id = taskId）—— PRE-ACTION plan_review 门的 3-state 决策。
+     *  body = {decision, editedPlan?, reason?}。approve/edit/reject 全跑模型 → 计费。非 submit → 不重试。
+     *  🔴 GATE-KIND GUARD: 非 plan_review 门 → 409 gate_not_plan_review。400: 坏/缺 decision; edit 缺非空 editedPlan;
+     *  approve/reject 带 editedPlan; reason 非串。owner 非属 → 404。 */
     async planReview(taskId, req, opts) {
         return this.t.request({
             method: "POST",
@@ -48,6 +67,9 @@ export class AssistantResource {
             signal: opts?.signal,
         });
     }
+    /** §4d POST /v1/assistant/tasks/:id/preempt（:id = taskId）—— 优雅 YIELD（跨副本让位, 与 runs.cancel 的 kill 相反）。
+     *  **无 body**。202 {status}（terminal → 202 no-op）。非 submit → 不重试。NOT billable。
+     *  suspended → 409; RESOURCE_SUSPEND off → 501; owner 非属 → 404。 */
     async preempt(taskId, opts) {
         return this.t.request({
             method: "POST",