pi-agent-browser-native 0.9.3 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/native-config.js

@@ -0,0 +1,144 @@
+import { readFile, rm } from "node:fs/promises";
+import { isRecord } from "../parsing.js";
+import { isUpstreamEnvFlagEnabled } from "../argv-grammar.js";
+import { runAgentBrowserProcess } from "../process.js";
+import { parseAgentBrowserEnvelope } from "../results/envelope.js";
+// Native local launch defaults must keep their launch-time argument policy stable.
+const VALUE_DEFAULTS = [
+    "executablePath",
+    "profile",
+    "state",
+    "proxy",
+    "args",
+    "userAgent",
+    "caCert",
+    "colorScheme",
+    "downloadPath",
+    "engine",
+    "allowedDomains",
+];
+const BOOLEAN_DEFAULTS = ["headed", "allowFileAccess", "webgpu", "noWebmcp"];
+const ARRAY_DEFAULTS = ["extensions", "initScripts", "enable"];
+export function nativeEnvName(key) {
+    return `AGENT_BROWSER_${key.replace(/[A-Z]/g, (letter) => `_${letter}`).toUpperCase()}`;
+}
+function nativeBooleanDefault(config, env, key) {
+    const value = env[nativeEnvName(key)];
+    if (key === "hideScrollbars") {
+        return value === undefined ? config[key] === false : !isUpstreamEnvFlagEnabled(value);
+    }
+    return value === undefined ? config[key] === true : isUpstreamEnvFlagEnabled(value);
+}
+export function hasLocalLaunchDefaults(config, env) {
+    return (VALUE_DEFAULTS.some((key) => env[nativeEnvName(key)] !== undefined || config[key] !== undefined) ||
+        BOOLEAN_DEFAULTS.some((key) => isUpstreamEnvFlagEnabled(env[nativeEnvName(key)]) || config[key] === true) ||
+        ARRAY_DEFAULTS.some((key) => (env[nativeEnvName(key)] ?? "").length > 0 ||
+            (Array.isArray(config[key]) && config[key].length > 0)) ||
+        nativeBooleanDefault(config, env, "clearCaCert") ||
+        nativeBooleanDefault(config, env, "hideScrollbars") ||
+        ["HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy"].some((key) => env[key] !== undefined));
+}
+function localFlag(key) {
+    switch (key) {
+        case "extensions":
+            return "--extension";
+        case "initScripts":
+            return "--init-script";
+        case "clearCaCert":
+            return "--no-ca-cert";
+        default:
+            return `--${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+    }
+}
+export const LOCAL_LAUNCH_DEFAULT_FLAGS = [
+    ...VALUE_DEFAULTS,
+    ...BOOLEAN_DEFAULTS,
+    ...ARRAY_DEFAULTS,
+    "hideScrollbars",
+    "clearCaCert",
+].map(localFlag);
+function requestsLaunch(config, options) {
+    const browserLaunch = options.browserCommand &&
+        (hasLocalLaunchDefaults(config, {}) ||
+            ["cdp", "autoConnect", "provider"].some((key) => config[key] !== undefined));
+    const rootLaunch = options.rootFallback &&
+        ["restore", "sessionName", "state", "allowedDomains", "profile", "executablePath"].some((key) => config[key] !== undefined);
+    return browserLaunch || rootLaunch;
+}
+async function readConfigFile(path) {
+    try {
+        const config = JSON.parse(await readFile(path, "utf8"));
+        if (!isRecord(config)) {
+            return undefined;
+        }
+        // Only identity is interpreted here; native validates every launch/config field.
+        return {
+            ...config,
+            session: typeof config.session === "string" ? config.session : undefined,
+            namespace: typeof config.namespace === "string" ? config.namespace : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function needsIdentityInspection(config, options) {
+    return (requestsLaunch(config, options) ||
+        config.confirmActions !== undefined ||
+        config.session !== undefined ||
+        config.namespace !== undefined);
+}
+function resolvedIdentity(config, data) {
+    if (!isRecord(data) || typeof data.session !== "string") {
+        throw new Error("Native agent-browser session inspection returned no session name; the browser command was not run.");
+    }
+    const { session: _session, namespace: _namespace, ...defaults } = config;
+    return {
+        ...defaults,
+        ...(config.session !== undefined ? { session: data.session } : {}),
+        ...(config.namespace !== undefined ? { namespace: config.namespace } : {}),
+    };
+}
+// Native `session` reports resolution, not whether a name was configured.
+async function readNativeIdentity(path, options) {
+    const config = await readConfigFile(path);
+    if (config === undefined) {
+        return {};
+    }
+    if (!needsIdentityInspection(config, options)) {
+        return {};
+    }
+    const result = await runAgentBrowserProcess({
+        args: ["--config", path, "--json", "session"],
+        cwd: options.cwd,
+        signal: options.signal,
+        timeoutMs: 5_000,
+    });
+    try {
+        if (result.aborted || result.timedOut || result.spawnError !== undefined) {
+            throw new Error("Could not resolve native agent-browser session configuration; the browser command was not run.");
+        }
+        if (result.exitCode !== 0) {
+            return {};
+        } // Discovered invalid files are native-ignored; explicit paths fail on the real command.
+        const parsed = await parseAgentBrowserEnvelope({
+            stdout: result.stdout,
+            stdoutPath: result.stdoutSpillPath,
+        });
+        return resolvedIdentity(config, parsed.envelope?.data);
+    }
+    finally {
+        if (result.stdoutSpillPath !== undefined && result.stdoutSpillPath.length > 0) {
+            await rm(result.stdoutSpillPath, { force: true });
+        }
+    }
+}
+export async function loadNativeIdentity(paths, options) {
+    const identity = {};
+    for (const path of paths) {
+        // Project defaults override global defaults; native validation must finish in that layer order.
+        // oxlint-disable-next-line no-await-in-loop
+        Object.assign(identity, await readNativeIdentity(path, options));
+    }
+    return identity;
+}

package/dist/extensions/agent-browser/lib/orchestration/native-root-launch.js

@@ -0,0 +1,77 @@
+import { scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
+import { withAgentBrowserProcessEnvironment } from "../process-environment.js";
+import { withChromeStartupArgs } from "../process.js";
+import { buildValidationFailureResult } from "./input-plan.js";
+import { inspectManagedSessionDaemon } from "./browser-run/managed-session-daemon-policy.js";
+import { buildMissingBinaryMessage } from "./browser-run/final-result-missing-binary.js";
+function cliValue(args, flag) {
+    return scanUpstreamGlobalFlagOccurrences([...args], flag).at(-1)?.value;
+}
+function bootstrapProfile(policy, bootstrap) {
+    const allowed = bootstrap &&
+        policy.chromeEngine &&
+        policy.restoreEligible &&
+        policy.identity.profile === undefined &&
+        policy.env.AGENT_BROWSER_PROFILE === undefined;
+    return (cliValue(policy.input.toolArgs, "--profile") ?? (allowed ? policy.defaultProfile : undefined));
+}
+function bootstrapExecutable(policy, bootstrap) {
+    const allowed = bootstrap &&
+        policy.chromeEngine &&
+        policy.identity.executablePath === undefined &&
+        policy.env.AGENT_BROWSER_EXECUTABLE_PATH === undefined;
+    return (cliValue(policy.input.toolArgs, "--executable-path") ??
+        (allowed ? policy.defaultExecutable : undefined));
+}
+function rootRestoreKey(policy, status, restoreKey) {
+    if (!policy.restoreEligible) {
+        return undefined;
+    }
+    if (status === "active") {
+        return restoreKey ?? undefined;
+    }
+    return status === "inactive" ? policy.rootName : undefined;
+}
+export async function withRootBrowserLaunch(policy, browserRun, signal) {
+    const daemon = await inspectManagedSessionDaemon({
+        cwd: policy.cwd,
+        signal,
+        sessionName: policy.rootName,
+        namespace: cliValue(policy.input.toolArgs, "--namespace") ?? policy.namespace,
+        timeoutMs: 5_000,
+    });
+    if (daemon.status === "missing-binary") {
+        return {
+            content: [{ type: "text", text: buildMissingBinaryMessage() }],
+            details: {
+                agentBrowserStarted: false,
+                args: policy.input.redactedArgs,
+                sessionName: policy.rootName,
+                resultCategory: "failure",
+                failureCategory: "missing-binary",
+            },
+            isError: true,
+        };
+    }
+    if (policy.input.kind === "qa" &&
+        policy.input.compiledQaPreset.checks.attached &&
+        daemon.status !== "active") {
+        return buildValidationFailureResult({
+            ...policy.input,
+            attemptedKind: "qa",
+            kind: "invalid",
+            status: "invalid",
+            validationError: "qa.attached requires an active attached session. Open the root browser first, or select an existing native session.",
+        });
+    }
+    // Active native daemons own their launch choices; defaults may only bootstrap or preserve explicit local options.
+    const bootstrap = daemon.status === "inactive";
+    const restore = rootRestoreKey(policy, daemon.status, daemon.status === "active" ? daemon.restoreKey : undefined);
+    const profile = bootstrapProfile(policy, bootstrap);
+    const executablePath = bootstrapExecutable(policy, bootstrap);
+    return withAgentBrowserProcessEnvironment({
+        ...(restore !== undefined ? { AGENT_BROWSER_RESTORE: restore } : {}),
+        ...(profile !== undefined ? { AGENT_BROWSER_PROFILE: profile } : {}),
+        ...(executablePath !== undefined ? { AGENT_BROWSER_EXECUTABLE_PATH: executablePath } : {}),
+    }, () => withChromeStartupArgs(bootstrap || policy.configuredChromeLaunch ? policy.chromeStartupArgs : undefined, () => browserRun(bootstrap)));
+}

package/dist/extensions/agent-browser/lib/orchestration/native-session-defaults.js

@@ -1,178 +1,231 @@
 import { createHash } from "node:crypto";
-import { readFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { extractExplicitSessionName, getBooleanFlagValue, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
-import { isRecord } from "../parsing.js";
+import { extractExplicitSessionName, getBooleanFlagValue, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "../argv-grammar.js";
 import { parseArgvDescriptor } from "../argv-descriptor.js";
 import { needsManagedSession } from "../command-policy.js";
 import { getUpstreamEffectiveBatchSteps } from "./batch-stdin.js";
 import { hasLaunchScopedFlagToken } from "../launch-scoped-flags.js";
-import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment } from "../process-environment.js";
-import { runAgentBrowserProcess, withChromeStartupArgs } from "../process.js";
-import { parseAgentBrowserEnvelope } from "../results/envelope.js";
+import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment, } from "../process-environment.js";
 import { isPlainTextInspectionArgs } from "../runtime.js";
-import { buildValidationFailureResult } from "./input-plan.js";
-import { inspectManagedSessionDaemon } from "./browser-run/managed-session-daemon-policy.js";
-import { buildMissingBinaryMessage } from "./browser-run/final-result.js";
-// These native defaults already send a local launch command on every call; keep its args stable too.
-const LOCAL_VALUE_DEFAULTS = ["executablePath", "profile", "state", "proxy", "args", "userAgent", "caCert", "colorScheme", "downloadPath", "engine", "allowedDomains"];
-const LOCAL_BOOLEAN_DEFAULTS = ["headed", "allowFileAccess", "webgpu", "noWebmcp"];
-const LOCAL_ARRAY_DEFAULTS = ["extensions", "initScripts", "enable"];
-const nativeEnvName = (key) => `AGENT_BROWSER_${key.replace(/[A-Z]/g, letter => `_${letter}`).toUpperCase()}`;
-function hasLocalLaunchDefaults(config, env) {
-    return LOCAL_VALUE_DEFAULTS.some(key => env[nativeEnvName(key)] !== undefined || config[key] !== undefined)
-        || LOCAL_BOOLEAN_DEFAULTS.some(key => isUpstreamEnvFlagEnabled(env[nativeEnvName(key)]) || config[key] === true)
-        || LOCAL_ARRAY_DEFAULTS.some(key => (env[nativeEnvName(key)]?.length ?? 0) > 0 || Array.isArray(config[key]) && config[key].length > 0)
-        || (env.AGENT_BROWSER_CLEAR_CA_CERT !== undefined ? isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_CLEAR_CA_CERT) : config.clearCaCert === true)
-        || (env.AGENT_BROWSER_HIDE_SCROLLBARS !== undefined ? !isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_HIDE_SCROLLBARS) : config.hideScrollbars === false)
-        || ["HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy"].some(key => env[key] !== undefined);
+import { hasLocalLaunchDefaults, loadNativeIdentity, LOCAL_LAUNCH_DEFAULT_FLAGS, } from "./native-config.js";
+import { withRootBrowserLaunch } from "./native-root-launch.js";
+function cliValue(args, flag) {
+    return scanUpstreamGlobalFlagOccurrences([...args], flag).at(-1)?.value;
 }
 function requestsConnection(tokens, stdin) {
-    return tokens[0] === "connect" || getUpstreamEffectiveBatchSteps(tokens, stdin).some(step => requestsConnection(step));
+    return (tokens[0] === "connect" ||
+        getUpstreamEffectiveBatchSteps(tokens, stdin).some((step) => requestsConnection(step)));
 }
 function rootBrowserSessionName(rootSessionId) {
     return `pi-root-${createHash("sha256").update(rootSessionId).digest("hex").slice(0, 24)}`;
 }
-// Native `session` reports the resolved name, but not whether it was configured.
-// Native validates its schema; retain configured launch defaults so root fallbacks never replace them.
-async function readNativeIdentity(path, cwd, signal, rootFallback, browserCommand) {
-    let config;
-    try {
-        config = JSON.parse(await readFile(path, "utf8"));
-    }
-    catch {
-        return {};
-    }
-    if (!isRecord(config))
-        return {};
-    const rootLaunchConfig = browserCommand && (hasLocalLaunchDefaults(config, {}) || ["cdp", "autoConnect", "provider"].some((key) => config[key] !== undefined))
-        || rootFallback && ["restore", "sessionName", "state", "allowedDomains", "profile", "executablePath"].some((key) => config[key] !== undefined);
-    if (!rootLaunchConfig && config.confirmActions === undefined && typeof config.session !== "string" && typeof config.namespace !== "string")
-        return {};
-    const result = await runAgentBrowserProcess({ args: ["--config", path, "--json", "session"], cwd, signal, timeoutMs: 5_000 });
-    try {
-        if (result.aborted || result.timedOut || result.spawnError)
-            throw new Error("Could not resolve native agent-browser session configuration; the browser command was not run.");
-        if (result.exitCode !== 0)
-            return {}; // Native ignores invalid discovered files; explicit files fail again in the actual command.
-        const parsed = await parseAgentBrowserEnvelope({ stdout: result.stdout, stdoutPath: result.stdoutSpillPath });
-        const data = parsed.envelope?.data;
-        if (!isRecord(data) || typeof data.session !== "string")
-            throw new Error("Native agent-browser session inspection returned no session name; the browser command was not run.");
-        const { session: _session, namespace: _namespace, ...defaults } = config;
+function nativeBooleanOverrides(args) {
+    const overrides = [];
+    for (const flag of ["--debug", "--no-auto-dialog"]) {
+        const value = getBooleanFlagValue([...args], flag);
+        if (value !== undefined) {
+            overrides.push([flag, String(value)]);
+        }
+    }
+    return overrides;
+}
+/** Owns one native config resolution and pure adaptation, never browser/auth authority. */
+class NativeSessionCall {
+    input;
+    context;
+    runner;
+    env = getAgentBrowserProcessEnvironment();
+    configPath;
+    configPaths;
+    rootName;
+    browserCommand;
+    rootFallback;
+    identity = {};
+    constructor(input, context, runner) {
+        this.input = input;
+        this.context = context;
+        this.runner = runner;
+        const configArg = scanUpstreamGlobalFlagOccurrences([...input.toolArgs], "--config").at(0);
+        this.configPath = configArg?.value ?? this.env.AGENT_BROWSER_CONFIG;
+        this.configPaths =
+            this.configPath !== undefined
+                ? [resolve(context.cwd, this.configPath)]
+                : [
+                    join(homedir(), ".agent-browser", "config.json"),
+                    join(context.cwd, "agent-browser.json"),
+                ];
+        this.rootName =
+            context.root === undefined ? undefined : rootBrowserSessionName(context.root.id);
+        this.browserCommand =
+            input.kind !== "electron" &&
+                needsManagedSession(parseArgvDescriptor([...input.toolArgs]), input.toolStdin);
+        const session = extractExplicitSessionName([...input.toolArgs]);
+        this.rootFallback =
+            context.root !== undefined &&
+                this.env.AGENT_BROWSER_SESSION === undefined &&
+                (session === undefined || session === this.rootName) &&
+                this.browserCommand;
+    }
+    attachment() {
+        const autoConnect = getBooleanFlagValue([...this.input.toolArgs], "--auto-connect") ??
+            (isUpstreamEnvFlagEnabled(this.env.AGENT_BROWSER_AUTO_CONNECT) ||
+                this.identity.autoConnect === true);
+        return (hasLaunchScopedFlagToken([...this.input.toolArgs], "--cdp") ||
+            this.env.AGENT_BROWSER_CDP !== undefined ||
+            this.identity.cdp !== undefined ||
+            autoConnect ||
+            parseArgvDescriptor([...this.input.toolArgs]).upstreamCommandTokens[0] === "connect");
+    }
+    restoreEligible() {
+        return (![
+            "--restore",
+            "--session-name",
+            "--state",
+            "--allowed-domains",
+            "--provider",
+            "-p",
+            "--device",
+        ].some((flag) => hasLaunchScopedFlagToken([...this.input.toolArgs], flag)) &&
+            !["restore", "sessionName", "state", "allowedDomains", "provider"].some((key) => this.identity[key] !== undefined) &&
+            ![
+                "AGENT_BROWSER_RESTORE",
+                "AGENT_BROWSER_SESSION_NAME",
+                "AGENT_BROWSER_STATE",
+                "AGENT_BROWSER_ALLOWED_DOMAINS",
+                "AGENT_BROWSER_PROVIDER",
+            ].some((key) => this.env[key] !== undefined));
+    }
+    chromeLaunch() {
+        const args = this.input.toolArgs;
+        const engine = cliValue(args, "--engine") ?? this.env.AGENT_BROWSER_ENGINE ?? this.identity.engine;
+        const chromeEngine = engine === undefined || engine === "chrome";
+        const nativeLaunchDefaults = hasLocalLaunchDefaults(this.identity, this.env);
+        // Native config/env can submit launch options on local commands too. Leave their args
+        // unchanged so browser calls and sessionless helpers do not reconfigure the same daemon.
+        const chromeStartupArgs = nativeLaunchDefaults
+            ? undefined
+            : this.chromeStartupArgs(chromeEngine);
+        const configuredChromeLaunch = nativeLaunchDefaults ||
+            LOCAL_LAUNCH_DEFAULT_FLAGS.some((flag) => scanUpstreamGlobalFlagOccurrences([...args], flag).length > 0);
+        return { chromeEngine, chromeStartupArgs, configuredChromeLaunch };
+    }
+    chromeStartupArgs(chromeEngine) {
+        if (!this.localChrome(chromeEngine)) {
+            return undefined;
+        }
+        const launchArgs = cliValue(this.input.toolArgs, "--args") ?? this.env.AGENT_BROWSER_ARGS ?? this.identity.args;
+        return ["--no-startup-window", ...(typeof launchArgs === "string" ? [launchArgs] : [])].join(",");
+    }
+    localChrome(chromeEngine) {
+        const args = this.input.toolArgs;
+        const provider = cliValue(args, "--provider") ??
+            cliValue(args, "-p") ??
+            this.env.AGENT_BROWSER_PROVIDER ??
+            this.identity.provider;
+        const batchAttaches = requestsConnection(parseArgvDescriptor([...args]).upstreamCommandTokens, this.input.toolStdin);
+        return (this.browserCommand &&
+            !this.attachment() &&
+            !batchAttaches &&
+            provider === undefined &&
+            chromeEngine);
+    }
+    confirmationActions(args) {
+        return (cliValue(args, "--confirm-actions") ??
+            this.env.AGENT_BROWSER_CONFIRM_ACTIONS ??
+            (typeof this.identity.confirmActions === "string" ? this.identity.confirmActions : undefined));
+    }
+    configEnvironment() {
+        return this.configPath === undefined
+            ? {}
+            : { AGENT_BROWSER_CONFIG: resolve(this.context.cwd, this.configPath) };
+    }
+    executionEnvironment(args, session, namespace) {
+        const idle = cliValue(args, "--idle-timeout");
+        const actionPolicy = cliValue(args, "--action-policy");
+        const confirm = cliValue(args, "--confirm-actions");
+        return {
+            ...(idle !== undefined ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: idle } : {}),
+            ...(actionPolicy !== undefined ? { AGENT_BROWSER_ACTION_POLICY: actionPolicy } : {}),
+            ...(confirm !== undefined ? { AGENT_BROWSER_CONFIRM_ACTIONS: confirm } : {}),
+            ...this.booleanEnvironment(args),
+            ...this.configEnvironment(),
+            ...(session !== undefined ? { AGENT_BROWSER_SESSION: session } : {}),
+            ...(namespace !== undefined ? { AGENT_BROWSER_NAMESPACE: namespace } : {}),
+        };
+    }
+    booleanEnvironment(args) {
+        const debug = getBooleanFlagValue([...args], "--debug");
+        const noAutoDialog = getBooleanFlagValue([...args], "--no-auto-dialog");
         return {
-            ...defaults,
-            ...(typeof config.session === "string" ? { session: data.session } : {}),
-            ...(typeof config.namespace === "string" ? { namespace: config.namespace } : {}),
+            ...(debug !== undefined ? { AGENT_BROWSER_DEBUG: debug ? "1" : undefined } : {}),
+            ...(noAutoDialog !== undefined
+                ? { AGENT_BROWSER_NO_AUTO_DIALOG: noAutoDialog ? "1" : "0" }
+                : {}),
         };
     }
-    finally {
-        if (result.stdoutSpillPath)
-            await rm(result.stdoutSpillPath, { force: true });
+    runElectron() {
+        const nativeConfirmActions = this.env.AGENT_BROWSER_CONFIRM_ACTIONS ??
+            (typeof this.identity.confirmActions === "string" ? this.identity.confirmActions : undefined);
+        const launch = this.input.kind === "electron" && this.input.compiledElectron.action === "launch";
+        return withAgentBrowserProcessEnvironment({ ...(launch ? { AGENT_BROWSER_SESSION: undefined } : {}), ...this.configEnvironment() }, () => this.runner({ ...this.input, nativeConfirmActions }));
+    }
+    rootDefaultSession(configuredSession) {
+        return this.rootName !== undefined &&
+            configuredSession === undefined &&
+            this.rootFallback &&
+            !this.attachment()
+            ? this.rootName
+            : undefined;
+    }
+    runBrowser() {
+        const configuredSession = this.env.AGENT_BROWSER_SESSION ?? this.identity.session;
+        const rootDefault = this.rootDefaultSession(configuredSession);
+        const session = configuredSession ?? rootDefault;
+        const namespace = this.env.AGENT_BROWSER_NAMESPACE ?? this.identity.namespace;
+        const args = session !== undefined && extractExplicitSessionName([...this.input.toolArgs]) === undefined
+            ? ["--session", session, ...this.input.toolArgs]
+            : this.input.toolArgs;
+        const launch = this.chromeLaunch();
+        const input = {
+            ...this.input,
+            toolArgs: args,
+            nativeConfirmActions: this.confirmationActions(args),
+            chromeStartupArgs: launch.chromeStartupArgs,
+            configuredChromeLaunch: launch.configuredChromeLaunch,
+        };
+        const defaults = rootDefault === undefined
+            ? undefined
+            : this.rootLaunchRunner({
+                ...launch,
+                cwd: this.context.cwd,
+                rootName: rootDefault,
+                namespace,
+                input,
+                env: this.env,
+                identity: this.identity,
+                restoreEligible: this.restoreEligible(),
+                defaultProfile: this.context.root?.profile,
+                defaultExecutable: this.context.root?.executablePath,
+            });
+        return withAgentBrowserProcessEnvironment(this.executionEnvironment(args, session, namespace), () => this.runner(input, defaults), nativeBooleanOverrides(args));
+    }
+    rootLaunchRunner(policy) {
+        return (browserRun, signal = this.context.signal) => withRootBrowserLaunch(policy, browserRun, signal);
+    }
+    async run() {
+        this.identity = await loadNativeIdentity(this.configPaths, {
+            cwd: this.context.cwd,
+            signal: this.context.signal,
+            rootFallback: this.rootFallback,
+            browserCommand: this.browserCommand,
+        });
+        return this.input.kind === "electron" ? this.runElectron() : this.runBrowser();
     }
 }
-export async function withNativeSessionDefaults(input, cwd, signal, run, root) {
-    if (isPlainTextInspectionArgs(input.toolArgs))
+export async function withNativeSessionDefaults(input, context, run) {
+    if (isPlainTextInspectionArgs([...input.toolArgs])) {
         return run(input);
-    const env = getAgentBrowserProcessEnvironment();
-    const configArg = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--config")[0];
-    const configPath = configArg?.value ?? env.AGENT_BROWSER_CONFIG;
-    const paths = configPath !== undefined
-        ? [resolve(cwd, configPath)]
-        : [join(homedir(), ".agent-browser", "config.json"), join(cwd, "agent-browser.json")];
-    const rootName = root && rootBrowserSessionName(root.id);
-    const explicitSession = extractExplicitSessionName(input.toolArgs);
-    const browserCommand = input.kind !== "electron" && needsManagedSession(parseArgvDescriptor(input.toolArgs), input.toolStdin);
-    const rootFallback = root !== undefined && env.AGENT_BROWSER_SESSION === undefined && (explicitSession === undefined || explicitSession === rootName)
-        && browserCommand;
-    let identity = {};
-    for (const path of paths)
-        identity = { ...identity, ...await readNativeIdentity(path, cwd, signal, rootFallback, browserCommand) };
-    if (input.kind === "electron") {
-        const nativeConfirmActions = env.AGENT_BROWSER_CONFIRM_ACTIONS ?? (typeof identity.confirmActions === "string" ? identity.confirmActions : undefined);
-        return withAgentBrowserProcessEnvironment({
-            ...(input.compiledElectron.action === "launch" ? { AGENT_BROWSER_SESSION: undefined } : {}),
-            ...(configPath !== undefined ? { AGENT_BROWSER_CONFIG: resolve(cwd, configPath) } : {}),
-        }, () => run({ ...input, nativeConfirmActions }));
-    }
-    // Native ORs environment/config booleans; only CLI false overrides configured auto-connect.
-    const autoConnect = getBooleanFlagValue(input.toolArgs, "--auto-connect")
-        ?? (isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_AUTO_CONNECT) || identity.autoConnect === true);
-    const attachment = hasLaunchScopedFlagToken(input.toolArgs, "--cdp")
-        || env.AGENT_BROWSER_CDP !== undefined || identity.cdp !== undefined || autoConnect
-        || parseArgvDescriptor(input.toolArgs).upstreamCommandTokens[0] === "connect";
-    const configuredSession = env.AGENT_BROWSER_SESSION ?? identity.session;
-    const launchArgs = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--args").at(-1)?.value ?? env.AGENT_BROWSER_ARGS ?? identity.args;
-    const engine = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--engine").at(-1)?.value ?? env.AGENT_BROWSER_ENGINE ?? identity.engine;
-    const chromeEngine = engine === undefined || engine === "chrome";
-    const provider = scanUpstreamGlobalFlagOccurrences(input.toolArgs, "--provider").at(-1)?.value ?? scanUpstreamGlobalFlagOccurrences(input.toolArgs, "-p").at(-1)?.value ?? env.AGENT_BROWSER_PROVIDER ?? identity.provider;
-    const tokens = parseArgvDescriptor(input.toolArgs).upstreamCommandTokens;
-    const batchAttaches = requestsConnection(tokens, input.toolStdin);
-    const localChrome = browserCommand && !attachment && !batchAttaches && provider === undefined
-        && chromeEngine;
-    const chromeStartupArgs = localChrome ? ["--no-startup-window", ...(typeof launchArgs === "string" ? [launchArgs] : [])].join(",") : undefined;
-    const persistentChromeArgs = hasLocalLaunchDefaults(identity, env) ? chromeStartupArgs : undefined;
-    const configuredChromeLaunch = persistentChromeArgs !== undefined || [...LOCAL_VALUE_DEFAULTS, ...LOCAL_BOOLEAN_DEFAULTS, ...LOCAL_ARRAY_DEFAULTS, "hideScrollbars", "clearCaCert"].some(key => {
-        const flag = { extensions: "--extension", initScripts: "--init-script", clearCaCert: "--no-ca-cert" }[key] ?? `--${key.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`)}`;
-        return scanUpstreamGlobalFlagOccurrences(input.toolArgs, flag).length > 0;
-    });
-    const rootDefault = rootName && configuredSession === undefined && rootFallback && !attachment
-        ? rootName : undefined;
-    const session = configuredSession ?? rootDefault;
-    const restoreEligible = !["--restore", "--session-name", "--state", "--allowed-domains", "--provider", "-p", "--device"].some((flag) => hasLaunchScopedFlagToken(input.toolArgs, flag))
-        && !["restore", "sessionName", "state", "allowedDomains", "provider"].some((key) => identity[key] !== undefined)
-        && !["AGENT_BROWSER_RESTORE", "AGENT_BROWSER_SESSION_NAME", "AGENT_BROWSER_STATE", "AGENT_BROWSER_ALLOWED_DOMAINS", "AGENT_BROWSER_PROVIDER"].some((key) => env[key] !== undefined);
-    const namespace = env.AGENT_BROWSER_NAMESPACE ?? identity.namespace;
-    let args = input.toolArgs;
-    if (session !== undefined && extractExplicitSessionName(args) === undefined)
-        args = ["--session", session, ...args];
-    const idleTimeout = scanUpstreamGlobalFlagOccurrences(args, "--idle-timeout").at(-1)?.value;
-    const actionPolicy = scanUpstreamGlobalFlagOccurrences(args, "--action-policy").at(-1)?.value;
-    const confirmActions = scanUpstreamGlobalFlagOccurrences(args, "--confirm-actions").at(-1)?.value;
-    const nativeConfirmActions = confirmActions ?? env.AGENT_BROWSER_CONFIRM_ACTIONS
-        ?? (typeof identity.confirmActions === "string" ? identity.confirmActions : undefined);
-    const debug = getBooleanFlagValue(args, "--debug");
-    const noAutoDialog = getBooleanFlagValue(args, "--no-auto-dialog");
-    return withAgentBrowserProcessEnvironment({
-        ...(idleTimeout !== undefined ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: idleTimeout } : {}),
-        ...(actionPolicy !== undefined ? { AGENT_BROWSER_ACTION_POLICY: actionPolicy } : {}),
-        ...(confirmActions !== undefined ? { AGENT_BROWSER_CONFIRM_ACTIONS: confirmActions } : {}),
-        ...(debug !== undefined ? { AGENT_BROWSER_DEBUG: debug ? "1" : undefined } : {}),
-        ...(noAutoDialog !== undefined ? { AGENT_BROWSER_NO_AUTO_DIALOG: noAutoDialog ? "1" : "0" } : {}),
-        ...(configPath !== undefined ? { AGENT_BROWSER_CONFIG: resolve(cwd, configPath) } : {}),
-        ...(session !== undefined ? { AGENT_BROWSER_SESSION: session } : {}),
-        ...(namespace !== undefined ? { AGENT_BROWSER_NAMESPACE: namespace } : {}),
-    }, () => run({ ...input, toolArgs: args, nativeConfirmActions, chromeStartupArgs, persistentChromeArgs, configuredChromeLaunch }, !rootDefault ? undefined : async (browserRun, launchSignal = signal) => {
-        const daemon = await inspectManagedSessionDaemon({ cwd, signal: launchSignal, sessionName: rootDefault,
-            namespace: scanUpstreamGlobalFlagOccurrences(args, "--namespace").at(-1)?.value ?? namespace, timeoutMs: 5_000 });
-        if (daemon.status === "missing-binary")
-            return {
-                content: [{ type: "text", text: buildMissingBinaryMessage() }],
-                details: { agentBrowserStarted: false, args: input.redactedArgs, sessionName: rootDefault, resultCategory: "failure", failureCategory: "missing-binary" },
-                isError: true,
-            };
-        if (input.kind === "qa" && input.compiledQaPreset.checks.attached && daemon.status !== "active") {
-            return buildValidationFailureResult({ ...input, attemptedKind: "qa", kind: "invalid", status: "invalid", validationError: "qa.attached requires an active attached session. Open the root browser first, or select an existing native session." });
-        }
-        // An active daemon already owns its launch settings. Re-sending defaults can replace an explicitly profiled browser.
-        const bootstrap = daemon.status === "inactive";
-        let restore;
-        if (restoreEligible && daemon.status === "active")
-            restore = daemon.restoreKey ?? undefined;
-        if (restoreEligible && bootstrap)
-            restore = rootDefault;
-        const profile = scanUpstreamGlobalFlagOccurrences(args, "--profile").at(-1)?.value
-            ?? (bootstrap && chromeEngine && restoreEligible && identity.profile === undefined && env.AGENT_BROWSER_PROFILE === undefined ? root?.profile : undefined);
-        const executablePath = scanUpstreamGlobalFlagOccurrences(args, "--executable-path").at(-1)?.value
-            ?? (bootstrap && chromeEngine && identity.executablePath === undefined && env.AGENT_BROWSER_EXECUTABLE_PATH === undefined ? root?.executablePath : undefined);
-        return withAgentBrowserProcessEnvironment({
-            ...(restore !== undefined ? { AGENT_BROWSER_RESTORE: restore } : {}),
-            ...(profile !== undefined ? { AGENT_BROWSER_PROFILE: profile } : {}),
-            ...(executablePath !== undefined ? { AGENT_BROWSER_EXECUTABLE_PATH: executablePath } : {}),
-        }, () => withChromeStartupArgs(bootstrap || configuredChromeLaunch ? chromeStartupArgs : undefined, () => browserRun(bootstrap)));
-    }), [
-        ...(debug !== undefined ? [["--debug", String(debug)]] : []),
-        ...(noAutoDialog !== undefined ? [["--no-auto-dialog", String(noAutoDialog)]] : []),
-    ]); // Native ORs env/config booleans; helpers need CLI false to override true config.
+    }
+    return new NativeSessionCall(input, context, run).run();
 }