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

package/CHANGELOG.md

@@ -7,6 +7,11 @@ 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`.

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() {
@@ -281,6 +282,12 @@ class TunnelManager {
         // - 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 () => {
             const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
             const BACKOFF_MS = self.connectBackoffMs; // bead ixh: test-overridable
@@ -293,11 +300,27 @@ class TunnelManager {
             };
             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();
-                    const url = await ngrok.connect(connectOpts);
-                    if (!url)
+                    // 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,
@@ -310,9 +333,11 @@ class TunnelManager {
                 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 (line ~437) classify the message.
+                    // 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',
@@ -327,13 +352,16 @@ class TunnelManager {
                         outcome: isLastAttempt ? 'giving-up' : 'will-retry',
                         stage: 'ngrok_connect',
                     });
-                    if (isLastAttempt)
+                    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();
@@ -341,7 +369,9 @@ class TunnelManager {
                     else {
                         logger.warn(`ngrok.connect() failed (attempt ${attempt}/${MAX_ATTEMPTS}), will retry: ${msg}`);
                     }
-                    await sleep(BACKOFF_MS[attempt - 1] ?? BACKOFF_MS[BACKOFF_MS.length - 1]);
+                    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
@@ -381,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.4",
+  "version": "2.1.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {