@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,165 @@
+// transport-relay.ts — the daemon WebSocket transport: local viewers use the
+// Unix API socket; remote viewers use a bearer-authenticated preview endpoint.
+// One JSON frame per WS message in both directions; no FrameDecoder is needed because
+// WebSocket preserves message boundaries.
+//
+// Callers keep the bearer token off argv and shell history (see
+// `core/remote-canvas-target.ts`). This transport sends it only as a request
+// header and never logs it.
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+import { classify } from '../fault-classifier.js';
+import { AttachRefusedError, BrokerUnavailableError } from './transport.js';
+function relayUrl(target, nodeId) {
+    if ('socketPath' in target) {
+        return `ws+unix://${target.socketPath}:/v1/nodes/${encodeURIComponent(nodeId)}/attach?revive=0`;
+    }
+    const url = new URL(target.previewEndpoint);
+    url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';
+    url.pathname = `/v1/nodes/${encodeURIComponent(nodeId)}/attach`;
+    // A person typed `crtr surface attach` at this node, so an exact parked
+    // resident is woken for it — the same thing the LOCAL attach ensure does for
+    // a direct attach. The bridge leaves a parked node parked without this, which
+    // is what a product page reconnecting its viewport wants.
+    url.search = '?wakeParked=1';
+    url.hash = '';
+    return url.toString();
+}
+export class RelayTransport extends EventEmitter {
+    nodeId;
+    target;
+    ws;
+    closeEmitted = false;
+    constructor(nodeId, target) {
+        super();
+        this.nodeId = nodeId;
+        this.target = target;
+    }
+    get url() {
+        return relayUrl(this.target, this.nodeId);
+    }
+    dial() {
+        const ws = new WebSocket(this.url, {
+            ...('relayToken' in this.target ? { headers: { authorization: `Bearer ${this.target.relayToken}` } } : {}),
+            perMessageDeflate: false,
+        });
+        this.ws = ws;
+        return ws;
+    }
+    connect() {
+        const ws = this.dial();
+        ws.on('open', () => {
+            this.emit('connect');
+        });
+        ws.on('message', (data) => this.onMessage(data));
+        ws.on('error', (err) => this.onError(err));
+        ws.on('close', (code, reason) => this.onClose(code, reason.toString()));
+    }
+    /** Re-dial the same daemon attach endpoint after a broker replacement. */
+    redial(_options) {
+        this.destroy();
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const ws = this.dial();
+            let settled = false;
+            ws.on('open', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.emit('connect');
+                resolve();
+            });
+            ws.on('message', (data) => this.onMessage(data));
+            ws.on('error', (err) => {
+                if (settled) {
+                    this.onError(err);
+                    return;
+                }
+                settled = true;
+                try {
+                    ws.terminate();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            ws.on('close', (code, reason) => {
+                if (!settled)
+                    return; // the 'error' handler above already rejected
+                this.onClose(code, reason.toString());
+            });
+        });
+    }
+    send(frame) {
+        const ws = this.ws;
+        if (ws === undefined || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    destroy() {
+        const ws = this.ws;
+        if (ws !== undefined && ws.readyState <= WebSocket.OPEN) {
+            try {
+                // An explicit 1000: a bare close() sends no status, which the crtrd
+                // bridge receives as 1005 and must not mistake for a dropped viewer.
+                ws.close(1000);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    onMessage(data) {
+        let frame;
+        try {
+            frame = JSON.parse(data.toString());
+        }
+        catch {
+            // A malformed frame must never crash the client — drop it (parity with
+            // the local FrameDecoder's own bad-JSON handling).
+            return;
+        }
+        this.emit('frame', frame);
+    }
+    onError(err) {
+        this.emitError(new Error(`relay transport error: ${err.message}`));
+        // 'close' follows 'error'; teardown converges there.
+    }
+    /** 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. */
+    onClose(code, reason) {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        const classified = classify('viewer↔broker', { code, reason });
+        const gone = code === 1008 ||
+            classified.kind === 'protocol' ||
+            (code === 1011 && (/^no running broker/.test(reason) || /^no node /.test(reason)));
+        if (code === 1008) {
+            // crtrd refused this client before any broker saw its hello: not a broker that is down.
+            this.emitError(new AttachRefusedError(this.nodeId, reason));
+        }
+        else if (gone) {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        this.emit('close');
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

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

@@ -0,0 +1,35 @@
+import { EventEmitter } from 'node:events';
+import { type ClientToBroker } from '../runtime/broker-protocol.js';
+import { type RedialOptions, type Transport } from './transport.js';
+export declare class SocketTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly options;
+    private socket;
+    private decoder;
+    private closeEmitted;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    private redialFaultRecorded;
+    /** `recordsViewerFaults: false` is for an internal daemon reader: its
+     *  connect outcome says nothing about any person's viewer. */
+    constructor(nodeId: string, options?: {
+        recordsViewerFaults?: boolean;
+    });
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath(): string;
+    private recordSocketFault;
+    connect(): void;
+    /** Re-establish the socket after a broker exit, on the SAME stable
+     *  `view.sock` path. Installs a FRESH FrameDecoder (a half-frame from the
+     *  dead stream must not corrupt the new one). */
+    redial(options?: RedialOptions): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private clearSocketFault;
+    private onData;
+    private onError;
+    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;
+}

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

@@ -0,0 +1,187 @@
+// transport-socket.ts — the LOCAL unix-socket Transport. This is the ORIGINAL
+// view-socket wire logic (node:net + the bounded FrameDecoder), unchanged in
+// behavior, extracted behind the `Transport` interface so BrokerClient can
+// also ride a `RelayTransport` (transport-relay.ts).
+//
+// Connects to a node's ALREADY-running headless broker over its unix socket
+// (`nodeDir(id)/view.sock`). NEVER spawns pi, NEVER opens the session
+// `.jsonl` — if the broker is not running, connect fails with a
+// BrokerUnavailableError.
+import { EventEmitter } from 'node:events';
+import { viewSocketPath } from '../canvas/paths.js';
+import { connectViewSocket } from '../runtime/view-socket.js';
+import { classify } from '../fault-classifier.js';
+import { clearNodeFault, recordNodeFault } from '../runtime/broker/daemon-ops.js';
+import { emitEvent } from '../events/emit.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../runtime/broker-protocol.js';
+import { BrokerUnavailableError } from './transport.js';
+export class SocketTransport extends EventEmitter {
+    nodeId;
+    options;
+    socket;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    redialFaultRecorded = false;
+    /** `recordsViewerFaults: false` is for an internal daemon reader: its
+     *  connect outcome says nothing about any person's viewer. */
+    constructor(nodeId, options = {}) {
+        super();
+        this.nodeId = nodeId;
+        this.options = options;
+    }
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath() {
+        return viewSocketPath(this.nodeId);
+    }
+    recordSocketFault(op, err) {
+        if (this.options.recordsViewerFaults === false)
+            return;
+        if (op === 'redial') {
+            if (this.redialFaultRecorded)
+                return;
+            this.redialFaultRecorded = true;
+        }
+        const classified = classify('viewer↔broker', err);
+        void recordNodeFault(this.nodeId, {
+            link: 'viewer↔broker',
+            op,
+            kind: classified.kind,
+            retry: op === 'redial'
+                ? { disposition: 'auto', by: 'client' }
+                : { disposition: 'manual' },
+            message: err instanceof Error ? err.message : String(err),
+        }).catch((error) => {
+            emitEvent({ event: 'broker.daemon.operation.failed', level: 'error', node_id: this.nodeId, error, fields: { operation: 'viewer_fault_record' } });
+        });
+    }
+    connect() {
+        const socket = connectViewSocket(this.nodeId);
+        this.socket = socket;
+        socket.on('connect', () => {
+            this.redialFaultRecorded = false;
+            this.clearSocketFault();
+            this.emit('connect');
+        });
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('error', (err) => this.onError(err, 'connect'));
+        socket.on('close', () => this.onClose());
+    }
+    /** Re-establish the socket after a broker exit, on the SAME stable
+     *  `view.sock` path. Installs a FRESH FrameDecoder (a half-frame from the
+     *  dead stream must not corrupt the new one). */
+    redial(options = {}) {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        if (options.brokerUnavailableIsExpected) {
+            this.redialFaultRecorded = false;
+            this.clearSocketFault();
+        }
+        return new Promise((resolve, reject) => {
+            const socket = connectViewSocket(this.nodeId);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.redialFaultRecorded = false;
+                this.clearSocketFault();
+                this.emit('connect');
+                resolve();
+            });
+            socket.on('data', (chunk) => this.onData(chunk));
+            socket.on('error', (err) => {
+                if (settled) {
+                    this.onError(err, 'redial');
+                    return;
+                }
+                settled = true;
+                const brokerUnavailable = err.code === 'ECONNREFUSED' || err.code === 'ENOENT';
+                if (!options.brokerUnavailableIsExpected || !brokerUnavailable) {
+                    this.recordSocketFault('redial', err);
+                }
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(err);
+            });
+            socket.on('close', () => this.onClose());
+        });
+    }
+    send(frame) {
+        const sock = this.socket;
+        if (sock === undefined || sock.destroyed)
+            return;
+        try {
+            sock.write(encodeFrame(frame));
+        }
+        catch {
+            /* dead socket — 'close' will fire and drive teardown */
+        }
+    }
+    destroy() {
+        const sock = this.socket;
+        if (sock !== undefined && !sock.destroyed) {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    clearSocketFault() {
+        if (this.options.recordsViewerFaults === false)
+            return;
+        void clearNodeFault(this.nodeId, { link: 'viewer↔broker' }).catch((error) => {
+            emitEvent({ event: 'broker.daemon.operation.failed', level: 'error', node_id: this.nodeId, error, fields: { operation: 'viewer_fault_clear' } });
+        });
+    }
+    onData(chunk) {
+        let frames;
+        try {
+            frames = this.decoder.push(chunk);
+        }
+        catch (err) {
+            // A broker that somehow emits an oversized frame (or a corrupt stream):
+            // clean error + drop, never a crash. The 'close' that follows destroy()
+            // is what rejects any in-flight BrokerClient requests.
+            const msg = err instanceof FrameOverflowError
+                ? `broker sent an oversized frame (${err.message}) — disconnecting`
+                : `failed to decode a broker frame: ${String(err)}`;
+            this.emitError(new Error(msg));
+            this.destroy();
+            return;
+        }
+        for (const raw of frames)
+            this.emit('frame', raw);
+    }
+    onError(err, op) {
+        this.recordSocketFault(op, err);
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
+            this.emitError(new BrokerUnavailableError(this.nodeId));
+        }
+        else {
+            this.emitError(new Error(`view socket error: ${err.message}`));
+        }
+        // 'close' typically follows 'error'; teardown converges there.
+    }
+    onClose() {
+        if (this.closeEmitted)
+            return;
+        this.closeEmitted = true;
+        this.emit('close');
+    }
+    /** Emit `error` only when a listener exists — a bare EventEmitter `error`
+     *  with no listener throws, and this transport must never throw uncaught. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+    }
+}

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

@@ -0,0 +1,46 @@
+import type { EventEmitter } from 'node:events';
+import type { BrokerToClient, ClientToBroker } from '../runtime/broker-protocol.js';
+export interface RedialOptions {
+    /** The node is dormant, so no broker at the target is normal until it wakes. */
+    brokerUnavailableIsExpected?: boolean;
+}
+export interface Transport extends EventEmitter {
+    /** Open the connection. Emits 'connect' on success, 'error' on a fatal
+     *  connect-time failure. Call once. */
+    connect(): void;
+    /** Re-establish the connection to the SAME target after a drop. Resolves on
+     *  a fresh 'connect'; rejects on a retryable dial failure (the caller's
+     *  reconnect supervisor decides whether to try again). */
+    redial(options?: RedialOptions): Promise<void>;
+    /** Encode + send one client→broker frame. No-op on a dead/absent connection;
+     *  never throws. */
+    send(frame: ClientToBroker): void;
+    /** Tear down the connection. 'close' fires if it has not already. */
+    destroy(): void;
+    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: 'error', listener: (err: Error) => void): this;
+    off(event: 'connect', listener: () => void): this;
+    off(event: 'error', listener: (err: Error) => void): this;
+}
+/** Surfaced when a Transport's target has no reachable broker — locally, no
+ *  socket file / nothing listening; remotely, a crtrd attach close signaling
+ *  "no broker for this node". The command catches this to exit non-zero with a
+ *  focus/revive hint — same meaning regardless of which Transport raised it. */
+export declare class BrokerUnavailableError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string, message?: string);
+}
+/** A crtrd attach that closed 1008: the daemon refused this client (revoked or
+ *  missing permission for the hello's role, or an invalid node id) before the
+ *  hello reached any broker. A BrokerUnavailableError too, so existing callers
+ *  keep treating it as a terminal connect failure; a viewer that must tell a
+ *  refusal from a broker that is merely restarting (a 1011 "no running broker")
+ *  checks for this class. */
+export declare class AttachRefusedError extends BrokerUnavailableError {
+    readonly reason: string;
+    constructor(nodeId: string, reason: string);
+}

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

@@ -0,0 +1,40 @@
+// transport.ts — the Transport seam: BrokerClient's broker I/O, abstracted
+// so the SAME correlation/pending/close logic can ride either the LOCAL unix
+// socket (SocketTransport, transport-socket.ts) or a WebSocket to crtrd's
+// remote attach endpoint (RelayTransport, transport-relay.ts). Both speak the same
+// broker-protocol JSON frames; only how bytes cross the wire differs.
+//
+// A Transport is a pure duplex frame pump — connect (dial), redial (re-dial
+// the SAME target after a drop), send (one client→broker frame), destroy
+// (tear down). It emits 'connect' once the peer is reachable, one 'frame' per
+// decoded broker→client frame, 'error' for a surfaced problem (including a
+// {@link BrokerUnavailableError} when the target has no reachable broker),
+// and 'close' exactly once when the connection is gone. Everything ABOVE this
+// seam — request correlation, the pending map, redial-vs-give-up policy — is
+// BrokerClient's job and never moves into a Transport implementation.
+/** Surfaced when a Transport's target has no reachable broker — locally, no
+ *  socket file / nothing listening; remotely, a crtrd attach close signaling
+ *  "no broker for this node". The command catches this to exit non-zero with a
+ *  focus/revive hint — same meaning regardless of which Transport raised it. */
+export class BrokerUnavailableError extends Error {
+    nodeId;
+    constructor(nodeId, message) {
+        super(message ?? `node ${nodeId} has no running broker — focus or revive it first`);
+        this.nodeId = nodeId;
+        this.name = 'BrokerUnavailableError';
+    }
+}
+/** A crtrd attach that closed 1008: the daemon refused this client (revoked or
+ *  missing permission for the hello's role, or an invalid node id) before the
+ *  hello reached any broker. A BrokerUnavailableError too, so existing callers
+ *  keep treating it as a terminal connect failure; a viewer that must tell a
+ *  refusal from a broker that is merely restarting (a 1011 "no running broker")
+ *  checks for this class. */
+export class AttachRefusedError extends BrokerUnavailableError {
+    reason;
+    constructor(nodeId, reason) {
+        super(nodeId, `the attach to node ${nodeId} was refused by the canvas (${reason || 'no reason given'})`);
+        this.reason = reason;
+        this.name = 'AttachRefusedError';
+    }
+}

package/dist/core/canvas/app-run.d.ts

@@ -0,0 +1,3 @@
+import type { NodeMeta, NodeRow } from './types.js';
+/** Run IDs also identify terminal roots; only a non-terminal app owns run history. */
+export declare function isAppRun(row: Pick<NodeRow | NodeMeta, 'run_id' | 'grantee'>): boolean;

package/dist/core/canvas/app-run.js

@@ -0,0 +1,4 @@
+/** Run IDs also identify terminal roots; only a non-terminal app owns run history. */
+export function isAppRun(row) {
+    return !!row.run_id && (row.grantee ?? 'app:terminal') !== 'app:terminal';
+}

package/dist/core/canvas/attention.d.ts

@@ -0,0 +1,18 @@
+export interface TicketEntry {
+    node_id: string;
+    name: string;
+    cwd: string;
+    count: number;
+    /** Open ticket titles for this node, newest first. */
+    subjects: string[];
+}
+/** Kept for callers that reset a canvas home in process. SQL has no directory-scan cache to invalidate. */
+export declare function invalidateTicketCounts(): void;
+/** Count pending tickets asked by one node. */
+export declare function countTickets(nodeId: string): Promise<number>;
+/** Pending tickets for every reachable asking node, including the root. */
+export declare function pendingTicketsForView(rootId: string): Promise<TicketEntry[]>;
+/** Per-node pending ticket counts for an explicit node set. */
+export declare function ticketCountsForNodes(ids: string[]): Promise<Record<string, number>>;
+/** Pending tickets across the entire canvas, attributed to asking nodes. */
+export declare function ticketsAcrossCanvas(): Promise<TicketEntry[]>;

package/dist/core/canvas/attention.js

@@ -0,0 +1,47 @@
+// Pending human-request counters across the canvas. The indexed request query is the authority; request directories are retained artifacts, never an inbox index.
+import { listOpenReplyBearingRequests } from '../human/requests.js';
+import { getNode, listNodes, view } from './canvas.js';
+/** Kept for callers that reset a canvas home in process. SQL has no directory-scan cache to invalidate. */
+export function invalidateTicketCounts() { }
+async function ticketSubjects() {
+    const subjects = new Map();
+    for (const request of await listOpenReplyBearingRequests()) {
+        const nodeId = request.requester_node_id;
+        const list = subjects.get(nodeId);
+        if (list === undefined)
+            subjects.set(nodeId, [request.title]);
+        else
+            list.push(request.title);
+    }
+    return subjects;
+}
+/** Count pending tickets asked by one node. */
+export async function countTickets(nodeId) { return (await ticketSubjects()).get(nodeId)?.length ?? 0; }
+/** Pending tickets for every reachable asking node, including the root. */
+export async function pendingTicketsForView(rootId) {
+    const found = await ticketSubjects();
+    const entries = [];
+    for (const id of [rootId, ...await view(rootId)]) {
+        const node = await getNode(id);
+        const subjects = found.get(id) ?? [];
+        if (node !== null && subjects.length > 0)
+            entries.push({ node_id: id, name: node.name, cwd: node.cwd, count: subjects.length, subjects });
+    }
+    return entries;
+}
+/** Per-node pending ticket counts for an explicit node set. */
+export async function ticketCountsForNodes(ids) {
+    const found = await ticketSubjects();
+    return Object.fromEntries(ids.map((id) => [id, found.get(id)?.length ?? 0]));
+}
+/** Pending tickets across the entire canvas, attributed to asking nodes. */
+export async function ticketsAcrossCanvas() {
+    const found = await ticketSubjects();
+    const entries = [];
+    for (const node of await listNodes()) {
+        const subjects = found.get(node.node_id) ?? [];
+        if (subjects.length > 0)
+            entries.push({ node_id: node.node_id, name: node.name, cwd: node.cwd, count: subjects.length, subjects });
+    }
+    return entries;
+}

package/dist/core/canvas/browse/app.d.ts

@@ -0,0 +1,29 @@
+import type { CanvasSource } from '../source.js';
+import type { HistorySearchQuery, HistorySearchResultDTO } from '../../../api/dto/canvas.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../../keybindings/index.js';
+declare const BROWSE_NAV_ACTIONS: readonly ["crtr.browse.quit", "crtr.browse.down", "crtr.browse.up", "crtr.browse.first", "crtr.browse.last", "crtr.browse.expand-or-child", "crtr.browse.collapse-or-parent", "crtr.browse.toggle-fold", "crtr.browse.tab-next", "crtr.browse.tab-previous", "crtr.browse.tab.1", "crtr.browse.tab.2", "crtr.browse.tab.3", "crtr.browse.tab.4", "crtr.browse.tab.5", "crtr.browse.close-subtree", "crtr.browse.sort", "crtr.browse.scope", "crtr.browse.profile", "crtr.browse.residents", "crtr.browse.preview", "crtr.browse.report", "crtr.browse.pin", "crtr.browse.search", "crtr.browse.revive-now", "crtr.browse.focus", "crtr.browse.focus-background", "crtr.browse.yank-id"];
+declare const BROWSE_SEARCH_ACTIONS: readonly ["crtr.browse.search.cancel", "crtr.browse.search.commit", "crtr.browse.search.delete", "crtr.browse.search.quit"];
+export declare function resolveBrowseNavAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_NAV_ACTIONS)[number] | null;
+export declare function resolveBrowseSearchAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof BROWSE_SEARCH_ACTIONS)[number] | null;
+export declare function runBrowse(opts: {
+    returnPane?: string;
+    cwd?: string;
+    /** Profile to show initially. Undefined means no profile is selected, so the
+     *  initial view includes all profiles and the profile toggle is unavailable. */
+    profileId?: string;
+    /** The local API-backed read source. No in-process openDb fallback exists here. */
+    source: CanvasSource;
+    /** Local viewer registry projection. Kept separate from CanvasSource because
+     *  focus rows describe this machine's screens. */
+    viewedNodeIds?: () => Promise<ReadonlySet<string>>;
+    /** Route the `x` close-out through the daemon API (the CLI injects
+     *  `cliClient().closeNode(id, { finish: true })`). Kept as a callback so this
+     *  core module never imports the openDb-reaching `runtime/close.js`. Returns the
+     *  torn-down ids (root + cascaded). */
+    closeNode: (id: string) => Promise<{
+        closed: string[];
+    }>;
+    /** Conversation-content search for `/` (the CLI injects `cliClient().historySearch`). */
+    contentSearch: (q: HistorySearchQuery) => Promise<HistorySearchResultDTO>;
+}): Promise<void>;
+export {};