@debugg-ai/debugg-ai-mcp 4.3.0 → 4.4.1

package/dist/services/tunnel/debuggTransport.js

@@ -0,0 +1,439 @@
+/**
+ * debuggTransport — the pure-TS tunnel client for the debugg tunnel server.
+ *
+ * One websocket per tunnel to the relayUrl a provision response supplies,
+ * speaking the wire protocol in services/tunnel/protocol/ (spec: bead
+ * debugg_ai_mcp-xkoh.1.2). It replaces the `ngrok` package, which downloads and
+ * spawns a native agent; `ws` is the only new dependency and is pure JS.
+ *
+ * This file owns exactly four things — the socket, the reconnect policy, the
+ * DIAL policy, and publishing a prober for probeTunnelHealth. Framing, flow
+ * control, liveness, GOAWAY drain and PROBE deadlines all belong to
+ * TunnelSession, and are deliberately not reimplemented here.
+ *
+ * THE DIAL POLICY IS THE SECURITY BOUNDARY: a stream is always piped to the
+ * address TunnelManager registered at connect() and never to anything the
+ * server sends. The protocol's decoder already strips address-shaped fields
+ * from OPEN metadata; this is the second half of that guarantee.
+ */
+import * as net from 'node:net';
+import * as tls from 'node:tls';
+import WebSocket from 'ws';
+import { Logger } from '../../utils/logger.js';
+import { buildHandshakeHeaders, interpretHandshakeResponse, webSocketTransport, CloseCode, ErrorCode, MAX_FRAME_SIZE, PROBE_TIMEOUT_MS, TunnelSession, } from './protocol/index.js';
+import { registerControlProbe, unregisterControlProbe } from './probeRegistry.js';
+const logger = new Logger({ module: 'debuggTransport' });
+/** A DebuggSocketLike is always usable as the protocol module's WebSocketLike. */
+const _socketIsWebSocketLike = (s) => s;
+void _socketIsWebSocketLike;
+const DEFAULT_RECONNECT_BACKOFF_MS = [250, 500, 1000, 2000, 5000, 10000];
+const defaultSocketFactory = (url, init) => new WebSocket(url, {
+    headers: init.headers,
+    // Both ends disable it: dev-server payloads are already compressed and
+    // deflate's per-connection buffers break the protocol's bounded-memory
+    // property (bead debugg_ai_mcp-xkoh.1.2 §0).
+    perMessageDeflate: false,
+    maxPayload: MAX_FRAME_SIZE,
+    followRedirects: false,
+});
+class DebuggTransport {
+    kind = 'debugg';
+    tunnels = new Map();
+    clientVersion;
+    socketFactory;
+    backoffMs;
+    probeTimeoutMs;
+    handshakeTimeoutMs;
+    constructor(opts = {}) {
+        this.clientVersion = opts.clientVersion;
+        this.socketFactory = opts.socketFactory ?? defaultSocketFactory;
+        this.backoffMs = opts.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS;
+        this.probeTimeoutMs = opts.probeTimeoutMs ?? PROBE_TIMEOUT_MS;
+        this.handshakeTimeoutMs = opts.handshakeTimeoutMs ?? 20_000;
+    }
+    async connect(localAddr, hostname, token, opts) {
+        if (!opts.relayUrl) {
+            throw terminal('debugg tunnel provisioning did not supply a relayUrl to connect to');
+        }
+        const host = hostname.toLowerCase();
+        const state = {
+            host,
+            hostname,
+            publicUrl: `https://${hostname}`,
+            tunnelId: opts.tunnelId,
+            token,
+            relayUrl: opts.relayUrl,
+            dial: parseLocalAddr(localAddr),
+            onDead: opts.onDead,
+            stopped: false,
+            dead: false,
+            reconnectAttempt: 0,
+        };
+        const { socket, session } = await this.handshake(state);
+        this.adopt(state, socket, session);
+        this.tunnels.set(host, state);
+        // Published so probeTunnelHealth can health-check a hostname that resolves
+        // only inside our VPC (services/tunnel/probeRegistry.ts).
+        registerControlProbe(host, (path, probeOpts) => this.runProbe(state, path, probeOpts));
+        logger.info(`debugg tunnel connected: ${state.publicUrl} -> ${describeDial(state.dial)}`);
+        return state.publicUrl;
+    }
+    async disconnect(publicUrl) {
+        const state = this.tunnels.get(hostOf(publicUrl));
+        if (!state)
+            return;
+        state.stopped = true;
+        this.teardown(state);
+    }
+    async probe(publicUrl, path, opts = {}) {
+        const state = this.tunnels.get(hostOf(publicUrl));
+        if (!state)
+            return { error: 'CLOSED', elapsedMs: 0 };
+        return this.runProbe(state, path, opts);
+    }
+    // ── Handshake ──────────────────────────────────────────────────────────────
+    handshake(state) {
+        const headers = buildHandshakeHeaders({
+            tunnelId: state.tunnelId,
+            tunnelKey: state.token,
+            ...(this.clientVersion ? { clientVersion: this.clientVersion } : {}),
+        });
+        // The token rides in a header and NEVER in the URL: the ALB and nginx log
+        // URLs, not headers.
+        const socket = this.socketFactory(state.relayUrl, { headers });
+        // ATTACH THE SESSION NOW, not on 'open', and not after connect() resolves.
+        //
+        // The server registers a tunnel the instant the handshake completes and may
+        // send OPEN in that same tick, before any post-handshake wiring could run.
+        // A session (or a 'stream' listener) attached even one microtask later
+        // parses those frames into nothing: the browser request hangs with no error
+        // on either side. It is invisible to a unit test that awaits connect()
+        // first, and it lands precisely in the reconnect gap — a deploy or a
+        // dropped socket is exactly what puts requests there — so in production it
+        // reads as a rare, unexplainable hang instead of a clean failure.
+        // (Cross-arc regression found by the tunnel server's integration tests.)
+        const session = new TunnelSession(webSocketTransport(socket), { role: 'client' });
+        session.on('stream', (stream) => this.pipeToLocal(state, stream));
+        // Non-fatal diagnostics. The session only emits these when something is
+        // listening, and every stream's own 'error' is sunk by the session.
+        session.on('error', (err) => {
+            logger.debug(`debugg tunnel ${state.hostname} session error: ${err.message}`);
+        });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let versionNegotiated = false;
+            let upgraded = false;
+            /**
+             * Tear down a session that never made it into service, so its timers and
+             * socket do not outlive the failed attempt. A socket that reached 101 can
+             * be closed politely with a code; one that never upgraded has no
+             * websocket to close, so the request is aborted instead (which is also
+             * what `ws` needs after 'unexpected-response' — it does not clean up the
+             * socket for you once you have registered that listener).
+             */
+            const abandon = (closeCode) => {
+                try {
+                    if (upgraded && closeCode !== undefined && !session.closed) {
+                        session.close(closeCode, 'handshake rejected');
+                    }
+                    else {
+                        socket.terminate();
+                    }
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+            const timer = setTimeout(() => {
+                fail(egressError(state, 'the connection timed out', 'ETIMEDOUT'));
+                abandon();
+            }, this.handshakeTimeoutMs);
+            timer.unref?.();
+            const done = () => { clearTimeout(timer); settled = true; };
+            const fail = (err) => {
+                if (settled)
+                    return;
+                done();
+                reject(err);
+            };
+            socket.on('upgrade', (res) => {
+                if (settled)
+                    return;
+                upgraded = true;
+                const result = interpretHandshakeResponse(res.statusCode ?? 101, res.headers ?? {});
+                if (result.ok) {
+                    versionNegotiated = true;
+                    return;
+                }
+                // A 101 we cannot negotiate: speaking anyway would corrupt the stream.
+                abandon(ErrorCode.PROTOCOL_ERROR);
+                fail(terminal('the debugg tunnel server accepted the connection but did not echo a protocol version this ' +
+                    'client offered. Update @debugg-ai/debugg-ai-mcp.'));
+            });
+            socket.on('open', () => {
+                if (settled)
+                    return;
+                upgraded = true;
+                if (!versionNegotiated) {
+                    abandon(ErrorCode.PROTOCOL_ERROR);
+                    fail(terminal('the debugg tunnel server accepted the connection without negotiating a protocol version. ' +
+                        'Update @debugg-ai/debugg-ai-mcp.'));
+                    return;
+                }
+                done();
+                resolve({ socket, session });
+            });
+            socket.on('unexpected-response', (_req, res) => {
+                const status = res?.statusCode ?? 0;
+                const result = interpretHandshakeResponse(status, res?.headers ?? {});
+                abandon();
+                fail(handshakeFailureError(state, status, result.ok ? undefined : result.supported, result.ok ? true : result.retryable));
+            });
+            socket.on('error', (err) => {
+                // Before the upgrade completes this is always a connection-level
+                // failure: DNS, TLS, refused, or blocked egress.
+                if (!settled)
+                    abandon();
+                fail(egressError(state, err.message, err.code));
+            });
+        });
+    }
+    // ── Session lifecycle ──────────────────────────────────────────────────────
+    adopt(state, socket, session) {
+        state.socket = socket;
+        state.session = session;
+        state.reconnectAttempt = 0;
+        // 'stream' and 'error' were attached in handshake(), before the handshake
+        // could deliver anything. Only the lifecycle wiring belongs here, because
+        // it must NOT fire for a session that never made it into service.
+        session.on('goaway', (info) => {
+            if (info.code === ErrorCode.REVOKED) {
+                this.markDead(state, `the tunnel server reported it revoked (${info.reason || 'no reason given'})`);
+                return;
+            }
+            // A deploy. Dial a replacement immediately (make-before-break) and let
+            // this session drain its in-flight streams; its later close is ignored
+            // because it is no longer the current one.
+            this.scheduleReconnect(state, 0);
+        });
+        session.on('close', (info) => {
+            if (state.session !== session)
+                return; // superseded by a newer connection
+            state.session = undefined;
+            state.socket = undefined;
+            if (state.stopped || state.dead)
+                return;
+            logger.warn(`debugg tunnel ${state.hostname} lost its control channel (${info.closeCode}); reconnecting`);
+            this.scheduleReconnect(state);
+        });
+    }
+    scheduleReconnect(state, delayOverrideMs) {
+        if (state.stopped || state.dead || state.reconnectTimer)
+            return;
+        const delay = delayOverrideMs ?? this.backoffMs[Math.min(state.reconnectAttempt, this.backoffMs.length - 1)];
+        const timer = setTimeout(() => {
+            state.reconnectTimer = undefined;
+            void this.reconnect(state);
+        }, delay);
+        // Never hold the process open just because a tunnel wants to come back.
+        timer.unref?.();
+        state.reconnectTimer = timer;
+    }
+    async reconnect(state) {
+        if (state.stopped || state.dead)
+            return;
+        try {
+            const { socket, session } = await this.handshake(state);
+            if (state.stopped || state.dead) {
+                try {
+                    socket.close(CloseCode.GOING_AWAY, 'tunnel stopped');
+                }
+                catch { /* ignore */ }
+                return;
+            }
+            const previous = state.session;
+            this.adopt(state, socket, session);
+            // The old session keeps draining; it is closed by the server, and its
+            // close event is ignored now that it is not the current one.
+            if (previous && previous !== session) {
+                void previous.goAway({ code: ErrorCode.GOING_AWAY, reason: 'replaced' }).catch(() => { });
+            }
+            logger.info(`debugg tunnel ${state.hostname} reconnected`);
+        }
+        catch (err) {
+            const error = err;
+            if (error?.retryable === false) {
+                this.markDead(state, error.message);
+                return;
+            }
+            state.reconnectAttempt++;
+            this.scheduleReconnect(state);
+        }
+    }
+    /**
+     * The tunnel can never come back. TunnelManager evicts it, so the next call
+     * re-provisions instead of reusing a corpse.
+     */
+    markDead(state, reason) {
+        if (state.dead)
+            return;
+        state.dead = true;
+        logger.warn(`debugg tunnel ${state.hostname} is permanently gone: ${reason}`);
+        const notify = state.onDead;
+        this.teardown(state);
+        notify?.(reason);
+    }
+    teardown(state) {
+        if (state.reconnectTimer) {
+            clearTimeout(state.reconnectTimer);
+            state.reconnectTimer = undefined;
+        }
+        unregisterControlProbe(state.host);
+        this.tunnels.delete(state.host);
+        const session = state.session;
+        const socket = state.socket;
+        state.session = undefined;
+        state.socket = undefined;
+        try {
+            session?.close(ErrorCode.GOING_AWAY, 'client disconnect');
+        }
+        catch {
+            /* already closed */
+        }
+        if (!session && socket) {
+            try {
+                socket.close(CloseCode.GOING_AWAY, 'client disconnect');
+            }
+            catch { /* ignore */ }
+        }
+    }
+    // ── The dial policy ────────────────────────────────────────────────────────
+    pipeToLocal(state, stream) {
+        const { host, port, tls: useTls } = state.dial;
+        const socket = useTls
+            // Local dev certificates are self-signed by definition, and Caddy's own
+            // upstream handling makes the same choice (insecure_skip_verify).
+            ? tls.connect({ host, port, servername: host, rejectUnauthorized: false })
+            : net.connect({ host, port });
+        let established = false;
+        const ready = useTls ? 'secureConnect' : 'connect';
+        socket.once(ready, () => {
+            established = true;
+            stream.pipe(socket);
+            socket.pipe(stream);
+        });
+        socket.on('error', () => {
+            if (!established) {
+                // The ERR_NGROK_8012 analogue: the tunnel is fine, the app refused.
+                // The server renders DEBUGG_TUNNEL_UPSTREAM_REFUSED from this code and
+                // tunnelDisposition keeps the tunnel.
+                stream.reset(ErrorCode.UPSTREAM_UNREACHABLE);
+            }
+            else {
+                stream.reset(ErrorCode.RESET);
+            }
+            socket.destroy();
+        });
+        stream.on('close', () => { socket.destroy(); });
+    }
+    async runProbe(state, path, opts = {}) {
+        const session = state.session;
+        // Mid-reconnect: report it as a closed channel rather than inventing a
+        // verdict. probeTunnelHealth retries that, and a reconnect lands inside
+        // its ladder.
+        if (!session)
+            return { error: 'CLOSED', elapsedMs: 0 };
+        return session.probe(path, { timeoutMs: opts.timeoutMs ?? this.probeTimeoutMs });
+    }
+}
+// ── Errors ───────────────────────────────────────────────────────────────────
+function tunnelError(message, retryable) {
+    const err = new Error(message);
+    err.retryable = retryable;
+    return err;
+}
+/** Terminal for this token or this build: retrying sends the same thing again. */
+function terminal(message) {
+    return tunnelError(message, false);
+}
+function handshakeFailureError(state, status, supported, retryable) {
+    switch (status) {
+        case 401:
+            // The word "authtoken" is load-bearing: TunnelManager matches it to
+            // render its "invalid auth token" message, the same one an ngrok auth
+            // failure produces.
+            return terminal('the debugg tunnel server rejected the authtoken (HTTP 401) — the tunnel key is invalid, ' +
+                'expired or revoked. A new one is provisioned on the next call.');
+        case 400:
+            return terminal(`the debugg tunnel server rejected the tunnel id "${state.tunnelId}" (HTTP 400)`);
+        case 426:
+            return terminal('this MCP speaks a tunnel protocol version the server no longer supports (HTTP 426' +
+                `${supported ? `, server supports ${supported.join(', ')}` : ''}). ` +
+                'Update @debugg-ai/debugg-ai-mcp.');
+        case 407:
+            return terminal(`an HTTP proxy at your network edge intercepted the tunnel connection to ${hostOf(state.relayUrl)} ` +
+                'and demanded authentication (HTTP 407). The tunnel needs a DIRECT outbound HTTPS (443) ' +
+                'connection; proxies are not supported.');
+        default:
+            return tunnelError(`the debugg tunnel server refused the connection (HTTP ${status})`, retryable);
+    }
+}
+/**
+ * A connection-level failure reaching the relay. This is the one place where
+ * the debugg transport can be WORSE than ngrok for a user — ngrok's agent
+ * honours HTTPS_PROXY and this client does not — so the message says plainly
+ * what has to be allowed instead of reading as a generic tunnel error.
+ */
+function egressError(state, detail, code) {
+    const relayHost = hostOf(state.relayUrl);
+    const proxyVar = ['HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy'].find((name) => process.env[name]);
+    const proxyNote = proxyVar
+        ? ` This environment sets ${proxyVar}, which the tunnel connection does NOT use — HTTP(S) proxies are not supported for it.`
+        : ' HTTP(S) proxies are not supported for the tunnel connection.';
+    return tunnelError(`could not reach the debugg tunnel server at ${relayHost} (${code ?? 'connection failed'}: ${detail}). ` +
+        `Testing a local app needs a direct outbound HTTPS connection to ${relayHost} on port 443 — ` +
+        `allow it in your firewall, VPN or container network rules.${proxyNote}`, true);
+}
+// ── Address handling ─────────────────────────────────────────────────────────
+/**
+ * The five forms TunnelManager registers: Caddy's `http://127.0.0.1:<p>` for a
+ * session tunnel (in Docker too — Caddy runs in the same container), and
+ * `127.0.0.1:<p>`, `host.docker.internal:<p>`, `https://localhost:<p>` or
+ * `https://host.docker.internal:<p>` for the dedicated test_suite path.
+ */
+function parseLocalAddr(localAddr) {
+    const schemed = /^(https?):\/\//i.exec(localAddr);
+    if (schemed) {
+        const url = new URL(localAddr);
+        const useTls = schemed[1].toLowerCase() === 'https';
+        return {
+            host: url.hostname.replace(/^\[|\]$/g, ''),
+            port: url.port ? Number(url.port) : (useTls ? 443 : 80),
+            tls: useTls,
+        };
+    }
+    const lastColon = localAddr.lastIndexOf(':');
+    if (lastColon === -1) {
+        throw terminal(`debugg tunnel cannot dial "${localAddr}": no port`);
+    }
+    const host = localAddr.slice(0, lastColon).replace(/^\[|\]$/g, '');
+    const port = Number(localAddr.slice(lastColon + 1));
+    if (!Number.isInteger(port) || port <= 0) {
+        throw terminal(`debugg tunnel cannot dial "${localAddr}": no port`);
+    }
+    return { host, port, tls: false };
+}
+function describeDial(dial) {
+    return `${dial.tls ? 'https' : 'http'}://${dial.host}:${dial.port}`;
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return url;
+    }
+}
+export function createDebuggTransport(options = {}) {
+    return new DebuggTransport(options);
+}

