agent-relay 2.3.2 → 2.3.4

package/packages/sdk-ts/src/__tests__/unit.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Unit tests — no broker binary or RELAY_API_KEY required.
+ *
+ * Run:
+ *   npm run build && node --test dist/__tests__/unit.test.js
+ */
+import assert from "node:assert/strict";
+import { join, sep } from "node:path";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import test from "node:test";
+
+import { AgentRelay, type Agent } from "../relay.js";
+import { getLogs, listLoggedAgents } from "../logs.js";
+
+// ── waitForAny ──────────────────────────────────────────────────────────────
+
+function makeFakeAgent(
+  name: string,
+  exitAfterMs?: number,
+): Agent {
+  let resolveExit: ((reason: "exited" | "released") => void) | undefined;
+  const exitPromise = new Promise<"exited" | "released">((resolve) => {
+    resolveExit = resolve;
+  });
+
+  if (exitAfterMs !== undefined) {
+    setTimeout(() => resolveExit?.("exited"), exitAfterMs);
+  }
+
+  return {
+    name,
+    runtime: "pty",
+    channels: ["general"],
+    exitCode: undefined,
+    exitSignal: undefined,
+    async release() {
+      resolveExit?.("released");
+    },
+    waitForExit(timeoutMs?: number) {
+      if (timeoutMs === 0) return Promise.resolve("timeout" as const);
+      if (timeoutMs !== undefined) {
+        return Promise.race([
+          exitPromise,
+          new Promise<"timeout">((resolve) =>
+            setTimeout(() => resolve("timeout"), timeoutMs),
+          ),
+        ]);
+      }
+      return exitPromise;
+    },
+    async sendMessage() {
+      return { eventId: "fake", from: name, to: "", text: "" };
+    },
+  };
+}
+
+test("waitForAny: returns first agent to exit", async () => {
+  const fast = makeFakeAgent("fast", 50);
+  const slow = makeFakeAgent("slow", 5_000);
+
+  const { agent, result } = await AgentRelay.waitForAny([fast, slow], 3_000);
+  assert.equal(agent.name, "fast");
+  assert.equal(result, "exited");
+});
+
+test("waitForAny: returns timeout when no agent exits", async () => {
+  const a = makeFakeAgent("a");
+  const b = makeFakeAgent("b");
+
+  const { result } = await AgentRelay.waitForAny([a, b], 100);
+  assert.equal(result, "timeout");
+});
+
+test("waitForAny: handles released agent", async () => {
+  const agent = makeFakeAgent("releasable");
+
+  // Release after 50ms
+  setTimeout(() => agent.release(), 50);
+
+  const { agent: resolved, result } = await AgentRelay.waitForAny([agent], 3_000);
+  assert.equal(resolved.name, "releasable");
+  assert.equal(result, "released");
+});
+
+test("waitForAny: throws on empty agents array", async () => {
+  await assert.rejects(
+    () => AgentRelay.waitForAny([]),
+    { message: "waitForAny requires at least one agent" },
+  );
+});
+
+// ── getLogs ──────────────────────────────────────────────────────────────────
+
+test("getLogs: rejects path traversal", async () => {
+  const result = await getLogs("../../etc/passwd", {
+    logsDir: "/tmp/test-logs",
+  });
+  assert.equal(result.found, false);
+  assert.equal(result.content, "");
+});
+
+test("getLogs: returns not found for missing agent", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "relay-test-logs-"));
+
+  try {
+    const result = await getLogs("nonexistent", { logsDir: dir });
+    assert.equal(result.found, false);
+    assert.equal(result.content, "");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("getLogs: reads content from log file", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "relay-test-logs-"));
+
+  try {
+    const logContent = "line1\nline2\nline3\n";
+    await writeFile(join(dir, "TestAgent.log"), logContent);
+
+    const result = await getLogs("TestAgent", { logsDir: dir, lines: 2 });
+    assert.equal(result.found, true);
+    assert.equal(result.content, "line2\nline3");
+    assert.equal(result.lineCount, 2);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("listLoggedAgents: lists agent names from log files", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "relay-test-logs-"));
+
+  try {
+    await writeFile(join(dir, "Alice.log"), "hello\n");
+    await writeFile(join(dir, "Bob.log"), "world\n");
+    await writeFile(join(dir, "not-a-log.txt"), "skip\n");
+
+    const agents = await listLoggedAgents(dir);
+    assert.ok(agents.includes("Alice"));
+    assert.ok(agents.includes("Bob"));
+    assert.ok(!agents.includes("not-a-log"));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("listLoggedAgents: returns empty for missing directory", async () => {
+  const agents = await listLoggedAgents("/tmp/definitely-nonexistent-dir");
+  assert.deepEqual(agents, []);
+});
+

package/packages/sdk-ts/src/client.ts

@@ -34,12 +34,14 @@ export interface SpawnPtyInput {
   cli: string;
   args?: string[];
   channels?: string[];
+  task?: string;
 }
 
 export interface SpawnHeadlessClaudeInput {
   name: string;
   args?: string[];
   channels?: string[];
+  task?: string;
 }
 
 export interface SendMessageInput {
@@ -167,6 +169,7 @@ export class AgentRelayClient {
     };
     const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>("spawn_agent", {
       agent,
+      ...(input.task != null ? { initial_task: input.task } : {}),
     });
     return result;
   }
@@ -183,6 +186,7 @@ export class AgentRelayClient {
     };
     const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>("spawn_agent", {
       agent,
+      ...(input.task != null ? { initial_task: input.task } : {}),
     });
     return result;
   }

