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

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.2.0] — 2026-11-13
+
+> Local click-through needs a backend with local executors enabled (platform flag `EXECUTORS_LOCAL_ENABLED`) and `DEBUGGAI_LOCAL_BROWSER=1` on the MCP server. Without both, nothing changes for existing calls.
+
+### Added — check_app_in_browser on your local Chrome, cloud brain (`browser: "local"`) (epic m7un)
+- New `browser: "local"` (also `headless`, `useProfile`, `allowedDomains`) runs the check in Chrome on your machine while the cloud brain decides each step. The laptop dials out, so no tunnel is needed for localhost or private apps. Opt-in: set `DEBUGGAI_LOCAL_BROWSER=1` in the MCP server environment; stdio only (not the remote HTTP/OAuth server). The platform side is flag-gated, so it needs a backend that has local executors enabled.
+- Uses the sense/think/act brain (`flow/tools/browse`; `DEBUGGAI_LOCAL_TEMPLATE` overrides the slug). The `browser_use` App Evaluation template cannot drive a local browser and is refused by the backend for local runs.
+- Safety: every navigation hop (redirects included) is checked against an allowlist of the target host plus `allowedDomains`/`extraOrigins`; an empty allowlist is refused. Passwords you pass are never sent to the cloud: the brain sees `{{cred:label}}` and the MCP substitutes it locally. Stored environment credentials arrive sealed to a per-session public key and are opened only on your machine. No cookies, HAR or login state are uploaded.
+- Screenshots go to the cloud by default (the brain needs them); `DEBUGGAI_LOCAL_SCREENSHOTS=local_only` keeps them on disk and sends a 1x1 placeholder. Full captures are written under `~/.debugg-ai/captures` (0600).
+- `useProfile` uses an MCP-owned Chrome profile (`~/.debugg-ai/chrome-profile`), never your real Chrome, and requires an allowlist. Note: it keeps persistent cookies between runs but not session cookies (Chrome drops them on close), so an app whose login is a session cookie will ask you to sign in again on the next run.
+- Limits are configuration from the server (heartbeat, lease, in-flight concurrency), not hard-coded in the client. Retries are off for local runs (a retry needs a fresh session). `LOG_LEVEL=debug` logs each executor command.
+- Verified against a flag-on backend: a click-through, a credentialed multi-step login with task creation, and cancel mid-run (call returns at once, Chrome closed).
+
 ### Changed — test_suite `run` retired (platform-g3am)
 - The server removed its suite-run route, so `run` only produced a raw HTML 404. It is gone from the tool's actions and description; a call from an older client now returns an `ActionRetired` error naming `results`, `check_app_in_browser` and `trigger_crawl`, without contacting the server.
 

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

package/dist/handlers/localExecutorBridge.js

@@ -0,0 +1,152 @@
+/**
+ * check_app_in_browser with browser:'local' (epic m7un). The cloud workflow runs as
+ * usual but its page calls are served by the Chrome on THIS machine through the
+ * Executor API v1 (sentinal docs/local-executor-api-design.md). This module owns the
+ * MCP side: create the session, hold Chrome, attach + serve commands while the
+ * workflow executes, tear down. The handler only calls prepare / begin / end.
+ */
+import { config } from '../config/index.js';
+import { logger } from '../utils/logger.js';
+import { localBrowserEnabled, LocalBrowserError, resolveAllowedDomains } from '../services/localBrowser.js';
+import { OpRunner } from '../services/localExecutor/opRunner.js';
+import { runExecutorSession } from '../services/localExecutor/session.js';
+import { HttpExecutorTransport } from '../services/localExecutor/httpTransport.js';
+import { generateSessionKeys } from '../services/localExecutor/credentialBox.js';
+/**
+ * Passwords never go to the cloud for a local run: the workflow gets `{{cred:<label>}}`
+ * and the real value stays here. Environment-stored credentials (credentialId/role)
+ * live in the cloud and are not handled by this path yet.
+ */
+export function localizeCredentials(input) {
+    const secrets = {};
+    const ph = (label, password) => { secrets[label] = password; return `{{cred:${label}}}`; };
+    const out = { ...input };
+    if (input.username && input.password)
+        out.password = ph(input.username, input.password);
+    if (input.loginCredentials) {
+        out.loginCredentials = input.loginCredentials.map((c) => ({ ...c, password: ph(c.label ?? c.username, c.password) }));
+    }
+    if (input.auth?.password && input.auth.username) {
+        out.auth = { ...input.auth, password: ph(input.auth.username, input.auth.password) };
+    }
+    return { input: out, secrets };
+}
+export function localAllowedDomains(input, startUrl) {
+    const startHost = (() => { try {
+        return new URL(startUrl).hostname;
+    }
+    catch {
+        return '';
+    } })();
+    const extra = (input.extraOrigins ?? []).map((o) => { try {
+        return new URL(/^\d+$/.test(o) ? `http://localhost:${o}` : o).hostname;
+    }
+    catch {
+        return '';
+    } });
+    if (input.useProfile)
+        return resolveAllowedDomains(input.allowedDomains);
+    return [startHost, ...(input.allowedDomains ?? []), ...extra].filter(Boolean);
+}
+export async function prepareLocalRun(args) {
+    const { client, input, startUrl, secrets, signal } = args;
+    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 = localAllowedDomains(input, startUrl);
+    if (allowed.length === 0) {
+        throw new LocalBrowserError('A profile session needs an allowlist of domains it may visit: pass allowedDomains or have the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.', 'PROFILE_ALLOWLIST_REQUIRED');
+    }
+    const headless = input.headless !== false;
+    const screenshotsMode = process.env.DEBUGGAI_LOCAL_SCREENSHOTS === 'local_only' ? 'local_only' : 'cloud';
+    // Chrome starts while the session is being created and the workflow queued.
+    // Mutable on purpose: stored credentials are decrypted into it once the session exists.
+    const liveSecrets = { ...secrets };
+    const keys = generateSessionKeys();
+    const runnerP = OpRunner.open({ allowedDomains: allowed, headless, useProfile: !!input.useProfile, secrets: liveSecrets, screenshots: screenshotsMode, signal });
+    runnerP.catch(() => { });
+    let created;
+    try {
+        created = await client.tx.post('api/v1/executors/sessions', {
+            executor: 'local',
+            allowedDomains: allowed,
+            headless,
+            viewport: { w: 1280, h: 800 },
+            capture: { screenshots: screenshotsMode },
+            // Public half only. The private key never leaves this process.
+            executorPublicKey: keys.publicKey,
+            ...(args.projectId ? { projectId: args.projectId } : {}),
+            ...(input.environmentId ? { environmentId: input.environmentId } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+            ...(input.credentialRole ? { credentialRole: input.credentialRole } : {}),
+        });
+    }
+    catch (err) {
+        (await runnerP.catch(() => null))?.close();
+        const status = err?.response?.status;
+        if (status === 404) {
+            throw new LocalBrowserError('The DebuggAI backend does not offer local browser execution yet (executor API not enabled for this account).', 'LOCAL_EXECUTOR_UNAVAILABLE');
+        }
+        throw err;
+    }
+    const runner = await runnerP;
+    if (created.captureMode === 'cloud' || created.captureMode === 'local_only')
+        runner.setCaptureMode(created.captureMode);
+    if (typeof created.headless === 'boolean' && created.headless !== (headless !== false)) {
+        logger.warn(`Server runs this session with headless=${created.headless}; the local browser was already launched with headless=${headless !== false}.`);
+    }
+    for (const c of created.credentials ?? []) {
+        try {
+            const pw = keys.open(c.sealed, created.sessionId);
+            liveSecrets[c.label] = pw;
+            // The backend names the placeholder after the label OR the username depending on the resolution path; accept both.
+            if (c.username && !(c.username in liveSecrets))
+                liveSecrets[c.username] = pw;
+        }
+        catch (err) {
+            logger.warn(`Could not open stored credential "${c.label}" (${err instanceof Error ? err.message : 'decrypt failed'})`);
+        }
+    }
+    const limits = {
+        heartbeat_s: created.limits?.heartbeatS ?? 10,
+        lease_s: created.limits?.leaseS ?? 45,
+        max_inline_bytes: created.limits?.maxInlineBytes ?? 1_000_000,
+        max_batch: created.limits?.maxBatch ?? 1,
+        ...(created.limits?.maxInflight ? { max_inflight: created.limits.maxInflight } : {}),
+    };
+    const transport = new HttpExecutorTransport({
+        baseUrl: config.api.baseUrl,
+        authorization: `${config.api.tokenType === 'bearer' ? 'Bearer' : 'Token'} ${config.api.key}`,
+        sessionId: created.sessionId,
+        secret: created.secret,
+    });
+    runner.setUploader((url, ct, bytes) => transport.upload(url, ct, bytes));
+    const stop = new AbortController();
+    const onAbort = () => stop.abort();
+    signal.addEventListener('abort', onAbort, { once: true });
+    let running;
+    return {
+        sessionId: created.sessionId,
+        begin() {
+            running = runExecutorSession({
+                transport, runner, limits, signal: stop.signal,
+                attach: {
+                    executor_version: 'debugg-ai-mcp',
+                    ops_supported: OpRunner.supportedOps(),
+                    browser: { name: 'chrome', headless },
+                    profile: input.useProfile ? 'mcp_owned' : 'ephemeral',
+                    credential_labels: Object.keys(liveSecrets),
+                },
+            }).catch((err) => { logger.warn(`local executor session failed: ${err instanceof Error ? err.message : err}`); return { ended: 'lease_lost', commandsRun: 0 }; });
+        },
+        async end() {
+            signal.removeEventListener('abort', onAbort);
+            if (!running) {
+                await runner.close();
+                return { ended: 'not_started', commandsRun: 0 };
+            }
+            stop.abort();
+            return running;
+        },
+    };
+}

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

@@ -9,7 +9,7 @@ import { Logger } from '../utils/logger.js';
 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 { getEvalTemplateSlug, getLocalBrowseTemplateSlug } from '../services/workflows.js';
 import { authorizeExtraOrigins, ExtraOriginError } from '../utils/extraOrigins.js';
 import { refreshPendingArtifacts } from '../utils/artifactGrace.js';
 import { adaptVerdict, credentialSubstitutions, summarizeLogins } from '../services/verdictAdapter.js';
@@ -23,6 +23,8 @@ import { extractLocalhostPort, rewriteLocalhostInText } from '../utils/urlParser
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { prepareLocalRun, localizeCredentials } from './localExecutorBridge.js';
+import { LocalBrowserError } from '../services/localBrowser.js';
 import { projectRequiredMessage, projectLookupFailedPayload } from '../utils/projectRequired.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
 // Bead kbxy: bounded retry on known transient backend signatures (Pydantic
@@ -136,6 +138,15 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         : undefined;
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
+    // browser:'local': Chrome on this machine does the clicking (no tunnel); passwords stay local.
+    const localMode = input.browser === 'local';
+    let localSecrets = {};
+    if (localMode) {
+        const l = localizeCredentials(input);
+        input = l.input;
+        localSecrets = l.secrets;
+    }
+    let localRun;
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
     let provision;
@@ -227,14 +238,14 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // is a billed leak, and beats a backend node failing mid-run.
         if (!projectUuid && !namedEnvironmentId && lookupError !== undefined && repoName) {
             // The lookup FAILED — not "no project linked" (platform-y2ob.4).
-            const payload = projectLookupFailedPayload(repoName, lookupError);
+            const payload = projectLookupFailedPayload(repoName, lookupError, false);
             logger.warn(`check_app_in_browser: ${payload.message}`);
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
         }
         if (!projectUuid && !namedEnvironmentId) {
             const payload = {
                 error: 'ProjectRequired',
-                message: projectRequiredMessage(repoName),
+                message: projectRequiredMessage(repoName, false),
             };
             logger.warn(`check_app_in_browser: ${payload.message}`);
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
@@ -263,7 +274,10 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
                 }
             }
