agent-relay 2.3.13 → 2.4.0

package/packages/sdk/src/client.ts

@@ -1,2071 +1,673 @@
-/**
- * RelayClient - Agent Relay SDK Client
- * @agent-relay/sdk
- *
- * Lightweight client for agent-to-agent communication via Agent Relay daemon.
- */
-
-import net from 'node:net';
-import { randomUUID } from 'node:crypto';
-import { discoverSocket } from '@agent-relay/utils/discovery';
-import { DaemonNotRunningError, ConnectionError } from '@agent-relay/utils/errors';
-// Import shared protocol types and framing utilities from @agent-relay/protocol
+import { once } from 'node:events';
+import { 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';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import {
-  type Envelope,
-  type HelloPayload,
-  type WelcomePayload,
-  type SendPayload,
-  type SendMeta,
-  type SendEnvelope,
-  type DeliverEnvelope,
-  type AckPayload,
-  type ErrorPayload,
-  type PayloadKind,
-  type LogPayload,
-  type SpeakOnTrigger,
-  type EntityType,
-  type ChannelMessagePayload,
-  type ChannelJoinEnvelope,
-  type ChannelLeaveEnvelope,
-  type ChannelMessageEnvelope,
-  type MessageAttachment,
-  type SpawnPayload,
-  type SpawnResultPayload,
-  type ReleasePayload,
-  type ReleaseResultPayload,
-  type SendInputPayload,
-  type SendInputResultPayload,
-  type SetModelPayload,
-  type SetModelResultPayload,
-  type SetModelEnvelope,
-  type ListWorkersPayload,
-  type ListWorkersResultPayload,
-  type SpawnEnvelope,
-  type ReleaseEnvelope,
-  type SendInputEnvelope,
-  type ListWorkersEnvelope,
-  type StatusResponsePayload,
-  type InboxPayload,
-  type InboxMessage,
-  type InboxResponsePayload,
-  type MessagesQueryPayload,
-  type MessagesResponsePayload,
-  type ListAgentsPayload,
-  type AgentInfo,
-  type ListAgentsResponsePayload,
-  type ListConnectedAgentsPayload,
-  type ListConnectedAgentsResponsePayload,
-  type RemoveAgentPayload,
-  type RemoveAgentResponsePayload,
-  type HealthPayload,
-  type HealthResponsePayload,
-  type MetricsPayload,
-  type MetricsResponsePayload,
-  type CreateProposalOptions,
-  type VoteOptions,
-  type AgentReadyPayload,
   PROTOCOL_VERSION,
-  encodeFrameLegacy,
-  FrameParser,
-} from '@agent-relay/protocol';
-
-export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
-
-export interface SyncOptions {
-  timeoutMs?: number;
-  kind?: PayloadKind;
-  data?: Record<string, unknown>;
-  thread?: string;
+  type AgentRuntime,
+  type AgentSpec,
+  type BrokerEvent,
+  type BrokerStats,
+  type BrokerStatus,
+  type CrashInsightsResponse,
+  type ProtocolEnvelope,
+  type ProtocolError,
+  type RestartPolicy,
+} from './protocol.js';
+
+export interface AgentRelayClientOptions {
+  binaryPath?: string;
+  binaryArgs?: string[];
+  brokerName?: string;
+  channels?: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  requestTimeoutMs?: number;
+  shutdownTimeoutMs?: number;
+  clientName?: string;
+  clientVersion?: string;
 }
 
-/**
- * Options for the request() method.
- */
-export interface RequestOptions {
-  /** Timeout in milliseconds (default: 30000) */
-  timeout?: number;
-  /** Optional structured data to include with the request */
-  data?: Record<string, unknown>;
-  /** Optional thread identifier for grouping related messages */
-  thread?: string;
-  /** Message kind (default: 'message') */
-  kind?: PayloadKind;
+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;
 }
 
