pi-model-fallback 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -2,25 +2,37 @@
 
 ## Unreleased
 
-## [0.3.7] - 2026-08-22
+## [0.4.0] - 2026-09-11
 
-### Changed
+### Added
 
-- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
+- `autoRetry` config option (default `true`): when a fallback switch happens after a failed turn, the failed user prompt is automatically re-queued so the turn retries on the fallback model.
 
 ### Fixed
 
-- Warn on completely shadowed fallback rules in config validation, save confirmations, status output, and config details without rejecting warning-bearing configs.
-- Document the missing `git add`/`git commit` steps in `CONTRIBUTING.md` release instructions so maintainers can trigger auto-release after `npm version patch --no-git-tag-version`.
-- Clarify that maintainers should update `CHANGELOG.md` before staging release files.
+- Parse leading bare status codes in provider error messages (for example `401: {...}` from OpenCode Go and OpenRouter) so fallback rules fire on real-world failure shapes.
+- Auto-retry when a fallback model is merely preselected instead of skipping the switch path.
+- Parse optional `Error:` prefixes before leading bare status codes.
 
 ### Changed
 
-- Bump package version to `0.3.5` for the next patch release.
+- Bump Pi dev dependencies to `@earendil-works/*` 0.84.4 and `@types/node` 26.4.0.
+- Add `jiti` as a devDependency so auto-retry integration tests run in CI.
+
+## [0.3.7] - 2026-08-22
+
+### Changed
 
+- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
 - Declare `@earendil-works/pi-agent-core` as a peerDependency to align with pi-extension-template.
 - Add Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
 
+### Fixed
+
+- Warn on completely shadowed fallback rules in config validation, save confirmations, status output, and config details without rejecting warning-bearing configs.
+- Document the missing `git add`/`git commit` steps in `CONTRIBUTING.md` release instructions so maintainers can trigger auto-release after `npm version patch --no-git-tag-version`.
+- Clarify that maintainers should update `CHANGELOG.md` before staging release files.
+
 ## [0.3.3] - 2026-07-04
 
 ### Changed
@@ -74,7 +86,7 @@ This project follows semantic versioning.
 - Publish workflow now installs a current npm CLI so npm Trusted Publishing OIDC is supported.
 - CI and publish workflow commands no longer include literal trailing `\\n` text.
 
-## [0.1.0] - YYYY-MM-DD
+## [0.1.0] - 2026-06-30
 
 ### Added
 

package/README.md

