@ai-setting/roy-agent-core 1.0.0

package/src/env/task/delegate/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Delegate Tools Index
+ */
+
+export { createDelegateTool, BackgroundTaskManager } from "./delegate-tool";
+export { createStopTool } from "./stop-tool";
+export type { DelegateToolResult, DelegateToolParams, DelegateToolParameters } from "./delegate-tool";
+export type { BackgroundTask, SubAgentSpec } from "./delegate-tool";
+
+// Event types
+export { 
+  TaskEventTypes,
+  type TaskEventType,
+  type TaskStartedPayload,
+  type TaskProgressPayload,
+  type TaskCompletedPayload,
+  type BaseTaskEventPayload,
+} from "./task-events";

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

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview stop_task Tool Tests
+ * 
+ * TDD: 红色阶段 - 编写失败的测试
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+
+// Mock the tool factory
+const createStopTool = async (backgroundTaskManager: any): Promise<Tool> => {
+  const module = await import("./stop-tool");
+  return module.createStopTool(backgroundTaskManager);
+};
+
+describe("stop_task Tool", () => {
+  let mockBackgroundTaskManager: any;
+  let tool: Tool;
+
+  beforeEach(async () => {
+    // Mock BackgroundTaskManager
+    mockBackgroundTaskManager = {
+      stopTask: vi.fn(),
+      getTask: vi.fn(),
+    };
+    
+    tool = await createStopTool(mockBackgroundTaskManager);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Tool Definition", () => {
+    test("should have correct tool name", () => {
+      expect(tool.name).toBe("stop_task");
+    });
+
+    test("should have description", () => {
+      expect(tool.description).toBeDefined();
+      expect(tool.description.length).toBeGreaterThan(0);
+    });
+
+    test("should have parameters schema", () => {
+      expect(tool.parameters).toBeDefined();
+      expect(tool.parameters.shape).toBeDefined();
+    });
+
+    test("should have task_id field in parameters", () => {
+      const shape = tool.parameters.shape;
+      expect(shape.task_id).toBeDefined();
+    });
+  });
+
+  describe("Execution", () => {
+    test("should stop a running task successfully", async () => {
+      const mockTask = {
+        id: "task_123",
+        description: "Test task",
+        status: "running",
+        startedAt: Date.now() - 60000,
+      };
+      
+      mockBackgroundTaskManager.stopTask.mockReturnValue({
+        success: true,
+        task: mockTask,
+        message: "Task has been stopped",
+      });
+
+      const result = await tool.execute(
+        { task_id: "task_123" },
+        { session_id: "test-session" }
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("Task stopped successfully");
+      expect(mockBackgroundTaskManager.stopTask).toHaveBeenCalledWith("task_123");
+    });
+
+    test("should return error when task not found", async () => {
+      mockBackgroundTaskManager.stopTask.mockReturnValue({
+        success: false,
+        message: "Task not found",
+      });
+
+      const result = await tool.execute(
+        { task_id: "non-existent-task" },
+        { session_id: "test-session" }
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Task not found");
+    });
+
+    test("should return error when task already completed", async () => {
+      const mockTask = {
+        id: "task_456",
+        description: "Completed task",
+        status: "completed",
+      };
+      
+      mockBackgroundTaskManager.stopTask.mockReturnValue({
+        success: false,
+        task: mockTask,
+        message: "Cannot stop task with status: completed",
+      });
+
+      const result = await tool.execute(
+        { task_id: "task_456" },
+        { session_id: "test-session" }
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.output).toContain("Cannot stop task");
+    });
+
+    test("should include task info in output", async () => {
+      const mockTask = {
+        id: "task_789",
+        description: "Running task",
+        status: "running",
+        startedAt: Date.now() - 120000,
+      };
+      
+      mockBackgroundTaskManager.stopTask.mockReturnValue({
+        success: true,
+        task: mockTask,
+        message: "Task has been stopped",
+      });
+
+      const result = await tool.execute(
+        { task_id: "task_789" },
+        { session_id: "test-session" }
+      );
+
+      expect(result.output).toContain("task_789");
+      expect(result.output).toContain("Running task");
+    });
+  });
+});

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

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview stop_task Tool
+ * 
+ * 基于 agent-core 的 stop_task 实现
+ * 参考: packages/core/src/core/environment/expend/task/stop-task-tool.ts
+ * 
+ * 功能：
+ * - 停止正在运行的后台任务
+ */
+
+import { z } from "zod";
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import type { BackgroundTaskManager } from "./delegate-tool";
+
+const StopTaskToolParameters = z.object({
+  task_id: z.string().describe("The ID of the background task to stop"),
+});
+
+type StopTaskToolParams = z.infer<typeof StopTaskToolParameters>;
+
+const 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: number): string {
+  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`;
+  }
+}
+
+export function createStopTool(taskManager: BackgroundTaskManager): Tool {
+  return {
+    name: "stop_task",
+    description: STOP_TASK_DESCRIPTION,
+    parameters: StopTaskToolParameters,
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      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`,
+          "",
+          `📋 Task ID: ${task_id}`,
+          `📝 Description: ${task.description}`,
+          `🔄 Status: ${task.status} → stopped`,
+          `⏱️ Elapsed Time: ${formatDuration(elapsedMs)}`,
+          "",
+          result.message,
+        ].join("\n");
+
+        return {
+          success: true,
+          output,
+          metadata: {
+            execution_time_ms: Date.now() - startTime,
+            task_id,
+            previous_status: task.status,
+          },
+        };
+      } else {
+        const task = result.task;
+        let output: string;
+
+        if (task) {
+          output = [
+            `⚠️ Cannot stop task`,
+            "",
+            `📋 Task ID: ${task_id}`,
+            `📝 Description: ${task.description}`,
+            `🔄 Current Status: ${task.status}`,
+            "",
+            result.message,
+          ].join("\n");
+        } else {
+          output = [
+            `❌ Task not found`,
+            "",
+            `📋 Task ID: ${task_id}`,
+            "",
+            result.message,
+          ].join("\n");
+        }
+
+        return {
+          success: false,
+          output,
+          error: result.message,
+          metadata: {
+            execution_time_ms: Date.now() - startTime,
+            task_id,
+          },
+        };
+      }
+    },
+  };
+}

