@steipete/oracle 1.0.7 → 1.1.0

package/dist/oracle/src/browser/promptSummary.js

@@ -0,0 +1,20 @@
+import { formatBytes } from './utils.js';
+export function buildTokenEstimateSuffix(artifacts) {
+    if (artifacts.tokenEstimateIncludesInlineFiles && artifacts.inlineFileCount > 0) {
+        const count = artifacts.inlineFileCount;
+        const plural = count === 1 ? '' : 's';
+        return ` (includes ${count} inline file${plural})`;
+    }
+    if (artifacts.attachments.length > 0) {
+        const count = artifacts.attachments.length;
+        const plural = count === 1 ? '' : 's';
+        return ` (prompt only; ${count} attachment${plural} excluded)`;
+    }
+    return '';
+}
+export function formatAttachmentLabel(attachment) {
+    if (typeof attachment.sizeBytes !== 'number' || Number.isNaN(attachment.sizeBytes)) {
+        return attachment.displayPath;
+    }
+    return `${attachment.displayPath} (${formatBytes(attachment.sizeBytes)})`;
+}

package/dist/oracle/src/browser/sessionRunner.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import { formatElapsed } from '../oracle.js';
+import { runBrowserMode } from '../browserMode.js';
+import { assembleBrowserPrompt } from './prompt.js';
+import { BrowserAutomationError } from '../oracle/errors.js';
+export async function runBrowserSessionExecution({ runOptions, browserConfig, cwd, log, cliVersion }, deps = {}) {
+    const assemblePrompt = deps.assemblePrompt ?? assembleBrowserPrompt;
+    const executeBrowser = deps.executeBrowser ?? runBrowserMode;
+    const promptArtifacts = await assemblePrompt(runOptions, { cwd });
+    if (runOptions.verbose) {
+        log(chalk.dim(`[verbose] Browser config: ${JSON.stringify({
+            ...browserConfig,
+        })}`));
+        log(chalk.dim(`[verbose] Browser prompt length: ${promptArtifacts.composerText.length} chars`));
+        if (promptArtifacts.attachments.length > 0) {
+            const attachmentList = promptArtifacts.attachments.map((attachment) => attachment.displayPath).join(', ');
+            log(chalk.dim(`[verbose] Browser attachments: ${attachmentList}`));
+            if (promptArtifacts.bundled) {
+                log(chalk.yellow(`[browser] More than 10 files provided; bundled ${promptArtifacts.bundled.originalCount} files into ${promptArtifacts.bundled.bundlePath} to satisfy ChatGPT upload limits.`));
+            }
+        }
+        else if (runOptions.file && runOptions.file.length > 0 && runOptions.browserInlineFiles) {
+            log(chalk.dim('[verbose] Browser inline file fallback enabled (pasting file contents).'));
+        }
+    }
+    const headerLine = `Oracle (${cliVersion}) launching browser mode (${runOptions.model}) with ~${promptArtifacts.estimatedInputTokens.toLocaleString()} tokens`;
+    const automationLogger = ((message) => {
+        if (typeof message === 'string') {
+            log(message);
+        }
+    });
+    automationLogger.verbose = Boolean(runOptions.verbose);
+    automationLogger.sessionLog = log;
+    log(headerLine);
+    log(chalk.dim('Chrome automation does not stream output; this may take a minute...'));
+    let browserResult;
+    try {
+        browserResult = await executeBrowser({
+            prompt: promptArtifacts.composerText,
+            attachments: promptArtifacts.attachments,
+            config: browserConfig,
+            log: automationLogger,
+            heartbeatIntervalMs: runOptions.heartbeatIntervalMs,
+            verbose: runOptions.verbose,
+        });
+    }
+    catch (error) {
+        if (error instanceof BrowserAutomationError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : 'Browser automation failed.';
+        throw new BrowserAutomationError(message, { stage: 'execute-browser' }, error);
+    }
+    if (!runOptions.silent) {
+        log(chalk.bold('Answer:'));
+        log(browserResult.answerMarkdown || browserResult.answerText || chalk.dim('(no text output)'));
+        log('');
+    }
+    const usage = {
+        inputTokens: promptArtifacts.estimatedInputTokens,
+        outputTokens: browserResult.answerTokens,
+        reasoningTokens: 0,
+        totalTokens: promptArtifacts.estimatedInputTokens + browserResult.answerTokens,
+    };
+    const tokensDisplay = `${usage.inputTokens}/${usage.outputTokens}/${usage.reasoningTokens}/${usage.totalTokens}`;
+    const statsParts = [`${runOptions.model}[browser]`, `tok(i/o/r/t)=${tokensDisplay}`];
+    if (runOptions.file && runOptions.file.length > 0) {
+        statsParts.push(`files=${runOptions.file.length}`);
+    }
+    log(chalk.blue(`Finished in ${formatElapsed(browserResult.tookMs)} (${statsParts.join(' | ')})`));
+    return {
+        usage,
+        elapsedMs: browserResult.tookMs,
+        runtime: {
+            chromePid: browserResult.chromePid,
+            chromePort: browserResult.chromePort,
+            userDataDir: browserResult.userDataDir,
+        },
+    };
+}

package/dist/oracle/src/browser/types.js

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

package/dist/oracle/src/browser/utils.js

@@ -0,0 +1,62 @@
+export function parseDuration(input, fallback) {
+    if (!input) {
+        return fallback;
+    }
+    const match = /^([0-9]+)(ms|s|m)?$/i.exec(input.trim());
+    if (!match) {
+        return fallback;
+    }
+    const value = Number(match[1]);
+    const unit = match[2]?.toLowerCase();
+    if (!unit || unit === 'ms') {
+        return value;
+    }
+    if (unit === 's') {
+        return value * 1000;
+    }
+    if (unit === 'm') {
+        return value * 60_000;
+    }
+    return fallback;
+}
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function estimateTokenCount(text) {
+    if (!text) {
+        return 0;
+    }
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    const estimate = Math.max(words.length * 0.75, text.length / 4);
+    return Math.max(1, Math.round(estimate));
+}
+export async function withRetries(task, options = {}) {
+    const { retries = 2, delayMs = 250, onRetry } = options;
+    let attempt = 0;
+    while (attempt <= retries) {
+        try {
+            return await task();
+        }
+        catch (error) {
+            if (attempt === retries) {
+                throw error;
+            }
+            attempt += 1;
+            onRetry?.(attempt, error);
+            await delay(delayMs * attempt);
+        }
+    }
+    throw new Error('withRetries exhausted without result');
+}
+export function formatBytes(size) {
+    if (!Number.isFinite(size) || size < 0) {
+        return 'n/a';
+    }
+    if (size < 1024) {
+        return `${size} B`;
+    }
+    if (size < 1024 * 1024) {
+        return `${(size / 1024).toFixed(1)} KB`;
+    }
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/oracle/src/browserMode.js

@@ -0,0 +1 @@
+export { runBrowserMode, CHATGPT_URL, DEFAULT_MODEL_TARGET, parseDuration, } from './browser/index.js';

package/dist/oracle/src/cli/browserConfig.js

@@ -0,0 +1,44 @@
+import { DEFAULT_MODEL_TARGET, parseDuration } from '../browserMode.js';
+const DEFAULT_BROWSER_TIMEOUT_MS = 900_000;
+const DEFAULT_BROWSER_INPUT_TIMEOUT_MS = 30_000;
+const DEFAULT_CHROME_PROFILE = 'Default';
+const BROWSER_MODEL_LABELS = {
+    'gpt-5-pro': 'GPT-5 Pro',
+    'gpt-5.1': 'ChatGPT 5.1',
+};
+export function buildBrowserConfig(options) {
+    const desiredModelOverride = options.browserModelLabel?.trim();
+    const normalizedOverride = desiredModelOverride?.toLowerCase() ?? '';
+    const baseModel = options.model.toLowerCase();
+    const shouldUseOverride = normalizedOverride.length > 0 && normalizedOverride !== baseModel;
+    return {
+        chromeProfile: options.browserChromeProfile ?? DEFAULT_CHROME_PROFILE,
+        chromePath: options.browserChromePath ?? null,
+        url: options.browserUrl,
+        timeoutMs: options.browserTimeout ? parseDuration(options.browserTimeout, DEFAULT_BROWSER_TIMEOUT_MS) : undefined,
+        inputTimeoutMs: options.browserInputTimeout
+            ? parseDuration(options.browserInputTimeout, DEFAULT_BROWSER_INPUT_TIMEOUT_MS)
+            : undefined,
+        cookieSync: options.browserNoCookieSync ? false : undefined,
+        headless: options.browserHeadless ? true : undefined,
+        keepBrowser: options.browserKeepBrowser ? true : undefined,
+        hideWindow: options.browserHideWindow ? true : undefined,
+        desiredModel: shouldUseOverride ? desiredModelOverride : mapModelToBrowserLabel(options.model),
+        debug: options.verbose ? true : undefined,
+        allowCookieErrors: options.browserAllowCookieErrors ? true : undefined,
+    };
+}
+export function mapModelToBrowserLabel(model) {
+    return BROWSER_MODEL_LABELS[model] ?? DEFAULT_MODEL_TARGET;
+}
+export function resolveBrowserModelLabel(input, model) {
+    const trimmed = input?.trim?.() ?? '';
+    if (!trimmed) {
+        return mapModelToBrowserLabel(model);
+    }
+    const normalizedInput = trimmed.toLowerCase();
+    if (normalizedInput === model.toLowerCase()) {
+        return mapModelToBrowserLabel(model);
+    }
+    return trimmed;
+}

package/dist/oracle/src/cli/dryRun.js

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import { MODEL_CONFIGS, TOKENIZER_OPTIONS, DEFAULT_SYSTEM_PROMPT, buildPrompt, readFiles, getFileTokenStats, printFileTokenStats, } from '../oracle.js';
+import { assembleBrowserPrompt } from '../browser/prompt.js';
+import { buildTokenEstimateSuffix, formatAttachmentLabel } from '../browser/promptSummary.js';
+export async function runDryRunSummary({ engine, runOptions, cwd, version, log, }, deps = {}) {
+    if (engine === 'browser') {
+        await runBrowserDryRun({ runOptions, cwd, version, log }, deps);
+        return;
+    }
+    await runApiDryRun({ runOptions, cwd, version, log }, deps);
+}
+async function runApiDryRun({ runOptions, cwd, version, log, }, deps) {
+    const readFilesImpl = deps.readFilesImpl ?? readFiles;
+    const files = await readFilesImpl(runOptions.file ?? [], { cwd });
+    const systemPrompt = runOptions.system?.trim() || DEFAULT_SYSTEM_PROMPT;
+    const combinedPrompt = buildPrompt(runOptions.prompt ?? '', files, cwd);
+    const tokenizer = MODEL_CONFIGS[runOptions.model].tokenizer;
+    const estimatedInputTokens = tokenizer([
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: combinedPrompt },
+    ], TOKENIZER_OPTIONS);
+    const headerLine = `[dry-run] Oracle (${version}) would call ${runOptions.model} with ~${estimatedInputTokens.toLocaleString()} tokens and ${files.length} files.`;
+    log(chalk.cyan(headerLine));
+    if (files.length === 0) {
+        log(chalk.dim('[dry-run] No files matched the provided --file patterns.'));
+        return;
+    }
+    const inputBudget = runOptions.maxInput ?? MODEL_CONFIGS[runOptions.model].inputLimit;
+    const stats = getFileTokenStats(files, {
+        cwd,
+        tokenizer,
+        tokenizerOptions: TOKENIZER_OPTIONS,
+        inputTokenBudget: inputBudget,
+    });
+    printFileTokenStats(stats, { inputTokenBudget: inputBudget, log });
+}
+async function runBrowserDryRun({ runOptions, cwd, version, log, }, deps) {
+    const assemblePromptImpl = deps.assembleBrowserPromptImpl ?? assembleBrowserPrompt;
+    const artifacts = await assemblePromptImpl(runOptions, { cwd });
+    const suffix = buildTokenEstimateSuffix(artifacts);
+    const headerLine = `[dry-run] Oracle (${version}) would launch browser mode (${runOptions.model}) with ~${artifacts.estimatedInputTokens.toLocaleString()} tokens${suffix}.`;
+    log(chalk.cyan(headerLine));
+    logBrowserFileSummary(artifacts, log);
+}
+function logBrowserFileSummary(artifacts, log) {
+    if (artifacts.attachments.length > 0) {
+        log(chalk.bold('[dry-run] Attachments to upload:'));
+        artifacts.attachments.forEach((attachment) => {
+            log(`  • ${formatAttachmentLabel(attachment)}`);
+        });
+        return;
+    }
+    if (artifacts.inlineFileCount > 0) {
+        log(chalk.bold('[dry-run] Inline file content:'));
+        log(`  • ${artifacts.inlineFileCount} file${artifacts.inlineFileCount === 1 ? '' : 's'} pasted directly into the composer.`);
+        return;
+    }
+    log(chalk.dim('[dry-run] No files attached.'));
+}

package/dist/oracle/src/cli/engine.js

@@ -0,0 +1,17 @@
+/**
+ * Determine which engine to use based on CLI flags and the environment.
+ *
+ * Precedence:
+ * 1) Legacy --browser flag forces browser.
+ * 2) Explicit --engine value.
+ * 3) OPENAI_API_KEY decides: api when set, otherwise browser.
+ */
+export function resolveEngine({ engine, browserFlag, env, }) {
+    if (browserFlag) {
+        return 'browser';
+    }
+    if (engine) {
+        return engine;
+    }
+    return env.OPENAI_API_KEY ? 'api' : 'browser';
+}

package/dist/oracle/src/cli/errorUtils.js

@@ -0,0 +1,9 @@
+const LOGGED_SYMBOL = Symbol('oracle.alreadyLogged');
+export function markErrorLogged(error) {
+    if (error instanceof Error) {
+        error[LOGGED_SYMBOL] = true;
+    }
+}
+export function isErrorLogged(error) {
+    return Boolean(error instanceof Error && error[LOGGED_SYMBOL]);
+}

package/dist/oracle/src/cli/help.js

@@ -0,0 +1,70 @@
+import kleur from 'kleur';
+const createColorWrapper = (isTty) => (styler) => (text) => isTty ? styler(text) : text;
+export function applyHelpStyling(program, version, isTty) {
+    const wrap = createColorWrapper(isTty);
+    const colors = {
+        banner: wrap((text) => kleur.bold().blue(text)),
+        subtitle: wrap((text) => kleur.dim(text)),
+        section: wrap((text) => kleur.bold().white(text)),
+        bullet: wrap((text) => kleur.blue(text)),
+        command: wrap((text) => kleur.bold().blue(text)),
+        option: wrap((text) => kleur.cyan(text)),
+        argument: wrap((text) => kleur.magenta(text)),
+        description: wrap((text) => kleur.white(text)),
+        muted: wrap((text) => kleur.gray(text)),
+        accent: wrap((text) => kleur.cyan(text)),
+    };
+    program.configureHelp({
+        styleTitle(title) {
+            return colors.section(title);
+        },
+        styleDescriptionText(text) {
+            return colors.description(text);
+        },
+        styleCommandText(text) {
+            return colors.command(text);
+        },
+        styleSubcommandText(text) {
+            return colors.command(text);
+        },
+        styleOptionText(text) {
+            return colors.option(text);
+        },
+        styleArgumentText(text) {
+            return colors.argument(text);
+        },
+    });
+    program.addHelpText('beforeAll', () => renderHelpBanner(version, colors));
+    program.addHelpText('after', () => renderHelpFooter(program, colors));
+}
+function renderHelpBanner(version, colors) {
+    const subtitle = 'GPT-5 Pro/GPT-5.1 for tough questions with code/file context.';
+    return `${colors.banner(`Oracle CLI v${version}`)} ${colors.subtitle(`— ${subtitle}`)}\n`;
+}
+function renderHelpFooter(program, colors) {
+    const tips = [
+        `${colors.bullet('•')} Attach lots of source (whole directories beat single files) and keep total input under ~196k tokens.`,
+        `${colors.bullet('•')} Oracle starts empty—open with a short project briefing (stack, services, build steps), spell out the question and prior attempts, and why it matters; the more explanation and context you provide, the better the response will be.`,
+        `${colors.bullet('•')} Oracle is one-shot: it does not remember prior runs, so start fresh each time with full context.`,
+        `${colors.bullet('•')} Run ${colors.accent('--files-report')} to inspect token spend before hitting the API.`,
+        `${colors.bullet('•')} Non-preview runs spawn detached sessions so they keep streaming even if your terminal closes — reattach anytime via ${colors.accent('pnpm oracle session <slug>')}.`,
+        `${colors.bullet('•')} Set a memorable 3–5 word slug via ${colors.accent('--slug "<words>"')} to keep session IDs tidy.`,
+        `${colors.bullet('•')} Finished sessions auto-hide preamble logs when reattached; raw timestamps remain in the saved log file.`,
+        `${colors.bullet('•')} Need hidden flags? Run ${colors.accent(`${program.name()} --help --verbose`)} to list search/token/browser overrides.`,
+    ].join('\n');
+    const formatExample = (command, description) => `${colors.command(`  ${command}`)}\n${colors.muted(`    ${description}`)}`;
+    const examples = [
+        formatExample(`${program.name()} --prompt "Summarize risks" --file docs/risk.md --files-report --preview`, 'Inspect tokens + files without calling the API.'),
+        formatExample(`${program.name()} --prompt "Explain bug" --file src/,docs/crash.log --files-report`, 'Attach src/ plus docs/crash.log, launch a background session, and capture the Session ID.'),
+        formatExample(`${program.name()} status --hours 72 --limit 50`, 'Show sessions from the last 72h (capped at 50 entries).'),
+        formatExample(`${program.name()} session <sessionId>`, 'Attach to a running/completed session and stream the saved transcript.'),
+        formatExample(`${program.name()} --prompt "Ship review" --slug "release-readiness-audit"`, 'Encourage the model to hand you a 3–5 word slug and pass it along with --slug.'),
+    ].join('\n\n');
+    return `
+${colors.section('Tips')}
+${tips}
+
+${colors.section('Examples')}
+${examples}
+`;
+}

package/dist/oracle/src/cli/markdownRenderer.js

@@ -0,0 +1,15 @@
+import { render as renderMarkdown } from 'markdansi';
+export function renderMarkdownAnsi(markdown) {
+    try {
+        return renderMarkdown(markdown, {
+            color: Boolean(process.stdout.isTTY),
+            width: process.stdout.columns,
+            wrap: true,
+            hyperlinks: false,
+        });
+    }
+    catch {
+        // Last-resort fallback: return the raw markdown so we never crash.
+        return markdown;
+    }
+}

package/dist/oracle/src/cli/options.js

@@ -0,0 +1,103 @@
+import { InvalidArgumentError } from 'commander';
+import { MODEL_CONFIGS } from '../oracle.js';
+export function collectPaths(value, previous = []) {
+    if (!value) {
+        return previous;
+    }
+    const nextValues = Array.isArray(value) ? value : [value];
+    return previous.concat(nextValues.flatMap((entry) => entry.split(',')).map((entry) => entry.trim()).filter(Boolean));
+}
+export function parseFloatOption(value) {
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed)) {
+        throw new InvalidArgumentError('Value must be a number.');
+    }
+    return parsed;
+}
+export function parseIntOption(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+        throw new InvalidArgumentError('Value must be an integer.');
+    }
+    return parsed;
+}
+export function parseHeartbeatOption(value) {
+    if (value == null) {
+        return 30;
+    }
+    if (typeof value === 'number') {
+        if (Number.isNaN(value) || value < 0) {
+            throw new InvalidArgumentError('Heartbeat interval must be zero or a positive number.');
+        }
+        return value;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return 30;
+    }
+    if (normalized === 'false' || normalized === 'off') {
+        return 0;
+    }
+    const parsed = Number.parseFloat(normalized);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        throw new InvalidArgumentError('Heartbeat interval must be zero or a positive number.');
+    }
+    return parsed;
+}
+export function usesDefaultStatusFilters(cmd) {
+    const hoursSource = cmd.getOptionValueSource?.('hours') ?? 'default';
+    const limitSource = cmd.getOptionValueSource?.('limit') ?? 'default';
+    const allSource = cmd.getOptionValueSource?.('all') ?? 'default';
+    return hoursSource === 'default' && limitSource === 'default' && allSource === 'default';
+}
+export function resolvePreviewMode(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    if (value === true) {
+        return 'summary';
+    }
+    return undefined;
+}
+export function parseSearchOption(value) {
+    const normalized = value.trim().toLowerCase();
+    if (['on', 'true', '1', 'yes'].includes(normalized)) {
+        return true;
+    }
+    if (['off', 'false', '0', 'no'].includes(normalized)) {
+        return false;
+    }
+    throw new InvalidArgumentError('Search mode must be "on" or "off".');
+}
+export function normalizeModelOption(value) {
+    return (value ?? '').trim();
+}
+export function resolveApiModel(modelValue) {
+    const normalized = normalizeModelOption(modelValue).toLowerCase();
+    if (normalized in MODEL_CONFIGS) {
+        return normalized;
+    }
+    throw new InvalidArgumentError(`Unsupported model "${modelValue}". Choose one of: ${Object.keys(MODEL_CONFIGS).join(', ')}`);
+}
+export function inferModelFromLabel(modelValue) {
+    const normalized = normalizeModelOption(modelValue).toLowerCase();
+    if (!normalized) {
+        return 'gpt-5-pro';
+    }
+    if (normalized in MODEL_CONFIGS) {
+        return normalized;
+    }
+    if (normalized.includes('pro')) {
+        return 'gpt-5-pro';
+    }
+    if (normalized.includes('5.1') || normalized.includes('5_1')) {
+        return 'gpt-5.1';
+    }
+    if (normalized.includes('instant') || normalized.includes('thinking') || normalized.includes('fast')) {
+        return 'gpt-5.1';
+    }
+    return 'gpt-5.1';
+}

