aiden-runtime 4.0.1 → 4.1.0

package/dist/cli/v4/chatSession.js

@@ -19,8 +19,12 @@
  *   5. Re-renders the status line after every turn.
  *
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BOOT_TRY_HINT = exports.ChatSession = void 0;
+exports.renderCommandLabel = renderCommandLabel;
 exports.detectOS = detectOS;
 exports.detectShell = detectShell;
 exports.formatStatusState = formatStatusState;
@@ -30,8 +34,38 @@ exports.renderProgressBar = renderProgressBar;
 exports.formatTokens = formatTokens;
 exports.formatDuration = formatDuration;
 exports.renderMemoryConfirmations = renderMemoryConfirmations;
+const display_1 = require("./display");
+const uiBuild_1 = require("./uiBuild");
+const aidenPrompt_1 = __importDefault(require("./aidenPrompt"));
+const historyStore_1 = require("./historyStore");
 const modelMetadata_1 = require("../../core/v4/modelMetadata");
 const bracketedPaste_1 = require("./bracketedPaste");
+const pasteCompression_1 = require("./pasteCompression");
+const pasteIntercept_1 = require("./pasteIntercept");
+const shellInterpolation_1 = require("./shellInterpolation");
+const resizeGuard_1 = require("./resizeGuard");
+/**
+ * Tier-3.1 helper: render a slash-command label honouring the
+ * `AIDEN_UI_ICONS` opt-in. Default OFF — emoji icons are gated to
+ * keep the dropdown ASCII-clean for terminals without good emoji
+ * support. `AIDEN_UI_ICONS=1` recovers the previous icon column.
+ */
+function renderCommandLabel(cmd) {
+    return cmd.icon && (0, uiBuild_1.uiIconsEnabled)()
+        ? `${cmd.icon} /${cmd.name}`
+        : `/${cmd.name}`;
+}
+/** Aiden version pulled from package.json at require-time; falls back
+ *  to a static literal so TS compiles without a JSON resolution wobble. */
+const AIDEN_VERSION = (() => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require('../../package.json').version ?? '4.0.0';
+    }
+    catch {
+        return '4.0.0';
+    }
+})();
 const STATUS_BAR_WIDTH = 10;
 class ChatSession {
     constructor(opts) {
@@ -129,7 +163,15 @@ class ChatSession {
             process.on('SIGINT', sigintHandler);
         }
         // 4. Main loop.
-        const promptApi = this.opts.promptApi ?? createDefaultPromptApi();
+        // Tier-3.1.1: feed the new aidenPrompt with live slash commands +
+        // recent history so ghost-text + dropdown work out of the box.
+        // The legacy inquirer path runs when `--no-ui` (AIDEN_NO_UI=1) is
+        // set or when a caller injects its own `promptApi`.
+        const promptApi = this.opts.promptApi ??
+            createDefaultPromptApi({
+                commands: this.opts.commandRegistry.list(),
+                loadHistory: () => (0, historyStore_1.loadRecent)(500),
+            });
         const max = this.opts.maxIterations ?? Number.POSITIVE_INFINITY;
         let iter = 0;
         // Phase 16: enable bracketed paste for the duration of the REPL when
@@ -139,6 +181,25 @@ class ChatSession {
         const pasteEnabled = stdout?.isTTY && !this.opts.promptApi
             ? (0, bracketedPaste_1.enableBracketedPaste)(stdout)
             : false;
+        // Tier-3.1a: install stdin pre-tap so bracketed paste payloads are
+        // captured and replaced with `[paste #N: …]` labels BEFORE inquirer
+        // sees them. Without this, modern @inquirer/prompts treats internal
+        // `\n` as Enter and auto-submits the first line of a multi-line paste.
+        // Tier-3.1c: install regardless of TTY status. Bracketed-paste
+        // sequences can arrive on a piped stdin too (CI harnesses, the
+        // runtime smoke), and the interceptor's wrap is a no-op on
+        // non-paste data — there's no cost to installing always. The
+        // promptApi opt-out remains so callers that supply their own
+        // input plumbing aren't surprised.
+        const restorePasteInterceptor = this.opts.promptApi
+            ? () => { }
+            : (0, pasteIntercept_1.installPasteInterceptor)(process.stdin);
+        // Tier-3-essentials: hard-clear the screen on terminal resize so
+        // dropdown re-renders + previous prompt frames don't ghost into
+        // the new viewport. No-op on non-TTY / MCP serve mode.
+        const restoreResizeGuard = this.opts.promptApi
+            ? () => { }
+            : (0, resizeGuard_1.installResizeGuard)();
         try {
             while (iter < max) {
                 iter += 1;
@@ -178,6 +239,7 @@ class ChatSession {
                         personalityManager: this.opts.personalityManager,
                         agent: this.opts.agent,
                         pluginLoader: this.opts.pluginLoader,
+                        channelManager: this.opts.channelManager,
                         confirm: async (msg) => {
                             // Phase 17.1: bug — was reading `this.opts.promptApi?` which is
                             // undefined when no override is passed; the chain silently
@@ -208,13 +270,30 @@ class ChatSession {
                 process.off('SIGINT', sigintHandler);
             if (pasteEnabled)
                 (0, bracketedPaste_1.disableBracketedPaste)(stdout);
+            restorePasteInterceptor();
+            restoreResizeGuard();
         }
     }
     // ── Inner: a single agent turn ─────────────────────────────────────
     async runAgentTurn(userInput) {
+        // Phase 30.2.1 — explore mode: short-circuit BEFORE building the
+        // turn-status spinner / agent call. The wizard skipped, so there's
+        // no real provider to talk to. Print a friendly redirect to /setup
+        // (or the env-var alternative) and return — REPL stays alive, user
+        // can run slash commands or hit /quit.
+        if (this.opts.unconfigured) {
+            void userInput; // silence unused-arg warning when this branch fires
+            this.opts.display.write('\n');
+            this.opts.display.printError('No AI provider configured yet.', 'Run /setup to configure a provider, or set an API key environment variable (e.g. GROQ_API_KEY).');
+            this.opts.display.write('\n');
+            return;
+        }
         // Phase 22 Task 4: status bar reflects the live phase. Set on
         // entry, cleared in both success and error paths below.
         this.setStatusState({ kind: 'generating', sinceMs: Date.now() });
+        // Tier-3.1a: dim full-width rule between the user input echo and
+        // the agent reply for clean visual rhythm.
+        this.opts.display.write(`  ${this.opts.display.rule()}\n`);
         // Phase 26.2.3 — blank line between the user-input echo and the
         // spinner / response so the eye sees user → agent as separate
         // beats instead of butting together.
@@ -301,6 +380,9 @@ class ChatSession {
             }
             this.setStatusState({ kind: 'ready' });
             this.lastTurnElapsedMs = Date.now() - turnStartedAt;
+            // Tier-3.1a: dim full-width rule between the agent reply and the
+            // post-turn status footer.
+            this.opts.display.write(`  ${this.opts.display.rule()}\n`);
             this.renderStatusLine();
         }
         catch (err) {
@@ -339,57 +421,107 @@ class ChatSession {
     // collapses to plain 4-line credits below 75 cols.
     async renderStartupCard() {
         const display = this.opts.display;
+        // Tier-3.1a: skip entirely on non-TTY so piped/scripted callers
+        // don't get scrollback chatter on stdout.
+        if (!process.stdout.isTTY)
+            return;
+        // Channel summary — observable, not banner-essential, but kept so
+        // status pills aren't the only place a user sees telegram health.
+        const cm = this.opts.channelManager;
+        if (cm) {
+            const adapterStatuses = cm.getStatus().map((s) => {
+                const adapter = cm.get(s.name);
+                const tg = adapter;
+                const botHandle = typeof tg?.getBotUsername === 'function' ? tg.getBotUsername() : null;
+                const state = typeof tg?.getState === 'function' ? tg.getState() : undefined;
+                return { id: s.name, healthy: s.healthy, botHandle, state };
+            });
+            void (0, display_1.summarizeChannelState)({ adapters: adapterStatuses });
+        }
+        else {
+            void (0, display_1.summarizeChannelState)(null);
+        }
+        const cols = display.cols();
+        const isNarrow = cols < 60;
+        const showEnvCapBlock = cols >= 70;
+        const version = AIDEN_VERSION;
         display.write('\n');
-        display.printBanner();
-        display.write(`  ${display.muted('Autonomous AI Engine')}\n`);
-        display.write('\n');
-        // Detection
-        const toolsCount = this.opts.toolRegistry.list().length;
-        let skillsLoaded = 0;
-        try {
-            skillsLoaded = (await this.opts.skillLoader.list()).length;
+        if (isNarrow) {
+            // Compact — single-line text logo + one-line capability summary.
+            display.write(`  ${display.brand('AIDEN')}  ${display.muted(`v${version}`)}\n`);
+            display.write(`  ${display.muted('Local AI · controls your computer · never forgets')}\n`);
         }
-        catch {
-            skillsLoaded = 0;
+        else {
+            // Wide — full ASCII art + subtitle. Tier-3.1c: dropped the
+            // tagline + sponsor lines from the top section because they
+            // duplicate the credits already inside the scrollFooter at
+            // the bottom of the boot card. Subtitle stays — it's the only
+            // brand anchor between the ASCII art and the pills row.
+            display.printBanner(version);
+            display.write(`  ${display.muted('Autonomous AI Engine')}\n`);
+            display.write('\n');
         }
-        // PIECE 1 — status pills row.
+        // Status pills.
         display.write(display.statusPillsRow({
             coreOnline: true,
             mode: 'auto',
             model: this.currentModelId,
             memoryActive: true,
+            providerOk: !this.opts.unconfigured,
         }) + '\n');
+        // Tier-3.1b: rule + environment/capabilities block + rule + scroll
+        // + bottom prompt hint. Skipped at <70 cols to keep the narrow
+        // boot card from wrapping into noise.
         display.write(`  ${display.rule()}\n`);
-        display.write('\n');
-        // PIECE 2 — Environment + Capabilities block.
-        display.write(display.twoColumnBlock({
-            title: 'Environment',
-            rows: [
-                { key: 'OS', value: detectOS() },
-                { key: 'shell', value: detectShell() },
-                { key: 'runtime', value: 'local-first' },
-                { key: 'tools', value: `${toolsCount} loaded` },
-                { key: 'skills', value: `${skillsLoaded} loaded` },
-            ],
-        }, {
-            title: 'Capabilities',
-            rows: [
-                { key: 'web', value: 'research · extract' },
-                { key: 'browser', value: 'navigate · automate' },
-                { key: 'files', value: 'read · patch · organize' },
-                { key: 'execution', value: 'shell · code · workflows' },
-                { key: 'memory', value: 'persistent recall' },
-            ],
-        }) + '\n');
-        display.write('\n');
-        display.write(`  ${display.rule()}\n`);
-        display.write('\n');
-        // PIECE 3 — scroll footer with credits.
+        if (showEnvCapBlock) {
+            // Detect environment lazily (cheap on every boot — no caching
+            // needed; tools/skills counts are already loaded by this point).
+            const toolsCount = this.opts.toolRegistry.list().length;
+            let skillsLoaded = 0;
+            try {
+                skillsLoaded = (await this.opts.skillLoader.list()).length;
+            }
+            catch {
+                skillsLoaded = 0;
+            }
+            display.write('\n');
+            // Pass sideBySideThreshold=120 so 70-119 cols stack vertically
+            // (per the tier3.1b dispatch's width-tier policy) and only
+            // ≥120 renders the full side-by-side block.
+            display.write(display.twoColumnBlock({
+                title: 'Environment',
+                rows: [
+                    { key: 'OS', value: detectOS() },
+                    { key: 'shell', value: detectShell() },
+                    { key: 'runtime', value: 'local-first' },
+                    { key: 'tools', value: `${toolsCount} loaded` },
+                    { key: 'skills', value: `${skillsLoaded} loaded` },
+                ],
+            }, {
+                title: 'Capabilities',
+                rows: [
+                    { key: 'web', value: 'research · extract' },
+                    { key: 'browser', value: 'navigate · automate' },
+                    { key: 'files', value: 'read · patch · organize' },
+                    { key: 'execution', value: 'shell · code · workflows' },
+                    { key: 'memory', value: 'persistent recall' },
+                ],
+            }, 
+            // Tier-3.1c: lowered from 120 → 100 so wide-but-not-huge
+            // terminals (laptop screens, default Windows Terminal) get
+            // the side-by-side block instead of the stacked fallback.
+            // Each column at ~38 chars + 4-char separator + 2-char
+            // indent fits in 82 chars; 100 leaves 18 chars headroom.
+            { sideBySideThreshold: 100 }) + '\n');
+            display.write('\n');
+            display.write(`  ${display.rule()}\n`);
+            display.write('\n');
+        }
+        // Scroll footer (parchment at ≥80 cols, single-line credits below).
         display.write(display.scrollFooter() + '\n');
+        // Bottom prompt hint — final line of the boot card.
         display.write('\n');
-        // PIECE 4 — bottom prompt hint.
         display.write(display.bottomPromptHint() + '\n');
-        display.write('\n');
     }
     /** Phase 22 Task 4: state transitions for the right-most segment. */
     setStatusState(state) {
@@ -435,14 +567,19 @@ class ChatSession {
         let raw = await api.readLine(promptText);
         if (raw == null)
             return '';
-        // Bracketed paste polish (Phase 16): if the terminal sent paste markers,
-        // strip them and accept the entire payload as one message. This replaces
-        // Phase 15's timing heuristic when the terminal supports CSI 2004; the
-        // timing fallback remains for older Console hosts that don't.
+        // Tier-3.1a: stdin pre-tap (pasteIntercept) already converted any
+        // bracketed-paste payload into a `[paste #N: …]` label before
+        // inquirer saw it. Swap the label back for the original here so
+        // the agent receives full content. User-typed labels with unknown
+        // ids are left untouched.
+        raw = (0, pasteIntercept_1.expandPasteLabels)(raw);
+        // Bracketed paste polish (Phase 16): if the terminal still sent
+        // paste markers (interceptor disabled — non-TTY or test promptApi),
+        // strip them and accept the entire payload as one message.
         if ((0, bracketedPaste_1.hasPasteMarkers)(raw)) {
             const stripped = (0, bracketedPaste_1.stripPasteMarkers)(raw).replace(/\r/g, '');
             if ((0, bracketedPaste_1.isCompletePaste)(raw))
-                return stripped;
+                return await this.maybeCompressVisiblePaste(stripped);
             // Unterminated paste — still return the stripped content so the user
             // doesn't see escape sequences in their prompt.
             raw = stripped;
@@ -453,7 +590,7 @@ class ChatSession {
             const inline = raw.slice(3);
             // Single-line `"""hello"""` shortcut.
             if (inline.endsWith('"""')) {
-                return inline.slice(0, -3);
+                return await this.maybeCompressVisiblePaste(inline.slice(0, -3));
             }
             const buffer = [inline];
             while (true) {
@@ -466,13 +603,22 @@ class ChatSession {
                 }
                 buffer.push(next);
             }
-            return buffer.join('\n').trim();
+            return await this.maybeCompressVisiblePaste(buffer.join('\n').trim());
         }
-        // Paste detection: multiple lines arrived in a single chunk. Accept verbatim.
+        // Paste detection: multiple lines arrived in a single chunk. The
+        // interceptor + expandPasteLabels path already produced the original
+        // text — no extra echo needed since the user saw the `[paste #N: …]`
+        // label in the input buffer. Pass the original through unchanged.
         if (raw.includes('\n'))
             return raw;
-        // Slash command: invoke the autocomplete dropdown if registry has matches.
-        if (raw.startsWith('/')) {
+        // Slash command: invoke the legacy autocomplete dropdown only
+        // when --no-ui (AIDEN_NO_UI=1) is set. The new aidenPrompt
+        // handles the dropdown inline as the user types, so re-opening
+        // a second prompt here would double-prompt — once in
+        // aidenPrompt, once in inq.search. Tier-3.1.1 routes everything
+        // through aidenPrompt unless the legacy path is explicitly
+        // requested.
+        if ((0, uiBuild_1.isNoUiMode)() && raw.startsWith('/')) {
             const matches = this.opts.commandRegistry.filter(raw);
             if (matches.length > 1) {
                 try {
@@ -481,7 +627,7 @@ class ChatSession {
                         return this.opts.commandRegistry
                             .filter(filterStr)
                             .map((cmd) => ({
-                            name: cmd.icon ? `${cmd.icon} /${cmd.name}` : `/${cmd.name}`,
+                            name: renderCommandLabel(cmd),
                             value: `/${cmd.name}`,
                             description: cmd.description,
                         }));
@@ -494,8 +640,48 @@ class ChatSession {
                 }
             }
         }
+        // Tier-3-essentials: inline shell interpolation. If the prompt
+        // contains `{!cmd}` spans, run each in parallel (5s timeout per
+        // span, 500-char output cap) and splice the output back in. The
+        // rewritten prompt is what reaches the agent — visible feedback
+        // is a single dim line so the user sees that the work happened.
+        if ((0, shellInterpolation_1.hasInterpolation)(raw)) {
+            const spans = (0, shellInterpolation_1.countSpans)(raw);
+            this.opts.display.dim(`[shell] running ${spans} interpolation${spans === 1 ? '' : 's'}…`);
+            try {
+                raw = await (0, shellInterpolation_1.expand)(raw);
+            }
+            catch {
+                // expand() never rejects, but defence-in-depth.
+            }
+        }
         return raw;
     }
+    /**
+     * Tier-3.1: when a paste is large (>5 lines OR >500 chars), echo a
+     * compact `[paste #<id>: …]` label to the user and persist the
+     * original to disk so `/show <id>` can recall it later. The agent
+     * still receives the full original text — only the visible echo is
+     * compressed.
+     *
+     * MCP serve mode never reaches this path (REPL doesn't run there),
+     * so the display.write here is safe.
+     */
+    async maybeCompressVisiblePaste(text) {
+        try {
+            const result = await (0, pasteCompression_1.compressPaste)(text);
+            if (result.compressed && result.label) {
+                // Echo the label only — newline-terminated for cleanliness.
+                this.opts.display.write(`  ${this.opts.display.muted(result.label)}\n`);
+            }
+        }
+        catch {
+            // Paste compression is a polish feature; if disk write fails we
+            // silently fall through to the original text rather than crash
+            // the prompt loop.
+        }
+        return text;
+    }
 }
 exports.ChatSession = ChatSession;
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -654,7 +840,7 @@ function formatDuration(ms) {
     const remMin = min % 60;
     return remMin > 0 ? `${hr}h${remMin}m` : `${hr}h`;
 }
-function createDefaultPromptApi() {
+function createDefaultPromptApi(opts = {}) {
     // Lazy-load @inquirer/prompts so test harnesses without a TTY don't break.
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const inq = require('@inquirer/prompts');
@@ -663,10 +849,37 @@ function createDefaultPromptApi() {
     // shows alone.  We pass per-status entries so the answered echo also
     // stays clean; `loading` is intentionally untouched (spinner state).
     const promptTheme = { prefix: { idle: '', done: '' } };
+    // Tier-3.1.1: when `--no-ui` (AIDEN_NO_UI=1) is set, fall back to
+    // the legacy inquirer prompt path. Otherwise use the new
+    // aidenPrompt component (ghost text + slash dropdown + history nav).
+    const useLegacyPrompt = (0, uiBuild_1.isNoUiMode)() || !opts.commands;
     return {
         async readLine(prompt) {
             try {
-                return (await inq.input({ message: prompt, theme: promptTheme })) ?? '';
+                if (useLegacyPrompt) {
+                    return (await inq.input({ message: prompt, theme: promptTheme })) ?? '';
+                }
+                // Fetch history just-in-time so each read sees the latest
+                // (the user's previous turn was just appended).
+                const history = opts.loadHistory ? await opts.loadHistory() : [];
+                const value = await (0, aidenPrompt_1.default)({
+                    message: prompt,
+                    commands: opts.commands ?? [],
+                    history,
+                    theme: promptTheme,
+                });
+                const trimmed = (value ?? '').trim();
+                // Append to disk history. Awaited so the write flushes before
+                // the agent loop progresses — `/quit` exits the process and
+                // a fire-and-forget write would race the exit. The latency
+                // on a single appended line is negligible (~ms).
+                if (trimmed.length > 0) {
+                    try {
+                        await (0, historyStore_1.appendHistory)(trimmed);
+                    }
+                    catch { /* best-effort */ }
+                }
+                return value ?? '';
             }
             catch (err) {
                 // Inquirer wraps Ctrl+C as ExitPromptError. Re-throw as plain Error
@@ -676,6 +889,10 @@ function createDefaultPromptApi() {
             }
         },
         async selectSlashCommand(source) {
+            // Tier-3.1.1: aidenPrompt handles the slash dropdown inline so
+            // this hook is rarely invoked. The legacy path stays available
+            // for `--no-ui` callers + any external promptApi shim that
+            // doesn't wrap aidenPrompt directly.
             try {
                 return (await inq.search({ message: '/', source, theme: promptTheme }));
             }

package/dist/cli/v4/citationFooter.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod). Licensed under AGPL-3.0.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/citationFooter.ts — Phase v4.1-reply-formatting
+ *
+ * Optional post-reply "Sources" footer. Detects URLs in recent
+ * tool-call results (fetch_url, web_fetch, web_search, open_url,
+ * fetch_page) and renders a numbered list at the end of an agent
+ * turn. Default OFF — gated on `AIDEN_CITATIONS=1`.
+ *
+ *     ──────
+ *     Sources
+ *       [1] forbes.com/sites/craigsmith/...
+ *       [2] safe.ai/newsletter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSources = extractSources;
+exports.buildCitationFooter = buildCitationFooter;
+exports.renderCitationFooter = renderCitationFooter;
+const skinEngine_1 = require("./skinEngine");
+const SOURCE_TOOL_RE = /^(fetch_url|fetch_page|web_search|web_fetch|open_url|browser_get_url|browser_extract|deep_research)$/i;
+const URL_RE = /\bhttps?:\/\/[^\s<>"'\\)\]]+/g;
+const MAX_DISPLAY_LEN = 80;
+/** Strip `https?://` and trailing slashes for compact display. */
+function shortenUrl(url) {
+    let s = url.replace(/^https?:\/\//i, '').replace(/\/+$/, '');
+    if (s.length > MAX_DISPLAY_LEN)
+        s = s.slice(0, MAX_DISPLAY_LEN - 1) + '…';
+    return s;
+}
+/**
+ * Walk a trace, emit deduplicated URLs in first-seen order. Only
+ * traces whose tool name matches `SOURCE_TOOL_RE` contribute. Both
+ * args and result are scanned — args catch the `url:` arg, result
+ * catches URLs returned in extracted text.
+ */
+function extractSources(trace) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of trace) {
+        if (!SOURCE_TOOL_RE.test(entry.name))
+            continue;
+        const blob = JSON.stringify({ args: entry.args ?? null, result: entry.result ?? null });
+        const matches = blob.match(URL_RE);
+        if (!matches)
+            continue;
+        for (const url of matches) {
+            // Strip trailing punctuation that the regex sometimes catches.
+            const clean = url.replace(/[.,;:!?]+$/, '');
+            if (!seen.has(clean)) {
+                seen.add(clean);
+                out.push(clean);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Build the rendered footer string. Returns an empty string when
+ * there are no sources to surface (caller can skip the line entirely).
+ *
+ * The OSC8 wrapper makes URLs clickable in modern terminals; the
+ * visible label is the shortened form for compact display.
+ */
+function buildCitationFooter(sources) {
+    if (sources.length === 0)
+        return '';
+    const sk = (0, skinEngine_1.getSkinEngine)();
+    const m = (s) => sk.applyColors(s, 'muted');
+    const lab = (s) => sk.applyColors(s, 'brand');
+    const val = (s) => sk.applyColors(s, 'accent');
+    const rule = m('──────');
+    const header = lab('Sources');
+    const lines = sources.map((url, i) => {
+        const idx = m(`[${i + 1}]`);
+        const display = shortenUrl(url);
+        // OSC8 hyperlink — the visible text is `display`, the link target
+        // is the full URL.
+        const linked = `\x1b]8;;${url}\x1b\\${val(display)}\x1b]8;;\x1b\\`;
+        return `  ${idx} ${linked}`;
+    });
+    return [rule, header, ...lines, ''].join('\n') + '\n';
+}
+/**
+ * Convenience: extract + build in one go. Returns '' when the env
+ * gate is off or no sources surface.
+ */
+function renderCitationFooter(trace) {
+    if (process.env.AIDEN_CITATIONS !== '1')
+        return '';
+    const sources = extractSources(trace);
+    return buildCitationFooter(sources);
+}