@steipete/oracle 0.18.0 → 0.19.0

package/dist/src/browser/chromeLifecycle.js

@@ -1,19 +1,29 @@
-import { rm } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import * as childProcess from "node:child_process";
 import net from "node:net";
+import path from "node:path";
 import CDP from "chrome-remote-interface";
-import { launch, Launcher } from "chrome-launcher";
+import { launch, Launcher, } from "chrome-launcher";
 import { cleanupStaleProfileState } from "./profileState.js";
 import { delay } from "./utils.js";
 import { isWsl, resolveWslChromeLaunchRoute } from "./wslHost.js";
 export async function launchChrome(config, userDataDir, logger) {
     const { connectHost, debugBindAddress, usePatchedLauncher } = resolveWslChromeLaunchRoute();
     const debugPort = config.debugPort ?? parseDebugPortEnv();
+    const usingCopiedProfile = Boolean(config.copyProfileSource);
+    const detachSharedChrome = shouldDetachSharedChrome(config);
+    const launchedProfileDirectory = usingCopiedProfile && config.chromeProfile ? config.chromeProfile : "Default";
+    await prepareChromeWindowStateForHiddenLaunch({
+        config,
+        userDataDir,
+        profileDirectory: launchedProfileDirectory,
+        logger,
+    });
     const chromeFlags = buildChromeFlags(config.headless ?? false, debugBindAddress, config.hideWindow ?? false);
     // copy-profile reuses a copied signed-in profile whose cookies are
     // Keychain-encrypted, so it must launch with the real Keychain (not mocked):
     // strip the keychain-mocking flags from both chrome-launcher's defaults and
     // Oracle's set, and ignore the defaults so they aren't re-added.
-    const usingCopiedProfile = Boolean(config.copyProfileSource);
     if (usingCopiedProfile && config.chromeProfile) {
         chromeFlags.push(`--profile-directory=${config.chromeProfile}`);
     }
@@ -26,38 +36,231 @@ export async function launchChrome(config, userDataDir, logger) {
             host: connectHost ?? "127.0.0.1",
             requestedPort: debugPort ?? undefined,
             ignoreDefaultFlags: launchOptions.ignoreDefaultFlags,
+            detachSharedChrome,
         })
-        : await launch({
+        : await launchWithStableProcessLifecycle({
             chromePath: config.chromePath ?? undefined,
             chromeFlags: launchOptions.chromeFlags,
             userDataDir,
             handleSIGINT: false,
             port: debugPort ?? undefined,
             ignoreDefaultFlags: launchOptions.ignoreDefaultFlags,
-        });
+        }, detachSharedChrome);
     const pidLabel = typeof launcher.pid === "number" ? ` (pid ${launcher.pid})` : "";
     const hostLabel = connectHost ? ` on ${connectHost}` : "";
     logger(`Launched Chrome${pidLabel} on port ${launcher.port}${hostLabel}`);
+    if (detachSharedChrome) {
+        logger("[browser] Browser control: Windows Chrome lifecycle detached=true; windowsHide=true.");
+    }
     return Object.assign(launcher, { host: connectHost ?? "127.0.0.1" });
 }
