feat: scheduled (cron) triggers for agents — closes #186

[ishaan-berri]

Why

Closes #186. Today every LAP session is started by an external trigger (human chat, Slack/Linear webhook, POST /agents/{id}/session). There's no native way to say "run this agent every day at 9am PT on its own." This blocks daily stargazer outreach, weekly digests, hourly health checks, periodic data syncs — every one of them today has to be poked by an external GitHub Action / Zapier / k8s CronJob.

What

Native scheduled triggers. Add a 5-field cron + IANA timezone to Agent; the worker fires a Session at each scheduled instant.

Schema

• Agent.cron_schedule (nullable 5-field cron)
• Agent.cron_timezone (IANA, default UTC)
• Agent.cron_enabled (toggle, default true)
• Agent.cron_overlap_policy ("skip" only in v1; reserved for "queue" / "parallel")
• Agent.cron_last_fired_at, Agent.cron_next_fire_at (server-managed)
• Index (cron_enabled, cron_next_fire_at) so the scheduler is a single index seek
• Session.trigger ("api" default, "cron" for scheduled runs) so the UI can badge them

Scheduler

src/server/cron.ts → tickCron() runs alongside the existing reconcile + warm-pool ticks in the worker. Each tick:

1. Inside a transaction, claim due agents via raw SELECT … FOR UPDATE SKIP LOCKED
2. Advance each agent's cron_next_fire_at inside the same tx (so a sibling pod won't re-claim on its next tick)
3. Commit the tx — release locks fast
4. Outside the tx, fire each agent's bring-up (warm claim → fall back to cold), tagged trigger="cron"

Bring-up is the same runBringUp the HTTP route already uses — extracted to src/server/session-bringup.ts so both callers share one implementation.

Answering "how does this work with multiple pods?" (the comment on the issue)

This was the open question. State lives in the DB (cron_next_fire_at column), not in any in-memory APScheduler instance. Concurrency is enforced by Postgres row locks:

• Two pods wake up at the same instant → both run SELECT … FOR UPDATE SKIP LOCKED
• Pod A grabs Agent X's lock; Pod B sees Agent X is locked and skips it (that's what SKIP LOCKED does — return rows that aren't currently locked)
• Pod A advances cron_next_fire_at and commits → Pod B's next tick won't see Agent X because the next-fire instant is now in the future

No leader election, no Redis, no Zookeeper. Just Postgres. Verified locally with a race test (Promise.all([tickCron(), tickCron()]) against a due row): exactly one pod fires, the other returns fired: 0.

API

PATCH /api/v1/managed_agents/agents/{id} accepts cron_schedule, cron_timezone, cron_enabled, cron_overlap_policy.

• Empty string cron_schedule clears the schedule (sets DB to NULL)
• Invalid cron string → 400 with the parser's error message
• Invalid timezone → 400 with a hint about IANA names
• Schedule or timezone change recomputes cron_next_fire_at server-side so the new cadence takes effect immediately

UI

Inline editor on the agent settings page — Schedule row next to Env vars.

Collapsed (read-only):

Schedule    Weekdays at 9am (America/Los_Angeles)  [enabled]   ✏ Edit    last: 5/18/2026, 9:24:50 AM
                                                                          next: 5/19/2026, 9:24:50 AM

Expanded (editing):

Schedule  ┌──────────────────────────────────────────────────────────┐
          │ Cron expression                                           │
          │ [ 0 9 * * 1-5                                          ]  │
          │ Weekdays at 9am                                           │
          │                                                           │
          │ [Every 5 minutes] [Hourly] [Daily at 9am]                 │
          │ [Weekdays at 9am] [Weekly (Monday 9am)]                   │
          │                                                           │
          │ Timezone                                                  │
          │ [ America/Los_Angeles                                  ▾] │
          │                                                           │
          │ [✓] Enabled                                               │
          │                                                           │
          │ [ Save ]   ✕ Cancel                                       │
          └──────────────────────────────────────────────────────────┘

Sessions list badges cron-driven runs with a cron pill alongside the status.

(Screenshots saved locally at /tmp/cron-collapsed.png and /tmp/cron-expanded.png — happy to drag-and-drop them onto the PR after merge or via a follow-up comment.)

Test plan

• Unit tests for parse + next-fire (node --import tsx --test scripts/cron-parse.test.mjs) — 9 assertions, all pass
• npx tsc --noEmit clean
• npx eslint clean on changed files
• npx next build succeeds (no breaking changes to existing routes)
• Migration applies cleanly against fresh Postgres
• PATCH /agents/{id} happy path: schedule set → cron_next_fire_at populated
• PATCH invalid cron string → 400
• PATCH invalid timezone → 400
• PATCH empty cron_schedule → both fields nulled
• tickCron with a due agent → fires + Session row created with trigger="cron"
• Two concurrent tickCron calls → exactly one fires (FOR UPDATE SKIP LOCKED verified)
• Overlap policy "skip" → second fire skipped while previous still active
• End-to-end test against a live k8s sandbox (deferred to staging)

