agent-relay 3.2.22 → 4.0.1

package/packages/sdk/src/client.ts

@@ -1,354 +1,369 @@
-import { once } from 'node:events';
-import { execSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
-import fs from 'node:fs';
-import os from 'node:os';
+/**
+ * AgentRelayClient — single client for communicating with an agent-relay broker
+ * over HTTP/WS. Works identically for local and remote brokers.
+ *
+ * Usage:
+ *   // Remote broker (Daytona sandbox, cloud, etc.)
+ *   const client = new AgentRelayClient({ baseUrl, apiKey });
+ *
+ *   // Local broker (spawn and connect)
+ *   const client = await AgentRelayClient.spawn({ cwd: '/my/project' });
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { getProjectPaths } from '@agent-relay/config';
-
-import {
-  PROTOCOL_VERSION,
-  type AgentRuntime,
-  type AgentSpec,
-  type BrokerEvent,
-  type BrokerStats,
-  type BrokerStatus,
-  type CrashInsightsResponse,
-  type HeadlessProvider,
-  type ProtocolEnvelope,
-  type ProtocolError,
-  type RestartPolicy,
-  type MessageInjectionMode,
+import { BrokerTransport, AgentRelayProtocolError } from './transport.js';
+import { getBrokerBinaryPath } from './broker-path.js';
+import type {
+  AgentRuntime,
+  BrokerEvent,
+  BrokerStats,
+  BrokerStatus,
+  CrashInsightsResponse,
+  HeadlessProvider,
 } from './protocol.js';
+import type {
+  AgentTransport,
+  SpawnPtyInput,
+  SpawnProviderInput,
+  SendMessageInput,
+  ListAgent,
+} from './types.js';
+
+// ── Types ──────────────────────────────────────────────────────────────
 
 export interface AgentRelayClientOptions {
+  baseUrl: string;
+  apiKey?: string;
+  /** Timeout in ms for HTTP requests. Default: 30000. */
+  requestTimeoutMs?: number;
+}
+
+export interface AgentRelayBrokerInitArgs {
+  /** Optional HTTP API port for dashboard proxy (0 = disabled). */
+  apiPort?: number;
+  /** Bind address for the HTTP API. Defaults to 127.0.0.1 in the broker. */
+  apiBind?: string;
+  /** Enable persistence for broker state under the working directory. */
+  persist?: boolean;
+  /** Override the directory used for broker state files. */
+  stateDir?: string;
+}
+
+export interface AgentRelaySpawnOptions {
+  /** Path to the agent-relay-broker binary. Auto-resolved if omitted. */
   binaryPath?: string;
-  binaryArgs?: string[];
+  /** Structured options mapped to the broker's Rust `init` CLI flags. */
+  binaryArgs?: AgentRelayBrokerInitArgs;
+  /** Broker name. Defaults to cwd basename. */
   brokerName?: string;
+  /** Default channels for spawned agents. */
   channels?: string[];
+  /** Working directory for the broker process. */
   cwd?: string;
+  /** Environment variables for the broker process. */
   env?: NodeJS.ProcessEnv;
+  /** Forward broker stderr to this callback. */
+  onStderr?: (line: string) => void;
+  /** Timeout in ms to wait for broker to become ready. Default: 15000. */
+  startupTimeoutMs?: number;
+  /** Timeout in ms for HTTP requests to the broker. Default: 30000. */
   requestTimeoutMs?: number;
-  shutdownTimeoutMs?: number;
-  clientName?: string;
-  clientVersion?: string;
 }
 
