@debugg-ai/debugg-ai-mcp 2.0.3 → 2.1.0

package/CHANGELOG.md

@@ -7,12 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — tunnel fault-injection + trace harness for diagnosis
+
+- New `DEBUGG_TUNNEL_FAULT_MODE` env var (dev/test only — inert when `NODE_ENV=production`) lets developers force specific ngrok-side failures without mocking, to reproduce client-reported transient "Tunnel setup failed" incidents. Modes: `fail-connect-N:<count>`, `empty-url-N:<count>`, `delay-connect:<ms>`, combinable with commas. Bead `42g`.
+- Structured `TunnelTrace` captures timestamped lifecycle events per tunnel-create call (start, each connect attempt, fault inject, agent reset, backoff, success/fail). Dumped to WARN logs on any tunnel creation failure so real-world flakes get a post-mortem trail instead of an opaque error message.
+
 ### Fixed — tunnel provisioning flakiness surfaces as user-facing errors
 
 - `check_app_in_browser` / `trigger_crawl` now automatically retry transient tunnel-provision failures (5xx, 408, 429, network errors like ECONNRESET) with exponential backoff (500ms → 1500ms → 3000ms, 3 attempts). Previously a single ngrok/backend blip forced the caller to manually retry the tool call. Bead `7nx`.
+- **ngrok.connect() retry widened from 2 to 3 attempts** with 500ms / 1500ms backoff. A client still hit "Tunnel setup failed" after `7nx` shipped — the failure was in the ngrok-listener-bringup path, not the backend-provision path. Auth errors still fail fast. Bead `ixh`.
 - Tunnel-provision error messages now carry structured diagnostic context — HTTP status, ngrok error code, backend `x-request-id`, retryable flag — so users have something actionable to file bug reports against instead of opaque "Tunnel setup failed". Bead `5wz`.
 - 4xx auth/quota errors (401/403/404) fail fast without retry to avoid loops against a bad API key.
-- New posthog telemetry event `tunnel.provision_retry` fires per retry attempt with outcome, status, and diagnostic fields so flaky provision rates become measurable.
+- New posthog telemetry event `tunnel.provision_retry` fires per retry attempt with outcome, status, stage (`ngrok_connect` vs backend-provision), and diagnostic fields so flaky rates become measurable.
 
 ## [2.0.0] - 2026-04-23
 

package/dist/services/ngrok/tunnelFaultInjection.js

@@ -0,0 +1,115 @@
+/**
+ * Fault injection + trace collection for tunnel lifecycle debugging (bead 42g).
+ *
+ * This is a TEST/DEV harness. Activation requires BOTH:
+ *   - NODE_ENV !== 'production'
+ *   - 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
+ *   empty-url-N:<count>         — return empty URL from first <count> connect() attempts
+ *   delay-connect:<ms>          — sleep <ms> before each connect() call
+ *
+ * Examples:
+ *   DEBUGG_TUNNEL_FAULT_MODE=fail-connect-N:2
+ *   DEBUGG_TUNNEL_FAULT_MODE=delay-connect:2000,fail-connect-N:1
+ */
+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+)$/);
+        if (!m)
+            continue;
+        const [, name, valStr] = m;
+        const val = parseInt(valStr, 10);
+        if (name === 'fail-connect-N')
+            mode.failConnectN = val;
+        else if (name === 'empty-url-N')
+            mode.emptyUrlN = val;
+        else if (name === 'delay-connect')
+            mode.delayConnectMs = val;
+    }
+    return Object.keys(mode).length > 0 ? mode : null;
+}
+export function getFaultModeFromEnv() {
+    if (process.env.NODE_ENV === 'production')
+        return null;
+    return parseFaultMode(process.env.DEBUGG_TUNNEL_FAULT_MODE);
+}
+/**
+ * Per-call, mutable fault-injection state. Tracks remaining fault counts so
+ * a 'fail first N' mode applies to the first N attempts within one call, not
+ * forever.
+ */
+export class FaultInjector {
+    failConnectRemaining;
+    emptyUrlRemaining;
+    delayMs;
+    constructor(mode) {
+        this.failConnectRemaining = mode?.failConnectN ?? 0;
+        this.emptyUrlRemaining = mode?.emptyUrlN ?? 0;
+        this.delayMs = mode?.delayConnectMs ?? 0;
+    }
+    /** Returns true if this attempt should be forced to fail. Consumes the counter. */
+    shouldFailConnect() {
+        if (this.failConnectRemaining > 0) {
+            this.failConnectRemaining -= 1;
+            return true;
+        }
+        return false;
+    }
+    /** Returns true if this attempt should return an empty URL. Consumes the counter. */
+    shouldReturnEmptyUrl() {
+        if (this.emptyUrlRemaining > 0) {
+            this.emptyUrlRemaining -= 1;
+            return true;
+        }
+        return false;
+    }
+    delayMsForAttempt() {
+        return this.delayMs;
+    }
+    /** For diagnostic logging — what's left after in-flight consumption. */
+    snapshot() {
+        return {
+            failConnectRemaining: this.failConnectRemaining,
+            emptyUrlRemaining: this.emptyUrlRemaining,
+            delayMs: this.delayMs,
+        };
+    }
+}
+export class TunnelTrace {
+    startTime;
+    events = [];
+    constructor(startTime = Date.now()) {
+        this.startTime = startTime;
+    }
+    emit(event, context) {
+        const now = Date.now();
+        this.events.push({
+            timestamp: now,
+            elapsedMs: now - this.startTime,
+            event,
+            context,
+        });
+    }
+    toJSON() {
+        const last = this.events[this.events.length - 1];
+        return {
+            startTime: this.startTime,
+            durationMs: last ? last.elapsedMs : 0,
+            events: this.events,
+        };
+    }
+    /** Human-readable one-line-per-event dump, newest last. */
+    format() {
+        return this.events
+            .map((e) => {
+            const ctx = e.context ? ' ' + JSON.stringify(e.context) : '';
+            return `+${e.elapsedMs.toString().padStart(6)}ms  ${e.event}${ctx}`;
+        })
+            .join('\n');
+    }
+}

