From bd4cf113568e00493236040224463a4fa3d46198 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 14:20:55 +0000 Subject: [PATCH 1/2] fix(skills): correct using-agent-relay drift in the vendored copies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both vendored copies of `using-agent-relay` had drifted from the published skill and were wrong in four ways: - **A dead security warning was suppressing content.** The CLI reference omitted every startup and status command because "Published Agent Relay versions through 11.3.0 can print live workspace credentials … Upgrade to Agent Relay 11.3.1 or later." This repo is on 11.4.0 and 11.3.1 shipped, so the warning describes a fixed defect while still hiding working commands from agents. - **The MCP tool prefix was wrong.** It documented `mcp__relaycast__send_dm` and `mcp__agent_relay__send_dm`. The prefix comes from the server key, which is `agent-relay`, so the real form is `mcp__agent-relay__send_dm`. - **`list_dms` was missing** from the tool table, even though `orchestrating-agent-relay` tells agents to use it to re-read consumed DM history. - **The base URL example was the legacy `gateway.relaycast.dev` host.** Every default in this repo and in relaycast is `cast.agentrelay.com`. The published version is correct on all four and is a strict superset of the vendored CLI reference (it also documents `message inbox mark_read`, `message dm list`, `message get_thread`, `channel list`, `node up`, `node status`, and the deprecated `local` alias). Both copies are synced to it; nothing unique was lost. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- .agents/skills/using-agent-relay/SKILL.md | 68 +++++++++++++++-------- .claude/rules/sdk.md | 11 +++- .claude/skills/using-agent-relay/SKILL.md | 68 +++++++++++++++-------- 3 files changed, 98 insertions(+), 49 deletions(-) diff --git a/.agents/skills/using-agent-relay/SKILL.md b/.agents/skills/using-agent-relay/SKILL.md index e7a76f730..b220d321e 100644 --- a/.agents/skills/using-agent-relay/SKILL.md +++ b/.agents/skills/using-agent-relay/SKILL.md @@ -40,10 +40,10 @@ The current Agent Relay MCP server registers flat tool names. Use the final tool name exactly as listed here. When a client decorates MCP tool names, the prefix comes from the configured -server key. Workflow prompts commonly show forms like -`mcp__relaycast__send_dm`; a server configured as `agent-relay` may expose -`mcp__agent_relay__send_dm`. In every case, the canonical tool name is the flat -suffix, such as `send_dm`. +server key. With the relay broker's `agent-relay` server key, Claude Code users +will commonly see these as `mcp__agent-relay__`, for example +`mcp__agent-relay__send_dm`. Codex and opencode users see the bare canonical +names, such as `send_dm`. Do not use older category-expanded names such as `mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`, or @@ -76,6 +76,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 | +| `list_dms` | List your direct-message conversations | | `post_message` | Post to a channel | | `list_messages` | Read channel history | | `reply_to_thread` | Reply to an existing message | @@ -187,39 +188,59 @@ Release workers after their work is accepted: remove_agent(name: "reviewer-1", reason: "Review accepted") ``` -## Current CLI Reference +## 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: +Messaging (agent token; these are how a participant reads and replies): ```bash -agent-relay status -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 inbox mark_read msg_123 --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 dm list --workspace-key rk_live_... --token at_live_... # persistent DM history (unlike unread-only inbox check) 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 message get_thread msg_123 --workspace-key rk_live_... --token at_live_... +agent-relay channel list --workspace-key rk_live_... --token at_live_... +``` + +Workspace identity: + +```bash +agent-relay agent register Worker --workspace-key rk_live_... +agent-relay agent list --workspace-key rk_live_... ``` +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 agent attach Worker --mode view +agent-relay node agent release Worker +agent-relay node tail --agent Worker # worker output/TTY, not durable messages +agent-relay node tail # broker debug events (unfiltered), not messages +``` + +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`. + Use environment variables instead of flags when available: ```bash -RELAY_WORKSPACE_KEY=rk_live_... -RELAY_AGENT_TOKEN=at_live_... -RELAY_BASE_URL=https://gateway.relaycast.dev +export RELAY_WORKSPACE_KEY=rk_live_... +export RELAY_AGENT_TOKEN=at_live_... +export RELAY_BASE_URL=https://cast.agentrelay.com ``` ## Common Mistakes @@ -229,6 +250,7 @@ RELAY_BASE_URL=https://gateway.relaycast.dev | Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | | Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | | Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | +| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | | Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | | Forgetting to ACK | Send `ACK:` to the lead before starting work | | Finishing silently | Send `DONE:` with evidence before stopping | diff --git a/.claude/rules/sdk.md b/.claude/rules/sdk.md index a58e8b940..afb22094a 100644 --- a/.claude/rules/sdk.md +++ b/.claude/rules/sdk.md @@ -53,9 +53,14 @@ The SDK uses subpath exports: ## Communication Protocol -- **Primary**: MCP tools (`mcp__relaycast__message_dm_send`, - `mcp__relaycast__message_inbox_check`, `mcp__relaycast__agent_list`, - `mcp__relaycast__agent_add`, `mcp__relaycast__agent_remove`) +- **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 e7a76f730..b220d321e 100644 --- a/.claude/skills/using-agent-relay/SKILL.md +++ b/.claude/skills/using-agent-relay/SKILL.md @@ -40,10 +40,10 @@ The current Agent Relay MCP server registers flat tool names. Use the final tool name exactly as listed here. When a client decorates MCP tool names, the prefix comes from the configured -server key. Workflow prompts commonly show forms like -`mcp__relaycast__send_dm`; a server configured as `agent-relay` may expose -`mcp__agent_relay__send_dm`. In every case, the canonical tool name is the flat -suffix, such as `send_dm`. +server key. With the relay broker's `agent-relay` server key, Claude Code users +will commonly see these as `mcp__agent-relay__`, for example +`mcp__agent-relay__send_dm`. Codex and opencode users see the bare canonical +names, such as `send_dm`. Do not use older category-expanded names such as `mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`, or @@ -76,6 +76,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 | +| `list_dms` | List your direct-message conversations | | `post_message` | Post to a channel | | `list_messages` | Read channel history | | `reply_to_thread` | Reply to an existing message | @@ -187,39 +188,59 @@ Release workers after their work is accepted: remove_agent(name: "reviewer-1", reason: "Review accepted") ``` -## Current CLI Reference +## 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: +Messaging (agent token; these are how a participant reads and replies): ```bash -agent-relay status -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 inbox mark_read msg_123 --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 dm list --workspace-key rk_live_... --token at_live_... # persistent DM history (unlike unread-only inbox check) 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 message get_thread msg_123 --workspace-key rk_live_... --token at_live_... +agent-relay channel list --workspace-key rk_live_... --token at_live_... +``` + +Workspace identity: + +```bash +agent-relay agent register Worker --workspace-key rk_live_... +agent-relay agent list --workspace-key rk_live_... ``` +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 agent attach Worker --mode view +agent-relay node agent release Worker +agent-relay node tail --agent Worker # worker output/TTY, not durable messages +agent-relay node tail # broker debug events (unfiltered), not messages +``` + +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`. + Use environment variables instead of flags when available: ```bash -RELAY_WORKSPACE_KEY=rk_live_... -RELAY_AGENT_TOKEN=at_live_... -RELAY_BASE_URL=https://gateway.relaycast.dev +export RELAY_WORKSPACE_KEY=rk_live_... +export RELAY_AGENT_TOKEN=at_live_... +export RELAY_BASE_URL=https://cast.agentrelay.com ``` ## Common Mistakes @@ -229,6 +250,7 @@ RELAY_BASE_URL=https://gateway.relaycast.dev | Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | | Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | | Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | +| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | | Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | | Forgetting to ACK | Send `ACK:` to the lead before starting work | | Finishing silently | Send `DONE:` with evidence before stopping | From 848cf17c6224646dbd413d8a17cf1e2e7b2c887e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 3 Aug 2026 14:31:40 +0000 Subject: [PATCH 2/2] style: auto-format with Prettier --- .agents/skills/using-agent-relay/SKILL.md | 18 +++++++++--------- .claude/skills/using-agent-relay/SKILL.md | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.agents/skills/using-agent-relay/SKILL.md b/.agents/skills/using-agent-relay/SKILL.md index b220d321e..f72813d45 100644 --- a/.agents/skills/using-agent-relay/SKILL.md +++ b/.agents/skills/using-agent-relay/SKILL.md @@ -245,12 +245,12 @@ export RELAY_BASE_URL=https://cast.agentrelay.com ## Common Mistakes -| Mistake | Fix | -| --------------------------------------------- | ------------------------------------------------------------------------------ | -| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | -| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | -| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | -| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | -| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | -| Forgetting to ACK | Send `ACK:` to the lead before starting work | -| Finishing silently | Send `DONE:` with evidence before stopping | +| Mistake | Fix | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | +| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | +| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | +| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | +| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | +| Forgetting to ACK | Send `ACK:` to the lead before starting work | +| Finishing silently | Send `DONE:` with evidence before stopping | diff --git a/.claude/skills/using-agent-relay/SKILL.md b/.claude/skills/using-agent-relay/SKILL.md index b220d321e..f72813d45 100644 --- a/.claude/skills/using-agent-relay/SKILL.md +++ b/.claude/skills/using-agent-relay/SKILL.md @@ -245,12 +245,12 @@ export RELAY_BASE_URL=https://cast.agentrelay.com ## Common Mistakes -| Mistake | Fix | -| --------------------------------------------- | ------------------------------------------------------------------------------ | -| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | -| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | -| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | -| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | -| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | -| Forgetting to ACK | Send `ACK:` to the lead before starting work | -| Finishing silently | Send `DONE:` with evidence before stopping | +| Mistake | Fix | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Using `message_dm_send` or `message.post` | Use current flat tools: `send_dm`, `post_message`, `reply_to_thread` | +| Acting as orchestrator with participant tools | Use `orchestrating-agent-relay`, or register yourself first | +| Calling tools before selecting a workspace | Call `set_workspace_key` or `create_workspace` first | +| Reading peer replies via `node tail` | `node tail` streams broker events; `node tail --agent ` streams that worker's raw output — neither is durable messages. Read with `check_inbox` / `list_messages` / `get_message_thread` (or the `message` CLI group) | +| Spawning with `add_agent(name, type)` | `add_agent` needs `name`, `cli`, and `task`; use `register_agent` for identity | +| Forgetting to ACK | Send `ACK:` to the lead before starting work | +| Finishing silently | Send `DONE:` with evidence before stopping |