codesearch-mcp 0.0.18-alpha → 0.1.0-alpha

package/dist/src/services/OpenAICompatibleEmbedder.d.ts

@@ -0,0 +1,25 @@
+import type { Config } from '../config';
+import type { IEmbedder, InputType } from '../interfaces/IEmbedder';
+import type { ILogger } from '../interfaces/ILogger';
+export interface EmbedderDeps {
+    fetchImpl?: typeof fetch;
+    baseDelayMs?: number;
+}
+/**
+ * Embedder for any server exposing an OpenAI-style `/embeddings` endpoint:
+ * OpenAI cloud, Infinity, TEI, vLLM, LM Studio, LocalAI. One request carries all
+ * inputs (`{ input: string[], model, dimensions? }`) and returns
+ * `{ data: [{ embedding, index }] }`, re-ordered to input order.
+ */
+export declare class OpenAICompatibleEmbedder implements IEmbedder {
+    protected config: Config;
+    private logger;
+    readonly dimensions: number;
+    rerank?: (query: string, documents: string[], topN: number) => Promise<number[]>;
+    private readonly url;
+    private readonly doFetch;
+    private readonly baseDelayMs?;
+    constructor(config: Config, logger?: ILogger, deps?: EmbedderDeps);
+    embed(text: string, inputType?: InputType): Promise<number[]>;
+    embedBatch(texts: string[], _inputType?: InputType): Promise<number[][]>;
+}

