agent-relay-server 0.99.1 → 0.101.0

package/runner/plugins/claude/hooks/kill-guard.sh

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+# Shared "fleet fratricide" kill-pattern guard (issue #753).
+#
+# Every managed agent's runner runs as
+#   bun run .../agent-relay-runner/src/index.ts <provider> ...
+# so a broad process kill such as `pkill -f "src/index.ts"` (or `pkill bun`,
+# `killall node`, ...) matches EVERY sibling agent host-wide and silently SIGTERMs
+# the whole fleet. This is the structural guard so that can't happen again.
+#
+# It blocks broad process-kill commands (pkill / killall, and `kill` with a
+# pattern that leaks a fleet token) whose target would match sibling runners,
+# while still allowing the safe shapes: PID-scoped kills (kill 12345,
+# kill "$SERVER_PID") and pkill -f on a token that is unique to the caller's own
+# throwaway server (its exact test port, or "$PWD/public").
+#
+# DUAL MODE:
+#   - sourced: defines fratricide_deny_reason() / fratricide_raw_reason() plus the
+#     shell-parsing helpers (trim_shell_text / split_segments / shell_words). The
+#     Claude PreToolUse Bash guard sources this and is wired to it.
+#   - executed: `kill-guard.sh "<command text>"` prints the guidance + exits 0 when
+#     the command is a dangerous broad kill, and exits 1 (silent) when it is safe.
+#     This lets non-bash callers reuse the SAME matcher as a subprocess.
+#
+# TODO(#753 follow-up): wire the Codex runner/exec layer to invoke this guard.
+# Codex managed agents have no Claude PreToolUse hook, so the same broad pkill can
+# still fratricide the fleet from a Codex session until that wiring lands. The
+# matcher is intentionally factored here so the Codex side can call it directly
+# (e.g. `bash kill-guard.sh "$command"`) without duplicating the pattern list.
+
+shopt -s extglob
+
+# Guidance returned on a block — tells the caller how to clean up safely instead.
+FRATRICIDE_PATTERN_GUIDANCE='Blocked a broad process-kill (#753 fleet-fratricide guard): this pattern would match sibling agents'\'' runners, because every managed agent runs "bun run .../agent-relay-runner/src/index.ts". Kill only a PID you own — capture it when you spawn the server (SERVER_PID=$!; kill "$SERVER_PID") — or pkill -f a token that is unique to your own process (your exact test port, or "$PWD/public"). Never pkill/killall on bun, node, src/index.ts, agent-relay, or agent-relay-runner.'
+
+trim_shell_text() {
+  local value="$1"
+  value="${value##+([[:space:]])}"
+  value="${value%%+([[:space:]])}"
+  printf '%s' "$value"
+}
+
+split_segments() {
+  local text="$1"
+  local current="" i len ch next quote="" escaped=0
+  SEGMENTS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      current+="$ch"
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      current+="$ch"
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      fi
+      continue
+    fi
+
+    case "$ch" in
+      "'"|'"')
+        quote="$ch"
+        current+="$ch"
+        ;;
+      "\\")
+        escaped=1
+        current+="$ch"
+        ;;
+      $'\n'|";")
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "&")
+        next="${text:i+1:1}"
+        if [ "$next" = "&" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "|")
+        next="${text:i+1:1}"
+        if [ "$next" = "|" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      *)
+        current+="$ch"
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  SEGMENTS+=("$current")
+  return 0
+}
+
+shell_words() {
+  local text="$1"
+  local word="" i len ch quote="" escaped=0 in_word=0
+  WORDS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      word+="$ch"
+      in_word=1
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      else
+        word+="$ch"
+      fi
+      in_word=1
+      continue
+    fi
+
+    case "$ch" in
+      [[:space:]])
+        if (( in_word )); then
+          WORDS+=("$word")
+          word=""
+          in_word=0
+        fi
+        ;;
+      "'"|'"')
+        quote="$ch"
+        in_word=1
+        ;;
+      "\\")
+        escaped=1
+        in_word=1
+        ;;
+      *)
+        word+="$ch"
+        in_word=1
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  if (( in_word )); then
+    WORDS+=("$word")
+  fi
+  return 0
+}
+
+# True (0) when text mentions a process-kill verb (pkill / killall / kill).
+_looks_like_kill() {
+  if [[ "${1,,}" =~ (^|[^a-z])(pkill|killall|kill)([^a-z]|$) ]]; then
+    return 0
+  fi
+  return 1
+}
+
+# True (0) when a kill pattern/token would match sibling runners across the fleet.
+# Matches the runner path tokens, and the bare interpreter process names bun/node
+# even when wrapped in pgrep/regex metacharacters such as [b]un, ^node$, bun.* .
+_pattern_hits_fleet() {
+  local lower="${1,,}"
+  case "$lower" in
+    *index.ts*|*agent-relay*)
+      return 0
+      ;;
+  esac
+  local cleaned="$lower" mc
+  for mc in '[' ']' '(' ')' '{' '}' '^' '$' '*' '+' '?' '\' '|'; do
+    cleaned="${cleaned//"$mc"/}"
+  done
+  if [[ "$cleaned" =~ (^|[^a-z0-9])(bun|node)([^a-z0-9]|$) ]]; then
+    return 0
+  fi
+  return 1
+}
+
+# Inspect one shell segment. Prints guidance + returns 0 when it is a dangerous
+# broad kill; returns 1 when the segment is safe or not a kill.
+_fratricide_segment_reason() {
+  local raw="$1" segment base i=0 j arg
+  segment="$(trim_shell_text "$raw")"
+  if [ -z "$segment" ]; then
+    return 1
+  fi
+  if ! shell_words "$segment"; then
+    # Unparseable — only worry if it both looks like a kill and leaks a fleet token.
+    if _looks_like_kill "$segment" && _pattern_hits_fleet "$segment"; then
+      printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+      return 0
+    fi
+    return 1
+  fi
+  if (( ${#WORDS[@]} == 0 )); then
+    return 1
+  fi
+
+  # Skip any leading VAR=value assignments (e.g. SERVER_PID=$!; kill ...).
+  while (( i < ${#WORDS[@]} )) && [[ "${WORDS[i]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do
+    ((i += 1))
+  done
+  if (( i >= ${#WORDS[@]} )); then
+    return 1
+  fi
+
+  base="${WORDS[i]##*/}"
+  base="${base,,}"
+  case "$base" in
+    pkill|killall)
+      # Pattern-matching kills: block if ANY non-flag operand hits the fleet.
+      j=$((i + 1))
+      while (( j < ${#WORDS[@]} )); do
+        arg="${WORDS[j]}"
+        if [[ "$arg" == -* ]]; then
+          ((j += 1))
+          continue
+        fi
+        if _pattern_hits_fleet "$arg"; then
+          printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+          return 0
+        fi
+        ((j += 1))
+      done
+      return 1
+      ;;
+    kill)
+      # PID-scoped kills (kill 123, kill "$PID", kill -9 %1) are safe. Block only
+      # when an operand leaks a fleet token — e.g. kill $(pgrep -f src/index.ts).
+      j=$((i + 1))
+      while (( j < ${#WORDS[@]} )); do
+        arg="${WORDS[j]}"
+        if _pattern_hits_fleet "$arg"; then
+          printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+          return 0
+        fi
+        ((j += 1))
+      done
+      return 1
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+# Structured matcher: split a full command into segments and check each one.
+# Prints guidance + returns 0 on the first dangerous broad kill; returns 1 if safe.
+fratricide_deny_reason() {
+  local text="$1" segment reason
+  if ! split_segments "$text"; then
+    fratricide_raw_reason "$text"
+    return $?
+  fi
+  local -a segments=("${SEGMENTS[@]}")
+  for segment in "${segments[@]}"; do
+    if reason="$(_fratricide_segment_reason "$segment")"; then
+      printf '%s' "$reason"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Coarse raw-text fallback for when structured parsing is unavailable (no jq, or
+# unparseable shell). Prints guidance + returns 0 only when the text both looks
+# like a kill and leaks a fleet token.
+fratricide_raw_reason() {
+  local text="$1"
+  if _looks_like_kill "$text" && _pattern_hits_fleet "$text"; then
+    printf '%s' "$FRATRICIDE_PATTERN_GUIDANCE"
+    return 0
+  fi
+  return 1
+}
+
+# Executed directly (not sourced): argv[1] is the command text to inspect.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  if reason="$(fratricide_deny_reason "${1:-}")"; then
+    printf '%s\n' "$reason"
+    exit 0
+  fi
+  exit 1
+fi

package/runner/plugins/claude/hooks/read-only-bash-guard.sh

@@ -4,8 +4,12 @@
 # Real boundaries are Relay token scope, unavailable write tools, and future
 # OS-level enforcement.
 set -euo pipefail
-source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+HOOK_DIR="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks"
+source "${HOOK_DIR}/relay-status.sh"
 relay_install_hook_guard read-only-bash-guard
+# Shared fleet-fratricide kill-pattern matcher (#753): trim_shell_text,
+# split_segments, shell_words and fratricide_deny_reason live here.
+source "${HOOK_DIR}/kill-guard.sh"
 
 payload="$(cat)"
 
@@ -15,6 +19,38 @@ emit_deny() {
     "$(relay_json_escape "$reason")"
 }
 
+shopt -s extglob
+
+# Extract the Bash command once. jq is strongly preferred; both the fleet-kill
+# guard (all modes) and the read-only allow-list (read-only mode) consume it.
+jq_available=0
+tool_name=""
+command_text=""
+if command -v jq >/dev/null 2>&1; then
+  jq_available=1
+  tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+  command_text="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+fi
+
+# --- Fleet-fratricide guard: ACTIVE IN ALL APPROVAL MODES (#753) ---
+# A broad pkill/killall/kill can SIGTERM every sibling agent's runner host-wide,
+# so this block runs before (and independent of) the read-only allow-list.
+if (( jq_available )); then
+  if [ "${tool_name,,}" = "bash" ] && [ -n "$command_text" ]; then
+    if fratricide_reason="$(fratricide_deny_reason "$command_text")"; then
+      emit_deny "$fratricide_reason"
+      exit 0
+    fi
+  fi
+else
+  # No jq: best-effort raw scan so the fleet guard still bites the obvious cases.
+  if fratricide_reason="$(fratricide_raw_reason "$payload")"; then
+    emit_deny "$fratricide_reason"
+    exit 0
+  fi
+fi
+
+# --- Read-only allow-list: only the read-only approval mode below this point ---
 case "${AGENT_RELAY_APPROVAL:-}" in
   open|guarded)
     exit 0
@@ -27,40 +63,27 @@ case "${AGENT_RELAY_APPROVAL:-}" in
     ;;
 esac
 
-if ! command -v jq >/dev/null 2>&1; then
+if (( ! jq_available )); then
   emit_deny "Read-only Bash guard could not inspect the command because jq is unavailable."
   exit 0
 fi
 
-tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
 if [ "${tool_name,,}" != "bash" ]; then
   exit 0
 fi
 
-command_text="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
 if [ -z "$command_text" ]; then
   emit_deny "Read-only Bash guard denied an empty Bash command."
   exit 0
 fi
 
-shopt -s extglob
-
 DENY_REASON=""
-SEGMENTS=()
-WORDS=()
 
 deny_segment() {
   DENY_REASON="$1"
   return 1
 }
 
-trim_shell_text() {
-  local value="$1"
-  value="${value##+([[:space:]])}"
-  value="${value%%+([[:space:]])}"
-  printf '%s' "$value"
-}
-
 hard_deny_reason() {
   local text="$1"
   case "$text" in
@@ -117,131 +140,6 @@ hard_deny_reason() {
   return 1
 }
 
-split_segments() {
-  local text="$1"
-  local current="" i len ch next quote="" escaped=0
-  SEGMENTS=()
-  len=${#text}
-  for ((i = 0; i < len; i++)); do
-    ch="${text:i:1}"
-    if (( escaped )); then
-      current+="$ch"
-      escaped=0
-      continue
-    fi
-    if [ -n "$quote" ]; then
-      current+="$ch"
-      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
-        escaped=1
-        continue
-      fi
-      if [ "$ch" = "$quote" ]; then
-        quote=""
-      fi
-      continue
-    fi
-
-    case "$ch" in
-      "'"|'"')
-        quote="$ch"
-        current+="$ch"
-        ;;
-      "\\")
-        escaped=1
-        current+="$ch"
-        ;;
-      $'\n'|";")
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      "&")
-        next="${text:i+1:1}"
-        if [ "$next" = "&" ]; then
-          ((i += 1))
-        fi
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      "|")
-        next="${text:i+1:1}"
-        if [ "$next" = "|" ]; then
-          ((i += 1))
-        fi
-        SEGMENTS+=("$current")
-        current=""
-        ;;
-      *)
-        current+="$ch"
-        ;;
-    esac
-  done
-
-  if [ -n "$quote" ] || (( escaped )); then
-    return 1
-  fi
-  SEGMENTS+=("$current")
-  return 0
-}
-
-shell_words() {
-  local text="$1"
-  local word="" i len ch quote="" escaped=0 in_word=0
-  WORDS=()
-  len=${#text}
-  for ((i = 0; i < len; i++)); do
-    ch="${text:i:1}"
-    if (( escaped )); then
-      word+="$ch"
-      in_word=1
-      escaped=0
-      continue
-    fi
-    if [ -n "$quote" ]; then
-      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
-        escaped=1
-        continue
-      fi
-      if [ "$ch" = "$quote" ]; then
-        quote=""
-      else
-        word+="$ch"
-      fi
-      in_word=1
-      continue
-    fi
-
-    case "$ch" in
-      [[:space:]])
-        if (( in_word )); then
-          WORDS+=("$word")
-          word=""
-          in_word=0
-        fi
-        ;;
-      "'"|'"')
-        quote="$ch"
-        in_word=1
-        ;;
-      "\\")
-        escaped=1
-        in_word=1
-        ;;
-      *)
-        word+="$ch"
-        in_word=1
-        ;;
-    esac
-  done
-
-  if [ -n "$quote" ] || (( escaped )); then
-    return 1
-  fi
-  if (( in_word )); then
-    WORDS+=("$word")
-  fi
-  return 0
-}
-
 validate_git_branch() {
   local i="$1" arg
   while (( i < ${#WORDS[@]} )); do

package/runner/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
@@ -30,7 +30,7 @@ export interface ProviderStatusEvent {
   // runner reconciles them against actual liveness and clears the busy marker if
   // every pid is dead — recovering from a tracked process killed out-of-band.
   pids?: number[];
-  providerState?: Record<string, unknown>;
+  providerState?: ProviderState;
   metadata?: Record<string, unknown>;
 }
 

package/src/agent-death-diagnosis.ts

@@ -6,7 +6,6 @@
 // deterministic and unit-testable per failure mode. The output rides the #633 terminal event and
 // is persisted as a CrashReport so the WHY survives the reaper.
 
-import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
 import type { AgentCard, AgentDeathCause, AgentDeathDiagnosis, CrashReport, ManagedSessionExitDiagnostics } from "./types";
 
 export interface DeathEvidence {
@@ -87,6 +86,16 @@ function haystack(ev: DeathEvidence): string {
   return parts.join("\n");
 }
 
+function terminalModelUnavailableMessage(meta: Record<string, unknown> | undefined): string | undefined {
+  const terminalReason = str(meta?.terminalFailureReason);
+  const terminalMessage = str(meta?.terminalFailureMessage);
+  if (terminalReason === "model-unavailable" && terminalMessage) return terminalMessage;
+  const providerState = record(meta, "providerState");
+  const stateReason = str(providerState?.reason);
+  const stateMessage = str(providerState?.message);
+  return stateReason === "model-unavailable" && stateMessage ? stateMessage : undefined;
+}
+
 function logTailOf(ev: DeathEvidence): string[] | undefined {
   if (ev.exit?.logTail?.length) return ev.exit.logTail;
   const lastExit = record(ev.agentMeta, "lastExit");
@@ -159,8 +168,8 @@ export function classifyAgentDeath(ev: DeathEvidence): AgentDeathDiagnosis {
     return verdict("onboarding-gate", fast ? "high" : "medium", "Stuck at a first-run onboarding/trust gate");
   }
 
-  // 4) provider-crash — CLI panic/segfault/model-unavailable, or a crash signal.
-  const modelUnavailable = extractClaudeModelUnavailableMessage(text);
+  // 4) provider-crash — CLI panic/segfault/adapter-classified model-unavailable, or a crash signal.
+  const modelUnavailable = terminalModelUnavailableMessage(ev.agentMeta);
   if (modelUnavailable) {
     pushUnique(evidence, modelUnavailable);
     return verdict("provider-crash", "high", "Provider unavailable (model/CLI error)");

package/src/bus.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import { ValidationError, createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
+import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
 import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
@@ -11,6 +11,7 @@ import { registerAgent } from "./services/register-agent";
 import { authContextFromBus } from "./services/auth-context";
 import { commandAuthorizationResource, dispatchCommand } from "./services/dispatch-command";
 import { auditProviderStateTransition } from "./services/provider-state-audit";
+import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider-timeline-event";
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
@@ -28,7 +29,7 @@ import {
   type BusFrame,
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
-import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
+import { errMessage, isRecord } from "agent-relay-sdk";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { Command, ComponentToken, ContextState, Message, ProviderCapabilities, QuotaState, RegisterAgentInput, Task } from "./types";
 
@@ -189,10 +190,11 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         }
         const after = getAgent(conn.agentId);
         auditProviderStateTransition(conn.agentId, before, after);
-        auditRunnerTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
+        const timelineEvent = agentProviderTimelineEvent(after);
+        auditRunnerTimelineEvent(conn.agentId, timelineEvent);
         // A real PreCompact/SessionStart hook arrives as a timelineEvent in the
         // merged meta — clears any pending stall watch (stale events ignored).
-        noteAgentTimelineEvent(conn.agentId, after?.meta?.timelineEvent);
+        noteAgentTimelineEvent(conn.agentId, timelineEvent);
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
@@ -568,47 +570,6 @@ function emitAgentStatusEvent(agentId: string): void {
   });
 }
 
-function auditRunnerTimelineEvent(agentId: string, timelineEvent: unknown): void {
-  if (!isRecord(timelineEvent)) return;
-  const metadata = isRecord(timelineEvent.metadata) ? timelineEvent.metadata : {};
-  if (metadata.source !== "runner") return;
-  const status = stringValue(timelineEvent.status);
-  if (!status) return;
-  const eventType = stringValue(metadata.eventType) ?? status;
-  const timestamp = numberValue(timelineEvent.timestamp) ?? Date.now();
-  const id = stringValue(timelineEvent.id) ?? `${eventType}-${timestamp}`;
-  const title = stringValue(timelineEvent.title) ?? status.replace(/[._-]+/g, " ");
-  const body = stringValue(timelineEvent.body);
-  const icon = stringValue(timelineEvent.icon) ?? "ti-activity";
-  try {
-    const event = createActivityEvent({
-      clientId: `runner-timeline-${agentId}-${id}`,
-      kind: "state",
-      title,
-      body,
-      meta: agentId,
-      icon,
-      view: "agents",
-      agentId,
-      metadata: {
-        ...metadata,
-        eventType,
-        timelineStatus: status,
-        timelineId: id,
-        timelineTimestamp: timestamp,
-      },
-    });
-    emitRelayEvent({
-      type: "activity.created",
-      source: "server",
-      subject: String(event.id),
-      data: event as unknown as Record<string, unknown>,
-    });
-  } catch {
-    // Timeline writes must never block bus status updates.
-  }
-}
-
 function sendCommandResult(
   ws: BusWebSocket,
   commandId: string,