vellum 0.2.0 → 0.2.2

package/src/tools/terminal/backends/native.ts

@@ -9,6 +9,8 @@ import type { SandboxBackend, SandboxResult } from './types.js';
 
 const log = getLogger('sandbox');
 
+const HASH_DISPLAY_LENGTH = 12;
+
 /**
  * macOS sandbox-exec profile that restricts shell commands:
  * - Denies all by default
@@ -81,7 +83,7 @@ function getProfilePath(workingDir: string): string {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
-  const hash = createHash('sha256').update(workingDir).digest('hex').slice(0, 12);
+  const hash = createHash('sha256').update(workingDir).digest('hex').slice(0, HASH_DISPLAY_LENGTH);
   const path = join(dir, `sandbox-profile-${hash}.sb`);
 
   const profile = SANDBOX_PROFILE.replace(/__WORKING_DIR__/g, workingDir);

package/src/tools/tool-manifest.ts

@@ -12,54 +12,30 @@ import type { Tool } from './types.js';
 import { memorySearchTool, memorySaveTool, memoryUpdateTool } from './memory/register.js';
 import { credentialStoreTool } from './credentials/vault.js';
 import { accountManageTool } from './credentials/account-registry.js';
-import { reminderTool } from './reminder/reminder.js';
 import { screenWatchTool } from './watch/screen-watch.js';
 import { vellumSkillsCatalogTool } from './skills/vellum-catalog.js';
-import { documentCreateTool, documentUpdateTool } from './document/index.js';
 import { cliDiscoverTool } from './host-terminal/cli-discover.js';
-import { followupCreateTool, followupListTool, followupResolveTool } from './followups/index.js';
-import { taskSaveTool, taskRunTool, taskListTool, taskDeleteTool, taskListShowTool, taskListAddTool } from './tasks/index.js';
-import {
-  subagentSpawnTool,
-  subagentStatusTool,
-  subagentAbortTool,
-  subagentMessageTool,
-  subagentReadTool,
-} from './subagent/index.js';
 
 // ── Eager side-effect modules ───────────────────────────────────────
 // Importing these modules triggers a top-level `registerTool()` call.
 
-export const eagerModules: string[] = [
-  './filesystem/read.js',
-  './filesystem/write.js',
-  './filesystem/edit.js',
-  './network/web-search.js',
-  './network/web-fetch.js',
-  './skills/load.js',
-  './skills/scaffold-managed.js',
-  './skills/delete-managed.js',
-  './system/request-permission.js',
-  './schedule/create.js',
-  './schedule/list.js',
-  './schedule/update.js',
-  './schedule/delete.js',
-  './watcher/create.js',
-  './watcher/list.js',
-  './watcher/update.js',
-  './watcher/delete.js',
-  './watcher/digest.js',
-  './playbooks/playbook-create.js',
-  './playbooks/playbook-list.js',
-  './playbooks/playbook-update.js',
-  './playbooks/playbook-delete.js',
-  './contacts/contact-upsert.js',
-  './contacts/contact-search.js',
-  './contacts/contact-merge.js',
-  './assets/search.js',
-  './assets/materialize.js',
-  './filesystem/view-image.js',
-];
+export async function loadEagerModules(): Promise<void> {
+  await import('./filesystem/read.js');
+  await import('./filesystem/write.js');
+  await import('./filesystem/edit.js');
+  await import('./network/web-search.js');
+  await import('./network/web-fetch.js');
+  await import('./skills/load.js');
+  await import('./skills/scaffold-managed.js');
+  await import('./skills/delete-managed.js');
+  await import('./system/request-permission.js');
+  await import('./assets/search.js');
+  await import('./assets/materialize.js');
+  await import('./filesystem/view-image.js');
+  await import('./calls/call-start.js');
+  await import('./calls/call-status.js');
+  await import('./calls/call-end.js');
+}
 
 // Tool names registered by the eager modules above.  Listed explicitly so
 // initializeTools() can recognise ESM-cached eager-module tools that were
@@ -75,25 +51,12 @@ export const eagerModuleToolNames: string[] = [
   'scaffold_managed_skill',
   'delete_managed_skill',
   'request_system_permission',
-  'schedule_create',
-  'schedule_list',
-  'schedule_update',
-  'schedule_delete',
-  'watcher_create',
-  'watcher_list',
-  'watcher_update',
-  'watcher_delete',
-  'watcher_digest',
-  'playbook_create',
-  'playbook_list',
-  'playbook_update',
-  'playbook_delete',
-  'contact_upsert',
-  'contact_search',
-  'contact_merge',
   'asset_search',
   'asset_materialize',
   'view_image',
+  'call_start',
+  'call_status',
+  'call_end',
 ];
 
 // ── Explicit tool instances ─────────────────────────────────────────
@@ -106,26 +69,9 @@ export const explicitTools: Tool[] = [
   memoryUpdateTool,
   credentialStoreTool,
   accountManageTool,
-  reminderTool,
   screenWatchTool,
   vellumSkillsCatalogTool,
-  documentCreateTool,
-  documentUpdateTool,
   cliDiscoverTool,
-  followupCreateTool,
-  followupListTool,
-  followupResolveTool,
-  taskSaveTool,
-  taskRunTool,
-  taskListTool,
-  taskDeleteTool,
-  taskListShowTool,
-  taskListAddTool,
-  subagentSpawnTool,
-  subagentStatusTool,
-  subagentAbortTool,
-  subagentMessageTool,
-  subagentReadTool,
 ];
 
 // ── Lazy tool descriptors ───────────────────────────────────────────

package/src/tools/types.ts

@@ -52,6 +52,8 @@ export interface ToolExecutedEvent extends ToolLifecycleEventBase {
   result: ToolExecutionResult;
 }
 
+export type ErrorCategory = 'permission_denied' | 'auth' | 'tool_failure' | 'unexpected';
+
 export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
   type: 'error';
   riskLevel: string;
@@ -59,6 +61,8 @@ export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
   durationMs: number;
   errorMessage: string;
   isExpected: boolean;
+  /** Classifies the error for downstream consumers (audit, alerting, monitoring). */
+  errorCategory: ErrorCategory;
   errorName?: string;
   errorStack?: string;
 }
@@ -89,6 +93,8 @@ export interface ToolContext {
   workingDir: string;
   sessionId: string;
   conversationId: string;
+  /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
+  taskRunId?: string;
   /** Per-message request ID for log correlation across session/connection boundaries. */
   requestId?: string;
   /** Optional callback for streaming incremental output to the client. */

package/src/tools/ui-surface/definitions.ts

@@ -35,6 +35,9 @@ export const uiShowTool: Tool = {
     'templateData shape: { location: string, currentTemp: number, feelsLike: number, unit: "F"|"C", condition: string, humidity: number, windSpeed: number, windDirection: string, ' +
     'hourly: Array<{ time: string, icon: string (SF Symbol name), temp: number }>, ' +
     'forecast: Array<{ day: string, icon: string (SF Symbol name), low: number, high: number, precip: number|null, condition: string }> }\n' +
+    '  Template "task_progress": renders a live-updating task progress widget showing structured step-by-step progress. ' +
+    'templateData shape: { title: string, status: "in_progress"|"completed"|"failed", ' +
+    'steps: Array<{ label: string, status: "pending"|"in_progress"|"completed"|"failed", detail?: string }> }\n' +
     '- table: Data table with columns, selectable rows, and action buttons. ' +
     'data shape: { columns: Array<{ id: string, label: string }>, rows: Array<{ id: string, cells: Record<string, string>, selectable?: boolean, selected?: boolean }>, selectionMode?: "none"|"single"|"multiple", caption?: string }\n' +
     '- form: Input form with typed fields. ' +
@@ -117,7 +120,9 @@ export const uiShowTool: Tool = {
 
 export const uiUpdateTool: Tool = {
   name: 'ui_update',
-  description: "Update an existing surface's data. The provided data object is merged into the surface's current data.",
+  description:
+    "Update an existing surface's data. The provided data object is merged into the surface's current data.\n" +
+    'For card templates (for example `task_progress`), update nested fields under `data.templateData` rather than sending template fields at the top level.',
   category: 'ui-surface',
   defaultRiskLevel: RiskLevel.Low,
   executionMode: 'proxy',

package/src/tools/watch/screen-watch.ts

@@ -13,6 +13,8 @@ import type { WatchSession } from './watch-state.js';
 
 const log = getLogger('screen-watch');
 
+const SHORT_HASH_LENGTH = 8;
+
 class ScreenWatchTool implements Tool {
   name = 'start_screen_watch';
   description = 'Start observing the screen at regular intervals for a specified duration. Captures OCR text from the active window and provides periodic commentary.';
@@ -77,7 +79,7 @@ class ScreenWatchTool implements Tool {
     }
 
     // Generate watchId
-    const watchId = crypto.randomUUID().slice(0, 8);
+    const watchId = crypto.randomUUID().slice(0, SHORT_HASH_LENGTH);
     const now = Date.now();
     const durationSeconds = durationMinutes * 60;
 

package/src/tools/watcher/create.ts

@@ -1,110 +1,64 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { createWatcher } from '../../watcher/watcher-store.js';
 import { getWatcherProvider, listWatcherProviders } from '../../watcher/provider-registry.js';
 
-class WatcherCreateTool implements Tool {
-  name = 'watcher_create';
-  description = 'Create a new watcher that polls an external service for events and processes them with an action prompt';
-  category = 'watcher';
-  defaultRiskLevel = RiskLevel.Medium;
+export async function executeWatcherCreate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const name = input.name as string;
+  const providerId = input.provider as string;
+  const actionPrompt = input.action_prompt as string;
+  const pollIntervalMs = (input.poll_interval_ms as number) ?? undefined;
+  const config = input.config as Record<string, unknown> | undefined;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          name: {
-            type: 'string',
-            description: 'A human-readable name for this watcher (e.g. "My Gmail")',
-          },
-          provider: {
-            type: 'string',
-            description: 'The provider to poll (e.g. "gmail")',
-          },
-          action_prompt: {
-            type: 'string',
-            description: 'Instructions for the LLM on how to handle detected events. This prompt is sent along with event data to a background conversation.',
-          },
-          poll_interval_ms: {
-            type: 'number',
-            description: 'How often to poll in milliseconds. Defaults to 60000 (1 minute). Minimum 15000.',
-          },
-          credential_service: {
-            type: 'string',
-            description: 'Override the credential service to use. Defaults to the provider\'s required service.',
-          },
-          config: {
-            type: 'object',
-            description: 'Provider-specific configuration (e.g. filter criteria)',
-          },
-        },
-        required: ['name', 'provider', 'action_prompt'],
-      },
-    };
+  if (!name || typeof name !== 'string') {
+    return { content: 'Error: name is required and must be a string', isError: true };
+  }
+  if (!providerId || typeof providerId !== 'string') {
+    return { content: 'Error: provider is required and must be a string', isError: true };
+  }
+  if (!actionPrompt || typeof actionPrompt !== 'string') {
+    return { content: 'Error: action_prompt is required and must be a string', isError: true };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const name = input.name as string;
-    const providerId = input.provider as string;
-    const actionPrompt = input.action_prompt as string;
-    const pollIntervalMs = (input.poll_interval_ms as number) ?? undefined;
-    const config = input.config as Record<string, unknown> | undefined;
-
-    if (!name || typeof name !== 'string') {
-      return { content: 'Error: name is required and must be a string', isError: true };
-    }
-    if (!providerId || typeof providerId !== 'string') {
-      return { content: 'Error: provider is required and must be a string', isError: true };
-    }
-    if (!actionPrompt || typeof actionPrompt !== 'string') {
-      return { content: 'Error: action_prompt is required and must be a string', isError: true };
-    }
-
-    const provider = getWatcherProvider(providerId);
-    if (!provider) {
-      const available = listWatcherProviders().map((p) => p.id).join(', ') || 'none';
-      return { content: `Error: Unknown provider "${providerId}". Available: ${available}`, isError: true };
-    }
+  const provider = getWatcherProvider(providerId);
+  if (!provider) {
+    const available = listWatcherProviders().map((p) => p.id).join(', ') || 'none';
+    return { content: `Error: Unknown provider "${providerId}". Available: ${available}`, isError: true };
+  }
 
-    if (pollIntervalMs !== undefined && pollIntervalMs < 15000) {
-      return { content: 'Error: poll_interval_ms must be at least 15000 (15 seconds)', isError: true };
-    }
+  if (pollIntervalMs !== undefined && pollIntervalMs < 15000) {
+    return { content: 'Error: poll_interval_ms must be at least 15000 (15 seconds)', isError: true };
+  }
 
-    const credentialService = (input.credential_service as string) ?? provider.requiredCredentialService;
+  const credentialService = (input.credential_service as string) ?? provider.requiredCredentialService;
 
-    try {
-      const watcher = createWatcher({
-        name,
-        providerId,
-        actionPrompt,
-        credentialService,
-        pollIntervalMs,
-        configJson: config ? JSON.stringify(config) : null,
-      });
+  try {
+    const watcher = createWatcher({
+      name,
+      providerId,
+      actionPrompt,
+      credentialService,
+      pollIntervalMs,
+      configJson: config ? JSON.stringify(config) : null,
+    });
 
-      const intervalSec = Math.round(watcher.pollIntervalMs / 1000);
-      return {
-        content: [
-          'Watcher created successfully.',
-          `  Name: ${watcher.name}`,
-          `  Provider: ${provider.displayName}`,
-          `  Poll interval: ${intervalSec}s`,
-          `  Credential: ${watcher.credentialService}`,
-          `  Status: ${watcher.status}`,
-          `  ID: ${watcher.id}`,
-        ].join('\n'),
-        isError: false,
-      };
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return { content: `Error creating watcher: ${msg}`, isError: true };
-    }
+    const intervalSec = Math.round(watcher.pollIntervalMs / 1000);
+    return {
+      content: [
+        'Watcher created successfully.',
+        `  Name: ${watcher.name}`,
+        `  Provider: ${provider.displayName}`,
+        `  Poll interval: ${intervalSec}s`,
+        `  Credential: ${watcher.credentialService}`,
+        `  Status: ${watcher.status}`,
+        `  ID: ${watcher.id}`,
+      ].join('\n'),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error creating watcher: ${msg}`, isError: true };
   }
 }
-
-registerTool(new WatcherCreateTool());

package/src/tools/watcher/delete.ts

@@ -1,53 +1,27 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { getWatcher, deleteWatcher } from '../../watcher/watcher-store.js';
 
-class WatcherDeleteTool implements Tool {
-  name = 'watcher_delete';
-  description = 'Delete a watcher and all its event history';
-  category = 'watcher';
-  defaultRiskLevel = RiskLevel.Medium;
-
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          watcher_id: {
-            type: 'string',
-            description: 'The ID of the watcher to delete',
-          },
-        },
-        required: ['watcher_id'],
-      },
-    };
+export async function executeWatcherDelete(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const watcherId = input.watcher_id as string;
+  if (!watcherId || typeof watcherId !== 'string') {
+    return { content: 'Error: watcher_id is required', isError: true };
   }
 
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const watcherId = input.watcher_id as string;
-    if (!watcherId || typeof watcherId !== 'string') {
-      return { content: 'Error: watcher_id is required', isError: true };
-    }
-
-    const watcher = getWatcher(watcherId);
-    if (!watcher) {
-      return { content: `Error: Watcher not found: ${watcherId}`, isError: true };
-    }
-
-    const deleted = deleteWatcher(watcherId);
-    if (!deleted) {
-      return { content: `Error: Failed to delete watcher: ${watcherId}`, isError: true };
-    }
+  const watcher = getWatcher(watcherId);
+  if (!watcher) {
+    return { content: `Error: Watcher not found: ${watcherId}`, isError: true };
+  }
 
-    return {
-      content: `Watcher deleted: "${watcher.name}"`,
-      isError: false,
-    };
+  const deleted = deleteWatcher(watcherId);
+  if (!deleted) {
+    return { content: `Error: Failed to delete watcher: ${watcherId}`, isError: true };
   }
-}
 
-registerTool(new WatcherDeleteTool());
+  return {
+    content: `Watcher deleted: "${watcher.name}"`,
+    isError: false,
+  };
+}

package/src/tools/watcher/digest.ts

@@ -1,84 +1,50 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import { registerTool } from '../registry.js';
+import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { listWatchers, listWatcherEvents } from '../../watcher/watcher-store.js';
 
-class WatcherDigestTool implements Tool {
-  name = 'watcher_digest';
-  description = 'Get a summary of recent watcher activity. Use this when the user asks about what happened with their email, notifications, etc.';
-  category = 'watcher';
-  defaultRiskLevel = RiskLevel.Low;
+export async function executeWatcherDigest(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const watcherId = input.watcher_id as string | undefined;
+  const hours = (input.hours as number) ?? 24;
+  const limit = (input.limit as number) ?? 50;
 
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          watcher_id: {
-            type: 'string',
-            description: 'Filter to events from a specific watcher. If omitted, shows events from all watchers.',
-          },
-          hours: {
-            type: 'number',
-            description: 'How many hours back to look. Defaults to 24.',
-          },
-          limit: {
-            type: 'number',
-            description: 'Maximum number of events to return. Defaults to 50.',
-          },
-        },
-        required: [],
-      },
-    };
-  }
-
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const watcherId = input.watcher_id as string | undefined;
-    const hours = (input.hours as number) ?? 24;
-    const limit = (input.limit as number) ?? 50;
-
-    const since = Date.now() - hours * 60 * 60 * 1000;
+  const since = Date.now() - hours * 60 * 60 * 1000;
 
-    const events = listWatcherEvents({ watcherId, limit, since });
+  const events = listWatcherEvents({ watcherId, limit, since });
 
-    if (events.length === 0) {
-      const period = hours === 24 ? 'today' : `the last ${hours} hours`;
-      return { content: `No watcher events detected ${period}.`, isError: false };
-    }
+  if (events.length === 0) {
+    const period = hours === 24 ? 'today' : `the last ${hours} hours`;
+    return { content: `No watcher events detected ${period}.`, isError: false };
+  }
 
-    // Group events by watcher
-    const watcherMap = new Map<string, typeof events>();
-    for (const event of events) {
-      const existing = watcherMap.get(event.watcherId) ?? [];
-      existing.push(event);
-      watcherMap.set(event.watcherId, existing);
-    }
+  // Group events by watcher
+  const watcherMap = new Map<string, typeof events>();
+  for (const event of events) {
+    const existing = watcherMap.get(event.watcherId) ?? [];
+    existing.push(event);
+    watcherMap.set(event.watcherId, existing);
+  }
 
-    // Get watcher names
-    const allWatchers = listWatchers();
-    const nameMap = new Map(allWatchers.map((w) => [w.id, w.name]));
+  // Get watcher names
+  const allWatchers = listWatchers();
+  const nameMap = new Map(allWatchers.map((w) => [w.id, w.name]));
 
-    const lines = [`Watcher activity (last ${hours}h, ${events.length} events):`];
+  const lines = [`Watcher activity (last ${hours}h, ${events.length} events):`];
 
-    for (const [wId, wEvents] of watcherMap) {
-      const name = nameMap.get(wId) ?? wId;
-      lines.push('', `${name} (${wEvents.length} events):`);
+  for (const [wId, wEvents] of watcherMap) {
+    const name = nameMap.get(wId) ?? wId;
+    lines.push('', `${name} (${wEvents.length} events):`);
 
-      for (const event of wEvents) {
-        const time = new Date(event.createdAt).toLocaleString();
-        const disposition = event.disposition !== 'pending' ? ` [${event.disposition}]` : '';
-        lines.push(`  - ${event.summary}${disposition} (${time})`);
-        if (event.llmAction) {
-          lines.push(`    Action: ${event.llmAction}`);
-        }
+    for (const event of wEvents) {
+      const time = new Date(event.createdAt).toLocaleString();
+      const disposition = event.disposition !== 'pending' ? ` [${event.disposition}]` : '';
+      lines.push(`  - ${event.summary}${disposition} (${time})`);
+      if (event.llmAction) {
+        lines.push(`    Action: ${event.llmAction}`);
       }
     }
-
-    return { content: lines.join('\n'), isError: false };
   }
-}
 
-registerTool(new WatcherDigestTool());
+  return { content: lines.join('\n'), isError: false };
+}