@steipete/oracle 0.4.0

package/dist/src/oracle/client.js

@@ -0,0 +1,87 @@
+import OpenAI, { AzureOpenAI } from 'openai';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { createGeminiClient } from './gemini.js';
+import { createClaudeClient } from './claude.js';
+export function createDefaultClientFactory() {
+    const customFactory = loadCustomClientFactory();
+    if (customFactory)
+        return customFactory;
+    return (key, options) => {
+        if (options?.model?.startsWith('gemini')) {
+            // Gemini client uses its own SDK; allow passing the already-resolved id for transparency/logging.
+            return createGeminiClient(key, options.model, options.resolvedModelId);
+        }
+        if (options?.model?.startsWith('claude')) {
+            return createClaudeClient(key, options.model, options.resolvedModelId, options.baseUrl);
+        }
+        let instance;
+        if (options?.azure?.endpoint) {
+            instance = new AzureOpenAI({
+                apiKey: key,
+                endpoint: options.azure.endpoint,
+                apiVersion: options.azure.apiVersion,
+                deployment: options.azure.deployment,
+                timeout: 20 * 60 * 1000,
+            });
+        }
+        else {
+            instance = new OpenAI({
+                apiKey: key,
+                timeout: 20 * 60 * 1000,
+                baseURL: options?.baseUrl,
+            });
+        }
+        return {
+            responses: {
+                stream: (body) => instance.responses.stream(body),
+                create: (body) => instance.responses.create(body),
+                retrieve: (id) => instance.responses.retrieve(id),
+            },
+        };
+    };
+}
+function loadCustomClientFactory() {
+    const override = process.env.ORACLE_CLIENT_FACTORY;
+    if (!override) {
+        return null;
+    }
+    if (override === 'INLINE_TEST_FACTORY') {
+        return () => ({
+            responses: {
+                create: async () => ({ id: 'inline-test', status: 'completed' }),
+                stream: async () => ({
+                    [Symbol.asyncIterator]: () => ({
+                        async next() {
+                            return { done: true, value: undefined };
+                        },
+                    }),
+                    finalResponse: async () => ({ id: 'inline-test', status: 'completed' }),
+                }),
+                retrieve: async (id) => ({ id, status: 'completed' }),
+            },
+        });
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const resolved = path.isAbsolute(override) ? override : path.resolve(process.cwd(), override);
+        const moduleExports = require(resolved);
+        const factory = typeof moduleExports === 'function'
+            ? moduleExports
+            : typeof moduleExports?.default === 'function'
+                ? moduleExports.default
+                : typeof moduleExports?.createClientFactory === 'function'
+                    ? moduleExports.createClientFactory
+                    : null;
+        if (typeof factory === 'function') {
+            return factory;
+        }
+        console.warn(`Custom client factory at ${resolved} did not export a function.`);
+    }
+    catch (error) {
+        console.warn(`Failed to load ORACLE_CLIENT_FACTORY module "${override}":`, error);
+    }
+    return null;
+}
+// Exposed for tests
+export { loadCustomClientFactory as __loadCustomClientFactory };

package/dist/src/oracle/config.js

