@lensmcp/bridge 1.18.4 → 1.18.7

package/index.js

@@ -1,5 +1 @@
-export { createBridgeServer, makePublisher, handleClientEnvelope, findFreePort, } from './lib/server.js';
-export { envelopeToEvent } from './lib/event-mappers.js';
-export { redactUrl, redactText, redactDeep, isSecretParam, clip, safeText, safeTitle, REDACTED, MAX_TITLE_CHARS, MAX_MESSAGE_CHARS, MAX_URL_CHARS, } from './lib/redact.js';
-export { resolveEnvSink, resetEnvSinkCache, udsEnvSink } from './lib/env-sink.js';
-export { DEFAULT_WS_HOST, DEFAULT_WS_PORT, ENV_WS_HOST, ENV_WS_PORT, ENV_SESSION_ID, } from './lib/constants.js';
+"use strict";export{createBridgeServer,makePublisher,handleClientEnvelope,findFreePort}from"./lib/server.js";export{envelopeToEvent}from"./lib/event-mappers.js";export{redactUrl,redactText,redactDeep,isSecretParam,clip,safeText,safeTitle,REDACTED,MAX_TITLE_CHARS,MAX_MESSAGE_CHARS,MAX_URL_CHARS}from"./lib/redact.js";export{resolveEnvSink,resetEnvSinkCache,udsEnvSink}from"./lib/env-sink.js";export{DEFAULT_WS_HOST,DEFAULT_WS_PORT,ENV_WS_HOST,ENV_WS_PORT,ENV_SESSION_ID}from"./lib/constants.js";

package/lib/constants.js

@@ -1,24 +1 @@
-/**
- * Shared transport constants for the LensMCP browser-event bridge.
- *
- * The bridge is the single WebSocket endpoint that the injected
- * `@lensmcp/client-runtime` posts envelopes to. For the Vite plugin this
- * endpoint is born inside the dev server on an ephemeral port; for every
- * other host (webpack, Next.js, no-build) it runs as a standalone sidecar
- * on a FIXED, env-overridable port — so the browser runtime can find it
- * without a build step baking the URL in.
- *
- * `DEFAULT_WS_PORT` must agree between the standalone bridge runner
- * (`@lensmcp/bridge`) and the no-build client entry
- * (`@lensmcp/client-runtime/auto`), which lives in a separate
- * browser-targeted package and re-declares the same literal.
- */
-export const DEFAULT_WS_HOST = '127.0.0.1';
-/** Default fixed port for the standalone bridge sidecar. Override via `LENSMCP_WS_PORT`. */
-export const DEFAULT_WS_PORT = 5747;
-/** Env var: bind host for the standalone bridge. */
-export const ENV_WS_HOST = 'LENSMCP_WS_HOST';
-/** Env var: bind port for the standalone bridge (`0` selects an ephemeral port). */
-export const ENV_WS_PORT = 'LENSMCP_WS_PORT';
-/** Env var: session id stamped onto every event the bridge publishes. */
-export const ENV_SESSION_ID = 'LENSMCP_SESSION_ID';
+"use strict";export const DEFAULT_WS_HOST="127.0.0.1",DEFAULT_WS_PORT=5747,ENV_WS_HOST="LENSMCP_WS_HOST",ENV_WS_PORT="LENSMCP_WS_PORT",ENV_SESSION_ID="LENSMCP_SESSION_ID";

package/lib/env-sink.js

