macroclaw 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/app.ts

@@ -1,7 +1,7 @@
 import type { Bot } from "grammy";
-import { CronScheduler } from "./cron";
 import { createLogger } from "./logger";
 import { type Claude, Orchestrator, type OrchestratorResponse } from "./orchestrator";
+import { Scheduler } from "./scheduler";
 import type { SpeechToText } from "./speech-to-text";
 import { createBot, downloadFile, sendFile, sendResponse } from "./telegram";
 
@@ -42,10 +42,10 @@ export class App {
 
   start() {
     log.info("Starting macroclaw...");
-    const cron = new CronScheduler(this.#config.workspace, {
+    const scheduler = new Scheduler(this.#config.workspace, {
       onJob: (name, prompt, model) => this.#orchestrator.handleCron(name, prompt, model),
     });
-    cron.start();
+    scheduler.start();
     this.#bot.api.setMyCommands([
       { command: "chatid", description: "Show current chat ID" },
       { command: "session", description: "Show current session ID" },

package/src/scheduler.test.ts

@@ -0,0 +1,423 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Scheduler } from "./scheduler";
+
+const TEST_DIR = join(import.meta.dir, "..", ".test-workspace-scheduler");
+const SCHEDULE_DIR = join(TEST_DIR, "data");
+const SCHEDULE_FILE = join(SCHEDULE_DIR, "schedule.json");
+
+function writeScheduleConfig(config: any) {
+	mkdirSync(SCHEDULE_DIR, { recursive: true });
+	writeFileSync(SCHEDULE_FILE, JSON.stringify(config));
+}
+
+function readScheduleConfig() {
+	return JSON.parse(readFileSync(SCHEDULE_FILE, "utf-8"));
+}
+
+function makeOnJob() {
+	return mock((_name: string, _prompt: string, _model?: string) => {});
+}
+
+// Build a cron expression that matches the current minute
+function currentMinuteCron(): string {
+	const now = new Date();
+	return `${now.getMinutes()} ${now.getHours()} * * *`;
+}
+
+// Build a cron expression that never matches now
+function nonMatchingCron(): string {
+	const now = new Date();
+	const otherMinute = (now.getMinutes() + 30) % 60;
+	return `${otherMinute} ${(now.getHours() + 12) % 24} * * *`;
+}
+
+// Build an ISO fireAt string N minutes in the past with timezone offset
+function minutesAgoFireAt(minutesAgo: number): string {
+	return toIsoWithOffset(new Date(Date.now() - minutesAgo * 60_000));
+}
+
+// Build an ISO fireAt string N days in the past with timezone offset
+function daysAgoFireAt(daysAgo: number): string {
+	return toIsoWithOffset(new Date(Date.now() - daysAgo * 24 * 60 * 60_000));
+}
+
+// Build an ISO fireAt string N minutes in the future with timezone offset
+function minutesFromNowFireAt(minutes: number): string {
+	return toIsoWithOffset(new Date(Date.now() + minutes * 60_000));
+}
+
+// Format a Date as ISO 8601 with +00:00 offset (not Z)
+function toIsoWithOffset(date: Date): string {
+	return date.toISOString().replace("Z", "+00:00");
+}
+
+// Build a fireAt string for ~30 seconds ago (within 60s window)
+function justNowFireAt(): string {
+	return toIsoWithOffset(new Date(Date.now() - 30_000));
+}
+
+beforeEach(() => {
+	mkdirSync(SCHEDULE_DIR, { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("Scheduler — cron jobs", () => {
+	it("calls onJob for matching cron job", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "test-job", cron: currentMinuteCron(), prompt: "do something" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("test-job", "do something", undefined);
+	});
+
+	it("does not call onJob for non-matching jobs", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "later", cron: nonMatchingCron(), prompt: "not now" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+	});
+
+	it("skips invalid cron expression and processes valid jobs", () => {
+		writeScheduleConfig({
+			jobs: [
+				{ name: "bad", cron: "invalid cron", prompt: "bad" },
+				{ name: "good", cron: currentMinuteCron(), prompt: "good" },
+			],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+		expect(onJob).toHaveBeenCalledWith("good", "good", undefined);
+	});
+
+	it("handles multiple matching jobs", () => {
+		writeScheduleConfig({
+			jobs: [
+				{ name: "first", cron: currentMinuteCron(), prompt: "first" },
+				{ name: "second", cron: currentMinuteCron(), prompt: "second" },
+			],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(2);
+		expect(onJob).toHaveBeenCalledWith("first", "first", undefined);
+		expect(onJob).toHaveBeenCalledWith("second", "second", undefined);
+	});
+
+	it("passes model override to onJob", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "smart", cron: currentMinuteCron(), prompt: "think hard", model: "opus" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("smart", "think hard", "opus");
+	});
+
+	it("never removes cron jobs after firing", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "keeper", cron: currentMinuteCron(), prompt: "stay" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+		expect(updated.jobs[0].name).toBe("keeper");
+	});
+});
+
+describe("Scheduler — fireAt jobs", () => {
+	it("fires one-shot job when fireAt is within 60s of now", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "now", fireAt: justNowFireAt(), prompt: "do it" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("now", "do it", undefined);
+	});
+
+	it("removes one-shot job after firing", () => {
+		writeScheduleConfig({
+			jobs: [
+				{ name: "once", fireAt: justNowFireAt(), prompt: "one-time" },
+				{ name: "recurring", cron: currentMinuteCron(), prompt: "forever" },
+			],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(2);
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+		expect(updated.jobs[0].name).toBe("recurring");
+	});
+
+	it("skips upcoming fireAt job (in the future)", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "later", fireAt: minutesFromNowFireAt(60), prompt: "not yet" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+		expect(updated.jobs[0].name).toBe("later");
+	});
+
+	it("fires missed one-shot job with missed prefix", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "reminder", fireAt: minutesAgoFireAt(3), prompt: "buy milk" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+		const call = onJob.mock.calls[0];
+		expect(call[0]).toBe("reminder");
+		expect(call[1]).toContain("[missed event, should have fired");
+		expect(call[1]).toContain("min ago at");
+		expect(call[1]).toContain("buy milk");
+	});
+
+	it("removes missed one-shot job after firing", () => {
+		writeScheduleConfig({
+			jobs: [
+				{ name: "missed", fireAt: minutesAgoFireAt(3), prompt: "do it" },
+				{ name: "keeper", cron: nonMatchingCron(), prompt: "stay" },
+			],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+		expect(updated.jobs[0].name).toBe("keeper");
+	});
+
+	it("fires one-shot job missed by 6 days (within week window)", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "recent", fireAt: daysAgoFireAt(6), prompt: "still valid" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+		const call = onJob.mock.calls[0];
+		expect(call[0]).toBe("recent");
+		expect(call[1]).toContain("[missed event, should have fired");
+		expect(call[1]).toContain("still valid");
+	});
+
+	it("discards stale one-shot job (older than a week) without firing", () => {
+		writeScheduleConfig({
+			jobs: [
+				{ name: "stale", fireAt: daysAgoFireAt(10), prompt: "too old" },
+				{ name: "keeper", cron: nonMatchingCron(), prompt: "stay" },
+			],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+		expect(updated.jobs[0].name).toBe("keeper");
+	});
+
+	it("passes model override for fireAt jobs", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "smart", fireAt: justNowFireAt(), prompt: "think", model: "opus" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledWith("smart", "think", "opus");
+	});
+
+	it("still fires when write-back of schedule.json fails", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "once", fireAt: justNowFireAt(), prompt: "fire" }],
+		});
+
+		const { chmodSync } = require("node:fs");
+		chmodSync(SCHEDULE_FILE, 0o444);
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		chmodSync(SCHEDULE_FILE, 0o644);
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("Scheduler — validation and edge cases", () => {
+	it("silently skips when schedule.json does not exist", () => {
+		rmSync(SCHEDULE_FILE, { force: true });
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+	});
+
+	it("does not call onJob on malformed JSON", () => {
+		writeFileSync(SCHEDULE_FILE, "not json{{{");
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+	});
+
+	it("does not call onJob when jobs is not an array", () => {
+		writeScheduleConfig({ jobs: "not-array" });
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+	});
+
+	it("skips job with both cron and fireAt", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "bad", cron: currentMinuteCron(), fireAt: justNowFireAt(), prompt: "oops" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+	});
+
+	it("skips fireAt with unparseable date", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "bad", fireAt: "not-a-date", prompt: "invalid" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).not.toHaveBeenCalled();
+
+		// Job should remain (not removed, just skipped)
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+	});
+
+	it("stop clears the interval", () => {
+		writeScheduleConfig({ jobs: [] });
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop(); // should not throw
+	});
+
+	it("only evaluates once per minute", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "once" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		expect(onJob).toHaveBeenCalledTimes(1);
+
+		// Start again with a new instance — the lastMinute tracker is per-instance
+		const onJob2 = makeOnJob();
+		const s2 = new Scheduler(TEST_DIR, { onJob: onJob2 });
+		s2.start();
+		s2.stop();
+
+		expect(onJob2).toHaveBeenCalledTimes(1);
+	});
+
+	it("does not write file when no one-shot jobs were processed", () => {
+		writeScheduleConfig({
+			jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope" }],
+		});
+
+		const onJob = makeOnJob();
+		const s = new Scheduler(TEST_DIR, { onJob });
+		s.start();
+		s.stop();
+
+		const updated = readScheduleConfig();
+		expect(updated.jobs).toHaveLength(1);
+	});
+});

package/src/scheduler.ts

@@ -0,0 +1,160 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CronExpressionParser } from "cron-parser";
+import { z } from "zod/v4";
+import { createLogger } from "./logger";
+
+const log = createLogger("scheduler");
+
+const jobSchema = z.object({
+	name: z.string(),
+	prompt: z.string(),
+	model: z.string().optional(),
+	cron: z.string().optional(),
+	fireAt: z.string().optional(),
+});
+
+const scheduleConfigSchema = z.object({
+	jobs: z.array(jobSchema),
+});
+
+type ScheduleConfig = z.infer<typeof scheduleConfigSchema>;
+type Job = z.infer<typeof jobSchema>;
+
+export interface SchedulerConfig {
+	onJob: (name: string, prompt: string, model?: string) => void;
+}
+
+const TICK_INTERVAL = 10_000; // 10 seconds
+const MAX_MISSED_MS = 7 * 24 * 60 * 60 * 1000; // 1 week
+
+export class Scheduler {
+	#lastMinute = -1;
+	#schedulePath: string;
+	#config: SchedulerConfig;
+	#timer: Timer | null = null;
+
+	constructor(workspace: string, config: SchedulerConfig) {
+		this.#schedulePath = join(workspace, "data", "schedule.json");
+		this.#config = config;
+	}
+
+	start(): void {
+		this.#tick();
+		this.#timer = setInterval(() => this.#tick(), TICK_INTERVAL);
+	}
+
+	stop(): void {
+		if (this.#timer) {
+			clearInterval(this.#timer);
+			this.#timer = null;
+		}
+	}
+
+	#tick(): void {
+		const now = new Date();
+		const currentMinute =
+			now.getMinutes() + now.getHours() * 60 + now.getDate() * 1440 + now.getMonth() * 43200;
+
+		// Only evaluate once per minute
+		if (currentMinute === this.#lastMinute) return;
+		this.#lastMinute = currentMinute;
+
+		let config: ScheduleConfig;
+		try {
+			const raw = readFileSync(this.#schedulePath, "utf-8");
+			const parsed = scheduleConfigSchema.safeParse(JSON.parse(raw));
+			if (!parsed.success) {
+				log.warn("schedule.json validation failed");
+				return;
+			}
+			config = parsed.data;
+		} catch (err) {
+			if (err instanceof Error && "code" in err && err.code === "ENOENT") return;
+			log.warn({ err: err instanceof Error ? err.message : err }, "Failed to read schedule.json");
+			return;
+		}
+
+		const removedIndices: number[] = [];
+
+		for (let i = 0; i < config.jobs.length; i++) {
+			const job = config.jobs[i];
+			if (job.cron && job.fireAt) {
+				log.warn({ name: job.name }, "Job has both cron and fireAt, skipping");
+				continue;
+			}
+			if (job.cron) {
+				this.#evaluateCronJob(job as Job & { cron: string }, now);
+			} else if (job.fireAt) {
+				try {
+					const result = this.#evaluateFireAtJob(job as Job & { fireAt: string }, now);
+					if (result === "remove") removedIndices.push(i);
+				} catch (err) {
+					log.warn({ name: job.name, fireAt: job.fireAt, err: err instanceof Error ? err.message : err }, "Failed to evaluate fireAt job");
+				}
+			} else {
+				log.warn({ name: job.name }, "Job has neither cron nor fireAt, skipping");
+			}
+		}
+
+		if (removedIndices.length > 0) {
+			for (let i = removedIndices.length - 1; i >= 0; i--) {
+				config.jobs.splice(removedIndices[i], 1);
+			}
+			try {
+				writeFileSync(this.#schedulePath, `${JSON.stringify(config, null, 2)}\n`);
+			} catch (err) {
+				log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write schedule.json");
+			}
+		}
+	}
+
+	#evaluateCronJob(job: { name: string; cron: string; prompt: string; model?: string }, now: Date): void {
+		try {
+			const interval = CronExpressionParser.parse(job.cron);
+			const prev = interval.prev();
+			const diff = Math.abs(now.getTime() - prev.getTime());
+			if (diff < 60_000) {
+				log.debug({ name: job.name, cron: job.cron }, "Cron job triggered");
+				this.#config.onJob(job.name, job.prompt, job.model);
+			}
+		} catch (err) {
+			log.warn({ cron: job.cron, err: err instanceof Error ? err.message : err }, "Invalid cron expression");
+		}
+	}
+
+	#evaluateFireAtJob(
+		job: { name: string; fireAt: string; prompt: string; model?: string },
+		now: Date,
+	): "remove" | "keep" {
+		const fireAt = new Date(job.fireAt);
+		if (Number.isNaN(fireAt.getTime())) {
+			log.warn({ name: job.name, fireAt: job.fireAt }, "Invalid fireAt date");
+			return "keep";
+		}
+
+		const diff = now.getTime() - fireAt.getTime();
+
+		if (diff < 0) {
+			// Upcoming — not yet due
+			return "keep";
+		}
+
+		if (diff < 60_000) {
+			log.debug({ name: job.name, fireAt: job.fireAt }, "One-shot job triggered");
+			this.#config.onJob(job.name, job.prompt, job.model);
+			return "remove";
+		}
+
+		if (diff <= MAX_MISSED_MS) {
+			const missedMinutes = Math.round(diff / 60_000);
+			const missedPrompt = `[missed event, should have fired ${missedMinutes} min ago at ${job.fireAt}] ${job.prompt}`;
+			log.info({ name: job.name, missedMinutes, fireAt: job.fireAt }, "Firing missed one-shot job");
+			this.#config.onJob(job.name, missedPrompt, job.model);
+			return "remove";
+		}
+
+		log.warn({ name: job.name, missedMinutes: Math.round(diff / 60_000) }, "Discarding stale one-shot job");
+		return "remove";
+	}
+}

package/workspace-template/.claude/skills/schedule/SKILL.md

@@ -18,26 +18,32 @@ Schedule a new event by adding it to `data/schedule.json`.
 
 1. Run `date` to get the current date and time
 2. Read `data/schedule.json` (create with `{"jobs": []}` if missing)
-3. Convert the user's request to a cron expression (see reference below)
+3. Determine job type:
+   - **Recurring** → convert to a cron expression (UTC). See reference below.
+   - **One-time** → compute an ISO 8601 timestamp with the user's timezone offset for `fireAt`
 4. **Be proactive about timing**: if the user says "next week" or "tomorrow" without a specific time, pick the best time based on what you know (their routine, calendar, context)
 5. Append the new job to the `jobs` array
 6. Write the updated file
 7. Confirm: what was scheduled, when it will fire, and offer to adjust
 
-## Natural language → cron
+## Natural language → job format
 
-Convert user intent to cron expressions. The user's timezone is in their profile (CLAUDE.md/USER.md) — convert to UTC for cron.
+The user's timezone is in their profile (CLAUDE.md/USER.md).
 
-Examples:
-- "in 5 minutes" → compute the exact minute/hour, use a one-shot with `recurring: false`
-- "tomorrow at 10am" → `0 8 14 3 *` (if user is UTC+2, March 13), `recurring: false`
-- "every morning" → `0 7 * * *` (adjust for timezone)
-- "every weekday at 9" → `0 7 * * 1-5` (UTC)
-- "next Monday" → specific date cron, `recurring: false`
-- "every 30 minutes" → `*/30 * * * *`
+**One-time events** use `fireAt` with the user's timezone offset:
+- "in 5 minutes" → compute exact time, e.g. `"fireAt": "2026-03-16T10:05:00+01:00"`
+- "tomorrow at 10am" → `"fireAt": "2026-03-14T10:00:00+01:00"`
+- "next Monday" → `"fireAt": "2026-03-17T09:00:00+01:00"` (pick a sensible time)
+
+**Recurring events** use `cron` in UTC:
+- "every morning" → `"cron": "0 7 * * *"` (adjust for timezone)
+- "every weekday at 9" → `"cron": "0 7 * * 1-5"` (UTC)
+- "every 30 minutes" → `"cron": "*/30 * * * *"`
 
 ## schedule.json format
 
+Two job types, discriminated by field:
+
 ```json
 {
   "jobs": [
@@ -54,9 +60,8 @@ Examples:
     },
     {
       "name": "dentist-reminder",
-      "cron": "0 8 15 3 *",
-      "prompt": "Reminder: call the dentist to reschedule your appointment",
-      "recurring": false
+      "fireAt": "2026-03-15T08:00:00+01:00",
+      "prompt": "Reminder: call the dentist to reschedule your appointment"
     }
   ]
 }
@@ -67,11 +72,13 @@ Examples:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `name` | yes | Short kebab-case identifier (e.g. `dentist-reminder`). Appears in the `[Context: cron/<name>]` prefix when fired. |
-| `cron` | yes | Standard cron expression (UTC). See reference below. |
+| `cron` | for recurring | Standard cron expression (UTC). See reference below. |
+| `fireAt` | for one-time | ISO 8601 timestamp, preferably with timezone offset (e.g. `2026-03-15T08:00:00+01:00`). Any format parseable by JavaScript `Date` works. |
 | `prompt` | yes | The message sent to the agent when the event fires. Write it as a natural instruction. |
-| `recurring` | no | Defaults to `true`. Set to `false` for one-time events — they're automatically removed after firing. |
 | `model` | no | Override the model. Use `haiku` for cheap checks, `opus` for complex reasoning. Omit for default. |
 
+Each job must have exactly one of `cron` or `fireAt` (not both).
+
 ## Cron expression reference (UTC)
 
 ```
@@ -95,5 +102,5 @@ Common patterns:
 
 - Changes are hot-reloaded — no restart needed
 - File location: `<workspace>/data/schedule.json`
-- One-shot events (`recurring: false`) are cleaned up automatically after firing
-- Missed one-shot events (e.g. service was down) are fired with a `[missed event]` prefix when the service restarts
+- One-shot events (`fireAt`) are cleaned up automatically after firing
+- Missed one-shot events (e.g. service was down) are fired with a `[missed event]` prefix when the service restarts (up to 7 days late)

package/src/cron.test.ts

@@ -1,340 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { CronScheduler } from "./cron";
-
-const TEST_DIR = join(import.meta.dir, "..", ".test-workspace-cron");
-const SCHEDULE_DIR = join(TEST_DIR, "data");
-const SCHEDULE_FILE = join(SCHEDULE_DIR, "schedule.json");
-
-function writeScheduleConfig(config: any) {
-  mkdirSync(SCHEDULE_DIR, { recursive: true });
-  writeFileSync(SCHEDULE_FILE, JSON.stringify(config));
-}
-
-function readScheduleConfig() {
-  return JSON.parse(readFileSync(SCHEDULE_FILE, "utf-8"));
-}
-
-function makeOnJob() {
-  return mock((_name: string, _prompt: string, _model?: string) => {});
-}
-
-// Build a cron expression that matches the current minute
-function currentMinuteCron(): string {
-  const now = new Date();
-  return `${now.getMinutes()} ${now.getHours()} * * *`;
-}
-
-// Build a cron expression that never matches now
-function nonMatchingCron(): string {
-  const now = new Date();
-  const otherMinute = (now.getMinutes() + 30) % 60;
-  return `${otherMinute} ${(now.getHours() + 12) % 24} * * *`;
-}
-
-// Build a cron expression that matched N minutes ago
-function minutesAgoCron(minutesAgo: number): string {
-  const past = new Date(Date.now() - minutesAgo * 60_000);
-  return `${past.getMinutes()} ${past.getHours()} ${past.getDate()} ${past.getMonth() + 1} *`;
-}
-
-beforeEach(() => {
-  mkdirSync(SCHEDULE_DIR, { recursive: true });
-});
-
-afterEach(() => {
-  rmSync(TEST_DIR, { recursive: true, force: true });
-});
-
-describe("CronScheduler", () => {
-  it("calls onJob for matching cron job", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "test-job", cron: currentMinuteCron(), prompt: "do something" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledWith("test-job", "do something", undefined);
-  });
-
-  it("does not call onJob for non-matching jobs", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "later", cron: nonMatchingCron(), prompt: "not now" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).not.toHaveBeenCalled();
-  });
-
-  it("silently skips when schedule.json does not exist", () => {
-    rmSync(SCHEDULE_FILE, { force: true });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).not.toHaveBeenCalled();
-  });
-
-  it("does not call onJob on malformed JSON", () => {
-    writeFileSync(SCHEDULE_FILE, "not json{{{");
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).not.toHaveBeenCalled();
-  });
-
-  it("does not call onJob when jobs is not an array", () => {
-    writeScheduleConfig({ jobs: "not-array" });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).not.toHaveBeenCalled();
-  });
-
-  it("skips invalid cron expression and processes valid jobs", () => {
-    writeScheduleConfig({
-      jobs: [
-        { name: "bad", cron: "invalid cron", prompt: "bad" },
-        { name: "good", cron: currentMinuteCron(), prompt: "good" },
-      ],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-    expect(onJob).toHaveBeenCalledWith("good", "good", undefined);
-  });
-
-  it("stop clears the interval", () => {
-    writeScheduleConfig({ jobs: [] });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop(); // should not throw
-  });
-
-  it("only evaluates once per minute", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "once" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-
-    // Start again with a new instance — the lastMinute tracker is per-instance
-    const onJob2 = makeOnJob();
-    const cron2 = new CronScheduler(TEST_DIR, { onJob: onJob2 });
-    cron2.start();
-    cron2.stop();
-
-    expect(onJob2).toHaveBeenCalledTimes(1);
-  });
-
-  it("handles multiple matching jobs", () => {
-    writeScheduleConfig({
-      jobs: [
-        { name: "first", cron: currentMinuteCron(), prompt: "first" },
-        { name: "second", cron: currentMinuteCron(), prompt: "second" },
-      ],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(2);
-    expect(onJob).toHaveBeenCalledWith("first", "first", undefined);
-    expect(onJob).toHaveBeenCalledWith("second", "second", undefined);
-  });
-
-  it("passes model override to onJob", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "smart", cron: currentMinuteCron(), prompt: "think hard", model: "opus" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledWith("smart", "think hard", "opus");
-  });
-
-  it("removes non-recurring job after it fires", () => {
-    writeScheduleConfig({
-      jobs: [
-        { name: "once", cron: currentMinuteCron(), prompt: "one-time", recurring: false },
-        { name: "always", cron: currentMinuteCron(), prompt: "forever" },
-      ],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(2);
-
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
-    expect(updated.jobs[0].name).toBe("always");
-  });
-
-  it("keeps recurring jobs (default behavior)", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "keeper", cron: currentMinuteCron(), prompt: "stay" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
-    expect(updated.jobs[0].name).toBe("keeper");
-  });
-
-  it("keeps jobs with recurring: true", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "explicit", cron: currentMinuteCron(), prompt: "stay", recurring: true }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
-  });
-
-  it("still fires job when write-back of schedule.json fails", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "fire", recurring: false }],
-    });
-
-    const { chmodSync } = require("node:fs");
-    chmodSync(SCHEDULE_FILE, 0o444);
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    chmodSync(SCHEDULE_FILE, 0o644);
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not write file when no non-recurring jobs fired", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
-  });
-});
-
-describe("missed non-recurring events", () => {
-  it("fires missed non-recurring job with missed prefix", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "reminder", cron: minutesAgoCron(3), prompt: "buy milk", recurring: false }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-    const call = onJob.mock.calls[0];
-    expect(call[0]).toBe("reminder");
-    expect(call[1]).toContain("[missed event, should have fired");
-    expect(call[1]).toContain("min ago at");
-    expect(call[1]).toContain("buy milk");
-  });
-
-  it("removes missed non-recurring job after firing", () => {
-    writeScheduleConfig({
-      jobs: [
-        { name: "missed", cron: minutesAgoCron(3), prompt: "do it", recurring: false },
-        { name: "keeper", cron: nonMatchingCron(), prompt: "stay" },
-      ],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
-    expect(updated.jobs[0].name).toBe("keeper");
-  });
-
-  it("does not fire missed recurring jobs", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "recurring", cron: minutesAgoCron(3), prompt: "repeat" }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).not.toHaveBeenCalled();
-  });
-
-  it("fires non-recurring job missed by more than 5 minutes", () => {
-    writeScheduleConfig({
-      jobs: [{ name: "old", cron: minutesAgoCron(10), prompt: "still fires", recurring: false }],
-    });
-
-    const onJob = makeOnJob();
-    const cron = new CronScheduler(TEST_DIR, { onJob });
-    cron.start();
-    cron.stop();
-
-    expect(onJob).toHaveBeenCalledTimes(1);
-    const call = onJob.mock.calls[0];
-    expect(call[0]).toBe("old");
-    expect(call[1]).toContain("[missed event, should have fired");
-    expect(call[1]).toContain("still fires");
-
-    const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(0);
-  });
-});

