@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hitl/planReviewWire.d.ts

@@ -1,216 +1,44 @@
-/**
- * ⇄ B7 批搬迁(2026-07-27,设计稿 §3 B7):cli `src/sema/planReviewWire.ts`(142 行)**整条进包**。
- *
- * 🔴 **`wireConfig()` 第七份收编闭合**:B6 的 `engineWireTarget.ts` 头注记着「本批搬入的是前六份;
- *    第七份 `planReviewWire` 不在 B6 范围,仍留壳内 —— 它是下一批的收编候选,别以为已经收干净了」。
- *    本批就是那一批:这里改用 `engineWireTarget()`,壳树 `grep -rn 'function wireConfig' src/sema/`
- *    的七份手抄至此**归零**(pure 门 B7 段有断言:壳树在场时命中数 = 0;缺席 ⇒ DEGRADED)。
- *
- * 🔴 其余搬迁差分(零行为变化):
- *   1. `logForDebugging` → `hostLog`。
- *   2. `await import('../utils/messageQueueManager.js').enqueuePendingNotification({...})`
- *      → `NotificationQueuePort.enqueueMetaPrompt`(B7 新增的**可选**方法 —— 既有宿主实现不破)。
- *      🔴 缺席后果不是「少个装饰」:模型永远不知道 plan 被批准/驳回后引擎跑出了什么结果,
- *      于是它在 approve 之后**原地不动**。所以缺席计 miss(`notificationQueuePortMisses()`),
- *      并保留壳原文的 try/catch fail-soft(投递失败绝不炸流)。
- *   3. `registerLocalQuestionResponder`/`publishQuestionFrame` → 包内 `liveQuestionStore`
- *      (B1 已搬,**同一个 module 台账**;两份实例 ⇒ 卡弹出来没人收答)。
- *
- * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
- *
- * planReviewWire — plan_review park 的壳侧审批闭环(core [508]③ 形状拍板 + [511]② 实证)。
- *
- * WIRE 全链(server 1.138 × core 1.257.4 探针逐字实证,probe-plan-final-frame.mjs):
- *   1. plan-mode turn 里模型调 ExitPlanMode → 引擎 park:done 帧 `status:"needs_review"` +
- *      `checkpointGate:{kind:"plan_review",reason:"ExitPlanMode"}` + `errorCode:"review.pending"`;
- *      plan 文本已由 ExitPlanMode tool_end 渲染在转录(fence 块),checkpoint 落 FileCheckpointStore。
- *   2. 壳(本模块,runStream done 分支调用)合成一个 QuestionFrame 借 AskUserQuestion overlay 弹
- *      审批卡(core 拍板:不新造 live question 帧,壳自绘)——合成 id `plan-review:<taskId>` 经
- *      liveQuestionStore 的 LOCAL responder 拦截,绝不会打到引擎的 /v1/questions(那里 404)。
- *   3. 决断 → POST /v1/assistant/tasks/:taskId/plan_review `{decision:"approve"|"reject"}`——
- *      resume 是 SYNC 驱动到终态的(实证 200 `{taskId,sessionId,status:"completed"}`,可能分钟级),
- *      所以 fire 后卡片即关,完成后经 enqueuePendingNotification 入队一个 isMeta turn:模型收到
- *      resume 终态,自然接续汇报(approve 后"继续干活"的 CC 体验由引擎侧 resume 已完成,这里是
- *      结果呈现)。reject 同构(引擎丢 plan 保持 plan 语境)。
- *
- * 挂账(诚实边界):approve 后壳本地的 plan-mode footer 徽章不自动退(CC 会退)——退 mode 的
- * app-state seam 不在本模块可达面,记 rc.47 接 REPL 层;engine 侧 handsReadOnly 已由 resume 处理。
- */
 import { type QuestionAnswer } from '../liveQuestionStore.js';
 import { type PlanReviewModeAfter } from './hitlBridge.js';
 import type { ReopenCardVerdict } from '../adapter/activeRunSelfHeal.js';
-/**
- * REF-CC-026:此前是 module-private 常量,唯一另一个消费者(cli `planReviewReopen.ts`)只能靠
- * 人眼手抄同步(头注写着「与 client-core planReviewWire 的原卡逐字一致」)——漂一个字节,判决就
- * 落到危险的默认臂(见下方 `planReviewDecisionFromAnswer` 的头注)。现在导出成唯一真源;cli 侧改
- * import 是后续跟车工单(壳仓文件域,不在本卡范围)。
- */
 export declare const PLAN_REVIEW_APPROVE_LABEL = "Yes, approve and run the plan";
 export declare const PLAN_REVIEW_REJECT_LABEL = "No, reject it (keep planning)";