@@ -0,0 +1,92 @@
+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 { stringifyTokenizerInput } from './tokenStringifier.js';
+export const DEFAULT_MODEL = 'gpt-5.1-pro';
+export const PRO_MODELS = new Set(['gpt-5.1-pro', 'gpt-5-pro', 'claude-4.1-opus']);
+const countTokensAnthropic = (input) => countTokensAnthropicRaw(stringifyTokenizerInput(input));
+export const MODEL_CONFIGS = {
+    'gpt-5.1-pro': {
+        model: 'gpt-5.1-pro',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 120 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5-pro': {
+        model: 'gpt-5-pro',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 120 / 1_000_000,
+        },
+        reasoning: null,
+    },
+    'gpt-5.1': {
+        model: 'gpt-5.1',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.25 / 1_000_000,
+            outputPerToken: 10 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+    },
+    'gpt-5.1-codex': {
+        model: 'gpt-5.1-codex',
+        tokenizer: countTokensGpt5,
+        inputLimit: 196000,
+        pricing: {
+            inputPerToken: 1.25 / 1_000_000,
+            outputPerToken: 10 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+    },
+    'gemini-3-pro': {
+        model: 'gemini-3-pro',
+        tokenizer: countTokensGpt5Pro,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 2 / 1_000_000,
+            outputPerToken: 12 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: true,
+    },
+    'claude-4.5-sonnet': {
+        model: 'claude-4.5-sonnet',
+        apiModel: 'claude-sonnet-4-5',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 3 / 1_000_000,
+            outputPerToken: 15 / 1_000_000,
+        },
+        reasoning: null,
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+    'claude-4.1-opus': {
+        model: 'claude-4.1-opus',
+        apiModel: 'claude-opus-4-1',
+        tokenizer: countTokensAnthropic,
+        inputLimit: 200000,
+        pricing: {
+            inputPerToken: 15 / 1_000_000,
+            outputPerToken: 75 / 1_000_000,
+        },
+        reasoning: { effort: 'high' },
+        supportsBackground: false,
+        supportsSearch: false,
+    },
+};
+export const DEFAULT_SYSTEM_PROMPT = [
+    'You are Oracle, a focused one-shot problem solver.',
+    'Emphasize direct answers, cite any files referenced, and clearly note when the search tool was used.',
+].join(' ');
+export const TOKENIZER_OPTIONS = { allowedSpecial: 'all' };

package/dist/src/oracle/errors.js