-export async function positionChromeWindowOffscreen(client, logger) {
+function shouldDetachSharedChrome(config, platform = process.platform) {
+    return platform === "win32" && config.manualLogin === true && !config.copyProfileSource;
+}
+export const shouldDetachSharedChromeForTest = shouldDetachSharedChrome;
+const spawnDetachedChromeOnWindows = ((command, args, options) => {
+    const child = childProcess.spawn(command, args, resolveChromeChildSpawnOptions(options, "win32"));
+    child.unref();
+    return child;
+});
+function resolveChromeChildSpawnOptions(options, platform = process.platform) {
+    return platform === "win32"
+        ? {
+            ...options,
+            detached: true,
+            windowsHide: true,
+        }
+        : options;
+}
+export function resolveChromeChildSpawnOptionsForTest(options, platform) {
+    return resolveChromeChildSpawnOptions(options, platform);
+}
+function chromeLauncherModuleOverrides(detachSharedChrome, platform = process.platform) {
+    return detachSharedChrome && platform === "win32"
+        ? { spawn: spawnDetachedChromeOnWindows }
+        : undefined;
+}
+async function launchWithStableProcessLifecycle(options, detachSharedChrome) {
+    if (!detachSharedChrome) {
+        return launch(options);
+    }
+    const launcher = new Launcher(options, chromeLauncherModuleOverrides(detachSharedChrome));
+    await launcher.launch();
+    return launchedChromeFromLauncher(launcher);
+}
+function launchedChromeFromLauncher(launcher) {
+    return {
+        pid: launcher.pid ?? 0,
+        port: launcher.port ?? 0,
+        process: launcher.chromeProcess,
+        kill: () => launcher.kill(),
+        remoteDebuggingPipes: launcher.remoteDebuggingPipes,
+    };
+}
+export async function positionChromeWindowOffscreen(client, userDataDir, logger) {
     if (process.platform !== "darwin") {
         logger("Window hiding is only supported on macOS");
         return;
     }
+    let savedState = false;
     try {
         const { windowId } = await client.Browser.getWindowForTarget();
+        if (!(await readSavedChromeWindowState(userDataDir))) {
+            const { bounds } = await client.Browser.getWindowBounds({ windowId });
+            await writeSavedChromeWindowState(userDataDir, bounds);
+            savedState = true;
+        }
         await client.Browser.setWindowBounds({
             windowId,
             bounds: { left: -32_000, top: -32_000, windowState: "normal" },
         });
-        logger("Chrome window positioned off-screen");
     }
     catch (error) {
+        if (savedState) {
+            await rm(chromeWindowStatePath(userDataDir), { force: true }).catch(() => undefined);
+        }
         const message = error instanceof Error ? error.message : String(error);
         logger(`Failed to position Chrome window off-screen: ${message}`);
+        return;
+    }
+    logger("Chrome window positioned off-screen");
+}
+export async function positionChromeWindowOnscreen(client, userDataDir, logger) {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    try {
+        const savedState = await readSavedChromeWindowState(userDataDir);
+        if (!savedState) {
+            return;
+        }
+        const { windowId } = await client.Browser.getWindowForTarget();
+        await client.Browser.setWindowBounds({
+            windowId,
+            bounds: restoreWindowBounds(savedState.bounds),
+        });
+        await rm(chromeWindowStatePath(userDataDir), { force: true });
+        logger("Chrome window restored to its pre-hide bounds");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger(`Failed to position Chrome window on-screen: ${message}`);
+    }
+}
+const CHROME_WINDOW_STATE_FILENAME = "oracle-window-state.json";
+const DEFAULT_VISIBLE_WINDOW_BOUNDS = {
+    left: 80,
+    top: 80,
+    width: 1280,
+    height: 720,
+    windowState: "normal",
+};
+function chromeWindowStatePath(userDataDir) {
+    return path.join(userDataDir, CHROME_WINDOW_STATE_FILENAME);
+}
+async function readSavedChromeWindowState(userDataDir) {
+    try {
+        const parsed = JSON.parse(await readFile(chromeWindowStatePath(userDataDir), "utf8"));
+        const bounds = parseChromeWindowBounds(parsed.bounds);
+        if (parsed.version !== 1 || !bounds) {
+            return null;
+        }
+        return { version: 1, bounds };
+    }
+    catch {
+        return null;
     }
 }
+async function writeSavedChromeWindowState(userDataDir, bounds) {
+    await mkdir(userDataDir, { recursive: true });
+    await writeFile(chromeWindowStatePath(userDataDir), `${JSON.stringify({ version: 1, bounds })}\n`, "utf8");
+}
+async function prepareChromeWindowStateForHiddenLaunch({ config, userDataDir, profileDirectory, logger, }) {
+    if (process.platform !== "darwin" ||
+        config.headless ||
+        !config.hideWindow ||
+        (await readSavedChromeWindowState(userDataDir))) {
+        return;
+    }
+    const bounds = (await readPersistedChromeWindowBounds(userDataDir, profileDirectory)) ??
+        DEFAULT_VISIBLE_WINDOW_BOUNDS;
+    await writeSavedChromeWindowState(userDataDir, bounds);
+    logger("Recorded Chrome window placement before hidden launch");
+}
+async function readPersistedChromeWindowBounds(userDataDir, profileDirectory) {
+    const root = path.resolve(userDataDir);
+    const profile = path.resolve(root, profileDirectory);
+    if (path.dirname(profile) !== root) {
+        return null;
+    }
+    try {
+        const preferences = JSON.parse(await readFile(path.join(profile, "Preferences"), "utf8"));
+        return persistedPlacementToBounds(preferences.browser?.window_placement);
+    }
+    catch {
+        return null;
+    }
+}
+function persistedPlacementToBounds(placement) {
+    if (!placement) {
+        return null;
+    }
+    if (placement.maximized === true) {
+        return { windowState: "maximized" };
+    }
+    const left = finiteNumber(placement.left);
+    const top = finiteNumber(placement.top);
+    const right = finiteNumber(placement.right);
+    const bottom = finiteNumber(placement.bottom);
+    if (left === null || top === null || right === null || bottom === null) {
+        return null;
+    }
+    const width = right - left;
+    const height = bottom - top;
+    if (width <= 0 || height <= 0) {
+        return null;
+    }
+    return { left, top, width, height, windowState: "normal" };
+}
+function parseChromeWindowBounds(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const bounds = value;
+    const windowState = bounds.windowState ?? "normal";
+    if (windowState !== "normal") {
+        return ["minimized", "maximized", "fullscreen"].includes(windowState) ? { windowState } : null;
+    }
+    const left = finiteNumber(bounds.left);
+    const top = finiteNumber(bounds.top);
+    const width = finiteNumber(bounds.width);
+    const height = finiteNumber(bounds.height);
+    if (left === null ||
+        top === null ||
+        width === null ||
+        height === null ||
+        width <= 0 ||
+        height <= 0) {
+        return null;
+    }
+    return { left, top, width, height, windowState: "normal" };
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function restoreWindowBounds(bounds) {
+    const windowState = bounds.windowState ?? "normal";
+    if (windowState !== "normal") {
+        return { windowState };
+    }
+    return {
+        left: bounds.left ?? 80,
+        top: bounds.top ?? 80,
+        width: bounds.width,
+        height: bounds.height,
+        windowState: "normal",
+    };
+}
 export function registerTerminationHooks(chrome, userDataDir, keepBrowser, logger, opts) {
     const signals = ["SIGINT", "SIGTERM", "SIGQUIT"];
     let handling;
@@ -68,7 +271,8 @@ export function registerTerminationHooks(chrome, userDataDir, keepBrowser, logge
         handling = true;
         const inFlight = opts?.isInFlight?.() ?? false;
         const forceCleanup = opts?.forceProfileCleanup ?? false;
-        const leaveRunning = (keepBrowser || inFlight) && !forceCleanup;
+        const preserveSharedChrome = opts?.preserveSharedChromeOnSignal ?? false;
+        const leaveRunning = (keepBrowser || inFlight || preserveSharedChrome) && !forceCleanup;
         if (leaveRunning) {
             logger(`Received ${signal}; leaving Chrome running${inFlight ? " (assistant response pending)" : ""}`);
         }
@@ -136,11 +340,12 @@ export async function connectToRemoteChrome(host, port, logger, targetUrl, brows
             approvalWaitMs: options?.approvalWaitMs,
         });
     }
-    if (targetUrl) {
-        const targetConnection = await connectToNewTarget(host, port, targetUrl, logger, {
-            opened: () => `Opened dedicated remote Chrome tab targeting ${targetUrl}`,
-            openFailed: (message) => `Failed to open dedicated remote Chrome tab (${message}); falling back to first target.`,
-            attachFailed: (targetId, message) => `Failed to attach to dedicated remote Chrome tab ${targetId} (${message}); falling back to first target.`,
+    const newTargetUrl = targetUrl || (options?.fallbackToDefault === false ? "about:blank" : undefined);
+    if (newTargetUrl) {
+        const targetConnection = await connectToNewTarget(host, port, newTargetUrl, logger, {
+            opened: () => `Opened dedicated remote Chrome tab targeting ${newTargetUrl}`,
+            openFailed: (message) => `Failed to open dedicated remote Chrome tab (${message}); ${options?.fallbackToDefault === false ? "refusing to reuse an unrelated tab" : "falling back to first target"}.`,
+            attachFailed: (targetId, message) => `Failed to attach to dedicated remote Chrome tab ${targetId} (${message}); ${options?.fallbackToDefault === false ? "refusing to reuse an unrelated tab" : "falling back to first target"}.`,
             closeFailed: (targetId, message) => `Failed to close unused remote Chrome tab ${targetId}: ${message}`,
         });
         if (targetConnection) {
@@ -153,6 +358,9 @@ export async function connectToRemoteChrome(host, port, logger, targetUrl, brows
                 },
             };
         }
+        if (options?.fallbackToDefault === false) {
+            throw new Error("Unable to create a dedicated remote Chrome tab; refusing to reuse an unrelated conversation.");
+        }
     }
     const fallbackClient = await CDP({ host, port });
     logger(`Connected to remote Chrome DevTools protocol at ${host}:${port}`);
@@ -183,7 +391,7 @@ export async function listRemoteChromeTargets(options) {
         const targets = await CDP.List({ host: options.host, port: options.port });
         return targets;
     }
-    const browser = await CDP({ target: options.browserWSEndpoint, local: true });
+    const browser = await connectToBrowserWebSocket(options.host, options.port, options.browserWSEndpoint, options.logger ?? (() => { }), options.approvalWaitMs);
     try {
         const result = await browser.Target.getTargets();
         return (result.targetInfos ?? []).map((target) => ({
@@ -241,33 +449,54 @@ async function connectToBrowserWebSocket(host, port, browserWSEndpoint, logger,
     if (!approvalWaitMs || approvalWaitMs <= 0) {
         return (await CDP({ target: browserWSEndpoint, local: true }));
     }
-    logger(`Waiting for Chrome remote debugging approval for ${host}:${port}...`);
-    const deadline = Date.now() + approvalWaitMs;
+    logger(`[browser] Waiting for Chrome remote debugging approval for ${host}:${port}...`);
+    const startedAt = Date.now();
+    const deadline = startedAt + approvalWaitMs;
+    const progress = setInterval(() => {
+        logger(`[browser] Still waiting for Chrome remote debugging approval for ${host}:${port} (${formatApprovalWait(Date.now() - startedAt)} elapsed). Click Allow in an open Chrome window.`);
+    }, 15_000);
     let lastApprovalError;
-    while (Date.now() < deadline) {
-        const remainingMs = Math.max(1, deadline - Date.now());
-        try {
-            return await Promise.race([
-                CDP({ target: browserWSEndpoint, local: true }),
-                new Promise((_, reject) => {
-                    setTimeout(() => {
-                        reject(new Error("__oracle_remote_debugging_approval_timeout__"));
-                    }, remainingMs);
-                }),
-            ]);
-        }
-        catch (error) {
-            if (error instanceof Error &&
-                error.message === "__oracle_remote_debugging_approval_timeout__") {
-                break;
+    try {
+        while (Date.now() < deadline) {
+            const remainingMs = Math.max(1, deadline - Date.now());
+            let timeout;
+            let expired = false;
+            try {
+                const connecting = CDP({ target: browserWSEndpoint, local: true }).then(async (client) => {
+                    // An approval arriving after our deadline must not leak a connection.
+                    if (expired)
+                        await client.close().catch(() => undefined);
+                    return client;
+                });
+                return await Promise.race([
+                    connecting,
+                    new Promise((_, reject) => {
+                        timeout = setTimeout(() => {
+                            expired = true;
+                            reject(new Error("__oracle_remote_debugging_approval_timeout__"));
+                        }, remainingMs);
+                    }),
+                ]);
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message === "__oracle_remote_debugging_approval_timeout__") {
+                    break;
+                }
+                if (!isRemoteDebuggingApprovalError(error)) {
+                    throw error;
+                }
+                lastApprovalError = error;
             }
-            if (!isRemoteDebuggingApprovalError(error)) {
-                throw error;
+            finally {
+                clearTimeout(timeout);
             }
-            lastApprovalError = error;
             await delay(Math.min(500, Math.max(0, deadline - Date.now())));
         }
     }
+    finally {
+        clearInterval(progress);
+    }
     const suffix = lastApprovalError instanceof Error && lastApprovalError.message
         ? ` Last Chrome response: ${lastApprovalError.message}`
         : "";
@@ -598,7 +827,7 @@ function parseDebugPortEnv() {
     }
     return value;
 }
-async function launchWithCustomHost({ chromeFlags, chromePath, userDataDir, host, requestedPort, ignoreDefaultFlags, }) {
+async function launchWithCustomHost({ chromeFlags, chromePath, userDataDir, host, requestedPort, ignoreDefaultFlags, detachSharedChrome, }) {
     const launcher = new Launcher({
         chromePath: chromePath ?? undefined,
         chromeFlags,
@@ -606,7 +835,7 @@ async function launchWithCustomHost({ chromeFlags, chromePath, userDataDir, host
         handleSIGINT: false,
         port: requestedPort ?? undefined,
         ignoreDefaultFlags,
-    });
+    }, chromeLauncherModuleOverrides(detachSharedChrome));
     if (host) {
         const patched = launcher;
         patched.isDebuggerReady = function patchedIsDebuggerReady() {
@@ -634,13 +863,8 @@ async function launchWithCustomHost({ chromeFlags, chromePath, userDataDir, host
         };
     }
     await launcher.launch();
-    const kill = async () => launcher.kill();
     return {
-        pid: launcher.pid ?? undefined,
-        port: launcher.port ?? 0,
-        process: launcher.chromeProcess,
-        kill,
+        ...launchedChromeFromLauncher(launcher),
         host: host ?? undefined,
-        remoteDebuggingPipes: launcher.remoteDebuggingPipes,
     };
 }

package/dist/src/browser/config.js

@@ -2,6 +2,7 @@ import { CHATGPT_URL, DEEP_RESEARCH_DEFAULT_TIMEOUT_MS, DEFAULT_MODEL_STRATEGY,
 import { normalizeBrowserModelStrategy } from "./modelStrategy.js";
 import { DEFAULT_MAX_CONCURRENT_CHATGPT_TABS, normalizeMaxConcurrentTabs, } from "./tabLeaseRegistry.js";
 import { normalizeChatgptUrl } from "./utils.js";
+import { parseDuration } from "../duration.js";
 import os from "node:os";
 import path from "node:path";
 export const DEFAULT_CHATGPT_COOKIE_NAMES = [
@@ -26,6 +27,7 @@ export const DEFAULT_BROWSER_CONFIG = {
     timeoutMs: 1_200_000,
     debugPort: null,
     inputTimeoutMs: 60_000,
+    approvalWaitMs: 20_000,
     attachmentTimeoutMs: 45_000,
     assistantRecheckDelayMs: 0,
     assistantRecheckTimeoutMs: 120_000,
@@ -82,6 +84,7 @@ export function resolveBrowserConfig(config) {
         timeoutMs: config?.timeoutMs ?? defaultTimeoutMs,
         debugPort: config?.debugPort ?? debugPortEnv ?? DEFAULT_BROWSER_CONFIG.debugPort,
         inputTimeoutMs: config?.inputTimeoutMs ?? DEFAULT_BROWSER_CONFIG.inputTimeoutMs,
+        approvalWaitMs: resolveBrowserApprovalWait(config?.approvalWaitMs),
         attachmentTimeoutMs: config?.attachmentTimeoutMs ?? DEFAULT_BROWSER_CONFIG.attachmentTimeoutMs,
         assistantRecheckDelayMs: config?.assistantRecheckDelayMs ?? DEFAULT_BROWSER_CONFIG.assistantRecheckDelayMs,
         assistantRecheckTimeoutMs: config?.assistantRecheckTimeoutMs ?? DEFAULT_BROWSER_CONFIG.assistantRecheckTimeoutMs,
@@ -154,3 +157,13 @@ function resolveManualLoginProfileDir(...candidates) {
     }
     return path.join(os.homedir(), ".oracle", "browser-profile");
 }
+export function resolveBrowserApprovalWait(value) {
+    const raw = value ?? process.env.ORACLE_BROWSER_APPROVAL_WAIT?.trim();
+    if (raw === undefined || raw === "")
+        return DEFAULT_BROWSER_CONFIG.approvalWaitMs;
+    const parsed = typeof raw === "number" ? raw : parseDuration(raw, Number.NaN);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > 2_147_483_647) {
+        throw new Error("Invalid browser approval wait: use a positive duration up to 2147483647ms (for example --browser-approval-wait 5m, browser.approvalWaitMs: 300000, or ORACLE_BROWSER_APPROVAL_WAIT=5m).");
+    }
+    return parsed;
+}

package/dist/src/browser/detect.js

@@ -291,7 +291,7 @@ function deriveDevToolsProfileRoot(activePortPath) {
     }
     return parentDir;
 }
-function formatWebSocketHost(host) {
+export function formatWebSocketHost(host) {
     if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
         return `[${host}]`;
     }