@steipete/oracle 1.0.0

package/dist/src/oracle/run.js

@@ -0,0 +1,411 @@
+import chalk from 'chalk';
+import kleur from 'kleur';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { performance } from 'node:perf_hooks';
+import { APIConnectionError, APIConnectionTimeoutError } from 'openai';
+import { DEFAULT_SYSTEM_PROMPT, MODEL_CONFIGS, TOKENIZER_OPTIONS } from './config.js';
+import { readFiles } from './files.js';
+import { buildPrompt, buildRequestBody } from './request.js';
+import { formatElapsed, formatUSD } from './format.js';
+import { getFileTokenStats, printFileTokenStats } from './tokenStats.js';
+import { OracleResponseError, OracleTransportError, PromptValidationError, describeTransportError, toTransportError, } from './errors.js';
+import { createDefaultClientFactory } from './client.js';
+import { startHeartbeat } from '../heartbeat.js';
+import { getCliVersion } from '../version.js';
+import { createFsAdapter } from './fsAdapter.js';
+const isTty = process.stdout.isTTY;
+const dim = (text) => (isTty ? kleur.dim(text) : text);
+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;
+const defaultWait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+export async function runOracle(options, deps = {}) {
+    const { apiKey = options.apiKey ?? process.env.OPENAI_API_KEY, cwd = process.cwd(), fs: fsModule = createFsAdapter(fs), log = console.log, write = (text) => process.stdout.write(text), now = () => performance.now(), clientFactory = createDefaultClientFactory(), client, wait = defaultWait, } = deps;
+    const logVerbose = (message) => {
+        if (options.verbose) {
+            log(dim(`[verbose] ${message}`));
+        }
+    };
+    const previewMode = resolvePreviewMode(options.previewMode ?? options.preview);
+    const isPreview = Boolean(previewMode);
+    if (!apiKey) {
+        throw new PromptValidationError('Missing OPENAI_API_KEY. Set it via the environment or a .env file.', {
+            env: 'OPENAI_API_KEY',
+        });
+    }
+    const modelConfig = MODEL_CONFIGS[options.model];
+    if (!modelConfig) {
+        throw new PromptValidationError(`Unsupported model "${options.model}". Choose one of: ${Object.keys(MODEL_CONFIGS).join(', ')}`, { model: options.model });
+    }
+    const useBackground = options.background ?? (options.model === 'gpt-5-pro');
+    const inputTokenBudget = options.maxInput ?? modelConfig.inputLimit;
+    const files = await readFiles(options.file ?? [], { cwd, fsModule });
+    const searchEnabled = options.search !== false;
+    logVerbose(`cwd: ${cwd}`);
+    if (files.length > 0) {
+        const displayPaths = files
+            .map((file) => path.relative(cwd, file.path) || file.path)
+            .slice(0, 10)
+            .join(', ');
+        const extra = files.length > 10 ? ` (+${files.length - 10} more)` : '';
+        logVerbose(`Attached files (${files.length}): ${displayPaths}${extra}`);
+    }
+    else {
+        logVerbose('No files attached.');
+    }
+    const fileTokenInfo = getFileTokenStats(files, {
+        cwd,
+        tokenizer: modelConfig.tokenizer,
+        tokenizerOptions: TOKENIZER_OPTIONS,
+        inputTokenBudget,
+    });
+    const totalFileTokens = fileTokenInfo.totalTokens;
+    logVerbose(`Attached files use ${totalFileTokens.toLocaleString()} tokens`);
+    const systemPrompt = options.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const promptWithFiles = buildPrompt(options.prompt, files, cwd);
+    const tokenizerInput = [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: promptWithFiles },
+    ];
+    const estimatedInputTokens = modelConfig.tokenizer(tokenizerInput, TOKENIZER_OPTIONS);
+    logVerbose(`Estimated tokens (prompt + files): ${estimatedInputTokens.toLocaleString()}`);
+    const fileCount = files.length;
+    const cliVersion = getCliVersion();
+    const headerLine = `Oracle (${cliVersion}) consulting ${modelConfig.model}'s crystal ball with ${estimatedInputTokens.toLocaleString()} tokens and ${fileCount} files...`;
+    const shouldReportFiles = (options.filesReport || fileTokenInfo.totalTokens > inputTokenBudget) && fileTokenInfo.stats.length > 0;
+    if (!isPreview) {
+        log(headerLine);
+        if (options.model === 'gpt-5-pro') {
+            log(dim('Pro is thinking, this can take up to 30 minutes...'));
+        }
+        log(dim('Press Ctrl+C to cancel.'));
+    }
+    if (shouldReportFiles) {
+        printFileTokenStats(fileTokenInfo, { inputTokenBudget, log });
+    }
+    if (estimatedInputTokens > inputTokenBudget) {
+        throw new PromptValidationError(`Input too large (${estimatedInputTokens.toLocaleString()} tokens). Limit is ${inputTokenBudget.toLocaleString()} tokens.`, { estimatedInputTokens, inputTokenBudget });
+    }
+    const requestBody = buildRequestBody({
+        modelConfig,
+        systemPrompt,
+        userPrompt: promptWithFiles,
+        searchEnabled,
+        maxOutputTokens: options.maxOutput,
+        background: useBackground,
+        storeResponse: useBackground,
+    });
+    if (isPreview && previewMode) {
+        if (previewMode === 'json' || previewMode === 'full') {
+            log('Request JSON');
+            log(JSON.stringify(requestBody, null, 2));
+            log('');
+        }
+        if (previewMode === 'full') {
+            log('Assembled Prompt');
+            log(promptWithFiles);
+            log('');
+        }
+        log(`Estimated input tokens: ${estimatedInputTokens.toLocaleString()} / ${inputTokenBudget.toLocaleString()} (model: ${modelConfig.model})`);
+        return {
+            mode: 'preview',
+            previewMode,
+            requestBody,
+            estimatedInputTokens,
+            inputTokenBudget,
+        };
+    }
+    const openAiClient = client ?? clientFactory(apiKey);
+    logVerbose('Dispatching request to OpenAI Responses API...');
+    const runStart = now();
+    let response = null;
+    let elapsedMs = 0;
+    let sawTextDelta = false;
+    let answerHeaderPrinted = false;
+    const ensureAnswerHeader = () => {
+        if (!options.silent && !answerHeaderPrinted) {
+            log(chalk.bold('Answer:'));
+            answerHeaderPrinted = true;
+        }
+    };
+    if (useBackground) {
+        response = await executeBackgroundResponse({
+            client: openAiClient,
+            requestBody,
+            log,
+            wait,
+            heartbeatIntervalMs: options.heartbeatIntervalMs,
+            now,
+        });
+        elapsedMs = now() - runStart;
+    }
+    else {
+        const stream = await openAiClient.responses.stream(requestBody);
+        let heartbeatActive = false;
+        let stopHeartbeat = null;
+        const stopHeartbeatNow = () => {
+            if (!heartbeatActive) {
+                return;
+            }
+            heartbeatActive = false;
+            stopHeartbeat?.();
+            stopHeartbeat = null;
+        };
+        if (options.heartbeatIntervalMs && options.heartbeatIntervalMs > 0) {
+            heartbeatActive = true;
+            stopHeartbeat = startHeartbeat({
+                intervalMs: options.heartbeatIntervalMs,
+                log: (message) => log(message),
+                isActive: () => heartbeatActive,
+                makeMessage: (elapsedMs) => {
+                    const elapsedText = formatElapsed(elapsedMs);
+                    return `API connection active — ${elapsedText} elapsed. Expect up to ~10 min before GPT-5 responds.`;
+                },
+            });
+        }
+        try {
+            for await (const event of stream) {
+                if (event.type === 'response.output_text.delta') {
+                    stopHeartbeatNow();
+                    sawTextDelta = true;
+                    ensureAnswerHeader();
+                    if (!options.silent && typeof event.delta === 'string') {
+                        write(event.delta);
+                    }
+                }
+            }
+        }
+        catch (streamError) {
+            if (typeof stream.abort === 'function') {
+                stream.abort();
+            }
+            stopHeartbeatNow();
+            const transportError = toTransportError(streamError);
+            log(chalk.yellow(describeTransportError(transportError)));
+            throw transportError;
+        }
+        response = await stream.finalResponse();
+        stopHeartbeatNow();
+        elapsedMs = now() - runStart;
+    }
+    if (!response) {
+        throw new Error('OpenAI did not return a response.');
+    }
+    logVerbose(`Response status: ${response.status ?? 'completed'}`);
+    if (response.status && response.status !== 'completed') {
+        const detail = response.error?.message || response.incomplete_details?.reason || response.status;
+        log(chalk.yellow(`OpenAI ended the run early (status=${response.status}${response.incomplete_details?.reason ? `, reason=${response.incomplete_details.reason}` : ''}).`));
+        throw new OracleResponseError(`Response did not complete: ${detail}`, response);
+    }
+    const answerText = extractTextOutput(response);
+    if (!options.silent) {
+        // biome-ignore lint/nursery/noUnnecessaryConditions: flips true when streaming events arrive
+        if (sawTextDelta) {
+            write('\n\n');
+        }
+        else {
+            ensureAnswerHeader();
+            log(answerText || chalk.dim('(no text output)'));
+            log('');
+        }
+    }
+    const usage = response.usage ?? {};
+    const inputTokens = usage.input_tokens ?? estimatedInputTokens;
+    const outputTokens = usage.output_tokens ?? 0;
+    const reasoningTokens = usage.reasoning_tokens ?? 0;
+    const totalTokens = usage.total_tokens ?? inputTokens + outputTokens + reasoningTokens;
+    const cost = inputTokens * modelConfig.pricing.inputPerToken + outputTokens * modelConfig.pricing.outputPerToken;
+    const elapsedDisplay = formatElapsed(elapsedMs);
+    const statsParts = [];
+    const modelLabel = modelConfig.model + (modelConfig.reasoning ? '[high]' : '');
+    statsParts.push(modelLabel);
+    statsParts.push(formatUSD(cost));
+    const tokensDisplay = [inputTokens, outputTokens, reasoningTokens, totalTokens]
+        .map((value, index) => formatTokenValue(value, usage, index))
+        .join('/');
+    statsParts.push(`tok(i/o/r/t)=${tokensDisplay}`);
+    if (!searchEnabled) {
+        statsParts.push('search=off');
+    }
+    if (files.length > 0) {
+        statsParts.push(`files=${files.length}`);
+    }
+    log(chalk.blue(`Finished in ${elapsedDisplay} (${statsParts.join(' | ')})`));
+    return {
+        mode: 'live',
+        response,
+        usage: { inputTokens, outputTokens, reasoningTokens, totalTokens },
+        elapsedMs,
+    };
+}
+function formatTokenValue(value, usage, index) {
+    const estimatedFlag = (index === 0 && usage?.input_tokens == null) ||
+        (index === 1 && usage?.output_tokens == null) ||
+        (index === 2 && usage?.reasoning_tokens == null) ||
+        (index === 3 && usage?.total_tokens == null);
+    const text = value.toLocaleString();
+    return estimatedFlag ? `${text}*` : text;
+}
+function resolvePreviewMode(value) {
+    const allowed = new Set(['summary', 'json', 'full']);
+    if (typeof value === 'string' && value.length > 0) {
+        return allowed.has(value) ? value : 'summary';
+    }
+    if (value) {
+        return 'summary';
+    }
+    return undefined;
+}
+export function extractTextOutput(response) {
+    if (Array.isArray(response.output_text) && response.output_text.length > 0) {
+        return response.output_text.join('\n');
+    }
+    if (Array.isArray(response.output)) {
+        const segments = [];
+        for (const item of response.output) {
+            if (Array.isArray(item.content)) {
+                for (const chunk of item.content) {
+                    if (chunk && (chunk.type === 'output_text' || chunk.type === 'text') && chunk.text) {
+                        segments.push(chunk.text);
+                    }
+                }
+            }
+            else if (typeof item.text === 'string') {
+                segments.push(item.text);
+            }
+        }
+        return segments.join('\n');
+    }
+    return '';
+}
+async function executeBackgroundResponse(params) {
+    const { client, requestBody, log, wait, heartbeatIntervalMs, now } = params;
+    const initialResponse = await client.responses.create(requestBody);
+    if (!initialResponse || !initialResponse.id) {
+        throw new OracleResponseError('OpenAI did not return a response ID for the background run.', initialResponse);
+    }
+    const responseId = initialResponse.id;
+    log(dim(`OpenAI 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 `OpenAI background run still in progress — ${elapsedText} elapsed (id=${responseId}).`;
+            },
+        });
+    }
+    try {
+        return await pollBackgroundResponse({
+            client,
+            responseId,
+            initialResponse,
+            log,
+            wait,
+            now,
+            maxWaitMs: BACKGROUND_MAX_WAIT_MS,
+        });
+    }
+    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: guard only for first iteration
+        if (firstCycle) {
+            firstCycle = false;
+            log(dim(`OpenAI background response status=${status}. We'll keep retrying automatically.`));
+        }
+        else if (status !== lastStatus && status !== 'completed') {
+            log(dim(`OpenAI 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 OpenAI background response to finish.');
+        }
+        await wait(BACKGROUND_POLL_INTERVAL_MS);
+        if (now() - startMark >= maxWaitMs) {
+            throw new OracleTransportError('client-timeout', 'Timed out waiting for OpenAI 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(dim(`Reconnected to OpenAI background response (status=${nextStatus}). OpenAI 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)} Retrying in ${formatElapsed(delay)}...`));
+            await wait(delay);
+            if (now() - startMark >= maxWaitMs) {
+                throw new OracleTransportError('client-timeout', 'Timed out waiting for OpenAI 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/tokenStats.js

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+import { createFileSections } from './files.js';
+export function getFileTokenStats(files, { cwd = process.cwd(), tokenizer, tokenizerOptions, inputTokenBudget, }) {
+    if (!files.length) {
+        return { stats: [], totalTokens: 0 };
+    }
+    const sections = createFileSections(files, cwd);
+    const stats = sections
+        .map((section) => {
+        const tokens = tokenizer(section.sectionText, tokenizerOptions);
+        const percent = inputTokenBudget ? (tokens / inputTokenBudget) * 100 : undefined;
+        return {
+            path: section.absolutePath,
+            displayPath: section.displayPath,
+            tokens,
+            percent,
+        };
+    })
+        .sort((a, b) => b.tokens - a.tokens);
+    const totalTokens = stats.reduce((sum, entry) => sum + entry.tokens, 0);
+    return { stats, totalTokens };
+}
+export function printFileTokenStats({ stats, totalTokens }, { inputTokenBudget, log = console.log }) {
+    if (!stats.length) {
+        return;
+    }
+    log(chalk.bold('File Token Usage'));
+    for (const entry of stats) {
+        const percentLabel = inputTokenBudget && entry.percent != null ? `${entry.percent.toFixed(2)}%` : 'n/a';
+        log(`${entry.tokens.toLocaleString().padStart(10)}  ${percentLabel.padStart(8)}  ${entry.displayPath}`);
+    }
+    if (inputTokenBudget) {
+        const totalPercent = (totalTokens / inputTokenBudget) * 100;
+        log(`Total: ${totalTokens.toLocaleString()} tokens (${totalPercent.toFixed(2)}% of ${inputTokenBudget.toLocaleString()})`);
+    }
+    else {
+        log(`Total: ${totalTokens.toLocaleString()} tokens`);
+    }
+}

package/dist/src/oracle/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/oracle.js

@@ -0,0 +1,9 @@
+export * from './oracle/types.js';
+export { MODEL_CONFIGS, DEFAULT_SYSTEM_PROMPT, TOKENIZER_OPTIONS, } from './oracle/config.js';
+export { readFiles, createFileSections } from './oracle/files.js';
+export { buildPrompt, buildRequestBody, renderPromptMarkdown } from './oracle/request.js';
+export { formatUSD, formatNumber, formatElapsed } from './oracle/format.js';
+export { getFileTokenStats, printFileTokenStats } from './oracle/tokenStats.js';
+export { OracleResponseError, OracleTransportError, OracleUserError, FileValidationError, BrowserAutomationError, PromptValidationError, describeTransportError, extractResponseMetadata, asOracleUserError, toTransportError, } from './oracle/errors.js';
+export { createDefaultClientFactory } from './oracle/client.js';
+export { runOracle, extractTextOutput } from './oracle/run.js';

package/dist/src/sessionManager.js

@@ -0,0 +1,205 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+const ORACLE_HOME = process.env.ORACLE_HOME_DIR ?? path.join(os.homedir(), '.oracle');
+const SESSIONS_DIR = path.join(ORACLE_HOME, 'sessions');
+const MAX_STATUS_LIMIT = 1000;
+const DEFAULT_SLUG = 'session';
+const MAX_SLUG_WORDS = 5;
+const MIN_CUSTOM_SLUG_WORDS = 3;
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+export async function ensureSessionStorage() {
+    await ensureDir(SESSIONS_DIR);
+}
+function slugify(text, maxWords = MAX_SLUG_WORDS) {
+    const normalized = text?.toLowerCase() ?? '';
+    const words = normalized.match(/[a-z0-9]+/g) ?? [];
+    const trimmed = words.slice(0, maxWords);
+    return trimmed.length > 0 ? trimmed.join('-') : DEFAULT_SLUG;
+}
+function countSlugWords(slug) {
+    return slug.split('-').filter(Boolean).length;
+}
+function normalizeCustomSlug(candidate) {
+    const slug = slugify(candidate, MAX_SLUG_WORDS);
+    const wordCount = countSlugWords(slug);
+    if (wordCount < MIN_CUSTOM_SLUG_WORDS || wordCount > MAX_SLUG_WORDS) {
+        throw new Error(`Custom slug must include between ${MIN_CUSTOM_SLUG_WORDS} and ${MAX_SLUG_WORDS} words.`);
+    }
+    return slug;
+}
+export function createSessionId(prompt, customSlug) {
+    if (customSlug) {
+        return normalizeCustomSlug(customSlug);
+    }
+    return slugify(prompt);
+}
+function sessionDir(id) {
+    return path.join(SESSIONS_DIR, id);
+}
+function metaPath(id) {
+    return path.join(sessionDir(id), 'session.json');
+}
+function logPath(id) {
+    return path.join(sessionDir(id), 'output.log');
+}
+function requestPath(id) {
+    return path.join(sessionDir(id), 'request.json');
+}
+async function fileExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureUniqueSessionId(baseSlug) {
+    let candidate = baseSlug;
+    let suffix = 2;
+    while (await fileExists(sessionDir(candidate))) {
+        candidate = `${baseSlug}-${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+export async function initializeSession(options, cwd) {
+    await ensureSessionStorage();
+    const baseSlug = createSessionId(options.prompt || DEFAULT_SLUG, options.slug);
+    const sessionId = await ensureUniqueSessionId(baseSlug);
+    const dir = sessionDir(sessionId);
+    await ensureDir(dir);
+    const mode = options.mode ?? 'api';
+    const browserConfig = options.browserConfig;
+    const metadata = {
+        id: sessionId,
+        createdAt: new Date().toISOString(),
+        status: 'pending',
+        promptPreview: (options.prompt || '').slice(0, 160),
+        model: options.model,
+        cwd,
+        mode,
+        browser: browserConfig ? { config: browserConfig } : undefined,
+        options: {
+            prompt: options.prompt,
+            file: options.file ?? [],
+            model: options.model,
+            maxInput: options.maxInput,
+            system: options.system,
+            maxOutput: options.maxOutput,
+            silent: options.silent,
+            filesReport: options.filesReport,
+            slug: sessionId,
+            mode,
+            browserConfig,
+            verbose: options.verbose,
+            heartbeatIntervalMs: options.heartbeatIntervalMs,
+            browserInlineFiles: options.browserInlineFiles,
+            background: options.background,
+        },
+    };
+    await fs.writeFile(metaPath(sessionId), JSON.stringify(metadata, null, 2), 'utf8');
+    await fs.writeFile(requestPath(sessionId), JSON.stringify(metadata.options, null, 2), 'utf8');
+    await fs.writeFile(logPath(sessionId), '', 'utf8');
+    return metadata;
+}
+export async function readSessionMetadata(sessionId) {
+    try {
+        const raw = await fs.readFile(metaPath(sessionId), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function updateSessionMetadata(sessionId, updates) {
+    const existing = (await readSessionMetadata(sessionId)) ?? { id: sessionId };
+    const next = { ...existing, ...updates };
+    await fs.writeFile(metaPath(sessionId), JSON.stringify(next, null, 2), 'utf8');
+    return next;
+}
+export function createSessionLogWriter(sessionId) {
+    const stream = createWriteStream(logPath(sessionId), { flags: 'a' });
+    const logLine = (line = '') => {
+        stream.write(`${line}\n`);
+    };
+    const writeChunk = (chunk) => {
+        stream.write(chunk);
+        return true;
+    };
+    return { stream, logLine, writeChunk, logPath: logPath(sessionId) };
+}
+export async function listSessionsMetadata() {
+    await ensureSessionStorage();
+    const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
+    const metas = [];
+    for (const entry of entries) {
+        const meta = await readSessionMetadata(entry);
+        if (meta) {
+            metas.push(meta);
+        }
+    }
+    return metas.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+}
+export function filterSessionsByRange(metas, { hours = 24, includeAll = false, limit = 100 }) {
+    const maxLimit = Math.min(limit, MAX_STATUS_LIMIT);
+    let filtered = metas;
+    if (!includeAll) {
+        const cutoff = Date.now() - hours * 60 * 60 * 1000;
+        filtered = metas.filter((meta) => new Date(meta.createdAt).getTime() >= cutoff);
+    }
+    const limited = filtered.slice(0, maxLimit);
+    const truncated = filtered.length > maxLimit;
+    return { entries: limited, truncated, total: filtered.length };
+}
+export async function readSessionLog(sessionId) {
+    try {
+        return await fs.readFile(logPath(sessionId), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export async function deleteSessionsOlderThan({ hours = 24, includeAll = false, } = {}) {
+    await ensureSessionStorage();
+    const entries = await fs.readdir(SESSIONS_DIR).catch(() => []);
+    if (!entries.length) {
+        return { deleted: 0, remaining: 0 };
+    }
+    const cutoff = includeAll ? Number.NEGATIVE_INFINITY : Date.now() - hours * 60 * 60 * 1000;
+    let deleted = 0;
+    for (const entry of entries) {
+        const dir = sessionDir(entry);
+        let createdMs;
+        const meta = await readSessionMetadata(entry);
+        if (meta?.createdAt) {
+            const parsed = Date.parse(meta.createdAt);
+            if (!Number.isNaN(parsed)) {
+                createdMs = parsed;
+            }
+        }
+        if (createdMs == null) {
+            try {
+                const stats = await fs.stat(dir);
+                createdMs = stats.birthtimeMs || stats.mtimeMs;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (includeAll || (createdMs != null && createdMs < cutoff)) {
+            await fs.rm(dir, { recursive: true, force: true });
+            deleted += 1;
+        }
+    }
+    const remaining = Math.max(entries.length - deleted, 0);
+    return { deleted, remaining };
+}
+export async function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export { ORACLE_HOME, SESSIONS_DIR, MAX_STATUS_LIMIT };