@agent-relay/sdk 3.2.21 → 4.0.0

package/dist/client.js

@@ -1,211 +1,223 @@
-import { once } from 'node:events';
-import { execSync, spawn } from 'node:child_process';
-import { createInterface } from 'node:readline';
-import fs from 'node:fs';
-import os from 'node:os';
+/**
+ * AgentRelayClient — single client for communicating with an agent-relay broker
+ * over HTTP/WS. Works identically for local and remote brokers.
+ *
+ * Usage:
+ *   // Remote broker (Daytona sandbox, cloud, etc.)
+ *   const client = new AgentRelayClient({ baseUrl, apiKey });
+ *
+ *   // Local broker (spawn and connect)
+ *   const client = await AgentRelayClient.spawn({ cwd: '/my/project' });
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { getProjectPaths } from '@agent-relay/config';
-import { PROTOCOL_VERSION, } 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;
-    }
-}
-export class AgentRelayProcessError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'AgentRelayProcessError';
-    }
-}
+import { BrokerTransport, AgentRelayProtocolError } from './transport.js';
+import { getBrokerBinaryPath } from './broker-path.js';
 function isHeadlessProvider(value) {
     return value === 'claude' || value === 'opencode';
 }
-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',
-        };
+function resolveSpawnTransport(input) {
+    return input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
+}
+function isProcessRunning(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
     }
-    static async start(options = {}) {
-        const client = new AgentRelayClient(options);
-        await client.start();
-        return client;
+    try {
+        process.kill(pid, 0);
+        return true;
     }
-    onEvent(listener) {
-        this.eventListeners.add(listener);
-        return () => {
-            this.eventListeners.delete(listener);
-        };
+    catch (error) {
+        return error.code === 'EPERM';
     }
-    queryEvents(filter) {
-        let events = [...this.eventBuffer];
-        if (filter?.kind) {
-            events = events.filter((event) => event.kind === filter.kind);
+}
+// ── Client ─────────────────────────────────────────────────────────────
+export class AgentRelayClient {
+    transport;
+    /** Set after spawn() — the managed child process. */
+    child = null;
+    /** Lease renewal timer (only for spawned brokers). */
+    leaseTimer = null;
+    workspaceKey;
+    constructor(options) {
+        this.transport = new BrokerTransport({
+            baseUrl: options.baseUrl,
+            apiKey: options.apiKey,
+            requestTimeoutMs: options.requestTimeoutMs,
+        });
+    }
+    /**
+     * Connect to an already-running broker by reading its connection file.
+     *
+     * The broker writes `connection.json` to its data directory ({cwd}/.agent-relay/
+     * in persist mode). This method reads that file to get the URL and API key.
+     *
+     * @param cwd — project directory (default: process.cwd())
+     * @param connectionPath — explicit path to connection.json (overrides cwd)
+     */
+    static connect(options) {
+        const cwd = options?.cwd ?? process.cwd();
+        const stateDir = process.env.AGENT_RELAY_STATE_DIR;
+        const connPath = options?.connectionPath ?? path.join(stateDir ?? path.join(cwd, '.agent-relay'), 'connection.json');
+        if (!existsSync(connPath)) {
+            throw new Error(`No running broker found (${connPath} does not exist). Start one with 'agent-relay up' or use AgentRelayClient.spawn().`);
         }
-        if (filter?.name) {
-            events = events.filter((event) => 'name' in event && event.name === filter.name);
+        const raw = readFileSync(connPath, 'utf-8');
+        let conn;
+        try {
+            conn = JSON.parse(raw);
         }
-        const since = filter?.since;
-        if (since !== undefined) {
-            events = events.filter((event) => 'timestamp' in event && typeof event.timestamp === 'number' && event.timestamp >= since);
+        catch {
+            throw new Error(`Corrupt broker connection file (${connPath}). Remove it and start the broker again.`);
         }
-        const limit = filter?.limit;
-        if (limit !== undefined) {
-            events = events.slice(-limit);
+        if (typeof conn.url !== 'string' || typeof conn.api_key !== 'string' || typeof conn.pid !== 'number') {
+            throw new Error(`Invalid broker connection metadata in ${connPath}. Remove it and start the broker again.`);
         }
-        return events;
-    }
-    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;
-            }
+        if (!isProcessRunning(conn.pid)) {
+            throw new Error(`Stale broker connection file (${connPath}) points to dead pid ${conn.pid}. Start the broker with 'agent-relay up' or use AgentRelayClient.spawn().`);
         }
-        return undefined;
+        return new AgentRelayClient({ baseUrl: conn.url, apiKey: conn.api_key });
     }
-    onBrokerStderr(listener) {
-        this.stderrListeners.add(listener);
-        return () => {
-            this.stderrListeners.delete(listener);
+    /**
+     * Spawn a local broker process and return a connected client.
+     *
+     * 1. Generates a random API key
+     * 2. Spawns the broker binary (attached)
+     * 3. Parses the API port from stdout
+     * 4. Connects HTTP/WS transport
+     * 5. Fetches session metadata
+     * 6. Starts event stream + lease renewal
+     */
+    static async spawn(options) {
+        const binaryPath = options?.binaryPath ?? getBrokerBinaryPath() ?? 'agent-relay-broker';
+        const cwd = options?.cwd ?? process.cwd();
+        const brokerName = options?.brokerName ?? (path.basename(cwd) || 'project');
+        const channels = options?.channels ?? ['general'];
+        const timeoutMs = options?.startupTimeoutMs ?? 15_000;
+        const userArgs = options?.binaryArgs ?? [];
+        const apiKey = `br_${randomBytes(16).toString('hex')}`;
+        const env = {
+            ...process.env,
+            ...options?.env,
+            RELAY_BROKER_API_KEY: apiKey,
         };
+        const args = ['init', '--name', brokerName, '--channels', channels.join(','), ...userArgs];
+        const child = spawn(binaryPath, args, {
+            cwd,
+            env,
+            stdio: ['ignore', 'pipe', options?.onStderr ? 'pipe' : 'ignore'],
+        });
+        // Forward stderr if requested
+        if (options?.onStderr && child.stderr) {
+            const { createInterface } = await import('node:readline');
+            const rl = createInterface({ input: child.stderr });
+            rl.on('line', (line) => options.onStderr(line));
+        }
+        // Parse the API URL from stdout (the broker prints it after binding)
+        const baseUrl = await waitForApiUrl(child, timeoutMs);
+        const client = new AgentRelayClient({
+            baseUrl,
+            apiKey,
+            requestTimeoutMs: options?.requestTimeoutMs,
+        });
+        client.child = child;
+        await client.getSession();
+        client.connectEvents();
+        // Renew the owner lease so the broker doesn't auto-shutdown
+        client.leaseTimer = setInterval(() => {
+            client.renewLease().catch(() => { });
+        }, 60_000);
+        child.on('exit', () => {
+            client.disconnectEvents();
+            if (client.leaseTimer) {
+                clearInterval(client.leaseTimer);
+                client.leaseTimer = null;
+            }
+        });
+        return client;
     }
+    /** PID of the managed broker process, if spawned locally. */
     get brokerPid() {
         return this.child?.pid;
     }
-    async start() {
-        if (this.child) {
-            return;
-        }
-        if (this.startingPromise) {
-            return this.startingPromise;
-        }
-        this.startingPromise = this.startInternal();
-        try {
-            await this.startingPromise;
-        }
-        finally {
-            this.startingPromise = undefined;
-        }
+    // ── Session ────────────────────────────────────────────────────────
+    async getSession() {
+        const session = await this.transport.request('/api/session');
+        this.workspaceKey = session.workspace_key;
+        return session;
     }
-    /**
-     * Pre-register a batch of agents with Relaycast before their steps execute.
-     * The broker warms its token cache in parallel; subsequent spawn_agent calls
-     * hit the cache rather than waiting on individual HTTP registrations.
-     * Fire-and-forget from the caller's perspective — broker responds immediately
-     * and registers in the background.
-     */
-    async preflightAgents(agents) {
-        if (agents.length === 0)
-            return;
-        await this.start();
-        await this.requestOk('preflight_agents', { agents });
+    async healthCheck() {
+        return this.transport.request('/health');
     }
-    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 } : {}),
-            ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
-        });
-        return result;
+    // ── Events ─────────────────────────────────────────────────────────
+    connectEvents(sinceSeq) {
+        this.transport.connect(sinceSeq);
     }
-    async spawnHeadless(input) {
-        await this.start();
-        const agent = {
-            name: input.name,
-            runtime: 'headless',
-            provider: input.provider,
-            args: input.args ?? [],
-            channels: input.channels ?? [],
-        };
-        const result = await this.requestOk('spawn_agent', {
-            agent,
-            ...(input.task != null ? { initial_task: input.task } : {}),
-            ...(input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}),
+    disconnectEvents() {
+        this.transport.disconnect();
+    }
+    onEvent(listener) {
+        return this.transport.onEvent(listener);
+    }
+    queryEvents(filter) {
+        return this.transport.queryEvents(filter);
+    }
+    getLastEvent(kind, name) {
+        return this.transport.getLastEvent(kind, name);
+    }
+    // ── Agent lifecycle ────────────────────────────────────────────────
+    async spawnPty(input) {
+        return this.transport.request('/api/spawn', {
+            method: 'POST',
+            body: JSON.stringify({
+                name: input.name,
+                cli: input.cli,
+                model: input.model,
+                args: input.args ?? [],
+                task: input.task,
+                channels: input.channels ?? [],
+                cwd: input.cwd,
+                team: input.team,
+                shadowOf: input.shadowOf,
+                shadowMode: input.shadowMode,
+                continueFrom: input.continueFrom,
+                idleThresholdSecs: input.idleThresholdSecs,
+                restartPolicy: input.restartPolicy,
+                skipRelayPrompt: input.skipRelayPrompt,
+            }),
         });
-        return result;
     }
     async spawnProvider(input) {
-        const transport = input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
-        if (transport === 'headless') {
-            if (!isHeadlessProvider(input.provider)) {
-                throw new AgentRelayProcessError(`provider '${input.provider}' does not support headless transport (supported: claude, opencode)`);
-            }
-            return this.spawnHeadless({
+        const transport = resolveSpawnTransport(input);
+        if (transport === 'headless' && !isHeadlessProvider(input.provider)) {
+            throw new Error(`provider '${input.provider}' does not support headless transport (supported: claude, opencode)`);
+        }
+        return this.transport.request('/api/spawn', {
+            method: 'POST',
+            body: JSON.stringify({
                 name: input.name,
-                provider: input.provider,
-                args: input.args,
-                channels: input.channels,
+                cli: input.provider,
+                model: input.model,
+                args: input.args ?? [],
                 task: input.task,
+                channels: input.channels ?? [],
+                cwd: input.cwd,
+                team: input.team,
+                shadowOf: input.shadowOf,
+                shadowMode: input.shadowMode,
+                continueFrom: input.continueFrom,
+                idleThresholdSecs: input.idleThresholdSecs,
+                restartPolicy: input.restartPolicy,
                 skipRelayPrompt: input.skipRelayPrompt,
-            });
-        }
-        return this.spawnPty({
-            name: input.name,
-            cli: input.provider,
-            args: input.args,
-            channels: input.channels,
-            task: input.task,
-            model: input.model,
-            cwd: input.cwd,
-            team: input.team,
-            shadowOf: input.shadowOf,
-            shadowMode: input.shadowMode,
-            idleThresholdSecs: input.idleThresholdSecs,
-            restartPolicy: input.restartPolicy,
-            continueFrom: input.continueFrom,
-            skipRelayPrompt: input.skipRelayPrompt,
+                transport,
+            }),
         });
     }
+    async spawnHeadless(input) {
+        return this.spawnProvider({ ...input, transport: 'headless' });
+    }
     async spawnClaude(input) {
         return this.spawnProvider({ ...input, provider: 'claude' });
     }
@@ -213,58 +225,44 @@ export class AgentRelayClient {
         return this.spawnProvider({ ...input, provider: 'opencode' });
     }
     async release(name, reason) {
-        await this.start();
-        return this.requestOk('release_agent', { name, reason });
-    }
-    async sendInput(name, data) {
-        await this.start();
-        return this.requestOk('send_input', { name, data });
-    }
-    async subscribeChannels(name, channels) {
-        await this.start();
-        await this.requestOk('subscribe_channels', { name, channels });
+        return this.transport.request(`/api/spawned/${encodeURIComponent(name)}`, {
+            method: 'DELETE',
+            ...(reason ? { body: JSON.stringify({ reason }) } : {}),
+        });
     }
-    async unsubscribeChannels(name, channels) {
-        await this.start();
-        await this.requestOk('unsubscribe_channels', { name, channels });
+    async listAgents() {
+        const result = await this.transport.request('/api/spawned');
+        return result.agents;
     }
-    async resizePty(name, rows, cols) {
-        await this.start();
-        return this.requestOk('resize_pty', {
-            name,
-            rows,
-            cols,
+    // ── PTY control ────────────────────────────────────────────────────
+    async sendInput(name, data) {
+        return this.transport.request(`/api/input/${encodeURIComponent(name)}`, {
+            method: 'POST',
+            body: JSON.stringify({ data }),
         });
     }
-    async setModel(name, model, opts) {
-        await this.start();
-        return this.requestOk('set_model', {
-            name,
-            model,
-            timeout_ms: opts?.timeoutMs,
+    async resizePty(name, rows, cols) {
+        return this.transport.request(`/api/resize/${encodeURIComponent(name)}`, {
+            method: 'POST',
+            body: JSON.stringify({ rows, cols }),
         });
     }
-    async getMetrics(agent) {
-        await this.start();
-        return this.requestOk('get_metrics', { agent });
-    }
-    async getCrashInsights() {
-        await this.start();
-        return this.requestOk('get_crash_insights', {});
-    }
+    // ── Messaging ──────────────────────────────────────────────────────
     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,
-                workspace_id: input.workspaceId,
-                workspace_alias: input.workspaceAlias,
-                priority: input.priority,
-                data: input.data,
-                mode: input.mode,
+            return await this.transport.request('/api/send', {
+                method: 'POST',
+                body: JSON.stringify({
+                    to: input.to,
+                    text: input.text,
+                    from: input.from,
+                    threadId: input.threadId,
+                    workspaceId: input.workspaceId,
+                    workspaceAlias: input.workspaceAlias,
+                    priority: input.priority,
+                    data: input.data,
+                    mode: input.mode,
+                }),
             });
         }
         catch (error) {
@@ -274,636 +272,150 @@ export class AgentRelayClient {
             throw error;
         }
     }
-    async listAgents() {
-        await this.start();
-        const result = await this.requestOk('list_agents', {});
-        return result.agents;
-    }
-    async getStatus() {
-        await this.start();
-        return this.requestOk('get_status', {});
-    }
-    async shutdown() {
-        if (!this.child) {
-            return;
-        }
-        void this.requestOk('shutdown', {}).catch(() => {
-            // Continue shutdown path if broker is already unhealthy or exits before replying.
+    // ── Model control ──────────────────────────────────────────────────
+    async setModel(name, model, opts) {
+        return this.transport.request(`/api/spawned/${encodeURIComponent(name)}/model`, {
+            method: 'POST',
+            body: JSON.stringify({ model, timeout_ms: opts?.timeoutMs }),
         });
-        const child = this.child;
-        const wait = this.exitPromise ?? Promise.resolve();
-        const waitForExit = async (timeoutMs) => {
-            let timer;
-            const result = await Promise.race([
-                wait.then(() => true),
-                new Promise((resolve) => {
-                    timer = setTimeout(() => resolve(false), timeoutMs);
-                }),
-            ]);
-            if (timer !== undefined)
-                clearTimeout(timer);
-            return result;
-        };
-        if (await waitForExit(this.options.shutdownTimeoutMs)) {
-            return;
-        }
-        if (child.exitCode === null && child.signalCode === null) {
-            child.kill('SIGTERM');
-        }
-        if (await waitForExit(1_000)) {
-            return;
-        }
-        if (child.exitCode === null && child.signalCode === null) {
-            child.kill('SIGKILL');
-        }
-        await waitForExit(1_000);
-    }
-    async waitForExit() {
-        if (!this.child) {
-            return;
-        }
-        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,
-            ...(this.options.channels.length > 0 ? ['--channels', this.options.channels.join(',')] : []),
-            ...this.options.binaryArgs,
-        ];
-        // Ensure the SDK bin directory (containing agent-relay-broker) is on
-        // PATH so spawned workers can find it without any user setup.
-        const env = { ...this.options.env };
-        if (isExplicitPath(this.options.binaryPath)) {
-            const binDir = path.dirname(path.resolve(resolvedBinary));
-            const currentPath = env.PATH ?? env.Path ?? '';
-            if (!currentPath.split(path.delimiter).includes(binDir)) {
-                env.PATH = `${binDir}${path.delimiter}${currentPath}`;
-            }
-        }
-        console.error(`[broker] Starting: ${resolvedBinary} ${args.join(' ')}`);
-        const child = spawn(resolvedBinary, args, {
-            cwd: this.options.cwd,
-            env,
-            stdio: 'pipe',
-        });
-        this.child = child;
-        this.stdoutRl = createInterface({ input: child.stdout, crlfDelay: Infinity });
-        this.stderrRl = createInterface({ input: child.stderr, crlfDelay: Infinity });
-        this.stdoutRl.on('line', (line) => {
-            this.handleStdoutLine(line);
-        });
-        this.stderrRl.on('line', (line) => {
-            const trimmed = line.trim();
-            if (trimmed) {
-                this.lastStderrLine = trimmed;
-            }
-            for (const listener of this.stderrListeners) {
-                listener(line);
-            }
+    // ── Channels ───────────────────────────────────────────────────────
+    async subscribeChannels(name, channels) {
+        await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/subscribe`, {
+            method: 'POST',
+            body: JSON.stringify({ channels }),
         });
-        this.exitPromise = new Promise((resolve) => {
-            // Use 'close' instead of 'exit' so that all buffered stderr/stdout
-            // data has been consumed before we build the error message.  The
-            // 'exit' event fires when the process terminates, but stdio streams
-            // may still have unread data; 'close' fires after both the process
-            // exits AND all stdio streams have ended.
-            child.once('close', (code, signal) => {
-                const detail = this.lastStderrLine ? `: ${this.lastStderrLine}` : '';
-                const error = new AgentRelayProcessError(`broker exited (code=${code ?? 'null'}, signal=${signal ?? 'null'})${detail}`);
-                this.failAllPending(error);
-                this.disposeProcessHandles();
-                resolve();
-            });
-            child.once('error', (error) => {
-                this.failAllPending(error);
-                this.disposeProcessHandles();
-                resolve();
-            });
+    }
+    async unsubscribeChannels(name, channels) {
+        await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/unsubscribe`, {
+            method: 'POST',
+            body: JSON.stringify({ channels }),
         });
-        const helloAck = await this.requestHello();
-        console.error('[broker] Broker ready (hello handshake complete)');
-        if (helloAck.workspace_key) {
-            this.workspaceKey = helloAck.workspace_key;
-        }
     }
-    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();
+    // ── Observability ──────────────────────────────────────────────────
+    async getMetrics(agent) {
+        const query = agent ? `?agent=${encodeURIComponent(agent)}` : '';
+        return this.transport.request(`/api/metrics${query}`);
     }
-    handleStdoutLine(line) {
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch {
-            // Non-protocol output should not crash the SDK.
-            return;
-        }
-        if (!parsed || typeof parsed !== 'object') {
-            return;
-        }
-        if (parsed.v !== PROTOCOL_VERSION || typeof parsed.type !== 'string') {
-            return;
-        }
-        const envelope = {
-            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);
-            }
-            return;
-        }
-        if (!envelope.request_id) {
-            return;
-        }
-        const pending = this.pending.get(envelope.request_id);
-        if (!pending) {
-            return;
-        }
-        if (envelope.type === 'error') {
-            clearTimeout(pending.timeout);
-            this.pending.delete(envelope.request_id);
-            pending.reject(new AgentRelayProtocolError(envelope.payload));
-            return;
-        }
-        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);
-    }
-    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;
+    async getStatus() {
+        return this.transport.request('/api/status');
     }
-    async requestOk(type, payload) {
-        const frame = await this.sendRequest(type, payload, 'ok');
-        const result = frame.payload;
-        return result.result;
+    async getCrashInsights() {
+        return this.transport.request('/api/crash-insights');
     }
-    async sendRequest(type, payload, expectedType) {
-        if (!this.child) {
-            throw new AgentRelayProcessError('broker is not running');
-        }
-        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,
-            });
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    async preflight(agents) {
+        return this.transport.request('/api/preflight', {
+            method: 'POST',
+            body: JSON.stringify({ agents }),
         });
-        const line = `${JSON.stringify(message)}\n`;
-        if (!this.child.stdin.write(line)) {
-            await once(this.child.stdin, 'drain');
-        }
-        return responsePromise;
-    }
-}
-const CLI_MODEL_FLAG_CLIS = new Set(['claude', 'codex', 'gemini', 'goose', 'aider']);
-const CLI_DEFAULT_ARGS = {
-    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;
-    }
-    if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
-        return baseArgs;
-    }
-    if (hasModelArg(baseArgs)) {
-        return baseArgs;
-    }
-    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;
-        }
-        if (arg.startsWith('--model=')) {
-            return true;
-        }
     }
-    return false;
-}
-function expandTilde(p) {
-    if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
-        const home = os.homedir();
-        return path.join(home, p.slice(2));
+    async renewLease() {
+        return this.transport.request('/api/session/renew', { method: 'POST' });
     }
-    return p;
-}
-function isExplicitPath(binaryPath) {
-    return (binaryPath.includes('/') ||
-        binaryPath.includes('\\') ||
-        binaryPath.startsWith('.') ||
-        binaryPath.startsWith('~'));
-}
-function detectPlatformSuffix() {
-    const platformMap = {
-        darwin: { arm64: 'darwin-arm64', x64: 'darwin-x64' },
-        linux: { arm64: 'linux-arm64', x64: 'linux-x64' },
-        win32: { x64: 'win32-x64' },
-    };
-    return platformMap[process.platform]?.[process.arch] ?? null;
-}
-function getLatestVersionSync() {
-    try {
-        const result = execSync('curl -fsSL https://api.github.com/repos/AgentWorkforce/relay/releases/latest', {
-            timeout: 15_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).toString();
-        const match = result.match(/"tag_name"\s*:\s*"([^"]+)"/);
-        if (!match?.[1])
-            return null;
-        // Strip tag prefixes: "openclaw-v3.1.18" -> "3.1.18", "v3.1.18" -> "3.1.18"
-        return match[1].replace(/^openclaw-/, '').replace(/^v/, '');
-    }
-    catch {
-        return null;
-    }
-}
-function installBrokerBinary() {
-    const suffix = detectPlatformSuffix();
-    if (!suffix) {
-        throw new AgentRelayProcessError(`Unsupported platform: ${process.platform}-${process.arch}`);
-    }
-    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    const installDir = path.join(homeDir, '.agent-relay', 'bin');
-    const brokerExe = process.platform === 'win32' ? 'agent-relay-broker.exe' : 'agent-relay-broker';
-    const targetPath = path.join(installDir, brokerExe);
-    console.log(`[agent-relay] Broker binary not found, installing for ${suffix}...`);
-    const version = getLatestVersionSync();
-    if (!version) {
-        throw new AgentRelayProcessError('Failed to fetch latest agent-relay version from GitHub.\n' +
-            'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash');
-    }
-    const binaryName = `agent-relay-broker-${suffix}`;
-    const downloadUrl = `https://github.com/AgentWorkforce/relay/releases/download/v${version}/${binaryName}`;
-    console.log(`[agent-relay] Downloading v${version} from ${downloadUrl}`);
-    try {
-        fs.mkdirSync(installDir, { recursive: true });
-        execSync(`curl -fsSL "${downloadUrl}" -o "${targetPath}"`, {
-            timeout: 60_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        fs.chmodSync(targetPath, 0o755);
-        // macOS: strip quarantine attribute and re-sign to avoid Gatekeeper issues
-        if (process.platform === 'darwin') {
-            try {
-                execSync(`xattr -d com.apple.quarantine "${targetPath}" 2>/dev/null || true`, {
-                    timeout: 10_000,
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                });
-            }
-            catch {
-                // Non-fatal
-            }
+    /**
+     * Shut down and clean up.
+     * - For spawned brokers (via .spawn()): sends POST /api/shutdown to kill the broker, waits for exit.
+     * - For connected brokers (via .connect() or constructor): just disconnects the transport.
+     *   Does NOT kill the broker — the caller doesn't own it.
+     */
+    async shutdown() {
+        if (this.leaseTimer) {
+            clearInterval(this.leaseTimer);
+            this.leaseTimer = null;
+        }
+        // Only send the shutdown command if we own the broker process
+        if (this.child) {
             try {
-                execSync(`codesign --force --sign - "${targetPath}"`, {
-                    timeout: 10_000,
-                    stdio: ['pipe', 'pipe', 'pipe'],
-                });
+                await this.transport.request('/api/shutdown', { method: 'POST' });
             }
             catch {
-                // Non-fatal
+                // Broker may already be dead
             }
         }
-        // Verify
-        execSync(`"${targetPath}" --help`, { timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] });
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(targetPath);
-        }
-        catch {
-            /* ignore */
+        this.transport.disconnect();
+        if (this.child) {
+            await waitForExit(this.child, 5000);
+            this.child = null;
         }
-        const message = err instanceof Error ? err.message : String(err);
-        throw new AgentRelayProcessError(`Failed to install broker binary: ${message}\n` +
-            'Install manually: curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash');
     }
-    console.log(`[agent-relay] Broker installed to ${targetPath}`);
-    return targetPath;
-}
-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 platform-specific broker binary in SDK package (npm install).
-    //    Only use binaries that match the current platform to avoid running
-    //    e.g. a macOS binary on Linux (or vice-versa).
-    const binDir = path.resolve(moduleDir, '..', 'bin');
-    const suffix = detectPlatformSuffix();
-    if (suffix) {
-        const ext = process.platform === 'win32' ? '.exe' : '';
-        const platformBinary = path.join(binDir, `agent-relay-broker-${suffix}${ext}`);
-        if (fs.existsSync(platformBinary)) {
-            return platformBinary;
+    /** Disconnect without shutting down the broker. Alias for cases where the intent is clear. */
+    disconnect() {
+        if (this.leaseTimer) {
+            clearInterval(this.leaseTimer);
+            this.leaseTimer = null;
         }
+        this.transport.disconnect();
     }
-    // 3. Check for standalone broker binary in ~/.agent-relay/bin/ (install.sh)
-    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-    const standaloneBroker = path.join(homeDir, '.agent-relay', 'bin', brokerExe);
-    if (fs.existsSync(standaloneBroker)) {
-        return standaloneBroker;
+    async getConfig() {
+        return this.transport.request('/api/config');
     }
-    // 4. Auto-install from GitHub releases
-    return installBrokerBinary();
-}
-const DEFAULT_DASHBOARD_PORT = (() => {
-    const envPort = typeof process !== 'undefined' ? process.env.AGENT_RELAY_DASHBOARD_PORT : undefined;
-    if (envPort) {
-        const parsed = Number.parseInt(envPort, 10);
-        if (Number.isFinite(parsed) && parsed > 0)
-            return parsed;
-    }
-    return 3888;
-})();
-const HTTP_MAX_PORT_SCAN = 25;
-const HTTP_AUTOSTART_TIMEOUT_MS = 10_000;
-const HTTP_AUTOSTART_POLL_MS = 250;
-function sanitizeBrokerName(name) {
-    return name.replace(/[^\p{L}\p{N}-]/gu, '-');
 }
-function brokerPidFilename(projectRoot) {
-    const brokerName = path.basename(projectRoot) || 'project';
-    return `broker-${sanitizeBrokerName(brokerName)}.pid`;
-}
-export class HttpAgentRelayClient {
-    port;
-    apiKey;
-    constructor(options) {
-        this.port = options.port;
-        this.apiKey = options.apiKey;
-    }
-    /**
-     * Connect to an already-running broker on the given port.
-     */
-    static async connectHttp(port, options) {
-        const client = new HttpAgentRelayClient({ port, apiKey: options?.apiKey });
-        // Verify connectivity
-        await client.healthCheck();
-        return client;
-    }
-    /**
-     * Discover a running broker for the current project and connect to it.
-     * Reads the broker PID file, verifies the process is alive, scans ports
-     * for the HTTP API, and returns a connected client.
-     */
-    static async discoverAndConnect(options) {
-        const cwd = options?.cwd ?? process.cwd();
-        const apiKey = options?.apiKey ?? process.env.RELAY_BROKER_API_KEY?.trim();
-        const autoStart = options?.autoStart ?? false;
-        const paths = getProjectPaths(cwd);
-        const preferredApiPort = DEFAULT_DASHBOARD_PORT + 1;
-        // Try to find a running broker via PID file
-        const pidFilePath = path.join(paths.dataDir, brokerPidFilename(paths.projectRoot));
-        const legacyPidPath = path.join(paths.dataDir, 'broker.pid');
-        let brokerRunning = false;
-        for (const pidPath of [pidFilePath, legacyPidPath]) {
-            if (fs.existsSync(pidPath)) {
-                const pidStr = fs.readFileSync(pidPath, 'utf-8').trim();
-                const pid = Number.parseInt(pidStr, 10);
-                if (Number.isFinite(pid) && pid > 0) {
-                    try {
-                        process.kill(pid, 0);
-                        brokerRunning = true;
-                        break;
-                    }
-                    catch {
-                        // Process not running
-                    }
-                }
-            }
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Parse the API URL from the broker's stdout. The broker prints:
+ *   [agent-relay] API listening on http://{bind}:{port}
+ * Returns the full URL (e.g. "http://127.0.0.1:3889").
+ */
+async function waitForApiUrl(child, timeoutMs) {
+    const { createInterface } = await import('node:readline');
+    return new Promise((resolve, reject) => {
+        if (!child.stdout) {
+            reject(new Error('Broker stdout not available'));
+            return;
         }
-        if (brokerRunning) {
-            const port = await HttpAgentRelayClient.scanForBrokerPort(preferredApiPort);
-            if (port !== null) {
-                return new HttpAgentRelayClient({ port, apiKey });
+        let resolved = false;
+        const rl = createInterface({ input: child.stdout });
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                rl.close();
+                reject(new Error(`Broker did not report API port within ${timeoutMs}ms`));
             }
-            throw new AgentRelayProcessError('broker is running for this project, but its local API is unavailable');
-        }
-        if (!autoStart) {
-            throw new AgentRelayProcessError('broker is not running for this project');
-        }
-        // Auto-start the broker using the resolved binary path (not process.argv[1],
-        // which only works from CLI context — breaks when SDK is imported by user apps).
-        // The broker binary requires the `init` subcommand with `--api-port` and
-        // `--persist` so it writes PID files for subsequent discovery.
-        const brokerBinary = options?.brokerBinaryPath ?? resolveDefaultBinaryPath();
-        const child = spawn(brokerBinary, ['init', '--persist', '--api-port', String(preferredApiPort)], {
-            cwd: paths.projectRoot,
-            env: process.env,
-            detached: true,
-            stdio: 'ignore',
-        });
-        child.unref();
-        const startedAt = Date.now();
-        while (Date.now() - startedAt < HTTP_AUTOSTART_TIMEOUT_MS) {
-            const port = await HttpAgentRelayClient.scanForBrokerPort(preferredApiPort);
-            if (port !== null) {
-                return new HttpAgentRelayClient({ port, apiKey });
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                rl.close();
+                reject(new Error(`Broker process exited with code ${code} before becoming ready`));
             }
-            await new Promise((resolve) => setTimeout(resolve, HTTP_AUTOSTART_POLL_MS));
-        }
-        throw new AgentRelayProcessError(`broker did not become ready within ${HTTP_AUTOSTART_TIMEOUT_MS}ms`);
-    }
-    static async scanForBrokerPort(startPort) {
-        for (let i = 0; i < HTTP_MAX_PORT_SCAN; i++) {
-            const port = startPort + i;
-            try {
-                const res = await fetch(`http://127.0.0.1:${port}/health`);
-                if (!res.ok)
-                    continue;
-                const payload = (await res.json().catch(() => null));
-                if (payload?.service === 'agent-relay-listen') {
-                    return port;
-                }
+        });
+        child.on('error', (err) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                rl.close();
+                reject(new Error(`Failed to start broker: ${err.message}`));
             }
-            catch {
-                // Keep scanning
+        });
+        rl.on('line', (line) => {
+            if (resolved)
+                return;
+            const match = line.match(/API listening on (https?:\/\/[^\s]+)/);
+            if (match) {
+                resolved = true;
+                clearTimeout(timer);
+                rl.close();
+                resolve(match[1]);
             }
-        }
-        return null;
-    }
-    async request(pathname, init) {
-        const headers = new Headers(init?.headers);
-        if (this.apiKey && !headers.has('x-api-key') && !headers.has('authorization')) {
-            headers.set('x-api-key', this.apiKey);
-        }
-        const response = await fetch(`http://127.0.0.1:${this.port}${pathname}`, {
-            ...init,
-            headers,
         });
-        const text = await response.text();
-        let payload;
-        try {
-            payload = text ? JSON.parse(text) : undefined;
-        }
-        catch {
-            payload = text;
-        }
-        if (!response.ok) {
-            const msg = HttpAgentRelayClient.extractErrorMessage(response, payload);
-            throw new AgentRelayProcessError(msg);
+    });
+}
+function waitForExit(child, timeoutMs) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null) {
+            resolve();
+            return;
         }
-        return payload;
-    }
-    static extractErrorMessage(response, payload) {
-        if (typeof payload === 'string' && payload.trim())
-            return payload.trim();
-        const p = payload;
-        if (typeof p?.error === 'string')
-            return p.error;
-        if (typeof p?.error?.message === 'string')
-            return p.error.message;
-        if (typeof p?.message === 'string' && p.message.trim())
-            return p.message.trim();
-        return `${response.status} ${response.statusText}`.trim();
-    }
-    async healthCheck() {
-        return this.request('/health');
-    }
-    /** No-op — broker is already running. */
-    async start() { }
-    /** No-op — don't kill an externally-managed broker. */
-    async shutdown() { }
-    async spawnPty(input) {
-        const payload = await this.request('/api/spawn', {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                name: input.name,
-                cli: input.cli,
-                model: input.model,
-                args: input.args ?? [],
-                task: input.task,
-                channels: input.channels ?? [],
-                cwd: input.cwd,
-                team: input.team,
-                shadowOf: input.shadowOf,
-                shadowMode: input.shadowMode,
-                continueFrom: input.continueFrom,
-                idleThresholdSecs: input.idleThresholdSecs,
-                restartPolicy: input.restartPolicy,
-                skipRelayPrompt: input.skipRelayPrompt,
-            }),
-        });
-        return {
-            name: typeof payload?.name === 'string' ? payload.name : input.name,
-            runtime: 'pty',
-        };
-    }
-    async sendMessage(input) {
-        return this.request('/api/send', {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-                to: input.to,
-                text: input.text,
-                from: input.from,
-                threadId: input.threadId,
-                workspaceId: input.workspaceId,
-                workspaceAlias: input.workspaceAlias,
-                priority: input.priority,
-                data: input.data,
-                mode: input.mode,
-            }),
-        });
-    }
-    async listAgents() {
-        const payload = await this.request('/api/spawned', { method: 'GET' });
-        return Array.isArray(payload?.agents) ? payload.agents : [];
-    }
-    async release(name, reason) {
-        const payload = await this.request(`/api/spawned/${encodeURIComponent(name)}`, {
-            method: 'DELETE',
-            ...(reason
-                ? { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ reason }) }
-                : {}),
-        });
-        return { name: typeof payload?.name === 'string' ? payload.name : name };
-    }
-    async subscribeChannels(_name, _channels) {
-        throw new Error('subscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
-            'The HTTP API does not support dynamic channel subscription.');
-    }
-    async unsubscribeChannels(_name, _channels) {
-        throw new Error('unsubscribeChannels is only available via the broker protocol (BrokerAgentRelayClient). ' +
-            'The HTTP API does not support dynamic channel unsubscription.');
-    }
-    async setModel(name, model, opts) {
-        const payload = await this.request(`/api/spawned/${encodeURIComponent(name)}/model`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ model, timeoutMs: opts?.timeoutMs }),
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            resolve();
+        }, timeoutMs);
+        child.on('exit', () => {
+            clearTimeout(timer);
+            resolve();
         });
-        return {
-            name,
-            model: typeof payload?.model === 'string' ? payload.model : model,
-            success: payload?.success !== false,
-        };
-    }
-    async getConfig() {
-        return this.request('/api/config');
-    }
+    });
 }
 //# sourceMappingURL=client.js.map