@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/adapter/downstream/terminalToSdkResult.d.ts

@@ -1,412 +1,100 @@
-/**
- * ⇄ B3 批搬迁(2026-07-27,多端改造设计稿 §3 B3):cli src/seam/adapter/downstream/terminalToSdkResult.ts
- * **逐字整搬**(闭包实测 4 文件 / 零 Node 内建)。`Date.now()`(elapsedMs)是浏览器原生,原样保留。
- */
-/**
- * Terminal projector (T22): `done` → CC `SDKResultSuccess`, `failed` →
- * `SDKResultError` (contract 02 §2.10/§2.11; 08 CS-10/CS-11/UC-2).
- *
- *  done   : result.result ⇐ TaskResult.result; result.model ⇐ TaskResult.model
- *           (MF-25 — the served model id, e.g. "deepseek-v4-pro"); stats ⇐
- *           flatten(TaskStats); modelUsage ⇐ stats.modelUsage (per-model split).
- *           DROP CC stop_reason / duration_api_ms / structured_output /
- *           fast_mode_state (contract 02 §2.10).
- *           Budget gate is a RESULT branch, not a throw: a `done` whose terminal
- *           cause is a failure carrying a budget code still settles as a result
- *           (08 CS-10) — surfaced via `terminal.failed.code` upstream, not here.
- *  failed : flatten CC's 4 SDKResultError subtypes + errors[] into the single
- *           {code, message} pair. A user-cancelled run settles here with
- *           code:"cancelled" (08 CS-11).
- *  park   : done 帧的 `terminal.kind === "paused"`(HITL/plan-review park)在无
- *           overlay 消费面(-p / 非 REPL)也走 SDKResultError 臂 —— 绝不投影成
- *           空成功([884]A1,见下方分支注释)。
- *
- * ── 终态分流([909]B1,2026-07-16;core 5.8.0 词表迁移 [2489],2026-08-04;因由形 0.60.0)──────
- * 🔴 **0.60.0(engine ≥7.64.0 / sdk 8.4.0)换判据**:终局不再是并列的八个平面键,而是一条**带标
- * 因由** `result.terminal`(四臂)。本文件一个 `status` 字面都不再比较 —— 读法单源在
- * `runTerminal.readRunTerminal`,它同时认**扁平形**的两个来源(升级前落盘、读盘面逐字回放的历史行;
- * server 自己的 409 拒绝信封),并把四臂之外的词一律归到 `unknown` 臂。分流表因此按**因由臂**排。
- *
- * ✅ **单代读面**(退役批,2026-08-04):core 5.8.0 是 BREAKING 大车(`status:'timeout'` 退役、
- * 四个到限码全部改名),交付时点壳的引擎还捆 core 5.7,故读面曾同时认新旧两代,每处钉一个可 grep
- * 的退役记号 + 一道逐文件逐次的等值登记门。**server 6.0.0 已捆 core 5.8.0 发车** ⇒ 窗口期关闭,
- * 旧码腿(`budget.exceeded`/`budget.precall`/`limit.max_turns`)与 `status:'timeout'` 整臂本批删除
- * (记号与登记门同批清空),读面与写面(limitsWire.ts)重新同为单一新形。旧形不再被认走这件事由
- * `scripts/run-streamjson-timing-honesty-test.mjs` 的四条**退役负控**常驻看守(加回来就红)。
- *
- *   terminal.kind   code                                 → subtype                      is_error
- *   ────────────────────────────────────────────────────────────────────────────────────────────
- *   completed       —(结构上写不出码)                  → 'success'                     false
- *   failed          limits.max_cost_exceeded             → 'error_max_budget_usd'        true
- *   failed          limits.max_turns_exceeded            → 'error_max_turns'             true
- *   failed          limits.max_tokens_exceeded           → 'error_during_execution'      true
- *                   (5.8.0 新增,且是**主限**。CC 4 词表里没有 token 预算词 —— error_max_budget_usd
- *                    是**美元**账不是 token 账,借用它会让消费者按成本口径读一个 token 口径的停因。
- *                    ⇒ 诚实兜底词 + errorCode 超集透传辨认;[2489] 明记该终帧「result 带已产出正文」
- *                    ⇒ 走 salvage 腿,正文不丢。)
- *   failed          limits.max_walltime_exceeded         → 'error_during_execution'      true
- *                   (5.8.0 起墙钟到限的**唯一**形;5.7 的 `status:'timeout'` + `limit.timeout`
- *                    是同一个停因的上一代形,server 6.0.0 捆 core 5.8.0 后已随本批整臂删除。
- *                    选型理由留档:CC 无 wall-clock deadline 概念。曾选 error_max_turns「唯一
- *                    run-limit 族词」,[2084]②a 定谳那是帧内自相矛盾(errorCode 是墙钟码而
- *                    num_turns 远小于上限)且对墙钟停指错旋钮(max-turns 是可恢复失败)⇒ 改诚实
- *                    兜底词。真实语义靠 errors[] 文案 + errorCode 透传辨认,不变。)
- *   failed          output.invalid                       → 'error_max_structured_output_retries' true
- *   failed          其余(含 cancelled/conflict…)        → 'error_during_execution'      true
- *   blocked         —(engine 只给 reason)               → 'error_during_execution'      true
- *   paused          —(结构上写不出码;扁平形回放的历史   → 'error_during_execution'      true([884]A1)
- *                    行仍可能带 review.pending)          措辞按门种分「复核 / 交互作答」两句
- *   unknown         —                                    → 'error_during_execution'      true(防御:
- *                    非 completed 的终局一律≠空成功;errors[] 里如实报出那个词的字面。**因由座在场
- *                    却整个读不出**(坏形/混合载体)也落这一臂,措辞改说「读不出」而不是编一个词)
- *   〈整个缺席〉    —                                    → 'error_during_execution'      true(0.72.12 CC-50:
- *                    (mock 车道 / 不带终态词的旧合成帧;读器返 null)  fail-closed 取舍 + `_sema_outcome:'unknown'`;
- *                    此前落 'success' = 把「没有终态记录」编成成功;unknown 臂同带该标记)
- *
- * errorCode 透传:引擎的码骑 additive seam 字段 `errorCode`(CC schema 无此字段——与 success 臂的
- * `model` 同款超集姿势),集成面可精确分流(limits.max_tokens_exceeded vs cancelled …)。
- * 🔴 因由形下「码属于失败」是**形状**:paused / blocked 上引擎写不出码 ⇒ 这两臂的 `errorCode`
- * 从 0.60.0 起恒缺席(扁平形回放的历史行仍带得动它)。截断 salvage:写出窗兑现的 r.result(非空)
- * 骑 additive `result` 字段——CC error 帧无 result,但把引擎已救回的最终文本静默丢弃对 -p 消费者
- * 是净损失。
- *
- * 成本取数 = `TaskStats.costMicroUsd`(整数 micro-USD 单轨,SDK 1.0.0 / server 1.319.0 /
- * core 2.0.0 起;legacy float `costUsd` 已删,见 costOrNull 头注)。**零成本不再 ambiguous**
- * (0.65.0 / B-073 ①):显式 `0` = 声明免费、键缺席 = 没定价,两档在 wire 上可分,包边界照实转;
- * 部署级「这台 worker 到底配没配价表」仍可另问 `Capabilities.pricingConfigured`(contract 02
- * §2.10 VERIFY)。本投影器只做单位换算(/1e6)并原样过境。
- */
 import type { AgentEvent, TaskStats } from '@sema-agent/sdk';
 import { type SDKMessage, type EmitContext } from '../types.js';
 import { type SemaModelUsage } from './turnUsageToModelUsage.js';
