obol-ai 0.2.31 → 0.2.33

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.2.33
+- add agentic cron jobs with instructions field and update_event tool
+
+## 0.2.32
+- fix cron-parser v5 tz option, enforce cron_expr for recurring events
+
 ## 0.2.31
 - update readme: remove github/vercel from onboarding, remove vercel tool references
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obol-ai",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Self-evolving AI assistant that learns, remembers, and acts on its own. Persistent vector memory, self-rewriting personality, proactive heartbeats.",
   "main": "src/index.js",
   "bin": {

package/src/claude/prompt.js

@@ -161,11 +161,12 @@ Returns the tapped button label, or \`"timeout"\` if the user doesn't respond wi
 
 ### Scheduling (\`schedule_event\`, \`list_events\`, \`cancel_event\`)
 Schedule one-time or recurring reminders. The user gets a Telegram message each time an event fires.
-- \`schedule_event\` — schedule a reminder with title, due_at (ISO 8601), timezone (IANA), optional description. For recurring events add \`cron_expr\` (5-field cron), optional \`max_runs\` and \`ends_at\`.
+- \`schedule_event\` — schedule a reminder with title, due_at (ISO 8601), timezone (IANA), optional description
 - \`list_events\` — list pending/sent/cancelled/completed events
 - \`cancel_event\` — cancel a scheduled event by ID
 
-Cron examples: \`0 9 * * 1-5\` (weekdays 9am), \`0 8 * * 1\` (Mondays 8am), \`*/30 * * * *\` (every 30 min), \`0 0 1 * *\` (1st of month).
+**Recurring events:** use \`cron_expr\` (5-field cron). The system auto-reschedules after each fire — never chain one-time events manually.
+Examples: \`*/30 * * * *\` (every 30 min), \`0 9 * * 1-5\` (weekdays 9am), \`0 8 * * 1\` (Mondays 8am), \`0 0 1 * *\` (1st of month).
 
 When scheduling: always search memory first for the user's timezone/location. If no timezone found, ask the user or default to UTC. Parse natural language dates relative to the user's timezone.
 

package/src/claude/tools/scheduler.js

@@ -3,7 +3,15 @@ const { toUTC } = require('../utils');
 const definitions = [
   {
     name: 'schedule_event',
-    description: 'Schedule a one-time or recurring reminder/event. For recurring events, provide a cron_expr (standard 5-field cron: minute hour day-of-month month day-of-week). The user will receive a Telegram message each time it fires. Always search memory first for the user\'s timezone/location.',
+    description: `Schedule a one-time or recurring reminder/event. The user will receive a Telegram message each time it fires.
+
+For RECURRING events (e.g. "every 30 minutes", "daily at 9am", "every Monday"):
+- ALWAYS use cron_expr — do NOT schedule one-time events and chain them manually
+- cron_expr is a standard 5-field cron: minute hour day-of-month month day-of-week
+- Examples: "*/30 * * * *" (every 30 min), "0 9 * * 1-5" (weekdays 9am), "0 8 * * 1" (Mondays 8am)
+- The system will auto-reschedule after each fire — no need to re-schedule manually
+
+Always search memory first for the user's timezone/location.`,
     input_schema: {
       type: 'object',
       properties: {
@@ -11,9 +19,10 @@ const definitions = [
         due_at: { type: 'string', description: 'ISO 8601 datetime for the first fire time (e.g. 2026-02-25T15:00:00)' },
         timezone: { type: 'string', description: 'IANA timezone (e.g. Europe/Brussels, America/New_York). Default: UTC' },
         description: { type: 'string', description: 'Context or details about the event' },
-        cron_expr: { type: 'string', description: 'Cron expression for recurring events (5-field: "0 9 * * 1-5" = weekdays 9am). Omit for one-time events.' },
+        cron_expr: { type: 'string', description: 'Cron expression for recurring events (5-field). REQUIRED for any repeating schedule — do not omit and chain one-time events instead.' },
         max_runs: { type: 'number', description: 'Maximum number of times to fire (omit for unlimited)' },
         ends_at: { type: 'string', description: 'ISO 8601 datetime after which the recurring event stops' },
+        instructions: { type: 'string', description: 'LLM instructions to execute when the event fires. If set, the bot will run these as an agentic task instead of sending a plain reminder message. Use for automations like "check email", "fetch weather", etc.' },
       },
       required: ['title', 'due_at'],
     },
@@ -39,6 +48,23 @@ const definitions = [
       required: ['event_id'],
     },
   },
+  {
+    name: 'update_event',
+    description: 'Update fields on an existing scheduled event. Only provided fields are changed.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        event_id: { type: 'string', description: 'UUID of the event to update' },
+        title: { type: 'string' },
+        description: { type: 'string' },
+        instructions: { type: 'string', description: 'LLM instructions to execute when the event fires. Set to empty string to clear.' },
+        timezone: { type: 'string' },
+        cron_expr: { type: 'string' },
+        max_runs: { type: 'number' },
+      },
+      required: ['event_id'],
+    },
+  },
 ];
 
 const handlers = {
@@ -51,7 +77,7 @@ const handlers = {
     if (input.cron_expr) {
       try {
         const { parseExpression } = require('cron-parser');
-        parseExpression(input.cron_expr, { tz });
+        parseExpression(input.cron_expr, { timezone: tz });
       } catch (e) {
         return `Invalid cron expression "${input.cron_expr}": ${e.message}`;
       }
@@ -62,19 +88,21 @@ const handlers = {
     const event = await context.scheduler.add(
       context.chatId, input.title, utcDate, tz,
       input.description || null, input.cron_expr || null,
-      input.max_runs || null, endsAtUtc
+      input.max_runs || null, endsAtUtc, input.instructions || null
     );
     const displayTime = new Date(utcDate).toLocaleString('en-US', { timeZone: tz });
 
+    const mode = input.instructions ? 'agentic' : 'reminder';
+
     if (input.cron_expr) {
-      let result = `Recurring event scheduled: "${input.title}"\nFirst run: ${displayTime} (${tz})\nSchedule: ${input.cron_expr}`;
+      let result = `Recurring ${mode} scheduled: "${input.title}"\nFirst run: ${displayTime} (${tz})\nSchedule: ${input.cron_expr}`;
       if (input.max_runs) result += `\nMax runs: ${input.max_runs}`;
       if (input.ends_at) result += `\nEnds: ${new Date(endsAtUtc).toLocaleString('en-US', { timeZone: tz })}`;
       result += `\nID: ${event.id}`;
       return result;
     }
 
-    return `Scheduled: "${input.title}" for ${displayTime} (${tz}) — ID: ${event.id}`;
+    return `Scheduled ${mode}: "${input.title}" for ${displayTime} (${tz}) — ID: ${event.id}`;
   },
 
   async list_events(input, memory, context) {
@@ -86,6 +114,7 @@ const handlers = {
         id: e.id,
         title: e.title,
         description: e.description,
+        instructions: e.instructions || null,
         due_at: e.due_at,
         timezone: e.timezone,
         due_local: new Date(e.due_at).toLocaleString('en-US', { timeZone: e.timezone }),
@@ -108,6 +137,22 @@ const handlers = {
     if (!cancelled) return `Event not found or not yours: ${input.event_id}`;
     return `Cancelled: "${cancelled.title}"`;
   },
+
+  async update_event(input, memory, context) {
+    if (!context.scheduler) return 'Scheduler not available (Supabase not configured).';
+    const { event_id, ...rest } = input;
+    const fields = {};
+    if (rest.title !== undefined) fields.title = rest.title;
+    if (rest.description !== undefined) fields.description = rest.description;
+    if (rest.instructions !== undefined) fields.instructions = rest.instructions || null;
+    if (rest.timezone !== undefined) fields.timezone = rest.timezone;
+    if (rest.cron_expr !== undefined) fields.cron_expr = rest.cron_expr;
+    if (rest.max_runs !== undefined) fields.max_runs = rest.max_runs;
+    if (Object.keys(fields).length === 0) return 'No fields to update.';
+    const updated = await context.scheduler.update(event_id, fields);
+    if (!updated) return `Event not found or not yours: ${event_id}`;
+    return `Updated: "${updated.title}"`;
+  },
 };
 
 module.exports = { definitions, handlers };

package/src/db/migrate.js

@@ -197,6 +197,9 @@ async function migrate(supabaseConfig) {
     `DROP FUNCTION IF EXISTS match_obol_messages(VECTOR(384), FLOAT, INT, BIGINT);`,
     `DROP INDEX IF EXISTS obol_messages_embedding_idx;`,
     `ALTER TABLE obol_messages DROP COLUMN IF EXISTS embedding;`,
+
+    // Instructions column for agentic cron jobs
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS instructions TEXT;`,
   ];
 
   // Save SQL file for manual fallback

package/src/heartbeat.js

@@ -1,7 +1,17 @@
 const cron = require('node-cron');
 const { createScheduler } = require('./scheduler');
+const { getTenant } = require('./tenant');
 
-function setupHeartbeat(bot, supabaseConfig) {
+function makeFakeCtx(bot, chatId) {
+  return {
+    chat: { id: chatId },
+    reply: (text, opts) => bot.api.sendMessage(chatId, text, opts),
+    api: bot.api,
+  };
+}
+
+function setupHeartbeat(bot, config) {
+  const supabaseConfig = config?.supabase;
   let scheduler = null;
   if (supabaseConfig?.url && supabaseConfig?.serviceKey) {
     scheduler = createScheduler(supabaseConfig);
@@ -21,25 +31,20 @@ function setupHeartbeat(bot, supabaseConfig) {
       const dueEvents = await scheduler.getDue();
       for (const event of dueEvents) {
         try {
+          if (event.instructions) {
+            await runAgenticEvent(bot, config, event);
+          } else {
+            await sendReminderMessage(bot, event);
+          }
+
           const tz = event.timezone || 'UTC';
-          const dueLocal = new Date(event.due_at).toLocaleString('en-US', { timeZone: tz });
-          const isRecurring = !!event.cron_expr;
-          const prefix = isRecurring ? '🔄 *Recurring Reminder:*' : '⏰ *Reminder:*';
-          let text = `${prefix} ${event.title}`;
-          if (event.description) text += `\n${event.description}`;
-          text += `\n_${dueLocal} (${tz})_`;
-
-          await bot.api.sendMessage(event.chat_id, text, { parse_mode: 'Markdown' }).catch(() =>
-            bot.api.sendMessage(event.chat_id, `${isRecurring ? '🔄 Recurring Reminder' : '⏰ Reminder'}: ${event.title}${event.description ? '\n' + event.description : ''}`)
-          );
-
-          if (isRecurring) {
+          if (event.cron_expr) {
             await scheduler.reschedule(event.id, event.cron_expr, tz, event.run_count, event.max_runs, event.ends_at);
           } else {
             await scheduler.markSent(event.id);
           }
         } catch (e) {
-          console.error(`[scheduler] Failed to send event ${event.id}:`, e.message);
+          console.error(`[scheduler] Failed to process event ${event.id}:`, e.message);
         }
       }
     } catch (e) {
@@ -50,4 +55,36 @@ function setupHeartbeat(bot, supabaseConfig) {
   console.log('  ✅ Heartbeat running (every 1min)');
 }
 
+async function sendReminderMessage(bot, event) {
+  const tz = event.timezone || 'UTC';
+  const dueLocal = new Date(event.due_at).toLocaleString('en-US', { timeZone: tz });
+  const isRecurring = !!event.cron_expr;
+  const prefix = isRecurring ? '🔄 *Recurring Reminder:*' : '⏰ *Reminder:*';
+  let text = `${prefix} ${event.title}`;
+  if (event.description) text += `\n${event.description}`;
+  text += `\n_${dueLocal} (${tz})_`;
+
+  await bot.api.sendMessage(event.chat_id, text, { parse_mode: 'Markdown' }).catch(() =>
+    bot.api.sendMessage(event.chat_id, `${isRecurring ? '🔄 Recurring Reminder' : '⏰ Reminder'}: ${event.title}${event.description ? '\n' + event.description : ''}`)
+  );
+}
+
+async function runAgenticEvent(bot, config, event) {
+  const tenant = await getTenant(event.user_id, config);
+  const fakeCtx = makeFakeCtx(bot, event.chat_id);
+
+  const taskId = tenant.bg.spawn(
+    tenant.claude,
+    event.instructions,
+    fakeCtx,
+    tenant.memory,
+    null,
+    {}
+  );
+
+  if (taskId === null) {
+    await bot.api.sendMessage(event.chat_id, `⚠️ Could not run "${event.title}" — too many background tasks already running.`).catch(() => {});
+  }
+}
+
 module.exports = { setupHeartbeat };

package/src/index.js

@@ -37,7 +37,7 @@ async function main() {
   checkUpgradeNotify(bot).catch(() => {});
 
   if (config.heartbeat !== false) {
-    setupHeartbeat(bot, config.supabase);
+    setupHeartbeat(bot, config);
   }
 
   if (config.github) {

package/src/scheduler.js

@@ -10,7 +10,7 @@ function createScheduler(supabaseConfig, userId = 0) {
     'Prefer': 'return=representation',
   };
 
-  async function add(chatId, title, dueAt, timezone = 'UTC', description = null, cronExpr = null, maxRuns = null, endsAt = null) {
+  async function add(chatId, title, dueAt, timezone = 'UTC', description = null, cronExpr = null, maxRuns = null, endsAt = null, instructions = null) {
     const body = {
       user_id: userId,
       chat_id: chatId,
@@ -23,6 +23,7 @@ function createScheduler(supabaseConfig, userId = 0) {
     if (cronExpr) body.cron_expr = cronExpr;
     if (maxRuns != null) body.max_runs = maxRuns;
     if (endsAt) body.ends_at = endsAt;
+    if (instructions) body.instructions = instructions;
     const res = await fetch(`${url}/rest/v1/obol_events`, {
       method: 'POST',
       headers,
@@ -36,7 +37,7 @@ function createScheduler(supabaseConfig, userId = 0) {
   async function list(opts = {}) {
     const status = opts.status || 'pending';
     const limit = opts.limit || 20;
-    let fetchUrl = `${url}/rest/v1/obol_events?user_id=eq.${userId}&status=eq.${status}&order=due_at.asc&limit=${limit}&select=id,title,description,due_at,timezone,status,created_at,cron_expr,last_run_at,run_count,max_runs,ends_at`;
+    const fetchUrl = `${url}/rest/v1/obol_events?user_id=eq.${userId}&status=eq.${status}&order=due_at.asc&limit=${limit}&select=id,title,description,due_at,timezone,status,created_at,cron_expr,last_run_at,run_count,max_runs,ends_at`;
     const res = await fetch(fetchUrl, { headers });
     const data = await res.json();
     if (!res.ok) throw new Error(JSON.stringify(data));
@@ -56,7 +57,7 @@ function createScheduler(supabaseConfig, userId = 0) {
 
   async function getDue() {
     const now = new Date().toISOString();
-    const fetchUrl = `${url}/rest/v1/obol_events?status=eq.pending&due_at=lte.${now}&select=id,user_id,chat_id,title,description,due_at,timezone,cron_expr,run_count,max_runs,ends_at`;
+    const fetchUrl = `${url}/rest/v1/obol_events?status=eq.pending&due_at=lte.${now}&select=id,user_id,chat_id,title,description,due_at,timezone,cron_expr,run_count,max_runs,ends_at,instructions`;
     const res = await fetch(fetchUrl, { headers });
     const data = await res.json();
     if (!res.ok) throw new Error(JSON.stringify(data));
@@ -87,7 +88,7 @@ function createScheduler(supabaseConfig, userId = 0) {
     }
 
     try {
-      const nextDate = parseExpression(cronExpr, { currentDate: new Date(), tz: timezone || 'UTC' }).next().toDate();
+      const nextDate = parseExpression(cronExpr, { currentDate: new Date(), timezone: timezone || 'UTC' }).next().toDate();
 
       if (endsAt && nextDate > new Date(endsAt)) {
         return patch(eventId, { status: 'completed', run_count: newRunCount, last_run_at: new Date().toISOString() });
@@ -105,7 +106,18 @@ function createScheduler(supabaseConfig, userId = 0) {
     }
   }
 
-  return { add, list, cancel, getDue, markSent, reschedule };
+  async function update(eventId, fields) {
+    const res = await fetch(`${url}/rest/v1/obol_events?id=eq.${eventId}&user_id=eq.${userId}`, {
+      method: 'PATCH',
+      headers,
+      body: JSON.stringify(fields),
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(JSON.stringify(data));
+    return data[0];
+  }
+
+  return { add, list, cancel, getDue, markSent, reschedule, update };
 }
 
 module.exports = { createScheduler };