agent-relay-plugin 0.4.16 → 0.4.18

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.4.16"
+  "version": "0.4.18"
 }

package/hooks/approval-gate.sh

@@ -1,8 +1,16 @@
 #!/usr/bin/env bash
 # Agent Relay plugin — approval gate for PreToolUse and PermissionDenied hooks.
-# Enforces AGENT_RELAY_APPROVAL policy: open (default), guarded, read-only.
+# Enforces AGENT_RELAY_APPROVAL/profile approval policy: open (default), guarded, read-only.
 
-MODE="${AGENT_RELAY_APPROVAL:-open}"
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "${script_dir}/profile-lib.sh"
+project=$(basename "${PWD:-unknown}")
+if [ -n "$CLAUDE_RIG_NAME" ]; then rig="$CLAUDE_RIG_NAME"
+elif [ -n "$CLAUDE_CONFIG_DIR" ]; then rig=$(basename "$CLAUDE_CONFIG_DIR")
+else rig="default"; fi
+ar_init_profile "claude" "$rig" "$project"
+MODE="${AGENT_RELAY_APPROVAL:-$AR_APPROVAL}"
+MODE="${MODE:-open}"
 [ "$MODE" = "open" ] && exit 0
 
 input=$(cat)

package/hooks/poll-inbox.sh

@@ -6,6 +6,8 @@
 RELAY_URL="$1"
 AGENT_ID="$2"
 INTERVAL="${3:-10}"
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "${script_dir}/profile-lib.sh"
 auth_header_args=()
 if [ -n "${AGENT_RELAY_TOKEN:-}" ]; then
   auth_header_args=(-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}")
@@ -19,6 +21,11 @@ fi
 # PID file so session-start.sh can find and kill us on /clear or /compact.
 pid_file="/tmp/agent-relay-poll-${AGENT_ID}.pid"
 status_file="/tmp/agent-relay-status-${AGENT_ID}.state"
+project=$(basename "${PWD:-unknown}")
+if [ -n "$CLAUDE_RIG_NAME" ]; then rig="$CLAUDE_RIG_NAME"
+elif [ -n "$CLAUDE_CONFIG_DIR" ]; then rig=$(basename "$CLAUDE_CONFIG_DIR")
+else rig="default"; fi
+ar_init_profile "claude" "$rig" "$project"
 cleanup() { rm -f "$pid_file"; }
 trap cleanup EXIT
 echo $$ > "$pid_file"
@@ -42,15 +49,13 @@ current_status() {
 }
 
 re_register() {
-  local machine rig project caps_csv caps_json approval reg_code
+  local machine rig project reg_code
   machine=$(hostname)
   project=$(basename "${PWD:-unknown}")
   if [ -n "$CLAUDE_RIG_NAME" ]; then rig="$CLAUDE_RIG_NAME"
   elif [ -n "$CLAUDE_CONFIG_DIR" ]; then rig=$(basename "$CLAUDE_CONFIG_DIR")
   else rig="default"; fi
-  caps_csv="${AGENT_RELAY_CAPS:-chat}"
-  caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
-  approval="${AGENT_RELAY_APPROVAL:-open}"
+  ar_init_profile "claude" "$rig" "$project"
 
   reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" "${auth_header_args[@]}" \
     -H 'Content-Type: application/json' \
@@ -59,10 +64,11 @@ re_register() {
       --arg name "$project ($rig @ $machine)" \
       --arg machine "$machine" \
       --arg rig "$rig" \
-      --argjson tags "$(jq -n --arg r "$rig" --arg p "$project" '[$r, $p]')" \
-      --argjson caps "$caps_json" \
-      --argjson meta "$(jq -n --arg cwd "$PWD" --arg approval "$approval" '{cwd: $cwd, approvalMode: $approval}')" \
-      '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta}'
+      --arg label "$AR_LABEL" \
+      --argjson tags "$AR_TAGS_JSON" \
+      --argjson caps "$AR_CAPS_JSON" \
+      --argjson meta "$AR_META_JSON" \
+      '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta} + (if $label != "" then {label: $label} else {} end)'
     )" 2>/dev/null)
 
   [ "$reg_code" = "200" ] || [ "$reg_code" = "201" ]
@@ -133,6 +139,9 @@ while true; do
     echo "$msgs" | jq -c '.[]' | while IFS= read -r msg; do
       mid=$(printf '%s' "$msg" | jq -r '.id')
       claimable=$(printf '%s' "$msg" | jq -r '.claimable // false')
+      if [ "$(ar_message_matches_channels "$msg")" != "true" ]; then
+        continue
+      fi
 
       if [ "$claimable" = "true" ]; then
         claim_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
@@ -144,7 +153,7 @@ while true; do
         fi
       fi
 
