@north-light/api 0.3.580 → 0.3.588

package/dist/core/blobs/fault.js

@@ -0,0 +1,6 @@
+/** Fault switch for the blob store (design-fleet, faulting-store seam): `CRTR_FAULT_BLOB=put_fail` makes every `put`
+ *  throw. Read on each call so a seam test can flip it in the serving process's environment. */
+export function blobFault(op) {
+    if (op === 'put' && process.env['CRTR_FAULT_BLOB'] === 'put_fail')
+        throw new Error('blob put refused (CRTR_FAULT_BLOB=put_fail)');
+}

package/dist/core/blobs/index.d.ts

@@ -0,0 +1,21 @@
+/** The one blob-store interface: conversation objects, run-event chunks, job output, attachments and releases are
+ *  objects under slash-separated keys (`conversations/<node>/<session>/<seq>.jsonl`). Implementations: a directory
+ *  (a Mac, `~/.crouter/runtime/blobs/`) and R2 (the cloud). A key never starts with `/` and has no `.` or `..` segment. */
+export interface BlobStore {
+    /** Write `data` at `key`, replacing any object there. Resolves once the object is durable. */
+    put(key: string, data: Buffer | Uint8Array | string): Promise<void>;
+    /** The object's bytes (just `length` bytes from `start` when a range is given; fewer at the end), or `null` when no object has this key. */
+    get(key: string, range?: {
+        start: number;
+        length: number;
+    }): Promise<Buffer | null>;
+    /** Every key beginning with `prefix`, in ascending byte order. */
+    list(prefix: string): Promise<string[]>;
+    /** Remove the object at `key`; removing an absent key is not an error. */
+    delete(key: string): Promise<void>;
+}
+/** A key is safe when it is a relative path of plain segments. Throws on anything else. */
+export declare function assertBlobKey(key: string): void;
+export declare function blobStore(): Promise<BlobStore>;
+/** Drop the selected store (tests that change the environment). */
+export declare function resetBlobStore(): void;

package/dist/core/blobs/index.js

@@ -0,0 +1,30 @@
+/** A key is safe when it is a relative path of plain segments. Throws on anything else. */
+export function assertBlobKey(key) {
+    if (key === '' || key.startsWith('/') || key.endsWith('/') || key.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new Error(`invalid blob key: ${JSON.stringify(key)}`);
+    }
+}
+/** The blob store this process uses: R2 when `CRTR_R2_BUCKET` is set (all four `CRTR_R2_*` variables are then required),
+ *  else the directory `<runtime root>/blobs` — the one crtrd-writable, volume-backed directory on every host (`/runtime` in a container),
+ *  which also adopts the older `<layout root>/blobs` once. Built per process on first use. */
+let selected;
+export async function blobStore() {
+    if (selected)
+        return selected;
+    const bucket = process.env['CRTR_R2_BUCKET'];
+    if (bucket) {
+        const need = (name) => { const v = process.env[name]; if (!v)
+            throw new Error(`${name} is required when CRTR_R2_BUCKET is set`); return v; };
+        const { createR2BlobStore } = await import('./r2.js');
+        selected = createR2BlobStore({ bucket, endpoint: need('CRTR_R2_ENDPOINT'), accessKeyId: need('CRTR_R2_ACCESS_KEY_ID'), secretAccessKey: need('CRTR_R2_SECRET_ACCESS_KEY') });
+    }
+    else {
+        const [{ join }, { layoutRoot, runtimeRoot }, { adoptBlobDirectory, createDirectoryBlobStore }] = await Promise.all([import('node:path'), import('../layout.js'), import('./directory.js')]);
+        const root = join(runtimeRoot(), 'blobs');
+        adoptBlobDirectory(join(layoutRoot(), 'blobs'), root);
+        selected = createDirectoryBlobStore(root);
+    }
+    return selected;
+}
+/** Drop the selected store (tests that change the environment). */
+export function resetBlobStore() { selected = undefined; }

package/dist/core/blobs/r2.d.ts