package/dist/src/services/OpenAICompatibleEmbedder.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAICompatibleEmbedder = void 0;
+const LoggerService_1 = require("./LoggerService");
+const config_1 = require("../config");
+const reranker_1 = require("./reranker");
+const http_retry_1 = require("./http-retry");
+const constants_1 = require("../constants");
+/**
+ * Embedder for any server exposing an OpenAI-style `/embeddings` endpoint:
+ * OpenAI cloud, Infinity, TEI, vLLM, LM Studio, LocalAI. One request carries all
+ * inputs (`{ input: string[], model, dimensions? }`) and returns
+ * `{ data: [{ embedding, index }] }`, re-ordered to input order.
+ */
+class OpenAICompatibleEmbedder {
+    config;
+    logger;
+    dimensions;
+    rerank;
+    url;
+    doFetch;
+    baseDelayMs;
+    constructor(config, logger = LoggerService_1.LoggerService.silent(), deps = {}) {
+        this.config = config;
+        this.logger = logger;
+        const base = config.embedding.baseURL.replace(/\/+$/, '');
+        // Allow a baseURL that already includes the path (…/v1) or not.
+        this.url = /\/embeddings$/.test(base) ? base : `${base}/embeddings`;
+        this.doFetch = deps.fetchImpl ?? fetch;
+        this.baseDelayMs = deps.baseDelayMs;
+        this.dimensions = config.embedding.dimensions ?? (0, constants_1.registryDimension)(config.embedding.model) ?? 0;
+        this.rerank = (0, reranker_1.makeReranker)(config, logger, deps);
+    }
+    async embed(text, inputType) {
+        const [v] = await this.embedBatch([text], inputType);
+        return v;
+    }
+    async embedBatch(texts, _inputType) {
+        if (texts.length === 0)
+            return [];
+        return (0, http_retry_1.withRetry)(async () => {
+            const headers = { 'Content-Type': 'application/json' };
+            // Resolve the key lazily — an unset `env:` ref throws here (request time),
+            // not at construction, so `rag-web`/`rag-mcp` still start.
+            const apiKey = (0, config_1.resolveEnvRef)(this.config.embedding.apiKey);
+            if (apiKey)
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            const body = { model: this.config.embedding.model, input: texts };
+            if (this.config.embedding.dimensions != null)
+                body.dimensions = this.config.embedding.dimensions;
+            const res = await this.doFetch(this.url, {
+                method: 'POST',
+                headers,
+                signal: AbortSignal.timeout(120_000),
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const errBody = (await res.text().catch(() => res.statusText)).slice(0, 200);
+                throw new http_retry_1.HttpError(res.status, `embeddings request failed: ${res.status} ${errBody}`);
+            }
+            const data = await res.json();
+            // Guard against a partial/mismatched response — a missing vector would
+            // otherwise be inserted as "[undefined]" and fail the whole file, or (with
+            // reordering + no index) silently misalign vectors to the wrong chunks.
+            if (!Array.isArray(data.data) || data.data.length !== texts.length) {
+                throw new Error(`embeddings response returned ${data.data?.length ?? 0} vectors for ${texts.length} inputs`);
+            }
+            // Sort by `index` so vectors line up with input order regardless of server ordering.
+            return [...data.data]
+                .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+                .map(d => d.embedding);
+        }, { logger: this.logger, baseDelayMs: this.baseDelayMs, label: 'openai-embed' });
+    }
+}
+exports.OpenAICompatibleEmbedder = OpenAICompatibleEmbedder;

package/dist/src/services/SearcherService.d.ts

@@ -9,6 +9,7 @@ export interface ChunkRow {
     filePath: string;
     startLine: number;
     content: string;
+    ownerPath?: string | null;
 }
 export interface SearchResult extends ChunkRow {
     score: number;
@@ -102,6 +103,12 @@ export declare class SearcherService {
         query: string;
         translated: boolean;
     }>;
+    /**
+     * Refuse when the configured embedding model disagrees with the one that built
+     * the index — embedding a query into a foreign vector space returns noise. A
+     * missing `index_meta` (un-migrated DB / not yet indexed) does not block.
+     */
+    assertIndexMatches(): Promise<void>;
     listProjects(): Promise<ProjectRow[]>;
     searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
@@ -125,7 +132,6 @@ export declare class SearcherService {
     };
     readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
     readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
-    private isNonEnglish;
     private walkDir;
     private buildFindSymbolPattern;
     private inferKind;

package/dist/src/services/SearcherService.js

@@ -127,16 +127,37 @@ class SearcherService {
         }
         return edges;
     }
+    // Query translation was removed (legacy). The query is embedded as-is; the
+    // method is kept so the tool layer needs no change and `translated` is always
+    // false.
     async prepareQuery(raw) {
-        const t0 = Date.now();
-        if (this.config.search.autoTranslate && this.isNonEnglish(raw) && this.embedder.translate) {
-            const query = await this.embedder.translate(raw, this.config.search.translateModel);
-            this.logger.debug('SearcherService: prepareQuery', { translated: true, raw: raw.slice(0, 120), query: query.slice(0, 120), ms: Date.now() - t0 });
-            return { query, translated: true };
-        }
-        this.logger.debug('SearcherService: prepareQuery', { translated: false, query: raw.slice(0, 120), ms: Date.now() - t0 });
         return { query: raw, translated: false };
     }
+    /**
+     * Refuse when the configured embedding model disagrees with the one that built
+     * the index — embedding a query into a foreign vector space returns noise. A
+     * missing `index_meta` (un-migrated DB / not yet indexed) does not block.
+     */
+    async assertIndexMatches() {
+        const meta = await this.db.readIndexMeta();
+        if (!meta)
+            return;
+        const { provider, model } = this.config.embedding;
+        if (meta.provider !== provider || meta.model !== model) {
+            throw new Error(`Index was built with ${meta.provider}/${meta.model} but the config selects ${provider}/${model}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index for the new model.`);
+        }
+        // Same model but a changed dimension (e.g. a Matryoshka `embedding.dimensions`
+        // override) would embed the query at a width the column can't hold — pgvector
+        // would throw an opaque "different vector dimensions" error mid-query. Catch
+        // it here with the friendly hint. `embedder.dimensions` is 0 when the width is
+        // only knowable by probing, in which case we skip (can't compare cheaply).
+        const dim = this.embedder.dimensions;
+        if (dim > 0 && dim !== meta.dimensions) {
+            throw new Error(`Index was built at ${meta.dimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index at the new dimension.`);
+        }
+    }
     async listProjects() {
         const rows = await this.db.query(`SELECT "serviceName", COUNT(*)::int AS chunks
        FROM code_chunk
@@ -150,21 +171,22 @@ class SearcherService {
     }
     async searchChunks(query, limit, project, threshold) {
         const t0 = Date.now();
+        await this.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
         const fetchLimit = this.embedder.rerank
-            ? Math.min(limit * this.config.search.rerankerOverfetch, 200)
+            ? Math.min(limit * this.config.reranker.overfetch, 200)
             : limit;
         this.logger.debug('SearcherService: searchChunks', {
             query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
-        const embedding = await this.embedder.embed(query);
+        const embedding = await this.embedder.embed(query, 'query');
         const params = [`[${embedding}]`, effectiveThreshold, fetchLimit];
         let projectFilter = '';
         if (project) {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
-        const candidates = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content,
+        const candidates = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
               ROUND((embedding <=> $1)::numeric, 4)::float8 AS score
        FROM code_chunk
        WHERE embedding <=> $1 < $2
@@ -182,7 +204,9 @@ class SearcherService {
         try {
             const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
             this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
-            return indices.filter(i => i >= 0 && i < candidates.length).map(i => candidates[i]);
+            // Cap at `limit`: some rerank servers ignore `top_n` and echo back every
+            // candidate, so slicing here keeps the result count within the request.
+            return indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
         }
         catch (err) {
             this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
@@ -602,11 +626,6 @@ class SearcherService {
         this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
     }
-    isNonEnglish(text) {
-        // Use Unicode script detection: check for CJK, Cyrillic, Arabic, Hebrew, Thai, etc.
-        // Excludes common non-ASCII punctuation (smart quotes, em-dashes, accented Latin chars)
-        return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Cyrillic}\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Thai}\p{Script=Devanagari}]/u.test(text);
-    }
     walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
         let entries;
         try {

package/dist/src/services/VoyageEmbedder.d.ts

@@ -0,0 +1,22 @@
+import type { Config } from '../config';
+import type { IEmbedder, InputType } from '../interfaces/IEmbedder';
+import type { ILogger } from '../interfaces/ILogger';
+import type { EmbedderDeps } from './OpenAICompatibleEmbedder';
+/**
+ * Voyage AI embedder. Voyage's schema differs from OpenAI's: `input` is an array
+ * of strings, `input_type` (`query` | `document`) is required for best quality,
+ * and the optional `output_dimension` requests Matryoshka truncation. Response
+ * is `{ data: [{ embedding, index }] }`.
+ */
+export declare class VoyageEmbedder implements IEmbedder {
+    private config;
+    private logger;
+    readonly dimensions: number;
+    rerank?: (query: string, documents: string[], topN: number) => Promise<number[]>;
+    private readonly url;
+    private readonly doFetch;
+    private readonly baseDelayMs?;
+    constructor(config: Config, logger?: ILogger, deps?: EmbedderDeps);
+    embed(text: string, inputType?: InputType): Promise<number[]>;
+    embedBatch(texts: string[], inputType?: InputType): Promise<number[][]>;
+}

package/dist/src/services/VoyageEmbedder.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoyageEmbedder = void 0;
+const LoggerService_1 = require("./LoggerService");
+const config_1 = require("../config");
+const reranker_1 = require("./reranker");
+const http_retry_1 = require("./http-retry");
+const constants_1 = require("../constants");
+/**
+ * Voyage AI embedder. Voyage's schema differs from OpenAI's: `input` is an array
+ * of strings, `input_type` (`query` | `document`) is required for best quality,
+ * and the optional `output_dimension` requests Matryoshka truncation. Response
+ * is `{ data: [{ embedding, index }] }`.
+ */
+class VoyageEmbedder {
+    config;
+    logger;
+    dimensions;
+    rerank;
+    url;
+    doFetch;
+    baseDelayMs;
+    constructor(config, logger = LoggerService_1.LoggerService.silent(), deps = {}) {
+        this.config = config;
+        this.logger = logger;
+        const base = config.embedding.baseURL.replace(/\/+$/, '');
+        this.url = /\/embeddings$/.test(base) ? base : `${base}/embeddings`;
+        this.doFetch = deps.fetchImpl ?? fetch;
+        this.baseDelayMs = deps.baseDelayMs;
+        this.dimensions = config.embedding.dimensions ?? (0, constants_1.registryDimension)(config.embedding.model) ?? 0;
+        this.rerank = (0, reranker_1.makeReranker)(config, logger, deps);
+    }
+    async embed(text, inputType) {
+        const [v] = await this.embedBatch([text], inputType);
+        return v;
+    }
+    async embedBatch(texts, inputType = 'document') {
+        if (texts.length === 0)
+            return [];
+        return (0, http_retry_1.withRetry)(async () => {
+            const headers = { 'Content-Type': 'application/json' };
+            const apiKey = (0, config_1.resolveEnvRef)(this.config.embedding.apiKey);
+            if (apiKey)
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            const body = {
+                model: this.config.embedding.model,
+                input: texts,
+                input_type: inputType,
+            };
+            if (this.config.embedding.dimensions != null)
+                body.output_dimension = this.config.embedding.dimensions;
+            const res = await this.doFetch(this.url, {
+                method: 'POST',
+                headers,
+                signal: AbortSignal.timeout(120_000),
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                const errBody = (await res.text().catch(() => res.statusText)).slice(0, 200);
+                throw new http_retry_1.HttpError(res.status, `Voyage embeddings request failed: ${res.status} ${errBody}`);
+            }
+            const data = await res.json();
+            if (!Array.isArray(data.data) || data.data.length !== texts.length) {
+                throw new Error(`Voyage embeddings response returned ${data.data?.length ?? 0} vectors for ${texts.length} inputs`);
+            }
+            return [...data.data]
+                .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+                .map(d => d.embedding);
+        }, { logger: this.logger, baseDelayMs: this.baseDelayMs, label: 'voyage-embed' });
+    }
+}
+exports.VoyageEmbedder = VoyageEmbedder;

package/dist/src/services/WebServerService.d.ts

@@ -13,19 +13,22 @@ export interface FieldOption {
     values: string[];
     strict: boolean;
 }
-/** Placeholder shown to the browser instead of the real DB password. */
+/** Placeholder shown to the browser instead of a real secret. */
 export declare const PASSWORD_MASK = "********";
 /**
- * Merge a config submitted from the browser with the stored one. If the
- * password field still holds the mask (i.e. the user did not change it),
- * preserve the previously stored password rather than overwriting it with the
- * placeholder. Pure — no I/O. Exported for unit testing.
+ * Merge a config submitted from the browser with the stored one. Any secret
+ * field (DB password, embedding/reranker API keys) still holding the mask means
+ * the user did not change it — restore the stored value rather than overwrite it
+ * with the placeholder. `env:` references are not masked and round-trip as-is.
+ * Pure — no I/O. Exported for unit testing.
  */
 export declare function mergeConfigForSave(incoming: JsonConfig, existing: JsonConfig | null): JsonConfig;
 /**
- * Return a copy of the config with the DB password replaced by the mask, so the
- * real secret never reaches the browser. The masked value round-trips through
- * `mergeConfigForSave` on save. Pure — no I/O. Exported for unit testing.
+ * Return a copy of the config with raw secrets (DB password, raw API keys)
+ * replaced by the mask, so real secrets never reach the browser. `env:`
+ * references are left verbatim — they are not secret and the dashboard shows
+ * them as "set via <VAR>". The masked value round-trips through
+ * `mergeConfigForSave`. Pure — no I/O. Exported for unit testing.
  */
 export declare function maskConfig(cfg: JsonConfig): JsonConfig;
 /**
@@ -49,9 +52,11 @@ export declare class WebServer {
     private maskedConfig;
     private saveConfig;
     /**
-     * Choice lists for model fields. The embedding model is strict (only
-     * dimension-compatible models); the translate/reranker models are suggested
-     * from the user's installed Ollama models but stay free-text.
+     * Choice lists for model fields. Both are non-strict comboboxes (free text
+     * allowed): the embedding model suggests the known registry models plus any
+     * locally-installed models; the reranker model suggests installed models.
+     * Backends beyond the registry (e.g. arbitrary HuggingFace models on Infinity)
+     * still work — their dimension is probed at index time.
      */
     private fieldOptions;
     private installedModels;

package/dist/src/services/WebServerService.js

@@ -42,35 +42,53 @@ const config_store_1 = require("../config-store");
 const constants_1 = require("../constants");
 const graph_1 = require("../graph");
 const dashboard_1 = require("../web/dashboard");
-/** Placeholder shown to the browser instead of the real DB password. */
+/** Placeholder shown to the browser instead of a real secret. */
 exports.PASSWORD_MASK = '********';
 const MAX_BODY = 1_000_000; // 1 MB — config payloads are tiny
+/** A secret worth masking: a non-empty string that is not an `env:` reference. */
+function isRawSecret(v) {
+    return typeof v === 'string' && v !== '' && !v.startsWith('env:');
+}
 /**
- * Merge a config submitted from the browser with the stored one. If the
- * password field still holds the mask (i.e. the user did not change it),
- * preserve the previously stored password rather than overwriting it with the
- * placeholder. Pure — no I/O. Exported for unit testing.
+ * Merge a config submitted from the browser with the stored one. Any secret
+ * field (DB password, embedding/reranker API keys) still holding the mask means
+ * the user did not change it — restore the stored value rather than overwrite it
+ * with the placeholder. `env:` references are not masked and round-trip as-is.
+ * Pure — no I/O. Exported for unit testing.
  */
 function mergeConfigForSave(incoming, existing) {
     const merged = JSON.parse(JSON.stringify(incoming ?? {}));
-    if (merged.db && merged.db.password === exports.PASSWORD_MASK) {
-        const prev = existing?.db?.password;
-        if (prev !== undefined)
-            merged.db.password = prev;
-        else
-            delete merged.db.password;
-    }
+    const restore = (grp, field) => {
+        const g = merged[grp];
+        if (g && g[field] === exports.PASSWORD_MASK) {
+            const prev = existing?.[grp]?.[field];
+            if (prev !== undefined)
+                g[field] = prev;
+            else
+                delete g[field];
+        }
+    };
+    restore('db', 'password');
+    restore('embedding', 'apiKey');
+    restore('reranker', 'apiKey');
     return merged;
 }
 /**
- * Return a copy of the config with the DB password replaced by the mask, so the
- * real secret never reaches the browser. The masked value round-trips through
- * `mergeConfigForSave` on save. Pure — no I/O. Exported for unit testing.
+ * Return a copy of the config with raw secrets (DB password, raw API keys)
+ * replaced by the mask, so real secrets never reach the browser. `env:`
+ * references are left verbatim — they are not secret and the dashboard shows
+ * them as "set via <VAR>". The masked value round-trips through
+ * `mergeConfigForSave`. Pure — no I/O. Exported for unit testing.
  */
 function maskConfig(cfg) {
-    if (!cfg.db?.password)
-        return cfg;
-    return { ...cfg, db: { ...cfg.db, password: exports.PASSWORD_MASK } };
+    const clone = JSON.parse(JSON.stringify(cfg ?? {}));
+    if (clone.db?.password)
+        clone.db.password = exports.PASSWORD_MASK;
+    if (isRawSecret(clone.embedding?.apiKey))
+        clone.embedding.apiKey = exports.PASSWORD_MASK;
+    if (isRawSecret(clone.reranker?.apiKey))
+        clone.reranker.apiKey = exports.PASSWORD_MASK;
+    return clone;
 }
 /**
  * Local HTTP dashboard. Serves a schema-driven config editor, a project
@@ -171,15 +189,17 @@ class WebServer {
         this.json(res, 200, { ok: true });
     }
     /**
-     * Choice lists for model fields. The embedding model is strict (only
-     * dimension-compatible models); the translate/reranker models are suggested
-     * from the user's installed Ollama models but stay free-text.
+     * Choice lists for model fields. Both are non-strict comboboxes (free text
+     * allowed): the embedding model suggests the known registry models plus any
+     * locally-installed models; the reranker model suggests installed models.
+     * Backends beyond the registry (e.g. arbitrary HuggingFace models on Infinity)
+     * still work — their dimension is probed at index time.
      */
     async fieldOptions() {
         const installed = await this.installedModels();
+        const registryModels = Object.keys(constants_1.MODEL_REGISTRY);
         return {
-            'ollama.model': { values: [...constants_1.SUPPORTED_EMBED_MODELS], strict: true },
-            'search.translateModel': { values: installed, strict: false },
+            'embedding.model': { values: [...new Set([...registryModels, ...installed])], strict: false },
             'reranker.model': { values: installed, strict: false },
         };
     }
@@ -188,7 +208,7 @@ class WebServer {
             return (await this.embedder.listModels?.()) ?? [];
         }
         catch (err) {
-            this.logger.warn('WebServer: could not list Ollama models', { reason: err instanceof Error ? err.message : String(err) });
+            this.logger.warn('WebServer: could not list models', { reason: err instanceof Error ? err.message : String(err) });
             return [];
         }
     }

package/dist/src/services/http-retry.d.ts

@@ -0,0 +1,19 @@
+import type { ILogger } from '../interfaces/ILogger';
+export declare class HttpError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface RetryOpts {
+    /** Total attempts including the first (default 4). */
+    attempts?: number;
+    /** Base backoff in ms; grows exponentially (default 500). Set 0 in tests. */
+    baseDelayMs?: number;
+    logger?: ILogger;
+    label?: string;
+}
+/**
+ * Run `fn` with bounded exponential backoff on HTTP 429/5xx and network errors.
+ * Re-throws the last error once attempts are exhausted or the error is not
+ * transient.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOpts): Promise<T>;

package/dist/src/services/http-retry.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+exports.withRetry = withRetry;
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+exports.HttpError = HttpError;
+function sleep(ms) {
+    return ms > 0 ? new Promise(r => setTimeout(r, ms)) : Promise.resolve();
+}
+/** True for transient failures worth retrying (rate limit / server error / network / timeout). */
+function isRetryable(err) {
+    if (err instanceof HttpError)
+        return err.status === 429 || (err.status >= 500 && err.status <= 599);
+    // A request timeout (AbortSignal.timeout) rejects with a DOMException named
+    // 'TimeoutError' — the most common transient cloud failure, so retry it.
+    if (err != null && typeof err === 'object' && err.name === 'TimeoutError')
+        return true;
+    // Network-level errors (fetch throws) are transient too.
+    return err instanceof TypeError;
+}
+/**
+ * Run `fn` with bounded exponential backoff on HTTP 429/5xx and network errors.
+ * Re-throws the last error once attempts are exhausted or the error is not
+ * transient.
+ */
+async function withRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 4;
+    const base = opts.baseDelayMs ?? 500;
+    let lastErr;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= attempts || !isRetryable(err))
+                break;
+            const delay = base * Math.pow(2, attempt - 1);
+            opts.logger?.warn('http-retry: transient failure, retrying', {
+                label: opts.label, attempt, attempts, delayMs: delay,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}

package/dist/src/services/reranker.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from '../config';
+import type { ILogger } from '../interfaces/ILogger';
+/**
+ * Build a rerank function from `config.reranker`, or return `undefined` when
+ * reranking is disabled / unconfigured. Targets an OpenAI-compatible `/rerank`
+ * endpoint returning `{ results: [{ index }] }` (Infinity, TEI, vLLM,
+ * Jina/Cohere-shape). Ollama has NO rerank API, so it is not a valid backend
+ * here — the embedding provider is independent of the rerank server
+ * (`reranker.baseURL`), so Ollama embeddings + an Infinity reranker is fine.
+ * Returns original indices into `documents`, best-first.
+ */
+export declare function makeReranker(config: Config, logger: ILogger, deps?: {
+    fetchImpl?: typeof fetch;
+    baseDelayMs?: number;
+}): ((query: string, documents: string[], topN: number) => Promise<number[]>) | undefined;

package/dist/src/services/reranker.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeReranker = makeReranker;
+const config_1 = require("../config");
+const http_retry_1 = require("./http-retry");
+/**
+ * Build a rerank function from `config.reranker`, or return `undefined` when
+ * reranking is disabled / unconfigured. Targets an OpenAI-compatible `/rerank`
+ * endpoint returning `{ results: [{ index }] }` (Infinity, TEI, vLLM,
+ * Jina/Cohere-shape). Ollama has NO rerank API, so it is not a valid backend
+ * here — the embedding provider is independent of the rerank server
+ * (`reranker.baseURL`), so Ollama embeddings + an Infinity reranker is fine.
+ * Returns original indices into `documents`, best-first.
+ */
+function makeReranker(config, logger, deps = {}) {
+    const r = config.reranker;
+    if (!r.enabled)
+        return undefined;
+    if (!r.model) {
+        logger.warn('reranker: enabled=true but reranker.model is not set — reranking disabled');
+        return undefined;
+    }
+    const doFetch = deps.fetchImpl ?? fetch;
+    return async (query, documents, topN) => {
+        return (0, http_retry_1.withRetry)(async () => {
+            const headers = { 'Content-Type': 'application/json' };
+            const apiKey = (0, config_1.resolveEnvRef)(r.apiKey);
+            if (apiKey)
+                headers['Authorization'] = `Bearer ${apiKey}`;
+            const res = await doFetch(r.url, {
+                method: 'POST',
+                headers,
+                signal: AbortSignal.timeout(30_000),
+                body: JSON.stringify({ model: r.model, query, documents, top_n: topN, truncate: true }),
+            });
+            if (!res.ok) {
+                const body = (await res.text().catch(() => res.statusText)).slice(0, 200);
+                throw new http_retry_1.HttpError(res.status, `rerank failed: ${res.status} ${body}`);
+            }
+            const data = await res.json();
+            return data.results.map(x => x.index);
+        }, { logger, baseDelayMs: deps.baseDelayMs, label: 'rerank' });
+    };
+}

package/dist/src/setup.d.ts

@@ -1,2 +1,8 @@
 import type { LoggerService } from './services/LoggerService';
+/**
+ * Default answer for the "start Docker containers?" prompt: no only when both
+ * the database and the embedding backend are already reachable. Pure — exported
+ * for unit testing.
+ */
+export declare function dockerPromptDefault(dbReachable: boolean, embReachable: boolean): 'y' | 'n';
 export declare function runSetup(logger?: LoggerService): Promise<void>;