opencode-see-image 0.9.2 → 0.10.0

package/.claude/settings.local.json

@@ -12,7 +12,15 @@
       "Read(//Users/alfa/Documents/opencodeprojects/opencode-see-image/bun-types/**)",
       "Bash(bun run *)",
       "WebFetch(domain:docs.z.ai)",
-      "Bash(npm publish *)"
+      "Bash(npm publish *)",
+      "Bash(python3 -c ' *)",
+      "Bash(open -a Preview \"/Users/alfa/.claude/image-cache/31fd2007-9418-45bb-a3e5-d273327f5f78/3.png\" \"/Users/alfa/.claude/image-cache/31fd2007-9418-45bb-a3e5-d273327f5f78/4.png\" \"/Users/alfa/.claude/image-cache/31fd2007-9418-45bb-a3e5-d273327f5f78/5.png\")",
+      "Bash(ps -o etime= -p 82196)",
+      "Bash(echo \"STILL RUNNING \\($\\(ps -o etime= -p 82196)",
+      "Bash(awk '/export type TextPart = \\\\{/,/\\\\};/' node_modules/@opencode-ai/sdk/dist/gen/types.gen.d.t)",
+      "Bash(awk '{print $2, $9, $11, $12, $13}')",
+      "Bash(pkill -f \"[o]pencode run\")",
+      "Bash(pkill -f \"[o]pencode-run\")"
     ]
   }
 }

package/README.md

@@ -1,18 +1,18 @@
 # opencode-see-image
 
-Give non-vision opencode models the ability to **see images and screenshots** by routing them to a vision-capable model.
+give non-vision opencode models the ability to see images and screenshots by routing them to a vision-capable model.
 
-When a user attaches a screenshot to a text-only model, opencode rejects it with an error. This plugin intercepts that flow by registering a `see_image` tool that sends the image to a vision model and returns a textual description the primary model can reason about.
+when a user attaches a screenshot to a text-only model, opencode rejects it with an error. This plugin intercepts that flow by registering a `see_image` tool that sends the image to a vision model and returns a textual description the primary model can reason about.
 
-## Install
+## install
 
-**Option A, one command (recommended):**
+**one command (recommended):**
 ```bash
 opencode plugin opencode-see-image --global
 ```
 This installs the package and adds it to your config. Then restart opencode.
 
-**Option B, edit config manually:**
+**edit config manually:**
 
 Add the plugin to your opencode config:
 
@@ -25,76 +25,76 @@ Add the plugin to your opencode config:
 ```
 Then restart opencode.
 
-## Install via your agent
+## install via your agent (for some reason?)
 
-Ask your agent:
+ask your agent:
 ```
 install the opencode-see-image plugin
 ```
-It'll run `opencode plugin opencode-see-image --global` and tell you to restart.
+it'll run `opencode plugin opencode-see-image --global` and tell you to restart. 
 
-## Prerequisites
+## prerequisites
 
-You need a connected vision-capable provider. The plugin auto-detects whichever you have connected, **either of these works**:
+you need a connected vision-capable provider. The plugin auto-detects whichever you have connected, **either of these work**:
 
-### Free (OpenCode Zen)
-1. Run `/connect` in opencode
-2. Select **opencode** (OpenCode Zen)
-3. Paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
+### free (OpenCode Zen)
+1. run `/connect` in opencode
+2. select **opencode** (OpenCode Zen)
+3. paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
 
-The plugin falls back to **mimo-v2.5-free**. No subscription needed.
+the plugin falls back to **mimo-v2.5-free**.
 
-### Paid, w/ OpenCode Go
-1. Run `/connect` in opencode
-2. Select **opencode-go**
-3. Paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
+### paid, w/ OpenCode Go
+1. run `/connect` in opencode
+2. select **opencode-go**
+3. paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
 
-The plugin prefers **minimax-m3** via opencode-go (~3000ms) when available.
+the plugin prefers **minimax-m3** via opencode-go when available.
 
-### Paid, w/ another provider
+### paid, w/ another provider
 
-Set the `SEE_IMAGE_*` env vars to point at any Anthropic-Messages-compatible endpoint. See [Configuration](#configuration) below.
+set the `SEE_IMAGE_*` env vars to point at any Anthropic-Messages-compatible endpoint. see [Configuration](#configuration) below.
 
-**Resolution order:** explicit `SEE_IMAGE_API_KEY` env → configured `SEE_IMAGE_PROVIDER` → `opencode-go` (MiniMax M3) → `opencode` (mimo-v2.5-free, free).
+**the resolve order:** explicit `SEE_IMAGE_API_KEY` env → configured `SEE_IMAGE_PROVIDER` → `opencode-go` (MiniMax M3) → `opencode` (mimo-v2.5-free).
 
-## How it works
+## how the _eye surgery_ works
 
 ```
 user attaches screenshot
