opencode-see-image 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 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 (e.g. GLM-5.2, DeepSeek, Kimi), opencode rejects it with an error. This plugin intercepts that flow: it registers a `see_image` tool that sends the image to a vision model (MiniMax M3 by default) 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
 
@@ -15,10 +15,24 @@ Add the plugin to your opencode config:
   "plugin": ["opencode-see-image"]
 }
 ```
+Then restart opencode.
 
-Then **restart opencode**.
 
-That's it — the plugin self-contains both the tool and the triggering instructions (injected into the system prompt). No separate skill file needed.
+## Install via your agent (copy-paste this)
+
+Paste this prompt to your opencode agent, and it'll install the plugin for you.
+
+```
+Install the opencode-see-image plugin so I can send you screenshots. Do this:
+
+1. Edit ~/.config/opencode/opencode.jsonc (create it if missing). Preserve any existing fields and the $schema. Add "opencode-see-image" to the "plugin" array. If "plugin" doesn't exist, add it as ["opencode-see-image"].
+2. Check that a vision-capable provider is connected by looking for ~/.local/share/opencode/auth.json with either an "opencode-go" entry (paid, fast) OR an "opencode" entry (free). If neither is present, tell me to run /connect and select either opencode-go or opencode (key from opencode.ai/auth).
+3. Tell me to quit and restart opencode for the plugin to load.
+
+After I restart and attach a screenshot, you should call the see_image tool to view it.
+```
+
+Then restart opencode.
 
 ## Prerequisites
 
@@ -62,6 +76,17 @@ see_image tool:
 primary model answers using the description
 ```
 
+## The `see_image` tool
+
+The plugin registers a `see_image` tool with two arguments:
+
+| 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?"`). |
+
+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
 
 All settings are env-var overrides. Defaults work out-of-the-box for opencode-go + MiniMax M3.
@@ -108,6 +133,21 @@ export SEE_IMAGE_MODEL="kimi-k2.7-code"
 | `kimi-k2.6` | ~20s | Accurate but slow. |
 | `qwen3.7-plus` | ~20s | Emits thinking blocks (handled). |
 
+## Updating
+
+**Auto-update (built in):** the plugin checks npm for a newer version on every opencode startup. If one exists, it runs `bun update` automatically 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.
+
+**Manual update** (if you want to force it now):
+```bash
+cd ~/.cache/opencode && bun update opencode-see-image
+```
+Then restart opencode.
+
+**Pin a version** in your config to opt out of auto-updates:
+```jsonc
+"plugin": ["opencode-see-image@0.3.0"]
+```
+
 ## File search locations
 
 When opencode rejects an image attachment, the model only receives a bare filename. `see_image` searches these locations in order:
@@ -120,20 +160,6 @@ When opencode rejects an image attachment, the model only receives a bare filena
 
 Pass an absolute `filePath` to skip the search.
 
-## Install via your agent (copy-paste this)
-
-Paste this prompt to your opencode agent — it'll install the plugin for you:
-
-```
-Install the opencode-see-image plugin so I can send you screenshots. Do this:
-
-1. Edit ~/.config/opencode/opencode.jsonc (create it if missing). Preserve any existing fields and the $schema. Add "opencode-see-image" to the "plugin" array. If "plugin" doesn't exist, add it as ["opencode-see-image"].
-2. Check that a vision-capable provider is connected by looking for ~/.local/share/opencode/auth.json with either an "opencode-go" entry (paid, fast) OR an "opencode" entry (free). If neither is present, tell me to run /connect and select either opencode-go or opencode (key from opencode.ai/auth).
-3. Tell me to quit and restart opencode for the plugin to load.
-
-After I restart and attach a screenshot, you should call the see_image tool to view it.
-```
-
 ## License
 
 MIT

package/index.ts

@@ -252,8 +252,119 @@ Do NOT use \`see_image\` for reading text files — use the \`read\` tool for th
 - If the tool cannot find the file, tell the user the filename and ask for a full path or to drag the file into the project directory.
 - To inspect a specific detail, pass a targeted \`question\` (e.g. "What error is shown in the terminal?").`
 
+// ─── Auto-update ────────────────────────────────────────────────────────────
+// Runs once at plugin init (async, non-blocking). Checks npm for a newer
+// version, runs `bun update` in the opencode plugin cache if available, and
+// toasts the user to restart opencode to apply. Never throws — failures are
+// logged and swallowed so the plugin always loads.
+
+const PKG_NAME = "opencode-see-image"
+const REGISTRY_LATEST = `https://registry.npmjs.org/${PKG_NAME}/latest`
+
+function currentVersion(): string | null {
+  try {
+    // import.meta.url points at this module inside the bun cache.
+    const here = new URL(".", import.meta.url)
+    const pkgPath = new URL("package.json", here)
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    return pkg.version ?? null
+  } catch {
+    return null
+  }
+}
+
+function semverGt(a: string, b: string): boolean {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0)
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0)
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (x > y) return true
+    if (x < y) return false
+  }
+  return false
+}
+
+async function maybeAutoUpdate(
+  client: any,
+  $: any,
+  log: (msg: string, level?: string) => void,
+) {
+  const current = currentVersion()
+  if (!current) {
+    log("could not determine current version; skipping update check", "debug")
+    return
+  }
+
+  let latest: string
+  try {
+    const res = await fetch(REGISTRY_LATEST, {
+      headers: { accept: "application/json" },
+    })
+    if (!res.ok) {
+      log(`registry fetch returned HTTP ${res.status}`, "debug")
+      return
+    }
+    const data: any = await res.json()
+    latest = data?.version
+    if (!latest) {
+      log("registry response had no version field", "debug")
+      return
+    }
+  } catch (e: any) {
+    log(`registry fetch failed: ${e?.message ?? e}`, "debug")
+    return
+  }
+
+  if (!semverGt(latest, current)) {
+    log(`up to date (${current})`, "debug")
+    return
+  }
+
+  log(`update available: ${current} → ${latest}; running bun update`, "info")
+
+  // Update the plugin in opencode's cache. --no-save keeps the lockfile
+  // resolution intact while still pulling the new tarball. We cd into the
+  // cache dir because bun operates on the nearest package.json/lockfile.
+  const cacheDir = path.join(os.homedir(), ".cache/opencode")
+  try {
+    await $`cd ${cacheDir} && bun update ${PKG_NAME} --no-save`.quiet()
+  } catch (e: any) {
+    log(`bun update failed: ${e?.message ?? e}`, "warn")
+    return
+  }
+
+  // Tell the user to restart. Toast is non-blocking; if it fails, we log.
+  try {
+    await client?.tui?.showToast?.({
+      body: {
+        message: `${PKG_NAME} updated to ${latest} — restart opencode to apply`,
+        variant: "success",
+      },
+    })
+  } catch {
+    log(`update applied: ${current} → ${latest}; restart opencode to load`, "info")
+  }
+}
+
 // ─── Plugin export ──────────────────────────────────────────────────────────
 const SeeImagePlugin: Plugin = async (ctx) => {
+  const { client, $ } = ctx
+
+  const log = (message: string, level: string = "info") => {
+    try {
+      client?.app?.log?.({
+        body: { service: PKG_NAME, level, message },
+      })
+    } catch {
+      // logging is best-effort
+    }
+  }
+
+  // Fire-and-forget the update check. Never awaited so plugin init is not
+  // delayed by network. Errors are swallowed inside.
+  maybeAutoUpdate(client, $, log).catch(() => {})
+
   return {
     tool: {
       see_image: seeImageTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-see-image",
-  "version": "0.2.0",
+  "version": "0.3.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",