agent-relay 3.0.1 → 3.1.0

package/packages/sdk-py/tests/test_relay_lifecycle_hooks.py

@@ -0,0 +1,250 @@
+"""Tests for spawn/release lifecycle hooks in the high-level relay facade."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+
+from agent_relay import AgentRelay, SpawnOptions
+
+
+class _FakeRelayClient:
+    def __init__(self) -> None:
+        self.spawn_error: Exception | None = None
+        self.release_error: Exception | None = None
+        self.spawn_calls: list[dict] = []
+        self.release_calls: list[tuple[str, str | None]] = []
+
+    async def spawn_pty(self, **kwargs):
+        self.spawn_calls.append(kwargs)
+        if self.spawn_error:
+            raise self.spawn_error
+        return {"name": kwargs["name"], "runtime": "pty"}
+
+    async def release(self, name: str, reason: str | None = None):
+        self.release_calls.append((name, reason))
+        if self.release_error:
+            raise self.release_error
+        return {"name": name}
+
+
+@pytest.mark.asyncio
+async def test_spawn_lifecycle_hooks_success():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    events: list[tuple[str, dict]] = []
+    options = SpawnOptions(
+        channels=["general"],
+        on_start=lambda ctx: events.append(("start", dict(ctx))),
+        on_success=lambda ctx: events.append(("success", dict(ctx))),
+        on_error=lambda ctx: events.append(("error", dict(ctx))),
+    )
+
+    agent = await relay.spawn("HookWorker", "claude", "Do the work", options)
+
+    assert agent.name == "HookWorker"
+    assert events[0] == (
+        "start",
+        {
+            "name": "HookWorker",
+            "cli": "claude",
+            "channels": ["general"],
+            "task": "Do the work",
+        },
+    )
+    assert events[1] == (
+        "success",
+        {
+            "name": "HookWorker",
+            "cli": "claude",
+            "channels": ["general"],
+            "task": "Do the work",
+            "runtime": "pty",
+        },
+    )
+    assert len(events) == 2
+
+
+@pytest.mark.asyncio
+async def test_spawn_lifecycle_hooks_support_async_callbacks():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    start_done = False
+    success_done = False
+
+    async def on_start(_ctx):
+        nonlocal start_done
+        await asyncio.sleep(0)
+        start_done = True
+
+    async def on_success(_ctx):
+        nonlocal success_done
+        await asyncio.sleep(0)
+        success_done = True
+
+    options = SpawnOptions(
+        channels=["general"],
+        on_start=on_start,
+        on_success=on_success,
+    )
+
+    await relay.spawn("AsyncHookWorker", "claude", "Do the work", options)
+
+    assert start_done is True
+    assert success_done is True
+
+
+@pytest.mark.asyncio
+async def test_spawn_lifecycle_hooks_error():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    client.spawn_error = RuntimeError("spawn failed")
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    on_error_calls: list[dict] = []
+    options = SpawnOptions(
+        channels=["general"],
+        on_start=lambda _: None,
+        on_error=lambda ctx: on_error_calls.append(dict(ctx)),
+    )
+
+    with pytest.raises(RuntimeError, match="spawn failed"):
+        await relay.spawn("HookWorkerFail", "claude", "Do the work", options)
+
+    assert len(on_error_calls) == 1
+    error_ctx = on_error_calls[0]
+    assert error_ctx["name"] == "HookWorkerFail"
+    assert error_ctx["cli"] == "claude"
+    assert isinstance(error_ctx["error"], RuntimeError)
+
+
+@pytest.mark.asyncio
+async def test_shorthand_spawn_lifecycle_hooks_success():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    events: list[str] = []
+    agent = await relay.claude.spawn(
+        name="ShorthandWorker",
+        channels=["general"],
+        task="Run analysis",
+        on_start=lambda _: events.append("start"),
+        on_success=lambda _: events.append("success"),
+        on_error=lambda _: events.append("error"),
+    )
+
+    assert agent.name == "ShorthandWorker"
+    assert events == ["start", "success"]
+
+
+@pytest.mark.asyncio
+async def test_shorthand_spawn_does_not_fire_start_hook_if_broker_startup_fails():
+    relay = AgentRelay()
+    relay._ensure_started = AsyncMock(side_effect=RuntimeError("broker startup failed"))
+
+    start_called = False
+    error_called = False
+
+    def _mark_called(kind: str) -> None:
+        nonlocal start_called, error_called
+        if kind == "start":
+            start_called = True
+        else:
+            error_called = True
+
+    with pytest.raises(RuntimeError, match="broker startup failed"):
+        await relay.claude.spawn(
+            name="ShorthandWorkerStartupFail",
+            channels=["general"],
+            on_start=lambda _ctx: _mark_called("start"),
+            on_error=lambda _ctx: _mark_called("error"),
+        )
+
+    assert start_called is False
+    assert error_called is False
+
+
+@pytest.mark.asyncio
+async def test_release_lifecycle_hooks_success_and_error():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    agent = await relay.spawn("ReleaseWorker", "claude")
+
+    success_events: list[str] = []
+    await agent.release(
+        "cleanup",
+        on_start=lambda _: success_events.append("start"),
+        on_success=lambda _: success_events.append("success"),
+        on_error=lambda _: success_events.append("error"),
+    )
+
+    assert client.release_calls[-1] == ("ReleaseWorker", "cleanup")
+    assert success_events == ["start", "success"]
+
+    client.release_error = RuntimeError("release failed")
+    error_calls: list[dict] = []
+    with pytest.raises(RuntimeError, match="release failed"):
+        await agent.release(
+            "cleanup-again",
+            on_error=lambda ctx: error_calls.append(dict(ctx)),
+        )
+
+    assert len(error_calls) == 1
+    assert error_calls[0]["name"] == "ReleaseWorker"
+    assert isinstance(error_calls[0]["error"], RuntimeError)
+
+
+@pytest.mark.asyncio
+async def test_release_lifecycle_hooks_support_async_callbacks():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    agent = await relay.spawn("ReleaseAsyncWorker", "claude")
+
+    success_done = False
+
+    async def on_success(_ctx):
+        nonlocal success_done
+        await asyncio.sleep(0)
+        success_done = True
+
+    await agent.release("cleanup", on_success=on_success)
+
+    assert success_done is True
+
+
+@pytest.mark.asyncio
+async def test_release_does_not_fire_hooks_if_broker_startup_fails():
+    relay = AgentRelay()
+    client = _FakeRelayClient()
+    relay._ensure_started = AsyncMock(return_value=client)
+    agent = await relay.spawn("ReleaseStartupFailWorker", "claude")
+
+    relay._ensure_started = AsyncMock(side_effect=RuntimeError("broker startup failed"))
+
+    start_called = False
+    error_called = False
+
+    def mark_start(_ctx):
+        nonlocal start_called
+        start_called = True
+
+    def mark_error(_ctx):
+        nonlocal error_called
+        error_called = True
+
+    with pytest.raises(RuntimeError, match="broker startup failed"):
+        await agent.release("cleanup", on_start=mark_start, on_error=mark_error)
+
+    assert start_called is False
+    assert error_called is False

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.0.1"
+    "@agent-relay/config": "3.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "3.0.1"
+    "@agent-relay/utils": "3.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "3.0.1",
+    "@agent-relay/config": "3.1.0",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {

package/scripts/postinstall.js

@@ -3,7 +3,7 @@
  * Postinstall Script for agent-relay
  *
  * This script runs after npm install to:
- * 1. Install relay-pty binary for current platform
+ * 1. Install agent-relay-broker binary for current platform
  * 2. Install dashboard dependencies
  * 3. Patch agent-trajectories CLI
  * 4. Check for tmux availability (fallback)
@@ -148,36 +148,6 @@ function ensureSqliteDriver() {
   return { ok: false, driver: 'none', statusPath, error: detail };
 }
 
-/**
- * Get the platform-specific binary name for relay-pty
- * Returns null if platform is not supported
- */
-function getRelayPtyBinaryName() {
-  const platform = os.platform();
-  const arch = os.arch();
-
-  // Map Node.js arch to Rust target arch
-  const archMap = {
-    'arm64': 'arm64',
-    'x64': 'x64',
-  };
-
-  // Map Node.js platform to Rust target platform
-  const platformMap = {
-    'darwin': 'darwin',
-    'linux': 'linux',
-  };
-
-  const targetPlatform = platformMap[platform];
-  const targetArch = archMap[arch];
-
-  if (!targetPlatform || !targetArch) {
-    return null;
-  }
-
-  return `relay-pty-${targetPlatform}-${targetArch}`;
-}
-
 /** Read the package version from package.json */
 function getPackageVersion(pkgRoot) {
   const packageJsonPath = path.join(pkgRoot, 'package.json');
@@ -198,7 +168,7 @@ function getPackageVersion(pkgRoot) {
  * Download a file via HTTPS, following redirects
  * Uses only built-in https module (no deps)
  */
-function downloadRelayPtyBinary(url, destPath, maxRedirects = 5) {
+function downloadBinary(url, destPath, maxRedirects = 5) {
   fs.mkdirSync(path.dirname(destPath), { recursive: true });
 
   const attemptDownload = (currentUrl, redirectsRemaining, resolve, reject) => {
@@ -210,7 +180,7 @@ function downloadRelayPtyBinary(url, destPath, maxRedirects = 5) {
       if (isRedirect) {
         if (redirectsRemaining <= 0) {
           res.resume();
-          reject(new Error('Too many redirects while downloading relay-pty binary'));
+          reject(new Error('Too many redirects while downloading binary'));
           return;
         }
 
@@ -280,83 +250,6 @@ function resignBinaryForMacOS(binaryPath) {
   }
 }
 
-/**
- * Install the relay-pty binary for the current platform
- */
-async function installRelayPtyBinary() {
-  const pkgRoot = getPackageRoot();
-  const binaryName = getRelayPtyBinaryName();
-
-  if (!binaryName) {
-    warn(`Unsupported platform: ${os.platform()}-${os.arch()}`);
-    warn('relay-pty binary not available, will fall back to tmux mode');
-    return false;
-  }
-
-  const sourcePath = path.join(pkgRoot, 'bin', binaryName);
-  const targetPath = path.join(pkgRoot, 'bin', 'relay-pty');
-
-  // Check if platform-specific binary exists (bundled install)
-  if (!fs.existsSync(sourcePath)) {
-    const version = getPackageVersion(pkgRoot);
-    if (!version) {
-      warn('relay-pty binary not available and package version unknown');
-      warn('Will fall back to tmux mode');
-      return false;
-    }
-
-    const downloadUrl = `https://github.com/AgentWorkforce/relay/releases/download/v${version}/${binaryName}`;
-    info(`relay-pty binary not bundled, downloading from ${downloadUrl} ...`);
-
-    try {
-      await downloadRelayPtyBinary(downloadUrl, sourcePath);
-      fs.chmodSync(sourcePath, 0o755);
-      success(`Downloaded relay-pty binary for ${os.platform()}-${os.arch()}`);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      warn(`Failed to download relay-pty binary: ${message}`);
-      warn('Will fall back to tmux mode');
-      return false;
-    }
-  }
-
-  // Check if already installed (and is a symlink or copy of correct binary)
-  if (fs.existsSync(targetPath)) {
-    try {
-      // Check if it's already the right binary by comparing size
-      const sourceStats = fs.statSync(sourcePath);
-      const targetStats = fs.statSync(targetPath);
-      if (sourceStats.size === targetStats.size) {
-        // Re-sign even if already installed to ensure signature is valid
-        // This fixes issues where previous installs have invalid signatures
-        resignBinaryForMacOS(targetPath);
-        info('relay-pty binary already installed');
-        return true;
-      }
-    } catch {
-      // Continue to reinstall
-    }
-  }
-
-  // Copy the binary (symlinks don't work well across npm install)
-  try {
-    fs.copyFileSync(sourcePath, targetPath);
-    fs.chmodSync(targetPath, 0o755);
-
-    // Re-sign the binary on macOS to prevent code signature validation failures
-    // Without this, macOS may SIGKILL the process immediately on execution
-    if (resignBinaryForMacOS(targetPath)) {
-      success(`Installed relay-pty binary for ${os.platform()}-${os.arch()}`);
-    } else {
-      warn(`Installed relay-pty binary but signing failed - may not work on macOS`);
-    }
-    return true;
-  } catch (err) {
-    warn(`Failed to install relay-pty binary: ${err.message}`);
-    return false;
-  }
-}
-
 /**
  * Get the platform-specific binary name for the broker binary.
  * The broker binary is the Rust-compiled broker (not the Bun-compiled CLI).
@@ -391,8 +284,9 @@ function getBrokerBinaryName() {
  *
  * Resolution order:
  *   1. Already bundled at packages/sdk/bin/agent-relay-broker (e.g. from prepack)
- *   2. Download platform-specific standalone binary from GitHub releases
- *   3. Fall back to the local Rust debug binary at target/debug/agent-relay-broker (dev only)
+ *   2. Platform-specific binary bundled in root bin/ (e.g. bin/agent-relay-broker-linux-x64)
+ *   3. Download platform-specific standalone binary from GitHub releases
+ *   4. Fall back to the local Rust debug binary at target/debug/agent-relay-broker (dev only)
  */
 async function installBrokerBinary() {
   const pkgRoot = getPackageRoot();
@@ -420,8 +314,25 @@ async function installBrokerBinary() {
 
   fs.mkdirSync(sdkBinDir, { recursive: true });
 
-  // 2. Try downloading from GitHub releases
   const binaryName = getBrokerBinaryName();
+
+  // 2. Check for bundled platform-specific binary in root bin/
+  if (binaryName) {
+    const bundledBinary = path.join(pkgRoot, 'bin', binaryName);
+    if (fs.existsSync(bundledBinary)) {
+      try {
+        fs.copyFileSync(bundledBinary, targetPath);
+        fs.chmodSync(targetPath, 0o755);
+        resignBinaryForMacOS(targetPath);
+        success(`Installed broker binary from bundled package (${binaryName})`);
+        return true;
+      } catch (err) {
+        warn(`Failed to copy bundled broker binary: ${err.message}`);
+      }
+    }
+  }
+
+  // 3. Try downloading from GitHub releases
   if (binaryName) {
     const version = getPackageVersion(pkgRoot);
     if (version) {
@@ -429,7 +340,7 @@ async function installBrokerBinary() {
       info(`Downloading broker binary from ${downloadUrl} ...`);
 
       try {
-        await downloadRelayPtyBinary(downloadUrl, targetPath);
+        await downloadBinary(downloadUrl, targetPath);
         fs.chmodSync(targetPath, 0o755);
         resignBinaryForMacOS(targetPath);
         success(`Downloaded broker binary for ${os.platform()}-${os.arch()}`);
@@ -441,7 +352,7 @@ async function installBrokerBinary() {
     }
   }
 
-  // 3. Dev fallback — check for local Rust build (release first, then debug)
+  // 4. Dev fallback — check for local Rust build (release first, then debug)
   for (const profile of ['release', 'debug']) {
     const localBinary = path.join(pkgRoot, 'target', profile, binaryFilename);
     if (fs.existsSync(localBinary)) {
@@ -462,18 +373,6 @@ async function installBrokerBinary() {
   return false;
 }
 
-/**
- * Check if tmux is available on the system
- */
-function hasSystemTmux() {
-  try {
-    execSync('which tmux', { stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Setup workspace package symlinks for global/bundled installs.
  *
@@ -683,7 +582,7 @@ function patchAgentTrajectories() {
   success('Patched agent-trajectories to record agent on trail start');
 }
 
-function logPostinstallDiagnostics(hasRelayPty, hasBrokerBinary, sqliteStatus, linkResult) {
+function logPostinstallDiagnostics(hasBrokerBinary, sqliteStatus, linkResult) {
   // Workspace packages status (for global installs)
   if (linkResult && linkResult.needed) {
     if (linkResult.success) {
@@ -693,16 +592,10 @@ function logPostinstallDiagnostics(hasRelayPty, hasBrokerBinary, sqliteStatus, l
     }
   }
 
-  if (hasRelayPty) {
-    console.log('✓ relay-pty binary installed');
-  } else {
-    console.log('⚠ relay-pty binary not installed - falling back to tmux mode if available');
-  }
-
   if (hasBrokerBinary) {
-    console.log('✓ broker binary installed (SDK programmatic usage ready)');
+    console.log('✓ agent-relay-broker binary installed');
   } else {
-    console.log('⚠ broker binary not installed - AgentRelay programmatic API will not work');
+    console.log('⚠ agent-relay-broker binary not installed - AgentRelay will not work');
   }
 
   if (sqliteStatus.ok && sqliteStatus.driver === 'better-sqlite3') {
@@ -734,10 +627,7 @@ async function main() {
     }
   }
 
-  // Install relay-pty binary for current platform (primary mode)
-  const hasRelayPty = await installRelayPtyBinary();
-
-  // Install broker binary for SDK programmatic usage (AgentRelay)
+  // Install broker binary for agent spawning and SDK programmatic usage
   const hasBrokerBinary = await installBrokerBinary();
 
   // Ensure SQLite driver is available (better-sqlite3 or node:sqlite)
@@ -750,30 +640,13 @@ async function main() {
   installDashboardDeps();
 
   // Always print diagnostics (even in CI)
-  logPostinstallDiagnostics(hasRelayPty, hasBrokerBinary, sqliteStatus, linkResult);
-
-  // Skip tmux check in CI environments
-  if (process.env.CI === 'true') {
-    return;
-  }
+  logPostinstallDiagnostics(hasBrokerBinary, sqliteStatus, linkResult);
 
-  // If relay-pty is installed, we're good
-  if (hasRelayPty) {
-    info('Using relay-pty for agent communication (fast mode)');
-    return;
+  if (!hasBrokerBinary) {
+    warn('agent-relay-broker binary not available');
+    info('Agent spawning will not work without the broker binary.');
+    info('To fix: cargo build --release --bin agent-relay-broker (requires Rust toolchain)');
   }
-
-  // Fall back to tmux check
-  if (hasSystemTmux()) {
-    info('System tmux found (fallback mode)');
-    return;
-  }
-
-  // Neither relay-pty nor tmux available
-  warn('Neither relay-pty nor tmux available');
-  info('Agent spawning will not work without one of:');
-  info('  1. relay-pty binary (included for darwin-arm64, darwin-x64, linux-x64)');
-  info('  2. tmux: brew install tmux (macOS) or apt install tmux (Linux)');
 }
 
 main().catch((err) => {

package/packages/sdk/.trajectories/active/traj_1771875803391_84ca57b2.json

@@ -1,50 +0,0 @@
-{
-  "id": "traj_1771875803391_84ca57b2",
-  "version": 1,
-  "task": {
-    "title": "default run #18889026",
-    "source": {
-      "system": "workflow-runner",
-      "id": "188890267c8264bd0f5a7422"
-    }
-  },
-  "status": "active",
-  "startedAt": "2026-02-23T19:43:23.391Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-23T19:43:23.391Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-23T19:43:28.180Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_ed619507",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-23T19:43:23.391Z",
-      "events": [
-        {
-          "ts": 1771875803391,
-          "type": "note",
-          "content": "Workflow \"default\" started with 2 steps"
-        },
-        {
-          "ts": 1771875803391,
-          "type": "note",
-          "content": "Parsed 2 steps, 1 dependent steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771875808180,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        }
-      ]
-    }
-  ]
-}