macroclaw 0.17.0 → 0.18.0

package/README.md

@@ -118,7 +118,7 @@ Macroclaw follows a **thin platform, rich workspace** design:
 **Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
 - [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
 - [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
-- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
+- [`data/schedule.json`](workspace-template/data/schedule.json) — scheduled event definitions
 - [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
 
 ### Where does a new feature belong?

package/package.json

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

package/src/cron.test.ts

@@ -4,16 +4,16 @@ import { join } from "node:path";
 import { CronScheduler } from "./cron";
 
 const TEST_DIR = join(import.meta.dir, "..", ".test-workspace-cron");
-const CRON_DIR = join(TEST_DIR, ".macroclaw");
-const CRON_FILE = join(CRON_DIR, "cron.json");
+const SCHEDULE_DIR = join(TEST_DIR, "data");
+const SCHEDULE_FILE = join(SCHEDULE_DIR, "schedule.json");
 
-function writeCronConfig(config: any) {
-  mkdirSync(CRON_DIR, { recursive: true });
-  writeFileSync(CRON_FILE, JSON.stringify(config));
+function writeScheduleConfig(config: any) {
+  mkdirSync(SCHEDULE_DIR, { recursive: true });
+  writeFileSync(SCHEDULE_FILE, JSON.stringify(config));
 }
 
-function readCronConfig() {
-  return JSON.parse(readFileSync(CRON_FILE, "utf-8"));
+function readScheduleConfig() {
+  return JSON.parse(readFileSync(SCHEDULE_FILE, "utf-8"));
 }
 
 function makeOnJob() {
@@ -33,8 +33,14 @@ function nonMatchingCron(): string {
   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(CRON_DIR, { recursive: true });
+  mkdirSync(SCHEDULE_DIR, { recursive: true });
 });
 
 afterEach(() => {
@@ -43,7 +49,7 @@ afterEach(() => {
 
 describe("CronScheduler", () => {
   it("calls onJob for matching cron job", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "test-job", cron: currentMinuteCron(), prompt: "do something" }],
     });
 
@@ -56,7 +62,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob for non-matching jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "later", cron: nonMatchingCron(), prompt: "not now" }],
     });
 
@@ -68,8 +74,8 @@ describe("CronScheduler", () => {
     expect(onJob).not.toHaveBeenCalled();
   });
 
-  it("silently skips when cron.json does not exist", () => {
-    rmSync(CRON_FILE, { force: true });
+  it("silently skips when schedule.json does not exist", () => {
+    rmSync(SCHEDULE_FILE, { force: true });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -80,7 +86,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob on malformed JSON", () => {
-    writeFileSync(CRON_FILE, "not json{{{");
+    writeFileSync(SCHEDULE_FILE, "not json{{{");
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -91,7 +97,7 @@ describe("CronScheduler", () => {
   });
 
   it("does not call onJob when jobs is not an array", () => {
-    writeCronConfig({ jobs: "not-array" });
+    writeScheduleConfig({ jobs: "not-array" });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -102,7 +108,7 @@ describe("CronScheduler", () => {
   });
 
   it("skips invalid cron expression and processes valid jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "bad", cron: "invalid cron", prompt: "bad" },
         { name: "good", cron: currentMinuteCron(), prompt: "good" },
@@ -119,7 +125,7 @@ describe("CronScheduler", () => {
   });
 
   it("stop clears the interval", () => {
-    writeCronConfig({ jobs: [] });
+    writeScheduleConfig({ jobs: [] });
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
@@ -128,7 +134,7 @@ describe("CronScheduler", () => {
   });
 
   it("only evaluates once per minute", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "once" }],
     });
 
@@ -149,7 +155,7 @@ describe("CronScheduler", () => {
   });
 
   it("handles multiple matching jobs", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "first", cron: currentMinuteCron(), prompt: "first" },
         { name: "second", cron: currentMinuteCron(), prompt: "second" },
@@ -167,7 +173,7 @@ describe("CronScheduler", () => {
   });
 
   it("passes model override to onJob", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "smart", cron: currentMinuteCron(), prompt: "think hard", model: "opus" }],
     });
 
@@ -180,7 +186,7 @@ describe("CronScheduler", () => {
   });
 
   it("removes non-recurring job after it fires", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [
         { name: "once", cron: currentMinuteCron(), prompt: "one-time", recurring: false },
         { name: "always", cron: currentMinuteCron(), prompt: "forever" },
@@ -194,13 +200,13 @@ describe("CronScheduler", () => {
 
     expect(onJob).toHaveBeenCalledTimes(2);
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
     expect(updated.jobs[0].name).toBe("always");
   });
 
   it("keeps recurring jobs (default behavior)", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "keeper", cron: currentMinuteCron(), prompt: "stay" }],
     });
 
@@ -209,13 +215,13 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
     expect(updated.jobs[0].name).toBe("keeper");
   });
 
   it("keeps jobs with recurring: true", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "explicit", cron: currentMinuteCron(), prompt: "stay", recurring: true }],
     });
 
@@ -224,32 +230,30 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    const updated = readCronConfig();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
   });
 
-  it("still fires job when write-back of cron.json fails", () => {
-    // Write config to a path that will be read successfully
-    writeCronConfig({
+  it("still fires job when write-back of schedule.json fails", () => {
+    writeScheduleConfig({
       jobs: [{ name: "once", cron: currentMinuteCron(), prompt: "fire", recurring: false }],
     });
 
-    // Make cron.json read-only so writeFileSync fails
     const { chmodSync } = require("node:fs");
-    chmodSync(CRON_FILE, 0o444);
+    chmodSync(SCHEDULE_FILE, 0o444);
 
     const onJob = makeOnJob();
     const cron = new CronScheduler(TEST_DIR, { onJob });
     cron.start();
     cron.stop();
 
-    chmodSync(CRON_FILE, 0o644);
+    chmodSync(SCHEDULE_FILE, 0o644);
 
     expect(onJob).toHaveBeenCalledTimes(1);
   });
 
   it("does not write file when no non-recurring jobs fired", () => {
-    writeCronConfig({
+    writeScheduleConfig({
       jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope", recurring: false }],
     });
 
@@ -258,8 +262,74 @@ describe("CronScheduler", () => {
     cron.start();
     cron.stop();
 
-    // File should remain unchanged (job still present since it didn't fire)
-    const updated = readCronConfig();
+    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("does not fire non-recurring jobs older than threshold", () => {
+    writeScheduleConfig({
+      jobs: [{ name: "old", cron: minutesAgoCron(10), prompt: "too late", recurring: false }],
+    });
+
+    const onJob = makeOnJob();
+    const cron = new CronScheduler(TEST_DIR, { onJob });
+    cron.start();
+    cron.stop();
+
+    expect(onJob).not.toHaveBeenCalled();
+    const updated = readScheduleConfig();
     expect(updated.jobs).toHaveLength(1);
   });
 });

package/src/cron.ts

@@ -25,15 +25,16 @@ export interface CronSchedulerConfig {
 }
 
 const TICK_INTERVAL = 10_000; // 10 seconds
+const MISSED_THRESHOLD = 300_000; // 5 minutes
 
 export class CronScheduler {
   #lastMinute = -1;
-  #cronPath: string;
+  #schedulePath: string;
   #config: CronSchedulerConfig;
   #timer: Timer | null = null;
 
   constructor(workspace: string, config: CronSchedulerConfig) {
-    this.#cronPath = join(workspace, ".macroclaw", "cron.json");
+    this.#schedulePath = join(workspace, "data", "schedule.json");
     this.#config = config;
   }
 
@@ -59,16 +60,16 @@ export class CronScheduler {
 
     let config: CronConfig;
     try {
-      const raw = readFileSync(this.#cronPath, "utf-8");
+      const raw = readFileSync(this.#schedulePath, "utf-8");
       const parsed = cronConfigSchema.safeParse(JSON.parse(raw));
       if (!parsed.success) {
-        log.warn("cron.json: 'jobs' is not an array");
+        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 cron.json");
+      log.warn({ err: err instanceof Error ? err.message : err }, "Failed to read schedule.json");
       return;
     }
 
@@ -87,6 +88,14 @@ export class CronScheduler {
           if (job.recurring === false) {
             firedNonRecurring.push(i);
           }
+        } else if (job.recurring === false && diff < MISSED_THRESHOLD) {
+          // Non-recurring job missed (service was down) — fire with missed prefix
+          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");
@@ -99,9 +108,9 @@ export class CronScheduler {
         config.jobs.splice(firedNonRecurring[i], 1);
       }
       try {
-        writeFileSync(this.#cronPath, `${JSON.stringify(config, null, 2)}\n`);
+        writeFileSync(this.#schedulePath, `${JSON.stringify(config, null, 2)}\n`);
       } catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write cron.json");
+        log.warn({ err: err instanceof Error ? err.message : err }, "Failed to write schedule.json");
       }
     }
   }

package/src/prompts.ts

@@ -42,7 +42,7 @@ Send files via files array (absolute paths). Images (.png/.jpg/.jpeg/.gif/.webp)
 Timeouts: user=${fmtMin(MAIN_TIMEOUT)}, cron=${fmtMin(CRON_TIMEOUT)}, background=${fmtMin(BG_TIMEOUT)}. \
 On timeout, task continues in background automatically. Spawn background agents proactively for long tasks.
 
-Cron: jobs in .macroclaw/cron.json (hot-reloaded). Use "silent" when check finds nothing new, "send" when noteworthy.
+Cron: jobs in data/schedule.json (hot-reloaded). Use "silent" when check finds nothing new, "send" when noteworthy.
 
 MessageButtons: include a buttons field (flat array of label strings) to attach inline buttons below your message. \
 Each button gets its own row. Max 27 characters per label — if options need more detail, describe them in the message and use short labels on buttons.`;

package/src/setup.ts

@@ -80,7 +80,7 @@ export class SetupWizard {
 
       // Workspace
       this.#io.write("\nThe workspace directory where Claude Code runs — instructions, skills,\n");
-      this.#io.write("memory, and cron definitions all live here.\n\n");
+      this.#io.write("memory, and scheduled events all live here.\n\n");
       const defaultWorkspace = this.#default("workspace", "~/.macroclaw-workspace");
       const workspace = await this.#askValidated("workspace", `Workspace [${defaultWorkspace}]: `, defaultWorkspace);
 

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

@@ -0,0 +1,102 @@
+---
+name: schedule
+description: >
+  Schedule events, reminders, and recurring tasks. Use when the user wants to:
+  set a reminder, schedule something for later, create a recurring task,
+  set up a periodic check, automate a prompt on a schedule, or plan a
+  one-time or repeating event at a specific time.
+---
+
+Schedule a new event by adding it to `data/schedule.json`.
+
+## When to use this
+
+- **Reminders**: "remind me to call the dentist tomorrow at 10"
+- **One-time events**: "send the weekly report this Friday at 5pm"
+- **Recurring tasks**: "check my email every 30 minutes"
+- **Periodic prompts**: "give me a morning summary every weekday at 9"
+- **Scheduled checks**: "monitor the deploy status every 5 minutes for the next hour"
+- **Future actions**: "next Monday, ask me how the presentation went"
+
+## How to schedule
+
+1. Read `data/schedule.json` (create with `{"jobs": []}` if missing)
+2. Convert the user's request to a cron expression (see reference below)
+3. **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)
+4. Append the new job to the `jobs` array
+5. Write the updated file
+6. Confirm: what was scheduled, when it will fire, and offer to adjust
+
+## Natural language → cron
+
+Convert user intent to cron expressions. The user's timezone is in their profile (CLAUDE.md/USER.md) — convert to UTC for cron.
+
+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 * * * *`
+
+## schedule.json format
+
+```json
+{
+  "jobs": [
+    {
+      "name": "morning-summary",
+      "cron": "0 7 * * 1-5",
+      "prompt": "Give me a morning summary of my tasks"
+    },
+    {
+      "name": "email-check",
+      "cron": "*/30 * * * *",
+      "prompt": "Check if any important emails arrived",
+      "model": "haiku"
+    },
+    {
+      "name": "dentist-reminder",
+      "cron": "0 8 15 3 *",
+      "prompt": "Reminder: call the dentist to reschedule your appointment",
+      "recurring": false
+    }
+  ]
+}
+```
+
+## Job fields
+
+| 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. |
+| `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. |
+
+## Cron expression reference (UTC)
+
+```
+┌───────── minute (0-59)
+│ ┌─────── hour (0-23)
+│ │ ┌───── day of month (1-31)
+│ │ │ ┌─── month (1-12)
+│ │ │ │ ┌─ day of week (0-7, 0 and 7 = Sunday)
+│ │ │ │ │
+* * * * *
+```
+
+Common patterns:
+- `0 9 * * *` — daily at 9:00 UTC
+- `0 7 * * 1-5` — weekdays at 7:00 UTC
+- `*/30 * * * *` — every 30 minutes
+- `0 */2 * * *` — every 2 hours
+- `0 9,18 * * *` — at 9:00 and 18:00 UTC
+
+## Notes
+
+- 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

package/workspace-template/CLAUDE.md

@@ -57,14 +57,14 @@ Don't ask permission. Just do it.
   - bullet points (plain text bullet character)
   - No markdown syntax. No # headings. No [links](url). No *stars*.
 
-## Cron Jobs
+## Scheduled Events
 
-Messages prefixed with `[Tool: cron/<name>]` are automated. The agent decides whether to respond:
+Scheduled events are created by the `schedule` skill and stored in `data/schedule.json`. Messages prefixed with `[Context: cron/<name>]` are automated scheduled events. The agent decides whether to respond:
 
 - **action: "send"** — the response goes to Telegram
 - **action: "silent"** — the response is logged but not sent
 
-Use `silent` when a cron check finds nothing new. Only send when there's something worth reading.
+Use `silent` when a scheduled check finds nothing new. Only send when there's something worth reading.
 
 ## Skills
 
@@ -86,7 +86,7 @@ When creating new skills, always put them in `.claude/skills/` within this works
 Structure:
 - `.claude/skills/` — local agent skills
 - `memory/` — daily logs (YYYY-MM-DD.md)
-- `.macroclaw/cron.json` — scheduled jobs (hot-reloaded, no restart needed) (use add-cron skill to modify)
+- `data/schedule.json` — scheduled events and reminders (hot-reloaded, no restart needed) (use schedule skill to modify)
 
 ## Safety
 

package/workspace-template/.claude/skills/add-cronjob/SKILL.md

@@ -1,77 +0,0 @@
----
-name: add-cronjob
-description: Add a new scheduled cron job. Use when the user wants to schedule a recurring prompt, add a periodic task, or set up automated messages.
----
-
-Add a new cron job to `.macroclaw/cron.json` in this workspace.
-
-## Steps
-
-1. Read the current `.macroclaw/cron.json` file (create it if missing with `{"jobs": []}`)
-2. Ask the user what prompt to run and when (if not already specified)
-3. Build a standard cron expression for the schedule
-4. Append the new job to the `jobs` array
-5. Write the updated file
-6. Confirm what was added and when it will next run
-
-## cron.json format
-
-```json
-{
-  "jobs": [
-    {
-      "name": "morning-summary",
-      "cron": "0 9 * * *",
-      "prompt": "Give me a morning summary of my tasks"
-    },
-    {
-      "name": "email-check",
-      "cron": "*/30 * * * *",
-      "prompt": "Check if any important emails arrived",
-      "model": "haiku"
-    },
-    {
-      "name": "weekly-report",
-      "cron": "0 17 * * 5",
-      "prompt": "Generate a weekly report of completed tasks",
-      "recurring": false
-    }
-  ]
-}
-```
-
-## Job fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Short identifier for the job. Appears in the `[Tool: cron/<name>]` prefix so the agent knows which job triggered the prompt. Use kebab-case (e.g. `morning-summary`). |
-| `cron` | yes | Standard cron expression defining when the job runs. See reference below. |
-| `prompt` | yes | The message sent to Claude when the job fires. Write it as if you're typing a message in Telegram — the agent will receive and act on it. |
-| `recurring` | no | Whether the job repeats. Defaults to `true`. Set to `false` for one-shot jobs that should fire once and be automatically removed from cron.json. Good for reminders ("remind me to call the dentist tomorrow at 10") or one-time scheduled events ("send the weekly report this Friday"). |
-| `model` | no | Override the model for this specific job. Omit to use the default model (set via `MODEL` in `.env`), which is best for normal interactive tasks. Use `haiku` for cheap/fast routine checks (email polling, status pings). Use `opus` only when the task genuinely needs deeper reasoning. |
-
-## Cron expression reference
-
-```
-┌───────── minute (0-59)
-│ ┌─────── hour (0-23)
-│ │ ┌───── day of month (1-31)
-│ │ │ ┌─── month (1-12)
-│ │ │ │ ┌─ day of week (0-7, 0 and 7 = Sunday)
-│ │ │ │ │
-* * * * *
-```
-
-Common patterns:
-- `0 9 * * *` — daily at 9:00
-- `0 9 * * 1-5` — weekdays at 9:00
-- `*/30 * * * *` — every 30 minutes
-- `0 */2 * * *` — every 2 hours
-- `0 9,18 * * *` — at 9:00 and 18:00
-
-## Notes
-
-- Changes are hot-reloaded — no restart needed
-- File location: `<workspace>/.macroclaw/cron.json`
-- Prompts are injected into the conversation with a `[Tool: cron/<name>]` prefix
-- One-shot jobs (`recurring: false`) are cleaned up automatically after firing