-/**
- * 0.72.13 CC-46(engine ≥7.86.0 S-433;契约 §4c):三选卡的两个 Yes —— 对齐 CC `ExitPlanMode` 卡
- * 「Yes, and auto-accept edits」/「Yes, and manually approve edits」。只在**双闸**都过时才出三选卡(见 {@link planReviewCardOptions}
- * 的调用点):宿主声明这条任务是它自己用 `permissionMode:"plan"` 提交的(适用面读不到 wire)∧ 引擎版本证据 ≥7.86.0。
- */
 export declare const PLAN_REVIEW_APPROVE_AUTO_LABEL = "Yes, and auto-accept edits";
 export declare const PLAN_REVIEW_APPROVE_MANUAL_LABEL = "Yes, and manually approve edits";
-/** `permissionModeAfter` 的引擎地板(server 7.86.0;更老的 server 静默丢这个键 = 承诺了却不兑现)。 */
 export declare const PLAN_REVIEW_MODE_AFTER_MIN_ENGINE: readonly [number, number, number];
-/** 引擎版本串够不够新:三态 —— 读不出(缺席 / 非 x.y.z)⇒ `unknown`,**不折 supported**(没证据不许出三选卡)。 */
 export declare function versionSupportsPlanReviewModeAfter(v: string | undefined): 'supported' | 'unsupported' | 'unknown';
-/**
- * REF-CC-026:三值判决(此前 `selected === APPROVE_LABEL ? 'approve' : 'reject'` 把「没读懂/没
- * 选」的第三种输入静默塌缩进危险的 reject 臂——overlay 的 dismiss/拒答语义是「送空 answers」,
- * 与用户真的点了 REJECT_LABEL 长得一模一样)。两个标签都做**显式**等值比对,任何第三种输入
- * (含 undefined)落 `'dismissed'`,由调用方决定是保持 park 还是显式当 reject 处理——本函数只
- * 负责如实分类,不替调用方做选择。
- */
-export declare function planReviewDecisionFromAnswer(answer: QuestionAnswer | null | undefined, 
-/** 本次实际展示的那张卡的标签;不给 = 老两选(见 {@link planReviewChoiceFromAnswer})。 */
-shownLabels?: readonly string[]): 'approve' | 'reject' | 'dismissed';
-/** 0.72.13 CC-46:带批准后模式的判读(三选卡的两个 Yes 各带一档;老两选的 Yes 不带键)。标签显式等值比对,第三种输入 ⇒ dismissed。 */
+export declare function planReviewDecisionFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): 'approve' | 'reject' | 'dismissed';
 export type PlanReviewChoice = {
     decision: 'approve';
     permissionModeAfter?: PlanReviewModeAfter;
 } | {
     decision: 'reject';
 };
-export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, 
-/**
- * 本次**实际展示**的那张卡的标签(`planReviewCardOptions(offer).map(o => o.label)`);只认其中的标签。
- * 🔴 **不给 = 老两选**:三选卡的两个 Yes 只有调用方显式说「我展示的是三选卡」才读得成批准 —— 缺省不许替老调用方
- *    悄悄扩大批准的输入域(异源对抗复审:重开腿恒两选,缺省放行时一个没展示过的 auto 标签会被投递成 approve)。
- */
-shownLabels?: readonly string[]): PlanReviewChoice | 'dismissed';
-/** 卡选项的**单源**:`offerModeAfter=false` ⇒ 老两选(逐字同旧);`true` ⇒ 三选(两个 Yes + No)。 */
+export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): PlanReviewChoice | 'dismissed';
 export declare function planReviewCardOptions(offerModeAfter: boolean): Array<{
     label: string;
     description: string;
 }>;
-/**
- * 推代的**门控口**(A-024.4;#244 F1 上收,语义照壳现实现):只有**决断性**作答(approve/
- * reject 标签命中 —— {@link planReviewDecisionFromAnswer} 的官方三值分类)才消费当代 plan 门。
- * Esc/空答对原卡是 dismissal(arm 臂的 dismissed 分支不驱动 decidePlanReview,checkpoint 仍
- * pending)—— 那时推代会把「被关过」翻成「首见」,恰是 A-024.4 在最常见路径(Esc 关卡)上要
- * 保住的区分。消费方 = 宿主 overlay 的 answerAndRelease(respond 成功后调 —— 它是 responder
- * 之外**第二条**决断可见点,原卡与重开卡两条通路对同一张卡各报一次,`notePlanReviewAnswered`
- * 按完整 questionId 去重恰推一代);包内 responder 走 {@link notePlanReviewAnswered} 直报
- * (它们没有 dismissed 臂会到达记账行)。
- */
 export declare function notePlanReviewAnsweredIfDecisive(questionId: unknown, answer: QuestionAnswer | null | undefined): void;
