cron
v0.22.2Run functions on cron schedules — hosts `cron::on-tick`; each observer of it passes `{ expression }` as args and receives that expression's ticks.
Install
iii trigger compose::add worker=cronRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
cron
Runs functions on cron schedules. A function runs on a schedule when it
observes cron::on-tick with a cron expression as args: this worker calls
cron::on-tick once per fire of that expression, at the next matching UTC
time, and every observer of the expression receives the tick.
Install
iii call compose::add worker=croniii call compose::add resolves the worker and its dependencies, writes
exact declarations to worker-compose.yaml, and reconciles the Compose project.
Quickstart
Register a function and observe cron::on-tick with it, passing the schedule
as args:
iii.registerFunction('reports::daily', async ({ output: tick }: { output: CronTick }) => {
// tick: { expression, scheduled_time, actual_time }
await sendDigest(tick.scheduled_time)
})
const digest = iii.observe(
{ function_id: 'cron::on-tick', args: { expression: '0 0 9 * * Mon-Fri' }, capture: ['output'] },
'reports::daily',
)
await digest.ready() // rejected with INVALID_CRON_EXPRESSION for a bad expression
// later: await digest.dispose() stops the scheduleThe same in Rust:
use iii_sdk::{errors::Error, register_worker, Capture, InitOptions, RegisterFunction, Source};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
iii.register_function(
"jobs::tick",
RegisterFunction::new_async(|observed: Value| async move {
println!("cron fired: {}", observed["output"]);
Ok::<Value, Error>(json!({ "ok": true }))
}),
);
iii.observe(
Source::function("cron::on-tick")
.args(json!({ "expression": "*/5 * * * * *" }))
.capture([Capture::Output]),
"jobs::tick",
);
tokio::signal::ctrl_c().await?;
Ok(())
}With capture: ['output'] the function receives the Observed envelope,
whose output is the tick:
{
"expression": "*/5 * * * * *",
"scheduled_time": "2026-07-03T12:00:00+00:00",
"actual_time": "2026-07-03T12:00:00.123456789+00:00"
}Without it, the function receives the Observed envelope, with the tick as
its input and output and the observer's id as observer_id.
Functions
| Function | Args | What it is |
|---|---|---|
cron::on-tick |
{ expression } |
One call per fire of a cron expression. Observers observe the tick; each observer receives the ticks of its own expression. |
cron::on-tick
| Arg | Required | Description |
|---|---|---|
expression |
yes | Cron expression parsed by the Rust cron crate: six fields sec min hour day month weekday, and an optional seventh year field. UTC. |
Rejections, through the observer's ready():
| Code | When |
|---|---|
INVALID_ARGS |
expression is missing or not a string, or another arg is present. |
INVALID_CRON_EXPRESSION |
expression is empty or does not parse; the message names the expression. |
The event, the function's input and what its observers observe:
| Field | Description |
|---|---|
expression |
The expression that fired, exactly as its observers passed it in args. |
scheduled_time |
The fire's scheduled time: RFC 3339 in UTC with a +00:00 offset, whole seconds (2026-11-01T09:00:00+00:00). |
actual_time |
When the worker fired it: RFC 3339 in UTC with a +00:00 offset. |
- Delivery. The worker runs one job per distinct expression and calls
cron::on-tickonce per fire. iii delivers the tick to the observers of that expression (matched byargs.expressionandinput.expression) whose filters accept it. The job starts with the expression's first observer and stops with its last. Every fire is delivered, even while the target still runs the previous one: observe withmax_in_flight: 1to run one at a time, the later fires waiting their turn. - Filters select ticks by
input, e.g.{ 'input.scheduled_time': { $gte: '2026-11-01T00:00:00+00:00' } }. Filters compare strings by code point, so a time bound is written in the form the worker emits: RFC 3339 with+00:00. - Metadata. The observer's
metadataarrives as each delivery's sidecar. - Missed fires. Fires while the worker is stopped, or disconnected from the engine, are skipped; there is no catch-up replay.
- Day of week. Write it as a name (
Mon...Sun). Numerically the crate counts Sunday as 1, so0 0 9 * * 1fires on Sunday, not Monday. - Private. Only this worker calls
cron::on-tick; a call from another worker is refused withFORBIDDEN, and the function cannot be an observer's target. - One host.
cron::on-tickhas one host per namespace, so each expression fires once per scheduled time. Run one instance: a second one is refused the function, and one started under the name a live worker holds is refused (WORKER_NAMESPACE_CONFLICT) and exits. When the instance restarts, the engine hands it the observers back.
A target that needs to know which schedule fired reads observer_id from the
envelope, or observes with its own target per schedule.
Configuration
The worker has no settings. The engine passes a worker's config: block as
--config <file>; this worker does not read it.
Console page
While the worker is connected it injects a cron page into the console
(page cron): every agent-owned schedule with its cadence, next UTC run and
fire count, the cron::on-tick observers other workers created for their own
functions, and a composer that turns "every weekday at 09:00, summarise open
PRs" into a schedule. The composer and the manual form ask a harness agent to
call harness::observe with { function_id: 'cron::on-tick', args: { expression } }; schedules created there live in a session of their own, so
each routine keeps its own transcript.
Console observer activity
The worker injects a cron-specific source section into Consoles that support
host.observerRenderers. The activity of a cron::on-tick observer (added,
fired, retired) shows a plain-language schedule, the exact expression, and
explicit UTC. Expressions that cannot be summarized without hiding cron
semantics keep an honest “custom schedule” label and the raw expression.
The Console retains the surrounding activity, delivery target/result, lifecycle state and controls, and raw JSON. Disabling or disconnecting this worker's injected UI falls back to the generic observer view.
For local UI development:
pnpm --dir cron/ui test
pnpm --dir cron/ui build
# terminal 1
pnpm --dir cron/ui watch
# terminal 2
cd cron && III_CRON_UI_WATCH=1 cargo runThe Rust build embeds cron/page.js and cron/styles.css; production does
not require a separate asset server.