-        │
-        ▼
+        |
+        v
 opencode rejects it: 'this model does not support image input'
-        │  (the model only sees the filename, no pixels)
-        ▼
+        |      (the model only sees the filename)
+        v
 plugin's system-prompt instructions tell the model to call see_image
-        │
-        ▼
+        |
+        v
 see_image tool:
-  1. queries opencode's SQLite DB for the image (handles clipboard pastes, dragged files, screenshots)
+  1. queries opencode's SQLite DB for the image
   2. falls back to filesystem search if not in DB
   3. sends the image to the vision model via opencode's SDK
   4. returns the textual description
-        │
-        ▼
+        |
+        v
 primary model answers using the description
 ```
 
-## The `see_image` tool
+## the `see_image` tool
 
-The plugin registers a `see_image` tool with two arguments:
+the plugin registers a `see_image` tool with two arguments:
 
-| Arg | Type | Required | Description |
+| arg | type | required? | description |
 |---|---|---|---|
-| `filePath` | string | yes | Path to the image. Absolute path, or a bare filename like `"Screenshot 2026-06-18 at 17.32.24.png"` to auto-locate. |
-| `question` | string | no | A specific question about the image. Defaults to a general detailed description. Use this to focus on a particular detail (e.g. `"What error is shown in the terminal?"`). |
+| `filePath` | string | y | path to the image. Absolute path, or a bare filename like `"Screenshot 2026-06-18 at 17.32.24.png"` to auto-locate. |
+| `question` | string | n | a specific question about the image. Defaults to a general detailed description. Use this to focus on a particular detail (e.g. `"What error is shown in the terminal?"`). |
 
-Your model calls this tool automatically when you attach a screenshot, you don't need to do anything special. The `question` arg is optional; the model uses it when you ask something specific about the image.
+your model calls this tool automatically when you attach a screenshot, you don't need to do anything special. The `question` arg is optional; the model uses it when you ask something specific about the image.
 
-## Configuration
+## configuration
 
-All settings are env-var overrides. The plugin uses opencode's SDK client by default (handles auth automatically). Set `SEE_IMAGE_API_KEY` to bypass the SDK and call an HTTP endpoint directly.
+all settings are env-var overrides. The plugin uses opencode's SDK client by default (handles auth automatically). Set `SEE_IMAGE_API_KEY` to bypass the SDK and call an HTTP endpoint directly.
 
-| Env var | Default | Description |
+| env var | default | description |
 |---|---|---|
 | `SEE_IMAGE_MODEL` | `minimax-m3` | Vision model ID |
 | `SEE_IMAGE_PROVIDER` | `opencode-go` | Provider ID for SDK routing |
@@ -102,11 +102,17 @@ All settings are env-var overrides. The plugin uses opencode's SDK client by def
 | `SEE_IMAGE_ENDPOINT` | `https://opencode.ai/zen/go/v1/messages` | HTTP endpoint (only used if `SEE_IMAGE_API_KEY` is set) |
 | `SEE_IMAGE_API_VERSION` | `2023-06-01` | `anthropic-version` header (HTTP mode only) |
 | `SEE_IMAGE_USER_AGENT` | _(Chrome UA)_ | User-Agent header (HTTP mode only) |
