@vellumai/assistant 0.3.0

package/src/tools/reminder/reminder-store.ts

@@ -0,0 +1,148 @@
+import { and, asc, eq, lte } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb } from '../../memory/db.js';
+import { reminders } from '../../memory/schema.js';
+
+export interface ReminderRow {
+  id: string;
+  label: string;
+  message: string;
+  fireAt: number;
+  mode: 'notify' | 'execute';
+  status: 'pending' | 'firing' | 'fired' | 'cancelled';
+  firedAt: number | null;
+  conversationId: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export function insertReminder(params: {
+  label: string;
+  message: string;
+  fireAt: number;
+  mode: 'notify' | 'execute';
+}): ReminderRow {
+  const db = getDb();
+  const id = uuid();
+  const now = Date.now();
+  const row: ReminderRow = {
+    id,
+    label: params.label,
+    message: params.message,
+    fireAt: params.fireAt,
+    mode: params.mode,
+    status: 'pending',
+    firedAt: null,
+    conversationId: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  db.insert(reminders).values(row).run();
+  return row;
+}
+
+export function getReminder(id: string): ReminderRow | null {
+  const db = getDb();
+  const row = db.select().from(reminders).where(eq(reminders.id, id)).get();
+  if (!row) return null;
+  return parseRow(row);
+}
+
+export function listReminders(options?: { pendingOnly?: boolean }): ReminderRow[] {
+  const db = getDb();
+  const conditions = options?.pendingOnly ? eq(reminders.status, 'pending') : undefined;
+  const rows = db
+    .select()
+    .from(reminders)
+    .where(conditions)
+    .orderBy(asc(reminders.fireAt))
+    .all();
+  return rows.map(parseRow);
+}
+
+export function cancelReminder(id: string): boolean {
+  const db = getDb();
+  const now = Date.now();
+  const result = db
+    .update(reminders)
+    .set({ status: 'cancelled', updatedAt: now })
+    .where(and(eq(reminders.id, id), eq(reminders.status, 'pending')))
+    .run() as unknown as { changes?: number };
+  return (result.changes ?? 0) > 0;
+}
+
+/**
+ * Claim all pending reminders where fire_at <= now.
+ * Transitions to 'firing' (not 'fired') so the reminder stays recoverable
+ * if execution fails. Call completeReminder() after successful delivery
+ * to move to the terminal 'fired' state.
+ */
+export function claimDueReminders(now: number): ReminderRow[] {
+  const db = getDb();
+  const candidates = db
+    .select()
+    .from(reminders)
+    .where(and(eq(reminders.status, 'pending'), lte(reminders.fireAt, now)))
+    .orderBy(asc(reminders.fireAt))
+    .all();
+
+  const claimed: ReminderRow[] = [];
+  for (const row of candidates) {
+    const result = db
+      .update(reminders)
+      .set({ status: 'firing', firedAt: now, updatedAt: now })
+      .where(and(eq(reminders.id, row.id), eq(reminders.status, 'pending')))
+      .run() as unknown as { changes?: number };
+
+    if ((result.changes ?? 0) === 0) continue;
+
+    claimed.push(parseRow({
+      ...row,
+      status: 'firing',
+      firedAt: now,
+      updatedAt: now,
+    }));
+  }
+  return claimed;
+}
+
+/** Mark a claimed reminder as successfully delivered. */
+export function completeReminder(id: string): void {
+  const db = getDb();
+  db.update(reminders)
+    .set({ status: 'fired', updatedAt: Date.now() })
+    .where(and(eq(reminders.id, id), eq(reminders.status, 'firing')))
+    .run();
+}
+
+/** Revert a claimed reminder back to pending so it can be retried. */
+export function failReminder(id: string): void {
+  const db = getDb();
+  db.update(reminders)
+    .set({ status: 'pending', firedAt: null, updatedAt: Date.now() })
+    .where(and(eq(reminders.id, id), eq(reminders.status, 'firing')))
+    .run();
+}
+
+export function setReminderConversationId(id: string, conversationId: string): void {
+  const db = getDb();
+  db.update(reminders)
+    .set({ conversationId, updatedAt: Date.now() })
+    .where(eq(reminders.id, id))
+    .run();
+}
+
+function parseRow(row: typeof reminders.$inferSelect): ReminderRow {
+  return {
+    id: row.id,
+    label: row.label,
+    message: row.message,
+    fireAt: row.fireAt,
+    mode: row.mode as ReminderRow['mode'],
+    status: row.status as ReminderRow['status'],
+    firedAt: row.firedAt,
+    conversationId: row.conversationId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/tools/reminder/reminder.ts

@@ -0,0 +1,80 @@
+import type { ToolExecutionResult } from '../types.js';
+import { formatLocalDate } from '../../schedule/schedule-store.js';
+import {
+  insertReminder,
+  listReminders,
+  cancelReminder,
+} from './reminder-store.js';
+
+// ── Exported execute functions ──────────────────────────────────────
+
+export function executeReminderCreate(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,
+  };
+}
+
+export function executeReminderList(): 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 };
+}
+
+export function executeReminderCancel(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 };
+}

package/src/tools/schedule/create.ts

@@ -0,0 +1,81 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { createSchedule, isValidCronExpression, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+import { normalizeScheduleSyntax } from '../../schedule/recurrence-types.js';
+import { validateRruleSetLines } from '../../schedule/recurrence-engine.js';
+
+export async function executeScheduleCreate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const name = input.name 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 (!message || typeof message !== 'string') {
+    return { content: 'Error: message is required and must be a string', isError: true };
+  }
+
+  // Resolve syntax and expression from new or legacy fields
+  const resolved = normalizeScheduleSyntax({
+    syntax: input.syntax as 'cron' | 'rrule' | undefined,
+    expression: input.expression as string | undefined,
+    legacyCronExpression: input.cron_expression as string | undefined,
+  });
+
+  if (!resolved) {
+    return { content: 'Error: expression (or cron_expression) is required', isError: true };
+  }
+
+  // Syntax-specific pre-validation for actionable error messages
+  if (resolved.syntax === 'cron' && !isValidCronExpression(resolved.expression)) {
+    return { content: `Error: Invalid cron expression: "${resolved.expression}"`, isError: true };
+  }
+  if (resolved.syntax === 'rrule') {
+    if (typeof resolved.expression !== 'string') {
+      return { content: 'Error: expression must be a string', isError: true };
+    }
+    const setError = validateRruleSetLines(resolved.expression);
+    if (setError) {
+      return {
+        content: `Error: ${setError}. Supported line types: DTSTART, RRULE, RDATE, EXDATE, EXRULE.`,
+        isError: true,
+      };
+    }
+  }
+
+  try {
+    const job = createSchedule({
+      name,
+      cronExpression: resolved.expression,
+      timezone,
+      message,
+      enabled,
+      syntax: resolved.syntax,
+      expression: resolved.expression,
+    });
+
+    const scheduleDescription = job.syntax === 'rrule'
+      ? job.expression
+      : describeCronExpression(job.cronExpression);
+
+    const nextRunDate = formatLocalDate(job.nextRunAt);
+    return {
+      content: [
+        `Schedule created successfully.`,
+        `  Name: ${job.name}`,
+        `  Syntax: ${job.syntax}`,
+        `  Schedule: ${scheduleDescription}${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 };
+  }
+}

package/src/tools/schedule/delete.ts

@@ -0,0 +1,28 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { deleteSchedule, getSchedule } from '../../schedule/schedule-store.js';
+
+export async function executeScheduleDelete(
+  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,
+  };
+}

package/src/tools/schedule/list.ts

@@ -0,0 +1,69 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { listSchedules, getSchedule, getScheduleRuns, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+import { hasSetConstructs } from '../../schedule/recurrence-engine.js';
+
+function describeSchedule(job: { syntax: string; expression: string; cronExpression: string }): string {
+  if (job.syntax === 'rrule') {
+    const label = hasSetConstructs(job.expression) ? '[RRULE set] ' : '';
+    return `${label}${job.expression}`;
+  }
+  return describeCronExpression(job.cronExpression);
+}
+
+export async function executeScheduleList(
+  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}`,
+      `  Syntax: ${job.syntax}`,
+      `  Expression: ${job.expression}`,
+      `  Schedule: ${describeSchedule(job)}${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} ([${job.syntax}] ${describeSchedule(job)}) — next: ${next}`);
+  }
+
+  return { content: lines.join('\n'), isError: false };
+}

package/src/tools/schedule/update.ts

@@ -0,0 +1,97 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { updateSchedule, formatLocalDate, describeCronExpression } from '../../schedule/schedule-store.js';
+import { normalizeScheduleSyntax, detectScheduleSyntax, type ScheduleSyntax } from '../../schedule/recurrence-types.js';
+import { validateRruleSetLines } from '../../schedule/recurrence-engine.js';
+
+export async function executeScheduleUpdate(
+  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.timezone !== undefined) updates.timezone = input.timezone;
+  if (input.message !== undefined) updates.message = input.message;
+  if (input.enabled !== undefined) updates.enabled = input.enabled;
+
+  // Auto-detect syntax when expression changes without explicit syntax
+  const hasExpression = input.expression !== undefined || input.cron_expression !== undefined;
+  if (hasExpression || input.syntax !== undefined) {
+    const resolved = normalizeScheduleSyntax({
+      syntax: input.syntax as 'cron' | 'rrule' | undefined,
+      expression: input.expression as string | undefined,
+      legacyCronExpression: input.cron_expression as string | undefined,
+    });
+    if (resolved) {
+      updates.syntax = resolved.syntax;
+      updates.expression = resolved.expression;
+    } else if (input.expression !== undefined) {
+      updates.expression = input.expression;
+      const detected = detectScheduleSyntax(input.expression as string);
+      if (detected) updates.syntax = detected;
+    } else if (input.cron_expression !== undefined) {
+      updates.cronExpression = input.cron_expression;
+    }
+    // When only syntax is provided (no expression), normalizeScheduleSyntax returns null
+    // but we still need to persist the explicit syntax value.
+    if (input.syntax !== undefined && updates.syntax === undefined) {
+      updates.syntax = input.syntax;
+    }
+  }
+
+  if (Object.keys(updates).length === 0) {
+    return { content: 'Error: No updates provided. Specify at least one field to update.', isError: true };
+  }
+
+  // Set-aware pre-validation for RRULE expressions
+  const effectiveSyntax = updates.syntax as string | undefined;
+  const effectiveExpr = (updates.expression as string | undefined) ?? (updates.cronExpression as string | undefined);
+  if (effectiveExpr && typeof effectiveExpr === 'string' && (effectiveSyntax === 'rrule' || /^(DTSTART|RRULE:)/m.test(effectiveExpr))) {
+    const setError = validateRruleSetLines(effectiveExpr);
+    if (setError) {
+      return {
+        content: `Error: ${setError}. Supported line types: DTSTART, RRULE, RDATE, EXDATE, EXRULE.`,
+        isError: true,
+      };
+    }
+  }
+
+  try {
+    const job = updateSchedule(jobId, updates as {
+      name?: string;
+      cronExpression?: string;
+      timezone?: string | null;
+      message?: string;
+      enabled?: boolean;
+      syntax?: ScheduleSyntax;
+      expression?: string;
+    });
+
+    if (!job) {
+      return { content: `Error: Schedule not found: ${jobId}`, isError: true };
+    }
+
+    const scheduleDescription = job.syntax === 'rrule'
+      ? job.expression
+      : describeCronExpression(job.cronExpression);
+
+    return {
+      content: [
+        `Schedule updated successfully.`,
+        `  Name: ${job.name}`,
+        `  Syntax: ${job.syntax}`,
+        `  Schedule: ${scheduleDescription}${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 };
+  }
+}

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 };
+}