@coryrylan/cradle 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [1.4.0](https://github.com/coryrylan/cradle/compare/cradle-v1.3.1...cradle-v1.4.0) (2026-08-31)
+
+### Features
+
+* **cli:** support schedules ([28f2e71](https://github.com/coryrylan/cradle/commit/28f2e714209e1e0e33cf22b7783e8730cd6ba232))
+
+## [1.3.1](https://github.com/coryrylan/cradle/compare/cradle-v1.3.0...cradle-v1.3.1) (2026-08-30)
+
+### Bug Fixes
+
+* **clI:** update dependencies ([24e2afe](https://github.com/coryrylan/cradle/commit/24e2afe3827a4f2916015fd1676464cb66a2dcd5))
+* **cli:** update deps ([07e4065](https://github.com/coryrylan/cradle/commit/07e4065826a2193d5c08ff7295441f0b496f89fe))
+
 ## [1.3.0](https://github.com/coryrylan/cradle/compare/cradle-v1.2.0...cradle-v1.3.0) (2026-07-26)
 
 ### Features

package/README.md

@@ -2,7 +2,7 @@
 
 ![CI Build](https://github.com/coryrylan/cradle/actions/workflows/pull-request.yml/badge.svg)
 
-A runtime for portable agents defined as folders. `cradle run <dir>` reads an agent folder — a `SYSTEM.md` or `APPEND_SYSTEM.md` (at least one) plus optional pi-native config, skills, extensions, and sandbox posture — and launches the [pi](https://github.com/earendil-works/pi-mono) coding agent configured from it. An agent declaring `sandbox/nono.json` or `sandbox/sbx.json` runs sandboxed — inside the [nono](https://github.com/always-further/nono) filesystem sandbox or the [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) microVM, respectively. See [ARCHITECTURE.md](../../ARCHITECTURE.md) for the folder format and [`examples/hello`](../../examples/hello) for a minimal agent. Built with Bun and TypeScript; install the standalone binary via `install.sh` (primary) or the npm package [`@coryrylan/cradle`](https://www.npmjs.com/package/@coryrylan/cradle) (alternative).
+A runtime for portable agents defined as folders. `cradle run <dir>` reads an agent folder — a `SYSTEM.md` or `APPEND_SYSTEM.md` (at least one) plus optional pi-native config, skills, extensions, and sandbox posture — and launches the [pi](https://github.com/earendil-works/pi-mono) coding agent configured from it. An agent declaring `sandbox/nono.json` or `sandbox/sbx.json` runs sandboxed — inside the [nono](https://github.com/nolabs-ai/nono) filesystem sandbox or the [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) microVM, respectively. See [ARCHITECTURE.md](../../ARCHITECTURE.md) for the folder format and [`examples/hello`](../../examples/hello) for a minimal agent. Built with Bun and TypeScript; install the standalone binary via `install.sh` (primary) or the npm package [`@coryrylan/cradle`](https://www.npmjs.com/package/@coryrylan/cradle) (alternative).
 
 ## Dependencies
 
@@ -11,7 +11,7 @@ A runtime for portable agents defined as folders. `cradle run <dir>` reads an ag
 | Tool                                              | Status          | Why                                                                                                                                                                                                                                                  |
 | ------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`pi`](https://github.com/earendil-works/pi-mono) | **Required**    | The coding agent cradle launches. Every `cradle run` spawns it.                                                                                                                                                                                      |
-| [`nono`](https://github.com/always-further/nono)  | **Recommended** | The filesystem sandbox pi runs inside for a nono-backend run — a folder declaring `sandbox/nono.json`, or `--sandbox`/`--sandbox-backend nono`/`--offline`/`--allow-host` with no `sandbox/sbx.json`; required for that run, not needed otherwise.   |
+| [`nono`](https://github.com/nolabs-ai/nono)       | **Recommended** | The filesystem sandbox pi runs inside for a nono-backend run — a folder declaring `sandbox/nono.json`, or `--sandbox`/`--sandbox-backend nono`/`--offline`/`--allow-host` with no `sandbox/sbx.json`; required for that run, not needed otherwise.   |
 | [`sbx`](https://docs.docker.com/ai/sandboxes/)    | **Recommended** | The Docker Sandboxes microVM pi runs inside for an sbx-backend run — a folder declaring `sandbox/sbx.json`, or `--sandbox-backend sbx`; required for that run, not needed otherwise.                                                                 |
 | [`mise`](https://mise.jdx.dev)                    | **Recommended** | The supported way to install and manage `pi` and `nono`. cradle doesn't invoke mise directly, but it falls back to mise's shims when resolving the tools, and the generated sandbox profile grants mise's trees so a sandboxed pi finds its runtime. |
 
@@ -73,10 +73,32 @@ cradle run . --allow-host api.example.com  # restrict network to these hosts (re
 cradle run . --sandbox-backend sbx  # run under the sbx Docker Sandboxes microVM instead of nono
 cradle run . --no-sandbox           # run pi directly (debug)
 cradle run . --dry-run -- --resume  # print the write plan + command; forward `--resume` to pi
+
+cradle schedule list ./my-agent            # scheduled tasks, cron, next fire
+cradle schedule list my-agent              # a name from ~/.cradle/settings.json works here too
+cradle schedule install ./my-agent         # write + load a native OS timer per task
+cradle schedule run ./my-agent daily-report  # fire one task now, in the foreground
+cradle schedule remove ./my-agent          # unload + delete
 ```
 
 The agent runs in _your_ working directory; the agent folder is a parameter (default `.`). Everything after `--` is forwarded verbatim to pi. `--dry-run` prints the generated-extension write plan and the composed command without spawning (and without requiring the bins to be installed). Per-agent state (generated extensions + session history) lives under `~/.cradle/agents/<name>-<hash>/`.
 
+### Scheduled runs (`schedule/`)
+
+An agent folder can carry a `schedule/` directory; each `schedule/<task>.md` is one cron-driven run — YAML frontmatter (`cron`, `cwd`, optional `name`/`description`) plus a markdown body that becomes the prompt.
+
+```yaml
+---
+name: Daily standup report
+cron: '0 9 * * 1-5'
+cwd: ~/dev/my-project
+---
+```
+
+`cradle schedule install` writes one native OS timer per task — a launchd LaunchAgent on macOS, a systemd user timer on Linux — each invoking `cradle schedule run <folder> <task>`. Both beat cron because they run a missed calendar job after the machine wakes. Task output lands in `~/.cradle/agents/<id>/schedule/<task>.log`.
+
+A scheduled run is an ordinary `cradle run` with the task's `cwd` and prompt, so it adds no new sandbox policy: `cwd` is read+write exactly as it is interactively, and reaching outside it still needs a `sandbox/nono.json` grant. Runs pass pi's `--print` and `--no-approve` so an unattended job never blocks on a trust prompt. Cron expressions constraining both day-of-month and day-of-week are rejected — cron ORs those fields while launchd and systemd both AND them. See [ARCHITECTURE.md](../../ARCHITECTURE.md#schedules) for the full format.
+
 ### Global agent aliases (`~/.cradle/settings.json`)
 
 The `dir` positional accepts a bare name instead of a path — `cradle run my-agent` resolves against a global name → folder map, so agent folders you keep far from any project don't need a full path from every cwd:

package/dist/agent/folder.d.ts

@@ -1,5 +1,5 @@
 import { type NpmPackageSpec } from './packages.js';
-export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export interface AgentSettings {
     readonly defaultProvider?: string;
     readonly defaultModel?: string;
@@ -85,6 +85,8 @@ export interface AgentFolder {
     /** Serialized `providers` object from models.json, `null` when absent. */
     readonly providersJson: string | null;
     readonly skillsDir: string | null;
+    /** `schedule/` dir, `null` when absent. Parsing is lazy — see `./schedules.js`'s `loadSchedules`. */
+    readonly scheduleDir: string | null;
     /** pi-native extensions (top-level `extensions/*.ts` plus each subdir's `index.ts`), absolute paths. */
     readonly extensionFiles: readonly string[];
     /** `sandbox/nono.json`'s declared posture — the Seatbelt/bubblewrap backend. */

package/dist/agent/schedules.d.ts

@@ -0,0 +1,27 @@
+export interface Schedule {
+    /** Filename without `.md` — the identity used on the CLI and in timer labels. */
+    readonly slug: string;
+    /** Display label from frontmatter `name`; falls back to `slug`. */
+    readonly name: string;
+    /** Absolute path of the source `.md`. */
+    readonly path: string;
+    /** Raw cron expression, unparsed. */
+    readonly cron: string;
+    /** Absolute working directory, `~`/`$HOME` already expanded. */
+    readonly cwd: string;
+    readonly description?: string;
+    /** The markdown body — the prompt handed to pi. */
+    readonly prompt: string;
+}
+export interface LoadedSchedules {
+    readonly schedules: readonly Schedule[];
+    readonly warnings: readonly string[];
+}
+/**
+ * The "folder has no `schedule/`" error. `schedules/` is the intuitive guess
+ * for a directory holding many schedules, so when that is what the folder
+ * actually has, name the rename — the same targeted hint `folder.ts` gives for
+ * a legacy `AGENTS.md`.
+ */
+export declare function missingScheduleDirError(agentDir: string): Promise<Error>;
+export declare function loadSchedules(scheduleDir: string, home: string): Promise<LoadedSchedules>;

package/dist/commands/doctor.d.ts

@@ -11,11 +11,15 @@ interface DoctorDeps {
     readonly which?: WhichFn;
     /** Read a bin's version output (default argv `--version`; sbx passes `['version']`); injected so in-process tests never spawn. */
     readonly readVersion?: (binPath: string, args?: readonly string[]) => Promise<string | null>;
+    /** Injectable so both the launchd and systemd probes are exercised from any one machine's tests. */
+    readonly platform?: NodeJS.Platform;
 }
 /**
  * Probe the environment cradle depends on: `pi` (always required), `nono` and
- * `sbx` (each required only for runs on its backend — see the notes), and
- * `mise` (recommended toolchain manager).
+ * `sbx` (each required only for runs on its backend — see the notes), `mise`
+ * (recommended toolchain manager), and the platform's scheduling backend
+ * (`launchctl`/`systemctl`, recommended for `cradle schedule`; skipped
+ * entirely on a platform with neither).
  */
 export declare function runDoctor(deps?: DoctorDeps): Promise<DoctorCheck[]>;
 export declare function formatDoctorReport(checks: readonly DoctorCheck[]): string;

package/dist/commands/run.d.ts

@@ -18,6 +18,18 @@ export interface RunFlags {
     readonly passthrough?: readonly string[];
     /** `--verbose` → show nono's full sandbox capabilities banner instead of the one-line status. */
     readonly verbose?: boolean;
+    /**
+     * A `schedule/<task>.md` slug to run headless instead of starting an
+     * interactive session. The named schedule's `cwd` replaces the run's
+     * effective working directory (see `RunPlan.cwd`), and its body is appended
+     * to the launch passthrough as `--print --name <name> --no-approve --
+     * <prompt>`, after any user `--` passthrough so it always terminates the
+     * argv. Set only by `cradle schedule run` — and therefore by the OS timers,
+     * whose composed argv is exactly that command (see `schedule/launchd.ts`
+     * and `schedule/systemd.ts`). There is deliberately no `--schedule` flag on
+     * `cradle run`: two spellings of one action is one too many.
+     */
+    readonly schedule?: string;
 }
 interface RunDeps {
     readonly cwd?: string;
@@ -88,6 +100,13 @@ export interface RunPlan {
     readonly packages: PackagesPlan | null;
     /** The single argv source: `composeArgv(plan.launch)` — package-entry-free until `materializeRun` recomposes it with resolved package entries. */
     readonly launch: LaunchSpec;
+    /**
+     * The effective working directory: `deps.cwd`, or `flags.schedule`'s
+     * `Schedule.cwd` when a schedule is running. Callers spawn here — `cli.ts`
+     * passes it to `runForeground` — since a scheduled run's launchd/systemd
+     * invocation carries no shell `cd` of its own.
+     */
+    readonly cwd: string;
     readonly dryRun: boolean;
 }
 /**

package/dist/commands/schedule.d.ts

@@ -0,0 +1,85 @@
+import { type AgentFolder } from '../agent/folder.js';
+import { type Schedule } from '../agent/schedules.js';
+import type { TimerPlan } from '../schedule/timer.js';
+import { type WhichFn } from '../util/which.js';
+/** `cradle schedule run` is NOT here: it executes the task in-process through `commands/run.ts`, so `cli.ts` routes it there instead. */
+export type ScheduleAction = 'list' | 'install' | 'remove';
+/** launchd (macOS) and systemd `--user` (Linux) are the only supported timer backends. */
+type SupportedSchedulePlatform = 'darwin' | 'linux';
+export interface ScheduleFlags {
+    readonly dir: string;
+    readonly action: ScheduleAction;
+    /** Required for `run`; an optional filter for `install`/`remove` (every schedule when absent); unused for `list`, which always lists everything. */
+    readonly slug?: string;
+    /** `install` only — print the write plan and touch nothing. */
+    readonly dryRun?: boolean;
+}
+interface ScheduleDeps {
+    readonly cwd?: string;
+    readonly home?: string;
+    readonly which?: WhichFn;
+    readonly platform?: NodeJS.Platform;
+    readonly uid?: number;
+    /** The OS account name `loginctl show-user <user>` checks — default the real login name. */
+    readonly user?: string;
+    readonly now?: () => Date;
+}
+/** One `cradle schedule list` row — a broken cron is reported inline rather than aborting the whole listing. */
+export interface ScheduleRow {
+    readonly slug: string;
+    readonly name: string;
+    readonly cron: string;
+    readonly cwd: string;
+    readonly cronError?: string;
+    readonly nextFire: Date | null;
+    readonly installed: boolean;
+}
+/** One resolved schedule's composed timer, for `install`/`remove`/`run`. */
+interface ScheduleTarget {
+    readonly schedule: Schedule;
+    readonly timerPlan: TimerPlan;
+    /** Not carried by `TimerPlan` itself — `materializeSchedule` `mkdir -p`s its parent before running `installSteps`. */
+    readonly logPath: string;
+}
+export interface SchedulePlan {
+    readonly action: ScheduleAction;
+    readonly folder: AgentFolder;
+    readonly platform: SupportedSchedulePlatform;
+    /** Populated for `list` only. */
+    readonly rows: readonly ScheduleRow[];
+    /** Populated for `install`/`remove`/`run` — every selected schedule with its composed `TimerPlan`. */
+    readonly targets: readonly ScheduleTarget[];
+    readonly warnings: readonly string[];
+    readonly dryRun: boolean;
+    /** `install` on Linux only — `materializeSchedule` runs this first and warns `LINGER_HINT` when lingering is off. */
+    readonly lingerCheckArgv: readonly string[] | null;
+}
+/**
+ * Resolve the ref, load the agent folder's `schedule/`, and — for every
+ * action but `list` — compose the selected schedule(s)' `TimerPlan`s. `list`
+ * never throws on a single bad schedule (see `buildScheduleRow`); every other
+ * action does, since installing/removing/firing a broken timer can't proceed.
+ */
+export declare function planSchedule(flags: ScheduleFlags, deps?: ScheduleDeps): Promise<SchedulePlan>;
+/** Format `list`'s rows into the printed report — pure, mirroring `doctor.ts`'s `runDoctor`/`formatDoctorReport` split. */
+export declare function formatScheduleList(rows: readonly ScheduleRow[]): string;
+export interface ScheduleRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface MaterializeScheduleDeps {
+    /** Runs one launchctl/systemctl/loginctl argv, capturing both streams; `cli.ts` passes `runCaptureAll` from `util/proc.js`. */
+    readonly run?: (argv: readonly string[]) => Promise<ScheduleRunResult>;
+}
+export interface MaterializeScheduleResult {
+    readonly warnings: string[];
+}
+/**
+ * Apply a non-`list` plan's side effects. The caller is responsible for
+ * skipping this entirely on `--dry-run` (`plan.dryRun`) — same precedent as
+ * `commands/run.ts`'s `materializeRun`, which `cli.ts` never calls when
+ * `plan.dryRun` is set.
+ */
+export declare function materializeSchedule(plan: SchedulePlan, deps?: MaterializeScheduleDeps): Promise<MaterializeScheduleResult>;
+export {};