@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/runtime/skill-route-registry.ts

@@ -1,131 +0,0 @@
-/**
- * Registry for skill-provided HTTP route handlers.
- *
- * Skills and plugins register route matchers + handlers at initialization
- * time. The runtime HTTP server checks the registry for each inbound request
- * before falling through to its own route table.
- *
- * Registrations are identified by an opaque {@link SkillRouteHandle} returned
- * from {@link registerSkillRoute}. Callers must pass that exact handle back
- * to {@link unregisterSkillRoute} to remove the registration — pattern text
- * is intentionally not a stable key, because two owners can legitimately
- * register the same regex, and keying on `source + flags` would let one
- * owner's teardown silently drop another owner's route.
- */
-
-import { getLogger } from "../util/logger.js";
-
-const log = getLogger("skill-route-registry");
-
-export interface SkillRoute {
-  /** Regex to match against the request path. Capture groups are passed to the handler. */
-  pattern: RegExp;
-  /** HTTP method(s) the route accepts. */
-  methods: string[];
-  /** Handler function. Receives the request and the regex match result. */
-  handler: (req: Request, match: RegExpMatchArray) => Promise<Response>;
-}
-
-export type SkillRouteMatch =
-  | { kind: "match"; route: SkillRoute; match: RegExpMatchArray }
-  | { kind: "methodMismatch"; allow: string[] };
-
-/**
- * Opaque token returned from {@link registerSkillRoute}. The token has no
- * observable fields — callers must treat it as a black box whose only valid
- * use is to pass it to {@link unregisterSkillRoute}. Identity comparison on
- * the token is what the registry keys against, so every call to
- * `registerSkillRoute` returns a fresh handle even when the route's
- * `pattern`/`methods`/`handler` are deep-equal to an existing entry.
- */
-declare const skillRouteHandleBrand: unique symbol;
-export interface SkillRouteHandle {
-  readonly [skillRouteHandleBrand]: true;
-}
-
-interface RegisteredRoute {
-  readonly handle: SkillRouteHandle;
-  readonly route: SkillRoute;
-}
-
-const routes: RegisteredRoute[] = [];
-
-/**
- * Register a skill- or plugin-provided HTTP route. Called at initialization
- * time. Returns an opaque handle the caller must retain and pass back to
- * {@link unregisterSkillRoute} at teardown time. Do not attempt to derive
- * the handle from the route's pattern — identity is the only stable key.
- */
-export function registerSkillRoute(route: SkillRoute): SkillRouteHandle {
-  const handle = Object.freeze({}) as SkillRouteHandle;
-  routes.push({ handle, route });
-  log.info(
-    { pattern: route.pattern.source, methods: route.methods },
-    "Skill route registered",
-  );
-  return handle;
-}
-
-/**
- * Unregister a previously-registered skill route by handle.
- *
- * Returns `true` if a route was removed, `false` otherwise. Not finding a
- * match is not an error: the plugin-shutdown path calls this best-effort for
- * every handle a plugin retained, and a stale handle (e.g. the registry was
- * cleared externally) should not crash shutdown.
- */
-export function unregisterSkillRoute(handle: SkillRouteHandle): boolean {
-  const index = routes.findIndex((entry) => entry.handle === handle);
-  if (index === -1) {
-    log.warn({}, "unregisterSkillRoute: no matching route found for handle");
-    return false;
-  }
-  const [removed] = routes.splice(index, 1);
-  log.info(
-    { pattern: removed!.route.pattern.source },
-    "Skill route unregistered",
-  );
-  return true;
-}
-
-/**
- * Try to match an inbound request path + method against registered skill routes.
- *
- * - Returns `{ kind: "match", ... }` when a route matches both path and method.
- * - Returns `{ kind: "methodMismatch", allow }` when one or more routes match
- *   the path but none accept the method — the caller should respond with 405
- *   and an `Allow` header listing the accepted methods.
- * - Returns `null` when no route matches the path at all; the request then
- *   falls through to JWT auth and the normal route table.
- *
- * Method gating lives here so unauthenticated requests with the wrong method
- * cannot reach skill handlers, and so same-path/different-method route pairs
- * dispatch to the correct handler.
- */
-export function matchSkillRoute(
-  path: string,
-  method: string,
-): SkillRouteMatch | null {
-  const pathMatches: SkillRoute[] = [];
-  for (const entry of routes) {
-    const match = path.match(entry.route.pattern);
-    if (!match) continue;
-    if (entry.route.methods.includes(method)) {
-      return { kind: "match", route: entry.route, match };
-    }
-    pathMatches.push(entry.route);
-  }
-  if (pathMatches.length === 0) return null;
-  const allow = Array.from(new Set(pathMatches.flatMap((r) => r.methods)));
-  return { kind: "methodMismatch", allow };
-}
-
-/**
- * Test-only helper — drops every registered route. Production code has no
- * legitimate need for this; a real shutdown walks the handles each owner
- * retained. Exported so tests that bypass the normal shutdown path (e.g.
- * those that crash mid-bootstrap) can reset registry state between cases.
- */
-export function resetSkillRoutesForTests(): void {
-  routes.length = 0;
-}

package/src/tasks/SPEC.md

@@ -1,132 +0,0 @@
-# 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 conversation.
-
----
-
-## 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 Policy
-
-Task runs share the single workspace memory pool — the same memory the user's
-main conversations read and write. There is no per-task memory isolation.
-
-This means:
-
-- **Cross-run learning**: All runs of a task draw from and contribute to the
-  shared workspace memory, so the assistant can accumulate knowledge relevant
-  to a task across invocations (e.g., learning the user's preferred summary
-  style over time).
-- **Shared context**: A run can use what the assistant already knows from the
-  user's chat history, and what a run records is available to later
-  conversations and other tasks.
-
----
-
-## 3. Run Surface
-
-Each task run creates a new background conversation with `conversationType: '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` SSE events.
-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 conversation
-   list (existing behavior in `conversation-crud.ts`). Clients can query for
-   them explicitly to surface task results in a dedicated UI.
-
-**Why background conversations:** Reuses the existing `conversationType: '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) | HTTP 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/task-compiler.ts

@@ -1,194 +0,0 @@
-import { eq } from "drizzle-orm";
-
-import { getDb } from "../persistence/db-connection.js";
-import { messages as messagesTable } from "../persistence/schema/index.js";
-import { parseJsonSafe } from "../util/json.js";
-import { truncate } from "../util/truncate.js";
-import type { Task } from "./task-store.js";
-import { createTask } from "./task-store.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 {
-  const parsed = parseJsonSafe(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");
-  }
-  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;
-
-    const parsed = parseJsonSafe(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);
-      }
-    }
-  }
-
-  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);
-}

package/src/tasks/task-runner.ts

@@ -1,119 +0,0 @@
-import { bootstrapConversation } from "../persistence/conversation-bootstrap.js";
-import { invalidateAssistantInferredItemsForConversation } from "../plugins/defaults/memory/task-memory-cleanup.js";
-import { getLogger } from "../util/logger.js";
-import { createTaskRun, getTask, updateTaskRun } from "./task-store.js";
-
-const log = getLogger("task-runner");
-
-export interface TaskRunOptions {
-  taskId: string;
-  inputs?: Record<string, string>;
-  workingDir: string;
-  /** Pre-approved tools from the permission preflight flow (stored for audit purposes). */
-  approvedTools?: string[];
-  /** Conversation source to propagate to the created conversation (e.g. 'schedule' when triggered by a schedule). */
-  source?: string;
-  /** Schedule job ID to associate with the conversation. Set when the task is triggered by a schedule. */
-  scheduleJobId?: 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 `<MISSING: ${key}>`;
-  });
-}
-
-/**
- * Execute a task: create a run, render the template, and process it as a message.
- */
-export async function runTask(
-  opts: TaskRunOptions,
-  processMessage: (
-    conversationId: string,
-    message: string,
-    taskRunId: 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 = await bootstrapConversation({
-    // Schedule-triggered tasks use "scheduled" so they don't crowd out
-    // interactive conversations in the main list; non-schedule tasks use
-    // "background" to stay out of the list entirely.
-    conversationType: opts.source === "schedule" ? "scheduled" : "background",
-    source: opts.source === "schedule" ? "schedule" : "task",
-    scheduleJobId: opts.scheduleJobId,
-    groupId:
-      opts.source === "schedule" ? "system:scheduled" : "system:background",
-    origin: "task",
-    systemHint: `Task: ${task.title}`,
-  });
-
-  updateTaskRun(run.id, {
-    conversationId: conversation.id,
-  });
-
-  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, run.id);
-
-    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(),
-    });
-
-    try {
-      invalidateAssistantInferredItemsForConversation(conversation.id);
-    } catch (cleanupErr) {
-      log.warn(
-        { err: cleanupErr, conversationId: conversation.id },
-        "Failed to invalidate assistant-inferred memory items",
-      );
-    }
-
-    return {
-      taskRunId: run.id,
-      conversationId: conversation.id,
-      status: "failed",
-      error: errorMessage,
-    };
-  }
-}

package/src/tasks/task-scheduler.ts

@@ -1,22 +0,0 @@
-import { createSchedule } from "../schedule/schedule-store.js";
-
-/**
- * Create a cron schedule that runs a task on a recurring 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,
-    description: `Run task: ${opts.name}`,
-    cronExpression: opts.cronExpression,
-    timezone: opts.timezone ?? null,
-    message: `run_task:${opts.taskId}`,
-    syntax: "cron",
-  });
-}