minimal-agent 0.10.0 → 0.12.0

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();
+}

package/src/tools/agent/agentTypes.js

@@ -16,31 +16,43 @@
 /**
  * 任何 agent_type 都排除的工具：
  *   - Agent：防递归 fork（子 agent 再 fork 子 agent，深度失控）。
- *   - Advisor：每个子 runQuery 有独立的 advisorCalls 预算（{used:0,max:2}），
- *     N 个并行分身 = 最多 2N 次顾问调用，成本失控；两次规则后再议。
+ *   - Advisor：子任务不咨询第二模型，避免 N 个并行分身放大成本。
  */
 export const SUBAGENT_EXCLUDED_TOOLS = [
     'Agent',
     'Advisor',
+    // 子任务只向主 Agent 汇报；正式用户交付由主 Agent 统一收口，避免重复结果卡。
+    'PresentResult',
+    'RememberMemory',
+    'UpdateMemory',
+    'ForgetMemory',
+    'SetPersona',
+    'ClearPersona',
+    'ConfirmMemory',
 ];
 /** explore 白名单（显式列名，可预期）：严格只读。 */
 export const EXPLORE_ALLOWED_TOOLS = [
     'Read',
     'Glob',
     'Grep',
+    'Snip',
+    'LSP',
+    'Skill',
     'WebSearch',
     'WebFetch',
     'WebBrowser',
+    'RecallMemory',
+    'ListMemories',
+    'ReviewMemories',
+    'SearchConversations',
+    'TaskGet',
+    'TaskList',
 ];
 /** 借鉴官方 EXPLORE_AGENT「READ-ONLY MODE」文案中文化。 */
 const EXPLORE_APPENDIX = `# 本次子任务类型：只读调研（explore）
-这是一次只读探索任务：你没有 Edit/Write/Bash/Download 等写工具，严禁尝试创建、修改或删除项目文件。
-你的产出就是调研报告文本本身——
-把结论、关键证据（文件路径 + 行号）、以及没查到的缺口写清楚。`;
+严格使用已提供的只读工具。报告给出结论、关键证据和没查到的缺口。`;
 const GENERAL_APPENDIX = `# 本次子任务类型：读写执行（general）
