pi-vision-handoff 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.1",

package/src/dataloader.ts

@@ -154,8 +154,23 @@ export class DescriptionLoader implements Disposable {
    *  prewarm batch be aborted the moment the live signal arrives. */
   bindTurnContext(ctx: { modelRegistry: ModelRegistry; signal?: AbortSignal }): void {
     this.turnModelRegistry = ctx.modelRegistry;
-    const resolved = this.deps.resolveVisionModel(ctx.modelRegistry, this.deps.getConfig().visionModel!);
-    if (resolved) this.turnVisionModel = resolved;
+    const cfg = this.deps.getConfig();
+    const resolved = this.deps.resolveVisionModel(ctx.modelRegistry, cfg.visionModel!);
+    if (resolved) {
+      this.turnVisionModel = resolved;
+    } else {
+      // Primary unresolvable (typo, removed model): pick the first resolvable
+      // fallback so failover still works instead of leaving the loader dead.
+      // Call-time failover in dispatchBatch covers the case where the primary
+      // RESOLVES but fails at call time.
+      for (const ref of cfg.fallbackModels ?? []) {
+        const fb = this.deps.resolveVisionModel(ctx.modelRegistry, ref);
+        if (fb) {
+          this.turnVisionModel = fb;
+          break;
+        }
+      }
+    }
     const signal = ctx.signal;
     if (!signal) return;
     if (signal.aborted) {
@@ -314,6 +329,34 @@ export class DescriptionLoader implements Disposable {
         );
       }
     }
+    // Failover: the same-model retry failed too. Try each configured fallback
+    // describer in order (a different provider has independent rate limits /
+    // auth / availability). No per-fallback backoff — the fallback doesn't
+    // share the primary's rate-limit state. A partial result from any
+    // fallback wins; only when every fallback also returns empty do we give
+    // up (UNAVAILABLE, evicted from cache, re-attempted next turn). User
+    // cancel (ESC) skips failover.
+    if (parsed.size === 0 && misses.length > 0 && !this.turnAbortController.signal.aborted) {
+      for (const ref of cfg.fallbackModels ?? []) {
+        if (this.turnAbortController.signal.aborted) break;
+        const fallbackModel = this.deps.resolveVisionModel(this.turnModelRegistry, ref);
+        if (!fallbackModel) {
+          this.deps.setLastError(`fallback vision model "${ref}" could not be resolved`);
+          continue;
+        }
+        this.deps.setLastError(null);
+        parsed = await runBatch(
+          misses,
+          this.pendingTurnPrompt,
+          fallbackModel,
+          this.turnModelRegistry,
+          cfg,
+          this.deps,
+          this.turnAbortController.signal,
+        );
+        if (parsed.size > 0 || this.turnAbortController.signal.aborted) break;
+      }
+    }
     // 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
     // left hanging).

package/src/index.ts

@@ -133,6 +133,13 @@ export interface VisionHandoffConfig {
   enabled: boolean;
   /** The vision-capable model that describes images, as "provider/id". null = not configured. */
   visionModel: string | null;
+  /** Optional fallback describers, tried in order when the primary vision
+   *  model's batched call fails entirely (auth, rate limit, timeout, network,
+   *  empty/error stopReason) and the same-model retry didn't recover.
+   *  Each entry is a "provider/id" ref; providers usually differ from the
+   *  primary so their rate limits / auth / availability are independent.
+   *  Empty (default) = no failover. */
+  fallbackModels: string[];
   /** When true (default), handoff is applied to every model whose input does not include "image". */
   autoHandoff: boolean;
   /** Extra "provider/id" refs that should ALSO receive handoff (e.g. weak vision models). */
@@ -188,6 +195,7 @@ export interface VisionHandoffConfig {
 export const DEFAULT_CONFIG: VisionHandoffConfig = {
   enabled: true,
   visionModel: null,
+  fallbackModels: [],
   autoHandoff: true,
   handoffModels: [],
   prewarmPastedImages: false,
@@ -233,6 +241,12 @@ export function normalizeConfig(raw: unknown): VisionHandoffConfig {
   } else if (obj.visionModel === null) {
     base.visionModel = null;
   }
+  if (Array.isArray(obj.fallbackModels)) {
+    base.fallbackModels = obj.fallbackModels
+      .filter((m): m is string => typeof m === "string")
+      .map((m) => m.trim())
+      .filter((m) => m && parseModelRef(m));
+  }
   if (typeof obj.autoHandoff === "boolean") base.autoHandoff = obj.autoHandoff;
 
   if (Array.isArray(obj.handoffModels)) {

package/vision-handoff.ts

@@ -206,6 +206,16 @@ function resolveVisionModel(modelRegistry: ModelRegistry, ref: string): Model<Ap
   return model;
 }
 
+/** True when the primary vision model resolves, or — failing that — at least
+ *  one configured fallback resolves. A broken primary ref (typo, removed
+ *  model) must not short-circuit the whole pipeline to "unresolved" warnings
+ *  when a fallback could still describe images; the loader's failover picks
+ *  the resolvable fallback up in bindTurnContext. */
+function isAnyVisionModelResolvable(modelRegistry: ModelRegistry, config: VisionHandoffConfig): boolean {
+  if (resolveVisionModel(modelRegistry, config.visionModel!)) return true;
+  return config.fallbackModels.some((ref) => resolveVisionModel(modelRegistry, ref));
+}
+
 const loaderDeps: LoaderDeps = {
   getConfig: () => config,
   resolveVisionModel,
@@ -415,7 +425,7 @@ export default function (pi: ExtensionAPI) {
     loader.setPendingTurnPrompt(event.prompt || "");
     loader.bindTurnContext(ctx);
 
-    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
+    if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }
@@ -575,7 +585,7 @@ export default function (pi: ExtensionAPI) {
 
     if (imgs.length === 0) return;
     loader.bindTurnContext(ctx);
-    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
+    if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }
@@ -667,7 +677,7 @@ export default function (pi: ExtensionAPI) {
     if (!anyImage) return;
     if (!isHandoffTarget(ctx.model, config)) return;
     loader.bindTurnContext(ctx);
-    if (!resolveVisionModel(ctx.modelRegistry, config.visionModel!)) {
+    if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
       notifyUnresolvedVisionModel(ctx, config.visionModel!);
       return;
     }