opencode-rag-plugin 1.22.1 → 1.23.0

package/ReadMe.md

@@ -189,7 +189,7 @@ opencode-rag mcp
 | `search_semantic` | Vector + keyword hybrid search across the indexed codebase |
 | `get_file_skeleton` | AST-based file outline (functions, classes, methods) |
 | `find_usages` | Find all references to a symbol by name |
-| `describe_image` | Return the pre-generated description for an indexed image file |
+| `describe_image` | Describe an image file with the configured vision model (`imageDescription.onDemand` overrides apply) |
 
 Clients can configure the MCP server manually, or `opencode-rag init` auto-registers it.
 
@@ -211,7 +211,7 @@ OpenCodeRAG registers tools that agents can invoke directly. Agents discover the
 | `search_semantic` | General-purpose code retrieval | Before any code task when you haven't read the relevant code |
 | `get_file_skeleton` | Quick file overview via AST | Before reading a large file to decide which sections matter |
 | `find_usages` | Symbol reference search | **Before editing** any function, variable, or class |
-| `describe_image` | Retrieve pre-generated image description | When a user asks about a screenshot, diagram, or visual asset |
+| `describe_image` | Live image description via the configured vision model | When a user asks about a screenshot, diagram, or visual asset |
 | `read` (optional) | RAG-enhanced file read | Full file contents with supplementary context chunks |
 
 ## OpenCode Integration

package/dist/chunker/image.d.ts

@@ -20,6 +20,20 @@ export declare function getMimeType(ext: string): string;
 export interface ImageVisionProvider {
     describeImage(imageBase64: string, mimeType: string, prompt: string, systemPrompt?: string, abort?: AbortSignal): Promise<string>;
 }
