Skip to content

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

Closed
coder[bot] wants to merge 2 commits into
docs/agent-relay-config-referencefrom
docs/agent-relay-smaller-fixes
Closed

coder[bot] wants to merge 2 commits into
docs/agent-relay-config-referencefrom
docs/agent-relay-smaller-fixes

Conversation

@coder

@coder coder Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

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/5. Review and merge in order:

Refs DOCS-1171

Generated by Coder Agents.

@linear-code

linear-code Bot commented Nov 6, 2026

Copy link
Copy Markdown

DOCS-1171

Comment thread docs/agent-relay/setup.md Outdated
Comment on lines +21 to +22
- Agent Relay v0.14.0 or later.
Claude Code `dispatch_deadline`, the reap delay, and the reaper startup grace require v0.15.0 or later.

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.

Let's advise people on using our latest published version. I do not like us linking options with versions

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.

Are we comfortable with enforcing a v0.14.0 floor? Or, should we maintain a hard floor at all? I'm pro-"latest" here, as well.

Comment thread docs/agent-relay/setup.md Outdated
Comment on lines +355 to +356
Each Agent Relay release on GitHub also includes static binaries for Linux and macOS on `amd64` and `arm64`, with a `checksums.txt` file.
This guide covers only the image and the Helm chart.

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.

The binaries aren't accessible because the repo is private. Only the Helm chart and the image are public.

Comment thread docs/agent-relay/slack.md

- Workspace names start with `cc-`, followed by the session's UUID.
- The module releases a session after 60 minutes without a user message, and Agent Relay deletes the workspace.
- The pool's `idle_release_timeout`, 1 hour by default, releases a session that goes that long without a user message, and Agent Relay deletes the workspace.

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.

Is this flag common to both Claude and Cursor?

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.

Yes, but in different denominations. Claude wants minutes, Cursor denominates in seconds.

@coder
coder Bot force-pushed the docs/agent-relay-smaller-fixes branch from d845fe4 to a815ecd Compare November 6, 2026 18:28
@nickvigilante
nickvigilante force-pushed the docs/agent-relay-smaller-fixes branch from a815ecd to ddfa319 Compare November 6, 2026 20:02
Comment thread docs/agent-relay/setup.md
</div>

Agent Relay release binaries for running as a `systemd` service aren't published yet.
Install Agent Relay with the container image or the Helm chart.

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.

Is this redundant given the install methods listed above?

Comment thread docs/agent-relay/slack.md
- Tagging `@claude !restart` replaces the thread's or channel's session with a new one in a new workspace.
- Deleting a thread's first message closes the session, and Agent Relay deletes its workspace.

