pi-multimodal-proxy 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.20.0] - 2026-10-02
+
+### Added
+
+- **`generate_image` tool (Pi ≥ 1.0, feature-detected)** — agent-facing image creation through `ModelRegistry.generateImages()` with the session's credentials and request-time auth; usage counts toward session cost. Parameters: `prompt` (1..4000 chars), optional `model` (`provider/model-id` of an image-generation model). Model resolution walks `getAvailableOfType("image")` (cached per session): without an override the first keyed image model wins; a mistyped override errors with recovery-style close matches and a malformed one gets the expected format (Pi 1.0 codemode-error philosophy). The prompt leaves only after the data-egress consent gate (`/multimodal-proxy consent yes` / `allowed-providers`). Results carry the generated image blocks (vision-capable base models see the pixels directly) plus a summary text naming each `image="<id>"` id, and an `outputSchema`-shaped `structuredContent` (provider, model, per-image id/mimeType/dimensions, `costUSD` when the provider reported usage; `usage` passed through on the tool result). Generated images are persisted in the per-session recall stores (`imageData`/`imageMeta`) with `generated-<hash8>.<ext>` filename hints, so the existing pipeline takes over: for text-only base models the `tool_result` hook auto-describes them via the vision model and appends `DescriptionEntry`s (making `#` recall work), and `analyze_image` can re-query or crop them by id regardless of base-model modality. Shares the per-turn tool-call budget with `analyze_image` (10/turn); annotated `readOnlyHint: false` (cost-incurring content creation) and namespaced `multimodal-proxy`. Registered only when the runtime exposes `generateImages` — pi < 1.0 never sees the tool.
+- Five new tests for `resolveImageGenModelChoice` (default-first, exact override, close-match suggestions on typos, expected-format error, actionable hint when nothing is keyed) — 512 total, all green.
+
+## [1.19.1] - 2026-10-02
+
+### Changed
+
+- **Leaner `analyze_image` description** — the tool description shrinks ~40% (1.7 KB → ~1.0 KB) while keeping every actionable detail (when to use, the three crop forms with shapes, recall ids, fence attributes, `crop_origin` math). Pi 1.0's codemode lists tool declarations under a 3000-token inline budget and drops what doesn't fit, so a long description both costs tokens on every request and risks pushing other tools out of the listing.
+- **Recovery-style errors (Pi 1.0 codemode philosophy: errors say how to recover)** — `analyze_image`'s model-not-found error now names close registry matches (`anthropic/claude-sont-5` → suggests `anthropic/claude-sonnet-5`, `…-sonnet-4-5`), the recall-id-not-found error lists close ids still retained in the session cache, and zero-area crop errors explain the expected shape (fraction/absolute bounds) instead of just "zero area".
+- **Dynamic implicit-vision-model fallback (Pi ≥ 1.0, feature-detected)** — when the curated fallback chain (`zai/glm-5.3-flash` → `deepseek/…-flash-vision-exp` → `anthropic/claude-sonnet-5/4-5`) is entirely unkeyed but another keyed vision-capable chat model exists (openrouter, google, …), `ModelRegistry.getAvailableOfType("chat")` resolves the implicit default to the first one (cheap-tier ids — flash/mini/fast/haiku/express/lite — preferred so an implicit default never lands on a frontier-priced model). Probe cached per session; older runtimes and the "nothing keyed anywhere" notice path are unchanged.
+- **`#` recall autocomplete regression tests** mirroring pi #10218 (autocomplete must trigger when input starts with whitespace) — the `(?:^|\s)#` token regex already handled it; the tests pin it.
+- Six new tests: `closeMatches` (near-typo ranking, substring bonus, relevance floor, deterministic ties), `pickDynamicVisionCandidate` (cheap-tier preference, first-capable fallback, input filtering), zero-area crop recovery hints (507 total, all green).
+
 ## [1.19.0] - 2026-10-01
 
 ### Added

package/README.md

@@ -8,10 +8,21 @@ 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.20.0
+
+Image generation, riding Pi 1.0's new `models.generateImages()` API:
+
+- **`generate_image` tool** — agent-facing image creation with the session's image-generation models (feature-detected; silently absent on pi < 1.0). Prompt leaves only after the data-egress consent gate; the call reports usage/cost through the normal session accounting.
+- **Generated images join the pipeline** — results return as image blocks (vision base models see the pixels) **and** are persisted in the recall stores, so a text-only base model gets an automatic vision-model description (same as any tool-returned image), `#` recall works once described, and `analyze_image` can re-query or crop them via their `image="<id>"` ids.
+- **Codemode-friendly** — `outputSchema`-shaped `structuredContent` (provider, model, per-image ids/dimensions, `costUSD`) so scripts consume results programmatically; leans into Pi 1.0's leaner codemode with a compact description and recovery-style errors (close-match model suggestions, expected `provider/model-id` format, actionable `pi --login` hint when nothing is keyed).
+- **Shared cost guard** — `generate_image` counts against the same per-turn tool-call budget as `analyze_image`.
+
 ## What's new in 1.19.0
 
 Deep integration with recent Pi releases (0.87 / 0.99):
 
+- **`generate_image` tool (Pi ≥ 1.0)** — the agent can now **create** images, not just understand them. Calls run through `models.generateImages()` with the session's credentials (usage counts toward session cost), the model defaults to the first keyed image-generation model (override per call with `model: "provider/model-id"`), results carry image blocks plus stable `image="<id>"` ids, and the existing pipeline takes over automatically: text-only base models get an auto-description via your vision model, and every generated image is recallable (`#`) and re-analyzable/croppable with `analyze_image` like any attachment. Data-egress consent gates the provider before the first call.
+- **Pi 1.0 alignment (1.19.1)** — leaner `analyze_image` description (~40% smaller — codemode lists tools under a 3000-token budget and drops what doesn't fit), recovery-style errors that name close matches (model typos, recall ids) and expected shapes (crops), and a dynamic implicit-vision-model fallback via `getAvailableOfType()` when the curated chain is entirely unkeyed.
 - **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.

package/extensions/__tests__/internal.test.ts

@@ -79,6 +79,9 @@ import {
 	bufferToPiAiImage,
 	shouldStripImages,
 	selectVisionModels,
+	closeMatches,
+	pickDynamicVisionCandidate,
+	resolveImageGenModelChoice,
 	splitSubcommand,
 	stripImagePaths,
 	stripMediaPaths,
@@ -374,6 +377,116 @@ describe("selectVisionModels", () => {
 	});
 });
 
