minimal-agent 0.10.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,18 +25,23 @@
  * ============================================================
  */
 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';
 import { getWorkingDir, withWorkingDir } from '../../bootstrap/workingDir.js';
+import { derivePromptCacheContext } from '../../llm/promptCache.js';
 import { createSessionState } from '../../session/sessionState.js';
-import { assembleBasePrompt } from '../../prompts/promptAssembly.js';
+import { assembleStablePrompt, buildTransientPromptBundle, } from '../../prompts/promptAssembly.js';
+import { createAgentRuntimeContext, filterToolsForRuntime, } from '../../runtime/agentRuntimeContext.js';
 import { stripThinkBlocks } from '../../utils/stripThink.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 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() {
@@ -77,24 +80,27 @@ 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.
-- isolation:'worktree' (general only): the sub-agent sees the repo's last COMMITTED state (uncommitted changes are invisible — commit first if it needs them). On completion its changes are auto-committed to a temp branch and the report tail tells you the branch name; review the diff, merge (e.g. \`git merge --squash <branch>\`), then clean up.
-- After sub-agents return you MUST synthesize: cross-check contradictions between reports, integrate into one conclusion — never just forward raw reports. A failed/timed-out fork is not a blocker: proceed with what you have and state the gap.`;
+- isolation:'worktree' (general only): the sub-agent sees the repo's last COMMITTED state. Never commit the user's work merely to expose uncommitted changes; instead keep the task in the current workspace or make the task self-contained. On completion its changes are committed only to a temporary branch; review before applying it to the user's workspace.
+- After sub-agents return you MUST synthesize: cross-check contradictions between reports, integrate into one conclusion — never just forward raw reports. A failed/timed-out fork is not a blocker: proceed with what you have and state the gap.
+- Each sub-task result carries coveredFiles: the actual files/URLs the sub-agent read, extracted from its tool-call history (not self-reported). Before trusting a conclusion, audit its coveredFiles for gaps/overlaps — if coverage looks too thin for what it claims, treat that conclusion as low-confidence.`;
 // ---------------- 3. 子 agent 系统提示词（memoize，提示词缓存友好） ----------------
-/** 通用附加段：所有 agent_type 共享（拼在 assembleBasePrompt 之后）。 */
+/** 任务回传契约。能力与权限已经由 assembleBasePrompt profile 精确注入。 */
 const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）
 你是主 agent 派生出的子 agent，正在执行一个自包含的子任务：
 - 你看不到主对话；任务书（用户消息）就是你的全部输入。
