@vellumai/assistant 0.3.0

package/src/tasks/task-runner.ts

@@ -0,0 +1,90 @@
+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';
+import { sanitizeToolList } from './tool-sanitizer.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. When set, only these tools get ephemeral allow rules. */
+  approvedTools?: 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, 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 = createConversation({ title: `Task: ${task.title}`, threadType: 'background' });
+
+  updateTaskRun(run.id, {
+    conversationId: conversation.id,
+    memoryScopeId: `task:${task.id}`,
+  });
+
+  // Build and register ephemeral permission rules. If the user pre-approved
+  // specific tools via the preflight flow, use those instead of all requiredTools.
+  const requiredTools = sanitizeToolList(task.requiredTools ? JSON.parse(task.requiredTools) : []);
+  const toolsForRules = opts.approvedTools ? sanitizeToolList(opts.approvedTools) : requiredTools;
+  const rules = buildTaskRules(run.id, toolsForRules, 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, 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() });
+
+    return {
+      taskRunId: run.id,
+      conversationId: conversation.id,
+      status: 'failed',
+      error: errorMessage,
+    };
+  } finally {
+    clearTaskRunRules(run.id);
+  }
+}

package/src/tasks/task-scheduler.ts

@@ -0,0 +1,21 @@
+import { createSchedule } from '../schedule/schedule-store.js';
+
+/**
+ * Create a cron schedule that runs a task on a recurring cron expression.
+ * RRULE syntax is supported at the store layer but this helper currently defaults to cron.
+ * 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();
+}

package/src/tasks/tool-sanitizer.ts

@@ -0,0 +1,36 @@
+import { getTool, getAllTools } from '../tools/registry.js';
+
+/**
+ * Deduplicate and sort a list of tool names, validating against the live
+ * tool registry. Unknown tool names are logged at warn level but kept —
+ * they may refer to skill tools that will be loaded at runtime.
+ *
+ * The returned array is deterministic: sorted alphabetically with no duplicates.
+ */
+export function sanitizeToolList(tools: string[]): string[] {
+  const seen = new Set<string>();
+
+  for (const tool of tools) {
+    if (!tool || typeof tool !== 'string') continue;
+    seen.add(tool);
+  }
+
+  return [...seen].sort();
+}
+
+/**
+ * Get all registered tool names from the live tool registry.
+ * Used as the fallback when a task/work-item has no explicit requiredTools.
+ */
+export function getRegisteredToolNames(): string[] {
+  return getAllTools()
+    .filter((t) => t.executionMode !== 'proxy' && t.origin !== 'skill')
+    .map((t) => t.name)
+    .sort();
+}
+
+/** Look up the human-readable description for a tool from the registry. */
+export function getToolDescription(tool: string): string {
+  const registered = getTool(tool);
+  return registered?.description ?? tool;
+}

package/src/tools/apps/definitions.ts

@@ -0,0 +1,59 @@
+/**
+ * Core app proxy tool definitions.
+ *
+ * Only the `app_open` proxy tool remains here -- it is forwarded to the
+ * connected macOS client (same pattern as ui_show).  All non-proxy data
+ * tools (create, list, query, update, delete, file ops) are now provided
+ * by the bundled app-builder skill via its TOOLS.json manifest and
+ * executor scripts.
+ */
+
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function proxyExecute(): Promise<ToolExecutionResult> {
+  throw new Error('Proxy tool: execution must be forwarded to the connected client');
+}
+
+// ---------------------------------------------------------------------------
+// app_open
+// ---------------------------------------------------------------------------
+
+const appOpenTool: Tool = {
+  name: 'app_open',
+  description:
+    'Open a persistent app in a dynamic_page surface on the connected client.',
+  category: 'apps',
+  defaultRiskLevel: RiskLevel.Low,
+  executionMode: 'proxy',
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          app_id: {
+            type: 'string',
+            description: 'The ID of the app to open',
+          },
+        },
+        required: ['app_id'],
+      },
+    };
+  },
+
+  execute: proxyExecute,
+};
+
+// ---------------------------------------------------------------------------
+// Proxy-only tools registered in the core daemon registry
+// ---------------------------------------------------------------------------
+
+export const coreAppProxyTools: Tool[] = [appOpenTool];

package/src/tools/apps/executors.ts

