minimal-agent 0.11.0 → 0.12.0

package/src/tools/agent/agent.js

@@ -3,14 +3,12 @@
  *  src/tools/agent/agent.ts —— Agent 工具（fork 子 agent / 多 agent 并行）
  * ------------------------------------------------------------
  *  借鉴 Claude Code 官方 AgentTool/ForkAgent 的核心思想，按 minimal-agent
- *  内核架构做同步等效实现：
+ *  内核架构做可恢复的前台/后台等效实现：
  *    - 官方 fork = 「隔离 context 嵌套跑同一主循环 + 摘要回传（完整历史不进
- *      父上下文）」。我们不需要它的后台任务队列/AsyncLocalStorage 身份追踪
- *      （那是为 Ink UI 后台任务服务的）——本工具同步 await 一个嵌套 runQuery，
- *      声明 isConcurrencySafe:true 后，模型在同一轮发出 N 个 Agent 调用时，
- *      loop.ts 现成的并行 worker 队列自动把它们并发执行。这就是并行的全部来源。
- *    - 同轮混入任一非并发安全工具（如 Edit）会整轮退化串行——这是想要的安全
- *      语义（写操作与并行 fork 不该交错）。
+ *      父上下文）」。本工具在隔离 history 中嵌套运行同一主循环，并将私有历史、
+ *      进度和结果写入会话运行存储；前台、后台和重启后续接共用同一执行内核。
+ *    - 同轮多个 Agent 调用仍由 loop.ts 的并行 worker 执行；write scopes 与可选
+ *      worktree 负责隔离真正可并行的写任务。
  *
  *  已知限制（如实声明）：
  *    - 子 agent 的 LoopEvent 不外泄：-p / stream-json 宿主只看到本工具的一对
@@ -27,6 +25,8 @@
  * ============================================================
  */
 import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { access } from 'node:fs/promises';
 import { withAskSource } from '../../askBridge.js';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
@@ -41,6 +41,7 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { SUBAGENT_EXCLUDED_TOOLS, resolveAgentType } from './agentTypes.js';
 import { acquireSubagentLease, normalizeWriteScopes } from './coordinator.js';
 import { commitWorktreeChanges, createAgentWorktree, hasWorktreeChanges, removeAgentWorktree, worktreeChangedFiles, worktreeDiffStat, } from './worktree.js';
