@debugg-ai/debugg-ai-mcp 1.0.65 → 1.0.66

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### 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`.
+- 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.
+
 ## [1.0.64] - 2026-04-23
 
 > **⚠️ Semver violation — this is functionally a major release shipped as a patch.**

package/dist/handlers/testPageChangesHandler.js

@@ -8,6 +8,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
+import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
@@ -96,14 +97,15 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             else {
                 let tunnel;
                 try {
-                    tunnel = await client.tunnels.provision();
+                    tunnel = await client.tunnels.provisionWithRetry();
                 }
                 catch (provisionError) {
                     const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                    const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
                     throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
                         `The remote browser needs a secure tunnel to reach your local dev server. ` +
                         `Make sure your dev server is running on the specified port and try again. ` +
-                        `(Detail: ${msg})`);
+                        `(Detail: ${msg})${diag}`);
                 }
                 keyId = tunnel.keyId;
                 try {

package/dist/handlers/triggerCrawlHandler.js

@@ -14,6 +14,7 @@ import { config } from '../config/index.js';
 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 { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
 const TEMPLATE_KEYWORD = 'raw crawl';
@@ -61,13 +62,14 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
             else {
                 let tunnel;
                 try {
-                    tunnel = await client.tunnels.provision();
+                    tunnel = await client.tunnels.provisionWithRetry();
                 }
                 catch (provisionError) {
                     const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                    const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
                     throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
                         `The remote browser needs a secure tunnel to reach your local dev server. ` +
-                        `(Detail: ${msg})`);
+                        `(Detail: ${msg})${diag}`);
                 }
                 keyId = tunnel.keyId;
                 ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));

package/dist/services/tunnels.js

@@ -3,11 +3,97 @@
  * Provisions short-lived ngrok keys for MCP-managed tunnel setup.
  * Called before executeWorkflow so the tunnel URL is known before execution starts.
  */
