@steipete/oracle 0.11.1 → 0.12.0

package/dist/src/mcp/types.js

@@ -11,6 +11,7 @@ export const consultInputSchema = z
     browserModelLabel: z.string().optional(),
     browserAttachments: z.enum(["auto", "never", "always"]).optional(),
     browserBundleFiles: z.boolean().optional(),
+    browserBundleFormat: z.enum(["text", "zip"]).optional(),
     browserThinkingTime: z.enum(["light", "standard", "extended", "heavy"]).optional(),
     browserModelStrategy: z.enum(["select", "current", "ignore"]).optional(),
     browserResearchMode: z.enum(["deep"]).optional(),

package/dist/src/mcp/utils.js

@@ -1,6 +1,6 @@
 import { resolveRunOptionsFromConfig } from "../cli/runOptions.js";
 import { Launcher } from "chrome-launcher";
-export function mapConsultToRunOptions({ prompt, files, model, models, engine, search, browserAttachments, browserBundleFiles, browserFollowUps, userConfig, env = process.env, }) {
+export function mapConsultToRunOptions({ prompt, files, model, models, engine, search, browserAttachments, browserBundleFiles, browserBundleFormat, browserFollowUps, userConfig, env = process.env, }) {
     // Normalize CLI-style inputs through the shared resolver so config/env defaults apply,
     // then overlay MCP-only overrides such as explicit search toggles.
     const mergedModels = Array.isArray(models) && models.length > 0
@@ -24,6 +24,9 @@ export function mapConsultToRunOptions({ prompt, files, model, models, engine, s
     if (typeof browserBundleFiles === "boolean") {
         result.runOptions.browserBundleFiles = browserBundleFiles;
     }
+    if (browserBundleFormat) {
+        result.runOptions.browserBundleFormat = browserBundleFormat;
+    }
     if (Array.isArray(browserFollowUps)) {
         result.runOptions.browserFollowUps = browserFollowUps
             .map((entry) => entry.trim())

package/dist/src/oracle/baseUrl.js

@@ -0,0 +1,17 @@
+const NATIVE_API_HOSTS = [
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+    "api.x.ai",
+];
+export function isCustomBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return false;
+    try {
+        const url = new URL(baseUrl);
+        return !NATIVE_API_HOSTS.some((host) => url.hostname === host || url.hostname.endsWith(`.${host}`));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/oracle/client.js

@@ -4,28 +4,7 @@ import { createRequire } from "node:module";
 import { createGeminiClient } from "./gemini.js";
 import { createClaudeClient } from "./claude.js";
 import { isOpenRouterBaseUrl } from "./modelResolver.js";
-/**
- * Known native API base URLs that should still use their dedicated SDKs.
- * Any other custom base URL is treated as an OpenAI-compatible proxy and
- * all models are routed through the chat/completions adapter.
- */
-const NATIVE_API_HOSTS = [
-    "api.openai.com",
-    "api.anthropic.com",
-    "generativelanguage.googleapis.com",
-    "api.x.ai",
-];
-export function isCustomBaseUrl(baseUrl) {
-    if (!baseUrl)
-        return false;
-    try {
-        const url = new URL(baseUrl);
-        return !NATIVE_API_HOSTS.some((host) => url.hostname === host || url.hostname.endsWith(`.${host}`));
-    }
-    catch {
-        return false;
-    }
-}
+import { isCustomBaseUrl } from "./baseUrl.js";
 export function buildAzureResponsesBaseUrl(endpoint) {
     return `${endpoint.replace(/\/+$/, "")}/openai/v1`;
 }

package/dist/src/oracle/config.js

@@ -1,7 +1,9 @@
-import { countTokens as countTokensGpt5 } from "gpt-tokenizer/model/gpt-5";
-import { countTokens as countTokensGpt5Pro } from "gpt-tokenizer/model/gpt-5-pro";
-import { countTokens as countTokensAnthropicRaw } from "@anthropic-ai/tokenizer";
+import { createRequire } from "node:module";
 import { stringifyTokenizerInput } from "./tokenStringifier.js";
+const require = createRequire(import.meta.url);
+let countTokensGpt5Impl;
+let countTokensGpt5ProImpl;
+let countTokensAnthropicImpl;
 export const DEFAULT_MODEL = "gpt-5.5-pro";
 export const PRO_MODELS = new Set([
     "gpt-5.5-pro",
@@ -12,7 +14,18 @@ export const PRO_MODELS = new Set([
     "claude-4.6-sonnet",
     "claude-4.1-opus",
 ]);
-const countTokensAnthropic = (input) => countTokensAnthropicRaw(stringifyTokenizerInput(input));
+const countTokensGpt5 = (input, options) => {
+    countTokensGpt5Impl ??= require("gpt-tokenizer/model/gpt-5").countTokens;
+    return countTokensGpt5Impl(input, options);
+};
+const countTokensGpt5Pro = (input, options) => {
+    countTokensGpt5ProImpl ??= require("gpt-tokenizer/model/gpt-5-pro").countTokens;
+    return countTokensGpt5ProImpl(input, options);
+};
+const countTokensAnthropic = (input) => {
+    countTokensAnthropicImpl ??= require("@anthropic-ai/tokenizer").countTokens;
+    return countTokensAnthropicImpl(stringifyTokenizerInput(input));
+};
 export const MODEL_CONFIGS = {
     "gpt-5.5-pro": {
         model: "gpt-5.5-pro",

package/dist/src/oracle/gemini.js

@@ -1,26 +1,6 @@
 import { GoogleGenAI, HarmCategory, HarmBlockThreshold, } from "@google/genai";
-const MODEL_ID_MAP = {
-    "gemini-3.1-pro": "gemini-3.1-pro-preview",
-    "gemini-3-pro": "gemini-3-pro-preview",
-    "gpt-5.5": "gpt-5.5",
-    "gpt-5.5-pro": "gpt-5.5-pro",
-    "gpt-5.4": "gpt-5.4",
-    "gpt-5.4-pro": "gpt-5.4-pro",
-    "gpt-5.1-pro": "gpt-5.1-pro",
-    "gpt-5-pro": "gpt-5-pro",
-    "gpt-5.1": "gpt-5.1",
-    "gpt-5.1-codex": "gpt-5.1-codex",
-    "gpt-5.2": "gpt-5.2",
-    "gpt-5.2-instant": "gpt-5.2-instant",
-    "gpt-5.2-pro": "gpt-5.2-pro",
-    "claude-4.6-sonnet": "claude-4.6-sonnet",
-    "claude-4.1-opus": "claude-4.1-opus",
-    "grok-4.1": "grok-4.1",
-};
-export function resolveGeminiModelId(modelName) {
-    // Map our logical Gemini names to the exact model ids expected by the SDK.
-    return MODEL_ID_MAP[modelName] ?? modelName;
-}
+import { resolveGeminiModelId } from "./geminiModels.js";
+export { resolveGeminiModelId } from "./geminiModels.js";
 export function createGeminiClient(apiKey, modelName = "gemini-3-pro", resolvedModelId) {
     const modelId = resolvedModelId ?? resolveGeminiModelId(modelName);
     const genAI = new GoogleGenAI({ apiKey });

package/dist/src/oracle/geminiModels.js

@@ -0,0 +1,21 @@
+const MODEL_ID_MAP = {
+    "gemini-3.1-pro": "gemini-3.1-pro-preview",
+    "gemini-3-pro": "gemini-3-pro-preview",
+    "gpt-5.5": "gpt-5.5",
+    "gpt-5.5-pro": "gpt-5.5-pro",
+    "gpt-5.4": "gpt-5.4",
+    "gpt-5.4-pro": "gpt-5.4-pro",
+    "gpt-5.1-pro": "gpt-5.1-pro",
+    "gpt-5-pro": "gpt-5-pro",
+    "gpt-5.1": "gpt-5.1",
+    "gpt-5.1-codex": "gpt-5.1-codex",
+    "gpt-5.2": "gpt-5.2",
+    "gpt-5.2-instant": "gpt-5.2-instant",
+    "gpt-5.2-pro": "gpt-5.2-pro",
+    "claude-4.6-sonnet": "claude-4.6-sonnet",
+    "claude-4.1-opus": "claude-4.1-opus",
+    "grok-4.1": "grok-4.1",
+};
+export function resolveGeminiModelId(modelName) {
+    return MODEL_ID_MAP[modelName] ?? modelName;
+}

package/dist/src/oracle/modelResolver.js

@@ -1,8 +1,14 @@
+import { createRequire } from "node:module";
 import { MODEL_CONFIGS, PRO_MODELS } from "./config.js";
-import { countTokens as countTokensGpt5Pro } from "gpt-tokenizer/model/gpt-5-pro";
 import { pricingFromUsdPerMillion } from "tokentally";
 const OPENROUTER_DEFAULT_BASE = "https://openrouter.ai/api/v1";
 const OPENROUTER_MODELS_ENDPOINT = "https://openrouter.ai/api/v1/models";
+const require = createRequire(import.meta.url);
+let countTokensGpt5ProImpl;
+const countTokensGpt5Pro = (input, options) => {
+    countTokensGpt5ProImpl ??= require("gpt-tokenizer/model/gpt-5-pro").countTokens;
+    return countTokensGpt5ProImpl(input, options);
+};
 export function isKnownModel(model) {
     return Object.hasOwn(MODEL_CONFIGS, model);
 }

package/dist/src/oracle/multiModelRunner.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { runOracle, OracleResponseError, OracleTransportError, extractResponseMetadata, asOracleUserError, extractTextOutput, } from "../oracle.js";
+import { runOracle, OracleResponseError, OracleTransportError, extractResponseMetadata, asOracleUserError, extractTextOutput, classifyProviderFailure, } from "../oracle.js";
 import { sessionStore } from "../sessionStore.js";
 import { findOscProgressSequences, OSC_PROGRESS_PREFIX } from "osc-progress";
 function forwardOscProgress(chunk, shouldForward) {
@@ -113,6 +113,13 @@ function startModelExecution({ sessionMeta, runOptions, model, cwd, store, runOr
     })()
         .catch(async (error) => {
         const userError = asOracleUserError(error);
+        const providerFailure = classifyProviderFailure(error, {
+            model,
+            providerMode: runOptions.provider,
+            azure: runOptions.azure,
+            baseUrl: runOptions.baseUrl,
+            apiKey: runOptions.apiKey,
+        });
         const responseMetadata = error instanceof OracleResponseError ? error.metadata : undefined;
         const transportMetadata = error instanceof OracleTransportError ? { reason: error.reason } : undefined;
         await store.updateModelRun(sessionMeta.id, model, {
@@ -126,7 +133,18 @@ function startModelExecution({ sessionMeta, runOptions, model, cwd, store, runOr
                     message: userError.message,
                     details: userError.details,
                 }
-                : undefined,
+                : providerFailure
+                    ? {
+                        category: providerFailure.category,
+                        message: providerFailure.label,
+                        details: {
+                            provider: providerFailure.provider,
+                            keyEnv: providerFailure.keyEnv,
+                            providerMessage: providerFailure.providerMessage,
+                            fix: providerFailure.fix,
+                        },
+                    }
+                    : undefined,
             log: await describeLog(sessionMeta.id, logWriter.logPath, store),
         });
         throw error;

package/dist/src/oracle/providerFailures.js

@@ -0,0 +1,204 @@
+import { OracleTransportError, asOracleUserError } from "./errors.js";
+import { buildProviderRoutePlan } from "./providerRoutePlan.js";
+export function classifyProviderFailure(error, context) {
+    const userError = asOracleUserError(error);
+    if (userError) {
+        return null;
+    }
+    const normalizedContext = normalizeContext(context);
+    const route = inferFailureRoute(normalizedContext);
+    const rawProviderMessage = extractProviderMessage(error);
+    const lower = rawProviderMessage.toLowerCase();
+    const category = classifyMessage(lower, error);
+    if (!category) {
+        return null;
+    }
+    const providerMessage = sanitizeProviderMessage(rawProviderMessage);
+    return {
+        category,
+        label: labelForCategory(category),
+        provider: route.provider,
+        keyEnv: route.keySource,
+        providerMessage,
+        fix: fixForCategory(category, route.provider, normalizedContext.model, route.keySource),
+    };
+}
+function classifyMessage(lower, error) {
+    if (isLocalPermissionError(error, lower)) {
+        return null;
+    }
+    if (lower.includes("expired") &&
+        (lower.includes("api key") || lower.includes("credential") || lower.includes("token"))) {
+        return "auth-expired";
+    }
+    if (lower.includes("invalid x-api-key") ||
+        lower.includes("invalid api key") ||
+        lower.includes("api key is invalid") ||
+        lower.includes("api key not valid") ||
+        lower.includes("incorrect api key") ||
+        lower.includes("unauthorized") ||
+        lower.includes("unauthenticated") ||
+        hasStatusCode(lower, "401")) {
+        return "auth-failed";
+    }
+    if (lower.includes("insufficient_quota") ||
+        lower.includes("quota exceeded") ||
+        lower.includes("billing") ||
+        lower.includes("resource_exhausted")) {
+        return "quota-exceeded";
+    }
+    if (lower.includes("rate limit") || lower.includes("rate_limit") || hasStatusCode(lower, "429")) {
+        return "rate-limited";
+    }
+    if (error instanceof OracleTransportError && error.reason === "model-unavailable") {
+        return "model-unavailable";
+    }
+    if (lower.includes("model not available") ||
+        lower.includes("model_not_found") ||
+        lower.includes("unknown model") ||
+        lower.includes("does not exist")) {
+        return "model-unavailable";
+    }
+    return null;
+}
+function hasStatusCode(lower, status) {
+    return new RegExp(`(^|\\D)${status}(\\D|$)`).test(lower);
+}
+function isLocalPermissionError(error, lower) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code).toUpperCase()
+        : "";
+    return (code === "EACCES" ||
+        code === "EPERM" ||
+        lower.includes("eacces:") ||
+        lower.includes("eperm:") ||
+        /permission denied, (open|scandir|mkdir|access|unlink|rename)\b/.test(lower));
+}
+function extractProviderMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function sanitizeProviderMessage(message) {
+    return message
+        .replace(/\bBearer\s+[A-Za-z0-9._\-+/=]+/gi, "Bearer [redacted]")
+        .replace(/\b(api[-_ ]?key\s+provided)(\s*[:=]?\s*)["']?[^"',;\s]+/gi, "$1$2[redacted]")
+        .replace(/\b(api[-_ ]?key|x-api-key|authorization|token)(\s*[:=]\s*)["']?[^"',;\s]+/gi, "$1$2[redacted]")
+        .replace(/\bsk-(?:ant-|or-)?[A-Za-z0-9_-]{8,}\b/g, "sk-...[redacted]")
+        .replace(/\bxai-[A-Za-z0-9_-]{8,}\b/g, "xai-...[redacted]")
+        .replace(/\bAIza[0-9A-Za-z_-]{8,}\b/g, "AIza...[redacted]");
+}
+function normalizeContext(context) {
+    if (typeof context === "string") {
+        return { model: context };
+    }
+    return context ?? {};
+}
+function inferFailureRoute(context) {
+    if (context.model) {
+        const plan = buildProviderRoutePlan({
+            model: context.model,
+            providerMode: context.providerMode,
+            azure: context.azure,
+            baseUrl: context.baseUrl,
+            apiKey: context.apiKey,
+            env: context.env,
+        });
+        const keySource = normalizeKeySource(plan.keySource);
+        if (plan.providerLabel === "OpenRouter" || plan.keySource.includes("OPENROUTER_API_KEY")) {
+            return { provider: "openrouter", keySource };
+        }
+        if (plan.provider === "azure")
+            return { provider: "azure", keySource };
+        if (plan.provider === "google")
+            return { provider: "gemini", keySource };
+        return { provider: plan.provider, keySource };
+    }
+    const normalized = context.model?.toLowerCase() ?? "";
+    const baseUrl = context.baseUrl?.toLowerCase() ?? "";
+    if (baseUrl.includes("openrouter.ai") || (normalized.includes("/") && !baseUrl)) {
+        return { provider: "openrouter", keySource: keyEnvForProvider("openrouter") };
+    }
+    if (context.azure?.endpoint?.trim() &&
+        context.providerMode !== "openai" &&
+        (normalized.startsWith("gpt") || normalized.startsWith("openai/") || !normalized.includes("/"))) {
+        return { provider: "azure", keySource: keyEnvForProvider("azure") };
+    }
+    if (normalized.startsWith("anthropic/"))
+        return providerRoute("anthropic");
+    if (normalized.startsWith("google/"))
+        return providerRoute("gemini");
+    if (normalized.startsWith("xai/"))
+        return providerRoute("xai");
+    if (normalized.startsWith("openai/"))
+        return providerRoute("openai");
+    if (normalized.startsWith("claude"))
+        return providerRoute("anthropic");
+    if (normalized.startsWith("gemini"))
+        return providerRoute("gemini");
+    if (normalized.startsWith("grok"))
+        return providerRoute("xai");
+    return providerRoute("openai");
+}
+function providerRoute(provider) {
+    return { provider, keySource: keyEnvForProvider(provider) };
+}
+function normalizeKeySource(keySource) {
+    if (!keySource || keySource.includes("|")) {
+        return undefined;
+    }
+    return keySource;
+}
+function keyEnvForProvider(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "gemini":
+            return "GEMINI_API_KEY";
+        case "xai":
+            return "XAI_API_KEY";
+        case "azure":
+            return "AZURE_OPENAI_API_KEY";
+        case "openrouter":
+            return "OPENROUTER_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return undefined;
+    }
+}
+function doctorCommand(model) {
+    return model ? `oracle doctor --providers --models ${model}` : "oracle doctor --providers";
+}
+function labelForCategory(category) {
+    switch (category) {
+        case "auth-failed":
+            return "auth failed";
+        case "auth-expired":
+            return "auth expired";
+        case "quota-exceeded":
+            return "quota exceeded";
+        case "rate-limited":
+            return "rate limited";
+        case "model-unavailable":
+            return "model unavailable";
+    }
+}
+function fixForCategory(category, provider, model, keySource) {
+    const doctor = doctorCommand(model);
+    const key = keySource ?? keyEnvForProvider(provider) ?? "the provider API key";
+    switch (category) {
+        case "auth-failed":
+            return key === "apiKey option"
+                ? `check --api-key value or run \`${doctor}\``
+                : `refresh ${key} or run \`${doctor}\``;
+        case "auth-expired":
+            return key === "apiKey option"
+                ? "replace --api-key value, then rerun the failed model"
+                : `rotate ${key}, then rerun the failed model`;
+        case "quota-exceeded":
+            return `check ${provider} billing/quota, then rerun the failed model`;
+        case "rate-limited":
+            return "retry later or reduce parallel model fan-out";
+        case "model-unavailable":
+            return `check model access/ID with \`${doctor}\``;
+    }
+}