@steipete/oracle 0.10.0 → 0.11.0

package/dist/src/browser/controlPlan.js

@@ -0,0 +1,81 @@
+export function describeBrowserControlPlan(config = {}) {
+    const guidance = [];
+    const tabRef = String(config.browserTabRef ?? "").trim();
+    const reusesExistingTab = tabRef.length > 0;
+    if (config.attachRunning) {
+        guidance.push(reusesExistingTab
+            ? `Oracle reuses the matching ChatGPT tab (${tabRef}) and leaves the existing browser process alone.`
+            : "Oracle opens a dedicated tab and leaves the existing browser process alone.");
+        if (config.keepBrowser) {
+            guidance.push("The browser stays open because Oracle did not launch it.");
+        }
+        return {
+            mode: "attach-running",
+            launchesChrome: false,
+            mayFocusWindow: true,
+            summary: reusesExistingTab
+                ? "attach to an already-running local Chrome tab"
+                : "attach to an already-running local Chrome session",
+            guidance,
+        };
+    }
+    if (config.remoteChrome) {
+        guidance.push(reusesExistingTab
+            ? `Oracle reuses the matching ChatGPT tab (${tabRef}) in the configured remote Chrome session.`
+            : "Oracle opens a dedicated tab in the configured remote Chrome session.");
+        guidance.push("Local Chrome launch, cookie copy, and window hiding flags are skipped.");
+        return {
+            mode: "remote-chrome",
+            launchesChrome: false,
+            mayFocusWindow: false,
+            summary: reusesExistingTab
+                ? "reuse an existing remote Chrome tab"
+                : "reuse an existing remote Chrome session",
+            guidance,
+        };
+    }
+    if (config.headless) {
+        guidance.push("Headless mode avoids visible UI but may be blocked by ChatGPT or Cloudflare.");
+        return {
+            mode: "headless",
+            launchesChrome: true,
+            mayFocusWindow: false,
+            summary: "launch headless Chrome",
+            guidance,
+        };
+    }
+    if (config.hideWindow) {
+        guidance.push("Chrome may briefly focus while launching before Oracle hides it.");
+        guidance.push("For the calmest shared-desktop flow, prefer --browser-attach-running or --remote-chrome.");
+        return {
+            mode: "hidden-window",
+            launchesChrome: true,
+            mayFocusWindow: true,
+            summary: "launch Chrome and hide the window after startup",
+            guidance,
+        };
+    }
+    guidance.push(config.manualLogin
+        ? "Manual-login mode may show the persistent Oracle Chrome profile for sign-in or automation."
+        : "A visible automation Chrome window may take focus while Oracle controls ChatGPT.");
+    guidance.push("Use --browser-hide-window, --browser-attach-running, or --remote-chrome to reduce desktop disruption.");
+    if (config.keepBrowser) {
+        guidance.push("Chrome will remain open after the run because --browser-keep-browser is enabled.");
+    }
+    return {
+        mode: "visible-window",
+        launchesChrome: true,
+        mayFocusWindow: true,
+        summary: "launch visible Chrome",
+        guidance,
+    };
+}
+export function formatBrowserControlPlan(plan, label = "browser") {
+    const risk = plan.mayFocusWindow
+        ? "may focus/control the browser UI"
+        : "does not use a visible local browser window";
+    return [
+        `[${label}] Browser control: ${plan.summary}; ${risk}.`,
+        ...plan.guidance.map((entry) => `[${label}] Browser guidance: ${entry}`),
+    ];
+}

package/dist/src/browser/detect.js

@@ -14,7 +14,7 @@ export async function detectChromeBinary() {
     if (launcherDetected) {
         return { path: launcherDetected };
     }
-    const candidates = platformChromeCandidates();
+    const candidates = platformChromeCandidates(process.platform, os.homedir());
     for (const candidate of candidates.absolutePaths) {
         if (await isExecutable(candidate)) {
             return { path: candidate };
@@ -31,9 +31,9 @@ export async function detectChromeCookieDb({ profile, }) {
     if (process.platform === "win32") {
         return null;
     }
-    const roots = platformProfileRoots();
+    const roots = resolveAttachRunningProfileRoots();
     for (const root of roots) {
-        const dir = path.join(root, profileName);
+        const dir = path.join(root.root, profileName);
         const direct = path.join(dir, "Cookies");
         if (await isFile(direct))
             return direct;
@@ -43,8 +43,155 @@ export async function detectChromeCookieDb({ profile, }) {
     }
     return null;
 }
-function platformChromeCandidates() {
-    if (process.platform === "linux") {
+export function resolveAttachRunningProfileRoots(platform = process.platform, homeDir = os.homedir()) {
+    if (platform === "darwin") {
+        return [
+            {
+                family: "chrome",
+                root: path.join(homeDir, "Library", "Application Support", "Google", "Chrome"),
+            },
+            {
+                family: "chromium",
+                root: path.join(homeDir, "Library", "Application Support", "Chromium"),
+            },
+            {
+                family: "edge",
+                root: path.join(homeDir, "Library", "Application Support", "Microsoft Edge"),
+            },
+            {
+                family: "brave",
+                root: path.join(homeDir, "Library", "Application Support", "BraveSoftware", "Brave-Browser"),
+            },
+        ];
+    }
+    if (platform === "linux") {
+        return [
+            { family: "chrome", root: path.join(homeDir, ".config", "google-chrome") },
+            { family: "chromium", root: path.join(homeDir, ".config", "chromium") },
+            { family: "edge", root: path.join(homeDir, ".config", "microsoft-edge") },
+            {
+                family: "brave",
+                root: path.join(homeDir, ".config", "BraveSoftware", "Brave-Browser"),
+            },
+            { family: "chromium", root: path.join(homeDir, "snap", "chromium", "common", "chromium") },
+            { family: "chromium", root: path.join(homeDir, "snap", "chromium", "current", "chromium") },
+        ];
+    }
+    if (platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local");
+        return [
+            {
+                family: "chrome",
+                root: path.join(localAppData, "Google", "Chrome", "User Data"),
+            },
+            {
+                family: "chromium",
+                root: path.join(localAppData, "Chromium", "User Data"),
+            },
+            {
+                family: "edge",
+                root: path.join(localAppData, "Microsoft", "Edge", "User Data"),
+            },
+            {
+                family: "brave",
+                root: path.join(localAppData, "BraveSoftware", "Brave-Browser", "User Data"),
+            },
+        ];
+    }
+    return [];
+}
+export function resolveDevToolsActivePortDiscoveryRoots(platform = process.platform, homeDir = os.homedir()) {
+    if (platform === "darwin") {
+        return [path.join(homeDir, "Library", "Application Support")];
+    }
+    if (platform === "linux") {
+        return [path.join(homeDir, ".config"), path.join(homeDir, "snap")];
+    }
+    if (platform === "win32") {
+        return [process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local")];
+    }
+    return [];
+}
+export function inferAttachRunningBrowserFamily(chromePath) {
+    const normalized = chromePath?.trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    if (normalized.includes("microsoft edge") || normalized.includes("msedge")) {
+        return "edge";
+    }
+    if (normalized.includes("brave")) {
+        return "brave";
+    }
+    if (normalized.includes("chromium")) {
+        return "chromium";
+    }
+    if (normalized.includes("chrome")) {
+        return "chrome";
+    }
+    return null;
+}
+export function parseDevToolsActivePort(raw, options = {}) {
+    const host = formatWebSocketHost(options.host ?? "127.0.0.1");
+    const [rawPort, rawBrowserPath] = raw.split(/\r?\n/u);
+    const port = Number.parseInt(rawPort?.trim() ?? "", 10);
+    if (!Number.isFinite(port) || port <= 0 || port > 65_535) {
+        throw new Error("DevToolsActivePort did not contain a valid port.");
+    }
+    const browserPath = rawBrowserPath?.trim() || "/devtools/browser";
+    const normalizedPath = browserPath.startsWith("/") ? browserPath : `/${browserPath}`;
+    return {
+        port,
+        browserWSEndpoint: `ws://${host}:${port}${normalizedPath}`,
+    };
+}
+export async function readDevToolsActivePortInfo(profileRoot, options = {}) {
+    const candidates = [
+        path.join(profileRoot, "DevToolsActivePort"),
+        path.join(profileRoot, "Default", "DevToolsActivePort"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const raw = await fs.readFile(candidate, "utf8");
+            const parsed = parseDevToolsActivePort(raw, options);
+            return { ...parsed, path: candidate };
+        }
+        catch {
+            // ignore missing/unreadable candidates
+        }
+    }
+    return null;
+}
+export async function discoverDevToolsActivePortCandidates(options = {}) {
+    const { host, platform = process.platform, homeDir = os.homedir(), maxDepth = 6 } = options;
+    const roots = resolveDevToolsActivePortDiscoveryRoots(platform, homeDir);
+    const candidates = [];
+    const seenPaths = new Set();
+    for (const root of roots) {
+        await walkForDevToolsActivePort(root, maxDepth, async (candidatePath, stat) => {
+            if (seenPaths.has(candidatePath)) {
+                return;
+            }
+            seenPaths.add(candidatePath);
+            try {
+                const raw = await fs.readFile(candidatePath, "utf8");
+                const parsed = parseDevToolsActivePort(raw, { host });
+                candidates.push({
+                    ...parsed,
+                    path: candidatePath,
+                    profileRoot: deriveDevToolsProfileRoot(candidatePath),
+                    mtimeMs: Number(stat.mtimeMs),
+                });
+            }
+            catch {
+                // ignore unreadable or malformed DevToolsActivePort files
+            }
+        });
+    }
+    return candidates;
+}
+function platformChromeCandidates(platform = process.platform, homeDir = os.homedir()) {
+    if (platform === "linux") {
         return {
             binaryNames: [
                 "google-chrome",
@@ -73,7 +220,7 @@ function platformChromeCandidates() {
             ],
         };
     }
-    if (process.platform === "darwin") {
+    if (platform === "darwin") {
         return {
             binaryNames: [],
             absolutePaths: [
@@ -84,10 +231,10 @@ function platformChromeCandidates() {
             ],
         };
     }
-    if (process.platform === "win32") {
+    if (platform === "win32") {
         const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
         const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
-        const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local");
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(homeDir, "AppData", "Local");
         return {
             binaryNames: [],
             absolutePaths: [
@@ -101,31 +248,6 @@ function platformChromeCandidates() {
     }
     return { binaryNames: [], absolutePaths: [] };
 }
-function platformProfileRoots() {
-    const home = os.homedir();
-    if (process.platform === "darwin") {
-        return [
-            path.join(home, "Library", "Application Support", "Google", "Chrome"),
-            path.join(home, "Library", "Application Support", "Chromium"),
-            path.join(home, "Library", "Application Support", "Microsoft Edge"),
-            path.join(home, "Library", "Application Support", "BraveSoftware", "Brave-Browser"),
-        ];
-    }
-    if (process.platform === "linux") {
-        return [
-            path.join(home, ".config", "google-chrome"),
-            path.join(home, ".config", "google-chrome-beta"),
-            path.join(home, ".config", "google-chrome-unstable"),
-            path.join(home, ".config", "chromium"),
-            path.join(home, ".config", "microsoft-edge"),
-            path.join(home, ".config", "BraveSoftware", "Brave-Browser"),
-            // Snap Chromium profiles
-            path.join(home, "snap", "chromium", "common", "chromium"),
-            path.join(home, "snap", "chromium", "current", "chromium"),
-        ];
-    }
-    return [];
-}
 async function isExecutable(candidate) {
     try {
         const stat = await fs.stat(candidate);
@@ -162,3 +284,54 @@ async function findOnPath(names) {
     }
     return null;
 }
+function deriveDevToolsProfileRoot(activePortPath) {
+    const parentDir = path.dirname(activePortPath);
+    if (path.basename(parentDir).toLowerCase() === "default") {
+        return path.dirname(parentDir);
+    }
+    return parentDir;
+}
+function formatWebSocketHost(host) {
+    if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
+        return `[${host}]`;
+    }
+    return host;
+}
+async function walkForDevToolsActivePort(root, maxDepth, onFile) {
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(current.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const candidatePath = path.join(current.dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isFile()) {
+                if (entry.name !== "DevToolsActivePort") {
+                    continue;
+                }
+                try {
+                    const stat = await fs.stat(candidatePath);
+                    await onFile(candidatePath, stat);
+                }
+                catch {
+                    // ignore unreadable candidates
+                }
+                continue;
+            }
+            if (entry.isDirectory() && current.depth < maxDepth) {
+                stack.push({ dir: candidatePath, depth: current.depth + 1 });
+            }
+        }
+    }
+}

package/dist/src/browser/domDebug.js

@@ -1,4 +1,7 @@
 import { CONVERSATION_TURN_SELECTOR } from "./constants.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveSessionArtifactsDir } from "./artifacts.js";
 export function buildConversationDebugExpression() {
     return `(() => {
     const CONVERSATION_SELECTOR = ${JSON.stringify(CONVERSATION_TURN_SELECTOR)};
@@ -34,3 +37,49 @@ export async function logDomFailure(Runtime, logger, context) {
         // ignore snapshot failures
     }
 }
+export async function captureBrowserDiagnostics(Runtime, logger, context, options = {}) {
+    if (!options.sessionId) {
+        await logConversationSnapshot(Runtime, logger).catch(() => undefined);
+        return {};
+    }
+    const dir = resolveSessionArtifactsDir(options.sessionId);
+    await fs.mkdir(dir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const baseName = `${context}-${timestamp}`;
+    const domPath = path.join(dir, `${baseName}.dom.json`);
+    const expression = `(() => {
+    const CONVERSATION_SELECTOR = ${JSON.stringify(CONVERSATION_TURN_SELECTOR)};
+    const turns = Array.from(document.querySelectorAll(CONVERSATION_SELECTOR)).slice(-6).map((node) => ({
+      role: node.getAttribute('data-message-author-role') || node.getAttribute('data-turn'),
+      text: (node.innerText || node.textContent || '').slice(0, 2000),
+      testid: node.getAttribute('data-testid'),
+    }));
+    return {
+      url: location.href,
+      title: document.title,
+      turns,
+      bodyText: (document.body?.innerText || '').slice(0, 5000),
+    };
+  })()`;
+    const { result } = await Runtime.evaluate({ expression, returnByValue: true });
+    await fs.writeFile(domPath, `${JSON.stringify(result?.value ?? null, null, 2)}\n`, "utf8");
+    logger(`[browser] Saved DOM diagnostic snapshot to ${domPath}`);
+    let screenshotPath;
+    if (options.Page?.captureScreenshot) {
+        try {
+            const screenshot = await options.Page.captureScreenshot({
+                format: "png",
+                captureBeyondViewport: true,
+            });
+            if (screenshot?.data) {
+                screenshotPath = path.join(dir, `${baseName}.png`);
+                await fs.writeFile(screenshotPath, Buffer.from(screenshot.data, "base64"));
+                logger(`[browser] Saved screenshot diagnostic snapshot to ${screenshotPath}`);
+            }
+        }
+        catch {
+            // Screenshots are best-effort; the DOM snapshot above is the primary diagnostic.
+        }
+    }
+    return { domPath, screenshotPath };
+}