@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/runTerminal.d.ts

@@ -1,324 +1,51 @@
-/**
- * src/runTerminal.ts — 一次 run **怎么结束的**:两代 wire 字节 → 一个带标读数(0.60.0)。
- *
- * ── 上游形变(engine ≥7.64.0 / sdk 8.4.0;wire BREAKING)────────────────────────────────────
- * 7.63.0 及以前,终局要从并列的**八个可选平面键**里拼:`status` / `errorCode` / `errorMessage` /
- * `blockedReason` / `checkpointToken` / `checkpointId` / `checkpointGate` / `workspaceRestoreMode`。
- * 哪些组合合法只活在引擎那条 if/else 阶梯里,读的人只能靠**缺席**推断。7.64.0 起它是**形状**:
- * `TaskResult.terminal`(四臂 `completed | failed | blocked | paused`),八个平面键从型面整删。
- *
- * ── 本模块存在的理由:两代字节,一个读器 ─────────────────────────────────────────────────────
- * 🔴 **这不是「留一条旧引擎兼容读」**(那条本批刻意不留:peer 地板抬到 `>=8.4.0`,7.63.0 及以前的
- *    引擎不在本版支持窗内)。本模块的第二代臂认的是**同一台 ≥7.64.0 引擎**在两条路上真会送来的
- *    扁平字节,两条都有出处:
- *      ① **读盘面**(上游逐字点名):`GET /v1/runs/:id` 的 `result` 是存储 blob 的**逐字透传**
- *         (server 不补 `terminal`),durable 账本回放出来的 `done` 行同理 —— 一台跨 7.64.0 升级过的
- *         部署上,升级**之前**落盘的那些行读出来仍是平面形;
- *      ② **拒绝信封**:SSE 提交腿的 409(`conflict.session_active_run`)是 **server 自己的**拒绝帧、
- *         不是引擎结果,这次形变没动它 —— 它带扁平 `status:"failed"` + `errorCode`,不带 `terminal`;
- *      ③ **同步提交直接撞上暂停**(engine 7.64.0 真机黑盒 + server 回帖确认):`POST /v1/tasks`
- *         若当场停在一道审批门上,200 回体是 **server 自造的一只形** ——
- *         `{ taskId, sessionId, status: "suspended" | "needs_review" }`,**既没有退役的八个平面键、
- *         也没有 `terminal`**,它**不是** `TaskResult`(是独立于它的另一个体)。它既不是历史字节
- *         也不是拒绝信封,是**活流腿上的第三个来源**,而且它说的是一句正面事实(「这条 run park 了」)。
- *         🔴 因此这一形上**连门都没有**(`checkpointGate` / `terminal.paused.gate` 两处皆缺)——
- *         「这是复核还是交互作答」只能从那个 `status` 词读,见 {@link RunTerminalPausedRead.flatStatus}。
- *    ⇒ 判别位就是上游钉的那一个:**`"terminal" in result`**。在场 = 因由形,缺席 = 扁平形。
- * 🔴 **「缺席」不许折成 `completed` / `failed`**(真机黑盒点名的那条边界):`terminal` 缺席时,
- *    读器要么按扁平词给出**对应的那一臂**(`suspended` ⇒ paused,不是 completed 也不是 failed),
- *    要么在连词都没有时返回 `null`(见 {@link readRunTerminal} 的 `null` 语义)。**非终态**词
- *    (`running` / 未来的排队词)落 `unknown` 臂 —— 那是「这不是一个我认得的终局」,同样**不是**成功。
- *    `GET /v1/runs/:id` 对**暂停中**的 run 读不到 `result`,那一格连载体都没有,本读器答 `null`。
- * 🔴 **两代读数在出口上带标**({@link RunTerminalRead.plane}):不带标就等于对消费端说「这两种字节
- *    没有区别」,而它们在**能不能出现新键**这件事上区别很大(平面形是停产的写者留下的历史字节,
- *    永远不会长出新位)。带标也让门可以对「哪一条腿读到了哪一代」下断言。
- *
- * ── 判据纪律 ────────────────────────────────────────────────────────────────────────────────
- * 🔴 **不认识的终态词绝不折成成功**(本仓 [884]A1 / [909]B1 两次实锤事故的常驻结论):四臂之外的
- *    `terminal.kind`、平面形里四词之外的 `status`,一律落 {@link RunTerminalRead} 的 `unknown` 臂并
- *    **逐字带回那个词**,由消费点渲成「非成功终态」。整个读器只有一条路返回 `null`:**连终态词都
- *    没有**(mock 车道 / 不带 status 的旧合成帧)—— 那一格的既有语义(落成功臂)由消费点保留。
- * 🔴 **`code` 结构上只属于失败**:因由形下 `completed` / `blocked` / `paused` 上**写不出**码。
- *    `blocked` / `paused` / `unknown` 三臂仍声明了 `code?`,那一位**只可能**来自平面形盘上字节
- *    (旧写者把 `errorCode` 与 `status` 平铺,`review.pending` 就骑在 park 行上)—— 丢掉它等于在
- *    回放历史行时把盘上真有的事实抹掉。因由形上它恒缺席,判据用 `plane`。
- * 🔴 **`token` 席位永不上 wire**:paused 因由与 `failed.nestedPause` 都不带恢复凭据(上游在两条
- *    够得着的路径上摘它)。本读器同样一个字节都不碰它,也不给它留位。
- * 🔴 **不复制上游的投影**:本模块**不**提供「因由 → 五词 `status`」的兼容投影。同一个事实在这条
- *    wire 上有两个真源之后,消费端会分成「读因由的」和「读投影的」两派,而下一次形变时后者全部
- *    无声地错(sdk 顶注逐字同规)。要旧词的消费点自己按 `kind` 分支。
- */
 import type { CheckpointGate } from '@sema-agent/sdk';
