vellum 0.2.14 → 0.3.2

package/src/swarm/plan-validator.ts

@@ -1,151 +0,0 @@
-import type { SwarmPlan, SwarmTaskNode } from './types.js';
-import { VALID_SWARM_ROLES } from './types.js';
-import type { SwarmLimits } from './limits.js';
-
-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 (silent truncation) ---
-  if (tasks.length > limits.maxTasks) {
-    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 cycleResult = detectCycles(tasks);
-    if (cycleResult) {
-      issues.push(`Plan contains a dependency cycle: ${cycleResult}.`);
-    }
-  }
-
-  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;
-}
-
-/**
- * Detect cycles using Kahn's algorithm. Returns a description of the cycle
- * if one exists, or null if the graph is acyclic.
- */
-function detectCycles(tasks: SwarmTaskNode[]): string | null {
-  const inDegree = new Map<string, number>();
-  const adj = new Map<string, string[]>();
-
-  for (const task of tasks) {
-    inDegree.set(task.id, 0);
-    adj.set(task.id, []);
-  }
-
-  for (const task of tasks) {
-    for (const dep of task.dependencies) {
-      adj.get(dep)!.push(task.id);
-      inDegree.set(task.id, (inDegree.get(task.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 node = queue.shift()!;
-    processed++;
-    for (const neighbor of adj.get(node)!) {
-      const newDeg = (inDegree.get(neighbor) ?? 0) - 1;
-      inDegree.set(neighbor, newDeg);
-      if (newDeg === 0) queue.push(neighbor);
-    }
-  }
-
-  if (processed < tasks.length) {
-    const stuck = tasks
-      .filter((t) => (inDegree.get(t.id) ?? 0) > 0)
-      .map((t) => t.id);
-    return stuck.join(' -> ');
-  }
-
-  return null;
-}

package/src/swarm/router-planner.ts

@@ -1,100 +0,0 @@
-import type { Provider, Message } from '../providers/types.js';
-import type { SwarmPlan, SwarmTaskNode } from './types.js';
-import type { SwarmLimits } from './limits.js';
-import { validateAndNormalizePlan } from './plan-validator.js';
-import { ROUTER_SYSTEM_PROMPT, buildPlannerUserMessage } from './router-prompts.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;
-  model: string;
-  limits: SwarmLimits;
-}): Promise<SwarmPlan> {
-  const { objective, provider, model, 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, model } },
-    );
-
-    // 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 plan: SwarmPlan = {
-      objective,
-      tasks: rawPlan.tasks as SwarmTaskNode[],
-    };
-
-    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 {
-  try {
-    const parsed = JSON.parse(jsonStr.trim());
-    if (parsed && Array.isArray(parsed.tasks)) {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 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: [],
-      },
-    ],
-  };
-}

package/src/swarm/router-prompts.ts

@@ -1,36 +0,0 @@
-/**
- * System prompt for the router planner LLM call.
- */
-export const ROUTER_SYSTEM_PROMPT = `You are a task decomposition planner. Given a user objective, break it down into a set of parallel and sequential tasks that can be executed by specialist workers.
-
-Available worker roles:
-- researcher: Can search the web, read files, and gather information. Cannot write or edit files.
-- coder: Can read, write, and edit files, run shell commands, and implement code changes.
-- reviewer: Can read and search files to review code. Cannot write or edit files.
-
-Rules:
-1. Output ONLY a valid JSON object. No prose, no markdown, no explanation.
-2. Each task must have a unique "id" (short slug), a "role", an "objective" (clear instruction), and "dependencies" (array of task IDs that must complete first).
-3. Maximize parallelism: only add a dependency if the task truly needs output from another.
-4. Keep the plan minimal — avoid unnecessary tasks. Prefer fewer, well-scoped tasks.
-5. Do not create tasks for the "router" role.
-6. The total number of tasks must not exceed the provided limit.
-
-Output schema:
-{
-  "tasks": [
-    {
-      "id": "string",
-      "role": "researcher" | "coder" | "reviewer",
-      "objective": "string",
-      "dependencies": ["task-id", ...]
-    }
-  ]
-}`;
-
-/**
- * Build the user message for the router planner.
- */
-export function buildPlannerUserMessage(objective: string, maxTasks: number): string {
-  return `Objective: ${objective}\n\nMaximum tasks allowed: ${maxTasks}\n\nReturn ONLY the JSON plan.`;
-}

package/src/swarm/synthesizer.ts

