@butlerw/vellum 0.1.0

package/src/agents/__tests__/task-persistence.test.ts

@@ -0,0 +1,235 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { TaskChain, TaskChainNode } from "@vellum/core";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  createTaskPersistence,
+  type PersistedTaskState,
+  type TaskPersistence,
+} from "../task-persistence.js";
+
+describe("TaskPersistence", () => {
+  let tempDir: string;
+  let persistence: TaskPersistence;
+
+  beforeEach(async () => {
+    tempDir = path.join(os.tmpdir(), `vellum-test-${Date.now()}`);
+    persistence = createTaskPersistence(tempDir);
+  });
+
+  afterEach(async () => {
+    // Clean up temp directory
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  function createMockTaskChain(): TaskChain {
+    const nodes = new Map<string, TaskChainNode>();
+    nodes.set("task-1", {
+      taskId: "task-1",
+      parentTaskId: undefined,
+      agentSlug: "orchestrator",
+      depth: 0,
+      createdAt: new Date("2025-01-01T00:00:00Z"),
+      status: "completed",
+    });
+    nodes.set("task-2", {
+      taskId: "task-2",
+      parentTaskId: "task-1",
+      agentSlug: "coder",
+      depth: 1,
+      createdAt: new Date("2025-01-01T00:01:00Z"),
+      status: "running",
+    });
+
+    return {
+      chainId: "chain-123",
+      rootTaskId: "task-1",
+      nodes,
+      maxDepth: 3,
+    };
+  }
+
+  function createMockState(overrides: Partial<PersistedTaskState> = {}): PersistedTaskState {
+    return {
+      chainId: "chain-123",
+      chain: createMockTaskChain(),
+      status: "running",
+      lastTaskId: "task-2",
+      checkpoint: {
+        completedTasks: ["task-1"],
+        pendingTasks: [],
+        failedTasks: [],
+      },
+      savedAt: new Date("2025-01-01T00:02:00Z"),
+      ...overrides,
+    };
+  }
+
+  describe("saveTaskState", () => {
+    it("should create directory and save state as JSON", async () => {
+      const state = createMockState();
+
+      await persistence.saveTaskState(state);
+
+      const filePath = path.join(tempDir, "chain-123.json");
+      const content = await fs.readFile(filePath, "utf-8");
+      const parsed = JSON.parse(content);
+
+      expect(parsed.chainId).toBe("chain-123");
+      expect(parsed.status).toBe("running");
+      expect(parsed.lastTaskId).toBe("task-2");
+      expect(parsed.chain.nodes).toHaveLength(2);
+    });
+
+    it("should sanitize chainId to prevent path traversal", async () => {
+      const state = createMockState({ chainId: "../../../evil" });
+
+      await persistence.saveTaskState(state);
+
+      // Should create sanitized file name (../../../evil -> _________evil)
+      const files = await fs.readdir(tempDir);
+      expect(files).toContain("_________evil.json");
+      expect(files).not.toContain("evil.json");
+    });
+
+    it("should overwrite existing state", async () => {
+      const state1 = createMockState({ status: "running" });
+      const state2 = createMockState({ status: "paused" });
+
+      await persistence.saveTaskState(state1);
+      await persistence.saveTaskState(state2);
+
+      const loaded = await persistence.loadTaskState("chain-123");
+      expect(loaded?.status).toBe("paused");
+    });
+  });
+
+  describe("loadTaskState", () => {
+    it("should return null for non-existent chain", async () => {
+      const result = await persistence.loadTaskState("non-existent");
+
+      expect(result).toBeNull();
+    });
+
+    it("should load and deserialize saved state", async () => {
+      const state = createMockState();
+      await persistence.saveTaskState(state);
+
+      const loaded = await persistence.loadTaskState("chain-123");
+
+      expect(loaded).not.toBeNull();
+      if (!loaded) throw new Error("loaded should not be null");
+      expect(loaded.chainId).toBe("chain-123");
+      expect(loaded.status).toBe("running");
+      expect(loaded.chain.nodes.size).toBe(2);
+      expect(loaded.chain.nodes.get("task-1")?.status).toBe("completed");
+      expect(loaded.savedAt).toBeInstanceOf(Date);
+      expect(loaded.chain.nodes.get("task-1")?.createdAt).toBeInstanceOf(Date);
+    });
+
+    it("should correctly restore Map from array", async () => {
+      const state = createMockState();
+      await persistence.saveTaskState(state);
+
+      const loaded = await persistence.loadTaskState("chain-123");
+
+      if (!loaded) throw new Error("loaded should not be null");
+      expect(loaded.chain.nodes).toBeInstanceOf(Map);
+      expect(loaded.chain.nodes.get("task-2")?.agentSlug).toBe("coder");
+    });
+  });
+
+  describe("listResumable", () => {
+    it("should return empty array when no tasks exist", async () => {
+      const result = await persistence.listResumable();
+
+      expect(result).toEqual([]);
+    });
+
+    it("should only list running and paused tasks", async () => {
+      await persistence.saveTaskState(createMockState({ chainId: "running-1", status: "running" }));
+      await persistence.saveTaskState(createMockState({ chainId: "paused-1", status: "paused" }));
+      await persistence.saveTaskState(
+        createMockState({ chainId: "completed-1", status: "completed" })
+      );
+      await persistence.saveTaskState(createMockState({ chainId: "failed-1", status: "failed" }));
+
+      const result = await persistence.listResumable();
+
+      expect(result).toHaveLength(2);
+      expect(result.map((r) => r.chainId)).toContain("running-1");
+      expect(result.map((r) => r.chainId)).toContain("paused-1");
+      expect(result.map((r) => r.chainId)).not.toContain("completed-1");
+      expect(result.map((r) => r.chainId)).not.toContain("failed-1");
+    });
+
+    it("should sort by savedAt descending", async () => {
+      await persistence.saveTaskState(
+        createMockState({
+          chainId: "older",
+          status: "running",
+          savedAt: new Date("2025-01-01T00:00:00Z"),
+        })
+      );
+      await persistence.saveTaskState(
+        createMockState({
+          chainId: "newer",
+          status: "running",
+          savedAt: new Date("2025-01-02T00:00:00Z"),
+        })
+      );
+
+      const result = await persistence.listResumable();
+
+      expect(result[0]?.chainId).toBe("newer");
+      expect(result[1]?.chainId).toBe("older");
+    });
+
+    it("should include status and savedAt in results", async () => {
+      await persistence.saveTaskState(
+        createMockState({
+          chainId: "test",
+          status: "paused",
+          savedAt: new Date("2025-06-15T12:30:00Z"),
+        })
+      );
+
+      const result = await persistence.listResumable();
+
+      expect(result[0]?.status).toBe("paused");
+      expect(result[0]?.savedAt).toBeInstanceOf(Date);
+    });
+  });
+
+  describe("deleteTaskState", () => {
+    it("should return false for non-existent chain", async () => {
+      const result = await persistence.deleteTaskState("non-existent");
+
+      expect(result).toBe(false);
+    });
+
+    it("should delete existing state and return true", async () => {
+      await persistence.saveTaskState(createMockState());
+
+      const result = await persistence.deleteTaskState("chain-123");
+
+      expect(result).toBe(true);
+
+      const loaded = await persistence.loadTaskState("chain-123");
+      expect(loaded).toBeNull();
+    });
+  });
+
+  describe("createTaskPersistence", () => {
+    it("should use default directory when not specified", () => {
+      const defaultPersistence = createTaskPersistence();
+      // Just verify it creates without error
+      expect(defaultPersistence).toBeDefined();
+    });
+  });
+});

package/src/agents/commands/delegate.ts

@@ -0,0 +1,240 @@
+/**
+ * CLI Delegate Command - REQ-034)
+ *
+ * Implements the `vellum delegate <agent> <task>` CLI command
+ * for delegating tasks to specific agents.
+ *
+ * @module cli/agents/commands/delegate
+ */
+
+import {
+  AgentLevel,
+  DEFAULT_DELEGATION_TIMEOUT,
+  type DelegateTaskContext,
+  type DelegateTaskParams,
+  type DelegateTaskResult,
+  type DelegationTarget,
+  executeDelegateTask,
+} from "@vellum/core";
+import type { Command } from "commander";
+
+import { ICONS } from "../../utils/icons.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the delegate command.
+ *
+ * @example
+ * ```typescript
+ * const options: DelegateCommandOptions = {
+ *   files: ['src/auth/login.ts', 'src/auth/types.ts'],
+ *   timeout: 60000,
+ *   confirm: true,
+ * };
+ * ```
+ */
+export interface DelegateCommandOptions {
+  /** Related files for the task (comma-separated in CLI, parsed to array) */
+  files?: string[];
+  /** Task timeout in milliseconds */
+  timeout?: number;
+  /** Whether to show confirmation prompt before delegation */
+  confirm?: boolean;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Parse comma-separated file paths into an array.
+ *
+ * @param value - Comma-separated file paths
+ * @returns Array of file paths, or undefined if empty
+ */
+function parseFiles(value: string | undefined): string[] | undefined {
+  if (!value) return undefined;
+  return value
+    .split(",")
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0);
+}
+
+/**
+ * Parse timeout value with validation.
+ *
+ * @param value - Timeout string value
+ * @returns Parsed timeout in milliseconds
+ * @throws Error if timeout is invalid
+ */
+function parseTimeout(value: string): number {
+  const timeout = parseInt(value, 10);
+  if (Number.isNaN(timeout) || timeout <= 0) {
+    throw new Error(`Invalid timeout value: ${value}. Must be a positive integer.`);
+  }
+  return timeout;
+}
+
+/**
+ * Create a DelegationTarget from an agent slug.
+ *
+ * CLI delegation supports builtin agents and MCP targets.
+ * Custom agents require a mode config and should be created
+ * through the TUI or programmatic API.
+ *
+ * @param agent - Agent identifier (slug or prefixed identifier)
+ * @returns DelegationTarget for the specified agent
+ * @throws Error if target format is invalid or unsupported
+ */
+function createDelegationTarget(agent: string): DelegationTarget {
+  // Custom agents require mode config - not supported via CLI
+  if (agent.startsWith("custom:")) {
+    throw new Error(
+      `Custom agents require a mode configuration and cannot be delegated via CLI. ` +
+        `Use the TUI or programmatic API for custom agent delegation.`
+    );
+  }
+
+  // MCP targets: mcp:serverId/toolName
+  if (agent.startsWith("mcp:")) {
+    const mcpPart = agent.slice(4);
+    const [serverId, toolName] = mcpPart.split("/");
+    if (!serverId || !toolName) {
+      throw new Error(`Invalid MCP target format: ${agent}. Expected 'mcp:serverId/toolName'.`);
+    }
+    return {
+      kind: "mcp",
+      serverId,
+      toolName,
+    };
+  }
+
+  // Default to builtin agent
+  return {
+    kind: "builtin",
+    slug: agent,
+  };
+}
+
+/**
+ * Create a mock DelegateTaskContext for CLI execution.
+ *
+ * In a full implementation, this would be integrated with the
+ * session and agent management systems.
+ *
+ * @returns DelegateTaskContext for CLI execution
+ */
+function createCliContext(): DelegateTaskContext {
+  return {
+    workingDir: process.cwd(),
+    sessionId: `cli-${Date.now()}`,
+    messageId: `msg-${Date.now()}`,
+    callId: `call-${Date.now()}`,
+    abortSignal: new AbortController().signal,
+    // CLI runs as orchestrator level (can delegate)
+    agentLevel: AgentLevel.orchestrator,
+    agentSlug: "cli",
+    checkPermission: async () => true,
+  };
+}
+
+// =============================================================================
+// Command Registration
+// =============================================================================
+
+/**
+ * Register the delegate command with Commander.js.
+ *
+ * Command: `vellum delegate <agent> <task>`
+ *
+ * Options:
+ *   --files <paths>    Related files (comma-separated)
+ *   --timeout <ms>     Task timeout in milliseconds (default: 300000)
+ *   --no-confirm       Skip confirmation prompt
+ *
+ * @example
+ * ```bash
+ * # Delegate a task to the coder agent
+ * vellum delegate coder "Implement authentication module"
+ *
+ * # With files context
+ * vellum delegate coder "Fix bug in login" --files src/auth/login.ts,src/auth/types.ts
+ *
+ * # With custom timeout
+ * vellum delegate analyst "Analyze codebase" --timeout 600000
+ *
+ * # Delegate to custom agent
+ * vellum delegate custom:my-agent "Custom task"
+ *
+ * # Delegate to MCP tool
+ * vellum delegate mcp:server/tool "MCP task"
+ * ```
+ *
+ * @param program - Commander program instance
+ */
+export function registerDelegateCommand(program: Command): void {
+  program
+    .command("delegate <agent> <task>")
+    .description("Delegate a task to a specific agent")
+    .option("--files <paths>", "Related files (comma-separated)")
+    .option("--timeout <ms>", "Task timeout in milliseconds", String(DEFAULT_DELEGATION_TIMEOUT))
+    .option("--no-confirm", "Skip confirmation prompt")
+    .action(async (agent: string, task: string, options: Record<string, unknown>) => {
+      try {
+        // Parse options
+        const delegateOptions: DelegateCommandOptions = {
+          files: parseFiles(options.files as string | undefined),
+          timeout: parseTimeout((options.timeout as string) || String(DEFAULT_DELEGATION_TIMEOUT)),
+          confirm: options.confirm !== false,
+        };
+
+        // Create delegation target
+        const target = createDelegationTarget(agent);
+
+        // Confirmation prompt (if enabled)
+        if (delegateOptions.confirm) {
+          console.log(`\n${ICONS.workflow} Delegation Details:`);
+          console.log(`   Agent: ${agent}`);
+          console.log(`   Task: ${task}`);
+          if (delegateOptions.files?.length) {
+            console.log(`   Files: ${delegateOptions.files.join(", ")}`);
+          }
+          console.log(`   Timeout: ${delegateOptions.timeout}ms`);
+          console.log("");
+
+          // In a full implementation, use readline or inquirer for confirmation
+          // For now, we proceed directly (confirmation can be skipped with --no-confirm)
+        }
+
+        // Build delegation parameters
+        const params: DelegateTaskParams = {
+          target,
+          task,
+          context: delegateOptions.files ? { files: delegateOptions.files } : undefined,
+          timeout: delegateOptions.timeout,
+        };
+
+        // Execute delegation
+        const context = createCliContext();
+        const result: DelegateTaskResult = await executeDelegateTask(params, context);
+
+        if (result.success) {
+          console.log(`\n${ICONS.success} Delegation successful!`);
+          console.log(`   Task Packet ID: ${result.taskPacketId}`);
+          if (result.agentId) {
+            console.log(`   Agent ID: ${result.agentId}`);
+          }
+        } else {
+          console.error(`\n${ICONS.error} Delegation failed:`);
+          console.error(`   ${result.error}`);
+          process.exit(1);
+        }
+      } catch (error) {
+        console.error(`\n${ICONS.error} Error:`, error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/agents/commands/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent Commands Index
+ *
+ * Re-exports all agent-related CLI commands.
+ *
+ * @module cli/agents/commands
+ */
+
+export { type DelegateCommandOptions, registerDelegateCommand } from "./delegate.js";
+export { type ResumeCommandOptions, registerResumeCommand } from "./resume.js";