@@ -0,0 +1,104 @@
+import { APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, } from 'openai';
+import { formatElapsed } from './format.js';
+export class OracleUserError extends Error {
+    category;
+    details;
+    constructor(category, message, details, cause) {
+        super(message);
+        this.name = 'OracleUserError';
+        this.category = category;
+        this.details = details;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+export class FileValidationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('file-validation', message, details, cause);
+        this.name = 'FileValidationError';
+    }
+}
+export class BrowserAutomationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('browser-automation', message, details, cause);
+        this.name = 'BrowserAutomationError';
+    }
+}
+export class PromptValidationError extends OracleUserError {
+    constructor(message, details, cause) {
+        super('prompt-validation', message, details, cause);
+        this.name = 'PromptValidationError';
+    }
+}
+export function asOracleUserError(error) {
+    if (error instanceof OracleUserError) {
+        return error;
+    }
+    return null;
+}
+export class OracleTransportError extends Error {
+    reason;
+    constructor(reason, message, cause) {
+        super(message);
+        this.name = 'OracleTransportError';
+        this.reason = reason;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+export class OracleResponseError extends Error {
+    metadata;
+    response;
+    constructor(message, response) {
+        super(message);
+        this.name = 'OracleResponseError';
+        this.response = response;
+        this.metadata = extractResponseMetadata(response);
+    }
+}
+export function extractResponseMetadata(response) {
+    if (!response) {
+        return {};
+    }
+    const metadata = {
+        responseId: response.id,
+        status: response.status,
+        incompleteReason: response.incomplete_details?.reason ?? undefined,
+    };
+    const requestId = response._request_id;
+    if (requestId !== undefined) {
+        metadata.requestId = requestId;
+    }
+    return metadata;
+}
+export function toTransportError(error) {
+    if (error instanceof OracleTransportError) {
+        return error;
+    }
+    if (error instanceof APIConnectionTimeoutError) {
+        return new OracleTransportError('client-timeout', 'OpenAI request timed out before completion.', error);
+    }
+    if (error instanceof APIUserAbortError) {
+        return new OracleTransportError('client-abort', 'The request was aborted before OpenAI finished responding.', error);
+    }
+    if (error instanceof APIConnectionError) {
+        return new OracleTransportError('connection-lost', 'Connection to OpenAI dropped before the response completed.', error);
+    }
+    return new OracleTransportError('unknown', error instanceof Error ? error.message : 'Unknown transport failure.', error);
+}
+export function describeTransportError(error, deadlineMs) {
+    switch (error.reason) {
+        case 'client-timeout':
+            return deadlineMs
+                ? `Client-side timeout: OpenAI streaming call exceeded the ${formatElapsed(deadlineMs)} deadline.`
+                : 'Client-side timeout: OpenAI streaming call exceeded the configured deadline.';
+        case 'connection-lost':
+            return 'Connection to OpenAI ended unexpectedly before the response completed.';
+        case 'client-abort':
+            return 'Request was aborted before OpenAI completed the response.';
+        default:
+            return 'OpenAI streaming call ended with an unknown transport error.';
+    }
+}

package/dist/src/oracle/files.js

@@ -0,0 +1,371 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import fg from 'fast-glob';
+import { FileValidationError } from './errors.js';
+const MAX_FILE_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB
+const DEFAULT_FS = fs;
+const DEFAULT_IGNORED_DIRS = ['node_modules', 'dist', 'coverage', '.git', '.turbo', '.next', 'build', 'tmp'];
+export async function readFiles(filePaths, { cwd = process.cwd(), fsModule = DEFAULT_FS, maxFileSizeBytes = MAX_FILE_SIZE_BYTES } = {}) {
+    if (!filePaths || filePaths.length === 0) {
+        return [];
+    }
+    const partitioned = await partitionFileInputs(filePaths, cwd, fsModule);
+    const useNativeFilesystem = fsModule === DEFAULT_FS || isNativeFsModule(fsModule);
+    let candidatePaths = [];
+    if (useNativeFilesystem) {
+        candidatePaths = await expandWithNativeGlob(partitioned, cwd);
+    }
+    else {
+        if (partitioned.globPatterns.length > 0 || partitioned.excludePatterns.length > 0) {
+            throw new Error('Glob patterns and exclusions are only supported for on-disk files.');
+        }
+        candidatePaths = await expandWithCustomFs(partitioned, fsModule);
+    }
+    const allowedLiteralDirs = partitioned.literalDirectories
+        .map((dir) => path.resolve(dir))
+        .filter((dir) => DEFAULT_IGNORED_DIRS.includes(path.basename(dir)));
+    const allowedLiteralFiles = partitioned.literalFiles.map((file) => path.resolve(file));
+    const resolvedLiteralDirs = new Set(allowedLiteralDirs);
+    const allowedPaths = new Set([...allowedLiteralDirs, ...allowedLiteralFiles]);
+    const ignoredWhitelist = await buildIgnoredWhitelist(candidatePaths, cwd, fsModule);
+    const ignoredLog = new Set();
+    const filteredCandidates = candidatePaths.filter((filePath) => {
+        const ignoredDir = findIgnoredAncestor(filePath, cwd, resolvedLiteralDirs, allowedPaths, ignoredWhitelist);
+        if (!ignoredDir) {
+            return true;
+        }
+        const displayFile = relativePath(filePath, cwd);
+        const key = `${ignoredDir}|${displayFile}`;
+        if (!ignoredLog.has(key)) {
+            console.log(`Skipping default-ignored path: ${displayFile} (matches ${ignoredDir})`);
+            ignoredLog.add(key);
+        }
+        return false;
+    });
+    if (filteredCandidates.length === 0) {
+        throw new FileValidationError('No files matched the provided --file patterns.', {
+            patterns: partitioned.globPatterns,
+            excludes: partitioned.excludePatterns,
+        });
+    }
+    const oversized = [];
+    const accepted = [];
+    for (const filePath of filteredCandidates) {
+        let stats;
+        try {
+            stats = await fsModule.stat(filePath);
+        }
+        catch (error) {
+            throw new FileValidationError(`Missing file or directory: ${relativePath(filePath, cwd)}`, { path: filePath }, error);
+        }
+        if (!stats.isFile()) {
+            continue;
+        }
+        if (maxFileSizeBytes && typeof stats.size === 'number' && stats.size > maxFileSizeBytes) {
+            const relative = path.relative(cwd, filePath) || filePath;
+            oversized.push(`${relative} (${formatBytes(stats.size)})`);
+            continue;
+        }
+        accepted.push(filePath);
+    }
+    if (oversized.length > 0) {
+        throw new FileValidationError(`The following files exceed the 1 MB limit:\n- ${oversized.join('\n- ')}`, {
+            files: oversized,
+            limitBytes: maxFileSizeBytes,
+        });
+    }
+    const files = [];
+    for (const filePath of accepted) {
+        const content = await fsModule.readFile(filePath, 'utf8');
+        files.push({ path: filePath, content });
+    }
+    return files;
+}
+async function partitionFileInputs(rawPaths, cwd, fsModule) {
+    const result = {
+        globPatterns: [],
+        excludePatterns: [],
+        literalFiles: [],
+        literalDirectories: [],
+    };
+    for (const entry of rawPaths) {
+        const raw = entry?.trim();
+        if (!raw) {
+            continue;
+        }
+        if (raw.startsWith('!')) {
+            const normalized = normalizeGlob(raw.slice(1), cwd);
+            if (normalized) {
+                result.excludePatterns.push(normalized);
+            }
+            continue;
+        }
+        if (fg.isDynamicPattern(raw)) {
+            result.globPatterns.push(normalizeGlob(raw, cwd));
+            continue;
+        }
+        const absolutePath = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+        let stats;
+        try {
+            stats = await fsModule.stat(absolutePath);
+        }
+        catch (error) {
+            throw new FileValidationError(`Missing file or directory: ${raw}`, { path: absolutePath }, error);
+        }
+        if (stats.isDirectory()) {
+            result.literalDirectories.push(absolutePath);
+        }
+        else if (stats.isFile()) {
+            result.literalFiles.push(absolutePath);
+        }
+        else {
+            throw new FileValidationError(`Not a file or directory: ${raw}`, { path: absolutePath });
+        }
+    }
+    return result;
+}
+async function expandWithNativeGlob(partitioned, cwd) {
+    const patterns = [
+        ...partitioned.globPatterns,
+        ...partitioned.literalFiles.map((absPath) => toPosixRelativeOrBasename(absPath, cwd)),
+        ...partitioned.literalDirectories.map((absDir) => makeDirectoryPattern(toPosixRelative(absDir, cwd))),
+    ].filter(Boolean);
+    if (patterns.length === 0) {
+        return [];
+    }
+    const dotfileOptIn = patterns.some((pattern) => includesDotfileSegment(pattern));
+    const gitignoreSets = await loadGitignoreSets(cwd);
+    const matches = (await fg(patterns, {
+        cwd,
+        absolute: false,
+        dot: true,
+        ignore: partitioned.excludePatterns,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        suppressErrors: true,
+    }));
+    const resolved = matches.map((match) => path.resolve(cwd, match));
+    const filtered = resolved.filter((filePath) => !isGitignored(filePath, gitignoreSets));
+    const finalFiles = dotfileOptIn ? filtered : filtered.filter((filePath) => !path.basename(filePath).startsWith('.'));
+    return Array.from(new Set(finalFiles));
+}
+async function loadGitignoreSets(cwd) {
+    const gitignorePaths = await fg('**/.gitignore', {
+        cwd,
+        dot: true,
+        absolute: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        suppressErrors: true,
+    });
+    const sets = [];
+    for (const filePath of gitignorePaths) {
+        try {
+            const raw = await fs.readFile(filePath, 'utf8');
+            const patterns = raw
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0 && !line.startsWith('#'));
+            if (patterns.length > 0) {
+                sets.push({ dir: path.dirname(filePath), patterns });
+            }
+        }
+        catch {
+            // Ignore unreadable .gitignore files
+        }
+    }
+    // Ensure deterministic parent-before-child ordering
+    return sets.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+function isGitignored(filePath, sets) {
+    for (const { dir, patterns } of sets) {
+        if (!filePath.startsWith(dir)) {
+            continue;
+        }
+        const relative = path.relative(dir, filePath) || path.basename(filePath);
+        if (matchesAny(relative, patterns)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function buildIgnoredWhitelist(filePaths, cwd, fsModule) {
+    const whitelist = new Set();
+    for (const filePath of filePaths) {
+        const absolute = path.resolve(filePath);
+        const rel = path.relative(cwd, absolute);
+        const parts = rel.split(path.sep).filter(Boolean);
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            const part = parts[i];
+            if (!DEFAULT_IGNORED_DIRS.includes(part)) {
+                continue;
+            }
+            const dirPath = path.resolve(cwd, ...parts.slice(0, i + 1));
+            if (whitelist.has(dirPath)) {
+                continue;
+            }
+            try {
+                const stats = await fsModule.stat(path.join(dirPath, '.gitignore'));
+                if (stats.isFile()) {
+                    whitelist.add(dirPath);
+                }
+            }
+            catch {
+                // no .gitignore at this level; keep ignored
+            }
+        }
+    }
+    return whitelist;
+}
+function findIgnoredAncestor(filePath, cwd, _literalDirs, allowedPaths, ignoredWhitelist) {
+    const absolute = path.resolve(filePath);
+    if (Array.from(allowedPaths).some((allowed) => absolute === allowed || absolute.startsWith(`${allowed}${path.sep}`))) {
+        return null; // explicitly requested path overrides default ignore when the ignored dir itself was passed
+    }
+    const rel = path.relative(cwd, absolute);
+    const parts = rel.split(path.sep);
+    for (let idx = 0; idx < parts.length; idx += 1) {
+        const part = parts[idx];
+        if (!DEFAULT_IGNORED_DIRS.includes(part)) {
+            continue;
+        }
+        const ignoredDir = path.resolve(cwd, parts.slice(0, idx + 1).join(path.sep));
+        if (ignoredWhitelist.has(ignoredDir)) {
+            continue;
+        }
+        return part;
+    }
+    return null;
+}
+function matchesAny(relativePath, patterns) {
+    return patterns.some((pattern) => matchesPattern(relativePath, pattern));
+}
+function matchesPattern(relativePath, pattern) {
+    if (!pattern) {
+        return false;
+    }
+    const normalized = pattern.replace(/\\+/g, '/');
+    // Directory rule
+    if (normalized.endsWith('/')) {
+        const dir = normalized.slice(0, -1);
+        return relativePath === dir || relativePath.startsWith(`${dir}/`);
+    }
+    // Simple glob support (* and **)
+    const regex = globToRegex(normalized);
+    return regex.test(relativePath);
+}
+function globToRegex(pattern) {
+    const withMarkers = pattern.replace(/\*\*/g, '§§DOUBLESTAR§§').replace(/\*/g, '§§SINGLESTAR§§');
+    const escaped = withMarkers.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const restored = escaped
+        .replace(/§§DOUBLESTAR§§/g, '.*')
+        .replace(/§§SINGLESTAR§§/g, '[^/]*');
+    return new RegExp(`^${restored}$`);
+}
+function includesDotfileSegment(pattern) {
+    const segments = pattern.split('/');
+    return segments.some((segment) => segment.startsWith('.') && segment.length > 1);
+}
+async function expandWithCustomFs(partitioned, fsModule) {
+    const paths = new Set();
+    partitioned.literalFiles.forEach((file) => {
+        paths.add(file);
+    });
+    for (const directory of partitioned.literalDirectories) {
+        const nested = await expandDirectoryRecursive(directory, fsModule);
+        nested.forEach((entry) => {
+            paths.add(entry);
+        });
+    }
+    return Array.from(paths);
+}
+async function expandDirectoryRecursive(directory, fsModule) {
+    const entries = await fsModule.readdir(directory);
+    const results = [];
+    for (const entry of entries) {
+        const childPath = path.join(directory, entry);
+        const stats = await fsModule.stat(childPath);
+        if (stats.isDirectory()) {
+            results.push(...(await expandDirectoryRecursive(childPath, fsModule)));
+        }
+        else if (stats.isFile()) {
+            results.push(childPath);
+        }
+    }
+    return results;
+}
+function makeDirectoryPattern(relative) {
+    if (relative === '.' || relative === '') {
+        return '**/*';
+    }
+    return `${stripTrailingSlashes(relative)}/**/*`;
+}
+function isNativeFsModule(fsModule) {
+    return ((fsModule.__nativeFs === true ||
+        (fsModule.readFile === DEFAULT_FS.readFile &&
+            fsModule.stat === DEFAULT_FS.stat &&
+            fsModule.readdir === DEFAULT_FS.readdir)));
+}
+function normalizeGlob(pattern, cwd) {
+    if (!pattern) {
+        return '';
+    }
+    let normalized = pattern;
+    if (path.isAbsolute(normalized)) {
+        normalized = path.relative(cwd, normalized);
+    }
+    normalized = toPosix(normalized);
+    if (normalized.startsWith('./')) {
+        normalized = normalized.slice(2);
+    }
+    return normalized;
+}
+function toPosix(value) {
+    return value.replace(/\\/g, '/');
+}
+function toPosixRelative(absPath, cwd) {
+    const relative = path.relative(cwd, absPath);
+    if (!relative) {
+        return '.';
+    }
+    return toPosix(relative);
+}
+function toPosixRelativeOrBasename(absPath, cwd) {
+    const relative = path.relative(cwd, absPath);
+    return toPosix(relative || path.basename(absPath));
+}
+function stripTrailingSlashes(value) {
+    const normalized = toPosix(value);
+    return normalized.replace(/\/+$/g, '');
+}
+function formatBytes(size) {
+    if (size >= 1024 * 1024) {
+        return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+    }
+    if (size >= 1024) {
+        return `${(size / 1024).toFixed(1)} KB`;
+    }
+    return `${size} B`;
+}
+function relativePath(targetPath, cwd) {
+    const relative = path.relative(cwd, targetPath);
+    return relative || targetPath;
+}
+export function createFileSections(files, cwd = process.cwd()) {
+    return files.map((file, index) => {
+        const relative = toPosix(path.relative(cwd, file.path) || file.path);
+        const sectionText = [
+            `### File ${index + 1}: ${relative}`,
+            '```',
+            file.content.trimEnd(),
+            '```',
+        ].join('\n');
+        return {
+            index: index + 1,
+            absolutePath: file.path,
+            displayPath: relative,
+            sectionText,
+            content: file.content,
+        };
+    });
+}

package/dist/src/oracle/format.js

@@ -0,0 +1,30 @@
+export function formatUSD(value) {
+    if (!Number.isFinite(value)) {
+        return 'n/a';
+    }
+    // Display with 4 decimal places, rounding to $0.0001 minimum granularity.
+    return `$${value.toFixed(4)}`;
+}
+export function formatNumber(value, { estimated = false } = {}) {
+    if (value == null) {
+        return 'n/a';
+    }
+    const suffix = estimated ? ' (est.)' : '';
+    return `${value.toLocaleString()}${suffix}`;
+}
+export function formatElapsed(ms) {
+    if (ms >= 60 * 60 * 1000) {
+        const hours = Math.floor(ms / (60 * 60 * 1000));
+        const minutes = Math.floor((ms % (60 * 60 * 1000)) / (60 * 1000));
+        return `${hours}h ${minutes}m`;
+    }
+    if (ms >= 60 * 1000) {
+        const minutes = Math.floor(ms / (60 * 1000));
+        const seconds = Math.floor((ms % (60 * 1000)) / 1000);
+        return `${minutes}m ${seconds}s`;
+    }
+    if (ms >= 1000) {
+        return `${Math.floor(ms / 1000)}s`;
+    }
+    return `${Math.round(ms)}ms`;
+}

package/dist/src/oracle/fsAdapter.js

@@ -0,0 +1,10 @@
+export function createFsAdapter(fsModule) {
+    const adapter = {
+        stat: (targetPath) => fsModule.stat(targetPath),
+        readdir: (targetPath) => fsModule.readdir(targetPath),
+        readFile: (targetPath, encoding) => fsModule.readFile(targetPath, encoding),
+    };
+    // Mark adapters so downstream callers can treat them as native filesystem access.
+    adapter.__nativeFs = true;
+    return adapter;
+}