Skip to content

docs: update Agent Relay docs for v0.16.0 - #32094

Merged
nickvigilante merged 3 commits into
mainfrom
docs/agent-relay-v0.16.0
Nov 12, 2026
Merged

nickvigilante merged 3 commits into
mainfrom
docs/agent-relay-v0.16.0

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

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. 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:

Refs DOCS-1171

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante nickvigilante self-assigned this Nov 12, 2026
@linear-code

linear-code Bot commented Nov 12, 2026

Copy link
Copy Markdown

DOCS-1171

@matifali matifali left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM Thanks

@BobbyHo
BobbyHo requested a review from Emyrk November 12, 2026 17:00

@dluman dluman left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
nickvigilante force-pushed the docs/agent-relay-v0.16.0 branch from 51d0229 to febe4ac Compare November 12, 2026 18:16
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-v0.16.0 branch from febe4ac to c15b736 Compare November 12, 2026 18:27
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-v0.16.0 branch from c15b736 to 0005c3e Compare November 12, 2026 18:39
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
nickvigilante force-pushed the docs/agent-relay-v0.16.0 branch from 0005c3e to e78de15 Compare November 12, 2026 18:44
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Thanks, @dluman. Done in 96cfad5 on this PR:

  • Every version-gated sentence now reads "Agent Relay v0.16.0 or later". That covers setup.md, troubleshooting.md, configuration.md and claude-code.md.
  • "The latest Agent Relay release" (requirements in index.md and setup.md, plus the module callouts in claude-code.md and cursor.md) and "Current Agent Relay releases" (setup.md, Upgrade from early access) now name v0.16.0 or later.
  • I removed the "v0.15.0 and older" behavior notes from setup.md and troubleshooting.md, because the docs now require v0.16.0.

I made the changes here rather than in #31987 so that #31987 stays scoped to v0.15.0, as discussed in that thread.

Generated by Coder Agents on behalf of @nickvigilante.

Base automatically changed from docs/agent-relay-smaller-fixes to main November 12, 2026 18:50
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
nickvigilante force-pushed the docs/agent-relay-v0.16.0 branch from 96cfad5 to c9e6c1f Compare November 12, 2026 18:50
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:50 — with GitHub Actions Inactive
@nickvigilante
nickvigilante merged commit b974184 into main Nov 12, 2026
29 checks passed
@nickvigilante
nickvigilante deleted the docs/agent-relay-v0.16.0 branch November 12, 2026 18:56
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:56 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 12, 2026

This branch was previously deployed

1 inactive deployment
main — c9e6c1f3 Deployed Nov 12, 2026 by nickvigilante via cla #255214
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants