minimal-agent 0.12.0 → 0.14.0

package/src/tools/agent/agent.ts

@@ -59,7 +59,7 @@ import {
   worktreeChangedFiles,
   worktreeDiffStat,
 } from './worktree.js';
-import { appendAgentEvent, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
+import { appendAgentEvent, attachAgentHistory, loadAgentRecord, saveAgentRecord, type AgentTaskRecord, type LiveAgentTask } from './agentTaskService.js';
 
 // ---------------- 0. 环内模块懒加载（见文件头「循环依赖纪律」） ----------------
 
@@ -120,7 +120,7 @@ const inputSchema = z.object({
   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>;
+export type AgentInput = z.infer<typeof inputSchema>;
 
 const parameters = toToolParameters(inputSchema);
 
@@ -227,7 +227,8 @@ export interface AgentTaskDeps {
   chat?: RunQueryOptions['chat'];
   executeTool?: RunQueryOptions['executeTool'];
   initialHistory?: RunQueryOptions['history'];
-  captureHistory?: (history:RunQueryOptions['history'])=>void|Promise<void>;
+  captureHistory?: (history: RunQueryOptions['history']) => void | Promise<void>;
+  onHistoryReady?: (history: RunQueryOptions['history']) => void;
   existingWorktree?: AgentWorktree;
   onWorktreeCreated?: (worktree: AgentWorktree) => void | Promise<void>;
 }
@@ -296,7 +297,10 @@ export async function runAgentTask(
   const { runQuery, ALL_TOOLS, executeTool } = await loadCore();
 
   const def = resolveAgentType(input.agent_type);
-  // 轮数上限：AGENT_TOOL_MAX_TURNS 可统一覆盖两种类型（默认 explore 50 / general 100）。
+  // 轮数上限：AGENT_TOOL_MAX_TURNS 可统一覆盖两种类型。默认值的唯一真值在
+  // config/configDefaults.ts::DEFAULT_SUBAGENTS_CONFIG（现为 explore 200 / general 100，
+  // 那里写了「只读的给宽、能写的给窄」的理由）。这条注释以前写着「explore 50」，
+  // 而代码早已是 200 —— 注释里复述数字必然漂移，所以现在只留指针。
   const maxTurns = positiveInt(process.env.AGENT_TOOL_MAX_TURNS)
     ?? (def.type === 'explore' ? ctx.subagentConfig?.exploreMaxTurns : ctx.subagentConfig?.generalMaxTurns)
     ?? def.maxTurns;
@@ -377,6 +381,7 @@ export async function runAgentTask(
   const history: RunQueryOptions['history'] = deps.initialHistory?.length ? [...deps.initialHistory] : [
     { role: 'system', content: await buildSubSystemPrompt(cwd, def, subTools) },
   ];
+  deps.onHistoryReady?.(history);
   const historyLenBefore = history.length;
   const maxConcurrent = positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT) ?? ctx.subagentConfig?.maxConcurrent ?? 3;
   let releaseLease: (() => void) | null = null;
@@ -469,8 +474,8 @@ export async function runAgentTask(
     let parsed: Record<string, unknown> = {};
     try { parsed = JSON.parse(args) as Record<string, unknown>; } catch { /* executeTool will report malformed input */ }
     const rawPath = typeof parsed.file_path === 'string' ? parsed.file_path : typeof parsed.path === 'string' ? parsed.path : undefined;
-    if (def.type === 'general' && !wt && name === 'Bash' && writeScopes[0] !== rootScope[0]) {
-      return { ok: false as const, error: '声明了局部 write_scopes 时禁止 Bash：无法可靠证明命令只写入批准范围。请改用文件工具或使用整个工作目录范围。' };
+    if (def.type === 'general' && !wt && ['Bash', 'ApplyPatch'].includes(name) && writeScopes[0] !== rootScope[0]) {
+      return { ok: false as const, error: `声明了局部 write_scopes 时禁止 ${name}：无法可靠证明一次调用只写入批准范围。请改用单文件工具或使用整个工作目录范围。` };
     }
     if (def.type === 'general' && rawPath) {
       if (isAbsolute(rawPath)) return { ok: false as const, error: `${name} 必须使用工作目录相对路径：${rawPath}` };
@@ -483,7 +488,14 @@ export async function runAgentTask(
         changedFiles.add(relative(cwd, resolve(cwd, rawPath)).split(sep).join('/'));
       }
     }
-    return baseExecute(name, args, s, c);
+    const result = await baseExecute(name, args, s, c);
+    if (result.metadata?.kind === 'file_activity') {
+      for (const file of result.metadata.files) {
+        if (['created', 'modified', 'generated', 'deleted'].includes(file.activity))
+          changedFiles.add(file.relativePath);
+      }
+    }
+    return result;
   };
 
   // ---- 事件消费：子 LoopEvent 一律不外泄，折算成统计 + 步内进度 ----
@@ -737,6 +749,7 @@ export async function runManagedAgentTask(
     abort,
     completion,
     events: new EventEmitter(),
+    inbox: [],
   };
   ctx.sessionState.agentTasks.tasks.set(id, task);
   await saveAgentRecord(ctx, task);
@@ -769,6 +782,7 @@ export async function runManagedAgentTask(
           await saveAgentRecord(ctx, task);
         },
         captureHistory: (history) => { captured = [...history]; },
+        onHistoryReady: (history) => attachAgentHistory(task, history),
       });
       task.result = result;
       task.history = captured;

package/src/tools/agent/agentControl.js

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { runManagedAgentTask } from './agent.js';
+import { appendAgentEvent, enqueueAgentMessage, getLiveAgentTask, listAgentRecords, loadAgentRecord, saveAgentRecord, } from './agentTaskService.js';
+const agentId = z.string().regex(/^agent_[0-9a-f-]{36}$/i);
+function needsContext(context) {
+    if (!context.sessionState)
+        return { ok: false, error: 'Agent 控制工具需要当前 Session 运行状态。' };
+    return undefined;
+}
+function snapshot(record) {
+    return {
+        agent_id: record.id,
+        status: record.status,
+        description: record.description,
+        progress: record.progress,
+        created_at: record.createdAt,
+        updated_at: record.updatedAt,
+        result: record.result
+            ? record.result.ok
+                ? record.result.content.slice(0, 4_000)
+                : `Error: ${record.result.error.slice(0, 4_000)}`
+            : undefined,
+    };
+}
+const messageSchema = z.object({
+    agent_id: agentId,
+    message: z.string().min(1).max(100_000),
+});
+export const agentMessageTool = {
+    name: 'AgentMessage',
+    description: 'Sends additional context or a correction to one running sub-agent by stable agent_id. ' +
+        'The message is inserted at the next model boundary without cancelling its current tool call. ' +
+        'Use AgentFollowup instead when the agent is already idle or completed.',
+    inputSchema: messageSchema,
+    parameters: toToolParameters(messageSchema),
+    isReadOnly: false,
+    isConcurrencySafe: true,
+    call: async () => ({
+        ok: false,
+        error: 'AgentMessage requires session context',
+    }),
+    callWithContext: async (input, _signal, context) => {
+        const missing = needsContext(context);
+        if (missing)
+            return missing;
+        const task = getLiveAgentTask(context.sessionState.agentTasks, input.agent_id);
+        if (!task || task.status !== 'running') {
+            const saved = await loadAgentRecord(context, input.agent_id);
+            return saved
+                ? {
+                    ok: false,
+                    error: `Agent ${input.agent_id} 当前为 ${saved.status}；请使用 AgentFollowup 启动后续回合。`,
+                }
+                : { ok: false, error: `当前 Session 中不存在 Agent ${input.agent_id}` };
+        }
+        enqueueAgentMessage(task, input.message);
+        await saveAgentRecord(context, task);
+        await appendAgentEvent(context, task.id, {
+            phase: 'message',
+            message: input.message,
+        });
+        return {
+            ok: true,
+            content: `消息已发送给 ${task.id}，将在下一个模型边界生效。`,
+        };
+    },
+};
+const listSchema = z.object({
+    include_completed: z.boolean().optional(),
+});
+export const agentListTool = {
+    name: 'AgentList',
+    description: 'Lists sub-agents owned by the current Session, including stable IDs, status and latest progress.',
+    inputSchema: listSchema,
+    parameters: toToolParameters(listSchema),
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    call: async () => ({
+        ok: false,
+        error: 'AgentList requires session context',
+    }),
+    callWithContext: async (input, _signal, context) => {
+        const missing = needsContext(context);
+        if (missing)
+            return missing;
+        const records = (await listAgentRecords(context)).filter((record) => input.include_completed !== false || record.status === 'running');
+        return {
+            ok: true,
+            content: records.length
+                ? JSON.stringify(records.map(snapshot), null, 2)
+                : '当前 Session 没有符合条件的子 Agent。',
+        };
+    },
+};
+const waitSchema = z.object({
+    agent_ids: z.array(agentId).min(1).max(8),
+    timeout_ms: z.number().int().min(0).max(120_000).optional(),
+});
+export const agentWaitTool = {
+    name: 'AgentWait',
+    description: 'Waits efficiently until any selected running sub-agent finishes or the timeout expires, then returns fresh snapshots for all selected IDs. Do not poll repeatedly.',
+    inputSchema: waitSchema,
+    parameters: toToolParameters(waitSchema),
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    interruptBehavior: () => 'cancel',
+    call: async () => ({
+        ok: false,
+        error: 'AgentWait requires session context',
+    }),
+    callWithContext: async (input, signal, context) => {
+        const missing = needsContext(context);
+        if (missing)
+            return missing;
+        const live = input.agent_ids
+            .map((id) => getLiveAgentTask(context.sessionState.agentTasks, id))
+            .filter((task) => Boolean(task?.status === 'running'));
+        const timeoutMs = input.timeout_ms ?? 30_000;
+        if (live.length && timeoutMs > 0) {
+            let timer;
+            let onAbort;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+                timer.unref?.();
+            });
+            const aborted = new Promise((resolve) => {
+                if (!signal)
+                    return;
+                onAbort = () => resolve();
+                if (signal.aborted)
+                    resolve();
+                else
+                    signal.addEventListener('abort', onAbort, { once: true });
+            });
+            await Promise.race([
+                ...live.map((task) => task.completion),
+                timeout,
+                aborted,
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (signal && onAbort)
+                signal.removeEventListener('abort', onAbort);
+            if (signal?.aborted)
+                return { ok: false, error: 'aborted' };
+        }
+        const records = [];
+        const missingIds = [];
+        for (const id of input.agent_ids) {
+            const record = getLiveAgentTask(context.sessionState.agentTasks, id) ??
+                (await loadAgentRecord(context, id));
+            if (record)
+                records.push(record);
+            else
+                missingIds.push(id);
+        }
+        return {
+            ok: true,
+            content: JSON.stringify({ agents: records.map(snapshot), missing: missingIds }, null, 2),
+        };
+    },
+};
+const interruptSchema = z.object({ agent_id: agentId });
+export const agentInterruptTool = {
+    name: 'AgentInterrupt',
+    description: 'Interrupts one running sub-agent owned by the current Session. Its private history, progress and worktree are preserved for a later AgentFollowup.',
+    inputSchema: interruptSchema,
+    parameters: toToolParameters(interruptSchema),
+    isReadOnly: false,
+    isConcurrencySafe: true,
+    call: async () => ({
+        ok: false,
+        error: 'AgentInterrupt requires session context',
+    }),
+    callWithContext: async (input, _signal, context) => {
+        const missing = needsContext(context);
+        if (missing)
+            return missing;
+        const live = getLiveAgentTask(context.sessionState.agentTasks, input.agent_id);
+        if (!live || live.status !== 'running') {
+            const saved = await loadAgentRecord(context, input.agent_id);
+            return saved
+                ? {
+                    ok: true,
+                    content: `Agent ${input.agent_id} 已经是 ${saved.status}，未执行中断。`,
+                }
+                : { ok: false, error: `当前 Session 中不存在 Agent ${input.agent_id}` };
+        }
+        const previous = live.status;
+        live.abort.abort(new Error('interrupted-by-parent-agent'));
+        await Promise.race([
+            live.completion,
+            new Promise((resolve) => setTimeout(resolve, 5_000)),
+        ]);
+        return {
+            ok: true,
+            content: `已中断 ${live.id}（先前状态：${previous}；当前状态：${live.status}）。`,
+        };
+    },
+};
+const followupSchema = z.object({
+    agent_id: agentId,
+    message: z.string().min(1).max(100_000),
+    run_in_background: z.boolean().optional(),
+});
+export const agentFollowupTool = {
+    name: 'AgentFollowup',
+    description: 'Adds a follow-up task to a stable sub-agent. If it is running, delivers the message at the next model boundary; if idle, resumes its persisted private history and starts a new turn.',
+    inputSchema: followupSchema,
+    parameters: toToolParameters(followupSchema),
+    isReadOnly: false,
+    isConcurrencySafe: true,
+    interruptBehavior: () => 'block',
+    call: async () => ({
+        ok: false,
+        error: 'AgentFollowup requires session context',
+    }),
+    callWithContext: async (input, signal, context) => {
+        const missing = needsContext(context);
+        if (missing)
+            return missing;
+        const live = getLiveAgentTask(context.sessionState.agentTasks, input.agent_id);
+        if (live?.status === 'running') {
+            enqueueAgentMessage(live, input.message);
+            await saveAgentRecord(context, live);
+            await appendAgentEvent(context, live.id, {
+                phase: 'followup',
+                message: input.message,
+            });
+            return { ok: true, content: `后续任务已发送给运行中的 ${live.id}。` };
+        }
+        const saved = await loadAgentRecord(context, input.agent_id);
+        if (!saved)
+            return {
+                ok: false,
+                error: `当前 Session 中不存在 Agent ${input.agent_id}`,
+            };
+        return runManagedAgentTask({
+            description: saved.description,
+            prompt: input.message,
+            resume_agent_id: input.agent_id,
+            run_in_background: input.run_in_background ?? true,
+        }, signal, context);
+    },
+};

package/src/tools/agent/agentControl.ts

@@ -0,0 +1,284 @@
+import { z } from 'zod';
+
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { runManagedAgentTask } from './agent.js';
+import {
+  type AgentTaskRecord,
+  appendAgentEvent,
+  enqueueAgentMessage,
+  getLiveAgentTask,
+  listAgentRecords,
+  loadAgentRecord,
+  saveAgentRecord,
+} from './agentTaskService.js';
+
+const agentId = z.string().regex(/^agent_[0-9a-f-]{36}$/i);
+
+function needsContext(context: ToolCallContext): ToolResult | undefined {
+  if (!context.sessionState)
+    return { ok: false, error: 'Agent 控制工具需要当前 Session 运行状态。' };
+  return undefined;
+}
+
+function snapshot(record: AgentTaskRecord) {
+  return {
+    agent_id: record.id,
+    status: record.status,
+    description: record.description,
+    progress: record.progress,
+    created_at: record.createdAt,
+    updated_at: record.updatedAt,
+    result: record.result
+      ? record.result.ok
+        ? record.result.content.slice(0, 4_000)
+        : `Error: ${record.result.error.slice(0, 4_000)}`
+      : undefined,
+  };
+}
+
+const messageSchema = z.object({
+  agent_id: agentId,
+  message: z.string().min(1).max(100_000),
+});
+
+export const agentMessageTool: Tool<z.infer<typeof messageSchema>> = {
+  name: 'AgentMessage',
+  description:
+    'Sends additional context or a correction to one running sub-agent by stable agent_id. ' +
+    'The message is inserted at the next model boundary without cancelling its current tool call. ' +
+    'Use AgentFollowup instead when the agent is already idle or completed.',
+  inputSchema: messageSchema,
+  parameters: toToolParameters(messageSchema),
+  isReadOnly: false,
+  isConcurrencySafe: true,
+  call: async () => ({
+    ok: false,
+    error: 'AgentMessage requires session context',
+  }),
+  callWithContext: async (input, _signal, context) => {
+    const missing = needsContext(context);
+    if (missing) return missing;
+    const task = getLiveAgentTask(
+      context.sessionState!.agentTasks,
+      input.agent_id,
+    );
+    if (!task || task.status !== 'running') {
+      const saved = await loadAgentRecord(context, input.agent_id);
+      return saved
+        ? {
+            ok: false,
+            error: `Agent ${input.agent_id} 当前为 ${saved.status}；请使用 AgentFollowup 启动后续回合。`,
+          }
+        : { ok: false, error: `当前 Session 中不存在 Agent ${input.agent_id}` };
+    }
+    enqueueAgentMessage(task, input.message);
+    await saveAgentRecord(context, task);
+    await appendAgentEvent(context, task.id, {
+      phase: 'message',
+      message: input.message,
+    });
+    return {
+      ok: true,
+      content: `消息已发送给 ${task.id}，将在下一个模型边界生效。`,
+    };
+  },
+};
+
+const listSchema = z.object({
+  include_completed: z.boolean().optional(),
+});
+
+export const agentListTool: Tool<z.infer<typeof listSchema>> = {
+  name: 'AgentList',
+  description:
+    'Lists sub-agents owned by the current Session, including stable IDs, status and latest progress.',
+  inputSchema: listSchema,
+  parameters: toToolParameters(listSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  call: async () => ({
+    ok: false,
+    error: 'AgentList requires session context',
+  }),
+  callWithContext: async (input, _signal, context) => {
+    const missing = needsContext(context);
+    if (missing) return missing;
+    const records = (await listAgentRecords(context)).filter(
+      (record) =>
+        input.include_completed !== false || record.status === 'running',
+    );
+    return {
+      ok: true,
+      content: records.length
+        ? JSON.stringify(records.map(snapshot), null, 2)
+        : '当前 Session 没有符合条件的子 Agent。',
+    };
+  },
+};
+
+const waitSchema = z.object({
+  agent_ids: z.array(agentId).min(1).max(8),
+  timeout_ms: z.number().int().min(0).max(120_000).optional(),
+});
+
+export const agentWaitTool: Tool<z.infer<typeof waitSchema>> = {
+  name: 'AgentWait',
+  description:
+    'Waits efficiently until any selected running sub-agent finishes or the timeout expires, then returns fresh snapshots for all selected IDs. Do not poll repeatedly.',
+  inputSchema: waitSchema,
+  parameters: toToolParameters(waitSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  interruptBehavior: () => 'cancel',
+  call: async () => ({
+    ok: false,
+    error: 'AgentWait requires session context',
+  }),
+  callWithContext: async (input, signal, context) => {
+    const missing = needsContext(context);
+    if (missing) return missing;
+    const live = input.agent_ids
+      .map((id) => getLiveAgentTask(context.sessionState!.agentTasks, id))
+      .filter((task): task is NonNullable<typeof task> =>
+        Boolean(task?.status === 'running'),
+      );
+    const timeoutMs = input.timeout_ms ?? 30_000;
+    if (live.length && timeoutMs > 0) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let onAbort: (() => void) | undefined;
+      const timeout = new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        timer.unref?.();
+      });
+      const aborted = new Promise<void>((resolve) => {
+        if (!signal) return;
+        onAbort = () => resolve();
+        if (signal.aborted) resolve();
+        else signal.addEventListener('abort', onAbort, { once: true });
+      });
+      await Promise.race([
+        ...live.map((task) => task.completion),
+        timeout,
+        aborted,
+      ]);
+      if (timer) clearTimeout(timer);
+      if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+      if (signal?.aborted) return { ok: false, error: 'aborted' };
+    }
+    const records: AgentTaskRecord[] = [];
+    const missingIds: string[] = [];
+    for (const id of input.agent_ids) {
+      const record =
+        getLiveAgentTask(context.sessionState!.agentTasks, id) ??
+        (await loadAgentRecord(context, id));
+      if (record) records.push(record);
+      else missingIds.push(id);
+    }
+    return {
+      ok: true,
+      content: JSON.stringify(
+        { agents: records.map(snapshot), missing: missingIds },
+        null,
+        2,
+      ),
+    };
+  },
+};
+
+const interruptSchema = z.object({ agent_id: agentId });
+
+export const agentInterruptTool: Tool<z.infer<typeof interruptSchema>> = {
+  name: 'AgentInterrupt',
+  description:
+    'Interrupts one running sub-agent owned by the current Session. Its private history, progress and worktree are preserved for a later AgentFollowup.',
+  inputSchema: interruptSchema,
+  parameters: toToolParameters(interruptSchema),
+  isReadOnly: false,
+  isConcurrencySafe: true,
+  call: async () => ({
+    ok: false,
+    error: 'AgentInterrupt requires session context',
+  }),
+  callWithContext: async (input, _signal, context) => {
+    const missing = needsContext(context);
+    if (missing) return missing;
+    const live = getLiveAgentTask(
+      context.sessionState!.agentTasks,
+      input.agent_id,
+    );
+    if (!live || live.status !== 'running') {
+      const saved = await loadAgentRecord(context, input.agent_id);
+      return saved
+        ? {
+            ok: true,
+            content: `Agent ${input.agent_id} 已经是 ${saved.status}，未执行中断。`,
+          }
+        : { ok: false, error: `当前 Session 中不存在 Agent ${input.agent_id}` };
+    }
+    const previous = live.status;
+    live.abort.abort(new Error('interrupted-by-parent-agent'));
+    await Promise.race([
+      live.completion,
+      new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
+    ]);
+    return {
+      ok: true,
+      content: `已中断 ${live.id}（先前状态：${previous}；当前状态：${live.status}）。`,
+    };
+  },
+};
+
+const followupSchema = z.object({
+  agent_id: agentId,
+  message: z.string().min(1).max(100_000),
+  run_in_background: z.boolean().optional(),
+});
+
+export const agentFollowupTool: Tool<z.infer<typeof followupSchema>> = {
+  name: 'AgentFollowup',
+  description:
+    'Adds a follow-up task to a stable sub-agent. If it is running, delivers the message at the next model boundary; if idle, resumes its persisted private history and starts a new turn.',
+  inputSchema: followupSchema,
+  parameters: toToolParameters(followupSchema),
+  isReadOnly: false,
+  isConcurrencySafe: true,
+  interruptBehavior: () => 'block',
+  call: async () => ({
+    ok: false,
+    error: 'AgentFollowup requires session context',
+  }),
+  callWithContext: async (input, signal, context) => {
+    const missing = needsContext(context);
+    if (missing) return missing;
+    const live = getLiveAgentTask(
+      context.sessionState!.agentTasks,
+      input.agent_id,
+    );
+    if (live?.status === 'running') {
+      enqueueAgentMessage(live, input.message);
+      await saveAgentRecord(context, live);
+      await appendAgentEvent(context, live.id, {
+        phase: 'followup',
+        message: input.message,
+      });
+      return { ok: true, content: `后续任务已发送给运行中的 ${live.id}。` };
+    }
+    const saved = await loadAgentRecord(context, input.agent_id);
+    if (!saved)
+      return {
+        ok: false,
+        error: `当前 Session 中不存在 Agent ${input.agent_id}`,
+      };
+    return runManagedAgentTask(
+      {
+        description: saved.description,
+        prompt: input.message,
+        resume_agent_id: input.agent_id,
+        run_in_background: input.run_in_background ?? true,
+      },
+      signal,
+      context,
+    );
+  },
+};

package/src/tools/agent/agentTaskService.js

@@ -1,4 +1,4 @@
-import { appendFile, mkdir } from 'node:fs/promises';
+import { appendFile, mkdir, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readRuntimeJson, sessionRuntimeDir, withRuntimeFileLock, writeRuntimeJson, } from '../../session/runtimeStore.js';
 export function createAgentTaskState() {
@@ -49,6 +49,45 @@ export async function loadAgentRecord(ctx, id) {
 export function getLiveAgentTask(state, id) {
     return state?.tasks.get(id);
 }
+/** List the durable tasks owned by this Session, with process-local state winning. */
+export async function listAgentRecords(ctx) {
+    const root = join(sessionRuntimeDir(ctx), 'agents');
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const records = new Map();
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !/^agent_[0-9a-f-]{36}$/i.test(entry.name))
+            continue;
+        const record = await loadAgentRecord(ctx, entry.name);
+        if (record)
+            records.set(record.id, record);
+    }
+    for (const live of ctx.sessionState?.agentTasks.tasks.values() ?? [])
+        records.set(live.id, live);
+    return [...records.values()].sort((a, b) => b.updatedAt - a.updatedAt);
+}
+export function agentMessage(message) {
+    return {
+        role: 'user',
+        content: `[主 Agent 后续消息]\n${message}`,
+        timestamp: Date.now(),
+    };
+}
+/** Deliver at the next model-message boundary without aborting the active turn. */
+export function enqueueAgentMessage(task, message) {
+    if (task.history)
+        task.history.push(agentMessage(message));
+    else
+        task.inbox.push(message);
+    task.updatedAt = Date.now();
+    task.events.emit('change');
+}
+/** Attach the live private history and flush messages accepted during startup. */
+export function attachAgentHistory(task, history) {
+    task.history = history;
+    for (const message of task.inbox.splice(0))
+        history.push(agentMessage(message));
+    task.events.emit('change');
+}
 export async function stopAllAgentTasks(state) {
     const running = [...state.tasks.values()].filter((t) => t.status === 'running');
     running.forEach((t) => t.abort.abort());