-| `SEE_IMAGE_TIMEOUT` | `30000` | Per-candidate timeout in ms. Prevents hanging on slow models. |
+| `SEE_IMAGE_TIMEOUT` | `30000` | Timeout in ms for session setup and HTTP-mode calls. |
+| `SEE_IMAGE_STALL_TIMEOUT` | `60000` | Stall timeout in ms (SDK streaming). The call is only aborted if the vision model produces no new tokens for this long — so long transcriptions keep running as long as they're progressing. |
+| `SEE_IMAGE_MAX_TIMEOUT` | `0` | Absolute cap in ms on a single streaming call. `0` = no cap. |
 
-### Using a different vision model
+### streaming
 
-Any Anthropic-Messages-compatible endpoint works. For example, to use a direct MiniMax key:
+On the SDK path the plugin streams the vision model's output and shows live progress in the tool call (`see_image: reading… N chars`). Instead of a hard timeout, it uses a **stall timeout** (`SEE_IMAGE_STALL_TIMEOUT`): a slow-but-progressing model (e.g. transcribing a huge table) runs to completion, while a genuinely hung call is still reaped. If a call is cut short, whatever was streamed so far is returned rather than nothing.
+
+### using a different vision model
+
+any Anthropic-Messages-compatible endpoint works. for example, to use a direct MiniMax key:
 
 ```bash
 export SEE_IMAGE_ENDPOINT="https://api.minimax.io/v1/messages"
@@ -114,60 +120,61 @@ export SEE_IMAGE_MODEL="minimax-m3"
 export SEE_IMAGE_API_KEY="your-minimax-key"
 ```
 
-To use a different opencode-go model (e.g. Kimi K2.7):
+to use a different opencode-go model (e.g. Kimi K2.7):
 
 ```bash
 export SEE_IMAGE_MODEL="kimi-k2.7-code"
 ```
 
-### Verified vision-capable models
+### verified vision-capable models
 
 **Free (OpenCode Zen):**
 
-| Model | Speed | Notes |
-|---|---|---|
-| `mimo-v2.5-free` | — | Free. Default fallback when only Zen is connected (routed via CLI). |
-| `big-pickle` | ~12000ms | Free. Accurate. Alternative Zen fallback. |
+| model | Notes |
+|---|---|
+| `mimo-v2.5-free` |  free. may be a bit slow. default fallback when only Zen is connected (routed via CLI). |
+| `big-pickle` | for some reason, big pickle works as an image capable model when called through the sdk w/ an active opencode go sub. |
 
-**Paid (OpenCode Go):**
+**paid (OpenCode Go):**
 
-| Model | Speed | Notes |
+| model | speed | notes |
 |---|---|---|
-| `minimax-m3` | ~3000ms | Default. Fast, clean text output. |
-| `kimi-k2.7-code` | ~7000ms | Clean output, accurate. |
-| `kimi-k2.6` | ~20000ms | Accurate but slow. |
-| `qwen3.7-plus` | ~20000ms | Emits thinking blocks (handled). |
+| `minimax-m3` | ~3000ms | default. fast, clean, and accurate. |
+| `kimi-k2.7-code` | ~7000ms | clean and accurate. |
+| `kimi-k2.6` | ~12000ms | accurate but slow. |
+| `qwen3.7-plus` | ~15000ms | slow, spends a bit more tokens because of thinking. |
 
-## Updating
+## updating
 
