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

package/README.md

@@ -47,6 +47,10 @@ cause), then that your dev server answers a plain `curl http://127.0.0.1:<port>/
 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>`.
 
+### Local Chrome capture (opt-in)
+
+`probe_page` accepts `browser: "local"` to capture with Chrome on your own machine: no tunnel, no cloud browser, nothing uploaded (screenshots also saved under `~/.debugg-ai/captures`, mode 0600). The server owner must set `DEBUGGAI_LOCAL_BROWSER=1`; Chrome is found automatically or via `DEBUGGAI_CHROME_PATH`; `playwright-core` is an optional dependency. `useProfile: true` uses an MCP-owned persistent profile (`~/.debugg-ai/chrome-profile`, never your everyday Chrome profile): sign in once with `headless: false, loginWindowMs: 120000`, later local probes are logged in. Profile sessions require `allowedDomains` (or the owner's `DEBUGGAI_PROFILE_ALLOWED_DOMAINS`, which overrides it); top-level navigations off the list, redirect hops included, are blocked.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json
@@ -102,6 +106,7 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `loginCredentials` | array | Accounts for logins the agent hits **during** the task — `[{username, password, label?}]` |
 | `useEnvironmentCredentials` | boolean | Default `true`. `false` forbids auto-filling the environment's stored credentials; with no account named it means **do not log in at all** |
 | `freshSession` | boolean | Default `false`. `true` forces a real login instead of reusing the warm session held for that account |
+| `extraOrigins` | string[] | Extra local origins the run may be redirected to, e.g. `["http://host.docker.internal:4717", "http://localhost:4304"]` (OAuth vendor + callback on other ports). Redirects to them (and back to `url`) are followed through the tunnel; pages on them are served at `/__o/<port>/`. Only listed origins are exposed. Absolute URLs written inside page HTML (not redirects) are not rewritten |
 | `auth` | object | Auth precondition — `{precondition, entryUrl, deepUrl, environmentId, username, password}` |
 | `repoName` | string | Override auto-detected git repo name (e.g. `my-org/my-repo`) |
 

package/dist/handlers/localProbeHandler.js

@@ -0,0 +1,46 @@
+/**
+ * probe_page with browser:'local' (bead jpw3.1/.2): capture each target with the
+ * user's own Chrome on this machine. No backend call, no tunnel.
+ */
+import { localCapture, LocalBrowserError } from '../services/localBrowser.js';
+import { imageContentBlock } from '../utils/imageUtils.js';
+import { logger } from '../utils/logger.js';
+export async function localProbe(input, context) {
+    const results = [];
+    const images = [];
+    for (const t of input.targets) {
+        try {
+            const r = await localCapture({
+                url: t.url,
+                headless: input.headless,
+                useProfile: input.useProfile,
+                loginWindowMs: input.loginWindowMs,
+                allowedDomains: input.allowedDomains,
+                waitForSelector: t.waitForSelector,
+                waitForLoadState: t.waitForLoadState,
+                timeoutMs: t.timeoutMs,
+                includeHtml: input.includeHtml,
+                captureScreenshot: input.captureScreenshots,
+                signal: context.signal,
+            });
+            const { screenshotBase64, ...rest } = r;
+            results.push(rest);
+            if (screenshotBase64)
+                images.push(imageContentBlock(screenshotBase64, 'image/png'));
+        }
+        catch (err) {
+            if (err instanceof LocalBrowserError && (err.code === 'LOCAL_BROWSER_DISABLED' || err.code === 'PLAYWRIGHT_MISSING' || err.code === 'PROFILE_ALLOWLIST_REQUIRED')) {
+                return { content: [{ type: 'text', text: JSON.stringify({ error: err.code, message: err.message }, null, 2) }], isError: true };
+            }
+            const message = err instanceof Error ? err.message.split('\n')[0] : String(err);
+            logger.warn(`probe_page local: ${t.url} failed: ${message}`);
+            results.push({ url: t.url, error: message, ...(err instanceof LocalBrowserError ? { errorCode: err.code } : {}) });
+        }
+    }
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify({ browser: 'local', results }, null, 2) },
+            ...images,
+        ],
+    };
+}

package/dist/handlers/probePageHandler.js

@@ -25,6 +25,7 @@ import { buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, relea
 import { randomUUID } from 'node:crypto';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
 import { getPageProbeTemplateSlug } from '../services/workflows.js';
+import { localProbe } from './localProbeHandler.js';
 import { reaggregateByOriginPath, mapConsoleSlice } from '../utils/harSummarizer.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'probePageHandler' });
@@ -76,6 +77,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
             }
         }
         : undefined;
