@debugg-ai/debugg-ai-mcp 6.1.2 → 6.1.4

package/README.md

@@ -23,6 +23,30 @@ clear error on the first localhost-URL call, not a silent hang. Public-URL calls
 non-browser tool, and `test_suite {action:"run"}` (which uses its own dedicated tunnel and
 bypasses Caddy entirely) don't need it either way.
 
+## Testing a local app (no Tailscale, no port exposure)
+
+Start your app on localhost, then pass the `http://localhost:<port>` URL straight to the tool. The MCP
+opens its own DebuggAI tunnel (one per session, dialed through a local Caddy proxy) — do not expose the
+port with Tailscale, ngrok, or anything else, and do not rewrite the URL to a tunnel hostname yourself.
+
+```json
+probe_page            { "targets": [{ "url": "http://localhost:4040" }] }
+check_app_in_browser  { "url": "http://localhost:4040", "description": "Open the home page and confirm the hero renders" }
+```
+
+Verified 2026-11-10 against a Next.js dev server on `localhost:4040`: `probe_page` returned
+`statusCode 200`, title, 0 console errors, and every asset request resolved via the tunnel.
+Prerequisites: `DEBUGGAI_API_KEY` set for the MCP, the `caddy` binary available (see above), and the
+app actually listening (a dead port fails fast with `LocalServerUnreachable`). Several pages on the
+same port can share one `probe_page` call; mixing ports in one call works but runs serially.
+
+`TunnelTrafficBlocked` means the tunnel came up but the health probe through it got no valid response. First
+check you are on the latest MCP (`npx -y @debugg-ai/debugg-ai-mcp@latest`; a stale pinned version is the usual
+cause), then that your dev server answers a plain `curl http://127.0.0.1:<port>/` and does not reject unknown
+`Host` headers (tunnel requests carry the tunnel hostname; a gateway that routes by `Host` needs a catch-all).
+Verified 2026-11-10: servers bound to `127.0.0.1` only (IPv4 Caddy gateways on :4040 and :4043) probe fine via
+`http://localhost:<port>` and `http://127.0.0.1:<port>`.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json

package/dist/handlers/testPageChangesHandler.js

@@ -608,7 +608,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             // the response) must not POST a cancel for finished work. EXCEPTION: on a
             // poll-deadline timeout the execution may still be running backend-side,
             // so keep it cancellable.
-            if (!finalExecution.timedOut)
+            if (!finalExecution.timedOut && !finalExecution.stalled)
                 currentExecutionUuid = '';
             // Decide retry vs exit: only retry on documented transient signatures
             // AND while we still have budget. Otherwise break and surface whatever
@@ -617,7 +617,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 break;
             // A poll-deadline timeout (bead 56kd.3) is never retried — surface the
             // partial result instead of burning another 10 minutes.
-            if (finalExecution.timedOut)
+            if (finalExecution.timedOut || finalExecution.stalled)
                 break;
             if (!isTransientWorkflowError(finalExecution))
                 break;
@@ -641,6 +641,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             // real numbers from the deadline path, so the reason is a record of what
             // we observed rather than a fixed sentence
             pollTimeout: timedOut ? finalExecution.pollTimeout : undefined,
+            stalled: finalExecution.stalled ? finalExecution.stall : undefined,
         });
         const relayActionTrace = verdict.actionTrace;
         // Evaluation: the backend derives it from the SAME verdict as the headline

package/dist/services/verdictAdapter.js

@@ -150,6 +150,13 @@ export function credentialSubstitutions(logins, namedIdentities) {
         && typeof l.username === 'string' && l.username.trim() !== ''
         && !named.has(norm(l.username)));
 }
+/** Backend agent loop was never started: an internal init bug, not a verdict on the user's page. */
+const BRAIN_UNINITIALISED = /BrowserUseBrain\.initialize\(\)|must be called before decide_next_action/i;
+export function stalledReason(facts) {
+    const where = facts.executionUuid ? ` (execution ${facts.executionUuid})` : '';
+    const secs = typeof facts.elapsedMs === 'number' ? ` after ${Math.round(facts.elapsedMs / 1000)}s` : '';
+    return `The run never started its agent loop${secs} (0 steps taken)${where}. This is a backend/browser-session start-up failure, not a result about your page; retry, and if it repeats report this execution id.`;
+}
 /**
  * Map a workflow execution onto the MCP relay verdict. Never throws.
  */
