@debugg-ai/debugg-ai-mcp 4.2.2 → 4.4.0

package/dist/utils/localReachability.js

@@ -17,6 +17,8 @@ import { createConnection } from 'node:net';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { Readable } from 'node:stream';
+import { tunnelDomainFor } from './tunnelDomains.js';
+import { getControlProbe } from '../services/tunnel/probeRegistry.js';
 export async function probeLocalPort(port, opts = {}) {
     const host = opts.host ?? '127.0.0.1';
     const timeoutMs = opts.timeoutMs ?? 1500;
@@ -91,7 +93,16 @@ const TRANSIENT_CAUSE_CODES = new Set([
  * other, and coupling them would make this module depend on policy it has no
  * business knowing.
  */
-const ENDPOINT_NOT_FOUND_CODES = new Set(['ERR_NGROK_3200']);
+const ENDPOINT_NOT_FOUND_CODES = new Set([
+    'ERR_NGROK_3200',
+    // The debugg analogue. The server already holds a browser request for
+    // RECONNECT_GRACE_MS (5s) while a client reconnects before rendering this,
+    // but a reconnect that outlasts the grace window would otherwise evict a
+    // tunnel that is about to come back, so confirm it across the ladder too.
+    // DEBUGG_TUNNEL_UNKNOWN is deliberately NOT here: the id is gone, and
+    // re-probing cannot change that answer.
+    'DEBUGG_TUNNEL_OFFLINE',
+]);
 // ─ HTTP/1.1 probe transport (bead kmzb) ──────────────────────────────────────
 /**
  * `fetch`-shaped GET that speaks HTTP/1.1, because the global fetch cannot.
@@ -241,6 +252,16 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
 }
 async function probeOnce(tunnelUrl, opts, started) {
     const timeoutMs = opts.timeoutMs ?? 5000;
+    // A debugg tunnel hostname resolves only inside our VPC, so it cannot be
+    // fetched from the user's machine at all. Its health question goes over the
+    // tunnel's own control websocket instead, and the server answers it by
+    // making a REAL request through the public ingress path — same ALB, same
+    // nginx, same routing a browser takes. Everything below this branch (the
+    // retry ladder, the confirm-across-retries rule, the result shape the
+    // handlers render) is shared by both transports.
+    if (tunnelDomainFor(tunnelUrl)?.transport === 'debugg') {
+        return probeOverControlChannel(tunnelUrl, timeoutMs, started);
+    }
     // Bead kmzb: HTTP/1.1, not the global fetch — see http1Fetch.
     const fetchImpl = opts.fetchFn ?? http1Fetch;
     const controller = new AbortController();
@@ -345,6 +366,118 @@ async function probeOnce(tunnelUrl, opts, started) {
         };
     }
 }
+// ─ Control-channel probe (debugg transport) ──────────────────────────────────
+/**
+ * Ask the tunnel server to fetch `path` back through this tunnel and report
+ * what it got. Maps PROBE_RESULT onto the same TunnelHealthProbeResult the
+ * HTTP path produces — the mapping is pinned on bead debugg_ai_mcp-xkoh.1.2 §9
+ * and must not be re-derived here.
+ */
+async function probeOverControlChannel(tunnelUrl, timeoutMs, started) {
+    const elapsed = () => Date.now() - started;
+    const probe = getControlProbe(tunnelUrl);
+    if (!probe) {
+        // No live control channel in this process for that hostname, and the URL
+        // is unreachable any other way. The tunnel is not coming back on its own,
+        // so report it gone and let the disposition policy clear the leftovers.
+        return {
+            retryable: false,
+            result: {
+                healthy: false,
+                code: 'NGROK_ERROR',
+                ngrokErrorCode: 'DEBUGG_TUNNEL_UNKNOWN',
+                detail: 'no live debugg tunnel session in this process for this hostname',
+                elapsedMs: elapsed(),
+            },
+        };
+    }
+    let probeResult;
+    try {
+        probeResult = await probe(probePathOf(tunnelUrl), { timeoutMs });
+    }
+    catch (err) {
+        // The probe API's contract is that it never throws. Belt and braces: a
+        // probe we could not run is not evidence of a fault.
+        return {
+            retryable: true,
+            result: {
+                healthy: false,
+                code: 'NETWORK_ERROR',
+                detail: err instanceof Error ? err.message : String(err),
+                elapsedMs: elapsed(),
+            },
+        };
+    }
+    const { status, marker, error } = probeResult;
+    if (marker) {
+        const notFound = ENDPOINT_NOT_FOUND_CODES.has(marker);
+        return {
+            retryable: notFound,
+            result: {
+                healthy: false,
+                status,
+                code: 'NGROK_ERROR',
+                ngrokErrorCode: marker,
+                detail: notFound
+                    ? `the tunnel server returned ${marker} — no client is connected for this tunnel`
+                    : `the tunnel server returned ${marker} — tunnel established but traffic could not reach the dev server`,
+                elapsedMs: elapsed(),
+            },
+        };
+    }
+    if (status !== undefined) {
+        if (status === 502 || status === 504) {
+            return {
+                retryable: false,
+                result: {
+                    healthy: false,
+                    status,
+                    code: 'BAD_GATEWAY',
+                    detail: `tunnel returned ${status} without an error marker — gateway is rejecting upstream`,
+                    elapsedMs: elapsed(),
+                },
+            };
+        }
+        // Any other status means traffic reached the dev server, which is healthy
+        // from the TUNNEL's point of view. A user's own 404 is a user concern.
+        return { retryable: false, result: { healthy: true, status, elapsedMs: elapsed() } };
+    }
+    if (error === 'TIMEOUT') {
+        // Not retried, for the same reason the HTTP path does not: a hanging
+        // tunnel must not cost three times the timeout budget.
+        return {
+            retryable: false,
+            result: {
+                healthy: false,
+                code: 'TIMEOUT',
+                detail: `tunnel health probe timed out after ${timeoutMs}ms`,
+                elapsedMs: elapsed(),
+            },
+        };
+    }
+    // Anything else (RESET, CLOSED, ...) is a connection-level failure. It is
+    // retried, because a session that is mid-reconnect reports exactly this and
+    // recovers within the ladder.
+    return {
+        retryable: true,
+        result: {
+            healthy: false,
+            code: 'NETWORK_ERROR',
+            detail: `tunnel control channel reported ${error ?? 'an unknown failure'}`,
+            elapsedMs: elapsed(),
+        },
+    };
+}
+/** The path (with search) a probe should request, defaulting to root. */
+function probePathOf(tunnelUrl) {
+    try {
+        const url = new URL(tunnelUrl);
+        return `${url.pathname}${url.search}` || '/';
+    }
+    catch {
+        return '/';
+    }
+}
 // ─ helpers ───────────────────────────────────────────────────────────────────
 async function readCapped(res, maxBytes) {
     if (!res.body)
@@ -375,8 +508,32 @@ async function readCapped(res, maxBytes) {
     }
     return out;
 }
+/**
+ * The debugg tunnel server's error markers, spelled out rather than matched by
+ * a `DEBUGG_TUNNEL_[A-Z_]+` pattern.
+ *
+ * A pattern would also match this repo's own `DEBUGG_TUNNEL_FAULT_MODE` env var
+ * (services/ngrok/tunnelFaultInjection.ts). This function is used on RUN
+ * EVIDENCE as well as on response bodies (testPageChangesHandler's
+ * findNgrokErrorMarker), so a log line mentioning that variable would otherwise
+ * be read as proof that the browser hit our error page, and a genuine UI
+ * failure would be reclassified as an infrastructure fault.
+ */
+const DEBUGG_TUNNEL_MARKERS = Object.freeze([
+    'DEBUGG_TUNNEL_OFFLINE',
+    'DEBUGG_TUNNEL_UNKNOWN',
+    'DEBUGG_TUNNEL_UPSTREAM_REFUSED',
+]);
+const MARKER_PATTERN = new RegExp(`ERR_NGROK_\\d+|${DEBUGG_TUNNEL_MARKERS.join('|')}`);
+/**
+ * The stable error marker a tunnel put in front of the user's app, from either
+ * transport: ngrok's `ERR_NGROK_*` or the debugg server's `DEBUGG_TUNNEL_*`.
+ *
+ * Name kept (and with it `TunnelHealthProbeResult.ngrokErrorCode` and
+ * `code: 'NGROK_ERROR'`) because handlers echo these into tool output;
+ * renaming them is part of deleting ngrok, not of adding a transport.
+ */
 export function extractNgrokErrorCode(body) {
-    // ngrok error pages surface codes like "ERR_NGROK_8012", "ERR_NGROK_3200", etc.
-    const match = body.match(/ERR_NGROK_\d+/);
+    const match = body.match(MARKER_PATTERN);
     return match ? match[0] : undefined;
 }

package/dist/utils/tunnelContext.js

@@ -61,12 +61,15 @@ export function findExistingTunnel(ctx) {
  * @param tunnelId  - ID to use as the ngrok subdomain (only takes effect the
  *                    first time this session creates a tunnel)
  * @param keyId     - Backend key ID; stored on the tunnel so it is revoked on stop
- * @param revokeKey - Callback that revokes the backend key (called when tunnel stops)
+ * @param revokeKey - Callback that revokes the backend tunnel (called when tunnel stops)
+ * @param selection - The provision response's transport fields. Omitted means
+ *                    ngrok, which is what an old backend implies, so every
+ *                    existing caller keeps its meaning.
  */
-export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey) {
+export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey, selection) {
     if (!ctx.isLocalhost)
         return ctx;
-    const info = await tunnelManager.ensureSessionTunnel(getSessionKey(), tunnelKey, tunnelId, keyId, revokeKey);
+    const info = await tunnelManager.ensureSessionTunnel(getSessionKey(), tunnelKey, tunnelId, keyId, revokeKey, selection);
     return { ...ctx, tunnelId: info.tunnelId, targetUrl: retargetTunnelUrl(info.tunnelUrl, ctx.originalUrl) };
 }
 /**

package/dist/utils/tunnelDisposition.js

@@ -72,7 +72,22 @@ const logger = new Logger({ module: 'tunnelDisposition' });
  * a "frozen" Set still succeeds silently. Freezing the array is a real runtime
  * guarantee; the lookup Set is derived from it and kept private.
  */
-const ENDPOINT_GONE_CODES = Object.freeze(['ERR_NGROK_3200']);
+const ENDPOINT_GONE_CODES = Object.freeze([
+    'ERR_NGROK_3200',
+    // The debugg tunnel server's equivalents (bead debugg_ai_mcp-xkoh.1.2 §10).
+    // Both are served BY THE EDGE ABOUT A HOSTNAME IT DOES NOT ROUTE, which is
+    // the inclusion criterion above:
+    //   DEBUGG_TUNNEL_OFFLINE — no client is connected. Confirmed across
+    //     probeTunnelHealth's retry ladder before it gets here, because the
+    //     server renders it after a 5s grace window that a slow reconnect can
+    //     outlast.
+    //   DEBUGG_TUNNEL_UNKNOWN — unknown or revoked tunnel id. Definitive.
+    // DEBUGG_TUNNEL_UPSTREAM_REFUSED is deliberately absent: like ERR_NGROK_8012
+    // it means the TUNNEL served us that page and is alive, while the user's dev
+    // server is what refused.
+    'DEBUGG_TUNNEL_OFFLINE',
+    'DEBUGG_TUNNEL_UNKNOWN',
+]);
 const ENDPOINT_GONE_LOOKUP = new Set(ENDPOINT_GONE_CODES);
 /** The allowlist, as an immutable list. Read-only by construction. */
 export const ENDPOINT_GONE_NGROK_CODES = ENDPOINT_GONE_CODES;

package/dist/utils/tunnelDomains.js

@@ -0,0 +1,113 @@
+/**
+ * The hostnames a tunnel can live on, and which transport serves each one.
+ *
+ * During the migration a single MCP process can hold an ngrok tunnel and a
+ * debugg tunnel at the same time, so every place that recognises a tunnel
+ * hostname has to know both. The one that matters to users is
+ * `replaceTunnelUrls`: it is what keeps a tunnel hostname out of every tool
+ * response, so a domain it does not know is a URL that leaks to the caller.
+ *
+ * A provision response may name a domain we do not ship (the backend moving
+ * `tunnel.debugg.ai` elsewhere, or a staging host), so domains can be
+ * registered at runtime — that is what lets the server move without an MCP
+ * release, the same reasoning as `relayUrl`.
+ *
+ * Imports NOTHING, deliberately: utils/urlParser.ts, utils/localReachability.ts
+ * and services/ngrok/tunnelManager.ts all depend on it, and it must never be
+ * the module that creates a cycle.
+ */
+const BUILT_IN_DOMAINS = Object.freeze([
+    { domain: 'ngrok.debugg.ai', transport: 'ngrok' },
+    { domain: 'tunnel.debugg.ai', transport: 'debugg' },
+]);
+const domains = new Map(BUILT_IN_DOMAINS.map((d) => [d.domain, d.transport]));
+/**
+ * A tunnel domain must be a lowercase DNS name of at least THREE labels.
+ *
+ * The label count is a safety rule, not a style one: a registered domain
+ * becomes a rewrite target, so accepting `debugg.ai` would make
+ * `replaceTunnelUrls` rewrite every real product link in a backend response
+ * (`https://app.debugg.ai/runs/1`) into the caller's localhost origin.
+ */
+export function isValidTunnelDomain(domain) {
+    if (typeof domain !== 'string')
+        return false;
+    if (domain.length > 253)
+        return false;
+    const labels = domain.split('.');
+    if (labels.length < 3)
+        return false;
+    return labels.every((label) => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+}
+/**
+ * Teach this process about a tunnel domain. Idempotent, and safe to call on
+ * every provision. Returns false for a domain that fails validation, so a
+ * caller can turn that into an error rather than silently trusting it.
+ */
+export function registerTunnelDomain(domain, transport) {
+    if (!isValidTunnelDomain(domain))
+        return false;
+    domains.set(domain, transport);
+    return true;
+}
+/** Every known domain, built-in and registered. */
+export function knownTunnelDomains() {
+    return [...domains.entries()].map(([domain, transport]) => ({ domain, transport }));
+}
+/** The known domain a host sits under, or undefined. Accepts a host or a full URL. */
+export function tunnelDomainFor(hostOrUrl) {
+    const host = hostOf(hostOrUrl);
+    if (!host)
+        return undefined;
+    for (const [domain, transport] of domains) {
+        // A tunnel host is always `<label>.<domain>` — never the bare domain.
+        if (host.length > domain.length + 1 && host.endsWith(`.${domain}`)) {
+            return { domain, transport };
+        }
+    }
+    return undefined;
+}
+export function isTunnelHost(hostOrUrl) {
+    return tunnelDomainFor(hostOrUrl) !== undefined;
+}
+/** The tunnel id (the leftmost label) of a tunnel host, or null. */
+export function extractTunnelIdFromHost(hostOrUrl) {
+    const host = hostOf(hostOrUrl);
+    const info = host ? tunnelDomainFor(host) : undefined;
+    if (!host || !info)
+        return null;
+    const label = host.slice(0, host.length - info.domain.length - 1);
+    return label.includes('.') ? null : label;
+}
+/**
+ * `https?://<label>.<known domain>` as one alternation, for whole-string
+ * rewriting. Rebuilt per call because the set can grow at runtime; these are
+ * short lists and the callers are not hot loops.
+ */
+export function tunnelUrlPattern() {
+    const alternatives = [...domains.keys()].map(escapeRegExp).join('|');
+    return new RegExp(`https?:\\/\\/[^\\s/"']+\\.(?:${alternatives})`, 'g');
+}
+function hostOf(hostOrUrl) {
+    if (typeof hostOrUrl !== 'string' || hostOrUrl.length === 0)
+        return undefined;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(hostOrUrl)) {
+        try {
+            return new URL(hostOrUrl).hostname.toLowerCase();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // A bare host, possibly with a port.
+    return hostOrUrl.split('/')[0].split(':')[0].toLowerCase();
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Test hook: drop every runtime-registered domain, keeping the built-ins. */
+export function _resetTunnelDomainsForTests() {
+    domains.clear();
+    for (const { domain, transport } of BUILT_IN_DOMAINS)
+        domains.set(domain, transport);
+}

package/dist/utils/urlParser.js

@@ -2,6 +2,7 @@
  * URL Parser Utilities
  * Helper functions for parsing and validating URLs, specifically for detecting localhost URLs
  */
+import { tunnelUrlPattern } from './tunnelDomains.js';
 /**
  * Normalize a user-supplied URL string before validation.
  * Handles bare hostnames without a scheme (e.g. "localhost:3000" → "http://localhost:3000").
@@ -87,13 +88,18 @@ export function isLocalhostUrl(urlString) {
     }
 }
 /**
- * Replace ngrok tunnel URLs with the original localhost origin in any string/object.
+ * Replace tunnel URLs with the original localhost origin in any string/object.
  * Used to sanitize backend responses that contain internal tunnel URLs before
  * returning them to callers who only know the original localhost address.
+ *
+ * Covers EVERY known tunnel domain (utils/tunnelDomains.ts), not just ngrok's:
+ * during the migration one session can hold an ngrok tunnel and another a
+ * debugg tunnel, and a domain this does not know is a hostname that leaks to
+ * the caller.
  */
 export function replaceTunnelUrls(value, localhostOrigin) {
     if (typeof value === 'string') {
-        return value.replace(/https?:\/\/[^\s/"]+\.ngrok\.debugg\.ai/g, localhostOrigin.replace(/\/$/, ''));
+        return value.replace(tunnelUrlPattern(), localhostOrigin.replace(/\/$/, ''));
     }
     if (Array.isArray(value)) {
         return value.map(item => replaceTunnelUrls(item, localhostOrigin));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "4.2.2",
+  "version": "4.4.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -65,6 +65,7 @@
     "posthog-node": "^5.26.0",
     "uuid": "^11.1.0",
     "winston": "^3.15.0",
+    "ws": "^8.21.3",
     "zod": "^3.25.32"
   },
   "devDependencies": {
@@ -73,6 +74,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.24",
     "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.2.0",
     "jest": "^30.0.5",
     "jest-environment-jsdom": "^30.0.5",