-/**
- * CC 的 `NonNullableUsage` 占位形(coreSchemas 里是 `z.unknown()`,这里给它一个名字)
- * + 0.66.0 / D-2 的两位 sema 超集(两位都**只在该说话时在场**,绝不铸 `false` / 假 0)。
- */
 export interface SemaFlatUsage {
     readonly inputTokens: number;
     readonly outputTokens: number;
     readonly cacheReadInputTokens: number;
     readonly cacheCreationInputTokens: number;
     readonly webSearchRequests: number;
-    /**
-     * D-2 / L-192② —— 在场且为 `true` ⇒ 同行的 `webSearchRequests: 0` 是「**wire 上没有这本账**」,
-     * 不是「这条 run 一次网搜都没做」。core 的 `TaskStats` 面上**没有**这一格(网搜只在散文里出现),
-     * 而 CC 的这一格型面是必填 `number` ⇒ 「不知道」只能以判别位在场(与 `_sema_cost_absent`
-     * 同一条两键合读纪律)。上游哪天真发这一格,值照读、本位退场(门里有正反两控)。
-     */
     readonly _sema_web_search_requests_absent?: true;
-    /**
-     * D-2 / L-192② —— `TaskStats.totalInputTokens`:**cache-INCLUSIVE** 的输入总量
-     * (core 逐字「the quantity cost is computed from … 'how much context did this task present'」)。
-     *
-     * 🔴 **为什么另开一格而不是灌进 `inputTokens`**:core RB-457-a(3.0.0 BREAKING)把
-     * `promptTokens` 的语义翻成 cache **MISS** 分量,而 CC / Anthropic 的 `input_tokens` 本义
-     * 正是 MISS —— 同帧已经另有 `cacheReadInputTokens` / `cacheCreationInputTokens` 两格,把总量
-     * 灌进 `inputTokens` 就是 core 逐字点名的那笔双算(「a 98% hit rate surfaced as 49.5%」)。
-     * 🔴 **为什么这一位必须长在扁平 usage 上**(与 [2295]「CC 形状不承载非 CC 语义」不矛盾,
-     * 差别与 `_sema_cost_absent` 那条同源):per-turn 那一面有**逐字通道**
-     * (`EngineTurnUsage` / chrome `last_turn_usage.engineUsage`),镜像不必长第二个座位;而
-     * **终帧这一面没有任何别的载体** —— 不给座位,这条 run 到底摆了多少上下文在终帧上就问不出来。
-     * 缺席 = wire 没报(老引擎 / 网关没报 usage),**绝不**拿 `promptTokens` 冒充总量。
-     */
     readonly _sema_total_input_tokens?: number;
-    /**
-     * D-2 族扫(0.66.0;异源对抗复审 [medium])—— `TaskStats.cacheWriteTokensLong`:**1 小时 TTL**
-     * 那一档的缓存写入分量。缺席 = wire 没报;显式 `0` 是**读数**(core 逐字「0 unless 1h caching
-     * is in use」),不是缺席。
-     * 🔴 **刻意不求和进 `cacheCreationInputTokens`**:core 对这两格的说法互相矛盾 ——
-     * `cacheWriteTokens` 自述是「Anthropic `cache_creation_input_tokens`」(协议侧那个量本就含 1h
-     * 子项),而 `totalInputTokens` 的求和式又把两格**并列相加**(那要求它们互不重叠)。相加与不加
-     * 各有一种错法,证据不足**不猜**:CC 那一格逐字保持 `cacheWriteTokens`(既有值一字不动),长 TTL
-     * 分量原样另给,对账由消费方按两个数自己做。上游澄清后再定(登记见 INTEGRATION §31d)。
-     */
     readonly _sema_cache_write_tokens_long?: number;
 }