-/**
- * done 帧的 plan_review park 形状(结构性读,别的终局一律 false)。
- *
- * 🔴 0.60.0(engine ≥7.64.0 / sdk 8.4.0):判据从退役的两个平面键(`status:"needs_review"` +
- *    `checkpointGate.kind`)换成带标因由 `terminal.paused.gate.kind`,读法单源
- *    {@link readRunTerminal}。门种仍**逐字只认 `plan_review`**(不顺手放宽到 `dry_run_review` /
- *    `needs_review`):本臂驱动的是那一个 resume verb,放宽等于把别的门送进一个它答不了的入口。
- */
 export declare function isPlanReviewPark(result: unknown): result is {
     taskId: string;
     sessionId?: string;
 };
-/** 测试钩:清掉武装态(不动 liveQuestionStore 本身,那边有自己的 reset)。 */
 export declare function _resetArmedPlanReviewsForTest(): void;
-/**
- * Arm the approval card for a parked plan_review (call with the RAW done.result). Returns true when
- * armed (live path + shape matched, INCLUDING the idempotent "already armed" short-circuit — see
- * REF-CC-027 above); false = caller renders the terminal as usual. Fail-soft: any error inside must
- * never break the stream drain.
- */
-export declare function armPlanReviewApproval(result: unknown, sessionKey?: string, 
-/**
- * 0.72.13 CC-46:`submittedInPlanMode: true` = 宿主声明「这条任务是我用 `permissionMode:"plan"` 提交的」(只读起步)。
- * 🔴 这件事**读不到 wire 上**(契约 §4c:两种任务产出同一张卡),所以只能由提交方声明;不声明 / false ⇒ 老两选卡、决断体不带键。
- * 声明了还要过第二道闸:本进程 caps 缓存里的引擎版本 ≥7.86.0(更老的 server 静默丢这个键 = 卡上承诺了却不兑现)。
- */
-opts?: {
+export declare function armPlanReviewApproval(result: unknown, sessionKey?: string, opts?: {
     submittedInPlanMode?: boolean;
 }): boolean;
-/**
- * 一次 plan-review 决断**有没有生效**(0.73.1;{@link decidePlanReview} 的 outcome 尾句按它选):
- *   · `took_effect` —— 回拉确认任务已离开审批门;
- *   · `advanced` —— 决断生效、任务推进到**另一张**审批门(不是做完了);
- *   · `still_parked` —— 送到了(200)但回拉确认任务仍锁在同一张门上(计划仍在等,这一形能确定);
- *   · `not_sent` —— 一个字节都没送出去(本地拒 / 无连接 / client 造不出)⇒ 计划仍在等,这一形也能确定;
- *   · `not_applied` —— 引擎明确拒收(4xx)⇒ 只知道这次没生效,**不知道**审批门还在不在(404 / 并发结算都可能)⇒ 先读任务状态;
- *   · `unconfirmed` —— 不知道(回拉不可用且回体无状态 / 5xx / 网络失败)。
- */
 export type PlanReviewDecisionEffect = 'took_effect' | 'advanced' | 'still_parked' | 'not_sent' | 'not_applied' | 'unconfirmed';
-/**
- * outcome 尾句的**唯一铸点**(给模型的下一步指令)。🔴 只有 `took_effect` 才许说「已批准并汇报做了什么 / 已拒绝」;
- * 其余三态一律不许出现把决断当成已生效的措辞 —— 那会让模型向用户汇报一件没发生的事。
- */
 export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect): string;
-/** 测试钩:清投递口闩。 */
 export declare function __resetPlanReviewDecisionLatchForTests(): void;
-export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', 
-/**
- * 0.72.13 CC-46(engine ≥7.86.0;契约 §4c):批准之后用哪一档。缺席 ⇒ 体逐字节同旧 `{decision}`。只配 approve、闭集两词 ——
- * 坏形本地拒(零 POST,outcome 如实说没送出去,不回显值)。引擎答 400 `request.field_conflict`(这条任务不是只读起步):
- * `default` 与缺席同义 ⇒ 去键重发恰一次;`acceptEdits` **不**重发(不静默降成逐次征询),outcome 说批准没生效。
- */
-permissionModeAfter?: string): Promise<void>;
-/**
- * {@link reopenPlanReviewCard} 的宿主参数。
- */
+export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string): Promise<void>;
 export interface ReopenPlanReviewOpts {
-    /**
-     * 宿主 overlay 是否按 questionId 做会话级去重(cli REPL 的 overlay 钩子 = true:它有一个
-     * `seenQuestionIds` 集,为的是 at-least-once wire 的重投不把 hook 跑第二遍 —— 拿 canonical id
-     * 再发一次,帧会被静默吃掉,「重开了」就成了假话)。
-     *   · `true`(缺省,两类宿主都安全):重开铸**每次都不同**的身份 `plan-review:<taskId>#reopen-*`;
-     *   · `false`:responder 仍绑着时按 canonical id 原样重呈(同一张卡、同一个 responder ——
-     *     与 arm 臂的重放重呈短路同形),不产生第二次 responder 注册。
-     */
     mintFreshQuestionId?: boolean;
-    /**
-     * 决断投递口(缺省 = 包内 `decidePlanReview` fire-and-forget,自带 outcome 通知管道)。
-     * 宿主要包一层重试/上屏编排(如 cli 的短退避恰一次重试腿)就从这里注入 —— 卡链/三态判决
-     * 单源在包,投递编排留端。
-     * 🔴 成文例外(0.29.0 发包扫描门):`mintFreshQuestionId:false` 且 canonical(arm)responder
-     * 仍绑着时走「同 id 重呈短路臂」——作答经 **arm 的既有 responder** 投递(缺省 decidePlanReview),
-     * 本注入口**不生效**(短路臂命中时 debug 留痕)。要保证注入口恒生效就走缺省 mintFresh 臂。
-     */
     deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
-    /**
-     * 多会话宿主的会话键(复审 [high] 补口;缺省 = DEFAULT_SESSION_KEY,cli 单会话装配零参不动)。
-     * overlay 在场检查 / 帧发布 / 呈现台账读写全部按此键走 `*For` 变体 —— 不传就落默认键,
-     * 多会话宿主不传 = 帧和台账都路由到别的会话的默认面,所以它们**必须**传自己的键。
-     * (`registerLocalQuestionResponder` 的 responder 表是进程级单表、id 全局唯一,不分键。)
-     * 🔴 已知局限(0.29.0 发包扫描门,候跟进票):`armPlanReviewApproval` 的 arm 臂是**默认会话**
-     * 装配(无 sessionKey 形参),其 responder 递交决断时清账走默认键 —— 非默认键会话对同一
-     * taskId 混用 arm 臂 + `mintFreshQuestionId:false` 重呈臂时,该键会话槽的呈现史不被消费
-     * (影响=后续首见/复见**文案**判定,动作两形一致)。多会话宿主避开该组合(用缺省 mintFresh)
-     * 或候 armPlanReviewApproval 补 sessionKey 位。
-     */
     sessionKey?: string;
-    /**
-     * **呈现回执模式**(#250 件1 语义;#244 F1 换装位,cli 装配用):在场 ⇒ 本函数转异步 ——
-     * publish 之后等宿主呈现面的登记事件(`waitForGateArmed`,键 = 本次发布的**原始帧 id**,
-     * 尝试级回执)最多这么多毫秒;回执到手才 `{reopened:true}`,窗尽如实 `{reopened:false}`。
-     * 🔴 本模式下重开腿**零登记**:登记时点 = 宿主 overlay 真入队点(`registerArmedGate
-     * FromQuestionId`),零回执还登记 = 下一次重开谎称复见(毒化 firstSight)。responder 在
-     * 窗尽后**故意保留**:hook 窗超过看门狗才入队的迟到卡必须仍可答(答不了的死卡比迟到更坏)。
-     * 缺席 ⇒ 同步路径逐字不变(0.30.0 行为:发布即登记、即回 `{reopened:true}`,像素级回执归
-     * 宿主经 `presented` 位补充)。
-     */
     presentationReceiptMs?: number;
 }
