@steipete/oracle 0.4.0

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

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { getCliVersion } from '../../version.js';
+import { LoggingMessageNotificationParamsSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ensureBrowserAvailable, mapConsultToRunOptions } from '../utils.js';
+import { sessionStore } from '../../sessionStore.js';
+async function readSessionLogTail(sessionId, maxBytes) {
+    try {
+        const log = await sessionStore.readLog(sessionId);
+        if (log.length <= maxBytes) {
+            return log;
+        }
+        return log.slice(-maxBytes);
+    }
+    catch {
+        return null;
+    }
+}
+import { performSessionRun } from '../../cli/sessionRunner.js';
+import { CHATGPT_URL } from '../../browser/constants.js';
+import { consultInputSchema } from '../types.js';
+import { loadUserConfig } from '../../config.js';
+import { resolveNotificationSettings } from '../../cli/notifier.js';
+import { mapModelToBrowserLabel, resolveBrowserModelLabel } from '../../cli/browserConfig.js';
+// Use raw shapes so the MCP SDK (with its bundled Zod) wraps them and emits valid JSON Schema.
+const consultInputShape = {
+    prompt: z.string().min(1, 'Prompt is required.'),
+    files: z.array(z.string()).default([]),
+    model: z.string().optional(),
+    models: z.array(z.string()).optional(),
+    engine: z.enum(['api', 'browser']).optional(),
+    browserModelLabel: z.string().optional(),
+    search: z.boolean().optional(),
+    slug: z.string().optional(),
+};
+const consultModelSummaryShape = z.object({
+    model: z.string(),
+    status: z.string(),
+    startedAt: z.string().optional(),
+    completedAt: z.string().optional(),
+    usage: z
+        .object({
+        inputTokens: z.number().optional(),
+        outputTokens: z.number().optional(),
+        reasoningTokens: z.number().optional(),
+        totalTokens: z.number().optional(),
+        cost: z.number().optional(),
+    })
+        .optional(),
+    response: z
+        .object({
+        id: z.string().optional(),
+        requestId: z.string().optional(),
+        status: z.string().optional(),
+    })
+        .optional(),
+    error: z
+        .object({
+        category: z.string().optional(),
+        message: z.string().optional(),
+    })
+        .optional(),
+    logPath: z.string().optional(),
+});
+const consultOutputShape = {
+    sessionId: z.string(),
+    status: z.string(),
+    output: z.string(),
+    models: z.array(consultModelSummaryShape).optional(),
+};
+export function summarizeModelRunsForConsult(runs) {
+    if (!runs || runs.length === 0) {
+        return undefined;
+    }
+    return runs.map((run) => {
+        const response = run.response
+            ? {
+                id: run.response.id ?? undefined,
+                requestId: run.response.requestId ?? undefined,
+                status: run.response.status ?? undefined,
+            }
+            : undefined;
+        const error = run.error
+            ? {
+                category: run.error.category,
+                message: run.error.message,
+            }
+            : undefined;
+        return {
+            model: run.model,
+            status: run.status ?? 'unknown',
+            startedAt: run.startedAt,
+            completedAt: run.completedAt,
+            usage: run.usage,
+            response,
+            error,
+            logPath: run.log?.path,
+        };
+    });
+}
+export function registerConsultTool(server) {
+    server.registerTool('consult', {
+        title: 'Run an oracle session',
+        description: 'Run a one-shot Oracle session (API or browser). Attach files/dirs for context, optional model/engine overrides, and an optional slug. Background handling follows the CLI defaults; browser runs only start when Chrome is available.',
+        // Cast to any to satisfy SDK typings across differing Zod versions.
+        inputSchema: consultInputShape,
+        outputSchema: consultOutputShape,
+    }, async (input) => {
+        const textContent = (text) => [{ type: 'text', text }];
+        const { prompt, files, model, models, engine, search, browserModelLabel, slug } = consultInputSchema.parse(input);
+        const { config: userConfig } = await loadUserConfig();
+        const { runOptions, resolvedEngine } = mapConsultToRunOptions({
+            prompt,
+            files: files ?? [],
+            model,
+            models,
+            engine,
+            search,
+            userConfig,
+            env: process.env,
+        });
+        const cwd = process.cwd();
+        const browserGuard = ensureBrowserAvailable(resolvedEngine);
+        if (resolvedEngine === 'browser' && browserGuard) {
+            return {
+                isError: true,
+                content: textContent(browserGuard),
+            };
+        }
+        let browserConfig;
+        if (resolvedEngine === 'browser') {
+            const preferredLabel = (browserModelLabel ?? model)?.trim();
+            const desiredModelLabel = resolveBrowserModelLabel(preferredLabel, runOptions.model);
+            // Keep the browser path minimal; only forward a desired model label for the ChatGPT picker.
+            browserConfig = {
+                url: CHATGPT_URL,
+                cookieSync: true,
+                headless: false,
+                hideWindow: false,
+                keepBrowser: false,
+                desiredModel: desiredModelLabel || mapModelToBrowserLabel(runOptions.model),
+            };
+        }
+        const notifications = resolveNotificationSettings({
+            cliNotify: undefined,
+            cliNotifySound: undefined,
+            env: process.env,
+            config: userConfig.notify,
+        });
+        const sessionMeta = await sessionStore.createSession({
+            ...runOptions,
+            mode: resolvedEngine,
+            slug,
+            browserConfig,
+        }, cwd, notifications);
+        const logWriter = sessionStore.createLogWriter(sessionMeta.id);
+        // Best-effort: emit MCP logging notifications for live chunks but never block the run.
+        const sendLog = (text, level = 'info') => server.server
+            .sendLoggingMessage(LoggingMessageNotificationParamsSchema.parse({
+            level,
+            data: { text, bytes: Buffer.byteLength(text, 'utf8') },
+        }))
+            .catch(() => { });
+        // Stream logs to both the session log and MCP logging notifications, but avoid buffering in memory
+        const log = (line) => {
+            logWriter.logLine(line);
+            if (line !== undefined) {
+                sendLog(line);
+            }
+        };
+        const write = (chunk) => {
+            logWriter.writeChunk(chunk);
+            sendLog(chunk, 'debug');
+            return true;
+        };
+        try {
+            await performSessionRun({
+                sessionMeta,
+                runOptions,
+                mode: resolvedEngine,
+                browserConfig,
+                cwd,
+                log,
+                write,
+                version: getCliVersion(),
+                notifications,
+                muteStdout: true,
+            });
+        }
+        catch (error) {
+            log(`Run failed: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                isError: true,
+                content: textContent(`Session ${sessionMeta.id} failed: ${error instanceof Error ? error.message : String(error)}`),
+            };
+        }
+        finally {
+            logWriter.stream.end();
+        }
+        try {
+            const finalMeta = (await sessionStore.readSession(sessionMeta.id)) ?? sessionMeta;
+            const summary = `Session ${sessionMeta.id} (${finalMeta.status})`;
+            const logTail = await readSessionLogTail(sessionMeta.id, 4000);
+            const modelsSummary = summarizeModelRunsForConsult(finalMeta.models);
+            return {
+                content: textContent([summary, logTail || '(log empty)'].join('\n').trim()),
+                structuredContent: {
+                    sessionId: sessionMeta.id,
+                    status: finalMeta.status,
+                    output: logTail ?? '',
+                    models: modelsSummary,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: textContent(`Session completed but metadata fetch failed: ${error instanceof Error ? error.message : String(error)}`),
+            };
+        }
+    });
+}

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

@@ -0,0 +1,75 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import fs from 'node:fs/promises';
+import { sessionStore } from '../../sessionStore.js';
+// URIs:
+// - oracle-session://<id>/metadata
+// - oracle-session://<id>/log
+// - oracle-session://<id>/request
+export function registerSessionResources(server) {
+    const template = new ResourceTemplate('oracle-session://{id}/{kind}', { list: undefined });
+    server.registerResource('oracle-session', template, {
+        title: 'oracle session resources',
+        description: 'Read stored session metadata, log, or request payload.',
+    }, async (uri, variables) => {
+        const idRaw = variables?.id;
+        const kindRaw = variables?.kind;
+        // uri-template variables arrive as string | string[]; collapse to first value.
+        const id = Array.isArray(idRaw) ? idRaw[0] : idRaw;
+        const kind = Array.isArray(kindRaw) ? kindRaw[0] : kindRaw;
+        if (!id || !kind) {
+            throw new Error('Missing id or kind');
+        }
+        switch (kind) {
+            case 'metadata': {
+                const metadata = await sessionStore.readSession(id);
+                if (!metadata) {
+                    throw new Error(`Session "${id}" not found.`);
+                }
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: JSON.stringify(metadata, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'log': {
+                const log = await sessionStore.readLog(id);
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: log,
+                        },
+                    ],
+                };
+            }
+            case 'request': {
+                const request = await sessionStore.readRequest(id);
+                if (request) {
+                    return {
+                        contents: [
+                            {
+                                uri: uri.href,
+                                text: JSON.stringify(request, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const paths = await sessionStore.getPaths(id);
+                const raw = await fs.readFile(paths.request, 'utf8');
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: raw,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unsupported resource kind: ${kind}`);
+        }
+    });
+}

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

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { sessionStore } from '../../sessionStore.js';
+import { sessionsInputSchema } from '../types.js';
+const sessionsInputShape = {
+    id: z.string().optional(),
+    hours: z.number().optional(),
+    limit: z.number().optional(),
+    includeAll: z.boolean().optional(),
+    detail: z.boolean().optional(),
+};
+const sessionsOutputShape = {
+    entries: z
+        .array(z.object({
+        id: z.string(),
+        createdAt: z.string(),
+        status: z.string(),
+        model: z.string().optional(),
+        mode: z.string().optional(),
+    }))
+        .optional(),
+    total: z.number().optional(),
+    truncated: z.boolean().optional(),
+    session: z
+        .object({
+        metadata: z.record(z.string(), z.any()),
+        log: z.string(),
+        request: z.record(z.string(), z.any()).optional(),
+    })
+        .optional(),
+};
+export function registerSessionsTool(server) {
+    server.registerTool('sessions', {
+        title: 'List or fetch oracle sessions',
+        description: 'List stored sessions (same defaults as `oracle status`) or, with id/slug, return a summary row. Pass detail:true to include metadata, log, and stored request for that session.',
+        inputSchema: sessionsInputShape,
+        outputSchema: sessionsOutputShape,
+    }, async (input) => {
+        const textContent = (text) => [{ type: 'text', text }];
+        const { id, hours = 24, limit = 100, includeAll = false, detail = false } = sessionsInputSchema.parse(input);
+        if (id) {
+            if (!detail) {
+                const metadata = await sessionStore.readSession(id);
+                if (!metadata) {
+                    throw new Error(`Session "${id}" not found.`);
+                }
+                return {
+                    content: textContent(`${metadata.createdAt} | ${metadata.status} | ${metadata.model ?? 'n/a'} | ${metadata.id}`),
+                    structuredContent: {
+                        entries: [
+                            {
+                                id: metadata.id,
+                                createdAt: metadata.createdAt,
+                                status: metadata.status,
+                                model: metadata.model,
+                                mode: metadata.mode,
+                            },
+                        ],
+                        total: 1,
+                        truncated: false,
+                    },
+                };
+            }
+            const metadata = await sessionStore.readSession(id);
+            if (!metadata) {
+                throw new Error(`Session "${id}" not found.`);
+            }
+            const log = await sessionStore.readLog(id);
+            const request = (await sessionStore.readRequest(id)) ?? undefined;
+            return {
+                content: textContent(log),
+                structuredContent: { session: { metadata, log, request } },
+            };
+        }
+        const metas = await sessionStore.listSessions();
+        const { entries, truncated, total } = sessionStore.filterSessions(metas, { hours, includeAll, limit });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: entries.map((entry) => `${entry.createdAt} | ${entry.status} | ${entry.model ?? 'n/a'} | ${entry.id}`).join('\n'),
+                },
+            ],
+            structuredContent: {
+                entries: entries.map((entry) => ({
+                    id: entry.id,
+                    createdAt: entry.createdAt,
+                    status: entry.status,
+                    model: entry.model,
+                    mode: entry.mode,
+                })),
+                total,
+                truncated,
+            },
+        };
+    });
+}