package/dist/oracle/src/cli/promptRequirement.js

@@ -0,0 +1,14 @@
+/**
+ * Determine whether the CLI should enforce a prompt requirement based on raw args and options.
+ */
+export function shouldRequirePrompt(rawArgs, options) {
+    const firstArg = rawArgs[0];
+    const bypassPrompt = Boolean(options.session ||
+        options.execSession ||
+        options.status ||
+        options.debugHelp ||
+        firstArg === 'status' ||
+        firstArg === 'session');
+    const requiresPrompt = options.renderMarkdown || Boolean(options.preview) || Boolean(options.dryRun) || !bypassPrompt;
+    return requiresPrompt && !options.prompt;
+}

package/dist/oracle/src/cli/rootAlias.js

@@ -0,0 +1,30 @@
+import { attachSession, showStatus } from './sessionDisplay.js';
+const defaultDeps = {
+    attachSession,
+    showStatus,
+};
+export async function handleStatusFlag(options, deps = defaultDeps) {
+    if (!options.status) {
+        return false;
+    }
+    if (options.session) {
+        await deps.attachSession(options.session);
+        return true;
+    }
+    await deps.showStatus({ hours: 24, includeAll: false, limit: 100, showExamples: true });
+    return true;
+}
+const defaultSessionDeps = {
+    attachSession,
+};
+/**
+ * Hidden root-level alias to attach to a stored session (`--session <id>`).
+ * Returns true when the alias was handled so callers can short-circuit.
+ */
+export async function handleSessionAlias(options, deps = defaultSessionDeps) {
+    if (!options.session) {
+        return false;
+    }
+    await deps.attachSession(options.session);
+    return true;
+}

