@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/hitl/frameRouter.d.ts

@@ -1,127 +1,33 @@
-/**
- * frameRouter — HITL gate 桥**内环**的帧路由(REF-CC-032 / SPLIT-12 第二刀,2026-08-02)。
- *
- * 一帧进、一个 `FrameAction` 出:路由本身不 yield、不读流、不决断,只把「这一帧该怎么处置」表达成
- * 数据。驱动(`askGateWire.bridgeAskUserQuestionGates`)照 action 吐帧 / 结束 / park,外环决断在
- * `parkResolver.ts`。这样内外环对台账的写全部经 `GateLedger` 的动词,不再各自直写同一批容器。
- *
- * 🔴 本文件同时是两把刀的**共享词汇层**:`AskGateWireDeps` / `isAskTool` / 两个 CC 逐字常量 /
- *    park 形状谓词都落在这里 —— 它是「内环路由」与「外环决断」都够得着的最低模块(`parkResolver.ts`
- *    import 本文件,反向没有边,不成环)。`askGateWire.ts` 原样 re-export 其中的公开面,对外零变化。
- *
- * 🔴 tool_end 的**有序**臂(拆分硬约束):原文 5 条分支的顺序是承重的 ——
- *    分类器 deny(结构性机器签名,比「fs 写报错」更特定)必须先于 fs 的 HOLD/REJECT 分支判。
- *    注册表化之后顺序不再由代码位置显式表达,所以 `TOOL_END_ARM_ORDER` 把顺序写成**数据**,
- *    模块加载期一条断言把两者钉死:重排 `TOOL_END_ARMS` 而不同批改 `TOOL_END_ARM_ORDER` ⇒ 当场抛。
- */
 import type { AgentEvent } from '@sema-agent/sdk';
 import type { HitlClientLike } from './hitlBridge.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
-/**
- * CC `utils/messages.ts` 的 `REJECT_MESSAGE` **逐字**(B7 搬迁差分 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.";
-/**
- * CC `utils/messages.ts` 的 `INTERRUPT_MESSAGE_FOR_TOOL_USE` **逐字**(件 B,#323 症状②,2026-08-25)。
- *
- * 🔴 CC 语料直证的两条事实(壳侧勘察,cli `src/utils/messages.ts:216-217` 逐字节同):
- *   ① `"Operation aborted"` 在 CC 只在 transport 层 throw,**从不上屏** —— 它是我们这条引擎链
- *      特有的产物,渲成红 `Error: Operation aborted` 是 CC 里根本不存在的形;
- *   ② CC 的**唯一**中断呈现形就是本串:壳的 `UserToolErrorMessage` 对
- *      `content.includes(INTERRUPT_MESSAGE_FOR_TOOL_USE)` 渲 dim `Interrupted`(CC 2.1.223 逐字判据)。
- * ⇒ 用户中断批的 tool_result 文案在**呈现向**归一到本串,三端就天然拿到 CC 的 Interrupted 形,
- *   不必各自再抄一份「Operation aborted 也算中断」的手工判据(那正是漂移温床)。
- * 🔴 **呈现向,不是模型面**:本包这条链是转录/渲染链;喂回模型的那一份由引擎自己的 wire 承载,
- *   这里一个字节都不碰它。
- */
 export declare const HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
-/**
- * core 对**被 gate park 的那个 call**(gate 主角)铸的 tool_end 载体(逐字;desktop session-host
- * 真引擎实测同款)。HOLD 谓词锚它做**精确等值** —— 普通工具错的输出是各自的错误文案,永不进 HOLD。
- *
- * 🔴 **勘误(件⑤,2026-08-22,[4970] 真机取证)**:此处原话是「core 对被 gate/**连坐** abort 的
- * call **恒**铸这一串」——对连坐的旁观者**不成立**。core 5.52.0 dist 直证两个短路点两种文案:
- * gate 主角走 abort 早退 = 本串;**执行前被连坐**的旁观者 = `"operation aborted before execution"`
- * (小写 + 后缀)。所以本串只是判据的**兜底臂**(旧 core 唯一的信号),主锚是机读码
- * `gate.parked`——见 {@link isEngineAbortToolEnd}。
- */
 export declare const ENGINE_ABORT_TOOL_RESULT = "Operation aborted";
-/**
- * tool_end.output 的文本归一(P0 案B,2026-08-03,server 6.0.0 wire 实测):sync leg 的毒化帧
- * `output` 不再是裸 string,而是 content-block 数组 `[{"type":"text","text":"Operation aborted"}]`
- * (8790 裸引擎 POST /v1/tasks/stream 逐帧记录字节形)。abort 标记的**等值锚**必须先归一再比,
- * 否则 6.0.0 下 hold-poison 臂全盲:毒化帧当场上屏 + generic-close 记 ended ⇒ decide 后重放的
- * 真收口帧被 isEnded 早退去重 —— 「按 Yes 屏幕永远停在 Error: Operation aborted」整案复发。
- * 只归一**判定**,帧本身一个字节不改;等值语义不放宽([2084]①-b 收窄仍然成立,负控见 gate ⑩)。
- * 🆕 [C93] 公面导出(0.17.1):web/desktop 被点名「两端务必接」的同款归一各自手抄=漂移温床,
- * 导出做单一真源;签名不变,加导出=additive。
- */
 export declare function toolEndOutputText(output: unknown): string | undefined;
