feat(agents): heartbeat & agent triggers

[OchnikBartek]

Summary

Heartbeat & agent triggers for #44 — an agent can now run itself with nobody at the
keyboard. A trigger is a row beside the agent (modelled on AgentExposure, deliberately
outside the portable spec), a once-a-minute heartbeat fires the due ones through the
ordinary run path, and a fired run runs as the trigger's creator with membership
re-resolved each fire.

The branch was cut plan-first (docs/design/heartbeat-triggers-plan.md) and now carries
the full implementation: both schedule triggers (interval and cron) and event
triggers (GitHub / email / LinkedIn / webhook), an in-place cadence editor, optional human
titles, and five UI surfaces.

What it introduces

Two kinds of trigger, one table (agent_triggers, AgentTrigger)

• Schedule (ScheduleKind = interval | cron) — an interval floor of 60s, or a
  crontab expression validated with croniter. next_fire_at is computed on write and
  advanced under the heartbeat's lock.
• Event (EventSource = github | email | linkedin | webhook) — a per-source
  event_config filter and a signing secret sealed through the one vault
  (event_secret_encrypted + secret_key_version), exactly as a channel bot stores its
  secret. An event row has a null next_fire_at; nothing is due until an event lands.
• A trigger_type discriminator and a single shape CHECK (ck_trigger_shape) keep "what
  makes this due" to exactly one answer per row.

The cadence engine — a trigger's cadence can be changed in place (interval↔cron, a
new interval, a new expression) without delete-and-recreate. _resolve_cadence infers the
kind from the fields sent, clears the opposite field, and refuses an unschedulable edit as
a 422 naming the field rather than a 500 from the shape CHECK.

A human title (name, migration 0024) — a trigger is listed by an optional title,
falling back to the agent's name, so two schedules on one agent no longer read identically.

RunSurface.SCHEDULE — a fired run is stamped schedule, a first-class surface in run
history (?surface=schedule) beside web/api/slack/embed. Triggered runs stay in Runs as
well as the new Scheduled view.

The heartbeat — check_agent_triggers_flow (IntervalSchedule(60)) claims due
triggers FOR UPDATE SKIP LOCKED, advances next_fire_at under the lock, and submits each
via run_deployment; run_scheduled_trigger_flow is one fired run. A fire runs as the
creator (membership re-resolved each time), opens one run-log conversation per trigger,
passes no message_history (fires are stateless), and disables-rather-than-retries on a
refusal.

Endpoints

• GET /triggers — org-wide listing (the same shape as the org-wide /runs), feeding the
  chat sidebar and the Activity view.
• GET/POST/PATCH/DELETE /agents/{agent_id}/triggers and
  POST /agents/{agent_id}/triggers/{trigger_id}/run.
• Gated per-resource by agents:run through the registry; a refusal is reported as
  not-found, so agent ids stay unprobeable.

Five UI surfaces

1. Availability tab — TriggersPanel on the agent page, managed at the agents:run
   floor (running an agent, not publishing it).
2. Chat sidebar — a triggers section; a run-less trigger opens its empty run-log
   conversation on click.
3. The form dialog — a cadence builder (hour input, daily / every-N-days / weekly /
   monthly presets, custom weekday selection, raw cron), the title field, and event-source
   configuration.
4. Activity → Scheduled tab — org-wide scheduled/triggered runs.
5. Trigger row & summary — the human-readable cadence ("Every 2 hours",
   "Cron 0 9 * * * (UTC)", "On inbound email") wherever a trigger is listed.

Migrations

0022_agent_triggers → 0023_agent_event_triggers → 0024_agent_trigger_name, chained
onto main's head 0021_drop_channel_tools_bindings. alembic check reports no drift; the
chain applies and rolls back cleanly (tests/test_migrations.py, plus a manual
forwards/back round-trip on a throwaway database).

How it was verified

The branch was merged onto origin/main (0.0.103) in place, so its diff against main is
the feature alone.

• make check green — lint (ruff / ty / eslint / prettier / tsc / i18n / codespell),
  make test (4540 passed, platform-layer coverage 100%), make test-frontend-cov
  (3936 passed), make build-frontend, make docs-build, make audit.
• Migrations — 0022–0024 forward and back, alembic check clean.
• Tests at every layer, including a real-database proof that two heartbeats never
  double-fire one trigger, and that a budget-exhausted fired run is recorded
  budget_exceeded and not retried.

Checks

• Tests cover the new behaviour, and would fail without the change
• make check passes (lint, format, types)
• Platform-layer coverage is still 100%
• No capability was added or changed (triggers are operational state beside the agent,
  not a capability)
• alembic downgrade base && alembic upgrade head works for 0022–0024

