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

package/dist/handlers/probePageHandler.js

@@ -18,7 +18,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
@@ -148,18 +148,12 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                                         elapsedMs: health.elapsedMs,
                                     },
                                 };
-                                if (tunneled.tunnelId) {
-                                    const deadPort = extractLocalhostPort(tunneled.originalUrl);
-                                    if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                        // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry
-                                        // so the next call re-provisions instead of re-borrowing the corpse
-                                        // (bead k34o) — plain stopTunnel leaves a borrowed entry to re-poison.
-                                        tunnelManager.markTunnelDead(deadPort, tunneled.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunneled.tunnelId}: ${err}`));
-                                    }
-                                    else {
-                                        tunnelManager.stopTunnel(tunneled.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${tunneled.tunnelId}: ${err}`));
-                                    }
-                                }
+                                // Evict ONLY on a code proving the endpoint is gone; every other
+                                // failure keeps the tunnel we are already paying for, since a
+                                // teardown+re-provision costs two billed hours and this probe
+                                // cannot tell a dead endpoint from a transient edge flake. See
+                                // utils/tunnelDisposition.ts for the allowlist and the evidence.
+                                disposeUnhealthyTunnel({ health, tunnelId: tunneled.tunnelId, originalUrl: tunneled.originalUrl });
                                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                             }
                         }

package/dist/handlers/runTestSuiteHandler.js

