Repository navigation
docs: backport Agent Relay docs for v0.16.0 to 2.39 - #32122
Merged
Merged
Conversation
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)
Contributor
|
👋 Hey @nickvigilante! This PR is targeting the 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: If this is not a bug fix, it likely should not target a release branch. |
dluman
approved these changes
Nov 12, 2026
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cherry-picks the Agent Relay docs stack from
maintorelease/2.39, so the 2.39 docs match Agent Relay v0.16.0.dispatch_deadlineEach commit is
git cherry-pick -xof the squash commit onmain, in merge order.On
release/2.39the pages live atdocs/ai-coder/agent-relay/, notdocs/agent-relay/(#31645 isn't on this branch). Git's rename detection applied every commit to the old path without conflicts.Verification:
docs/ai-coder/agent-relay/resolves on this branch.markdown-table-formatter --check, andlint/emdashpass.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
agent_lifecyclefield. Without it, those sections would be partial or contradictory on 2.39.docs/manifest. The stack adds no pages, and the 2.39 manifest already routesai-coder/agent-relay.