summary: "RFC: Cron jobs + wakeups for Clawd/Clawdis (main vs isolated sessions)"

read_when:

- Designing scheduled jobs, alarms, or wakeups

- Adding Gateway methods or CLI commands for automation

- Adjusting heartbeat behavior or session routing

Status: Draft

Last updated: 2025-12-13

Clawdis already has:

- A **periodic reply heartbeat** that runs the agent with `HEARTBEAT /think:high` and suppresses `HEARTBEAT_OK` (`src/web/auto-reply.ts`).

- A lightweight, in-memory **system event queue** (`enqueueSystemEvent`) that is injected into the next **main session** turn (`drainSystemEvents` in `src/auto-reply/reply.ts`).

- A WebSocket **Gateway** daemon that is intended to be always-on (`docs/gateway.md`).

This RFC adds a small “cron job system” so Clawd can schedule future work and reliably wake itself up:

- **Delayed**: run on the *next* normal heartbeat tick

- **Immediate**: run *now* (trigger a heartbeat immediately)

- **Isolated jobs**: optionally run in their own session that does not pollute the main session and can run concurrently (within configured limits).

- Provide a **persistent job store** and an **in-process scheduler** owned by the Gateway.

- Allow each job to target either:

- `sessionTarget: "main"`: inject as `System:` lines and rely on the main heartbeat (or trigger it immediately).

- `sessionTarget: "isolated"`: run an agent turn in a dedicated session key (job session), optionally delivering a message and/or posting a summary back to main.

- Expose a stable control surface:

- **Gateway methods** (`cron.*`, `wake`) for programmatic usage (mac app, CLI, agents).

- **CLI commands** (`clawdis cron ...`) to add/remove/edit/list and to debug `run`.

- Produce clear, structured **logs** for job lifecycle and execution outcomes.

- Multi-host distributed scheduling.

- Exactly-once semantics across crashes (we aim for “at-least-once with idempotency hooks”).

- A full Unix-cron parser as the only schedule format (we can support it, but v1 should not require complex cron features to be useful).

- **Wake**: a request to ensure the agent gets a turn soon (either right now or next heartbeat).

- **Main session**: the canonical session bucket (default key `"main"`) that receives `System:` events.

- **Isolated session**: a per-job session key (e.g. `cron:<jobId>`) with its own session id / session file.

- “Remind me in 20 minutes” → add a one-shot job that triggers an immediate heartbeat at T+20m.

- “Every weekday at 7:30, wake me up and start music” → recurring job, isolated session, deliver to WhatsApp.

- “Every hour, check battery; only interrupt me if < 20%” → isolated job that decides whether to deliver; may also post a brief status to main.

- “Next heartbeat, please check calendar” → delayed wake targeting main session.

Each job is a JSON object with stable keys (unknown keys ignored for forward compatibility):

- `id: string` (UUID)

- `name?: string`

- `enabled: boolean`

- `createdAtMs: number`

- `updatedAtMs: number`

- `schedule` (one of)

- `{"kind":"at","atMs":number}` (one-shot)

- `{"kind":"every","everyMs":number,"anchorMs"?:number}` (simple interval)

- `{"kind":"cron","expr":string,"tz"?:string}` (optional; see “Schedule parsing”)

- `sessionTarget: "main" | "isolated"`

- `wakeMode: "next-heartbeat" | "now"`

- For `sessionTarget:"isolated"`, `wakeMode:"now"` means “run immediately when due”.

- For `sessionTarget:"main"`, `wakeMode` controls whether we trigger the heartbeat immediately or just enqueue and wait.

- `payload` (one of)

- `{"kind":"systemEvent","text":string}` (enqueue as `System:`)

- `{"kind":"agentTurn","message":string,"deliver"?:boolean,"channel"?: "last"|"whatsapp"|"telegram","to"?:string,"timeoutSeconds"?:number}`

- `isolation` (optional; only meaningful for isolated jobs)

- `{"postToMain": boolean, "postToMainPrefix"?: string}`

- `runtime` (optional)

- `{"maxAttempts"?:number,"retryBackoffMs"?:number}` (best-effort retries; defaults off)

- `state` (runtime-maintained)

- `{"nextRunAtMs":number,"lastRunAtMs"?:number,"lastStatus"?: "ok"|"error"|"skipped","lastError"?:string,"lastDurationMs"?:number}`

- `sessionTarget:"main"` jobs always enqueue `payload.kind:"systemEvent"` (directly or derived from `agentTurn` results; see below).

- `sessionTarget:"isolated"` jobs create/use a stable session key: `cron:<jobId>`.

We can store this directly under `~/.clawdis` without a subfolder, but a folder gives us room for future artifacts (per-job state, migration backups, run history).

Current behavior (v1):

