agent-relay 3.0.2 → 3.1.1

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.2",
+  "version": "3.1.1",
   "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.2",
+  "version": "3.1.1",
   "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.2"
+    "@agent-relay/config": "3.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "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.2"
+    "@agent-relay/utils": "3.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "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.2",
+    "@agent-relay/config": "3.1.1",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {

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\""
-        }
-      ]
-    }
-  ]
-}

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

@@ -1,50 +0,0 @@
-{
-  "id": "traj_1771891934534_06504121",
-  "version": 1,
-  "task": {
-    "title": "default run #0a780183",
-    "source": {
-      "system": "workflow-runner",
-      "id": "0a780183edfa9ba0236202fe"
-    }
-  },
-  "status": "active",
-  "startedAt": "2026-02-24T00:12:14.534Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-24T00:12:14.534Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-24T00:12:19.066Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_1558a41b",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-24T00:12:14.534Z",
-      "events": [
-        {
-          "ts": 1771891934534,
-          "type": "note",
-          "content": "Workflow \"default\" started with 2 steps"
-        },
-        {
-          "ts": 1771891934534,
-          "type": "note",
-          "content": "Parsed 2 steps, 1 dependent steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771891939066,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        }
-      ]
-    }
-  ]
-}

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

@@ -1,50 +0,0 @@
-{
-  "id": "traj_1771891957929_211afc4e",
-  "version": 1,
-  "task": {
-    "title": "default run #e0eb8bb0",
-    "source": {
-      "system": "workflow-runner",
-      "id": "e0eb8bb09b4f17b228b7b97c"
-    }
-  },
-  "status": "active",
-  "startedAt": "2026-02-24T00:12:37.929Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-24T00:12:37.929Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-24T00:12:41.616Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_ab277099",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-24T00:12:37.929Z",
-      "events": [
-        {
-          "ts": 1771891957929,
-          "type": "note",
-          "content": "Workflow \"default\" started with 2 steps"
-        },
-        {
-          "ts": 1771891957929,
-          "type": "note",
-          "content": "Parsed 2 steps, 1 dependent steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771891961616,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        }
-      ]
-    }
-  ]
-}

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

@@ -1,50 +0,0 @@
-{
-  "id": "traj_1771891982509_38c84638",
-  "version": 1,
-  "task": {
-    "title": "default run #1fe87646",
-    "source": {
-      "system": "workflow-runner",
-      "id": "1fe87646b1d24cb6ee8c31b9"
-    }
-  },
-  "status": "active",
-  "startedAt": "2026-02-24T00:13:02.509Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-24T00:13:02.509Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-24T00:13:05.944Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_8bc7d236",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-24T00:13:02.509Z",
-      "events": [
-        {
-          "ts": 1771891982509,
-          "type": "note",
-          "content": "Workflow \"default\" started with 2 steps"
-        },
-        {
-          "ts": 1771891982509,
-          "type": "note",
-          "content": "Parsed 2 steps, 1 dependent steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771891985944,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        }
-      ]
-    }
-  ]
-}

package/packages/sdk/.trajectories/completed/traj_1771875803188_cd6d181c.json

@@ -1,80 +0,0 @@
-{
-  "id": "traj_1771875803188_cd6d181c",
-  "version": 1,
-  "task": {
-    "title": "default run #f1ef6db7",
-    "source": {
-      "system": "workflow-runner",
-      "id": "f1ef6db787ae83da31837011"
-    }
-  },
-  "status": "completed",
-  "startedAt": "2026-02-23T19:43:23.188Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-23T19:43:23.188Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-23T19:43:23.194Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_aa683478",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-23T19:43:23.188Z",
-      "events": [
-        {
-          "ts": 1771875803189,
-          "type": "note",
-          "content": "Workflow \"default\" started with 1 steps"
-        },
-        {
-          "ts": 1771875803189,
-          "type": "note",
-          "content": "Parsed 1 steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771875803194,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        },
-        {
-          "ts": 1771875803200,
-          "type": "finding",
-          "content": "Step \"step-1\" completed: Agent exited (exited)",
-          "significance": "medium"
-        }
-      ],
-      "endedAt": "2026-02-23T19:43:23.201Z"
-    },
-    {
-      "id": "ch_ea90fb42",
-      "title": "Retrospective",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-23T19:43:23.202Z",
-      "events": [
-        {
-          "ts": 1771875803202,
-          "type": "reflection",
-          "content": "Workflow completed in 0 seconds. 1/1 steps passed. (completed in 0 seconds)",
-          "significance": "high"
-        }
-      ],
-      "endedAt": "2026-02-23T19:43:23.202Z"
-    }
-  ],
-  "completedAt": "2026-02-23T19:43:23.202Z",
-  "retrospective": {
-    "summary": "Workflow completed in 0 seconds. 1/1 steps passed.",
-    "approach": "workflow-runner DAG execution",
-    "confidence": 0.75,
-    "learnings": [],
-    "challenges": []
-  }
-}

package/packages/sdk/.trajectories/completed/traj_1771875803204_f2aeb8c8.json

@@ -1,80 +0,0 @@
-{
-  "id": "traj_1771875803204_f2aeb8c8",
-  "version": 1,
-  "task": {
-    "title": "default run #8dcb0f8f",
-    "source": {
-      "system": "workflow-runner",
-      "id": "8dcb0f8f3997ff66b1441525"
-    }
-  },
-  "status": "completed",
-  "startedAt": "2026-02-23T19:43:23.204Z",
-  "agents": [
-    {
-      "name": "orchestrator",
-      "role": "workflow-runner",
-      "joinedAt": "2026-02-23T19:43:23.204Z"
-    },
-    {
-      "name": "agent-a",
-      "role": "agent-a",
-      "joinedAt": "2026-02-23T19:43:23.205Z"
-    }
-  ],
-  "chapters": [
-    {
-      "id": "ch_4ec95d3b",
-      "title": "Planning",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-23T19:43:23.204Z",
-      "events": [
-        {
-          "ts": 1771875803204,
-          "type": "note",
-          "content": "Workflow \"default\" started with 1 steps"
-        },
-        {
-          "ts": 1771875803204,
-          "type": "note",
-          "content": "Parsed 1 steps, DAG validated, no cycles"
-        },
-        {
-          "ts": 1771875803205,
-          "type": "note",
-          "content": "Step \"step-1\" assigned to agent \"agent-a\""
-        },
-        {
-          "ts": 1771875803206,
-          "type": "finding",
-          "content": "Step \"step-1\" completed: Agent exited (exited)",
-          "significance": "medium"
-        }
-      ],
-      "endedAt": "2026-02-23T19:43:23.207Z"
-    },
-    {
-      "id": "ch_fb0ea95b",
-      "title": "Retrospective",
-      "agentName": "orchestrator",
-      "startedAt": "2026-02-23T19:43:23.207Z",
-      "events": [
-        {
-          "ts": 1771875803207,
-          "type": "reflection",
-          "content": "Workflow completed in 0 seconds. 1/1 steps passed. (completed in 0 seconds)",
-          "significance": "high"
-        }
-      ],
-      "endedAt": "2026-02-23T19:43:23.207Z"
-    }
-  ],
-  "completedAt": "2026-02-23T19:43:23.207Z",
-  "retrospective": {
-    "summary": "Workflow completed in 0 seconds. 1/1 steps passed.",
-    "approach": "workflow-runner DAG execution",
-    "confidence": 0.75,
-    "learnings": [],
-    "challenges": []
-  }
-}