Cron

Canonical contract: packages/sdk/docs.md — Cron namespace.

The Cron namespace lets you schedule recurring agent runs. Backed by croner (ADR D7), persisted as JSON to .theokit/cron/jobs.json with atomic writes (ADR D8).

Schedule a job

import { Cron } from "@theokit/sdk";

const job = await Cron.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  schedule: "0 9 * * *", // every day at 09:00 local
  prompt: "Summarize yesterday's logs and post to Slack.",
  agent: {
    model: { id: "openai/gpt-4o-mini" },
    name: "log-summarizer",
  },
});

console.log(job.id, job.nextFire); // "cron-abc...", "2026-05-24T09:00:00..."

Persistence + restart

Jobs survive process restart. On next Cron.list() or Cron.create(), the persisted jobs reload and continue firing.

List / cancel

const all = await Cron.list();
await Cron.cancel(job.id);

Manual fire (testing)

await Cron.fire(job.id);

Schedule expression

croner accepts:

• 5-field cron: * * * * * (min hour dom month dow)
• 6-field cron: * * * * * * (sec min hour dom month dow)
• Aliases: @hourly, @daily, @weekly, @monthly

Caveats

• Process MUST be running when the schedule fires. Cron isn't a daemon — it's an in-process scheduler. Use a process supervisor (pm2, systemd, Cloudflare Cron Triggers, etc.) to keep your Node app alive.
• File lock via proper-lockfile (ADR D61) prevents two processes from corrupting jobs.json.

API reference