llm-api-gateway-cli 1.0.0

package/lib/agent.js

@@ -0,0 +1,607 @@
+/**
+ * 模式五 · 任务模式的 Agent 循环
+ *
+ * 一轮任务 = 反复「模型 → 工具 → 回填结果 → 再问模型」，直到模型不再要求调用工具。
+ *
+ * 写入类工具怎么处理由 run.mode 决定：
+ *   manual —— 挂起等用户批准（默认）；
+ *   auto   —— 直接执行，不再打断用户（界面仍逐条显示改了什么）；
+ *   plan   —— 只提供只读工具，先出计划、不动文件。
+ */
+
+import { availableTools, isWriteTool, isFileWriteTool, executeTool, describeCall, writePreview, TOOLS } from './tools.js';
+import { refreshMcpTools, mcpHeadersForChat, mcpToolSpecs } from './mcp.js';
+import { errorText, sessionBaggage } from './common.js';
+
+/**
+ * 单次任务最多几轮工具调用。这里数的是「模型轮次」，不是工具次数 ——
+ * 一轮里模型可以并行发多个调用，所以 8 轮 / 40 轮对真实任务来说都太紧（实测一次代码调研就用掉 8 轮 / 21 次调用）。
+ * 会话、任务、挂起态都已落盘，撞线后能带着全部历史接着跑，轮次上限只是「防跑飞」的兜底而非省钱闸门，
+ * 所以放宽到 100；真要收紧用 --max-steps / TASK_MAX_STEPS / config.json 的 maxSteps 覆盖。
+ * 撞到上限也不是「不许干活」：会额外走一轮收尾给出结论，并且页面给一个「继续执行」按钮接着干。
+ */
+const DEFAULT_MAX_STEPS = 100;
+const APPROVAL_TTL_MS = 60 * 60 * 1000; // 挂起态保留 60 分钟（落盘，刷新/重启都还在）
+const MAX_RUNS = 40;
+
+/** 上限可按请求覆盖（cfg.maxSteps），非法值一律回落到默认 */
+export function resolveMaxSteps(v) {
+  // 只接受数字或纯数字字符串：布尔值会被 Number() 悄悄变成 1（--max-steps 当成开关时踩过）
+  if (typeof v !== 'number' && typeof v !== 'string') return DEFAULT_MAX_STEPS;
+  if (typeof v === 'string' && !/^\s*\d+\s*$/.test(v)) return DEFAULT_MAX_STEPS;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_MAX_STEPS;
+}
+
+export const MODES = ['manual', 'auto', 'plan'];
+export const MODE_LABELS = { manual: '手动', auto: '自动', plan: '计划' };
+
+export function normalizeMode(mode) {
+  return MODES.includes(mode) ? mode : 'manual';
+}
+
+/** 计划模式只给只读工具 —— 模型拿不到写入工具，就没法动文件 */
+export function toolsForMode(mode) {
+  const list = availableTools(); // bash 未开启时这里就不带它，别让模型去试
+  return normalizeMode(mode) === 'plan' ? list.filter((t) => !isWriteTool(t.function.name)) : list;
+}
+
+/* ---------- 上游请求重试 ---------- */
+
+/** 只重试「再试一次有意义」的：限流、网关类错误、超时。4xx 业务错误重试纯属浪费 token */
+const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+const MAX_FETCH_ATTEMPTS = 3;
+
+const sleep = (ms, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(Object.assign(new Error('已中止'), { name: 'AbortError' }));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener?.(
+      'abort',
+      () => {
+        clearTimeout(t);
+        reject(Object.assign(new Error('已中止'), { name: 'AbortError' }));
+      },
+      { once: true },
+    );
+  });
+
+function backoffMs(attempt) {
+  const base = 300 * 2 ** attempt;
+  return base + Math.floor(Math.random() * 200); // 加抖动，避免多个请求同时重试又同时撞上
+}
+
+function retryAfterMs(resp) {
+  const raw = resp.headers?.get?.('retry-after');
+  if (!raw) return null;
+  const secs = Number(raw);
+  if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1000, 10000);
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.min(Math.max(at - Date.now(), 0), 10000) : null;
+}
+
+/**
+ * 带重试的 fetch。
+ *
+ * 关键前提：请求体是字符串（已经 JSON.stringify 过的），所以重发不会遇到「流已被消费」的问题。
+ * 中止信号必须原样生效 —— 用户按 Ctrl+C 时不能还在傻等退避。
+ */
+async function fetchWithRetry(url, init, { signal, attempts = MAX_FETCH_ATTEMPTS } = {}) {
+  let lastError = null;
+  for (let i = 0; i < attempts; i++) {
+    if (signal?.aborted) throw Object.assign(new Error('已中止'), { name: 'AbortError' });
+    try {
+      const resp = await fetch(url, init);
+      if (!RETRYABLE_STATUS.has(resp.status) || i === attempts - 1) return resp;
+      // 把响应体读掉，免得连接挂着；随后按 Retry-After（若有）或指数退避等待
+      try {
+        await resp.text();
+      } catch {
+        /* 忽略 */
+      }
+      await sleep(retryAfterMs(resp) ?? backoffMs(i), signal);
+    } catch (e) {
+      if (signal?.aborted || e?.name === 'AbortError') throw e;
+      lastError = e;
+      if (i === attempts - 1) throw e;
+      await sleep(backoffMs(i), signal);
+    }
+  }
+  throw lastError || new Error('请求失败');
+}
+
+/** 挂起态优先放内存；配了落盘的话，重启后还能从磁盘捞回来 */
+let persistence = null;
+
+/** 装上挂起态持久化（Web 用；CLI 不装就是纯内存，行为不变） */
+export function setRunPersistence(store) {
+  persistence = store;
+}
+
+const runs = new Map();
+
+export function pruneRuns() {
+  const now = Date.now();
+  for (const [id, run] of runs) if (now - run.touchedAt > APPROVAL_TTL_MS) runs.delete(id);
+  while (runs.size > MAX_RUNS) runs.delete(runs.keys().next().value); // Map 保持插入序，淘汰最早的
+  // 磁盘那一份只让它自己按 TTL 清，**不往内存里搬** ——
+  // 否则每次 takeRun 都要把所有挂起文件读一遍，而且「内存里没有就去磁盘找」这条路永远是死的
+  if (persistence) {
+    try {
+      persistence.list(APPROVAL_TTL_MS);
+    } catch {
+      /* 磁盘读不动就只当内存用 */
+    }
+  }
+}
+
+export function saveRun(run) {
+  pruneRuns();
+  run.touchedAt = Date.now();
+  runs.set(run.id, run);
+  if (persistence) {
+    try {
+      persistence.write(run);
+    } catch {
+      /* 落盘失败不影响本次批准 */
+    }
+  }
+  return run;
+}
+
+/** 取一个挂起态；内存里没有就去磁盘找（服务重启后的情况） */
+export function takeRun(id) {
+  pruneRuns();
+  let run = runs.get(id);
+  if (!run && persistence) {
+    try {
+      run = persistence.read(id);
+    } catch {
+      run = null;
+    }
+  }
+  if (!run) return null;
+  // 磁盘上可能躺着一个已经过期的（进程重启后内存里没有它的记录）
+  if (Date.now() - (run.touchedAt || 0) > APPROVAL_TTL_MS) {
+    dropRun(id);
+    return null;
+  }
+  run.touchedAt = Date.now();
+  runs.set(id, run);
+  // touchedAt 变了要写回，否则 TTL 会按旧时间把你正在处理的任务清掉
+  if (persistence) {
+    try {
+      persistence.write(run);
+    } catch {
+      /* 忽略 */
+    }
+  }
+  return run;
+}
+
+export function dropRun(id) {
+  runs.delete(id);
+  if (persistence) {
+    try {
+      persistence.drop(id);
+    } catch {
+      /* 忽略 */
+    }
+  }
+}
+
+/** 当前所有待批准的挂起态（页面刷新后用它把批准卡片恢复出来） */
+export function listRuns() {
+  pruneRuns();
+  // 内存是缓存、磁盘是底账：两个来源合起来才是「当前所有挂起态」。
+  // 重启之后内存是空的，全靠这里从磁盘读回来。
+  const merged = new Map();
+  if (persistence) {
+    try {
+      for (const run of persistence.list(APPROVAL_TTL_MS)) merged.set(run.id, run);
+    } catch {
+      /* 磁盘读不动就只能报内存里的 */
+    }
+  }
+  for (const [id, run] of runs) merged.set(id, run);
+  return [...merged.values()].map((r) => ({
+    runId: r.id,
+    taskId: r.taskId || null,
+    mode: normalizeMode(r.mode),
+    workingDir: r.workingDir,
+    touchedAt: r.touchedAt,
+    pending: r.pending
+      ? {
+          id: r.pending.id,
+          name: r.pending.name,
+          args: r.pending.args,
+          label: describeCall(r.pending.name, r.pending.args),
+        }
+      : null,
+    preview: r.pendingPreview || null,
+  }));
+}
+
+export function runStats() {
+  return { pending: runs.size, max: MAX_RUNS, ttlMinutes: APPROVAL_TTL_MS / 60000 };
+}
+
+/** 工具执行包一层：失败也要作为工具结果回到模型，让它自己纠正 */
+async function safeExec(run, call, allowWrite) {
+  try {
+    // 把「这一步是哪个任务节点」带给 MCP 调用（见 mcp.js 的 PLAN_NODE_HEADER）。
+    // 节点是网关在**上一轮对话响应头**里回带的；本机工具用不到这个字段。
+    // 任务页/交互式聊天都走同一口径：会话标识用 taskId || id，与对话请求一致，
+    // 否则同一次会话的对话与工具调用会被网关归到两棵树上。
+    const result = await executeTool(call.name, call.args, run.workingDir, {
+      allowWrite,
+      mcp: { planNode: run.planNode, sessionId: run.taskId || run.id },
+    });
+    return { ok: true, ...result };
+  } catch (e) {
+    const message = e?.message || String(e);
+    return { ok: false, summary: `失败：${message}`, content: `工具执行失败：${message}` };
+  }
+}
+
+/** 预览要按工具类型算（apply_patch 要看补丁后的结果，bash 要看命令），所以带上工具名 */
+const previewOf = (run, call) => writePreview(run.workingDir, { ...(call.args || {}), __tool: call.name });
+
+/**
+ * 最后一条「带 tool_calls 的 assistant 消息」里**还没有被回应**的调用。
+ *
+ * 恢复路径靠它拿到「这一批里还没跑的部分」。从 `run.messages` 现算、而不是另存一份进度，
+ * 是因为 messages 本来就已经落盘（`sessionstore` / `taskstore` 都存它），所以进程重启、
+ * 页面刷新之后照样能重建——不会出现「进度存了、重启后和消息对不上」。
+ *
+ * 它同时是**自愈**的：无论什么原因让某个 tool_call 少了回应，下一轮都会补上，
+ * 而不是等网关回一个 400 把整条任务打死。
+ */
+function unansweredCalls(run) {
+  const msgs = run.messages || [];
+  let idx = -1;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (m && m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) { idx = i; break; }
+  }
+  if (idx < 0) return [];
+  const answered = new Set();
+  for (let i = idx + 1; i < msgs.length; i++) {
+    const m = msgs[i];
+    if (m && m.role === 'tool' && m.tool_call_id) answered.add(m.tool_call_id);
+  }
+  return msgs[idx].tool_calls
+    .filter((c) => c && c.id && !answered.has(c.id))
+    // 消息里的回传形态是 {id, type, function:{name, arguments}}；执行要的是 {id, name, args, argsRaw}
+    .map((c) => {
+      const argsRaw = c.function?.arguments || '{}';
+      let args = {};
+      try { args = argsRaw ? JSON.parse(argsRaw) : {}; } catch { args = {}; }
+      return { id: c.id, name: c.function?.name || '', argsRaw, args };
+    })
+    .filter((c) => c.name);
+}
+
+/**
+ * 跑完**一批**工具调用（一条 assistant 消息里的全部 tool_calls）。
+ *
+ * 返回 `{ status: 'completed' }`；手动模式下遇到需要批准的工具时返回
+ * `{ status: 'awaiting-approval', pending, preview }`。
+ *
+ * **为什么必须整批一起管**：这批调用属于**同一条** assistant 消息，协议要求每个
+ * `tool_calls[i]` 都有一个对应的 `role:'tool'` 消息。原先手动模式分支在循环里直接
+ * `return`，于是**排在待批准调用后面的调用既不执行、也不回应**；恢复时又只补了那一个
+ * 就开下一轮 ⇒ 请求里 tool_calls 数与 tool 消息数不等，网关（正确地）拒绝：
+ * `400 An assistant message with 'tool_calls' must be followed by tool messages ...`
+ *
+ * 实测：一批计划了 8 个调用（`list_dir` + `maps_geo` + `maps_weather` + 5 个
+ * `text_search`），只跑了 2 个就 400，整条任务作废——所以恢复时必须先补完这一批
+ * （见 `unansweredCalls`）。
+ */
+async function runToolBatch({ run, send, calls, mode }) {
+  for (const call of calls) {
+    send({ type: 'tool_call', id: call.id, name: call.name, args: call.args, label: describeCall(call.name, call.args) });
+
+    // 计划模式：写入类工具根本没给模型，这里再兜一道。用 isWriteTool（含 MCP）以便与
+    // toolsForMode 的过滤口径**保持一致**，否则会出现「清单里没有、执行时却放行」。
+    if (mode === 'plan' && isWriteTool(call.name)) {
+      const refusal = '当前是计划模式，不能修改任何文件。请只用读取类工具调研，然后输出一份可执行的计划。';
+      send({ type: 'tool_result', id: call.id, name: call.name, ok: false, summary: '计划模式已拒绝写入', content: refusal, blocked: 'plan' });
+      run.messages.push({ role: 'tool', tool_call_id: call.id, content: refusal });
+      continue;
+    }
+
+    // 只有**改本机文件**的工具需要批准；MCP 调用直接执行（见 tools.js 的 isFileWriteTool）
+    if (isFileWriteTool(call.name)) {
+      if (mode === 'auto') {
+        // 自动模式：直接执行，但把「改了什么」照样发给前端逐条显示
+        const result = await safeExec(run, call, true);
+        send({
+          type: 'tool_result',
+          id: call.id,
+          name: call.name,
+          ok: result.ok,
+          summary: result.summary,
+          content: result.content,
+          approved: true,
+          auto: true,
+          preview: previewOf(run, call),
+        });
+        run.messages.push({ role: 'tool', tool_call_id: call.id, content: result.content });
+        continue;
+      }
+
+      // 手动模式：挂起等用户批准；运行态交给调用方保存
+      run.pending = call;
+      run.pendingPreview = previewOf(run, call);
+      return { status: 'awaiting-approval', pending: call, preview: run.pendingPreview };
+    }
+
+    const result = await safeExec(run, call, false);
+    send({
+      type: 'tool_result',
+      id: call.id,
+      name: call.name,
+      ok: result.ok,
+      summary: result.summary,
+      content: result.content,
+    });
+    run.messages.push({ role: 'tool', tool_call_id: call.id, content: result.content });
+  }
+
+  return { status: 'completed' };
+}
+
+/**
+ * 跑一次模型调用，把增量转发给前端，并累积正文与工具调用。
+ * 工具调用在流里是分片下发的（name 一次、arguments 多次），需要按 index 拼接。
+ */
+async function streamModelTurn({ cfg, run, send, signal, allowTools = true }) {
+  const payload = {
+    model: run.model,
+    messages: run.messages,
+    stream: true,
+    stream_options: { include_usage: true },
+  };
+  if (allowTools) {
+    // 本地文件/bash 工具没有工作目录就无法执行，不能声明；但**远端 MCP 工具不需要根目录**，
+    // 所以任务模式/页面（会话默认没有工作目录）照样能把 MCP 工具给模型用。
+    const allowed = new Set(toolsForMode(run.mode).map((t) => t.function.name));
+    const tools = run.workingDir
+      ? toolsForMode(run.mode)
+      : mcpToolSpecs(new Set(TOOLS.map((t) => t.function.name))).filter((t) => allowed.has(t.function.name));
+    if (tools.length) {
+      payload.tools = tools;
+      payload.tool_choice = 'auto';
+    }
+  }
+  if (Number.isFinite(run.temperature)) payload.temperature = run.temperature;
+  if (Number.isFinite(run.maxTokens) && run.maxTokens > 0) payload.max_tokens = run.maxTokens;
+
+  // 告诉网关「这次请求属于哪个任务/会话」：任务页用 taskId（它就是那次对话，
+  // 一次对话的所有轮次共用同一个），交互式聊天用 session.id。
+  // 网关据此把一趟任务的 N 次调用聚成一棵任务树，而不是靠指纹去猜。
+  const headers = { 'content-type': 'application/json', authorization: `Bearer ${cfg.key}` };
+  const baggage = sessionBaggage(run.taskId || run.id);
+  if (baggage) headers.baggage = baggage;
+  // CLI 自己执行 MCP 工具时，若后台绑定模式是 loop，两边会各执行一次同一个工具
+  // （等于白烧一次第三方配额）。这条头只让网关这一轮别插手，不改后台配置。
+  Object.assign(headers, mcpHeadersForChat());
+
+  const resp = await fetchWithRetry(
+    `${cfg.baseUrl}/v1/chat/completions`,
+    {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+      signal,
+    },
+    { signal },
+  );
+  if (!resp.ok) throw Object.assign(new Error(await errorText(resp)), { status: resp.status });
+
+  // 网关回带的「这一轮是哪个任务节点」（`log<账本行 id>`）。本轮的工具调用把它
+  // 原样带回 /v1/mcp/call，那次调用才能被**精确**挂到这一步上；拿不到就退回
+  // 会话级口径——功能照常，只是页面上挂接精度差一档。
+  // 老版本网关没有这个头：`.get()` 返回 null，这里就是空串，什么都不变。
+  run.planNode = String(
+    (typeof resp.headers?.get === 'function' ? resp.headers.get('x-dsh-plan-node') : '') ?? '',
+  );
+
+  const slots = [];
+  let content = '';
+  let sawReasoning = false;
+  let finish = null;
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split('\n');
+    buf = lines.pop() ?? '';
+    for (const line of lines) {
+      const t = line.trim();
+      if (!t.startsWith('data:')) continue;
+      const data = t.slice(5).trim();
+      if (!data || data === '[DONE]') continue;
+      let chunk;
+      try {
+        chunk = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      const choice = chunk?.choices?.[0];
+      const delta = choice?.delta;
+      if (delta?.reasoning_content) {
+        sawReasoning = true;
+        send({ type: 'reasoning', text: delta.reasoning_content });
+      }
+      if (delta?.content) {
+        content += delta.content;
+        send({ type: 'delta', text: delta.content });
+      }
+      if (Array.isArray(delta?.tool_calls)) {
+        for (const tc of delta.tool_calls) {
+          const i = Number.isInteger(tc.index) ? tc.index : slots.length;
+          if (!slots[i]) slots[i] = { id: '', name: '', argsRaw: '' };
+          if (tc.id) slots[i].id = tc.id;
+          if (tc.function?.name) slots[i].name += tc.function.name;
+          if (tc.function?.arguments) slots[i].argsRaw += tc.function.arguments;
+        }
+      }
+      if (choice?.finish_reason) finish = choice.finish_reason;
+      if (chunk?.usage) {
+        run.usage.prompt += chunk.usage.prompt_tokens ?? 0;
+        run.usage.completion += chunk.usage.completion_tokens ?? 0;
+        send({
+          type: 'usage',
+          usage: {
+            prompt: chunk.usage.prompt_tokens ?? null,
+            completion: chunk.usage.completion_tokens ?? null,
+            total: chunk.usage.total_tokens ?? null,
+          },
+        });
+      }
+    }
+  }
+
+  const calls = slots
+    .filter((s) => s && s.name)
+    .map((s) => {
+      let args = {};
+      try {
+        args = s.argsRaw ? JSON.parse(s.argsRaw) : {};
+      } catch {
+        args = {}; // 参数不是合法 JSON，交给工具自己报错
+      }
+      return { id: s.id || `call_${Math.random().toString(36).slice(2, 10)}`, name: s.name, argsRaw: s.argsRaw || '{}', args };
+    });
+
+  // 模型这一轮什么都没产出（既没正文也没工具调用）。
+  // 光看 finish_reason 会漏：思考模型把预算耗在思维链上时，finish 常常是 'stop' 而不是 'length'，
+  // 结果页面「读完文件就没下文了」却不给任何解释。所以只要空轮就提示，并带上 finish 便于排查。
+  if (!content && !calls.length) {
+    send({
+      type: 'notice',
+      text: sawReasoning
+        ? `上游只返回了思维链、没产出正文（finish_reason=${finish || '未知'}）—— 通常是 max_tokens 太小，被思考过程耗尽了，调大后再试`
+        : `上游结束但没有返回任何正文（finish_reason=${finish || '未知'}）`,
+    });
+  }
+
+  return { content, calls, finish };
+}
+
+/**
+ * 主循环。返回 { status: 'done' | 'awaiting-approval' | 'aborted', pending? }。
+ * 调用方负责 SSE 的开头与结尾。
+ */
+export async function runAgent({ cfg, run, send, signal }) {
+  const mode = normalizeMode(run.mode);
+  run.mode = mode;
+
+  // MCP 工具清单按**当次密钥**从网关取（best-effort，失败静默）：
+  // 网关没开 MCP / 断网 / 密钥无效时，这里不会有任何工具，行为与改动前一致。
+  //
+  // 计划模式下 MCP 工具会被 toolsForMode 当成写工具过滤掉，取了也用不上，跳过；
+  // 其余模式一律取（best-effort、静默失败、60 秒 TTL 内不会重复出网）。
+  // 注意：**不能**再拿 workingDir 当闸门 —— 任务模式/页面的会话默认没有工作目录，
+  // 之前这样写等于让整条任务模式用不上 MCP。
+  if (run.mode !== 'plan') {
+    await refreshMcpTools({ baseUrl: cfg?.baseUrl, key: cfg?.key });
+  }
+
+  const MAX_STEPS = resolveMaxSteps(cfg?.maxSteps ?? run.maxSteps);
+
+  for (let step = 0; step < MAX_STEPS; step++) {
+    // 让页面知道「模型正在生成第几轮」，否则最后一次工具调用之后就是一段没有任何状态的长静默
+    send({ type: 'turn_start', step: step + 1, max: MAX_STEPS });
+    let turn;
+    try {
+      turn = await streamModelTurn({ cfg, run, send, signal });
+    } catch (e) {
+      if (signal?.aborted) return { status: 'aborted' };
+      throw e;
+    }
+
+    if (!turn.calls.length) {
+      run.messages.push({ role: 'assistant', content: turn.content || '' });
+      // 计划模式下模型给出计划就结束了，前端据此显示「按计划执行」
+      return { status: 'done', planReady: mode === 'plan' && Boolean(turn.content) };
+    }
+
+    // 带工具调用的 assistant 消息必须原样回传（arguments 用原始字符串）
+    run.messages.push({
+      role: 'assistant',
+      content: turn.content || null,
+      tool_calls: turn.calls.map((c) => ({ id: c.id, type: 'function', function: { name: c.name, arguments: c.argsRaw } })),
+    });
+
+    if (turn.content) send({ type: 'assistant_text_end' });
+
+    const batch = await runToolBatch({ run, send, calls: turn.calls, mode });
+    if (batch.status === 'awaiting-approval') return batch;
+  }
+
+  // 用满工具轮数：不要「读完一堆文件然后戛然而止」，最后一次不给工具、明确要求它收尾，
+  // 这样用户至少能拿到一份基于已读内容的结论。
+  send({ type: 'turn_start', step: MAX_STEPS + 1, max: MAX_STEPS, wrapUp: true });
+  run.messages.push({
+    role: 'user',
+    content: '已经用完工具调用次数了，现在不要再调用任何工具。请直接基于你上面已经读到的内容给出结论；信息不足的地方就明说还缺什么。',
+  });
+  try {
+    const last = await streamModelTurn({ cfg, run, send, signal, allowTools: false });
+    if (last.content) {
+      run.messages.push({ role: 'assistant', content: last.content });
+      send({ type: 'notice', text: `已用完 ${MAX_STEPS} 轮工具，以上基于已读内容。` });
+      return { status: 'done', hitLimit: true, wrappedUp: true };
+    }
+  } catch (e) {
+    if (signal?.aborted) return { status: 'aborted' };
+    if (cfg.verbose) console.error(`[agent] 收尾轮失败：${e?.message || e}`);
+  }
+
+  send({ type: 'notice', text: `已达上限（${MAX_STEPS} 轮），可继续追问。` });
+  return { status: 'done', hitLimit: true };
+}
+
+/** 用户对写入做出决定后，把结果回填并继续循环 */
+export async function resumeWithApproval({ cfg, run, send, signal, approved }) {
+  const pending = run.pending;
+  if (!pending) throw Object.assign(new Error('该任务没有待批准的写入'), { status: 409 });
+  run.pending = null;
+  run.pendingPreview = null;
+
+  const result = approved
+    ? await safeExec(run, pending, true)
+    : {
+        ok: false,
+        summary: '用户拒绝了这次写入',
+        content: '用户拒绝执行这次写入操作。不要重试同样的写入，请改为向用户说明你的思路，或提出替代方案。',
+      };
+
+  send({
+    type: 'tool_result',
+    id: pending.id,
+    name: pending.name,
+    ok: result.ok,
+    summary: result.summary,
+    content: result.content,
+    approved: Boolean(approved),
+  });
+  run.messages.push({ role: 'tool', tool_call_id: pending.id, content: result.content });
+
+  // 把**同一条 assistant 消息里剩下的**调用补跑完，再交给模型。
+  // 漏掉任何一个，下一次请求都会被网关以「tool_calls 与 tool 消息数量不等」拒掉（400），
+  // 整条任务作废——这是实测踩出来的（详见 runToolBatch 的说明）。
+  const more = await runToolBatch({ run, send, calls: unansweredCalls(run), mode: normalizeMode(run.mode) });
+  if (more.status === 'awaiting-approval') return more;
+
+  return runAgent({ cfg, run, send, signal });
+}
+
+export const AGENT_LIMITS = { MAX_STEPS: DEFAULT_MAX_STEPS, DEFAULT_MAX_STEPS, RUN_TTL_MS: APPROVAL_TTL_MS, APPROVAL_TTL_MS, MAX_RUNS, MODES };