@@ -2,7 +2,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { buildContext, findExistingTunnel, ensureTunnel } from '../utils/tunnelContext.js';
@@ -82,9 +82,17 @@ export async function runTestSuiteHandler(input, _context) {
                         if (tunneled.targetUrl) {
                             const health = await probeTunnelHealth(tunneled.targetUrl);
                             if (!health.healthy) {
-                                if (tunneled.tunnelId) {
-                                    tunnelManager.stopTunnel(tunneled.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${tunneled.tunnelId}: ${err}`));
-                                }
+                                // Brought in line with the other three handlers, which this one never
+                                // was (it evicted on EVERY failure and never got bead k34o's shared-
+                                // registry eviction). Evict only on a code proving the endpoint is
+                                // gone: a transient edge flake must not cost two billed hours.
+                                // See utils/tunnelDisposition.ts.
+                                disposeUnhealthyTunnel({ health, tunnelId: tunneled.tunnelId, originalUrl: ctx.originalUrl });
+                                // Record the tunnel so the finally block's orphaned-key revoke can't
+                                // fire: the tunnel we just kept is authenticated with that key, and
+                                // revoking a live tunnel's credential would kill what we preserved.
+                                // (On the eviction branch markTunnelDead already revokes it.)
+                                tunnelId = tunneled.tunnelId;
                                 return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
                             }
                         }

package/dist/handlers/testPageChangesHandler.js

@@ -13,7 +13,7 @@ import { adaptVerdict, isEnvironmentDefault } from '../services/verdictAdapter.j
 import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth, extractNgrokErrorCode } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
@@ -276,21 +276,16 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                             },
                         };
                         logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
-                        // Tear down the broken tunnel so a subsequent call doesn't reuse it.
-                        if (ctx.tunnelId) {
-                            const deadPort = extractLocalhostPort(ctx.originalUrl);
-                            if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry
-                                // so the next call re-provisions instead of re-borrowing the corpse.
-                                // Plain stopTunnel leaves a borrowed entry to re-poison (bead k34o).
-                                tunnelManager.markTunnelDead(deadPort, ctx.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                            else {
-                                tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                        }
-                        // keyId is consumed by stopTunnel's revoke path; clear so the
-                        // outer finally block doesn't double-revoke.
+                        // Evict ONLY on a code proving the endpoint is gone; every other
+                        // failure keeps the tunnel we are already paying for, because a
+                        // teardown+re-provision costs two billed hours and this probe cannot
+                        // tell a dead endpoint from a transient edge flake. See
+                        // utils/tunnelDisposition.ts for the allowlist and the evidence.
+                        disposeUnhealthyTunnel({ health, tunnelId: ctx.tunnelId, originalUrl: ctx.originalUrl });
+                        // Don't revoke the key on either branch: if we evicted, markTunnelDead's
+                        // owned path already revokes it; if we kept the tunnel, the key is that
+                        // live tunnel's own credential and revoking it would kill what we just
+                        // decided to preserve.
                         keyId = undefined;
                         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                     }

package/dist/handlers/triggerCrawlHandler.js

@@ -15,7 +15,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
@@ -138,18 +138,15 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
                             },
                         };
                         logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
-                        if (ctx.tunnelId) {
-                            const deadPort = extractLocalhostPort(ctx.originalUrl);
-                            if (health.ngrokErrorCode && typeof deadPort === 'number') {
-                                // Tunnel-level dead (ERR_NGROK_*): evict the SHARED registry entry so
-                                // the next call re-provisions instead of re-borrowing the corpse — plain
-                                // stopTunnel leaves a borrowed entry to re-poison (bead k34o).
-                                tunnelManager.markTunnelDead(deadPort, ctx.tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                            else {
-                                tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
-                            }
-                        }
+                        // Evict ONLY on a code proving the endpoint is gone; every other failure
+                        // keeps the tunnel we are already paying for, because a teardown+
+                        // re-provision costs two billed hours and this probe cannot tell a dead
+                        // endpoint from a transient edge flake. See utils/tunnelDisposition.ts.
+                        disposeUnhealthyTunnel({ health, tunnelId: ctx.tunnelId, originalUrl: ctx.originalUrl });
+                        // Don't revoke the key on either branch: if we evicted, markTunnelDead's
+                        // owned path already revokes it; if we kept the tunnel, the key is that
+                        // live tunnel's own credential and revoking it would kill what we just
+                        // decided to preserve.
                         keyId = undefined;
                         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                     }

package/dist/services/ngrok/ngrokAgentInspector.js

@@ -0,0 +1,210 @@
+/**
+ * Local ngrok agent inspector (bead lc62).
+ *
+ * Every ngrok agent process serves a local inspection API on 127.0.0.1:4040,
+ * incrementing to 4041, 4042, ... when the port is taken. `GET /api/tunnels`
+ * answers with the tunnels THAT AGENT currently has open:
+ *
+ *   {"tunnels":[{"public_url":"https://x.ngrok.debugg.ai",
+ *                "config":{"addr":"http://127.0.0.1:3011"}}],"uri":"/api/tunnels"}
+ *
+ * This is the only free, honest source of tunnel liveness we have. It is
+ * loopback: no DNS, no TLS, no ngrok edge, no undici, and — critically — no
+ * request to the tunnel's PUBLIC url. Probing the public url for a reuse
+ * decision is the k6yq / z15n / kmzb failure class: the edge answers undici
+ * over HTTP/2 and the response is lost to a concurrent GOAWAY, so a live tunnel
+ * reads as dead and gets replaced for two billed hours.
+ *
+ * ── The safety property, and why it is structural rather than a policy ──
+ *
+ * A tunnel MISSING from this API is not proof it is gone: the agent that owns
+ * it may be on a port we did not scan, or may not be answering. Only a
+ * REACHABLE agent that does not list a tunnel is evidence, and even that is
+ * scoped to that one agent.
+ *
+ * Rather than encode that asymmetry as a tri-state ("live" / "gone" /
+ * "unknown") that some future caller could mishandle, the inspector returns
+ * only what it POSITIVELY OBSERVED, and TunnelManager uses it in an
+ * ADD-ONLY way: reconciliation can create or refresh a registry entry, never
+ * delete one. An unreachable agent therefore contributes an empty list and
+ * changes nothing versus today's behaviour, and no failure of this module can
+ * ever cost a re-provision. That is a guarantee about the shape of the data
+ * flow, not a rule someone has to remember.
+ *
+ * Adoption is filtered to `*.ngrok.debugg.ai`. A developer's own unrelated
+ * ngrok tunnels share this agent API and must never be touched by us.
+ */
+import { request as httpRequest } from 'node:http';
+import { Logger } from '../../utils/logger.js';
+import { getFaultModeFromEnv } from './tunnelFaultInjection.js';
+const logger = new Logger({ module: 'ngrokAgentInspector' });
+/** Only tunnels on this suffix are ours to adopt. */
+const OWNED_TUNNEL_SUFFIX = '.ngrok.debugg.ai';
+/** ngrok's web-inspector base port, and how far it walks when 4040 is busy. */
+const FIRST_INSPECTOR_PORT = 4040;
+const INSPECTOR_PORT_COUNT = 10;
+/**
+ * Parse one agent's `/api/tunnels` body into the tunnels we are allowed to own.
+ *
+ * Tolerant by construction — every unexpected shape drops the entry rather than
+ * throwing, because a parse failure must degrade to "learned nothing".
+ *
+ * ngrok reports the same tunnel more than once when it exposes several protos,
+ * so results are de-duplicated by tunnelId; first hostname wins.
+ */
+export function parseAgentTunnels(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return [];
+    }
+    const raw = parsed?.tunnels;
+    if (!Array.isArray(raw))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const item of raw) {
+        const publicUrl = item?.public_url;
+        const addr = item?.config?.addr;
+        if (typeof publicUrl !== 'string' || typeof addr !== 'string')
+            continue;
+        const tunnelId = tunnelIdFromPublicUrl(publicUrl);
+        if (!tunnelId || seen.has(tunnelId))
+            continue;
+        const port = portFromAgentAddr(addr);
+        if (port === undefined)
+            continue;
+        seen.add(tunnelId);
+        out.push({ tunnelId, publicUrl, port });
+    }
+    return out;
+}
+/**
+ * Subdomain of a `*.ngrok.debugg.ai` public url, or undefined for anything
+ * else — including a developer's personal ngrok tunnels, which share this
+ * agent API and are none of our business.
+ */
+function tunnelIdFromPublicUrl(publicUrl) {
+    let host;
+    try {
+        host = new URL(publicUrl).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    if (!host.endsWith(OWNED_TUNNEL_SUFFIX))
+        return undefined;
+    const sub = host.slice(0, -OWNED_TUNNEL_SUFFIX.length);
+    // A bare or multi-label subdomain is not a tunnelId we minted.
+    return sub && !sub.includes('.') ? sub : undefined;
+}
+/**
+ * Local port out of an agent `config.addr`, which ngrok reports in several
+ * shapes depending on how connect() was called: `http://127.0.0.1:3011`,
+ * `https://localhost:3443`, or a bare `localhost:3011`.
+ */
+export function portFromAgentAddr(addr) {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(addr) ? addr : `tcp://${addr}`;
+    try {
+        const port = new URL(withScheme).port;
+        if (port) {
+            const n = Number(port);
+            return Number.isInteger(n) && n > 0 && n <= 65535 ? n : undefined;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return undefined;
+}
+/**
+ * GET one agent's /api/tunnels over loopback HTTP/1.1.
+ *
+ * `agent: false` so the socket is closed rather than pooled — this runs once
+ * per process and must not leave a keep-alive handle behind.
+ */
+function fetchAgentTunnelsOverHttp(port, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const req = httpRequest({ host: '127.0.0.1', port, path: '/api/tunnels', method: 'GET', agent: false, timeout: timeoutMs }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return done(undefined);
+            }
+            let body = '';
+            res.setEncoding('utf8');
+            // 256KB ceiling: something answering on 4040 that is not an ngrok agent
+            // must not be able to stream us out of memory.
+            res.on('data', (chunk) => {
+                if (body.length < 262144)
+                    body += chunk;
+            });
+            res.on('end', () => done(body));
+            res.on('error', () => done(undefined));
+        });
+        req.on('timeout', () => { req.destroy(); done(undefined); });
+        // Nothing is listening on most of these ports; ECONNREFUSED is the norm.
+        req.on('error', () => done(undefined));
+        req.end();
+    });
+}
+/**
+ * Scans the local agents. Ports are probed in parallel — nearly all of them
+ * refuse instantly, so the wall cost is one timeout at worst.
+ */
+export function createLocalAgentInspector(opts = {}) {
+    const ports = opts.ports ?? Array.from({ length: INSPECTOR_PORT_COUNT }, (_, i) => FIRST_INSPECTOR_PORT + i);
+    const timeoutMs = opts.timeoutMs ?? 500;
+    const fetchOne = opts.fetchAgentTunnels ?? fetchAgentTunnelsOverHttp;
+    return {
+        async listLiveTunnels() {
+            const faults = opts.faultMode !== undefined ? opts.faultMode : getFaultModeFromEnv();
+            if (faults?.inspectorUnreachable) {
+                logger.debug('[fault-inject] ngrok agent inspector forced unreachable');
+                return [];
+            }
+            if (faults?.inspectorAdoptPort !== undefined) {
+                const port = faults.inspectorAdoptPort;
+                logger.debug(`[fault-inject] ngrok agent inspector reporting a synthetic tunnel on port ${port}`);
+                return [{
+                        tunnelId: `fault-adopt-${port}`,
+                        publicUrl: `https://fault-adopt-${port}${OWNED_TUNNEL_SUFFIX}`,
+                        port,
+                    }];
+            }
+            const bodies = await Promise.all(ports.map((port) => fetchOne(port, timeoutMs).catch(() => undefined)));
+            const seen = new Set();
+            const found = [];
+            for (const body of bodies) {
+                if (!body)
+                    continue;
+                for (const tunnel of parseAgentTunnels(body)) {
+                    if (seen.has(tunnel.tunnelId))
+                        continue;
+                    seen.add(tunnel.tunnelId);
+                    found.push(tunnel);
+                }
+            }
+            return found;
+        },
+    };
+}
+/** Learns nothing, ever. The default under NODE_ENV=test. */
+export const noopInspector = {
+    listLiveTunnels: async () => [],
+};
+/**
+ * Mirrors getDefaultRegistry(): tests get the inert inspector so no unit test
+ * can reach the network, production gets the real loopback scan.
+ */
+export function getDefaultInspector() {
+    return process.env.NODE_ENV === 'test' ? noopInspector : createLocalAgentInspector();
+}

package/dist/services/ngrok/tunnelFaultInjection.js

@@ -6,20 +6,27 @@
  *   - DEBUGG_TUNNEL_FAULT_MODE env var explicitly set
  *
  * Modes (comma-separated, parseable by parseFaultMode):
- *   fail-connect-N:<count>     — fail the first <count> ngrok.connect() attempts
+ *   fail-connect-N:<count>      — fail the first <count> ngrok.connect() attempts
  *   empty-url-N:<count>         — return empty URL from first <count> connect() attempts
  *   delay-connect:<ms>          — sleep <ms> before each connect() call
+ *   inspector-unreachable:1     — the local ngrok agent inspector observes nothing
+ *                                 (bead lc62: proves reconciliation is add-only, i.e.
+ *                                 a blind inspector cannot cost a re-provision)
+ *   inspector-adopt:<port>      — the inspector reports one synthetic live tunnel on
+ *                                 <port>, exercising re-adoption end to end without
+ *                                 provisioning a real, billable tunnel
  *
  * Examples:
  *   DEBUGG_TUNNEL_FAULT_MODE=fail-connect-N:2
  *   DEBUGG_TUNNEL_FAULT_MODE=delay-connect:2000,fail-connect-N:1
+ *   DEBUGG_TUNNEL_FAULT_MODE=inspector-adopt:3000
  */
 export function parseFaultMode(raw) {
     if (!raw)
         return null;
     const mode = {};
     for (const token of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
-        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect):(\d+)$/);
+        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect|inspector-unreachable|inspector-adopt):(\d+)$/);
         if (!m)
             continue;
         const [, name, valStr] = m;
@@ -30,6 +37,12 @@ export function parseFaultMode(raw) {
             mode.emptyUrlN = val;
         else if (name === 'delay-connect')
             mode.delayConnectMs = val;
+        // Value-less switch, but kept in the `name:<digits>` grammar so one regex
+        // covers every mode. Any non-zero value turns it on.
+        else if (name === 'inspector-unreachable')
+            mode.inspectorUnreachable = val !== 0;
+        else if (name === 'inspector-adopt')
+            mode.inspectorAdoptPort = val;
     }
     return Object.keys(mode).length > 0 ? mode : null;
 }