@sema-agent/client-core 0.8.0 → 0.9.0

package/dist/hitl/askGateWire.d.ts

@@ -0,0 +1,155 @@
+/**
+ * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/sema/liveHitlAskWire.ts`(658 行)**整条进包**
+ *    (设计稿表 §2.5:`S/liveHitlAskWire.ts | 659 | utils/debug · utils/messages(dyn) | B7`)。
+ *
+ * 🔴 搬迁差分(逐条,零行为变化;每条都在 pure 门 B7 段有断言):
+ *   1. `logForDebugging(x)` / `logForDebugging(x,{level:'error'})` → `hostLog('debug'|'error', x)`
+ *      —— 本包零 `utils/debug`(portability 门盯着)。
+ *   2. `require('../utils/messages.js').REJECT_MESSAGE` 的 lazy require + 内联字面量兜底
+ *      → 直接用常量 `HITL_REJECT_MESSAGE`(**逐字**同一串)。lazy require 存在的理由是「wire 模块
+ *      别拉 React/ink 图」,在包里没有那张图 ⇒ 理由消失,只留常量。
+ *      🔴 常量漂移锁:pure 门 B7 段拿壳树 `src/utils/messages.ts` 的 `REJECT_MESSAGE` 做
+ *      byte-identity 对拍(壳树缺席 ⇒ DEGRADED 打印,不假绿)。
+ *   3. `getAppStateStoreRef()` 直写 `AppState.notifications` → `HitlHostSurface` 口
+ *      (`showNotice` / `clearNoticeIfCurrent`)—— `AppState` 是**端的状态形状**。
+ *      同理 `surfaceClassifierDeny`(footer 通知 + /permissions Recent Denials 记账,两者都是壳资产)
+ *      也走这个口。判定半场(`classifierDenyFromToolEnd`)B2 就已在包内。
+ *   4. `liveToolApprovalWire` 的引用 → 包内 `./toolApprovalWire.js`(同批拆搬)。
+ *   5. `liveQuestionStore` → 包内同名模块(B1 已搬,**同一个 module 台账**)。
+ *
+ * 🔴 单实例纪律:本文件自身无 module 级台账,但它**读**两个包内台账
+ *   (`liveQuestionStore` 的 responder 表 / `toolApprovalWire` 的卡口)。壳侧本地副本与 npm 包
+ *   同时进 bundle ⇒ overlay responder 注册在一份、`publishQuestionFrame` 发到另一份 = 对话框
+ *   弹出来但没人收答(静默挂死)。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * liveHitlAskWire — §4④ AskUserQuestion 的 suspended↔overlay 桥(engine 1.163 HITL 语义,2026-07-12)。
+ *
+ * WIRE 全链(engine 1.163.0 × SDK 0.0.44,askq-wire-probe 逐字实证 2026-07-12):
+ *   1. 模型调 AskUserQuestion → 引擎 DURABLE_APPROVAL park:sync leg(POST /v1/tasks/stream)上先发
+ *      `tool_start`(args 带完整 questions payload)、再发被 park 毒化的 `tool_end isError:true
+ *      output:"Operation aborted"`(同 turn 其它并发工具也一并 abort,模型 resume 后自己重发),
+ *      终帧 `done` `status:"suspended"` + `checkpointGate:{kind:"human",toolName:"AskUserQuestion"}`,流结束。
+ *      🔴 1.61 时代的 `event: question` 帧已蒸发(SDK 0.0.44 连 questions 资源都没了)——
+ *      demuxQuestionFrames→overlay 旧链收不到任何东西,turn 尾裸渲 `⎿ Error: Operation aborted`。
+ *   2. 本模块(liveClient 流管道内层)拦下这个 park:HOLD 毒化 tool_end(不渲)、吞 suspended done、
+ *      从 `GET /v1/approvals` 拿 pending 行(input=questions + boundCallId/boundInputHash 绑定)、
+ *      合成 QuestionFrame 借既有 AskUserQuestion overlay(planReviewWire 同款 local-responder 姿势,
+ *      CC 原生对话框,零新 UI)、等用户作答。
+ *   3. 决断走 T23 HitlBridge(答案 ride `ApprovalDecision.answer`,D-1 绑定 verbatim 回显;拒答=
+ *      cancel-by-deny,contract/04 §2.4)。decide 是 SYNC 驱动的:引擎跑到下一个 park 或终态才返
+ *      (实测 4-5s+),返回体 `{status}` 即下一状态。
+ *   4. 续流:attach `GET /v1/runs/:taskId/events`(durable leg;实证 durable log 从 park 点才开始,
+ *      无挂起前重放)。重放的 tool_start/tool_end 按 toolCallId 去重;被 gate 的 call 在重放里带来
+ *      `tool_end isError:false` = 卡片正常收口(HOLD 的毒化帧被丢弃)。模型再次提问时 durable 流发
+ *      `suspended` arm(带 gate)后流结束 → 同一循环再走一遍,`lastEventId` 续传防重放。
+ *
+ * 🔴 fail-soft 铁律:桥内任何一步失败(overlay 未挂载/print 模式、pending 蒸发、decide 409/404、
+ *   turn 中断)都回退到「flush HOLD 的毒化帧 + 原样吐 suspended 终帧」= 今天的诚实红,绝不更糟。
+ * 🔴 路由面([816] 壳侧承诺① 放宽,2026-07-14):AskUserQuestion gate 走问答 overlay(原路);
+ *   fs 写权限 gate(Write/Edit/NotebookEdit,或一等 kind==='tool_approval')走 liveToolApprovalWire
+ *   的 CC 三选卡(vendored PermissionRequest);其余 human/irreversible gate 保持现状透传。
+ * 🔴 UNTRUSTED:questions 为模型作文(service 已 redact),只渲染绝不回喂;答案由 core 围栏
+ *   (`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;
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
+export declare function hitlHostSurfaceMisses(): number;
+/** 测试钩:卸口 + 清计数。 */
+export declare function _resetHitlHostSurfaceForTest(): void;
+/**
+ * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(搬迁差分 2)。deny 后重放 tool_end 的
+ * render 面 stamp 用 —— vendored `renderToolUseRejectedMessage` 渲 `User rejected <op> to <path>`。
+ * 🔴 与壳树那份的 byte-identity 由 pure 门 B7 段锁住(壳树缺席 ⇒ DEGRADED,不假绿)。
+ */
+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;
+}
+/** 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;
+/**
+ * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。
+ * 其它事件原样透传;非 AskUserQuestion 的 gate 保持现状。fail-soft:任何桥内失败回退为
+ * 「flush 毒化 tool_end + 原样终帧」(= 修复前行为)。
+ *
+ * @param source 上游 AgentEvent 流(tasks.stream 或 runs.events,已过 demuxQuestionFrames)。
+ * @param opts.taskId runs.events 消费时已知的 run handle(sync leg 从 suspended done 捕获)。
+ */
+export declare function bridgeAskUserQuestionGates(source: AsyncGenerator<AgentEvent>, deps: AskGateWireDeps, opts?: {
+    signal?: AbortSignal;
+    taskId?: string;
+}): AsyncGenerator<AgentEvent>;