@ai-setting/roy-agent-core 1.3.9 → 1.3.11

package/src/env/task/delegate/delegate-tool.ts

@@ -1,1014 +0,0 @@
-/**
- * @fileoverview delegate_task Tool
- * 
- * 基于 agent-core 的 delegate_task 实现
- * 参考: packages/core/src/core/environment/expend/task/task-tool.ts
- * 
- * 功能：
- * - 委派子Agent执行任务（同步/后台模式）
- * - 支持多种 subagent 类型
- * - 支持任务关联（task_id）
- * - 发布 EnvEvent 事件
- */
-
-import { z } from "zod";
-import type { Tool, ToolContext, ToolResult } from "../../tool/types";
-import type { TaskComponent } from "../task-component";
-import type { SessionComponent } from "../../session/session-component";
-import { createLogger } from "../../log-trace/logger";
-import { 
-  TaskEventTypes, 
-  createTaskStartedPayload, 
-  createTaskProgressPayload, 
-  createTaskCompletedPayload 
-} from "./task-events";
-import { env } from "process";
-import { AgentComponent } from "../../agent";
-
-// Hook 机制
-import { globalHookManager } from "../../hook/global-hook-manager";
-import { TaskHookPoints } from "../hooks";
-import type { TaskDelegateContext } from "../hooks/contexts";
-import type { TagService } from "../tag-service";
-
-const logger = createLogger("task:delegate");
-
-// ============================================================================
-// SubAgent Types (简化版)
-// ============================================================================
-
-export interface SubAgentSpec {
-  id: string;
-  name: string;
-  description: string;
-  mode: "subagent" | "primary" | "all";
-  promptOverride?: string;
-  /** 允许的工具列表（白名单） */
-  allowedTools?: string[];
-  /** 拒绝的工具列表（黑名单） */
-  deniedTools?: string[];
-}
-
-export const builtInSubAgents: SubAgentSpec[] = [
-  {
-    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`,
-    // Prevent nested delegation by denying delegate_task and stop_task
-    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: string): SubAgentSpec | undefined {
-  return builtInSubAgents.find((agent) => agent.id === id);
-}
-
-function listSubAgents(): SubAgentSpec[] {
-  return [...builtInSubAgents];
-}
-
-function getSubAgentToolDescription(): string {
-  return builtInSubAgents.map((agent) => `- ${agent.id}: ${agent.description}`).join("\n");
-}
-
-// ============================================================================
-// SubAgent Registration Helper
-// ============================================================================
-
-/**
- * 确保 subAgent 已注册到 AgentComponent
- * 
- * @param agentComponent AgentComponent 实例
- * @param subagentType subAgent 类型（用作 agentName）
- * @param basePrompt 基础 system prompt
- * @param subAgent subAgent 配置（可能包含 allowedTools）
- * @param deniedTools 拒绝的工具列表
- * @returns 注册的 agent 实例
- */
-function ensureSubAgentRegistered(
-  agentComponent: any,
-  subagentType: string,
-  basePrompt: string,
-  subAgent: SubAgentSpec | undefined,
-  deniedTools: string[]
-): any {
-  let agentInstance = agentComponent.getAgent(subagentType);
-  if (!agentInstance) {
-    const agentConfig: Record<string, unknown> = {
-      type: "sub",
-      systemPrompt: basePrompt,
-    };
-
-    // 添加 allowedTools（如果有）
-    if (subAgent?.allowedTools && subAgent.allowedTools.length > 0) {
-      agentConfig.allowedTools = subAgent.allowedTools;
-    }
-
-    // 添加 deniedTools（如果有）
-    if (deniedTools.length > 0) {
-      agentConfig.deniedTools = deniedTools;
-    }
-
-    agentInstance = agentComponent.registerAgent(subagentType, agentConfig as any);
-    logger.debug(`[delegate] Registered subagent: ${subagentType}`);
-  }
-  return agentInstance;
-}
-
-// ============================================================================
-// Tool Parameters Schema
-// ============================================================================
-
-export const 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"] as const)
-    .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(),
-});
-
-export type DelegateToolParams = z.infer<typeof DelegateToolParameters>;
-
-// ============================================================================
-// Delegate Tool Implementation
-// ============================================================================
-
-export interface DelegateToolResult {
-  tool: Tool;
-  backgroundTaskManager: BackgroundTaskManager;
-}
-
-export interface BackgroundTask {
-  id: string;
-  subSessionId: string;
-  parentSessionId: string;
-  description: string;
-  subagentType: string;
-  status: "pending" | "running" | "completed" | "failed" | "timeout" | "stopped";
-  createdAt: number;
-  startedAt?: number;
-  completedAt?: number;
-  result?: string;
-  error?: string;
-  progress?: number;
-  progressMessage?: string;
-  abortController?: AbortController;
-  taskId?: number; // 关联的任务ID
-}
-
-export interface CreateBackgroundTaskOptions {
-  parentSessionId: string;
-  description: string;
-  prompt: string;
-  subagentType: string;
-  timeout?: number;
-  cleanup?: "delete" | "keep";
-  taskId?: number;
-}
-
-const DEFAULT_TIMEOUT = 900000; // 15 minutes
-const PROGRESS_INTERVAL = 120000; // 2 minutes
-
-/**
- * Background Task Manager (简化版)
- * 
- * 管理后台任务的创建、执行、状态跟踪
- * 支持 EnvEvent 发布
- */
-export class BackgroundTaskManager {
-  private tasks: Map<string, BackgroundTask> = new Map();
-  private progressTimers: Map<string, NodeJS.Timeout> = new Map();
-  private abortControllers: Map<string, AbortController> = new Map();
-
-  constructor(private env: any) {
-    // env 应该具有 pushEnvEvent 和 getComponent 方法
-  }
-
-  /**
-   * Get SessionComponent from env
-   */
-  private getSessionComponent(): any {
-    return this.env?.getComponent?.("session");
-  }
-
-  async createTask(options: CreateBackgroundTaskOptions): Promise<{ taskId: string; subSessionId: string }> {
-    const { parentSessionId, description, prompt, subagentType, timeout, cleanup, taskId } = options;
-
-    const taskIdGen = `task_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
-
-    // Get SessionComponent
-    const sessionComponent = this.getSessionComponent();
-    if (!sessionComponent) {
-      throw new Error("SessionComponent not found");
-    }
-
-    // Create sub-session
-    const parentSession = await sessionComponent.get(parentSessionId);
-    if (!parentSession) {
-      throw new Error(`Parent session not found: ${parentSessionId}`);
-    }
-
-    const metadata: Record<string, unknown> = {
-      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: BackgroundTask = {
-      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);
-
-    // Publish task.started event
-    this.publishEvent(TaskEventTypes.TASK_STARTED, createTaskStartedPayload(task, parentSessionId), parentSessionId);
-
-    // Start execution asynchronously
-    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 };
-  }
-
-  private async executeTask(
-    taskId: string,
-    prompt: string,
-    timeout?: number,
-    cleanup?: "delete" | "keep",
-    parentSessionId?: string
-  ): Promise<void> {
-    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);
-
-    // Start progress reporter
-    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}`);
-      }
-
-      // Execute with timeout and abort support
-      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;
-
-      // Publish task.completed event
-      const executionTimeMs = task.completedAt - task.startedAt!;
-      this.publishEvent(
-        TaskEventTypes.TASK_COMPLETED,
-        createTaskCompletedPayload(task, parentSessionId || task.parentSessionId, executionTimeMs),
-        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");
-
-      if (isStoppedError) {
-        task.status = "stopped";
-        // Publish task.stopped event
-        this.publishEvent(
-          TaskEventTypes.TASK_STOPPED,
-          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId, 
-            task.completedAt! - task.startedAt!),
-          parentSessionId || task.parentSessionId
-        );
-      } else if (errorMessage.includes("timeout")) {
-        task.status = "timeout";
-        // Publish task.timeout event
-        this.publishEvent(
-          TaskEventTypes.TASK_TIMEOUT,
-          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId,
-            task.completedAt! - task.startedAt!),
-          parentSessionId || task.parentSessionId
-        );
-      } else {
-        task.status = "failed";
-        // Publish task.failed event
-        this.publishEvent(
-          TaskEventTypes.TASK_FAILED,
-          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId,
-            task.completedAt! - task.startedAt!),
-          parentSessionId || task.parentSessionId
-        );
-      }
-      task.error = errorMessage;
-      task.completedAt = Date.now();
-
-      logger.error(`[BackgroundTaskManager] Task execution error`, {
-        taskId,
-        status: task.status,
-        error: errorMessage,
-      });
-    } finally {
-      // Stop progress reporter
-      this.stopProgressReporter(taskId);
-    }
-  }
-
-  private async executeWithAbort(
-    subSession: any,
-    prompt: string,
-    timeoutMs: number,
-    signal?: AbortSignal
-  ): Promise<string> {
-    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"));
-      });
-
-      // Build full prompt
-      const metadata = subSession.info?.metadata || {};
-      const taskId = metadata.task_id as number | undefined;
-      const taskDescription = metadata.task_description as string || "";
-      const sessionId = subSession.id;
-      const subagentType = metadata.subagent_type as string || "general";
-
-      const subAgent = getSubAgentSpec(subagentType);
-      let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
-
-      // Get denied tools from subagent config
-      const deniedTools = subAgent?.deniedTools || [];
-
-      // Only replace valid placeholders
-      let fullPrompt = basePrompt.replace(/{task_description}/g, taskDescription || "N/A");
-
-      // Add session info and execution guidelines
-      fullPrompt += `
-
----
-
-# Session Info
-- task_id: ${taskId || "N/A"}
-- session_id: ${sessionId}
-
----
-
-## 用户指令
-${prompt}
-
----
-
-## 执行规范
-- 使用可用工具完成任务
-- 返回清晰的任务执行结果摘要
-- 适时调用 task_operation_create 记录进展`;
-
-      // Get AgentComponent and ensure subagent is registered
-      const agentComponent = this.env?.getComponent?.("agent") as any;
-
-      if (!agentComponent) {
-        clearTimeout(timer);
-        reject(new Error("AgentComponent not found"));
-        return;
-      }
-
-      // 注册 subagent（使用公共函数）
-      ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
-
-      // Execute using handle_query with agentType specified
-      this.env.handle_query?.(fullPrompt, {
-        sessionId: sessionId,
-        deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
-        agentType: subagentType, // handle_query will use this agent
-      })
-        .then((result: string) => {
-          clearTimeout(timer);
-          resolve(result);
-        })
-        .catch((error: Error) => {
-          clearTimeout(timer);
-          reject(error);
-        });
-    });
-  }
-
-  /**
-   * Start progress reporter for a task
-   */
-  private startProgressReporter(taskId: string, parentSessionId: string): void {
-    const timer = setInterval(() => {
-      const task = this.tasks.get(taskId);
-      if (!task || task.status !== "running") {
-        this.stopProgressReporter(taskId);
-        return;
-      }
-
-      // Update progress
-      if (task.startedAt) {
-        const elapsedMs = Date.now() - task.startedAt;
-        task.progress = Math.min(95, Math.floor((elapsedMs / PROGRESS_INTERVAL) * 100));
-      }
-
-      // Publish progress event
-      this.publishEvent(
-        TaskEventTypes.TASK_PROGRESS,
-        createTaskProgressPayload(task, parentSessionId),
-        parentSessionId
-      );
-    }, PROGRESS_INTERVAL);
-
-    this.progressTimers.set(taskId, timer);
-  }
-
-  /**
-   * Stop progress reporter for a task
-   */
-  private stopProgressReporter(taskId: string): void {
-    const timer = this.progressTimers.get(taskId);
-    if (timer) {
-      clearInterval(timer);
-      this.progressTimers.delete(taskId);
-    }
-  }
-
-  /**
-   * Publish an event to the environment
-   */
-  private publishEvent<T>(type: string, payload: T, triggerSessionId?: string): void {
-    if (this.env?.pushEnvEvent) {
-      this.env.pushEnvEvent({
-        type,
-        metadata: {
-          trigger_session_id: triggerSessionId,
-          source: "task.delegate",
-        },
-        payload,
-      });
-      logger.info(`[BackgroundTaskManager] Event published: ${type}`, { payload });
-    }
-  }
-
-  stopTask(taskId: string): { success: boolean; task?: BackgroundTask; message: string } {
-    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();
-
-    // Publish task.stopped event
-    this.publishEvent(
-      TaskEventTypes.TASK_STOPPED,
-      createTaskCompletedPayload(task, task.parentSessionId, task.completedAt - task.startedAt!),
-      task.parentSessionId
-    );
-
-    return { success: true, task, message: "Task has been stopped" };
-  }
-
-  getTask(taskId: string): BackgroundTask | undefined {
-    return this.tasks.get(taskId);
-  }
-
-  listTasks(): BackgroundTask[] {
-    return Array.from(this.tasks.values());
-  }
-
-  /**
-   * Dispose and cleanup all resources
-   * Call this when shutting down to prevent process from hanging
-   */
-  dispose(): void {
-    // Clear all progress timers
-    for (const [taskId, timer] of this.progressTimers) {
-      clearInterval(timer);
-      logger.debug(`[BackgroundTaskManager] Cleared progress timer for task: ${taskId}`);
-    }
-    this.progressTimers.clear();
-
-    // Abort all running tasks
-    for (const [taskId, controller] of this.abortControllers) {
-      controller.abort();
-      logger.debug(`[BackgroundTaskManager] Aborted task: ${taskId}`);
-    }
-    this.abortControllers.clear();
-
-    // Clear all tasks
-    this.tasks.clear();
-
-    logger.info(`[BackgroundTaskManager] Disposed`);
-  }
-}
-
-/**
- * Create delegate_task tool
- */
-export function createDelegateTool(taskComponent: TaskComponent): Tool {
-  // Pass taskComponent.env instead of taskComponent, so BackgroundTaskManager
-  // can correctly call this.env.getComponent("session")
-  const env = (taskComponent as any).env;
-  const backgroundTaskManager = new BackgroundTaskManager(env);
-
-  const tool: 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: unknown, ctx: ToolContext): Promise<ToolResult> => {
-      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}`);
-
-      // Validate subagent_type
-      const subAgent = getSubAgentSpec(subagent_type);
-      if (!subAgent) {
-        return {
-          success: false,
-          output: "",
-          error: `Unknown subagent type: ${subagent_type}`,
-          metadata: { execution_time_ms: Date.now() - startTime },
-        };
-      }
-
-      // Get TagService from TaskComponent
-      const tagService = taskComponent.getTagService();
-
-      // Build initial prompt - hook will inject similar tasks info
-      let promptWithTaskInfo = prompt;
-
-      // Execute delegate:before Hook (can modify prompt, subagentType, etc.)
-      const delegateCtx: TaskDelegateContext = {
-        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" as const,
-        hookPoint: TaskHookPoints.DELEGATE_BEFORE,
-      };
-
-      await globalHookManager.execute(TaskHookPoints.DELEGATE_BEFORE, hookCtx, { sessionId: parentSessionId });
-
-      // Use potentially modified prompt from hook
-      promptWithTaskInfo = delegateCtx.prompt;
-
-      if (background) {
-        // Background execution
-        return await handleBackgroundTask(
-          taskComponent,
-          backgroundTaskManager,
-          parentSessionId,
-          description,
-          promptWithTaskInfo,
-          delegateCtx.subagentType,
-          delegateCtx.timeout,
-          delegateCtx.cleanup,
-          delegateCtx.taskId
-        );
-      } else {
-        // Synchronous execution
-        return await handleSyncTask(
-          taskComponent,
-          parentSessionId,
-          description,
-          promptWithTaskInfo,
-          delegateCtx.subagentType,
-          delegateCtx.timeout,
-          delegateCtx.taskId
-        );
-      }
-    },
-  };
-
-  return tool;
-}
-
-async function handleSyncTask(
-  taskComponent: TaskComponent,
-  parentSessionId: string,
-  description: string,
-  prompt: string,
-  subagentType: string,
-  timeout?: number,
-  taskId?: number
-): Promise<ToolResult> {
-  const startTime = Date.now();
-
-  try {
-    // Get SessionComponent from environment
-    const sessionComponent = (taskComponent as any).env?.getComponent?.("session") as SessionComponent | undefined;
-    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 },
-      };
-    }
-
-    // Create sub-session
-    const metadata: Record<string, unknown> = {
-      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 },
-      };
-    }
-
-    // Build full prompt
-    const subAgent = getSubAgentSpec(subagentType);
-    let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
-
-    // Get denied tools from subagent config
-    const deniedTools = subAgent?.deniedTools || [];
-
-    // Only replace valid placeholders
-    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 as any).env?.getComponent?.("agent") as any;
-
-    if (!agentComponent) {
-      return {
-        success: false,
-        output: "",
-        error: "AgentComponent not found",
-        metadata: { execution_time_ms: Date.now() - startTime },
-      };
-    }
-
-    // 注册 subagent（使用公共函数）
-    ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
-
-    // 使用 handle_query 执行，通过 agentType 指定 agent
-    const timeoutMs = timeout || DEFAULT_TIMEOUT;
-    let result: string;
-    
-    try {
-      result = await Promise.race([
-        (taskComponent as any).env?.handle_query?.(fullPrompt, { 
-          sessionId: subSession.id,
-          deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
-          agentType: subagentType, // 传入 agentType，handle_query 会使用对应的 agent
-        }),
-        new Promise<string>((_, reject) =>
-          setTimeout(() => reject(new Error(`Task execution timeout after ${timeoutMs}ms`)), timeoutMs)
-        ),
-      ]);
-    } catch (error) {
-      result = error instanceof Error ? error.message : String(error);
-    }
-
-    // Add result message to session
-    await sessionComponent.addMessage(subSession.id, {
-      role: "assistant",
-      content: result,
-    });
-
-    return {
-      success: true,
-      output: result + "\n\n" + [
-        "<task_metadata>",
-        `session_id: ${subSession.id}`,
-        `subagent_type: ${subagentType}`,
-        "</task_metadata>",
-      ].join("\n"),
-      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: TaskComponent,
-  backgroundTaskManager: BackgroundTaskManager,
-  parentSessionId: string,
-  description: string,
-  prompt: string,
-  subagentType: string,
-  timeout?: number,
-  cleanup?: "delete" | "keep",
-  taskId?: number
-): Promise<ToolResult> {
-  const startTime = Date.now();
-
-  try {
-    // Create or update task
-    let associatedTaskId = taskId;
-    
-    if (!associatedTaskId) {
-      // Create new task
-      const newTask = await taskComponent.createTask({
-        title: description,
-        description: `Background task delegated to ${subagentType} subagent`,
-        priority: "medium",
-        goals_and_expected_deliverables: prompt,
-        sessionId: parentSessionId,
-      });
-      associatedTaskId = newTask.id;
-
-      // Create operation record
-      await taskComponent.createOperation({
-        taskId: associatedTaskId,
-        sessionId: parentSessionId,
-        actionType: "create",
-        actionTitle: `Delegated to ${subagentType} subagent`,
-        actionDescription: `Background task started: ${description}`,
-      });
-    } else {
-      // Update existing task
-      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}`,
-      });
-    }
-
-    // Create background task
-    const { taskId: bgTaskId, subSessionId } = await backgroundTaskManager.createTask({
-      parentSessionId,
-      description,
-      prompt,
-      subagentType,
-      timeout,
-      cleanup,
-      taskId: associatedTaskId,
-    });
-
-    const output = [
-      `✅ Background task accepted`,
-      "",
-      `📋 Task ID: ${bgTaskId}`,
-      `📝 Description: ${description}`,
-      `🤖 Sub-agent: ${subagentType}`,
-      associatedTaskId ? `📌 Associated Task: #${associatedTaskId}` : "",
-      `⏱️ Timeout: ${(timeout || DEFAULT_TIMEOUT) / 1000}s`,
-      "",
-      `Use stop_task with task_id="${bgTaskId}" to cancel this task.`,
-    ].filter(Boolean).join("\n");
-
-    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 },
-    };
-  }
-}
-
-// Export for stop_task tool
-export { handleBackgroundTask, handleSyncTask };