-**Auto-update (built in):** the plugin checks npm for a newer version on startup. If one exists, it updates itself via `opencode plugin --force` (uses opencode's bundled bun, no global bun needed) and shows a toast: *"opencode-see-image updated to X.Y.Z, restart opencode to apply"*. You just need to restart opencode to load the new version. Nothing to configure.
+**auto-update (built in):** uses the opencode-plugin-update-kit and shows a toast: *"opencode-see-image updated to X.Y.Z, restart opencode to apply"*. You just need to restart opencode to load the new version.
 
-**Manual update** (if you want to force it now):
+**manual update**:
 ```bash
 opencode plugin opencode-see-image --force --global
 ```
-Then restart opencode. (No bun required, this uses opencode's own bun.)
+then restart opencode.
 
-**Pin a version** in your config to opt out of auto-updates:
+**pin a version** in your config to opt out of auto-updates:
 ```jsonc
 "plugin": ["opencode-see-image@0.4.2"]
 ```
 
-## Limitations
+## kimitations
 
-- **macOS-only filesystem search** — the filesystem fallback targets macOS screenshot temp dirs. Linux/Windows users should rely on the DB lookup (which is cross-platform) or pass absolute paths.
+- **macOS-only filesystem search**. the filesystem fallback targets macOS screenshot temp dirs. Linux/Windows users should rely on the DB lookup (which is cross-platform) or pass absolute paths.
+> if you can add compat for more platforms, i would love a pr.
 
-## File search locations
+## file search locations
 
-When opencode rejects an image attachment, the model only receives a bare filename. `see_image` searches these locations in order:
+when opencode rejects an image attachment, the model only receives a bare filename. `see_image` searches these locations in order:
 
 1. `$TMPDIR/TemporaryItems/NSIRD_screencaptureui_*/` (where macOS stashes dragged screenshots)
 2. `$TMPDIR/TemporaryItems/`
 3. `~/Desktop` (default screenshot save location)
 4. `~/Downloads`
-5. Current working directory
+5. current working directory
 
-Pass an absolute `filePath` to skip the search.
+pass an absolute `filePath` to skip the search.
 
 ## License
 

package/index.ts

@@ -12,6 +12,12 @@ const ENDPOINT =
 const MODEL = process.env.SEE_IMAGE_MODEL || "minimax-m3"
 const PROVIDER_ID = process.env.SEE_IMAGE_PROVIDER || "opencode-go"
 const TIMEOUT = parseInt(process.env.SEE_IMAGE_TIMEOUT || "30000", 10)
+// Stall timeout: while streaming, only abort if the model produces no new
+// tokens for this long. Lets long transcriptions run as long as they keep
+// progressing. Used for the SDK streaming path.
+const STALL_TIMEOUT = parseInt(process.env.SEE_IMAGE_STALL_TIMEOUT || "60000", 10)
+// Optional absolute cap on a single streaming call (0 = no cap).
+const MAX_TIMEOUT = parseInt(process.env.SEE_IMAGE_MAX_TIMEOUT || "0", 10)
 const API_VERSION = process.env.SEE_IMAGE_API_VERSION || "2023-06-01"
 const USER_AGENT =
   process.env.SEE_IMAGE_USER_AGENT ||
@@ -216,12 +222,15 @@ function readProviderKey(providerID: string): string | null {
   }
 }
 
+type ProgressFn = (info: { chars: number; preview: string; provider: string; model: string }) => void
+
 async function seeImageViaSDK(
   client: any,
   dataUrl: string,
   mediaType: string,
   prompt: string,
   abort?: AbortSignal,
+  onProgress?: ProgressFn,
 ): Promise<{ text: string; model: string; provider: string }> {
   const errors: string[] = []
 
@@ -288,6 +297,115 @@ async function seeImageViaSDK(
     return null
   }
 
+  // Stream a vision response from a paid/SDK provider. Subscribes to opencode's
+  // event stream so we can (a) surface live progress and (b) use a *stall*
+  // timeout — we only give up if the model goes quiet for STALL_TIMEOUT, so a
+  // long transcription keeps running as long as it's producing tokens. Returns
+  // whatever text was produced, even if a stall/abort cut it short (partial).
+  const streamCandidate = async (
+    providerID: string,
+    modelID: string,
+  ): Promise<string | null> => {
+    const sessionRes = await Promise.race([
+      client.session.create({ body: {} }),
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`session.create timed out after ${TIMEOUT}ms`)),
+          TIMEOUT,
+        ),
+      ),
+    ])
+    const sessionID: string | undefined = sessionRes.data?.id
+    if (!sessionID) throw new Error("no session ID")
+
+    const controller = new AbortController()
+    const onAbort = () => controller.abort()
+    abort?.addEventListener("abort", onAbort)
+
+    // Subscribe to events before prompting so we don't miss early tokens.
+    let stream: AsyncGenerator<any> | undefined
+    try {
+      const sub = await client.event.subscribe()
+      stream = sub?.stream
+    } catch {}
+
+    const partsByID = new Map<string, string>()
+    let streamedText = ""
+    let lastActivity = Date.now()
+    let finished = false
+
+    const consume = (async () => {
+      if (!stream) return
+      try {
+        for await (const ev of stream) {
+          if (finished) break
+          if (
+            ev?.type === "message.part.updated" &&
+            ev.properties?.part?.type === "text" &&
+            ev.properties.part.sessionID === sessionID
+          ) {
+            const p = ev.properties.part
+            partsByID.set(p.id, typeof p.text === "string" ? p.text : "")
+            streamedText = [...partsByID.values()].join("\n").trim()
+            lastActivity = Date.now()
+            onProgress?.({
+              chars: streamedText.length,
+              preview: streamedText.slice(-160),
+              provider: providerID,
+              model: modelID,
+            })
+          }
+        }
+      } catch {}
+    })()
+
+    // Stall watchdog (only when we actually have a stream to measure activity).
+    const stallTimer = stream
+      ? setInterval(() => {
+          if (Date.now() - lastActivity > STALL_TIMEOUT) controller.abort()
+        }, 1000)
+      : undefined
+    const maxTimer =
+      MAX_TIMEOUT > 0 ? setTimeout(() => controller.abort(), MAX_TIMEOUT) : undefined
+
+    let res: any
+    try {
+      res = await client.session.prompt({
+        path: { id: sessionID },
+        body: {
+          model: { providerID, modelID },
+          parts: [
+            { type: "file", mime: mediaType, url: dataUrl },
+            { type: "text", text: prompt },
+          ],
+          tools: {},
+          system:
+            "You are a vision assistant. Describe the image accurately and concisely. Answer with text only.",
+        },
+        signal: controller.signal,
+      })
+    } catch (e: any) {
+      // Aborted by stall/max/external — fall through to whatever we streamed.
+      if (!streamedText) throw e
+    } finally {
+      finished = true
+      if (stallTimer) clearInterval(stallTimer)
+      if (maxTimer) clearTimeout(maxTimer)
+      try { await stream?.return?.(undefined) } catch {}
+      abort?.removeEventListener("abort", onAbort)
+      client.session.delete({ path: { id: sessionID } }).catch(() => {})
+    }
+
+    const finalText = (res?.data?.parts ?? [])
+      .filter((p: any) => p.type === "text")
+      .map((p: any) => p.text)
+      .filter((t: any) => typeof t === "string" && t.length > 0)
+      .join("\n")
+      .trim()
+
+    return finalText || streamedText || null
+  }
+
   let result: { text: string; model: string; provider: string } | undefined
 
   try {
@@ -312,56 +430,8 @@ async function seeImageViaSDK(
         continue
       }
 
-      let sessionID: string | undefined
       try {
-        const sessionRes = await Promise.race([
-          client.session.create({ body: {} }),
-          new Promise<never>((_, reject) =>
-            setTimeout(
-              () => reject(new Error(`session.create timed out after ${TIMEOUT}ms`)),
-              TIMEOUT,
-            ),
-          ),
-        ])
-        sessionID = sessionRes.data?.id
-        if (!sessionID) {
-          errors.push(`${providerID}/${modelID}: no session ID`)
-          continue
-        }
-
-        const controller = new AbortController()
-        const onAbort = () => controller.abort()
-        abort?.addEventListener("abort", onAbort)
-        const timer = setTimeout(() => controller.abort(), TIMEOUT)
-        let res
-        try {
-          res = await client.session.prompt({
-            path: { id: sessionID },
-            body: {
-              model: { providerID, modelID },
-              parts: [
-                { type: "file", mime: mediaType, url: dataUrl },
-                { type: "text", text: prompt },
-              ],
-              tools: {},
-              system:
-                "You are a vision assistant. Describe the image accurately and concisely. Answer with text only.",
-            },
-            signal: controller.signal,
-          })
-        } finally {
-          clearTimeout(timer)
-          abort?.removeEventListener("abort", onAbort)
-        }
-
-        const parts = res.data?.parts ?? []
-        const text = (parts as any[])
-          .filter((p: any) => p.type === "text")
-          .map((p: any) => p.text)
-          .filter((t: any) => typeof t === "string" && t.length > 0)
-          .join("\n")
-          .trim()
-
+        const text = await streamCandidate(providerID, modelID)
         if (text) {
           result = { text, model: modelID, provider: providerID }
           break
@@ -369,12 +439,6 @@ async function seeImageViaSDK(
         errors.push(`${providerID}/${modelID}: no text in response`)
       } catch (e: any) {
         errors.push(`${providerID}/${modelID}: ${e?.message ?? e}`)
-      } finally {
-        if (sessionID) {
-          await client.session
-            .delete({ path: { id: sessionID } })
-            .catch(() => {})
-        }
       }
     }
 
@@ -522,7 +586,17 @@ const SeeImagePlugin: Plugin = async (ctx) => {
         .string()
         .optional()
         .describe(
-          "Optional specific question about the image. Defaults to a general detailed description.",
+          [
+            "What to ask the vision model. Omit for a general detailed description.",
+            "Tailor it to the situation for much better results:",
+            '- Reading/transcribing text or code: "Transcribe all text exactly, preserving layout, line breaks, and code indentation."',
+            '- An error or stack trace screenshot: "Quote the exact error message and stack trace, then state the likely cause."',
+            '- Reproducing a UI as code: "Describe the layout, components, text, colors, and spacing precisely enough to rebuild this UI in code."',
+            '- A technical diagram/architecture: "Explain this diagram: list each component and the relationships and data/flow direction between them."',
+            '- A chart/graph/dashboard: "Read this visualization: axes, series, key values, and the main takeaway."',
+            '- Comparing against an expected design: "Describe this UI in detail so it can be diffed against an expected layout (note any visible defects or misalignment)."',
+            "Otherwise pass the user's own specific question verbatim.",
+          ].join("\n"),
         ),
     },
     async execute(args, context) {
@@ -539,12 +613,25 @@ const SeeImagePlugin: Plugin = async (ctx) => {
         const b64 = resolved.dataUrl.split(",")[1] || ""
         result = await seeImageViaHTTP(b64, resolved.mediaType, prompt, context.abort)
       } else {
+        // Throttle live progress updates so we don't spam the UI while the
+        // vision model streams a long response.
+        let lastUpdate = 0
+        const onProgress: ProgressFn = (info) => {
+          const now = Date.now()
+          if (now - lastUpdate < 400) return
+          lastUpdate = now
+          context.metadata({
+            title: `see_image: reading… ${info.chars} chars (${info.model})`,
+            metadata: { streaming: true, chars: info.chars, preview: info.preview },
+          })
+        }
         result = await seeImageViaSDK(
           client,
           resolved.dataUrl,
           resolved.mediaType,
           prompt,
           context.abort,
+          onProgress,
         )
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-see-image",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Give non-vision opencode models the ability to see images/screenshots by routing them to a vision-capable model (MiniMax M3 via opencode-go by default).",
   "type": "module",
   "main": "index.ts",