@debugg-ai/debugg-ai-mcp 3.9.1 → 3.9.3

package/dist/utils/localReachability.js

@@ -14,6 +14,9 @@
  *     misconfigured ngrok, etc.)
  */
 import { createConnection } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { Readable } from 'node:stream';
 export async function probeLocalPort(port, opts = {}) {
     const host = opts.host ?? '127.0.0.1';
     const timeoutMs = opts.timeoutMs ?? 1500;
@@ -72,9 +75,134 @@ const TRANSIENT_CAUSE_CODES = new Set([
     'EAI_AGAIN', // DNS: temporary resolver failure
     'ECONNRESET', // edge dropped the connection mid-handshake
     'EPIPE',
-    'UND_ERR_SOCKET', // undici socket error — this is the GOAWAY case
+    // undici codes. Since bead kmzb the default probe transport is node:https,
+    // which reports the OS codes above instead — these stay for an injected
+    // fetchFn, and as the record of what the HTTP/2 path used to produce.
+    'UND_ERR_SOCKET',
     'UND_ERR_CONNECT_TIMEOUT',
 ]);
+/**
+ * ngrok codes meaning "the edge does not route this hostname".
+ *
+ * Kept here deliberately separate from tunnelDisposition's ENDPOINT_GONE
+ * allowlist even though they currently hold the same code: that list decides
+ * whether a verdict may DESTROY a tunnel, this one decides whether a verdict is
+ * worth double-checking first. A code could reasonably be on one and not the
+ * 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']);
+// ─ HTTP/1.1 probe transport (bead kmzb) ──────────────────────────────────────
+/**
+ * `fetch`-shaped GET that speaks HTTP/1.1, because the global fetch cannot.
+ *
+ * Measured against the ngrok edge on 2026-07-27, Node v26:
+ *
+ *   ALPN offer [h2, http/1.1] → edge selects h2
+ *   raw HTTP/2 GET of a hostname ngrok no longer routes
+ *       → 404 with ERR_NGROK_3200 in the body, AND a GOAWAY (code 0, NO_ERROR)
+ *         on the same connection
+ *   undici (global fetch) over that h2 connection
+ *       → TypeError: fetch failed / UND_ERR_SOCKET, 3/3 — the response is lost
+ *         to the concurrent GOAWAY and never surfaces
+ *   node:https (HTTP/1.1)
+ *       → 404 + ERR_NGROK_3200, 3/3
+ *
+ * So the edge was answering us the whole time and undici was dropping the
+ * answer. That is why `ngrokErrorCode` had never once been populated in
+ * production, which in turn made tunnelDisposition's ENDPOINT_GONE allowlist
+ * unreachable: every probe failure looked like a transient network error, and
+ * a genuinely dead endpoint could never be told apart from a flake. Speaking
+ * HTTP/1.1 makes the distinction observable again and re-activates that
+ * allowlist — so ERR_NGROK_3200 can once more evict a tunnel that is provably
+ * gone, while everything short of proof still keeps the tunnel we are paying
+ * for. It also removes the h2 GOAWAY that bead k6yq's retry ladder existed to
+ * paper over, leaving the ladder as a genuine safety net rather than a
+ * load-bearing workaround.
+ *
+ * Node's fetch offers no way to disable h2, hence a transport rather than an
+ * option. `http.ClientRequest` — which `https.request` returns — implements
+ * HTTP/1.x only, so this cannot regress into h2 no matter what a future Node
+ * negotiates by default. The seam is deliberately `typeof fetch` so every
+ * caller and test that injects `fetchFn` is unaffected.
+ */
+export const http1Fetch = async (input, init) => {
+    const url = new URL(typeof input === 'string' ? input : input.url ?? String(input));
+    const isPlainHttp = url.protocol === 'http:';
+    const signal = init?.signal ?? undefined;
+    const options = {
+        protocol: url.protocol,
+        host: url.hostname,
+        port: url.port || (isPlainHttp ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: (init?.method ?? 'GET').toUpperCase(),
+        headers: init?.headers ?? {},
+        // One-shot probe — do not leave a pooled keep-alive socket behind.
+        agent: false,
+    };
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        const onResponse = (res) => {
+            if (settled)
+                return;
+            settled = true;
+            const status = res.statusCode ?? 0;
+            // Response rejects a body on these statuses; they have none anyway.
+            const bodyless = status === 101 || status === 204 || status === 205 || status === 304;
+            if (bodyless)
+                res.resume();
+            resolve(new Response(bodyless ? null : Readable.toWeb(res), {
+                status,
+                headers: headersFrom(res.headers),
+            }));
+        };
+        const req = isPlainHttp
+            ? httpRequest(options, onResponse)
+            : httpsRequest(options, onResponse);
+        if (signal) {
+            if (signal.aborted) {
+                req.destroy();
+                return fail(abortError());
+            }
+            signal.addEventListener('abort', () => {
+                req.destroy();
+                fail(abortError());
+            }, { once: true });
+        }
+        req.on('error', fail);
+        req.end();
+    });
+};
+/** Matches what an aborted fetch throws, so probeOnce's TIMEOUT arm still fires. */
+function abortError() {
+    const err = new Error('The operation was aborted.');
+    err.name = 'AbortError';
+    return err;
+}
+/** node:http header bag → Headers, skipping the pseudo/array oddities. */
+function headersFrom(raw) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            try {
+                headers.append(key, v);
+            }
+            catch {
+                // A header Headers refuses (invalid name from a hostile server) is not
+                // worth failing a health probe over.
+            }
+        }
+    }
+    return headers;
+}
 /** undici hides the real error behind `TypeError: fetch failed` — dig it out. */
 function errorCodeOf(err) {
     return err?.cause?.code ?? err?.code;
@@ -113,7 +241,8 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
 }
 async function probeOnce(tunnelUrl, opts, started) {
     const timeoutMs = opts.timeoutMs ?? 5000;
-    const fetchImpl = opts.fetchFn ?? fetch;
+    // Bead kmzb: HTTP/1.1, not the global fetch — see http1Fetch.
+    const fetchImpl = opts.fetchFn ?? http1Fetch;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -129,18 +258,31 @@ async function probeOnce(tunnelUrl, opts, started) {
         // ngrok error pages are small; a full user app body is a waste.
         const bodyText = await readCapped(res, 4096);
         const ngrokErr = extractNgrokErrorCode(bodyText);
-        // 502/504 + ngrok error marker → ngrok couldn't reach our server.
-        // A RESPONSE is proof the edge is up: never retried, so bead 4bui's
+        // An ngrok error page. A RESPONSE is proof the edge is up, so these are
+        // returned as-is rather than retried into a false pass, and bead 4bui's
         // marker-driven reclassification keeps seeing the real verdict.
+        //
+        // One exception, and it exists only because bead kmzb made these codes
+        // reachable at all: ENDPOINT_NOT_FOUND is the single verdict that
+        // AUTHORISES A TEARDOWN (tunnelDisposition's allowlist), and the ngrok
+        // agent passes through a short window where it is briefly true — while a
+        // dropped session reconnects and re-announces the same hostname. Acting on
+        // one sample would kill a tunnel that was about to come back, at a cost of
+        // two billed hours. So this code alone is confirmed across the retry
+        // ladder: a reconnect resolves inside it, a genuinely deleted endpoint
+        // answers the same way every time and is still reported as gone.
         if (ngrokErr) {
+            const notFound = ENDPOINT_NOT_FOUND_CODES.has(ngrokErr);
             return {
-                retryable: false,
+                retryable: notFound,
                 result: {
                     healthy: false,
                     status: res.status,
                     code: 'NGROK_ERROR',
                     ngrokErrorCode: ngrokErr,
-                    detail: `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
+                    detail: notFound
+                        ? `ngrok returned ${ngrokErr} — the edge no longer routes this tunnel hostname`
+                        : `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
                     elapsedMs: Date.now() - started,
                 },
             };

package/dist/utils/tunnelDisposition.js

@@ -0,0 +1,128 @@
+/**
+ * What to do with a tunnel whose health probe just failed.
+ *
+ * ngrok bills a MINIMUM OF ONE HOUR PER TUNNEL, so tearing one down and standing
+ * a replacement up costs TWO billed hours. A teardown therefore has to be backed
+ * by proof that the tunnel is already gone — not by a probe result that a
+ * transient edge flake produces just as readily as a real death.
+ *
+ * All four tool handlers probe tunnel health before handing the URL to the remote
+ * browser, and all four used to gate eviction on `health.ngrokErrorCode` being
+ * set AT ALL, falling back to stopTunnel() otherwise. Both halves were wrong:
+ *
+ *   - `ngrokErrorCode` is not a verdict. ERR_NGROK_8012 means the tunnel is ALIVE
+ *     and its upstream refused the connection — the tunnel is literally what
+ *     served us that error. Evicting on it orphans a live, billing tunnel and
+ *     makes the next call provision a replacement: two billed hours spent on a
+ *     dev server that was the actual problem.
+ *   - the stopTunnel() fallback tore down an OWNED tunnel on ANY probe failure,
+ *     including the transient HTTP/2 GOAWAY the ngrok edge sends to undici
+ *     (bead k6yq — measured at roughly 1 run in 5 before the retry ladder landed,
+ *     and still reachable whenever that ladder exhausts).
+ *
+ * Hence an explicit allowlist of codes that prove the ENDPOINT ITSELF is gone.
+ * Everything else leaves both the tunnel and the shared registry entry completely
+ * untouched and just reports TunnelTrafficBlocked: the user fixes their dev
+ * server and the next call reuses the same tunnel for free.
+ *
+ * Bead kmzb, confirmed live on 2026-07-27: probeTunnelHealth cannot currently
+ * produce ANY ngrokErrorCode against this edge. `curl` and a raw node:https
+ * request both get `404 + ERR_NGROK_3200` from a hostname ngrok no longer routes,
+ * but undici's fetch negotiates HTTP/2 and the edge answers with a GOAWAY, which
+ * surfaces as UND_ERR_SOCKET / NETWORK_ERROR with no code at all. So in practice
+ * every probe failure takes the leave-it-alone branch today. The allowlist is the
+ * policy that governs the moment a code CAN be produced — whether that is kmzb
+ * forcing HTTP/1.1 for the probe, or a caller passing the marker recorded by a
+ * run's own evidence (bead 4bui, the one live-confirmed source of ERR_NGROK_*).
+ */
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { extractLocalhostPort } from './urlParser.js';
+import { Logger } from './logger.js';
+const logger = new Logger({ module: 'tunnelDisposition' });
+/**
+ * ngrok error codes that PROVE the endpoint no longer exists, so evicting it
+ * costs nothing and re-borrowing it costs everyone a failed run (bead k34o).
+ *
+ * Inclusion criterion — the code must be served BY THE EDGE ABOUT A HOSTNAME IT
+ * NO LONGER ROUTES, i.e. it is impossible to receive it from a tunnel that is
+ * still up. Anything describing the upstream, the agent, or the connection is a
+ * live tunnel reporting on something else, and must NOT be here.
+ *
+ * Verify a candidate before adding it — the check is free and creates no tunnel:
+ *   curl -s https://<random-uuid>.ngrok.debugg.ai/ | grep -o 'ERR_NGROK_[0-9]*'
+ * (use curl or node:https, NOT fetch — see the kmzb note above).
+ *
+ *   ERR_NGROK_3200 — "not found". Verified live 2026-07-27: a GET to a
+ *   nonexistent *.ngrok.debugg.ai host returns 404 with this code in the body.
+ *   The endpoint is definitively gone; nothing is billing for it.
+ *
+ * Deliberately EXCLUDED, and the sharpest case of all:
+ *
+ *   ERR_NGROK_8012 — the agent could not dial the upstream (connection refused).
+ *   The TUNNEL IS ALIVE; it is the thing that generated the error page. Evicting
+ *   on 8012 orphans a paid-for tunnel and buys a duplicate — two billed hours —
+ *   to work around a dev server that is down, bound to the wrong interface, or
+ *   still starting up. Leave it be; it will serve the very next request once the
+ *   user's server is back.
+ *
+ * This set is pinned by a test. Adding a code has to be a deliberate act with
+ * evidence behind it, not a silent default to teardown.
+ *
+ * The frozen ARRAY is the source of truth, not a frozen Set: Object.freeze does
+ * not make a Set immutable — its entries live in internal slots, so `.add()` on
+ * 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_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;
+/**
+ * True only when the code proves the endpoint is gone. Unset / unknown codes are
+ * NOT proof of anything, so they answer false: the default is always to keep the
+ * tunnel we are already paying for.
+ */
+export function isEndpointGone(ngrokErrorCode) {
+    return !!ngrokErrorCode && ENDPOINT_GONE_LOOKUP.has(ngrokErrorCode);
+}
+/**
+ * Decide — once, in one place — what an unhealthy tunnel health probe does to the
+ * tunnel. Called by every handler that probes, so the policy cannot drift between
+ * them (run_test_suite had already drifted: it evicted on every failure and never
+ * got bead k34o's shared-registry eviction at all).
+ *
+ * Endpoint proven gone  → markTunnelDead: for an owned tunnel that disconnects and
+ *                         revokes the key; for a BORROWED one it also evicts the
+ *                         shared registry entry, which plain stopTunnel leaves
+ *                         behind for every other session to re-borrow (bead k34o).
+ * Anything else         → nothing at all. The caller still returns
+ *                         TunnelTrafficBlocked, so the user is told; we simply do
+ *                         not spend two billed hours acting on a verdict this
+ *                         probe cannot actually deliver.
+ *
+ * Never throws and never awaits the eviction: a cleanup decision must not be able
+ * to fail or slow down the error response the caller is about to return.
+ */
+export function disposeUnhealthyTunnel(args) {
+    const { health, tunnelId, originalUrl } = args;
+    if (!tunnelId)
+        return;
+    if (!isEndpointGone(health.ngrokErrorCode)) {
+        logger.info(`Tunnel ${tunnelId} failed its health probe (${health.code}${health.ngrokErrorCode ? ` ${health.ngrokErrorCode}` : ''}) ` +
+            'but nothing proves the endpoint is gone — keeping it. Tearing down a live tunnel costs two billed hours ' +
+            '(1-hour minimum down, another up) and the next call reuses this one for free.');
+        return;
+    }
+    const port = extractLocalhostPort(originalUrl);
+    if (typeof port !== 'number') {
+        // markTunnelDead is keyed by port. Without one we cannot evict the shared
+        // entry safely, and a blind stopTunnel is exactly the teardown this module
+        // exists to prevent — so keep the tunnel and say why.
+        logger.warn(`Tunnel ${tunnelId} reported ${health.ngrokErrorCode} but no port could be parsed from ${originalUrl} — ` +
+            'leaving it in place rather than risking a teardown of a live tunnel.');
+        return;
+    }
+    logger.warn(`Tunnel ${tunnelId} on port ${port} reported ${health.ngrokErrorCode} — the endpoint is gone, evicting it ` +
+        'so no session re-borrows the corpse (bead k34o).');
+    tunnelManager.markTunnelDead(port, tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunnelId}: ${err}`));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "3.9.1",
+  "version": "3.9.3",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {