@steipete/oracle 0.10.0 → 0.11.0

package/dist/src/browser/sessionRunner.js

@@ -4,6 +4,7 @@ import { formatFinishLine } from "../oracle/finishLine.js";
 import { runBrowserMode } from "../browserMode.js";
 import { assembleBrowserPrompt } from "./prompt.js";
 import { BrowserAutomationError } from "../oracle/errors.js";
+import { appendArtifacts, saveBrowserTranscriptArtifact, saveDeepResearchReportArtifact, } from "./artifacts.js";
 export async function runBrowserSessionExecution({ runOptions, browserConfig, cwd, log }, deps = {}) {
     const assemblePrompt = deps.assemblePrompt ?? assembleBrowserPrompt;
     const executeBrowser = deps.executeBrowser ?? runBrowserMode;
@@ -35,7 +36,8 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
     const automationLogger = ((message) => {
         if (typeof message !== "string")
             return;
-        const shouldAlwaysPrint = message.startsWith("[browser] ") && /fallback|retry/i.test(message);
+        const shouldAlwaysPrint = message.startsWith("[browser] ") &&
+            /archive|fallback|follow-up|retry|thinking|waiting for chatgpt|browser slot|browser control|browser guidance/i.test(message);
         if (!runOptions.verbose && !shouldAlwaysPrint)
             return;
         log(message);
@@ -63,6 +65,10 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
             log: automationLogger,
             heartbeatIntervalMs: runOptions.heartbeatIntervalMs,
             verbose: runOptions.verbose,
+            sessionId: runOptions.sessionId,
+            generateImagePath: runOptions.generateImage,
+            outputPath: runOptions.outputPath,
+            followUpPrompts: runOptions.browserFollowUps,
             runtimeHintCb: async (runtime) => {
                 await persistRuntimeHint({
                     ...runtime,
@@ -84,6 +90,15 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
         log("");
     }
     const answerText = browserResult.answerMarkdown || browserResult.answerText || "";
+    const savedArtifacts = await ensureSessionArtifacts({
+        sessionId: runOptions.sessionId,
+        prompt: promptArtifacts.composerText,
+        answerMarkdown: answerText,
+        conversationUrl: browserResult.tabUrl,
+        browserConfig,
+        existingArtifacts: browserResult.artifacts,
+        logger: automationLogger,
+    });
     const usage = {
         inputTokens: promptArtifacts.estimatedInputTokens,
         outputTokens: browserResult.answerTokens,
@@ -120,12 +135,49 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
         usage,
         elapsedMs: browserResult.tookMs,
         runtime: {
+            browserTransport: browserResult.browserTransport,
             chromePid: browserResult.chromePid,
             chromePort: browserResult.chromePort,
             chromeHost: browserResult.chromeHost,
+            chromeBrowserWSEndpoint: browserResult.chromeBrowserWSEndpoint,
+            chromeProfileRoot: browserResult.chromeProfileRoot,
             userDataDir: browserResult.userDataDir,
+            chromeTargetId: browserResult.chromeTargetId,
+            tabUrl: browserResult.tabUrl,
+            conversationId: browserResult.conversationId,
             controllerPid: browserResult.controllerPid ?? process.pid,
         },
+        archive: browserResult.archive,
         answerText,
+        artifacts: savedArtifacts,
     };
 }
+export async function ensureSessionArtifacts(params) {
+    if (!params.sessionId || !params.answerMarkdown.trim()) {
+        return params.existingArtifacts;
+    }
+    let artifacts = params.existingArtifacts;
+    const hasReport = artifacts?.some((artifact) => artifact.kind === "deep-research-report");
+    if (params.browserConfig.researchMode === "deep" && !hasReport) {
+        const report = await saveDeepResearchReportArtifact({
+            sessionId: params.sessionId,
+            reportMarkdown: params.answerMarkdown,
+            conversationUrl: params.conversationUrl,
+            logger: params.logger,
+        }).catch(() => null);
+        artifacts = appendArtifacts(artifacts, [report]);
+    }
+    const hasTranscript = artifacts?.some((artifact) => artifact.kind === "transcript");
+    if (!hasTranscript) {
+        const transcript = await saveBrowserTranscriptArtifact({
+            sessionId: params.sessionId,
+            prompt: params.prompt,
+            answerMarkdown: params.answerMarkdown,
+            conversationUrl: params.conversationUrl,
+            artifacts,
+            logger: params.logger,
+        }).catch(() => null);
+        artifacts = appendArtifacts(artifacts, [transcript]);
+    }
+    return artifacts;
+}

package/dist/src/browser/tabLeaseRegistry.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { isProcessAlive } from "./profileState.js";
+import { delay } from "./utils.js";
+export const DEFAULT_MAX_CONCURRENT_CHATGPT_TABS = 3;
+const REGISTRY_FILENAME = "oracle-tab-leases.json";
+const REGISTRY_LOCK_DIRNAME = "oracle-tab-leases.lock";
+const DEFAULT_POLL_MS = 1000;
+const DEFAULT_STALE_MS = 6 * 60 * 60 * 1000;
+const REGISTRY_LOCK_TIMEOUT_MS = 10_000;
+export function normalizeMaxConcurrentTabs(value) {
+    if (value === undefined || value === null) {
+        return DEFAULT_MAX_CONCURRENT_CHATGPT_TABS;
+    }
+    const numeric = typeof value === "string" ? Number.parseInt(value, 10) : Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+        return DEFAULT_MAX_CONCURRENT_CHATGPT_TABS;
+    }
+    return Math.max(1, Math.trunc(numeric));
+}
+export async function acquireBrowserTabLease(profileDir, options, deps = {}) {
+    const maxConcurrentTabs = normalizeMaxConcurrentTabs(options.maxConcurrentTabs);
+    const pollMs = Math.max(50, options.pollMs ?? DEFAULT_POLL_MS);
+    const timeoutMs = Math.max(0, options.timeoutMs ?? 0);
+    const staleMs = Math.max(60_000, options.staleMs ?? DEFAULT_STALE_MS);
+    const now = deps.now ?? Date.now;
+    const pid = deps.pid ?? process.pid;
+    const leaseId = randomUUID();
+    const startedAt = now();
+    let warned = false;
+    let lastHeartbeatAt = 0;
+    for (;;) {
+        const acquired = await withRegistryLock(profileDir, async () => {
+            const registry = await readRegistry(profileDir);
+            const active = pruneStaleLeases(registry.leases, {
+                nowMs: now(),
+                staleMs,
+                isProcessAlive: deps.isProcessAlive ?? isProcessAlive,
+            });
+            if (active.length >= maxConcurrentTabs) {
+                if (active.length !== registry.leases.length) {
+                    await writeRegistry(profileDir, { version: 1, leases: active });
+                }
+                return null;
+            }
+            const timestamp = new Date(now()).toISOString();
+            const lease = {
+                id: leaseId,
+                pid,
+                sessionId: options.sessionId,
+                chromeHost: options.chromeHost,
+                chromePort: options.chromePort,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+            };
+            await writeRegistry(profileDir, { version: 1, leases: [...active, lease] });
+            return lease;
+        });
+        if (acquired) {
+            options.logger?.(`[browser] Acquired ChatGPT browser slot ${leaseId.slice(0, 8)} (${maxConcurrentTabs} max).`);
+            return {
+                id: leaseId,
+                release: async () => releaseBrowserTabLease(profileDir, leaseId, options.logger),
+                update: async (patch) => updateBrowserTabLease(profileDir, leaseId, patch),
+            };
+        }
+        const elapsed = now() - startedAt;
+        if (!warned || now() - lastHeartbeatAt >= 30_000) {
+            options.logger?.(`[browser] Waiting for ChatGPT browser slot (${maxConcurrentTabs} max, ${Math.round(elapsed / 1000)}s elapsed).`);
+            warned = true;
+            lastHeartbeatAt = now();
+        }
+        if (timeoutMs > 0 && elapsed >= timeoutMs) {
+            throw new Error(`Timed out waiting for ChatGPT browser slot after ${Math.round(elapsed / 1000)}s (${maxConcurrentTabs} max).`);
+        }
+        await delay(timeoutMs > 0 ? Math.min(pollMs, timeoutMs - elapsed) : pollMs);
+    }
+}
+export async function updateBrowserTabLease(profileDir, leaseId, patch) {
+    await withRegistryLock(profileDir, async () => {
+        const registry = await readRegistry(profileDir);
+        const leases = registry.leases.map((lease) => lease.id === leaseId
+            ? { ...lease, ...patch, id: lease.id, updatedAt: new Date().toISOString() }
+            : lease);
+        await writeRegistry(profileDir, { version: 1, leases });
+    });
+}
+export async function releaseBrowserTabLease(profileDir, leaseId, logger) {
+    await withRegistryLock(profileDir, async () => {
+        const registry = await readRegistry(profileDir);
+        const leases = registry.leases.filter((lease) => lease.id !== leaseId);
+        await writeRegistry(profileDir, { version: 1, leases });
+    }).catch(() => undefined);
+    logger?.(`[browser] Released ChatGPT browser slot ${leaseId.slice(0, 8)}.`);
+}
+export async function hasOtherActiveBrowserTabLeases(profileDir, leaseId, options = {}) {
+    const now = options.now ?? Date.now;
+    const staleMs = Math.max(60_000, options.staleMs ?? DEFAULT_STALE_MS);
+    return withRegistryLock(profileDir, async () => {
+        const registry = await readRegistry(profileDir);
+        const active = pruneStaleLeases(registry.leases, {
+            nowMs: now(),
+            staleMs,
+            isProcessAlive: options.isProcessAlive ?? isProcessAlive,
+        });
+        if (active.length !== registry.leases.length) {
+            await writeRegistry(profileDir, { version: 1, leases: active });
+        }
+        return active.some((lease) => lease.id !== leaseId);
+    });
+}
+async function withRegistryLock(profileDir, callback) {
+    const lockDir = path.join(profileDir, REGISTRY_LOCK_DIRNAME);
+    const startedAt = Date.now();
+    for (;;) {
+        try {
+            await mkdir(lockDir, { recursive: false });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            if (Date.now() - startedAt > REGISTRY_LOCK_TIMEOUT_MS) {
+                await rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+                continue;
+            }
+            await delay(50);
+        }
+    }
+    try {
+        return await callback();
+    }
+    finally {
+        await rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function readRegistry(profileDir) {
+    try {
+        const raw = await readFile(registryPath(profileDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.leases)) {
+            return { version: 1, leases: [] };
+        }
+        return {
+            version: 1,
+            leases: parsed.leases.filter(isLeaseRecord),
+        };
+    }
+    catch {
+        return { version: 1, leases: [] };
+    }
+}
+async function writeRegistry(profileDir, registry) {
+    await mkdir(profileDir, { recursive: true });
+    await writeFile(registryPath(profileDir), `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+}
+function registryPath(profileDir) {
+    return path.join(profileDir, REGISTRY_FILENAME);
+}
+function pruneStaleLeases(leases, options) {
+    return leases.filter((lease) => {
+        if (!options.isProcessAlive(lease.pid)) {
+            return false;
+        }
+        const updatedAt = Date.parse(lease.updatedAt);
+        if (Number.isFinite(updatedAt) && options.nowMs - updatedAt > options.staleMs) {
+            return false;
+        }
+        return true;
+    });
+}
+function isLeaseRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.pid === "number" &&
+        typeof record.createdAt === "string" &&
+        typeof record.updatedAt === "string");
+}

package/dist/src/cli/bridge/claudeConfig.js

@@ -12,20 +12,24 @@ export async function runBridgeClaudeConfig(options) {
         env: process.env,
     });
     const snippet = formatClaudeMcpConfig({
-        oracleHomeDir: process.env.ORACLE_HOME_DIR ?? path.join(os.homedir(), ".oracle-local"),
-        browserProfileDir: process.env.ORACLE_BROWSER_PROFILE_DIR ??
-            path.join(os.homedir(), ".oracle-local", "browser-profile"),
+        oracleHomeDir: options.oracleHomeDir ??
+            process.env.ORACLE_HOME_DIR ??
+            path.join(os.homedir(), options.localBrowser ? ".oracle" : ".oracle-local"),
+        browserProfileDir: options.browserProfileDir ??
+            process.env.ORACLE_BROWSER_PROFILE_DIR ??
+            path.join(os.homedir(), options.localBrowser ? ".oracle" : ".oracle-local", "browser-profile"),
         remoteHost: resolved.host,
         remoteToken: resolved.token,
         includeToken: Boolean(options.printToken),
+        localBrowser: Boolean(options.localBrowser),
     });
     console.log(snippet);
-    if (!options.printToken) {
-        console.log("");
-        console.log(chalk.dim("Tip: rerun with --print-token to include ORACLE_REMOTE_TOKEN in the snippet."));
+    if (!options.printToken && !options.localBrowser) {
+        console.error("");
+        console.error(chalk.dim("Tip: rerun with --print-token to include ORACLE_REMOTE_TOKEN in the snippet."));
     }
 }
-export function formatClaudeMcpConfig({ oracleHomeDir, browserProfileDir, remoteHost, remoteToken, includeToken, }) {
+export function formatClaudeMcpConfig({ oracleHomeDir, browserProfileDir, remoteHost, remoteToken, includeToken, localBrowser = false, }) {
     const env = {};
     // biome-ignore lint/complexity/useLiteralKeys: env vars are uppercase and include underscores.
     env["ORACLE_ENGINE"] = "browser";
@@ -33,7 +37,7 @@ export function formatClaudeMcpConfig({ oracleHomeDir, browserProfileDir, remote
     env["ORACLE_HOME_DIR"] = oracleHomeDir;
     // biome-ignore lint/complexity/useLiteralKeys: env vars are uppercase and include underscores.
     env["ORACLE_BROWSER_PROFILE_DIR"] = browserProfileDir;
-    if (remoteHost) {
+    if (remoteHost && !localBrowser) {
         // biome-ignore lint/complexity/useLiteralKeys: env vars are uppercase and include underscores.
         env["ORACLE_REMOTE_HOST"] = remoteHost;
         // biome-ignore lint/complexity/useLiteralKeys: env vars are uppercase and include underscores.

package/dist/src/cli/bridge/codexConfig.js

@@ -16,8 +16,8 @@ export async function runBridgeCodexConfig(options) {
     });
     console.log(snippet);
     if (!options.printToken) {
-        console.log("");
-        console.log(chalk.dim("Tip: rerun with --print-token to include ORACLE_REMOTE_TOKEN in the snippet."));
+        console.error("");
+        console.error(chalk.dim("Tip: rerun with --print-token to include ORACLE_REMOTE_TOKEN in the snippet."));
     }
 }
 export function formatCodexMcpSnippet({ remoteHost, remoteToken, includeToken, }) {

package/dist/src/cli/browserConfig.js

@@ -74,6 +74,11 @@ export async function buildBrowserConfig(options) {
     if (options.remoteChrome) {
         remoteChrome = parseRemoteChromeTarget(options.remoteChrome);
     }
+    const attachRunning = options.browserAttachRunning === true;
+    validateAttachRunningOptions(options, {
+        attachRunning,
+        hasInlineCookies: Boolean(inline?.cookies),
+    });
     const rawUrl = options.chatgptUrl ?? options.browserUrl;
     const url = rawUrl ? normalizeChatgptUrl(rawUrl, CHATGPT_URL) : undefined;
     const desiredModel = isChatGptModel
@@ -92,6 +97,7 @@ export async function buildBrowserConfig(options) {
         chromeProfile: options.browserChromeProfile ?? DEFAULT_CHROME_PROFILE,
         chromePath: options.browserChromePath ?? null,
         chromeCookiePath: options.browserCookiePath ?? null,
+        attachRunning,
         url,
         debugPort: selectBrowserPort(options),
         timeoutMs: options.browserTimeout
@@ -112,6 +118,7 @@ export async function buildBrowserConfig(options) {
         profileLockTimeoutMs: options.browserProfileLockTimeout
             ? parseDuration(options.browserProfileLockTimeout, 0)
             : undefined,
+        maxConcurrentTabs: parseMaxConcurrentTabs(options.browserMaxConcurrentTabs),
         autoReattachDelayMs: options.browserAutoReattachDelay
             ? parseDuration(options.browserAutoReattachDelay, 0)
             : undefined,
@@ -139,9 +146,33 @@ export async function buildBrowserConfig(options) {
         // Allow cookie failures by default so runs can continue without Chrome/Keychain secrets.
         allowCookieErrors: options.browserAllowCookieErrors ?? true,
         remoteChrome,
+        browserTabRef: options.browserTab ?? undefined,
         thinkingTime: options.browserThinkingTime,
+        researchMode: options.browserResearch === "deep" ? "deep" : "off",
+        archiveConversations: options.browserArchive,
     };
 }
+function validateAttachRunningOptions(options, { attachRunning, hasInlineCookies, }) {
+    if (!attachRunning) {
+        return;
+    }
+    const conflicts = [
+        options.browserChromeProfile ? "--browser-chrome-profile" : null,
+        options.browserCookiePath ? "--browser-cookie-path" : null,
+        options.browserNoCookieSync ? "--browser-no-cookie-sync" : null,
+        options.browserHideWindow ? "--browser-hide-window" : null,
+        options.browserKeepBrowser ? "--browser-keep-browser" : null,
+        options.browserManualLogin ? "--browser-manual-login" : null,
+        options.browserManualLoginProfileDir ? "--browser-manual-login-profile-dir" : null,
+        hasInlineCookies ? "--browser-inline-cookies/--browser-inline-cookies-file" : null,
+        options.browserPort != null || options.browserDebugPort != null
+            ? "--browser-port/--browser-debug-port"
+            : null,
+    ].filter((value) => Boolean(value));
+    if (conflicts.length > 0) {
+        throw new Error(`--browser-attach-running cannot be combined with ${conflicts.join(", ")} because attach mode reuses an already-running browser instead of launching and configuring its own Chrome instance.`);
+    }
+}
 function selectBrowserPort(options) {
     const candidate = options.browserPort ?? options.browserDebugPort;
     if (candidate === undefined || candidate === null)
@@ -151,6 +182,15 @@ function selectBrowserPort(options) {
     }
     return candidate;
 }
+function parseMaxConcurrentTabs(raw) {
+    if (!raw)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Invalid browser max concurrent tabs: ${raw}. Expected a positive integer.`);
+    }
+    return Math.trunc(value);
+}
 export function mapModelToBrowserLabel(model) {
     const normalized = normalizeChatGptModelForBrowser(model);
     // Iterate ordered array to find first match (most specific first)

package/dist/src/cli/browserDefaults.js

@@ -7,27 +7,36 @@ export function applyBrowserDefaultsFromConfig(options, config, getSource) {
         const source = getSource(key);
         return source === undefined || source === "default";
     };
+    const attachRunningRequested = options.browserAttachRunning === true ||
+        (isUnset("browserAttachRunning") && browser.attachRunning === true);
     const configuredChatgptUrl = browser.chatgptUrl ?? browser.url;
     const cliChatgptSet = options.chatgptUrl !== undefined || options.browserUrl !== undefined;
     if (isUnset("chatgptUrl") && !cliChatgptSet && configuredChatgptUrl !== undefined) {
         options.chatgptUrl = normalizeChatgptUrl(configuredChatgptUrl ?? "", CHATGPT_URL);
     }
-    if (isUnset("browserChromeProfile") && browser.chromeProfile !== undefined) {
+    if (!attachRunningRequested &&
+        isUnset("browserChromeProfile") &&
+        browser.chromeProfile !== undefined) {
         options.browserChromeProfile = browser.chromeProfile ?? undefined;
     }
     if (isUnset("browserChromePath") && browser.chromePath !== undefined) {
         options.browserChromePath = browser.chromePath ?? undefined;
     }
-    if (isUnset("browserCookiePath") && browser.chromeCookiePath !== undefined) {
+    if (!attachRunningRequested &&
+        isUnset("browserCookiePath") &&
+        browser.chromeCookiePath !== undefined) {
         options.browserCookiePath = browser.chromeCookiePath ?? undefined;
     }
+    if (isUnset("browserAttachRunning") && browser.attachRunning !== undefined) {
+        options.browserAttachRunning = browser.attachRunning;
+    }
     if (isUnset("browserUrl") && options.browserUrl === undefined && browser.url !== undefined) {
         options.browserUrl = browser.url;
     }
     if (isUnset("browserTimeout") && typeof browser.timeoutMs === "number") {
         options.browserTimeout = String(browser.timeoutMs);
     }
-    if (isUnset("browserPort") && typeof browser.debugPort === "number") {
+    if (!attachRunningRequested && isUnset("browserPort") && typeof browser.debugPort === "number") {
         options.browserPort = browser.debugPort;
     }
     if (isUnset("browserInputTimeout") && typeof browser.inputTimeoutMs === "number") {
@@ -45,6 +54,9 @@ export function applyBrowserDefaultsFromConfig(options, config, getSource) {
     if (isUnset("browserProfileLockTimeout") && typeof browser.profileLockTimeoutMs === "number") {
         options.browserProfileLockTimeout = String(browser.profileLockTimeoutMs);
     }
+    if (isUnset("browserMaxConcurrentTabs") && typeof browser.maxConcurrentTabs === "number") {
+        options.browserMaxConcurrentTabs = String(browser.maxConcurrentTabs);
+    }
     if (isUnset("browserAutoReattachDelay") && typeof browser.autoReattachDelayMs === "number") {
         options.browserAutoReattachDelay = String(browser.autoReattachDelayMs);
     }
@@ -61,10 +73,12 @@ export function applyBrowserDefaultsFromConfig(options, config, getSource) {
     if (isUnset("browserHeadless") && browser.headless !== undefined) {
         options.browserHeadless = browser.headless;
     }
-    if (isUnset("browserHideWindow") && browser.hideWindow !== undefined) {
+    if (!attachRunningRequested && isUnset("browserHideWindow") && browser.hideWindow !== undefined) {
         options.browserHideWindow = browser.hideWindow;
     }
-    if (isUnset("browserKeepBrowser") && browser.keepBrowser !== undefined) {
+    if (!attachRunningRequested &&
+        isUnset("browserKeepBrowser") &&
+        browser.keepBrowser !== undefined) {
         options.browserKeepBrowser = browser.keepBrowser;
     }
     if (isUnset("browserModelStrategy") && browser.modelStrategy !== undefined) {
@@ -73,10 +87,20 @@ export function applyBrowserDefaultsFromConfig(options, config, getSource) {
     if (isUnset("browserThinkingTime") && browser.thinkingTime !== undefined) {
         options.browserThinkingTime = browser.thinkingTime;
     }
-    if (isUnset("browserManualLogin") && browser.manualLogin !== undefined) {
+    if (isUnset("browserResearch") && browser.researchMode !== undefined) {
+        options.browserResearch = browser.researchMode;
+    }
+    if (isUnset("browserArchive") && browser.archiveConversations !== undefined) {
+        options.browserArchive = browser.archiveConversations;
+    }
+    if (!attachRunningRequested &&
+        isUnset("browserManualLogin") &&
+        browser.manualLogin !== undefined) {
         options.browserManualLogin = browser.manualLogin;
     }
-    if (isUnset("browserManualLoginProfileDir") && browser.manualLoginProfileDir !== undefined) {
+    if (!attachRunningRequested &&
+        isUnset("browserManualLoginProfileDir") &&
+        browser.manualLoginProfileDir !== undefined) {
         options.browserManualLoginProfileDir = browser.manualLoginProfileDir;
     }
 }