agent-relay-runner 0.10.19 → 0.10.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.10.19",
+  "version": "0.10.20",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.0"
+    "agent-relay-sdk": "0.2.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,5 +1,8 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.10.19"
+  "version": "0.10.20",
+  "agentRelayContracts": {
+    "providerPluginProtocol": 1
+  }
 }

package/plugins/claude/hooks/hooks.json

@@ -0,0 +1,114 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/permission-request.sh\"",
+            "timeout": 900
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/stop-failure.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/post-compact.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/claude/hooks/permission-request.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+port="${AGENT_RELAY_RUNNER_PORT:-}"
+if [[ -z "$port" ]]; then
+  exit 0
+fi
+
+payload="$(cat)"
+response="$(
+  printf '%s' "$payload" | curl -fsS \
+    --max-time 900 \
+    -H 'Content-Type: application/json' \
+    --data-binary @- \
+    "http://127.0.0.1:${port}/permissions/request" 2>/dev/null || true
+)"
+
+if [[ -n "$response" ]]; then
+  printf '%s\n' "$response"
+fi

package/plugins/claude/hooks/post-compact.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+relay_post_timeline_status idle provider-turn "" compacted

package/plugins/claude/hooks/pre-compact.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+relay_post_timeline_status busy provider-turn "" compacting

package/plugins/claude/hooks/relay-status.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+
+relay_post_status() {
+  local status="${1:-}"
+  local reason="${2:-}"
+  local id="${3:-}"
+  local label="${4:-}"
+  local role="${5:-}"
+  local parent_id="${6:-}"
+  local clear_kind="${7:-}"
+  local timeline_status="${8:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  [ -z "$status" ] && return 0
+  local body="{\"status\":\"$(relay_json_escape "$status")\""
+  [ -n "${AGENT_RELAY_PROVIDER_SESSION_ID:-}" ] && body="${body},\"providerSessionId\":\"$(relay_json_escape "$AGENT_RELAY_PROVIDER_SESSION_ID")\""
+  [ -n "$reason" ] && body="${body},\"reason\":\"$(relay_json_escape "$reason")\""
+  [ -n "$clear_kind" ] && body="${body},\"clear\":[\"$(relay_json_escape "$clear_kind")\"]"
+  [ -n "$timeline_status" ] && body="${body},\"timeline\":{\"status\":\"$(relay_json_escape "$timeline_status")\"}"
+  [ -n "$id" ] && body="${body},\"id\":\"$(relay_json_escape "$id")\""
+  [ -n "$label" ] && body="${body},\"label\":\"$(relay_json_escape "$label")\""
+  [ -n "$role" ] && body="${body},\"role\":\"$(relay_json_escape "$role")\""
+  [ -n "$parent_id" ] && body="${body},\"parentId\":\"$(relay_json_escape "$parent_id")\""
+  body="${body}}"
+  curl -fsS -X POST "http://127.0.0.1:${port}/status" \
+    -H 'Content-Type: application/json' \
+    -d "$body" >/dev/null || true
+}
+
+relay_post_status_clearing_subagents() {
+  relay_post_status "$1" "${2:-}" "${3:-}" "${4:-}" "${5:-}" "${6:-}" subagent
+}
+
+relay_post_timeline_status() {
+  relay_post_status "$1" "${2:-provider-turn}" "" "" "" "" "${3:-}" "$4"
+}
+
+relay_pending_reply_stop_decision() {
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local response
+  response="$(curl -fsS "http://127.0.0.1:${port}/reply-obligations/claude-stop" 2>/dev/null || true)"
+  case "$response" in
+    *'"decision":"block"'*|*'"decision": "block"'*) ;;
+    *) return 0 ;;
+  esac
+  printf '%s' "$response"
+}
+
+relay_json_string_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' | head -1
+}
+
+relay_json_bool_field() {
+  local field="${1:-}"
+  local input="${2:-}"
+  [ -z "$field" ] && return 0
+  printf '%s' "$input" | sed -nE 's/.*"'"$field"'"[[:space:]]*:[[:space:]]*(true|false).*/\1/p' | head -1
+}
+
+relay_json_escape() {
+  printf '%s' "${1:-}" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}

package/plugins/claude/hooks/session-end.sh

@@ -1,5 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
-port="${AGENT_RELAY_RUNNER_PORT:-}"
-[ -z "$port" ] && exit 0
-curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"offline"}' >/dev/null || true
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+reason="$(relay_json_string_field reason "$payload")"
+
+case "$reason" in
+  clear)
+    relay_post_timeline_status idle provider-turn subagent clearing-context
+    ;;
+  resume)
+    relay_post_status_clearing_subagents idle
+    ;;
+  logout|prompt_input_exit|bypass_permissions_disabled|other|*)
+    relay_post_status_clearing_subagents offline
+    ;;
+esac

package/plugins/claude/hooks/session-start.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+source_kind="$(relay_json_string_field source "$payload")"
+
+case "$source_kind" in
+  clear)
+    relay_post_timeline_status idle provider-turn subagent context-cleared
+    ;;
+  *)
+    ;;
+esac

package/plugins/claude/hooks/stop-failure.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+error="$(relay_json_string_field error "$payload")"
+
+case "$error" in
+  authentication_failed|oauth_org_not_allowed|billing_error|model_not_found)
+    relay_post_status_clearing_subagents error
+    ;;
+  *)
+    relay_post_status_clearing_subagents idle
+    ;;
+esac

package/plugins/claude/hooks/stop.sh

@@ -1,5 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
-port="${AGENT_RELAY_RUNNER_PORT:-}"
-[ -z "$port" ] && exit 0
-curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"idle"}' >/dev/null || true
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+stop_hook_active="$(relay_json_bool_field stop_hook_active "$payload")"
+if [ "$stop_hook_active" != "true" ]; then
+  stop_decision="$(relay_pending_reply_stop_decision)"
+  if [ -n "$stop_decision" ]; then
+    printf '%s\n' "$stop_decision"
+    exit 0
+  fi
+fi
+
+relay_post_status_clearing_subagents idle

package/plugins/claude/hooks/subagent-start.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# shellcheck source=/dev/null
+source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+agent_id="$(relay_json_string_field agent_id "$payload")"
+agent_type="$(relay_json_string_field agent_type "$payload")"
+
+relay_post_status busy subagent "${agent_id:-subagent}" "$agent_type" "$agent_type"

package/plugins/claude/hooks/subagent-stop.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+# shellcheck source=/dev/null
+source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+
+payload="$(cat || true)"
+agent_id="$(relay_json_string_field agent_id "$payload")"
+agent_type="$(relay_json_string_field agent_type "$payload")"
+
+relay_post_status idle subagent "${agent_id:-subagent}" "$agent_type" "$agent_type"

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
 set -euo pipefail
-port="${AGENT_RELAY_RUNNER_PORT:-}"
-[ -z "$port" ] && exit 0
-curl -fsS -X POST "http://127.0.0.1:${port}/status" -H 'Content-Type: application/json' -d '{"status":"busy"}' >/dev/null || true
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_post_status busy

package/plugins/claude/monitors/relay-monitor.ts

@@ -1,16 +1,28 @@
+import type { Message } from "agent-relay-sdk";
+import { claudeProviderMessageText } from "../../../src/adapters/claude-delivery";
+import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT } from "../../../src/relay-instructions";
+
 const port = process.env.AGENT_RELAY_RUNNER_PORT;
 if (!port) process.exit(0);
 