-/**
- * **这一条流**的收口快照(per-stream 的按次入参,绝不挂在调用方可复用的 `EmitContext` 上)。
- * 每一格缺席 ⇒ 这次投影没有对应的流内面,只读终帧 `stats` 那一半。
- */
 export interface TerminalStreamObserved {
     readonly usageMissingObserved?: boolean;
     readonly nestedUsageByTask?: ReadonlyMap<string, MutableSubagentUsageRow>;
-    /**
-     * 0.73.4 —— 本流见过的 `tool_start` 帧:`toolCallId → args`(帧上那只对象的**同一个引用**,不复制)。
-     * 拒绝账本行给不出入参对象,而被拒那次调用的入参已经在同一条流上;终帧铸拒绝行时按 id join
-     * (判据见 {@link joinableToolInput})。同一个 id 出现过两份不同入参的,收集方必须**不放进来**。
-     */
     readonly toolInputByCallId?: ReadonlyMap<string, unknown>;
 }
-/** 本流 `toolCallId → args` 快照的条数上限;溢出的调用不记 ⇒ 那一行 join 不上,留在 sema 载体(诚实缺席)。 */
 export declare const TOOL_INPUT_JOIN_MAX_CALLS = 4096;
-/**
- * D-1 / L-192①(0.66.0)—— 一条被拒记录的**全可选**形:CC `SDKPermissionDenial`
- * (agent-types `permissions.d.ts`,真形 `{tool_name: string; tool_use_id: string;
- * tool_input: Record<string, unknown>}` **三键必填**)的三键 + 一位 sema 超集,**每一键都按
- * wire 能不能兑现决定在不在**。
- *
- * 🔴 **三键里兑现得出两键**(引擎 ≥7.23.0):这本账在 wire 上是 `TaskStats.humanReview.gates[]`,core
- *    的 gate 行是具名 `HumanReviewGateRow` 六格(`kind` / `waitMs` / `decision?` / `toolName?` /
- *    `toolArg?` / `toolCallId?`,`task-result.d.ts` 真字节)。`toolCallId` 是**行身份**(core 逐字:
- *    「absent = not joinable … Never a placeholder」—— 缺席 = 铸点没有调用 id 可给:探针行 / 非
- *    tool_approval 的耐久门 / 老引擎;**不是**「没有调用」)。被拒时的**入参对象**账本上**没有**
- *    (sdk `types.d.ts` 同一格逐字记着「`tool_input`/`toolInput` **不在** gate ledger 上」)。⇒ 第三键的
- *    来源是**同一条流的 `tool_start` 帧**(0.73.4;按 `toolCallId` join,判据见 {@link joinableToolInput});
- *    join 不上 ⇒ 那一键**缺席**,绝不铸 `{}`:一个空对象在 CC 形上读起来是「这次调用的入参是空的」,那是编的。
- * 🔴 **两键都声明在这里**(不是假 affordance):mint 点对它们是**开集宽读** —— `toolCallId` 在
- *    7.23.0 串上账本那天 `tool_use_id` 就**自动**开始带值(见 {@link permissionDenialParts} 的自动
- *    升级腿,门里钉着 7.23.0 的真字节正控);账本上的 `toolInput` 仍等上游(哪天串上,它恒优先于流内
- *    join 的那份)。消费端读它们**必须按可选位读**(老引擎 / 不可 join 的行两键缺席)。
- * 🔴 `_sema_tool_arg` = core 已经**脱敏并截短**的一行入参摘要(`primaryActivityArg` 同一道口),
- *    它是 CC「denied: Bash(rm …)」那行显示唯一拿得到的材料。UNTRUSTED-for-display:只渲染,
- *    绝不回喂模型、绝不当鉴权判据。
- */
 export interface SemaPermissionDenial {
-    /** 被拒的工具名(⇐ `gates[].toolName`);wire 没报 ⇒ 键缺席,绝不编一个名字。 */
     readonly tool_name?: string;
-    /** 被拒的**那一次调用**(⇐ `gates[].toolCallId`,引擎 ≥7.23.0 带;缺席 = 不可 join,不是没有调用)。 */
     readonly tool_use_id?: string;
-    /** 被拒调用的**完整入参**(⇐ `gates[].toolInput`,今天 wire 上没有 ⇒ 恒缺席;非对象一律不铸)。 */
     readonly tool_input?: Record<string, unknown>;
-    /**
-     * 0.73.4 —— `tool_input` 的来源位,**只在**它来自同一条流的 `tool_start` 帧时在场(账本自己带的那份不铸本位)。
-     * 读法:在场 = 这只对象是流内帧上的入参(审批人改写过入参的调用,帧上是改写后的那份)。
-     */
     readonly _sema_tool_input_source?: 'tool_start';
-    /** 被拒调用的一行入参摘要(⇐ `gates[].toolArg`,core 侧已脱敏截短);缺席 = 这条腿没串入参。 */
     readonly _sema_tool_arg?: string;
 }
