pi-vision-handoff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tom X Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+<div align="center">
+
+# 👁️ pi-vision-handoff
+
+**Give text-only [pi](https://github.com/earendil-works/pi-coding-agent) models vision**
+
+_Describe images with a vision model you pick, then feed the text to models that can't see._
+
+[![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/pi-vision-handoff)](https://www.npmjs.com/package/pi-vision-handoff)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+## The Problem
+
+Some of the best coding models are blind. You paste a screenshot, a UI mock, a stack trace, or a diagram into pi — and a text-only model either silently ignores the image or rejects the request outright. Up to now your only options were to describe the image yourself, or switch to a (often weaker-for-coding) vision model just to read it.
+
+The `pi-umans-provider` extension quietly solved this for GLM 5.1: a hardcoded "vision handoff" pipeline that had `umans-flash` describe each image at prompt time and swapped the text in for the image block before the request left. It worked great — but it was welded to one provider, one describer, and one set of models.
+
+## The Solution
+
+`pi-vision-handoff` extracts that pipeline and makes it **provider-agnostic**:
+
+- **Pick any vision-capable model** from your registry via an interactive picker — OpenAI, Anthropic, Google, Ollama, or any custom provider pi knows about.
+- Your choice **persists** to `~/.pi/agent/extensions/pi-vision-handoff.json`.
+- For any model that doesn't declare image input (or any model you explicitly target), `pi-vision-handoff` describes the image with your chosen vision model **before** the request is sent, then **swaps the image block for the description** in the actual provider payload.
+- Works across all three request formats pi uses — OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages — detected by block shape.
+- Descriptions are **cached per image hash** (LRU), so the swap is instant by the time the request fires.
+
+No `settings.json` touched. No per-provider glue. Pick a describer once and every text-only model you own can suddenly see.
+
+## Features
+
+- **🎮 Interactive picker** — `/vision-handoff` opens a TUI listing every model, vision-capable ones first (👁), to choose your describer.
+- **🔌 Provider-agnostic** — uses pi's own model execution machinery (`@earendil-works/pi-ai`'s `complete()`), so it works with any provider/configured model, including custom provider extensions.
+- **🧠 Automatic targets** — by default, handoff applies to *every* model that lacks native vision. Opt out with `/vision-handoff auto off`.
+- **🗂️ Explicit overrides** — force handoff for specific models (e.g. a weak vision model) with `/vision-handoff add`.
+- **⚡ Cache-warmed** — `before_agent_start` describes attached images the moment you submit, so the request is rarely delayed.
+- **🛡️ Graceful degradation** — no API key? Describer unreachable? Aborted? The image is replaced with a clean `[Image: description unavailable]` placeholder instead of crashing your turn.
+- **🔧 Tunable** — cap description length and cache size in the config file.
+
+## Usage
+
+### Interactive Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/vision-handoff` | Open the interactive picker to choose the vision model |
+| `/vision-handoff select` | Same as `/vision-handoff` |
+| `/vision-handoff model openai/gpt-4o` | Set the vision model directly |
+| `/vision-handoff status` | Show current config + whether handoff is active for the current model |
+| `/vision-handoff enable` / `disable` | Master switch (keeps your configured model) |
+| `/vision-handoff auto on` / `off` | Toggle automatic handoff for all non-vision models |
+| `/vision-handoff add ollama/llava:13b` | Force handoff for an extra model |
+| `/vision-handoff remove ollama/llava:13b` | Stop forcing handoff for a model |
+| `/vision-handoff clear` | Clear the configured vision model |
+| `/vision-handoff help` | Show usage reference |
+
+### Config File
+
+Created automatically at `~/.pi/agent/extensions/pi-vision-handoff.json` on first change:
+
+```json
+{
+  "enabled": true,
+  "visionModel": "openai/gpt-4o",
+  "autoHandoff": true,
+  "handoffModels": ["ollama/llava:13b"],
+  "maxTokens": 1024,
+  "cacheMax": 50,
+  "prompt": "Describe this image exhaustively…",
+  "userPromptPrefix": "The user's request about this image: "
+}
+```
+
+| Field | Default | Effect |
+|-------|---------|--------|
+| `enabled` | `true` | Master switch. When `false`, no handoff occurs. |
+| `visionModel` | `null` | The describer, as `provider/id`. `null` = not configured (handoff inactive). |
+| `autoHandoff` | `true` | Apply handoff to every model whose `input` does not include `image`. |
+| `handoffModels` | `[]` | Extra `provider/id` refs that should also receive handoff. |
+| `maxTokens` | `1024` | Cap on a single description's output. |
+| `cacheMax` | `50` | Max described images kept in the in-memory cache per session. |
+| `prompt` | _(built-in)_ | Override the describer system prompt. |
+| `userPromptPrefix` | _(built-in)_ | Override the prefix prepended to your original prompt. |
+
+> The config path uses pi's `getAgentDir()` — set `PI_CODING_AGENT_DIR` to relocate it.
+
+## Installation
+
+**With `pi install`** (recommended):
+
+```bash
+pi install npm:pi-vision-handoff
+```
+
+Or install from GitHub:
+
+```bash
+pi install https://github.com/monotykamary/pi-vision-handoff
+```
+
+**With npm**:
+
+```bash
+npm install pi-vision-handoff
+```
+
+Or in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    "npm:pi-vision-handoff"
+  ]
+}
+```
+
+Then `/reload` or restart pi.
+
+For a quick one-off test:
+
+```bash
+pi -e ./vision-handoff.ts
+```
+
+## How It Works
+
+```
+You submit a prompt + image, on a text-only model
+  → before_agent_start
+      • is this model a handoff target? (non-vision, or in handoffModels)
+      • for each attached image → describeImage() with your chosen vision model
+          - complete() via pi-ai (resolves API key/headers/baseUrl for you)
+          - cached by sha256(mime + base64)
+      • fire-and-forget — warms the cache
+  → before_provider_request
+      • walk the provider payload's messages[]
+      • for every image block (detected by shape) → swap for a text block:
+          "[Image: <cached description>]"
+      • returns the modified payload to pi
+
+Result: the text-only model receives a vivid text description in place of
+the image, and your turn proceeds normally.
+```
+
+### Image-block formats handled
+
+| API | Image block shape | Replacement |
+|-----|-------------------|-------------|
+| OpenAI Chat Completions | `{ type: "image_url", image_url: { url: "data:…" } }` | `{ type: "text", text }` |
+| OpenAI Responses | `{ type: "input_image", image_url: "data:…" }` | `{ type: "input_text", text }` |
+| Anthropic Messages | `{ type: "image", source: { type: "base64", media_type, data } }` | `{ type: "text", text }` |
+
+The describer call itself goes through pi's normal model machinery (`complete()`), **not** the agent event loop — so it never re-triggers `before_provider_request` (no recursion).
+
+## Comparison with Alternatives
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **pi-vision-handoff** (this) | Provider-agnostic; pick any describer; automatic for text-only models; cached; survives across providers | Adds one extra model call per unique image |
+| Native vision on every model | Zero overhead | Not all models support it; you may be forced off your preferred coding model |
+| Manually describing images | No extension | Tedious; lossy; kills the "paste a screenshot" workflow |
+| The original `pi-umans-provider` handoff | Battle-tested | Hardcoded to `umans-flash` + UMANS models only |
+| Switching to a vision model to read an image, then back | Works | Context loss across model swaps; worse coding model for the actual work |
+
+## Development
+
+```bash
+pnpm install
+pnpm test          # Vitest unit tests (31 passing)
+pnpm typecheck     # TypeScript validation
+pnpm lint:dead     # Dead code detection (knip)
+```
+
+### Structure
+
+```
+.
+├── vision-handoff.ts            # Main extension: hooks, command, describer
+├── src/
+│   ├── index.ts                  # Config schema, read/write, image-block helpers
+│   └── vision-model-selector.ts  # Interactive picker TUI component
+├── __tests__/unit/
+│   ├── config-dir.test.ts        # Ensures getAgentDir() usage
+│   └── vision-handoff.test.ts    # Config, refs, image-block extraction, round-trip
+├── package.json
+├── tsconfig.json
+├── knip.json
+└── vitest.config.ts
+```
+
+## Acknowledgements
+
+The vision handoff concept and the exhaustive describer prompt originate from
+the [pi-umans-provider](https://github.com/monotykamary/pi-umans-provider) GLM 5.1
+pipeline. The picker TUI builds on the patterns from
+[pi-hide-providers](https://github.com/monotykamary/pi-hide-providers), which in
+turn mirror pi core's built-in selectors.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-vision-handoff",
+  "version": "0.1.0",
+  "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": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-vision-handoff.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-vision-handoff#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-vision-handoff/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "vision",
+    "image",
+    "handoff",
+    "multimodal",
+    "model-selector",
+    "accessibility"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.79.10",
+    "@earendil-works/pi-coding-agent": "0.79.4",
+    "@earendil-works/pi-tui": "0.79.4",
+    "@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-handoff.ts"
+    ]
+  },
+  "peerDependencies": {},
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  }
+}

package/src/index.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared constants, types, and utilities for pi-vision-handoff.
+ *
+ * Config lives at ~/.pi/agent/extensions/pi-vision-handoff.json — the same
+ * convention pi-model-sort uses for picker-backed extensions.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Subdirectory under the pi agent dir where picker extensions store config. */
+const CONFIG_SUBDIR = "extensions";
+
+/** Config file name. */
+export const CONFIG_FILENAME = "pi-vision-handoff.json";
+
+/** Full config path: ~/.pi/agent/extensions/pi-vision-handoff.json */
+export function getConfigPath(): string {
+  return join(getAgentDir(), CONFIG_SUBDIR, CONFIG_FILENAME);
+}
+
+/** Description shown in the / commands list. */
+export const HANDOFF_COMMAND_DESCRIPTION =
+  "Configure vision handoff — pick a vision model to describe images for text-only models";
+
+/** Default system prompt for the vision describer. Mirrors the pi-umans-provider pipeline. */
+export const DEFAULT_VISION_PROMPT =
+  "You are a vision assistant for a coding agent. Describe this image exhaustively. Cover: all visible text (verbatim if possible), code snippets, UI layout and widgets, diagrams and flow arrows, error messages and stack traces, file trees, terminal output, color and style details, spatial relationships between elements, and anything else a developer would need to act on this image. Do not summarize — be exhaustive.";
+
+/** Prefix prepended to the user's original prompt when describing an image. */
+export const DEFAULT_USER_PROMPT_PREFIX = "The user's request about this image: ";
+
+/** Placeholder text block injected in place of an image block. */
+export const IMAGE_PLACEHOLDER_PREFIX = "[Image: ";
+export const IMAGE_PLACEHOLDER_SUFFIX = "]";
+
+/** Default max output tokens for a single image description. */
+export const DEFAULT_MAX_TOKENS = 1024;
+
+/** Default vision cache size (number of described images kept in memory per session). */
+export const DEFAULT_CACHE_MAX = 50;
+
+/** Per-description request timeout. */
+export const DESCRIBE_TIMEOUT_MS = 30_000;
+
+export interface VisionHandoffConfig {
+  /** Master switch. When false, no handoff occurs even if a vision model is configured. */
+  enabled: boolean;
+  /** The vision-capable model that describes images, as "provider/id". null = not configured. */
+  visionModel: string | null;
+  /** When true (default), handoff is applied to every model whose input does not include "image". */
+  autoHandoff: boolean;
+  /** Extra "provider/id" refs that should ALSO receive handoff (e.g. weak vision models). */
+  handoffModels: string[];
+  /** Max output tokens for a single description. */
+  maxTokens: number;
+  /** Max images kept in the in-memory description cache. */
+  cacheMax: number;
+  /** Override the describer system prompt (defaults to DEFAULT_VISION_PROMPT). */
+  prompt?: string;
+  /** Override the user-prompt prefix (defaults to DEFAULT_USER_PROMPT_PREFIX). */
+  userPromptPrefix?: string;
+}
+
+export const DEFAULT_CONFIG: VisionHandoffConfig = {
+  enabled: true,
+  visionModel: null,
+  autoHandoff: true,
+  handoffModels: [],
+  maxTokens: DEFAULT_MAX_TOKENS,
+  cacheMax: DEFAULT_CACHE_MAX,
+};
+
+/** Parse a "provider/id" reference. Returns null if malformed. */
+export function parseModelRef(ref: string): { provider: string; id: string } | null {
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+  const slashIndex = trimmed.indexOf("/");
+  if (slashIndex <= 0) return null; // no slash, or empty provider
+  const provider = trimmed.slice(0, slashIndex);
+  const id = trimmed.slice(slashIndex + 1);
+  if (!provider || !id) return null;
+  return { provider, id };
+}
+
+/** Format a provider/id reference string. */
+export function formatModelRef(provider: string, id: string): string {
+  return `${provider}/${id}`;
+}
+
+/** 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");
+}
+
+/** Merge a parsed config object onto defaults, tolerating missing/invalid fields. */
+export function normalizeConfig(raw: unknown): VisionHandoffConfig {
+  const base: VisionHandoffConfig = { ...DEFAULT_CONFIG };
+  if (!raw || typeof raw !== "object") return base;
+  const obj = raw as Record<string, unknown>;
+
+  if (typeof obj.enabled === "boolean") base.enabled = obj.enabled;
+  if (typeof obj.visionModel === "string" && obj.visionModel.trim()) {
+    base.visionModel = parseModelRef(obj.visionModel) ? obj.visionModel.trim() : null;
+  } else if (obj.visionModel === null) {
+    base.visionModel = null;
+  }
+  if (typeof obj.autoHandoff === "boolean") base.autoHandoff = obj.autoHandoff;
+
+  if (Array.isArray(obj.handoffModels)) {
+    base.handoffModels = obj.handoffModels
+      .filter((m): m is string => typeof m === "string")
+      .map((m) => m.trim())
+      .filter((m) => m && parseModelRef(m));
+  }
+  if (typeof obj.maxTokens === "number" && Number.isFinite(obj.maxTokens) && obj.maxTokens > 0) {
+    base.maxTokens = Math.floor(obj.maxTokens);
+  }
+  if (typeof obj.cacheMax === "number" && Number.isFinite(obj.cacheMax) && obj.cacheMax > 0) {
+    base.cacheMax = Math.floor(obj.cacheMax);
+  }
+  if (typeof obj.prompt === "string" && obj.prompt.trim()) base.prompt = obj.prompt;
+  if (typeof obj.userPromptPrefix === "string") base.userPromptPrefix = obj.userPromptPrefix;
+
+  return base;
+}
+
+/** Read config from disk (falls back to defaults on missing/corrupt file). */
+export function readConfig(): VisionHandoffConfig {
+  const path = getConfigPath();
+  if (!existsSync(path)) return { ...DEFAULT_CONFIG };
+  try {
+    const raw = readFileSync(path, "utf8");
+    return normalizeConfig(JSON.parse(raw));
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+/** Write config to disk. Creates the directory if needed. Returns the path written. */
+export function writeConfig(config: VisionHandoffConfig): string {
+  const path = getConfigPath();
+  const dir = join(getAgentDir(), CONFIG_SUBDIR);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  return path;
+}
+
+export interface ExtractedImage {
+  data: string;
+  mimeType: string;
+}
+
+/** Parse a `data:<mime>;base64,<data>` URL into raw base64 + mime. Returns null if not a data URL. */
+export function parseDataUrl(url: string): ExtractedImage | null {
+  const match = /^data:([^;,]+)?(?:;base64)?,(.*)$/s.exec(url);
+  if (!match) return null;
+  return { mimeType: match[1] || "image/png", data: match[2] };
+}
+
+/**
+ * Detect an image block by shape across the three request formats pi uses:
+ *   openai-completions: { type: "image_url",  image_url: { url: "data:..." } }
+ *   openai-responses:   { type: "input_image", image_url: "data:..." | { url } }
+ *   anthropic-messages: { type: "image", source: { type: "base64", media_type, data } }
+ */
+export function extractImageFromBlock(block: unknown): ExtractedImage | null {
+  if (!block || typeof block !== "object") return null;
+  const b = block as Record<string, any>;
+
+  if (b.type === "image_url" && typeof b.image_url?.url === "string") {
+    return parseDataUrl(b.image_url.url);
+  }
+
+  if (b.type === "input_image") {
+    const url = typeof b.image_url === "string" ? b.image_url : b.image_url?.url;
+    if (typeof url === "string") return parseDataUrl(url);
+    return null;
+  }
+
+  if (b.type === "image" && b.source?.type === "base64" && typeof b.source.data === "string") {
+    return { data: b.source.data, mimeType: b.source.media_type || "image/png" };
+  }
+
+  return null;
+}
+
+/** Build a text block that replaces an image block, matching the request format. */
+export function makeReplacementText(block: unknown, description: string): Record<string, unknown> {
+  const b = (block ?? null) as Record<string, unknown> | null;
+  if (b?.type === "input_image") {
+    return { type: "input_text", text: description };
+  }
+  return { type: "text", text: description };
+}

package/src/vision-model-selector.ts

@@ -0,0 +1,333 @@
+/**
+ * VisionModelSelectorComponent — an interactive TUI for choosing which model
+ * describes images during vision handoff.
+ *
+ * Uses the same patterns as pi's built-in selectors and pi-hide-providers:
+ * - Lists all models, vision-capable ones first (👁 badge)
+ * - A leading "None" row clears the configured vision model
+ * - Search/filter via Input component
+ * - Enter or Ctrl+S confirms the highlighted model and saves
+ * - Esc / Ctrl+C cancels
+ * - The currently configured vision model is marked ✓
+ */
+
+import {
+  Container,
+  type Component,
+  fuzzyFilter,
+  getKeybindings,
+  Input,
+  Key,
+  matchesKey,
+  Spacer,
+  Text,
+} from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, keyText } from "@earendil-works/pi-coding-agent";
+import { formatModelRef, isVisionModel } from "./index.js";
+
+interface DisplayItem {
+  /** "provider/id", or null for the synthetic "None" row. */
+  ref: string | null;
+  provider: string;
+  modelId: string;
+  modelName: string;
+  vision: boolean;
+  none?: boolean;
+}
+
+export interface VisionModelSelectorResult {
+  /** The selected "provider/id", or null if the user picked "None" / cancelled. */
+  ref: string | null;
+  /** True if the user cancelled (esc) — config should not change. */
+  cancelled: boolean;
+}
+
+export class VisionModelSelectorComponent implements Component {
+  private theme: Theme;
+  private done: (result: VisionModelSelectorResult) => void;
+
+  private allItems: DisplayItem[];
+  private filteredItems: DisplayItem[];
+  private selectedIndex = 0;
+  private readonly maxVisible = 10;
+  private searchInput: Input;
+  private listContainer: Container;
+  private footerText: Text;
+
+  private currentRef: string | null;
+
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor(
+    theme: Theme,
+    allModels: Array<{ provider: string; id: string; name: string; input?: ("text" | "image")[] }>,
+    currentRef: string | null,
+    done: (result: VisionModelSelectorResult) => void,
+  ) {
+    this.theme = theme;
+    this.done = done;
+    this.currentRef = currentRef;
+    this.allItems = this.buildItems(allModels);
+    this.filteredItems = this.allItems;
+
+    const startIdx = this.allItems.findIndex((i) => i.ref === currentRef);
+    this.selectedIndex = startIdx >= 0 ? startIdx : 0;
+
+    this.searchInput = new Input();
+    this.listContainer = new Container();
+    this.footerText = new Text(this.getFooterText(), 0, 0);
+
+    this.searchInput.onSubmit = () => {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+    };
+
+    this.updateList();
+  }
+
+  render(width: number): string[] {
+    const lines: string[] = [];
+    lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
+    lines.push("");
+    lines.push(this.theme.fg("accent", this.theme.bold("Vision Handoff")));
+    lines.push(
+      this.theme.fg("muted", "Pick a vision-capable model to describe images for text-only models."),
+    );
+    lines.push("");
+    lines.push(...this.searchInput.render(width));
+    lines.push("");
+    lines.push(...this.listContainer.render(width));
+    lines.push("");
+    lines.push(...this.footerText.render(width));
+    lines.push(...new DynamicBorder((s) => this.theme.fg("accent", s)).render(width));
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    const kb = getKeybindings();
+
+    if (kb.matches(data, "tui.select.up")) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === 0
+          ? this.filteredItems.length - 1
+          : this.selectedIndex - 1;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "tui.select.down")) {
+      if (this.filteredItems.length === 0) return;
+      this.selectedIndex =
+        this.selectedIndex === this.filteredItems.length - 1
+          ? 0
+          : this.selectedIndex + 1;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "tui.select.confirm")) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("s"))) {
+      const item = this.filteredItems[this.selectedIndex];
+      if (item) this.confirm(item);
+      return;
+    }
+
+    if (matchesKey(data, Key.escape)) {
+      this.finish(true);
+      return;
+    }
+
+    if (matchesKey(data, Key.ctrl("c"))) {
+      if (this.searchInput.getValue()) {
+        this.searchInput.setValue("");
+        this.refresh();
+      } else {
+        this.finish(true);
+      }
+      return;
+    }
+
+    this.searchInput.handleInput(data);
+    this.refresh();
+  }
+
+  invalidate(): void {
+    this.searchInput.invalidate();
+    this.listContainer.invalidate();
+    this.footerText.invalidate();
+  }
+
+  // Internal helpers
+
+  private buildItems(
+    allModels: Array<{ provider: string; id: string; name: string; input?: ("text" | "image")[] }>,
+  ): DisplayItem[] {
+    const items: DisplayItem[] = [
+      {
+        ref: null,
+        provider: "",
+        modelId: "none",
+        modelName: "None — disable vision handoff",
+        vision: false,
+        none: true,
+      },
+    ];
+
+    const make = (m: {
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+    }): DisplayItem => ({
+      ref: formatModelRef(m.provider, m.id),
+      provider: m.provider,
+      modelId: m.id,
+      modelName: m.name || m.id,
+      vision: isVisionModel(m),
+    });
+
+    // Vision-capable first (registry order), then the rest (registry order).
+    const visionModels = allModels.filter((m) => isVisionModel(m)).map(make);
+    const textModels = allModels.filter((m) => !isVisionModel(m)).map(make);
+    return [...items, ...visionModels, ...textModels];
+  }
+
+  private getFooterText(): string {
+    const totalCount = this.allItems.length - 1; // exclude the None row
+    const visionCount = this.allItems.filter((i) => i.vision).length;
+
+    const current = this.currentRef
+      ? `current: ${this.currentRef}`
+      : "current: none";
+
+    const parts: string[] = [
+      `${keyText("tui.select.confirm")} select`,
+      `ctrl+s done`,
+      `esc cancel`,
+      this.searchInput.getValue() ? `${this.filteredItems.length - 1} match` : `${totalCount} models · ${visionCount} vision`,
+    ];
+
+    return this.theme.fg("dim", `  ${parts.join(" · ")} · ${current} `);
+  }
+
+  private refresh(): void {
+    const query = this.searchInput.getValue();
+    this.filteredItems = query
+      ? fuzzyFilter(
+          this.allItems,
+          query,
+          (i) => `${i.provider} ${i.modelId} ${i.ref ?? "none"} ${i.modelName}`,
+        )
+      : this.allItems;
+    this.selectedIndex = Math.min(
+      this.selectedIndex,
+      Math.max(0, this.filteredItems.length - 1),
+    );
+    this.updateList();
+  }
+
+  private updateList(): void {
+    this.listContainer.clear();
+
+    if (this.filteredItems.length === 0) {
+      this.listContainer.addChild(
+        new Text(this.theme.fg("muted", "  No matching models"), 0, 0),
+      );
+      this.footerText.setText(this.getFooterText());
+      return;
+    }
+
+    const startIndex = Math.max(
+      0,
+      Math.min(
+        this.selectedIndex - Math.floor(this.maxVisible / 2),
+        this.filteredItems.length - this.maxVisible,
+      ),
+    );
+    const endIndex = Math.min(startIndex + this.maxVisible, this.filteredItems.length);
+
+    for (let i = startIndex; i < endIndex; i++) {
+      const item = this.filteredItems[i];
+      if (!item) continue;
+
+      const isSelected = i === this.selectedIndex;
+      const prefix = isSelected ? this.theme.fg("accent", "→ ") : "  ";
+
+      let label: string;
+      if (item.none) {
+        label = this.theme.fg("warning", item.modelName);
+      } else {
+        const labelled = isSelected
+          ? this.theme.fg("accent", item.modelId)
+          : item.modelId;
+        const badge = item.vision ? this.theme.fg("success", " 👁") : this.theme.fg("muted", " ·");
+        const providerBadge = this.theme.fg("muted", ` [${item.provider}]`);
+        label = `${labelled}${providerBadge}${badge}`;
+      }
+
+      const current = item.ref === this.currentRef && item.ref !== null
+        ? this.theme.fg("success", " ✓")
+        : item.none && this.currentRef === null
+          ? this.theme.fg("success", " ✓")
+          : "";
+
+      this.listContainer.addChild(new Text(`${prefix}${label}${current}`, 0, 0));
+    }
+
+    if (startIndex > 0 || endIndex < this.filteredItems.length) {
+      this.listContainer.addChild(
+        new Text(
+          this.theme.fg("muted", `  (${this.selectedIndex + 1}/${this.filteredItems.length})`),
+          0, 0,
+        ),
+      );
+    }
+
+    const selected = this.filteredItems[this.selectedIndex];
+    if (selected) {
+      this.listContainer.addChild(new Spacer(1));
+      if (selected.none) {
+        this.listContainer.addChild(
+          new Text(this.theme.fg("muted", `  ${selected.modelName}`), 0, 0),
+        );
+      } else {
+        this.listContainer.addChild(
+          new Text(this.theme.fg("muted", `  Model Name: ${selected.modelName}`), 0, 0),
+        );
+        this.listContainer.addChild(
+          new Text(
+            this.theme.fg(
+              "dim",
+              `${selected.vision ? "👁 vision-capable — recommended describer" : "no native vision — not a good describer"}`,
+            ),
+            0, 0,
+          ),
+        );
+      }
+    }
+
+    this.footerText.setText(this.getFooterText());
+  }
+
+  private confirm(item: DisplayItem): void {
+    this.done({ ref: item.ref, cancelled: false });
+  }
+
+  private finish(cancelled: boolean): void {
+    this.done({ ref: null, cancelled });
+  }
+}

package/vision-handoff.ts

@@ -0,0 +1,479 @@
+/**
+ * pi-vision-handoff — give text-only models vision by proxying image input
+ * through a vision-capable model of your choice.
+ *
+ * Extracted from the GLM 5.1 vision-handoff pipeline in pi-umans-provider and
+ * generalized: instead of a hardcoded describer, the user picks any
+ * vision-capable model from the registry via an interactive picker, and the
+ * choice is persisted to ~/.pi/agent/extensions/pi-vision-handoff.json.
+ *
+ * Pipeline (provider-agnostic via @earendil-works/pi-ai's complete()):
+ *   before_agent_start → warm the description cache for attached images
+ *   before_provider_request → swap image blocks in the payload for text
+ *
+ * Image blocks are detected by shape across the three request formats pi uses:
+ *   openai-completions: { type: "image_url",  image_url: { url: "data:..." } }
+ *   openai-responses:   { type: "input_image", image_url: "data:..." }
+ *   anthropic-messages: { type: "image", source: { type: "base64", media_type, data } }
+ *
+ * Descriptions are cached per image hash (LRU, size = config.cacheMax) so the
+ * swap is instant by the time before_provider_request fires.
+ */
+
+import crypto from "node:crypto";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { complete } from "@earendil-works/pi-ai";
+import type { Api, ImageContent, Message, Model, TextContent } from "@earendil-works/pi-ai";
+import {
+  DEFAULT_USER_PROMPT_PREFIX,
+  DEFAULT_VISION_PROMPT,
+  DESCRIBE_TIMEOUT_MS,
+  HANDOFF_COMMAND_DESCRIPTION,
+  IMAGE_PLACEHOLDER_PREFIX,
+  IMAGE_PLACEHOLDER_SUFFIX,
+  extractImageFromBlock,
+  formatModelRef,
+  isVisionModel,
+  makeReplacementText,
+  parseModelRef,
+  readConfig,
+  writeConfig,
+  type VisionHandoffConfig,
+} from "./src/index.js";
+import { VisionModelSelectorComponent, type VisionModelSelectorResult } from "./src/vision-model-selector.js";
+
+const UNAVAILABLE = `${IMAGE_PLACEHOLDER_PREFIX}description unavailable${IMAGE_PLACEHOLDER_SUFFIX}`;
+
+let config: VisionHandoffConfig = readConfig();
+
+const visionCache = new Map<string, Promise<string>>();
+let visionModelCache: { ref: string; model: Model<Api> } | null = null;
+let visionModelUnresolvedRef: string | null = null;
+
+function isConfigured(cfg: VisionHandoffConfig): boolean {
+  return cfg.enabled && !!cfg.visionModel;
+}
+
+function isHandoffTarget(
+  model: { provider?: string; id?: string; input?: ("text" | "image")[] } | undefined | null,
+  cfg: VisionHandoffConfig,
+): boolean {
+  if (!model || !model.provider || !model.id) return false;
+  const ref = formatModelRef(model.provider, model.id);
+  if (cfg.handoffModels.includes(ref)) return true;
+  if (cfg.autoHandoff && !isVisionModel(model)) return true;
+  return false;
+}
+
+function resolveVisionModel(modelRegistry: ModelRegistry, ref: string): Model<Api> | null {
+  if (visionModelCache && visionModelCache.ref === ref) return visionModelCache.model;
+  const parsed = parseModelRef(ref);
+  if (!parsed) return null;
+  const model = modelRegistry.find(parsed.provider, parsed.id);
+  if (!model) return null;
+  visionModelCache = { ref, model };
+  return model;
+}
+
+function imageHash(mimeType: string, data: string): string {
+  return crypto.createHash("sha256").update(`${mimeType}\x00${data}`).digest("hex").slice(0, 32);
+}
+
+async function describeImage(
+  data: string,
+  mimeType: string,
+  userPrompt: string,
+  visionModel: Model<Api>,
+  modelRegistry: ModelRegistry,
+  cfg: VisionHandoffConfig,
+): Promise<string> {
+  const key = imageHash(mimeType, data);
+  const cached = visionCache.get(key);
+  if (cached) return cached;
+
+  const promise = (async (): Promise<string> => {
+    const auth = await modelRegistry.getApiKeyAndHeaders(visionModel);
+    if (!auth.ok || !auth.apiKey) return UNAVAILABLE;
+
+    const prefix = cfg.userPromptPrefix ?? DEFAULT_USER_PROMPT_PREFIX;
+    const systemPrompt = cfg.prompt ?? DEFAULT_VISION_PROMPT;
+
+    const content: (TextContent | ImageContent)[] = [];
+    if (userPrompt && userPrompt.trim()) {
+      content.push({ type: "text", text: prefix + userPrompt });
+    } else {
+      content.push({ type: "text", text: "Describe this image." } satisfies TextContent);
+    }
+    content.push({ type: "image", data, mimeType } satisfies ImageContent);
+
+    const userMessage: Message = {
+      role: "user",
+      content,
+      timestamp: Date.now(),
+    };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DESCRIBE_TIMEOUT_MS);
+    try {
+      const response = await complete(
+        visionModel,
+        { systemPrompt, messages: [userMessage] },
+        {
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+          signal: controller.signal,
+          maxTokens: cfg.maxTokens,
+        },
+      );
+      if (response.stopReason === "aborted" || response.stopReason === "error") {
+        return UNAVAILABLE;
+      }
+      const description = response.content
+        .filter((c): c is TextContent => c.type === "text")
+        .map((c) => c.text)
+        .join("\n")
+        .trim();
+      if (!description) return UNAVAILABLE;
+      return `${IMAGE_PLACEHOLDER_PREFIX}${description}${IMAGE_PLACEHOLDER_SUFFIX}`;
+    } catch {
+      return UNAVAILABLE;
+    } finally {
+      clearTimeout(timer);
+    }
+  })();
+
+  if (visionCache.size >= cfg.cacheMax) {
+    const firstKey = visionCache.keys().next().value;
+    if (firstKey !== undefined) visionCache.delete(firstKey);
+  }
+  visionCache.set(key, promise);
+
+  return promise;
+}
+
+async function replaceImagesWithDescriptions(
+  payload: Record<string, unknown>,
+  userPrompt: string,
+  visionModel: Model<Api>,
+  modelRegistry: ModelRegistry,
+  cfg: VisionHandoffConfig,
+): Promise<boolean> {
+  const messages = payload.messages;
+  if (!Array.isArray(messages)) return false;
+
+  let replaced = false;
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const content = (msg as Record<string, unknown>).content;
+    if (!Array.isArray(content)) continue;
+
+    for (let i = 0; i < content.length; i++) {
+      const img = extractImageFromBlock(content[i]);
+      if (!img) continue;
+      const description = await describeImage(img.data, img.mimeType, userPrompt, visionModel, modelRegistry, cfg);
+      content[i] = makeReplacementText(content[i], description);
+      replaced = true;
+    }
+  }
+  return replaced;
+}
+
+function notifyUnresolvedVisionModel(ctx: ExtensionContext, ref: string): void {
+  if (visionModelUnresolvedRef === ref) return;
+  visionModelUnresolvedRef = ref;
+  if (ctx.hasUI) {
+    ctx.ui.notify(
+      `pi-vision-handoff: configured vision model "${ref}" was not found in the registry — run /vision-handoff to pick a model.`,
+      "warning",
+    );
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  config = readConfig();
+
+  pi.on("session_start", async () => {
+    // Reload in case the user edited the config on disk from another session.
+    config = readConfig();
+    visionModelCache = null;
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!isConfigured(config)) return;
+    if (!isHandoffTarget(ctx.model, config)) return;
+    const images = event.images;
+    if (!images || images.length === 0) return;
+
+    const visionModel = resolveVisionModel(ctx.modelRegistry, config.visionModel!);
+    if (!visionModel) {
+      notifyUnresolvedVisionModel(ctx, config.visionModel!);
+      return;
+    }
+
+    const userPrompt = event.prompt || "";
+    for (const image of images) {
+      if (!image || image.type !== "image" || !image.data) continue;
+      const mimeType = image.mimeType || "image/png";
+      describeImage(image.data, mimeType, userPrompt, visionModel, ctx.modelRegistry, config).catch(
+        () => {},
+      );
+    }
+  });
+
+  pi.on("before_provider_request", async (event, ctx) => {
+    if (!isConfigured(config)) return;
+    if (!isHandoffTarget(ctx.model, config)) return;
+
+    const visionModel = resolveVisionModel(ctx.modelRegistry, config.visionModel!);
+    if (!visionModel) {
+      notifyUnresolvedVisionModel(ctx, config.visionModel!);
+      return;
+    }
+
+    const payload = event.payload as Record<string, unknown>;
+    await replaceImagesWithDescriptions(payload, "", visionModel, ctx.modelRegistry, config);
+    return payload;
+  });
+
+  pi.on("model_select", (event, ctx) => {
+    if (!ctx.hasUI) return;
+    if (!isConfigured(config)) return;
+    const model = event.model;
+    if (!model) return;
+    if (isHandoffTarget(model, config) && !isVisionModel(model)) {
+      ctx.ui.notify(
+        `pi-vision-handoff: active — images will be described by ${config.visionModel}`,
+        "info",
+      );
+    }
+  });
+
+  pi.registerCommand("vision-handoff", {
+    description: HANDOFF_COMMAND_DESCRIPTION,
+    getArgumentCompletions(prefix: string) {
+      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "add", "remove", "clear", "help"];
+      const matches = subcommands.filter((s) => s.startsWith(prefix));
+      return matches.length > 0 ? matches.map((s) => ({ value: s, label: s })) : null;
+    },
+    handler: async (args, ctx) => {
+      await handleHandoffCommand(ctx, args.trim());
+    },
+  });
+}
+
+async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string): Promise<void> {
+  const parts = args.split(/\s+/);
+  const subcommand = parts[0]?.toLowerCase() ?? "";
+  const rest = parts.slice(1).join(" ");
+
+  // /vision-handoff (no args) or /vision-handoff select — interactive picker
+  if (!subcommand || subcommand === "select") {
+    await showSelector(ctx);
+    return;
+  }
+
+  if (subcommand === "help") {
+    ctx.ui.notify(
+      [
+        "pi-vision-handoff commands:",
+        "  /vision-handoff                 Open interactive picker to choose the vision model",
+        "  /vision-handoff select         Same as /vision-handoff",
+        "  /vision-handoff model <p/id>   Set the vision model directly",
+        "  /vision-handoff status         Show current config and active state",
+        "  /vision-handoff enable         Enable vision handoff",
+        "  /vision-handoff disable        Disable vision handoff (keeps configured model)",
+        "  /vision-handoff auto <on|off>  Toggle automatic handoff for all non-vision models",
+        "  /vision-handoff add <p/id>     Force handoff for an extra model",
+        "  /vision-handoff remove <p/id>  Stop forcing handoff for a model",
+        "  /vision-handoff clear          Clear the configured vision model",
+        "  /vision-handoff help           This message",
+        "",
+        "Config: ~/.pi/agent/extensions/pi-vision-handoff.json",
+        "Mechanism: before_agent_start warms a description cache; before_provider_request",
+        "  swaps image blocks in the payload for the cached text description.",
+      ].join("\n"),
+      "info",
+    );
+    return;
+  }
+
+  if (subcommand === "status") {
+    showStatus(ctx);
+    return;
+  }
+
+  if (subcommand === "enable") {
+    updateConfig(ctx, (c) => ({ ...c, enabled: true }), "Vision handoff enabled.");
+    return;
+  }
+
+  if (subcommand === "disable") {
+    updateConfig(ctx, (c) => ({ ...c, enabled: false }), "Vision handoff disabled.");
+    return;
+  }
+
+  if (subcommand === "auto") {
+    const value = rest.toLowerCase();
+    if (value !== "on" && value !== "off") {
+      ctx.ui.notify("Usage: /vision-handoff auto <on|off>", "warning");
+      return;
+    }
+    const on = value === "on";
+    updateConfig(
+      ctx,
+      (c) => ({ ...c, autoHandoff: on }),
+      `Automatic handoff for non-vision models ${on ? "on" : "off"}.`,
+    );
+    return;
+  }
+
+  if (subcommand === "clear") {
+    updateConfig(
+      ctx,
+      (c) => ({ ...c, visionModel: null }),
+      "Vision model cleared — handoff inactive until you pick a model.",
+    );
+    return;
+  }
+
+  if (subcommand === "model") {
+    if (!rest) {
+      ctx.ui.notify("Usage: /vision-handoff model <provider/id>", "warning");
+      return;
+    }
+    const parsed = parseModelRef(rest);
+    if (!parsed) {
+      ctx.ui.notify(`Invalid model reference: "${rest}". Use "provider/id".`, "error");
+      return;
+    }
+    const model = ctx.modelRegistry.find(parsed.provider, parsed.id);
+    if (!model) {
+      ctx.ui.notify(`Model not found: ${rest}. Use /vision-handoff to pick from the list.`, "error");
+      return;
+    }
+    const ref = formatModelRef(parsed.provider, parsed.id);
+    updateConfig(ctx, (c) => ({ ...c, visionModel: ref }), `Vision model set to ${ref}.`);
+    if (!isVisionModel(model)) {
+      ctx.ui.notify(
+        `Note: ${ref} does not declare image input — it may not describe images well.`,
+        "warning",
+      );
+    }
+    return;
+  }
+
+  if (subcommand === "add") {
+    if (!rest) {
+      ctx.ui.notify("Usage: /vision-handoff add <provider/id>", "warning");
+      return;
+    }
+    const parsed = parseModelRef(rest);
+    if (!parsed) {
+      ctx.ui.notify(`Invalid model reference: "${rest}". Use "provider/id".`, "error");
+      return;
+    }
+    const ref = formatModelRef(parsed.provider, parsed.id);
+    updateConfig(
+      ctx,
+      (c) => ({ ...c, handoffModels: Array.from(new Set([...c.handoffModels, ref])) }),
+      `Added ${ref} to handoff targets.`,
+    );
+    return;
+  }
+
+  if (subcommand === "remove") {
+    if (!rest) {
+      ctx.ui.notify("Usage: /vision-handoff remove <provider/id>", "warning");
+      return;
+    }
+    const parsed = parseModelRef(rest);
+    if (!parsed) {
+      ctx.ui.notify(`Invalid model reference: "${rest}". Use "provider/id".`, "error");
+      return;
+    }
+    const ref = formatModelRef(parsed.provider, parsed.id);
+    const before = config.handoffModels.length;
+    updateConfig(
+      ctx,
+      (c) => ({ ...c, handoffModels: c.handoffModels.filter((m) => m !== ref) }),
+      `Removed ${ref} from handoff targets.`,
+    );
+    if (config.handoffModels.length === before) {
+      ctx.ui.notify(`Note: ${ref} was not in the handoff list.`, "info");
+    }
+    return;
+  }
+
+  ctx.ui.notify(`Unknown subcommand: "${subcommand}". Use /vision-handoff help for usage.`, "warning");
+}
+
+function updateConfig(
+  ctx: ExtensionCommandContext,
+  transform: (c: VisionHandoffConfig) => VisionHandoffConfig,
+  message: string,
+): void {
+  const next = transform(config);
+  const path = writeConfig(next);
+  config = next;
+  visionModelCache = null;
+  visionModelUnresolvedRef = null;
+  ctx.ui.notify(`${message} (config: ${path})`, "info");
+}
+
+async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("/vision-handoff requires interactive mode.", "error");
+    return;
+  }
+
+  const allModels = ctx.modelRegistry
+    .getAll()
+    .map((m) => ({ provider: m.provider, id: m.id, name: m.name, input: m.input }));
+
+  const result = await ctx.ui.custom<VisionModelSelectorResult>((tui, theme, _kb, done) => {
+    const selector = new VisionModelSelectorComponent(theme, allModels, config.visionModel, (r) => done(r));
+    return {
+      render(width: number) {
+        return selector.render(width);
+      },
+      invalidate() {
+        selector.invalidate();
+      },
+      handleInput(data: string) {
+        selector.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  if (!result || result.cancelled) {
+    ctx.ui.notify("Vision handoff picker cancelled.", "info");
+    return;
+  }
+
+  const ref = result.ref;
+  updateConfig(ctx, (c) => ({ ...c, visionModel: ref }), ref ? `Vision model set to ${ref}` : "Vision model cleared");
+  if (!ref) {
+    ctx.ui.notify("Handoff is inactive until you pick a vision model.", "warning");
+  }
+}
+
+function showStatus(ctx: ExtensionCommandContext): void {
+  const lines: string[] = [];
+  lines.push(`Vision handoff: ${config.enabled ? "enabled" : "disabled"}`);
+  lines.push(`Vision model: ${config.visionModel ?? "(none — pick one with /vision-handoff)"}`);
+  lines.push(`Auto handoff (non-vision models): ${config.autoHandoff ? "on" : "off"}`);
+  lines.push(`Handoff targets (explicit): ${config.handoffModels.length ? config.handoffModels.join(", ") : "(none)"}`);
+  lines.push(`maxTokens: ${config.maxTokens} · cacheMax: ${config.cacheMax}`);
+
+  const model = ctx.model;
+  let active = false;
+  if (isConfigured(config) && model) {
+    active = isHandoffTarget(model, config);
+  }
+  lines.push(
+    `Active for current model (${model ? formatModelRef(model.provider, model.id) : "none"}): ${active ? "yes" : "no"}`,
+  );
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["__tests__/**/*.test.ts"],
+    exclude: ["node_modules", "dist", ".idea", ".git", ".cache"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      exclude: ["node_modules/", "**/*.d.ts", "**/*.test.ts"],
+    },
+  },
+});