+let firstDelivery = true;
+let deliveryCount = 0;
 const ws = new WebSocket(`ws://127.0.0.1:${port}/monitor`);
 
 ws.onmessage = (event) => {
   const payload = parsePayload(String(event.data));
   if (!payload || payload.type !== "message.deliver" || !Array.isArray(payload.messages)) return;
-  const messages = payload.messages as Array<{ id: number; from: string; subject?: string; body: string }>;
-  for (const message of messages) {
-    const subject = message.subject ? `\nSubject: ${message.subject}` : "";
-    console.log(`Relay message #${message.id} from ${message.from}${subject}\n${message.body}`);
+  const messages = payload.messages as Message[];
+  deliveryCount += 1;
+  if (firstDelivery) {
+    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    console.log("");
+    firstDelivery = false;
   }
+  console.log(claudeProviderMessageText(messages, {
+    deliveryCount,
+    readOnly: process.env.AGENT_RELAY_APPROVAL === "read-only",
+  }));
   ws.send(JSON.stringify({
     type: "message.delivered",
     deliveryId: typeof payload.deliveryId === "string" ? payload.deliveryId : "",

package/plugins/claude/skills/react/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: react
+description: Add or remove an Agent Relay reaction on a message. Use for lightweight acknowledgement, approval, thanks, or good-job responses when no text reply is needed.
+argument-hint: "<messageId> <emoji> [--remove]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay React
+
+Run:
+
+```bash
+agent-relay /react $ARGUMENTS
+```
+
+Use reactions instead of text when the message only needs lightweight acknowledgement, approval, thanks, or "good job".
+
+Do not use reactions when the sender asked a question, gave a new task, reported a bug, or needs a result in text.

package/plugins/claude/skills/read-message/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: read-message
+description: Fetch a full Agent Relay message by ID, including full body, attachments, metadata, and thread context. Use when a delivered Relay preview is truncated or when the user asks to inspect a relay message.
+argument-hint: "<messageId> [--json|--body]"
+allowed-tools: [Bash]
+---
+
+# Agent Relay Read Message
+
+Run:
+
+```bash
+agent-relay get-message $ARGUMENTS
+```
+
+Useful forms:
+
+```bash
+agent-relay get-message 206
+agent-relay get-message 206 --json
+agent-relay get-message 206 --body
+```
+
+Use `--body` when you only need the complete message text. Use `--json` when attachments, metadata, or thread context matter.

package/plugins/claude/skills/reply/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: reply
-description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context — no target needed. Use when the user invokes /reply or asks to reply to a specific relay message.
-argument-hint: "<messageId> <message>"
+description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context — no target needed. Use when the user invokes /reply or asks to reply to a specific relay message, especially with stdin/file for long replies.
+argument-hint: "<messageId> <message|--stdin|--body-file PATH>"
 allowed-tools: [Bash]
 ---
 
@@ -20,6 +20,10 @@ Examples:
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
 agent-relay /reply 42 "Done — the fix is in commit abc123"
+agent-relay /reply 42 --stdin < response.md
+agent-relay /reply 42 --body-file response.md
 ```
 
-Report the sent message id and resolved target briefly.
+Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
+
+Do not send a separate Relay follow-up that only confirms the reply was sent. The CLI output is enough local confirmation.

package/plugins/codex/skills/guide/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: guide
+description: Show the Agent Relay command guide for coding agents. Use when the user invokes /guide or asks how to use Agent Relay messaging, replies, pair sessions, labels, tags, targets, or claimable work.
+argument-hint: ""
+---
+
+# Agent Relay Guide
+
+Run:
+
+```bash
+agent-relay /guide
+```
+
+Use this before guessing Relay commands. The guide explains reply, message, pair, status, label, tag, target, and claimable-work commands.

package/plugins/codex/skills/react/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: react
+description: Add or remove an Agent Relay reaction on a message. Use for lightweight acknowledgement, approval, thanks, or good-job responses when no text reply is needed.
+argument-hint: "<messageId> <emoji> [--remove]"
+---
+
+# Agent Relay React
+
+Run:
+
+```bash
+agent-relay /react $ARGUMENTS
+```
+
+Use reactions instead of text when the message only needs lightweight acknowledgement, approval, thanks, or "good job".
+
+Do not use reactions when the sender asked a question, gave a new task, reported a bug, or needs a result in text.

package/plugins/codex/skills/read-message/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: read-message
+description: Fetch a full Agent Relay message by ID, including full body, attachments, metadata, and thread context. Use when a delivered Relay preview is truncated or when the user asks to inspect a relay message.
+argument-hint: "<messageId> [--json|--body]"
+---
+
+# Agent Relay Read Message
+
+Run:
+
+```bash
+agent-relay get-message $ARGUMENTS
+```
+
+Useful forms:
+
+```bash
+agent-relay get-message 206
+agent-relay get-message 206 --json
+agent-relay get-message 206 --body
+```
+
+Use `--body` when you only need the complete message text. Use `--json` when attachments, metadata, or thread context matter.

package/plugins/codex/skills/reply/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: reply
-description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context, so no target is needed. Use when the user invokes /reply or asks to reply to a specific relay message.
-argument-hint: "<messageId> <message>"
+description: Reply to an Agent Relay message by ID. Auto-routes to the sender and inherits channel context, so no target is needed. Use when the user invokes /reply or asks to reply to a specific relay message, especially with stdin/file for long replies.
+argument-hint: "<messageId> <message|--stdin|--body-file PATH>"
 ---
 
 # Agent Relay Reply
@@ -19,6 +19,10 @@ Examples:
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
 agent-relay /reply 42 "Done; the fix is in commit abc123"
+agent-relay /reply 42 --stdin < response.md
+agent-relay /reply 42 --body-file response.md
 ```
 
+Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
+
 Report the sent message id and resolved target briefly.