@sema-agent/server 7.52.1 → 7.54.0

package/dist/plugins/approval-payload-fingerprint.js

@@ -0,0 +1,23 @@
+import { createLogger } from "../observability/logger.js";
+const fingerprintLogger = createLogger();
+function canonicalFingerprintJson(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return `[${v.map(canonicalFingerprintJson).join(",")}]`;
+    const entries = Object.entries(v)
+        .filter(([, val]) => val !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalFingerprintJson(val)}`).join(",")}}`;
+}
+export function approvalPayloadFingerprint(v) {
+    try {
+        const fp = canonicalFingerprintJson([v.updatedInput ?? null, v.answer ?? null, v.reason ?? null]);
+        return fp;
+    }
+    catch (e) {
+        fingerprintLogger.warn("approval decision payload is not serializable — idempotent replay refused", { error: e instanceof Error ? e.message : String(e) });
+        return null;
+    }
+}
+//# sourceMappingURL=approval-payload-fingerprint.js.map

package/dist/plugins/background-agent-store-sql.d.ts

@@ -1,10 +1,10 @@
 /**
- * BackgroundAgentStore SQL twins(design/151 S1 server 半场,[1503] 提货单②)——core
+ * BackgroundAgentStore SQL twins([ref] S1 server 半场,[ref] 提货单②)——core
  * `RunnerDeps.backgroundAgentStore` / `SubagentToolOptions.background.agentStore` 的 TiDB/PG
  * 双方言实现:每个后台子代(`a*` 句柄)一行 durable 执行记录。
  *
  * 语义对齐真源 = core `InMemoryBackgroundAgentStore`(dist/core/background-agent-store.js),
- * 契约四条([1503] 必守):
+ * 契约四条([ref] 必守):
  *  1. `put` create-once:重复 (scope, handle) 键 → `BackgroundAgentStoreError("agent_record.already_exists")`
  *     (唯一键原子,多副本安全);scope 缺席/空串拒收(与 core 同文案——default-deny 谓词下无 scope 的
  *     行会经 fallback 面变成公共可读)。
@@ -14,15 +14,15 @@
  *     recentSteps 可能是大 blob);session 锚 = `sessionScoped ? owner : parentSessionId`,写入时物化为
  *     `session_anchor` 列(anchor 为 NULL 的行 `= ?` 恒假 = core `anchor !== sessionId` 同义)。
  *  4. `delete` 条件删(可选 rev CAS);`reap` 三策略与 core 逐条同形(staleRunning 翻 failed 走
- *     rev-CAS 逐行,竞态输了跳过不计;terminal maxAge/keep 按 spawnedAt DESC)。[1522] LOW6 记账:裸
+ *     rev-CAS 逐行,竞态输了跳过不计;terminal maxAge/keep 按 spawnedAt DESC)。[ref] LOW6 记账:裸
  *     `reap` 的批删 IN 无上界、stale 臂全量拉 record_json——server 自己的 retention 只走
  *     reapDurableAgents(core 编排,不触这两条);第三方直调超大 scope 时自行分批。
  *
  * 行形:`record_json` = 全量真源(get 逐位读回);查询/谓词列全是投影,写入时从 record 物化
  * (展示列 name/agent_type 截到列宽 + PG 侧过 lossy 清洗——真源仍在 record_json;身份键列
  * scope/handle/owner/session 锚**不清洗不截断**:改写身份键会让行与 engine 查询键错位,含不可存
- * 字节的身份键=写入失败 fail-loud,与 [1439] 协议数据拒绝式同向)。
- * PG unstorable bytes([1439] 三层定谳):record/usage 走 `pgSafeJsonStringify`(观测/内容面 lossy
+ * 字节的身份键=写入失败 fail-loud,与 [ref] 协议数据拒绝式同向)。
+ * PG unstorable bytes([ref] 三层定谳):record/usage 走 `pgSafeJsonStringify`(观测/内容面 lossy
  * U+FFFD,与 run 行/journal 同族;终报含真 NUL 的病态输入换替换标记,内容面不失行);TiDB TEXT 存 verbatim。
  *
  * 键列 = 字节等价(TiDB VARBINARY / PG COLLATE "C"——roster F2 同案:PAD SPACE/大小写近撞不得穿过
@@ -52,7 +52,7 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
-    /** core 1.383([1565] 提货单)REQUIRED 新方法——原子守卫 CAS(claim 的 reservation/rollback/finalize
+    /** core 1.383([ref] 提货单)REQUIRED 新方法——原子守卫 CAS(claim 的 reservation/rollback/finalize
      *  绑定字段态非仅 rev:rev 可因无关写移动而字段义已变)。语义逐字对齐 core InMemoryBackgroundAgentStore
      *  ({@link parkGuardConditions} 顶注)。 */
     updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