-export const createTunnelsService = (tx) => ({
-    async provision(purpose = 'workflow') {
-        const response = await tx.post('api/v1/tunnels/', { purpose });
+import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+/**
+ * Typed error thrown by provision() when the backend/ngrok path fails.
+ * Carries diagnostic fields a retry wrapper (bead 7nx) can use to decide
+ * whether to retry, and that handler error messages can surface so users
+ * have something actionable to file bug reports against.
+ */
+export class TunnelProvisionError extends Error {
+    status;
+    code;
+    requestId;
+    networkCode;
+    retryable;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'TunnelProvisionError';
+        this.status = opts.status;
+        this.code = opts.code;
+        this.requestId = opts.requestId;
+        this.networkCode = opts.networkCode;
+        this.retryable = opts.retryable;
+    }
+    /**
+     * Stable one-line suffix for user-facing error messages.
+     * Example: '(status: 503, request-id: abc123, retryable)' or '(network: ECONNRESET, retryable)'.
+     */
+    diagnosticSuffix() {
+        const parts = [];
+        if (this.status != null)
+            parts.push(`status: ${this.status}`);
+        if (this.code)
+            parts.push(`code: ${this.code}`);
+        if (this.requestId)
+            parts.push(`request-id: ${this.requestId}`);
+        if (this.networkCode)
+            parts.push(`network: ${this.networkCode}`);
+        parts.push(this.retryable ? 'retryable' : 'not-retryable');
+        return `(${parts.join(', ')})`;
+    }
+}
+/**
+ * Classify an axios-interceptor-rewritten error (or any thrown Error) into a
+ * TunnelProvisionError with retryable semantics. Called from provision().
+ *
+ * Retryable: 5xx, 408 (request timeout), 429 (rate limit), and any network
+ * error (no response received — ECONNRESET / ECONNREFUSED / timeout).
+ * Not retryable: 4xx other than 408/429 — those indicate auth/quota/input
+ * problems that won't self-heal on the same API key.
+ */
+export function classifyProvisionError(err) {
+    const e = err;
+    const message = e?.message ? String(e.message) : 'Tunnel provisioning failed';
+    const status = typeof e?.statusCode === 'number' ? e.statusCode : undefined;
+    const data = e?.responseData;
+    const code = data && typeof data === 'object' && typeof data.code === 'string' ? data.code : undefined;
+    const headers = e?.responseHeaders;
+    const requestId = headers && typeof headers === 'object'
+        ? ((headers['x-request-id'] || headers['X-Request-Id']) ?? undefined)
+        : undefined;
+    const networkCode = typeof e?.networkCode === 'string' ? e.networkCode : undefined;
+    let retryable;
+    if (status == null) {
+        retryable = true;
+    }
+    else if (status >= 500) {
+        retryable = true;
+    }
+    else if (status === 408 || status === 429) {
+        retryable = true;
+    }
+    else {
+        retryable = false;
+    }
+    return new TunnelProvisionError({ message, status, code, requestId, networkCode, retryable });
+}
+const DEFAULT_BACKOFF_MS = [500, 1500, 3000];
+const DEFAULT_MAX_ATTEMPTS = 3;
+export const createTunnelsService = (tx) => {
+    async function provision(purpose = 'workflow') {
+        let response;
+        try {
+            response = await tx.post('api/v1/tunnels/', { purpose });
+        }
+        catch (err) {
+            throw classifyProvisionError(err);
+        }
         if (!response?.tunnelId || !response?.tunnelKey) {
-            throw new Error('Tunnel provisioning failed: missing tunnelId or tunnelKey in response');
+            throw new TunnelProvisionError({
+                message: 'Tunnel provisioning returned a success response missing tunnelId or tunnelKey',
+                retryable: false,
+            });
         }
         return {
             tunnelId: response.tunnelId,
@@ -15,5 +101,48 @@ export const createTunnelsService = (tx) => ({
             keyId: response.keyId,
             expiresAt: response.expiresAt,
         };
-    },
-});
+    }
+    async function provisionWithRetry(opts = {}) {
+        const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        const backoff = opts.backoffMs ?? DEFAULT_BACKOFF_MS;
+        const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const result = await provision(opts.purpose);
+                if (attempt > 1) {
+                    Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                        attempt,
+                        outcome: 'success',
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const e = err instanceof TunnelProvisionError ? err : classifyProvisionError(err);
+                lastErr = e;
+                const isLastAttempt = attempt >= maxAttempts;
+                const willRetry = e.retryable && !isLastAttempt;
+                Telemetry.capture(TelemetryEvents.TUNNEL_PROVISION_RETRY, {
+                    attempt,
+                    outcome: willRetry ? 'will-retry' : 'giving-up',
+                    status: e.status,
+                    code: e.code,
+                    requestId: e.requestId,
+                    networkCode: e.networkCode,
+                    retryable: e.retryable,
+                });
+                if (!willRetry)
+                    throw e;
+                const waitMs = backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 0;
+                await sleep(waitMs);
+            }
+        }
+        // Unreachable in practice — loop always returns or throws.
+        throw lastErr ?? new TunnelProvisionError({
+            message: 'provisionWithRetry exhausted attempts without a classified error',
+            retryable: false,
+        });
+    }
+    return { provision, provisionWithRetry };
+};

package/dist/utils/axiosTransport.js

@@ -35,9 +35,14 @@ export class AxiosTransport {
                 const newErr = new Error(String(msg));
                 newErr.statusCode = err.response?.status;
                 newErr.responseData = data;
+                newErr.responseHeaders = err.response?.headers;
                 return Promise.reject(newErr);
             }
-            return Promise.reject(new Error(err.message || 'Unknown Axios error'));
+            // Network-class error (no response received) — preserve err.code (ECONNRESET, etc.)
+            const networkErr = new Error(err.message || 'Unknown Axios error');
+            if (err.code)
+                networkErr.networkCode = err.code;
+            return Promise.reject(networkErr);
         });
         // Request → snake_case
         this.axios.interceptors.request.use((cfg) => {

package/dist/utils/telemetry.js

@@ -53,5 +53,6 @@ export const TelemetryEvents = {
     TOOL_FAILED: 'tool.failed',
     WORKFLOW_EXECUTED: 'workflow.executed',
     TUNNEL_PROVISIONED: 'tunnel.provisioned',
+    TUNNEL_PROVISION_RETRY: 'tunnel.provision_retry',
     TUNNEL_STOPPED: 'tunnel.stopped',
 };

package/package.json

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