-/**
- * D-3 / B-068 · L-198(0.66.0)—— core `TaskStats.costBreakdown`(`task-result.d.ts` 的
- * finance taxonomy)的**窄读投影**,单位 = **micro-USD 原值**(键名即单位,包不折 USD:
- * 折一次就多一次浮点漂移,而这一面正是账单面)。
- *
- * 每一格都是**可选**的:读不出的键不铸(绝不补 0 —— core 明说 unpriced 时整段与 `costMicroUsd`
- * 一起省略,而一个补出来的 0 在账单面上就是一句「这一段没花钱」的假话)。**开集**:core 往这段
- * 里加新类目时原样过境(sdk 的型面是 `costBreakdown?: unknown`,词表属主在 core)。
- */
 export interface SemaCostBreakdown {
-    /** 根 agent 的 LLM 花费 = `costMicroUsd − compactionMicroUsd`(**不减 nested**)。 */
     readonly llmRootMicroUsd?: number;
-    /** 委派子代的 LLM 花费 = `nested?.costMicroUsd ?? 0`;它**在 `costMicroUsd` 之外**。 */
     readonly nestedSubagentMicroUsd?: number;
     readonly memoryConsolidationMicroUsd?: number;
     readonly suggestionsMicroUsd?: number;
-    /** 任务内压缩的 LLM 花费 —— 它**在 `costMicroUsd` 里面**(所以从 root 里减掉)。 */
     readonly compactionMicroUsd?: number;
-    /** 开集:core 新加的类目原样过境(消费方 switch 必须带 default)。 */
     readonly [k: string]: number | undefined;
 }
