swarm-request-response

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:

1. Ack the response channel to advance past this message:

   ve board ack <response_channel>
   

2. 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.
3. Continue waiting for the next message.

If the message IS relevant:

1. Return the response content to the operator
2. Ack the response channel:

   ve board ack <response_channel>
   

3. 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.