@vellumai/assistant 0.5.6 → 0.5.8

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");
-}

package/src/swarm/plan-validator.ts

@@ -1,117 +0,0 @@
-import { getLogger } from "../util/logger.js";
-import { detectCycles } from "./graph-utils.js";
-import type { SwarmLimits } from "./limits.js";
-import type { SwarmPlan, SwarmTaskNode } from "./types.js";
-import { VALID_SWARM_ROLES } from "./types.js";
-
-const log = getLogger("swarm:plan-validator");
-
-export class SwarmPlanValidationError extends Error {
-  constructor(
-    message: string,
-    public readonly issues: string[],
-  ) {
-    super(message);
-    this.name = "SwarmPlanValidationError";
-  }
-}
-
-/**
- * Validate and normalize a swarm plan. Returns the validated plan or throws
- * SwarmPlanValidationError with all detected issues.
- */
-export function validateAndNormalizePlan(
-  plan: SwarmPlan,
-  limits: SwarmLimits,
-): SwarmPlan {
-  const issues: string[] = [];
-
-  // --- Basic structure ---
-  if (!plan.objective || typeof plan.objective !== "string") {
-    issues.push("Plan must have a non-empty objective string.");
-  }
-  if (!Array.isArray(plan.tasks) || plan.tasks.length === 0) {
-    issues.push("Plan must have at least one task.");
-    throw new SwarmPlanValidationError("Plan validation failed", issues);
-  }
-
-  // --- Normalize dependencies early (before any checks that iterate them) ---
-  let tasks: SwarmTaskNode[] = plan.tasks.map((t) => ({
-    ...t,
-    dependencies: Array.isArray(t.dependencies) ? t.dependencies : [],
-  }));
-  const originalIds = new Set(tasks.map((task) => task.id));
-
-  // --- Task count limit ---
-  if (tasks.length > limits.maxTasks) {
-    log.warn(
-      { original: tasks.length, max: limits.maxTasks },
-      "Plan truncated to task limit",
-    );
-    tasks = tasks.slice(0, limits.maxTasks);
-  }
-
-  // --- Unique IDs ---
-  const ids = new Set<string>();
-  for (const task of tasks) {
-    if (!task.id || typeof task.id !== "string") {
-      issues.push(`Task has invalid or empty id.`);
-      continue;
-    }
-    if (ids.has(task.id)) {
-      issues.push(`Duplicate task id: "${task.id}".`);
-    }
-    ids.add(task.id);
-  }
-
-  // --- Valid roles ---
-  for (const task of tasks) {
-    if (!VALID_SWARM_ROLES.includes(task.role)) {
-      issues.push(
-        `Task "${task.id}" has invalid role "${
-          task.role
-        }". Valid roles: ${VALID_SWARM_ROLES.join(", ")}.`,
-      );
-    }
-  }
-
-  // --- Strip orphaned dependency references (from truncation) and report real errors ---
-  for (const task of tasks) {
-    const valid: string[] = [];
-    for (const dep of task.dependencies) {
-      if (!ids.has(dep)) {
-        if (!originalIds.has(dep)) {
-          issues.push(`Task "${task.id}" depends on unknown task "${dep}".`);
-        }
-      } else {
-        valid.push(dep);
-      }
-    }
-    task.dependencies = valid;
-  }
-
-  // --- Cycle detection (Kahn's algorithm) ---
-  if (!hasDuplicateIds(tasks) && issues.length === 0) {
-    const cycleNodes = detectCycles(tasks);
-    if (cycleNodes) {
-      issues.push(
-        `Plan contains a dependency cycle: ${cycleNodes.join(" -> ")}.`,
-      );
-    }
-  }
-
-  if (issues.length > 0) {
-    throw new SwarmPlanValidationError("Plan validation failed", issues);
-  }
-
-  return { ...plan, tasks };
-}
-
-function hasDuplicateIds(tasks: SwarmTaskNode[]): boolean {
-  const seen = new Set<string>();
-  for (const t of tasks) {
-    if (seen.has(t.id)) return true;
-    seen.add(t.id);
-  }
-  return false;
-}

package/src/swarm/router-planner.ts

