@geminilight/mindos 0.5.21 → 0.5.22

package/app/components/settings/MonitoringTab.tsx

@@ -0,0 +1,202 @@
+'use client';
+
+import { useEffect, useState, useCallback } from 'react';
+import { Activity, Cpu, Database, HardDrive, Loader2, RefreshCw, Zap } from 'lucide-react';
+import { apiFetch } from '@/lib/api';
+import type { Messages } from '@/lib/i18n';
+
+interface MonitoringData {
+  system: {
+    uptimeMs: number;
+    memory: { heapUsed: number; heapTotal: number; rss: number };
+    nodeVersion: string;
+  };
+  application: {
+    agentRequests: number;
+    toolExecutions: number;
+    totalTokens: { input: number; output: number };
+    avgResponseTimeMs: number;
+    errors: number;
+  };
+  knowledgeBase: {
+    root: string;
+    fileCount: number;
+    totalSizeBytes: number;
+  };
+  mcp: {
+    running: boolean;
+    port: number;
+  };
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+function formatUptime(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  const d = Math.floor(h / 24);
+  return `${d}d ${h % 24}h`;
+}
+
+function ProgressBar({ value, max, className }: { value: number; max: number; className?: string }) {
+  const pct = max > 0 ? Math.min(100, (value / max) * 100) : 0;
+  return (
+    <div className={`h-2 w-full rounded-full bg-muted ${className ?? ''}`}>
+      <div
+        className={`h-full rounded-full transition-all duration-300 ${pct > 85 ? 'bg-destructive' : 'bg-amber-500'}`}
+        style={{ width: `${pct}%` }}
+      />
+    </div>
+  );
+}
+
+function StatCard({ label, value, sub }: { label: string; value: string | number; sub?: string }) {
+  return (
+    <div className="flex flex-col gap-0.5">
+      <span className="text-xs text-muted-foreground">{label}</span>
+      <span className="text-sm font-medium tabular-nums">{value}</span>
+      {sub && <span className="text-[10px] text-muted-foreground">{sub}</span>}
+    </div>
+  );
+}
+
+export interface MonitoringTabProps {
+  t: Messages;
+}
+
+export function MonitoringTab({ t }: MonitoringTabProps) {
+  const [data, setData] = useState<MonitoringData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+
+  const mon = t.settings.monitoring;
+
+  const fetchData = useCallback(async () => {
+    try {
+      const d = await apiFetch<MonitoringData>('/api/monitoring', { timeout: 5000 });
+      setData(d);
+      setError(false);
+    } catch {
+      setError(true);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    fetchData();
+    const id = setInterval(fetchData, 5000);
+    return () => clearInterval(id);
+  }, [fetchData]);
+
+  if (loading && !data) {
+    return (
+      <div className="flex justify-center py-8">
+        <Loader2 size={18} className="animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  if (error && !data) {
+    return (
+      <div className="text-center py-8 text-sm text-muted-foreground">
+        {mon.fetchError || 'Failed to load monitoring data'}
+      </div>
+    );
+  }
+
+  if (!data) return null;
+
+  const { system, application, knowledgeBase, mcp } = data;
+  const heapPct = system.memory.heapTotal > 0
+    ? Math.round((system.memory.heapUsed / system.memory.heapTotal) * 100)
+    : 0;
+
+  return (
+    <div className="space-y-6">
+      {/* System */}
+      <section>
+        <h3 className="flex items-center gap-1.5 text-xs font-semibold text-foreground mb-3">
+          <Cpu size={13} className="text-muted-foreground" />
+          {mon.system || 'System'}
+        </h3>
+        <div className="space-y-3">
+          <div>
+            <div className="flex justify-between text-xs mb-1">
+              <span className="text-muted-foreground">{mon.heapMemory || 'Heap Memory'}</span>
+              <span className="tabular-nums">{formatBytes(system.memory.heapUsed)} / {formatBytes(system.memory.heapTotal)} ({heapPct}%)</span>
+            </div>
+            <ProgressBar value={system.memory.heapUsed} max={system.memory.heapTotal} />
+          </div>
+          <div className="grid grid-cols-3 gap-4">
+            <StatCard label={mon.rss || 'RSS'} value={formatBytes(system.memory.rss)} />
+            <StatCard label={mon.uptime || 'Uptime'} value={formatUptime(system.uptimeMs)} />
+            <StatCard label={mon.nodeVersion || 'Node'} value={system.nodeVersion} />
+          </div>
+        </div>
+      </section>
+
+      {/* Application */}
+      <section>
+        <h3 className="flex items-center gap-1.5 text-xs font-semibold text-foreground mb-3">
+          <Zap size={13} className="text-muted-foreground" />
+          {mon.application || 'Application'}
+        </h3>
+        <div className="grid grid-cols-3 gap-4">
+          <StatCard label={mon.requests || 'Requests'} value={application.agentRequests} />
+          <StatCard label={mon.toolCalls || 'Tool Calls'} value={application.toolExecutions} />
+          <StatCard label={mon.avgResponse || 'Avg Response'} value={application.avgResponseTimeMs > 0 ? `${application.avgResponseTimeMs}ms` : '—'} />
+          <StatCard
+            label={mon.tokens || 'Tokens'}
+            value={`${(application.totalTokens.input + application.totalTokens.output).toLocaleString()}`}
+            sub={`↑${application.totalTokens.input.toLocaleString()} ↓${application.totalTokens.output.toLocaleString()}`}
+          />
+          <StatCard label={mon.errors || 'Errors'} value={application.errors} />
+        </div>
+      </section>
+
+      {/* Knowledge Base */}
+      <section>
+        <h3 className="flex items-center gap-1.5 text-xs font-semibold text-foreground mb-3">
+          <Database size={13} className="text-muted-foreground" />
+          {mon.knowledgeBase || 'Knowledge Base'}
+        </h3>
+        <div className="grid grid-cols-3 gap-4">
+          <StatCard label={mon.files || 'Files'} value={knowledgeBase.fileCount} />
+          <StatCard label={mon.totalSize || 'Total Size'} value={formatBytes(knowledgeBase.totalSizeBytes)} />
+          <StatCard label={mon.rootPath || 'Root'} value={knowledgeBase.root.split('/').pop() ?? knowledgeBase.root} sub={knowledgeBase.root} />
+        </div>
+      </section>
+
+      {/* MCP */}
+      <section>
+        <h3 className="flex items-center gap-1.5 text-xs font-semibold text-foreground mb-3">
+          <HardDrive size={13} className="text-muted-foreground" />
+          MCP
+        </h3>
+        <div className="grid grid-cols-3 gap-4">
+          <StatCard
+            label={mon.mcpStatus || 'Status'}
+            value={mcp.running ? (mon.mcpRunning || 'Running') : (mon.mcpStopped || 'Stopped')}
+          />
+          <StatCard label={mon.mcpPort || 'Port'} value={mcp.port} />
+        </div>
+      </section>
+
+      {/* Refresh indicator */}
+      <div className="flex items-center gap-1.5 text-[10px] text-muted-foreground">
+        <RefreshCw size={10} className={loading ? 'animate-spin' : ''} />
+        {mon.autoRefresh || 'Auto-refresh every 5s'}
+      </div>
+    </div>
+  );
+}

package/app/components/settings/types.ts

@@ -33,7 +33,7 @@ export interface SettingsData {
   envValues?: Record<string, string>;
 }
 
-export type Tab = 'ai' | 'appearance' | 'knowledge' | 'mcp' | 'plugins' | 'sync';
+export type Tab = 'ai' | 'appearance' | 'knowledge' | 'mcp' | 'plugins' | 'sync' | 'monitoring' | 'agents';
 
 export const CONTENT_WIDTHS = [
   { value: '680px', label: 'Narrow (680px)' },

package/app/instrumentation.ts

@@ -7,9 +7,14 @@ export async function register() {
       const configPath = join(homedir(), '.mindos', 'config.json');
       const config = JSON.parse(readFileSync(configPath, 'utf-8'));
       if (config.sync?.enabled && config.mindRoot) {
-        // Resolve absolute path to avoid Turbopack bundling issues
+        // Turbopack statically analyzes ALL forms of require/import — including
+        // createRequire() calls. The only way to load a runtime-computed path
+        // is to hide the require call inside a Function constructor, which is
+        // opaque to bundler static analysis.
         const syncModule = resolve(process.cwd(), '..', 'bin', 'lib', 'sync.js');
-        const { startSyncDaemon } = await import(/* webpackIgnore: true */ syncModule);
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        const dynamicRequire = new Function('id', 'return require(id)') as (id: string) => any;
+        const { startSyncDaemon } = dynamicRequire(syncModule);
         await startSyncDaemon(config.mindRoot);
       }
     } catch {

package/app/lib/agent/index.ts

@@ -6,3 +6,4 @@ export {
   truncateToolOutputs, compactMessages, hardPrune, createTransformContext,
 } from './context';
 export { toAgentMessages } from './to-agent-messages';
+export { loadSkillRules } from './skill-rules';

package/app/lib/agent/log.ts

@@ -11,6 +11,7 @@ interface AgentOpEntry {
   params: Record<string, unknown>;
   result: 'ok' | 'error';
   message?: string;
+  durationMs?: number;
 }
 
 /**

package/app/lib/agent/skill-rules.ts

@@ -0,0 +1,70 @@
+/**
+ * Load skill-rules.md and user-rules.md from the user's knowledge base.
+ *
+ * Files are located at: {mindRoot}/.agents/skills/{skillName}/skill-rules.md
+ * These are part of the progressive skill loading system (v4).
+ *
+ * Designed to be called from route.ts during system prompt assembly.
+ * All errors are caught — missing files are normal (not all users have skill rules).
+ */
+import fs from 'fs';
+import path from 'path';
+import { truncate } from './tools';
+
+export interface SkillRuleFile {
+  ok: boolean;
+  content: string;
+  truncated: boolean;
+  empty: boolean;
+  error?: string;
+}
+
+export interface SkillRulesResult {
+  skillRules: SkillRuleFile;
+  userRules: SkillRuleFile;
+}
+
+const MAX_SKILL_CHARS = 20_000;
+
+function readSkillFile(absPath: string): SkillRuleFile {
+  try {
+    const raw = fs.readFileSync(absPath, 'utf-8');
+    const isEmpty = raw.trim().length === 0;
+    if (raw.length > MAX_SKILL_CHARS) {
+      return {
+        ok: true,
+        content: truncate(raw),
+        truncated: true,
+        empty: false,
+      };
+    }
+    return {
+      ok: true,
+      content: raw,
+      truncated: false,
+      empty: isEmpty,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      content: '',
+      truncated: false,
+      empty: true,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Load skill-rules.md and user-rules.md from {mindRoot}/.agents/skills/{skillName}/
+ *
+ * @param mindRoot - Absolute path to the knowledge base root
+ * @param skillName - 'mindos' or 'mindos-zh'
+ */
+export function loadSkillRules(mindRoot: string, skillName: string): SkillRulesResult {
+  const skillDir = path.join(mindRoot, '.agents', 'skills', skillName);
+  return {
+    skillRules: readSkillFile(path.join(skillDir, 'skill-rules.md')),
+    userRules: readSkillFile(path.join(skillDir, 'user-rules.md')),
+  };
+}

package/app/lib/api.ts

@@ -8,10 +8,12 @@
 
 export class ApiError extends Error {
   status: number;
-  constructor(message: string, status: number) {
+  code?: string;
+  constructor(message: string, status: number, code?: string) {
     super(message);
     this.name = 'ApiError';
     this.status = status;
+    this.code = code;
   }
 }
 
@@ -41,11 +43,18 @@ export async function apiFetch<T>(url: string, opts: ApiFetchOptions = {}): Prom
 
     if (!res.ok) {
       let msg = `Request failed (${res.status})`;
+      let code: string | undefined;
       try {
         const body = await res.json();
-        if (body?.error) msg = body.error;
+        // Support structured { ok: false, error: { code, message } } envelope
+        if (body?.error?.code && body?.error?.message) {
+          msg = body.error.message;
+          code = body.error.code;
+        } else if (body?.error) {
+          msg = typeof body.error === 'string' ? body.error : body.error.message ?? msg;
+        }
       } catch { /* non-JSON error body */ }
-      throw new ApiError(msg, res.status);
+      throw new ApiError(msg, res.status, code);
     }
 
     return (await res.json()) as T;

package/app/lib/core/csv.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolveSafe } from './security';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Appends a single row to a CSV file with RFC 4180 escaping.
@@ -9,7 +10,7 @@ import { resolveSafe } from './security';
  */
 export function appendCsvRow(mindRoot: string, filePath: string, row: string[]): { newRowCount: number } {
   const resolved = resolveSafe(mindRoot, filePath);
-  if (!filePath.endsWith('.csv')) throw new Error('Only .csv files support row append');
+  if (!filePath.endsWith('.csv')) throw new MindOSError(ErrorCodes.INVALID_FILE_TYPE, 'Only .csv files support row append', { filePath });
 
   const escaped = row.map((cell) => {
     if (cell.includes(',') || cell.includes('"') || cell.includes('\n')) {

package/app/lib/core/fs-ops.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolveSafe, assertWithinRoot } from './security';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Reads the content of a file given a relative path from mindRoot.
@@ -35,7 +36,7 @@ export function writeFile(mindRoot: string, filePath: string, content: string):
 export function createFile(mindRoot: string, filePath: string, initialContent = ''): void {
   const resolved = resolveSafe(mindRoot, filePath);
   if (fs.existsSync(resolved)) {
-    throw new Error(`File already exists: ${filePath}`);
+    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `File already exists: ${filePath}`, { filePath });
   }
   fs.mkdirSync(path.dirname(resolved), { recursive: true });
   fs.writeFileSync(resolved, initialContent, 'utf-8');
@@ -47,7 +48,7 @@ export function createFile(mindRoot: string, filePath: string, initialContent =
 export function deleteFile(mindRoot: string, filePath: string): void {
   const resolved = resolveSafe(mindRoot, filePath);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`File not found: ${filePath}`);
+    throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `File not found: ${filePath}`, { filePath });
   }
   fs.unlinkSync(resolved);
 }
@@ -59,7 +60,7 @@ export function deleteFile(mindRoot: string, filePath: string): void {
  */
 export function renameFile(mindRoot: string, oldPath: string, newName: string): string {
   if (newName.includes('/') || newName.includes('\\')) {
-    throw new Error('Invalid filename: must not contain path separators');
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Invalid filename: must not contain path separators', { newName });
   }
   const root = path.resolve(mindRoot);
   const oldResolved = path.resolve(path.join(root, oldPath));
@@ -70,7 +71,7 @@ export function renameFile(mindRoot: string, oldPath: string, newName: string):
   assertWithinRoot(newResolved, root);
 
   if (fs.existsSync(newResolved)) {
-    throw new Error('A file with that name already exists');
+    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, 'A file with that name already exists', { newName });
   }
   fs.renameSync(oldResolved, newResolved);
   return path.relative(root, newResolved);
@@ -88,8 +89,8 @@ export function moveFile(
 ): { newPath: string; affectedFiles: string[] } {
   const fromResolved = resolveSafe(mindRoot, fromPath);
   const toResolved = resolveSafe(mindRoot, toPath);
-  if (!fs.existsSync(fromResolved)) throw new Error(`Source not found: ${fromPath}`);
-  if (fs.existsSync(toResolved)) throw new Error(`Destination already exists: ${toPath}`);
+  if (!fs.existsSync(fromResolved)) throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `Source not found: ${fromPath}`, { fromPath });
+  if (fs.existsSync(toResolved)) throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, `Destination already exists: ${toPath}`, { toPath });
   fs.mkdirSync(path.dirname(toResolved), { recursive: true });
   fs.renameSync(fromResolved, toResolved);
   const backlinks = findBacklinksFn(mindRoot, fromPath);

package/app/lib/core/index.ts

@@ -36,7 +36,7 @@ export {
 export type { TreeOptions } from './tree';
 
 // Search
-export { searchFiles } from './search';
+export { searchFiles, invalidateSearchIndex } from './search';
 
 // Line-level operations
 export {

package/app/lib/core/lines.ts

@@ -1,4 +1,5 @@
 import { readFile, writeFile } from './fs-ops';
+import { MindOSError, ErrorCodes } from '@/lib/errors';
 
 /**
  * Reads a file and returns its content split into lines.
@@ -11,9 +12,9 @@ export function readLines(mindRoot: string, filePath: string): string[] {
  * Validates line indices are within bounds.
  */
 function validateLineRange(totalLines: number, start: number, end: number): void {
-  if (start < 0 || end < 0) throw new Error('Invalid line index: indices must be >= 0');
-  if (start > end) throw new Error(`Invalid range: start (${start}) > end (${end})`);
-  if (start >= totalLines) throw new Error(`Invalid line index: start (${start}) >= total lines (${totalLines})`);
+  if (start < 0 || end < 0) throw new MindOSError(ErrorCodes.INVALID_RANGE, 'Invalid line index: indices must be >= 0', { start, end });
+  if (start > end) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid range: start (${start}) > end (${end})`, { start, end });
+  if (start >= totalLines) throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid line index: start (${start}) >= total lines (${totalLines})`, { start, totalLines });
 }
 
 /**
@@ -23,7 +24,7 @@ function validateLineRange(totalLines: number, start: number, end: number): void
 export function insertLines(mindRoot: string, filePath: string, afterIndex: number, lines: string[]): void {
   const existing = readLines(mindRoot, filePath);
   if (afterIndex >= existing.length) {
-    throw new Error(`Invalid after_index: ${afterIndex} >= total lines (${existing.length})`);
+    throw new MindOSError(ErrorCodes.INVALID_RANGE, `Invalid after_index: ${afterIndex} >= total lines (${existing.length})`, { afterIndex, totalLines: existing.length });
   }
   const insertAt = afterIndex < 0 ? 0 : afterIndex + 1;
   existing.splice(insertAt, 0, ...lines);
@@ -58,7 +59,7 @@ export function insertAfterHeading(mindRoot: string, filePath: string, heading:
     const trimmed = l.trim();
     return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
   });
-  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+  if (idx === -1) throw new MindOSError(ErrorCodes.HEADING_NOT_FOUND, `Heading not found: "${heading}"`, { heading });
   let insertAt = idx + 1;
   while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
   insertLines(mindRoot, filePath, insertAt - 1, ['', content]);
@@ -73,7 +74,7 @@ export function updateSection(mindRoot: string, filePath: string, heading: strin
     const trimmed = l.trim();
     return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
   });
-  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+  if (idx === -1) throw new MindOSError(ErrorCodes.HEADING_NOT_FOUND, `Heading not found: "${heading}"`, { heading });
 
   const headingLevel = (lines[idx].match(/^#+/) ?? [''])[0].length;
   let sectionEnd = lines.length - 1;

package/app/lib/core/search-index.ts

@@ -0,0 +1,174 @@
+import { collectAllFiles } from './tree';
+import { readFile } from './fs-ops';
+
+const MAX_CONTENT_LENGTH = 50_000;
+
+// CJK Unicode ranges: Chinese, Japanese Hiragana/Katakana, Korean
+const CJK_REGEX = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/;
+
+/**
+ * Tokenize text for indexing: split on word boundaries + CJK bigrams.
+ *
+ * Latin/ASCII: split on non-alphanumeric characters, lowercased.
+ * CJK: generate character-level bigrams (overlapping pairs).
+ * Mixed text: both strategies applied, tokens merged.
+ */
+function tokenize(text: string): Set<string> {
+  const tokens = new Set<string>();
+  const lower = text.toLowerCase();
+
+  // Latin/ASCII word tokens.
+  // Single Latin chars (e.g. "a") are noise and excluded; CJK unigrams
+  // carry meaning and are handled separately below.
+  const words = lower.match(/[a-z0-9_$@#]+/g);
+  if (words) {
+    for (const w of words) {
+      if (w.length >= 2) tokens.add(w);
+    }
+  }
+
+  // CJK bigrams + single chars (unigrams carry meaning in CJK scripts)
+  if (CJK_REGEX.test(lower)) {
+    const cjkChars: string[] = [];
+    for (const ch of lower) {
+      if (CJK_REGEX.test(ch)) {
+        cjkChars.push(ch);
+      } else {
+        // Emit bigrams for accumulated CJK run
+        if (cjkChars.length > 0) {
+          emitCjkTokens(cjkChars, tokens);
+          cjkChars.length = 0;
+        }
+      }
+    }
+    if (cjkChars.length > 0) emitCjkTokens(cjkChars, tokens);
+  }
+
+  return tokens;
+}
+
+function emitCjkTokens(chars: string[], tokens: Set<string>): void {
+  for (let i = 0; i < chars.length; i++) {
+    tokens.add(chars[i]); // unigram
+    if (i + 1 < chars.length) {
+      tokens.add(chars[i] + chars[i + 1]); // bigram
+    }
+  }
+}
+
+/**
+ * In-memory inverted index for core search acceleration.
+ *
+ * The index maps tokens → Set<filePath>. When a search query arrives,
+ * we tokenize the query and intersect candidate sets from the index,
+ * dramatically reducing the number of files that need full-text scanning.
+ *
+ * Lifecycle:
+ * - `rebuild(mindRoot)` — full build from disk (called lazily on first search)
+ * - `invalidate()` — mark stale (next search triggers rebuild)
+ * - `getCandidates(query)` — return candidate file set, or null if no index / no tokens
+ */
+export class SearchIndex {
+  private invertedIndex: Map<string, Set<string>> | null = null;
+  private builtForRoot: string | null = null;
+  private fileCount = 0;
+
+  /** Full rebuild: read all files and build inverted index. */
+  rebuild(mindRoot: string): void {
+    const allFiles = collectAllFiles(mindRoot);
+    const inverted = new Map<string, Set<string>>();
+
+    for (const filePath of allFiles) {
+      let content: string;
+      try {
+        content = readFile(mindRoot, filePath);
+      } catch {
+        continue;
+      }
+
+      if (content.length > MAX_CONTENT_LENGTH) {
+        content = content.slice(0, MAX_CONTENT_LENGTH);
+      }
+
+      // Also index the file path itself
+      const allText = filePath + '\n' + content;
+      const tokens = tokenize(allText);
+
+      for (const token of tokens) {
+        let set = inverted.get(token);
+        if (!set) {
+          set = new Set<string>();
+          inverted.set(token, set);
+        }
+        set.add(filePath);
+      }
+    }
+
+    this.invertedIndex = inverted;
+    this.builtForRoot = mindRoot;
+    this.fileCount = allFiles.length;
+  }
+
+  /** Clear the index. Next search will trigger a lazy rebuild. */
+  invalidate(): void {
+    this.invertedIndex = null;
+    this.builtForRoot = null;
+    this.fileCount = 0;
+  }
+
+  /** Whether the index has been built for the given mindRoot. */
+  isBuiltFor(mindRoot: string): boolean {
+    return this.invertedIndex !== null && this.builtForRoot === mindRoot;
+  }
+
+  /** Whether the index has been built (for any root). */
+  isBuilt(): boolean {
+    return this.invertedIndex !== null;
+  }
+
+  /** Number of files in the index. */
+  getFileCount(): number {
+    return this.fileCount;
+  }
+
+  /**
+   * Get candidate file paths for a query (single or multi-word).
+   *
+   * Tokenizes the query and intersects candidate sets from the inverted index.
+   *
+   * Returns:
+   * - `null` if the index is not built, query is empty, or query produces no
+   *   tokens (e.g. substring shorter than 2 chars). Callers should fall back
+   *   to a full scan when null is returned.
+   * - `string[]` (possibly empty) if the index can answer definitively.
+   */
+  getCandidates(query: string): string[] | null {
+    if (!query.trim()) return null;
+    if (!this.invertedIndex) return null;
+
+    const tokens = tokenize(query.toLowerCase().trim());
+    // No tokens produced → query is a substring/single-char that the index
+    // cannot resolve. Return null so the caller falls back to full scan,
+    // preserving pre-index indexOf behavior for partial-word queries.
+    if (tokens.size === 0) return null;
+
+    let result: Set<string> | null = null;
+
+    for (const token of tokens) {
+      const set = this.invertedIndex.get(token);
+      if (!set) return []; // No files have this token → intersection is empty
+
+      if (result === null) {
+        result = new Set(set);
+      } else {
+        // Intersect
+        for (const path of result) {
+          if (!set.has(path)) result.delete(path);
+        }
+        if (result.size === 0) return [];
+      }
+    }
+
+    return result ? Array.from(result) : [];
+  }
+}