pi-multimodal-proxy 1.18.1 → 1.19.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.19.0] - 2026-10-01
+
+### Added
+
+- **Virtual model — `Multimodal Auto`** (`multimodal-proxy/auto`, Pi ≥ 0.99, feature-detected). The extension registers a virtual model via `pi.registerVirtualModel()`; selecting it in `/model` routes each request: turns whose pending user input carries image blocks go natively to the configured vision model (real pixels, no description fence), everything else goes to the base model — the pinned `virtual-base` model, else the physical model that answered last (`request.previous`), else the vision model. Sticky routing (`retry` → `failed`, `continuation`/`direct` → `previous`) keeps prompt caches and thinking signatures valid. `route()` resolves config per request (no registration churn on model changes) and throws an actionable error pointing at `/multimodal-proxy pick` when no vision model resolves. New commands `/multimodal-proxy virtual on|off` (default on; `unregisterVirtualModel` when off), `/multimodal-proxy virtual-base <provider/model-id>|off`, env overrides `PI_VISION_PROXY_VIRTUAL` / `PI_VISION_PROXY_VIRTUAL_BASE`, status-line `[+virtual]` marker, interactive-menu entry, and summary/help lines. With the virtual model selected, image stripping never applies (it advertises image input); video/audio detection, `analyze_image`, and consent gates are unchanged.
+- **`analyze_image` adopts the Pi 0.99 extension tool API** (older hosts ignore the new fields): results carry `isError: true` for failures instead of "Error: …" text masquerading as content (all ~18 failure paths now route through an `AnalyzeImageOutcome`), successful calls return an `outputSchema`-shaped `structuredContent` — analysis text, `cached`, fallback-aware `provider`/`model`, `latencyMs`, `groundingFormat`, and per-image `id`/`filename`/dimensions/absolute-pixel `crop` — so codemode scripts and other `ctx.executeTool()` callers receive machine-readable results, and MCP-style `annotations` (`readOnlyHint: true`, `openWorldHint: true`) plus a `multimodal-proxy` namespace group the tool in codemode listings.
+- **Model-aware upload downscale** (Pi ≥ 0.87). `modelImageResizeLimits()` reads the vision model catalog entry's `inputLimits.images.resize` (`maxWidth`/`maxHeight`/`maxBytes`/`jpegQuality`, all optional) and `downscaleForUpload()` tightens the user's `maxUploadDim`/`maxUploadBytes`/quality with it — the derived long-edge target is `min(maxWidth, maxHeight)`, the base64 `maxBytes` budget is converted to raw bytes (×0.75) before mixing with the user's raw budget, and a user-disabled downscale (`maxUploadDim: 0`) always wins. `downscaleImage` gained a `quality` parameter threaded through both the worker task and the in-thread path. All four upload paths (auto-proxy, `analyze_image`, joint descriptions, `/describe`) pass the resolved vision model's limits.
+- **Compaction-proof, cache-stable recall hint** (Pi ≥ 0.87). A `context_with_system` handler — probed on first invocation so the affordance never appears twice — takes over the `analyze_image` recall affordance once media has been described: a stable system-layer block replaces the per-user-message restatement. It survives compaction (which summarized the old hint away) and reaches vision-capable session models, where the strip path never fired. Older hosts keep the exact previous behavior.
+
+### Changed
+
+- `envFlags()` reports two new presence flags (`virtual`, `virtualBase`); the config summary, no-UI command list, and interactive menu show the virtual-model state (including a "(needs pi ≥ 0.99)" qualifier when registered on an older host).
+- Six new tests: env override + flag presence for the virtual vars, `modelImageResizeLimits` derivation (null cases, box target, quality default, raw-byte conversion), model-limits tightening vs. user-disabled downscale vs. in-budget images, and sanitize validation of the new fields (494 total, all green).
+
+### Fixed (PR #34 review)
+
+- **`modelImageResizeLimits` no longer drops maxBytes-only declarations** — a catalog entry with `inputLimits.images.resize.maxBytes` but no `maxWidth`/`maxHeight` is now honored: `targetDim` stays unset (the user's dim target applies) while the byte budget (converted to raw bytes, floored at 1) and JPEG quality still tighten the upload path. Quality-only declarations remain a no-op.
+- **Virtual-model routing filters for vision-capable entries** — `resolveVisionTarget` only accepts models whose `input` includes `image`, so a text-only pin (via `/multimodal-proxy model` or `PI_VISION_PROXY_MODEL`) can no longer route a media turn to a model that would receive image placeholders; `route()` throws the actionable `/multimodal-proxy pick` error instead.
+- **Cache-hit `structuredContent.text` now matches fresh calls** — the analyze_image tool cache stores `{ fence, raw }`, so cached requests return the raw analysis text in `structuredContent` (as `AnalyzeImageOutput` advertises) while the model still sees the identical fence.
+
 ## [1.18.1] - 2026-08-30
 
 ### Fixed (post-release review of 1.18.0)

package/README.md

@@ -8,6 +8,15 @@ When **video or audio files** are detected, they are routed to a **multimodal mo
 
 **YouTube links** are detected too: paste a URL (`youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, etc.) and the video is downloaded with [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) and analyzed exactly like a local file.
 
+## What's new in 1.19.0
+
+Deep integration with recent Pi releases (0.87 / 0.99):
+
+- **Virtual model — `Multimodal Auto`** (Pi ≥ 0.99, on by default): a new entry in `/model` that routes each request for you — turns whose pending input carries images go **natively** to your configured vision model (real pixels, no text fence), everything else stays on your base model (auto = whatever physical model handled the session before, or pin one with `/multimodal-proxy virtual-base`). Sticky routing keeps prompt caches valid within a turn; the footer shows the routed model and `/session` lists cost per physical model. Disable with `/multimodal-proxy virtual off`.
+- **`analyze_image` speaks the 0.99 tool API** — errors now surface as real tool errors (`isError`) instead of fake text, results carry a machine-readable `structuredContent` (analysis text, provider/model, latency, grounding format, per-image ids/dimensions/crop) so **codemode scripts** can consume them programmatically, and the tool is annotated (`readOnlyHint`) and namespaced (`multimodal-proxy`) for codemode listings.
+- **Model-aware upload downscale** (Pi ≥ 0.87) — when the configured vision model declares `inputLimits.images.resize` in its catalog entry, the proxy derives the downscale target, JPEG quality, and byte budget from it (tightening, never loosening, your `max-upload` settings). No more double-resizing against provider limits.
+- **Compaction-proof recall hint** (Pi ≥ 0.87) — the `analyze_image` recall affordance moves to a stable system-layer block via `context_with_system` once media has been described: it survives compaction (the old per-user-message hint was summarized away) and also reaches vision-capable session models, where the strip path never fired. Older hosts keep the previous behavior.
+
 ## What's new in 1.18.0
 
 - **Key-aware default model resolution** — the implicit vision default now lands on a model you can actually call. If the default (`zai/glm-5.3-flash`) has no API key in your setup, the proxy walks a preference-ordered candidate chain — `zai/glm-5.3-flash` → `deepseek/deepseek-v4-flash-vision-exp` (new in Pi 0.84.4, cheap, built-in provider) → `anthropic/claude-sonnet-5` — and picks the first candidate that is in the catalog **and keyed**. A keyed legacy default is never traded for an unkeyed model; explicit choices (`/multimodal-proxy model`, `pick`, `PI_VISION_PROXY_MODEL`) are still never rewritten; and when nothing is keyed you get the actionable `pi --login` hint as before. A substitution is announced once per session.
@@ -118,6 +127,24 @@ Both are persisted in `~/.pi/agent/multimodal-proxy.json` and can be set via env
 | **`always`** | Always uses the proxy, even if the active model supports images |
 | **`off`** | Disabled entirely |
 
+## Virtual model (Pi ≥ 0.99)
+
+`Multimodal Auto` (`multimodal-proxy/auto`) is a [virtual model](https://pi.dev/docs/latest/virtual-models) the extension registers on Pi 0.99+ (on by default; `/multimodal-proxy virtual off` removes it). Select it once in `/model` and every request is routed for you:
+
+| Turn | Routed to |
+|------|-----------|
+| Pending input carries an image attachment | Your configured **vision model** — natively, so the model sees the actual pixels |
+| Everything else | Your **base model**: the pinned `/multimodal-proxy virtual-base` model, else the physical model that handled the session before, else the vision model |
+
+Why you'd want it:
+
+- **One selection, automatic escalation** — keep a cheap/fast model for text turns and pay for the vision model only when media actually appears. No manual `/model` switching.
+- **Native vision instead of descriptions** — unlike proxy mode (which converts images to text fences for non-vision models), media turns get real pixel fidelity while `analyze_image` recall stays available for re-querying.
+- **Cost transparency for free** — the footer shows `Multimodal Auto → <routed model>`, and `/session` lists cost per physical model.
+- **Cache-safe** — continuations and retries stay on the model that handled the turn, so prompt caches and thinking signatures survive.
+
+Virtual-model routing is orthogonal to proxy mode: with `Multimodal Auto` selected, image stripping never applies (the virtual model advertises image input), while video/audio path detection, `analyze_image`, and consent gates keep working exactly as before.
+
 ## Configuration
 
 Settings persist across sessions in `~/.pi/agent/multimodal-proxy.json`. Environment variables override file settings; in-session commands override both.
@@ -147,6 +174,8 @@ Settings persist across sessions in `~/.pi/agent/multimodal-proxy.json`. Environ
                                                          (clear with: /multimodal-proxy fallback-model clear)
 /multimodal-proxy retry <0-5>                          → retries on transient errors (429/5xx/network), default 2
 /multimodal-proxy max-upload <dim | n mb | off>        → downscale uploads larger than this (default 2048 px / 5 MB; off = 8192 px / 20 MB)
+/multimodal-proxy virtual on | off                     → register/remove the 'Multimodal Auto' virtual model (Pi ≥ 0.99, default on)
+/multimodal-proxy virtual-base <provider/model-id>     → pin the text-turn model for the virtual model ('off' clears → auto)
 /multimodal-proxy status on | off                      → show/hide the steady status line
 /multimodal-proxy grounding-models list                → show grounding-capable models
 /multimodal-proxy grounding-models add <provider/id> [--format <fmt>]
@@ -188,6 +217,8 @@ Legacy alias: /vision-proxy <args> works identically.
 | `PI_VISION_PROXY_MAX_UPLOAD_DIM` | `0` (disable downscaling entirely), or 512–8192 px long-edge threshold | `2048` |
 | `PI_VISION_PROXY_MAX_UPLOAD_MB` | 0.5–20 upload byte budget before downscale | `5` |
 | `PI_VISION_PROXY_FALLBACK_MODEL` | `provider/model-id`, or `none`/`off` to clear | not set |
+| `PI_VISION_PROXY_VIRTUAL` | `on`, `off` — register the `Multimodal Auto` virtual model (Pi ≥ 0.99) | `on` |
+| `PI_VISION_PROXY_VIRTUAL_BASE` | `provider/model-id` pinning the virtual model's text-turn model, or `none` to clear | not set |
 | `PI_VISION_PROXY_STATUS_LINE` | `on`, `off` | `on` |
 | `PI_VISION_PROXY_PATH_DETECTION` | `on`, `off` — `off` disables scanning prompt text for media file paths; structured attachments are always processed | `on` |
 

package/extensions/__tests__/internal.test.ts

@@ -98,6 +98,7 @@ import {
 	RECALL_HINT,
 	createAbortError,
 	downscaleForUpload,
+	modelImageResizeLimits,
 	overUploadDim,
 	downscaleTargetDim,
 	isAbortError,
@@ -278,18 +279,18 @@ describe("readEnvOverrides", () => {
 
 describe("envFlags", () => {
 	it("reports presence per variable", () => {
-		assert.deepEqual(envFlags({}), { mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false });
+		assert.deepEqual(envFlags({}), { mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false, virtual: false, virtualBase: false });
 		assert.deepEqual(
 			envFlags({
 				PI_VISION_PROXY_MODE: "x",
 				PI_VISION_PROXY_MODEL: "y",
 				PI_VISION_PROXY_INCLUDE_CONTEXT: "",
 			}),
-			{ mode: true, model: true, context: true, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false },
+			{ mode: true, model: true, context: true, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false, virtual: false, virtualBase: false },
 		);
 		assert.deepEqual(
 			envFlags({ PI_VISION_PROXY_ALLOW_HOME: "1", PI_VISION_PROXY_ALLOWED_FOLDERS: "/a" }),
-			{ mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: true, allowedFolders: true, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false },
+			{ mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: true, allowedFolders: true, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false, retryMax: false, maxUpload: false, fallbackModel: false, virtual: false, virtualBase: false },
 		);
 		assert.equal(envFlags({ PI_VISION_PROXY_ALLOWED_PROVIDERS: "" }).allowedProviders, true);
 		// An unrecognized ALLOW_HOME value is not an override and must not lock the command
@@ -302,6 +303,21 @@ describe("envFlags", () => {
 		assert.equal(envFlags({ PI_VISION_PROXY_STATUS_LINE: "bogus" }).statusLine, false);
 		assert.equal(envFlags({ PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER: "chrome" }).ytdlpCookies, true);
 		assert.equal(envFlags({ PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS: "youtube:player_client=web" }).ytdlpExtractorArgs, true);
+		// 1.19.0 virtual-model overrides
+		assert.equal(envFlags({ PI_VISION_PROXY_VIRTUAL: "on" }).virtual, true);
+		assert.equal(envFlags({ PI_VISION_PROXY_VIRTUAL: "bogus" }).virtual, false);
+		assert.equal(envFlags({ PI_VISION_PROXY_VIRTUAL_BASE: "zai/glm-5.3-flash" }).virtualBase, true);
+		assert.equal(envFlags({ PI_VISION_PROXY_VIRTUAL_BASE: "none" }).virtualBase, true);
+		assert.deepEqual(readEnvOverrides({ PI_VISION_PROXY_VIRTUAL: "off" }).virtualModel, "off");
+		assert.deepEqual(readEnvOverrides({ PI_VISION_PROXY_VIRTUAL: "bogus" }).virtualModel, undefined);
+		assert.deepEqual(readEnvOverrides({ PI_VISION_PROXY_VIRTUAL_BASE: "zai/glm-5.3-flash" }), {
+			virtualBaseProvider: "zai",
+			virtualBaseModelId: "glm-5.3-flash",
+		});
+		assert.deepEqual(readEnvOverrides({ PI_VISION_PROXY_VIRTUAL_BASE: "none" }), {
+			virtualBaseProvider: undefined,
+			virtualBaseModelId: undefined,
+		});
 	});
 });
 
@@ -3480,6 +3496,109 @@ describe("1.16.0 downscaleForUpload (integration)", () => {
 	});
 });
 
+describe("1.19.0 model image limits (pi ≥ 0.87 inputLimits.images.resize)", () => {
+	it("modelImageResizeLimits returns null without a declaration", () => {
+		assert.equal(modelImageResizeLimits(undefined), null);
+		assert.equal(modelImageResizeLimits({}), null);
+		assert.equal(modelImageResizeLimits({ inputLimits: {} }), null);
+		assert.equal(modelImageResizeLimits({ inputLimits: { images: {} } }), null);
+		// No numeric dimension → no usable target
+		assert.equal(modelImageResizeLimits({ inputLimits: { images: { resize: { jpegQuality: 75 } } } }), null);
+	});
+
+	it("modelImageResizeLimits derives a long-edge target, quality, and raw-byte budget", () => {
+		const limits = modelImageResizeLimits({
+			inputLimits: { images: { resize: { maxWidth: 1568, maxHeight: 1040, jpegQuality: 75, maxBytes: 524288 } } },
+		});
+		assert.equal(limits?.targetDim, 1040);
+		assert.equal(limits?.quality, 75);
+		assert.equal(limits?.maxBytes, 393216); // 524288 × 0.75
+		const partial = modelImageResizeLimits({ inputLimits: { images: { resize: { maxWidth: 1568 } } } });
+		assert.equal(partial?.targetDim, 1568);
+		assert.equal(partial?.quality, 88);
+		assert.equal(partial?.maxBytes, undefined);
+	});
+
+	it("maxBytes-only declarations are honored — targetDim stays unset, budget and quality tighten (PR #34 review)", () => {
+		const limits = modelImageResizeLimits({
+			inputLimits: { images: { resize: { maxBytes: 524288, jpegQuality: 70 } } },
+		});
+		assert.notEqual(limits, null);
+		assert.equal(limits?.targetDim, undefined);
+		assert.equal(limits?.quality, 70);
+		assert.equal(limits?.maxBytes, 393216);
+		// A tiny maxBytes never collapses to a zero budget
+		assert.equal(modelImageResizeLimits({ inputLimits: { images: { resize: { maxBytes: 1 } } } })?.maxBytes, 1);
+	});
+
+	it("maxBytes-only limits trigger the byte budget on downscaleForUpload (PR #34 review)", async () => {
+		const { Image } = await import("imagescript");
+		const noise = new Image(200, 150);
+		for (let x = 1; x <= 200; x++) {
+			for (let y = 1; y <= 150; y++) {
+				noise.setPixelAt(x, y, (Math.random() * 0xffffffff) >>> 0);
+			}
+		}
+		const img = bufferToPiAiImage(Buffer.from(await noise.encode(1)), "image/png");
+		// Dims are inside every dim threshold; only the model's byte budget
+		// (2048 raw) is exceeded by the ~100 KB noise PNG → must re-encode.
+		const out = await downscaleForUpload(
+			img,
+			{ maxUploadDim: 2048, maxUploadBytes: 5 * 1024 * 1024 },
+			{ quality: 75, maxBytes: 2048 },
+		);
+		assert.equal(out.mimeType, "image/jpeg");
+	});
+
+	it("model limits tighten downscaleForUpload below the user config", async () => {
+		const { Image } = await import("imagescript");
+		const big = bufferToPiAiImage(Buffer.from(await new Image(3000, 200).encode(1)), "image/png");
+		const out = await downscaleForUpload(
+			big,
+			{ maxUploadDim: 2048, maxUploadBytes: 5 * 1024 * 1024 },
+			{ targetDim: 1024, quality: 75 },
+		);
+		assert.equal(out.mimeType, "image/jpeg");
+		const dims = extractDimensions(piAiImageToBuffer(out));
+		assert.equal(dims?.width, 1024);
+	});
+
+	it("model limits never re-enable a user-disabled downscale", async () => {
+		const { Image } = await import("imagescript");
+		const big = bufferToPiAiImage(Buffer.from(await new Image(3000, 200).encode(1)), "image/png");
+		const out = await downscaleForUpload(
+			big,
+			{ maxUploadDim: 0, maxUploadBytes: 5 * 1024 * 1024 },
+			{ targetDim: 1024, quality: 75 },
+		);
+		assert.equal(out, big);
+	});
+
+	it("model limits under the user config do not shrink an in-budget image", async () => {
+		const { Image } = await import("imagescript");
+		const small = bufferToPiAiImage(Buffer.from(await new Image(800, 600).encode(1)), "image/png");
+		const out = await downscaleForUpload(
+			small,
+			{ maxUploadDim: 2048, maxUploadBytes: 5 * 1024 * 1024 },
+			{ targetDim: 1024, quality: 75 },
+		);
+		assert.equal(out, small);
+	});
+
+	it("sanitize validates the 1.19.0 virtual-model fields", () => {
+		assert.equal(sanitize({ ...DEFAULT_CONFIG }).virtualModel, "on");
+		assert.equal(sanitize({ ...DEFAULT_CONFIG, virtualModel: "off" }).virtualModel, "off");
+		assert.equal(sanitize({ ...DEFAULT_CONFIG, virtualModel: "bogus" as any }).virtualModel, "on");
+		const pinned = sanitize({ ...DEFAULT_CONFIG, virtualBaseProvider: "x-ai", virtualBaseModelId: "some-model" });
+		assert.equal(pinned.virtualBaseProvider, "xai");
+		assert.equal(pinned.virtualBaseModelId, "some-model");
+		// Both halves required — a lone provider is dropped
+		const lone = sanitize({ ...DEFAULT_CONFIG, virtualBaseProvider: "zai" });
+		assert.equal("virtualBaseProvider" in lone, false);
+		assert.equal("virtualBaseModelId" in lone, false);
+	});
+});
+
 describe("1.16.0 review fixes (PR #27)", () => {
 	it("createAbortError is abort-shaped with the exact 'aborted' message", () => {
 		const err = createAbortError();

package/extensions/internal.ts

@@ -94,6 +94,15 @@ export interface VisionConfig {
 	maxUploadBytes: number;
 	fallbackProvider?: string;
 	fallbackModelId?: string;
+	// 1.19.0 — virtual model (pi ≥ 0.99): registers `multimodal-proxy/auto`, a
+	// selectable model that routes media-bearing turns to the configured vision
+	// model and text turns to a base model. "on" registers it, "off" never
+	// does. The optional base pin names the physical text model; unset = stay on
+	// whatever physical model handled the session before, falling back to the
+	// vision model for the first turn.
+	virtualModel: ToolSetting;
+	virtualBaseProvider?: string;
+	virtualBaseModelId?: string;
 }
 
 export interface ImageMeta {
@@ -727,6 +736,9 @@ export const DEFAULT_CONFIG: VisionConfig = {
 	retryMax: 2,
 	maxUploadDim: 2048,
 	maxUploadBytes: 5 * 1024 * 1024,
+	// 1.19.0 — virtual model registered on hosts with pi.registerVirtualModel()
+	// (pi ≥ 0.99); feature-detected and skipped on older hosts.
+	virtualModel: "on",
 };
 
 // ── Persistent file storage ────────────────────────────────────────────────
@@ -759,6 +771,9 @@ const PERSISTED_CONFIG_KEYS = new Set([
 	"maxUploadBytes",
 	"fallbackProvider",
 	"fallbackModelId",
+	"virtualModel",
+	"virtualBaseProvider",
+	"virtualBaseModelId",
 ]);
 
 /** Read config from the persistent file. Returns empty object on any failure. */
@@ -871,6 +886,7 @@ export function parseFallbackModelEnv(
 	return parsed ? { provider: parsed.provider, modelId: parsed.modelId } : undefined;
 }
 
+/** Environment overrides (PI_VISION_PROXY_*) applied last; only recognized values land. */
 export function readEnvOverrides(env: NodeJS.ProcessEnv = process.env): Partial<VisionConfig> {
 	const overrides: Partial<VisionConfig> = {};
 	const modeEnv = env.PI_VISION_PROXY_MODE;
@@ -966,10 +982,24 @@ export function readEnvOverrides(env: NodeJS.ProcessEnv = process.env): Partial<
 			overrides.fallbackModelId = fallbackModelEnv.modelId;
 		}
 	}
+	// 1.19.0 virtual-model overrides
+	const virtualEnv = env.PI_VISION_PROXY_VIRTUAL;
+	if (virtualEnv === "on" || virtualEnv === "off") overrides.virtualModel = virtualEnv;
+	const virtualBaseEnv = parseFallbackModelEnv(env.PI_VISION_PROXY_VIRTUAL_BASE);
+	if (virtualBaseEnv) {
+		if (virtualBaseEnv.clear) {
+			overrides.virtualBaseProvider = undefined;
+			overrides.virtualBaseModelId = undefined;
+		} else {
+			overrides.virtualBaseProvider = virtualBaseEnv.provider;
+			overrides.virtualBaseModelId = virtualBaseEnv.modelId;
+		}
+	}
 	return overrides;
 }
 
-export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean; model: boolean; context: boolean; tool: boolean; maxImagesPerCall: boolean; maxBatch: boolean; cacheSize: boolean; videoModel: boolean; allowedProviders: boolean; allowHome: boolean; allowedFolders: boolean; statusLine: boolean; pathDetection: boolean; ytdlpCookies: boolean; ytdlpExtractorArgs: boolean; retryMax: boolean; maxUpload: boolean; fallbackModel: boolean } {
+/** Which env vars actually override a setting — used to lock the matching commands. */
+export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean; model: boolean; context: boolean; tool: boolean; maxImagesPerCall: boolean; maxBatch: boolean; cacheSize: boolean; videoModel: boolean; allowedProviders: boolean; allowHome: boolean; allowedFolders: boolean; statusLine: boolean; pathDetection: boolean; ytdlpCookies: boolean; ytdlpExtractorArgs: boolean; retryMax: boolean; maxUpload: boolean; fallbackModel: boolean; virtual: boolean; virtualBase: boolean } {
 	return {
 		mode: Boolean(env.PI_VISION_PROXY_MODE),
 		model: Boolean(env.PI_VISION_PROXY_MODEL),
@@ -998,6 +1028,9 @@ export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean;
 			parseUploadDimEnv(env.PI_VISION_PROXY_MAX_UPLOAD_DIM) !== undefined ||
 			parseUploadMbEnv(env.PI_VISION_PROXY_MAX_UPLOAD_MB) !== undefined,
 		fallbackModel: parseFallbackModelEnv(env.PI_VISION_PROXY_FALLBACK_MODEL) !== undefined,
+		// 1.19.0 — only recognized values count as overrides.
+		virtual: env.PI_VISION_PROXY_VIRTUAL === "on" || env.PI_VISION_PROXY_VIRTUAL === "off",
+		virtualBase: parseFallbackModelEnv(env.PI_VISION_PROXY_VIRTUAL_BASE) !== undefined,
 	};
 }
 
@@ -1139,6 +1172,7 @@ export function sanitizeProviderHeaders(
 	return out;
 }
 
+/** Validate and normalize a merged config: canonicalize providers, clamp numbers, drop malformed pairs. */
 export function sanitize(config: VisionConfig): VisionConfig {
 	const safe: VisionConfig = { ...config };
 	if (typeof safe.provider === "string") safe.provider = canonicalProvider(safe.provider);
@@ -1244,6 +1278,17 @@ export function sanitize(config: VisionConfig): VisionConfig {
 		delete safe.fallbackProvider;
 		delete safe.fallbackModelId;
 	}
+	// 1.19.0 virtual-model fields
+	if (safe.virtualModel !== "on" && safe.virtualModel !== "off") safe.virtualModel = DEFAULT_CONFIG.virtualModel;
+	if (typeof safe.virtualBaseProvider !== "string") delete safe.virtualBaseProvider;
+	else safe.virtualBaseProvider = canonicalProvider(safe.virtualBaseProvider);
+	if (typeof safe.virtualBaseModelId !== "string") delete safe.virtualBaseModelId;
+	if (safe.virtualBaseProvider !== undefined && !PROVIDER_PATTERN.test(safe.virtualBaseProvider)) delete safe.virtualBaseProvider;
+	if (safe.virtualBaseModelId !== undefined && !MODEL_ID_PATTERN.test(safe.virtualBaseModelId)) delete safe.virtualBaseModelId;
+	if (!safe.virtualBaseProvider || !safe.virtualBaseModelId) {
+		delete safe.virtualBaseProvider;
+		delete safe.virtualBaseModelId;
+	}
 	return safe;
 }
 
@@ -1251,6 +1296,11 @@ export function persistedBase(entries: readonly SessionEntry[]): VisionConfig {
 	return sanitize({ ...DEFAULT_CONFIG, ...readPersistedConfig(entries) });
 }
 
+/**
+ * Resolve the effective config: defaults ← persisted file ← session-entry
+ * config ← environment overrides, then sanitize (invalid values fall back to
+ * defaults; half-set model pairs are dropped).
+ */
 export function resolveConfig(
 	entries: readonly SessionEntry[],
 	env: NodeJS.ProcessEnv = process.env,
@@ -2606,7 +2656,7 @@ parentPort.on("message", async (task) => {
 			const w = Math.max(1, Math.round(img.width * scale));
 			const h = Math.max(1, Math.round(img.height * scale));
 			// Downscaled uploads are re-encoded as JPEG — the size reduction is the point.
-			encoded = await (scale >= 1 ? img : img.resize(w, h)).encodeJPEG(88);
+			encoded = await (scale >= 1 ? img : img.resize(w, h)).encodeJPEG(task.quality ?? 88);
 		} else {
 			const cropped = img.crop(task.crop.x, task.crop.y, task.crop.width, task.crop.height);
 			encoded = mimeType === "image/png" ? await cropped.encode(1) : await cropped.encodeJPEG(90);
@@ -2873,7 +2923,7 @@ export function overUploadDim(
 }
 
 /** In-thread decode → resize → JPEG encode, mirroring cropInThread. */
-async function resizeInThread(imageBytes: Buffer, targetDim: number): Promise<Buffer | null> {
+async function resizeInThread(imageBytes: Buffer, targetDim: number, quality = 88): Promise<Buffer | null> {
 	const img = await decodeWithTimeout(imageBytes);
 	if (img.width > MAX_IMAGE_DIMENSION || img.height > MAX_IMAGE_DIMENSION) {
 		return null;
@@ -2881,7 +2931,7 @@ async function resizeInThread(imageBytes: Buffer, targetDim: number): Promise<Bu
 	const scale = Math.min(targetDim / img.width, targetDim / img.height, 1);
 	const w = Math.max(1, Math.round(img.width * scale));
 	const h = Math.max(1, Math.round(img.height * scale));
-	const encoded = await (scale >= 1 ? img : img.resize(w, h)).encodeJPEG(88);
+	const encoded = await (scale >= 1 ? img : img.resize(w, h)).encodeJPEG(quality);
 	return Buffer.from(encoded);
 }
 
@@ -2890,6 +2940,7 @@ async function resizeInWorker(
 	imageBytes: Buffer,
 	targetDim: number,
 	timeoutMs: number,
+	quality?: number,
 ): Promise<Buffer | null | typeof WORKER_UNAVAILABLE> {
 	if (!(await ensureWorkerInfra())) return WORKER_UNAVAILABLE;
 
@@ -2904,7 +2955,7 @@ async function resizeInWorker(
 
 	const { result, reusable } = await runCropTask(
 		worker,
-		{ op: "resize", bytes: ab, targetDim, mimeType: "image/jpeg", maxDim: MAX_IMAGE_DIMENSION },
+		{ op: "resize", bytes: ab, targetDim, quality, mimeType: "image/jpeg", maxDim: MAX_IMAGE_DIMENSION },
 		timeoutMs,
 	);
 	if (reusable) releaseWorker(worker);
@@ -2913,32 +2964,97 @@ async function resizeInWorker(
 }
 
 /**
- * Downscale image bytes so the long edge fits targetDim, re-encoding as
- * JPEG q88. Returns null on decode/encode failure — callers then send the
- * original bytes rather than failing the whole analysis.
+ * Downscale image bytes so the long edge fits targetDim, re-encoding as JPEG
+ * (quality 88 unless overridden). Returns null on decode/encode failure —
+ * callers then send the original bytes rather than failing the whole analysis.
  */
-export async function downscaleImage(imageBytes: Buffer, targetDim: number): Promise<Buffer | null> {
+export async function downscaleImage(
+	imageBytes: Buffer,
+	targetDim: number,
+	quality = 88,
+): Promise<Buffer | null> {
 	try {
 		const dims = extractDimensions(imageBytes);
 		if (dims && (dims.width > MAX_IMAGE_DIMENSION || dims.height > MAX_IMAGE_DIMENSION)) {
 			return null;
 		}
 		if (decodeWorkerEnabled()) {
-			const viaWorker = await resizeInWorker(imageBytes, targetDim, decodeTimeoutMs());
+			const viaWorker = await resizeInWorker(imageBytes, targetDim, decodeTimeoutMs(), quality);
 			if (viaWorker !== WORKER_UNAVAILABLE) return viaWorker;
 			// else: worker infra unavailable — fall through to the in-thread path
 		}
-		return await resizeInThread(imageBytes, targetDim);
+		return await resizeInThread(imageBytes, targetDim, quality);
 	} catch {
 		return null;
 	}
 }
 
+/**
+ * Per-model image upload limits declared on a catalog entry (pi ≥ 0.87):
+ * `inputLimits.images.resize` = { maxWidth, maxHeight, maxBytes, jpegQuality }.
+ * `maxBytes` limits the base64 payload; here it is converted to a raw-byte
+ * budget (~3/4) so it can share the raw-byte comparison of the user config.
+ * Returns null when the model declares nothing (or an older pi host).
+ */
+export interface ModelImageResizeLimits {
+	/** Long-edge target that satisfies the model's max-width/max-height box. Absent when the model declares no dimension limits (byte-budget-only declarations keep the user's dim target). */
+	targetDim?: number;
+	/** JPEG re-encode quality (default 88). */
+	quality: number;
+	/** Raw-byte budget derived from the base64 maxBytes, when declared. */
+	maxBytes?: number;
+}
+
+export function modelImageResizeLimits(model: unknown): ModelImageResizeLimits | null {
+	const resize = (
+		model as
+			| {
+					inputLimits?: {
+						images?: {
+							resize?: {
+								maxWidth?: unknown;
+								maxHeight?: unknown;
+								maxBytes?: unknown;
+								jpegQuality?: unknown;
+							};
+						};
+				};
+			  }
+			| null
+			| undefined
+	)?.inputLimits?.images?.resize;
+	if (!resize) return null;
+	const maxW = typeof resize.maxWidth === "number" && resize.maxWidth > 0 ? resize.maxWidth : undefined;
+	const maxH = typeof resize.maxHeight === "number" && resize.maxHeight > 0 ? resize.maxHeight : undefined;
+	const dims = [maxW, maxH].filter((d): d is number => d !== undefined);
+	const quality =
+		typeof resize.jpegQuality === "number" && resize.jpegQuality >= 1 && resize.jpegQuality <= 100
+			? Math.round(resize.jpegQuality)
+			: 88;
+	const maxBytes =
+		typeof resize.maxBytes === "number" && resize.maxBytes > 0
+			? Math.max(1, Math.floor(resize.maxBytes * 0.75))
+			: undefined;
+	// A declaration must carry at least one meaningful limit — dimensions or a
+	// byte budget. Quality alone changes nothing until a resize triggers, so a
+	// quality-only declaration is treated as absent. A maxBytes-only
+	// declaration is honored (PR #34 review): targetDim stays unset and only
+	// the byte budget and quality tighten the user's thresholds.
+	if (dims.length === 0 && maxBytes === undefined) return null;
+	return {
+		targetDim: dims.length > 0 ? Math.min(...dims) : undefined,
+		quality,
+		maxBytes,
+	};
+}
+
 /**
  * Downscale an image for upload when it exceeds the configured thresholds
- * (1.16.0). Returns the original image untouched when it is small enough or
- * when downscaling fails for any reason — upload downscale is best-effort
- * cost/limit protection, never a hard failure.
+ * (1.16.0). Model-declared limits (pi ≥ 0.87 `inputLimits.images.resize`,
+ * 1.19.0) tighten the user's thresholds; they never re-enable a downscale the
+ * user disabled with `maxUploadDim: 0`. Returns the original image untouched
+ * when it is small enough or when downscaling fails for any reason — upload
+ * downscale is best-effort cost/limit protection, never a hard failure.
  *
  * Dimension-triggered resizes are accepted even when the JPEG re-encode grows
  * the payload slightly (flat-color PNGs compress better than JPEG) — the pixel
@@ -2948,13 +3064,23 @@ export async function downscaleImage(imageBytes: Buffer, targetDim: number): Pro
 export async function downscaleForUpload(
 	img: PiAiImage,
 	config: Pick<VisionConfig, "maxUploadDim" | "maxUploadBytes">,
+	modelLimits?: ModelImageResizeLimits | null,
 ): Promise<PiAiImage> {
 	if (config.maxUploadDim === 0) return img; // downscaling disabled
+	const targetDim = modelLimits?.targetDim
+		? Math.min(config.maxUploadDim, modelLimits.targetDim)
+		: config.maxUploadDim;
+	const maxUploadBytes =
+		modelLimits?.maxBytes !== undefined
+			? Math.min(config.maxUploadBytes, modelLimits.maxBytes)
+			: config.maxUploadBytes;
+	const quality = modelLimits?.quality ?? 88;
+	const effective = { maxUploadDim: targetDim, maxUploadBytes };
 	const buf = piAiImageToBuffer(img);
 	const dims = extractDimensions(buf);
-	const overDim = overUploadDim(dims, config);
-	if (downscaleTargetDim(dims, buf.byteLength, config) === null) return img;
-	const resized = await downscaleImage(buf, config.maxUploadDim);
+	const overDim = overUploadDim(dims, effective);
+	if (downscaleTargetDim(dims, buf.byteLength, effective) === null) return img;
+	const resized = await downscaleImage(buf, targetDim, quality);
 	if (!resized) return img;
 	if (!overDim && resized.byteLength >= buf.byteLength) return img;
 	return bufferToPiAiImage(resized, "image/jpeg");