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

package/dist/utils/tunnelDisposition.js

@@ -1,70 +1,64 @@
 /**
  * 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.
+ * A teardown has to be backed by PROOF that the tunnel is already gone — not
+ * by a probe result that a transient flake produces just as readily as a real
+ * death. Tearing down a live tunnel is not free: the next call has to
+ * re-provision, re-handshake and re-point Caddy, and it does that while the
+ * user's actual problem (a dev server that is down, bound to the wrong
+ * interface, or still starting) is untouched. It converts "your app isn't
+ * answering" into "your app isn't answering AND your tunnel churned".
+ *
+ * (Under ngrok the same rule had a sharper edge — its minimum billing unit was
+ * one hour per tunnel, so a needless teardown cost two billed hours. We own
+ * the tunnel server now, so the cost is latency and churn rather than money.
+ * The policy is unchanged; only the size of the bill is.)
  *
  * 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:
+ * browser, and all four used to gate eviction on the error code 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
+ *   - an error code is not a verdict. UPSTREAM_REFUSED 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.
+ *     served us that error. Evicting on it orphans a working tunnel and makes
+ *     the next call provision a replacement, to work around 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).
+ *     including a transient connection-level flake (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_*).
+ * server and the next call reuses the same tunnel.
  */
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { tunnelManager } from '../services/tunnel/tunnelManager.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.
+ * Tunnel-server error markers that PROVE the endpoint no longer exists, so
+ * evicting it costs nothing and keeping it costs the next call a failed run.
  *
- * 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).
+ * Inclusion criterion — the marker must be served BY THE EDGE ABOUT A TUNNEL IT
+ * CANNOT ROUTE, i.e. it is impossible to receive it from a tunnel that is still
+ * up. Anything describing the upstream, the client, or the connection is a live
+ * tunnel reporting on something else, and must NOT be here.
  *
- *   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.
+ *   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.
  *
  * 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.
+ *   DEBUGG_TUNNEL_UPSTREAM_REFUSED — the client could not dial the local app.
+ *   The TUNNEL IS ALIVE; it is the thing that generated the error page.
+ *   Evicting on it throws away a working tunnel 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
+ * This set is pinned by a test. Adding a marker 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
@@ -73,31 +67,19 @@ const logger = new Logger({ module: 'tunnelDisposition' });
  * guarantee; the lookup Set is derived from it and kept private.
  */
 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;
+export const ENDPOINT_GONE_TUNNEL_CODES = ENDPOINT_GONE_CODES;
 /**
- * True only when the code proves the endpoint is gone. Unset / unknown codes are
+ * True only when the marker 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.
+ * tunnel we already have.
  */
-export function isEndpointGone(ngrokErrorCode) {
-    return !!ngrokErrorCode && ENDPOINT_GONE_LOOKUP.has(ngrokErrorCode);
+export function isEndpointGone(tunnelErrorCode) {
+    return !!tunnelErrorCode && ENDPOINT_GONE_LOOKUP.has(tunnelErrorCode);
 }
 /**
  * Decide — once, in one place — what an unhealthy tunnel health probe does to the
@@ -114,8 +96,8 @@ export function isEndpointGone(ngrokErrorCode) {
  *                         tunnel half retired along with cross-process borrowing.
  * 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.
+ *                         not tear down a tunnel 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.
@@ -124,12 +106,12 @@ 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.');
+    if (!isEndpointGone(health.tunnelErrorCode)) {
+        logger.info(`Tunnel ${tunnelId} failed its health probe (${health.code}${health.tunnelErrorCode ? ` ${health.tunnelErrorCode}` : ''}) ` +
+            'but nothing proves the endpoint is gone — keeping it. Tearing down a live tunnel makes the next ' +
+            'call re-provision and re-handshake for nothing, while the next call can reuse this one as is.');
         return;
     }
-    logger.warn(`Tunnel ${tunnelId} (${originalUrl}) reported ${health.ngrokErrorCode} — the endpoint is gone, evicting it.`);
+    logger.warn(`Tunnel ${tunnelId} (${originalUrl}) reported ${health.tunnelErrorCode} — the endpoint is gone, evicting it.`);
     tunnelManager.markTunnelDead(tunnelId).catch((err) => logger.warn(`Failed to evict dead tunnel ${tunnelId}: ${err}`));
 }

package/dist/utils/tunnelDomains.js

@@ -1,26 +1,35 @@
 /**
- * The hostnames a tunnel can live on, and which transport serves each one.
+ * The hostnames a tunnel URL can live on.
  *
- * 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.
+ * What this is FOR: `replaceTunnelUrls` reads this list to keep 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
+ * `tunnel.debugg.ai` elsewhere, or a local dev host), so domains can be
  * registered at runtime — that is what lets the server move without an MCP
  * release, the same reasoning as `relayUrl`.
  *
+ * ┌─ DO NOT DELETE `ngrok.debugg.ai` AS DEAD CODE ─────────────────────────────┐
+ * │ This client can no longer CREATE an ngrok tunnel — the ngrok transport was │
+ * │ deleted. `ngrok.debugg.ai` stays here purely as a REWRITE TARGET, because  │
+ * │ a backend response about a historical run (evidence, screenshots, an       │
+ * │ execution's stored targetUrl) can still carry one of those hostnames. It   │
+ * │ costs one entry in a list; removing it means those URLs leak to the caller │
+ * │ verbatim. Retire it when no stored run references it any more — bead       │
+ * │ debugg_ai_mcp-xkoh.6.6, which also drops the *.ngrok.debugg.ai DNS.        │
+ * │ Locked by __tests__/utils/tunnelDomains.test.ts.                           │
+ * └────────────────────────────────────────────────────────────────────────────┘
+ *
  * Imports NOTHING, deliberately: utils/urlParser.ts, utils/localReachability.ts
- * and services/ngrok/tunnelManager.ts all depend on it, and it must never be
+ * and services/tunnel/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]));
+const LIVE_DOMAIN = 'tunnel.debugg.ai';
+/** Rewrite-only. See the box above before touching this. */
+const LEGACY_DOMAINS = ['ngrok.debugg.ai'];
+const BUILT_IN_DOMAINS = Object.freeze([LIVE_DOMAIN, ...LEGACY_DOMAINS]);
+const domains = new Set(BUILT_IN_DOMAINS);
 /**
  * A tunnel domain must be a lowercase DNS name of at least THREE labels.
  *
@@ -44,25 +53,25 @@ export function isValidTunnelDomain(domain) {
  * 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) {
+export function registerTunnelDomain(domain) {
     if (!isValidTunnelDomain(domain))
         return false;
-    domains.set(domain, transport);
+    domains.add(domain);
     return true;
 }
 /** Every known domain, built-in and registered. */
 export function knownTunnelDomains() {
-    return [...domains.entries()].map(([domain, transport]) => ({ domain, transport }));
+    return [...domains].map((domain) => ({ domain }));
 }
 /** 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) {
+    for (const domain 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 { domain };
         }
     }
     return undefined;
@@ -85,7 +94,7 @@ export function extractTunnelIdFromHost(hostOrUrl) {
  * short lists and the callers are not hot loops.
  */
 export function tunnelUrlPattern() {
-    const alternatives = [...domains.keys()].map(escapeRegExp).join('|');
+    const alternatives = [...domains].map(escapeRegExp).join('|');
     return new RegExp(`https?:\\/\\/[^\\s/"']+\\.(?:${alternatives})`, 'g');
 }
 function hostOf(hostOrUrl) {
@@ -108,6 +117,6 @@ function escapeRegExp(value) {
 /** 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);
+    for (const domain of BUILT_IN_DOMAINS)
+        domains.add(domain);
 }

package/dist/utils/urlParser.js

@@ -92,10 +92,9 @@ export function isLocalhostUrl(urlString) {
  * 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.
+ * Covers EVERY known tunnel domain (utils/tunnelDomains.ts), including the
+ * retired `ngrok.debugg.ai` one a historical run's stored URLs still carry: a
+ * domain this does not know is a hostname that leaks to the caller.
  */
 export function replaceTunnelUrls(value, localhostOrigin) {
     if (typeof value === 'string') {
@@ -116,7 +115,7 @@ export function replaceTunnelUrls(value, localhostOrigin) {
 /**
  * Re-point a REUSED tunnel at the current caller's path (bead zmc9).
  *
- * A tunnel is origin-scoped: its `tunnelUrl` (scheme://host from ngrok) forwards
+ * A tunnel is origin-scoped: its `tunnelUrl` (scheme://host from the transport) forwards
  * every path. The path is request-scoped. On reuse we must compose the reused
  * tunnel's ORIGIN with THIS request's path/search/hash — never replay the
  * path-bearing `publicUrl` baked in by whichever call created the tunnel.
@@ -138,7 +137,7 @@ export function retargetTunnelUrl(tunnelOrigin, requestedUrl) {
 /**
  * Generate a tunneled URL for a localhost URL
  */
-export function generateTunnelUrl(originalUrl, tunnelId, tunnelDomain = 'ngrok.debugg.ai') {
+export function generateTunnelUrl(originalUrl, tunnelId, tunnelDomain) {
     try {
         const parsed = parseUrl(originalUrl);
         if (!parsed.isLocalhost) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "4.4.1",
+  "version": "5.0.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "lint": "eslint .",
-    "build": "tsc && shx chmod +x dist/index.js",
+    "build": "shx rm -rf dist && tsc && shx chmod +x dist/index.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
@@ -61,7 +61,6 @@
     "@radically-straightforward/caddy": "^2.0.12",
     "axios": "^1.9.0",
     "mkdirp": "^3.0.1",
-    "ngrok": "^5.0.0-beta.2",
     "posthog-node": "^5.26.0",
     "uuid": "^11.1.0",
     "winston": "^3.15.0",

package/dist/services/ngrok/error.js

@@ -1,3 +0,0 @@
-export function isError(error) {
-    return error instanceof Error;
-}

package/dist/services/ngrok/ngrokAgentInspector.js

@@ -1,210 +0,0 @@
-/**
- * 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/ngrokAgentSession.js

@@ -1,49 +0,0 @@
-/**
- * ngrok agent session bootstrap (bead pqgj).
- *
- * ngrok's connect() calls its internal getProcess() and then IMMEDIATELY asks
- * the agent to open a tunnel. But getProcess() resolves as soon as the agent
- * prints its local API address, which — measured live against agent v3.38.0 —
- * is ~293ms BEFORE the client session is established:
- *
- *   [ 110ms] msg="starting web service" addr=127.0.0.1:4043   <- getProcess resolves
- *   [ 403ms] msg="client session established"                 <- ~293ms later
- *
- * Tunnelling inside that window returns 503 "a successful ngrok tunnel session
- * has not yet been established". That 503 is retriable and ngrok retries it
- * internally — but connectRetry() pins opts.name on the first call and reuses
- * it, so its own retry collides with the tunnel record the 503 left behind:
- * 400 "invalid tunnel configuration — tunnel already exists". 400 is not
- * retriable, so it surfaces to us. That is bead pqgj's 100% attempt-1 failure.
- *
- * Fix: start the agent and wait for its session BEFORE anyone tunnels.
- * getProcess() memoizes on a module-level promise, so ngrok's own connect()
- * then reuses the very agent we started and never re-spawns it.
- *
- * getProcess is not in ngrok's package export map ({".": "./index.js"}), hence
- * the resolved deep require. It is isolated in this module so the reach into
- * another package's internals is explicit, greppable, and mockable — and so a
- * version bump that moves it fails HERE, loudly, instead of silently spawning
- * something unexpected. Callers treat a throw as "no pre-warm available" and
- * fall back to their connect retry ladder.
- */
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-/**
- * Spawn (or reuse) the ngrok agent, wiring the session callbacks.
- *
- * Resolves once the agent's local API is up — NOT once the session is live.
- * Callers await the session via `onStatusChange('connected')`.
- *
- * @throws if ngrok's internals cannot be reached (version bump, stubbed module).
- */
-export const startAgentSession = async (opts) => {
-    const require = createRequire(import.meta.url);
-    const ngrokEntry = require.resolve('ngrok');
-    const processModulePath = join(dirname(ngrokEntry), 'src', 'process.js');
-    const { getProcess } = require(processModulePath);
-    if (typeof getProcess !== 'function') {
-        throw new Error(`ngrok getProcess() not found at ${processModulePath}`);
-    }
-    await getProcess(opts);
-};

package/dist/services/ngrok/types.js

@@ -1 +0,0 @@
-export {};