-- explore 子任务不能向用户提问；general 仅在缺少关键输入或高风险取舍时使用 AskUserQuestion，最多两次。
 - 你的**最后一条回复就是唯一回传主 agent 的报告**，必须自包含：结论 + 关键证据（文件路径/行号）+ 未尽事项。
   不要输出「我完成了」这类无信息量收尾，也不要在报告里向主 agent 提问——它不会回复你。`;
 /**
@@ -107,15 +113,18 @@ const SUBAGENT_COMMON_APPENDIX = `# 你是子 agent（fork 分身）
 const PROMPT_CACHE_TTL_MS = 60_000;
 const promptCache = new Map();
 async function buildSubSystemPrompt(cwd, def, allTools) {
-    const key = `${cwd}::${def.type}`;
+    // Effective capabilities are part of prompt identity; a child must never
+    // reuse a cached parent-capability prompt (notably Desktop WebBrowser).
+    const key = `${cwd}::${def.type}::${allTools.map((tool) => tool.name).join(',')}`;
     const hit = promptCache.get(key);
     if (hit && Date.now() - hit.at < PROMPT_CACHE_TTL_MS)
         return hit.value;
     const allowedNames = def.resolveAllowedTools(allTools.map((t) => t.name));
     const subTools = allTools.filter((t) => allowedNames.includes(t.name));
-    const base = await assembleBasePrompt({
+    const base = await assembleStablePrompt({
         cwd,
         tools: subTools,
+        profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
         includeProjectInstructions: true, // 子 agent 在同一仓库干活，项目约定必须继承
         includePlugins: false, // 插件是宿主命令面，子 agent 不该被引去激活插件
     });
@@ -123,6 +132,52 @@ async function buildSubSystemPrompt(cwd, def, allTools) {
     promptCache.set(key, { value, at: Date.now() });
     return value;
 }
+// ---------------- 3.5 覆盖度提取（客观，从工具调用历史推导） ----------------
+/**
+ * 从子任务 history 中提取「实际读取/调研过的文件/目标」清单，
+ * 用于父 agent / 宿主做覆盖度自检，避免「以为覆盖了其实没覆盖」的幻觉。
+ */
+export function extractCoveredFiles(history, startIdx) {
+    const seen = new Set();
+    for (let i = startIdx; i < history.length; i++) {
+        const msg = history[i];
+        if (msg.role !== 'assistant' || !msg.tool_calls)
+            continue;
+        for (const tc of msg.tool_calls) {
+            const name = tc.function.name;
+            let args;
+            try {
+                args = JSON.parse(tc.function.arguments);
+            }
+            catch {
+                continue;
+            }
+            if (!args)
+                continue;
+            if (name === 'Read' && typeof args.file_path === 'string') {
+                seen.add(args.file_path);
+            }
+            else if (name === 'Glob' && typeof args.pattern === 'string') {
+                seen.add(`glob:${args.pattern}`);
+            }
+            else if (name === 'Grep') {
+                const parts = ['grep:' + (typeof args.pattern === 'string' ? args.pattern : '?')];
+                if (typeof args.path === 'string')
+                    parts.push(`path=${args.path}`);
+                if (typeof args.glob === 'string')
+                    parts.push(`glob=${args.glob}`);
+                seen.add(parts.join(' '));
+            }
+            else if (name === 'WebFetch' && typeof args.url === 'string') {
+                seen.add(args.url);
+            }
+            else if (name === 'WebBrowser' && typeof args.url === 'string') {
+                seen.add(`browser:${args.url}`);
+            }
+        }
+    }
+    return [...seen].sort();
+}
 function positiveInt(value) {
     const n = Number.parseInt(value ?? '', 10);
     return Number.isFinite(n) && n > 0 ? n : undefined;
@@ -186,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,
@@ -197,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'
@@ -211,6 +267,38 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         return { ok: false, error: error.message };
     }
     const rootScope = await normalizeWriteScopes(cwd, undefined);
+    const childMemoryAccess = ctx.memoryAccess === 'denied' || !ctx.memoryAccess
+        ? 'denied'
+        : 'read-only';
+    const childRuntime = createAgentRuntimeContext({
+        surface: 'subagent',
+        profile: def.type === 'general' ? 'subagent-general' : 'subagent-explore',
+        cwd,
+        workspaceId: ctx.workspaceId,
+        sessionId: ctx.sessionId,
+        owner: childMemoryAccess === 'denied' ? 'untrusted' : 'local-owner',
+        memoryAccess: childMemoryAccess,
+        interactiveAsk: def.type === 'general',
+        toolGate: ctx.toolGate,
+    });
+    const subTools = filterToolsForRuntime(ALL_TOOLS.filter((tool) => allowedTools.includes(tool.name)), childRuntime);
+    const subToolNames = subTools.map((tool) => tool.name);
+    const childTransientBundle = await buildTransientPromptBundle({
+        cwd,
+        tools: subTools,
+        profile: childRuntime.profile,
+        includeProjectInstructions: true,
+        includePlugins: false,
+        runtime: {
+            surface: 'subagent',
+            cwd,
+            workspaceId: ctx.workspaceId,
+            sessionId: ctx.sessionId,
+            interactiveAsk: childRuntime.interactiveAsk,
+            memoryAccess: childMemoryAccess,
+            currentUserInput: input.prompt,
+        },
+    }).catch(() => undefined);
     let lastPublishAt = 0;
     const label = input.description;
     const publish = (line, detail, force = false) => {
@@ -221,8 +309,8 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         ctx.reportProgress?.(line, detail);
     };
     // ---- 子 history：一条 system（压缩按 role 定位，必须存在）+ runQuery 自己 push 任务书 ----
-    const history = [
-        { role: 'system', content: await buildSubSystemPrompt(cwd, def, ALL_TOOLS) },
+    const history = deps.initialHistory?.length ? [...deps.initialHistory] : [
+        { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
     ];
     const historyLenBefore = history.length;
     const maxConcurrent = positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT) ?? ctx.subagentConfig?.maxConcurrent ?? 3;
@@ -353,20 +441,22 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
         publish('正在分析任务', { kind: 'subagent', phase: 'analyzing' }, true);
         const events = runQuery(input.prompt, {
             provider: ctx.provider,
+            runtimeContext: childRuntime,
             history,
             maxTurns,
-            allowedTools,
+            allowedTools: subToolNames,
             signal: combinedSignal,
             sessionState: createSessionState(), // 独立会话态，不与主循环/其他分身串扰
             toolGate: ctx.toolGate, // 继承主循环审批策略（不给可写子 agent 开审批后门）
             chat: deps.chat,
             executeTool: guardedExecute,
-            // 受监督宿主（Desktop）下把「监督位」透传给子 agent：子 agent 的浏览器 challenge（验证码/登录）
-            // 仍可由用户在可见浏览器里处理，与主 agent 行为一致；非监督（CLI/-p/TUI）不传 → 子 agent 同样
-            // 非阻塞、绝不挂起。conversationKey 留空以维持子 agent「不认领独立标签页」的既有行为。
-            ...(ctx.browserRun?.supervised
-                ? { browserRun: { conversationKey: '', runId: randomUUID(), supervised: true } }
-                : {}),
+            memoryContext: {
+                access: childMemoryAccess,
+                workspaceId: ctx.workspaceId,
+                sessionId: ctx.sessionId,
+            },
+            transientBundle: childTransientBundle,
+            promptCache: derivePromptCacheContext(ctx.promptCache, `subagent:${ctx.toolCallId ?? input.description}`),
             // 不传 transientContext：任务书必须自包含，父回合的瞬时上下文不该隐式泄入
         });
         for await (const ev of events) {
@@ -445,6 +535,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
     finally {
         stopTimeout();
         releaseLease?.();
+        await deps.captureHistory?.(history);
     }
     // ---- 结局映射（直接查 signal 状态，不依赖事件旗标） ----
     if (ownerCancelController.signal.aborted) {
@@ -505,6 +596,8 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             changedFiles.add(path);
         report += await finalizeWorktree(wt, label);
     }
+    // 覆盖度提取（客观，从 tool call 历史推导）——在截断之前，不受报告长度影响。
+    const coveredFiles = extractCoveredFiles(history, historyLenBefore);
     if (report.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
         report =
             report.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
@@ -523,6 +616,7 @@ export async function runAgentTask(input, signal, ctx, deps = {}) {
             failedToolCalls: toolFail,
             durationMs: Date.now() - startedAt,
             changedFiles: [...changedFiles].sort(),
+            coveredFiles,
             ...(wt && changedFiles.size > 0 ? {
                 worktree: {
                     id: wt.branch.replace(/^agent\//, ''),
@@ -538,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',
@@ -551,5 +767,5 @@ export const agentTool = {
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
     call,
-    callWithContext: runAgentTask,
+    callWithContext: runManagedAgentTask,
 };