@debugg-ai/debugg-ai-mcp 3.9.3 → 4.0.0

package/dist/handlers/runTestSuiteHandler.js

@@ -5,7 +5,8 @@ import { TunnelProvisionError } from '../services/tunnels.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
-import { buildContext, findExistingTunnel, ensureTunnel } from '../utils/tunnelContext.js';
+import { buildContext, sanitizeResponseUrls } from '../utils/tunnelContext.js';
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
 import { config } from '../config/index.js';
 import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
 const logger = new Logger({ module: 'runTestSuiteHandler' });
@@ -19,6 +20,13 @@ export async function runTestSuiteHandler(input, _context) {
     await client.init();
     let acquiredKeyId = null;
     let tunnelId;
+    // Used ONLY to scope the defensive sanitizeResponseUrls call below (bead
+    // debugg_ai_mcp-6cfv.7) — never fed into acquirePortRoute/PortLock. This
+    // handler is fire-and-forget (no poll loop, no bounded window to hold the
+    // shared session lock over — see the acquireDedicatedTunnel call below), so
+    // it deliberately does NOT go through findExistingTunnel/ensureTunnel/
+    // acquirePortRoute at all (§2.3's named, deliberate exception).
+    let sanitizeCtx;
     try {
         let suiteUuid = input.suiteUuid;
         if (!suiteUuid) {
@@ -51,68 +59,79 @@ export async function runTestSuiteHandler(input, _context) {
                     logger.info(`run_test_suite: dev mode — using localhost URL directly: ${input.targetUrl}`);
                 }
                 else {
-                    // Reuse an existing tunnel for this port if one is already active.
-                    const reused = findExistingTunnel(ctx);
-                    if (reused) {
-                        effectiveTargetUrl = reused.targetUrl ?? input.targetUrl;
-                        tunnelId = reused.tunnelId;
+                    // §2.3: run_test_suite is the ONE named, deliberate exception to
+                    // "one tunnel per session" — it is fire-and-forget (dispatches
+                    // client.runTestSuite() below and returns; the tests it triggers
+                    // keep using this tunnel on the BACKEND for possibly many more
+                    // minutes, entirely outside this process's poll loop, because
+                    // there IS no poll loop). Sharing the session's Caddy-routed tunnel
+                    // and its PortLock would give this handler no real protection —
+                    // the lock would release back to contention seconds after
+                    // triggering a suite that goes on to use the port for much longer.
+                    // So it gets its OWN tunnel, dialing ngrok directly, bypassing
+                    // Caddy/PortLock entirely (never deduped/reused — always fresh).
+                    let tunnel;
+                    try {
+                        tunnel = await client.tunnels.provisionWithRetry();
                     }
-                    else {
-                        // Provision a new tunnel.
-                        let tunnel;
-                        try {
-                            tunnel = await client.tunnels.provisionWithRetry();
-                        }
-                        catch (provisionError) {
-                            const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
-                            const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
-                            return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
-                        }
-                        acquiredKeyId = tunnel.keyId;
-                        let tunneled;
-                        try {
-                            tunneled = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
-                        }
-                        catch (tunnelError) {
-                            const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
-                            return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
-                        }
-                        // Health probe — catches ERR_NGROK_8012 and bind mismatches before
-                        // the remote agent wastes steps trying to reach the server.
-                        if (tunneled.targetUrl) {
-                            const health = await probeTunnelHealth(tunneled.targetUrl);
-                            if (!health.healthy) {
-                                // Brought in line with the other three handlers, which this one never
-                                // was (it evicted on EVERY failure and never got bead k34o's shared-
-                                // registry eviction). Evict only on a code proving the endpoint is
-                                // gone: a transient edge flake must not cost two billed hours.
-                                // See utils/tunnelDisposition.ts.
-                                disposeUnhealthyTunnel({ health, tunnelId: tunneled.tunnelId, originalUrl: ctx.originalUrl });
-                                // Record the tunnel so the finally block's orphaned-key revoke can't
-                                // fire: the tunnel we just kept is authenticated with that key, and
-                                // revoking a live tunnel's credential would kill what we preserved.
-                                // (On the eviction branch markTunnelDead already revokes it.)
-                                tunnelId = tunneled.tunnelId;
-                                return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
-                            }
+                    catch (provisionError) {
+                        const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                        const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
+                        return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
+                    }
+                    acquiredKeyId = tunnel.keyId;
+                    let dedicated;
+                    try {
+                        dedicated = await tunnelManager.acquireDedicatedTunnel(ctx.originalUrl, tunnel.tunnelKey, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+                    }
+                    catch (tunnelError) {
+                        const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
+                        return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
+                    }
+                    // Health probe — catches ERR_NGROK_8012 and bind mismatches before
+                    // the remote agent wastes steps trying to reach the server.
+                    if (dedicated.url) {
+                        const health = await probeTunnelHealth(dedicated.url);
+                        if (!health.healthy) {
+                            // Brought in line with the other three handlers, which this one never
+                            // was (it evicted on EVERY failure and never got bead k34o's shared-
+                            // registry eviction). Evict only on a code proving the endpoint is
+                            // gone: a transient edge flake must not cost two billed hours.
+                            // See utils/tunnelDisposition.ts.
+                            disposeUnhealthyTunnel({ health, tunnelId: dedicated.tunnelId, originalUrl: ctx.originalUrl });
+                            // Record the tunnel so the finally block's orphaned-key revoke can't
+                            // fire: the tunnel we just kept is authenticated with that key, and
+                            // revoking a live tunnel's credential would kill what we preserved.
+                            // (On the eviction branch markTunnelDead already revokes it.)
+                            tunnelId = dedicated.tunnelId;
+                            return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
                         }
-                        effectiveTargetUrl = tunneled.targetUrl ?? input.targetUrl;
-                        tunnelId = tunneled.tunnelId;
                     }
+                    effectiveTargetUrl = dedicated.url;
+                    tunnelId = dedicated.tunnelId;
+                    sanitizeCtx = { ...ctx, tunnelId: dedicated.tunnelId, targetUrl: dedicated.url };
                     logger.info(`run_test_suite: localhost detected, tunneled ${input.targetUrl} → ${effectiveTargetUrl}`);
                 }
             }
         }
         const result = await client.runTestSuite(suiteUuid, { targetUrl: effectiveTargetUrl });
         logger.toolComplete('run_test_suite', Date.now() - start);
+        const responsePayload = {
+            ...result,
+            ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
+            note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
+        };
+        // Bead debugg_ai_mcp-6cfv.7: this handler previously had NO sanitize call
+        // at all — safe only by accident of `result`'s narrow return type never
+        // having carried a tunnel hostname in practice. Add the same defensive
+        // pass every other handler already runs, so a future backend field that
+        // echoes back the (dedicated, ngrok-direct) tunnel URL can never leak it
+        // to a caller who only knows their own localhost address.
+        const sanitizedPayload = sanitizeCtx ? sanitizeResponseUrls(responsePayload, sanitizeCtx) : responsePayload;
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify({
-                        ...result,
-                        ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
-                        note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
-                    }, null, 2),
+                    text: JSON.stringify(sanitizedPayload, null, 2),
                 }],
         };
     }

package/dist/handlers/testPageChangesHandler.js

@@ -11,7 +11,8 @@ import { DebuggAIServerClient } from '../services/index.js';
 import { getEvalTemplateSlug } from '../services/workflows.js';
 import { adaptVerdict, isEnvironmentDefault } from '../services/verdictAdapter.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
-import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { randomUUID } from 'node:crypto';
 import { detectRepoName } from '../utils/gitContext.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth, extractNgrokErrorCode } from '../utils/localReachability.js';
@@ -175,6 +176,9 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             logger.warn(`Best-effort cancel of abandoned execution ${uuid} threw synchronously: ${err}`);
         }
     };
+    // Unique per-call id for the shared port-route lock's holder bookkeeping
+    // (§2.4) — reused for abort wiring purposes elsewhere in this handler.
+    const callId = randomUUID();
     const abortController = new AbortController();
     const onAbort = () => {
         clientAborted = true;
@@ -257,6 +261,24 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                     }
                     logger.info(`Tunnel ready: ${ctx.targetUrl} (id: ${ctx.tunnelId})`);
                 }
+                // §2.4: acquire this session's shared Caddy route for our port BEFORE
+                // probing/dispatching — probing before the repoint is confirmed would
+                // probe whatever port happened to be active a moment ago. Blocks here
+                // (not just during the repoint) until any different-port holder in
+                // this same session releases.
+                ctx = await acquirePortRoute(ctx, {
+                    callId,
+                    signal: abortController.signal,
+                    onWaitProgress: progressCallback
+                        ? async (info) => {
+                            await progressCallback({
+                                progress: 1,
+                                total: TOTAL_STEPS,
+                                message: `Waiting for shared tunnel — port ${info.blockingPort} is in use (waited ${Math.round(info.waitedMs / 1000)}s)...`,
+                            });
+                        }
+                        : undefined,
+                });
                 // Bead 1om: verify traffic actually flows through the tunnel. The
                 // tunnel can be established (ngrok.connect returns OK) yet refuse
                 // to forward traffic — e.g., IPv4/IPv6 bind mismatch, or the dev
