@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/hitl/approvalDecisionNoteAudit.d.ts

@@ -1,58 +1,9 @@
-/**
- * hitl/approvalDecisionNoteAudit.ts — 审批**回决备注**(`decisionNote` / `noteRecorded`)的读面
- * 判定 + 人话行(#265 上收件,2026-08-14;源形 = cli `src/sema/approvalDecisionNoteAudit.ts`,
- * 供给半场 = server 7.15.0 的 `AskDecisionAck.decisionNote` / `ToolApprovalRespondAck.noteRecorded`)。
- *
- * ── 病 ────────────────────────────────────────────────────────────────────────────────────────
- * 送出去的那条 deny 理由到底有没有落进审计档,客户端这边**一个字都不知道**:决断腿此前是
- * `await decide…` 裸调,回体整个被丢掉。于是「我写了拒绝理由」与「那条理由真的进了审计行」之间
- * 没有任何证据 —— deny 归因链在用户这一端是断的。
- *
- * ── 三态,不是两态 ────────────────────────────────────────────────────────────────────────────
- * server 对这一位的契约(SDK `ToolApprovalRespondAck.noteRecorded` / `AskDecisionAck.decisionNote`
- * 头注逐字)是**三态**,把它压成布尔就会造谎:
- *   · `recorded`     —— `noteRecorded === true`,**或** durable ack 回显了 `decisionNote` 正文
- *                       (契约:「行上有才发」⇒ 回显本身就是落行的证据);
- *   · `not-recorded` —— `noteRecorded === false`。这是店的**真实结果**(并发歧义臂的输家如实 false),
- *                       它说的是「理由没落档」,**不是**「审批失败」—— 决断照旧成立,渲染面必须
- *                       在同一行里把这句说出来,否则用户会以为自己按的那个拒绝没生效;
- *   · `unknown`      —— 两个位都不在场(旧 server / 这台部署没有 durable ask 账本 / 本次压根没送 note)。
- *                       ⇒ **整行不渲**。缺席≠false —— 渲一行「未记录」等于替引擎回答一个它没回答
- *                       的问题。
- *
- * 🔴 `noteRecorded === false` **压过**正文回显:显式的 per-call 真相优先。两者同时在场的形
- *    (并发歧义臂:行上留的是赢家那条备注,我这条没落)只有这样才说得准 —— 正文仍带出来当归因
- *    材料(用户看得见「行上现在是哪条」),但状态词按 false 走。
- *
- * ── 🔴 归层 ───────────────────────────────────────────────────────────────────────────────────
- * 本文件 = **纯判定 + 文案**,`import` 列表为空(常驻门 ④ 段逐次对账)。呈现口不在这里 ——
- * 装配层把行交给宿主的通知/转录面。三端(cli / desktop / web)撞的是同一件事,读的是同一份 ack。
- *
- * ── UNTRUSTED ─────────────────────────────────────────────────────────────────────────────────
- * `decisionNote` 的正文是**卡口自由文本**原样回声(用户自己打的拒绝理由,也可能是别的客户端打的)。
- * 读面就地有界截断 + 清洗控制字符 —— 只渲染,永不回喂模型,也绝不整段进日志。
- */
-/** 审计面通知的独占 key —— 与审批流告警面分格(两件事不抢同一格)。 */
 export declare const DECISION_NOTE_NOTICE_KEY = "approval-decision-note";
-/** 备注面的三态判决。`note` = 引擎回显的正文(缺席 = 引擎没回显,**不是**「没有备注」)。 */
 export interface DecisionNoteAudit {
     state: 'recorded' | 'not-recorded' | 'unknown';
     note?: string;
 }
-/**
- * 读一份回体(durable `AskDecisionAck` / legacy `ToolApprovalRespondAck` / 409
- * `conflict.ask_decided` 体)里的备注面判决。
- *
- * 🔴 **在场即读、不在场即 unknown**:两个位在 SDK 类型上都是可选的,而「类型说 optional」与
- *    「这台引擎真的发了」是两件事 —— 一律结构窄读,读不出就是缺席,绝不合成。
- */
 export declare function readDecisionNoteAudit(ack: unknown): DecisionNoteAudit;
-/**
- * 人话行。**`unknown` ⇒ `null`(整行不渲)** —— 这条纪律不可削。
- *
- * @param opts.settledElsewhere 这份材料来自 409 `conflict.ask_decided`(别的客户端/legacy 腿先结算)
- *   ⇒ 行里要点明归因来源,否则用户会把首决那条备注当成自己刚写的那条。
- */
 export declare function decisionNoteAuditLine(audit: DecisionNoteAudit, opts?: {
     settledElsewhere?: boolean;
 }): string | null;

package/dist/hitl/approvalDecisionNoteAudit.js

