@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/hitl/hitlBridge.d.ts

@@ -1,122 +1,28 @@
-/**
- * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/seam/adapter/upstream/hitlBridge.ts`(491 行)
- *    **整条进包**。这是 HITL 的心脏 —— suspended ↔ canUseTool 的编组层。
- *
- * 🔴 **D-1 两元组是安全不变量,原样搬,一个字节不改**(设计稿 §3 B7 原文):
- *    `bindingOf()`(下方 §1 末)把人**看见的那一行** `PendingCheckpoint` 上的
- *    `boundCallId` + `boundInputHash` **逐字回显**进 `approvals.decide(...)` —— 绝不本地重算
- *    (重算出来的假不匹配会 fail-close 掉一个合法审批);409 `approval_binding_mismatch`
- *    是**安全信号**,抛 `HitlSafetyError('binding_mismatch')`,**绝不自动重试**。
- *    这两段代码在 `scripts/run-client-core-pure-test.mjs` 的 B7 段有**字节级**断言
- *    (常量字面量比对 + 壳树在场时的双向比对),改一个字符就红。
- *
- * ── 搬迁差分(只有三处,全在类型/依赖面,零运行时语义变化)────────────────────────────────
- *  1. `eventSeq` 从 `../types.js` → `../adapter/types.js`(B3 已搬入本包,同一份实现)。
- *  2. CC 的 `PermissionDecision` / `PermissionDenyDecision` / `CanUseToolFn` 三个类型住在壳的
- *     `src/types/permissions.ts` + `src/hooks/useCanUseTool.tsx`(它们拖 `ToolType` /
- *     `ToolUseContext` / `AssistantMessage` 整张 CC 内部类型图,不属于 wire 词汇表)。
- *     本包改用**结构切片 + 泛型**:`HitlPermissionDecisionLike`(本桥真正读的三个键)与
- *     `HitlCanUseToolFn<D>`(CC 回调的形状,tool/context/message 三个位对本桥是不透明的)。
- *     壳侧 shim 用自己的 `PermissionDecision` 实例化泛型 ⇒ 壳侧调用点类型一字节不变。
- *     🔴 这是**类型面**的收窄,不是行为面:运行时只读 `.behavior` / `.message` / `.updatedInput`
- *        三个键(原文就只读这三个)。
- *  3. `backendDeny` 的返回形状(`decisionReason:{type:'asyncAgent',reason}`)是 CC 的
- *     `PermissionDenyDecision` 逐字形,本包按字面量声明(壳侧 shim 断言可赋值)。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * src/seam/adapter/upstream/hitlBridge.ts — the UPSTREAM control bridge (tasks.json T23; NEW file, no CC-logic edit).
- *
- * This is the human-in-the-loop (HITL) heart of the seam: the place where CC's synchronous `canUseTool`
- * callback (useCanUseTool.tsx:27 — the spine the contract must reproduce) meets the `@sema-ai/sdk`
- * suspended → decide → resume loop (contract/04 §2/§4/§6, contract/08 IH-4/IH-5/IH-10). CC's loop calls
- * `canUseTool(tool, input, …)` before any guarded tool runs and BLOCKS on the returned `PermissionDecision`;
- * the contract turns that blocking callback into a DURABLE pause (a `suspended` event carrying a
- * `CheckpointGate`) plus a `decide` verb. This module is the marshalling layer between the two worlds.
- *
- * What it does (the three contract laws this file pins):
- *
- *  1. **suspended ↔ canUseTool with the D-1 TOCTOU guard** (contract/04 §2.2, §D-1; 08 IH-4).
- *     When CC asks "may I run THIS tool?", the bridge finds the matching `PendingCheckpoint` the human SAW
- *     (joined by `toolCallId` → `boundCallId`), reads its `boundCallId` + `boundInputHash` two-tuple, and
- *     echoes them back into `approvals.decide(...)` VERBATIM. The hash is a server-minted opaque sha256 over
- *     the pending args at mint time — the bridge NEVER recomputes it (a false mismatch would fail-close a
- *     legitimate approval, approvals.ts:33). `updatedInput` (approve-with-edit, design/37 last-wins) is
- *     applied AFTER the binding check and does NOT change the binding — the hash still binds the ORIGINAL
- *     input the human reviewed. A 409 `approval_binding_mismatch` is a SAFETY signal: re-present to the
- *     human, NEVER auto-retry (contract/04 §9.1 fail-closed law).
- *
- *  2. **AskUserQuestion answer marshalling** (contract/04 §4.1; 08 CS-16/IH-4). The same suspended → decide
- *     loop, but the gate's `toolName` is `"AskUserQuestion"` and the answer rides `ApprovalDecision.answer`
- *     as the worker-validated wire shape `{ answers: [{ header, selected, note? }] }` — `header` MATCHES the
- *     question's header, `selected` is an ARRAY (multi-select → multiple entries), `note` is optional free
- *     text. The SDK types `answer` as `unknown`, so this is hand-marshalled (catalog mock-fill); the
- *     transport is sdk-covered. The D-1 binding still binds (AskUserQuestion is still a checkpoint).
- *
- *  3. **plan_review** (contract/04 §3; 08 CS-17/IH-6). CC's plan mode ends a planning turn with a markdown
- *     plan; the human approves/edits/rejects the PLAN itself (no bound tool action). This resolves on a
- *     DISTINCT wire — `assistant.planReview(taskId, { decision, editedPlan?, reason? })` — NOT `decide` and
- *     NOT `resume`. `editedPlan` is REQUIRED iff `decision === "edit"` and FORBIDDEN otherwise (→ 400). A
- *     non-`plan_review` gate routed here would 409 `gate_not_plan_review`; the bridge guards the gate kind
- *     before it calls.
- *
- * Provider- and presentation-agnostic (contract/04 laws 2-3; 08 invariants): every verb stays at
- * `ApprovalDecision` / `PlanReviewRequest` / `CheckpointGate` altitude. No Anthropic `effort`/`fast_mode`
- * vocabulary, no claude.ai permission-rule destinations, no widget/glyph/keybinding crosses this seam. The
- * backend supplies the SIGNAL; the shell owns the chrome.
- */
 import type { AgentEvent, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
-/** durable `/decide` 腿的既有缺省拒因(不带归因时逐字不变 —— 0.27.0 及之前的 wire 字节)。 */
 export declare const DEFAULT_DENY_REASON = "The user rejected this tool use";
-/**
- * 归因原文 → 可上 wire 的形。缺席/非串/纯空白 ⇒ `undefined`(调用方自定回落:deny 腿落
- * {@link DEFAULT_DENY_REASON},plan-review 腿键不落);超上限 ⇒ 截到上限并 debug 留痕。
- * 🔴 截断**边界安全**:切点落在代理对中间会产出孤高代理 —— server 长度检查放行,但 UTF-8
- * 落库/入签时末尾退化成 U+FFFD,两侧字节不一致还会毒化签名对账。末码元是高代理就再退一位。
- * 🔴 只做归因,不参与裁决:任何返回值都不改变这次决断本身。
- */
 export declare function denyReasonForWire(reason: string | undefined, tag: string): string | undefined;
-/** CC `PermissionDecision` 的结构切片 —— 本桥运行时真正读的三个键。 */
 export interface HitlPermissionDecisionLike {
     behavior: 'allow' | 'ask' | 'deny';
-    /** deny 臂的人话理由(CC `PermissionDenyDecision.message`),approve 臂缺席。 */
     message?: string;
-    /** approve-with-edit(design/37 last-wins);在**绑定校验之后**生效,绑定仍绑原始 input。 */
     updatedInput?: unknown;
 }
-/**
- * CC `CanUseToolFn` 的结构形(`useCanUseTool.tsx:28`)。tool / toolUseContext / assistantMessage
- * 三个位对本桥是**不透明**的(只读 `tool.name`),所以按最小形声明 —— 壳侧那个更窄的真类型
- * 可赋值到这里(函数参数双变),`makeHitlCanUseTool` 的返回值也就能直接当 `CanUseToolFn` 用。
- */
 export type HitlCanUseToolFn<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (tool: {
     name: string;
 }, input: Record<string, unknown>, toolUseContext: never, assistantMessage: never, toolUseID: string, forceDecision?: D) => Promise<D>;
 export interface ApprovalsResourceLike {
-    /** GET /v1/approvals — the rich decide-ready queue (approvals.ts:45). NEVER carries a capability token.
-     *  SDK ≥0.1.0([1908] 信封归一):wire 信封原样 `{ pending }`。
-     *  🔴 L-38(server 7.55.0):回体是 {@link ApprovalsListEnvelope} —— `pending` 之外还可能带
-     *  additive 的 `livePending` / `crashConverged`(按 deps 在场才发)。**放宽是 additive**:
-     *  老 mock 的 `{ pending }` 仍然可赋值,本文件与 `approvalsFeed.ts` 的 `.pending` 消费点
-     *  一个字节不动。`crashConverged` 的读法见 `hitl/crashConverged.ts` 的 `projectCrashConverged`
-     *  —— 🔴 它是**上一条命的残留**读面,与本桥这条 D-1 取件路**互不相干**,别在这里顺手消费它。 */
     list(opts?: {
         signal?: AbortSignal;
     }): Promise<ApprovalsListEnvelope>;
-    /** POST /v1/approvals/:sessionId/decide — resolve THAT checkpoint; the resumed run continues its stream
-     *  (approvals.ts:52). NOT a submit → no retry (a decide must never double-act). */
     decide(sessionId: string, decision: ApprovalDecision, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
 }
 export interface AssistantResourceLike {
-    /** POST /v1/assistant/tasks/:id/plan_review — the 3-state plan gate (assistant.ts:87). */
     planReview(taskId: string, req: PlanReviewRequest, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
-    /** POST /v1/assistant/tasks/:id/resume — continue a resource_limit slice, NO body (assistant.ts:75). */
     resume(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
@@ -125,339 +31,61 @@ export interface HitlClientLike {
     approvals: ApprovalsResourceLike;
     assistant: AssistantResourceLike;
 }
-/** The marshalled AskUserQuestion answer body — the worker-validated wire shape (contract/04 §4.1). */
 export interface AskAnswer {
-    /** MATCHES the question's `header`. */
     header: string;
-    /** ARRAY — multi-select yields multiple entries; single-select is a one-element array. */
     selected: string[];
-    /** Optional operator free-text note. */
     note?: string;
 }
-/** A plan-review outcome the shell collected (contract/04 §3.1). `editedPlan` REQUIRED iff decision==="edit". */
 export interface PlanReviewOutcome {
     decision: 'approve' | 'edit' | 'reject';
     editedPlan?: string;
     reason?: string;
-    /**
-     * 0.72.13 CC-46(engine ≥7.86.0;契约 §4c):批准之后这条任务继续用的 permission mode。**只配 `approve`**;
-     * 缺席 = 键不落(老壳姿势,引擎按 `default`)。🔴 适用面读不到 wire:只有**提交这条任务的那一方**知道它是不是
-     * `permissionMode:"plan"` 只读起步的 —— 不是只读起步的任务送这一位会吃 400 `request.field_conflict`,那次批准整个送不出去。
-     */
     permissionModeAfter?: PlanReviewModeAfter;
 }
-/** 契约 §4c `permissionModeAfter` 的闭集两词(`acceptEdits` = 工作目录内的写不再逐次征询;`default` = 每次写照常征询)。 */
 export declare const PLAN_REVIEW_MODE_AFTER_WORDS: readonly ["default", "acceptEdits"];
 export type PlanReviewModeAfter = (typeof PLAN_REVIEW_MODE_AFTER_WORDS)[number];
-/** 这个值是不是闭集里的词(词表外 —— 含 `plan` / `bypassPermissions` / `auto` —— 引擎 400:一次批准不许顺带关掉征询面)。 */
 export declare function isPlanReviewModeAfter(v: string | undefined): v is PlanReviewModeAfter;
-/**
- * {@link HitlSafetyError.code} 的闭集(0.60.0 抽名,**成员一个没动**)。
- *
- * 🔴 抽名的理由是**消费面**:决断腿的失败结局要把「本地安全停」与「引擎的 wire 拒绝」结构分开
- * (`FsApprovalOutcome.safetyCode` / `GateOutcome.code`),而那两处此前只能各自把这五个词再抄一遍
- * ——抄一份就是给自己立第二个判官(B-025 的病形)。加员仍必须**同批**改齐
- * `parkResolver.GATE_FAILURE_CODES` 白名单(见下方原注)。
- */
 export type HitlSafetyCode = 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'bad_plan_mode' | 'empty_answer';
-/**
- * 一次决断链失败**停在哪一段**(0.60.0;异源对抗复审 [medium] 采纳,B-037 候包件 ② 的完整兑现)。
- *
- * ── 病 ──────────────────────────────────────────────────────────────────────────────────────
- * 两条决断腿(fs / ask)的 `failed` 结局把 typed 错**拍平成一个 `reason` 串**,于是四类完全不同的
- * 失败在消费点**同形**:「取件那一拍没有可决行」「卡口没装」「引擎语义拒绝」「出站瞬断耗尽」——
- * 分流只能去正则匹配那句拍平文案(里面嵌的是 `String(e)`,上游改一个词就静默空转)。而这四类的
- * 出路完全不同:重探 / 装口 / 重呈或换参数 / 重呈不判死。
- *
- * ── 词与判据 ────────────────────────────────────────────────────────────────────────────────
- *  · `fetch`         —— 取件腿没给出可决行,或读面自己炸了(**一个字节都没送出去**);
- *  · `input`         —— 行上没有可呈现的载荷(工具入参 / 问句),卡渲不出来(同样没送出去);
- *  · `card`          —— 卡口那一段失败(没装卡口 / 卡口自己报失败 / 没有问答 overlay);
- *  · `decide`        —— 决断**已经发出去了**(引擎语义拒绝,或出站瞬断耗尽);
- *  · `orchestration` —— 上面四段都不是:编排层在若干轮重挂之后收口(轮数/park 数硬上限、连续零进展)。
- * 🔴 **只有 `decide` 代表「引擎那一头知道这次决断」** —— 安全停的第一问就是它,前三段一个字节都没送出。
- * 🔴 **必填**:一个可选的阶段位等于又留了一格「读不出就猜」,而这一位存在的全部理由就是消灭那一格。
- */
 export type HitlFailureStage = 'fetch' | 'input' | 'card' | 'decide' | 'orchestration';
-/** A safety stop: a contract law was about to be violated (e.g. a binding mismatch, a wrong-gate route).
- *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
- *  (contract/04 §9.1 fail-closed law). */
 export declare class HitlSafetyError extends Error {
-    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
-     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
-    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
-     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
-     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
     readonly code: HitlSafetyCode;
-    constructor(message: string, 
-    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
-     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
-    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
-     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
-     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
-    code: HitlSafetyCode);
+    constructor(message: string, code: HitlSafetyCode);
 }
-/**
- * decide 409 `approval_stale` 拒体上的 **additive 指路键** `currentPending` —— 本会话**当前**那条
- * pending 的三件 D-1 坐标(#363,0.47.0;server S-02 ≥7.52)。
- *
- * ── 它是什么、不是什么 ────────────────────────────────────────────────────────────────────
- * 是:「你手上那条已经不是当前的了,**当前**这条长这样」——壳拿它**一跳重定位**再 decide,
- *     免去整队重拉(`GET /v1/approvals`)。
- * 不是:放行凭据 / CAS 输入 / resume 凭证。server 自己的 fail-open 登记原话逐字:
- *     「纯指路/便利面,**不参与任何门/CAS/resume 判定**」。⇒ 缺席的代价 = 退回它到货前的行为
- *     (重拉列表自行重定位),所以本包对它一律**宽读、诚实缺席**,绝不 fail-closed。
- * 🔴 **恒不含 `checkpointToken`**(server 侧 resume 凭证不外发纪律)——本形也刻意没有那一位:
- *     多一个位就是给一个「凭证能过境」的错觉。
- *
- * ── 自铸形已退役,本名现在是上游形的**别名**(0.48.0)──────────────────────────────────
- * 0.47.0 这里是一个**自铸 interface** + 一段记账:`@sema-agent/sdk` 7.3.0 起已有逐字同形的
- * `ApprovalStaleCurrentPending`,但当时本包 peer 地板是 `>=7.2.0`,那一版上这个名字不存在 ⇒
- * `import type` 会让装 7.2.0 的端当场编不过。记账段同批写死了退役条件:「peer 地板抬到 `>=7.3.0`
- * 的那一批,把本形改成 `import type` 的别名并删掉这段记账」。
- * 本批(0.48.0)peer 地板抬到 **`>=7.4.0`**(四件新投影都吃 7.4.0 的类型面)⇒ 条件满足,兑现。
- * 🔴 **别名而不是删名**:`GateCurrentPending` 是 `FsApprovalOutcome` / `GateOutcome` 两条腿的**已发布
- *    导出名**,删它是 BREAKING。别名让上游形成为**唯一真源**(上游改一个位,本包的两条腿当天跟着
- *    动,不再有第二份可能漂的声明),而本名继续对已接入的端有效。
- * 🔴 **同名不同源的风险随之消失**:0.47.0 刻意取了个**不同名**(免得地板线下出现一个与上游同名却
- *    不同源的形,[same-name-different-meaning-crosses-layers]);现在两者是同一个形,那条顾虑不再
- *    适用 —— 但名字**不回改**成上游名,理由见上一条(已发布导出名)。
- *
- * 🔴 **为什么绕道 `ApprovalStaleError['currentPending']` 而不是直接 `import type
- *    { ApprovalStaleCurrentPending }`(上游缺口,本批亲验实证)**:那个名字在 sdk 7.4.0 里**声明了
- *    但没有从包入口导出** —— `dist/types.d.ts:2359` 有 `export interface ApprovalStaleCurrentPending`,
- *    而 `dist/index.d.ts` 的 re-export 名单里**没有它**(同文件只导出了 `ApprovalStaleError`),
- *    且包 `exports` 映射只开 `.` / `./registry` 两个子路径,深引 `@sema-agent/sdk/dist/types.js`
- *    这条路根本不通。⇒ 按名 import 是**编译错**,不是风格选择。
- *    绕道取的是**同一个声明**(`currentPending?: ApprovalStaleCurrentPending | undefined`,
- *    `NonNullable` 剥掉可选位),所以单源化的目的一字不打折:上游改那个形,本包当天跟着动。
- *    📋 **上游候件(已登记,不在本批修)**:请 sdk 把 `ApprovalStaleCurrentPending` 加进 `index.d.ts`
- *    的 `export type {…}` 名单(纯 additive,零行为)。到货后本别名可改回按名 import,
- *    **但那是等价重构、不是修复** —— 今天这条路已经拿到上游形本身,不存在第二份可能漂的声明。
- */
 export type GateCurrentPending = Readonly<NonNullable<ApprovalStaleError['currentPending']>>;
-/**
- * 从一次 decide 失败(任意抛出物)里读出 {@link GateCurrentPending} —— 读不出即 `undefined`。
- *
- * 🔴 **结构视图读,不 `instanceof`**(两条理由,都是承重的):
- *   ① **供给面**:本包的 decide 出站走的是宿主注入的 `HitlClientLike`(见该型)。抛出来的到底是不是
- *      SDK 的 `ApprovalStaleError` 由**宿主**决定 —— web/desktop 完全可以注入自己的传输层。拿
- *      `instanceof` 当闸,等于让「宿主用的是哪一份 SDK 实例」决定一个纯读值的位在不在
- *      (跨 realm / 双实例 = `HitlSafetyError` 判型契约踩过的同一个坑,见 §4e)。
- *   ② **类型面**(0.48.0 就地订正):0.47.0 这条写的是「`ApprovalStaleError.currentPending` 只在
- *      sdk ≥7.3.0 上声明,而本包地板是 7.2.0」——**地板已抬到 `>=7.4.0`,那半条不再成立**。
- *      但本条的**结论不变**,因为承重的从来是 ① 那半:即使类型面现在够得着,抛出来的对象仍由宿主
- *      的传输层决定,`instanceof` 依旧是错的判据。⇒ 保留宽读,只订正理由。
- * 🔴 **判据锚在「值本身合不合形」,不锚它骑在哪个类/哪个 errorCode 上**
- *    ([anchor-on-the-deciding-quantity]):真正决定「壳能不能一跳重定位」的量,是**这个三元组的
- *    两件必填位在不在且是非空串** —— 而不是错误的类名。宽读在这里是**方向安全**的:本位不参与
- *    任何裁决(见 {@link GateCurrentPending} 顶注),多读到一次的代价 = 多一条指路;漏读的代价 =
- *    退回整队重拉。
- * 🔴 **两件必填位缺一即整只不铸**:半个三元组重定位不了(`decide` 要的是 boundCallId 本体),
- *    铸一个残形只会让消费点以为「有指路」。`boundInputHash` 是**行上有才带**的可选位,缺席照铸。
- */
 export declare function readDecideCurrentPending(e: unknown): GateCurrentPending | undefined;
-/**
- * 从一次 decide / 取件失败(任意抛出物)里读出**引擎的机器码** —— 读不出即 `undefined`。
- *
- * 🔴 **为什么这一位非透出不可**(0.60.0;上游候包件 ②,与 0.47.0 补 `currentPending` **同形**):
- *    本包把 typed 错**拍平成 `reason` 串**交给消费点(`FsApprovalOutcome.failed.reason`),于是
- *    「只读 outcome 形」的消费者(壳的重开链、迟到决断代理)对机读码**全盲** —— 要分辨
- *    `resume.preflight_rejected` / `approval_stale` / 传输类失败,只能去正则匹配那句拍平文案,
- *    而那句文案里嵌的是 `String(e)`(上游一改措辞就静默空转)。上游为此在壳里绕了一整圈
- *    (把 client 套进代理、站在拍平**之前**读)——那圈本该由这一位省掉。
- * 🔴 **结构视图读,不 `instanceof`**:理由与 {@link readDecideCurrentPending} 逐字同一条 ——
- *    抛出来的是不是 SDK 的错误类由**宿主注入的传输层**决定(跨 realm / 双实例)。
- * 🔴 **键位只认 `errorCode`**([2055] 死键纪律,退役的 `code` 槽不做兼容);非空串才算数,
- *    其余一律诚实缺席。
- * 🔴 **只搬运不解释**:本读口不判任何码属于哪一族(词表属主在 server/core,开集)——消费点分支
- *    已知码、永远带 `default`。
- * 🔴 **绝不把它当凭证面**:`errorCode` 是机器码,不是错误正文;错误正文(可能含凭据/内部路径)
- *    照旧**不**经本位外流。
- */
 export declare function readWireErrorCode(e: unknown): string | undefined;
-/** 测试钩:把超时类重试总窗调小(传 undefined 还原缺省)。 */
 export declare function __setDecideTimeoutRetryBudgetForTests(ms?: number): void;
-/**
- * decide 出站在瞬断类失败上重试一次**仍未送达**(两发都没拿到引擎的语义答复)。
- *
- * 🔴 判别位契约:消费方(`toolApprovalWire` 的 catch 臂 / `parkResolver.surfaceGateAndDecide`)
- * 据 `instanceof` 在 outcome 上 stamp `retryExhausted: true`,parkResolver 对该位走**重呈臂**
- * (re-attach ⇒ durable 流重放 park ⇒ 同一张卡重新交给用户),不再合成 `hitl_unanswered` 把 turn
- * 判死 —— run 仍 parked、pending 行仍可决,判死是三条出路里唯一不可逆的那条。
- * 🔴 message 刻意避开 `isAlreadyResolvedGateReason` 的词表(no pending checkpoint / resolved /
- * already / not found):被那把兜底尺误判成「已解决」会走成静默 reattach,判别位就白铸了 ——
- * pure 门(hitl-gate-honesty F6-d)有常驻负控钉着这一条。
- */
 export declare class DecideTransportRetryExhaustedError extends Error {
-    /** 实际发出的次数(网络断类 = 2:首发 + 单次重试;超时类 = 总窗内发出的全部)。 */
     readonly attempts: number;
-    constructor(
-    /** 实际发出的次数(网络断类 = 2:首发 + 单次重试;超时类 = 总窗内发出的全部)。 */
-    attempts: number, lastFailureText: string);
+    constructor(attempts: number, lastFailureText: string);
 }
-/** The active gate the downstream stream most recently suspended on (null when running). */
 export interface ActiveGate {
     gate: CheckpointGate;
-    /** The durable seq of the `suspended` event, for rewind/dedup correlation (types.ts:48 eventSeq). */
     seq?: string | undefined;
-    /** 0.74.3 CC-73:这条挂起是不是一次 reopen(`suspended.reopened` 三态,见 {@link suspendedReopenOf});每条 suspended 重读,不粘上一条。 */
     reopened: SuspendedReopenReading;
 }
-/** Outcome of {@link findPendingForTask}. */
 export type FindPendingOutcome = {
     ok: true;
     pending: PendingCheckpoint;
     gatedCallId: string | undefined;
-}
-/** `code`:结构化判别位(REF-CC-033)。'no_pending'=良性缺席(park 重放常见);缺席=真失败(list 抛)。 */
- | {
+} | {
     ok: false;
     reason: string;
     code?: 'no_pending';
 };
-/**
- * The single source for "which `PendingCheckpoint` row is the human about to decide on", used by the two
- * decision wires (`toolApprovalWire.surfaceFsApprovalAndDecide` / `askGateWire.surfaceGateAndDecide`)
- * BEFORE they know which specific call/question they're presenting — that is the FIRST fetch, the one
- * that decides what gets rendered on the card/overlay.
- *
- * REF-CC-029(2026-08-02,消 hitl2-08/hitl2-01 双病根):this used to be three near-identical copies
- * (this file's own `HitlBridge.findPending` plus one each in `toolApprovalWire.ts` / `askGateWire.ts`),
- * and only `HitlBridge.findPending`'s copy had a `?? pending[0]` last-resort fallback (REF-CC-022) that
- * could resolve a DIFFERENT session's or a background subagent lane's pending row once this taskId's own
- * rows were gone — they all share the same `/v1/approvals` queue. Single-sourcing this lookup here means
- * that divergence can't recur, and passing the resolved row straight into `decideTool`/`answerQuestion`'s
- * `preResolvedPending` param closes the TOCTOU window between "the row the human saw" (this fetch) and
- * "the row decide resolves" (previously a SECOND independent fetch inside the bridge).
- *
- * Match by `taskId` + a caller-supplied predicate over the row's `toolName` (the tool family this wire
- * cares about, e.g. fs-write vs AskUserQuestion) first; fall back to ANY row for this `taskId` (a gate
- * whose toolName the predicate doesn't recognize, but which still belongs to this run). Never `pending[0]`
- * — a typed failure when nothing for this taskId is queued.
- *
- * F4947-1(2026-08-22,0.41.0):`callId` 是**更强的身份腿**,在场时先于上面两条跑。它来自
- * `HitlBridge.decideTool`/`answerQuestion` 的 `toolUseID`(CC 的 tool_use id)—— 那两处此前走的是
- * 本类里一个**同名私有** `findPending`,REF-CC-029 的收编没覆盖到它、P-30 的门种闸也没加到它,
- * 于是真实生产入口(`makeHitlCanUseTool` → `decideTool`,从不传 `preResolvedPending`)一直在一条
- * **没有闸**的复刻上跑(test 线 P0-KPI 复现)。收口方式是把私有件删掉改调本函数,而不是给它补第二
- * 份过滤 —— 复刻正是这条缺陷的成因。身份腿同样只在**过完门种闸的行**里找:一个 `plan_review` 行
- * 哪怕 callId 逐字命中也不该被工具审批 decide 掉(server 那边照样 409 `gate_not_tool_approval`)。
- *
- * P-30(2026-08-14):both legs only consider rows whose `gateKind` belongs to the ask/approval family
- * ({@link askParkForeignGateKind} — the same single-source guard `classifyAskParkRows` uses). Without it
- * the ANY-row fallback would hand a `plan_review`/`resource_limit` row to the tool-approval wire — an
- * empty-toolName card whose decide then 409s (`gate_not_tool_approval`). A foreign-kind row is filtered
- * out, not a rejection of the whole queue: a genuine approval row for the same task still resolves.
- * Rows with no `gateKind` (pre-`gate_kind` history) keep the old behaviour — no stronger signal exists.
- */
 export declare function findPendingForTask(client: HitlClientLike, taskId: string, matches: (toolName: string | undefined) => boolean, opts?: {
     signal?: AbortSignal;
-}, 
-/**
- * F4947-1:调用方手上的**更强身份** —— CC 的 `toolUseID`(`HitlBridge`),或这张 park 的
- * wire 身份(server ≥7.41.0,两条决断腿)。在场 ⇒ 先在**本 taskId** 的行里按
- * `boundCallId`/`toolCallId` 逐字命中(仍在门种闸之内);不命中再走下面两条 taskId 腿。
- *
- * 🔴 **刻意不 fail-closed**(异源复审二审 finding① 的部分驳回,理由成文):身份在场而队列里
- * 没有那一行时**照旧回落**,不铸「身份不匹配」的硬拒。两条理由:
- *   · 回落的失效面 = 与本参数出现之前**逐字节相同**(那时压根没有身份腿);fail-closed 的失效面
- *     = **每一次审批都决断不了**(用户点了 Yes 也过不去)。代价严重不对称;
- *   · 这个 join(checkpoint 的 `pendingAction.toolCallId` ↔ `/v1/approvals` 富行的
- *     `toolCallId`/`boundCallId`)本仓**没有对真 server 的实证**,只有上游帖面的口径。拿一个
- *     没实证的键去关整条 HITL 的门,是把「可能对不上」赌成「一定对得上」。
- * 跨 run 那一半的风险由上面的 taskId 约束关掉;「决断落在同 task 的另一行」这一格与本参数出现
- * 之前同形,且下游 `dropHeldForDecidedPark` 对这一格自带保守判(身份对不上 ⇒ 一帧都不摘)。
- */
-callId?: string, 
-/**
- * 身份腿的**族闸**(整行可读)。缺省 = 退回 `matches(toolName)`。
- *
- * 🔴 为什么必须能读**整行**而不是只读 toolName(五审 finding①):工具审批族有**两条腿** ——
- * 一等 `kind === 'tool_approval'`(放行**任意** toolName)与 fs 写 / shell 名字腿。而 wire 模块
- * 传下来的 `matches` 只有名字腿那半(它服务的是「同族第一行」那条 leg 2)。拿它当身份闸,一个
- * **合法的 kind-only 行**即使 taskId+callId 逐字命中也会被判出局 ⇒ 回落挑了同 task 的另一行,
- * 卡面与决断全落在别的审批上、真 gate 继续 suspended。⇒ 调用方按自己那条腿的**完整**族判据
- * 供给本闸(fs 腿 = `isToolApprovalGate({kind: row.gateKind, toolName})`,ask 腿 = `isAskTool`)。
- */
-identityAccepts?: (row: PendingCheckpoint) => boolean): Promise<FindPendingOutcome>;
-/**
- * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
- * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
- */
+}, callId?: string, identityAccepts?: (row: PendingCheckpoint) => boolean): Promise<FindPendingOutcome>;
 export declare class HitlBridge {
     private readonly client;
-    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
     private readonly taskId;
     private active;
-    constructor(client: HitlClientLike, 
-    /** The suspended run's taskId — the handle plan_review/resume address (RunReceipt.taskId). */
-    taskId: string);
-    /** Observe a downstream event; latch the gate on `suspended`, clear it on a resuming/terminal arm. */
+    constructor(client: HitlClientLike, taskId: string);
     observe(ev: AgentEvent): void;
-    /** The gate currently awaiting a human, if any. The shell branches on `gate.kind` to pick the chrome. */
     currentGate(): CheckpointGate | null;
-    /**
-     * 0.74.3 CC-73:当前挂起是不是一次 reopen(`suspended.reopened` 三态);没挂起 ⇒ `null`。
-     * 消费方据此把「真 reopen 成功、重试会重放」那半句说出来:`reopened` 在场码 ⇒ 卡仍 pending、决定没被消费、可再决;
-     * `not_reopened` / `unstated` ⇒ 普通挂起,一个字都不多说。
-     */
     currentGateReopen(): SuspendedReopenReading | null;
-    /**
-     * Fetch the `PendingCheckpoint` this decide/answer is about to resolve, for the callers that do NOT
-     * already have one in hand (see `decideTool`/`answerQuestion`'s `preResolvedPending` param — the wire
-     * modules that surface a card/overlay BEFORE deciding fetch the row themselves and pass it straight
-     * through, closing the TOCTOU window between "the row the human saw" and "the row decide resolves",
-     * REF-CC-029/hitl2-08).
-     *
-     * 🔴 F4947-1(2026-08-22,0.41.0):本方法**没有自己的查找逻辑** —— 它是 {@link findPendingForTask}
-     * 的一层出参映射,一个字节的行过滤都不在这里。上一版是一个与那个单源导出**撞名**的私有复刻
-     * (`findPending`),REF-CC-029 的三合一没覆盖到它、P-30 的门种闸也只加在导出那一份上,于是
-     * `makeHitlCanUseTool` → `decideTool`(真实用户点 Yes/No 那条路,从不传 `preResolvedPending`)
-     * 一直在没有闸的老复刻上跑:同 task 停着 `plan_review` 行时,它被当成「这个 run 的 pending」
-     * 交给工具审批 decide(空 toolName 卡 / 409 `gate_not_tool_approval`)。
-     * 名字也一并换掉:撞名正是「看起来只有一份实现」的成因。
-     *
-     * 谓词传 {@link ANY_TOOL_FAMILY}:桥这一层对工具族**没有意见**(人刚刚决断的是哪张门就是哪张),
-     * 与旧私有件的 taskId 兜底逐字同语义;身份腿(`toolUseID`)由单源函数的 `callId` 参数承接。
-     */
     private pendingForDecide;
-    /**
-     * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
-     * (contract/04 §2.2). `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
-     * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
-     *
-     * pre-D-1 的 `{}` 回落臂已删(2026-08-03,#117 提货 / [2356]#2):server 5.x 的 decide 三键必填、
-     * 缺键 400,「发一个注定 400 的请求」不如在本地响亮失败——pending 行缺绑定键只可能来自
-     * 不再支持的旧 worker 或坏数据,fail-loud 带坐标好过静默烧一轮 HTTP。
-     */
     private bindingOf;
-    /**
-     * Resolve a `human` / `irreversible_ask` permission gate (contract/04 §2, §6.2; 08 IH-4/IH-10).
-     *
-     *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
-     *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
-     *  - `deny`    → `{decision:"deny", reason}`.
-     *
-     * 🔴 **§2.4「DENY-abort」撤稿(0.42.0;server [4833] 明请,契约成文 `4631a0f` 随 7.39 出)**。
-     *    本段原文写的是:「CANCEL a suspended run by DENYING, never by `runs.cancel` (**which 409s on a
-     *    suspended run** — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is *the run ends
-     *    after the deny*」。**三句话里有两句已被上游证伪,逐条**:
-     *      · **「deny 用来 cancel 一条 run」** —— `ASSISTANT-WIRE-CONTRACT.md` §4a 逐字反过来说:
-     *        **DENY is a TOOL-level answer, NEVER a run kill**;客户端不得把用户的拒绝译成 cancel。
-     *        两个动词的 wire 判别式是 `cancelled`(真取消)vs `gate.batch_halted`(裸拒的兄弟结算)。
-     *      · **「`runs.cancel` 对 suspended run 回 409」** —— 自 server [868] 起**就地取消**:
-     *        `runs.js` 的 cancel 腿对 SUSPENDED/needs_review 先结算 pending checkpoint(CAS expire)再
-     *        终态化,`cancelSuspended` 有实体,409 只剩 `conflict.approval_settled` 一条
-     *        (本仓 `docs/fresh-scan-client-core-2026-08-08.md` B型-5 已按真字节证伪,当时未跟修注释)。
-     *      · **仍然成立的那一句**:deny 之后 run 是否结束由**后端编排**决定,不是 wire 上的旗标
-     *        (裸拒 ⇒ `gate.batch_halted` + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
-     *    ⇒ 本方法的**行为一字未改**(它本来走的就是 §4a 说的那条 TOOL 级 decide 通路);改的是这段
-     *      引用错权威、并把一条早已失效的 409 断言当理由的散文。
-     *
-     * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
-     * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
-     */
     decideTool(outcome: {
         decision: 'approve';
         updatedInput?: unknown;
@@ -467,75 +95,25 @@ export declare class HitlBridge {
         reason?: string | undefined;
     }, toolUseID?: string, opts?: {
         signal?: AbortSignal;
-    }, 
-    /** REF-CC-029(2026-08-02):the pending row the caller ALREADY fetched (via `findPendingForTask`,
-     *  below) to render the card/overlay the human just decided on. When supplied, this method skips
-     *  its own `approvals.list()` — closing the TOCTOU window between "the row the human saw" and "the
-     *  row decide resolves" (two independent fetches could otherwise land on different rows if the
-     *  first one got resolved/expired in between, hitl2-01/hitl2-08). Omit only when the caller has no
-     *  such row in hand(缺省回落 `pendingForDecide` — 见其头注,那是单源 `findPendingForTask` 的一层出参映射). */
-    preResolvedPending?: PendingCheckpoint): Promise<unknown>;
-    /**
-     * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a
-     * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
-     * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
-     * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
-     *
-     * 🔴 FIX②(2026-08-07)—— **本地 fail-loud**:此前本方法对 `answers: []` 与「某条 `selected: []`」
-     * 零校验,一条注定 400 的请求照样出门。这不是「多一次往返」而已 ——
-     *   · 用户面只看到「作答失败」,而失败的原因(空作答)在壳侧一个字都没说;
-     *   · `ToolPermissionDecision.answer` 的头注自己写着「a silently emptied answer is the user's
-     *     choice being thrown away without anyone noticing」—— 那条纪律此前只写在类型注释里,
-     *     没有任何一层真的执行它;
-     *   · `{answers:[]}` 在 wire 上另有确切含义(question 域 **deny** 的 NO_HUMAN 形),把它当成一次
-     *     approve 发出去 = 拿 deny 的载荷冒充 approve。
-     * 三形一律抛 `HitlSafetyError('empty_answer')`,一次 decide 都不发:空 `answers[]` /
-     * 任一条 `selected[]` 为空 / 任一条 `header` 为空串。
-     */
+    }, preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     answerQuestion(answers: AskAnswer[], toolUseID?: string, opts?: {
         signal?: AbortSignal;
-    }, 
-    /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
-     *  fetched via `findPendingForTask`. */
-    preResolvedPending?: PendingCheckpoint): Promise<unknown>;
-    /**
-     * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
-     * `resume`. Also guards the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
-     * otherwise → 400) so the bad call never leaves the shell — that check is unconditional (no
-     * `observe()` dependency). The gate-kind guard below is host-optional (see its own comment); the
-     * server's 409 `gate_not_plan_review` is the real backstop either way.
-     */
+    }, preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     reviewPlan(outcome: PlanReviewOutcome, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
-    /**
-     * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
-     * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
-     * must NEVER bypass a human approval). REF-CC-028(2026-08-02,评注现势):the local guard below is
-     * host-optional — it only fires when the host drives `observe(ev)` (neither production call site does
-     * today, see `reviewPlan`'s comment); the server's 409 is the fail-closed backstop that actually holds
-     * this invariant.
-     */
     resumeResourceLimit(opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
     private decideRaw;
 }
-/** The shell's presentation hook: surface a gate, resolve to a CC `PermissionDecision`. */
 export type GatePrompt<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike> = (ctx: {
     toolName: string;
     input: Record<string, unknown>;
     toolUseID: string;
     gate: CheckpointGate | null;
 }) => Promise<D>;
-/**
- * Build a `CanUseToolFn` backed by the bridge. CC's loop calls it before any guarded tool; it surfaces the
- * gate via `prompt`, routes the human's decision to `approvals.decide` (binding echoed verbatim), and
- * returns the same `PermissionDecision` to unblock the loop. A `forceDecision` (CC's pre-resolved path)
- * short-circuits the prompt but STILL drives the decide verb so the backend resolves the checkpoint.
- */
 export declare function makeHitlCanUseTool<D extends HitlPermissionDecisionLike = HitlPermissionDecisionLike>(bridge: HitlBridge, prompt: GatePrompt<D>): HitlCanUseToolFn<D>;
-/** CC `PermissionDenyDecision` 的逐字形(`decisionReason` 的 `asyncAgent` 臂)。 */
 export interface HitlBackendDenyDecision {
     behavior: 'deny';
     message: string;
@@ -544,6 +122,4 @@ export interface HitlBackendDenyDecision {
         reason: string;
     };
 }
-/** Build a CC deny `PermissionDecision` from a backend-driven denial (e.g. an SLA / policy auto-deny).
- *  The decisionReason is `asyncAgent` — the denial originated upstream, not from a local rule/mode. */
 export declare function backendDeny(reason: string): HitlBackendDenyDecision;