@@ -1,203 +1,3 @@
-import { connect } from 'node:net';
-import { createSocket } from 'node:dgram';
-import { appendFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
-// ---- file-sink hygiene — mirrors @lensmcp/node-instrumentation's emit.ts contract ------------------
-// (bridge deliberately has no dep on node-instrumentation, so the ~40 lines are mirrored, same env
-// vars.) Browser producers are the highest-volume writers on the bus — a valtio store churning per
-// frame or a fetch retry loop must not grow events.jsonl unboundedly (2026-07-28: ~680 ev/s, 254 MB
-// in 2h, every ingesting consumer OOM-crash-looped). Per-fingerprint token bucket + round-robin
-// rotation: live file caps at MAX_EVENT_BYTES, history kept as `.1` … `.N`, oldest dropped.
-/** Same cap contract as emit.ts: `LENSMCP_EVENT_MAX_BYTES` (default 50 MB) per generation. */
-const MAX_EVENT_BYTES = (() => {
-    const n = Number(process.env['LENSMCP_EVENT_MAX_BYTES']);
-    return Number.isFinite(n) && n > 0 ? n : 50 * 1024 * 1024;
-})();
-/** Same history contract as emit.ts: `LENSMCP_EVENT_MAX_FILES` rotated generations (default 5). */
-const MAX_EVENT_FILES = (() => {
-    const n = Number(process.env['LENSMCP_EVENT_MAX_FILES']);
-    return Number.isFinite(n) && n >= 1 && n <= 20 ? Math.floor(n) : 5;
-})();
-const ROTATE_CHECK_BYTES = 1024 * 1024; // stat at most ~once per MB appended
-let bytesSinceCheck = 0;
-function rotateIfLarge(file, addedBytes) {
-    bytesSinceCheck += addedBytes;
-    if (bytesSinceCheck < ROTATE_CHECK_BYTES)
-        return;
-    bytesSinceCheck = 0;
-    try {
-        if (statSync(file).size <= MAX_EVENT_BYTES)
-            return;
-    }
-    catch {
-        return; /* missing / already rotated by a concurrent writer — fine */
-    }
-    try {
-        unlinkSync(`${file}.${MAX_EVENT_FILES}`); // drop the oldest generation
-    }
-    catch { /* none to drop */ }
-    for (let gen = MAX_EVENT_FILES - 1; gen >= 1; gen--) {
-        try {
-            renameSync(`${file}.${gen}`, `${file}.${gen + 1}`);
-        }
-        catch { /* gap in history */ }
-    }
-    try {
-        renameSync(file, `${file}.1`);
-    }
-    catch { /* lost the rotate race — a concurrent cascade ran */ }
-}
-/** Per-fingerprint token bucket (burst 30, then 5/s; `LENSMCP_EVENT_MAX_EPS` overrides, 0/'off' disables). */
-const FLOOD_PER_SEC = (() => {
-    const raw = process.env['LENSMCP_EVENT_MAX_EPS'];
-    if (raw === 'off')
-        return Infinity;
-    const n = Number(raw);
-    if (raw !== undefined && raw !== '' && Number.isFinite(n))
-        return n <= 0 ? Infinity : n;
-    return 5;
-})();
-const FLOOD_BURST = Math.max(30, FLOOD_PER_SEC === Infinity ? 0 : FLOOD_PER_SEC * 4);
-const floodBuckets = new Map();
-/** Returns `-1` to drop, else the suppressed-since-last-admit count to annotate (0 normally). */
-function floodAdmit(fingerprint) {
-    if (FLOOD_PER_SEC === Infinity)
-        return 0;
-    const now = Date.now();
-    let b = floodBuckets.get(fingerprint);
-    if (!b) {
-        if (floodBuckets.size >= 2048) {
-            for (const [k, v] of floodBuckets)
-                if (now - v.lastSeenAt > 60_000)
-                    floodBuckets.delete(k);
-            if (floodBuckets.size >= 2048)
-                floodBuckets.clear();
-        }
-        b = { tokens: FLOOD_BURST, lastRefillAt: now, suppressed: 0, lastSeenAt: now };
-        floodBuckets.set(fingerprint, b);
-    }
-    b.lastSeenAt = now;
-    b.tokens = Math.min(FLOOD_BURST, b.tokens + ((now - b.lastRefillAt) / 1000) * FLOOD_PER_SEC);
-    b.lastRefillAt = now;
-    if (b.tokens >= 1) {
-        b.tokens -= 1;
-        const suppressed = b.suppressed;
-        b.suppressed = 0;
-        return suppressed;
-    }
-    b.suppressed += 1;
-    return -1;
-}
-/**
- * Resolve a cross-process event sink from env, mirroring
- * `@lensmcp/nest-instrumentation`'s `defaultEventSink` so every producer
- * (Nest app, Vite plugin, standalone bridge) speaks the same transport:
- *   1. `LENSMCP_EVENT_FILE` — append one JSON line per event.
- *   2. `LENSMCP_UDS` — Unix domain socket, framed NDJSON, reconnecting.
- *   3. `LENSMCP_IPC_SOCKET` (`host:port`) — one UDP datagram per event.
- * Cached after first resolution; returns `null` when none is set.
- */
-let cachedEnvSink;
-export function resolveEnvSink() {
-    if (cachedEnvSink !== undefined)
-        return cachedEnvSink;
-    const filePath = process.env['LENSMCP_EVENT_FILE'];
-    if (filePath) {
-        cachedEnvSink = (event) => {
-            try {
-                const suppressed = floodAdmit(event.fingerprint);
-                if (suppressed < 0)
-                    return; // flood-guarded — next admitted event carries the count
-                const line = JSON.stringify(suppressed > 0 ? { ...event, raw: { ...(event.raw ?? {}), floodSuppressed: suppressed } } : event) + '\n';
-                rotateIfLarge(filePath, line.length);
-                appendFileSync(filePath, line);
-            }
-            catch {
-                /* swallow */
-            }
-        };
-        return cachedEnvSink;
-    }
-    const udsPath = process.env['LENSMCP_UDS'];
-    if (udsPath) {
-        cachedEnvSink = udsEnvSink(udsPath);
-        return cachedEnvSink;
-    }
-    const socketPath = process.env['LENSMCP_IPC_SOCKET'];
-    if (socketPath) {
-        const [host, portStr] = socketPath.split(':');
-        const port = Number(portStr);
-        if (host && Number.isFinite(port)) {
-            const sock = createSocket('udp4');
-            sock.unref();
-            cachedEnvSink = (event) => {
-                try {
-                    const buf = Buffer.from(JSON.stringify(event));
-                    sock.send(buf, port, host, () => undefined);
-                }
-                catch {
-                    /* swallow */
-                }
-            };
-            return cachedEnvSink;
-        }
-    }
-    cachedEnvSink = null;
-    return null;
-}
-/** Test/embedding hook: drop the memoised sink so the next resolve re-reads env. */
-export function resetEnvSinkCache() {
-    cachedEnvSink = undefined;
-}
-/** Reconnecting NDJSON client over a Unix domain socket (see session/uds.ts). */
-export function udsEnvSink(path) {
-    const queue = [];
-    let sock = null;
-    let connecting = false;
-    const flush = () => {
-        if (!sock || !sock.writable)
-            return;
-        while (queue.length > 0)
-            sock.write(queue.shift());
-    };
-    const open = () => {
-        if (connecting || sock)
-            return;
-        connecting = true;
-        const s = connect(path);
-        s.on('connect', () => {
-            connecting = false;
-            sock = s;
-            flush();
-        });
-        s.on('drain', flush);
-        s.on('error', () => {
-            connecting = false;
-            sock = null;
-        });
-        s.on('close', () => {
-            sock = null;
-        });
-        s.unref();
-    };
-    open();
-    return (event) => {
-        queue.push(JSON.stringify(event) + '\n');
-        while (queue.length > 10000)
-            queue.shift();
-        if (sock && sock.writable) {
-            flush();
-            return;
-        }
-        // Dead socket (server restart) — drop it so open() reconnects.
-        if (sock) {
-            try {
-                sock.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-            sock = null;
-        }
-        open();
-    };
-}
+"use strict";var y=Object.defineProperty;var f=(e,n)=>y(e,"name",{value:n,configurable:!0});var b=Object.defineProperty,l=f((e,n)=>b(e,"name",{value:n,configurable:!0}),"f"),_=Object.defineProperty,c=l((e,n)=>_(e,"name",{value:n,configurable:!0}),"i");import{connect as M}from"node:net";import{createSocket as C}from"node:dgram";import{appendFileSync as g,renameSync as d,statSync as A,unlinkSync as L}from"node:fs";const P=(()=>{const e=Number(process.env.LENSMCP_EVENT_MAX_BYTES);return Number.isFinite(e)&&e>0?e:50*1024*1024})(),h=(()=>{const e=Number(process.env.LENSMCP_EVENT_MAX_FILES);return Number.isFinite(e)&&e>=1&&e<=20?Math.floor(e):5})(),w=1024*1024;let p=0;function E(e,n){if(p+=n,!(p<w)){p=0;try{if(A(e).size<=P)return}catch{return}try{L(`${e}.${h}`)}catch{}for(let t=h-1;t>=1;t--)try{d(`${e}.${t}`,`${e}.${t+1}`)}catch{}try{d(e,`${e}.1`)}catch{}}}f(E,"d"),l(E,"C"),c(E,"rotateIfLarge");const S=(()=>{const e=process.env.LENSMCP_EVENT_MAX_EPS;if(e==="off")return 1/0;const n=Number(e);return e!==void 0&&e!==""&&Number.isFinite(n)?n<=0?1/0:n:5})(),m=Math.max(30,S===1/0?0:S*4),a=new Map;function v(e){if(S===1/0)return 0;const n=Date.now();let t=a.get(e);if(!t){if(a.size>=2048){for(const[r,s]of a)n-s.lastSeenAt>6e4&&a.delete(r);a.size>=2048&&a.clear()}t={tokens:m,lastRefillAt:n,suppressed:0,lastSeenAt:n},a.set(e,t)}if(t.lastSeenAt=n,t.tokens=Math.min(m,t.tokens+(n-t.lastRefillAt)/1e3*S),t.lastRefillAt=n,t.tokens>=1){t.tokens-=1;const r=t.suppressed;return t.suppressed=0,r}return t.suppressed+=1,-1}f(v,"v"),l(v,"T"),c(v,"floodAdmit");let o;export function resolveEnvSink(){if(o!==void 0)return o;const e=process.env.LENSMCP_EVENT_FILE;if(e)return o=c(r=>{try{const s=v(r.fingerprint);if(s<0)return;const u=JSON.stringify(s>0?{...r,raw:{...r.raw??{},floodSuppressed:s}}:r)+`
+`;E(e,u.length),g(e,u)}catch{}},"cachedEnvSink"),o;const n=process.env.LENSMCP_UDS;if(n)return o=udsEnvSink(n),o;const t=process.env.LENSMCP_IPC_SOCKET;if(t){const[r,s]=t.split(":"),u=Number(s);if(r&&Number.isFinite(u)){const i=C("udp4");return i.unref(),o=c(N=>{try{const k=Buffer.from(JSON.stringify(N));i.send(k,u,r,()=>{})}catch{}},"cachedEnvSink"),o}}return o=null,null}f(resolveEnvSink,"resolveEnvSink"),l(resolveEnvSink,"resolveEnvSink"),c(resolveEnvSink,"resolveEnvSink");export function resetEnvSinkCache(){o=void 0}f(resetEnvSinkCache,"resetEnvSinkCache"),l(resetEnvSinkCache,"resetEnvSinkCache"),c(resetEnvSinkCache,"resetEnvSinkCache");export function udsEnvSink(e){const n=[];let t=null,r=!1;const s=c(()=>{if(!(!t||!t.writable))for(;n.length>0;)t.write(n.shift())},"flush"),u=c(()=>{if(r||t)return;r=!0;const i=M(e);i.on("connect",()=>{r=!1,t=i,s()}),i.on("drain",s),i.on("error",()=>{r=!1,t=null}),i.on("close",()=>{t=null}),i.unref()},"open");return u(),i=>{for(n.push(JSON.stringify(i)+`
+`);n.length>1e4;)n.shift();if(t&&t.writable){s();return}if(t){try{t.destroy()}catch{}t=null}u()}}f(udsEnvSink,"udsEnvSink"),l(udsEnvSink,"udsEnvSink"),c(udsEnvSink,"udsEnvSink");

package/lib/event-mappers.js

@@ -1,299 +1,3 @@
-import { fingerprint, ulid } from '@lensmcp/core';
-import { redactDeep, redactText, redactUrl, safeText, safeTitle } from './redact.js';
-const SESSION_ID_PLACEHOLDER = 'pending';
-/**
- * Translate a single client-runtime envelope into the normalised
- * `BaseEvent` consumed by the LensMCP event bus. The bridge publishes
- * these; reducers in `@lensmcp/<app>` materialise them into
- * `runtime://browser/*` resources.
- *
- * ── Substance is the point ──────────────────────────────────────────────────
- * This mapper decides what a reader of `runtime://browser/errors` can actually
- * learn. Measured on foodguard (2026-07-30) an entry looked like:
- *
- *     { id, timestamp, severity: 'error', source: 'client-runtime',
- *       fingerprint: 'runtime:52331dbd', tabId: 'tab-gal0r3bs',
- *       raw: { kind: 'error', at: 1785450203325, tabId: 'tab-gal0r3bs' } }
- *
- * — no message, no stack, no URL, no status. The resource could report that
- * two errors happened and nothing whatsoever about what they were. A signal
- * that is correct but undiagnosable is only half a signal, so every branch
- * below now carries identity: a title that names the failure, a bounded
- * message/stack, and for a request its method, URL and STATUS.
- *
- * Every string that reaches `title`/`message` is redacted and bounded first
- * (`./redact.js`) — enrichment is exactly what creates the leak risk, so the
- * two land together. See that module for what is and is not scrubbed.
- */
-export function envelopeToEvent(env, sessionId = SESSION_ID_PLACEHOLDER) {
-    // Per-tab identity stamped by the client runtime — keys browser://tabs.
-    const tab = env.tabId ? { tabId: env.tabId } : {};
-    switch (env.kind) {
-        case 'error': {
-            // A cross-origin script yields the opaque "Script error." with no stack
-            // and no file. Saying so is more use than a bare message, because the
-            // fix is a `crossorigin` attribute rather than anything in the app.
-            const opaque = !env.stack && !env.source && (!env.message || env.message === 'Script error.');
-            const name = env.name && env.name !== 'Error' ? `${env.name}: ` : '';
-            // Opaque FIRST: the browser's own "Script error." is a message, but a
-            // useless one — naming the cause points at the actual fix (a
-            // `crossorigin` attribute on the script tag), which the raw string does not.
-            const title = opaque
-                ? 'Uncaught cross-origin script error (no detail available — add crossorigin to the script tag)'
-                : env.message
-                    ? `${name}${env.message}`
-                    : `Uncaught ${env.name ?? 'error'}`;
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity: 'error',
-                context: { sessionId, ...tab },
-                fingerprint: fingerprint({
-                    kind: 'runtime',
-                    identity: `error:${normaliseStackTopFrame(env.stack)}`,
-                    file: env.source,
-                    // The message is the discriminator between two errors thrown from
-                    // the same frame. Without it every anonymous error collapsed into
-                    // one fingerprint, so a count of them meant nothing.
-                    detail: env.message ?? env.name,
-                }),
-                title: safeTitle(title),
-                message: safeText(env.stack ?? env.message),
-                location: env.source
-                    ? { file: redactUrl(env.source), line: env.lineno, column: env.colno }
-                    : undefined,
-                // `raw` is read too — redact it as thoroughly as the rendered fields,
-                // or the credential just moves one key deeper.
-                raw: {
-                    ...env,
-                    ...(env.message ? { message: redactText(env.message) } : {}),
-                    ...(env.stack ? { stack: safeText(env.stack) } : {}),
-                    ...(env.source ? { source: redactUrl(env.source) } : {}),
-                },
-            };
-        }
-        case 'resource-error': {
-            const url = env.url ? redactUrl(env.url) : undefined;
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity: 'error',
-                context: { sessionId, ...tab },
-                fingerprint: fingerprint({
-                    kind: 'runtime',
-                    // Path-normalised so a cache-busted asset does not mint a new
-                    // fingerprint on every reload, while two different failing assets
-                    // stay distinct.
-                    identity: `resource-error:${env.tagName}:${normaliseUrl(env.url ?? '')}`,
-                }),
-                title: safeTitle(`Failed to load <${env.tagName}>${url ? ` ${url}` : ''}`),
-                ...(url ? { relatedUrls: [url] } : {}),
-                raw: { ...env, ...(url ? { url } : {}) },
-            };
-        }
-        case 'unhandledrejection': {
-            const name = env.name && env.name !== 'Error' ? `${env.name}: ` : '';
-            const summary = env.reason.split('\n')[0] ?? env.reason;
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity: 'error',
-                context: { sessionId, ...tab },
-                fingerprint: fingerprint({
-                    kind: 'runtime',
-                    identity: `unhandledrejection:${env.reason.slice(0, 80)}`,
-                }),
-                // The reason belongs in the title. "Unhandled promise rejection" on
-                // its own is a category, not a finding — a reader had to open `raw` to
-                // learn anything, and the status-line summary showed only the category.
-                title: safeTitle(`Unhandled promise rejection: ${name}${summary}`),
-                message: safeText(env.stack ?? env.reason),
-                raw: {
-                    ...env,
-                    reason: redactText(env.reason),
-                    ...(env.stack ? { stack: safeText(env.stack) } : {}),
-                },
-            };
-        }
-        case 'console': {
-            const severity = env.level === 'error' ? 'error' : env.level === 'warn' ? 'warning' : 'info';
-            // Redact the args FIRST, then join. Joining first and scrubbing the
-            // result only catches credential SHAPES (a JWT, a `Bearer …`) — it
-            // cannot know that a key literally named `apiKey` holds one, so
-            // `console.log({ apiKey })` leaked into `message` while `raw.args` was
-            // correctly redacted. Redacting at the structured end catches both.
-            const args = redactDeep(env.args);
-            const text = args.map(stringify).join(' ');
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity,
-                context: { sessionId, ...tab },
-                fingerprint: fingerprint({
-                    kind: 'runtime',
-                    identity: `console:${env.level}:${text.slice(0, 80)}`,
-                }),
-                title: `console.${env.level}`,
-                message: safeText(text),
-                // Console args are the one genuinely unstructured captured payload —
-                // `console.log('auth', { token })` is ordinary debugging code.
-                raw: { ...env, args },
-            };
-        }
-        case 'fetch': {
-            const failed = env.error !== undefined || (env.status !== undefined && env.status >= 400);
-            const url = redactUrl(env.url);
-            const status = env.status !== undefined
-                ? ` → ${env.status}${env.statusText ? ` ${env.statusText}` : ''}`
-                : '';
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'network',
-                severity: failed ? 'error' : 'info',
-                context: { sessionId, ...tab },
-                fingerprint: fingerprint({
-                    kind: 'network',
-                    identity: `${env.method}:${normaliseUrl(env.url)}:${env.status ?? 'err'}`,
-                }),
-                title: safeTitle(`${env.method} ${url}${status}`),
-                message: safeText(env.error),
-                relatedUrls: [url],
-                raw: { ...env, url },
-            };
-        }
-        case 'route':
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity: 'info',
-                context: { sessionId, url: env.url, ...tab },
-                fingerprint: fingerprint({ kind: 'runtime', identity: `route:${env.url}` }),
-                title: `Route → ${env.url}`,
-                raw: env,
-            };
-        case 'ready':
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: 'client-runtime',
-                category: 'runtime',
-                severity: 'info',
-                context: { sessionId, url: env.url, ...tab },
-                fingerprint: fingerprint({ kind: 'runtime', identity: 'client-ready' }),
-                title: 'Client runtime ready',
-                message: env.userAgent,
-                raw: env,
-            };
-        case 'publish': {
-            // Pre-formed publish envelope from in-page instrumentation. Trust
-            // its source/category (the producer is our own injected code); the
-            // reducers gate on those, and the context carries the flow id so
-            // React renders correlate with the originating user action.
-            const net = networkDetails(env.category, env.raw);
-            // A FAILED REQUEST IS AN ERROR, wherever it was published from.
-            //
-            // `flow-fetch` classified every non-ok response as `warning`, so a 4xx
-            // or 5xx never reached `runtime://browser/failed-requests` (the runtime
-            // reducer routes only `severity === 'error'` there). On foodguard that
-            // silently hid 116 real failures — 98×401, 10×503, 8×502. Normalising
-            // here rather than only at the publisher means the invariant holds for
-            // any producer, including an app pinned to an older instrumentation
-            // build.
-            const severity = net && net.status !== undefined && net.status >= 400
-                ? 'error'
-                : (env.severity ?? 'info');
-            // The publisher embedded the un-redacted URL in its own title AND its
-            // own fingerprint (flow-fetch builds both from the raw URL); swap in the
-            // redacted form rather than dropping either. The substitution is
-            // deterministic, so the fingerprint stays a stable dedupe key.
-            const scrub = (s) => net && net.url !== net.redactedUrl ? s.split(net.url).join(net.redactedUrl) : s;
-            const title = scrub(env.title);
-            return {
-                id: ulid(),
-                sessionId,
-                timestamp: env.at,
-                source: env.source,
-                category: env.category,
-                severity,
-                context: { sessionId, ...tab, ...(env.context ?? {}) },
-                fingerprint: env.fingerprint
-                    ? scrub(env.fingerprint)
-                    : fingerprint({ kind: 'publish', identity: title }),
-                title: safeTitle(title),
-                message: safeText(env.message),
-                ...(net ? { relatedUrls: [net.redactedUrl] } : {}),
-                raw: net
-                    ? { ...redactDeep(env.raw), url: net.redactedUrl }
-                    : redactDeep(env.raw),
-            };
-        }
-    }
-}
-// --- helpers ---
-/**
- * Pull `{ url, status }` off a network `publish` envelope's `raw` (the shape
- * `flow-fetch` emits: `fetch-start` / `fetch-done` / `fetch-error`). Returns
- * undefined for anything that is not a network publish carrying a URL, so
- * every other publish passes through untouched.
- */
-function networkDetails(category, raw) {
-    if (category !== 'network' || !raw || typeof raw !== 'object')
-        return undefined;
-    const r = raw;
-    if (typeof r.url !== 'string' || r.url.length === 0)
-        return undefined;
-    return {
-        url: r.url,
-        redactedUrl: redactUrl(r.url),
-        ...(typeof r.status === 'number' ? { status: r.status } : {}),
-    };
-}
-function normaliseStackTopFrame(stack) {
-    if (!stack)
-        return 'unknown';
-    const lines = stack.split('\n').slice(0, 2);
-    for (const line of lines) {
-        const m = line.match(/at\s+(\S+)/);
-        if (m && m[1])
-            return m[1];
-    }
-    return 'unknown';
-}
-function normaliseUrl(url) {
-    try {
-        const u = new URL(url, 'http://x');
-        return `${u.pathname}`;
-    }
-    catch {
-        return url;
-    }
-}
-function stringify(v) {
-    if (typeof v === 'string')
-        return v;
-    try {
-        return JSON.stringify(v);
-    }
-    catch {
-        return String(v);
-    }
-}
+"use strict";var h=Object.defineProperty;var c=(t,e)=>h(t,"name",{value:e,configurable:!0});var x=Object.defineProperty,l=c((t,e)=>x(t,"name",{value:e,configurable:!0}),"c"),U=Object.defineProperty,d=l((t,e)=>U(t,"name",{value:e,configurable:!0}),"s");import{fingerprint as o,ulid as a}from"@lensmcp/core";import{redactDeep as f,redactText as I,redactUrl as m,safeText as u,safeTitle as g}from"./redact.js";const b="pending";export function envelopeToEvent(t,e=b){const s=t.tabId?{tabId:t.tabId}:{};switch(t.kind){case"error":{const r=!t.stack&&!t.source&&(!t.message||t.message==="Script error."),i=t.name&&t.name!=="Error"?`${t.name}: `:"",n=r?"Uncaught cross-origin script error (no detail available \u2014 add crossorigin to the script tag)":t.message?`${i}${t.message}`:`Uncaught ${t.name??"error"}`;return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"error",context:{sessionId:e,...s},fingerprint:o({kind:"runtime",identity:`error:${v(t.stack)}`,file:t.source,detail:t.message??t.name}),title:g(n),message:u(t.stack??t.message),location:t.source?{file:m(t.source),line:t.lineno,column:t.colno}:void 0,raw:{...t,...t.message?{message:I(t.message)}:{},...t.stack?{stack:u(t.stack)}:{},...t.source?{source:m(t.source)}:{}}}}case"resource-error":{const r=t.url?m(t.url):void 0;return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"error",context:{sessionId:e,...s},fingerprint:o({kind:"runtime",identity:`resource-error:${t.tagName}:${p(t.url??"")}`}),title:g(`Failed to load <${t.tagName}>${r?` ${r}`:""}`),...r?{relatedUrls:[r]}:{},raw:{...t,...r?{url:r}:{}}}}case"unhandledrejection":{const r=t.name&&t.name!=="Error"?`${t.name}: `:"",i=t.reason.split(`
+`)[0]??t.reason;return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"error",context:{sessionId:e,...s},fingerprint:o({kind:"runtime",identity:`unhandledrejection:${t.reason.slice(0,80)}`}),title:g(`Unhandled promise rejection: ${r}${i}`),message:u(t.stack??t.reason),raw:{...t,reason:I(t.reason),...t.stack?{stack:u(t.stack)}:{}}}}case"console":{const r=t.level==="error"?"error":t.level==="warn"?"warning":"info",i=f(t.args),n=i.map($).join(" ");return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:r,context:{sessionId:e,...s},fingerprint:o({kind:"runtime",identity:`console:${t.level}:${n.slice(0,80)}`}),title:`console.${t.level}`,message:u(n),raw:{...t,args:i}}}case"fetch":{const r=t.error!==void 0||t.status!==void 0&&t.status>=400,i=m(t.url),n=t.status!==void 0?` \u2192 ${t.status}${t.statusText?` ${t.statusText}`:""}`:"";return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"network",severity:r?"error":"info",context:{sessionId:e,...s},fingerprint:o({kind:"network",identity:`${t.method}:${p(t.url)}:${t.status??"err"}`}),title:g(`${t.method} ${i}${n}`),message:u(t.error),relatedUrls:[i],raw:{...t,url:i}}}case"route":return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"info",context:{sessionId:e,url:t.url,...s},fingerprint:o({kind:"runtime",identity:`route:${t.url}`}),title:`Route \u2192 ${t.url}`,raw:t};case"ready":return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"info",context:{sessionId:e,url:t.url,...s},fingerprint:o({kind:"runtime",identity:"client-ready"}),title:"Client runtime ready",message:t.userAgent,raw:t};case"gone":return{id:a(),sessionId:e,timestamp:t.at,source:"client-runtime",category:"runtime",severity:"info",context:{sessionId:e,...s},fingerprint:o({kind:"runtime",identity:"client-gone"}),title:"Client runtime gone",raw:t};case"publish":{const r=y(t.category,t.raw),i=r&&r.status!==void 0&&r.status>=400?"error":t.severity??"info",n=d(w=>r&&r.url!==r.redactedUrl?w.split(r.url).join(r.redactedUrl):w,"scrub"),k=n(t.title);return{id:a(),sessionId:e,timestamp:t.at,source:t.source,category:t.category,severity:i,context:{sessionId:e,...s,...t.context??{}},fingerprint:t.fingerprint?n(t.fingerprint):o({kind:"publish",identity:k}),title:g(k),message:u(t.message),...r?{relatedUrls:[r.redactedUrl]}:{},raw:r?{...f(t.raw),url:r.redactedUrl}:f(t.raw)}}}}c(envelopeToEvent,"envelopeToEvent"),l(envelopeToEvent,"envelopeToEvent"),d(envelopeToEvent,"envelopeToEvent");function y(t,e){if(t!=="network"||!e||typeof e!="object")return;const s=e;if(!(typeof s.url!="string"||s.url.length===0))return{url:s.url,redactedUrl:m(s.url),...typeof s.status=="number"?{status:s.status}:{}}}c(y,"k"),l(y,"w"),d(y,"networkDetails");function v(t){if(!t)return"unknown";const e=t.split(`
+`).slice(0,2);for(const s of e){const r=s.match(/at\s+(\S+)/);if(r&&r[1])return r[1]}return"unknown"}c(v,"v"),l(v,"h"),d(v,"normaliseStackTopFrame");function p(t){try{return`${new URL(t,"http://x").pathname}`}catch{return t}}c(p,"p"),l(p,"y"),d(p,"normaliseUrl");function $(t){if(typeof t=="string")return t;try{return JSON.stringify(t)}catch{return String(t)}}c($,"w"),l($,"x"),d($,"stringify");

