vellum 0.0.16 → 0.2.0

package/src/tasks/SPEC.md

@@ -0,0 +1,133 @@
+# 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. **Start**: The daemon creates a `background` thread, substitutes template
+   placeholders, and sends the prompt to the LLM. An IPC notification
+   (`task_run_started`) is broadcast to all connected clients with the run ID,
+   task ID, and thread ID.
+2. **Completion**: When the LLM response is received and stored, the daemon
+   broadcasts a `task_run_completed` notification with the run ID, task ID,
+   thread ID, and a status (`success` | `error`).
+3. **Visibility**: Background threads 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 threads:** 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
+
+- **No auto-execution**: Tasks are never triggered automatically. Every run
+  requires an explicit user action (CLI command, API call, or UI button press).
+- **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 always prompt**: Regardless of any task-level permission
+  configuration, tools classified as `RiskLevel.High` (destructive shell
+  commands, private-network fetches, etc.) always require interactive user
+  confirmation. This invariant cannot be overridden by task definitions.
+
+---
+
+## 5. PR Dependency Chain
+
+Implementation is split into sequential PRs, each building on the previous:
+
+| PR | Title | What it delivers |
+|----|-------|------------------|
+| 0  | Spec decisions | This document. |
+| 1  | Schema + storage | `tasks` and `task_runs` tables, Drizzle schema, migration in `db.ts`, CRUD functions in `task-store.ts`. |
+| 2  | Template engine | `renderTemplate()` — placeholder substitution with input validation against the JSON Schema. |
+| 3  | Run executor | `executeTaskRun()` — creates background thread, calls LLM, writes result, broadcasts IPC notifications (`task_run_started`, `task_run_completed`). |
+| 4  | CLI surface | `vellum task create`, `vellum task run`, `vellum task list` commands. |
+| 5  | IPC + macOS integration | Wire up IPC message types; macOS client displays task run results. |

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,41 @@
+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 to the
+ * given working directory. Priority is set to 50 — lower than user rules (100)
+ * so that user deny rules still take precedence. `allowHighRisk` is NOT set,
+ * so high-risk operations continue to prompt for approval.
+ */
+export function buildTaskRules(taskRunId: string, requiredTools: string[], workingDir: string): TrustRule[] {
+  return requiredTools.map((tool) => ({
+    id: `ephemeral:${taskRunId}:${tool}`,
+    tool,
+    pattern: '**',
+    scope: workingDir,
+    decision: 'allow' as const,
+    priority: 50,
+    createdAt: Date.now(),
+    principalKind: 'task',
+    principalId: taskRunId,
+  }));
+}

package/src/tasks/task-compiler.ts

@@ -0,0 +1,198 @@
+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';
+
+/** 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 = 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();
+  if (firstLine.length <= 60) return firstLine;
+  return firstLine.slice(0, 57) + '...';
+}

package/src/tasks/task-runner.ts

@@ -0,0 +1,85 @@
+import { getLogger } from '../util/logger.js';
+import { createConversation } from '../memory/conversation-store.js';
+import { getTask, createTaskRun, updateTaskRun } from './task-store.js';
+import { buildTaskRules, setTaskRunRules, clearTaskRunRules } from './ephemeral-permissions.js';
+
+const log = getLogger('task-runner');
+
+export interface TaskRunOptions {
+  taskId: string;
+  inputs?: Record<string, string>;
+  workingDir: string;
+}
+
+export interface TaskRunResult {
+  taskRunId: string;
+  conversationId: string;
+  status: 'completed' | 'failed';
+  error?: string;
+}
+
+/** Replace {{key}} placeholders in template with values from inputs. */
+export function renderTemplate(template: string, inputs: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (key in inputs) return inputs[key];
+    return match;
+  });
+}
+
+/**
+ * Execute a task: create a run, set up ephemeral permissions,
+ * render the template, and process it as a message.
+ */
+export async function runTask(
+  opts: TaskRunOptions,
+  processMessage: (conversationId: string, message: string) => Promise<void>,
+): Promise<TaskRunResult> {
+  const task = getTask(opts.taskId);
+  if (!task) {
+    throw new Error(`Task not found: ${opts.taskId}`);
+  }
+
+  const run = createTaskRun(task.id);
+  const conversation = createConversation({ title: `Task: ${task.title}`, threadType: 'background' });
+
+  updateTaskRun(run.id, {
+    conversationId: conversation.id,
+    memoryScopeId: `task:${task.id}`,
+  });
+
+  // Build and register ephemeral permission rules from the task's required tools
+  const requiredTools: string[] = task.requiredTools ? JSON.parse(task.requiredTools) : [];
+  const rules = buildTaskRules(run.id, requiredTools, opts.workingDir);
+  setTaskRunRules(run.id, rules);
+
+  try {
+    const renderedTemplate = renderTemplate(task.template, opts.inputs ?? {});
+
+    updateTaskRun(run.id, { status: 'running', startedAt: Date.now() });
+
+    log.info({ taskId: task.id, taskRunId: run.id, conversationId: conversation.id }, 'Executing task');
+    await processMessage(conversation.id, renderedTemplate);
+
+    updateTaskRun(run.id, { status: 'completed', finishedAt: Date.now() });
+
+    return {
+      taskRunId: run.id,
+      conversationId: conversation.id,
+      status: 'completed',
+    };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    log.warn({ err, taskId: task.id, taskRunId: run.id }, 'Task execution failed');
+
+    updateTaskRun(run.id, { status: 'failed', error: errorMessage, finishedAt: Date.now() });
+
+    return {
+      taskRunId: run.id,
+      conversationId: conversation.id,
+      status: 'failed',
+      error: errorMessage,
+    };
+  } finally {
+    clearTaskRunRules(run.id);
+  }
+}

