@vellumai/assistant 0.3.0

package/src/swarm/worker-runner.ts

@@ -0,0 +1,164 @@
+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;
+  model?: 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 (!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,
+      model: opts.model,
+      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,
+    };
+  }
+}

package/src/tasks/SPEC.md

@@ -0,0 +1,139 @@
+# One-Shot Tasks — Design Spec
+
+One-shot tasks are user-defined, reusable prompt templates that run as
+self-contained LLM invocations. A user creates a task once (template + input
+schema), then triggers it with concrete inputs whenever needed. Each run
+produces a result in an isolated background thread.
+
+---
+
+## 1. Template Format (v1)
+
+A task definition consists of two parts:
+
+### Prompt template
+
+A plain-text string with `{{placeholder}}` markers. When a task is run, every
+placeholder is replaced with the corresponding user-supplied value, and the
+resulting string is sent to the LLM as the user message.
+
+```
+Summarize the following meeting notes in {{style}} format:
+
+{{notes}}
+```
+
+Placeholder names must match `[a-zA-Z_][a-zA-Z0-9_]*`.
+
+### Input schema
+
+A JSON Schema object that describes every placeholder variable — its type,
+description, and any validation constraints. This serves double duty: it
+drives input validation before the run starts, and it provides enough metadata
+for a UI to render an input form automatically.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "style": {
+      "type": "string",
+      "enum": ["bullet", "narrative", "executive"],
+      "description": "Output format for the summary"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Raw meeting transcript or notes"
+    }
+  },
+  "required": ["style", "notes"]
+}
+```
+
+**Why this design:** A single text template is the simplest possible v1 — no
+multi-message choreography, no branching, no tool-use orchestration. It covers
+the most common use case (structured prompt with variable inputs) while leaving
+room to extend later (e.g., multi-step chains, tool-enabled tasks).
+
+---
+
+## 2. Memory Isolation Policy
+
+Each task's memory is scoped by its task ID:
+
+```
+scope_id = "task:{task_id}"
+```
+
+This means:
+
+- **Cross-run learning**: All runs of the same task share the same memory
+  scope. The LLM can accumulate knowledge about the task across invocations
+  (e.g., learning the user's preferred summary style over time).
+- **Isolation from default scope**: Task memory is completely separate from the
+  user's main conversation memory (`scope_id = "default"`). A task cannot read
+  or pollute the user's chat history, and vice versa.
+- **Per-task boundaries**: Different tasks have different scopes and cannot see
+  each other's memory.
+
+This mirrors the existing `private:{id}` scoping pattern used by private
+threads (see `conversation-store.ts`), extended to a new `task:` namespace.
+
+---
+
+## 3. Run Surface
+
+Each task run creates a new conversation thread with `threadType: 'background'`.
+
+### Lifecycle
+
+1. **Preflight**: The client requests a permission preflight for the work item.
+   The daemon classifies risk for each required tool and returns the permission
+   set. The client displays an approval dialog; approved tools are stored on
+   the work item.
+2. **Start**: The daemon creates a `background` conversation, substitutes
+   template placeholders, sets up ephemeral permission rules for the approved
+   tools, and processes the rendered prompt through a daemon `Session`. Status
+   updates are broadcast to all connected clients via `work_item_status_changed`
+   and `tasks_changed` IPC messages.
+3. **Completion**: When the session finishes, the work item transitions to
+   `awaiting_review` (on success) or `failed` (on error). The daemon broadcasts
+   the final status to all clients.
+4. **Visibility**: Background conversations are excluded from the default thread
+   list (existing behavior in `conversation-store.ts`). Clients can query for
+   them explicitly to surface task results in a dedicated UI.
+
+**Why background conversations:** Reuses the existing `threadType: 'background'`
+infrastructure. Task runs don't interrupt the user's current conversation, and
+clients can choose how and when to display results (toast, panel, separate
+tab).
+
+---
+
+## 4. Safety Invariants
+
+- **Explicit trigger required**: Task runs are triggered either by an explicit
+  user action (UI button press, API call) or by a user-configured schedule
+  (`run_task:<task_id>` via the scheduler).
+- **Ephemeral permission bundles**: If a task is configured with tool access,
+  the permission grants are scoped to the single run and discarded afterward.
+  No persistent allowlist entries are created on behalf of a task.
+- **High-risk tools require upfront approval**: Tools classified as
+  `RiskLevel.High` (destructive shell commands, private-network fetches, etc.)
+  are surfaced in the preflight dialog so the user can explicitly approve or
+  deny them before execution begins. During the run itself, approved tools
+  (including high-risk ones) execute without further prompting.
+
+---
+
+## 5. Implementation Notes
+
+The implementation is complete. Key modules:
+
+| Module | What it delivers |
+|--------|------------------|
+| `task-store.ts` | `tasks` and `task_runs` tables, CRUD functions. |
+| `task-runner.ts` | `runTask()` — creates background conversation, renders template, processes through daemon Session. |
+| `ephemeral-permissions.ts` | Scoped permission rules for the duration of a single task run. |
+| `work-items.ts` (daemon handler) | IPC handlers for preflight, run, cancel, and status queries. |
+| Bundled skill (`tasks/`) | Tool definitions (`task_save`, `task_run`, `task_list`, `task_delete`, `task_list_*`) for the LLM. |

package/src/tasks/candidate-store.ts

@@ -0,0 +1,86 @@
+import { eq, desc, isNull } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { taskCandidates } from '../memory/schema.js';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface TaskCandidate {
+  id: string;
+  sourceConversationId: string;
+  compiledTemplate: string;
+  confidence: number | null;
+  requiredTools: string[] | null;
+  createdAt: number;
+  promotedTaskId: string | null;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/** Convert a raw DB row to a TaskCandidate, deserializing the JSON requiredTools field. */
+function rowToCandidate(row: typeof taskCandidates.$inferSelect): TaskCandidate {
+  return {
+    id: row.id,
+    sourceConversationId: row.sourceConversationId,
+    compiledTemplate: row.compiledTemplate,
+    confidence: row.confidence,
+    requiredTools: row.requiredTools ? JSON.parse(row.requiredTools) : null,
+    createdAt: row.createdAt,
+    promotedTaskId: row.promotedTaskId,
+  };
+}
+
+// ── CRUD ─────────────────────────────────────────────────────────────
+
+/** Record a new task candidate from a conversation. */
+export function createCandidate(opts: {
+  sourceConversationId: string;
+  compiledTemplate: string;
+  confidence?: number;
+  requiredTools?: string[];
+}): TaskCandidate {
+  const db = getDb();
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  const row = {
+    id,
+    sourceConversationId: opts.sourceConversationId,
+    compiledTemplate: opts.compiledTemplate,
+    confidence: opts.confidence ?? null,
+    requiredTools: opts.requiredTools ? JSON.stringify(opts.requiredTools) : null,
+    createdAt: now,
+    promotedTaskId: null,
+  };
+  db.insert(taskCandidates).values(row).run();
+  return {
+    ...row,
+    requiredTools: opts.requiredTools ?? null,
+  };
+}
+
+/** List unpromoted candidates (most recent first). */
+export function listUnpromotedCandidates(limit?: number): TaskCandidate[] {
+  const db = getDb();
+  const query = db
+    .select()
+    .from(taskCandidates)
+    .where(isNull(taskCandidates.promotedTaskId))
+    .orderBy(desc(taskCandidates.createdAt));
+  const rows = limit ? query.limit(limit).all() : query.all();
+  return rows.map(rowToCandidate);
+}
+
+/** Mark a candidate as promoted to a real task. */
+export function promoteCandidate(candidateId: string, taskId: string): void {
+  const db = getDb();
+  db.update(taskCandidates)
+    .set({ promotedTaskId: taskId })
+    .where(eq(taskCandidates.id, candidateId))
+    .run();
+}
+
+/** Get a candidate by ID. */
+export function getCandidate(id: string): TaskCandidate | undefined {
+  const db = getDb();
+  const row = db.select().from(taskCandidates).where(eq(taskCandidates.id, id)).get();
+  return row ? rowToCandidate(row) : undefined;
+}

package/src/tasks/ephemeral-permissions.ts

@@ -0,0 +1,48 @@
+import type { TrustRule } from '../permissions/types.js';
+
+// In-memory map: task_run_id -> ephemeral rules
+const activeTaskRules = new Map<string, TrustRule[]>();
+
+/** Register ephemeral permission rules for a task run. */
+export function setTaskRunRules(taskRunId: string, rules: TrustRule[]): void {
+  activeTaskRules.set(taskRunId, rules);
+}
+
+/** Get ephemeral rules for a task run (returns empty array if none). */
+export function getTaskRunRules(taskRunId: string): TrustRule[] {
+  return activeTaskRules.get(taskRunId) ?? [];
+}
+
+/** Remove ephemeral rules when a task run ends. */
+export function clearTaskRunRules(taskRunId: string): void {
+  activeTaskRules.delete(taskRunId);
+}
+
+/**
+ * Build ephemeral TrustRule entries from a task's required_tools list.
+ *
+ * Each rule allows the specified tool with a wildcard pattern scoped
+ * globally ('everywhere'). The scope is intentionally broad because the
+ * session's workingDir (sandbox path like ~/.vellum/workspace) differs
+ * from process.cwd() — using a directory-scoped rule would fail
+ * matchesScope() and silently miss. Priority is set to 75 — above
+ * default rules (50) so pre-approved tools aren't shadowed by default
+ * `ask` rules (which would trigger prompting and auto-deny in
+ * non-interactive task runs), but below user rules (100) so user deny
+ * rules still take precedence. `allowHighRisk` is set because task runs
+ * execute asynchronously without interactive confirmation — the client
+ * pre-approves tools via the preflight flow before execution begins,
+ * so there is no interactive prompt during the run itself.
+ */
+export function buildTaskRules(taskRunId: string, requiredTools: string[], _workingDir: string): TrustRule[] {
+  return requiredTools.map((tool) => ({
+    id: `ephemeral:${taskRunId}:${tool}`,
+    tool,
+    pattern: '**',
+    scope: 'everywhere',
+    decision: 'allow' as const,
+    allowHighRisk: true,
+    priority: 75,
+    createdAt: Date.now(),
+  }));
+}

package/src/tasks/task-compiler.ts

@@ -0,0 +1,199 @@
+import { eq } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { messages as messagesTable } from '../memory/schema.js';
+import { createTask } from './task-store.js';
+import type { Task } from './task-store.js';
+import { truncate } from '../util/truncate.js';
+import { sanitizeToolList } from './tool-sanitizer.js';
+
+/** Output schema for the task compiler. */
+export interface CompiledTask {
+  title: string;
+  template: string;
+  inputSchema: Record<string, unknown> | null;
+  contextFlags: string[];
+  requiredTools: string[];
+}
+
+/**
+ * Extract a task template (reusable definition) from a conversation's message history.
+ *
+ * Pattern-based extraction (v1) that:
+ * 1. Reads the conversation messages
+ * 2. Identifies the user's original request (first user message)
+ * 3. Identifies which tools were used (from assistant tool_use messages)
+ * 4. Builds a template from the original request
+ * 5. Extracts likely input variables (file paths, URLs, quoted strings)
+ */
+export function compileTaskFromConversation(conversationId: string): CompiledTask {
+  const db = getDb();
+  const msgs = db
+    .select()
+    .from(messagesTable)
+    .where(eq(messagesTable.conversationId, conversationId))
+    .all();
+
+  if (msgs.length === 0) {
+    throw new Error(`No messages found for conversation: ${conversationId}`);
+  }
+
+  // Find the first user message to use as the template basis
+  const firstUserMsg = msgs.find((m) => m.role === 'user');
+  if (!firstUserMsg) {
+    throw new Error(`No user messages found in conversation: ${conversationId}`);
+  }
+
+  // Extract user message text content
+  const userText = extractTextContent(firstUserMsg.content);
+
+  // Extract unique tool names from assistant messages.
+  const requiredTools = sanitizeToolList(extractToolNames(msgs));
+
+  // Build template with placeholder substitutions
+  const { template, properties } = buildTemplate(userText);
+
+  // Build JSON Schema for extracted placeholders
+  const inputSchema =
+    Object.keys(properties).length > 0
+      ? { type: 'object' as const, properties }
+      : null;
+
+  // Derive title from the first user message (truncated to 60 chars)
+  const title = deriveTitle(userText);
+
+  return {
+    title,
+    template,
+    inputSchema,
+    contextFlags: [],
+    requiredTools,
+  };
+}
+
+/**
+ * Save a compiled task to the database.
+ */
+export function saveCompiledTask(compiled: CompiledTask, conversationId: string): Task {
+  return createTask({
+    title: compiled.title,
+    template: compiled.template,
+    inputSchema: compiled.inputSchema ?? undefined,
+    contextFlags: compiled.contextFlags,
+    requiredTools: compiled.requiredTools,
+    createdFromConversationId: conversationId,
+  });
+}
+
+// ── Internal helpers ────────────────────────────────────────────────
+
+/**
+ * Extract plain text from a message content field. Content may be a plain
+ * string or a JSON array of Anthropic content blocks.
+ */
+function extractTextContent(content: string): string {
+  try {
+    const parsed = JSON.parse(content);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter((block: Record<string, unknown>) => block.type === 'text')
+        .map((block: Record<string, unknown>) => block.text as string)
+        .join('\n');
+    }
+    // If it parsed but isn't an array, treat as plain text
+    return content;
+  } catch {
+    // Not JSON — it's a plain text message
+    return content;
+  }
+}
+
+/**
+ * Extract unique tool names from assistant messages that contain tool_use blocks.
+ */
+function extractToolNames(
+  msgs: { role: string; content: string }[],
+): string[] {
+  const tools = new Set<string>();
+
+  for (const msg of msgs) {
+    if (msg.role !== 'assistant') continue;
+
+    try {
+      const parsed = JSON.parse(msg.content);
+      if (!Array.isArray(parsed)) continue;
+
+      for (const block of parsed) {
+        if (
+          block &&
+          typeof block === 'object' &&
+          block.type === 'tool_use' &&
+          typeof block.name === 'string'
+        ) {
+          tools.add(block.name);
+        }
+      }
+    } catch {
+      // Not JSON content — skip
+    }
+  }
+
+  return [...tools];
+}
+
+/**
+ * Build a template from user text by replacing variable-looking parts
+ * with mustache-style placeholders.
+ *
+ * Returns the template string and a map of property schemas for the
+ * identified placeholders.
+ */
+function buildTemplate(text: string): {
+  template: string;
+  properties: Record<string, { type: string; description: string }>;
+} {
+  const properties: Record<string, { type: string; description: string }> = {};
+  let template = text;
+  let urlIndex = 0;
+  let filePathIndex = 0;
+
+  // Replace URLs first so they don't get partially matched by file path regex
+  template = template.replace(
+    /https?:\/\/[^\s)>]+/g,
+    () => {
+      const key = urlIndex === 0 ? 'url' : `url_${urlIndex}`;
+      urlIndex++;
+      properties[key] = {
+        type: 'string',
+        description: 'The URL to use',
+      };
+      return `{{${key}}}`;
+    },
+  );
+
+  // Replace absolute file paths (e.g. /Users/foo/bar.txt, ~/docs/file)
+  // Only match paths starting with / or ~/ that have at least two segments
+  template = template.replace(
+    /(?:~\/|\/(?:[a-zA-Z0-9._-]+\/)+[a-zA-Z0-9._-]+)/g,
+    () => {
+      const key = filePathIndex === 0 ? 'file_path' : `file_path_${filePathIndex}`;
+      filePathIndex++;
+      properties[key] = {
+        type: 'string',
+        description: 'The file path to operate on',
+      };
+      return `{{${key}}}`;
+    },
+  );
+
+  return { template, properties };
+}
+
+/**
+ * Derive a short title from the user's first message.
+ * Truncates to 60 characters with ellipsis if needed.
+ */
+function deriveTitle(text: string): string {
+  // Take the first line and trim whitespace
+  const firstLine = text.split('\n')[0].trim();
+  return truncate(firstLine, 60);
+}