package/lib/redact.d.ts

@@ -1,89 +1,20 @@
 /**
- * Redaction + bounding for browser-originated event text.
- *
- * ── Why this exists ─────────────────────────────────────────────────────────
- * Until now the browser taps recorded almost nothing about an error, so there
- * was nothing to leak. Enriching them (message, stack, method/URL/status)
- * changes that: a request URL routinely carries a credential in its query
- * string (`?access_token=…`, `?code=…` on an OAuth callback, `?key=…` on a
- * Google API), and an error message can quote a JWT or an `Authorization`
- * header. Those values then land in `runtime://browser/*`, which an agent
- * reads and may quote into a transcript.
- *
- * So enrichment and redaction ship together, in the same place. This module is
- * applied in `envelopeToEvent` — the ONE function every browser envelope
- * crosses on its way to the bus — rather than at each tap, so a tap cannot
- * forget it and a hand-rolled client cannot bypass it.
- *
- * `nx.json` has carried a `redaction: { headers, paths }` block since the init
- * generator was written, with no reader anywhere in the repo. This is the
- * first code to honour that intent; the lists below are a superset of it.
- *
- * ── Deliberately NOT done here ──────────────────────────────────────────────
- * • Request/response HEADERS are never captured in the first place (the taps
- *   read none), which is the strongest possible defence — nothing to redact.
- *   Keep it that way; do not add header capture without extending this module.
- * • Request/response BODIES are likewise never captured.
- * • Free text is scrubbed for credential SHAPES (JWT, `Bearer …`), not parsed
- *   for arbitrary URLs. A URL embedded in a stack frame keeps its query
- *   string. Widening that means running the URL redactor over every message,
- *   which is a cost/false-positive trade not worth making blind.
- */
-/** Replacement for a redacted value. Short, obvious, greppable. */
-export declare const REDACTED = "REDACTED";
-/**
- * Bounds. `raw` is structurally clamped to 32KiB by the bus transform
- * (`createEventClamp`, wired in `@lensmcp/session`), but `title`/`message` are
- * NOT — they are plain strings on `BaseEvent` and reach every reader
- * unclamped. A stack from a deep React tree is routinely tens of KB, so these
- * are the bounds that actually keep an event small.
- */
-export declare const MAX_TITLE_CHARS = 300;
-export declare const MAX_MESSAGE_CHARS = 4096;
-export declare const MAX_URL_CHARS = 1024;
-/** Is this query-parameter name carrying a credential? */
-export declare function isSecretParam(name: string): boolean;
-/**
- * Strip credentials from a URL, preserving every other byte.
- *
- * Implemented as a regex rewrite rather than `new URL(...)` on purpose:
- * `URL` re-encodes as it round-trips (`+` vs `%20`, dropped default ports,
- * sorted-looking output), which would mean the URL an agent reads is not the
- * URL the app requested. It also throws on relative inputs, which is most of
- * what a SPA fetches. This keeps the string byte-identical apart from the
- * redacted values, and never throws.
- *
- * Redacts, in order: userinfo, then any query OR fragment parameter whose name
- * looks like a credential. The fragment matters — an OAuth implicit-flow
- * callback puts the access token there (`#access_token=…`).
- */
-export declare function redactUrl(url: string): string;
-/**
- * Scrub credential SHAPES out of free text (an error message, a stack, a
- * console line). Cheap, linear, and tuned for precision over recall — a false
- * positive destroys the diagnostic value this whole change is adding.
- */
-export declare function redactText(text: string): string;
-/**
- * Bound a string, marking what was removed. Marker text matches
- * `@lensmcp/storage`'s `clampEventRaw` so the two truncations read the same in
- * a transcript.
- */
-export declare function clip(value: string, max: number): string;
-/** Redact then bound — the standard treatment for any captured free text. */
-export declare function safeText(value: string | undefined, max?: number): string | undefined;
-/** Redact then bound — the standard treatment for a captured title. */
-export declare function safeTitle(value: string): string;
-/**
- * Scrub credential shapes out of every string leaf of an arbitrary value.
- *
- * Needed for `console` arguments, which are the one captured payload that is
- * genuinely unstructured — `console.log('auth', { token })` is ordinary
- * debugging code, and the whole point of this change is that those payloads
- * now reach a transcript. Bounded on depth and array length so a pathological
- * object cannot make the bridge the slow part of a page's logging.
- *
- * Values are returned by reference when nothing changed, so the common case
- * (no credential anywhere) allocates nothing.
+ * Redaction + bounding — re-exported from `@lensmcp/core/redact`.
+ *
+ * The implementation used to live HERE, applied in `envelopeToEvent` (the one
+ * function every browser envelope crosses). That worked, and it covered only
+ * the browser: the cluster GATEWAY publishes its own events straight onto the
+ * same bus without crossing that function, and was found writing
+ * `?access_token=sk_live_…` verbatim into `title`, `raw.url` and
+ * `raw.steps[].url` of a real `.lensmcp/events.jsonl`.
+ *
+ * Fixing that needed the same redactor in `@lensmcp/cluster`, which sits at
+ * `layer:install` and cannot sensibly depend on this WebSocket-server package.
+ * So the module moved DOWN to `layer:core` — reachable by both — and this file
+ * stays as the re-export so nothing in the bridge (or any consumer of
+ * `@lensmcp/bridge`'s public API) has to change.
+ *
+ * There is exactly ONE implementation. Do not add logic here; edit
+ * `libs/core/src/lib/redact.ts`.
  */