+/**
+ * Resolve the effective image-description configuration for on-demand
+ * `describe_image` calls (OpenCode plugin tool, MCP server, CLI
+ * `describe-image`).
+ *
+ * Applies the optional `imageDescription.onDemand` overrides on top of the
+ * indexing settings. The indexing pipeline always uses the base config and
+ * ignores `onDemand`. `null`/`undefined` override values are ignored so a
+ * partially written config cannot blank out required fields.
+ *
+ * @param config - The base image description configuration.
+ * @returns A copy with on-demand overrides applied and `onDemand` stripped.
+ */
+export declare function resolveOnDemandImageConfig(config: ImageDescriptionConfig): ImageDescriptionConfig;
 /**
  * Factory function that creates the appropriate {@link ImageVisionProvider}
  * implementation based on the `provider` field in the config.

package/dist/chunker/image.js

@@ -306,6 +306,32 @@ class GeminiImageVisionProvider {
         throw lastError;
     }
 }
+/**
+ * Resolve the effective image-description configuration for on-demand
+ * `describe_image` calls (OpenCode plugin tool, MCP server, CLI
+ * `describe-image`).
+ *
+ * Applies the optional `imageDescription.onDemand` overrides on top of the
+ * indexing settings. The indexing pipeline always uses the base config and
+ * ignores `onDemand`. `null`/`undefined` override values are ignored so a
+ * partially written config cannot blank out required fields.
+ *
+ * @param config - The base image description configuration.
+ * @returns A copy with on-demand overrides applied and `onDemand` stripped.
+ */
+export function resolveOnDemandImageConfig(config) {
+    const override = config.onDemand;
+    const resolved = { ...config };
+    delete resolved.onDemand;
+    if (!override)
+        return resolved;
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined || value === null)
+            continue;
+        resolved[key] = value;
+    }
+    return resolved;
+}
 /**
  * Factory function that creates the appropriate {@link ImageVisionProvider}
  * implementation based on the `provider` field in the config.

package/dist/cli/commands/describe-image.js

@@ -36,7 +36,7 @@ export function registerDescribeImageCommand(program) {
                 process.exit(1);
             }
             const ext = path.extname(resolvedPath).toLowerCase();
-            const { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, getMimeType } = await import("../../chunker/image.js");
+            const { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType } = await import("../../chunker/image.js");
             if (!SUPPORTED_IMAGE_EXTENSIONS.has(ext)) {
                 const exts = [...SUPPORTED_IMAGE_EXTENSIONS].join(", ");
                 logCliError(logFilePath, "describe-image", `\nUnsupported file extension "${ext}". Supported: ${exts}`, undefined);
@@ -48,16 +48,20 @@ export function registerDescribeImageCommand(program) {
                 process.exit(1);
             }
             const { resizeImage } = await import("../../content/image.js");
+            const effectiveImageConfig = resolveOnDemandImageConfig(imageDescriptionConfig);
             logCliInfo(logFilePath, "describe-image", `\n${c.heading("Describing image:")} ${c.file(filePath)}`);
-            logCliInfo(logFilePath, "describe-image", `  ${c.label("Provider:")} ${c.value(imageDescriptionConfig.provider)}`);
-            logCliInfo(logFilePath, "describe-image", `  ${c.label("Model:")}    ${c.value(imageDescriptionConfig.model)}`);
+            logCliInfo(logFilePath, "describe-image", `  ${c.label("Provider:")} ${c.value(effectiveImageConfig.provider)}`);
+            logCliInfo(logFilePath, "describe-image", `  ${c.label("Model:")}    ${c.value(effectiveImageConfig.model)}`);
+            if (imageDescriptionConfig.onDemand) {
+                logCliInfo(logFilePath, "describe-image", `  ${c.label("Source:")}   imageDescription.onDemand override`);
+            }
             const buffer = readFileSync(resolvedPath);
             const mimeType = getMimeType(ext);
-            const maxDimension = imageDescriptionConfig.resizeMaxDimension ?? 1024;
+            const maxDimension = effectiveImageConfig.resizeMaxDimension ?? 1024;
             const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
             const b64 = sized.toString("base64");
-            const provider = createImageVisionProvider(imageDescriptionConfig);
-            const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, options.systemPrompt);
+            const provider = createImageVisionProvider(effectiveImageConfig);
+            const description = await provider.describeImage(b64, mimeType, effectiveImageConfig.prompt, options.systemPrompt);
             logCliInfo(logFilePath, "describe-image", `\n${c.desc(description)}\n`);
             await cleanupContext(ctx);
         }

package/dist/cli/commands/index-command.js

@@ -98,6 +98,7 @@ export function registerIndexCommand(program) {
                 }
             }
             logCliInfo(logFilePath, "index", `${c.label("Scanning:")} ${c.file(cwd)}`);
+            let incomplete = false;
             const runPass = async (watchTriggered = false, abortSignal, filterPaths) => {
                 const passStarted = Date.now();
                 const stats = await runIndexPass({
@@ -116,6 +117,14 @@ export function registerIndexCommand(program) {
                 });
                 if (!watchTriggered) {
                     logIndexSummary(logFilePath, stats);
+                    if (stats.embeddingUnavailable) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.error("Indexing incomplete:")} the embedding provider was unavailable — nothing was stored. Fix the provider and run the index again.`);
+                    }
+                    else if (stats.totalChunks === 0 && stats.newFiles + stats.modifiedFiles > 0) {
+                        incomplete = true;
+                        logCliInfo(logFilePath, "index", `\n${c.warn("Indexing incomplete:")} files were processed but no chunks were stored. Check the log for details.`);
+                    }
                     logCliInfo(logFilePath, "index", `\n${c.success("Indexing complete.")} ${c.num(stats.finalCount)} chunks stored (${formatDuration(Date.now() - passStarted)}).`);
                 }
                 if (sigReceived && !watchTriggered) {
@@ -128,7 +137,7 @@ export function registerIndexCommand(program) {
             process.removeListener("SIGTERM", handleSigint);
             if (!options.watch) {
                 await cleanupContext(ctx);
-                process.exit(sigReceived ? 130 : 0);
+                process.exit(sigReceived ? 130 : incomplete ? 1 : 0);
             }
             // Only one watcher may run per workspace — a background auto-indexer
             // in an OpenCode session (or another `index --watch`) may already own

package/dist/cli/commands/init.js

@@ -261,7 +261,7 @@ export function registerInitCommand(program) {
                 const results = await healthPromise;
                 for (const r of results) {
                     const icon = r.status === "ok" ? c.success("✓") : r.status === "missing" ? c.warn("○") : c.error("✗");
-                    const typeLabel = r.type === "image_description" ? "image description" : r.type;
+                    const typeLabel = r.type === "image_description" ? "image description" : r.type === "image_description_on_demand" ? "image description (on-demand)" : r.type;
                     const label = `${typeLabel} model`;
                     console.log(`  ${icon} ${c.value(r.model)} (${r.provider}) — ${label}: ${r.status}`);
                     if (r.error)
@@ -280,6 +280,14 @@ export function registerInitCommand(program) {
                         if (r.type === "image_description" && ragConfig.imageDescription) {
                             return { model: r.model, baseUrl: ragConfig.imageDescription.baseUrl, proxy: ragConfig.imageDescription.proxy };
                         }
+                        if (r.type === "image_description_on_demand" && ragConfig.imageDescription) {
+                            const onDemand = ragConfig.imageDescription.onDemand;
+                            return {
+                                model: r.model,
+                                baseUrl: onDemand?.baseUrl ?? ragConfig.imageDescription.baseUrl,
+                                proxy: onDemand?.proxy ?? ragConfig.imageDescription.proxy,
+                            };
+                        }
                         return { model: r.model, baseUrl: ragConfig.embedding.baseUrl, proxy: ragConfig.embedding.proxy };
                     });
                     console.log(`\n  ${c.warn("Models not found:")} ${pullEntries.map((e) => e.model).join(", ")}`);

package/dist/cli/commands/status.js

@@ -75,6 +75,20 @@ export function registerStatusCommand(program) {
             logCliInfo(logFilePath, "status", `${c.label("Store path:")}        ${c.file(storePath)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
             logCliInfo(logFilePath, "status", `${c.label("Embedding model:")}   ${c.value(config.embedding.model)}`);
+            const storeDimension = await store.getVectorDimension?.();
+            const embedderDimension = config.embedding.vectorDimension;
+            if (embedderDimension && embedderDimension > 0) {
+                logCliInfo(logFilePath, "status", `${c.label("Embedder dim:")}      ${c.num(embedderDimension)}`);
+            }
+            if (storeDimension !== undefined) {
+                logCliInfo(logFilePath, "status", `${c.label("Store dimension:")}   ${c.num(storeDimension)}`);
+            }
+            if (storeDimension !== undefined &&
+                embedderDimension !== undefined &&
+                embedderDimension > 0 &&
+                storeDimension !== embedderDimension) {
+                logCliInfo(logFilePath, "status", `${c.label("Dimension mismatch:")} ${c.warn("yes")} — the store was built with a different embedding model. Run 'opencode-rag index' to rebuild.`);
+            }
             logCliInfo(logFilePath, "status", `${c.label("File extensions:")}   ${config.indexing.includeExtensions.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Excluded dirs:")}     ${config.indexing.excludeDirs.join(", ")}`);
             logCliInfo(logFilePath, "status", `${c.label("Default top-K:")}     ${c.num(config.retrieval.topK)}`);

package/dist/cli/format.js

@@ -92,7 +92,7 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
         configPath: opt.config,
         ...bootstrapOpts,
     });
-    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.logFilePath)}`);
+    logCliInfo(logFilePath, "config", `${c.label("Config:")} ${c.file(ctx.configPath ?? "(built-in defaults)")}`);
     logConfigDetails(logFilePath, ctx.config);
     return ctx;
 }
@@ -105,6 +105,9 @@ export async function resolveCliContext(opt, logFilePath, bootstrapOpts) {
 function logConfigDetails(logFilePath, config) {
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding provider:")} ${c.value(config.embedding.provider)}`);
     logCliInfo(logFilePath, "config", `  ${c.label("Embedding model:")}    ${c.value(config.embedding.model)}`);
+    if (config.embedding.vectorDimension && config.embedding.vectorDimension > 0) {
+        logCliInfo(logFilePath, "config", `  ${c.label("Embedding dim:")}      ${c.num(config.embedding.vectorDimension)}`);
+    }
     logCliInfo(logFilePath, "config", `  ${c.label("Vector store:")}       ${c.file(config.vectorStore.path)}`);
 }
 /**
@@ -153,7 +156,13 @@ export function logIndexSummary(logFilePath, stats) {
     if (stats.descriptionFailedFiles > 0) {
         logCliInfo(logFilePath, "index", `  ${c.label("Desc failed:")}     ${c.num(stats.descriptionFailedFiles)}`);
     }
+    if (stats.embeddingFailures > 0) {
+        logCliInfo(logFilePath, "index", `  ${c.label("Embed failed:")}    ${c.num(stats.embeddingFailures)} chunk(s) without vectors — retried next pass`);
+    }
     logCliInfo(logFilePath, "index", `  ${c.label("Chunks written:")}   ${c.num(stats.totalChunks)}`);
+    if (stats.embeddingUnavailable) {
+        logCliInfo(logFilePath, "index", `  ${c.error("Embedding provider unavailable during this pass — no chunks were stored.")}`);
+    }
 }
 /**
  * Format a millisecond duration into a compact human-readable string.

package/dist/core/bootstrap.d.ts

@@ -35,6 +35,8 @@ export interface RagContext {
     dimension: number;
     /** Resolved path to the debug log file. */
     logFilePath: string;