@@ -1,162 +0,0 @@
-import type { Message, ModelIntent, Provider } from "../providers/types.js";
-import { parseJsonSafe } from "../util/json.js";
-import type { SwarmLimits } from "./limits.js";
-import { validateAndNormalizePlan } from "./plan-validator.js";
-import {
-  buildPlannerUserMessage,
-  ROUTER_SYSTEM_PROMPT,
-} from "./router-prompts.js";
-import type { SwarmPlan, SwarmTaskNode } from "./types.js";
-import { VALID_SWARM_ROLES } from "./types.js";
-
-/**
- * Generate a validated swarm plan from a user objective using an LLM.
- * Falls back to a single-coder plan if generation or validation fails.
- */
-export async function generatePlan(opts: {
-  objective: string;
-  provider: Provider;
-  modelIntent: ModelIntent;
-  limits: SwarmLimits;
-}): Promise<SwarmPlan> {
-  const { objective, provider, modelIntent, limits } = opts;
-
-  try {
-    const messages: Message[] = [
-      {
-        role: "user",
-        content: [
-          {
-            type: "text",
-            text: buildPlannerUserMessage(objective, limits.maxTasks),
-          },
-        ],
-      },
-    ];
-
-    const response = await provider.sendMessage(
-      messages,
-      undefined,
-      ROUTER_SYSTEM_PROMPT,
-      { config: { max_tokens: 2048, modelIntent } },
-    );
-
-    // Extract text from response
-    const textBlock = response.content.find((b) => b.type === "text");
-    if (!textBlock || textBlock.type !== "text") {
-      return makeFallbackPlan(objective);
-    }
-
-    const rawPlan = parsePlanJSON(textBlock.text);
-    if (!rawPlan) {
-      return makeFallbackPlan(objective);
-    }
-
-    const validatedTasks = validateRawTasks(rawPlan.tasks);
-    if (validatedTasks.length === 0) {
-      return makeFallbackPlan(objective);
-    }
-
-    const plan: SwarmPlan = {
-      objective,
-      tasks: validatedTasks,
-    };
-
-    return validateAndNormalizePlan(plan, limits);
-  } catch {
-    return makeFallbackPlan(objective);
-  }
-}
-
-/**
- * Parse the LLM output as a plan JSON. Handles bare JSON objects and
- * fenced code blocks (tries all fenced blocks, not just the first).
- */
-export function parsePlanJSON(raw: string): {
-  tasks: Array<{
-    id: string;
-    role: string;
-    objective: string;
-    dependencies: string[];
-  }>;
-} | null {
-  // Try all fenced code blocks — LLMs sometimes emit non-JSON blocks before the plan
-  const fencedRegex = /```(?:json)?\s*\n?([\s\S]*?)\n?```/g;
-  let match;
-  while ((match = fencedRegex.exec(raw)) != null) {
-    const result = tryParsePlan(match[1]);
-    if (result) return result;
-  }
-
-  // Fall back to parsing the raw string as bare JSON
-  return tryParsePlan(raw);
-}
-
-function tryParsePlan(jsonStr: string): {
-  tasks: Array<{
-    id: string;
-    role: string;
-    objective: string;
-    dependencies: string[];
-  }>;
-} | null {
-  const parsed = parseJsonSafe<{ tasks?: unknown }>(jsonStr.trim());
-  if (parsed && Array.isArray(parsed.tasks)) {
-    return parsed as {
-      tasks: Array<{
-        id: string;
-        role: string;
-        objective: string;
-        dependencies: string[];
-      }>;
-    };
-  }
-  return null;
-}
-
-/**
- * Validate that raw parsed task objects have the required fields and correct types
- * before treating them as SwarmTaskNode[]. Filters out malformed entries so a
- * partially valid LLM response can still produce a usable plan.
- */
-function validateRawTasks(raw: unknown[]): SwarmTaskNode[] {
-  const validRoles = new Set<string>(VALID_SWARM_ROLES);
-  const validated: SwarmTaskNode[] = [];
-
-  for (const item of raw) {
-    if (item == null || typeof item !== "object") continue;
-    const t = item as Record<string, unknown>;
-
-    if (typeof t.id !== "string" || t.id === "") continue;
-    if (typeof t.role !== "string" || !validRoles.has(t.role)) continue;
-    if (typeof t.objective !== "string" || t.objective === "") continue;
-
-    validated.push({
-      id: t.id,
-      role: t.role as SwarmTaskNode["role"],
-      objective: t.objective,
-      dependencies: Array.isArray(t.dependencies)
-        ? t.dependencies.filter((d): d is string => typeof d === "string")
-        : [],
-    });
-  }
-
-  return validated;
-}
-
-/**
- * Deterministic fallback: a single coder task for the full objective.
- */
-export function makeFallbackPlan(objective: string): SwarmPlan {
-  return {
-    objective,
-    tasks: [
-      {
-        id: "fallback-coder",
-        role: "coder",
-        objective,
-        dependencies: [],
-      },
-    ],
-  };
-}