pi-vision-handoff 0.4.1 → 0.4.2

package/README.md

@@ -39,7 +39,7 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 - **🎮 Interactive picker** — `/vision-handoff` opens a TUI listing every model, vision-capable ones first (👁), to choose your describer.
 - **🖼️ DataLoader-batched descriptions** — the `read` tools are `load()` callers: N parallel reads coalesce into ONE batched vision call (dispatched via `setImmediate` after the poll phase, so reads completing together batch instead of splitting), awaited during the tool-result phase (free time) so the agent's next turn never blocks on the describer. Descriptions are ready before `context` fires, so the swap is a non-blocking cache hit.
 - **🧹 Hides pi's "model does not support images" note** — on read results the extension strips pi's `[Current model does not support images…]` note from the text block (it's misleading once the handoff delivers the image's content as text), while keeping the image block for kitty inline rendering and `/resume`.
-- **🔌 Provider-agnostic** — uses pi's own model execution machinery (`@earendil-works/pi-ai`'s `complete()`), so it works with any provider/configured model, including custom provider extensions.
+- **🔌 Provider-agnostic** — uses pi's own model execution machinery (`@earendil-works/pi-ai`'s `completeSimple()`), so it works with any provider/configured model, including custom provider extensions.
 - **🧠 Automatic targets** — by default, handoff applies to *every* model that lacks native vision. Opt out with `/vision-handoff auto off`.
 - **🗂️ Explicit overrides** — force handoff for specific models (e.g. a weak vision model) with `/vision-handoff add`.
 - **⚡ Pre-warmed at paste-enter** — the moment you press enter, `before_agent_start` scans the prompt for pasted clipboard image temp-file paths (pi writes pasted images to `<tmpdir>/pi-clipboard-<uuid>.<ext>` and inserts the path as text), reads them, and kicks off the ONE batched vision call concurrent with the agent's first response — so by the time the agent reads the files, they're already cache hits.
@@ -164,7 +164,7 @@ phase (so reads completing together batch instead of splitting into N calls).
           tool_result handler calls `loadDescription(img)` for its image
           blocks and AWAITS the shared batch
         • DataLoader: all `load()` calls in one event-loop poll iteration
-          land in ONE batch → ONE `complete()` vision call for the whole read
+          land in ONE batch → ONE `completeSimple()` vision call for the whole read
           set. `enqueuePostPromiseJob` schedules dispatch via `setImmediate`
           (the check phase, which runs AFTER the whole poll phase — not
           `process.nextTick`, which would drain between the reads' I/O
@@ -210,7 +210,7 @@ sends every uncached image in a single user message with per-image
 per-image descriptions (keyed by `sha256(mime + base64)` in the per-image
 cache). If the vision model ignores the delimiter format and the batched
 response can't be split, each unparsed image falls back to its own
-single-image `complete()` call **in parallel** (no delimiters to cooperate
+single-image `completeSimple()` call **in parallel** (no delimiters to cooperate
 with) — descriptions still arrive together. Only when a per-image call
 itself genuinely fails (auth, timeout, empty) does that image degrade to
 `[Image: description unavailable]`; one bad image never voids the rest.
@@ -268,7 +268,7 @@ off mid-stream); earlier sections had `<<<END>>>` delimiters and are complete.
 it before the LLM call), so a slow describer would also make aborting a turn
 slow — pi has to wait for the transform to return. The hook therefore wires
 the turn's abort signal (`ctx.signal`, the active run's `AbortController`)
-into the describer's `complete()` call, so a user cancel kills the in-flight
+into the describer's `completeSimple()` call, so a user cancel kills the in-flight
 vision request immediately. A deliberate abort is not warned about (it's
 not a vision-model failure) and the LLM-bound payload is left untouched since
 the turn is being torn down anyway.
@@ -282,7 +282,7 @@ the turn is being torn down anyway.
 | `context` (all messages) | `{ type: "input_image", image_url: "data:…" }` (OpenAI Responses) | detected by shape → replaced with `{ type: "input_text", text }` |
 | `context` (all messages) | `{ type: "image", source: { type: "base64", media_type, data } }` (Anthropic Messages) | detected by shape → replaced with `{ type: "text", text }` |
 
-The describer call itself goes through pi's normal model machinery (`complete()`),
+The describer call itself goes through pi's normal model machinery (`completeSimple()`),
 **not** the agent event loop — so it never re-triggers `context` (no recursion).
 The `read` tool result keeps its image block untouched (kitty inline + `/resume`);
 only the `context`-cloned LLM-bound payload has images swapped for text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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/src/describer.ts