+import { appendAgentEvent, loadAgentRecord, saveAgentRecord } from './agentTaskService.js';
 let corePromise = null;
 /** 首次调用时才真正加载 loop/tools——此刻模块图早已初始化完毕，环安全。 */
 function loadCore() {
@@ -79,13 +80,16 @@ const inputSchema = z.object({
         .max(32)
         .optional()
         .describe('general 预计修改的工作目录相对路径。范围互不重叠时可并行；缺省时按整个工作目录串行。explore 不需要。'),
+    run_in_background: z.boolean().optional().describe('立即返回 agent_id，子任务在后台运行；用 TaskOutput/TaskStop 管理'),
+    resume_agent_id: z.string().regex(/^agent_[0-9a-f-]{36}$/i).optional().describe('继续当前会话中此前完成、中断或失败的 Agent 历史'),
 });
 const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
-const description = `- Launches a stateless sub-agent with a fresh, isolated context to execute one self-contained subtask; returns only its final report text (its full working history never enters this conversation).
+const description = `- Launches an isolated sub-agent for one self-contained task. Every run returns an agent_id; run_in_background=true continues without blocking, and resume_agent_id continues its persisted private history across user turns or an app restart.
 - The sub-agent CANNOT see this conversation. The \`prompt\` must be fully self-contained: background, exact file paths, what to look for / do, and the expected output format.
 - **To parallelize, emit multiple Agent calls in ONE assistant message** — they run concurrently. This is the main value of this tool.
+- Background Agent progress/results are read with TaskOutput and stopped with TaskStop. Do not poll: TaskOutput(block=true) waits efficiently.
 - Use for: exploring/researching several independent areas of a codebase at once, parallel information gathering from multiple sources, independent analyses that will be synthesized afterwards, and (with agent_type:'general') genuinely parallelizable write/execute work.
 - Do NOT use for: single targeted lookups that one or two direct tool calls would answer (a fork starts cold and re-derives context — slower and costlier), or strictly sequential work. Only general execution agents may ask the user, and only when genuinely blocked.
 - agent_type: 'explore' (default) = strictly read-only research; 'general' = read-write execution. For direct writes, declare relative write_scopes; disjoint scopes may run concurrently, overlapping or omitted scopes are serialized.
@@ -237,10 +241,10 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     // allowedTools 只裁「下发给模型的清单」；guardedExecute 是真正的硬防线（见下）。
     const allowedTools = def.resolveAllowedTools(ALL_TOOLS.map((t) => t.name));
     // ---- worktree 隔离（仅 general 显式要求时） ----
-    let wt = null;
+    let wt = deps.existingWorktree ?? null;
     const isolation = input.isolation ?? ctx.subagentConfig?.defaultWriteIsolation ?? 'none';
-    if (def.type === 'general' && isolation === 'worktree') {
-        const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`);
+    if (def.type === 'general' && isolation === 'worktree' && !wt) {
+        const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`, ctx.cwd);
         if (!created.ok) {
             return {
                 ok: false,
@@ -248,8 +252,9 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             };
         }
         wt = created;
+        await deps.onWorktreeCreated?.(created);
     }
-    const cwd = wt?.path ?? getWorkingDir();
+    const cwd = wt?.path ?? ctx.cwd ?? getWorkingDir();
     let writeScopes;
     try {
         writeScopes = def.type === 'general'
@@ -288,6 +293,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             surface: 'subagent',
             cwd,
             workspaceId: ctx.workspaceId,
+            sessionId: ctx.sessionId,
             interactiveAsk: childRuntime.interactiveAsk,
             memoryAccess: childMemoryAccess,
             currentUserInput: input.prompt,
@@ -303,7 +309,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         ctx.reportProgress?.(line, detail);
     };
     // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
-    const history = [
+    const history = deps.initialHistory?.length ? [...deps.initialHistory] : [
         { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
     ];
     const historyLenBefore = history.length;
@@ -529,6 +535,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     finally {
         stopTimeout();
         releaseLease?.();
+        await deps.captureHistory?.(history);
     }
     // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
     if (ownerCancelController.signal.aborted) {
@@ -625,6 +632,128 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
 async function call(input, signal) {
     return runAgentTask(input, signal, {});
 }
+export async function runManagedAgentTask(input, signal, ctx, deps = {}) {
+    if (!ctx.sessionState)
+        return runAgentTask(input, signal, ctx);
+    const id = input.resume_agent_id ?? `agent_${randomUUID()}`;
+    let initialHistory;
+    let resumedWorktree;
+    let coreInput = { ...input, run_in_background: undefined, resume_agent_id: undefined };
+    if (input.resume_agent_id) {
+        const live = ctx.sessionState.agentTasks.tasks.get(id);
+        if (live?.status === 'running')
+            return { ok: false, error: `Agent ${id} 正在运行，不能并发恢复` };
+        const saved = await loadAgentRecord(ctx, id);
+        if (!saved)
+            return { ok: false, error: `找不到可恢复 Agent：${id}` };
+        initialHistory = saved.history;
+        resumedWorktree = saved.worktree && await access(saved.worktree.path)
+            .then(() => saved.worktree)
+            .catch(() => undefined);
+        coreInput = {
+            ...saved.input,
+            prompt: input.prompt,
+            description: input.description || saved.description,
+            run_in_background: undefined,
+            resume_agent_id: undefined,
+        };
+    }
+    const abort = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+    let settle;
+    const completion = new Promise((resolvePromise) => { settle = resolvePromise; });
+    const task = {
+        id,
+        status: 'running',
+        description: coreInput.description,
+        input: coreInput,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        abort,
+        completion,
+        events: new EventEmitter(),
+    };
+    ctx.sessionState.agentTasks.tasks.set(id, task);
+    await saveAgentRecord(ctx, task);
+    await appendAgentEvent(ctx, id, { phase: 'started', resumed: Boolean(input.resume_agent_id) });
+    const run = async () => {
+        let captured = initialHistory;
+        let lastPersistedProgressAt = 0;
+        const managedContext = {
+            ...ctx,
+            reportProgress: (line, detail) => {
+                ctx.reportProgress?.(line, detail);
+                task.progress = line;
+                task.events.emit('change');
+                if (Date.now() - lastPersistedProgressAt >= 1_000) {
+                    lastPersistedProgressAt = Date.now();
+                    void saveAgentRecord(ctx, task).catch(() => undefined);
+                    void appendAgentEvent(ctx, id, { phase: 'progress', message: line })
+                        .catch(() => undefined);
+                }
+            },
+        };
+        try {
+            const result = await runAgentTask(coreInput, combined, managedContext, {
+                ...deps,
+                initialHistory,
+                existingWorktree: resumedWorktree,
+                onWorktreeCreated: async (worktree) => {
+                    task.worktree = worktree;
+                    await saveAgentRecord(ctx, task);
+                },
+                captureHistory: (history) => { captured = [...history]; },
+            });
+            task.result = result;
+            task.history = captured;
+            task.status = abort.signal.aborted ? 'stopped' : result.ok ? 'completed' : 'failed';
+            if (task.worktree && !await access(task.worktree.path).then(() => true).catch(() => false)) {
+                task.worktree = undefined;
+            }
+            task.updatedAt = Date.now();
+            await saveAgentRecord(ctx, task);
+            await appendAgentEvent(ctx, id, { phase: task.status, ok: result.ok });
+            return result;
+        }
+        catch (error) {
+            task.status = abort.signal.aborted ? 'stopped' : 'failed';
+            task.result = { ok: false, error: error.message };
+            task.history = captured;
+            task.updatedAt = Date.now();
+            await saveAgentRecord(ctx, task).catch(() => undefined);
+            await appendAgentEvent(ctx, id, { phase: task.status, error: error.message })
+                .catch(() => undefined);
+            return task.result;
+        }
+        finally {
+            task.events.emit('change');
+            settle();
+        }
+    };
+    if (input.run_in_background) {
+        void run();
+        return {
+            ok: true,
+            content: `后台 Agent 已启动。agent_id=${id}\n使用 TaskOutput 获取进度/结果，TaskStop 停止。`,
+            metadata: {
+                kind: 'agent', agentId: id, status: 'running',
+                agentType: input.agent_type ?? 'explore', description: input.description,
+                isolation: input.isolation ?? 'none', turns: 0, toolCalls: 0,
+                failedToolCalls: 0, durationMs: 0, changedFiles: [],
+            },
+        };
+    }
+    const result = await run();
+    if (result.ok && result.metadata?.kind === 'agent') {
+        result.metadata.agentId = id;
+        result.metadata.status = 'completed';
+        result.content = `agent_id=${id}\n${result.content}`;
+    }
+    else if (!result.ok) {
+        result.error = `agent_id=${id}\n${result.error}`;
+    }
+    return result;
+}
 // ---------------- 5. 导出 ----------------
 export const agentTool = {
     name: 'Agent',
@@ -638,5 +767,5 @@ export const agentTool = {
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
     call,
-    callWithContext: runAgentTask,
+    callWithContext: runManagedAgentTask,
 };

package/src/tools/agent/agent.ts

@@ -3,14 +3,12 @@
  *  src/tools/agent/agent.ts —— Agent 工具（fork 子 agent / 多 agent 并行）
  * ------------------------------------------------------------
  *  借鉴 Claude Code 官方 AgentTool/ForkAgent 的核心思想，按 minimal-agent
- *  内核架构做同步等效实现：
+ *  内核架构做可恢复的前台/后台等效实现：
  *    - 官方 fork = 「隔离 context 嵌套跑同一主循环 + 摘要回传（完整历史不进
- *      父上下文）」。我们不需要它的后台任务队列/AsyncLocalStorage 身份追踪
- *      （那是为 Ink UI 后台任务服务的）——本工具同步 await 一个嵌套 runQuery，
- *      声明 isConcurrencySafe:true 后，模型在同一轮发出 N 个 Agent 调用时，
- *      loop.ts 现成的并行 worker 队列自动把它们并发执行。这就是并行的全部来源。
- *    - 同轮混入任一非并发安全工具（如 Edit）会整轮退化串行——这是想要的安全
- *      语义（写操作与并行 fork 不该交错）。
+ *      父上下文）」。本工具在隔离 history 中嵌套运行同一主循环，并将私有历史、
+ *      进度和结果写入会话运行存储；前台、后台和重启后续接共用同一执行内核。
+ *    - 同轮多个 Agent 调用仍由 loop.ts 的并行 worker 执行；write scopes 与可选
+ *      worktree 负责隔离真正可并行的写任务。
  *
  *  已知限制（如实声明）：
  *    - 子 agent 的 LoopEvent 不外泄：-p / stream-json 宿主只看到本工具的一对
@@ -28,6 +26,8 @@
  */
 
 import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { access } from 'node:fs/promises';
 import { withAskSource } from '../../askBridge.js';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { z } from 'zod';
@@ -59,6 +59,7 @@ import {
   worktreeChangedFiles,
   worktreeDiffStat,
 } from './worktree.js';
+import { appendAgentEvent, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
 
 // ---------------- 0. 环内模块懒加载（见文件头「循环依赖纪律」） ----------------
 
@@ -116,6 +117,8 @@ const inputSchema = z.object({
     .describe(
       'general 预计修改的工作目录相对路径。范围互不重叠时可并行；缺省时按整个工作目录串行。explore 不需要。',
     ),
+  run_in_background: z.boolean().optional().describe('立即返回 agent_id，子任务在后台运行；用 TaskOutput/TaskStop 管理'),
+  resume_agent_id: z.string().regex(/^agent_[0-9a-f-]{36}$/i).optional().describe('继续当前会话中此前完成、中断或失败的 Agent 历史'),
 });
 type AgentInput = z.infer<typeof inputSchema>;
 
@@ -124,9 +127,10 @@ const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
 // 借鉴官方 AgentTool prompt 文案（任务书自包含 / 同轮并行 / 何时不用）。
 
-const description = `- Launches a stateless sub-agent with a fresh, isolated context to execute one self-contained subtask; returns only its final report text (its full working history never enters this conversation).
+const description = `- Launches an isolated sub-agent for one self-contained task. Every run returns an agent_id; run_in_background=true continues without blocking, and resume_agent_id continues its persisted private history across user turns or an app restart.
 - The sub-agent CANNOT see this conversation. The \`prompt\` must be fully self-contained: background, exact file paths, what to look for / do, and the expected output format.
 - **To parallelize, emit multiple Agent calls in ONE assistant message** — they run concurrently. This is the main value of this tool.
+- Background Agent progress/results are read with TaskOutput and stopped with TaskStop. Do not poll: TaskOutput(block=true) waits efficiently.
 - Use for: exploring/researching several independent areas of a codebase at once, parallel information gathering from multiple sources, independent analyses that will be synthesized afterwards, and (with agent_type:'general') genuinely parallelizable write/execute work.
 - Do NOT use for: single targeted lookups that one or two direct tool calls would answer (a fork starts cold and re-derives context — slower and costlier), or strictly sequential work. Only general execution agents may ask the user, and only when genuinely blocked.
 - agent_type: 'explore' (default) = strictly read-only research; 'general' = read-write execution. For direct writes, declare relative write_scopes; disjoint scopes may run concurrently, overlapping or omitted scopes are serialized.
@@ -222,6 +226,10 @@ export function extractCoveredFiles(
 export interface AgentTaskDeps {
   chat?: RunQueryOptions['chat'];
   executeTool?: RunQueryOptions['executeTool'];
+  initialHistory?: RunQueryOptions['history'];
+  captureHistory?: (history:RunQueryOptions['history'])=>void|Promise<void>;
+  existingWorktree?: AgentWorktree;
+  onWorktreeCreated?: (worktree: AgentWorktree) => void | Promise<void>;
 }
 
 function positiveInt(value: string | undefined): number | undefined {
@@ -296,10 +304,10 @@ export async function runAgentTask(
   const allowedTools = def.resolveAllowedTools(ALL_TOOLS.map((t) => t.name));
 
   // ---- worktree 隔离（仅 general 显式要求时） ----
-  let wt: AgentWorktree | null = null;
+  let wt: AgentWorktree | null = deps.existingWorktree ?? null;
   const isolation = input.isolation ?? ctx.subagentConfig?.defaultWriteIsolation ?? 'none';
-  if (def.type === 'general' && isolation === 'worktree') {
-    const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`);
+  if (def.type === 'general' && isolation === 'worktree' && !wt) {
+    const created = await createAgentWorktree(`fork-${randomUUID().slice(0, 8)}`, ctx.cwd);
     if (!created.ok) {
       return {
         ok: false,
@@ -307,8 +315,9 @@ export async function runAgentTask(
       };
     }
     wt = created;
+    await deps.onWorktreeCreated?.(created);
   }
-  const cwd = wt?.path ?? getWorkingDir();
+  const cwd = wt?.path ?? ctx.cwd ?? getWorkingDir();
   let writeScopes: string[];
   try {
     writeScopes = def.type === 'general'
@@ -348,6 +357,7 @@ export async function runAgentTask(
       surface: 'subagent',
       cwd,
       workspaceId: ctx.workspaceId,
+      sessionId: ctx.sessionId,
       interactiveAsk: childRuntime.interactiveAsk,
       memoryAccess: childMemoryAccess,
       currentUserInput: input.prompt,
@@ -364,7 +374,7 @@ export async function runAgentTask(
   };
 
   // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
-  const history: RunQueryOptions['history'] = [
+  const history: RunQueryOptions['history'] = deps.initialHistory?.length ? [...deps.initialHistory] : [
     { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
   ];
   const historyLenBefore = history.length;
@@ -582,6 +592,7 @@ export async function runAgentTask(
   } finally {
     stopTimeout();
     releaseLease?.();
+    await deps.captureHistory?.(history);
   }
 
   // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
@@ -684,6 +695,130 @@ async function call(input: AgentInput, signal?: AbortSignal): Promise<ToolResult
   return runAgentTask(input, signal, {});
 }
 
+export async function runManagedAgentTask(
+  input: AgentInput,
+  signal: AbortSignal | undefined,
+  ctx: ToolCallContext,
+  deps: AgentTaskDeps = {},
+): Promise<ToolResult> {
+  if (!ctx.sessionState) return runAgentTask(input, signal, ctx);
+  const id = input.resume_agent_id ?? `agent_${randomUUID()}`;
+  let initialHistory: RunQueryOptions['history'] | undefined;
+  let resumedWorktree: AgentWorktree | undefined;
+  let coreInput = { ...input, run_in_background: undefined, resume_agent_id: undefined };
+  if (input.resume_agent_id) {
+    const live = ctx.sessionState.agentTasks.tasks.get(id);
+    if (live?.status === 'running') return { ok: false, error: `Agent ${id} 正在运行，不能并发恢复` };
+    const saved = await loadAgentRecord(ctx, id);
+    if (!saved) return { ok: false, error: `找不到可恢复 Agent：${id}` };
+    initialHistory = saved.history;
+    resumedWorktree = saved.worktree && await access(saved.worktree.path)
+      .then(() => saved.worktree)
+      .catch(() => undefined);
+    coreInput = {
+      ...(saved.input as AgentInput),
+      prompt: input.prompt,
+      description: input.description || saved.description,
+      run_in_background: undefined,
+      resume_agent_id: undefined,
+    };
+  }
+  const abort = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+  let settle!: () => void;
+  const completion = new Promise<void>((resolvePromise) => { settle = resolvePromise; });
+  const task: LiveAgentTask = {
+    id,
+    status: 'running',
+    description: coreInput.description,
+    input: coreInput as unknown as Record<string, unknown>,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    abort,
+    completion,
+    events: new EventEmitter(),
+  };
+  ctx.sessionState.agentTasks.tasks.set(id, task);
+  await saveAgentRecord(ctx, task);
+  await appendAgentEvent(ctx, id, { phase: 'started', resumed: Boolean(input.resume_agent_id) });
+
+  const run = async (): Promise<ToolResult> => {
+    let captured = initialHistory;
+    let lastPersistedProgressAt = 0;
+    const managedContext: ToolCallContext = {
+      ...ctx,
+      reportProgress: (line, detail) => {
+        ctx.reportProgress?.(line, detail);
+        task.progress = line;
+        task.events.emit('change');
+        if (Date.now() - lastPersistedProgressAt >= 1_000) {
+          lastPersistedProgressAt = Date.now();
+          void saveAgentRecord(ctx, task).catch(() => undefined);
+          void appendAgentEvent(ctx, id, { phase: 'progress', message: line })
+            .catch(() => undefined);
+        }
+      },
+    };
+    try {
+      const result = await runAgentTask(coreInput, combined, managedContext, {
+        ...deps,
+        initialHistory,
+        existingWorktree: resumedWorktree,
+        onWorktreeCreated: async (worktree) => {
+          task.worktree = worktree;
+          await saveAgentRecord(ctx, task);
+        },
+        captureHistory: (history) => { captured = [...history]; },
+      });
+      task.result = result;
+      task.history = captured;
+      task.status = abort.signal.aborted ? 'stopped' : result.ok ? 'completed' : 'failed';
+      if (task.worktree && !await access(task.worktree.path).then(() => true).catch(() => false)) {
+        task.worktree = undefined;
+      }
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task);
+      await appendAgentEvent(ctx, id, { phase: task.status, ok: result.ok });
+      return result;
+    } catch (error) {
+      task.status = abort.signal.aborted ? 'stopped' : 'failed';
+      task.result = { ok: false, error: (error as Error).message };
+      task.history = captured;
+      task.updatedAt = Date.now();
+      await saveAgentRecord(ctx, task).catch(() => undefined);
+      await appendAgentEvent(ctx, id, { phase: task.status, error: (error as Error).message })
+        .catch(() => undefined);
+      return task.result;
+    } finally {
+      task.events.emit('change');
+      settle();
+    }
+  };
+
+  if (input.run_in_background) {
+    void run();
+    return {
+      ok: true,
+      content: `后台 Agent 已启动。agent_id=${id}\n使用 TaskOutput 获取进度/结果，TaskStop 停止。`,
+      metadata: {
+        kind: 'agent', agentId: id, status: 'running',
+        agentType: input.agent_type ?? 'explore', description: input.description,
+        isolation: input.isolation ?? 'none', turns: 0, toolCalls: 0,
+        failedToolCalls: 0, durationMs: 0, changedFiles: [],
+      },
+    };
+  }
+  const result = await run();
+  if (result.ok && result.metadata?.kind === 'agent') {
+    result.metadata.agentId = id;
+    result.metadata.status = 'completed';
+    result.content = `agent_id=${id}\n${result.content}`;
+  } else if (!result.ok) {
+    result.error = `agent_id=${id}\n${result.error}`;
+  }
+  return result;
+}
+
 // ---------------- 5. 导出 ----------------
 
 export const agentTool: Tool<AgentInput> = {
@@ -698,5 +833,5 @@ export const agentTool: Tool<AgentInput> = {
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   interruptBehavior: () => 'block',
   call,
-  callWithContext: runAgentTask,
+  callWithContext: runManagedAgentTask,
 };

package/src/tools/agent/agentTaskService.js

@@ -0,0 +1,60 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readRuntimeJson, sessionRuntimeDir, withRuntimeFileLock, writeRuntimeJson, } from '../../session/runtimeStore.js';
+export function createAgentTaskState() {
+    return { tasks: new Map() };
+}
+function dir(ctx, id) {
+    return join(sessionRuntimeDir(ctx), 'agents', id);
+}
+export async function appendAgentEvent(ctx, id, event) {
+    const path = join(dir(ctx, id), 'events.jsonl');
+    await mkdir(dir(ctx, id), { recursive: true, mode: 0o700 });
+    await withRuntimeFileLock(path, () => appendFile(path, `${JSON.stringify({ at: Date.now(), ...event })}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }));
+}
+export async function saveAgentRecord(ctx, record) {
+    const persisted = {
+        id: record.id,
+        status: record.status,
+        description: record.description,
+        input: record.input,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        ...(record.progress ? { progress: record.progress } : {}),
+        ...(record.worktree ? { worktree: record.worktree } : {}),
+        ...(record.result ? { result: record.result } : {}),
+    };
+    const recordDir = dir(ctx, record.id);
+    await withRuntimeFileLock(join(recordDir, '.record'), async () => {
+        await writeRuntimeJson(join(recordDir, 'state.json'), persisted);
+        if (record.history) {
+            await writeRuntimeJson(join(recordDir, 'history.json'), record.history);
+        }
+    });
+}
+export async function loadAgentRecord(ctx, id) {
+    const state = await readRuntimeJson(join(dir(ctx, id), 'state.json'), undefined);
+    if (!state)
+        return undefined;
+    const history = await readRuntimeJson(join(dir(ctx, id), 'history.json'), undefined);
+    return {
+        ...state,
+        status: state.status === 'running' ? 'interrupted' : state.status,
+        history,
+    };
+}
+export function getLiveAgentTask(state, id) {
+    return state?.tasks.get(id);
+}
+export async function stopAllAgentTasks(state) {
+    const running = [...state.tasks.values()].filter((t) => t.status === 'running');
+    running.forEach((t) => t.abort.abort());
+    await Promise.race([
+        Promise.allSettled(running.map((t) => t.completion)).then(() => undefined),
+        new Promise((r) => setTimeout(r, 5000)),
+    ]);
+    state.tasks.clear();
+}

package/src/tools/agent/agentTaskService.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'node:events';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Message, ToolCallContext, ToolResult } from '../../types.js';
+import type { AgentWorktree } from './worktree.js';
+import {
+  readRuntimeJson,
+  sessionRuntimeDir,
+  withRuntimeFileLock,
+  writeRuntimeJson,
+} from '../../session/runtimeStore.js';
+
+export type AgentTaskStatus =
+  'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+export interface AgentTaskRecord {
+  id: string;
+  status: AgentTaskStatus;
+  description: string;
+  input: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  progress?: string;
+  worktree?: AgentWorktree;
+  result?: ToolResult;
+  history?: Message[];
+}
+export interface LiveAgentTask extends AgentTaskRecord {
+  abort: AbortController;
+  completion: Promise<void>;
+  events: EventEmitter;
+}
+export interface AgentTaskState {
+  tasks: Map<string, LiveAgentTask>;
+}
+export function createAgentTaskState(): AgentTaskState {
+  return { tasks: new Map() };
+}
+function dir(ctx: ToolCallContext, id: string) {
+  return join(sessionRuntimeDir(ctx), 'agents', id);
+}
+export async function appendAgentEvent(
+  ctx: ToolCallContext,
+  id: string,
+  event: Record<string, unknown>,
+): Promise<void> {
+  const path = join(dir(ctx, id), 'events.jsonl');
+  await mkdir(dir(ctx, id), { recursive: true, mode: 0o700 });
+  await withRuntimeFileLock(path, () =>
+    appendFile(path, `${JSON.stringify({ at: Date.now(), ...event })}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    }),
+  );
+}
+export async function saveAgentRecord(
+  ctx: ToolCallContext,
+  record: AgentTaskRecord,
+): Promise<void> {
+  const persisted: AgentTaskRecord = {
+    id: record.id,
+    status: record.status,
+    description: record.description,
+    input: record.input,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    ...(record.progress ? { progress: record.progress } : {}),
+    ...(record.worktree ? { worktree: record.worktree } : {}),
+    ...(record.result ? { result: record.result } : {}),
+  };
+  const recordDir = dir(ctx, record.id);
+  await withRuntimeFileLock(join(recordDir, '.record'), async () => {
+    await writeRuntimeJson(join(recordDir, 'state.json'), persisted);
+    if (record.history) {
+      await writeRuntimeJson(join(recordDir, 'history.json'), record.history);
+    }
+  });
+}
+export async function loadAgentRecord(
+  ctx: ToolCallContext,
+  id: string,
+): Promise<AgentTaskRecord | undefined> {
+  const state = await readRuntimeJson<AgentTaskRecord | undefined>(
+    join(dir(ctx, id), 'state.json'),
+    undefined,
+  );
+  if (!state) return undefined;
+  const history = await readRuntimeJson<Message[] | undefined>(
+    join(dir(ctx, id), 'history.json'),
+    undefined,
+  );
+  return {
+    ...state,
+    status: state.status === 'running' ? 'interrupted' : state.status,
+    history,
+  };
+}
+export function getLiveAgentTask(
+  state: AgentTaskState | undefined,
+  id: string,
+): LiveAgentTask | undefined {
+  return state?.tasks.get(id);
+}
+export async function stopAllAgentTasks(state: AgentTaskState): Promise<void> {
+  const running = [...state.tasks.values()].filter(
+    (t) => t.status === 'running',
+  );
+  running.forEach((t) => t.abort.abort());
+  await Promise.race([
+    Promise.allSettled(running.map((t) => t.completion)).then(() => undefined),
+    new Promise<void>((r) => setTimeout(r, 5000)),
+  ]);
+  state.tasks.clear();
+}