@north-light/api 0.3.579 → 0.3.587

package/dist/daemon/runs/observer.js

@@ -0,0 +1,441 @@
+import { randomUUID } from 'node:crypto';
+import { openDb, withCanvasWrite } from '../../core/canvas/db.js';
+import { claimReconcilerLease, releaseReconcilerLease, renewReconcilerLease } from '../../core/canvas/reconciler-leases.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { BrokerClient, SocketTransport } from '../../core/broker-client/client.js';
+import { liveExecutionForNode } from '../../core/canvas/executions.js';
+import { runnerForExecution } from '../../core/runtime/runner/index.js';
+import { connectWssView } from '../../core/runtime/view-socket.js';
+import { openMachineView } from '../machine-link/forward.js';
+import { ViewLinkTransport } from './view-transport.js';
+import { emitRunEvent, emitRunSettlement, emitRunStatus } from '../../core/runs/events.js';
+import { cancelOpenQuestions } from '../../core/runs/questions.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { toRunOutcomeDTO } from '../api/map.js';
+import { readOutputResult } from '../../core/runtime/output-result.js';
+/** A root row always carries usage; a missing one reads as a run that has used nothing. */
+const ZERO_USAGE_JSON = JSON.stringify({ input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, cost_usd: 0 });
+const observers = new Map();
+/** One process observes a node at a time: the holder of this lease. A stolen or lapsed lease closes the observer, and the reconcile pass lets another process claim it. */
+const OBSERVER_LANE = 'run-observer';
+const OBSERVER_LEASE_MS = 10_000;
+/** Streamed text is stored as coalesced deltas: one row per flush window, not
+ *  one per view frame. Each row is a canvas write and a full-row insert. */
+const DELTA_FLUSH_MS = 250;
+/** Runs `body` in one transaction that first locks the observer lease row, and only while `owner` still holds it unexpired.
+ *  A successor's claim updates that row, so it waits for this commit: nothing the body writes lands after a theft. Returns
+ *  `{ held: false }` without running `body` when the lease is no longer this owner's. */
+async function whileHoldingLease(nodeId, owner, body) {
+    return await withCanvasWrite(async (db) => {
+        const lease = await db.prepare('SELECT 1 AS held FROM reconciler_leases WHERE lane = ? AND key = ? AND owner = ? AND expires_at > ? FOR SHARE')
+            .get(OBSERVER_LANE, nodeId, owner, new Date().toISOString());
+        return lease === undefined ? { held: false } : { held: true, value: await body() };
+    });
+}
+class RunObserver {
+    nodeId;
+    runId;
+    owner;
+    client;
+    timer;
+    status;
+    /** The node's `pi_pid` as of the last poll. */
+    piPid = null;
+    outcomeRevision;
+    openAssistant = false;
+    assistantStartSequence = 0;
+    /** The newest content block of the open assistant message, as the model streams it. */
+    block = null;
+    thinking = '';
+    output = '';
+    pendingThinking = '';
+    pendingOutput = '';
+    flushTimer;
+    closed = false;
+    lastRenewAt = Date.now();
+    /** The release of this observer's stream columns and lease, started by `close`. */
+    released = Promise.resolve();
+    /** The poll in flight: an interval tick or a caller during one waits for it instead of starting a second. */
+    polling;
+    /** Frames are handled one at a time in arrival order; a handler awaits the db. */
+    frames = Promise.resolve();
+    constructor(nodeId, runId, owner, priorStatus, priorOutcomeRevision) {
+        this.nodeId = nodeId;
+        this.runId = runId;
+        this.owner = owner;
+        this.status = priorStatus;
+        this.outcomeRevision = priorOutcomeRevision;
+        this.timer = setInterval(() => { void this.pollOrClose(); }, 250);
+        this.timer.unref();
+        observers.set(nodeId, this);
+    }
+    /** Reads the last status and outcome this node's stream recorded, registers the observer, and runs its first poll. `owner` is the token of the lease the caller claimed. */
+    static async start(nodeId, runId, owner) {
+        const db = await openDb();
+        const priorOutcome = await db.prepare("SELECT body_json FROM run_events WHERE node_id = ? AND type = ? ORDER BY sequence_number DESC LIMIT 1").get(nodeId, nodeId === runId ? 'node.settled' : 'child.settled');
+        const priorStatus = await db.prepare("SELECT body_json FROM run_events WHERE node_id = ? AND type = 'node.status.changed' ORDER BY sequence_number DESC LIMIT 1").get(nodeId);
+        const observer = new RunObserver(nodeId, runId, owner, priorStatus ? JSON.parse(priorStatus.body_json).status : undefined, priorOutcome ? JSON.parse(priorOutcome.body_json).outcome.revision : undefined);
+        // A message open in a previous holder's view is unknown here; its columns are cleared and the next message_start writes them again.
+        await observer.writeStream(null, null);
+        await observer.poll();
+        return observer;
+    }
+    /** The interval's poll: a throw here would be an uncaught exception in the daemon, so it ends this observer instead. */
+    async pollOrClose() {
+        try {
+            await this.poll();
+        }
+        catch (error) {
+            this.close();
+            emitEvent({ level: 'error', event: 'daemon.runs.observer_failed', node_id: this.nodeId, error });
+        }
+    }
+    /** Emits status and outcome changes, then holds a broker connection only
+     *  while the node has a live broker; a dormant node's observer closes. */
+    poll() {
+        if (this.polling === undefined)
+            this.polling = this.pollOnce().finally(() => { this.polling = undefined; });
+        return this.polling;
+    }
+    /** Extends the lease about every third of its length. A failed renewal means another process holds the node now (or this one stalled past expiry); this observer stops. */
+    async holdLease() {
+        if (Date.now() - this.lastRenewAt < OBSERVER_LEASE_MS / 3)
+            return true;
+        if (!await renewReconcilerLease(OBSERVER_LANE, this.nodeId, this.owner, OBSERVER_LEASE_MS))
+            return false;
+        this.lastRenewAt = Date.now();
+        return true;
+    }
+    /** Writes the open message's start sequence and newest block to the node's row, only while this observer holds the lease. `null, null` records no open message. */
+    async writeStream(startSequence, block, keepSequence = false) {
+        const result = await (await openDb()).prepare(`UPDATE nodes SET ${keepSequence ? '' : `stream_message_seq = ${startSequence === null ? 'NULL' : '(SELECT event_cursor FROM nodes WHERE node_id = ?)'},`} stream_block = ?
+      WHERE node_id = ? AND EXISTS (SELECT 1 FROM reconciler_leases WHERE lane = ? AND key = ? AND owner = ? AND expires_at > ?)`)
+            .run(...(startSequence === null || keepSequence ? [] : [this.runId]), block === null ? null : JSON.stringify(block), this.nodeId, OBSERVER_LANE, this.nodeId, this.owner, new Date().toISOString());
+        return result.changes === 1;
+    }
+    async pollOnce() {
+        if (this.closed)
+            return;
+        if (!await this.holdLease()) {
+            this.close();
+            return;
+        }
+        const node = await getNode(this.nodeId);
+        if (!node || node.run_id !== this.runId || !await runRootExists(this.runId)) {
+            this.close();
+            return;
+        }
+        this.piPid = node.pi_pid ?? null;
+        const status = node.pi_pid === null ? 'dormant' : node.status;
+        if (this.status !== status) {
+            if (!(await whileHoldingLease(this.nodeId, this.owner, () => emitRunStatus(this.runId, this.nodeId, status, node.intent ?? null))).held) {
+                this.close();
+                return;
+            }
+            this.status = status;
+        }
+        const outcome = await toRunOutcomeDTO(node);
+        if (outcome && outcome.revision !== this.outcomeRevision && Date.now() - Date.parse(outcome.settled_at) < 30 * 24 * 60 * 60_000) {
+            if (this.nodeId === this.runId) {
+                const children = await (await openDb()).prepare('SELECT node_id FROM nodes WHERE run_id = ? AND node_id != ? ORDER BY created DESC').all(this.runId, this.runId);
+                for (const child of children) {
+                    await ensureRunObserver(child.node_id, this.runId);
+                    await observers.get(child.node_id)?.poll();
+                }
+            }
+            this.outcomeRevision = outcome.revision;
+            // D2-RES-5: the settlement a result made carries the value `run.get` returns.
+            const result = this.nodeId === this.runId && outcome.kind === 'result' ? await readOutputResult(this.nodeId) : undefined;
+            const settled = await whileHoldingLease(this.nodeId, this.owner, () => this.nodeId === this.runId
+                ? emitRunSettlement(this.runId, this.nodeId, 'node.settled', { outcome, usage: JSON.parse(node.usage_json ?? ZERO_USAGE_JSON), ...(result === undefined ? {} : { result }) })
+                : emitRunSettlement(this.runId, this.nodeId, 'child.settled', { child_node_id: this.nodeId, outcome }));
+            if (!settled.held) {
+                this.close();
+                return;
+            }
+            // A run that settles, by any reason, or an asking node that is closed,
+            // cancels its open questions. Terminal runs keep the inbox's page behavior.
+            if (node.grantee && node.grantee !== 'app:terminal') {
+                const target = this.nodeId === this.runId ? { run_id: this.runId } : { node_id: this.nodeId };
+                void cancelOpenQuestions(target, this.nodeId === this.runId ? 'the run settled' : 'the asking node was closed')
+                    .catch((error) => emitEvent({ level: 'error', event: 'daemon.runs.question_cancel_failed', node_id: this.nodeId, error }));
+            }
+        }
+        if (node.pi_pid === null)
+            this.close();
+        else
+            await this.connect();
+    }
+    async settlePoll() {
+        await this.polling?.catch(() => { });
+        await this.frames;
+        await this.released;
+    }
+    /** An open view socket keeps a Blaxel sandbox awake, so an idle sandbox node (design D18) gets no view link until the wake path clears its `idle_at`. */
+    async viewAdmitted() {
+        const execution = await liveExecutionForNode(this.nodeId);
+        return !(execution?.runner === 'blaxel' && execution.idleAt !== null);
+    }
+    /** Closes the view link once the frames already received are handled and the open message is cleared from the node's row. */
+    async dropView() {
+        const client = this.client;
+        if (!client)
+            return;
+        // Detached first: a frame still queued or arriving now is ignored by `handleFrame`, so the clearing write below is the last stream write.
+        this.client = undefined;
+        await this.frames;
+        await this.flushDeltas();
+        this.discardDeltas();
+        this.openAssistant = false;
+        this.block = null;
+        await this.writeStream(null, null);
+        client.close();
+    }
+    async connect() {
+        if (this.closed)
+            return;
+        if (!await this.viewAdmitted()) {
+            await this.dropView();
+            return;
+        }
+        if (this.client)
+            return;
+        const transport = await viewTransport(this.nodeId);
+        // The node can go idle while its transport is being made, so admission is checked again before the client dials.
+        const admitted = await this.viewAdmitted();
+        if (this.client || this.closed || !admitted) {
+            transport.destroy();
+            return;
+        }
+        const client = new BrokerClient(this.nodeId, { transport });
+        this.client = client;
+        client.on('connect', () => client.send({ type: 'hello', role: 'observer', client_id: randomUUID(), attends: false }));
+        const handleFrame = async (frame) => {
+            if (this.closed || this.client !== client)
+                return;
+            if (frame.type === 'message_start' && frame.message.role === 'assistant') {
+                this.discardDeltas();
+                this.openAssistant = true;
+                this.block = null;
+                this.thinking = '';
+                this.output = '';
+                if (!await this.writeStream('run-cursor', null)) {
+                    this.close();
+                    return;
+                }
+                this.assistantStartSequence = Number((await (await openDb()).prepare('SELECT stream_message_seq FROM nodes WHERE node_id = ?').get(this.nodeId)).stream_message_seq);
+            }
+            if (frame.type === 'message_update' && frame.message.role === 'assistant' && this.openAssistant) {
+                const blocks = frame.message.content;
+                if (!Array.isArray(blocks))
+                    return;
+                const last = blocks.at(-1);
+                if (last && typeof last === 'object' && 'type' in last) {
+                    if (last.type === 'toolCall')
+                        this.block = { kind: 'tool_call', name: 'name' in last && typeof last.name === 'string' ? last.name : '' };
+                    else if (last.type === 'text' || last.type === 'thinking')
+                        this.block = { kind: last.type };
+                }
+                if (!await this.writeStream(null, this.block, true)) {
+                    this.close();
+                    return;
+                }
+                const thinking = blocks.filter((block) => block?.type === 'thinking').map((block) => block.thinking).join('');
+                const output = blocks.filter((block) => block?.type === 'text').map((block) => block.text).join('');
+                const thinkingDelta = thinking.startsWith(this.thinking) ? thinking.slice(this.thinking.length) : thinking;
+                const outputDelta = output.startsWith(this.output) ? output.slice(this.output.length) : output;
+                this.thinking = thinking;
+                this.output = output;
+                this.pendingThinking += thinkingDelta;
+                this.pendingOutput += outputDelta;
+                if ((this.pendingThinking || this.pendingOutput) && !this.flushTimer) {
+                    this.flushTimer = setTimeout(() => {
+                        this.flushDeltas().catch((error) => emitEvent({ level: 'error', event: 'daemon.runs.observer_failed', node_id: this.nodeId, error }));
+                    }, DELTA_FLUSH_MS);
+                    this.flushTimer.unref();
+                }
+            }
+            if (frame.type === 'message_end' && frame.message.role === 'assistant') {
+                await this.flushDeltas();
+                this.openAssistant = false;
+                this.block = null;
+                await this.writeStream(null, null);
+            }
+        };
+        client.on('frame', (frame) => {
+            this.frames = this.frames.then(() => handleFrame(frame)).catch((error) => {
+                this.close();
+                emitEvent({ level: 'error', event: 'daemon.runs.observer_failed', node_id: this.nodeId, error });
+            });
+        });
+        client.on('error', () => { });
+        client.on('close', () => {
+            if (this.client !== client)
+                return;
+            this.client = undefined;
+            this.discardDeltas();
+            this.openAssistant = false;
+            this.block = null;
+            this.released = this.released.then(async () => { await this.writeStream(null, null); }).catch(() => { });
+        });
+        client.connect();
+    }
+    async flushDeltas() {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        const thinking = this.pendingThinking;
+        const output = this.pendingOutput;
+        this.pendingThinking = '';
+        this.pendingOutput = '';
+        if (!this.openAssistant || (!thinking && !output))
+            return;
+        // The append and the view frame travel on different sockets. Once the
+        // entry has been stored, even a delayed frame is no longer a delta.
+        const written = await whileHoldingLease(this.nodeId, this.owner, async () => {
+            const completed = await (await openDb()).prepare("SELECT 1 FROM run_events WHERE run_id = ? AND node_id = ? AND sequence_number >= ? AND type IN ('node.output_text.done', 'node.thinking.done', 'usage') LIMIT 1")
+                .get(this.runId, this.nodeId, this.assistantStartSequence);
+            if (completed) {
+                this.openAssistant = false;
+                return;
+            }
+            if (thinking)
+                await emitRunEvent(this.runId, this.nodeId, 'node.thinking.delta', { delta: thinking });
+            if (output)
+                await emitRunEvent(this.runId, this.nodeId, 'node.output_text.delta', { delta: output });
+        });
+        if (!written.held)
+            this.close();
+    }
+    discardDeltas() {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        this.pendingThinking = '';
+        this.pendingOutput = '';
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.discardDeltas();
+        clearInterval(this.timer);
+        observers.delete(this.nodeId);
+        // Clear the open message and give the lease up, so another process can take over at once; a stolen lease makes both no-ops.
+        this.released = this.released.then(async () => { await this.writeStream(null, null); await releaseReconcilerLease(OBSERVER_LANE, this.nodeId, this.owner); }).then(() => undefined)
+            .catch((error) => { emitEvent({ level: 'error', event: 'daemon.runs.observer_release_failed', node_id: this.nodeId, error }); });
+        const client = this.client;
+        this.client = undefined;
+        client?.close();
+    }
+}
+/** The transport to the node's live broker, from where its runner says viewers connect: this machine's `view.sock`, or
+ *  the `/view` WebSocket behind a sandbox's preview. */
+async function viewTransport(nodeId) {
+    const execution = await liveExecutionForNode(nodeId);
+    if (execution === null)
+        return new SocketTransport(nodeId, { recordsViewerFaults: false });
+    const address = await runnerForExecution(execution.runner).viewerAddress(execution);
+    if (address.kind === 'machine')
+        return new ViewLinkTransport(nodeId, () => openMachineView(address.environmentId, nodeId));
+    return address.kind === 'unix'
+        ? new SocketTransport(nodeId, { recordsViewerFaults: false })
+        : new ViewLinkTransport(nodeId, () => connectWssView(address.url, address.headers));
+}
+/** The start sequence of the node's open assistant message, from the observer's columns; null when none is open or the node has no live broker. */
+export async function openAssistantMessageStartSequence(nodeId) {
+    const row = await (await openDb()).prepare('SELECT stream_message_seq FROM node_rows WHERE node_id = ? AND pi_pid IS NOT NULL').get(nodeId);
+    return row?.stream_message_seq == null ? null : Number(row.stream_message_seq);
+}
+/** The newest block of the node's open assistant message; null when no message is open or nothing has streamed yet. */
+export async function openAssistantBlock(nodeId) {
+    const row = await (await openDb()).prepare('SELECT stream_message_seq, stream_block FROM node_rows WHERE node_id = ? AND pi_pid IS NOT NULL').get(nodeId);
+    return row?.stream_message_seq == null || row.stream_block === null ? null : JSON.parse(row.stream_block);
+}
+/** Test-only: stop every observer and wait out the polls in flight, so none touches a home the test is about to delete. */
+export async function closeRunObserversForTests() {
+    const open = [...observers.values()];
+    for (const observer of open)
+        observer.close();
+    await Promise.all(open.map((observer) => observer.settlePoll()));
+    await Promise.all([...starting.values()].map((start) => start.catch(() => { })));
+}
+/** Whether the run still has its root row, which holds the event cursor every append reads. */
+async function runRootExists(runId) {
+    return await (await openDb()).prepare('SELECT 1 FROM nodes WHERE node_id = ? AND run_id = ? AND event_cursor IS NOT NULL').get(runId, runId) !== undefined;
+}
+/** Observers whose start is in flight, so two callers for one node never start two. */
+const starting = new Map();
+export async function ensureRunObserver(nodeId, runId) {
+    const pending = starting.get(nodeId);
+    if (pending)
+        return pending;
+    if (observers.has(nodeId))
+        return;
+    const start = startRunObserver(nodeId, runId).finally(() => starting.delete(nodeId));
+    starting.set(nodeId, start);
+    return start;
+}
+async function startRunObserver(nodeId, runId) {
+    // A node whose run root is gone has no stream to append to; nothing observes it.
+    if (!await runRootExists(runId))
+        return;
+    // One process observes a node: whoever holds the lease. A held lease means another process already is.
+    const owner = randomUUID();
+    if (await claimReconcilerLease(OBSERVER_LANE, nodeId, owner, OBSERVER_LEASE_MS) === undefined)
+        return;
+    try {
+        if (nodeId !== runId) {
+            const node = await getNode(nodeId);
+            const exists = await (await openDb()).prepare("SELECT 1 FROM run_events WHERE run_id = ? AND node_id = ? AND type = 'child.started' LIMIT 1").get(runId, nodeId);
+            if (!exists && node && Date.now() - Date.parse(node.created) < 30 * 24 * 60 * 60_000) {
+                if (!(await whileHoldingLease(nodeId, owner, () => emitRunEvent(runId, nodeId, 'child.started', { child_node_id: nodeId, kind: node.kind }))).held)
+                    return;
+            }
+        }
+        await RunObserver.start(nodeId, runId, owner);
+    }
+    catch (error) {
+        await releaseReconcilerLease(OBSERVER_LANE, nodeId, owner).catch(() => { });
+        throw error;
+    }
+}
+/** Observes run nodes with a live broker, plus those whose current outcome
+ *  (settled within the event retention window) has no `node.settled` event yet. */
+export async function pollRunObservers() {
+    const cutoff = new Date(Date.now() - 30 * 24 * 60 * 60_000).toISOString();
+    // A settled node is owed an observer until a settled event carries its current outcome revision; `run_events.body_json` is text, so the revision is read here.
+    const candidates = await (await openDb()).prepare(`SELECT n.node_id, n.run_id, n.pi_pid, COALESCE(n.outcome_revision, 1) AS revision, e.body_json
+    FROM node_rows n
+    LEFT JOIN run_events e ON n.pi_pid IS NULL AND e.run_id = n.run_id AND e.node_id = n.node_id
+      AND e.type = CASE WHEN n.node_id = n.run_id THEN 'node.settled' ELSE 'child.settled' END
+    WHERE n.run_id IS NOT NULL AND (n.pi_pid IS NOT NULL OR (n.outcome_at IS NOT NULL AND n.outcome_at > ? AND n.outcome_reason != 'parked'))`)
+        .all(cutoff);
+    const owed = new Map();
+    for (const row of candidates) {
+        const entry = owed.get(row.node_id) ?? { node_id: row.node_id, run_id: row.run_id, reported: false };
+        if (row.body_json !== null && JSON.parse(row.body_json).outcome?.revision === row.revision)
+            entry.reported = true;
+        owed.set(row.node_id, entry);
+    }
+    const nodes = [...owed.values()].filter((entry) => !entry.reported);
+    for (const node of nodes) {
+        // One node's observer failing must not stop the others, nor the rest of the supervise tick.
+        try {
+            await ensureRunObserver(node.node_id, node.run_id);
+            reportedFailures.delete(node.node_id);
+        }
+        catch (error) {
+            reportObserverFailure(node.node_id, error);
+        }
+    }
+}
+/** A failure that repeats every tick is logged once per node and message, not every two seconds. */
+const reportedFailures = new Map();
+function reportObserverFailure(nodeId, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (reportedFailures.get(nodeId) === message)
+        return;
+    reportedFailures.set(nodeId, message);
+    emitEvent({ level: 'error', event: 'daemon.runs.observer_failed', node_id: nodeId, error });
+}