-/**
- * 这条读数出自哪一代字节。
- *  · `cause` —— 现行的带标因由形(`result.terminal` 在场);
- *  · `flat`  —— 扁平形。**两个来源同形不可分**,所以刻意共用一个词:①升级前落盘、由读盘面逐字
- *    回放的历史行;②server 自己的 409 拒绝信封(它从来就是扁平的,这次形变没动它)。
- *    🔴 拿 `stats` 在场性去分这两源是**假判据**:本包的抢救腿(从 run row 合成的 done 帧)本来就
- *    可能不带 `stats`(见 `terminalToSdkResult` 的 ADAPTER-1/-2 收口注),那条判据会把它误判成拒绝
- *    信封。两源的**投影处置完全相同**,所以不分反而是诚实的。
- */
 export type RunTerminalPlane = 'cause' | 'flat';
-/** paused 因由的**结构视图**(`token` 席位不在这里,也不在 wire 上)。 */
 export interface RunTerminalPause {
-    /** **哪一道**暂停 —— 谁/什么必须来恢复它。开集读(词表属主是引擎)。 */
     gate?: CheckpointGate;
-    /** 这次暂停的**非密**稳定身份;pre-identity 的老 checkpoint 上缺席。 */
     checkpointId?: string;
-    /**
-     * 被暂停任务的远端工作区**怎么回来**:`snapshot`(VM 挂起成快照)/ `park_only`(环境自陈不可
-     * 挂起 —— 机器继续跑、继续花钱)。**缺席 = 进程内暂停**(没有远端工作区被捕获)。
-     * 🔴 型面**不收窄成那两个词**:词表属主是引擎,抄一份会把新词吞成缺席。
-     */
     restoreMode?: string;
 }
-/**
- * paused 臂的整只读数 —— {@link RunTerminalPause} 三座 + 判别位。
- *
- * 🔴 **抽名而不是写成交叉形**(`{…} & RunTerminalPause`):交叉形的左操作数是一个内联匿名形,
- *    typeshape 门的 B4 棘轮按设计把它算进「导出签名里的内联匿名形」——而具名 interface 正是那条
- *    棘轮点名的替代品。`extends` 同时保住了三座的**单一真源**(顶层 paused 臂与
- *    `failed.nestedPause` 读的是同一个形,两处各写一份必漂)。
- */
 export interface RunTerminalPausedRead extends RunTerminalPause {
     kind: 'paused';
     plane: RunTerminalPlane;
-    /** 见 {@link RunTerminalRead} 顶注:只可能来自扁平形盘上字节。 */
     code?: string;
-    /**
-     * 扁平形上那个退役的 status 词(`suspended` / `needs_review`)—— **因由形上恒缺席**。
-     *
-     * 🔴 **它不是「留一条兼容读」,是这一形上唯一存在的信号**(server 回帖确认):同步提交腿命中
-     *    park 时,server 自造的 200 体 `{taskId, sessionId, status}` **连门都不带** ⇒
-     *    {@link runTerminalGateKind} 在那一形上恒 `undefined`,「这是复核还是交互作答」除了这个词
-     *    再没有第二个来源。把它丢掉 = 那一形的 plan-review 卡与终帧措辞**全部**落到「交互作答」那一句上。
-     * 🔴 仍然**不做因由 → 五词 status 的反向投影**:本位只在扁平形上原样带回读到的那一个词,
-     *    因由形上不铸(读器一个词都不猜)。
-     */
     flatStatus?: string;
 }
-/**
- * 一次 run 的终局读数。`kind` 是判别位。
- *
- * ⚠️ 与 sdk `TerminalCause` 的差别只有两处,都是**防御读**逼出来的:①多一条 `unknown` 臂
- * (四臂之外的词不许落成功);②`blocked` / `paused` / `unknown` 上多一个 `code?`(平面形盘上字节
- * 才可能有,见模块顶注)。其余逐位同义。
- */
 export type RunTerminalRead = {
     kind: 'completed';
     plane: RunTerminalPlane;
 } | {
     kind: 'failed';
     plane: RunTerminalPlane;
-    /** 这次失败带的**机器码**(开集,点分命名空间;缺席 = 这次失败本来就没有码)。 */
     code?: string;
-    /** 人类可读的失败文本;没有就缺席。 */
     message?: string;
-    /**
-     * 这次失败**顶替的那次耐久暂停** —— 只在**嵌套硬边界**(verify / cascade)上出现:嵌套腿停在
-     * 一道耐久门上而编排器驱动不了 resume,于是在它的边界上如实报 failed,同时把那次 park 的因由
-     * 整只带在这里。引擎自己组装的失败上恒缺席;平面形上**结构性缺席**(旧写者没有这个位)。
-     */
     nestedPause?: RunTerminalPause;
 } | {
     kind: 'blocked';
     plane: RunTerminalPlane;
-    /** agent 为什么完不成(治理判决不是失败)。缺席 = 引擎没给因由,**不是**「没被挡」。 */
     reason?: string;
-    /** 见模块顶注:只可能来自平面形。 */
     code?: string;
 } | RunTerminalPausedRead | {
-    /** 四臂之外的终态词、**或一座读不出的因由** —— 两者都**绝不折成成功**。 */
     kind: 'unknown';
     plane: RunTerminalPlane;
-    /**
-     * 那个本读器不认识的词(因由形取 `terminal.kind`,扁平形取 `status`),逐字。
-     * 🔴 **缺席 = 那一座在场但整个读不出**(`terminal` 是 `null` / 数组 / 标量,或它的 `kind`
-     *    不是非空串)。这一格与「四臂之外的一个词」是两件事,所以刻意用**这一位的缺席**分开:
-     *    前者消费点只能说「一座读不出的终局」,后者能把那个词逐字报出来。
-     *    ⚠️ 它**不是**「没有终局」——那一格由 {@link readRunTerminal} 返 `null` 表达。
-     */
     word?: string;
     code?: string;
     message?: string;
 };
