@butlerw/vellum 0.1.0

package/src/agents/commands/resume.ts

@@ -0,0 +1,335 @@
+/**
+ * CLI Resume Command - REQ-034)
+ *
+ * Implements the `vellum resume [chainId]` CLI command
+ * for resuming interrupted task chains.
+ *
+ * @module cli/agents/commands/resume
+ */
+
+import type { Command } from "commander";
+import { getOrCreateOrchestrator, getOrchestrator } from "../../orchestrator-singleton.js";
+import { ICONS } from "../../utils/icons.js";
+
+import { createTaskPersistence, type TaskPersistence } from "../task-persistence.js";
+import {
+  createTaskResumption,
+  type ResumeOptions,
+  type ResumeResult,
+  type TaskResumption,
+} from "../task-resumption.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the resume command.
+ *
+ * @example
+ * ```typescript
+ * const options: ResumeCommandOptions = {
+ *   skipFailed: true,
+ *   retryFailed: false,
+ *   from: 'task-123',
+ * };
+ * ```
+ */
+export interface ResumeCommandOptions {
+  /** Skip tasks that previously failed */
+  skipFailed?: boolean;
+  /** Retry failed tasks instead of skipping */
+  retryFailed?: boolean;
+  /** Resume from a specific task ID */
+  from?: string;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Format a date for display in the CLI.
+ *
+ * @param date - Date to format
+ * @returns Formatted date string
+ */
+function formatDate(date: Date): string {
+  return date.toLocaleString();
+}
+
+/**
+ * Format a chain status for display with emoji indicator.
+ *
+ * @param status - Chain status
+ * @returns Formatted status string with emoji
+ */
+function formatStatus(status: string): string {
+  switch (status) {
+    case "paused":
+      return "[PAUSE] paused";
+    case "running":
+      return `${ICONS.interrupted} interrupted`;
+    case "completed":
+      return `${ICONS.success} completed`;
+    case "failed":
+      return `${ICONS.error} failed`;
+    default:
+      return status;
+  }
+}
+
+/**
+ * Display a list of resumable chains in the terminal.
+ *
+ * @param chains - Array of resumable chain metadata
+ */
+function displayResumableChains(
+  chains: Array<{ chainId: string; savedAt: Date; status: string }>
+): void {
+  if (chains.length === 0) {
+    console.log("\nNo resumable task chains found.");
+    console.log("   Task chains become resumable when paused or interrupted.\n");
+    return;
+  }
+
+  console.log(`\n${ICONS.workflow} Resumable Task Chains:\n`);
+  console.log("   %-40s  %-20s  %s", "Chain ID", "Status", "Saved At");
+  console.log(`   ${"-".repeat(80)}`);
+
+  for (const chain of chains) {
+    console.log(
+      "   %-40s  %-20s  %s",
+      chain.chainId,
+      formatStatus(chain.status),
+      formatDate(chain.savedAt)
+    );
+  }
+
+  console.log("\n   Use 'vellum resume <chainId>' to resume a specific chain.\n");
+}
+
+/**
+ * Display detailed resume options for a chain.
+ *
+ * @param chainId - The chain ID
+ * @param options - Resume options for the chain
+ */
+function displayResumeOptions(
+  chainId: string,
+  options: {
+    lastCompletedTask: string;
+    pendingTasks: string[];
+    failedTasks: string[];
+  }
+): void {
+  console.log(`\n📊 Chain Status: ${chainId}\n`);
+
+  if (options.lastCompletedTask) {
+    console.log(`   Last Completed: ${options.lastCompletedTask}`);
+  } else {
+    console.log("   Last Completed: (none)");
+  }
+
+  console.log(`   Pending Tasks:  ${options.pendingTasks.length}`);
+  if (options.pendingTasks.length > 0 && options.pendingTasks.length <= 5) {
+    for (const task of options.pendingTasks) {
+      console.log(`     - ${task}`);
+    }
+  } else if (options.pendingTasks.length > 5) {
+    for (const task of options.pendingTasks.slice(0, 3)) {
+      console.log(`     - ${task}`);
+    }
+    console.log(`     ... and ${options.pendingTasks.length - 3} more`);
+  }
+
+  console.log(`   Failed Tasks:   ${options.failedTasks.length}`);
+  if (options.failedTasks.length > 0) {
+    for (const task of options.failedTasks) {
+      console.log(`     - ${task}`);
+    }
+  }
+
+  console.log("");
+}
+
+/**
+ * Display the result of a resume operation.
+ *
+ * @param result - Resume operation result
+ */
+function displayResumeResult(result: ResumeResult): void {
+  if (!result.resumed) {
+    console.error(`\n${ICONS.error} Failed to resume chain: ${result.chainId}`);
+    console.error("   Chain may not exist or is not in a resumable state.\n");
+    return;
+  }
+
+  console.log(`\n${ICONS.success} Successfully resumed chain: ${result.chainId}`);
+  console.log(`   From Task:        ${result.fromTaskId || "(start)"}`);
+  console.log(`   Tasks Remaining:  ${result.totalRemaining}`);
+
+  if (result.skippedCount > 0) {
+    console.log(`   Tasks Skipped:    ${result.skippedCount}`);
+  }
+
+  console.log("");
+}
+
+// =============================================================================
+// Command Actions
+// =============================================================================
+
+/**
+ * List all resumable task chains.
+ *
+ * @param persistence - Task persistence instance
+ */
+async function listResumableChains(persistence: TaskPersistence): Promise<void> {
+  const chains = await persistence.listResumable();
+  displayResumableChains(chains);
+}
+
+/**
+ * Resume a specific task chain.
+ *
+ * @param chainId - The chain ID to resume
+ * @param options - Resume command options
+ * @param persistence - Task persistence instance
+ * @param resumption - Task resumption instance
+ */
+async function resumeChain(
+  chainId: string,
+  options: ResumeCommandOptions,
+  _persistence: TaskPersistence,
+  resumption: TaskResumption
+): Promise<void> {
+  // First, check if the chain can be resumed
+  const canResume = await resumption.canResume(chainId);
+
+  if (!canResume) {
+    console.error(`\n${ICONS.error} Chain '${chainId}' cannot be resumed.`);
+    console.error("   It may not exist or is not in a resumable state (paused/interrupted).\n");
+    process.exit(1);
+  }
+
+  // Get and display resume options
+  const resumeOptions = await resumption.getResumeOptions(chainId);
+
+  if (resumeOptions) {
+    displayResumeOptions(chainId, resumeOptions);
+  }
+
+  // Build resume options
+  const resumeParams: ResumeOptions = {
+    skipFailed: options.skipFailed,
+    retryFailed: options.retryFailed,
+    fromTask: options.from,
+  };
+
+  // Validate options
+  if (options.skipFailed && options.retryFailed) {
+    console.error(`\n${ICONS.error} Cannot use both --skip-failed and --retry-failed options.\n`);
+    process.exit(1);
+  }
+
+  // If --from is specified, validate it exists in pending or failed tasks
+  if (options.from && resumeOptions) {
+    const allTasks = [...resumeOptions.pendingTasks, ...resumeOptions.failedTasks];
+    if (!allTasks.includes(options.from)) {
+      console.error(
+        `\n${ICONS.error} Task '${options.from}' not found in pending or failed tasks.\n`
+      );
+      console.error("   Available tasks:");
+      for (const task of allTasks.slice(0, 10)) {
+        console.error(`     - ${task}`);
+      }
+      if (allTasks.length > 10) {
+        console.error(`     ... and ${allTasks.length - 10} more`);
+      }
+      console.log("");
+      process.exit(1);
+    }
+  }
+
+  // Execute resume
+  console.log(`${ICONS.running} Resuming task chain...`);
+  const result = await resumption.resume(chainId, resumeParams);
+
+  displayResumeResult(result);
+
+  if (!result.resumed) {
+    process.exit(1);
+  }
+}
+
+// =============================================================================
+// Command Registration
+// =============================================================================
+
+/**
+ * Register the resume command with Commander.js.
+ *
+ * Command: `vellum resume [chainId]`
+ *
+ * If no chainId is provided, lists all resumable chains.
+ *
+ * Options:
+ *   --skip-failed      Skip previously failed tasks
+ *   --retry-failed     Retry previously failed tasks
+ *   --from <taskId>    Resume from specific task
+ *
+ * @example
+ * ```bash
+ * # List all resumable chains
+ * vellum resume
+ *
+ * # Resume a specific chain
+ * vellum resume chain-abc123
+ *
+ * # Resume and skip failed tasks
+ * vellum resume chain-abc123 --skip-failed
+ *
+ * # Resume and retry failed tasks
+ * vellum resume chain-abc123 --retry-failed
+ *
+ * # Resume from a specific task
+ * vellum resume chain-abc123 --from task-456
+ * ```
+ *
+ * @param program - Commander program instance
+ */
+export function registerResumeCommand(program: Command): void {
+  program
+    .command("resume [chainId]")
+    .description("Resume an interrupted task chain")
+    .option("--skip-failed", "Skip previously failed tasks")
+    .option("--retry-failed", "Retry previously failed tasks")
+    .option("--from <taskId>", "Resume from specific task")
+    .action(async (chainId: string | undefined, options: Record<string, unknown>) => {
+      try {
+        // Parse options
+        const commandOptions: ResumeCommandOptions = {
+          skipFailed: options.skipFailed === true,
+          retryFailed: options.retryFailed === true,
+          from: options.from as string | undefined,
+        };
+
+        // Create persistence and resumption instances
+        const persistence = createTaskPersistence();
+        const orchestrator = getOrchestrator() ?? getOrCreateOrchestrator();
+        const resumption = createTaskResumption(persistence, orchestrator);
+
+        if (!chainId) {
+          // List all resumable chains
+          await listResumableChains(persistence);
+        } else {
+          // Resume specific chain
+          await resumeChain(chainId, commandOptions, persistence, resumption);
+        }
+      } catch (error) {
+        console.error(`\n${ICONS.error} Error:`, error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/agents/index.ts

@@ -0,0 +1,29 @@
+/**
+ * CLI Agent Utilities
+ *
+ * Re-exports all agent-related CLI utilities including:
+ * - Task persistence for saving/loading agent task state
+ * - Task resumption for continuing interrupted tasks
+ * - CLI commands for delegate and resume operations
+ */
+
+// CLI commands
+export {
+  type DelegateCommandOptions,
+  type ResumeCommandOptions,
+  registerDelegateCommand,
+  registerResumeCommand,
+} from "./commands/index.js";
+// Task persistence utilities
+export {
+  createTaskPersistence,
+  type PersistedTaskState,
+  type TaskPersistence,
+} from "./task-persistence.js";
+// Task resumption utilities
+export {
+  createTaskResumption,
+  type ResumeOptions,
+  type ResumeResult,
+  type TaskResumption,
+} from "./task-resumption.js";

package/src/agents/task-persistence.ts

@@ -0,0 +1,272 @@
+/**
+ * Task Persistence for Resumable Workflows
+ *
+ * Enables saving and loading task chain state to support
+ * pausing and resuming multi-agent workflows.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { TaskChain } from "@vellum/core";
+
+/**
+ * Serializable version of TaskChain for JSON persistence
+ */
+interface SerializedTaskChain {
+  chainId: string;
+  rootTaskId: string;
+  nodes: Array<{
+    taskId: string;
+    parentTaskId?: string;
+    agentSlug: string;
+    depth: number;
+    createdAt: string;
+    status: "pending" | "running" | "completed" | "failed";
+  }>;
+  maxDepth: number;
+}
+
+/**
+ * Represents the persisted state of a task chain
+ */
+export interface PersistedTaskState {
+  chainId: string;
+  chain: TaskChain;
+  status: "running" | "paused" | "completed" | "failed";
+  lastTaskId: string;
+  checkpoint: {
+    completedTasks: string[];
+    pendingTasks: string[];
+    failedTasks: string[];
+  };
+  savedAt: Date;
+}
+
+/**
+ * Serialized format for JSON storage
+ */
+interface SerializedPersistedTaskState {
+  chainId: string;
+  chain: SerializedTaskChain;
+  status: "running" | "paused" | "completed" | "failed";
+  lastTaskId: string;
+  checkpoint: {
+    completedTasks: string[];
+    pendingTasks: string[];
+    failedTasks: string[];
+  };
+  savedAt: string;
+}
+
+/**
+ * Interface for task state persistence operations
+ */
+export interface TaskPersistence {
+  /**
+   * Save task chain state to persistent storage
+   */
+  saveTaskState(state: PersistedTaskState): Promise<void>;
+
+  /**
+   * Load task chain state from persistent storage
+   * @returns The persisted state, or null if not found
+   */
+  loadTaskState(chainId: string): Promise<PersistedTaskState | null>;
+
+  /**
+   * List all resumable task states
+   */
+  listResumable(): Promise<{ chainId: string; savedAt: Date; status: string }[]>;
+
+  /**
+   * Delete a persisted task state
+   * @returns true if deleted, false if not found
+   */
+  deleteTaskState(chainId: string): Promise<boolean>;
+}
+
+/**
+ * Convert TaskChain to serializable format
+ */
+function serializeTaskChain(chain: TaskChain): SerializedTaskChain {
+  const nodesArray = Array.from(chain.nodes.values()).map((node) => ({
+    taskId: node.taskId,
+    parentTaskId: node.parentTaskId,
+    agentSlug: node.agentSlug,
+    depth: node.depth,
+    createdAt: node.createdAt.toISOString(),
+    status: node.status,
+  }));
+
+  return {
+    chainId: chain.chainId,
+    rootTaskId: chain.rootTaskId,
+    nodes: nodesArray,
+    maxDepth: chain.maxDepth,
+  };
+}
+
+/**
+ * Convert serialized format back to TaskChain
+ */
+function deserializeTaskChain(serialized: SerializedTaskChain): TaskChain {
+  const nodes = new Map(
+    serialized.nodes.map((node) => [
+      node.taskId,
+      {
+        taskId: node.taskId,
+        parentTaskId: node.parentTaskId,
+        agentSlug: node.agentSlug,
+        depth: node.depth,
+        createdAt: new Date(node.createdAt),
+        status: node.status,
+      },
+    ])
+  );
+
+  return {
+    chainId: serialized.chainId,
+    rootTaskId: serialized.rootTaskId,
+    nodes,
+    maxDepth: serialized.maxDepth,
+  };
+}
+
+/**
+ * Convert PersistedTaskState to JSON-serializable format
+ */
+function serializeState(state: PersistedTaskState): SerializedPersistedTaskState {
+  return {
+    chainId: state.chainId,
+    chain: serializeTaskChain(state.chain),
+    status: state.status,
+    lastTaskId: state.lastTaskId,
+    checkpoint: state.checkpoint,
+    savedAt: state.savedAt.toISOString(),
+  };
+}
+
+/**
+ * Convert JSON data back to PersistedTaskState
+ */
+function deserializeState(data: SerializedPersistedTaskState): PersistedTaskState {
+  return {
+    chainId: data.chainId,
+    chain: deserializeTaskChain(data.chain),
+    status: data.status,
+    lastTaskId: data.lastTaskId,
+    checkpoint: data.checkpoint,
+    savedAt: new Date(data.savedAt),
+  };
+}
+
+/**
+ * Sanitize chainId to prevent path traversal attacks
+ */
+function sanitizeChainId(chainId: string): string {
+  // Remove any path separators and dots that could cause traversal
+  return chainId.replace(/[/\\.:]/g, "_");
+}
+
+/**
+ * Create a TaskPersistence instance
+ * @param baseDir Base directory for task storage (default: '.vellum/tasks/')
+ */
+export function createTaskPersistence(baseDir = ".vellum/tasks/"): TaskPersistence {
+  const resolvedBaseDir = path.resolve(baseDir);
+
+  /**
+   * Ensure the storage directory exists
+   */
+  async function ensureDirectory(): Promise<void> {
+    await fs.mkdir(resolvedBaseDir, { recursive: true });
+  }
+
+  /**
+   * Get the file path for a chain ID
+   */
+  function getFilePath(chainId: string): string {
+    const safeChainId = sanitizeChainId(chainId);
+    return path.join(resolvedBaseDir, `${safeChainId}.json`);
+  }
+
+  return {
+    async saveTaskState(state: PersistedTaskState): Promise<void> {
+      await ensureDirectory();
+      const filePath = getFilePath(state.chainId);
+      const serialized = serializeState(state);
+      await fs.writeFile(filePath, JSON.stringify(serialized, null, 2), "utf-8");
+    },
+
+    async loadTaskState(chainId: string): Promise<PersistedTaskState | null> {
+      const filePath = getFilePath(chainId);
+
+      try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const data = JSON.parse(content) as SerializedPersistedTaskState;
+        return deserializeState(data);
+      } catch (error) {
+        // Return null if file doesn't exist
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return null;
+        }
+        throw error;
+      }
+    },
+
+    async listResumable(): Promise<{ chainId: string; savedAt: Date; status: string }[]> {
+      try {
+        await ensureDirectory();
+        const files = await fs.readdir(resolvedBaseDir);
+        const jsonFiles = files.filter((f) => f.endsWith(".json"));
+
+        const results: { chainId: string; savedAt: Date; status: string }[] = [];
+
+        for (const file of jsonFiles) {
+          try {
+            const filePath = path.join(resolvedBaseDir, file);
+            const content = await fs.readFile(filePath, "utf-8");
+            const data = JSON.parse(content) as SerializedPersistedTaskState;
+
+            // Only include resumable states (running or paused)
+            if (data.status === "running" || data.status === "paused") {
+              results.push({
+                chainId: data.chainId,
+                savedAt: new Date(data.savedAt),
+                status: data.status,
+              });
+            }
+          } catch {
+            // Skip files that can't be parsed
+          }
+        }
+
+        // Sort by savedAt descending (most recent first)
+        results.sort((a, b) => b.savedAt.getTime() - a.savedAt.getTime());
+
+        return results;
+      } catch (error) {
+        // Return empty list if directory doesn't exist
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return [];
+        }
+        throw error;
+      }
+    },
+
+    async deleteTaskState(chainId: string): Promise<boolean> {
+      const filePath = getFilePath(chainId);
+
+      try {
+        await fs.unlink(filePath);
+        return true;
+      } catch (error) {
+        // Return false if file doesn't exist
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return false;
+        }
+        throw error;
+      }
+    },
+  };
+}