@sema-agent/server 7.54.0 → 7.55.0

package/dist/runs.js

@@ -400,6 +400,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                     abortSignal: cancelCtrl.signal,
                     ...(spec.sessionId ? { sessionId: spec.sessionId } : {}),
                     emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
+                    emitRevoke: (f) => approvalEmit(f),
                     legKey: "",
                     ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
                 }, withQuestion)

package/dist/tool-approval.d.ts

@@ -2,7 +2,8 @@ import type { IncomingMessage } from "node:http";
 import { type AskRequest, type AskOutcome, type RuleOffer } from "@sema-agent/core";
 import { type CardRulePersisted, type RuleConsentLane } from "./rules-consent.js";
 import { type RuleOffersAbsence, type ApprovalRequestFrame, type ApprovalRevokeFrame, type RuleEvidenceProjection } from "./approval-card.js";
-import type { ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import { type ApprovalAskStore } from "./plugins/approval-ask-store-sql.js";
+import type { ApprovalAskAuditSink } from "./approval-ask-audit-store.js";
 import { type GovernanceAskMarks } from "./governance-ask-marks.js";
 /** [ref]:审批 gate kind 闭集(core gateMatch 的 `human`/`irreversible_ask` ↔ outcome.gate "policy_ask")。
  *  此前 7 份手写副本散在两只 checkpoint store 的数组/SQL 字面与 /decide 守卫——core 加审批味 kind 时
@@ -329,8 +330,9 @@ export interface ToolApprovalRunContext {
     owner: string | null;
     emit: (frame: ToolApprovalFrame) => void | Promise<void>;
     /**
-     * [ref] 车6:**批级撤卡帧**(`approval_revoke`,live only —— 语义见 approval-card.ts 的
-     * `ApprovalRevokeFrame` 顶注)的投递口。
+     * [ref] 车6:**批级撤卡帧**(`approval_revoke`,语义与发射面见 approval-card.ts 的
+     * `ApprovalRevokeFrame` 顶注 —— [ref] 起 bg/resume durable 腿的钩子写本腿账本,sync 腿仍 live)
+     * 的投递口。
      *
      * 🔴 为什么是**独立的可选钩子**而不是给 `emit` 的入参加宽:`emit` 是既有 `tool_approval` 活卡腿的
      * 通道,它的消费方(装配点 + 全部存量帧断言面)今天只认那两种帧;把入参改成联合会强迫每一个消费点
@@ -339,9 +341,8 @@ export interface ToolApprovalRunContext {
      * 车4 域)可以与 `approval_request` 的发射点**同批**接上。
      *
      * 缺席 ⇒ 本连接不收撤卡帧;壳侧的结构补偿恒是重连 preamble 的全量对账基准。
-     * (原注拿「`approval_request` 今天也还没接上发射点」作同栏类比 —— 那个类比已被 60846e6 证伪:呈卡口
-     * 三腿都接上了,而本钩子至今只有 sync 腿接 live 口。两者不再同栏,类比句因此删掉,别再据它推断
-     * 「两族都还没接线」。)
+     * (接线现状:[ref] 起三腿全接 —— sync 腿 live 口(`routes/tasks.ts`),bg/resume 两腿 durable
+     * append(`runs.ts` / `http/server.ts`),与 `emitCard` 的三腿同批对齐。)
      */
     emitRevoke?: (frame: ApprovalRevokeFrame) => void | Promise<void>;
     /**
@@ -603,6 +604,17 @@ export declare function resolveApprovalLeg(input: {
 export declare class ToolApprovalCoordinator {
     private readonly als;
     private readonly pending;
+    /** [ref] codex R3-1 / R4-1:终局阶梯**在飞店调用**(claim + 让路探针读)的计数 —— 按**持久 askId** 记(不按
+     *  本地登记闭包:同 askId 的重复登记 `pendingByAskId` 各领一顶帽 = 帽可被登记数绕开,池位按行数才是帽的
+     *  本义)。原始店 promise settle(resolve/reject 皆是)归还,归零即删键;帽值 {@link MAX_INFLIGHT_TERMINAL_CLAIMS}。 */
+    private readonly terminalClaimsInFlight;
+    /** {@link terminalClaimsInFlight} 的唯一写口:申请一格(帽满 ⇒ `undefined`),返回归还闭包。 */
+    private admitTerminalClaim;
+    /** 某 askId 此刻的在飞终局店调用数(claim + 让路探针)。阶梯据它分「调度争用」与「无人在飞」(R6-1);
+     *  判据钩子同读此口。 */
+    private terminalClaimsInFlightCount;
+    /** 判据钩子(生产路径不调)。 */
+    terminalClaimsInFlightForTest(askId: string): number;
     /** [ref] 车2(codex 交叉复审 round3 抓获真 finding,round5 精化成 Set):次级索引,键 = 持久层 askId
      *  (与 {@link pending} 的 wire-面 uuidv7 `id` 是两条独立的身份轴,顶注同精神)——只在 askStore 在场且
      *  这只 ask 真有 askId 时才登记。**同一 askId 下可能同时挂着不止一条本地条目**(round5 抓获:
@@ -696,6 +708,11 @@ export declare class ToolApprovalCoordinator {
      *  构造之后才装配;同款 holder 先例 = main.ts 的 `getRunDenySweep`)。取到 undefined ⇒ 该臂逐字回落
      *  修前 404,partial 部署安全。 */
     private readonly parkedRedeem;
+    /** [ref] 裁 (c):local 车道的 File ask **审计** sink(在场 ⇔ `DB_BACKEND=local` ∧ 审批面开着,装配点
+     *  `boot/coordinators.ts`)。三个挂线点:铸造(askBroadcast register 后)/ 决议(`settle()` 公共咽喉)/
+     *  腿闭(`runWithContext` finally)。**纯观察面**:sink 自己吞写失败并 `recordFailOpen`,任何一次审计
+     *  写都不得改变审批终局(店头注成文)。SQL 车道恒缺席(那里有真 ask 店)。 */
+    private readonly askAudit;
     constructor(opts?: {
         ttlMs?: number;
         /** [ref](案A):零活流铸造的 ask 的窗(见 {@link unreachedTtlMs})。装配点在协议**上场**时才传
@@ -721,6 +738,8 @@ export declare class ToolApprovalCoordinator {
         parkTombstoneTtlMs?: number;
         /** [ref]:per-principal 子帽(同上不接 env;生效值恒 `min(本值, parkTombstoneMax)`)。 */
         parkTombstonePerPrincipalMax?: number;
+        /** [ref] (c):local 车道审计 sink(见 {@link ToolApprovalCoordinator.askAudit})。 */
+        askAudit?: ApprovalAskAuditSink;
     });
     /**
      * [ref] R-13 C —— 「**无人可答**」这一类终局的**唯一**成形口(park 路由 vs deny 政策)。
@@ -732,8 +751,8 @@ export declare class ToolApprovalCoordinator {
      *  (e) 断连 `forceParkNow` / emit 全灭 / 写侧准入超限 —— 走本方法。
      *
      * **持久回放的两个口也归它管**(codex R1-F1 验真后收口,红先钉在
-     * `test/unattended-approval-policy.test.ts`):`convergeFromDurableState` 与 `ensureAsk` 幂等重入,
-     * 只要回放出来的是 `"unavailable"`(行 PARKING/PARKED)就过这个口。理由:那三处与臂 (a) 是**同一件
+     * `test/unattended-approval-policy.test.ts`):claim 败方真相的结算([ref] `settleFromClaimLoss`,前身
+     * `convergeFromDurableState`)与 `ensureAsk` 幂等重入,只要回放出来的是 `"unavailable"`(行 PARKING/PARKED)就过这个口。理由:那三处与臂 (a) 是**同一件
      * 事**(本 ask 的等待以「行进了投递面」收场,赢家可能是别的副本 / 上一次调用),不统一的话同一只 ask
      * 的终局会取决于「谁赢了那把 CAS」「重试没重试」—— 比残余更坏的不可解释性。人的**真决议**(回放出
      * `true`/`false`)当然不过这个口:那不是「无人可答」。
@@ -881,23 +900,33 @@ export declare class ToolApprovalCoordinator {
      */
     private sessionGrantUncontestedByRow;
     /**
-     * [ref] 恢复读口:一次带墙钟的 `getAsk`,把行翻译成 {@link RecoveryRead} 七态。**只读不写**(单赢者:终局
-     * 写点只有各臂的 CAS)。两处消费 —— 干净输后的 `convergeFromDurableState`(在 pending/unreadable 上退避)
-     * 与店未知态后的 `recoverFromUnknownStore`(只在 unreadable 上退避)—— 共用这**一份**映射,不各自
-     * `switch` 一遍(`replayTerminalAskRow` 仍是唯一的三态映射,这里只把它接到结算动作上)。
+     * [ref]:claim 败方读数的分类器 —— **零读**(真相已随 `claimed:false` 回来,384 §4.3-1「settle 自足」),
+     * 把 {@link AskTerminalClaimCurrent} 翻译成 {@link RecoveryRead} 五态。两处消费 —— `resolveLocalOutcome`
+     * 主阶梯与三臂的迟到回调(迟到输同样自足,律 3)—— 共用这**一份**映射(`replayTerminalAskRow` 仍是唯一的
+     * 三态行映射,这里只把它接到结算动作上)。
      *
-     * 沿革:前身 `readDecidedForRecovery`([ref] codex R3-F1,窗到期臂店报错支专用)只答「有没有真决议」,
-     * 且把「读失败」与「行不是 DECIDED」折成同一个 `undefined` —— 调用臂分不清「店真不可用」与「行就是没定」,
-     * 于是取消臂 / emit 全灭臂的同形缺口一直没法接同一条路(R4-F1/F2 登记的残余)。[ref] 把两种「不知道」
-     * 拆开(设计件 §2 K1/K2),三臂 catch 才统一得起来。[ref] 那条(行派生 approve 丢编辑)已随 [ref] 落列
-     * 收口:`approved` 臂带行上的 `updatedInput`。
+     * 沿革:[ref] 时代这里是恢复读口 `readRowForRecovery`(一次带墙钟的 `getAsk`,七态含 pending/unreadable),
+     * 前身 `readDecidedForRecovery`([ref] codex R3-F1)。「CAS 与读真相是两次店往返」= [ref]-R1 残余窗的病根
+     * ([ref]①):CAS 迟到干净输时真相不在答案里,补读又撞店不可用 ⇒ 人类决议丢失。[ref] 把读口整个撤掉:
+     * 争终局与读真相并成店的一次原子 claim,分类器只剩纯函数半场。[ref](行派生 approve 丢编辑)已随
+     * [ref] 落列收口:`approved` 臂带行上的 `updatedInput`。
      *
      * 行派生 approve 的两道守卫**在这里**施加(五处消费一份判据,见 {@link guardRowDerivedApprove}):
      *  · 弃单墓碑在场 ⇒ `parked`(park 路由,可逆可再批 —— 绝不把一个证不出载荷的放行交出去);
      *  · 编辑在飞 ⇒ `edit-in-flight`(codex R4-[critical] 同族口:载荷还在别人手里的那一拍按行结算 = 用裸
      *    `true` 抢在它前面;持有者随后必定自己结算)。
      */
-    private readRowForRecovery;
+    /**
+     * [ref] 让路探针(**只读、不争、不定局**):编辑在飞标记在场时 claim 阶梯刻意**不重打** claim(顶注:本臂
+     * 抢赢会把持有者正在提交的带编辑批准翻成 park),但一次**已落盘**的决议不该等到标记放开才被消费 ——
+     * codex [ref] R3-F1 的真窗:持有者回读慢于让路预算而标记仍在看门狗内 ⇒ 让路用尽走 park = 把已落盘批准
+     * 翻成 unavailable。探针 = 一次带墙钟的 `getAsk`;它**不是**败方真相的来源(那是 claim 答案,律 1),
+     * 只在 claim 被扣住的那几拍上不干扰地看一眼行:终态 ⇒ 交分类器(带载荷 approve 当拍兑现 / 负终态、
+     * PARKING 当拍结算 / 裸 approve 继续让);pending、行不在、读不出 ⇒ `undefined`,继续让路(有界)。
+     * 它只能**提前**兑现一个已落的决议,永远不会按意图定局 —— 这是它与 [ref] 恢复读口的本质差别。
+     */
+    private probeRowWhileYielding;
+    private classifyClaimLoss;
     /** [ref] codex R3-F2:同一 askId 下**其余本地注册**(重复注册,见 {@link pendingByAskId} 顶注)按
      *  **park 路由**收尾 —— 行已 PARKING,它们看的是同一条行,终局必须与赢家同形(`unattendedPolicy`
      *  由各自的闭包读同一个口,deny 部署上一起是 deny)。赢家自己此刻已 settle 过、已从集合里摘除,
@@ -943,11 +972,13 @@ export declare class ToolApprovalCoordinator {
         settled: number;
     };
     /**
-     * [ref] 车6:把一张**批级撤卡帧**投给给定的一组连接(live only —— 见 `ApprovalRevokeFrame` 顶注:
-     * 撤卡帧不进 durable tail,丢帧的结构补偿是重连 preamble 的全量对账基准)。
+     * [ref] 车6:把一张**批级撤卡帧**投给给定的一组连接(逐 ctx 分发 —— 见 `ApprovalRevokeFrame` 顶注:
+     * [ref] 起 durable 腿的钩子把帧落进本腿账本、sync 腿仍 live;丢帧的结构补偿是重连 preamble 的
+     * 全量对账基准)。
      *
      * 空名单不发(零信息的帧只会让壳多一次无意义的对账)。每路独立 catch:一路 emit 失败(连接刚死、
-     * durable-append 目标抖动)**绝不回滚已经落定的持久 CAS** —— 帧是通知,行才是真源。
+     * durable-append 目标抖动)**绝不回滚已经落定的持久 CAS** —— 帧是通知,行才是真源。[ref] 的 durable
+     * append 失败同落这只 catch(不新铸失败臂;账本行 VOID 是真源,撤帧丢失由 preamble 对账补偿)。
      */
     private emitRevokeTo;
     /**
@@ -1245,8 +1276,8 @@ export declare class ToolApprovalCoordinator {
      * R6 把弃单墓碑的兑现点收在 {@link notifyExternalDecision} 上,并自称「公共咽喉」—— 那句话**不成立**:
      * 树上还有三处**直接** `settle(true, …)` / 直接把 `true` 交回 core 的行派生回放(`convergeFromDurableState`
      * 的收敛臂、`ensureAsk` 幂等命中终局行的回放、窗到期报错臂的 `readDecidedForRecovery` —— [ref] 起前者与
-     * 后者合并成 `readRowForRecovery` 一个读口、三臂共用),它们跳过那个口。于是弃单之后从这三条路上仍能放出
-     * 原始命令。
+     * 后者合并成 `readRowForRecovery` 一个读口、三臂共用;[ref] 起读口撤销,同一份判据长在 claim 败方读数的
+     * 分类器 `classifyClaimLoss` 里),它们跳过那个口。于是弃单之后从这三条路上仍能放出原始命令。
      *
      * 收口形 = **一个判据函数、五处消费**(上面三处 + 轮询 + HTTP 观察者):把「行说 approve」这件事
      * 在弃单墓碑在场时翻译成 `"unavailable"`(park 路由,可逆可再批),其余取值逐字透传。