opencode-rag-plugin 1.19.4 → 1.19.5

package/dist/cli/format.js

@@ -8,6 +8,7 @@
 import pc from "picocolors";
 import { resolveRagContext } from "../core/bootstrap.js";
 import { destroyAllPooledConnections } from "../embedder/http.js";
+import { appendDebugLog } from "../core/fileLogger.js";
 // ── Color palette ───────────────────────────────────────────────
 /**
  * Semantic color helpers for consistent CLI output styling.
@@ -61,9 +62,9 @@ export const c = {
  * @param message - Human-readable error message.
  * @param error - Optional error object for structured logging.
  */
-export function logCliError(_logFilePath, _scope, message, _error) {
+export function logCliError(logFilePath, scope, message, error) {
     console.error(c.error(message));
-    //appendDebugLog(logFilePath, { scope, message, error });
+    appendDebugLog(logFilePath, { scope, message, error });
 }
 /**
  * Log an informational message to stdout and optionally append to the debug log.
@@ -72,9 +73,9 @@ export function logCliError(_logFilePath, _scope, message, _error) {
  * @param scope - Logical scope (e.g. "index", "query") for log filtering.
  * @param message - Human-readable info message.
  */
-export function logCliInfo(_logFilePath, _scope, message) {
+export function logCliInfo(logFilePath, scope, message) {
     console.log(message);
-    //appendDebugLog(logFilePath, { scope, message });
+    appendDebugLog(logFilePath, { scope, message });
 }
 // ── Context resolution ──────────────────────────────────────────
 /**
@@ -109,10 +110,18 @@ function logConfigDetails(logFilePath, config) {
 /**
  * Gracefully close a `RagContext` — closes the vector store and destroys pooled HTTP connections.
  *
+ * The store close is raced against a timeout because LanceDB's native `close()`
+ * can hang indefinitely on Windows; callers must never be blocked forever.
+ *
  * @param ctx - The `RagContext` to clean up.
  */
 export async function cleanupContext(ctx) {
-    await ctx.store.close();
+    await Promise.race([
+        ctx.store.close(),
+        new Promise((resolve) => {
+            setTimeout(resolve, 5000).unref();
+        }),
+    ]);
     destroyAllPooledConnections();
 }
 // ── Formatting helpers ──────────────────────────────────────────

package/dist/content/image.js

@@ -95,25 +95,47 @@ export async function resizeImage(buffer, filePath, maxDimension) {
             const { pixels, width, height, channels } = decodeBmp(buffer);
             const ch = channels;
             if (width <= maxDimension && height <= maxDimension) {
-                return sharp(pixels, { raw: { width, height, channels: ch } })
-                    .jpeg({ quality: 80 })
-                    .toBuffer();
+                const pipeline = sharp(pixels, { raw: { width, height, channels: ch } })
+                    .jpeg({ quality: 80 });
+                try {
+                    return await pipeline.toBuffer();
+                }
+                finally {
+                    pipeline.destroy();
+                }
             }
-            return sharp(pixels, { raw: { width, height, channels: ch } })
+            const pipeline = sharp(pixels, { raw: { width, height, channels: ch } })
                 .resize({ width: maxDimension, fit: "inside", withoutEnlargement: true })
-                .jpeg({ quality: 80 })
-                .toBuffer();
+                .jpeg({ quality: 80 });
+            try {
+                return await pipeline.toBuffer();
+            }
+            finally {
+                pipeline.destroy();
+            }
         }
-        const meta = await sharp(buffer).metadata();
+        const metaPipeline = sharp(buffer);
+        const meta = await metaPipeline.metadata().finally(() => metaPipeline.destroy());
         const w = meta.width ?? 0;
         const h = meta.height ?? 0;
         if (w <= maxDimension && h <= maxDimension) {
-            return sharp(buffer).jpeg({ quality: 80 }).toBuffer();
+            const pipeline = sharp(buffer).jpeg({ quality: 80 });
+            try {
+                return await pipeline.toBuffer();
+            }
+            finally {
+                pipeline.destroy();
+            }
         }
-        return sharp(buffer)
+        const pipeline = sharp(buffer)
             .resize({ width: maxDimension, fit: "inside", withoutEnlargement: true })
-            .jpeg({ quality: 80 })
-            .toBuffer();
+            .jpeg({ quality: 80 });
+        try {
+            return await pipeline.toBuffer();
+        }
+        finally {
+            pipeline.destroy();
+        }
     }
     catch (err) {
         throw new Error(`Image resize failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/content/reader.js

@@ -145,13 +145,57 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
                 const stat = await fs.stat(filePath);
                 const entry = manifest.files[normalizedPath];
                 if (entry.mtime === stat.mtimeMs && entry.size === stat.size) {
+                    // Fast path — BUT only when the description config is unchanged:
+                    // when descHash differs, the worker needs the full content to
+                    // re-chunk and re-describe the file. Returning empty content here
+                    // would make chunkFile() yield zero chunks and the pipeline would
+                    // DELETE the file from the index instead of re-describing it.
+                    // Mirrors pipeline.ts: `descriptionProvider ? computeDescriptionConfigHash(config) : undefined`.
+                    const currentDescHash = config.description?.enabled
+                        ? (computeDescriptionConfigHash(config) ?? "")
+                        : "";
+                    if (!currentDescHash || entry.descHash === currentDescHash) {
+                        completed++;
+                        return {
+                            filePath,
+                            normalizedPath,
+                            content: "",
+                            hash: entry.hash,
+                            isEmpty: false,
+                            isTooSmall: false,
+                            extractionStatus: "ok",
+                            mtime: stat.mtimeMs,
+                            size: stat.size,
+                        };
+                    }
+                }
+            }
+            catch {
+                /* stat failed, fall through to full read */
+            }
+        }
+        const isImage = imageVisionProvider !== null && imageExtractor.isImageFile(filePath);
+        const ext = path.extname(filePath).toLowerCase();
+        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(ext) ||
+            docxExtractor.DOCX_EXTENSIONS.has(ext) ||
+            docExtractor.DOC_EXTENSIONS.has(ext) ||
+            excelExtractor.EXCEL_EXTENSIONS.has(ext) ||
+            isImage;
+        // Reject oversized binaries BEFORE buffering them — a 2 GB PDF was
+        // previously read fully into memory only to be rejected by the
+        // 100 MB check inside the PDF extractor.
+        if (isBinary && pdfExtractor.PDF_EXTENSIONS.has(ext)) {
+            try {
+                const stat = await fs.stat(filePath);
+                if (stat.size > 100 * 1024 * 1024) {
+                    logger?.warn(`  ${filePath} (PDF exceeds 100 MB — skipping)`);
                     completed++;
                     return {
                         filePath,
                         normalizedPath,
                         content: "",
-                        hash: entry.hash,
-                        isEmpty: false,
+                        hash: computeFileHash(""),
+                        isEmpty: true,
                         isTooSmall: false,
                         extractionStatus: "ok",
                         mtime: stat.mtimeMs,
@@ -160,17 +204,10 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
                 }
             }
             catch {
-                /* stat failed, fall through to full read */
+                /* stat failed, fall through to read */
             }
         }
-        const isImage = imageVisionProvider !== null && imageExtractor.isImageFile(filePath);
-        const ext = path.extname(filePath).toLowerCase();
-        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(ext) ||
-            docxExtractor.DOCX_EXTENSIONS.has(ext) ||
-            docExtractor.DOC_EXTENSIONS.has(ext) ||
-            excelExtractor.EXCEL_EXTENSIONS.has(ext) ||
-            isImage;
-        logger?.info(`Reading: ${filePath}`);
+        logger?.debug(`Reading: ${filePath}`);
         const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
         // For images, check the persistent description cache before calling the vision provider
         if (isImage && descCache && imageDescConfigHash) {
@@ -206,15 +243,39 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             logger?.info(`  Describing image: ${filePath}`);
         }
         const result = await dispatchExtraction(filePath, buffer, imageVisionProvider, imagePrompt, imageResizeMaxDimension);
-        // Cache the image description for future runs
+        // Cache the image description for future runs. Saves are throttled —
+        // a full cache rewrite per image was O(n²) I/O for image-heavy workspaces.
+        // The pipeline saves the cache again at the end of a pass.
         if (isImage && result.ok && descCache && imageDescConfigHash) {
             const imageBytesHash = computeFileHash(buffer.toString("base64"));
             const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
             descCache.set(cacheKey, result.content);
-            await descCache.save();
+            if (completed % 25 === 0) {
+                await descCache.save();
+            }
         }
         if (!result.ok) {
             logger?.warn(`  ${filePath} (extraction failed: ${result.error})`);
+            // A transient extraction failure (file lock, antivirus, timeout) must
+            // NOT delete a previously-good index entry. Report the file as
+            // unchanged with the OLD hash so the worker keeps the old chunks;
+            // the entry stays and the file is re-attempted on a later pass.
+            const previous = manifest?.files[normalizedPath];
+            if (previous) {
+                completed++;
+                return {
+                    filePath,
+                    normalizedPath,
+                    content: "",
+                    hash: previous.hash,
+                    isEmpty: false,
+                    isTooSmall: false,
+                    extractionStatus: "failed",
+                    extractionError: result.error,
+                    mtime: previous.mtime,
+                    size: previous.size,
+                };
+            }
         }
         const content = result.content;
         const byteLength = Buffer.byteLength(content, "utf-8");

package/dist/core/bootstrap.js

@@ -3,7 +3,7 @@
  * creates embedder, vector store, keyword index, and description provider.
  */
 import path from "node:path";
-import { loadConfig, findConfigFile, DEFAULT_CONFIG } from "./config.js";
+import { loadConfig, findConfigFile, resolveLogConfig, DEFAULT_CONFIG } from "./config.js";
 import { resolveApiKey } from "./resolve-api-key.js";
 import { loadChunkersFromConfig } from "../chunker/loader.js";
 import { createEmbedder } from "../embedder/factory.js";
@@ -21,6 +21,10 @@ async function probeDimension(embedder) {
     catch {
         // fallback to 384
     }
+    // A wrong dimension is only discovered later as cryptic LanceDB errors —
+    // surface the fallback loudly so misconfigured providers are easy to spot.
+    console.warn("[bootstrap] Could not probe embedding dimension — falling back to 384. " +
+        "If indexing later fails with dimension errors, set embedding.vectorDimension explicitly.");
     return 384;
 }
 /** Load the keyword index from disk, or create a new empty one if loading fails. */
@@ -50,9 +54,12 @@ export async function resolveRagContext(opts = {}) {
         await loadChunkersFromConfig(cfg, path.dirname(configPath));
     }
     else {
-        cfg = { ...DEFAULT_CONFIG };
+        // Deep-clone so resolveApiKey (below) cannot mutate the shared
+        // DEFAULT_CONFIG singleton.
+        cfg = structuredClone(DEFAULT_CONFIG);
+        resolveApiKey(cfg, workDir);
     }
-    const logFilePath = path.resolve(workDir, cfg.logging?.logFilePath ?? ".opencode/opencode-rag.log");
+    const logFilePath = path.resolve(workDir, resolveLogConfig(cfg).logFilePath);
     const embedder = createEmbedder(cfg);
     const dimension = opts.skipProbe ? 384 : await probeDimension(embedder);
     const storePath = path.resolve(workDir, cfg.vectorStore.path);

package/dist/core/config.js

@@ -378,6 +378,23 @@ export function validateConfig(config) {
     if (config.memory?.autoInjectTopK != null && config.memory.autoInjectTopK < 1) {
         warnings.push("memory.autoInjectTopK must be >= 1");
     }
+    if (config.memory?.minConfidence != null) {
+        const r = config.memory.minConfidence;
+        if (r < 0 || r > 1)
+            warnings.push("memory.minConfidence must be between 0 and 1");
+    }
+    if (config.memory?.autoCaptureDedupThreshold != null) {
+        const t = config.memory.autoCaptureDedupThreshold;
+        // > 1 would make dedup reject every candidate; < 0 disables it silently
+        if (t < 0 || t > 1)
+            warnings.push("memory.autoCaptureDedupThreshold must be between 0 and 1");
+    }
+    if (config.memory?.decay && config.memory.decay.halfLifeDays <= 0) {
+        warnings.push("memory.decay.halfLifeDays must be > 0");
+    }
+    if (config.openCode.maxReadOutputChars != null && config.openCode.maxReadOutputChars <= 0) {
+        warnings.push("openCode.maxReadOutputChars must be > 0");
+    }
     if (config.openCode.maxContextChunks <= 0) {
         warnings.push("openCode.maxContextChunks must be > 0");
     }
@@ -480,6 +497,14 @@ export function loadConfig(filePath, validate = true) {
                 ...DEFAULT_CONFIG.retrieval.hybridSearch,
                 ...(safeObj(parsed.retrieval?.hybridSearch) ?? {}),
             },
+            // contextOptimization MUST be nested-merged too — a shallow spread
+            // would replace the whole default object with a partial user object,
+            // silently leaving maxPerFile/mergeAdjacent/similarityThreshold etc.
+            // undefined (which disables the features via NaN comparisons).
+            contextOptimization: {
+                ...DEFAULT_CONFIG.retrieval.contextOptimization,
+                ...(safeObj(parsed.retrieval?.contextOptimization) ?? {}),
+            },
         },
         openCode: (() => {
             const base = DEFAULT_CONFIG.openCode;
@@ -528,6 +553,12 @@ export function loadConfig(filePath, validate = true) {
         memory: {
             ...DEFAULT_CONFIG.memory,
             ...(safeObj(parsed.memory) ?? {}),
+            // decay is a nested object — a user config with only
+            // `memory.decay.enabled` must not lose the halfLifeDays default.
+            decay: {
+                ...DEFAULT_CONFIG.memory.decay,
+                ...(safeObj((safeObj(parsed.memory) ?? {})?.decay) ?? {}),
+            },
         },
         ui: {
             ...DEFAULT_CONFIG.ui,

package/dist/core/desc-cache.d.ts

@@ -22,8 +22,14 @@ export declare class DescriptionCache {
     has(key: string): boolean;
     /** Persist the cache to disk if dirty. Safe to call multiple times. */
     save(): Promise<void>;
-    /** Build a cache key for a code chunk. */
-    static codeKey(content: string, descConfigHash: string): string;
+    /**
+     * Build a cache key for a code chunk.
+     *
+     * The optional `context` (relative path + line range) is included because
+     * the description prompt contains the file path — identical chunk content
+     * in two different files must not reuse a contextually wrong description.
+     */
+    static codeKey(content: string, descConfigHash: string, context?: string): string;
     /** Build a cache key for an image file. */
     static imageKey(imageBytesHash: string, imageDescConfigHash: string): string;
     /** Remove old entries to stay under the limit. */

package/dist/core/desc-cache.js

@@ -89,10 +89,17 @@ export class DescriptionCache {
         });
         return this.savePromise;
     }
-    /** Build a cache key for a code chunk. */
-    static codeKey(content, descConfigHash) {
+    /**
+     * Build a cache key for a code chunk.
+     *
+     * The optional `context` (relative path + line range) is included because
+     * the description prompt contains the file path — identical chunk content
+     * in two different files must not reuse a contextually wrong description.
+     */
+    static codeKey(content, descConfigHash, context) {
         const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
-        return contentHash + "_" + descConfigHash.slice(0, 16);
+        const contextHash = context ? createHash("sha256").update(context).digest("hex").slice(0, 8) : "";
+        return contentHash + "_" + descConfigHash.slice(0, 16) + (contextHash ? "_" + contextHash : "");
     }
     /** Build a cache key for an image file. */
     static imageKey(imageBytesHash, imageDescConfigHash) {

package/dist/core/doc-progress.js

@@ -47,17 +47,20 @@ export function markFileDocumented(storePath, filePath) {
 export function markSubdirectoryDocumented(storePath, subdir, allFilePaths) {
     const normalized = subdir.replace(/\\/g, "/").replace(/\/$/, "");
     const progress = loadDocProgress(storePath);
+    // Set lookups avoid the O(n·m) `includes` scan for large workspaces
+    const documentedSet = new Set(progress.documented);
     let changed = false;
     for (const filePath of allFilePaths) {
         const normalizedFile = filePath.replace(/\\/g, "/");
         if (normalizedFile.startsWith(normalized + "/") || normalizedFile === normalized) {
-            if (!progress.documented.includes(filePath)) {
-                progress.documented.push(filePath);
+            if (!documentedSet.has(filePath)) {
+                documentedSet.add(filePath);
                 changed = true;
             }
         }
     }
     if (changed) {
+        progress.documented = [...documentedSet];
         progress.lastUpdated = Date.now();
         saveDocProgress(storePath, progress);
     }

package/dist/core/provider-defaults.d.ts

@@ -19,3 +19,5 @@ export declare const PROVIDER_DEFAULTS: Record<string, ProviderDefaults>;
 export declare function getProviderDefault(provider: string): ProviderDefaults | undefined;
 /** Check whether a given provider uses an OpenAI-compatible API format. */
 export declare function isOpenAiCompatible(provider: string): boolean;
+/** Whether the given provider can produce embeddings. */
+export declare function supportsEmbedding(provider: string): boolean;

package/dist/core/provider-defaults.js

@@ -81,11 +81,26 @@ export const PROVIDER_DEFAULTS = {
 export function getProviderDefault(provider) {
     return PROVIDER_DEFAULTS[provider];
 }
+/** OpenAI-compatible providers (embedding + chat via /v1-style APIs). */
+const OPENAI_COMPATIBLE_PROVIDERS = new Set([
+    "openai",
+    "nvidia",
+    "azure",
+    "mistral",
+    "together",
+    "groq",
+    "deepseek",
+    "fireworks",
+]);
 /** Check whether a given provider uses an OpenAI-compatible API format. */
 export function isOpenAiCompatible(provider) {
-    if (provider === "ollama" || provider === "anthropic" || provider === "google" || provider === "cohere") {
-        return false;
-    }
-    return true;
+    // Only KNOWN OpenAI-compatible providers qualify — an unknown/typo'd
+    // provider name must fail fast instead of silently attempting
+    // OpenAI-style calls against a nonsense base URL.
+    return OPENAI_COMPATIBLE_PROVIDERS.has(provider);
+}
+/** Whether the given provider can produce embeddings. */
+export function supportsEmbedding(provider) {
+    return PROVIDER_DEFAULTS[provider]?.supportsEmbedding ?? false;
 }
 //# sourceMappingURL=provider-defaults.js.map

package/dist/core/runtime-overrides.d.ts

@@ -19,12 +19,6 @@ export interface RuntimeOverrides {
             debounceMs?: number;
             watcher?: string;
         };
-        autoInject?: {
-            enabled?: boolean;
-            minScore?: number;
-            maxChunks?: number;
-            contentType?: string;
-        };
     };
     embedding?: {
         provider?: string;

package/dist/core/version-check.d.ts

@@ -45,6 +45,11 @@ type NpmRunner = (command: string, options: {
 export declare function getCurrentVersion(): string;
 /**
  * Compare two semver-ish strings.
+ *
+ * Pre-release suffixes are stripped before comparison — "1.2.3-beta.1"
+ * must compare equal to "1.2.3" (parseInt would turn "3-beta.1" into 3,
+ * and non-numeric segments into NaN which compares equal).
+ *
  * @returns 1 if a > b, -1 if a < b, 0 if equal.
  */
 export declare function compareVersions(a: string, b: string): number;

package/dist/core/version-check.js

@@ -38,11 +38,17 @@ function normalizeVersion(tag) {
 }
 /**
  * Compare two semver-ish strings.
+ *
+ * Pre-release suffixes are stripped before comparison — "1.2.3-beta.1"
+ * must compare equal to "1.2.3" (parseInt would turn "3-beta.1" into 3,
+ * and non-numeric segments into NaN which compares equal).
+ *
  * @returns 1 if a > b, -1 if a < b, 0 if equal.
  */
 export function compareVersions(a, b) {
-    const pa = a.split(".").map((s) => parseInt(s, 10));
-    const pb = b.split(".").map((s) => parseInt(s, 10));
+    const clean = (s) => s.split("-", 1)[0] ?? s;
+    const pa = clean(a).split(".").map((s) => parseInt(s, 10));
+    const pb = clean(b).split(".").map((s) => parseInt(s, 10));
     for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
         const na = pa[i] ?? 0;
         const nb = pb[i] ?? 0;

package/dist/describer/anthropic.d.ts

@@ -25,8 +25,8 @@ export declare class AnthropicDescriptionProvider implements DescriptionProvider
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
     /**
      * Sends a request to the Anthropic Messages API with retry and exponential backoff.
-     * The system prompt is combined with all user messages into a single message payload, and
-     * the assistant placeholder is appended to elicit a completion.
+     * The system prompt is sent via the native `system` field (never concatenated into
+     * the user message, so chunk content cannot compete with it).
      *
      * @param messages - The user messages to send.
      * @param timeoutMs - Request timeout in milliseconds.

package/dist/describer/anthropic.js

@@ -59,8 +59,8 @@ export class AnthropicDescriptionProvider {
     }
     /**
      * Sends a request to the Anthropic Messages API with retry and exponential backoff.
-     * The system prompt is combined with all user messages into a single message payload, and
-     * the assistant placeholder is appended to elicit a completion.
+     * The system prompt is sent via the native `system` field (never concatenated into
+     * the user message, so chunk content cannot compete with it).
      *
      * @param messages - The user messages to send.
      * @param timeoutMs - Request timeout in milliseconds.
@@ -74,7 +74,8 @@ export class AnthropicDescriptionProvider {
         const body = {
             model: this.config.model,
             max_tokens: 4096,
-            messages: [{ role: "user", content: systemPrompt + "\n\n" + messages.map((m) => `${m.role}: ${m.content}`).join("\n\n") + "\n\nassistant:" }],
+            system: systemPrompt,
+            messages: messages.map((m) => ({ role: m.role, content: m.content })),
         };
         const headers = {
             "x-api-key": apiKey,
@@ -85,7 +86,20 @@ export class AnthropicDescriptionProvider {
         const retryBaseDelayMs = this.config.retryBaseDelayMs ?? 1000;
         let lastError;
         for (let attempt = 0; attempt <= retryMax; attempt++) {
-            const response = await postJson(`${baseUrl}/messages`, body, headers, timeoutMs, this.config.proxy);
+            let response;
+            try {
+                response = await postJson(`${baseUrl}/messages`, 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.content?.[0]?.text;
@@ -100,7 +114,7 @@ export class AnthropicDescriptionProvider {
                 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("Anthropic LLM request failed: unknown error");

package/dist/describer/describer.js

@@ -85,7 +85,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 +109,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/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