@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/turn/provider-error.js

@@ -0,0 +1,154 @@
+import { APICallError, NoOutputGeneratedError } from 'ai';
+/**
+ * provider 请求级错误的「取真」与「说人话」。
+ *
+ * **为什么需要取真**：`streamText` 里，provider 在 `doStream` 阶段抛出的
+ * `APICallError`（余额不足、鉴权失败、限流、上下文超限……）**不会**成为
+ * `result.steps` 的 rejection。SDK 把它转成流内的 `error` part 交给
+ * `onError` 回调，而 flush 时另造一个**全新的、`cause` 为 undefined 的**
+ * `NoOutputGeneratedError({ message: 'No output generated. Check the stream
+ * for errors.' })` 去 reject 那些 promise（`sdk-contract.spec.ts` 的
+ * 「provider 请求级错误」一节钉住）。也就是说：**不接 `onError` 就永久拿不到
+ * 真实错误**，catch 到的那个对象里没有状态码、没有 responseBody、没有 cause。
+ *
+ * 后果不止是「日志难看」：`isContextOverflowError` 的输入是 `APICallError`，
+ * 拿这个包装壳去判恒为 false —— 上下文超限的就地补救因此整条形同虚设，而它的
+ * 单测用裸 `APICallError` 构造夹具，永远绿。线上的症状是那个会话每一次发言都
+ * 以同一条错误结束（见 `context-overflow.ts` 的大注释）。
+ */
+/** 单条错误文案进对话气泡时的长度上限——够定位，又不至于刷屏。 */
+const MAX_DETAIL_CHARS = 300;
+/**
+ * HTTP 状态码 → 「运维/成员拿了能干什么」。
+ *
+ * 只列**判据明确**的几档：这几个码在各家 provider 之间语义一致，且各自指向
+ * 一个具体的动作（充值 / 换 key / 等一会儿 / 改配置）。其余一律走兜底文案带上
+ * 原始状态码，不猜。
+ */
+const STATUS_HINTS = {
+    401: '模型服务商拒绝了鉴权，API Key 可能无效或已失效',
+    403: '模型服务商拒绝访问，当前 API Key 没有调用该模型的权限',
+    402: '模型服务商账户余额不足，请先充值',
+    404: '模型服务商没有这个模型，请检查模型配置里的模型名',
+    429: '模型服务商限流，请稍后重试',
+};
+/**
+ * 拿到这一步**真正**的失败原因。
+ *
+ * `streamError` 是调用方从 `streamText` 的 `onError` 里接住的那个错误。判据
+ * 刻意窄——**只有** `err` 是那个无信息的 `NoOutputGeneratedError` 壳、且这一步
+ * 确实记到过流内错误时才替换。abort 走的是另一条（SDK 用 `abortSignal.reason`
+ * reject），不会被这里误伤。
+ */
+export function unwrapInferenceError(err, streamError) {
+    if (streamError === undefined)
+        return err;
+    if (!NoOutputGeneratedError.isInstance(err))
+        return err;
+    return streamError;
+}
+/**
+ * 把错误说成一句用户能看懂、运维能定位的中文。
+ *
+ * 落进 `TurnResult.error`（→ `chat_message.metadata.error` 与零产出时的占位
+ * 气泡）。**始终带上服务商原话**：归一化只是给前面加一句「该干什么」，把原文
+ * 抹掉就等于让运维去猜。
+ */
+export function describeProviderError(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const detail = truncate(raw);
+    // 传输层断连：没有状态码、原话是 undici 的一个英文单词（`terminated`）。
+    // 单独说清楚——它不是服务商「拒绝」了什么，是连接半路没了，重试就是答案。
+    if (isTransportError(err)) {
+        return `与模型服务商的连接在响应中途断开（${truncate(describeErrorChain(err))}）`;
+    }
+    if (!APICallError.isInstance(err))
+        return detail;
+    const hint = err.statusCode ? STATUS_HINTS[err.statusCode] : undefined;
+    if (hint)
+        return `${hint}（服务商返回：${detail}）`;
+    return err.statusCode
+        ? `调用模型服务失败（HTTP ${err.statusCode}）：${detail}`
+        : `调用模型服务失败：${detail}`;
+}
+function truncate(text) {
+    const trimmed = text.trim();
+    return trimmed.length > MAX_DETAIL_CHARS
+        ? `${trimmed.slice(0, MAX_DETAIL_CHARS)}…`
+        : trimmed;
+}
+/**
+ * 传输层断连的判据：**响应流读到一半，连接没了**。
+ *
+ * 这一类错误不是 HTTP 错误——没有状态码，AI SDK 的请求级重试（只认
+ * `APICallError.isRetryable`，且只包着「发起请求」那一步）罩不到它；流式响应
+ * 里它经 `onError` 冒出来，原始形状是 Node 内置 HTTP 客户端 undici 的
+ * `TypeError: terminated`（对端关闭）或 `ECONNRESET`（连接被重置），真正的
+ * 原因挂在 `cause` 链上。2026-09-09 线上 deepseek 一次 555 秒的轮次就是这么
+ * 死的：前 5 步正常，第 6 次调模型读流中途 `terminated`，整轮 failed。
+ *
+ * **判据刻意窄**：只认「已经建立的连接中途断开」这一族（code 表 + undici 的几句
+ * 原话），不认连接建立阶段的失败（`fetch failed` / `ECONNREFUSED` / DNS）——
+ * 那些发生在请求阶段，SDK 自己已经退避重试过了，到这里的是它放弃之后的
+ * `RetryError`，再重试一轮只是把同一个死结多绕三圈。也**不认 abort**：用户按
+ * 停止走的是 `AbortError`，那是有人要它停，不是链路坏了。
+ *
+ * 顺着 `cause` 链看（最多 8 层）：undici 把 `SocketError` 包在 `TypeError`
+ * 里，只看最外层的 message 会漏掉 `ECONNRESET` 这种只在里层出现的 code。
+ */
+export function isTransportError(err) {
+    let cur = err;
+    for (let depth = 0; depth < 8 && cur instanceof Error; depth++) {
+        if (cur.name === 'AbortError')
+            return false;
+        const code = cur.code;
+        if (typeof code === 'string' && TRANSPORT_ERROR_CODES.has(code))
+            return true;
+        const message = cur.message;
+        if (TRANSPORT_ERROR_MESSAGES.some(re => re.test(message)))
+            return true;
+        cur = cur.cause;
+    }
+    return false;
+}
+const TRANSPORT_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ECONNABORTED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'UND_ERR_SOCKET',
+    'UND_ERR_ABORTED',
+    'UND_ERR_BODY_TIMEOUT',
+]);
+const TRANSPORT_ERROR_MESSAGES = [
+    /^terminated$/i,
+    /socket hang up/i,
+    /other side closed/i,
+];
+/**
+ * 把 `cause` 链摊平成一行给日志：`TypeError: terminated ← SocketError: other
+ * side closed [UND_ERR_SOCKET]`。`String(err)` 只有最外层那句，而对传输层错误
+ * 来说最外层恰恰是信息量最低的一层——线上那次日志里只剩一个 `terminated`，
+ * 连是对端正常关闭还是被重置都分不出来。
+ */
+export function describeErrorChain(err) {
+    const parts = [];
+    let cur = err;
+    for (let depth = 0; depth < 8; depth++) {
+        if (!(cur instanceof Error)) {
+            // 链尾不是 Error（有人 `throw 'x'` 或 `cause: {code}`）：原样带上，别让
+            // 它变成 '[object Object]'。
+            if (typeof cur === 'string')
+                parts.push(cur);
+            else if (cur !== undefined && cur !== null)
+                parts.push(JSON.stringify(cur));
+            break;
+        }
+        const code = cur.code;
+        const tag = typeof code === 'string' ? ` [${code}]` : '';
+        parts.push(`${cur.name}: ${cur.message}${tag}`);
+        cur = cur.cause;
+    }
+    return parts.join(' ← ');
+}
+//# sourceMappingURL=provider-error.js.map