+    if (input.browser === 'local') {
+        return localProbe(input, context);
+    }
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
     // Bead 56kd.7: cancellation is driven by the MCP request/transport lifecycle

package/dist/handlers/testPageChangesHandler.js

@@ -10,7 +10,9 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { getEvalTemplateSlug } from '../services/workflows.js';
-import { adaptVerdict, credentialSubstitutions } from '../services/verdictAdapter.js';
+import { authorizeExtraOrigins, ExtraOriginError } from '../utils/extraOrigins.js';
+import { refreshPendingArtifacts } from '../utils/artifactGrace.js';
+import { adaptVerdict, credentialSubstitutions, summarizeLogins } from '../services/verdictAdapter.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, retargetAuxiliaryUrl, } from '../utils/tunnelContext.js';
 import { randomUUID } from 'node:crypto';
@@ -318,6 +320,18 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                         }
                         : undefined,
                 });
+                // Bead w1os.2: extra local origins (OAuth vendor, callback) this run may
+                // be redirected to. Needs the route held; validated here so a bad entry
+                // fails fast with a plain message instead of mid-run.
+                try {
+                    ctx = await authorizeExtraOrigins(ctx, input.extraOrigins);
+                }
+                catch (err) {
+                    if (err instanceof ExtraOriginError) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ error: 'InvalidExtraOrigin', message: err.message }, null, 2) }], isError: true };
+                    }
+                    throw err;
+                }
                 // Bead 1om: verify traffic actually flows through the tunnel. The
                 // tunnel can be established (connect returns OK) yet refuse
                 // to forward traffic — e.g., IPv4/IPv6 bind mismatch, or the dev
@@ -494,6 +508,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         let executeResponse;
         let executionUuid = '';
         let finalExecution;
+        let execStartedAtMs;
         let attempt = 0;
         while (true) {
             attempt++;
@@ -516,6 +531,8 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 }
                 await new Promise(r => setTimeout(r, 1000 * (attempt - 1)));
             }
+            const execStartedAt = Date.now();
+            execStartedAtMs = execStartedAt;
             executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
             executionUuid = executeResponse.executionUuid;
             // Bead 5er7: this is now the execution an abort must cancel (a retry moves
@@ -626,6 +643,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         }
         const duration = Date.now() - startTime;
         // --- Format result ---
+        const runDoneAtMs = Date.now();
         const nodes = finalExecution.nodeExecutions ?? [];
         // subworkflow.run carries an inline base64 screenshot on some graph shapes;
         // only used for the image block below.
@@ -729,13 +747,26 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         };
         if (verdict.budget)
             responsePayload.budget = verdict.budget;
+        // Bead w1os.1: say where the wall-clock went. setupMs is everything this MCP
+        // did before queuing the run (tunnel, route lock, health probe); runMs is
+        // queue-to-terminal on the backend (agent loop, incl. sign-in). Measured,
+        // not estimated.
+        if (execStartedAtMs !== undefined) {
+            responsePayload.timings = {
+                setupMs: execStartedAtMs - startTime,
+                runMs: runDoneAtMs - execStartedAtMs,
+                totalMs: Date.now() - startTime,
+            };
+        }
         // 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)
+        if (verdict.logins) {
             responsePayload.logins = verdict.logins;
+            responsePayload.loginSummary = summarizeLogins(verdict.logins);
+        }
         if (verdict.loginError)
             responsePayload.loginError = verdict.loginError;
         // Bead b5x6: the caller named an account and the run SUBMITTED an
@@ -801,7 +832,9 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // browser_session block: presigned S3 URLs for HAR + console log + recording,
         // passed through verbatim.
         if (finalExecution.browserSession) {
-            responsePayload.browserSession = finalExecution.browserSession;
+            // Bead w1os.3: artifacts are uploaded after the terminal state; re-read
+            // briefly while the backend says they are still queued.
+            responsePayload.browserSession = await refreshPendingArtifacts((id) => client.workflows.getExecution(id), executionUuid, finalExecution.browserSession) ?? finalExecution.browserSession;
         }
         logger.toolComplete('check_app_in_browser', duration);
         // NOTE (bead 0bq): the final "Complete:" progress is emitted INSIDE

package/dist/services/caddy/caddyProxy.js

@@ -222,6 +222,84 @@ export const CADDY_HANDLER_ID = 'dbg-handler';
 /** Placeholder upstream: dials a closed port so a stray request 502s cleanly
  *  from the first millisecond instead of exposing a raw connection-refused. */
 const PLACEHOLDER_DIAL = '127.0.0.1:1';