-/** 本桥消费的 wire 面(@sema-agent/sdk AgentClient 的结构切片,mock 可注入)。 */
-/** L-80:非进展 reattach 的一次用户面告知(命名形,typeshape B4 棘轮:导出签名不带内联匿名对象)。 */
 export interface ParkReattachNotice {
-    /** 该臂同因连续第几次。 */
     attempt: number;
-    /** 该臂上限(到了就诚实收场)。 */
     max: number;
-    /** 真因 token(已解决码 / 传输错类词)。 */
     reason: string;
 }
 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;
-    /** L-80(2026-09-03,[6215]):**非进展** reattach 的用户面告知口 —— 每一轮「引擎重放了同一张 park /
-     *  decide 出站瞬断耗尽」而壳只能再附着一次时调一次(`attempt`=该臂同因连续第几次,`max`=该臂上限,
-     *  `reason`=真因 token)。缺席 = 只留 debug 行(修前形:24 轮空转用户零告知)。进展轮**不**调。 */
     onParkReattach?: (e: ParkReattachNotice) => void;
-    /** #229 respond-note 供给链(0.29.0 发包扫描门修,2026-08-12):帧腿车道参数(能力位读数),
-     *  宿主从自己的 caps 缓存供给。缺席 = note 门 fail-closed 到「不发」侧(决断照常,现状字节
-     *  不变)—— 此前包内唯一生产调用点(routeFrame 的 tool_approval 臂)无此位,note 恒不发。
-     *  ⚠️ **本位早已不只管 note**(0.43.0 订正,异源对抗复审五轮 [medium]:上句的「note 门」措辞
-     *  是 0.29.0 的历史射程,再留着会让宿主以为不接这个字段只损失一条备注)。`ToolApprovalFrameLaneOpts`
-     *  今天携带**四位**,缺席各有各的后果:`approvalDecisionNoteCapable`(备注不发)·
-     *  `respondFreeFormRulesCapable`(**编辑臂**整条不发)· `respondBatchRuleOffersCapable`
-     *  (**批臂**整条不发)· `windowIsCurrent`(窗三键不过境 ⇒ 卡上无倒计时)。后两位缺席时,人在卡上
-     *  按下的「不再询问」会被整条丢弃(决断照送 + 一条 `surfaceRuleArmNotSent` 通知)—— 逐位语义见
-     *  各自的 JSDoc 与 `docs/INTEGRATION-CLIENTS.md` §5b。 */
     approvalLane?: ToolApprovalFrameLaneOpts;
-    /**
-     * 0.74.1(CC-68)—— 流内帧腿的**结局回交**:每次 `tool_approval` 帧经卡口决断后调一次(帧 + {@link ToolApprovalFrameOutcome}),
-     * 宿主据此直接判「这一发落没落定」(孤儿认领回收不必再靠间接判据)。缺席零变化;抛错 / reject 被吞。
-     */
     onToolApprovalOutcome?: (frame: ToolApprovalFrame, outcome: ToolApprovalFrameOutcome) => void | Promise<void>;
 }
-/** 两族 gate:AskUserQuestion 走问答 overlay(原路);其余(fs 写三件 / Bash / 一等
- *  `kind==='tool_approval'`)走 CC 三选卡。 */
 export type GateKind = 'ask' | 'fs';
-/** park 请求:内环遇 gate 时带出去给外环决断。 */
 export interface GatePark {
     gate: GateKind;
-    /** sync leg 的 `done{suspended}` 终帧 —— fail-soft 回退时原样吐回去(durable leg 的 park 无此帧)。 */
     pendingDone?: AgentEvent | undefined;
-    /**
-     * 这张 park 的**待批 call 身份**(server ≥7.41.0,[4913]/[4914] 请托① 到货件)。
-     * 供给见 {@link parkGatedCallId};消费者今天只有一个:`parkResolver` 决断成功臂的
-     * `dropHeldForDecidedPark` —— 它此前只能拿 `findPendingForTask` 那个**卡面渲染宽口**当身份,
-     * 同族多行排队时会摘错 call 的扣留帧([4933] 立案的存量)。
-     * 🔴 缺席是**常态**(旧引擎 / tool-less park / 键畸形),消费方必须自带无身份也能走的臂。
-     * 🔴 刻意**不**喂给 `#324` 的连坐判别子:那条判据的换锚是独立一件事(S3/S33 的「已知局限锁」
-     *    断言到时会翻红 = 点亮信号),两件事混在一起改就分不清谁引入了假阳。
-     */
     gatedCallId?: string | undefined;
 }
