@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/hitl/parkRowBirthWait.d.ts

@@ -1,19 +1,13 @@
-/** 一次读面探测的判决(三态;见文件头「这个模块是什么」)。 */
 export type ParkRowProbe<Row> = {
     kind: 'row';
     row: Row;
-}
-/** 此刻没有可决断的行,且拿不出「已了结」的正面证据 ⇒ 可能只是还没出生。 */
- | {
+} | {
     kind: 'unborn';
     reason: string;
-}
-/** 有正面证据:这里没有本臂该决的事 ⇒ 再等也不会变(如行在但门种不属本臂)。 */
- | {
+} | {
     kind: 'settled';
     reason: string;
 };
-/** 有界重查环的判决。`waitedMs`/`probes` 是留证位(debug 档),不参与任何分支。 */
 export type ParkRowWaitVerdict<Row> = {
     kind: 'row';
     row: Row;
@@ -35,29 +29,11 @@ export type ParkRowWaitVerdict<Row> = {
     probes: number;
 };
 export interface ParkRowBirthWaitDeps<Row> {
-    /**
-     * 读一次真状态(第 N 次探测,N 从 1 起)。
-     *
-     * 🔴 `signal` **必须**被透传进真实读面(HTTP 请求等):它是本环对 `budgetMs` 的**执行手段** ——
-     * 环在窗尽时 abort 它,读面才真的被掐断。不接这个 signal 的 probe 会让「有界」退化成一句
-     * 口号:一次挂死的读面能把总窗拖到任意长。
-     */
     probe: (attempt: number, signal?: AbortSignal) => Promise<ParkRowProbe<Row>>;
-    /** 总窗上限(ms)。`<=0` ⇒ 恰一次 probe,不等(那一拍不设内部 deadline,与修前逐字同拍)。 */
     budgetMs: number;
-    /** 轮询间隔(ms);实际 sleep = min(intervalMs, 窗内剩余)。 */
     intervalMs: number;
-    /** 时钟(测试注入;缺省 Date.now)。 */
     now?: () => number;
-    /** sleep(测试注入;缺省 = 可中断等待,见 {@link parkRowPollDelay})。 */
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
-    /** 中断口(Esc/turn abort);每轮读,真停。 */
     signal?: AbortSignal;
 }
-/**
- * 有界、可中断地等一条 park 的待决行出生。语义与边界见文件头;绝不抛。
- *
- * 🔴 判决只有 `row` 一态可以往下走 —— `unborn`(窗尽)与 `aborted` 都必须由调用方翻成**如实的
- * 失败**,绝不许翻成「已决/已成功」(那正是 cli #269 的病)。
- */
 export declare function waitForParkRowBirth<Row>(deps: ParkRowBirthWaitDeps<Row>): Promise<ParkRowWaitVerdict<Row>>;

package/dist/hitl/parkRowBirthWait.js

@@ -1,62 +1,7 @@
-/**
- * hitl/parkRowBirthWait.ts — 「park 的待决行**还没出生**」这个第三态的有界等待(#265 上收件,
- * 2026-08-14;源形 = cli `src/sema/parkRowBirthWait.ts`,该文件自设计起就按候上收形写成零依赖)。
- *
- * ── 病(cli #269,plan 批准 → write 卡永不呈现)──────────────────────────────────────────────
- * `/v1/approvals` 的 pending 表里**没有**某个 park 的行,过去被单义化成「这件事已经决了」。
- * 真实世界有第三态:引擎刚被推进到下一只门,而门的行要等一次真实模型调用(实测 ~3s:plan
- * 批准 → 模型算出 Write 的参数 → 才铸审批行)才落库。在那个窗里读到的空表既不是「已决」
- * 也不是「没有这件事」,而是**还没出生**。
- * 把「未出生」当「已决」的代价 = 客户端按成功收口 → 呈现回执永远等不到 → 上一句「没能重开
- * 这张卡」的降级话,而那张卡三秒之后真的出生了却再没人去接 —— 用户看到的是会话死了。
- *
- * ── 这个模块是什么 ──────────────────────────────────────────────────────────────────────────
- * 把「行不在表」拆成**三态**并给一个有界、可中断的重查环:
- *   · `row`     —— 拿到一行可决断的行(唯一可以往下走的态);
- *   · `unborn`  —— 此刻没有可决断的行,但**没有任何正面证据**说明这件事已经了结 ⇒ 值得再看一眼;
- *   · `settled` —— 有正面证据说明这里没有本臂该决的事(如行在但门种不属本臂)⇒ 等待零意义,立即收口。
- * 判据纪律:`settled` 必须由**正面证据**得出;缺席本身永远只能得 `unborn`
- * (「不知道」不许渲成「已完成」)。
- *
- * ── 边界(承重,别削)────────────────────────────────────────────────────────────────────────
- *   · **恒至少探一次**:`budgetMs <= 0` ⇒ 恰一次 probe,行为与「不等」逐字相同(存量判决不漂,
- *     也让测试能把等待窗调成 0 拿回旧语义)。
- *   · **有界**:总窗 `budgetMs` 封顶,轮询间隔 `intervalMs`;窗尽如实回 `unborn`(不是回
- *     `settled` —— 等不到不等于已决,降级话在这一刻才是真话)。
- *   · **真可中断**:每一轮 probe 前、每一次 sleep 后都读 `signal.aborted`;缺省 sleep 自身也吃
- *     signal(包内共享叶 `abortableSleep`,不另铸第二份等待原语)。
- *   · **绝不裸固定拍当判据**:sleep 只是轮询节奏,判决恒来自下一次 probe 的真实读数。
- *   · probe 抛错按 `unborn` 处置(瞬时读面故障不该把有界重查提前判死),错误摘要进 reason ——
- *     调用方只在 debug 档消费,绝不上屏(凭证外溢面纪律)。
- *
- * ── 归层 ────────────────────────────────────────────────────────────────────────────────────
- * 「一条 park 的待决行到底出生了没有」是 wire 语义,三端(cli / desktop / web)都要问同一句;
- * 各端只注入自己的读面(cli = `approvals.list` + 归属判据),环本身共用这一份。行形走结构泛型,
- * 读面/时钟/sleep 全部注入 —— 本文件值级 import 只有包内 `abortableSleep`,零 SDK 零宿主。
- */
 import { abortableSleep } from '../abortableSleep.js';
-/**
- * 缺省轮询等待:signal 在场时直接借包内共享叶 {@link abortableSleep}(中止即刻 resolve 并清
- * timer),缺席时退化成纯定时。
- *
- * 🔴 **不另铸第二份等待原语**:仓内「怎么安全地睡一觉」只此一份(`abortableSleep.ts` 的头注
- * 写死了这条 —— D 族循环各自保留自己的节拍策略,但等待原语统一)。两份并存的代价不是重复代码,
- * 是两条会各自漂的中止语义。
- * 🔴 timer **不 unref**(与 abortableSleep 同判据):调用方正 await 本环拿判决,轮询窗里这只
- * timer 可能是事件循环里唯一的活,unref 会让进程在等待中途直接退出、判决连同它要说的那句真话
- * 一起蒸发。代价上限 = 一个 intervalMs 的进程存活延长。
- */
 function parkRowPollDelay(ms, signal) {
-    // 无 signal 的调用方(端没接中断口)也走同一个叶:给它一只**永不 abort** 的 signal,而不是就地
-    // 再写一个裸 setTimeout —— 那就是第二份等待原语的起点。
     return abortableSleep(ms, signal ?? new AbortController().signal);
 }
-/**
- * 有界、可中断地等一条 park 的待决行出生。语义与边界见文件头;绝不抛。
- *
- * 🔴 判决只有 `row` 一态可以往下走 —— `unborn`(窗尽)与 `aborted` 都必须由调用方翻成**如实的
- * 失败**,绝不许翻成「已决/已成功」(那正是 cli #269 的病)。
- */
 export async function waitForParkRowBirth(deps) {
     const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
     const sleep = typeof deps.sleep === 'function' ? deps.sleep : parkRowPollDelay;
@@ -65,27 +10,15 @@ export async function waitForParkRowBirth(deps) {
     const startedAt = now();
     let probes = 0;
     let lastReason = 'no decidable pending row for this park';
-    // 🔴 经函数读,别直接读 `deps.signal?.aborted`:tsc 的控制流分析会拿环顶那一次判断把它窄成
-    // `false | undefined`,sleep 之后的第二次判断当场被判「不可能为 true」而报错 —— 而真实世界里
-    // 正是 sleep 期间它会翻。函数返回值走声明类型,不参与那条窄化链。
     const aborted = () => deps.signal?.aborted === true;
-    /** 一拍探测(读面故障按 unborn,绝不外溢)。 */
     const safeProbe = async (attempt, signal) => {
         try {
             return await deps.probe(attempt, signal);
         }
         catch (e) {
-            // 读面瞬时故障 ≠ 已决:按未出生继续轮询(有界,窗尽自然如实收口)。
             return { kind: 'unborn', reason: `probe threw: ${String(e)}` };
         }
     };
-    /**
-     * 🔴 把**剩余预算**套在每一拍 probe 上:deadline 只在 `await probe` **之后**判,等于什么都没
-     * 界住 —— 一次挂死的 `approvals.list` 能把「15s 有界」拖到 SDK 请求超时那么长,而中断也要等
-     * 那个 promise 落地才被看见。这里给每一拍配一个内部 controller:窗尽即 abort(读面真被掐,
-     * 不只是被放弃)并当拍判窗尽;外部 signal 与它合流,Esc 同样当拍生效。
-     * 零窗形(budgetMs<=0)**不设**内部 deadline —— 那一拍就是「修前那一次 list」,不许被新机制改语义。
-     */
     const probeWithinRemaining = async (attempt, remainingMs) => {
         if (budgetMs <= 0)
             return safeProbe(attempt, deps.signal);
@@ -97,36 +30,23 @@ export async function waitForParkRowBirth(deps) {
                 resolve('deadline');
             }, Math.max(1, remainingMs));
         });
-        // 🔴 外部中断**自己也是竞速的一臂**,不能只靠「signal 传下去 ⇒ 读面自己会拒」:那是对 probe
-        // 实现的一个假设,而假设不成立时(probe 吞了 signal / 读面 abort 得慢)Esc 之后这一拍要一直
-        // 等到窗尽才被看见 —— 「UI 说停了、后台还在等」正是本模块承诺不会发生的那件事。
         const caller = deps.signal;
-        /**
-         * 把中止**传导到真正交给 probe 的那只 signal**(清理动作:它自己的异常绝不挡住中止判决)。
-         * 🔴 承重理由:`AbortSignal.any` 缺席的宿主上 `merged` 就是 `ctl.signal`,而外部中断只赢竞速、
-         * 不会传导到它 —— finally 又把 deadline timer 清了,于是那一拍挂死的读面**永远**不会被 abort
-         * (判决说「停了」,后台请求活到进程结束)。两个中止入口(进拍即已中断 / 等待期间翻)共用这一份。
-         */
         const abortProbeLane = () => {
             try {
                 ctl.abort();
             }
             catch {
-                /* abort 面异常绝不挡住中止判决(唯一后果是那一拍的读面少收一次 abort) */
             }
         };
         let onAbort;
         const externalAbort = new Promise(resolve => {
             if (caller === undefined)
-                return; // 永不 settle:race 另有两臂,无害
+                return;
             if (caller.aborted) {
-                // 进这一拍时就已中断 ⇒ probe 拿到的那只 signal 必须是**已中止**的(一个不查 `aborted`、
-                // 只挂 'abort' 事件的读面否则会一直挂着)。
                 abortProbeLane();
                 resolve('aborted');
                 return;
             }
-            // 🔴 先传导中止**再** resolve(见 {@link abortProbeLane}):否则「可中断」只是判决面的说法。
             onAbort = () => {
                 abortProbeLane();
                 resolve('aborted');
@@ -135,34 +55,25 @@ export async function waitForParkRowBirth(deps) {
                 caller.addEventListener('abort', onAbort, { once: true });
             }
             catch {
-                onAbort = undefined; // 没有事件面的 signal 形:退化成环顶那次 aborted() 读
+                onAbort = undefined;
             }
         });
-        // 合流(Node ≥20.3 / 现代浏览器原生);缺席时退化成只吃内部 deadline —— 中止仍由上面那一臂
-        // 当拍生效。`typeof` 探的是**运行期**在场,不是类型面缺口。
         const merged = caller !== undefined && typeof AbortSignal.any === 'function' ? AbortSignal.any([caller, ctl.signal]) : ctl.signal;
         try {
             return await Promise.race([safeProbe(attempt, merged), deadline, externalAbort]);
         }
         finally {
-            // timer 必清:竞速由 probe 赢时它还挂着,不清会把进程按 remainingMs 拖活一拍。
             if (timer !== undefined)
                 clearTimeout(timer);
-            // 监听器必摘:环可以跑几十拍,不摘就是几十个挂在调用方 signal 上的闭包。
             if (onAbort !== undefined && caller !== undefined) {
                 try {
                     caller.removeEventListener('abort', onAbort);
                 }
                 catch {
-                    /* 监听面异常绝不反噬等待环 */
                 }
             }
         }
     };
-    // B-005(test [6497] 异源复审轨,cli 1.0.101 定谳):上一拍读面的**实测时延**。窗尾剩余若已不够再答一次
-    // (remaining < lastProbeMs),再起一拍只会被内部 deadline 切成 'deadline' 出站——那一拍一个字都没读到,
-    // 却让宿主(每拍先清 evidence 的形,cli askParkReopen)把此前成立的「读面答了、零属主行」证据抹掉
-    // ⇒ pendingRowGone 不置 ⇒ 陈旧 park 两选卡不出。窗尾不起注定超时的探测,按已有证据出站。
     let lastProbeMs = 0;
     for (;;) {
         if (aborted())
@@ -176,8 +87,7 @@ export async function waitForParkRowBirth(deps) {
         probes += 1;
         const probeStartedAt = now();
         const outcome = await probeWithinRemaining(probes, budgetMs - (now() - startedAt));
-        lastProbeMs = now() - probeStartedAt; // 瞬答(0)不设闸:只有真有时延的读面才可能在窗尾被切
-        // 读面挂着的时候用户按了 Esc ⇒ 当拍停(判决优先于窗尽,两者都成立时中断更准确)。
+        lastProbeMs = now() - probeStartedAt;
         if (outcome === 'aborted' || aborted())
             return { kind: 'aborted', waitedMs: now() - startedAt, probes };
         if (outcome === 'deadline') {