@@ -70,6 +70,7 @@ Default config shape:
 {
   "version": 1,
   "enabled": true,
+  "autoRetry": true,
   "rules": [
     {
       "name": "zai-to-deepseek-flash",
@@ -92,6 +93,11 @@ Rule fields:
 - `cooldownMs`: optional persistent fallback window
 - `fallback`: target model Pi should switch to
 
+Top-level fields:
+
+- `enabled`: toggle the extension without deleting rules
+- `autoRetry`: when a fallback fires from a failed turn, automatically re-queue the failed user prompt so the turn retries on the fallback model (defaults to `true`; set to `false` to only switch models)
+
 Rules use first-match order: the first rule whose provider/model and status match wins. Put specific `matchModels` rules before broad `matchProviders` rules when they should take priority. `model_fallback_config validate`, `save`, `read`, and `status` report warning-only diagnostics when a later rule or model entry is completely shadowed by an earlier rule; `/model-fallback:status` also includes a concise warning summary for the current config. Warning-bearing config remains valid and can still be saved.
 
 ### Cooldowns

package/extensions/index.ts

@@ -17,6 +17,7 @@ import {
 } from "../lib/config.js";
 import { parseStatusFromErrorMessage } from "../lib/error-status.js";
 import { emptyState, findActiveStateEntry, pruneExpiredState, readState, upsertStateEntry, validateStateShape, writeState, type FallbackState } from "../lib/state.js";
+import { isRecord } from "../lib/internal.ts";
 import { modelFallbackPaths, readConfig, writeConfig, type ModelFallbackPaths } from "../lib/storage.js";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -106,17 +107,20 @@ export default function modelFallback(pi: ExtensionAPI) {
     ctx.ui.notify(`Model fallback preselected: ${originalModelKey} → ${activeFallbackKey} until ${active.until}.`, "warning");
   }
 
-  async function persistFailure(source: ModelRef, status: number, headers: Record<string, string>, ctx: ExtensionContext): Promise<void> {
+  async function persistFailure(source: ModelRef, status: number, headers: Record<string, string>, ctx: ExtensionContext): Promise<boolean> {
     const loaded = config ?? (await loadConfig(ctx));
-    if (!loaded) return;
+    if (!loaded) return false;
     const match = findFallback(loaded, { provider: source.provider, id: source.model }, status);
-    if (!match) return;
-    if (activeFallbackKey && activeFallbackKey === modelRefKey(match.fallback)) return;
+    if (!match) return false;
+    // Only skip when the failing model IS the active fallback (its own failure should not
+    // re-trigger). A failure on the original model while the fallback is merely preselected
+    // must still proceed so auto-retry can run on the fallback.
+    if (activeFallbackKey && modelRefKey(source) === activeFallbackKey) return false;
 
     const fallbackModel = ctx.modelRegistry.find(match.fallback.provider, match.fallback.model);
     if (!fallbackModel) {
       ctx.ui.notify(`Model fallback missing: ${modelRefKey(match.fallback)}`, "warning");
-      return;
+      return false;
     }
 
     const now = new Date();
@@ -135,7 +139,7 @@ export default function modelFallback(pi: ExtensionAPI) {
     const ok = await pi.setModel(fallbackModel);
     if (!ok) {
       ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
-      return;
+      return false;
     }
 
     originalModelKey = modelRefKey(source);
@@ -143,6 +147,7 @@ export default function modelFallback(pi: ExtensionAPI) {
     lastFallbackReason = `${status} from ${originalModelKey}; persistent until ${until}`;
     updateStatus(ctx);
     ctx.ui.notify(`Model fallback: ${originalModelKey} → ${activeFallbackKey} (${status}). Future sessions preselect fallback until ${until}.`, "warning");
+    return true;
   }
 
   pi.on("agent_start", async (_event, ctx) => {
@@ -182,7 +187,14 @@ export default function modelFallback(pi: ExtensionAPI) {
     const model = typeof message.model === "string" ? message.model : ctx.model?.id;
     if (!provider || !model) return;
     if (activeFallbackKey && `${provider}/${model}` === activeFallbackKey) return;
-    await persistFailure({ provider, model }, status, {}, ctx);
+    const switched = await persistFailure({ provider, model }, status, {}, ctx);
+    if (!switched) return;
+    const loaded = config;
+    if (!loaded || loaded.autoRetry === false) return;
+    const prompt = lastUserPromptText(ctx);
+    if (!prompt) return;
+    ctx.ui.notify(`Model fallback: retrying failed prompt on ${activeFallbackKey}.`, "info");
+    await pi.sendUserMessage(prompt, { deliverAs: "followUp" });
   });
 
   pi.registerCommand("model-fallback:status", {
@@ -266,6 +278,33 @@ export default function modelFallback(pi: ExtensionAPI) {
   });
 }
 
+function autoRetryEnabled(config: ModelFallbackConfig): boolean {
+  return config.autoRetry !== false;
+}
+
+function lastUserPromptText(ctx: ExtensionContext): string | undefined {
+  const entries = ctx.sessionManager.getEntries() as unknown[];
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (!isRecord(entry) || !isRecord(entry.message)) continue;
+    const message = entry.message;
+    if (message.role !== "user") continue;
+    return userMessageText(message.content);
+  }
+  return undefined;
+}
+
+function userMessageText(content: unknown): string | undefined {
+  if (typeof content === "string") return content.trim() || undefined;
+  if (!Array.isArray(content)) return undefined;
+  const parts: string[] = [];
+  for (const block of content) {
+    if (isRecord(block) && block.type === "text" && typeof block.text === "string") parts.push(block.text);
+  }
+  const text = parts.join("\n").trim();
+  return text || undefined;
+}
+
 function shouldUseProjectLocalState(ctx: ExtensionContext): boolean {
   const projectSettingsPath = join(ctx.cwd, ".pi", "settings.json");
   return existsSync(projectSettingsPath) && projectSettingsIncludesThisPackage(projectSettingsPath);
@@ -307,6 +346,7 @@ function formatStatus(
 ): string {
   return [
     `Model fallback: ${config.enabled ? "enabled" : "disabled"}`,
+    `Auto retry: ${autoRetryEnabled(config) ? "enabled" : "disabled"}`,
     `Config: ${configPath}`,
     `State: ${statePath}`,
     `Rules: ${config.rules.length}`,
@@ -322,6 +362,7 @@ function formatStatus(
 function summarizeConfig(config: ModelFallbackConfig, warnings: RuleWarning[]): string {
   return [
     `enabled: ${config.enabled}`,
+    `autoRetry: ${autoRetryEnabled(config)}`,
     ...config.rules.map((rule) => `${rule.name ?? "rule"}: ${rule.matchProviders?.join(",") ?? "models"} -> ${modelRefKey(rule.fallback)}`),
     `warnings: ${warningSummary(warnings)}`,
   ].join("\n");
@@ -423,6 +464,3 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/lib/config.ts

@@ -1,4 +1,5 @@
 import type { Model } from "@earendil-works/pi-ai";
+import { isRecord, readModelRef, readNonEmptyString } from "./internal.ts";
 
 export const CONFIG_VERSION = 1;
 export const DEFAULT_FALLBACK_STATUSES = [429, 500, 502, 503, 504] as const;
@@ -21,6 +22,8 @@ export interface FallbackRule {
 export interface ModelFallbackConfig {
   version: 1;
   enabled: boolean;
+  /** Re-queue the failed user prompt after switching to the fallback model so the turn retries automatically. Defaults to true. */
+  autoRetry?: boolean;
   rules: FallbackRule[];
 }
 
@@ -55,6 +58,7 @@ export function defaultConfig(): ModelFallbackConfig {
   return {
     version: CONFIG_VERSION,
     enabled: true,
+    autoRetry: true,
     rules: [
       {
         name: "zai-to-deepseek-flash",
@@ -76,6 +80,7 @@ export function validateConfigShape(value: unknown): ModelFallbackConfig {
   return {
     version: CONFIG_VERSION,
     enabled,
+    autoRetry: typeof value.autoRetry === "boolean" ? value.autoRetry : true,
     rules: value.rules.map((ruleValue, index) => validateRule(ruleValue, index)),
   };
 }
@@ -281,14 +286,6 @@ function formatModelList(models: ModelRef[]): string {
   return models.map(modelRefKey).sort().join(", ");
 }
 
-function readModelRef(value: unknown, path: string): ModelRef {
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  return {
-    provider: readNonEmptyString(value.provider, `${path}.provider`),
-    model: readNonEmptyString(value.model, `${path}.model`),
-  };
-}
-
 function readModelRefArray(value: unknown, path: string): ModelRef[] {
   if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
   if (value.length === 0) throw new Error(`${path} must not be empty.`);
@@ -315,11 +312,3 @@ function readPositiveInteger(value: unknown, path: string): number {
   return value;
 }
 
-function readNonEmptyString(value: unknown, path: string): string {
-  if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
-  return value.trim();
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/lib/error-status.ts

@@ -1,5 +1,8 @@
 export function parseStatusFromErrorMessage(message: string): number | undefined {
   const patterns: RegExp[] = [
+    // Leading bare status code, optionally prefixed with "Error:", e.g. "401: {\"type\":\"CreditsError\"...}"
+    // or "Error: 401: {\"type\":\"CreditsError\"...}" (OpenCode Go, OpenRouter relays)
+    /^\s*(?:error\s*:?\s*)?([1-5][0-9]{2})\s*:/i,
     /\b(?:status|code|http)\s*[:\s]?\s*([1-5][0-9]{2})\b/i,
     /\bHTTP\/\d(?:\.\d)?\s+([1-5][0-9]{2})\b/,
     /\b(?:rate[\s-]?limit(?:ed)?|too many requests)[^0-9]{0,40}([45][0-9]{2})\b/i,

package/lib/internal.ts

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+  return value.trim();
+}
+
+export function readModelRef(value: unknown, path: string): { provider: string; model: string } {
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  return {
+    provider: readNonEmptyString(value.provider, `${path}.provider`),
+    model: readNonEmptyString(value.model, `${path}.model`),
+  };
+}
+
+export async function readJsonIfExists(path: string): Promise<unknown | undefined> {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/lib/state.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import type { ModelRef } from "./config.js";
+import { modelRefKey, type ModelRef } from "./config.ts";
+import { isRecord, readJsonIfExists, readModelRef, readNonEmptyString } from "./internal.ts";
 
 export const STATE_VERSION = 1;
 
@@ -41,10 +42,6 @@ export function upsertStateEntry(state: FallbackState, entry: FallbackStateEntry
   };
 }
 
-function modelRefKey(ref: ModelRef): string {
-  return `${ref.provider}/${ref.model}`;
-}
-
 export function findActiveStateEntry(state: FallbackState, source: ModelRef, now = new Date()): FallbackStateEntry | undefined {
   const sourceKey = modelRefKey(source);
   return state.entries.find((entry) => modelRefKey(entry.source) === sourceKey && Date.parse(entry.until) > now.getTime());
@@ -87,32 +84,3 @@ function validateEntry(value: unknown, index: number): FallbackStateEntry {
   return entry;
 }
 
-function readModelRef(value: unknown, path: string): ModelRef {
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  return {
-    provider: readNonEmptyString(value.provider, `${path}.provider`),
-    model: readNonEmptyString(value.model, `${path}.model`),
-  };
-}
-
-function readNonEmptyString(value: unknown, path: string): string {
-  if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
-  return value.trim();
-}
-
-async function readJsonIfExists(path: string): Promise<unknown | undefined> {
-  try {
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") return undefined;
-    throw error;
-  }
-}
-
-function isNodeError(error: unknown): error is NodeJS.ErrnoException {
-  return error instanceof Error && "code" in error;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/lib/storage.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { defaultConfig, validateConfigShape, type ModelFallbackConfig } from "./config.js";
+import { defaultConfig, validateConfigShape, type ModelFallbackConfig } from "./config.ts";
+import { readJsonIfExists } from "./internal.ts";
 
 export interface ModelFallbackPaths {
   dir: string;
@@ -23,15 +24,3 @@ export async function writeConfig(path: string, config: ModelFallbackConfig): Pr
   await writeFile(path, `${JSON.stringify(validateConfigShape(config), null, 2)}\n`, "utf8");
 }
 
-async function readJsonIfExists(path: string): Promise<unknown | undefined> {
-  try {
-    return JSON.parse(await readFile(path, "utf8"));
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") return undefined;
-    throw error;
-  }
-}
-
-function isNodeError(error: unknown): error is NodeJS.ErrnoException {
-  return error instanceof Error && "code" in error;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-model-fallback",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
   "type": "module",
   "license": "MIT",
@@ -54,8 +54,9 @@
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "@earendil-works/pi-tui": "^0.84.1",
-    "typebox": "latest",
     "@types/node": "^26.0.0",
+    "jiti": "^2.7.0",
+    "typebox": "latest",
     "typescript": "^7.0.2"
   }
 }