@agent-relay/sdk 6.3.6 → 7.0.1

package/README.md

@@ -89,6 +89,11 @@ const client = await AgentRelayClient.spawn({
   channels: ['general'],
 });
 
+const unsubscribeBrokerExit = client.onBrokerExit((info) => {
+  console.error('broker exited', info.code, info.signal, info.recentStderr);
+  unsubscribeBrokerExit();
+});
+
 // Or connect to an already-running broker (reads connection.json)
 // const client = AgentRelayClient.connect({ cwd: '/my/project' });
 

package/dist/broker-logs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Helpers for the broker's tracing log directory.
+ *
+ * The Rust broker writes its diagnostic logs to a platform-standard directory
+ * with daily rotation (see `crates/broker/src/runtime/util.rs::broker_log_dir`).
+ * This module mirrors that path so the TypeScript CLI can list, tail, prune,
+ * and clear those files without spawning the broker.
+ */
+export interface BrokerLogFile {
+    /** Absolute path to the log file. */
+    path: string;
+    /** Just the file name, e.g. `myproject.log.2026-05-21`. */
+    name: string;
+    /** Broker identifier inferred from the filename (the prefix before `.log`). */
+    brokerId: string;
+    /**
+     * The rotation date suffix in `YYYY-MM-DD` form, or `null` for the
+     * pre-rotation file laid down before `tracing-appender` rolled over.
+     */
+    date: string | null;
+    /** File size in bytes. */
+    size: number;
+    /** Last-modified time. */
+    mtime: Date;
+}
+/**
+ * Resolve the platform-standard broker log directory. Matches the Rust
+ * implementation in `runtime/util.rs::broker_log_dir`.
+ *
+ * - macOS: `~/Library/Logs/agent-relay`
+ * - Linux / other Unix: `$XDG_STATE_HOME/agent-relay/logs` (default
+ *   `~/.local/state/agent-relay/logs`)
+ * - Windows: `%LOCALAPPDATA%\agent-relay\Logs`
+ */
+export declare function getBrokerLogDir(): string;
+/** List all broker log files (current + rotated) in [`getBrokerLogDir`]. */
+export declare function listBrokerLogs(dir?: string): Promise<BrokerLogFile[]>;
+/**
+ * Read the last `lines` lines of a broker's log. Picks the most recent file
+ * matching `brokerId`. Returns `null` when no log file exists for that id.
+ */
+export declare function tailBrokerLog(brokerId: string, options?: {
+    lines?: number;
+    dir?: string;
+}): Promise<{
+    path: string;
+    content: string;
+} | null>;
+export interface PruneBrokerLogsOptions {
+    /** Override the log directory. Defaults to [`getBrokerLogDir`]. */
+    dir?: string;
+    /**
+     * Keep rotated files newer than this many days. `0` removes everything
+     * except the current (un-suffixed) file. Default: 7.
+     */
+    keepDays?: number;
+    /** When true, list candidates but don't delete. */
+    dryRun?: boolean;
+    /** Restrict to a single broker id. */
+    brokerId?: string;
+}
+export interface PruneBrokerLogsResult {
+    removed: BrokerLogFile[];
+    kept: BrokerLogFile[];
+}
+/**
+ * Delete rotated log files older than `keepDays` days. The current
+ * un-suffixed file is always kept because `tracing-appender` is writing to it.
+ */
+export declare function pruneBrokerLogs(options?: PruneBrokerLogsOptions): Promise<PruneBrokerLogsResult>;
+export interface ClearBrokerLogsOptions {
+    dir?: string;
+    /** Restrict to a single broker id. When omitted, removes all log files. */
+    brokerId?: string;
+    /** When true, list candidates but don't delete. */
+    dryRun?: boolean;
+}
+/** Delete every log file (including the current one) matching the filter. */
+export declare function clearBrokerLogs(options?: ClearBrokerLogsOptions): Promise<BrokerLogFile[]>;
+//# sourceMappingURL=broker-logs.d.ts.map

package/dist/broker-logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-logs.d.ts","sourceRoot":"","sources":["../src/broker-logs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,KAAK,EAAE,IAAI,CAAC;CACb;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAiBxC;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkC3E;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAMnD;AAED,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgC1G;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,6EAA6E;AAC7E,wBAAsB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAcpG"}

package/dist/broker-logs.js

@@ -0,0 +1,189 @@
+/**
+ * Helpers for the broker's tracing log directory.
+ *
+ * The Rust broker writes its diagnostic logs to a platform-standard directory
+ * with daily rotation (see `crates/broker/src/runtime/util.rs::broker_log_dir`).
+ * This module mirrors that path so the TypeScript CLI can list, tail, prune,
+ * and clear those files without spawning the broker.
+ */
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { readdir, stat, unlink, open } from 'node:fs/promises';
+const LOG_NAME_PATTERN = /^(?<brokerId>.+)\.log(?:\.(?<date>\d{4}-\d{2}-\d{2}))?$/;
+/**
+ * Resolve the platform-standard broker log directory. Matches the Rust
+ * implementation in `runtime/util.rs::broker_log_dir`.
+ *
+ * - macOS: `~/Library/Logs/agent-relay`
+ * - Linux / other Unix: `$XDG_STATE_HOME/agent-relay/logs` (default
+ *   `~/.local/state/agent-relay/logs`)
+ * - Windows: `%LOCALAPPDATA%\agent-relay\Logs`
+ */
+export function getBrokerLogDir() {
+    const home = homedir();
+    switch (platform()) {
+        case 'darwin':
+            return join(home, 'Library', 'Logs', 'agent-relay');
+        case 'win32': {
+            const localAppData = process.env.LOCALAPPDATA ?? join(home, 'AppData', 'Local');
+            return join(localAppData, 'agent-relay', 'Logs');
+        }
+        default: {
+            const stateHome = process.env.XDG_STATE_HOME && process.env.XDG_STATE_HOME.length > 0
+                ? process.env.XDG_STATE_HOME
+                : join(home, '.local', 'state');
+            return join(stateHome, 'agent-relay', 'logs');
+        }
+    }
+}
+/** List all broker log files (current + rotated) in [`getBrokerLogDir`]. */
+export async function listBrokerLogs(dir) {
+    const logDir = dir ?? getBrokerLogDir();
+    let entries;
+    try {
+        entries = await readdir(logDir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const files = [];
+    for (const name of entries) {
+        const match = LOG_NAME_PATTERN.exec(name);
+        if (!match || !match.groups)
+            continue;
+        const fullPath = join(logDir, name);
+        let info;
+        try {
+            info = await stat(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (!info.isFile())
+            continue;
+        files.push({
+            path: fullPath,
+            name,
+            brokerId: match.groups.brokerId,
+            date: match.groups.date ?? null,
+            size: info.size,
+            mtime: info.mtime,
+        });
+    }
+    files.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+    return files;
+}
+/**
+ * Read the last `lines` lines of a broker's log. Picks the most recent file
+ * matching `brokerId`. Returns `null` when no log file exists for that id.
+ */
+export async function tailBrokerLog(brokerId, options = {}) {
+    const lines = options.lines ?? 200;
+    const files = (await listBrokerLogs(options.dir)).filter((f) => f.brokerId === brokerId);
+    if (files.length === 0)
+        return null;
+    const target = files[0]; // newest first
+    return { path: target.path, content: await tailFile(target.path, lines) };
+}
+/**
+ * Delete rotated log files older than `keepDays` days. The current
+ * un-suffixed file is always kept because `tracing-appender` is writing to it.
+ */
+export async function pruneBrokerLogs(options = {}) {
+    const keepDays = options.keepDays ?? 7;
+    const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
+    const files = await listBrokerLogs(options.dir);
+    const removed = [];
+    const kept = [];
+    for (const file of files) {
+        if (options.brokerId && file.brokerId !== options.brokerId) {
+            kept.push(file);
+            continue;
+        }
+        // Never delete the current (un-suffixed) file — it's being written to.
+        if (file.date === null) {
+            kept.push(file);
+            continue;
+        }
+        if (file.mtime.getTime() >= cutoff) {
+            kept.push(file);
+            continue;
+        }
+        if (!options.dryRun) {
+            try {
+                await unlink(file.path);
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT')
+                    throw err;
+            }
+        }
+        removed.push(file);
+    }
+    return { removed, kept };
+}
+/** Delete every log file (including the current one) matching the filter. */
+export async function clearBrokerLogs(options = {}) {
+    const files = await listBrokerLogs(options.dir);
+    const target = options.brokerId ? files.filter((f) => f.brokerId === options.brokerId) : files;
+    if (options.dryRun)
+        return target;
+    for (const file of target) {
+        try {
+            await unlink(file.path);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    return target;
+}
+async function tailFile(filePath, lines) {
+    const CHUNK = 8192;
+    let fh;
+    try {
+        fh = await open(filePath, 'r');
+        const { size } = await fh.stat();
+        if (size === 0)
+            return '';
+        if (size <= CHUNK) {
+            const buf = Buffer.alloc(size);
+            await fh.read(buf, 0, size, 0);
+            return tailLines(buf.toString('utf-8'), lines);
+        }
+        const chunks = [];
+        let position = size;
+        let newlines = 0;
+        while (position > 0 && newlines <= lines) {
+            const readSize = Math.min(CHUNK, position);
+            position -= readSize;
+            const buf = Buffer.alloc(readSize);
+            await fh.read(buf, 0, readSize, position);
+            chunks.unshift(buf);
+            newlines += countNewlines(buf);
+        }
+        const combined = Buffer.concat(chunks).toString('utf-8');
+        return tailLines(combined, lines);
+    }
+    finally {
+        if (fh)
+            await fh.close();
+    }
+}
+function tailLines(text, count) {
+    const split = text.split('\n');
+    if (split.length > 0 && split[split.length - 1] === '')
+        split.pop();
+    return split.slice(-count).join('\n');
+}
+function countNewlines(buf) {
+    let n = 0;
+    for (const byte of buf)
+        if (byte === 0x0a)
+            n++;
+    return n;
+}
+//# sourceMappingURL=broker-logs.js.map

package/dist/broker-logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-logs.js","sourceRoot":"","sources":["../src/broker-logs.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -14,7 +14,7 @@ import { type PtyInputStream, type PtyInputStreamOptions } from './transport.js'
 import type { AgentRuntime, BrokerEvent, BrokerStats, BrokerStatus, CrashInsightsResponse, PendingRelayMessage, PtySnapshot, InboundDeliveryMode, SnapshotFormat } from './protocol.js';
 import type { SpawnHeadlessInput, SpawnPtyInput, SpawnProviderInput, SendMessageInput, ListAgent } from './types.js';
 import { EventBus } from './event-bus.js';
-import type { AgentRelayEvents } from './lifecycle-hooks.js';
+import type { AgentRelayEvents, BeforeAgentSpawnHandler } from './lifecycle-hooks.js';
 export interface AgentRelayClientOptions {
     baseUrl: string;
     apiKey?: string;
@@ -31,6 +31,16 @@ export interface AgentRelayClientOptions {
      */
     eventBus?: EventBus<AgentRelayEvents>;
 }
+export interface BrokerExitInfo {
+    /** Exit code, or null when the process was killed by signal. */
+    code: number | null;
+    /** Terminating signal, or null when the process exited normally. */
+    signal: NodeJS.Signals | null;
+    /** PID of the managed broker process that exited. */
+    pid: number | undefined;
+    /** Recent stderr lines captured from the managed broker process. */
+    recentStderr: string[];
+}
 export interface AgentRelayBrokerInitArgs {
     /** Optional HTTP API port for dashboard proxy (0 = disabled). */
     apiPort?: number;
@@ -81,12 +91,15 @@ export interface WorkerStreamSubscriptionOptions {
     /** Sequence offset to pass to the broker event stream when connecting. */
     sinceSeq?: number;
 }
+type BrokerExitListener = (info: BrokerExitInfo) => void;
 export declare class AgentRelayClient {
     private readonly transport;
     /** Set after spawn() — the managed child process. */
     private child;
     /** Lease renewal timer (only for spawned brokers). */
     private leaseTimer;
+    private brokerExitInfo;
+    private brokerExitListeners;
     workspaceKey?: string;
     /** Resolved broker URL — captured so call-site lifecycle contexts can surface it. */
     readonly baseUrl: string;
@@ -98,9 +111,16 @@ export declare class AgentRelayClient {
      * function. Equivalent to `client.eventBus.addListener(...)` but mirrors
      * the `AgentRelay` facade API so direct-client callers don't need to
      * reach through `.eventBus`.
+     *
+     * `beforeAgentSpawn` is the one event whose handler may return a
+     * `SpawnPatch` to mutate the spawn input — the dedicated overload
+     * keeps that contract type-safe without forcing other events to accept
+     * non-void returns.
      */
+    addListener(event: 'beforeAgentSpawn', handler: BeforeAgentSpawnHandler): () => void;
     addListener<K extends keyof AgentRelayEvents>(event: K, handler: (...args: AgentRelayEvents[K]) => void | Promise<void>): () => void;
     /** Remove a previously-registered listener. */
+    removeListener(event: 'beforeAgentSpawn', handler: BeforeAgentSpawnHandler): void;
     removeListener<K extends keyof AgentRelayEvents>(event: K, handler: (...args: AgentRelayEvents[K]) => void | Promise<void>): void;
     /**
      * Fold `beforeAgentSpawn` patches into the input. Listeners run in
@@ -143,6 +163,13 @@ export declare class AgentRelayClient {
     connectEvents(sinceSeq?: number): void;
     disconnectEvents(): void;
     onEvent(listener: (event: BrokerEvent) => void): () => void;
+    /**
+     * 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: BrokerExitListener): () => void;
     queryEvents(filter?: {
         kind?: string;
         name?: string;
@@ -239,6 +266,8 @@ export declare class AgentRelayClient {
     getConfig(): Promise<{
         workspaceKey?: string;
     }>;
+    private notifyBrokerExit;
+    private installManagedBrokerExitHandler;
 }
 declare function drainBrokerStdioAfterStartup(child: ChildProcess): void;
 /** @internal Test-only hooks; not part of the public SDK API. */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9D,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,qBAAqB,EAErB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,cAAc,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAEV,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAGV,gBAAgB,EAGhB,uBAAuB,EAExB,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,qDAAqD;IACrD,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,oEAAoE;IACpE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,+BAA+B;IAC9C,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAUD,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;AAiGzD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAE5C,qDAAqD;IACrD,OAAO,CAAC,KAAK,CAA6B;IAC1C,sDAAsD;IACtD,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,mBAAmB,CAAiC;IAE5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;gBAElC,OAAO,EAAE,uBAAuB;IAW5C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IACpF,WAAW,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAC1C,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9D,MAAM,IAAI;IAWb,+CAA+C;IAC/C,cAAc,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,uBAAuB,GAAG,IAAI;IACjF,cAAc,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAC7C,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC9D,IAAI;IAQP;;;;;OAKG;YACW,cAAc;IAe5B;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;KACvC,GAAG,gBAAgB;IAuCpB;;;;;;;;;OASG;WACU,KAAK,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuH/E,6DAA6D;IAC7D,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAIK,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAMlC,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAMjD,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAItC,gBAAgB,IAAI,IAAI;IAIxB,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3D;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAyBtD,WAAW,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,EAAE;IAIrG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAM5D,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IAuBhF,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IA8B1F,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IAI1F,WAAW,CACf,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GAC1C,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IAI7C,aAAa,CACjB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,GAC1C,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IAI7C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;YA6BzD,cAAc;IAiBtB,UAAU,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAOlC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAO7F,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc;IAIxE,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlD,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAalE,sBAAsB,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,4BAA4B,CAAC;IAoBlC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAOxD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAQxD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,cAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAMpF,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,+BAAoC,GAAG,aAAa,CAAC,MAAM,CAAC;IA6EnG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA0BtF,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IASvD,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlE,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpE,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACxC,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACxF,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;IAKI,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;IAIlC,gBAAgB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAMlD,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAOpF,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAI1E;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB/B,8FAA8F;IAC9F,UAAU,IAAI,IAAI;IAQZ,SAAS,IAAI,OAAO,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrD,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,+BAA+B;CAyBxC;AA+ED,iBAAS,4BAA4B,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAW/D;AAED,iEAAiE;AACjE,eAAO,MAAM,qBAAqB;;CAEjC,CAAC"}

package/dist/client.js

@@ -104,6 +104,8 @@ export class AgentRelayClient {
     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;
@@ -119,16 +121,9 @@ export class AgentRelayClient {
             requestTimeoutMs: options.requestTimeoutMs,
         });
     }
-    /**
-     * Register a listener on the client's event bus. Returns an unsubscribe
-     * function. Equivalent to `client.eventBus.addListener(...)` but mirrors
-     * the `AgentRelay` facade API so direct-client callers don't need to
-     * reach through `.eventBus`.
-     */
     addListener(event, handler) {
         return this.eventBus.addListener(event, handler);
     }
-    /** Remove a previously-registered listener. */
     removeListener(event, handler) {
         this.eventBus.removeListener(event, handler);
     }
@@ -252,6 +247,7 @@ export class AgentRelayClient {
             ...(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:
@@ -288,18 +284,13 @@ export class AgentRelayClient {
                 await new Promise((resolve) => setTimeout(resolve, 1000));
             }
         }
-        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;
-            }
-        });
+        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. */
@@ -325,6 +316,34 @@ export class AgentRelayClient {
     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);
     }
@@ -650,6 +669,42 @@ export class AgentRelayClient {
     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 ──────────────────────────────────────────────────────────────
 /**
@@ -727,6 +782,12 @@ function pushBufferedLine(lines, line) {
         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'}`,