To change how long a session can sit idle before release, set `idle_release_timeout` on the pool, as described in [Fields for every pool](./configuration.md#fields-for-every-pool).

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.

I've left this one off the list in past reviews, but do we want to talk about the behavior of setting this to 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.

I think anything I left here are mostly nits or lesser -- despite comments, I think this looks good to me after @matifali worked through the larger feedback.


Leave `template_version` unset so that builds use the template's active version, and roll out changes by promoting a version in Coder.
That includes rebuilds: when Agent Relay rebuilds an existing workspace for a session that the provider sends again, it moves the workspace to the active version.
A stopped workspace then picks up the new version, and still starts on a template that requires the active version.

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.

Blocking: The comma before "and" joins two verbs that share the subject "A stopped workspace", and it does not separate two independent clauses. The sentence reads better without it: "A stopped workspace then picks up the new version and still starts on a template that requires the active version." (Copy Editor)

Rule: No comma in a short compound predicate

Suggested change
A stopped workspace then picks up the new version, and still starts on a template that requires the active version.
A stopped workspace then picks up the new version and still starts on a template that requires the active version.

Leave `template_version` unset so that builds use the template's active version, and roll out changes by promoting a version in Coder.
That includes rebuilds: when Agent Relay rebuilds an existing workspace for a session that the provider sends again, it moves the workspace to the active version.
A stopped workspace then picks up the new version, and still starts on a template that requires the active version.
If Coder refuses a rebuild with `400` or `403`, such as for a version that the service account can't use, Agent Relay reports the failure as non-retryable instead of retrying in a loop.

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.

Blocking: This sentence hands the reader status codes (400, 403) and retry-loop mechanics that the reader never types or receives. The claim worth keeping is the outcome. Reframe it to state what happens without the internals, for example: "A version the service account can't use fails without a retry." (Reader Advocate)

Rule: Evidence justifies a claim and does not belong in the claim

Comment thread docs/agent-relay/slack.md
- Deleting a thread's first message closes the session, and Agent Relay deletes its workspace.

To change how long a session can sit idle before release, set `idle_release_timeout` on the pool, as described in [Fields for every pool](./configuration.md#fields-for-every-pool).
Agent Relay sets the value on every build, so the pool setting overrides the module's `release_idle_session_min` input, which is only a fallback.

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.

Blocking: This paragraph names release_idle_session_min as the module's input and calls it a fallback, but the module input table on this same page no longer lists it; the row was removed from slack.md. The term is still documented as a module input in claude-code.md:129 and configuration.md:176. Either restore a note for release_idle_session_min in the module input table, or drop the module-input reference here and state that the pool's idle_release_timeout is the control, matching claude-code.md:131. (Continuity Editor)

Rule: One term per concept

Comment thread docs/agent-relay/setup.md
After the grace passes, Agent Relay fails and deletes a workspace where the worker hasn't started.

To check whether workers start before setup finishes, compare the [`agent_relay_reaper_claim_to_agent_ready_seconds` and `agent_relay_reaper_claim_to_runner_up_seconds`](./monitoring/index.md#shared-metrics) metrics.
A worker that's up before the agent is ready started while startup scripts were still running.

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.

Blocking: This sentence uses "worker", while the same new signal in monitoring/index.md:118 is described with "runner". index.md defines "worker" as the generic term and notes that Claude Code calls it a "runner". Use one term for the same concept here. Because this is the shared-metric description, align monitoring/index.md:118 to "worker". (Continuity Editor)

Rule: One term per concept


> [!NOTE]
> Module version 1.0.0 and later need Coder 2.39 or later and Agent Relay v0.14.0 or later, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.

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.

The comma before "and receive" joins two verbs that share the subject "Module version 1.0.0 and later", so it is not separating independent clauses. Remove it: "Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release and receive the credential as a workspace build secret." (Copy Editor)

Rule: No comma in a short compound predicate

Suggested change
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release and receive the credential as a workspace build secret.


> [!NOTE]
> Module version 1.0.0 and later need Coder 2.39 or later and Agent Relay v0.14.0 or later, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.

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.

The comma before "and receive" joins two verbs that share the subject "Module version 1.0.0 and later", so it is not separating independent clauses. Remove it: "Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release and receive the credential as a workspace build secret." (Copy Editor)

Rule: No comma in a short compound predicate

Suggested change
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret.
> Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release and receive the credential as a workspace build secret.

@coderagents

coderagents Bot commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/agent-relay/configuration.md (open) - Remove the comma before "and" in "picks up the new version, and still starts".
  • docs/agent-relay/configuration.md (open) - Reframe the 400/403 retry mechanism as the reader-facing outcome.
  • docs/agent-relay/slack.md (open) - release_idle_session_min is named but no longer in the module input table on this page.
  • docs/agent-relay/setup.md (open) - Use one term ("worker" vs "runner") for the same new signal across pages.
Findings for agents
- id: language-1
  persona: language
  class: rule
  blocking: true
  file: docs/agent-relay/configuration.md
  line: 158
  quote: "A stopped workspace then picks up the new version, and still starts on a template that requires the active version."
  evidence:
    - docs/agent-relay/configuration.md:158
  rule: style-guide/capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
  problem: A comma before "and" joins two verbs that share the subject "A stopped workspace" instead of separating two clauses.
  fix: Remove the comma: "A stopped workspace then picks up the new version and still starts on a template that requires the active version."
  verified: true
- id: audience-1
  persona: audience
  class: rule
  blocking: true
  file: docs/agent-relay/configuration.md
  line: 159
  quote: "If Coder refuses a rebuild with `400` or `403`, such as for a version that the service account can't use, Agent Relay reports the failure as non-retryable instead of retrying in a loop."
  evidence:
    - docs/agent-relay/configuration.md:159
  rule: content-guidelines.md#evidence-justifies-a-claim-and-does-not-belong-in-the-claim
  problem: Status codes and retry-loop mechanics are internals the reader never types or receives.
  fix: Reframe to "A version the service account can't use fails without a retry."
  verified: true
- id: consistency-1
  persona: consistency
  class: rule
  blocking: true
  file: docs/agent-relay/slack.md
  line: 152
  quote: "Agent Relay sets the value on every build, so the pool setting overrides the module's `release_idle_session_min` input, which is only a fallback."
  evidence:
    - docs/agent-relay/slack.md:152
    - docs/agent-relay/claude-code.md:129
    - docs/agent-relay/configuration.md:176
  rule: style-guide/word-choice.md#one-term-per-concept
  problem: This page removed the `release_idle_session_min` row from its module input table yet still names it here.
  fix: Restore a note for `release_idle_session_min`, or drop the module-input reference and state the pool's `idle_release_timeout` is the control.
  verified: true
- id: consistency-2
  persona: consistency
  class: rule
  blocking: true
  file: docs/agent-relay/setup.md
  line: 256
  quote: "A worker that's up before the agent is ready started while startup scripts were still running."
  evidence:
    - docs/agent-relay/setup.md:256
    - docs/agent-relay/monitoring/index.md:118
    - docs/agent-relay/index.md:28
  rule: style-guide/word-choice.md#one-term-per-concept
  problem: The same signal is described with "worker" here and "runner" in monitoring/index.md while index.md defines "worker" as the generic term.
  fix: Align monitoring/index.md:118 to "worker".
  verified: true
- id: language-2
  persona: language
  class: suggestion
  blocking: false
  file: docs/agent-relay/claude-code.md
  line: 122
  quote: "Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret."
  evidence:
    - docs/agent-relay/claude-code.md:122
  rule: style-guide/capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
  problem: A comma before "and receive" joins two verbs that share the subject "Module version 1.0.0 and later".
  fix: Remove the comma.
  verified: true
- id: language-3
  persona: language
  class: suggestion
  blocking: false
  file: docs/agent-relay/cursor.md
  line: 111
  quote: "Module version 1.0.0 and later need Coder 2.39 or later and the latest Agent Relay release, and receive the credential as a workspace build secret."
  evidence:
    - docs/agent-relay/cursor.md:111
  rule: style-guide/capitalization-and-punctuation.md#no-comma-in-a-short-compound-predicate
  problem: A comma before "and receive" joins two verbs that share the subject "Module version 1.0.0 and later".
  fix: Remove the comma.
  verified: true

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

@matifali

matifali commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Let's resolve all open comments before merging please.

nickvigilante added a commit that referenced this pull request Nov 9, 2026
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>
coder Bot and others added 2 commits November 9, 2026 14:09
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

Copy link
Copy Markdown
Collaborator

Closing and reopening under a human author, as required for this repository.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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