@minhpnq1807/contextos 0.5.42 → 0.5.45

package/plugins/ctx/lib/analyzer.js

@@ -15,10 +15,6 @@ const IMPORTANT_WORDS = [
   "luon", "khong bao gio", "bat buoc", "quan trong"
 ];
 
-const IGNORE_DIRS = new Set([
-  ".git", ".next", ".turbo", "coverage", "dist", "build", "node_modules", "vendor"
-]);
-
 const SEMANTIC_ALIASES = {
   duyet: ["moderation", "moderate", "review", "approve", "approval", "approved", "reject", "rejected"],
   kiem: ["check", "verify", "validation", "validate"],
@@ -49,8 +45,6 @@ const SEMANTIC_ALIASES = {
   recheck: ["check", "verify", "review"]
 };
 
-const MODERATION_TOKENS = new Set(["moderation", "moderate", "content-moderation", "approval", "approved", "reject", "rejected", "needs_review"]);
-
 const SYSTEM_USER_RULE_PATTERNS = [
   /\ball\s+shell\s+commands?\s+must\s+run\s+as\b/i,
   /\bcommands?\s+must\s+run\s+as\b/i,
@@ -287,50 +281,31 @@ export async function findRelevantFiles({
   fileEmbeddingTimeoutMs,
   fileEmbeddingOptions = {}
 } = {}) {
-  const rawTaskTokens = new Set(tokenize(task));
-  if (!rawTaskTokens.size) return [];
-
-  const candidates = [];
-  walkFiles(cwd, (filePath) => {
-    const rel = path.relative(cwd, filePath);
-    const fileTokens = new Set(tokenize(rel));
-    const match = scoreFileTokens({ rawTaskTokens, fileTokens });
-    if (match.score > 0) {
-      candidates.push({
-        path: rel,
-        score: match.score,
-        reasons: match.reasons
-      });
-    }
-  });
+  if (!String(task || "").trim()) return [];
 
-  const heuristicFiles = candidates
-    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
-    .slice(0, Math.max(limit * 2, 6));
-  const hasHighConfidenceHeuristics =
-    heuristicFiles.length >= limit &&
-    Number(heuristicFiles[0]?.score || 0) >= 8;
-  const embeddingFiles = hasHighConfidenceHeuristics
-    ? []
-    : await embeddingFileFinder({
-      cwd,
-      task,
-      dataDir,
-      timeoutMs: fileEmbeddingTimeoutMs,
-      embeddingOptions: fileEmbeddingOptions,
-      limit: Math.max(limit * 2, 6)
-    });
+  const retrievalTask = expandFileRetrievalTask(task);
+  const explicitFiles = findExplicitPromptFiles({ cwd, task, limit: Math.max(limit * 2, 6) });
+  const manifestFiles = findProjectManifestFiles({ cwd, task, limit: Math.max(limit * 2, 6) });
+  const embeddingFiles = await embeddingFileFinder({
+    cwd,
+    task: retrievalTask,
+    dataDir,
+    timeoutMs: fileEmbeddingTimeoutMs,
+    embeddingOptions: fileEmbeddingOptions,
+    limit: Math.max(limit * 2, 6)
+  });
   const importGraphFiles = expandImportGraph({
     cwd,
-    seedFiles: mergeLocalFileCandidates([...heuristicFiles, ...embeddingFiles]).slice(0, limit),
+    seedFiles: [...explicitFiles, ...manifestFiles, ...embeddingFiles].slice(0, limit),
+    dataDir,
     limit: Math.max(limit * 2, 6)
   });
-  const seedFiles = mergeLocalFileCandidates([...heuristicFiles, ...embeddingFiles, ...importGraphFiles])
+  const seedFiles = mergeLocalFileCandidates([...explicitFiles, ...manifestFiles, ...embeddingFiles, ...importGraphFiles])
     .slice(0, Math.max(limit * 3, 9));
 
   const graphFiles = findGraphRelevantFiles({
     cwd,
-    task,
+    task: retrievalTask,
     rules,
     seedFiles,
     limit: Math.max(limit * 2, 6)
@@ -339,70 +314,197 @@ export async function findRelevantFiles({
   return mergeRelevantFiles({ graphFiles, heuristicFiles: seedFiles, limit });
 }
 
-function mergeLocalFileCandidates(files) {
-  const byPath = new Map();
-  for (const file of files) {
-    const existing = byPath.get(file.path);
-    byPath.set(file.path, {
-      ...existing,
-      ...file,
-      score: Number(existing?.score || 0) + Number(file.score || 0),
-      reasons: [...new Set([...(existing?.reasons || []), ...(file.reasons || [])])],
-      source: existing?.source === "import-graph" || file.source === "import-graph" ? "import-graph" : file.source
-    });
-  }
-  return [...byPath.values()].sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+export function findProjectManifestFiles({ cwd = process.cwd(), task = "", limit = 6 } = {}) {
+  const tokens = new Set(tokenize(task));
+  if (!isManifestRelevantTask(tokens)) return [];
+  const manifests = workspacePackageManifests(cwd, tokens);
+  return manifests.slice(0, limit).map((filePath, index) => ({
+    path: filePath,
+    score: manifestScore(filePath, tokens, index),
+    source: "manifest",
+    reasons: ["project-manifest"]
+  }));
 }
 
-function scoreFileTokens({ rawTaskTokens, fileTokens }) {
-  let score = 0;
-  const reasons = new Set();
-  const hasModerationIntent = rawTaskTokens.has("kiem-duyet") || rawTaskTokens.has("kiemduyet") || rawTaskTokens.has("duyet");
-  const hasUploadIntent = rawTaskTokens.has("upload") || rawTaskTokens.has("tai-len") || rawTaskTokens.has("tailen");
+function manifestScore(manifest, taskTokens, index) {
+  if (manifest === "package.json") return 50;
+  const parts = manifest.split(/[\\/]+/).filter(Boolean);
+  const workspaceName = parts.at(-2);
+  return (taskTokens.has(workspaceName) ? 35 : 20) - index * 0.01;
+}
 
-  for (const token of rawTaskTokens) {
-    if (fileTokens.has(token)) {
-      score += 3;
-      reasons.add(token);
-    }
-    for (const alias of SEMANTIC_ALIASES[token] || []) {
-      if (fileTokens.has(alias)) {
-        score += 2;
-        reasons.add(`${token}->${alias}`);
-      }
-    }
-  }
+function isManifestRelevantTask(tokens) {
+  const runIntent = ["run", "start", "connect", "qr", "install", "build", "script", "scripts"].some((token) => tokens.has(token));
+  const projectIntent = ["webapp", "frontend", "expo", "native", "app", "package", "workspace"].some((token) => tokens.has(token));
+  return runIntent && projectIntent;
+}
 
-  if (hasModerationIntent && [...fileTokens].some((token) => MODERATION_TOKENS.has(token))) {
-    score += 6;
-    reasons.add("domain:moderation");
+function workspacePackageManifests(cwd, taskTokens = new Set()) {
+  const rootManifest = path.join(cwd, "package.json");
+  const manifests = [];
+  if (fs.existsSync(rootManifest)) manifests.push("package.json");
+  const rootPackage = readJson(rootManifest);
+  for (const pattern of workspacePatterns(rootPackage?.workspaces)) {
+    for (const manifest of expandWorkspacePattern({ cwd, pattern })) {
+      manifests.push(path.relative(cwd, manifest));
+    }
   }
+  return [...new Set(manifests)].sort((a, b) => manifestPriority(b, taskTokens) - manifestPriority(a, taskTokens) || a.localeCompare(b));
+}
 
-  if (hasUploadIntent && (fileTokens.has("upload") || fileTokens.has("uploaded") || fileTokens.has("resource"))) {
-    score += 2;
-    reasons.add("domain:upload");
-  }
+function manifestPriority(manifest, taskTokens) {
+  if (manifest === "package.json") return 100;
+  const parts = manifest.split(/[\\/]+/).filter(Boolean);
+  const workspaceName = parts.at(-2);
+  return taskTokens.has(workspaceName) ? 80 : 0;
+}
 
-  return { score, reasons: [...reasons] };
+function workspacePatterns(workspaces) {
+  if (Array.isArray(workspaces)) return workspaces.filter((item) => typeof item === "string");
+  if (Array.isArray(workspaces?.packages)) return workspaces.packages.filter((item) => typeof item === "string");
+  return [];
 }
 
-function walkFiles(directory, onFile, depth = 0) {
-  if (depth > 6) return;
+function expandWorkspacePattern({ cwd, pattern }) {
+  const normalized = String(pattern || "").replace(/\\/g, "/").replace(/\/+$/g, "");
+  if (!normalized || normalized.startsWith("..") || path.isAbsolute(normalized)) return [];
+  if (!normalized.includes("*")) {
+    const manifest = path.join(cwd, normalized, "package.json");
+    return fs.existsSync(manifest) ? [manifest] : [];
+  }
+  const parts = normalized.split("/");
+  const starIndex = parts.indexOf("*");
+  if (starIndex < 0 || parts.includes("**")) return [];
+  const baseDir = path.join(cwd, ...parts.slice(0, starIndex));
+  const suffix = parts.slice(starIndex + 1);
   let entries = [];
   try {
-    entries = fs.readdirSync(directory, { withFileTypes: true });
+    entries = fs.readdirSync(baseDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => path.join(baseDir, entry.name, ...suffix, "package.json"))
+    .filter((manifest) => fs.existsSync(manifest));
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
   } catch {
-    return;
+    return null;
+  }
+}
+
+function expandFileRetrievalTask(task) {
+  const tokens = new Set(tokenize(task));
+  const additions = new Set();
+  if (hasAny(tokens, ["purchase", "purchased", "buy", "buyer", "seller", "payment", "pay", "checkout"])) {
+    addAll(additions, [
+      "purchase", "payment", "checkout", "billing", "wallet", "balance", "top up",
+      "transaction", "order", "invoice"
+    ]);
   }
-  for (const entry of entries) {
-    if (entry.name.startsWith(".") && entry.name !== ".github") {
-      if (entry.name !== ".codex") continue;
+  if (hasAny(tokens, ["wallet", "balance", "topup", "top", "funded"])) {
+    addAll(additions, ["wallet", "balance", "top up", "billing"]);
+  }
+  if (hasAny(tokens, ["library", "access", "permissions", "permission", "resources", "tutorials", "collections"])) {
+    addAll(additions, [
+      "content access", "content-access-service", "access permissions", "library",
+      "resource", "resources", "tutorial", "tutorials", "collections"
+    ]);
+  }
+  if (hasAny(tokens, ["notification", "notifications", "notify", "buyer", "seller"])) {
+    addAll(additions, ["notification", "notifications", "notify", "buyer", "seller"]);
+  }
+  if (!additions.size) return task;
+  return `${task}\n\nContextOS retrieval hints: ${[...additions].join(", ")}`;
+}
+
+function hasAny(tokens, values) {
+  return values.some((value) => tokens.has(value));
+}
+
+function addAll(target, values) {
+  for (const value of values) target.add(value);
+}
+
+export function findExplicitPromptFiles({ cwd = process.cwd(), task = "", limit = 6 } = {}) {
+  const candidates = new Set();
+  const normalizedTask = String(task || "").replace(/\/\s+/g, "/");
+  const matches = normalizedTask.match(/[A-Za-z0-9_.()[\]@~:-]+(?:\/[A-Za-z0-9_.()[\]@~:-]+)+/g) || [];
+  for (const match of matches) {
+    const cleaned = match.replace(/[),.;:]+$/g, "");
+    for (const filePath of resolvePromptPathCandidates({ cwd, promptPath: cleaned })) {
+      candidates.add(filePath);
+      if (candidates.size >= limit) break;
     }
-    const fullPath = path.join(directory, entry.name);
-    if (entry.isDirectory()) {
-      if (!IGNORE_DIRS.has(entry.name)) walkFiles(fullPath, onFile, depth + 1);
-    } else if (entry.isFile()) {
-      onFile(fullPath);
+    if (candidates.size >= limit) break;
+  }
+  return [...candidates].map((filePath, index) => ({
+    path: filePath,
+    score: 12 - index * 0.01,
+    source: "prompt-path",
+    reasons: ["prompt-path"]
+  }));
+}
+
+function resolvePromptPathCandidates({ cwd, promptPath }) {
+  if (!promptPath || promptPath.includes("://")) return [];
+  const relative = promptPath.replace(/^\.?\//, "");
+  if (relative.startsWith("..")) return [];
+  const absolute = path.resolve(cwd, relative);
+  if (!isInsidePath(absolute, cwd)) return [];
+  const resolved = [];
+  if (isSourceFile(absolute)) resolved.push(path.relative(cwd, absolute));
+  if (isDirectory(absolute)) {
+    for (const fileName of ["page.tsx", "page.ts", "page.jsx", "page.js", "layout.tsx", "index.tsx", "index.ts"]) {
+      const candidate = path.join(absolute, fileName);
+      if (isSourceFile(candidate)) resolved.push(path.relative(cwd, candidate));
+    }
+  }
+  if (!path.extname(relative)) {
+    for (const extension of [".tsx", ".ts", ".jsx", ".js", ".md", ".json"]) {
+      const candidate = `${absolute}${extension}`;
+      if (isSourceFile(candidate)) resolved.push(path.relative(cwd, candidate));
     }
   }
+  return resolved;
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(path.resolve(parentPath), path.resolve(filePath));
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isSourceFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function mergeLocalFileCandidates(files) {
+  const byPath = new Map();
+  for (const file of files) {
+    const existing = byPath.get(file.path);
+    byPath.set(file.path, {
+      ...existing,
+      ...file,
+      score: Number(existing?.score || 0) + Number(file.score || 0),
+      reasons: [...new Set([...(existing?.reasons || []), ...(file.reasons || [])])],
+      source: existing?.source === "import-graph" || file.source === "import-graph" ? "import-graph" : file.source
+    });
+  }
+  return [...byPath.values()].sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
 }

package/plugins/ctx/lib/auto-warm.js

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_COOLDOWN_MS = 15 * 60 * 1000;
+
+export function maybeAutoWarmWorkspace({
+  cwd = process.cwd(),
+  prompt = "",
+  dataDir,
+  reason,
+  now = Date.now(),
+  spawnProcess = spawn,
+  cooldownMs = Number(process.env.CONTEXTOS_AUTO_WARM_COOLDOWN_MS || DEFAULT_COOLDOWN_MS)
+} = {}) {
+  if (process.env.CONTEXTOS_AUTO_WARM === "0") return { status: "disabled" };
+  if (!dataDir) return { status: "skipped", reason: "missing-data-dir" };
+  if (!String(prompt || "").trim()) return { status: "skipped", reason: "missing-prompt" };
+  if (!shouldAutoWarm(reason)) return { status: "skipped", reason: "not-actionable" };
+
+  const markerPath = path.join(dataDir, "auto-warm.json");
+  const existing = readJson(markerPath);
+  if (existing?.startedAt) {
+    const ageMs = now - Date.parse(existing.startedAt);
+    if (Number.isFinite(ageMs) && ageMs >= 0 && ageMs < cooldownMs) {
+      return { status: "cooldown", markerPath, ageMs };
+    }
+  }
+
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(markerPath, `${JSON.stringify({
+      startedAt: new Date(now).toISOString(),
+      cwd,
+      reason,
+      prompt: String(prompt).slice(0, 300)
+    }, null, 2)}\n`, "utf8");
+  } catch {
+    return { status: "skipped", reason: "marker-write-failed" };
+  }
+
+  const child = spawnProcess(process.execPath, [ctxBinPath(), "autowarm", "--", prompt], {
+    cwd,
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      CONTEXTOS_AUTO_WARM_CHILD: "1"
+    }
+  });
+  child.on?.("error", () => {});
+  child.unref?.();
+  return { status: "started", pid: child.pid, markerPath };
+}
+
+function shouldAutoWarm(reason) {
+  if (reason === "no-context-candidates") return true;
+  if (reason === "enabled-sections-empty-after-formatting") return true;
+  return false;
+}
+
+function ctxBinPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "../../../bin/ctx.js");
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}

package/plugins/ctx/lib/ctx-mcp-client.js

@@ -4,50 +4,99 @@ import path from "node:path";
 
 import { defaultDataRoot } from "./workspace-data.js";
 
-const DEFAULT_TIMEOUT_MS = 1000;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 100;
+export const CTX_MCP_BRIDGE_REVISION = 2;
 
 export function ctxMcpSocketPath(dataDir = defaultDataDir()) {
   return path.join(dataDir, "ctx-mcp.sock");
 }
 
+export function invalidateCtxMcpSocket(dataDir = defaultDataDir()) {
+  const socketPath = ctxMcpSocketPath(dataDir);
+  if (!fs.existsSync(socketPath)) return false;
+  try {
+    fs.rmSync(socketPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function callCtxScoreContext(payload, {
   dataDir = defaultDataDir(),
-  timeoutMs = Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || DEFAULT_TIMEOUT_MS)
+  timeoutMs = Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
+  connectTimeoutMs = Number(process.env.CONTEXTOS_MCP_CONNECT_TIMEOUT_MS || DEFAULT_CONNECT_TIMEOUT_MS),
+  createConnection = net.createConnection
 } = {}) {
   const socketPath = ctxMcpSocketPath(dataDir);
   if (!fs.existsSync(socketPath)) {
     throw new Error(`ctx-mcp bridge socket not found: ${socketPath}`);
   }
+  const socketIdentity = statIdentity(socketPath);
 
   return new Promise((resolve, reject) => {
-    const client = net.createConnection(socketPath);
+    const client = createConnection(socketPath);
     let raw = "";
-    const timer = setTimeout(() => {
+    let responseTimer;
+    const connectTimer = setTimeout(() => {
       client.destroy();
-      reject(new Error(`ctx-mcp bridge timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
+      reject(new Error(`ctx-mcp bridge connect timed out after ${connectTimeoutMs}ms`));
+    }, connectTimeoutMs);
 
     client.on("connect", () => {
+      clearTimeout(connectTimer);
+      responseTimer = setTimeout(() => {
+        client.destroy();
+        reject(new Error(`ctx-mcp bridge timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
       client.write(`${JSON.stringify(payload)}\n`);
     });
     client.on("data", (chunk) => {
       raw += chunk.toString("utf8");
     });
     client.on("end", () => {
-      clearTimeout(timer);
+      clearTimeout(connectTimer);
+      clearTimeout(responseTimer);
       try {
-        resolve(JSON.parse(raw || "{}"));
+        const response = JSON.parse(raw || "{}");
+        if (response.bridgeRevision !== CTX_MCP_BRIDGE_REVISION) {
+          invalidateSocketIfUnchanged(socketPath, socketIdentity);
+          reject(new Error(`ctx-mcp bridge revision mismatch: expected ${CTX_MCP_BRIDGE_REVISION}, received ${response.bridgeRevision || "missing"}`));
+          return;
+        }
+        resolve(response);
       } catch (error) {
         reject(error);
       }
     });
     client.on("error", (error) => {
-      clearTimeout(timer);
+      clearTimeout(connectTimer);
+      clearTimeout(responseTimer);
       reject(error);
     });
   });
 }
 
+function invalidateSocketIfUnchanged(socketPath, expectedIdentity) {
+  if (!expectedIdentity || statIdentity(socketPath) !== expectedIdentity) return false;
+  try {
+    fs.rmSync(socketPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function statIdentity(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return `${stat.dev}:${stat.ino}`;
+  } catch {
+    return null;
+  }
+}
+
 function defaultDataDir() {
   return defaultDataRoot();
 }

package/plugins/ctx/lib/embedding-scorer.js

@@ -74,6 +74,54 @@ export async function warmRuleEmbeddings({
   return { count: texts.length, cachePath: cache.path };
 }
 
+export async function searchIndexedEmbeddings({
+  kind,
+  task = "",
+  dataDir = defaultDataRoot(),
+  timeoutMs = Number(process.env.CONTEXTOS_EMBEDDING_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
+  allowRemote = process.env.CONTEXTOS_EMBEDDING_ALLOW_REMOTE === "1",
+  enabled = process.env.CONTEXTOS_EMBEDDINGS !== "0"
+} = {}) {
+  if (!enabled || !kind || !String(task || "").trim()) return { items: [], status: "disabled" };
+  const cachePath = path.join(dataDir, "embeddings.db");
+  if (!allowRemote && !fs.existsSync(cachePath)) return { items: [], status: "cold-cache", cachePath };
+
+  try {
+    return await withTimeout(searchIndexed({ kind, task, dataDir, allowRemote }), timeoutMs);
+  } catch (error) {
+    return { items: [], status: "fallback", error: error?.message || String(error) };
+  }
+}
+
+export async function warmIndexedEmbeddings({
+  kind,
+  items = [],
+  task = "",
+  dataDir = defaultDataRoot(),
+  sources = [],
+  allowRemote = true
+} = {}) {
+  if (!kind || !items.length) return { count: 0, cachePath: path.join(dataDir, "embeddings.db") };
+  if (!allowRemote && !isModelCacheReady(dataDir)) {
+    return { count: 0, cachePath: path.join(dataDir, "embeddings.db"), status: "missing-model" };
+  }
+
+  const cache = await openEmbeddingCache(dataDir);
+  const embedder = await getExtractor({ allowRemote, dataDir });
+  if (String(task || "").trim()) await getCachedEmbedding({ cache, embedder, text: task, sources });
+
+  const indexed = [];
+  for (const item of items) {
+    const text = String(item.text || "");
+    if (!item.id || !text.trim()) continue;
+    const vector = await getCachedEmbedding({ cache, embedder, text, sources });
+    indexed.push({ id: item.id, text, vector });
+  }
+  cache.replaceIndex(kind, indexed);
+  cache.close();
+  return { count: indexed.length, cachePath: cache.path };
+}
+
 async function enhanceRuleScores(rules, task, { dataDir, sources, allowRemote }) {
   const cache = await openEmbeddingCache(dataDir);
   const embedder = await getExtractor({ allowRemote, dataDir });
@@ -113,6 +161,20 @@ async function enhanceRuleScores(rules, task, { dataDir, sources, allowRemote })
   };
 }
 
+async function searchIndexed({ kind, task, dataDir, allowRemote }) {
+  const cache = await openEmbeddingCache(dataDir);
+  const embedder = await getExtractor({ allowRemote, dataDir });
+  const taskEmbedding = await getCachedEmbedding({ cache, embedder, text: task, sources: [] });
+  const items = cache.listIndexed(kind)
+    .map((item) => ({
+      ...item,
+      embeddingScore: Number(similarityToScore(cosine(taskEmbedding, item.vector)).toFixed(3))
+    }))
+    .sort((a, b) => b.embeddingScore - a.embeddingScore || a.id.localeCompare(b.id));
+  cache.close();
+  return { items, status: "enabled", model: DEFAULT_MODEL, cachePath: cache.path };
+}
+
 async function getExtractor({ allowRemote, dataDir }) {
   const cacheDir = modelCacheDir(dataDir);
   const key = `${allowRemote ? "remote" : "local"}:${cacheDir}`;
@@ -183,6 +245,30 @@ export async function openEmbeddingCache(dataDir) {
       );
       writeDatabaseAtomically(cachePath, db);
     },
+    listIndexed(kind) {
+      const stmt = db.prepare("SELECT id, text, vector FROM embedding_index WHERE kind = ? AND model = ?");
+      const items = [];
+      try {
+        stmt.bind([kind, DEFAULT_MODEL]);
+        while (stmt.step()) {
+          const row = stmt.getAsObject();
+          items.push({ id: row.id, text: row.text, vector: JSON.parse(row.vector) });
+        }
+      } finally {
+        stmt.free();
+      }
+      return items;
+    },
+    replaceIndex(kind, items) {
+      db.run("DELETE FROM embedding_index WHERE kind = ? AND model = ?", [kind, DEFAULT_MODEL]);
+      for (const item of items) {
+        db.run(
+          "INSERT INTO embedding_index (kind, id, text, model, vector, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
+          [kind, item.id, item.text, DEFAULT_MODEL, JSON.stringify(item.vector), new Date().toISOString()]
+        );
+      }
+      writeDatabaseAtomically(cachePath, db);
+    },
     close() {
       writeDatabaseAtomically(cachePath, db);
       db.close();
@@ -218,6 +304,17 @@ function ensureEmbeddingSchema(db) {
       updated_at TEXT NOT NULL
     )
   `);
+  db.run(`
+    CREATE TABLE IF NOT EXISTS embedding_index (
+      kind TEXT NOT NULL,
+      id TEXT NOT NULL,
+      text TEXT NOT NULL,
+      model TEXT NOT NULL,
+      vector TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      PRIMARY KEY (kind, id, model)
+    )
+  `);
 }
 
 function openSqlDatabase(SQL, cachePath) {
@@ -316,11 +413,16 @@ function similarityToScore(similarity) {
   return Math.max(0, Math.min(1, (similarity + 1) / 2));
 }
 
-function withTimeout(promise, timeoutMs) {
-  return Promise.race([
-    promise,
-    new Promise((_, reject) => {
-      setTimeout(() => reject(new Error(`embedding scorer timed out after ${timeoutMs}ms`)), timeoutMs);
-    })
-  ]);
+async function withTimeout(promise, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`embedding scorer timed out after ${timeoutMs}ms`)), timeoutMs);
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
 }