@@ -79,7 +79,7 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
      *  翻转集里」把 doomed 拆两批删 —— 重叠那批照样真删、只是不再计数。两边都不能用「doomed.size 当删除数」
      *  近似:并发写者(真心跳复活)会让 `status <> 'running'` 守卫少删几行,那时 doomed.size 会虚高。 */
     reap(scope: string, now: number, opts?: ReapOpts): Promise<number>;
-    /** core 1.368([1516]②)可选接口成员落位(原 server 扩展 listReapScopes 更名对齐):当前持行
+    /** core 1.368([ref]②)可选接口成员落位(原 server 扩展 listReapScopes 更名对齐):当前持行
      *  scope 枚举——reaper 的 per-scope 联合 reap 入口。JS 侧 sort 与 core InMemory 逐字节同序
      *  (SQL ORDER BY 按 collation,非码元序)。 */
     listScopes(): Promise<string[]>;
@@ -92,7 +92,7 @@ export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
-    /** core 1.383([1565] 提货单)REQUIRED 新方法(TiDB twin 同案注释)。PG 侧占位符是显式编号 `$N`
+    /** core 1.383([ref] 提货单)REQUIRED 新方法(TiDB twin 同案注释)。PG 侧占位符是显式编号 `$N`
      *  (不像 TiDB `?` 靠数组顺序)——`n` 是跑动计数器,只在真正消耗一个占位符(非 IS NULL 分支)时前增。 */
     updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;

package/dist/plugins/background-shell-support.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/103 — shared support for the remote (TOB) `BackgroundShellCapability` implementations.
+ * [ref] — shared support for the remote (TOB) `BackgroundShellCapability` implementations.
  *
  * core defines the seam (`@sema-agent/core` `BackgroundShellCapability` + `hasBackgroundShell`) and ships the TOC
  * reference (`NodeExecutionEnv`). This module centralises the **security + lifecycle red-lines** that EVERY remote
@@ -7,23 +7,23 @@
  * primitives and cannot accidentally re-implement (or skip) an invariant:
  *
  *  - **opaque shellId** — a fresh `bg_<n>_<uuid>` brand, NEVER derived from the provider's job/pid (超范围红线,
- *    design/103 §3.8). The provider id lives only inside the driver state.
+ *    [ref] §3.8). The provider id lives only inside the driver state.
  *  - **owned-id isolation** — `poll`/`kill` look the shellId up in THIS manager's registry; an id from another env
- *    (or a forged one) is `not_found`, never resolved against the provider (design/103 §3.8 / interface 超范围契约).
+ *    (or a forged one) is `not_found`, never resolved against the provider ([ref] §3.8 / interface 超范围契约).
  *  - **maxConcurrent** — counts only `running` shells (terminal entries are kept for residual polling but free their
  *    slot, so "TaskStop one first" is actionable — matches the TOC `maxConcurrent 终态占槽` review fix).
  *  - **timeout hard wall** — a control-plane timer kills the shell and flips it to `killed` at the bounded BG
- *    timeout (design/103 §3.6); the driver may set an additional provider-level backstop ≥ this wall.
- *  - **dispose** — kills + cleans up EVERY shell, best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+ *    timeout ([ref] §3.6); the driver may set an additional provider-level backstop ≥ this wall.
+ *  - **dispose** — kills + cleans up EVERY shell, best-effort, MUST NOT throw, idempotent ([ref] §3.7).
  *