package/src/env/task/delegate/task-events.test.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Task Events Tests
+ */
+
+import { describe, test, expect } from "vitest";
+import { 
+  TaskEventTypes,
+  createTaskStartedPayload,
+  createTaskProgressPayload,
+  createTaskCompletedPayload,
+} from "./task-events";
+import type { BackgroundTask } from "./delegate-tool";
+
+describe("Task Events", () => {
+  describe("TaskEventTypes", () => {
+    test("should have all required event types", () => {
+      expect(TaskEventTypes.TASK_STARTED).toBe("task.started");
+      expect(TaskEventTypes.TASK_PROGRESS).toBe("task.progress");
+      expect(TaskEventTypes.TASK_COMPLETED).toBe("task.completed");
+      expect(TaskEventTypes.TASK_FAILED).toBe("task.failed");
+      expect(TaskEventTypes.TASK_TIMEOUT).toBe("task.timeout");
+      expect(TaskEventTypes.TASK_STOPPED).toBe("task.stopped");
+    });
+
+    test("event types should be unique strings", () => {
+      const types = Object.values(TaskEventTypes);
+      const uniqueTypes = new Set(types);
+      expect(uniqueTypes.size).toBe(types.length);
+    });
+  });
+
+  describe("createTaskStartedPayload", () => {
+    test("should create correct payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "pending",
+        createdAt: Date.now(),
+        taskId: 100,
+      };
+
+      const payload = createTaskStartedPayload(task, "parent_789");
+
+      expect(payload.taskId).toBe("task_123");
+      expect(payload.subSessionId).toBe("sub_session_456");
+      expect(payload.parentSessionId).toBe("parent_789");
+      expect(payload.description).toBe("Test task");
+      expect(payload.subagentType).toBe("general");
+      expect(payload.associatedTaskId).toBe(100);
+    });
+
+    test("should handle missing taskId", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "pending",
+        createdAt: Date.now(),
+      };
+
+      const payload = createTaskStartedPayload(task, "parent_789");
+
+      expect(payload.associatedTaskId).toBeUndefined();
+    });
+  });
+
+  describe("createTaskProgressPayload", () => {
+    test("should create correct payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "running",
+        createdAt: Date.now(),
+        progress: 50,
+        progressMessage: "Processing...",
+      };
+
+      const payload = createTaskProgressPayload(task, "parent_789");
+
+      expect(payload.taskId).toBe("task_123");
+      expect(payload.status).toBe("running");
+      expect(payload.progress).toBe(50);
+      expect(payload.progressMessage).toBe("Processing...");
+    });
+  });
+
+  describe("createTaskCompletedPayload", () => {
+    test("should create completed payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "completed",
+        createdAt: Date.now(),
+        startedAt: Date.now() - 10000,
+        completedAt: Date.now(),
+        result: "Task completed successfully",
+        taskId: 100,
+      };
+
+      const payload = createTaskCompletedPayload(task, "parent_789", 10000);
+
+      expect(payload.taskId).toBe("task_123");
+      expect(payload.status).toBe("completed");
+      expect(payload.result).toBe("Task completed successfully");
+      expect(payload.executionTimeMs).toBe(10000);
+      expect(payload.associatedTaskId).toBe(100);
+    });
+
+    test("should create failed payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "failed",
+        createdAt: Date.now(),
+        startedAt: Date.now() - 5000,
+        completedAt: Date.now(),
+        error: "Something went wrong",
+        taskId: 100,
+      };
+
+      const payload = createTaskCompletedPayload(task, "parent_789", 5000);
+
+      expect(payload.status).toBe("failed");
+      expect(payload.error).toBe("Something went wrong");
+    });
+
+    test("should create timeout payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "timeout",
+        createdAt: Date.now(),
+        startedAt: Date.now() - 900000,
+        completedAt: Date.now(),
+        error: "Task execution timeout after 900000ms",
+      };
+
+      const payload = createTaskCompletedPayload(task, "parent_789", 900000);
+
+      expect(payload.status).toBe("timeout");
+    });
+
+    test("should create stopped payload", () => {
+      const task: BackgroundTask = {
+        id: "task_123",
+        subSessionId: "sub_session_456",
+        parentSessionId: "parent_789",
+        description: "Test task",
+        subagentType: "general",
+        status: "stopped",
+        createdAt: Date.now(),
+        startedAt: Date.now() - 3000,
+        completedAt: Date.now(),
+      };
+
+      const payload = createTaskCompletedPayload(task, "parent_789", 3000);
+
+      expect(payload.status).toBe("stopped");
+    });
+  });
+});

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

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Task Event Types
+ * 
+ * 定义任务相关的 EnvEvent 类型
+ */
+
+import type { EnvEvent } from "../../types";
+
+// ============================================================================
+// Task Event Types
+// ============================================================================
+
+/**
+ * 任务事件类型枚举
+ */
+export const TaskEventTypes = {
+  /** 任务开始执行 */
+  TASK_STARTED: "task.started",
+  /** 任务进度更新 */
+  TASK_PROGRESS: "task.progress",
+  /** 任务完成 */
+  TASK_COMPLETED: "task.completed",
+  /** 任务失败 */
+  TASK_FAILED: "task.failed",
+  /** 任务超时 */
+  TASK_TIMEOUT: "task.timeout",
+  /** 任务被停止 */
+  TASK_STOPPED: "task.stopped",
+} as const;
+
+export type TaskEventType = (typeof TaskEventTypes)[keyof typeof TaskEventTypes];
+
+// ============================================================================
+// Task Event Payloads
+// ============================================================================
+
+/**
+ * 任务开始事件负载
+ */
+export interface TaskStartedPayload {
+  taskId: string;
+  subSessionId: string;
+  parentSessionId: string;
+  description: string;
+  subagentType: string;
+  associatedTaskId?: number;
+}
+
+/**
+ * 任务进度事件负载
+ */
+export interface TaskProgressPayload {
+  taskId: string;
+  subSessionId: string;
+  parentSessionId: string;
+  status: string;
+  progress?: number;
+  progressMessage?: string;
+  description?: string;
+  subagentType?: string;
+}
+
+/**
+ * 任务完成事件负载
+ */
+export interface TaskCompletedPayload {
+  taskId: string;
+  subSessionId: string;
+  parentSessionId: string;
+  status: "completed" | "failed" | "timeout" | "stopped";
+  result?: string;
+  error?: string;
+  executionTimeMs: number;
+  associatedTaskId?: number;
+  description?: string;
+  subagentType?: string;
+}
+
+/**
+ * 任务事件基类
+ */
+export interface BaseTaskEventPayload {
+  taskId: string;
+  subSessionId: string;
+  parentSessionId: string;
+  description: string;
+  subagentType: string;
+  associatedTaskId?: number;
+}
+
+// ============================================================================
+// Event Creators
+// ============================================================================
+
+import type { BackgroundTask } from "./delegate-tool";
+
+/**
+ * 从 BackgroundTask 创建事件负载
+ */
+export function createTaskStartedPayload(task: BackgroundTask, parentSessionId: string): TaskStartedPayload {
+  return {
+    taskId: task.id,
+    subSessionId: task.subSessionId,
+    parentSessionId,
+    description: task.description,
+    subagentType: task.subagentType,
+    associatedTaskId: task.taskId,
+  };
+}
+
+export function createTaskProgressPayload(task: BackgroundTask, parentSessionId: string): TaskProgressPayload {
+  return {
+    taskId: task.id,
+    subSessionId: task.subSessionId,
+    parentSessionId,
+    status: task.status,
+    progress: task.progress,
+    progressMessage: task.progressMessage,
+    // 添加 description 和 subagentType 以便 EventMessageFormatter 使用
+    description: task.description,
+    subagentType: task.subagentType,
+  };
+}
+
+export function createTaskCompletedPayload(
+  task: BackgroundTask,
+  parentSessionId: string,
+  executionTimeMs: number
+): TaskCompletedPayload {
+  return {
+    taskId: task.id,
+    subSessionId: task.subSessionId,
+    parentSessionId,
+    status: task.status as "completed" | "failed" | "timeout" | "stopped",
+    result: task.result,
+    error: task.error,
+    executionTimeMs,
+    associatedTaskId: task.taskId,
+    // 添加 description 和 subagentType 以便 EventMessageFormatter 使用
+    description: task.description,
+    subagentType: task.subagentType,
+  };
+}

