agent-relay-plugin 0.3.8 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "agent-relay",
   "description": "Client connector for Agent Relay — auto-registers Claude Code sessions as agents and enables inter-agent messaging via a lightweight HTTP message bus",
-  "version": "0.3.8"
+  "version": "0.4.0"
 }

package/hooks/poll-inbox.sh

@@ -6,6 +6,10 @@
 RELAY_URL="$1"
 AGENT_ID="$2"
 INTERVAL="${3:-10}"
+auth_header_args=()
+if [ -n "${AGENT_RELAY_TOKEN:-}" ]; then
+  auth_header_args=(-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}")
+fi
 
 if [ -z "$RELAY_URL" ] || [ -z "$AGENT_ID" ]; then
   echo "Usage: poll-inbox.sh <relay-url> <agent-id> [interval]" >&2
@@ -19,12 +23,12 @@ trap cleanup EXIT
 echo $$ > "$pid_file"
 
 # Bootstrap cursor at current max so we only see messages arriving after session start.
-since_id=$(curl -s "${RELAY_URL}/api/messages/cursor" 2>/dev/null | jq -r '.latestId // 0' 2>/dev/null || echo 0)
+since_id=$(curl -s "${auth_header_args[@]}" "${RELAY_URL}/api/messages/cursor" 2>/dev/null | jq -r '.latestId // 0' 2>/dev/null || echo 0)
 
 fail_streak=0
 marked_ready=false
 while true; do
-  hb_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+  hb_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${auth_header_args[@]}" \
     "${RELAY_URL}/api/agents/${AGENT_ID}/heartbeat" 2>/dev/null)
 
   # Agent was deleted or doesn't exist — we're orphaned, exit.
@@ -32,7 +36,7 @@ while true; do
     exit 0
   fi
 
-  msgs=$(curl -s --fail "${RELAY_URL}/api/messages?for=${AGENT_ID}&sinceId=${since_id}&unread=true" 2>/dev/null)
+  msgs=$(curl -s --fail "${auth_header_args[@]}" "${RELAY_URL}/api/messages?for=${AGENT_ID}&sinceId=${since_id}&unread=true" 2>/dev/null)
   poll_rc=$?
 
   if [ "$hb_code" != "200" ] || [ $poll_rc -ne 0 ]; then
@@ -52,7 +56,7 @@ while true; do
   fail_streak=0
 
   if [ "$marked_ready" = "false" ]; then
-    curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${AGENT_ID}/ready" \
+    curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${AGENT_ID}/ready" "${auth_header_args[@]}" \
       -H 'Content-Type: application/json' -d '{"ready":true}' 2>/dev/null
     marked_ready=true
   fi
@@ -62,7 +66,7 @@ while true; do
     echo "$msgs" | jq -r '.[] | if .type == "system" then "⚠ SYSTEM [msg:\(.id)]: \(.body)" else "[msg:\(.id)] \(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)" end'
     since_id=$(echo "$msgs" | jq '[.[].id] | max')
     echo "$msgs" | jq -r '.[].id' | while read -r mid; do
-      curl -s -X PATCH "${RELAY_URL}/api/messages/${mid}" \
+      curl -s -X PATCH "${RELAY_URL}/api/messages/${mid}" "${auth_header_args[@]}" \
         -H 'Content-Type: application/json' \
         -d "{\"readBy\":\"${AGENT_ID}\"}" > /dev/null 2>&1 || true
     done

package/hooks/relay-monitor.sh

@@ -6,6 +6,11 @@
 
 RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
 PLUGIN_VERSION=$(jq -r '.version' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || echo "unknown")
+auth_header_args=()
+auth_header_example=' ${AGENT_RELAY_TOKEN:+-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}"}'
+if [ -n "${AGENT_RELAY_TOKEN:-}" ]; then
+  auth_header_args=(-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}")
+fi
 
 # --- Compute agent identity ---
 machine=$(hostname)
@@ -39,7 +44,7 @@ if [ -f "$instance_state" ]; then
       fi
       rm -f "$old_pid_file"
     fi
-    curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${old_agent_id}/status" \
+    curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${old_agent_id}/status" "${auth_header_args[@]}" \
       -H 'Content-Type: application/json' -d '{"status":"offline"}' 2>/dev/null
   fi
 fi
@@ -49,7 +54,7 @@ printf '%s\n' "$agent_id" > "$instance_state"
 caps_csv="${AGENT_RELAY_CAPS:-chat}"
 caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
 
-reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" \
+reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" "${auth_header_args[@]}" \
   -H 'Content-Type: application/json' \
   -d "$(jq -n \
     --arg id "$agent_id" \
@@ -67,7 +72,7 @@ if [ "$reg_code" != "201" ] && [ "$reg_code" != "200" ]; then
 fi
 
 # --- Check server version ---
-server_version=$(curl -s "${RELAY_URL}/api/stats" 2>/dev/null | jq -r '.version // empty' 2>/dev/null)
+server_version=$(curl -s "${auth_header_args[@]}" "${RELAY_URL}/api/stats" 2>/dev/null | jq -r '.version // empty' 2>/dev/null)
 version_warning=""
 if [ -z "$server_version" ]; then
   version_warning="⚠ Server does not report its version — consider updating: bunx agent-relay-server@latest"
@@ -81,41 +86,43 @@ Agent Relay active. Your agent ID: ${agent_id}
 Relay URL: ${RELAY_URL} | Server: ${server_version:-unknown} | Plugin: ${PLUGIN_VERSION}
 
 To send a message:
