opencode-rag-plugin 1.22.2 → 1.23.1

package/ReadMe.md

@@ -81,7 +81,7 @@ Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for deta
 
 OpenCodeRAG can index image files (PNG, JPEG, WebP, etc.) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable via natural language queries (e.g., "login screen screenshot", "architecture diagram").
 
-**Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini compatible providers.
+**Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode`/`opencode-go`) compatible providers.
 
 **Disabled by default** — enable in `opencode-rag.json` to opt in (recommended for dedicated GPUs).
 
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Image file chunking via vision provider integration (Ollama, OpenAI, Anthropic, Gemini).
+ * @fileoverview Image file chunking via vision provider integration (Ollama, OpenAI, Anthropic, Gemini, OpenCode Zen).
  */
 import type { Chunker, Chunk } from "../core/interfaces.js";
 import type { ImageDescriptionConfig } from "../core/config.js";
@@ -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

@@ -1,5 +1,7 @@
 import { normalizeKeepAlive } from "../core/ollama.js";
 import { postJson } from "../embedder/http.js";
+import { getCurrentVersion } from "../core/version-check.js";
+import { isZenProvider, resolveZenBaseUrl } from "../core/zen.js";
 import { uuid } from "./uuid.js";
 const MAX_CHUNK_CHARS = 4000;
 const MIN_GROUP_CHARS = 300;
@@ -7,6 +9,15 @@ const PARAGRAPH_SPLIT = /\n\s*\n/;
 const VISION_RETRY_MAX = 2;
 const VISION_RETRY_BASE_DELAY_MS = 1000;
 const VISION_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** Stable per-process session id so Zen can route and cache prompts per client. */
+const ZEN_SESSION_ID = uuid();
+/** Headers sent with every OpenCode Zen vision request. */
+function zenRequestHeaders() {
+    return {
+        "x-opencode-session": ZEN_SESSION_ID,
+        "User-Agent": `opencode-rag/${getCurrentVersion()}`,
+    };
+}
 function visionSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -106,12 +117,14 @@ class OpenAIImageVisionProvider {
     model;
     apiKey;
     timeoutMs;
+    extraHeaders;
     proxy;
-    constructor(config) {
+    constructor(config, extraHeaders) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, "");
         this.model = config.model;
         this.apiKey = config.apiKey ?? "";
         this.timeoutMs = config.timeoutMs;
+        this.extraHeaders = extraHeaders ?? {};
         this.proxy = config.proxy;
     }
     async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
@@ -136,6 +149,7 @@ class OpenAIImageVisionProvider {
             max_tokens: 2048,
         };
         const headers = {
+            ...this.extraHeaders,
             "Content-Type": "application/json",
         };
         if (this.apiKey) {
@@ -250,7 +264,7 @@ class GeminiImageVisionProvider {
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, "");
         this.model = config.model;
-        this.apiKey = config.apiKey;
+        this.apiKey = config.apiKey ?? "";
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
@@ -306,6 +320,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.
@@ -329,6 +369,13 @@ export function createImageVisionProvider(config) {
         }
         return new OpenAIImageVisionProvider(config);
     }
+    if (isZenProvider(config.provider)) {
+        if (!config.apiKey) {
+            throw new Error(`${config.provider} image provider requires an apiKey — log in with OpenCode (auth.json) or set it in the config`);
+        }
+        const baseUrl = resolveZenBaseUrl(config.baseUrl, config.provider);
+        return new OpenAIImageVisionProvider({ ...config, baseUrl }, zenRequestHeaders());
+    }
     return new OllamaImageVisionProvider(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";
@@ -23,12 +28,13 @@ function resolveForSection(provider, section, worktree) {
     if (section.apiKey && !isPlaceholder(section.apiKey))
         return;
     const defaults = getProviderDefault(provider);
-    if (!defaults || !defaults.apiKeyEnvVar)
-        return;
-    const envKey = process.env[defaults.apiKeyEnvVar];
-    if (envKey) {
-        section.apiKey = envKey;
-        return;
+    const envVar = defaults?.apiKeyEnvVar;
+    if (envVar) {
+        const envKey = process.env[envVar];
+        if (envKey) {
+            section.apiKey = envKey;
+            return;
+        }
     }
     if (worktree) {
         const key = readOpenCodeProviderKey(worktree, provider);
@@ -37,9 +43,38 @@ function resolveForSection(provider, section, worktree) {
             return;
         }
     }
+    const authKey = readOpenCodeAuthKey(provider);
+    if (authKey) {
+        section.apiKey = authKey;
+        return;
+    }
     // If we had a placeholder but couldn't resolve a real key, keep the placeholder
     // so createEmbedder can throw a clear error about the missing key
 }
+/**
+ * Read an API key from OpenCode's auth store (`$XDG_DATA_HOME/opencode/auth.json`
+ * or `~/.local/share/opencode/auth.json`). This is where `/connect` stores keys
+ * for providers such as OpenCode Zen (`opencode`, `opencode-go`).
+ */
+function readOpenCodeAuthKey(providerId) {
+    const homeDir = process.env.USERPROFILE || process.env.HOME;
+    const dataHome = process.env.XDG_DATA_HOME?.trim() || (homeDir ? path.join(homeDir, ".local", "share") : undefined);
+    if (!dataHome)
+        return undefined;
+    const authPath = path.join(dataHome, "opencode", "auth.json");
+    try {
+        if (!existsSync(authPath))
+            return undefined;
+        const auth = JSON.parse(readFileSync(authPath, "utf-8"));
+        const entry = auth[providerId];
+        if (entry && entry.type === "api" && entry.key)
+            return entry.key;
+    }
+    catch {
+        // skip unreadable or unparseable auth stores
+    }
+    return undefined;
+}
 function stripJsoncComments(text) {
     return text.replace(/("[^"\\]*(?:\\.[^"\\]*)*")|(\/\/[^\n]*|\/\*[\s\S]*?\*\/)/g, (_, string) => string ?? "");
 }

package/dist/core/zen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview OpenCode Zen provider helpers — provider detection, chat-completion
+ * base URLs, and base-URL resolution for the OpenAI-compatible Zen endpoints.
+ */
+/** OpenCode Zen chat-completion base URLs by provider id. */
+export declare const ZEN_PROVIDER_BASE_URLS: Record<string, string>;
+/** Whether the provider id refers to an OpenCode Zen endpoint. */
+export declare function isZenProvider(provider: string): boolean;
+/**
+ * Pick the Zen base URL for a Zen provider. Configured URLs that point at an
+ * `opencode.ai` host are kept (alternate Zen endpoints); anything else — e.g.
+ * the Ollama/llama.cpp base inherited from the indexing section — is replaced
+ * by the provider default.
+ */
+export declare function resolveZenBaseUrl(configuredBaseUrl: string | undefined, provider: string): string;

package/dist/core/zen.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview OpenCode Zen provider helpers — provider detection, chat-completion
+ * base URLs, and base-URL resolution for the OpenAI-compatible Zen endpoints.
+ */
+/** OpenCode Zen chat-completion base URLs by provider id. */
+export const ZEN_PROVIDER_BASE_URLS = {
+    opencode: "https://opencode.ai/zen/v1",
+    "opencode-go": "https://opencode.ai/zen/go/v1",
+};
+/** Whether the provider id refers to an OpenCode Zen endpoint. */
+export function isZenProvider(provider) {
+    return provider in ZEN_PROVIDER_BASE_URLS;
+}
+/**
+ * Pick the Zen base URL for a Zen provider. Configured URLs that point at an
+ * `opencode.ai` host are kept (alternate Zen endpoints); anything else — e.g.
+ * the Ollama/llama.cpp base inherited from the indexing section — is replaced
+ * by the provider default.
+ */
+export function resolveZenBaseUrl(configuredBaseUrl, provider) {
+    const configured = (configuredBaseUrl ?? "").trim();
+    if (configured.includes("opencode.ai"))
+        return configured;
+    return ZEN_PROVIDER_BASE_URLS[provider] ?? configured;
+}
+//# sourceMappingURL=zen.js.map

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,5 @@
+import { resolveOnDemandImageConfig } from "../chunker/image.js";
+import { isZenProvider, resolveZenBaseUrl } from "../core/zen.js";
 import { fetchWithProxy, postJson } from "./http.js";
 /**
  * Check connectivity and model availability for all configured providers.
@@ -13,6 +15,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 +62,29 @@ 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");
+    // OpenAI-compatible chat endpoint (OpenCode Zen providers default to their
+    // own base URL when the config still carries the indexing section's URL)
+    const openAiBaseUrl = isZenProvider(provider) ? resolveZenBaseUrl(baseUrl, provider) : baseUrl;
+    return checkOpenAiChat(openAiBaseUrl, 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, Gemini, or OpenCode Zen). 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, Gemini, or OpenCode Zen). 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/mcp/server.js

@@ -74,7 +74,7 @@ export async function createMcpServer(options) {
             };
         }
     });
-    server.tool("describe_image", "Describe an image file using a vision model. Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, or Google Gemini), and returns a text description of the image contents. Optionally accepts a systemPrompt to steer the description toward specific features.", {
+    server.tool("describe_image", "Describe an image file using a vision model. Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, Google Gemini, or OpenCode Zen), and returns a text description of the image contents. Optionally accepts a systemPrompt to steer the description toward specific features.", {
         filePath: z.string().min(1, "An image file path is required."),
         systemPrompt: z.string().optional(),
     }, async (args) => {

package/dist/opencode/tools.d.ts

@@ -48,8 +48,11 @@ export interface DescribeImageToolOptions {
  * Create the `describe_image` tool.
  *
  * Reads an image file from disk and sends it to the configured vision provider
- * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
- * Google Gemini providers with automatic resizing.
+ * for natural-language description. Supports Ollama, OpenAI, Anthropic,
+ * Google Gemini, and OpenCode Zen 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";
@@ -244,8 +244,11 @@ export function createFileSkeletonTool(options) {
  * Create the `describe_image` tool.
  *
  * Reads an image file from disk and sends it to the configured vision provider
- * for natural-language description. Supports Ollama, OpenAI, Anthropic, and
- * Google Gemini providers with automatic resizing.
+ * for natural-language description. Supports Ollama, OpenAI, Anthropic,
+ * Google Gemini, and OpenCode Zen 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.
@@ -254,7 +257,7 @@ export function createDescribeImageTool(options) {
     const { worktree, config, visionProvider } = options;
     return tool({
         description: "Describe an image file using a vision model. " +
-            "Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, or Google Gemini), " +
+            "Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, Google Gemini, or OpenCode Zen), " +
             "and returns a natural language description of what the image shows. " +
             "Optionally accepts a `systemPrompt` to steer the description toward specific features or details you care about " +
             "(e.g. colors, layout, accessibility, text content, specific UI elements). " +
@@ -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.1",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",