+describe("closeMatches", () => {
+	const catalog = [
+		"anthropic/claude-sonnet-5",
+		"anthropic/claude-sonnet-4-5",
+		"deepseek/deepseek-v4-flash-vision-exp",
+		"zai/glm-5.3-flash",
+		"openai/gpt-5.6",
+	];
+
+	it("ranks a near-typo above unrelated models", () => {
+		assert.deepEqual(closeMatches("anthropic/claude-sont-5", catalog, 2), [
+			"anthropic/claude-sonnet-5",
+			"anthropic/claude-sonnet-4-5",
+		]);
+	});
+
+	it("gives substring matches a strong bonus", () => {
+		assert.deepEqual(closeMatches("glm", catalog, 1), ["zai/glm-5.3-flash"]);
+	});
+
+	it("returns nothing for queries with no reasonable match", () => {
+		assert.deepEqual(closeMatches("banana-pudding", catalog), []);
+	});
+
+	it("is deterministic on ties (alphabetical)", () => {
+		assert.deepEqual(closeMatches("mod", ["mod-b", "mod-a", "mod-c"], 3), ["mod-a", "mod-b", "mod-c"]);
+	});
+
+	it("handles empty input", () => {
+		assert.deepEqual(closeMatches("", catalog), []);
+		assert.deepEqual(closeMatches("x", []), []);
+	});
+});
+
+describe("pickDynamicVisionCandidate", () => {
+	const m = (provider: string, modelId: string, input: readonly string[] = ["text", "image"]) => ({
+		provider,
+		modelId,
+		input,
+	});
+
+	it("prefers a cheap-tier model over registry order", () => {
+		const out = pickDynamicVisionCandidate([
+			m("anthropic", "claude-opus-6"),
+			m("zai", "glm-5.3-flash"),
+		]);
+		assert.equal(out?.modelId, "glm-5.3-flash");
+	});
+
+	it("falls back to the first image-capable model when none is cheap-tier", () => {
+		const out = pickDynamicVisionCandidate([m("anthropic", "claude-opus-6"), m("x", "y")]);
+		assert.equal(out?.modelId, "claude-opus-6");
+	});
+
+	it("skips models without image input and empty lists", () => {
+		assert.equal(pickDynamicVisionCandidate([m("a", "b", ["text"])]), undefined);
+		assert.equal(pickDynamicVisionCandidate([]), undefined);
+	});
+});
+
+describe("resolveImageGenModelChoice", () => {
+	const available = [
+		{ provider: "openrouter", modelId: "gpt-image-1" },
+		{ provider: "openrouter", modelId: "flux-schnell" },
+		{ provider: "google", modelId: "imagen-4" },
+	];
+
+	it("defaults to the first available model without an override", () => {
+		assert.deepEqual(resolveImageGenModelChoice(undefined, available), {
+			ok: true,
+			provider: "openrouter",
+			modelId: "gpt-image-1",
+		});
+		assert.deepEqual(resolveImageGenModelChoice("", available), {
+			ok: true,
+			provider: "openrouter",
+			modelId: "gpt-image-1",
+		});
+	});
+
+	it("accepts an exact override", () => {
+		assert.deepEqual(resolveImageGenModelChoice("google/imagen-4", available), {
+			ok: true,
+			provider: "google",
+			modelId: "imagen-4",
+		});
+	});
+
+	it("mistyped overrides carry recovery-style close matches", () => {
+		const out = resolveImageGenModelChoice("openrouter/gpt-imge-1", available);
+		assert.equal(out.ok, false);
+		if (!out.ok) {
+			assert.match(out.error, /not found/);
+			assert.ok(out.suggestions.includes("openrouter/gpt-image-1"));
+		}
+	});
+
+	it("rejects malformed model strings with the expected format", () => {
+		const out = resolveImageGenModelChoice("no-slash", available);
+		assert.equal(out.ok, false);
+		if (!out.ok) assert.match(out.error, /Expected format: provider\/model-id/);
+	});
+
+	it("errors with an actionable hint when nothing is keyed", () => {
+		const out = resolveImageGenModelChoice(undefined, []);
+		assert.equal(out.ok, false);
+		if (!out.ok) assert.match(out.error, /pi --login/);
+	});
+});
+
 describe("sanitizeProviderHeaders", () => {
 	it("drops null deletion markers", () => {
 		assert.deepEqual(
@@ -1844,6 +1957,21 @@ describe("resolveCropEntry", () => {
 			/zero area/,
 		);
 	});
+
+	it("zero-area normalized errors carry a recovery hint (pi 1.0 style)", () => {
+		assert.throws(
+			() =>
+				resolveCropEntry({ image_index: 0, normalized: { x: 1.0, y: 1.0, width: 0, height: 0 } }, 100, 100),
+			/fractions of the image/,
+		);
+	});
+
+	it("zero-area pixel errors carry a recovery hint (pi 1.0 style)", () => {
+		assert.throws(
+			() => resolveCropEntry({ image_index: 0, pixels: { x: 200, y: 200, width: 10, height: 10 } }, 100, 100),
+			/inside the image/,
+		);
+	});
 });
 
 describe("cropSignature", () => {

package/extensions/__tests__/recall-autocomplete.test.ts

@@ -16,6 +16,16 @@ describe("extractRecallToken", () => {
 		assert.deepEqual(extractRecallToken(["#"], 0, 1), { query: "", prefix: "#" });
 	});
 
+	it("matches a # token after leading whitespace (pi #10218 mirror)", () => {
+		// Pi 1.0 fixed slash-command autocomplete not triggering when the input
+		// starts with whitespace; the # recall provider must behave the same.
+		assert.deepEqual(extractRecallToken(["  #shot"], 0, 7), {
+			query: "shot",
+			prefix: "#shot",
+		});
+		assert.deepEqual(extractRecallToken(["   #"], 0, 4), { query: "", prefix: "#" });
+	});
+
 	it("matches a # token after whitespace with a partial query", () => {
 		assert.deepEqual(extractRecallToken(["zoom into #shot"], 0, 15), {
 			query: "shot",

package/extensions/internal.ts

@@ -2373,6 +2373,112 @@ export function selectVisionModels<T extends VisionModelLike>(
 	return all.filter((m) => m.input.includes("image"));
 }
 
+/** Lowercased bigram set of a string, for Dice-coefficient similarity. */
+function bigrams(s: string): Set<string> {
+	const t = s.toLowerCase();
+	const out = new Set<string>();
+	for (let i = 0; i + 1 < t.length; i++) out.add(t.slice(i, i + 2));
+	return out;
+}
+
+/**
+ * Close-match suggestions for a mistyped identifier, in the spirit of Pi
+ * 1.0's codemode recovery errors ("tools.Bash suggests tools.bash").
+ * Ranks by Dice bigram similarity with a strong exact/substring bonus;
+ * returns at most `limit` candidates above the relevance floor, best first,
+ * ties broken alphabetically so the output is deterministic.
+ */
+export function closeMatches(query: string, candidates: readonly string[], limit = 3): string[] {
+	if (!query || candidates.length === 0) return [];
+	const q = query.toLowerCase();
+	const scored = candidates.map((candidate) => {
+		const c = candidate.toLowerCase();
+		let score: number;
+		if (c === q) score = 2;
+		else if (c.includes(q) || q.includes(c)) score = 1.5;
+		else {
+			const bq = bigrams(q);
+			const bc = bigrams(c);
+			let shared = 0;
+			for (const g of bq) if (bc.has(g)) shared++;
+			score = bq.size === 0 || bc.size === 0 ? 0 : (2 * shared) / (bq.size + bc.size);
+		}
+		return { candidate, score };
+	});
+	return scored
+		.filter((s) => s.score >= 0.3)
+		.sort((a, b) => b.score - a.score || (a.candidate < b.candidate ? -1 : a.candidate > b.candidate ? 1 : 0))
+		.slice(0, limit)
+		.map((s) => s.candidate);
+}
+
+/** Minimal shape for dynamic (registry-provided) vision candidates. */
+export interface DynamicCandidateLike {
+	provider: string;
+	modelId: string;
+	input?: readonly string[];
+}
+
+/** Cheap-tier heuristic for implicit default resolution (Pi 1.0 last resort). */
+const CHEAP_MODEL_RE = /flash|mini|fast|haiku|express|lite/i;
+
+/**
+ * First keyed registry model with image input — the last-resort implicit
+ * vision default when the curated fallback chain is entirely unkeyed
+ * (Pi ≥ 1.0 `getAvailableOfType("chat")`). Cheap-tier ids are preferred so
+ * an implicit default never lands on a frontier-priced model; registry
+ * order breaks remaining ties.
+ */
+export function pickDynamicVisionCandidate<T extends DynamicCandidateLike>(models: readonly T[]): T | undefined {
+	const vision = models.filter((m) => m.input?.includes("image"));
+	if (vision.length === 0) return undefined;
+	return vision.find((m) => CHEAP_MODEL_RE.test(m.modelId)) ?? vision[0];
+}
+
+/** Outcome of image-generation model resolution (generate_image tool). */
+export type ImageGenModelChoice =
+	| { ok: true; provider: string; modelId: string }
+	| { ok: false; error: string; suggestions: readonly string[] };
+
+/**
+ * Resolve the image-generation model for one `generate_image` call (Pi ≥ 1.0).
+ * An explicit `provider/model-id` override must match an available (keyed)
+ * image model exactly — otherwise the error carries recovery-style close
+ * matches. Without an override the first available model wins.
+ */
+export function resolveImageGenModelChoice(
+	override: string | undefined,
+	available: ReadonlyArray<{ provider: string; modelId: string }>,
+): ImageGenModelChoice {
+	const labels = available.map((m) => `${m.provider}/${m.modelId}`);
+	if (override === undefined || override === "") {
+		const first = available[0];
+		if (!first) {
+			return {
+				ok: false,
+				error: "no image-generation model is available (keyed) in this session — add a provider key (e.g. pi --login openrouter)",
+				suggestions: [],
+			};
+		}
+		return { ok: true, provider: first.provider, modelId: first.modelId };
+	}
+	const parsed = parseModelString(override);
+	if (!parsed) {
+		return {
+				ok: false,
+			error: `invalid model string "${override}". Expected format: provider/model-id`,
+			suggestions: [],
+		};
+	}
+	const exact = available.find((m) => m.provider === parsed.provider && m.modelId === parsed.modelId);
+	if (exact) return { ok: true, provider: exact.provider, modelId: exact.modelId };
+	return {
+		ok: false,
+		error: `model "${parsed.provider}/${parsed.modelId}" not found among available image-generation models`,
+		suggestions: closeMatches(`${parsed.provider}/${parsed.modelId}`, labels, 3),
+	};
+}
+
 export function shouldStripImages(config: VisionConfig, modelInput: readonly string[] | undefined): boolean {
 	if (config.mode === "off") return false;
 	if (config.mode === "always") return true;
@@ -2524,12 +2630,20 @@ export function resolveCropEntry(crop: CropEntry, imgWidth: number, imgHeight: n
 	}
 	if ("normalized" in crop) {
 		const result = normalizedToPixels(crop.normalized, imgWidth, imgHeight);
-		if (!result) throw new Error(`Normalized crop has zero area after clamping (image: ${imgWidth}x${imgHeight})`);
+		if (!result)
+			throw new Error(
+				`Normalized crop has zero area after clamping (image: ${imgWidth}x${imgHeight}). ` +
+					`Use fractions of the image: x ≥ 0, y ≥ 0, x + width ≤ 1, y + height ≤ 1.`,
+			);
 		return result;
 	}
 	if ("pixels" in crop) {
 		const result = clampPixels(crop.pixels, imgWidth, imgHeight);
-		if (!result) throw new Error(`Pixel crop has zero area after clamping (image: ${imgWidth}x${imgHeight})`);
+		if (!result)
+			throw new Error(
+				`Pixel crop has zero area after clamping (image: ${imgWidth}x${imgHeight}). ` +
+					`Keep the rectangle inside the image: x ≥ 0, y ≥ 0, x + width ≤ ${imgWidth}, y + height ≤ ${imgHeight}.`,
+			);
 		return result;
 	}
 	throw new Error("Invalid CropEntry: must have exactly one of region, normalized, or pixels");

package/extensions/vision-proxy.ts

@@ -282,6 +282,9 @@ import {
 	canonicalYouTubeUrl,
 	youTubeVideoId,
 	applyDefaultModelFallback,
+	closeMatches,
+	pickDynamicVisionCandidate,
+	resolveImageGenModelChoice,
 	DEFAULT_MODEL_FALLBACKS,
 	applyRecallCompletion,
 	buildRecallItems,
@@ -450,27 +453,69 @@ const AnalyzeImageOutput = Type.Object({
 });
 
 const TOOL_DESCRIPTION = [
-	"Use `analyze_image` when (a) the cached description of an image lacks a detail you need,",
-	"(b) you need to compare or cross-reference multiple images, or (c) you need to focus on a specific region.",
+	"Targeted image analysis with cropping and model-native grounding support.",
 	"",
-	"**Cropping.** Three forms, in order of preference:",
+	"Use it when (a) a cached image description lacks a detail you need, (b) you must compare or cross-reference images, or (c) you must focus on a region. The result is authoritative for the question asked; the cached generic description stays the default for everything else.",
 	"",
-	"- **`region`** - coarse cut by name. Use when you don't have exact dimensions: `{ image_index: 0, region: \"bottom-right\" }`.",
-	"- **`normalized`** - fractional coordinates 0.0-1.0. Default choice for precise crops without knowing image dimensions: `{ image_index: 0, normalized: { x: 0.5, y: 0.5, width: 0.4, height: 0.4 } }`.",
-	"- **`pixels`** - absolute pixels. Use only when you have authoritative coordinates from a prior `<vision_proxy_description>` or `<vision_proxy_analysis>` (which carry `width` and `height` attributes) or from a previous grounded response. Example: `{ image_index: 0, pixels: { x: 1840, y: 120, width: 840, height: 360 } }`.",
+	"Image references are file paths OR the `image=\"<id>\"` id carried by every `<vision_proxy_description>`/`<vision_proxy_analysis>`/`<vision_proxy_joint_description>` fence — pass an id to re-examine or crop an image the user shared earlier, even if it is no longer attached.",
 	"",
-	"Image dimensions and filenames are available in the `width`, `height`, and `filename` attributes of `<vision_proxy_description>`, `<vision_proxy_analysis>`, and `<vision_proxy_joint_description>` blocks in your context.",
+	"Cropping, in order of preference (one crop per image, keyed by `image_index`):",
+	"- `region` — named cut (`top-left`, `bottom-right`, `center`, `right-half`, …) when you don't know the dimensions: `{ image_index: 0, region: \"bottom-right\" }`.",
+	"- `normalized` — `{ x, y, width, height }` as 0.0-1.0 fractions; the default for precise crops without dimensions.",
+	"- `pixels` — `{ x, y, width, height }` absolute; only with authoritative coordinates from a prior fence's `width`/`height` attributes or a grounded response.",
 	"",
-	"**Recalling an earlier image.** Every such block also carries an `image=\"...\"` id. To re-examine or crop an image the user shared earlier in the session — even if it is no longer attached to the current message (e.g. \"zoom into that screenshot from before\") — pass that id as the image reference instead of a file path. No re-attachment is required.",
-	"",
-	"When a crop is applied, the response fence carries a `crop_origin` attribute (e.g. `crop_origin=\"1840,120\"`). Add the origin's x to any returned x-coordinate and the origin's y to any returned y-coordinate to map coordinates back to the original full image.",
-	"",
-	"The tool result is authoritative for the specific question asked; the cached generic description remains the default for everything else.",
+	"Fences carry `width`, `height`, and `filename`, and a crop adds `crop_origin=\"x,y\"` — add the origin to returned coordinates to map them back to the full image.",
 ].join("\n");
 
 /** Maximum analyze_image tool calls per agent turn. Prevents cost runaway. */
 const MAX_TOOL_CALLS_PER_TURN = 10;
 
+/**
+ * generate_image parameters (Pi ≥ 1.0). Lean on purpose: pi 1.0's codemode
+ * lists tool declarations under a 3000-token inline budget.
+ */
+const GenerateImageParams = Type.Object({
+	prompt: Type.String({
+		description: "Required, non-empty, max 4000 chars. What to draw; include style and aspect-ratio cues the provider supports.",
+	}),
+	model: Type.Optional(
+		Type.String({
+			description: "Optional; provider/model-id of an image-generation model. Defaults to the first available (keyed) image model.",
+		}),
+	),
+	reason: Type.Optional(Type.String({ description: "Optional; logged for analytics only" })),
+});
+
+/**
+ * outputSchema of generate_image: codemode scripts receive this
+ * structuredContent instead of the text + image blocks.
+ */
+const GenerateImageOutput = Type.Object({
+	ok: Type.Boolean({ description: "Whether generation succeeded." }),
+	error: Type.Optional(Type.String({ description: "Failure message, present when ok is false." })),
+	provider: Type.Optional(Type.String({ description: "Provider that generated the images." })),
+	model: Type.Optional(Type.String({ description: "Model id that generated the images." })),
+	images: Type.Optional(
+		Type.Array(
+			Type.Object({
+				id: Type.String({ description: "Stable image id usable for recall (image=\"...\") and analyze_image." }),
+				mimeType: Type.String(),
+				width: Type.Optional(Type.Number()),
+				height: Type.Optional(Type.Number()),
+			}),
+		),
+	),
+	costUSD: Type.Optional(Type.Number({ description: "Reported generation cost, when the provider returned usage." })),
+});
+
+const GENERATE_IMAGE_DESCRIPTION = [
+	"Generate images with the session's image-generation models (Pi ≥ 1.0, request-time credentials).",
+	"",
+	"`prompt` describes what to draw; `model` optionally picks an image-generation model (provider/model-id — defaults to the first available).",
+	"Returns image blocks attached to this result plus stable `image=\"<id>\"` ids that analyze_image can re-analyze or crop like any other image.",
+	"Each call costs money — use it when the user asks for an image to be created, not speculatively.",
+].join("\n");
+
 /** Default tool-result cache size; resized to config.cacheSize on first use. */
 const DEFAULT_TOOL_CACHE_SIZE = 50;
 
@@ -508,6 +553,10 @@ interface SessionState {
 	compaction?: { reason?: "manual" | "threshold" | "overflow"; willRetry?: boolean };
 	/** Cached "provider/model has an API key" probes (cleared per session). */
 	keyProbe?: Map<string, boolean>;
+	/** Cached dynamic (registry-keyed) vision candidate; null = none or runtime without the API (Pi ≥ 1.0). */
+	dynamicVisionProbe?: { provider: string; modelId: string } | null;
+	/** Cached available (keyed) image-generation models (Pi ≥ 1.0). */
+	imageGenModels?: Array<{ provider: string; modelId: string }>;
 	/** Last implicit-default substitution already notified this session. */
 	notifiedDefaultSub?: string;
 	/**
@@ -762,7 +811,56 @@ async function withModelFallback(config: VisionConfig, ctx: ExtensionContext): P
 		keys.set(`${pair.provider}/${pair.modelId}`, await probe(pair.provider, pair.modelId));
 	}
 	const hasKey = (p: string, m: string) => keys.get(`${p}/${m}`) === true;
-	return applyDefaultModelFallback(config, hasModel, false, hasKey);
+	const resolved = applyDefaultModelFallback(config, hasModel, false, hasKey);
+	// Pi ≥ 1.0 last resort: the curated chain can be entirely unkeyed while
+	// the user has another keyed vision-capable model (openrouter, google, …).
+	// getAvailableOfType lists exactly those — land the implicit default on
+	// the first one instead of dead-ending on the "No API key" notice.
+	// (Explicit choices returned early above; a keyed chain resolution already
+	// changed provider/modelId, which the equality check skips.)
+	const anyKeyed = [...keys.values()].some(Boolean);
+	if (!anyKeyed && resolved.provider === config.provider && resolved.modelId === config.modelId) {
+		const dyn = await dynamicVisionCandidate(ctx);
+		if (dyn) return { ...resolved, provider: dyn.provider, modelId: dyn.modelId };
+	}
+	return resolved;
+}
+
+/**
+ * Pi ≥ 1.0 dynamic vision-candidate probe (ModelRegistry.getAvailableOfType):
+ * the first keyed chat model with image input, cheap tier preferred
+ * (pickDynamicVisionCandidate). Feature-detected — older runtimes and probe
+ * failures cache as null; the probe runs once per session.
+ */
+async function dynamicVisionCandidate(ctx: ExtensionContext): Promise<{ provider: string; modelId: string } | null> {
+	const state = getSessionState(ctx);
+	if (state.dynamicVisionProbe !== undefined) return state.dynamicVisionProbe;
+	let out: { provider: string; modelId: string } | null = null;
+	const reg = ctx.modelRegistry as ModelRegistry & {
+		getAvailableOfType?: (type: string) => Promise<ReadonlyArray<unknown>>;
+	};
+	if (typeof reg.getAvailableOfType === "function") {
+		try {
+			const available = await reg.getAvailableOfType("chat");
+			const candidates = (
+				available as ReadonlyArray<{ provider?: unknown; id?: unknown; input?: unknown }>
+			)
+				.filter(
+					(m): m is { provider: string; id: string; input: readonly string[] } =>
+						typeof m.provider === "string" &&
+						typeof m.id === "string" &&
+						Array.isArray(m.input) &&
+						m.input.includes("image"),
+				)
+				.map((m) => ({ provider: m.provider, modelId: m.id, input: m.input }));
+			const pick = pickDynamicVisionCandidate(candidates);
+			if (pick) out = { provider: pick.provider, modelId: pick.modelId };
+		} catch {
+			out = null;
+		}
+	}
+	state.dynamicVisionProbe = out;
+	return out;
 }
 
 /**
@@ -1646,6 +1744,234 @@ function analysisError(message: string): AnalyzeImageOutcome {
 	return { text: message, isError: true, structured: { ok: false, error: message } };
 }
 
+/**
+ * Close-match vision-model suggestions for recovery-style tool errors, in
+ * the spirit of Pi 1.0's codemode errors ("tools.Bash suggests
+ * tools.bash"). Labels every registry model with image input; no key
+ * probing — error paths must stay cheap.
+ */
+function registryVisionSuggestions(ctx: ExtensionContext, query: string, limit = 3): string[] {
+	try {
+		const models = ctx.modelRegistry.getAll() as unknown as ReadonlyArray<{
+			provider?: unknown;
+			id?: unknown;
+			input?: unknown;
+		}>;
+		const labels = models
+			.filter(
+				(m): m is { provider: string; id: string; input: readonly string[] } =>
+					typeof m.provider === "string" &&
+					typeof m.id === "string" &&
+					Array.isArray(m.input) &&
+					m.input.includes("image"),
+			)
+			.map((m) => `${m.provider}/${m.id}`);
+		return closeMatches(query, labels, limit);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Close-match recall-id suggestions: matches the mistyped id against every
+ * retained image's hash (and filename, when known) and returns full ids the
+ * agent can pass verbatim.
+ */
+function recallSuggestions(imageData: ImageDataStore, imageMeta: ImageMetaStore, query: string, limit = 3): string[] {
+	const candidates: string[] = [];
+	try {
+		for (const hash of imageData.map.keys()) {
+			const meta = imageMeta.get(hash);
+			candidates.push(meta?.filename ? `${hash} (${meta.filename})` : hash);
+		}
+	} catch {
+		return [];
+	}
+	return closeMatches(query, candidates, limit);
+}
+
+/** Content block shapes a tool result may carry (text and/or image). */
+type ToolContentBlock = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+/** Structured outcome of one generate_image call (1.20.0). */
+interface GenerateImageOutcome {
+	content: ToolContentBlock[];
+	isError?: boolean;
+	structured?: Record<string, unknown>;
+	usage?: unknown;
+}
+
+/** Wrap a failure message as a GenerateImageOutcome. */
+function generationError(message: string): GenerateImageOutcome {
+	return { content: [{ type: "text", text: message }], isError: true, structured: { ok: false, error: message } };
+}
+
+/**
+ * Available (keyed) image-generation models via getAvailableOfType("image")
+ * (Pi ≥ 1.0, feature-detected). Cached per session; probe failures cache as
+ * an empty list so a transient error cannot wedge the tool.
+ */
+async function availableImageGenModels(ctx: ExtensionContext): Promise<Array<{ provider: string; modelId: string }>> {
+	const state = getSessionState(ctx);
+	if (state.imageGenModels) return state.imageGenModels;
+	let out: Array<{ provider: string; modelId: string }> = [];
+	const reg = ctx.modelRegistry as ModelRegistry & {
+		getAvailableOfType?: (type: string) => Promise<ReadonlyArray<unknown>>;
+	};
+	if (typeof reg.getAvailableOfType === "function") {
+		try {
+			const models = (await reg.getAvailableOfType("image")) as ReadonlyArray<{ provider?: unknown; id?: unknown }>;
+			out = models
+				.filter((m): m is { provider: string; id: string } => typeof m.provider === "string" && typeof m.id === "string")
+				.map((m) => ({ provider: m.provider, modelId: m.id }));
+		} catch {
+			out = [];
+		}
+	}
+	state.imageGenModels = out;
+	return out;
+}
+
+/** Minimal response shape of ModelRegistry.generateImages() (Pi ≥ 1.0). */
+interface GenerateImagesResponseLike {
+	output?: ReadonlyArray<{ type?: unknown; data?: unknown; mimeType?: unknown }>;
+	usage?: { costUSD?: unknown; inputTokens?: unknown; outputTokens?: unknown };
+	stopReason?: unknown;
+	errorMessage?: unknown;
+}
+
+/**
+ * Generate one or more images with the session's image-generation models
+ * (Pi ≥ 1.0 `models.generateImages()`): resolve the model (explicit override
+ * with recovery-style suggestions, else the first keyed image model), gate
+ * on data-egress consent (the prompt leaves), call the registry, and return
+ * image blocks the conversation can see. Generated images are persisted in
+ * the recall stores, so analyze_image (and `#` recall once described) work
+ * on them exactly like attached images — including when the base model sees
+ * the pixels directly and the tool_result auto-description path never fires.
+ */
+async function handleGenerateImage(
+	params: { prompt: string; model?: string; reason?: string },
+	ctx: ExtensionContext,
+	config: VisionConfig,
+): Promise<GenerateImageOutcome> {
+	const prompt = typeof params.prompt === "string" ? params.prompt.trim() : "";
+	if (!prompt) return generationError("Error: prompt is required and must be non-empty.");
+	if (prompt.length > 4000) return generationError("Error: prompt must be at most 4000 characters.");
+
+	// Resolve the image-generation model.
+	const available = await availableImageGenModels(ctx);
+	const choice = resolveImageGenModelChoice(params.model, available);
+	if (!choice.ok) {
+		return generationError(
+			`Error: ${choice.error}.` +
+				(choice.suggestions.length > 0 ? ` Close matches: ${choice.suggestions.join(", ")}.` : ""),
+		);
+	}
+
+	// Data-egress consent: the prompt leaves for the image provider.
+	const entries = ctx.sessionManager.getEntries();
+	if (!hasConsent(entries, choice.provider, config.allowedProviders, config.deniedProviders)) {
+		return generationError(
+			`Error: consent required before sending the prompt to ${choice.provider}. Please tell the user to run the following command and then retry:\n\n/multimodal-proxy consent yes\n\n(To pre-consent this provider permanently: /multimodal-proxy allowed-providers add ${choice.provider})`,
+		);
+	}
+
+	// Fetch the ImageModel object for the chosen pair (sync registry lookups).
+	const reg = ctx.modelRegistry as ModelRegistry & {
+		getModelsOfType?: (type: string) => ReadonlyArray<unknown>;
+		findOfType?: (type: string, provider: string, modelId: string) => unknown;
+		generateImages?: (
+			model: unknown,
+			context: { input: Array<{ type: "text"; text: string }> },
+			options?: { signal?: AbortSignal },
+		) => Promise<GenerateImagesResponseLike>;
+	};
+	if (typeof reg.generateImages !== "function") {
+		return generationError("Error: this pi runtime does not expose models.generateImages() (needs pi ≥ 1.0). Update pi.");
+	}
+	let imageModel: unknown;
+	if (typeof reg.getModelsOfType === "function") {
+		const all = reg.getModelsOfType("image") as ReadonlyArray<{ provider?: unknown; id?: unknown }>;
+		imageModel = all.find(
+				(m) =>
+					typeof m.provider === "string" &&
+					typeof m.id === "string" &&
+					m.provider === choice.provider &&
+					m.id === choice.modelId,
+		);
+	}
+	if (!imageModel && typeof reg.findOfType === "function") {
+		imageModel = reg.findOfType("image", choice.provider, choice.modelId);
+	}
+	if (!imageModel) {
+		return generationError(
+			`Error: image model "${choice.provider}/${choice.modelId}" could not be resolved in the registry.`,
+		);
+	}
+
+	let response: GenerateImagesResponseLike;
+	try {
+		response = await reg.generateImages(imageModel, { input: [{ type: "text", text: prompt }] }, { signal: ctx.signal });
+	} catch (err) {
+		return generationError(`Error: image generation failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (response.stopReason === "aborted") return generationError("Error: generation was cancelled.");
+	if (response.stopReason === "error") {
+		return generationError(
+			`Error: image generation failed: ${typeof response.errorMessage === "string" ? response.errorMessage : "unknown provider error"}`,
+		);
+	}
+
+	const blocks = (response.output ?? []).filter(
+		(b): b is { type: "image"; data: string; mimeType: string } =>
+			b.type === "image" && typeof b.data === "string" && typeof b.mimeType === "string",
+	);
+	if (blocks.length === 0) {
+		return generationError(
+			"Error: the model returned no images (text-only response). Try a different prompt or model.",
+		);
+	}
+
+	// Persist recall data so analyze_image (and # recall, once a description
+	// exists) work on generated images even when the base model sees the
+	// pixels directly and the tool_result auto-description path never fires.
+	const { imageMeta, imageData } = getSessionState(ctx);
+	const structuredImages: Array<Record<string, unknown>> = [];
+	for (const b of blocks) {
+		const hash = hashImageData(b.data);
+		const ext = b.mimeType.split("/")[1]?.replace(/[^a-z0-9]/gi, "") || "png";
+		storeImageMeta(imageMeta, hash, b.data, `generated-${hash.slice(0, 8)}.${ext}`);
+		storeImageData(imageData, hash, b.data, b.mimeType);
+		const dims = imageMeta.get(hash);
+		structuredImages.push({
+			id: hash,
+			mimeType: b.mimeType,
+			...(dims ? { width: dims.width, height: dims.height } : {}),
+		});
+	}
+
+	const costUSD = typeof response.usage?.costUSD === "number" ? response.usage.costUSD : undefined;
+	const ids = structuredImages.map((i) => `image="${i.id}"`).join(", ");
+	const text =
+		`[generate_image] ${pluralImages(blocks.length)} generated via ${choice.provider}/${choice.modelId}` +
+		(ids ? ` (${ids})` : "") +
+		(costUSD !== undefined ? ` — cost $${costUSD.toFixed(4)}` : "") +
+		". The images are attached as image blocks; their ids can be re-analyzed or cropped with analyze_image.";
+
+	return {
+		content: [{ type: "text", text }, ...blocks],
+		structured: {
+			ok: true,
+			provider: choice.provider,
+			model: choice.modelId,
+			images: structuredImages,
+			...(costUSD !== undefined ? { costUSD } : {}),
+		},
+		...(response.usage ? { usage: response.usage } : {}),
+	};
+}
+
 /**
  * Answer a targeted analyze_image question about one or more images: resolve
  * references (session recall ids or file paths), validate and apply crops,
@@ -1709,7 +2035,12 @@ async function handleAnalyzeImage(
 	// Verify model exists and supports images
 	const visionModel = ctx.modelRegistry.find(visionProvider, visionModelId);
 	if (!visionModel) {
-		return analysisError(`Error: model "${visionProvider}/${visionModelId}" not found in registry. Use /multimodal-proxy pick to choose a vision model.`);
+		const suggestions = registryVisionSuggestions(ctx, `${visionProvider}/${visionModelId}`);
+		return analysisError(
+			`Error: model "${visionProvider}/${visionModelId}" not found in registry.` +
+				(suggestions.length > 0 ? ` Close matches: ${suggestions.join(", ")}.` : "") +
+				" Use /multimodal-proxy pick to choose a vision model.",
+		);
 	}
 	if (!visionModel.input.includes("image")) {
 		return analysisError(`Error: model "${visionModel.name ?? visionModelId}" does not support image input.`);
@@ -1731,7 +2062,12 @@ async function handleAnalyzeImage(
 		if (recallHash) {
 			const stored = getImageData(imageData, recallHash);
 			if (!stored) {
-				return analysisError(`Error: image "${recallHash}" is not available for recall — it may have expired from the session cache or was never analyzed. Ask the user to re-attach it, or pass a file path.`);
+				const suggestions = recallSuggestions(imageData, imageMeta, recallHash);
+				return analysisError(
+					`Error: image "${recallHash}" is not available for recall — it may have expired from the session cache or was never analyzed.` +
+						(suggestions.length > 0 ? ` Close ids still retained: ${suggestions.join(", ")}.` : "") +
+						" Ask the user to re-attach it, or pass a file path.",
+				);
 			}
 			const image: PiAiImage = { type: "image", data: stored.data, mimeType: stored.mimeType };
 			// Backfill dimensions if metadata was evicted, so crops still work on recall.
@@ -2000,6 +2336,7 @@ interface EditorAutocompleteProvider {
 
 export default function (pi: ExtensionAPI) {
 	let _toolRegistered = false;
+	let _generateToolRegistered = false;
 	let _autocompleteRegistered = false;
 
 	/**
@@ -2235,7 +2572,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 	/** Register or unregister the analyze_image tool based on config. */
-	function syncToolRegistration(config: VisionConfig) {
+	function syncToolRegistration(config: VisionConfig, runtimeCtx?: ExtensionContext) {
 		const shouldHaveTool = config.mode !== "off" && config.tool === "on";
 		if (shouldHaveTool && !_toolRegistered) {
 			pi.registerTool({
@@ -2298,6 +2635,82 @@ export default function (pi: ExtensionAPI) {
 			});
 			_toolRegistered = true;
 		}
+		// generate_image (Pi ≥ 1.0 only): registered alongside analyze_image
+		// when the runtime exposes ModelRegistry.generateImages; silently
+		// skipped on older hosts so the tool never appears there.
+		if (
+			shouldHaveTool &&
+			!_generateToolRegistered &&
+			runtimeCtx &&
+			typeof (runtimeCtx.modelRegistry as ModelRegistry & { generateImages?: unknown }).generateImages ===
+				"function"
+		) {
+			pi.registerTool({
+				name: "generate_image",
+				label: "Generate Image",
+				description: GENERATE_IMAGE_DESCRIPTION,
+				promptSnippet: "Generate images with the session's image-generation models",
+				promptGuidelines: [
+					"Use generate_image when the user explicitly asks to create an image; each call costs money.",
+					'Generated images carry image="<id>" ids and can be re-analyzed or cropped with analyze_image like any other image.',
+				],
+				// Cost-incurring content creation: not read-only. openWorldHint — the
+				// prompt leaves for the configured image provider.
+				annotations: {
+					readOnlyHint: false,
+					destructiveHint: false,
+					idempotentHint: false,
+					openWorldHint: true,
+				},
+				namespace: {
+					name: "multimodal-proxy",
+					description: "pi-multimodal-proxy media analysis (targeted image re-analysis with crop and grounding)",
+				},
+				outputSchema: GenerateImageOutput,
+				parameters: GenerateImageParams,
+				execute: async (_toolCallId, params, _signal, _onUpdate, extCtx) => {
+					const entries = extCtx.sessionManager.getEntries();
+					const config = await withModelFallback(resolveConfig(entries, process.env, _fileConfig), extCtx);
+
+					// Runtime check - tool may have been disabled mid-session
+					if (config.tool !== "on" || config.mode === "off") {
+						return {
+							content: [
+								{
+									type: "text" as const,
+									text: "Error: generate_image tool is currently disabled. Use /multimodal-proxy tool on to enable.",
+								},
+							],
+							isError: true,
+						};
+					}
+
+					// Share the per-turn cost-runaway budget with analyze_image.
+					const state = getSessionState(extCtx);
+					state.toolCallCount++;
+					if (state.toolCallCount > MAX_TOOL_CALLS_PER_TURN) {
+						return {
+							content: [
+								{
+									type: "text" as const,
+									text: `Error: tool call limit reached (${MAX_TOOL_CALLS_PER_TURN} per turn). Try again in the next turn.`,
+								},
+							],
+							isError: true,
+						};
+					}
+
+					const outcome = await handleGenerateImage(params, extCtx, config);
+					return {
+						content: outcome.content,
+						...(outcome.isError ? { isError: true } : {}),
+						...(outcome.structured ? { structuredContent: outcome.structured } : {}),
+						...(outcome.usage !== undefined ? { usage: outcome.usage } : {}),
+					};
+				},
+			});
+			_generateToolRegistered = true;
+		}
 		// Note: Pi's extension API doesn't have unregisterTool - tool registration
 		// persists for the session. The tool's execute handler checks the current
 		// config at runtime and returns an error if disabled.
@@ -2313,6 +2726,8 @@ export default function (pi: ExtensionAPI) {
 		clearImageData(state.imageData);
 		state.compaction = undefined;
 		state.keyProbe = undefined;
+		state.dynamicVisionProbe = undefined;
+		state.imageGenModels = undefined;
 		state.notifiedDefaultSub = undefined;
 
 		_fileConfig = await readPersistentFile();
@@ -2322,7 +2737,7 @@ export default function (pi: ExtensionAPI) {
 		ctx.ui.setStatus("multimodal-proxy", steadyStatusText(config, ctx.modelRegistry));
 
 		// Register tool if enabled
-		syncToolRegistration(config);
+		syncToolRegistration(config, ctx);
 
 		// Register the multimodal-proxy/auto virtual model (pi ≥ 0.99)
 		syncVirtualModelRegistration(config);
@@ -3214,7 +3629,7 @@ export default function (pi: ExtensionAPI) {
 					next.mode === "off" ? "warning" : "info",
 				);
 				// Sync tool registration on mode change
-				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig));
+				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig), ctx);
 				return;
 			}
 
@@ -3626,7 +4041,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				}
 				if (valueLower === "on") {
 					const next = writePersisted({ ...persisted, tool: "on" });
-					syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig));
+					syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig), ctx);
 					ctx.ui.notify(`[multimodal-proxy] analyze_image tool: ON`, "info");
 					return;
 				}
@@ -4367,7 +4782,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				if (modeChoice !== "fallback" && modeChoice !== "always" && modeChoice !== "off") return;
 				const next = writePersisted({ ...persisted, mode: modeChoice });
 				ctx.ui.notify(`Mode set to: ${next.mode}`, "info");
-				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig));
+				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig), ctx);
 				return;
 			}
 
@@ -4396,7 +4811,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				}
 				const nextTool = effective.tool === "on" ? "off" : "on";
 				writePersisted({ ...persisted, tool: nextTool });
-				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig));
+				syncToolRegistration(resolveConfig(ctx.sessionManager.getEntries(), process.env, _fileConfig), ctx);
 				ctx.ui.notify(`Tool: ${nextTool}`, nextTool === "on" ? "info" : "warning");
 				return;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multimodal-proxy",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Automatic image, video and audio description for any model in Pi. Routes media to a multimodal model and injects descriptions into context.",
   "keywords": [
     "pi-package"