@sema-agent/client-core 0.12.1 → 0.13.0

package/dist/headlessPermissionModeWire.js

@@ -28,11 +28,19 @@
  */
 import { permissionModeField } from './permissionWireCaps.js';
 import { hostEnv } from './hostEnv.js';
+import { lastFlagValue } from './argvFlagValue.js';
 /** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
 export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
 /** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
  *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
 const HEADLESS_PERMISSION_WIRE_MODE_TUPLE = ['default', 'plan', 'acceptEdits', 'bypassPermissions', 'auto'];
+/**
+ * 🔴 [2006] B-CC-2(2026-07-29):`readonly PermissionMode[]` 的注解只保证「元素合法」,**从不保证
+ * 穷举** —— server 五模式表加第六个词、`PermissionMode` 跟了而这张运行时镜像没跟 ⇒ 编译期全绿,
+ * 而那个词从 env 旋钮走进来会被判非法、一次性 warn 后**静默回落**(部署以为设了、实际没设)。
+ * 补「类型 → 常量」那半边;之前的看守只有 `length > 0 && includes('plan')`(对这个方向零判别力)。
+ * `Covers`(REF-CC-145/dup-12,P3 wave1 卡C-argv)改吃共用叶 typePins.ts——四份逐字重复钉之一。
+ */
 const _headlessPermissionModePins = [true, true];
 void _headlessPermissionModePins;
 export const HEADLESS_PERMISSION_WIRE_MODES = HEADLESS_PERMISSION_WIRE_MODE_TUPLE;
@@ -40,33 +48,28 @@ export const HEADLESS_PERMISSION_WIRE_MODES = HEADLESS_PERMISSION_WIRE_MODE_TUPL
  * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
  * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
  * 返回 undefined = flag 车道未显式表态。
+ *
+ * REF-CC-143(dup-07)收编:`--permission-mode` 的取值改吃共用 lastFlagValue(argvFlagValue.ts,
+ * `onMissingValue:'latch-previous'`)——旧手写循环对「某一次 occurrence 缺值」的处置是跳过这一次、
+ * 锁存(latch)住之前已经取到的合法值,不是把整个旗塌缩成「从没写过」(`--permission-mode plan
+ * --permission-mode` 的旧行为是 `mode==='plan'`,不是 `undefined`)。共用叶的缺省策略
+ * (`'invalidate'`,sandboxWire/scenarioWire 用)会把这个情形塌缩成「有旗无值」,与本函数原有语义
+ * 不符,所以本调用点显式传 `'latch-previous'` 保住旧行为——这才是任务书说的「各调用方保持自己现有
+ * 对缺值的处置」(wave1 回炉修复,blocker:此前误用了共用叶的 invalidate 缺省,详见 commit 记账)。
+ * `--dangerously-skip-permissions` 的存在性判别不属于「取某旗最后值」这个不变量,单独一个小循环即
+ * 可,零重复。
  */
 export function permissionModeFromArgv(argv) {
-    let mode;
-    let dsp = false;
+    const flag = lastFlagValue(argv, '--permission-mode', 'latch-previous');
+    if (flag.present && flag.raw !== undefined)
+        return flag.raw;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === '--permission-mode') {
-            const v = argv[i + 1];
-            if (typeof v === 'string' && !v.startsWith('-')) {
-                mode = v;
-                i++;
-            }
-        }
-        else if (a?.startsWith('--permission-mode=')) {
-            mode = a.slice('--permission-mode='.length);
-        }
-        else if (a === '--dangerously-skip-permissions') {
-            dsp = true;
-        }
-        else if (a === '--') {
+        if (a === '--')
             break; // POSIX 约定:-- 之后不是 flag
-        }
+        if (a === '--dangerously-skip-permissions')
+            return 'bypassPermissions';
     }
-    if (mode !== undefined)
-        return mode;
-    if (dsp)
-        return 'bypassPermissions';
     return undefined;
 }
 // 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)

package/dist/headlessReconnectWire.d.ts

@@ -56,7 +56,13 @@
  * 消费面兜住。
  */
 import type { AgentEvent } from '@sema-agent/sdk';