-/** 测试钩:清空重开 responder 台账(跨用例状态)。 */
 export declare function _resetActiveReopenRespondersForTest(): void;
-/**
- * 重开某个 parked plan_review 的审批卡(409 自愈分诊树 `attemptActiveRunSelfHeal` 的
- * `reopenPlanReview` 注入口的包内生产实现)。判决形/成文语义见 {@link ReopenCardVerdict}
- * (`adapter/activeRunSelfHeal.ts`);本函数不产 `presented` 位 —— 包看不到像素,回执机制归
- * 宿主端包装。绝不抛(turn 收尾路径)。
- *
- * 与 arm 臂的合成关系(A-028.4):首呈(done 帧)= `armPlanReviewApproval`;重开(409 撞锁)=
- * 本函数。两臂共用同一份题面构造点/标签单源/决断三态判决与同一条 `decidePlanReview` 投递管道;
- * 「铸新 questionId 还是复用同 id」由宿主去重语义作参数(见 {@link ReopenPlanReviewOpts})。
- * firstSight 判据 = 呈现台账(`armedGateRegistry`,键 = canonical `plan-review:<taskId>`);
- * 先查后记 —— 顺序决定判决正确性。
- */
 export declare function reopenPlanReviewCard(taskId: string, opts: ReopenPlanReviewOpts & {
     presentationReceiptMs: number;
 }): Promise<ReopenCardVerdict>;