agent-relay 2.3.13 → 2.4.0

package/packages/sdk/dist/client.js

@@ -1,1591 +1,498 @@
-/**
- * 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 { PROTOCOL_VERSION, encodeFrameLegacy, FrameParser, } from '@agent-relay/protocol';
-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) {
-    if (configPath)
-        return configPath;
-    const discovery = discoverSocket();
-    return discovery?.socketPath || DEFAULT_SOCKET_PATH;
-}
-const DEFAULT_CLIENT_CONFIG = {
-    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() {
-    return `${Date.now().toString(36)}-${(++idCounter).toString(36)}`;
-}
-/**
- * Circular buffer for O(1) deduplication with bounded memory.
- */
-class CircularDedupeCache {
-    ids = new Set();
-    ring;
-    head = 0;
-    capacity;
-    constructor(capacity = 2000) {
-        this.capacity = capacity;
-        this.ring = new Array(capacity);
-    }
-    check(id) {
-        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);
-        }
-        this.ring[this.head] = id;
-        this.ids.add(id);
-        this.head = (this.head + 1) % this.capacity;
-        return false;
-    }
-    clear() {
-        this.ids.clear();
-        this.ring = new Array(this.capacity);
-        this.head = 0;
+import { once } from 'node:events';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PROTOCOL_VERSION, } from './protocol.js';
+export class AgentRelayProtocolError extends Error {
+    code;
+    retryable;
+    data;
+    constructor(payload) {
+        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 {
-    config;
-    socket;
-    parser;
-    _state = 'DISCONNECTED';
-    sessionId;
-    resumeToken;
-    reconnectAttempts = 0;
-    reconnectDelay;
-    reconnectTimer;
-    _destroyed = false;
-    dedupeCache = new CircularDedupeCache(2000);
-    writeQueue = [];
-    writeScheduled = false;
-    pendingSyncAcks = new Map();
-    pendingSpawns = new Map();
-    pendingReleases = new Map();
-    pendingSendInputs = new Map();
-    pendingSetModels = new Map();
-    pendingListWorkers = new Map();
-    pendingQueries = new Map();
-    pendingRequests = new Map();
-    pendingAgentReady = new Map();
-    // Event handlers
-    onMessage;
-    /**
-     * Callback for channel messages.
-     */
-    onChannelMessage;
-    onStateChange;
-    onError;
-    /**
-     * 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;
-    constructor(config = {}) {
-        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;
-    }
-    get state() {
-        return this._state;
+export class AgentRelayProcessError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentRelayProcessError';
     }
-    get agentName() {
-        return this.config.agentName;
+}
+export class AgentRelayClient {
+    options;
+    child;
+    stdoutRl;
+    stderrRl;
+    lastStderrLine;
+    requestSeq = 0;
+    pending = new Map();
+    startingPromise;
+    eventListeners = new Set();
+    stderrListeners = new Set();
+    eventBuffer = [];
+    maxBufferSize = 1000;
+    exitPromise;
+    /** The workspace key returned by the broker in its hello_ack response. */
+    workspaceKey;
+    constructor(options = {}) {
+        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 currentSessionId() {
-        return this.sessionId;
+    static async start(options = {}) {
+        const client = new AgentRelayClient(options);
+        await client.start();
+        return client;
     }
-    /**
-     * Connect to the relay daemon.
-     */
-    connect() {
-        if (this._state !== 'DISCONNECTED' && this._state !== 'BACKOFF') {
-            return Promise.resolve();
-        }
-        return new Promise((resolve, reject) => {
-            let settled = false;
-            const settleResolve = () => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve();
-            };
-            const settleReject = (err) => {
-                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.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);
-        });
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => {
+            this.eventListeners.delete(listener);
+        };
     }
-    /**
-     * Disconnect from the relay daemon.
-     */
-    disconnect() {
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = undefined;
-        }
-        if (this.socket) {
-            this.send({
-                v: PROTOCOL_VERSION,
-                type: 'BYE',
-                id: generateId(),
-                ts: Date.now(),
-                payload: {},
-            });
-            this.socket.end();
-            this.socket = undefined;
+    queryEvents(filter) {
+        let events = [...this.eventBuffer];
+        if (filter?.kind) {
+            events = events.filter((event) => event.kind === filter.kind);
         }
-        this.setState('DISCONNECTED');
-    }
-    /**
-     * Permanently destroy the client.
-     */
-    destroy() {
-        this._destroyed = true;
-        this.disconnect();
-    }
-    /**
-     * Send a message to another agent.
-     */
-    sendMessage(to, body, kind = 'message', data, thread, meta) {
-        if (this._state !== 'READY') {
-            return false;
+        if (filter?.name) {
+            events = events.filter((event) => 'name' in event && event.name === filter.name);
         }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'SEND',
-            id: generateId(),
-            ts: Date.now(),
-            to,
-            payload: {
-                kind,
-                body,
-                data,
-                thread,
-            },
-            payload_meta: meta,
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Send an ACK for a delivered message.
-     */
-    sendAck(payload) {
-        if (this._state !== 'READY') {
-            return false;
+        const since = filter?.since;
+        if (since !== undefined) {
+            events = events.filter((event) => 'timestamp' in event && typeof event.timestamp === 'number' && event.timestamp >= since);
         }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'ACK',
-            id: generateId(),
-            ts: Date.now(),
-            payload,
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Send a message and wait for ACK response.
-     */
-    async sendAndWait(to, body, options = {}) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
+        const limit = filter?.limit;
+        if (limit !== undefined) {
+            events = events.slice(-limit);
         }
-        const correlationId = randomUUID();
-        const timeoutMs = options.timeoutMs ?? 30000;
-        const kind = options.kind ?? 'message';
-        return new Promise((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 = {
-                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'));
-            }
-        });
+        return events;
     }
-    /**
-     * 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, body, options = {}) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const correlationId = randomUUID();
-        const timeoutMs = options.timeout ?? 30000;
-        const kind = options.kind ?? 'message';
-        return new Promise((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 = {
-                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'));
+    getLastEvent(kind, name) {
+        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;
             }
-        });
-    }
-    /**
-     * 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, to, body, data) {
-        if (this._state !== 'READY') {
-            return false;
         }
-        const envelope = {
-            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 this.send(envelope);
-    }
-    /**
-     * Broadcast a message to all agents.
-     */
-    broadcast(body, kind = 'message', data) {
-        return this.sendMessage('*', body, kind, data);
-    }
-    /**
-     * Subscribe to a topic.
-     */
-    subscribe(topic) {
-        if (this._state !== 'READY')
-            return false;
-        return this.send({
-            v: PROTOCOL_VERSION,
-            type: 'SUBSCRIBE',
-            id: generateId(),
-            ts: Date.now(),
-            topic,
-            payload: {},
-        });
-    }
-    /**
-     * Unsubscribe from a topic.
-     */
-    unsubscribe(topic) {
-        if (this._state !== 'READY')
-            return false;
-        return this.send({
-            v: PROTOCOL_VERSION,
-            type: 'UNSUBSCRIBE',
-            id: generateId(),
-            ts: Date.now(),
-            topic,
-            payload: {},
-        });
-    }
-    /**
-     * Bind as a shadow to a primary agent.
-     */
-    bindAsShadow(primaryAgent, options = {}) {
-        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,
-            },
-        });
-    }
-    /**
-     * Unbind from a primary agent.
-     */
-    unbindAsShadow(primaryAgent) {
-        if (this._state !== 'READY')
-            return false;
-        return this.send({
-            v: PROTOCOL_VERSION,
-            type: 'SHADOW_UNBIND',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                primaryAgent,
-            },
-        });
+        return undefined;
     }
-    /**
-     * Send log output to the daemon for dashboard streaming.
-     */
-    sendLog(data) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'LOG',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                data,
-                timestamp: Date.now(),
-            },
+    onBrokerStderr(listener) {
+        this.stderrListeners.add(listener);
+        return () => {
+            this.stderrListeners.delete(listener);
         };
-        return this.send(envelope);
     }
-    // =============================================================================
-    // 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, timeoutMs = 60000) {
-        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;
-        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((resolve, reject) => {
-                const timeoutHandle = setTimeout(() => {
-                    this.pendingAgentReady.delete(options.name);
-                    reject(new Error(`Agent ${options.name} did not become ready within ${readyTimeoutMs}ms`));
-                }, readyTimeoutMs);
-                this.pendingAgentReady.set(options.name, { resolve, reject, timeoutHandle });
-            });
+    async start() {
+        if (this.child) {
+            return;
         }
-        // Send the spawn request
-        const spawnResult = await new Promise((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 = {
-                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);
-                }
-            }
-            return spawnResult;
+        if (this.startingPromise) {
+            return this.startingPromise;
         }
-        // Wait for the agent to become ready
+        this.startingPromise = this.startInternal();
         try {
-            const readyInfo = await readyPromise;
-            return {
-                ...spawnResult,
-                ready: true,
-                readyInfo,
-            };
+            await this.startingPromise;
         }
-        catch (err) {
-            // Agent spawned but didn't become ready in time
-            // Return the spawn result with ready: false
-            return {
-                ...spawnResult,
-                ready: false,
-            };
+        finally {
+            this.startingPromise = undefined;
         }
     }
     /**
-     * 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
+     * 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 waitForAgentReady(name, timeoutMs = 60000) {
-        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((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 preflightAgents(agents) {
+        if (agents.length === 0)
+            return;
+        await this.start();
+        await this.requestOk('preflight_agents', { agents });
+    }
+    async spawnPty(input) {
+        await this.start();
+        const args = buildPtyArgsWithModel(input.cli, input.args ?? [], input.model);
+        const agent = {
+            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('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 } : {}),
         });
-    }
-    /**
-     * 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, reason, timeoutMs = 10000) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const envelopeId = generateId();
-        return new Promise((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 = {
-                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'));
-            }
+        return result;
+    }
+    async spawnHeadlessClaude(input) {
+        await this.start();
+        const agent = {
+            name: input.name,
+            runtime: 'headless_claude',
+            args: input.args ?? [],
+            channels: input.channels ?? [],
+        };
+        const result = await this.requestOk('spawn_agent', {
+            agent,
+            ...(input.task != null ? { initial_task: input.task } : {}),
         });
+        return result;
     }
-    /**
-     * 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, data, timeoutMs = 10000) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const envelopeId = generateId();
-        return new Promise((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 = {
-                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'));
-            }
-        });
+    async release(name, reason) {
+        await this.start();
+        return this.requestOk('release_agent', { name, reason });
     }
-    /**
-     * 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, model, options, operationTimeoutMs = 45000) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const envelopeId = generateId();
-        return new Promise((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 = {
-                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'));
-            }
-        });
+    async sendInput(name, data) {
+        await this.start();
+        return this.requestOk('send_input', { name, data });
     }
-    /**
-     * List active spawned workers.
-     * @param timeoutMs - Timeout for the operation (default: 10000ms)
-     */
-    async listWorkers(timeoutMs = 10000) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const envelopeId = generateId();
-        return new Promise((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 = {
-                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'));
-            }
+    async setModel(name, model, opts) {
+        await this.start();
+        return this.requestOk('set_model', {
+            name,
+            model,
+            timeout_ms: opts?.timeoutMs,
         });
     }
-    // =============================================================================
-    // 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, displayName) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            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, member) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            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, reason) {
-        if (this._state !== 'READY')
-            return false;
-        const envelope = {
-            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, member) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            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, body, options) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            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);
-    }
-    // =============================================================================
-    // 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) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        // Build the PROPOSE command message
-        const lines = [
-            `PROPOSE: ${options.title}`,
-            `TYPE: ${options.consensusType ?? 'majority'}`,
-            `PARTICIPANTS: ${options.participants.join(', ')}`,
-            `DESCRIPTION: ${options.description}`,
-        ];
-        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');
+    async getMetrics(agent) {
+        await this.start();
+        return this.requestOk('get_metrics', { agent });
     }
-    /**
-     * 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) {
-        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');
+    async getCrashInsights() {
+        await this.start();
+        return this.requestOk('get_crash_insights', {});
     }
-    // =============================================================================
-    // Query Operations
-    // =============================================================================
-    /**
-     * Send a query to the daemon and wait for a response.
-     * @internal
-     */
-    async query(type, payload, timeoutMs = 5000) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const envelopeId = generateId();
-        return new Promise((resolve, reject) => {
-            const timeoutHandle = setTimeout(() => {
-                this.pendingQueries.delete(envelopeId);
-                reject(new Error(`Query timeout after ${timeoutMs}ms`));
-            }, timeoutMs);
-            this.pendingQueries.set(envelopeId, {
-                resolve: resolve,
-                reject,
-                timeoutHandle,
+    async sendMessage(input) {
+        await this.start();
+        try {
+            return await this.requestOk('send_message', {
+                to: input.to,
+                text: input.text,
+                from: input.from,
+                thread_id: input.threadId,
+                priority: input.priority,
+                data: input.data,
             });
-            const envelope = {
-                v: PROTOCOL_VERSION,
-                type: 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`));
+        }
+        catch (error) {
+            if (error instanceof AgentRelayProtocolError && error.code === 'unsupported_operation') {
+                return { event_id: 'unsupported_operation', targets: [] };
             }
-        });
-    }
-    /**
-     * Get daemon status information.
-     * @returns Daemon status including version, uptime, and counts
-     */
-    async getStatus() {
-        return this.query('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 = {}) {
-        const payload = {
-            agent: this.config.agentName,
-            limit: options.limit,
-            unreadOnly: options.unreadOnly,
-            from: options.from,
-            channel: options.channel,
-        };
-        const response = await this.query('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 = {}) {
-        const payload = {
-            limit: options.limit,
-            sinceTs: options.sinceTs,
-            from: options.from,
-            to: options.to,
-            thread: options.thread,
-            order: options.order,
-        };
-        const response = await this.query('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 = {}) {
-        const payload = {
-            includeIdle: options.includeIdle ?? true,
-            project: options.project,
-        };
-        const response = await this.query('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 = {}) {
-        const payload = {
-            includeCrashes: options.includeCrashes ?? true,
-            includeAlerts: options.includeAlerts ?? true,
-        };
-        return this.query('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 = {}) {
-        const payload = {
-            agent: options.agent,
-        };
-        return this.query('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 = {}) {
-        const payload = {
-            project: options.project,
-        };
-        const response = await this.query('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, options = {}) {
-        const payload = {
-            name,
-            removeMessages: options.removeMessages,
-        };
-        return this.query('REMOVE_AGENT', payload);
-    }
-    // Private methods
-    setState(state) {
-        this._state = state;
-        if (this.onStateChange) {
-            this.onStateChange(state);
+            throw error;
         }
     }
-    sendHello() {
-        const hello = {
-            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);
+    async listAgents() {
+        await this.start();
+        const result = await this.requestOk('list_agents', {});
+        return result.agents;
     }
-    send(envelope) {
-        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);
-            return false;
-        }
+    async getStatus() {
+        await this.start();
+        return this.requestOk('get_status', {});
     }
-    flushWrites() {
-        this.writeScheduled = false;
-        if (this.writeQueue.length === 0 || !this.socket)
+    async shutdown() {
+        if (!this.child) {
             return;
-        if (this.writeQueue.length === 1) {
-            this.socket.write(this.writeQueue[0]);
-        }
-        else {
-            this.socket.write(Buffer.concat(this.writeQueue));
         }
-        this.writeQueue = [];
-    }
-    handleData(data) {
         try {
-            const frames = this.parser.push(data);
-            for (const frame of frames) {
-                this.processFrame(frame);
-            }
+            await this.requestOk('shutdown', {});
         }
-        catch (err) {
-            this.handleError(err);
+        catch {
+            // Continue shutdown path if broker is already unhealthy.
         }
-    }
-    processFrame(envelope) {
-        switch (envelope.type) {
-            case 'WELCOME':
-                this.handleWelcome(envelope);
-                break;
-            case 'DELIVER':
-                this.handleDeliver(envelope);
-                break;
-            case 'CHANNEL_MESSAGE':
-                this.handleChannelMessage(envelope);
-                break;
-            case 'PING':
-                this.handlePing(envelope);
-                break;
-            case 'ACK':
-                this.handleAck(envelope);
-                break;
-            case 'SPAWN_RESULT':
-                this.handleSpawnResult(envelope);
-                break;
-            case 'RELEASE_RESULT':
-                this.handleReleaseResult(envelope);
-                break;
-            case 'SEND_INPUT_RESULT':
-                this.handleSendInputResult(envelope);
-                break;
-            case 'SET_MODEL_RESULT':
-                this.handleSetModelResult(envelope);
-                break;
-            case 'LIST_WORKERS_RESULT':
-                this.handleListWorkersResult(envelope);
-                break;
-            case 'AGENT_READY':
-                this.handleAgentReady(envelope);
-                break;
-            case 'ERROR':
-                this.handleErrorFrame(envelope);
-                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;
+        const child = this.child;
+        const wait = this.exitPromise ?? Promise.resolve();
+        const timeout = setTimeout(() => {
+            if (!child.killed) {
+                child.kill('SIGTERM');
+            }
+        }, this.options.shutdownTimeoutMs);
+        try {
+            await wait;
         }
-    }
-    handleWelcome(envelope) {
-        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})`);
+        finally {
+            clearTimeout(timeout);
+            if (this.child) {
+                this.child.kill('SIGKILL');
+            }
         }
     }
-    handleDeliver(envelope) {
-        // 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) {
+    async waitForExit() {
+        if (!this.child) {
             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
+        await this.exitPromise;
+    }
+    async startInternal() {
+        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,
+            '--channels',
+            this.options.channels.join(','),
+            ...this.options.binaryArgs,
+        ];
+        // 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}`;
             }
         }
-        if (this.onMessage && envelope.from) {
-            this.onMessage(envelope.from, envelope.payload, envelope.id, envelope.payload_meta, envelope.delivery.originalTo);
+        console.log(`[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((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();
+            });
+        });
+        const helloAck = await this.requestHello();
+        console.log('[broker] Broker ready (hello handshake complete)');
+        if (helloAck.workspace_key) {
+            this.workspaceKey = helloAck.workspace_key;
+        }
+    }
+    disposeProcessHandles() {
+        this.stdoutRl?.close();
+        this.stderrRl?.close();
+        this.stdoutRl = undefined;
+        this.stderrRl = undefined;
+        this.lastStderrLine = undefined;
+        this.child = undefined;
+        this.exitPromise = undefined;
+    }
+    failAllPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timeout);
+            pending.reject(error);
         }
+        this.pending.clear();
     }
-    /**
-     * Extract correlation ID from a delivered message.
-     * Checks both payload_meta.replyTo and payload.data._correlationId
-     */
-    extractCorrelationId(envelope) {
-        // 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;
+    handleStdoutLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
         }
-        return undefined;
-    }
-    handleChannelMessage(envelope) {
-        const duplicate = this.dedupeCache.check(envelope.id);
-        if (duplicate) {
+        catch {
+            // Non-protocol output should not crash the SDK.
             return;
         }
-        // Notify channel message handler
-        if (this.onChannelMessage && envelope.from) {
-            this.onChannelMessage(envelope.from, envelope.payload.channel, envelope.payload.body, envelope);
-        }
-        // Also call onMessage for backwards compatibility
-        if (this.onMessage && envelope.from) {
-            const 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);
-        }
-    }
-    handleAck(envelope) {
-        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);
-    }
-    handleSpawnResult(envelope) {
-        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);
-    }
-    handleReleaseResult(envelope) {
-        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);
-    }
-    handleSendInputResult(envelope) {
-        const replyTo = envelope.payload.replyTo;
-        if (!replyTo)
+        if (!parsed || typeof parsed !== 'object') {
             return;
-        const pending = this.pendingSendInputs.get(replyTo);
-        if (!pending)
-            return;
-        clearTimeout(pending.timeoutHandle);
-        this.pendingSendInputs.delete(replyTo);
-        pending.resolve(envelope.payload);
-    }
-    handleSetModelResult(envelope) {
-        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);
-    }
-    handleListWorkersResult(envelope) {
-        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);
-    }
-    handleAgentReady(envelope) {
-        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);
         }
-        // Call the onAgentReady callback if registered
-        if (this.onAgentReady) {
-            this.onAgentReady(envelope.payload);
-        }
-    }
-    handleQueryResponse(envelope) {
-        // Query responses use the envelope id to match requests
-        const pending = this.pendingQueries.get(envelope.id);
-        if (!pending)
+        if (parsed.v !== PROTOCOL_VERSION || typeof parsed.type !== 'string') {
             return;
-        clearTimeout(pending.timeoutHandle);
-        this.pendingQueries.delete(envelope.id);
-        pending.resolve(envelope.payload);
-    }
-    handlePing(envelope) {
-        this.send({
-            v: PROTOCOL_VERSION,
-            type: 'PONG',
-            id: generateId(),
-            ts: Date.now(),
-            payload: envelope.payload ?? {},
-        });
-    }
-    handleErrorFrame(envelope) {
-        if (!this.config.quiet) {
-            console.error('[sdk] Server error:', envelope.payload);
-        }
-        if (envelope.payload.code === 'RESUME_TOO_OLD') {
-            this.resumeToken = undefined;
-            this.sessionId = undefined;
         }
-        // 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);
+        const envelope = {
+            v: parsed.v,
+            type: parsed.type,
+            request_id: parsed.request_id,
+            payload: parsed.payload,
+        };
+        if (envelope.type === 'event') {
+            const payload = envelope.payload;
+            this.eventBuffer.push(payload);
+            if (this.eventBuffer.length > this.maxBufferSize) {
+                this.eventBuffer.shift();
+            }
+            for (const listener of this.eventListeners) {
+                listener(payload);
             }
-            this._destroyed = true;
-        }
-    }
-    handleDisconnect() {
-        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;
         }
-        if (this.config.reconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
-            this.scheduleReconnect();
+        if (!envelope.request_id) {
+            return;
         }
-        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 pending = this.pending.get(envelope.request_id);
+        if (!pending) {
+            return;
         }
-    }
-    handleError(error) {
-        if (!this.config.quiet) {
-            console.error('[sdk] Error:', error.message);
+        if (envelope.type === 'error') {
+            clearTimeout(pending.timeout);
+            this.pending.delete(envelope.request_id);
+            pending.reject(new AgentRelayProtocolError(envelope.payload));
+            return;
         }
-        if (this.onError) {
-            this.onError(error);
+        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);
     }
-    rejectPendingSyncAcks(error) {
-        for (const [correlationId, pending] of this.pendingSyncAcks.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingSyncAcks.delete(correlationId);
-        }
+    async requestHello() {
+        const payload = {
+            client_name: this.options.clientName,
+            client_version: this.options.clientVersion,
+        };
+        const frame = await this.sendRequest('hello', payload, 'hello_ack');
+        return frame.payload;
     }
-    rejectPendingSpawns(error) {
-        for (const [id, pending] of this.pendingSpawns.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingSpawns.delete(id);
-        }
+    async requestOk(type, payload) {
+        const frame = await this.sendRequest(type, payload, 'ok');
+        const result = frame.payload;
+        return result.result;
     }
-    rejectPendingReleases(error) {
-        for (const [id, pending] of this.pendingReleases.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingReleases.delete(id);
+    async sendRequest(type, payload, expectedType) {
+        if (!this.child) {
+            throw new AgentRelayProcessError('broker is not running');
         }
-    }
-    rejectPendingSendInputs(error) {
-        for (const [id, pending] of this.pendingSendInputs.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingSendInputs.delete(id);
+        const requestId = `req_${++this.requestSeq}`;
+        const message = {
+            v: PROTOCOL_VERSION,
+            type,
+            request_id: requestId,
+            payload,
+        };
+        const responsePromise = new Promise((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,
+            });
+        });
+        const line = `${JSON.stringify(message)}\n`;
+        if (!this.child.stdin.write(line)) {
+            await once(this.child.stdin, 'drain');
         }
+        return responsePromise;
     }
-    rejectPendingSetModels(error) {
-        for (const [id, pending] of this.pendingSetModels.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingSetModels.delete(id);
-        }
+}
+const CLI_MODEL_FLAG_CLIS = new Set(['claude', 'codex', 'gemini', 'goose', 'aider']);
+const CLI_DEFAULT_ARGS = {
+    codex: ['-c', 'check_for_update_on_startup=false'],
+};
+function buildPtyArgsWithModel(cli, args, model) {
+    const cliName = cli.split(':')[0].trim().toLowerCase();
+    const defaultArgs = CLI_DEFAULT_ARGS[cliName] ?? [];
+    const baseArgs = [...defaultArgs, ...args];
+    if (!model) {
+        return baseArgs;
     }
-    rejectPendingListWorkers(error) {
-        for (const [id, pending] of this.pendingListWorkers.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingListWorkers.delete(id);
-        }
+    if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
+        return baseArgs;
     }
-    rejectPendingQueries(error) {
-        for (const [id, pending] of this.pendingQueries.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingQueries.delete(id);
-        }
+    if (hasModelArg(baseArgs)) {
+        return baseArgs;
     }
-    rejectPendingRequests(error) {
-        for (const [correlationId, pending] of this.pendingRequests.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingRequests.delete(correlationId);
+    return ['--model', model, ...baseArgs];
+}
+function hasModelArg(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--model') {
+            return true;
         }
-    }
-    rejectPendingAgentReady(error) {
-        for (const [agentName, pending] of this.pendingAgentReady.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingAgentReady.delete(agentName);
+        if (arg.startsWith('--model=')) {
+            return true;
         }
     }
-    scheduleReconnect() {
-        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);
+    return false;
+}
+function expandTilde(p) {
+    if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
+        const home = os.homedir();
+        return path.join(home, p.slice(2));
     }
+    return p;
+}
+function isExplicitPath(binaryPath) {
+    return (binaryPath.includes('/') ||
+        binaryPath.includes('\\') ||
+        binaryPath.startsWith('.') ||
+        binaryPath.startsWith('~'));
+}
+function resolveDefaultBinaryPath() {
+    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;
+    }
+    // 2. Check for bundled broker binary in SDK package (npm install)
+    const bundled = path.resolve(moduleDir, '..', 'bin', brokerExe);
+    if (fs.existsSync(bundled)) {
+        return bundled;
+    }
+    // 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';
 }
 //# sourceMappingURL=client.js.map