package/src/tasks/task-scheduler.ts

@@ -0,0 +1,20 @@
+import { createSchedule } from '../schedule/schedule-store.js';
+
+/**
+ * Create a schedule that runs a task on a cron expression.
+ * The scheduler detects the `run_task:<taskId>` message format
+ * and delegates to runTask() instead of processMessage().
+ */
+export function scheduleTask(opts: {
+  taskId: string;
+  name: string;
+  cronExpression: string;
+  timezone?: string;
+}): ReturnType<typeof createSchedule> {
+  return createSchedule({
+    name: opts.name,
+    cronExpression: opts.cronExpression,
+    timezone: opts.timezone ?? null,
+    message: `run_task:${opts.taskId}`,
+  });
+}

package/src/tasks/task-store.ts

@@ -0,0 +1,127 @@
+import { eq, desc, inArray } from 'drizzle-orm';
+import { getDb } from '../memory/db.js';
+import { tasks, taskRuns, workItems } from '../memory/schema.js';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+export interface Task {
+  id: string;
+  title: string;
+  template: string;
+  inputSchema: string | null;
+  contextFlags: string | null;
+  requiredTools: string | null;
+  createdFromConversationId: string | null;
+  status: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TaskRun {
+  id: string;
+  taskId: string;
+  conversationId: string | null;
+  status: string;
+  startedAt: number | null;
+  finishedAt: number | null;
+  error: string | null;
+  principalId: string | null;
+  memoryScopeId: string | null;
+  createdAt: number;
+}
+
+// ── Task CRUD ────────────────────────────────────────────────────────
+
+export function createTask(opts: {
+  title: string;
+  template: string;
+  inputSchema?: object;
+  contextFlags?: string[];
+  requiredTools?: string[];
+  createdFromConversationId?: string;
+}): Task {
+  const db = getDb();
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  const task: Task = {
+    id,
+    title: opts.title,
+    template: opts.template,
+    inputSchema: opts.inputSchema ? JSON.stringify(opts.inputSchema) : null,
+    contextFlags: opts.contextFlags ? JSON.stringify(opts.contextFlags) : null,
+    requiredTools: opts.requiredTools ? JSON.stringify(opts.requiredTools) : null,
+    createdFromConversationId: opts.createdFromConversationId ?? null,
+    status: 'active',
+    createdAt: now,
+    updatedAt: now,
+  };
+  db.insert(tasks).values(task).run();
+  return task;
+}
+
+export function getTask(id: string): Task | undefined {
+  const db = getDb();
+  return db.select().from(tasks).where(eq(tasks.id, id)).get();
+}
+
+export function listTasks(): Task[] {
+  const db = getDb();
+  return db.select().from(tasks).orderBy(desc(tasks.createdAt)).all();
+}
+
+export function deleteTask(id: string): boolean {
+  const db = getDb();
+  const existing = db.select().from(tasks).where(eq(tasks.id, id)).get();
+  if (!existing) return false;
+  db.delete(workItems).where(eq(workItems.taskId, id)).run();
+  db.delete(taskRuns).where(eq(taskRuns.taskId, id)).run();
+  db.delete(tasks).where(eq(tasks.id, id)).run();
+  return true;
+}
+
+export function deleteTasks(ids: string[]): number {
+  if (ids.length === 0) return 0;
+  const db = getDb();
+  const existing = db.select().from(tasks).where(inArray(tasks.id, ids)).all();
+  if (existing.length === 0) return 0;
+  const foundIds = existing.map((t) => t.id);
+  db.delete(workItems).where(inArray(workItems.taskId, foundIds)).run();
+  db.delete(taskRuns).where(inArray(taskRuns.taskId, foundIds)).run();
+  db.delete(tasks).where(inArray(tasks.id, foundIds)).run();
+  return existing.length;
+}
+
+// ── TaskRun CRUD ─────────────────────────────────────────────────────
+
+export function createTaskRun(taskId: string): TaskRun {
+  const db = getDb();
+  const now = Date.now();
+  const id = crypto.randomUUID();
+  const run: TaskRun = {
+    id,
+    taskId,
+    conversationId: null,
+    status: 'pending',
+    startedAt: null,
+    finishedAt: null,
+    error: null,
+    principalId: null,
+    memoryScopeId: null,
+    createdAt: now,
+  };
+  db.insert(taskRuns).values(run).run();
+  return run;
+}
+
+export function updateTaskRun(
+  id: string,
+  updates: Partial<Pick<TaskRun, 'status' | 'conversationId' | 'error' | 'principalId' | 'memoryScopeId' | 'startedAt' | 'finishedAt'>>,
+): void {
+  const db = getDb();
+  db.update(taskRuns).set(updates).where(eq(taskRuns.id, id)).run();
+}
+
+export function getTaskRun(id: string): TaskRun | undefined {
+  const db = getDb();
+  return db.select().from(taskRuns).where(eq(taskRuns.id, id)).get();
+}