-export interface SpawnPtyInput {
-  name: string;
-  cli: string;
-  args?: string[];
-  channels?: string[];
-  task?: string;
-  model?: string;
-  cwd?: string;
-  team?: string;
-  shadowOf?: string;
-  shadowMode?: string;
-  /** Silence duration in seconds before emitting agent_idle (0 = disabled, default: 30). */
-  idleThresholdSecs?: number;
-  /** Auto-restart policy for crashed agents. */
-  restartPolicy?: RestartPolicy;
-  /** Name of a previously released agent whose continuity context should be injected. */
-  continueFrom?: string;
-  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
-   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
-  skipRelayPrompt?: boolean;
+export interface SessionInfo {
+  broker_version: string;
+  protocol_version: number;
+  workspace_key?: string;
+  default_workspace_id?: string;
+  mode: string;
+  uptime_secs: number;
 }
 
-export interface SpawnHeadlessInput {
-  name: string;
-  provider: HeadlessProvider;
-  args?: string[];
-  channels?: string[];
-  task?: string;
-  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
-   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
-  skipRelayPrompt?: boolean;
+function isHeadlessProvider(value: string): value is HeadlessProvider {
+  return value === 'claude' || value === 'opencode';
 }
 
-export type AgentTransport = 'pty' | 'headless';
-
-export interface SpawnProviderInput {
-  name: string;
-  provider: string;
-  transport?: AgentTransport;
-  args?: string[];
-  channels?: string[];
-  task?: string;
-  model?: string;
-  cwd?: string;
-  team?: string;
-  shadowOf?: string;
-  shadowMode?: string;
-  idleThresholdSecs?: number;
-  restartPolicy?: RestartPolicy;
-  continueFrom?: string;
-  /** When true, skip injecting the relay MCP configuration and protocol prompt into the spawned agent.
-   *  Useful for minor tasks where relay messaging is not needed, saving tokens. */
-  skipRelayPrompt?: boolean;
+function resolveSpawnTransport(input: SpawnProviderInput): AgentTransport {
+  return input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
 }
 
-export interface SendMessageInput {
-  to: string;
-  text: string;
-  from?: string;
-  threadId?: string;
-  workspaceId?: string;
-  workspaceAlias?: string;
-  priority?: number;
-  data?: Record<string, unknown>;
-  mode?: MessageInjectionMode;
-}
+function isProcessRunning(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
 
-export interface ListAgent {
-  name: string;
-  runtime: AgentRuntime;
-  provider?: HeadlessProvider;
-  cli?: string;
-  model?: string;
-  team?: string;
-  channels: string[];
-  parent?: string;
-  pid?: number;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
 }
 
-interface PendingRequest {
-  expectedType: 'ok' | 'hello_ack';
-  resolve: (value: ProtocolEnvelope<unknown>) => void;
-  reject: (error: Error) => void;
-  timeout: ReturnType<typeof setTimeout>;
-}
+function buildBrokerInitArgs(args?: AgentRelayBrokerInitArgs): string[] {
+  if (!args) {
+    return [];
+  }
 
-interface ParsedEnvelope {
-  v: number;
-  type: string;
-  request_id?: string;
-  payload: unknown;
-}
+  const cliArgs: string[] = [];
 
-export class AgentRelayProtocolError extends Error {
-  code: string;
-  retryable: boolean;
-  data?: unknown;
-
-  constructor(payload: ProtocolError) {
-    super(payload.message);
-    this.name = 'AgentRelayProtocolError';
-    this.code = payload.code;
-    this.retryable = payload.retryable;
-    this.data = payload.data;
+  if (args.persist) {
+    cliArgs.push('--persist');
   }
-}
-
-export class AgentRelayProcessError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'AgentRelayProcessError';
+  if (args.apiPort !== undefined) {
+    cliArgs.push('--api-port', String(args.apiPort));
+  }
+  if (args.apiBind !== undefined) {
+    cliArgs.push('--api-bind', args.apiBind);
+  }
+  if (args.stateDir !== undefined) {
+    cliArgs.push('--state-dir', args.stateDir);
   }
-}
 
-function isHeadlessProvider(value: string): value is HeadlessProvider {
-  return value === 'claude' || value === 'opencode';
+  return cliArgs;
 }
 
+// ── Client ─────────────────────────────────────────────────────────────
+
 export class AgentRelayClient {
-  private readonly options: Required<AgentRelayClientOptions>;
-  private child?: ChildProcessWithoutNullStreams;
-  private stdoutRl?: ReadlineInterface;
-  private stderrRl?: ReadlineInterface;
-  private lastStderrLine?: string;
-  private requestSeq = 0;
-  private pending = new Map<string, PendingRequest>();
-  private startingPromise?: Promise<void>;
-  private eventListeners = new Set<(event: BrokerEvent) => void>();
-  private stderrListeners = new Set<(line: string) => void>();
-  private eventBuffer: BrokerEvent[] = [];
-  private maxBufferSize = 1000;
-  private exitPromise?: Promise<void>;
-  /** The workspace key returned by the broker in its hello_ack response. */
-  workspaceKey?: string;
+  private readonly transport: BrokerTransport;
 
-  constructor(options: AgentRelayClientOptions = {}) {
-    this.options = {
-      binaryPath: options.binaryPath ?? resolveDefaultBinaryPath(),
-      binaryArgs: options.binaryArgs ?? [],
-      brokerName: options.brokerName ?? (path.basename(options.cwd ?? process.cwd()) || 'project'),
-      channels: options.channels ?? ['general'],
-      cwd: options.cwd ?? process.cwd(),
-      env: options.env ?? process.env,
-      requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
-      shutdownTimeoutMs: options.shutdownTimeoutMs ?? 3_000,
-      clientName: options.clientName ?? '@agent-relay/sdk',
-      clientVersion: options.clientVersion ?? '0.1.0',
-    };
-  }
+  /** Set after spawn() — the managed child process. */
+  private child: ChildProcess | null = null;
+  /** Lease renewal timer (only for spawned brokers). */
+  private leaseTimer: ReturnType<typeof setInterval> | null = null;
 
-  static async start(options: AgentRelayClientOptions = {}): Promise<AgentRelayClient> {
-    const client = new AgentRelayClient(options);
-    await client.start();
-    return client;
-  }
+  workspaceKey?: string;
 
-  onEvent(listener: (event: BrokerEvent) => void): () => void {
-    this.eventListeners.add(listener);
-    return () => {
-      this.eventListeners.delete(listener);
-    };
+  constructor(options: AgentRelayClientOptions) {
+    this.transport = new BrokerTransport({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      requestTimeoutMs: options.requestTimeoutMs,
+    });
   }
 
-  queryEvents(filter?: { kind?: string; name?: string; since?: number; limit?: number }): BrokerEvent[] {
-    let events = [...this.eventBuffer];
-    if (filter?.kind) {
-      events = events.filter((event) => event.kind === filter.kind);
+  /**
+   * Connect to an already-running broker by reading its connection file.
+   *
+   * The broker writes `connection.json` to its data directory ({cwd}/.agent-relay/
+   * in persist mode). This method reads that file to get the URL and API key.
+   *
+   * @param cwd — project directory (default: process.cwd())
+   * @param connectionPath — explicit path to connection.json (overrides cwd)
+   */
+  static connect(options?: { cwd?: string; connectionPath?: string }): AgentRelayClient {
+    const cwd = options?.cwd ?? process.cwd();
+    const stateDir = process.env.AGENT_RELAY_STATE_DIR;
+    const connPath =
+      options?.connectionPath ?? path.join(stateDir ?? path.join(cwd, '.agent-relay'), 'connection.json');
+
+    if (!existsSync(connPath)) {
+      throw new Error(
+        `No running broker found (${connPath} does not exist). Start one with 'agent-relay up' or use AgentRelayClient.spawn().`
+      );
     }
-    if (filter?.name) {
-      events = events.filter((event) => 'name' in event && event.name === filter.name);
+
+    const raw = readFileSync(connPath, 'utf-8');
+    let conn: { url?: string; api_key?: string; port?: number; pid?: number };
+    try {
+      conn = JSON.parse(raw);
+    } catch {
+      throw new Error(`Corrupt broker connection file (${connPath}). Remove it and start the broker again.`);
     }
-    const since = filter?.since;
-    if (since !== undefined) {
-      events = events.filter(
-        (event) => 'timestamp' in event && typeof event.timestamp === 'number' && event.timestamp >= since
+
+    if (typeof conn.url !== 'string' || typeof conn.api_key !== 'string' || typeof conn.pid !== 'number') {
+      throw new Error(
+        `Invalid broker connection metadata in ${connPath}. Remove it and start the broker again.`
       );
     }
-    const limit = filter?.limit;
-    if (limit !== undefined) {
-      events = events.slice(-limit);
-    }
-    return events;
-  }
 
-  getLastEvent(kind: string, name?: string): BrokerEvent | undefined {
-    for (let i = this.eventBuffer.length - 1; i >= 0; i -= 1) {
-      const event = this.eventBuffer[i];
-      if (event.kind === kind && (!name || ('name' in event && event.name === name))) {
-        return event;
-      }
+    if (!isProcessRunning(conn.pid)) {
+      throw new Error(
+        `Stale broker connection file (${connPath}) points to dead pid ${conn.pid}. Start the broker with 'agent-relay up' or use AgentRelayClient.spawn().`
+      );
     }
-    return undefined;
+
+    return new AgentRelayClient({ baseUrl: conn.url, apiKey: conn.api_key });
   }
 
-  onBrokerStderr(listener: (line: string) => void): () => void {
-    this.stderrListeners.add(listener);
-    return () => {
-      this.stderrListeners.delete(listener);
+  /**
+   * Spawn a local broker process and return a connected client.
+   *
+   * 1. Generates a random API key
+   * 2. Spawns the broker binary (attached)
+   * 3. Parses the API port from stdout
+   * 4. Connects HTTP/WS transport
+   * 5. Fetches session metadata
+   * 6. Starts event stream + lease renewal
+   */
+  static async spawn(options?: AgentRelaySpawnOptions): Promise<AgentRelayClient> {
+    const binaryPath = options?.binaryPath ?? getBrokerBinaryPath() ?? 'agent-relay-broker';
+    const cwd = options?.cwd ?? process.cwd();
+    const brokerName = options?.brokerName ?? (path.basename(cwd) || 'project');
+    const channels = options?.channels ?? ['general'];
+    const timeoutMs = options?.startupTimeoutMs ?? 15_000;
+    const userArgs = buildBrokerInitArgs(options?.binaryArgs);
+
+    const apiKey = `br_${randomBytes(16).toString('hex')}`;
+
+    const env = {
+      ...process.env,
+      ...options?.env,
+      RELAY_BROKER_API_KEY: apiKey,
     };
+
+    const args = ['init', '--name', brokerName, '--channels', channels.join(','), ...userArgs];
+
+    const child = spawn(binaryPath, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', options?.onStderr ? 'pipe' : 'ignore'],
+    });
+
+    // Forward stderr if requested
+    if (options?.onStderr && child.stderr) {
+      const { createInterface } = await import('node:readline');
+      const rl = createInterface({ input: child.stderr });
+      rl.on('line', (line) => options.onStderr!(line));
+    }
+
+    // Parse the API URL from stdout (the broker prints it after binding)
+    const baseUrl = await waitForApiUrl(child, timeoutMs);
+
+    const client = new AgentRelayClient({
+      baseUrl,
+      apiKey,
+      requestTimeoutMs: options?.requestTimeoutMs,
+    });
+    client.child = child;
+
+    await client.getSession();
+    client.connectEvents();
+
+    // Renew the owner lease so the broker doesn't auto-shutdown
+    client.leaseTimer = setInterval(() => {
+      client.renewLease().catch(() => {});
+    }, 60_000);
+
+    child.on('exit', () => {
+      client.disconnectEvents();
+      if (client.leaseTimer) {
+        clearInterval(client.leaseTimer);
+        client.leaseTimer = null;
+      }
+    });
+
+    return client;
   }
 
+  /** PID of the managed broker process, if spawned locally. */
   get brokerPid(): number | undefined {
     return this.child?.pid;
   }
 
-  async start(): Promise<void> {
-    if (this.child) {
-      return;
-    }
-    if (this.startingPromise) {
-      return this.startingPromise;
-    }
+  // ── Session ────────────────────────────────────────────────────────
 
-    this.startingPromise = this.startInternal();
-    try {
-      await this.startingPromise;
-    } finally {
-      this.startingPromise = undefined;
-    }
+  async getSession(): Promise<SessionInfo> {
+    const session = await this.transport.request<SessionInfo>('/api/session');
+    this.workspaceKey = session.workspace_key;
+    return session;
   }
 
-  /**
-   * Pre-register a batch of agents with Relaycast before their steps execute.
-   * The broker warms its token cache in parallel; subsequent spawn_agent calls
-   * hit the cache rather than waiting on individual HTTP registrations.
-   * Fire-and-forget from the caller's perspective — broker responds immediately
-   * and registers in the background.
-   */
-  async preflightAgents(agents: Array<{ name: string; cli: string | AgentRuntime }>): Promise<void> {
-    if (agents.length === 0) return;
-    await this.start();
-    await this.requestOk<void>('preflight_agents', { agents });
+  async healthCheck(): Promise<{ service: string }> {
+    return this.transport.request<{ service: string }>('/health');
   }
 
-  async spawnPty(input: SpawnPtyInput): Promise<{ name: string; runtime: AgentRuntime }> {
-    await this.start();
-    const args = buildPtyArgsWithModel(input.cli, input.args ?? [], input.model);
-    const agent: AgentSpec = {
-      name: input.name,
-      runtime: 'pty',
-      cli: input.cli,
-      args,
-      channels: input.channels ?? [],
-      model: input.model,
-      cwd: input.cwd ?? this.options.cwd,
-      team: input.team,
-      shadow_of: input.shadowOf,
-      shadow_mode: input.shadowMode,
-      restart_policy: input.restartPolicy,
-    };
-    const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>('spawn_agent', {
-      agent,
-      ...(input.task != null ? { initial_task: input.task } : {}),
-      ...(input.idleThresholdSecs != null ? { idle_threshold_secs: input.idleThresholdSecs } : {}),
-      ...(input.continueFrom != null ? { continue_from: input.continueFrom } : {}),
-      ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
-    });
-    return result;
+  // ── Events ─────────────────────────────────────────────────────────
+
+  connectEvents(sinceSeq?: number): void {
+    this.transport.connect(sinceSeq);
   }
 
-  async spawnHeadless(input: SpawnHeadlessInput): Promise<{ name: string; runtime: AgentRuntime }> {
-    await this.start();
-    const agent: AgentSpec = {
-      name: input.name,
-      runtime: 'headless',
-      provider: input.provider,
-      args: input.args ?? [],
-      channels: input.channels ?? [],
-    };
-    const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>('spawn_agent', {
-      agent,
-      ...(input.task != null ? { initial_task: input.task } : {}),
-      ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
-    });
-    return result;
+  disconnectEvents(): void {
+    this.transport.disconnect();
   }
 
-  async spawnProvider(input: SpawnProviderInput): Promise<{ name: string; runtime: AgentRuntime }> {
-    const transport = input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
-    if (transport === 'headless') {
-      if (!isHeadlessProvider(input.provider)) {
-        throw new AgentRelayProcessError(
-          `provider '${input.provider}' does not support headless transport (supported: claude, opencode)`
-        );
-      }
-      return this.spawnHeadless({
+  onEvent(listener: (event: BrokerEvent) => void): () => void {
+    return this.transport.onEvent(listener);
+  }
+
+  queryEvents(filter?: { kind?: string; name?: string; since?: number; limit?: number }): BrokerEvent[] {
+    return this.transport.queryEvents(filter);
+  }
+
+  getLastEvent(kind: string, name?: string): BrokerEvent | undefined {
+    return this.transport.getLastEvent(kind, name);
+  }
+
+  // ── Agent lifecycle ────────────────────────────────────────────────
+
+  async spawnPty(input: SpawnPtyInput): Promise<{ name: string; runtime: AgentRuntime }> {
+    return this.transport.request('/api/spawn', {
+      method: 'POST',
+      body: JSON.stringify({
         name: input.name,
-        provider: input.provider,
-        args: input.args,
-        channels: input.channels,
+        cli: input.cli,
+        model: input.model,
+        args: input.args ?? [],
         task: input.task,
+        channels: input.channels ?? [],
+        cwd: input.cwd,
+        team: input.team,
+        shadowOf: input.shadowOf,
+        shadowMode: input.shadowMode,
+        continueFrom: input.continueFrom,
+        idleThresholdSecs: input.idleThresholdSecs,
+        restartPolicy: input.restartPolicy,
         skipRelayPrompt: input.skipRelayPrompt,
-      });
+      }),
+    });
+  }
+
+  async spawnProvider(input: SpawnProviderInput): Promise<{ name: string; runtime: AgentRuntime }> {
+    const transport = resolveSpawnTransport(input);
+    if (transport === 'headless' && !isHeadlessProvider(input.provider)) {
+      throw new Error(
+        `provider '${input.provider}' does not support headless transport (supported: claude, opencode)`
+      );
     }
 
-    return this.spawnPty({
-      name: input.name,
-      cli: input.provider,
-      args: input.args,
-      channels: input.channels,
-      task: input.task,
-      model: input.model,
-      cwd: input.cwd,
-      team: input.team,
-      shadowOf: input.shadowOf,
-      shadowMode: input.shadowMode,
-      idleThresholdSecs: input.idleThresholdSecs,
-      restartPolicy: input.restartPolicy,
-      continueFrom: input.continueFrom,
-      skipRelayPrompt: input.skipRelayPrompt,
+    return this.transport.request('/api/spawn', {
+      method: 'POST',
+      body: JSON.stringify({
+        name: input.name,
+        cli: input.provider,
+        model: input.model,
+        args: input.args ?? [],
+        task: input.task,
+        channels: input.channels ?? [],
+        cwd: input.cwd,
+        team: input.team,
+        shadowOf: input.shadowOf,
+        shadowMode: input.shadowMode,
+        continueFrom: input.continueFrom,
+        idleThresholdSecs: input.idleThresholdSecs,
+        restartPolicy: input.restartPolicy,
+        skipRelayPrompt: input.skipRelayPrompt,
+        transport,
+      }),
     });
   }
 
+  async spawnHeadless(input: {
+    name: string;
+    provider: HeadlessProvider;
+    args?: string[];
+    channels?: string[];
+    task?: string;
+    skipRelayPrompt?: boolean;
+  }): Promise<{ name: string; runtime: AgentRuntime }> {
+    return this.spawnProvider({ ...input, transport: 'headless' });
+  }
+
   async spawnClaude(
     input: Omit<SpawnProviderInput, 'provider'>
   ): Promise<{ name: string; runtime: AgentRuntime }> {
@@ -362,23 +377,24 @@ export class AgentRelayClient {
   }
 
   async release(name: string, reason?: string): Promise<{ name: string }> {
-    await this.start();
-    return this.requestOk<{ name: string }>('release_agent', { name, reason });
+    return this.transport.request(`/api/spawned/${encodeURIComponent(name)}`, {
+      method: 'DELETE',
+      ...(reason ? { body: JSON.stringify({ reason }) } : {}),
+    });
   }
 
-  async sendInput(name: string, data: string): Promise<{ name: string; bytes_written: number }> {
-    await this.start();
-    return this.requestOk<{ name: string; bytes_written: number }>('send_input', { name, data });
+  async listAgents(): Promise<ListAgent[]> {
+    const result = await this.transport.request<{ agents: ListAgent[] }>('/api/spawned');
+    return result.agents;
   }
 
-  async subscribeChannels(name: string, channels: string[]): Promise<void> {
-    await this.start();
-    await this.requestOk<void>('subscribe_channels', { name, channels });
-  }
+  // ── PTY control ────────────────────────────────────────────────────
 
-  async unsubscribeChannels(name: string, channels: string[]): Promise<void> {
-    await this.start();
-    await this.requestOk<void>('unsubscribe_channels', { name, channels });
+  async sendInput(name: string, data: string): Promise<{ name: string; bytes_written: number }> {
+    return this.transport.request(`/api/input/${encodeURIComponent(name)}`, {
+      method: 'POST',
+      body: JSON.stringify({ data }),
+    });
   }
 
   async resizePty(
@@ -386,56 +402,29 @@ export class AgentRelayClient {
     rows: number,
     cols: number
   ): Promise<{ name: string; rows: number; cols: number }> {
-    await this.start();
-    return this.requestOk<{ name: string; rows: number; cols: number }>('resize_pty', {
-      name,
-      rows,
-      cols,
-    });
-  }
-
-  async setModel(
-    name: string,
-    model: string,
-    opts?: { timeoutMs?: number }
-  ): Promise<{ name: string; model: string; success: boolean }> {
-    await this.start();
-    return this.requestOk<{ name: string; model: string; success: boolean }>('set_model', {
-      name,
-      model,
-      timeout_ms: opts?.timeoutMs,
+    return this.transport.request(`/api/resize/${encodeURIComponent(name)}`, {
+      method: 'POST',
+      body: JSON.stringify({ rows, cols }),
     });
   }
 
-  async getMetrics(agent?: string): Promise<{
-    agents: Array<{ name: string; pid: number; memory_bytes: number; uptime_secs: number }>;
-    broker?: BrokerStats;
-  }> {
-    await this.start();
-    return this.requestOk<{
-      agents: Array<{ name: string; pid: number; memory_bytes: number; uptime_secs: number }>;
-      broker?: BrokerStats;
-    }>('get_metrics', { agent });
-  }
-
-  async getCrashInsights(): Promise<CrashInsightsResponse> {
-    await this.start();
-    return this.requestOk<CrashInsightsResponse>('get_crash_insights', {});
-  }
+  // ── Messaging ──────────────────────────────────────────────────────
 
   async sendMessage(input: SendMessageInput): Promise<{ event_id: string; targets: string[] }> {
-    await this.start();
     try {
-      return await this.requestOk<{ event_id: string; targets: string[] }>('send_message', {
-        to: input.to,
-        text: input.text,
-        from: input.from,
-        thread_id: input.threadId,
-        workspace_id: input.workspaceId,
-        workspace_alias: input.workspaceAlias,
-        priority: input.priority,
-        data: input.data,
-        mode: input.mode,
+      return await this.transport.request('/api/send', {
+        method: 'POST',
+        body: JSON.stringify({
+          to: input.to,
+          text: input.text,
+          from: input.from,
+          threadId: input.threadId,
+          workspaceId: input.workspaceId,
+          workspaceAlias: input.workspaceAlias,
+          priority: input.priority,
+          data: input.data,
+          mode: input.mode,
+        }),
       });
     } catch (error) {
       if (error instanceof AgentRelayProtocolError && error.code === 'unsupported_operation') {
@@ -445,786 +434,181 @@ export class AgentRelayClient {
     }
   }
 
-  async listAgents(): Promise<ListAgent[]> {
-    await this.start();
-    const result = await this.requestOk<{ agents: ListAgent[] }>('list_agents', {});
-    return result.agents;
-  }
+  // ── Model control ──────────────────────────────────────────────────
 
-  async getStatus(): Promise<BrokerStatus> {
-    await this.start();
-    return this.requestOk<BrokerStatus>('get_status', {});
-  }
-
-  async shutdown(): Promise<void> {
-    if (!this.child) {
-      return;
-    }
-
-    void this.requestOk('shutdown', {}).catch(() => {
-      // Continue shutdown path if broker is already unhealthy or exits before replying.
+  async setModel(
+    name: string,
+    model: string,
+    opts?: { timeoutMs?: number }
+  ): Promise<{ name: string; model: string; success: boolean }> {
+    return this.transport.request(`/api/spawned/${encodeURIComponent(name)}/model`, {
+      method: 'POST',
+      body: JSON.stringify({ model, timeout_ms: opts?.timeoutMs }),
     });
-
-    const child = this.child;
-    const wait = this.exitPromise ?? Promise.resolve();
-    const waitForExit = async (timeoutMs: number): Promise<boolean> => {
-      let timer: ReturnType<typeof setTimeout> | undefined;
-      const result = await Promise.race([
-        wait.then(() => true),
-        new Promise<boolean>((resolve) => {
-          timer = setTimeout(() => resolve(false), timeoutMs);
-        }),
-      ]);
-      if (timer !== undefined) clearTimeout(timer);
-      return result;
-    };
-
-    if (await waitForExit(this.options.shutdownTimeoutMs)) {
-      return;
-    }
-
-    if (child.exitCode === null && child.signalCode === null) {
-      child.kill('SIGTERM');
-    }
-    if (await waitForExit(1_000)) {
-      return;
-    }
-
-    if (child.exitCode === null && child.signalCode === null) {
-      child.kill('SIGKILL');
-    }
-    await waitForExit(1_000);
   }
 
-  async waitForExit(): Promise<void> {
-    if (!this.child) {
-      return;
-    }
-    await this.exitPromise;
-  }
+  // ── Channels ───────────────────────────────────────────────────────
 
-  private async startInternal(): Promise<void> {
-    const resolvedBinary = expandTilde(this.options.binaryPath);
-    if (isExplicitPath(this.options.binaryPath) && !fs.existsSync(resolvedBinary)) {
-      throw new AgentRelayProcessError(`broker binary not found: ${this.options.binaryPath}`);
-    }
-    this.lastStderrLine = undefined;
-
-    const args = [
-      'init',
-      '--name',
-      this.options.brokerName,
-      ...(this.options.channels.length > 0 ? ['--channels', this.options.channels.join(',')] : []),
-      ...this.options.binaryArgs,
-    ];
-
-    // Ensure the SDK bin directory (containing agent-relay-broker) is on
-    // PATH so spawned workers can find it without any user setup.
-    const env = { ...this.options.env };
-    if (isExplicitPath(this.options.binaryPath)) {
-      const binDir = path.dirname(path.resolve(resolvedBinary));
-      const currentPath = env.PATH ?? env.Path ?? '';
-      if (!currentPath.split(path.delimiter).includes(binDir)) {
-        env.PATH = `${binDir}${path.delimiter}${currentPath}`;
-      }
-    }
-
-    console.error(`[broker] Starting: ${resolvedBinary} ${args.join(' ')}`);
-    const child = spawn(resolvedBinary, args, {
-      cwd: this.options.cwd,
-      env,
-      stdio: 'pipe',
-    });
-
-    this.child = child;
-    this.stdoutRl = createInterface({ input: child.stdout, crlfDelay: Infinity });
-    this.stderrRl = createInterface({ input: child.stderr, crlfDelay: Infinity });
-
-    this.stdoutRl.on('line', (line) => {
-      this.handleStdoutLine(line);
-    });
-
-    this.stderrRl.on('line', (line) => {
-      const trimmed = line.trim();
-      if (trimmed) {
-        this.lastStderrLine = trimmed;
-      }
-      for (const listener of this.stderrListeners) {
-        listener(line);
-      }
-    });
-
-    this.exitPromise = new Promise<void>((resolve) => {
-      // Use 'close' instead of 'exit' so that all buffered stderr/stdout
-      // data has been consumed before we build the error message.  The
-      // 'exit' event fires when the process terminates, but stdio streams
-      // may still have unread data; 'close' fires after both the process
-      // exits AND all stdio streams have ended.
-      child.once('close', (code, signal) => {
-        const detail = this.lastStderrLine ? `: ${this.lastStderrLine}` : '';
-        const error = new AgentRelayProcessError(
-          `broker exited (code=${code ?? 'null'}, signal=${signal ?? 'null'})${detail}`
-        );
-        this.failAllPending(error);
-        this.disposeProcessHandles();
-        resolve();
-      });
-      child.once('error', (error) => {
-        this.failAllPending(error);
-        this.disposeProcessHandles();
-        resolve();
-      });
+  async subscribeChannels(name: string, channels: string[]): Promise<void> {
+    await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/subscribe`, {
+      method: 'POST',
+      body: JSON.stringify({ channels }),
     });
-
-    const helloAck = await this.requestHello();
-    console.error('[broker] Broker ready (hello handshake complete)');
-    if (helloAck.workspace_key) {
-      this.workspaceKey = helloAck.workspace_key;
-    }
   }
 
-  private disposeProcessHandles(): void {
-    this.stdoutRl?.close();
-    this.stderrRl?.close();
-    this.stdoutRl = undefined;
-    this.stderrRl = undefined;
-    this.lastStderrLine = undefined;
-    this.child = undefined;
-    this.exitPromise = undefined;
-  }
-
-  private failAllPending(error: Error): void {
-    for (const pending of this.pending.values()) {
-      clearTimeout(pending.timeout);
-      pending.reject(error);
-    }
-    this.pending.clear();
+  async unsubscribeChannels(name: string, channels: string[]): Promise<void> {
+    await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/unsubscribe`, {
+      method: 'POST',
+      body: JSON.stringify({ channels }),
+    });
   }
 
-  private handleStdoutLine(line: string): void {
-    let parsed: ParsedEnvelope;
-    try {
-      parsed = JSON.parse(line) as ParsedEnvelope;
-    } catch {
-      // Non-protocol output should not crash the SDK.
-      return;
-    }
-
-    if (!parsed || typeof parsed !== 'object') {
-      return;
-    }
-    if (parsed.v !== PROTOCOL_VERSION || typeof parsed.type !== 'string') {
-      return;
-    }
-
-    const envelope: ProtocolEnvelope<unknown> = {
-      v: parsed.v,
-      type: parsed.type,
-      request_id: parsed.request_id,
-      payload: parsed.payload,
-    };
-
-    if (envelope.type === 'event') {
-      const payload = envelope.payload as BrokerEvent;
-      this.eventBuffer.push(payload);
-      if (this.eventBuffer.length > this.maxBufferSize) {
-        this.eventBuffer.shift();
-      }
-      for (const listener of this.eventListeners) {
-        listener(payload);
-      }
-      return;
-    }
-
-    if (!envelope.request_id) {
-      return;
-    }
-
-    const pending = this.pending.get(envelope.request_id);
-    if (!pending) {
-      return;
-    }
-
-    if (envelope.type === 'error') {
-      clearTimeout(pending.timeout);
-      this.pending.delete(envelope.request_id);
-      pending.reject(new AgentRelayProtocolError(envelope.payload as ProtocolError));
-      return;
-    }
+  // ── Observability ──────────────────────────────────────────────────
 
-    if (envelope.type !== pending.expectedType) {
-      clearTimeout(pending.timeout);
-      this.pending.delete(envelope.request_id);
-      pending.reject(
-        new AgentRelayProcessError(
-          `unexpected response type '${envelope.type}' for request '${envelope.request_id}' (expected '${pending.expectedType}')`
-        )
-      );
-      return;
-    }
-
-    clearTimeout(pending.timeout);
-    this.pending.delete(envelope.request_id);
-    pending.resolve(envelope);
-  }
-
-  private async requestHello(): Promise<{
-    broker_version: string;
-    protocol_version: number;
-    workspace_key?: string;
+  async getMetrics(agent?: string): Promise<{
+    agents: Array<{ name: string; pid: number; memory_bytes: number; uptime_secs: number }>;
+    broker?: BrokerStats;
   }> {
-    const payload = {
-      client_name: this.options.clientName,
-      client_version: this.options.clientVersion,
-    };
-    const frame = await this.sendRequest('hello', payload, 'hello_ack');
-    return frame.payload as { broker_version: string; protocol_version: number; workspace_key?: string };
+    const query = agent ? `?agent=${encodeURIComponent(agent)}` : '';
+    return this.transport.request(`/api/metrics${query}`);
   }
 
-  private async requestOk<T = unknown>(type: string, payload: unknown): Promise<T> {
-    const frame = await this.sendRequest(type, payload, 'ok');
-    const result = frame.payload as { result: T };
-    return result.result;
+  async getStatus(): Promise<BrokerStatus> {
+    return this.transport.request<BrokerStatus>('/api/status');
   }
 
-  private async sendRequest(
-    type: string,
-    payload: unknown,
-    expectedType: 'ok' | 'hello_ack'
-  ): Promise<ProtocolEnvelope<unknown>> {
-    if (!this.child) {
-      throw new AgentRelayProcessError('broker is not running');
-    }
+  async getCrashInsights(): Promise<CrashInsightsResponse> {
+    return this.transport.request('/api/crash-insights');
+  }
 
-    const requestId = `req_${++this.requestSeq}`;
-    const message: ProtocolEnvelope<unknown> = {
-      v: PROTOCOL_VERSION,
-      type,
-      request_id: requestId,
-      payload,
-    };
+  // ── Lifecycle ──────────────────────────────────────────────────────
 
-    const responsePromise = new Promise<ProtocolEnvelope<unknown>>((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.pending.delete(requestId);
-        reject(
-          new AgentRelayProcessError(
-            `request timed out after ${this.options.requestTimeoutMs}ms (type='${type}', request_id='${requestId}')`
-          )
-        );
-      }, this.options.requestTimeoutMs);
-
-      this.pending.set(requestId, {
-        expectedType,
-        resolve,
-        reject,
-        timeout,
-      });
+  async preflight(agents: Array<{ name: string; cli: string }>): Promise<{ queued: number }> {
+    return this.transport.request('/api/preflight', {
+      method: 'POST',
+      body: JSON.stringify({ agents }),
     });
-
-    const line = `${JSON.stringify(message)}\n`;
-    if (!this.child.stdin.write(line)) {
-      await once(this.child.stdin, 'drain');
-    }
-
-    return responsePromise;
   }
-}
-
-const CLI_MODEL_FLAG_CLIS = new Set(['claude', 'codex', 'gemini', 'goose', 'aider']);
-
-const CLI_DEFAULT_ARGS: Record<string, string[]> = {
-  codex: ['-c', 'check_for_update_on_startup=false'],
-};
 
-function buildPtyArgsWithModel(cli: string, args: string[], model?: string): string[] {
-  const cliName = cli.split(':')[0].trim().toLowerCase();
-  const defaultArgs = CLI_DEFAULT_ARGS[cliName] ?? [];
-  const baseArgs = [...defaultArgs, ...args];
-  if (!model) {
-    return baseArgs;
+  async renewLease(): Promise<{ renewed: boolean; expires_in_secs: number }> {
+    return this.transport.request('/api/session/renew', { method: 'POST' });
   }
-  if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
-    return baseArgs;
-  }
-  if (hasModelArg(baseArgs)) {
-    return baseArgs;
-  }
-  return ['--model', model, ...baseArgs];
-}
 
-function hasModelArg(args: string[]): boolean {
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === '--model') {
-      return true;
-    }
-    if (arg.startsWith('--model=')) {
-      return true;
+  /**
+   * Shut down and clean up.
+   * - For spawned brokers (via .spawn()): sends POST /api/shutdown to kill the broker, waits for exit.
+   * - For connected brokers (via .connect() or constructor): just disconnects the transport.
+   *   Does NOT kill the broker — the caller doesn't own it.
+   */
+  async shutdown(): Promise<void> {
+    if (this.leaseTimer) {
+      clearInterval(this.leaseTimer);
+      this.leaseTimer = null;
     }
-  }
-  return false;
-}
-
-function expandTilde(p: string): string {
-  if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
-    const home = os.homedir();
-    return path.join(home, p.slice(2));
-  }
-  return p;
-}
-
-function isExplicitPath(binaryPath: string): boolean {
-  return (
-    binaryPath.includes('/') ||
-    binaryPath.includes('\\') ||
-    binaryPath.startsWith('.') ||
-    binaryPath.startsWith('~')
-  );
-}
-
-function detectPlatformSuffix(): string | null {
-  const platformMap: Record<string, Record<string, string>> = {
-    darwin: { arm64: 'darwin-arm64', x64: 'darwin-x64' },
-    linux: { arm64: 'linux-arm64', x64: 'linux-x64' },
-    win32: { x64: 'win32-x64' },
-  };
-  return platformMap[process.platform]?.[process.arch] ?? null;
-}
-
-function getLatestVersionSync(): string | null {
-  try {
-    const result = execSync('curl -fsSL https://api.github.com/repos/AgentWorkforce/relay/releases/latest', {
-      timeout: 15_000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).toString();
-    const match = result.match(/"tag_name"\s*:\s*"([^"]+)"/);
-    if (!match?.[1]) return null;
-    // Strip tag prefixes: "openclaw-v3.1.18" -> "3.1.18", "v3.1.18" -> "3.1.18"
-    return match[1].replace(/^openclaw-/, '').replace(/^v/, '');
-  } catch {
-    return null;
-  }
-}
 
-function installBrokerBinary(): string {
-  const suffix = detectPlatformSuffix();
-  if (!suffix) {
-    throw new AgentRelayProcessError(`Unsupported platform: ${process.platform}-${process.arch}`);
-  }
-
-  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-  const installDir = path.join(homeDir, '.agent-relay', 'bin');
-  const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
-  const targetPath = path.join(installDir, brokerExe);
-
-  console.log(`[agent-relay] Broker binary not found, installing for ${suffix}...`);
-
-  const version = getLatestVersionSync();
-  if (!version) {
-    throw new AgentRelayProcessError(
-      'Failed to fetch latest agent-relay version from GitHub.\n' +
-        'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash'
-    );
-  }
-
-  const binaryName = `agent-relay-broker-${suffix}`;
-  const downloadUrl = `https://github.com/AgentWorkforce/relay/releases/download/v${version}/${binaryName}`;
-
-  console.log(`[agent-relay] Downloading v${version} from ${downloadUrl}`);
-
-  try {
-    fs.mkdirSync(installDir, { recursive: true });
-    execSync(`curl -fsSL "${downloadUrl}" -o "${targetPath}"`, {
-      timeout: 60_000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    fs.chmodSync(targetPath, 0o755);
-
-    // macOS: strip quarantine attribute and re-sign to avoid Gatekeeper issues
-    if (process.platform === 'darwin') {
-      try {
-        execSync(`xattr -d com.apple.quarantine "${targetPath}" 2>/dev/null || true`, {
-          timeout: 10_000,
-          stdio: ['pipe', 'pipe', 'pipe'],
-        });
-      } catch {
-        // Non-fatal
-      }
+    // Only send the shutdown command if we own the broker process
+    if (this.child) {
       try {
-        execSync(`codesign --force --sign - "${targetPath}"`, {
-          timeout: 10_000,
-          stdio: ['pipe', 'pipe', 'pipe'],
-        });
+        await this.transport.request('/api/shutdown', { method: 'POST' });
       } catch {
-        // Non-fatal
+        // Broker may already be dead
       }
     }
 
-    // Verify
-    execSync(`"${targetPath}" --help`, { timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] });
-  } catch (err) {
-    try {
-      fs.unlinkSync(targetPath);
-    } catch {
-      /* ignore */
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    throw new AgentRelayProcessError(
-      `Failed to install broker binary: ${message}\n` +
-        'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash'
-    );
-  }
-
-  console.log(`[agent-relay] Broker installed to ${targetPath}`);
-  return targetPath;
-}
+    this.transport.disconnect();
 
-function resolveDefaultBinaryPath(): string {
-  const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
-  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
-
-  // 1. In a source checkout, prefer Cargo's release binary to avoid stale bundled
-  // copies when local dev rebuilds happen while broker processes are running.
-  const workspaceRelease = path.resolve(moduleDir, '..', '..', '..', 'target', 'release', brokerExe);
-  if (fs.existsSync(workspaceRelease)) {
-    return workspaceRelease;
+    if (this.child) {
+      await waitForExit(this.child, 5000);
+      this.child = null;
+    }
   }
 
-  // 2. Check for bundled platform-specific broker binary in SDK package (npm install).
-  //    Only use binaries that match the current platform to avoid running
-  //    e.g. a macOS binary on Linux (or vice-versa).
-  const binDir = path.resolve(moduleDir, '..', 'bin');
-  const suffix = detectPlatformSuffix();
-  if (suffix) {
-    const ext = process.platform === 'win32' ? '.exe' : '';
-    const platformBinary = path.join(binDir, `agent-relay-broker-${suffix}${ext}`);
-    if (fs.existsSync(platformBinary)) {
-      return platformBinary;
+  /** Disconnect without shutting down the broker. Alias for cases where the intent is clear. */
+  disconnect(): void {
+    if (this.leaseTimer) {
+      clearInterval(this.leaseTimer);
+      this.leaseTimer = null;
     }
+    this.transport.disconnect();
   }
 
-  // 3. Check for standalone broker binary in ~/.agent-relay/bin/ (install.sh)
-  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-  const standaloneBroker = path.join(homeDir, '.agent-relay', 'bin', brokerExe);
-  if (fs.existsSync(standaloneBroker)) {
-    return standaloneBroker;
+  async getConfig(): Promise<{ workspaceKey?: string }> {
+    return this.transport.request('/api/config');
   }
-
-  // 4. Auto-install from GitHub releases
-  return installBrokerBinary();
 }
 
-// ---------------------------------------------------------------------------
-// HTTP transport client — connects to an already-running broker's HTTP API
-// ---------------------------------------------------------------------------
+// ── Helpers ──────────────────────────────────────────────────────────────
 
-export interface HttpAgentRelayClientOptions {
-  port: number;
-  apiKey?: string;
-}
+/**
+ * Parse the API URL from the broker's stdout. The broker prints:
+ *   [agent-relay] API listening on http://{bind}:{port}
+ * Returns the full URL (e.g. "http://127.0.0.1:3889").
+ */
+async function waitForApiUrl(child: ChildProcess, timeoutMs: number): Promise<string> {
+  const { createInterface } = await import('node:readline');
 
-export interface DiscoverAndConnectOptions {
-  cwd?: string;
-  apiKey?: string;
-  /** Auto-start the broker if not running (default: false). */
-  autoStart?: boolean;
-  /**
-   * Path to the broker binary for auto-start.
-   * If not provided, the SDK resolves it automatically via standard install locations
-   * (~/.agent-relay/bin, bundled platform binary, or Cargo release build).
-   * Only used when `autoStart: true`.
-   */
-  brokerBinaryPath?: string;
-}
-
-const DEFAULT_DASHBOARD_PORT = (() => {
-  const envPort = typeof process !== 'undefined' ? process.env.AGENT_RELAY_DASHBOARD_PORT : undefined;
-  if (envPort) {
-    const parsed = Number.parseInt(envPort, 10);
-    if (Number.isFinite(parsed) && parsed > 0) return parsed;
-  }
-  return 3888;
-})();
-const HTTP_MAX_PORT_SCAN = 25;
-const HTTP_AUTOSTART_TIMEOUT_MS = 10_000;
-const HTTP_AUTOSTART_POLL_MS = 250;
-
-function sanitizeBrokerName(name: string): string {
-  return name.replace(/[^\p{L}\p{N}-]/gu, '-');
-}
-
-function brokerPidFilename(projectRoot: string): string {
-  const brokerName = path.basename(projectRoot) || 'project';
-  return `broker-${sanitizeBrokerName(brokerName)}.pid`;
-}
-
-export class HttpAgentRelayClient {
-  private readonly port: number;
-  private readonly apiKey?: string;
-
-  constructor(options: HttpAgentRelayClientOptions) {
-    this.port = options.port;
-    this.apiKey = options.apiKey;
-  }
-
-  /**
-   * Connect to an already-running broker on the given port.
-   */
-  static async connectHttp(
-    port: number,
-    options?: { apiKey?: string }
-  ): Promise<HttpAgentRelayClient> {
-    const client = new HttpAgentRelayClient({ port, apiKey: options?.apiKey });
-    // Verify connectivity
-    await client.healthCheck();
-    return client;
-  }
-
-  /**
-   * Discover a running broker for the current project and connect to it.
-   * Reads the broker PID file, verifies the process is alive, scans ports
-   * for the HTTP API, and returns a connected client.
-   */
-  static async discoverAndConnect(
-    options?: DiscoverAndConnectOptions
-  ): Promise<HttpAgentRelayClient> {
-    const cwd = options?.cwd ?? process.cwd();
-    const apiKey = options?.apiKey ?? process.env.RELAY_BROKER_API_KEY?.trim();
-    const autoStart = options?.autoStart ?? false;
-    const paths = getProjectPaths(cwd);
-    const preferredApiPort = DEFAULT_DASHBOARD_PORT + 1;
-
-    // Try to find a running broker via PID file
-    const pidFilePath = path.join(paths.dataDir, brokerPidFilename(paths.projectRoot));
-    const legacyPidPath = path.join(paths.dataDir, 'broker.pid');
-    let brokerRunning = false;
-
-    for (const pidPath of [pidFilePath, legacyPidPath]) {
-      if (fs.existsSync(pidPath)) {
-        const pidStr = fs.readFileSync(pidPath, 'utf-8').trim();
-        const pid = Number.parseInt(pidStr, 10);
-        if (Number.isFinite(pid) && pid > 0) {
-          try {
-            process.kill(pid, 0);
-            brokerRunning = true;
-            break;
-          } catch {
-            // Process not running
-          }
-        }
-      }
-    }
-
-    if (brokerRunning) {
-      const port = await HttpAgentRelayClient.scanForBrokerPort(preferredApiPort);
-      if (port !== null) {
-        return new HttpAgentRelayClient({ port, apiKey });
-      }
-      throw new AgentRelayProcessError(
-        'broker is running for this project, but its local API is unavailable'
-      );
+  return new Promise<string>((resolve, reject) => {
+    if (!child.stdout) {
+      reject(new Error('Broker stdout not available'));
+      return;
     }
 
-    if (!autoStart) {
-      throw new AgentRelayProcessError('broker is not running for this project');
-    }
+    let resolved = false;
+    const rl = createInterface({ input: child.stdout });
 
-    // Auto-start the broker using the resolved binary path (not process.argv[1],
-    // which only works from CLI context — breaks when SDK is imported by user apps).
-    // The broker binary requires the `init` subcommand with `--api-port` and
-    // `--persist` so it writes PID files for subsequent discovery.
-    const brokerBinary = options?.brokerBinaryPath ?? resolveDefaultBinaryPath();
-
-    const child = spawn(
-      brokerBinary,
-      ['init', '--persist', '--api-port', String(preferredApiPort)],
-      {
-        cwd: paths.projectRoot,
-        env: process.env,
-        detached: true,
-        stdio: 'ignore',
+    const timer = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        reject(new Error(`Broker did not report API port within ${timeoutMs}ms`));
       }
-    );
-    child.unref();
-
-    const startedAt = Date.now();
-    while (Date.now() - startedAt < HTTP_AUTOSTART_TIMEOUT_MS) {
-      const port = await HttpAgentRelayClient.scanForBrokerPort(preferredApiPort);
-      if (port !== null) {
-        return new HttpAgentRelayClient({ port, apiKey });
+    }, timeoutMs);
+
+    child.on('exit', (code) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        rl.close();
+        reject(new Error(`Broker process exited with code ${code} before becoming ready`));
       }
-      await new Promise((resolve) => setTimeout(resolve, HTTP_AUTOSTART_POLL_MS));
-    }
-
-    throw new AgentRelayProcessError(
-      `broker did not become ready within ${HTTP_AUTOSTART_TIMEOUT_MS}ms`
-    );
-  }
+    });
 
-  private static async scanForBrokerPort(startPort: number): Promise<number | null> {
-    for (let i = 0; i < HTTP_MAX_PORT_SCAN; i++) {
-      const port = startPort + i;
-      try {
-        const res = await fetch(`http://127.0.0.1:${port}/health`);
-        if (!res.ok) continue;
-        const payload = (await res.json().catch(() => null)) as { service?: string } | null;
-        if (payload?.service === 'agent-relay-listen') {
-          return port;
-        }
-      } catch {
-        // Keep scanning
+    child.on('error', (err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timer);
+        rl.close();
+        reject(new Error(`Failed to start broker: ${err.message}`));
       }
-    }
-    return null;
-  }
-
-  private async request<T = unknown>(pathname: string, init?: RequestInit): Promise<T> {
-    const headers = new Headers(init?.headers);
-    if (this.apiKey && !headers.has('x-api-key') && !headers.has('authorization')) {
-      headers.set('x-api-key', this.apiKey);
-    }
-
-    const response = await fetch(`http://127.0.0.1:${this.port}${pathname}`, {
-      ...init,
-      headers,
     });
 
-    const text = await response.text();
-    let payload: unknown;
-    try {
-      payload = text ? JSON.parse(text) : undefined;
-    } catch {
-      payload = text;
-    }
-
-    if (!response.ok) {
-      const msg = HttpAgentRelayClient.extractErrorMessage(response, payload);
-      throw new AgentRelayProcessError(msg);
-    }
-
-    return payload as T;
-  }
-
-  private static extractErrorMessage(response: Response, payload: unknown): string {
-    if (typeof payload === 'string' && payload.trim()) return payload.trim();
-    const p = payload as Record<string, unknown> | undefined;
-    if (typeof p?.error === 'string') return p.error;
-    if (typeof (p?.error as Record<string, unknown>)?.message === 'string')
-      return (p!.error as Record<string, unknown>).message as string;
-    if (typeof p?.message === 'string' && (p.message as string).trim())
-      return (p.message as string).trim();
-    return `${response.status} ${response.statusText}`.trim();
-  }
-
-  async healthCheck(): Promise<{ service: string }> {
-    return this.request<{ service: string }>('/health');
-  }
-
-  /** No-op — broker is already running. */
-  async start(): Promise<void> {}
-
-  /** No-op — don't kill an externally-managed broker. */
-  async shutdown(): Promise<void> {}
+    rl.on('line', (line) => {
+      if (resolved) return;
 
-  async spawnPty(input: SpawnPtyInput): Promise<{ name: string; runtime: AgentRuntime }> {
-    const payload = await this.request<{ name?: string }>('/api/spawn', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        name: input.name,
-        cli: input.cli,
-        model: input.model,
-        args: input.args ?? [],
-        task: input.task,
-        channels: input.channels ?? [],
-        cwd: input.cwd,
-        team: input.team,
-        shadowOf: input.shadowOf,
-        shadowMode: input.shadowMode,
-        continueFrom: input.continueFrom,
-        idleThresholdSecs: input.idleThresholdSecs,
-        restartPolicy: input.restartPolicy,
-        skipRelayPrompt: input.skipRelayPrompt,
-      }),
+      const match = line.match(/API listening on (https?:\/\/[^\s]+)/);
+      if (match) {
+        resolved = true;
+        clearTimeout(timer);
+        rl.close();
+        resolve(match[1]);
+      }
     });
-    return {
-      name: typeof payload?.name === 'string' ? payload.name : input.name,
-      runtime: 'pty',
-    };
-  }
+  });
+}
 
-  async sendMessage(input: SendMessageInput): Promise<{ event_id: string; targets: string[] }> {
-    return this.request<{ event_id: string; targets: string[] }>('/api/send', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        to: input.to,
-        text: input.text,
-        from: input.from,
-        threadId: input.threadId,
-        workspaceId: input.workspaceId,
-        workspaceAlias: input.workspaceAlias,
-        priority: input.priority,
-        data: input.data,
-        mode: input.mode,
-      }),
+function waitForExit(child: ChildProcess, timeoutMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve();
+    }, timeoutMs);
+    child.on('exit', () => {
+      clearTimeout(timer);
+      resolve();
     });
-  }
-
-  async listAgents(): Promise<ListAgent[]> {
-    const payload = await this.request<{ agents?: ListAgent[] }>('/api/spawned', { method: 'GET' });
-    return Array.isArray(payload?.agents) ? payload.agents : [];
-  }
-
-  async release(name: string, reason?: string): Promise<{ name: string }> {
-    const payload = await this.request<{ name?: string }>(
-      `/api/spawned/${encodeURIComponent(name)}`,
-      {
-        method: 'DELETE',
-        ...(reason
-          ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ reason }) }
-          : {}),
-      }
-    );
-    return { name: typeof payload?.name === 'string' ? payload.name : name };
-  }
-
-  async subscribeChannels(_name: string, _channels: string[]): Promise<void> {
-    throw new Error(
-      'subscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
-      'The HTTP API does not support dynamic channel subscription.'
-    );
-  }
-
-  async unsubscribeChannels(_name: string, _channels: string[]): Promise<void> {
-    throw new Error(
-      'unsubscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
-      'The HTTP API does not support dynamic channel unsubscription.'
-    );
-  }
-
-  async setModel(
-    name: string,
-    model: string,
-    opts?: { timeoutMs?: number }
-  ): Promise<{ name: string; model: string; success: boolean }> {
-    const payload = await this.request<{ success?: boolean; model?: string }>(
-      `/api/spawned/${encodeURIComponent(name)}/model`,
-      {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ model, timeoutMs: opts?.timeoutMs }),
-      }
-    );
-    return {
-      name,
-      model: typeof payload?.model === 'string' ? payload.model : model,
-      success: payload?.success !== false,
-    };
-  }
-
-  async getConfig(): Promise<{ workspace_key?: string }> {
-    return this.request<{ workspace_key?: string }>('/api/config');
-  }
+  });
 }