package/dist/src/mcp/types.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export const consultInputSchema = z.object({
+    prompt: z.string().min(1, 'Prompt is required.'),
+    files: z.array(z.string()).default([]),
+    model: z.string().optional(),
+    models: z.array(z.string()).optional(),
+    engine: z.enum(['api', 'browser']).optional(),
+    browserModelLabel: z.string().optional(),
+    search: z.boolean().optional(),
+    slug: z.string().optional(),
+});
+export const sessionsInputSchema = z.object({
+    id: z.string().optional(),
+    hours: z.number().optional(),
+    limit: z.number().optional(),
+    includeAll: z.boolean().optional(),
+    detail: z.boolean().optional(),
+});

package/dist/src/mcp/utils.js

@@ -0,0 +1,27 @@
+import { resolveRunOptionsFromConfig } from '../cli/runOptions.js';
+import { Launcher } from 'chrome-launcher';
+export function mapConsultToRunOptions({ prompt, files, model, models, engine, search, 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
+        ? [model, ...models].filter((entry) => Boolean(entry?.trim()))
+        : models;
+    const result = resolveRunOptionsFromConfig({ prompt, files, model, models: mergedModels, engine, userConfig, env });
+    if (typeof search === 'boolean') {
+        result.runOptions.search = search;
+    }
+    return result;
+}
+export function ensureBrowserAvailable(engine) {
+    if (engine !== 'browser') {
+        return null;
+    }
+    if (process.env.CHROME_PATH) {
+        return null;
+    }
+    const found = Launcher.getFirstInstallation();
+    if (!found) {
+        return 'Browser engine unavailable: no Chrome installation found and CHROME_PATH is unset.';
+    }
+    return null;
+}

package/dist/src/oracle/background.js

@@ -0,0 +1,134 @@
+import { APIConnectionError, APIConnectionTimeoutError } from 'openai';
+import chalk from 'chalk';
+import { formatElapsed } from './format.js';
+import { startHeartbeat } from '../heartbeat.js';
+import { OracleResponseError, OracleTransportError, describeTransportError, toTransportError, } from './errors.js';
+const BACKGROUND_MAX_WAIT_MS = 30 * 60 * 1000;
+const BACKGROUND_POLL_INTERVAL_MS = 5000;
+const BACKGROUND_RETRY_BASE_MS = 3000;
+const BACKGROUND_RETRY_MAX_MS = 15000;
+export async function executeBackgroundResponse(params) {
+    const { client, requestBody, log, wait, heartbeatIntervalMs, now, maxWaitMs } = params;
+    const initialResponse = await client.responses.create(requestBody);
+    if (!initialResponse || !initialResponse.id) {
+        throw new OracleResponseError('API did not return a response ID for the background run.', initialResponse);
+    }
+    const responseId = initialResponse.id;
+    log(chalk.dim(`API scheduled background response ${responseId} (status=${initialResponse.status ?? 'unknown'}). Monitoring up to ${Math.round(BACKGROUND_MAX_WAIT_MS / 60000)} minutes for completion...`));
+    let heartbeatActive = false;
+    let stopHeartbeat = null;
+    const stopHeartbeatNow = () => {
+        if (!heartbeatActive)
+            return;
+        heartbeatActive = false;
+        stopHeartbeat?.();
+        stopHeartbeat = null;
+    };
+    if (heartbeatIntervalMs && heartbeatIntervalMs > 0) {
+        heartbeatActive = true;
+        stopHeartbeat = startHeartbeat({
+            intervalMs: heartbeatIntervalMs,
+            log: (message) => log(message),
+            isActive: () => heartbeatActive,
+            makeMessage: (elapsedMs) => {
+                const elapsedText = formatElapsed(elapsedMs);
+                return `API background run still in progress — ${elapsedText} elapsed.`;
+            },
+        });
+    }
+    try {
+        return await pollBackgroundResponse({
+            client,
+            responseId,
+            initialResponse,
+            log,
+            wait,
+            now,
+            maxWaitMs,
+        });
+    }
+    finally {
+        stopHeartbeatNow();
+    }
+}
+async function pollBackgroundResponse(params) {
+    const { client, responseId, initialResponse, log, wait, now, maxWaitMs } = params;
+    const startMark = now();
+    let response = initialResponse;
+    let firstCycle = true;
+    let lastStatus = response.status;
+    // biome-ignore lint/nursery/noUnnecessaryConditions: intentional polling loop.
+    while (true) {
+        const status = response.status ?? 'completed';
+        // biome-ignore lint/nursery/noUnnecessaryConditions: firstCycle toggles immediately; keep for clarity in logs.
+        if (firstCycle) {
+            firstCycle = false;
+            log(chalk.dim(`API background response status=${status}. We'll keep retrying automatically.`));
+        }
+        else if (status !== lastStatus && status !== 'completed') {
+            log(chalk.dim(`API background response status=${status}.`));
+        }
+        lastStatus = status;
+        if (status === 'completed') {
+            return response;
+        }
+        if (status !== 'in_progress' && status !== 'queued') {
+            const detail = response.error?.message || response.incomplete_details?.reason || status;
+            throw new OracleResponseError(`Response did not complete: ${detail}`, response);
+        }
+        if (now() - startMark >= maxWaitMs) {
+            throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+        }
+        await wait(BACKGROUND_POLL_INTERVAL_MS);
+        if (now() - startMark >= maxWaitMs) {
+            throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+        }
+        const { response: nextResponse, reconnected } = await retrieveBackgroundResponseWithRetry({
+            client,
+            responseId,
+            wait,
+            now,
+            maxWaitMs,
+            startMark,
+            log,
+        });
+        if (reconnected) {
+            const nextStatus = nextResponse.status ?? 'in_progress';
+            log(chalk.dim(`Reconnected to API background response (status=${nextStatus}). API is still working...`));
+        }
+        response = nextResponse;
+    }
+}
+async function retrieveBackgroundResponseWithRetry(params) {
+    const { client, responseId, wait, now, maxWaitMs, startMark, log } = params;
+    let retries = 0;
+    // biome-ignore lint/nursery/noUnnecessaryConditions: intentional retry loop
+    while (true) {
+        try {
+            const next = await client.responses.retrieve(responseId);
+            return { response: next, reconnected: retries > 0 };
+        }
+        catch (error) {
+            const transportError = asRetryableTransportError(error);
+            if (!transportError) {
+                throw error;
+            }
+            retries += 1;
+            const delay = Math.min(BACKGROUND_RETRY_BASE_MS * 2 ** (retries - 1), BACKGROUND_RETRY_MAX_MS);
+            log(chalk.yellow(`${describeTransportError(transportError, maxWaitMs)} Retrying in ${formatElapsed(delay)}...`));
+            await wait(delay);
+            if (now() - startMark >= maxWaitMs) {
+                throw new OracleTransportError('client-timeout', 'Timed out waiting for API background response to finish.');
+            }
+        }
+    }
+}
+function asRetryableTransportError(error) {
+    if (error instanceof OracleTransportError) {
+        return error;
+    }
+    if (error instanceof APIConnectionError || error instanceof APIConnectionTimeoutError) {
+        return toTransportError(error);
+    }
+    return null;
+}

package/dist/src/oracle/claude.js

@@ -0,0 +1,95 @@
+const DEFAULT_CLAUDE_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+function extractPrompt(body) {
+    const first = body.input?.[0]?.content?.[0];
+    if (first && first.type === 'input_text') {
+        return first.text ?? '';
+    }
+    return '';
+}
+async function callClaude({ apiKey, model, prompt, endpoint, stream = false, }) {
+    const url = endpoint?.trim() || DEFAULT_CLAUDE_ENDPOINT;
+    const payload = {
+        model,
+        max_tokens: 2048,
+        messages: [
+            {
+                role: 'user',
+                content: prompt,
+            },
+        ],
+        stream,
+    };
+    return fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify(payload),
+    });
+}
+async function parseClaudeResponse(raw) {
+    const json = (await raw.json());
+    if (json.error) {
+        throw new Error(json.error.message || 'Claude request failed');
+    }
+    const textParts = json.content?.map((part) => part.text ?? '').filter(Boolean) ?? [];
+    const outputText = textParts.join('');
+    return {
+        id: json.id ?? `claude-${Date.now()}`,
+        status: 'completed',
+        output_text: [outputText],
+        output: [{ type: 'text', text: outputText }],
+        usage: {
+            input_tokens: json.usage?.input_tokens ?? 0,
+            output_tokens: json.usage?.output_tokens ?? 0,
+            total_tokens: (json.usage?.input_tokens ?? 0) + (json.usage?.output_tokens ?? 0),
+        },
+    };
+}
+export function createClaudeClient(apiKey, modelName, resolvedModelId, baseUrl) {
+    const modelId = resolveClaudeModelId(resolvedModelId ?? modelName);
+    const stream = async (body) => {
+        const prompt = extractPrompt(body);
+        const resp = await callClaude({ apiKey, model: modelId, prompt, stream: false, endpoint: baseUrl });
+        const parsed = await parseClaudeResponse(resp);
+        const iterator = async function* () {
+            if (parsed.output_text?.[0]) {
+                yield { type: 'response.output_text.delta', delta: parsed.output_text[0] };
+            }
+            return;
+        };
+        return {
+            [Symbol.asyncIterator]: () => iterator(),
+            finalResponse: async () => parsed,
+        };
+    };
+    const create = async (body) => {
+        const prompt = extractPrompt(body);
+        const resp = await callClaude({ apiKey, model: modelId, prompt, stream: false, endpoint: baseUrl });
+        return parseClaudeResponse(resp);
+    };
+    const retrieve = async (id) => ({
+        id,
+        status: 'error',
+        error: { message: 'Retrieve by ID not supported for Claude API yet.' },
+    });
+    return {
+        responses: {
+            stream,
+            create,
+            retrieve,
+        },
+    };
+}
+export function resolveClaudeModelId(modelName) {
+    if (modelName === 'claude-4.5-sonnet' || modelName === 'claude-sonnet-4-5-20241022') {
+        return 'claude-sonnet-4-5';
+    }
+    if (modelName === 'claude-4.1-opus' || modelName === 'claude-opus-4-1-20240808') {
+        return 'claude-opus-4-1';
+    }
+    return modelName;
+}