codeep 2.18.1 → 2.20.0

package/dist/renderer/Screen.d.ts

@@ -73,6 +73,19 @@ export declare class Screen {
     /**
      * Full render (no diff, redraw everything)
      */
+    /**
+     * Force the next `render()` to repaint every cell.
+     *
+     * The differential renderer skips a cell whose buffer value already matches
+     * the shadow copy — correct only while nothing else writes to the terminal.
+     * The inline overlays (session picker, confirm prompt) draw below the managed
+     * area and scroll it, after which the shadow no longer describes what is on
+     * screen and stale glyphs survive: most visibly a leftover character in
+     * column 0 of the header, which the header never overwrites because it starts
+     * at x = 1. Resizing already recovered by rebuilding both buffers; this is the
+     * same recovery without making the user resize the window.
+     */
+    invalidate(): void;
     fullRender(): void;
     /**
      * Initialize screen (hide cursor, clear)

package/dist/renderer/Screen.js

@@ -286,6 +286,28 @@ export class Screen {
     /**
      * Full render (no diff, redraw everything)
      */
+    /**
+     * Force the next `render()` to repaint every cell.
+     *
+     * The differential renderer skips a cell whose buffer value already matches
+     * the shadow copy — correct only while nothing else writes to the terminal.
+     * The inline overlays (session picker, confirm prompt) draw below the managed
+     * area and scroll it, after which the shadow no longer describes what is on
+     * screen and stale glyphs survive: most visibly a leftover character in
+     * column 0 of the header, which the header never overwrites because it starts
+     * at x = 1. Resizing already recovered by rebuilding both buffers; this is the
+     * same recovery without making the user resize the window.
+     */
+    invalidate() {
+        // Fill the shadow with a sentinel no real cell can hold, NOT with spaces.
+        // createEmptyBuffer() fills with ' ', which still compares EQUAL to a blank
+        // buffer cell — so every blank stayed skipped and column 0 of the header
+        // (the wordmark starts at x = 1) was never emitted at all. Whatever the
+        // terminal happened to show there survived indefinitely.
+        const impossible = '\u0000';
+        this.rendered = Array.from({ length: this.height }, () => Array.from({ length: this.width }, () => ({ char: impossible, style: impossible })));
+        process.stdout.write('\x1b[2J');
+    }
     fullRender() {
         let output = cursor.hide + cursor.home;
         let lastStyle = '';

package/dist/renderer/commands/registry.js

@@ -197,7 +197,7 @@ export const COMMANDS = [
         category: 'settings',
         usage: ['save <name>', 'list', 'apply <name>', 'delete <name>'],
     },
-    { name: 'personality', description: 'List or switch agent tone (concise / verbose / security / senior-reviewer / …)', category: 'settings', usage: ['<name>', 'off'] },
+    { name: 'personality', description: 'List or switch a personality or structured custom bot', category: 'settings', usage: ['<name>', 'off'] },
     {
         name: 'me',
         description: 'Your user profile (reply language, style, stack) — adapts the agent to you',
@@ -441,8 +441,8 @@ export const HELP_LAYOUT = [
             { key: '/profile save <name>', description: 'Save current provider+model as profile' },
             { key: '/profile list', description: 'List saved profiles' },
             { key: '/openrouter', description: 'OpenRouter routing prefs (prefer/ignore providers, fallbacks, privacy)' },
-            { key: '/personality', description: 'List or switch agent tone (concise / verbose / security / senior-reviewer / …)' },
-            { key: '/personality <name>', description: 'Activate a personality. /personality off to clear.' },
+            { key: '/personality', description: 'List personalities and custom bots with model, tools, and scope' },
+            { key: '/personality <name>', description: 'Activate a personality or custom bot. /personality off to clear.' },
             { key: '/me', description: 'Your user profile (reply language, style, stack) — adapts the agent to you' },
             { key: '/me init [project]', description: 'Scaffold a profile template (global, or for this project). /me off to disable' },
             { key: '/me learn [on|off]', description: 'Learn durable prefs from this session now; on/off toggles auto-learn. /me forget clears it' },

package/dist/renderer/commands.js

@@ -5,7 +5,7 @@
  * decoupled from global state. Import-heavy commands use dynamic imports
  * to keep startup time low.
  */
-import { config, getCurrentProvider, getModelsForCurrentProvider, PROTOCOLS, LANGUAGES, setProvider, setApiKey, clearApiKey, getApiKey, isTelemetryEnabled, telemetryForcedOffByEnv, isKeySyncEnabled, keySyncForcedOffByEnv, saveSession, startNewSession, loadSession, listSessionsWithInfo, deleteSession, renameSession, setProjectPermission, saveProfile, loadProfile, applyProfile, listProfiles, deleteProfile, initializeAsProject, isManuallyInitializedProject, } from '../config/index.js';
+import { config, getCurrentProvider, getModelsForCurrentProvider, PROTOCOLS, LANGUAGES, setProvider, setApiKey, clearApiKey, getApiKey, saveSession, startNewSession, loadSession, listSessionsWithInfo, deleteSession, renameSession, setProjectPermission, saveProfile, loadProfile, applyProfile, listProfiles, deleteProfile, initializeAsProject, isManuallyInitializedProject, } from '../config/index.js';
 import { getProjectContext } from '../utils/project.js';
 import { getCurrentVersion } from '../utils/update.js';
 import { getProviderList, getProvider, modelSupportsReasoningEffort, reasoningParamsFor, availableReasoningTiers, resolveReasoningTier, REASONING_TIERS } from '../config/providers.js';
@@ -15,6 +15,8 @@ import { loadProjectIntelligence, saveProjectIntelligence } from '../utils/proje
 import { ollamaModelHint } from './ollamaHint.js';
 import { buildSearchSnippets, parseKeepRecent, joinSessionName, parseTaskAddArgs, formatTaskList, formatProfileList, formatMemoryList, formatStatsReport, extractCodeBlocks, resolveBlockIndex, extractFileChanges, formatApplyDiffLine, parsePromptArgs, formatMcpReloadReport, formatMcpResourcesList, formatMcpResourceRead, formatMcpPromptsList, formatMcpPromptResult, formatMcpServerList, parseInsightsDays, formatCloudSessionLabel, formatMeSyncReport, formatMeLearnResult, formatMeInitResult, formatSkillsShow, formatSkillsBrowseEmpty, formatSkillsPublishResult } from './commands/helpers.js';
 import { resolveCommand } from './commands/registry.js';
+import { telemetryCommand } from '../commands/core/telemetry.js';
+import { keysyncCommand } from '../commands/core/keysync.js';
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Returns a hint for an Ollama model name based on parameter count.
@@ -262,61 +264,27 @@ export async function handleCommand(command, args, ctx) {
             break;
         }
         case 'telemetry': {
-            const sub = args[0]?.toLowerCase();
-            const envOff = telemetryForcedOffByEnv();
-            if (sub === 'on' || sub === 'off') {
-                if (envOff) {
-                    ctx.app.notify('Telemetry is forced OFF by CODEEP_NO_TELEMETRY / DO_NOT_TRACK — unset that env var to change it.');
-                    break;
-                }
-                config.set('telemetry', sub === 'on');
-                ctx.app.notify(sub === 'on'
-                    ? 'Telemetry on — usage stats, transcripts, progress & notes sync to codeep.dev.'
-                    : 'Telemetry off — no automatic cloud uploads.');
-                break;
+            // Core semantics in commands/core/telemetry.ts — this surface renders
+            // status as a banner system message, everything else as a notification.
+            const result = telemetryCommand(args);
+            if (result.kind === 'info') {
+                ctx.app.addMessage({ role: 'system', content: `## Telemetry\n\n${result.message}` });
             }
-            if (sub && sub !== 'status') {
-                ctx.app.notify('Usage: /telemetry · /telemetry on · /telemetry off');
-                break;
+            else {
+                ctx.app.notify(result.message);
             }
-            const flag = config.get('telemetry') !== false;
-            const tLines = ['## Telemetry', ''];
-            tLines.push(`**State**      ${isTelemetryEnabled() ? 'on' : 'off'}`);
-            tLines.push(`**Flag**       telemetry = ${flag}`);
-            if (envOff)
-                tLines.push('**Env**        forced off by CODEEP_NO_TELEMETRY / DO_NOT_TRACK (overrides the flag)');
-            tLines.push('');
-            tLines.push('Toggle with `/telemetry on` or `/telemetry off`. Controls automatic uploads of usage stats, session transcripts, progress, and memory notes.');
-            ctx.app.addMessage({ role: 'system', content: tLines.join('\n') });
             break;
         }
         case 'keysync': {
-            const sub = args[0]?.toLowerCase();
-            const envOff = keySyncForcedOffByEnv();
-            if (sub === 'on' || sub === 'off') {
-                if (envOff) {
-                    ctx.app.notify('Cloud key sync is forced OFF by CODEEP_NO_KEY_SYNC — unset that env var to change it.');
-                    break;
-                }
-                config.set('syncKeysToCloud', sub === 'on');
-                ctx.app.notify(sub === 'on'
-                    ? 'Cloud key sync on — `codeep account push/sync` will now upload/download API keys. Note: synced keys are stored server-readable on codeep.dev.'
-                    : 'Cloud key sync off — API keys stay in your OS keychain only. (Run `codeep account purge-keys` to also wipe any keys already on the server.)');
-                break;
+            // Core semantics in commands/core/keysync.ts — this surface renders
+            // status as a banner system message, everything else as a notification.
+            const result = keysyncCommand(args);
+            if (result.kind === 'info') {
+                ctx.app.addMessage({ role: 'system', content: `## Cloud key sync\n\n${result.message}` });
             }
-            if (sub && sub !== 'status') {
-                ctx.app.notify('Usage: /keysync · /keysync on · /keysync off');
-                break;
+            else {
+                ctx.app.notify(result.message);
             }
-            const flag = config.get('syncKeysToCloud') === true;
-            const kLines = ['## Cloud key sync', ''];
-            kLines.push(`**State**      ${isKeySyncEnabled() ? 'on' : 'off'}`);
-            kLines.push(`**Flag**       syncKeysToCloud = ${flag}`);
-            if (envOff)
-                kLines.push('**Env**        forced off by CODEEP_NO_KEY_SYNC (overrides the flag)');
-            kLines.push('');
-            kLines.push('OFF by default. API keys live only in your OS keychain unless you turn this on. When on, `codeep account push`/`sync` upload/download keys, which are stored **server-readable** on codeep.dev. Toggle with `/keysync on` or `/keysync off`; wipe server copies with `codeep account purge-keys`.');
-            ctx.app.addMessage({ role: 'system', content: kLines.join('\n') });
             break;
         }
         case 'effort':
@@ -454,7 +422,7 @@ export async function handleCommand(command, args, ctx) {
             break;
         }
         case 'personality': {
-            const { formatPersonalityList, findPersonality } = await import('../utils/personalities.js');
+            const { formatPersonalityList, findPersonality, formatPersonalityActivation } = await import('../utils/personalities.js');
             const sub = args[0]?.toLowerCase();
             if (!sub) {
                 ctx.app.addMessage({ role: 'system', content: formatPersonalityList(ctx.projectPath) });
@@ -473,7 +441,7 @@ export async function handleCommand(command, args, ctx) {
             config.set('activePersonality', personality.name);
             ctx.app.addMessage({
                 role: 'system',
-                content: `Active personality: **${personality.displayName}** (\`${personality.name}\`, ${personality.scope})\n\n_${personality.description}_\n\nClear with \`/personality off\`.`,
+                content: formatPersonalityActivation(personality),
             });
             break;
         }

package/dist/renderer/components/CommandAutocomplete.d.ts

@@ -0,0 +1,46 @@
+import type { Screen } from '../Screen';
+export interface CommandAutocompleteState {
+    open: boolean;
+    index: number;
+    items: string[];
+}
+export declare function createCommandAutocompleteState(): CommandAutocompleteState;
+/** Set the picker to a fresh filter result (from filterCommands). */
+export declare function setCommandAutocomplete(state: CommandAutocompleteState, items: string[], index: number): CommandAutocompleteState;
+/** Close the picker and clear its items. */
+export declare function closeCommandAutocomplete(state: CommandAutocompleteState): CommandAutocompleteState;
+/** Minimal key shape App's KeyEvent satisfies. */
+export interface CommandAutocompleteKeyEvent {
+    key: string;
+}
+/** What App should do after a key press. */
+export type CommandAutocompleteAction = {
+    type: 'none';
+} | {
+    type: 'close';
+} | {
+    type: 'navigate';
+    delta: -1 | 1;
+} | {
+    type: 'select';
+    command: string;
+};
+/**
+ * Handle one key event while the `/command` picker is open. Returns the
+ * next state plus an action; `select` carries the chosen command name so
+ * App can rewrite the editor buffer (`/<command> `).
+ */
+export declare function handleCommandAutocompleteKey(state: CommandAutocompleteState, event: CommandAutocompleteKeyEvent): {
+    state: CommandAutocompleteState;
+    action: CommandAutocompleteAction;
+};
+/**
+ * Compute the editor buffer after selecting a command. Pure: returns the
+ * next value for App to set.
+ */
+export declare function commandToBuffer(command: string): string;
+/**
+ * Paint the `/command` picker below the status bar. `descriptions` maps
+ * command name → one-line description (App passes COMMAND_DESCRIPTIONS).
+ */
+export declare function renderCommandAutocomplete(screen: Screen, state: CommandAutocompleteState, startY: number, descriptions: Record<string, string>): void;

package/dist/renderer/components/CommandAutocomplete.js

@@ -0,0 +1,103 @@
+// components/CommandAutocomplete.ts
+// `/command` autocomplete picker.
+//
+// Extracted from App.ts (P2 refactor) following the component convention
+// (HunkPicker/PasteDialog/MentionPicker). Appears when the input starts
+// with `/` and offers matching slash commands; ↑/↓ navigate, Tab or Enter
+// select (App rewrites the editor buffer with `/<command> `), Esc closes.
+// Descriptions come from the command registry via COMMAND_DESCRIPTIONS —
+// passed into render so this module doesn't import the registry itself.
+import { fg, style } from '../ansi.js';
+import { PRIMARY_COLOR } from './uiConstants.js';
+export function createCommandAutocompleteState() {
+    return { open: false, index: 0, items: [] };
+}
+/** Set the picker to a fresh filter result (from filterCommands). */
+export function setCommandAutocomplete(state, items, index) {
+    return { open: items.length > 0, items, index };
+}
+/** Close the picker and clear its items. */
+export function closeCommandAutocomplete(state) {
+    return { ...state, open: false, items: [] };
+}
+/**
+ * Handle one key event while the `/command` picker is open. Returns the
+ * next state plus an action; `select` carries the chosen command name so
+ * App can rewrite the editor buffer (`/<command> `).
+ */
+export function handleCommandAutocompleteKey(state, event) {
+    switch (event.key) {
+        case 'up':
+            return {
+                state: { ...state, index: Math.max(0, state.index - 1) },
+                action: { type: 'navigate', delta: -1 },
+            };
+        case 'down':
+            return {
+                state: {
+                    ...state,
+                    index: Math.min(state.items.length - 1, state.index + 1),
+                },
+                action: { type: 'navigate', delta: 1 },
+            };
+        case 'tab':
+        case 'enter':
+            if (state.items.length > 0) {
+                const command = state.items[state.index];
+                return {
+                    state: closeCommandAutocomplete(state),
+                    action: { type: 'select', command },
+                };
+            }
+            return { state, action: { type: 'none' } };
+        default:
+            return { state, action: { type: 'none' } };
+    }
+}
+/**
+ * Compute the editor buffer after selecting a command. Pure: returns the
+ * next value for App to set.
+ */
+export function commandToBuffer(command) {
+    return '/' + command + ' ';
+}
+/**
+ * Paint the `/command` picker below the status bar. `descriptions` maps
+ * command name → one-line description (App passes COMMAND_DESCRIPTIONS).
+ */
+export function renderCommandAutocomplete(screen, state, startY, descriptions) {
+    const items = state.items;
+    const maxVisible = Math.min(items.length, 8);
+    let y = startY;
+    // Separator line
+    screen.horizontalLine(y++, '─', PRIMARY_COLOR);
+    // Title
+    screen.writeLine(y++, 'Commands', PRIMARY_COLOR + style.bold);
+    // Items with descriptions
+    const visibleStart = Math.max(0, state.index - maxVisible + 1);
+    const visibleItems = items.slice(visibleStart, visibleStart + maxVisible);
+    for (let i = 0; i < visibleItems.length; i++) {
+        const item = visibleItems[i];
+        const actualIndex = visibleStart + i;
+        const isSelected = actualIndex === state.index;
+        const desc = descriptions[item] || '';
+        const prefix = isSelected ? '► ' : '  ';
+        const cmdText = ('/' + item).padEnd(18);
+        if (isSelected) {
+            screen.write(0, y, prefix, PRIMARY_COLOR);
+            screen.write(prefix.length, y, cmdText, PRIMARY_COLOR + style.bold);
+            screen.write(prefix.length + cmdText.length, y, desc, fg.white);
+        }
+        else {
+            screen.write(0, y, prefix, '');
+            screen.write(prefix.length, y, cmdText, fg.green);
+            screen.write(prefix.length + cmdText.length, y, desc, fg.gray);
+        }
+        y++;
+    }
+    // Footer
+    const scrollInfo = items.length > maxVisible
+        ? ` (${visibleStart + 1}-${visibleStart + visibleItems.length}/${items.length})`
+        : '';
+    screen.writeLine(y, `↑↓ navigate • Tab/Enter select • Esc cancel${scrollInfo}`, fg.gray);
+}

package/dist/renderer/components/HunkPicker.d.ts

@@ -0,0 +1,48 @@
+import type { Screen } from '../Screen';
+/** One hunk in the interactive `/apply --interactive` picker. */
+export interface HunkPickerItem {
+    /** File path this hunk belongs to. */
+    path: string;
+    /** 0-based hunk index within the file diff. */
+    hunkIndex: number;
+    /** Human-readable hunk header, e.g. `@@ -12,3 +12,5 @@`. */
+    header: string;
+    /** Pre-formatted diff lines to display. */
+    lines: string[];
+}
+export interface HunkPickerOptions {
+    title: string;
+    items: HunkPickerItem[];
+    onComplete: (accepted: Array<{
+        path: string;
+        hunkIndex: number;
+    }>) => void;
+}
+export interface HunkPickerState {
+    open: boolean;
+    options: HunkPickerOptions | null;
+    index: number;
+    accepted: Array<{
+        path: string;
+        hunkIndex: number;
+    }>;
+}
+export declare function createHunkPickerState(): HunkPickerState;
+/** Minimal key shape App's KeyEvent satisfies. */
+export interface HunkPickerKeyEvent {
+    key: string;
+}
+/**
+ * Handle one key event for the picker. Returns the (possibly updated) state
+ * and whether the picker consumed the event (always true while open — the
+ * picker is modal). `onComplete` from the options fires exactly once, from
+ * `finish()`; after that the state is reset to closed.
+ */
+export declare function handleHunkPickerKey(state: HunkPickerState, event: HunkPickerKeyEvent): HunkPickerState;
+/** Panel height the layout needs to reserve for the picker. */
+export declare function hunkPickerPanelHeight(): number;
+/**
+ * Paint the picker into the screen. Mirrors the rendering previously inlined
+ * in App.renderInlineHunkPicker.
+ */
+export declare function renderHunkPicker(screen: Screen, state: HunkPickerState, startY: number, width: number): void;

package/dist/renderer/components/HunkPicker.js

@@ -0,0 +1,140 @@
+// components/HunkPicker.ts
+// Interactive hunk-by-hunk diff picker for `/apply --interactive`.
+//
+// Extracted from App.ts (P2 refactor) following the established component
+// convention (Settings/Export/Search): a pure-ish state object + key handler
+// + render function, so App.ts only owns a HunkPickerState field and the
+// wiring. The picker walks the user through items one at a time; for each
+// they accept (`y`/Enter/→) or skip (`n`/←). `a` accepts all remaining,
+// `q`/Esc quits. `onComplete` fires exactly once with the accepted set.
+import { fg, style } from '../ansi.js';
+import { PRIMARY_COLOR } from './uiConstants.js';
+export function createHunkPickerState() {
+    return { open: false, options: null, index: 0, accepted: [] };
+}
+/**
+ * Handle one key event for the picker. Returns the (possibly updated) state
+ * and whether the picker consumed the event (always true while open — the
+ * picker is modal). `onComplete` from the options fires exactly once, from
+ * `finish()`; after that the state is reset to closed.
+ */
+export function handleHunkPickerKey(state, event) {
+    const opts = state.options;
+    if (!opts || !state.open) {
+        return { ...state, open: false };
+    }
+    const finish = () => {
+        const accepted = state.accepted;
+        const cb = opts.onComplete;
+        // Reset first so a re-entrant show() from the callback can't race the
+        // stale state; then fire the callback once.
+        const next = createHunkPickerState();
+        cb(accepted);
+        return next;
+    };
+    const advance = () => {
+        if (state.index >= opts.items.length - 1) {
+            return finish();
+        }
+        return { ...state, index: state.index + 1 };
+    };
+    const acceptCurrent = () => {
+        const item = opts.items[state.index];
+        if (item) {
+            return advanceWith(state, { path: item.path, hunkIndex: item.hunkIndex });
+        }
+        return advance();
+    };
+    const advanceWith = (s, entry) => {
+        const next = { ...s, accepted: [...s.accepted, entry] };
+        if (next.index >= opts.items.length - 1) {
+            return finishFrom(next);
+        }
+        return { ...next, index: next.index + 1 };
+    };
+    const finishFrom = (s) => {
+        const cb = opts.onComplete;
+        const next = createHunkPickerState();
+        cb(s.accepted);
+        return next;
+    };
+    switch (event.key) {
+        case 'y':
+        case 'enter':
+        case 'right':
+            return acceptCurrent();
+        case 'n':
+        case 'left':
+            return advance();
+        case 'a': {
+            // Accept current + all remaining.
+            const accepted = [...state.accepted];
+            for (let i = state.index; i < opts.items.length; i++) {
+                const item = opts.items[i];
+                accepted.push({ path: item.path, hunkIndex: item.hunkIndex });
+            }
+            return finishFrom({ ...state, accepted });
+        }
+        case 'q':
+        case 'escape':
+            return finish();
+        case 'up':
+            return state.index > 0 ? { ...state, index: state.index - 1 } : state;
+        case 'down':
+            return state.index < opts.items.length - 1
+                ? { ...state, index: state.index + 1 }
+                : state;
+        default:
+            return state;
+    }
+}
+/** Panel height the layout needs to reserve for the picker. */
+export function hunkPickerPanelHeight() {
+    // Title + progress + path + header + up to 12 diff lines + more marker + legend.
+    return 18;
+}
+/**
+ * Paint the picker into the screen. Mirrors the rendering previously inlined
+ * in App.renderInlineHunkPicker.
+ */
+export function renderHunkPicker(screen, state, startY, width) {
+    const opts = state.options;
+    if (!opts)
+        return;
+    const item = opts.items[state.index];
+    let y = startY;
+    screen.horizontalLine(y++, '─', PRIMARY_COLOR);
+    // Title + progress
+    const progress = opts.items.length > 0 ? ` (${state.index + 1}/${opts.items.length})` : '';
+    screen.writeLine(y++, `${opts.title}${progress}`, PRIMARY_COLOR + style.bold);
+    if (!item) {
+        screen.writeLine(y++, 'No hunks to review.', fg.gray);
+        screen.writeLine(y, 'Press any key to close.', fg.gray);
+        return;
+    }
+    // File path + hunk header
+    screen.writeLine(y++, `File: ${item.path}`, fg.cyan);
+    screen.writeLine(y++, `Hunk: ${item.header}`, fg.gray);
+    // Diff lines (capped to available vertical space; show up to 12)
+    const maxDiffLines = 12;
+    const lines = item.lines.slice(0, maxDiffLines);
+    for (const line of lines) {
+        const prefix = line.charAt(0);
+        let color = fg.white;
+        if (prefix === '+')
+            color = fg.green;
+        else if (prefix === '-')
+            color = fg.red;
+        else if (prefix === '@')
+            color = fg.cyan;
+        // Truncate long lines to terminal width.
+        const truncated = line.length > width - 2 ? line.slice(0, width - 5) + '...' : line;
+        screen.writeLine(y++, `  ${truncated}`, color);
+    }
+    if (item.lines.length > maxDiffLines) {
+        screen.writeLine(y++, `  … (${item.lines.length - maxDiffLines} more lines)`, fg.gray);
+    }
+    y++;
+    // Key legend
+    screen.writeLine(y, 'y/Enter accept • n skip • a accept all • q/Esc quit • ↑/↓ navigate', fg.gray);
+}

package/dist/renderer/components/MentionPicker.d.ts

@@ -0,0 +1,60 @@
+import type { Screen } from '../Screen';
+import type { MentionSuggestion } from '../../utils/mentions';
+export interface MentionPickerState {
+    open: boolean;
+    index: number;
+    items: MentionSuggestion[];
+    /** Index of the `@` in the editor value at the time the query started. */
+    atStart: number;
+    /** Project root used to resolve suggestions (cached per update). */
+    root: string;
+}
+export declare function createMentionPickerState(): MentionPickerState;
+/** Set the picker to a fresh query result. */
+export declare function openMentionPicker(state: MentionPickerState, items: MentionSuggestion[], atStart: number, root: string): MentionPickerState;
+/** Close the picker and clear its items. */
+export declare function closeMentionPicker(state: MentionPickerState): MentionPickerState;
+/** Minimal key shape App's KeyEvent satisfies. */
+export interface MentionPickerKeyEvent {
+    key: string;
+}
+/** What App should do after a key press. */
+export type MentionPickerAction = {
+    type: 'none';
+} | {
+    type: 'close';
+} | {
+    type: 'navigate';
+    delta: -1 | 1;
+} | {
+    type: 'select';
+    suggestion: MentionSuggestion;
+    atStart: number;
+};
+/**
+ * Handle one key event while the mention picker is open. Returns the next
+ * state plus an action; `select` carries the chosen suggestion and the
+ * `@` index so App can rewrite the editor buffer.
+ */
+export declare function handleMentionPickerKey(state: MentionPickerState, event: MentionPickerKeyEvent): {
+    state: MentionPickerState;
+    action: MentionPickerAction;
+};
+/**
+ * Compute the editor buffer after applying a mention selection. Pure:
+ * returns the next value + cursor position for App to set.
+ *
+ * `atStart` is the index OF the `@`, so the `before` slice EXCLUDES it —
+ * the sigil is re-added or the completed path is no longer a mention and
+ * the file never gets attached.
+ */
+export declare function applyMentionToBuffer(value: string, cursor: number, atStart: number, suggestion: MentionSuggestion): {
+    value: string;
+    cursor: number;
+};
+/**
+ * Paint the mention picker below the status bar. Mirrors the layout of the
+ * `/` Autocomplete (separator → title → items → footer) but shows file
+ * paths with their parent directory as the description, and an `@` prefix.
+ */
+export declare function renderMentionPicker(screen: Screen, state: MentionPickerState, startY: number): void;