package/dist/services/ngrok/tunnelManager.js

@@ -20,6 +20,7 @@ import { Logger } from '../../utils/logger.js';
 import { Telemetry, TelemetryEvents } from '../../utils/telemetry.js';
 import { isLocalhostUrl, extractLocalhostPort, generateTunnelUrl } from '../../utils/urlParser.js';
 import { v4 as uuidv4 } from 'uuid';
+import { FaultInjector, TunnelTrace, getFaultModeFromEnv } from './tunnelFaultInjection.js';
 import { getDefaultRegistry, } from './tunnelRegistry.js';
 let ngrokModule = null;
 async function getNgrok() {
@@ -48,6 +49,12 @@ class TunnelManager {
     pendingTunnels = new Map();
     initialized = false;
     TUNNEL_TIMEOUT_MS = 55 * 60 * 1000;
+    /**
+     * Backoff schedule (ms) between ngrok.connect() retry attempts. Bead ixh.
+     * Exposed on the class so tests can override with short delays without
+     * changing the public API or depending on jest fake timers.
+     */
+    connectBackoffMs = [500, 1500];
     constructor(reg = getDefaultRegistry()) {
         this.reg = reg;
     }
@@ -266,37 +273,109 @@ class TunnelManager {
         else {
             localAddr = inDocker ? `${dockerHost}:${port}` : port;
         }
+        // Bead ixh: 3-attempt retry for ngrok.connect transient failures. Previously
+        // only retried ONCE (with agent reset), which is insufficient against real
+        // ngrok / network flakes (client-reported incident 2026-04-24).
+        // - Attempt 1: fresh connect
+        // - Attempt 2: after 500ms backoff, reset the ngrok agent module and retry
+        //   (existing "agent died" recovery path)
+        // - Attempt 3: after 1500ms backoff, retry with the already-reset agent
+        // Auth-token errors short-circuit at any attempt — no point looping.
+        const self = this;
+        // Bead 42g: fault injection + trace. Only active when NODE_ENV !== 'production'
+        // AND DEBUGG_TUNNEL_FAULT_MODE env var is set. Zero overhead when disabled.
+        const faultMode = getFaultModeFromEnv();
+        const faults = new FaultInjector(faultMode);
+        const trace = new TunnelTrace();
+        trace.emit('createTunnel.start', { port, tunnelId, hasFaultMode: !!faultMode });
         const connectWithRetry = async () => {
-            try {
-                const ngrok = await getNgrok();
-                const url = await ngrok.connect({
-                    proto: 'http',
-                    addr: localAddr,
-                    hostname: tunnelDomain,
-                    authtoken: authToken,
-                });
-                if (!url)
-                    throw new Error('ngrok.connect() returned empty URL');
-                return url;
-            }
-            catch (firstError) {
-                // The ngrok agent process may have died after a previous disconnect.
-                // Reset module state and retry once with a fresh agent.
-                logger.warn(`ngrok.connect() failed, retrying with fresh agent: ${firstError}`);
-                resetNgrokModule();
-                this.initialized = false;
-                await this.ensureInitialized();
-                const ngrok = await getNgrok();
-                const url = await ngrok.connect({
-                    proto: 'http',
-                    addr: localAddr,
-                    hostname: tunnelDomain,
-                    authtoken: authToken,
-                });
-                if (!url)
-                    throw new Error('ngrok.connect() returned empty URL after retry');
-                return url;
+            const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+            const BACKOFF_MS = self.connectBackoffMs; // bead ixh: test-overridable
+            const MAX_ATTEMPTS = BACKOFF_MS.length + 1; // N sleeps between N+1 attempts
+            const connectOpts = {
+                proto: 'http',
+                addr: localAddr,
+                hostname: tunnelDomain,
+                authtoken: authToken,
+            };
+            let lastError;
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                trace.emit('connect.attempt.start', { attempt });
+                // Optional fault-injected delay before each attempt.
+                const delayMs = faults.delayMsForAttempt();
+                if (delayMs > 0) {
+                    trace.emit('connect.fault.delay', { attempt, delayMs });
+                    await sleep(delayMs);
+                }
+                try {
+                    const ngrok = await getNgrok();
+                    // Fault-inject a synthetic failure BEFORE ngrok.connect runs so we
+                    // can simulate connect-layer failures without hitting the real API.
+                    if (faults.shouldFailConnect()) {
+                        trace.emit('connect.fault.inject', { attempt, mode: 'fail-connect-N' });
+                        throw new Error(`[fault-inject] synthetic connect failure (attempt ${attempt})`);
+                    }
+                    const url = faults.shouldReturnEmptyUrl() ? '' : await ngrok.connect(connectOpts);
+                    if (!url) {
+                        trace.emit('connect.attempt.empty-url', { attempt });
+                        throw new Error(`ngrok.connect() returned empty URL (attempt ${attempt})`);
+                    }
+                    trace.emit('connect.attempt.success', { attempt });
+                    if (attempt > 1) {
+                        Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                            attempt,
+                            outcome: 'success',
+                            stage: 'ngrok_connect',
+                        });
+                    }
+                    return url;
+                }
+                catch (err) {
+                    lastError = err;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    trace.emit('connect.attempt.fail', { attempt, message: msg.slice(0, 200) });
+                    // Auth-class errors are non-retryable — retrying with the same token
+                    // would loop. Let the outer catch classify the message.
+                    if (/authtoken|unauthorized|\b401\b|\b403\b/i.test(msg)) {
+                        trace.emit('connect.giving-up', { reason: 'auth-error' });
+                        Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                            attempt,
+                            outcome: 'giving-up',
+                            stage: 'ngrok_connect',
+                            reason: 'auth-error',
+                        });
+                        throw err;
+                    }
+                    const isLastAttempt = attempt >= MAX_ATTEMPTS;
+                    Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                        attempt,
+                        outcome: isLastAttempt ? 'giving-up' : 'will-retry',
+                        stage: 'ngrok_connect',
+                    });
+                    if (isLastAttempt) {
+                        trace.emit('connect.giving-up', { reason: 'max-attempts' });
+                        throw err;
+                    }
+                    // Between attempt 1→2, do an agent-reset (covers the "agent died"
+                    // failure mode that used to be the only retried case). Between 2→3,
+                    // just wait — the reset already happened.
+                    if (attempt === 1) {
+                        logger.warn(`ngrok.connect() failed (attempt 1/${MAX_ATTEMPTS}), resetting agent: ${msg}`);
+                        trace.emit('agent.reset');
+                        resetNgrokModule();
+                        this.initialized = false;
+                        await this.ensureInitialized();
+                    }
+                    else {
+                        logger.warn(`ngrok.connect() failed (attempt ${attempt}/${MAX_ATTEMPTS}), will retry: ${msg}`);
+                    }
+                    const backoffMs = BACKOFF_MS[attempt - 1] ?? BACKOFF_MS[BACKOFF_MS.length - 1];
+                    trace.emit('connect.backoff', { attempt, backoffMs });
+                    await sleep(backoffMs);
+                }
             }
+            // Unreachable (loop always returns or throws), but satisfy TS
+            throw lastError ?? new Error('connectWithRetry: exhausted attempts without error');
         };
         try {
             const tunnelUrl = await connectWithRetry();
@@ -332,12 +411,18 @@ class TunnelManager {
                 // best-effort
             }
             this.resetTunnelTimer(tunnelInfo);
+            trace.emit('createTunnel.success', { tunnelId, publicUrl });
             logger.info(`Tunnel created: ${publicUrl} → localhost:${port}`);
             Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'created' });
             return tunnelInfo;
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : 'Unknown error';
+            trace.emit('createTunnel.fail', { message: msg.slice(0, 200) });
+            // Bead 42g: when the trace captured meaningful timing info, log it at
+            // WARN so operators can post-mortem. Keeping it out of the thrown error
+            // text so we don't leak internals to users.
+            logger.warn(`Tunnel lifecycle trace (fail path):\n${trace.format()}`);
             if (msg.includes('authtoken')) {
                 throw new Error(`Failed to create tunnel: invalid auth token. ${msg}`);
             }

package/package.json

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