-export declare function redactDeep(value: unknown, depth?: number): unknown;
+export { clip, isSecretParam, MAX_MESSAGE_CHARS, MAX_TITLE_CHARS, MAX_URL_CHARS, redactDeep, redactText, redactUrl, redactUrlParams, REDACTED, safeText, safeTitle, } from '@lensmcp/core/redact';

package/lib/redact.js

@@ -1,215 +1 @@
-/**
- * Redaction + bounding for browser-originated event text.
- *
- * ── Why this exists ─────────────────────────────────────────────────────────
- * Until now the browser taps recorded almost nothing about an error, so there
- * was nothing to leak. Enriching them (message, stack, method/URL/status)
- * changes that: a request URL routinely carries a credential in its query
- * string (`?access_token=…`, `?code=…` on an OAuth callback, `?key=…` on a
- * Google API), and an error message can quote a JWT or an `Authorization`
- * header. Those values then land in `runtime://browser/*`, which an agent
- * reads and may quote into a transcript.
- *
- * So enrichment and redaction ship together, in the same place. This module is
- * applied in `envelopeToEvent` — the ONE function every browser envelope
- * crosses on its way to the bus — rather than at each tap, so a tap cannot
- * forget it and a hand-rolled client cannot bypass it.
- *
- * `nx.json` has carried a `redaction: { headers, paths }` block since the init
- * generator was written, with no reader anywhere in the repo. This is the
- * first code to honour that intent; the lists below are a superset of it.
- *
- * ── Deliberately NOT done here ──────────────────────────────────────────────
- * • Request/response HEADERS are never captured in the first place (the taps
- *   read none), which is the strongest possible defence — nothing to redact.
- *   Keep it that way; do not add header capture without extending this module.
- * • Request/response BODIES are likewise never captured.
- * • Free text is scrubbed for credential SHAPES (JWT, `Bearer …`), not parsed
- *   for arbitrary URLs. A URL embedded in a stack frame keeps its query
- *   string. Widening that means running the URL redactor over every message,
- *   which is a cost/false-positive trade not worth making blind.
- */
-/** Replacement for a redacted value. Short, obvious, greppable. */
-export const REDACTED = 'REDACTED';
-/**
- * Bounds. `raw` is structurally clamped to 32KiB by the bus transform
- * (`createEventClamp`, wired in `@lensmcp/session`), but `title`/`message` are
- * NOT — they are plain strings on `BaseEvent` and reach every reader
- * unclamped. A stack from a deep React tree is routinely tens of KB, so these
- * are the bounds that actually keep an event small.
- */
-export const MAX_TITLE_CHARS = 300;
-export const MAX_MESSAGE_CHARS = 4096;
-export const MAX_URL_CHARS = 1024;
-/**
- * Substrings that make a query-parameter name a credential regardless of how
- * it is spelled or delimited. These are safe as substrings — no ordinary
- * parameter name contains them innocently.
- */
-const SECRET_SUBSTRINGS = [
-    'token',
-    'secret',
-    'password',
-    'passwd',
-    'apikey',
-    'credential',
-    'assertion',
-    'signature',
-];
-/**
- * Whole delimiter-separated words that make a parameter name a credential.
- * Matched per-word (splitting on `-`, `_`, `.`) rather than as substrings,
- * because the short ones collide: `auth` is a substring of `author`, `key` of
- * `keywords`, `sig` of `sign_up_date`. Word matching keeps `?author=jane` and
- * `?keywords=x` intact while still catching `?api_key=`/`?x-auth=`.
- */
-const SECRET_WORDS = new Set([
-    'key',
-    'auth',
-    'authorization',
-    'jwt',
-    'code',
-    'sig',
-    'pwd',
-    'pass',
-    'session',
-    'sid',
-    'bearer',
-    'otp',
-    // The `headers` half of the `nx.json` redaction contract. Relevant to
-    // `redactDeep` (a headers object logged to console) as much as to a query
-    // string.
-    'cookie',
-    'set-cookie',
-]);
-/** Is this query-parameter name carrying a credential? */
-export function isSecretParam(name) {
-    const n = name.toLowerCase();
-    if (SECRET_SUBSTRINGS.some((s) => n.includes(s)))
-        return true;
-    for (const word of n.split(/[-_.]+/)) {
-        if (word && SECRET_WORDS.has(word))
-            return true;
-    }
-    return false;
-}
-/**
- * `scheme://user:pass@host` — credentials in the authority component.
- * Anchored at the scheme so it cannot match a `@` inside a path or query.
- */
-const USERINFO_RE = /^([a-z][a-z0-9+.-]*:\/\/)[^/?#@\s]*@/i;
-/**
- * One `?name=value` / `&name=value` / `#name=value` pair. Values are matched
- * lazily up to the next delimiter, so the walk is linear and cannot backtrack
- * catastrophically on a long URL.
- */
-const PARAM_RE = /([?&#])([^=&#\s]+)=([^&#\s]*)/g;
-/**
- * Strip credentials from a URL, preserving every other byte.
- *
- * Implemented as a regex rewrite rather than `new URL(...)` on purpose:
- * `URL` re-encodes as it round-trips (`+` vs `%20`, dropped default ports,
- * sorted-looking output), which would mean the URL an agent reads is not the
- * URL the app requested. It also throws on relative inputs, which is most of
- * what a SPA fetches. This keeps the string byte-identical apart from the
- * redacted values, and never throws.
- *
- * Redacts, in order: userinfo, then any query OR fragment parameter whose name
- * looks like a credential. The fragment matters — an OAuth implicit-flow
- * callback puts the access token there (`#access_token=…`).
- */
-export function redactUrl(url) {
-    if (!url)
-        return url;
-    const withoutUserinfo = url.replace(USERINFO_RE, `$1${REDACTED}@`);
-    const withoutSecrets = withoutUserinfo.replace(PARAM_RE, (match, delim, name) => isSecretParam(name) ? `${delim}${name}=${REDACTED}` : match);
-    return clip(withoutSecrets, MAX_URL_CHARS);
-}
-/** A JSON Web Token: three base64url segments, the first starting `eyJ` (`{"`). */
-const JWT_RE = /\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]*/g;
-/** `Bearer <token>` / `Basic <creds>`, however it was quoted or spaced. */
-const SCHEME_CREDENTIAL_RE = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi;
-/**
- * A credential-bearing header quoted into free text — `authorization: xyz`,
- * `"x-api-key": "xyz"`, `cookie=xyz`. Only the VALUE is replaced so the reader
- * still learns which header was involved.
- */
-const HEADER_CREDENTIAL_RE = /\b(authorization|x-api-key|api-key|cookie|set-cookie|proxy-authorization)\b(\s*[:=]\s*)(["']?)([^\s"',;]{4,})\3/gi;
-/**
- * Scrub credential SHAPES out of free text (an error message, a stack, a
- * console line). Cheap, linear, and tuned for precision over recall — a false
- * positive destroys the diagnostic value this whole change is adding.
- */
-export function redactText(text) {
-    return text
-        .replace(HEADER_CREDENTIAL_RE, (_m, header, sep, quote) => `${header}${sep}${quote}${REDACTED}${quote}`)
-        .replace(JWT_RE, REDACTED)
-        .replace(SCHEME_CREDENTIAL_RE, (_m, scheme) => `${scheme} ${REDACTED}`);
-}
-/**
- * Bound a string, marking what was removed. Marker text matches
- * `@lensmcp/storage`'s `clampEventRaw` so the two truncations read the same in
- * a transcript.
- */
-export function clip(value, max) {
-    if (value.length <= max)
-        return value;
-    return `${value.slice(0, max)}…[lensmcp truncated: ${value.length - max} more chars]`;
-}
-/** Redact then bound — the standard treatment for any captured free text. */
-export function safeText(value, max = MAX_MESSAGE_CHARS) {
-    if (value === undefined)
-        return undefined;
-    return clip(redactText(value), max);
-}
-/** Redact then bound — the standard treatment for a captured title. */
-export function safeTitle(value) {
-    return clip(redactText(value), MAX_TITLE_CHARS);
-}
-/** Depth ceiling for {@link redactDeep}; doubles as an allocation-free cycle guard. */
-const MAX_REDACT_DEPTH = 6;
-/** Array ceiling for {@link redactDeep}. Beyond this the tail is left as-is for the raw clamp to shed. */
-const MAX_REDACT_ITEMS = 64;
-/**
- * Scrub credential shapes out of every string leaf of an arbitrary value.
- *
- * Needed for `console` arguments, which are the one captured payload that is
- * genuinely unstructured — `console.log('auth', { token })` is ordinary
- * debugging code, and the whole point of this change is that those payloads
- * now reach a transcript. Bounded on depth and array length so a pathological
- * object cannot make the bridge the slow part of a page's logging.
- *
- * Values are returned by reference when nothing changed, so the common case
- * (no credential anywhere) allocates nothing.
- */
-export function redactDeep(value, depth = 0) {
-    if (typeof value === 'string') {
-        return redactText(value);
-    }
-    if (value === null || typeof value !== 'object' || depth >= MAX_REDACT_DEPTH) {
-        return value;
-    }
-    if (Array.isArray(value)) {
-        let changed = false;
-        const out = value.map((item, i) => {
-            if (i >= MAX_REDACT_ITEMS)
-                return item;
-            const next = redactDeep(item, depth + 1);
-            if (next !== item)
-                changed = true;
-            return next;
-        });
-        return changed ? out : value;
-    }
-    let changed = false;
-    const out = {};
-    for (const [key, item] of Object.entries(value)) {
-        // A key named like a credential is redacted whatever its value's shape —
-        // this is the `paths` half of the `nx.json` redaction contract.
-        const next = isSecretParam(key) && item !== undefined && item !== null ? REDACTED : redactDeep(item, depth + 1);
-        if (next !== item)
-            changed = true;
-        out[key] = next;
-    }
-    return changed ? out : value;
-}
+"use strict";export{clip,isSecretParam,MAX_MESSAGE_CHARS,MAX_TITLE_CHARS,MAX_URL_CHARS,redactDeep,redactText,redactUrl,redactUrlParams,REDACTED,safeText,safeTitle}from"@lensmcp/core/redact";

package/lib/server.d.ts

@@ -41,6 +41,8 @@ export declare function makePublisher(deps: BridgeDeps): (event: BaseEvent) => v
  * exercised over a real WebSocket without booting any bundler.
  */
 export declare function handleClientEnvelope(raw: string, publish: (event: BaseEvent) => void, sessionId?: string): void;
+/** The tab a raw envelope belongs to, or undefined for a malformed/untagged one. */
+export declare function readTabId(raw: string): string | undefined;
 /**
  * Stand up the browser-event bridge: a WebSocket server the injected
  * `@lensmcp/client-runtime` connects to, forwarding every envelope onto

package/lib/server.js

@@ -1,109 +1 @@
-import { createServer as createNetServer } from 'node:net';
-import { WebSocketServer } from 'ws';
-import { DEFAULT_WS_HOST, DEFAULT_WS_PORT } from './constants.js';
-import { resolveEnvSink } from './env-sink.js';
-import { envelopeToEvent } from './event-mappers.js';
-/**
- * Build a `publish` function honouring the bus → sink → env-sink → console
- * precedence. Mirrors the logic the Vite plugin used to inline, lifted here
- * so the standalone sidecar and the plugin share one path.
- */
-export function makePublisher(deps) {
-    let resolvedSink;
-    return (event) => {
-        if (deps.bus) {
-            deps.bus.publish(event);
-            return;
-        }
-        if (deps.sink) {
-            deps.sink(event);
-            return;
-        }
-        // Resolve the env sink once, lazily — matches the Nest sink contract.
-        if (resolvedSink === undefined)
-            resolvedSink = resolveEnvSink();
-        if (resolvedSink) {
-            resolvedSink(event);
-            return;
-        }
-        // Standalone fallback so the bridge is debuggable without any transport.
-        if (event.severity === 'error' || event.severity === 'fatal') {
-            console.debug(`[lensmcp-bridge] ${event.severity}: ${event.title}`);
-        }
-    };
-}
-/**
- * Parse one raw WebSocket message from the injected client runtime and
- * forward the resulting event via `publish`. Exported so it can be
- * exercised over a real WebSocket without booting any bundler.
- */
-export function handleClientEnvelope(raw, publish, sessionId) {
-    let env;
-    try {
-        env = JSON.parse(raw);
-    }
-    catch {
-        return; // ignore malformed
-    }
-    if (!env || typeof env !== 'object' || !('kind' in env))
-        return;
-    publish(envelopeToEvent(env, sessionId));
-}
-/**
- * Stand up the browser-event bridge: a WebSocket server the injected
- * `@lensmcp/client-runtime` connects to, forwarding every envelope onto
- * the event bus (in-process or cross-process). Build-agnostic — the Vite
- * plugin uses it on an ephemeral port; the standalone sidecar uses it on a
- * fixed port for webpack / Next.js / no-build hosts.
- *
- * Resolves once the server is listening, with the actual bound `port`.
- */
-export async function createBridgeServer(options = {}) {
-    const host = options.host ?? DEFAULT_WS_HOST;
-    const requestedPort = options.port ?? DEFAULT_WS_PORT;
-    const port = requestedPort === 0 ? await findFreePort() : requestedPort;
-    const publish = makePublisher(options);
-    const wss = new WebSocketServer({ host, port });
-    wss.on('connection', (socket) => {
-        socket.on('message', (raw) => {
-            handleClientEnvelope(raw.toString(), publish, options.sessionId);
-        });
-    });
-    await new Promise((resolve, reject) => {
-        const onError = (err) => {
-            wss.off('listening', onListening);
-            reject(err);
-        };
-        const onListening = () => {
-            wss.off('error', onError);
-            resolve();
-        };
-        wss.once('error', onError);
-        wss.once('listening', onListening);
-    });
-    return {
-        port,
-        host,
-        close: () => new Promise((resolve) => {
-            wss.close(() => resolve());
-        }),
-    };
-}
-/** Allocate an ephemeral free port (used when `port: 0` is requested). */
-export function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const s = createNetServer();
-        s.unref();
-        s.on('error', reject);
-        s.listen(0, () => {
-            const addr = s.address();
-            if (!addr) {
-                s.close();
-                reject(new Error('Could not allocate free port'));
-                return;
-            }
-            const freePort = addr.port;
-            s.close(() => resolve(freePort));
-        });
-    });
-}
+"use strict";var v=Object.defineProperty;var i=(e,r)=>v(e,"name",{value:r,configurable:!0});var b=Object.defineProperty,c=i((e,r)=>b(e,"name",{value:r,configurable:!0}),"i"),m=Object.defineProperty,t=c((e,r)=>m(e,"name",{value:r,configurable:!0}),"o");import{createServer as g}from"node:net";import{WebSocketServer as S}from"ws";import{DEFAULT_WS_HOST as h,DEFAULT_WS_PORT as y}from"./constants.js";import{resolveEnvSink as P}from"./env-sink.js";import{envelopeToEvent as k}from"./event-mappers.js";export function makePublisher(e){let r;return o=>{if(e.bus){e.bus.publish(o);return}if(e.sink){e.sink(o);return}if(r===void 0&&(r=P()),r){r(o);return}(o.severity==="error"||o.severity==="fatal")&&console.debug(`[lensmcp-bridge] ${o.severity}: ${o.title}`)}}i(makePublisher,"makePublisher"),c(makePublisher,"makePublisher"),t(makePublisher,"makePublisher");export function handleClientEnvelope(e,r,o){let n;try{n=JSON.parse(e)}catch{return}!n||typeof n!="object"||!("kind"in n)||r(k(n,o))}i(handleClientEnvelope,"handleClientEnvelope"),c(handleClientEnvelope,"handleClientEnvelope"),t(handleClientEnvelope,"handleClientEnvelope");export function readTabId(e){try{const r=JSON.parse(e);return typeof r?.tabId=="string"&&r.tabId?r.tabId:void 0}catch{return}}i(readTabId,"readTabId"),c(readTabId,"readTabId"),t(readTabId,"readTabId");export async function createBridgeServer(e={}){const r=e.host??h,o=e.port??y,n=o===0?await findFreePort():o,f=makePublisher(e),s=new S({host:r,port:n});return s.on("connection",a=>{let l;a.on("message",u=>{const d=u.toString();l??=readTabId(d),handleClientEnvelope(d,f,e.sessionId)}),a.on("close",()=>{l&&handleClientEnvelope(JSON.stringify({kind:"gone",at:Date.now(),tabId:l}),f,e.sessionId)})}),await new Promise((a,l)=>{const u=t(p=>{s.off("listening",d),l(p)},"onError"),d=t(()=>{s.off("error",u),a()},"onListening");s.once("error",u),s.once("listening",d)}),{port:n,host:r,close:t(()=>new Promise(a=>{s.close(()=>a())}),"close")}}i(createBridgeServer,"createBridgeServer"),c(createBridgeServer,"createBridgeServer"),t(createBridgeServer,"createBridgeServer");export function findFreePort(){return new Promise((e,r)=>{const o=g();o.unref(),o.on("error",r),o.listen(0,()=>{const n=o.address();if(!n){o.close(),r(new Error("Could not allocate free port"));return}const f=n.port;o.close(()=>e(f))})})}i(findFreePort,"findFreePort"),c(findFreePort,"findFreePort"),t(findFreePort,"findFreePort");

package/lib/types.d.ts

@@ -79,6 +79,24 @@ export type ClientEnvelope = (
     at: number;
     userAgent: string;
     url: string;
+}
+/**
+ * The tab's transport closed — its document is GONE.
+ *
+ * Synthesised by the BRIDGE on socket close, never sent by the page: the
+ * failure this exists for is exactly the one a page cannot report. `ready`
+ * comes from the injected client runtime, so a tab whose entry script failed
+ * to load can never announce a document boundary — and under `ready`-only
+ * retraction its error was immortal by construction.
+ *
+ * Measured on foodguard (2026-08-01): 38 retained browser errors across 26
+ * DISTINCT tabs, none with more than two — 26 dead one-shot documents, 15 of
+ * them the client script itself failing to load. `agent://current-status`
+ * reported `failing` on all of it while the app served cleanly.
+ */
+ | {
+    kind: 'gone';
+    at: number;
 } | {
     kind: 'publish';
     at: number;

package/lib/types.js

@@ -1 +1 @@
-export {};
+"use strict";export{};

package/main.js

@@ -1,47 +1 @@
-/**
- * Standalone bridge sidecar — the build-agnostic entry.
- *
- * Run directly (`node bridge.js`) or via `lensmcp bridge`. Stands up the
- * WebSocket the injected `@lensmcp/client-runtime` connects to, on a FIXED
- * port (so a no-build / webpack / Next.js host can point at a known URL),
- * and forwards every browser envelope onto the cross-process event sink
- * the MCP server tails.
- *
- * Env:
- *   LENSMCP_WS_HOST     bind host (default 127.0.0.1)
- *   LENSMCP_WS_PORT     bind port (default 5747; `0` = ephemeral)
- *   LENSMCP_SESSION_ID  session id stamped onto every event (optional)
- *   LENSMCP_EVENT_FILE  JSONL sink the MCP server ingests (or LENSMCP_UDS /
- *                       LENSMCP_IPC_SOCKET) — resolved by the env sink.
- */
-import { DEFAULT_WS_HOST, DEFAULT_WS_PORT, ENV_SESSION_ID, ENV_WS_HOST, ENV_WS_PORT } from './lib/constants.js';
-import { createBridgeServer } from './lib/server.js';
-async function main() {
-    const host = process.env[ENV_WS_HOST] ?? DEFAULT_WS_HOST;
-    const portRaw = process.env[ENV_WS_PORT];
-    const port = portRaw !== undefined && portRaw !== '' ? Number(portRaw) : DEFAULT_WS_PORT;
-    if (!Number.isFinite(port) || port < 0) {
-        console.error(`[lensmcp-bridge] invalid ${ENV_WS_PORT}=${portRaw}`);
-        process.exit(2);
-    }
-    const sessionId = process.env[ENV_SESSION_ID];
-    let server;
-    try {
-        server = await createBridgeServer({ host, port, sessionId });
-    }
-    catch (err) {
-        console.error(`[lensmcp-bridge] failed to listen on ws://${host}:${port} — ${err.message}`);
-        process.exit(1);
-    }
-    console.log(`[lensmcp-bridge] listening on ws://${server.host}:${server.port}`);
-    let closing = false;
-    const shutdown = () => {
-        if (closing)
-            return;
-        closing = true;
-        void server.close().then(() => process.exit(0));
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
-}
-void main();
+"use strict";var d=Object.defineProperty;var n=(s,e)=>d(s,"name",{value:e,configurable:!0});var v=Object.defineProperty,a=n((s,e)=>v(s,"name",{value:e,configurable:!0}),"n"),g=Object.defineProperty,l=a((s,e)=>g(s,"name",{value:e,configurable:!0}),"n");import{DEFAULT_WS_HOST as u,DEFAULT_WS_PORT as _,ENV_SESSION_ID as b,ENV_WS_HOST as T,ENV_WS_PORT as p}from"./lib/constants.js";import{createBridgeServer as f}from"./lib/server.js";async function t(){const s=process.env[T]??u,e=process.env[p],o=e!==void 0&&e!==""?Number(e):_;(!Number.isFinite(o)||o<0)&&(console.error(`[lensmcp-bridge] invalid ${p}=${e}`),process.exit(2));const m=process.env[b];let r;try{r=await f({host:s,port:o,sessionId:m})}catch(S){console.error(`[lensmcp-bridge] failed to listen on ws://${s}:${o} \u2014 ${S.message}`),process.exit(1)}console.log(`[lensmcp-bridge] listening on ws://${r.host}:${r.port}`);let c=!1;const i=l(()=>{c||(c=!0,r.close().then(()=>process.exit(0)))},"shutdown");process.on("SIGINT",i),process.on("SIGTERM",i)}n(t,"l"),a(t,"g"),l(t,"main"),t();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/bridge",
-  "version": "1.18.4",
+  "version": "1.18.7",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -19,8 +19,8 @@
     }
   },
   "dependencies": {
-    "@lensmcp/core": "1.18.4",
-    "@lensmcp/protocol-types": "1.18.4",
+    "@lensmcp/core": "1.18.7",
+    "@lensmcp/protocol-types": "1.18.7",
     "tslib": "^2.3.0",
     "ws": "^8.21.0"
   },