-  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE"}'
+  curl -s -X POST ${RELAY_URL}/api/messages${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE"}'
   TARGET: agent-id (direct), tag:NAME (by tag), cap:NAME (by capability), label:NAME (by human-set label, fan-out), broadcast (all)
 
 To rename yourself (set a short, human-friendly label so the user can refer to you easily):
-  curl -s -X PATCH ${RELAY_URL}/api/agents/${agent_id}/label -H 'Content-Type: application/json' -d '{"label":"backend fixing"}'
+  curl -s -X PATCH ${RELAY_URL}/api/agents/${agent_id}/label${auth_header_example} -H 'Content-Type: application/json' -d '{"label":"backend fixing"}'
   When the user tells you to rename yourself ("call yourself X", "rename to X"), call this endpoint.
   Labels are NOT unique — if multiple sessions share a label, \`to: "label:X"\` fans out to all of them.
   Use \`to: "label:backend fixing"\` when the user says "tell 'backend fixing' to do Y".
 
 To reply to a message (threading):
-  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE","replyTo":MSG_ID}'
+  curl -s -X POST ${RELAY_URL}/api/messages${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE","replyTo":MSG_ID}'
   Always use replyTo when responding to a specific message — it creates a thread.
   The inbox monitor prefixes each message with [msg:ID] — parse the ID from there.
+  Message etiquette: when another agent messages you, send a short acknowledgement or status reply unless the message is obvious spam/noise.
+  Anti-loop rule: do not auto-reply to pure acknowledgements, "thanks", or "received" messages; acknowledge once, then only send follow-ups when there is new work, a decision, or a deliverable.
 
 To send a claimable task (only one agent can claim it):
-  curl -s -X POST ${RELAY_URL}/api/messages -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"cap:review","body":"TASK","claimable":true}'
+  curl -s -X POST ${RELAY_URL}/api/messages${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"cap:review","body":"TASK","claimable":true}'
 
 To claim a task:
-  curl -s -X POST ${RELAY_URL}/api/messages/MSG_ID/claim -H 'Content-Type: application/json' -d '{"agentId":"${agent_id}"}'
+  curl -s -X POST ${RELAY_URL}/api/messages/MSG_ID/claim${auth_header_example} -H 'Content-Type: application/json' -d '{"agentId":"${agent_id}"}'
   When you see a claimable message, claim it BEFORE starting work. If claim fails, someone else got it — move on.
 
 To view a thread:
-  curl -s '${RELAY_URL}/api/messages/MSG_ID/thread'
+  curl -s${auth_header_example} '${RELAY_URL}/api/messages/MSG_ID/thread'
 
 To check messages:
-  curl -s '${RELAY_URL}/api/messages?for=${agent_id}&unread=true'
+  curl -s${auth_header_example} '${RELAY_URL}/api/messages?for=${agent_id}&unread=true'
 
 To mark read:
-  curl -s -X PATCH ${RELAY_URL}/api/messages/ID -H 'Content-Type: application/json' -d '{"readBy":"${agent_id}"}'
+  curl -s -X PATCH ${RELAY_URL}/api/messages/ID${auth_header_example} -H 'Content-Type: application/json' -d '{"readBy":"${agent_id}"}'
 
 To find agents by capability:
-  curl -s '${RELAY_URL}/api/agents/find?capability=review'
+  curl -s${auth_header_example} '${RELAY_URL}/api/agents/find?capability=review'
 
 To list online agents:
-  curl -s '${RELAY_URL}/api/agents?status=online'
+  curl -s${auth_header_example} '${RELAY_URL}/api/agents?status=online'
 
 System messages:
   Messages prefixed with "⚠ SYSTEM" are relay-level instructions (e.g. plugin updates, restart requests).
@@ -128,7 +135,7 @@ if [ -n "$version_warning" ]; then
 fi
 
 # --- Check for unread messages ---
-unread=$(curl -s "${RELAY_URL}/api/messages?for=${agent_id}&unread=true" 2>/dev/null)
+unread=$(curl -s "${auth_header_args[@]}" "${RELAY_URL}/api/messages?for=${agent_id}&unread=true" 2>/dev/null)
 unread_count=$(echo "$unread" | jq 'length' 2>/dev/null || echo "0")
 if [ "$unread_count" -gt 0 ] 2>/dev/null && [ "$unread_count" != "0" ]; then
   echo ""

package/hooks/session-end.sh

@@ -3,12 +3,16 @@
 # Marks this session's agent as offline using state file written by relay-monitor.
 
 RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
+auth_header_args=()
+if [ -n "${AGENT_RELAY_TOKEN:-}" ]; then
+  auth_header_args=(-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}")
+fi
 instance_state="/tmp/agent-relay-instance-${PPID}.state"
 
 if [ -f "$instance_state" ]; then
   agent_id=$(head -1 "$instance_state" 2>/dev/null)
   if [ -n "$agent_id" ]; then
-    curl -s -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" \
+    curl -s -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" "${auth_header_args[@]}" \
       -H 'Content-Type: application/json' \
       -d '{"status":"offline"}' \
       > /dev/null 2>&1 &

package/hooks/set-status.sh

@@ -9,6 +9,10 @@ case "$status" in
 esac
 
 RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
+auth_header_args=()
+if [ -n "${AGENT_RELAY_TOKEN:-}" ]; then
+  auth_header_args=(-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}")
+fi
 instance_state="/tmp/agent-relay-instance-${PPID}.state"
 
 if [ ! -f "$instance_state" ]; then
@@ -20,7 +24,7 @@ if [ -z "$agent_id" ]; then
   exit 0
 fi
 
-curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" \
+curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" "${auth_header_args[@]}" \
   -H 'Content-Type: application/json' \
   -d "{\"status\":\"${status}\"}" \
   2>/dev/null || true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-plugin",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Claude Code plugin for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
   "type": "module",
   "license": "MIT",