agent-relay-server 0.123.1 → 0.123.2

package/README.md

@@ -477,7 +477,9 @@ client/                              # TypeScript client (npm: agent-relay-clien
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and
-[SECURITY.md](SECURITY.md) for vulnerability reporting.
+[SECURITY.md](SECURITY.md) for vulnerability reporting. Before a feature counts as
+shipped, work it through the [Feature Delivery Guide](docs/feature-delivery.md) — the
+end-to-end Definition of Done that stops assembly-correct-but-dead features.
 
 ```bash
 git clone https://github.com/edimuj/agent-relay.git

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.123.1",
+    "version": "0.123.2",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.123.1",
+  "version": "0.123.2",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -28,6 +28,7 @@
     "scripts/orchestrator-spawn-smoke.ts",
     "runner/src/**/*.ts",
     "runner/plugins/**",
+    "runner/hooks/**",
     "!runner/**/*.test.ts",
     "public/**",
     "docs/openapi.json",
@@ -36,7 +37,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-channels-host": "0.123.1",
+    "agent-relay-channels-host": "0.123.2",
     "agent-relay-providers": "0.104.4",
     "agent-relay-sdk": "0.2.115",
     "ajv": "^8.20.0"

package/runner/hooks/rg-r-guard/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${HOOK_DIR}/rg-r-guard.cjs\"",
+            "timeout": 5,
+            "statusMessage": "Checking ripgrep replace guard",
+            "suppressOutput": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/runner/hooks/rg-r-guard/rg-r-guard.cjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+"use strict";
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+});
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(input || "{}");
+  } catch {
+    return;
+  }
+
+  const toolName = String(payload.tool_name || payload.toolName || "").toLowerCase();
+  const command = String(payload.tool_input?.command || payload.toolInput?.command || "");
+  if (toolName !== "bash" || !command || !containsRipgrepReplaceFootgun(command)) return;
+
+  const reason = "Blocked: `rg -r` is ripgrep replace, not recursive search. Use `rg PATTERN PATH` for search, or `rg --replace REPLACEMENT PATTERN` only when replacement output is intentional.";
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }));
+  process.stdout.write("\n");
+});
+
+function containsRipgrepReplaceFootgun(command) {
+  for (const segment of splitShellSegments(command)) {
+    const words = shellWords(segment);
+    for (let i = 0; i < words.length; i += 1) {
+      const word = basename(words[i] || "");
+      if (word !== "rg" && word !== "ripgrep") continue;
+      if (ripgrepArgsUseReplace(words.slice(i + 1))) return true;
+    }
+  }
+  return false;
+}
+
+function ripgrepArgsUseReplace(args) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] || "";
+    if (arg === "--") return false;
+    if (arg === "--replace" || arg.startsWith("--replace=")) return true;
+    if (arg === "-r") return true;
+    if (/^-([A-Za-z]*r[A-Za-z]*|[A-Za-z]*r=.+)$/.test(arg)) return true;
+  }
+  return false;
+}
+
+function splitShellSegments(text) {
+  const segments = [];
+  let current = "";
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      current += ch;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    // Command-substitution + grouping boundaries (`$(rg -r …)`, backtick `` `rg -r …` ``,
+    // subshells) split into their own segments so the inner command is scanned on its own
+    // (basename of `$(rg` ≠ rg otherwise) and its args never bleed into the outer command's
+    // scan. Only fires OUTSIDE quotes — a single/double-quoted literal is left intact, matching
+    // the tokenizer's existing quote handling. Known gap: substitution inside double quotes
+    // ("$(rg -r x)") is still treated as an opaque quoted word.
+    if (ch === "(" || ch === ")" || ch === "`") {
+      if (current.trim()) segments.push(current);
+      current = "";
+      continue;
+    }
+    if (ch === ";" || ch === "|" || ch === "&" || ch === "\n") {
+      if (current.trim()) segments.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) segments.push(current);
+  return segments;
+}
+
+function shellWords(text) {
+  const words = [];
+  let current = "";
+  let quote = "";
+  let escaped = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = "";
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current) {
+        words.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (current) words.push(current);
+  return words;
+}
+
+function basename(value) {
+  return value.split("/").pop() || value;
+}

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

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.123.1",
+  "version": "0.123.2",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/services/spawn-chain-inspector.ts