@@ -1,45 +1,5 @@
-/**
- * hitl/approvalDecisionNoteAudit.ts — 审批**回决备注**(`decisionNote` / `noteRecorded`)的读面
- * 判定 + 人话行(#265 上收件,2026-08-14;源形 = cli `src/sema/approvalDecisionNoteAudit.ts`,
- * 供给半场 = server 7.15.0 的 `AskDecisionAck.decisionNote` / `ToolApprovalRespondAck.noteRecorded`)。
- *
- * ── 病 ────────────────────────────────────────────────────────────────────────────────────────
- * 送出去的那条 deny 理由到底有没有落进审计档,客户端这边**一个字都不知道**:决断腿此前是
- * `await decide…` 裸调,回体整个被丢掉。于是「我写了拒绝理由」与「那条理由真的进了审计行」之间
- * 没有任何证据 —— deny 归因链在用户这一端是断的。
- *
- * ── 三态,不是两态 ────────────────────────────────────────────────────────────────────────────
- * server 对这一位的契约(SDK `ToolApprovalRespondAck.noteRecorded` / `AskDecisionAck.decisionNote`
- * 头注逐字)是**三态**,把它压成布尔就会造谎:
- *   · `recorded`     —— `noteRecorded === true`,**或** durable ack 回显了 `decisionNote` 正文
- *                       (契约:「行上有才发」⇒ 回显本身就是落行的证据);
- *   · `not-recorded` —— `noteRecorded === false`。这是店的**真实结果**(并发歧义臂的输家如实 false),
- *                       它说的是「理由没落档」,**不是**「审批失败」—— 决断照旧成立,渲染面必须
- *                       在同一行里把这句说出来,否则用户会以为自己按的那个拒绝没生效;
- *   · `unknown`      —— 两个位都不在场(旧 server / 这台部署没有 durable ask 账本 / 本次压根没送 note)。
- *                       ⇒ **整行不渲**。缺席≠false —— 渲一行「未记录」等于替引擎回答一个它没回答
- *                       的问题。
- *
- * 🔴 `noteRecorded === false` **压过**正文回显:显式的 per-call 真相优先。两者同时在场的形
- *    (并发歧义臂:行上留的是赢家那条备注,我这条没落)只有这样才说得准 —— 正文仍带出来当归因
- *    材料(用户看得见「行上现在是哪条」),但状态词按 false 走。
- *
- * ── 🔴 归层 ───────────────────────────────────────────────────────────────────────────────────
- * 本文件 = **纯判定 + 文案**,`import` 列表为空(常驻门 ④ 段逐次对账)。呈现口不在这里 ——
- * 装配层把行交给宿主的通知/转录面。三端(cli / desktop / web)撞的是同一件事,读的是同一份 ack。
- *
- * ── UNTRUSTED ─────────────────────────────────────────────────────────────────────────────────
- * `decisionNote` 的正文是**卡口自由文本**原样回声(用户自己打的拒绝理由,也可能是别的客户端打的)。
- * 读面就地有界截断 + 清洗控制字符 —— 只渲染,永不回喂模型,也绝不整段进日志。
- */
-/** 备注面在渲染时的正文上界(一行 footer 通知,不是转录面正文)。 */
 const NOTE_DISPLAY_MAX = 200;
-/** 审计面通知的独占 key —— 与审批流告警面分格(两件事不抢同一格)。 */
 export const DECISION_NOTE_NOTICE_KEY = 'approval-decision-note';