- * The two transports legitimately take different "按-id-可重读" paths (design/103 §5.2): E2B holds a resident
+ * The two transports legitimately take different "按-id-可重读" paths ([ref] §5.2): E2B holds a resident
  * `CommandHandle` reader feeding a control-plane tail buffer (path ②); kata/k8s buffers into pod-side files
  * re-read by byte cursor on each poll (path ①). Both are expressed through {@link BackgroundShellDriver}.
  */
 import { BackgroundShellError } from "@sema-agent/core";
 import type { BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions, Result } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
-/** Per-端 background capability bounds, surfaced as `backgroundCapabilities` on the env (design/103 §3.1/§3.6).
+/** Per-端 background capability bounds, surfaced as `backgroundCapabilities` on the env ([ref] §3.1/§3.6).
  *
  *  ⚠️ 有据不接:core 契约的 `retainBackgroundProcesses` 能力字段【有意】不在此声明(2026-07-08 定谳):
  *  TB 的声明与兑现全在 core 自己 runtime 内闭环(sema-tb bin 进程内 TOC local env 声明,core task-registry
@@ -79,7 +79,7 @@ export interface DriverPoll {
     stdout: string;
     /** New stderr since last read. */
     stderr: string;
-    /** Total output bytes the process has produced from start (cursor metadata; design/103 §3.4). */
+    /** Total output bytes the process has produced from start (cursor metadata; [ref] §3.4). */
     bytesFromStart: number;
     /** Bytes permanently lost to head-eviction before this read's cursor (0 if none). */
     bytesDroppedBeforeCursor: number;
