fix(skills): retarget openclaw-orchestrator and /spawn at the current CLI - #90
Open
willwashburn wants to merge 2 commits into
Open
fix(skills): retarget openclaw-orchestrator and /spawn at the current CLI#90willwashburn wants to merge 2 commits into
willwashburn wants to merge 2 commits into
Conversation
…tokens The three pattern skills each mandated printing the raw workspace key in an observer URL — "Do not print a placeholder — print the real URL the user can click. This is mandatory." A workspace key is an administrative credential; a URL query string is the worst place to put one. They also required the key be copied into every worker prompt. That is unnecessary: `create_workspace` and `set_workspace_key` both pin the workspace to the project, and the relay MCP server a `relay-worker` subagent starts resolves that pin on its own. The mandate put an admin credential into N prompts and N transcripts to achieve nothing. - Step 3 now calls `get_observer_url`, which mints a scoped, expiring, read-only token. Requires the tool added in AgentWorkforce/relay#1422. - Worker prompts no longer carry the workspace key; the worker agent definition and SubagentStart hook now say the workspace is inherited and that a key must never be printed or requested. - The three skills' shared setup steps are now byte-identical, and all three carry the worker/stage tracking table and the "do not self-release" instruction that only relay-team had. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
… CLI `openclaw-orchestrator` documented Agent Relay's removed flat command surface almost end to end: `agent-relay up`, `spawn`, `agents`, `agents:logs`, `agents:kill`, `send`, `inbox`, `down`, plus `mcporter call relaycast ...` for channels and messaging. None of those are registered at the top level any more — `createProgram()` puts lifecycle under `agent-relay node ...` and messaging under `agent-relay message ...`, with the old flat group surviving only as a hidden, deprecated `local` alias. It also documented a `--team` flag that `node agent spawn` does not have; grouping is by `--channels`. Rather than re-document what `orchestrating-agent-relay` already covers correctly, this reduces the skill to what is actually OpenClaw-specific (the `@agent-relay/openclaw` setup, `openclaw system event` completion reporting, provider quirks) and defers everything else to that skill. It also names the removed commands explicitly so an agent carrying them in context discards them. Other fixes: - Frontmatter `name:` was `agent-relay-orchestrator` while the published package and directory are `openclaw-orchestrator`, so the installed skill registered under a name nothing referenced. Also drops the non-contract `version:`/`homepage:`/`metadata:` keys. - `/spawn` used the same removed commands, told the user to supply a workspace key that `node up` auto-creates, and pointed monitoring at `agents:logs`. Retargeted, and it now offers an observer link. - `/create-workflow` referenced `agent-relay agents`. Every command in the rewritten files was checked against `--help` on a build of the current CLI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1
|
Warning Review limit reached
Next review available in: 56 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (10)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: aec62d675f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Use relay MCP tools (`send_dm`, `post_message`, `check_inbox`) to communicate with workers after they're running. | ||
| - Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay. | ||
| - Run workers in **background mode** (`run_in_background: true`) so they work concurrently. | ||
| - Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key. |
There was a problem hiding this comment.
These authentication and observer-token changes alter the published claude-relay-plugin, but its version remains 0.1.0 in .claude-plugin/marketplace.json, the plugin manifest, and package.json. Marketplace clients use that version to detect updates, so existing installations can remain on the prior prompts that expose workspace keys instead of receiving this security fix; bump the three plugin version declarations together.
Useful? React with 👍 / 👎.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
4 issues found across 10 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh">
<violation number="1" location="plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh:11">
P2: Workers spawned without a successfully pinned project workspace now fail at `register_agent` and then cannot execute `check_inbox`, ACK, or DONE because every relay operation still requires that workspace. The bootstrap should either guarantee workspace pinning before any worker can start or stop with a clear non-relay failure path when registration reports `Workspace key not configured`, rather than asserting the pin for all `SubagentStart` invocations.</violation>
</file>
<file name="plugins/claude-relay-plugin/agents/relay-worker/agent.md">
<violation number="1" location="plugins/claude-relay-plugin/agents/relay-worker/agent.md:10">
P3: After this change, step 2 is a static prohibition ("Never print or request a workspace key"), so the startup protocol's "If any of steps 1-2 fail, retry once" now only meaningfully applies to step 1 (register_agent). Consider rewording the retry clause to reference only the fallible step so the failure/retry semantics stay accurate.</violation>
</file>
<file name="plugins/claude-relay-plugin/skills/relay-team/SKILL.md">
<violation number="1" location="plugins/claude-relay-plugin/skills/relay-team/SKILL.md:27">
P2: These changes instruct the lead to call an MCP tool `get_observer_url` so the user can follow along, but that tool is not part of the relay MCP surface this plugin documents. The canonical tool reference in `skills/using-agent-relay/SKILL.md` (the section literally titled "Current MCP Tool Names") lists create_workspace, set_workspace_key, register_agent, send_dm, check_inbox, etc., and has no get_observer_url entry; the only occurrences of get_observer_url anywhere in the repo are the newly added lines in this batch. If the tool is not actually registered by the agent-relay MCP server, a lead following these instructions will attempt a non-existent tool and fail to produce the observer link (and may stall retrying). Please confirm the tool exists under the agent-relay MCP server, or point the instructions at the real observer mechanism (e.g. the orchestrator-side CLI/web observer path) instead of an assumed MCP tool name.</violation>
</file>
<file name="plugins/claude-relay-plugin/skills/relay-fanout/SKILL.md">
<violation number="1" location="plugins/claude-relay-plugin/skills/relay-fanout/SKILL.md:18">
P2: This changes the workspace-key handling behavior for the published claude-relay-plugin (workers no longer receive the key in their prompt, and printing/requesting it is now disallowed), but none of the plugin's version declarations (marketplace.json, plugin manifest, package.json) appear to be bumped alongside it. Since marketplace clients rely on that version to detect updates, existing installations could remain on the old prompts that still expose workspace keys instead of picking up this fix. Consider bumping the plugin version declarations together with this change.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| 4. Send an ACK to your lead via \`send_dm(as: "$AGENT_NAME")\` when you understand the task. | ||
| 5. When finished, send a DONE message with a concise completion summary via \`send_dm(as: "$AGENT_NAME")\` before stopping. | ||
| 1. Call \`register_agent(name: "$AGENT_NAME", type: "agent")\` to register with the relay. | ||
| The workspace is already pinned to this project, so the relay MCP server resolves it |
There was a problem hiding this comment.
P2: Workers spawned without a successfully pinned project workspace now fail at register_agent and then cannot execute check_inbox, ACK, or DONE because every relay operation still requires that workspace. The bootstrap should either guarantee workspace pinning before any worker can start or stop with a clear non-relay failure path when registration reports Workspace key not configured, rather than asserting the pin for all SubagentStart invocations.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh, line 11:
<comment>Workers spawned without a successfully pinned project workspace now fail at `register_agent` and then cannot execute `check_inbox`, ACK, or DONE because every relay operation still requires that workspace. The bootstrap should either guarantee workspace pinning before any worker can start or stop with a clear non-relay failure path when registration reports `Workspace key not configured`, rather than asserting the pin for all `SubagentStart` invocations.</comment>
<file context>
@@ -7,13 +7,15 @@ AGENT_NAME="${RELAY_AGENT_NAME:-the assigned subagent name}"
-4. Send an ACK to your lead via \`send_dm(as: "$AGENT_NAME")\` when you understand the task.
-5. When finished, send a DONE message with a concise completion summary via \`send_dm(as: "$AGENT_NAME")\` before stopping.
+1. Call \`register_agent(name: "$AGENT_NAME", type: "agent")\` to register with the relay.
+ The workspace is already pinned to this project, so the relay MCP server resolves it
+ for you — you do NOT need a workspace key, and must never print or ask for one.
+ If this fails with "Workspace key not configured", report that to your lead.
</file context>
| 6. Spawn each worker using the Agent tool. **You must include the workspace key in the prompt** so the worker can call `set_workspace_key`: | ||
| 1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead. | ||
| 2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up. | ||
| 3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key. |
There was a problem hiding this comment.
P2: These changes instruct the lead to call an MCP tool get_observer_url so the user can follow along, but that tool is not part of the relay MCP surface this plugin documents. The canonical tool reference in skills/using-agent-relay/SKILL.md (the section literally titled "Current MCP Tool Names") lists create_workspace, set_workspace_key, register_agent, send_dm, check_inbox, etc., and has no get_observer_url entry; the only occurrences of get_observer_url anywhere in the repo are the newly added lines in this batch. If the tool is not actually registered by the agent-relay MCP server, a lead following these instructions will attempt a non-existent tool and fail to produce the observer link (and may stall retrying). Please confirm the tool exists under the agent-relay MCP server, or point the instructions at the real observer mechanism (e.g. the orchestrator-side CLI/web observer path) instead of an assumed MCP tool name.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plugins/claude-relay-plugin/skills/relay-team/SKILL.md, line 27:
<comment>These changes instruct the lead to call an MCP tool `get_observer_url` so the user can follow along, but that tool is not part of the relay MCP surface this plugin documents. The canonical tool reference in `skills/using-agent-relay/SKILL.md` (the section literally titled "Current MCP Tool Names") lists create_workspace, set_workspace_key, register_agent, send_dm, check_inbox, etc., and has no get_observer_url entry; the only occurrences of get_observer_url anywhere in the repo are the newly added lines in this batch. If the tool is not actually registered by the agent-relay MCP server, a lead following these instructions will attempt a non-existent tool and fail to produce the observer link (and may stall retrying). Please confirm the tool exists under the agent-relay MCP server, or point the instructions at the real observer mechanism (e.g. the orchestrator-side CLI/web observer path) instead of an assumed MCP tool name.</comment>
<file context>
@@ -11,45 +11,46 @@ $ARGUMENTS
-6. Spawn each worker using the Agent tool. **You must include the workspace key in the prompt** so the worker can call `set_workspace_key`:
+1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead.
+2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up.
+3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
+4. Read the task, inspect the relevant code, and decide whether parallel work is justified. Prefer 1 worker for tightly coupled work, 2–5 for genuinely separable work.
+5. Break the task into non-overlapping scopes. Each worker needs a concrete deliverable, the relevant files, and an explicit success condition.
</file context>
Suggested change
| 3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key. | |
| 3. **Give the user a link to follow along.** Obtain the read-only observer URL from the supported observer mechanism (orchestrator CLI/web) and print it. Never build an observer URL from the workspace key, and never print the key. |
| - Use relay MCP tools (`send_dm`, `check_inbox`) to monitor worker progress. | ||
| - Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay. | ||
| - Run all workers in **background mode** (`run_in_background: true`) so they work concurrently. | ||
| - Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key. |
There was a problem hiding this comment.
P2: This changes the workspace-key handling behavior for the published claude-relay-plugin (workers no longer receive the key in their prompt, and printing/requesting it is now disallowed), but none of the plugin's version declarations (marketplace.json, plugin manifest, package.json) appear to be bumped alongside it. Since marketplace clients rely on that version to detect updates, existing installations could remain on the old prompts that still expose workspace keys instead of picking up this fix. Consider bumping the plugin version declarations together with this change.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plugins/claude-relay-plugin/skills/relay-fanout/SKILL.md, line 18:
<comment>This changes the workspace-key handling behavior for the published claude-relay-plugin (workers no longer receive the key in their prompt, and printing/requesting it is now disallowed), but none of the plugin's version declarations (marketplace.json, plugin manifest, package.json) appear to be bumped alongside it. Since marketplace clients rely on that version to detect updates, existing installations could remain on the old prompts that still expose workspace keys instead of picking up this fix. Consider bumping the plugin version declarations together with this change.</comment>
<file context>
@@ -11,49 +11,45 @@ $ARGUMENTS
-- Use relay MCP tools (`send_dm`, `check_inbox`) to monitor worker progress.
+- Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay.
+- Run all workers in **background mode** (`run_in_background: true`) so they work concurrently.
+- Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key.
+- The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker.
+- Use the relay MCP tools (`send_dm`, `check_inbox`) to monitor progress.
</file context>
| 1. **Authenticate.** Your task prompt includes a workspace key. Call the `set_workspace_key` MCP tool with that key. Do not print the key to the user. | ||
| 2. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. | ||
| 1. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. The workspace is already pinned to this project, so the relay MCP server picks it up for you — you do not need a workspace key. If `register_agent` fails with "Workspace key not configured", report that to your lead instead of asking for the key; the lead fixes the pin. | ||
| 2. **Never print or request a workspace key.** It is an administrative credential. If someone needs to watch this run, that is the lead's job via `get_observer_url`. |
There was a problem hiding this comment.
P3: After this change, step 2 is a static prohibition ("Never print or request a workspace key"), so the startup protocol's "If any of steps 1-2 fail, retry once" now only meaningfully applies to step 1 (register_agent). Consider rewording the retry clause to reference only the fallible step so the failure/retry semantics stay accurate.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plugins/claude-relay-plugin/agents/relay-worker/agent.md, line 10:
<comment>After this change, step 2 is a static prohibition ("Never print or request a workspace key"), so the startup protocol's "If any of steps 1-2 fail, retry once" now only meaningfully applies to step 1 (register_agent). Consider rewording the retry clause to reference only the fallible step so the failure/retry semantics stay accurate.</comment>
<file context>
@@ -6,8 +6,8 @@ You are a relay-connected worker in a coordinated multi-agent team. Your job is
-1. **Authenticate.** Your task prompt includes a workspace key. Call the `set_workspace_key` MCP tool with that key. Do not print the key to the user.
-2. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages.
+1. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. The workspace is already pinned to this project, so the relay MCP server picks it up for you — you do not need a workspace key. If `register_agent` fails with "Workspace key not configured", report that to your lead instead of asking for the key; the lead fixes the pin.
+2. **Never print or request a workspace key.** It is an administrative credential. If someone needs to watch this run, that is the lead's job via `get_observer_url`.
3. **Check your inbox.** Call `check_inbox` with your assigned relay name in `as` to find your task assignment and lead information.
4. **Send an ACK.** Before you do substantive work, send `ACK: <one-sentence understanding of the assignment>` to your lead via `send_dm`, again using your assigned relay name in `as`.
</file context>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
openclaw-orchestratordocuments a CLI that no longer exists. Nearly every command in it is wrong:agent-relay up --workspace-key … --no-spawnagent-relay node up --backgroundagent-relay spawn NAME CLI "task"agent-relay node agent spawn <cli> --name … --task …agent-relay agentsagent-relay node agent listagent-relay agents:logs NAMEagent-relay node tail --agent NAMEagent-relay agents:kill NAMEagent-relay node agent release NAMEagent-relay send '#chan' 'msg'/agent-relay inboxagent-relay message post/message inbox checkagent-relay downagent-relay node downmcporter call relaycast create_channel--channelson spawn--team TEAM--channelscreateProgram()inpackages/cli/src/cli/bootstrap.tsregisters none of those at the top level. Lifecycle lives underagent-relay node …, messaging underagent-relay message …, and the old flat surface survives only as a hidden, deprecatedlocalalias that prints a removal warning.Rather than re-document what
orchestrating-agent-relayalready covers correctly, this reduces the skill to what is genuinely OpenClaw-specific — the@agent-relay/openclawsetup,openclaw system eventcompletion reporting, provider quirks — and defers everything else to that skill. It names the removed commands explicitly, so an agent that has them in context from an older copy discards them rather than trusting them.Alternative worth considering: delete the skill outright. Its unique content is now about 30 lines, and everything else duplicates
orchestrating-agent-relay. I kept it because it's a published package (@agent-relay/openclaw-orchestrator) and removing one is your call, not mine.Also fixed
name:wasagent-relay-orchestratorwhile the directory and published package areopenclaw-orchestrator, so the installed skill registered under a name nothing else referenced. Also drops the non-contractversion:/homepage:/metadata:keys./spawnused the same removed commands, told the user to supply a workspace key thatnode upauto-creates, and pointed monitoring atagents:logs. Retargeted; it now also offers an observer link and warns against reading replies withnode tail./create-workflowreferencedagent-relay agents.prpm.json+ README:openclaw-orchestrator1.0.0 → 2.0.0 (rewrite),/spawn1.0.0 → 1.1.0,/create-workflow1.0.4 → 1.0.5.Part of a series from a review of the Agent Relay skills and plugins.
Test Plan
node agent spawn,node agent list,node agent attach,node agent release,node status,node up,message inbox check,observer— all return help, none errornode agent spawn --helpthat the flags are--name/--channels/--task/--modeland that no--teamflag existsagent-relay --helpthat the top-level surface has noup,spawn,agents,send, ordownprpm.jsonparses as valid JSON after the version bumpspackage.json, no CI workflows)Screenshots
n/a
Generated by Claude Code