@@ -721,6 +743,11 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // bug. Relay the logins verbatim, and when the caller named an account but
         // an environment default was used anyway, say so explicitly rather than
         // leaving the caller to infer it from a failed check.
+        // For "navigate and describe what you see", the answer IS the deliverable —
+        // and it reached callers only incidentally, buried in actionTrace[0].intent,
+        // which the verify-gate rewrites when it disagrees with the page. Surface it.
+        if (verdict.report)
+            responsePayload.report = verdict.report;
         if (verdict.logins)
             responsePayload.logins = verdict.logins;
         if (verdict.loginError)
@@ -908,6 +935,10 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     finally {
         if (requestSignal)
             requestSignal.removeEventListener('abort', onAbort);
+        // §2.4: release this call's claim on the shared port route (no-op if we
+        // never acquired one — public URL, dev mode, or an early-return before
+        // acquisition). Covers every early-return path above for free.
+        releasePortRoute(ctx);
         // Tunnel is intentionally NOT torn down here — tunnelManager reuses it on
         // subsequent calls to the same port and auto-shutoffs after 55 min idle.
         // Process-exit cleanup happens via stopAllTunnels() in the SIGINT/SIGTERM

package/dist/handlers/triggerCrawlHandler.js

@@ -18,7 +18,8 @@ import { TunnelProvisionError } from '../services/tunnels.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
-import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { randomUUID } from 'node:crypto';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
 import { detectLocalGitRef } from '../utils/gitContext.js';
 import { getCrawlTemplateSlug } from '../services/workflows.js';
@@ -67,6 +68,8 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     // we get: stdin is not the transport, so the old stdin 'close' listener never
     // fired and a dropped client kept polling for up to ~10 min. Wiring to
     // context.signal cancels the poll immediately (parity with 56kd.5).
+    // Unique per-call id for the shared port-route lock's holder bookkeeping (§2.4).
+    const callId = randomUUID();
     const abortController = new AbortController();
     const onAbort = () => {
         abortController.abort();
@@ -123,6 +126,25 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
                     keyId = tunnel.keyId;
                     ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
                 }
+                // §2.4: acquire this session's shared Caddy route for our port BEFORE
+                // probing/dispatching — trigger_crawl polls (pollExecution below) for
+                // the full duration real backend traffic can occur, exactly like
+                // check_app_in_browser/probe_page, so it holds this lock for the
+                // whole call, not just the repoint (verified: it is NOT a
+                // fire-and-forget exception — only run_test_suite is, §2.3).
+                ctx = await acquirePortRoute(ctx, {
+                    callId,
+                    signal: abortController.signal,
+                    onWaitProgress: progressCallback
+                        ? async (info) => {
+                            await progressCallback({
+                                progress: 1,
+                                total: 4,
+                                message: `Waiting for shared tunnel — port ${info.blockingPort} is in use (waited ${Math.round(info.waitedMs / 1000)}s)...`,
+                            });
+                        }
+                        : undefined,
+                });
                 // Bead 1om: post-tunnel health check — verify traffic actually flows.
                 if (ctx.targetUrl) {
                     const health = await probeTunnelHealth(ctx.targetUrl);
@@ -336,6 +358,9 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     finally {
         if (requestSignal)
             requestSignal.removeEventListener('abort', onAbort);
+        // §2.4: release this call's claim on the shared port route (no-op if we
+        // never acquired one).
+        releasePortRoute(ctx);
         // Tunnel intentionally NOT torn down (reuse path per bead vwd).
         // If tunnel creation failed after key provision, revoke the orphaned key.
         if (!ctx.tunnelId && keyId) {