@@ -166,8 +173,9 @@ export function adaptVerdict(execution, opts = {}) {
     const rawOutcome = opts.outcomeOverride ?? verdict?.outcome;
     const raw = typeof rawOutcome === 'string' ? rawOutcome.trim() : '';
     const isOurPollTimeout = opts.outcomeOverride === 'timeout';
+    const isStalled = !!opts.stalled;
     const backendReason = typeof verdict?.reason === 'string' && verdict.reason.trim() !== '' ? verdict.reason : null;
-    if (!isOurPollTimeout && !raw) {
+    if (!isOurPollTimeout && !isStalled && !raw) {
         // A run that never attempted a test (platform-98fv.16): no verdict, and the
         // backend's recorded reason, verbatim.
         if (verdict?.skipped === true) {
@@ -189,7 +197,7 @@ export function adaptVerdict(execution, opts = {}) {
     // error covers: the backend's own 'error'/'timeout', every retired non-answer
     // (inconclusive/unverified/unknown/abandoned), anything a newer backend
     // invents, and a verdict that never arrived.
-    const outcome = toUserFacingOutcome(raw);
+    const outcome = isStalled ? 'error' : toUserFacingOutcome(raw);
     const relay = { outcome };
     if (budget && typeof budget === 'object')
         relay.budget = budget;
@@ -202,13 +210,19 @@ export function adaptVerdict(execution, opts = {}) {
     // any reason we are holding came from a mid-flight poll — it describes a run
     // still in progress, not its result. Relaying it next to outcome='error'
     // would pair someone else's "looks good" with our failure.
-    if (isOurPollTimeout) {
+    if (isStalled) {
+        relay.reason = stalledReason({ executionUuid: execution?.uuid, ...opts.stalled });
+    }
+    else if (isOurPollTimeout) {
         relay.reason = pollTimeoutReason({
             executionUuid: execution?.uuid,
             lastStatus: execution?.status,
             ...(opts.pollTimeout ?? {}),
         });
     }
+    else if (backendReason && BRAIN_UNINITIALISED.test(backendReason)) {
+        relay.reason = `${stalledReason({ executionUuid: execution?.uuid, elapsedMs: execution?.durationMs ?? undefined })} Backend said: ${backendReason}`;
+    }
     else if (backendReason) {
         relay.reason = backendReason;
     }

package/dist/services/workflows.js

@@ -13,6 +13,15 @@ const POLL_INTERVAL_INITIAL_MS = 1000;
 const POLL_INTERVAL_MAX_MS = 5000;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
 const EXECUTION_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
+// A run that is still non-terminal with ZERO agent steps this long after we
+// started polling is not "slow", it is wedged (e.g. the backend brain never
+// initialised, so the agent loop never starts). Stop waiting and say so rather
+// than burning the full run budget. Override with DEBUGGAI_NO_PROGRESS_TIMEOUT_MS.
+const DEFAULT_NO_PROGRESS_TIMEOUT_MS = 4 * 60 * 1000;
+const noProgressTimeoutMs = () => {
+    const n = Number(process.env.DEBUGGAI_NO_PROGRESS_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_NO_PROGRESS_TIMEOUT_MS;
+};
 /**
  * Stable dispatch slugs for the three MCP browser workflows (bug clka /
  * bead 56kd.8). All three handlers pin to a STABLE slug so a backend
@@ -145,6 +154,24 @@ export const createWorkflowsService = (tx) => {
                 if (signal?.aborted) {
                     throw new Error(`Polling cancelled for execution ${executionUuid}`);
                 }
+                const hasSteps = (execution.state?.stepsTaken ?? 0) > 0 ||
+                    (execution.nodeExecutions ?? []).some(n => n.nodeType === 'brain.step');
+                if (!hasSteps && Date.now() - pollStart >= noProgressTimeoutMs()) {
+                    Telemetry.capture(TelemetryEvents.WORKFLOW_EXECUTED, {
+                        status: execution.status,
+                        success: false,
+                        outcome: 'stalled',
+                        stepsTaken: 0,
+                        durationMs: Date.now() - pollStart,
+                        pollCount,
+                        finalIntervalMs: intervalMs,
+                    });
+                    return {
+                        ...execution,
+                        stalled: true,
+                        stall: { elapsedMs: Date.now() - pollStart, pollCount },
+                    };
+                }
                 const sleepMs = intervalMs;
                 await new Promise((resolve, reject) => {
                     const timer = setTimeout(resolve, sleepMs);

package/dist/utils/localReachability.js

@@ -101,10 +101,13 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 5000;
     const started = Date.now();
     let last;
+    let allClosed = true;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         const { result, retryable } = await probeOverControlChannel(tunnelUrl, timeoutMs, started);
         if (!retryable)
             return result;
+        if (!result.detail?.endsWith(' CLOSED'))
+            allClosed = false;
         last = result;
         if (attempt < maxAttempts) {
             await sleep(backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 150);
@@ -112,6 +115,14 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
     }
     // Ladder exhausted on a transient error — the tunnel never came up. Report
     // it: "not ready" that never becomes ready IS unhealthy.
+    //
+    // A control channel CLOSED on every attempt means the tunnel has no live
+    // session at all (a reconnect that never lands, or the transport forgot the
+    // tunnel while the manager still holds it). It can never serve a request, so
+    // flag it for eviction — otherwise every later call reuses the corpse and
+    // fails identically until the MCP process restarts.
+    if (allClosed && last)
+        last.tunnelErrorCode = 'CONTROL_CHANNEL_CLOSED';
     return last;
 }
 // ─ Control-channel probe ─────────────────────────────────────────────────────

package/dist/utils/tunnelDisposition.js

@@ -69,6 +69,11 @@ const logger = new Logger({ module: 'tunnelDisposition' });
 const ENDPOINT_GONE_CODES = Object.freeze([
     'DEBUGG_TUNNEL_OFFLINE',
     'DEBUGG_TUNNEL_UNKNOWN',
+    // Client-side verdict, not a server marker: probeTunnelHealth saw the tunnel's
+    // own control channel CLOSED on every attempt of its ladder, i.e. there is no
+    // session left to carry traffic. Keeping it makes every later call fail the
+    // same way (the crochets build lead's "stuck at CLOSED" report).
+    'CONTROL_CHANNEL_CLOSED',
 ]);
 const ENDPOINT_GONE_LOOKUP = new Set(ENDPOINT_GONE_CODES);
 /** The allowlist, as an immutable list. Read-only by construction. */

package/package.json

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