- Default store: `~/.clawdis/cron.json`

- If `~/.clawdis/cron/jobs.json` exists, it is preferred (and is a good location for future per-cron artifacts).

- Any path can be forced via `cron.store` in config.

The scheduler should never require additional configuration for the base directory (Clawdis already treats `~/.clawdis` as fixed).

Cron execution should be opt-in via config:

{

cron: {

enabled: true,

// optional:

store: "~/.clawdis/cron.json",

maxConcurrentRuns: 1

}

}

The Gateway owns:

- the scheduler timer,

- job store reads/writes,

- job execution (enqueue system events and/or agent turns).

This keeps scheduling unified with the always-on process and prevents “two schedulers” when multiple CLIs run.

- Maintain an in-memory heap/array of enabled jobs keyed by `state.nextRunAtMs`.

- Use a **single `setTimeout`** to wake at the earliest next run.

- On wake:

- compute all due jobs (now >= nextRunAtMs),

- mark them “in flight” (in memory),

- persist updated `state` (at least bump `nextRunAtMs` / `lastRunAtMs`) before starting execution to minimize duplicate runs on crash,

- execute jobs (with concurrency limits),

- persist final `lastStatus/lastError/lastDurationMs`,

- re-arm timer for the next earliest run.

V1 can ship with `at` + `every` without extra deps.

If we add `"kind":"cron"`:

- Use a well-maintained parser (we use `croner`) and support:

- 5-field cron (`min hour dom mon dow`) at minimum

- optional `tz`

- Store `nextRunAtMs` computed by the parser; re-compute after each run.

Main session jobs do not run the agent directly by default.

When due:

1) `enqueueSystemEvent(job.payload.text)` (or a derived message)

2) If `wakeMode:"now"`, trigger an immediate heartbeat run (see “Heartbeat wake hook”).

3) Otherwise do nothing else (the next scheduled heartbeat will pick up the system event).

Why: This keeps the main session’s “proactive” behavior centralized in the heartbeat rules and avoids ad-hoc agent turns that might fight with inbound message processing.

Isolated jobs run an agent turn in a dedicated session key, intended to be separate from main.

When due:

- Build a message body that includes schedule metadata, e.g.:

- `"[cron:<jobId>] <job.name>: <payload.message>"`

- Execute via the same agent runner path as other command-mode runs, but pinned to:

- `sessionKey = cron:<jobId>`

- `sessionId = store[sessionKey].sessionId` (create if missing)

- Optionally deliver output (`payload.deliver === true`) to the configured channel/to.

- If `isolation.postToMain` is true, enqueue a summary system event to main, e.g.:

- `System: Cron "<name>" completed: <1-line summary>`

Clawdis currently serializes command execution through a global in-process queue (`src/process/command-queue.ts`) to avoid collisions.

To support isolated cron jobs running “in parallel”, we should introduce **lanes** (keyed queues) plus a global concurrency cap:

- Lane `"main"`: inbound auto-replies + main heartbeat.

- Lane `"cron"` (or `cron:<jobId>`): isolated jobs.

- Configurable `cron.maxConcurrentRuns` (default 1 or 2).

This yields:

- isolated jobs can overlap with the main lane (up to cap),

- each lane still preserves ordering for its own work (optional),

- we retain safety knobs to prevent runaway resource contention.

We need a way for the Gateway (or the scheduler) to request an immediate heartbeat without duplicating heartbeat logic.

Design:

- `monitorWebProvider` owns the real `runReplyHeartbeat()` function (it already has all the local state needed).

- Add a small global hook module:

- `setReplyHeartbeatWakeHandler(fn | null)` installed by `monitorWebProvider`

- `requestReplyHeartbeatNow({ reason, coalesceMs? })`

- If the handler is absent (provider not connected), the request is stored as “pending”; the next time the handler is installed, it runs once.

- Coalesce rapid calls and respect the existing “skip when queue busy” behavior (prefer retrying soon vs dropping).

In addition to normal structured logs, the Gateway writes an append-only run history “ledger” (JSONL) whenever a job finishes. This is intended for quick debugging (“did the job run, when, and what happened?”).

Path rules:

- If the cron store path basename is `jobs.json` (e.g. `~/.clawdis/cron/jobs.json`), logs go to `.../runs/<jobId>.jsonl` (e.g. `~/.clawdis/cron/runs/<jobId>.jsonl`).

- Otherwise logs go to `<storeBase>.runs.jsonl` in the same directory (e.g. `~/.clawdis/cron.json` → `~/.clawdis/cron.runs.jsonl`).

Retention:

- Best-effort pruning when the file grows beyond ~2MB; keep the newest ~2000 lines.

New methods (names can be bikeshed; `cron.*` is suggested):

- `wake`