+    /** Resolved path to the config file, or undefined when built-in defaults are used. */
+    configPath?: string;
 }
 /** Bootstrap the full RAG pipeline context: load config, resolve API keys, create embedder, vector store, keyword index, and description provider. */
 export declare function resolveRagContext(opts?: BootstrapOptions): Promise<RagContext>;

package/dist/core/bootstrap.js

@@ -6,26 +6,46 @@ import path from "node:path";
 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";
+import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
 import { createDescriptionProvider } from "../describer/factory.js";
 import { createVectorStore } from "../vectorstore/factory.js";
+import { readStoreDimension } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
-/** Probe the embedding provider to determine the vector dimension. Falls back to 384 on failure. */
-async function probeDimension(embedder) {
-    try {
-        const probe = await embedder.embed(["dimension-probe"], "query");
-        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-            return probe[0].length;
-        }
+/**
+ * Resolve the embedding dimension for the store.
+ *
+ * Precedence: an explicit `embedding.vectorDimension` in the config wins (it
+ * is persisted after the first successful probe), then a live probe of the
+ * provider, then the dimension of an existing store table, then the 384
+ * fallback. The old behavior always probed and fell back to 384 — which
+ * silently created 384-dimensional stores whenever the provider was down,
+ * even though the config declared the real dimension.
+ *
+ * @param embedder - Configured embedding provider (probed only when needed).
+ * @param storePath - Vector store path, used to read an existing schema.
+ * @param skipProbe - When true, never call the provider (read-only commands).
+ * @returns The resolved dimension.
+ */
+async function resolveDimension(embedder, storePath, skipProbe, configured) {
+    if (configured && configured > 0) {
+        return configured;
     }
-    catch {
-        // fallback to 384
+    if (!skipProbe) {
+        const probe = await probeEmbeddingDimension(embedder);
+        if (probe.dimension !== undefined) {
+            return probe.dimension;
+        }
+        const storeDimension = await readStoreDimension(storePath);
+        if (storeDimension !== undefined) {
+            console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+                `using the existing store's dimension ${storeDimension}.`);
+            return storeDimension;
+        }
+        console.warn(`[bootstrap] Could not probe embedding dimension (${probe.error?.message ?? "unknown error"}) — ` +
+            "falling back to 384. Set embedding.vectorDimension explicitly if the provider produces a different size.");
+        return 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;
+    return (await readStoreDimension(storePath)) ?? 384;
 }
 /** Load the keyword index from disk, or create a new empty one if loading fails. */
 async function loadKeywordIndex(storePath) {
@@ -61,8 +81,16 @@ export async function resolveRagContext(opts = {}) {
     }
     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);
+    const dimension = await resolveDimension(embedder, storePath, opts.skipProbe ?? false, cfg.embedding.vectorDimension);
+    // Warn (but do not block) when the existing store schema disagrees with the
+    // resolved dimension: the next index pass rebuilds automatically, and search
+    // callers would otherwise see only cryptic LanceDB errors.
+    const storeDimension = await readStoreDimension(storePath);
+    if (storeDimension !== undefined && storeDimension !== dimension) {
+        console.warn(`[bootstrap] Store was built with vector dimension ${storeDimension} but the current embedder produces ${dimension} — ` +
+            "run 'opencode-rag index' to rebuild the index with the current model.");
+    }
     const store = createVectorStore(cfg, storePath, dimension);
     const keywordIndex = opts.skipKeywordIndex
         ? new KeywordIndex(storePath)
@@ -80,6 +108,7 @@ export async function resolveRagContext(opts = {}) {
         descriptionProvider,
         dimension,
         logFilePath,
+        configPath,
     };
 }
 //# sourceMappingURL=bootstrap.js.map

package/dist/core/config.d.ts

@@ -85,6 +85,36 @@ export interface DescriptionConfig {
     maxContentChars?: number;
 }
 /** Configuration for vision-model-based image description generation. */
+/**
+ * Optional overrides for on-demand `describe_image` calls (OpenCode plugin
+ * tool, MCP server, CLI `describe-image`). Fields omitted here fall back to
+ * the indexing settings in {@link ImageDescriptionConfig}; the indexing
+ * pipeline itself always uses the base settings.
+ */
+export interface ImageDescriptionOnDemandConfig {
+    /** Vision provider name ("ollama", "openai", "anthropic", "google"). */
+    provider?: string;
+    /** Vision model name. */
+    model?: string;
+    /** Base URL of the vision API. */
+    baseUrl?: string;
+    /** API key for providers that require authentication. */
+    apiKey?: string;
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Prompt template sent to the vision model. */
+    prompt?: string;
+    /** Whether to include chain-of-thought tokens. */
+    think?: boolean;
+    /** Context window size. */
+    numCtx?: number;
+    /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/chat requests. */
+    keepAlive?: string;
+    /** Proxy configuration. */
+    proxy?: ProxyConfig;
+    /** Maximum image dimension (pixels) — larger images are resized before sending. */
+    resizeMaxDimension?: number;
+}
 export interface ImageDescriptionConfig {
     /** Whether image description is enabled. */
     enabled: boolean;
@@ -110,8 +140,13 @@ export interface ImageDescriptionConfig {
     proxy?: ProxyConfig;
     /** Maximum image dimension (pixels) — larger images are resized before sending. */
     resizeMaxDimension?: number;
+    /**
+     * Optional overrides for on-demand `describe_image` calls (OpenCode plugin
+     * tool, MCP server, CLI `describe-image`). Omitted fields fall back to the
+     * indexing settings above. The indexing pipeline ignores this section.
+     */
+    onDemand?: ImageDescriptionOnDemandConfig;
 }
-/** Configuration for the built-in web dashboard UI. */
 export interface UiConfig {
     /** HTTP port for the UI server. */
     port: number;
@@ -296,6 +331,18 @@ export interface RagConfig {
         ollamaMaxBatchSize?: number;
         /** Maximum concurrent description generation requests. */
         descriptionConcurrency?: number;
+        /**
+         * Include LLM-generated chunk descriptions in the text that gets embedded.
+         *
+         * Descriptions help general-purpose embedding models align natural-language
+         * queries with raw code. Code-specialized models (e.g. jina-code-embeddings,
+         * trained for NL→code retrieval with instruction prefixes) do not need the
+         * crutch — and their passage prompt expects a code snippet, not prose.
+         * When false, descriptions are still generated and stored (search results,
+         * web UI), but only path/meta header/content are embedded.
+         * @default true
+         */
+        embedDescriptions?: boolean;
         /**
          * Maximum file size in bytes for SVG/XML files before chunking is skipped.
          * Large SVGs can cause tree-sitter to hang. Set to 0 for no limit.

package/dist/core/config.js

@@ -117,6 +117,7 @@ export const DEFAULT_CONFIG = {
         embedConcurrency: 3,
         ollamaMaxBatchSize: 100,
         descriptionConcurrency: 4,
+        embedDescriptions: true,
         maxSvgSizeBytes: 1_048_576,
         optimizeIntervalWindows: 8,
     },
@@ -443,6 +444,10 @@ export function validateConfig(config) {
                 warnings.push("imageDescription.timeoutMs must be > 0");
             }
         }
+        const onDemand = config.imageDescription.onDemand;
+        if (onDemand?.timeoutMs !== undefined && onDemand.timeoutMs <= 0) {
+            warnings.push("imageDescription.onDemand.timeoutMs must be > 0");
+        }
     }
     return { valid: warnings.length === 0, warnings };
 }

package/dist/core/interfaces.d.ts

@@ -224,6 +224,14 @@ export interface VectorStore {
      * Used by the index pipeline to detect silent corruption before scanning.
      */
     checkIntegrity?(): Promise<boolean>;
+    /**
+     * Return the actual embedding dimension of the stored vector column, or
+     * `undefined` when the store has no table yet. Used to detect a store that
+     * was built with a different embedding model than the currently configured
+     * one — a mismatch makes every vector search fail and silently corrupts
+     * writes, so the pipeline rebuilds the index instead.
+     */
+    getVectorDimension?(): Promise<number | undefined>;
 }
 /** Filter criteria for narrowing search results by file path, language, kind, or extension. */
 export interface MetadataFilter {

package/dist/core/resolve-api-key.js

@@ -14,6 +14,11 @@ export function resolveApiKey(cfg, worktree) {
     if (cfg.imageDescription?.enabled && cfg.imageDescription.provider !== "ollama") {
         resolveForSection(cfg.imageDescription.provider, cfg.imageDescription, worktree);
     }
+    const imageOnDemand = cfg.imageDescription?.onDemand;
+    if (imageOnDemand) {
+        const provider = imageOnDemand.provider ?? cfg.imageDescription?.provider ?? "ollama";
+        resolveForSection(provider, imageOnDemand, worktree);
+    }
 }
 function isPlaceholder(value) {
     return value === "public" || value === "" || value === "PLACEHOLDER";

package/dist/embedder/factory.d.ts

@@ -15,6 +15,26 @@ import type { RagConfig } from "../core/config.js";
  * @throws If the provider is unsupported or a required apiKey is not set
  */
 export declare function createEmbedder(config: RagConfig): EmbeddingProvider;
+/** Result of probing an embedding provider for its output dimension. */
+export interface EmbeddingProbeResult {
+    /** Detected vector dimension, or `undefined` when the probe failed. */
+    dimension?: number;
+    /** Error raised by the provider (or an empty response), when the probe failed. */
+    error?: Error;
+}
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Promise<EmbeddingProbeResult>;
 /**
  * Embed a list of texts in batches with optional concurrency control and per-batch retry.
  *

package/dist/embedder/factory.js

@@ -40,6 +40,30 @@ export function createEmbedder(config) {
     }
     throw new Error(`Unknown embedding provider: ${provider}`);
 }
+/**
+ * Probe an embedding provider with a single short text to discover the
+ * dimension of the vectors it produces.
+ *
+ * Used as a health/dimension preflight before expensive index work: a provider
+ * that is down (server not running, model not pulled) fails here in
+ * milliseconds instead of after chunking and describing every file. Errors are
+ * captured in the result rather than thrown.
+ *
+ * @param embedder - The embedding provider to probe.
+ * @returns The detected dimension, or the failure reason.
+ */
+export async function probeEmbeddingDimension(embedder) {
+    try {
+        const probe = await embedder.embed(["dimension-probe"], "query");
+        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
+            return { dimension: probe[0].length };
+        }
+        return { error: new Error("Embedding provider returned an empty probe vector") };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err : new Error(String(err)) };
+    }
+}
 /**
  * HTTP statuses that indicate a permanent failure — retrying cannot help
  * (auth errors, bad requests, missing resources). Providers raise these as

package/dist/embedder/health.d.ts

@@ -10,7 +10,7 @@ export interface HealthCheckResult {
     /** Model identifier that was tested */
     model: string;
     /** Which capability was checked */
-    type: "embedding" | "description" | "image_description";
+    type: "embedding" | "description" | "image_description" | "image_description_on_demand";
     /** Whether the provider is reachable and the model is available */
     status: "ok" | "missing" | "error";
     /** Human-readable error message when status is not "ok" */

package/dist/embedder/health.js

@@ -1,3 +1,4 @@
+import { resolveOnDemandImageConfig } from "../chunker/image.js";
 import { fetchWithProxy, postJson } from "./http.js";
 /**
  * Check connectivity and model availability for all configured providers.
@@ -13,6 +14,10 @@ export async function checkProviderHealth(config) {
     }
     if (config.imageDescription?.enabled) {
         checks.push(checkImageDescriptionModel(config, timeoutMs));
+        const onDemand = resolveOnDemandImageConfig(config.imageDescription);
+        if (onDemand.provider !== config.imageDescription.provider || onDemand.model !== config.imageDescription.model) {
+            checks.push(checkOnDemandImageDescriptionModel(onDemand));
+        }
     }
     return Promise.all(checks);
 }
@@ -56,19 +61,27 @@ async function checkImageDescriptionModel(config, _timeoutMs) {
     if (!img) {
         return { provider: "unknown", model: "unknown", type: "image_description", status: "error", error: "Image description config is undefined" };
     }
+    return checkVisionModel(img, "image_description");
+}
+/** Check the optional `imageDescription.onDemand` vision model used by the describe_image tool, MCP server, and CLI. */
+async function checkOnDemandImageDescriptionModel(img) {
+    return checkVisionModel(img, "image_description_on_demand");
+}
+/** Dispatch a vision-model check (indexing or on-demand) to the correct provider-specific handler. */
+async function checkVisionModel(img, type) {
     const { provider, baseUrl, model, apiKey } = img;
     const imgTimeout = img.timeoutMs ?? 60000;
     if (provider === "ollama") {
-        return checkOllamaChat(baseUrl, model, imgTimeout, img.proxy, "image_description");
+        return checkOllamaChat(baseUrl, model, imgTimeout, img.proxy, type);
     }
     if (provider === "anthropic") {
-        return checkAnthropicChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
+        return checkAnthropicChat(baseUrl, model, apiKey, imgTimeout, img.proxy, type);
     }
     if (provider === "google") {
-        return checkGoogleChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
+        return checkGoogleChat(baseUrl, model, apiKey, imgTimeout, img.proxy, type);
     }
     // OpenAI-compatible chat endpoint
-    return checkOpenAiChat(baseUrl, model, apiKey, imgTimeout, img.proxy, "image_description");
+    return checkOpenAiChat(baseUrl, model, apiKey, imgTimeout, img.proxy, type);
 }
 /** Check whether a provider name matches a known OpenAI-compatible provider. */
 function isOpenAiCompatible(provider) {

package/dist/index.d.ts

@@ -14,9 +14,9 @@ export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/conte
 export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
 export { createBackgroundIndexer } from "./watcher.js";
 export { createWatchIgnore } from "./indexer.js";
-export { ImageChunker, createImageVisionProvider, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
+export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
 export { DescriptionCache } from "./core/desc-cache.js";
-export type { RagConfig, DescriptionConfig, ImageDescriptionConfig } from "./core/config.js";
+export type { RagConfig, DescriptionConfig, ImageDescriptionConfig, ImageDescriptionOnDemandConfig } from "./core/config.js";
 export type { Chunk, SearchResult, OptimizedSearchResult, Chunker, DescriptionProvider, EmbeddingProvider, VectorStore } from "./core/interfaces.js";
 export type { ContextOptimizationConfig, ContextOptimizationOptions } from "./retriever/context-optimizer.js";
 /**

package/dist/index.js

@@ -14,7 +14,7 @@ export { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/conte
 export { loadConfig, DEFAULT_CONFIG } from "./core/config.js";
 export { createBackgroundIndexer } from "./watcher.js";
 export { createWatchIgnore } from "./indexer.js";
-export { ImageChunker, createImageVisionProvider, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
+export { ImageChunker, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType, SUPPORTED_IMAGE_EXTENSIONS } from "./chunker/image.js";
 export { DescriptionCache } from "./core/desc-cache.js";
 /**
  * High-level convenience API — search, index, and retrieve context in a single function call.