@ai-setting/roy-agent-core 1.0.0

package/src/env/workflow/tools/run-workflow.test.ts

@@ -0,0 +1,352 @@
+/**
+ * Run Workflow Tool Tests - Phase 7
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "bun:test";
+import { z } from "zod";
+import { createRunWorkflowTool, resetRunWorkflowTool } from "./run-workflow";
+import type { WorkflowService } from "../service/workflow-service";
+import type { ToolContext } from "../../../env/tool/types";
+
+// Mock logger
+vi.mock("../../../env/log-trace/logger", () => ({
+  createLogger: () => ({
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  }),
+}));
+
+describe("RunWorkflowTool", () => {
+  let mockWorkflowService: Partial<WorkflowService>;
+  let tool: ReturnType<typeof createRunWorkflowTool>;
+  let mockContext: ToolContext;
+
+  beforeEach(() => {
+    // Reset state
+    resetRunWorkflowTool();
+
+    // Create mock WorkflowService
+    mockWorkflowService = {
+      runWorkflow: vi.fn(),
+    };
+
+    // Create the tool
+    tool = createRunWorkflowTool(mockWorkflowService as WorkflowService);
+
+    // Create mock context
+    mockContext = {
+      workdir: "/tmp",
+    };
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("Tool Definition", () => {
+    it("should have correct name", () => {
+      expect(tool.name).toBe("run-workflow");
+    });
+
+    it("should have correct description", () => {
+      expect(tool.description).toBe(
+        "Run a workflow by name with optional input. Returns run_id, status, output, error, and duration_ms."
+      );
+    });
+
+    it("should have correct category in metadata", () => {
+      expect(tool.metadata?.category).toBe("workflow");
+    });
+
+    it("should have workflow tags", () => {
+      expect(tool.metadata?.tags).toEqual(["workflow", "execute", "run"]);
+    });
+
+    it("should have sandbox disabled", () => {
+      expect(tool.sandbox?.enabled).toBe(false);
+    });
+
+    it("should have safe permission level", () => {
+      expect(tool.permission?.level).toBe("safe");
+    });
+  });
+
+  describe("Parameter Schema", () => {
+    it("should handle missing workflow_name gracefully", async () => {
+      // When called directly (without ToolComponent validation), 
+      // the tool should handle missing required params
+      const result = await tool.execute({}, mockContext);
+      // The tool receives undefined as workflow_name and fails when trying to use it
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Failed to run workflow");
+    });
+
+    it("should accept valid workflow_name", async () => {
+      // Mock the service to avoid actual execution
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+        output: { result: "success" },
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow" },
+        mockContext
+      );
+      expect(result.success).toBe(true);
+    });
+
+    it("should accept optional input parameter", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+        output: { result: "success" },
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow", input: { key: "value" } },
+        mockContext
+      );
+      expect(result.success).toBe(true);
+      expect(mockWorkflowService.runWorkflow).toHaveBeenCalledWith(
+        "test-workflow",
+        { key: "value" },
+        { sync: true }
+      );
+    });
+
+    it("should accept sync parameter", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+      });
+
+      await tool.execute(
+        { workflow_name: "test-workflow", sync: false },
+        mockContext
+      );
+      expect(mockWorkflowService.runWorkflow).toHaveBeenCalledWith(
+        "test-workflow",
+        undefined,
+        { sync: false }
+      );
+    });
+
+    it("should accept timeout parameter", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+      });
+
+      await tool.execute(
+        { workflow_name: "test-workflow", timeout: 5000 },
+        mockContext
+      );
+      expect(mockWorkflowService.runWorkflow).toHaveBeenCalledWith(
+        "test-workflow",
+        undefined,
+        { sync: true }
+      );
+    });
+  });
+
+  describe("Sync Execution", () => {
+    it("should return completed status for successful sync execution", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+        output: { result: "success" },
+        durationMs: 100,
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow", sync: true },
+        mockContext
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.output).toEqual({
+        run_id: "run-123",
+        status: "completed",
+        output: { result: "success" },
+        error: undefined,
+        duration_ms: 100,
+      });
+    });
+
+    it("should return failed status for failed sync execution", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "failed",
+        error: "Something went wrong",
+        durationMs: 50,
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow", sync: true },
+        mockContext
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.output).toEqual({
+        run_id: "run-123",
+        status: "failed",
+        output: undefined,
+        error: "Something went wrong",
+        duration_ms: 50,
+      });
+    });
+
+    it("should include execution_time_ms in metadata", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-123",
+        status: "completed",
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow" },
+        mockContext
+      );
+
+      expect(result.metadata?.execution_time_ms).toBeDefined();
+      expect(typeof result.metadata?.execution_time_ms).toBe("number");
+    });
+  });
+
+  describe("Async Execution", () => {
+    it("should return immediately with run_id for async execution", async () => {
+      (mockWorkflowService.runWorkflow as any).mockResolvedValue({
+        runId: "run-456",
+        status: "running",
+      });
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow", sync: false },
+        mockContext
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.output).toEqual({
+        run_id: "run-456",
+        status: "running",
+        duration_ms: expect.any(Number),
+      });
+      // Should not include full output for async
+      expect((result.output as any).output).toBeUndefined();
+    });
+  });
+
+  describe("Error Handling", () => {
+    it("should handle workflow not found error", async () => {
+      (mockWorkflowService.runWorkflow as any).mockRejectedValue(
+        new Error("Workflow not found: non-existent-workflow")
+      );
+
+      const result = await tool.execute(
+        { workflow_name: "non-existent-workflow" },
+        mockContext
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe(
+        "Workflow not found: non-existent-workflow"
+      );
+    });
+
+    it("should handle execution errors", async () => {
+      (mockWorkflowService.runWorkflow as any).mockRejectedValue(
+        new Error("Internal error")
+      );
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow" },
+        mockContext
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Failed to run workflow");
+      expect(result.error).toContain("Internal error");
+    });
+
+    it("should handle timeout errors", async () => {
+      // Create a tool with a short timeout
+      const slowTool = createRunWorkflowTool(mockWorkflowService as WorkflowService);
+
+      // Mock a slow-running workflow
+      (mockWorkflowService.runWorkflow as any).mockImplementation(
+        () => new Promise((resolve) => setTimeout(resolve, 1000))
+      );
+
+      const result = await slowTool.execute(
+        { workflow_name: "slow-workflow", timeout: 100 },
+        mockContext
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("timed out");
+    });
+  });
+
+  describe("External Abort Signal", () => {
+    it("should handle external abort signal", async () => {
+      const abortController = new AbortController();
+
+      (mockWorkflowService.runWorkflow as any).mockImplementation(
+        () =>
+          new Promise((_, reject) => {
+            abortController.signal.addEventListener("abort", () => {
+              reject(new Error("The operation was aborted"));
+            });
+          })
+      );
+
+      const contextWithAbort: ToolContext = {
+        ...mockContext,
+        abort: abortController.signal,
+      };
+
+      // Abort after a short delay
+      setTimeout(() => abortController.abort(), 50);
+
+      const result = await tool.execute(
+        { workflow_name: "test-workflow" },
+        contextWithAbort
+      );
+
+      expect(result.success).toBe(false);
+      // Should handle abort-related errors
+      expect(result.error).toMatch(/aborted|timed out/i);
+    });
+  });
+});
+
+describe("RunWorkflowInputSchema", () => {
+  it("should validate correct input", () => {
+    const { RunWorkflowInputSchema } = require("./run-workflow");
+    const result = RunWorkflowInputSchema.safeParse({
+      workflow_name: "test",
+      input: { key: "value" },
+      sync: true,
+      timeout: 5000,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("should require workflow_name", () => {
+    const { RunWorkflowInputSchema } = require("./run-workflow");
+    const result = RunWorkflowInputSchema.safeParse({});
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].path).toContain("workflow_name");
+  });
+
+  it("should have default sync=true", () => {
+    const { RunWorkflowInputSchema } = require("./run-workflow");
+    const result = RunWorkflowInputSchema.safeParse({
+      workflow_name: "test",
+    });
+    expect(result.success).toBe(true);
+    expect(result.data?.sync).toBe(true);
+  });
+});

package/src/env/workflow/tools/run-workflow.ts

@@ -0,0 +1,214 @@
+/**
+ * Run Workflow Tool - Phase 7
+ * 
+ * A Tool for executing workflows by name from within other workflows or agents.
+ */
+
+import { z } from "zod";
+import type { Tool, ToolContext, ToolResult } from "../../../env/tool/types";
+import type { WorkflowService } from "../service/workflow-service";
+import { createLogger } from "../../../env/log-trace/logger";
+
+// 创建日志器
+const logger = createLogger("run-workflow-tool");
+
+/**
+ * Input schema for run-workflow tool
+ */
+export const RunWorkflowInputSchema = z.object({
+  workflow_name: z.string().describe("Name of the workflow to run"),
+  input: z.record(z.any()).optional().describe("Input to pass to the workflow"),
+  sync: z.boolean().default(true).describe("Wait for completion (default: true)"),
+  timeout: z.number().positive().optional().describe("Timeout in milliseconds"),
+});
+
+export type RunWorkflowInput = z.infer<typeof RunWorkflowInputSchema>;
+
+/**
+ * Run Workflow Tool interface for type-safe access
+ */
+export interface RunWorkflowToolInterface {
+  name: "run-workflow";
+  description: string;
+  inputSchema: typeof RunWorkflowInputSchema;
+}
+
+/**
+ * Create a run-workflow tool with the given WorkflowService
+ * 
+ * @param workflowService - The WorkflowService instance for executing workflows
+ * @returns A Tool instance for running workflows
+ */
+export function createRunWorkflowTool(workflowService: WorkflowService): Tool {
+  return {
+    name: "run-workflow",
+    description: "Run a workflow by name with optional input. Returns run_id, status, output, error, and duration_ms.",
+    parameters: RunWorkflowInputSchema,
+    sandbox: {
+      enabled: false, // Workflow execution doesn't need sandbox
+    },
+    permission: {
+      level: "safe",
+    },
+    metadata: {
+      category: "workflow",
+      tags: ["workflow", "execute", "run"],
+      version: "1.0.0",
+      experimental: false,
+    },
+    execute: async (args, ctx: ToolContext): Promise<ToolResult> => {
+      const startTime = Date.now();
+      const { workflow_name, input, sync = true, timeout } = args;
+
+      logger.info(`Running workflow: ${workflow_name}`, { input, sync, timeout });
+
+      let timeoutHandle: NodeJS.Timeout | undefined;
+      let durationMs: number;
+
+      try {
+        let result;
+        
+        if (timeout) {
+          // Execute workflow with timeout wrapper
+          result = await Promise.race([
+            workflowService.runWorkflow(workflow_name, input, { sync }),
+            new Promise<never>((_, reject) => {
+              timeoutHandle = setTimeout(() => {
+                reject(new Error("Workflow execution timed out"));
+              }, timeout);
+            }),
+          ]);
+        } else {
+          // No timeout - execute directly
+          result = await workflowService.runWorkflow(workflow_name, input, { sync });
+        }
+
+        // Clear timeout
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+
+        durationMs = Date.now() - startTime;
+
+        // Handle the result based on execution mode
+        if (sync) {
+          // Synchronous execution - return full result
+          return {
+            success: result.status === "completed",
+            output: {
+              run_id: result.runId,
+              status: result.status,
+              output: result.output,
+              error: result.error,
+              duration_ms: result.durationMs || durationMs,
+            },
+            metadata: {
+              execution_time_ms: durationMs,
+            },
+          };
+        } else {
+          // Asynchronous execution - return run_id immediately
+          return {
+            success: true,
+            output: {
+              run_id: result.runId,
+              status: result.status,
+              duration_ms: durationMs,
+            },
+            metadata: {
+              execution_time_ms: durationMs,
+            },
+          };
+        }
+      } catch (error) {
+        // Clear timeout on error
+        if (timeoutHandle) {
+          clearTimeout(timeoutHandle);
+        }
+
+        durationMs = Date.now() - startTime;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+
+        // Handle specific error types
+        if (errorMessage.includes("Workflow not found")) {
+          return {
+            success: false,
+            output: "",
+            error: `Workflow not found: ${workflow_name}`,
+            metadata: {
+              execution_time_ms: durationMs,
+            },
+          };
+        }
+
+        if (errorMessage.includes("abort") || errorMessage.includes("timed out")) {
+          return {
+            success: false,
+            output: "",
+            error: `Workflow execution timed out or was aborted: ${workflow_name}`,
+            metadata: {
+              execution_time_ms: durationMs,
+            },
+          };
+        }
+
+        // Safe logging - don't throw if logger is not available
+        if (logger?.error) {
+          logger.error(`Failed to run workflow: ${workflow_name}`, { error: errorMessage });
+        }
+
+        return {
+          success: false,
+          output: "",
+          error: `Failed to run workflow ${workflow_name}: ${errorMessage}`,
+          metadata: {
+            execution_time_ms: durationMs,
+          },
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Default run-workflow tool instance (lazy initialization)
+ * This is a placeholder that should be replaced with the actual tool
+ * created via createRunWorkflowTool(workflowService) in the application
+ */
+let _runWorkflowTool: Tool | null = null;
+let _workflowService: WorkflowService | null = null;
+
+/**
+ * Initialize the run-workflow tool with a WorkflowService
+ * 
+ * @param workflowService - The WorkflowService instance
+ */
+export function initRunWorkflowTool(workflowService: WorkflowService): void {
+  _workflowService = workflowService;
+  _runWorkflowTool = createRunWorkflowTool(workflowService);
+}
+
+/**
+ * Get the run-workflow tool instance
+ * 
+ * @throws Error if the tool has not been initialized
+ */
+export function getRunWorkflowTool(): Tool {
+  if (!_runWorkflowTool || !_workflowService) {
+    throw new Error(
+      "run-workflow tool not initialized. Call initRunWorkflowTool(workflowService) first."
+    );
+  }
+  return _runWorkflowTool;
+}
+
+/**
+ * Reset the run-workflow tool (for testing)
+ */
+export function resetRunWorkflowTool(): void {
+  _runWorkflowTool = null;
+  _workflowService = null;
+}
+
+// Re-export the tool interface for type checking
+export type RunWorkflowTool = ReturnType<typeof createRunWorkflowTool>;

package/src/env/workflow/types/context.ts

@@ -0,0 +1,18 @@
+/**
+ * askUser 选项
+ */
+export interface AskUserOptions {
+  options?: string[];
+  required_confirm?: boolean;
+}
+
+/**
+ * 从 Session 恢复的运行时状态
+ */
+export interface RuntimeState {
+  sessionId: string;
+  nodeOutputs: Map<string, unknown>;
+  pendingNodeId: string | null;
+  waitingForUser: boolean;
+  agentSessionId?: string;
+}