@steipete/oracle 0.4.0

package/dist/src/oracle/gemini.js

@@ -0,0 +1,185 @@
+import { GoogleGenAI, HarmCategory, HarmBlockThreshold } from '@google/genai';
+const MODEL_ID_MAP = {
+    'gemini-3-pro': 'gemini-3-pro-preview',
+    'gpt-5.1-pro': 'gpt-5.1-pro', // unused, normalize TS map
+    'gpt-5-pro': 'gpt-5-pro',
+    'gpt-5.1': 'gpt-5.1',
+    'gpt-5.1-codex': 'gpt-5.1-codex',
+    'claude-4.5-sonnet': 'claude-4.5-sonnet',
+    'claude-4.1-opus': 'claude-4.1-opus',
+};
+export function resolveGeminiModelId(modelName) {
+    // Map our logical Gemini names to the exact model ids expected by the SDK.
+    return MODEL_ID_MAP[modelName] ?? modelName;
+}
+export function createGeminiClient(apiKey, modelName = 'gemini-3-pro', resolvedModelId) {
+    const modelId = resolvedModelId ?? resolveGeminiModelId(modelName);
+    const genAI = new GoogleGenAI({ apiKey });
+    const adaptBodyToGemini = (body) => {
+        const contents = body.input.map((inputItem) => ({
+            role: inputItem.role === 'user' ? 'user' : 'model',
+            parts: inputItem.content
+                .map((contentPart) => {
+                if (contentPart.type === 'input_text') {
+                    return { text: contentPart.text };
+                }
+                return null;
+            })
+                .filter((part) => part !== null),
+        }));
+        const tools = body.tools
+            ?.map((tool) => {
+            if (tool.type === 'web_search_preview') {
+                return {
+                    googleSearch: {},
+                };
+            }
+            return {};
+        })
+            .filter((t) => Object.keys(t).length > 0);
+        const safetySettings = [
+            {
+                category: HarmCategory.HARM_CATEGORY_HARASSMENT,
+                threshold: HarmBlockThreshold.BLOCK_NONE,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
+                threshold: HarmBlockThreshold.BLOCK_NONE,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
+                threshold: HarmBlockThreshold.BLOCK_NONE,
+            },
+            {
+                category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold: HarmBlockThreshold.BLOCK_NONE,
+            },
+        ];
+        const systemInstruction = body.instructions
+            ? { role: 'system', parts: [{ text: body.instructions }] }
+            : undefined;
+        return {
+            model: modelId,
+            contents,
+            config: {
+                maxOutputTokens: body.max_output_tokens,
+                safetySettings,
+                tools,
+                systemInstruction,
+            },
+        };
+    };
+    const adaptGeminiResponseToOracle = (geminiResponse) => {
+        const outputText = [];
+        const output = [];
+        geminiResponse.candidates?.forEach((candidate) => {
+            candidate.content?.parts?.forEach((part) => {
+                if (part.text) {
+                    outputText.push(part.text);
+                    output.push({ type: 'text', text: part.text });
+                }
+            });
+        });
+        const usage = {
+            input_tokens: geminiResponse.usageMetadata?.promptTokenCount || 0,
+            output_tokens: geminiResponse.usageMetadata?.candidatesTokenCount || 0,
+            total_tokens: (geminiResponse.usageMetadata?.promptTokenCount || 0) + (geminiResponse.usageMetadata?.candidatesTokenCount || 0),
+        };
+        return {
+            id: geminiResponse.responseId ?? `gemini-${Date.now()}`,
+            status: 'completed',
+            output_text: outputText,
+            output,
+            usage,
+        };
+    };
+    const adaptAggregatedTextToOracle = (text, usageMetadata, responseId) => {
+        const usage = {
+            input_tokens: usageMetadata?.promptTokenCount ?? 0,
+            output_tokens: usageMetadata?.candidatesTokenCount ?? 0,
+            total_tokens: (usageMetadata?.promptTokenCount ?? 0) + (usageMetadata?.candidatesTokenCount ?? 0),
+        };
+        return {
+            id: responseId ?? `gemini-${Date.now()}`,
+            status: 'completed',
+            output_text: [text],
+            output: [{ type: 'text', text }],
+            usage,
+        };
+    };
+    const enrichGeminiError = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('404')) {
+            return new Error(`Gemini model not available to this API key/region. Confirm preview access and model ID (${modelId}). Original: ${message}`);
+        }
+        return error instanceof Error ? error : new Error(message);
+    };
+    return {
+        responses: {
+            stream: (body) => {
+                const geminiBody = adaptBodyToGemini(body);
+                let finalResponsePromise = null;
+                let aggregatedText = '';
+                let lastUsage;
+                let responseId;
+                async function* iterator() {
+                    let streamingResp;
+                    try {
+                        streamingResp = await genAI.models.generateContentStream(geminiBody);
+                    }
+                    catch (error) {
+                        throw enrichGeminiError(error);
+                    }
+                    for await (const chunk of streamingResp) {
+                        const text = chunk.text;
+                        if (text) {
+                            aggregatedText += text;
+                            yield { type: 'chunk', delta: text };
+                        }
+                        if (chunk.usageMetadata) {
+                            lastUsage = chunk.usageMetadata;
+                        }
+                        if (chunk.responseId) {
+                            responseId = chunk.responseId;
+                        }
+                    }
+                    finalResponsePromise = Promise.resolve(adaptAggregatedTextToOracle(aggregatedText, lastUsage, responseId));
+                }
+                const generator = iterator();
+                return {
+                    [Symbol.asyncIterator]: () => generator,
+                    finalResponse: async () => {
+                        // Ensure the stream has been consumed or at least started to get the promise
+                        if (!finalResponsePromise) {
+                            // In case the user calls finalResponse before iterating, we need to consume the stream
+                            // This is a bit edge-casey but safe.
+                            for await (const _ of generator) { }
+                        }
+                        if (!finalResponsePromise) {
+                            throw new Error('Response promise not initialized');
+                        }
+                        return finalResponsePromise;
+                    }
+                };
+            },
+            create: async (body) => {
+                const geminiBody = adaptBodyToGemini(body);
+                let result;
+                try {
+                    result = await genAI.models.generateContent(geminiBody);
+                }
+                catch (error) {
+                    throw enrichGeminiError(error);
+                }
+                return adaptGeminiResponseToOracle(result);
+            },
+            retrieve: async (id) => {
+                return {
+                    id,
+                    status: 'error',
+                    error: { message: 'Retrieve by ID not supported for Gemini API yet.' },
+                };
+            },
+        },
+    };
+}