+/** Path prefix under which a secondary local origin is exposed on the tunnel. */
+export const AUX_PATH_PREFIX = '/__o';
+/** @id of the subroute holding the per-origin routes. */
+export const CADDY_AUX_ID = 'dbg-aux';
+const LOCAL_HOST_ALIASES = '(?:localhost|127\\.0\\.0\\.1|host\\.docker\\.internal|\\[::1\\])';
+/**
+ * Location-header rewrite rules: a redirect to any local alias of a known port
+ * becomes a path on the tunnel origin, so the REMOTE browser (which cannot
+ * resolve `host.docker.internal` / dial its own `localhost:PORT`) follows it
+ * through the tunnel. The primary port maps to `/`, an aux port to `/__o/<port>/`.
+ */
+export function buildLocationRewrites(primaryPort, aux) {
+    const rules = [];
+    for (const o of aux) {
+        rules.push({
+            search_regexp: `^https?://${LOCAL_HOST_ALIASES}:${o.port}(?:/(.*))?$`,
+            replace: AUX_PATH_PREFIX + '/' + o.port + '/${1}',
+        });
+    }
+    if (primaryPort !== undefined) {
+        rules.push({
+            search_regexp: `^https?://${LOCAL_HOST_ALIASES}:${primaryPort}(?:/(.*))?$`,
+            // Once any aux origin exists the primary is addressed by prefix too, so a
+            // redirect BACK to it does not inherit an aux page's Referer-scoped routing.
+            replace: AUX_PATH_PREFIX + '/' + primaryPort + '/${1}',
+        });
+    }
+    return rules;
+}
+function withLocationRewrites(handler, rules) {
+    if (rules.length === 0)
+        return handler;
+    return { ...handler, headers: { response: { replace: { Location: rules } } } };
+}
+/**
+ * The subroute that serves every authorised origin (aux origins plus the
+ * current primary), each addressable two ways:
+ *  - `/__o/<port>/*`  -> prefix stripped, proxied to that port;
+ *  - any other path whose Referer is a `/__o/<port>/` page -> proxied to that
+ *    port UNstripped, so root-relative links, form actions and assets on a
+ *    secondary origin's page stay on that origin. The per-origin routes are
+ *    fixed at config time, so a forged Referer can only select an origin the
+ *    caller already authorised.
+ * A request matching neither falls through to the primary upstream.
+ */
+export function buildAuxSubroute(aux, primary, inDocker) {
+    const rules = buildLocationRewrites(primary?.port, aux);
+    const all = [...aux];
+    if (primary && aux.length > 0 && !all.some((o) => o.port === primary.port)) {
+        all.push({ port: primary.port, isHttpsLocal: primary.isHttpsLocal });
+    }
+    const proxyFor = (o) => {
+        const proxy = {
+            handler: 'reverse_proxy',
+            upstreams: [{ dial: resolveDialAddress(o.port, !!o.isHttpsLocal, inDocker) }],
+        };
+        if (o.isHttpsLocal)
+            proxy.transport = { protocol: 'http', tls: { insecure_skip_verify: true } };
+        return withLocationRewrites(proxy, rules);
+    };
+    const routes = [];
+    for (const o of all) {
+        routes.push({
+            match: [{ path: [`${AUX_PATH_PREFIX}/${o.port}/*`] }],
+            handle: [{ handler: 'rewrite', strip_path_prefix: `${AUX_PATH_PREFIX}/${o.port}` }, proxyFor(o)],
+        });
+    }
+    for (const o of all) {
+        routes.push({
+            match: [{
+                    not: [{ path: [`${AUX_PATH_PREFIX}/*`] }],
+                    header_regexp: { Referer: { pattern: `^https?://[^/]+${AUX_PATH_PREFIX}/${o.port}/` } },
+                }],
+            handle: [proxyFor(o)],
+        });
+    }
+    return { '@id': CADDY_AUX_ID, handler: 'subroute', routes };
+}
 /**
  * Builds the eager-at-spawn Caddy JSON config. One code path for every call
  * including the first (architecture doc §2.2): PATCH-only against a known
@@ -229,7 +307,7 @@ const PLACEHOLDER_DIAL = '127.0.0.1:1';
  * building new structure. Both listeners bind 127.0.0.1 only — the admin
  * API has no built-in auth, so this is a hard security requirement.
  */
