pi-multimodal-proxy 1.19.1 → 1.21.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.21.0] - 2026-10-03
+
+### Added
+
+- **Compact transcript rows via `pi.registerToolRenderer()` (Pi ≥ 1.0.1, feature-detected)** — `analyze_image` and `generate_image` calls now render as one compact, themed line each instead of the default JSON-args dump. The `analyze_image` call line shows the question (word-boundary truncated, surrogate-pair safe), image references (recall ids → `image="deadbeef…"`, file paths → file name, `+N more` beyond two shown), a crop summary (`bottom-right@0` / `25%,13% 50%×50%@1` / `128,64 256×256@0` / `crops ×N`), and a model override; `generate_image` shows the prompt and override. Result lines summarize `✓ provider/model · cached · 1.2s` for analyses and `✓ N images via provider/model · $0.0311 · image="<id8>…"` for generations, or `✗ <error>`; expanding a row reveals the full text content. Generated images still render inline from the result's image blocks (independent of `renderResult`), reliable across Kitty/Ghostty/WezTerm/Warp via pi 1.0.1's JPEG/WebP/GIF `Image` fixes.
+- **Renderer coverage for unregistered tools** — registering through `registerToolRenderer` rather than inline `renderCall`/`renderResult` on the tool definitions means the compact rows also apply to calls replayed when the tool is *not registered* at render time: sessions resumed with the tool disabled (`/multimodal-proxy tool off`, mode off), transcript rows rendered before extension load, and HTML exports. Resolver chaining (`next() ?? {}`) preserves other extensions' renderers for the keys we don't set.
+- **Tool-result `details` payloads** — both tools now return a display-sized `details` object (analyze: `ok`/`error`/`cached`/`provider`/`model`/`latencyMs`/`groundingFormat`, with the heavy `text`/`images` stripped; generate: the structured payload as-is — ids/dims/cost) that feeds the renderer and persists in the session log without ever reaching the model.
+- Defensive renderer plumbing: pi-tui's `Text` (ANSI-aware wrapping) is loaded lazily with a width-truncating plain-lines fallback (ANSI-aware, rough wcwidth — pi's differential renderer stops on overwide lines) so an unresolvable package can never block extension load nor crash rendering; the expanded result view renders **every** text block, so a `generate_image` row on a text-only base model (where the `tool_result` hook replaces image blocks with description fences) still shows the per-image descriptions; renderers tolerate partial/garbage streaming args and missing result objects. (PR #37 review: CodeRabbit.)
+- New `tool-render.test.ts` (24 tests: truncation with a surrogate-pair regression trap, ref/crop summarization, call and result lines, garbage tolerance, details stripping) plus a fake-host smoke script (`tools/smoke-renderers.mjs`, real ANSI theme) that loads the real extension module and exercises the resolver contract end-to-end — 540 tests total, all green; also verified loading under the real pi 1.0.1 RPC loader.
+
+### Changed
+
+- Nothing user-visible on pi < 1.0.1 hosts: registration is gated on `typeof pi.registerToolRenderer === "function"`, so older runtimes keep the default tool rendering with zero behavior change.
+
+## [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

package/README.md

@@ -8,10 +8,35 @@ 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.
 
+**Compact tool rows (Pi ≥ 1.0.1)** — `analyze_image` and `generate_image` calls render as one tidy line each (`analyze_image  "What does the legend say?" · 2 images (image="deadbeef…", shot.png) · crop bottom-right@0`) with themed result summaries (`✓ zai/glm-5.3-flash · cached · 1.2s`, `✓ 1 image via google/imagen-4 · $0.0311`), instead of the default JSON-args dump. Generated images still render inline from the result blocks; expand a row to see the full analysis fence.
+
+## What's new in 1.21.0
+
+Adopting Pi 1.0.1's new `pi.registerToolRenderer()` API:
+
+- **Compact transcript rows for `analyze_image`** — the call line shows the question (truncated on a word boundary), the image refs (recall ids shortened to `image="deadbeef…"`, paths to their file name, `+N more` beyond two), a crop summary (`bottom-right@0`, `25%,13% 50%×50%@1`, `128,64 256×256@0`, or `crops ×N`), and any model override — instead of the raw JSON arguments. The result line summarizes `✓ provider/model · cached · latency` (or `✗ <error>`), and expanding the row reveals the full analysis fence.
+- **Compact transcript rows for `generate_image`** — the call line shows the prompt (and any model override); the result line summarizes `✓ N images via provider/model · $cost · image="<id8>…"`. The generated images themselves keep rendering inline — pi draws image blocks from the result content next to the renderer output — so this is purely a better header/summary, now reliable across Kitty, Ghostty, WezTerm, and Warp thanks to pi 1.0.1's JPEG/WebP/GIF image fixes.
+- **Works even when the tool isn't registered** — registering through `registerToolRenderer` (instead of inline `renderCall`/`renderResult` on the tool definitions) covers rows replayed from a session where the tool is now disabled (`/multimodal-proxy tool off`, mode off), resumed sessions, and HTML exports. `next()` chaining preserves renderers from other extensions for the keys we don't set.
+- **Renderer state via tool `details`** — results now carry a display-sized `details` payload (provider/model, `cached`, `latencyMs`, image ids, `costUSD`; heavy fields stripped) that feeds the renderer but never reaches the model.
+- Fully feature-gated (`typeof pi.registerToolRenderer === "function"`): pi < 1.0.1 hosts keep the default rendering, zero behavior change. pi-tui's `Text` component is loaded lazily with a plain-lines fallback so a missing package can never block extension load.
+
+Also benefits from pi 1.0.1 host fixes (no code needed here): Anthropic prompt caches survive mid-session tool toggles (tools added/redefined mid-conversation are now defined inline), "model at capacity" errors are retried instead of ending the turn, and Bedrock Claude thinking-signature failures after tool/prompt changes are fixed.
+
+## 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

@@ -81,6 +81,7 @@ import {
 	selectVisionModels,
 	closeMatches,
 	pickDynamicVisionCandidate,
+	resolveImageGenModelChoice,
 	splitSubcommand,
 	stripImagePaths,
 	stripMediaPaths,
@@ -436,6 +437,56 @@ describe("pickDynamicVisionCandidate", () => {
 	});
 });
 
