@ai-setting/roy-agent-core 1.5.15-test → 1.5.17-beta.1

package/dist/shared/@ai-setting/roy-agent-core-vf215qfv.js

@@ -0,0 +1,812 @@
+import {
+  TaskHookPoints
+} from "./roy-agent-core-92z6t4he.js";
+import {
+  globalHookManager
+} from "./roy-agent-core-gjq1yk68.js";
+import {
+  createLogger,
+  init_logger
+} from "./roy-agent-core-44hnfb02.js";
+
+// src/env/task/delegate/delegate-tool.ts
+init_logger();
+import { z } from "zod";
+var logger = createLogger("task:delegate");
+var BackgroundTaskEventTypes = {
+  STARTED: "task.background.started",
+  PROGRESS: "task.background.progress",
+  COMPLETED: "task.background.completed",
+  FAILED: "task.background.failed",
+  TIMEOUT: "task.background.timeout",
+  STOPPED: "task.background.stopped"
+};
+var builtInSubAgents = [
+  {
+    id: "general",
+    name: "general",
+    mode: "subagent",
+    description: "General-purpose agent for researching complex questions and executing multi-step tasks.",
+    promptOverride: `You are a subagent created by the main agent to handle a specific task.
+
+## Your Role
+- You were created to handle: {task_description}
+- Complete this task. That's your entire purpose.
+- You are NOT the main agent. Don't try to be.
+
+## Task Context Awareness (Required Behavior)
+
+**IMPORTANT: Before starting any work, you MUST gather task context to avoid working with outdated or missing information.**
+
+1. **Read task details first**: Use \`task_get\` to read the task's:
+   - \`description\`: Detailed description of what needs to be done
+   - \`goals_and_expected_deliverables\`: Clear success criteria and expected outputs
+   - \`current_status\`: Current work progress
+   - \`parent_task_id\`: If exists, this is a sub-task
+
+2. **Read recent operations**: Use \`task_operation_list\` to get the last ~15 operation records
+   - These provide history, progress, decisions, and context from previous work
+
+3. **Read parent task context** (if \`parent_task_id\` exists):
+   - Use \`task_get\` to read the parent task's description and goals
+   - Use \`task_operation_list\` to get parent's recent operations
+   - This forms the overall task background and ensures alignment
+
+**Why this matters**: 
+- The main agent may have made critical decisions recorded in operations
+- Parent task goals provide the broader context for your sub-task
+- Without this context, you risk working on wrong/outdated goals
+
+## Rules
+1. **Gather context first** - Always read task details and operations before starting
+2. **Stay focused** - Do your assigned task, nothing else
+3. **Complete the task** - Your final message will be automatically reported to the main agent
+4. **Don't initiate** - No heartbeats, no proactive actions, no side quests
+5. **Be ephemeral** - You may be terminated after task completion. That's fine.
+6. **No nested delegation** - Do NOT use delegate_task or stop_task tools. Complete the task yourself.
+
+## Execution
+- Use the available tools to complete the task
+- If you need more information, ask the main agent through the result
+- Return a clear summary of what you did and the results`,
+    deniedTools: ["delegate_task", "stop_task"]
+  },
+  {
+    id: "explore",
+    name: "explore",
+    mode: "subagent",
+    description: "Fast agent specialized for exploring codebases, finding files, and searching for patterns.",
+    allowedTools: ["glob", "grep", "read", "bash"],
+    deniedTools: ["delegate_task", "stop_task"]
+  },
+  {
+    id: "file_agent",
+    name: "file_agent",
+    mode: "subagent",
+    description: "File operation expert, skilled at reading, writing, searching and organizing files.",
+    allowedTools: ["file_read", "file_write", "file_glob", "grep", "glob", "read"],
+    deniedTools: ["delegate_task", "stop_task"]
+  },
+  {
+    id: "web_search_agent",
+    name: "web_search_agent",
+    mode: "subagent",
+    description: "Web search expert, using Exa search engine to get latest information.",
+    allowedTools: ["exa_web_search_exa"],
+    deniedTools: ["delegate_task", "stop_task"]
+  }
+];
+function getSubAgentSpec(id) {
+  return builtInSubAgents.find((agent) => agent.id === id);
+}
+function getSubAgentToolDescription() {
+  return builtInSubAgents.map((agent) => `- ${agent.id}: ${agent.description}`).join(`
+`);
+}
+function ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools) {
+  let agentInstance = agentComponent.getAgent(subagentType);
+  if (!agentInstance) {
+    const agentConfig = {
+      type: "sub",
+      systemPrompt: basePrompt
+    };
+    if (subAgent?.allowedTools && subAgent.allowedTools.length > 0) {
+      agentConfig.allowedTools = subAgent.allowedTools;
+    }
+    if (deniedTools.length > 0) {
+      agentConfig.deniedTools = deniedTools;
+    }
+    agentInstance = agentComponent.registerAgent(subagentType, agentConfig);
+    logger.debug(`[delegate] Registered subagent: ${subagentType}`);
+  }
+  return agentInstance;
+}
+var DelegateToolParameters = z.object({
+  description: z.string().describe("A short (3-5 words) description of the task"),
+  prompt: z.string().describe("The task for the agent to perform"),
+  subagent_type: z.string().describe("The type of specialized agent to use for this task").default("general"),
+  background: z.boolean().describe("Whether to run the task in background. If true, returns immediately and notifies when complete (default: false)").default(false),
+  timeout: z.number().describe("Task timeout in milliseconds. If set, task will be terminated after timeout (optional)").optional(),
+  cleanup: z.enum(["delete", "keep"]).describe("Whether to delete sub session after completion. 'delete' removes the session, 'keep' retains it (default: keep)").default("keep").optional(),
+  task_id: z.number().describe("Optional task ID to associate with this delegate task, for tracking in operation records").optional(),
+  reason: z.string().describe("Brief reason for calling this tool (max 30 chars, e.g., 'Delegate refactor task')").optional()
+});
+var DEFAULT_TIMEOUT = 900000;
+var PROGRESS_INTERVAL = 120000;
+
+class BackgroundTaskManager {
+  env;
+  tasks = new Map;
+  abortControllers = new Map;
+  progressTimers = new Map;
+  constructor(env) {
+    this.env = env;
+  }
+  getSessionComponent() {
+    return this.env?.getComponent?.("session");
+  }
+  publishBackgroundEvent(type, payload, parentSessionId) {
+    if (this.env?.pushEnvEvent) {
+      this.env.pushEnvEvent({
+        type,
+        payload,
+        metadata: {
+          source: "task.background",
+          trigger_session_id: parentSessionId
+        }
+      });
+      logger.info(`[BackgroundTaskManager] Event published: ${type}`);
+    }
+  }
+  async createTask(options) {
+    const { parentSessionId, description, prompt, subagentType, timeout, cleanup, taskId } = options;
+    const taskIdGen = `task_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+    const sessionComponent = this.getSessionComponent();
+    if (!sessionComponent) {
+      throw new Error("SessionComponent not found");
+    }
+    const parentSession = await sessionComponent.get(parentSessionId);
+    if (!parentSession) {
+      throw new Error(`Parent session not found: ${parentSessionId}`);
+    }
+    const metadata = {
+      subagent_type: subagentType,
+      created_by: "subagent",
+      task_description: description
+    };
+    if (taskId) {
+      metadata.task_id = taskId;
+    }
+    const subSession = await sessionComponent.create({
+      title: `${description} (@${subagentType} subagent)`,
+      metadata
+    });
+    if (!subSession) {
+      throw new Error("Failed to create sub-session");
+    }
+    const abortController = new AbortController;
+    const task = {
+      id: taskIdGen,
+      subSessionId: subSession.id,
+      parentSessionId,
+      description,
+      subagentType,
+      status: "pending",
+      createdAt: Date.now(),
+      abortController,
+      taskId
+    };
+    this.tasks.set(taskIdGen, task);
+    this.abortControllers.set(taskIdGen, abortController);
+    const startedPayload = {
+      backgroundTaskId: taskIdGen,
+      subSessionId: subSession.id,
+      parentSessionId,
+      description,
+      subagentType,
+      associatedTaskId: taskId
+    };
+    this.publishBackgroundEvent(BackgroundTaskEventTypes.STARTED, startedPayload, parentSessionId);
+    this.executeTask(taskIdGen, prompt, timeout, cleanup, parentSessionId).catch((err) => {
+      logger.error(`[BackgroundTaskManager] executeTask unhandled rejection`, {
+        taskId: taskIdGen,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    });
+    return { taskId: taskIdGen, subSessionId: subSession.id };
+  }
+  async executeTask(taskId, prompt, timeout, cleanup, parentSessionId) {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      logger.warn(`[BackgroundTaskManager] executeTask: Task not found`, { taskId });
+      return;
+    }
+    task.status = "running";
+    task.startedAt = Date.now();
+    const timeoutMs = timeout || DEFAULT_TIMEOUT;
+    const abortController = this.abortControllers.get(taskId);
+    this.startProgressReporter(taskId, parentSessionId || task.parentSessionId);
+    try {
+      const sessionComponent = this.getSessionComponent();
+      const subSession = await sessionComponent.get(task.subSessionId);
+      if (!subSession) {
+        throw new Error(`Sub session not found: ${task.subSessionId}`);
+      }
+      const result = await this.executeWithAbort(subSession, prompt, timeoutMs, abortController?.signal);
+      if (abortController?.signal.aborted) {
+        logger.info(`[BackgroundTaskManager] Task was aborted`, { taskId });
+        return;
+      }
+      task.status = "completed";
+      task.completedAt = Date.now();
+      task.result = result;
+      const executionTimeMs = task.completedAt - task.startedAt;
+      const completedPayload = {
+        backgroundTaskId: task.id,
+        subSessionId: task.subSessionId,
+        parentSessionId: parentSessionId || task.parentSessionId,
+        status: "completed",
+        result: task.result,
+        description: task.description,
+        executionTimeMs,
+        associatedTaskId: task.taskId
+      };
+      this.publishBackgroundEvent(BackgroundTaskEventTypes.COMPLETED, completedPayload, parentSessionId || task.parentSessionId);
+      logger.info(`[BackgroundTaskManager] Task completed successfully`, {
+        taskId,
+        executionTimeMs
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isStoppedError = errorMessage.toLowerCase().includes("stopped") || errorMessage.toLowerCase().includes("aborted");
+      const executionTimeMs = task.startedAt ? Date.now() - task.startedAt : 0;
+      if (isStoppedError) {
+        task.status = "stopped";
+        const stoppedPayload = {
+          backgroundTaskId: task.id,
+          subSessionId: task.subSessionId,
+          parentSessionId: parentSessionId || task.parentSessionId,
+          status: "stopped",
+          description: task.description,
+          error: errorMessage,
+          executionTimeMs,
+          associatedTaskId: task.taskId
+        };
+        this.publishBackgroundEvent(BackgroundTaskEventTypes.STOPPED, stoppedPayload, parentSessionId || task.parentSessionId);
+      } else if (errorMessage.includes("timeout")) {
+        task.status = "timeout";
+        const timeoutPayload = {
+          backgroundTaskId: task.id,
+          subSessionId: task.subSessionId,
+          parentSessionId: parentSessionId || task.parentSessionId,
+          status: "timeout",
+          description: task.description,
+          error: errorMessage,
+          executionTimeMs,
+          associatedTaskId: task.taskId
+        };
+        this.publishBackgroundEvent(BackgroundTaskEventTypes.TIMEOUT, timeoutPayload, parentSessionId || task.parentSessionId);
+      } else {
+        task.status = "failed";
+        const failedPayload = {
+          backgroundTaskId: task.id,
+          subSessionId: task.subSessionId,
+          parentSessionId: parentSessionId || task.parentSessionId,
+          status: "failed",
+          description: task.description,
+          error: errorMessage,
+          executionTimeMs,
+          associatedTaskId: task.taskId
+        };
+        this.publishBackgroundEvent(BackgroundTaskEventTypes.FAILED, failedPayload, parentSessionId || task.parentSessionId);
+      }
+      task.error = errorMessage;
+      task.completedAt = Date.now();
+      logger.error(`[BackgroundTaskManager] Task execution error`, {
+        taskId,
+        status: task.status,
+        error: errorMessage
+      });
+    } finally {
+      this.stopProgressReporter(taskId);
+    }
+  }
+  startProgressReporter(taskId, parentSessionId) {
+    const timer = setInterval(() => {
+      const task = this.tasks.get(taskId);
+      if (!task || task.status !== "running") {
+        this.stopProgressReporter(taskId);
+        return;
+      }
+      if (task.startedAt) {
+        const elapsedMs = Date.now() - task.startedAt;
+        task.progress = Math.min(95, Math.floor(elapsedMs / PROGRESS_INTERVAL * 100));
+      }
+      const progressPayload = {
+        backgroundTaskId: taskId,
+        subSessionId: task.subSessionId,
+        parentSessionId,
+        status: task.status,
+        progress: task.progress
+      };
+      this.publishBackgroundEvent(BackgroundTaskEventTypes.PROGRESS, progressPayload, parentSessionId);
+    }, PROGRESS_INTERVAL);
+    this.progressTimers.set(taskId, timer);
+  }
+  stopProgressReporter(taskId) {
+    const timer = this.progressTimers.get(taskId);
+    if (timer) {
+      clearInterval(timer);
+      this.progressTimers.delete(taskId);
+    }
+  }
+  async executeWithAbort(subSession, prompt, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Task execution timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+      signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new Error("Task execution stopped"));
+      });
+      const metadata = subSession.info?.metadata || {};
+      const taskId = metadata.task_id;
+      const taskDescription = metadata.task_description || "";
+      const sessionId = subSession.id;
+      const subagentType = metadata.subagent_type || "general";
+      const subAgent = getSubAgentSpec(subagentType);
+      let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
+      const deniedTools = subAgent?.deniedTools || [];
+      let fullPrompt = basePrompt.replace(/{task_description}/g, taskDescription || "N/A");
+      fullPrompt += `
+
+---
+
+# Session Info
+- task_id: ${taskId || "N/A"}
+- session_id: ${sessionId}
+
+---
+
+## 用户指令
+${prompt}
+
+---
+
+## 执行规范
+- 使用可用工具完成任务
+- 返回清晰的任务执行结果摘要
+- 适时调用 task_operation_create 记录进展`;
+      const agentComponent = this.env?.getComponent?.("agent");
+      if (!agentComponent) {
+        clearTimeout(timer);
+        reject(new Error("AgentComponent not found"));
+        return;
+      }
+      ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
+      this.env.handle_query?.(fullPrompt, {
+        sessionId,
+        deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
+        agentType: subagentType
+      }).then((result) => {
+        clearTimeout(timer);
+        resolve(result);
+      }).catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+  }
+  stopTask(taskId) {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      return { success: false, message: "Task not found" };
+    }
+    if (task.status === "completed" || task.status === "failed" || task.status === "stopped" || task.status === "timeout") {
+      return {
+        success: false,
+        task,
+        message: `Cannot stop task with status: ${task.status}`
+      };
+    }
+    task.status = "stopped";
+    task.abortController?.abort();
+    task.completedAt = Date.now();
+    const stoppedPayload = {
+      backgroundTaskId: task.id,
+      subSessionId: task.subSessionId,
+      parentSessionId: task.parentSessionId,
+      status: "stopped",
+      description: task.description,
+      error: "Task stopped by user",
+      executionTimeMs: task.startedAt ? task.completedAt - task.startedAt : 0,
+      associatedTaskId: task.taskId
+    };
+    this.publishBackgroundEvent(BackgroundTaskEventTypes.STOPPED, stoppedPayload, task.parentSessionId);
+    return { success: true, task, message: "Task has been stopped" };
+  }
+  getTask(taskId) {
+    return this.tasks.get(taskId);
+  }
+  listTasks() {
+    return Array.from(this.tasks.values());
+  }
+  dispose() {
+    for (const [taskId, controller] of this.abortControllers) {
+      controller.abort();
+      logger.debug(`[BackgroundTaskManager] Aborted task: ${taskId}`);
+    }
+    this.abortControllers.clear();
+    this.tasks.clear();
+    logger.info(`[BackgroundTaskManager] Disposed`);
+  }
+}
+function createDelegateTool(taskComponent) {
+  const env = taskComponent.env;
+  const backgroundTaskManager = new BackgroundTaskManager(env);
+  taskComponent._backgroundTaskManager = backgroundTaskManager;
+  const tool = {
+    name: "delegate_task",
+    description: `Launch a new sub-agent to handle complex, multistep tasks autonomously.
+
+Available agent types:
+${getSubAgentToolDescription()}
+
+When using the delegate_task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+## When to use delegate_task:
+- When you need to perform complex, multi-step tasks that require independent execution
+- When you need to explore a codebase thoroughly (use "explore" subagent)
+- When you need to run long-running tasks without blocking the main agent (use background=true)
+
+## Parameters:
+- **description**: A short (3-5 words) description of the task
+- **prompt**: The task for the agent to perform
+- **subagent_type**: The type of specialized agent to use (e.g., "general", "explore")
+- **background**: Whether to run in background (default: false)
+- **timeout**: Task timeout in milliseconds (optional)
+- **task_id**: Optional task ID to associate with this delegate task
+
+## Synchronous vs Background mode:
+**Synchronous mode (default)**: Waits for subagent to complete and returns result directly
+**Background mode (background=true)**: Returns immediately with "accepted" status, runs independently`,
+    parameters: DelegateToolParameters,
+    execute: async (args, ctx) => {
+      const startTime = Date.now();
+      const params = DelegateToolParameters.parse(args);
+      const { description, prompt, subagent_type = "general", background = false, timeout, cleanup, task_id, reason } = params;
+      const parentSessionId = ctx.session_id || "default";
+      logger.info(`[delegate_task] Called: description=${description}, subagent_type=${subagent_type}, background=${background}, task_id=${task_id}`);
+      const subAgent = getSubAgentSpec(subagent_type);
+      if (!subAgent) {
+        return {
+          success: false,
+          output: "",
+          error: `Unknown subagent type: ${subagent_type}`,
+          metadata: { execution_time_ms: Date.now() - startTime }
+        };
+      }
+      const tagService = taskComponent.getTagService();
+      let promptWithTaskInfo = prompt;
+      const delegateCtx = {
+        taskId: task_id,
+        prompt: promptWithTaskInfo,
+        subagentType: subagent_type,
+        background,
+        timeout,
+        cleanup,
+        reason,
+        tagService
+      };
+      const hookCtx = {
+        component: { name: "task", version: "1.0.0" },
+        data: delegateCtx,
+        metadata: { sessionId: parentSessionId },
+        phase: "before",
+        hookPoint: TaskHookPoints.DELEGATE_BEFORE
+      };
+      await globalHookManager.execute(TaskHookPoints.DELEGATE_BEFORE, hookCtx, { sessionId: parentSessionId });
+      promptWithTaskInfo = delegateCtx.prompt;
+      if (background) {
+        return await handleBackgroundTask(taskComponent, backgroundTaskManager, parentSessionId, description, promptWithTaskInfo, delegateCtx.subagentType, delegateCtx.timeout, delegateCtx.cleanup, delegateCtx.taskId);
+      } else {
+        return await handleSyncTask(taskComponent, parentSessionId, description, promptWithTaskInfo, delegateCtx.subagentType, delegateCtx.timeout, delegateCtx.taskId);
+      }
+    }
+  };
+  return tool;
+}
+async function handleSyncTask(taskComponent, parentSessionId, description, prompt, subagentType, timeout, taskId) {
+  const startTime = Date.now();
+  try {
+    const sessionComponent = taskComponent.env?.getComponent?.("session");
+    if (!sessionComponent) {
+      return {
+        success: false,
+        output: "",
+        error: "SessionComponent not found",
+        metadata: { execution_time_ms: Date.now() - startTime }
+      };
+    }
+    const parentSession = await sessionComponent.get(parentSessionId);
+    if (!parentSession) {
+      return {
+        success: false,
+        output: "",
+        error: `Parent session not found: ${parentSessionId}`,
+        metadata: { execution_time_ms: Date.now() - startTime }
+      };
+    }
+    const metadata = {
+      subagent_type: subagentType,
+      created_by: "subagent",
+      task_description: description
+    };
+    if (taskId) {
+      metadata.task_id = taskId;
+    }
+    const subSession = await sessionComponent.create({
+      parentID: parentSessionId,
+      title: `${description} (@${subagentType} subagent)`,
+      metadata
+    });
+    if (!subSession) {
+      return {
+        success: false,
+        output: "",
+        error: "Failed to create sub-session",
+        metadata: { execution_time_ms: Date.now() - startTime }
+      };
+    }
+    const subAgent = getSubAgentSpec(subagentType);
+    let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
+    const deniedTools = subAgent?.deniedTools || [];
+    let fullPrompt = basePrompt.replace(/{task_description}/g, description || "N/A");
+    fullPrompt += `
+
+---
+
+# Session Info
+- task_id: ${taskId || "N/A"}
+- session_id: ${subSession.id}
+
+---
+
+## 用户指令
+${prompt}
+
+---
+
+## 执行规范
+- 使用可用工具完成任务
+- 返回清晰的任务执行结果摘要
+- 适时调用 task_operation_create 记录进展`;
+    const agentComponent = taskComponent.env?.getComponent?.("agent");
+    if (!agentComponent) {
+      return {
+        success: false,
+        output: "",
+        error: "AgentComponent not found",
+        metadata: { execution_time_ms: Date.now() - startTime }
+      };
+    }
+    ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
+    const timeoutMs = timeout || DEFAULT_TIMEOUT;
+    let result;
+    try {
+      result = await Promise.race([
+        taskComponent.env?.handle_query?.(fullPrompt, {
+          sessionId: subSession.id,
+          deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
+          agentType: subagentType
+        }),
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`Task execution timeout after ${timeoutMs}ms`)), timeoutMs))
+      ]);
+    } catch (error) {
+      result = error instanceof Error ? error.message : String(error);
+    }
+    await sessionComponent.addMessage(subSession.id, {
+      role: "assistant",
+      content: result
+    });
+    return {
+      success: true,
+      output: result + `
+
+` + [
+        "<task_metadata>",
+        `session_id: ${subSession.id}`,
+        `subagent_type: ${subagentType}`,
+        "</task_metadata>"
+      ].join(`
+`),
+      metadata: {
+        execution_time_ms: Date.now() - startTime,
+        sessionId: subSession.id
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: "",
+      error: error instanceof Error ? error.message : String(error),
+      metadata: { execution_time_ms: Date.now() - startTime }
+    };
+  }
+}
+async function handleBackgroundTask(taskComponent, backgroundTaskManager, parentSessionId, description, prompt, subagentType, timeout, cleanup, taskId) {
+  const startTime = Date.now();
+  try {
+    let associatedTaskId = taskId;
+    if (!associatedTaskId) {
+      const newTask = await taskComponent.createTask({
+        title: description,
+        description: `Background task delegated to ${subagentType} subagent`,
+        priority: "medium",
+        goals_and_expected_deliverables: prompt,
+        sessionId: parentSessionId,
+        project_path: "unknown",
+        context: "unknown"
+      });
+      associatedTaskId = newTask.id;
+      await taskComponent.createOperation({
+        taskId: associatedTaskId,
+        sessionId: parentSessionId,
+        actionType: "create",
+        actionTitle: `Delegated to ${subagentType} subagent`,
+        actionDescription: `Background task started: ${description}`
+      });
+    } else {
+      await taskComponent.updateTask(associatedTaskId, {
+        status: "active",
+        current_status: `Running ${subagentType} subagent`
+      });
+      await taskComponent.createOperation({
+        taskId: associatedTaskId,
+        sessionId: parentSessionId,
+        actionType: "progress",
+        actionTitle: `Started ${subagentType} subagent`,
+        actionDescription: `Background task: ${description}`
+      });
+    }
+    const { taskId: bgTaskId, subSessionId } = await backgroundTaskManager.createTask({
+      parentSessionId,
+      description,
+      prompt,
+      subagentType,
+      timeout,
+      cleanup,
+      taskId: associatedTaskId
+    });
+    const output = [
+      `✅ Background task accepted`,
+      "",
+      `\uD83D\uDCCB Task ID: ${bgTaskId}`,
+      `\uD83D\uDCDD Description: ${description}`,
+      `\uD83E\uDD16 Sub-agent: ${subagentType}`,
+      associatedTaskId ? `\uD83D\uDCCC Associated Task: #${associatedTaskId}` : "",
+      `⏱️ Timeout: ${(timeout || DEFAULT_TIMEOUT) / 1000}s`,
+      "",
+      `Use stop_task with task_id="${bgTaskId}" to cancel this task.`
+    ].filter(Boolean).join(`
+`);
+    return {
+      success: true,
+      output,
+      metadata: {
+        execution_time_ms: Date.now() - startTime,
+        sessionId: subSessionId,
+        background: true,
+        status: "accepted",
+        task_id: associatedTaskId,
+        bgTaskId
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: "",
+      error: error instanceof Error ? error.message : String(error),
+      metadata: { execution_time_ms: Date.now() - startTime }
+    };
+  }
+}
+// src/env/task/delegate/stop-tool.ts
+import { z as z2 } from "zod";
+var StopTaskToolParameters = z2.object({
+  task_id: z2.string().describe("The ID of the background task to stop")
+});
+var STOP_TASK_DESCRIPTION = `Stop a running background task.
+
+Use this tool to stop a background task that is currently running. This is useful when:
+- The user wants to cancel a long-running task
+- The task is taking too long and needs to be stopped
+- The user wants to change direction and doesn't need the task result anymore
+
+When stopped, the task will be terminated immediately and you will receive a confirmation.
+
+Parameters:
+- task_id: The ID of the background task to stop (obtained from the delegate_task response)`;
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  } else {
+    return `${seconds}s`;
+  }
+}
+function createStopTool(taskManager) {
+  return {
+    name: "stop_task",
+    description: STOP_TASK_DESCRIPTION,
+    parameters: StopTaskToolParameters,
+    execute: async (args, ctx) => {
+      const startTime = Date.now();
+      const params = StopTaskToolParameters.parse(args);
+      const { task_id } = params;
+      const result = taskManager.stopTask(task_id);
+      if (result.success) {
+        const task = result.task;
+        const elapsedMs = task.startedAt ? Date.now() - task.startedAt : Date.now() - task.createdAt;
+        const output = [
+          `✅ Task stopped successfully`,
+          "",
+          `\uD83D\uDCCB Task ID: ${task_id}`,
+          `\uD83D\uDCDD Description: ${task.description}`,
+          `\uD83D\uDD04 Status: ${task.status} → stopped`,
+          `⏱️ Elapsed Time: ${formatDuration(elapsedMs)}`,
+          "",
+          result.message
+        ].join(`
+`);
+        return {
+          success: true,
+          output,
+          metadata: {
+            execution_time_ms: Date.now() - startTime,
+            task_id,
+            previous_status: task.status
+          }
+        };
+      } else {
+        const task = result.task;
+        let output;
+        if (task) {
+          output = [
+            `⚠️ Cannot stop task`,
+            "",
+            `\uD83D\uDCCB Task ID: ${task_id}`,
+            `\uD83D\uDCDD Description: ${task.description}`,
+            `\uD83D\uDD04 Current Status: ${task.status}`,
+            "",
+            result.message
+          ].join(`
+`);
+        } else {
+          output = [
+            `❌ Task not found`,
+            "",
+            `\uD83D\uDCCB Task ID: ${task_id}`,
+            "",
+            result.message
+          ].join(`
+`);
+        }
+        return {
+          success: false,
+          output,
+          error: result.message,
+          metadata: {
+            execution_time_ms: Date.now() - startTime,
+            task_id
+          }
+        };
+      }
+    }
+  };
+}
+export { BackgroundTaskEventTypes, BackgroundTaskManager, createDelegateTool, createStopTool };