@steipete/oracle 0.13.0 → 0.14.0

package/dist/src/cli/runOptions.js

@@ -28,16 +28,11 @@ export function resolveRunOptionsFromConfig({ prompt, files = [], model, models,
     const isCodex = apiModel.startsWith("gpt-5.1-codex");
     const isClaude = apiModel.startsWith("claude");
     const isGrok = apiModel.startsWith("grok");
-    const isGeminiApiOnly = apiModel === "gemini-3.1-pro";
     const engineWasBrowser = resolvedEngine === "browser";
     const allModels = normalizedRequestedModels.length > 0
         ? Array.from(new Set(normalizedRequestedModels.map((entry) => resolveApiModel(entry))))
         : [apiModel];
     const browserCompatibilityModels = normalizedRequestedModels.length > 0 ? allModels : [browserModel];
-    const includesGeminiApiOnly = allModels.some((m) => m === "gemini-3.1-pro");
-    if (browserEngineRequested && includesGeminiApiOnly) {
-        throw new PromptValidationError("gemini-3.1-pro is API-only today. Use --engine api or switch to gemini-3-pro for Gemini web.", { engine: "browser", models: allModels });
-    }
     const isBrowserCompatible = (m) => m.startsWith("gpt-") || m.startsWith("gemini");
     const hasNonBrowserCompatibleTarget = browserEngineRequested && browserCompatibilityModels.some((m) => !isBrowserCompatible(m));
     if (hasNonBrowserCompatibleTarget) {
@@ -47,13 +42,8 @@ export function resolveRunOptionsFromConfig({ prompt, files = [], model, models,
     const azureAutoApi = Boolean(azure?.endpoint) &&
         !browserEngineRequested &&
         allModels.some(isAzureOpenAICandidateModel);
-    const engineCoercedToApi = engineWasBrowser && (isCodex || isClaude || isGrok || isGeminiApiOnly || azureAutoApi);
-    const fixedEngine = isCodex ||
-        isClaude ||
-        isGrok ||
-        isGeminiApiOnly ||
-        azureAutoApi ||
-        normalizedRequestedModels.length > 0
+    const engineCoercedToApi = engineWasBrowser && (isCodex || isClaude || isGrok || azureAutoApi);
+    const fixedEngine = isCodex || isClaude || isGrok || azureAutoApi || normalizedRequestedModels.length > 0
         ? "api"
         : resolvedEngine;
     // Browser runs use ChatGPT picker labels/aliases; API runs must keep API model ids intact.

package/dist/src/cli/sessionCommand.js

@@ -109,16 +109,20 @@ export async function handleSessionCommand(sessionId, command, deps = defaultDep
             process.exitCode = 1;
             return;
         }
+        // Commander sets `recover: false` when --no-recover is passed; default is `true`.
+        const recoverIfMissing = sessionOptions.recover !== false;
         if (harvestRequested) {
             await deps.harvestSessionBrowserOutput(sessionId, {
                 writeOutputPath,
                 browserTabRef,
+                recoverIfMissing,
             });
             return;
         }
         await deps.liveTailSessionBrowserOutput(sessionId, {
             writeOutputPath,
             browserTabRef,
+            recoverIfMissing,
         });
         return;
     }

package/dist/src/cli/sessionDisplay.js

@@ -628,6 +628,14 @@ function matchesModel(entry, filter) {
         (entry.model ? [entry.model.toLowerCase()] : []);
     return models.includes(normalized);
 }
+function formatLineageParentLabel(lineage) {
+    if (!lineage?.parentSessionId) {
+        return undefined;
+    }
+    return lineage.parentResponseId
+        ? `${lineage.parentSessionId} (${abbreviateResponseId(lineage.parentResponseId)})`
+        : lineage.parentSessionId;
+}
 function buildStatusTreeRows(entries, responseOwners) {
     const entryById = new Map(entries.map((entry) => [entry.id, entry]));
     const orderIndex = new Map(entries.map((entry, index) => [entry.id, index]));
@@ -668,7 +676,7 @@ function buildStatusTreeRows(entries, responseOwners) {
         visited.add(entry.id);
         const lineage = lineageById.get(entry.id);
         const hiddenParent = lineage?.parentSessionId && !entryById.has(lineage.parentSessionId)
-            ? `${lineage.parentSessionId} (${abbreviateResponseId(lineage.parentResponseId)})`
+            ? formatLineageParentLabel(lineage)
             : undefined;
         const children = childMap.get(entry.id) ?? [];
         rows.push({ entry, displaySlug: entry.id, detachedParentLabel: hiddenParent });
@@ -694,13 +702,19 @@ async function buildSessionChainLine(metadata) {
         return `root -> ${metadata.id}`;
     }
     if (lineageWithoutLookup.parentSessionId) {
-        return `${lineageWithoutLookup.parentSessionId} (${abbreviateResponseId(lineageWithoutLookup.parentResponseId)}) -> ${metadata.id}`;
+        return `${formatLineageParentLabel(lineageWithoutLookup)} -> ${metadata.id}`;
+    }
+    if (!lineageWithoutLookup.parentResponseId) {
+        return `root -> ${metadata.id}`;
     }
     const sessions = await sessionStore.listSessions().catch(() => []);
     const responseOwners = buildResponseOwnerIndex(sessions);
     const lineage = resolveSessionLineage(metadata, responseOwners) ?? lineageWithoutLookup;
     if (lineage.parentSessionId) {
-        return `${lineage.parentSessionId} (${abbreviateResponseId(lineage.parentResponseId)}) -> ${metadata.id}`;
+        return `${formatLineageParentLabel(lineage)} -> ${metadata.id}`;
+    }
+    if (!lineage.parentResponseId) {
+        return `root -> ${metadata.id}`;
     }
     return `${abbreviateResponseId(lineage.parentResponseId)} -> ${metadata.id}`;
 }

package/dist/src/cli/sessionLineage.js

@@ -39,17 +39,20 @@ export function buildResponseOwnerIndex(sessions) {
 }
 export function resolveSessionLineage(meta, responseOwners) {
     const previous = meta.options?.previousResponseId?.trim();
-    if (!previous) {
+    let parentSessionId = meta.options?.followupSessionId?.trim();
+    if (!previous && !parentSessionId) {
         return null;
     }
-    let parentSessionId = meta.options?.followupSessionId?.trim();
-    if (!parentSessionId && responseOwners) {
+    if (!parentSessionId && previous && responseOwners) {
         parentSessionId = responseOwners.get(previous);
     }
     if (parentSessionId === meta.id) {
         parentSessionId = undefined;
     }
-    return { parentResponseId: previous, parentSessionId };
+    return {
+        parentResponseId: previous || undefined,
+        parentSessionId,
+    };
 }
 export function abbreviateResponseId(responseId, max = 18) {
     if (responseId.length <= max) {

package/dist/src/cli/sessionRunner.js

@@ -24,6 +24,7 @@ import { resumeBrowserSession } from "../browser/reattach.js";
 import { hasRecoverableChatGptConversation } from "../browser/reattachability.js";
 import { estimateTokenCount } from "../browser/utils.js";
 import { formatElapsed } from "../oracle/format.js";
+import { formatBrowserReattachGuidance } from "./reattachGuidance.js";
 const isTty = process.stdout.isTTY;
 const dim = (text) => (isTty ? kleur.dim(text) : text);
 export async function performSessionRun({ sessionMeta, runOptions, mode, browserConfig, cwd, log, write, version, notifications, browserDeps, muteStdout = false, }) {
@@ -388,6 +389,16 @@ export async function performSessionRun({ sessionMeta, runOptions, mode, browser
             userError.details?.stage === "assistant-timeout";
         const cloudflareChallenge = userError?.category === "browser-automation" &&
             userError.details?.stage === "cloudflare-challenge";
+        let reattachGuidanceLogged = false;
+        const logBrowserReattachGuidance = (runtime) => {
+            if (reattachGuidanceLogged || mode !== "browser")
+                return;
+            if (!hasRecoverableChatGptConversation(runtime) && runtime?.promptSubmitted !== true) {
+                return;
+            }
+            reattachGuidanceLogged = true;
+            log(formatBrowserReattachGuidance(sessionMeta.id));
+        };
         if (connectionLost && mode === "browser") {
             const runtime = userError.details
                 ?.runtime;
@@ -442,6 +453,7 @@ export async function performSessionRun({ sessionMeta, runOptions, mode, browser
                 },
                 response: { status: "running", incompleteReason: "chrome-disconnected" },
             });
+            logBrowserReattachGuidance(recoverableRuntime);
             return;
         }
         if (assistantTimeout && mode === "browser") {
@@ -492,7 +504,7 @@ export async function performSessionRun({ sessionMeta, runOptions, mode, browser
                     return;
                 }
             }
-            log(dim(`Reattach later with: oracle session ${sessionMeta.id}`));
+            logBrowserReattachGuidance(runtime ?? sessionMeta.browser?.runtime);
             return;
         }
         if (cloudflareChallenge && mode === "browser") {
@@ -518,6 +530,9 @@ export async function performSessionRun({ sessionMeta, runOptions, mode, browser
         const browserRuntime = mode === "browser"
             ? userError?.details?.runtime
             : undefined;
+        if (!cloudflareChallenge) {
+            logBrowserReattachGuidance(browserRuntime ?? sessionMeta.browser?.runtime);
+        }
         await sessionStore.updateSession(sessionMeta.id, {
             status: "error",
             completedAt: new Date().toISOString(),

package/dist/src/gemini-web/client.js

@@ -1,13 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { buildGeminiWebModelHeader, FALLBACK_GEMINI_WEB_MODEL, } from "./models.js";
 const USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
 const MODEL_HEADER_NAME = "x-goog-ext-525001261-jspb";
-const MODEL_HEADERS = {
-    "gemini-3-pro": '[1,null,null,null,"9d8ca3786ebdfbea",null,null,0,[4]]',
-    "gemini-3-pro-deep-think": '[1,null,null,null,"e6fa609c3fa255c0",null,null,0,[4],null,null,3]',
-    "gemini-2.5-pro": '[1,null,null,null,"4af6c7f5da75d65d",null,null,0,[4]]',
-    "gemini-2.5-flash": '[1,null,null,null,"9ec249fc9ad08861",null,null,0,[4]]',
-};
 const GEMINI_APP_URL = "https://gemini.google.com/app";
 const GEMINI_STREAM_GENERATE_URL = "https://gemini.google.com/_/BardChatUi/data/assistant.lamda.BardFrontendService/StreamGenerate";
 const GEMINI_UPLOAD_URL = "https://content-push.googleapis.com/upload";
@@ -276,7 +271,7 @@ export async function runGeminiWebOnce(input) {
             "x-same-domain": "1",
             "user-agent": USER_AGENT,
             cookie: cookieHeader,
-            [MODEL_HEADER_NAME]: MODEL_HEADERS[input.model],
+            [MODEL_HEADER_NAME]: buildGeminiWebModelHeader(input.model),
         },
         body: params.toString(),
     });
@@ -324,9 +319,9 @@ export async function runGeminiWebOnce(input) {
 }
 export async function runGeminiWebWithFallback(input) {
     const attempt = await runGeminiWebOnce(input);
-    if (isGeminiModelUnavailable(attempt.errorCode) && input.model !== "gemini-2.5-flash") {
-        const fallback = await runGeminiWebOnce({ ...input, model: "gemini-2.5-flash" });
-        return { ...fallback, effectiveModel: "gemini-2.5-flash" };
+    if (isGeminiModelUnavailable(attempt.errorCode) && input.model !== FALLBACK_GEMINI_WEB_MODEL) {
+        const fallback = await runGeminiWebOnce({ ...input, model: FALLBACK_GEMINI_WEB_MODEL });
+        return { ...fallback, effectiveModel: FALLBACK_GEMINI_WEB_MODEL };
     }
     return { ...attempt, effectiveModel: input.model };
 }

package/dist/src/gemini-web/executor.js

@@ -4,6 +4,7 @@ import { runProviderDomFlow } from "../browser/providerDomFlow.js";
 import { delay } from "../browser/utils.js";
 import { runGeminiWebWithFallback, saveFirstGeminiImageFromOutput } from "./client.js";
 import { geminiDeepThinkDomProvider } from "../browser/providers/index.js";
+import { resolveGeminiWebModel } from "./models.js";
 import { openGeminiBrowserSession } from "./browserSessionManager.js";
 import { selectGeminiExecutionMode } from "./executionMode.js";
 const GEMINI_COOKIE_NAMES = [
@@ -38,30 +39,6 @@ function resolveInvocationPath(value) {
         return undefined;
     return path.isAbsolute(trimmed) ? trimmed : path.resolve(process.cwd(), trimmed);
 }
-function resolveGeminiWebModel(desiredModel, log) {
-    const desired = typeof desiredModel === "string" ? desiredModel.trim() : "";
-    if (!desired)
-        return "gemini-3-pro";
-    const normalized = desired.toLowerCase().replace(/[_\s]+/g, "-");
-    switch (normalized) {
-        case "gemini-3-pro":
-        case "gemini-3.0-pro":
-            return "gemini-3-pro";
-        case "gemini-3-deep-think":
-        case "gemini-3-pro-deep-think":
-        case "gemini-3-pro-deepthink":
-            return "gemini-3-pro-deep-think";
-        case "gemini-2.5-pro":
-            return "gemini-2.5-pro";
-        case "gemini-2.5-flash":
-            return "gemini-2.5-flash";
-        default:
-            if (normalized.startsWith("gemini-") || normalized.includes("gemini")) {
-                log?.(`[gemini-web] Unsupported Gemini web model "${desired}". Falling back to gemini-3-pro.`);
-            }
-            return "gemini-3-pro";
-    }
-}
 function resolveCookieDomain(cookie) {
     const rawDomain = cookie.domain?.trim();
     if (rawDomain) {

package/dist/src/gemini-web/models.js

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+export const DEFAULT_GEMINI_WEB_MODEL = "gemini-3.1-pro";
+export const FALLBACK_GEMINI_WEB_MODEL = "gemini-3.1-flash-lite";
+const MODEL_SPECS = {
+    "gemini-3.1-flash-lite": {
+        hash: "1d44b34bcaa1c04d",
+        modelCode: 6,
+        thinkingCode: 1,
+    },
+    "gemini-3.5-flash": {
+        hash: "56fdd199312815e2",
+        modelCode: 1,
+        thinkingCode: 1,
+    },
+    "gemini-3.1-pro": {
+        hash: "797f3d0293f288ad",
+        modelCode: 3,
+        thinkingCode: 1,
+    },
+    "gemini-3-pro-deep-think": {
+        hash: "797f3d0293f288ad",
+        modelCode: 3,
+        thinkingCode: 3,
+    },
+};
+let clientId;
+function getGeminiWebClientId() {
+    clientId ??= randomUUID().toUpperCase();
+    return clientId;
+}
+export function buildGeminiWebModelHeader(model, webClientId = getGeminiWebClientId()) {
+    const spec = MODEL_SPECS[model];
+    return JSON.stringify([
+        1,
+        null,
+        null,
+        null,
+        spec.hash,
+        null,
+        null,
+        1,
+        [4, 5, 6, 8],
+        null,
+        null,
+        3,
+        null,
+        null,
+        spec.modelCode,
+        spec.thinkingCode,
+        webClientId,
+    ]);
+}
+export function resolveGeminiWebModel(desiredModel, log) {
+    const desired = typeof desiredModel === "string" ? desiredModel.trim() : "";
+    if (!desired)
+        return DEFAULT_GEMINI_WEB_MODEL;
+    const normalized = desired.toLowerCase().replace(/[_\s]+/g, "-");
+    switch (normalized) {
+        case "gemini-3.1-pro":
+        case "gemini-3-pro":
+        case "gemini-3.0-pro":
+            return "gemini-3.1-pro";
+        case "gemini-3.5-flash":
+            return "gemini-3.5-flash";
+        case "gemini-3.1-flash-lite":
+        case "gemini-3.1-flashlite":
+            return "gemini-3.1-flash-lite";
+        case "gemini-3-deep-think":
+        case "gemini-3-pro-deep-think":
+        case "gemini-3-pro-deepthink":
+        case "gemini-3.1-pro-deep-think":
+            return "gemini-3-pro-deep-think";
+        case "gemini-2.5-pro":
+            return "gemini-3.1-pro";
+        case "gemini-2.5-flash":
+            return "gemini-3.1-flash-lite";
+        default:
+            if (normalized.startsWith("gemini-") || normalized.includes("gemini")) {
+                log?.(`[gemini-web] Unsupported Gemini web model "${desired}". Falling back to ${DEFAULT_GEMINI_WEB_MODEL}.`);
+            }
+            return DEFAULT_GEMINI_WEB_MODEL;
+    }
+}

package/dist/src/mcp/server.js

@@ -5,6 +5,7 @@ import { pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { getCliVersion } from "../version.js";
+import { registerChatGptImageTool } from "./tools/chatgptImage.js";
 import { registerConsultTool } from "./tools/consult.js";
 import { registerProjectSourcesTool } from "./tools/projectSources.js";
 import { registerSessionsTool } from "./tools/sessions.js";
@@ -19,6 +20,7 @@ export async function startMcpServer() {
         },
     });
     registerConsultTool(server);
+    registerChatGptImageTool(server);
     registerProjectSourcesTool(server);
     registerSessionsTool(server);
     registerSessionResources(server);

package/dist/src/mcp/tools/chatgptImage.js

@@ -0,0 +1,127 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { getOracleHomeDir } from "../../oracleHome.js";
+import { consultOutputShape, runConsultTool } from "./consult.js";
+const chatGptImageInputShape = {
+    prompt: z.string().min(1, "Prompt is required.").describe("Image generation prompt."),
+    files: z
+        .array(z.string())
+        .default([])
+        .describe("Optional reference image/file paths or globs to upload to ChatGPT."),
+    outputPath: z
+        .string()
+        .optional()
+        .describe("Where to save the first generated image. Defaults to a unique file under ORACLE_HOME_DIR/generated/."),
+    aspectRatio: z
+        .string()
+        .optional()
+        .describe('Optional requested image aspect ratio, e.g. "1:1", "9:16", or "16:9".'),
+    model: z
+        .string()
+        .refine((value) => !/^(claude|gemini|grok)(?:[-\s]|$)/i.test(value.trim()), {
+        message: "chatgpt_image requires a ChatGPT/GPT model.",
+    })
+        .optional()
+        .describe("Optional ChatGPT/browser model label or alias. Defaults follow Oracle config."),
+    browserModelLabel: z.string().optional().describe("Explicit ChatGPT UI model label to select."),
+    browserAttachments: z
+        .enum(["auto", "never", "always"])
+        .optional()
+        .describe('How to deliver files. Defaults to "always" when files are present so reference images are uploaded.'),
+    browserThinkingTime: z
+        .enum(["light", "standard", "extended", "heavy"])
+        .optional()
+        .describe("Set ChatGPT thinking time when supported by the chosen model."),
+    browserModelStrategy: z
+        .enum(["select", "current", "ignore"])
+        .optional()
+        .describe("Model picker strategy. Mirrors the consult tool and CLI browser flag."),
+    browserArchive: z
+        .enum(["auto", "always", "never"])
+        .optional()
+        .describe("Archive completed ChatGPT conversations after local artifacts are saved."),
+    browserKeepBrowser: z
+        .boolean()
+        .optional()
+        .describe("Keep Chrome running after completion for debugging."),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("Preview the resolved image run without touching the browser."),
+    slug: z.string().optional().describe("Optional human-friendly session id."),
+};
+const chatGptImageOutputShape = {
+    // Mirror the consult output contract so structuredContent stays consistent
+    // (images/artifacts/resolved are typed by the shared consult shapes), plus the
+    // image-specific echo of the requested path.
+    ...consultOutputShape,
+    requestedOutputPath: z.string(),
+};
+const chatGptImageInputSchema = z.object(chatGptImageInputShape).strict();
+function resolveDefaultImageOutputPath() {
+    // Include a random token so concurrent agent calls in the same millisecond do
+    // not resolve to the same default path and overwrite each other.
+    const unique = `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+    return path.join(getOracleHomeDir(), "generated", `chatgpt-image-${unique}.png`);
+}
+function appendAspectRatio(prompt, aspectRatio) {
+    const requestedAspectRatio = aspectRatio?.trim();
+    if (!requestedAspectRatio) {
+        return prompt.trim();
+    }
+    return `${prompt.trim()}\n\nCreate the image with aspect ratio ${requestedAspectRatio}.`;
+}
+export function buildChatGptImageConsultInput(input) {
+    const files = input.files ?? [];
+    const outputPath = input.outputPath?.trim() || resolveDefaultImageOutputPath();
+    const browserAttachments = input.browserAttachments ?? (files.length > 0 ? "always" : undefined);
+    return {
+        prompt: appendAspectRatio(input.prompt, input.aspectRatio),
+        files,
+        model: input.model,
+        engine: "browser",
+        browserModelLabel: input.browserModelLabel,
+        browserAttachments,
+        browserThinkingTime: input.browserThinkingTime,
+        browserModelStrategy: input.browserModelStrategy,
+        browserArchive: input.browserArchive,
+        browserKeepBrowser: input.browserKeepBrowser,
+        generateImage: outputPath,
+        dryRun: input.dryRun,
+        slug: input.slug,
+    };
+}
+export function registerChatGptImageTool(server) {
+    server.registerTool("chatgpt_image", {
+        title: "Generate an image with ChatGPT",
+        description: "Agent-friendly wrapper for ChatGPT browser image generation. It selects browser mode, enables the image-aware wait/download path, uploads reference files when provided, and returns saved image paths in structuredContent.images.",
+        inputSchema: chatGptImageInputShape,
+        outputSchema: chatGptImageOutputShape,
+    }, async (input) => {
+        const textContent = (text) => [{ type: "text", text }];
+        let parsed;
+        try {
+            parsed = chatGptImageInputSchema.parse(input);
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: textContent(error instanceof Error ? error.message : String(error)),
+            };
+        }
+        const consultInput = buildChatGptImageConsultInput(parsed);
+        const result = await runConsultTool(consultInput, { server: server.server });
+        if (result.isError || !result.structuredContent) {
+            return result;
+        }
+        const structuredContent = {
+            ...result.structuredContent,
+            requestedOutputPath: consultInput.generateImage,
+        };
+        return {
+            ...result,
+            structuredContent,
+        };
+    });
+}