docs(agent-relay-cursor, agent-relay-claude-code): order the module after setup

registry/coder/modules/agent-relay-claude-code/README.md

@@ -16,7 +16,7 @@ on each build and runs the Claude Code self-hosted runner.
 ```tf
 module "claude_code_runner" {
   source   = "registry.coder.com/coder/agent-relay-claude-code/coder"
-  version  = "1.0.0"
+  version  = "1.0.1"
   agent_id = coder_agent.main.id
 
   # Downloads the Claude Code CLI at start when it is not in the image. Bake
@@ -68,6 +68,58 @@ optional; see [Session attachment](#session-attachment).
 - Builds must finish inside Agent Relay's 300s spawn budget: pre-pulled
   images, no persistent volumes.
 
+## Start the runner after your setup
+
+The start step runs as one of the agent's start scripts. Without an
+ordering rule, every start script runs at once, so the runner can take
+a session while your template is still cloning a repository or installing
+tools. The module cannot wait for the agent to be `ready`: its own start
+script is one of the scripts the agent waits on.
+
+Order the module after your setup in the template, with a
+`coder_script_order` rule. The module cannot declare this rule for you,
+because a rule can only select scripts in its own module, so it lives
+beside the module call:
+
+```tf
+resource "coder_script" "setup" {
+  agent_id     = coder_agent.main.id
+  display_name = "Workspace setup"
+  run_on_start = true
+  timeout      = 300
+  script       = file("${path.module}/setup.sh")
+}
+
+data "coder_script_order" "relay_runner" {
+  rule {
+    phase = "start"
+    run   = ["module.claude_code_runner"]
+    after = ["coder_script.setup"]
+  }
+}
+```
+
+- Script ordering needs Coder 2.39.0 or newer on the control plane, the
+  provisioners and the workspace agents, and the Coder provider 2.20.0 or
+  newer. Older Coder ignores the rule without an error and the runner
+  starts right away.
+- `coder_agent.startup_script` cannot be ordered. Put setup the runner
+  depends on in `coder_script` resources or modules, including a step that
+  installs the CLI (set `install_cli = false` and order the module after it).
+- With the default `requires = "success"`, a failed setup script skips
+  this module and the runner never starts. Agent Relay fails the session
+  about a minute after the agent reports the failure. Set
+  `requires = "completion"` to start the runner anyway.
+- While the rule holds the start step, `agent_relay_status` reads `pending`.
+  Agent Relay deletes a workspace that stays `pending` for 15 minutes, so
+  keep setup under that. Prebuilt workspaces run setup at prebuild time and
+  are claimed in seconds.
+- A `cli_binary` wrapper that waits for setup is not needed; the rule does
+  the waiting.
+
+The full example is in the Agent Relay repository under
+[`example/templates/claude-code`](https://github.com/coder/agent-relay/tree/main/example/templates/claude-code).
+
 ## Additional runner arguments
 
 Use `additional_args` to pass extra arguments to `claude self-hosted-runner`, as a
@@ -79,7 +131,7 @@ can contain spaces or quotes without escaping. Flags the module already sets
 ```tf
 module "claude_code_runner" {
   source          = "registry.coder.com/coder/agent-relay-claude-code/coder"
-  version         = "1.0.0"
+  version         = "1.0.1"
   agent_id        = coder_agent.main.id
   additional_args = ["--some-flag", "value", "--some-flag", "another value", "--another-flag"]
 }
@@ -182,7 +234,7 @@ fails the start step with `failed invalid-release-idle-session-min`.
 ```tf
 module "claude_code_runner" {
   source                   = "registry.coder.com/coder/agent-relay-claude-code/coder"
-  version                  = "1.0.0"
+  version                  = "1.0.1"
   agent_id                 = coder_agent.main.id
   release_idle_session_min = 30
 }
@@ -221,7 +273,7 @@ from reaching it.
 ```tf
 module "claude_code_runner" {
   source      = "registry.coder.com/coder/agent-relay-claude-code/coder"
-  version     = "1.0.0"
+  version     = "1.0.1"
   agent_id    = coder_agent.main.id
   health_port = 3290
 }

registry/coder/modules/agent-relay-cursor/README.md

@@ -16,7 +16,7 @@ parameters the relay stamps on each build and runs the Cursor CLI worker.
 ```tf
 module "cursor_worker" {
   source   = "registry.coder.com/coder/agent-relay-cursor/coder"
-  version  = "1.0.0"
+  version  = "1.0.1"
   agent_id = coder_agent.main.id
 
   # Downloads the Cursor CLI at start when it is not in the image. Bake
@@ -76,7 +76,9 @@ created.
   `true`) downloads it at start only when it is not already on PATH; bake it
   into the image for the fastest start. `cli_binary` overrides the path.
 - Repo-scoped pools: the template must clone `agent_relay_cursor_repo_url` and
-  provide SCM credentials before this module's script runs.
+  provide SCM credentials before this module's script runs. Order this
+  module's scripts after the clone; see
+  [Start the worker after your setup](#start-the-worker-after-your-setup).
 - `computer_use = true` needs the computer-use packages in the image.
   `share_desktop = true` (requires `computer_use`) lets people watch or take
   control of the agent's desktop from the Desktop tab in Cursor. It needs
@@ -87,6 +89,59 @@ created.
 - Builds must finish inside the pool's `dispatch_deadline` (default 10m, max
   15m): pre-pulled images, no persistent volumes.
 
+## Start the worker after your setup
+
+The start step runs as one of the agent's start scripts. Without an
+ordering rule, every start script runs at once, so the worker can take
+a session while your template is still cloning a repository or installing
+tools. The module cannot wait for the agent to be `ready`: its own start
+script is one of the scripts the agent waits on.
+
+Order the module after your setup in the template, with a
+`coder_script_order` rule. The module cannot declare this rule for you,
+because a rule can only select scripts in its own module, so it lives
+beside the module call:
+
+```tf
+resource "coder_script" "setup" {
+  agent_id     = coder_agent.main.id
+  display_name = "Workspace setup"
+  run_on_start = true
+  timeout      = 300
+  script       = file("${path.module}/setup.sh")
+}
+
+data "coder_script_order" "relay_worker" {
+  rule {
+    phase = "start"
+    run   = ["module.cursor_worker"]
+    after = ["coder_script.setup"]
+  }
+}
+```
+
+- Script ordering needs Coder 2.39.0 or newer on the control plane, the
+  provisioners and the workspace agents, and the Coder provider 2.20.0 or
+  newer. Older Coder ignores the rule without an error and the worker
+  starts right away.
+- `coder_agent.startup_script` cannot be ordered. Put setup the worker
+  depends on in `coder_script` resources or modules, including a step that
+  installs the CLI (set `install_cli = false` and order the module after it).
+- With the default `requires = "success"`, a failed setup script skips
+  this module and the worker never starts. Agent Relay fails the session
+  about a minute after the agent reports the failure. Set
+  `requires = "completion"` to start the worker anyway.
+- While the rule holds the start step, `agent_relay_status` reads `pending`.
+  Agent Relay deletes a workspace that stays `pending` for 15 minutes, so
+  keep setup under that. Prebuilt workspaces run setup at prebuild time and
+  are claimed in seconds.
+- A `cli_binary` wrapper that waits for setup is not needed and is a trap:
+  the status script recognises the worker by the binary's basename, so a
+  wrapper not named `agent` reads as `orphaned`.
+
+The full example is in the Agent Relay repository under
+[`example/templates/cursor`](https://github.com/coder/agent-relay/tree/main/example/templates/cursor).
+
 ## Worker credential
 
 The pool's service-account API key never leaves Agent Relay. When the relay
@@ -118,7 +173,7 @@ optional value an explicit one (`--flag=value`), or it consumes `start`.
 ```tf
 module "cursor_worker" {
   source          = "registry.coder.com/coder/agent-relay-cursor/coder"
-  version         = "1.0.0"
+  version         = "1.0.1"
   agent_id        = coder_agent.main.id
   additional_args = ["--some-flag", "value", "--some-flag", "another value", "--another-flag"]
 }
@@ -243,7 +298,7 @@ scrape the worker, and never publish it through a `coder_app`.
 ```tf
 module "cursor_worker" {
   source          = "registry.coder.com/coder/agent-relay-cursor/coder"
-  version         = "1.0.0"
+  version         = "1.0.1"
   agent_id        = coder_agent.main.id
   management_addr = "127.0.0.1:3290"
 }