Files
coder/coderd/database/dbmock
Thomas Kosiewski 8620361fcc feat(coderd): run chat automation schedules (#30160)
Part of CODAGT-1211. Part of CODAGT-1135.

> Stack: PR 7a of "Automations for Coder Agents", on top of 1210 5b
(#30134, `tk/codagt-1210b-automations-new-chat`). Run now (`POST
.../runs`) is split into PR 7b (#30166) on top of this one, which closes
CODAGT-1211.

Schedule automations now run. Every coderd instance scans for due
schedules at start and every 30 seconds, and publishes each occurrence
through the existing `Publish` paths (existing_chat `SendMessage(queue)`
and new_chat `Create`, with their `AdmitInTx` callbacks). There is no
second admission path.

## How a scan works

1. An unlocked read returns enabled schedule automations whose cursor
(`schedule_next_run_at`) is due, in pages of 500 by (cursor, id) until a
short page. It leaves out inactive or deleted owners and existing_chat
targets that are gone or archived.
2. The `chat-automations` experiment is evaluated once per owner per
tick, outside any callback. Owners with it off are dropped without a
cursor write. `Publish` checks the experiment for the owner again before
the transaction (webhooks map that refusal to 404, like the handler's
own check).
3. A cursor more than 60 seconds (the grace window) old is missed: a
guarded write moves it to the next future time, nothing is published,
and nothing is replayed.
4. Otherwise `Publish` runs (up to eight occurrences at once, so one
slow hook or lock wait does not hold back the rest) with the observed
revision and cursor. The pre-check refuses a stale or expired occurrence
before any hook runs. Under the chat and automation locks, the callback
requires the same revision and cursor, reads the clock after the locks,
requires the occurrence to be due and within grace, and moves the cursor
to the first cron time after that read in the same transaction.
5. A busy chat with `skip`, a full queue or automation share, a hook
denial, lost permission, or an occurrence that expired while waiting for
a lock skips the occurrence with the same guarded write and an info log.
A stale, disabled, or deleted automation is left alone. Other errors
keep the cursor, so the next scan retries within grace. That includes an
experiment-off refusal from `Publish`, because the evaluator also
reports a failed read as off.

New chats created by a schedule are titled with the occurrence's
scheduled time in the schedule's time zone, for example `Tokyo digest
2026-09-30 08:14 JST` (the ticket says acceptance time; the two differ
by at most the grace window, and the scheduled time cannot drift across
a minute while hooks or locks run). Webhook titles stay in UTC. Each
such chat gets an audit entry as created by the automation owner, with
the automation and input ids, like the chats the webhook endpoint
creates.

## Decisions reviewers should check

- **Clock (deviates from the ticket's "fresh database clock").** The
callback reads the injected quartz clock after the chat and automation
locks are held, not transaction-start `now()`. The ticket also requires
fake-clock tests, and the lower layers already read the clock after
locks. Exactly-once rests on the revision and cursor tuple, not on time.
Inter-instance clock skew cannot cause a double acceptance or a replay:
an acceptance commits only together with the conditional cursor write
under the automation lock, and every cursor write moves the cursor
strictly forward (`advanceAutomationSchedule` refuses a next run at or
before the cursor). A clock that is off by `d` only shifts the
acceptance window to `[cursor-d, cursor+grace+d]` in true time; a clock
that runs ahead can skip occurrences within `d`. See the comment on
`checkAutomationOccurrence` and the `CursorOnlyMovesForward` test.
Swapping in `clock_timestamp()` later is a one-line change.
- **Authorization of the cursor write.**
`AdvanceChatAutomationScheduleCursor` follows the object pattern of
`ConsumeChatAutomationWebhookByID` and `UpdateChatAutomationByID`: the
dbauthz wrapper loads the automation and authorizes `update` on it. The
scanner and the callback call it as chatd, so the chatd subject gains
`update` on `chat_automation` (it already had `read`). This is the
smallest grant; chatd still cannot create or delete automations (pinned
in `TestAsChatd`), and owner-only changes stay in the chatd automation
service. No 1207 migration is touched.
- **Narrow write.** The query sets only `schedule_next_run_at` and
`updated_at`, guarded by `id`, `kind = 'schedule'`, `enabled`, the
observed `schedule_revision`, and the observed cursor. It never touches
owner-controlled fields or the revision.
- **Known limitation (CODAGT-1234).** Two replicas that read the same
due row can both reach the `user_prompt_submit` hook before one loses
under the lock; only one message or chat commits. This matches the lower
layer's best-effort unlocked pre-check for webhooks. A claim-first
cursor move would break the ticket's retry-within-grace rule or the
forward-only cursor, so a lease column is proposed as a follow-up.
- The schedule tests run their servers through dbauthz, so they use the
chatd subject's real permissions (they fail without the grant).

## Tests

`coderd/x/chatd/automation_schedules_internal_test.go` uses a mock
clock, real Postgres, and a second connection that holds row locks
(waiting on `pg_stat_activity`): two instances accept one occurrence
(existing_chat, and new_chat with no orphan chat); busy `skip`,
automation share full, and queue full each advance the cursor once; a
cron edit rolls back an in-flight acceptance; restart after missed
intervals publishes nothing, restart within grace accepts once; previews
match accepted runs; an occurrence that expires while waiting for a lock
is not accepted; a DST change keeps 09:00 wall-clock time; the
experiment off gets no run (scan and Publish); the cursor only moves
forward; the loop scans at start.

Dogfood UAT ran on a real dev instance through Coder Agents and passed:
a one-minute schedule delivered one message per minute with no browser
open, a busy chat skipped its occurrence, disable stopped runs and
re-enable did not replay, new_chat titles used Asia/Tokyo, two coderd
instances produced no duplicates, and downtime was not replayed.

## Size

About 994 hand-written lines (about 560 of them tests). Generated:
`queries.sql.go`, `querier.go`, `dbmetrics`, `dbmock` (181 lines).

ARCHITECTURE.md prose was drafted by an agent at the user's request; the
user will review it.

---
_Generated with [`xum`](https://github.com/coder/xum) • Model:
`anthropic:claude-opus-5-5` • Thinking: `high`_
2026-10-02 15:54:52 +00:00
..