package/dist/services/tunnel/ngrokTransport.js

@@ -0,0 +1,165 @@
+/**
+ * ngrokTransport — today's ngrok client, behind the TunnelTransport seam.
+ *
+ * This is a MOVE, not a rewrite. Every line here came out of
+ * services/ngrok/tunnelManager.ts unchanged, because the whole point of the
+ * extraction is that the ngrok path keeps behaving exactly as it did while the
+ * debugg transport is rolled out (design §5, bead debugg_ai_mcp-xkoh.5.5): the
+ * lazy module load, `getApi()` bootstrap, the agent pre-warm, the connect
+ * options (including the `https://` addr form), disconnect, and the
+ * module-reset-when-no-tunnels-remain behaviour.
+ *
+ * It exists so that nothing on the debugg path can reach the `ngrok` package.
+ * Until this file was split out, `import('ngrok')` ran on every tunnel
+ * creation, every teardown and every retry, which would have meant a binary
+ * download on machines that never use ngrok again.
+ *
+ * Deleted wholesale in the rollout arc's last step, along with
+ * services/ngrok/ngrokAgentSession.ts and the `ngrok` dependency.
+ */
+import { Logger } from '../../utils/logger.js';
+import { startAgentSession } from '../ngrok/ngrokAgentSession.js';
+const logger = new Logger({ module: 'ngrokTransport' });
+let ngrokModule = null;
+async function getNgrok() {
+    if (!ngrokModule) {
+        try {
+            ngrokModule = await import('ngrok');
+        }
+        catch (error) {
+            throw new Error(`Failed to load ngrok module: ${error}`);
+        }
+    }
+    return ngrokModule;
+}
+/**
+ * Reset the cached ngrok module so the next connect() bootstraps a fresh agent.
+ * Called when the last tunnel is disconnected and the agent process may have died.
+ */
+function resetNgrokModule() {
+    ngrokModule = null;
+}
+class NgrokTransport {
+    kind = 'ngrok';
+    /** Public so TunnelManager can keep exposing its existing test seams. */
+    agentSessionStarter;
+    agentSessionTimeoutMs;
+    /** Whether the ngrok agent's client session is established (bead pqgj). */
+    agentSessionReady = false;
+    /** In-flight session bootstrap, so concurrent tunnels wait on one spawn. */
+    agentSessionPromise = null;
+    initialized = false;
+    constructor(opts = {}) {
+        this.agentSessionStarter = opts.agentSessionStarter ?? startAgentSession;
+        this.agentSessionTimeoutMs = opts.agentSessionTimeoutMs ?? 5000;
+    }
+    /**
+     * Bead pqgj: make sure the ngrok agent's client session is established before
+     * we ask it for a tunnel, so attempt 1 lands on a ready agent instead of the
+     * ~293ms not-ready window that made every single run fail its first connect.
+     *
+     * Never throws: if the agent can't be pre-warmed (ngrok internals moved, slow
+     * session, dead token) we fall through and let the retry ladder do what it
+     * did before this fix. The ladder stays a genuine safety net.
+     */
+    async prepare(authtoken) {
+        await this.ensureInitialized();
+        if (this.agentSessionReady)
+            return;
+        if (!this.agentSessionPromise) {
+            this.agentSessionPromise = (async () => {
+                let markEstablished;
+                const established = new Promise((resolve) => { markEstablished = resolve; });
+                await this.agentSessionStarter({
+                    authtoken,
+                    onStatusChange: (status) => {
+                        if (status === 'connected') {
+                            this.agentSessionReady = true;
+                            markEstablished();
+                        }
+                        else if (status === 'closed') {
+                            this.agentSessionReady = false;
+                        }
+                    },
+                    onTerminated: () => {
+                        // Agent process died — next tunnel must re-warm.
+                        this.agentSessionReady = false;
+                        this.agentSessionPromise = null;
+                    },
+                });
+                let capTimer;
+                const cap = new Promise((resolve) => {
+                    capTimer = setTimeout(resolve, this.agentSessionTimeoutMs);
+                });
+                try {
+                    await Promise.race([established, cap]);
+                }
+                finally {
+                    if (capTimer)
+                        clearTimeout(capTimer);
+                }
+            })().catch((err) => {
+                // Pre-warm unavailable — not fatal, the ladder covers it.
+                this.agentSessionPromise = null;
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.debug(`ngrok agent pre-warm unavailable, relying on connect retry ladder: ${msg}`);
+            });
+        }
+        await this.agentSessionPromise;
+    }
+    /** Whether the pre-warm believes the agent session is live (trace/diagnostics). */
+    get sessionReady() {
+        return this.agentSessionReady;
+    }
+    async connect(localAddr, hostname, token, _opts) {
+        const ngrok = await getNgrok();
+        const url = await ngrok.connect({
+            proto: 'http',
+            addr: localAddr,
+            hostname,
+            authtoken: token,
+        });
+        if (!url) {
+            throw new Error('ngrok.connect() returned empty URL');
+        }
+        return url;
+    }
+    async disconnect(publicUrl) {
+        const ngrok = await getNgrok();
+        await ngrok.disconnect(publicUrl);
+    }
+    /**
+     * The agent-reset the retry ladder does between attempts 1 and 2 — the
+     * "agent died" recovery path that used to be the only retried case.
+     */
+    async resetAfterFailedAttempt() {
+        resetNgrokModule();
+        this.initialized = false;
+        await this.ensureInitialized();
+    }
+    /**
+     * No ngrok tunnels remain, so the agent process may have exited. Reset the
+     * module and init state so the next connect() bootstraps a fresh agent.
+     */
+    onAllTunnelsStopped() {
+        resetNgrokModule();
+        this.initialized = false;
+        this.agentSessionReady = false;
+        this.agentSessionPromise = null;
+    }
+    async ensureInitialized() {
+        if (this.initialized)
+            return;
+        try {
+            const ngrok = await getNgrok();
+            ngrok.getApi();
+        }
+        catch {
+            // ignore — let connect surface real errors
+        }
+        this.initialized = true;
+    }
+}
+export function createNgrokTransport(opts = {}) {
+    return new NgrokTransport(opts);
+}