-/**
- * `done.result` / run row 的 `result` → 终局读数。**绝不抛**;读不出终态词 ⇒ `null`。
- *
- * 🔴 `null` **只有一个意思**:这份载体上连终态词都没有(mock 车道 / 不带 status 的旧合成帧)。
- *    它**不是**「成功」也**不是**「未知终态」—— 消费点对这一格的既有处置(落成功臂)由消费点自己
- *    保留,本读器不替它下这个断言。
- * 🔴 **「因由座在场但读不出」绝不返 `null`**(异源对抗复审 [medium] 采纳,真病):`terminal: null` /
- *    `{}` / `[]` / `{kind: 7}` 这几形若返 `null`,消费点会把它当成「连终态词都没有」而落**成功臂**
- *    —— 一条明确 park 着的 run 被投影成空成功,正是 [884]A1 / [909]B1 两次事故的形状。⇒ 这几形
- *    一律落 `unknown` 臂(`word` 缺席 = 那个词本身读不出),消费点照旧渲「非成功终局」。
- *    ⚠️ 混合载体(既有坏 `terminal` 又有平面 `status`)同样落这里:判别位是**因由座在场性**,
- *    因由在场就不再回头读平面键(留一条回落 = 同一事实两个真源,而坏的那一份才是当代写者写的)。
- * 🔴 判别位是 **`"terminal" in result`**(上游钉的那一个),不是 `status` 的在场性:拒绝信封与
- *    平面盘上字节**都**带 `status`,拿它当第一步判别位方向是脆的(sdk 顶注逐字点名)。
- */
 export declare function readRunTerminal(result: unknown): RunTerminalRead | null;
-/**
- * 「这次暂停要的是**一次复核**」的门种 —— **呈现措辞**这条轴上的单一词表(不是路由表)。
- *
- * 🔴 与 `activeRunSelfHeal.PLAN_REVIEW_GATE_KINDS`(`plan_review` / `dry_run_review`)**刻意不同集**,
- *    差别有出处:那张表答的是「**重开臂能不能驱动它**」(两个成员共用同一个 resume 入口
- *    `/v1/assistant/tasks/{taskId}/plan_review`),而本表答的是「**跟用户怎么说**」。门种
- *    `needs_review`(design/76 dry-run/shadow 的 POST-prediction 复核)没有那个 resume 入口,所以
- *    它不在路由表里 —— 但它同样是**一次复核**而不是「一次交互作答」,措辞轴上必须在。
- * 🔴 两张表的包含关系由常驻门钉死(本表 ⊇ 路由表):路由表加员而本表没跟 ⇒ 新门种的终帧会被说成
- *    「在等一次交互作答」,那正是 [884]A1 那句文案要防的错话。
- * 🔴 **开集读**:表外门种一律落「交互作答」那一句 —— 它是两句里更宽的那一句(指的出路对两族都有效)。
- */
 export declare const REVIEW_PARK_GATE_KINDS: readonly string[];
-/**
- * 这次暂停停在**哪一种门**上(开集读;缺席 = 门没报 kind)。
- * 消费点要分「plan 复核 park」与「审批/提问 park」时读它,**不要**再去找退役的 `status` 五词。
- */
 export declare function runTerminalGateKind(read: RunTerminalRead | null): string | undefined;
-/** 这次暂停扣着**哪个工具**(开集读;tool-less park 上缺席)。 */
 export declare function runTerminalGateToolName(read: RunTerminalRead | null): string | undefined;
-/**
- * 这次终局的**机器码**(开集)。`failed` 臂是它的结构归属;`blocked` / `paused` / `unknown` 上
- * 只可能来自扁平形盘上字节(见模块顶注)。`completed` 上恒 `undefined`。
- */
 export declare function runTerminalCode(read: RunTerminalRead | null): string | undefined;
-/**
- * 这次暂停在等**一次复核**(而不是一次交互作答)吗。**两个来源,缺一不可**:
- *   · **因由形** —— 门种 ∈ {@link REVIEW_PARK_GATE_KINDS};
- *   · **扁平形** —— {@link RunTerminalPausedRead.flatStatus} 是 `needs_review`。
- *     🔴 这一条不是冗余:server 自造的**同步 park 200 体**上连门都没有(见 `flatStatus` 顶注),
- *     只读门种会让那一形**全部**落到「交互作答」那一句上 —— plan-review 卡不弹、终帧措辞说错话。
- * 非 paused 的读数、以及两个来源都答不出的 paused,一律 `false`(更宽的那一句兜底)。
- */
 export declare function isReviewPark(read: RunTerminalRead | null): boolean;
