@bismawy/pi-vision-watcher 1.0.7 → 1.0.9

package/README.md

@@ -1,79 +1,67 @@
-# 👁️ pi-vision-watcher
+# 👁️ @bismawy/pi-vision-watcher
 
-**Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision**
+**Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision capabilities.**
 
-Describe images using an authenticated vision model of your choice, then seamlessly hand off the text descriptions to non-vision models.
+Seamlessly inspect, describe, and convert visual inputs (screenshots, mockups, terminal errors, clipboard pastes) into structured descriptions using your preferred vision model, and hand them off to text-only coding models without interrupting your workflow.
 
 [![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
 [![npm](https://img.shields.io/npm/v/@bismawy/pi-vision-watcher)](https://www.npmjs.com/package/@bismawy/pi-vision-watcher)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
----
-
-## The Problem
-
-Some of the best coding models are text-only. When you attach a screenshot, diagram, or UI mock, they either ignore it or fail the request entirely. Switching models just to read an image interrupts your workflow.
-
-## The Solution
-
-`pi-vision-watcher` bridges this gap automatically:
-- **Interactive Picker:** Pick any vision model from your authenticated providers with `/vision-watcher`.
-- **Automatic Handoff:** Whenever a non-vision model receives an image (via paste, attachment, or the `read` tool), the image is described behind the scenes and swapped for rich descriptive text before reaching the model.
-- **Batched & Cached:** Uses a DataLoader pattern so multiple images in a turn coalesce into a **single batched vision request**, cached by SHA-256 hash.
+![pi-vision-watcher](./assets/screenshot.webp)
 
 ---
 
-## ✨ Features
-
-- 🎯 **Connected-Only Model Picker** — `/vision-watcher` filters out unconfigured providers, showing only models you actually have credentials for (`/login`, `models.json`, or environment variables). Vision-capable models are highlighted with 👁️.
-- ⚡ **DataLoader Batching** — Multiple images from parallel `read` calls or multi-image attachments merge into ONE batched vision call during the tool-result phase, eliminating latency bottlenecks.
-- 🧠 **Thinking & Reasoning Support** — Configure reasoning effort (`/vision-watcher thinking <level>`) for reasoning-capable vision models (e.g. OpenAI o-series, Claude, DeepSeek).
-- 🔄 **Fallback Chains** — Specify backup vision models that automatically take over if your primary describer is unavailable or encounters rate limits.
-- 🚀 **Paste-Time Prewarm (Opt-in)** — Describe pasted images the moment the path lands in the prompt editor before you even press Enter.
-- 📬 **Async Clipboard Fallback (Opt-in)** — Races direct reads against asynchronous description delivery to prevent stalling.
-- 💾 **LRU Hash Caching** — Prevents duplicate calls for identical images across conversation turns.
-- 🛡️ **Graceful Degradation** — Never crashes your agent turn. If a description fails, a clean `[Image: description unavailable]` placeholder is provided and logged to `~/.pi/agent/logs/pi-vision-watcher/errors.log`.
-
----
-
-## 📦 Install
+## ⚡ Quick Start
 
+### 1. Installation
 ```bash
 pi install npm:@bismawy/pi-vision-watcher
 ```
+*(Or install directly from Git: `pi install git:github.com/bismawy/pi-vision-watcher`)*
 
-Alternatively, install directly from GitHub:
-
+### 2. Select Vision Model
+Open the interactive TUI selector to choose your vision describer model from your connected providers:
 ```bash
-pi install git:github.com/bismawy/pi-vision-watcher
+/vision-watcher
 ```
+*(You can also set it directly: `/vision-watcher model openai/gpt-4o`)*
 
-Then run `/reload` in Pi (or restart Pi).
+### 3. Work Seamlessly
+Switch to any text-only model in Pi (e.g. DeepSeek, Claude text-only, local models). Whenever you paste an image, attach a file, or the agent runs `read` on an image, `pi-vision-watcher` describes it automatically in the background.
 
 ---
 
-## 🎮 Usage
+## 🚀 Key Capabilities
+
+- 🎯 **Connected-Only Interactive Picker:** Shows only vision-capable models from providers where you actually have active credentials (`/login`, `models.json`, or environment variables).
+- ⚡ **DataLoader Batching & SHA-256 Cache:** Automatically groups multiple images across parallel tool calls or multi-file prompts into a single batched describer request. Cached images are never re-described.
+- 🛡️ **Proactive False-Vision Healing:** Aggregator providers often mistakenly flag models (like DeepSeek V4) as multimodal, causing HTTP 400 errors (`This model does not support image`). `pi-vision-watcher` proactively forces handoff for these models and auto-heals `models.json` `modelOverrides` in-process.
+- 🧠 **Thinking & Reasoning Controls:** Adjust reasoning levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) for reasoning-capable vision models (o-series, Claude, DeepSeek).
+- 🔄 **Multi-Model Fallback Chains:** Automatically falls back to backup vision models if your primary provider is rate-limited or unavailable.
 
-### Interactive Commands
+---
+
+## 🕹️ Command Reference
 
-| Command | Description |
+| Command | Action |
 |---|---|
-| `/vision-watcher` | Open the interactive TUI picker to select your vision model |
-| `/vision-watcher model <provider/id>` | Set the vision describer model directly |
-| `/vision-watcher status` | View active configuration and handoff status |
-| `/vision-watcher enable` / `disable` | Toggle extension on or off |
-| `/vision-watcher auto on` / `off` | Toggle automatic handoff for all non-vision models |
-| `/vision-watcher add <provider/id>` | Force handoff for a specific model (e.g. weak vision models) |
+| `/vision-watcher` | Open interactive TUI picker for connected vision models |
+| `/vision-watcher model <provider/id>` | Set primary vision describer directly |
+| `/vision-watcher status` | View current configuration and active model status |
+| `/vision-watcher auto <on\|off>` | Toggle automatic handoff for non-vision models (default: `on`) |
+| `/vision-watcher add <provider/id>` | Force handoff on a specific model |
 | `/vision-watcher remove <provider/id>` | Remove model from forced handoff list |
-| `/vision-watcher thinking <level>` | Set describer thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) |
-| `/vision-watcher prewarm on` / `off` | Enable paste-time prewarming in TUI editor |
-| `/vision-watcher fallback on` / `off` | Enable async pasted-path description injection |
-| `/vision-watcher clear` | Clear configured vision model |
-| `/vision-watcher help` | Display full command reference |
+| `/vision-watcher thinking <level>` | Configure reasoning effort for vision models |
+| `/vision-watcher enable` / `disable` | Toggle extension active state |
+| `/vision-watcher help` | Show in-CLI command documentation |
 
 ---
 
-## ⚙️ Configuration
+## 📖 Deep Dive & Advanced Configuration
+
+<details>
+<summary><b>⚙️ Configuration File Schema (<code>pi-vision-watcher.json</code>)</b></summary>
 
 Configuration is stored at `~/.pi/agent/extensions/pi-vision-watcher.json`:
 
@@ -86,6 +74,7 @@ Configuration is stored at `~/.pi/agent/extensions/pi-vision-watcher.json`:
   "handoffModels": [],
   "thinking": false,
   "thinkingLevel": "medium",
+  "describeTimeoutMs": 45000,
   "prewarmPastedImages": false,
   "asyncClipboardHandoff": false,
   "maxTokens": null,
@@ -94,47 +83,58 @@ Configuration is stored at `~/.pi/agent/extensions/pi-vision-watcher.json`:
 }
 ```
 
-| Field | Default | Description |
-|---|---|---|
-| `enabled` | `true` | Master switch for vision handoff. |
-| `visionModel` | `null` | Primary describer as `provider/id` (`null` = handoff inactive). |
-| `fallbackModels` | `[]` | List of fallback `provider/id` models tried in order if primary fails. |
-| `autoHandoff` | `true` | Automatically apply handoff to all models lacking native vision. |
-| `handoffModels` | `[]` | Additional models forced to receive handoff even if vision-capable. |
-| `thinking` / `thinkingLevel` | `false` / `"medium"` | Reasoning effort for vision models that support thinking. |
-| `prewarmPastedImages` | `false` | Describe images immediately upon pasting into the prompt. |
-| `asyncClipboardHandoff` | `false` | Asynchronous injection fallback for pasted image paths. |
-| `maxTokens` | `null` | Output token cap for descriptions (`null` = model default). |
-| `cacheMax` | `50` | Maximum number of described images cached per session. |
-| `maxDescriptionLines` | `0` | Truncate description lines (`0` = unbounded). |
-
----
-
-## 🔍 Troubleshooting & Logs
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | Master switch for handoff processing. |
+| `visionModel` | `string \| null` | `null` | Primary describer model ref (`provider/id`). |
+| `fallbackModels` | `string[]` | `[]` | Ordered backup models if the primary model fails. |
+| `autoHandoff` | `boolean` | `true` | Automatically describe images for models lacking native vision. |
+| `handoffModels` | `string[]` | `[]` | Specific model IDs forced to receive descriptions. |
+| `thinking` | `boolean` | `false` | Enable reasoning tokens for vision model. |
+| `thinkingLevel` | `string` | `"medium"` | Reasoning effort (`minimal`, `low`, `medium`, `high`, `xhigh`, `max`). |
+| `describeTimeoutMs` | `number` | `45000` | Per-batch timeout before aborting or triggering fallbacks. |
+| `prewarmPastedImages` | `boolean` | `false` | Start describing clipboard images immediately upon pasting in prompt. |
+| `asyncClipboardHandoff` | `boolean` | `false` | Async clipboard injection fallback mechanism. |
+| `maxTokens` | `number \| null` | `null` | Max output tokens for descriptions (`null` = model default). |
+| `cacheMax` | `number` | `50` | Maximum cached image hashes per session. |
+| `maxDescriptionLines` | `number` | `0` | Truncate lines in description block (`0` = full description). |
+
+</details>
+
+<details>
+<summary><b>🔍 Troubleshooting, Recovery & Diagnostics</b></summary>
+
+### Structured Error Logging
+If a vision call fails, errors are appended with stack traces and request metadata to:
+```text
+~/.pi/agent/logs/pi-vision-watcher/errors.log
+```
+Failures degrade gracefully to `[Image: description unavailable]` without breaking the agent turn.
 
-- **Error Logs:** Detailed failure traces, timestamps, and config snapshots are recorded in `~/.pi/agent/logs/pi-vision-watcher/errors.log`.
-- **Transient Retries:** Failed descriptions are never cached permanently — the next turn automatically re-attempts description generation.
+### False-Vision Auto-Recovery
+When a model falsely advertises image capability and returns an HTTP 400 rejection:
+1. `pi-vision-watcher` captures the error in the `message_end` event.
+2. It automatically updates `~/.pi/agent/models.json` under `providers.<name>.modelOverrides.<model>.input = ["text"]`.
+3. It triggers an in-process registry refresh so subsequent turns use handoff naturally.
 
----
+</details>
 
-## 🛠️ Development
+<details>
+<summary><b>🛠️ Development & Testing</b></summary>
 
 ```bash
-pnpm install
-pnpm test          # Run Vitest unit tests
-pnpm typecheck     # Run TypeScript type check
+bun install
+bun run test          # Run Vitest test suite (240+ unit tests)
+bun run typecheck     # Run TypeScript compiler check
+bun run lint:dead     # Scan for unused exports with Knip
 ```
 
----
+</details>
 
-## 📜 Credits & License
-
-`pi-vision-watcher` is inspired by and forked from [`pi-vision-handoff`](https://github.com/monotykamary/pi-vision-handoff) by [Tom X Nguyen](https://github.com/monotykamary) (originating from the concept in `pi-umans-provider`).
+---
 
-**Key Enhancements:**
-- Filters picker to only authenticated/connected models.
-- Added thinking & reasoning controls for modern reasoning vision models.
-- Multi-model fallback chain support.
-- Streamlined settings and UI badging.
+## 📜 License & Acknowledgments
 
-Released under the [MIT License](./LICENSE).
+- Built for the **[pi coding agent](https://github.com/earendil-works/pi-coding-agent)** ecosystem.
+- Evolved from concepts in `pi-vision-handoff` by Tom X Nguyen and `pi-umans-provider`.
+- Distributed under the **[MIT License](./LICENSE)**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bismawy/pi-vision-watcher",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Give text-only pi models vision — describe images with a vision model you pick via an interactive picker, then hand off the text description to non-vision models",
   "type": "module",
   "author": "bismawy",
@@ -57,7 +57,7 @@
     "extensions": [
       "./vision-watcher.ts"
     ],
-    "image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/screenshot.png"
+    "image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/screenshot.webp"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/image.ts

@@ -20,7 +20,7 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { isAbsolute, join, sep } from "node:path";
+import { isAbsolute, join, normalize, sep } from "node:path";
 import crypto from "node:crypto";
 import type { ExtractedImage } from "./index.js";
 
@@ -299,14 +299,14 @@ const LEADING_WRAP_RE = new RegExp('^[^A-Za-z0-9_/@.~-]+');
  *  dir and mistaken for local files; leading wrapping chars (parentheses,
  *  quotes) are stripped so quoted/parenthesized paths still resolve. */
 export function findPastedImagePaths(prompt: string): string[] {
-  const tmp = tmpdir();
+  const tmp = normalize(tmpdir());
   const paths = new Set<string>();
   for (const m of prompt.matchAll(PASTED_IMAGE_PATH_RE)) {
     const token = m[1];
     if (!token) continue;
     if (URL_RE.test(token)) continue;
     const p = token.replace(LEADING_WRAP_RE, "");
-    const abs = isAbsolute(p) ? p : join(tmp, p);
+    const abs = normalize(isAbsolute(p) ? p : join(tmp, p));
     // Ensure the resolved candidate stays inside the temp directory.
     if (abs.startsWith(tmp + sep) || abs === tmp) paths.add(abs);
   }

package/src/index.ts

@@ -235,6 +235,84 @@ export function formatModelRef(provider: string, id: string): string {
   return `${provider}/${id}`;
 }
 
+/** Match provider errors meaning "this model can't take image input" — e.g.
+ *  AgentRouter's 400 `"This model does not support image"`, OpenRouter's
+ *  "does not support image inputs". Used by the message_end auto-recovery:
+ *  a model whose registry entry FALSELY declares `input: ["text","image"]`
+ *  passes the autoHandoff vision check, so the raw image reaches the provider
+ *  and 400s — we learn from that error and force handoff for the model. */
+export function isImageNotSupportedError(text: string): boolean {
+  return /not support (?:the )?image|image[s]? (?:input[s]? )?(?:is |are )?not supported|does not accept image|unsupported (?:image|multimodal)/i.test(
+    text,
+  );
+}
+
+/** Models whose registry entries commonly declare image input while the
+ *  backend rejects images (DeepSeek V4 via aggregator proxies). Conservative:
+ *  VL / Vision / Janus variants keep image input. Used so autoHandoff covers
+ *  them on the FIRST send — waiting for a 400 is too late. */
+export function isKnownTextOnlyFalselyVision(id: string | undefined | null): boolean {
+  if (!id) return false;
+  const n = id.toLowerCase();
+  if (n.includes("vl") || n.includes("vision") || n.includes("janus")) return false;
+  return /deepseek[-_./]*v4/.test(n);
+}
+
+/** Extract the provider error string from a finalized assistant message.
+ *  Pi stores it on `errorMessage`; some providers also put the 400 body in a
+ *  text content block. */
+export function assistantErrorText(msg: {
+  errorMessage?: unknown;
+  content?: unknown;
+} | null | undefined): string {
+  if (!msg) return "";
+  if (typeof msg.errorMessage === "string" && msg.errorMessage) return msg.errorMessage;
+  if (typeof msg.content === "string") return msg.content;
+  if (!Array.isArray(msg.content)) return "";
+  return msg.content
+    .filter((b): b is { type: string; text: string } => !!b && typeof b === "object" && typeof (b as { text?: unknown }).text === "string")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+/** Set (or add) a `modelOverrides` entry forcing a model's input to
+ *  `["text"]` in a PARSED models.json config object. Pure: returns a new
+ *  object, never mutates the input. Preserves every other field (credentials,
+ * compat, sibling models) — only the one model's `input` override is touched.
+ *  Used by the message_end auto-recovery to fix models whose registry entry
+ *  falsely declares image input the backend rejects with a 400. */
+export function setTextOnlyInputOverride(
+  cfg: unknown,
+  providerId: string,
+  modelId: string,
+): Record<string, unknown> {
+  const root =
+    cfg && typeof cfg === "object" && !Array.isArray(cfg)
+      ? { ...(cfg as Record<string, unknown>) }
+      : {};
+  const providers =
+    root.providers && typeof root.providers === "object" && !Array.isArray(root.providers)
+      ? { ...(root.providers as Record<string, unknown>) }
+      : {};
+  const provider =
+    providers[providerId] && typeof providers[providerId] === "object" && !Array.isArray(providers[providerId])
+      ? { ...(providers[providerId] as Record<string, unknown>) }
+      : {};
+  const overrides =
+    provider.modelOverrides && typeof provider.modelOverrides === "object" && !Array.isArray(provider.modelOverrides)
+      ? { ...(provider.modelOverrides as Record<string, unknown>) }
+      : {};
+  const existing =
+    overrides[modelId] && typeof overrides[modelId] === "object" && !Array.isArray(overrides[modelId])
+      ? { ...(overrides[modelId] as Record<string, unknown>) }
+      : {};
+  overrides[modelId] = { ...existing, input: ["text"] };
+  provider.modelOverrides = overrides;
+  providers[providerId] = provider;
+  root.providers = providers;
+  return root;
+}
+
 /** Whether a model declares image input. */
 export function isVisionModel(model: { input?: ("text" | "image")[] } | undefined | null): boolean {
   return !!model && Array.isArray(model.input) && model.input.includes("image");

package/vision-watcher.ts

@@ -31,17 +31,24 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, resizeImage } from "@earendil-works/pi-coding-agent";
 import type { Api, ImageContent, Model, TextContent } from "@earendil-works/pi-ai";
 import { isAbsolute, resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import {
   DESCRIBE_TIMEOUT_MS,
   extractImageFromBlock,
   formatModelRef,
   isThinkingLevel,
+  assistantErrorText,
+  isImageNotSupportedError,
+  isKnownTextOnlyFalselyVision,
   isVisionModel,
   NON_VISION_IMAGE_NOTE,
   parseModelRef,
   readConfig,
+  setTextOnlyInputOverride,
   stripNonVisionImageNote,
   writeConfig,
   HANDOFF_COMMAND_DESCRIPTION,
@@ -56,7 +63,6 @@ import {
 import { DescriptionLoader, UNAVAILABLE, type LoaderDeps } from "./src/dataloader.js";
 import { imageHash, findPastedImagePaths, readImageBuffer, readImageBufferBounded, resolvePrewarmImage, isOmittedImageNote } from "./src/image.js";
 import { appendVisionError } from "./src/error-log.js";
-import { resizeImage } from "@earendil-works/pi-coding-agent";
 import { VisionModelSelectorComponent, type VisionModelSelectorResult } from "./src/vision-model-selector.js";
 import { PrewarmEditor } from "./src/prewarm-editor.js";
 import { Text } from "@earendil-works/pi-tui";
@@ -238,6 +244,10 @@ function isHandoffTarget(
   if (!model || !model.provider || !model.id) return false;
   const ref = formatModelRef(model.provider, model.id);
   if (cfg.handoffModels.includes(ref)) return true;
+  // Aggregators often mark DeepSeek V4 as vision; the backend 400s on images.
+  // Treat as text-only so the FIRST send is handed off — waiting for the 400
+  // is too late. Persist the models.json override separately so /model agrees.
+  if (cfg.autoHandoff && isKnownTextOnlyFalselyVision(model.id)) return true;
   if (cfg.autoHandoff && !isVisionModel(model)) return true;
   return false;
 }
@@ -303,6 +313,46 @@ function installPrewarmEditor(ctx: ExtensionContext): void {
   );
 }
 
+/** Write a `modelOverrides.<modelId>.input = ["text"]` fix to models.json and
+ *  refresh the registry in-process so it applies without /reload (the same
+ *  write+refresh pattern pi-auto-compat uses). Never touches credentials or
+ *  other fields — the merge is done by the pure {@link setTextOnlyInputOverride}.
+ *  Returns true when the override was written; false when models.json is
+ *  unreadable/corrupt or the write fails (callers fall back to handoffModels). */
+function fixModelInputTextOnly(ctx: ExtensionContext, providerId: string, modelId: string): boolean {
+  const path = join(getAgentDir(), "models.json");
+  let cfg: unknown;
+  try {
+    cfg = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+  } catch {
+    return false;
+  }
+  try {
+    writeFileSync(path, JSON.stringify(setTextOnlyInputOverride(cfg, providerId, modelId), null, 2) + "\n", "utf8");
+  } catch {
+    return false;
+  }
+  // Refresh the merged registry in-process so the corrected input takes
+  // effect this session. Fire-and-forget: a refresh failure only delays the
+  // fix to the next session start (models.json is already corrected on disk).
+  void ctx.modelRegistry
+    ?.refresh?.({ allowNetwork: false })
+    ?.catch?.(() => {});
+  return true;
+}
+
+/** Persist `input: ["text"]` for a model that falsely declares image input.
+ *  No-op if the model is already text-only or isn't a known false-vision id. */
+function persistFalseVisionOverride(
+  ctx: ExtensionContext,
+  model: { provider?: string; id?: string; input?: ("text" | "image")[] } | undefined | null,
+): boolean {
+  if (!model?.provider || !model.id) return false;
+  if (!isKnownTextOnlyFalselyVision(model.id)) return false;
+  if (!isVisionModel(model)) return false;
+  return fixModelInputTextOnly(ctx, model.provider, model.id);
+}
+
 function notifyUnresolvedVisionModel(ctx: ExtensionContext, ref: string): void {
   if (visionModelUnresolvedRef === ref) return;
   visionModelUnresolvedRef = ref;
@@ -401,6 +451,7 @@ export default function (pi: ExtensionAPI) {
     warnedHashes.clear();
     loader.reset();
     currentModel = ctx.model;
+    persistFalseVisionOverride(ctx, ctx.model);
     installPrewarmEditor(ctx);
   });
 
@@ -719,13 +770,69 @@ export default function (pi: ExtensionAPI) {
     if (changed) return { messages: event.messages };
   });
 
+  // Auto-recovery from "model does not support image" 400s: a model whose
+  // registry entry falsely declares `input: ["text","image"]` (common on
+  // aggregator providers) passes the autoHandoff vision check, so handoff is
+  // skipped and the raw image block reaches the provider — which rejects it.
+  // PRIMARY fix: correct the metadata at its layer — write a `modelOverrides`
+  // entry forcing `input: ["text"]` to models.json and refresh the registry
+  // in-process (modelOverrides is Pi's topmost config layer, so it wins even
+  // over a regenerated models[] entry). The model then registers as text-only,
+  // autoHandoff covers it naturally, and /model shows it correctly. FALLBACK
+  // (write failed): force handoff via handoffModels. Either way, the failed
+  // turn's images are still in history; the context hook describes them on the
+  // retry instead of failing again.
+  pi.on("message_end", (event, ctx) => {
+    const msg = event.message as {
+      role?: string;
+      type?: string;
+      stopReason?: string;
+      errorMessage?: unknown;
+      content?: unknown;
+    };
+    // Pi assistant messages use `role`, not `type`. Checking `type` made this
+    // handler a no-op, so the 400 never taught us anything.
+    if (msg?.role !== "assistant" && msg?.type !== "assistant") return;
+    if (msg.stopReason !== "error") return;
+    if (!isImageNotSupportedError(assistantErrorText(msg))) return;
+    if (!isConfigured(config)) return;
+    const model = ctx.model;
+    if (!model?.provider || !model.id) return;
+    const ref = formatModelRef(model.provider, model.id);
+
+    const fixed = persistFalseVisionOverride(ctx, model) || fixModelInputTextOnly(ctx, model.provider, model.id);
+    if (fixed) {
+      if (!config.handoffModels.includes(ref)) {
+        config = { ...config, handoffModels: [...config.handoffModels, ref] };
+        writeConfig(config);
+      }
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          `pi-vision-watcher: ${ref} rejected image input — marked as text-only. Resend; images will be described by ${config.visionModel}.`,
+          "warning",
+        );
+      }
+      return;
+    }
+
+    if (config.handoffModels.includes(ref)) return;
+    config = { ...config, handoffModels: [...config.handoffModels, ref] };
+    writeConfig(config);
+    if (!ctx.hasUI) return;
+    ctx.ui.notify(
+      `pi-vision-watcher: ${ref} rejected image input — handoff forced for this model. Resend; images will be described by ${config.visionModel}.`,
+      "warning",
+    );
+  });
+
   pi.on("model_select", (event, ctx) => {
     currentModel = event.model;
+    persistFalseVisionOverride(ctx, event.model);
     if (!ctx.hasUI) return;
     if (!isConfigured(config)) return;
     const model = event.model;
     if (!model) return;
-    if (isHandoffTarget(model, config) && !isVisionModel(model)) {
+    if (isHandoffTarget(model, config)) {
       ctx.ui.notify(
         `pi-vision-watcher: active — images will be described by ${config.visionModel}`,
         "info",