@@ -1,6 +1,14 @@
 /**
- * The vision describer: calls a vision-capable model via pi-ai's `complete()`
- * to produce text descriptions of images.
+ * The vision describer: calls a vision-capable model via pi-ai's
+ * `completeSimple()` to produce text descriptions of images.
+ *
+ * `completeSimple` (not `complete`) is the path that translates the `reasoning`
+ * ThinkingLevel into each provider's `reasoningEffort`/budget. `complete()` →
+ * `stream()` reads only the pre-translated `reasoningEffort` field and silently
+ * drops a bare `reasoning`, so the describer's thinking setting would be a no-op
+ * through `complete()` — the bug this swap fixes. The agent loop, SDK, and
+ * compaction all route thinking through `completeSimple`/`streamSimple` for the
+ * same reason.
  *
  * Two entry points:
  *   - {@link runBatch}: ONE batched call describing N images at once (the
@@ -13,13 +21,13 @@
  * Resource lifetimes (fetch interceptor, timeout timer, turn-abort wire) are
  * managed with the `using` keyword via the {@link Disposable} guards in
  * `dispose.ts`, replacing the manual `try`/`finally` cleanup the old code
- * carried. Disposing is lexical and exception-safe: a thrown `complete()`
+ * carried. Disposing is lexical and exception-safe: a thrown `completeSimple()`
  * still tears down the timer, uninstalls the interceptor, and detaches the
  * abort listener.
  */
 
 import type { Api, ImageContent, Message, Model, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
-import { complete } from "@earendil-works/pi-ai/compat";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import {
   batchUserPrompt,
@@ -52,7 +60,7 @@ import { abortWireGuard, fetchInterceptorGuard, timeoutGuard, type AbortWire } f
  *  model (e.g. 262144 context − 8192 reserve = 253952 output budget). */
 const INPUT_RESERVE_TOKENS = 8192;
 
-/** Resolve the `maxTokens` to pass to `complete()` for a describer call.
+/** Resolve the `maxTokens` to pass to `completeSimple()` for a describer call.
  *
  *  - A configured `cfg.maxTokens` wins (explicit cost/latency cap), clamped to
  *    fit the context window.
@@ -76,7 +84,7 @@ export function resolveMaxTokens(
   return Math.max(1, Math.min(requested, cap));
 }
 
-/** Resolve the `reasoning` (thinking) level to pass to `complete()`, or
+/** Resolve the `reasoning` (thinking) level to pass to `completeSimple()`, or
  *  `undefined` to leave thinking off.
  *
  *  - Returns `undefined` when thinking is disabled in config.
@@ -108,7 +116,7 @@ export interface DescriberDeps {
 /** The result of a batched describer call: per-image raw descriptions keyed by hash. */
 export type BatchResult = Map<string, string>;
 
-/** Describe N images with ONE batched `complete()` call and split the response
+/** Describe N images with ONE batched `completeSimple()` call and split the response
  *  back into per-image descriptions. Returns a map keyed by image hash; an
  *  image whose section failed to parse is omitted (the caller treats omission
  *  as "description unavailable"). On a genuine call failure (auth, abort,
@@ -159,7 +167,7 @@ export async function runBatch(
   const describeCtx: DescribeContext = { energyReader: undefined };
   try {
     const response = await describeAls.run(describeCtx, async () =>
-      complete(
+      completeSimple(
         visionModel,
         { systemPrompt, messages: [userMessage] },
         { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens, reasoning },
@@ -231,7 +239,7 @@ export async function runBatch(
   }
 }
 
-/** Describe a single image with one `complete()` call and return the RAW
+/** Describe a single image with one `completeSimple()` call and return the RAW
  *  description (no envelope, no truncation). Returns null on any genuine
  *  failure (auth, abort/error, empty) so the caller only caches `UNAVAILABLE`
  *  when a real describer attempt failed. */
@@ -273,7 +281,7 @@ export async function describeSingle(
   const describeCtx: DescribeContext = { energyReader: undefined };
   try {
     const response = await describeAls.run(describeCtx, async () =>
-      complete(
+      completeSimple(
         visionModel,
         { systemPrompt, messages: [userMessage] },
         { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens, reasoning },

package/src/index.ts

@@ -38,7 +38,7 @@ export const DEFAULT_USER_PROMPT_PREFIX = "The user's request about this image:
 export const IMAGE_PLACEHOLDER_PREFIX = "[Image: ";
 export const IMAGE_PLACEHOLDER_SUFFIX = "]";
 
-/** Marker appended to a description whose `complete()` call ended with
+/** Marker appended to a description whose `completeSimple()` call ended with
  *  `stopReason: "length"` — i.e. the vision model hit a token limit (either the
  *  configured `maxTokens` or the provider's hard output cap) before finishing.
  *  A truncated description is still useful, but the agent must not mistake it

package/src/usage.ts

@@ -3,7 +3,7 @@
  *
  * One record is produced per REAL describer provider call (cache hits emit
  * nothing):
- *   - model + tokens: from complete()'s AssistantMessage.usage
+ *   - model + tokens: from completeSimple()'s AssistantMessage.usage
  *   - energy + cost + raw MCR/energy/cost payloads: from Neuralwatt SSE comment
  *     lines parsed out of the teed response body (readEnergyFromTee). Present
  *     ONLY when the vision model is a Neuralwatt model — non-Neuralwatt models
@@ -197,7 +197,7 @@ export function buildUsageRecord(
 
 // ── Concurrency-safe fetch interceptor ─────────────────────────────────────
 //
-// The only body-interception point for complete() is globalThis.fetch (pi-ai's
+// The only body-interception point for completeSimple() is globalThis.fetch (pi-ai's
 // StreamOptions.onResponse exposes headers only, not the body where the
 // `: energy` SSE comments live). before_agent_start fires several describeImage()
 // calls fire-and-forget, so a naïve save/patch/restore of globalThis.fetch would