-/**
- * D-3 —— core `NestedUsage`(`tool-spec.d.ts`)的窄读投影:这条 run **委派出去**的那本账。
- * 🔴 `costMicroUsd` **缺席 = 委派花费没定价**(core 逐字 `ABSENT when the delegated spend was
- * unpriced (RB-368) — never a fabricated 0`)⇒ 键缺席,绝不铸 0。
- */
 export interface SemaNestedUsage {
     readonly tokens?: number;
     readonly turns?: number;
     readonly tasks?: number;
     readonly costMicroUsd?: number;
 }
-/**
- * D-3 —— 终局**对账三段 + 两个判别位**。这正是 chrome 臂 `run_cost_reconciled` 的载荷本体:
- * 两面共用**同一个**读器,所以「终帧超集键」与「chrome 对账臂」永远不会各算各的
- * ([paired-mechanisms-must-share-premise])。
- *
- * core 的两条对账式(`task-result.d.ts` 逐字):
- *   · `llmRootMicroUsd + compactionMicroUsd === costMicroUsd`(压缩在 own 里面);
- *   · fully-reconciled spend = `costMicroUsd + nested.costMicroUsd`(子代在 own **外面**)。
- * 🔴 本包**不当第二个会计**:三段照实过境,不改数、不补差;`reconciledMicroUsd` 只在**两段都
- * 读得出**时才铸 —— 少了任何一边,总额就是不知道,而「不知道」只能以判别位在场。
- */
 export interface RunCostReconcile {
-    /** 本任务 own 花费(⇐ `costMicroUsd`),**不含**子代。缺席 ⇒ 没定价,见 `costAbsent`。 */
     readonly ownMicroUsd?: number;
-    /** 委派子代花费(⇐ `nested.costMicroUsd`)。缺席 ⇒ 没委派、或委派花费没定价(见判别位)。 */
     readonly nestedMicroUsd?: number;
-    /** 任务内压缩花费(⇐ `costBreakdown.compactionMicroUsd`);它已含在 `ownMicroUsd` 里。 */
     readonly compactionMicroUsd?: number;
-    /** 根 agent 花费(⇐ `costBreakdown.llmRootMicroUsd`);`own − compaction`。 */
     readonly llmRootMicroUsd?: number;
-    /** `own + nested` —— core 逐字的 fully-reconciled spend;**任一段不知道就不铸**。 */
     readonly reconciledMicroUsd?: number;
-    /** `true` ⇒ own 花费**没定价**(不是 0)。绝不铸 `false`。 */
     readonly costAbsent?: true;
-    /** `true` ⇒ 委派过,但那本账**没定价**(不是 0)。绝不铸 `false`。 */
     readonly nestedCostAbsent?: true;
-    /**
-     * 0.67.0(core 7.14.0 `TaskResult.stats.usageMissing`)—— `true` ⇒ 这条 run 上**至少有一轮**
-     * 没报 usage,所以本对账里的每一个数字(以及终帧 `usage` / `modelUsage` / `_sema_nested_usage`
-     * 的每一个 token 数)都是**下界**,不是一笔已知的账。
-     *
-     * 🔴 **`tokens: 0` 在这一位在场时读作「不知道」,不是「免费」**(core 合同逐字)。
-     * 🔴 **never false**:core 只在真缺 usage 时铸 `true`,缺席 ⇔ 每一轮都报了 usage ⇒ 本包同律
-     *    **缺席不铸**(铸一个 `false` 就是替引擎说「我全都数到了」)。
-     * ⚠️ 它**与成本位正交**:`costAbsent` 说的是「没定价」,本位说的是「数得不全」——
-     *    一笔定了价、但少数了几轮的账,两位可以同时在场,渲染面要分别说。
-     */
     readonly usageLowerBound?: true;
 }