-export function buildCaddyConfig(proxyPort, adminPort) {
+export function buildCaddyConfig(proxyPort, adminPort, aux = []) {
     return {
         admin: { listen: `127.0.0.1:${adminPort}` },
         apps: {
@@ -238,6 +316,10 @@ export function buildCaddyConfig(proxyPort, adminPort) {
                     srv0: {
                         listen: [`127.0.0.1:${proxyPort}`],
                         routes: [
+                            // Aux origins first so `/__o/<port>/*` never falls through to the primary upstream.
+                            {
+                                handle: [buildAuxSubroute(aux, undefined, isDockerEnv())],
+                            },
                             {
                                 handle: [
                                     {
@@ -265,7 +347,7 @@ export function buildCaddyConfig(proxyPort, adminPort) {
  * address, so an omitted `@id` deletes the tag and the NEXT PATCH 404s
  * (only manifests on the second call — see LIFE-4 in the test suite).
  */
-export function buildPatchBody(target, inDocker) {
+export function buildPatchBody(target, inDocker, aux = []) {
     const isHttpsLocal = !!target.isHttpsLocal;
     const dial = resolveDialAddress(target.port, isHttpsLocal, inDocker);
     const body = {
@@ -277,7 +359,8 @@ export function buildPatchBody(target, inDocker) {
         // Local self-signed certs — doesn't touch the public leg's real TLS.
         body.transport = { protocol: 'http', tls: { insecure_skip_verify: true } };
     }
-    return body;
+    // Redirects to the primary origin or an authorised aux origin stay on the tunnel.
+    return aux.length > 0 ? withLocationRewrites(body, buildLocationRewrites(target.port, aux)) : body;
 }
 function adminHttpRequest(adminPort, method, reqPath, body, timeoutMs = 2000) {
     return new Promise((resolve, reject) => {
@@ -325,6 +408,8 @@ export class CaddyProxyManager {
     configPath = null;
     lastProxyPort = null;
     lastAppliedTarget = null;
+    /** Authorised secondary origins (bead w1os.2). Grow-only; survives a respawn. */
+    auxOrigins = [];
     portChangedListeners = [];
     constructor(opts = {}) {
         // Short random hex suffix — PID alone collides once one process hosts
@@ -359,7 +444,7 @@ export class CaddyProxyManager {
             this.lastAppliedTarget.isHttpsLocal === isHttpsLocal) {
             return; // idempotent no-op — this is what makes same-port calls free
         }
-        const body = buildPatchBody(target, isDockerEnv());
+        const body = buildPatchBody(target, isDockerEnv(), this.auxOrigins);
         try {
             await this.patchHandler(adminPort, body);
         }
@@ -379,6 +464,33 @@ export class CaddyProxyManager {
             await this.patchHandler(freshAdminPort, body);
         }
         this.lastAppliedTarget = { port: target.port, isHttpsLocal };
+        if (this.auxOrigins.length > 0)
+            await this.patchAux(this.lastAppliedTarget);
+    }
+    /** Re-issue the aux subroute so it knows the current primary (bead w1os.2). */
+    async patchAux(primary, origins = this.auxOrigins) {
+        const adminPort = this.adminPort;
+        if (adminPort === null)
+            return;
+        const res = await adminHttpRequest(adminPort, 'PATCH', `/id/${CADDY_AUX_ID}`, JSON.stringify(buildAuxSubroute(origins, primary, isDockerEnv())));
+        if (res.status < 200 || res.status >= 300) {
+            throw new CaddyAdminApiError(`PATCH /id/${CADDY_AUX_ID} failed: ${res.status} ${res.body}`);
+        }
+    }
+    async addAuxOrigins(origins) {
+        const fresh = origins.filter((o) => !this.auxOrigins.some((a) => a.port === o.port && !!a.isHttpsLocal === !!o.isHttpsLocal));
+        if (fresh.length === 0)
+            return;
+        const { adminPort } = await this.ensureStarted();
+        const next = [...this.auxOrigins, ...fresh];
+        const primary = this.lastAppliedTarget;
+        // Replace the aux subroute, then re-issue the primary handler so its
+        // Location rewrites know the new origins. Both are idempotent PATCHes.
+        await this.patchAux(primary ?? undefined, next);
+        this.auxOrigins = next;
+        if (primary) {
+            await this.patchHandler(adminPort, buildPatchBody(primary, isDockerEnv(), next));
+        }
     }
     async isHealthy() {
         if (!this.started || !this.adminPort || this.isChildDead)
@@ -445,7 +557,7 @@ export class CaddyProxyManager {
     writeConfig(proxyPort, adminPort) {
         fs.mkdirSync(this.configDir, { recursive: true });
         const configPath = path.join(this.configDir, configFileName(process.pid, this.instanceId));
-        const config = buildCaddyConfig(proxyPort, adminPort);
+        const config = buildCaddyConfig(proxyPort, adminPort, this.auxOrigins);
         fs.writeFileSync(configPath, JSON.stringify(config));
         return configPath;
     }

package/dist/services/localBrowser.js

@@ -0,0 +1,266 @@
+/**
+ * Local Chrome capture for probe_page (bead jpw3.1 / jpw3.2).
+ *
+ * Launches the user's installed Chrome through playwright-core on THIS machine
+ * and captures a page directly — no tunnel, no cloud browser, nothing uploaded.
+ * Everything stays local: screenshots are returned inline and also written under
+ * ~/.debugg-ai/captures (0600).
+ *
+ * Opt-in at the server: DEBUGGAI_LOCAL_BROWSER=1. With `useProfile`, the browser
+ * uses an MCP-owned persistent profile (~/.debugg-ai/chrome-profile, override with
+ * DEBUGGAI_CHROME_PROFILE_DIR) the user logs into once via `loginToLocalProfile`;
+ * the user's everyday Chrome profile is never touched.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class LocalBrowserError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalBrowserError';
+    }
+}
+/** Host matches an allowed domain exactly or as a subdomain. */
+export 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}`));
+    });
+}
+/**
+ * Allowlist for a profile session (bead jpw3.3). The server owner's
+ * DEBUGGAI_PROFILE_ALLOWED_DOMAINS (comma list) is authoritative when set;
+ * otherwise the call must name allowedDomains. Never empty for a profile run.
+ */
+export function resolveAllowedDomains(perCall, env = process.env) {
+    const owner = (env.DEBUGGAI_PROFILE_ALLOWED_DOMAINS ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    return owner.length > 0 ? owner : (perCall ?? []).filter(Boolean);
+}
+export function localBrowserEnabled(env = process.env) {
+    return env.DEBUGGAI_LOCAL_BROWSER === '1' || env.DEBUGGAI_LOCAL_BROWSER === 'true';
+}
+export function debuggHome(env = process.env) {
+    return env.DEBUGGAI_HOME || path.join(os.homedir(), '.debugg-ai');
+}
+export function profileDir(env = process.env) {
+    return env.DEBUGGAI_CHROME_PROFILE_DIR || path.join(debuggHome(env), 'chrome-profile');
+}
+/** Well-known Chrome locations; DEBUGGAI_CHROME_PATH wins. undefined => let playwright try channel 'chrome'. */
+export function findChrome(env = process.env) {
+    if (env.DEBUGGAI_CHROME_PATH)
+        return env.DEBUGGAI_CHROME_PATH;
+    const candidates = process.platform === 'darwin'
+        ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium']
+        : process.platform === 'win32'
+            ? [
+                `${env.PROGRAMFILES ?? 'C:\\Program Files'}\\Google\\Chrome\\Application\\chrome.exe`,
+                `${env['PROGRAMFILES(X86)'] ?? 'C:\\Program Files (x86)'}\\Google\\Chrome\\Application\\chrome.exe`,
+            ]
+            : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+    return candidates.find((p) => fs.existsSync(p));
+}
+async function loadPlaywright() {
+    try {
+        return await import('playwright-core');
+    }
+    catch {
+        throw new LocalBrowserError('Local browser mode needs the optional dependency playwright-core, which is not installed. Run `npm i playwright-core` next to the MCP.', 'PLAYWRIGHT_MISSING');
+    }
+}
+function safeHost(u) {
+    try {
+        return new URL(u).hostname;
+    }
+    catch {
+        return u;
+    }
+}
+function ensurePrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+async function launch(opts) {
+    const pw = await loadPlaywright();
+    const executablePath = findChrome();
+    const base = { headless: opts.headless, ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
+    try {
+        if (opts.useProfile) {
+            const dir = profileDir();
+            ensurePrivateDir(dir);
+            const context = await pw.chromium.launchPersistentContext(dir, { ...base, viewport: { width: 1280, height: 800 } });
+            return { context, close: () => context.close() };
+        }
+        const browser = await pw.chromium.launch(base);
+        const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+        return { context, close: () => browser.close() };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/ProcessSingleton|SingletonLock|profile.*in use|already running/i.test(msg)) {
+            throw new LocalBrowserError(`The MCP's Chrome profile (${profileDir()}) is already open in another Chrome window. Close it and retry.`, 'PROFILE_LOCKED');
+        }
+        if (/Executable doesn't exist|Failed to launch|chrome.*not found|distribution/i.test(msg)) {
+            throw new LocalBrowserError(`Could not start Chrome (${executablePath ?? "channel 'chrome'"}). Install Google Chrome or set DEBUGGAI_CHROME_PATH. Detail: ${msg.split('\n')[0]}`, 'CHROME_NOT_FOUND');
+        }
+        throw err;
+    }
+}
+/** Aggregate responses by origin+path (query stripped), capped. */
+function summarize(entries) {
+    const map = new Map();
+    for (const e of entries) {
+        let key = e.url;
+        try {
+            const u = new URL(e.url);
+            key = u.origin + u.pathname;
+        }
+        catch { /* keep raw */ }
+        const row = map.get(key) ?? { url: key, count: 0, statuses: {}, totalBytes: 0 };
+        row.count++;
+        row.statuses[String(e.status)] = (row.statuses[String(e.status)] ?? 0) + 1;
+        row.totalBytes += e.bytes;
+        map.set(key, row);
+    }
+    return [...map.values()].sort((a, b) => b.count - a.count).slice(0, 50);
+}
+export async function localCapture(o) {
+    if (!localBrowserEnabled()) {
+        throw new LocalBrowserError('Local browser mode is off. Set DEBUGGAI_LOCAL_BROWSER=1 in the MCP server environment to allow it.', 'LOCAL_BROWSER_DISABLED');
+    }
+    const allowed = o.useProfile ? resolveAllowedDomains(o.allowedDomains) : [];
+    if (o.useProfile && allowed.length === 0) {
+        throw new LocalBrowserError('A profile session needs an allowlist of domains it may visit: pass allowedDomains (e.g. ["example.com"]) or have the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.', 'PROFILE_ALLOWLIST_REQUIRED');
+    }
+    const timeout = Math.min(Math.max(o.timeoutMs ?? 10000, 1000), 30000);
+    const { context, close } = await launch({ headless: o.headless !== false, useProfile: !!o.useProfile });
+    const onAbort = () => { void close().catch(() => { }); };
+    o.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        const page = context.pages()[0] ?? await context.newPage();
+        if (o.useProfile) {
+            const isLocal = (h) => ['localhost', '127.0.0.1', '[::1]', '::1'].includes(h);
+            const startHost = (() => { try {
+                return new URL(o.url).hostname;
+            }
+            catch {
+                return '';
+            } })();
+            if (!hostAllowed(startHost, allowed) && !isLocal(startHost)) {
+                throw new LocalBrowserError(`${startHost || o.url} is not in the allowlist for this profile session.`, 'DOMAIN_NOT_ALLOWED');
+            }
+            // Block top-level DOCUMENT loads off the allowlist, redirect hops included, via
+            // CDP Fetch (Playwright's route() never sees server-side redirect hops, so it
+            // cannot enforce this). Sub-resources (CDNs) pass.
+            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 () => {
+                        const check = (u) => {
+                            try {
+                                const h = new URL(u).hostname;
+                                return hostAllowed(h, allowed) || isLocal(h);
+                            }
+                            catch {
+                                return false;
+                            }
+                        };
+                        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)) {
+                                    blocked.push(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)) {
+                                    blocked.push(safeHost(next));
+                                    await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
+                                    return;
+                                }
+                            }
+                            await cdp.send('Fetch.continueResponse', { requestId: ev.requestId });
+                        }
+                        catch { /* page closed */ }
+                    })();
+                });
+            };
+            await guard(page);
+            context.on('page', (pg) => { void guard(pg).catch(() => { }); });
+        }
+        const blocked = [];
+        const consoleErrors = [];
+        const net = [];
+        page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning')
+            consoleErrors.push({ level: m.type(), text: m.text() }); });
+        page.on('pageerror', (e) => consoleErrors.push({ level: 'error', text: e.message }));
+        page.on('response', (r) => {
+            const len = Number(r.headers()['content-length'] ?? 0);
+            net.push({ url: r.url(), status: r.status(), bytes: Number.isFinite(len) ? len : 0 });
+        });
+        const t0 = Date.now();
+        let resp;
+        try {
+            resp = await page.goto(o.url, { waitUntil: o.waitForLoadState === 'load' ? 'load' : 'domcontentloaded', timeout });
+        }
+        catch (err) {
+            if (blocked.length > 0) {
+                throw new LocalBrowserError(`Navigation to ${[...new Set(blocked)].join(', ')} was blocked: not in this profile session's allowlist.`, 'NAVIGATION_BLOCKED');
+            }
+            throw err;
+        }
+        if (o.waitForSelector)
+            await page.waitForSelector(o.waitForSelector, { timeout: Math.max(1000, timeout - (Date.now() - t0)) });
+        else
+            await page.waitForLoadState('networkidle', { timeout: Math.min(2000, Math.max(500, timeout - (Date.now() - t0))) }).catch(() => { });
+        const result = {
+            url: o.url,
+            finalUrl: page.url() || null,
+            statusCode: resp ? resp.status() : null,
+            title: (await page.title().catch(() => '')) || null,
+            loadTimeMs: Date.now() - t0,
+            consoleErrors,
+            networkSummary: summarize(net),
+        };
+        if (blocked.length > 0)
+            result.blockedNavigations = [...new Set(blocked)];
+        if (o.loginWindowMs && o.useProfile && o.headless === false) {
+            const ms = Math.min(o.loginWindowMs, 600000);
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, ms);
+                context.once('close', () => { clearTimeout(t); resolve(); });
+            });
+        }
+        if (o.includeHtml)
+            result.html = await page.content();
+        if (o.captureScreenshot !== false) {
+            const buf = await page.screenshot({ type: 'png' });
+            result.screenshotBase64 = buf.toString('base64');
+            const dir = path.join(debuggHome(), 'captures');
+            ensurePrivateDir(dir);
+            const file = path.join(dir, `probe-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.png`);
+            fs.writeFileSync(file, buf, { mode: 0o600 });
+            result.screenshotPath = file;
+        }
+        return result;
+    }
+    finally {
+        o.signal?.removeEventListener('abort', onAbort);
+        await close().catch(() => { });
+    }
+}

package/dist/services/verdictAdapter.js

@@ -120,6 +120,23 @@ export function pollTimeoutReason(facts) {
     const head = parts.join(' ');
     return facts.lastStatus ? `${head}; last status: ${facts.lastStatus}.` : `${head}.`;
 }
+/**
+ * Counts over the login records (bead w1os.4) — numbers only, so the MCP
+ * authors no text (epic 56kd). The backend appends a `no_login_form_detected`
+ * record (submitted:false, authenticated:false) after a successful sign-in
+ * whenever a later page had no form; read alone it looks like a failed login.
+ * The raw records stay verbatim (bead ymq2); this just states the tally:
+ *   authenticated — records with authenticated:true
+ *   failed        — typed credentials (submitted:true) and did not authenticate
+ *   notAttempted  — nothing was typed (skipped or refused records)
+ */
+export function summarizeLogins(logins) {
+    if (!logins)
+        return undefined;
+    const authenticated = logins.filter((l) => l.authenticated === true).length;
+    const failed = logins.filter((l) => l.authenticated !== true && l.submitted === true).length;
+    return { total: logins.length, authenticated, failed, notAttempted: logins.length - authenticated - failed };
+}
 /** Credential sources that mean "the caller named this account for this run". */
 const CALLER_SPECIFIED_SOURCES = new Set(['task', 'explicit', 'credential_id']);
 /**

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;
@@ -128,11 +138,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,12 @@ 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."
                 },
+                extraOrigins: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Extra LOCAL origins this run may be redirected to, e.g. [\"http://host.docker.internal:4717\", \"http://localhost:4304\"] (a bare port like \"4304\" also works). Use for flows that hop between local servers — an OAuth consent page on another port, a callback on a third — which the remote browser otherwise cannot reach (DNS_PROBE_FINISHED_NXDOMAIN / connection refused). Redirects to these origins, and to the main url's origin, are followed through the tunnel; only origins listed here are exposed. Hosts allowed: localhost, 127.0.0.1, [::1], host.docker.internal. Limitation: absolute URLs written inside page HTML (not redirects) are not rewritten.",
+                    maxItems: 8
+                },
                 repoName: {
                     type: "string",
                     description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this if you want to run against a different project than the one you're in."

package/dist/types/index.js

@@ -64,6 +64,11 @@ 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(),
+    // 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
+    // here are exposed.
+    extraOrigins: z.array(z.string().min(1)).max(8, 'extraOrigins accepts at most 8 origins.').optional(),
     // Auth-precondition deep-link intent (bead 56kd.6) — "log in THEN go to X".
     auth: AuthPreconditionSchema.optional(),
 });
@@ -269,6 +274,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/artifactGrace.js

@@ -0,0 +1,29 @@
+const PENDING = /queue|pending|processing|uploading|downloading/i;
+export function artifactsPending(bs) {
+    if (!bs)
+        return false;
+    const statuses = [bs.recordingStatus, bs.harStatus, bs.consoleLogStatus];
+    return statuses.some((s) => typeof s === 'string' && PENDING.test(s));
+}
+function artifactsReady(bs) {
+    return !artifactsPending(bs) || (!!bs.harUrl && !!bs.consoleLogUrl);
+}
+export async function refreshPendingArtifacts(getExecution, executionUuid, current, opts = {}) {
+    const attempts = opts.attempts ?? 3;
+    const intervalMs = opts.intervalMs ?? 2000;
+    let latest = current;
+    for (let i = 0; i < attempts && artifactsPending(latest) && !(latest && artifactsReady(latest)); i++) {
+        if (opts.signal?.aborted)
+            break;
+        await new Promise((r) => setTimeout(r, intervalMs));
+        try {
+            const exec = await getExecution(executionUuid);
+            if (exec.browserSession)
+                latest = exec.browserSession;
+        }
+        catch {
+            break; // artifact refresh is best-effort; never fail the run for it
+        }
+    }
+    return latest;
+}

package/dist/utils/extraOrigins.js

@@ -0,0 +1,57 @@
+/**
+ * Extra local origins a run may be redirected to (bead w1os.2). Kept out of
+ * tunnelContext.ts so handler tests that mock that module are unaffected.
+ */
+import { tunnelManager } from '../services/tunnel/tunnelManager.js';
+import { extractLocalhostPort } from './urlParser.js';
+const EXTRA_ORIGIN_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1', 'host.docker.internal']);
+export class ExtraOriginError extends Error {
+    origin;
+    constructor(origin, reason) {
+        super(`extraOrigins entry "${origin}" ${reason}`);
+        this.origin = origin;
+        this.name = 'ExtraOriginError';
+    }
+}
+/** Parse `4304`, `localhost:4304`, or `http(s)://host.docker.internal:4717[/…]`. */
+export function parseExtraOrigin(raw) {
+    const t = raw.trim();
+    if (/^\d+$/.test(t)) {
+        const port = Number(t);
+        if (port < 1 || port > 65535)
+            throw new ExtraOriginError(raw, 'is not a valid port');
+        return { port };
+    }
+    let u;
+    try {
+        u = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(t) ? t : `http://${t}`);
+    }
+    catch {
+        throw new ExtraOriginError(raw, 'is not a URL, host:port, or port');
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:')
+        throw new ExtraOriginError(raw, 'must be http or https');
+    if (!EXTRA_ORIGIN_HOSTS.has(u.hostname.toLowerCase())) {
+        throw new ExtraOriginError(raw, 'must be localhost, 127.0.0.1, [::1] or host.docker.internal');
+    }
+    const isHttpsLocal = u.protocol === 'https:';
+    const port = u.port ? Number(u.port) : isHttpsLocal ? 443 : 80;
+    return { port, ...(isHttpsLocal ? { isHttpsLocal: true } : {}) };
+}
+/**
+ * Authorise the caller's extra origins on this session's Caddy and record them
+ * on the context. Call after `acquirePortRoute`. No-op without a tunnel.
+ */
+export async function authorizeExtraOrigins(ctx, raw) {
+    if (!raw || raw.length === 0 || !ctx.isLocalhost || !ctx.tunnelId)
+        return ctx;
+    const primaryPort = extractLocalhostPort(ctx.originalUrl);
+    const origins = raw.map(parseExtraOrigin).filter((o) => o.port !== primaryPort);
+    if (origins.length === 0)
+        return ctx;
+    const info = tunnelManager.getTunnelInfo(ctx.tunnelId);
+    if (!info)
+        throw new Error(`authorizeExtraOrigins: no TunnelInfo for tunnel ${ctx.tunnelId}`);
+    await info.caddy.addAuxOrigins(origins);
+    return { ...ctx, extraOrigins: origins };
+}

package/dist/utils/tunnelContext.js

@@ -9,6 +9,7 @@
  */
 import { tunnelManager, getSessionKey } from '../services/tunnel/tunnelManager.js';
 import { isLocalhostUrl, replaceTunnelUrls, retargetTunnelUrl, extractLocalhostPort } from './urlParser.js';
+import { AUX_PATH_PREFIX } from '../services/caddy/caddyProxy.js';
 // ─── URL resolution ──────────────────────────────────────────────────────────
 /**
  * Resolve tool input to a concrete URL string.
@@ -110,6 +111,12 @@ export function retargetAuxiliaryUrl(ctx, auxUrl) {
     const port = extractLocalhostPort(auxUrl);
     const primaryPort = extractLocalhostPort(ctx.originalUrl);
     if (port !== undefined && primaryPort !== undefined && port !== primaryPort) {
+        // Bead w1os.2: a port the caller authorised via extraOrigins is reachable at /__o/<port>/.
+        if (ctx.extraOrigins?.some((o) => o.port === port)) {
+            const t = new URL(auxUrl);
+            const base = new URL(ctx.targetUrl);
+            return { ok: true, url: `${base.origin}${AUX_PATH_PREFIX}/${port}${t.pathname}${t.search}${t.hash}`, rewritten: true };
+        }
         return { ok: false, reason: 'port_mismatch', port, primaryPort };
     }
     return { ok: true, url: retargetTunnelUrl(ctx.targetUrl, auxUrl), rewritten: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "6.1.4",
+  "version": "6.1.6",
   "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"
   }
 }