minovative-mind-cli 2.13.5 → 2.14.1

package/dist/services/mentionEngine.js

@@ -0,0 +1,1395 @@
+/**
+ * @fileoverview Context Mentions and Autocomplete Engine for Minovative Mind CLI.
+ *
+ * This service provides:
+ * 1. **Autocomplete Suggestions**: Real-time suggestion generation for `@files`, `@symbols`,
+ *    `@git` context helpers, `@workspace` aliases, and `@diagnostics` / special mentions.
+ * 2. **Mention Parsing**: Robust parsing of `@mention` tokens in user prompts with support for
+ *    line ranges (`:10-50`), scoped symbol targets (`@symbol:foo`), git modifiers (`@git:diff`),
+ *    and cross-workspace references (`@alias/path`).
+ * 3. **Context Resolution**: Resolves all mentions in a prompt into structured, sanitized,
+ *    token-budgeted XML injection blocks ready for LLM consumption.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import ignore from 'ignore';
+import { distance } from 'fastest-levenshtein';
+import { workspaceRegistry } from './workspaceRegistry.js';
+import { extractSymbols, extractSymbolIndex, } from '../utils/symbolExtractor.js';
+import { sanitizeForCDATA, estimateTokens, formatContextMentions, CONTEXT_BUDGET_CONFIG, } from '../utils/contextPrompts.js';
+import { resolveAndValidateMultiWorkspacePath, } from '../utils/pathSecurity.js';
+import { localValidate } from '../utils/localSyntaxValidator.js';
+import { debugLog } from '../utils/logger.js';
+const execFileAsync = promisify(execFile);
+// ─── Default Ignored Patterns ────────────────────────────────────────
+const DEFAULT_IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.cache',
+    'coverage',
+    '.turbo',
+    '.tmp',
+    'temp',
+    'tmp',
+    'scratch',
+    '.minovativemind',
+    '.minovative-mind-cli',
+]);
+const DEFAULT_IGNORED_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.DS_Store',
+    'Thumbs.db',
+    '.minovative-scratch.js',
+]);
+const SOURCE_FILE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mts',
+    '.cts',
+    '.mjs',
+    '.cjs',
+    '.py',
+    '.pyi',
+    '.go',
+    '.rs',
+    '.java',
+    '.c',
+    '.cpp',
+    '.h',
+    '.hpp',
+    '.cs',
+    '.php',
+    '.rb',
+    '.swift',
+    '.kt',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.toml',
+    '.md',
+    '.css',
+    '.scss',
+    '.html',
+    '.sql',
+    '.sh',
+    '.bash',
+]);
+/**
+ * Context Mentions Engine.
+ *
+ * Core engine responsible for parsing `@` tokens, providing fast autocomplete suggestions,
+ * and resolving file, symbol, git, workspace, and diagnostic mentions into structured context.
+ */
+export class MentionEngine {
+    /** In-memory cache for workspace file listings (TTL: 15 seconds) */
+    fileListCache = new Map();
+    /** In-memory cache for parsed symbol indexes per file path */
+    symbolIndexCache = new Map();
+    /** Cache TTL in milliseconds */
+    CACHE_TTL_MS = 15_000;
+    // ─── Mention Parsing ────────────────────────────────────────────────
+    /**
+     * Parses all `@mention` tokens from a user prompt text string.
+     *
+     * Correctly ignores email addresses (e.g. `user@domain.com`) and supports:
+     * - `@file:<path>` or `@<path>` (e.g. `@src/index.ts`, `@src/index.ts:10-50`)
+     * - `@symbol:<name>` or `@#<name>` or `@symbol:<filePath>:<name>`
+     * - `@git:diff`, `@git:staged`, `@git:branch`, `@git:log`, `@git:status`, `@diff`
+     * - `@<alias>` or `@<alias>/<path>` for registered external workspaces
+     * - `@diagnostics`, `@problems`, `@errors`
+     *
+     * @param prompt - The input prompt text.
+     * @param workspaceRoot - Optional workspace root for alias and file disambiguation.
+     * @returns Array of ParsedMention objects.
+     */
+    parseMentions(prompt, workspaceRoot = process.cwd()) {
+        if (!prompt || typeof prompt !== 'string')
+            return [];
+        const mentions = [];
+        // Match @ preceded by whitespace, start of line, or common delimiters (excluding word chars to avoid email matching)
+        const mentionRegex = /(?:^|[\s([{"'`=:,])@([A-Za-z0-9_#.:/\-@]+)/g;
+        let match;
+        while ((match = mentionRegex.exec(prompt)) !== null) {
+            const fullMatch = match[0];
+            const token = match[1];
+            // Determine exact start offset of '@'
+            const atIndex = match.index + (fullMatch.indexOf('@'));
+            const raw = `@${token}`;
+            const range = [atIndex, atIndex + raw.length];
+            // Defensive guard against trailing punctuation (e.g. `@src/index.ts.` or `@git:diff,`)
+            let cleanToken = token;
+            let cleanRaw = raw;
+            let cleanEnd = range[1];
+            while (cleanToken.length > 0 && /[,.;:!?'")\]}>]$/.test(cleanToken)) {
+                cleanToken = cleanToken.slice(0, -1);
+                cleanRaw = `@${cleanToken}`;
+                cleanEnd--;
+            }
+            if (!cleanToken)
+                continue;
+            const parsed = this.classifyMentionToken(cleanRaw, cleanToken, atIndex, cleanEnd, workspaceRoot);
+            if (parsed) {
+                mentions.push(parsed);
+            }
+        }
+        return mentions;
+    }
+    /**
+     * Classifies a raw mention token into its appropriate MentionType and targets.
+     *
+     * @private
+     */
+    classifyMentionToken(raw, token, start, end, workspaceRoot) {
+        const range = [start, end];
+        // 1. Git Mentions (@git:diff, @diff, @git:staged, @git:status, @git:branch, @git:log)
+        if (token === 'git' ||
+            token === 'diff' ||
+            token.startsWith('git:') ||
+            token.startsWith('diff:')) {
+            let sub = 'diff';
+            if (token.includes(':')) {
+                sub = token.split(':')[1].toLowerCase();
+            }
+            else if (token === 'diff') {
+                sub = 'diff';
+            }
+            return {
+                raw,
+                type: 'git',
+                target: sub || 'diff',
+                range,
+                valid: true,
+            };
+        }
+        // 2. Diagnostics / Problems / Errors Mentions (@diagnostics, @problems, @errors, @diag, @prob)
+        if (token === 'diagnostics' ||
+            token === 'problems' ||
+            token === 'errors' ||
+            token === 'diag' ||
+            token === 'prob') {
+            return {
+                raw,
+                type: 'diagnostics',
+                target: token,
+                range,
+                valid: true,
+            };
+        }
+        // 3. Terminal / Console Mentions (@terminal, @console, @term)
+        if (token === 'terminal' || token === 'console' || token === 'term') {
+            return {
+                raw,
+                type: 'terminal',
+                target: token,
+                range,
+                valid: true,
+            };
+        }
+        // 4. Explicit Symbol Mentions (@symbol:name, @#name, @symbol:filePath:name)
+        if (token.startsWith('symbol:') || token.startsWith('sym:') || token.startsWith('#')) {
+            const body = token.startsWith('symbol:')
+                ? token.slice(7)
+                : token.startsWith('sym:')
+                    ? token.slice(4)
+                    : token.slice(1);
+            if (!body) {
+                return {
+                    raw,
+                    type: 'symbol',
+                    target: '',
+                    range,
+                    valid: false,
+                    error: 'Empty symbol identifier.',
+                };
+            }
+            // Check if file path is prefixed (e.g. `src/utils.ts:extractSymbols`)
+            if (body.includes(':')) {
+                const parts = body.split(':');
+                return {
+                    raw,
+                    type: 'symbol',
+                    target: parts[parts.length - 1],
+                    subTarget: parts.slice(0, -1).join(':'),
+                    range,
+                    valid: true,
+                };
+            }
+            return {
+                raw,
+                type: 'symbol',
+                target: body,
+                range,
+                valid: true,
+            };
+        }
+        // 5. Explicit File Mentions (@file:path or @file:path:10-50)
+        if (token.startsWith('file:')) {
+            const filePathWithLine = token.slice(5);
+            const { filePath, lineRange } = this.parseLineRange(filePathWithLine);
+            const alias = workspaceRegistry.isAliasedPath(filePath)
+                ? filePath.slice(1).split('/')[0]
+                : null;
+            return {
+                raw,
+                type: 'file',
+                target: filePath,
+                workspaceAlias: alias,
+                lineRange,
+                range,
+                valid: Boolean(filePath),
+            };
+        }
+        // 6. Registered Workspace Reference (@alias or @alias/path)
+        const firstSlash = token.indexOf('/');
+        const candidateAlias = firstSlash === -1 ? token : token.slice(0, firstSlash);
+        const registeredWorkspaces = workspaceRegistry.list().map((w) => w.alias.toLowerCase());
+        if (registeredWorkspaces.includes(candidateAlias.toLowerCase())) {
+            if (firstSlash === -1) {
+                // Just the workspace alias (@alias)
+                return {
+                    raw,
+                    type: 'workspace',
+                    target: candidateAlias,
+                    workspaceAlias: candidateAlias,
+                    range,
+                    valid: true,
+                };
+            }
+            // Workspace file reference (@alias/src/...)
+            const { filePath, lineRange } = this.parseLineRange(token);
+            return {
+                raw,
+                type: 'file',
+                target: filePath,
+                workspaceAlias: candidateAlias,
+                lineRange,
+                range,
+                valid: true,
+            };
+        }
+        // 7. Implicit File Mention (@src/index.ts, @./config.json, @test/foo.test.ts:10-20)
+        // Check if token looks like a file path (has slashes, extension, or relative prefix)
+        const hasPathIndicators = token.includes('/') ||
+            token.startsWith('./') ||
+            token.startsWith('../') ||
+            /\.[a-zA-Z0-9_-]{1,10}(?::\d+(?:-\d+)?)?$/.test(token);
+        if (hasPathIndicators) {
+            const { filePath, lineRange } = this.parseLineRange(token);
+            const alias = workspaceRegistry.isAliasedPath(filePath)
+                ? filePath.slice(1).split('/')[0]
+                : null;
+            return {
+                raw,
+                type: 'file',
+                target: filePath,
+                workspaceAlias: alias,
+                lineRange,
+                range,
+                valid: Boolean(filePath),
+            };
+        }
+        // 8. Implicit Symbol Reference (e.g. `@parseTargetSymbol` or `@UserService.getUser`)
+        if (/^[A-Za-z_$][A-Za-z0-9_$.#:-]*$/.test(token)) {
+            return {
+                raw,
+                type: 'symbol',
+                target: token,
+                range,
+                valid: true,
+            };
+        }
+        // Fallback generic mention
+        return {
+            raw,
+            type: 'file',
+            target: token,
+            range,
+            valid: false,
+            error: `Unrecognized mention format: ${raw}`,
+        };
+    }
+    /**
+     * Extracts line range numbers from a path string (e.g. `src/index.ts:10-50` or `src/index.ts#10-50` or `src/index.ts:25`).
+     *
+     * @private
+     */
+    parseLineRange(pathWithLine) {
+        // Check :start-end or #start-end or :start
+        const match = pathWithLine.match(/[:#](?:L)?(\d+)(?:-(?:L)?(\d+))?$/i);
+        if (!match) {
+            return { filePath: pathWithLine };
+        }
+        const filePath = pathWithLine.slice(0, match.index);
+        const start = Number.parseInt(match[1], 10);
+        const end = match[2] ? Number.parseInt(match[2], 10) : start;
+        return {
+            filePath,
+            lineRange: {
+                start: Math.min(start, end),
+                end: Math.max(start, end),
+            },
+        };
+    }
+    // ─── Autocomplete Query & Suggestions ───────────────────────────────
+    /**
+     * Determines the active mention query at a specific cursor position in an input string.
+     *
+     * @param input - The current input text.
+     * @param cursorPosition - The 0-based cursor offset.
+     * @returns Object describing the active mention query and range.
+     */
+    getActiveMentionQuery(input, cursorPosition) {
+        if (!input || cursorPosition <= 0) {
+            return { query: '', startIndex: -1, endIndex: -1, isMention: false };
+        }
+        const textBeforeCursor = input.slice(0, cursorPosition);
+        // Find last '@' that is either at the beginning or preceded by whitespace/delimiters
+        const lastAtIndex = textBeforeCursor.lastIndexOf('@');
+        if (lastAtIndex === -1) {
+            return { query: '', startIndex: -1, endIndex: -1, isMention: false };
+        }
+        // Ensure '@' is preceded by start of text or whitespace/delimiter (not part of email)
+        if (lastAtIndex > 0) {
+            const prevChar = textBeforeCursor[lastAtIndex - 1];
+            if (/[A-Za-z0-9_]/.test(prevChar)) {
+                return { query: '', startIndex: -1, endIndex: -1, isMention: false };
+            }
+        }
+        const queryCandidate = textBeforeCursor.slice(lastAtIndex + 1);
+        // If there is whitespace between '@' and cursor, it's no longer an active mention query
+        if (/\s/.test(queryCandidate)) {
+            return { query: '', startIndex: -1, endIndex: -1, isMention: false };
+        }
+        return {
+            query: queryCandidate,
+            startIndex: lastAtIndex,
+            endIndex: cursorPosition,
+            isMention: true,
+        };
+    }
+    /**
+     * Generates ranked autocomplete suggestions based on the current prompt text and cursor position.
+     *
+     * @param input - Full prompt input text.
+     * @param cursorPosition - Cursor index.
+     * @param options - Suggestion configuration options.
+     * @returns Array of ranked MentionSuggestion objects.
+     */
+    async getSuggestions(input, cursorPosition, options = {}) {
+        const active = this.getActiveMentionQuery(input, cursorPosition);
+        if (!active.isMention) {
+            return [];
+        }
+        return this.getSuggestionsForQuery(active.query, {
+            ...options,
+            cursorPosition,
+        });
+    }
+    /**
+     * Generates autocomplete suggestions for a given raw query string (the text after '@').
+     *
+     * @param query - The query string typed after '@'.
+     * @param options - Configuration options.
+     * @returns Array of ranked MentionSuggestion objects.
+     */
+    async getSuggestionsForQuery(query = '', options = {}) {
+        const workspaceRoot = options.workspaceRoot || process.cwd();
+        const maxSuggestions = options.maxSuggestions ?? 25;
+        const includeTypes = options.includeTypes
+            ? new Set(options.includeTypes)
+            : new Set(['file', 'symbol', 'git', 'workspace', 'diagnostics', 'terminal']);
+        const rawClean = query.startsWith('@') ? query.slice(1) : query;
+        const normalizedQuery = rawClean.toLowerCase().trim();
+        const suggestions = [];
+        // 1. Special & Git Suggestions
+        if (includeTypes.has('git') || includeTypes.has('diagnostics') || includeTypes.has('terminal')) {
+            const specialSuggestions = this.getSpecialSuggestions(normalizedQuery, includeTypes);
+            suggestions.push(...specialSuggestions);
+        }
+        // 2. Workspace Alias Suggestions
+        if (includeTypes.has('workspace')) {
+            const workspaceSuggestions = this.getWorkspaceSuggestions(normalizedQuery);
+            suggestions.push(...workspaceSuggestions);
+        }
+        // 3. File Suggestions (for current workspace or external workspace)
+        if (includeTypes.has('file')) {
+            let fileSearchQuery = normalizedQuery;
+            let targetWorkspaceRoot = workspaceRoot;
+            let prefixAlias = null;
+            if (fileSearchQuery.startsWith('file:')) {
+                fileSearchQuery = fileSearchQuery.slice(5);
+            }
+            // Check if querying an external workspace (e.g. `@backend/src` or `backend/src` or `backend/`)
+            const cleanFileQuery = fileSearchQuery.startsWith('@') ? fileSearchQuery.slice(1) : fileSearchQuery;
+            const slashIdx = cleanFileQuery.indexOf('/');
+            if (slashIdx !== -1) {
+                const alias = cleanFileQuery.slice(0, slashIdx);
+                const ws = workspaceRegistry.get(alias);
+                if (ws) {
+                    targetWorkspaceRoot = ws.absolutePath;
+                    prefixAlias = ws.alias;
+                    fileSearchQuery = cleanFileQuery.slice(slashIdx + 1);
+                }
+            }
+            const fileSuggestions = await this.getFileSuggestions(fileSearchQuery, targetWorkspaceRoot, prefixAlias, prefixAlias ? undefined : options.cachedFileList);
+            suggestions.push(...fileSuggestions);
+        }
+        // 4. Symbol Suggestions
+        if (includeTypes.has('symbol')) {
+            let symbolQuery = normalizedQuery;
+            const isHash = normalizedQuery.startsWith('#');
+            if (symbolQuery.startsWith('symbol:') || symbolQuery.startsWith('sym:') || symbolQuery.startsWith('#')) {
+                symbolQuery = symbolQuery.startsWith('symbol:')
+                    ? symbolQuery.slice(7)
+                    : symbolQuery.startsWith('sym:')
+                        ? symbolQuery.slice(4)
+                        : symbolQuery.slice(1);
+            }
+            // Only search symbols if query explicitly triggers symbols or has length >= 2
+            const isExplicitSymbol = normalizedQuery.startsWith('symbol:') ||
+                normalizedQuery.startsWith('sym:') ||
+                normalizedQuery.startsWith('#');
+            if (isExplicitSymbol || symbolQuery.length >= 2) {
+                const symbolSuggestions = await this.getSymbolSuggestions(symbolQuery, workspaceRoot, options.maxSymbolFiles ?? 250, isHash);
+                suggestions.push(...symbolSuggestions);
+            }
+        }
+        // Sort by relevance score descending
+        suggestions.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+        return suggestions.slice(0, maxSuggestions);
+    }
+    /**
+     * Generates built-in git, diagnostics, terminal, and symbol template suggestions.
+     *
+     * @private
+     */
+    getSpecialSuggestions(query, includeTypes) {
+        const special = [];
+        if (includeTypes.has('git')) {
+            const gitItems = [
+                {
+                    label: '@git:diff',
+                    value: '@git:diff',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Git diff of uncommitted working tree changes',
+                    detail: 'Working tree modifications',
+                    helperLabel: '[git] uncommitted diff',
+                    icon: '🔀',
+                    keywords: ['git:diff', 'diff', 'git', 'changes', 'uncommitted'],
+                },
+                {
+                    label: '@diff',
+                    value: '@diff',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Quick git diff of uncommitted working changes',
+                    detail: 'Alias for @git:diff',
+                    helperLabel: '[git] working tree diff',
+                    icon: '🔀',
+                    keywords: ['diff', 'git:diff', 'git', 'changes', 'uncommitted'],
+                },
+                {
+                    label: '@git:staged',
+                    value: '@git:staged',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Git diff of staged / index changes',
+                    detail: 'Staged index modifications',
+                    helperLabel: '[git] staged diff',
+                    icon: '📦',
+                    keywords: ['git:staged', 'staged', 'git', 'index'],
+                },
+                {
+                    label: '@git:status',
+                    value: '@git:status',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Git working tree status summary',
+                    detail: 'Modified & untracked files',
+                    helperLabel: '[git] status summary',
+                    icon: '📊',
+                    keywords: ['git:status', 'status', 'git', 'modified', 'untracked'],
+                },
+                {
+                    label: '@git:branch',
+                    value: '@git:branch',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Current git branch name and tracking status',
+                    detail: 'Active branch metadata',
+                    helperLabel: '[git] active branch',
+                    icon: '🌿',
+                    keywords: ['git:branch', 'branch', 'git', 'head'],
+                },
+                {
+                    label: '@git:log',
+                    value: '@git:log',
+                    type: 'git',
+                    category: 'git',
+                    description: 'Recent git commit history (last 5 commits)',
+                    detail: 'Commit log summary',
+                    helperLabel: '[git] commit log',
+                    icon: '📜',
+                    keywords: ['git:log', 'log', 'commits', 'history'],
+                },
+            ];
+            for (const item of gitItems) {
+                const score = this.calculateMatchScore(query, item.keywords, item.label);
+                if (score > 0) {
+                    special.push({ ...item, score });
+                }
+            }
+        }
+        if (includeTypes.has('diagnostics')) {
+            const diagItems = [
+                {
+                    label: '@diagnostics',
+                    value: '@diagnostics',
+                    type: 'diagnostics',
+                    category: 'diag',
+                    description: 'Current workspace syntax and linter diagnostics',
+                    detail: 'Validation errors & warnings',
+                    helperLabel: '[diag] syntax & lint scan',
+                    icon: '⚠️',
+                    keywords: ['diagnostics', 'diag', 'problems', 'errors', 'lint', 'syntax'],
+                },
+                {
+                    label: '@problems',
+                    value: '@problems',
+                    type: 'diagnostics',
+                    category: 'prob',
+                    description: 'Workspace diagnostics and syntax problem scan',
+                    detail: 'Alias for @diagnostics',
+                    helperLabel: '[prob] problem scan',
+                    icon: '⚠️',
+                    keywords: ['problems', 'prob', 'diagnostics', 'errors', 'lint', 'syntax'],
+                },
+                {
+                    label: '@errors',
+                    value: '@errors',
+                    type: 'diagnostics',
+                    category: 'diag',
+                    description: 'Workspace errors and syntax diagnostics',
+                    detail: 'Alias for @diagnostics',
+                    helperLabel: '[diag] error scan',
+                    icon: '❌',
+                    keywords: ['errors', 'error', 'diagnostics', 'problems', 'syntax', 'diag'],
+                },
+            ];
+            for (const item of diagItems) {
+                const score = this.calculateMatchScore(query, item.keywords, item.label);
+                if (score > 0) {
+                    special.push({ ...item, score });
+                }
+            }
+        }
+        if (includeTypes.has('terminal')) {
+            const termItems = [
+                {
+                    label: '@terminal',
+                    value: '@terminal',
+                    type: 'terminal',
+                    category: 'term',
+                    description: 'Terminal environment, shell info, and working directory',
+                    detail: 'Node/platform environment',
+                    helperLabel: '[term] shell & platform',
+                    icon: '💻',
+                    keywords: ['terminal', 'term', 'shell', 'console', 'env'],
+                },
+                {
+                    label: '@console',
+                    value: '@console',
+                    type: 'terminal',
+                    category: 'term',
+                    description: 'Console environment and terminal session details',
+                    detail: 'Alias for @terminal',
+                    helperLabel: '[term] console session',
+                    icon: '🖥️',
+                    keywords: ['console', 'terminal', 'shell', 'env', 'term'],
+                },
+            ];
+            for (const item of termItems) {
+                const score = this.calculateMatchScore(query, item.keywords, item.label);
+                if (score > 0) {
+                    special.push({ ...item, score });
+                }
+            }
+        }
+        if (includeTypes.has('symbol') || query.startsWith('sym') || query.startsWith('#') || query.startsWith('symbol')) {
+            const symTemplateItem = {
+                label: '@symbol:<name>',
+                value: '@symbol:',
+                type: 'symbol',
+                category: 'sym',
+                description: 'AST symbol extraction (@symbol:name, @#name, @symbol:path:name)',
+                detail: 'Extract function, class, or type declaration',
+                helperLabel: '[sym] AST symbol extraction',
+                icon: '⚡',
+                keywords: ['symbol:', 'symbol', 'sym:', 'sym', '#', 'ast', 'function', 'class', 'method', 'type'],
+            };
+            const score = this.calculateMatchScore(query, symTemplateItem.keywords, symTemplateItem.label);
+            if (score > 0) {
+                special.push({ ...symTemplateItem, score: score + 10 });
+            }
+        }
+        return special;
+    }
+    /**
+     * Generates registered workspace alias suggestions.
+     *
+     * @private
+     */
+    getWorkspaceSuggestions(query) {
+        const workspaces = workspaceRegistry.list();
+        const suggestions = [];
+        for (const ws of workspaces) {
+            const aliasLabel = `@${ws.alias}`;
+            const keywords = [ws.alias, `@${ws.alias}`, path.basename(ws.absolutePath)];
+            const score = this.calculateMatchScore(query, keywords, aliasLabel);
+            if (score > 0) {
+                suggestions.push({
+                    label: aliasLabel,
+                    value: aliasLabel,
+                    type: 'workspace',
+                    category: 'ws',
+                    description: `External workspace: ${ws.absolutePath}`,
+                    detail: `Profile: ${ws.profile}`,
+                    helperLabel: `[ws] @${ws.alias}`,
+                    icon: '📁',
+                    workspaceAlias: ws.alias,
+                    score: score + 15, // boost workspace aliases
+                });
+            }
+        }
+        return suggestions;
+    }
+    /**
+     * Generates workspace file suggestions with fast fuzzy/prefix matching.
+     *
+     * @private
+     */
+    async getFileSuggestions(query, workspaceRoot, prefixAlias = null, cachedFiles) {
+        const files = cachedFiles || (await this.getFileList(workspaceRoot));
+        const suggestions = [];
+        for (const relPath of files) {
+            const basename = path.basename(relPath);
+            const ext = path.extname(relPath);
+            const fullDisplayPath = prefixAlias ? `${prefixAlias}/${relPath}` : relPath;
+            const insertValue = prefixAlias ? `@${prefixAlias}/${relPath}` : `@${relPath}`;
+            // Keywords for scoring
+            const keywords = [
+                relPath.toLowerCase(),
+                basename.toLowerCase(),
+                fullDisplayPath.toLowerCase(),
+            ];
+            const score = this.calculateMatchScore(query, keywords, basename.toLowerCase());
+            if (score > 0) {
+                suggestions.push({
+                    label: `@${fullDisplayPath}`,
+                    value: insertValue,
+                    type: 'file',
+                    category: prefixAlias ? 'ws' : 'file',
+                    description: prefixAlias ? `Workspace file: @${prefixAlias}` : `File (${ext || 'binary'})`,
+                    detail: prefixAlias ? `[${prefixAlias}] ${relPath}` : relPath,
+                    helperLabel: prefixAlias ? `[ws] @${prefixAlias}/${relPath}` : `[file] ${relPath}`,
+                    icon: this.getFileIcon(ext),
+                    filePath: relPath,
+                    workspaceAlias: prefixAlias,
+                    score,
+                });
+            }
+        }
+        return suggestions;
+    }
+    /**
+     * Generates symbol suggestions across indexed source files.
+     *
+     * @private
+     */
+    async getSymbolSuggestions(query, workspaceRoot, maxFiles = 250, isHash = false) {
+        const symbols = await this.getSymbolIndex(workspaceRoot, maxFiles);
+        const suggestions = [];
+        for (const item of symbols) {
+            const symName = item.symbol;
+            const keywords = [symName.toLowerCase(), path.basename(item.filePath).toLowerCase()];
+            const score = this.calculateMatchScore(query, keywords, symName.toLowerCase());
+            if (score > 0) {
+                const kindLabel = item.kind ? `${item.kind} in ` : '';
+                const prefix = isHash ? '@#' : '@symbol:';
+                suggestions.push({
+                    label: `${prefix}${symName}`,
+                    value: `${prefix}${symName}`,
+                    type: 'symbol',
+                    category: 'sym',
+                    description: `${kindLabel}${item.filePath}`,
+                    detail: item.signature || symName,
+                    helperLabel: `[sym] ${symName}`,
+                    icon: this.getSymbolIcon(item.kind),
+                    filePath: item.filePath,
+                    symbolKind: item.kind,
+                    score: score + 5, // slightly boost exact symbol matches
+                });
+            }
+        }
+        return suggestions;
+    }
+    /**
+     * Calculates a match score between a user query and candidate keywords.
+     * Higher scores represent stronger matches.
+     *
+     * @private
+     */
+    calculateMatchScore(query, keywords, primaryText) {
+        if (!query)
+            return 50; // Base score for empty query
+        let maxScore = 0;
+        for (const kw of keywords) {
+            if (kw === query) {
+                maxScore = Math.max(maxScore, 100); // Exact match
+            }
+            else if (kw.startsWith(query)) {
+                maxScore = Math.max(maxScore, 85 + (query.length / kw.length) * 10); // Prefix match
+            }
+            else if (kw.includes(query)) {
+                maxScore = Math.max(maxScore, 70 + (query.length / kw.length) * 10); // Substring match
+            }
+            else if (query.length >= 3) {
+                // Levenshtein fuzzy distance for typos
+                const lev = distance(query, kw.slice(0, query.length));
+                if (lev <= 1) {
+                    maxScore = Math.max(maxScore, 60);
+                }
+            }
+        }
+        // Boost if primary text (e.g. basename or symbol name) starts with query
+        if (primaryText.startsWith(query)) {
+            maxScore += 10;
+        }
+        return maxScore;
+    }
+    // ─── Workspace File & Symbol Indexing ────────────────────────────────
+    /**
+     * Returns a cached recursive list of all relative file paths in the workspace.
+     *
+     * @param workspaceRoot - Root directory path.
+     * @param maxFiles - Safety ceiling on maximum files returned (defaults to 3000).
+     * @returns Array of relative file paths.
+     */
+    async getFileList(workspaceRoot, maxFiles = 3000) {
+        const normalizedRoot = path.resolve(workspaceRoot);
+        const cached = this.fileListCache.get(normalizedRoot);
+        const now = Date.now();
+        if (cached && now - cached.timestamp < this.CACHE_TTL_MS) {
+            return cached.files;
+        }
+        const files = [];
+        const ig = ignore();
+        ig.add(Array.from(DEFAULT_IGNORED_DIRS).map((d) => `${d}/`));
+        ig.add(Array.from(DEFAULT_IGNORED_FILES));
+        // Read project .gitignore if present
+        const gitignorePath = path.join(normalizedRoot, '.gitignore');
+        if (fs.existsSync(gitignorePath)) {
+            try {
+                const content = await fs.promises.readFile(gitignorePath, 'utf-8');
+                ig.add(content);
+            }
+            catch {
+                // Continue with defaults
+            }
+        }
+        const scanDirectory = async (currentDir, relativeBase) => {
+            if (files.length >= maxFiles)
+                return;
+            let entries;
+            try {
+                entries = await fs.promises.readdir(currentDir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (files.length >= maxFiles)
+                    break;
+                const relPath = relativeBase ? `${relativeBase}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    if (DEFAULT_IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                        continue;
+                    if (ig.ignores(`${relPath}/`))
+                        continue;
+                    await scanDirectory(path.join(currentDir, entry.name), relPath);
+                }
+                else if (entry.isFile()) {
+                    if (DEFAULT_IGNORED_FILES.has(entry.name))
+                        continue;
+                    if (ig.ignores(relPath))
+                        continue;
+                    files.push(relPath);
+                }
+            }
+        };
+        await scanDirectory(normalizedRoot, '');
+        this.fileListCache.set(normalizedRoot, { files, timestamp: now, root: normalizedRoot });
+        return files;
+    }
+    /**
+     * Extracts and returns all declared symbols across workspace source files.
+     *
+     * @param workspaceRoot - Workspace root path.
+     * @param maxFiles - Maximum source files to scan.
+     * @returns Array of symbol entries.
+     */
+    async getSymbolIndex(workspaceRoot, maxFiles = 250) {
+        const fileList = await this.getFileList(workspaceRoot);
+        const sourceFiles = fileList
+            .filter((f) => SOURCE_FILE_EXTENSIONS.has(path.extname(f).toLowerCase()))
+            .sort((a, b) => {
+            const aIsSrc = a.startsWith('src/') || a.startsWith('lib/') || a.startsWith('app/') ? 0 : 1;
+            const bIsSrc = b.startsWith('src/') || b.startsWith('lib/') || b.startsWith('app/') ? 0 : 1;
+            if (aIsSrc !== bIsSrc)
+                return aIsSrc - bIsSrc;
+            return a.localeCompare(b);
+        })
+            .slice(0, maxFiles);
+        const allSymbols = [];
+        for (const relPath of sourceFiles) {
+            const fullPath = path.resolve(workspaceRoot, relPath);
+            try {
+                const stat = await fs.promises.stat(fullPath);
+                const cached = this.symbolIndexCache.get(fullPath);
+                if (cached && cached.mtimeMs === stat.mtimeMs) {
+                    allSymbols.push(...cached.symbols);
+                    continue;
+                }
+                const content = await fs.promises.readFile(fullPath, 'utf-8');
+                const rawSymbols = extractSymbolIndex(content, fullPath);
+                const fileSymbols = rawSymbols.map((s) => ({
+                    symbol: s.symbol,
+                    kind: s.kind,
+                    filePath: relPath,
+                    signature: s.signature,
+                    startLine: s.startLine,
+                    endLine: s.endLine,
+                }));
+                this.symbolIndexCache.set(fullPath, {
+                    symbols: fileSymbols,
+                    mtimeMs: stat.mtimeMs,
+                });
+                allSymbols.push(...fileSymbols);
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        return allSymbols;
+    }
+    // ─── Mention Context Resolution ─────────────────────────────────────
+    /**
+     * Resolves all mentions in a prompt string into structured context injection blocks.
+     *
+     * @param prompt - The user prompt containing `@mentions`.
+     * @param workspaceRoot - The primary workspace root path.
+     * @param options - Resolution and token budgeting options.
+     * @returns Comprehensive ResolvedMentionsResult containing structured XML blocks.
+     */
+    async resolveMentions(prompt, workspaceRoot = process.cwd(), options = {}) {
+        const parsedMentions = this.parseMentions(prompt, workspaceRoot);
+        if (parsedMentions.length === 0) {
+            return {
+                originalPrompt: prompt,
+                cleanedPrompt: prompt,
+                mentions: [],
+                formattedContext: '',
+                totalTokens: 0,
+                hasMentions: false,
+            };
+        }
+        const resolvedMentions = [];
+        const seenMentionKeys = new Set();
+        for (const mention of parsedMentions) {
+            // Deduplicate identical mentions in the same prompt
+            const dedupeKey = `${mention.type}:${mention.target}:${mention.subTarget || ''}:${JSON.stringify(mention.lineRange || {})}`;
+            if (seenMentionKeys.has(dedupeKey))
+                continue;
+            seenMentionKeys.add(dedupeKey);
+            try {
+                const resolved = await this.resolveSingleMention(mention, workspaceRoot, options);
+                resolvedMentions.push(resolved);
+            }
+            catch (err) {
+                debugLog(`[MentionEngine] Failed to resolve mention ${mention.raw}: ${err.message}`);
+                resolvedMentions.push({
+                    mention,
+                    resolved: false,
+                    content: `<!-- Failed to resolve mention ${mention.raw}: ${err.message} -->`,
+                    tokenEstimate: 0,
+                    error: err.message,
+                });
+            }
+        }
+        const formattedContext = this.formatMentionsContext(resolvedMentions, options.maxChars);
+        const totalTokens = estimateTokens(formattedContext);
+        return {
+            originalPrompt: prompt,
+            cleanedPrompt: prompt,
+            mentions: resolvedMentions,
+            formattedContext,
+            totalTokens,
+            hasMentions: resolvedMentions.length > 0,
+        };
+    }
+    /**
+     * Resolves a single parsed mention into its structured XML context block.
+     *
+     * @private
+     */
+    async resolveSingleMention(mention, workspaceRoot, options) {
+        switch (mention.type) {
+            case 'file':
+                return this.resolveFileMention(mention, workspaceRoot, options);
+            case 'symbol':
+                return this.resolveSymbolMention(mention, workspaceRoot, options);
+            case 'git':
+                return this.resolveGitMention(mention, workspaceRoot, options);
+            case 'workspace':
+                return this.resolveWorkspaceMention(mention, workspaceRoot, options);
+            case 'diagnostics':
+                return this.resolveDiagnosticsMention(mention, workspaceRoot, options);
+            case 'terminal':
+                return this.resolveTerminalMention(mention, workspaceRoot, options);
+            default:
+                throw new Error(`Unsupported mention type: ${mention.type}`);
+        }
+    }
+    /**
+     * Resolves a file mention (`@file:src/index.ts` or `@src/index.ts:10-50`).
+     *
+     * @private
+     */
+    async resolveFileMention(mention, workspaceRoot, options) {
+        const targetPath = mention.workspaceAlias && !mention.target.startsWith('@')
+            ? `@${mention.target}`
+            : mention.target;
+        const resolvedPath = resolveAndValidateMultiWorkspacePath(workspaceRoot, targetPath);
+        if (!fs.existsSync(resolvedPath.absolutePath)) {
+            throw new Error(`File does not exist: "${mention.target}"`);
+        }
+        const stats = await fs.promises.stat(resolvedPath.absolutePath);
+        if (!stats.isFile()) {
+            throw new Error(`Target is not a file: "${mention.target}"`);
+        }
+        const fullContent = await fs.promises.readFile(resolvedPath.absolutePath, 'utf-8');
+        const allLines = fullContent.split('\n');
+        const totalLines = allLines.length;
+        let fileContent = fullContent;
+        let lineRangeAttr = '';
+        const isSliced = Boolean(mention.lineRange);
+        if (mention.lineRange) {
+            const startIdx = Math.max(0, mention.lineRange.start - 1);
+            const endIdx = Math.min(allLines.length, mention.lineRange.end);
+            fileContent = allLines.slice(startIdx, endIdx).join('\n');
+            lineRangeAttr = ` lines="${mention.lineRange.start}-${mention.lineRange.end}"`;
+        }
+        const slicedLines = fileContent.split('\n');
+        const linesCount = slicedLines.length;
+        const charCount = fileContent.length;
+        const category = isSliced ? 'lines' : 'file';
+        const statusLabel = isSliced
+            ? `lines ${mention.lineRange.start}-${mention.lineRange.end}, ${charCount} chars`
+            : `file (${stats.size} bytes, ${totalLines} lines)`;
+        const helperLabel = isSliced
+            ? `[lines] ${mention.target} (${mention.lineRange.start}-${mention.lineRange.end})`
+            : `[file] ${mention.target} (${totalLines} lines)`;
+        const workspaceAttr = resolvedPath.alias ? ` workspace="${resolvedPath.alias}"` : '';
+        const formattedContent = `<workspace_file path="${mention.target}"${workspaceAttr}${lineRangeAttr}>
+<content_data><![CDATA[
+${sanitizeForCDATA(fileContent)}
+]]\\u200B></content_data>
+</workspace_file>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                absolutePath: resolvedPath.absolutePath,
+                relativePath: mention.target,
+                sizeBytes: stats.size,
+                charCount,
+                linesCount,
+                totalLines,
+                lineRange: mention.lineRange,
+                isSliced,
+                workspaceAlias: resolvedPath.alias || null,
+                category,
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Resolves a symbol mention (`@symbol:extractSymbols` or `@#extractSymbols`).
+     *
+     * @private
+     */
+    async resolveSymbolMention(mention, workspaceRoot, options) {
+        const symbolName = mention.target;
+        let targetFilePath = mention.subTarget;
+        let matchedSymbol;
+        // If file path not specified, search symbol index to find declaration file
+        if (!targetFilePath) {
+            const symbols = await this.getSymbolIndex(workspaceRoot);
+            const found = symbols.find((s) => s.symbol.toLowerCase() === symbolName.toLowerCase());
+            if (found) {
+                targetFilePath = found.filePath;
+                matchedSymbol = found;
+            }
+        }
+        if (!targetFilePath) {
+            throw new Error(`Could not find declaration for symbol "${symbolName}" across workspace files.`);
+        }
+        const resolved = resolveAndValidateMultiWorkspacePath(workspaceRoot, targetFilePath);
+        if (!fs.existsSync(resolved.absolutePath)) {
+            throw new Error(`File containing symbol not found: "${targetFilePath}"`);
+        }
+        const rawContent = await fs.promises.readFile(resolved.absolutePath, 'utf-8');
+        const extractedBlock = extractSymbols(rawContent, resolved.absolutePath, [symbolName], {
+            maxLinesPerSymbol: options.symbolMaxLines ?? 300,
+        });
+        const linesCount = extractedBlock.split('\n').length;
+        const charCount = extractedBlock.length;
+        const statusLabel = `${targetFilePath}, ${linesCount} lines`;
+        const helperLabel = `[sym] ${symbolName} in ${targetFilePath} (${linesCount} lines)`;
+        const formattedContent = `<symbol_definition symbol="${symbolName}" file="${targetFilePath}">
+<content_data><![CDATA[
+${sanitizeForCDATA(extractedBlock)}
+]]\\u200B></content_data>
+</symbol_definition>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                symbol: symbolName,
+                filePath: targetFilePath,
+                kind: matchedSymbol?.kind || 'symbol',
+                signature: matchedSymbol?.signature || symbolName,
+                startLine: matchedSymbol?.startLine,
+                endLine: matchedSymbol?.endLine,
+                linesCount,
+                charCount,
+                category: 'symbol',
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Resolves a git mention (`@git:diff`, `@git:staged`, `@git:branch`, `@git:log`, `@git:status`, `@diff`).
+     *
+     * @private
+     */
+    async resolveGitMention(mention, workspaceRoot, options) {
+        const gitSubCommand = mention.target.toLowerCase() || 'diff';
+        const timeout = options.gitTimeoutMs ?? 5000;
+        let gitArgs = [];
+        let contextType = gitSubCommand;
+        switch (gitSubCommand) {
+            case 'staged':
+            case 'cached':
+                gitArgs = ['diff', '--cached'];
+                contextType = 'staged_diff';
+                break;
+            case 'branch':
+            case 'head':
+                gitArgs = ['branch', '-vv'];
+                contextType = 'branch';
+                break;
+            case 'log':
+            case 'history':
+                gitArgs = ['log', '-n', '5', '--oneline', '--decorate'];
+                contextType = 'log';
+                break;
+            case 'status':
+                gitArgs = ['status', '--short'];
+                contextType = 'status';
+                break;
+            case 'diff':
+            default:
+                gitArgs = ['diff'];
+                contextType = 'diff';
+                break;
+        }
+        let output = '';
+        let isClean = false;
+        try {
+            const { stdout } = await execFileAsync('git', gitArgs, {
+                cwd: workspaceRoot,
+                timeout,
+                maxBuffer: 5 * 1024 * 1024,
+                encoding: 'utf-8',
+                env: { ...process.env, GIT_PAGER: 'cat', GIT_TERMINAL_PROMPT: '0' },
+            });
+            output = stdout.trim();
+            isClean = !output;
+        }
+        catch (err) {
+            output = `[Git command "git ${gitArgs.join(' ')}" returned error: ${err.message}]`;
+        }
+        if (!output) {
+            output = `[No ${contextType} output / clean working tree]`;
+            isClean = true;
+        }
+        const outputLines = output.split('\n').length;
+        const statusLabel = gitSubCommand === 'status'
+            ? `short status, ${isClean ? 'clean' : 'modified'}`
+            : `${contextType}, ${outputLines} lines${isClean ? ' (clean)' : ''}`;
+        const helperLabel = `[git] ${gitSubCommand} (${outputLines} lines)`;
+        const formattedContent = `<git_context type="${contextType}">
+<content_data><![CDATA[
+${sanitizeForCDATA(output)}
+]]\\u200B></content_data>
+</git_context>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                gitSubCommand,
+                contextType,
+                outputLines,
+                charCount: output.length,
+                isClean,
+                category: 'git',
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Resolves a registered workspace alias mention (`@effortlist-ai`).
+     *
+     * @private
+     */
+    async resolveWorkspaceMention(mention, workspaceRoot, options) {
+        const alias = mention.target;
+        const ws = workspaceRegistry.get(alias);
+        if (!ws) {
+            throw new Error(`Workspace alias "@${alias}" is not registered. Use /workspaces to register it.`);
+        }
+        const files = await this.getFileList(ws.absolutePath, 50);
+        const summary = `Profile: ${ws.profile}\nRoot: ${ws.absolutePath}\nRegistered: ${new Date(ws.registeredAt).toISOString()}\n\nSample Files (${files.length} found):\n${files.slice(0, 25).map((f) => `- ${f}`).join('\n')}`;
+        const statusLabel = `external workspace (${files.length} files scanned)`;
+        const helperLabel = `[ws] @${alias} (${ws.profile})`;
+        const formattedContent = `<workspace_context alias="${alias}" path="${ws.absolutePath}">
+<content_data><![CDATA[
+${sanitizeForCDATA(summary)}
+]]\\u200B></content_data>
+</workspace_context>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                alias,
+                path: ws.absolutePath,
+                profile: ws.profile,
+                filesCount: files.length,
+                category: 'workspace',
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Resolves diagnostics / problems mention (`@diagnostics`, `@problems`, `@errors`).
+     *
+     * @private
+     */
+    async resolveDiagnosticsMention(mention, workspaceRoot, options) {
+        const files = await this.getFileList(workspaceRoot, 100);
+        const sourceFiles = files
+            .filter((f) => ['.ts', '.js', '.tsx', '.jsx'].includes(path.extname(f).toLowerCase()))
+            .slice(0, 20);
+        const issues = [];
+        for (const relPath of sourceFiles) {
+            const fullPath = path.resolve(workspaceRoot, relPath);
+            try {
+                const content = await fs.promises.readFile(fullPath, 'utf-8');
+                const validation = localValidate(fullPath, content);
+                if (!validation.isValid && validation.error) {
+                    issues.push(`${relPath}: ${validation.error}`);
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        const summary = issues.length > 0
+            ? issues.join('\n')
+            : '[No immediate syntax or structural validation errors detected across checked files]';
+        const statusLabel = issues.length > 0
+            ? `${issues.length} issue(s) detected`
+            : `syntax scan clean (${sourceFiles.length} files checked)`;
+        const helperLabel = `[diag] ${issues.length > 0 ? `${issues.length} errors found` : 'clean syntax scan'}`;
+        const formattedContent = `<diagnostics_context>
+<content_data><![CDATA[
+${sanitizeForCDATA(summary)}
+]]\\u200B></content_data>
+</diagnostics_context>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                filesChecked: sourceFiles.length,
+                issuesCount: issues.length,
+                issues,
+                category: 'diagnostics',
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Resolves terminal / console mention (`@terminal`, `@console`).
+     *
+     * @private
+     */
+    async resolveTerminalMention(mention, workspaceRoot, options) {
+        const summary = `Active Working Directory: ${workspaceRoot}\nNode Version: ${process.version}\nPlatform: ${process.platform} (${process.arch})`;
+        const statusLabel = `shell environment (${process.platform}-${process.arch}, Node ${process.version})`;
+        const helperLabel = `[term] ${process.platform} (${process.version})`;
+        const formattedContent = `<terminal_context>
+<content_data><![CDATA[
+${sanitizeForCDATA(summary)}
+]]\\u200B></content_data>
+</terminal_context>`;
+        return {
+            mention,
+            resolved: true,
+            content: formattedContent,
+            tokenEstimate: estimateTokens(formattedContent),
+            statusLabel,
+            helperLabel,
+            metadata: {
+                platform: process.platform,
+                arch: process.arch,
+                nodeVersion: process.version,
+                cwd: workspaceRoot,
+                category: 'terminal',
+                statusLabel,
+                helperLabel,
+            },
+        };
+    }
+    /**
+     * Formats resolved mention blocks into a unified XML context injection string,
+     * respecting character budget limits.
+     *
+     * @param resolvedMentions - Array of resolved mention blocks.
+     * @param maxChars - Optional maximum character budget.
+     * @returns Unified XML context block.
+     */
+    formatMentionsContext(resolvedMentions, maxChars = CONTEXT_BUDGET_CONFIG.DEFAULT_CONTEXT_MAX_CHARS) {
+        return formatContextMentions(resolvedMentions, maxChars);
+    }
+    /**
+     * Helper to get an icon glyph corresponding to a file extension.
+     *
+     * @private
+     */
+    getFileIcon(ext) {
+        switch (ext.toLowerCase()) {
+            case '.ts':
+            case '.tsx':
+            case '.mts':
+                return '🔷';
+            case '.js':
+            case '.jsx':
+            case '.mjs':
+                return '🟨';
+            case '.py':
+            case '.pyi':
+                return '🐍';
+            case '.go':
+                return '🐹';
+            case '.rs':
+                return '🦀';
+            case '.json':
+            case '.yaml':
+            case '.yml':
+            case '.toml':
+                return '⚙️';
+            case '.md':
+                return '📝';
+            default:
+                return '📄';
+        }
+    }
+    /**
+     * Helper to get an icon glyph corresponding to a symbol kind.
+     *
+     * @private
+     */
+    getSymbolIcon(kind) {
+        switch (kind) {
+            case 'function':
+                return '⚡';
+            case 'class':
+                return '🏛️';
+            case 'method':
+                return '🔹';
+            case 'interface':
+                return '📋';
+            case 'type':
+                return '🏷️';
+            case 'enum':
+                return '🔢';
+            case 'struct':
+                return '📦';
+            case 'trait':
+                return '🧬';
+            default:
+                return '✨';
+        }
+    }
+    /**
+     * Clears in-memory caches for file listings and symbols.
+     */
+    clearCaches() {
+        this.fileListCache.clear();
+        this.symbolIndexCache.clear();
+    }
+}
+/**
+ * Singleton instance of the MentionEngine.
+ */
+export const mentionEngine = new MentionEngine();