package/src/cron.ts

@@ -1,116 +0,0 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { CronExpressionParser } from "cron-parser";
-import { z } from "zod/v4";
-import { createLogger } from "./logger";
-
-const log = createLogger("cron");
-
-const cronJobSchema = z.object({
-  name: z.string(),
-  cron: z.string(),
-  prompt: z.string(),
-  recurring: z.boolean().optional(),
-  model: z.string().optional(),
-});
-
-const cronConfigSchema = z.object({
-  jobs: z.array(cronJobSchema),
-});
-
-type CronConfig = z.infer<typeof cronConfigSchema>;
-
-export interface CronSchedulerConfig {
-  onJob: (name: string, prompt: string, model?: string) => void;
-}
-
-const TICK_INTERVAL = 10_000; // 10 seconds
-
-export class CronScheduler {
-  #lastMinute = -1;
-  #schedulePath: string;
-  #config: CronSchedulerConfig;
-  #timer: Timer | null = null;
-
-  constructor(workspace: string, config: CronSchedulerConfig) {
-    this.#schedulePath = join(workspace, "data", "schedule.json");
-    this.#config = config;
-  }
-
-  start(): void {
-    this.#tick();
-    this.#timer = setInterval(() => this.#tick(), TICK_INTERVAL);
-  }
-
-  stop(): void {
-    if (this.#timer) {
-      clearInterval(this.#timer);
-      this.#timer = null;
-    }
-  }
-
-  #tick(): void {
-    const now = new Date();
-    const currentMinute = now.getMinutes() + now.getHours() * 60 + now.getDate() * 1440 + now.getMonth() * 43200;
-
-    // Only evaluate once per minute
-    if (currentMinute === this.#lastMinute) return;
-    this.#lastMinute = currentMinute;
-
-    let config: CronConfig;
-    try {
-      const raw = readFileSync(this.#schedulePath, "utf-8");
-      const parsed = cronConfigSchema.safeParse(JSON.parse(raw));
-      if (!parsed.success) {
-        log.warn("schedule.json: 'jobs' is not an array");
-        return;
-      }
-      config = parsed.data;
-    } catch (err) {
-      if (err instanceof Error && "code" in err && err.code === "ENOENT") return;
-      log.warn({ err: err instanceof Error ? err.message : err }, "Failed to read schedule.json");
-      return;
-    }
-
-    const firedNonRecurring: number[] = [];
-
-    for (let i = 0; i < config.jobs.length; i++) {
-      const job = config.jobs[i];
-      try {
-        const interval = CronExpressionParser.parse(job.cron);
-        const prev = interval.prev();
-        const diff = Math.abs(now.getTime() - prev.getTime());
-        // Match if the previous occurrence is within the current minute
-        if (diff < 60_000) {
-          log.debug({ name: job.name, cron: job.cron }, "Cron job triggered");
-          this.#config.onJob(job.name, job.prompt, job.model);
-          if (job.recurring === false) {
-            firedNonRecurring.push(i);
-          }
-        } else if (job.recurring === false && diff >= 60_000) {
-          // Non-recurring job in the past — fire regardless of how late
-          const missedMinutes = Math.round(diff / 60_000);
-          const firedAt = prev.toISOString();
-          const missedPrompt = `[missed event, should have fired ${missedMinutes} min ago at ${firedAt}] ${job.prompt}`;
-          log.info({ name: job.name, missedMinutes, firedAt }, "Firing missed non-recurring job");
-          this.#config.onJob(job.name, missedPrompt, job.model);
-          firedNonRecurring.push(i);
-        }
-      } catch (err) {
-        log.warn({ cron: job.cron, err: err instanceof Error ? err.message : err }, "Invalid cron expression");
-      }
-    }
-
-    // Remove fired non-recurring jobs (iterate in reverse to preserve indices)
-    if (firedNonRecurring.length > 0) {
-      for (let i = firedNonRecurring.length - 1; i >= 0; i--) {
-        config.jobs.splice(firedNonRecurring[i], 1);
-      }
-      try {
-        writeFileSync(this.#schedulePath, `${JSON.stringify(config, null, 2)}\n`);
-      } catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write schedule.json");
-      }
-    }
-  }
-}