+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(

package/extensions/__tests__/tool-render.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Unit tests for the tool-transcript rendering helpers (1.21.0).
+ *
+ * These back the pi ≥ 1.0.1 registerToolRenderer() integration: compact
+ * analyze_image / generate_image call and result lines. Pure data in, plain
+ * segments out — theming happens in vision-proxy.ts.
+ *
+ * Run:
+ *   node --experimental-strip-types --test extensions/__tests__/tool-render.test.ts
+ */
+
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import {
+	analyzeDetailsForTranscript,
+	formatAnalyzeImageCall,
+	formatAnalyzeImageResult,
+	formatGenerateImageCall,
+	formatGenerateImageResult,
+	summarizeCrop,
+	summarizeForTranscript,
+	summarizeImageRef,
+} from "../internal.ts";
+
+const HASH32 = "deadbeefdeadbeefdeadbeefdeadbeef";
+
+function plain(segments: ReadonlyArray<{ text: string }>): string {
+	return segments.map((s) => s.text).join("");
+}
+
+describe("summarizeForTranscript", () => {
+	it("passes short text through with collapsed whitespace", () => {
+		assert.equal(summarizeForTranscript("  hello   world\n\tnext  ", 50), "hello world next");
+	});
+
+	it("truncates long text on a word boundary", () => {
+		const out = summarizeForTranscript("alpha bravo charlie delta echo foxtrot golf hotel", 20);
+		assert.ok(out.length <= 20, `length ${out.length}: ${out}`);
+		assert.ok(out.endsWith("…"));
+		assert.ok(!out.endsWith(" …"), "no dangling space before ellipsis");
+	});
+
+	it("never splits a surrogate pair", () => {
+		const emoji = "😀".repeat(60); // each emoji is a surrogate pair
+		const out = summarizeForTranscript(emoji, 20); // odd max → cut lands mid-pair
+		assert.ok(out.length <= 20);
+		// No lone high surrogate anywhere: the string still round-trips as text.
+		// (With the guard removed, the hard cut leaves an unpaired high surrogate
+		// right before the ellipsis, which this regex detects.)
+		assert.ok(!/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/.test(out));
+	});
+});
+
+describe("summarizeImageRef", () => {
+	it("shortens a quoted recall reference", () => {
+		assert.equal(summarizeImageRef(`image="${HASH32}"`), `image="deadbeef…"`);
+	});
+
+	it("shortens an unquoted recall reference and sha256:/#crop forms", () => {
+		assert.equal(summarizeImageRef(`image=${HASH32}`), `image="deadbeef…"`);
+		assert.equal(summarizeImageRef(`sha256:${HASH32}#x0y0`), `image="deadbeef…"`);
+		assert.equal(summarizeImageRef(HASH32), `image="deadbeef…"`);
+	});
+
+	it("reduces file paths to the file name (posix + windows)", () => {
+		assert.equal(summarizeImageRef("/home/u/pics/cat.png"), "cat.png");
+		assert.equal(summarizeImageRef("D:\\Users\\u\\Downloads\\shot (1).jpg"), "shot (1).jpg");
+	});
+
+	it("truncates very long file names", () => {
+		const long = "a".repeat(120) + ".png";
+		const out = summarizeImageRef(long);
+		assert.ok(out.length <= 48);
+		assert.ok(out.endsWith("…"));
+	});
+
+	it("leaves non-hash short junk as-is", () => {
+		assert.equal(summarizeImageRef("not-a-hash"), "not-a-hash");
+	});
+});
+
+describe("summarizeCrop", () => {
+	it("renders named regions with the image index", () => {
+		assert.equal(summarizeCrop({ image_index: 0, region: "bottom-right" }), "bottom-right@0");
+	});
+
+	it("renders normalized crops as percentages", () => {
+		assert.equal(
+			summarizeCrop({ image_index: 1, normalized: { x: 0.25, y: 0.133, width: 0.5, height: 0.5 } }),
+			"25%,13.3% 50%×50%@1",
+		);
+	});
+
+	it("renders pixel crops rounded", () => {
+		assert.equal(
+			summarizeCrop({ image_index: 0, pixels: { x: 128.4, y: 64.2, width: 256, height: 256 } }),
+			"128,64 256×256@0",
+		);
+	});
+
+	it("returns empty for unrecognized input", () => {
+		assert.equal(summarizeCrop(undefined), "");
+		assert.equal(summarizeCrop("nonsense"), "");
+		assert.equal(summarizeCrop({ image_index: 0 }), "crop@0");
+	});
+});
+
+describe("formatAnalyzeImageCall", () => {
+	it("builds a full call line", () => {
+		const segs = formatAnalyzeImageCall({
+			images: [`image="${HASH32}"`, "/tmp/chart.png"],
+			question: "What does the legend say?",
+			crop: [{ image_index: 0, region: "center" }],
+			model: "zai/glm-5.3-flash",
+		});
+		assert.equal(
+			plain(segs),
+			`"What does the legend say?" · 2 images (image="deadbeef…", chart.png) · crop center@0 · zai/glm-5.3-flash`,
+		);
+		assert.equal(segs[0]!.style, "accent");
+	});
+
+	it("collapses many images to two shown plus a count", () => {
+		const segs = formatAnalyzeImageCall({
+			images: ["/a.png", "/b.png", "/c.png", "/d.png"],
+			question: "q",
+		});
+		assert.ok(plain(segs).includes("4 images (a.png, b.png +2)"));
+	});
+
+	it("summarizes multiple crops as a count", () => {
+		const segs = formatAnalyzeImageCall({
+			images: ["/a.png", "/b.png"],
+			question: "q",
+			crop: [
+				{ image_index: 0, region: "top" },
+				{ image_index: 1, region: "bottom" },
+			],
+		});
+		assert.ok(plain(segs).includes("crops ×2"));
+	});
+
+	it("truncates long questions and tolerates garbage args", () => {
+		const long = formatAnalyzeImageCall({ images: ["/a.png"], question: "x".repeat(300) });
+		assert.ok(plain(long).length < 200);
+
+		assert.deepEqual(formatAnalyzeImageCall("junk"), [{ text: '"junk"', style: "muted" }]);
+		assert.deepEqual(formatAnalyzeImageCall(null), [{ text: "null", style: "muted" }]);
+	});
+
+	it("handles missing question/images defensively", () => {
+		const segs = formatAnalyzeImageCall({});
+		assert.equal(plain(segs), '""');
+	});
+});
+
+describe("formatGenerateImageCall", () => {
+	it("builds prompt + model line", () => {
+		const segs = formatGenerateImageCall({ prompt: "A red panda astronaut, watercolor", model: "google/imagen-4" });
+		assert.equal(plain(segs), '"A red panda astronaut, watercolor" · google/imagen-4');
+	});
+
+	it("prompt-only line and garbage fallback", () => {
+		assert.equal(plain(formatGenerateImageCall({ prompt: "cat" })), '"cat"');
+		assert.deepEqual(formatGenerateImageCall(42), [{ text: "42", style: "muted" }]);
+	});
+});
+
+describe("formatAnalyzeImageResult", () => {
+	it("summarizes a successful analysis", () => {
+		const segs = formatAnalyzeImageResult(
+			{ ok: true, provider: "zai", model: "glm-5.3-flash", cached: true, latencyMs: 1234 },
+			false,
+		);
+		assert.equal(plain(segs), "✓ zai/glm-5.3-flash · cached · 1.2s");
+	});
+
+	it("summarizes without optional fields and with model only", () => {
+		assert.equal(plain(formatAnalyzeImageResult({ ok: true }, false)), "✓");
+		assert.equal(plain(formatAnalyzeImageResult({ ok: true, model: "glm-5.3-flash" }, false)), "✓ glm-5.3-flash");
+	});
+
+	it("renders errors from details, isError flag, or a generic fallback", () => {
+		assert.equal(
+			plain(formatAnalyzeImageResult({ ok: false, error: "Error: consent required" }, true)),
+			"✗ Error: consent required",
+		);
+		// isError without details
+		assert.equal(plain(formatAnalyzeImageResult(undefined, true)), "✗ analysis failed");
+		// ok:false wins even without the flag (older rows)
+		assert.equal(plain(formatAnalyzeImageResult({ ok: false }, false)), "✗ analysis failed");
+	});
+
+	it("marks the summary segment styles", () => {
+		const segs = formatAnalyzeImageResult({ ok: true, provider: "zai", model: "m" }, false);
+		assert.equal(segs[0]!.style, "success");
+		assert.equal(segs[1]!.style, "muted");
+	});
+});
+
+describe("formatGenerateImageResult", () => {
+	it("summarizes generation with images, cost, and first id", () => {
+		const segs = formatGenerateImageResult(
+			{
+				ok: true,
+				provider: "google",
+				model: "imagen-4",
+				images: [
+					{ id: HASH32, mimeType: "image/png", width: 1024, height: 768 },
+					{ id: "f".repeat(32), mimeType: "image/png", width: 1024, height: 768 },
+				],
+				costUSD: 0.0311,
+			},
+			false,
+		);
+		assert.equal(plain(segs), `✓ 2 images via google/imagen-4 · $0.0311 · image="deadbeef…" +1`);
+	});
+
+	it("renders errors from details or generically", () => {
+		assert.equal(
+			plain(formatGenerateImageResult({ ok: false, error: "Error: no keyed image model" }, true)),
+			"✗ Error: no keyed image model",
+		);
+		assert.equal(plain(formatGenerateImageResult(undefined, true)), "✗ generation failed");
+	});
+
+	it("falls back to 'done' when details carry no image list", () => {
+		assert.equal(plain(formatGenerateImageResult({ ok: true, provider: "google", model: "imagen-4" }, false)), "✓ done via google/imagen-4");
+	});
+});
+
+describe("analyzeDetailsForTranscript", () => {
+	it("strips text and images but keeps display fields", () => {
+		const out = analyzeDetailsForTranscript({
+			ok: true,
+			text: "a".repeat(2000),
+			images: [{ id: HASH32 }],
+			provider: "zai",
+			model: "glm-5.3-flash",
+			latencyMs: 120,
+		});
+		assert.deepEqual(out, { ok: true, provider: "zai", model: "glm-5.3-flash", latencyMs: 120 });
+	});
+
+	it("does not mutate the input", () => {
+		const input = { ok: true, text: "keep-me", images: [1, 2] };
+		analyzeDetailsForTranscript(input);
+		assert.deepEqual(input, { ok: true, text: "keep-me", images: [1, 2] });
+	});
+});

package/extensions/internal.ts

@@ -2435,6 +2435,50 @@ export function pickDynamicVisionCandidate<T extends DynamicCandidateLike>(model
 	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;
@@ -3219,6 +3263,201 @@ export function buildToolCacheKey(
 	return `${sortedHashes.join("+")}${cropSig ? "#crop:" + cropSig : ""}?q=${questionHash}&m=${modelId}`;
 }
 
+// ── Tool transcript rendering (pi ≥ 1.0.1 registerToolRenderer) ────────────
+
+/**
+ * Styling hints for one segment of a tool-transcript line, mapped to
+ * theme.fg tokens by the renderer in vision-proxy.ts. Kept as plain data so
+ * these helpers stay pure and unit-testable without a terminal theme.
+ */
+export type TranscriptStyle = "plain" | "accent" | "muted" | "dim" | "success" | "warning" | "error";
+
+export interface TranscriptSegment {
+	text: string;
+	style: TranscriptStyle;
+}
+
+/** Collapse whitespace and truncate on a word boundary (surrogate-pair safe). */
+export function summarizeForTranscript(text: string, max: number): string {
+	const t = text.replace(/\s+/g, " ").trim();
+	if (t.length <= max) return t;
+	let cut = t.slice(0, Math.max(1, max - 1));
+	// Never split a surrogate pair on a hard cut (lone high surrogate → U+FFFD).
+	if (/[\uD800-\uDBFF]$/.test(cut)) cut = cut.slice(0, -1);
+	const ws = cut.lastIndexOf(" ");
+	if (ws > cut.length * 0.6) cut = cut.slice(0, ws);
+	return `${cut.trimEnd()}…`;
+}
+
+/** Defensive finite-number check for values coming from model-authored args. */
+function isFiniteNumber(v: unknown): v is number {
+	return typeof v === "number" && Number.isFinite(v);
+}
+
+/** Compact percentage for crop summaries: integral values stay integral. */
+function pct(v: number): string {
+	const p = v * 100;
+	return Math.abs(p - Math.round(p)) < 0.05 ? String(Math.round(p)) : String(Math.round(p * 10) / 10);
+}
+
+/** Safe one-line JSON rendering of an arbitrary value (circular-safe). */
+function safeJson(value: unknown, max = 120): string {
+	try {
+		return summarizeForTranscript(JSON.stringify(value) ?? String(value), max);
+	} catch {
+		return String(value);
+	}
+}
+
+/**
+ * Shorten one analyze_image image reference for display: a recall id
+ * (`image="<hash>"`, `sha256:<hash>#…`, or a bare hash) becomes
+ * `image="deadbeef…"`; a file path becomes its file name (Windows or POSIX).
+ */
+export function summarizeImageRef(ref: string): string {
+	const s = ref.trim().replace(/^["']|["']$/g, "");
+	const quoted = /image="?([a-f0-9]{16,64})"?/i.exec(s);
+	if (quoted) return `image="${quoted[1]!.slice(0, 8)}…"`;
+	const bare = parseRecallRef(s);
+	if (bare) return `image="${bare.slice(0, 8)}…"`;
+	const base = s.replace(/\\/g, "/").split("/").filter(Boolean).pop() ?? s;
+	return summarizeForTranscript(base, 48);
+}
+
+/**
+ * Compact crop descriptor for the transcript: `bottom-right@0`,
+ * `25%,13% 50%×50%@1`, or `128,64 256×256@0`. Empty string when nothing
+ * recognizable.
+ */
+export function summarizeCrop(crop: unknown): string {
+	if (typeof crop !== "object" || crop === null) return "";
+	const c = crop as Record<string, unknown>;
+	const idx =
+		isFiniteNumber(c.image_index) ? `@${Math.trunc(c.image_index)}` : "";
+	if (typeof c.region === "string" && c.region.trim()) return `${c.region.trim()}${idx}`;
+	const box = (c.normalized ?? c.pixels) as Record<string, unknown> | undefined;
+	if (
+		typeof box === "object" &&
+		box !== null &&
+		isFiniteNumber(box.x) &&
+		isFiniteNumber(box.y) &&
+		isFiniteNumber(box.width) &&
+		isFiniteNumber(box.height)
+	) {
+		if (c.normalized !== undefined) {
+			return `${pct(box.x)}%,${pct(box.y)}% ${pct(box.width)}%×${pct(box.height)}%${idx}`;
+		}
+		return `${Math.round(box.x)},${Math.round(box.y)} ${Math.round(box.width)}×${Math.round(box.height)}${idx}`;
+	}
+	return idx ? `crop${idx}` : "";
+}
+
+/** One-line transcript summary of an analyze_image call (pi ≥ 1.0.1 renderer). */
+export function formatAnalyzeImageCall(args: unknown): TranscriptSegment[] {
+	if (typeof args !== "object" || args === null || Array.isArray(args)) {
+		return [{ text: safeJson(args), style: "muted" }];
+	}
+	const a = args as Record<string, unknown>;
+	const out: TranscriptSegment[] = [];
+	const question = typeof a.question === "string" ? a.question : "";
+	out.push({ text: `"${summarizeForTranscript(question, 120)}"`, style: "accent" });
+	const images = Array.isArray(a.images)
+		? a.images.filter((r): r is string => typeof r === "string" && r.trim() !== "")
+		: [];
+	if (images.length > 0) {
+		const shown = images.slice(0, 2).map(summarizeImageRef);
+		const more = images.length - shown.length;
+		out.push({
+			text:
+				` · ${images.length} image${images.length === 1 ? "" : "s"}` +
+				(shown.length ? ` (${shown.join(", ")}${more > 0 ? ` +${more}` : ""})` : ""),
+			style: "muted",
+		});
+	}
+	const crops = Array.isArray(a.crop) ? a.crop.map(summarizeCrop).filter((s) => s !== "") : [];
+	if (crops.length === 1) out.push({ text: ` · crop ${crops[0]}`, style: "dim" });
+	else if (crops.length > 1) out.push({ text: ` · crops ×${crops.length}`, style: "dim" });
+	const model = typeof a.model === "string" && a.model.trim() ? a.model.trim() : undefined;
+	if (model) out.push({ text: ` · ${summarizeForTranscript(model, 60)}`, style: "muted" });
+	return out;
+}
+
+/** One-line transcript summary of a generate_image call (pi ≥ 1.0.1 renderer). */
+export function formatGenerateImageCall(args: unknown): TranscriptSegment[] {
+	if (typeof args !== "object" || args === null || Array.isArray(args)) {
+		return [{ text: safeJson(args), style: "muted" }];
+	}
+	const a = args as Record<string, unknown>;
+	const prompt = typeof a.prompt === "string" ? a.prompt : "";
+	const out: TranscriptSegment[] = [{ text: `"${summarizeForTranscript(prompt, 120)}"`, style: "accent" }];
+	const model = typeof a.model === "string" && a.model.trim() ? a.model.trim() : undefined;
+	if (model) out.push({ text: ` · ${summarizeForTranscript(model, 60)}`, style: "muted" });
+	return out;
+}
+
+function recordOf(details: unknown): Record<string, unknown> | undefined {
+	return typeof details === "object" && details !== null && !Array.isArray(details)
+		? (details as Record<string, unknown>)
+		: undefined;
+}
+
+/** One-line transcript summary of an analyze_image result from its `details`. */
+export function formatAnalyzeImageResult(details: unknown, isError: boolean): TranscriptSegment[] {
+	const d = recordOf(details);
+	if (isError || d?.ok === false) {
+		const msg = typeof d?.error === "string" && d.error ? d.error : "analysis failed";
+		return [{ text: `✗ ${summarizeForTranscript(msg, 160)}`, style: "error" }];
+	}
+	const segments: TranscriptSegment[] = [{ text: "✓", style: "success" }];
+	const provider = typeof d?.provider === "string" && d.provider ? d.provider : undefined;
+	const modelId = typeof d?.model === "string" && d.model ? d.model : undefined;
+	if (provider && modelId) segments.push({ text: ` ${summarizeForTranscript(`${provider}/${modelId}`, 80)}`, style: "muted" });
+	else if (modelId) segments.push({ text: ` ${summarizeForTranscript(modelId, 80)}`, style: "muted" });
+	if (d?.cached === true) segments.push({ text: " · cached", style: "dim" });
+	if (isFiniteNumber(d?.latencyMs)) {
+		segments.push({ text: ` · ${(Math.max(0, d.latencyMs) / 1000).toFixed(1)}s`, style: "dim" });
+	}
+	return segments;
+}
+
+/** One-line transcript summary of a generate_image result from its `details`. */
+export function formatGenerateImageResult(details: unknown, isError: boolean): TranscriptSegment[] {
+	const d = recordOf(details);
+	if (isError || d?.ok === false) {
+		const msg = typeof d?.error === "string" && d.error ? d.error : "generation failed";
+		return [{ text: `✗ ${summarizeForTranscript(msg, 160)}`, style: "error" }];
+	}
+	const images = Array.isArray(d?.images)
+		? (d!.images as unknown[]).filter((x): x is Record<string, unknown> => typeof x === "object" && x !== null)
+		: [];
+	const provider = typeof d?.provider === "string" && d.provider ? d.provider : undefined;
+	const modelId = typeof d?.model === "string" && d.model ? d.model : undefined;
+	const count = images.length > 0 ? `${images.length} image${images.length === 1 ? "" : "s"}` : "done";
+	const segments: TranscriptSegment[] =
+		provider && modelId
+			? [{ text: `✓ ${count} via ${summarizeForTranscript(`${provider}/${modelId}`, 80)}`, style: "success" }]
+			: [{ text: `✓ ${count}`, style: "success" }];
+	if (isFiniteNumber(d?.costUSD)) segments.push({ text: ` · $${Math.max(0, d.costUSD).toFixed(4)}`, style: "dim" });
+	const firstId = typeof images[0]?.id === "string" && images[0].id ? images[0].id : undefined;
+	if (firstId) {
+		const more = images.length > 1 ? ` +${images.length - 1}` : "";
+		segments.push({ text: ` · image="${firstId.slice(0, 8)}…"${more}`, style: "dim" });
+	}
+	return segments;
+}
+
+/**
+ * Copy of a structured analyze_image result without the fields the
+ * transcript renderer never reads — `details` must stay small because it is
+ * persisted in the session log alongside the (already stored) text fence.
+ */
+export function analyzeDetailsForTranscript(structured: Record<string, unknown>): Record<string, unknown> {
+	const rest: Record<string, unknown> = { ...structured };
+	delete rest.text;
+	delete rest.images;
+	return rest;
+}
+
 // ── Fence builders ────────────────────────────────────────────────────────
 
 export interface VideoDescriptionEntry {

package/extensions/vision-proxy.ts

@@ -256,6 +256,12 @@ import {
 	buildVideoProxySection,
 	extractXaiResponsesText,
 	formatXaiSttTranscript,
+	analyzeDetailsForTranscript,
+	formatAnalyzeImageCall,
+	formatAnalyzeImageResult,
+	formatGenerateImageCall,
+	formatGenerateImageResult,
+	type TranscriptSegment,
 	isTranscriptionRequest,
 	isXaiProvider,
 	bufferToPiAiImage,
@@ -284,6 +290,7 @@ import {
 	applyDefaultModelFallback,
 	closeMatches,
 	pickDynamicVisionCandidate,
+	resolveImageGenModelChoice,
 	DEFAULT_MODEL_FALLBACKS,
 	applyRecallCompletion,
 	buildRecallItems,
@@ -469,6 +476,52 @@ const TOOL_DESCRIPTION = [
 /** 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 +561,8 @@ interface SessionState {
 	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;
 	/**
@@ -1741,6 +1796,188 @@ function recallSuggestions(imageData: ImageDataStore, imageMeta: ImageMetaStore,
 	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,
@@ -2105,6 +2342,7 @@ interface EditorAutocompleteProvider {
 
 export default function (pi: ExtensionAPI) {
 	let _toolRegistered = false;
+	let _generateToolRegistered = false;
 	let _autocompleteRegistered = false;
 
 	/**
@@ -2149,6 +2387,227 @@ export default function (pi: ExtensionAPI) {
 		);
 	}
 
+	// ── Tool transcript renderers (pi ≥ 1.0.1) ─────────────────────────────
+
+	/** Minimal structural shape of the TUI component the renderers return. */
+	interface ComponentLike {
+		render(width: number): string[];
+		invalidate?(): void;
+	}
+
+	/** Theme subset the renderers use (pi's Theme helpers). */
+	interface RenderThemeLike {
+		fg(token: string, text: string): string;
+		bold(text: string): string;
+	}
+
+	/** ToolRenderContext subset available to renderCall/renderResult. */
+	interface RenderContextLike {
+		isError?: boolean;
+		isPartial?: boolean;
+		expanded?: boolean;
+		showImages?: boolean;
+	}
+
+	/** AgentToolResult subset the result renderer receives. */
+	interface RenderResultLike {
+		content?: ReadonlyArray<{ type?: string; text?: string }>;
+		details?: unknown;
+	}
+
+	type ToolRenderersLike = {
+		renderCall?: (args: unknown, theme: RenderThemeLike, context: RenderContextLike) => ComponentLike;
+		renderResult?: (
+			result: RenderResultLike,
+			options: { expanded: boolean; isPartial: boolean },
+			theme: RenderThemeLike,
+			context: RenderContextLike,
+		) => ComponentLike;
+	};
+
+	/**
+	 * pi-tui's Text (ANSI-aware word wrap), loaded lazily so an unresolvable
+	 * package can never block extension load — the crash-loop lesson from
+	 * 1.16.0. Warmed at registration time, long before the first tool row
+	 * renders.
+	 */
+	let _textCtor: (new (text: string, paddingX?: number, paddingY?: number) => ComponentLike) | undefined;
+	let _textLoadTried = false;
+
+	function preloadTextComponent(): void {
+		if (_textLoadTried) return;
+		_textLoadTried = true;
+		void import("@earendil-works/pi-tui")
+			.then((m) => {
+				const ctor = (
+					m as { Text?: new (text: string, paddingX?: number, paddingY?: number) => ComponentLike }
+				).Text;
+				if (ctor) _textCtor = ctor;
+			})
+			.catch(() => {
+				// pi-tui unreachable — the plain-lines fallback below keeps rendering
+			});
+	}
+
+	/**
+	 * Fixed-lines component used only when pi-tui's Text cannot load.
+	 * Truncates each line to the render width (ANSI-aware, rough wcwidth) —
+	 * pi's differential renderer stops on "rendered line exceeds terminal
+	 * width", so an overwide fallback line is worse than an ugly one.
+	 */
+	function plainLines(text: string): ComponentLike {
+		return {
+			render: (width: number) => text.split("\n").map((line) => truncateAnsiLine(line, Math.max(1, width))),
+			invalidate: () => {},
+		};
+	}
+
+	/** Rough wcwidth: 2 for the common wide ranges, 0 for combining marks, else 1. */
+	function codePointWidth(cp: number): number {
+		if (cp >= 0x0300 && cp <= 0x036f) return 0; // combining diacritics
+		if (
+			(cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+			(cp >= 0x2e80 && cp <= 0xa4cf) || // CJK radicals … Yi
+			(cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+			(cp >= 0xf900 && cp <= 0xfaff) || // CJK compat ideographs
+			(cp >= 0xfe30 && cp <= 0xfe4f) ||
+			(cp >= 0xff00 && cp <= 0xff60) ||
+			(cp >= 0xffe0 && cp <= 0xffe6) ||
+			(cp >= 0x1f300 && cp <= 0x1faff) || // emoji blocks
+			(cp >= 0x20000 && cp <= 0x3fffd) // CJK ext
+		) {
+			return 2;
+		}
+		return 1;
+	}
+
+	/** ANSI-preserving truncation of one styled line to a visible width. */
+	function truncateAnsiLine(line: string, width: number): string {
+		let out = "";
+		let w = 0;
+		let i = 0;
+		while (i < line.length) {
+			if (line[i] === "\x1b") {
+				const m = /^\x1b\[[0-9;]*m/.exec(line.slice(i));
+				const seq = m ? m[0] : line[i]!;
+				out += seq;
+				i += seq.length;
+				continue;
+			}
+			const cp = line.codePointAt(i)!;
+			const s = String.fromCodePoint(cp);
+			const cw = codePointWidth(cp);
+			if (w + cw > width) break;
+			out += s;
+			w += cw;
+			i += s.length;
+		}
+		return out;
+	}
+
+	function textComponent(text: string): ComponentLike {
+		return _textCtor ? new _textCtor(text, 0, 0) : plainLines(text);
+	}
+
+	function styleSegments(segments: readonly TranscriptSegment[], theme: RenderThemeLike): string {
+		let out = "";
+		for (const seg of segments) {
+			out += seg.style === "plain" ? seg.text : theme.fg(seg.style, seg.text);
+		}
+		return out;
+	}
+
+	function textBlocks(content: ReadonlyArray<{ type?: string; text?: string }> | undefined): string[] {
+		if (!content) return [];
+		const out: string[] = [];
+		for (const block of content) {
+			if (block?.type === "text" && typeof block.text === "string" && block.text) out.push(block.text);
+		}
+		return out;
+	}
+
+	function toolTitle(name: string, theme: RenderThemeLike): string {
+		return theme.fg("toolTitle", theme.bold(`${name}  `));
+	}
+
+	/** Compact result component: summary line, plus the full text content when expanded. */
+	function resultComponent(
+		summary: readonly TranscriptSegment[],
+		result: RenderResultLike,
+		options: { expanded: boolean },
+		theme: RenderThemeLike,
+	): ComponentLike {
+		let text = styleSegments(summary, theme);
+		if (options.expanded) {
+			// All text blocks: a generate_image result on a text-only base model
+			// carries the header plus per-image description fences that replaced
+			// the image blocks — the first block alone would hide them.
+			const body = textBlocks(result.content).join("\n\n");
+			if (body) {
+				// Re-apply the style per line: pi resets styling after every line.
+				text += `\n${body.split("\n").map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+			}
+		}
+		return textComponent(text);
+	}
+
+	/**
+	 * Register transcript renderers for analyze_image/generate_image (pi ≥
+	 * 1.0.1). Registered through pi.registerToolRenderer — instead of inline
+	 * renderCall/renderResult on the tool definitions — so the compact rows
+	 * also cover tools that are *not registered* at render time: calls
+	 * replayed from a session where the tool is now disabled (`tool off` /
+	 * mode off), resumed sessions rendered before extension load, and HTML
+	 * exports. `next() ?? {}` keeps renderers from later resolvers / the
+	 * registered tool for the keys we don't set. Generated images keep
+	 * rendering inline regardless: pi draws image blocks from the result
+	 * content next to the renderer output, independent of renderResult.
+	 */
+	function registerToolRenderers() {
+		const api = pi as unknown as {
+			registerToolRenderer?: (
+				resolver: (toolName: string, next: () => ToolRenderersLike | undefined) => ToolRenderersLike | undefined,
+			) => void;
+		};
+		if (typeof api.registerToolRenderer !== "function") return; // pi < 1.0.1
+		preloadTextComponent();
+		api.registerToolRenderer((toolName, next) => {
+			if (toolName === "analyze_image") {
+				return {
+					...(next() ?? {}),
+					renderCall: (args, theme) =>
+						textComponent(toolTitle("analyze_image", theme) + styleSegments(formatAnalyzeImageCall(args), theme)),
+					renderResult: (result, options, theme, context) => {
+						if (options.isPartial) return textComponent(theme.fg("warning", "Analyzing…"));
+						return resultComponent(
+							formatAnalyzeImageResult(result?.details, context?.isError === true),
+							result ?? {},
+							options,
+							theme,
+						);
+					},
+				};
+			}
+			if (toolName === "generate_image") {
+				return {
+					...(next() ?? {}),
+					renderCall: (args, theme) =>
+						textComponent(toolTitle("generate_image", theme) + styleSegments(formatGenerateImageCall(args), theme)),
+					renderResult: (result, options, theme, context) => {
+						if (options.isPartial) return textComponent(theme.fg("warning", "Generating…"));
+						return resultComponent(
+							formatGenerateImageResult(result?.details, context?.isError === true),
+							result ?? {},
+							options,
+							theme,
+						);
+					},
+				};
+			}
+			return next();
+		});
+	}
+
 	// ── Virtual model (pi ≥ 0.99) ─────────────────────────────────────────────
 
 	const VIRTUAL_PROVIDER = "multimodal-proxy";
@@ -2339,8 +2798,12 @@ export default function (pi: ExtensionAPI) {
 			// unreadable config file — session_start surfaces the error path
 		});
 
+	// Transcript renderers for analyze_image/generate_image rows (pi ≥ 1.0.1).
+	// Registered once at load; the resolver serves any later session state.
+	registerToolRenderers();
+
 	/** 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({
@@ -2398,11 +2861,93 @@ export default function (pi: ExtensionAPI) {
 						// codemode scripts. Older hosts ignore both fields.
 						...(outcome.isError ? { isError: true } : {}),
 						...(outcome.structured ? { structuredContent: outcome.structured } : {}),
+						// `details` feeds the transcript renderer (pi ≥ 1.0.1) without
+						// the model seeing it; heavy fields (text, images) are stripped.
+						...(outcome.structured ? { details: analyzeDetailsForTranscript(outcome.structured) } : {}),
 					};
 				},
 			});
 			_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 } : {}),
+						// `details` feeds the transcript renderer (pi ≥ 1.0.1); the
+						// structured payload is already display-sized (ids, dims, cost).
+						...(outcome.structured ? { details: 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.
@@ -2418,6 +2963,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();
@@ -2427,7 +2974,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);
@@ -3319,7 +3866,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;
 			}
 
@@ -3731,7 +4278,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;
 				}
@@ -4472,7 +5019,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;
 			}
 
@@ -4501,7 +5048,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.1",
+  "version": "1.21.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"