package/dist/turn/provider-error.js.map

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

package/dist/turn/tool-input-preview.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 工具入参流式构建的**内容预览器**。
+ *
+ * 与 `tool-input-progress.ts` 分工：那条 tracker 答「写了多少」（字数，
+ * 不看内容），这条答「写了什么」——只对白名单工具实时抽出它入参里那个正文
+ * 字段（`Write.content`）的累计前缀，外加解析完整了的 `path`，供对话页的稿栏
+ * 边写边显示文件名与正文。
+ *
+ * 两个 tracker 各管一条事件（`tool-input-progress` / `tool-input-preview`），
+ * 互不知道对方；`chunk-projection.ts` 在同一处 `tool-input-delta` 分支里
+ * 各喂一遍。
+ *
+ * ## 成本（这一条决定了下面两道闸的形状）
+ *
+ * 每次 `delta` 都得**从头**重扫一遍累计的 `raw` 才能抽出字段值
+ * （`extractJsonStringField` 是线性扫描，没有可续跑的状态：转义与代理对的
+ * 收尾判定依赖上下文）。模型吐一篇长文约 120 块入参增量，若每块都扫一遍
+ * 就是 O(n²) 的字符比对，且每帧还要把整段前缀再发一次。
+ *
+ * 两道闸把它压回可接受：
+ * 1. **扫描前先看 `raw` 涨了多少**——解码后的字符数**恒不大于**原始 JSON 的
+ *    字符数（转义只会更长、代理对只会更多），所以「raw 涨的还不够一个阈值」
+ *    是「正文涨的也不够」的**必要条件**，此时连扫都不必扫。唯一例外是 `path`
+ *    还没解析完整那一段：第一帧必须尽早带上路径（稿栏靠它先开栏显示文件名），
+ *    那几块一律照扫。
+ * 2. **阈值随正文长度自适应**（`previewThreshold`）：短文里每 80 码点发一条
+ *    才看得出「在写」；长文里正文本身已经几千字，再按 80 发就是每帧重发一份
+ *    越来越大的全量前缀。载荷语义仍是**累计前缀**（幂等，断线重放/去重下不会
+ *    拼错），只是发得更疏。
+ *
+ * 零依赖纯函数式实现，同一套单测风格（本仓既有做法：`tool-input-progress.ts`）。
+ */
+/**
+ * 阈值下限，也是短正文期间的实际阈值：每积累这么多字符发一条预览。
+ *
+ * 按「界面上正文多久长一截」定：模型出中文大约 100+ 字符/秒，80 约等于每秒
+ * 一次。再密只是徒增事件（每条都带全量前缀），再疏就开始像卡住了。
+ */
+export declare const TOOL_INPUT_PREVIEW_CHARS = 80;
+/**
+ * 阈值上限。一篇 8000 字的稿子按 400 发也有 20 帧，够看出它在长；再放宽就
+ * 变成「写了半天才蹦一大段」。
+ */
+export declare const TOOL_INPUT_PREVIEW_CHARS_MAX = 400;
+/**
+ * 已经发出 `chars` 个字符之后，下一条预览要等正文再涨多少。
+ *
+ * `chars / 8` 意味着「每帧最多把正文推进八分之一」——发出的总字节量随正文
+ * 长度线性（而不是平方）增长，界面上的推进感又与正文长度无关（短文每秒一
+ * 帧、长文每几秒一大段，都是「一直在长」）。
+ *
+ * @param floor 阈值下限，默认 `TOOL_INPUT_PREVIEW_CHARS`；测试用它把节流拨快。
+ */
+export declare function previewThreshold(chars: number, floor?: number): number;
+/**
+ * 白名单：只有登记在这里的工具才会被追踪，且只认这两个字段名。
+ *
+ * `path` 用来给稿栏定位文件；`text` 是要显示的正文字段，**为 `null` 表示这个
+ * 工具没有可预览的正文**——`Edit` 的入参是替换对（`old_string`/`new_string`）
+ * 而不是整篇，半截的替换对画不出任何东西。它仍然登记在这里，是因为稿栏需要
+ * 在 `Edit` 落盘之前就知道「agent 正在改哪份文件」（栏头显示「生成改动中」，
+ * 而不是等几十秒后才跳出一份改好的稿）。
+ */
+export declare const TOOL_INPUT_PREVIEW_FIELDS: Record<string, {
+    path: string;
+    text: string | null;
+}>;
+export interface ToolInputPreviewEvent {
+    toolCallId: string;
+    toolName: string;
+    /** 只有 `path` 字段解析**完整**了才不是 null（首次完整立刻发一条）。 */
+    path: string | null;
+    /** 正文字段的累计前缀（可能是 `''`；无正文字段的工具恒 `''`）。 */
+    text: string;
+    /** 至此 `text` 的码点数（与 `tool-input-progress` 同一判据）。 */
+    chars: number;
+}
+export interface ToolInputPreviewTracker {
+    /** 模型开始吐某次调用的参数。不在白名单的工具直接忽略，不建账。 */
+    start(toolCallId: string, toolName: string): void;
+    /**
+     * 收到一块入参增量。返回非 null 表示「该发一条预览了」。
+     *
+     * **未 `start` 过（或起手时就不在白名单）的 toolCallId 一律返回 null**。
+     */
+    delta(toolCallId: string, text: string): ToolInputPreviewEvent | null;
+    /** 这次调用的参数收齐了，丢掉它的累计。 */
+    done(toolCallId: string): void;
+}
+export declare function createToolInputPreviewTracker(fields?: Record<string, {
+    path: string;
+    text: string | null;
+}>, thresholdChars?: number): ToolInputPreviewTracker;
+//# sourceMappingURL=tool-input-preview.d.ts.map

