pi-vision-handoff 0.6.1 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Give text-only pi models vision — describe images with a vision model you pick via an interactive picker, then hand off the text description to non-vision models",
   "type": "module",
   "author": "Tom X Nguyen",

package/vision-handoff.ts

@@ -349,15 +349,17 @@ export default function (pi: ExtensionAPI) {
   // `tool_result` as its I/O completes (poll phase), and the loader's
   // `setImmediate` dispatch defers to the check phase AFTER the whole poll
   // iteration, so reads completing together land in ONE batch 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.
+  // together.
   //
-  // 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.
+  // Both a direct agent `read` and a NESTED `pi.read` inside fabric_exec reach
+  // this handler and take the SAME path: WARM the cache (during the free
+  // tool-result phase), strip pi's misleading non-vision note, and KEEP the
+  // image block so kitty renders it inline and /resume retains it. The
+  // `context` hook swaps image→description on the LLM-bound clone before the
+  // next turn, so the text-only agent receives the description as text. This
+  // holds for fabric too: pi-fabric re-attaches the nested read's image to the
+  // fabric_exec tool-result content, which IS the agent's message context — so
+  // the `context` hook sees and swaps it, exactly like a direct read.
   pi.on("tool_result", async (event, ctx) => {
     if (!isConfigured(config)) return;
     if (event.toolName !== "read") return;
@@ -385,19 +387,9 @@ export default function (pi: ExtensionAPI) {
     // loader's `setImmediate` dispatch defers to the check phase, AFTER the
     // whole poll iteration, so reads completing together (the common case for
     // cached local files) land in ONE batch — ONE vision call for the whole
-    // read set, not N. Reads completing in separate iterations get separate
-    // calls, but always in parallel, never sequential. 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.
+    // read set, not N. Awaiting here runs the describer during the tool-result
+    // phase (free time), so the batch is COMPLETE before `context` fires,
+    // making `context` a non-blocking cache hit instead of a cold miss.
     const descs = await Promise.all(imgs.map((img) => loader.loadDescription(img)));
 
     // On user abort, leave the result untouched — pi is tearing the turn
@@ -406,12 +398,13 @@ export default function (pi: ExtensionAPI) {
 
     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
+    // Warm the cache (done above) and 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.
+    // 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++) {