-/**
- * 控制字符/换行清洗 + 有界截断(UNTRUSTED 正文只走这一个口)。
- * 🔴 换行必须折平:footer 通知是**单行**面,一条带换行的备注会把整段排版撕开。
- */
 function cleanNote(raw) {
     const flat = raw
         .replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ')
@@ -47,40 +7,24 @@ function cleanNote(raw) {
         .trim();
     return flat.length <= NOTE_DISPLAY_MAX ? flat : `${flat.slice(0, NOTE_DISPLAY_MAX - 1)}…`;
 }
-/**
- * 读一份回体(durable `AskDecisionAck` / legacy `ToolApprovalRespondAck` / 409
- * `conflict.ask_decided` 体)里的备注面判决。
- *
- * 🔴 **在场即读、不在场即 unknown**:两个位在 SDK 类型上都是可选的,而「类型说 optional」与
- *    「这台引擎真的发了」是两件事 —— 一律结构窄读,读不出就是缺席,绝不合成。
- */
 export function readDecisionNoteAudit(ack) {
     if (ack === null || typeof ack !== 'object')
         return { state: 'unknown' };
     const o = ack;
     const note = typeof o.decisionNote === 'string' && o.decisionNote.trim() !== '' ? cleanNote(o.decisionNote) : undefined;
-    // 显式 per-call 真相优先(见头注)。
     if (o.noteRecorded === false)
         return { state: 'not-recorded', ...(note !== undefined ? { note } : {}) };
     if (o.noteRecorded === true)
         return { state: 'recorded', ...(note !== undefined ? { note } : {}) };
-    // `noteRecorded` 是非布尔垃圾值(旧 server / 代理改写)⇒ 当它不在场,只看正文回显。
     if (note !== undefined)
         return { state: 'recorded', note };
     return { state: 'unknown' };
 }
-/**
- * 人话行。**`unknown` ⇒ `null`(整行不渲)** —— 这条纪律不可削。
- *
- * @param opts.settledElsewhere 这份材料来自 409 `conflict.ask_decided`(别的客户端/legacy 腿先结算)
- *   ⇒ 行里要点明归因来源,否则用户会把首决那条备注当成自己刚写的那条。
- */
 export function decisionNoteAuditLine(audit, opts) {
     if (audit.state === 'unknown')
         return null;
     const quoted = audit.note !== undefined ? `: "${audit.note}"` : '';
     if (opts?.settledElsewhere === true) {
-        // 首决备注只在 recorded 侧有意义(false = 我这条没落,但行上仍是别人那条)。
         return audit.state === 'recorded'
             ? `this approval was already decided elsewhere — the reason recorded on the audit trail${quoted}`
             : `this approval was already decided elsewhere; your reason was not saved to the audit trail — that decision stands${quoted}`;

package/dist/hitl/approvalOutcomeNote.d.ts

@@ -1,5 +1,4 @@
 import type { ToolApprovalFrame, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
-/** 宿主便签形(三端同一形;`retracted` / `detail` 在场才带)。 */
 export interface StreamApprovalOutcomeNote {
     readonly approvalId: string;
     readonly settled: boolean;
@@ -8,5 +7,4 @@ export interface StreamApprovalOutcomeNote {
 }
 export declare const APPROVAL_NOTE_RETRACTED_DETAIL = "the card was retracted (this host no longer has a decision port for it)";
 export declare const APPROVAL_NOTE_EDIT_REFUSED_DETAIL = "edits are not accepted on this card";
-/** 帧 + 结局 → 便签(纯函数;结局上的坏形按缺席读,不抛)。 */
 export declare function approvalOutcomeNoteOf(frame: Pick<ToolApprovalFrame, 'approvalId'>, outcome: ToolApprovalFrameOutcome): StreamApprovalOutcomeNote;

package/dist/hitl/approvalOutcomeNote.js

@@ -1,40 +1,20 @@
-/**
- * approvalOutcomeNote — 流内帧腿的审批结局回交(`AskGateWireDeps.onToolApprovalOutcome(frame, outcome)`,0.74.1 CC-68)
- * 到宿主「审批结局便签」的**单源映射**(0.74.5 CC-88;此前三端装配点各手拼一份,语义以 cli 1.0.123 现行为准):
- *   · `approvalId` = 帧上的原词;
- *   · `settled` = 这次决断**落定了**(respond 送达并落定;**不看** ack 在不在 —— ack 是 server 的回执形,宿主不读);
- *     判据 = {@link approvalResolutionOf} 的落定臂,与旧口径 `outcome.decision !== 'unresolved'` 在实装可达的每一形上同值
- *     (撤卡 / 编辑被拒两形只与 `'unresolved'` 同场铸出);
- *   · `retracted` 只在 `outcome.retracted === true` 时带键(**独立判别位**,不折进 detail:撤卡 ≠ 投递失败 —— 释放认领但不扣重出卡预算);
- *     `editRefused` **不算** retracted,只折进 detail;
- *   · `detail` 三支优先序:撤卡固定句 → 编辑被拒固定句 → `respondRefusal` 的 errorCode / message 过滤非空后 ` · ` 拼接;
- *     拼出空串 ⇒ 键缺席(绝不编一句;不用决断词、不用 ack 摘要)。
- *
- * 🔴 **三位的判据自本版起由 {@link approvalResolutionOf} 派生**(「一次决断最后怎么了」的单源判别联合):
- *    `settled` = 落定臂;`retracted` = 「零字节 · 撤卡」这一 cause;`detail` 的三支 = 那三个臂/cause 的
- *    三个分支。本便签的**导出形与逐字输出不变** —— 变的只是判据不再在这里第二次手读旁挂布尔位
- *    (同一个问题两处各判一次 = 两份判据必然分叉)。
- */
 import { approvalNotSentCause, approvalResolutionOf, isApprovalDecided, } from './approvalResolution.js';
 export const APPROVAL_NOTE_RETRACTED_DETAIL = 'the card was retracted (this host no longer has a decision port for it)';
 export const APPROVAL_NOTE_EDIT_REFUSED_DETAIL = 'edits are not accepted on this card';
 function nonEmpty(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/** 结局的三支 detail(与 {@link ApprovalResolution} 的臂/cause 一一对应;拼出空串 = 没有可交的原文)。 */
 function detailOf(r) {
     const cause = approvalNotSentCause(r);
     if (cause === 'retracted')
         return APPROVAL_NOTE_RETRACTED_DETAIL;
     if (cause === 'edit_refused')
         return APPROVAL_NOTE_EDIT_REFUSED_DETAIL;
-    // 引擎那一头给的原文:机器码 + 拒句,各自非空才进,` · ` 拼(不复述决断词、不摘 ack)。
     if (r.kind === 'unsettled') {
         return [nonEmpty(r.errorCode), nonEmpty(r.detail)].filter((x) => x !== undefined).join(' · ');
     }
     return '';
 }
-/** 帧 + 结局 → 便签(纯函数;结局上的坏形按缺席读,不抛)。 */
 export function approvalOutcomeNoteOf(frame, outcome) {
     const r = approvalResolutionOf(outcome);
     const retracted = approvalNotSentCause(r) === 'retracted';

package/dist/hitl/approvalResolution.d.ts

@@ -1,148 +1,35 @@
-/**
- * approvalResolution — 「**一次审批决断最后怎么了**」的单源判别联合({@link ApprovalResolution})
- * 与它的唯一映射口({@link approvalResolutionOf})。
- *
- * ── 这一件修的是什么 ────────────────────────────────────────────────────────────────────────
- * 同一个问题今天有**两种结局形**,而且第二种把三件互斥的事挤进同一个词:
- *   · durable-park 腿 {@link import('./toolApprovalWire.js').FsApprovalOutcome} —— 四个 `kind`
- *     + `failed.stage` 五词;
- *   · 流内帧腿 / 悬挂 ask(盲卡)腿 {@link import('./toolApprovalWire.js').ToolApprovalFrameOutcome}
- *     —— `decision` 四词,其中 `'unresolved'` 有 **3 种互斥含义**(宿主撤卡 / 编辑被拒 / respond 没落定),
- *     要再读兄弟布尔位(`retracted` / `editRefused`)才分得开。
- * ⇒ 本模块给出**一个**判别联合,两条腿的每一种结局各落恰一个臂 + 一个 cause 词,`'unresolved'`
- *   的三义各落一臂。消费端从此一次判别拿到答案,不再靠读旁挂布尔位。
- *
- * ── 🔴 本版是 **additive**:既有型面一字未动 ───────────────────────────────────────────────
- * `FsApprovalOutcome` / `ToolApprovalFrameOutcome` / `ApprovalCardDecision` 的键、值、语义
- * **逐字节不变**;本模块只是**读**它们。端可以立刻改读本联合,也可以照旧读原结局对象。
- *
- * ── 三个臂各自答什么(边界写清,别处不许重铸)────────────────────────────────────────────────
- *   · `decided` —— 决断**送到了引擎并拿到语义答复**;
- *   · `not_sent` —— 包侧**一个字节都没发**(引擎那头的 ask 照旧挂着,`'no_pending'` 这一 cause 例外:
- *     那一行本来就已经不在了);
- *   · `unsettled` —— **没落定**。🔴 它**刻意不承诺**「字节已经出站」:见
- *     {@link ApprovalUnsettledCause} 的 `'safety_stop'` / `'orchestration'` 两词的头注 ——
- *     那两格在今天的结局对象上**分不出**决断有没有出站,而一个「保证发了」的承诺在这里是编的。
- */
 import type { DecideReceiptView } from '../decideReceipt.js';
 import type { HitlSafetyCode } from './hitlBridge.js';
 import type { FsApprovalOutcome, ToolApprovalFrameOutcome, ToolApprovalRespondAckView, ToolApprovalRespondDecision } from './toolApprovalWire.js';
-/**
- * 「包侧一个字节都没发」的因由闭集(**唯一真源**;端零手抄)。
- *  · `'retracted'` —— 宿主撤掉了一张已经没有决断口的卡(两条腿都有这一形)。
- *  · `'edit_refused'` —— 入参不可得的卡(悬挂 ask)上收到「编辑后批准」:丢掉改写再批准、或把改写
- *    转发出去,两条都不是人按下的那个决定 ⇒ 整次不发。
- *  · `'no_pending'` —— 取件那一拍队列里没有本 run 的可决行(结构化判别位,不是文案猜的)。
- *  · `'fetch_failed'` —— 取件这一步**自己**失败了(与上一词结构可分:那是「没有行」,这是「问不出来」)。
- *  · `'no_input'` —— 行上没有可呈现的工具入参,卡渲不出来。
- *  · `'card_unavailable'` —— 卡口那一段失败(没装卡口 / 卡口自报失败)。
- */
 export declare const APPROVAL_NOT_SENT_CAUSES: readonly ["retracted", "edit_refused", "no_pending", "fetch_failed", "no_input", "card_unavailable"];
-/** {@link APPROVAL_NOT_SENT_CAUSES} 的成员型。 */
 export type ApprovalNotSentCause = (typeof APPROVAL_NOT_SENT_CAUSES)[number];
-/**
- * 「没落定」的因由闭集(**唯一真源**;端零手抄)。
- *  · `'engine_refused'` —— 决断发出去了,引擎**真的答复并拒了**(卡通常仍 pending、决定没被消费)。
- *    🔴 **只在有肯定证据时才给这个词**:结局对象上带着引擎的 wire 机器码,或带着引擎在拒体上铸的指路键。
- *    没有证据的 decide 失败落 `'decide_failed'` —— 见下一词。
- *  · `'decide_failed'` —— decide 这一段失败了,而结局对象上**没有任何「引擎答复过」的证据**:
- *    调用方中止(人按了 Esc,出站前就抛)、抛出物身上根本没有码、老引擎的无码失败,三形同落这里。
- *    🔴 **不许**据此说「引擎拒了」:那三形里有两形连字节都没出去。要不要重呈看别的位,不看这个词。
- *  · `'transport_exhausted'` —— 出站瞬断类失败重试后仍未送达:**两发都没拿到语义答复**。
- *  · `'safety_stop'` —— 本包的安全停闭集({@link HitlSafetyCode})命中 ⇒ 要重新呈现给人,**绝不自动重发**。
- *    🔴 **这一格不承诺字节已出站**:`'binding_mismatch'` 既可能是本地绑定守卫在发送**前**拦下的,
- *    也可能是引擎 409 答复重抛的 —— 今天的结局对象上这两个出处**不可分**,所以这里只说「没落定」。
- *  · `'respond_failed'` —— 流内帧腿的 respond 抛错:这次决断没落定,**引擎按 TTL / abort 自决**。
- *  · `'interrupted'` —— turn 被中断:包侧**发起**了一次工具级拒绝来结算挂着的 ask,但那一发是不观察结果的,
- *    而且它自己也可能在出站前本地失败(绑定键缺失一类)。⇒ 既不能说落定,也**不能**说「一个字节都没发」。
- *    🔴 它**不是** `not_sent`:`not_sent` 是「零字节」的承诺,这一格给不出那个承诺。
- *  · `'orchestration'` —— 重挂环在硬上限 / 连续零进展上收口:那不属于决断链的任何一段,
- *    结局对象上**分不出**决断有没有出站。
- *  · `'unreadable'` —— 这个结局对象读不出来(不是对象 / 两个判别位都不成词 / 段词不认识)。
- *    🔴 读不出**绝不猜 `decided`**,也不敢说「零字节」——两个方向猜错的代价都是替人说一句他没说的话。
- */
 export declare const APPROVAL_UNSETTLED_CAUSES: readonly ["engine_refused", "decide_failed", "transport_exhausted", "safety_stop", "respond_failed", "interrupted", "orchestration", "unreadable"];
-/** {@link APPROVAL_UNSETTLED_CAUSES} 的成员型。 */
 export type ApprovalUnsettledCause = (typeof APPROVAL_UNSETTLED_CAUSES)[number];
-/** 决断送到了引擎并拿到语义答复。 */
 export interface ApprovalResolutionDecided {
     kind: 'decided';
-    /**
-     * 落定的决断词,**原样透传**。
-     * 🔴 **不在这里复校闭集**:帧腿的词已经在它自己的发送段窄化过,边界上再校一遍等于装第二个判官
-     *    (一个表外的词会被降成「读不出」,而它其实是引擎收下的那个决断)。
-     * 🔴 durable-park 腿只可能给 `'allow'` / `'deny'`:那一腿的结局对象上**没有**「remember 送成了」
-     *    这一位,所以这里**不铸** `'allow_session'`(铸一个就是替引擎说一句它没说的话)。
-     * 🔴 流内帧腿上 **fail-closed 的拒绝与人按的拒绝不可分**(卡口的 `aborted` / `failed` 与 `deny`
-     *    在发送段折成同一个词)—— 今天的真相如实说,本联合不发明新位。
-     */
     decision: ToolApprovalRespondDecision;
-    /** 待批 call 身份(durable-park 腿在场;帧腿没有这一位 —— 身份在帧的 `approvalId` 上,**不是**「没有身份」)。 */
     gatedCallId?: string;
-    /** decide 的 200 回执读数(缺席 = 老 server / 终局形 / 回体读不动,三形同缺);🔴 它**不是**「门已解决」的证据。 */
     receipt?: DecideReceiptView;
-    /** respond 的 200 ack(缺席 = **未知**:注入面回 void / 旧 server / 相关性门丢弃,绝不当成 false)。 */
     ack?: ToolApprovalRespondAckView;
 }
-/** 包侧一个字节都没发。 */
 export interface ApprovalResolutionNotSent {
     kind: 'not_sent';
     cause: ApprovalNotSentCause;
     gatedCallId?: string;
-    /** 本包铸的诊断文案(原样;读不出 / 空串 ⇒ 键缺席,绝不编一句)。 */
     detail?: string;
 }
-/** 没落定(见模块顶注:**不承诺**字节已出站)。 */
 export interface ApprovalResolutionUnsettled {
     kind: 'unsettled';
     cause: ApprovalUnsettledCause;
     gatedCallId?: string;
-    /** 本包的安全停判别位(`'safety_stop'` 这一 cause 上在场)。 */
     safetyCode?: HitlSafetyCode;
-    /** 引擎的 wire 机器码(开集,原样;缺席**不带语义** —— 缺席 ≠「不是引擎拒的」)。 */
     errorCode?: string;
-    /** 应答的 HTTP 状态(在场 = 引擎真应答了;缺席 = 传输层失败 / 注入面自抛,**不许**反推成 0)。 */
     status?: number;
-    /** 可呈现的原文(帧腿 = 引擎的拒句原文;durable 腿 = 本包铸的诊断文案)。读不出 ⇒ 键缺席。 */
     detail?: string;
 }
-/**
- * 一次审批决断的**结局**(判别联合;三臂穷举,`'unresolved'` 的三义各落一臂)。
- *
- * 与旧读法的对照(消费端迁移判据一句话):
- *   · `out.decision !== 'unresolved'`(帧腿)⇒ `approvalResolutionOf(out).kind === 'decided'`;
- *   · `out.retracted === true` ⇒ `approvalNotSentCause(r) === 'retracted'`;
- *   · `out.editRefused === true` ⇒ `approvalNotSentCause(r) === 'edit_refused'`;
- *   · 裸 `'unresolved'` ⇒ `approvalUnsettledCause(r) === 'respond_failed'`。
- *
- * 🔴 **不并表的位**:指路键(`currentPending`)、ack 的逐位解释、receipt 的逐位语义照旧读原结局
- *    对象 —— 本联合只答「怎么了」这一个问题。
- */
 export type ApprovalResolution = ApprovalResolutionDecided | ApprovalResolutionNotSent | ApprovalResolutionUnsettled;
-/**
- * {@link approvalResolutionOf} 认的入参:两条腿今天的结局对象。
- * 🔴 ask / plan-review 腿的 `GateOutcome` **刻意不在**这个联合里(它多一个 `answered` 位与一张
- *    另外的失败码闭集),plan-review 的决断生效读数也不在(它自己是另一张六词表)。
- * ⚠️ **这是分工边界,不是一道编译期围栏**,如实说:只有 `failed` 那一臂因为失败码闭集不同而赋不进来;
- *    `decided` / `aborted` 两臂在结构上仍然兼容,硬喂进来会被按本腿的口径读(`answered` 被忽略、
- *    别的码表词读不出判别位)。把别的腿的结局喂进本口是调用方的错,本函数不替它兜。
- */
 export type ApprovalLegOutcome = FsApprovalOutcome | ToolApprovalFrameOutcome;
-/**
- * 今天各腿的结局对象 → {@link ApprovalResolution}。**纯函数,永不抛,永不造**。
- *
- * 判别序(固定,不随键序变):
- *   ① `kind` 是 durable-park 腿的闭四词 ⇒ 按那一腿读;
- *   ② 否则决断词是串 ⇒ 按流内帧腿 / 盲卡腿读;
- *   ③ 都不成立 ⇒ `unsettled{cause:'unreadable'}`(🔴 不猜 `decided`,也不说「零字节」)。
- *
- * 🔴 **旁挂位在场压过决断词**(帧腿):撤卡 / 编辑被拒这两形是「一个字节都没发」,而它们今天与
- *    `decision` 同在一只对象上;先读决断词就会把一张没发出去的卡说成「批过了」。
- */
 export declare function approvalResolutionOf(outcome: ApprovalLegOutcome): ApprovalResolution;
-/** 这次决断**落定了吗**(唯一判据;`true` ⇒ 决断送到并拿到语义答复)。坏形入参 ⇒ `false`。 */
 export declare function isApprovalDecided(r: ApprovalResolution): r is ApprovalResolutionDecided;
-/** 「一个字节都没发」的因由;不是那一臂 ⇒ `undefined`(**不是**「发了」的证据,只是「不是这一臂」)。 */
 export declare function approvalNotSentCause(r: ApprovalResolution): ApprovalNotSentCause | undefined;
-/** 「没落定」的因由;不是那一臂 ⇒ `undefined`。 */
 export declare function approvalUnsettledCause(r: ApprovalResolution): ApprovalUnsettledCause | undefined;

package/dist/hitl/approvalResolution.js

@@ -1,13 +1,3 @@
-/**
- * 「包侧一个字节都没发」的因由闭集(**唯一真源**;端零手抄)。
- *  · `'retracted'` —— 宿主撤掉了一张已经没有决断口的卡(两条腿都有这一形)。
- *  · `'edit_refused'` —— 入参不可得的卡(悬挂 ask)上收到「编辑后批准」:丢掉改写再批准、或把改写
- *    转发出去,两条都不是人按下的那个决定 ⇒ 整次不发。
- *  · `'no_pending'` —— 取件那一拍队列里没有本 run 的可决行(结构化判别位,不是文案猜的)。
- *  · `'fetch_failed'` —— 取件这一步**自己**失败了(与上一词结构可分:那是「没有行」,这是「问不出来」)。
- *  · `'no_input'` —— 行上没有可呈现的工具入参,卡渲不出来。
- *  · `'card_unavailable'` —— 卡口那一段失败(没装卡口 / 卡口自报失败)。
- */
 export const APPROVAL_NOT_SENT_CAUSES = Object.freeze([
     'retracted',
     'edit_refused',
@@ -16,27 +6,6 @@ export const APPROVAL_NOT_SENT_CAUSES = Object.freeze([
     'no_input',
     'card_unavailable',
 ]);
-/**
- * 「没落定」的因由闭集(**唯一真源**;端零手抄)。
- *  · `'engine_refused'` —— 决断发出去了,引擎**真的答复并拒了**(卡通常仍 pending、决定没被消费)。
- *    🔴 **只在有肯定证据时才给这个词**:结局对象上带着引擎的 wire 机器码,或带着引擎在拒体上铸的指路键。
- *    没有证据的 decide 失败落 `'decide_failed'` —— 见下一词。
- *  · `'decide_failed'` —— decide 这一段失败了,而结局对象上**没有任何「引擎答复过」的证据**:
- *    调用方中止(人按了 Esc,出站前就抛)、抛出物身上根本没有码、老引擎的无码失败,三形同落这里。
- *    🔴 **不许**据此说「引擎拒了」:那三形里有两形连字节都没出去。要不要重呈看别的位,不看这个词。
- *  · `'transport_exhausted'` —— 出站瞬断类失败重试后仍未送达:**两发都没拿到语义答复**。
- *  · `'safety_stop'` —— 本包的安全停闭集({@link HitlSafetyCode})命中 ⇒ 要重新呈现给人,**绝不自动重发**。
- *    🔴 **这一格不承诺字节已出站**:`'binding_mismatch'` 既可能是本地绑定守卫在发送**前**拦下的,
- *    也可能是引擎 409 答复重抛的 —— 今天的结局对象上这两个出处**不可分**,所以这里只说「没落定」。
- *  · `'respond_failed'` —— 流内帧腿的 respond 抛错:这次决断没落定,**引擎按 TTL / abort 自决**。
- *  · `'interrupted'` —— turn 被中断:包侧**发起**了一次工具级拒绝来结算挂着的 ask,但那一发是不观察结果的,
- *    而且它自己也可能在出站前本地失败(绑定键缺失一类)。⇒ 既不能说落定,也**不能**说「一个字节都没发」。
- *    🔴 它**不是** `not_sent`:`not_sent` 是「零字节」的承诺,这一格给不出那个承诺。
- *  · `'orchestration'` —— 重挂环在硬上限 / 连续零进展上收口:那不属于决断链的任何一段,
- *    结局对象上**分不出**决断有没有出站。
- *  · `'unreadable'` —— 这个结局对象读不出来(不是对象 / 两个判别位都不成词 / 段词不认识)。
- *    🔴 读不出**绝不猜 `decided`**,也不敢说「零字节」——两个方向猜错的代价都是替人说一句他没说的话。
- */
 export const APPROVAL_UNSETTLED_CAUSES = Object.freeze([
     'engine_refused',
     'decide_failed',
@@ -47,17 +16,13 @@ export const APPROVAL_UNSETTLED_CAUSES = Object.freeze([
     'orchestration',
     'unreadable',
 ]);
-/** durable-park 腿的 `kind` 闭四词(判别序的第一把;不是这四个词才去看决断词)。 */
 const FS_OUTCOME_KINDS = Object.freeze(['decided', 'aborted', 'retracted', 'failed']);
-/** 非空串窄读(与本包其余读面同一条:空串 = 没这一格)。 */
 function str(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/** 有限数窄读(在场 = 真答了;非有限数一律当缺席,**不许**反推成 0)。 */
 function num(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
 }
-/** 一只可能来自宿主 / 注入面的记录:读属性本身就可能抛(getter 钩子),逐位各自兜住。 */
 function pick(o, key) {
     try {
         return o?.[key];
@@ -66,21 +31,9 @@ function pick(o, key) {
         return undefined;
     }
 }
-/** `{...(x !== undefined ? {k:x} : {})}` 的一处写法收口:缺席**不落键**(不折成空串 / 0 / false)。 */
 function opt(key, v) {
     return v === undefined ? {} : { [key]: v };
 }
-/**
- * 今天各腿的结局对象 → {@link ApprovalResolution}。**纯函数,永不抛,永不造**。
- *
- * 判别序(固定,不随键序变):
- *   ① `kind` 是 durable-park 腿的闭四词 ⇒ 按那一腿读;
- *   ② 否则决断词是串 ⇒ 按流内帧腿 / 盲卡腿读;
- *   ③ 都不成立 ⇒ `unsettled{cause:'unreadable'}`(🔴 不猜 `decided`,也不说「零字节」)。
- *
- * 🔴 **旁挂位在场压过决断词**(帧腿):撤卡 / 编辑被拒这两形是「一个字节都没发」,而它们今天与
- *    `decision` 同在一只对象上;先读决断词就会把一张没发出去的卡说成「批过了」。
- */
 export function approvalResolutionOf(outcome) {
     if (typeof outcome !== 'object' || outcome === null || Array.isArray(outcome)) {
         return { kind: 'unsettled', cause: 'unreadable' };
@@ -94,12 +47,10 @@ export function approvalResolutionOf(outcome) {
     }
     return { kind: 'unsettled', cause: 'unreadable' };
 }
-/** durable-park 腿(`surfaceFsApprovalAndDecide`)的十二形。 */
 function fsLegResolution(outcome, kind) {
     const gatedCallId = str(pick(outcome, 'gatedCallId'));
     const call = opt('gatedCallId', gatedCallId);
     if (kind === 'decided') {
-        // `denied` 在场即真(缺席 = 放行);`'allow_session'` 在这一腿上无位可读 ⇒ 不铸(见 decision 位顶注)。
         return {
             kind: 'decided',
             decision: pick(outcome, 'denied') === true ? 'deny' : 'allow',
@@ -109,15 +60,11 @@ function fsLegResolution(outcome, kind) {
     }
     if (kind === 'retracted')
         return { kind: 'not_sent', cause: 'retracted', ...call };
-    // 🔴 中断臂**发起**一次工具级拒绝(不观察结果,也不保证真出了站)⇒ 给不出 `not_sent` 的零字节承诺。
     if (kind === 'aborted')
         return { kind: 'unsettled', cause: 'interrupted', ...call };
-    // 剩下的是 `failed`:**停在链条哪一段**决定了「有没有发出去」——
-    // 取件 / 入参 / 卡口三段一个字节都没送出,只有 decide 那一段代表决断已经离开本包。
     const detail = opt('detail', str(pick(outcome, 'reason')));
     const stage = pick(outcome, 'stage');
     if (stage === 'fetch') {
-        // 取件腿的结构化判别位:「这一拍没有可决行」与「问不出来」结构可分(不靠文案子串猜)。
         const cause = pick(outcome, 'code') === 'no_pending' ? 'no_pending' : 'fetch_failed';
         return { kind: 'not_sent', cause, ...call, ...detail };
     }
@@ -128,13 +75,7 @@ function fsLegResolution(outcome, kind) {
     if (stage === 'decide') {
         const safetyCode = str(pick(outcome, 'safetyCode'));
         const errorCode = str(pick(outcome, 'errorCode'));
-        // 🔴 **「引擎答复过」必须有肯定证据**:wire 机器码在场,或引擎在拒体上铸的指路键在场。
-        //    没有证据的 decide 失败(调用方中止 ⇒ 出站前原错上抛 / 抛出物身上没有码 / 老引擎无码失败)
-        //    一律落 `'decide_failed'` —— 把它们说成「引擎拒了」是替引擎编了一句它没说过的话,
-        //    而消费端会照这句话去渲拒绝原因、去决定还要不要重呈。
         const engineAnswered = errorCode !== undefined || pick(outcome, 'currentPending') !== undefined;
-        // 优先序固定:安全停 > 瞬断耗尽 > 引擎语义拒绝 > 无证据的 decide 失败。前两者在实装里互斥
-        // (两个抛出物类型),写死优先序是为了「同场也只有一个答案」,不让键序决定结局。
         const cause = safetyCode !== undefined
             ? 'safety_stop'
             : pick(outcome, 'retryExhausted') === true
@@ -153,13 +94,9 @@ function fsLegResolution(outcome, kind) {
     }
     if (stage === 'orchestration')
         return { kind: 'unsettled', cause: 'orchestration', ...call, ...detail };
-    // 段词读不出 ⇒ 分不出停在哪:**不许**说「零字节」(那是 not_sent 的承诺),只说没落定。
     return { kind: 'unsettled', cause: 'unreadable', ...call, ...detail };
 }
-/** 流内帧腿 / 悬挂 ask(盲卡)腿(`surfaceToolApprovalFrameAndRespond`)的四形。 */
 function frameLegResolution(outcome) {
-    // 🔴 两个旁挂位先判(见 approvalResolutionOf 顶注):它们说的是「一个字节都没发」。
-    //    两位同在 ⇒ 撤卡胜 —— 与结局便签的 detail 优先序同一条,不是另铸一份。
     if (pick(outcome, 'retracted') === true)
         return { kind: 'not_sent', cause: 'retracted' };
     if (pick(outcome, 'editRefused') === true)
@@ -181,17 +118,14 @@ function frameLegResolution(outcome) {
         ...(typeof ack === 'object' && ack !== null ? { ack: ack } : {}),
     };
 }
-/** 这次决断**落定了吗**(唯一判据;`true` ⇒ 决断送到并拿到语义答复)。坏形入参 ⇒ `false`。 */
 export function isApprovalDecided(r) {
     return typeof r === 'object' && r !== null && r.kind === 'decided';
 }
-/** 「一个字节都没发」的因由;不是那一臂 ⇒ `undefined`(**不是**「发了」的证据,只是「不是这一臂」)。 */
 export function approvalNotSentCause(r) {
     if (typeof r !== 'object' || r === null || r.kind !== 'not_sent')
         return undefined;
     return r.cause;
 }
-/** 「没落定」的因由;不是那一臂 ⇒ `undefined`。 */
 export function approvalUnsettledCause(r) {
     if (typeof r !== 'object' || r === null || r.kind !== 'unsettled')
         return undefined;