package/dist/services/tunnel/probeRegistry.js

@@ -0,0 +1,52 @@
+/**
+ * Control-channel probers, keyed by public tunnel host.
+ *
+ * Why this exists: debugg tunnel URLs resolve only inside our VPC, so
+ * utils/localReachability.ts's probeTunnelHealth cannot fetch them from a
+ * user's machine. For those hosts the health check goes over the tunnel's own
+ * control websocket (PROBE / PROBE_RESULT) instead, and the server answers by
+ * making a real request back through the public ingress path.
+ *
+ * probeTunnelHealth is a free function that takes nothing but a URL, and it is
+ * called from four handlers that hold no transport handle. Rather than thread a
+ * new argument through five call sites, debuggTransport registers a prober for
+ * the host it just connected and removes it when the tunnel stops; everything
+ * else keeps taking the HTTP path unchanged.
+ *
+ * Module-level state, like the template caches in utils/handlerCaches.ts. It is
+ * keyed by hostname, which is globally unique (the tunnel id is a uuid), so two
+ * sessions in one process cannot collide.
+ */
+const probes = new Map();
+/** Called by a transport once its control channel is up, for `<id>.tunnel.debugg.ai`. */
+export function registerControlProbe(host, probe) {
+    probes.set(normalizeHost(host), probe);
+}
+/** Called when the tunnel stops for good. Safe to call for an unknown host. */
+export function unregisterControlProbe(host) {
+    probes.delete(normalizeHost(host));
+}
+/**
+ * The prober for a URL's host, or undefined when this process holds no live
+ * control channel for it. Accepts a full URL or a bare host.
+ */
+export function getControlProbe(url) {
+    return probes.get(normalizeHost(url));
+}
+/** Test hook: forget every registered prober. */
+export function _resetControlProbesForTests() {
+    probes.clear();
+}
+function normalizeHost(hostOrUrl) {
+    if (typeof hostOrUrl !== 'string')
+        return '';
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(hostOrUrl)) {
+        try {
+            return new URL(hostOrUrl).hostname.toLowerCase();
+        }
+        catch {
+            return hostOrUrl.toLowerCase();
+        }
+    }
+    return hostOrUrl.split('/')[0].split(':')[0].toLowerCase();
+}