@@ -1,62 +0,0 @@
-import type { Provider, Message } from '../providers/types.js';
-import type { SwarmTaskResult } from './types.js';
-
-/**
- * Synthesize a final answer from all worker results using an LLM.
- * Falls back to a deterministic markdown summary if the LLM call fails.
- */
-export async function synthesizeResults(opts: {
-  objective: string;
-  results: SwarmTaskResult[];
-  provider: Provider;
-  model: string;
-}): Promise<string> {
-  const { objective, results, provider, model } = opts;
-
-  const taskSummaries = results.map((r) => {
-    const status = r.status === 'completed' ? 'completed' : 'FAILED';
-    return `[${r.taskId}] (${status}): ${r.summary}`;
-  }).join('\n');
-
-  const systemPrompt = 'You are a synthesis assistant. Combine the outputs from multiple specialist workers into a coherent, concise final answer. Focus on the user\'s original objective.';
-
-  const userMessage = `Original objective: ${objective}
-
-Worker results:
-${taskSummaries}
-
-Synthesize these results into a clear, complete answer for the user.`;
-
-  try {
-    const messages: Message[] = [
-      { role: 'user', content: [{ type: 'text', text: userMessage }] },
-    ];
-
-    const response = await provider.sendMessage(
-      messages,
-      undefined,
-      systemPrompt,
-      { config: { max_tokens: 4096, model } },
-    );
-
-    const textBlock = response.content.find((b) => b.type === 'text');
-    if (textBlock && textBlock.type === 'text') {
-      return textBlock.text;
-    }
-
-    return buildFallbackSynthesis(objective, results);
-  } catch {
-    return buildFallbackSynthesis(objective, results);
-  }
-}
-
-function buildFallbackSynthesis(objective: string, results: SwarmTaskResult[]): string {
-  const lines: string[] = [`## Results: ${objective}`, ''];
-
-  for (const r of results) {
-    const icon = r.status === 'completed' ? 'OK' : 'FAIL';
-    lines.push(`- [${icon}] **${r.taskId}**: ${r.summary}`);
-  }
-
-  return lines.join('\n');
-}

package/src/swarm/types.ts

@@ -1,62 +0,0 @@
-/**
- * Swarm runtime types for multi-worker task orchestration.
- */
-
-export type SwarmRole = 'router' | 'researcher' | 'coder' | 'reviewer';
-
-export const VALID_SWARM_ROLES: readonly SwarmRole[] = ['router', 'researcher', 'coder', 'reviewer'] as const;
-
-export interface SwarmTaskNode {
-  /** Unique identifier within the plan. */
-  id: string;
-  /** Role that will execute this task. */
-  role: SwarmRole;
-  /** Human-readable objective for the worker. */
-  objective: string;
-  /** IDs of tasks that must complete before this one can start. */
-  dependencies: string[];
-}
-
-export interface SwarmPlan {
-  /** Top-level objective that was decomposed into tasks. */
-  objective: string;
-  /** Ordered list of tasks forming a DAG. */
-  tasks: SwarmTaskNode[];
-}
-
-export type SwarmTaskStatus = 'queued' | 'running' | 'completed' | 'failed' | 'blocked';
-
-export interface SwarmTaskResult {
-  taskId: string;
-  status: 'completed' | 'failed';
-  /** Structured summary from the worker. */
-  summary: string;
-  /** Artifacts produced (file paths, code snippets, etc.). */
-  artifacts: string[];
-  /** Issues encountered during execution. */
-  issues: string[];
-  /** Suggested follow-up steps. */
-  nextSteps: string[];
-  /** Raw unprocessed output from the worker backend. */
-  rawOutput: string;
-  /** Wall-clock duration in milliseconds. */
-  durationMs: number;
-  /** Number of retry attempts before final result. */
-  retryCount: number;
-}
-
-export interface SwarmExecutionSummary {
-  objective: string;
-  plan: SwarmPlan;
-  results: SwarmTaskResult[];
-  /** Synthesized final answer combining all worker outputs. */
-  finalAnswer: string;
-  /** Aggregate stats. */
-  stats: {
-    totalTasks: number;
-    completed: number;
-    failed: number;
-    blocked: number;
-    totalDurationMs: number;
-  };
-}

package/src/swarm/worker-backend.ts

