@wingman-ai/gateway 0.3.0 → 0.3.2

package/dist/agent/tools/browser_control.js

@@ -0,0 +1,1242 @@
+import { spawn, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tool } from "langchain";
+import { array, boolean as external_zod_boolean, discriminatedUnion, enum as external_zod_enum, literal, number, object, string } from "zod";
+import { createLogger } from "../../logger.js";
+const logger = createLogger();
+const DEVTOOLS_ENDPOINT_REGEX = /DevTools listening on (ws:\/\/\S+)/i;
+const DEFAULT_ACTION_TIMEOUT_MS = 30000;
+const MAX_ACTION_TIMEOUT_MS = 300000;
+const DEFAULT_LAUNCH_TIMEOUT_MS = 15000;
+const DEFAULT_RELAY_CONNECT_TIMEOUT_MS = 5000;
+const DEFAULT_RELAY_HOST = "127.0.0.1";
+const DEFAULT_RELAY_PORT = 18792;
+const DEFAULT_MAX_EXTRACT_CHARS = 5000;
+const MAX_EXTRACT_CHARS = 1000000;
+const MAX_ACTIONS = 25;
+const DEFAULT_PROFILES_ROOT = ".wingman/browser-profiles";
+const DEFAULT_EXTENSIONS_ROOT = ".wingman/browser-extensions";
+const DEFAULT_BUNDLED_EXTENSION_ID = "wingman";
+const BUNDLED_EXTENSION_RELATIVE_PATH = "../../../extensions/wingman-browser-extension";
+const PERSISTENT_PROFILE_IGNORE_DEFAULT_ARGS = [
+    "--password-store=basic",
+    "--use-mock-keychain"
+];
+const PROFILE_LOCK_FILENAME = ".wingman-browser.lock";
+const PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const CHROME_COMMON_ARGS = [
+    "--disable-extensions",
+    "--disable-background-networking",
+    "--disable-default-apps",
+    "--no-default-browser-check",
+    "--no-first-run",
+    "--disable-sync",
+    "--disable-component-update",
+    "--mute-audio",
+    "--hide-scrollbars"
+];
+const NavigateActionSchema = object({
+    type: literal("navigate"),
+    url: string().url().describe("Destination URL")
+});
+const NavigateAliasActionSchema = object({
+    type: literal("url"),
+    url: string().url().describe("Destination URL")
+});
+const NavigateOpenAliasActionSchema = object({
+    type: literal("open"),
+    url: string().url().describe("Destination URL")
+});
+const NavigateGotoAliasActionSchema = object({
+    type: literal("goto"),
+    url: string().url().describe("Destination URL")
+});
+const ClickActionSchema = object({
+    type: literal("click"),
+    selector: string().min(1).describe("CSS selector to click")
+});
+const TypeActionSchema = object({
+    type: literal("type"),
+    selector: string().min(1).describe("CSS selector to target"),
+    text: string().describe("Text value to enter"),
+    submit: external_zod_boolean().optional().default(false).describe("Press Enter after typing")
+});
+const PressActionSchema = object({
+    type: literal("press"),
+    key: string().min(1).describe("Keyboard key (for example Enter, Tab, ArrowDown)")
+});
+const WaitActionSchema = object({
+    type: literal("wait"),
+    ms: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).optional().describe("How long to wait in milliseconds"),
+    selector: string().min(1).optional().describe("Wait for this selector to become visible"),
+    url: string().min(1).optional().describe("Wait for this URL/glob pattern"),
+    load: external_zod_enum([
+        "load",
+        "domcontentloaded",
+        "networkidle"
+    ]).optional().describe("Wait for this load state"),
+    fn: string().min(1).optional().describe("Wait for this JavaScript predicate to become truthy"),
+    timeoutMs: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).optional().describe("Optional timeout override in milliseconds")
+}).refine((action)=>Boolean(action.ms || action.selector || action.url || action.load || action.fn), {
+    message: "wait requires ms or one of selector/url/load/fn"
+});
+const WaitAliasActionSchema = object({
+    type: literal("ms"),
+    ms: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).describe("How long to wait in milliseconds")
+});
+const WaitSleepAliasActionSchema = object({
+    type: literal("sleep"),
+    ms: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).describe("How long to wait in milliseconds")
+});
+const WaitPauseAliasActionSchema = object({
+    type: literal("pause"),
+    ms: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).describe("How long to wait in milliseconds")
+});
+const WaitForActionBaseSchema = object({
+    selector: string().min(1).optional().describe("Wait for this selector to become visible"),
+    url: string().min(1).optional().describe("Wait for this URL/glob pattern"),
+    load: external_zod_enum([
+        "load",
+        "domcontentloaded",
+        "networkidle"
+    ]).optional().describe("Wait for this load state"),
+    fn: string().min(1).optional().describe("Wait for this JavaScript predicate to become truthy"),
+    timeoutMs: number().int().min(1).max(MAX_ACTION_TIMEOUT_MS).optional().describe("Optional timeout override in milliseconds")
+});
+const WaitForActionSchema = WaitForActionBaseSchema.extend({
+    type: literal("wait_for")
+}).refine((action)=>Boolean(action.selector || action.url || action.load || action.fn), {
+    message: "wait_for requires at least one of selector/url/load/fn"
+});
+const WaitUntilAliasActionSchema = WaitForActionBaseSchema.extend({
+    type: literal("wait_until")
+}).refine((action)=>Boolean(action.selector || action.url || action.load || action.fn), {
+    message: "wait_until requires at least one of selector/url/load/fn"
+});
+const ExtractTextActionSchema = object({
+    type: literal("extract_text"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const ExtractTextAliasActionSchema = object({
+    type: literal("selector"),
+    selector: string().min(1).describe("CSS selector"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const ExtractAliasActionSchema = object({
+    type: literal("extract"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const GetContentAliasActionSchema = object({
+    type: literal("getContent"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const GetContentSnakeAliasActionSchema = object({
+    type: literal("get_content"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const QuerySelectorAliasActionSchema = object({
+    type: literal("querySelector"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const QuerySelectorSnakeAliasActionSchema = object({
+    type: literal("query_selector"),
+    selector: string().min(1).optional().describe("Optional CSS selector; defaults to body"),
+    maxChars: number().int().min(1).max(MAX_EXTRACT_CHARS).optional().default(DEFAULT_MAX_EXTRACT_CHARS).describe("Maximum returned characters")
+});
+const ScreenshotActionSchema = object({
+    type: literal("screenshot"),
+    path: string().min(1).optional().describe("Relative output path within workspace"),
+    fullPage: external_zod_boolean().optional().default(true).describe("Capture the full page")
+});
+const ScreenshotAliasActionSchema = object({
+    type: literal("path"),
+    path: string().min(1).describe("Relative output path within workspace"),
+    fullPage: external_zod_boolean().optional().default(true).describe("Capture the full page")
+});
+const SnapshotAliasActionSchema = object({
+    type: literal("snapshot"),
+    path: string().min(1).describe("Relative output path within workspace"),
+    fullPage: external_zod_boolean().optional().default(true).describe("Capture the full page")
+});
+const CaptureAliasActionSchema = object({
+    type: literal("capture"),
+    path: string().min(1).describe("Relative output path within workspace"),
+    fullPage: external_zod_boolean().optional().default(true).describe("Capture the full page")
+});
+const EvaluateActionSchema = object({
+    type: literal("evaluate"),
+    expression: string().min(1).describe("JavaScript expression to evaluate in page context")
+});
+const EvaluateAliasActionSchema = object({
+    type: literal("expression"),
+    expression: string().min(1).describe("JavaScript expression to evaluate in page context")
+});
+const EvaluateJsAliasActionSchema = object({
+    type: literal("js"),
+    expression: string().min(1).describe("JavaScript expression to evaluate in page context")
+});
+const EvaluateScriptAliasActionSchema = object({
+    type: literal("script"),
+    expression: string().min(1).describe("JavaScript expression to evaluate in page context")
+});
+const BrowserActionSchema = discriminatedUnion("type", [
+    NavigateActionSchema,
+    NavigateAliasActionSchema,
+    NavigateOpenAliasActionSchema,
+    NavigateGotoAliasActionSchema,
+    ClickActionSchema,
+    TypeActionSchema,
+    PressActionSchema,
+    WaitActionSchema,
+    WaitAliasActionSchema,
+    WaitSleepAliasActionSchema,
+    WaitPauseAliasActionSchema,
+    WaitForActionSchema,
+    WaitUntilAliasActionSchema,
+    ExtractTextActionSchema,
+    ExtractTextAliasActionSchema,
+    ExtractAliasActionSchema,
+    GetContentAliasActionSchema,
+    GetContentSnakeAliasActionSchema,
+    QuerySelectorAliasActionSchema,
+    QuerySelectorSnakeAliasActionSchema,
+    ScreenshotActionSchema,
+    ScreenshotAliasActionSchema,
+    SnapshotAliasActionSchema,
+    CaptureAliasActionSchema,
+    EvaluateActionSchema,
+    EvaluateAliasActionSchema,
+    EvaluateJsAliasActionSchema,
+    EvaluateScriptAliasActionSchema
+]);
+const BrowserControlInputSchema = object({
+    url: string().url().optional().describe("Optional initial URL to open"),
+    actions: array(BrowserActionSchema).max(MAX_ACTIONS).optional().default([]).describe("Ordered browser actions to execute"),
+    headless: external_zod_boolean().optional().describe("Launch browser in headless mode. Non-persistent runs default to headless; persistent browser profiles default to headed unless headless is explicitly requested."),
+    timeoutMs: number().int().min(1000).max(MAX_ACTION_TIMEOUT_MS).optional().default(DEFAULT_ACTION_TIMEOUT_MS).describe("Per-action timeout in milliseconds"),
+    executablePath: string().min(1).optional().describe("Optional path to Chrome/Chromium binary. Falls back to WINGMAN_CHROME_EXECUTABLE or common install paths.")
+});
+const DEFAULT_BROWSER_CONTROL_DEPENDENCIES = {
+    importPlaywright: async ()=>await import("playwright-core"),
+    startChrome: startChromeWithDevtools,
+    resolveRelayWsEndpoint: resolveRelayWsEndpoint,
+    mkTempDir: ()=>mkdtempSync(join(tmpdir(), "wingman-browser-")),
+    removeDir: (target)=>rmSync(target, {
+            recursive: true,
+            force: true
+        }),
+    now: ()=>Date.now()
+};
+function getChromeCandidates() {
+    const candidates = [
+        process.env.WINGMAN_CHROME_EXECUTABLE,
+        "google-chrome",
+        "chromium-browser",
+        "chromium"
+    ].filter((candidate)=>Boolean(candidate?.trim()));
+    if ("darwin" === process.platform) candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium");
+    if ("linux" === process.platform) candidates.push("/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium-browser", "/usr/bin/chromium");
+    if ("win32" === process.platform) candidates.push("C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe", "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe");
+    return candidates;
+}
+function resolveBinaryFromPath(binaryName) {
+    const locator = "win32" === process.platform ? "where" : "which";
+    const result = spawnSync(locator, [
+        binaryName
+    ], {
+        encoding: "utf-8"
+    });
+    if (0 !== result.status || !result.stdout) return null;
+    const firstLine = result.stdout.split(/\r?\n/).map((line)=>line.trim()).find(Boolean);
+    return firstLine || null;
+}
+function resolveChromeExecutablePath(explicitPath) {
+    const candidatePool = explicitPath?.trim() ? [
+        explicitPath.trim()
+    ] : getChromeCandidates();
+    for (const candidate of candidatePool)if (candidate) {
+        if (isAbsolute(candidate) && existsSync(candidate)) return candidate;
+        if (!isAbsolute(candidate)) {
+            const fromPath = resolveBinaryFromPath(candidate);
+            if (fromPath) return fromPath;
+        }
+    }
+    if (explicitPath?.trim()) throw new Error(`Chrome executable not found at "${explicitPath}". Provide a valid executable path.`);
+    throw new Error("No Chrome/Chromium executable found. Install Chrome/Chromium or set WINGMAN_CHROME_EXECUTABLE.");
+}
+function waitForDevtoolsEndpoint(chromeProcess, launchTimeoutMs, userDataDir) {
+    return new Promise((resolveEndpoint, rejectEndpoint)=>{
+        let settled = false;
+        let logs = "";
+        const intervalHandle = setInterval(()=>{
+            const endpointFromFile = readDevtoolsEndpointFromFile(userDataDir);
+            if (!endpointFromFile) return;
+            finish(()=>resolveEndpoint(endpointFromFile));
+        }, 100);
+        const finish = (callback)=>{
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            clearInterval(intervalHandle);
+            chromeProcess.stdout.removeListener("data", onData);
+            chromeProcess.stderr.removeListener("data", onData);
+            chromeProcess.removeListener("error", onError);
+            chromeProcess.removeListener("exit", onExit);
+            callback();
+        };
+        const onData = (chunk)=>{
+            const text = chunk.toString();
+            logs += text;
+            const match = text.match(DEVTOOLS_ENDPOINT_REGEX);
+            if (!match?.[1]) return;
+            finish(()=>resolveEndpoint(match[1]));
+        };
+        const onError = (error)=>{
+            finish(()=>rejectEndpoint(new Error(`Failed to launch Chrome for CDP connection: ${error.message}`)));
+        };
+        const onExit = (code)=>{
+            finish(()=>rejectEndpoint(new Error(`Chrome exited before exposing DevTools endpoint (code: ${code ?? "unknown"}). Output: ${logs.trim() || "none"}`)));
+        };
+        const timeoutHandle = setTimeout(()=>{
+            finish(()=>rejectEndpoint(new Error(`Timed out waiting for DevTools endpoint after ${launchTimeoutMs}ms.`)));
+        }, launchTimeoutMs);
+        chromeProcess.stdout.on("data", onData);
+        chromeProcess.stderr.on("data", onData);
+        chromeProcess.on("error", onError);
+        chromeProcess.on("exit", onExit);
+    });
+}
+function readDevtoolsEndpointFromFile(userDataDir) {
+    const activePortPath = join(userDataDir, "DevToolsActivePort");
+    if (!existsSync(activePortPath)) return null;
+    try {
+        const raw = readFileSync(activePortPath, "utf-8").trim();
+        if (!raw) return null;
+        const [portLine, browserPathLine] = raw.split(/\r?\n/);
+        const port = Number.parseInt(portLine?.trim() || "", 10);
+        if (!Number.isFinite(port) || port <= 0) return null;
+        const rawPath = browserPathLine?.trim();
+        if (!rawPath) return null;
+        const browserPath = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+        return `ws://127.0.0.1:${port}${browserPath}`;
+    } catch  {
+        return null;
+    }
+}
+async function closeChromeProcess(chromeProcess) {
+    if (null !== chromeProcess.exitCode || chromeProcess.killed) return;
+    await new Promise((resolveClose)=>{
+        let resolved = false;
+        const finish = ()=>{
+            if (resolved) return;
+            resolved = true;
+            resolveClose();
+        };
+        const forceKillTimeout = setTimeout(()=>{
+            if (null === chromeProcess.exitCode && !chromeProcess.killed) chromeProcess.kill("SIGKILL");
+        }, 2000);
+        chromeProcess.once("exit", ()=>{
+            clearTimeout(forceKillTimeout);
+            finish();
+        });
+        try {
+            chromeProcess.kill("SIGTERM");
+        } catch  {
+            clearTimeout(forceKillTimeout);
+            finish();
+        }
+    });
+}
+function clearStaleDevtoolsArtifacts(userDataDir) {
+    const activePortPath = join(userDataDir, "DevToolsActivePort");
+    try {
+        unlinkSync(activePortPath);
+    } catch  {}
+}
+async function startChromeWithDevtools(input) {
+    const executablePath = resolveChromeExecutablePath(input.executablePath);
+    clearStaleDevtoolsArtifacts(input.userDataDir);
+    const args = [
+        "--remote-debugging-port=0",
+        `--user-data-dir=${input.userDataDir}`,
+        ...input.chromeArgs || CHROME_COMMON_ARGS
+    ];
+    if (input.headless) args.push("--headless=new");
+    args.push("about:blank");
+    const chromeProcess = spawn(executablePath, args, {
+        stdio: [
+            "ignore",
+            "pipe",
+            "pipe"
+        ]
+    });
+    let wsEndpoint = "";
+    try {
+        wsEndpoint = await waitForDevtoolsEndpoint(chromeProcess, input.launchTimeoutMs, input.userDataDir);
+    } catch (error) {
+        await closeChromeProcess(chromeProcess);
+        throw error;
+    }
+    return {
+        wsEndpoint,
+        close: async ()=>{
+            await closeChromeProcess(chromeProcess);
+        }
+    };
+}
+function resolveBrowserTransportPreference(value) {
+    if ("playwright" === value || "relay" === value) return value;
+    return "auto";
+}
+function resolveRelayConfig(options) {
+    if (!options.relayConfig?.enabled) return null;
+    const host = (options.relayConfig.host || DEFAULT_RELAY_HOST).trim();
+    const port = Number.isInteger(options.relayConfig.port) ? Number(options.relayConfig.port) : DEFAULT_RELAY_PORT;
+    const requireAuth = false !== options.relayConfig.requireAuth;
+    const authToken = options.relayConfig.authToken?.trim() || void 0;
+    if (!host) throw new Error("Browser relay host cannot be empty.");
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid browser relay port: ${String(options.relayConfig.port)}`);
+    if (requireAuth && !authToken) throw new Error('Browser relay requires authToken. Run "wingman browser extension pair" and configure the extension token.');
+    return {
+        host,
+        port,
+        requireAuth,
+        authToken
+    };
+}
+async function resolveRelayWsEndpoint(config, timeoutMs) {
+    const relayHttpBase = `http://${config.host}:${config.port}`;
+    const controller = new AbortController();
+    const timer = setTimeout(()=>controller.abort(), timeoutMs);
+    try {
+        const versionResponse = await fetch(`${relayHttpBase}/json/version`, {
+            method: "GET",
+            signal: controller.signal
+        });
+        if (!versionResponse.ok) throw new Error(`Browser relay endpoint returned HTTP ${versionResponse.status}`);
+        const payload = await versionResponse.json();
+        if ("string" == typeof payload?.webSocketDebuggerUrl && payload.webSocketDebuggerUrl.trim()) return payload.webSocketDebuggerUrl.trim();
+    } catch (error) {
+        const suffix = error instanceof Error ? `: ${error.message}` : "";
+        throw new Error(`Failed to resolve browser relay endpoint${suffix}`);
+    } finally{
+        clearTimeout(timer);
+    }
+    const tokenParam = config.requireAuth && config.authToken ? `?token=${encodeURIComponent(config.authToken)}` : "";
+    return `ws://${config.host}:${config.port}/cdp${tokenParam}`;
+}
+function preferPersistentLaunch(options, _isPersistentProfile) {
+    if ("boolean" == typeof options.preferPersistentLaunch) return options.preferPersistentLaunch;
+    return _isPersistentProfile;
+}
+function resolveHeadlessMode(inputHeadless, isPersistentProfile) {
+    if ("boolean" == typeof inputHeadless) return inputHeadless;
+    return !isPersistentProfile;
+}
+function selectContext(contexts) {
+    if (0 === contexts.length) throw new Error("Failed to initialize browser context.");
+    const reversed = [
+        ...contexts
+    ].reverse();
+    return reversed.find((candidate)=>candidate.pages().length > 0) || reversed[0];
+}
+async function launchPersistentContext(playwright, userDataDir, executablePath, headless, startupTimeoutMs, chromeArgs) {
+    if ("function" != typeof playwright.chromium.launchPersistentContext) throw new Error("playwright-core runtime does not support launchPersistentContext.");
+    return playwright.chromium.launchPersistentContext(userDataDir, {
+        executablePath: resolveChromeExecutablePath(executablePath),
+        headless,
+        timeout: startupTimeoutMs,
+        args: chromeArgs,
+        ignoreDefaultArgs: PERSISTENT_PROFILE_IGNORE_DEFAULT_ARGS
+    });
+}
+function validateExtensionId(extensionId) {
+    const normalized = extensionId.trim();
+    if (!normalized) throw new Error("Extension ID cannot be empty.");
+    if (!PROFILE_ID_PATTERN.test(normalized)) throw new Error(`Invalid extension ID "${extensionId}". Use letters, numbers, dot, underscore, or dash.`);
+    return normalized;
+}
+function resolveExtensionPath(workspace, extensionId, options) {
+    const mappedPath = options.extensionPaths?.[extensionId];
+    if (mappedPath?.trim()) {
+        const trimmed = mappedPath.trim();
+        return isAbsolute(trimmed) ? trimmed : resolve(workspace, trimmed);
+    }
+    const rootDir = options.extensionsRootDir?.trim() || DEFAULT_EXTENSIONS_ROOT;
+    const absoluteRoot = isAbsolute(rootDir) ? rootDir : resolve(workspace, rootDir);
+    return join(absoluteRoot, extensionId);
+}
+function resolveBundledExtensionSourcePath() {
+    const bundledPath = resolve(fileURLToPath(new URL(BUNDLED_EXTENSION_RELATIVE_PATH, import.meta.url)));
+    const bundledManifest = join(bundledPath, "manifest.json");
+    return existsSync(bundledManifest) ? bundledPath : null;
+}
+function ensureBundledWingmanExtension(extensionPath) {
+    const bundledSourcePath = resolveBundledExtensionSourcePath();
+    if (!bundledSourcePath) return false;
+    mkdirSync(dirname(extensionPath), {
+        recursive: true
+    });
+    cpSync(bundledSourcePath, extensionPath, {
+        recursive: true,
+        force: true
+    });
+    return true;
+}
+function resolveEnabledExtensions(workspace, options) {
+    const requestedIds = options.browserExtensions?.length ? options.browserExtensions : options.defaultExtensions;
+    if (!requestedIds?.length) return {
+        extensionIds: [],
+        extensionDirs: []
+    };
+    const uniqueIds = Array.from(new Set(requestedIds.map((value)=>validateExtensionId(value))));
+    const extensionDirs = uniqueIds.map((extensionId)=>{
+        const extensionPath = resolveExtensionPath(workspace, extensionId, options);
+        if (!existsSync(extensionPath)) {
+            if (extensionId === DEFAULT_BUNDLED_EXTENSION_ID && ensureBundledWingmanExtension(extensionPath)) logger.info(`browser_control auto-provisioned bundled extension "${extensionId}" at ${extensionPath}`);
+        }
+        if (!existsSync(extensionPath)) throw new Error(`Configured extension path does not exist for "${extensionId}": ${extensionPath}`);
+        const manifestPath = join(extensionPath, "manifest.json");
+        if (!existsSync(manifestPath)) throw new Error(`manifest.json not found for extension "${extensionId}" at ${extensionPath}`);
+        return extensionPath;
+    });
+    return {
+        extensionIds: uniqueIds,
+        extensionDirs
+    };
+}
+function buildChromeArgs(extensionDirs) {
+    if (0 === extensionDirs.length) return CHROME_COMMON_ARGS;
+    const joined = extensionDirs.join(",");
+    return [
+        ...CHROME_COMMON_ARGS.filter((arg)=>"--disable-extensions" !== arg),
+        `--disable-extensions-except=${joined}`,
+        `--load-extension=${joined}`
+    ];
+}
+function validateProfileId(profileId) {
+    const normalized = profileId.trim();
+    if (!normalized) throw new Error("browserProfile cannot be empty.");
+    if (!PROFILE_ID_PATTERN.test(normalized)) throw new Error(`Invalid browserProfile "${profileId}". Use letters, numbers, dot, underscore, or dash.`);
+    return normalized;
+}
+function resolveProfilePath(workspace, profileId, options) {
+    const normalizedProfileId = validateProfileId(profileId);
+    const mappedPath = options.profilePaths?.[normalizedProfileId];
+    if (mappedPath && mappedPath.trim()) {
+        const trimmed = mappedPath.trim();
+        return isAbsolute(trimmed) ? trimmed : resolve(workspace, trimmed);
+    }
+    const rootDir = options.profilesRootDir?.trim() || DEFAULT_PROFILES_ROOT;
+    const absoluteRoot = isAbsolute(rootDir) ? rootDir : resolve(workspace, rootDir);
+    return join(absoluteRoot, normalizedProfileId);
+}
+function readProfileLockMetadata(lockPath) {
+    try {
+        const raw = readFileSync(lockPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || "object" != typeof parsed) return null;
+        return parsed;
+    } catch  {
+        return null;
+    }
+}
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        if (error && "object" == typeof error && "code" in error && "EPERM" === error.code) return true;
+        return false;
+    }
+}
+function acquireProfileLock(profileDir) {
+    const lockPath = join(profileDir, PROFILE_LOCK_FILENAME);
+    const writeLock = ()=>writeFileSync(lockPath, JSON.stringify({
+            pid: process.pid,
+            createdAt: new Date().toISOString()
+        }), {
+            flag: "wx"
+        });
+    try {
+        writeLock();
+    } catch (error) {
+        if (!(error instanceof Error && "code" in error && "EEXIST" === error.code)) throw error;
+        const lockMetadata = readProfileLockMetadata(lockPath);
+        if ("number" == typeof lockMetadata?.pid && lockMetadata.pid === process.pid) return ()=>{};
+        const stalePid = "number" == typeof lockMetadata?.pid && !isPidAlive(lockMetadata.pid);
+        if (!stalePid) throw new Error(`Browser profile is already in use: ${profileDir}. Wait for the other run to finish.`);
+        try {
+            unlinkSync(lockPath);
+        } catch  {
+            throw new Error(`Browser profile is already in use: ${profileDir}. Wait for the other run to finish.`);
+        }
+        try {
+            writeLock();
+        } catch  {
+            throw new Error(`Browser profile is already in use: ${profileDir}. Wait for the other run to finish.`);
+        }
+    }
+    let released = false;
+    return ()=>{
+        if (released) return;
+        released = true;
+        try {
+            unlinkSync(lockPath);
+        } catch  {}
+    };
+}
+function resolveUserDataDir(workspace, options, dependencies) {
+    const configuredProfile = options.browserProfile?.trim();
+    if (!configuredProfile) return {
+        userDataDir: dependencies.mkTempDir(),
+        persistentProfile: false
+    };
+    const profileId = validateProfileId(configuredProfile);
+    const profileDir = resolveProfilePath(workspace, profileId, options);
+    mkdirSync(profileDir, {
+        recursive: true
+    });
+    const releaseLock = acquireProfileLock(profileDir);
+    return {
+        userDataDir: profileDir,
+        persistentProfile: true,
+        profileId,
+        releaseLock
+    };
+}
+function resolveWorkspaceRelativePath(workspace, targetPath) {
+    const absolutePath = resolve(workspace, targetPath);
+    const relativePath = relative(resolve(workspace), absolutePath);
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) throw new Error("Output path must stay inside the workspace.");
+    return absolutePath;
+}
+function resolveScreenshotPath(workspace, requestedPath, now, actionIndex) {
+    if (requestedPath && isAbsolute(requestedPath)) throw new Error("Screenshot path must be relative to the workspace.");
+    const fallback = join(".wingman", "browser", `screenshot-${now()}-${actionIndex + 1}.png`);
+    const relativeOutputPath = requestedPath || fallback;
+    const absoluteOutputPath = resolveWorkspaceRelativePath(workspace, relativeOutputPath);
+    mkdirSync(dirname(absoluteOutputPath), {
+        recursive: true
+    });
+    return {
+        absolute: absoluteOutputPath,
+        relative: relative(workspace, absoluteOutputPath).split("\\").join("/")
+    };
+}
+function serializeEvaluation(value) {
+    if ("string" == typeof value || "number" == typeof value || "boolean" == typeof value || null === value) return value;
+    try {
+        return JSON.parse(JSON.stringify(value));
+    } catch  {
+        return String(value);
+    }
+}
+function globToRegex(globPattern) {
+    let regex = "^";
+    for(let index = 0; index < globPattern.length; index += 1){
+        const current = globPattern[index];
+        const next = globPattern[index + 1];
+        if ("*" === current && "*" === next) {
+            regex += ".*";
+            index += 1;
+            continue;
+        }
+        if ("*" === current) {
+            regex += "[^/]*";
+            continue;
+        }
+        regex += current.replace(/[-/\\^$+?.()|[\]{}]/g, "\\$&");
+    }
+    regex += "$";
+    return new RegExp(regex);
+}
+async function waitForUrlFallback(page, urlPattern, timeoutMs) {
+    const regex = globToRegex(urlPattern);
+    const startedAt = Date.now();
+    while(Date.now() - startedAt < timeoutMs){
+        if (regex.test(page.url())) return;
+        await page.waitForTimeout(100);
+    }
+    throw new Error(`Timed out waiting for URL pattern "${urlPattern}".`);
+}
+async function waitForPredicateFallback(page, expression, timeoutMs) {
+    const startedAt = Date.now();
+    while(Date.now() - startedAt < timeoutMs){
+        const result = await page.evaluate(expression);
+        if (result) return;
+        await page.waitForTimeout(100);
+    }
+    throw new Error("Timed out waiting for JavaScript predicate to become truthy.");
+}
+async function runConditionalWait(page, action, timeoutMs) {
+    const waitTimeoutMs = action.timeoutMs ?? timeoutMs;
+    if (action.selector) if ("function" == typeof page.waitForSelector) await page.waitForSelector(action.selector, {
+        state: "visible",
+        timeout: waitTimeoutMs
+    });
+    else await page.textContent(action.selector, {
+        timeout: waitTimeoutMs
+    });
+    if (action.url) if ("function" == typeof page.waitForURL) await page.waitForURL(globToRegex(action.url), {
+        timeout: waitTimeoutMs
+    });
+    else await waitForUrlFallback(page, action.url, waitTimeoutMs);
+    if (action.load && "function" == typeof page.waitForLoadState) await page.waitForLoadState(action.load, {
+        timeout: waitTimeoutMs
+    });
+    if (action.fn) if ("function" == typeof page.waitForFunction) await page.waitForFunction(action.fn, void 0, {
+        timeout: waitTimeoutMs
+    });
+    else await waitForPredicateFallback(page, action.fn, waitTimeoutMs);
+    return {
+        type: "wait_for",
+        selector: action.selector || null,
+        url: action.url || null,
+        load: action.load || null,
+        fn: action.fn || null,
+        timeoutMs: waitTimeoutMs
+    };
+}
+async function runAction(page, action, timeoutMs, workspace, now, actionIndex) {
+    switch(action.type){
+        case "navigate":
+            await page.goto(action.url, {
+                waitUntil: "domcontentloaded",
+                timeout: timeoutMs
+            });
+            return {
+                type: action.type,
+                url: action.url
+            };
+        case "url":
+            await page.goto(action.url, {
+                waitUntil: "domcontentloaded",
+                timeout: timeoutMs
+            });
+            return {
+                type: "navigate",
+                url: action.url
+            };
+        case "open":
+            await page.goto(action.url, {
+                waitUntil: "domcontentloaded",
+                timeout: timeoutMs
+            });
+            return {
+                type: "navigate",
+                url: action.url
+            };
+        case "goto":
+            await page.goto(action.url, {
+                waitUntil: "domcontentloaded",
+                timeout: timeoutMs
+            });
+            return {
+                type: "navigate",
+                url: action.url
+            };
+        case "click":
+            await page.click(action.selector, {
+                timeout: timeoutMs
+            });
+            return {
+                type: action.type,
+                selector: action.selector
+            };
+        case "type":
+            await page.fill(action.selector, action.text, {
+                timeout: timeoutMs
+            });
+            if (action.submit) await page.keyboard.press("Enter");
+            return {
+                type: action.type,
+                selector: action.selector,
+                textLength: action.text.length,
+                submit: Boolean(action.submit)
+            };
+        case "press":
+            await page.keyboard.press(action.key);
+            return {
+                type: action.type,
+                key: action.key
+            };
+        case "wait":
+            if ("number" == typeof action.ms) {
+                await page.waitForTimeout(action.ms);
+                return {
+                    type: action.type,
+                    ms: action.ms
+                };
+            }
+            return runConditionalWait(page, {
+                type: "wait_for",
+                selector: action.selector,
+                url: action.url,
+                load: action.load,
+                fn: action.fn,
+                timeoutMs: action.timeoutMs
+            }, timeoutMs);
+        case "ms":
+            await page.waitForTimeout(action.ms);
+            return {
+                type: "wait",
+                ms: action.ms
+            };
+        case "sleep":
+            await page.waitForTimeout(action.ms);
+            return {
+                type: "wait",
+                ms: action.ms
+            };
+        case "pause":
+            await page.waitForTimeout(action.ms);
+            return {
+                type: "wait",
+                ms: action.ms
+            };
+        case "wait_for":
+            return runConditionalWait(page, action, timeoutMs);
+        case "wait_until":
+            return runConditionalWait(page, action, timeoutMs);
+        case "extract_text":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: action.type,
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "selector":
+            {
+                const content = await page.textContent(action.selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector: action.selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "extract":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "getContent":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "get_content":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "querySelector":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "query_selector":
+            {
+                const selector = action.selector || "body";
+                const content = await page.textContent(selector, {
+                    timeout: timeoutMs
+                });
+                const text = content || "";
+                const maxChars = action.maxChars ?? DEFAULT_MAX_EXTRACT_CHARS;
+                return {
+                    type: "extract_text",
+                    selector,
+                    text: text.slice(0, maxChars),
+                    truncated: text.length > maxChars
+                };
+            }
+        case "screenshot":
+            {
+                const screenshotPath = resolveScreenshotPath(workspace, action.path, now, actionIndex);
+                await page.screenshot({
+                    path: screenshotPath.absolute,
+                    fullPage: action.fullPage
+                });
+                return {
+                    type: action.type,
+                    path: screenshotPath.relative,
+                    fullPage: Boolean(action.fullPage)
+                };
+            }
+        case "path":
+            {
+                const screenshotPath = resolveScreenshotPath(workspace, action.path, now, actionIndex);
+                await page.screenshot({
+                    path: screenshotPath.absolute,
+                    fullPage: action.fullPage
+                });
+                return {
+                    type: "screenshot",
+                    path: screenshotPath.relative,
+                    fullPage: Boolean(action.fullPage)
+                };
+            }
+        case "snapshot":
+            {
+                const screenshotPath = resolveScreenshotPath(workspace, action.path, now, actionIndex);
+                await page.screenshot({
+                    path: screenshotPath.absolute,
+                    fullPage: action.fullPage
+                });
+                return {
+                    type: "screenshot",
+                    path: screenshotPath.relative,
+                    fullPage: Boolean(action.fullPage)
+                };
+            }
+        case "capture":
+            {
+                const screenshotPath = resolveScreenshotPath(workspace, action.path, now, actionIndex);
+                await page.screenshot({
+                    path: screenshotPath.absolute,
+                    fullPage: action.fullPage
+                });
+                return {
+                    type: "screenshot",
+                    path: screenshotPath.relative,
+                    fullPage: Boolean(action.fullPage)
+                };
+            }
+        case "evaluate":
+            {
+                const result = await page.evaluate(action.expression);
+                return {
+                    type: action.type,
+                    expression: action.expression,
+                    result: serializeEvaluation(result)
+                };
+            }
+        case "expression":
+            {
+                const result = await page.evaluate(action.expression);
+                return {
+                    type: "evaluate",
+                    expression: action.expression,
+                    result: serializeEvaluation(result)
+                };
+            }
+        case "js":
+            {
+                const result = await page.evaluate(action.expression);
+                return {
+                    type: "evaluate",
+                    expression: action.expression,
+                    result: serializeEvaluation(result)
+                };
+            }
+        case "script":
+            {
+                const result = await page.evaluate(action.expression);
+                return {
+                    type: "evaluate",
+                    expression: action.expression,
+                    result: serializeEvaluation(result)
+                };
+            }
+        default:
+            throw new Error(`Unsupported browser action type: ${action.type}`);
+    }
+}
+const createBrowserControlTool = (options = {}, dependencies = {})=>{
+    const workspace = options.workspace || process.cwd();
+    const configWorkspace = options.configWorkspace || workspace;
+    const launchTimeoutMs = options.launchTimeoutMs || DEFAULT_LAUNCH_TIMEOUT_MS;
+    const deps = {
+        ...DEFAULT_BROWSER_CONTROL_DEPENDENCIES,
+        ...dependencies
+    };
+    return tool(async (input)=>{
+        let userDataDirSelection = null;
+        let chromeSession = null;
+        let browser = null;
+        let launchedContext = null;
+        let browserTransport = "cdp";
+        let transportFallbackReason = null;
+        const transportRequested = resolveBrowserTransportPreference(options.browserTransport);
+        let reusedExistingCdpSession = false;
+        let context = null;
+        try {
+            userDataDirSelection = resolveUserDataDir(configWorkspace, options, deps);
+            const selectedUserDataDir = userDataDirSelection;
+            if (!selectedUserDataDir) throw new Error("Failed to resolve browser user data directory.");
+            const headless = resolveHeadlessMode(input.headless, selectedUserDataDir.persistentProfile);
+            const timeoutMs = input.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
+            const startupTimeoutMs = Math.max(launchTimeoutMs, timeoutMs);
+            const playwright = await deps.importPlaywright();
+            const relayConfig = resolveRelayConfig(options);
+            const executablePath = input.executablePath || options.defaultExecutablePath;
+            const { extensionIds, extensionDirs } = resolveEnabledExtensions(configWorkspace, options);
+            const chromeArgs = buildChromeArgs(extensionDirs);
+            const usePersistentLaunch = preferPersistentLaunch(options, selectedUserDataDir.persistentProfile);
+            const closeTransientSessions = async ()=>{
+                if (launchedContext?.close) {
+                    try {
+                        await launchedContext.close();
+                    } catch  {}
+                    launchedContext = null;
+                }
+                if (browser) {
+                    if (!reusedExistingCdpSession) try {
+                        await browser.close();
+                    } catch  {}
+                    browser = null;
+                }
+                if (chromeSession) {
+                    try {
+                        await chromeSession.close();
+                    } catch  {}
+                    chromeSession = null;
+                }
+                context = null;
+                reusedExistingCdpSession = false;
+            };
+            const initializeViaRelay = async (connectTimeoutMs)=>{
+                if (!relayConfig) throw new Error("Browser relay transport requested but browser.relay.enabled is false.");
+                const relayWsEndpoint = await deps.resolveRelayWsEndpoint(relayConfig, connectTimeoutMs);
+                browser = await playwright.chromium.connectOverCDP(relayWsEndpoint, {
+                    timeout: connectTimeoutMs
+                });
+                context = selectContext(browser.contexts());
+                browserTransport = "relay-cdp";
+                reusedExistingCdpSession = false;
+            };
+            const initializeViaPlaywright = async ()=>{
+                if (usePersistentLaunch) {
+                    launchedContext = await launchPersistentContext(playwright, selectedUserDataDir.userDataDir, executablePath, headless, startupTimeoutMs, chromeArgs);
+                    context = launchedContext;
+                    browserTransport = "persistent-context";
+                    return;
+                }
+                if (selectedUserDataDir.persistentProfile) {
+                    const existingWsEndpoint = readDevtoolsEndpointFromFile(selectedUserDataDir.userDataDir);
+                    if (existingWsEndpoint) try {
+                        browser = await playwright.chromium.connectOverCDP(existingWsEndpoint, {
+                            timeout: startupTimeoutMs
+                        });
+                        context = selectContext(browser.contexts());
+                        reusedExistingCdpSession = true;
+                    } catch (reuseError) {
+                        logger.warn(`browser_control failed to attach to existing CDP endpoint, launching a fresh session: ${reuseError instanceof Error ? reuseError.message : String(reuseError)}`);
+                        if (browser) {
+                            try {
+                                await browser.close();
+                            } catch  {}
+                            browser = null;
+                        }
+                    }
+                }
+                if (!context) {
+                    chromeSession = await deps.startChrome({
+                        executablePath,
+                        headless,
+                        launchTimeoutMs: startupTimeoutMs,
+                        userDataDir: selectedUserDataDir.userDataDir,
+                        chromeArgs
+                    });
+                    try {
+                        browser = await playwright.chromium.connectOverCDP(chromeSession.wsEndpoint, {
+                            timeout: startupTimeoutMs
+                        });
+                        context = selectContext(browser.contexts());
+                    } catch (cdpError) {
+                        const cdpMessage = cdpError instanceof Error ? cdpError.message : String(cdpError);
+                        if (browser) {
+                            try {
+                                await browser.close();
+                            } catch  {}
+                            browser = null;
+                        }
+                        if (chromeSession) {
+                            try {
+                                await chromeSession.close();
+                            } catch  {}
+                            chromeSession = null;
+                        }
+                        if (selectedUserDataDir.persistentProfile) {
+                            logger.warn(`browser_control CDP connection failed for persistent profile, retrying CDP once: ${cdpMessage}`);
+                            try {
+                                chromeSession = await deps.startChrome({
+                                    executablePath,
+                                    headless,
+                                    launchTimeoutMs: startupTimeoutMs,
+                                    userDataDir: selectedUserDataDir.userDataDir,
+                                    chromeArgs
+                                });
+                                browser = await playwright.chromium.connectOverCDP(chromeSession.wsEndpoint, {
+                                    timeout: startupTimeoutMs
+                                });
+                                context = selectContext(browser.contexts());
+                            } catch (retryError) {
+                                const retryMessage = retryError instanceof Error ? retryError.message : String(retryError);
+                                if (browser) {
+                                    try {
+                                        await browser.close();
+                                    } catch  {}
+                                    browser = null;
+                                }
+                                if (chromeSession) {
+                                    try {
+                                        await chromeSession.close();
+                                    } catch  {}
+                                    chromeSession = null;
+                                }
+                                const launchPersistent = playwright.chromium.launchPersistentContext;
+                                if ("function" != typeof launchPersistent) throw new Error(`CDP connection failed for persistent profile after retry. Initial error: ${cdpMessage}. Retry error: ${retryMessage}`);
+                                logger.warn(`browser_control CDP retry failed for persistent profile, falling back to persistent launch: ${retryMessage}`);
+                                launchedContext = await launchPersistentContext(playwright, selectedUserDataDir.userDataDir, executablePath, headless, startupTimeoutMs, chromeArgs);
+                                context = launchedContext;
+                                browserTransport = "persistent-context";
+                            }
+                        } else {
+                            const launchPersistent = playwright.chromium.launchPersistentContext;
+                            if ("function" != typeof launchPersistent) throw cdpError;
+                            logger.warn(`browser_control CDP connection failed, retrying with persistent launch: ${cdpMessage}`);
+                            launchedContext = await launchPersistentContext(playwright, selectedUserDataDir.userDataDir, executablePath, headless, startupTimeoutMs, chromeArgs);
+                            context = launchedContext;
+                            browserTransport = "persistent-context";
+                        }
+                    }
+                }
+            };
+            if ("relay" === transportRequested) await initializeViaRelay(startupTimeoutMs);
+            else try {
+                await initializeViaPlaywright();
+            } catch (playwrightError) {
+                if ("auto" !== transportRequested || !relayConfig) throw playwrightError;
+                await closeTransientSessions();
+                const relayTimeoutMs = Math.min(startupTimeoutMs, DEFAULT_RELAY_CONNECT_TIMEOUT_MS);
+                const playwrightMessage = playwrightError instanceof Error ? playwrightError.message : String(playwrightError);
+                logger.warn(`browser_control playwright initialization failed in auto mode, falling back to relay: ${playwrightMessage}`);
+                await initializeViaRelay(relayTimeoutMs);
+                transportFallbackReason = `playwright initialization failed: ${playwrightMessage}`;
+            }
+            const resolvedContext = context;
+            if (!resolvedContext) throw new Error("Failed to initialize browser context.");
+            const activeContext = resolvedContext;
+            let page = activeContext.pages().at(-1);
+            if (!page) page = await activeContext.newPage();
+            if ("function" == typeof page.bringToFront) await page.bringToFront();
+            if (input.url) await page.goto(input.url, {
+                waitUntil: "domcontentloaded",
+                timeout: timeoutMs
+            });
+            const actionResults = [];
+            for (const [index, action] of (input.actions || []).entries()){
+                const result = await runAction(page, action, timeoutMs, workspace, deps.now, index);
+                actionResults.push(result);
+            }
+            const summary = {
+                browser: "cdp" === browserTransport ? "chrome-cdp" : "persistent-context" === browserTransport ? "chrome-playwright" : "chrome-relay",
+                transport: browserTransport,
+                transportRequested,
+                transportUsed: browserTransport,
+                fallbackReason: transportFallbackReason,
+                mode: headless ? "headless" : "headed",
+                persistentProfile: selectedUserDataDir.persistentProfile,
+                profileId: selectedUserDataDir.profileId || null,
+                profilePath: selectedUserDataDir.persistentProfile ? selectedUserDataDir.userDataDir : null,
+                reusedExistingSession: reusedExistingCdpSession,
+                executionWorkspace: workspace,
+                configWorkspace,
+                extensions: extensionIds,
+                finalUrl: page.url(),
+                title: await page.title(),
+                actionResults
+            };
+            return JSON.stringify(summary, null, 2);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown browser error";
+            logger.error(`browser_control failed: ${message}`);
+            return `Error running browser_control: ${message}`;
+        } finally{
+            const contextToClose = launchedContext;
+            if (contextToClose?.close) try {
+                await contextToClose.close();
+            } catch  {}
+            const browserToClose = browser;
+            if (browserToClose) {
+                if (!reusedExistingCdpSession) try {
+                    await browserToClose.close();
+                } catch  {}
+            }
+            const chromeSessionToClose = chromeSession;
+            if (chromeSessionToClose) try {
+                await chromeSessionToClose.close();
+            } catch  {}
+            if (userDataDirSelection?.releaseLock) userDataDirSelection.releaseLock();
+            if (userDataDirSelection && !userDataDirSelection.persistentProfile) deps.removeDir(userDataDirSelection.userDataDir);
+        }
+    }, {
+        name: "browser_control",
+        description: 'Native browser automation for Wingman using Chrome/Chromium runtime control. Transport is selected by config ("auto", "playwright", or "relay"): Playwright persistent-context is preferred for persistent profiles, CDP is used for standard runs with persistent-context fallback, and relay can bridge a live extension-attached tab. This is a first-class runtime capability, not an MCP server. Use it for JavaScript-rendered pages, interactions, screenshots, and structured extraction.',
+        schema: BrowserControlInputSchema
+    });
+};
+export { clearStaleDevtoolsArtifacts, createBrowserControlTool };