@@ -0,0 +1,313 @@
+/**
+ * Standalone executor functions for app tool operations.
+ *
+ * Each executor encapsulates the business logic that was previously inline
+ * in the tool definition's execute() handler.  They accept plain typed
+ * parameters and return plain result objects, making them reusable from
+ * both core tool handlers and skill scripts without depending on
+ * ToolDefinition or ToolContext types.
+ */
+
+import type { AppDefinition } from '../../memory/app-store.js';
+import type { EditEngineResult } from '../../memory/app-store.js';
+import { setHomeBaseAppLink } from '../../home-base/app-link-store.js';
+import { openAppViaSurface } from './open-proxy.js';
+
+// ---------------------------------------------------------------------------
+// Shared result type
+// ---------------------------------------------------------------------------
+
+export interface ExecutorResult {
+  content: string;
+  isError: boolean;
+  /** Optional status message for display (e.g. progress indicator). */
+  status?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Dependency interfaces — callers inject these rather than importing the
+// app-store module directly, which makes the executors testable with mocks.
+// ---------------------------------------------------------------------------
+
+export interface AppStoreReader {
+  getApp(id: string): AppDefinition | null;
+  listApps(): AppDefinition[];
+  queryAppRecords(appId: string): unknown[];
+  listAppFiles(appId: string): string[];
+  readAppFile(appId: string, path: string): string;
+}
+
+export interface AppStoreWriter {
+  createApp(params: {
+    name: string;
+    description?: string;
+    schemaJson: string;
+    htmlDefinition: string;
+    pages?: Record<string, string>;
+    appType?: 'app' | 'site';
+  }): AppDefinition;
+  updateApp(
+    id: string,
+    updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>>,
+  ): AppDefinition;
+  deleteApp(id: string): void;
+  writeAppFile(appId: string, path: string, content: string): void;
+  editAppFile(
+    appId: string,
+    path: string,
+    oldString: string,
+    newString: string,
+    replaceAll?: boolean,
+  ): EditEngineResult;
+}
+
+export type AppStore = AppStoreReader & AppStoreWriter;
+
+/**
+ * Proxy resolver type matching the shape used by the core tool context.
+ * Allows app_create's auto-open behavior to forward to the connected client.
+ */
+export type ProxyResolver = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ExecutorResult>;
+
+// ---------------------------------------------------------------------------
+// app_create
+// ---------------------------------------------------------------------------
+
+export interface AppCreateInput {
+  name: string;
+  description?: string;
+  schema_json?: string;
+  html: string;
+  pages?: Record<string, string>;
+  type?: 'app' | 'site';
+  auto_open?: boolean;
+  set_as_home_base?: boolean;
+  preview?: Record<string, unknown>;
+}
+
+export async function executeAppCreate(
+  input: AppCreateInput,
+  store: AppStore,
+  proxyToolResolver?: ProxyResolver,
+): Promise<ExecutorResult> {
+  const name = input.name;
+  const description = input.description;
+  const schemaJson = input.schema_json ?? '{}';
+  const htmlDefinition = input.html;
+  const pages = input.pages;
+  const autoOpen = input.auto_open !== false; // default true
+  const preview = input.preview;
+  const appType = input.type === 'site' ? 'site' as const : 'app' as const;
+
+  const app = store.createApp({ name, description, schemaJson, htmlDefinition, pages, appType });
+
+  if (input.set_as_home_base) {
+    setHomeBaseAppLink(app.id, 'personalized');
+  }
+
+  // Auto-open the app via the shared open-proxy helper
+  if (autoOpen && proxyToolResolver) {
+    const extraInput = preview ? { preview } : undefined;
+    const openResultText = await openAppViaSurface(app.id, proxyToolResolver, extraInput);
+
+    // Determine whether the open succeeded by checking for the fallback text
+    const opened = openResultText !== 'Failed to auto-open app. Use app_open to open it manually.';
+    if (opened) {
+      return {
+        content: JSON.stringify({
+          ...app,
+          auto_opened: true,
+          open_result: openResultText,
+        }),
+        isError: false,
+      };
+    }
+
+    return {
+      content: JSON.stringify({
+        ...app,
+        auto_opened: false,
+        auto_open_error: openResultText,
+      }),
+      isError: false,
+    };
+  }
+
+  return { content: JSON.stringify(app), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_list
+// ---------------------------------------------------------------------------
+
+export function executeAppList(store: AppStoreReader): ExecutorResult {
+  const apps = store.listApps().map((a) => ({
+    id: a.id,
+    name: a.name,
+    description: a.description,
+    updatedAt: a.updatedAt,
+  }));
+  return { content: JSON.stringify(apps), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_query
+// ---------------------------------------------------------------------------
+
+export interface AppQueryInput {
+  app_id: string;
+}
+
+export function executeAppQuery(
+  input: AppQueryInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const records = store.queryAppRecords(input.app_id);
+  return { content: JSON.stringify(records), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_update
+// ---------------------------------------------------------------------------
+
+export interface AppUpdateInput {
+  app_id: string;
+  name?: string;
+  description?: string;
+  schema_json?: string;
+  html?: string;
+  pages?: Record<string, string>;
+}
+
+export function executeAppUpdate(
+  input: AppUpdateInput,
+  store: AppStore,
+): ExecutorResult {
+  const updates: Partial<Pick<AppDefinition, 'name' | 'description' | 'schemaJson' | 'htmlDefinition' | 'pages'>> = {};
+  if (typeof input.name === 'string') updates.name = input.name;
+  if (typeof input.description === 'string') updates.description = input.description;
+  if (typeof input.schema_json === 'string') updates.schemaJson = input.schema_json;
+  if (typeof input.html === 'string') updates.htmlDefinition = input.html;
+  if (input.pages && typeof input.pages === 'object') updates.pages = input.pages;
+
+  const app = store.updateApp(input.app_id, updates);
+  return { content: JSON.stringify(app), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_delete
+// ---------------------------------------------------------------------------
+
+export interface AppDeleteInput {
+  app_id: string;
+}
+
+export function executeAppDelete(
+  input: AppDeleteInput,
+  store: AppStore,
+): ExecutorResult {
+  store.deleteApp(input.app_id);
+  return { content: JSON.stringify({ deleted: true, appId: input.app_id }), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_list
+// ---------------------------------------------------------------------------
+
+export interface AppFileListInput {
+  app_id: string;
+}
+
+export function executeAppFileList(
+  input: AppFileListInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const files = store.listAppFiles(input.app_id);
+  return { content: JSON.stringify(files), isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_read
+// ---------------------------------------------------------------------------
+
+export interface AppFileReadInput {
+  app_id: string;
+  path: string;
+  offset?: number;
+  limit?: number;
+}
+
+export function executeAppFileRead(
+  input: AppFileReadInput,
+  store: AppStoreReader,
+): ExecutorResult {
+  const offset = input.offset ?? 1;
+  const limit = input.limit;
+
+  const raw = store.readAppFile(input.app_id, input.path);
+  const allLines = raw.split('\n');
+  const startIndex = Math.max(0, offset - 1);
+  const sliced = limit != null ? allLines.slice(startIndex, startIndex + limit) : allLines.slice(startIndex);
+
+  const formatted = sliced
+    .map((line, i) => {
+      const lineNum = startIndex + i + 1;
+      return `${String(lineNum).padStart(6)}\t${line}`;
+    })
+    .join('\n');
+
+  return { content: formatted, isError: false };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_edit
+// ---------------------------------------------------------------------------
+
+export interface AppFileEditInput {
+  app_id: string;
+  path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+  status?: string;
+}
+
+export function executeAppFileEdit(
+  input: AppFileEditInput,
+  store: AppStore,
+): ExecutorResult {
+  if (!input.old_string) {
+    return { content: JSON.stringify({ error: 'old_string must not be empty' }), isError: true };
+  }
+
+  const replaceAll = input.replace_all ?? false;
+  const result = store.editAppFile(input.app_id, input.path, input.old_string, input.new_string, replaceAll);
+  return { content: JSON.stringify(result), isError: false, status: input.status };
+}
+
+// ---------------------------------------------------------------------------
+// app_file_write
+// ---------------------------------------------------------------------------
+
+export interface AppFileWriteInput {
+  app_id: string;
+  path: string;
+  content: string;
+  status?: string;
+}
+
+export function executeAppFileWrite(
+  input: AppFileWriteInput,
+  store: AppStore,
+): ExecutorResult {
+  const app = store.getApp(input.app_id);
+  if (!app) {
+    return { content: JSON.stringify({ error: `App '${input.app_id}' not found` }), isError: true };
+  }
+
+  store.writeAppFile(input.app_id, input.path, input.content);
+  return { content: JSON.stringify({ written: true, path: input.path }), isError: false, status: input.status };
+}

package/src/tools/apps/open-proxy.ts

@@ -0,0 +1,43 @@
+/**
+ * Centralized helper for resolving and executing the `app_open` proxy tool.
+ *
+ * This encapsulates the proxyToolResolver('app_open', ...) pattern so that
+ * callers (app_create auto-open, document-tool, future skill scripts) share
+ * a single implementation with consistent success/failure messaging.
+ */
+
+import type { ProxyResolver, ExecutorResult } from './executors.js';
+
+/**
+ * Open an app on the connected client via the proxy tool resolver.
+ *
+ * @param appId - The ID of the app to open.
+ * @param proxyToolResolver - Optional proxy resolver from the tool context.
+ *   When undefined (e.g. no macOS client connected), returns an informational
+ *   message rather than throwing.
+ * @param extraInput - Optional additional fields to pass alongside app_id
+ *   (e.g. preview metadata).
+ * @returns A stable result string describing the outcome.
+ */
+export async function openAppViaSurface(
+  appId: string,
+  proxyToolResolver: ProxyResolver | undefined,
+  extraInput?: Record<string, unknown>,
+): Promise<string> {
+  if (!proxyToolResolver) {
+    return 'App created but could not be opened (no connected client). Use app_open to open it manually.';
+  }
+
+  try {
+    const result: ExecutorResult = await proxyToolResolver('app_open', {
+      app_id: appId,
+      ...extraInput,
+    });
+    if (result.isError) {
+      return 'Failed to auto-open app. Use app_open to open it manually.';
+    }
+    return result.content;
+  } catch {
+    return 'Failed to auto-open app. Use app_open to open it manually.';
+  }
+}