- params: `{ mode: "now" | "next-heartbeat", text: string }`

- effect: `enqueueSystemEvent(text)`, plus optional immediate heartbeat trigger

- `cron.list`

- params: optional `{ includeDisabled?: boolean }`

- returns: `{ jobs: CronJob[] }`

- `cron.add`

- params: job payload without `id/state` (server generates and returns created job)

- `cron.update`

- params: `{ id: string, patch: Partial<CronJobWritableFields> }`

- `cron.remove`

- params: `{ id: string }`

- `cron.run`

- params: `{ id: string, mode?: "due" | "force" }` (debugging; does not change schedule unless `force` requires it)

- `cron.runs`

- params: `{ id?: string, limit?: number }`

- returns: `{ entries: CronRunLogEntry[] }`

- note: if the store layout is `.../jobs.json`, `id` is required (runs are stored per-job).

The Gateway should broadcast a `cron` event for UI/debug:

- event: `cron`

- payload: `{ jobId, action: "added"|"updated"|"removed"|"started"|"finished", status?, error?, nextRunAtMs? }`

Add a `cron` command group (all commands should also support `--json` where sensible):

- `clawdis cron list [--json] [--all]`

- `clawdis cron add ...`

- schedule flags:

- `--at <iso8601|ms|relative>` (one-shot)

- `--every <duration>` (e.g. `10m`, `1h`)

- `--cron "<expr>" [--tz "<tz>"]`

- target flags:

- `--session main|isolated`

- `--wake now|next`

- payload flags (choose one):

- `--system-event "<text>"`

- `--message "<agent message>" [--deliver] [--channel last|whatsapp|telegram] [--to <dest>]`

- `clawdis cron edit <id> ...` (patch-by-flags, non-interactive)

- `clawdis cron rm <id>`

- `clawdis cron enable <id>` / `clawdis cron disable <id>`

- `clawdis cron run <id> [--force]` (debug)

Additionally:

- `clawdis wake --mode now|next --text "<text>"` as a thin wrapper around `wake` for agents to call.

One-shot reminder that targets the main session and triggers a heartbeat immediately at the scheduled time:

clawdis cron add \

--at "2025-12-14T07:00:00-08:00" \

--session main \

--wake now \

--system-event "Alarm: wake up (meeting in 30 minutes)."

Daily at 07:00 in a specific timezone (preferred over “every 24h” to avoid DST drift):

clawdis cron add \

--cron "0 7 * * *" \

--tz "America/Los_Angeles" \

--session isolated \

--wake now \

--message "Daily check: scan calendar + inbox; deliver only if urgent." \

--deliver \

--channel last

Every Wednesday at 09:00:

clawdis cron add \

--cron "0 9 * * 3" \

--tz "America/Los_Angeles" \

--session isolated \

--wake now \

--message "Weekly: summarize status and remind me of goals." \

--deliver \

--channel last

Enqueue a note for the main session but let the existing heartbeat cadence pick it up:

clawdis wake --mode next --text "Next heartbeat: check battery + upcoming meetings."

Logging requirements:

- Use `getChildLogger({ module: "cron", jobId, runId, name })` for every run.

- Log lifecycle:

- store load/save (debug; include job count)

- schedule recompute (debug; include nextRunAt)

- job start/end (info)

- job skipped (info; include reason)

- job error (warn; include error + stack where available)

- Emit a concise user-facing line to stdout when running in CLI mode (similar to heartbeat logs).

Suggested log events:

- `cron: scheduler started` (jobCount, nextWakeAt)

- `cron: job started` (jobId, scheduleKind, sessionTarget, wakeMode)

- `cron: job finished` (status, durationMs, nextRunAtMs)

- Respect existing allowlists/routing rules: delivery defaults should not send to arbitrary destinations unless explicitly configured.

- Provide a global “kill switch”:

- `cron.enabled: boolean` config default true (or false until enabled).

- `gateway method set-heartbeats` already exists; cron should have similar.

- Avoid persistence of sensitive payloads unless requested; job text may contain private content.

- Unit tests:

- schedule computation for `at` and `every`

- job store read/write + migration behavior

- lane concurrency: main vs cron overlap is bounded

- “wake now” coalescing and pending behavior when provider not ready

- Integration tests:

- start Gateway with `CLAWDIS_SKIP_PROVIDERS=1`, add jobs, list/edit/remove

- simulate due jobs and assert `enqueueSystemEvent` called + cron events broadcast

1) Add the `wake` primitive + heartbeat wake hook (no persistent jobs yet).

2) Add `cron.*` API and CLI wrappers with `at` + `every`.

3) Add optional cron expression parsing (`kind:"cron"`) if needed.

4) Add UI surfacing in WebChat/macOS app (optional).