@prom.codes/context-mcp 0.2.2 → 0.3.0

package/dist/bin.js

@@ -3275,15 +3275,30 @@ var EMBEDDING_DRIFT_CODE = "EMBEDDING_DRIFT";
 function hasLazyIdentity(embedder) {
   return typeof embedder.resolveIdentity === "function";
 }
+var EMBED_BODY_CHARS = 1500;
+var EMBED_TEXT_VERSION = 2;
 function chunkTextForSymbol(sym) {
   const container = sym.container === null ? "" : ` in ${sym.container}`;
   const exported = sym.exported ? "exported " : "";
-  return `${exported}${sym.kind} ${sym.name}${container} (${sym.language})`;
+  const descriptor = `${exported}${sym.kind} ${sym.name}${container} (${sym.language})`;
+  const body = sym.body?.trim();
+  if (!body)
+    return descriptor;
+  const slice = body.length > EMBED_BODY_CHARS ? body.slice(0, EMBED_BODY_CHARS) : body;
+  return `${descriptor}
+${sym.filePath}
+${slice}`;
 }
 async function embedWorkspace(storage, embedder, options = {}) {
   if (hasLazyIdentity(embedder)) {
     await embedder.resolveIdentity(options.signal);
   }
+  {
+    const existing = await storage.getEmbeddingMeta();
+    if (existing !== null && (existing.embedTextVersion ?? 1) !== EMBED_TEXT_VERSION && existing.provider === embedder.name && existing.model === embedder.model && existing.dim === embedder.dimension) {
+      await storage.clearEmbeddings();
+    }
+  }
   try {
     return await runEmbedPass(storage, embedder, options, false);
   } catch (err) {
@@ -3301,7 +3316,8 @@ async function runEmbedPass(storage, embedder, options, driftRecovered) {
     provider: embedder.name,
     model: embedder.model,
     dim: embedder.dimension,
-    region: embedder.region
+    region: embedder.region,
+    embedTextVersion: EMBED_TEXT_VERSION
   };
   await storage.setEmbeddingMeta(meta);
   const rows = [];
@@ -3391,6 +3407,13 @@ var EDGE_TYPES = [
   "co-change"
 ];
 
+// ../shared/dist/hyde-prompt.js
+function renderHydePrompt(query) {
+  return `You are a code-retrieval assistant. Given the user query, emit a single hypothetical code snippet (no prose, no markdown fences) that would directly answer it. Use the most common language for the intent. Keep it \u2264 25 lines.
+
+Query: ${query}`;
+}
+
 // ../shared/dist/sensitive-paths.js
 var SENSITIVE_DIRECTORIES = /* @__PURE__ */ new Set([
   "secrets",
@@ -4113,6 +4136,7 @@ function rowToStoredSymbol(row) {
     language: row.language,
     container: row.container,
     exported: row.exported === 1,
+    body: row.body ?? void 0,
     range: {
       start: { row: row.start_row, column: row.start_col },
       end: { row: row.end_row, column: row.end_col },
@@ -7531,6 +7555,344 @@ var OpenAICompatRerankProvider = class {
   }
 };
 
+// ../rewriter-gemini/dist/index.js
+var DEFAULT_MODEL4 = "gemini-2.5-flash";
+var DEFAULT_BASE_URL2 = "https://generativelanguage.googleapis.com/v1beta";
+var DEFAULT_RETRIES7 = 6;
+var DEFAULT_BACKOFF7 = 2e3;
+var DEFAULT_RETRY_MAX4 = 6e4;
+var DEFAULT_MAX_TOKENS = 256;
+function parseRetryAfterMs4(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 sleep7(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 nonRetryable7(message) {
+  const err = new Error(message);
+  err.nonRetryable = true;
+  return err;
+}
+var GeminiQueryRewriter = class {
+  name;
+  model;
+  region;
+  #baseUrl;
+  #apiKey;
+  #maxRetries;
+  #retryBaseMs;
+  #retryMaxMs;
+  #fetch;
+  constructor(opts) {
+    if (typeof opts.apiKey !== "string" || opts.apiKey === "") {
+      throw new Error("GeminiQueryRewriter: apiKey is required");
+    }
+    this.model = opts.model ?? DEFAULT_MODEL4;
+    this.name = opts.name ?? `gemini:${this.model}`;
+    this.region = opts.region ?? "us";
+    this.#baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/+$/, "");
+    this.#apiKey = opts.apiKey;
+    this.#maxRetries = opts.maxRetries ?? DEFAULT_RETRIES7;
+    this.#retryBaseMs = opts.retryBaseMs ?? DEFAULT_BACKOFF7;
+    this.#retryMaxMs = opts.retryMaxMs ?? DEFAULT_RETRY_MAX4;
+    this.#fetch = opts.fetch ?? fetch;
+  }
+  async rewrite(query, opts) {
+    const trimmed = query.trim();
+    if (trimmed === "")
+      return [];
+    const n = opts?.n ?? 1;
+    if (!Number.isInteger(n) || n < 1)
+      return [];
+    const maxTokens = opts?.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const temperature = opts?.temperature ?? 0;
+    const signal = opts?.signal;
+    const body = {
+      contents: [
+        {
+          role: "user",
+          parts: [{ text: renderHydePrompt(trimmed) }]
+        }
+      ],
+      generationConfig: {
+        temperature,
+        maxOutputTokens: maxTokens,
+        candidateCount: n
+      }
+    };
+    try {
+      const payload = await this.#postWithRetry(body, signal);
+      return this.#decode(payload, n);
+    } catch {
+      return [];
+    }
+  }
+  async #postWithRetry(body, signal) {
+    const url = `${this.#baseUrl}/models/${encodeURIComponent(this.model)}:generateContent`;
+    const init = {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-goog-api-key": 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(url, 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 sleep7(backoff, signal);
+          continue;
+        }
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw nonRetryable7(`${this.name}: HTTP ${res.status} ${res.statusText}` + (text === "" ? "" : ` \u2014 ${text}`));
+        }
+        return await res.json();
+      } 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 sleep7(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 = parseRetryAfterMs4(retryAfterHeader);
+    const lower = advised === null ? exp : Math.max(exp, advised);
+    return Math.min(lower, this.#retryMaxMs);
+  }
+  #decode(payload, requested) {
+    const candidates = payload.candidates ?? [];
+    const out = [];
+    for (const cand of candidates) {
+      const parts = cand.content?.parts ?? [];
+      const text = parts.map((p) => typeof p.text === "string" ? p.text : "").join("");
+      const trimmed = text.trim();
+      if (trimmed !== "")
+        out.push(trimmed);
+      if (out.length >= requested)
+        break;
+    }
+    return out;
+  }
+};
+
+// ../rewriter-mistral/dist/index.js
+var DEFAULT_MODEL5 = "mistral-small-latest";
+var DEFAULT_BASE_URL3 = "https://api.mistral.ai/v1";
+var DEFAULT_RETRIES8 = 6;
+var DEFAULT_BACKOFF8 = 2e3;
+var DEFAULT_RETRY_MAX5 = 6e4;
+var DEFAULT_MAX_TOKENS2 = 256;
+function parseRetryAfterMs5(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 sleep8(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 nonRetryable8(message) {
+  const err = new Error(message);
+  err.nonRetryable = true;
+  return err;
+}
+var MistralQueryRewriter = class {
+  name;
+  model;
+  region;
+  #baseUrl;
+  #apiKey;
+  #maxRetries;
+  #retryBaseMs;
+  #retryMaxMs;
+  #fetch;
+  constructor(opts) {
+    if (typeof opts.apiKey !== "string" || opts.apiKey === "") {
+      throw new Error("MistralQueryRewriter: apiKey is required");
+    }
+    this.model = opts.model ?? DEFAULT_MODEL5;
+    this.name = opts.name ?? `mistral:${this.model}`;
+    this.region = opts.region ?? "eu";
+    this.#baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL3).replace(/\/+$/, "");
+    this.#apiKey = opts.apiKey;
+    this.#maxRetries = opts.maxRetries ?? DEFAULT_RETRIES8;
+    this.#retryBaseMs = opts.retryBaseMs ?? DEFAULT_BACKOFF8;
+    this.#retryMaxMs = opts.retryMaxMs ?? DEFAULT_RETRY_MAX5;
+    this.#fetch = opts.fetch ?? fetch;
+  }
+  async rewrite(query, opts) {
+    const trimmed = query.trim();
+    if (trimmed === "")
+      return [];
+    const n = opts?.n ?? 1;
+    if (!Number.isInteger(n) || n < 1)
+      return [];
+    const maxTokens = opts?.maxTokens ?? DEFAULT_MAX_TOKENS2;
+    const temperature = opts?.temperature ?? 0;
+    const signal = opts?.signal;
+    const body = {
+      model: this.model,
+      messages: [
+        { role: "user", content: renderHydePrompt(trimmed) }
+      ],
+      temperature,
+      max_tokens: maxTokens,
+      n
+    };
+    try {
+      const payload = await this.#postWithRetry(body, signal);
+      return this.#decode(payload, n);
+    } catch {
+      return [];
+    }
+  }
+  async #postWithRetry(body, signal) {
+    const url = `${this.#baseUrl}/chat/completions`;
+    const init = {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "accept": "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(url, 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 sleep8(backoff, signal);
+          continue;
+        }
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw nonRetryable8(`${this.name}: HTTP ${res.status} ${res.statusText}` + (text === "" ? "" : ` \u2014 ${text}`));
+        }
+        return await res.json();
+      } 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 sleep8(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 = parseRetryAfterMs5(retryAfterHeader);
+    const lower = advised === null ? exp : Math.max(exp, advised);
+    return Math.min(lower, this.#retryMaxMs);
+  }
+  #decode(payload, requested) {
+    const choices = payload.choices ?? [];
+    const out = [];
+    for (const c of choices) {
+      const text = c.message?.content ?? "";
+      const trimmed = text.trim();
+      if (trimmed !== "")
+        out.push(trimmed);
+      if (out.length >= requested)
+        break;
+    }
+    return out;
+  }
+};
+
 // dist/composition.js
 var RegionModeViolation = class extends Error {
   mode;
@@ -7816,6 +8178,55 @@ function discoverRerankProvider(env, fetchImpl) {
   }
   throw new NoProviderError(`unknown PROMETHEUS_RERANK_PROVIDER="${forced}" (expected "none", "voyage", or "bge")`);
 }
+function discoverQueryRewriter(env, fetchImpl) {
+  const regionMode = parseRegionMode(env.PROMETHEUS_REGION_MODE);
+  const forced = env.PROMETHEUS_REWRITER_PROVIDER?.toLowerCase() ?? "none";
+  if (forced === "" || forced === "none")
+    return { id: "none", provider: null };
+  if (forced === "gemini") {
+    const apiKey = env.GEMINI_API_KEY;
+    if (apiKey === void 0 || apiKey === "") {
+      throw new NoProviderError(`rewriter provider "gemini" requested but GEMINI_API_KEY is missing`);
+    }
+    const region = "us";
+    if (regionMode !== "default") {
+      throw new RegionModeViolation(regionMode, "gemini", region, regionMode === "eu-strict" ? ["mistral"] : []);
+    }
+    const model = env.GEMINI_REWRITER_MODEL ?? "gemini-2.5-flash";
+    const provider = new GeminiQueryRewriter({
+      name: `gemini:${model}`,
+      apiKey,
+      model,
+      region,
+      maxRetries: intEnv(env, "GEMINI_REWRITER_MAX_RETRIES", 6),
+      retryBaseMs: intEnv(env, "GEMINI_REWRITER_RETRY_BASE_MS", 2e3),
+      ...fetchOpt(fetchImpl)
+    });
+    return { id: "gemini", provider };
+  }
+  if (forced === "mistral") {
+    const apiKey = env.MISTRAL_API_KEY;
+    if (apiKey === void 0 || apiKey === "") {
+      throw new NoProviderError(`rewriter provider "mistral" requested but MISTRAL_API_KEY is missing`);
+    }
+    const region = "eu";
+    if (regionMode === "oss-only") {
+      throw new RegionModeViolation(regionMode, "mistral", region, []);
+    }
+    const model = env.MISTRAL_REWRITER_MODEL ?? "mistral-small-latest";
+    const provider = new MistralQueryRewriter({
+      name: `mistral:${model}`,
+      apiKey,
+      model,
+      region,
+      maxRetries: intEnv(env, "MISTRAL_REWRITER_MAX_RETRIES", 6),
+      retryBaseMs: intEnv(env, "MISTRAL_REWRITER_RETRY_BASE_MS", 2e3),
+      ...fetchOpt(fetchImpl)
+    });
+    return { id: "mistral", provider };
+  }
+  throw new NoProviderError(`unknown PROMETHEUS_REWRITER_PROVIDER="${forced}" (expected "none", "gemini", or "mistral")`);
+}
 function getStableDbPath(workspaceRoot) {
   const abs = resolve4(workspaceRoot);
   const hash = createHash3("sha256").update(abs).digest("hex").slice(0, 16);
@@ -7901,6 +8312,7 @@ async function composeFromEnv(opts) {
   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 { id: queryRewriterId, provider: queryRewriter } = discoverQueryRewriter(env, opts.fetch);
   const managed = apiKeyPresent && storageBackend === "sqlite";
   let closed = false;
   return {
@@ -7918,6 +8330,8 @@ async function composeFromEnv(opts) {
     reranker,
     rerankId,
     rerankTopN,
+    queryRewriter,
+    queryRewriterId,
     async close() {
       if (closed)
         return;
@@ -8072,6 +8486,34 @@ var DEFAULT_K2 = 10;
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_SNIPPET_BYTES = 1500;
 var RERANK_DOC_BYTES = 4096;
+var DEMOTE_NONSOURCE = process.env.PROMETHEUS_DEMOTE_NONSOURCE !== "off";
+function isNonSourcePath(filePath) {
+  const p = filePath.replace(/\\/g, "/").toLowerCase();
+  if (/(^|\/)(tests?|testing|doc|docs|examples?|fixtures?|\.github|benchmarks?|samples?)\//.test(p))
+    return true;
+  if (/(^|\/)(test_[^/]*|conftest)\.py$|(_test|\.test|\.spec)\.[a-z]+$/.test(p))
+    return true;
+  if (/\.(txt|md|rst|cfg|toml|ini|lock|json|ya?ml)$/.test(p))
+    return true;
+  return false;
+}
+var NONSOURCE_INTENT = /\b(tests?|testing|specs?|fixtures?|docs?|documentation|examples?|benchmarks?|samples?)\b/i;
+function queryWantsNonSource(query) {
+  const words = query.trim().split(/\s+/);
+  if (words.length > 12)
+    return false;
+  return NONSOURCE_INTENT.test(query);
+}
+function demoteNonSource(ordered, query) {
+  if (!DEMOTE_NONSOURCE || queryWantsNonSource(query))
+    return [...ordered];
+  const source = [];
+  const nonSource = [];
+  for (const r of ordered) {
+    (isNonSourcePath(r.symbol.filePath) ? nonSource : source).push(r);
+  }
+  return source.concat(nonSource);
+}
 function symbolToJson(s) {
   return {
     name: s.name,
@@ -8228,17 +8670,34 @@ var changedSinceInput = {
 };
 var emptyInput = {};
 function registerTools(server, deps) {
-  const { storage, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend, reranker, rerankTopN } = deps;
+  const { storage, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend, reranker, rerankTopN, queryRewriter } = deps;
   server.registerTool("search_code", {
     title: "Hybrid code search",
-    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).",
+    description: (
+      // Adoption lever (B3, 2026-06-22): assertive + HONEST positioning so the
+      // agent reaches for this instead of a grep-then-read loop on the queries
+      // where semantic search genuinely wins. Claims here are true by design.
+      'PRIMARY code search for this workspace \u2014 the fast path to WHERE code lives. Hybrid retrieval (lexical FTS + dense vector over the actual source body + symbol-graph, RRF-fused, cross-encoder reranked) returns the top symbols with provenance AND an inline source snippet per hit \u2014 ONE call that replaces a manual Grep\u2192Read loop, so prefer it for any code-location question. USE THIS FIRST when: you need a concept or behaviour ("where is auth handled?"), the exact symbol name is unknown or may have been renamed, the term is generic/high-frequency (grep would flood), or the repo is large or cross-language. Plain Grep is fine for an exact, known literal string in a known file \u2014 this tool wins on everything else, and returns the code inline so you usually don\'t need a follow-up read. Set `includeSnippet: false` for symbols only.'
+    ),
     inputSchema: searchInput
   }, async (args) => {
     const k = clampK(args.k);
     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 searchQuery = args.query;
+    if (queryRewriter) {
+      try {
+        const docs = await queryRewriter.rewrite(args.query, { n: 1, maxTokens: 512 });
+        const hyp = docs[0]?.trim();
+        if (hyp)
+          searchQuery = `${args.query}
+
+${hyp}`;
+      } catch {
+      }
+    }
+    const pool = await retriever.search(searchQuery, { k: poolK });
     let ordered = pool;
     let reranked = false;
     if (reranker && pool.length > 0) {
@@ -8250,6 +8709,7 @@ function registerTools(server, deps) {
         reranked = true;
       }
     }
+    ordered = demoteNonSource(ordered, args.query);
     const results = ordered.slice(0, k);
     const mapped = await Promise.all(results.map(async (r) => {
       const base = {

package/package.json

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