@bismawy/pi-vision-watcher 1.0.14 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+## [1.1.0] - 2026-10-05
+
+### Changed
+- **Breaking:** rebind four picker chords that collided with OS, terminal, readline and Pi
+  shortcuts. VTE (GNOME Terminal) closes the window on `ctrl+shift+q`, and POSIX tty flow
+  control swallows `ctrl+q`, so the previous bindings were unusable or destructive on Linux:
+  - `ctrl+q` → `ctrl+enter` (failover chain toggle)
+  - `ctrl+shift+q` → `ctrl+shift+r` (reset failover chain)
+  - `ctrl+a` → `alt+a` · `ctrl+alt+a` (async paste handoff)
+  - `ctrl+t` → `ctrl+shift+t` (thinking ladder)
+- Vision and failover markers now use single-cell glyphs (`✦`, `⇆`) instead of emoji, which
+  are double-width and broke column alignment. The symbols in the detail pane carry the same
+  colour as the badges they explain.
+- Detail pane labels read `Vision-capable ✦ :` / `Fallback ⇆ :` and the async row prints its
+  own chord beside the state.
+- `package.json` `description` now leads with the README tagline, per the `/arnative-pi`
+  manifest standard — `pi.dev/packages` renders this field verbatim as the package card
+  description. (Previously staged as `[Unreleased]` in PR #1.)
+
+### Added
+- `alt+↑` / `alt+↓` reorder the highlighted model; the failover chain follows list order and
+  the `None` row stays pinned first.
+
+### Fixed
+- Pressing `enter` while a filter was active silently saved the previously selected primary,
+  which the user could not see in the filtered list. `enter` now adopts the highlighted match.
+- Removed the `f2` binding from the README; it was documented but never implemented.
+
+### Notes
+- The three `ctrl+` chords are no-ops on legacy terminals that do not speak the Kitty Keyboard
+  Protocol (no wrong action fires). They work on Windows Terminal/conhost, X11, macOS, tmux
+  and SSH.
+- `ctrl+alt+a` is the international-layout-safe half of the async chord, where AltGr occupies
+  `alt+a`.
+
+---
+
+## [1.0.15] - 2026-09-28
+
+### Added
+- Standard `CHANGELOG.md` tracking repository release history according to Keep a Changelog.
+- Added `dev` script (`pi --extension ./vision-watcher.ts`) to `package.json` for live local testing without installation.
+
+### Changed
+- Refreshed README presentation layout, badge aesthetics, and structure to match the standard `pi-arnative` specification.
+- Streamlined README commands and shortcuts tables, tightened bullet copywriting, and repaired link icon character.
+- Standardized README tagline (`Intelligent vision watcher. Connected models. Zero workflow interruption.`) and `package.json` description to use vision watcher identity.
+- Refreshed package keywords and repository topics to focus on vision-watcher, image-describer, and failover capabilities (purged legacy handoff tags).
+- Standardized README banner image to full-width responsive `<img width="100%">` matching `pi-jev-eye`.
+- Updated `pi.image` manifest URL to `assets/banner.webp`.
+- Registered `CHANGELOG.md` and `LICENSE` in `package.json` `"files"` packaging list.
+
+### Fixed
+- Fixed model picker detail pane hanging wrapped values and aligned filter input field with the list gutter.
+
+---
+
+## [1.0.14] - 2026-09-22
+
+### Changed
+- Tightened picker header by removing empty spacing between top border and dialog title.
+- Updated picker footer legend to use clean `[Key] Action` layout with colored accent highlighting for model counter.
+
+---
+
+## [1.0.13] - 2026-09-22
+
+### Added
+- Added `ctrl+shift+q` shortcut to reset the entire fallback model chain in one keystroke.
+
+### Changed
+- Polished picker footer spacing and legend descriptions.
+
+---
+
+## [1.0.12] - 2026-09-22
+
+### Added
+- Footer key legend in the interactive picker with clear separator formatting.
+
+---
+
+## [1.0.11] - 2026-09-12
+
+### Added
+- In-picker failover chain configuration (`ctrl+q` / `f2`) with real-time preview in the detail pane.
+- Auto-healing and detection for GLM 4/5 false-vision and provider HTTP 400 errors.
+
+### Changed
+- Major model picker architecture overhaul with connected-only provider credentials filtering.
+
+---
+
+## [1.0.0] - 2026-08-21
+
+### Added
+- Initial standalone release of `pi-vision-watcher` providing intelligent vision handoff to text-only coding models in Pi.

package/README.md

@@ -1,129 +1,137 @@
-<div align="center">
-
-# pi-vision-watcher
-
-Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision — images are described by a vision model you pick, then handed off to text-only coding models without interrupting your workflow.
-
-[pi package](https://pi.dev/packages/@bismawy/pi-vision-watcher) · [npm](https://www.npmjs.com/package/@bismawy/pi-vision-watcher) · [Issues](https://github.com/bismawy/pi-vision-watcher/issues)
-
-![npm](https://img.shields.io/npm/v/@bismawy/pi-vision-watcher)
-![license](https://img.shields.io/badge/license-MIT-green)
-
-</div>
-
-<img src="assets/screenshot.webp" alt="pi-vision-watcher" width="100%">
-
-## What it does
-
-Paste an image, attach a file, or have the agent `read` one — pi-vision-watcher describes it in the background with your chosen vision model and feeds the description to whatever text-only model you're using (DeepSeek, local models, etc.).
-
-- **Connected-only picker:** `/vision-watcher` shows only vision-capable models from providers where you actually have credentials.
-- **Batching & cache:** multiple images across parallel tool calls are batched into one describer request; cached images (SHA-256) are never re-described.
-- **False-vision healing:** aggregator providers sometimes flag text-only models as multimodal, causing HTTP 400s. The extension proactively forces handoff for them and auto-heals `models.json` in-process.
-- **Thinking controls:** adjust reasoning effort (`off` – `max`) for reasoning-capable vision models.
-- **Fallback chains:** automatically falls back to backup vision models when the primary is rate-limited or down.
-
-## Install
-
-```bash
-pi install npm:@bismawy/pi-vision-watcher
-```
-
-Then run `/vision-watcher` to pick your vision model (or set it directly: `/vision-watcher model openai/gpt-4o`). Handoff is on by default — just switch to any text-only model and work as usual.
-
-## Commands
-
-| Command | Action |
-| :--- | :--- |
-| `/vision-watcher` | Interactive picker for connected vision models |
-| `/vision-watcher model <provider/id>` | Set primary vision describer directly |
-| `/vision-watcher status` | View current configuration |
-| `/vision-watcher auto <on\|off>` | Toggle automatic handoff (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>` | Configure reasoning effort |
-| `/vision-watcher timeout <ms>` | Set the base per-image description timeout (default `45000`) |
-| `/vision-watcher prewarm <on\|off>` | Describe pasted images at paste-time (opt-in) |
-| `/vision-watcher async <on\|off>` | Inject pasted-image descriptions asynchronously when no matching `read` wins (alias: `fallback`) |
-| `/vision-watcher clear` | Clear the configured vision model |
-| `/vision-watcher enable` / `disable` | Toggle extension active state |
-| `/vision-watcher help` | List all subcommands |
-
-`async` is the async *clipboard* fallback and has nothing to do with the
-`fallbackModels` failover chain.
-
-In the picker:
-
-| Key | Action |
-|---|---|
-| `space` | Select the highlighted model as the primary describer (press again to clear) |
-| `ctrl+q` | Toggle the highlighted model in/out of the failover chain (marked 🔁, max 3). Not a mnemonic, and that's on purpose: `ctrl+f` is pi's find-text (bound since pi 0.85), `alt+f` is editor word-right, and `ctrl+alt+f` never survives Windows conhost/Windows Terminal. pi 0.85 also binds `ctrl+q` to `app.message.followUp`, which is inert while a picker is open — if it ever double-fires, `f2` is the free fallback (unbound in 0.84 and 0.85) |
-| `ctrl+t` | Walk the thinking ladder: off → minimal → low → medium → high → xhigh → max → off → … |
-| `ctrl+a` | Toggle async paste handoff |
-| `enter` / `ctrl+s` | Save (primary **and** chain together) |
-| `esc` | Cancel |
-
-The detail pane always shows the current configuration — primary, chain,
-thinking, async handoff — so every keypress shows exactly what will be saved.
-`space` is left to the search box while a filter query is present, so multi-word
-searches like `gemini 3.8` stay typeable.
-
-## How it works
-
-<details>
-<summary><b>Configuration</b> (<code>~/.pi/agent/extensions/pi-vision-watcher.json</code>)</summary>
-
-```json
-{
-  "enabled": true,
-  "visionModel": "openai/gpt-4o",
-  "fallbackModels": [],
-  "autoHandoff": true,
-  "handoffModels": [],
-  "thinking": false,
-  "thinkingLevel": "medium",
-  "describeTimeoutMs": 45000,
-  "prewarmPastedImages": false,
-  "asyncClipboardHandoff": false,
-  "maxTokens": null,
-  "cacheMax": 50,
-  "maxDescriptionLines": 0
-}
-```
-
-Most fields have sane defaults — `visionModel` is the only one you normally set.
-
-`fallbackModels` is the failover chain: when the primary describer fails (timeout,
-rate limit, auth), each entry is tried **in order** — fallback 1 fails, fallback 2
-runs, and so on until one returns a description. The picker caps the chain at 3
-entries (`ctrl+q`). Set it from the picker instead of hand-editing the file.
-
-</details>
-
-<details>
-<summary><b>Diagnostics & recovery</b></summary>
-
-- Failed vision calls log with stack traces to `~/.pi/agent/logs/pi-vision-watcher/errors.log` and degrade gracefully to `[Image: description unavailable]`.
-- When a model falsely advertises image capability and 400s, the error is captured on `message_end`, `modelOverrides.<model>.input = ["text"]` is written to `models.json`, and the registry refreshes in-process.
-
-</details>
-
-<details>
-<summary><b>Development</b></summary>
-
-```bash
-bun install
-bun run test          # Vitest suite (240+ unit tests)
-bun run typecheck
-bun run lint:dead
-```
-
-</details>
-
-## License
-
-Distributed under the **MIT** license.
-
-## Developer
-
-Developed and maintained by [Bisma](https://github.com/bismawy).
+# Vision Watcher
+
+Intelligent vision watcher. Connected models. Zero workflow interruption.
+
+[![Custom badge](https://shieldcn.dev/badge/pi-%20Packages.svg?variant=outline&size=xs&logo=ri%3APiPiBold)](https://pi.dev/packages/@bismawy/pi-vision-watcher)
+[![badge](https://shieldcn.dev/npm/@bismawy/pi-vision-watcher.svg?variant=outline&size=xs)](https://www.npmjs.com/package/@bismawy/pi-vision-watcher)
+[![license](https://shieldcn.dev/github/bismawy/pi-vision-watcher/license.svg?variant=outline&size=xs)](https://github.com/bismawy/pi-vision-watcher)
+
+<img src="https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/banner.webp" alt="Vision Watcher: intelligent vision watcher for text-only coding models in Pi" width="100%">
+
+## Overview
+
+pi-vision-watcher gives text-only pi models vision — images are described in the background by a vision model you pick, watching over text-only coding models without interrupting your workflow.
+
+- Connected-only Picker: `/vision-watcher` filters models to connected providers with valid credentials.
+- Batching & Cache: Parallel tool calls batch images into one request; SHA-256 cache prevents redundant descriptions.
+- False-Vision Healing: Proactively detects text-only models falsely advertised as multimodal and auto-heals `models.json` on HTTP 400.
+- Thinking Controls: Configurable reasoning effort (`off` – `max`) for reasoning-capable vision models.
+- Failover Chains: Ordered fallbacks to backup vision models on timeouts, rate limits, or auth errors.
+
+## Install
+
+```bash
+pi install npm:@bismawy/pi-vision-watcher
+```
+
+Run `/vision-watcher` to pick a vision model (or `/vision-watcher model <provider/id>`). Handoff is enabled by default.
+
+To test locally without installing:
+```bash
+pi --extension ./vision-watcher.ts
+```
+
+## Shortcuts
+
+| Key | Action |
+| --- | --- |
+| `space` | Toggle highlighted model as primary describer |
+| `ctrl+enter` | Toggle highlighted model in/out of failover chain (marked ⇆, max 3) |
+| `ctrl+shift+r` | Reset failover chain |
+| `alt+↑` · `alt+↓` | Reorder the highlighted model (the chain follows list order) |
+| `ctrl+shift+t` | Walk thinking ladder (`off` → `minimal` → `low` → `medium` → `high` → `xhigh` → `max`) |
+| `ctrl+alt+a` | Toggle async paste handoff (`alt+a` also works on Windows/macOS) |
+| `enter` · `ctrl+s` | Save configuration (primary describer and chain) |
+| `esc` | Cancel and exit picker |
+
+> **Notes:**
+> - In filter mode, `space` enters a space character so multi-word queries (e.g. `gemini 3.8`) stay typeable; press `enter` to adopt the highlighted match as the primary describer.
+> - The detail pane renders live preview updates before saving.
+> - Chords are chosen to avoid POSIX tty flow control (`ctrl+s`/`ctrl+q`), VTE's window-level `ctrl+shift+q`, readline keys (`ctrl+a`/`ctrl+t`) and pi's own bindings. `ctrl+enter` works on Windows Terminal/conhost, X11, macOS, tmux and SSH. `ctrl+alt+a` is the safe half of the async chord on international layouts, where AltGr occupies `alt+a`.
+
+## Commands
+
+| Command | Action |
+| --- | --- |
+| `/vision-watcher` | Interactive picker for connected vision models |
+| `/vision-watcher model <provider/id>` | Set primary vision describer directly |
+| `/vision-watcher status` | View active configuration and failover chain |
+| `/vision-watcher auto <on\|off>` | Toggle automatic handoff (default: `on`) |
+| `/vision-watcher add \| remove <provider/id>` | Force or unforce handoff on specific models |
+| `/vision-watcher thinking <level>` | Configure reasoning effort (`off` – `max`) |
+| `/vision-watcher timeout <ms>` | Set per-image description timeout in ms (default: `45000`) |
+| `/vision-watcher prewarm \| async <on\|off>` | Toggle paste-time prewarming or async clipboard fallback |
+| `/vision-watcher clear` | Clear configured vision model |
+| `/vision-watcher enable \| disable` | Toggle extension active state |
+| `/vision-watcher help` | List all subcommands |
+
+## Architecture
+
+<details>
+<summary><b>Configuration</b> (<code>~/.pi/agent/extensions/pi-vision-watcher.json</code>)</summary>
+
+```json
+{
+  "enabled": true,
+  "visionModel": "openai/gpt-4o",
+  "fallbackModels": [],
+  "autoHandoff": true,
+  "handoffModels": [],
+  "thinking": false,
+  "thinkingLevel": "medium",
+  "describeTimeoutMs": 45000,
+  "prewarmPastedImages": false,
+  "asyncClipboardHandoff": false,
+  "maxTokens": null,
+  "cacheMax": 50,
+  "maxDescriptionLines": 0
+}
+```
+
+Most fields have sane defaults — `visionModel` is the only one you normally set.
+
+`fallbackModels` is the failover chain: when the primary describer fails (timeout, rate limit, auth), each entry is tried **in order** until one returns a description. The picker caps the chain at 3 entries (`ctrl+enter`). Set it from the picker instead of hand-editing the file.
+
+</details>
+
+<details>
+<summary><b>Diagnostics & Recovery</b></summary>
+
+- Failed vision calls log with stack traces to `~/.pi/agent/logs/pi-vision-watcher/errors.log` and degrade gracefully to `[Image: description unavailable]`.
+- When a model falsely advertises image capability and 400s, the error is captured on `message_end`, `modelOverrides.<model>.input = ["text"]` is written to `models.json`, and the registry refreshes in-process.
+
+</details>
+
+<details>
+<summary><b>Components</b></summary>
+
+| File | Role |
+| --- | --- |
+| `vision-watcher.ts` | Extension entry point, lifecycle hooks, and CLI command handlers |
+| `src/vision-model-selector.ts` | Interactive TUI model picker with connected-only filtering |
+| `src/describer.ts` | Vision API request orchestration, multi-image batching, and failover chains |
+| `src/dataloader.ts` | Batched image loader to prevent redundant parallel requests |
+| `src/image.ts` | Image hashing (SHA-256), memory caching, and MIME detection |
+| `src/prewarm-editor.ts` | Paste-time image prewarming and async clipboard injection |
+| `src/error-log.ts` | Structured logging and error capture |
+
+</details>
+
+<details>
+<summary><b>Development</b></summary>
+
+```bash
+npm test          # Vitest suite (250+ unit tests)
+npm run typecheck # TypeScript checks
+npm run lint:dead # Knip dead code analysis
+```
+
+</details>
+
+## License
+
+Distributed under the **MIT** license.
+
+## Author
+
+[Bisma](https://github.com/bismawy)

package/package.json

@@ -1,68 +1,72 @@
-{
-  "name": "@bismawy/pi-vision-watcher",
-  "version": "1.0.14",
-  "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",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bismawy/pi-vision-watcher.git"
-  },
-  "homepage": "https://github.com/bismawy/pi-vision-watcher#readme",
-  "bugs": {
-    "url": "https://github.com/bismawy/pi-vision-watcher/issues"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "pi-vision-watcher",
-    "pi-vision-handoff",
-    "pi",
-    "pi-coding-agent",
-    "extension",
-    "vision",
-    "image",
-    "handoff",
-    "multimodal",
-    "model-selector",
-    "accessibility"
-  ],
-  "files": [
-    "*.ts",
-    "src/",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint:dead": "knip --no-gitignore"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
-    "@types/node": "25.9.1",
-    "@vitest/coverage-v8": "4.1.7",
-    "knip": "6.14.1",
-    "typescript": "6.0.3",
-    "vitest": "4.1.7"
-  },
-  "pi": {
-    "extensions": [
-      "./vision-watcher.ts"
-    ],
-    "image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/screenshot.webp"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  },
-  "packageManager": "pnpm@11.20.0"
-}
+{
+  "name": "@bismawy/pi-vision-watcher",
+  "version": "1.1.0",
+  "description": "Intelligent vision watcher. Connected models. Zero workflow interruption. Text-only Pi models get background image descriptions with failover chains.",
+  "type": "module",
+  "author": "bismawy",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bismawy/pi-vision-watcher.git"
+  },
+  "homepage": "https://github.com/bismawy/pi-vision-watcher#readme",
+  "bugs": {
+    "url": "https://github.com/bismawy/pi-vision-watcher/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-vision-watcher",
+    "vision-watcher",
+    "pi",
+    "pi-coding-agent",
+    "vision",
+    "image-describer",
+    "image-description",
+    "multimodal",
+    "model-selector",
+    "model-picker",
+    "failover",
+    "accessibility"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "dev": "pi --extension ./vision-watcher.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "pi": {
+    "extensions": [
+      "./vision-watcher.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/banner.webp"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "packageManager": "pnpm@11.20.0"
+}