@debugg-ai/debugg-ai-mcp 6.1.5 → 6.2.1

package/dist/services/navigationGuard.js

@@ -0,0 +1,71 @@
+export function isLoopbackHost(h) {
+    return ['localhost', '127.0.0.1', '[::1]', '::1'].includes(h.toLowerCase());
+}
+export function safeHost(u) {
+    try {
+        return new URL(u).hostname;
+    }
+    catch {
+        return u;
+    }
+}
+function hostAllowed(host, allowed) {
+    const h = host.toLowerCase();
+    return allowed.some((d) => {
+        const a = d.trim().toLowerCase().replace(/^\*?\./, '');
+        return a !== '' && (h === a || h.endsWith(`.${a}`));
+    });
+}
+/** Guard every current and future page of the context. `onBlocked` receives the refused host. */
+export async function installNavigationGuard(context, allowed, onBlocked) {
+    const check = (u) => {
+        try {
+            const h = new URL(u).hostname;
+            return hostAllowed(h, allowed) || isLoopbackHost(h);
+        }
+        catch {
+            return false;
+        }
+    };
+    const guard = async (pg) => {
+        const cdp = await context.newCDPSession(pg);
+        const mainFrameId = (await cdp.send('Page.getFrameTree')).frameTree.frame.id;
+        await cdp.send('Fetch.enable', { patterns: [
+                { urlPattern: '*', resourceType: 'Document', requestStage: 'Request' },
+                { urlPattern: '*', resourceType: 'Document', requestStage: 'Response' },
+            ] });
+        cdp.on('Fetch.requestPaused', (ev) => {
+            void (async () => {
+                try {
+                    if (ev.frameId !== mainFrameId) {
+                        await cdp.send(ev.responseStatusCode ? 'Fetch.continueResponse' : 'Fetch.continueRequest', { requestId: ev.requestId });
+                        return;
+                    }
+                    if (ev.responseStatusCode === undefined) {
+                        if (!check(ev.request.url)) {
+                            onBlocked(safeHost(ev.request.url));
+                            await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
+                            return;
+                        }
+                        await cdp.send('Fetch.continueRequest', { requestId: ev.requestId });
+                        return;
+                    }
+                    const loc = ev.responseHeaders?.find((h) => h.name.toLowerCase() === 'location')?.value;
+                    if (ev.responseStatusCode >= 300 && ev.responseStatusCode < 400 && loc) {
+                        const next = new URL(loc, ev.request.url).toString();
+                        if (!check(next)) {
+                            onBlocked(safeHost(next));
+                            await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
+                            return;
+                        }
+                    }
+                    await cdp.send('Fetch.continueResponse', { requestId: ev.requestId });
+                }
+                catch { /* page closed */ }
+            })();
+        });
+    };
+    for (const pg of context.pages())
+        await guard(pg);
+    context.on('page', (pg) => { void guard(pg).catch(() => { }); });
+}

package/dist/services/workflows.js

@@ -3,12 +3,22 @@
  * 4-step integration: find template → execute → poll → result
  */
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { logger } from '../utils/logger.js';
 import { redactRunSecrets } from '../utils/redactRunSecrets.js';
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 // Exponential backoff polling: short executions (10-15s crawls) detect terminal
 // status quickly via the early polls; long executions (60-150s browser runs)
 // avoid hammering the backend with 20+ roundtrips. Cap at 5s so we never wait
 // more than 5s past terminal-state achievement.
