@thenewlabs/entangle-serve 2.6.2 → 2.7.0

package/dist/ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAgBrE,mEAAmE;AACnE,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAkB,CAAC;AAI/C,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,oEAAoE;AACpE,MAAM,MAAM,cAAc,GACtB;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC5C,uDAAuD;GACrD;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,CAAC,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,cAAc;AACxB,4CAA4C;AAC1C;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC9B,iEAAiE;GAC/D;IAAE,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,CAAC,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE;AAC/C,4CAA4C;GAC1C;IAAE,CAAC,EAAE,SAAS,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,CAAC,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEvC,mDAAmD;AACnD,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,cAAc,CAAC;AAIzD,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CASrD;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAErE;AAID;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA2B;IAEzC;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,EAAE;CAoBtC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAC7B,MAAM,IAAI,CAgBZ"}

package/dist/ipc.js

@@ -0,0 +1,115 @@
+// Local unix-socket IPC framing between the `entangle serve` daemon and an
+// attached terminal client. This is a *local* transport (a filesystem socket
+// secured by directory permissions — see session-registry.ts), so there is no
+// encryption here: confidentiality is the registry's job.
+//
+// Framing: a 4-byte big-endian (network order) unsigned length prefix followed
+// by exactly that many bytes of a UTF-8 JSON payload. Terminal data (which is
+// binary) travels as base64 strings inside the JSON so the wire is always valid
+// JSON and we never have to deal with mixed binary/text framing.
+//
+//   +----------------+----------------------------+
+//   | uint32 BE len  | JSON payload (len bytes)    |
+//   +----------------+----------------------------+
+/** Bytes of the length prefix that precedes every JSON payload. */
+export const HEADER_BYTES = 4;
+/**
+ * Maximum accepted payload size. A frame declaring a larger payload is rejected
+ * (the decoder errors) rather than buffering an unbounded amount of memory for
+ * a payload that may never fully arrive. 8 MB comfortably fits a full-screen
+ * replay while capping a hostile/framed-wrong peer.
+ */
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+// --- base64 helpers for binary chunks --------------------------------------
+/** Encode a binary terminal chunk as a base64 string for the JSON wire. */
+export function encodeChunk(data) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('base64');
+}
+/** Decode a base64 chunk string back into a Buffer of terminal bytes. */
+export function decodeChunk(chunk) {
+    return Buffer.from(chunk, 'base64');
+}
+// --- Encoding --------------------------------------------------------------
+/**
+ * Serialize a message to a length-prefixed frame: a 4-byte big-endian payload
+ * length followed by the UTF-8 JSON payload.
+ *
+ * @throws if the resulting payload exceeds {@link MAX_FRAME_BYTES}.
+ */
+export function encodeMessage(msg) {
+    const payload = Buffer.from(JSON.stringify(msg), 'utf8');
+    if (payload.length > MAX_FRAME_BYTES) {
+        throw new Error(`IPC frame too large to encode: ${payload.length} > ${MAX_FRAME_BYTES}`);
+    }
+    const frame = Buffer.allocUnsafe(HEADER_BYTES + payload.length);
+    frame.writeUInt32BE(payload.length, 0);
+    payload.copy(frame, HEADER_BYTES);
+    return frame;
+}
+/** Encode and write a single message to a socket/stream. */
+export function writeMessage(socket, msg) {
+    return socket.write(encodeMessage(msg));
+}
+// --- Decoding --------------------------------------------------------------
+/**
+ * Incrementally decodes length-prefixed frames from a byte stream, tolerating
+ * partial reads (a frame split across chunks) and coalesced reads (many frames
+ * in one chunk). A frame whose declared length exceeds {@link MAX_FRAME_BYTES}
+ * makes {@link push} throw rather than buffering unbounded memory — callers
+ * should treat that as a fatal protocol error and close the socket.
+ */
+export class FrameDecoder {
+    buffer = Buffer.alloc(0);
+    /**
+     * Feed received bytes; returns every message that became fully available.
+     * @throws if a frame declares a payload larger than {@link MAX_FRAME_BYTES}
+     *         or if a completed payload is not valid JSON.
+     */
+    push(chunk) {
+        const messages = [];
+        this.buffer = this.buffer.length === 0
+            ? Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+            : Buffer.concat([this.buffer, Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)]);
+        while (this.buffer.length >= HEADER_BYTES) {
+            const length = this.buffer.readUInt32BE(0);
+            if (length > MAX_FRAME_BYTES) {
+                throw new Error(`IPC frame too large: ${length} > ${MAX_FRAME_BYTES}`);
+            }
+            if (this.buffer.length < HEADER_BYTES + length)
+                break; // wait for more bytes
+            const payload = this.buffer.subarray(HEADER_BYTES, HEADER_BYTES + length);
+            messages.push(JSON.parse(payload.toString('utf8')));
+            this.buffer = this.buffer.subarray(HEADER_BYTES + length);
+        }
+        return messages;
+    }
+}
+/**
+ * Attach a {@link FrameDecoder} to a socket and invoke `onMessage` for each
+ * decoded message. A decode error (oversize frame or malformed JSON) is routed
+ * to `onError` if provided, otherwise emitted on the socket as an `'error'`.
+ *
+ * @returns a detach function that removes the installed `'data'` listener.
+ */
+export function createMessageReader(socket, onMessage, onError) {
+    const decoder = new FrameDecoder();
+    const onData = (chunk) => {
+        let messages;
+        try {
+            messages = decoder.push(chunk);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (onError)
+                onError(error);
+            else
+                socket.emit('error', error);
+            return;
+        }
+        for (const msg of messages)
+            onMessage(msg);
+    };
+    socket.on('data', onData);
+    return () => socket.off('data', onData);
+}
+//# sourceMappingURL=ipc.js.map

package/dist/ipc.js.map

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

package/dist/remote-host-session.d.ts

@@ -0,0 +1,72 @@
+import type { Socket } from 'net';
+import type { WindowStateBody } from '@thenewlabs/entangle-protocol';
+import type { HostSession } from './host-session.js';
+/**
+ * The socket-backed {@link HostSession}: the CLIENT half of the daemon/client
+ * split. It renders the SAME host UI (host-terminal.ts) that {@link LocalHostSession}
+ * does, but every read is a cached value fed by the daemon over a local unix
+ * socket and every action is a framed message written back to it.
+ *
+ * On construction it sends a `hello` (so the daemon learns the client's terminal
+ * size) and starts decoding {@link DaemonToClient} frames: live output, the
+ * post-attach replay, window-state, viewer count, captured logs, the session URL
+ * and the terminal exit. State the UI reads synchronously ({@link getReplay},
+ * {@link windowState}, {@link viewerCount}, {@link getUrl}, {@link getLogBuffer})
+ * is cached from those frames; the daemon sends the current state immediately on
+ * connect so these populate before the first paint.
+ */
+export declare class RemoteHostSession implements HostSession {
+    private readonly socket;
+    private replay;
+    private winState;
+    private viewers;
+    private url;
+    private readonly logBuf;
+    private hostDataCb?;
+    private windowStateCb?;
+    private viewersCb?;
+    private logCb?;
+    private urlCb?;
+    private exitCb?;
+    private exited;
+    private closed;
+    private pendingExitCode;
+    constructor(socket: Socket, initial: {
+        cols: number;
+        rows: number;
+    });
+    private dispatch;
+    /** Fire the one-shot exit callback (idempotent). */
+    private fireExit;
+    /** Socket gone: fire exit (with a clean code if an `exit` frame preceded it). */
+    private handleClose;
+    /** Write a framed message, swallowing sends after the socket has closed. */
+    private send;
+    onHostData(cb: (chunk: Buffer) => void): void;
+    write(data: Uint8Array | string): void;
+    resize(cols: number, rows: number): void;
+    getReplay(): Uint8Array;
+    onWindowState(cb: (s: WindowStateBody) => void): void;
+    windowState(): WindowStateBody;
+    newWindow(): void;
+    nextWindow(): void;
+    prevWindow(): void;
+    selectWindow(i: number): void;
+    closeWindow(i: number): void;
+    onViewersChange(cb: (n: number) => void): void;
+    viewerCount(): number;
+    onLog(cb: (line: string) => void): void;
+    getLogBuffer(): readonly string[];
+    getUrl(): string | null;
+    onUrl(cb: (url: string) => void): void;
+    onExit(cb: (code: number | null, signal: string | null) => void): void;
+    /**
+     * Detach without ending the daemon session: tell the daemon to drop this
+     * client (it keeps running), end the socket, then run the local exit path so
+     * the host UI tears its terminal down (host-terminal's restore() runs on exit).
+     */
+    detach(): void;
+    /** Tear down: end the socket (no exit fired — the caller is disposing us). */
+    dispose(): void;
+}
+//# sourceMappingURL=remote-host-session.d.ts.map

package/dist/remote-host-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-host-session.d.ts","sourceRoot":"","sources":["../src/remote-host-session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAqBrD;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAGhC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAIvC,OAAO,CAAC,UAAU,CAAC,CAA0B;IAC7C,OAAO,CAAC,aAAa,CAAC,CAA+B;IACrD,OAAO,CAAC,SAAS,CAAC,CAAsB;IACxC,OAAO,CAAC,KAAK,CAAC,CAAyB;IACvC,OAAO,CAAC,KAAK,CAAC,CAAwB;IACtC,OAAO,CAAC,MAAM,CAAC,CAAuD;IAKtE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAuB;gBAElC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAgBnE,OAAO,CAAC,QAAQ;IAyChB,oDAAoD;IACpD,OAAO,CAAC,QAAQ;IAMhB,iFAAiF;IACjF,OAAO,CAAC,WAAW;IAOnB,4EAA4E;IAC5E,OAAO,CAAC,IAAI;IAWZ,UAAU,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAC7C,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAItC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IACxC,SAAS,IAAI,UAAU;IAGvB,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;IACrD,WAAW,IAAI,eAAe;IAC9B,SAAS,IAAI,IAAI;IACjB,UAAU,IAAI,IAAI;IAClB,UAAU,IAAI,IAAI;IAClB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAC7B,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAG5B,eAAe,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAC9C,WAAW,IAAI,MAAM;IAGrB,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IACvC,YAAY,IAAI,SAAS,MAAM,EAAE;IAGjC,MAAM,IAAI,MAAM,GAAG,IAAI;IACvB,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAGtC,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI;IAEtE;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAOd,8EAA8E;IAC9E,OAAO,IAAI,IAAI;CAIhB"}

package/dist/remote-host-session.js

@@ -0,0 +1,170 @@
+import { createMessageReader, decodeChunk, encodeChunk, writeMessage, } from './ipc.js';
+/** Cap on the client-side mirror of the captured-log ring buffer. */
+const DEBUG_MAX_LINES = 1000;
+/** Empty window-state used before the daemon's first window-state frame arrives. */
+const EMPTY_WINDOW_STATE = {
+    v: 1,
+    kind: 'window-state',
+    windows: [],
+    activeIndex: 0,
+};
+/**
+ * The socket-backed {@link HostSession}: the CLIENT half of the daemon/client
+ * split. It renders the SAME host UI (host-terminal.ts) that {@link LocalHostSession}
+ * does, but every read is a cached value fed by the daemon over a local unix
+ * socket and every action is a framed message written back to it.
+ *
+ * On construction it sends a `hello` (so the daemon learns the client's terminal
+ * size) and starts decoding {@link DaemonToClient} frames: live output, the
+ * post-attach replay, window-state, viewer count, captured logs, the session URL
+ * and the terminal exit. State the UI reads synchronously ({@link getReplay},
+ * {@link windowState}, {@link viewerCount}, {@link getUrl}, {@link getLogBuffer})
+ * is cached from those frames; the daemon sends the current state immediately on
+ * connect so these populate before the first paint.
+ */
+export class RemoteHostSession {
+    socket;
+    // Cached state fed by daemon frames; read synchronously by the host UI.
+    replay = new Uint8Array(0);
+    winState = EMPTY_WINDOW_STATE;
+    viewers = 0;
+    url = null;
+    logBuf = [];
+    // The host UI registers exactly one callback per event; mirror the
+    // SharedWorkspace single-callback surface it binds against.
+    hostDataCb;
+    windowStateCb;
+    viewersCb;
+    logCb;
+    urlCb;
+    exitCb;
+    // Guards: `exited` makes the onExit path fire at most once (a clean `exit`
+    // frame or an unexpected socket close, whichever comes first); `closed` stops
+    // any send after the socket is gone.
+    exited = false;
+    closed = false;
+    pendingExitCode = null;
+    constructor(socket, initial) {
+        this.socket = socket;
+        createMessageReader(socket, (msg) => this.dispatch(msg), () => this.handleClose(null));
+        socket.on('close', () => this.handleClose(this.pendingExitCode));
+        socket.on('error', () => { });
+        this.send({ t: 'hello', cols: initial.cols, rows: initial.rows });
+    }
+    // --- inbound daemon → client ---------------------------------------------
+    dispatch(msg) {
+        // Only DaemonToClient frames arrive on a client socket; the daemon never
+        // sends ClientToDaemon frames back, so narrow by the discriminants we own.
+        const m = msg;
+        switch (m.t) {
+            case 'data':
+                this.hostDataCb?.(decodeChunk(m.chunk));
+                break;
+            case 'replay':
+                // Cached for getReplay(); NOT fed to onHostData — the host UI writes the
+                // replay itself once, via getReplay(), at go-live.
+                this.replay = decodeChunk(m.chunk);
+                break;
+            case 'window-state':
+                this.winState = m.state;
+                this.windowStateCb?.(m.state);
+                break;
+            case 'viewers':
+                this.viewers = m.n;
+                this.viewersCb?.(m.n);
+                break;
+            case 'log':
+                this.logBuf.push(m.line);
+                if (this.logBuf.length > DEBUG_MAX_LINES) {
+                    this.logBuf.splice(0, this.logBuf.length - DEBUG_MAX_LINES);
+                }
+                this.logCb?.(m.line);
+                break;
+            case 'url':
+                this.url = m.url;
+                this.urlCb?.(m.url);
+                break;
+            case 'exit':
+                // Record the clean exit code so a following socket 'close' reports it,
+                // then fire the exit path now.
+                this.pendingExitCode = m.code;
+                this.fireExit(m.code, null);
+                break;
+        }
+    }
+    /** Fire the one-shot exit callback (idempotent). */
+    fireExit(code, signal) {
+        if (this.exited)
+            return;
+        this.exited = true;
+        this.exitCb?.(code, signal);
+    }
+    /** Socket gone: fire exit (with a clean code if an `exit` frame preceded it). */
+    handleClose(code) {
+        this.closed = true;
+        this.fireExit(code, null);
+    }
+    // --- outbound client → daemon --------------------------------------------
+    /** Write a framed message, swallowing sends after the socket has closed. */
+    send(msg) {
+        if (this.closed)
+            return;
+        try {
+            writeMessage(this.socket, msg);
+        }
+        catch {
+            // A write on a half-closed socket can throw; treat as closed.
+            this.closed = true;
+        }
+    }
+    // --- terminal ------------------------------------------------------------
+    onHostData(cb) { this.hostDataCb = cb; }
+    write(data) {
+        const bytes = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+        this.send({ t: 'input', data: encodeChunk(bytes) });
+    }
+    resize(cols, rows) { this.send({ t: 'resize', cols, rows }); }
+    getReplay() { return this.replay; }
+    // --- windows -------------------------------------------------------------
+    onWindowState(cb) { this.windowStateCb = cb; }
+    windowState() { return this.winState; }
+    newWindow() { this.send({ t: 'win', op: 'new' }); }
+    nextWindow() { this.send({ t: 'win', op: 'next' }); }
+    prevWindow() { this.send({ t: 'win', op: 'prev' }); }
+    selectWindow(i) { this.send({ t: 'win', op: 'select', index: i }); }
+    closeWindow(i) { this.send({ t: 'win', op: 'close', index: i }); }
+    // --- viewers -------------------------------------------------------------
+    onViewersChange(cb) { this.viewersCb = cb; }
+    viewerCount() { return this.viewers; }
+    // --- logs (debug tab) ----------------------------------------------------
+    onLog(cb) { this.logCb = cb; }
+    getLogBuffer() { return this.logBuf; }
+    // --- url -----------------------------------------------------------------
+    getUrl() { return this.url; }
+    onUrl(cb) { this.urlCb = cb; }
+    // --- lifecycle -----------------------------------------------------------
+    onExit(cb) { this.exitCb = cb; }
+    /**
+     * Detach without ending the daemon session: tell the daemon to drop this
+     * client (it keeps running), end the socket, then run the local exit path so
+     * the host UI tears its terminal down (host-terminal's restore() runs on exit).
+     */
+    detach() {
+        this.send({ t: 'detach' });
+        this.closed = true;
+        try {
+            this.socket.end();
+        }
+        catch { /* already ending */ }
+        this.fireExit(null, null);
+    }
+    /** Tear down: end the socket (no exit fired — the caller is disposing us). */
+    dispose() {
+        this.closed = true;
+        try {
+            this.socket.end();
+        }
+        catch { /* already ending */ }
+    }
+}
+//# sourceMappingURL=remote-host-session.js.map

package/dist/remote-host-session.js.map

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

package/dist/session-registry.d.ts

@@ -0,0 +1,51 @@
+/** A registered, discoverable daemon session. */
+export interface SessionInfo {
+    name: string;
+    socket: string;
+    logFile: string;
+    pid: number;
+    capId: string;
+    url: string;
+    createdAt: number;
+}
+/**
+ * Resolve the runtime directory holding sockets, logs and the registry.
+ *
+ * Precedence:
+ *   1. `ENTANGLE_RUN_DIR` — explicit override (used by tests, and handy for the
+ *      daemon to pin a location);
+ *   2. `$XDG_RUNTIME_DIR/entangle` — the standard per-user runtime dir;
+ *   3. `~/.entangle/run` — fallback when XDG is unset.
+ */
+export declare function resolveRunDir(): string;
+/** Ensure the runtime directory exists with 0700 perms, returning its path. */
+export declare function ensureRunDir(): string;
+/** Reduce an arbitrary name to a filesystem-safe token ([A-Za-z0-9._-]). */
+export declare function sanitizeName(name: string): string;
+/** Absolute path of the unix socket for a session. */
+export declare function socketPath(name: string): string;
+/** Absolute path of the log file for a session. */
+export declare function logPath(name: string): string;
+/**
+ * Stable short session name derived from a capability id, so an unnamed session
+ * is keyed on its capability. Deterministic: the same capId always yields the
+ * same name. Uses the sanitized leading characters of the capId (capIds are
+ * already url-safe base-ish tokens) to stay human-recognizable.
+ */
+export declare function defaultSessionName(capId: string): string;
+/** Read the registry. A missing or corrupt file is treated as empty. */
+export declare function listSessions(): SessionInfo[];
+/** Add (or replace by name) a session in the registry. */
+export declare function addSession(info: SessionInfo): void;
+/** Remove a session from the registry by name. No-op if absent. */
+export declare function removeSession(name: string): void;
+/** Find a registered session by name. */
+export declare function findSession(name: string): SessionInfo | undefined;
+/** True if the pid is alive AND the session's socket file still exists. */
+export declare function isAlive(info: SessionInfo): boolean;
+/**
+ * Prune dead state: drop registry entries whose pid is gone, and unlink any
+ * `.sock` file in the run dir that no live registered session owns.
+ */
+export declare function cleanupStale(): void;
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/session-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.d.ts","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"AAeA,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,mDAAmD;AACnD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxD;AAsBD,wEAAwE;AACxE,wBAAgB,YAAY,IAAI,WAAW,EAAE,CAc5C;AAaD,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAIlD;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhD;AAED,yCAAyC;AACzC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEjE;AAID,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAElD;AAcD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAoBnC"}

package/dist/session-registry.js

@@ -0,0 +1,167 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const REGISTRY_FILE = 'sessions.json';
+/**
+ * Resolve the runtime directory holding sockets, logs and the registry.
+ *
+ * Precedence:
+ *   1. `ENTANGLE_RUN_DIR` — explicit override (used by tests, and handy for the
+ *      daemon to pin a location);
+ *   2. `$XDG_RUNTIME_DIR/entangle` — the standard per-user runtime dir;
+ *   3. `~/.entangle/run` — fallback when XDG is unset.
+ */
+export function resolveRunDir() {
+    const override = process.env.ENTANGLE_RUN_DIR;
+    if (override)
+        return override;
+    const xdg = process.env.XDG_RUNTIME_DIR;
+    if (xdg)
+        return path.join(xdg, 'entangle');
+    return path.join(os.homedir(), '.entangle', 'run');
+}
+/** Ensure the runtime directory exists with 0700 perms, returning its path. */
+export function ensureRunDir() {
+    const dir = resolveRunDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+/** Reduce an arbitrary name to a filesystem-safe token ([A-Za-z0-9._-]). */
+export function sanitizeName(name) {
+    const safe = name.replace(/[^A-Za-z0-9._-]/g, '-');
+    // Avoid an empty basename or a name that resolves to a directory entry.
+    return safe.length > 0 && safe !== '.' && safe !== '..' ? safe : 'session';
+}
+/** Absolute path of the unix socket for a session. */
+export function socketPath(name) {
+    return path.join(resolveRunDir(), `${sanitizeName(name)}.sock`);
+}
+/** Absolute path of the log file for a session. */
+export function logPath(name) {
+    return path.join(resolveRunDir(), `${sanitizeName(name)}.log`);
+}
+/**
+ * Stable short session name derived from a capability id, so an unnamed session
+ * is keyed on its capability. Deterministic: the same capId always yields the
+ * same name. Uses the sanitized leading characters of the capId (capIds are
+ * already url-safe base-ish tokens) to stay human-recognizable.
+ */
+export function defaultSessionName(capId) {
+    const token = sanitizeName(capId).replace(/[._-]/g, '').slice(0, 10) || 'anon';
+    return `cap-${token}`;
+}
+// --- registry file I/O (best-effort, tolerant of missing/corrupt data) -----
+function registryPath() {
+    return path.join(resolveRunDir(), REGISTRY_FILE);
+}
+function isSessionInfo(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === 'string' &&
+        typeof v.socket === 'string' &&
+        typeof v.logFile === 'string' &&
+        typeof v.pid === 'number' &&
+        typeof v.capId === 'string' &&
+        typeof v.url === 'string' &&
+        typeof v.createdAt === 'number');
+}
+/** Read the registry. A missing or corrupt file is treated as empty. */
+export function listSessions() {
+    let raw;
+    try {
+        raw = fs.readFileSync(registryPath(), 'utf8');
+    }
+    catch {
+        return []; // missing file (or unreadable) → no sessions
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(isSessionInfo);
+    }
+    catch {
+        return []; // corrupt JSON → treat as empty
+    }
+}
+function writeSessions(sessions) {
+    ensureRunDir();
+    const tmp = `${registryPath()}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(sessions, null, 2), { mode: 0o600 });
+        fs.renameSync(tmp, registryPath()); // atomic replace
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* nothing to clean up */ }
+    }
+}
+/** Add (or replace by name) a session in the registry. */
+export function addSession(info) {
+    const sessions = listSessions().filter((s) => s.name !== info.name);
+    sessions.push(info);
+    writeSessions(sessions);
+}
+/** Remove a session from the registry by name. No-op if absent. */
+export function removeSession(name) {
+    const sessions = listSessions();
+    const next = sessions.filter((s) => s.name !== name);
+    if (next.length !== sessions.length)
+        writeSessions(next);
+}
+/** Find a registered session by name. */
+export function findSession(name) {
+    return listSessions().find((s) => s.name === name);
+}
+// --- liveness --------------------------------------------------------------
+/** True if the pid is alive AND the session's socket file still exists. */
+export function isAlive(info) {
+    return pidAlive(info.pid) && fs.existsSync(info.socket);
+}
+/** True if a process with `pid` exists and is signalable by us. */
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but we may not signal it → still alive.
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Prune dead state: drop registry entries whose pid is gone, and unlink any
+ * `.sock` file in the run dir that no live registered session owns.
+ */
+export function cleanupStale() {
+    const dir = resolveRunDir();
+    const sessions = listSessions();
+    const live = sessions.filter((s) => pidAlive(s.pid));
+    if (live.length !== sessions.length)
+        writeSessions(live);
+    const liveSockets = new Set(live.map((s) => s.socket));
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return; // dir gone → nothing to unlink
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.sock'))
+            continue;
+        const full = path.join(dir, entry);
+        if (liveSockets.has(full))
+            continue; // owned by a live session
+        try {
+            fs.unlinkSync(full);
+        }
+        catch { /* raced / already gone */ }
+    }
+}
+//# sourceMappingURL=session-registry.js.map

package/dist/session-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-registry.js","sourceRoot":"","sources":["../src/session-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAwB7B,MAAM,aAAa,GAAG,eAAe,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC9C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACxC,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACnD,wEAAwE;IACxE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClE,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC;IAC/E,OAAO,OAAO,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,8EAA8E;AAE9E,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,aAAa,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ;QACzB,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAC3B,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ;QACzB,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAChC,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY;IAC1B,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,6CAA6C;IAC1D,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QACtC,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,gCAAgC;IAC7C,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,QAAuB;IAC5C,YAAY,EAAE,CAAC;IACf,MAAM,GAAG,GAAG,GAAG,YAAY,EAAE,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IACnD,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,iBAAiB;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;IACpE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,aAAa,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,aAAa,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,8EAA8E;AAE9E,2EAA2E;AAC3E,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,mEAAmE;AACnE,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,yEAAyE;QACzE,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAEzD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEvD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,+BAA+B;IACzC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,0BAA0B;QAC/D,IAAI,CAAC;YAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,0BAA0B,CAAC,CAAC;IACnE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenewlabs/entangle-serve",
-  "version": "2.6.2",
+  "version": "2.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
@@ -17,9 +17,9 @@
   },
   "dependencies": {
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
-    "@thenewlabs/entangle-crypto": "^2.6.2",
-    "@thenewlabs/entangle-protocol": "^2.6.2",
-    "@thenewlabs/entangle-utils": "^2.6.2",
+    "@thenewlabs/entangle-crypto": "^2.7.0",
+    "@thenewlabs/entangle-protocol": "^2.7.0",
+    "@thenewlabs/entangle-utils": "^2.7.0",
     "cborg": "^4.5.8",
     "commander": "^15.0.0",
     "ws": "^8.21.0"