@@ -112,7 +112,7 @@ export declare class BackgroundShellManager<S> {
     private readonly shells;
     private counter;
     constructor(driver: BackgroundShellDriver<S>, caps: BackgroundCaps);
-    /** [1116] 六轮复审:destroy 端判「还有 shell 依赖 spool 文件吗」——running(驻留 keep-alive)与
+    /** [ref] 六轮复审:destroy 端判「还有 shell 依赖 spool 文件吗」——running(驻留 keep-alive)与
      *  terminal 残余(dispose 前仍可轮询)都算;有=env 不得整树删 spool 根(逐 shell 清理归 dispose 面)。 */
     hasShells(): boolean;
     /** Count live shells; KillShell/timeout flip a shell out of `running` and free its slot. */
@@ -123,7 +123,7 @@ export declare class BackgroundShellManager<S> {
         shellId: BackgroundShellId;
     }, BackgroundShellError>>;
     /**
-     * design/116 detach (clay 排,1.81): adopt an EXTERNALLY-created RUNNING process as a background shell — the
+     * [ref] detach (clay 排,1.81): adopt an EXTERNALLY-created RUNNING process as a background shell — the
      * mid-flight ctrl+b path, where the process was spawned by a FOREGROUND `exec` and must move under this
      * manager's ownership instead of being killed. The `builder` receives the same {@link LaunchCtx} a driver
      * `launch` would (terminal notification + the bounded BG timeout it may use as a backstop) and returns the
@@ -143,7 +143,7 @@ export declare class BackgroundShellManager<S> {
      * all-or-nothing: put every operation that can throw BEFORE the first side effect, or clean up on the throw
      * path itself. Today's three lane builders are entirely non-throwing (listener attach + object construction).
      */
-    /** #131-T0:两条注册腿共用的 BG 超时钳制。非有限值(NaN/±Infinity)当缺席回退 default——
+    /** [ref]-T0:两条注册腿共用的 BG 超时钳制。非有限值(NaN/±Infinity)当缺席回退 default——
      *  Math.max/min 对 NaN 全塌 NaN,setTimeout(NaN) 被 Node 折成 1ms = 后台 shell 秒杀
      *  (方向反转:想给超时变成即杀;同族判例 TASK_TIMEOUT_SEC / leader 旋钮非法值)。 */
     private boundedBgTimeoutSec;
@@ -154,7 +154,7 @@ export declare class BackgroundShellManager<S> {
     private register;
     poll(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     kill(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
-    /** Kill + clean up EVERY shell. Best-effort, MUST NOT throw, idempotent (design/103 §3.7).
+    /** Kill + clean up EVERY shell. Best-effort, MUST NOT throw, idempotent ([ref] §3.7).
      *
      *  core `except` 契约(background-shell.d.ts:core runtask 尾调 `{except: keepAlive}`):
      *  这些 shellId **留活**——session 驻留 persistent Monitor 的进程,其全部意义就是跨 turn 存活;run-end

package/dist/plugins/blob-backend.d.ts

@@ -50,7 +50,7 @@ export declare class SqlBlobBackend implements BlobBackend {
     private readonly pool;
     /** Effective per-blob cap: explicit ctor value wins; else tidb=SQL_BLOB_DEFAULT_MAX_BYTES, pg=uncapped. */
     private readonly capBytes;
-    /** Blob-domain table (S-15 blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
+    /** Blob-domain table ([ref] blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
     private readonly table;
     constructor(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, maxBytes?: number, table?: string);
     /** The created_at-refreshing content-addressed upsert — VERBATIM the tidb/pg stores' `putBlobRow`. Refreshes
@@ -70,7 +70,7 @@ export declare class SqlBlobBackend implements BlobBackend {
      *  excluded referenced hashes). Best-effort: a delete error is swallowed (under-delete is harmless). */
     deleteBlobs(hashes: string[]): Promise<number>;
 }
-/** SHARED index op(workspace 浏览面 #3,[1894]②)—— per-blob 字节数,读 SQL INDEX 的 `byte_len`
+/** SHARED index op(workspace 浏览面 #3,[ref]②)—— per-blob 字节数,读 SQL INDEX 的 `byte_len`
  *  列(sqlHasBlobs 同款单 IN 查询;MinIO 后端的 bytes-NULL 索引行同样带 byte_len,两后端同源)。
  *  tree/file 面的 size 投影与「超限先拒后拉」都靠它——绝不为拿大小去 getBlob 整块字节。 */
 export declare function sqlBlobSizes(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, hashes: string[]): Promise<Map<string, number>>;
@@ -119,7 +119,7 @@ export declare class MinioBlobBackend implements BlobBackend {
      *  path). The file-snapshot stores ALWAYS pass the pool, so the live reference-tracking always has the index. */
     private readonly indexPool?;
     private readonly indexDialect?;
-    /** Blob-domain index table (S-15 域隔离,SqlBlobBackend.table 同款;默认 = E19 纪元的 snapshot_blob)。 */
+    /** Blob-domain index table ([ref] 域隔离,SqlBlobBackend.table 同款;默认 = E19 纪元的 snapshot_blob)。 */
     private readonly indexTable;
     constructor(cfg: MinioBlobBackendConfig, index?: {
         dialect: "tidb" | "pg";

package/dist/plugins/breaker-state-sql.d.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-replica circuit-breaker state (core 1.38 `BreakerState`) — SINGLE-FILE DUAL-DIALECT
- * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBBreakerState` /
- * `PgBreakerState` class names survive as thin ctor subclasses in THIS file ([2354]: the old per-dialect shim files are deleted) so every consumer (store-backend.ts, the
+ * ([ref] A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBBreakerState` /
+ * `PgBreakerState` class names survive as thin ctor subclasses in THIS file ([ref]: the old per-dialect shim files are deleted) so every consumer (store-backend.ts, the
  * fake-pool unit suites, the real dual-DB integration suite) is untouched.
  *
  * core's `createCircuitBreakerBrain` defaults to a per-PROCESS Map → on a multi-replica deployment
@@ -18,7 +18,7 @@
  *     learns a peer already opened the breaker — self-healing, never wrong in a dangerous direction).
  *
  * Strict per-call linearizable state would need an async `BreakerState` from core (a separate effort);
- * for a consultative breaker, eventually-consistent write-through is the right trade (see core design/20).
+ * for a consultative breaker, eventually-consistent write-through is the right trade (see core [ref]).
  *
  * ── Dialect deltas, kept EXPLICIT (the ONLY place the two engines actually differ) ─────────────────
  *   - placeholders `?` vs `$n`

package/dist/plugins/caching-session-store.d.ts

@@ -56,7 +56,7 @@ export declare class CachingSessionStore implements SessionStore {
      *  wrapper, so without forwarding `noteTaskRun?.()` silently no-ops and lastRunId stays null (review BLOCKER). Pure
      *  pass-through to the inner store's in-mem map — no cache interaction. (TiDB/PG don't implement it → not bound.)
      *  Return type matches core's `SessionStore.noteTaskRun?(): void | Promise<void>` (review: don't narrow to void).
-     *  #499(core 5.65 增量批):第三参 = engine runId。绑定用的是 `.bind(inner)`(整函数),运行期本就
+     *  [ref](core 5.65 增量批):第三参 = engine runId。绑定用的是 `.bind(inner)`(整函数),运行期本就
      *  三参全转 —— 这里把**声明**对齐到 core 的三参形,免得读这行类型的人以为缝上只有两参(fork-routing
      *  的两参形正是在运行期真丢过第三参的那个病,同批修)。内店(LocalSessionStore)今日仍是两参消费,
      *  runId 落地候 sessions 列表 wire 键的 spec 节拍(见本批提货报告件1b)。 */
@@ -67,7 +67,7 @@ export declare class CachingSessionStore implements SessionStore {
     /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
      *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     readonly getLeafId?: (sessionId: string) => Promise<string | null>;
-    /** [1196] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
+    /** [ref] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
     readonly getHead?: (sessionId: string) => Promise<{
         owner: string | null;
         leafId: string | null;
@@ -86,7 +86,7 @@ export declare class CachingSessionStore implements SessionStore {
     /** 轴A #1(1.254):core B-17 forget 面(evict 本地 + 转发 inner 可选面)。 */
     forget?: (sessionId: string) => void | Promise<void>;
     readonly importEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
-    /** [2024](cli 取证)2c session-sync P1d-β — delegated STAGED import seam. 此前 staging 族不在本类的逐方法
+    /** [ref](cli 取证)2c session-sync P1d-β — delegated STAGED import seam. 此前 staging 族不在本类的逐方法
      *  转发白名单里 ⇒ 默认部署(SESSION_CACHE_TTL_SEC=300 把真店包进本类)PUSH Phase A 恒 501
      *  `capability.session_store_required`,而 capabilities().sessionSync 谓词三项(backend/exportEntries/
      *  fileHistoryStore)都被转发了 ⇒ 照报 true(能力面谎)。转发形:handle 的 `commit` 是唯一写真 id 的
@@ -101,7 +101,7 @@ export declare class CachingSessionStore implements SessionStore {
      *  `sessionId`, so a stale warm handle for that id is evicted on success (next acquire re-wakes from the new log). */
     readonly replaceEntries?: (sessionId: string, owner: string | null, entries: SessionTreeEntry[]) => Promise<void>;
     /**
-     * #270 车1 —— 内层店的 `retention` **声明**(core `RetentionDeclaring`)。
+     * [ref] 车1 —— 内层店的 `retention` **声明**(core `RetentionDeclaring`)。
      *
      * 🔴 为什么这一格必须转发,而且方向比别的转发更要命:生产默认 `SESSION_CACHE_TTL_SEC=300` 会把真店
      * 包进本类,于是 boot 递给 `assertRetentionCapability` 的就是**包装层**。core 对缺席是 fail-closed
@@ -111,7 +111,7 @@ export declare class CachingSessionStore implements SessionStore {
      */
     readonly retention?: RetentionDeclaration;
     /**
-     * #292 C18 —— 内层店的 **placement 声明**转发。
+     * [ref] C18 —— 内层店的 **placement 声明**转发。
      *
      * 🔴 这一格与 {@link retention} 是同一条教训的同一族(而且更狠):生产默认 `SESSION_CACHE_TTL_SEC=300`
      * 把真店包进本类,于是 boot 递给 core 的就是**包装层**。core 的铸造门判「row store ∧ **session 店声明**」
@@ -120,7 +120,7 @@ export declare class CachingSessionStore implements SessionStore {
      * 只读快照而非 getter:声明是店的构造期常量(会变的声明本身就是缺陷)。
      */
     readonly placements?: SessionStore["placements"];
-    /** #292:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
+    /** [ref]:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
      *  是包装层,不转发 = 分区腿静默不可用、暖命中的 claim 关门静默失效。缺席则不设(诚实降级)。 */
     readonly listPlaced?: (kind: "subagent", opts?: {
         olderThanMs?: number;