-/**
- * ══════════════════════════════════════════════════════════════════════════════════════════════
- * 0.68.0 🔴 BREAKING —— 终态词**两表分源**(L-247;core [7067] @cli 行顺答)
- * ══════════════════════════════════════════════════════════════════════════════════════════════
- * 修前本模块只有一张 `TERMINAL_STATUSES = ['completed','failed','killed','blocked']`,把**两个不同
- * 属主**的词表合成了一张:
- *   · `completed` / `failed` / `blocked` 属 **core 的终局因由闭集**(`TerminalCause["kind"]`,
- *     `terminal-cause.ts`;core 那边第四员是 `paused`);
- *   · `killed` 属 **server 的 run 行状态面**(core 的因由集里**根本没有这个词** —— core [7067] 逐字:
- *     「`killed` 不是 core 词 —— 壳手抄四词里的 `killed` 来自 server run status 面」)。
- * 合成一张的后果是两边加员时都读不出该改哪儿:core 加第五个因由(闭集加员会在 wire 清单的
- * `closedSetMembers` 上具名)与 server 加一个行状态词,在一张表上长得一模一样,于是消费方要么
- * 把新词折进已知词(不安全侧,B-079① 同形),要么两边都漏。
- *
- * ⇒ 两张表**按属主分开**,各自带自己的对账物:
- *   · {@link TERMINAL_CAUSE_KINDS} —— core 闭集的镜像,门对**实装 devDep core** 双向对账;
- *   · {@link RUN_TERMINAL_STATUSES} —— server run 行状态面的终态词,门对 sdk 真字节钉 + 反向钉
- *     「`killed` 不在 core 因由集里」。
- *
- * 🔴 **为什么是镜像而不是 `export … from '@sema-agent/core'`**(与 `engineNoticeCodes.ts` /
- *    `autoModeUnavailable.ts` / `toolResult.ts` 三处逐字同一条理由,再加两条本表独有的):
- *    ① `@sema-agent/core` 既不是本包的 peer 也不是 runtime dep —— 本包的 `.d.ts` 一旦引用它,
- *       装了本包却没装 core 的下游当场编译不过;`portability` 门的 `EXPECTED_PACKAGES_INDEX` 是
- *       **等值门**(闭包外部包恒等于 `{diff, @sema-agent/sdk}`)且 ③ 段拿 esbuild
- *       `--platform=browser` 真打一次包,一条值级边会把整台引擎焊进 web/desktop 的产物;
- *    ② core **没有导出**任何名为「终局因由闭集」的元组:它只导出 `TERMINAL_CAUSE_IS_REPLAYABLE`
- *       (一张 `Record<kind, boolean>` 的处置表)与谓词 `isTerminalCauseKind`,而且这两件**都不在
- *       core 的 barrel 上**(`dist/index.d.ts` 只 re-export 了**类型** `TerminalCause`)⇒
- *       「直接 re-export 那个闭集」在今天的上游字节上不存在可 re-export 的符号。
- *    ⇒ 镜像 + 机器对账(本仓对「不自抄」的既定机制):这张表是一份**抄件**不是意见,
- *       `scripts/run-terminal-word-source-test.mjs` 拿 core 那张处置表的**键集**逐词双向钉,
- *       core 一动这里就先红。
- */
-/**
- * **core 终局因由**的 kind 闭集(core `TerminalCause["kind"]` 逐词镜像;顺序同源 =
- * `dist/core/terminal-cause.js` 的 `TERMINAL_CAUSE_IS_REPLAYABLE` 键序)。
- *
- * 四员各答「这条 run 为什么结束」:
- *  · `completed` —— 跑完了(用户干净 halt 也算,见 `TaskResult.haltedByUser`);
- *  · `failed` —— 限额 / provider 失败 / abort / 产出不合法……;
- *  · `blocked` —— **agent 自报**走不下去(`report_blocked`)。上游逐字:它是 TERMINAL 的,
- *    「the leg is over and it waits for nobody」;
- *  · `paused` —— 一次耐久暂停提交了 checkpoint,**run 可以被恢复**。🔴 它在因由面上是一个
- *    合法的 kind,但它**不是**「run 结束了」——所以它**不在** {@link RUN_TERMINAL_STATUSES} 里。
- *    这正是两张表必须分源的最硬那一格:同一个词在两张面上答的是两个问题。
- *
- * 🔴 **集外词的读法**:core 加第五个因由词时,wire 清单的 `closedSetMembers` 必须列、发车帖必须
- *    具名(core [7067] 逐字规矩)。消费方按闭集读 —— **集外词整键缺席,绝不折成已知词**。
- * 🔴 形制:`Object.freeze` 的**字面元组**(`as const`),不是 `readonly string[]` —— 后者在类型面
- *    交不出成员字面量,端就只能自己再抄一遍四个词(L-247 的病根)。冻结是为了让公面消费者
- *    `.push()` 改不动判定源(同 `RESUME_RETRY_LATER_CODES` 的已定谳病形)。
- */
 export declare const TERMINAL_CAUSE_KINDS: readonly ["completed", "failed", "blocked", "paused"];
-/** {@link TERMINAL_CAUSE_KINDS} 的成员型(端的型面改**派生**,不再手抄词)。 */
 export type TerminalCauseKind = (typeof TERMINAL_CAUSE_KINDS)[number];
-/**
- * 一个词是不是 core 的终局**因由** kind({@link TERMINAL_CAUSE_KINDS} 的成员)。
- *
- * 🔴 **它不答「这条 run 结束了没有」** —— `paused` 是合法成员而 run 还能被恢复。要那一问请读
- *    {@link isTerminalStatus}(server 行状态面)或 {@link readRunTerminal} 的因由臂。
- * 🔴 非串 / 空串 / 集外词 ⇒ `false` = 「这不是本端认得的因由词」,**不是**「成功」。
- */
 export declare function isTerminalCauseKind(kind: unknown): kind is TerminalCauseKind;
-/**
- * **server run 行状态面**的「非成功终局」词(闭集;0.65.0 新铸,L-215② / core [6908];
- * 0.68.0 随 L-247 更名 `TERMINAL_NOT_SUCCESS_STATUSES` → 本名,理由见本段顶注的分源说明)——
- * 「这条 run **不会再自己动了**,而且它没有成功」。
- *
- * 🔴 三员各有出处,且 **`blocked` 与 `suspended`/`needs_review` 的分界是本表存在的全部理由**
- *    (core [6908] 定谳):
- *      · `failed` —— 引擎自报失败;
- *      · `killed` —— 外力终止。🔴 **这一员是本表与 {@link TERMINAL_CAUSE_KINDS} 的分水岭**:
- *        core 的因由闭集里没有它,它是 server run 行状态面自己的词(sdk `FleetTaskStatus` /
- *        `SessionNotifyStatus` 上都在,`RunStatus` 上今天还没有 —— 见 §33 的登记);
- *      · `blocked` —— **agent 自报的终态**:它自己判定这条 run 走不下去了(core `terminal.blocked`
- *        的 `reason` 是它的说明)。🔴 它**不是「等人」** —— 这正是修前被漏掉的那一格;
- *      · 🔴 **`suspended` / `needs_review` 刻意不在表里**:那两个词是**等一次人的决定**,run 还活着、
- *        决定给了就继续跑。把它们读成「非成功终局」会把一条**正等着你**的 run 在面板上判死,
- *        而用户从此不知道有一张卡在等他 —— 与本表要修的方向相反的同一类错。
- *
- * 🔴 形制:`Object.freeze` 的**字面元组**,不是 `ReadonlySet`(同 `RESUME_RETRY_LATER_CODES` 的
- *    已定谳病形:`ReadonlySet` 只在类型面只读,而判定查的就是公面上这同一个实例)。
- */
 export declare const RUN_TERMINAL_NOT_SUCCESS_STATUSES: readonly ["failed", "killed", "blocked"];
