@wingman-ai/gateway 0.5.3 → 0.6.0

package/dist/agent/tools/browser_runtime.js

@@ -0,0 +1,1288 @@
+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 { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { array, boolean as external_zod_boolean, discriminatedUnion, enum as external_zod_enum, literal, number, object, string, union } 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_BROWSER_VIDEO_ROOT = ".wingman/browser/videos";
+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 BrowserTransportPreferenceSchema = external_zod_enum([
+    "auto",
+    "playwright",
+    "relay"
+]);
+const BrowserVideoSizeSchema = object({
+    width: number().int().min(1).max(3840).describe("Video width in pixels"),
+    height: number().int().min(1).max(3840).describe("Video height in pixels")
+});
+const BrowserSessionVideoRecordingSchema = union([
+    external_zod_boolean(),
+    object({
+        dir: string().min(1).optional().describe("Relative output directory within the workspace for videos"),
+        size: BrowserVideoSizeSchema.optional().describe("Optional recorded video dimensions")
+    })
+]);
+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."),
+    transport: BrowserTransportPreferenceSchema.optional().describe('Optional per-call browser transport override ("auto", "playwright", or "relay").')
+});
+const BrowserSessionActionInputSchema = object({
+    session_id: string().min(1).describe("Existing browser session id"),
+    url: string().url().optional().describe("Optional URL to open before actions"),
+    actions: array(BrowserActionSchema).max(MAX_ACTIONS).optional().default([]).describe("Ordered browser actions to execute in the existing session"),
+    timeoutMs: number().int().min(1000).max(MAX_ACTION_TIMEOUT_MS).optional().default(DEFAULT_ACTION_TIMEOUT_MS).describe("Per-action timeout in milliseconds")
+});
+const DEFAULT_BROWSER_CONTROL_DEPENDENCIES = {
+    importPlaywright: async ()=>await import("playwright-core"),
+    startChrome: startChromeWithDevtools,
+    resolveRelayWsEndpoint,
+    mkTempDir: ()=>mkdtempSync(join(tmpdir(), "wingman-browser-")),
+    removeDir: (target)=>rmSync(target, {
+            recursive: true,
+            force: true
+        }),
+    now: ()=>Date.now()
+};
+const createBrowserDependencies = (dependencies = {})=>({
+        ...DEFAULT_BROWSER_CONTROL_DEPENDENCIES,
+        ...dependencies
+    });
+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 closeOptionalHandle(candidate) {
+    if (!candidate?.close) return;
+    try {
+        await candidate.close();
+    } catch  {}
+}
+async function closeHandle(candidate) {
+    if (!candidate) return;
+    try {
+        await candidate.close();
+    } 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, videoRecording) {
+    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,
+        ...videoRecording ? {
+            recordVideo: {
+                dir: videoRecording.dirAbsolute,
+                ...videoRecording.size ? {
+                    size: videoRecording.size
+                } : {}
+            }
+        } : {}
+    });
+}
+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?.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 toGatewayFileUrl(absolutePath) {
+    return `/api/fs/file?path=${encodeURIComponent(absolutePath)}`;
+}
+function resolveVideoOutputDir(workspace, requested, now) {
+    if (!requested) return null;
+    const dir = "object" == typeof requested && requested.dir?.trim() ? requested.dir.trim() : join(DEFAULT_BROWSER_VIDEO_ROOT, `recording-${now()}`);
+    if (isAbsolute(dir)) throw new Error("Video recording directory must be relative to the workspace.");
+    const dirAbsolute = resolveWorkspaceRelativePath(workspace, dir);
+    mkdirSync(dirAbsolute, {
+        recursive: true
+    });
+    return {
+        dirAbsolute,
+        dirRelative: relative(workspace, dirAbsolute).split("\\").join("/"),
+        ..."object" == typeof requested && requested.size ? {
+            size: requested.size
+        } : {}
+    };
+}
+function resolveVideoMimeType(pathname) {
+    const extension = extname(pathname).trim().toLowerCase();
+    switch(extension){
+        case ".mp4":
+            return "video/mp4";
+        case ".mov":
+            return "video/quicktime";
+        case ".webm":
+        default:
+            return "video/webm";
+    }
+}
+function buildScreenshotMedia(workspace, actionResults) {
+    return actionResults.flatMap((result, index)=>{
+        if ("screenshot" !== result.type || "string" != typeof result.path || !result.path.trim()) return [];
+        const relativePath = result.path.trim();
+        const absolutePath = "string" == typeof result.absolutePath && result.absolutePath.trim() ? result.absolutePath.trim() : resolveWorkspaceRelativePath(workspace, relativePath);
+        const uri = "string" == typeof result.uri && result.uri.trim() ? result.uri.trim() : toGatewayFileUrl(absolutePath);
+        return [
+            {
+                kind: "image",
+                source: "screenshot",
+                path: absolutePath,
+                relativePath,
+                uri,
+                url: uri,
+                mimeType: "image/png",
+                name: basename(absolutePath),
+                ..."boolean" == typeof result.fullPage ? {
+                    fullPage: result.fullPage
+                } : {},
+                actionIndex: index
+            }
+        ];
+    });
+}
+function summarizeVideoRecording(recording, state, videoCount = 0) {
+    if (!recording) return null;
+    return {
+        enabled: true,
+        state,
+        dir: recording.dirRelative,
+        size: recording.size || null,
+        videoCount
+    };
+}
+async function registerPageVideoHandle(runtime, page) {
+    if (!runtime.videoRecording || "function" != typeof page.video) return;
+    try {
+        const video = page.video();
+        if (video) runtime.videoRecording.handles.add(video);
+    } catch  {}
+}
+async function finalizeRecordedVideos(runtime) {
+    if (!runtime.videoRecording || 0 === runtime.videoRecording.handles.size) return [];
+    const seen = new Set();
+    const media = [];
+    for (const handle of runtime.videoRecording.handles)try {
+        const absolutePath = (await handle.path()).trim();
+        if (!absolutePath) continue;
+        const relativePath = relative(runtime.workspace, absolutePath).split("\\").join("/");
+        if (!relativePath || relativePath.startsWith("..") || isAbsolute(relativePath) || seen.has(relativePath)) continue;
+        seen.add(relativePath);
+        const uri = toGatewayFileUrl(absolutePath);
+        media.push({
+            kind: "video",
+            source: "video-recording",
+            path: absolutePath,
+            relativePath,
+            uri,
+            url: uri,
+            mimeType: resolveVideoMimeType(absolutePath),
+            name: basename(absolutePath)
+        });
+    } catch  {}
+    return media;
+}
+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 runBrowserAction(page, action, timeoutMs, workspace, now, actionIndex) {
+    switch(action.type){
+        case "navigate":
+        case "url":
+        case "open":
+        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":
+        case "sleep":
+        case "pause":
+            await page.waitForTimeout(action.ms);
+            return {
+                type: "wait",
+                ms: action.ms
+            };
+        case "wait_for":
+        case "wait_until":
+            return runConditionalWait(page, action, timeoutMs);
+        case "extract_text":
+        case "extract":
+        case "getContent":
+        case "get_content":
+        case "querySelector":
+        case "query_selector":
+            {
+                const selector = "selector" in action && action.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 "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 "screenshot":
+        case "path":
+        case "snapshot":
+        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,
+                    absolutePath: screenshotPath.absolute,
+                    uri: toGatewayFileUrl(screenshotPath.absolute),
+                    fullPage: Boolean(action.fullPage)
+                };
+            }
+        case "evaluate":
+        case "expression":
+        case "js":
+        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.");
+    }
+}
+const resolveToolOptions = (options)=>{
+    const workspace = options.workspace || process.cwd();
+    return {
+        ...options,
+        workspace,
+        configWorkspace: options.configWorkspace || workspace,
+        launchTimeoutMs: options.launchTimeoutMs || DEFAULT_LAUNCH_TIMEOUT_MS
+    };
+};
+async function openBrowserSessionRuntime(options = {}, dependencies = {}, input = {}) {
+    const resolvedOptions = resolveToolOptions(options);
+    const workspace = resolvedOptions.workspace;
+    const configWorkspace = resolvedOptions.configWorkspace;
+    const deps = createBrowserDependencies(dependencies);
+    let userDataDirSelection = null;
+    let chromeSession = null;
+    let browser = null;
+    let launchedContext = null;
+    let browserTransport = "cdp";
+    let transportFallbackReason = null;
+    let reusedExistingCdpSession = false;
+    let context = null;
+    let videoRecording = null;
+    try {
+        userDataDirSelection = resolveUserDataDir(configWorkspace, resolvedOptions, deps);
+        const selectedUserDataDir = userDataDirSelection;
+        const headless = resolveHeadlessMode(input.headless, selectedUserDataDir.persistentProfile);
+        const timeoutMs = input.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
+        const startupTimeoutMs = Math.max(resolvedOptions.launchTimeoutMs, timeoutMs);
+        const playwright = await deps.importPlaywright();
+        const relayConfig = resolveRelayConfig(resolvedOptions);
+        const executablePath = input.executablePath || resolvedOptions.defaultExecutablePath;
+        const { extensionIds, extensionDirs } = resolveEnabledExtensions(configWorkspace, resolvedOptions);
+        const chromeArgs = buildChromeArgs(extensionDirs);
+        const requestedVideoRecording = resolveVideoOutputDir(workspace, input.recordVideo, deps.now);
+        const usePersistentLaunch = preferPersistentLaunch(resolvedOptions, selectedUserDataDir.persistentProfile);
+        const effectivePersistentLaunch = usePersistentLaunch || Boolean(requestedVideoRecording);
+        const transportRequested = resolveBrowserTransportPreference(input.transport || resolvedOptions.browserTransport);
+        if (requestedVideoRecording && "relay" === transportRequested) throw new Error("Video recording is only supported with Playwright persistent launch sessions.");
+        if (requestedVideoRecording) videoRecording = {
+            ...requestedVideoRecording,
+            handles: new Set()
+        };
+        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 (effectivePersistentLaunch) {
+                launchedContext = await launchPersistentContext(playwright, selectedUserDataDir.userDataDir, executablePath, headless, startupTimeoutMs, chromeArgs, videoRecording);
+                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, videoRecording);
+                            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, videoRecording);
+                        context = launchedContext;
+                        browserTransport = "persistent-context";
+                    }
+                }
+            }
+        };
+        if ("relay" === transportRequested) await initializeViaRelay(startupTimeoutMs);
+        else try {
+            await initializeViaPlaywright();
+        } catch (playwrightError) {
+            if ("auto" !== transportRequested || !relayConfig || requestedVideoRecording) 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.");
+        return {
+            workspace,
+            configWorkspace,
+            now: deps.now,
+            headless,
+            context: resolvedContext,
+            activePage: null,
+            userDataDirSelection: selectedUserDataDir,
+            browserTransport,
+            transportRequested,
+            transportFallbackReason,
+            reusedExistingCdpSession,
+            extensionIds,
+            launchedContext,
+            browser,
+            chromeSession,
+            videoRecording,
+            closed: false
+        };
+    } catch (error) {
+        await closeOptionalHandle(launchedContext);
+        if (!reusedExistingCdpSession) await closeHandle(browser);
+        await closeHandle(chromeSession);
+        if (userDataDirSelection?.releaseLock) userDataDirSelection.releaseLock();
+        if (userDataDirSelection && !userDataDirSelection.persistentProfile) deps.removeDir(userDataDirSelection.userDataDir);
+        throw error;
+    }
+}
+function getPageUrl(page) {
+    try {
+        return page.url().trim();
+    } catch  {
+        return "";
+    }
+}
+function isBrowserInternalPageUrl(url) {
+    const normalized = url.trim().toLowerCase();
+    if (!normalized) return true;
+    return normalized.startsWith("about:blank") || normalized.startsWith("chrome://") || normalized.startsWith("chrome-extension://") || normalized.startsWith("devtools://") || normalized.startsWith("edge://") || normalized.startsWith("extension://") || normalized.startsWith("moz-extension://");
+}
+function selectPreferredPage(pages) {
+    for(let index = pages.length - 1; index >= 0; index -= 1){
+        const candidate = pages[index];
+        if (candidate) {
+            if (!isBrowserInternalPageUrl(getPageUrl(candidate))) return candidate;
+        }
+    }
+    return pages.at(-1) || null;
+}
+async function selectActivePage(runtime) {
+    const pages = runtime.context.pages();
+    const preferredPage = selectPreferredPage(pages);
+    let page = runtime.activePage && pages.includes(runtime.activePage) ? runtime.activePage : null;
+    if (preferredPage && (!page || isBrowserInternalPageUrl(getPageUrl(page)))) page = preferredPage;
+    if (!page) page = await runtime.context.newPage();
+    runtime.activePage = page;
+    if ("function" == typeof page.bringToFront) await page.bringToFront();
+    return page;
+}
+async function executeBrowserSessionRuntime(runtime, input = {}) {
+    if (runtime.closed) throw new Error("Browser session is already closed.");
+    const timeoutMs = input.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
+    const page = await selectActivePage(runtime);
+    await registerPageVideoHandle(runtime, page);
+    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 runBrowserAction(page, action, timeoutMs, runtime.workspace, runtime.now, index);
+        actionResults.push(result);
+    }
+    const media = buildScreenshotMedia(runtime.workspace, actionResults);
+    return {
+        browser: "cdp" === runtime.browserTransport ? "chrome-cdp" : "persistent-context" === runtime.browserTransport ? "chrome-playwright" : "chrome-relay",
+        transport: runtime.browserTransport,
+        transportRequested: runtime.transportRequested,
+        transportUsed: runtime.browserTransport,
+        fallbackReason: runtime.transportFallbackReason,
+        mode: runtime.headless ? "headless" : "headed",
+        persistentProfile: runtime.userDataDirSelection.persistentProfile,
+        profileId: runtime.userDataDirSelection.profileId || null,
+        profilePath: runtime.userDataDirSelection.persistentProfile ? runtime.userDataDirSelection.userDataDir : null,
+        reusedExistingSession: runtime.reusedExistingCdpSession,
+        executionWorkspace: runtime.workspace,
+        configWorkspace: runtime.configWorkspace,
+        extensions: runtime.extensionIds,
+        finalUrl: page.url(),
+        title: await page.title(),
+        actionResults,
+        media,
+        videoRecording: summarizeVideoRecording(runtime.videoRecording, runtime.videoRecording ? "recording" : "inactive", 0)
+    };
+}
+async function closeBrowserSessionRuntime(runtime, dependencies = {}) {
+    if (runtime.closed) return {
+        media: [],
+        videoRecording: summarizeVideoRecording(runtime.videoRecording, "inactive", 0)
+    };
+    runtime.closed = true;
+    const deps = createBrowserDependencies(dependencies);
+    const recording = runtime.videoRecording;
+    await closeOptionalHandle(runtime.launchedContext);
+    const media = await finalizeRecordedVideos(runtime);
+    if (runtime.browser && !runtime.reusedExistingCdpSession) await closeHandle(runtime.browser);
+    await closeHandle(runtime.chromeSession);
+    if (runtime.userDataDirSelection.releaseLock) runtime.userDataDirSelection.releaseLock();
+    if (!runtime.userDataDirSelection.persistentProfile) deps.removeDir(runtime.userDataDirSelection.userDataDir);
+    return {
+        media,
+        videoRecording: summarizeVideoRecording(recording, recording ? "saved" : "inactive", media.length)
+    };
+}
+export { BrowserActionSchema, BrowserControlInputSchema, BrowserSessionActionInputSchema, BrowserSessionVideoRecordingSchema, BrowserTransportPreferenceSchema, DEFAULT_ACTION_TIMEOUT_MS, clearStaleDevtoolsArtifacts, closeBrowserSessionRuntime, createBrowserDependencies, executeBrowserSessionRuntime, openBrowserSessionRuntime, runBrowserAction };