@steipete/oracle 0.4.0

package/dist/src/cli/sessionRunner.js

@@ -0,0 +1,419 @@
+import kleur from 'kleur';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runOracle, OracleResponseError, OracleTransportError, extractResponseMetadata, asOracleUserError, extractTextOutput, } from '../oracle.js';
+import { runBrowserSessionExecution } from '../browser/sessionRunner.js';
+import { renderMarkdownAnsi } from './markdownRenderer.js';
+import { formatResponseMetadata, formatTransportMetadata } from './sessionDisplay.js';
+import { markErrorLogged } from './errorUtils.js';
+import { sendSessionNotification, deriveNotificationSettingsFromMetadata, } from './notifier.js';
+import { sessionStore } from '../sessionStore.js';
+import { runMultiModelApiSession } from '../oracle/multiModelRunner.js';
+import { MODEL_CONFIGS, DEFAULT_SYSTEM_PROMPT } from '../oracle/config.js';
+import { buildPrompt, buildRequestBody } from '../oracle/request.js';
+import { estimateRequestTokens } from '../oracle/tokenEstimate.js';
+import { formatTokenEstimate, formatTokenValue } from '../oracle/runUtils.js';
+import { formatElapsed } from '../oracle/format.js';
+import { sanitizeOscProgress } from './oscUtils.js';
+import { readFiles } from '../oracle/files.js';
+import { formatUSD } from '../oracle/format.js';
+import { SESSIONS_DIR } from '../sessionManager.js';
+import { cwd as getCwd } from 'node:process';
+const isTty = process.stdout.isTTY;
+const dim = (text) => (isTty ? kleur.dim(text) : text);
+export async function performSessionRun({ sessionMeta, runOptions, mode, browserConfig, cwd, log, write, version, notifications, browserDeps, muteStdout = false, }) {
+    const writeInline = (chunk) => {
+        // Keep session logs intact while still echoing inline output to the user.
+        write(chunk);
+        return muteStdout ? true : process.stdout.write(chunk);
+    };
+    await sessionStore.updateSession(sessionMeta.id, {
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        mode,
+        ...(browserConfig ? { browser: { config: browserConfig } } : {}),
+    });
+    const notificationSettings = notifications ?? deriveNotificationSettingsFromMetadata(sessionMeta, process.env);
+    const modelForStatus = runOptions.model ?? sessionMeta.model;
+    try {
+        if (mode === 'browser') {
+            if (runOptions.model.startsWith('gemini')) {
+                throw new Error('Gemini models are not available in browser mode. Re-run with --engine api.');
+            }
+            if (!browserConfig) {
+                throw new Error('Missing browser configuration for session.');
+            }
+            if (modelForStatus) {
+                await sessionStore.updateModelRun(sessionMeta.id, modelForStatus, {
+                    status: 'running',
+                    startedAt: new Date().toISOString(),
+                });
+            }
+            const result = await runBrowserSessionExecution({ runOptions, browserConfig, cwd, log }, browserDeps);
+            if (modelForStatus) {
+                await sessionStore.updateModelRun(sessionMeta.id, modelForStatus, {
+                    status: 'completed',
+                    completedAt: new Date().toISOString(),
+                    usage: result.usage,
+                });
+            }
+            await sessionStore.updateSession(sessionMeta.id, {
+                status: 'completed',
+                completedAt: new Date().toISOString(),
+                usage: result.usage,
+                elapsedMs: result.elapsedMs,
+                browser: {
+                    config: browserConfig,
+                    runtime: result.runtime,
+                },
+                response: undefined,
+                transport: undefined,
+                error: undefined,
+            });
+            await writeAssistantOutput(runOptions.writeOutputPath, result.answerText ?? '', log);
+            await sendSessionNotification({
+                sessionId: sessionMeta.id,
+                sessionName: sessionMeta.options?.slug ?? sessionMeta.id,
+                mode,
+                model: sessionMeta.model,
+                usage: result.usage,
+                characters: result.answerText?.length,
+            }, notificationSettings, log, result.answerText?.slice(0, 140));
+            return;
+        }
+        const multiModels = Array.isArray(runOptions.models) ? runOptions.models.filter(Boolean) : [];
+        if (multiModels.length > 1) {
+            const [primaryModel] = multiModels;
+            if (!primaryModel) {
+                throw new Error('Missing model name for multi-model run.');
+            }
+            const modelConfig = MODEL_CONFIGS[primaryModel];
+            if (!modelConfig) {
+                throw new Error(`Unsupported model "${primaryModel}".`);
+            }
+            const files = await readFiles(runOptions.file ?? [], { cwd });
+            const promptWithFiles = buildPrompt(runOptions.prompt, files, cwd);
+            const requestBody = buildRequestBody({
+                modelConfig,
+                systemPrompt: runOptions.system ?? DEFAULT_SYSTEM_PROMPT,
+                userPrompt: promptWithFiles,
+                searchEnabled: runOptions.search !== false,
+                maxOutputTokens: runOptions.maxOutput,
+                background: runOptions.background,
+                storeResponse: runOptions.background,
+            });
+            const estimatedTokens = estimateRequestTokens(requestBody, modelConfig);
+            const tokenLabel = formatTokenEstimate(estimatedTokens, (text) => (isTty ? kleur.green(text) : text));
+            const filesPhrase = files.length === 0 ? 'no files' : `${files.length} files`;
+            const modelsLabel = multiModels.join(', ');
+            log(`Calling ${isTty ? kleur.cyan(modelsLabel) : modelsLabel} — ${tokenLabel} tokens, ${filesPhrase}.`);
+            const multiRunTips = [];
+            if (files.length === 0) {
+                multiRunTips.push('Tip: no files attached — Oracle works best with project context. Add files via --file path/to/code or docs.');
+            }
+            const shortPrompt = (runOptions.prompt?.trim().length ?? 0) < 80;
+            if (shortPrompt) {
+                multiRunTips.push('Tip: brief prompts often yield generic answers — aim for 6–30 sentences and attach key files.');
+            }
+            for (const tip of multiRunTips) {
+                log(dim(tip));
+            }
+            // Surface long-running model expectations up front so users know why a response might lag.
+            const longRunningModels = multiModels.filter((model) => MODEL_CONFIGS[model]?.reasoning?.effort === 'high');
+            if (longRunningModels.length > 0) {
+                for (const model of longRunningModels) {
+                    log('');
+                    const headingLabel = `[${model}]`;
+                    log(isTty ? kleur.bold(headingLabel) : headingLabel);
+                    log(dim('This model can take up to 60 minutes (usually replies much faster).'));
+                    log(dim('Press Ctrl+C to cancel.'));
+                }
+            }
+            const shouldStreamInline = !muteStdout && process.stdout.isTTY;
+            const shouldRenderMarkdown = shouldStreamInline && runOptions.renderPlain !== true;
+            const printedModels = new Set();
+            const answerFallbacks = new Map();
+            const stripOscProgress = (text) => sanitizeOscProgress(text, shouldStreamInline);
+            const printModelLog = async (model) => {
+                if (printedModels.has(model))
+                    return;
+                printedModels.add(model);
+                const body = stripOscProgress(await sessionStore.readModelLog(sessionMeta.id, model));
+                log('');
+                const fallback = answerFallbacks.get(model);
+                const hasBody = body.length > 0;
+                if (!hasBody && !fallback) {
+                    log(dim(`${model}: (no output recorded)`));
+                    return;
+                }
+                const headingLabel = `[${model}]`;
+                const heading = shouldStreamInline ? kleur.bold(headingLabel) : headingLabel;
+                log(heading);
+                const content = hasBody ? body : fallback ?? '';
+                const printable = shouldRenderMarkdown ? renderMarkdownAnsi(content) : content;
+                writeInline(printable);
+                if (!printable.endsWith('\n')) {
+                    log('');
+                }
+            };
+            const summary = await runMultiModelApiSession({
+                sessionMeta,
+                runOptions,
+                models: multiModels,
+                cwd,
+                version,
+                onModelDone: shouldStreamInline
+                    ? async (result) => {
+                        if (result.answerText) {
+                            answerFallbacks.set(result.model, result.answerText);
+                        }
+                        await printModelLog(result.model);
+                    }
+                    : undefined,
+            }, {
+                runOracleImpl: muteStdout
+                    ? (opts, deps) => runOracle(opts, { ...deps, allowStdout: false })
+                    : undefined,
+            });
+            if (!shouldStreamInline) {
+                // If we couldn't stream inline (e.g., non-TTY), print all logs after completion.
+                for (const [index, result] of summary.fulfilled.entries()) {
+                    if (index > 0) {
+                        log('');
+                    }
+                    await printModelLog(result.model);
+                }
+            }
+            const aggregateUsage = summary.fulfilled.reduce((acc, entry) => ({
+                inputTokens: acc.inputTokens + entry.usage.inputTokens,
+                outputTokens: acc.outputTokens + entry.usage.outputTokens,
+                reasoningTokens: acc.reasoningTokens + entry.usage.reasoningTokens,
+                totalTokens: acc.totalTokens + entry.usage.totalTokens,
+                cost: (acc.cost ?? 0) + (entry.usage.cost ?? 0),
+            }), { inputTokens: 0, outputTokens: 0, reasoningTokens: 0, totalTokens: 0, cost: 0 });
+            const tokensDisplay = [
+                aggregateUsage.inputTokens,
+                aggregateUsage.outputTokens,
+                aggregateUsage.reasoningTokens,
+                aggregateUsage.totalTokens,
+            ]
+                .map((v, idx) => formatTokenValue(v, {
+                input_tokens: aggregateUsage.inputTokens,
+                output_tokens: aggregateUsage.outputTokens,
+                reasoning_tokens: aggregateUsage.reasoningTokens,
+                total_tokens: aggregateUsage.totalTokens,
+            }, idx))
+                .join('/');
+            const costLabel = aggregateUsage.cost != null ? formatUSD(aggregateUsage.cost) : 'cost=N/A';
+            const statusColor = summary.rejected.length === 0 ? kleur.green : summary.fulfilled.length > 0 ? kleur.yellow : kleur.red;
+            const overallText = `${summary.fulfilled.length}/${multiModels.length} models`;
+            log(statusColor(`Finished in ${formatElapsed(summary.elapsedMs)} (${overallText} | ${costLabel} | tok(i/o/r/t)=${tokensDisplay})`));
+            const hasFailure = summary.rejected.length > 0;
+            await sessionStore.updateSession(sessionMeta.id, {
+                status: hasFailure ? 'error' : 'completed',
+                completedAt: new Date().toISOString(),
+                usage: aggregateUsage,
+                elapsedMs: summary.elapsedMs,
+                response: undefined,
+                transport: undefined,
+                error: undefined,
+            });
+            const totalCharacters = summary.fulfilled.reduce((sum, entry) => sum + entry.answerText.length, 0);
+            await sendSessionNotification({
+                sessionId: sessionMeta.id,
+                sessionName: sessionMeta.options?.slug ?? sessionMeta.id,
+                mode,
+                model: `${multiModels.length} models`,
+                usage: aggregateUsage,
+                characters: totalCharacters,
+            }, notificationSettings, log);
+            if (runOptions.writeOutputPath) {
+                const savedOutputs = [];
+                for (const entry of summary.fulfilled) {
+                    const modelOutputPath = deriveModelOutputPath(runOptions.writeOutputPath, entry.model);
+                    const savedPath = await writeAssistantOutput(modelOutputPath, entry.answerText, log);
+                    if (savedPath) {
+                        savedOutputs.push({ model: entry.model, path: savedPath });
+                    }
+                }
+                if (savedOutputs.length > 0) {
+                    log(dim('Saved outputs:'));
+                    for (const item of savedOutputs) {
+                        log(dim(`- ${item.model} -> ${item.path}`));
+                    }
+                }
+            }
+            if (hasFailure) {
+                throw summary.rejected[0].reason;
+            }
+            return;
+        }
+        const singleModelOverride = multiModels.length === 1 ? multiModels[0] : undefined;
+        const apiRunOptions = singleModelOverride
+            ? { ...runOptions, model: singleModelOverride, models: undefined }
+            : runOptions;
+        if (modelForStatus && singleModelOverride == null) {
+            await sessionStore.updateModelRun(sessionMeta.id, modelForStatus, {
+                status: 'running',
+                startedAt: new Date().toISOString(),
+            });
+        }
+        const result = await runOracle(apiRunOptions, {
+            cwd,
+            log,
+            write,
+            allowStdout: !muteStdout,
+        });
+        if (result.mode !== 'live') {
+            throw new Error('Unexpected preview result while running a session.');
+        }
+        await sessionStore.updateSession(sessionMeta.id, {
+            status: 'completed',
+            completedAt: new Date().toISOString(),
+            usage: result.usage,
+            elapsedMs: result.elapsedMs,
+            response: extractResponseMetadata(result.response),
+            transport: undefined,
+            error: undefined,
+        });
+        if (modelForStatus && singleModelOverride == null) {
+            await sessionStore.updateModelRun(sessionMeta.id, modelForStatus, {
+                status: 'completed',
+                completedAt: new Date().toISOString(),
+                usage: result.usage,
+            });
+        }
+        const answerText = extractTextOutput(result.response);
+        await writeAssistantOutput(runOptions.writeOutputPath, answerText, log);
+        await sendSessionNotification({
+            sessionId: sessionMeta.id,
+            sessionName: sessionMeta.options?.slug ?? sessionMeta.id,
+            mode,
+            model: sessionMeta.model ?? runOptions.model,
+            usage: result.usage,
+            characters: answerText.length,
+        }, notificationSettings, log, answerText.slice(0, 140));
+    }
+    catch (error) {
+        const message = formatError(error);
+        log(`ERROR: ${message}`);
+        markErrorLogged(error);
+        const userError = asOracleUserError(error);
+        if (userError) {
+            log(dim(`User error (${userError.category}): ${userError.message}`));
+        }
+        const responseMetadata = error instanceof OracleResponseError ? error.metadata : undefined;
+        const metadataLine = formatResponseMetadata(responseMetadata);
+        if (metadataLine) {
+            log(dim(`Response metadata: ${metadataLine}`));
+        }
+        const transportMetadata = error instanceof OracleTransportError ? { reason: error.reason } : undefined;
+        const transportLine = formatTransportMetadata(transportMetadata);
+        if (transportLine) {
+            log(dim(`Transport: ${transportLine}`));
+        }
+        await sessionStore.updateSession(sessionMeta.id, {
+            status: 'error',
+            completedAt: new Date().toISOString(),
+            errorMessage: message,
+            mode,
+            browser: browserConfig ? { config: browserConfig } : undefined,
+            response: responseMetadata,
+            transport: transportMetadata,
+            error: userError
+                ? {
+                    category: userError.category,
+                    message: userError.message,
+                    details: userError.details,
+                }
+                : undefined,
+        });
+        if (mode === 'browser') {
+            log(dim('Next steps (browser fallback):')); // guides users when automation breaks
+            log(dim('- Rerun with --engine api to bypass Chrome entirely.'));
+            log(dim('- Or rerun with --engine api --render-markdown [--file …] to generate a single markdown bundle you can paste into ChatGPT manually (add --browser-bundle-files if you still want attachments).'));
+        }
+        if (modelForStatus) {
+            await sessionStore.updateModelRun(sessionMeta.id, modelForStatus, {
+                status: 'error',
+                completedAt: new Date().toISOString(),
+            });
+        }
+        throw error;
+    }
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function writeAssistantOutput(targetPath, content, log) {
+    if (!targetPath)
+        return;
+    if (!content || content.trim().length === 0) {
+        log(dim('write-output skipped: no assistant content to save.'));
+        return;
+    }
+    const normalizedTarget = path.resolve(targetPath);
+    const normalizedSessionsDir = path.resolve(SESSIONS_DIR);
+    if (normalizedTarget === normalizedSessionsDir ||
+        normalizedTarget.startsWith(`${normalizedSessionsDir}${path.sep}`)) {
+        log(dim(`write-output skipped: refusing to write inside session storage (${normalizedSessionsDir}).`));
+        return;
+    }
+    try {
+        await fs.mkdir(path.dirname(normalizedTarget), { recursive: true });
+        const payload = content.endsWith('\n') ? content : `${content}\n`;
+        await fs.writeFile(normalizedTarget, payload, 'utf8');
+        log(dim(`Saved assistant output to ${normalizedTarget}`));
+        return normalizedTarget;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        if (isPermissionError(error)) {
+            const fallbackPath = buildFallbackPath(normalizedTarget);
+            if (fallbackPath) {
+                try {
+                    await fs.mkdir(path.dirname(fallbackPath), { recursive: true });
+                    const payload = content.endsWith('\n') ? content : `${content}\n`;
+                    await fs.writeFile(fallbackPath, payload, 'utf8');
+                    log(dim(`write-output fallback to ${fallbackPath} (original failed: ${reason})`));
+                    return fallbackPath;
+                }
+                catch (innerError) {
+                    const innerReason = innerError instanceof Error ? innerError.message : String(innerError);
+                    log(dim(`write-output failed (${reason}); fallback failed (${innerReason}); session completed anyway.`));
+                    return;
+                }
+            }
+        }
+        log(dim(`write-output failed (${reason}); session completed anyway.`));
+    }
+}
+export function deriveModelOutputPath(basePath, model) {
+    if (!basePath)
+        return undefined;
+    const ext = path.extname(basePath);
+    const stem = path.basename(basePath, ext);
+    const dir = path.dirname(basePath);
+    const suffix = ext.length > 0 ? `${stem}.${model}${ext}` : `${stem}.${model}`;
+    return path.join(dir, suffix);
+}
+function isPermissionError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    return code === 'EACCES' || code === 'EPERM';
+}
+function buildFallbackPath(original) {
+    const ext = path.extname(original);
+    const stem = path.basename(original, ext);
+    const dir = getCwd();
+    const candidate = ext ? `${stem}.fallback${ext}` : `${stem}.fallback`;
+    const fallback = path.join(dir, candidate);
+    const normalizedSessionsDir = path.resolve(SESSIONS_DIR);
+    const normalizedFallback = path.resolve(fallback);
+    if (normalizedFallback === normalizedSessionsDir ||
+        normalizedFallback.startsWith(`${normalizedSessionsDir}${path.sep}`)) {
+        return null;
+    }
+    return fallback;
+}

