@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/hitl/approvalsFeed.d.ts

@@ -1,57 +1,5 @@
-/**
- * ⇄ B7 ③(census **G20**,设计稿 §3 B7 末条):`approvals.list` 取件 → **SDK 原生推送
- *    `approvals.stream()`**,断流/无端点**回落轮询**的韧性臂保留。这是**行为改动**(不是搬迁),
- *    所以单独一个文件、单独一条测试、单独一个 commit。
- *
- * ## 先纠一个事实(census G20 的措辞会误导下一棒)
- *
- * G20 原话是「`hitlBridge.ts:197` 等三处今天靠 `approvals.list` 轮询」。**实测不是轮询** ——
- * 那三处(`hitlBridge.pendingForDecide` / `askGateWire.surfaceGateAndDecide` /
- * `toolApprovalWire.surfaceFsApprovalAndDecide`)都是**按需单次取件**:流上已经来了 park 信号,
- * 才去取那一行。真正缺的不是「把轮询换成推送」,而是**根本没有推送通道**:
- *   · 别的客户端(web/桌面/另一个 TUI)解掉了一条 pending —— 本端不知道;
- *   · 后台子代 lane 的 park 不在宿主自己的流上 —— 本端只有等下一次自己去 list 才看得见;
- *   · 端要渲一个「有 N 条待审批」的常驻指示 —— 今天只能自己起定时器。
- *
- * ⇒ 本文件提供的是那条**缺失的推送通道**(pending 快照的订阅面),而不是把上面三处改成读缓存。
- *
- * ## 🔴 它**不替换** D-1 的取件(这条是安全边界,别"顺手优化"掉)
- *
- * D-1 两元组必须取自**人看见的那一行**。让取件去读一个可能陈旧的快照 =
- * 用一个过期的 `boundInputHash` 去 decide ⇒ server fail-closed 409 ⇒ 一个合法审批被拒
- * (或者更坏:快照比服务端新旧关系不确定时,人看到的和绑定的不是同一件事)。
- * 所以那三处**继续走权威 `list()`**,本 feed 只做「有变化了」的通知面与快照面。
- * pure 门 B7③ 段对这条有断言(feed 跑着的时候,decide 路径仍然打 `list()`)。
- *
- * ## 两条腿与降级次序
- *
- * 1. **push**:`approvals.stream()`(SDK 内部已带断线重连 + heartbeat 静默重连)。
- *    收到**非 heartbeat** 事件 ⇒ 重取权威 `list()`。
- *    🔴 绝不解析 delta 载荷 —— SDK 自述 `ApprovalStreamEvent` 是 **FORWARD-DRAFT**
- *    (「payload fields are FORWARD-DRAFT pending service's shape confirmation」),
- *    照着未确认的形写解析 = 服务端一改就静默错。
- * 2. **poll**:stream 抛(404 无端点 / SDK 连 5 次开不起来 / 连 5 次空转)⇒ 落到定时 `list()`。
- *    并按 `streamRetryMs` 定期**再试一次 stream** —— 回落是降级不是永久放弃
- *    (服务端升级上线后不该还要重启客户端)。
- *    🆕 [C77]② 这条腿可由宿主按拍闸门:`opts.shouldPoll`(desktop 的「仅活跃 run 时轮询」)。
- *    跳拍 ≠ 停摆(mode 仍 'poll'、定时器照排、不计 polls、不算 F5 逃逸),契约见该选项的 doc。
- * 3. **idle**:stop() 之后 / signal abort 之后 / F5 判定 poll 腿真挂了。
- *
- * ## 诚实面([probe-must-prove-it-speaks])
- *
- * 「一条快照都没有」既可能是「真的没有 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';
-/** feed 消费的 wire 切片。`stream` 可选 —— 老 SDK / mock 没有它就直接走轮询腿。 */
 export interface ApprovalsFeedClientLike {
     approvals: {
         list(opts?: {
@@ -70,80 +18,22 @@ 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[];
-    /**
-     * 0.72.14:**流内 ask**(含悬挂的子代 ask)的窄读行,同样恒来自 `list()`。
-     * 🔴 **键缺席 = 引擎没报这一段**(老引擎),不是「没有」;引擎报了且为空 ⇒ `[]`。读法见 `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';
 } | {
@@ -155,80 +45,26 @@ export type ApprovalsFeedReading = {
     at: number;
 };
 export interface ApprovalsFeedStats {
-    /** 收到的**非 heartbeat** 推送事件数。 */
     pushEvents: number;
-    /** heartbeat 帧数(证明「连着但没事发生」,与「断了」区分开)。 */
     heartbeats: number;
-    /** 轮询腿真取件的次数。 */
     polls: number;
-    /** `list()` 抛错的次数(两条腿共用计数 —— 取件失败不该被静默)。 */
     listErrors: number;
-    /** stream 抛出(404 / 反复失败)导致降级的次数。 */
     streamFailures: number;
-    /** 真正发给订阅者的快照数(内容无变化时不发 ⇒ 这个数会小于 polls+pushEvents)。 */
     snapshots: number;
-    /** 0.72.14:对账节拍真取件的次数(与 `polls` 分开记 —— 它不属于回落轮询腿)。 */
     reconciles: number;
-    /** 0.73.4:「欠一次看」的重试取件次数(见 `ApprovalsFeedOptions.pushTakeRetryMs`)。 */
     pushTakeRetries: number;
-    /**
-     * CC-98:真发给订阅者的「不知道」张数。与 `listErrors` 刻意分开:后者数**失败次数**,本位数
-     * **发布次数**(同一段「不知道」只发一张)⇒ `unknowns <= listErrors` 恒成立,端的自检据此
-     * 区分「一直在失败」与「失败了但端被通知过几次」。
-     */
     unknowns: number;
 }
-/**
- * 0.72.14 **对账节拍**:悬挂的流内 ask 出现 / 结算时,较老的引擎不在 `approvals.stream` 上发任何事件 ⇒ push 腿连着也
- * 看不见它;而「仅活跃 run 时轮询」的 `shouldPoll` 恰好在宿主 turn 结束后关着。本旋钮给宿主一个**独立**的闸:
- * `shouldReconcile()` 为真(典型:会话有活跃后台代理 ∧ 没有活着的宿主 run)期间,无论当前是哪条腿都定时重取 `list()`。
- *   · 闸关 ⇒ 零额外取件;不传本旋钮 ⇒ 连定时器都不起,行为与此前一字不差。
- *   · 取件后快照没变 ⇒ 间隔翻倍直到 `maxIntervalMs`;变了 / 闸由关转开 ⇒ 回到 `intervalMs`。
- *   · 谓词抛错 / 返回非布尔 ⇒ 按「查」处理(与 `shouldPoll` 同一个 fail-safe 方向:少查一次 = 一只等人的 ask 迟迟不出现)。
- *   · 引擎开始在 stream 上为这一段发事件之后,push 腿自己就会重取,本节拍只剩兜底意义,宿主可以不再传。
- */
 export interface ApprovalsFeedReconcileOptions {
     shouldReconcile: () => boolean;
-    /** 基础间隔;缺省 5000ms。 */
     intervalMs?: number;
-    /** 退避上限;缺省 30_000ms。 */
     maxIntervalMs?: number;
 }
 export interface ApprovalsFeedOptions {
-    /** 回落轮询间隔;缺省 5000ms。 */
     pollIntervalMs?: number;
-    /** 降级后多久再试一次 stream;缺省 60_000ms。0 = 不再试(永久轮询)。 */
     streamRetryMs?: number;
-    /**
-     * [C77]② 轮询条件旋钮(协作板 desktop 请托:那一端的现行纪律是**仅活跃 run 时轮询**)。
-     * 每一拍**触发时**查询一次:`false` ⇒ 跳过本拍取件,但照常排下一拍。缺省(不传)= 恒 true,
-     * 行为与加旋钮之前一字不差。
-     *
-     * 🔴 语义与 `mode()==='idle'` 严格分开(别混同,端的自检读的就是这两个量):
-     *   · `shouldPoll()===false` = **消费方说现在不用查** —— 腿活着、定时器照排、`mode` 仍是
-     *     `'poll'`、`stats.polls` 不增(跳掉的那一拍没取件,计成 poll 就是谎报流量)、
-     *     **不计入** F5 的 `consecutivePollEscapes`(跳拍不是失败,连着跳一百拍也不该转 idle);
-     *   · `mode()==='idle'` = 这条腿**真挂了**(F5:回调体连续逃逸到上限)或已 `stop()`。
-     *
-     * 管辖边界(只管轮询腿,三处**不**受它约束,都是有理由的):
-     *   · **构造期那一次取件**不受管 —— 它是「首帧之前也要有内容」的一次性快照(否则端分不清
-     *     「空白」与「没有 pending」);要连这一次都不要,就晚一点再 `startApprovalsFeed`;
-     *   · **push 腿**(`approvals.stream` 事件驱动的重取)不受管 —— 那是服务端说「变了」,
-     *     省掉它 = 明知有变化还不去看,与本旋钮要省的「空转流量」不是一回事;
-     *   · **`refresh()`** 不受管 —— 那是端自己按下的显式动作。
-     */
     shouldPoll?: () => boolean;
-    /**
-     * 0.73.4:**欠一次看**的重试基础间隔(ms;缺省 1000;`<= 0` = 关,与 0.73.3 之前同)。
-     *
-     * push 腿收到事件 = 引擎说「变了」;那一次 `list()` 若失败(抛出,或回体读不懂),这个「变了」就没人去看:
-     * 其后的 heartbeat 不触发取件,没有别的事件的话,那张待批的卡一直不出现。⇒ 任何一次 push 侧取件
-     * (起手那次、事件触发的、`refresh()`)没看成,就记一笔欠账并按 base、2×base、4×base … 退避重试,
-     * 间隔封顶 30 s 与 base 的较大者,**不按次数放弃**(有人可能正在等这张卡);**比欠账更晚发起**的任何一次
-     * 取件看成(哪条腿都算)即销账、撤定时器、间隔回到 base;更早发起、迟到回来的成功不销账。只在 push 模式记账 —— 轮询模式下轮询腿自己会再来。
-     */
     pushTakeRetryMs?: number;
-    /** 0.72.14:对账节拍(见 {@link ApprovalsFeedReconcileOptions})。缺省不起。 */
     reconcile?: ApprovalsFeedReconcileOptions;
     signal?: AbortSignal;
 }
@@ -236,27 +72,8 @@ export interface ApprovalsFeedHandle {
     stop(): void;
     mode(): ApprovalsFeedMode;
     stats(): ApprovalsFeedStats;
-    /**
-     * 最近一次**真**快照(还没有过 ⇒ 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: (emission: ApprovalsFeedEmission) => void, opts?: ApprovalsFeedOptions): ApprovalsFeedHandle;