-/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。 */
+/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。
+ *  选值:design/HEADLESS-RECONNECT-DESIGN.md §2 铁律 5 只钉了「有界」与这个数,未留更细的推导
+ *  —— 诚实记账,不倒推一个当时没写下来的公式。可核实的取值依据是本环自身的形状(REF-CC-148
+ *  普查记账):每次尝试是两次真网络往返(重试环里的 `probe(deps.baseUrl)` + `deps.openEvents(…)`)
+ *  且两次尝试之间**零退避**,预算越大,在一个真死引擎上耗尽这个环、落到诚实判死文案之前的墙钟代价就越高
+ *  ——2 是「给瞬时抖动一次重试余地」与「死引擎上不过度拖延判死」之间的保守取值,不是精算结果;
+ *  若上游把撕裂形态改成更常见的可重连态,这个数可能需要上调(域词表-19 已留此账)。 */
 export declare const HEADLESS_RECONNECT_MAX = 2;
 /** GET /v1/runs/:id 的 run row 终局子集(SDK RunRecord;字段防御性读)。 */
 export interface RunRowLike {

package/dist/headlessReconnectWire.js

@@ -1,6 +1,12 @@
 import { isSseIdleError, probeEngineAlive } from './sseIdleTriage.js';
 import { hostEnv } from './hostEnv.js';
-/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。 */
+/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。
+ *  选值:design/HEADLESS-RECONNECT-DESIGN.md §2 铁律 5 只钉了「有界」与这个数,未留更细的推导
+ *  —— 诚实记账,不倒推一个当时没写下来的公式。可核实的取值依据是本环自身的形状(REF-CC-148
+ *  普查记账):每次尝试是两次真网络往返(重试环里的 `probe(deps.baseUrl)` + `deps.openEvents(…)`)
+ *  且两次尝试之间**零退避**,预算越大,在一个真死引擎上耗尽这个环、落到诚实判死文案之前的墙钟代价就越高
+ *  ——2 是「给瞬时抖动一次重试余地」与「死引擎上不过度拖延判死」之间的保守取值,不是精算结果;
+ *  若上游把撕裂形态改成更常见的可重连态,这个数可能需要上调(域词表-19 已留此账)。 */
 export const HEADLESS_RECONNECT_MAX = 2;
 /** SEMA_DEBUG 探针(headless `-p` 车道 Ink 未挂载,stderr 可用;绝不带凭证/帧内容)。 */
 function debugLog(msg) {
@@ -72,10 +78,22 @@ export async function* withHeadlessR1Reconnect(live, deps) {
     let attempts = 0;
     let lastSeenSeq; // R1 去重锚(runs.events SSE id = 账本 seq;见模块头选型)
     const probe = deps.probeAlive ?? probeEngineAlive;
+    // REF-CC-148(域词表-19):originalTearErr 在环内从不被重写(它是进入本重试环前唯一捕获的
+    // 错误对象),所以这个判型是**环不变式**——算一次即可,不必逐轮重算。
+    // wave1 回炉复审(codex blocker):求值时机必须排在铁律 3(用户中止恒先行)**之后**才对 main
+    // 逐字——main 是「每轮入口先查 aborted,再判型」,若把判型提到循环顶(环外、抢在第一轮的
+    // aborted 检查之前),当 originalTearErr 是一个 `.name` getter 会抛的畸形错误对象、且入环时
+    // signal 已经 aborted 时,新顺序会先让 isSseIdleError 抛出**那个畸形对象的二次异常**,盖过
+    // 本该抛出的 originalTearErr,违反铁律 3。改法:惰性 memo——用 `undefined` 起始态占位「尚未算
+    // 过」(合法返回值只有 true/false),真正求值仍只发生一次,但**排在每轮的 aborted 检查之后**,
+    // 与 main 的求值顺序逐字一致,「只判一次」的不变量原样保留。
+    let isRecoverableTear;
     for (;;) {
         if (deps.signal?.aborted)
             throw originalTearErr; // 铁律 3:用户中止恒先行,绝不进重连分支
-        if (!isSseIdleError(originalTearErr))
+        if (isRecoverableTear === undefined)
+            isRecoverableTear = isSseIdleError(originalTearErr);
+        if (!isRecoverableTear)
             throw originalTearErr; // 只救 engine-alive-idle 的静默撕裂形
         const taskId = deps.getTaskId();
         if (!taskId)

package/dist/hitl/approvalsFeed.js

@@ -1,4 +1,5 @@
 import { hostLog } from '../host.js';
+import { unrefTimer } from '../unrefTimer.js';
 /**
  * pending 列表的稳定摘要 —— 只在**内容变了**的时候发快照。
  * 键里带 `boundInputHash`:同一条 pending 的绑定被服务端换掉(TOCTOU 场景)也算变化,
@@ -36,10 +37,9 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     const stats = {
         pushEvents: 0, heartbeats: 0, polls: 0, listErrors: 0, streamFailures: 0, snapshots: 0,
     };
+    /** 域词表-14 收编:「怎么调 unref」的单一实现见 unrefTimer.ts,本函数只是就地起个短名。 */
     function arm(t) {
-        ;
-        t.unref?.();
-        return t;
+        return unrefTimer(t);
     }
     async function take(via) {
         if (stopped)
@@ -91,25 +91,44 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
                 await take('poll');
                 if (mode === 'poll')
                     schedulePoll();
-            })();
+            })().catch(e => {
+                // REF-CC-024 ①:take() 理论上自己兜底(见 take() 内的 try/catch),但这是它逃逸时的最后一道
+                // 接盘 —— 缺了它,轮询定时器的回调体抛出会变成 unhandled rejection(Node 默认致命)。
+                hostLog('debug', `approvalsFeed: poll leg threw unexpectedly (take() should have self-caught): ${String(e)}`);
+            });
         }, pollIntervalMs));
     }