Out of scope for v1

• Per-run retry policy on bring-up failure
• Backfill on cron_enabled = false → true resume
• Manual "run now" button (separate issue)
• cron_overlap_policy = "queue" | "parallel" (column exists, only "skip" accepted)

[greptile-apps]

Greptile Summary

This PR adds native scheduled (cron) triggers for agents: new schema columns on Agent and Session, a Postgres-based multi-pod-safe scheduler (tickCron with SELECT … FOR UPDATE SKIP LOCKED), bring-up logic extracted to a shared module, and a UI inline editor. The architecture is sound \u2014 state lives in the DB, no leader election required \u2014 but there are two logic bugs in the Phase 1 / Phase 2 handoff inside tickCron.

• cron_last_fired_at is committed inside the claim transaction before the overlap check runs outside it; when a run is skipped due to cron_overlap_policy = \"skip\", the column still shows now with no corresponding Session row, misleading the UI "last fired" display.
• When computeNextFireAt throws for an agent with a corrupted schedule (the catch branch sets cron_enabled = false), the agent remains in the claimed list returned from the transaction and is still passed to fireCronRun in Phase 2 \u2014 spawning one unintended session despite the explicit "disabling" log message.

Confidence Score: 3/5

The core scheduler has two logic gaps in its Phase 1 / Phase 2 handoff that produce incorrect DB state and unintended session creation; safe to merge only after those are addressed.

Both bugs live in the hot path of the new cron tick. The first means every overlap-skipped firing writes a stale 'last fired' timestamp users can see in the UI. The second means an agent that the code explicitly logs as 'disabling' due to a bad schedule still gets a session spawned for it in the same tick.

src/server/cron.ts — specifically the Phase 1 transaction block (lines ~204-222) and the Phase 2 loop (lines ~238-268) need attention before merging.

Important Files Changed

Filename	Overview
src/server/cron.ts	New scheduler with two logic bugs: cron_last_fired_at is committed before the overlap check (skipped agents get a false timestamp), and agents disabled mid-tick for invalid schedules still fire once in Phase 2.
prisma/migrations/0006_agent_cron_triggers/migration.sql	Additive-only migration (new columns with safe defaults + one index). No column deletions, no data loss risk.
src/server/session-bringup.ts	Logic extracted from the session POST route into a shared module — functionally identical, just moved to enable reuse by the cron tick.
src/app/api/v1/managed_agents/agents/[agent_id]/route.ts	PATCH handler extended with cron field validation; parseCronSpec called server-side for immediate 400 on bad cron/tz pair, and cron_next_fire_at recomputed on schedule/timezone change.
src/components/cron-editor.tsx	New UI component for inline schedule editing; validation is server-side only with errors surfaced via onError prop. Clean implementation.
src/worker/index.ts	Worker tick wired to call tickCron() alongside existing reconcile and warm-pool ticks; result logged in heartbeat.
src/server/cron-bringup.ts	Thin shim that sets a cron-specific title and delegates to runBringUp; keeps cron.ts free of API-route imports.
prisma/schema.prisma	Six new nullable/defaulted cron columns on Agent plus trigger on Session; composite index on (cron_enabled, cron_next_fire_at) matches the scheduler query exactly.
src/server/types.ts	ApiAgent and ApiSession extended with cron fields; extensive cast-through-unknown pattern due to pre-generate Prisma client compatibility.

_{Reviews (1): Last reviewed commit: "test(cron): unit cover parser, next-fire..." | Re-trigger Greptile}

[greptile-apps]

cron_last_fired_at set before overlap check, so skipped runs show a false "last fired" timestamp

cron_last_fired_at = now is committed inside the claim transaction (line 209) for every claimed agent. The overlap check (hasActiveCronRun) runs after the transaction commits (line 250). When the check fires and a previous run is still active, the agent is skipped via continue — no session is created — but cron_last_fired_at already reflects now in the database. The UI then shows "last: X minutes ago" for a run that never happened, with no matching Session row users can inspect.

[greptile-apps]

Agents disabled for invalid schedule are still fired in Phase 2

When computeNextFireAt throws for an agent (invalid schedule mutated between last fire and this tick), the catch block sets cron_enabled = false and cron_next_fire_at = null inside the transaction — correctly preventing future fires. However, the agent is still present in the claimed array returned from the transaction, and Phase 2 iterates over dueAgents without checking cron_enabled. The result is that the "now disabled" agent still gets fireCronRun called, spawning one unintended session. The error log says "disabling" but the code fires anyway.