vellum 0.0.16 → 0.2.0

package/src/tools/reminder/reminder.ts

@@ -0,0 +1,153 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { formatLocalDate } from '../../schedule/schedule-store.js';
+import {
+  insertReminder,
+  listReminders,
+  cancelReminder,
+} from './reminder-store.js';
+
+function executeReminder(input: Record<string, unknown>): ToolExecutionResult {
+  const action = input.action as string | undefined;
+  if (!action) {
+    return { content: 'Error: action is required', isError: true };
+  }
+
+  switch (action) {
+    case 'create':
+      return createAction(input);
+    case 'list':
+      return listAction();
+    case 'cancel':
+      return cancelAction(input);
+    default:
+      return {
+        content: `Error: Unknown action "${action}". Valid actions: create, list, cancel`,
+        isError: true,
+      };
+  }
+}
+
+function createAction(input: Record<string, unknown>): ToolExecutionResult {
+  const fireAtStr = input.fire_at as string | undefined;
+  const label = input.label as string | undefined;
+  const message = input.message as string | undefined;
+  const mode = (input.mode as string | undefined) ?? 'notify';
+
+  if (!fireAtStr) {
+    return { content: 'Error: fire_at is required for create', isError: true };
+  }
+  if (!label) {
+    return { content: 'Error: label is required for create', isError: true };
+  }
+  if (!message) {
+    return { content: 'Error: message is required for create', isError: true };
+  }
+  if (mode !== 'notify' && mode !== 'execute') {
+    return { content: 'Error: mode must be "notify" or "execute"', isError: true };
+  }
+
+  // Require strict ISO 8601 with timezone offset or Z to avoid ambiguous parsing
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(fireAtStr)) {
+    return { content: `Error: Invalid timestamp "${fireAtStr}". Use ISO 8601 format with timezone (e.g. "2025-03-15T09:00:00Z" or "2025-03-15T09:00:00-05:00").`, isError: true };
+  }
+  const fireAt = new Date(fireAtStr).getTime();
+  if (isNaN(fireAt)) {
+    return { content: `Error: Invalid timestamp "${fireAtStr}". Use ISO 8601 format with timezone (e.g. "2025-03-15T09:00:00Z").`, isError: true };
+  }
+  if (fireAt <= Date.now()) {
+    return { content: 'Error: fire_at must be in the future', isError: true };
+  }
+
+  const reminder = insertReminder({ label, message, fireAt, mode });
+
+  return {
+    content: `Reminder created.\n  ID: ${reminder.id}\n  Label: ${reminder.label}\n  Fires at: ${formatLocalDate(reminder.fireAt)}\n  Mode: ${reminder.mode}`,
+    isError: false,
+  };
+}
+
+function listAction(): ToolExecutionResult {
+  const all = listReminders();
+  if (all.length === 0) {
+    return { content: 'No reminders found.', isError: false };
+  }
+
+  const lines = all.map((r) => {
+    const status = r.status === 'fired'
+      ? `fired at ${formatLocalDate(r.firedAt!)}`
+      : r.status === 'firing'
+        ? 'firing'
+        : r.status;
+    return `  - [${r.id}] "${r.label}" — ${formatLocalDate(r.fireAt)} (${r.mode}, ${status})`;
+  });
+
+  return { content: `Reminders:\n${lines.join('\n')}`, isError: false };
+}
+
+function cancelAction(input: Record<string, unknown>): ToolExecutionResult {
+  const reminderId = input.reminder_id as string | undefined;
+  if (!reminderId) {
+    return { content: 'Error: reminder_id is required for cancel', isError: true };
+  }
+
+  const ok = cancelReminder(reminderId);
+  if (!ok) {
+    return { content: `Error: Reminder "${reminderId}" not found or already fired/cancelled.`, isError: true };
+  }
+
+  return { content: `Reminder "${reminderId}" cancelled.`, isError: false };
+}
+
+class ReminderTool implements Tool {
+  name = 'reminder';
+  description = 'Create, list, or cancel one-time time-based reminders. Reminders fire at a specific future time and either notify the user or execute a message through the assistant. Use this ONLY when the user wants a time-triggered notification (e.g. "remind me at 3pm", "remind me in 2 hours"). Do NOT use this for "add to my tasks" or "add to my queue" — use task_list_add for those requests.';
+  category = 'reminder';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['create', 'list', 'cancel'],
+            description: 'Reminder action',
+          },
+          fire_at: {
+            type: 'string',
+            description: 'ISO 8601 timestamp for when the reminder should fire (required for create)',
+          },
+          label: {
+            type: 'string',
+            description: 'Human-readable label (required for create)',
+          },
+          message: {
+            type: 'string',
+            description: 'Content shown in notification (notify) or sent to agent (execute). Required for create.',
+          },
+          mode: {
+            type: 'string',
+            enum: ['notify', 'execute'],
+            description: 'How the reminder fires. Defaults to notify.',
+          },
+          reminder_id: {
+            type: 'string',
+            description: 'Reminder ID (required for cancel)',
+          },
+        },
+        required: ['action'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    return executeReminder(input);
+  }
+}
+
+export const reminderTool = new ReminderTool();