-/** {@link readRunCostFacts} 的产物:两面(终帧超集键 / chrome 对账臂)各取所需。 */
 export interface RunCostFacts {
-    /** 终帧 `_sema_cost_breakdown` 的值;一个键都读不出 ⇒ `undefined`(不铸空对象)。 */
     readonly breakdown?: SemaCostBreakdown;
-    /** 终帧 `_sema_nested_usage` 的值;同上。 */
     readonly nested?: SemaNestedUsage;
-    /** chrome 臂 `run_cost_reconciled` 的载荷本体。 */
     readonly reconcile: RunCostReconcile;
 }
-/**
- * D-3 / B-068 · L-198 —— 终局成本事实的**唯一读器**(终帧超集键与 chrome 对账臂共用)。
- *
- * 🔴 `stats` 不是可读对象(409 拒绝信封 / park 体 / `failed` 事件帧)⇒ 返 `undefined` =
- * **这条帧没有账**,调用方据此「不说话」(不发臂、不铸键),而不是发一条全缺席的空账。
- *
- * 🔴 **第二参 `observed`(0.67.1 / B-091,additive)**:**这一条流**的流内观测快照。给了它,对账段上的
- * {@link RunCostReconcile.usageLowerBound} 就是**取并后**的读数(见 {@link usageLowerBoundOf});
- * 不给(旧签名)⇒ 只读 `stats` 那一半,既有端逐位不变。
- * ⚠️ 包内的两个调用点(`costFactParts` 与 `runStream` 的 `run_cost_reconciled` 铸点)**都必须**
- * 传它 —— 少传一处就是把本件修的那条不对称原样种回去。
- * 🔴 0.67.2 / 车 I 件 I-1:它是**按次调用的入参**,不再是 `EmitContext` 上的一格 —— 共享 ctx 被复用
- * 给多条流时,那一格会把别的流的缺口串进这一条(见 {@link usageLowerBoundOf} 的第三段 🔴)。
- */
 export declare function readRunCostFacts(stats: TaskStats | undefined, observed?: {
     readonly usageMissingObserved?: boolean;
 }): RunCostFacts | undefined;
-/**
- * L-228(0.67.0)—— 一只子任务在**这条流上被看见的**那本账(`_sema_nested_usage_by_task` 的行形)。
- *
- * 🔴 **它是流内累加的产物,不是引擎报的一个字段**:core 终局只有合计 `stats.nested`
- * (`{tokens, turns, tasks, costMicroUsd}`),**没有 per-task 分项**(`task-result.d.ts` #594-660 亲验)。
- * ⇒ 这几个数的唯一来源是子流 `turn_end` 的逐轮累加,而「这条流看见了多少」与「这条 run 一共有多少」
- * 可以不相等 —— 那正是 {@link SemaNestedUsageByTask.partial} 存在的理由。
- * 🔴 **没有 `costMicroUsd`**:`turn_end.usage` 上没有钱这一格(定价在终局做),编一个出来就是造账。
- */
 export interface SemaSubagentUsageRow {
-    /** 这条流上看见的该子任务 `turn_end` 条数(**不是** core 的 `nested.turns`,见顶注)。 */
     readonly turns: number;
-    /** 逐轮 `inputTokens` 求和。`usageMissing` 在场时它是**下界**。 */
     readonly inputTokens: number;
-    /** 逐轮 `outputTokens` 求和。同上。 */
     readonly outputTokens: number;
-    /** 逐轮 `cacheReadTokens` 求和;一轮都没报过 ⇒ **键不在**(绝不铸 0 冒充「零命中」)。 */
     readonly cacheReadTokens?: number;
-    /** `true` ⇒ 这只子任务**至少有一轮**没报 usage,本行三个数是**下界**。never false。 */
     readonly usageMissing?: true;
-    /**
-     * 0.67.2(车 I 件 I-2)—— `true` ⇒ **这一行是两个身份命名空间的同字面碰撞合并出来的**:
-     * 一半轮次的行键来自真身份 `sourceTaskId`、另一半来自回落的 `parentToolCallId`,而两者的**字面相等**。
-     * 本层没有任何读数能把它们拆回去(core 的合同不保证两个命名空间互斥),所以这一行的数字是**几只
-     * 子任务混在一起**的和。⇒ 这一位在场时**必然**伴随 `_sema_nested_usage_by_task_partial`,消费方
-     * 不许把本行当成某一只子代的账去渲。**never false**(缺席 = 这一行的每一轮都来自同一个命名空间)。
-     */
     readonly keyCollision?: true;
 }