Follow-up (tracked as #589)

Two fire()-hardening items are addressed in #589, a pull request stacked on this branch
(base: feat/agent-triggers), rather than in this PR. Both were flagged in review and are
resolved here as triage, with the real fix tracked in #589:

• last_run_id self-overlap. The heartbeat's "skip a trigger whose previous run has
  not reached a terminal status" guard joins on last_run_id, which the child flow writes
  only after execute returns — so while a run is executing the guard still sees the
  previous (terminal) run, and a run slower than the interval can overlap itself. The fix
  is an in-flight marker the heartbeat sets in the same UPDATE that advances
  next_fire_at, cleared by the child in a finally.
• Partial-dispatch batch. One failed run_deployment aborts the heartbeat's dispatch
  loop after the claims are already committed, so the rest of that batch has next_fire_at
  advanced with no run — a missed fire. The fix isolates each dispatch so one failure does
  not drop the others.

Review

All review threads are resolved; the two fire()-hardening findings above are resolved as
triage, with the fix tracked in #589. The design doc stays in the PR: docs/design/ is
exclude_docs-configured engineering material for review, matching four such docs already
on main.

Closes #44

[DEENUU1]

Good plan, and thanks for doing the reading before the code — this is the shape #44 asked for. I checked every code anchor against main and they all hold: RunSurface has no SCHEDULE and surface is a String(16) so no migration; drain() really is CLI-only; execute → prepare → _assemble is the funnel with the budget read inside _assemble; the spec docstring does exclude "where it runs / who may use it"; and exclude_docs: design/ is in mkdocs.yml. That accuracy is most of why the plan is trustworthy.

Answering the five, since they're pointed at me:

1. Creator-gone — yes, auto-disable + audit, and notify an admin. It's the only option that doesn't either retry forever or silently move the bill onto someone who didn't ask for it.
2. Spec vs row — yes, keep it a row. Strongest call in the plan; more inline.
3. Single heartbeat — yes.
4. Output sink — the per-fire conversation works, but see my note in §5: I'd lean to one conversation per trigger rather than one per fire.
5. Email split — yes, cron-only here, email as its own issue.

Two things to sort before implementation, both where the plan leans on the sync precedent. The no-overlap guard needs a column the agent_triggers table doesn't have yet, and "copying check_scheduled_syncs_flow exactly" overstates it — that flow neither locks rows nor submits-and-returns, so both guards are net-new code rather than something to inherit. Details inline.

[DEENUU1]

Second pass, after the revision — this time reading it for how it holds up under load and whether it stretches to other trigger kinds. The revision is honest work: the corrections are folded in rather than papered over, and advancing next_fire_at from now (not from the previous mark) quietly avoids the post-downtime backfill storm that already OOM-killed this worker once (the war story at prefect_app.py:95).

One real hole is left, and it's in the guard we added last round: last_run_id is written only after the run finishes, so the no-overlap check is blind for exactly the window it exists to cover — any run longer than its interval double-fires. Details inline, with a fix that's one column and one lease. The rest is naming things the plan currently leaves implicit: the runner's 5-slot ceiling (PREFECT_RUNNER_LIMIT), that a fire is stateless, that a parked approval stalls the schedule (boundedly), and whether email triggers will ever live in this table. None of those change the architecture — they change what the implementation must not get wrong.

[bll-kacper-wlodarczyk]

Third pass, on the code this time. This is strong work — the refusals are exactly the tests I'd have asked for, the SKIP LOCKED claim is proven on a real database, and disable-not-retry is symmetric across the budget and the authz doors, which was the easiest thing to get wrong.

Three blockers, each with its fix inline: the migration chains off 0012 while main is at 0021, which is single-handedly both red CI jobs; the no-overlap guard still can't see a run in flight (the one open thread from my second pass, now traced through the runner's commit timing); and repointing a trigger's environment 500s because a raw UUID reaches the JSONB audit column. Two smaller suggestions and a stale plan line beside those. The remaining plan-doc notes from my second pass (the parked-approval policy sentence, the email-vs-kind table decision) can ride along in the same push.

[DEENUU1]

Fourth pass, focused on what landed after my last review: the event triggers end to end, the cadence editor, the titles, and the UI surfaces. This is strong work. The secret handling is exactly right — sealed on create, absent from every audit entry and every response, with a test proving precisely that — the webhook answers 202 whether or not there was anything to do so trigger ids stay unprobeable, and the disable-not-retry symmetry now covers access withdrawn mid-run too. The #589 deferrals are fine as triaged.

One thing I'd fix before merging: GET /triggers is a collection listing with no require() gate, and the comment defending that in test_platform_routes.py leans on a claim that isn't true — /runs does carry require(RUNS_VIEW) (backend/app/api/routes/v1/runs.py:42). No live hole today, since every role holds agents:view, but it's our own hard rule and the fix is one line. Beside that: the event-context size cap is applied to the generic webhook but not to GitHub, email or LinkedIn bodies, and a few small nits inline.

[DEENUU1]

Fifth pass, on the last push (bf5c989). Every finding from my fourth pass is addressed the way I asked: GET /triggers now carries require(agents:view) and the route sweep in test_platform_routes.py covers it as a gated call instead of exempting it on a wrong claim about /runs; the clip is hoisted into _clip() and applied to the GitHub, email and LinkedIn bodies, with tests proving the header survives a 10k-character paste; the email and LinkedIn filters casefold both sides; and both stale comments are fixed.

I went looking for something new to hold this on and didn't find it. The rename left no stale references, the gate matches its siblings (GET /agents on agents:view, GET /runs on runs:view), the webhook's create_task has no committed-row hazard because prepare_event_fire writes nothing the task would need to read, and the fields left unclipped (subject, title, author) are all bounded in practice while the deliverer holds the secret. The deferrals stand as triaged: #589 for the fire() hardening, #658 for the inline run-now.

CI is green across the board, e2e included. Approving — good work carrying this through five passes.