@prom.codes/context-mcp 0.1.0 → 0.2.1

package/README.md

@@ -25,4 +25,13 @@ your workspace into a local SQLite database (`~/.prometheus/<hash>.db`)
 and embeds via the Prometheus API. Your code never leaves your machine —
 only embedding text transits to the API.
 
+## Native modules
+
+Uses native Tree-sitter grammars + `better-sqlite3` for parsing and storage.
+Prebuilt binaries are fetched automatically on the mainstream platforms
+(macOS x64/arm64, Linux x64, Windows x64) — no compiler needed. On other
+platforms (e.g. Linux/Windows arm64) or a Node ABI without a prebuild, install
+C/C++ build tools so the native modules can compile (Windows: VS Build Tools).
+Requires Node ≥ 20.10.
+
 Docs: https://prom.codes/docs

package/dist/bin.js

@@ -3354,6 +3354,116 @@ async function runEmbedPass(storage, embedder, options, driftRecovered) {
 import chokidar from "chokidar";
 import { resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
+
+// ../shared/dist/types.js
+var GRAMMAR_LANGUAGE_IDS = [
+  "typescript",
+  "tsx",
+  "javascript",
+  "python",
+  "php",
+  "go",
+  "rust",
+  "java",
+  "csharp",
+  "c",
+  "cpp",
+  "ruby",
+  "kotlin",
+  "html"
+];
+var DOCUMENT_LANGUAGE_IDS = [
+  "markdown",
+  "text",
+  "json",
+  "yaml",
+  "toml"
+];
+var LANGUAGE_IDS = [
+  ...GRAMMAR_LANGUAGE_IDS,
+  ...DOCUMENT_LANGUAGE_IDS
+];
+var EDGE_TYPES = [
+  "defines",
+  "calls",
+  "imports",
+  "same-file",
+  "co-change"
+];
+
+// ../shared/dist/sensitive-paths.js
+var SENSITIVE_DIRECTORIES = /* @__PURE__ */ new Set([
+  "secrets",
+  "credentials",
+  ".aws",
+  ".ssh",
+  ".gnupg"
+]);
+var SENSITIVE_BASENAMES = /* @__PURE__ */ new Set([
+  ".npmrc",
+  ".pypirc",
+  ".netrc",
+  ".pgpass",
+  "known_hosts",
+  // Project-specific: CLAUDE.md carries live credentials by convention.
+  "claude.md"
+]);
+var SENSITIVE_EXTENSIONS = [
+  ".pem",
+  ".key",
+  ".p12",
+  ".pfx",
+  ".jks",
+  ".keystore",
+  ".ppk"
+];
+var ENV_TEMPLATE_BASENAMES = /* @__PURE__ */ new Set([
+  ".env.example",
+  ".env.sample",
+  ".env.template"
+]);
+function isSensitivePath(path) {
+  const normalised = path.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  if (normalised === "")
+    return false;
+  const segments = normalised.split("/").filter((s) => s !== "" && s !== ".").map((s) => s.toLowerCase());
+  if (segments.length === 0)
+    return false;
+  for (const segment of segments) {
+    if (SENSITIVE_DIRECTORIES.has(segment))
+      return true;
+  }
+  const base = segments[segments.length - 1];
+  if (SENSITIVE_BASENAMES.has(base))
+    return true;
+  if (base === ".env")
+    return true;
+  if (base.startsWith(".env.") && !ENV_TEMPLATE_BASENAMES.has(base))
+    return true;
+  for (const ext of SENSITIVE_EXTENSIONS) {
+    if (base.endsWith(ext))
+      return true;
+  }
+  if (base.startsWith("id_rsa") || base.startsWith("id_ed25519"))
+    return true;
+  if (/\.tfstate(\.|$)/.test(base))
+    return true;
+  if (base.endsWith(".json")) {
+    if (base.startsWith("serviceaccount"))
+      return true;
+    if (base.startsWith("gcp-"))
+      return true;
+    if (base.endsWith("-credentials.json"))
+      return true;
+  }
+  return false;
+}
+var SENSITIVE_PATH_ERROR = "path matches the sensitive-file deny-list";
+
+// ../shared/dist/index.js
+var PROMETHEUS_VERSION = "0.1.0";
+
+// ../indexer/dist/watcher.js
 var DEFAULT_IGNORED = [
   /(^|[/\\])\.git([/\\]|$)/,
   /(^|[/\\])node_modules([/\\]|$)/,
@@ -3389,8 +3499,12 @@ var WorkspaceWatcher = class extends EventEmitter {
   async start() {
     if (this.#watcher !== null)
       return;
+    const denySensitive = (abs) => {
+      const rel = toRelative(this.#root, abs);
+      return rel !== abs && isSensitivePath(rel);
+    };
     const watcher = chokidar.watch(this.#root, {
-      ignored: this.#ignored,
+      ignored: [...this.#ignored, denySensitive],
       ignoreInitial: false,
       persistent: true,
       awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 }
@@ -3415,6 +3529,8 @@ var WorkspaceWatcher = class extends EventEmitter {
     this.#watcher = null;
   }
   #schedule(kind, abs) {
+    if (isSensitivePath(toRelative(this.#root, abs)))
+      return;
     const key = `${kind}::${abs}`;
     const existing = this.#pending.get(key);
     if (existing !== void 0)
@@ -3728,6 +3844,8 @@ var WorkspaceIndexer = class {
     }
   }
   #isIgnored(relPath) {
+    if (isSensitivePath(relPath))
+      return true;
     const patterns = this.#ignored ?? DEFAULT_IGNORED_PATTERNS;
     for (const pat of patterns) {
       if (pat instanceof RegExp) {
@@ -3807,7 +3925,10 @@ var WorkspaceIndexer = class {
           hasParseErrors: parsed.hasParseErrors
         },
         symbols: parsed.symbols,
-        references: parsed.references
+        references: parsed.references,
+        // Full source so the SQLite adapter can store per-symbol body
+        // text for the full-text lexical channel (sliced by byte offset).
+        source
       });
       return "indexed";
     } catch (err) {
@@ -3836,47 +3957,8 @@ import { basename as basename5, dirname as dirname2, join as join3, resolve as r
 // ../storage-sqlite/dist/adapter.js
 import Database from "better-sqlite3";
 
-// ../shared/dist/types.js
-var GRAMMAR_LANGUAGE_IDS = [
-  "typescript",
-  "tsx",
-  "javascript",
-  "python",
-  "php",
-  "go",
-  "rust",
-  "java",
-  "csharp",
-  "c",
-  "cpp",
-  "ruby",
-  "kotlin",
-  "html"
-];
-var DOCUMENT_LANGUAGE_IDS = [
-  "markdown",
-  "text",
-  "json",
-  "yaml",
-  "toml"
-];
-var LANGUAGE_IDS = [
-  ...GRAMMAR_LANGUAGE_IDS,
-  ...DOCUMENT_LANGUAGE_IDS
-];
-var EDGE_TYPES = [
-  "defines",
-  "calls",
-  "imports",
-  "same-file",
-  "co-change"
-];
-
-// ../shared/dist/index.js
-var PROMETHEUS_VERSION = "0.1.0";
-
 // ../storage-sqlite/dist/schema.js
-var SCHEMA_VERSION = 3;
+var SCHEMA_VERSION = 4;
 var SCHEMA_STATEMENTS = [
   `PRAGMA journal_mode = WAL`,
   `PRAGMA foreign_keys = ON`,
@@ -3907,7 +3989,8 @@ var SCHEMA_STATEMENTS = [
      end_row     INTEGER NOT NULL,
      end_col     INTEGER NOT NULL,
      start_byte  INTEGER NOT NULL,
-     end_byte    INTEGER NOT NULL
+     end_byte    INTEGER NOT NULL,
+     body        TEXT
    )`,
   `CREATE TABLE IF NOT EXISTS refs (
      id                INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -3937,25 +4020,27 @@ var SCHEMA_STATEMENTS = [
   `CREATE INDEX IF NOT EXISTS idx_refs_name_nocase   ON refs(name COLLATE NOCASE)`,
   // FTS5 virtual table: external-content design — actual rows live in
   // `symbols`, FTS holds only the tokenised index. Triggers below keep
-  // the FTS index in sync so we never write to it directly.
+  // the FTS index in sync so we never write to it directly. The `body`
+  // column (version 4) carries each symbol's source slice, so the lexical
+  // channel matches symbol *source text*, not just name + container.
   `CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
-     name, container,
+     name, container, body,
      content='symbols', content_rowid='id',
      tokenize='unicode61 remove_diacritics 2'
    )`,
   `CREATE TRIGGER IF NOT EXISTS symbols_ai AFTER INSERT ON symbols BEGIN
-     INSERT INTO symbols_fts(rowid, name, container)
-     VALUES (new.id, new.name, COALESCE(new.container, ''));
+     INSERT INTO symbols_fts(rowid, name, container, body)
+     VALUES (new.id, new.name, COALESCE(new.container, ''), COALESCE(new.body, ''));
    END`,
   `CREATE TRIGGER IF NOT EXISTS symbols_ad AFTER DELETE ON symbols BEGIN
-     INSERT INTO symbols_fts(symbols_fts, rowid, name, container)
-     VALUES('delete', old.id, old.name, COALESCE(old.container, ''));
+     INSERT INTO symbols_fts(symbols_fts, rowid, name, container, body)
+     VALUES('delete', old.id, old.name, COALESCE(old.container, ''), COALESCE(old.body, ''));
    END`,
   `CREATE TRIGGER IF NOT EXISTS symbols_au AFTER UPDATE ON symbols BEGIN
-     INSERT INTO symbols_fts(symbols_fts, rowid, name, container)
-     VALUES('delete', old.id, old.name, COALESCE(old.container, ''));
-     INSERT INTO symbols_fts(rowid, name, container)
-     VALUES (new.id, new.name, COALESCE(new.container, ''));
+     INSERT INTO symbols_fts(symbols_fts, rowid, name, container, body)
+     VALUES('delete', old.id, old.name, COALESCE(old.container, ''), COALESCE(old.body, ''));
+     INSERT INTO symbols_fts(rowid, name, container, body)
+     VALUES (new.id, new.name, COALESCE(new.container, ''), COALESCE(new.body, ''));
    END`,
   // Phase 2.15.8 — co-change pairs (file-level historical coupling).
   // Pairs are canonical (`file_a < file_b`) so each unordered pair has
@@ -3981,6 +4066,7 @@ var SCHEMA_STATEMENTS = [
 ];
 
 // ../storage-sqlite/dist/adapter.js
+var MAX_BODY_BYTES = 8e3;
 function vectorToBlob(v) {
   return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
 }
@@ -4054,6 +4140,14 @@ var SqliteStorageAdapter = class {
   #options;
   #db = null;
   #stmts = null;
+  /**
+   * Lazily-prepared, weight-keyed FTS statements for the adaptive
+   * column-weighting path (see {@link searchByText}). The default
+   * (equal-weight) statement lives in {@link PreparedStatements.searchFts};
+   * non-default weight triples get one cached statement each here. Cleared
+   * on `close` together with the handle.
+   */
+  #weightedFts = /* @__PURE__ */ new Map();
   constructor(options) {
     this.#options = options;
   }
@@ -4070,6 +4164,16 @@ var SqliteStorageAdapter = class {
     }
     const hasMeta = db.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='meta'`).get();
     const priorVersion = hasMeta ? Number(db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get()?.value ?? 0) : 0;
+    if (priorVersion > 0 && priorVersion < 4) {
+      const cols = db.prepare(`PRAGMA table_info(symbols)`).all();
+      if (!cols.some((c) => c.name === "body")) {
+        db.exec(`ALTER TABLE symbols ADD COLUMN body TEXT`);
+      }
+      db.exec(`DROP TRIGGER IF EXISTS symbols_ai;
+         DROP TRIGGER IF EXISTS symbols_ad;
+         DROP TRIGGER IF EXISTS symbols_au;
+         DROP TABLE   IF EXISTS symbols_fts;`);
+    }
     for (const ddl of SCHEMA_STATEMENTS)
       db.exec(ddl);
     if (priorVersion < SCHEMA_VERSION) {
@@ -4087,6 +4191,7 @@ var SqliteStorageAdapter = class {
     this.#db.close();
     this.#db = null;
     this.#stmts = null;
+    this.#weightedFts.clear();
   }
   async getFileHash(path) {
     const row = this.#requireStmts().getFileHash.get(path);
@@ -4104,11 +4209,12 @@ var SqliteStorageAdapter = class {
   async upsertFile(payload) {
     const db = this.#requireDb();
     const stmts = this.#requireStmts();
+    const sourceBuf = payload.source === void 0 ? null : Buffer.from(payload.source, "utf8");
     const tx = db.transaction((p) => {
       stmts.deleteFile.run(p.file.path);
       stmts.insertFile.run(p.file.path, p.file.language, p.file.contentHash, p.file.size, p.file.mtimeMs, p.file.indexedAt, p.file.hasParseErrors ? 1 : 0);
       for (const s of p.symbols)
-        this.#insertSymbol(p.file.path, s, stmts);
+        this.#insertSymbol(p.file.path, s, sourceBuf, stmts);
       for (const r of p.references)
         this.#insertRef(p.file.path, r, stmts);
     });
@@ -4238,18 +4344,53 @@ var SqliteStorageAdapter = class {
       vector: byKey.get(`${r.filePath}\0${r.chunkIndex}`) ?? null
     }));
   }
-  async searchByText(query, limit) {
+  async searchByText(query, limit, options) {
     if (limit <= 0)
       return [];
     const sanitised = sanitiseFtsQuery(query);
     if (sanitised === "")
       return [];
-    const rows = this.#requireStmts().searchFts.all(sanitised, limit);
+    const stmt = this.#ftsStmt(options?.columnWeights);
+    const rows = stmt.all(sanitised, limit);
     return rows.map((row) => ({
       symbol: rowToStoredSymbol(row),
       score: row.bm25_score
     }));
   }
+  /**
+   * Pick the FTS statement for a given `[name, container, body]` BM25
+   * column-weight triple. No weights (or an all-1 triple) returns the
+   * cached default statement — byte-identical, equal-weight ranking. A
+   * non-default triple gets a lazily-prepared, cached statement whose
+   * `bm25()` carries the weights as literal arguments. The weights are
+   * internal, validated finite numbers (never user input), so inlining
+   * them in the SQL is injection-safe; FTS5 requires them as function
+   * arguments, not bindable parameters.
+   */
+  #ftsStmt(weights) {
+    if (weights === void 0)
+      return this.#requireStmts().searchFts;
+    for (const w of weights) {
+      if (!Number.isFinite(w) || w < 0) {
+        throw new Error(`searchByText: columnWeights must be finite and >= 0, got [${weights.join(", ")}]`);
+      }
+    }
+    const [n, c, b] = weights;
+    if (n === 1 && c === 1 && b === 1)
+      return this.#requireStmts().searchFts;
+    const key = `${n},${c},${b}`;
+    const cached = this.#weightedFts.get(key);
+    if (cached !== void 0)
+      return cached;
+    const stmt = this.#requireDb().prepare(`SELECT s.*, bm25(symbols_fts, ${n}, ${c}, ${b}) AS bm25_score
+       FROM symbols_fts
+       JOIN symbols s ON s.id = symbols_fts.rowid
+       WHERE symbols_fts MATCH ?
+       ORDER BY bm25_score
+       LIMIT ?`);
+    this.#weightedFts.set(key, stmt);
+    return stmt;
+  }
   async expandSymbolGraph(symbolName, limit, options) {
     if (limit <= 0)
       return [];
@@ -4353,8 +4494,9 @@ var SqliteStorageAdapter = class {
       commitCount: r.commit_count
     }));
   }
-  #insertSymbol(filePath, s, stmts) {
-    stmts.insertSymbol.run(filePath, s.name, s.kind, s.language, s.container, s.exported ? 1 : 0, s.range.start.row, s.range.start.column, s.range.end.row, s.range.end.column, s.range.startByte, s.range.endByte);
+  #insertSymbol(filePath, s, sourceBuf, stmts) {
+    const body = sourceBuf === null ? null : sourceBuf.subarray(s.range.startByte, Math.min(s.range.endByte, s.range.startByte + MAX_BODY_BYTES)).toString("utf8");
+    stmts.insertSymbol.run(filePath, s.name, s.kind, s.language, s.container, s.exported ? 1 : 0, s.range.start.row, s.range.start.column, s.range.end.row, s.range.end.column, s.range.startByte, s.range.endByte, body);
   }
   #insertRef(filePath, r, stmts) {
     stmts.insertRef.run(filePath, r.name, r.kind, r.fromContainer, r.moduleSpecifier, r.range.start.row, r.range.start.column, r.range.end.row, r.range.end.column, r.range.startByte, r.range.endByte);
@@ -4378,8 +4520,9 @@ var SqliteStorageAdapter = class {
       insertFile: db.prepare(`INSERT INTO files(path, language, content_hash, size, mtime_ms, indexed_at, has_parse_errors)
          VALUES(?, ?, ?, ?, ?, ?, ?)`),
       insertSymbol: db.prepare(`INSERT INTO symbols(file_path, name, kind, language, container, exported,
-                              start_row, start_col, end_row, end_col, start_byte, end_byte)
-         VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+                              start_row, start_col, end_row, end_col, start_byte, end_byte,
+                              body)
+         VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
       insertRef: db.prepare(`INSERT INTO refs(file_path, name, kind, from_container, module_specifier,
                            start_row, start_col, end_row, end_col, start_byte, end_byte)
          VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
@@ -4403,6 +4546,14 @@ var SqliteStorageAdapter = class {
          WHERE s.file_path = ?
          ORDER BY s.id
          LIMIT 1 OFFSET ?`),
+      // BM25 over (name, container, body). Default (equal) column weights:
+      // SWE-bench django showed name-dominant weights (10/5/1) regress
+      // localization vs equal weights — common name tokens ("field",
+      // "model") then crowd out the specific body match that pinpoints the
+      // right file. The body column (Schema v4) lets lexical search match a
+      // symbol's source text, which lifts file localization (bm25-only
+      // any@5 25→50 on django). Column weighting is left as a future tuning
+      // knob if a name-vs-body balance proves worthwhile per-corpus.
       searchFts: db.prepare(`SELECT s.*, bm25(symbols_fts) AS bm25_score
          FROM symbols_fts
          JOIN symbols s ON s.id = symbols_fts.rowid
@@ -5109,7 +5260,7 @@ var SupabaseStorageAdapter = class {
       }));
     });
   }
-  async searchByText(query, limit) {
+  async searchByText(query, limit, _options) {
     if (limit <= 0)
       return [];
     const tokens = query.toLowerCase().split(/[^a-z0-9_]+/u).filter((t) => t.length >= 2);
@@ -5945,7 +6096,8 @@ var HybridRetriever = class {
     const activeEdgeTypes = EDGE_TYPES.filter((t) => effectiveEdgeWeights[t] > 0);
     const staticEdgeTypes = activeEdgeTypes.filter((t) => t !== CO_CHANGE);
     const coChangeActive = effectiveEdgeWeights[CO_CHANGE] > 0;
-    const lexicalPromise = wLex > 0 ? this.#storage.searchByText(trimmed, candidateLimit) : Promise.resolve([]);
+    const lexCols = options.lexicalColumnWeights;
+    const lexicalPromise = wLex > 0 ? this.#storage.searchByText(trimmed, candidateLimit, lexCols !== void 0 ? { columnWeights: lexCols } : void 0) : Promise.resolve([]);
     const vectorPromise = wVec > 0 ? this.#runVector(trimmed, candidateLimit, options.signal) : Promise.resolve({ hits: [], queryVector: null });
     const [lexicalHits, vectorResult] = await Promise.all([
       lexicalPromise,
@@ -5959,7 +6111,23 @@ var HybridRetriever = class {
     if (wLex > 0)
       firstPassLists.push({ ...lexicalAsList(lexicalHits), weight: wLex });
     const firstPass = reciprocalRankFusion(firstPassLists, { k: rrfK });
-    const seedSymbols = wGraph > 0 && expandN > 0 && firstPass.length > 0 ? firstPass.slice(0, expandN).map((r) => r.payload) : [];
+    let seedSymbols = [];
+    if (wGraph > 0 && expandN > 0) {
+      const seedCols = options.graphSeedColumnWeights;
+      if (seedCols !== void 0 && wLex > 0) {
+        const seedLexHits = await this.#storage.searchByText(trimmed, candidateLimit, {
+          columnWeights: seedCols
+        });
+        const seedLists = [];
+        if (wVec > 0)
+          seedLists.push({ ...vectorAsList(vectorHits), weight: wVec });
+        seedLists.push({ ...lexicalAsList(seedLexHits), weight: wLex });
+        const seedPass = reciprocalRankFusion(seedLists, { k: rrfK });
+        seedSymbols = seedPass.slice(0, expandN).map((r) => r.payload);
+      } else if (firstPass.length > 0) {
+        seedSymbols = firstPass.slice(0, expandN).map((r) => r.payload);
+      }
+    }
     const graphPromise = seedSymbols.length > 0 && staticEdgeTypes.length > 0 ? this.#runGraphExpansion(seedSymbols, candidateLimit, staticEdgeTypes, maxDepth, adaptiveThreshold) : Promise.resolve(/* @__PURE__ */ new Map());
     const coChangePromise = coChangeActive && seedSymbols.length > 0 && ccFilesPerSeed > 0 && ccPerFileCap > 0 ? this.#runCoChangeStage(seedSymbols, ccFilesPerSeed, ccPerFileCap, ccMinWeight) : Promise.resolve([]);
     const [graphBuckets, coChangeSymbols] = await Promise.all([
@@ -6992,6 +7160,377 @@ var HashEmbeddingProvider = class {
   }
 };
 
+// ../rerank-voyage/dist/index.js
+var DEFAULT_MODEL2 = "rerank-2.5";
+var DEFAULT_BASE_URL = "https://api.voyageai.com/v1";
+var DEFAULT_BATCH5 = 100;
+var DEFAULT_RETRIES5 = 6;
+var DEFAULT_BACKOFF5 = 2e3;
+var DEFAULT_RETRY_MAX2 = 6e4;
+function parseRetryAfterMs2(value, now = Date.now()) {
+  if (value === null)
+    return null;
+  const trimmed = value.trim();
+  if (trimmed === "")
+    return null;
+  if (/^[0-9]+(\.[0-9]+)?$/.test(trimmed)) {
+    const secs = Number(trimmed);
+    if (!Number.isFinite(secs) || secs < 0)
+      return null;
+    return Math.round(secs * 1e3);
+  }
+  if (!/[A-Za-z]/.test(trimmed))
+    return null;
+  const ts = Date.parse(trimmed);
+  if (!Number.isFinite(ts))
+    return null;
+  const delta = ts - now;
+  return delta > 0 ? delta : 0;
+}
+function sleep5(ms, signal) {
+  return new Promise((resolve6, reject) => {
+    if (signal?.aborted === true) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve6();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function nonRetryable5(message) {
+  const err = new Error(message);
+  err.nonRetryable = true;
+  return err;
+}
+var VoyageRerankProvider = class {
+  name;
+  model;
+  region;
+  #baseUrl;
+  #apiKey;
+  #batchSize;
+  #maxRetries;
+  #retryBaseMs;
+  #retryMaxMs;
+  #fetch;
+  constructor(opts) {
+    if (typeof opts.apiKey !== "string" || opts.apiKey === "") {
+      throw new Error("VoyageRerankProvider: apiKey is required");
+    }
+    if (opts.batchSize !== void 0 && (!Number.isInteger(opts.batchSize) || opts.batchSize <= 0 || opts.batchSize > 1e3)) {
+      throw new Error(`VoyageRerankProvider: batchSize must be an integer in 1..1000, got ${opts.batchSize}`);
+    }
+    this.model = opts.model ?? DEFAULT_MODEL2;
+    this.name = opts.name ?? `voyage:${this.model}`;
+    this.region = opts.region ?? "us";
+    this.#baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#apiKey = opts.apiKey;
+    this.#batchSize = opts.batchSize ?? DEFAULT_BATCH5;
+    this.#maxRetries = opts.maxRetries ?? DEFAULT_RETRIES5;
+    this.#retryBaseMs = opts.retryBaseMs ?? DEFAULT_BACKOFF5;
+    this.#retryMaxMs = opts.retryMaxMs ?? DEFAULT_RETRY_MAX2;
+    this.#fetch = opts.fetch ?? fetch;
+  }
+  async rerank(query, candidates, opts) {
+    if (candidates.length === 0)
+      return [];
+    const all = new Array(candidates.length);
+    let cursor = 0;
+    for (let start = 0; start < candidates.length; start += this.#batchSize) {
+      const slice = candidates.slice(start, start + this.#batchSize);
+      const scored = await this.#rerankBatch(query, slice, opts?.signal);
+      for (const hit of scored) {
+        const globalIndex = start + hit.localIndex;
+        const cand = candidates[globalIndex];
+        all[cursor++] = { id: cand.id, index: globalIndex, score: hit.score };
+      }
+    }
+    all.sort((a, b) => b.score - a.score);
+    if (opts?.topK !== void 0 && opts.topK >= 0 && opts.topK < all.length) {
+      return all.slice(0, opts.topK);
+    }
+    return all;
+  }
+  async #rerankBatch(query, batch, signal) {
+    const body = {
+      query,
+      documents: batch.map((c) => c.text),
+      model: this.model,
+      return_documents: false,
+      truncation: true
+    };
+    const init = {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.#apiKey}`
+      },
+      body: JSON.stringify(body)
+    };
+    if (signal !== void 0)
+      init.signal = signal;
+    let attempt = 0;
+    let lastError = null;
+    while (attempt <= this.#maxRetries) {
+      try {
+        const res = await this.#fetch(`${this.#baseUrl}/rerank`, init);
+        if (res.status === 429 || res.status >= 500 && res.status < 600) {
+          lastError = new Error(`${this.name}: HTTP ${res.status}`);
+          attempt += 1;
+          if (attempt > this.#maxRetries)
+            break;
+          const backoff = this.#computeBackoff(attempt, res.headers.get("retry-after"));
+          await sleep5(backoff, signal);
+          continue;
+        }
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw nonRetryable5(`${this.name}: HTTP ${res.status} ${res.statusText}${text === "" ? "" : ` \u2014 ${text}`}`);
+        }
+        const payload = await res.json();
+        return this.#decode(payload, batch.length);
+      } catch (err) {
+        if (err?.name === "AbortError")
+          throw err;
+        if (err?.nonRetryable === true)
+          throw err;
+        if (attempt >= this.#maxRetries)
+          throw err;
+        lastError = err;
+        attempt += 1;
+        await sleep5(this.#computeBackoff(attempt, null), signal);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(`${this.name}: exhausted ${this.#maxRetries} retries`);
+  }
+  #computeBackoff(attempt, retryAfterHeader) {
+    const exp = this.#retryBaseMs * 2 ** Math.max(0, attempt - 1);
+    const advised = parseRetryAfterMs2(retryAfterHeader);
+    const lower = advised === null ? exp : Math.max(exp, advised);
+    return Math.min(lower, this.#retryMaxMs);
+  }
+  #decode(payload, expected) {
+    if (!Array.isArray(payload.data) || payload.data.length !== expected) {
+      throw nonRetryable5(`${this.name}: expected ${expected} rerank rows, got ${payload.data?.length ?? 0}`);
+    }
+    return payload.data.map((row) => {
+      if (!Number.isInteger(row.index) || row.index < 0 || row.index >= expected) {
+        throw nonRetryable5(`${this.name}: invalid index ${row.index} in rerank response`);
+      }
+      if (typeof row.relevance_score !== "number" || !Number.isFinite(row.relevance_score)) {
+        throw nonRetryable5(`${this.name}: invalid relevance_score ${row.relevance_score} at index ${row.index}`);
+      }
+      return { localIndex: row.index, score: row.relevance_score };
+    });
+  }
+};
+
+// ../rerank-openai-compat/dist/index.js
+var DEFAULT_MODEL3 = "bge-reranker-base";
+var DEFAULT_BATCH6 = 100;
+var DEFAULT_RETRIES6 = 6;
+var DEFAULT_BACKOFF6 = 2e3;
+var DEFAULT_RETRY_MAX3 = 6e4;
+var DEFAULT_TIMEOUT = 18e4;
+function parseRetryAfterMs3(value, now = Date.now()) {
+  if (value === null)
+    return null;
+  const trimmed = value.trim();
+  if (trimmed === "")
+    return null;
+  if (/^[0-9]+(\.[0-9]+)?$/.test(trimmed)) {
+    const secs = Number(trimmed);
+    if (!Number.isFinite(secs) || secs < 0)
+      return null;
+    return Math.round(secs * 1e3);
+  }
+  if (!/[A-Za-z]/.test(trimmed))
+    return null;
+  const ts = Date.parse(trimmed);
+  if (!Number.isFinite(ts))
+    return null;
+  const delta = ts - now;
+  return delta > 0 ? delta : 0;
+}
+function sleep6(ms, signal) {
+  return new Promise((resolve6, reject) => {
+    if (signal?.aborted === true) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve6();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function nonRetryable6(message) {
+  const err = new Error(message);
+  err.nonRetryable = true;
+  return err;
+}
+var OpenAICompatRerankProvider = class {
+  name;
+  model;
+  region;
+  #baseUrl;
+  #apiKey;
+  #batchSize;
+  #maxRetries;
+  #retryBaseMs;
+  #retryMaxMs;
+  #timeoutMs;
+  #fetch;
+  constructor(opts) {
+    if (typeof opts.baseUrl !== "string" || opts.baseUrl === "") {
+      throw new Error("OpenAICompatRerankProvider: baseUrl is required");
+    }
+    if (opts.batchSize !== void 0 && (!Number.isInteger(opts.batchSize) || opts.batchSize <= 0 || opts.batchSize > 1e3)) {
+      throw new Error(`OpenAICompatRerankProvider: batchSize must be an integer in 1..1000, got ${opts.batchSize}`);
+    }
+    if (opts.timeoutMs !== void 0 && (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs < 0)) {
+      throw new Error(`OpenAICompatRerankProvider: timeoutMs must be a non-negative integer (0 disables), got ${opts.timeoutMs}`);
+    }
+    this.model = opts.model ?? DEFAULT_MODEL3;
+    this.name = opts.name ?? `openai-compat:${this.model}`;
+    this.region = opts.region ?? "self-hosted";
+    this.#baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.#apiKey = opts.apiKey === void 0 || opts.apiKey === "" ? void 0 : opts.apiKey;
+    this.#batchSize = opts.batchSize ?? DEFAULT_BATCH6;
+    this.#maxRetries = opts.maxRetries ?? DEFAULT_RETRIES6;
+    this.#retryBaseMs = opts.retryBaseMs ?? DEFAULT_BACKOFF6;
+    this.#retryMaxMs = opts.retryMaxMs ?? DEFAULT_RETRY_MAX3;
+    this.#timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    this.#fetch = opts.fetch ?? fetch;
+  }
+  async rerank(query, candidates, opts) {
+    if (candidates.length === 0)
+      return [];
+    const all = new Array(candidates.length);
+    let cursor = 0;
+    for (let start = 0; start < candidates.length; start += this.#batchSize) {
+      const slice = candidates.slice(start, start + this.#batchSize);
+      const scored = await this.#rerankBatch(query, slice, opts?.signal);
+      for (const hit of scored) {
+        const globalIndex = start + hit.localIndex;
+        const cand = candidates[globalIndex];
+        all[cursor++] = { id: cand.id, index: globalIndex, score: hit.score };
+      }
+    }
+    all.sort((a, b) => b.score - a.score);
+    if (opts?.topK !== void 0 && opts.topK >= 0 && opts.topK < all.length) {
+      return all.slice(0, opts.topK);
+    }
+    return all;
+  }
+  async #rerankBatch(query, batch, signal) {
+    const body = {
+      query,
+      documents: batch.map((c) => c.text),
+      model: this.model,
+      return_documents: false
+    };
+    const headers = { "content-type": "application/json" };
+    if (this.#apiKey !== void 0)
+      headers.authorization = `Bearer ${this.#apiKey}`;
+    const payloadJson = JSON.stringify(body);
+    let attempt = 0;
+    let lastError = null;
+    while (attempt <= this.#maxRetries) {
+      const controller = new AbortController();
+      let timedOut = false;
+      let timer;
+      if (this.#timeoutMs > 0) {
+        timer = setTimeout(() => {
+          timedOut = true;
+          controller.abort();
+        }, this.#timeoutMs);
+      }
+      const onParentAbort = () => controller.abort();
+      if (signal !== void 0) {
+        if (signal.aborted)
+          controller.abort();
+        else
+          signal.addEventListener("abort", onParentAbort, { once: true });
+      }
+      const init = {
+        method: "POST",
+        headers,
+        body: payloadJson,
+        signal: controller.signal
+      };
+      try {
+        const res = await this.#fetch(`${this.#baseUrl}/rerank`, init);
+        if (res.status === 429 || res.status >= 500 && res.status < 600) {
+          lastError = new Error(`${this.name}: HTTP ${res.status}`);
+          attempt += 1;
+          if (attempt > this.#maxRetries)
+            break;
+          const backoff = this.#computeBackoff(attempt, res.headers.get("retry-after"));
+          await sleep6(backoff, signal);
+          continue;
+        }
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw nonRetryable6(`${this.name}: HTTP ${res.status} ${res.statusText}${text === "" ? "" : ` \u2014 ${text}`}`);
+        }
+        const payload = await res.json();
+        return this.#decode(payload, batch.length);
+      } catch (err) {
+        const isAbort = err?.name === "AbortError";
+        if (isAbort && !timedOut)
+          throw err;
+        if (!isAbort && err?.nonRetryable === true)
+          throw err;
+        const normalized = timedOut ? new Error(`${this.name}: request timed out after ${this.#timeoutMs}ms`) : err;
+        if (attempt >= this.#maxRetries)
+          throw normalized;
+        lastError = normalized;
+        attempt += 1;
+        await sleep6(this.#computeBackoff(attempt, null), signal);
+      } finally {
+        if (timer !== void 0)
+          clearTimeout(timer);
+        if (signal !== void 0)
+          signal.removeEventListener("abort", onParentAbort);
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error(`${this.name}: exhausted ${this.#maxRetries} retries`);
+  }
+  #computeBackoff(attempt, retryAfterHeader) {
+    const exp = this.#retryBaseMs * 2 ** Math.max(0, attempt - 1);
+    const advised = parseRetryAfterMs3(retryAfterHeader);
+    const lower = advised === null ? exp : Math.max(exp, advised);
+    return Math.min(lower, this.#retryMaxMs);
+  }
+  #decode(payload, expected) {
+    if (!Array.isArray(payload.results) || payload.results.length !== expected) {
+      throw nonRetryable6(`${this.name}: expected ${expected} rerank rows, got ${payload.results?.length ?? 0}`);
+    }
+    return payload.results.map((row) => {
+      if (!Number.isInteger(row.index) || row.index < 0 || row.index >= expected) {
+        throw nonRetryable6(`${this.name}: invalid index ${row.index} in rerank response`);
+      }
+      if (typeof row.relevance_score !== "number" || !Number.isFinite(row.relevance_score)) {
+        throw nonRetryable6(`${this.name}: invalid relevance_score ${row.relevance_score} at index ${row.index}`);
+      }
+      return { localIndex: row.index, score: row.relevance_score };
+    });
+  }
+};
+
 // dist/composition.js
 var RegionModeViolation = class extends Error {
   mode;
@@ -7227,6 +7766,56 @@ function discoverEmbeddingProvider(env, fetchImpl) {
   validateRegionMode(regionMode, picked.id, picked.provider.region);
   return { ...picked, regionMode };
 }
+function discoverRerankProvider(env, fetchImpl) {
+  const regionMode = parseRegionMode(env.PROMETHEUS_REGION_MODE);
+  const forced = env.PROMETHEUS_RERANK_PROVIDER?.toLowerCase() ?? "none";
+  if (forced === "" || forced === "none")
+    return { id: "none", provider: null };
+  if (forced === "voyage") {
+    const apiKey = env.VOYAGE_API_KEY;
+    if (apiKey === void 0 || apiKey === "") {
+      throw new NoProviderError(`rerank provider "voyage" requested but VOYAGE_API_KEY is missing`);
+    }
+    const model = env.VOYAGE_RERANK_MODEL ?? "rerank-2.5";
+    const region = "us";
+    if (regionMode !== "default") {
+      throw new RegionModeViolation(regionMode, "voyage", region, regionMode === "eu-strict" ? ["nomic", "bge-m3", "mistral", "hash"] : ["nomic", "bge-m3", "hash"]);
+    }
+    const provider = new VoyageRerankProvider({
+      name: "voyage-rerank",
+      apiKey,
+      model,
+      region,
+      baseUrl: env.VOYAGE_BASE_URL ?? "https://api.voyageai.com/v1",
+      maxRetries: intEnv(env, "VOYAGE_RERANK_MAX_RETRIES", 6),
+      retryBaseMs: intEnv(env, "VOYAGE_RERANK_RETRY_BASE_MS", 2e3),
+      batchSize: intEnv(env, "VOYAGE_RERANK_BATCH", 100),
+      ...fetchOpt(fetchImpl)
+    });
+    return { id: "voyage", provider };
+  }
+  if (forced === "bge" || forced === "generic") {
+    const baseUrl = env.PROMETHEUS_RERANK_ENDPOINT;
+    if (baseUrl === void 0 || baseUrl === "") {
+      throw new NoProviderError(`rerank provider "${forced}" requested but PROMETHEUS_RERANK_ENDPOINT is missing`);
+    }
+    const model = env.PROMETHEUS_RERANK_MODEL ?? "bge-reranker-base";
+    const provider = new OpenAICompatRerankProvider({
+      name: env.PROMETHEUS_RERANK_NAME ?? `bge-rerank:${model}`,
+      model,
+      region: "self-hosted",
+      baseUrl,
+      maxRetries: intEnv(env, "PROMETHEUS_RERANK_MAX_RETRIES", 6),
+      retryBaseMs: intEnv(env, "PROMETHEUS_RERANK_RETRY_BASE_MS", 2e3),
+      batchSize: intEnv(env, "PROMETHEUS_RERANK_BATCH", 100),
+      timeoutMs: intEnv(env, "PROMETHEUS_RERANK_TIMEOUT_MS", 18e4),
+      ...apiKeyOpt(env.PROMETHEUS_RERANK_API_KEY),
+      ...fetchOpt(fetchImpl)
+    });
+    return { id: "bge", provider };
+  }
+  throw new NoProviderError(`unknown PROMETHEUS_RERANK_PROVIDER="${forced}" (expected "none", "voyage", or "bge")`);
+}
 function getStableDbPath(workspaceRoot) {
   const abs = resolve4(workspaceRoot);
   const hash = createHash3("sha256").update(abs).digest("hex").slice(0, 16);
@@ -7310,6 +7899,8 @@ async function composeFromEnv(opts) {
   const { id: storageBackend, adapter: storage, dbPath } = discoverStorageBackend(env, regionMode, storageOptions);
   await storage.init();
   const retriever = new HybridRetriever({ storage, embedder });
+  const { id: rerankId, provider: reranker } = discoverRerankProvider(env, opts.fetch);
+  const rerankTopN = intEnv(env, "PROMETHEUS_RERANK_TOP_N", 100);
   const managed = apiKeyPresent && storageBackend === "sqlite";
   let closed = false;
   return {
@@ -7324,6 +7915,9 @@ async function composeFromEnv(opts) {
     storageBackend,
     managed,
     dbPath,
+    reranker,
+    rerankId,
+    rerankTopN,
     async close() {
       if (closed)
         return;
@@ -7476,6 +8070,8 @@ var FRAMEWORK_MANIFESTS = [
 var MAX_K = 50;
 var DEFAULT_K2 = 10;
 var MAX_FILE_BYTES = 256 * 1024;
+var MAX_SNIPPET_BYTES = 1500;
+var RERANK_DOC_BYTES = 4096;
 function symbolToJson(s) {
   return {
     name: s.name,
@@ -7502,6 +8098,64 @@ function textResult(payload) {
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
   };
 }
+async function snippetForSymbol(workspaceRoot, symbol, cache, capBytes = MAX_SNIPPET_BYTES) {
+  try {
+    const relPath = symbol.filePath;
+    if (isSensitivePath(relPath))
+      return null;
+    let buf = cache.get(relPath);
+    if (buf === void 0) {
+      const abs = resolveInWorkspace(workspaceRoot, relPath);
+      buf = await readFile3(abs).catch(() => null);
+      cache.set(relPath, buf);
+    }
+    if (buf === null)
+      return null;
+    const startByte = Math.max(0, symbol.range.startByte);
+    const endByte = Math.min(symbol.range.endByte, buf.byteLength);
+    if (!(endByte > startByte))
+      return null;
+    const full = buf.subarray(startByte, endByte);
+    const truncated = full.byteLength > capBytes;
+    const view = truncated ? full.subarray(0, capBytes) : full;
+    return { text: view.toString("utf8"), truncated };
+  } catch {
+    return null;
+  }
+}
+async function rerankHead(reranker, query, head, workspaceRoot, cache) {
+  const candidates = [];
+  for (let i = 0; i < head.length; i++) {
+    const snip = await snippetForSymbol(workspaceRoot, head[i].symbol, cache, RERANK_DOC_BYTES);
+    if (snip === null)
+      continue;
+    candidates.push({ id: String(i), text: snip.text });
+  }
+  if (candidates.length === 0)
+    return null;
+  let hits;
+  try {
+    hits = await reranker.rerank(query, candidates, { topK: candidates.length });
+  } catch {
+    return null;
+  }
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const hit of hits) {
+    const i = Number(hit.id);
+    if (!Number.isFinite(i) || seen.has(i))
+      continue;
+    seen.add(i);
+    const r = head[i];
+    if (r !== void 0)
+      out.push(r);
+  }
+  for (let i = 0; i < head.length; i++) {
+    if (!seen.has(i))
+      out.push(head[i]);
+  }
+  return out;
+}
 function resolveInWorkspace(workspaceRoot, input) {
   if (input === "")
     throw new Error("path must not be empty.");
@@ -7541,7 +8195,8 @@ function clampK(k) {
 }
 var searchInput = {
   query: z.string().min(1, "query must not be empty"),
-  k: z.number().int().positive().max(MAX_K).optional()
+  k: z.number().int().positive().max(MAX_K).optional(),
+  includeSnippet: z.boolean().optional()
 };
 var lookupInput = {
   name: z.string().min(1, "name must not be empty"),
@@ -7573,23 +8228,41 @@ var changedSinceInput = {
 };
 var emptyInput = {};
 function registerTools(server, deps) {
-  const { storage, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend } = deps;
+  const { storage, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend, reranker, rerankTopN } = deps;
   server.registerTool("search_code", {
     title: "Hybrid code search",
-    description: "Hybrid retrieval over the indexed workspace (lexical FTS + vector + symbol graph) fused with RRF. Returns the top-k symbols with provenance per source.",
+    description: "PRIMARY code search for this workspace \u2014 call this FIRST to find where something is defined, used or implemented, before reading files or guessing paths. Hybrid retrieval (lexical FTS + vector + symbol graph, RRF-fused) over natural-language or symbol queries. Returns the top-k symbols with provenance AND an inline source snippet per hit, so the result is usually actionable without a follow-up get_file. Set `includeSnippet: false` to omit the inline code (symbols only).",
     inputSchema: searchInput
   }, async (args) => {
     const k = clampK(args.k);
-    const results = await retriever.search(args.query, { k });
-    return textResult({
-      query: args.query,
-      k,
-      results: results.map((r) => ({
+    const includeSnippet = args.includeSnippet ?? true;
+    const cache = /* @__PURE__ */ new Map();
+    const poolK = reranker ? Math.max(k, rerankTopN ?? 100) : k;
+    const pool = await retriever.search(args.query, { k: poolK });
+    let ordered = pool;
+    let reranked = false;
+    if (reranker && pool.length > 0) {
+      const head = pool.slice(0, rerankTopN ?? 100);
+      const tail = pool.slice(rerankTopN);
+      const reorderedHead = await rerankHead(reranker, args.query, head, workspaceRoot, cache);
+      if (reorderedHead !== null) {
+        ordered = reorderedHead.concat(tail);
+        reranked = true;
+      }
+    }
+    const results = ordered.slice(0, k);
+    const mapped = await Promise.all(results.map(async (r) => {
+      const base = {
         score: r.score,
         provenance: r.provenance,
         symbol: symbolToJson(r.symbol)
-      }))
-    });
+      };
+      if (!includeSnippet)
+        return base;
+      const snip = await snippetForSymbol(workspaceRoot, r.symbol, cache);
+      return snip === null ? base : { ...base, snippet: snip.text, snippetTruncated: snip.truncated };
+    }));
+    return textResult({ query: args.query, k, reranked, results: mapped });
   });
   server.registerTool("get_symbol", {
     title: "Exact symbol lookup",
@@ -7656,6 +8329,9 @@ function registerTools(server, deps) {
     inputSchema: getFileInput
   }, async (args) => {
     const abs = resolveInWorkspace(workspaceRoot, args.path);
+    if (isSensitivePath(relative(workspaceRoot, abs))) {
+      throw new Error(`${SENSITIVE_PATH_ERROR}: "${args.path}".`);
+    }
     const buf = await readFile3(abs);
     const start = args.startByte ?? 0;
     const end = args.endByte ?? buf.byteLength;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prom.codes/context-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Prometheus Context Engine — local-first codebase indexing & retrieval as an MCP server.",
   "type": "module",
   "bin": {