-/** {@link SemaSubagentUsageRow} 的累加中间态(runStream 持有;`readonly` 在收口那一拍才加)。 */
 export interface MutableSubagentUsageRow {
-    /**
-     * 0.67.2(车 I 件 I-2)—— **交付面的裸 id**(`sourceTaskId`,缺席时是回落的 `parentToolCallId`)。
-     * 🔴 累加表的**键**从 0.67.2 起带出身前缀(`s:` / `p:`,见 `runStream` 的 `rowKey`),因为两个身份
-     * 命名空间的字面可以相等、并在累加那一层就把两只子任务并掉(并掉之后出身位只剩一种,「出身混合」
-     * 那道闸读不出混合);交付面的键仍然必须是**裸 id**(端零改),所以原值存在行上,前缀不出本层。
-     */
     taskId: string;
     turns: number;
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens?: number;
     usageMissing?: true;
-    /**
-     * 0.67.1(异源复审 [medium] 实抓)—— **这一行的键是回落来的**(`parentToolCallId`),不是真身份
-     * `sourceTaskId`。**只进 `partial` 的判据,不进交付行**({@link SemaSubagentUsageRow} 上没有这一位:
-     * 它是本层的对账中间量,不是一条要过 wire 的事实)。
-     * 🔴 为什么非记不可:B-090 放宽入表条件之后,一条流上的行键**可以有两种出身**。混合出身时
-     * **同一只**子任务可以同时占两行(一轮走回落键、一轮走真身份),而另外两只子任务又可能并进同一个
-     * 回落行 —— 一次**拆行**与一次**合行**的计数误差方向相反,于是「行数 === `nested.tasks` **且**
-     * turns 之和 === `nested.turns`」两条对账**同时成立**,一张归属错误的表被标成「可证完整」。
-     * ⇒ 出身混合时 {@link SemaNestedUsageByTask.partial} **恒立**(见 `nestedUsageByTaskParts`)。
-     */
     keyFromParentFallback?: true;
 }
-/**
- * 子代用量面的**下界判别位键名**(`_sema_subagent_usage_partial`)。
- *
- * 🔴 它与终帧的 `_sema_usage_lower_bound` **刻意不同名**(见上段):两者答的是两个问题,
- *    一个消费面同时拿到两者时必须分得出来。
- * 🔴 本包**不在任何 wire 帧上铸它** —— 它是**渲染面**的位(端把一行子代用量交给自己的视图时用)。
- *    包给名与判据,是为了三端零自拼(同 `gateIdentity` 的三条身份键字面同一条纪律)。
- */
 export declare const SEMA_SUBAGENT_USAGE_PARTIAL_KEY = "_sema_subagent_usage_partial";
-/**
- * 一行子代用量的数字**是不是下界**({@link SEMA_SUBAGENT_USAGE_PARTIAL_KEY} 该不该立)。
- *
- * 三个来源**取并**,每一条都能独立让这一行的数字不是最终数:
- *  · `row.usageMissing` —— 这只子代**至少有一轮**引擎没报账(数字照累加,但它是下界);
- *  · `row.keyCollision` —— 两个命名空间的 id 撞了字面,这一行是**几只子代的账并起来的**;
- *  · `opts.tablePartial` —— 整张表对不上引擎的权威合计(`_sema_nested_usage_by_task_partial`)⇒
- *    表里**每一行**都不可证完整。
- *
- * 🔴 **`false` 不是「这一行是最终数」的证据**:它只说「本端没有任何一条理由认为它是下界」。
- *    行本身还没收口(端自己的 store 知道,包不知道)时,端要自己把那一条并进来 —— 所以这只谓词
- *    收一个 `opts`,而不是假装它掌握全部真相。
- * 🔴 非对象 / 缺席入参 ⇒ `false`(答不出,不是断言);坏形位(非 `true` 的值)不当真。
- */
 export declare function subagentUsageIsPartial(row: {
     readonly usageMissing?: unknown;
     readonly keyCollision?: unknown;
 } | null | undefined, opts?: {
     readonly tablePartial?: boolean;
 }): boolean;