@@ -1,121 +0,0 @@
-import type { SwarmRole } from './types.js';
-
-/**
- * Profile names that scope tool access for worker tasks.
- */
-export type WorkerProfile = 'general' | 'researcher' | 'coder' | 'reviewer';
-
-/**
- * Maps swarm roles to worker profiles.
- */
-export function roleToProfile(role: SwarmRole): WorkerProfile {
-  switch (role) {
-    case 'researcher': return 'researcher';
-    case 'coder': return 'coder';
-    case 'reviewer': return 'reviewer';
-    case 'router': return 'general';
-    default: return 'general';
-  }
-}
-
-/**
- * Per-profile tool access policy. The sets are checked in order:
- * 1. If tool is in `deny`, block unconditionally.
- * 2. If tool is in `allow`, auto-approve.
- * 3. If tool is in `approvalRequired`, prompt user.
- * 4. Otherwise follow default approval flow.
- */
-export interface ProfilePolicy {
-  allow: Set<string>;
-  deny: Set<string>;
-  approvalRequired: Set<string>;
-}
-
-const READ_ONLY_TOOLS = new Set([
-  'Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'LS',
-  'Bash(grep *)', 'Bash(rg *)', 'Bash(find *)',
-]);
-
-const WRITE_TOOLS = new Set([
-  'Edit', 'Write', 'MultiEdit', 'NotebookEdit',
-]);
-
-/**
- * Return the tool access policy for a given profile.
- */
-export function getProfilePolicy(profile: WorkerProfile): ProfilePolicy {
-  switch (profile) {
-    case 'general':
-      return {
-        allow: new Set(READ_ONLY_TOOLS),
-        deny: new Set(),
-        approvalRequired: new Set(['Bash', ...WRITE_TOOLS]),
-      };
-
-    case 'researcher':
-      return {
-        allow: new Set(READ_ONLY_TOOLS),
-        deny: new Set([...WRITE_TOOLS, 'Bash']),
-        approvalRequired: new Set(),
-      };
-
-    case 'coder':
-      return {
-        allow: new Set(READ_ONLY_TOOLS),
-        deny: new Set(),
-        approvalRequired: new Set(['Bash', ...WRITE_TOOLS]),
-      };
-
-    case 'reviewer':
-      return {
-        allow: new Set(READ_ONLY_TOOLS),
-        deny: new Set([...WRITE_TOOLS, 'Bash']),
-        approvalRequired: new Set(),
-      };
-
-    default:
-      return {
-        allow: new Set(READ_ONLY_TOOLS),
-        deny: new Set(),
-        approvalRequired: new Set(['Bash', ...WRITE_TOOLS]),
-      };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Worker Backend
-// ---------------------------------------------------------------------------
-
-export type WorkerFailureReason =
-  | 'backend_unavailable'
-  | 'timeout'
-  | 'cancelled'
-  | 'malformed_output'
-  | 'tool_denied';
-
-export interface SwarmWorkerBackendResult {
-  success: boolean;
-  output: string;
-  failureReason?: WorkerFailureReason;
-  durationMs: number;
-}
-
-export interface SwarmWorkerBackendInput {
-  prompt: string;
-  profile: WorkerProfile;
-  workingDir: string;
-  model?: string;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-}
-
-/**
- * Abstraction over execution backends for swarm workers.
- */
-export interface SwarmWorkerBackend {
-  readonly name: string;
-  /** Check whether the backend is available (e.g. API key present). */
-  isAvailable(): boolean;
-  /** Run a task with the given input. */
-  runTask(input: SwarmWorkerBackendInput): Promise<SwarmWorkerBackendResult>;
-}

package/src/swarm/worker-prompts.ts

@@ -1,79 +0,0 @@
-import type { SwarmRole, SwarmTaskResult } from './types.js';
-import { truncate } from '../util/truncate.js';
-
-/**
- * Build a role-specific worker prompt for a swarm task.
- */
-export function buildWorkerPrompt(opts: {
-  role: SwarmRole;
-  objective: string;
-  upstreamContext?: string;
-  dependencyOutputs?: Array<{ taskId: string; summary: string }>;
-}): string {
-  const parts: string[] = [];
-
-  parts.push(`You are a ${opts.role} worker in a swarm. Your objective:\n${opts.objective}`);
-
-  if (opts.upstreamContext) {
-    parts.push(`\nContext from the orchestrator:\n${opts.upstreamContext}`);
-  }
-
-  if (opts.dependencyOutputs && opts.dependencyOutputs.length > 0) {
-    parts.push('\nOutputs from prerequisite tasks:');
-    for (const dep of opts.dependencyOutputs) {
-      parts.push(`- [${dep.taskId}]: ${dep.summary}`);
-    }
-  }
-
-  parts.push(WORKER_OUTPUT_CONTRACT);
-
-  return parts.join('\n');
-}
-
-const WORKER_OUTPUT_CONTRACT = `
-
-When you are finished, output your result as a single fenced JSON block:
-
-\`\`\`json
-{
-  "summary": "Brief summary of what you accomplished",
-  "artifacts": ["list of file paths, code snippets, or other outputs"],
-  "issues": ["list of problems encountered, if any"],
-  "nextSteps": ["suggested follow-up actions, if any"]
-}
-\`\`\`
-
-If you cannot produce valid JSON, just write a plain-text summary.`;
-
-/**
- * Parse the worker's raw output into a structured result shape.
- * Scans fenced JSON blocks from last to first, picking the last one that
- * matches the worker-result contract (has a `summary` string field).
- * Falls back to treating the entire output as a plain-text summary.
- */
-export function parseWorkerOutput(raw: string): Pick<SwarmTaskResult, 'summary' | 'artifacts' | 'issues' | 'nextSteps'> {
-  const jsonBlocks = Array.from(raw.matchAll(/```json\s*\n([\s\S]*?)\n```/g));
-
-  // Walk backwards to prefer the final valid contract block.
-  for (let i = jsonBlocks.length - 1; i >= 0; i--) {
-    try {
-      const parsed = JSON.parse(jsonBlocks[i][1]);
-      if (typeof parsed.summary !== 'string') continue;
-      return {
-        summary: parsed.summary,
-        artifacts: Array.isArray(parsed.artifacts) ? parsed.artifacts : [],
-        issues: Array.isArray(parsed.issues) ? parsed.issues : [],
-        nextSteps: Array.isArray(parsed.nextSteps) ? parsed.nextSteps : [],
-      };
-    } catch {
-      // Malformed JSON — try the next block up.
-    }
-  }
-
-  return {
-    summary: truncate(raw, 500, ''),
-    artifacts: [],
-    issues: [],
-    nextSteps: [],
-  };
-}