Skip to content

docs: backport Agent Relay docs for v0.16.0 to 2.39 - #32122

Merged
bpmct merged 7 commits into
release/2.39from
docs/agent-relay-backport-2.39
Nov 12, 2026
Merged

bpmct merged 7 commits into
release/2.39from
docs/agent-relay-backport-2.39

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Cherry-picks the Agent Relay docs stack from main to release/2.39, so the 2.39 docs match Agent Relay v0.16.0.

Order PR Change
1 #31834 Claude Code dispatch_deadline
2 #31896 What Agent Relay does with agent readiness (prerequisite, see below)
3 #31984 Reaper startup grace and reap delay
4 #31985 SIEM alert messages for v0.15.0
5 #31986 Missing configuration reference options
6 #31987 Smaller v0.15.0 drift fixes
7 #32094 v0.16.0 updates, and "v0.16.0 or later" throughout

Each commit is git cherry-pick -x of the squash commit on main, in merge order.

On release/2.39 the pages live at docs/ai-coder/agent-relay/, not docs/agent-relay/ (#31645 isn't on this branch). Git's rename detection applied every commit to the old path without conflicts.

Verification:

  • Every relative link and image path in docs/ai-coder/agent-relay/ resolves on this branch.
  • markdownlint, markdown-table-formatter --check, and lint/emdash pass.
  • Compared with main, the pages differ only in path depth (../../ instead of ../) and in edits from main-only PRs that aren't part of this stack, such as docs: cut Coder.AbbreviationFirstUse false positives #31874 and the Premium trial link.
Decision log

Generated by Coder Agents on behalf of @nickvigilante.

coder Bot and others added 7 commits November 12, 2026 18:58
Agent Relay v0.15.0 replaced the fixed 300-second Claude Code spawn
budget with a per-pool `dispatch_deadline`
([agent-relay#147](coder/agent-relay#147)).

- `claude-code.md`: rewrite **Build budget** (default `5m`, `10s` to
`15m`, whole seconds, can't be turned off, sent to Anthropic as the hint
TTL, needs v0.15.0) and add the field to both pool examples.
- `configuration.md`: add `dispatch_deadline` to the Claude Code pool
fields.
- `troubleshooting.md`, `monitoring/siem.md`: drop the fixed 300-second
wording.

Verification notes:
- Checked against `internal/services/serviceclaudecoderunners`
(`parseDispatchDeadline`, `poller.go` constants) at v0.15.0 (`9b96578`).
- The old text said Agent Relay returns a missed-budget session as
**retryable**. In v0.15.0, Claude requests use `TerminalOnDeadline`
([agent-relay#138](coder/agent-relay#138)), so a
failure at or after the deadline is nacked non-retryable. The page now
says Agent Relay "reports the failure" and doesn't claim either way.

Stack 1/5. Review and merge in order:
- #31834
- #31835
- #31836
- #31837
- #31838

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
(cherry picked from commit f457b34)
## Summary

Updates Agent Relay documentation to reflect workspace agent lifecycle handling, startup failure behavior, and configuration changes introduced in v0.15.0 and coder/agent-relay#155.

- Clarifies that workers must wait for workspace setup using `coder_script_order`, with examples from the registry modules.
- Documents setup timeout requirements and pool-specific budgets: startup grace for Cursor and build budget for Claude Code.
- Explains startup failures and timeouts, including faster failure detection (~1 minute) and Claude Code's one-retry behavior in versions newer than v0.15.0.
- Documents the known limitation where claimed prebuilds remain `idle` after setup failures.
- Adds `--reap-startup-grace` configuration, including its 15-minute default and interaction with `dispatch_deadline`.
- Updates troubleshooting guidance with lifecycle states, failure reasons, and relevant log fields.
- Corrects Cursor deadline references and the SIEM handoff log message to `workspace built, runner handoff`.

Docs only; five files changed. No runtime behavior changes.

## Testing

- `make lint/markdown` — passed
- `make lint/emdash` — passed
- `make fmt/markdown` — completed
- Verified configuration options and failure reasons against Agent Relay source.

Refs:
- https://linear.app/codercom/issue/RELAY-67
- https://linear.app/codercom/issue/DOCS-1473

(cherry picked from commit a0b595b)
Agent Relay v0.15.0 made the reaper's 15-minute startup window
configurable
([agent-relay#152](coder/agent-relay#152)) and
added a reap delay
([agent-relay#134](coder/agent-relay#134)).

- `configuration.md`: add `--reap-startup-grace` (Helm
`reapStartupGrace`) and `--reap-delay`, plus the per-pool `reap_delay`
field, under an intro that says how the two options differ. The Cursor
`dispatch_deadline: 0` row now points at the startup grace.
- `setup.md`: fix the script-ordering note and **Workspace lifecycle**,
which hardcoded 15 minutes and said failed builds are deleted "on the
next sweep". **Workspace lifecycle** now states the 30-second gap
between sweeps, and **Choose cleanup settings** maps each goal to its
setting.
- `cursor.md`: fix the **Build deadline** bullet and the `pending`
lifecycle row.
- `troubleshooting.md`: the "session ended but its workspace remains"
row mentions the reap delay.
- `monitoring/index.md`: add the `delayed` verdict to
`agent_relay_reaper_verdicts_total` and define it as a wait before
`delete` or `failed`.

Verification notes:
- The chart has **no `reapDelay` value** at v0.15.0 (only
`reapStartupGrace`; checked `values.yaml` and `templates/_helpers.tpl`),
so the docs say to set `CODER_AGENT_RELAY_REAP_DELAY` through
`extraEnv`.
- Pending or starting builds wait `max(grace, dispatch_deadline)`. A
finished build whose runner reports `pending` or nothing fails after the
grace alone (`workspacereaper/lifecycle.go`).
- The reap delay counts from the latest build's `Job.CompletedAt`, not
from the worker's exit, so a session that ran longer than the delay gets
no extra time (`reapDeadline` in `workspacereaper/reaper.go`).
- `delayed` is only a metric label. A sweep records it when the verdict
is `delete` or `failed` but the delay hasn't passed. The `Verdict` type
has only `keep`, `delete`, `failed`, and `stuck`.
- The reaper sleeps 30 seconds after it sweeps every pool, rather than
running on a fixed ticker (`sweepLoop` in `servicereaper/reaper.go`).

Stack 2/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Bobby Ho <bobby@coder.com>
(cherry picked from commit 75574df)
Updates `monitoring/siem.md` to the log messages Agent Relay v0.15.0
writes.

| Old `msg` | v0.15.0 `msg` |
|---|---|
| `workspace ready, runner handoff` | `workspace built, runner handoff`
([agent-relay#154](coder/agent-relay#154)) |
| `workspace build passed the session deadline, reporting retryable and
deleting` | `workspace build passed the session deadline, reporting
failure` (also lists `workspace build succeeded after the session
deadline`) |
| `workspace build failed, reporting retryable and deleting` |
`workspace build failed` |
| `delete workspace failed, leaving for reconciliation` | `delete
workspace failed, leaving it for the reaper` |

The PR also adds the `agent_lifecycle` field, which appears on the
handoff record and on reaper records.

Verification notes:
- Every other quoted `msg` in `siem.md` was checked by grepping
`internal/` at `9b96578` and still matches.
- `leaving for reconciliation` doesn't exist at v0.15.0. Its replacement
comes from `Dispatcher.deleteWorkspace`.

Stack 3/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
(cherry picked from commit b5c43f8)
…31986)

Brings `configuration.md` closer to Agent Relay v0.15.0 and answers
review questions about repo-scoped Cursor pools.

- The Cursor `repo_url` pool field. The row says the template clones the
repository before the worker starts, and links to **Source control** in
`cursor.md`.
- `cursor.md` **Source control**: when to set `repo_url`, a two-pool
example, and a link to Cursor's any-repo pools docs for routing, which
Cursor decides.
- Helm values: a commented YAML example with defaults replaces the
table.
- Removes the HTML source comment at the top of `configuration.md`,
which named the private repository, internal paths, and a Linear issue.

Per review, this PR no longer documents the status page, its TLS
options, or `--dangerous-allow-parameter-credential-transport`.

Verification notes:
- `repo_url`: agent-relay
`internal/services/servicecursorworkers/cursorworkers.go`
(`repoOwnerName`, `RegisterPool`) and `dispatch.go` (`buildParameters`),
plus the `agent-relay-cursor` module README, which says the template
must clone `agent_relay_cursor_repo_url`.
- Helm defaults: `helm/coder-agent-relay/values.yaml`.
- `reapStartupGrace` is covered in 2/5. `reapDelay` has no Helm value
(see 2/5).

Stack 4/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
(cherry picked from commit af41767)
Smaller fixes so the Agent Relay docs match v0.15.0.

- `slack.md`: idle release comes from the pool's `idle_release_timeout`.
Agent Relay sets `agent_relay_claude_code_release_idle_session_min` on
every build, so the module's `release_idle_session_min` input is only a
fallback (confirmed in the `agent-relay-claude-code` module's
`main.tf`). This matches `claude-code.md`.
- `setup.md`: replace "release binaries aren't published yet".
`.github/workflows/release.yaml` builds `linux` and `darwin` binaries
for `amd64` and `arm64`, plus `checksums.txt`, on tags (there is no
goreleaser config).
- `setup.md` step 6: check `credential_transport=secrets`, as the
agent-relay README says.
- `setup.md`, `index.md`: say which features need v0.15.0.
- `setup.md` **Start the worker after workspace setup**: point to the
agent-ready and runner-up metrics.
- `monitoring/index.md`: add `reaper_sweeps_total`,
`reaper_sweep_seconds`, `reaper_claim_to_runner_up_seconds`,
`reaper_claim_to_agent_ready_seconds`
([agent-relay#154](coder/agent-relay#154)),
`claude_code_polls_total`, `claude_code_last_poll_timestamp_seconds`,
`claude_code_nacks_total`, `claude_code_pool_sessions`,
`claude_code_issued_to_claimed_seconds`,
`claude_code_queue_wait_seconds`, and the
`client_platform`/`spawn_reason` labels on `work_orders_claimed_total`.
- `configuration.md` **Pin a template version**: unpinned rebuilds move
to the active version
([agent-relay#135](coder/agent-relay#135)), and
a refused rebuild is non-retryable
([agent-relay#136](coder/agent-relay#136)).

Verification notes:
- Rebuild errors: the code treats both `400` and `403` as non-retryable
(`dispatcher.go`, `retryable := ... != 400 && != 403`), so the docs
mention both.
- The release workflow creates a **draft** GitHub Release
(`softprops/action-gh-release`, `draft: true`). The v0.15.0 release is
now published, but coder/agent-relay is an internal repository, so
customers can't see GitHub release assets. Needs a decision on where
binaries are distributed before this wording ships.

Stack 5/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
(cherry picked from commit 0313949)
Brings the Agent Relay docs up to v0.16.0, per Atif's request for a pass
against the new release.

Of the seven PRs in v0.16.0, only
[agent-relay#155](coder/agent-relay#155) changes
behavior users see. `main` already described most of it ahead of the
release (#31896) as "newer than v0.15.0". This PR fills the remaining
gaps:

- `setup.md`, `troubleshooting.md`: "newer than v0.15.0" becomes
"v0.16.0 and later". Both pages now say Claude Code skips its one retry
when the failure comes later than `dispatch_deadline` after the build
was created.
- `setup.md` **Workspace lifecycle**: a row for failed or timed-out
startup scripts, and a note that these don't wait for the startup grace.
- `configuration.md` `--reap-startup-grace`: the "fails after this
grace" bullet notes the faster startup-script failure.
- `claude-code.md` **Build budget**: when a build succeeds but the
runner never starts, Anthropic retries only on the session's first
delivery and only within `dispatch_deadline`. Otherwise the session
fails. In v0.15.0 that nack was always retryable.

Verification notes (agent-relay `v0.15.0...v0.16.0`):
- `serviceclaudecoderunners/reap.go`: for a `pending` runner, `retryable
= !redelivered(attempt) && (dispatchDeadline == 0 || obs.Age <
dispatchDeadline)`. `obs.Age` counts from the latest build's creation,
not from the work order's issue.
- `workspacereaper/reaper.go` `confirmStartupFailure`: the first
`pending` read after `start_error` or `start_timeout` is stored. A later
sweep confirms only when its sample's `CollectedAt` is newer, and a
sweep that re-reads the same sample doesn't reset it. So the docs say
"two `pending` reads, the second from a newer sample", not "two sweeps
in a row".
- `workspacereaper/lifecycle.go` `StartupFailure`: applies only to
running builds whose status is `pending`.

Not documented:
- The example templates (agent-relay#157), because the repository is
internal.
- The older-coderd `include_agent_metadata` detection fix
(agent-relay#146), which is a bug fix with no setting or behavior
change.
- The agent lifecycle in nack failure details, a minor diagnostic
change.

Stack 6/6. Review and merge in order:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents on behalf of @nickvigilante.

(cherry picked from commit b974184)
@nickvigilante nickvigilante self-assigned this Nov 12, 2026
@github-actions

Copy link
Copy Markdown
Contributor

👋 Hey @nickvigilante!

This PR is targeting the release/2.39 release branch, but its title does not start with fix: or fix(scope):.

Only bug fixes should be cherry-picked to release branches. If this is a bug fix, please update the PR title to match the conventional commit format:

fix: description of the bug fix
fix(scope): description of the bug fix

If this is not a bug fix, it likely should not target a release branch.

@bpmct
bpmct merged commit 8e10d46 into release/2.39 Nov 12, 2026
54 of 55 checks passed
@bpmct
bpmct deleted the docs/agent-relay-backport-2.39 branch November 12, 2026 20:01
@bpmct
bpmct temporarily deployed to docs-preview November 12, 2026 20:01 — with GitHub Actions Inactive
bpmct pushed a commit that referenced this pull request Nov 12, 2026
)

The 2.39 docs at coder.com/docs/v2.39 haven't updated since 2026-11-09:
every hourly publish of `release/2.39` since 21:23 UTC that day has
failed, 92 runs and counting. The docs sync builds 2.39 strictly and
stops on one broken link:

```
DocSyncError: docs sync found 1 blocking issue group(s):
1 inter-doc link(s) resolve to no synced page:
  admin/templates/extending-templates/index.md -> admin/workspaces/devcontainers/customizing-dev-containers.md
```

The backport in #31796 (`1b0fab74f6`) carried over `main`'s link to
`admin/workspaces/devcontainers/customizing-dev-containers.md`, but on
2.39 that page still lives at
`user-guides/devcontainers/customizing-dev-containers.md`. This points
the link there. It also unblocks #32122's Agent Relay docs, which merged
into `release/2.39` today and can't publish until this lands.

Testing: I ran the docs-engine sync in single-version publish mode
against `release/2.39` before and after this change. Before, it reported
the one unmapped link above; after, it reports none (495 pages, 330
images). The new target has a route in 2.39's `docs/manifest.json`, and
the relative path resolves from the source file.

---

🤖 Built with AI assistance.

This branch was previously deployed

1 inactive deployment
docs-preview — f0e4adc8 Deployed Nov 12, 2026 by bpmct via cleanup #4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants