pi-vision-handoff 0.9.5 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "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",
@@ -31,9 +31,9 @@
     "README.md"
   ],
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.1",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1",
+    "@earendil-works/pi-ai": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.1",

package/src/agent-dir.ts

@@ -0,0 +1,16 @@
+// pi's agent-dir resolution in-process, so no module on the extension load
+// path imports the pi-coding-agent runtime (its graph costs ~1s per extension
+// in pi's loader).
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const expandTilde = (value: string): string => {
+  if (value === "~") return homedir();
+  return value.startsWith("~/") ? join(homedir(), value.slice(2)) : value;
+};
+
+export const resolveAgentDir = (): string => {
+  const override = process.env.PI_CODING_AGENT_DIR;
+  return override ? expandTilde(override) : join(homedir(), ".pi", "agent");
+};

package/src/dataloader.ts

@@ -31,8 +31,7 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import {
-  IMAGE_PLACEHOLDER_PREFIX,
-  IMAGE_PLACEHOLDER_SUFFIX,
+  UNAVAILABLE,
   wrapDescription,
   type ExtractedImage,
   type VisionHandoffConfig,
@@ -40,9 +39,9 @@ import {
 import { imageHash } from "./image.js";
 import { runBatch, describeSingle, type DescriberDeps } from "./describer.js";
 
-/** Resolved when a description couldn't be obtained (graceful degradation).
- *  Failures are NOT cached, so the next turn re-attempts. */
-export const UNAVAILABLE = `${IMAGE_PLACEHOLDER_PREFIX}description unavailable${IMAGE_PLACEHOLDER_SUFFIX}`;
+// Kept for back-compat with tests and older consumers; the canonical export
+// lives in ./index.js where it costs no describer-chain import.
+export { UNAVAILABLE };
 
 interface DescriptionBatch {
   keys: string[];

package/src/error-log.ts

@@ -22,9 +22,9 @@
  * errors.log.1) bounds growth to ~2× the cap.
  */
 
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { appendFileSync, existsSync, mkdirSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { resolveAgentDir } from "./agent-dir.js";
 
 /** Subdirectory under the pi agent dir holding this extension's logs. */
 const LOG_SUBDIR = "logs/pi-vision-handoff";
@@ -76,7 +76,7 @@ export interface VisionErrorLogEntry {
 /** Directory holding this extension's logs:
  *  ~/.pi/agent/logs/pi-vision-handoff (overridable via $PI_CODING_AGENT_DIR). */
 export function getErrorLogDir(): string {
-  return join(getAgentDir(), LOG_SUBDIR);
+  return join(resolveAgentDir(), LOG_SUBDIR);
 }
 
 /** Path to the active error log file. */

package/src/index.ts

@@ -6,9 +6,9 @@
  */
 
 import type { ImageContent, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { resolveAgentDir } from "./agent-dir.js";
 
 export * from "./usage.js";
 
@@ -20,7 +20,7 @@ export const CONFIG_FILENAME = "pi-vision-handoff.json";
 
 /** Full config path: ~/.pi/agent/extensions/pi-vision-handoff.json */
 export function getConfigPath(): string {
-  return join(getAgentDir(), CONFIG_SUBDIR, CONFIG_FILENAME);
+  return join(resolveAgentDir(), CONFIG_SUBDIR, CONFIG_FILENAME);
 }
 
 /** Description shown in the / commands list. */
@@ -38,6 +38,11 @@ export const DEFAULT_USER_PROMPT_PREFIX = "The user's request about this image:
 export const IMAGE_PLACEHOLDER_PREFIX = "[Image: ";
 export const IMAGE_PLACEHOLDER_SUFFIX = "]";
 
+/** Resolved when a description couldn't be obtained (graceful degradation).
+ *  Failures are NOT cached, so the next turn re-attempts. Defined here so
+ *  consumers reach it without loading the describer chain. */
+export const UNAVAILABLE = `${IMAGE_PLACEHOLDER_PREFIX}description unavailable${IMAGE_PLACEHOLDER_SUFFIX}`;
+
 /** 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.
@@ -299,7 +304,7 @@ export function readConfig(): VisionHandoffConfig {
 /** Write config to disk. Creates the directory if needed. Returns the path written. */
 export function writeConfig(config: VisionHandoffConfig): string {
   const path = getConfigPath();
-  const dir = join(getAgentDir(), CONFIG_SUBDIR);
+  const dir = join(resolveAgentDir(), CONFIG_SUBDIR);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }

package/vision-handoff.ts

@@ -44,6 +44,7 @@ import {
   stripNonVisionImageNote,
   writeConfig,
   HANDOFF_COMMAND_DESCRIPTION,
+  UNAVAILABLE,
   type ExtractedImage,
   type VisionHandoffConfig,
 } from "./src/index.js";
@@ -52,12 +53,10 @@ import {
   USAGE_EVENT_CHANNEL,
   type VisionHandoffUsageRecord,
 } from "./src/usage.js";
-import { DescriptionLoader, UNAVAILABLE, type LoaderDeps } from "./src/dataloader.js";
+import type { DescriptionLoader, LoaderDeps } from "./src/dataloader.js";
 import { imageHash, findPastedImagePaths, readImageBuffer, readImageBufferBounded, resolvePrewarmImage, isOmittedImageNote } from "./src/image.js";
 import { appendVisionError } from "./src/error-log.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";
+import type { VisionModelSelectorResult } from "./src/vision-model-selector.js";
 import { Text } from "@earendil-works/pi-tui";
 
 let config: VisionHandoffConfig = readConfig();
@@ -224,7 +223,19 @@ const loaderDeps: LoaderDeps = {
     lastDescriberError = msg;
   },
 };
-const loader = new DescriptionLoader(loaderDeps);
+// The describer chain (dataloader -> describer -> pi-ai/compat) and pi-core's
+// resizeImage / pi-tui's Text each drag a host module graph into this
+// extension's loader when imported statically. Load them behind the first
+// image turn / editor install / async render so startup stays import-free.
+let loaderPromise: Promise<DescriptionLoader> | undefined;
+const getLoader = (): Promise<DescriptionLoader> => {
+  loaderPromise ??= import("./src/dataloader.js").then(
+    ({ DescriptionLoader }) => new DescriptionLoader(loaderDeps),
+  );
+  return loaderPromise;
+};
+const loadResizeImage = () =>
+  import("@earendil-works/pi-coding-agent").then(({ resizeImage }) => resizeImage);
 
 function isConfigured(cfg: VisionHandoffConfig): boolean {
   return cfg.enabled && !!cfg.visionModel;
@@ -257,9 +268,11 @@ function shouldPrewarmPaste(): boolean {
  *  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 {
+async function prewarmClipboardPath(path: string, modelRegistry: ModelRegistry): Promise<void> {
   const read = readImageBuffer(path);
   if (!read) return;
+  const resizeImage = await loadResizeImage();
+  const loader = await getLoader();
   resolvePrewarmImage(read.buf, read.mimeType, resizeImage)
     .then((img) => {
       if (!img) return;
@@ -283,7 +296,7 @@ function prewarmClipboardPath(path: string, modelRegistry: ModelRegistry): void
  *  (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 {
+async function installPrewarmEditor(ctx: ExtensionContext): Promise<void> {
   if (ctx.mode !== "tui") {
     editorInstalled = false;
     return;
@@ -292,6 +305,7 @@ function installPrewarmEditor(ctx: ExtensionContext): void {
     editorInstalled = false;
     return;
   }
+  const { PrewarmEditor } = await import("./src/prewarm-editor.js");
   editorInstalled = true;
   ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
     new PrewarmEditor(_tui, theme, keybindings, {
@@ -398,9 +412,9 @@ export default function (pi: ExtensionAPI) {
     visionModelCache = null;
     visionModelUnresolvedRef = null;
     warnedHashes.clear();
-    loader.reset();
+    void getLoader().then((loader) => loader.reset());
     currentModel = ctx.model;
-    installPrewarmEditor(ctx);
+    await installPrewarmEditor(ctx);
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
@@ -418,6 +432,7 @@ export default function (pi: ExtensionAPI) {
     // signal into it. Without this reset, a previous turn's ESC would leave
     // the controller aborted and every dispatch would short-circuit to
     // UNAVAILABLE.
+    const loader = await getLoader();
     loader.resetTurnAbort();
 
     // Capture this turn's user prompt so every image in the turn — attached or
@@ -470,6 +485,7 @@ export default function (pi: ExtensionAPI) {
     // 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).
     const clipboardPaths = findPastedImagePaths(event.prompt || "");
+    const resizeImage = await loadResizeImage();
     const preparedClipboardImages = clipboardPaths.map(
       async (path): Promise<PreparedClipboardImage | null> => {
         try {
@@ -584,6 +600,7 @@ export default function (pi: ExtensionAPI) {
     }
 
     if (imgs.length === 0) return;
+    const loader = await getLoader();
     loader.bindTurnContext(ctx);
     if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
@@ -676,6 +693,7 @@ export default function (pi: ExtensionAPI) {
     }
     if (!anyImage) return;
     if (!isHandoffTarget(ctx.model, config)) return;
+    const loader = await getLoader();
     loader.bindTurnContext(ctx);
     if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
@@ -1046,6 +1064,7 @@ async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
     return;
   }
 
+  const { VisionModelSelectorComponent } = await import("./src/vision-model-selector.js");
   const result = await ctx.ui.custom<VisionModelSelectorResult>((tui, theme, _kb, done) => {
     const selector = new VisionModelSelectorComponent(
       theme,