Cron jobs and the API log

Setting one up

A cron sends a prompt to an agent on a schedule. Six fields. The job has its own name, separate from the agent's — one agent can carry several jobs, and the list has to be readable when it does. Run on restart exists because the Space sleeps: a job that only trusts the clock quietly does not happen.

Seeing what is scheduled

The list is what gets used daily: what is due, how the last run went, and three actions per row. Run now fires it outside the schedule — the "after a restart" case. Stop switches the job off but keeps it, so it can be turned back on. Delete removes it. Stopping and deleting are different acts and both are one click away.

The same thing over the API

Agents set these up the way they use everything else, and the call is logged like any other write — so a cron created by an agent appears in the API log below, attributed to that agent.

# create — the agent is made on the first fire if it does not exist
POST /api/crons?from=$AM_ID
{
  "name":         "nightly deploy check",     // the JOB's name
  "agent":        { "name": "nightly-index", "cli": "claude" },
  "prompt":       "Check last night's deploy log…",
  "schedule":     { "cron": "0 9 * * *", "tz": "Europe/Zurich" },
  "runOnRestart": true
}
→ 201 { "id": "cron_7f3a", "next": "2026-08-20T07:00:00.000Z" }

# list, with how each one last went
GET  /api/crons
→ 200 { "crons": [ { "id": "cron_7f3a", "name": "nightly deploy check", "agent": "nightly-index",
         "state": "running", "next": "…",
         "last": { "at": "…", "status": "ok", "durationMs": 258000 } } ] }

# fire one by hand — the "after a restart" case
POST /api/crons/cron_7f3a/run?from=$AM_ID     → 202 { "ok": true, "agentCreated": false }

# stop keeps the job; delete removes it
PUT    /api/crons/cron_7f3a?from=$AM_ID  { "state": "stopped" }
DELETE /api/crons/cron_7f3a?from=$AM_ID

The list view

This half is nearly free: /api/operations already records every write with who made it, what it hit, the status and how long it took. One line per call, so a screen holds twenty of them. Rows below are real.

The visual view: connected swimlanes

One lane per agent, time left to right, and the interactions drawn between the lanes. A prompt is an arrow from caller down to target. A finished wait is an arrow back the other way. So the picture shows work going out and attention coming back — which is the thing a flat list cannot show.

// operations.js — log the reads that mean "A waited for B", nothing else
const LOGGED_READS = [/^\/api\/agents\/[^/]+\/wait$/];
const shouldLog = (req) => MUTATING.has(req.method)
  || (req.method === 'GET' && LOGGED_READS.some((re) => re.test(req.path)));

// …and inside record(), drop a wait that carried no news:
// wait is a polling loop — only the call that RESOLVED is an event
if (req.method === 'GET' && responseBody && responseBody.matched === false) return;

Feasibility and loopholes

Where each half is easy because something already exists, and where it is genuinely hard.