@debugg-ai/debugg-ai-mcp 4.2.0 → 4.2.2

package/README.md

@@ -142,13 +142,13 @@ Fires a server-side browser-agent crawl to populate the project's knowledge grap
 
 #### `probe_page`
 
-**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, waits for load, and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
+**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, settles on content (the DOM going quiet, bounded — never on network silence, which a live app never reaches), and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `targets` | array **required** | 1-20 entries: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]` |
 | `targets[].url` | string **required** | Public URL or localhost (auto-tunneled) |
-| `targets[].waitForLoadState` | enum | `'load'` (default) / `'domcontentloaded'` / `'networkidle'` |
+| `targets[].waitForLoadState` | enum | `'domcontentloaded'` (default, + a bounded content settle) / `'load'` (also blocks on third-party embeds) / `'networkidle'` (accepted, never issued — a live site's network does not go idle) |
 | `targets[].waitForSelector` | string | Optional CSS selector to wait for after navigation |
 | `targets[].timeoutMs` | number | Per-URL timeout, 1000-30000 (default 10000) |
 | `includeHtml` | boolean | Return raw HTML in each result (default false) |

package/dist/handlers/testPageChangesHandler.js

@@ -12,7 +12,7 @@ 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, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, retargetAuxiliaryUrl, } from '../utils/tunnelContext.js';
 import { randomUUID } from 'node:crypto';
 import { detectRepoName } from '../utils/gitContext.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
@@ -379,10 +379,33 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 auth.environmentId = input.auth.environmentId;
             if (input.auth.precondition)
                 auth.precondition = input.auth.precondition;
-            if (input.auth.entryUrl)
-                auth.entryUrl = input.auth.entryUrl;
-            if (input.auth.deepUrl)
-                auth.deepUrl = input.auth.deepUrl;
+            // Bead go1m: entryUrl/deepUrl are URLs the run NAVIGATES, so they need the
+            // same localhost→tunnel rewrite `url` gets (contextData.targetUrl above).
+            // Forwarded verbatim they reached the remote browser as literal localhost
+            // and it dialled its own loopback: offscope_host + ERR_CONNECTION_REFUSED.
+            for (const field of ['entryUrl', 'deepUrl']) {
+                const supplied = input.auth[field];
+                if (!supplied)
+                    continue;
+                const rewrite = retargetAuxiliaryUrl(ctx, supplied);
+                if (!rewrite.ok) {
+                    const payload = {
+                        error: 'AuthUrlPortMismatch',
+                        message: `auth.${field} points at localhost:${rewrite.port} but url points at ` +
+                            `localhost:${rewrite.primaryPort}. A single call tunnels exactly one local ` +
+                            `port, so the remote browser cannot reach both. Put the login page and the ` +
+                            `target page on the same port, or drop auth.${field} and pass username/password ` +
+                            `at the top level so the agent signs in on the page it already reached.`,
+                        detail: { field, authPort: rewrite.port, urlPort: rewrite.primaryPort, url: originalUrl },
+                    };
+                    logger.warn(`check_app_in_browser: ${payload.message}`);
+                    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                }
+                auth[field] = rewrite.url;
+                if (rewrite.rewritten) {
+                    logger.info(`check_app_in_browser: tunneled auth.${field} ${supplied} -> ${rewrite.url}`);
+                }
+            }
             // WHICH account the precondition logs in as. Absent → the environment's
             // default credential (the pre-existing behaviour, correct for a caller
             // that named nobody).

package/dist/tools/probePage.js

@@ -22,6 +22,8 @@ LOCALHOST SUPPORT: any localhost URL is auto-tunneled. Pre-flight TCP probe fail
 
 BATCH MODE: pass up to 20 targets in one call to share browser session + tunnel — dramatically faster than firing parallel single-URL probes (one execution unit, not N). Per-URL waitForSelector / waitForLoadState / timeoutMs override defaults.
 
+READINESS: navigation settles on CONTENT (the page's DOM going quiet), bounded — not on network silence, which never arrives on a live app, and not on 'load', which blocks on third-party embeds. The default is right for SPAs; reach for waitForSelector, not waitForLoadState, when you need to wait for something specific.
+
 A single failed target's error appears in result.error without failing the whole batch — the other results stay valid.`;
 const TARGET_PROPERTIES = {
     url: {
@@ -35,11 +37,15 @@ const TARGET_PROPERTIES = {
     waitForLoadState: {
         type: 'string',
         enum: ['load', 'domcontentloaded', 'networkidle'],
-        description: "When to consider the page 'loaded' before capturing. Default 'load'. Use 'networkidle' for SPAs to wait until the bundle finishes rendering.",
+        // sentinal-kvoou. This description used to read "Default 'load'. Use 'networkidle'
+        // for SPAs to wait until the bundle finishes rendering" — advice that hangs on
+        // exactly the class of app it names. See __tests__/tools/probePageWaitContract.ts
+        // for the measurement against https://debugg.ai.
+        description: "When to consider the page ready to capture. Default 'domcontentloaded', followed by a bounded content settle (the page's DOM going quiet) — that is what actually makes a client-rendered SPA safe to screenshot, and it needs no override. Only override for a specific reason: 'load' additionally blocks on every sub-resource, including third-party iframes and images we do not control, so a slow embed can time the whole probe out. 'networkidle' is accepted for compatibility but is never issued — a live site's network does not go idle (analytics, polling, websockets, ads) — and behaves as 'domcontentloaded'. To wait on something specific, use waitForSelector.",
     },
     timeoutMs: {
         type: 'number',
-        description: 'Per-URL navigation timeout in milliseconds (1000-30000, default 10000).',
+        description: "Per-URL budget in milliseconds for navigating AND settling this target (1000-30000, default 10000). The content settle spends what the navigation left over, so this is the whole cost of the target, not just the goto.",
     },
 };
 export function buildProbePageTool() {

package/dist/types/index.js

@@ -226,7 +226,15 @@ export var LogLevel;
 export const ProbePageTargetSchema = z.object({
     url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),
     waitForSelector: z.string().optional(),
-    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('load'),
+    // sentinal-kvoou: 'domcontentloaded', NOT 'load'. 'load' blocks on every
+    // sub-resource including third-party iframes we do not control — measured against
+    // https://debugg.ai (two YouTube embeds), the 'load' default timed the goto out at
+    // 10s and reported statusCode 0 on a page that renders in 3.5s. Readiness comes from
+    // the backend's bounded CONTENT settle after the goto, not from a load state.
+    // 'networkidle' stays in the enum (this package is published; removing it would turn
+    // an existing caller's probe into a hard validation error) and is neutralized
+    // server-side — never a wait, always domcontentloaded + settle.
+    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('domcontentloaded'),
     timeoutMs: z.number().int().min(1000, 'timeoutMs minimum is 1000 (1s)').max(30000, 'timeoutMs maximum is 30000 (30s) — longer probes should use check_app_in_browser').default(10000),
 }).strict();
 export const ProbePageInputSchema = z.object({

package/dist/utils/tunnelContext.js

@@ -69,6 +69,46 @@ export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey) {
     const info = await tunnelManager.ensureSessionTunnel(getSessionKey(), tunnelKey, tunnelId, keyId, revokeKey);
     return { ...ctx, tunnelId: info.tunnelId, targetUrl: retargetTunnelUrl(info.tunnelUrl, ctx.originalUrl) };
 }
+/**
+ * Retarget an auxiliary URL the CALLER supplied (`auth.entryUrl`, `auth.deepUrl`)
+ * onto the same tunnel the run's primary `url` already uses.
+ *
+ * Bead go1m: only the top-level `url` ever went through the localhost→tunnel
+ * rewrite. `auth.entryUrl`/`auth.deepUrl` were forwarded verbatim, so a
+ * localhost entry URL reached the REMOTE browser as a literal `localhost:PORT`
+ * and it dialled its own loopback — `offscope_host` + ERR_CONNECTION_REFUSED on
+ * the documented "log in THEN deep-navigate" path. Every URL the run may
+ * navigate has to go through the same rewrite as `url`.
+ *
+ * Three cases, deliberately distinguished:
+ *  - not localhost (public URL, or dev mode / no tunnel) → returned unchanged.
+ *    Matches how the primary `url` is treated in those same conditions.
+ *  - localhost on the SAME port as the primary URL → retargeted onto the
+ *    tunnel origin, preserving path + query + hash (`retargetTunnelUrl`).
+ *  - localhost on a DIFFERENT port → REFUSED, never silently retargeted. The
+ *    session's single Caddy upstream is pointed at the primary URL's port for
+ *    the whole call (see `acquirePortRoute`), so rewriting a cross-port URL
+ *    onto the same origin would send the login navigation to whichever port
+ *    Caddy happens to hold — the silent misdirection the port lock exists to
+ *    prevent. Fail fast and tell the caller instead.
+ */
+export function retargetAuxiliaryUrl(ctx, auxUrl) {
+    // No tunnel in play (public target, or dev mode where the backend reaches
+    // localhost directly): the primary URL isn't rewritten either, so neither is this.
+    if (!ctx.isLocalhost || !ctx.tunnelId || !ctx.targetUrl) {
+        return { ok: true, url: auxUrl, rewritten: false };
+    }
+    // A public auxiliary URL is reachable by the remote browser as-is.
+    if (!isLocalhostUrl(auxUrl)) {
+        return { ok: true, url: auxUrl, rewritten: false };
+    }
+    const port = extractLocalhostPort(auxUrl);
+    const primaryPort = extractLocalhostPort(ctx.originalUrl);
+    if (port !== undefined && primaryPort !== undefined && port !== primaryPort) {
+        return { ok: false, reason: 'port_mismatch', port, primaryPort };
+    }
+    return { ok: true, url: retargetTunnelUrl(ctx.targetUrl, auxUrl), rewritten: true };
+}
 // ─── Port route lock (§2.4) ──────────────────────────────────────────────────
 /**
  * Acquire this session's shared Caddy route for `ctx`'s port, blocking until

package/package.json

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