@@ -0,0 +1,13 @@
+import { type BlobStore } from './index.js';
+export interface R2Config {
+    bucket: string;
+    endpoint: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+/** S3-compatible object store (R2) over `fetch`: path-style requests signed with SigV4, region `auto`. */
+export declare function createR2BlobStore(config: R2Config): BlobStore;
+/** The R2 settings of this process, or `null` when it uses the directory store. Same variables as `blobStore()`. */
+export declare function r2ConfigFromEnv(): R2Config | null;
+/** A SigV4 query-signed URL that lets its holder PUT one object at `key` until `expiresSeconds` pass. */
+export declare function presignPutUrl(config: R2Config, key: string, expiresSeconds: number, now?: Date): string;

package/dist/core/blobs/r2.js

@@ -0,0 +1,104 @@
+import { createHash, createHmac } from 'node:crypto';
+import { assertBlobKey } from './index.js';
+import { blobFault } from './fault.js';
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const hmac = (key, data) => createHmac('sha256', key).update(data).digest();
+const encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+/** S3-compatible object store (R2) over `fetch`: path-style requests signed with SigV4, region `auto`. */
+export function createR2BlobStore(config) {
+    const base = new URL(config.endpoint);
+    async function send(method, key, query, body, range) {
+        const path = `/${encode(config.bucket)}${key === '' ? '' : `/${key.split('/').map(encode).join('/')}`}`;
+        const canonicalQuery = [...query].sort(([a], [b]) => a < b ? -1 : 1).map(([k, v]) => `${encode(k)}=${encode(v)}`).join('&');
+        const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+        const date = amzDate.slice(0, 8);
+        const payloadHash = sha256(body ?? '');
+        const headers = { host: base.host, 'x-amz-content-sha256': payloadHash, 'x-amz-date': amzDate };
+        const names = Object.keys(headers).sort();
+        const canonicalHeaders = names.map((name) => `${name}:${headers[name]}\n`).join('');
+        const signed = names.join(';');
+        const scope = `${date}/auto/s3/aws4_request`;
+        const request = [method, path, canonicalQuery, canonicalHeaders, signed, payloadHash].join('\n');
+        const toSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256(request)].join('\n');
+        const signingKey = hmac(hmac(hmac(hmac(`AWS4${config.secretAccessKey}`, date), 'auto'), 's3'), 'aws4_request');
+        const signature = createHmac('sha256', signingKey).update(toSign).digest('hex');
+        headers['authorization'] = `AWS4-HMAC-SHA256 Credential=${config.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`;
+        const { host: _host, ...sent } = headers;
+        if (range)
+            sent['range'] = `bytes=${range.start}-${range.start + range.length - 1}`;
+        return await fetch(`${base.origin}${path}${canonicalQuery ? `?${canonicalQuery}` : ''}`, { method, headers: sent, ...(body ? { body: new Uint8Array(body) } : {}) });
+    }
+    async function ok(response, what) {
+        if (!response.ok)
+            throw new Error(`R2 ${what} failed (${response.status}): ${(await response.text()).slice(0, 300)}`);
+        return response;
+    }
+    return {
+        async put(key, data) {
+            blobFault('put');
+            assertBlobKey(key);
+            await ok(await send('PUT', key, [], typeof data === 'string' ? Buffer.from(data, 'utf8') : Buffer.from(data)), `put ${key}`);
+        },
+        async get(key, range) {
+            assertBlobKey(key);
+            const response = await send('GET', key, [], undefined, range);
+            if (response.status === 416) {
+                await response.arrayBuffer();
+                return Buffer.alloc(0);
+            }
+            if (response.status === 404) {
+                await response.arrayBuffer();
+                return null;
+            }
+            return Buffer.from(await (await ok(response, `get ${key}`)).arrayBuffer());
+        },
+        async list(prefix) {
+            const keys = [];
+            let token;
+            do {
+                const query = [['list-type', '2'], ['prefix', prefix], ...(token ? [['continuation-token', token]] : [])];
+                const xml = await (await ok(await send('GET', '', query), `list ${prefix}`)).text();
+                for (const match of xml.matchAll(/<Key>([^<]*)<\/Key>/g))
+                    keys.push(match[1].replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'"));
+                token = /<IsTruncated>true<\/IsTruncated>/.test(xml) ? /<NextContinuationToken>([^<]*)<\/NextContinuationToken>/.exec(xml)?.[1] : undefined;
+            } while (token);
+            return keys.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+        },
+        async delete(key) {
+            assertBlobKey(key);
+            const response = await send('DELETE', key, []);
+            if (response.status !== 404)
+                await ok(response, `delete ${key}`);
+            else
+                await response.arrayBuffer();
+        },
+    };
+}
+/** The R2 settings of this process, or `null` when it uses the directory store. Same variables as `blobStore()`. */
+export function r2ConfigFromEnv() {
+    const bucket = process.env['CRTR_R2_BUCKET'];
+    if (!bucket)
+        return null;
+    const need = (name) => { const v = process.env[name]; if (!v)
+        throw new Error(`${name} is required when CRTR_R2_BUCKET is set`); return v; };
+    return { bucket, endpoint: need('CRTR_R2_ENDPOINT'), accessKeyId: need('CRTR_R2_ACCESS_KEY_ID'), secretAccessKey: need('CRTR_R2_SECRET_ACCESS_KEY') };
+}
+/** A SigV4 query-signed URL that lets its holder PUT one object at `key` until `expiresSeconds` pass. */
+export function presignPutUrl(config, key, expiresSeconds, now = new Date()) {
+    assertBlobKey(key);
+    const base = new URL(config.endpoint);
+    const path = `/${encode(config.bucket)}/${key.split('/').map(encode).join('/')}`;
+    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+    const date = amzDate.slice(0, 8);
+    const scope = `${date}/auto/s3/aws4_request`;
+    const query = [
+        ['X-Amz-Algorithm', 'AWS4-HMAC-SHA256'], ['X-Amz-Credential', `${config.accessKeyId}/${scope}`], ['X-Amz-Date', amzDate],
+        ['X-Amz-Expires', String(expiresSeconds)], ['X-Amz-SignedHeaders', 'host'],
+    ];
+    const canonicalQuery = query.sort(([a], [b]) => a < b ? -1 : 1).map(([k, v]) => `${encode(k)}=${encode(v)}`).join('&');
+    const request = ['PUT', path, canonicalQuery, `host:${base.host}\n`, 'host', 'UNSIGNED-PAYLOAD'].join('\n');
+    const toSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256(request)].join('\n');
+    const signingKey = hmac(hmac(hmac(hmac(`AWS4${config.secretAccessKey}`, date), 'auto'), 's3'), 'aws4_request');
+    const signature = createHmac('sha256', signingKey).update(toSign).digest('hex');
+    return `${base.origin}${path}?${canonicalQuery}&X-Amz-Signature=${signature}`;
+}

package/dist/core/broker-client/client.d.ts

@@ -0,0 +1,89 @@
+import { EventEmitter } from 'node:events';
+import type { NodeRow } from '../canvas/types.js';
+import type { BrokerDataFrame, BrokerToClient, ClientToBroker, DequeueFrame, GetHumanForkCoordinatesFrame, GetSettingsFrame, GetTreeFrame, ListMemoryRefsFrame, ListModelsFrame, ListScopedModelsFrame, ListSessionsFrame } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+export { BrokerUnavailableError, type Transport } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport, type RelayTarget } from './transport-relay.js';
+/** A correlated read-op (or `dequeue`) request MINUS the client-chosen `id` —
+ *  {@link BrokerClient.request} mints the `id`, sends the frame, and resolves
+ *  with the matching `data` reply. The picker/operator code builds these; the
+ *  client owns the correlation token so callers never hand-roll one. */
+export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame, 'id'> | Omit<GetTreeFrame, 'id'> | Omit<GetSettingsFrame, 'id'> | Omit<ListScopedModelsFrame, 'id'> | Omit<DequeueFrame, 'id'> | Omit<GetHumanForkCoordinatesFrame, 'id'> | Omit<ListMemoryRefsFrame, 'id'>;
+export interface BrokerClientOptions {
+    /** Where the frames go. Defaults to a {@link SocketTransport} against this
+     *  node's local `view.sock` — the common case. Pass a {@link RelayTransport}
+     *  to attach a remote node instead; every method behaves identically either
+     *  way. */
+    transport?: Transport;
+}
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same target while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` and an
+ *  exact unfinalized parked resident are NOT terminal — either can wake while
+ *  the viewer remains seated. Local canvas rows only — a remote target has no
+ *  local row, so callers driving a remote attach must not consult this. */
+export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
+/** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
+ *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */
+export interface BrokerClient {
+    on(event: 'connect', listener: () => void): this;
+    on(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    on(event: 'close', listener: () => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    once(event: 'connect', listener: () => void): this;
+    once(event: 'frame', listener: (frame: BrokerToClient) => void): this;
+    once(event: 'close', listener: () => void): this;
+    once(event: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+export declare class BrokerClient extends EventEmitter {
+    private readonly nodeId;
+    private readonly transport;
+    private closeEmitted;
+    /** Tracks live connect↔close state so {@link request} can fail fast on a
+     *  dead/absent connection rather than parking a promise the reply will
+     *  never reach (transport-agnostic mirror of the old socket.destroyed
+     *  check). A post-close request lands here too — {@link rejectAllPending}
+     *  already ran by the time this flips false. */
+    private connected;
+    /** The last transport-level error message, so a close can reject any
+     *  in-flight requests with the precise reason (e.g. an oversized-frame
+     *  overflow) instead of a generic one. Cleared on every fresh connect. */
+    private lastTransportError;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
+    private pending;
+    constructor(nodeId: string, options?: BrokerClientOptions);
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or transport teardown). Mints
+     *  the `id`, sends `{...frame, id}`, and parks a resolver consumed by
+     *  {@link onFrame}. The reply is narrowed by the caller on its `kind`. */
+    request(frame: ReadOpRequest): Promise<BrokerDataFrame>;
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
+    private rejectAllPending;
+    /** Open the connection. Emits `connect` on success or `error` (a
+     *  {@link BrokerUnavailableError} when the target has no reachable broker)
+     *  on failure. Idempotent guard is the caller's job — call once. */
+    connect(): void;
+    /** Re-establish the connection after a broker exit (a yield→revive cycle),
+     *  to the SAME target. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on a retryable dial failure. */
+    redial(options?: RedialOptions): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
+    send(frame: ClientToBroker): void;
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
+    close(): void;
+    private onFrame;
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    private emitError;
+}

package/dist/core/broker-client/client.js

@@ -0,0 +1,184 @@
+// client.ts — THE broker protocol client. Every Node process that talks to a
+// node's broker over `view.sock` uses this one class: the `crtr surface attach`
+// viewer, `auth-reload`, `model-swap`, and the human-prompt dequeue path.
+//
+// The §0 ONE-WRITER INVARIANT lives here: a client has ONLY a Transport
+// (`transport.ts`) to an ALREADY-running headless broker — locally over its
+// unix socket (`SocketTransport`, `nodeDir(id)/view.sock`), or remotely over a
+// bearer-authenticated WebSocket to crtrd's preview-served attach endpoint
+// (`RelayTransport`, `transport-relay.ts`). BrokerClient NEVER spawns pi, NEVER opens the session
+// `.jsonl`, NEVER constructs an engine — if the broker is not running, connect
+// fails and the caller exits (focus/revive is what keeps a broker alive, not
+// attach). It also never uses pi's `RpcClient` (which would spawn its own
+// engine).
+//
+// Everything in this file is transport-agnostic: request correlation (the
+// pending map), the reconnect give-up predicate, and close handling are the
+// SAME regardless of which Transport is plugged in at construction — only the
+// wire differs. See `transport.ts` for the seam contract. Fault recording
+// (`viewer↔broker` canvas fault rows) belongs to the transport that can
+// produce a dial error, and lives in `SocketTransport`.
+//
+// Reconnect: a dropped broker emits `close`; the caller's reconnect supervisor
+// decides whether to re-dial (a yield/revive keeps the SAME target — a local
+// `view.sock` path, or a remote preview endpoint — `redial()` re-establishes
+// the connection to it) or give up ("broker gone"). A connect-time
+// unavailable-broker signal surfaces as `BrokerUnavailableError` so the FIRST
+// connect exits non-zero with a clear message; the same signal during a
+// redial rejects the redial promise as retryable.
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { SocketTransport } from './transport-socket.js';
+export { BrokerUnavailableError } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport } from './transport-relay.js';
+/** How long {@link BrokerClient.request} waits for the correlated reply before
+ *  rejecting — bounds a pending picker fetch if the broker drops the request
+ *  (it should always reply with `data` or a correlated `error`). */
+const REQUEST_TIMEOUT_MS = 10_000;
+/** The reconnect supervisor's give-up predicate (extracted pure so it is
+ *  testable without a socket or TUI). After a broker close the viewer KEEPS
+ *  re-dialing the same target while the node is still alive — a yield
+ *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
+ *  broker on the same path. It gives up only when the node is genuinely gone:
+ *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` and an
+ *  exact unfinalized parked resident are NOT terminal — either can wake while
+ *  the viewer remains seated. Local canvas rows only — a remote target has no
+ *  local row, so callers driving a remote attach must not consult this. */
+export function reconnectShouldGiveUp(row) {
+    if (row === null)
+        return true;
+    if (row.lifecycle === 'resident'
+        && row.status === 'done'
+        && row.intent === 'parked'
+        && row.final_report == null)
+        return false;
+    return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
+}
+export class BrokerClient extends EventEmitter {
+    nodeId;
+    transport;
+    closeEmitted = false;
+    /** Tracks live connect↔close state so {@link request} can fail fast on a
+     *  dead/absent connection rather than parking a promise the reply will
+     *  never reach (transport-agnostic mirror of the old socket.destroyed
+     *  check). A post-close request lands here too — {@link rejectAllPending}
+     *  already ran by the time this flips false. */
+    connected = false;
+    /** The last transport-level error message, so a close can reject any
+     *  in-flight requests with the precise reason (e.g. an oversized-frame
+     *  overflow) instead of a generic one. Cleared on every fresh connect. */
+    lastTransportError;
+    /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
+     *  Resolved by the matching `data` frame / rejected by the matching `error`
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
+    pending = new Map();
+    constructor(nodeId, options = {}) {
+        super();
+        this.nodeId = nodeId;
+        this.transport = options.transport ?? new SocketTransport(nodeId);
+        this.transport.on('connect', () => {
+            this.closeEmitted = false;
+            this.connected = true;
+            this.lastTransportError = undefined;
+            this.emit('connect');
+        });
+        this.transport.on('frame', (frame) => this.onFrame(frame));
+        this.transport.on('error', (err) => {
+            this.lastTransportError = err.message;
+            this.emitError(err);
+        });
+        this.transport.on('close', () => this.onClose());
+    }
+    /** Issue a correlated read-op and resolve with the broker's `data` reply (or
+     *  reject on the correlated `error`, a timeout, or transport teardown). Mints
+     *  the `id`, sends `{...frame, id}`, and parks a resolver consumed by
+     *  {@link onFrame}. The reply is narrowed by the caller on its `kind`. */
+    request(frame) {
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            if (!this.connected) {
+                reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
+                return;
+            }
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request '${frame.type}' timed out after ${REQUEST_TIMEOUT_MS}ms`));
+            }, REQUEST_TIMEOUT_MS);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ ...frame, id });
+        });
+    }
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
+    rejectAllPending(reason) {
+        for (const { reject, timer } of this.pending.values()) {
+            clearTimeout(timer);
+            reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+    /** Open the connection. Emits `connect` on success or `error` (a
+     *  {@link BrokerUnavailableError} when the target has no reachable broker)
+     *  on failure. Idempotent guard is the caller's job — call once. */
+    connect() {
+        this.transport.connect();
+    }
+    /** Re-establish the connection after a broker exit (a yield→revive cycle),
+     *  to the SAME target. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on a retryable dial failure. */
+    redial(options) {
+        return this.transport.redial(options);
+    }
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
+    send(frame) {
+        this.transport.send(frame);
+    }
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
+    close() {
+        this.transport.destroy();
+    }
+    onFrame(frame) {
+        // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
+        // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
+        // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
+        // frame is ALWAYS a reply, so by default it is swallowed unconditionally —
+        // even a late post-timeout one (no pending entry) is dropped, never leaked
+        // to the router. An `error` is correlated only when its `id` matches an
+        // in-flight request; an uncorrelated error still flows through.
+        if (frame.type === 'data') {
+            const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+            if (entry) {
+                this.pending.delete(frame.id);
+                clearTimeout(entry.timer);
+                entry.resolve(frame);
+            }
+            return;
+        }
+        if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+            const entry = this.pending.get(frame.id);
+            this.pending.delete(frame.id);
+            clearTimeout(entry.timer);
+            entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+            return;
+        }
+        this.emit('frame', frame);
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        this.connected = false;
+        this.rejectAllPending(this.lastTransportError ?? 'broker connection closed');
+        this.emit('close');
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this client must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

package/dist/core/broker-client/index.d.ts

@@ -0,0 +1,2 @@
+export { AttachRefusedError } from './transport.js';
+export { BrokerClient, BrokerUnavailableError, reconnectShouldGiveUp, RelayTransport, SocketTransport, type BrokerClientOptions, type ReadOpRequest, type RelayTarget, type Transport, } from './client.js';

package/dist/core/broker-client/index.js

@@ -0,0 +1,14 @@
+// core/broker-client — the ONE `view.sock` protocol client for Node processes.
+//
+// `client.ts` owns the protocol (request correlation, the pending map, close
+// handling, the reconnect give-up predicate); `transport.ts` is the seam, with
+// two implementations — `transport-socket.ts` (local unix socket) and
+// `transport-relay.ts` (remote wss via the preview endpoint). The wire format
+// itself stays in `core/runtime/broker-protocol.ts`, which both the broker and
+// every client share.
+//
+// Nothing here reads or writes canvas state: a caller that needs the graph goes
+// to crtrd `/v1`, and a caller that needs a surface goes to tmux placement. That
+// is what keeps this module importable from a CLI leaf (V-1).
+export { AttachRefusedError } from './transport.js';
+export { BrokerClient, BrokerUnavailableError, reconnectShouldGiveUp, RelayTransport, SocketTransport, } from './client.js';

package/dist/core/broker-client/transport-relay.d.ts

@@ -0,0 +1,47 @@
+import { EventEmitter } from 'node:events';
+import type { ClientToBroker } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+/** A resolved remote canvas target — see `core/remote-canvas-target.ts` for how
+ *  this is assembled from config (`relayTokenRef`) plus the 0600 secrets store
+ *  via `resolveRemoteCanvasTarget`. This transport itself never takes the
+ *  token from argv — `canvas config add --relay-token -` is the only accepted
+ *  form for writing a token to the store — stdin-only, never argv; that is a
+ *  one-time config-write path, not this call. */
+export interface RelayTarget {
+    /** The preview endpoint origin, e.g. `https://<hash>.preview.bl.run`. */
+    previewEndpoint: string;
+    /** The raw bearer token. NEVER logged, NEVER echoed. */
+    relayToken: string;
+}
+export interface LocalRelayTarget {
+    /** The owner's daemon API socket. The viewer has already called ensureAttach. */
+    socketPath: string;
+}
+export declare class RelayTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly target;
+    private ws;
+    private closeEmitted;
+    constructor(nodeId: string, target: RelayTarget | LocalRelayTarget);
+    private get url();
+    private dial;
+    connect(): void;
+    /** Re-dial the same daemon attach endpoint after a broker replacement. */
+    redial(_options?: RedialOptions): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private onMessage;
+    private onError;
+    /** A 1008 invalid-id close or a 1011 whose reason starts with "no running
+     *  broker" or "no node " is a terminal unavailable-broker signal from the
+     *  crtrd attach bridge. Surface it as BrokerUnavailableError so the reconnect
+     *  supervisor applies its normal give-up path across transports. `classify`
+     *  only handles the 1008/protocol case: its 1011 classification answers
+     *  whether a close is connection-shaped, not whether the broker is gone.
+     *  Everything else (1006 abnormal, 1000 normal, or an unrecognized 1011
+     *  reason) is a transient or expected drop that the caller may redial. */
+    private onClose;
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    private emitError;
+}