-/** 终帧两个超集键的产物形(见 {@link nestedUsageByTaskParts})。 */
 export interface SemaNestedUsageByTask {
     readonly rows: Readonly<Record<string, SemaSubagentUsageRow>>;
-    /** 见 `_sema_nested_usage_by_task_partial`。 */
     readonly partial: boolean;
 }
-/**
- * D-2 族扫(0.66.0;异源对抗复审 [medium])—— **终局** per-model 行的 sema 超集位。
- *
- * 🔴 为什么只长在终局这一面:per-turn 那一面有**逐字通道**(`EngineTurnUsage` /
- * chrome `last_turn_usage.engineUsage`,整对象原形过境),镜像不必长第二个座位([2295] 裁 ②);
- * 而**终局的 per-model 分表没有任何逐字通道** —— 不给座位,多模型部署下「哪个模型摆了多少上下文 /
- * 那一行的分量口径可不可信」在终帧上就问不出来。故本形只由 `mapModelUsage` / `modelUsageFor`
- * (两条终局腿)加挂,`toCcModelUsage` 那个共用 mint 点一个字不动。
- */
 export interface SemaTerminalModelUsage extends SemaModelUsage {
-    /** ⇐ 行上的 `totalInputTokens`(cache-INCLUSIVE 总量);缺席 = 这一行没报。 */
     readonly _sema_total_input_tokens?: number;
-    /**
-     * ⇐ 行上的 `usageBasis` —— **口径版本标记**(sdk 逐字:`"uncached-components-v1"` = 三个输入
-     * 分量键互不重叠;缺席 = 口径不可保证,可能是存量行、也可能是跨阶段混窗聚合)。**开集串**:
-     * 原样过境,消费方 `switch` 必须带 `default`;🔴 **缺席不许倒推口径**(sdk 明令)。
-     */
     readonly _sema_usage_basis?: string;
-    /** ⇐ 行上的 `cacheWriteTokensLong`;语义与不求和的理由见 `SemaFlatUsage` 的同名位。 */
     readonly _sema_cache_write_tokens_long?: number;
 }
-/** `done` → SDKResultSuccess (contract 02 §2.10 / 08 CS-10). */
 export declare function doneToSdkResult(ev: Extract<AgentEvent, {
     type: 'done';
-}>, ctx: EmitContext, 
-/**
- * 0.67.2:**这一条流**的收口快照 —— usage 缺口观测(见 {@link usageLowerBoundOf})与 per-subagent
- * 累加表(见 {@link nestedUsageByTaskParts})。两格都是 per-stream 的事实,缺席 ⇒ 这次投影没有流内面
- * (只读 `stats` 那一半、两个分表键都不铸),**绝不**回头去读调用方对象上可能残留的上一条流。
- */
-observed?: TerminalStreamObserved): SDKMessage;
-/** `failed` → SDKResultError (contract 02 §2.11 / 08 CS-11). */
+}>, ctx: EmitContext, observed?: TerminalStreamObserved): SDKMessage;
 export declare function failedToSdkResult(ev: Extract<AgentEvent, {
     type: 'failed';
-}>, ctx: EmitContext, 
-/** 0.67.2:同 {@link doneToSdkResult} 的第三参。 */
-observed?: TerminalStreamObserved): SDKMessage;
-/**
- * Dispatch a terminal AgentEvent to its SDKResult arm.
- *
- * 🔴 第三参(0.67.2 / 车 I 件 I-1):**这一条流**的 usage 观测快照。`runStream` 在终帧那一拍**按值**
- * 交给它与 `run_cost_reconciled` 铸臂 —— 两个投影口读的是**同一份本流快照**,而不是一个可能被别的流
- * 写过的共享位。缺席(端直调)⇒ 与 0.67.1 的旧签名逐位同行为。
- */
+}>, ctx: EmitContext, observed?: TerminalStreamObserved): SDKMessage;
 export declare function terminalToSdkResult(ev: Extract<AgentEvent, {
     type: 'done';
 } | {