package/dist/oracle/src/cli/sessionCommand.js

@@ -0,0 +1,77 @@
+import { usesDefaultStatusFilters } from './options.js';
+import { attachSession, showStatus } from './sessionDisplay.js';
+import { deleteSessionsOlderThan } from '../sessionManager.js';
+const defaultDependencies = {
+    showStatus,
+    attachSession,
+    usesDefaultStatusFilters,
+    deleteSessionsOlderThan,
+};
+const SESSION_OPTION_KEYS = new Set(['hours', 'limit', 'all', 'clear', 'clean', 'render', 'renderMarkdown']);
+export async function handleSessionCommand(sessionId, command, deps = defaultDependencies) {
+    const sessionOptions = command.opts();
+    if (sessionOptions.verboseRender) {
+        process.env.ORACLE_VERBOSE_RENDER = '1';
+    }
+    const clearRequested = Boolean(sessionOptions.clear || sessionOptions.clean);
+    if (clearRequested) {
+        if (sessionId) {
+            console.error('Cannot combine a session ID with --clear. Remove the ID to delete cached sessions.');
+            process.exitCode = 1;
+            return;
+        }
+        const hours = sessionOptions.hours;
+        const includeAll = sessionOptions.all;
+        const result = await deps.deleteSessionsOlderThan({ hours, includeAll });
+        const scope = includeAll ? 'all stored sessions' : `sessions older than ${hours}h`;
+        console.log(formatSessionCleanupMessage(result, scope));
+        return;
+    }
+    if (sessionId === 'clear' || sessionId === 'clean') {
+        console.error('Session cleanup now uses --clear. Run "oracle session --clear --hours <n>" instead.');
+        process.exitCode = 1;
+        return;
+    }
+    if (!sessionId) {
+        const showExamples = deps.usesDefaultStatusFilters(command);
+        await deps.showStatus({
+            hours: sessionOptions.all ? Infinity : sessionOptions.hours,
+            includeAll: sessionOptions.all,
+            limit: sessionOptions.limit,
+            showExamples,
+        });
+        return;
+    }
+    // Surface any root-level flags that were provided but are ignored when attaching to a session.
+    const ignoredFlags = listIgnoredFlags(command);
+    if (ignoredFlags.length > 0) {
+        console.log(`Ignoring flags on session attach: ${ignoredFlags.join(', ')}`);
+    }
+    const renderMarkdown = Boolean(sessionOptions.render || sessionOptions.renderMarkdown);
+    await deps.attachSession(sessionId, { renderMarkdown });
+}
+export function formatSessionCleanupMessage(result, scope) {
+    const deletedLabel = `${result.deleted} ${result.deleted === 1 ? 'session' : 'sessions'}`;
+    const remainingLabel = `${result.remaining} ${result.remaining === 1 ? 'session' : 'sessions'} remain`;
+    const hint = 'Run "oracle session --clear --all" to delete everything.';
+    return `Deleted ${deletedLabel} (${scope}). ${remainingLabel}.\n${hint}`;
+}
+function listIgnoredFlags(command) {
+    const opts = command.optsWithGlobals();
+    const ignored = [];
+    for (const key of Object.keys(opts)) {
+        if (SESSION_OPTION_KEYS.has(key)) {
+            continue;
+        }
+        const source = command.getOptionValueSource?.(key);
+        if (source !== 'cli' && source !== 'env') {
+            continue;
+        }
+        const value = opts[key];
+        if (value === undefined || value === false || value === null) {
+            continue;
+        }
+        ignored.push(key);
+    }
+    return ignored;
+}