package/dist/src/oracle/logging.js

@@ -0,0 +1,36 @@
+export function maskApiKey(key) {
+    if (!key)
+        return null;
+    if (key.length <= 8)
+        return `${key[0] ?? ''}***${key[key.length - 1] ?? ''}`;
+    const prefix = key.slice(0, 4);
+    const suffix = key.slice(-4);
+    return `${prefix}****${suffix}`;
+}
+export function formatBaseUrlForLog(raw) {
+    if (!raw)
+        return '';
+    try {
+        const parsed = new URL(raw);
+        const segments = parsed.pathname.split('/').filter(Boolean);
+        let path = '';
+        if (segments.length > 0) {
+            path = `/${segments[0]}`;
+            if (segments.length > 1) {
+                path += '/...';
+            }
+        }
+        const allowedQueryKeys = ['api-version'];
+        const maskedQuery = allowedQueryKeys
+            .filter((key) => parsed.searchParams.has(key))
+            .map((key) => `${key}=***`);
+        const query = maskedQuery.length > 0 ? `?${maskedQuery.join('&')}` : '';
+        return `${parsed.protocol}//${parsed.host}${path}${query}`;
+    }
+    catch {
+        const trimmed = raw.trim();
+        if (trimmed.length <= 64)
+            return trimmed;
+        return `${trimmed.slice(0, 32)}…${trimmed.slice(-8)}`;
+    }
+}