-      printf '%s' "$msg" | jq -r 'if .type == "system" then "⚠ SYSTEM [msg:\(.id)]: \(.body)" else "[msg:\(.id)] \(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)" end'
+      printf '%s' "$msg" | jq -r '(.meta.pairId // empty) as $pair | (if $pair != "" then " [pair:\($pair)]" else "" end) as $pairText | if .type == "system" then "⚠ SYSTEM [msg:\(.id)]\($pairText): \(.body)" else "[msg:\(.id)]\($pairText) \(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)" end'
 
       curl -s -X PATCH "${RELAY_URL}/api/messages/${mid}" "${auth_header_args[@]}" \
         -H 'Content-Type: application/json' \

package/hooks/profile-lib.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+ar_csv_json() {
+  printf '%s' "$1" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0)) | reduce .[] as $x ([]; if index($x) then . else . + [$x] end)'
+}
+
+ar_profile_value() {
+  local key="$1"
+  printf '%s' "${AR_PROFILE_JSON:-{}}" | jq -r --arg key "$key" '.[$key] // empty | if type == "string" then gsub("^\\s+|\\s+$"; "") else empty end'
+}
+
+ar_profile_array() {
+  local key="$1"
+  printf '%s' "${AR_PROFILE_JSON:-{}}" | jq -c --arg key "$key" 'if (.[$key] | type) == "array" then .[$key] | map(select(type == "string") | gsub("^\\s+|\\s+$"; "") | select(length > 0)) | reduce .[] as $x ([]; if index($x) then . else . + [$x] end) else [] end'
+}
+
+ar_init_profile() {
+  local provider="$1"
+  local rig="$2"
+  local project="$3"
+  local profiles_file profile_meta extra_tags
+
+  AR_PROFILE_NAME="${AGENT_RELAY_PROFILE:-}"
+  profiles_file="${AGENT_RELAY_PROFILES_FILE:-${HOME:-}/.config/agent-relay/profiles.json}"
+  AR_PROFILE_JSON="{}"
+  if [ -n "$AR_PROFILE_NAME" ] && [ -f "$profiles_file" ]; then
+    AR_PROFILE_JSON=$(jq -c --arg name "$AR_PROFILE_NAME" '.[$name] // {}' "$profiles_file" 2>/dev/null || printf '{}')
+  fi
+
+  if [ -n "${AGENT_RELAY_CAPS:-}" ]; then
+    AR_CAPS_JSON=$(ar_csv_json "$AGENT_RELAY_CAPS")
+  else
+    AR_CAPS_JSON=$(ar_profile_array capabilities)
+    if [ "$AR_CAPS_JSON" = "[]" ]; then AR_CAPS_JSON='["chat"]'; fi
+  fi
+
+  if [ -n "${AGENT_RELAY_TAGS:-}" ]; then
+    extra_tags=$(ar_csv_json "$AGENT_RELAY_TAGS")
+  else
+    extra_tags=$(ar_profile_array tags)
+  fi
+  AR_TAGS_JSON=$(jq -n --arg provider "$provider" --arg rig "$rig" --arg project "$project" --argjson extra "$extra_tags" \
+    '[$provider, $rig, $project] + $extra | map(select(length > 0)) | reduce .[] as $x ([]; if index($x) then . else . + [$x] end)')
+
+  if [ -n "${AGENT_RELAY_CHANNELS:-}" ]; then
+    AR_CHANNELS_JSON=$(ar_csv_json "$AGENT_RELAY_CHANNELS")
+  else
+    AR_CHANNELS_JSON=$(ar_profile_array channels)
+  fi
+
+  AR_LABEL="${AGENT_RELAY_LABEL:-$(ar_profile_value label)}"
+  AR_APPROVAL="${AGENT_RELAY_APPROVAL:-$(ar_profile_value approval)}"
+  AR_APPROVAL="${AR_APPROVAL:-open}"
+  case "$AR_APPROVAL" in
+    open|guarded|read-only) ;;
+    *) AR_APPROVAL="open" ;;
+  esac
+  profile_meta=$(printf '%s' "$AR_PROFILE_JSON" | jq -c 'if (.meta | type) == "object" then .meta else {} end' 2>/dev/null || printf '{}')
+  AR_META_JSON=$(jq -n \
+    --arg cwd "${PWD:-}" \
+    --arg approval "$AR_APPROVAL" \
+    --arg profile "$AR_PROFILE_NAME" \
+    --argjson channels "$AR_CHANNELS_JSON" \
+    --argjson profileMeta "$profile_meta" \
+    '$profileMeta + {cwd: $cwd, approvalMode: $approval, channels: $channels} + (if $profile != "" then {profile: $profile} else {} end)')
+}
+
+ar_message_matches_channels() {
+  local msg="$1"
+  printf '%s' "$msg" | jq -r --argjson channels "${AR_CHANNELS_JSON:-[]}" \
+    '(.channel // "") as $ch | if (($channels | length) == 0) or ($ch == "") or (($channels | index($ch)) != null) then "true" else "false" end'
+}

