# Changelog

All notable changes to `@xinizai/pi-vision-tool` are documented here.

## 0.6.0 - 2026-02-18

### Added

- **Auto-resize oversized images**: when a local image's width or height exceeds `maxImageSize` (default 2048, the de-facto limit of most OpenAI-compatible vision models), it is automatically resized to fit before upload, using pi's bundled Photon WASM resizer. No more `HTTP 400 input size exceed limit` on large screenshots and diagrams.
- Configurable per-Provider `maxImageSize` (range 256–8192). Omit to use the default 2048; set 0 to disable auto-resize.

### Changed

- **Fallback on size rejection (Plan B)**: if a request is rejected with `HTTP 400` and the error message carries an image size limit (e.g. `exceed limit 2048x2048`, `max 1024`), vision parses the limit, resizes every image to fit it, and retries exactly once. This covers providers whose limit differs from your configured default without any manual tuning.
- `VisionProviderConfig` gains an optional `maxImageSize` field; `validateProvider` enforces 256–8192.

## 0.5.0 - 2026-02-18

### Added

- Streaming analysis via SSE: requests now send `stream: true` and read `text/event-stream` responses incrementally. A `: PING` keep-alive line or any chunk counts as progress and resets the idle watchdog, so a slow but steadily streaming response never aborts. Providers that ignore `stream: true` or return non-SSE bodies fall back to the buffered path automatically.
- Idle-timeout semantics replace the old fixed total-timeout: the request aborts only when no data is received within `timeoutSeconds`. A response that streams for minutes still succeeds.
- Structured multi-image prompt: with 2 images the vision model is asked to describe each then compare; with 3+ it describes each in order and refers to them by ordinal.

### Changed

- `timeoutSeconds` upper bound raised from 600 to 1800, since idle-timeout makes longer ceilings safe.
- Retry on transient HTTP statuses (429/5xx) now only retries once and only when the request payload is small (<256 KB). Large image-bearing requests no longer re-hammer a rate limiter. Server `Retry-After` is honored, capped at 10 s.

### Fixed

- Remove unused `win32`/`posix` imports in `images.ts`.
- Config parsing now guards on schema `version`; unknown versions route through a migration stub so future schema changes do not silently drop providers.

## 0.4.0 - 2026-02-18

### Added

- `vision` tool accepts an optional `image_path` parameter. When the user message references a local image file but there is no current-turn attachment (e.g. `read` returned an image the model cannot see, or `image_generate`/`image_edit`/`image_variation` saved a file), the agent can pass the local path and vision reads, validates, and uploads the file for it. PNG, JPEG, WebP, GIF are supported; `~` is expanded.
- Auto-off when the active model already accepts image input: if `ctx.model.input` includes `"image"` and no `image_path` was passed, vision returns a hint instead of making a redundant proxy call. Lets the model use native image input.
- Tool description and prompt guidelines now explicitly tell the model to use `vision({ image_path })` as the fallback whenever it cannot see an image, instead of trying `read`/OCR/pixel inspection.

### Changed

- `resolveCurrentImages` keeps per-candidate error handling (no longer aborts the whole batch on one bad clipboard file); local-path resolution is gated behind an explicit `allowLocalPaths` option.

### Fixed

- Declare `engines.node >= 20.3` so the `AbortSignal.timeout()` / `AbortSignal.any()` usage in `provider.ts` does not crash on older Node versions.

## 0.3.3 - 2026-02-18

### Fixed

- Replace the npm-incompatible relative README link with a working UNPKG changelog link.
- Show the latest release summary directly in the npm README.

## 0.3.2 - 2026-02-18

### Changed

- Store Vision Provider configuration in the Pi user directory so Providers are shared across projects.
- Migrate an existing project-level `.pi/vision.json` to the global configuration on first access.
- Recalculate native attachment sizes from Base64 content before enforcing image limits.
- Redact custom request Header values from Provider error messages.
- Document the global configuration path and migration behavior.

## 0.3.1 - 2026-02-18

### Added

- Paginated model selection with 24 models per page.
- Model search, manual model entry, refresh, and current-model retention.
- Quick Provider setup for common OpenAI-compatible services.
- Credential status in the Provider list.
- Staged connection-test notifications with elapsed time and failure details.
- Per-header add, edit, and clear controls for custom request headers.

## 0.3.0 - 2026-02-18

### Added

- Multi-image Vision requests with ordering, deduplication, and image limits.
- Clipboard image validation for temporary paths, file signatures, size, and supported MIME types.
- Bearer, API-key header, and no-auth modes.
- Environment-variable API key references.
- Custom chat/models paths and request headers.
- Redacted errors and limited retries for transient HTTP failures.
- MIT license and Pi peer dependency compatibility with Pi 0.84.2 or newer.

## 0.2.2

### Fixed

- Sent all attached images in input order for OpenAI-compatible requests.
- Resolved multiple Pi clipboard image paths.