@debugg-ai/debugg-ai-mcp 6.1.6 → 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/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/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

@@ -14,6 +14,7 @@
 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) {
@@ -70,18 +71,10 @@ async function loadPlaywright() {
         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) {
+export function ensurePrivateDir(dir) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
-async function launch(opts) {
+export async function launch(opts) {
     const pw = await loadPlaywright();
     const executablePath = findChrome();
     const base = { headless: opts.headless, ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
@@ -139,71 +132,19 @@ export async function localCapture(o) {
     o.signal?.addEventListener('abort', onAbort, { once: true });
     try {
         const page = context.pages()[0] ?? await context.newPage();
+        const blocked = [];
         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)) {
+            if (!hostAllowed(startHost, allowed) && !isLoopbackHost(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(() => { }); });
+            await installNavigationGuard(context, allowed, (h) => blocked.push(h));
         }
-        const blocked = [];
         const consoleErrors = [];
         const net = [];
         page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning')

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') };
+}

package/dist/services/localExecutor/httpTransport.js

@@ -0,0 +1,72 @@
+import { API_VERSION } from './ops.js';
+export const EXECUTOR_PATHS = {
+    attach: (id) => `/api/v1/executors/sessions/${id}/attach`,
+    commands: (id, waitS) => `/api/v1/executors/sessions/${id}/commands?wait=${waitS}`,
+    results: (id) => `/api/v1/executors/sessions/${id}/results`,
+    heartbeat: (id) => `/api/v1/executors/sessions/${id}/heartbeat`,
+    cancel: (id) => `/api/v1/executors/sessions/${id}/cancel`,
+};
+export class HttpTransportError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class HttpExecutorTransport {
+    o;
+    constructor(o) {
+        this.o = o;
+    }
+    async req(method, path, body, signal) {
+        const f = this.o.fetchImpl ?? fetch;
+        const res = await f(this.o.baseUrl.replace(/\/$/, '') + path, {
+            method,
+            signal,
+            headers: {
+                authorization: this.o.authorization,
+                'x-executor-secret': this.o.secret,
+                'x-executor-api-version': String(API_VERSION),
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (res.status === 204)
+            return null;
+        if (!res.ok)
+            throw new HttpTransportError(`${method} ${path.split('?')[0]} -> HTTP ${res.status}`, res.status);
+        const text = await res.text();
+        return text ? JSON.parse(text) : null;
+    }
+    /** PUT raw bytes to a command's upload_url with the executor auth headers; returns the server's `ref`. */
+    async upload(url, contentType, bytes) {
+        const f = this.o.fetchImpl ?? fetch;
+        const res = await f(url, {
+            method: 'PUT',
+            headers: { authorization: this.o.authorization, 'x-executor-secret': this.o.secret, 'x-executor-api-version': String(API_VERSION), 'content-type': contentType },
+            body: bytes,
+        });
+        if (!res.ok)
+            throw new HttpTransportError(`PUT upload -> HTTP ${res.status}`, res.status);
+        const text = await res.text();
+        let ref;
+        try {
+            ref = text ? JSON.parse(text).ref : undefined;
+        }
+        catch { /* not json */ }
+        return typeof ref === 'string' && ref ? ref : url.split('?')[0];
+    }
+    async attach(info) { await this.req('POST', EXECUTOR_PATHS.attach(this.o.sessionId), info); }
+    async poll(waitS, signal) {
+        const r = await this.req('GET', EXECUTOR_PATHS.commands(this.o.sessionId, waitS), undefined, signal);
+        if (Array.isArray(r))
+            return r;
+        const o = (r ?? {});
+        return { commands: o.commands ?? [], cancel: o.cancel, drain: o.drain };
+    }
+    async postResults(results) { await this.req('POST', EXECUTOR_PATHS.results(this.o.sessionId), { results }); }
+    async heartbeat() {
+        const r = (await this.req('POST', EXECUTOR_PATHS.heartbeat(this.o.sessionId), {}));
+        return { cancel: !!r?.cancel, drain: !!r?.drain };
+    }
+}

package/dist/services/localExecutor/opRunner.js

@@ -0,0 +1,437 @@
+/**
+ * OpRunner: executes ONE Command in real local Chrome (playwright-core) and returns a
+ * CommandResult. Thin by design: Playwright's own semantics (auto-wait, actionability)
+ * do the work; this layer serialises, enforces the allowlist on every navigation hop,
+ * substitutes credential placeholders locally, redacts, and reports page events.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { launch, localBrowserEnabled, LocalBrowserError, hostAllowed, resolveAllowedDomains, debuggHome, ensurePrivateDir } from '../localBrowser.js';
+import { installNavigationGuard, isLoopbackHost } from '../navigationGuard.js';
+import { OPS } from './ops.js';
+const SECRET_RE = /\{\{cred:([^}]+)\}\}/g;
+const PX = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DwHwAFAAH/iqLiWAAAAABJRU5ErkJggg==';
+class OpError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+export class OpRunner {
+    context;
+    closeBrowser;
+    opts;
+    events = [];
+    emit(e) { this.events.push({ ...e, ts: Date.now() }); }
+    pages = new Map();
+    ids = new Map();
+    nextPage = 1;
+    currentId = '';
+    closed = false;
+    blocked = [];
+    uploader;
+    /** Set once the session exists (auth headers are known only then). Without it, uploads fall back to an unauthenticated PUT. */
+    /** The server's effective capture mode wins over the local default (it is deployment config, not a per-request choice). */
+    setCaptureMode(mode) { this.opts.screenshots = mode; }
+    setUploader(fn) { this.uploader = fn; }
+    constructor(context, closeBrowser, opts) {
+        this.context = context;
+        this.closeBrowser = closeBrowser;
+        this.opts = opts;
+    }
+    static supportedOps() { return OPS; }
+    static async open(opts) {
+        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 = opts.useProfile ? resolveAllowedDomains(opts.allowedDomains) : opts.allowedDomains;
+        if (allowed.length === 0) {
+            throw new LocalBrowserError('A local session needs a non-empty domain allowlist (allowedDomains, or DEBUGGAI_PROFILE_ALLOWED_DOMAINS for profile sessions).', 'ALLOWLIST_REQUIRED');
+        }
+        const { context, close } = await launch({ headless: opts.headless !== false, useProfile: !!opts.useProfile });
+        try {
+            const r = new OpRunner(context, close, { ...opts, allowedDomains: allowed });
+            const vp = opts.viewport ?? { width: 1280, height: 800 };
+            const first = context.pages()[0] ?? await context.newPage();
+            await first.setViewportSize(vp).catch(() => { });
+            await installNavigationGuard(context, allowed, (h) => r.blocked.push(h));
+            r.register(first);
+            context.on('page', (pg) => { const id = r.register(pg); r.emit({ type: 'popup', page_id: id, url: pg.url() }); });
+            opts.signal?.addEventListener('abort', () => { void r.close(); }, { once: true });
+            return r;
+        }
+        catch (err) {
+            await close().catch(() => { });
+            throw err;
+        }
+    }
+    register(pg) {
+        const id = `p${this.nextPage++}`;
+        this.pages.set(id, pg);
+        this.ids.set(pg, id);
+        this.currentId = id;
+        pg.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning')
+            this.emit({ type: 'console', level: m.type(), text: m.text().slice(0, 500) }); });
+        pg.on('pageerror', (e) => this.emit({ type: 'console', level: 'error', text: e.message.slice(0, 500) }));
+        pg.on('response', (r) => { if (r.status() >= 400)
+            this.emit({ type: 'request_failed', url: stripQuery(r.url()), status: r.status() }); });
+        pg.on('requestfailed', (r) => this.emit({ type: 'request_failed', url: stripQuery(r.url()), status: 'aborted' }));
+        pg.on('dialog', (d) => {
+            this.emit({ type: 'dialog', dialog: d.type(), message: d.message().slice(0, 300) });
+            void (d.type() === 'beforeunload' ? d.accept() : d.dismiss()).catch(() => { });
+        });
+        pg.on('download', (d) => this.emit({ type: 'download', url: stripQuery(d.url()), filename: d.suggestedFilename() }));
+        pg.on('close', () => { this.pages.delete(id); this.ids.delete(pg); if (this.currentId === id)
+            this.currentId = [...this.pages.keys()].pop() ?? ''; });
+        return id;
+    }
+    page(cmd) {
+        const id = cmd.target?.page_id || this.currentId;
+        const pg = this.pages.get(id);
+        if (!pg || pg.isClosed())
+            throw new OpError('invalid_args', `No open page${id ? ` with id ${id}` : ''}.`);
+        return pg;
+    }
+    locator(pg, cmd) {
+        const sel = cmd.target?.selector;
+        if (!sel)
+            throw new OpError('invalid_args', `${cmd.op} needs target.selector.`);
+        let scope = pg;
+        for (const f of cmd.target?.frame ?? [])
+            scope = scope.frameLocator(f);
+        return scope.locator(sel);
+    }
+    async execute(cmd) {
+        const t0 = Date.now();
+        this.blocked = [];
+        const base = { command_id: cmd.id };
+        if (this.closed)
+            return { ...base, ok: false, duration_ms: 0, error: { code: 'cancelled', message: 'executor is closed', retryable: false } };
+        if (!OPS.includes(cmd.op)) {
+            return { ...base, ok: false, duration_ms: 0, error: { code: 'unsupported_op', message: `Unsupported op: ${cmd.op}`, retryable: false, detail: { op: cmd.op } } };
+        }
+        let observation;
+        let error;
+        let abortTimer;
+        try {
+            const work = this.run(cmd);
+            const guarded = cmd.deadline_ms
+                ? Promise.race([work, new Promise((_r, rej) => { abortTimer = setTimeout(() => rej(new OpError('timeout', `Command exceeded deadline_ms=${cmd.deadline_ms}.`)), cmd.deadline_ms); })])
+                : work;
+            observation = await guarded;
+        }
+        catch (err) {
+            error = await this.toError(err, cmd);
+        }
+        finally {
+            if (abortTimer)
+                clearTimeout(abortTimer);
+        }
+        const pg = this.pages.get(cmd.target?.page_id || this.currentId);
+        const out = {
+            ...base, ok: !error, duration_ms: Date.now() - t0,
+            url: pg && !pg.isClosed() ? pg.url() : undefined,
+            title: pg && !pg.isClosed() ? await pg.title().catch(() => undefined) : undefined,
+            events: this.events.splice(0).slice(0, 100),
+            ...(observation ? { observation } : {}),
+            ...(error ? { error } : {}),
+        };
+        return this.redactSecrets(out);
+    }
+    /**
+     * Nothing the cloud receives may contain a live secret. The page itself can echo one back (the brain's
+     * snapshot script reads every input's value, so a filled password field returns the real password), so
+     * scrub every string in the result, replacing the value with its placeholder. Screenshot pixels are
+     * left alone (password inputs are masked by the browser).
+     */
+    redactSecrets(result) {
+        const pairs = Object.entries(this.opts.secrets ?? {}).filter(([, v]) => typeof v === 'string' && v.length > 0).sort((a, b) => b[1].length - a[1].length);
+        if (pairs.length === 0)
+            return result;
+        const walk = (v, key) => {
+            if (typeof v === 'string') {
+                if (key === 'base64')
+                    return v;
+                let o = v;
+                for (const [label, val] of pairs)
+                    if (o.includes(val))
+                        o = o.split(val).join(`{{cred:${label}}}`);
+                return o;
+            }
+            if (Array.isArray(v))
+                return v.map((x) => walk(x));
+            if (v && typeof v === 'object')
+                return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, k)]));
+            return v;
+        };
+        return walk(result);
+    }
+    sub(v) {
+        const s = typeof v === 'string' ? v : String(v ?? '');
+        return s.replace(SECRET_RE, (_m, label) => {
+            const val = this.opts.secrets?.[label];
+            if (val === undefined)
+                throw new OpError('invalid_args', `Unknown credential placeholder {{cred:${label}}}.`);
+            return val;
+        });
+    }
+    to(cmd) {
+        const t = cmd.args?.timeout_ms;
+        return typeof t === 'number' ? t : this.opts.defaultTimeoutMs;
+    }
+    async run(cmd) {
+        const a = cmd.args ?? {};
+        const timeout = this.to(cmd);
+        const act = { kind: 'action' };
+        switch (cmd.op) {
+            case 'goto': {
+                const pg = this.page(cmd);
+                const url = String(a.url ?? '');
+                let host;
+                try {
+                    host = new URL(url).hostname;
+                }
+                catch {
+                    throw new OpError('invalid_args', `Invalid URL: ${url}`);
+                }
+                if (!hostAllowed(host, this.opts.allowedDomains) && !isLoopbackHost(host))
+                    throw new OpError('domain_blocked', `${host} is not in this session's allowlist (${this.opts.allowedDomains.join(', ')}).`, false);
+                const resp = await pg.goto(url, { waitUntil: a.wait_until ?? 'domcontentloaded', timeout });
+                return { kind: 'action', value: { status: resp?.status() ?? null } };
+            }
+            case 'back':
+                await this.page(cmd).goBack({ waitUntil: 'domcontentloaded', timeout });
+                return act;
+            case 'forward':
+                await this.page(cmd).goForward({ waitUntil: 'domcontentloaded', timeout });
+                return act;
+            case 'reload':
+                await this.page(cmd).reload({ waitUntil: 'domcontentloaded', timeout });
+                return act;
+            case 'evaluate': {
+                const pg = this.page(cmd);
+                const expr = String(a.expression ?? '');
+                // Playwright does not invoke a function passed as a string, so run the source ourselves: a
+                // function source is called with (element?, arg); any other expression is returned as its value.
+                const value = cmd.target?.selector
+                    ? await this.locator(pg, cmd).first().evaluate((el, [src, arg]) => { const f = (0, eval)('(' + src + ')'); return typeof f === 'function' ? f(el, arg) : f; }, [expr, a.arg], { timeout })
+                    : await pg.evaluate(([src, arg]) => { const f = (0, eval)('(' + src + ')'); return typeof f === 'function' ? f(arg) : f; }, [expr, a.arg]);
+                return { kind: 'eval', value: value === undefined ? null : value };
+            }
+            case 'click': {
+                const loc = this.locator(this.page(cmd), cmd).first();
+                const o = { timeout, button: a.button, force: a.force };
+                if (a.double)
+                    await loc.dblclick(o);
+                else
+                    await loc.click(o);
+                return act;
+            }
+            case 'dblclick':
+                await this.locator(this.page(cmd), cmd).first().dblclick({ timeout, force: a.force });
+                return act;
+            case 'fill':
+                await this.locator(this.page(cmd), cmd).first().fill(this.sub(a.value ?? a.text), { timeout });
+                return act;
+            case 'type':
+                await this.locator(this.page(cmd), cmd).first().pressSequentially(this.sub(a.text ?? a.value), { timeout, delay: (a.delay_ms ?? a.delay) });
+                return act;
+            case 'press': {
+                const key = this.sub(a.key);
+                if (cmd.target?.selector)
+                    await this.locator(this.page(cmd), cmd).first().press(key, { timeout });
+                else
+                    await this.page(cmd).keyboard.press(key);
+                return act;
+            }
+            case 'hover':
+                await this.locator(this.page(cmd), cmd).first().hover({ timeout });
+                return act;
+            case 'select_option': {
+                const v = a.index !== undefined ? { index: Number(a.index) } : a.label !== undefined ? { label: String(a.label) } : (a.values ?? a.value);
+                await this.locator(this.page(cmd), cmd).first().selectOption(v, { timeout });
+                return act;
+            }
+            case 'check':
+                await this.locator(this.page(cmd), cmd).first().check({ timeout });
+                return act;
+            case 'uncheck':
+                await this.locator(this.page(cmd), cmd).first().uncheck({ timeout });
+                return act;
+            case 'focus':
+                await this.locator(this.page(cmd), cmd).first().focus({ timeout });
+                return act;
+            case 'scroll': {
+                const pg = this.page(cmd);
+                const to = a.to_selector ?? cmd.target?.selector;
+                if (to)
+                    await (a.to_selector ? pg.locator(to) : this.locator(pg, cmd)).first().scrollIntoViewIfNeeded({ timeout });
+                else
+                    await pg.mouse.wheel(Number(a.dx ?? a.x ?? 0), Number(a.dy ?? a.y ?? 600));
+                return act;
+            }
+            case 'wait_for_selector':
+                await this.locator(this.page(cmd), cmd).first().waitFor({ state: a.state ?? 'visible', timeout });
+                return act;
+            case 'wait_for_load_state':
+                await this.page(cmd).waitForLoadState(a.state ?? 'load', { timeout });
+                return act;
+            case 'wait_for_function':
+                await this.page(cmd).waitForFunction(String(a.expression ?? ''), a.arg, { timeout });
+                return act;
+            case 'query': return { kind: 'query', value: await this.query(this.locator(this.page(cmd), cmd).first(), String(a.what ?? a.kind ?? 'text'), a, timeout) };
+            case 'query_all': {
+                const loc = this.locator(this.page(cmd), cmd);
+                const n = Math.min(await loc.count(), Number(a.limit ?? 500));
+                const out = [];
+                for (let i = 0; i < n; i++)
+                    out.push(await this.query(loc.nth(i), String(a.what ?? a.kind ?? 'text'), a, timeout));
+                return { kind: 'query', value: out };
+            }
+            case 'screenshot': return this.screenshot(cmd);
+            case 'content': return { kind: 'content', value: await this.page(cmd).content() };
+            case 'set_content':
+                await this.page(cmd).setContent(String(a.html ?? ''), { timeout });
+                return act;
+            case 'add_init_script':
+                await this.context.addInitScript(String(a.script ?? ''));
+                return act;
+            case 'title': return { kind: 'query', value: await this.page(cmd).title() };
+            case 'url': return { kind: 'query', value: this.page(cmd).url() };
+            case 'set_viewport':
+                await this.page(cmd).setViewportSize({ width: Number(a.w ?? a.width ?? 1280), height: Number(a.h ?? a.height ?? 800) });
+                return act;
+            case 'new_page': {
+                const pg = await this.context.newPage();
+                if (a.url) {
+                    let h;
+                    try {
+                        h = new URL(String(a.url)).hostname;
+                    }
+                    catch {
+                        throw new OpError('invalid_args', `Invalid URL: ${a.url}`);
+                    }
+                    if (!hostAllowed(h, this.opts.allowedDomains) && !isLoopbackHost(h)) {
+                        await pg.close();
+                        throw new OpError('domain_blocked', `${h} is not in this session's allowlist.`);
+                    }
+                    await pg.goto(String(a.url), { waitUntil: 'domcontentloaded', timeout });
+                }
+                const id = this.ids.get(pg) ?? this.register(pg);
+                return { kind: 'action', value: { page_id: id } };
+            }
+            case 'list_pages': return { kind: 'query', value: [...this.pages.entries()].map(([id, p]) => ({ page_id: id, url: p.url(), current: id === this.currentId })) };
+            case 'switch_page': {
+                const id = String(a.page_id ?? cmd.target?.page_id ?? '');
+                if (!this.pages.has(id))
+                    throw new OpError('invalid_args', `No page ${id}.`);
+                this.currentId = id;
+                await this.pages.get(id).bringToFront().catch(() => { });
+                return act;
+            }
+            case 'close_page':
+                await this.page(cmd).close();
+                return act;
+            default: throw new OpError('unsupported_op', `Unsupported op: ${cmd.op}`);
+        }
+    }
+    async query(loc, kind, a, timeout) {
+        switch (kind) {
+            case 'count': return loc.count();
+            case 'text': return loc.innerText({ timeout });
+            case 'html': return loc.innerHTML({ timeout });
+            case 'attr': return loc.getAttribute(String(a.name ?? ''), { timeout });
+            case 'value': {
+                const type = (await loc.getAttribute('type', { timeout }).catch(() => null))?.toLowerCase();
+                return type === 'password' ? '' : loc.inputValue({ timeout });
+            }
+            case 'visible': return loc.isVisible();
+            case 'enabled': return loc.isEnabled({ timeout });
+            case 'checked': return loc.isChecked({ timeout });
+            case 'box': return loc.boundingBox({ timeout });
+            default: throw new OpError('invalid_args', `Unknown query kind: ${kind}`);
+        }
+    }
+    async screenshot(cmd) {
+        const a = cmd.args ?? {};
+        const pg = this.page(cmd);
+        const shotType = a.type === 'jpeg' || cmd.upload_content_type === 'image/jpeg' ? 'jpeg' : 'png';
+        const quality = Number(a.quality ?? 70);
+        const buf = cmd.target?.selector
+            ? await this.locator(pg, cmd).first().screenshot({ type: shotType, ...(shotType === 'jpeg' ? { quality } : {}), timeout: this.to(cmd) })
+            : await pg.screenshot({ type: shotType, ...(shotType === 'jpeg' ? { quality } : {}), fullPage: !!a.full_page, timeout: this.to(cmd) });
+        const dir = path.join(debuggHome(), 'captures');
+        ensurePrivateDir(dir);
+        const file = path.join(dir, `shot-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.${shotType === 'jpeg' ? 'jpg' : 'png'}`);
+        fs.writeFileSync(file, buf, { mode: 0o600 });
+        if (this.opts.screenshots === 'local_only') {
+            return { kind: 'screenshot', value: { base64: PX, local_path: file, redacted: true }, screenshot_ref: null };
+        }
+        if (cmd.upload_url) {
+            const ct = cmd.upload_content_type ?? (shotType === 'jpeg' ? 'image/jpeg' : 'image/png');
+            let ref;
+            if (this.uploader) {
+                try {
+                    ref = await this.uploader(cmd.upload_url, ct, new Uint8Array(buf));
+                }
+                catch (e) {
+                    throw new OpError('internal', `Screenshot upload failed: ${e instanceof Error ? e.message : String(e)}`, true);
+                }
+            }
+            else {
+                const res = await fetch(cmd.upload_url, { method: 'PUT', headers: { 'content-type': ct }, body: new Uint8Array(buf) });
+                if (!res.ok)
+                    throw new OpError('internal', `Screenshot upload failed: HTTP ${res.status}`, true);
+                ref = cmd.upload_url.split('?')[0];
+            }
+            return { kind: 'screenshot', value: { local_path: file }, screenshot_ref: ref };
+        }
+        if (buf.length > (this.opts.maxInlineBytes ?? 1_000_000)) {
+            throw new OpError('invalid_args', `Screenshot is ${buf.length} bytes, over max_inline_bytes, and no upload_url was given.`);
+        }
+        return { kind: 'screenshot', value: { base64: buf.toString('base64'), local_path: file }, screenshot_ref: null };
+    }
+    async toError(err, cmd) {
+        if (err instanceof OpError)
+            return { code: err.code, message: err.message, retryable: err.retryable };
+        const msg = err instanceof Error ? err.message.split('\n')[0] : String(err);
+        if (this.blocked.length > 0)
+            return { code: 'domain_blocked', message: `Navigation to ${[...new Set(this.blocked)].join(', ')} was blocked by the allowlist.`, retryable: false };
+        if (/Target (page, context or browser )?has been closed|browser has been closed|Page crashed/i.test(msg))
+            return { code: 'browser_crashed', message: msg, retryable: false };
+        if (/net::ERR|NS_ERROR|Navigation failed|ERR_/i.test(msg))
+            return { code: 'navigation_failed', message: msg, retryable: true };
+        if (/not visible|not attached|hidden|not stable|intercepts pointer/i.test(msg))
+            return { code: 'not_visible', message: msg, retryable: true };
+        if (/strict mode violation|waiting for locator|No node found/i.test(msg) || err instanceof Error && err.name === 'TimeoutError') {
+            if (cmd.target?.selector) {
+                try {
+                    const n = await this.locator(this.page(cmd), cmd).count();
+                    if (n === 0)
+                        return { code: 'target_not_found', message: msg, retryable: true };
+                }
+                catch { /* fall through */ }
+            }
+            return { code: 'timeout', message: msg, retryable: true };
+        }
+        return { code: 'internal', message: msg, retryable: false };
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.closeBrowser().catch(() => { });
+    }
+}
+function stripQuery(u) {
+    try {
+        const x = new URL(u);
+        return x.origin + x.pathname;
+    }
+    catch {
+        return u.slice(0, 200);
+    }
+}

