opencode-rag-plugin 1.19.4 → 1.19.8

package/dist/describer/describer.js

@@ -1,8 +1,10 @@
 import { postJson } from "../embedder/http.js";
-import { buildUserMessage, sleep } from "./shared.js";
+import { buildUserMessage, buildBatchUserMessage, parseBatchDescriptions, sleep } from "./shared.js";
 import pLimit from "p-limit";
 /** HTTP status codes that are safe to retry on. */
 const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** Consecutive failed batch attempts after which batching is disabled for the rest of the run. */
+const BATCH_MAX_STREAK = 2;
 /**
  * Description provider that works with any OpenAI-compatible chat API (including Ollama).
  *
@@ -11,6 +13,10 @@ const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
  */
 export class LlmDescriptionProvider {
     config;
+    /** Consecutive batches that needed individual fallback; disables batching past BATCH_MAX_STREAK. */
+    batchFailStreak = 0;
+    /** Whether multi-chunk batching is still active (adaptive, per provider instance / index run). */
+    adaptiveBatchActive = true;
     /**
      * @param config - Configuration for the LLM provider, including base URL, model, API key, proxy, and retry settings.
      */
@@ -37,28 +43,125 @@ export class LlmDescriptionProvider {
     async generateBatchDescriptions(chunks, logger, opts) {
         const log = logger ?? { info: (msg) => process.stderr.write(`${msg}\n`), warn: (msg) => process.stderr.write(`${msg}\n`), debug: (msg) => process.stderr.write(`${msg}\n`) };
         const concurrency = this.config.batchConcurrency ?? 3;
+        // Batching is an EXPERIMENTAL opt-in (description.batchEnabled). Off by
+        // default — a batch size of 1 routes every group through the individual
+        // request path below, which is exactly the per-chunk behavior.
+        const batchEnabled = this.config.batchEnabled === true;
+        const batchMaxChunks = batchEnabled ? (this.config.batchMaxChunks ?? 25) : 1;
         const total = chunks.length;
-        log.debug(`[describer] Generating descriptions for ${total} chunks via ${this.config.provider}/${this.config.model} (concurrency: ${concurrency})`);
+        log.debug(`[describer] Generating descriptions for ${total} chunks via ${this.config.provider}/${this.config.model} (concurrency: ${concurrency}, batch: ${batchEnabled ? batchMaxChunks : "off"})`);
         const result = new Map();
         const limit = pLimit(concurrency);
         let completed = 0;
-        await Promise.all(chunks.map((chunk) => limit(async () => {
-            const userMsg = buildUserMessage(chunk, this.config.maxContentChars);
-            log.debug(`[describer] REQUEST chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}):\n${userMsg}`);
-            try {
-                const desc = await this.generateDescription(chunk);
-                result.set(chunk.id, desc);
-                log.debug(`[describer] RESPONSE chunk ${chunk.id}: ${desc}`);
-            }
-            catch (err) {
-                log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
-            }
+        const emitProgress = (chunk) => {
             completed++;
             opts?.onProgress?.(chunk, completed, opts.total ?? total);
+        };
+        // Group chunks so that up to batchMaxChunks share a single LLM request,
+        // cutting round trips (one prefill + one generation per group instead of
+        // per chunk). Groups with a single chunk use the individual path for
+        // consistent error handling.
+        const groups = [];
+        for (let i = 0; i < chunks.length; i += batchMaxChunks) {
+            groups.push(chunks.slice(i, i + batchMaxChunks));
+        }
+        await Promise.all(groups.map((group) => limit(async () => {
+            if (group.length === 1) {
+                const chunk = group[0];
+                try {
+                    const desc = await this.generateDescription(chunk);
+                    result.set(chunk.id, desc);
+                }
+                catch (err) {
+                    log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                emitProgress(chunk);
+                return;
+            }
+            // Small models are unreliable at structured multi-item output — if a
+            // batch response can't be parsed, fall back to individual requests
+            // and degrade to per-chunk mode for the rest of the run after
+            // BATCH_MAX_STREAK consecutive failures.
+            let resolved;
+            let batchFailed = false;
+            if (this.adaptiveBatchActive) {
+                try {
+                    resolved = await this.batchDescribe(group, log);
+                }
+                catch (err) {
+                    log.warn(`[describer] Batch description failed for ${group.length} chunks, falling back to individual: ${err instanceof Error ? err.message : String(err)}`);
+                    resolved = new Map();
+                    batchFailed = true;
+                }
+            }
+            else {
+                resolved = new Map();
+            }
+            // Batch labels are ordinals (1..N); map back to chunks by position.
+            const missing = [];
+            for (let i = 0; i < group.length; i++) {
+                const chunk = group[i];
+                const desc = resolved.get(String(i + 1));
+                if (desc && desc.trim().length > 0) {
+                    result.set(chunk.id, desc.trim());
+                    emitProgress(chunk);
+                }
+                else {
+                    missing.push(chunk);
+                }
+            }
+            if (batchFailed || missing.length > 0) {
+                this.batchFailStreak++;
+                if (this.adaptiveBatchActive && this.batchFailStreak >= BATCH_MAX_STREAK) {
+                    this.adaptiveBatchActive = false;
+                    log.warn(`[describer] Batch descriptions unreliable (${this.batchFailStreak} consecutive failures), switching to individual requests for the rest of the run`);
+                }
+            }
+            else {
+                this.batchFailStreak = 0;
+            }
+            // Fall back to individual requests for chunks the batch did not cover.
+            for (const chunk of missing) {
+                try {
+                    const desc = await this.generateDescription(chunk);
+                    result.set(chunk.id, desc);
+                }
+                catch (err) {
+                    log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                emitProgress(chunk);
+            }
         })));
         log.debug(`[describer] Descriptions generated: ${result.size}/${total}`);
         return result;
     }
+    /**
+     * Describe a group of chunks in a single LLM request and parse the response.
+     *
+     * Builds one chat request whose user message contains all chunks wrapped in
+     * `[CHUNK <n>]` markers and expects a `<n>: <description>` line per chunk.
+     * Labels are ordinals and are mapped back to chunks by position in the
+     * calling group; labels outside the group's range (hallucinations) are
+     * naturally dropped, prompting the caller to fall back to individual
+     * requests for the missing chunks.
+     *
+     * @param group - Chunks to describe in one request (length > 1)
+     * @param log - Logger for diagnostic messages
+     * @returns Map of ordinal label to description (may be partial or empty)
+     * @throws When the LLM request itself fails (caller falls back per chunk)
+     */
+    async batchDescribe(group, log) {
+        const messages = [
+            { role: "system", content: this.config.systemPrompt },
+            { role: "user", content: buildBatchUserMessage(group, this.config.maxContentChars) },
+        ];
+        const timeoutMs = this.config.batchTimeoutMs ?? this.config.timeoutMs ?? 120000;
+        log.debug(`[describer] BATCH REQUEST ${group.length} chunks (${group[0].metadata.filePath}):\n${messages[1].content}`);
+        const content = await this.chatRequest(messages, timeoutMs);
+        const parsed = parseBatchDescriptions(content);
+        log.debug(`[describer] BATCH RESPONSE parsed ${parsed.size}/${group.length} chunks`);
+        return parsed;
+    }
     /**
      * Sends a chat completion request to the LLM API with retry and exponential backoff.
      * For Ollama, uses the `/api/chat` endpoint with streaming disabled; otherwise uses the standard `/v1/chat/completions` endpoint.
@@ -75,7 +178,7 @@ export class LlmDescriptionProvider {
             ? `${baseUrl}/chat`
             : `${baseUrl}${baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
         const body = isOllama
-            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx } }
+            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: this.config.keepAlive }
             : { model: this.config.model, messages };
         const headers = {};
         if (this.config.apiKey) {
@@ -85,7 +188,20 @@ export class LlmDescriptionProvider {
         const retryBaseDelayMs = this.config.retryBaseDelayMs ?? 1000;
         let lastError;
         for (let attempt = 0; attempt <= retryMax; attempt++) {
-            const response = await postJson(url, body, headers, timeoutMs, this.config.proxy);
+            let response;
+            try {
+                response = await postJson(url, body, headers, timeoutMs, this.config.proxy);
+            }
+            catch (err) {
+                // Network-level failures (ECONNREFUSED, socket timeouts) are transient —
+                // treat them like retryable HTTP statuses.
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt === retryMax)
+                    throw lastError;
+                const delayMs = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
+                await sleep(delayMs);
+                continue;
+            }
             if (response.ok) {
                 const json = (await response.json());
                 return extractResponseText(json, isOllama);
@@ -96,7 +212,7 @@ export class LlmDescriptionProvider {
                 throw error;
             }
             lastError = error;
-            const delayMs = retryBaseDelayMs * Math.pow(2, attempt);
+            const delayMs = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
             await sleep(delayMs);
         }
         throw lastError ?? new Error("Description LLM request failed: unknown error");

package/dist/describer/gemini.js

@@ -57,24 +57,39 @@ export class GeminiDescriptionProvider {
         const apiKey = this.config.apiKey ?? "";
         const model = this.config.model;
         const systemPrompt = systemOverride ?? this.config.systemPrompt;
-        const allParts = [{ text: systemPrompt }];
-        for (const c of contents) {
-            allParts.push(...c.parts);
-        }
         const body = {
-            contents: [{ role: "user", parts: allParts }],
+            // The system prompt goes into the native systemInstruction field, never
+            // into the same content parts as the chunk text.
+            systemInstruction: { parts: [{ text: systemPrompt }] },
+            contents: contents.map((c) => ({ role: c.role, parts: c.parts })),
         };
         const headers = {
             "Content-Type": "application/json",
         };
-        const url = apiKey
-            ? `${baseUrl}/models/${model}:generateContent?key=${apiKey}`
-            : `${baseUrl}/models/${model}:generateContent`;
+        // Send the key via header so it never appears in URLs (which are echoed in
+        // redirect-limit error messages) and cannot be mangled by URL encoding.
+        if (apiKey) {
+            headers["x-goog-api-key"] = apiKey;
+        }
+        const url = `${baseUrl}/models/${model}:generateContent`;
         const retryMax = this.config.retryMax ?? 3;
         const retryBaseDelayMs = this.config.retryBaseDelayMs ?? 1000;
         let lastError;
         for (let attempt = 0; attempt <= retryMax; attempt++) {
-            const response = await postJson(url, body, headers, timeoutMs);
+            let response;
+            try {
+                response = await postJson(url, body, headers, timeoutMs, this.config.proxy);
+            }
+            catch (err) {
+                // Network-level failures (ECONNREFUSED, socket timeouts) are transient —
+                // treat them like retryable HTTP statuses.
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt === retryMax)
+                    throw lastError;
+                const delayMs = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
+                await sleep(delayMs);
+                continue;
+            }
             if (response.ok) {
                 const json = (await response.json());
                 const text = json.candidates?.[0]?.content?.parts?.[0]?.text;
@@ -89,7 +104,7 @@ export class GeminiDescriptionProvider {
                 throw error;
             }
             lastError = error;
-            const delayMs = retryBaseDelayMs * Math.pow(2, attempt);
+            const delayMs = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
             await sleep(delayMs);
         }
         throw lastError ?? new Error("Gemini LLM request failed: unknown error");

package/dist/describer/shared.d.ts

@@ -15,3 +15,31 @@ import type { Chunk } from "../core/interfaces.js";
 export declare function buildUserMessage(chunk: Chunk, maxContentChars?: number): string;
 /** Promise-based delay for use with async/await. */
 export declare function sleep(ms: number): Promise<void>;
+/**
+ * Build a user message describing multiple chunks in a single LLM request.
+ *
+ * Each chunk is wrapped in `[CHUNK <n>] ... [END CHUNK <n>]` markers using
+ * short ordinal labels (1-based position in the group) rather than chunk
+ * UUIDs — small models reliably reproduce `n: <description>` lines but often
+ * mangle long random ids. The model is asked to reply with exactly one line
+ * per chunk in `<n>: <one-line description>` format (see
+ * `parseBatchDescriptions`); labels map back to chunks by position.
+ *
+ * @param chunks - The chunks to describe in one request
+ * @param maxContentChars - Optional per-chunk content truncation limit
+ * @returns Formatted message string for the batched LLM request
+ */
+export declare function buildBatchUserMessage(chunks: Chunk[], maxContentChars?: number): string;
+/**
+ * Parse a batched description response into a `label → description` map.
+ *
+ * Tolerant parser: only lines matching `<label>: <text>` are kept, so
+ * preamble, trailing prose, or markdown fences are ignored. Labels are the
+ * short ordinals used in `buildBatchUserMessage` (e.g. `1: handles auth`);
+ * they are mapped back to chunk IDs by position in the calling group.
+ * Duplicate labels keep the first occurrence.
+ *
+ * @param content - Raw response text from the LLM
+ * @returns Map of label to description (may be empty or partial)
+ */
+export declare function parseBatchDescriptions(content: string): Map<string, string>;

package/dist/describer/shared.js

@@ -31,4 +31,64 @@ export function buildUserMessage(chunk, maxContentChars) {
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Build a user message describing multiple chunks in a single LLM request.
+ *
+ * Each chunk is wrapped in `[CHUNK <n>] ... [END CHUNK <n>]` markers using
+ * short ordinal labels (1-based position in the group) rather than chunk
+ * UUIDs — small models reliably reproduce `n: <description>` lines but often
+ * mangle long random ids. The model is asked to reply with exactly one line
+ * per chunk in `<n>: <one-line description>` format (see
+ * `parseBatchDescriptions`); labels map back to chunks by position.
+ *
+ * @param chunks - The chunks to describe in one request
+ * @param maxContentChars - Optional per-chunk content truncation limit
+ * @returns Formatted message string for the batched LLM request
+ */
+export function buildBatchUserMessage(chunks, maxContentChars) {
+    const parts = [
+        "Describe each code chunk below in ONE short sentence (max 20 words) each.",
+        "Do not repeat code in your descriptions.",
+        "Reply with EXACTLY one line per chunk, in this format:",
+        "<number>: <one-line description>",
+        "",
+    ];
+    chunks.forEach((chunk, index) => {
+        const label = index + 1;
+        parts.push(`[CHUNK ${label}]`);
+        parts.push(buildUserMessage(chunk, maxContentChars));
+        parts.push(`[END CHUNK ${label}]`);
+        parts.push("");
+    });
+    return parts.join("\n").trim();
+}
+/**
+ * Parse a batched description response into a `label → description` map.
+ *
+ * Tolerant parser: only lines matching `<label>: <text>` are kept, so
+ * preamble, trailing prose, or markdown fences are ignored. Labels are the
+ * short ordinals used in `buildBatchUserMessage` (e.g. `1: handles auth`);
+ * they are mapped back to chunk IDs by position in the calling group.
+ * Duplicate labels keep the first occurrence.
+ *
+ * @param content - Raw response text from the LLM
+ * @returns Map of label to description (may be empty or partial)
+ */
+export function parseBatchDescriptions(content) {
+    const result = new Map();
+    const lineRe = /^([A-Za-z0-9_.-]+):\s*(.+)$/;
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const match = lineRe.exec(line);
+        if (match && match[1] && match[2] && match[2].trim().length > 0) {
+            const id = match[1];
+            if (!result.has(id)) {
+                result.set(id, match[2].trim());
+            }
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=shared.js.map

package/dist/embedder/factory.d.ts

@@ -22,9 +22,11 @@ export declare function createEmbedder(config: RagConfig): EmbeddingProvider;
  * (or concurrently when `concurrency > 1`). When concurrency is limited, uses
  * `p-limit` to cap the number of in-flight requests.
  *
- * Each batch is retried up to `retryMax` times with exponential backoff. If all
- * retries are exhausted, the batch is skipped and empty arrays are returned for
- * those texts so the caller can still process successfully embedded batches.
+ * Each batch is retried up to `retryMax` times with exponential backoff (only
+ * for transient failures — auth/validation errors are not retried). If all
+ * retries are exhausted or the provider returns a mismatched embedding count,
+ * the batch is skipped and empty arrays are returned for those texts so the
+ * caller can still process successfully embedded batches.
  *
  * @param embedder - The embedding provider to use
  * @param texts - Array of text strings to embed

package/dist/embedder/factory.js

@@ -1,4 +1,4 @@
-import { isOpenAiCompatible } from "../core/provider-defaults.js";
+import { isOpenAiCompatible, supportsEmbedding } from "../core/provider-defaults.js";
 import { OllamaProvider } from "./ollama.js";
 import { OpenAIProvider } from "./openai.js";
 import { CohereProvider } from "./cohere.js";
@@ -17,8 +17,14 @@ import pLimit from "p-limit";
 export function createEmbedder(config) {
     const { provider, baseUrl, model, apiKey, proxy, timeoutMs } = config.embedding;
     const effectiveTimeoutMs = timeoutMs ?? 120000;
+    // Fail fast for chat-only providers (groq, deepseek, anthropic, google)
+    // — proceeding would surface a cryptic failure at index time.
+    if (!supportsEmbedding(provider)) {
+        throw new Error(`Provider "${provider}" does not support embeddings. ` +
+            "Use an embedding-capable provider (ollama, openai, cohere, nvidia, azure, mistral, together, fireworks).");
+    }
     if (provider === "ollama") {
-        return new OllamaProvider(baseUrl, model, apiKey, effectiveTimeoutMs, proxy, config.logging.level);
+        return new OllamaProvider(baseUrl, model, apiKey, effectiveTimeoutMs, proxy, config.logging.level, config.embedding.keepAlive);
     }
     if (provider === "cohere") {
         if (!apiKey) {
@@ -34,6 +40,15 @@ export function createEmbedder(config) {
     }
     throw new Error(`Unknown embedding provider: ${provider}`);
 }
+/**
+ * HTTP statuses that indicate a permanent failure — retrying cannot help
+ * (auth errors, bad requests, missing resources). Providers raise these as
+ * Error objects whose messages contain the status code.
+ */
+const PERMANENT_STATUS_RE = /\(?(400|401|403|404|422)\)?/;
+function isPermanentError(err) {
+    return PERMANENT_STATUS_RE.test(err instanceof Error ? err.message : String(err));
+}
 /**
  * Embed a list of texts in batches with optional concurrency control and per-batch retry.
  *
@@ -41,9 +56,11 @@ export function createEmbedder(config) {
  * (or concurrently when `concurrency > 1`). When concurrency is limited, uses
  * `p-limit` to cap the number of in-flight requests.
  *
- * Each batch is retried up to `retryMax` times with exponential backoff. If all
- * retries are exhausted, the batch is skipped and empty arrays are returned for
- * those texts so the caller can still process successfully embedded batches.
+ * Each batch is retried up to `retryMax` times with exponential backoff (only
+ * for transient failures — auth/validation errors are not retried). If all
+ * retries are exhausted or the provider returns a mismatched embedding count,
+ * the batch is skipped and empty arrays are returned for those texts so the
+ * caller can still process successfully embedded batches.
  *
  * @param embedder - The embedding provider to use
  * @param texts - Array of text strings to embed
@@ -67,13 +84,27 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
     async function embedWithRetry(batchTexts) {
         for (let attempt = 0; attempt <= retryMax; attempt++) {
             try {
-                return await embedder.embed(batchTexts, purpose);
+                const embeddings = await embedder.embed(batchTexts, purpose);
+                // Validate the response shape: a count mismatch would silently attach
+                // vectors to the wrong chunks downstream; a dimension mismatch would
+                // poison the store. Treat both as a retryable batch failure.
+                if (embeddings.length !== batchTexts.length) {
+                    throw new Error(`Embedding provider returned ${embeddings.length} vectors for ${batchTexts.length} texts`);
+                }
+                const dims = new Set(embeddings.map((v) => v.length));
+                if (dims.size > 1 || dims.has(0)) {
+                    throw new Error(`Embedding provider returned inconsistent vector dimensions: ${[...dims].join(", ")}`);
+                }
+                return embeddings;
             }
             catch (err) {
-                if (attempt < retryMax) {
-                    const delay = retryBaseDelayMs * Math.pow(2, attempt);
+                if (attempt < retryMax && !isPermanentError(err)) {
+                    const delay = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
                     await new Promise(resolve => setTimeout(resolve, delay));
                 }
+                else if (attempt >= retryMax || isPermanentError(err)) {
+                    return null;
+                }
             }
         }
         return null;
@@ -99,7 +130,9 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
     const batchResults = await Promise.all(batches.map((batch) => limit(async () => {
         const embeddings = await embedWithRetry(batch.texts);
         const flatResult = embeddings ?? batch.texts.map(() => []);
-        completedCount += embeddings?.length ?? 0;
+        // Count processed TEXTS (not returned vectors) so failed batches
+        // still advance progress towards the total.
+        completedCount += batch.texts.length;
         onProgress?.(completedCount, texts.length);
         return { index: batch.index, embeddings: flatResult };
     })));

package/dist/embedder/health.js

@@ -1,4 +1,4 @@
-import { postJson } from "./http.js";
+import { fetchWithProxy, postJson } from "./http.js";
 /**
  * Check connectivity and model availability for all configured providers.
  * Returns one result per configured model (embedding + description + image_description if enabled).
@@ -42,10 +42,10 @@ async function checkDescriptionModel(config, _timeoutMs) {
         return checkOllamaChat(baseUrl, model, descTimeout, desc.proxy);
     }
     if (provider === "anthropic") {
-        return checkAnthropicChat(baseUrl, model, apiKey, descTimeout);
+        return checkAnthropicChat(baseUrl, model, apiKey, descTimeout, desc.proxy);
     }
     if (provider === "google") {
-        return checkGoogleChat(baseUrl, model, apiKey, descTimeout);
+        return checkGoogleChat(baseUrl, model, apiKey, descTimeout, desc.proxy);
     }
     // OpenAI-compatible chat endpoint
     return checkOpenAiChat(baseUrl, model, apiKey, descTimeout, desc.proxy);
@@ -62,10 +62,10 @@ async function checkImageDescriptionModel(config, _timeoutMs) {
         return checkOllamaChat(baseUrl, model, imgTimeout, img.proxy, "image_description");
     }
     if (provider === "anthropic") {
-        return checkAnthropicChat(baseUrl, model, apiKey, imgTimeout, "image_description");
+        return checkAnthropicChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
     }
     if (provider === "google") {
-        return checkGoogleChat(baseUrl, model, apiKey, imgTimeout, "image_description");
+        return checkGoogleChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
     }
     // OpenAI-compatible chat endpoint
     return checkOpenAiChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
@@ -125,16 +125,16 @@ async function checkOllamaChat(baseUrl, model, timeoutMs, proxy, type = "descrip
  * Check OpenAI-compatible embedding endpoint via the /models endpoint
  * to validate the API key without consuming embedding tokens.
  */
-async function checkOpenAiEmbed(baseUrl, model, apiKey, timeoutMs, _proxy) {
+async function checkOpenAiEmbed(baseUrl, model, apiKey, timeoutMs, proxy) {
     if (!apiKey) {
         return { provider: "openai", model, type: "embedding", status: "error", error: "No API key configured" };
     }
     const url = `${baseUrl.replace(/\/+$/, "")}/models`;
     try {
-        const response = await fetch(url, {
+        const response = await fetchWithProxy(url, {
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(Math.min(timeoutMs ?? 15000, 15000)),
-        });
+        }, proxy);
         if (response.ok) {
             return { provider: "openai", model, type: "embedding", status: "ok" };
         }
@@ -150,16 +150,16 @@ async function checkOpenAiEmbed(baseUrl, model, apiKey, timeoutMs, _proxy) {
     }
 }
 /** Check OpenAI-compatible chat endpoint via the /models endpoint. */
-async function checkOpenAiChat(baseUrl, model, apiKey, timeoutMs, _proxy, type = "description") {
+async function checkOpenAiChat(baseUrl, model, apiKey, timeoutMs, proxy, type = "description") {
     if (!apiKey) {
         return { provider: "openai", model, type, status: "error", error: "No API key configured" };
     }
     const url = `${baseUrl.replace(/\/+$/, "")}/models`;
     try {
-        const response = await fetch(url, {
+        const response = await fetchWithProxy(url, {
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(Math.min(timeoutMs ?? 15000, 15000)),
-        });
+        }, proxy);
         if (response.ok) {
             return { provider: "openai", model, type, status: "ok" };
         }
@@ -196,13 +196,13 @@ async function checkCohereEmbed(baseUrl, model, apiKey, timeoutMs, proxy) {
 }
 // ── Anthropic check ────────────────────────────────────────────
 /** Check Anthropic chat endpoint by sending a minimal message. */
-async function checkAnthropicChat(baseUrl, model, apiKey, timeoutMs, type = "description") {
+async function checkAnthropicChat(baseUrl, model, apiKey, timeoutMs, proxy, type = "description") {
     if (!apiKey) {
         return { provider: "anthropic", model, type, status: "error", error: "No API key configured" };
     }
     const url = `${baseUrl.replace(/\/+$/, "")}/messages`;
     try {
-        const response = await fetch(url, {
+        const response = await fetchWithProxy(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
@@ -215,7 +215,7 @@ async function checkAnthropicChat(baseUrl, model, apiKey, timeoutMs, type = "des
                 messages: [{ role: "user", content: "hi" }],
             }),
             signal: AbortSignal.timeout(Math.min(timeoutMs ?? 15000, 15000)),
-        });
+        }, proxy);
         if (response.ok) {
             return { provider: "anthropic", model, type, status: "ok" };
         }
@@ -232,20 +232,20 @@ async function checkAnthropicChat(baseUrl, model, apiKey, timeoutMs, type = "des
 }
 // ── Google Gemini check ────────────────────────────────────────
 /** Check Google Gemini chat endpoint by sending a minimal generateContent request. */
-async function checkGoogleChat(baseUrl, model, apiKey, timeoutMs, type = "description") {
+async function checkGoogleChat(baseUrl, model, apiKey, timeoutMs, proxy, type = "description") {
     if (!apiKey) {
         return { provider: "google", model, type, status: "error", error: "No API key configured" };
     }
-    const url = `${baseUrl.replace(/\/+$/, "")}/models/${model}:generateContent?key=${apiKey}`;
+    const url = `${baseUrl.replace(/\/+$/, "")}/models/${model}:generateContent`;
     try {
-        const response = await fetch(url, {
+        const response = await fetchWithProxy(url, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: { "Content-Type": "application/json", "x-goog-api-key": apiKey },
             body: JSON.stringify({
                 contents: [{ parts: [{ text: "hi" }] }],
             }),
             signal: AbortSignal.timeout(Math.min(timeoutMs ?? 15000, 15000)),
-        });
+        }, proxy);
         if (response.ok) {
             return { provider: "google", model, type, status: "ok" };
         }

package/dist/embedder/http.d.ts

@@ -12,6 +12,19 @@ export interface HttpResponseLike {
 /** Destroy all pooled TCP/TLS sockets and clear the connection pool. */
 declare function destroyAllPooledConnections(): void;
 export { destroyAllPooledConnections };
+/**
+ * Fetch a URL through the configured proxy, applying the proxy to
+ * HTTP(S)_PROXY env vars for the duration of the request (serialized).
+ *
+ * Used by health checks and other one-off requests that do not go
+ * through {@link postJson}.
+ */
+export declare function fetchWithProxy(urlString: string, init: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}, proxy?: ProxyConfig): Promise<Response>;
 /**
  * Check whether a hostname refers to the local machine.
  *
@@ -43,7 +56,7 @@ export declare function matchesNoProxy(hostname: string, noProxy?: string): bool
  * @param redirectCount - Internal redirect counter (starts at 0)
  * @returns A promise resolving to an HttpResponseLike
  */
-export declare function directRequest(url: URL, body: unknown, headers: Record<string, string>, timeoutMs: number, redirectCount?: number): Promise<HttpResponseLike>;
+export declare function directRequest(url: URL, body: unknown, headers: Record<string, string>, timeoutMs: number, redirectCount?: number, signal?: AbortSignal): Promise<HttpResponseLike>;
 /**
  * POST JSON to a URL, optionally routing through a proxy.
  *