package/dist/src/oracle/markdown.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+const EXT_TO_LANG = {
+    '.ts': 'ts',
+    '.tsx': 'tsx',
+    '.js': 'js',
+    '.jsx': 'jsx',
+    '.json': 'json',
+    '.swift': 'swift',
+    '.md': 'md',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.zsh': 'bash',
+    '.py': 'python',
+    '.rb': 'ruby',
+    '.rs': 'rust',
+    '.go': 'go',
+    '.java': 'java',
+    '.c': 'c',
+    '.h': 'c',
+    '.cpp': 'cpp',
+    '.hpp': 'cpp',
+    '.css': 'css',
+    '.scss': 'scss',
+    '.sql': 'sql',
+    '.yaml': 'yaml',
+    '.yml': 'yaml',
+};
+function detectFenceLanguage(displayPath) {
+    const ext = path.extname(displayPath).toLowerCase();
+    return EXT_TO_LANG[ext] ?? null;
+}
+function pickFence(content) {
+    // Choose a fence longer than any backtick run inside the file so the block can't prematurely close.
+    const matches = [...content.matchAll(/`+/g)];
+    const maxTicks = matches.reduce((max, m) => Math.max(max, m[0].length), 0);
+    const fenceLength = Math.max(3, maxTicks + 1);
+    return '`'.repeat(fenceLength);
+}
+export function formatFileSection(displayPath, content) {
+    const fence = pickFence(content);
+    const lang = detectFenceLanguage(displayPath);
+    const normalized = content.replace(/\s+$/u, '');
+    const header = `### File: ${displayPath}`;
+    const fenceOpen = lang ? `${fence}${lang}` : fence;
+    return [header, fenceOpen, normalized, fence, ''].join('\n');
+}

package/dist/src/oracle/multiModelRunner.js

@@ -0,0 +1,164 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runOracle, OracleResponseError, OracleTransportError, extractResponseMetadata, asOracleUserError, extractTextOutput, } from '../oracle.js';
+import { sessionStore } from '../sessionStore.js';
+const OSC_PROGRESS_PREFIX = '\u001b]9;4;';
+const OSC_PROGRESS_END = '\u001b\\';
+function forwardOscProgress(chunk, shouldForward) {
+    if (!shouldForward || !chunk.includes(OSC_PROGRESS_PREFIX)) {
+        return;
+    }
+    let searchFrom = 0;
+    while (searchFrom < chunk.length) {
+        const start = chunk.indexOf(OSC_PROGRESS_PREFIX, searchFrom);
+        if (start === -1) {
+            break;
+        }
+        const end = chunk.indexOf(OSC_PROGRESS_END, start + OSC_PROGRESS_PREFIX.length);
+        if (end === -1) {
+            break;
+        }
+        process.stdout.write(chunk.slice(start, end + OSC_PROGRESS_END.length));
+        searchFrom = end + OSC_PROGRESS_END.length;
+    }
+}
+const defaultDeps = {
+    store: sessionStore,
+    runOracleImpl: runOracle,
+    now: () => Date.now(),
+};
+export async function runMultiModelApiSession(params, deps = defaultDeps) {
+    const { sessionMeta, runOptions, models, cwd } = params;
+    const { onModelDone } = params;
+    const store = deps.store ?? sessionStore;
+    const runOracleImpl = deps.runOracleImpl ?? runOracle;
+    const now = deps.now ?? (() => Date.now());
+    const startMark = now();
+    const executions = models.map((model) => startModelExecution({
+        sessionMeta,
+        runOptions,
+        model,
+        cwd,
+        store,
+        runOracleImpl,
+    }));
+    const settled = await Promise.allSettled(executions.map((exec) => exec.promise.then(async (value) => {
+        if (onModelDone) {
+            await onModelDone(value);
+        }
+        return value;
+    }, (error) => {
+        throw error;
+    })));
+    const fulfilled = [];
+    const rejected = [];
+    settled.forEach((result, index) => {
+        const exec = executions[index];
+        if (result.status === 'fulfilled') {
+            fulfilled.push(result.value);
+        }
+        else {
+            rejected.push({ model: exec.model, reason: result.reason });
+        }
+    });
+    return {
+        fulfilled,
+        rejected,
+        elapsedMs: now() - startMark,
+    };
+}
+function startModelExecution({ sessionMeta, runOptions, model, cwd, store, runOracleImpl, }) {
+    const logWriter = store.createLogWriter(sessionMeta.id, model);
+    const perModelOptions = {
+        ...runOptions,
+        model,
+        models: undefined,
+        sessionId: `${sessionMeta.id}:${model}`,
+    };
+    const perModelLog = (message) => {
+        logWriter.logLine(message ?? '');
+    };
+    const mirrorOscProgress = process.stdout.isTTY === true;
+    const perModelWrite = (chunk) => {
+        logWriter.writeChunk(chunk);
+        forwardOscProgress(chunk, mirrorOscProgress);
+        return true;
+    };
+    const promise = (async () => {
+        await store.updateModelRun(sessionMeta.id, model, {
+            status: 'running',
+            queuedAt: new Date().toISOString(),
+            startedAt: new Date().toISOString(),
+        });
+        const result = await runOracleImpl({
+            ...perModelOptions,
+            effectiveModelId: model,
+            // Drop per-model preamble; the aggregate runner prints the shared header and tips once.
+            suppressHeader: true,
+            suppressAnswerHeader: true,
+            suppressTips: true,
+        }, {
+            cwd,
+            log: perModelLog,
+            write: perModelWrite,
+        });
+        if (result.mode !== 'live') {
+            throw new Error('Unexpected preview result while running a session.');
+        }
+        const answerText = extractTextOutput(result.response);
+        await store.updateModelRun(sessionMeta.id, model, {
+            status: 'completed',
+            completedAt: new Date().toISOString(),
+            usage: result.usage,
+            response: extractResponseMetadata(result.response),
+            transport: undefined,
+            error: undefined,
+            log: await describeLog(sessionMeta.id, logWriter.logPath, store),
+        });
+        return {
+            model,
+            usage: result.usage,
+            answerText,
+            logPath: logWriter.logPath,
+        };
+    })()
+        .catch(async (error) => {
+        const userError = asOracleUserError(error);
+        const responseMetadata = error instanceof OracleResponseError ? error.metadata : undefined;
+        const transportMetadata = error instanceof OracleTransportError ? { reason: error.reason } : undefined;
+        await store.updateModelRun(sessionMeta.id, model, {
+            status: 'error',
+            completedAt: new Date().toISOString(),
+            response: responseMetadata,
+            transport: transportMetadata,
+            error: userError
+                ? {
+                    category: userError.category,
+                    message: userError.message,
+                    details: userError.details,
+                }
+                : undefined,
+            log: await describeLog(sessionMeta.id, logWriter.logPath, store),
+        });
+        throw error;
+    })
+        .finally(() => {
+        logWriter.stream.end();
+    });
+    return { model, promise };
+}
+async function describeLog(sessionId, logFilePath, store) {
+    const { dir } = await store.getPaths(sessionId);
+    const relative = path.relative(dir, logFilePath);
+    try {
+        const stats = await fsStat(logFilePath);
+        return { path: relative, bytes: stats.size };
+    }
+    catch {
+        return { path: relative };
+    }
+}
+async function fsStat(target) {
+    const stats = await fs.stat(target);
+    return { size: stats.size };
+}

package/dist/src/oracle/oscProgress.js

@@ -0,0 +1,66 @@
+import process from 'node:process';
+const OSC = '\u001b]9;4;';
+const ST = '\u001b\\';
+function sanitizeLabel(label) {
+    const withoutEscape = label.split('\u001b').join('');
+    const withoutBellAndSt = withoutEscape.replaceAll('\u0007', '').replaceAll('\u009c', '');
+    return withoutBellAndSt.replaceAll(']', '').trim();
+}
+export function supportsOscProgress(env = process.env, isTty = process.stdout.isTTY) {
+    if (!isTty) {
+        return false;
+    }
+    if (env.ORACLE_NO_OSC_PROGRESS === '1') {
+        return false;
+    }
+    if (env.ORACLE_FORCE_OSC_PROGRESS === '1') {
+        return true;
+    }
+    const termProgram = (env.TERM_PROGRAM ?? '').toLowerCase();
+    if (termProgram.includes('ghostty')) {
+        return true;
+    }
+    if (termProgram.includes('wezterm')) {
+        return true;
+    }
+    if (env.WT_SESSION) {
+        return true; // Windows Terminal exposes this
+    }
+    return false;
+}
+export function startOscProgress(options = {}) {
+    const { label = 'Waiting for API', targetMs = 10 * 60_000, write = (text) => process.stdout.write(text), indeterminate = false, } = options;
+    if (!supportsOscProgress(options.env, options.isTty)) {
+        return () => { };
+    }
+    const cleanLabel = sanitizeLabel(label);
+    if (indeterminate) {
+        write(`${OSC}3;;${cleanLabel}${ST}`);
+        return () => {
+            write(`${OSC}0;0;${cleanLabel}${ST}`);
+        };
+    }
+    const target = Math.max(targetMs, 1_000);
+    const send = (state, percent) => {
+        const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+        write(`${OSC}${state};${clamped};${cleanLabel}${ST}`);
+    };
+    const startedAt = Date.now();
+    send(1, 0); // activate progress bar
+    const timer = setInterval(() => {
+        const elapsed = Date.now() - startedAt;
+        const percent = Math.min(99, (elapsed / target) * 100);
+        send(1, percent);
+    }, 900);
+    timer.unref?.();
+    let stopped = false;
+    return () => {
+        // biome-ignore lint/nursery/noUnnecessaryConditions: multiple callers may try to stop
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        clearInterval(timer);
+        send(0, 0); // clear the progress bar
+    };
+}

package/dist/src/oracle/promptAssembly.js

@@ -0,0 +1,13 @@
+import { formatFileSection } from './markdown.js';
+/**
+ * Build the shared markdown structure for system/user/file sections.
+ * Collapses excessive blank lines and trims trailing whitespace to keep
+ * snapshots stable across CLI and browser modes.
+ */
+export function buildPromptMarkdown(systemPrompt, userPrompt, sections) {
+    const lines = ['[SYSTEM]', systemPrompt, '', '[USER]', userPrompt, ''];
+    sections.forEach((section) => {
+        lines.push(formatFileSection(section.displayPath, section.content));
+    });
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+}

package/dist/src/oracle/request.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import { DEFAULT_SYSTEM_PROMPT } from './config.js';
+import { createFileSections, readFiles } from './files.js';
+import { formatFileSection } from './markdown.js';
+import { createFsAdapter } from './fsAdapter.js';
+export function buildPrompt(basePrompt, files, cwd = process.cwd()) {
+    if (!files.length) {
+        return basePrompt;
+    }
+    const sections = createFileSections(files, cwd);
+    const sectionText = sections.map((section) => section.sectionText).join('\n\n');
+    return `${basePrompt.trim()}\n\n${sectionText}`;
+}
+export function buildRequestBody({ modelConfig, systemPrompt, userPrompt, searchEnabled, maxOutputTokens, background, storeResponse, }) {
+    return {
+        model: modelConfig.apiModel ?? modelConfig.model,
+        instructions: systemPrompt,
+        input: [
+            {
+                role: 'user',
+                content: [
+                    {
+                        type: 'input_text',
+                        text: userPrompt,
+                    },
+                ],
+            },
+        ],
+        tools: searchEnabled ? [{ type: 'web_search_preview' }] : undefined,
+        reasoning: modelConfig.reasoning || undefined,
+        max_output_tokens: maxOutputTokens,
+        background: background ? true : undefined,
+        store: storeResponse ? true : undefined,
+    };
+}
+export async function renderPromptMarkdown(options, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const fsModule = deps.fs ?? createFsAdapter(fs);
+    const files = await readFiles(options.file ?? [], { cwd, fsModule });
+    const sections = createFileSections(files, cwd);
+    const systemPrompt = options.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const userPrompt = (options.prompt ?? '').trim();
+    const lines = ['[SYSTEM]', systemPrompt, ''];
+    lines.push('[USER]', userPrompt, '');
+    sections.forEach((section) => {
+        lines.push(formatFileSection(section.displayPath, section.content));
+    });
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+}