@agent-relay/sdk 7.1.1 → 8.0.1

package/dist/client.js

@@ -1,838 +0,0 @@
-/**
- * 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 { BrokerTransport, AgentRelayProtocolError, } from './transport.js';
-import { getBrokerBinaryPath, formatBrokerNotFoundError } from './broker-path.js';
-import { EventBus } from './event-bus.js';
-function isHeadlessProvider(value) {
-    return value === 'claude' || value === 'opencode';
-}
-function resolveSpawnTransport(input) {
-    return input.transport ?? (input.provider === 'opencode' ? 'headless' : 'pty');
-}
-/**
- * Serialize a {@link SpawnPtyInput} for the broker `/api/spawn` endpoint.
- * Factored out of {@link AgentRelayClient.spawnPty} so the same shape can
- * be applied to the post-`beforeAgentSpawn` resolved input.
- */
-function buildSpawnPtyBody(input) {
-    return {
-        name: input.name,
-        cli: input.cli,
-        ...(input.model !== undefined ? { model: input.model } : {}),
-        args: input.args ?? [],
-        ...(input.task !== undefined ? { task: input.task } : {}),
-        channels: input.channels ?? [],
-        ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
-        ...(input.team !== undefined ? { team: input.team } : {}),
-        ...(input.agentToken !== undefined ? { agentToken: input.agentToken } : {}),
-        ...(input.shadowOf !== undefined ? { shadowOf: input.shadowOf } : {}),
-        ...(input.shadowMode !== undefined ? { shadowMode: input.shadowMode } : {}),
-        ...(input.continueFrom !== undefined ? { continueFrom: input.continueFrom } : {}),
-        ...(input.idleThresholdSecs !== undefined ? { idleThresholdSecs: input.idleThresholdSecs } : {}),
-        ...(input.restartPolicy !== undefined ? { restartPolicy: input.restartPolicy } : {}),
-        ...(input.skipRelayPrompt !== undefined ? { skipRelayPrompt: input.skipRelayPrompt } : {}),
-        ...(input.agentResultSchema !== undefined ? { agentResultSchema: input.agentResultSchema } : {}),
-    };
-}
-function buildSpawnProviderBody(input, transport) {
-    return {
-        name: input.name,
-        cli: input.provider,
-        ...(input.model !== undefined ? { model: input.model } : {}),
-        args: input.args ?? [],
-        ...(input.task !== undefined ? { task: input.task } : {}),
-        channels: input.channels ?? [],
-        ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
-        ...(input.team !== undefined ? { team: input.team } : {}),
-        ...(input.agentToken !== undefined ? { agentToken: input.agentToken } : {}),
-        ...(input.shadowOf !== undefined ? { shadowOf: input.shadowOf } : {}),
-        ...(input.shadowMode !== undefined ? { shadowMode: input.shadowMode } : {}),
-        ...(input.continueFrom !== undefined ? { continueFrom: input.continueFrom } : {}),
-        ...(input.idleThresholdSecs !== undefined ? { idleThresholdSecs: input.idleThresholdSecs } : {}),
-        ...(input.restartPolicy !== undefined ? { restartPolicy: input.restartPolicy } : {}),
-        ...(input.skipRelayPrompt !== undefined ? { skipRelayPrompt: input.skipRelayPrompt } : {}),
-        ...(input.agentResultSchema !== undefined ? { agentResultSchema: input.agentResultSchema } : {}),
-        transport,
-    };
-}
-function isProcessRunning(pid) {
-    if (!Number.isInteger(pid) || pid <= 0) {
-        return false;
-    }
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === 'EPERM';
-    }
-}
-function buildBrokerInitArgs(args) {
-    if (!args) {
-        return [];
-    }
-    const cliArgs = [];
-    if (args.persist) {
-        cliArgs.push('--persist');
-    }
-    if (args.apiPort !== undefined) {
-        cliArgs.push('--api-port', String(args.apiPort));
-    }
-    if (args.apiBind !== undefined) {
-        cliArgs.push('--api-bind', args.apiBind);
-    }
-    if (args.stateDir !== undefined) {
-        cliArgs.push('--state-dir', args.stateDir);
-    }
-    return cliArgs;
-}
-// ── Client ─────────────────────────────────────────────────────────────
-export class AgentRelayClient {
-    transport;
-    /** Set after spawn() — the managed child process. */
-    child = null;
-    /** Lease renewal timer (only for spawned brokers). */
-    leaseTimer = null;
-    brokerExitInfo = null;
-    brokerExitListeners = new Set();
-    workspaceKey;
-    /** Resolved broker URL — captured so call-site lifecycle contexts can surface it. */
-    baseUrl;
-    /** Shared multi-listener registry. Created bare when no `eventBus` is passed in. */
-    eventBus;
-    constructor(options) {
-        this.baseUrl = options.baseUrl;
-        this.eventBus = options.eventBus ?? new EventBus();
-        this.transport = new BrokerTransport({
-            baseUrl: options.baseUrl,
-            apiKey: options.apiKey,
-            fetch: options.fetch,
-            requestTimeoutMs: options.requestTimeoutMs,
-        });
-    }
-    addListener(event, handler) {
-        return this.eventBus.addListener(event, handler);
-    }
-    removeListener(event, handler) {
-        this.eventBus.removeListener(event, handler);
-    }
-    /**
-     * Fold `beforeAgentSpawn` patches into the input. Listeners run in
-     * registration order; each may return a {@link SpawnPatch} that is
-     * shallow-merged over the running result. Handler exceptions are caught
-     * and logged but do not abort the chain.
-     */
-    async runBeforeSpawn(ctx) {
-        let resolved = { ...ctx.input };
-        for (const handler of this.eventBus.listeners('beforeAgentSpawn')) {
-            try {
-                const patch = await handler({ ...ctx, input: resolved });
-                if (patch && typeof patch === 'object') {
-                    resolved = { ...resolved, ...patch };
-                }
-            }
-            catch (err) {
-                console.error('[agent-relay] beforeAgentSpawn listener threw:', err);
-            }
-        }
-        return resolved;
-    }
-    /**
-     * 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().`);
-        }
-        const raw = readFileSync(connPath, 'utf-8');
-        let conn;
-        try {
-            conn = JSON.parse(raw);
-        }
-        catch {
-            throw new Error(`Corrupt broker connection file (${connPath}). Remove it and start the broker again.`);
-        }
-        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.`);
-        }
-        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 new AgentRelayClient({
-            baseUrl: conn.url,
-            apiKey: conn.api_key,
-            ...(options?.eventBus ? { eventBus: options.eventBus } : {}),
-        });
-    }
-    /**
-     * 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) {
-        let binaryPath = options?.binaryPath;
-        if (!binaryPath) {
-            const resolved = getBrokerBinaryPath();
-            if (!resolved) {
-                throw new Error(formatBrokerNotFoundError());
-            }
-            binaryPath = resolved;
-        }
-        const cwd = options?.cwd ?? process.cwd();
-        const brokerName = options?.brokerName ?? (path.basename(cwd) || 'project');
-        const channels = options?.channels ?? ['general'];
-        const timeoutMs = options?.startupTimeoutMs ?? 45_000;
-        const userArgs = buildBrokerInitArgs(options?.binaryArgs);
-        const apiKey = `br_${randomBytes(16).toString('hex')}`;
-        const env = {
-            ...process.env,
-            ...options?.env,
-            AGENT_RELAY_STARTUP_DEBUG: options?.env?.AGENT_RELAY_STARTUP_DEBUG ?? process.env.AGENT_RELAY_STARTUP_DEBUG ?? '1',
-            RELAY_BROKER_API_KEY: apiKey,
-        };
-        const args = ['init', '--name', brokerName, '--channels', channels.join(','), ...userArgs];
-        const stderrLines = [];
-        const stdoutLines = [];
-        const child = spawn(binaryPath, args, {
-            cwd,
-            env,
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        if (child.stderr) {
-            const { createInterface } = await import('node:readline');
-            const rl = createInterface({ input: child.stderr });
-            rl.on('line', (line) => {
-                pushBufferedLine(stderrLines, line);
-                options?.onStderr?.(line);
-            });
-        }
-        // Parse the API URL from stdout (the broker prints it after binding)
-        const baseUrl = await waitForApiUrl(child, timeoutMs, {
-            binaryPath,
-            args,
-            cwd,
-            stdoutLines,
-            stderrLines,
-        });
-        drainBrokerStdioAfterStartup(child);
-        const client = new AgentRelayClient({
-            baseUrl,
-            apiKey,
-            requestTimeoutMs: options?.requestTimeoutMs,
-            ...(options?.eventBus ? { eventBus: options.eventBus } : {}),
-        });
-        client.child = child;
-        client.installManagedBrokerExitHandler(child, stderrLines);
-        // The broker prints "API listening on …" the moment its TCP listener is
-        // bound, but it still needs to complete a Relaycast handshake before
-        // `getSession()` will return. Two failure modes to handle:
-        //
-        //   1. Broker is alive and warming up — the startup-only API responds
-        //      503 until the handshake completes. Poll until it succeeds.
-        //   2. Broker died during the handshake (e.g. Relaycast unreachable) —
-        //      the in-flight fetch sees the socket drop as `TypeError: fetch
-        //      failed`, which is uninformative on its own.
-        //
-        // We race each `getSession()` against `brokerExited` so case (2) reports
-        // as the actual broker exit (with its stderr tail and exit code), not as
-        // a mystery network error. No backoff for the death case — we know it
-        // immediately. 503 polling stays simple at 1s intervals.
-        const brokerExited = new Promise((_, reject) => {
-            child.once('exit', (code) => {
-                reject(new Error(formatBrokerStartupError(`Broker process exited with code ${code} during initial handshake`, child, { binaryPath, args, cwd, stdoutLines, stderrLines })));
-            });
-        });
-        // Suppress unhandledRejection if the race is won by getSession before
-        // the broker exits later (e.g. on normal shutdown).
-        brokerExited.catch(() => { });
-        let session;
-        for (let attempt = 0; attempt < 10; attempt++) {
-            try {
-                session = await Promise.race([client.getSession(), brokerExited]);
-                break;
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                const is503 = message.includes('503') || message.includes('Service Unavailable');
-                if (!is503 || attempt >= 9)
-                    throw err;
-                await new Promise((resolve) => setTimeout(resolve, 1000));
-            }
-        }
-        if (!client.brokerExitInfo) {
-            client.connectEvents();
-            // Renew the owner lease so the broker doesn't auto-shutdown
-            client.leaseTimer = setInterval(() => {
-                client.renewLease().catch(() => { });
-            }, 60_000);
-        }
-        return client;
-    }
-    /** PID of the managed broker process, if spawned locally. */
-    get brokerPid() {
-        return this.child?.pid;
-    }
-    // ── Session ────────────────────────────────────────────────────────
-    async getSession() {
-        const session = await this.transport.request('/api/session');
-        this.workspaceKey = session.workspace_key;
-        return session;
-    }
-    async healthCheck() {
-        return this.transport.request('/health');
-    }
-    // ── Events ─────────────────────────────────────────────────────────
-    connectEvents(sinceSeq) {
-        this.transport.connect(sinceSeq);
-    }
-    disconnectEvents() {
-        this.transport.disconnect();
-    }
-    onEvent(listener) {
-        return this.transport.onEvent(listener);
-    }
-    /**
-     * Subscribe to managed broker child-process exit.
-     *
-     * Clients created with `new AgentRelayClient(...)` or `connect()` do not own a
-     * broker child process, so this is a no-op for them.
-     */
-    onBrokerExit(listener) {
-        if (!this.child && !this.brokerExitInfo) {
-            return () => { };
-        }
-        this.brokerExitListeners.add(listener);
-        if (this.brokerExitInfo) {
-            const info = cloneBrokerExitInfo(this.brokerExitInfo);
-            queueMicrotask(() => {
-                if (this.brokerExitListeners.has(listener)) {
-                    try {
-                        listener(info);
-                    }
-                    catch {
-                        // Listener failures should not interfere with SDK cleanup.
-                    }
-                }
-            });
-        }
-        return () => {
-            this.brokerExitListeners.delete(listener);
-        };
-    }
-    queryEvents(filter) {
-        return this.transport.queryEvents(filter);
-    }
-    getLastEvent(kind, name) {
-        return this.transport.getLastEvent(kind, name);
-    }
-    // ── Agent lifecycle ────────────────────────────────────────────────
-    async spawnPty(input) {
-        const beforeCtx = {
-            kind: 'pty',
-            input,
-            spawnerPid: process.pid,
-            spawnStartTs: new Date().toISOString(),
-            baseUrl: this.baseUrl,
-        };
-        const t0 = Date.now();
-        const resolvedInput = (await this.runBeforeSpawn(beforeCtx));
-        try {
-            const result = await this.transport.request('/api/spawn', {
-                method: 'POST',
-                body: JSON.stringify(buildSpawnPtyBody(resolvedInput)),
-            });
-            await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, result, undefined);
-            return result;
-        }
-        catch (err) {
-            await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, undefined, err);
-            throw err;
-        }
-    }
-    async spawnProvider(input) {
-        const transport = resolveSpawnTransport(input);
-        if (transport === 'headless' && !isHeadlessProvider(input.provider)) {
-            throw new Error(`provider '${input.provider}' does not support headless transport (supported: claude, opencode)`);
-        }
-        const beforeCtx = {
-            kind: 'provider',
-            input,
-            spawnerPid: process.pid,
-            spawnStartTs: new Date().toISOString(),
-            baseUrl: this.baseUrl,
-        };
-        const t0 = Date.now();
-        const resolvedInput = (await this.runBeforeSpawn(beforeCtx));
-        try {
-            const result = await this.transport.request('/api/spawn', {
-                method: 'POST',
-                body: JSON.stringify(buildSpawnProviderBody(resolvedInput, transport)),
-            });
-            await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, result, undefined);
-            return result;
-        }
-        catch (err) {
-            await this.emitAfterSpawn(beforeCtx, resolvedInput, t0, undefined, err);
-            throw err;
-        }
-    }
-    async spawnHeadless(input) {
-        return this.spawnProvider({ ...input, transport: 'headless' });
-    }
-    async spawnClaude(input) {
-        return this.spawnProvider({ ...input, provider: 'claude' });
-    }
-    async spawnOpencode(input) {
-        return this.spawnProvider({ ...input, provider: 'opencode' });
-    }
-    async release(name, reason) {
-        const beforeCtx = { name, reason, baseUrl: this.baseUrl };
-        const t0 = Date.now();
-        await this.eventBus.emit('beforeAgentRelease', beforeCtx);
-        try {
-            const result = await this.transport.request(`/api/spawned/${encodeURIComponent(name)}`, {
-                method: 'DELETE',
-                ...(reason ? { body: JSON.stringify({ reason }) } : {}),
-            });
-            const afterCtx = {
-                ...beforeCtx,
-                durationMs: Date.now() - t0,
-            };
-            await this.eventBus.emit('afterAgentRelease', afterCtx);
-            return result;
-        }
-        catch (err) {
-            const afterCtx = {
-                ...beforeCtx,
-                error: err instanceof Error ? err : new Error(String(err)),
-                durationMs: Date.now() - t0,
-            };
-            await this.eventBus.emit('afterAgentRelease', afterCtx);
-            throw err;
-        }
-    }
-    async emitAfterSpawn(beforeCtx, resolvedInput, startMs, result, error) {
-        const afterCtx = {
-            ...beforeCtx,
-            resolvedInput,
-            ...(result ? { result } : {}),
-            ...(error !== undefined ? { error: error instanceof Error ? error : new Error(String(error)) } : {}),
-            durationMs: Date.now() - startMs,
-        };
-        await this.eventBus.emit('afterAgentSpawn', afterCtx);
-    }
-    async listAgents() {
-        const result = await this.transport.request('/api/spawned');
-        return result.agents;
-    }
-    // ── PTY control ────────────────────────────────────────────────────
-    async sendInput(name, data) {
-        return this.transport.request(`/api/input/${encodeURIComponent(name)}`, {
-            method: 'POST',
-            body: JSON.stringify({ data }),
-        });
-    }
-    openInputStream(name, options) {
-        return this.transport.openInputStream(name, options);
-    }
-    async resizePty(name, rows, cols) {
-        return this.transport.request(`/api/resize/${encodeURIComponent(name)}`, {
-            method: 'POST',
-            body: JSON.stringify({ rows, cols }),
-        });
-    }
-    async getInboundDeliveryMode(name) {
-        const result = await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/delivery-mode`);
-        if (result.mode !== 'auto_inject' && result.mode !== 'manual_flush') {
-            throw new AgentRelayProtocolError({
-                code: 'invalid_response',
-                message: "inbound delivery mode response missing valid 'mode'",
-            });
-        }
-        return result.mode;
-    }
-    async setInboundDeliveryMode(name, mode) {
-        const result = await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/delivery-mode`, {
-            method: 'PUT',
-            body: JSON.stringify({ mode }),
-        });
-        if (result.mode !== 'auto_inject' && result.mode !== 'manual_flush') {
-            throw new AgentRelayProtocolError({
-                code: 'invalid_response',
-                message: "set inbound delivery mode response missing valid 'mode'",
-            });
-        }
-        return {
-            mode: result.mode,
-            flushed: typeof result.flushed === 'number' ? result.flushed : 0,
-        };
-    }
-    async getPending(name) {
-        const result = await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/pending`);
-        return Array.isArray(result.pending) ? result.pending : [];
-    }
-    async flushPending(name) {
-        const result = await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/flush`, { method: 'POST' });
-        return { flushed: typeof result.flushed === 'number' ? result.flushed : 0 };
-    }
-    async snapshot(name, format = 'plain') {
-        return this.transport.request(`/api/spawned/${encodeURIComponent(name)}/snapshot?format=${encodeURIComponent(format)}`);
-    }
-    subscribeWorkerStream(name, options = {}) {
-        this.connectEvents(options.sinceSeq);
-        return {
-            [Symbol.asyncIterator]: () => {
-                const queue = [];
-                let pending;
-                let done = false;
-                const unsubscribe = this.onEvent((event) => {
-                    if (event.kind !== 'worker_stream' ||
-                        event.name !== name ||
-                        (options.stream !== undefined && event.stream !== options.stream)) {
-                        return;
-                    }
-                    if (pending) {
-                        const { resolve } = pending;
-                        pending = undefined;
-                        resolve({ done: false, value: event.chunk });
-                        return;
-                    }
-                    queue.push(event.chunk);
-                });
-                const close = () => {
-                    done = true;
-                    unsubscribe();
-                    if (pending) {
-                        const { resolve } = pending;
-                        pending = undefined;
-                        resolve({ done: true, value: undefined });
-                    }
-                    return { done: true, value: undefined };
-                };
-                return {
-                    next() {
-                        if (queue.length > 0) {
-                            return Promise.resolve({ done: false, value: queue.shift() });
-                        }
-                        if (done) {
-                            return Promise.resolve({ done: true, value: undefined });
-                        }
-                        return new Promise((resolve, reject) => {
-                            pending = { resolve, reject };
-                        });
-                    },
-                    return() {
-                        return Promise.resolve(close());
-                    },
-                    throw(error) {
-                        done = true;
-                        unsubscribe();
-                        if (pending) {
-                            const { reject } = pending;
-                            pending = undefined;
-                            reject(error);
-                        }
-                        return Promise.reject(error);
-                    },
-                    [Symbol.asyncIterator]() {
-                        return this;
-                    },
-                };
-            },
-        };
-    }
-    // ── Messaging ──────────────────────────────────────────────────────
-    async sendMessage(input) {
-        try {
-            return await this.transport.request('/api/send', {
-                method: 'POST',
-                body: JSON.stringify({
-                    to: input.to,
-                    text: input.text,
-                    from: input.from,
-                    threadId: input.threadId,
-                    workspaceId: input.workspaceId,
-                    workspaceAlias: input.workspaceAlias,
-                    priority: input.priority,
-                    data: input.data,
-                    mode: input.mode,
-                }),
-            });
-        }
-        catch (error) {
-            if (error instanceof AgentRelayProtocolError && error.code === 'unsupported_operation') {
-                return { event_id: 'unsupported_operation', targets: [] };
-            }
-            throw error;
-        }
-    }
-    // ── 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 }),
-        });
-    }
-    // ── Channels ───────────────────────────────────────────────────────
-    async subscribeChannels(name, channels) {
-        await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/subscribe`, {
-            method: 'POST',
-            body: JSON.stringify({ channels }),
-        });
-    }
-    async unsubscribeChannels(name, channels) {
-        await this.transport.request(`/api/spawned/${encodeURIComponent(name)}/unsubscribe`, {
-            method: 'POST',
-            body: JSON.stringify({ channels }),
-        });
-    }
-    // ── Observability ──────────────────────────────────────────────────
-    async getMetrics(agent) {
-        const query = agent ? `?agent=${encodeURIComponent(agent)}` : '';
-        return this.transport.request(`/api/metrics${query}`);
-    }
-    async getStatus() {
-        return this.transport.request('/api/status');
-    }
-    async getCrashInsights() {
-        return this.transport.request('/api/crash-insights');
-    }
-    // ── Lifecycle ──────────────────────────────────────────────────────
-    async preflight(agents) {
-        return this.transport.request('/api/preflight', {
-            method: 'POST',
-            body: JSON.stringify({ agents }),
-        });
-    }
-    async renewLease() {
-        return this.transport.request('/api/session/renew', { method: 'POST' });
-    }
-    /**
-     * 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 {
-                await this.transport.request('/api/shutdown', { method: 'POST' });
-            }
-            catch {
-                // Broker may already be dead
-            }
-        }
-        this.transport.disconnect();
-        if (this.child) {
-            await waitForExit(this.child, 5000);
-            this.child = null;
-        }
-    }
-    /** 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();
-    }
-    async getConfig() {
-        return this.transport.request('/api/config');
-    }
-    notifyBrokerExit(info) {
-        if (this.brokerExitInfo)
-            return;
-        this.brokerExitInfo = cloneBrokerExitInfo(info);
-        for (const listener of this.brokerExitListeners) {
-            try {
-                listener(cloneBrokerExitInfo(info));
-            }
-            catch {
-                // Listener failures should not interfere with SDK cleanup.
-            }
-        }
-    }
-    installManagedBrokerExitHandler(child, stderrLines) {
-        const handleExit = (code, signal) => {
-            this.notifyBrokerExit({
-                code,
-                signal,
-                pid: child.pid,
-                recentStderr: [...stderrLines],
-            });
-            this.disconnectEvents();
-            if (this.leaseTimer) {
-                clearInterval(this.leaseTimer);
-                this.leaseTimer = null;
-            }
-            if (this.child === child) {
-                this.child = null;
-            }
-        };
-        if (child.exitCode !== null || child.signalCode !== null) {
-            handleExit(child.exitCode, child.signalCode);
-            return;
-        }
-        child.once('exit', handleExit);
-    }
-}
-// ── 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, debug) {
-    const { createInterface } = await import('node:readline');
-    return new Promise((resolve, reject) => {
-        if (!child.stdout) {
-            reject(new Error('Broker stdout not available'));
-            return;
-        }
-        let resolved = false;
-        const rl = createInterface({ input: child.stdout });
-        const timer = setTimeout(() => {
-            if (!resolved) {
-                resolved = true;
-                rl.close();
-                child.kill('SIGTERM');
-                reject(new Error(formatBrokerStartupError(`Broker did not report API port within ${timeoutMs}ms`, child, debug)));
-            }
-        }, timeoutMs);
-        child.on('exit', (code) => {
-            if (!resolved) {
-                resolved = true;
-                clearTimeout(timer);
-                rl.close();
-                reject(new Error(formatBrokerStartupError(`Broker process exited with code ${code} before becoming ready`, child, debug)));
-            }
-        });
-        child.on('error', (err) => {
-            if (!resolved) {
-                resolved = true;
-                clearTimeout(timer);
-                rl.close();
-                reject(new Error(formatBrokerStartupError(`Failed to start broker: ${err.message}`, child, debug)));
-            }
-        });
-        rl.on('line', (line) => {
-            if (resolved)
-                return;
-            pushBufferedLine(debug.stdoutLines, line);
-            const match = line.match(/API listening on (https?:\/\/[^\s]+)/);
-            if (match) {
-                resolved = true;
-                clearTimeout(timer);
-                rl.close();
-                resolve(match[1]);
-            }
-        });
-    });
-}
-function drainBrokerStdioAfterStartup(child) {
-    // Drain both stdout AND stderr after startup so high-volume broker
-    // diagnostics/events cannot fill either pipe and block the broker process.
-    // Stderr also has a readline consumer above for line buffering/onStderr; this
-    // raw drain is intentionally no-op and exists only to keep the stream flowing
-    // if that consumer is changed or removed later.
-    for (const stream of [child.stdout, child.stderr]) {
-        if (!stream)
-            continue;
-        stream.on('data', () => { });
-        stream.resume();
-    }
-}
-/** @internal Test-only hooks; not part of the public SDK API. */
-export const __clientTestInternals = {
-    drainBrokerStdioAfterStartup,
-};
-function pushBufferedLine(lines, line) {
-    lines.push(line);
-    if (lines.length > 40) {
-        lines.splice(0, lines.length - 40);
-    }
-}
-function cloneBrokerExitInfo(info) {
-    return {
-        ...info,
-        recentStderr: [...info.recentStderr],
-    };
-}
-function formatBrokerStartupError(message, child, debug) {
-    const details = [
-        `pid=${child.pid ?? 'unknown'}`,
-        `cwd=${debug.cwd}`,
-        `command=${formatCommand(debug.binaryPath, debug.args)}`,
-        `stdout_tail=${formatBufferedLines(debug.stdoutLines)}`,
-        `stderr_tail=${formatBufferedLines(debug.stderrLines)}`,
-    ];
-    return `${message} (${details.join('; ')})`;
-}
-function formatBufferedLines(lines) {
-    if (lines.length === 0) {
-        return '<empty>';
-    }
-    return lines
-        .slice(-8)
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .join(' | ');
-}
-function formatCommand(binaryPath, args) {
-    const render = [binaryPath, ...args].map((value) => {
-        if (/^[A-Za-z0-9_./:@=-]+$/u.test(value)) {
-            return value;
-        }
-        return JSON.stringify(value);
-    });
-    return render.join(' ');
-}
-function waitForExit(child, timeoutMs) {
-    return new Promise((resolve) => {
-        if (child.exitCode !== null) {
-            resolve();
-            return;
-        }
-        const timer = setTimeout(() => {
-            child.kill('SIGKILL');
-            resolve();
-        }, timeoutMs);
-        child.on('exit', () => {
-            clearTimeout(timer);
-            resolve();
-        });
-    });
-}
-//# sourceMappingURL=client.js.map