package/dist/src/cli/tagline.js

@@ -0,0 +1,258 @@
+import chalk from 'chalk';
+const TAGLINES = [
+    'Whispering your tokens to the silicon sage.',
+    'Turning scattered files into one sharp question.',
+    'One slug to gather them all.',
+    'Token thrift, oracle lift.',
+    'Globs to gospel, minus the incense.',
+    'Your repo, neatly bottled, gently shaken.',
+    'Clarity, with a hint of smoke.',
+    'Questions in, clarity out.',
+    'Globs become guidance.',
+    'Token-aware, omen-ready.',
+    'Globs go in; citations and costs come out.',
+    'Keeps 196k tokens feeling roomy, not risky.',
+    'Remembers your paths, forgets your past runs.',
+    'A TUI when you want it, a one-liner when you do not.',
+    'Less ceremony, more certainty.',
+    'Guidance without the guesswork.',
+    'One prompt fanned out, no echoes wasted.',
+    'Detached runs, tethered results.',
+    'Calm CLI, loud answers.',
+    'Single scroll, many seers.',
+    'Background magic with foreground receipts.',
+    'Paths aligned, models attuned.',
+    'Light spell, heavy insight.',
+    'Signal first, sorcery second.',
+    'One command, several seers; results stay grounded.',
+    'Context braided, answers sharpened.',
+    'Short incantation, long provenance.',
+    'Attach, cast, reattach later.',
+    'Spell once, cite always.',
+    'Edge cases foretold, receipts attached.',
+    'Silent run, loud receipts.',
+    'Detours gone; clarity walks in.',
+    'Tokens tallied, omens tallied.',
+    'Calm prompt, converged truths.',
+    'Single spell, multiple verdicts.',
+    'Prompt once, harvest many omens.',
+    'Light on ceremony, heavy on receipts.',
+    'From globs to guidance in one breath.',
+    'Quiet prompt, thunderous answers.',
+    'Balanced mystique, measurable results.',
+    'Debugger by day, oracle by night.',
+    "Your code's confessional booth.",
+    'Edge cases fear this inbox.',
+    'Slop in, sharp answers out.',
+    "Your AI coworker's quality control.",
+    "Because vibes aren't a deliverable.",
+    'When the other agents shrug, the oracle ships.',
+    'Hallucinations checked at the door.',
+    'Context police for overeager LLMs.',
+    'Turns prompt spaghetti into ship-ready sauce.',
+    'Lint for large language models.',
+    "Slaps wrists before they hit 'ship'.",
+    "Because 'let the model figure it out' is not QA.",
+    "Fine, I'll write the test for the AI too.",
+    'We bring receipts; they bring excuses.',
+    'Less swagger, more citations.',
+    'LLM babysitter with a shipping agenda.',
+    'Ships facts, not vibes.',
+    'Context sanitizer for reckless prompts.',
+    'AI babysitter with merge rights.',
+    'Stops the hallucination before it hits prod.',
+    'Slop filter set to aggressive.',
+    'We debug the debugger.',
+    'Model said maybe; oracle says ship/no.',
+    'Less lorem, more logic.',
+    "Your prompt's adult supervision.",
+    'Cleanup crew for AI messes.',
+    'AI wrote it? Oracle babysits it.',
+    'Turning maybe into mergeable.',
+    'The AI said vibes; we said tests.',
+    'Cleanup crew for model-made messes—now with citations.',
+    'Less hallucination, more escalation.',
+    "Your AI's ghostwriter, but with citations.",
+    'Where prompt soup becomes production code.',
+    'From shruggy agents to shippable PRs.',
+    'Token mop for agent spillover.',
+    'We QA the AI so you can ship the code.',
+    'Less improv, more implementation.',
+    'Ships facts faster than agents make excuses.',
+    'From prompt chaos to PR-ready prose.',
+    "Your AI's hot take, fact-checked.",
+    'Cleanup crew for LLM loose ends.',
+    'We babysit the bot; you ship the build.',
+    'Prompt drama in; release notes out.',
+    'AI confidence filtered through reality.',
+    "From 'it told me so' to 'tests say so'.",
+    "We refactor the model's hubris before it hits prod.",
+    'Prompt chaos triaged, answers discharged.',
+    'Oracle babysits; you merge.',
+    'Vibes quarantined; facts admitted.',
+    'The cleanup crew for speculative stack traces.',
+    'Ship-ready answers, minus the AI improv.',
+    "We pre-empt the hallucination so you don't triage it at 2am.",
+    'AI confidence monitored, citations required.',
+    'Ship logs, not lore.',
+    'Hallucinations flagged, reality shipped.',
+    'We lint the lore so you can ship the code.',
+    'Hallucination hotline: we answer, not the pager.',
+    'Less mystique, more mergeability.',
+    'Slop filter set past 11.',
+    'Bottled prompt chaos, filtered answers.',
+    "Your AI's swagger, audited.",
+    'New year, same oracle: resolutions shipped, not wished.',
+    'Lunar New Year sweep: clear caches, invite good deploys.',
+    'Eid Mubarak: feast on clarity, fast from hallucinations.',
+    'Diwali: lights on, incident lights off.',
+    'Holi colors on dashboards, not in logs.',
+    "Workers' Day: let oracle haul the heavy context.",
+    'Earth Day: trim carbon, trim token waste.',
+    'Halloween: ship treats, not trick exceptions.',
+    'Independence Day: sparkles in the sky, not in the error console.',
+    'Christmas: all is calm, all is shipped.',
+    'Nowruz reset: sweep caches, welcome clean deploys.',
+    'Hanukkah lights, zero prod fires.',
+    'Ramadan focus: fast from scope creep, feast on clarity.',
+    'Pride Month: more color on the streets, less red in CI.',
+    'Thanksgiving: grateful for green builds, no turkey outages.',
+    'Solstice deploy: longest day, shortest incident list.',
+];
+const DAY_MS = 24 * 60 * 60 * 1000;
+function utcParts(date) {
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth(),
+        day: date.getUTCDate(),
+    };
+}
+const onMonthDay = (month, day) => (date) => {
+    const parts = utcParts(date);
+    return parts.month === month && parts.day === day;
+};
+const onSpecificDates = (dates, durationDays = 1) => (date) => {
+    const parts = utcParts(date);
+    return dates.some(([year, month, day]) => {
+        if (parts.year !== year)
+            return false;
+        const start = Date.UTC(year, month, day);
+        const current = Date.UTC(parts.year, parts.month, parts.day);
+        return current >= start && current < start + durationDays * DAY_MS;
+    });
+};
+const inYearWindow = (windows) => (date) => {
+    const parts = utcParts(date);
+    const window = windows.find((entry) => entry.year === parts.year);
+    if (!window)
+        return false;
+    const start = Date.UTC(window.year, window.month, window.day);
+    const current = Date.UTC(parts.year, parts.month, parts.day);
+    return current >= start && current < start + window.duration * DAY_MS;
+};
+const isFourthThursdayOfNovember = (date) => {
+    const parts = utcParts(date);
+    if (parts.month !== 10)
+        return false; // November
+    const firstDay = new Date(Date.UTC(parts.year, 10, 1)).getUTCDay();
+    const offsetToThursday = (4 - firstDay + 7) % 7; // 4 = Thursday
+    const fourthThursday = 1 + offsetToThursday + 21; // 1st + offset + 3 weeks
+    return parts.day === fourthThursday;
+};
+const HOLIDAY_RULES = new Map([
+    ['New year, same oracle: resolutions shipped, not wished.', onMonthDay(0, 1)],
+    [
+        'Lunar New Year sweep: clear caches, invite good deploys.',
+        onSpecificDates([
+            [2025, 0, 29],
+            [2026, 1, 17],
+            [2027, 1, 6],
+        ], 1),
+    ],
+    [
+        'Eid Mubarak: feast on clarity, fast from hallucinations.',
+        onSpecificDates([
+            [2025, 2, 31],
+            [2026, 2, 20],
+            [2027, 2, 10],
+        ], 1),
+    ],
+    [
+        'Diwali: lights on, incident lights off.',
+        onSpecificDates([
+            [2025, 9, 20],
+            [2026, 10, 8],
+            [2027, 9, 29],
+        ], 1),
+    ],
+    [
+        'Holi colors on dashboards, not in logs.',
+        onSpecificDates([
+            [2025, 2, 14],
+            [2026, 2, 3],
+            [2027, 2, 23],
+        ], 1),
+    ],
+    ["Workers' Day: let oracle haul the heavy context.", onMonthDay(4, 1)],
+    ['Earth Day: trim carbon, trim token waste.', onMonthDay(3, 22)],
+    ['Halloween: ship treats, not trick exceptions.', onMonthDay(9, 31)],
+    [
+        'Independence Day: sparkles in the sky, not in the error console.',
+        onMonthDay(6, 4),
+    ],
+    ['Christmas: all is calm, all is shipped.', onMonthDay(11, 25)],
+    ['Nowruz reset: sweep caches, welcome clean deploys.', onMonthDay(2, 20)],
+    [
+        'Hanukkah lights, zero prod fires.',
+        inYearWindow([
+            { year: 2025, month: 11, day: 14, duration: 8 },
+            { year: 2026, month: 11, day: 4, duration: 8 },
+            { year: 2027, month: 10, day: 24, duration: 8 },
+        ]),
+    ],
+    [
+        'Ramadan focus: fast from scope creep, feast on clarity.',
+        inYearWindow([
+            { year: 2025, month: 1, day: 28, duration: 30 },
+            { year: 2026, month: 1, day: 17, duration: 30 },
+            { year: 2027, month: 1, day: 7, duration: 30 },
+        ]),
+    ],
+    ['Pride Month: more color on the streets, less red in CI.', (date) => utcParts(date).month === 5],
+    ['Thanksgiving: grateful for green builds, no turkey outages.', isFourthThursdayOfNovember],
+    ['Solstice deploy: longest day, shortest incident list.', onMonthDay(5, 21)],
+]);
+function isTaglineActive(tagline, date) {
+    const rule = HOLIDAY_RULES.get(tagline);
+    if (!rule)
+        return true;
+    return rule(date);
+}
+export function activeTaglines(options = {}) {
+    const today = options.now ? options.now() : new Date();
+    const filtered = TAGLINES.filter((tagline) => isTaglineActive(tagline, today));
+    return filtered.length > 0 ? filtered : TAGLINES;
+}
+export function pickTagline(options = {}) {
+    const env = options.env ?? process.env;
+    const override = env?.ORACLE_TAGLINE_INDEX;
+    if (override !== undefined) {
+        const parsed = Number.parseInt(override, 10);
+        if (!Number.isNaN(parsed) && parsed >= 0) {
+            return TAGLINES[parsed % TAGLINES.length];
+        }
+    }
+    const pool = activeTaglines(options);
+    const rand = options.random ?? Math.random;
+    const index = Math.floor(rand() * pool.length) % pool.length;
+    return pool[index];
+}
+export function formatIntroLine(version, options = {}) {
+    const tagline = pickTagline(options);
+    const rich = options.richTty ?? true;
+    if (rich && chalk.level > 0) {
+        return `${chalk.bold('🧿 oracle')} ${version} — ${tagline}`;
+    }
+    return `🧿 oracle ${version} — ${tagline}`;
+}
+export { TAGLINES };