-你可以读写文件、执行命令。写盘前照常先 Read（内核有覆盖保护）。
-只有在关键输入缺失、高风险取舍或无法安全继续时才使用 AskUserQuestion；能从代码、上下文或合理默认值判断时不要打断用户。每个子任务最多提问两次。
-只做任务书里交代的事，不要顺手扩大改动范围；改完在报告里列出动过的每个文件。`;
+只做任务书范围内的修改；报告列出改动文件和验证结果。`;
 const EXPLORE_DEF = {
     type: 'explore',
     resolveAllowedTools: (all) => all.filter((n) => EXPLORE_ALLOWED_TOOLS.includes(n)),

package/src/tools/agent/agentTypes.ts

@@ -0,0 +1,94 @@
+/**
+ * ============================================================
+ *  src/tools/agent/agentTypes.ts —— 内置子 agent 类型（类型即数据）
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 官方 builtInAgents.ts 的「agent 定义 = 一段提示词附加段
+ *  + 工具白名单 + 轮数上限」模式，按 minimal-agent 减法原则只保留两种：
+ *
+ *    - explore（默认）：严格只读收集调研，不包含任何会写盘的工具。
+ *    - general：可读写执行（松权限裁决：写工具全放开）。并行时各子任务
+ *      必须写互不相交的文件，或经 isolation:'worktree' 走独立分支。
+ *
+ *  不做 plan 类型：explore + 任务书里一句「最后列出关键文件清单」即可表达
+ *  （两次规则：真实需要出现两次再议）。
+ * ============================================================
+ */
+
+export type AgentTypeName = 'explore' | 'general';
+
+export interface AgentTypeDef {
+  type: AgentTypeName;
+  /** 计算子 agent 的工具白名单（下发给模型的清单，硬防线在 guardedExecute） */
+  resolveAllowedTools(allToolNames: readonly string[]): string[];
+  /**
+   * 子任务轮数上限（默认值，`AGENT_TOOL_MAX_TURNS` env 可统一覆盖，见 agent.ts）。
+   * 宁宽勿窄：初版 15/30 被真实审计型子任务撞穿——全部轮次烧在读文件上，
+   * 报告还没写就被截断零产出；截断的浪费远大于多留余量的成本（上限非预订）。
+   */
+  maxTurns: number;
+  /** agent_type 专属提示词附加段（拼在子 agent system prompt 末尾） */
+  promptAppendix: string;
+}
+
+/**
+ * 任何 agent_type 都排除的工具：
+ *   - Agent：防递归 fork（子 agent 再 fork 子 agent，深度失控）。
+ *   - Advisor：子任务不咨询第二模型，避免 N 个并行分身放大成本。
+ */
+export const SUBAGENT_EXCLUDED_TOOLS: readonly string[] = [
+  'Agent',
+  'Advisor',
+  // 子任务只向主 Agent 汇报；正式用户交付由主 Agent 统一收口，避免重复结果卡。
+  'PresentResult',
+  'RememberMemory',
+  'UpdateMemory',
+  'ForgetMemory',
+  'SetPersona',
+  'ClearPersona',
+  'ConfirmMemory',
+];
+
+/** explore 白名单（显式列名，可预期）：严格只读。 */
+export const EXPLORE_ALLOWED_TOOLS: readonly string[] = [
+  'Read',
+  'Glob',
+  'Grep',
+  'Snip',
+  'LSP',
+  'Skill',
+  'WebSearch',
+  'WebFetch',
+  'WebBrowser',
+  'RecallMemory',
+  'ListMemories',
+  'ReviewMemories',
+  'SearchConversations',
+  'TaskGet',
+  'TaskList',
+];
+
+/** 借鉴官方 EXPLORE_AGENT「READ-ONLY MODE」文案中文化。 */
+const EXPLORE_APPENDIX = `# 本次子任务类型：只读调研（explore）
+严格使用已提供的只读工具。报告给出结论、关键证据和没查到的缺口。`;
+
+const GENERAL_APPENDIX = `# 本次子任务类型：读写执行（general）
+只做任务书范围内的修改；报告列出改动文件和验证结果。`;
+
+const EXPLORE_DEF: AgentTypeDef = {
+  type: 'explore',
+  resolveAllowedTools: (all) => all.filter((n) => EXPLORE_ALLOWED_TOOLS.includes(n)),
+  maxTurns: 50,
+  promptAppendix: EXPLORE_APPENDIX,
+};
+
+const GENERAL_DEF: AgentTypeDef = {
+  type: 'general',
+  resolveAllowedTools: (all) => all.filter((n) => !SUBAGENT_EXCLUDED_TOOLS.includes(n)),
+  maxTurns: 100,
+  promptAppendix: GENERAL_APPENDIX,
+};
+
+/** 未知/缺省一律回落 explore（最安全的默认：只读）。 */
+export function resolveAgentType(name: string | undefined): AgentTypeDef {
+  return name === 'general' ? GENERAL_DEF : EXPLORE_DEF;
+}

package/src/tools/agent/coordinator.ts

@@ -0,0 +1,111 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+interface Waiter {
+  cwd: string;
+  scopes: string[];
+  maxConcurrent: number;
+  onStatus?: (status: LeaseStatus) => void;
+  signal?: AbortSignal;
+  onAbort?: () => void;
+  resolve: (release: () => void) => void;
+  reject: (error: Error) => void;
+}
+
+interface ActiveLease { cwd: string; scopes: string[] }
+
+const active: ActiveLease[] = [];
+const waiters: Waiter[] = [];
+let running = 0;
+
+export interface LeaseStatus {
+  phase: 'queued' | 'acquired';
+  queuePosition?: number;
+  activeCount: number;
+  maxConcurrent: number;
+}
+
+function overlaps(a: string, b: string): boolean {
+  return a === b || a.startsWith(`${b}${sep}`) || b.startsWith(`${a}${sep}`);
+}
+
+function conflicts(cwd: string, scopes: string[]): boolean {
+  return active.some((lease) => lease.cwd === cwd && lease.scopes.some((left) => scopes.some((right) => overlaps(left, right))));
+}
+
+function publishQueue(): void {
+  waiters.forEach((waiter, index) => waiter.onStatus?.({
+    phase: 'queued',
+    queuePosition: index + 1,
+    activeCount: running,
+    maxConcurrent: waiter.maxConcurrent,
+  }));
+}
+
+function drain(): void {
+  for (let i = 0; i < waiters.length;) {
+    const waiter = waiters[i]!;
+    if (running >= waiter.maxConcurrent) { i++; continue; }
+    if (conflicts(waiter.cwd, waiter.scopes)) { i++; continue; }
+    waiters.splice(i, 1);
+    if (waiter.onAbort) waiter.signal?.removeEventListener('abort', waiter.onAbort);
+    running++;
+    const lease = { cwd: waiter.cwd, scopes: waiter.scopes };
+    active.push(lease);
+    waiter.onStatus?.({ phase: 'acquired', activeCount: running, maxConcurrent: waiter.maxConcurrent });
+    waiter.resolve(() => {
+      const index = active.indexOf(lease);
+      if (index >= 0) active.splice(index, 1);
+      running = Math.max(0, running - 1);
+      drain();
+    });
+  }
+  publishQueue();
+}
+
+export async function normalizeWriteScopes(cwd: string, rawScopes: readonly string[] | undefined): Promise<string[]> {
+  const lexicalRoot = resolve(cwd);
+  const physicalRoot = await realpath(lexicalRoot).catch(() => lexicalRoot);
+  if (!rawScopes?.length) return [physicalRoot];
+  const normalized = new Set<string>();
+  for (const raw of rawScopes) {
+    const value = raw.trim();
+    if (!value || isAbsolute(value)) throw new Error(`write_scopes 必须是工作目录内的相对路径：${raw}`);
+    const lexical = resolve(lexicalRoot, value);
+    const rel = relative(lexicalRoot, lexical);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error(`write_scopes 越过工作目录：${raw}`);
+    const physical = await realpath(lexical).catch(async () => {
+      const parent = await realpath(resolve(lexical, '..')).catch(() => physicalRoot);
+      return resolve(parent, lexical.split(sep).at(-1) ?? '');
+    });
+    const physicalRel = relative(physicalRoot, physical);
+    if (physicalRel === '..' || physicalRel.startsWith(`..${sep}`) || isAbsolute(physicalRel)) throw new Error(`write_scopes 经过符号链接越过工作目录：${raw}`);
+    normalized.add(physical);
+  }
+  return [...normalized].sort();
+}
+
+export async function acquireSubagentLease(
+  cwd: string,
+  scopes: string[],
+  maxConcurrent = 3,
+  options: { signal?: AbortSignal; onStatus?: (status: LeaseStatus) => void } = {},
+): Promise<() => void> {
+  const safeMax = Math.max(1, Math.min(8, maxConcurrent));
+  return new Promise((resolveLease, reject) => {
+    if (options.signal?.aborted) return reject(new DOMException('Aborted', 'AbortError'));
+    const waiter: Waiter = { cwd, scopes, maxConcurrent: safeMax, onStatus: options.onStatus, signal: options.signal, resolve: resolveLease, reject };
+    waiter.onAbort = () => {
+      const index = waiters.indexOf(waiter);
+      if (index >= 0) waiters.splice(index, 1);
+      publishQueue();
+      reject(new DOMException('Aborted', 'AbortError'));
+    };
+    options.signal?.addEventListener('abort', waiter.onAbort, { once: true });
+    waiters.push(waiter);
+    // 不在这里 publishQueue：立即拿到租约的 waiter 会被 drain 直接报 'acquired'，
+    // 抢先报一次 'queued' 会让每个子任务都闪一下幻影「排队中」；真排队者由 drain
+    // 结尾的 publishQueue 覆盖。
+    drain();
+  });
+}