+const MAX_CONSECUTIVE_POLL_FAILURES = 5;
+/** Network-class (no response), 5xx, 408 and 429 are worth another poll; any other 4xx is a real answer. */
+function isTransientPollError(err) {
+    const e = err;
+    const status = e?.statusCode;
+    if (typeof status === 'number')
+        return status >= 500 || status === 408 || status === 429;
+    return true; // no status: network-class error (message-only), as axiosTransport shapes it
+}
 const POLL_INTERVAL_INITIAL_MS = 1000;
 const POLL_INTERVAL_MAX_MS = 5000;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -33,11 +43,16 @@ const noProgressTimeoutMs = () => {
  */
 export const EVAL_TEMPLATE_SLUG = 'flow/e2es/app-eval'; // check_app_in_browser
 export const PAGE_PROBE_TEMPLATE_SLUG = 'flow/tools/probe'; // probe_page
+export const LOCAL_BROWSE_TEMPLATE_SLUG = 'flow/tools/browse'; // check_app_in_browser browser:'local' (sense/think/act brain)
 export const RAW_CRAWL_TEMPLATE_SLUG = 'crawl-execution-workflow-template'; // trigger_crawl
 /** The slug the eval-template dispatch pins to (env-overridable). */
 export function getEvalTemplateSlug() {
     return process.env.DEBUGGAI_EVAL_TEMPLATE || EVAL_TEMPLATE_SLUG;
 }
+/** The slug a local-executor check pins to: the browser_use brain cannot drive a local executor (env-overridable). */
+export function getLocalBrowseTemplateSlug() {
+    return process.env.DEBUGGAI_LOCAL_TEMPLATE || LOCAL_BROWSE_TEMPLATE_SLUG;
+}
 /** The slug the page-probe dispatch pins to (env-overridable). */
 export function getPageProbeTemplateSlug() {
     return process.env.DEBUGGAI_PROBE_TEMPLATE || PAGE_PROBE_TEMPLATE_SLUG;
@@ -128,11 +143,26 @@ export const createWorkflowsService = (tx) => {
             // partial results (screenshot + trace) instead of discarding them (bead
             // 56kd.3).
             let lastExecution;
+            let consecutivePollFailures = 0;
             while (Date.now() < deadline) {
                 if (signal?.aborted) {
                     throw new Error(`Polling cancelled for execution ${executionUuid}`);
                 }
-                const execution = await service.getExecution(executionUuid);
+                let execution;
+                try {
+                    execution = await service.getExecution(executionUuid);
+                    consecutivePollFailures = 0;
+                }
+                catch (err) {
+                    // Bead kruv: one blip (ECONNRESET, 5xx during a deploy, 30s client
+                    // timeout) must not lose a run the server is still executing. Only
+                    // transient failures are tolerated, and only a few in a row.
+                    if (!isTransientPollError(err) || ++consecutivePollFailures > MAX_CONSECUTIVE_POLL_FAILURES)
+                        throw err;
+                    logger.warn(`pollExecution: transient status-poll failure ${consecutivePollFailures}/${MAX_CONSECUTIVE_POLL_FAILURES} for ${executionUuid}: ${err instanceof Error ? err.message : err}`);
+                    await new Promise((r) => setTimeout(r, intervalMs));
+                    continue;
+                }
                 lastExecution = execution;
                 pollCount++;
                 if (onUpdate) {

package/dist/tools/probePage.js

@@ -81,6 +81,28 @@ export function buildProbePageTool() {
                     type: 'string',
                     description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this to scope the probe to a different project context.",
                 },
+                browser: {
+                    type: 'string',
+                    enum: ['remote', 'local'],
+                    description: "Default 'remote' (cloud browser; localhost is tunneled). 'local' runs Chrome on THIS machine against the URL directly: no tunnel, nothing uploaded, screenshot also saved under ~/.debugg-ai/captures. Works only when the MCP server runs on your machine AND its owner set DEBUGGAI_LOCAL_BROWSER=1. waitForSelector/waitForLoadState/timeoutMs apply; the local mode returns screenshot, console errors, network summary, title and (optionally) HTML.",
+                },
+                headless: {
+                    type: 'boolean',
+                    description: "browser:'local' only. Default true. false opens a visible Chrome window.",
+                },
+                useProfile: {
+                    type: 'boolean',
+                    description: "browser:'local' only. Default false (fresh throwaway profile). true uses the MCP-owned persistent profile (~/.debugg-ai/chrome-profile, never your everyday Chrome profile), so pages you signed into there are captured logged-in. Sign in once with headless:false plus loginWindowMs. Captures from it never leave the machine.",
+                },
+                allowedDomains: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: "browser:'local', useProfile:true only. REQUIRED for a profile session unless the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS (which then overrides this). Hostnames (subdomains included) the logged-in session may navigate to; any other top-level navigation, redirects included, is blocked and reported in blockedNavigations. localhost is always allowed.",
+                },
+                loginWindowMs: {
+                    type: 'number',
+                    description: "browser:'local', useProfile:true, headless:false only. Keep the window open up to this long (1000-600000 ms) or until you close it, so you can sign in to the site once.",
+                },
             },
             required: ['targets'],
             additionalProperties: false,

package/dist/tools/testPageChanges.js

@@ -106,6 +106,14 @@ export function buildTestPageChangesTool(ctx) {
                     type: "boolean",
                     description: "Default false. Set true to force a REAL login instead of reusing the warm session the backend keeps per account. Use when the login flow itself is what you're checking, when you suspect the stored session is stale, or when the app's only route between personas is a logout. Costs one login; the run re-captures afterwards, so later runs stay fast."
                 },
+                browser: {
+                    type: "string",
+                    enum: ["remote", "local"],
+                    description: "Default 'remote' (cloud browser; localhost is tunneled). 'local' runs the clicking in Chrome on THIS machine — no tunnel, no *.localhost limits, much faster — while the cloud agent still decides each step. Needs DEBUGGAI_LOCAL_BROWSER=1 on the MCP server and the backend's local executor enabled. Passwords passed in this call stay on this machine. Page screenshots and text are still sent to the cloud agent. Not available over the remote HTTP MCP."
+                },
+                headless: { type: "boolean", description: "browser:'local' only. Default true; false shows the Chrome window." },
+                useProfile: { type: "boolean", description: "browser:'local' only. Use the MCP-owned logged-in Chrome profile (never your everyday Chrome). Requires allowedDomains." },
+                allowedDomains: { type: "array", items: { type: "string" }, description: "browser:'local' only. Extra hostnames (and subdomains) the run may navigate to, beyond the url's own host and localhost. Navigation off this list is refused, redirects included." },
                 extraOrigins: {
                     type: "array",
                     items: { type: "string" },

package/dist/types/index.js

@@ -64,6 +64,12 @@ export const TestPageChangesInputSchema = z.object({
     // skip login; that is right for speed and wrong when the login itself is what
     // you are checking, or when the app's only route between personas is a logout.
     freshSession: z.boolean().optional(),
+    // 'local' runs the clicking in Chrome on THIS machine (no tunnel); the cloud agent still decides each step.
+    // Needs DEBUGGAI_LOCAL_BROWSER=1 on the MCP server.
+    browser: z.enum(['remote', 'local']).default('remote'),
+    headless: z.boolean().optional(),
+    useProfile: z.boolean().optional(),
+    allowedDomains: z.array(z.string().min(1)).max(32).optional(),
     // Extra LOCAL origins the run may be redirected to (bead w1os.2) — e.g. an OAuth
     // vendor on :4717 (also host.docker.internal:4717) or a callback on :4304. Each is
     // tunnelled and redirects to it are followed through the tunnel. Only origins named
@@ -274,6 +280,16 @@ export const ProbePageInputSchema = z.object({
     includeHtml: z.boolean().default(false),
     captureScreenshots: z.boolean().default(true),
     repoName: z.string().optional(),
+    // Local Chrome capture (beads jpw3.1/.2). 'remote' (default) is the cloud browser.
+    browser: z.enum(['remote', 'local']).default('remote'),
+    // local only: false opens a visible window.
+    headless: z.boolean().default(true),
+    // local only: use the MCP-owned persistent profile (log in once) instead of a throwaway one.
+    useProfile: z.boolean().default(false),
+    // local + useProfile + headless:false only: keep the window open this long so the user can sign in once.
+    loginWindowMs: z.number().int().min(1000).max(600000).optional(),
+    // local + useProfile: domains (and subdomains) the session may navigate to. Required unless the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.
+    allowedDomains: z.array(z.string().min(1)).max(50).optional(),
 }).strict();
 // ── E2E Suite Management ──────────────────────────────────────────────────────
 const projectIdentifier = {

package/dist/utils/projectRequired.js

@@ -2,12 +2,14 @@
  * Shared ProjectRequired text (platform-y2ob.2): says what was observed and
  * what to pass. Used by check_app_in_browser and trigger_crawl.
  */
-export function projectRequiredMessage(repoName) {
+export function projectRequiredMessage(repoName, acceptsProjectUuid = true) {
     const observed = repoName
         ? `Could not determine the DebuggAI project: no project is linked to git repo "${repoName}".`
         : 'Could not determine the DebuggAI project: this is not a git repo and no repoName was passed.';
     return observed
-        + ' Pass `projectUuid` (list yours with the `project` tool, action "list") or `repoName` (the "org/repo" of a linked project).';
+        + (acceptsProjectUuid
+            ? ' Pass `projectUuid` (list yours with the `project` tool, action "list") or `repoName` (the "org/repo" of a linked project).'
+            : ' Pass `repoName` (matches a project name, slug or linked "org/repo"; list yours with the `project` tool, action "list") or `environmentId`.');
 }
 /**
  * A repo->project lookup that FAILED (platform-y2ob.4), as opposed to one that
@@ -15,7 +17,7 @@ export function projectRequiredMessage(repoName) {
  * network error says nothing about whether a project exists. Reports the HTTP
  * status and the backend's message verbatim.
  */
-export function projectLookupFailedPayload(repoName, err) {
+export function projectLookupFailedPayload(repoName, err, acceptsProjectUuid = true) {
     const e = err;
     const statusCode = typeof e?.statusCode === 'number' ? e.statusCode : undefined;
     const reason = err instanceof Error ? err.message : String(err);
@@ -25,7 +27,9 @@ export function projectLookupFailedPayload(repoName, err) {
     return {
         error: 'ProjectLookupFailed',
         message: `Could not look up the DebuggAI project for git repo "${repoName}" (${how}). `
-            + 'This is a lookup failure, not a missing link: pass `projectUuid` to skip the lookup, or fix the connection and retry.',
+            + 'This is a lookup failure, not a missing link: '
+            + (acceptsProjectUuid ? 'pass `projectUuid` to skip the lookup, ' : 'pass `environmentId` to skip the lookup, ')
+            + 'or fix the connection and retry.',
         detail: { repoName, ...(statusCode !== undefined ? { statusCode } : {}), ...(e?.networkCode ? { networkCode: e.networkCode } : {}) },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "6.1.5",
+  "version": "6.2.1",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -83,5 +83,8 @@
     "ts-jest": "^29.4.1",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.58.2"
+  },
+  "optionalDependencies": {
+    "playwright-core": "^1.65.0"
   }
 }