vellum 0.2.0 → 0.2.2

package/src/schedule/recurrence-engine.ts

@@ -0,0 +1,138 @@
+import { Cron } from 'croner';
+import { rrulestr, RRuleSet } from 'rrule';
+import type { ScheduleSyntax } from './recurrence-types.js';
+
+export interface ScheduleSpec {
+  syntax: ScheduleSyntax;
+  expression: string;
+  timezone?: string | null;
+}
+
+const SUPPORTED_RRULE_PREFIXES = ['DTSTART', 'RRULE:', 'RDATE', 'EXDATE', 'EXRULE'];
+
+function normalizeRruleExpression(expression: string): string {
+  // Handle escaped newlines from JSON transport
+  return expression.replace(/\\n/g, '\n').trim();
+}
+
+function parseRruleLines(expression: string): string[] {
+  return normalizeRruleExpression(expression)
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(Boolean);
+}
+
+function validateRruleLines(lines: string[]): string | null {
+  let hasInclusion = false;
+  let hasDtstart = false;
+
+  for (const line of lines) {
+    const upper = line.toUpperCase();
+    if (!SUPPORTED_RRULE_PREFIXES.some(p => upper.startsWith(p))) {
+      return `Unsupported recurrence line: ${line}`;
+    }
+    if (upper.startsWith('DTSTART')) hasDtstart = true;
+    if (upper.startsWith('RRULE:') || upper.startsWith('RDATE')) hasInclusion = true;
+  }
+
+  if (!hasDtstart) return 'RRULE expression must include DTSTART for deterministic scheduling';
+  if (!hasInclusion) return 'RRULE expression must include at least one RRULE or RDATE';
+  return null;
+}
+
+/**
+ * Detect whether an RRULE expression contains set constructs (RDATE, EXDATE,
+ * EXRULE, or multiple RRULE lines) that require RRuleSet parsing.
+ */
+export function hasSetConstructs(expression: string): boolean {
+  const lines = parseRruleLines(expression);
+  let rruleCount = 0;
+  for (const line of lines) {
+    const upper = line.toUpperCase();
+    if (upper.startsWith('RDATE') || upper.startsWith('EXDATE') || upper.startsWith('EXRULE')) return true;
+    if (upper.startsWith('RRULE:')) rruleCount++;
+  }
+  return rruleCount > 1;
+}
+
+/**
+ * Validate RRULE set lines in an expression. Returns null if valid, or an
+ * actionable error string describing the problem. This is intended for tool
+ * layers that want to surface a specific error message before calling the
+ * store.
+ */
+export function validateRruleSetLines(expression: string): string | null {
+  const lines = parseRruleLines(expression);
+  return validateRruleLines(lines);
+}
+
+/**
+ * Validate a schedule expression. Returns true if the expression is valid
+ * for the given syntax, false otherwise.
+ */
+export function isValidScheduleExpression(spec: ScheduleSpec): boolean {
+  try {
+    if (spec.syntax === 'cron') {
+      new Cron(spec.expression, { maxRuns: 0 });
+      return true;
+    }
+
+    if (spec.syntax === 'rrule') {
+      const lines = parseRruleLines(spec.expression);
+      const error = validateRruleLines(lines);
+      if (error) return false;
+
+      const normalized = normalizeRruleExpression(spec.expression);
+      const tzid = spec.timezone ?? undefined;
+      if (hasSetConstructs(normalized)) {
+        rrulestr(normalized, { forceset: true, tzid });
+      } else {
+        rrulestr(normalized, { tzid });
+      }
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compute the next run timestamp (epoch ms) for a schedule expression.
+ * Throws if no future runs exist.
+ */
+export function computeNextRunAt(spec: ScheduleSpec, nowMs?: number): number {
+  const now = nowMs ?? Date.now();
+
+  if (spec.syntax === 'cron') {
+    const cron = new Cron(spec.expression, {
+      timezone: spec.timezone ?? undefined,
+    });
+    const next = cron.nextRun(new Date(now));
+    if (!next) {
+      throw new Error(`Cron expression "${spec.expression}" has no upcoming runs`);
+    }
+    return next.getTime();
+  }
+
+  if (spec.syntax === 'rrule') {
+    const normalized = normalizeRruleExpression(spec.expression);
+    const lines = parseRruleLines(normalized);
+    const error = validateRruleLines(lines);
+    if (error) throw new Error(error);
+
+    const useSet = hasSetConstructs(normalized);
+    const tzid = spec.timezone ?? undefined;
+    const parsed = useSet
+      ? (rrulestr(normalized, { forceset: true, tzid }) as RRuleSet)
+      : rrulestr(normalized, { tzid });
+    const next = parsed.after(new Date(now));
+    if (!next) {
+      throw new Error(`RRULE expression has no upcoming runs after ${new Date(now).toISOString()}`);
+    }
+    return next.getTime();
+  }
+
+  throw new Error(`Unsupported schedule syntax: ${spec.syntax}`);
+}

package/src/schedule/recurrence-types.ts

@@ -0,0 +1,67 @@
+export type ScheduleSyntax = 'cron' | 'rrule';
+
+/**
+ * Detect whether an expression string is cron or RRULE syntax.
+ * Returns null for ambiguous or invalid expressions.
+ */
+export function detectScheduleSyntax(expression: string): ScheduleSyntax | null {
+  if (!expression || typeof expression !== 'string') return null;
+  const trimmed = expression.trim();
+  if (!trimmed) return null;
+
+  // RRULE detection: starts with RRULE:, DTSTART, or contains FREQ=
+  if (/^(RRULE:|DTSTART)/m.test(trimmed) || /FREQ=/i.test(trimmed)) {
+    return 'rrule';
+  }
+
+  // Cron detection: 5 space-separated fields
+  const fields = trimmed.split(/\s+/);
+  if (fields.length === 5) {
+    // Basic sanity check: each field should match cron-like characters
+    const cronFieldPattern = /^[\d\*\/\-\,\?LW#]+$/;
+    if (fields.every(f => cronFieldPattern.test(f))) {
+      return 'cron';
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalize schedule syntax from tool/API inputs.
+ * Resolution order:
+ * 1. If explicit `syntax` is provided, use it
+ * 2. If `expression` is provided, auto-detect from expression
+ * 3. If `legacyCronExpression` is provided, treat as cron
+ * 4. Return null if nothing resolved
+ */
+export function normalizeScheduleSyntax(input: {
+  syntax?: ScheduleSyntax;
+  expression?: string;
+  legacyCronExpression?: string;
+}): { syntax: ScheduleSyntax; expression: string } | null {
+  // Explicit syntax + expression
+  if (input.syntax && input.expression) {
+    return { syntax: input.syntax, expression: input.expression };
+  }
+
+  // Auto-detect from expression
+  if (input.expression) {
+    const detected = detectScheduleSyntax(input.expression);
+    if (detected) {
+      return { syntax: detected, expression: input.expression };
+    }
+    // If we have an explicit syntax but couldn't detect, trust the explicit syntax
+    if (input.syntax) {
+      return { syntax: input.syntax, expression: input.expression };
+    }
+    return null;
+  }
+
+  // Legacy cron_expression fallback
+  if (input.legacyCronExpression) {
+    return { syntax: 'cron', expression: input.legacyCronExpression };
+  }
+
+  return null;
+}

package/src/schedule/schedule-store.ts

@@ -2,12 +2,16 @@ import { and, asc, desc, eq, lte } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { Cron } from 'croner';
 import { getDb } from '../memory/db.js';
-import { cronJobs, cronRuns } from '../memory/schema.js';
+import { scheduleJobs, scheduleRuns } from '../memory/schema.js';
+import { computeNextRunAt as computeNextRunAtEngine, isValidScheduleExpression } from './recurrence-engine.js';
+import type { ScheduleSyntax } from './recurrence-types.js';
 
 export interface ScheduleJob {
   id: string;
   name: string;
   enabled: boolean;
+  syntax: ScheduleSyntax;
+  expression: string;
   cronExpression: string;
   timezone: string | null;
   message: string;
@@ -48,7 +52,7 @@ export function computeNextRunAt(cronExpression: string, timezone?: string | nul
   });
   const next = cron.nextRun();
   if (!next) {
-    throw new Error(`Cron expression "${cronExpression}" has no upcoming runs`);
+    throw new Error(`Schedule expression "${cronExpression}" has no upcoming runs`);
   }
   return next.getTime();
 }
@@ -60,9 +64,16 @@ export function createSchedule(params: {
   message: string;
   enabled?: boolean;
   createdBy?: string;
+  syntax?: ScheduleSyntax;
+  expression?: string;
 }): ScheduleJob {
-  if (!isValidCronExpression(params.cronExpression)) {
-    throw new Error(`Invalid cron expression: "${params.cronExpression}"`);
+  // Resolve syntax and expression: prefer explicit values, fall back to cron default
+  const syntax: ScheduleSyntax = params.syntax ?? 'cron';
+  const expression = params.expression ?? params.cronExpression;
+
+  const spec = { syntax, expression, timezone: params.timezone };
+  if (!isValidScheduleExpression(spec)) {
+    throw new Error(`Invalid ${syntax} expression: "${expression}"`);
   }
 
   const db = getDb();
@@ -70,13 +81,14 @@ export function createSchedule(params: {
   const now = Date.now();
   const enabled = params.enabled ?? true;
   const timezone = params.timezone ?? null;
-  const nextRunAt = enabled ? computeNextRunAt(params.cronExpression, timezone) : 0;
+  const nextRunAt = enabled ? computeNextRunAtEngine(spec) : 0;
 
   const row = {
     id,
     name: params.name,
     enabled,
-    cronExpression: params.cronExpression,
+    cronExpression: expression,
+    scheduleSyntax: syntax,
     timezone,
     message: params.message,
     nextRunAt,
@@ -88,16 +100,16 @@ export function createSchedule(params: {
     updatedAt: now,
   };
 
-  db.insert(cronJobs).values(row).run();
-  return row;
+  db.insert(scheduleJobs).values(row).run();
+  return parseJobRow(row);
 }
 
 export function getSchedule(id: string): ScheduleJob | null {
   const db = getDb();
   const row = db
     .select()
-    .from(cronJobs)
-    .where(eq(cronJobs.id, id))
+    .from(scheduleJobs)
+    .where(eq(scheduleJobs.id, id))
     .get();
   if (!row) return null;
   return parseJobRow(row);
@@ -105,12 +117,12 @@ export function getSchedule(id: string): ScheduleJob | null {
 
 export function listSchedules(options?: { enabledOnly?: boolean }): ScheduleJob[] {
   const db = getDb();
-  const conditions = options?.enabledOnly ? eq(cronJobs.enabled, true) : undefined;
+  const conditions = options?.enabledOnly ? eq(scheduleJobs.enabled, true) : undefined;
   const rows = db
     .select()
-    .from(cronJobs)
+    .from(scheduleJobs)
     .where(conditions)
-    .orderBy(asc(cronJobs.nextRunAt))
+    .orderBy(asc(scheduleJobs.nextRunAt))
     .all();
   return rows.map(parseJobRow);
 }
@@ -123,90 +135,120 @@ export function updateSchedule(
     timezone?: string | null;
     message?: string;
     enabled?: boolean;
+    syntax?: ScheduleSyntax;
+    expression?: string;
   },
 ): ScheduleJob | null {
   const db = getDb();
-  const existing = db.select().from(cronJobs).where(eq(cronJobs.id, id)).get();
+  const existing = db.select().from(scheduleJobs).where(eq(scheduleJobs.id, id)).get();
   if (!existing) return null;
 
-  if (updates.cronExpression && !isValidCronExpression(updates.cronExpression)) {
-    throw new Error(`Invalid cron expression: "${updates.cronExpression}"`);
+  // Resolve the effective syntax and expression after this update
+  const newSyntax = updates.syntax ?? (existing.scheduleSyntax as ScheduleSyntax) ?? 'cron';
+  const newExpr = updates.expression ?? updates.cronExpression ?? existing.cronExpression;
+  const newTimezone = updates.timezone !== undefined ? updates.timezone : existing.timezone;
+  const newEnabled = updates.enabled !== undefined ? updates.enabled : existing.enabled;
+
+  // Validate if expression or syntax changed
+  if (updates.expression !== undefined || updates.cronExpression !== undefined || updates.syntax !== undefined) {
+    const spec = { syntax: newSyntax, expression: newExpr, timezone: newTimezone };
+    if (!isValidScheduleExpression(spec)) {
+      throw new Error(`Invalid ${newSyntax} expression: "${newExpr}"`);
+    }
   }
 
   const now = Date.now();
   const set: Record<string, unknown> = { updatedAt: now };
 
   if (updates.name !== undefined) set.name = updates.name;
-  if (updates.cronExpression !== undefined) set.cronExpression = updates.cronExpression;
+  if (updates.cronExpression !== undefined || updates.expression !== undefined) set.cronExpression = newExpr;
+  if (updates.syntax !== undefined) set.scheduleSyntax = newSyntax;
   if (updates.timezone !== undefined) set.timezone = updates.timezone;
   if (updates.message !== undefined) set.message = updates.message;
   if (updates.enabled !== undefined) set.enabled = updates.enabled;
 
-  const newExpr = updates.cronExpression ?? existing.cronExpression;
-  const newTimezone = updates.timezone !== undefined ? updates.timezone : existing.timezone;
-  const newEnabled = updates.enabled !== undefined ? updates.enabled : existing.enabled;
-
+  // Recompute nextRunAt if schedule timing may have changed
   if (
     updates.cronExpression !== undefined ||
+    updates.expression !== undefined ||
+    updates.syntax !== undefined ||
     updates.timezone !== undefined ||
     updates.enabled !== undefined
   ) {
-    set.nextRunAt = newEnabled ? computeNextRunAt(newExpr, newTimezone) : 0;
+    const spec = { syntax: newSyntax, expression: newExpr, timezone: newTimezone };
+    set.nextRunAt = newEnabled ? computeNextRunAtEngine(spec) : 0;
   }
 
-  db.update(cronJobs).set(set).where(eq(cronJobs.id, id)).run();
+  db.update(scheduleJobs).set(set).where(eq(scheduleJobs.id, id)).run();
 
   return getSchedule(id);
 }
 
 export function deleteSchedule(id: string): boolean {
   const db = getDb();
-  const result = db.delete(cronJobs).where(eq(cronJobs.id, id)).run() as unknown as { changes?: number };
+  const result = db.delete(scheduleJobs).where(eq(scheduleJobs.id, id)).run() as unknown as { changes?: number };
   return (result.changes ?? 0) > 0;
 }
 
 /**
- * Claim due schedules atomically. For each candidate where enabled=true and
- * next_run_at <= now, we advance next_run_at using optimistic locking on the
- * old value to prevent double-claiming by concurrent ticks.
+ * Claim due recurrence schedules atomically. For each candidate where
+ * enabled=true and next_run_at <= now, we advance next_run_at using
+ * optimistic locking on the old value to prevent double-claiming by
+ * concurrent ticks. Works for both cron and RRULE syntax.
  */
 export function claimDueSchedules(now: number): ScheduleJob[] {
   const db = getDb();
   const candidates = db
     .select()
-    .from(cronJobs)
-    .where(and(eq(cronJobs.enabled, true), lte(cronJobs.nextRunAt, now)))
-    .orderBy(asc(cronJobs.nextRunAt))
+    .from(scheduleJobs)
+    .where(and(eq(scheduleJobs.enabled, true), lte(scheduleJobs.nextRunAt, now)))
+    .orderBy(asc(scheduleJobs.nextRunAt))
     .all();
 
   const claimed: ScheduleJob[] = [];
   for (const row of candidates) {
-    let newNextRunAt: number;
+    let newNextRunAt: number | null;
+    let exhausted = false;
     try {
-      newNextRunAt = computeNextRunAt(row.cronExpression, row.timezone);
+      const syntax = (row.scheduleSyntax as ScheduleSyntax) ?? 'cron';
+      newNextRunAt = computeNextRunAtEngine({
+        syntax,
+        expression: row.cronExpression,
+        timezone: row.timezone,
+      });
     } catch {
-      // Expression has no future runs — skip
-      continue;
+      // Finite schedule with no future runs — still claim the current due
+      // run but disable the schedule so it doesn't fire again.
+      newNextRunAt = null;
+      exhausted = true;
     }
 
     // Optimistic lock: only update if nextRunAt hasn't changed
+    const updates: Record<string, unknown> = {
+      lastRunAt: now,
+      updatedAt: now,
+    };
+    if (exhausted) {
+      updates.nextRunAt = 0;
+      updates.enabled = false;
+    } else {
+      updates.nextRunAt = newNextRunAt!;
+    }
+
     const result = db
-      .update(cronJobs)
-      .set({
-        nextRunAt: newNextRunAt,
-        lastRunAt: now,
-        updatedAt: now,
-      })
-      .where(and(eq(cronJobs.id, row.id), eq(cronJobs.nextRunAt, row.nextRunAt)))
+      .update(scheduleJobs)
+      .set(updates)
+      .where(and(eq(scheduleJobs.id, row.id), eq(scheduleJobs.nextRunAt, row.nextRunAt)))
       .run() as unknown as { changes?: number };
 
     if ((result.changes ?? 0) === 0) continue;
 
     claimed.push(parseJobRow({
       ...row,
-      nextRunAt: newNextRunAt,
+      nextRunAt: exhausted ? 0 : newNextRunAt!,
       lastRunAt: now,
       updatedAt: now,
+      enabled: exhausted ? false : row.enabled,
     }));
   }
   return claimed;
@@ -216,7 +258,7 @@ export function createScheduleRun(jobId: string, conversationId: string): string
   const db = getDb();
   const id = uuid();
   const now = Date.now();
-  db.insert(cronRuns).values({
+  db.insert(scheduleRuns).values({
     id,
     jobId,
     status: 'running',
@@ -238,12 +280,12 @@ export function completeScheduleRun(
   const db = getDb();
   const now = Date.now();
 
-  const run = db.select().from(cronRuns).where(eq(cronRuns.id, runId)).get();
+  const run = db.select().from(scheduleRuns).where(eq(scheduleRuns.id, runId)).get();
   if (!run) return;
 
   const durationMs = now - run.startedAt;
 
-  db.update(cronRuns)
+  db.update(scheduleRuns)
     .set({
       status: result.status,
       finishedAt: now,
@@ -251,23 +293,23 @@ export function completeScheduleRun(
       output: result.output?.slice(0, 10_000) ?? null,
       error: result.error?.slice(0, 2000) ?? null,
     })
-    .where(eq(cronRuns.id, runId))
+    .where(eq(scheduleRuns.id, runId))
     .run();
 
   // Update the parent job's lastStatus and retryCount
   if (result.status === 'error') {
     // Increment retry count
-    const job = db.select().from(cronJobs).where(eq(cronJobs.id, run.jobId)).get();
+    const job = db.select().from(scheduleJobs).where(eq(scheduleJobs.id, run.jobId)).get();
     if (job) {
-      db.update(cronJobs)
+      db.update(scheduleJobs)
         .set({ lastStatus: 'error', retryCount: job.retryCount + 1, updatedAt: now })
-        .where(eq(cronJobs.id, run.jobId))
+        .where(eq(scheduleJobs.id, run.jobId))
         .run();
     }
   } else {
-    db.update(cronJobs)
+    db.update(scheduleJobs)
       .set({ lastStatus: 'ok', retryCount: 0, updatedAt: now })
-      .where(eq(cronJobs.id, run.jobId))
+      .where(eq(scheduleJobs.id, run.jobId))
       .run();
   }
 }
@@ -276,9 +318,9 @@ export function getScheduleRuns(jobId: string, limit?: number): ScheduleRun[] {
   const db = getDb();
   const rows = db
     .select()
-    .from(cronRuns)
-    .where(eq(cronRuns.jobId, jobId))
-    .orderBy(desc(cronRuns.createdAt))
+    .from(scheduleRuns)
+    .where(eq(scheduleRuns.jobId, jobId))
+    .orderBy(desc(scheduleRuns.createdAt))
     .limit(limit ?? 10)
     .all();
   return rows.map(parseRunRow);
@@ -296,7 +338,8 @@ export function formatLocalDate(timestamp: number): string {
 }
 
 // Convert a cron expression to a human-readable description.
-// Uses the croner library to parse the expression and inspect its pattern fields.
+// Only applicable to cron syntax; RRULE schedules should display the
+// raw expression text instead.
 //
 // Examples:
 //   "* * * * *"     -> "Every minute"
@@ -418,11 +461,13 @@ export function describeCronExpression(expr: string): string {
   }
 }
 
-function parseJobRow(row: typeof cronJobs.$inferSelect): ScheduleJob {
+function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
   return {
     id: row.id,
     name: row.name,
     enabled: row.enabled,
+    syntax: (row.scheduleSyntax as ScheduleSyntax) ?? 'cron',
+    expression: row.cronExpression,
     cronExpression: row.cronExpression,
     timezone: row.timezone,
     message: row.message,
@@ -436,7 +481,7 @@ function parseJobRow(row: typeof cronJobs.$inferSelect): ScheduleJob {
   };
 }
 
-function parseRunRow(row: typeof cronRuns.$inferSelect): ScheduleRun {
+function parseRunRow(row: typeof scheduleRuns.$inferSelect): ScheduleRun {
   return {
     id: row.id,
     jobId: row.jobId,

package/src/schedule/scheduler.ts

@@ -5,6 +5,7 @@ import {
   createScheduleRun,
   completeScheduleRun,
 } from './schedule-store.js';
+import { hasSetConstructs } from './recurrence-engine.js';
 import { claimDueReminders, completeReminder, failReminder, setReminderConversationId } from '../tools/reminder/reminder-store.js';
 import { runWatchersOnce, type WatcherNotifier, type WatcherEscalator } from '../watcher/engine.js';
 
@@ -73,19 +74,20 @@ async function runScheduleOnce(
   const now = Date.now();
   let processed = 0;
 
-  // ── Cron jobs ───────────────────────────────────────────────────────
+  // ── Recurrence schedules (cron + RRULE) ─────────────────────────────
   const jobs = claimDueSchedules(now);
   for (const job of jobs) {
     // Check if message is a task invocation (run_task:<task_id>)
     const taskMatch = job.message.match(/^run_task:(\S+)$/);
     if (taskMatch) {
       const taskId = taskMatch[1];
+      const isRruleSet = job.syntax === 'rrule' && hasSetConstructs(job.expression);
       try {
-        log.info({ jobId: job.id, name: job.name, taskId }, 'Executing scheduled task');
+        log.info({ jobId: job.id, name: job.name, taskId, syntax: job.syntax, expression: job.expression, isRruleSet }, 'Executing scheduled task');
         const { runTask } = await import('../tasks/task-runner.js');
         const result = await runTask(
           { taskId, workingDir: process.cwd() },
-          processMessage as (conversationId: string, message: string) => Promise<void>,
+          processMessage as (conversationId: string, message: string, taskRunId: string) => Promise<void>,
         );
 
         // Track the schedule run using the task's conversation
@@ -99,7 +101,7 @@ async function runScheduleOnce(
         processed += 1;
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        log.warn({ err, jobId: job.id, name: job.name, taskId }, 'Scheduled task execution failed');
+        log.warn({ err, jobId: job.id, name: job.name, taskId, syntax: job.syntax, expression: job.expression, isRruleSet }, 'Scheduled task execution failed');
         // Create a fallback conversation for the schedule run record
         const fallbackConversation = createConversation(`Schedule: ${job.name}`);
         const runId = createScheduleRun(job.id, fallbackConversation.id);
@@ -110,16 +112,17 @@ async function runScheduleOnce(
 
     const conversation = createConversation(`Schedule: ${job.name}`);
     const runId = createScheduleRun(job.id, conversation.id);
+    const isRruleSetMsg = job.syntax === 'rrule' && hasSetConstructs(job.expression);
 
     try {
-      log.info({ jobId: job.id, name: job.name, conversationId: conversation.id }, 'Executing schedule');
+      log.info({ jobId: job.id, name: job.name, syntax: job.syntax, expression: job.expression, isRruleSet: isRruleSetMsg, conversationId: conversation.id }, 'Executing schedule');
       await processMessage(conversation.id, job.message);
       completeScheduleRun(runId, { status: 'ok' });
       notifySchedule({ id: job.id, name: job.name });
       processed += 1;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      log.warn({ err, jobId: job.id, name: job.name }, 'Schedule execution failed');
+      log.warn({ err, jobId: job.id, name: job.name, syntax: job.syntax, expression: job.expression, isRruleSet: isRruleSetMsg }, 'Schedule execution failed');
       completeScheduleRun(runId, { status: 'error', error: message });
     }
   }

package/src/security/oauth2.ts

@@ -6,6 +6,9 @@
  */
 
 import { randomBytes, createHash } from 'node:crypto';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('oauth2');
 
 // ---------------------------------------------------------------------------
 // Types
@@ -170,8 +173,19 @@ export async function startOAuth2Flow(
     });
 
     if (!tokenResp.ok) {
-      const body = await tokenResp.text().catch(() => '');
-      throw new Error(`OAuth2 token exchange failed (${tokenResp.status}): ${body}`);
+      const rawBody = await tokenResp.text().catch(() => '');
+      let safeDetail: Record<string, unknown> = {};
+      let errorCode = '';
+      try {
+        const parsed = JSON.parse(rawBody) as Record<string, unknown>;
+        if (parsed.error) { safeDetail.error = String(parsed.error); errorCode = String(parsed.error); }
+        if (parsed.error_description) safeDetail.error_description = String(parsed.error_description);
+      } catch {
+        safeDetail.error = '[non-JSON response]';
+      }
+      log.error({ status: tokenResp.status, ...safeDetail }, 'OAuth2 token exchange failed');
+      const detail = errorCode ? `HTTP ${tokenResp.status}: ${errorCode}` : `HTTP ${tokenResp.status}`;
+      throw new Error(`OAuth2 token exchange failed (${detail})`);
     }
 
     const tokenData = await tokenResp.json() as Record<string, unknown>;
@@ -225,8 +239,19 @@ export async function refreshOAuth2Token(
   });
 
   if (!resp.ok) {
-    const body = await resp.text().catch(() => '');
-    throw new Error(`OAuth2 token refresh failed (${resp.status}): ${body}`);
+    const rawBody = await resp.text().catch(() => '');
+    let safeDetail: Record<string, unknown> = {};
+    let errorCode = '';
+    try {
+      const parsed = JSON.parse(rawBody) as Record<string, unknown>;
+      if (parsed.error) { safeDetail.error = String(parsed.error); errorCode = String(parsed.error); }
+      if (parsed.error_description) safeDetail.error_description = String(parsed.error_description);
+    } catch {
+      safeDetail.error = '[non-JSON response]';
+    }
+    log.error({ status: resp.status, ...safeDetail }, 'OAuth2 token refresh failed');
+    const detail = errorCode ? `HTTP ${resp.status}: ${errorCode}` : `HTTP ${resp.status}`;
+    throw new Error(`OAuth2 token refresh failed (${detail})`);
   }
 
   const data = await resp.json() as Record<string, unknown>;