feat: routines — scheduled and API-triggered agent runs with a zero-cost check gate and real budgets

[saucam]

Closes #54.

What this adds

Routines: saved agent tasks that codeoid runs on a cron or interval schedule, once at a set time, from their own API endpoint, or on demand.

codeoid routine add ci-watch -w ~/src/repo --every 15m \
  --check 'gh run list --branch main --limit 1 --json conclusion --jq ".[] | select(.conclusion==\"failure\")"' \
  --prompt 'CI on main is failing. Find the cause and summarise it in three lines. {{check}}' \
  --guarded --max-cost 1

The design goal is that most scheduled runs cost nothing:

• A routine can have a check, a shell command that runs first. If it prints nothing, the run ends silent: no agent starts and nothing is spent.
• An agent that finds nothing worth reporting replies [SILENT], and you hear nothing.

Every run is an ordinary session. You can open it from the terminal, the web UI or your phone, then approve, continue or fork it.

The daemon enforces the limits, not the model:

• guarded approvals, or an autonomous tool budget;
• a wall-clock limit;
• per-run and per-day spend ceilings (on Claude, for fresh sessions, also a hard stop through the Agent SDK's maxBudgetUsd);
• overlap set to skip or queue;
• catch-up after downtime;
• auto-pause after repeated failures;
• optionally, a git worktree per run.

API trigger. POST /routines/<id>/fire takes a per-routine rt_… token, which can be revoked, is rate-limited, and is stored only as a hash. Its body (up to 16,000 characters) reaches the agent as {{payload}}, delimited as data.

Outcomes:

• Pushes go to devices per the routine's notify policy and carry no content.
• The new routine_end hook fires for every run.

Full guide: docs/routines.md. It covers usage, the safety model, how this compares with Claude Code routines, Cursor Automations and Codex automations, and known limits.

What it does that the cloud products don't:

• runs on your own machine, with your repos and credentials;
• works with any backend;
• a 60-second minimum interval instead of 1 hour;
• a zero-cost check gate;
• real approvals in unattended runs;
• in-flight spend and time limits;
• every run is a live session you can pick up.

Authority model

• A routine is its owner's alone. Names are unique per owner. Anyone else in the tenant gets "not found", by id or by name.
• Scopes: no new one. Routines use the scopes a routine itself exercises:
  • Every routine command except preview needs session:create and session:send, reading included, so read-only watchers can't see prompts, checks or payloads.
  • Saving, firing, re-tokening or resuming a routine that pre-approves work also needs session:approve. That means an autonomous routine, or one with a check (a host shell command nobody approves at run time). Pausing never needs it.
  • Delegated tokens can't change routines. A teammate's share token arrives delegated whatever scopes it carries, so this is what keeps standing authority out of shared hands; no ZeroID scope-profile change is needed.
• Runs act as the owner, and are attributed routine:<name>. Each one starts autonomous only for the run itself: the session steps down to guarded the moment the run ends or parks.
• The check gets a scrubbed environment, the same policy as hooks and backends, and never the daemon's secrets.
• Run sessions are ordinary tenant sessions. The docs say so plainly: watchers can read them, and send-holders can prompt them.

Code tour

• src/daemon/routines/:
  • schedule.ts: croner 10.0.1 (exact pin, MIT, no deps), IANA zones, phase-anchored intervals, stable jitter, strict ISO for --at.
  • store.ts: SQLite tables. A compare-and-set on next_fire_at is the tick lock. History is trimmed, but never today's runs, the last summary, or the last handled run.
  • service.ts: scheduler, admission, check gate, run loop, retention, management API, behind a RoutineHost seam.
  • http.ts: the fire endpoint.
  • wire.ts.
• src/daemon/session-manager.ts:
  • #routineHandle: all authorization.
  • #makeRoutineHost: sessions, worktrees, push, hooks.
• Session.lastAssistantMessage and CanonicalHistoryAccumulator.lastTextBlock: the run summary is the agent's final message.
• maxBudgetUsd is plumbed through TurnOpts to the Claude provider; error_max_budget_usd maps to BUDGET_STOP_MESSAGE.
• Protocol (additive):
  • routine.* messages and results;
  • SessionInfo.managedBy: "routine";
  • push kind "routine".
• CLI: codeoid routine add|edit|ls|show|runs|run [--wait]|pause|resume|rm|cancel|token|preview (src/cli.ts, src/terminal/routine-format.ts).
• Config: routines.*, CODEOID_ROUTINES_ENABLED, CODEOID_ROUTINES_MAX_CONCURRENT, plus a Settings group.

Verification

Tests:

• The full suite passes: 3249 pass, 0 fail, 19 skipped.

• bun run typecheck (root, protocol, core), the web typecheck and biome check are all clean.

• Routine suites: 92 tests.

  • routine-schedule: cron/DST, intervals, once.
  • routine-service: a scripted host with a fake clock, covering every scheduling, gating, budget, outcome, retention and authority-left-behind rule.
  • routine-manager: a real SessionManager on a mock backend, covering scopes, ownership, delegation, the HTTP trigger, worktrees and the hook.
  • routine-format: CLI parsing and output.

• Protocol and schema cases for every routine message, in addition to those 92.

• Mutation-checked guards. I broke each of these in turn and confirmed a test fails:

  • the claimFire CAS;
  • native cap for fresh sessions only;
  • process-group kill;
  • rowid tiebreak;
  • unnamed-park grace;
  • the approve-scope gate;
  • parked spend follow-up;
  • Origin reject;
  • hooks on every run.

  The CAS and process-group guards first survived mutation; I added tests that catch them.

Run live against real Claude, through the real codeoid routine CLI, on an isolated local-mode daemon:

• an empty check → silent, $0;
• a check with output → succeeded with a correct summary;
• a [SILENT] reply → silent;
• an --every 1m schedule firing on its own;
• curl to the API endpoint → 202; a bad token → 401; an Origin header → 403;
• a guarded write → needs_attention and the file not created. After codeoid approve, the file was written and the run's cost and summary updated;
• --max-cost 0.01 → over_budget;
• the routine_end hook payload;
• a past --at rejected;
• the cron default timezone.

The live runs found five fixes, all included:

• hooks only fired when a push would;
• parked runs stayed at $0;
• token counts excluded cache reads;
• summaries included mid-turn narration;
• summaries mentioned unrelated claude.ai connectors.

Dogfooded on this repo. These routines ran against main:

• ci-watch: silent at $0, because no PR is failing.
• stale-issues: guarded, with the issue list and history from the check. It found 8 open issues that look resolved, 3 with high confidence (Wire multi-provider selection into runtime (Gemini/OpenAI selectable, Claude default) #40, perf: cache MemoryEngine vector matrix instead of reloading per recall #5, Protocol hardening (audit, medium): inbound zod validation, unknown-type default, WS payload/backpressure limits #15). The list is for a maintainer to act on; nothing was closed.
• docs-drift: autonomous, in a worktree. It found and committed 6 real CLAUDE.md errors: the retry module that no longer exists, 17 scopes rather than 8, the missing llamacpp backend, scrollback defaults, and two more. That commit is in this PR (96e1e99). Its scope count was one short (there are 18), corrected in 256222a.

Dogfooding also found that the 16 KB check-output cap was too small; it is now 64 KB, with an honest truncation note.

Audit rounds:

• Round 1 (correctness, security, cross-repo impact):

  • security H1: the check inherited daemon secrets;
  • security H2: teammates could steer others' routines;
  • correctness H1–H3: persistent session reused while parked or busy, prune destroying sessions in use, the since-window dropping items;
  • about 20 Medium and Low items.

  All fixed in 18156d5. Cross-repo: no consumer breaks (details below).

• Round 2:

  • Security High: run sessions are tenant-visible. Resolved by documenting the boundary; the session visibility model is unchanged.
  • Mediums: autonomy left on after a run, reply lost on context rotation, trimming losing the summary and today's spend, a stale abort listener, prune leaks.

  All fixed in d9c9f96.

• Round 3: correctness was clean ("no Critical, High or Medium I would fix before merge"); security found no merge blockers. Its Lows and the send-only docs were folded into 98aad5f.

• Final audit (whole PR, every claim in this body and the docs checked against the code): nothing to change in the code; "ready for human review once" 4 doc and comment fixes went in. Those, plus 20 polish items, are in bd76bb0.

What did not run:

• The web UI against a routine-driven daemon. There is no routine screen yet; run sessions show as ordinary sessions marked routine-managed.
• Push delivery to a real device. The push path is unit-tested only; no device was registered.
• Non-Claude backends live. Codex, Gemini and Qwen routines are covered by the mock-provider tests only.
• A ZeroID-mode daemon. The live runs were local-mode. ZeroID scope and ownership behaviour is covered by tests with ZeroID-shaped AuthContexts.
• The mobile app's handling of kind: "routine". Cross-repo review found the app routes by sessionId and ignores kind.
• Oracle: n/a. codeoid is not in Oracle's enabled_repos.

Follow-ups (not in this PR)

1. A web UI routines screen, and routine tools on /mcp/control and the conductor: feat: routines in the web UI, the conductor, and /mcp/control #383.
2. GitHub and Slack event triggers: feat: event triggers for routines — GitHub, Slack, and generic webhooks #384.
3. Send-only messages should never run autonomously (fix: a message from a token without session:approve never runs autonomously #385). In any autonomous session, a message from a token without session:approve should have its tool calls run guarded. This is not new with this PR, but routines make autonomous sessions more common.
4. Routine ownership (feat: key routine ownership on the human, not the credential's identity #386) keys on the token's subject, which for a codeoid login key is the key's identity. Consider keying on the human principal, if ZeroID carries it.
5. Smaller items:
   • the codeoid-ui TUI's hardcoded scope list is stale (it already was): fix: TUI requests a stale scope list codeoid-ui#40;
   • bump @highflame/codeoid-protocol to the next minor version on release.

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	croner@​10.0.1

View full report

[saucam]

pr-shepherd: CI is green on 98aad5f (iteration 1). All 4 checks passed: daemon-check, web-check, Socket Security: Project Report, Socket Security: Pull Request Alerts. Nothing needed fixing and no commits were pushed. The branch is up to date with main.