@vellumai/assistant 0.5.6 → 0.5.8

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

package/src/swarm/worker-runner.ts

@@ -1,170 +0,0 @@
-import type { SwarmTaskNode, SwarmTaskResult } from "./types.js";
-import type { SwarmWorkerBackend } from "./worker-backend.js";
-import { roleToProfile } from "./worker-backend.js";
-import { buildWorkerPrompt, parseWorkerOutput } from "./worker-prompts.js";
-
-export type WorkerStatusKind = "queued" | "running" | "completed" | "failed";
-
-export type WorkerStatusCallback = (
-  taskId: string,
-  status: WorkerStatusKind,
-) => void;
-
-export interface RunWorkerTaskOptions {
-  task: SwarmTaskNode;
-  /** Top-level objective context passed from the orchestrator. */
-  upstreamContext?: string;
-  /** Summaries from completed dependency tasks. */
-  dependencyOutputs?: Array<{ taskId: string; summary: string }>;
-  backend: SwarmWorkerBackend;
-  workingDir: string;
-  modelIntent?: string;
-  timeoutMs: number;
-  onStatus?: WorkerStatusCallback;
-  signal?: AbortSignal;
-}
-
-function emitStatus(
-  onStatus: WorkerStatusCallback | undefined,
-  taskId: string,
-  status: WorkerStatusKind,
-): void {
-  if (!onStatus) return;
-  try {
-    onStatus(taskId, status);
-  } catch {
-    // Observer failures must not abort worker execution.
-  }
-}
-
-/**
- * Execute a single swarm worker task through the given backend.
- * Returns a normalized SwarmTaskResult regardless of success or failure.
- */
-export async function runWorkerTask(
-  opts: RunWorkerTaskOptions,
-): Promise<SwarmTaskResult> {
-  const { task, backend, workingDir, timeoutMs, onStatus, signal } = opts;
-
-  if (signal?.aborted) {
-    return {
-      taskId: task.id,
-      status: "failed",
-      summary: "Cancelled",
-      artifacts: [],
-      issues: ["aborted"],
-      nextSteps: [],
-      rawOutput: "",
-      durationMs: 0,
-      retryCount: 0,
-    };
-  }
-
-  emitStatus(onStatus, task.id, "queued");
-
-  // Check backend availability
-  if (!(await backend.isAvailable())) {
-    emitStatus(onStatus, task.id, "failed");
-    return {
-      taskId: task.id,
-      status: "failed",
-      summary: `Backend "${backend.name}" is not available. Check API key and SDK configuration.`,
-      artifacts: [],
-      issues: [`Backend "${backend.name}" unavailable`],
-      nextSteps: ["Configure the backend or use a different one"],
-      rawOutput: "",
-      durationMs: 0,
-      retryCount: 0,
-    };
-  }
-
-  emitStatus(onStatus, task.id, "running");
-
-  const prompt = buildWorkerPrompt({
-    role: task.role,
-    objective: task.objective,
-    upstreamContext: opts.upstreamContext,
-    dependencyOutputs: opts.dependencyOutputs,
-  });
-
-  const profile = roleToProfile(task.role);
-
-  try {
-    const backendPromise = backend.runTask({
-      prompt,
-      profile,
-      workingDir,
-      modelIntent: opts.modelIntent,
-      timeoutMs,
-      signal,
-    });
-
-    // Enforce timeout via Promise.race
-    const timeoutPromise = new Promise<"timeout">((resolve) => {
-      const timer = setTimeout(() => resolve("timeout"), timeoutMs);
-      // Don't keep the process alive just for this timer
-      if (typeof timer === "object" && "unref" in timer) timer.unref();
-    });
-
-    const raceResult = await Promise.race([backendPromise, timeoutPromise]);
-
-    if (raceResult === "timeout") {
-      emitStatus(onStatus, task.id, "failed");
-      return {
-        taskId: task.id,
-        status: "failed",
-        summary: `Worker timed out after ${timeoutMs}ms`,
-        artifacts: [],
-        issues: ["timeout"],
-        nextSteps: [],
-        rawOutput: "",
-        durationMs: timeoutMs,
-        retryCount: 0,
-      };
-    }
-
-    const result = raceResult;
-
-    if (result.success) {
-      const parsed = parseWorkerOutput(result.output);
-      emitStatus(onStatus, task.id, "completed");
-      return {
-        taskId: task.id,
-        status: "completed",
-        ...parsed,
-        rawOutput: result.output,
-        durationMs: result.durationMs,
-        retryCount: 0,
-      };
-    }
-
-    // Backend returned a failure
-    emitStatus(onStatus, task.id, "failed");
-    return {
-      taskId: task.id,
-      status: "failed",
-      summary:
-        result.output || `Task failed: ${result.failureReason ?? "unknown"}`,
-      artifacts: [],
-      issues: [result.failureReason ?? "unknown_failure"],
-      nextSteps: [],
-      rawOutput: result.output,
-      durationMs: result.durationMs,
-      retryCount: 0,
-    };
-  } catch (err) {
-    emitStatus(onStatus, task.id, "failed");
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      taskId: task.id,
-      status: "failed",
-      summary: `Unexpected error: ${message}`,
-      artifacts: [],
-      issues: [message],
-      nextSteps: [],
-      rawOutput: "",
-      durationMs: 0,
-      retryCount: 0,
-    };
-  }
-}