@vellumai/assistant 0.5.5 → 0.5.7

package/src/swarm/graph-utils.ts

@@ -1,53 +0,0 @@
-/**
- * Shared graph utilities for swarm DAG operations.
- */
-
-export interface GraphNode {
-  id: string;
-  dependencies: string[];
-}
-
-/**
- * Detect cycles in a directed graph using Kahn's algorithm.
- * Returns the IDs of nodes involved in cycles, or null if the graph is acyclic.
- */
-export function detectCycles(nodes: GraphNode[]): string[] | null {
-  const inDegree = new Map<string, number>();
-  const adj = new Map<string, string[]>();
-
-  for (const node of nodes) {
-    inDegree.set(node.id, 0);
-    adj.set(node.id, []);
-  }
-
-  for (const node of nodes) {
-    for (const dep of node.dependencies) {
-      if (adj.has(dep)) {
-        adj.get(dep)!.push(node.id);
-        inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
-      }
-    }
-  }
-
-  const queue: string[] = [];
-  for (const [id, deg] of inDegree) {
-    if (deg === 0) queue.push(id);
-  }
-
-  let processed = 0;
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    processed++;
-    for (const neighbor of adj.get(current)!) {
-      const newDeg = (inDegree.get(neighbor) ?? 0) - 1;
-      inDegree.set(neighbor, newDeg);
-      if (newDeg === 0) queue.push(neighbor);
-    }
-  }
-
-  if (processed < nodes.length) {
-    return nodes.filter((n) => (inDegree.get(n.id) ?? 0) > 0).map((n) => n.id);
-  }
-
-  return null;
-}

package/src/swarm/index.ts

@@ -1,55 +0,0 @@
-export type { SwarmCheckpoint } from "./checkpoint.js";
-export {
-  isCheckpointCompatible,
-  loadCheckpoint,
-  removeCheckpoint,
-  writeCheckpoint,
-} from "./checkpoint.js";
-export type { SwarmLimits } from "./limits.js";
-export {
-  getTimeoutForRole,
-  resolveSwarmLimits,
-  SWARM_HARD_LIMITS,
-} from "./limits.js";
-export type {
-  ExecuteSwarmOptions,
-  OrchestratorEvent,
-  OrchestratorEventKind,
-  OrchestratorStatusCallback,
-} from "./orchestrator.js";
-export { executeSwarm } from "./orchestrator.js";
-export {
-  SwarmPlanValidationError,
-  validateAndNormalizePlan,
-} from "./plan-validator.js";
-export {
-  generatePlan,
-  makeFallbackPlan,
-  parsePlanJSON,
-} from "./router-planner.js";
-export { synthesizeResults } from "./synthesizer.js";
-export type {
-  SwarmExecutionSummary,
-  SwarmPlan,
-  SwarmRole,
-  SwarmTaskNode,
-  SwarmTaskResult,
-  SwarmTaskStatus,
-} from "./types.js";
-export { VALID_SWARM_ROLES } from "./types.js";
-export type {
-  ProfilePolicy,
-  SwarmWorkerBackend,
-  SwarmWorkerBackendInput,
-  SwarmWorkerBackendResult,
-  WorkerFailureReason,
-  WorkerProfile,
-} from "./worker-backend.js";
-export { getProfilePolicy, roleToProfile } from "./worker-backend.js";
-export { buildWorkerPrompt, parseWorkerOutput } from "./worker-prompts.js";
-export type {
-  RunWorkerTaskOptions,
-  WorkerStatusCallback,
-  WorkerStatusKind,
-} from "./worker-runner.js";
-export { runWorkerTask } from "./worker-runner.js";

package/src/swarm/limits.ts