package/hooks/relay-monitor.sh

@@ -6,6 +6,7 @@
 
 RELAY_URL="${AGENT_RELAY_URL:-http://localhost:4850}"
 script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+source "${script_dir}/profile-lib.sh"
 plugin_root="${CLAUDE_PLUGIN_ROOT:-$(cd "${script_dir}/.." && pwd)}"
 PLUGIN_VERSION=$(
   jq -r '.version // empty' "${plugin_root}/.claude-plugin/plugin.json" 2>/dev/null ||
@@ -30,6 +31,7 @@ elif [ -n "$CLAUDE_CONFIG_DIR" ]; then
 else
   rig="default"
 fi
+ar_init_profile "claude" "$rig" "$project"
 
 if command -v shasum >/dev/null 2>&1; then
   short_pid=$(printf '%s' "$PPID" | shasum -a 1 | head -c 6)
@@ -57,11 +59,6 @@ if [ -f "$instance_state" ]; then
 fi
 printf '%s\n' "$agent_id" > "$instance_state"
 
-# --- Register agent ---
-caps_csv="${AGENT_RELAY_CAPS:-chat}"
-caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
-approval="${AGENT_RELAY_APPROVAL:-open}"
-
 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 \
@@ -69,10 +66,11 @@ reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agen
     --arg name "$project ($rig @ $machine)" \
     --arg machine "$machine" \
     --arg rig "$rig" \
-    --argjson tags "$(jq -n --arg r "$rig" --arg p "$project" '[$r, $p]')" \
-    --argjson caps "$caps_json" \
-    --argjson meta "$(jq -n --arg cwd "$PWD" --arg approval "$approval" '{cwd: $cwd, approvalMode: $approval}')" \
-    '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta}'
+    --arg label "$AR_LABEL" \
+    --argjson tags "$AR_TAGS_JSON" \
+    --argjson caps "$AR_CAPS_JSON" \
+    --argjson meta "$AR_META_JSON" \
+    '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta} + (if $label != "" then {label: $label} else {} end)'
   )" 2>/dev/null)
 
 if [ "$reg_code" != "201" ] && [ "$reg_code" != "200" ]; then
@@ -92,7 +90,7 @@ fi
 
 # --- Output context (first stdout = notification injected into conversation) ---
 approval_note=""
-case "$approval" in
+case "$AR_APPROVAL" in
   guarded) approval_note=" — destructive ops (rm, mv, chmod, kill, force-push) are blocked" ;;
   read-only) approval_note=" — observe/analyze/report only, no file writes or mutation commands" ;;
 esac
@@ -100,7 +98,10 @@ esac
 cat <<CONTEXT
 Agent Relay active. Your agent ID: ${agent_id}
 Relay URL: ${RELAY_URL} | Server: ${server_version:-unknown} | Plugin: ${PLUGIN_VERSION}
-Approval mode: ${approval}${approval_note}
+Profile: ${AR_PROFILE_NAME:-none} | Label: ${AR_LABEL:-none}
+Tags: $(printf '%s' "$AR_TAGS_JSON" | jq -r 'join(", ")') | Capabilities: $(printf '%s' "$AR_CAPS_JSON" | jq -r 'join(", ")')
+Channels: $(printf '%s' "$AR_CHANNELS_JSON" | jq -r 'if length == 0 then "all" else join(", ") end')
+Approval mode: ${AR_APPROVAL}${approval_note}
 
 To send a 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"}'
@@ -141,6 +142,22 @@ To find agents by capability:
 To list online agents:
   curl -s${auth_header_example} '${RELAY_URL}/api/agents?status=online'
 
+To pair with one available agent for focused two-party live collaboration:
+  If the user types "/pair codex", "/pair status", "/pair send PAIR_ID MESSAGE", "/disconnect", "/status", "/label LABEL", or "/tags TAGS", run the matching agent-relay CLI command.
+  agent-relay /pair codex "WORK TO SOLVE TOGETHER"
+  agent-relay /pair status
+  agent-relay /pair send PAIR_ID "MESSAGE"
+  agent-relay /disconnect
+  agent-relay /status
+  agent-relay /label backend-fixer
+  agent-relay /tags backend tests urgent
+  If the CLI is unavailable, use the API directly:
+  curl -s -X POST ${RELAY_URL}/api/pairs${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","target":"codex","objective":"WORK TO SOLVE TOGETHER"}'
+  Accept an incoming pair invite: curl -s -X POST ${RELAY_URL}/api/pairs/PAIR_ID/accept${auth_header_example} -H 'Content-Type: application/json' -d '{"agentId":"${agent_id}"}'
+  Send pair chat: curl -s -X POST ${RELAY_URL}/api/pairs/PAIR_ID/messages${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","body":"MESSAGE"}'
+  Hang up: curl -s -X POST ${RELAY_URL}/api/pairs/PAIR_ID/hangup${auth_header_example} -H 'Content-Type: application/json' -d '{"agentId":"${agent_id}"}'
+  Pairing is exclusive: one agent can have only one pending or active pair.
+
 System messages:
   Messages prefixed with "⚠ SYSTEM" are relay-level instructions (e.g. plugin updates, restart requests).
   When you see one, follow the instruction immediately — for example, restart the inbox monitor if asked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-plugin",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "description": "Claude Code plugin for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -17,7 +17,8 @@
   "files": [
     ".claude-plugin/",
     "hooks/",
-    "monitors/"
+    "monitors/",
+    "skills/"
   ],
   "keywords": [
     "claude-code",

package/skills/disconnect/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: disconnect
+description: End the current Agent Relay pair session. Use when the user invokes /disconnect or asks to hang up, unpair, or disconnect from a paired agent.
+argument-hint: "[PAIR_ID]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Disconnect
+
+Run:
+
+```bash
+agent-relay /disconnect $ARGUMENTS
+```
+
+If no pair id is supplied, the CLI ends the active pair for this session. Report the result briefly.

package/skills/label/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: label
+description: Read, set, or clear the current Agent Relay agent label. Use when the user invokes /label or asks to rename this relay agent.
+argument-hint: "[LABEL|--clear]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Label
+
+Run:
+
+```bash
+agent-relay /label $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /label backend-fixer
+agent-relay /label --clear
+```
+
+Report the new label or current label briefly.

package/skills/message/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: message
+description: Send a normal Agent Relay message to another agent, label, tag, capability, or broadcast target. Use when the user invokes /message or asks to send a one-off relay message.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Message
+
+Run:
+
+```bash
+agent-relay /message $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /message codex "Can you look at that failing action?"
+agent-relay /message tag:backend "Does anyone see the regression?"
+agent-relay /message broadcast "Standup in five minutes"
+```
+
+Report the sent message id briefly.

package/skills/pair/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: pair
+description: Start, inspect, accept, reject, or send messages in an Agent Relay two-agent pair session. Use when the user invokes /pair or asks to pair this agent with Codex, Claude, or another relay agent.
+argument-hint: "<target|status|accept|reject|send> [args]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Pair
+
+Run the Agent Relay CLI with the user's arguments:
+
+```bash
+agent-relay /pair $ARGUMENTS
+```
+
+Use this for pair-session commands such as:
+
+```bash
+agent-relay /pair codex "Debug flaky tests"
+agent-relay /pair status
+agent-relay /pair accept PAIR_ID
+agent-relay /pair reject PAIR_ID
+agent-relay /pair send PAIR_ID "What do you see?"
+```
+
+Report the command output briefly. If the CLI cannot detect this session's agent id, rerun with `--agent AGENT_ID` or `--from AGENT_ID` using the Agent Relay ID shown in session context.

package/skills/send-claimable/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: send-claimable
+description: Send a claimable Agent Relay work item so one matching agent can claim and handle it. Use when the user invokes /send-claimable or wants to enqueue work for another agent.
+argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Send Claimable
+
+Run:
+
+```bash
+agent-relay /send-claimable $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /send-claimable codex "Claim this and inspect the failing action"
+agent-relay /send-claimable tag:backend "Fix the failing API test"
+agent-relay /send-claimable cap:review "Review the migration patch"
+```
+
+Report the sent claimable message id briefly.

package/skills/status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: status
+description: Show Agent Relay status for this session, including relay health, current agent id, label, tags, readiness, and active pair state. Use when the user invokes /status or asks for relay connection status.
+argument-hint: "[--json]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Status
+
+Run:
+
+```bash
+agent-relay /status $ARGUMENTS
+```
+
+Summarize the current relay connection, agent identity, label, tags, and active pair state.

package/skills/tags/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: tags
+description: List or update Agent Relay tags for the current session. Use when the user invokes /tags or asks to set, add, remove, or inspect relay tags.
+argument-hint: "[TAG ...|--list|--add TAGS|--remove TAGS]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Tags
+
+Run:
+
+```bash
+agent-relay /tags $ARGUMENTS
+```
+
+Examples:
+
+```bash
+agent-relay /tags
+agent-relay /tags backend tests urgent
+agent-relay /tags --add backend,tests
+agent-relay /tags --remove urgent
+```
+
+Report the resulting tags briefly.