-            if (config.devMode) {
+            if (localMode) {
+                logger.info(`check_app_in_browser: local browser — no tunnel for ${ctx.originalUrl}`);
+            }
+            else if (config.devMode) {
                 // Dev mode: local backend can reach localhost directly — no tunnel needed.
                 logger.info(`check_app_in_browser: dev mode — using localhost URL directly: ${ctx.originalUrl}`);
             }
@@ -375,11 +389,14 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // Cache key = the dispatch slug so the cache key and the lookup can never
         // drift apart (bug clka: the key used to be a decoupled 'app evaluation'
         // literal while the lookup searched a different string).
-        const templateUuid = await getCachedTemplateUuid(getEvalTemplateSlug(), async () => {
-            return client.workflows.findEvaluationTemplate();
+        const templateSlug = localMode ? getLocalBrowseTemplateSlug() : getEvalTemplateSlug();
+        const templateUuid = await getCachedTemplateUuid(templateSlug, async () => {
+            return localMode
+                ? client.workflows.findTemplateBySlug(templateSlug)
+                : client.workflows.findEvaluationTemplate();
         });
         if (!templateUuid) {
-            throw new Error(`App Evaluation workflow template not found (slug "${getEvalTemplateSlug()}").`);
+            throw new Error(`${localMode ? 'Local browse' : 'App Evaluation'} workflow template not found (slug "${templateSlug}").`);
         }
         // --- Build context data (camelCase here — axiosTransport auto-converts to snake_case) ---
         const contextData = {
@@ -395,6 +412,11 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             contextData.projectId = projectUuid;
         }
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
+        if (localMode) {
+            localRun = await prepareLocalRun({ client, input, startUrl: originalUrl, secrets: localSecrets, signal: abortController.signal, projectId: projectUuid || undefined });
+            contextData.executorSessionId = localRun.sessionId;
+            contextData.goal = contextData.question; // flow/tools/browse reads `goal`
+        }
         // Bead 56kd.6: forward the auth-precondition deep-link intent verbatim per
         // backend contract sentinal-k8x1f.8 (contextData.auth). Thin relay — express
         // intent + forward; the backend authenticates then navigates to deepUrl. Only
@@ -504,7 +526,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         //   28:    Complete
         const BACKEND_SETUP_END = 6;
         const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
-        const MAX_RETRIES = getMaxTransientRetries();
+        const MAX_RETRIES = localMode ? 0 : getMaxTransientRetries(); // a retry would need a fresh local session
         let executeResponse;
         let executionUuid = '';
         let finalExecution;
@@ -539,6 +561,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             // the target forward; the previous attempt already reached a terminal
             // state, so there is nothing to cancel there).
             currentExecutionUuid = executionUuid;
+            localRun?.begin();
             logger.info(`Execution queued: ${executionUuid}${attempt > 1 ? ` (retry ${attempt - 1}/${MAX_RETRIES})` : ''}`);
             // The abort can fire BEFORE anything is queued — while provisioning the
             // tunnel or resolving the template — and there is no abort check between
@@ -930,6 +953,11 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         return tunnelFault ? { content, isError: true } : { content };
     }
     catch (error) {
+        if (error instanceof LocalBrowserError) {
+            const payload = { error: error.code, message: error.message };
+            logger.warn(`check_app_in_browser (local): ${error.code}: ${error.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
         const duration = Date.now() - startTime;
         logger.toolError('check_app_in_browser', error, duration);
         if (error instanceof Error && (error.message.includes('not found') || error.message.includes('401'))) {
@@ -939,6 +967,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
+        await localRun?.end().catch(() => { });
         if (requestSignal)
             requestSignal.removeEventListener('abort', onAbort);
         // §2.4: release this call's claim on the shared port route (no-op if we

package/dist/services/localBrowser.js

@@ -0,0 +1,207 @@
+/**
+ * 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';
+import { installNavigationGuard, isLoopbackHost } from './navigationGuard.js';
+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');
+    }
+}
+export function ensurePrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export 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();
+        const blocked = [];
+        if (o.useProfile) {
+            const startHost = (() => { try {
+                return new URL(o.url).hostname;
+            }
+            catch {
+                return '';
+            } })();
+            if (!hostAllowed(startHost, allowed) && !isLoopbackHost(startHost)) {
+                throw new LocalBrowserError(`${startHost || o.url} is not in the allowlist for this profile session.`, 'DOMAIN_NOT_ALLOWED');
+            }
+            await installNavigationGuard(context, allowed, (h) => blocked.push(h));
+        }
+        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/localExecutor/credentialBox.js

@@ -0,0 +1,43 @@
+/**
+ * Sealed-box credential delivery. The executor makes a fresh X25519 keypair per session
+ * and sends ONLY the public key at session creation. The server decrypts a stored
+ * credential with its own key (which never leaves the server), then re-encrypts it to
+ * this public key before it enters any queue or response. Only this process can open it.
+ *
+ * Envelope (JSON, all base64): { v:1, alg:'x25519-hkdf-sha256-aes256gcm', epk, iv, ct, tag }
+ *   epk = sender's ephemeral X25519 public key, SPKI DER
+ *   key = HKDF-SHA256(ikm = ECDH(epk, recipient private), salt = empty, info = 'debuggai-executor-credential-v1', 32 bytes)
+ *   ct/tag = AES-256-GCM(key, iv(12 bytes), plaintext); AAD = the session id
+ */
+import crypto from 'node:crypto';
+export const SEAL_ALG = 'x25519-hkdf-sha256-aes256gcm';
+export const SEAL_INFO = 'debuggai-executor-credential-v1';
+export function generateSessionKeys() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+    return {
+        publicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+        open(env, sessionId) {
+            if (env.v !== 1 || env.alg !== SEAL_ALG)
+                throw new Error(`Unsupported credential envelope (${env.alg}).`);
+            const epk = crypto.createPublicKey({ key: Buffer.from(env.epk, 'base64'), type: 'spki', format: 'der' });
+            const shared = crypto.diffieHellman({ privateKey, publicKey: epk });
+            const key = Buffer.from(crypto.hkdfSync('sha256', shared, Buffer.alloc(0), SEAL_INFO, 32));
+            const d = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+            d.setAAD(Buffer.from(sessionId));
+            d.setAuthTag(Buffer.from(env.tag, 'base64'));
+            return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]).toString('utf8');
+        },
+    };
+}
+/** Reference sealer (server side lives in the platform repo; used here for tests and as the spec). */
+export function sealTo(publicKeyB64, plaintext, sessionId) {
+    const recipient = crypto.createPublicKey({ key: Buffer.from(publicKeyB64, 'base64'), type: 'spki', format: 'der' });
+    const eph = crypto.generateKeyPairSync('x25519');
+    const shared = crypto.diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
+    const key = Buffer.from(crypto.hkdfSync('sha256', shared, Buffer.alloc(0), SEAL_INFO, 32));
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+    c.setAAD(Buffer.from(sessionId));
+    const ct = Buffer.concat([c.update(plaintext, 'utf8'), c.final()]);
+    return { v: 1, alg: SEAL_ALG, epk: eph.publicKey.export({ type: 'spki', format: 'der' }).toString('base64'), iv: iv.toString('base64'), ct: ct.toString('base64'), tag: c.getAuthTag().toString('base64') };
+}