@@ -1,66 +0,0 @@
-/**
- * Runtime limits for swarm execution, resolved from config.
- */
-
-import type { SwarmRole } from "./types.js";
-
-export interface SwarmLimits {
-  maxWorkers: number;
-  maxTasks: number;
-  maxRetriesPerTask: number;
-  workerTimeoutSec: number;
-  /** Per-role timeout overrides. When set, takes precedence over workerTimeoutSec for that role. */
-  roleTimeoutsSec: Partial<Record<SwarmRole, number>>;
-}
-
-/** Hard ceilings that config values are clamped to. */
-export const SWARM_HARD_LIMITS = {
-  maxWorkers: 6,
-  maxTasks: 20,
-  maxRetriesPerTask: 3,
-} as const;
-
-/**
- * Resolve effective limits from config, clamping to hard ceilings.
- */
-export function resolveSwarmLimits(config: {
-  maxWorkers: number;
-  maxTasks: number;
-  maxRetriesPerTask: number;
-  workerTimeoutSec: number;
-  roleTimeoutsSec?: Partial<Record<SwarmRole, number>>;
-}): SwarmLimits {
-  const resolvedRoleTimeouts: Partial<Record<SwarmRole, number>> = {};
-  if (config.roleTimeoutsSec) {
-    for (const [role, timeout] of Object.entries(config.roleTimeoutsSec)) {
-      if (timeout != null) {
-        resolvedRoleTimeouts[role as SwarmRole] = Math.max(1, timeout);
-      }
-    }
-  }
-
-  return {
-    maxWorkers: Math.min(
-      Math.max(1, config.maxWorkers),
-      SWARM_HARD_LIMITS.maxWorkers,
-    ),
-    maxTasks: Math.min(
-      Math.max(1, config.maxTasks),
-      SWARM_HARD_LIMITS.maxTasks,
-    ),
-    maxRetriesPerTask: Math.min(
-      Math.max(0, config.maxRetriesPerTask),
-      SWARM_HARD_LIMITS.maxRetriesPerTask,
-    ),
-    workerTimeoutSec: Math.max(1, config.workerTimeoutSec),
-    roleTimeoutsSec: resolvedRoleTimeouts,
-  };
-}
-
-/** Get the effective timeout for a given role, falling back to the global workerTimeoutSec. */
-export function getTimeoutForRole(
-  limits: SwarmLimits,
-  role: SwarmRole,
-): number {
-  return limits.roleTimeoutsSec[role] ?? limits.workerTimeoutSec;
-}

package/src/swarm/orchestrator.ts