@@ -0,0 +1,134 @@
+// Real-chain spawn inspector (#1103 L1 seed) — the regression harness whose absence let two
+// dead #1096 fixes ship. It drives the ACTUAL spawn chain for a named profile, end to end, with
+// NO hand-fed config objects:
+//
+//   getAgentProfile(name)            — the real built-in/stored profile
+//   → withResolvedProvisioning       — relay-side registry resolution (needs a seeded DB)
+//   → buildSpawnCommand              — the command params the orchestrator dispatches
+//   → JSON round-trip                — the command-bus / AGENT_RELAY_AGENT_PROFILE_JSON env seam
+//   → spawnOptionsFromControl        — orchestrator re-parse of the command
+//   → ClaudeAdapter.buildSpawnArgs   — runner assembly + hook/skill/plugin MATERIALIZATION to disk
+//
+// then reads back the EFFECTIVE on-disk artifacts: the written managed `settings.json`, the
+// materialized `relay-provisioned-hooks/` tree, and the assembled argv. Two prior fixes each
+// tested one half in isolation (relay resolution OR runner materialization) with a hand-fed
+// `provisioning.hooks`, so neither caught that the bundled hook asset is never SHIPPED (the
+// `runner/hooks/**` packaging gap) and so never seeds → resolves empty on a real deployed spawn.
+// This helper runs the whole chain against the real DB + real package layout, so that class of
+// break surfaces as a red on-disk artifact instead of a green half-test.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SpawnProvider } from "agent-relay-sdk";
+import { withResolvedProvisioning } from "../db";
+import { getAgentProfile } from "../config-store";
+import { buildSpawnCommand } from "../spawn-command";
+import { spawnOptionsFromControl } from "../../orchestrator/src/control";
+import { ClaudeAdapter } from "../../runner/src/adapters/claude";
+import { defaultProviderConfig } from "../../runner/src/config";
+import type { RunnerSpawnConfig } from "../../runner/src/adapter";
+
+/** The bundled baseline safety hook whose silent absence is the #1096 bug. */
+export const BASELINE_HOOK_REF = "agent-relay-rg-r-guard";
+export const BASELINE_HOOK_SCRIPT = "rg-r-guard.cjs";
+
+export interface SpawnChainInspection {
+  profile: string;
+  provider: SpawnProvider;
+  /** The isolated managed CLAUDE_CONFIG_DIR the runner assembled + materialized into. */
+  configHome: string | undefined;
+  /** Absolute path of the managed settings.json (whether or not it exists). */
+  settingsPath: string | undefined;
+  /** Parsed on-disk settings.json (null when relay wrote none). */
+  settings: Record<string, unknown> | null;
+  /** The effective launch argv the adapter would exec. */
+  argv: string[];
+  /** The launch command (claude / claude-rig). */
+  command: string;
+  /** relay-provisioned-hooks/<ref> dir for the baseline guard. */
+  baselineHookAssetDir: string | undefined;
+  baselineHookAssetExists: boolean;
+  baselineHookScriptExists: boolean;
+  /** True iff the WRITTEN settings.json (the documented, transit-safe hook source) carries the
+   *  baseline PreToolUse guard — the #1096 proof-of-life bar. */
+  settingsHasBaselineHook: boolean;
+  /** True iff SOME launch channel (written settings.json OR inline --settings) carries it. */
+  launchHasBaselineHook: boolean;
+}
+
+function settingsCarriesBaselineHook(settings: Record<string, unknown> | null): boolean {
+  const pre = (settings?.hooks as { PreToolUse?: unknown } | undefined)?.PreToolUse;
+  if (!Array.isArray(pre)) return false;
+  return JSON.stringify(pre).includes(BASELINE_HOOK_SCRIPT);
+}
+
+function argvCarriesBaselineHook(argv: string[]): boolean {
+  const idx = argv.findIndex((a) => a === "--settings");
+  if (idx < 0 || idx + 1 >= argv.length) return false;
+  return argv[idx + 1]!.includes(BASELINE_HOOK_SCRIPT);
+}
+
+/**
+ * Run the real spawn chain for a profile and read back the on-disk artifacts. Two preconditions,
+ * both owned by the caller so this stays a pure harness (no global/env mutation of its own):
+ *   • the DB is seeded (initDb) so registry resolution can find the bundled hook, and
+ *   • AGENT_RELAY_PROVIDER_HOME_ROOT points at a scratch dir (the runner's config module reads it
+ *     to place isolated provider homes) — set it like launch-assembly.test.ts does.
+ */
+export function inspectSpawnChain(opts: {
+  profile: string;
+  provider: SpawnProvider;
+  cwd: string;
+  approvalMode?: string;
+}): SpawnChainInspection {
+  const { profile, provider, cwd } = opts;
+
+  // 1. RELAY: resolve the named profile's provisioning against the registry.
+  const resolved = withResolvedProvisioning(getAgentProfile(profile)?.value, provider);
+  if (!resolved) throw new Error(`profile not found: ${profile}`);
+
+  // 2. RELAY: build the spawn command params the orchestrator dispatches.
+  const cmdParams = buildSpawnCommand({
+    provider, cwd, agentProfile: resolved, env: {}, requestedBy: "spawn-chain-inspector",
+  } as Parameters<typeof buildSpawnCommand>[0]);
+
+  // 3. SEAM: JSON round-trip through the command bus / AGENT_RELAY_AGENT_PROFILE_JSON env var.
+  const roundTripped = JSON.parse(JSON.stringify(cmdParams)) as Record<string, unknown>;
+
+  // 4. ORCHESTRATOR: re-parse the command into spawn options.
+  const spawnOpts = spawnOptionsFromControl(roundTripped, { providers: [provider], baseDir: cwd } as never);
+
+  // 5. RUNNER: assemble the RunnerSpawnConfig the adapter consumes.
+  const providerConfig = defaultProviderConfig(provider);
+  const config = {
+    provider, runnerId: "inspector", instanceId: `insp-${profile}`, agentId: "insp",
+    relayUrl: "http://localhost:4850", cwd, headless: true,
+    approvalMode: opts.approvalMode ?? "open", providerArgs: [], providerConfig,
+    env: {}, controlPort: 4900,
+    agentProfile: spawnOpts.agentProfile,
+  } as unknown as RunnerSpawnConfig;
+
+  // 6. RUNNER: the REAL adapter path — prepares the home, materializes provisioned assets to
+  //    disk, and returns the launch argv (exactly what the runner execs).
+  const spawnArgs = new ClaudeAdapter().buildSpawnArgs(config, providerConfig);
+
+  // 7. Read back the effective on-disk artifacts.
+  const configHome = spawnArgs.env.CLAUDE_CONFIG_DIR;
+  const settingsPath = configHome ? join(configHome, "settings.json") : undefined;
+  const settings = settingsPath && existsSync(settingsPath)
+    ? (JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>)
+    : null;
+  const baselineHookAssetDir = configHome
+    ? join(configHome, "relay-provisioned-hooks", BASELINE_HOOK_REF)
+    : undefined;
+
+  return {
+    profile, provider, configHome, settingsPath, settings,
+    argv: spawnArgs.args, command: spawnArgs.command,
+    baselineHookAssetDir,
+    baselineHookAssetExists: Boolean(baselineHookAssetDir && existsSync(baselineHookAssetDir)),
+    baselineHookScriptExists: Boolean(baselineHookAssetDir && existsSync(join(baselineHookAssetDir, BASELINE_HOOK_SCRIPT))),
+    settingsHasBaselineHook: settingsCarriesBaselineHook(settings),
+    launchHasBaselineHook: settingsCarriesBaselineHook(settings) || argvCarriesBaselineHook(spawnArgs.args),
+  };
+}