@sema-agent/server 1.323.0 → 2.0.1

package/dist/approval-hmac.d.ts

@@ -1,4 +1,35 @@
 import type { ApprovalHmacKey } from "./auth-keys.js";
+/**
+ * The canonical message an approval MAC signs — a fixed-order, JSON-escaped tuple so no field value (an id, a
+ * hash, a free-text note) can ambiguate the boundary with the next (same discipline as the approvals-stream diff
+ * key). 🔴 Bound to CLIENT-VISIBLE values only: `sessionId` (in the /decide URL) + `boundCallId`/`boundInputHash`
+ * (surfaced by listPending) + `reason` (the caller's own body). It must NOT include the checkpointToken — that is
+ * the unexposed resume credential the client can never see (it resumes by sessionId), so a checkpointToken-bound
+ * message would be uncomputable by the signer.
+ *
+ * ── `reason` 入签(三方裁 (a):cli [1797] / core [1801]§四 / server;clay「干净切」令 [1802])─────────────
+ * `reason` 是随决定落账的自由文本(审计面的一部分)。它此前**在信封之外** ⇒ 能改线上字节的一方(反代 /
+ * 被劫持的客户端 —— 正是 HMAC 要防的威胁模型)可以在操作员批准同一个动作的那次决定里,把落账理由换成
+ * 别的:动作没变,**审计记录变了**。三方裁定纳入签名载荷,不留 `reasonUnsigned` 宽限代际(未上生产)。
+ *
+ * ── 🔴 字节构造规则(权威定义;跨仓签名器照此实现,docs/ASSISTANT-WIRE-CONTRACT.md §6.2 同源)──────────
+ * 被 HMAC 的是下面这个字符串的 **UTF-8 字节**:
+ *   1. **恒 5 元素、定序**的紧凑 JSON 数组(元素间**无空格**):
+ *      `[sessionId, boundCallId|null, boundInputHash|null, decision, reason|null]`
+ *      —— 恒定长度是刻意的:签名器里少一个"有 reason 才追加"的条件分支,就少一类跨实现漂移。
+ *   2. 缺席 ⇒ `null`;**`""`(空串)是与 `null` 不同的被签值**(否则"把理由抹成空"不改变 MAC)。
+ *   3. 字符串转义 = RFC 8259 最小集:`"`→`\"`、`\`→`\\`、U+0000–U+001F → `\n`/`\t`/`\uXXXX`。
+ *   4. **非 ASCII 原样输出 UTF-8,不转 `\uXXXX`**。⚠️ Python 的 `json.dumps` 缺省 `ensure_ascii=True` 会踩
+ *      —— 必须 `json.dumps(t, ensure_ascii=False, separators=(",", ":"))`。
+ *   5. **`<` `>` `&` 不转义**。⚠️ Go 的 `json.Marshal` 缺省 HTML 转义会踩 —— 必须
+ *      `enc := json.NewEncoder(w); enc.SetEscapeHTML(false)`(并去掉它追加的换行)。
+ *   6. 孤代理项按 ES2019 well-formed 语义转成 `\udXXX`(JS 原生行为,其它语言按同规则)。
+ *   7. MAC = HMAC-SHA256(上述字节),**小写十六进制**上 wire。
+ * 逐字节黄金向量(含中文/引号/换行/制表/`<`/`&`/emoji)钉在 `test/approval-hmac.test.ts`,签名器对拍用。
+ *
+ * 之所以到今天才把规则写死:此前四个字段全是**受限字母表**(uuid / 调用 id / 十六进制 / 枚举),转义怎么
+ * 写都一样、规则不写也测不出来;`reason` 是第一个进入签名载荷的自由文本,转义从"无所谓"变成"承重"。
+ */
 export declare function approvalHmacMessage(env: {
     sessionId: string;
     boundCallId?: string | null;
@@ -6,7 +37,16 @@ export declare function approvalHmacMessage(env: {
     decision: string;
     reason?: string | null;
 }): string;
+/** 签名载荷里 `reason` 的字符上限。**拒**而不是截 —— 截断在这条路径上**结构上不可行**:服务端截过的字节
+ *  与签名方签的字节必然不同,MAC 恒不匹配,"截断"只会把一个可诊断的 413 变成一个费解的 401。
+ *  取 4096 与本仓既有的人写文本上限同档(`MAX_ELICIT_MESSAGE_CHARS` / `MAX_AGENT_TEXT_CHARS`)。 */
 export declare const MAX_APPROVAL_REASON_CHARS = 4096;
+/**
+ * design/80 D-G: verify the INTEGRITY of an approval-decision envelope. Returns true iff `mac` (hex) equals
+ * HMAC-SHA256(canonical-envelope) under ANY key in the set — the `kid`-hinted key first, then the rest (so a MAC
+ * signed with a key being rotated out still verifies during the overlap). `timingSafeEqual` avoids a timing
+ * oracle. An empty key-set ⇒ false (caller decides whether absence = skip-because-inactive or fail-closed).
+ */
 export declare function verifyApprovalHmac(env: {
     sessionId: string;
     boundCallId?: string | null;

package/dist/approval-hmac.js

@@ -1,8 +1,75 @@
+/**
+ * design/80 D-G: approval-envelope HMAC (INTEGRITY, not identity). Split out of `security.ts` (design/158
+ * A13, internal-lossless — the facade re-exports every symbol below unchanged; verifyDirectDoorProof in
+ * ./principal-jwt.ts imports {@link verifyApprovalHmac} from here for the combined proof).
+ *
+ * ✅ WIRED into the resolve path (was "🔴 SCAFFOLD — NOT YET WIRED" — that claim went STALE; a 2026-07-25 doc-rot
+ * sweep traced the real call chain: {@link verifyApprovalHmac} ← `verifyDirectDoorProof` ← the live decide
+ * routes at `http/server.ts:4796` and `:4907`). So "not wired" was wrong; "not turned on" is right, and turning it
+ * on is a DEPLOYMENT + KEY-PROVISIONING task (sema-registry mints/rotates the set), not a coding task.
+ *
+ * FULL activation chain (an independent 2026-07-25 cross-check caught the first draft of this note naming only the
+ * leaf conditions — record it completely so a deployment engineer isn't surprised): the crypto branch lives ONLY
+ * under the durable-checkpoint /decide path, whose route block is gated on `deps.checkpointStore`
+ * (`http/server.ts:4517`), which needs `backend?.checkpoint && config.durableApproval` (`main.ts:1902`). That is NOT
+ * an extra thing to remember, because `directDoorActive` ALREADY requires `DURABLE_APPROVAL=true` by construction
+ * (`config.ts:1264` — and see the 🔴 note above it: without it, checkpointStore is undefined, this branch is
+ * skipped, and the LEGACY trusted-header /decide becomes live = a full crypto bypass). So `directDoorActive` really
+ * is the single load-bearing switch — it just transitively implies the durable store, rather than being independent
+ * of it. A half-configured door refuses to boot (`config.ts:1266`+), so "looks on, verifies nothing" is impossible.
+ * This is the crypto FOUNDATION for D-G (the direct-connect approval door): it proves the decision envelope
+ * `{checkpointToken, boundCallId, boundInputHash, decision}` was not tampered in transit. It is INTEGRITY, NOT
+ * identity — `isOperator(principal)` stays the identity gate (a valid MAC says "the bytes are intact", never
+ * "this is the operator").
+ * The KEY-SET shape here is PROVISIONAL — sema-registry owns the final secret format; only parseApprovalHmacKeys
+ * changes if it differs. Replay protection is the checkpointToken's SINGLE-USE nature (a replayed MAC names an
+ * already-resolved token → the resolve CAS fails already_resolved), so no separate replay cache is needed.
+ */
 import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * The canonical message an approval MAC signs — a fixed-order, JSON-escaped tuple so no field value (an id, a
+ * hash, a free-text note) can ambiguate the boundary with the next (same discipline as the approvals-stream diff
+ * key). 🔴 Bound to CLIENT-VISIBLE values only: `sessionId` (in the /decide URL) + `boundCallId`/`boundInputHash`
+ * (surfaced by listPending) + `reason` (the caller's own body). It must NOT include the checkpointToken — that is
+ * the unexposed resume credential the client can never see (it resumes by sessionId), so a checkpointToken-bound
+ * message would be uncomputable by the signer.
+ *
+ * ── `reason` 入签(三方裁 (a):cli [1797] / core [1801]§四 / server;clay「干净切」令 [1802])─────────────
+ * `reason` 是随决定落账的自由文本(审计面的一部分)。它此前**在信封之外** ⇒ 能改线上字节的一方(反代 /
+ * 被劫持的客户端 —— 正是 HMAC 要防的威胁模型)可以在操作员批准同一个动作的那次决定里,把落账理由换成
+ * 别的:动作没变,**审计记录变了**。三方裁定纳入签名载荷,不留 `reasonUnsigned` 宽限代际(未上生产)。
+ *
+ * ── 🔴 字节构造规则(权威定义;跨仓签名器照此实现,docs/ASSISTANT-WIRE-CONTRACT.md §6.2 同源)──────────
+ * 被 HMAC 的是下面这个字符串的 **UTF-8 字节**:
+ *   1. **恒 5 元素、定序**的紧凑 JSON 数组(元素间**无空格**):
+ *      `[sessionId, boundCallId|null, boundInputHash|null, decision, reason|null]`
+ *      —— 恒定长度是刻意的:签名器里少一个"有 reason 才追加"的条件分支,就少一类跨实现漂移。
+ *   2. 缺席 ⇒ `null`;**`""`(空串)是与 `null` 不同的被签值**(否则"把理由抹成空"不改变 MAC)。
+ *   3. 字符串转义 = RFC 8259 最小集:`"`→`\"`、`\`→`\\`、U+0000–U+001F → `\n`/`\t`/`\uXXXX`。
+ *   4. **非 ASCII 原样输出 UTF-8,不转 `\uXXXX`**。⚠️ Python 的 `json.dumps` 缺省 `ensure_ascii=True` 会踩
+ *      —— 必须 `json.dumps(t, ensure_ascii=False, separators=(",", ":"))`。
+ *   5. **`<` `>` `&` 不转义**。⚠️ Go 的 `json.Marshal` 缺省 HTML 转义会踩 —— 必须
+ *      `enc := json.NewEncoder(w); enc.SetEscapeHTML(false)`(并去掉它追加的换行)。
+ *   6. 孤代理项按 ES2019 well-formed 语义转成 `\udXXX`(JS 原生行为,其它语言按同规则)。
+ *   7. MAC = HMAC-SHA256(上述字节),**小写十六进制**上 wire。
+ * 逐字节黄金向量(含中文/引号/换行/制表/`<`/`&`/emoji)钉在 `test/approval-hmac.test.ts`,签名器对拍用。
+ *
+ * 之所以到今天才把规则写死:此前四个字段全是**受限字母表**(uuid / 调用 id / 十六进制 / 枚举),转义怎么
+ * 写都一样、规则不写也测不出来;`reason` 是第一个进入签名载荷的自由文本,转义从"无所谓"变成"承重"。
+ */
 export function approvalHmacMessage(env) {
     return JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null, env.decision, env.reason ?? null]);
 }
+/** 签名载荷里 `reason` 的字符上限。**拒**而不是截 —— 截断在这条路径上**结构上不可行**:服务端截过的字节
+ *  与签名方签的字节必然不同,MAC 恒不匹配,"截断"只会把一个可诊断的 413 变成一个费解的 401。
+ *  取 4096 与本仓既有的人写文本上限同档(`MAX_ELICIT_MESSAGE_CHARS` / `MAX_AGENT_TEXT_CHARS`)。 */
 export const MAX_APPROVAL_REASON_CHARS = 4_096;
+/**
+ * design/80 D-G: verify the INTEGRITY of an approval-decision envelope. Returns true iff `mac` (hex) equals
+ * HMAC-SHA256(canonical-envelope) under ANY key in the set — the `kid`-hinted key first, then the rest (so a MAC
+ * signed with a key being rotated out still verifies during the overlap). `timingSafeEqual` avoids a timing
+ * oracle. An empty key-set ⇒ false (caller decides whether absence = skip-because-inactive or fail-closed).
+ */
 export function verifyApprovalHmac(env, mac, kid, keys) {
     if (keys.length === 0)
         return false;

package/dist/approval.d.ts

@@ -1,27 +1,58 @@
+/**
+ * OA human-in-the-loop approval gate (F4) — a `ToolPolicy` that holds a gated tool call until an
+ * operator approves/denies, with the pending state in TiDB so the decision can arrive on any instance.
+ *
+ * Built on core's `createApprovalPolicy` (which routes requireApproval/deny and races the wait against
+ * the task's AbortSignal). Our `approve` records a pending row and polls it for a decision; it also
+ * honors the signal directly (marks the request expired and releases) so a never-answered approval is
+ * dropped at the task deadline instead of holding the worker — design/06 F4 self-protection.
+ */
 import { type ToolPolicy } from "@sema-agent/core";
 import type { ApprovalStore } from "./plugins/store-backend.js";
+/**
+ * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
+ * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into
+ * a **suspend** (persists a checkpoint, ends `status:"suspended"`) — no held connection, resumable on any
+ * replica. (Contrast {@link createOaApprovalPolicy}, which holds the call open by polling a TiDB row.)
+ */
 export declare function createDurableAskPolicy(opts: {
     requireApproval: string[];
     deny?: string[];
     autoBudget?: number;
     neverAuto?: string[];
+    /** Per-session approval-exemption probe ("本会话不再询问"): consulted ONLY for require-listed
+     *  tools, AFTER deny/neverAuto (both always win) and BEFORE the budget path. Canonical-space toolName.
+     *  A rejected promise is treated as NOT exempt (fail-closed → ask) at the call site below. */
     exempt?: (canonicalToolName: string) => Promise<boolean>;
+    /** Audit hook — fired when an exemption short-circuits the ask (the `approval_exempted` log line). */
     onExempted?: (canonicalToolName: string, rawToolName: string) => void;
 }): ToolPolicy;
 export interface OaApprovalOptions {
     store: ApprovalStore;
+    /** Tool names that require an operator decision before they run. */
     requireApproval: string[];
+    /** Safety tools that must ALWAYS reach a human — checked BEFORE the exemption probe (workflow audit
+     *  2026-07-13: the OA leg consumed exemptions without the neverAuto guard, so a grant made in durable mode
+     *  could silently auto-approve a NEVER_AUTO tool after an ops switch back to the poll gate). */
     neverAuto?: string[];
+    /** Session exemption probe — same contract as createDurableAskPolicy.exempt (fail-closed). */
     exempt?: (sessionId: string, canonicalToolName: string) => Promise<boolean>;
+    /** Audit hook for an exemption short-circuit. */
     onExempted?: (sessionId: string, canonicalToolName: string) => void;
+    /** Per-run context captured for the approval row (operator UI shows session/tool/args). */
     context: () => {
         taskId?: string | null;
         sessionId?: string | null;
         owner?: string | null;
     };
+    /** Always-denied tools. */
     deny?: string[];
+    /** Poll interval for the decision. Default 1500ms. */
     pollMs?: number;
 }
 export declare function createOaApprovalPolicy(opts: OaApprovalOptions): ToolPolicy;
+/** Poll the approval row until decided, or release (deny) when the task aborts. Exported for unit tests.
+ *  `scope` is the run's tenant identity (owner-sourced) — carried on every read/decide so a run only ever
+ *  observes/aborts its OWN pending row (single-DB fleet read guard; defense-in-depth). */
 export declare function waitForDecision(store: ApprovalStore, id: string, scope: string | null, signal: AbortSignal | undefined, pollMs: number): Promise<boolean>;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -1,30 +1,68 @@
+/**
+ * OA human-in-the-loop approval gate (F4) — a `ToolPolicy` that holds a gated tool call until an
+ * operator approves/denies, with the pending state in TiDB so the decision can arrive on any instance.
+ *
+ * Built on core's `createApprovalPolicy` (which routes requireApproval/deny and races the wait against
+ * the task's AbortSignal). Our `approve` records a pending row and polls it for a decision; it also
+ * honors the signal directly (marks the request expired and releases) so a never-answered approval is
+ * dropped at the task deadline instead of holding the worker — design/06 F4 self-protection.
+ */
 import { createApprovalPolicy, canonicalToolName, uuidv7 } from "@sema-agent/core";
+/**
+ * Durable approval policy (core 1.67 / design/45): returns three-state **`ask`** for gated tools instead of
+ * polling. With `TaskSpec.durableApproval` set + a `checkpointStore` on the Runner, core turns that `ask` into
+ * a **suspend** (persists a checkpoint, ends `status:"suspended"`) — no held connection, resumable on any
+ * replica. (Contrast {@link createOaApprovalPolicy}, which holds the call open by polling a TiDB row.)
+ */
 export function createDurableAskPolicy(opts) {
+    // 🔒 CANONICAL-space matching (mirrors core 1.202 `createAllowDenyPolicy` + the design/116 S8 discipline):
+    // configured names AND the live request name both normalize via `canonicalToolName`, so an operator rule written
+    // against a legacy alias ("Task"/"KillShell"/"MultiEdit") keeps gating after a core CC-parity rename, and a
+    // durable-resume replay carrying a pre-rename `req.toolName` can't slip a rule written in the new names. A raw
+    // compare here is the same silent fail-open class the 1.202 rename exposed in main.ts's read-only strip.
     const require = new Set(opts.requireApproval.map(canonicalToolName));
     const deny = new Set((opts.deny ?? []).map(canonicalToolName));
     const neverAuto = new Set((opts.neverAuto ?? []).map(canonicalToolName));
     const budget = Math.max(0, Math.floor(opts.autoBudget ?? 0));
+    // design/80 D-E (upgrade-budget): a per-run-leg counter of NORMAL gated calls auto-approved so far. The policy
+    // is rebuilt per resolveSpec call (= per submit AND per resume — server.ts), so this closure is per-leg —
+    // adequate for a runaway-loop circuit-breaker (the loop lives within one leg; a suspend only fires on an
+    // over-budget / never-auto ask, which escalates to a human anyway). A durable per-run budget is a refinement.
     let autoApproved = 0;
     return {
         check: (req) => {
-            const toolName = canonicalToolName(req.toolName);
+            const toolName = canonicalToolName(req.toolName); // canonical-space lookup; messages keep the raw name for the operator
             if (deny.has(toolName))
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
+            // inv#2: a never-auto (irreversible / safety) tool ALWAYS asks a human — UNCONDITIONALLY, even if it was not
+            // also listed in requireApproval. An operator marking a tool "never auto-approve" means "always human"; it
+            // must never fall through to a bare allow (the footgun: neverAuto ⊄ requireApproval). Checked BEFORE the
+            // budget so a safety tool is never auto-approved. The enforcement is THIS deterministic policy `ask` — NOT a
+            // decisionReason (core 1.102 council proved decisionReason both misses policy-ask asks AND is forgeable, so
+            // the safety axis is sourced only from tool marks / core's persisted CheckpointGate.safetyAxis, never here).
             if (neverAuto.has(toolName))
                 return { action: "ask", message: `human approval required to run "${req.toolName}"` };
             if (require.has(toolName)) {
+                // Invariant alignment (workflow audit 2026-07-13): the DURABLE-resource-exhausted escalation is a
+                // SAFETY-axis ask (like neverAuto), so it outranks an exemption. In practice core already fail-fasts
+                // an exhausted leg before any tool call (runtask budget gate) — this is defense-in-depth ordering,
+                // zero behavior change on the live path, and it makes "耗尽恒问人" structural rather than incidental.
                 const remEarly = req.budget?.resourceRemainingMicroUsd;
                 if (remEarly !== undefined && remEarly <= 0) {
                     return { action: "ask", message: `durable resource budget exhausted — human approval required to run "${req.toolName}"` };
                 }
+                // Session exemption — an APPROVAL MEMORY, not a policy loosen: deny/neverAuto already won
+                // above; this only skips the HUMAN ask for a require-listed tool the operator said "remember" on. The
+                // probe is fail-closed (store error ⇒ not exempt ⇒ the normal ask path). AskUserQuestion is excluded
+                // for the same reason as the budget below (owned by the durable-question policy; its ask must stand).
                 if (opts.exempt && toolName !== "AskUserQuestion") {
                     return (async () => {
                         let exempted = false;
                         try {
-                            exempted = (await opts.exempt(toolName)) === true;
+                            exempted = (await opts.exempt(toolName)) === true; // strict: a truthy non-boolean must not auto-approve
                         }
                         catch {
-                            exempted = false;
+                            exempted = false; // fail-closed: a store hiccup must never auto-approve
                         }
                         if (exempted) {
                             opts.onExempted?.(toolName, req.toolName);
@@ -38,11 +76,27 @@ export function createDurableAskPolicy(opts) {
             return { action: "allow" };
         },
     };
+    /** The pre-existing require-branch tail (durable resource cap → per-leg count budget → ask), factored so the
+     *  async exemption probe and the sync path share ONE implementation (no drift). */
     function decideRequired(req, toolName) {
+        // a NORMAL gated tool AUTO-APPROVES while under the per-leg budget (the AI proceeds, no human); once the
+        // budget is exhausted the rest escalate to a human (the circuit-breaker trips). budget 0 ⇒ always ask.
+        // 🔴 EXCLUDE AskUserQuestion: it is owned by the durable-question policy (it ALWAYS asks), and
+        // combinePolicies (deny>ask>allow) makes that ask outrank our allow anyway — so counting it would
+        // silently shrink the real auto-approve budget for genuine NORMAL tools (adversarial finding). It falls
+        // through to ask here, consuming no budget.
+        // design/80 D-E-core (b, Framing 3): self-limit against the DURABLE resource ledger. If the run's durable
+        // resource budget is EXHAUSTED, escalate to a human REGARDLESS of the per-leg count budget. `req.budget`
+        // (core 1.103, built per-leg from the frozen-total resourceLedger) survives suspend/resume and CANNOT be
+        // re-granted (frozen-total, prior-wins) — so this is the durable cap that closes the per-leg re-grant below.
+        // 🔴 `resourceRemainingMicroUsd` is NEVER falsy-tested: 0 = exhausted (escalate), undefined = no ceiling.
         const rem = req.budget?.resourceRemainingMicroUsd;
         if (rem !== undefined && rem <= 0) {
             return { action: "ask", message: `durable resource budget exhausted — human approval required to run "${req.toolName}"` };
         }
+        // The per-leg COUNT budget remains a circuit-breaker (looser than configured across a deny-resume, but
+        // BOUNDED by core's suspendLoopCap, and inv#2 holds — a safety tool returned ask above). The durable
+        // resource cap above is the exact-per-run limiter the per-leg counter could not be (finding#1).
         if (toolName !== "AskUserQuestion" && budget > 0 && autoApproved < budget) {
             autoApproved++;
             return { action: "allow" };
@@ -58,12 +112,16 @@ export function createOaApprovalPolicy(opts) {
         deny: opts.deny,
         approve: async (req, signal) => {
             const ctx = opts.context();
+            // Session exemption — core already routed deny (deny wins before approve is ever called);
+            // a remembered (sessionId, toolName) auto-approves without a pending row. Fail-closed on a store error.
+            // neverAuto ALWAYS wins the exemption (same ordering lock as the durable policy — the OA leg previously
+            // lacked this guard, workflow audit 2026-07-13).
             if (opts.exempt && ctx.sessionId) {
                 const toolName = canonicalToolName(req.toolName);
                 if (toolName !== "AskUserQuestion" && !neverAuto.has(toolName)) {
                     let exempted = false;
                     try {
-                        exempted = (await opts.exempt(ctx.sessionId, toolName)) === true;
+                        exempted = (await opts.exempt(ctx.sessionId, toolName)) === true; // strict boolean, same as the durable twin
                     }
                     catch {
                         exempted = false;
@@ -75,13 +133,19 @@ export function createOaApprovalPolicy(opts) {
                 }
             }
             const id = uuidv7();
+            // scope = the run's tenant identity, owner-sourced (single-DB fleet read guard; defense-in-depth). The
+            // poll/abort paths below carry the SAME scope so this run only ever reads/aborts its own pending row.
             const scope = ctx.owner ?? null;
             await opts.store.createPending(id, scope, { ...ctx, toolName: req.toolName, args: req.args });
             return waitForDecision(opts.store, id, scope, signal, pollMs);
         },
     });
 }
+/** Consecutive poll errors tolerated before giving up (a persistent outage still fail-closes to deny). */
 const MAX_POLL_ERRORS = 5;
+/** Poll the approval row until decided, or release (deny) when the task aborts. Exported for unit tests.
+ *  `scope` is the run's tenant identity (owner-sourced) — carried on every read/decide so a run only ever
+ *  observes/aborts its OWN pending row (single-DB fleet read guard; defense-in-depth). */
 export async function waitForDecision(store, id, scope, signal, pollMs) {
     let consecutiveErrors = 0;
     for (;;) {
@@ -95,6 +159,10 @@ export async function waitForDecision(store, id, scope, signal, pollMs) {
             consecutiveErrors = 0;
         }
         catch (e) {
+            // A single transient TiDB blip must NOT throw out of the poll loop — core fail-closes a thrown
+            // approval policy to DENY, so one hiccup would deny an already-approved high-risk call after the
+            // operator clicked approve. Tolerate a few consecutive errors (keep polling); only give up (re-throw →
+            // deny) on a persistent outage.
             if (++consecutiveErrors >= MAX_POLL_ERRORS)
                 throw e;
             await sleepAbortable(pollMs, signal);

package/dist/audit.d.ts

@@ -1,15 +1,26 @@
 import type { Pool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+/**
+ * Audit view of a session = its **current context** (the live messages + the last compaction's
+ * summary), i.e. the floor-bounded window — never the full raw transcript. This matches the
+ * deployment decision that audit/回溯 needs "current + summary" (design/08); the full `session_event`
+ * log remains available as a separate cold-forensic query if ever needed.
+ */
 export interface SessionAudit {
     sessionId: string;
     createdAt: string;
+    /** The bounded-window floor (last compaction's firstKeptEntryId), or null if never compacted. */
     floorEntryId: string | null;
     thinkingLevel: string;
     model: {
         provider: string;
         modelId: string;
     } | null;
+    /** Current model context: prior messages with older history collapsed into a summary message. */
     messages: unknown[];
+    /** [1023]① web 观测切片 B: the session's prompt-epoch pin, core contract verbatim (core 1.304
+     *  `session.getPromptEpoch()` — first-class `prompt_epoch` entry, compaction restatement, RB-14 anchor
+     *  all inside core). Additive; a pre-epoch session omits the key entirely (undefined). */
     promptEpoch?: {
         epoch: number;
         artifactDigest: string;
@@ -18,9 +29,19 @@ export interface SessionAudit {
         activatedBy: "session_start" | "compaction" | "legacy_migration";
     };
 }
+/** Build the audit view from the durable log. Returns undefined if the session does not exist. */
 export declare function buildSessionAudit(pool: Pool, sessionId: string): Promise<SessionAudit | undefined>;
+/** The PG twin — same view over PgSessionStorage.wake. Until this, the
+ *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. local = follow-on
+ *  (its storage seam has no wake-equivalent yet — may turn out to be a core gap). */
 export declare function buildSessionAuditPg(pool: PgPool, sessionId: string): Promise<SessionAudit | undefined>;
+/** The LOCAL (File) leg — web session area on DB_BACKEND=local.
+ *  实现姿势:`FileSessionRepo.exportEntries`(纯读、torn-tail 恢复、missing→not_found)→
+ *  `boundedTail`(纯函数切 floor)→ InMemorySessionStorage → 同一 auditFromStorage 内核。零写面、
+ *  零新 seam;createdAt 从 repo.list() 的 metadata 取(File 形态 meta 与 entries 分储)。 */
 export declare function buildSessionAuditLocal(root: string, sessionId: string): Promise<SessionAudit | undefined>;
+/** Window `messages` — `tail=N` (last N) or `before=<offset>&limit=N` ([max(0,before-N), before)).
+ *  Returns the window + its {offset,total} so the web can page upward. */
 export declare function windowMessages(messages: unknown[], opts: {
     tail?: number;
     before?: number;
@@ -32,5 +53,10 @@ export declare function windowMessages(messages: unknown[], opts: {
         total: number;
     };
 };
+/** Cap oversized STRING bodies inside a message (top-level `content` string, or `text`/`content`
+ *  string fields of content parts — the shapes core emits; anything else passes through untouched). A capped
+ *  message gains `truncated: true` (message level — the web renders an expand affordance and refetches that
+ *  one message at full size). Pure/copy-on-write: uncapped messages keep their original reference.
+ *  [1075]①:超预算时引擎注入块(INJECTED_BLOCK_RE 闭集)优先整段让位,用户正文最后截。 */
 export declare function truncateMessageBlobs(messages: unknown[], capBytes: number): unknown[];
 //# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -1,12 +1,23 @@
+// 🔴 core 1.403 迁移(2026-07-25):`Session` 从 runtime class 降级成纯 interface,可构造的 storage-backed
+// class 改名 `StoredSession`(core CHANGELOG 1.403.0:"the constructable storage-backed class formerly
+// exported as `Session` is now `StoredSession`")——这里是 runtime 构造用法,照 core 给的迁移指南改。
 import { StoredSession, FileSessionRepo, InMemorySessionStorage, boundedTail } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
 import { PgSessionStorage } from "./plugins/pg-session-storage.js";
+/** Build the audit view from the durable log. Returns undefined if the session does not exist. */
 export async function buildSessionAudit(pool, sessionId) {
     return auditFromStorage(await TiDBSessionStorage.wake(pool, sessionId), sessionId);
 }
+/** The PG twin — same view over PgSessionStorage.wake. Until this, the
+ *  audit face was TiDB-only and a PG/local deployment 404'd the whole web session area. local = follow-on
+ *  (its storage seam has no wake-equivalent yet — may turn out to be a core gap). */
 export async function buildSessionAuditPg(pool, sessionId) {
     return auditFromStorage(await PgSessionStorage.wake(pool, sessionId), sessionId);
 }
+/** The LOCAL (File) leg — web session area on DB_BACKEND=local.
+ *  实现姿势:`FileSessionRepo.exportEntries`(纯读、torn-tail 恢复、missing→not_found)→
+ *  `boundedTail`(纯函数切 floor)→ InMemorySessionStorage → 同一 auditFromStorage 内核。零写面、
+ *  零新 seam;createdAt 从 repo.list() 的 metadata 取(File 形态 meta 与 entries 分储)。 */
 export async function buildSessionAuditLocal(root, sessionId) {
     const repo = new FileSessionRepo(root);
     let entries;
@@ -21,14 +32,19 @@ export async function buildSessionAuditLocal(root, sessionId) {
     const meta = (await repo.list()).find((m) => m.id === sessionId);
     const { tail, floorEntryId } = boundedTail(entries);
     const storage = new InMemorySessionStorage({ entries: tail, floorEntryId, ...(meta ? { metadata: meta } : {}) });
-    return auditFromStorage(storage, sessionId);
+    return auditFromStorage(storage, sessionId); // BaseSessionStorage 本有 getFloorId(构造喂了 floorEntryId)
 }
+/** The dialect-neutral kernel: both wake() twins land on core's StoredSession over a BaseSessionStorage. */
 async function auditFromStorage(storage, sessionId) {
     if (!storage)
         return undefined;
     const session = new StoredSession(storage);
     const meta = await session.getMetadata();
     const ctx = await session.buildContext();
+    // [1023]①: the typed prompt_epoch entry is NOT an LLM message, so it never appears in buildContext()'s
+    // messages — attach it as its own additive field. One kernel call covers all three dialect twins.
+    // (On the Local leg the bounded tail may pre-date the root pin; core resolves through the kept
+    // compaction's restatement — a truly pre-epoch session stays undefined → key omitted.)
     const promptEpoch = await session.getPromptEpoch();
     return {
         sessionId,
@@ -40,6 +56,18 @@ async function auditFromStorage(storage, sessionId) {
         ...(promptEpoch ? { promptEpoch } : {}),
     };
 }
+// ── web 会话区性能 PRD 的两条 additive 缝 ────────────────────────────────────────────────────
+//
+// The audit view's `messages` used to be ALL-OR-NOTHING: a 1000-entry session shipped its whole current
+// context on open (first-paint transfer + parse both scale with history). Two PURE post-processing helpers
+// give the route the additive knobs (hard requirement: parameterless requests stay byte-identical):
+//   windowMessages — tail/before+limit windowing over the messages array (offset-based; offsets are stable
+//     within one floor generation — the response's floorEntryId is the generation tag, a compaction changes
+//     it and the web refetches);
+//   truncateMessageBlobs — cap oversized string bodies (tool outputs are the whale) to a preview + a
+//     `truncated:true` marker; the web expands one message on demand via the single-message face.
+/** Window `messages` — `tail=N` (last N) or `before=<offset>&limit=N` ([max(0,before-N), before)).
+ *  Returns the window + its {offset,total} so the web can page upward. */
 export function windowMessages(messages, opts) {
     const total = messages.length;
     if (opts.before !== undefined) {
@@ -52,7 +80,12 @@ export function windowMessages(messages, opts) {
     const offset = Math.max(0, total - tail);
     return { messages: messages.slice(offset), window: { offset, total } };
 }
+/** 引擎注入块的闭集标签([1075]①,web [1069] 同款拆法):user wire 消息里每轮前置的
+ *  <system-reminder>/<task-notification> 原文段。裁剪时这些段**优先整段丢弃**——blobCap 预算留给
+ *  用户真正说的话(clay 报障现场:注入块排在人话前把 4096 字节吃光,`[truncated …]` 后正文整段消失)。 */
 const INJECTED_BLOCK_RE = /<(system-reminder|task-notification)>[\s\S]*?<\/\1>\s*/g;
+/** blobCap 下先剥注入块再量预算:剥后若已在预算内=保住全部人话(加 `injectedDropped:true` 注记);
+ *  仍超才截人话本身。剥离只在「原文本超预算」时发生——预算内的消息原样(含注入块)零变化,旧行为不动。 */
 function capWithInjectionAwareness(s, capBytes) {
     const total = Buffer.byteLength(s, "utf8");
     if (total <= capBytes)
@@ -62,8 +95,14 @@ function capWithInjectionAwareness(s, capBytes) {
     if (droppedAny && Buffer.byteLength(stripped, "utf8") <= capBytes) {
         return { text: `${stripped}…[${total - Buffer.byteLength(stripped, "utf8")} bytes of injected context omitted]`, dropped: true };
     }
+    // 剥后仍超(或无注入块):截 stripped——人话最后动,且从头保留(注入块已让位)。
     return { text: `${stripped.slice(0, capBytes)}…[truncated ${total} bytes total]`, dropped: droppedAny };
 }
+/** Cap oversized STRING bodies inside a message (top-level `content` string, or `text`/`content`
+ *  string fields of content parts — the shapes core emits; anything else passes through untouched). A capped
+ *  message gains `truncated: true` (message level — the web renders an expand affordance and refetches that
+ *  one message at full size). Pure/copy-on-write: uncapped messages keep their original reference.
+ *  [1075]①:超预算时引擎注入块(INJECTED_BLOCK_RE 闭集)优先整段让位,用户正文最后截。 */
 export function truncateMessageBlobs(messages, capBytes) {
     const capStr = (s) => capWithInjectionAwareness(s, capBytes)?.text;
     return messages.map((m) => {

package/dist/auth-bridge.d.ts

@@ -4,15 +4,20 @@ import type { Metrics } from "./observability/metrics.js";
 export type { VerifiedIdentity } from "@sema-agent/registry-core/api/auth-bridge";
 export { looksLikeJwt } from "@sema-agent/registry-core/api/auth-bridge";
 export interface RegistryJwtVerifierOptions {
+    /** R4 — 期望 iss(registry 的 SSO_ISSUER;默认=SEMA_REGISTRY_URL,双侧去尾斜杠比较)。 */
     issuer: string;
+    /** R2 — JWKS 绝对 URL(默认=issuer + REGISTRY_JWKS_PATH)。 */
     jwksUrl?: string;
+    /** R7 — 设了则 aud 必须包含它;不设=忽略 aud。 */
     audience?: string;
     clockSkewSec?: number;
     jwksRefreshMinIntervalSec?: number;
     offlineGraceSec?: number;
+    /** 常规(非 kid-miss)缓存刷新周期——过期后下一次 verify 顺路重拉(成功前旧键继续用,R8 语义)。 */
     jwksTtlSec?: number;
     logger?: Logger;
     metrics?: Pick<Metrics, "inc" | "observe">;
+    /** 测试注入。 */
     fetchImpl?: typeof fetch;
     nowMs?: () => number;
 }
@@ -23,8 +28,13 @@ export type VerifyOutcome = {
     ok: false;
     error: AuthBridgeErrorCode;
 };
+/** The live object `createRegistryJwtVerifier` produces — a single `verify` entry point over the process-level JWKS cache. */
 export interface RegistryJwtVerifier {
     verify: (bearer: string) => Promise<VerifyOutcome>;
 }
+/**
+ * registry-JWT verifier(单例,进程级 JWKS 缓存)。`verify(bearer)` 全程不 throw——一切异常折为
+ * AUTH_BRIDGE_ERROR_CODES(HTTP 面由调用方恒答 generic 401,码只进日志/metrics,R9)。
+ */
 export declare function createRegistryJwtVerifier(opts: RegistryJwtVerifierOptions): RegistryJwtVerifier;
 //# sourceMappingURL=auth-bridge.d.ts.map