package/packages/sdk-ts/src/protocol.ts

@@ -34,7 +34,7 @@ export type SdkToBroker =
     }
   | {
       type: "spawn_agent";
-      payload: { agent: AgentSpec };
+      payload: { agent: AgentSpec; initial_task?: string };
     }
   | {
       type: "send_message";

package/packages/sdk-ts/src/relay.ts

@@ -34,6 +34,7 @@ import {
 } from "./client.js";
 import type { AgentRuntime, BrokerEvent, BrokerStatus } from "./protocol.js";
 import { RelaycastApi } from "./relaycast.js";
+import { getLogs as getLogsFromFile, listLoggedAgents as listLoggedAgentsFromFile, type LogsResult, type GetLogsOptions } from "./logs.js";
 
 function isUnsupportedOperation(error: unknown): error is AgentRelayProtocolError {
   return error instanceof AgentRelayProtocolError && error.code === "unsupported_operation";
@@ -66,6 +67,10 @@ export interface Agent {
   readonly name: string;
   readonly runtime: AgentRuntime;
   readonly channels: string[];
+  /** Set when the agent exits. Available after `onAgentExited` fires. */
+  exitCode?: number;
+  /** Set when the agent exits via signal. Available after `onAgentExited` fires. */
+  exitSignal?: string;
   release(): Promise<void>;
   /** Wait for the agent process to exit on its own.
    *  @param timeoutMs — optional timeout in ms. Resolves with `"timeout"` if exceeded,
@@ -94,6 +99,7 @@ export interface AgentSpawner {
     name?: string;
     args?: string[];
     channels?: string[];
+    task?: string;
   }): Promise<Agent>;
 }
 
@@ -119,6 +125,7 @@ export class AgentRelay {
   onAgentSpawned: EventHook<Agent> = null;
   onAgentReleased: EventHook<Agent> = null;
   onAgentExited: EventHook<Agent> = null;
+  onAgentReady: EventHook<Agent> = null;
   onWorkerOutput: EventHook<{ name: string; stream: string; chunk: string }> = null;
   onDeliveryUpdate: EventHook<BrokerEvent> = null;
 
@@ -133,7 +140,11 @@ export class AgentRelay {
   private startPromise?: Promise<AgentRelayClient>;
   private unsubEvent?: () => void;
   private readonly knownAgents = new Map<string, Agent>();
-  private readonly exitResolvers = new Map<string, (reason: "exited" | "released") => void>();
+  private readonly exitResolvers = new Map<
+    string,
+    { resolve: (reason: "exited" | "released") => void; token: number }
+  >();
+  private exitResolverSeq = 0;
   private readonly relaycastByName = new Map<string, RelaycastApi>();
 
   constructor(options: AgentRelayOptions = {}) {
@@ -164,6 +175,7 @@ export class AgentRelay {
       cli: input.cli,
       args: input.args,
       channels,
+      task: input.task,
     });
     const agent = this.makeAgent(result.name, result.runtime, channels);
     this.knownAgents.set(agent.name, agent);
@@ -211,6 +223,21 @@ export class AgentRelay {
     };
   }
 
+  // ── Messaging ─────────────────────────────────────────────────────────
+
+  /**
+   * Broadcast a message to all connected agents.
+   * @param text — the message body
+   * @param options — optional sender name (defaults to "human:orchestrator")
+   */
+  async broadcast(
+    text: string,
+    options?: { from?: string },
+  ): Promise<Message> {
+    const from = options?.from ?? "human:orchestrator";
+    return this.human({ name: from }).sendMessage({ to: "*", text });
+  }
+
   // ── Listing ─────────────────────────────────────────────────────────────
 
   async listAgents(): Promise<Agent[]> {
@@ -232,6 +259,57 @@ export class AgentRelay {
     return client.getStatus();
   }
 
+  // ── Logs ──────────────────────────────────────────────────────────────
+
+  /**
+   * Read the last N lines of an agent's log file.
+   *
+   * @example
+   * ```ts
+   * const logs = await relay.getLogs("Worker1", { lines: 100 });
+   * if (logs.found) console.log(logs.content);
+   * ```
+   */
+  async getLogs(agentName: string, options?: { lines?: number }): Promise<LogsResult> {
+    const cwd = this.clientOptions.cwd ?? process.cwd();
+    const logsDir = path.join(cwd, ".agent-relay", "worker-logs");
+    return getLogsFromFile(agentName, { logsDir, lines: options?.lines });
+  }
+
+  /** List all agents that have log files. */
+  async listLoggedAgents(): Promise<string[]> {
+    const cwd = this.clientOptions.cwd ?? process.cwd();
+    const logsDir = path.join(cwd, ".agent-relay", "worker-logs");
+    return listLoggedAgentsFromFile(logsDir);
+  }
+
+  // ── Wait helpers ──────────────────────────────────────────────────────
+
+  /**
+   * Wait for any one of the given agents to exit. Returns the first agent
+   * that exits along with its exit reason.
+   *
+   * @example
+   * ```ts
+   * const { agent, result } = await AgentRelay.waitForAny([worker1, worker2], 60_000);
+   * console.log(`${agent.name} finished: ${result}`);
+   * ```
+   */
+  static async waitForAny(
+    agents: Agent[],
+    timeoutMs?: number,
+  ): Promise<{ agent: Agent; result: "exited" | "timeout" | "released" }> {
+    if (agents.length === 0) {
+      throw new Error("waitForAny requires at least one agent");
+    }
+    return Promise.race(
+      agents.map(async (agent) => {
+        const result = await agent.waitForExit(timeoutMs);
+        return { agent, result };
+      }),
+    );
+  }
+
   // ── Lifecycle ───────────────────────────────────────────────────────────
 
   async shutdown(): Promise<void> {
@@ -244,8 +322,8 @@ export class AgentRelay {
       this.client = undefined;
     }
     this.knownAgents.clear();
-    for (const resolve of this.exitResolvers.values()) {
-      resolve("released");
+    for (const entry of this.exitResolvers.values()) {
+      entry.resolve("released");
     }
     this.exitResolvers.clear();
   }
@@ -323,7 +401,7 @@ export class AgentRelay {
             this.makeAgent(event.name, "pty", []);
           this.onAgentReleased?.(agent);
           this.knownAgents.delete(event.name);
-          this.exitResolvers.get(event.name)?.("released");
+          this.exitResolvers.get(event.name)?.resolve("released");
           this.exitResolvers.delete(event.name);
           break;
         }
@@ -331,12 +409,24 @@ export class AgentRelay {
           const agent =
             this.knownAgents.get(event.name) ??
             this.makeAgent(event.name, "pty", []);
+          // Populate exit info before firing the hook
+          (agent as { exitCode?: number }).exitCode = event.code;
+          (agent as { exitSignal?: string }).exitSignal = event.signal;
           this.onAgentExited?.(agent);
           this.knownAgents.delete(event.name);
-          this.exitResolvers.get(event.name)?.("exited");
+          this.exitResolvers.get(event.name)?.resolve("exited");
           this.exitResolvers.delete(event.name);
           break;
         }
+        case "worker_ready": {
+          let agent = this.knownAgents.get(event.name);
+          if (!agent) {
+            agent = this.makeAgent(event.name, event.runtime, []);
+            this.knownAgents.set(event.name, agent);
+          }
+          this.onAgentReady?.(agent);
+          break;
+        }
         case "worker_stream": {
           this.onWorkerOutput?.({
             name: event.name,
@@ -362,6 +452,8 @@ export class AgentRelay {
       name,
       runtime,
       channels,
+      exitCode: undefined,
+      exitSignal: undefined,
       async release() {
         const client = await relay.ensureStarted();
         await client.release(name);
@@ -379,13 +471,21 @@ export class AgentRelay {
             return;
           }
           let timer: ReturnType<typeof setTimeout> | undefined;
-          relay.exitResolvers.set(name, (reason) => {
-            if (timer) clearTimeout(timer);
-            resolve(reason);
+          const token = ++relay.exitResolverSeq;
+          relay.exitResolvers.set(name, {
+            resolve(reason) {
+              if (timer) clearTimeout(timer);
+              resolve(reason);
+            },
+            token,
           });
           if (timeoutMs !== undefined) {
             timer = setTimeout(() => {
-              relay.exitResolvers.delete(name);
+              // Only delete if this is still our resolver (not one from a later call)
+              const current = relay.exitResolvers.get(name);
+              if (current?.token === token) {
+                relay.exitResolvers.delete(name);
+              }
               resolve("timeout");
             }, timeoutMs);
           }
@@ -438,11 +538,12 @@ export class AgentRelay {
         const channels = options?.channels ?? ["general"];
         const args = options?.args ?? [];
 
+        const task = options?.task;
         let result: { name: string; runtime: AgentRuntime };
         if (runtime === "headless_claude") {
-          result = await client.spawnHeadlessClaude({ name, args, channels });
+          result = await client.spawnHeadlessClaude({ name, args, channels, task });
         } else {
-          result = await client.spawnPty({ name, cli, args, channels });
+          result = await client.spawnPty({ name, cli, args, channels, task });
         }
 
         const agent = relay.makeAgent(result.name, result.runtime, channels);

package/packages/sdk-ts/src/relaycast.ts

@@ -2,7 +2,7 @@ import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { Relay, RelayError, type AgentClient } from "@relaycast/sdk";
+import { RelayCast, RelayError, type AgentClient } from "@relaycast/sdk";
 
 export interface RelaycastCredentials {
   workspace_id: string;
@@ -85,7 +85,7 @@ export class RelaycastApi {
     if (this.agentClient) return this.agentClient;
 
     const apiKey = await this.resolveApiKey();
-    const relay = new Relay({ apiKey, baseUrl: this.baseUrl });
+    const relay = new RelayCast({ apiKey, baseUrl: this.baseUrl });
 
     // Register — retry with a suffixed name on 409 conflict.
     let name = this.agentName;

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.3.2"
+    "@agent-relay/protocol": "2.3.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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": "2.3.2",
+  "version": "2.3.4",
   "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": "2.3.2"
+    "@agent-relay/config": "2.3.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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/resiliency": "2.3.2"
+    "@agent-relay/resiliency": "2.3.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

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

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.3.2",
-    "@agent-relay/protocol": "2.3.2",
-    "@agent-relay/config": "2.3.2",
-    "@agent-relay/continuity": "2.3.2",
-    "@agent-relay/resiliency": "2.3.2",
+    "@agent-relay/api-types": "2.3.4",
+    "@agent-relay/protocol": "2.3.4",
+    "@agent-relay/config": "2.3.4",
+    "@agent-relay/continuity": "2.3.4",
+    "@agent-relay/resiliency": "2.3.4",
     "zod": "^3.23.8"
   },
   "devDependencies": {