| name | swarm-request-response |
| description | Send a request and wait for the response on a channel pair |
Tips
- The ve command is an installed CLI tool, not a file in the repository. Do not
search for it - run it directly via Bash.
Instructions
Send a request to one channel and wait for the response on another. This
encapsulates the request-response pattern over swarm channel pairs — advancing
the response channel cursor to head, starting a background watch before
sending the request (to prevent races), and filtering broadcast responses for
relevance.
The most common channel pair is <project>-steward (request) /
<project>-changelog (response), but any two channels work.
Phase 1: Parse arguments
$ARGUMENTS
Extract from the arguments:
- Request channel — where to send the request (e.g.,
myproject-steward)
- Response channel — where to watch for the response (e.g.,
myproject-changelog)
- Message body — the request content
- Swarm ID — which swarm to use (optional if default is configured)
- Server URL — optional, for non-default backends
Project name shorthand: If the operator provides a project name instead of
explicit channels, derive the channel pair using the standard convention:
<project>-steward (request) and <project>-changelog (response).
If any required argument (request channel, response channel, message body) is
missing, ask the operator and stop.
Phase 2: Advance response channel cursor to head
Query current channel state:
ve board channels [--swarm <swarm_id>] [--server <url>]
Output format: Each line is <name> head=<N> oldest=<N>.
Parse the head=<N> value for the response channel. This is the offset we'll
use to start the watch — it skips all historical messages so we only see
responses that arrive after we start.
If the response channel doesn't exist yet in the output, warn the operator
and proceed with offset 0. The steward may create it on first response.
Phase 3: Start watching response channel in background
Start the watch before sending the request. This prevents the race
condition where the steward responds before we're listening:
ve board watch <response_channel> --offset <head_position> --swarm <swarm_id> [--server <url>]
Run with run_in_background. The --offset flag starts from the head
position (ephemeral — does not modify the persisted cursor). Record the task
ID for later use.
Watch safety: There must be only one watch per channel. If a previous
watch on the response channel is still running from an earlier invocation,
TaskStop it first. The CLI's PID-based kill provides a safety net, but
explicit task lifecycle management is preferred.
Phase 4: Send the request
Now that the watch is active, send the request:
ve board send <request_channel> "<message>" --swarm <swarm_id> [--server <url>]
Report the assigned position to the operator.
Phase 5: Receive and filter response
When the background watch returns a message, determine if it's actually a
response to this specific request. The response channel is a broadcast
channel — it may contain notifications from other requests or unrelated
activity.
Filtering heuristic — use your judgment to assess relevance. Signals include:
- Temporal proximity — the response arrived shortly after the request
- Content correlation — the response references or addresses the request topic
- Explicit acknowledgment — the response quotes or names the request
If the message is NOT relevant:
- Ack the response channel to advance past this message:
ve board ack <response_channel>
- Re-launch the watch in background (the persisted cursor has advanced via
ack, so no
--offset is needed now):
ve board watch <response_channel> --swarm <swarm_id> [--server <url>]
Run with run_in_background. Record the new task ID.
- Continue waiting for the next message.
If the message IS relevant:
- Return the response content to the operator
- Ack the response channel:
ve board ack <response_channel>
- Report success: what was sent, what was received, and on which channels.
Watch timeout: If the background watch exits with code 144 (Claude Code
task timeout), the steward may not have responded yet. TaskStop the timed-out
task, then re-launch the watch (without --offset — use the persisted cursor
position, since no acks have changed it):
ve board watch <response_channel> --swarm <swarm_id> [--server <url>]
Run with run_in_background and continue waiting.
Key Concepts
-
Why watch-before-send matters — if you send the request first, the
steward might respond before the watch starts, and the response is missed.
Starting the watch first ensures no responses are lost. The small window
between querying ve board channels and starting the watch is safe — any
message arriving in that window predates our request and will be correctly
filtered out as irrelevant.
-
--offset vs persisted cursor — the --offset flag is ephemeral and
used only for the initial watch to skip historical messages. After acking
irrelevant messages, subsequent re-watches use the persisted cursor
naturally (no --offset needed).
-
Channel pair convention — <project>-steward (request) /
<project>-changelog (response) is the standard pair, but any two channels
can form a request-response pair.
-
Broadcast channel filtering — the response channel is shared. Not every
message on it is a response to your request. Use the filtering heuristic to
distinguish relevant responses from unrelated activity.
-
Manual cursor management — this skill uses ve board ack explicitly
(like /steward-watch), not auto-advancing cursors (like /swarm-monitor).
Ack only after you've determined whether the message is relevant or not.