@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/turn/turn-run.d.ts

@@ -0,0 +1,487 @@
+import { type JSONValue, type LanguageModel } from 'ai';
+import { type AgentExtensions, type Initiator } from '../agent-extensions.js';
+import type { TurnHookRegistry } from '../hooks/turn-hook.registry.js';
+import type { Logger } from '../ports/logger.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { AgentEvent } from '../schema/agent-event.js';
+import type { ToolContext } from '../tools/agent-tool.interface.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import type { TurnEnvelope, TurnHost, TurnResult } from './turn-envelope.js';
+/** agent 定义的最小切面 —— 内核不查库，由宿主传入。 */
+export interface AgentDefinition {
+    id: string;
+    systemPrompt: string;
+    enabledTools: readonly string[];
+    /** 自驱循环迭代上限；`null` = 不限（失控回环靠停止按钮与 abort 兜住）。 */
+    maxSteps: number | null;
+    isActive: boolean;
+    /**
+     * 宿主的 agent 字段（`AgentExtensions`），原样进 `ToolContext.agent`、`TurnContext.agent`。
+     * 随本轮所跑的那一版配置一起传进来——工具不自己查库，否则「跑哪一版」会分叉。
+     */
+    extensions: AgentExtensions;
+}
+/**
+ * 结构上与 `llm/protocols` 的 `ProviderOptions` 等价
+ * （即 AI SDK 的 `ProviderOptions` = `Record<string, JSONObject>`，`ai` 包
+ * 只导出组成它的 `JSONValue`、不导出该类型名本身）——**特意不 import 那个模块**：
+ * agent-core 是零 llm 依赖的内核，llm 句柄由壳（chat-turn.service.ts 等）组装好
+ * 传入，本文件不该反向依赖具体的领域模块。
+ */
+export type LlmProviderOptions = Record<string, Record<string, JSONValue>>;
+export interface LlmHandles {
+    model: LanguageModel;
+    providerOptions?: LlmProviderOptions;
+    /**
+     * 工具调用的 `providerMetadata` 里要随 part 落库、重放时作为 `providerOptions`
+     * 发回的命名空间（`ModelHandle.replayedMetadataKeys`，当前只有 google 的思考
+     * 签名）。缺省 = 一个都不留，别家的请求形状一个字节不变。
+     */
+    replayedMetadataKeys?: readonly string[];
+}
+/**
+ * runTurn 的入参。**用单个 options 对象而非位置参数** —— 这里的字段还会继续加
+ * （深度守卫的 excludeTools、异步工具的回投通道都是后来补的），位置参数会持续膨胀。
+ */
+export interface RunTurnArgs {
+    envelope: TurnEnvelope;
+    host: TurnHost;
+    agent: AgentDefinition;
+    llm: LlmHandles;
+    /** 该 stream 的 seq 分配器（由壳 open 时取得）。 */
+    nextSeq: () => number;
+    /**
+     * 事件往哪去。壳传本轮 recorder 的 `emit`（消息中心；那一层同时管落库，
+     * 判据见 `TurnRecorder.emit`）。
+     *
+     * **内核因此不认识 StreamBus**：它只要一个同步的投递口。这也让单测不必再
+     * 搭一个 bus——传个数组的 push 就够（`agent-runtime.service.spec.ts`）。
+     */
+    sink: (event: AgentEvent) => void;
+    /**
+     * 本轮的中断信号。壳传 `bus.signalOf(streamId)`。
+     *
+     * **必填**：它此前是内核自己去 bus 上要的，而在整个 `runTurn` 里那都是同一个
+     * 信号——`signalOf` 只是搭了 streamId 的便车住在事件总线上，与「事件」无关。
+     * 拿不到信号是壳的接线错误（`bus.open` 之后必然有值），别在内核里补
+     * `?? new AbortController().signal` 那种兜底：那会把「停止按钮按了没反应」
+     * 变成一个不报错的静默症状。
+     */
+    abortSignal: AbortSignal;
+    /** 从本轮工具集中排除的工具名（Plan 3 的深度守卫用）。 */
+    excludeTools?: string[];
+    /** 本轮说明按配置算的工具：工具名 → 说明（`ToolRegistry.descriptionsFor`）；没列的用装饰器的。 */
+    toolDescriptions?: Readonly<Record<string, string>>;
+    /**
+     * 本轮的发起人此刻有哪些权限点——决定声明了 `ToolMeta.permission` 的工具端不端上桌
+     * （注册表侧判据见 `buildToolSchemasFor`）；`isSuperuser` 那半只给结构性判断。
+     *
+     * **缺省 `NO_INITIATOR` 是有意的 fail-closed**：内核不查库、不认识角色，这个事实只能
+     * 由壳层（loop-driver 读会话的 userId）告诉它，而漏告诉时正确的退化方向是
+     * 「不给」。系统触发的运行没有发起人，落在这里就是空集，与工具自己那道
+     * `denyUnlessPermitted` 的结论一致。
+     */
+    initiator?: Initiator;
+    /**
+     * 异步工具的回投通道，绑定到本轮的 `envelope.sessionId`（同型见
+     * `ToolContext.postToInbox`）；runtime 原样注入 toolCtxBase，不在内核内
+     * 实现投递/唤醒 ——那些属于壳层（消息中心 + 唤醒广播）。
+     */
+    postToInbox?: ToolContext['postToInbox'];
+    /**
+     * 壳给本轮工具上下文预置的便签（`ToolContext.metadata` 的初值）。**内核不解释
+     * 任何键**，只在建 toolCtxBase 时浅拷一份进去——键的含义归写它的壳与读它的
+     * 工具（今天唯一的一项是工作空间的布局坐标，见 `workspace/tools/tool-support.ts`
+     * 的 `LAYOUT_CTX_METADATA_KEY`）。拷一份是因为 `metadata` 本轮可变，壳手里那份
+     * 不该被工具改到。
+     */
+    toolMetadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * `TurnRun` 要用的单例依赖。**不走 DI**：这个类是 per-turn 的，而 provider 是
+ * 单例——依赖一律由 `AgentRuntimeService` 构造时递进来，单测因此可以直接 `new`
+ * 出一个 TurnRun，不必搭一套 DI 容器。
+ */
+export interface TurnRunDeps {
+    tools: ToolRegistry;
+    hooks: TurnHookRegistry;
+    runs: RunStore;
+    logger: Logger;
+    /**
+     * 失败文案进会话前的净化（如把第三方服务名换成中性说法）；原话只进日志。缺省原样。
+     */
+    sanitizeError?: (text: string) => string;
+    /**
+     * 传输层重试的退避等待。缺省 `abortableSleep`（真定时器）；单测注入记账替身
+     * （`agent-runtime.service.spec.ts` / `turn-timeline.spec.ts` 直接 `new TurnRun`）。
+     * **必须响应 abort**：用户在等待期间按停止，这一轮该立刻以 aborted 收尾，
+     * 而不是等完 4 秒再去发一次注定被拒的请求。
+     */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * 同一步的模型调用因传输层断连最多重试几次（不含首次）。
+ *
+ * 3 次是产品拍板（2026-09-09）：偶发断连一次就够，连断三次多半是服务商那头
+ * 出了问题，第四次也不会好，不如把失败交给用户。
+ */
+export declare const MAX_TRANSPORT_RETRIES = 3;
+/** 第 n 次重试前等多久（毫秒）。指数退避，封顶在最后一档。 */
+export declare function transportRetryBackoffMs(attempt: number): number;
+/** `TurnRunDeps.sleep` 的缺省实现：到点或被 abort 都 resolve，从不 reject。 */
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void>;
+/**
+ * **一轮的执行体，一轮一个实例。**
+ *
+ * 本轮的全部可变状态（工作消息数组、事件账本、usage 累加、迭代计数、压力基线）
+ * 都是这个对象的字段——挂在单例 provider 上会串味，散成 700 行方法里的局部变量
+ * 则谁都测不到。
+ *
+ * **`execute()` 的主干必须保持线性可读**：它就是那个 `for(;;)` 的骨架，每一步
+ * 调一个名字自解释的方法。别把主干本身也拆散——这套 loop 的耦合不在依赖上、
+ * 在时序上（测压必须在 drain 之后 streamText 之前、step-finish 必须发在
+ * tool-result 之后、……），而**看得见的顺序才是被守住的顺序**。
+ *
+ * **整条时序有一份总账测试**：`turn-timeline.spec.ts` 把一轮里内核对外的每一次
+ * 可观测动作（宿主方法、hook 点、streamText、工具执行、每条事件、agent_run 开关）
+ * 打进同一个有序数组逐项比对。改动主干顺序时它会以「哪一行错位」变红——先回到
+ * 对应的判据看它还成不成立，再决定是改回来还是连判据一起改。
+ */
+export declare class TurnRun {
+    private readonly args;
+    private readonly tools;
+    private readonly hooks;
+    private readonly runs;
+    private readonly logger;
+    private readonly envelope;
+    private readonly host;
+    private readonly agent;
+    private readonly llm;
+    private readonly streamId;
+    private readonly runId;
+    private readonly depth;
+    private readonly parentRunId;
+    private readonly turnCtx;
+    /** 本轮的中断信号（壳传进来，见 `RunTurnArgs.abortSignal`）。 */
+    private readonly abortSignal;
+    /**
+     * 本轮的事件账本。**内核自己要读回去**：`eventsToSteps` 落 `agent_run.steps`、
+     * abort 与失败路径靠 `partsFromEventBuffer(entries())` 重建这一轮已产出的
+     * parts。事件流不只是对外广播，别把它改成异步/fire-and-forget（见 TurnJournal）。
+     */
+    private readonly journal;
+    /**
+     * 上下文压力的真实基线：**最后一步**请求的 `inputTokens`。声明在这里而不是
+     * 循环里，是为了让每一条终态路径（含 abort / catch）都能把它带进
+     * `TurnResult.contextTokens` —— 下一轮开头没有别的办法知道上下文有多大，
+     * 而恰恰是被中断/失败的长轮次最需要下一轮一开口就腾空间。
+     */
+    private lastStepInputTokens;
+    /**
+     * 最后一步的输出。**只用来算 `contextTokens`，不进 `ContextPressure`** ——
+     * 轮内测压时模型这一步产出的文字已经被 `charsSinceLastStep` 数进去了，
+     * 再加一次就是重复计。
+     */
+    private lastStepOutputTokens;
+    /**
+     * 增量落库游标：从事件账本重建出的 parts 里，已经交给宿主的前缀长度。
+     *
+     * **turn 级而不是 step 级**：重建的输入是整本账本（`partsFromEventBuffer`
+     * 没有 step 的概念），所以它数的也是整轮的 parts。做成 step 级就要在每步开头
+     * 把它归零，而重建出来的数组并不会跟着归零——第二步的第一次 flush 会把第一步
+     * 的 parts 整段再落一次。
+     */
+    private flushedParts;
+    /** 本轮喂给模型的工作数组（轮初 `loadContext()`，之后逐步追加）。 */
+    private messages;
+    private finalText;
+    private readonly usageAcc;
+    private iterations;
+    /**
+     * 本轮是否已经真 drain 过一次。**第一次必须真取**，之后只探不取、见货即
+     * 换轮（见 `TurnHost.hasPendingInbox`）——否则会话空闲时用户发一条消息就会
+     * 收尾 → re-wake → 又探到有货 → 收尾 …… 永远没人取走它。
+     *
+     * **独立字段而不是复用 `iterations === 0`**：两者今天恰好等价（`iterations++`
+     * 排在所有 `continue` 之前，溢出补救那条也不例外），但它们回答的是不同的
+     * 问题——那个计数问「推理了几次」，这个问「取过没有」。把 drain 行为挂到推理
+     * 计数上，将来任何一次挪动 `iterations++`、或新增一条回到循环顶部的路径，都会
+     * 静默改变「这一圈取不取」；而两个方向的症状（同一批消息被取两次 / 一次都不
+     * 取）都不报错。
+     */
+    private drainedOnce;
+    /**
+     * 上一次测量时 `messages` 的字符规模。轮初这一份对应的是「跨轮基线之后
+     * 已经追加过一些内容」的状态（上一轮的收尾输出 + 本轮的用户消息还没算进
+     * 那个基线里），所以第一次检查会略微低估——同 `charsSinceLastStep` 那条，
+     * 方向是晚触发，第一步真实值回来就纠正了。
+     */
+    private charsAtLastMeasure;
+    /**
+     * 本轮是否已经为「provider 报了上下文超限」补救过一次（见 `settleStep`）。
+     * 一轮一次，不是一步一次：补救会把历史砍到保留预算，这是数量级的下降，
+     * 再撞就不是历史的问题了。
+     */
+    private overflowRelieved;
+    /**
+     * 这一步流内报上来的 provider 错误（`streamText` 的 `onError`）。
+     *
+     * **它是拿到真实失败原因的唯一入口**：SDK 让 `steps` reject 出的是一个全新
+     * 的、不带 cause 的 `NoOutputGeneratedError` 壳（判据见 `provider-error.ts`
+     * 的大注释与 `sdk-contract.spec.ts`）。每步开头清空——补救后重来的那一步
+     * 若成功，上一步的错误不该再跟着走。
+     */
+    private stepStreamError;
+    /**
+     * 这一步开跑那一刻账本的长度（`startInference` 记）。传输层断连要作废的正是
+     * 从这里起到断连为止的那一截——它们没有一条交给过宿主（见
+     * `TurnJournal.discardAfter` 的前提）。
+     */
+    private stepMark;
+    /**
+     * **当前这一步**已经因传输层断连重试了几次。步级而不是轮级：一轮里的每一步
+     * 各有 `MAX_TRANSPORT_RETRIES` 次机会，某一步成功落定就归零（`settleStep`）
+     * ——十几步的长轮次里前面的步各偶发断过一次，不该把最后那步的机会用光。
+     */
+    private stepTransportRetries;
+    private readonly sleep;
+    private readonly sanitizeError;
+    /**
+     * 一个 turn 一个：toolCallId 全局唯一，跨 step 复用同一个不会串味，而
+     * 每步新建会丢掉「这次调用已经报到多少字了」（step 边界不等于调用边界）。
+     */
+    private readonly inputProgress;
+    /**
+     * 同上一个 turn 一个的理由：toolCallId 全局唯一，且丢了「已经拼到哪」就
+     * 没法在下一块 delta 上接着拼出全量前缀。
+     */
+    private readonly inputPreview;
+    /**
+     * 下面三样在 `execute()` 的 2)/3) 步定死，之后整轮恒定。用 definite
+     * assignment 而不是给个空初值：空初值会把「顺序搞反了」变成一次带着空
+     * system prompt 的正常请求，而那不报错。
+     */
+    private system;
+    private toolset;
+    private toolCtxBase;
+    constructor(args: RunTurnArgs, deps: TurnRunDeps);
+    /**
+     * 跑完这一轮。组装 → streamText → 事件发布 → 结果整形。
+     *
+     * **主干是线性的，别拆散**（见类头）。每个编号小节对应下面一个私有方法，
+     * 编号与它们之间那些「位置不能挪」的判据一一对应。
+     */
+    execute(): Promise<TurnResult>;
+    /** agent_run 开行。**失败不该在 streamText 跑之前就中断整轮对话。** */
+    private openRunRow;
+    /**
+     * 终态收尾。**先 persist 后 emit('run-finish')**——这个顺序与 SDD brief
+     * 的示例代码相反，是刻意的修正：run-finish 是"这条流已经跑完"的对外信号，
+     * 若先发它再落库、落库又失败，SSE 订阅者会以为消息已经安全存下，刷新页面
+     * 却发现刚才那条回复不见了。落库失败时改发一个 'error' 事件（否则客户端
+     * 只会看到流卡死在最后一个 text-delta 上、无从得知原因），随后把异常继续
+     * 往上抛——内核不吞这个错误：是否重试/告警/仍要 bus.close() 都是壳的决定
+     * （见类头「内核零 HTTP、零会话概念」），runTurn() 本身的 reject 就是内核
+     * 唯一能给出的信号。
+     *
+     * **重要**：`execute()` 里所有调用点一律写成裸 `return this.finish(...)`
+     * （不带 `await`），这是故意的、不是漏写。原因：finish() 内部会
+     * `await host.persist(result)`；若改成 `return await this.finish(...)`，
+     * persist() 抛出的异常会在 *这次* await 处被 `execute()` 的 try/catch
+     * 捕获，进而落进 catch 分支再调一次 `finish()`——即二次调用
+     * `persist()`，用一个 status:'failed' 的兜底结果覆盖掉刚才那个真实
+     * 结果，且是静默的（不会报错、不会有日志提示"发生了二次持久化"）。
+     * 不加 await 时，finish() 内部 catch 已经把异常处理完（记日志+发
+     * 'error' 事件）并重新 throw，这个 throw 是从"未被 await 的 promise"
+     * 里抛出的，不会被 execute() 的 try/catch 拦截，而是直接作为它返回值的
+     * rejection 冒出去——这正是我们要的行为。**看到任何一处
+     * `return this.finish(...)` 想顺手补 `await`，请先读完这段注释。**
+     */
+    private finish;
+    /**
+     * 整行写不进去时的退路：只盖终态，正文与步骤留空，错误换成一句固定的话。
+     *
+     * 写不进去多半是内容本身的问题（比如 jsonb 拒收的孤立代理对），原样重试只会再
+     * 失败一次；而 `result.error` 可能是落库异常的全文、连 SQL 参数一起，正是那串
+     * 坏内容，也不能带。不补这一步的话，这行会一直停在 `running`，等会话锁过期后被
+     * 孤儿 sweeper 当成进程被杀，标成「服务中断（进程重启）」——真实原因就这样被
+     * 盖住了。
+     */
+    private finishBare;
+    /**
+     * 4.1) drain —— **一轮只调一次**，在第一次推理之前。轮内后续进来的消息
+     * （用户补一句、后台子 Agent 回执）由 `hasPendingInbox` 探到后换轮处理，
+     * 见循环顶部与 `TurnHost.hasPendingInbox`。
+     *
+     * 取出与落库在 `drainInbox` 内部是同一个事务，返回即已入库；随后
+     * 发 `inbox-drained`（带上消息本身）让前端就地插气泡。
+     *
+     * **顺序**：这一次 drain 发生在模型开口之前，所以刚落库的 user 行的
+     * `created_at` 天然早于本轮的任何 assistant 输出。软插话的排序问题因此
+     * 不存在 —— 打断当前这一轮的那条消息属于**下一轮**，由下一个 tick 的这
+     * 同一个点取走。
+     *
+     * @returns 这次取到的条数。
+     */
+    private drainAndAppend;
+    /**
+     * 4.2b) 上下文预算：drain 完、消息补齐、真要发请求的这一刻测压，超了就
+     *       让宿主腾空间。**位置不能挪**——放在 drain 之前会漏掉刚插进来的
+     *       消息，放在 streamText 之后就是「撞爆了再说」。
+     *
+     *       替换的是**头部**而不是重新投影整个数组：尾部那些 drain 进来的
+     *       消息在内存里是围栏形态（`modelParts`），重查一遍库会把围栏静默
+     *       抹掉（见 ContextRelief）。
+     *
+     *       **内核只测压与替换头部**：「阈值多少、模型容量多大、腾出来的是什么」
+     *       全在 `beforeModelCall` 的实现方（单例点，注册期保证至多一个——两个
+     *       插件先后替换头部的语义定义不出来）。没有实现方 = 历史一路喂到撞
+     *       context window 为止，那时溢出补救接手（见 `settleStep`）。
+     */
+    private relieveIfNeeded;
+    /**
+     * 4.3) 发起单次推理。onChunk 只做一件事：把 chunk 机械翻译成事件记进账本
+     * （`projectChunk` 零内核状态）。
+     *
+     * 这里曾另测一份 reasoning 的时间窗，供落库的 reasoning part 用。现在
+     * durationMs 取自事件自带的 `ts`（就是同一个调用栈下一行盖的 `Date.now()`），
+     * 那份并行的计量随 `acc.parts` 一起删了。
+     */
+    private startInference;
+    /**
+     * 中断的收尾。正文从事件账本取，与失败路径（`execute` 的 catch）同一个来源；
+     * 已产出的 parts 不在这里取——`finish()` 的终态 flush 会把它们从同一本账本里
+     * 交给宿主（这条路曾经是「整段重建塞进 `TurnResult.parts`」，而那份只在首步
+     * 之前就中断时才真的落得进库）。
+     *
+     * 曾经这里先试 `stepsToParts(await step.steps)`、reject 了才退回账本——那是
+     * 落库还有第二个来源时的产物，而账本这一份**更全**：SDK 的 step.content 里
+     * 根本没有工具结果（喂它的是无 execute 的 schema 工具集，结果是我们自己执行
+     * 后补发事件的），半截的 tool-call 也只有 `tool-input-delta` 那条流里才有。
+     *
+     * **`step.steps` 仍然要 await 一下**：zero-step abort 时 SDK 让它 reject
+     * （`sdk-contract.spec.ts` 钉住），没人接的 rejected promise 会成为
+     * unhandledRejection 打崩进程。拿到的值不再使用，只是把它消费掉。
+     */
+    private abortedResult;
+    /**
+     * 4.4) 取该步的 text 与 tool-call 列表。
+     *
+     *      **provider 的请求级错误在这里冒出来**（`consumeStream` 吞掉流内
+     *      错误、绝不 reject），其中「上下文装不下了」这一类要就地补救：
+     *      阈值只是我们对「快满了」的猜测，而这一刻 provider 已经替我们判定
+     *      了必要性 —— 也顺带覆盖了「模型没填 max_context_tokens、平时压根
+     *      不主动裁」的那一类会话。
+     *
+     * @returns `null` = 已补救，调用方 `continue` 重来这一步。溢出那条它一个字都
+     *          没产出（请求在生成之前就被拒了，不必收拾任何半成品）；断连那条的
+     *          半成品由 `retractAndRetryIfTransportError` 收拾。
+     */
+    private settleStep;
+    /**
+     * 4.4 的另一条补救：**响应流读到一半连接没了**（`isTransportError`）——把
+     * 这一步已经播出去的半截产出作废，退避一下原地重发。
+     *
+     * 与溢出补救的差别在于「有没有半成品」：溢出是请求在生成之前就被拒了，一个
+     * 字都没有；断连则是模型已经说了一半——这半截已经经 SSE 到了屏幕上、也已经
+     * 记进账本，重发之后模型会**从头再说一遍**（不是续写：请求是同一份，服务商
+     * 那边没有「接着上次」这回事）。所以要做两件事：
+     *
+     * 1. **账本里删掉这一截**（`discardAfter(stepMark)`）：它没有一条交给过宿主
+     *    （步内的 flush 全在 `settleStep` 之后），删了库里不会缺东西；不删的话
+     *    下一次 flush 会把「说了一半的旧版 + 完整的新版」拼成一段落库，模型自己
+     *    看不到（喂模型的是 `settled.stepText`，只有新版），但用户刷新页面会看
+     *    到同一句话出现一遍半。
+     * 2. **发一条 `step-retract` 让前端撤回**：SSE 已经发出去的字收不回来，只能
+     *    告诉它「seq 在 (afterSeq, 本事件) 之间的都作废、正文/思考各裁掉多少字符」。
+     *    seq 单调不复用，作废段与重发段在流里天然可分；这条事件本身不落库、不进
+     *    任何重建路径。
+     *
+     * **步级计数、最多 `MAX_TRANSPORT_RETRIES` 次**（判据见字段注释）。abort 优先：
+     * 用户已经按了停止就不重试，也不睡——睡醒之后照旧 throw，`execute` 的 catch
+     * 按 aborted 收尾。
+     *
+     * @returns true = 已作废并准备重发，调用方 `continue`；false = 不归这里管。
+     */
+    private retractAndRetryIfTransportError;
+    /**
+     * 4.5 前半) 封口这一步的文本段落，并把它回喂进模型的工作数组。
+     *
+     * **`text-end` 是承重的**：落库 parts 从事件账本重建，而文本 part 正是由它
+     * 封口的（见 `partsFromEventBuffer`）。少发一条，这一步的文字就会一直挂在
+     * 重建器的 buffer 里，直到下一步的某个事件才被封口——落库顺序随即错位，且
+     * 一个字都不会报错。
+     *
+     * **reasoning 不在这里做**：它由事件流里 `reasoning-delta` 的连续段自己
+     * 封口，时间窗也取自事件自带的 `ts`。曾经这里从 `step.content` 另取一份
+     * reasoning、再把流里现测的时间窗挂到第一个上——那是"落库另攒一份"的最后
+     * 一处残留，删掉之后「模型说了什么」只剩账本一个答案。
+     *
+     * **文本仍取 `settled.stepText`（只为回喂模型与 `finalText`）**：落库那份
+     * 来自 text-delta 的拼接，也就是用户在流里实际看到的字。两者相等由
+     * `sdk-contract.spec.ts` 钉住——不等的话，界面上的文字与库里的会分叉。
+     */
+    private collectStepOutput;
+    /** 4.5 后半) 逐个执行工具调用：记账 → 落库 → 执行 → 结果三处同源。 */
+    private executeToolCalls;
+    /**
+     * 一次工具调用的结果**两处同源**地落定：事件账本（SSE 与落库共读它）与回喂
+     * 模型的 tool-result，两份用的是同一个字符串与同一个 `isError`。
+     *
+     * 曾经是三处——落库另有一份手工 push 的 part。那一份已经删了：落库改从账本
+     * 投影，于是「SSE 发了、落库那份忘了 push」这种分叉从结构上不再可能。剩下
+     * 的这两处仍要人守：喂模型的那份是**围栏形态**（`withSystemNote` 拼接、按
+     * `isError` 选变体），不是同一个东西，合并不了。
+     *
+     * 抽成一处是因为它有两个调用方（真跑完的、被 `preToolUse` 拒掉的），而
+     * 「拒绝那条路忘了写某一份」的症状分别是：少事件 = 界面卡在调用中、刷新后
+     * 这次调用也凭空消失；少 `toolResults` = 没有 result 的 tool_use → 400。
+     */
+    private recordToolResult;
+    /**
+     * 把事件账本里尚未交给宿主的那一截 parts 落库。
+     *
+     * **落库 parts 只有事件账本这一个来源。** 曾经还有一份手工累积的
+     * `acc.parts`（SSE 发一份、落库另攒一份、喂模型第三份），三者同源全靠一段
+     * 注释担保——而担保不住的东西已经分叉过：SSE 发结构化 JSON、落库发渲染文本，
+     * 同一次调用刷新前后长得不一样。现在「模型说了什么」只有账本一个答案，
+     * 落库是它的纯函数投影。
+     *
+     * **一步之内多次落库**，而不是等整步跑完一次性写。理由是工具可能跑很久
+     * （沙箱 `Bash`、子 Agent 同步等待、媒体解析都是分钟级）：等到步末才写，
+     * 期间任何一次刷新页面都会读到一条不含这次调用的历史，界面上什么都没有
+     * ——用户看到的是"卡死"。SSE 那一半本来就是即时的（`tool-call` 在
+     * `executeTool` **之前**发），缺的一直是落库这半边，于是"看着在跑"与
+     * "刷新后不存在"两种事实并存。落库点有三个，与 SSE 的节奏对齐：发出
+     * `tool-call` 之后、拿到 `tool-result` 之后、以及步末收尾。
+     *
+     * **`'hold'` 不能改成默认的 `'rescue'`**：轮子还在跑，半截的入参会被当成
+     * 一次真实调用落库（判据见 `PartsTail`）。
+     *
+     * **游标在 `await` 之前推进，不是漏写。** 落库失败时这一批就此丢掉、不会被
+     * 后面的 flush 重投——**宁可丢也不能重**：宿主侧是 jsonb `||` 追加，天然不
+     * 幂等，而「写进去了但响应超时」这类失败一重试就会在库里留下两份同
+     * `toolCallId` 的 tool-call/tool-result。那是下一轮要原样喂回模型的历史，
+     * 重复的 tool_use id 各家协议一律拒——即把一次可恢复的写入抖动升级成「此后
+     * 这个会话每次发言都 400」。
+     *
+     * 丢掉那一截的代价是有界的：异常会冒到 `execute()` 的 catch，这一轮以
+     * failed 收尾（用户看得见），SSE 与事件账本上那些内容也都还在；而下一轮重放
+     * 历史时，投影层会给没有 result 的 tool-call 补一条合成的错误结果
+     * （`parts-to-model-messages.ts`），协议不会因此坏掉。
+     *
+     * **`tail` 只有终态那一次传 `'rescue'`**（`finish()`）。游标照常有效：
+     * `'rescue'` 的产出是 `'hold'` 的**前缀延长**（同一串事件、同一个循环，只是
+     * 末尾多了几条被抢救出来的），所以 `slice(flushedParts)` 交出去的仍然恰好是
+     * 「还没交过的那一截」。
+     */
+    private flushStep;
+    /** 4.6) 回喂进工作数组，供下一轮推理。 */
+    private appendStepToMessages;
+    /**
+     * 4.7) 增量落库 + 累加 usage（跨迭代求和）。SDK 的 usage 是两层的，
+     * 缓存命中数只住在嵌套层，必须先拍平——见 usage.ts。
+     */
+    private accountUsage;
+}
+//# sourceMappingURL=turn-run.d.ts.map

package/dist/turn/turn-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-run.d.ts","sourceRoot":"","sources":["../../src/turn/turn-run.ts"],"names":[],"mappings":"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"}