package/dist/turn/tool-input-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input-preview.d.ts","sourceRoot":"","sources":["../../src/turn/tool-input-preview.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAiC,GACvC,MAAM,CAKR;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAC5C,MAAM,EACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAItC,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,qCAAqC;IACrC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD;;;;OAIG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAAC;IACtE,yBAAyB;IACzB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAOD,wBAAgB,6BAA6B,CAC3C,MAAM,GAAE,MAAM,CACZ,MAAM,EACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CACV,EAC7B,cAAc,GAAE,MAAiC,GAChD,uBAAuB,CAsGzB"}

package/dist/turn/tool-input-preview.js

@@ -0,0 +1,143 @@
+import { extractJsonStringField } from './json-string-field.js';
+/**
+ * 工具入参流式构建的**内容预览器**。
+ *
+ * 与 `tool-input-progress.ts` 分工：那条 tracker 答「写了多少」（字数，
+ * 不看内容），这条答「写了什么」——只对白名单工具实时抽出它入参里那个正文
+ * 字段（`Write.content`）的累计前缀，外加解析完整了的 `path`，供对话页的稿栏
+ * 边写边显示文件名与正文。
+ *
+ * 两个 tracker 各管一条事件（`tool-input-progress` / `tool-input-preview`），
+ * 互不知道对方；`chunk-projection.ts` 在同一处 `tool-input-delta` 分支里
+ * 各喂一遍。
+ *
+ * ## 成本（这一条决定了下面两道闸的形状）
+ *
+ * 每次 `delta` 都得**从头**重扫一遍累计的 `raw` 才能抽出字段值
+ * （`extractJsonStringField` 是线性扫描，没有可续跑的状态：转义与代理对的
+ * 收尾判定依赖上下文）。模型吐一篇长文约 120 块入参增量，若每块都扫一遍
+ * 就是 O(n²) 的字符比对，且每帧还要把整段前缀再发一次。
+ *
+ * 两道闸把它压回可接受：
+ * 1. **扫描前先看 `raw` 涨了多少**——解码后的字符数**恒不大于**原始 JSON 的
+ *    字符数（转义只会更长、代理对只会更多），所以「raw 涨的还不够一个阈值」
+ *    是「正文涨的也不够」的**必要条件**，此时连扫都不必扫。唯一例外是 `path`
+ *    还没解析完整那一段：第一帧必须尽早带上路径（稿栏靠它先开栏显示文件名），
+ *    那几块一律照扫。
+ * 2. **阈值随正文长度自适应**（`previewThreshold`）：短文里每 80 码点发一条
+ *    才看得出「在写」；长文里正文本身已经几千字，再按 80 发就是每帧重发一份
+ *    越来越大的全量前缀。载荷语义仍是**累计前缀**（幂等，断线重放/去重下不会
+ *    拼错），只是发得更疏。
+ *
+ * 零依赖纯函数式实现，同一套单测风格（本仓既有做法：`tool-input-progress.ts`）。
+ */
+/**
+ * 阈值下限，也是短正文期间的实际阈值：每积累这么多字符发一条预览。
+ *
+ * 按「界面上正文多久长一截」定：模型出中文大约 100+ 字符/秒，80 约等于每秒
+ * 一次。再密只是徒增事件（每条都带全量前缀），再疏就开始像卡住了。
+ */
+export const TOOL_INPUT_PREVIEW_CHARS = 80;
+/**
+ * 阈值上限。一篇 8000 字的稿子按 400 发也有 20 帧，够看出它在长；再放宽就
+ * 变成「写了半天才蹦一大段」。
+ */
+export const TOOL_INPUT_PREVIEW_CHARS_MAX = 400;
+/**
+ * 已经发出 `chars` 个字符之后，下一条预览要等正文再涨多少。
+ *
+ * `chars / 8` 意味着「每帧最多把正文推进八分之一」——发出的总字节量随正文
+ * 长度线性（而不是平方）增长，界面上的推进感又与正文长度无关（短文每秒一
+ * 帧、长文每几秒一大段，都是「一直在长」）。
+ *
+ * @param floor 阈值下限，默认 `TOOL_INPUT_PREVIEW_CHARS`；测试用它把节流拨快。
+ */
+export function previewThreshold(chars, floor = TOOL_INPUT_PREVIEW_CHARS) {
+    return Math.max(floor, Math.min(Math.floor(chars / 8), TOOL_INPUT_PREVIEW_CHARS_MAX));
+}
+/**
+ * 白名单：只有登记在这里的工具才会被追踪，且只认这两个字段名。
+ *
+ * `path` 用来给稿栏定位文件；`text` 是要显示的正文字段，**为 `null` 表示这个
+ * 工具没有可预览的正文**——`Edit` 的入参是替换对（`old_string`/`new_string`）
+ * 而不是整篇，半截的替换对画不出任何东西。它仍然登记在这里，是因为稿栏需要
+ * 在 `Edit` 落盘之前就知道「agent 正在改哪份文件」（栏头显示「生成改动中」，
+ * 而不是等几十秒后才跳出一份改好的稿）。
+ */
+export const TOOL_INPUT_PREVIEW_FIELDS = {
+    Write: { path: 'path', text: 'content' },
+    Edit: { path: 'path', text: null },
+};
+/** 按码点数，不是 UTF-16 code unit —— 与 tool-input-progress 同一判据。 */
+function countCodePoints(text) {
+    return Array.from(text).length;
+}
+export function createToolInputPreviewTracker(fields = TOOL_INPUT_PREVIEW_FIELDS, thresholdChars = TOOL_INPUT_PREVIEW_CHARS) {
+    const entries = new Map();
+    return {
+        start(toolCallId, toolName) {
+            const field = fields[toolName];
+            if (field === undefined)
+                return; // 不在白名单，不建账——delta 恒 null
+            entries.set(toolCallId, {
+                toolName,
+                pathKey: field.path,
+                textKey: field.text,
+                raw: '',
+                rawChars: 0,
+                path: null,
+                emittedChars: 0,
+                emittedRawChars: 0,
+            });
+        },
+        delta(toolCallId, text) {
+            const e = entries.get(toolCallId);
+            if (e === undefined)
+                return null;
+            e.raw += text;
+            e.rawChars += countCodePoints(text);
+            // `path` 一旦完整就不会再变（同一个 JSON 里只有一个顶层 `path`），不必
+            // 重扫；而它还没完整时**每块都要扫**——第一帧要尽快把路径带出去。
+            if (e.path === null) {
+                const pathResult = extractJsonStringField(e.raw, e.pathKey);
+                // 路径都还没齐，正文更不可能过阈值（正文在 JSON 里排在后面）。
+                if (pathResult === null || !pathResult.complete)
+                    return null;
+                e.path = pathResult.value;
+                // 「首次拿到完整 path」是独立于字数阈值的触发点——稿栏靠它在正文
+                // 到来之前先打开并显示文件名，晚了就是「先写了半天字才冒出标题」。
+                // 正文多半还是空串，但同一块里就带上了正文时也要如实发出去。
+                const seed = readText(e);
+                return emit(e, toolCallId, seed.text, seed.chars);
+            }
+            // 没有正文字段的工具（`Edit`）：路径那一条发完就再没有可发的了。
+            if (e.textKey === null)
+                return null;
+            // 见头注释「成本」①：raw 涨得还不够一个阈值 → 正文必然也不够，不扫。
+            const threshold = previewThreshold(e.emittedChars, thresholdChars);
+            if (e.rawChars - e.emittedRawChars < threshold)
+                return null;
+            const next = readText(e);
+            if (next.chars - e.emittedChars < threshold)
+                return null;
+            return emit(e, toolCallId, next.text, next.chars);
+        },
+        done(toolCallId) {
+            entries.delete(toolCallId);
+        },
+    };
+    /** 当前累计的正文前缀；无正文字段的工具恒 `('', 0)`。 */
+    function readText(e) {
+        if (e.textKey === null)
+            return { text: '', chars: 0 };
+        const result = extractJsonStringField(e.raw, e.textKey);
+        const text = result !== null ? result.value : '';
+        return { text, chars: countCodePoints(text) };
+    }
+    function emit(e, toolCallId, text, chars) {
+        e.emittedChars = chars;
+        e.emittedRawChars = e.rawChars;
+        return { toolCallId, toolName: e.toolName, path: e.path, text, chars };
+    }
+}
+//# sourceMappingURL=tool-input-preview.js.map

package/dist/turn/tool-input-preview.js.map

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

package/dist/turn/tool-input-progress.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 工具入参流式构建的**进度节流器**。
+ *
+ * **为什么需要它**：`emit('tool-call', …)` 发生在整个 step 的流被消费完之后
+ * （`runTurn` 里 `emit('text-end')` 之后那个 `for (const tc of toolCalls)`
+ * 循环），而模型吐这次调用参数的那段时间——写一篇长文时就是绝大部分时间——
+ * 界面上一片死寂：`tool-input-delta` 在 depth 0 从不投影，用户看到的是一个
+ * 停住的界面，只能当它卡了。
+ *
+ * **为什么不直接把 `tool-input-delta` 投出去**：那条流是**有消费方的**——
+ * `parts-from-events.ts` 的 abort 兜底靠累积它的原始 JSON 片段，在中断时重建
+ * 半截的 tool-call。它必须保持逐块、不节流、原样。而它作为 UI 信号又太碎
+ * （实测一次调用约 120 块），且投影层根本没有 `delta` 字段可透。
+ *
+ * 所以这里另发一条**只服务于界面**的进度事件：累积到一定字数才发一次，
+ * 载荷是「已经收到多少字符」而不是内容本身。
+ *
+ * 零依赖纯函数，便于单测（本仓既有做法：`running-nodes.ts`/`autosave-scheduler.ts`）。
+ */
+/**
+ * 每积累这么多字符发一条进度。
+ *
+ * 按「界面上那个数字多久动一次」定：模型出中文大约 100+ 字符/秒，故 120 约等于
+ * 每秒一次。再密只是徒增事件，再疏就又开始像卡住了。
+ */
+export declare const TOOL_INPUT_PROGRESS_CHARS = 120;
+export interface ToolInputProgressEvent {
+    toolCallId: string;
+    toolName: string;
+    /** 至此累计收到的入参字符数（不是内容）。 */
+    chars: number;
+}
+export interface ToolInputProgressTracker {
+    /** 模型开始吐某次调用的参数。 */
+    start(toolCallId: string, toolName: string): void;
+    /**
+     * 收到一块入参增量。返回非 null 表示「该发一条进度了」。
+     *
+     * **未 `start` 过的 toolCallId 一律返回 null**：没有 `tool-input-start` 就
+     * 没有 toolName，发一条不知道是什么工具的进度，界面上无从落位。
+     */
+    delta(toolCallId: string, text: string): ToolInputProgressEvent | null;
+    /** 这次调用的参数收齐了，丢掉它的累计（一个 turn 可以跑很多步）。 */
+    done(toolCallId: string): void;
+}
+export declare function createToolInputProgressTracker(thresholdChars?: number): ToolInputProgressTracker;
+//# sourceMappingURL=tool-input-progress.d.ts.map

