opencode-rag-plugin 1.22.2 → 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/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/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;

package/dist/core/config.js

@@ -444,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/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/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.

package/dist/mcp/handlers.d.ts

@@ -97,7 +97,7 @@ export interface DescribeImageResult {
     /** Human-readable formatted output with metadata. */
     formatted: string;
 }
-/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). */
+/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). Honors `imageDescription.onDemand` overrides. */
 export declare function handleDescribeImage(params: DescribeImageParams, cfg: RagConfig, worktree: string, visionProvider?: ImageVisionProvider): Promise<DescribeImageResult>;
 /** Find usages and references of a symbol across the indexed codebase using hybrid (keyword + vector) search. */
 export declare function handleFindUsages(params: FindUsagesParams, embedder: EmbeddingProvider, store: VectorStore, cfg: RagConfig, keywordIndex?: KeywordIndex, retrieveFn?: typeof retrieve): Promise<FindUsagesResult>;

package/dist/mcp/handlers.js

@@ -227,7 +227,7 @@ export async function handleFileSkeleton(params, worktree) {
     const formatted = `${skeleton.length} structural elements (${summary || "—"})\n\n${formatSkeleton(skeleton)}`;
     return { elements: skeleton, formatted, summary };
 }
-/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). */
+/** Describe an image file using the configured vision provider (Ollama, OpenAI, Anthropic, or Gemini). Honors `imageDescription.onDemand` overrides. */
 export async function handleDescribeImage(params, cfg, worktree, visionProvider) {
     const { existsSync, readFileSync } = await import("node:fs");
     const path = await import("node:path");
@@ -244,21 +244,22 @@ export async function handleDescribeImage(params, cfg, worktree, visionProvider)
     if (!imageDescriptionConfig?.enabled) {
         throw new Error("Image description is not enabled in config (imageDescription.enabled)");
     }
-    const { getMimeType } = await import("../chunker/image.js");
+    const { getMimeType, createImageVisionProvider, resolveOnDemandImageConfig } = await import("../chunker/image.js");
     const { resizeImage } = await import("../content/image.js");
+    const effectiveImageConfig = resolveOnDemandImageConfig(imageDescriptionConfig);
     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 = visionProvider ?? (await import("../chunker/image.js")).createImageVisionProvider(imageDescriptionConfig);
-    const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, params.systemPrompt);
+    const provider = visionProvider ?? createImageVisionProvider(effectiveImageConfig);
+    const description = await provider.describeImage(b64, mimeType, effectiveImageConfig.prompt, params.systemPrompt);
     const formatted = [
         `**Image description** — ${params.filePath}`,
         "",
         description,
         "",
-        `_Generated with ${imageDescriptionConfig.provider}/${imageDescriptionConfig.model}_`,
+        `_Generated with ${effectiveImageConfig.provider}/${effectiveImageConfig.model}_`,
     ].join("\n");
     return { description, formatted };
 }

package/dist/opencode/tools.d.ts

@@ -51,6 +51,9 @@ export interface DescribeImageToolOptions {
  * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
  * Google Gemini providers with automatic resizing.
  *
+ * On-demand calls honor the optional `imageDescription.onDemand` overrides
+ * (a different provider/model than the indexing pipeline).
+ *
  * @param options - Tool configuration including workspace root and vision provider.
  * @returns A tool definition suitable for OpenCode plugin registration.
  */

package/dist/opencode/tools.js

@@ -14,7 +14,7 @@
  */
 import { tool } from "@opencode-ai/plugin/tool";
 import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
-import { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, getMimeType } from "../chunker/image.js";
+import { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, resolveOnDemandImageConfig, getMimeType } from "../chunker/image.js";
 import { resizeImage } from "../content/image.js";
 import { retrieve } from "../retriever/retriever.js";
 import { Parser } from "web-tree-sitter";
@@ -247,6 +247,9 @@ export function createFileSkeletonTool(options) {
  * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
  * Google Gemini providers with automatic resizing.
  *
+ * On-demand calls honor the optional `imageDescription.onDemand` overrides
+ * (a different provider/model than the indexing pipeline).
+ *
  * @param options - Tool configuration including workspace root and vision provider.
  * @returns A tool definition suitable for OpenCode plugin registration.
  */
@@ -292,22 +295,23 @@ export function createDescribeImageTool(options) {
                         metadata: { tool: "describe_image", filePath: args.filePath, error: "disabled" },
                     };
                 }
+                const effectiveImageConfig = resolveOnDemandImageConfig(imageDescriptionConfig);
                 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 = visionProvider ?? createImageVisionProvider(imageDescriptionConfig);
-                const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, args.systemPrompt);
+                const provider = visionProvider ?? createImageVisionProvider(effectiveImageConfig);
+                const description = await provider.describeImage(b64, mimeType, effectiveImageConfig.prompt, args.systemPrompt);
                 return {
                     title: `Image description — ${args.filePath}`,
-                    output: `**${args.filePath}**\n\n${description}\n\n_Generated with ${imageDescriptionConfig.provider}/${imageDescriptionConfig.model}_`,
+                    output: `**${args.filePath}**\n\n${description}\n\n_Generated with ${effectiveImageConfig.provider}/${effectiveImageConfig.model}_`,
                     metadata: {
                         tool: "describe_image",
                         filePath: args.filePath,
                         description,
-                        provider: imageDescriptionConfig.provider,
-                        model: imageDescriptionConfig.model,
+                        provider: effectiveImageConfig.provider,
+                        model: effectiveImageConfig.model,
                     },
                 };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rag-plugin",
-  "version": "1.22.2",
+  "version": "1.23.0",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",