-/** 帧路由的产物:驱动只认这四种,自己不再判帧型。 */
 export type FrameAction = {
     kind: 'yield';
     events: readonly AgentEvent[];
@@ -136,8 +42,6 @@ export type FrameAction = {
     kind: 'end';
     events: readonly AgentEvent[];
 };
-/** 跨刀共享的可变标量(`realTaskId`):sync leg 从 `done{suspended}` 捕获、外环 attach 时读。
- *  显式 ref 传参而不是让两把刀各存一份 —— 两份会在 durable 腿上分叉。 */
 export interface TaskIdRef {
     current: string | undefined;
 }
@@ -147,50 +51,12 @@ export interface FrameRouterCtx {
     taskId: TaskIdRef;
     signal?: AbortSignal | undefined;
 }
-/** 上者的**窄口**(`findPendingForTask` 的 gate 过滤谓词签名)—— 出境的那一版不吃 `unknown`:
- *  边界层的 unknown 在本模块里窄化完再跨模块(typeshape 门 B2 的纪律)。 */
 export declare function isAskTool(toolName: string | undefined): boolean;
-/** 这一帧是不是「host lane 的模型推进」= 扣留帧的放行信号。 */
 export declare function isHostProgressFrame(ev: AgentEvent): boolean;
-/** {@link flushHeldWithInterruptRewrite} 的出口证据(三腿,全是结构事实;缺席即不改写)。 */
 export interface HeldFlushInterruptEvidence {
-    /** 本出口手上的终帧(有就读它的 cancel 码);中途出口/无终帧路径传 `undefined`。 */
     terminal?: AgentEvent | undefined;
-    /** 宿主的 turn 中断信号。 */
     signal?: AbortSignal | undefined;
-    /**
-     * **这张 park 是被用户中断掉的**(`GateOutcome.kind === 'aborted'`)—— 唯一写者 =
-     * `parkResolver` 的 fail-soft 出口。该 outcome 在包内的语义就是逐字的「turn 被中断(Esc/Ctrl+C)」
-     * (见 `toolApprovalWire` 同臂:它顺带用一次 TOOL 级 deny `reason:'Interrupted by user'` 把
-     * 挂着的门结算掉),所以它是**关于这张 park 本身**的一手中断证据,不是推断。
-     */
     gateAbortedByUser?: boolean | undefined;
 }
-/**
- * `led.flushHeld()` 的**唯一**排水出口包装:用户中断批把毒化帧的 `output` 归一成 CC 的中断形
- * ({@link HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE}),其余一切原样。
- *
- * ── 判词(两模,别合并;方向一律 fail-safe:证据不足就走原路)──────────────────────────────
- *  · **模 A —— 纯用户中断批**(证据 = cancel 终帧码 / 宿主 `signal.aborted`):要求 **本批零 park
- *    登记**(`hasBatchPark() === false`),且帧上 `errorCode !== "gate.parked"`。两道门都是同一件事
- *    的两个面 ——「这一批背后没有任何门」才谈得上纯中断;有门而我们只看见 abort 帧 = 判不出,不改。
- *  · **模 B —— 门被用户中断**(证据 = {@link HeldFlushInterruptEvidence.gateAbortedByUser}):
- *    park 在场是**前提**而不是障碍,所以模 A 的两道门在这一模下**都让位** —— 包括
- *    `gate.parked` 那一票。理由:该码回答的是「这次调用为什么中止 =被门 park 了」,回答不了
- *    「这一批为什么收场 = 用户按了 Esc」,两者正交;拿它做否决会把这一格里**最该显形的那张
- *    主角卡**留成红 `Error: Operation aborted`(真机复现:审批卡挂着按 Esc,主角与连坐帧同文案)。
- * 🔴 **gate deny 语义零变**:deny 走的是 `decided` 分支(→ 续流重放 → `denied-call`/`deny-stamp-next`
- *    两臂 stamp CC REJECT 文案),那两臂排在 hold-poison **之前**、帧根本不进扣留表,本包装够不着。
- *    fail-soft 的其余原因(no_pending / 传输失败 / hop 用尽)三腿全不命中 ⇒ 诚实红照旧。
- *
- * 🔴 **只改 `output` 一个键**:`isError` / `errorCode` / `toolCallId` / `toolName` / `gate` /
- * `delivered` / `gatedCallId` / `structured` 以及 `flushHeld` 自己盖的
- * `_sema_collateral_abort` 机读位全部原样过境(展开赋值只覆盖 `output`)—— 端侧的连坐折叠锚的是
- * 机读位不是文案,所以折叠语义不受影响,只是被折那一行的正文换成了 CC 中断形。
- */
 export declare function flushHeldWithInterruptRewrite(led: GateLedger, evidence: HeldFlushInterruptEvidence): Generator<AgentEvent>;
-/**
- * 一帧 → 一个处置。手柄的**先后**与原文逐条同序:tool_approval 帧 → tool_start → tool_end →
- * suspended → done → failed → 透传。
- */
 export declare function routeFrame(ev: AgentEvent, ctx: FrameRouterCtx): Promise<FrameAction>;