0005 — Heartbeats on Vercel cron, queue later

• Date: 2026-04-30
• Status: Accepted

Context

Paperclip-style heartbeats let agents wake up on a schedule. We need a trigger source that fires due agents and creates runs. Options: Vercel cron, Inngest, Trigger.dev, our own worker.

Decision

Vercel cron for v1. Migrate to a real queue when we hit any of: sub-minute cadence, fan-out >100 runs/tick, retry/backoff requirements, per-workspace isolation.

Alternatives considered

• Inngest / Trigger.dev. Better long-term but adds a dependency and a billing relationship before we know whether heartbeats are heavily used.
• Own worker on Fly. More control, more ops; not worth it at v1 traffic levels.

Consequences

• The dispatcher must be idempotent. We use runs.idempotency_key = (agent_id, scheduled_at) so a duplicated tick doesn't double-charge an agent's budget.
• The dispatcher's interface (resolve due agents → enqueue runs) is stable across migrations; only the trigger source changes.
• Cron's minimum cadence is 1 minute on Vercel. That's the floor for v1 heartbeats; users wanting tighter loops are explicitly out of scope.