minovative-mind-cli 2.13.5 → 2.14.1

package/dist/services/proxyClient.js

@@ -2,19 +2,29 @@ import { debugLog, isDebugOn } from '../utils/logger.js';
 import { GEMINI_MODELS } from '../utils/config.js';
 import { getMetricCollector } from './metrics.js';
 /**
- * ============================================================================
- *                               PROXY CLIENT SERVICE
- * ============================================================================
- * Facilitates stream-based communication with the secure, Firebase-authenticated
- * serverless Gemini content generation proxy.
- *
- * Core Capabilities:
- * - Server-Sent Events (SSE) parsing for thoughts, text, and function calls.
- * - Secure Authentication handling (Firebase ID Tokens).
- * - Real-time stream-callback piping for instant responses.
- * - Accurate token usage, credit consumption, and grounding metadata parsing.
- * ============================================================================
+ * Normalizes generation configuration across Proxy and BYOK endpoints.
+ * Strips 'MINIMAL' thinking level since Gemini 3.x models use default thinking
+ * behavior when no explicit thinking level is provided, preventing 400 Bad Request
+ * rejections from Google's Generative Language API.
  */
+export function normalizeGenerationConfig(config) {
+    if (!config)
+        return undefined;
+    const normalized = { ...config };
+    if (normalized.thinkingConfig) {
+        const thinkingConfig = { ...normalized.thinkingConfig };
+        if (thinkingConfig.thinkingLevel === 'MINIMAL') {
+            delete thinkingConfig.thinkingLevel;
+        }
+        if (Object.keys(thinkingConfig).length === 0) {
+            delete normalized.thinkingConfig;
+        }
+        else {
+            normalized.thinkingConfig = thinkingConfig;
+        }
+    }
+    return normalized;
+}
 /**
  * Helper to pause execution for a specified duration, respecting abort signals.
  */
@@ -106,23 +116,28 @@ export class ProxyClient {
                 err.name = 'AbortError';
                 throw err;
             }
+            const normalizedGenConfig = normalizeGenerationConfig(generationConfig);
+            const requestBody = {
+                model: activeModel,
+                contents,
+                tools,
+                toolConfig,
+                systemInstruction,
+            };
+            if (normalizedGenConfig && Object.keys(normalizedGenConfig).length > 0) {
+                requestBody.generationConfig = normalizedGenConfig;
+            }
             const response = await fetch(this.PROXY_URL, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
                     'X-Firebase-Auth': `Bearer ${idToken}`,
                 },
-                body: JSON.stringify({
-                    model: activeModel,
-                    contents,
-                    tools,
-                    toolConfig,
-                    systemInstruction,
-                    generationConfig,
-                }),
+                body: JSON.stringify(requestBody),
                 signal: abortSignal,
             });