+    /**
+     * 与 schedulePoll 对称(域词表-18):**幂等卫兵**(retryTimer 已在飞则不再排一个)+ **回调首行
+     * 自清**(否则 retryTimer 触发后仍持有已死句柄,degradeToPoll 若被再次调用会直接覆盖它而不清掉
+     * 旧的——旧的照样触发一次 `void runStream()`,两条 push 腿并行 = 双倍取件)。
+     */
     function scheduleStreamRetry() {
         if (stopped || ac.signal.aborted || streamRetryMs <= 0)
             return;
         if (!client.approvals.stream)
             return;
+        if (retryTimer !== undefined)
+            return;
         retryTimer = arm(setTimeout(() => {
+            retryTimer = undefined;
             if (stopped || ac.signal.aborted)
                 return;
             hostLog('debug', 'approvalsFeed: retrying push leg (降级是暂时的,服务端升级后不该还要重启客户端)');
             void runStream();
         }, streamRetryMs));
     }
-    function degradeToPoll(why) {
+    /**
+     * REF-CC-024 ③:`real`(缺省 true)只计**真正的** stream 故障(抛出 / 空转结束)进
+     * `stats.streamFailures`。「SDK 根本没有 `approvals.stream` 这个动词」不是失败,是能力缺席
+     * (老 SDK / mock)——此前无条件 `++` 会让这类宿主在 t=0 就报 streamFailures=1,而文件头
+     * 38-42 正是拿这个数卖「区分『连着但没事发生』与『断了』」,能力缺席被计成故障就说反了。
+     */
+    function degradeToPoll(why, real = true) {
         if (stopped)
             return;
-        stats.streamFailures++;
+        if (real)
+            stats.streamFailures++;
         if (mode !== 'poll') {
             hostLog('debug', `approvalsFeed: push leg unavailable (${why}) — falling back to polling every ${pollIntervalMs}ms`);
         }
@@ -120,7 +139,7 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
     async function runStream() {
         const stream = client.approvals.stream;
         if (!stream) {
-            degradeToPoll('SDK has no approvals.stream (old SDK / mock)');
+            degradeToPoll('SDK has no approvals.stream (old SDK / mock)', false);
             return;
         }
         try {
@@ -162,7 +181,11 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
         if (client.approvals.stream)
             void runStream();
         else
-            degradeToPoll('SDK has no approvals.stream (old SDK / mock)');
+            degradeToPoll('SDK has no approvals.stream (old SDK / mock)', false);
+    }).catch(e => {
+        // REF-CC-024 ①:同款接盘(见 schedulePoll 里那份同款注释)——首帧取件是唯一没被 try/catch
+        // 包住的调用点之一,这里补上不让它成为 unhandled rejection。
+        hostLog('debug', `approvalsFeed: initial take() threw unexpectedly (take() should have self-caught): ${String(e)}`);
     });
     return {
         stop() {

package/dist/hitl/askGateWire.d.ts

@@ -22,6 +22,21 @@
  *   同时进 bundle ⇒ overlay responder 注册在一份、`publishQuestionFrame` 发到另一份 = 对话框
  *   弹出来但没人收答(静默挂死)。
  *
+ * ── REF-CC-032(2026-08-02,P3 A 族压轴卡 askgate-split;设计输入 = P1 lens-giant-split SPLIT-12)──
+ *
+ * 本文件从 369 行的单函数塌成**驱动 + 公开面**。三刀落在同目录三个新文件,分工与各自头注一致:
+ *   ① `gateLedger.ts` —— 8 个集合 + 3 个记账标量收成一个台账对象并给出动词。拆分的真约束就是
+ *      「同一个容器有内环、外环两个写者」(`heldAskEnds` / `deniedCalls` / `resolvedAnswers` /
+ *      `endedCalls` 四个各自都有两处写点),收口后容器只剩一个写者。
+ *   ② `frameRouter.ts` —— 内环帧路由:一帧进、一个 `FrameAction` 出。tool_end 的 5 条分支是
+ *      **有序**的(分类器 deny 的结构性签名必须先于 fs HOLD/REJECT 判),注册表化后顺序写成数据
+ *      并配一条加载期断言钉死。共享词汇(`AskGateWireDeps` / `isAskTool` / 两个 CC 逐字常量 /
+ *      park 形状谓词)也落在那里 —— 它是内外环都够得着的最低模块。
+ *   ③ `parkResolver.ts` —— 外环 park 决断:`reattach` 还是 `failsoft`,两条 hostLog 与 hop 预算
+ *      全在那里。
+ * 本文件只剩:双层驱动循环(内环读流吐帧、外环决断后换流)+ 对外 re-export。**公开面一个名字
+ * 都没动**(`export *` 经本文件出去的四个值 + 四个类型全部原位可达)。
+ *
  * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
  *
  * liveHitlAskWire — §4④ AskUserQuestion 的 suspended↔overlay 桥(engine 1.163 HITL 语义,2026-07-12)。
@@ -54,107 +69,23 @@
  *   (`selected ⊆ options`,off-list 进 note)。
  */
 import type { AgentEvent } from '@sema-agent/sdk';
-import { type HitlClientLike } from './hitlBridge.js';
-import { type QuestionAnswer } from '../liveQuestionStore.js';
-import { type RespondToolApprovalFn } from './toolApprovalWire.js';
-import { type ClassifierDenyVerdict } from '../classifierVerdictWire.js';
-/** footer 通知(壳 `AppState.notifications.current` 的形)。 */
-export interface HitlNotice {
-    key: string;
-    text: string;
-    color: 'warning';
-    priority: 'immediate';
-    timeoutMs: number;
-}
-/** HITL 的宿主副作用面 —— 通知上屏 + 分类器 deny 的端侧记账。 */
-export interface HitlHostSurface {
-    /** 立即顶到 current(壳:`notifications.current = notice`,queue 不动)。 */
-    showNotice(notice: HitlNotice): void;
-    /** **仅当** current 仍是这个 key 时清掉(壳原文的 if-still-mine 语义 —— 否则会误清别人的通知)。 */
-    clearNoticeIfCurrent(key: string): void;
-    /** 分类器 deny 裁决的宿主副作用:footer 通知 + /permissions Recent Denials 记账(壳资产)。 */
-    surfaceClassifierDeny(toolName: string, verdict: ClassifierDenyVerdict): void;
-}
-/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
-export declare function installHitlHostSurface(surface: HitlHostSurface | null): () => void;
-/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
-export declare function installHitlHostSurfaceFor(sessionKey: string, surface: HitlHostSurface | null): () => void;
-/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
-export declare function hitlHostSurfaceMisses(): number;
-/** W1 带 key 变体(miss 计数逐键)。 */
-export declare function hitlHostSurfaceMissesFor(sessionKey: string): number;
-/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
-export declare function hitlHostSurfaceFor(sessionKey: string): HitlHostSurface | null;
-/** 测试钩:卸口 + 清计数。 */
-export declare function _resetHitlHostSurfaceForTest(): void;
-/**
- * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(搬迁差分 2)。deny 后重放 tool_end 的
- * render 面 stamp 用 —— vendored `renderToolUseRejectedMessage` 渲 `User rejected <op> to <path>`。
- * 🔴 pure 门 B7 段:包内冻结字面量(无条件)+ 壳树全树扫描「每一处声明都逐字节相同」(壳树缺席=跳过)。
- */
-export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
-/** 本桥消费的 wire 面(@sema-ai/sdk AgentClient 的结构切片,mock 可注入)。 */
-export interface AskGateWireDeps {
-    /** approvals.list/decide + assistant(HitlBridge 的 client 切片)。 */
-    client: HitlClientLike;
-    /** GET /v1/runs/:id/events — decide 后的续流 attach(lastEventId 续传)。 */
-    runsEvents: (taskId: string, opts?: {
-        signal?: AbortSignal;
-        lastEventId?: string;
-    }) => AsyncGenerator<AgentEvent>;
-    /** POST /v1/tool-approvals/:id/respond(server 1.191 同步帧腿,[830]①)。缺省=不消费
-     *  tool_approval 帧(帧被吞、引擎按自身 fail-closed TTL 自决)——mock/旧引擎路径零影响。 */
-    respondToolApproval?: RespondToolApprovalFn;
-}
-/** core 对被 gate/连坐 abort 的 call 铸的 tool_end 载体(逐字;desktop session-host 真引擎实测
- *  同款)——HOLD 谓词锚它做**精确等值**,普通工具错的输出是各自错误文案,永不进 HOLD。 */
-export declare const ENGINE_ABORT_TOOL_RESULT = "Operation aborted";
-/** CC AskUserQuestion outputSchema 形状(答过的问题卡):toolResult 的 `ask-user-question` arm
- *  消费它渲真实答案卡(否则「诚实缺席」路径会把这张卡渲成结果不可用)。 */
-export interface AskAnsweredOutput {
-    type: 'ask-user-question';
-    questions: unknown[];
-    answers: Record<string, string>;
-    annotations?: Record<string, {
-        notes?: string;
-    }>;
-}
-export type GateOutcome = {
-    kind: 'decided';
-    gatedCallId?: string;
-    answered?: AskAnsweredOutput;
-} | {
-    kind: 'aborted';
-    gatedCallId?: string;
-} | {
-    kind: 'failed';
-    gatedCallId?: string;
-    reason: string;
-};
-/** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
- *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
-export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
-/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
- *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
- *  只是多一行良性 warn,比锁死无线索诚实)。 */
-export declare const CANCEL_DENY_BUDGET_MS = 2000;
-/** warn 行文案(测试锁字面)。 */
-export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
-/**
- * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面)。
- * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
- *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
- *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
- *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
- *   - HitlSafetyError code==='no_pending' ⇒ 良性静默(pending 已被别处消解/过期 —— run 没锁;
- *     hitlBridge decideTool 的同款语义,那里的静默维持不动)。
- */
-export declare function observeCancelByDeny(settle: Promise<unknown>, taskId: string): void;
+import { type AskGateWireDeps } from './frameRouter.js';
+export { HITL_REJECT_MESSAGE, ENGINE_ABORT_TOOL_RESULT } from './frameRouter.js';
+export type { AskGateWireDeps } from './frameRouter.js';
+export type { AskAnsweredOutput } from './gateLedger.js';
+export { toAnsweredOutput, isAlreadyResolvedGateReason } from './parkResolver.js';
+export type { GateOutcome, GateFailureCode } from './parkResolver.js';
 /**
  * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。
  * 其它事件原样透传;非 AskUserQuestion 的 gate 保持现状。fail-soft:任何桥内失败回退为
  * 「flush 毒化 tool_end + 原样终帧」(= 修复前行为)。
  *
+ * 双层循环(REF-CC-032 后只剩驱动骨架):
+ *   · 内环 `for await` 读流 —— 每帧先记 seq、再判扣留帧放行、再交 `routeFrame` 定处置;
+ *     `park` 动作 break 出内环。
+ *   · 外环 `while` —— `resolvePark` 决断:`reattach` 就换一条 `runs.events` 流接着读
+ *     (hop 预算在 resolver 内按 `hops` 判),`failsoft` 就吐完 events 收场。
+ *
  * @param source 上游 AgentEvent 流(tasks.stream 或 runs.events,已过 demuxQuestionFrames)。
  * @param opts.taskId runs.events 消费时已知的 run handle(sync leg 从 suspended done 捕获)。
  */