Repository navigation
docs: say what Agent Relay does with agent readiness - #31896
Conversation
Agent Relay now reads the workspace agent's lifecycle on every sweep and fails a session about a minute after the agent reports that its startup scripts failed. Update the setup section to say so, link the example templates that carry the ordering rule, tell operators what a failed setup looks like in the logs, and name the handoff log line the relay emits since it was renamed.
|
/coder-agents-review Please limit the review to P0, P1, and P2 issues only. |
|
/coder-agents-review Please limit the review to P0, P1, and P2 issues only. |
There was a problem hiding this comment.
This PR updates three Agent Relay docs pages for the relay's agent lifecycle reads and early startup failure. As requested, this review covers P0 to P2 only: 3 P2 findings. The two claims about what a failed setup does were checked against origin/bobby/relay-67-b-startup-failure (coder/agent-relay#155); whether that branch has merged was not checked.
Out of scope (needs a ticket or explicit acceptance by a human):
- coder/agent-relay
internal/services/servicecursorworkers/reap.go: a confirmed startup failure has statuspending, so the claim fails as retryable and the Cursor user reads "Try again in a few minutes." Retrying rebuilds the same template and the same setup fails again. docs/agent-relay/configuration.md:278: the Workspace reaper section does not document--reap-delay, which postpones provider failure reporting, so readers cannot tell why a startup failure arrives later than about a minute.
🤖 This review was automatically generated with Coder Agents.
The private agent-relay repository is not reachable by docs readers, so the example pointer now goes to the module READMEs on the Coder Registry. A failed setup fails a Cursor request about a minute later, but a Claude Code work order is retried once on a new workspace first, and only Claude Code receives the reaper's reason in its error. The reaper's log line is named so an operator can search for it.
|
/coder-agents-review Please limit the review to P0, P1, and P2 issues only. |
There was a problem hiding this comment.
This PR updates three Agent Relay docs pages for the relay's agent lifecycle reads and early startup failure. Within the requested P0 to P2 scope, this round has no new findings. The three P2 findings from the last round (the private-repository link, the Claude Code retry on a first delivery, and where the startup failure reason appears) are fixed in 7169ef2; the new text matches origin/bobby/relay-67-b-startup-failure.
Out of scope (needs a ticket or explicit acceptance by a human):
docs/agent-relay/setup.md:257: for Claude Code, build plus setup must fit within the pool'sdispatch_deadline(default 5 minutes, counted from work-order issue), but this unchanged line tells authors to keep setup well under 15 minutes, so a 4-minute setup can have its session offered again mid-setup.docs/agent-relay/monitoring/siem.md:226,:227,:233: the rows nameworkspace build failed, reporting retryable and deleting,workspace build passed the session deadline, reporting retryable and deleting, anddelete workspace failed, leaving for reconciliation, but the relay logsworkspace build failed,workspace build passed the session deadline, reporting failure, anddelete workspace failed, leaving it for the reaper(workspacedispatcher/dispatcher.go:991,:1078,:1159on the #155 branch), so SIEM rules copied from those rows match nothing.- coder/agent-relay
internal/workspacereaper/reaper.go:798: after a retryable Claude Code nack the reaper deletes the workspace, while the redelivered work order can try to start a build on that same workspace, so the redelivery may fail with "workspace was deleted before its build could start" instead of getting the one retry the docs describe. Inferred from code, not reproduced.
🤖 This review was automatically generated with Coder Agents.
The ordering section told every reader to keep setup under 15 minutes. That is the Cursor startup grace. A Claude Code pool is bounded by the work order's dispatch_deadline, 5 minutes by default, so the example timeout of 300 seconds already overran it before the build was counted.
Documentation CheckBlocking
Design notes
Findings for agents- id: accuracy-1
persona: accuracy
class: wrong
blocking: true
file: docs/agent-relay/setup.md
line: 258
quote: " - For a Cursor pool, keep them well under Agent Relay's startup grace of 15 minutes, after which it deletes a workspace whose worker hasn't started."
evidence:
- docs/agent-relay/cursor.md:197
- docs/agent-relay/cursor.md:200
rule: null
problem: The Cursor budget bullet names "Agent Relay's startup grace of 15 minutes" as the budget, but the Cursor pool's actual budget is its dispatch_deadline, default 10m and at most 15m. "startup grace" was a new undefined term.
fix: Name the pool's dispatch_deadline (10m default, at most 15) like the sibling Claude Code bullet.
verified: true
- id: consistency-2
persona: consistency
class: rule
blocking: true
file: docs/agent-relay/setup.md
line: 260
quote: " Past it, Anthropic redelivers the work order and Agent Relay rebuilds the workspace, so setup that can't fit reruns on every delivery and the session is never served."
evidence:
- docs/agent-relay/setup.md:254
- docs/agent-relay/troubleshooting.md:106
rule: docs/.style/style-guide/word-choice.md#one-term-per-concept
problem: The Claude Code retry count conflicts: "reruns on every delivery" vs "handed back once" (setup.md:254) and "retries once" (troubleshooting.md:106).
fix: State the trigger and count together, reusing the same wording as the other two places.
verified: true
- id: audience-1
persona: audience
class: rule
blocking: true
file: docs/agent-relay/setup.md
line: 218
quote: "It reads the workspace agent's lifecycle on every sweep and reports it on the status page, but it doesn't wait for it: the provider module starts the worker as soon as its start script runs."
evidence:
- docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
rule: docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
problem: The sentence describes Agent Relay's sweep/status-page mechanism, which the setup reader neither types nor receives; the reader-facing effect follows in the next sentence.
fix: "The provider module starts the worker as soon as its start script runs, without waiting for the workspace to be set up."
verified: true
- id: audience-2
persona: audience
class: rule
blocking: true
file: docs/agent-relay/setup.md
line: 252
quote: "Agent Relay reads the agent's `start_error` or `start_timeout` lifecycle and acts about a minute later."
evidence:
- docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
rule: docs/.style/content-guidelines.md#describe-the-current-version-for-the-end-user
problem: The sentence describes internal lifecycle reading and sweep timing; the reader-facing effects are stated in the sentences that follow.
fix: Remove the sentence so the bullet goes straight to the effect.
verified: true
- id: language-1
persona: language
class: rule
blocking: true
file: docs/agent-relay/setup.md
line: 258
quote: "after which it deletes a workspace whose worker hasn't started."
evidence:
- docs/.style/style-guide/word-choice.md#whose-for-people-not-things
rule: docs/.style/style-guide/word-choice.md#whose-for-people-not-things
problem: "Whose" is used with the inanimate object "workspace"; the rule requires "where the worker hasn't started".
fix: "after which it deletes a workspace where the worker hasn't started."
verified: true
- id: learner-1
persona: learner
class: suggestion
blocking: false
file: docs/agent-relay/setup.md
line: 257
quote: " The build and setup together must fit the provider's budget:"
evidence:
- docs/agent-relay/setup.md:229
- docs/agent-relay/setup.md:256-260
rule: null
problem: The reader can't translate the 5m/15m budgets into a coder_script timeout value.
fix: State the units and that the coder_script timeout is in seconds and bounds one script.
verified: true
- id: language-4
persona: language
class: suggestion
blocking: false
file: docs/agent-relay/setup.md
line: 258
quote: "keep them well under Agent Relay's startup grace of 15 minutes"
evidence:
- docs/.style/style-guide/word-choice.md#avoid-weasel-words
rule: docs/.style/style-guide/word-choice.md#avoid-weasel-words
problem: "well under" is a hedged degree qualifier.
fix: "keep them under the pool's `dispatch_deadline`, 10 minutes by default and at most 15"
verified: true
- id: audience-3
persona: audience
class: suggestion
blocking: false
file: docs/agent-relay/setup.md
line: 229
quote: " timeout = 120"
evidence:
- docs/templates/extending-templates/script-ordering.md
rule: null
problem: The coder_script timeout is in seconds, but the example gives a bare 120 directly above budget guidance in minutes.
fix: " timeout = 120 # 2 minutes"
verified: true
- id: language-5
persona: language
class: suggestion
blocking: false
file: docs/agent-relay/configuration.md
line: 309
quote: "A short grace can cut off slow agent connections and slow worker startups."
evidence:
- docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning
rule: docs/.style/style-guide/word-choice.md#choose-words-that-have-one-meaning
problem: "can" is used for a possible adverse outcome; the rule maps "might" to possibility.
fix: "A short grace might cut off slow agent connections and slow worker startups."
verified: trueAutomated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong. |
Say that the coder_script timeout is in seconds and bounds one script, name the Cursor budget as the reaper's startup grace and the Claude Code budget as the pool's build budget with links to both, state the single redelivery, and document --reap-startup-grace on the configuration page.
|
Thanks for the review. All six inline threads are addressed in 981c5a3; the version one stays open until the next relay tag. The four 15-minute lines outside the diff (cursor.md, setup.md, configuration.md) are fixed in this PR too, and the description is rewritten to match the branch. |
|
Active-voice pass on the latest diff: the earlier passive sentence about handing the Claude Code work order back is already active. Two passive turns remain in Coder Agents on behalf of @Emyrk. |
Emyrk
left a comment
There was a problem hiding this comment.
Just comments on language. Overall LG and need to get the new flag in
|
A few accuracy notes on the current wording:
Coder Agents on behalf of @Emyrk. |
The budget starts when Anthropic issues the work order, and a setup that overruns it means no worker ever serves the session.
|
Fixed in 25dfbca. Both sentences are active now, and the first matches the Build budget wording on the Claude Code page. SIEM string untouched. |
…b.com/coder/coder into bobby/relay-67-e-agent-readiness-docs
… claimed prebuilds Agent Relay newer than v0.15.0 fails a session about a minute after a setup script fails; v0.15.0 and older wait out the startup grace. A claimed prebuild keeps reporting the prebuild's idle after a failed setup, so the quick failure never fires there. A Claude Code setup is only never served when it keeps overrunning the budget.
…b.com/coder/coder into bobby/relay-67-e-agent-readiness-docs
|
Fixed in e763311. Both pages now give the timing per relay version, matching the cursor module README. The claimed-prebuild case is stated on the setup, troubleshooting and Cursor pages, and the Claude Code sentence is scoped to setup that keeps overrunning the budget. |
nickvigilante
left a comment
There was a problem hiding this comment.
Approved with changes. Thanks for this!
One issue is inline, in two places: the Claude Code one-retry cap came with dd726ff (#155) and isn't in v0.15.0, so the v0.15.0 sentences need to say that those versions keep handing Claude Code work orders back as retryable.
Checked and correct: the version scoping (main publishes :unstable, so newer than v0.15.0 is installable), the claimed-prebuild behavior (the module's status script keeps the prebuild's idle until the worker starts, and the reaper keeps idle workspaces), the startup-grace links and defaults in cursor.md, configuration.md, and setup.md, the timed-out setup strings, and the v0.15.0 source note.
The one-retry cap on Claude Code work orders arrived with the quick failure in agent-relay#155, so v0.15.0 and older hand a pending runner back as retryable on every redelivery and rerun the setup each time.
TL;DR
Agent Relay now reads the workspace agent's lifecycle, shows it on its status page, renamed the log line it writes at handoff, and, with coder/agent-relay#155, fails a session about a minute after the agent's startup scripts fail or time out instead of waiting out the 15-minute startup grace (coder/agent-relay#154 and coder/agent-relay#155). The docs still described the relay as ignoring agent readiness, gave template authors no way to size their setup scripts against each pool's budget, did not document the
--reap-startup-graceoption that sets that budget, and listed a log line the relay no longer writes. This PR updates the setup, troubleshooting, configuration, Cursor and SIEM pages.Refs https://linear.app/codercom/issue/RELAY-67/start-the-cursor-worker-only-after-the-workspace-agent-is-ready
Refs https://linear.app/codercom/issue/DOCS-1473
How to navigate this PR
docs/agent-relay/setup.mdclosely and skim the rest.docs/agent-relay/setup.md, section "Start the worker after workspace setup": the opening sentences, the example'stimeout, the sentence after the code block, the failed-prerequisite bullet, and the new budget bullet with one sub-bullet per provider.docs/agent-relay/configuration.md: the new--reap-startup-graceentry, thedispatch_deadlinerow, and the source note at the top.docs/agent-relay/troubleshooting.md, "The agent runs commands before the workspace finishes setting up": five added sentences.docs/agent-relay/cursor.md: two lines that now say the 15-minute limit is a default.docs/agent-relay/monitoring/siem.md: one string in the Dashboard row.Implementation
docs/agent-relay/setup.mdtimeoutis now120with a# 2 minutescomment, so it fits the smallest default budget below. It was300.coder/agent-relay-claude-codeandcoder/agent-relay-cursormodule READMEs on the registry, which show the rule with a full example as of module version 1.0.1 (docs(agent-relay-cursor, agent-relay-claude-code): order the module after setup registry#1239). The templates those examples came from live in the Agent Relay repository underexample/templates(coder/agent-relay#157), which the docs can't link because the repository is private.timeoutis in seconds and bounds one script, and that the build plus the sum of the setup timeouts must fit the pool's budget. For Cursor that budget is the reaper's startup grace. For Claude Code it is the pool's build budget, and a setup that keeps overrunning it is never served because Anthropic keeps offering the session and each new build reruns setup. There is no retry count on that path, since the one-retry cap only applies after a startup failure.docs/agent-relay/configuration.md--reap-startup-graceentry: type, environment variable, YAML and Helm keys, the15m0sdefault, what passing it does to a building workspace and to a built one with no worker, the interaction withdispatch_deadline, and the "must be positive" validation.dispatch_deadlinerow for Cursor pools links the 15-minute backstop to that entry and calls it a default.docs/agent-relay/troubleshooting.md: the existing entry gains what the operator sees with the rule in place. The session fails about a minute afterstart_error, orstart_timeoutwhen a script reaches itstimeout. The reaper's log line carriesagent_lifecycleandreasonfor both cases, with both reason strings quoted. Only Claude Code sessions receive the reason in their error. Cursor users see a fixed message.docs/agent-relay/cursor.md: the "Build deadline" backstop line and thependingrow of the lifecycle table now say 15 minutes is the startup grace's default and link to the option. The Prebuilds section says setup reruns on a claim and what a failed setup looks like there.docs/agent-relay/monitoring/siem.md: the Dashboard row'sworkspace ready, runner handoffbecomesworkspace built, runner handoff, the line the relay writes since v0.15.0. A SIEM rule built from the old string no longer matches.claim_to_agent_ready_secondssits beside, so adding one without the other would be odd.--reap-startup-graceoption and the renamed log line, is in v0.15.0.idle, so Agent Relay neither fails the session nor deletes the workspace. The quick failure only fires onpending, and the module README already documents the gap.Expected Output
timeouton each setup script, in seconds, and to size the build plus all the timeouts against their pool's budget: the startup grace for Cursor, the build budget for Claude Code.idleand is neither failed nor deleted.--reap-startup-grace, its default, and what it bounds, and sees that the 15-minute limits elsewhere in the docs are that default.Testing
make lint/markdownpasses with 0 errors over the docs tree.make lint/emdashpasses.make fmt/markdownrealigned the two tables this PR widened and changed nothing else.--reap-startup-graceentry was checked against the relay's reaper service flag definition at v0.15.0, and both troubleshooting reason strings against the reaper's startup-failure check on the relay's main branch.