@migor/agentia 0.7.2 → 0.8.1

package/dist/engine/stop-reason.js

@@ -0,0 +1,76 @@
+import { textOf } from './text.js';
+/**
+ * —— 终止/边界分支（每个都给出终止结论，退出循环不再兜底改判）——
+ * 五种已知 stop_reason 各有归宿；剩余形态按「有没有可执行块」区分：
+ * 畸形 tool_use（块为空）与框架不认识的 stop_reason。
+ */
+export function resolveStopReason(message, maxTokens) {
+    if (message.stop_reason === 'end_turn') {
+        return { kind: 'finish', stopReason: 'end_turn', finalText: textOf(message) };
+    }
+    if (message.stop_reason === 'refusal') {
+        return {
+            kind: 'finish',
+            stopReason: 'refusal',
+            finalText: textOf(message),
+            error: { type: 'refusal', message: 'model refused the request', retryable: false },
+        };
+    }
+    if (message.stop_reason === 'max_tokens') {
+        // 与 budget_exceeded / refusal 同口径：非正常收尾都带结构化 error（进 run 根 span），
+        // 否则 trace 里这类 run「失败却没有原因」
+        return {
+            kind: 'finish',
+            stopReason: 'max_tokens',
+            finalText: textOf(message),
+            error: {
+                type: 'max_tokens',
+                message: `模型输出触顶被截断（max_tokens=${maxTokens}）`,
+                retryable: false,
+            },
+        };
+    }
+    if (message.stop_reason === 'pause_turn') {
+        // 无 server tools 时正常不会到；避免无限循环直接停
+        return {
+            kind: 'finish',
+            stopReason: 'pause_turn',
+            finalText: textOf(message),
+            error: {
+                type: 'pause_turn',
+                message: '模型返回 pause_turn（无 server tools 的场景不应出现），防死循环直接收尾',
+                retryable: false,
+            },
+        };
+    }
+    if (message.stop_reason === 'stop_sequence') {
+        // 命中 stop 序列 = 正常收尾（与 end_turn 同类），不是失败
+        return { kind: 'finish', stopReason: 'stop_sequence', finalText: textOf(message) };
+    }
+    const toolUses = message.content.filter((b) => b.type === 'tool_use');
+    if (toolUses.length === 0) {
+        // 到这里的剩余 stop_reason 不会产生可执行块，防死循环直接停：
+        // 'tool_use' 但块为空（畸形响应）与「本框架不认识的 stop_reason」区分开。
+        //
+        // **两种都属非正常收尾，都必须挂结构化 error** —— engine/loop.ts 的不变量是
+        // 「非正常收尾都带结构化 error」（与 budget_exceeded / refusal / max_iterations 同口径）。
+        // 此前只有 unknown_stop_reason 带 error，tool_use_no_blocks 不带：run 以
+        // status:'failed' 收尾、result.error 却是 undefined，HTTP body 与任务记录里
+        // 看不出「为什么失败」，只能看到一句 stopReason 字符串。
+        const stopReason = message.stop_reason === 'tool_use' ? 'tool_use_no_blocks' : 'unknown_stop_reason';
+        return {
+            kind: 'finish',
+            stopReason,
+            finalText: textOf(message),
+            error: {
+                type: 'agent_error',
+                message: stopReason === 'tool_use_no_blocks'
+                    ? '模型以 stop_reason=tool_use 收尾，但响应里没有任何 tool_use 块（畸形响应）'
+                    : `模型返回了未识别的 stop_reason: ${String(message.stop_reason)}`,
+                retryable: false,
+            },
+        };
+    }
+    return { kind: 'tools', toolUses };
+}
+//# sourceMappingURL=stop-reason.js.map

package/dist/engine/stop-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-reason.js","sourceRoot":"","sources":["../../src/engine/stop-reason.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAMnC;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,SAAiB;IACnE,IAAI,OAAO,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,2BAA2B,EAAE,SAAS,EAAE,KAAK,EAAE;SACnF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;QACzC,kEAAkE;QAClE,4BAA4B;QAC5B,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,YAAY;YACxB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE;gBACL,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,wBAAwB,SAAS,GAAG;gBAC7C,SAAS,EAAE,KAAK;aACjB;SACF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;QACzC,kCAAkC;QAClC,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,YAAY;YACxB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE;gBACL,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,kDAAkD;gBAC3D,SAAS,EAAE,KAAK;aACjB;SACF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,eAAe,EAAE,CAAC;QAC5C,wCAAwC;QACxC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IACrF,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IACzF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,uCAAuC;QACvC,kDAAkD;QAClD,EAAE;QACF,sDAAsD;QACtD,wEAAwE;QACxE,+DAA+D;QAC/D,gEAAgE;QAChE,oCAAoC;QACpC,MAAM,UAAU,GACd,OAAO,CAAC,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,qBAAqB,CAAC;QACpF,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,UAAU;YACV,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE;gBACL,IAAI,EAAE,aAAa;gBACnB,OAAO,EACL,UAAU,KAAK,oBAAoB;oBACjC,CAAC,CAAC,uDAAuD;oBACzD,CAAC,CAAC,0BAA0B,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE;gBAC7D,SAAS,EAAE,KAAK;aACjB;SACF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACrC,CAAC"}

package/dist/engine/text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 引擎侧的文本读取口径（**单源**）：多文本块用 `\n` 连接。
+ *
+ * 从 turn.ts 外移（2026-09-20，turn 拆分第一步）：`stop-reason.ts` 也要用这个口径，而它若
+ * 继续从 turn.ts 取、turn.ts 又要 import stop-reason.ts ⇒ **成环**（分层守卫禁环）。这一层很薄，
+ * 但「引擎用 `\n`、适配器用 `''`」这个选择必须只有一处 —— 见 core/text.ts 头注。
+ */
+import type { Message } from '../core/message.js';
+/** 取消息里的全部文本块（引擎口径：多块按 `\n` 连接，保住模型的分段输出） */
+export declare function textOf(message: Message): string;

package/dist/engine/text.js

@@ -0,0 +1,6 @@
+import { textOf as coreTextOf } from '../core/text.js';
+/** 取消息里的全部文本块（引擎口径：多块按 `\n` 连接，保住模型的分段输出） */
+export function textOf(message) {
+    return coreTextOf(message, '\n');
+}
+//# sourceMappingURL=text.js.map

package/dist/engine/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/engine/text.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEvD,6CAA6C;AAC7C,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/engine/tool-context.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 单工具执行的**上下文装配**（纯）：把引擎侧的取值摊成交给工具的 `ToolRunContext`。
+ *
+ * 从 turn.ts 的 executeOneTool 里外移（2026-09-20，turn 拆分第三步）。这段全部是搬运，但它
+ * **不是无害的样板**：八处条件展开里每一处都对应一个「漏了就静默降级」的守卫 ——
+ * 价格覆盖漏了 ⇒ 子 agent 用同一模型退化成「未定价」、`maxCostUsd` 静默失效；预算/超时上限
+ * 漏了 ⇒ 护栏在子循环里离线；`abandoned` 漏了 ⇒ 超时后没人通知工具「别等了」。
+ *
+ * 判定用哪一种是**语义**，不是风格，单测逐项钉住：
+ * - `signal` / `priceOverrides` / `onUnpricedModel` 用**真值**判定；
+ * - `maxEventChars` / `maxTotalTokens` / `maxCostUsd` / `toolTimeoutMs` 用**非空**判定 ——
+ *   因为 `false`（不截断）与 `0`（不限/不超时）都是**有意义的值**，真值判定会把它们吃掉；
+ * - `approval` 用 `!== undefined`：批/拒的决定要原样带给工具体（审计与分级授权用）。
+ *
+ * 纯的边界：只做取值搬运，不读 ctx、不碰 recorder、不执行工具。
+ */
+import type { SpanId } from '../core/trace.js';
+import type { RecorderBackend, ToolRunContext } from '../core/tool.js';
+export declare function buildToolRunContext(opts: {
+    client: ToolRunContext['client'];
+    recorder: RecorderBackend;
+    parentSpanId: SpanId;
+    abandoned: AbortSignal;
+    signal?: ToolRunContext['signal'];
+    priceOverrides?: ToolRunContext['priceOverrides'];
+    onUnpricedModel?: ToolRunContext['onUnpricedModel'];
+    maxEventChars?: ToolRunContext['maxEventChars'];
+    maxTotalTokens?: ToolRunContext['maxTotalTokens'];
+    maxCostUsd?: ToolRunContext['maxCostUsd'];
+    toolTimeoutMs?: ToolRunContext['toolTimeoutMs'];
+    approval?: ToolRunContext['approval'];
+}): ToolRunContext;

package/dist/engine/tool-context.js

@@ -0,0 +1,18 @@
+export function buildToolRunContext(opts) {
+    const { client, recorder, parentSpanId, abandoned, signal, priceOverrides, onUnpricedModel, maxEventChars, maxTotalTokens, maxCostUsd, toolTimeoutMs, approval, } = opts;
+    return {
+        client,
+        recorder,
+        parentSpanId,
+        abandoned,
+        ...(signal ? { signal } : {}),
+        ...(priceOverrides ? { priceOverrides } : {}),
+        ...(onUnpricedModel ? { onUnpricedModel } : {}),
+        ...(maxEventChars != null ? { maxEventChars } : {}),
+        ...(maxTotalTokens != null ? { maxTotalTokens } : {}),
+        ...(maxCostUsd != null ? { maxCostUsd } : {}),
+        ...(toolTimeoutMs != null ? { toolTimeoutMs } : {}),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}
+//# sourceMappingURL=tool-context.js.map

package/dist/engine/tool-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/engine/tool-context.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,mBAAmB,CAAC,IAanC;IACC,MAAM,EACJ,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,MAAM,EACN,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,QAAQ,GACT,GAAG,IAAI,CAAC;IACT,OAAO;QACL,MAAM;QACN,QAAQ;QACR,YAAY;QACZ,SAAS;QACT,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/engine/tool-events.d.ts

@@ -0,0 +1,42 @@
+import type { ToolResultBlockParam, ToolUseBlock } from '../core/message.js';
+/**
+ * 事件正文（tool.input / tool.output 的 body）缺省截断上限（字符）。
+ *
+ * 与「入参」/「成功出参」/「失败出参」三类一一对应：失败出参减半是为了让
+ * 「哪个工具老超时」这类判断在**一行**里看得完（正文本身多为一句错误摘要，
+ * 1000 已远超常见长度，只有工具把异常里的长上下文一起吐回来时才会触发）。
+ */
+export declare const DEFAULT_EVENT_CHARS = 2000;
+export declare const DEFAULT_ERROR_EVENT_CHARS = 1000;
+/** 工具失败归类（进 `tool.output` 事件）。`denied` 是**人**的决定，不是工具故障，故单列一类账 */
+export type ToolErrorKind = 'invalid_input' | 'timeout' | 'threw' | 'unknown_tool' | 'denied';
+export interface ToolInputPayload {
+    tool: string;
+    tool_use_id: string;
+    input: string;
+}
+/** `tool.input` 事件体：入参按 `maxEventChars`（缺省 2000）截断 */
+export declare function toolInputPayload(use: ToolUseBlock, maxEventChars?: number | false): ToolInputPayload;
+export interface ToolOutputPayload {
+    tool: string;
+    tool_use_id: string;
+    ok: boolean;
+    durationMs: number;
+    errorKind?: ToolErrorKind;
+    content: string;
+}
+/**
+ * `tool.output` 事件体：耗时四路径都记、失败出参用**更小**的截断上限、`errorKind` 有值才在场。
+ * `now` 由调用点传入（便于单测固定时钟；时钟回拨时 durationMs 钳到 0）。
+ */
+export declare function toolOutputPayload(opts: {
+    use: ToolUseBlock;
+    ok: boolean;
+    errorKind?: ToolErrorKind | undefined;
+    startedAt: number;
+    now: number;
+    content: unknown;
+    maxEventChars?: number | false | undefined;
+}): ToolOutputPayload;
+/** 回给模型的 tool_result 块：`is_error` 与 `ok` 互为反，content 一律走 stringifySafe */
+export declare function toolResultBlock(use: ToolUseBlock, ok: boolean, content: unknown): ToolResultBlockParam;

package/dist/engine/tool-events.js

@@ -0,0 +1,64 @@
+/**
+ * 单工具执行的**记账面**（纯）：`tool.input` / `tool.output` 两个事件体 + 回给模型的 tool_result 块。
+ *
+ * 从 turn.ts 的 executeOneTool 里外移（2026-09-20，turn 拆分第四步）。这里的每一条都是**口径**，
+ * 混在执行流程里只能透过 trace 的观感去猜：
+ * - **截断上限不对称**：失败出参用更小的上限（1000 vs 2000）—— 理由见常量注释；
+ * - **`maxEventChars: false` = 不截断**（调试期开全文），必须原样透传而不是回落默认；
+ * - **`durationMs` 覆盖四条路径**（成功 / 失败 / 超时 / 入参被拒）且**非负** —— 时钟回拨时不出现负数；
+ * - **`errorKind` 只在有值时在场**：成功事件不该带一个 `undefined` 的键。
+ *
+ * 纯的边界：只拼装数据，不读 ctx、不碰 recorder、不执行工具。
+ */
+import { stringifySafe, truncateWithMark } from '../core/json.js';
+/**
+ * 事件正文（tool.input / tool.output 的 body）缺省截断上限（字符）。
+ *
+ * 与「入参」/「成功出参」/「失败出参」三类一一对应：失败出参减半是为了让
+ * 「哪个工具老超时」这类判断在**一行**里看得完（正文本身多为一句错误摘要，
+ * 1000 已远超常见长度，只有工具把异常里的长上下文一起吐回来时才会触发）。
+ */
+export const DEFAULT_EVENT_CHARS = 2_000;
+export const DEFAULT_ERROR_EVENT_CHARS = 1_000;
+/**
+ * 截断到上限字符，超长加省略标记（标记格式由 core/json.ts 的 truncateWithMark 单一提供）。
+ * `n === false` 表示**不截断**（`RunAgentOptions.maxEventChars: false`）——
+ * 传数字时三类事件共用同一个上限，缺省值由调用点给出。
+ */
+function limit(x, n) {
+    const s = stringifySafe(x);
+    return n === false ? s : truncateWithMark(s, n);
+}
+/** `tool.input` 事件体：入参按 `maxEventChars`（缺省 2000）截断 */
+export function toolInputPayload(use, maxEventChars) {
+    return {
+        tool: use.name,
+        tool_use_id: use.id,
+        input: limit(use.input, maxEventChars ?? DEFAULT_EVENT_CHARS),
+    };
+}
+/**
+ * `tool.output` 事件体：耗时四路径都记、失败出参用**更小**的截断上限、`errorKind` 有值才在场。
+ * `now` 由调用点传入（便于单测固定时钟；时钟回拨时 durationMs 钳到 0）。
+ */
+export function toolOutputPayload(opts) {
+    const { use, ok, errorKind, startedAt, now, content, maxEventChars } = opts;
+    return {
+        tool: use.name,
+        tool_use_id: use.id,
+        ok,
+        durationMs: Math.max(0, now - startedAt),
+        ...(errorKind ? { errorKind } : {}),
+        content: limit(content, maxEventChars ?? (ok ? DEFAULT_EVENT_CHARS : DEFAULT_ERROR_EVENT_CHARS)),
+    };
+}
+/** 回给模型的 tool_result 块：`is_error` 与 `ok` 互为反，content 一律走 stringifySafe */
+export function toolResultBlock(use, ok, content) {
+    return {
+        type: 'tool_result',
+        tool_use_id: use.id,
+        content: stringifySafe(content),
+        is_error: !ok,
+    };
+}
+//# sourceMappingURL=tool-events.js.map

package/dist/engine/tool-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-events.js","sourceRoot":"","sources":["../../src/engine/tool-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGlE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAK/C;;;;GAIG;AACH,SAAS,KAAK,CAAC,CAAU,EAAE,CAAiB;IAC1C,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClD,CAAC;AAQD,sDAAsD;AACtD,MAAM,UAAU,gBAAgB,CAC9B,GAAiB,EACjB,aAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,EAAE;QACnB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,IAAI,mBAAmB,CAAC;KAC9D,CAAC;AACJ,CAAC;AAWD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAQjC;IACC,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAC5E,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,EAAE;QACnB,EAAE;QACF,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,SAAS,CAAC;QACxC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,KAAK,CACZ,OAAO,EACP,aAAa,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CACxE;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAC7B,GAAiB,EACjB,EAAW,EACX,OAAgB;IAEhB,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,GAAG,CAAC,EAAE;QACnB,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC;QAC/B,QAAQ,EAAE,CAAC,EAAE;KACd,CAAC;AACJ,CAAC"}

package/dist/engine/turn-request.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 回合请求的**装配**（纯）：把引擎侧的取值摊成客户端 `messages.stream` 的入参。
+ *
+ * 从 turn.ts 的 streamTurn 里外移（2026-09-20，turn 拆分第二步）。这里没有一行逻辑算"难"，
+ * 但三处**条件展开**是容易写错的地方 —— **键在不在场是语义**：
+ * - `system` / `tools` / `signal` 缺省时**不带该键**（不是传 `undefined`、更不是空数组）：
+ *   适配器按「键是否在场」决定是否写进请求体，带一个空数组会被某些端点读成「声明了零个工具」；
+ * - `system: ''` 这种空值同样不带键（`!system` 判定）—— 与抽取前的行内写法逐字一致。
+ *
+ * 纯的边界：只做取值搬运，不读 ctx、不碰 recorder、不认识重试。
+ */
+import type { MessageParam, ToolParam } from '../core/message.js';
+import type { ModelClient } from '../core/tool.js';
+import type { SystemParam } from './types.js';
+type StreamParams = Parameters<ModelClient['messages']['stream']>[0];
+export declare function buildTurnRequest(opts: {
+    model: string;
+    maxTokens: number;
+    system?: SystemParam | undefined;
+    apiTools: ToolParam[];
+    messages: MessageParam[];
+    signal?: AbortSignal | undefined;
+}): StreamParams;
+export {};

package/dist/engine/turn-request.js

@@ -0,0 +1,12 @@
+export function buildTurnRequest(opts) {
+    const { model, maxTokens, system, apiTools, messages, signal } = opts;
+    return {
+        model,
+        max_tokens: maxTokens,
+        ...(system ? { system } : {}),
+        ...(apiTools.length ? { tools: apiTools } : {}),
+        messages,
+        ...(signal ? { signal } : {}),
+    };
+}
+//# sourceMappingURL=turn-request.js.map

package/dist/engine/turn-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-request.js","sourceRoot":"","sources":["../../src/engine/turn-request.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,gBAAgB,CAAC,IAOhC;IACC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtE,OAAO;QACL,KAAK;QACL,UAAU,EAAE,SAAS;QACrB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,QAAQ;QACR,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9B,CAAC;AACJ,CAAC"}

package/dist/engine/turn.d.ts

@@ -4,11 +4,12 @@
  * 分工：loop.ts 留入口与编排骨架（runAgent / runAgentScoped / agentLoop 本体 +
  * 缺省旋钮解析）；本文件装回合内部 —— 回合上下文装配（buildLoopContext）、
  * 回合入口检查（checkTurnEntry）、流式请求与重试（streamTurn）、回合记账
- * （recordTurnUsage）、stop_reason 分流（resolveStopReason）、工具执行
+ * （recordTurnUsage）、stop_reason 分流（已外移到 stop-reason.ts）、工具执行
  * （executeTurnTools / executeOneTool）。
  * 依赖方向单向：loop.ts → turn.ts（分层守卫禁环）；两侧共用的类型与 helper
- * （AgentLoopArgs / textOf / replaceMessages）在本文件做 module 级 export，供 loop.ts
- * 与测试 import —— 按仓库约定不进 src/index.ts（纯内部实现细节）。
+ * （AgentLoopArgs / replaceMessages）在本文件做 module 级 export，供 loop.ts
+ * 与测试 import —— 按仓库约定不进 src/index.ts（纯内部实现细节）。textOf 的
+ * 规范位置是 text.ts（loop.ts 与 stop-reason.ts 都从那儿取；回本文件取会成环）。
  */
 import type { Message, MessageParam, ToolParam, ToolResultBlockParam, ToolUseBlock } from '../core/message.js';
 import type { AgentTool, ApprovalDecision, JsonSchema, ModelClient, ModelPricing, RecorderBackend, SchemaType } from '../core/tool.js';
@@ -127,21 +128,6 @@ export declare function streamTurn<S extends JsonSchema>(ctx: LoopContext<S>): P
  */
 export declare function recordTurnUsage<S extends JsonSchema>(ctx: LoopContext<S>, turnId: SpanId, message: Message): void;
 /** 回合收尾分流：finish = 终止/边界分支（带 stopReason 与收尾文本）；tools = 还有工具要执行 */
-export type StopResolution = {
-    kind: 'finish';
-    stopReason: AgentStopReason;
-    finalText: string;
-    error?: SpanError;
-} | {
-    kind: 'tools';
-    toolUses: ToolUseBlock[];
-};
-/**
- * —— 终止/边界分支（每个都给出终止结论，退出循环不再兜底改判）——
- * 五种已知 stop_reason 各有归宿；剩余形态按「有没有可执行块」区分：
- * 畸形 tool_use（块为空）与框架不认识的 stop_reason。
- */
-export declare function resolveStopReason(message: Message, maxTokens: number): StopResolution;
 /**
  * 回合工具执行的结果：
  * - `executed`：全部执行完（results 与输入一一对应，顺序保持）；
@@ -168,15 +154,6 @@ export type TurnToolsOutcome = {
  * 永不需审批）与未知工具（走既有 unknown_tool 路径）。
  */
 export declare function executeTurnTools<S extends JsonSchema>(ctx: LoopContext<S>, turnId: SpanId, toolUses: ToolUseBlock[], overBudget: 'tokens' | 'cost' | null): Promise<TurnToolsOutcome>;
-/**
- * 取消息里的全部文本块（引擎侧口径：**多块按 `\n` 连接** —— 多文本块是模型分段的
- * 输出，拼成 `finalText` 要保住分段）。
- *
- * 实现单源在 `core/text.ts`（2026-09-17 去重）：两个适配器的「非流式回落路径」各有
- * 一份逐字相同的实现，只差连接符。这里保留同名包装，是为了让 loop.ts 与测试既有的
- * 大量调用点零改动，同时把「引擎用 `\n`」这个选择钉在一处。
- */
-export declare function textOf(message: Message): string;
 /**
  * 用 `next` 原地替换 `target` 的全部内容（保持数组引用不变 —— 循环各处持同一数组）。
  *