package/dist/turn/tool-input-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input-progress.d.ts","sourceRoot":"","sources":["../../src/turn/tool-input-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,oBAAoB;IACpB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CAAC;IACvE,yCAAyC;IACzC,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,8BAA8B,CAC5C,cAAc,GAAE,MAAkC,GACjD,wBAAwB,CAwB1B"}

package/dist/turn/tool-input-progress.js

@@ -0,0 +1,50 @@
+/**
+ * 工具入参流式构建的**进度节流器**。
+ *
+ * **为什么需要它**：`emit('tool-call', …)` 发生在整个 step 的流被消费完之后
+ * （`runTurn` 里 `emit('text-end')` 之后那个 `for (const tc of toolCalls)`
+ * 循环），而模型吐这次调用参数的那段时间——写一篇长文时就是绝大部分时间——
+ * 界面上一片死寂：`tool-input-delta` 在 depth 0 从不投影，用户看到的是一个
+ * 停住的界面，只能当它卡了。
+ *
+ * **为什么不直接把 `tool-input-delta` 投出去**：那条流是**有消费方的**——
+ * `parts-from-events.ts` 的 abort 兜底靠累积它的原始 JSON 片段，在中断时重建
+ * 半截的 tool-call。它必须保持逐块、不节流、原样。而它作为 UI 信号又太碎
+ * （实测一次调用约 120 块），且投影层根本没有 `delta` 字段可透。
+ *
+ * 所以这里另发一条**只服务于界面**的进度事件：累积到一定字数才发一次，
+ * 载荷是「已经收到多少字符」而不是内容本身。
+ *
+ * 零依赖纯函数，便于单测（本仓既有做法：`running-nodes.ts`/`autosave-scheduler.ts`）。
+ */
+/**
+ * 每积累这么多字符发一条进度。
+ *
+ * 按「界面上那个数字多久动一次」定：模型出中文大约 100+ 字符/秒，故 120 约等于
+ * 每秒一次。再密只是徒增事件，再疏就又开始像卡住了。
+ */
+export const TOOL_INPUT_PROGRESS_CHARS = 120;
+export function createToolInputProgressTracker(thresholdChars = TOOL_INPUT_PROGRESS_CHARS) {
+    const entries = new Map();
+    return {
+        start(toolCallId, toolName) {
+            entries.set(toolCallId, { toolName, chars: 0, emittedAt: 0 });
+        },
+        delta(toolCallId, text) {
+            const e = entries.get(toolCallId);
+            if (e === undefined)
+                return null;
+            // 按**码点**数，不是 UTF-16 code unit：中文一字一码点，而 `.length`
+            // 对 emoji 之类会翻倍——这个数字是给人看的「已经写了多少字」。
+            e.chars += Array.from(text).length;
+            if (e.chars - e.emittedAt < thresholdChars)
+                return null;
+            e.emittedAt = e.chars;
+            return { toolCallId, toolName: e.toolName, chars: e.chars };
+        },
+        done(toolCallId) {
+            entries.delete(toolCallId);
+        },
+    };
+}
+//# sourceMappingURL=tool-input-progress.js.map

package/dist/turn/tool-input-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input-progress.js","sourceRoot":"","sources":["../../src/turn/tool-input-progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAuB7C,MAAM,UAAU,8BAA8B,CAC5C,iBAAyB,yBAAyB;IAElD,MAAM,OAAO,GAAG,IAAI,GAAG,EAGpB,CAAC;IAEJ,OAAO;QACL,KAAK,CAAC,UAAU,EAAE,QAAQ;YACxB,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,KAAK,CAAC,UAAU,EAAE,IAAI;YACpB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACjC,mDAAmD;YACnD,qCAAqC;YACrC,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YACnC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS,GAAG,cAAc;gBAAE,OAAO,IAAI,CAAC;YACxD,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC;YACtB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,UAAU;YACb,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}