-/**
- * Response from the request() method.
- */
-export interface RequestResponse {
-  /** Sender of the response */
-  from: string;
-  /** Response body text */
-  body: string;
-  /** Optional structured data from the response */
-  data?: Record<string, unknown>;
-  /** The correlation ID used for this request/response */
-  correlationId: string;
-  /** Thread identifier if set */
-  thread?: string;
-  /** The full payload for advanced use cases */
-  payload: SendPayload;
+export interface SpawnHeadlessClaudeInput {
+  name: string;
+  args?: string[];
+  channels?: string[];
+  task?: string;
 }
 
-/**
- * Extended spawn result with optional readiness information.
- * When `waitForReady` is true, the spawn will wait for the agent to complete
- * its HELLO/WELCOME handshake before resolving.
- */
-export interface SpawnResult extends SpawnResultPayload {
-  /** Whether the agent is ready to receive messages (only set when waitForReady is true) */
-  ready?: boolean;
-  /** Agent ready details (only set when waitForReady is true and spawn succeeded) */
-  readyInfo?: AgentReadyPayload;
+export interface SendMessageInput {
+  to: string;
+  text: string;
+  from?: string;
+  threadId?: string;
+  priority?: number;
+  data?: Record<string, unknown>;
 }
 
-export interface ClientConfig {
-  /** Daemon socket path (default: /tmp/agent-relay.sock) */
-  socketPath: string;
-  /** Agent name */
-  agentName: string;
-  /** Entity type: 'agent' (default) or 'user' */
-  entityType?: EntityType;
-  /** CLI identifier (claude, codex, gemini, etc.) */
+export interface ListAgent {
+  name: string;
+  runtime: AgentRuntime;
   cli?: string;
-  /** Program identifier */
-  program?: string;
-  /** Model identifier */
   model?: string;
-  /** Task description */
-  task?: string;
-  /** Working directory */
-  workingDirectory?: string;
-  /** Team name */
   team?: string;
-  /** Display name for human users */
-  displayName?: string;
-  /** Avatar URL for human users */
-  avatarUrl?: string;
-  /** Suppress console logging */
-  quiet?: boolean;
-  /** Auto-reconnect on disconnect */
-  reconnect: boolean;
-  /** Max reconnect attempts */
-  maxReconnectAttempts: number;
-  /** Initial reconnect delay (ms) */
-  reconnectDelayMs: number;
-  /** Max reconnect delay (ms) */
-  reconnectMaxDelayMs: number;
-  /**
-   * Mark this client as a system component.
-   * Allows using reserved agent names (Dashboard, cli, system).
-   * Should only be set by trusted system components.
-   */
-  _isSystemComponent?: boolean;
+  channels: string[];
+  parent?: string;
+  pid?: number;
 }
 
-const DEFAULT_SOCKET_PATH = '/tmp/agent-relay.sock';
-
-/**
- * Resolve the socket path using discovery if not explicitly provided.
- * Falls back to /tmp/agent-relay.sock if discovery fails.
- */
-function resolveSocketPath(configPath?: string): string {
-  if (configPath) return configPath;
-  const discovery = discoverSocket();
-  return discovery?.socketPath || DEFAULT_SOCKET_PATH;
+interface PendingRequest {
+  expectedType: 'ok' | 'hello_ack';
+  resolve: (value: ProtocolEnvelope<unknown>) => void;
+  reject: (error: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
 }
 
-const DEFAULT_CLIENT_CONFIG: ClientConfig = {
-  socketPath: DEFAULT_SOCKET_PATH,
-  agentName: 'agent',
-  cli: undefined,
-  quiet: false,
-  reconnect: true,
-  maxReconnectAttempts: 10,
-  reconnectDelayMs: 1000, // Increased from 100ms to prevent reconnect storms
-  reconnectMaxDelayMs: 30000,
-};
-
-// Simple ID generator
-let idCounter = 0;
-function generateId(): string {
-  return `${Date.now().toString(36)}-${(++idCounter).toString(36)}`;
+interface ParsedEnvelope {
+  v: number;
+  type: string;
+  request_id?: string;
+  payload: unknown;
 }
 
-/**
- * Circular buffer for O(1) deduplication with bounded memory.
- */
-class CircularDedupeCache {
-  private ids: Set<string> = new Set();
-  private ring: string[];
-  private head = 0;
-  private readonly capacity: number;
-
-  constructor(capacity = 2000) {
-    this.capacity = capacity;
-    this.ring = new Array(capacity);
-  }
-
-  check(id: string): boolean {
-    if (this.ids.has(id)) return true;
-
-    if (this.ids.size >= this.capacity) {
-      const oldest = this.ring[this.head];
-      if (oldest) this.ids.delete(oldest);
-    }
+export class AgentRelayProtocolError extends Error {
+  code: string;
+  retryable: boolean;
+  data?: unknown;
 
-    this.ring[this.head] = id;
-    this.ids.add(id);
-    this.head = (this.head + 1) % this.capacity;
-
-    return false;
-  }
-
-  clear(): void {
-    this.ids.clear();
-    this.ring = new Array(this.capacity);
-    this.head = 0;
+  constructor(payload: ProtocolError) {
+    super(payload.message);
+    this.name = 'AgentRelayProtocolError';
+    this.code = payload.code;
+    this.retryable = payload.retryable;
+    this.data = payload.data;
   }
 }
 
-/**
- * RelayClient for agent-to-agent communication.
- */
-export class RelayClient {
-  private config: ClientConfig;
-  private socket?: net.Socket;
-  private parser: FrameParser;
-
-  private _state: ClientState = 'DISCONNECTED';
-  private sessionId?: string;
-  private resumeToken?: string;
-  private reconnectAttempts = 0;
-  private reconnectDelay: number;
-  private reconnectTimer?: NodeJS.Timeout;
-  private _destroyed = false;
-
-  private dedupeCache = new CircularDedupeCache(2000);
-  private writeQueue: Buffer[] = [];
-  private writeScheduled = false;
-
-  private pendingSyncAcks: Map<string, {
-    resolve: (ack: AckPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingSpawns: Map<string, {
-    resolve: (result: SpawnResultPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingReleases: Map<string, {
-    resolve: (result: ReleaseResultPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingSendInputs: Map<string, {
-    resolve: (result: SendInputResultPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingSetModels: Map<string, {
-    resolve: (result: SetModelResultPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingListWorkers: Map<string, {
-    resolve: (result: ListWorkersResultPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingQueries: Map<string, {
-    resolve: (payload: unknown) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  private pendingRequests: Map<string, {
-    resolve: (response: RequestResponse) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-    targetAgent: string;
-  }> = new Map();
-
-  private pendingAgentReady: Map<string, {
-    resolve: (info: AgentReadyPayload) => void;
-    reject: (err: Error) => void;
-    timeoutHandle: NodeJS.Timeout;
-  }> = new Map();
-
-  // Event handlers
-  onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
-  /**
-   * Callback for channel messages.
-   */
-  onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
-  onStateChange?: (state: ClientState) => void;
-  onError?: (error: Error) => void;
-  /**
-   * Callback when an agent becomes ready (completes HELLO/WELCOME handshake).
-   * This is broadcast by the daemon when any agent connects.
-   * Useful for knowing when a spawned agent is ready to receive messages.
-   */
-  onAgentReady?: (info: AgentReadyPayload) => void;
-
-  constructor(config: Partial<ClientConfig> = {}) {
-    this.config = { ...DEFAULT_CLIENT_CONFIG, ...config };
-    // Use socket discovery if no explicit socketPath was provided
-    if (!config.socketPath) {
-      this.config.socketPath = resolveSocketPath();
-    }
-    this.parser = new FrameParser();
-    this.parser.setLegacyMode(true);
-    this.reconnectDelay = this.config.reconnectDelayMs;
+export class AgentRelayProcessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentRelayProcessError';
   }
+}
 
-  get state(): ClientState {
-    return this._state;
+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;
+
+  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',
+    };
   }
 
-  get agentName(): string {
-    return this.config.agentName;
+  static async start(options: AgentRelayClientOptions = {}): Promise<AgentRelayClient> {
+    const client = new AgentRelayClient(options);
+    await client.start();
+    return client;
   }
 
-  get currentSessionId(): string | undefined {
-    return this.sessionId;
+  onEvent(listener: (event: BrokerEvent) => void): () => void {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
   }
 
-  /**
-   * Connect to the relay daemon.
-   */
-  connect(): Promise<void> {
-    if (this._state !== 'DISCONNECTED' && this._state !== 'BACKOFF') {
-      return Promise.resolve();
+  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);
     }
-
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const settleResolve = (): void => {
-        if (settled) return;
-        settled = true;
-        resolve();
-      };
-      const settleReject = (err: Error): void => {
-        if (settled) return;
-        settled = true;
-        reject(err);
-      };
-
-      this.setState('CONNECTING');
-
-      this.socket = net.createConnection(this.config.socketPath, () => {
-        this.setState('HANDSHAKING');
-        this.sendHello();
-      });
-
-      this.socket.on('data', (data) => this.handleData(data));
-
-      this.socket.on('close', () => {
-        this.handleDisconnect();
-      });
-
-      this.socket.on('error', (err) => {
-        if (this._state === 'CONNECTING') {
-          const errno = (err as NodeJS.ErrnoException).code;
-          if (errno === 'ECONNREFUSED' || errno === 'ENOENT') {
-            settleReject(new DaemonNotRunningError(`Cannot connect to daemon at ${this.config.socketPath}`));
-          } else {
-            settleReject(new ConnectionError(err.message));
-          }
-        }
-        this.handleError(err);
-      });
-
-      const checkReady = setInterval(() => {
-        if (this._state === 'READY') {
-          clearInterval(checkReady);
-          clearTimeout(timeout);
-          settleResolve();
-        }
-      }, 10);
-
-      const timeout = setTimeout(() => {
-        if (this._state !== 'READY') {
-          clearInterval(checkReady);
-          this.socket?.destroy();
-          settleReject(new Error('Connection timeout'));
-        }
-      }, 5000);
-    });
-  }
-
-  /**
-   * Disconnect from the relay daemon.
-   */
-  disconnect(): void {
-    if (this.reconnectTimer) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = undefined;
+    if (filter?.name) {
+      events = events.filter((event) => 'name' in event && event.name === filter.name);
     }
-
-    if (this.socket) {
-      this.send({
-        v: PROTOCOL_VERSION,
-        type: 'BYE',
-        id: generateId(),
-        ts: Date.now(),
-        payload: {},
-      });
-      this.socket.end();
-      this.socket = undefined;
+    const since = filter?.since;
+    if (since !== undefined) {
+      events = events.filter(
+        (event) => 'timestamp' in event && typeof event.timestamp === 'number' && event.timestamp >= since
+      );
     }
-
-    this.setState('DISCONNECTED');
-  }
-
-  /**
-   * Permanently destroy the client.
-   */
-  destroy(): void {
-    this._destroyed = true;
-    this.disconnect();
-  }
-
-  /**
-   * Send a message to another agent.
-   */
-  sendMessage(
-    to: string,
-    body: string,
-    kind: PayloadKind = 'message',
-    data?: Record<string, unknown>,
-    thread?: string,
-    meta?: SendMeta
-  ): boolean {
-    if (this._state !== 'READY') {
-      return false;
+    const limit = filter?.limit;
+    if (limit !== undefined) {
+      events = events.slice(-limit);
     }
-
-    const envelope: SendEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'SEND',
-      id: generateId(),
-      ts: Date.now(),
-      to,
-      payload: {
-        kind,
-        body,
-        data,
-        thread,
-      },
-      payload_meta: meta,
-    };
-
-    return this.send(envelope);
+    return events;
   }
 
-  /**
-   * Send an ACK for a delivered message.
-   */
-  sendAck(payload: AckPayload): boolean {
-    if (this._state !== 'READY') {
-      return false;
+  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;
+      }
     }
+    return undefined;
+  }
 
-    const envelope: Envelope<AckPayload> = {
-      v: PROTOCOL_VERSION,
-      type: 'ACK',
-      id: generateId(),
-      ts: Date.now(),
-      payload,
+  onBrokerStderr(listener: (line: string) => void): () => void {
+    this.stderrListeners.add(listener);
+    return () => {
+      this.stderrListeners.delete(listener);
     };
-
-    return this.send(envelope);
   }
 
-  /**
-   * Send a message and wait for ACK response.
-   */
-  async sendAndWait(to: string, body: string, options: SyncOptions = {}): Promise<AckPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
+  async start(): Promise<void> {
+    if (this.child) {
+      return;
     }
-
-    const correlationId = randomUUID();
-    const timeoutMs = options.timeoutMs ?? 30000;
-    const kind = options.kind ?? 'message';
-
-    return new Promise<AckPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingSyncAcks.delete(correlationId);
-        reject(new Error(`ACK timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingSyncAcks.set(correlationId, { resolve, reject, timeoutHandle });
-
-      const envelope: SendEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'SEND',
-        id: generateId(),
-        ts: Date.now(),
-        to,
-        payload: {
-          kind,
-          body,
-          data: options.data,
-          thread: options.thread,
-        },
-        payload_meta: {
-          sync: {
-            correlationId,
-            timeoutMs,
-            blocking: true,
-          },
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingSyncAcks.delete(correlationId);
-        reject(new Error('Failed to send message'));
-      }
-    });
-  }
-
-  /**
-   * Send a request to another agent and wait for their response.
-   *
-   * This implements a request/response pattern where the message is sent with
-   * a correlation ID, and the method waits for the target agent to respond
-   * with a message containing that correlation ID.
-   *
-   * @example
-   * ```typescript
-   * // Simple request
-   * const response = await client.request('Worker', 'Process this task');
-   * console.log(response.body); // Worker's response
-   *
-   * // With options
-   * const response = await client.request('Worker', 'Process task', {
-   *   timeout: 60000,
-   *   data: { taskId: '123', priority: 'high' },
-   *   thread: 'task-thread-1',
-   * });
-   * ```
-   *
-   * @param to - Target agent name
-   * @param body - Request message body
-   * @param options - Request options (timeout, data, thread, kind)
-   * @returns Promise that resolves with the response from the target agent
-   * @throws Error if client is not ready, send fails, timeout occurs, or agent disconnects
-   */
-  async request(to: string, body: string, options: RequestOptions = {}): Promise<RequestResponse> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
+    if (this.startingPromise) {
+      return this.startingPromise;
     }
 
-    const correlationId = randomUUID();
-    const timeoutMs = options.timeout ?? 30000;
-    const kind = options.kind ?? 'message';
-
-    return new Promise<RequestResponse>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingRequests.delete(correlationId);
-        reject(new Error(`Request timeout after ${timeoutMs}ms waiting for response from ${to}`));
-      }, timeoutMs);
-
-      this.pendingRequests.set(correlationId, {
-        resolve,
-        reject,
-        timeoutHandle,
-        targetAgent: to,
-      });
-
-      const envelope: SendEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'SEND',
-        id: generateId(),
-        ts: Date.now(),
-        to,
-        payload: {
-          kind,
-          body,
-          data: {
-            ...options.data,
-            _correlationId: correlationId,
-          },
-          thread: options.thread,
-        },
-        payload_meta: {
-          replyTo: correlationId,
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingRequests.delete(correlationId);
-        reject(new Error('Failed to send request'));
-      }
+    this.startingPromise = this.startInternal();
+    try {
+      await this.startingPromise;
+    } finally {
+      this.startingPromise = undefined;
+    }
+  }
+
+  /**
+   * 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 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 } : {}),
     });
-  }
-
-  /**
-   * Respond to a request from another agent.
-   *
-   * This is a convenience method for responding to messages that have a
-   * correlation ID. The response will be routed back to the requesting agent.
-   *
-   * @param correlationId - The correlation ID from the original request (from data._correlationId or meta.replyTo)
-   * @param to - Target agent (the one who sent the original request)
-   * @param body - Response body
-   * @param data - Optional structured data to include in the response
-   * @returns true if the message was sent
-   */
-  respond(correlationId: string, to: string, body: string, data?: Record<string, unknown>): boolean {
-    if (this._state !== 'READY') {
-      return false;
-    }
-
-    const envelope: SendEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'SEND',
-      id: generateId(),
-      ts: Date.now(),
-      to,
-      payload: {
-        kind: 'message',
-        body,
-        data: {
-          ...data,
-          _correlationId: correlationId,
-          _isResponse: true,
-        },
-      },
-      payload_meta: {
-        replyTo: correlationId,
-      },
+    return result;
+  }
+
+  async spawnHeadlessClaude(
+    input: SpawnHeadlessClaudeInput
+  ): Promise<{ name: string; runtime: AgentRuntime }> {
+    await this.start();
+    const agent: AgentSpec = {
+      name: input.name,
+      runtime: 'headless_claude',
+      args: input.args ?? [],
+      channels: input.channels ?? [],
     };
-
-    return this.send(envelope);
-  }
-
-  /**
-   * Broadcast a message to all agents.
-   */
-  broadcast(body: string, kind: PayloadKind = 'message', data?: Record<string, unknown>): boolean {
-    return this.sendMessage('*', body, kind, data);
-  }
-
-  /**
-   * Subscribe to a topic.
-   */
-  subscribe(topic: string): boolean {
-    if (this._state !== 'READY') return false;
-
-    return this.send({
-      v: PROTOCOL_VERSION,
-      type: 'SUBSCRIBE',
-      id: generateId(),
-      ts: Date.now(),
-      topic,
-      payload: {},
+    const result = await this.requestOk<{ name: string; runtime: AgentRuntime }>('spawn_agent', {
+      agent,
+      ...(input.task != null ? { initial_task: input.task } : {}),
     });
+    return result;
   }
 
-  /**
-   * Unsubscribe from a topic.
-   */
-  unsubscribe(topic: string): boolean {
-    if (this._state !== 'READY') return false;
-
-    return this.send({
-      v: PROTOCOL_VERSION,
-      type: 'UNSUBSCRIBE',
-      id: generateId(),
-      ts: Date.now(),
-      topic,
-      payload: {},
-    });
+  async release(name: string, reason?: string): Promise<{ name: string }> {
+    await this.start();
+    return this.requestOk<{ name: string }>('release_agent', { name, reason });
   }
 
-  /**
-   * Bind as a shadow to a primary agent.
-   */
-  bindAsShadow(
-    primaryAgent: string,
-    options: {
-      speakOn?: SpeakOnTrigger[];
-      receiveIncoming?: boolean;
-      receiveOutgoing?: boolean;
-    } = {}
-  ): boolean {
-    if (this._state !== 'READY') return false;
-
-    return this.send({
-      v: PROTOCOL_VERSION,
-      type: 'SHADOW_BIND',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        primaryAgent,
-        speakOn: options.speakOn,
-        receiveIncoming: options.receiveIncoming,
-        receiveOutgoing: options.receiveOutgoing,
-      },
-    });
+  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 });
   }
 
-  /**
-   * Unbind from a primary agent.
-   */
-  unbindAsShadow(primaryAgent: string): boolean {
-    if (this._state !== 'READY') return false;
-
-    return this.send({
-      v: PROTOCOL_VERSION,
-      type: 'SHADOW_UNBIND',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        primaryAgent,
-      },
+  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,
     });
   }
 
-  /**
-   * Send log output to the daemon for dashboard streaming.
-   */
-  sendLog(data: string): boolean {
-    if (this._state !== 'READY') {
-      return false;
-    }
-
-    const envelope: Envelope<LogPayload> = {
-      v: PROTOCOL_VERSION,
-      type: 'LOG',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        data,
-        timestamp: Date.now(),
-      },
-    };
-
-    return this.send(envelope);
+  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 });
   }
 
-  // =============================================================================
-  // Spawn/Release Operations
-  // =============================================================================
-
-  /**
-   * Spawn a new agent via the relay daemon.
-   * @param options - Spawn options
-   * @param options.name - Name for the new agent
-   * @param options.cli - CLI to use (claude, codex, gemini, etc.)
-   * @param options.task - Task description
-   * @param options.cwd - Working directory
-   * @param options.team - Team name
-   * @param options.interactive - Interactive mode
-   * @param options.shadowMode - Shadow execution mode ('subagent' or 'process')
-   * @param options.shadowOf - Spawn as shadow of this agent
-   * @param options.shadowAgent - Shadow agent profile to use (for subagent mode)
-   * @param options.shadowTriggers - When to trigger the shadow (for subagent mode)
-   * @param options.shadowSpeakOn - Shadow speak-on triggers
-   * @param options.waitForReady - Wait for the agent to be ready before resolving (default: false)
-   * @param options.readyTimeoutMs - Timeout for agent to become ready (default: 60000ms)
-   * @param timeoutMs - Timeout for spawn operation (default: 60000ms)
-   * @returns Spawn result. When waitForReady is true, includes `ready` and `readyInfo` fields.
-   */
-  async spawn(
-    options: {
-      name: string;
-      cli: string;
-      task?: string;
-      cwd?: string;
-      team?: string;
-      /** Model override (e.g., 'opus', 'sonnet', 'haiku'). Takes precedence over agent profile. */
-      model?: string;
-      interactive?: boolean;
-      shadowMode?: 'subagent' | 'process';
-      shadowOf?: string;
-      shadowAgent?: string;
-      shadowTriggers?: SpeakOnTrigger[];
-      shadowSpeakOn?: SpeakOnTrigger[];
-      /** User ID for cloud persistence */
-      userId?: string;
-      /** Include ACK/DONE workflow conventions in agent instructions */
-      includeWorkflowConventions?: boolean;
-      /** Override the spawner name (defaults to this client's agentName) */
-      spawnerName?: string;
-      /** Wait for the agent to complete connection before resolving */
-      waitForReady?: boolean;
-      /** Timeout for agent to become ready (default: 60000ms). Only used when waitForReady is true. */
-      readyTimeoutMs?: number;
-    },
-    timeoutMs = 60000
-  ): Promise<SpawnResult> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
-    }
-
-    const envelopeId = generateId();
-    const waitForReady = options.waitForReady ?? false;
-    const readyTimeoutMs = options.readyTimeoutMs ?? 60000;
-
-    // If waitForReady, set up the agent ready listener BEFORE spawning
-    // This ensures we don't miss the AGENT_READY event if it arrives quickly
-    let readyPromise: Promise<AgentReadyPayload> | undefined;
-    if (waitForReady) {
-      // Check if we're already waiting for this agent (prevents overwriting existing waiter)
-      if (this.pendingAgentReady.has(options.name)) {
-        throw new Error(`Already waiting for agent ${options.name} to be ready`);
-      }
-
-      readyPromise = new Promise<AgentReadyPayload>((resolve, reject) => {
-        const timeoutHandle = setTimeout(() => {
-          this.pendingAgentReady.delete(options.name);
-          reject(new Error(`Agent ${options.name} did not become ready within ${readyTimeoutMs}ms`));
-        }, readyTimeoutMs);
+  async getCrashInsights(): Promise<CrashInsightsResponse> {
+    await this.start();
+    return this.requestOk<CrashInsightsResponse>('get_crash_insights', {});
+  }
 
-        this.pendingAgentReady.set(options.name, { resolve, reject, timeoutHandle });
+  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,
+        priority: input.priority,
+        data: input.data,
       });
-    }
-
-    // Send the spawn request
-    const spawnResult = await new Promise<SpawnResultPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingSpawns.delete(envelopeId);
-        // Also clean up pending agent ready if spawn times out
-        if (waitForReady) {
-          const pending = this.pendingAgentReady.get(options.name);
-          if (pending) {
-            clearTimeout(pending.timeoutHandle);
-            this.pendingAgentReady.delete(options.name);
-          }
-        }
-        reject(new Error(`Spawn timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingSpawns.set(envelopeId, { resolve, reject, timeoutHandle });
-
-      const envelope: SpawnEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'SPAWN',
-        id: envelopeId,
-        ts: Date.now(),
-        payload: {
-          name: options.name,
-          cli: options.cli,
-          task: options.task || '',
-          cwd: options.cwd,
-          team: options.team,
-          model: options.model,
-          interactive: options.interactive,
-          shadowMode: options.shadowMode,
-          shadowOf: options.shadowOf,
-          shadowAgent: options.shadowAgent,
-          shadowTriggers: options.shadowTriggers,
-          shadowSpeakOn: options.shadowSpeakOn,
-          userId: options.userId,
-          includeWorkflowConventions: options.includeWorkflowConventions,
-          spawnerName: options.spawnerName || this.config.agentName,
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingSpawns.delete(envelopeId);
-        // Also clean up pending agent ready if send fails
-        if (waitForReady) {
-          const pending = this.pendingAgentReady.get(options.name);
-          if (pending) {
-            clearTimeout(pending.timeoutHandle);
-            this.pendingAgentReady.delete(options.name);
-          }
-        }
-        reject(new Error('Failed to send spawn message'));
-      }
-    });
-
-    // If spawn failed or we don't need to wait for ready, return immediately
-    if (!spawnResult.success || !waitForReady || !readyPromise) {
-      // Clean up pending agent ready if spawn failed
-      if (!spawnResult.success && waitForReady) {
-        const pending = this.pendingAgentReady.get(options.name);
-        if (pending) {
-          clearTimeout(pending.timeoutHandle);
-          this.pendingAgentReady.delete(options.name);
-        }
+    } catch (error) {
+      if (error instanceof AgentRelayProtocolError && error.code === 'unsupported_operation') {
+        return { event_id: 'unsupported_operation', targets: [] };
       }
-      return spawnResult;
-    }
-
-    // Wait for the agent to become ready
-    try {
-      const readyInfo = await readyPromise;
-      return {
-        ...spawnResult,
-        ready: true,
-        readyInfo,
-      };
-    } catch (err) {
-      // Agent spawned but didn't become ready in time
-      // Return the spawn result with ready: false
-      return {
-        ...spawnResult,
-        ready: false,
-      };
+      throw error;
     }
   }
 
-  /**
-   * Wait for an agent to become ready (complete HELLO/WELCOME handshake).
-   * This is useful when you want to wait for an agent that was spawned through
-   * another mechanism, or to verify an agent is connected before sending messages.
-   *
-   * @example
-   * ```typescript
-   * // Wait for an agent that might be spawning
-   * try {
-   *   const readyInfo = await client.waitForAgentReady('Worker', 30000);
-   *   console.log(`Worker is ready: ${readyInfo.cli}`);
-   * } catch (err) {
-   *   console.error('Worker did not become ready in time');
-   * }
-   * ```
-   *
-   * @param name - Agent name to wait for
-   * @param timeoutMs - Timeout in milliseconds (default: 60000ms)
-   * @returns Promise that resolves with AgentReadyPayload when the agent connects
-   * @throws Error if the agent doesn't become ready within the timeout
-   */
-  async waitForAgentReady(name: string, timeoutMs = 60000): Promise<AgentReadyPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
-    }
-
-    // Check if we're already waiting for this agent
-    if (this.pendingAgentReady.has(name)) {
-      throw new Error(`Already waiting for agent ${name} to be ready`);
-    }
-
-    return new Promise<AgentReadyPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingAgentReady.delete(name);
-        reject(new Error(`Agent ${name} did not become ready within ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingAgentReady.set(name, { resolve, reject, timeoutHandle });
-    });
+  async listAgents(): Promise<ListAgent[]> {
+    await this.start();
+    const result = await this.requestOk<{ agents: ListAgent[] }>('list_agents', {});
+    return result.agents;
   }
 
-  /**
-   * Release (terminate) an agent via the relay daemon.
-   * @param name - Agent name to release
-   * @param timeoutMs - Timeout for release operation (default: 10000ms)
-   */
-  async release(name: string, reason?: string, timeoutMs = 10000): Promise<ReleaseResultPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
-    }
-
-    const envelopeId = generateId();
-
-    return new Promise<ReleaseResultPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingReleases.delete(envelopeId);
-        reject(new Error(`Release timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingReleases.set(envelopeId, { resolve, reject, timeoutHandle });
-
-      const envelope: ReleaseEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'RELEASE',
-        id: envelopeId,
-        ts: Date.now(),
-        payload: {
-          name,
-          reason,
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingReleases.delete(envelopeId);
-        reject(new Error('Failed to send release message'));
-      }
-    });
+  async getStatus(): Promise<BrokerStatus> {
+    await this.start();
+    return this.requestOk<BrokerStatus>('get_status', {});
   }
 
-  /**
-   * Send input data to a spawned agent's PTY.
-   * @param name - Agent name to send input to
-   * @param data - Input data to send
-   * @param timeoutMs - Timeout for the operation (default: 10000ms)
-   */
-  async sendWorkerInput(name: string, data: string, timeoutMs = 10000): Promise<SendInputResultPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
+  async shutdown(): Promise<void> {
+    if (!this.child) {
+      return;
     }
 
-    const envelopeId = generateId();
-
-    return new Promise<SendInputResultPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingSendInputs.delete(envelopeId);
-        reject(new Error(`Send input timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingSendInputs.set(envelopeId, { resolve, reject, timeoutHandle });
-
-      const envelope: SendInputEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'SEND_INPUT',
-        id: envelopeId,
-        ts: Date.now(),
-        payload: {
-          name,
-          data,
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingSendInputs.delete(envelopeId);
-        reject(new Error('Failed to send input message'));
-      }
-    });
-  }
-
-  /**
-   * Change the model of a running spawned agent.
-   * The command waits for the agent to be idle before sending the model switch command.
-   *
-   * @param name - Agent name to switch model for
-   * @param model - Target model (e.g., 'opus', 'sonnet', 'haiku')
-   * @param options - Options including idle wait timeout
-   * @param operationTimeoutMs - Timeout for the overall protocol operation (default: 45000ms)
-   */
-  async setWorkerModel(
-    name: string,
-    model: string,
-    options?: { timeoutMs?: number },
-    operationTimeoutMs = 45000,
-  ): Promise<SetModelResultPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
+    try {
+      await this.requestOk('shutdown', {});
+    } catch {
+      // Continue shutdown path if broker is already unhealthy.
     }
 
-    const envelopeId = generateId();
-
-    return new Promise<SetModelResultPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingSetModels.delete(envelopeId);
-        reject(new Error(`Set model timeout after ${operationTimeoutMs}ms`));
-      }, operationTimeoutMs);
-
-      this.pendingSetModels.set(envelopeId, { resolve, reject, timeoutHandle });
-
-      const envelope: SetModelEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'SET_MODEL',
-        id: envelopeId,
-        ts: Date.now(),
-        payload: {
-          name,
-          model,
-          timeoutMs: options?.timeoutMs,
-        },
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingSetModels.delete(envelopeId);
-        reject(new Error('Failed to send set model message'));
+    const child = this.child;
+    const wait = this.exitPromise ?? Promise.resolve();
+    const timeout = setTimeout(() => {
+      if (!child.killed) {
+        child.kill('SIGTERM');
       }
-    });
-  }
+    }, this.options.shutdownTimeoutMs);
 
-  /**
-   * List active spawned workers.
-   * @param timeoutMs - Timeout for the operation (default: 10000ms)
-   */
-  async listWorkers(timeoutMs = 10000): Promise<ListWorkersResultPayload> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
-    }
-
-    const envelopeId = generateId();
-
-    return new Promise<ListWorkersResultPayload>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingListWorkers.delete(envelopeId);
-        reject(new Error(`List workers timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      this.pendingListWorkers.set(envelopeId, { resolve, reject, timeoutHandle });
-
-      const envelope: ListWorkersEnvelope = {
-        v: PROTOCOL_VERSION,
-        type: 'LIST_WORKERS',
-        id: envelopeId,
-        ts: Date.now(),
-        payload: {},
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingListWorkers.delete(envelopeId);
-        reject(new Error('Failed to send list workers message'));
+    try {
+      await wait;
+    } finally {
+      clearTimeout(timeout);
+      if (this.child) {
+        this.child.kill('SIGKILL');
       }
-    });
-  }
-
-  // =============================================================================
-  // Channel Operations
-  // =============================================================================
-
-  /**
-   * Join a channel.
-   * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
-   * @param displayName - Optional display name for this member
-   */
-  joinChannel(channel: string, displayName?: string): boolean {
-    if (this._state !== 'READY') {
-      return false;
-    }
-
-    const envelope: ChannelJoinEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'CHANNEL_JOIN',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        channel,
-        displayName,
-      },
-    };
-
-    return this.send(envelope);
-  }
-
-  /**
-   * Admin join: Add any member to a channel (does not require member to be connected).
-   * @param channel - Channel name
-   * @param member - Name of the member to add
-   */
-  adminJoinChannel(channel: string, member: string): boolean {
-    if (this._state !== 'READY') {
-      return false;
-    }
-
-    const envelope: ChannelJoinEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'CHANNEL_JOIN',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        channel,
-        member,
-      },
-    };
-
-    return this.send(envelope);
-  }
-
-  /**
-   * Leave a channel.
-   * @param channel - Channel name to leave
-   * @param reason - Optional reason for leaving
-   */
-  leaveChannel(channel: string, reason?: string): boolean {
-    if (this._state !== 'READY') return false;
-
-    const envelope: ChannelLeaveEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'CHANNEL_LEAVE',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        channel,
-        reason,
-      },
-    };
-
-    return this.send(envelope);
-  }
-
-  /**
-   * Admin remove: Remove any member from a channel.
-   * @param channel - Channel name
-   * @param member - Name of the member to remove
-   */
-  adminRemoveMember(channel: string, member: string): boolean {
-    if (this._state !== 'READY') {
-      return false;
     }
-
-    const envelope: ChannelLeaveEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'CHANNEL_LEAVE',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        channel,
-        member,
-      },
-    };
-
-    return this.send(envelope);
   }
 
-  /**
-   * Send a message to a channel.
-   * @param channel - Channel name
-   * @param body - Message content
-   * @param options - Optional thread, mentions, attachments
-   */
-  sendChannelMessage(
-    channel: string,
-    body: string,
-    options?: {
-      thread?: string;
-      mentions?: string[];
-      attachments?: MessageAttachment[];
-      data?: Record<string, unknown>;
-    }
-  ): boolean {
-    if (this._state !== 'READY') {
-      return false;
+  async waitForExit(): Promise<void> {
+    if (!this.child) {
+      return;
     }
-
-    const envelope: ChannelMessageEnvelope = {
-      v: PROTOCOL_VERSION,
-      type: 'CHANNEL_MESSAGE',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        channel,
-        body,
-        thread: options?.thread,
-        mentions: options?.mentions,
-        attachments: options?.attachments,
-        data: options?.data,
-      },
-    };
-
-    return this.send(envelope);
+    await this.exitPromise;
   }
 
-  // =============================================================================
-  // Consensus Operations
-  // =============================================================================
-
-  /**
-   * Create a consensus proposal.
-   *
-   * The proposal will be broadcast to all participants. They can vote using
-   * the `vote()` method. Results are delivered via `onMessage` callback.
-   *
-   * @example
-   * ```typescript
-   * client.createProposal({
-   *   title: 'Approve API design',
-   *   description: 'Should we proceed with the REST API design?',
-   *   participants: ['Developer', 'Reviewer', 'Lead'],
-   *   consensusType: 'majority',
-   * });
-   * ```
-   *
-   * @param options - Proposal options
-   * @returns true if the message was sent
-   */
-  createProposal(options: CreateProposalOptions): boolean {
-    if (this._state !== 'READY') {
-      return false;
+  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;
 
-    // Build the PROPOSE command message
-    const lines: string[] = [
-      `PROPOSE: ${options.title}`,
-      `TYPE: ${options.consensusType ?? 'majority'}`,
-      `PARTICIPANTS: ${options.participants.join(', ')}`,
-      `DESCRIPTION: ${options.description}`,
+    const args = [
+      'init',
+      '--name',
+      this.options.brokerName,
+      '--channels',
+      this.options.channels.join(','),
+      ...this.options.binaryArgs,
     ];
 
-    if (options.timeoutMs !== undefined) {
-      lines.push(`TIMEOUT: ${options.timeoutMs}`);
-    }
-    if (options.quorum !== undefined) {
-      lines.push(`QUORUM: ${options.quorum}`);
-    }
-    if (options.threshold !== undefined) {
-      lines.push(`THRESHOLD: ${options.threshold}`);
-    }
-
-    const body = lines.join('\n');
-
-    // Send to the special _consensus recipient
-    return this.sendMessage('_consensus', body, 'action');
-  }
-
-  /**
-   * Vote on a consensus proposal.
-   *
-   * @example
-   * ```typescript
-   * // Approve with a reason
-   * client.vote({
-   *   proposalId: 'prop_123',
-   *   value: 'approve',
-   *   reason: 'Looks good to me',
-   * });
-   *
-   * // Reject without reason
-   * client.vote({ proposalId: 'prop_123', value: 'reject' });
-   * ```
-   *
-   * @param options - Vote options
-   * @returns true if the message was sent
-   */
-  vote(options: VoteOptions): boolean {
-    if (this._state !== 'READY') {
-      return false;
-    }
-
-    // Build the VOTE command
-    let body = `VOTE ${options.proposalId} ${options.value}`;
-    if (options.reason) {
-      body += ` ${options.reason}`;
-    }
-
-    // Send to the special _consensus recipient
-    return this.sendMessage('_consensus', body, 'action');
-  }
-
-  // =============================================================================
-  // Query Operations
-  // =============================================================================
-
-  /**
-   * Send a query to the daemon and wait for a response.
-   * @internal
-   */
-  private async query<T>(type: string, payload: unknown, timeoutMs = 5000): Promise<T> {
-    if (this._state !== 'READY') {
-      throw new Error('Client not ready');
+    // Ensure the SDK bin directory (containing agent-relay-broker + relay_send) is on
+    // PATH so spawned workers can find relay_send 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}`;
+      }
     }
 
-    const envelopeId = generateId();
+    console.log(`[broker] Starting: ${resolvedBinary} ${args.join(' ')}`);
+    const child = spawn(resolvedBinary, args, {
+      cwd: this.options.cwd,
+      env,
+      stdio: 'pipe',
+    });
 
-    return new Promise<T>((resolve, reject) => {
-      const timeoutHandle = setTimeout(() => {
-        this.pendingQueries.delete(envelopeId);
-        reject(new Error(`Query timeout after ${timeoutMs}ms`));
-      }, timeoutMs);
+    this.child = child;
+    this.stdoutRl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    this.stderrRl = createInterface({ input: child.stderr, crlfDelay: Infinity });
 
-      this.pendingQueries.set(envelopeId, {
-        resolve: resolve as (p: unknown) => void,
-        reject,
-        timeoutHandle,
-      });
+    this.stdoutRl.on('line', (line) => {
+      this.handleStdoutLine(line);
+    });
 
-      const envelope: Envelope = {
-        v: PROTOCOL_VERSION,
-        type: type as Envelope['type'],
-        id: envelopeId,
-        ts: Date.now(),
-        payload,
-      };
-
-      const sent = this.send(envelope);
-      if (!sent) {
-        clearTimeout(timeoutHandle);
-        this.pendingQueries.delete(envelopeId);
-        reject(new Error(`Failed to send ${type} query`));
+    this.stderrRl.on('line', (line) => {
+      const trimmed = line.trim();
+      if (trimmed) {
+        this.lastStderrLine = trimmed;
+      }
+      for (const listener of this.stderrListeners) {
+        listener(line);
       }
     });
-  }
-
-  /**
-   * Get daemon status information.
-   * @returns Daemon status including version, uptime, and counts
-   */
-  async getStatus(): Promise<StatusResponsePayload> {
-    return this.query<StatusResponsePayload>('STATUS', {});
-  }
 
-  /**
-   * Get messages from the inbox.
-   * @param options - Filter options
-   * @param options.limit - Maximum number of messages to return
-   * @param options.unreadOnly - Only return unread messages
-   * @param options.from - Filter by sender
-   * @param options.channel - Filter by channel
-   * @returns Array of inbox messages
-   */
-  async getInbox(options: {
-    limit?: number;
-    unreadOnly?: boolean;
-    from?: string;
-    channel?: string;
-  } = {}): Promise<InboxMessage[]> {
-    const payload: InboxPayload = {
-      agent: this.config.agentName,
-      limit: options.limit,
-      unreadOnly: options.unreadOnly,
-      from: options.from,
-      channel: options.channel,
-    };
-    const response = await this.query<InboxResponsePayload>('INBOX', payload);
-    return response.messages || [];
-  }
-
-  /**
-   * Query all messages (not filtered by recipient).
-   * Used by dashboard to get message history.
-   * @param options - Query options
-   * @param options.limit - Maximum number of messages to return (default: 100)
-   * @param options.sinceTs - Only return messages after this timestamp
-   * @param options.from - Filter by sender
-   * @param options.to - Filter by recipient
-   * @param options.thread - Filter by thread ID
-   * @param options.order - Sort order ('asc' or 'desc', default: 'desc')
-   * @returns Array of messages
-   */
-  async queryMessages(options: {
-    limit?: number;
-    sinceTs?: number;
-    from?: string;
-    to?: string;
-    thread?: string;
-    order?: 'asc' | 'desc';
-  } = {}): Promise<MessagesResponsePayload['messages']> {
-    const payload: MessagesQueryPayload = {
-      limit: options.limit,
-      sinceTs: options.sinceTs,
-      from: options.from,
-      to: options.to,
-      thread: options.thread,
-      order: options.order,
-    };
-    const response = await this.query<MessagesResponsePayload>('MESSAGES_QUERY', payload);
-    return response.messages || [];
-  }
-
-  /**
-   * List online agents.
-   * @param options - Filter options
-   * @param options.includeIdle - Include idle agents (default: true)
-   * @param options.project - Filter by project
-   * @returns Array of agent info
-   */
-  async listAgents(options: {
-    includeIdle?: boolean;
-    project?: string;
-  } = {}): Promise<AgentInfo[]> {
-    const payload: ListAgentsPayload = {
-      includeIdle: options.includeIdle ?? true,
-      project: options.project,
-    };
-    const response = await this.query<ListAgentsResponsePayload>('LIST_AGENTS', payload);
-    return response.agents || [];
-  }
-
-  /**
-   * Get system health information.
-   * @param options - Include options
-   * @param options.includeCrashes - Include crash history (default: true)
-   * @param options.includeAlerts - Include alerts (default: true)
-   * @returns Health information including score, issues, and recommendations
-   */
-  async getHealth(options: {
-    includeCrashes?: boolean;
-    includeAlerts?: boolean;
-  } = {}): Promise<HealthResponsePayload> {
-    const payload: HealthPayload = {
-      includeCrashes: options.includeCrashes ?? true,
-      includeAlerts: options.includeAlerts ?? true,
-    };
-    return this.query<HealthResponsePayload>('HEALTH', payload);
-  }
-
-  /**
-   * Get resource metrics for agents.
-   * @param options - Filter options
-   * @param options.agent - Filter to a specific agent
-   * @returns Metrics including memory, CPU, and system info
-   */
-  async getMetrics(options: {
-    agent?: string;
-  } = {}): Promise<MetricsResponsePayload> {
-    const payload: MetricsPayload = {
-      agent: options.agent,
-    };
-    return this.query<MetricsResponsePayload>('METRICS', payload);
-  }
-
-  /**
-   * List only currently connected agents (not historical/registered agents).
-   * Use this instead of listAgents() when you need accurate liveness information.
-   * @param options - Filter options
-   * @param options.project - Filter by project
-   * @returns Array of currently connected agent info
-   */
-  async listConnectedAgents(options: {
-    project?: string;
-  } = {}): Promise<AgentInfo[]> {
-    const payload: ListConnectedAgentsPayload = {
-      project: options.project,
-    };
-    const response = await this.query<ListConnectedAgentsResponsePayload>('LIST_CONNECTED_AGENTS', payload);
-    return response.agents || [];
-  }
-
-  /**
-   * Remove an agent from the registry (sessions, agents.json).
-   * Use this to clean up stale agents that are no longer needed.
-   * @param name - Agent name to remove
-   * @param options - Removal options
-   * @param options.removeMessages - Also remove all messages from/to this agent (default: false)
-   * @returns Result indicating if the agent was removed
-   */
-  async removeAgent(name: string, options: {
-    removeMessages?: boolean;
-  } = {}): Promise<RemoveAgentResponsePayload> {
-    const payload: RemoveAgentPayload = {
-      name,
-      removeMessages: options.removeMessages,
-    };
-    return this.query<RemoveAgentResponsePayload>('REMOVE_AGENT', payload);
-  }
-
-  // Private methods
+    this.exitPromise = new Promise<void>((resolve) => {
+      child.once('exit', (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();
+      });
+    });
 
-  private setState(state: ClientState): void {
-    this._state = state;
-    if (this.onStateChange) {
-      this.onStateChange(state);
+    const helloAck = await this.requestHello();
+    console.log('[broker] Broker ready (hello handshake complete)');
+    if (helloAck.workspace_key) {
+      this.workspaceKey = helloAck.workspace_key;
     }
   }
 
-  private sendHello(): void {
-    const hello: Envelope<HelloPayload> = {
-      v: PROTOCOL_VERSION,
-      type: 'HELLO',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        agent: this.config.agentName,
-        entityType: this.config.entityType,
-        cli: this.config.cli,
-        program: this.config.program,
-        model: this.config.model,
-        task: this.config.task,
-        workingDirectory: this.config.workingDirectory,
-        team: this.config.team,
-        displayName: this.config.displayName,
-        avatarUrl: this.config.avatarUrl,
-        capabilities: {
-          ack: true,
-          resume: true,
-          max_inflight: 256,
-          supports_topics: true,
-        },
-        session: this.resumeToken ? { resume_token: this.resumeToken } : undefined,
-        _isSystemComponent: this.config._isSystemComponent,
-      },
-    };
-
-    this.send(hello);
-  }
-
-  private send(envelope: Envelope): boolean {
-    if (!this.socket) return false;
-
-    try {
-      const frame = encodeFrameLegacy(envelope);
-      this.writeQueue.push(frame);
-
-      if (!this.writeScheduled) {
-        this.writeScheduled = true;
-        setImmediate(() => this.flushWrites());
-      }
-      return true;
-    } catch (err) {
-      this.handleError(err as Error);
-      return false;
-    }
+  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 flushWrites(): void {
-    this.writeScheduled = false;
-    if (this.writeQueue.length === 0 || !this.socket) return;
-
-    if (this.writeQueue.length === 1) {
-      this.socket.write(this.writeQueue[0]);
-    } else {
-      this.socket.write(Buffer.concat(this.writeQueue));
+  private failAllPending(error: Error): void {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(error);
     }
-    this.writeQueue = [];
+    this.pending.clear();
   }
 
-  private handleData(data: Buffer): void {
+  private handleStdoutLine(line: string): void {
+    let parsed: ParsedEnvelope;
     try {
-      const frames = this.parser.push(data);
-      for (const frame of frames) {
-        this.processFrame(frame);
-      }
-    } catch (err) {
-      this.handleError(err as Error);
-    }
-  }
-
-  private processFrame(envelope: Envelope): void {
-    switch (envelope.type) {
-      case 'WELCOME':
-        this.handleWelcome(envelope as Envelope<WelcomePayload>);
-        break;
-
-      case 'DELIVER':
-        this.handleDeliver(envelope as DeliverEnvelope);
-        break;
-
-      case 'CHANNEL_MESSAGE':
-        this.handleChannelMessage(envelope as Envelope<ChannelMessagePayload> & { from?: string });
-        break;
-
-      case 'PING':
-        this.handlePing(envelope);
-        break;
-
-      case 'ACK':
-        this.handleAck(envelope as Envelope<AckPayload>);
-        break;
-
-      case 'SPAWN_RESULT':
-        this.handleSpawnResult(envelope as Envelope<SpawnResultPayload>);
-        break;
-
-      case 'RELEASE_RESULT':
-        this.handleReleaseResult(envelope as Envelope<ReleaseResultPayload>);
-        break;
-
-      case 'SEND_INPUT_RESULT':
-        this.handleSendInputResult(envelope as Envelope<SendInputResultPayload>);
-        break;
-
-      case 'SET_MODEL_RESULT':
-        this.handleSetModelResult(envelope as Envelope<SetModelResultPayload>);
-        break;
-
-      case 'LIST_WORKERS_RESULT':
-        this.handleListWorkersResult(envelope as Envelope<ListWorkersResultPayload>);
-        break;
-
-      case 'AGENT_READY':
-        this.handleAgentReady(envelope as Envelope<AgentReadyPayload>);
-        break;
-
-      case 'ERROR':
-        this.handleErrorFrame(envelope as Envelope<ErrorPayload>);
-        break;
-
-      case 'BUSY':
-        if (!this.config.quiet) {
-          console.warn('[sdk] Server busy, backing off');
-        }
-        break;
-
-      case 'STATUS_RESPONSE':
-      case 'INBOX_RESPONSE':
-      case 'MESSAGES_RESPONSE':
-      case 'LIST_AGENTS_RESPONSE':
-      case 'LIST_CONNECTED_AGENTS_RESPONSE':
-      case 'REMOVE_AGENT_RESPONSE':
-      case 'HEALTH_RESPONSE':
-      case 'METRICS_RESPONSE':
-        this.handleQueryResponse(envelope);
-        break;
+      parsed = JSON.parse(line) as ParsedEnvelope;
+    } catch {
+      // Non-protocol output should not crash the SDK.
+      return;
     }
-  }
 
-  private handleWelcome(envelope: Envelope<WelcomePayload>): void {
-    this.sessionId = envelope.payload.session_id;
-    this.resumeToken = envelope.payload.resume_token;
-    this.reconnectAttempts = 0;
-    this.reconnectDelay = this.config.reconnectDelayMs;
-    this.setState('READY');
-    if (!this.config.quiet) {
-      console.log(`[sdk] Connected as ${this.config.agentName} (session: ${this.sessionId})`);
+    if (!parsed || typeof parsed !== 'object') {
+      return;
     }
-  }
-
-  private handleDeliver(envelope: DeliverEnvelope): void {
-    // Send ACK
-    this.send({
-      v: PROTOCOL_VERSION,
-      type: 'ACK',
-      id: generateId(),
-      ts: Date.now(),
-      payload: {
-        ack_id: envelope.id,
-        seq: envelope.delivery.seq,
-      },
-    });
-
-    const duplicate = this.dedupeCache.check(envelope.id);
-    if (duplicate) {
+    if (parsed.v !== PROTOCOL_VERSION || typeof parsed.type !== 'string') {
       return;
     }
 
-    // Check if this is a response to a pending request
-    const correlationId = this.extractCorrelationId(envelope);
-    if (correlationId && envelope.from) {
-      const pending = this.pendingRequests.get(correlationId);
-      if (pending) {
-        // This is a response to our request
-        clearTimeout(pending.timeoutHandle);
-        this.pendingRequests.delete(correlationId);
-        pending.resolve({
-          from: envelope.from,
-          body: envelope.payload.body,
-          data: envelope.payload.data,
-          correlationId,
-          thread: envelope.payload.thread,
-          payload: envelope.payload,
-        });
-        // Still call onMessage so the app is aware of the response if needed
+    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 (this.onMessage && envelope.from) {
-      this.onMessage(
-        envelope.from,
-        envelope.payload,
-        envelope.id,
-        envelope.payload_meta,
-        envelope.delivery.originalTo
-      );
+    if (!envelope.request_id) {
+      return;
     }
-  }
 
-  /**
-   * Extract correlation ID from a delivered message.
-   * Checks both payload_meta.replyTo and payload.data._correlationId
-   */
-  private extractCorrelationId(envelope: DeliverEnvelope): string | undefined {
-    // Check payload_meta.replyTo first (the preferred location)
-    if (envelope.payload_meta?.replyTo) {
-      return envelope.payload_meta.replyTo;
-    }
-    // Fall back to checking data._correlationId
-    if (envelope.payload.data && typeof envelope.payload.data._correlationId === 'string') {
-      return envelope.payload.data._correlationId;
+    const pending = this.pending.get(envelope.request_id);
+    if (!pending) {
+      return;
     }
-    return undefined;
-  }
 
-  private handleChannelMessage(envelope: Envelope<ChannelMessagePayload> & { from?: string }): void {
-    const duplicate = this.dedupeCache.check(envelope.id);
-    if (duplicate) {
+    if (envelope.type === 'error') {
+      clearTimeout(pending.timeout);
+      this.pending.delete(envelope.request_id);
+      pending.reject(new AgentRelayProtocolError(envelope.payload as ProtocolError));
       return;
     }
 
-    // Notify channel message handler
-    if (this.onChannelMessage && envelope.from) {
-      this.onChannelMessage(
-        envelope.from,
-        envelope.payload.channel,
-        envelope.payload.body,
-        envelope as Envelope<ChannelMessagePayload>
+    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;
     }
 
-    // Also call onMessage for backwards compatibility
-    if (this.onMessage && envelope.from) {
-      const sendPayload: SendPayload = {
-        kind: 'message',
-        body: envelope.payload.body,
-        data: {
-          _isChannelMessage: true,
-          _channel: envelope.payload.channel,
-          _mentions: envelope.payload.mentions,
-        },
-        thread: envelope.payload.thread,
-      };
-      this.onMessage(envelope.from, sendPayload, envelope.id, undefined, envelope.payload.channel);
-    }
-  }
-
-  private handleAck(envelope: Envelope<AckPayload>): void {
-    const correlationId = envelope.payload.correlationId;
-    if (!correlationId) return;
-
-    const pending = this.pendingSyncAcks.get(correlationId);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingSyncAcks.delete(correlationId);
-    pending.resolve(envelope.payload);
+    clearTimeout(pending.timeout);
+    this.pending.delete(envelope.request_id);
+    pending.resolve(envelope);
   }
 
-  private handleSpawnResult(envelope: Envelope<SpawnResultPayload>): void {
-    const replyTo = envelope.payload.replyTo;
-    if (!replyTo) return;
-
-    const pending = this.pendingSpawns.get(replyTo);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingSpawns.delete(replyTo);
-    pending.resolve(envelope.payload);
-  }
-
-  private handleReleaseResult(envelope: Envelope<ReleaseResultPayload>): void {
-    const replyTo = envelope.payload.replyTo;
-    if (!replyTo) return;
-
-    const pending = this.pendingReleases.get(replyTo);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingReleases.delete(replyTo);
-    pending.resolve(envelope.payload);
-  }
-
-  private handleSendInputResult(envelope: Envelope<SendInputResultPayload>): void {
-    const replyTo = envelope.payload.replyTo;
-    if (!replyTo) return;
-
-    const pending = this.pendingSendInputs.get(replyTo);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingSendInputs.delete(replyTo);
-    pending.resolve(envelope.payload);
-  }
-
-  private handleSetModelResult(envelope: Envelope<SetModelResultPayload>): void {
-    const replyTo = envelope.payload.replyTo;
-    if (!replyTo) return;
-
-    const pending = this.pendingSetModels.get(replyTo);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingSetModels.delete(replyTo);
-    pending.resolve(envelope.payload);
+  private async requestHello(): Promise<{ broker_version: string; protocol_version: number; workspace_key?: string }> {
+    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 };
   }
 
-  private handleListWorkersResult(envelope: Envelope<ListWorkersResultPayload>): void {
-    const replyTo = envelope.payload.replyTo;
-    if (!replyTo) return;
-
-    const pending = this.pendingListWorkers.get(replyTo);
-    if (!pending) return;
-
-    clearTimeout(pending.timeoutHandle);
-    this.pendingListWorkers.delete(replyTo);
-    pending.resolve(envelope.payload);
+  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;
   }
 
-  private handleAgentReady(envelope: Envelope<AgentReadyPayload>): void {
-    const agentName = envelope.payload.name;
-
-    // Resolve any pending waitForReady promises for this agent
-    const pending = this.pendingAgentReady.get(agentName);
-    if (pending) {
-      clearTimeout(pending.timeoutHandle);
-      this.pendingAgentReady.delete(agentName);
-      pending.resolve(envelope.payload);
+  private async sendRequest(
+    type: string,
+    payload: unknown,
+    expectedType: 'ok' | 'hello_ack'
+  ): Promise<ProtocolEnvelope<unknown>> {
+    if (!this.child) {
+      throw new AgentRelayProcessError('broker is not running');
     }
 
-    // Call the onAgentReady callback if registered
-    if (this.onAgentReady) {
-      this.onAgentReady(envelope.payload);
-    }
-  }
-
-  private handleQueryResponse(envelope: Envelope): void {
-    // Query responses use the envelope id to match requests
-    const pending = this.pendingQueries.get(envelope.id);
-    if (!pending) return;
+    const requestId = `req_${++this.requestSeq}`;
+    const message: ProtocolEnvelope<unknown> = {
+      v: PROTOCOL_VERSION,
+      type,
+      request_id: requestId,
+      payload,
+    };
 
-    clearTimeout(pending.timeoutHandle);
-    this.pendingQueries.delete(envelope.id);
-    pending.resolve(envelope.payload);
-  }
+    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);
 
-  private handlePing(envelope: Envelope): void {
-    this.send({
-      v: PROTOCOL_VERSION,
-      type: 'PONG',
-      id: generateId(),
-      ts: Date.now(),
-      payload: (envelope.payload as { nonce?: string }) ?? {},
+      this.pending.set(requestId, {
+        expectedType,
+        resolve,
+        reject,
+        timeout,
+      });
     });
-  }
-
-  private handleErrorFrame(envelope: Envelope<ErrorPayload>): void {
-    if (!this.config.quiet) {
-      console.error('[sdk] Server error:', envelope.payload);
-    }
 
-    if (envelope.payload.code === 'RESUME_TOO_OLD') {
-      this.resumeToken = undefined;
-      this.sessionId = undefined;
+    const line = `${JSON.stringify(message)}\n`;
+    if (!this.child.stdin.write(line)) {
+      await once(this.child.stdin, 'drain');
     }
 
-    // Fatal errors (like DUPLICATE_CONNECTION) should prevent reconnection
-    if (envelope.payload.fatal) {
-      if (!this.config.quiet) {
-        console.error('[sdk] Fatal error received, will not reconnect:', envelope.payload.message);
-      }
-      this._destroyed = true;
-    }
+    return responsePromise;
   }
+}
 
-  private handleDisconnect(): void {
-    this.parser.reset();
-    this.socket = undefined;
-    this.rejectPendingSyncAcks(new Error('Disconnected while awaiting ACK'));
-    this.rejectPendingSpawns(new Error('Disconnected while awaiting spawn result'));
-    this.rejectPendingReleases(new Error('Disconnected while awaiting release result'));
-    this.rejectPendingSendInputs(new Error('Disconnected while awaiting send input result'));
-    this.rejectPendingSetModels(new Error('Disconnected while awaiting set model result'));
-    this.rejectPendingListWorkers(new Error('Disconnected while awaiting list workers result'));
-    this.rejectPendingQueries(new Error('Disconnected while awaiting query response'));
-    this.rejectPendingRequests(new Error('Disconnected while awaiting request response'));
-    this.rejectPendingAgentReady(new Error('Disconnected while awaiting agent ready'));
-
-    if (this._destroyed) {
-      this.setState('DISCONNECTED');
-      return;
-    }
+const CLI_MODEL_FLAG_CLIS = new Set(['claude', 'codex', 'gemini', 'goose', 'aider']);
 
-    if (this.config.reconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
-      this.scheduleReconnect();
-    } else {
-      this.setState('DISCONNECTED');
-      if (this.reconnectAttempts >= this.config.maxReconnectAttempts && !this.config.quiet) {
-        console.error(
-          `[sdk] Max reconnect attempts reached (${this.config.maxReconnectAttempts}), giving up`
-        );
-      }
-    }
-  }
+const CLI_DEFAULT_ARGS: Record<string, string[]> = {
+  codex: ['-c', 'check_for_update_on_startup=false'],
+};
 
-  private handleError(error: Error): void {
-    if (!this.config.quiet) {
-      console.error('[sdk] Error:', error.message);
-    }
-    if (this.onError) {
-      this.onError(error);
-    }
+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;
   }
-
-  private rejectPendingSyncAcks(error: Error): void {
-    for (const [correlationId, pending] of this.pendingSyncAcks.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingSyncAcks.delete(correlationId);
-    }
+  if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
+    return baseArgs;
   }
-
-  private rejectPendingSpawns(error: Error): void {
-    for (const [id, pending] of this.pendingSpawns.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingSpawns.delete(id);
-    }
+  if (hasModelArg(baseArgs)) {
+    return baseArgs;
   }
+  return ['--model', model, ...baseArgs];
+}
 
-  private rejectPendingReleases(error: Error): void {
-    for (const [id, pending] of this.pendingReleases.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingReleases.delete(id);
+function hasModelArg(args: string[]): boolean {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--model') {
+      return true;
     }
-  }
-
-  private rejectPendingSendInputs(error: Error): void {
-    for (const [id, pending] of this.pendingSendInputs.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingSendInputs.delete(id);
+    if (arg.startsWith('--model=')) {
+      return true;
     }
   }
+  return false;
+}
 
-  private rejectPendingSetModels(error: Error): void {
-    for (const [id, pending] of this.pendingSetModels.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingSetModels.delete(id);
-    }
+function expandTilde(p: string): string {
+  if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
+    const home = os.homedir();
+    return path.join(home, p.slice(2));
   }
+  return p;
+}
 
-  private rejectPendingListWorkers(error: Error): void {
-    for (const [id, pending] of this.pendingListWorkers.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingListWorkers.delete(id);
-    }
-  }
+function isExplicitPath(binaryPath: string): boolean {
+  return (
+    binaryPath.includes('/') ||
+    binaryPath.includes('\\') ||
+    binaryPath.startsWith('.') ||
+    binaryPath.startsWith('~')
+  );
+}
 
-  private rejectPendingQueries(error: Error): void {
-    for (const [id, pending] of this.pendingQueries.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingQueries.delete(id);
-    }
-  }
+function resolveDefaultBinaryPath(): string {
+  const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
-  private rejectPendingRequests(error: Error): void {
-    for (const [correlationId, pending] of this.pendingRequests.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingRequests.delete(correlationId);
-    }
+  // 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;
   }
 
-  private rejectPendingAgentReady(error: Error): void {
-    for (const [agentName, pending] of this.pendingAgentReady.entries()) {
-      clearTimeout(pending.timeoutHandle);
-      pending.reject(error);
-      this.pendingAgentReady.delete(agentName);
-    }
+  // 2. Check for bundled broker binary in SDK package (npm install)
+  const bundled = path.resolve(moduleDir, '..', 'bin', brokerExe);
+  if (fs.existsSync(bundled)) {
+    return bundled;
   }
 
-  private scheduleReconnect(): void {
-    this.setState('BACKOFF');
-    this.reconnectAttempts++;
-
-    const jitter = Math.random() * 0.3 + 0.85;
-    const delay = Math.min(this.reconnectDelay * jitter, this.config.reconnectMaxDelayMs);
-    this.reconnectDelay *= 2;
-
-    if (!this.config.quiet) {
-      console.log(`[sdk] Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempts})`);
-    }
-
-    this.reconnectTimer = setTimeout(() => {
-      this.connect().catch(() => {});
-    }, delay);
+  // 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;
   }
+
+  // 4. Fall back to agent-relay on PATH (may be Node CLI — will fail for broker ops)
+  return 'agent-relay';
 }