@@ -1,424 +0,0 @@
-import type { ModelIntent, Provider } from "../providers/types.js";
-import { getLogger } from "../util/logger.js";
-import {
-  isCheckpointCompatible,
-  loadCheckpoint,
-  removeCheckpoint,
-  writeCheckpoint,
-} from "./checkpoint.js";
-import { detectCycles } from "./graph-utils.js";
-import type { SwarmLimits } from "./limits.js";
-import { getTimeoutForRole } from "./limits.js";
-import { synthesizeResults } from "./synthesizer.js";
-import type {
-  SwarmExecutionSummary,
-  SwarmPlan,
-  SwarmTaskNode,
-  SwarmTaskResult,
-} from "./types.js";
-import type { SwarmWorkerBackend } from "./worker-backend.js";
-import { runWorkerTask } from "./worker-runner.js";
-
-const log = getLogger("swarm-orchestrator");
-
-export type OrchestratorEventKind =
-  | "plan_created"
-  | "task_started"
-  | "task_completed"
-  | "task_failed"
-  | "task_blocked"
-  | "synthesis_started"
-  | "done";
-
-export interface OrchestratorEvent {
-  kind: OrchestratorEventKind;
-  taskId?: string;
-  message?: string;
-}
-
-export type OrchestratorStatusCallback = (event: OrchestratorEvent) => void;
-
-export interface ExecuteSwarmOptions {
-  plan: SwarmPlan;
-  limits: SwarmLimits;
-  backend: SwarmWorkerBackend;
-  workingDir: string;
-  modelIntent?: string;
-  /** Provider + model intent for final synthesis. */
-  synthesisProvider?: Provider;
-  synthesisModelIntent?: ModelIntent;
-  onStatus?: OrchestratorStatusCallback;
-  signal?: AbortSignal;
-  /** Stable identifier for this swarm run, used for checkpoint persistence. */
-  runId?: string;
-  /** When true, attempt to resume from the last checkpoint for this runId. */
-  resume?: boolean;
-}
-
-/**
- * Execute a validated swarm plan with parallel DAG scheduling,
- * bounded concurrency, and per-task retries.
- */
-export async function executeSwarm(
-  opts: ExecuteSwarmOptions,
-): Promise<SwarmExecutionSummary> {
-  const {
-    plan,
-    limits,
-    backend,
-    workingDir,
-    modelIntent,
-    onStatus,
-    signal,
-    runId,
-    resume,
-  } = opts;
-  const startTime = Date.now();
-
-  // Safety net: reject cyclic plans even if the caller skipped validation
-  const cycleNodes = detectCycles(plan.tasks);
-  if (cycleNodes) {
-    throw new Error(
-      `Swarm plan contains a dependency cycle: ${cycleNodes.join(" -> ")}`,
-    );
-  }
-
-  onStatus?.({
-    kind: "plan_created",
-    message: `Plan with ${plan.tasks.length} tasks`,
-  });
-
-  const results = new Map<string, SwarmTaskResult>();
-  const blocked = new Set<string>();
-
-  // Restore from checkpoint if resuming
-  if (runId && resume) {
-    const checkpoint = loadCheckpoint(runId);
-    if (checkpoint && isCheckpointCompatible(checkpoint, plan)) {
-      for (const result of checkpoint.results) {
-        results.set(result.taskId, result);
-      }
-      for (const taskId of checkpoint.blockedTaskIds) {
-        blocked.add(taskId);
-      }
-      const restored = checkpoint.results.length;
-      const restoredBlocked = checkpoint.blockedTaskIds.length;
-      log.info({ runId, restored, restoredBlocked }, "Resumed from checkpoint");
-      onStatus?.({
-        kind: "plan_created",
-        message: `Resumed ${restored} completed tasks from checkpoint`,
-      });
-    } else if (checkpoint) {
-      log.warn(
-        { runId },
-        "Checkpoint incompatible with current plan, starting fresh",
-      );
-    }
-  }
-
-  // Build adjacency for dependency tracking
-  const dependents = new Map<string, string[]>();
-  for (const task of plan.tasks) {
-    dependents.set(task.id, []);
-  }
-  for (const task of plan.tasks) {
-    for (const dep of task.dependencies) {
-      dependents.get(dep)?.push(task.id);
-    }
-  }
-
-  // Determine initial ready tasks — skip tasks already completed or blocked
-  // from a restored checkpoint
-  const ready: SwarmTaskNode[] = [];
-  const remaining = new Map<string, SwarmTaskNode>();
-  const pendingDeps = new Map<string, Set<string>>();
-
-  for (const task of plan.tasks) {
-    if (results.has(task.id) || blocked.has(task.id)) continue;
-    remaining.set(task.id, task);
-    // Remove already-completed dependencies from this task's pending set
-    const unresolvedDeps = task.dependencies.filter((d) => !results.has(d));
-    if (unresolvedDeps.length === 0) {
-      ready.push(task);
-    } else {
-      pendingDeps.set(task.id, new Set(unresolvedDeps));
-    }
-  }
-
-  // Concurrent DAG executor — schedule tasks as soon as their prerequisites
-  // finish, bounded by maxWorkers.  Unlike wave/batch execution, a newly
-  // unblocked task can start immediately when a worker slot opens up rather
-  // than waiting for the entire previous batch to complete.
-  let activeCount = 0;
-  let resolve: (() => void) | null = null;
-
-  // Resolves whenever a running task completes (or the ready queue is refilled)
-  // so the main loop can re-evaluate whether to launch more work.
-  function signalProgress(): void {
-    if (resolve) {
-      const r = resolve;
-      resolve = null;
-      r();
-    }
-  }
-
-  function waitForProgress(): Promise<void> {
-    return new Promise<void>((r) => {
-      resolve = r;
-    });
-  }
-
-  function processResult(result: SwarmTaskResult): void {
-    results.set(result.taskId, result);
-    remaining.delete(result.taskId);
-
-    if (result.status === "completed") {
-      onStatus?.({ kind: "task_completed", taskId: result.taskId });
-      // Immediately unblock dependents so they enter the ready queue
-      for (const depId of dependents.get(result.taskId) ?? []) {
-        const pending = pendingDeps.get(depId);
-        if (pending) {
-          pending.delete(result.taskId);
-          if (pending.size === 0) {
-            pendingDeps.delete(depId);
-            const task = plan.tasks.find((t) => t.id === depId);
-            if (task && !blocked.has(depId)) {
-              ready.push(task);
-            }
-          }
-        }
-      }
-    } else {
-      onStatus?.({ kind: "task_failed", taskId: result.taskId });
-      blockDependents(result.taskId, dependents, blocked, onStatus);
-    }
-
-    if (runId) {
-      writeCheckpoint(runId, plan, results, blocked);
-    }
-  }
-
-  async function runTask(task: SwarmTaskNode): Promise<void> {
-    onStatus?.({ kind: "task_started", taskId: task.id });
-
-    const depOutputs = task.dependencies
-      .map((depId) => {
-        const r = results.get(depId);
-        return r ? { taskId: depId, summary: r.summary } : null;
-      })
-      .filter((d): d is { taskId: string; summary: string } => d != null);
-
-    let result: SwarmTaskResult;
-    try {
-      const taskTimeoutMs = getTimeoutForRole(limits, task.role) * 1000;
-
-      result = await runWorkerTask({
-        task,
-        upstreamContext: plan.objective,
-        dependencyOutputs: depOutputs,
-        backend,
-        workingDir,
-        modelIntent,
-        timeoutMs: taskTimeoutMs,
-        signal,
-      });
-
-      let retries = 0;
-      while (
-        result.status === "failed" &&
-        retries < limits.maxRetriesPerTask &&
-        !signal?.aborted
-      ) {
-        retries++;
-        // Exponential backoff with ±25% jitter to prevent thundering herd
-        const baseDelayMs = 1000 * Math.pow(2, retries - 1);
-        const jitter = baseDelayMs * 0.25 * (2 * Math.random() - 1);
-        await abortableSleep(baseDelayMs + jitter, signal);
-        if (signal?.aborted) break;
-        result = await runWorkerTask({
-          task,
-          upstreamContext: plan.objective,
-          dependencyOutputs: depOutputs,
-          backend,
-          workingDir,
-          modelIntent,
-          timeoutMs: taskTimeoutMs,
-          signal,
-        });
-      }
-      result.retryCount = retries;
-
-      if (result.status === "failed") {
-        log.error(
-          { taskId: task.id, error: result.summary, retries },
-          "Swarm task execution failed",
-        );
-      }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      log.error(
-        { taskId: task.id, error: error.message, stack: error.stack },
-        "Swarm task execution failed unexpectedly",
-      );
-      result = {
-        taskId: task.id,
-        status: "failed",
-        summary: `Unexpected error: ${error.message}`,
-        artifacts: [],
-        issues: [error.message],
-        nextSteps: [],
-        rawOutput: "",
-        durationMs: 0,
-        retryCount: 0,
-      };
-    }
-
-    processResult(result);
-  }
-
-  while (ready.length > 0 || activeCount > 0) {
-    if (signal?.aborted) break;
-
-    // Launch as many ready tasks as worker slots allow
-    while (ready.length > 0 && activeCount < limits.maxWorkers) {
-      const task = ready.shift()!;
-      activeCount++;
-      // Fire-and-forget — completion is handled inside runTask.
-      // .finally() ensures activeCount is decremented exactly once
-      // regardless of where an error occurs (e.g. a throwing onStatus
-      // callback inside processResult). .catch() suppresses the
-      // unhandled rejection for fire-and-forget usage.
-      runTask(task)
-        .finally(() => {
-          activeCount--;
-          signalProgress();
-        })
-        .catch((err) => {
-          const error = err instanceof Error ? err : new Error(String(err));
-          log.error(
-            { taskId: task.id, error: error.message, stack: error.stack },
-            "Swarm task runner failed",
-          );
-        });
-    }
-
-    // Nothing left to launch and nothing running — we're done
-    if (activeCount === 0 && ready.length === 0) break;
-
-    // Wait until a running task completes (or a new task becomes ready)
-    await waitForProgress();
-  }
-
-  // Let in-flight workers settle before finalizing — if we broke out of the
-  // loop due to abort, workers may still be running and would otherwise emit
-  // events (task_completed / task_failed) after the 'done' event.
-  while (activeCount > 0) {
-    await waitForProgress();
-  }
-
-  // Mark any remaining tasks that were never reached as blocked
-  for (const [taskId] of remaining) {
-    if (!results.has(taskId) && !blocked.has(taskId)) {
-      blocked.add(taskId);
-      onStatus?.({ kind: "task_blocked", taskId });
-    }
-  }
-
-  // Synthesize final answer (skip LLM synthesis when aborted, but still
-  // build the markdown fallback so partial results are preserved)
-  const allResults = Array.from(results.values());
-
-  let finalAnswer: string;
-  if (opts.synthesisProvider && !signal?.aborted) {
-    onStatus?.({ kind: "synthesis_started" });
-    finalAnswer = await synthesizeResults({
-      objective: plan.objective,
-      results: allResults,
-      provider: opts.synthesisProvider,
-      modelIntent: opts.synthesisModelIntent ?? "quality-optimized",
-    });
-  } else {
-    if (!signal?.aborted) onStatus?.({ kind: "synthesis_started" });
-    finalAnswer = buildMarkdownFallback(plan.objective, allResults);
-  }
-
-  const totalDurationMs = Date.now() - startTime;
-
-  // Clean up checkpoint on successful completion (not on abort, so it can be resumed)
-  if (runId && !signal?.aborted) {
-    removeCheckpoint(runId);
-  }
-
-  onStatus?.({ kind: "done", message: `Completed in ${totalDurationMs}ms` });
-
-  return {
-    objective: plan.objective,
-    plan,
-    results: allResults,
-    finalAnswer,
-    stats: {
-      totalTasks: plan.tasks.length,
-      completed: allResults.filter((r) => r.status === "completed").length,
-      failed: allResults.filter((r) => r.status === "failed").length,
-      blocked: blocked.size,
-      totalDurationMs,
-    },
-  };
-}
-
-function blockDependents(
-  taskId: string,
-  dependents: Map<string, string[]>,
-  blocked: Set<string>,
-  onStatus?: OrchestratorStatusCallback,
-): void {
-  for (const depId of dependents.get(taskId) ?? []) {
-    if (!blocked.has(depId)) {
-      blocked.add(depId);
-      onStatus?.({ kind: "task_blocked", taskId: depId });
-      blockDependents(depId, dependents, blocked, onStatus);
-    }
-  }
-}
-
-/** Resolves after `ms` milliseconds, or immediately if the signal fires first. */
-function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) return Promise.resolve();
-  return new Promise<void>((resolve) => {
-    const timer = setTimeout(done, ms);
-    signal?.addEventListener("abort", done, { once: true });
-    function done() {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", done);
-      resolve();
-    }
-  });
-}
-
-function buildMarkdownFallback(
-  objective: string,
-  results: SwarmTaskResult[],
-): string {
-  const lines: string[] = [`## Swarm Results: ${objective}`, ""];
-
-  const completed = results.filter((r) => r.status === "completed");
-  const failed = results.filter((r) => r.status === "failed");
-
-  if (completed.length > 0) {
-    lines.push("### Completed Tasks");
-    for (const r of completed) {
-      lines.push(`- **${r.taskId}**: ${r.summary}`);
-    }
-    lines.push("");
-  }
-
-  if (failed.length > 0) {
-    lines.push("### Failed Tasks");
-    for (const r of failed) {
-      lines.push(`- **${r.taskId}**: ${r.summary}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}