@crouton-kit/crouter 0.3.60 → 0.3.62

package/dist/clients/attach/transport-socket.js

@@ -0,0 +1,164 @@
+// transport-socket.ts — the LOCAL unix-socket Transport. This is the ORIGINAL
+// `ViewSocketClient` wire logic (node:net + the bounded FrameDecoder),
+// unchanged in behavior, extracted behind the `Transport` interface so
+// ViewSocketClient 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 { createConnection } from 'node:net';
+import { viewSocketPath } from '../../core/canvas/paths.js';
+import { classify } from '../../core/fault-classifier.js';
+import { clearFault, recordFault } from '../../core/runtime/fault.js';
+import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+import { BrokerUnavailableError } from './transport.js';
+export class SocketTransport extends EventEmitter {
+    nodeId;
+    socket;
+    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    closeEmitted = false;
+    /** One redial fault line per reconnect EPISODE, not per attempt — see
+     *  {@link recordSocketFault}. */
+    redialFaultRecorded = false;
+    constructor(nodeId) {
+        super();
+        this.nodeId = nodeId;
+    }
+    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
+    get socketPath() {
+        return viewSocketPath(this.nodeId);
+    }
+    recordSocketFault(op, err) {
+        if (op === 'redial') {
+            if (this.redialFaultRecorded)
+                return;
+            this.redialFaultRecorded = true;
+        }
+        const classified = classify('viewer↔broker', err);
+        recordFault(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),
+        });
+    }
+    connect() {
+        const socket = createConnection(this.socketPath);
+        this.socket = socket;
+        socket.on('connect', () => {
+            this.redialFaultRecorded = false;
+            clearFault(this.nodeId, { link: 'viewer↔broker' });
+            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() {
+        this.destroy();
+        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
+        this.closeEmitted = false;
+        return new Promise((resolve, reject) => {
+            const socket = createConnection(this.socketPath);
+            this.socket = socket;
+            let settled = false;
+            socket.on('connect', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.redialFaultRecorded = false;
+                clearFault(this.nodeId, { link: 'viewer↔broker' });
+                this.emit('connect');
+                resolve();
+            });
+            socket.on('data', (chunk) => this.onData(chunk));
+            socket.on('error', (err) => {
+                if (settled) {
+                    this.onError(err, 'redial');
+                    return;
+                }
+                settled = true;
+                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 */
+            }
+        }
+    }
+    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 ViewSocketClient 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/clients/attach/transport.d.ts

@@ -0,0 +1,32 @@
+import type { EventEmitter } from 'node:events';
+import type { BrokerToClient, ClientToBroker } from '../../core/runtime/broker-protocol.js';
+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(): 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 relay 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);
+}

package/dist/clients/attach/transport.js

@@ -0,0 +1,26 @@
+// transport.ts — the Transport seam: ViewSocketClient'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 relayed WebSocket to a
+// remote broker (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
+// ViewSocketClient'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 relay 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) {
+        super(`node ${nodeId} has no running broker — focus or revive it first`);
+        this.nodeId = nodeId;
+        this.name = 'BrokerUnavailableError';
+    }
+}

package/dist/clients/attach/view-socket.d.ts

@@ -1,28 +1,26 @@
 import { EventEmitter } from 'node:events';
 import type { NodeRow } from '../../core/canvas/types.js';
-import { type BrokerDataFrame, type BrokerToClient, type ClientToBroker, type DequeueFrame, type GetSettingsFrame, type GetTreeFrame, type ListModelsFrame, type ListScopedModelsFrame, type ListSessionsFrame } from '../../core/runtime/broker-protocol.js';
+import type { BrokerDataFrame, BrokerToClient, ClientToBroker, DequeueFrame, GetSettingsFrame, GetTreeFrame, ListModelsFrame, ListScopedModelsFrame, ListSessionsFrame } from '../../core/runtime/broker-protocol.js';
+import { 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 ViewSocketClient.request} mints the `id`, sends the frame, and resolves
  *  with the matching `data` reply. The picker/operator code builds these; the
  *  socket 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'>;
-/** Surfaced when the node has no reachable broker at connect time (no socket
- *  file, or a stale socket with nothing listening). The command catches this to
- *  exit non-zero with a focus/revive hint. */
 /** 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 `view.sock` while the node is still alive — a yield
+ *  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` is NOT
  *  terminal — an idle-release node revives on its next inbox wake, so keep
  *  trying (the supervisor waits at a relaxed cadence for as long as the row
- *  stays live). */
+ *  stays live). Local canvas rows only — a remote target has no local row, so
+ *  callers driving a remote attach must not consult this (see attach-cmd.ts). */
 export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
-export declare class BrokerUnavailableError extends Error {
-    readonly nodeId: string;
-    constructor(nodeId: string);
-}
 /** The plan-fixed interface (Wave 3): `connect()`, `on('frame', …)`,
  *  `send(frame)`, `on('close', …)`, plus `connect`/`error` events. */
 export interface ViewSocketClient {
@@ -39,52 +37,50 @@ export interface ViewSocketClient {
 }
 export declare class ViewSocketClient extends EventEmitter {
     private readonly nodeId;
-    private socket;
-    private decoder;
+    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 onData}, the request's timeout, or socket teardown. */
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
     private pending;
-    /** One redial fault line per reconnect EPISODE, not per attempt: the
-     *  supervisor redials for as long as the node can come back (a dormant node
-     *  may be gone for hours), so a per-attempt record would grow fault.log
-     *  without bound. Set on the first failed redial, reset on any successful
-     *  connect. */
-    private redialFaultRecorded;
-    constructor(nodeId: string);
-    private recordSocketFault;
+    /** `transport` defaults to a {@link SocketTransport} against this node's
+     *  local `view.sock` — today's behavior, unchanged. Pass a
+     *  {@link RelayTransport} to attach a remote node instead; every method
+     *  below behaves identically either way. */
+    constructor(nodeId: string, transport?: Transport);
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or
-     *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
-     *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
-     *  The reply is narrowed by the caller on its `kind`. */
+     *  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 (socket gone / decode error) so a
-     *  picker fetch never hangs past the connection it rode on. */
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
     private rejectAllPending;
-    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
-    get socketPath(): string;
-    /** Open the connection. Wire up listeners; emits `connect` on success or
-     *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
-     *  failure. Idempotent guard is the caller's job — call once. */
+    /** 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 socket after a broker exit (a yield→revive cycle), on the
-     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
-     *  from the dead stream must not corrupt the new one) and resets the close
-     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
-     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
-     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
-     *  post-connect error flows through the normal `onError`→`close` path. */
+    /** 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(): Promise<void>;
-    /** Encode + write one client→broker frame. No-op on a dead/absent socket
-     *  (a `close` event drives teardown); never throws. */
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
     send(frame: ClientToBroker): void;
-    /** Detach: destroy the socket. `close` fires → the caller tears down. */
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
     close(): void;
-    private onData;
-    private onError;
+    private onFrame;
     private onClose;
-    private destroy;
     /** Emit `error` only when a listener exists — a bare EventEmitter `error`
      *  with no listener throws, and this client must never throw uncaught. */
     private emitError;