package/dist/services/localExecutor/ops.js

@@ -0,0 +1,12 @@
+/**
+ * Wire types for the Browser Executor API v1 (sentinal docs/local-executor-api-design.md).
+ * The cloud brain's page calls arrive as Commands; this side answers with Results.
+ */
+export const API_VERSION = 1;
+export const OPS = [
+    'goto', 'back', 'forward', 'reload', 'evaluate',
+    'click', 'dblclick', 'fill', 'type', 'press', 'hover', 'select_option', 'check', 'uncheck', 'focus', 'scroll',
+    'wait_for_selector', 'wait_for_load_state', 'wait_for_function',
+    'query', 'query_all', 'screenshot', 'content', 'set_content', 'add_init_script', 'title', 'url', 'set_viewport',
+    'new_page', 'list_pages', 'switch_page', 'close_page',
+];

package/dist/services/localExecutor/session.js

@@ -0,0 +1,125 @@
+import { logger } from '../../utils/logger.js';
+export async function runExecutorSession(o) {
+    const { transport, runner, limits } = o;
+    const stop = new AbortController();
+    let ended = null;
+    const finish = (why) => { if (!ended) {
+        ended = why;
+        stop.abort();
+    } };
+    o.signal?.addEventListener('abort', () => finish('aborted'), { once: true });
+    if (o.signal?.aborted)
+        finish('aborted');
+    await transport.attach(o.attach);
+    let lastContact = Date.now();
+    const retryDelay = o.retryDelayMs ?? 1000;
+    const hb = setInterval(() => {
+        transport.heartbeat().then((r) => {
+            lastContact = Date.now();
+            if (r.cancel)
+                finish('cancelled');
+            else if (r.drain)
+                finish('drained');
+        }).catch(() => { if (Date.now() - lastContact > limits.lease_s * 1000)
+            finish('lease_lost'); });
+    }, Math.max(limits.heartbeat_s * 1000, 50));
+    const done = new Map(); // idempotent replays
+    const inflight = new Set(); // the cloud re-delivers unfinished commands; never run one twice
+    let commandsRun = 0;
+    try {
+        while (!ended) {
+            let cmds;
+            try {
+                const polled = await transport.poll(o.pollWaitS ?? 25, stop.signal);
+                lastContact = Date.now();
+                if (Array.isArray(polled))
+                    cmds = polled;
+                else {
+                    cmds = polled.commands ?? [];
+                    if (polled.cancel) {
+                        finish('cancelled');
+                        break;
+                    }
+                    if (polled.drain && cmds.length === 0) {
+                        finish('drained');
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                if (ended)
+                    break;
+                if (Date.now() - lastContact > limits.lease_s * 1000) {
+                    finish('lease_lost');
+                    break;
+                }
+                await sleep(retryDelay, stop.signal);
+                continue;
+            }
+            const conc = Math.max(1, limits.max_inflight ?? cmds.length);
+            let next = 0;
+            const worker = async () => {
+                while (next < cmds.length && !ended) {
+                    const cmd = cmds[next++];
+                    const key = cmd.idempotency_key ?? cmd.id;
+                    if (inflight.has(key))
+                        continue;
+                    inflight.add(key);
+                    const cached = done.get(key);
+                    let result;
+                    try {
+                        result = cached ? { ...cached, command_id: cmd.id } : await runner.execute(cmd);
+                    }
+                    finally {
+                        inflight.delete(key);
+                    }
+                    logger.debug('executor command', { op: cmd.op, ok: result.ok, ms: result.duration_ms, err: result.error?.code, msg: result.error?.message, obs: result.observation ? Object.keys(result.observation) : undefined, args: JSON.stringify(cmd.args ?? {}).slice(0, 160), sel: cmd.target?.selector, val: op_preview(result) });
+                    if (!cached) {
+                        done.set(key, result);
+                        commandsRun++;
+                        if (done.size > 200)
+                            done.delete(done.keys().next().value);
+                    }
+                    // Results are idempotent by command_id on the cloud side, so retrying a post is safe.
+                    for (let attempt = 0;; attempt++) {
+                        try {
+                            await transport.postResults([result]);
+                            lastContact = Date.now();
+                            break;
+                        }
+                        catch {
+                            if (ended || Date.now() - lastContact > limits.lease_s * 1000) {
+                                finish('lease_lost');
+                                break;
+                            }
+                            await sleep(retryDelay * Math.min(attempt + 1, 5), stop.signal);
+                        }
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(conc, cmds.length) }, worker));
+        }
+    }
+    finally {
+        clearInterval(hb);
+        await runner.close();
+    }
+    return { ended: ended ?? 'closed_by_cloud', commandsRun };
+}
+function sleep(ms, signal) {
+    return new Promise((r) => {
+        const t = setTimeout(r, ms);
+        signal.addEventListener('abort', () => { clearTimeout(t); r(); }, { once: true });
+    });
+}
+function op_preview(r) {
+    const v = r.observation && 'value' in r.observation ? r.observation.value : undefined;
+    if (v === undefined || r.observation.kind === 'screenshot')
+        return undefined;
+    try {
+        return JSON.stringify(v).slice(0, 200);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -43,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;

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

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.6",
+  "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",