package/dist/daemon/runs/view-transport.d.ts

@@ -0,0 +1,19 @@
+import { EventEmitter } from 'node:events';
+import { type RedialOptions, type Transport } from '../../core/broker-client/transport.js';
+import { type ClientToBroker } from '../../core/runtime/broker-protocol.js';
+import type { BrokerViewLink } from '../../core/runtime/view-socket.js';
+export declare class ViewLinkTransport extends EventEmitter implements Transport {
+    private readonly nodeId;
+    private readonly open;
+    private link;
+    private decoder;
+    private closeEmitted;
+    constructor(nodeId: string, open: () => BrokerViewLink);
+    connect(): void;
+    redial(_options?: RedialOptions): Promise<void>;
+    send(frame: ClientToBroker): void;
+    destroy(): void;
+    private dial;
+    /** `error` is emitted only when a listener exists: a bare EventEmitter `error` throws. */
+    private emitError;
+}

package/dist/daemon/runs/view-transport.js

@@ -0,0 +1,81 @@
+// A broker-client Transport over a BrokerViewLink: the link a sandbox broker's `/view` WebSocket gives
+// (`connectWssView`). Frames are newline-terminated lines in both directions, as on a view.sock.
+import { EventEmitter } from 'node:events';
+import { BrokerUnavailableError } from '../../core/broker-client/transport.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder } from '../../core/runtime/broker-protocol.js';
+export class ViewLinkTransport extends EventEmitter {
+    nodeId;
+    open;
+    link;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    constructor(nodeId, open) {
+        super();
+        this.nodeId = nodeId;
+        this.open = open;
+    }
+    connect() {
+        this.dial(() => this.emit('connect'));
+    }
+    redial(_options) {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const link = this.dial(() => { if (settled)
+                return; settled = true; this.emit('connect'); resolve(); });
+            link.on('error', (error) => { if (!settled) {
+                settled = true;
+                link.destroy();
+                reject(error);
+            } });
+        });
+    }
+    send(frame) {
+        if (this.link === undefined || this.link.destroyed)
+            return;
+        try {
+            this.link.write(encodeFrame(frame));
+        }
+        catch { /* a dead link closes, which drives teardown */ }
+    }
+    destroy() {
+        if (this.link !== undefined && !this.link.destroyed)
+            this.link.destroy();
+    }
+    dial(onConnect) {
+        const link = this.open();
+        this.link = link;
+        link.on('connect', onConnect);
+        link.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = this.decoder.push(chunk);
+            }
+            catch (error) {
+                this.emitError(new Error(`failed to decode a broker frame: ${String(error)}`));
+                this.destroy();
+                return;
+            }
+            for (const frame of frames)
+                this.emit('frame', frame);
+        });
+        link.on('error', (error) => {
+            const unavailable = error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND';
+            this.emitError(unavailable ? new BrokerUnavailableError(this.nodeId) : new Error(`broker view error: ${error.message}`));
+        });
+        link.on('close', () => {
+            if (this.closeEmitted)
+                return;
+            this.closeEmitted = true;
+            this.emit('close');
+        });
+        return link;
+    }
+    /** `error` is emitted only when a listener exists: a bare EventEmitter `error` throws. */
+    emitError(error) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', error);
+    }
+}

package/dist/daemon/structured-requests/sidecar.d.ts

@@ -0,0 +1,4 @@
+import { type StructuredRequestRow } from '../../core/canvas/structured-requests.js';
+import type { StructuredOutputMode } from '../../core/runtime/structured-output.js';
+/** Admit a node/message schema request: the pending `structured_requests` row is the whole request. */
+export declare function admitLegacyStructuredOutput(nodeId: string, submission: StructuredOutputMode, schema: Record<string, unknown>, requestMessageId?: string): Promise<StructuredRequestRow>;

package/dist/daemon/structured-requests/sidecar.js

@@ -0,0 +1,5 @@
+import { registerLegacyStructuredRequest } from '../../core/canvas/structured-requests.js';
+/** Admit a node/message schema request: the pending `structured_requests` row is the whole request. */
+export async function admitLegacyStructuredOutput(nodeId, submission, schema, requestMessageId) {
+    return await registerLegacyStructuredRequest(nodeId, submission, schema, requestMessageId);
+}