pi-vision-handoff 0.3.1 → 0.3.2

package/vision-handoff.ts

@@ -8,87 +8,73 @@
  * choice is persisted to ~/.pi/agent/extensions/pi-vision-handoff.json.
  *
  * Pipeline (provider-agnostic via @earendil-works/pi-ai's complete()):
- *   before_agent_start → warm the description cache for attached images
- *   tool_result (read) → describe read-tool images and INSERT the description
- *     as a text block before each image, keeping the image so the TUI still
- *     renders it (kitty). pi-ai later strips the image for non-vision models,
- *     leaving the description text for the model.
- *   before_provider_request → swap remaining image blocks in the payload for
- *     text (catches user-attached images for vision-capable handoff targets)
+ *   before_agent_start → warm the description cache for attached images AND
+ *     pasted clipboard image file paths found in the prompt text (pre-warm at
+ *     paste-enter, concurrent with the agent's first response).
+ *   tool_result (read) → loadDescription() each read-tool image and AWAIT the
+ *     shared batch, so N parallel reads coalesce into ONE vision call. The
+ *     descriptions land in the tool results before the agent's next turn.
+ *   context → swap any remaining image blocks for their (now cached) text
+ *     description on the cloned LLM-bound payload.
  *
- * Image blocks are detected by shape across the four formats pi uses:
- *   openai-completions: { type: "image_url",  image_url: { url: "data:..." } }
- *   openai-responses:   { type: "input_image", image_url: "data:..." }
- *   anthropic-messages: { type: "image", source: { type: "base64", media_type, data } }
- *   pi-ai internal:     { type: "image", data, mimeType }   ← read tool / ToolResultEvent
+ * This file is the wiring layer: pi event handlers + the /vision-handoff
+ * command. The dataloader (`src/dataloader.ts`), describer (`src/describer.ts`),
+ * image IO (`src/image.ts`), resource guards (`src/dispose.ts`), config/types
+ * (`src/index.ts`), and usage/energy (`src/usage.ts`) live in `src/`.
  *
- * Descriptions are cached per image hash (LRU, size = config.cacheMax) so the
- * swap is instant by the time before_provider_request fires.
+ * Image blocks are detected by shape across the four formats pi uses — see
+ * `extractImageFromBlock` in `src/index.ts`. Descriptions are cached per image
+ * hash (LRU, size = config.cacheMax) so the swap is instant by the time
+ * `context` fires.
  */
 
-import crypto from "node:crypto";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { complete } from "@earendil-works/pi-ai/compat";
-import type { Api, ImageContent, Message, Model, TextContent } from "@earendil-works/pi-ai";
+import type { Api, ImageContent, Model, TextContent } from "@earendil-works/pi-ai";
 import {
-  DEFAULT_USER_PROMPT_PREFIX,
-  DEFAULT_VISION_PROMPT,
-  DESCRIBE_TIMEOUT_MS,
-  HANDOFF_COMMAND_DESCRIPTION,
-  IMAGE_PLACEHOLDER_PREFIX,
-  IMAGE_PLACEHOLDER_SUFFIX,
-  USAGE_ENTRY_TYPE,
-  USAGE_EVENT_CHANNEL,
-  EMPTY_ENERGY_CAPTURE,
-  buildUsageRecord,
-  describeAls,
   extractImageFromBlock,
   formatModelRef,
-  insertImageDescriptions,
-  installFetchInterceptor,
   isVisionModel,
-  makeReplacementText,
+  NON_VISION_IMAGE_NOTE,
   parseModelRef,
   readConfig,
-  truncateDescription,
-  uninstallFetchInterceptor,
+  stripNonVisionImageNote,
   writeConfig,
-  type DescribeContext,
+  HANDOFF_COMMAND_DESCRIPTION,
+  type ExtractedImage,
   type VisionHandoffConfig,
-  type VisionHandoffEnergyCapture,
-  type VisionHandoffUsageRecord,
 } from "./src/index.js";
+import {
+  USAGE_ENTRY_TYPE,
+  USAGE_EVENT_CHANNEL,
+  type VisionHandoffUsageRecord,
+} from "./src/usage.js";
+import { DescriptionLoader, UNAVAILABLE, type LoaderDeps } from "./src/dataloader.js";
+import { imageHash, findClipboardImagePaths, readImageBuffer, resolvePrewarmImage } from "./src/image.js";
+import { resizeImage } from "@earendil-works/pi-coding-agent";
 import { VisionModelSelectorComponent, type VisionModelSelectorResult } from "./src/vision-model-selector.js";
 
-const UNAVAILABLE = `${IMAGE_PLACEHOLDER_PREFIX}description unavailable${IMAGE_PLACEHOLDER_SUFFIX}`;
-
-// Usage reporter; wired to pi.appendEntry + pi.events.emit in the default
-// export. No-op until then so describeImage is safe to call before wiring.
-let reportUsage: (record: VisionHandoffUsageRecord) => void = () => {};
-
 let config: VisionHandoffConfig = readConfig();
 
-/** User prompt for the current agent turn, captured from before_agent_start. */
-let pendingTurnPrompt: string | null = null;
+/** Most recent describer failure message (auth error, network error, abort,
+ *  empty response, etc.). Set by the describer via the loader deps; surfaced
+ *  to the user by the `context`/`tool_result` handler via ctx.ui.notify so a
+ *  broken vision model stops looking like a silent "extension doesn't work".
+ *  Cleared at the start of each describer attempt. */
+let lastDescriberError: string | null = null;
+
+/** Image hashes we've already warned the user about this session. Prevents the
+ *  `context` hook (which fires before every LLM turn) from re-warning on the
+ *  same failing images every turn — describer failures aren't cached, so
+ *  without this guard a broken vision model would spam a warning per turn.
+ *  Cleared on `session_start`. */
+const warnedHashes = new Set<string>();
 
-const visionCache = new Map<string, Promise<string>>();
 let visionModelCache: { ref: string; model: Model<Api> } | null = null;
 let visionModelUnresolvedRef: string | null = null;
 
-function isConfigured(cfg: VisionHandoffConfig): boolean {
-  return cfg.enabled && !!cfg.visionModel;
-}
-
-function isHandoffTarget(
-  model: { provider?: string; id?: string; input?: ("text" | "image")[] } | undefined | null,
-  cfg: VisionHandoffConfig,
-): boolean {
-  if (!model || !model.provider || !model.id) return false;
-  const ref = formatModelRef(model.provider, model.id);
-  if (cfg.handoffModels.includes(ref)) return true;
-  if (cfg.autoHandoff && !isVisionModel(model)) return true;
-  return false;
-}
+// Usage reporter; wired to pi.appendEntry + pi.events.emit in the default
+// export. No-op until then so the describer is safe to call before wiring.
+let reportUsage: (record: VisionHandoffUsageRecord) => void = () => {};
 
 function resolveVisionModel(modelRegistry: ModelRegistry, ref: string): Model<Api> | null {
   if (visionModelCache && visionModelCache.ref === ref) return visionModelCache.model;
@@ -100,140 +86,29 @@ function resolveVisionModel(modelRegistry: ModelRegistry, ref: string): Model<Ap
   return model;
 }
 
-function imageHash(mimeType: string, data: string): string {
-  return crypto.createHash("sha256").update(`${mimeType}\x00${data}`).digest("hex").slice(0, 32);
-}
-
-async function describeImage(
-  data: string,
-  mimeType: string,
-  userPrompt: string,
-  visionModel: Model<Api>,
-  modelRegistry: ModelRegistry,
-  cfg: VisionHandoffConfig,
-): Promise<string> {
-  const key = imageHash(mimeType, data);
-  const cached = visionCache.get(key);
-  if (cached) return cached;
-
-  const promise = (async (): Promise<string> => {
-    const auth = await modelRegistry.getApiKeyAndHeaders(visionModel);
-    if (!auth.ok || !auth.apiKey) return UNAVAILABLE;
-
-    const prefix = cfg.userPromptPrefix ?? DEFAULT_USER_PROMPT_PREFIX;
-    const systemPrompt = cfg.prompt ?? DEFAULT_VISION_PROMPT;
-
-    const content: (TextContent | ImageContent)[] = [];
-    if (userPrompt && userPrompt.trim()) {
-      content.push({ type: "text", text: prefix + userPrompt });
-    } else {
-      content.push({ type: "text", text: "Describe this image." } satisfies TextContent);
-    }
-    content.push({ type: "image", data, mimeType } satisfies ImageContent);
-
-    const userMessage: Message = {
-      role: "user",
-      content,
-      timestamp: Date.now(),
-    };
+const loaderDeps: LoaderDeps = {
+  getConfig: () => config,
+  resolveVisionModel,
+  reportUsage: (record) => reportUsage(record),
+  setLastError: (msg) => {
+    lastDescriberError = msg;
+  },
+};
+const loader = new DescriptionLoader(loaderDeps);
 
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DESCRIBE_TIMEOUT_MS);
-    // Energy/token capture for this describer call. The fetch interceptor is
-    // refcount-installed around the complete() window and routes the teed
-    // response body to this describe's AsyncLocalStorage slot — so concurrent
-    // describes (before_agent_start warm-up fires several in parallel) each
-    // get their own capture without clobbering globalThis.fetch. For non-
-    // Neuralwatt vision models no SSE energy comments are present and the
-    // capture stays empty (energy fields omitted from the record).
-    const describeCtx: DescribeContext = { energyReader: undefined };
-    installFetchInterceptor();
-    try {
-      const response = await describeAls.run(describeCtx, async () =>
-        complete(
-          visionModel,
-          { systemPrompt, messages: [userMessage] },
-          {
-            apiKey: auth.apiKey,
-            headers: auth.headers,
-            signal: controller.signal,
-            maxTokens: cfg.maxTokens,
-          },
-        ),
-      );
-      let capture: VisionHandoffEnergyCapture = EMPTY_ENERGY_CAPTURE;
-      if (describeCtx.energyReader) {
-        try {
-          capture = await describeCtx.energyReader;
-        } catch {
-          // tee aborted with the main stream — keep the empty capture
-        }
-      }
-      const record = buildUsageRecord(response, capture, visionModel, key);
-      if (record) reportUsage(record);
-      if (response.stopReason === "aborted" || response.stopReason === "error") {
-        return UNAVAILABLE;
-      }
-      const description = response.content
-        .filter((c): c is TextContent => c.type === "text")
-        .map((c) => c.text)
-        .join("\n")
-        .trim();
-      if (!description) return UNAVAILABLE;
-      // The full description lives in the stored tool-result content; the read
-      // tool's native collapse (ctrl+o) handles compactness — collapsed shows
-      // the image only, expanded shows the full description + image. Only apply
-      // a hard line cap when the user opts in (maxDescriptionLines > 0); by
-      // default (0) the description is unbounded so ctrl+o can expand to all
-      // of it and the model receives the complete context.
-      const { text: final } =
-        cfg.maxDescriptionLines && cfg.maxDescriptionLines > 0
-          ? truncateDescription(description, cfg.maxDescriptionLines)
-          : { text: description };
-      return `${IMAGE_PLACEHOLDER_PREFIX}${final}${IMAGE_PLACEHOLDER_SUFFIX}`;
-    } catch {
-      return UNAVAILABLE;
-    } finally {
-      if (describeCtx.energyReader) describeCtx.energyReader.catch(() => {});
-      uninstallFetchInterceptor();
-      clearTimeout(timer);
-    }
-  })();
-
-  if (visionCache.size >= cfg.cacheMax) {
-    const firstKey = visionCache.keys().next().value;
-    if (firstKey !== undefined) visionCache.delete(firstKey);
-  }
-  visionCache.set(key, promise);
-
-  return promise;
+function isConfigured(cfg: VisionHandoffConfig): boolean {
+  return cfg.enabled && !!cfg.visionModel;
 }
 
-async function replaceImagesWithDescriptions(
-  payload: Record<string, unknown>,
-  userPrompt: string,
-  visionModel: Model<Api>,
-  modelRegistry: ModelRegistry,
+function isHandoffTarget(
+  model: { provider?: string; id?: string; input?: ("text" | "image")[] } | undefined | null,
   cfg: VisionHandoffConfig,
-): Promise<boolean> {
-  const messages = payload.messages;
-  if (!Array.isArray(messages)) return false;
-
-  let replaced = false;
-  for (const msg of messages) {
-    if (!msg || typeof msg !== "object") continue;
-    const content = (msg as Record<string, unknown>).content;
-    if (!Array.isArray(content)) continue;
-
-    for (let i = 0; i < content.length; i++) {
-      const img = extractImageFromBlock(content[i]);
-      if (!img) continue;
-      const description = await describeImage(img.data, img.mimeType, userPrompt, visionModel, modelRegistry, cfg);
-      content[i] = makeReplacementText(content[i], description);
-      replaced = true;
-    }
-  }
-  return replaced;
+): boolean {
+  if (!model || !model.provider || !model.id) return false;
+  const ref = formatModelRef(model.provider, model.id);
+  if (cfg.handoffModels.includes(ref)) return true;
+  if (cfg.autoHandoff && !isVisionModel(model)) return true;
+  return false;
 }
 
 function notifyUnresolvedVisionModel(ctx: ExtensionContext, ref: string): void {
@@ -247,6 +122,29 @@ function notifyUnresolvedVisionModel(ctx: ExtensionContext, ref: string): void {
   }
 }
 
+/** Notify once per failing image per session (dedup via warnedHashes). */
+function warnFailedImages(
+  ctx: ExtensionContext,
+  imgs: ExtractedImage[],
+  descs: string[],
+  reason: string,
+): void {
+  if (!ctx.hasUI) return;
+  const newlyFailed: string[] = [];
+  for (let i = 0; i < imgs.length; i++) {
+    if (descs[i] === UNAVAILABLE) {
+      const h = imageHash(imgs[i].mimeType, imgs[i].data);
+      if (!warnedHashes.has(h)) newlyFailed.push(h);
+    }
+  }
+  if (newlyFailed.length === 0) return;
+  for (const h of newlyFailed) warnedHashes.add(h);
+  ctx.ui.notify(
+    `pi-vision-handoff: image description failed — ${reason}. Vision model: ${config.visionModel}`,
+    "warning",
+  );
+}
+
 export default function (pi: ExtensionAPI) {
   config = readConfig();
 
@@ -274,72 +172,228 @@ export default function (pi: ExtensionAPI) {
     // Reload in case the user edited the config on disk from another session.
     config = readConfig();
     visionModelCache = null;
-    pendingTurnPrompt = null;
+    visionModelUnresolvedRef = null;
+    warnedHashes.clear();
+    loader.reset();
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (!isConfigured(config)) return;
     if (!isHandoffTarget(ctx.model, config)) return;
 
-    // Capture this turn's user prompt so read-tool images are described in
-    // the same context. Fires before any tool_result for the turn.
-    pendingTurnPrompt = event.prompt || "";
-
-    const images = event.images;
-    if (!images || images.length === 0) return;
+    // Capture this turn's user prompt so every image in the turn — attached or
+    // read via the read tool — is described in the same request context.
+    loader.setPendingTurnPrompt(event.prompt || "");
+    loader.bindTurnContext(ctx);
 
-    const visionModel = resolveVisionModel(ctx.modelRegistry, config.visionModel!);
-    if (!visionModel) {
+    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }
 
-    const userPrompt = event.prompt || "";
-    for (const image of images) {
+    // PRE-WARM at paste-enter via the DataLoader. Two image sources land here:
+    //
+    // 1. Attached image blocks (event.images) — vision-capable targets where
+    //    the user message itself carries image blocks (e.g. `pi --image`).
+    //
+    // 2. Pasted clipboard image FILE PATHS in the prompt text — the common
+    //    non-vision flow. pi's `handleClipboardImagePaste` writes each pasted
+    //    image to `<tmpdir>/pi-clipboard-<uuid>.<ext>` and inserts the PATH as
+    //    text at the cursor; on a non-vision model these arrive as path tokens
+    //    in `event.prompt`, NOT as `event.images`. We scan the prompt for those
+    //    temp paths, read the files, and `loadDescription()` them so the ONE
+    //    batched vision call starts the instant you press enter — CONCURRENT
+    //    with the agent's first response generation — instead of waiting for
+    //    the agent to `read` the files. By the time the agent's `read` tool
+    //    results fire, `tool_result`'s `loadDescription()` is a cache hit.
+    //
+    // Both sources flow through the same loader: `load()` is synchronous and
+    // memoized, so all images in this frame (attached + clipboard-path)
+    // coalesce into ONE batch dispatched after the microtask cascade.
+    for (const image of event.images ?? []) {
       if (!image || image.type !== "image" || !image.data) continue;
-      const mimeType = image.mimeType || "image/png";
-      describeImage(image.data, mimeType, userPrompt, visionModel, ctx.modelRegistry, config).catch(
-        () => {},
-      );
+      loader.loadDescription({ data: image.data, mimeType: image.mimeType || "image/png" }).catch(() => {});
+    }
+
+    // Pasted clipboard image paths in the prompt text — resolve each to the
+    // SAME ExtractedImage pi's `read` tool will emit, then warm the loader so
+    // the `tool_result`'s `loadDescription()` is a cache hit (no wasted vision
+    // call). pi's read tool resizes images by default: for a small image it
+    // returns the raw bytes unchanged (our raw read matches), but for an
+    // oversized image it RE-ENCODES via Photon — so we run the same
+    // `resizeImage` pipeline to produce a matching key. The resize branch is
+    // async (worker thread) and fire-and-forget; its `loadDescription()` lands
+    // in a later batch than the no-resize images, so a mixed small+oversized
+    // paste may split into two vision calls (still no WASTED call — each
+    // describes an image the agent will see). A file that can't be read, isn't
+    // a supported image, or fails to resize is skipped (the agent's `read`
+    // will still describe it via `tool_result` if it emits an image block).
+    for (const p of findClipboardImagePaths(event.prompt || "")) {
+      const read = readImageBuffer(p);
+      if (!read) continue;
+      resolvePrewarmImage(read.buf, read.mimeType, resizeImage)
+        .then((img) => {
+          if (img) loader.loadDescription(img).catch(() => {});
+        })
+        .catch(() => {});
     }
   });
 
-  pi.on("before_provider_request", async (event, ctx) => {
+  // The PRIMARY injection point: the `read` tool's `tool_result` handler.
+  // When the agent reads image files, this fires for each read result. It
+  // calls the loader's `loadDescription(img)` for every image block and
+  // AWAITS the shared batch — so N parallel reads (pi runs `read` via
+  // Promise.all) coalesce into ONE batched vision call (DataLoader: all
+  // load() calls in the same microtask frame share one batch, dispatched
+  // after the cascade settles) and all resolve together. The descriptions
+  // replace the image blocks in the returned `content`, so by the time the
+  // agent's next turn starts the tool results already carry text — the
+  // agent never sees raw image blocks it can't process.
+  //
+  // Why block here and not in `context`: the tool-result phase is free time
+  // (the agent is just waiting for tool results), so running the describer
+  // here adds zero latency to the critical path. `context` then becomes a
+  // cache-hit no-op for read images.
+  pi.on("tool_result", async (event, ctx) => {
     if (!isConfigured(config)) return;
-    if (!isHandoffTarget(ctx.model, config)) return;
+    if (event.toolName !== "read") return;
+    const content = event.content;
+    if (!Array.isArray(content)) return;
 
-    const visionModel = resolveVisionModel(ctx.modelRegistry, config.visionModel!);
-    if (!visionModel) {
+    // Collect image blocks in this read result. (The read tool emits image
+    // blocks even for non-vision models — they reach here untouched.)
+    const imgs: ExtractedImage[] = [];
+    for (const block of content) {
+      const img = extractImageFromBlock(block);
+      if (img) imgs.push(img);
+    }
+    if (imgs.length === 0) return;
+    if (!isHandoffTarget(ctx.model, config)) return;
+    loader.bindTurnContext(ctx);
+    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }
 
-    const payload = event.payload as Record<string, unknown>;
-    await replaceImagesWithDescriptions(payload, "", visionModel, ctx.modelRegistry, config);
-    return payload;
+    // load() each image — synchronous calls that push into the current batch
+    // and return memoized promises — then await them all. Parallel reads'
+    // load() calls land in the SAME batch (same microtask frame), so this is
+    // ONE vision call for the whole read set, not N. Awaiting here runs the
+    // describer during the tool-result phase (free time — the agent is just
+    // waiting for tool results), so the batch is COMPLETE before `context`
+    // fires, making `context` a non-blocking cache hit instead of a cold miss
+    // on the critical path.
+    //
+    // We do NOT mutate the result content here for the image blocks: returning
+    // undefined keeps the image block in storage so kitty renders it inline
+    // and `/resume` retains it. The actual image→text swap happens in the
+    // `context` hook (on the cloned LLM-bound payload only), by which point
+    // these are cache hits. We DO strip pi's misleading non-vision note (below)
+    // since the handoff will replace the image with a description.
+    const descs = await Promise.all(imgs.map((img) => loader.loadDescription(img)));
+
+    // On user abort, leave the result untouched — pi is tearing the turn
+    // down and the LLM-bound content won't be sent.
+    if (ctx.signal?.aborted) return;
+
+    warnFailedImages(ctx, imgs, descs, lastDescriberError ?? "unknown error");
+
+    // Strip pi's `[Current model does not support images…]` note from text
+    // blocks — since the handoff replaces the image with a description in the
+    // `context` hook, that note is misleading (the agent WILL receive the
+    // image's content, as text). Keep the image block itself so kitty still
+    // renders it inline and `/resume` retains it; the `context` hook swaps the
+    // image for its description in the LLM-bound clone before the next turn.
+    let stripped = false;
+    const next = content.slice();
+    for (let i = 0; i < next.length; i++) {
+      const block = next[i];
+      if (block && typeof block === "object" && (block as { type: string }).type === "text") {
+        const text = (block as { text: string }).text;
+        if (typeof text === "string" && text.includes(NON_VISION_IMAGE_NOTE)) {
+          const cleaned = stripNonVisionImageNote(text);
+          if (cleaned !== text) {
+            next[i] = { type: "text", text: cleaned };
+            stripped = true;
+          }
+        }
+      }
+    }
+    if (stripped) return { content: next as (TextContent | ImageContent)[] };
   });
 
-  pi.on("tool_result", async (event, ctx) => {
+  // The FALLBACK injection point: the `context` event fires as the agent's
+  // `transformContext`, BEFORE pi-ai's `downgradeUnsupportedImages` strips
+  // image blocks and BEFORE `convertToLlm`. It catches any image blocks that
+  // didn't go through the `read` tool's `tool_result` handler — user-attached
+  // images (for vision-capable handoff targets), custom extension-injected
+  // messages, or reads that somehow bypassed the handler. `emitContext` does a
+  // `structuredClone`, so swapping here touches only the LLM-bound payload.
+  //
+  // Read images are already text by this point (the `tool_result` handler
+  // replaced them), so this is usually a no-op for the common paste-and-read
+  // flow. For the images it does find, `loadDescription()` is a cache hit
+  // (warmed by `before_agent_start`) or queues into the loader's current batch.
+  pi.on("context", async (event, ctx) => {
     if (!isConfigured(config)) return;
-    if (!isHandoffTarget(ctx.model, config)) return;
-    if (event.toolName !== "read") return;
 
-    const content = event.content;
-    if (!Array.isArray(content)) return;
-    // Skip the async work entirely when there is nothing to describe.
-    if (!content.some((c) => extractImageFromBlock(c))) return;
-
-    const visionModel = resolveVisionModel(ctx.modelRegistry, config.visionModel!);
-    if (!visionModel) {
+    const messages = event.messages as unknown as Array<Record<string, unknown>>;
+    if (!Array.isArray(messages)) return;
+
+    const byHash = new Map<string, ExtractedImage>();
+    let anyImage = false;
+    for (const msg of messages) {
+      const content = msg.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        const img = extractImageFromBlock(block);
+        if (!img) continue;
+        anyImage = true;
+        byHash.set(imageHash(img.mimeType, img.data), img);
+      }
+    }
+    if (!anyImage) return;
+    if (!isHandoffTarget(ctx.model, config)) return;
+    loader.bindTurnContext(ctx);
+    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }
 
-    const { content: next, changed } = await insertImageDescriptions(content, (img) =>
-      describeImage(img.data, img.mimeType, pendingTurnPrompt ?? "", visionModel, ctx.modelRegistry, config),
-    );
-    if (!changed) return;
-    return { content: next };
+    // Cache hits (warmed by before_agent_start / tool_result) resolve
+    // instantly; any remaining misses queue into the loader's current batch.
+    const imgs = [...byHash.values()];
+    const descArr = await Promise.all(imgs.map((img) => loader.loadDescription(img)));
+    const descs = new Map<string, string>();
+    for (let i = 0; i < imgs.length; i++) {
+      descs.set(imageHash(imgs[i].mimeType, imgs[i].data), descArr[i]);
+    }
+
+    if (ctx.signal?.aborted) return;
+
+    warnFailedImages(ctx, imgs, descArr, lastDescriberError ?? "unknown error");
+
+    let changed = false;
+    for (const msg of messages) {
+      const content = msg.content;
+      if (!Array.isArray(content)) continue;
+      let touched = false;
+      const next: unknown[] = [];
+      for (const block of content) {
+        const img = extractImageFromBlock(block);
+        if (img) {
+          next.push({ type: "text", text: descs.get(imageHash(img.mimeType, img.data)) ?? UNAVAILABLE });
+          touched = true;
+        } else {
+          next.push(block);
+        }
+      }
+      if (touched) {
+        msg.content = next;
+        changed = true;
+      }
+    }
+    if (changed) return { messages: event.messages };
   });
 
   pi.on("model_select", (event, ctx) => {
@@ -396,8 +450,9 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "  /vision-handoff help           This message",
         "",
         "Config: ~/.pi/agent/extensions/pi-vision-handoff.json",
-        "Mechanism: before_agent_start warms a description cache; before_provider_request",
-        "  swaps image blocks in the payload for the cached text description.",
+        "Mechanism: before_agent_start warms a description cache; tool_result loads",
+        "  read images through a dataloader (one batched vision call); context swaps",
+        "  image blocks in the payload for the cached text description.",
       ].join("\n"),
       "info",
     );
@@ -571,7 +626,7 @@ function showStatus(ctx: ExtensionCommandContext): void {
   lines.push(`Vision model: ${config.visionModel ?? "(none — pick one with /vision-handoff)"}`);
   lines.push(`Auto handoff (non-vision models): ${config.autoHandoff ? "on" : "off"}`);
   lines.push(`Handoff targets (explicit): ${config.handoffModels.length ? config.handoffModels.join(", ") : "(none)"}`);
-  lines.push(`maxTokens: ${config.maxTokens} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);
+  lines.push(`maxTokens: ${config.maxTokens ?? "unbounded"} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);
 
   const model = ctx.model;
   let active = false;