Files
coder/coderd/database/queries/chatautomations.sql
T
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

198 lines
5.2 KiB
SQL

-- name: InsertChatAutomation :one
INSERT INTO chat_automations (
id,
organization_id,
owner_id,
name,
created_by_chat_id,
kind,
enabled,
target_mode,
target_chat_id,
new_chat_model_config_id,
reasoning_effort,
when_busy,
webhook_use,
webhook_secret_hash,
webhook_secret_version,
prompt,
schedule_cron,
schedule_time_zone,
schedule_next_run_at,
created_at,
updated_at
) VALUES (
@id,
@organization_id,
@owner_id,
@name,
@created_by_chat_id,
@kind,
@enabled,
@target_mode,
@target_chat_id,
@new_chat_model_config_id,
@reasoning_effort,
@when_busy,
@webhook_use,
-- A nil []byte is sent as an empty bytea, not NULL. Store NULL so
-- automations without a secret satisfy chat_automations_kind_shape.
NULLIF(@webhook_secret_hash::bytea, ''::bytea),
@webhook_secret_version,
@prompt,
@schedule_cron,
@schedule_time_zone,
@schedule_next_run_at,
@created_at,
@updated_at
)
RETURNING
*;
-- name: GetChatAutomationByID :one
SELECT
*
FROM
chat_automations
WHERE
id = @id::uuid;
-- name: DeleteChatAutomationByID :exec
DELETE FROM
chat_automations
WHERE
id = @id::uuid;
-- name: GetChatAutomationsByIDsForUpdate :many
-- Locks the given automations in ascending id order so concurrent
-- lockers always acquire automation row locks in the same order.
-- Missing ids are not returned.
SELECT
*
FROM
chat_automations
WHERE
id = ANY(@ids::uuid[])
ORDER BY
id
FOR UPDATE;
-- name: GetChatAutomationsByOrganizationID :many
SELECT
*
FROM
chat_automations
WHERE
organization_id = @organization_id::uuid
ORDER BY
created_at DESC,
id DESC;
-- name: CountChatAutomationsByOwnerID :one
-- Counts the automations owner_id owns across all organizations.
SELECT
COUNT(*)
FROM
chat_automations
WHERE
owner_id = @owner_id::uuid;
-- name: UpdateChatAutomationByID :one
UPDATE
chat_automations
SET
name = @name,
prompt = @prompt,
target_chat_id = @target_chat_id,
new_chat_model_config_id = @new_chat_model_config_id,
reasoning_effort = @reasoning_effort,
when_busy = @when_busy,
schedule_cron = @schedule_cron,
schedule_time_zone = @schedule_time_zone,
schedule_revision = @schedule_revision,
schedule_next_run_at = @schedule_next_run_at,
enabled = @enabled,
queue_generation = @queue_generation,
updated_at = @updated_at
WHERE
id = @id::uuid
RETURNING
*;
-- name: UpdateChatAutomationWebhookSecretByID :one
-- Replaces the webhook secret hash and increments the secret version. The
-- single-use marker webhook_consumed_at is intentionally kept.
UPDATE
chat_automations
SET
webhook_secret_hash = @webhook_secret_hash,
webhook_secret_version = webhook_secret_version + 1,
updated_at = @updated_at
WHERE
id = @id::uuid
RETURNING
*;
-- name: ConsumeChatAutomationWebhookByID :execrows
-- Marks an unconsumed single-use webhook as consumed. It affects no row
-- when the automation is not a single-use webhook or was already
-- consumed, so callers can refuse the delivery.
UPDATE
chat_automations
SET
webhook_consumed_at = @now::timestamptz,
updated_at = @now::timestamptz
WHERE
id = @id::uuid
AND kind = 'webhook'
AND webhook_use = 'single'
AND webhook_consumed_at IS NULL;
-- name: GetDueChatAutomationSchedules :many
-- Returns enabled schedule automations whose cursor is at or before now,
-- oldest cursor first, starting after the (after_next_run_at, after_id)
-- keyset so callers can page through every due row. Automations of
-- inactive owners and existing_chat automations whose target chat is gone
-- or archived are left out. It takes no locks: publishing rechecks each
-- row under the chat and automation locks.
SELECT
chat_automations.*
FROM
chat_automations
JOIN users ON users.id = chat_automations.owner_id
LEFT JOIN chats ON chats.id = chat_automations.target_chat_id
WHERE
chat_automations.kind = 'schedule'
AND chat_automations.enabled
AND chat_automations.schedule_next_run_at <= @now::timestamptz
AND (chat_automations.schedule_next_run_at, chat_automations.id) > (@after_next_run_at::timestamptz, @after_id::uuid)
AND users.status = 'active'
AND NOT users.deleted
AND (
chat_automations.target_mode = 'new_chat'
OR (chats.id IS NOT NULL AND NOT chats.archived)
)
ORDER BY
chat_automations.schedule_next_run_at,
chat_automations.id
LIMIT
@limit_count::int;
-- name: AdvanceChatAutomationScheduleCursor :execrows
-- Moves the schedule cursor of an enabled schedule automation from the
-- observed occurrence to next_run_at. It affects no row when the schedule
-- revision or the cursor changed since they were observed, so exactly one
-- caller moves the cursor past each occurrence. A NULL next_run_at means
-- no occurrence is pending.
UPDATE
chat_automations
SET
schedule_next_run_at = sqlc.narg('next_run_at')::timestamptz,
updated_at = @updated_at::timestamptz
WHERE
id = @id::uuid
AND kind = 'schedule'
AND enabled
AND schedule_revision = @schedule_revision::bigint
AND schedule_next_run_at = @observed_next_run_at::timestamptz;