package/src/env/task/hooks/contexts.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Task Hook Contexts Tests
+ */
+
+import { describe, test, expect } from "vitest";
+import type {
+  TaskCreateContext,
+  TaskUpdateContext,
+  TaskDeleteContext,
+  TaskDelegateContext,
+  TaskOperationCreateContext,
+  TaskHookContextMap,
+} from "./contexts";
+
+describe("Task Hook Contexts", () => {
+  test("TaskCreateContext should have required fields", () => {
+    const ctx: TaskCreateContext = {
+      options: {
+        title: "Test Task",
+        sessionId: "test-session",
+      },
+      sessionId: "test-session",
+      tagService: {} as any,
+    };
+    
+    expect(ctx.options.title).toBe("Test Task");
+    expect(ctx.sessionId).toBe("test-session");
+    expect(ctx.tagService).toBeDefined();
+  });
+
+  test("TaskUpdateContext should have required fields", () => {
+    const ctx: TaskUpdateContext = {
+      id: 1,
+      options: { title: "Updated Task" },
+      tagService: {} as any,
+    };
+    
+    expect(ctx.id).toBe(1);
+    expect(ctx.options.title).toBe("Updated Task");
+  });
+
+  test("TaskDeleteContext should have required fields", () => {
+    const ctx: TaskDeleteContext = { id: 1 };
+    expect(ctx.id).toBe(1);
+  });
+
+  test("TaskDelegateContext should have required fields", () => {
+    const ctx: TaskDelegateContext = {
+      taskId: 1,
+      prompt: "Do something",
+      subagentType: "general",
+      background: false,
+      tagService: {} as any,
+    };
+    
+    expect(ctx.taskId).toBe(1);
+    expect(ctx.prompt).toBe("Do something");
+    expect(ctx.subagentType).toBe("general");
+    expect(ctx.background).toBe(false);
+  });
+
+  test("TaskOperationCreateContext should have required fields", () => {
+    const ctx: TaskOperationCreateContext = {
+      options: {
+        taskId: 1,
+        sessionId: "test-session",
+        actionType: "create",
+        actionTitle: "Test",
+      },
+    };
+    
+    expect(ctx.options.taskId).toBe(1);
+    expect(ctx.options.actionType).toBe("create");
+  });
+
+  test("TaskHookContextMap should map all hook points", () => {
+    const map: TaskHookContextMap = {
+      "task:before.create": {} as any,
+      "task:after.create": {} as any,
+      "task:before.update": {} as any,
+      "task:after.update": {} as any,
+      "task:before.delete": {} as any,
+      "task:after.delete": {} as any,
+      "task:delegate:before": {} as any,
+      "task:delegate:after": {} as any,
+      "task:operation:before.create": {} as any,
+      "task:operation:after.create": {} as any,
+    };
+    
+    expect(Object.keys(map)).toHaveLength(10);
+  });
+});