@sema-agent/client-core 0.75.0 → 0.76.0

package/dist/hitl/approvalResolution.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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

@@ -0,0 +1,199 @@
+/**
+ * 「包侧一个字节都没发」的因由闭集(**唯一真源**;端零手抄)。
+ *  · `'retracted'` —— 宿主撤掉了一张已经没有决断口的卡(两条腿都有这一形)。
+ *  · `'edit_refused'` —— 入参不可得的卡(悬挂 ask)上收到「编辑后批准」:丢掉改写再批准、或把改写
+ *    转发出去,两条都不是人按下的那个决定 ⇒ 整次不发。
+ *  · `'no_pending'` —— 取件那一拍队列里没有本 run 的可决行(结构化判别位,不是文案猜的)。
+ *  · `'fetch_failed'` —— 取件这一步**自己**失败了(与上一词结构可分:那是「没有行」,这是「问不出来」)。
+ *  · `'no_input'` —— 行上没有可呈现的工具入参,卡渲不出来。
+ *  · `'card_unavailable'` —— 卡口那一段失败(没装卡口 / 卡口自报失败)。
+ */
+export const APPROVAL_NOT_SENT_CAUSES = Object.freeze([
+    'retracted',
+    'edit_refused',
+    'no_pending',
+    'fetch_failed',
+    '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',
+    'transport_exhausted',
+    'safety_stop',
+    'respond_failed',
+    'interrupted',
+    '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];
+    }
+    catch {
+        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' };
+    }
+    const kind = pick(outcome, 'kind');
+    if (typeof kind === 'string' && FS_OUTCOME_KINDS.includes(kind)) {
+        return fsLegResolution(outcome, kind);
+    }
+    if (typeof pick(outcome, 'decision') === 'string') {
+        return frameLegResolution(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',
+            ...call,
+            ...opt('receipt', pick(outcome, 'receipt')),
+        };
+    }
+    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 };
+    }
+    if (stage === 'input')
+        return { kind: 'not_sent', cause: 'no_input', ...call, ...detail };
+    if (stage === 'card')
+        return { kind: 'not_sent', cause: 'card_unavailable', ...call, ...detail };
+    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
+                ? 'transport_exhausted'
+                : engineAnswered
+                    ? 'engine_refused'
+                    : 'decide_failed';
+        return {
+            kind: 'unsettled',
+            cause,
+            ...call,
+            ...opt('safetyCode', safetyCode),
+            ...opt('errorCode', errorCode),
+            ...detail,
+        };
+    }
+    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)
+        return { kind: 'not_sent', cause: 'edit_refused' };
+    if (pick(outcome, 'decision') === 'unresolved') {
+        const refusal = pick(outcome, 'respondRefusal');
+        return {
+            kind: 'unsettled',
+            cause: 'respond_failed',
+            ...opt('status', num(pick(refusal, 'status'))),
+            ...opt('errorCode', str(pick(refusal, 'errorCode'))),
+            ...opt('detail', str(pick(refusal, 'message'))),
+        };
+    }
+    const ack = pick(outcome, 'ack');
+    return {
+        kind: 'decided',
+        decision: pick(outcome, 'decision'),
+        ...(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;
+    return r.cause;
+}

package/dist/hitl/approvalsFeed.d.ts

@@ -42,6 +42,12 @@
  * 「一条快照都没有」既可能是「真的没有 pending」,也可能是「两条腿都挂了」。所以 feed 暴露
  * `stats()`(pushEvents / polls / listErrors / streamFailures / snapshots)与 `mode()`,
  * 端的自检可以断言「跑了 N 秒之后 mode 不是 idle 且 polls+pushEvents > 0」。
+ *
+ * 🔴 **CC-98 三态**:上面那两个量是**自检**面(端自己查健康),不是**渲染**面。渲染面要的是一句话 ——
+ * 「有 N 条」/「一条都没有」/「这次取不到,不知道有没有」。第三句此前在订阅口上根本不存在:
+ * `list()` 抛 / 回体读不懂 ⇒ 只 `listErrors++` 并静默返回 ⇒ 端手上停着上一张快照,它说 0 就一直
+ * 显示 0。⇒ 订阅口现在发**两臂**({@link ApprovalsFeedEmission}),另有拉面三态 `reading()`。
+ * 退避 / 重试 / 熔断语义**不变**:发了「不知道」照旧重试,取到就发真快照(含「内容与失败前一字不差」那一形)。
  */
 import type { PendingCheckpoint } from '@sema-agent/sdk';
 import { type LivePendingAskView } from './livePendingAsk.js';
@@ -64,6 +70,12 @@ export interface ApprovalsFeedClientLike {
 }
 export type ApprovalsFeedMode = 'push' | 'poll' | 'idle';
 export interface ApprovalsFeedSnapshot {
+    /**
+     * CC-98 判别位。订阅口发的**不只有**真快照 —— 取件没看成时发
+     * {@link ApprovalsFeedUnknownSnapshot}(`kind:'unknown'`)。
+     * 🔴 消费者先看这一位再读别的键:把「取不到」当成「一条都没有」是本包的头号病形。
+     */
+    kind: 'snapshot';
     /** 权威 pending 列表(**恒来自 `list()`**,不是 delta 拼出来的)。 */
     pending: PendingCheckpoint[];
     /**
@@ -71,11 +83,77 @@ export interface ApprovalsFeedSnapshot {
      * 🔴 **键缺席 = 引擎没报这一段**(老引擎),不是「没有」;引擎报了且为空 ⇒ `[]`。读法见 `livePendingAsk.ts`。
      */
     livePending?: LivePendingAskView[];
+    /**
+     * 🔴 CC-98(异源复审 R1 [high] 采修):这一段里**读不出来的行数**(>0 才在场)。
+     *
+     * 为什么必须上快照:读器对坏行是「逐条丢 + 计数」,丢掉的那几行**引擎照旧在报**。只把读得懂的行交出去
+     * 而不交这个数,消费端就会拿一份**自己不知道不完整**的列表去做两件不许做的事:
+     *   ① 报精确总数(「0 条在等你」而其实有一条读不懂的在等人);
+     *   ② **缺席对账**(「这一行不在列表里了 ⇒ 撤卡」,而它只是这一拍读不懂)。
+     * ⇒ 在场时:{@link countApprovalsAwaitingDecision} 的流内两格答 `null`(不知道确切数),
+     * {@link createSuspendedAskTracker} 的 `ingest` **不报 `gone`**(照报 `appeared` / `upgraded`)。
+     * 缺席 = 这一段**完整**(每一行都读出来了)—— 这时「一条都没有」才是一句可以说的话。
+     */
+    livePendingDropped?: number;
+    /**
+     * 🔴 CC-98(异源复审 R2 [medium] 采修):`pending` 段里**读不出来的行数**(>0 才在场)。
+     * 与 `livePendingDropped` 同一条纪律:在场 ⇒ 这一段**不完整** ⇒ {@link countApprovalsAwaitingDecision}
+     * 的 `durable` 格答 `null`(不知道确切数),缺席 = 每一行都读出来了。
+     */
+    pendingDropped?: number;
     /** 这次快照是被哪条腿触发的(对账节拍触发的取件记 `'poll'`:它就是一次定时 `list()`)。 */
     mode: 'push' | 'poll';
     /** 单调递增的修订号(端可用它判「我看到的是不是最新的」)。 */
     revision: number;
 }
+/**
+ * CC-98:一次取件**没看成**的两个成因(闭集,不设「其它」)。
+ *   · `list_threw` —— 取件本身抛出 / 返回 reject 的 promise(手上根本没有回体:无端点、传输层炸、上游 5xx …);
+ *   · `unreadable_payload` —— 有回体但读不懂(回体不是对象 / `livePending` 键在场却不是数组 / `pending` 不是数组或行畸形)。
+ * 两者刻意不合并:前者是「没拿到」,后者是「拿到了但不敢信」,宿主的提示文案与自检口径都不同。
+ */
+export type ApprovalsFeedUnknownWhy = 'list_threw' | 'unreadable_payload';
+/**
+ * 🔴 CC-98 **「这次取不到,不知道有没有」** —— 订阅口的第二臂,与真快照并列的一句话。
+ *
+ * 为什么必须有这一臂(而不是「不发」、更不是「发一张空的」):`list()` 失败 / 回体读不懂时,此前本 feed
+ * **一张都不发** ⇒ 端手上停着上一张快照 —— 它说 0 就一直显示 0(而真相是「不知道」),说 1 就一直显示 1。
+ * 「取不到」渲成「没有」是本包的头号病形,所以这一臂让**每个**消费者必须表态:渲破折号 / 渲「暂时看不到」/
+ * 显式选择继续显示上一张并标过期 —— 任选其一,但不许当成 0。
+ *
+ * 🔴 本臂**不带** `pending` / `livePending` / `revision`:那三样都是「视图」,而本臂说的正是「视图现在不可信」。
+ * 要上一张真快照(**过去**的事实)问 `snapshot()`;要「现在可不可信」问 `reading()`。
+ */
+export interface ApprovalsFeedUnknownSnapshot {
+    kind: 'unknown';
+    /** 成因(见 {@link ApprovalsFeedUnknownWhy})。 */
+    why: ApprovalsFeedUnknownWhy;
+    /**
+     * 这一段「不知道」的**起点**(epoch ms)。同一成因连着失败不重复发臂(与「内容没变不发快照」同一条纪律),
+     * 所以本位不随每次失败前移 —— 端可以拿它答「已经盲了多久」。
+     */
+    at: number;
+    /** 在哪条腿上取不到(与真快照的 `mode` 同义)。 */
+    mode: 'push' | 'poll';
+}
+/** 订阅口发的东西(两臂)。🔴 先看 `kind`,再读别的键。 */
+export type ApprovalsFeedEmission = ApprovalsFeedSnapshot | ApprovalsFeedUnknownSnapshot;
+/**
+ * CC-98 **拉面三态**(与本包能力位族的读数同一套词)。端在任何时刻问「我现在该渲什么」:
+ *   · `unobserved` —— 本 feed 还没有过任何结果(首次取件还没回来)。**不是**「没有 pending」。
+ *   · `present` —— 手上这张快照就是最近一次取件的结论(「一条都没有」只在这一态且列表为空时成立)。
+ *   · `unknown` —— 最近一次取件没看成(`why` / `at` 与最近发出的 {@link ApprovalsFeedUnknownSnapshot} 同源)。
+ */
+export type ApprovalsFeedReading = {
+    kind: 'unobserved';
+} | {
+    kind: 'present';
+    snapshot: ApprovalsFeedSnapshot;
+} | {
+    kind: 'unknown';
+    why: ApprovalsFeedUnknownWhy;
+    at: number;
+};
 export interface ApprovalsFeedStats {
     /** 收到的**非 heartbeat** 推送事件数。 */
     pushEvents: number;
@@ -93,6 +171,12 @@ export interface ApprovalsFeedStats {
     reconciles: number;
     /** 0.73.4:「欠一次看」的重试取件次数(见 `ApprovalsFeedOptions.pushTakeRetryMs`)。 */
     pushTakeRetries: number;
+    /**
+     * CC-98:真发给订阅者的「不知道」张数。与 `listErrors` 刻意分开:后者数**失败次数**,本位数
+     * **发布次数**(同一段「不知道」只发一张)⇒ `unknowns <= listErrors` 恒成立,端的自检据此
+     * 区分「一直在失败」与「失败了但端被通知过几次」。
+     */
+    unknowns: number;
 }
 /**
  * 0.72.14 **对账节拍**:悬挂的流内 ask 出现 / 结算时,较老的引擎不在 `approvals.stream` 上发任何事件 ⇒ push 腿连着也
@@ -152,13 +236,27 @@ export interface ApprovalsFeedHandle {
     stop(): void;
     mode(): ApprovalsFeedMode;
     stats(): ApprovalsFeedStats;
-    /** 最近一次快照(还没取过 ⇒ null)。 */
+    /**
+     * 最近一次**真**快照(还没有过 ⇒ null)。
+     * 🔴 CC-98:它是**过去**的事实 —— 取件正失败时它仍是上一张(内容不会被改写成空)。
+     * 「现在可不可信」问 {@link ApprovalsFeedHandle.reading}。
+     */
     snapshot(): ApprovalsFeedSnapshot | null;
+    /**
+     * CC-98 三态:**现在**该渲什么。
+     * 🔴 「一条都没有」只在 `present` 且列表为空时成立;`unobserved` / `unknown` 一律渲「不知道」
+     * (破折号 / 「暂时看不到」),绝不渲 0。
+     */
+    reading(): ApprovalsFeedReading;
     /** 立刻取一次权威 list 并(有变化时)发快照。端在「用户点了刷新」之类的场景用。 */
     refresh(): Promise<void>;
 }
 /**
  * 起一条 pending-approvals feed。**幂等性归调用方**:一个 client 起一条就够了,起两条 =
  * 两倍取件(不是错误,但没意义)。
+ *
+ * 🔴 CC-98 订阅口收**两臂**({@link ApprovalsFeedEmission}):真快照(`kind:'snapshot'`)与
+ * 「这次取不到」({@link ApprovalsFeedUnknownSnapshot},`kind:'unknown'`)。先判 `kind` 再读别的键 ——
+ * 把 unknown 臂当成一张空列表就是把「不知道」渲成「没有」。三态的拉面读口是 `reading()`。
  */
-export declare function startApprovalsFeed(client: ApprovalsFeedClientLike, onSnapshot: (snap: ApprovalsFeedSnapshot) => void, opts?: ApprovalsFeedOptions): ApprovalsFeedHandle;
+export declare function startApprovalsFeed(client: ApprovalsFeedClientLike, onSnapshot: (emission: ApprovalsFeedEmission) => void, opts?: ApprovalsFeedOptions): ApprovalsFeedHandle;