package/src/tools/schedule/create.ts

@@ -0,0 +1,86 @@
+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 { createSchedule, isValidCronExpression, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+
+class ScheduleCreateTool implements Tool {
+  name = 'schedule_create';
+  description = 'Create a recurring scheduled automation that sends a message at a cron interval. ONLY use this when the user explicitly wants something to run on a schedule (e.g. "every day at 9am", "weekly on Mondays", "every hour"). Do NOT use this for "add to my tasks" or "add to my queue" — use task_list_add for those requests instead.';
+  category = 'schedule';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'A human-readable name for the scheduled task',
+          },
+          cron_expression: {
+            type: 'string',
+            description: 'A cron expression (e.g. "0 9 * * 1-5" for weekdays at 9am). Supports standard 5-field cron syntax.',
+          },
+          timezone: {
+            type: 'string',
+            description: 'IANA timezone (e.g. "America/Los_Angeles"). Defaults to system timezone if omitted.',
+          },
+          message: {
+            type: 'string',
+            description: 'The message to send to the assistant when the schedule triggers',
+          },
+          enabled: {
+            type: 'boolean',
+            description: 'Whether the job is enabled immediately. Defaults to true.',
+          },
+        },
+        required: ['name', 'cron_expression', 'message'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const name = input.name as string;
+    const cronExpression = input.cron_expression as string;
+    const timezone = (input.timezone as string) ?? null;
+    const message = input.message as string;
+    const enabled = (input.enabled as boolean) ?? true;
+
+    if (!name || typeof name !== 'string') {
+      return { content: 'Error: name is required and must be a string', isError: true };
+    }
+    if (!cronExpression || typeof cronExpression !== 'string') {
+      return { content: 'Error: cron_expression is required and must be a string', isError: true };
+    }
+    if (!message || typeof message !== 'string') {
+      return { content: 'Error: message is required and must be a string', isError: true };
+    }
+    if (!isValidCronExpression(cronExpression)) {
+      return { content: `Error: Invalid cron expression: "${cronExpression}"`, isError: true };
+    }
+
+    try {
+      const job = createSchedule({ name, cronExpression, timezone, message, enabled });
+      const nextRunDate = formatLocalDate(job.nextRunAt);
+      return {
+        content: [
+          `Schedule created successfully.`,
+          `  Name: ${job.name}`,
+          `  Schedule: ${describeCronExpression(job.cronExpression)}${job.timezone ? ` (${job.timezone})` : ''}`,
+          `  Enabled: ${job.enabled}`,
+          `  Next run: ${nextRunDate}`,
+        ].join('\n'),
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error creating schedule: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new ScheduleCreateTool());

package/src/tools/schedule/delete.ts

@@ -0,0 +1,54 @@
+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 { deleteSchedule, getSchedule } from '../../schedule/schedule-store.js';
+
+class ScheduleDeleteTool implements Tool {
+  name = 'schedule_delete';
+  description = 'Delete a recurring scheduled automation and all its run history';
+  category = 'schedule';
+  defaultRiskLevel = RiskLevel.High;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          job_id: {
+            type: 'string',
+            description: 'The ID of the schedule to delete',
+          },
+        },
+        required: ['job_id'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const jobId = input.job_id as string;
+    if (!jobId || typeof jobId !== 'string') {
+      return { content: 'Error: job_id is required', isError: true };
+    }
+
+    // Fetch the job first for the confirmation message
+    const job = getSchedule(jobId);
+    if (!job) {
+      return { content: `Error: Schedule not found: ${jobId}`, isError: true };
+    }
+
+    const deleted = deleteSchedule(jobId);
+    if (!deleted) {
+      return { content: `Error: Failed to delete schedule: ${jobId}`, isError: true };
+    }
+
+    return {
+      content: `Schedule deleted: "${job.name}"`,
+      isError: false,
+    };
+  }
+}
+
+registerTool(new ScheduleDeleteTool());

package/src/tools/schedule/list.ts

@@ -0,0 +1,88 @@
+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 { listSchedules, getSchedule, getScheduleRuns, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+
+class ScheduleListTool implements Tool {
+  name = 'schedule_list';
+  description = 'List recurring scheduled automations (cron jobs), or show details and recent runs for a specific one. For the user\'s task queue, use task_list_show instead.';
+  category = 'schedule';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          enabled_only: {
+            type: 'boolean',
+            description: 'When true, only show enabled jobs. Defaults to false.',
+          },
+          job_id: {
+            type: 'string',
+            description: 'If provided, show detailed info and recent runs for this specific job.',
+          },
+        },
+        required: [],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const jobId = input.job_id as string | undefined;
+    const enabledOnly = (input.enabled_only as boolean) ?? false;
+
+    // Detail mode for a specific job
+    if (jobId) {
+      const job = getSchedule(jobId);
+      if (!job) {
+        return { content: `Error: Schedule not found: ${jobId}`, isError: true };
+      }
+
+      const runs = getScheduleRuns(jobId, 5);
+      const lines = [
+        `Schedule: ${job.name}`,
+        `  Schedule: ${describeCronExpression(job.cronExpression)}${job.timezone ? ` (${job.timezone})` : ''}`,
+        `  Enabled: ${job.enabled}`,
+        `  Message: ${job.message}`,
+        `  Next run: ${formatLocalDate(job.nextRunAt)}`,
+        `  Last run: ${job.lastRunAt ? formatLocalDate(job.lastRunAt) : 'never'}`,
+        `  Last status: ${job.lastStatus ?? 'n/a'}`,
+        `  Retry count: ${job.retryCount}`,
+        `  Created: ${formatLocalDate(job.createdAt)}`,
+      ];
+
+      if (runs.length > 0) {
+        lines.push('', `Recent runs (${runs.length}):`);
+        for (const run of runs) {
+          const dur = run.durationMs != null ? `${run.durationMs}ms` : 'n/a';
+          lines.push(`  - ${run.status} at ${formatLocalDate(run.startedAt)} (${dur})${run.error ? ` error: ${run.error}` : ''}`);
+        }
+      } else {
+        lines.push('', 'No runs yet.');
+      }
+
+      return { content: lines.join('\n'), isError: false };
+    }
+
+    // List mode
+    const jobs = listSchedules({ enabledOnly });
+    if (jobs.length === 0) {
+      return { content: 'No schedules found.', isError: false };
+    }
+
+    const lines = [`Schedules (${jobs.length}):`];
+    for (const job of jobs) {
+      const status = job.enabled ? 'enabled' : 'disabled';
+      const next = job.enabled ? formatLocalDate(job.nextRunAt) : 'n/a';
+      lines.push(`  - [${status}] ${job.name} (${describeCronExpression(job.cronExpression)}) — next: ${next}`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  }
+}
+
+registerTool(new ScheduleListTool());

package/src/tools/schedule/update.ts

@@ -0,0 +1,97 @@
+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 { updateSchedule, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+
+class ScheduleUpdateTool implements Tool {
+  name = 'schedule_update';
+  description = 'Update an existing recurring scheduled automation (cron expression, message, name, or enabled state)';
+  category = 'schedule';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          job_id: {
+            type: 'string',
+            description: 'The ID of the schedule to update',
+          },
+          name: {
+            type: 'string',
+            description: 'New name for the job',
+          },
+          cron_expression: {
+            type: 'string',
+            description: 'New cron expression',
+          },
+          timezone: {
+            type: 'string',
+            description: 'New IANA timezone',
+          },
+          message: {
+            type: 'string',
+            description: 'New message to send when triggered',
+          },
+          enabled: {
+            type: 'boolean',
+            description: 'Enable or disable the job',
+          },
+        },
+        required: ['job_id'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const jobId = input.job_id as string;
+    if (!jobId || typeof jobId !== 'string') {
+      return { content: 'Error: job_id is required', isError: true };
+    }
+
+    const updates: Record<string, unknown> = {};
+    if (input.name !== undefined) updates.name = input.name;
+    if (input.cron_expression !== undefined) updates.cronExpression = input.cron_expression;
+    if (input.timezone !== undefined) updates.timezone = input.timezone;
+    if (input.message !== undefined) updates.message = input.message;
+    if (input.enabled !== undefined) updates.enabled = input.enabled;
+
+    if (Object.keys(updates).length === 0) {
+      return { content: 'Error: No updates provided. Specify at least one field to update.', isError: true };
+    }
+
+    try {
+      const job = updateSchedule(jobId, updates as {
+        name?: string;
+        cronExpression?: string;
+        timezone?: string | null;
+        message?: string;
+        enabled?: boolean;
+      });
+
+      if (!job) {
+        return { content: `Error: Schedule not found: ${jobId}`, isError: true };
+      }
+
+      return {
+        content: [
+          `Schedule updated successfully.`,
+          `  Name: ${job.name}`,
+          `  Schedule: ${describeCronExpression(job.cronExpression)}${job.timezone ? ` (${job.timezone})` : ''}`,
+          `  Enabled: ${job.enabled}`,
+          `  Next run: ${job.enabled ? formatLocalDate(job.nextRunAt) : 'n/a (disabled)'}`,
+        ].join('\n'),
+        isError: false,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: `Error updating schedule: ${msg}`, isError: true };
+    }
+  }
+}
+
+registerTool(new ScheduleUpdateTool());

package/src/tools/shared/filesystem/edit-engine.ts

@@ -0,0 +1,56 @@
+import { findAllMatches, adjustIndentation } from '../../filesystem/fuzzy-match.js';
+import type { MatchMethod } from '../../filesystem/fuzzy-match.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type EditEngineResult =
+  | { ok: true; updatedContent: string; matchCount: number; matchMethod: MatchMethod; similarity: number; actualOld: string; actualNew: string }
+  | { ok: false; reason: 'not_found' }
+  | { ok: false; reason: 'ambiguous'; matchCount: number };
+
+// ---------------------------------------------------------------------------
+// Engine
+// ---------------------------------------------------------------------------
+
+/**
+ * Core match/replace logic shared by both sandbox and host edit tools,
+ * and by the executor's preview-diff computation.
+ *
+ * This function is pure — it takes file content and edit parameters and
+ * returns the result without performing any I/O.
+ */
+export function applyEdit(
+  content: string,
+  oldString: string,
+  newString: string,
+  replaceAll: boolean,
+): EditEngineResult {
+  if (replaceAll) {
+    const firstIndex = content.indexOf(oldString);
+    if (firstIndex === -1) {
+      return { ok: false, reason: 'not_found' };
+    }
+    const count = content.split(oldString).length - 1;
+    const updatedContent = content.split(oldString).join(newString);
+    return { ok: true, updatedContent, matchCount: count, matchMethod: 'exact', similarity: 1, actualOld: oldString, actualNew: newString };
+  }
+
+  // Single-match path: cascading exact -> whitespace -> fuzzy
+  const matches = findAllMatches(content, oldString);
+  if (matches.length === 0) {
+    return { ok: false, reason: 'not_found' };
+  }
+  if (matches.length > 1) {
+    return { ok: false, reason: 'ambiguous', matchCount: matches.length };
+  }
+
+  const match = matches[0];
+  const adjustedNewString = match.method !== 'exact'
+    ? adjustIndentation(oldString, match.matched, newString)
+    : newString;
+
+  const updatedContent = content.slice(0, match.start) + adjustedNewString + content.slice(match.end);
+  return { ok: true, updatedContent, matchCount: 1, matchMethod: match.method, similarity: match.similarity, actualOld: match.matched, actualNew: adjustedNewString };
+}

package/src/tools/shared/filesystem/errors.ts

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// Error codes
+// ---------------------------------------------------------------------------
+
+export type FsErrorCode =
+  | 'INVALID_PATH'
+  | 'PATH_OUT_OF_BOUNDS'
+  | 'PATH_NOT_ABSOLUTE'
+  | 'NOT_FOUND'
+  | 'NOT_A_FILE'
+  | 'SIZE_LIMIT_EXCEEDED'
+  | 'MATCH_NOT_FOUND'
+  | 'MATCH_AMBIGUOUS'
+  | 'IO_ERROR';
+
+// ---------------------------------------------------------------------------
+// Error type
+// ---------------------------------------------------------------------------
+
+export interface FsError {
+  code: FsErrorCode;
+  message: string;
+  /** The path that caused the error, when applicable. */
+  path?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export function invalidPath(path: string, reason: string): FsError {
+  return { code: 'INVALID_PATH', message: reason, path };
+}
+
+export function pathOutOfBounds(path: string, boundary: string): FsError {
+  return {
+    code: 'PATH_OUT_OF_BOUNDS',
+    message: `Path "${path}" resolves outside the allowed boundary "${boundary}"`,
+    path,
+  };
+}
+
+export function pathNotAbsolute(path: string): FsError {
+  return {
+    code: 'PATH_NOT_ABSOLUTE',
+    message: `Path must be absolute: ${path}`,
+    path,
+  };
+}
+
+export function notFound(path: string): FsError {
+  return { code: 'NOT_FOUND', message: `File not found: ${path}`, path };
+}
+
+export function notAFile(path: string): FsError {
+  return { code: 'NOT_A_FILE', message: `Not a regular file: ${path}`, path };
+}
+
+export function sizeLimitExceeded(path: string, detail: string): FsError {
+  return {
+    code: 'SIZE_LIMIT_EXCEEDED',
+    message: detail,
+    path,
+  };
+}
+
+export function matchNotFound(path: string): FsError {
+  return {
+    code: 'MATCH_NOT_FOUND',
+    message: `old_string not found in ${path}`,
+    path,
+  };
+}
+
+export function matchAmbiguous(path: string, count: number): FsError {
+  return {
+    code: 'MATCH_AMBIGUOUS',
+    message: `old_string appears ${count} times in ${path}. Provide more surrounding context to make it unique, or set replace_all to true.`,
+    path,
+  };
+}
+
+export function ioError(path: string, detail: string): FsError {
+  return { code: 'IO_ERROR', message: detail, path };
+}