Skip to content

docs: fix smaller Agent Relay doc drift for v0.15.0 - #31987

Merged
nickvigilante merged 2 commits into
mainfrom
docs/agent-relay-smaller-fixes
Nov 12, 2026
Merged

nickvigilante merged 2 commits into
mainfrom
docs/agent-relay-smaller-fixes

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

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), 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), and a refused rebuild is non-retryable (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:

Refs DOCS-1171

Generated by Coder Agents.

@nickvigilante nickvigilante added the community Pull Requests and issues created by the community. label Nov 10, 2026
@nickvigilante nickvigilante self-assigned this Nov 10, 2026
@linear-code

linear-code Bot commented Nov 10, 2026

Copy link
Copy Markdown

DOCS-1171

@matifali

Copy link
Copy Markdown
Contributor

Should it now be repurposed for 0.16.0?

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

Throughout, we're adopting "v0.16.0 or later"

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-smaller-fixes branch from 661c611 to 35e7c86 Compare November 12, 2026 18:16
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@dluman @matifali Yes, that's covered by #32094. I wanted to keep each PR scoped individually. I'm going to send one giant backport PR with everything for 2.39.

@nickvigilante
nickvigilante requested a review from dluman November 12, 2026 18:24
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-smaller-fixes branch from 35e7c86 to 60b930a Compare November 12, 2026 18:27
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-smaller-fixes branch from 60b930a to 49f7157 Compare November 12, 2026 18:39
Base automatically changed from docs/agent-relay-config-reference to main November 12, 2026 18:44
coder Bot and others added 2 commits November 12, 2026 18:44
Correct Slack idle release guidance, release binaries, the setup verification log field, and minimum versions. Document missing metrics and active-version rebuilds (coder/agent-relay#135, coder/agent-relay#136, coder/agent-relay#154).
…rsions

Drop the static binaries note; the docs cover the image and Helm chart.
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-smaller-fixes branch from 49f7157 to 30fe17d Compare November 12, 2026 18:44
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@nickvigilante
nickvigilante enabled stacked auto-merge (squash) November 12, 2026 18:44
@nickvigilante
nickvigilante merged commit 0313949 into main Nov 12, 2026
27 of 29 checks passed
@nickvigilante
nickvigilante deleted the docs/agent-relay-smaller-fixes branch November 12, 2026 18:50
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:50 — 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 — 30fe17df Deployed Nov 12, 2026 by nickvigilante via cla #255210
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants