baychat 0.9.1 → 0.11.0

package/dist/relay/transport.js

@@ -0,0 +1,364 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeenDeliveries = void 0;
+exports.runRelayFeed = runRelayFeed;
+/**
+ * The relay's event SOURCE, and the only place that chooses between the two.
+ *
+ * Everything downstream — routing on `sessionName`, the per-session mutex, the
+ * adapters, the pending-vs-delivered distinction — is untouched by this file.
+ * It hands `onEvents` exactly what `runUpdatesLoop` used to hand it, from
+ * whichever transport is currently live.
+ *
+ * The policy, in one place because it is one decision:
+ *
+ *   • Prefer the socket. It is the same events with none of the poll latency.
+ *   • The long-poll is the FLOOR, not a mode. Any socket that will not connect,
+ *     is refused, or drops sends us straight back to it with the cursor we were
+ *     holding — no config, no flag, nothing for a user to know about. An older
+ *     server with no `/ws` route simply never gets past `connect-failed`, and
+ *     the relay behaves exactly as it did before this file existed.
+ *   • The two never run at once. The bus allows one waiter per agent and tells a
+ *     displaced incumbent to retry, so a socket and a poll racing for the same
+ *     session would take turns and add latency to both.
+ *
+ * The socket is retried on a ladder, and the long-poll covers every gap in it,
+ * so "degraded" here means "slower", never "deaf".
+ */
+const api_1 = require("../api");
+const updates_1 = require("./updates");
+const ws_1 = require("./ws");
+/**
+ * How long a socket must survive before we call the attempt healthy and reset
+ * the ladder. Shorter than this and a server that accepts a handshake then
+ * drops it would be retried forever at the fastest rung.
+ */
+const HEALTHY_AFTER_MS = 60_000;
+/**
+ * Delay before the next socket attempt, by consecutive failure count. The last
+ * rung repeats. A server with no `/ws` route settles on it and costs one
+ * refused handshake every ten minutes — cheap enough to keep trying, because
+ * the alternative is a relay that stays on the long-poll until it is restarted.
+ */
+const WS_RETRY_LADDER_MS = [3_000, 15_000, 60_000, 300_000, 600_000];
+/** How often the live-session list is re-read while the socket is up. See `refreshSessions`. */
+const SESSION_REFRESH_MS = 60_000;
+/** Deliveries (session + message id) remembered for de-duplication across a transport switch. */
+const SEEN_DELIVERIES_LIMIT = 2_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Feed relay events from the best available transport until `signal` aborts.
+ *
+ * Throws only for the reasons `runUpdatesLoop` already threw: a terminal 4xx on
+ * the long-poll (an expired device credential needs a human). A socket failure
+ * is never terminal on its own — see `wsEnded`.
+ */
+async function runRelayFeed(opts) {
+    const { auth, watermarks, onEvents, onSessions, onPoll, onError, onTransport, signal, request = api_1.apiRequest, connect = ws_1.nodeWebSocketConnect, retryLadderMs = WS_RETRY_LADDER_MS, healthyAfterMs = HEALTHY_AFTER_MS, sessionRefreshMs = SESSION_REFRESH_MS, } = opts;
+    const seen = new SeenDeliveries(SEEN_DELIVERIES_LIMIT);
+    /** The shared position. Handed to whichever transport starts next. */
+    let cursor;
+    /** Consecutive socket attempts that did not stay healthy. Indexes the ladder. */
+    let failures = 0;
+    /** Epoch ms before which the socket is not worth trying. */
+    let retryAfter = 0;
+    /** Set once a runtime has told us it has no WebSocket; it will not grow one. */
+    let socketsPossible = connect !== null;
+    let announced = null;
+    const announce = (kind, detail) => {
+        const key = `${kind}:${detail}`;
+        if (announced === key)
+            return;
+        announced = key;
+        onTransport?.(kind, detail);
+    };
+    /**
+     * The single funnel every event passes through, from either transport.
+     *
+     * De-duplication lives HERE rather than in the queue because a transport
+     * switch is exactly when the same event arrives twice: the socket hands over
+     * a batch, dies before the `cursor` frame that would have closed it, and the
+     * long-poll resumes from the last cursor — which is the position BEFORE that
+     * batch, so the whole batch comes back. That replay is the design (it is why
+     * event frames carry no cursor), and this set is what makes it free.
+     *
+     * The queue's own buffer de-dupe is unchanged and still needed: it covers
+     * duplicates inside one undelivered batch. This covers duplicates that span a
+     * delivery, which the buffer cannot see because it has already been drained.
+     *
+     * A duplicate is the same message TO THE SAME SESSION. One message into a room
+     * two of this machine's sessions are in arrives as two events sharing a
+     * `message.id`, one per session, and both of those are deliveries this relay
+     * owes a terminal — see `SeenDeliveries`.
+     */
+    const emit = (events) => {
+        const fresh = events.filter((e) => seen.add(e.sessionName, e.message.id));
+        if (fresh.length > 0)
+            onEvents(fresh);
+    };
+    const recordCursor = (next) => {
+        cursor = next;
+        onPoll?.(next);
+    };
+    while (!signal.aborted) {
+        if (socketsPossible && connect && Date.now() >= retryAfter) {
+            const startedAt = Date.now();
+            const end = await runSocket({
+                auth,
+                watermarks,
+                request,
+                connect,
+                cursor,
+                emit,
+                onSessions,
+                onError,
+                // Only claim the socket once the server has answered `ready`. Announcing
+                // at connect time would report "transport: websocket" to a human staring
+                // at a relay that is in fact failing every handshake.
+                onReady: () => announce("websocket", "connected"),
+                recordCursor,
+                clearCursor: () => {
+                    cursor = undefined;
+                },
+                sessionRefreshMs,
+                signal,
+            });
+            if (signal.aborted)
+                return;
+            if (end.reason === "unavailable") {
+                // Node 20 has no WebSocket and never will at runtime. Stop asking.
+                socketsPossible = false;
+                onError?.(new Error(`websocket transport unavailable: ${end.detail}`), true);
+            }
+            else {
+                const healthy = end.reason === "closed" && Date.now() - startedAt >= healthyAfterMs;
+                failures = healthy ? 0 : failures + 1;
+                retryAfter = Date.now() + ladderDelay(retryLadderMs, failures);
+                wsEnded(end, onError);
+            }
+        }
+        if (signal.aborted)
+            return;
+        // The socket is due right now — a healthy connection that just dropped. Go
+        // straight back rather than paying for a long-poll round trip we would
+        // abandon at its first boundary anyway.
+        if (socketsPossible && connect && Date.now() >= retryAfter)
+            continue;
+        // The long-poll stint. It runs until the socket is worth retrying, and its
+        // own signal is the ONLY thing that ends it — a terminal 401 still throws
+        // straight out of here, exactly as it did before.
+        const detail = socketsPossible
+            ? `fallback — retrying the socket in ${Math.max(0, Math.round((retryAfter - Date.now()) / 1000))}s`
+            : "fallback — no WebSocket in this runtime";
+        announce("long-poll", detail);
+        const stint = new AbortController();
+        const stopStint = () => stint.abort();
+        signal.addEventListener("abort", stopStint, { once: true });
+        try {
+            await (0, updates_1.runUpdatesLoop)({
+                auth,
+                watermarks,
+                initialCursor: cursor,
+                onEvents: emit,
+                onSessions,
+                onPoll: (next) => {
+                    recordCursor(next);
+                    // End the stint at a poll BOUNDARY, never mid-request: the position
+                    // has just advanced and nothing is in flight, so the handover to the
+                    // socket cannot straddle a batch. It costs at most one poll's wait
+                    // before the socket is retried, and loses nothing.
+                    if (socketsPossible && connect && Date.now() >= retryAfter)
+                        stint.abort();
+                },
+                onError,
+                signal: stint.signal,
+                request,
+            });
+        }
+        finally {
+            signal.removeEventListener("abort", stopStint);
+        }
+        // A stint that ended without the parent aborting and without a socket to go
+        // back to would spin. It cannot happen (the only aborts are the parent's
+        // and the retry boundary), but a hot loop here would be invisible and
+        // expensive, so make it impossible rather than unlikely.
+        if (!signal.aborted && !(socketsPossible && connect))
+            await sleep(1_000);
+    }
+}
+/** Fold one socket's end into an `onError` line. Never terminal — see the comment. */
+function wsEnded(end, onError) {
+    if (end.reason === "aborted")
+        return;
+    if (end.reason === "credential") {
+        // A 4001 is NOT treated as terminal here. The gateway raises it for a
+        // revoked credential AND for any error thrown while re-verifying one (a
+        // database blip re-verifying a device token lands in the same branch), and
+        // a WebSocket close carries no HTTP status to tell those apart. The
+        // long-poll we drop back to answers the question properly: a real 401 is
+        // terminal there and always has been, and a blip just keeps polling.
+        onError?.(new Error(`websocket credential check failed (${end.detail}) — verifying over the long-poll`), true);
+        return;
+    }
+    onError?.(new Error(`websocket ${end.reason}: ${end.detail}`), true);
+}
+function ladderDelay(ladder, failures) {
+    // A socket that was healthy and then dropped (a redeploy, a NAT reset) goes
+    // straight back — the ladder is for things that are actually broken.
+    if (failures === 0)
+        return 0;
+    // A floor for a caller that passed an empty ladder: zero here plus a socket
+    // that fails instantly is a hot reconnect loop, which is the one failure mode
+    // this whole file exists to avoid.
+    if (ladder.length === 0)
+        return 1_000;
+    return ladder[Math.min(failures, ladder.length) - 1] ?? ladder[ladder.length - 1];
+}
+/** One socket, plus the live-session refresh that rides alongside it. */
+async function runSocket(args) {
+    const { auth, watermarks, request, connect, cursor, emit, onSessions, onError } = args;
+    const done = new AbortController();
+    const stop = () => done.abort();
+    args.signal.addEventListener("abort", stop, { once: true });
+    /** Serialises `reset` recoveries: two overlapping catch-ups would double-read every room. */
+    let recovering = Promise.resolve();
+    const refresher = refreshSessions({
+        auth,
+        request,
+        onSessions,
+        onError,
+        everyMs: args.sessionRefreshMs,
+        signal: done.signal,
+    });
+    try {
+        return await (0, ws_1.runWebSocketFeed)({
+            auth,
+            resume: cursor,
+            onEvents: emit,
+            onSessions,
+            onCursor: args.recordCursor,
+            onReady: () => args.onReady(),
+            onReset: () => {
+                // `{"t":"reset"}` is `409 cursor_expired` in frame form, and the
+                // recovery is the same one: re-read every watched conversation from our
+                // own watermark. The server does not bridge the gap and keeps streaming
+                // through it, so events arriving during the catch-up are delivered too
+                // and de-duplicated by id.
+                args.clearCursor();
+                recovering = recovering
+                    .then(() => (0, updates_1.catchUpFromWatermarks)(auth, watermarks, request))
+                    .then((recovered) => {
+                    if (recovered.length > 0)
+                        emit(recovered);
+                })
+                    .catch((err) => {
+                    // The cursor is already cleared — the socket re-baselined at "now"
+                    // server-side whatever we do — so this is a reported gap, not a
+                    // silent one.
+                    onError?.(err, true);
+                });
+            },
+            signal: done.signal,
+            connect,
+        });
+    }
+    finally {
+        args.signal.removeEventListener("abort", stop);
+        done.abort();
+        await refresher;
+        await recovering;
+    }
+}
+/**
+ * Re-read the live session list on a timer while the socket is up.
+ *
+ * The socket reports sessions on `cursor` frames — but the server sends no
+ * cursor frame at all when a device owns NO live session (there is no bus to
+ * park on, so the loop just sleeps). Without this, a relay whose last session
+ * was ended from the app would keep that target in its registry until the
+ * socket next dropped. The long-poll has no such gap: every response carries
+ * `sessions`, including an empty one.
+ *
+ * Best-effort by construction: an older server has no `/sessions` route, and
+ * one failure stops the refresher for this connection rather than retrying into
+ * a 404 forever. Pruning then falls back to the long-poll, which is where it
+ * lived before.
+ */
+async function refreshSessions(args) {
+    const { auth, request, onSessions, onError, everyMs, signal } = args;
+    if (!onSessions || everyMs <= 0)
+        return;
+    while (!signal.aborted) {
+        await interruptibleSleep(everyMs, signal);
+        if (signal.aborted)
+            return;
+        try {
+            const res = await request(auth, "GET", "/api/device-api/sessions");
+            if (signal.aborted)
+                return;
+            onSessions((res.sessions ?? []).filter((s) => s.live).map((s) => s.name));
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            onError?.(new Error(`live-session refresh unavailable (${err instanceof Error ? err.message : String(err)}) — pruning waits for the long-poll`), true);
+            return;
+        }
+    }
+}
+function interruptibleSleep(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(finish, ms);
+        timer.unref?.();
+        function finish() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        }
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
+/**
+ * Deliveries already handed downstream, newest-last, bounded.
+ *
+ * Keyed by SESSION and message id, because that pair is the delivery — not the
+ * message. Two sessions on this machine in the same room each get their own copy
+ * of one message, with one `message.id` between them; a set keyed on the id alone
+ * wakes whichever arrived first and drops the other session's copy on the floor,
+ * after the server's cursor has already moved past it. That is a lost message,
+ * not a de-duplicated one.
+ *
+ * Bounded rather than complete on purpose: the relay is a long-lived daemon and
+ * an unbounded set is a slow leak. The window only has to outlive a transport
+ * switch — one batch, plus whatever a catch-up re-reads — and 2000 entries is
+ * several orders of magnitude more than that.
+ */
+class SeenDeliveries {
+    limit;
+    keys = new Set();
+    order = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** True when this delivery had not been seen — i.e. the caller should deliver it. */
+    add(sessionName, messageId) {
+        // NUL separates: a session name is user-chosen and may contain anything else.
+        const key = `${sessionName ?? ""}\u0000${messageId}`;
+        if (this.keys.has(key))
+            return false;
+        this.keys.add(key);
+        this.order.push(key);
+        while (this.order.length > this.limit) {
+            const evicted = this.order.shift();
+            if (evicted !== undefined)
+                this.keys.delete(evicted);
+        }
+        return true;
+    }
+    get size() {
+        return this.keys.size;
+    }
+}
+exports.SeenDeliveries = SeenDeliveries;

package/dist/relay/updates.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runUpdatesLoop = runUpdatesLoop;
+exports.catchUpFromWatermarks = catchUpFromWatermarks;
 const api_1 = require("../api");
 /** Server clamps `wait` into [1s, 30s]; 25s stays under the usual 60s proxy idle timeout. */
 const WAIT_SECONDS = 25;
@@ -42,8 +43,8 @@ function isTransient(err) {
  * watermark, then poll again with no cursor.
  */
 async function runUpdatesLoop(opts) {
-    const { auth, watermarks, onEvents, onSessions, onPoll, onError, signal, request = api_1.apiRequest } = opts;
-    let cursor;
+    const { auth, watermarks, onEvents, onSessions, onPoll, onError, initialCursor, signal, request = api_1.apiRequest } = opts;
+    let cursor = initialCursor;
     let backoff = BACKOFF_MIN_MS;
     while (!signal.aborted) {
         try {
@@ -69,7 +70,7 @@ async function runUpdatesLoop(opts) {
             if (err instanceof api_1.ApiError && err.status === 409) {
                 onError?.(err, true);
                 try {
-                    const recovered = await catchUp(auth, watermarks, request);
+                    const recovered = await catchUpFromWatermarks(auth, watermarks, request);
                     if (recovered.length > 0)
                         onEvents(recovered);
                 }
@@ -96,16 +97,17 @@ async function runUpdatesLoop(opts) {
     }
 }
 /**
- * Re-read each watched conversation from its watermark. Used only on 409
- * recovery. Messages we already delivered come back here; the caller's
- * per-session queue de-dupes them by id, so a replay is cheap rather than
- * duplicated into the room.
+ * Re-read each watched conversation from its watermark. Used on 409 recovery
+ * and on the WebSocket's `{"t":"reset"}`, which is the same condition in frame
+ * form — one recovery, so the two transports cannot drift apart. Messages we
+ * already delivered come back here; the caller de-dupes them by id, so a replay
+ * is cheap rather than duplicated into the room.
  *
  * A 404 for one conversation is skipped rather than fatal: a session may have
  * ended or left the room between the poll and the recovery, and one dead room
  * must not strand the catch-up for every other.
  */
-async function catchUp(auth, watermarks, request) {
+async function catchUpFromWatermarks(auth, watermarks, request) {
     const events = [];
     for (const [conversationId, since] of watermarks) {
         let res;

package/dist/relay/ws.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeWebSocketConnect = exports.WebSocketUnavailableError = exports.AGENT_WS_PATH = void 0;
+exports.runWebSocketFeed = runWebSocketFeed;
+exports.wsUrlFor = wsUrlFor;
+exports.parseFrame = parseFrame;
+/** The published endpoint. Changing it breaks every deployed server — a wire constant. */
+exports.AGENT_WS_PATH = "/api/agent-api/ws";
+/** How long we wait for the server's `ready` after sending `hello`. */
+const READY_TIMEOUT_MS = 10_000;
+/** Close code the gateway uses when the credential stopped verifying. */
+const WS_CLOSE_CREDENTIAL = 4001;
+/** Thrown by `nodeWebSocketConnect` on a runtime with no global `WebSocket`. */
+class WebSocketUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebSocketUnavailableError";
+    }
+}
+exports.WebSocketUnavailableError = WebSocketUnavailableError;
+/**
+ * Run one socket until it ends. Never throws: every failure mode is a `WsFeedEnd`,
+ * because a transport that can be fallen back from must not surface as an
+ * exception the daemon would treat as fatal.
+ */
+function runWebSocketFeed(opts) {
+    const { auth, resume, onEvents, onSessions, onCursor, onReset, onReady, signal, connect = exports.nodeWebSocketConnect, readyTimeoutMs = READY_TIMEOUT_MS, } = opts;
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve({ reason: "aborted" });
+        let settled = false;
+        let ready = false;
+        /** An `{"t":"error"}` frame arrives just before the close that explains it. */
+        let serverError;
+        let socket;
+        let readyTimer;
+        const finish = (end) => {
+            if (settled)
+                return;
+            settled = true;
+            if (readyTimer)
+                clearTimeout(readyTimer);
+            signal.removeEventListener("abort", onAbort);
+            resolve(end);
+        };
+        function onAbort() {
+            try {
+                socket?.close(1000, "relay stopping");
+            }
+            catch {
+                // Already gone. The promise still has to settle, which the next line does.
+            }
+            finish({ reason: "aborted" });
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+        const handlers = {
+            onOpen() {
+                // `hello` must be the first frame; the server reaps a socket that stays
+                // silent for 10s. `resume` is omitted rather than sent as null when we
+                // hold no position — absent means "start at now", which is what a
+                // cursorless client actually wants.
+                try {
+                    socket?.send(JSON.stringify(resume ? { t: "hello", resume } : { t: "hello" }));
+                }
+                catch (err) {
+                    finish({ reason: "connect-failed", detail: errText(err) });
+                }
+            },
+            onMessage(data) {
+                const frame = parseFrame(data);
+                if (!frame)
+                    return; // unknown or unparseable frames are ignored by contract
+                if (frame.t === "ready") {
+                    ready = true;
+                    if (readyTimer)
+                        clearTimeout(readyTimer);
+                    readyTimer = undefined;
+                    if (frame.sessions)
+                        onSessions?.(frame.sessions);
+                    if (frame.cursor)
+                        onCursor?.(frame.cursor);
+                    onReady?.(frame.cursor ?? null);
+                    return;
+                }
+                if (frame.t === "cursor") {
+                    // The batch above this frame is now ours. Sessions ride along, which
+                    // is how a session that joined or ended mid-connection is noticed.
+                    if (frame.sessions)
+                        onSessions?.(frame.sessions);
+                    if (frame.cursor)
+                        onCursor?.(frame.cursor);
+                    return;
+                }
+                if (frame.t === "event") {
+                    // Handed over immediately rather than buffered until the closing
+                    // cursor frame: the position does not advance here, so a socket that
+                    // dies now replays this event and the caller de-dupes it by id.
+                    if (frame.event)
+                        onEvents([frame.event]);
+                    return;
+                }
+                if (frame.t === "reset") {
+                    onReset?.();
+                    return;
+                }
+                serverError = { code: frame.code, message: frame.message };
+            },
+            onError(detail) {
+                // A WebSocket error event carries no HTTP status — a 401, a 404 from a
+                // server with no `/ws` route and a dead network are indistinguishable
+                // here. That is why classification stops at "could not connect" and the
+                // long-poll is left to be the authority on a bad credential.
+                if (!ready)
+                    finish({ reason: "connect-failed", detail: detail || "socket error" });
+            },
+            onClose(code, reason) {
+                const detail = serverError ? `${serverError.code}: ${serverError.message}` : reason || `code ${code}`;
+                if (code === WS_CLOSE_CREDENTIAL || serverError?.code === "WS_CREDENTIAL_REVOKED" || serverError?.code === "WS_TOKEN_EXPIRED") {
+                    finish({ reason: "credential", detail });
+                    return;
+                }
+                if (!ready) {
+                    finish({ reason: "connect-failed", detail });
+                    return;
+                }
+                finish({ reason: "closed", code, detail });
+            },
+        };
+        try {
+            socket = connect(wsUrlFor(auth), handlers);
+        }
+        catch (err) {
+            const unavailable = err instanceof WebSocketUnavailableError;
+            finish({ reason: unavailable ? "unavailable" : "connect-failed", detail: errText(err) });
+            return;
+        }
+        readyTimer = setTimeout(() => {
+            try {
+                socket?.close(1000, "no ready frame");
+            }
+            catch {
+                // Nothing to do; `finish` below is what actually unblocks the caller.
+            }
+            finish({ reason: "connect-failed", detail: `no ready frame within ${readyTimeoutMs}ms` });
+        }, readyTimeoutMs);
+        readyTimer.unref?.();
+    });
+}
+/**
+ * The socket URL for a stored REST base URL: `http` → `ws`, `https` → `wss`,
+ * host, port and any path prefix preserved.
+ *
+ * The credential rides in the query string because the WHATWG WebSocket API
+ * cannot set an `Authorization` header — the server accepts `?token=` for
+ * exactly that reason (`handshakeToken` in `agent-ws/auth.ts`). It is a real
+ * trade-off: a URL is likelier to be logged by a proxy than a header, and it is
+ * why the CLI only ever speaks `wss` in production.
+ */
+function wsUrlFor(auth) {
+    const url = new URL(exports.AGENT_WS_PATH.replace(/^\//, ""), ensureTrailingSlash(auth.baseUrl));
+    url.protocol = url.protocol === "https:" ? "wss:" : url.protocol === "http:" ? "ws:" : url.protocol;
+    url.searchParams.set("token", auth.token);
+    return url.toString();
+}
+function ensureTrailingSlash(base) {
+    return base.endsWith("/") ? base : `${base}/`;
+}
+/**
+ * The default connect: Node's built-in WebSocket, adapted to `WsHandlers`.
+ *
+ * Reached through a cast rather than `@types/node`'s own declaration on
+ * purpose — the global has moved between type releases (Node 20 has none, 21
+ * has it behind a flag, 22 ships it), and a package published for `node >= 20`
+ * must compile the same on all three and decide at RUNTIME whether it exists.
+ */
+const nodeWebSocketConnect = (url, handlers) => {
+    const ctor = globalThis.WebSocket;
+    if (typeof ctor !== "function") {
+        throw new WebSocketUnavailableError("this Node build has no WebSocket (added in Node 22) — staying on the long-poll");
+    }
+    const ws = new ctor(url);
+    ws.onopen = () => handlers.onOpen();
+    ws.onmessage = (ev) => handlers.onMessage(typeof ev?.data === "string" ? ev.data : String(ev?.data ?? ""));
+    ws.onerror = (ev) => handlers.onError(eventText(ev));
+    ws.onclose = (ev) => handlers.onClose(typeof ev?.code === "number" ? ev.code : 1006, ev?.reason ?? "");
+    return {
+        send: (data) => ws.send(data),
+        close: (code, reason) => ws.close(code, reason),
+    };
+};
+exports.nodeWebSocketConnect = nodeWebSocketConnect;
+/**
+ * Read one server frame. Anything we do not recognise returns null and is
+ * dropped: the contract says unknown `t` values must be ignored, so a server
+ * that grows a frame type does not break an older relay.
+ */
+function parseFrame(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const frame = value;
+    switch (frame.t) {
+        case "ready":
+            return { t: "ready", cursor: str(frame.cursor), sessions: names(frame.sessions) };
+        case "cursor":
+            return { t: "cursor", cursor: str(frame.cursor), sessions: names(frame.sessions) };
+        case "event":
+            return { t: "event", event: toUpdateEvent(frame.event) };
+        case "reset":
+            return { t: "reset" };
+        case "error":
+            return { t: "error", code: str(frame.code) ?? "WS_ERROR", message: str(frame.message) ?? "socket error" };
+        default:
+            return null;
+    }
+}
+/**
+ * The device/user event payload: `{ sessionName, agentId, conversationId, message }`
+ * — byte-identical to an entry in the long-poll's `events` array, which is what
+ * makes the two transports interchangeable for everything downstream.
+ *
+ * A frame missing `conversationId` or `message.id` is dropped rather than
+ * forwarded half-formed: routing and de-duplication both key on those, and an
+ * event that cannot be routed or de-duplicated is worse than one not delivered.
+ */
+function toUpdateEvent(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const raw = value;
+    const message = raw.message;
+    if (!message || typeof message !== "object")
+        return null;
+    const msg = message;
+    const conversationId = str(raw.conversationId) ?? str(msg.conversationId);
+    const id = str(msg.id);
+    if (!conversationId || !id)
+        return null;
+    return {
+        conversationId,
+        sessionName: str(raw.sessionName),
+        message: { ...msg, id, conversationId },
+    };
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function names(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((v) => typeof v === "string");
+}
+function eventText(ev) {
+    if (!ev)
+        return "socket error";
+    if (typeof ev.message === "string" && ev.message)
+        return ev.message;
+    return errText(ev.error);
+}
+function errText(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string" && err)
+        return err;
+    return "socket error";
+}