-/** {@link RUN_TERMINAL_NOT_SUCCESS_STATUSES} 的成员型(端的型面改派生,不再手抄三词)。 */
 export type RunTerminalNotSuccessStatus = (typeof RUN_TERMINAL_NOT_SUCCESS_STATUSES)[number];
-/**
- * 一个状态词是不是**非成功终局**({@link RUN_TERMINAL_NOT_SUCCESS_STATUSES} 的成员)。
- *
- * **单铸谓词**(L-215②):本包的通知链(面板 settle 的 `isError` 位)与三端各自的后台白名单
- * 读的必须是**同一个判据** —— 修前包里是一处内联的 `status === 'failed' || status === 'killed'`,
- * 壳里另有一份白名单,两处各写各的,于是 core 加 `blocked` 那天两边一起漏,而漏的后果是
- * **面板把一条自报失败的 run 渲成成功**。
- *
- * 🔴 **开集外的词答 `false`,而 `false` 不等于「成功」**:它只说「这个词不在本端认得的非成功终局
- *    表里」。消费点要判「成功」必须去读成功那一侧的正向证据({@link readRunTerminal} 的
- *    `completed` 臂),不能拿本谓词的取反当成功判据 —— 那正是「不认识的终态词折成成功」那条
- *    已定谳的事故形。
- * 🔴 非串 / 空串 ⇒ `false`(同上:是「答不出」,不是「成功」)。
- */
 export declare function isTerminalNotSuccess(status: unknown): status is RunTerminalNotSuccessStatus;
-/**
- * **server run 行状态面**的终局状态词(闭集;0.65.0 新铸,0.68.0 随 L-247 更名 `TERMINAL_STATUSES`
- * → 本名)—— 成功那一员加上 {@link RUN_TERMINAL_NOT_SUCCESS_STATUSES} 的三员。答的是「这条 run
- * 还会不会自己动」,与上一张表答的「它成没成功」是**两个问题**,所以两张表分开、后者由前者派生
- * (加员只有一处要改)。
- *
- * 🔴 同样**不含** `suspended` / `needs_review`:那两个词是「等一次人的决定」——run 没有结束。
- * 🔴 也**不含** core 因由面的 `paused`:那是另一张表的词,而且它在语义上恰好与本表相反
- *    ({@link TERMINAL_CAUSE_KINDS} 顶注)。
- */
 export declare const RUN_TERMINAL_STATUSES: readonly ["completed", "failed", "killed", "blocked"];
-/** {@link RUN_TERMINAL_STATUSES} 的成员型(端的型面改派生,不再手抄四词 —— L-247 的修形)。 */
 export type RunTerminalStatus = (typeof RUN_TERMINAL_STATUSES)[number];
-/**
- * 一个状态词是不是**终局**({@link RUN_TERMINAL_STATUSES} 的成员)。
- *
- * 用在「这条通知/这条行是不是可以收摊了」这一问上(通知去重的 seed 扫描、后台行 settle 门)。
- * 🔴 表外词 ⇒ `false` = 「本端认不出这是个终局」,**不是**「它还在跑」;要判「在跑」请读正向证据。
- */
 export declare function isTerminalStatus(status: unknown): status is RunTerminalStatus;
-/**
- * 0.72.12 CC-50:**通知**(`task_notification.status`)自己的终态词表 —— 引擎 `TaskNotificationStatus` 五词里的四个终态
- * (`completed` / `failed` / `killed` / `cancelled`;第五词 `event` 是唯一非终态 = 仍在跑的 Monitor 批)逐字镜像。
- * 🔴 它与 run 级 {@link RUN_TERMINAL_STATUSES} 是**两张表**(那张有 `blocked`、没有 `cancelled`):通知说「已取消」是明确终态,
- *    借 run 级表会把它读成「认不出」(异源对抗复审抓出)。住在词表属主文件里,src 别处零内联(终态词汇门 D3)。
- */
 export declare const TASK_NOTIFICATION_TERMINAL_STATUSES: readonly string[];
-/** 这个通知 status 是不是**明确终态**;表外词(`event` / `unknown` / 未来词 / 缺席)⇒ false = 「本端不能断言它结束了」。 */
 export declare function isTaskNotificationTerminalStatus(status: string | undefined): boolean;

package/dist/runTerminal.js