-            debugLog(`Proxy Request to ${activeModel} complete. Status: ${response.status} ${response.statusText}`);
+            const thinkingLevel = generationConfig?.thinkingConfig?.thinkingLevel || 'DEFAULT';
+            debugLog(`Proxy Request to ${activeModel} (thinking: ${thinkingLevel}) complete. Status: ${response.status} ${response.statusText}`);
             if (response.status === 429 || response.status === 503 || response.status === 502 || response.status === 500 || response.status === 504) {
                 if (attempt < MAX_RETRIES) {
                     if (abortSignal?.aborted) {
@@ -342,6 +357,7 @@ export class ProxyClient {
     async generateViaBYOK(apiKey, modelName, contents, tools, toolConfig, systemInstruction, generationConfig, streamCallbacks, abortSignal) {
         const isStreaming = Boolean(streamCallbacks?.onChunk);
         const formattedSystemInstruction = typeof systemInstruction === 'string' ? { parts: [{ text: systemInstruction }] } : systemInstruction;
+        const normalizedGenConfig = normalizeGenerationConfig(generationConfig);
         const payload = { contents };
         if (tools && tools.length > 0)
             payload.tools = tools;
@@ -349,8 +365,9 @@ export class ProxyClient {
             payload.toolConfig = toolConfig;
         if (formattedSystemInstruction)
             payload.systemInstruction = formattedSystemInstruction;
-        if (generationConfig)
-            payload.generationConfig = generationConfig;
+        if (normalizedGenConfig && Object.keys(normalizedGenConfig).length > 0) {
+            payload.generationConfig = normalizedGenConfig;
+        }
         const MAX_RETRIES = 5;
         const BASE_DELAY_MS = 2000;
         const MAX_DELAY_MS = 30000;
@@ -370,7 +387,8 @@ export class ProxyClient {
                 body: JSON.stringify(payload),
                 signal: abortSignal,
             });
-            debugLog(`BYOK Request to ${activeModel} complete. Status: ${response.status} ${response.statusText}`);
+            const thinkingLevel = generationConfig?.thinkingConfig?.thinkingLevel || 'DEFAULT';
+            debugLog(`BYOK Request to ${activeModel} (thinking: ${thinkingLevel}) complete. Status: ${response.status} ${response.statusText}`);
             if (response.status === 429 ||
                 response.status === 503 ||
                 response.status === 502 ||

package/dist/utils/config.d.ts

@@ -23,6 +23,21 @@ export declare const GEMINI_MODELS: {
     readonly FLASH_LITE: "gemini-3.5-flash-lite";
     readonly AUTO: "auto";
 };
+/**
+ * Supported native thinking reasoning levels for Gemini 3.x series models.
+ */
+export type ThinkingLevel = 'MINIMAL' | 'LOW' | 'MEDIUM' | 'HIGH';
+/**
+ * Thinking configuration structure for Gemini API generation requests.
+ */
+export interface ThinkingConfig {
+    thinkingLevel?: ThinkingLevel;
+    includeThoughts?: boolean;
+}
+/**
+ * Default thinking level mappings per model for reasoning budget allocation.
+ */
+export declare const DEFAULT_MODEL_THINKING_LEVELS: Record<string, ThinkingLevel>;
 /** Default Gemini model for the coding agent. */
 export declare const DEFAULT_MODEL: "auto";
 /** Maximum tokens the model can output per response. */
@@ -49,7 +64,67 @@ export declare const TPM_COOLING_DELAYS: {
     readonly ORCHESTRATION_RECONCILE_MS: 2000;
     /** Pause before sending automated verification self-correction prompts */
     readonly CORRECTION_TURN_MS: 2000;
+    /** Stagger delay when spawning concurrent sub-agents to avoid rate burst */
+    readonly SUB_AGENT_SPAWN_MS: 1500;
+    /** Subtle inter-tool execution delay for burst protection during high-frequency loops */
+    readonly TOOL_CALL_PACING_MS: 1000;
+    /** Deliberate settling recovery window after massive token generations */
+    readonly BURST_RECOVERY_MS: 4000;
+    /** Token threshold above which heavy-prompt adaptive cooling delays are applied */
+    readonly HEAVY_PROMPT_THRESHOLD_TOKENS: 100000;
+    /** Minimum adaptive cooling delay bound in milliseconds */
+    readonly ADAPTIVE_PACING_MIN_MS: 1000;
+    /** Maximum adaptive cooling delay bound in milliseconds */
+    readonly ADAPTIVE_PACING_MAX_MS: 8000;
 };
+/**
+ * Standardized rate limiting and exponential backoff configuration.
+ */
+export declare const RATE_LIMIT_CONFIG: {
+    /** Maximum retry attempts for transient 429 / 503 / 500 server errors */
+    readonly MAX_RETRIES: 5;
+    /** Base backoff delay in milliseconds */
+    readonly BASE_DELAY_MS: 2000;
+    /** Maximum backoff delay cap in milliseconds */
+    readonly MAX_DELAY_MS: 30000;
+    /** Multiplicative exponential backoff factor */
+    readonly BACKOFF_FACTOR: 2.5;
+    /** Random jitter factor applied to backoff delays to prevent thundering herd */
+    readonly JITTER_FACTOR: 0.5;
+    /** Default target tokens-per-minute threshold across rolling 60-second window */
+    readonly DEFAULT_TPM_LIMIT: 4000000;
+    /** Safety buffer threshold before triggering adaptive TPM pacing (85% capacity) */
+    readonly TARGET_TOKEN_PACING_BUFFER: 0.85;
+    /** Maximum concurrent sub-agents allowed to prevent rate limit exhaustion */
+    readonly MAX_PARALLEL_SUBAGENTS: 3;
+    /** Estimated tokens per character heuristic (approx. 4 characters per token) */
+    readonly ESTIMATED_TOKENS_PER_CHAR: 0.25;
+};
+/**
+ * Estimates token count from character length using standard tokenization heuristics.
+ *
+ * @param charCount Number of characters in the string.
+ * @returns Estimated number of tokens.
+ */
+export declare function estimateTokensFromCharLength(charCount: number): number;
+/**
+ * Calculates dynamic adaptive pacing delay (in milliseconds) based on prompt token volume
+ * and provider tier (BYOK vs Proxy).
+ *
+ * @param estimatedInputTokens Estimated prompt tokens for the upcoming call.
+ * @param isByok Whether the user is using Bring-Your-Own-Key.
+ * @returns Delay duration in milliseconds.
+ */
+export declare function calculateAdaptivePacingDelay(estimatedInputTokens?: number, isByok?: boolean): number;
+/**
+ * Returns the recommended cooling-off delay for a specific operational phase,
+ * optionally factoring in token volume.
+ *
+ * @param phase Operational phase key.
+ * @param tokenCount Optional estimated token count for dynamic scaling.
+ * @returns Delay in milliseconds.
+ */
+export declare function getSmartPacingDelay(phase: keyof typeof TPM_COOLING_DELAYS | string, tokenCount?: number): number;
 /**
  * Checks if BYOK is currently enabled for the user.
  */

package/dist/utils/config.js

@@ -23,6 +23,16 @@ export const GEMINI_MODELS = {
     FLASH_LITE: 'gemini-3.5-flash-lite',
     AUTO: 'auto',
 };
+/**
+ * Default thinking level mappings per model for reasoning budget allocation.
+ */
+export const DEFAULT_MODEL_THINKING_LEVELS = {
+    [GEMINI_MODELS.FLASH_3_7]: 'MEDIUM',
+    [GEMINI_MODELS.FLASH_3_6]: 'MEDIUM',
+    [GEMINI_MODELS.PRO]: 'HIGH',
+    [GEMINI_MODELS.FLASH_LITE]: 'LOW',
+    [GEMINI_MODELS.AUTO]: 'MEDIUM',
+};
 /** Default Gemini model for the coding agent. */
 export const DEFAULT_MODEL = GEMINI_MODELS.AUTO;
 /** Maximum tokens the model can output per response. */
@@ -49,7 +59,90 @@ export const TPM_COOLING_DELAYS = {
     ORCHESTRATION_RECONCILE_MS: 2000,
     /** Pause before sending automated verification self-correction prompts */
     CORRECTION_TURN_MS: 2000,
+    /** Stagger delay when spawning concurrent sub-agents to avoid rate burst */
+    SUB_AGENT_SPAWN_MS: 1500,
+    /** Subtle inter-tool execution delay for burst protection during high-frequency loops */
+    TOOL_CALL_PACING_MS: 1000,
+    /** Deliberate settling recovery window after massive token generations */
+    BURST_RECOVERY_MS: 4000,
+    /** Token threshold above which heavy-prompt adaptive cooling delays are applied */
+    HEAVY_PROMPT_THRESHOLD_TOKENS: 100_000,
+    /** Minimum adaptive cooling delay bound in milliseconds */
+    ADAPTIVE_PACING_MIN_MS: 1000,
+    /** Maximum adaptive cooling delay bound in milliseconds */
+    ADAPTIVE_PACING_MAX_MS: 8000,
+};
+/**
+ * Standardized rate limiting and exponential backoff configuration.
+ */
+export const RATE_LIMIT_CONFIG = {
+    /** Maximum retry attempts for transient 429 / 503 / 500 server errors */
+    MAX_RETRIES: 5,
+    /** Base backoff delay in milliseconds */
+    BASE_DELAY_MS: 2000,
+    /** Maximum backoff delay cap in milliseconds */
+    MAX_DELAY_MS: 30_000,
+    /** Multiplicative exponential backoff factor */
+    BACKOFF_FACTOR: 2.5,
+    /** Random jitter factor applied to backoff delays to prevent thundering herd */
+    JITTER_FACTOR: 0.5,
+    /** Default target tokens-per-minute threshold across rolling 60-second window */
+    DEFAULT_TPM_LIMIT: 4_000_000,
+    /** Safety buffer threshold before triggering adaptive TPM pacing (85% capacity) */
+    TARGET_TOKEN_PACING_BUFFER: 0.85,
+    /** Maximum concurrent sub-agents allowed to prevent rate limit exhaustion */
+    MAX_PARALLEL_SUBAGENTS: 3,
+    /** Estimated tokens per character heuristic (approx. 4 characters per token) */
+    ESTIMATED_TOKENS_PER_CHAR: 0.25,
 };
+/**
+ * Estimates token count from character length using standard tokenization heuristics.
+ *
+ * @param charCount Number of characters in the string.
+ * @returns Estimated number of tokens.
+ */
+export function estimateTokensFromCharLength(charCount) {
+    return Math.ceil(charCount * RATE_LIMIT_CONFIG.ESTIMATED_TOKENS_PER_CHAR);
+}
+/**
+ * Calculates dynamic adaptive pacing delay (in milliseconds) based on prompt token volume
+ * and provider tier (BYOK vs Proxy).
+ *
+ * @param estimatedInputTokens Estimated prompt tokens for the upcoming call.
+ * @param isByok Whether the user is using Bring-Your-Own-Key.
+ * @returns Delay duration in milliseconds.
+ */
+export function calculateAdaptivePacingDelay(estimatedInputTokens = 0, isByok = false) {
+    if (estimatedInputTokens <= 0) {
+        return isByok ? TPM_COOLING_DELAYS.ADAPTIVE_PACING_MIN_MS / 2 : TPM_COOLING_DELAYS.ADAPTIVE_PACING_MIN_MS;
+    }
+    const threshold = TPM_COOLING_DELAYS.HEAVY_PROMPT_THRESHOLD_TOKENS;
+    if (estimatedInputTokens < threshold) {
+        return TPM_COOLING_DELAYS.ADAPTIVE_PACING_MIN_MS;
+    }
+    // Scale linearly between MIN and MAX based on token weight exceeding threshold
+    const ratio = Math.min(1.0, (estimatedInputTokens - threshold) / threshold);
+    const dynamicDelay = TPM_COOLING_DELAYS.ADAPTIVE_PACING_MIN_MS +
+        ratio * (TPM_COOLING_DELAYS.ADAPTIVE_PACING_MAX_MS - TPM_COOLING_DELAYS.ADAPTIVE_PACING_MIN_MS);
+    // BYOK users may have higher or lower custom tier limits, apply modest discount
+    return Math.round(isByok ? dynamicDelay * 0.8 : dynamicDelay);
+}
+/**
+ * Returns the recommended cooling-off delay for a specific operational phase,
+ * optionally factoring in token volume.
+ *
+ * @param phase Operational phase key.
+ * @param tokenCount Optional estimated token count for dynamic scaling.
+ * @returns Delay in milliseconds.
+ */
+export function getSmartPacingDelay(phase, tokenCount) {
+    const baseDelay = TPM_COOLING_DELAYS[phase] ?? TPM_COOLING_DELAYS.INTER_TURN_MS;
+    if (typeof tokenCount === 'number' && tokenCount > TPM_COOLING_DELAYS.HEAVY_PROMPT_THRESHOLD_TOKENS) {
+        const adaptive = calculateAdaptivePacingDelay(tokenCount);
+        return Math.max(baseDelay, adaptive);
+    }
+    return baseDelay;
+}
 /**
  * Checks if BYOK is currently enabled for the user.
  */

package/dist/utils/contextPrompts.d.ts

@@ -1,9 +1,22 @@
+import { ContextAgentResult } from '../services/contextAgent.js';
 /**
- * @file Utility functions for preparing and sanitizing context-related
- * injection strings to be sent to the AI model. Includes handling of CDATA block
- * formatting, character/token budgeting, and lightweight AST-scoped context extraction.
+ * Standard character and token budgeting constants for context injections.
  */
-import { ContextAgentResult } from '../services/contextAgent.js';
+export declare const CONTEXT_BUDGET_CONFIG: {
+    /** Default maximum character budget for full context injections (~60,000 tokens) */
+    readonly DEFAULT_CONTEXT_MAX_CHARS: 240000;
+    /** Default maximum character budget for scoped context injections (~30,000 tokens) */
+    readonly DEFAULT_SCOPED_MAX_CHARS: 120000;
+    /** Estimated characters per token heuristic */
+    readonly ESTIMATED_CHARS_PER_TOKEN: 4;
+};
+/**
+ * Estimates token count from a given text string.
+ *
+ * @param text The input text to measure.
+ * @returns Estimated number of tokens.
+ */
+export declare function estimateTokens(text: string): number;
 /**
  * Sanitizes file content string to prevent nesting or breakout issues when wrapped in CDATA.
  * Replaces occurrences of "]]\u200B>" with an escaped equivalent containing a zero-width space.
@@ -37,3 +50,14 @@ export declare function buildContextInjection(context: ContextAgentResult, maxCh
  * @returns A formatted string containing project profile, structure, investigation summaries, and AST-scoped file outlines.
  */
 export declare function buildScopedContextInjection(context: ContextAgentResult, maxChars?: number): string;
+/**
+ * Formats an array of resolved context mention blocks into a single structured
+ * XML `<context_mentions>` block adhering to character/token budget constraints.
+ *
+ * @param resolvedBlocks Array of objects with content string.
+ * @param maxChars Optional maximum character budget.
+ * @returns Unified XML context block.
+ */
+export declare function formatContextMentions(resolvedBlocks: Array<{
+    content: string;
+}>, maxChars?: number): string;

package/dist/utils/contextPrompts.js

@@ -5,6 +5,28 @@
  */
 import { changeLogger } from '../services/changeLogger.js';
 import { extractDeclarationsOutline } from './symbolExtractor.js';
+/**
+ * Standard character and token budgeting constants for context injections.
+ */
+export const CONTEXT_BUDGET_CONFIG = {
+    /** Default maximum character budget for full context injections (~60,000 tokens) */
+    DEFAULT_CONTEXT_MAX_CHARS: 240_000,
+    /** Default maximum character budget for scoped context injections (~30,000 tokens) */
+    DEFAULT_SCOPED_MAX_CHARS: 120_000,
+    /** Estimated characters per token heuristic */
+    ESTIMATED_CHARS_PER_TOKEN: 4,
+};
+/**
+ * Estimates token count from a given text string.
+ *
+ * @param text The input text to measure.
+ * @returns Estimated number of tokens.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / CONTEXT_BUDGET_CONFIG.ESTIMATED_CHARS_PER_TOKEN);
+}
 /**
  * Sanitizes file content string to prevent nesting or breakout issues when wrapped in CDATA.
  * Replaces occurrences of "]]\u200B>" with an escaped equivalent containing a zero-width space.
@@ -13,7 +35,7 @@ import { extractDeclarationsOutline } from './symbolExtractor.js';
  * @returns The sanitized string safe to place inside a CDATA section.
  */
 export function sanitizeForCDATA(content) {
-    // Prevent CDATA breakout by escaping ]]>
+    // Prevent CDATA breakout by escaping ]]\\u200B>
     return content.replace(new RegExp('\\]\\]>', 'g'), ']]\\\\u200B>');
 }
 /**
@@ -136,6 +158,17 @@ function assembleContextWithFiles(baseContext, relevantFiles, maxChars, useScope
             injection += fullBlock;
             continue;
         }
+        // Token-efficiency optimization: If full file does not fit and wasn't scoped, attempt AST outline first
+        if (!useScopedOutline) {
+            const outlinedText = extractDeclarationsOutline(contentText, filePath);
+            if (outlinedText) {
+                const outlinedBlock = formatWorkspaceFileBlock(filePath, outlinedText, true);
+                if (outlinedBlock.length <= remainingBudgetForThisFile) {
+                    injection += outlinedBlock;
+                    continue;
+                }
+            }
+        }
         // Try partial/truncated block
         const emptyBlock = formatWorkspaceFileBlock(filePath, '', useScopedOutline);
         const wrapperOverhead = emptyBlock.length;
@@ -194,3 +227,39 @@ export function buildScopedContextInjection(context, maxChars) {
     const baseContext = buildBaseContext(context);
     return assembleContextWithFiles(baseContext, context.relevantFiles, maxChars, true);
 }
+/**
+ * Formats an array of resolved context mention blocks into a single structured
+ * XML `<context_mentions>` block adhering to character/token budget constraints.
+ *
+ * @param resolvedBlocks Array of objects with content string.
+ * @param maxChars Optional maximum character budget.
+ * @returns Unified XML context block.
+ */
+export function formatContextMentions(resolvedBlocks, maxChars = CONTEXT_BUDGET_CONFIG.DEFAULT_CONTEXT_MAX_CHARS) {
+    if (!resolvedBlocks || resolvedBlocks.length === 0)
+        return '';
+    const validBlocks = resolvedBlocks.filter((b) => b.content && b.content.trim());
+    if (validBlocks.length === 0)
+        return '';
+    let combined = '<context_mentions>\n';
+    const closingTag = '\n</context_mentions>';
+    for (let i = 0; i < validBlocks.length; i++) {
+        const block = validBlocks[i];
+        const nextContent = `${block.content}\n`;
+        if (maxChars && combined.length + nextContent.length + closingTag.length > maxChars) {
+            const remaining = validBlocks.length - i;
+            const omissionNotice = `<!-- ${remaining} mention context block(s) omitted to stay within token budget -->\n`;
+            if (combined.length + omissionNotice.length + closingTag.length <= maxChars) {
+                combined += omissionNotice;
+            }
+            break;
+        }
+        combined += nextContent;
+    }
+    combined += '</context_mentions>';
+    if (maxChars && combined.length > maxChars) {
+        const keepChars = Math.max(0, maxChars - closingTag.length);
+        combined = `${combined.slice(0, keepChars).trimEnd()}${closingTag}`;
+    }
+    return combined;
+}

package/dist/utils/historyPrompt.d.ts

@@ -1,3 +1,48 @@
+/**
+ * Represents an individual autocomplete suggestion item for @ context mentions.
+ */
+export interface AutocompleteItem {
+    /** Optional unique identifier for the suggestion */
+    id?: string;
+    /** The value or token to insert into the input buffer (e.g. "@src/utils/historyPrompt.ts" or "@git:diff") */
+    value: string;
+    /** Display label shown in the dropdown list */
+    label: string;
+    /** Category badge type (e.g. 'file', 'lines', 'symbol', 'sym', 'git', 'workspace', 'ws', 'diagnostics', 'diag', 'problem', 'prob', 'terminal', 'term', 'doc') */
+    category?: 'file' | 'lines' | 'line' | 'symbol' | 'sym' | 'git' | 'workspace' | 'ws' | 'diagnostics' | 'diag' | 'problem' | 'prob' | 'terminal' | 'term' | 'doc' | string;
+    /** Short secondary description or path info */
+    description?: string;
+    /** Additional metadata for advanced resolvers */
+    metadata?: Record<string, any>;
+}
+/**
+ * Configuration options governing real-time @ autocomplete behavior.
+ */
+export interface AutocompleteOptions {
+    /** Whether autocomplete is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Maximum number of suggestions displayed in the popup list at once. Defaults to 10. */
+    maxVisibleItems?: number;
+    /** Custom suggestion provider returning static or dynamic suggestions. */
+    getSuggestions?: (query: string, context: {
+        fullText: string;
+        cursor: number;
+    }) => AutocompleteItem[] | Promise<AutocompleteItem[]>;
+    /** Custom filter/ranking function for suggestions */
+    filter?: (items: AutocompleteItem[], query: string) => AutocompleteItem[];
+    /** Alias for filter */
+    filterSuggestions?: (items: AutocompleteItem[], query: string) => AutocompleteItem[];
+    /** Trigger character(s) that activate autocomplete. Defaults to ['@']. */
+    triggers?: string[];
+    /** Root directory for workspace file scanning. Defaults to process.cwd(). */
+    workspaceRoot?: string;
+    /** Whether pressing Tab completes the selected suggestion. Defaults to true. */
+    tabCompletion?: boolean;
+    /** Whether pressing Enter when autocomplete is open completes the suggestion (false submits prompt). Defaults to false. */
+    enterCompletion?: boolean;
+    /** Cache timeout in ms for file and workspace scanning. Defaults to 5000ms. */
+    cacheTtlMs?: number;
+}
 /**
  * Configuration options for the history-enabled text prompt.
  */
@@ -16,6 +61,17 @@ export interface HistoryTextOptions {
     maxHistoryLength?: number;
     /** Callback to validate the user input. */
     validate?: (value: string) => string | Error | undefined;
+    /** Autocomplete configuration options for @ context mentions and symbols. */
+    autocomplete?: boolean | AutocompleteOptions;
+    /** Optional custom suggestion provider shortcut */
+    getSuggestions?: (query: string, context: {
+        fullText: string;
+        cursor: number;
+    }) => AutocompleteItem[] | Promise<AutocompleteItem[]>;
+    /** Optional custom readable input stream (e.g. for testing) */
+    input?: NodeJS.ReadableStream;
+    /** Optional custom writable output stream (e.g. for testing) */
+    output?: NodeJS.WritableStream;
 }
 /**
  * Configuration options for dynamic token budget calculation.
@@ -67,13 +123,15 @@ export declare function calculateDynamicTokenBudget(config: TokenBudgetConfig):
  * @param text The text to prune.
  * @param maxTokens Maximum allowable tokens for this text.
  * @param options Pruning options.
+ * @param options.truncationMarker Marker to append/prepend indicating truncation.
+ * @param options.fromStart If true, prunes from the start.
  * @returns Pruned string, with an optional truncation marker.
  */
 export declare function pruneTextToTokenBudget(text: string, maxTokens: number, options?: {
-    /** Marker to append/prepend indicating truncation. */
-    truncationMarker?: string;
     /** If true, prunes from the start (keeping the end). If false, prunes from the end (keeping the start). */
     fromStart?: boolean;
+    /** Marker to append/prepend indicating truncation. */
+    truncationMarker?: string;
 }): string;
 /**
  * Optimizes an array of history strings by trimming whitespace, deduplicating consecutive items,
@@ -89,25 +147,126 @@ export declare function optimizeHistoryForContext(history: string[] | undefined,
  * pruning older turns if the total estimated tokens exceed the allocated budget.
  *
  * @param history Array of conversation turns with role and text content.
- * @param maxTokens Maximum allowable tokens for the formatted history.
+ * @param maxTokens Maximum allowable tokens for the formatted history. Defaults to 16_384.
  * @param options Formatting options.
+ * @param options.keepRecentTurns Minimum number of recent turns to always keep regardless of budget if possible. Defaults to 2.
+ * @param options.userLabel Custom label prefix for user turns. Defaults to "User".
+ * @param options.modelLabel Custom label prefix for assistant/model turns. Defaults to "Assistant".
  * @returns Formatted and budget-constrained conversation history string.
  */
 export declare function formatHistoryWithTokenBudget(history: Array<{
+    parts?: any[];
     role: string;
     text?: string;
-    parts?: any[];
 }>, maxTokens?: number, options?: {
     /** Minimum number of recent turns to always keep regardless of budget if possible. Defaults to 2. */
     keepRecentTurns?: number;
-    /** Custom label prefix for user turns. Defaults to "User". */
-    userLabel?: string;
     /** Custom label prefix for assistant/model turns. Defaults to "Assistant". */
     modelLabel?: string;
+    /** Custom label prefix for user turns. Defaults to "User". */
+    userLabel?: string;
 }): string;
+/**
+ * Extracts an active mention trigger token (such as `@query`) directly preceding the cursor.
+ *
+ * @param line - The full input line buffer.
+ * @param cursor - The current cursor index within the line buffer.
+ * @param triggers - Allowed trigger prefix characters (defaults to `['@']`).
+ * @returns An object containing query string and starting trigger index, or `null` if not active.
+ */
+export declare function extractMentionQuery(line: string, cursor: number, triggers?: string[]): {
+    query: string;
+    triggerIndex: number;
+    trigger: string;
+} | null;
+/**
+ * Scores an autocomplete item against a search query for fuzzy and prefix ranking.
+ *
+ * @param item - The autocomplete candidate.
+ * @param query - The user search query without trigger prefix.
+ * @returns Numerical score (higher score = better match, 0 = no match).
+ */
+export declare function scoreAutocompleteItem(item: AutocompleteItem, query: string): number;
+/**
+ * Filters and ranks suggestions according to match quality.
+ *
+ * @param items - Candidate autocomplete suggestions.
+ * @param query - The search query string.
+ * @param maxItems - Maximum number of top items to return.
+ * @returns Ranked subset of suggestions.
+ */
+export declare function filterAndRankSuggestions(items: AutocompleteItem[], query: string, maxItems?: number): AutocompleteItem[];
+/**
+ * Formats a terminal-styled category badge with picocolors.
+ *
+ * @param category - Category name (e.g. 'lines', 'sym', 'git', 'diag', 'term', 'ws', 'file').
+ * @returns Formatted ANSI badge string.
+ */
+export declare function formatCategoryBadge(category?: string): string;
+/**
+ * Renders an aesthetically styled autocomplete popup dropdown box for terminal display.
+ *
+ * @param suggestions - Current list of visible suggestions.
+ * @param selectedIndex - Currently selected item index.
+ * @param maxVisible - Maximum number of items visible simultaneously.
+ * @returns Multi-line ANSI string representing the autocomplete popup.
+ */
+export declare function renderAutocompletePopup(suggestions: AutocompleteItem[], selectedIndex: number, maxVisible?: number): string;
+/**
+ * Resolver for dynamic workspace files, git actions, and registered external workspaces.
+ */
+export declare class ContextMentionResolver {
+    private cachedFiles;
+    private externalWorkspaceCache;
+    private symbolCache;
+    private cacheTimestamp;
+    private cacheTtlMs;
+    private workspaceRoot;
+    constructor(workspaceRoot?: string, cacheTtlMs?: number);
+    /**
+     * Clears in-memory file scanning caches.
+     */
+    clearCache(): void;
+    /**
+     * Returns standard built-in git, diagnostic, terminal, and symbol context mention options.
+     */
+    getBuiltInMentions(): AutocompleteItem[];
+    /**
+     * Scans and caches workspace relative file paths up to depth limit.
+     *
+     * @param targetRoot - Directory root to scan. Defaults to this.workspaceRoot.
+     * @returns Array of relative file paths within the target root.
+     */
+    getWorkspaceFiles(targetRoot?: string): string[];
+    /**
+     * Returns registered external workspaces as autocomplete items.
+     */
+    getWorkspaceMentions(): AutocompleteItem[];
+    /**
+     * Collects base mention items including builtins, registered workspace descriptors,
+     * local files, and external workspace files if matching an external workspace alias query.
+     */
+    private collectMentionItems;
+    /**
+     * Resolves, filters, and ranks suggestions matching the user's @ query.
+     */
+    resolveSuggestions(query: string, options?: AutocompleteOptions): Promise<AutocompleteItem[]>;
+    /**
+     * Resolves, filters, and ranks suggestions synchronously for real-time prompt keystrokes.
+     */
+    resolveSuggestionsSync(query: string, options?: AutocompleteOptions): AutocompleteItem[];
+}
+/**
+ * Resolves context mentions for an @ query string.
+ *
+ * @param query - The search query string without the @ prefix.
+ * @param options - Optional autocomplete configuration.
+ * @returns A promise resolving to ranked autocomplete suggestions.
+ */
+export declare function resolveContextMentions(query: string, options?: AutocompleteOptions): Promise<AutocompleteItem[]>;
 /**
  * A custom text prompt that supports command history navigation using Up/Down arrow keys
- * with memory bounds and dynamic input optimization.
+ * with memory bounds, dynamic input optimization, and real-time interactive @ autocomplete popups.
  *
  * @param opts - The configuration options for the prompt.
  * @returns A promise that resolves to the user's input string or a symbol if cancelled.