@vellumai/assistant 0.5.6 → 0.5.7

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: [],
-      },
-    ],
-  };
-}

package/src/swarm/router-prompts.ts

@@ -1,39 +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,81 +0,0 @@
-import type { Message, ModelIntent, Provider } 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;
-  modelIntent?: ModelIntent;
-}): Promise<string> {
-  const { objective, results, provider, modelIntent } = opts;
-
-  // Cap individual summaries and total input to avoid blowing up context on large plans
-  const MAX_SUMMARY_CHARS = 500;
-  const MAX_TOTAL_CHARS = 12_000;
-
-  let taskSummaries = results
-    .map((r) => {
-      const status = r.status === "completed" ? "completed" : "FAILED";
-      const summary =
-        r.summary.length > MAX_SUMMARY_CHARS
-          ? r.summary.slice(0, MAX_SUMMARY_CHARS) + "..."
-          : r.summary;
-      return `[${r.taskId}] (${status}): ${summary}`;
-    })
-    .join("\n");
-
-  if (taskSummaries.length > MAX_TOTAL_CHARS) {
-    taskSummaries =
-      taskSummaries.slice(0, MAX_TOTAL_CHARS) + "\n... (truncated)";
-  }
-
-  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, modelIntent } },
-    );
-
-    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,72 +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,131 +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;
-  modelIntent?: 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 | Promise<boolean>;
-  /** Run a task with the given input. */
-  runTask(input: SwarmWorkerBackendInput): Promise<SwarmWorkerBackendResult>;
-}

package/src/swarm/worker-prompts.ts

@@ -1,80 +0,0 @@
-import { parseJsonSafe } from "../util/json.js";
-import { truncate } from "../util/truncate.js";
-import type { SwarmRole, SwarmTaskResult } from "./types.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--) {
-    const parsed = parseJsonSafe<Record<string, unknown>>(jsonBlocks[i][1]);
-    if (!parsed || 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 : [],
-    };
-  }
-
-  return {
-    summary: truncate(raw, 500, ""),
-    artifacts: [],
-    issues: [],
-    nextSteps: [],
-  };
-}