Repository navigation
docs: update Agent Relay docs for v0.16.0 - #32094
Merged
Merged
Conversation
This was referenced Nov 12, 2026
BobbyHo
approved these changes
Nov 12, 2026
dluman
approved these changes
Nov 12, 2026
dluman
left a comment
Collaborator
There was a problem hiding this comment.
Need to ensure the guidance throughout reads "v0.16.0 or later" -- some does, some doesn't. That's in another PR in the stack, so once that's good to go this will be a-OK.
nickvigilante
added a commit
that referenced
this pull request
Nov 12, 2026
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>
nickvigilante
added a commit
that referenced
this pull request
Nov 12, 2026
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>
nickvigilante
force-pushed
the
docs/agent-relay-v0.16.0
branch
from
November 12, 2026 18:16
51d0229 to
febe4ac
Compare
nickvigilante
force-pushed
the
docs/agent-relay-v0.16.0
branch
from
November 12, 2026 18:27
febe4ac to
c15b736
Compare
nickvigilante
force-pushed
the
docs/agent-relay-v0.16.0
branch
from
November 12, 2026 18:39
c15b736 to
0005c3e
Compare
nickvigilante
added a commit
that referenced
this pull request
Nov 12, 2026
…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>
nickvigilante
force-pushed
the
docs/agent-relay-v0.16.0
branch
from
November 12, 2026 18:44
0005c3e to
e78de15
Compare
Collaborator
Author
|
Thanks, @dluman. Done in 96cfad5 on this PR:
I made the changes here rather than in #31987 so that #31987 stays scoped to v0.15.0, as discussed in that thread.
|
nickvigilante
added a commit
that referenced
this pull request
Nov 12, 2026
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>
nickvigilante
force-pushed
the
docs/agent-relay-v0.16.0
branch
from
November 12, 2026 18:50
96cfad5 to
c9e6c1f
Compare
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
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 changes behavior users see.
mainalready 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 thandispatch_deadlineafter the build was created.setup.mdWorkspace 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.mdBuild budget: when a build succeeds but the runner never starts, Anthropic retries only on the session's first delivery and only withindispatch_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 apendingrunner,retryable = !redelivered(attempt) && (dispatchDeadline == 0 || obs.Age < dispatchDeadline).obs.Agecounts from the latest build's creation, not from the work order's issue.workspacereaper/reaper.goconfirmStartupFailure: the firstpendingread afterstart_errororstart_timeoutis stored. A later sweep confirms only when its sample'sCollectedAtis newer, and a sweep that re-reads the same sample doesn't reset it. So the docs say "twopendingreads, the second from a newer sample", not "two sweeps in a row".workspacereaper/lifecycle.goStartupFailure: applies only to running builds whose status ispending.Not documented:
include_agent_metadatadetection fix (agent-relay#146), which is a bug fix with no setting or behavior change.Stack 6/6. Review and merge in order:
Refs DOCS-1171