From ec97e4bf7cda974bfa8de868a542597bb9710dcd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 14:20:55 +0000 Subject: [PATCH 1/2] fix(skills): finish the using-agent-relay drift cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Main has since fixed the MCP tool prefix and added the injection-mode guidance (`mode: "wait"` vs `"steer"`, `get_message_readers`), so this rebuilds the vendored copies on top of that rather than syncing them to the published skill, which would now regress both. Three drift items survived and are fixed here, plus two from review: - **A dead security warning was suppressing working content.** The CLI reference omitted every startup and status command because "versions through 11.3.0 can print live workspace credentials … upgrade to 11.3.1 or later." Main is on 11.8.0. The warning describes a defect fixed four minor versions ago while still hiding commands agents need. - **`gateway.relaycast.dev`** was the documented `RELAY_BASE_URL`. The default in this repo and in relaycast is `cast.agentrelay.com`. - **`list_dms` was missing** from the tool table, though `orchestrating-agent-relay` tells agents to use it to re-read consumed DM history. - **Credentials moved out of argv** (review). Every example passed `--workspace-key rk_live_... --token at_live_...` as arguments, which are visible to other processes via `ps` and land in shell history and CI logs. The examples now export the documented environment variables once, with a note that the flags exist for when env is not an option. - **`` replaced with `"$CONVERSATION_ID"`** (review) — angle brackets are shell redirection, so the old example could not be pasted as written. Also keeps the fuller `.claude/rules/sdk.md` wording: main corrected the prefix, but this additionally names the canonical flat tool names and warns off the category-expanded forms that `using-agent-relay` already tells agents not to use. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- .agents/skills/using-agent-relay/SKILL.md | 70 ++++++++++++++++------- .claude/rules/sdk.md | 12 ++-- .claude/skills/using-agent-relay/SKILL.md | 70 ++++++++++++++++------- 3 files changed, 104 insertions(+), 48 deletions(-) diff --git a/.agents/skills/using-agent-relay/SKILL.md b/.agents/skills/using-agent-relay/SKILL.md index d139db642c..24a00cc537 100644 --- a/.agents/skills/using-agent-relay/SKILL.md +++ b/.agents/skills/using-agent-relay/SKILL.md @@ -77,6 +77,7 @@ Do not use older category-expanded names such as | `send_dm` | Send a direct message to one agent | | `send_group_dm` | Create a group DM and send the first message | | `post_message` | Post to a channel | +| `list_dms` | List your direct-message conversations | | `list_messages` | Read channel history | | `reply_to_thread` | Reply to an existing message | | `get_message_thread` | Read a thread | @@ -198,38 +199,63 @@ remove_agent(name: "reviewer-1", reason: "Review accepted") ## Current CLI Reference -Startup and status commands are intentionally omitted from these agent-facing -examples. Published Agent Relay versions through 11.3.0 can print live -workspace credentials when those commands run in a transcribed session. Upgrade -to Agent Relay 11.3.1 or later before running them there. +Prefer the MCP tools above for messaging. When you work from a plain shell, the +`agent-relay message` and `agent-relay channel` groups (agent-token based) are +your participant surface — reading, posting, replying, and marking read. The +`agent-relay node` group is broker lifecycle and debug only. -These are the current CLI forms for local broker and SDK-backed messaging -operations: +Export your credentials once instead of repeating them as flags. Command-line +arguments are visible to other processes on the machine (`ps`), and they land in +shell history and CI logs: ```bash -agent-relay status +export RELAY_WORKSPACE_KEY=rk_live_... +export RELAY_AGENT_TOKEN=at_live_... +export RELAY_BASE_URL=https://cast.agentrelay.com # only to override the default +``` + +Messaging (agent token; these are how a participant reads and replies): + +```bash +agent-relay message inbox check +agent-relay message inbox mark_read msg_123 +agent-relay message dm send Lead "ACK: I am online." +agent-relay message dm list "$CONVERSATION_ID" # persistent DM history (unlike unread-only inbox check) +agent-relay message post general "Status update" +agent-relay message list general +agent-relay message reply msg_123 "Thread reply" +agent-relay message get_thread msg_123 +agent-relay channel list +``` + +Workspace identity: + +```bash +agent-relay agent register Worker +agent-relay agent list +``` + +Local broker lifecycle and debug (lifecycle only — read replies through the +`message` group above, never `node tail`): + +```bash +agent-relay status # workspace + cloud + broker overview +agent-relay node up --background --verbose +agent-relay node status --wait-for 10 agent-relay node agent list agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay." -agent-relay node tail --agent Worker agent-relay node agent attach Worker --mode view agent-relay node agent release Worker - -agent-relay agent register Worker --workspace-key rk_live_... -agent-relay agent list --workspace-key rk_live_... -agent-relay message inbox check --workspace-key rk_live_... --token at_live_... -agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_... -agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_... -agent-relay message list general --workspace-key rk_live_... --token at_live_... -agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_... +agent-relay node tail --agent Worker # worker output/TTY, not durable messages +agent-relay node tail # broker debug events (unfiltered), not messages ``` -Use environment variables instead of flags when available: +These lifecycle commands live under `agent-relay node …`. The old flat +`agent-relay local …` group still works as a hidden, deprecated alias (it prints +a removal warning) — prefer `node`. -```bash -RELAY_WORKSPACE_KEY=rk_live_... -RELAY_AGENT_TOKEN=at_live_... -RELAY_BASE_URL=https://gateway.relaycast.dev -``` +Every command above accepts explicit `--workspace-key` / `--token` / `--base-url` +flags too, but only reach for them when you cannot set the environment. ## Common Mistakes diff --git a/.claude/rules/sdk.md b/.claude/rules/sdk.md index 5ecc56f1ff..afb22094aa 100644 --- a/.claude/rules/sdk.md +++ b/.claude/rules/sdk.md @@ -53,10 +53,14 @@ The SDK uses subpath exports: ## Communication Protocol -- **Primary**: MCP tools (`mcp__agent-relay__send_dm`, - `mcp__agent-relay__post_message`, `mcp__agent-relay__check_inbox`, - `mcp__agent-relay__list_agents`, `mcp__agent-relay__add_agent`, - `mcp__agent-relay__remove_agent`) +- **Primary**: MCP tools. The canonical names are flat — `send_dm`, + `check_inbox`, `post_message`, `list_agents`, `add_agent`, `remove_agent`. + A client may decorate them with the configured server key, so Claude Code + users typically see `mcp__agent-relay__send_dm` while Codex and opencode see + the bare name. +- Do **not** use the older category-expanded forms + (`mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`, + `message.post`). They are not registered by `agent-relay mcp`. ## No Storage Layer diff --git a/.claude/skills/using-agent-relay/SKILL.md b/.claude/skills/using-agent-relay/SKILL.md index d139db642c..24a00cc537 100644 --- a/.claude/skills/using-agent-relay/SKILL.md +++ b/.claude/skills/using-agent-relay/SKILL.md @@ -77,6 +77,7 @@ Do not use older category-expanded names such as | `send_dm` | Send a direct message to one agent | | `send_group_dm` | Create a group DM and send the first message | | `post_message` | Post to a channel | +| `list_dms` | List your direct-message conversations | | `list_messages` | Read channel history | | `reply_to_thread` | Reply to an existing message | | `get_message_thread` | Read a thread | @@ -198,38 +199,63 @@ remove_agent(name: "reviewer-1", reason: "Review accepted") ## Current CLI Reference -Startup and status commands are intentionally omitted from these agent-facing -examples. Published Agent Relay versions through 11.3.0 can print live -workspace credentials when those commands run in a transcribed session. Upgrade -to Agent Relay 11.3.1 or later before running them there. +Prefer the MCP tools above for messaging. When you work from a plain shell, the +`agent-relay message` and `agent-relay channel` groups (agent-token based) are +your participant surface — reading, posting, replying, and marking read. The +`agent-relay node` group is broker lifecycle and debug only. -These are the current CLI forms for local broker and SDK-backed messaging -operations: +Export your credentials once instead of repeating them as flags. Command-line +arguments are visible to other processes on the machine (`ps`), and they land in +shell history and CI logs: ```bash -agent-relay status +export RELAY_WORKSPACE_KEY=rk_live_... +export RELAY_AGENT_TOKEN=at_live_... +export RELAY_BASE_URL=https://cast.agentrelay.com # only to override the default +``` + +Messaging (agent token; these are how a participant reads and replies): + +```bash +agent-relay message inbox check +agent-relay message inbox mark_read msg_123 +agent-relay message dm send Lead "ACK: I am online." +agent-relay message dm list "$CONVERSATION_ID" # persistent DM history (unlike unread-only inbox check) +agent-relay message post general "Status update" +agent-relay message list general +agent-relay message reply msg_123 "Thread reply" +agent-relay message get_thread msg_123 +agent-relay channel list +``` + +Workspace identity: + +```bash +agent-relay agent register Worker +agent-relay agent list +``` + +Local broker lifecycle and debug (lifecycle only — read replies through the +`message` group above, never `node tail`): + +```bash +agent-relay status # workspace + cloud + broker overview +agent-relay node up --background --verbose +agent-relay node status --wait-for 10 agent-relay node agent list agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay." -agent-relay node tail --agent Worker agent-relay node agent attach Worker --mode view agent-relay node agent release Worker - -agent-relay agent register Worker --workspace-key rk_live_... -agent-relay agent list --workspace-key rk_live_... -agent-relay message inbox check --workspace-key rk_live_... --token at_live_... -agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_... -agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_... -agent-relay message list general --workspace-key rk_live_... --token at_live_... -agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_... +agent-relay node tail --agent Worker # worker output/TTY, not durable messages +agent-relay node tail # broker debug events (unfiltered), not messages ``` -Use environment variables instead of flags when available: +These lifecycle commands live under `agent-relay node …`. The old flat +`agent-relay local …` group still works as a hidden, deprecated alias (it prints +a removal warning) — prefer `node`. -```bash -RELAY_WORKSPACE_KEY=rk_live_... -RELAY_AGENT_TOKEN=at_live_... -RELAY_BASE_URL=https://gateway.relaycast.dev -``` +Every command above accepts explicit `--workspace-key` / `--token` / `--base-url` +flags too, but only reach for them when you cannot set the environment. ## Common Mistakes From ef3905e169e3f2e0b7d0008f56722b71016e94be Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 13:18:08 +0000 Subject: [PATCH 2/2] fix(skills): scope the credential-flag note to the SDK-backed groups Review caught that the closing note claimed "every command above" accepts `--workspace-key` / `--token` / `--base-url`. The `node` group does not. Verified against a build of the current CLI: - `node agent list` takes only `--pretty` and `--status` - `node tail`, `node agent release`, `node agent spawn` take no connection flags at all - `node status` takes only `--state-dir` - `node agent attach` uses `--broker-url` / `--api-key` / `--state-dir` - `node up --workspace-key` exists but means something else ("use a pre-established Relaycast workspace key"), and there is no `--token` or `--base-url` anywhere in the group The node group talks to the local broker over its own connection model (`RELAY_BROKER_URL` / `RELAY_BROKER_API_KEY`), not the SDK workspace and agent-token model. As written, the note would have sent an agent to add flags that error out. Now scoped to `message`, `channel`, and `agent`, with the node group's separate model stated explicitly. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- .agents/skills/using-agent-relay/SKILL.md | 8 ++++++-- .claude/skills/using-agent-relay/SKILL.md | 8 ++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/.agents/skills/using-agent-relay/SKILL.md b/.agents/skills/using-agent-relay/SKILL.md index 24a00cc537..546c996811 100644 --- a/.agents/skills/using-agent-relay/SKILL.md +++ b/.agents/skills/using-agent-relay/SKILL.md @@ -254,8 +254,12 @@ These lifecycle commands live under `agent-relay node …`. The old flat `agent-relay local …` group still works as a hidden, deprecated alias (it prints a removal warning) — prefer `node`. -Every command above accepts explicit `--workspace-key` / `--token` / `--base-url` -flags too, but only reach for them when you cannot set the environment. +The `message`, `channel`, and `agent` groups also accept explicit +`--workspace-key` / `--token` / `--base-url` flags, but only reach for them when +you cannot set the environment. The `node` group does **not** take those — it +talks to the local broker over its own `--broker-url` / `--api-key` / +`--state-dir` flags (`RELAY_BROKER_URL`, `RELAY_BROKER_API_KEY`), and the +`--workspace-key` on `node up` is a different flag with a different meaning. ## Common Mistakes diff --git a/.claude/skills/using-agent-relay/SKILL.md b/.claude/skills/using-agent-relay/SKILL.md index 24a00cc537..546c996811 100644 --- a/.claude/skills/using-agent-relay/SKILL.md +++ b/.claude/skills/using-agent-relay/SKILL.md @@ -254,8 +254,12 @@ These lifecycle commands live under `agent-relay node …`. The old flat `agent-relay local …` group still works as a hidden, deprecated alias (it prints a removal warning) — prefer `node`. -Every command above accepts explicit `--workspace-key` / `--token` / `--base-url` -flags too, but only reach for them when you cannot set the environment. +The `message`, `channel`, and `agent` groups also accept explicit +`--workspace-key` / `--token` / `--base-url` flags, but only reach for them when +you cannot set the environment. The `node` group does **not** take those — it +talks to the local broker over its own `--broker-url` / `--api-key` / +`--state-dir` flags (`RELAY_BROKER_URL`, `RELAY_BROKER_API_KEY`), and the +`--workspace-key` on `node up` is a different flag with a different meaning. ## Common Mistakes