From 3572a05f2cea8247d2fe8e74173150163b8b87ba Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Aug 2026 14:31:40 +0000 Subject: [PATCH] feat(orchestrating-agent-relay): teach the orchestrator to hand out an observer link MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The orchestrator is exactly the role that should give a watching human a way to follow a run, and this skill never mentioned observation at all — no observer link, no warning against building one from the workspace key. That silence is why leads reach for `?key=`: it is the only pattern they have seen. Adds `agent-relay observer` (and the `get_observer_url` MCP equivalent) in the four places a lead actually looks: the Quick Reference table, a new bootstrap step after spawning, the paste-worthy protocol template, and the Common Mistakes table. Each states the default posture — read-only, 24h expiry, agent DMs excluded — and why a workspace key can never take its place. Requires the command and tool from AgentWorkforce/relay#1422. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Jmke9G9s7ftrN49opNmdx1 --- README.md | 2 +- prpm.json | 2 +- skills/orchestrating-agent-relay/SKILL.md | 27 +++++++++++++++++++++++ 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5d385fb..99a0441 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes ` | [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.18 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, Relayfile-backed Slack human assistance, integration subscriptions, waitFor gates, review-depth review/fix loops, channels, and chat-native coordination recipes. | | [setting-up-relayfile](skills/setting-up-relayfile/SKILL.md) | 1.1.1 | Set up Relayfile mounts and writeback for provider files through local filesystem access. | | [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.4.0 | Participant-side MCP reference for a **registered** relay agent (spawned worker / registered lead): messaging, channels, threads, reactions, search, inbox, actions, and worker spawn/release. Counterpart to `orchestrating-agent-relay`. | -| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.2.0 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention. | +| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.3.0 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention. | | [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.8 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, review-depth review/fix with test hardening, and commit gates. | | [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.2 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. | | [trigger-autocomplete-catalog](skills/trigger-autocomplete-catalog/SKILL.md) | 1.0.0 | Enforce webhook/event trigger autocomplete coverage through KNOWN_TRIGGER_CATALOG in @relayfile/adapter-core. | diff --git a/prpm.json b/prpm.json index 0339e99..b448b1b 100644 --- a/prpm.json +++ b/prpm.json @@ -89,7 +89,7 @@ }, { "name": "orchestrating-agent-relay", - "version": "2.2.0", + "version": "2.3.0", "description": "The canonical way to run agent-relay - self-bootstrap the local broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, message-based reading via the relay MCP, and team coordination.", "format": "claude", "subtype": "skill", diff --git a/skills/orchestrating-agent-relay/SKILL.md b/skills/orchestrating-agent-relay/SKILL.md index 6eeb350..a3f8c29 100644 --- a/skills/orchestrating-agent-relay/SKILL.md +++ b/skills/orchestrating-agent-relay/SKILL.md @@ -62,6 +62,7 @@ reference is the **`using-agent-relay`** skill. | Send DM to worker (MCP) | `send_dm(to: "Worker1", text: "...")` | | Post to channel (MCP) | `post_message(channel: "general", text: "...")` | | Read worker replies (MCP) | `check_inbox(limit: 20)` / `list_messages(channel: "general")` | +| Give a human a follow-along link | `agent-relay observer` | | Inspect a worker's TTY | `agent-relay node agent attach Worker1 --mode view` | | Release worker | `agent-relay node agent release Worker1` | | Stop broker | `agent-relay node down` | @@ -156,6 +157,28 @@ runs in `interactive` spawn mode; pass `--exit-after-task` for a one-shot worker > for at least 60s (e.g. a 30-iteration poll) before escalating to > troubleshooting. +### Step 2.5: Give the Human a Way to Watch (optional) + +A human driving an autonomous run usually wants to see what the team is saying +without joining it. Hand them a read-only observer link: + +```bash +agent-relay observer +``` + +That prints a URL backed by a scoped `ot_live_` token — read-only, expiring in +24 hours, agent DMs excluded. Narrow it with `--channels build,review`, widen it +with `--include-dms` or `--expires 7d`, and cut it off early with +`agent-relay observer revoke `. + +From the relay MCP, the equivalent is `get_observer_url`. + +> **Never build an observer URL from the workspace key.** `rk_live_` is an +> administrative credential — it can send messages, spawn agents, and change +> workspace settings — and a URL query string is not a place to put one. The +> realtime endpoint rejects it anyway; only a scoped observer token with +> `stream:read` is accepted. + ### Step 3: Monitor and Coordinate The orchestrator reads and sends through the relay MCP (it is auto-registered as @@ -342,6 +365,9 @@ Quick Reference. Then enforce this protocol: model - Poll `agent-relay node agent list` for worker liveness; set a wall-clock fallback so a silently-dead worker can't hang the loop +- If a human is watching, give them a follow-along link with + `agent-relay observer` and print the URL it returns. Never print the + workspace key or put it in a URL ``` ## Multi-Round Review Loops (DONE → NO-GO → fix → re-review) @@ -470,6 +496,7 @@ named `target_node`). | New worker appears in `node agent list` but no ACK yet | Expected — appearing means process up (~5s); the CLI cold-starts for another 30–45s before its first ACK DM. Wait ≥60s before troubleshooting a fresh worker | | Harness blocks `sleep 25; check_inbox ...` | Bare foreground `sleep` wait loops are disallowed in harnessed environments. Run the poll loop with `run_in_background` (or Monitor + until-loop); the inline `sleep` snippets show logic only | | Worker self-removed; can't send review fixes | Instruct workers not to self-remove until told. If already gone, spawn a fresh worker and re-inject branch + commit SHA + full verdict (see Multi-Round Review Loops) | +| Told the user to open an observer URL built from the workspace key | That is an admin credential in a query string, and the realtime endpoint rejects it. Run `agent-relay observer` (or `get_observer_url`) and share the `ot_live_` URL it returns | | Worker died silently; loop hangs | Inbox polling fires on messages only. Poll `agent-relay node agent list` for liveness and set a wall-clock fallback (~30 min ScheduleWakeup) | ## Prerequisites