pi-vision-handoff 0.4.3 → 0.5.1

package/README.md

@@ -43,6 +43,7 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 - **🧠 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.
+- **🚀 Paste-time prewarm (opt-in)** — `prewarmPastedImages` (off by default) wraps the editor so pasted clipboard images are described the *instant* their path lands in the prompt — before you hit enter — not at submit. The vision call starts concurrent with you typing your question. Tradeoff: the description is generated without your typed question as context (the question usually isn't entered yet at paste time), and a paste-then-abandon wastes one vision call. TUI only; inactive if another extension replaces the editor. Toggle with `/vision-handoff prewarm on`.
 - **🛡️ Graceful degradation** — no API key? Describer unreachable? Aborted? The image is replaced with a clean `[Image: description unavailable]` placeholder instead of crashing your turn.
 - **📊 Usage reporting** — every real describer call reports model + tokens (and Neuralwatt energy/cost when the vision model is a Neuralwatt model), via `pi.appendEntry` + a `vision-handoff:usage` event for live consumers.
 - **🔧 Tunable** — cap description length (`maxDescriptionLines`; unbounded by default, so `read`'s native `ctrl+o` collapse handles compactness) and cache size, in the config file.
@@ -59,6 +60,7 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 | `/vision-handoff status` | Show current config + whether handoff is active for the current model |
 | `/vision-handoff enable` / `disable` | Master switch (keeps your configured model) |
 | `/vision-handoff auto on` / `off` | Toggle automatic handoff for all non-vision models |
+| `/vision-handoff prewarm on` / `off` | Toggle paste-time prewarm (opt-in, off by default) |
 | `/vision-handoff add ollama/llava:13b` | Force handoff for an extra model |
 | `/vision-handoff remove ollama/llava:13b` | Stop forcing handoff for a model |
 | `/vision-handoff clear` | Clear the configured vision model |
@@ -74,6 +76,7 @@ Created automatically at `~/.pi/agent/extensions/pi-vision-handoff.json` on firs
   "visionModel": "openai/gpt-4o",
   "autoHandoff": true,
   "handoffModels": ["ollama/llava:13b"],
+  "prewarmPastedImages": false,
   "maxTokens": null,
   "cacheMax": 50,
   "maxDescriptionLines": 0,
@@ -88,6 +91,7 @@ Created automatically at `~/.pi/agent/extensions/pi-vision-handoff.json` on firs
 | `visionModel` | `null` | The describer, as `provider/id`. `null` = not configured (handoff inactive). |
 | `autoHandoff` | `true` | Apply handoff to every model whose `input` does not include `image`. |
 | `handoffModels` | `[]` | Extra `provider/id` refs that should also receive handoff. |
+| `prewarmPastedImages` | `false` | **Opt-in paste-time prewarm.** When `true`, a custom editor wrapper describes pasted clipboard images the instant their temp-file path lands in the prompt (pre-submit), instead of at submit. Trades a bit of description quality (the description is generated without your typed question as context, since the question usually isn't entered yet at paste time) and a speculative vision call on paste-then-abandon, for earlier prewarm. TUI mode only; inactive if another extension has replaced the editor. |
 | `maxTokens` | _(unset = model max, clamped to context window)_ | Cap on a single description's output. `null`/unset = use the vision model's declared max output (`model.maxTokens`), clamped so `maxTokens + 8192 <= contextWindow` (a model whose declared max equals its full context window would otherwise be rejected with a 400). Set a number only to cap cost/latency. A truncation is always surfaced via a `[... description truncated …]` marker when the model hits the limit, so a cut-off description is never mistaken for complete. |
 | `cacheMax` | `50` | Max described images kept in the in-memory cache per session. |
 | `maxDescriptionLines` | `0` | Cap on description lines (`0` = unbounded). Default keeps the full description so the `read` tool's native collapse (`ctrl+o`) handles compactness and the model gets complete context; setting `> 0` applies a lossy head-cap to both the TUI render and the model. |
@@ -142,6 +146,26 @@ memoizes promises; all `load()` calls in the same execution frame coalesce
 into ONE batched vision call, dispatched via `setImmediate` after the poll
 phase (so reads completing together batch instead of splitting into N calls).
 
+With `prewarmPastedImages` on (opt-in), an even earlier stage runs:
+
+    → editor onChange (paste-time, pre-submit)
+        • pi has no "image pasted" event; the earliest signal is the editor's
+          `onChange(text)`, which fires when pi's `handleClipboardImagePaste`
+          inserts the temp-file path via `insertTextAtCursor`
+        • a wrapping CustomEditor chains `onChange` (pi assigns its own
+          `onChange` — for bash-mode border tracking — after construction, so
+          the wrapper captures it via an accessor and runs it alongside an
+          observer that `diffPrewarmPaths`s new `pi-clipboard-*` paths and
+          `loadDescription()`s them at paste-time — the vision call starts
+          before you hit enter; `before_agent_start`'s same-path prewarm is
+          then a cache hit
+        • it does NOT override `handleInput`, so keybindings + `ctrl+v` paste
+          are untouched; TUI only, and skipped when another extension has
+          replaced the editor (installing over one would break paste, since
+          pi wires paste-image to the outermost editor only)
+
+The default submit-time pipeline below runs regardless:
+
     → before_agent_start
         • captures this turn's user prompt (shared by every image description)
         • binds turn context (vision model + abort signal) to the loader
@@ -346,6 +370,7 @@ pnpm lint:dead     # Dead code detection (knip)
 │   ├── dataloader.ts              # DescriptionLoader — DataLoader-batched descriptions (Disposable)
 │   ├── describer.ts              # Vision describer calls (runBatch / describeSingle) with `using` resource guards
 │   ├── image.ts                  # Image hashing, MIME sniffing, clipboard-path reading
+│   ├── prewarm-editor.ts        # Opt-in paste-time prewarm CustomEditor wrapper (chains onChange)
 │   ├── dispose.ts                 # `Disposable` guard factories for `using` (fetch interceptor, timer, abort wire)
 │   ├── usage.ts                  # Describer usage + Neuralwatt energy capture, fetch interceptor
 │   └── vision-model-selector.ts  # Interactive picker TUI component
@@ -355,7 +380,7 @@ pnpm lint:dead     # Dead code detection (knip)
 │   ├── vision-handoff.test.ts    # Config, refs, image-block extraction, insertion, truncation, round-trip
 │   ├── dataloader.test.ts        # Batch coalescing, memoization, failure eviction, Disposable reset
 │   ├── describer.test.ts        # stopReason handling (length → truncation marker, aborted/error)
-│   ├── image.test.ts             # MIME sniffing, clipboard-path confinement, file reading
+│   ├── image.test.ts             # MIME sniffing, clipboard-path confinement, file reading, diffPrewarmPaths
 │   └── dispose.test.ts           # `using` guards: fetch refcount, timeout, abort-wire propagation
 ├── package.json
 ├── tsconfig.json

package/package.json

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

@@ -91,19 +91,68 @@ export class DescriptionLoader implements Disposable {
   private dispatchScheduled = false;
   private turnModelRegistry: ModelRegistry | null = null;
   private turnVisionModel: Model<Api> | null = null;
-  private turnSignal: AbortSignal | undefined;
+  /** Turn-level abort controller. In-flight describer batches (`runBatch`)
+   *  are wired to `turnAbortController.signal` so a user cancel (ESC) aborts
+   *  them EVEN WHEN the batch was dispatched before the run's live abort
+   *  signal existed — the `before_agent_start` / paste-time prewarm case,
+   *  where `ctx.signal` is `undefined` (the agent run hasn't started yet).
+   *  The run's live signal, once it arrives via `bindTurnContext`, is forwarded
+   *  into `turnAbortController.abort()`. Because `runBatch` holds a reference
+   *  to this controller's signal (not a snapshot of `ctx.signal`), a batch
+   *  that started during prewarm becomes abortable the instant a later
+   *  `bindTurnContext` (from `tool_result`/`context`) brings the live signal.
+   *  Reset per turn via {@link resetTurnAbort} so a previous turn's cancel
+   *  can't poison the next turn's prewarm. */
+  private turnAbortController = new AbortController();
+  /** The run signal currently forwarded into {@link turnAbortController}, so
+   *  the abort listener is attached at most once per signal (the same signal
+   *  is bound by every `tool_result`/`context` event in a turn). */
+  private wiredSignal: AbortSignal | undefined;
   private pendingTurnPrompt = "";
 
   constructor(private readonly deps: LoaderDeps) {}
 
-  /** Bind the turn context (model registry, resolved vision model, abort signal)
-   *  for the loader's next dispatch. Called from every handler that may trigger
-   *  `loadDescription()`. */
+  /** Bind the turn context (model registry, resolved vision model, abort
+   *  signal) for the loader's next dispatch. Called from every handler that
+   *  may trigger `loadDescription()`.
+   *
+   *  The abort signal is forwarded into the loader's {@link turnAbortController}
+   *  rather than stored directly. Storing `ctx.signal` directly would leave a
+   *  prewarm-dispatched batch (started in `before_agent_start`, where
+   *  `ctx.signal` is `undefined` because the run hasn't started) with no abort
+   *  wire — ESC couldn't cancel it, so the `tool_result` handler would only
+   *  discard the result AFTER the vision call ran to completion. Forwarding
+   *  the live signal into a stable, loader-owned controller lets an in-flight
+   *  prewarm batch be aborted the moment the live signal arrives. */
   bindTurnContext(ctx: { modelRegistry: ModelRegistry; signal?: AbortSignal }): void {
     this.turnModelRegistry = ctx.modelRegistry;
-    this.turnSignal = ctx.signal;
     const resolved = this.deps.resolveVisionModel(ctx.modelRegistry, this.deps.getConfig().visionModel!);
     if (resolved) this.turnVisionModel = resolved;
+    const signal = ctx.signal;
+    if (!signal) return;
+    if (signal.aborted) {
+      this.turnAbortController.abort();
+      this.wiredSignal = signal;
+      return;
+    }
+    if (signal === this.wiredSignal) return; // already forwarded this signal
+    this.wiredSignal = signal;
+    signal.addEventListener("abort", () => this.turnAbortController.abort(), { once: true });
+  }
+
+  /** Reset the turn-level abort controller for a fresh turn. Call at turn
+   *  boundaries (`before_agent_start`, paste-time prewarm) so a previous turn's
+   *  cancel doesn't leave {@link turnAbortController} aborted — which would
+   *  make every subsequent dispatch short-circuit to UNAVAILABLE. A
+   *  non-aborted controller is reused (avoids orphaning an in-flight paste
+   *  prewarm holding its signal); only an aborted one is replaced. `wiredSignal`
+   *  is always cleared so the next live signal re-wires. Safe at a real turn
+   *  boundary, where the prior turn's batch has settled. */
+  resetTurnAbort(): void {
+    if (this.turnAbortController.signal.aborted) {
+      this.turnAbortController = new AbortController();
+    }
+    this.wiredSignal = undefined;
   }
 
   /** Capture this turn's user prompt so every image in the turn is described in
@@ -160,7 +209,9 @@ export class DescriptionLoader implements Disposable {
     this.dispatchScheduled = false;
     this.turnModelRegistry = null;
     this.turnVisionModel = null;
-    this.turnSignal = undefined;
+    // Fresh controller on session reset (no in-flight batch to orphan).
+    this.turnAbortController = new AbortController();
+    this.wiredSignal = undefined;
     this.pendingTurnPrompt = "";
   }
 
@@ -194,7 +245,7 @@ export class DescriptionLoader implements Disposable {
       for (const cb of batch.callbacks) cb.resolve(UNAVAILABLE);
       return;
     }
-    if (this.turnSignal?.aborted) {
+    if (this.turnAbortController.signal.aborted) {
       for (const key of batch.keys) this.cache.delete(key);
       for (const cb of batch.callbacks) cb.resolve(UNAVAILABLE);
       return;
@@ -209,7 +260,7 @@ export class DescriptionLoader implements Disposable {
       this.turnModelRegistry,
       cfg,
       this.deps,
-      this.turnSignal,
+      this.turnAbortController.signal,
     );
     // Build per-hash results, then fan them out to every callback. This reaches
     // duplicate-hash callbacks that a key-indexed loop would have skipped (and

package/src/image.ts

@@ -272,3 +272,20 @@ export function findClipboardImagePaths(prompt: string): string[] {
   }
   return [...paths];
 }
+
+/** Diff the clipboard image paths in `text` against `known`, returning those
+ *  that are newly appeared (not yet seen). Used by the paste-time prewarm
+ *  editor to prewarm only newly-pasted paths on each text change, without
+ *  re-reading already-seen ones. `findClipboardImagePaths` already dedups
+ *  within a single text, so each returned path is unique and seen at most
+ *  once. Returns [] when `text` holds no clipboard paths (e.g. ordinary
+ *  typing) — so the editor's per-keystroke cost when the opt-in is on is one
+ *  regex scan that almost always yields nothing. */
+export function diffPrewarmPaths(text: string, known: Set<string>): string[] {
+  const paths = findClipboardImagePaths(text);
+  const newPaths: string[] = [];
+  for (const p of paths) {
+    if (!known.has(p)) newPaths.push(p);
+  }
+  return newPaths;
+}

package/src/index.ts

@@ -136,6 +136,18 @@ export interface VisionHandoffConfig {
   autoHandoff: boolean;
   /** Extra "provider/id" refs that should ALSO receive handoff (e.g. weak vision models). */
   handoffModels: string[];
+  /** Opt-in: when true, the editor is wrapped at session start to describe
+   *  pasted clipboard images the instant their temp-file path lands in the
+   *  prompt (pre-submit), instead of waiting for submit. Trades a bit of
+   *  description quality (the description is generated without the user's
+   *  typed question as context, since the question usually isn't entered yet
+   *  at paste time) and a speculative vision call on paste-then-abandon, for
+   *  earlier prewarm. Off by default — submit-time prewarm
+   *  (before_agent_start) still covers this case when off. TUI mode only, and
+   *  inactive when another extension has replaced the editor (installing over
+   *  a custom editor would break clipboard paste, since pi wires paste-image
+   *  to the outermost editor only). */
+  prewarmPastedImages: boolean;
   /** Max output tokens for a single description. `undefined` (default) = use the
    *  vision model's declared max output (`model.maxTokens`) as the cap — the
    *  highest the model supports — so the "be exhaustive" prompt isn't defeated
@@ -172,6 +184,7 @@ export const DEFAULT_CONFIG: VisionHandoffConfig = {
   visionModel: null,
   autoHandoff: true,
   handoffModels: [],
+  prewarmPastedImages: false,
   maxTokens: undefined,
   cacheMax: DEFAULT_CACHE_MAX,
   maxDescriptionLines: DEFAULT_MAX_DESCRIPTION_LINES,
@@ -221,6 +234,7 @@ export function normalizeConfig(raw: unknown): VisionHandoffConfig {
       .map((m) => m.trim())
       .filter((m) => m && parseModelRef(m));
   }
+  if (typeof obj.prewarmPastedImages === "boolean") base.prewarmPastedImages = obj.prewarmPastedImages;
   // maxTokens: optional. undefined (default) = no artificial cap. Only set when
   // a valid positive finite number is given; any other value leaves it unset.
   if (typeof obj.maxTokens === "number" && Number.isFinite(obj.maxTokens) && obj.maxTokens > 0) {

package/src/prewarm-editor.ts

@@ -0,0 +1,95 @@
+/**
+ * Paste-time prewarm editor wrapper.
+ *
+ * pi has no "image pasted into the prompt" event — the extension event bus
+ * only surfaces input at submit time (`input` / `before_agent_start`). The
+ * earliest observable signal that a clipboard image has landed in the prompt
+ * is the editor's own `onChange(text)`, which fires when pi's
+ * `handleClipboardImagePaste` inserts the temp-file path
+ * (`<tmpdir>/pi-clipboard-<uuid>.<ext>`) via `insertTextAtCursor` — still
+ * pre-submit. This wrapper installs a `CustomEditor` that observes `onChange`
+ * to prewarm the describer for newly-pasted clipboard image paths the instant
+ * they appear, so the vision call starts before the user hits enter (true
+ * paste-time) instead of at `before_agent_start` (submit-time).
+ *
+ * It does NOT override `handleInput`, so every keybinding and pi's clipboard
+ * paste flow (`ctrl+v` → `onPasteImage` → `handleClipboardImagePaste`) is
+ * untouched. We only observe the result via `onChange`.
+ *
+ * Why chain `onChange` via an accessor: pi's `setCustomEditorComponent` does
+ * `newEditor.onChange = this.defaultEditor.onChange` after construction,
+ * clobbering any `onChange` set in the constructor — and that default
+ * `onChange` tracks bash-mode for the editor border, so it must keep running.
+ * The accessor captures pi's assignment and runs it alongside our observer.
+ * (The `Editor` base never reassigns `onChange` itself, so the captured
+ * reference is stable for the editor's lifetime.)
+ *
+ * Opt-in via `VisionHandoffConfig.prewarmPastedImages`. When off (or the
+ * active model isn't a handoff target), the observer short-circuits before
+ * the path regex runs, so overhead is one boolean check per text change.
+ */
+
+import { CustomEditor, type KeybindingsManager, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { EditorTheme, TUI } from "@earendil-works/pi-tui";
+import { diffPrewarmPaths } from "./image.js";
+
+/** Dependencies the editor can't own itself (held by the engine, captured at
+ *  session start). `modelRegistry` is fixed for the editor's (session)
+ *  lifetime; `shouldPrewarm` and `prewarmPath` read live config/model state so
+ *  toggling the opt-in or switching models takes effect without reinstalling. */
+export interface PrewarmEditorDeps {
+  modelRegistry: ModelRegistry;
+  /** Live gate: paste-time prewarm runs only when this returns true. */
+  shouldPrewarm: () => boolean;
+  /** Prewarm one clipboard image path (read + resize-match + loadDescription). */
+  prewarmPath: (path: string, modelRegistry: ModelRegistry) => void;
+}
+
+/** A `CustomEditor` that observes `onChange` to prewarm pasted clipboard image
+ *  paths at paste-time. See the module doc for the `onChange` chaining. */
+export class PrewarmEditor extends CustomEditor {
+  private readonly knownPaths = new Set<string>();
+  private piOnChange: ((text: string) => void) | undefined;
+  private readonly shouldPrewarm: () => boolean;
+  private readonly prewarmPath: (path: string, modelRegistry: ModelRegistry) => void;
+  private readonly modelRegistry: ModelRegistry;
+
+  constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, deps: PrewarmEditorDeps) {
+    super(tui, theme, keybindings);
+    this.shouldPrewarm = deps.shouldPrewarm;
+    this.prewarmPath = deps.prewarmPath;
+    this.modelRegistry = deps.modelRegistry;
+
+    // Stable wrapper: calls pi's onChange (bash-mode border tracking) then our
+    // observer. Returned on every read so the Editor's `this.onChange(...)` calls
+    // all hit the same function.
+    const wrapper = (text: string): void => {
+      this.piOnChange?.(text);
+      this.handleTextChange(text);
+    };
+    // pi assigns defaultEditor.onChange to this property after construction;
+    // capture it via the setter, expose the wrapper via the getter.
+    Object.defineProperty(this, "onChange", {
+      configurable: true,
+      enumerable: true,
+      get: () => wrapper,
+      set: (fn: ((text: string) => void) | undefined) => {
+        this.piOnChange = fn;
+      },
+    });
+  }
+
+  /** Scan the editor text for clipboard image paths not yet seen this prompt
+   *  and prewarm each. Clears the known set when the editor empties (after
+   *  submit) so a later paste (fresh uuid) re-prewarms and the set can't grow
+   *  unbounded. */
+  private handleTextChange(text: string): void {
+    if (!this.shouldPrewarm()) return;
+    const newPaths = diffPrewarmPaths(text, this.knownPaths);
+    for (const p of newPaths) {
+      this.knownPaths.add(p);
+      this.prewarmPath(p, this.modelRegistry);
+    }
+    if (text.length === 0) this.knownPaths.clear();
+  }
+}

package/vision-handoff.ts

@@ -53,6 +53,7 @@ import { DescriptionLoader, UNAVAILABLE, type LoaderDeps } from "./src/dataloade
 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";
+import { PrewarmEditor } from "./src/prewarm-editor.js";
 
 let config: VisionHandoffConfig = readConfig();
 
@@ -70,6 +71,15 @@ let lastDescriberError: string | null = null;
  *  Cleared on `session_start`. */
 const warnedHashes = new Set<string>();
 
+/** Current model, tracked so the paste-time prewarm gate can skip prewarming
+ *  when the active model is vision-capable (handoff won't run → a prewarm
+ *  would be a wasted vision call). Updated in session_start and model_select. */
+let currentModel: Model<Api> | undefined | null;
+
+/** Whether the paste-time prewarm editor is installed this session. False in
+ *  non-TUI modes or when another extension already replaced the editor. */
+let editorInstalled = false;
+
 let visionModelCache: { ref: string; model: Model<Api> } | null = null;
 let visionModelUnresolvedRef: string | null = null;
 
@@ -112,6 +122,67 @@ function isHandoffTarget(
   return false;
 }
 
+/** Whether paste-time prewarm should fire for a text change right now: the
+ *  opt-in flag is on, handoff is configured, and the active model is a handoff
+ *  target (so the prewarmed description will actually be consumed — a
+ *  vision-capable model needs no handoff, so prewarming would waste a call). */
+function shouldPrewarmPaste(): boolean {
+  return config.prewarmPastedImages && isConfigured(config) && isHandoffTarget(currentModel, config);
+}
+
+/** Prewarm one pasted clipboard image path through the dataloader at paste
+ *  time. Mirrors the before_agent_start clipboard prewarm, but binds only the
+ *  model registry (no turn signal — the agent is idle at paste time) and
+ *  resets the turn prompt to "" so a stale previous-turn prompt can't leak
+ *  into the description. The user's question isn't typed yet at paste time, so
+ *  the description is generated without question context (the documented
+ *  tradeoff of the opt-in). If the user submits before this dispatch fires,
+ *  before_agent_start overwrites the prompt — a benign bonus, not a bug. */
+function prewarmClipboardPath(path: string, modelRegistry: ModelRegistry): void {
+  const read = readImageBuffer(path);
+  if (!read) return;
+  resolvePrewarmImage(read.buf, read.mimeType, resizeImage)
+    .then((img) => {
+      if (!img) return;
+      // Paste happens while the agent is idle (no run → no live signal).
+      // Reset the turn-abort controller so a previous turn's ESC doesn't leave
+      // it aborted and short-circuit this prewarm; the next submit's
+      // `before_agent_start` resets again. The prewarm batch uses the loader's
+      // controller and becomes abortable once a run starts and binds a live
+      // signal.
+      loader.resetTurnAbort();
+      loader.setPendingTurnPrompt("");
+      loader.bindTurnContext({ modelRegistry });
+      loader.loadDescription(img).catch(() => {});
+    })
+    .catch(() => {});
+}
+
+/** Install the paste-time prewarm editor wrapper for this session. TUI only,
+ *  and only when no other extension has replaced the editor — installing over
+ *  a custom editor would clobber its input handling and break clipboard paste
+ *  (pi wires paste-image to the outermost editor only). When a custom editor
+ *  is present, paste-time prewarm is unavailable; submit-time prewarm
+ *  (before_agent_start) still covers clipboard paths. */
+function installPrewarmEditor(ctx: ExtensionContext): void {
+  if (ctx.mode !== "tui") {
+    editorInstalled = false;
+    return;
+  }
+  if (ctx.ui.getEditorComponent()) {
+    editorInstalled = false;
+    return;
+  }
+  editorInstalled = true;
+  ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
+    new PrewarmEditor(_tui, theme, keybindings, {
+      modelRegistry: ctx.modelRegistry,
+      shouldPrewarm: shouldPrewarmPaste,
+      prewarmPath: prewarmClipboardPath,
+    }),
+  );
+}
+
 function notifyUnresolvedVisionModel(ctx: ExtensionContext, ref: string): void {
   if (visionModelUnresolvedRef === ref) return;
   visionModelUnresolvedRef = ref;
@@ -169,19 +240,33 @@ export default function (pi: ExtensionAPI) {
     }
   };
 
-  pi.on("session_start", async () => {
+  pi.on("session_start", async (_event, ctx) => {
     // Reload in case the user edited the config on disk from another session.
     config = readConfig();
     visionModelCache = null;
     visionModelUnresolvedRef = null;
     warnedHashes.clear();
     loader.reset();
+    currentModel = ctx.model;
+    installPrewarmEditor(ctx);
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (!isConfigured(config)) return;
     if (!isHandoffTarget(ctx.model, config)) return;
 
+    // Fresh turn → fresh turn-abort controller. `before_agent_start` fires
+    // BEFORE the agent run starts, so `ctx.signal` is undefined here (the run's
+    // abort signal doesn't exist yet — it's created in `agent.prompt()` →
+    // `runWithLifecycle`, which runs AFTER this event). The prewarm below
+    // dispatches describer batches now, and they must be abortable once the
+    // run's live signal arrives — so reset the loader's turn-abort controller
+    // here, and let the later `tool_result`/`context` binds forward the live
+    // signal into it. Without this reset, a previous turn's ESC would leave
+    // the controller aborted and every dispatch would short-circuit to
+    // UNAVAILABLE.
+    loader.resetTurnAbort();
+
     // 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 || "");
@@ -405,6 +490,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("model_select", (event, ctx) => {
+    currentModel = event.model;
     if (!ctx.hasUI) return;
     if (!isConfigured(config)) return;
     const model = event.model;
@@ -420,7 +506,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("vision-handoff", {
     description: HANDOFF_COMMAND_DESCRIPTION,
     getArgumentCompletions(prefix: string) {
-      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "add", "remove", "clear", "help"];
+      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "prewarm", "add", "remove", "clear", "help"];
       const matches = subcommands.filter((s) => s.startsWith(prefix));
       return matches.length > 0 ? matches.map((s) => ({ value: s, label: s })) : null;
     },
@@ -454,6 +540,8 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "  /vision-handoff auto <on|off>  Toggle automatic handoff for all non-vision models",
         "  /vision-handoff thinking <off|minimal|low|medium|high|xhigh>",
         "                               Set the vision describer's thinking effort (off = disabled)",
+        "  /vision-handoff prewarm <on|off>",
+        "                               Toggle describing pasted images at paste-time (opt-in, off by default)",
         "  /vision-handoff add <p/id>     Force handoff for an extra model",
         "  /vision-handoff remove <p/id>  Stop forcing handoff for a model",
         "  /vision-handoff clear          Clear the configured vision model",
@@ -463,6 +551,7 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "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.",
+        "  prewarm on wraps the editor to describe pasted images at paste-time.",
       ].join("\n"),
       "info",
     );
@@ -504,6 +593,11 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
     return;
   }
 
+  if (subcommand === "prewarm") {
+    handlePrewarmSubcommand(ctx, rest);
+    return;
+  }
+
   if (subcommand === "clear") {
     updateConfig(
       ctx,
@@ -629,6 +723,30 @@ function handleThinkingSubcommand(ctx: ExtensionCommandContext, rest: string): v
   );
 }
 
+/** Handle `/vision-handoff prewarm <on|off>` — toggle paste-time prewarm. */
+function handlePrewarmSubcommand(ctx: ExtensionCommandContext, rest: string): void {
+  const value = rest.trim().toLowerCase();
+  if (!value) {
+    ctx.ui.notify(
+      `Paste-time prewarm: ${config.prewarmPastedImages ? "on" : "off"}.\n` +
+        `Usage: /vision-handoff prewarm <on|off>`,
+      "info",
+    );
+    return;
+  }
+  if (value !== "on" && value !== "off") {
+    ctx.ui.notify("Usage: /vision-handoff prewarm <on|off>", "warning");
+    return;
+  }
+  const on = value === "on";
+  const note = on
+    ? editorInstalled
+      ? "Paste-time prewarm on — pasted images are described the instant their path lands in the prompt (before submit)."
+      : "Paste-time prewarm on — but another custom editor extension is active, so it's unavailable. Submit-time prewarm still works; disable the other editor extension (or /vision-handoff prewarm off) to silence this."
+    : "Paste-time prewarm off — images are described at submit time (default).";
+  updateConfig(ctx, (c) => ({ ...c, prewarmPastedImages: on }), note);
+}
+
 async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   if (!ctx.hasUI) {
     ctx.ui.notify("/vision-handoff requires interactive mode.", "error");
@@ -692,6 +810,7 @@ function showStatus(ctx: ExtensionCommandContext): void {
   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(`Thinking: ${config.thinking ? `on (${config.thinkingLevel})` : "off"}`);
+  lines.push(`Paste-time prewarm: ${config.prewarmPastedImages ? `on${editorInstalled ? "" : " (inactive — another custom editor is active)"}` : "off"}`);
   lines.push(`maxTokens: ${config.maxTokens ?? "unbounded"} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);
 
   const model = ctx.model;