@@ -1,14 +1,11 @@
-/** 非空串窄化(空串按缺席归一 —— 一个空的因由渲不出任何有用的话)。 */
 function str(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/** wire 上的门对象 → 结构视图;不成形 ⇒ 缺席(绝不铸一个空门)。 */
 function gateOf(v) {
     if (typeof v !== 'object' || v === null || Array.isArray(v))
         return undefined;
     return v;
 }
-/** paused 三座的共用窄读(顶层 paused 臂与 `failed.nestedPause` 同一把 —— 两处各写一份必漂)。 */
 function pauseOf(v) {
     if (typeof v !== 'object' || v === null || Array.isArray(v))
         return undefined;
@@ -22,35 +19,13 @@ function pauseOf(v) {
         ...(restoreMode !== undefined ? { restoreMode } : {}),
     };
 }
-/**
- * 扁平形里映射到 **paused 因由臂**的两个退役 status 词。
- * 🔴 表外词一律走 `unknown` 臂 —— 含历史终态 `timeout`,也含**非终态**词 `running`
- *    (那是「这不是一个我认得的终局」,**不是**成功;真机黑盒点名的那条边界)。
- */
 const FLAT_PAUSED_STATUSES = ['suspended', 'needs_review'];
-/**
- * `done.result` / run row 的 `result` → 终局读数。**绝不抛**;读不出终态词 ⇒ `null`。
- *
- * 🔴 `null` **只有一个意思**:这份载体上连终态词都没有(mock 车道 / 不带 status 的旧合成帧)。
- *    它**不是**「成功」也**不是**「未知终态」—— 消费点对这一格的既有处置(落成功臂)由消费点自己
- *    保留,本读器不替它下这个断言。
- * 🔴 **「因由座在场但读不出」绝不返 `null`**(异源对抗复审 [medium] 采纳,真病):`terminal: null` /
- *    `{}` / `[]` / `{kind: 7}` 这几形若返 `null`,消费点会把它当成「连终态词都没有」而落**成功臂**
- *    —— 一条明确 park 着的 run 被投影成空成功,正是 [884]A1 / [909]B1 两次事故的形状。⇒ 这几形
- *    一律落 `unknown` 臂(`word` 缺席 = 那个词本身读不出),消费点照旧渲「非成功终局」。
- *    ⚠️ 混合载体(既有坏 `terminal` 又有平面 `status`)同样落这里:判别位是**因由座在场性**,
- *    因由在场就不再回头读平面键(留一条回落 = 同一事实两个真源,而坏的那一份才是当代写者写的)。
- * 🔴 判别位是 **`"terminal" in result`**(上游钉的那一个),不是 `status` 的在场性:拒绝信封与
- *    平面盘上字节**都**带 `status`,拿它当第一步判别位方向是脆的(sdk 顶注逐字点名)。
- */
 export function readRunTerminal(result) {
     if (typeof result !== 'object' || result === null || Array.isArray(result))
         return null;
     const r = result;
     if ('terminal' in r) {
         const t = r.terminal;
-        // 🔴 因由座在场但整个读不出 ⇒ `unknown` 臂(**不是** `null`;见顶注:返 `null` 会让消费点把
-        //    一条明确 park 着的 run 落进成功臂)。`word` 缺席 = 连那个词都读不出来。
         if (typeof t !== 'object' || t === null || Array.isArray(t))
             return { kind: 'unknown', plane: 'cause' };
         const c = t;
@@ -82,7 +57,6 @@ export function readRunTerminal(result) {
                 return { kind: 'unknown', plane: 'cause', word: kind };
         }
     }
-    // ── 扁平形(读盘回放 / 409 拒绝信封;见模块顶注)────────────────────────────────────────────
     const status = str(r.status);
     if (status === undefined)
         return null;
@@ -114,8 +88,6 @@ export function readRunTerminal(result) {
         return {
             kind: 'paused',
             plane: 'flat',
-            // 🔴 见 `flatStatus` 顶注:server 自造的同步 park 体上**连门都没有**,这个词是那一形上
-            //    「复核 / 交互作答」的唯一信号。
             flatStatus: status,
             ...(code !== undefined ? { code } : {}),
             ...(gate !== undefined ? { gate } : {}),
@@ -131,203 +103,54 @@ export function readRunTerminal(result) {
         ...(message !== undefined ? { message } : {}),
     };
 }
-/**
- * 「这次暂停要的是**一次复核**」的门种 —— **呈现措辞**这条轴上的单一词表(不是路由表)。
- *
- * 🔴 与 `activeRunSelfHeal.PLAN_REVIEW_GATE_KINDS`(`plan_review` / `dry_run_review`)**刻意不同集**,
- *    差别有出处:那张表答的是「**重开臂能不能驱动它**」(两个成员共用同一个 resume 入口
- *    `/v1/assistant/tasks/{taskId}/plan_review`),而本表答的是「**跟用户怎么说**」。门种
- *    `needs_review`(design/76 dry-run/shadow 的 POST-prediction 复核)没有那个 resume 入口,所以
- *    它不在路由表里 —— 但它同样是**一次复核**而不是「一次交互作答」,措辞轴上必须在。
- * 🔴 两张表的包含关系由常驻门钉死(本表 ⊇ 路由表):路由表加员而本表没跟 ⇒ 新门种的终帧会被说成
- *    「在等一次交互作答」,那正是 [884]A1 那句文案要防的错话。
- * 🔴 **开集读**:表外门种一律落「交互作答」那一句 —— 它是两句里更宽的那一句(指的出路对两族都有效)。
- */
 export const REVIEW_PARK_GATE_KINDS = Object.freeze([
     'plan_review',
     'dry_run_review',
     'needs_review',
 ]);
-/**
- * 这次暂停停在**哪一种门**上(开集读;缺席 = 门没报 kind)。
- * 消费点要分「plan 复核 park」与「审批/提问 park」时读它,**不要**再去找退役的 `status` 五词。
- */
 export function runTerminalGateKind(read) {
     return read !== null && read.kind === 'paused' ? str(read.gate?.kind) : undefined;
 }
-/** 这次暂停扣着**哪个工具**(开集读;tool-less park 上缺席)。 */
 export function runTerminalGateToolName(read) {
     return read !== null && read.kind === 'paused' ? str(read.gate?.toolName) : undefined;
 }
-/**
- * 这次终局的**机器码**(开集)。`failed` 臂是它的结构归属;`blocked` / `paused` / `unknown` 上
- * 只可能来自扁平形盘上字节(见模块顶注)。`completed` 上恒 `undefined`。
- */
 export function runTerminalCode(read) {
     if (read === null || read.kind === 'completed')
         return undefined;
     return read.code;
 }
-/**
- * 扁平形上「这是一次复核」的那个退役 status 词。**只有一个**,刻意不写成表:
- * `suspended` 与它是 `FLAT_PAUSED_STATUSES` 的两个成员,而两者的分法就是这一条。
- */
 const FLAT_REVIEW_STATUS = 'needs_review';
-/**
- * 这次暂停在等**一次复核**(而不是一次交互作答)吗。**两个来源,缺一不可**:
- *   · **因由形** —— 门种 ∈ {@link REVIEW_PARK_GATE_KINDS};
- *   · **扁平形** —— {@link RunTerminalPausedRead.flatStatus} 是 `needs_review`。
- *     🔴 这一条不是冗余:server 自造的**同步 park 200 体**上连门都没有(见 `flatStatus` 顶注),
- *     只读门种会让那一形**全部**落到「交互作答」那一句上 —— plan-review 卡不弹、终帧措辞说错话。
- * 非 paused 的读数、以及两个来源都答不出的 paused,一律 `false`(更宽的那一句兜底)。
- */
 export function isReviewPark(read) {
     const kind = runTerminalGateKind(read);
     if (kind !== undefined && REVIEW_PARK_GATE_KINDS.includes(kind))
         return true;
     return read !== null && read.kind === 'paused' && read.flatStatus === FLAT_REVIEW_STATUS;
 }
-/**
- * ══════════════════════════════════════════════════════════════════════════════════════════════
- * 0.68.0 🔴 BREAKING —— 终态词**两表分源**(L-247;core [7067] @cli 行顺答)
- * ══════════════════════════════════════════════════════════════════════════════════════════════
- * 修前本模块只有一张 `TERMINAL_STATUSES = ['completed','failed','killed','blocked']`,把**两个不同
- * 属主**的词表合成了一张:
- *   · `completed` / `failed` / `blocked` 属 **core 的终局因由闭集**(`TerminalCause["kind"]`,
- *     `terminal-cause.ts`;core 那边第四员是 `paused`);
- *   · `killed` 属 **server 的 run 行状态面**(core 的因由集里**根本没有这个词** —— core [7067] 逐字:
- *     「`killed` 不是 core 词 —— 壳手抄四词里的 `killed` 来自 server run status 面」)。
- * 合成一张的后果是两边加员时都读不出该改哪儿:core 加第五个因由(闭集加员会在 wire 清单的
- * `closedSetMembers` 上具名)与 server 加一个行状态词,在一张表上长得一模一样,于是消费方要么
- * 把新词折进已知词(不安全侧,B-079① 同形),要么两边都漏。
- *
- * ⇒ 两张表**按属主分开**,各自带自己的对账物:
- *   · {@link TERMINAL_CAUSE_KINDS} —— core 闭集的镜像,门对**实装 devDep core** 双向对账;
- *   · {@link RUN_TERMINAL_STATUSES} —— server run 行状态面的终态词,门对 sdk 真字节钉 + 反向钉
- *     「`killed` 不在 core 因由集里」。
- *
- * 🔴 **为什么是镜像而不是 `export … from '@sema-agent/core'`**(与 `engineNoticeCodes.ts` /
- *    `autoModeUnavailable.ts` / `toolResult.ts` 三处逐字同一条理由,再加两条本表独有的):
- *    ① `@sema-agent/core` 既不是本包的 peer 也不是 runtime dep —— 本包的 `.d.ts` 一旦引用它,
- *       装了本包却没装 core 的下游当场编译不过;`portability` 门的 `EXPECTED_PACKAGES_INDEX` 是
- *       **等值门**(闭包外部包恒等于 `{diff, @sema-agent/sdk}`)且 ③ 段拿 esbuild
- *       `--platform=browser` 真打一次包,一条值级边会把整台引擎焊进 web/desktop 的产物;
- *    ② core **没有导出**任何名为「终局因由闭集」的元组:它只导出 `TERMINAL_CAUSE_IS_REPLAYABLE`
- *       (一张 `Record<kind, boolean>` 的处置表)与谓词 `isTerminalCauseKind`,而且这两件**都不在
- *       core 的 barrel 上**(`dist/index.d.ts` 只 re-export 了**类型** `TerminalCause`)⇒
- *       「直接 re-export 那个闭集」在今天的上游字节上不存在可 re-export 的符号。
- *    ⇒ 镜像 + 机器对账(本仓对「不自抄」的既定机制):这张表是一份**抄件**不是意见,
- *       `scripts/run-terminal-word-source-test.mjs` 拿 core 那张处置表的**键集**逐词双向钉,
- *       core 一动这里就先红。
- */
-/**
- * **core 终局因由**的 kind 闭集(core `TerminalCause["kind"]` 逐词镜像;顺序同源 =
- * `dist/core/terminal-cause.js` 的 `TERMINAL_CAUSE_IS_REPLAYABLE` 键序)。
- *
- * 四员各答「这条 run 为什么结束」:
- *  · `completed` —— 跑完了(用户干净 halt 也算,见 `TaskResult.haltedByUser`);
- *  · `failed` —— 限额 / provider 失败 / abort / 产出不合法……;
- *  · `blocked` —— **agent 自报**走不下去(`report_blocked`)。上游逐字:它是 TERMINAL 的,
- *    「the leg is over and it waits for nobody」;
- *  · `paused` —— 一次耐久暂停提交了 checkpoint,**run 可以被恢复**。🔴 它在因由面上是一个
- *    合法的 kind,但它**不是**「run 结束了」——所以它**不在** {@link RUN_TERMINAL_STATUSES} 里。
- *    这正是两张表必须分源的最硬那一格:同一个词在两张面上答的是两个问题。
- *
- * 🔴 **集外词的读法**:core 加第五个因由词时,wire 清单的 `closedSetMembers` 必须列、发车帖必须
- *    具名(core [7067] 逐字规矩)。消费方按闭集读 —— **集外词整键缺席,绝不折成已知词**。
- * 🔴 形制:`Object.freeze` 的**字面元组**(`as const`),不是 `readonly string[]` —— 后者在类型面
- *    交不出成员字面量,端就只能自己再抄一遍四个词(L-247 的病根)。冻结是为了让公面消费者
- *    `.push()` 改不动判定源(同 `RESUME_RETRY_LATER_CODES` 的已定谳病形)。
- */
 export const TERMINAL_CAUSE_KINDS = Object.freeze([
     'completed',
     'failed',
     'blocked',
     'paused',
 ]);
-/**
- * 一个词是不是 core 的终局**因由** kind({@link TERMINAL_CAUSE_KINDS} 的成员)。
- *
- * 🔴 **它不答「这条 run 结束了没有」** —— `paused` 是合法成员而 run 还能被恢复。要那一问请读
- *    {@link isTerminalStatus}(server 行状态面)或 {@link readRunTerminal} 的因由臂。
- * 🔴 非串 / 空串 / 集外词 ⇒ `false` = 「这不是本端认得的因由词」,**不是**「成功」。
- */
 export function isTerminalCauseKind(kind) {
     return typeof kind === 'string' && TERMINAL_CAUSE_KINDS.includes(kind);
 }
-/**
- * **server run 行状态面**的「非成功终局」词(闭集;0.65.0 新铸,L-215② / core [6908];
- * 0.68.0 随 L-247 更名 `TERMINAL_NOT_SUCCESS_STATUSES` → 本名,理由见本段顶注的分源说明)——
- * 「这条 run **不会再自己动了**,而且它没有成功」。
- *
- * 🔴 三员各有出处,且 **`blocked` 与 `suspended`/`needs_review` 的分界是本表存在的全部理由**
- *    (core [6908] 定谳):
- *      · `failed` —— 引擎自报失败;
- *      · `killed` —— 外力终止。🔴 **这一员是本表与 {@link TERMINAL_CAUSE_KINDS} 的分水岭**:
- *        core 的因由闭集里没有它,它是 server run 行状态面自己的词(sdk `FleetTaskStatus` /
- *        `SessionNotifyStatus` 上都在,`RunStatus` 上今天还没有 —— 见 §33 的登记);
- *      · `blocked` —— **agent 自报的终态**:它自己判定这条 run 走不下去了(core `terminal.blocked`
- *        的 `reason` 是它的说明)。🔴 它**不是「等人」** —— 这正是修前被漏掉的那一格;
- *      · 🔴 **`suspended` / `needs_review` 刻意不在表里**:那两个词是**等一次人的决定**,run 还活着、
- *        决定给了就继续跑。把它们读成「非成功终局」会把一条**正等着你**的 run 在面板上判死,
- *        而用户从此不知道有一张卡在等他 —— 与本表要修的方向相反的同一类错。
- *
- * 🔴 形制:`Object.freeze` 的**字面元组**,不是 `ReadonlySet`(同 `RESUME_RETRY_LATER_CODES` 的
- *    已定谳病形:`ReadonlySet` 只在类型面只读,而判定查的就是公面上这同一个实例)。
- */
 export const RUN_TERMINAL_NOT_SUCCESS_STATUSES = Object.freeze([
     'failed',
     'killed',
     'blocked',
 ]);
-/**
- * 一个状态词是不是**非成功终局**({@link RUN_TERMINAL_NOT_SUCCESS_STATUSES} 的成员)。
- *
- * **单铸谓词**(L-215②):本包的通知链(面板 settle 的 `isError` 位)与三端各自的后台白名单
- * 读的必须是**同一个判据** —— 修前包里是一处内联的 `status === 'failed' || status === 'killed'`,
- * 壳里另有一份白名单,两处各写各的,于是 core 加 `blocked` 那天两边一起漏,而漏的后果是
- * **面板把一条自报失败的 run 渲成成功**。
- *
- * 🔴 **开集外的词答 `false`,而 `false` 不等于「成功」**:它只说「这个词不在本端认得的非成功终局
- *    表里」。消费点要判「成功」必须去读成功那一侧的正向证据({@link readRunTerminal} 的
- *    `completed` 臂),不能拿本谓词的取反当成功判据 —— 那正是「不认识的终态词折成成功」那条
- *    已定谳的事故形。
- * 🔴 非串 / 空串 ⇒ `false`(同上:是「答不出」,不是「成功」)。
- */
 export function isTerminalNotSuccess(status) {
     return typeof status === 'string' && RUN_TERMINAL_NOT_SUCCESS_STATUSES.includes(status);
 }
-/**
- * **server run 行状态面**的终局状态词(闭集;0.65.0 新铸,0.68.0 随 L-247 更名 `TERMINAL_STATUSES`
- * → 本名)—— 成功那一员加上 {@link RUN_TERMINAL_NOT_SUCCESS_STATUSES} 的三员。答的是「这条 run
- * 还会不会自己动」,与上一张表答的「它成没成功」是**两个问题**,所以两张表分开、后者由前者派生
- * (加员只有一处要改)。
- *
- * 🔴 同样**不含** `suspended` / `needs_review`:那两个词是「等一次人的决定」——run 没有结束。
- * 🔴 也**不含** core 因由面的 `paused`:那是另一张表的词,而且它在语义上恰好与本表相反
- *    ({@link TERMINAL_CAUSE_KINDS} 顶注)。
- */
 export const RUN_TERMINAL_STATUSES = Object.freeze([
     'completed',
     ...RUN_TERMINAL_NOT_SUCCESS_STATUSES,
 ]);
-/**
- * 一个状态词是不是**终局**({@link RUN_TERMINAL_STATUSES} 的成员)。
- *
- * 用在「这条通知/这条行是不是可以收摊了」这一问上(通知去重的 seed 扫描、后台行 settle 门)。
- * 🔴 表外词 ⇒ `false` = 「本端认不出这是个终局」,**不是**「它还在跑」;要判「在跑」请读正向证据。
- */
 export function isTerminalStatus(status) {
     return typeof status === 'string' && RUN_TERMINAL_STATUSES.includes(status);
 }
-/**
- * 0.72.12 CC-50:**通知**(`task_notification.status`)自己的终态词表 —— 引擎 `TaskNotificationStatus` 五词里的四个终态
- * (`completed` / `failed` / `killed` / `cancelled`;第五词 `event` 是唯一非终态 = 仍在跑的 Monitor 批)逐字镜像。
- * 🔴 它与 run 级 {@link RUN_TERMINAL_STATUSES} 是**两张表**(那张有 `blocked`、没有 `cancelled`):通知说「已取消」是明确终态,
- *    借 run 级表会把它读成「认不出」(异源对抗复审抓出)。住在词表属主文件里,src 别处零内联(终态词汇门 D3)。
- */
 export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(['completed', 'failed', 'killed', 'cancelled']);
-/** 这个通知 status 是不是**明确终态**;表外词(`event` / `unknown` / 未来词 / 缺席)⇒ false = 「本端不能断言它结束了」。 */
 export function isTaskNotificationTerminalStatus(status) {
     return status !== undefined && TASK_NOTIFICATION_TERMINAL_STATUSES.includes(status);
 }