pi-model-fallback 0.3.7 → 0.5.0

package/CHANGELOG.md

@@ -2,25 +2,55 @@
 
 ## Unreleased
 
-## [0.3.7] - 2026-08-22
+## [0.5.0] - 2026-09-22
+
+### Added
+
+- `reasons` rule option: match optional failure reason codes (for example `context_length_exceeded`) parsed from provider error messages, so status codes like `400` can trigger fallback only for specific causes such as context-length overflow. Reason-aware rules participate in shadowing analysis, and unrestricted earlier rules still shadow later reason-scoped rules.
+- Never fall back to the failing model itself: rules whose fallback target equals the failing model are skipped so the next matching rule applies.
+- Cascading fallback chains: when the active fallback model fails, other matching rules can move the session onward (for example `free → kimi-k2.6 → glm-5.3-flash`). Cascades never revisit a model already used in the current run, so circular rules cannot loop.
+
+### Fixed
+
+- Parse `Error: <status>` messages that carry no colon after the status, such as GitHub Copilot's `Error: 429 quota exceeded`. These fell between the leading-bare-status pattern, which requires a colon after the status, and the `error <status>` pattern, which requires whitespace directly after `error`, so Copilot quota exhaustion never triggered a fallback.
+- Recognise a bare status followed by a quota noun, such as `429 quota exceeded`.
 
 ### Changed
 
-- Merge the 2026-08-22 managed OSS dependency and maintenance PR batch.
+- Bump Pi dev dependencies to `@earendil-works/*` 0.86.1 and `@types/node` 26.5.1.
+- Refresh the fallback retry example in the README and usage docs.
+
+## [0.4.0] - 2026-09-11
+
+### Added
+
+- `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 +104,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",
@@ -89,9 +90,15 @@ Rule fields:
 - `matchProviders`: match all models from a provider
 - `matchModels`: match specific `provider` + `model` pairs
 - `statuses`: optional; defaults to `429, 500, 502, 503, 504`
+- `reasons`: optional list of failure reason codes (for example `context_length_exceeded`); when set, the rule only fires if the parsed failure reason is listed. Reasons come from quoted machine codes in the error message (for example `"provider_error_code":"context_length_exceeded"`) or prose such as `exceeds this model's context length`. Useful for status codes like `400` that should only trigger a fallback for specific causes, such as context-length overflow.
 - `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). The failed prompt is queued once, not retried indefinitely.
+
 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
@@ -117,7 +124,11 @@ If the package is installed project-locally and the current project references i
 - Successful responses do nothing.
 - Matching failures from `after_provider_response` can trigger fallback immediately.
 - Assistant error messages parsed at `turn_end` can also persist fallback state for SDK/provider failures that do not emit the normal response hook. Status extraction looks for HTTP-style tokens (for example `status 429`, `HTTP 503`, or `rate limit`) rather than any bare 3-digit number in the message.
-- The failed request is not automatically replayed.
+- With the default `autoRetry: true`, the failed prompt is automatically queued once on the fallback model. Set `autoRetry: false` to switch models without replaying it.
+
+Rules never fall back to the failing model itself; a rule whose fallback target equals the failing model is skipped so the next matching rule (or no rule) applies.
+
+Fallback chains cascade: when the active fallback model itself fails, another matching rule may move the session further (for example `free model → kimi-k2.6 → glm-5.3-flash`). A cascade never revisits a model already used in the current run (the original or an earlier fallback), so circular rule configurations cannot ping-pong; when no unvisited target remains, the failure surfaces normally.
 
 ## Development
 

package/docs/usage.md

@@ -6,7 +6,7 @@ Install:
 pi install npm:pi-model-fallback
 ```
 
-Default behavior: when a `zai/*` model receives `429`, `500`, `502`, `503`, or `504`, Pi switches to `deepseek/deepseek-v4-flash` for the next prompt.
+Default behavior: when a `zai/*` model receives `429`, `500`, `502`, `503`, or `504`, Pi switches to `deepseek/deepseek-v4-flash` for the next prompt. The failed prompt is automatically queued once on the fallback model; set `"autoRetry": false` in `model-fallback/config.json` to switch models without retrying it.
 
 Commands:
 
@@ -17,6 +17,8 @@ Commands:
 
 Rule order is first-match: the first rule whose provider/model and status match wins. Place specific `matchModels` rules before broad `matchProviders` rules when the model-specific fallback should take priority. `model_fallback_config validate`, `save`, `read`, and `status` expose warning-only details for completely shadowed later rules or model entries, and `/model-fallback:status` includes a concise current-config warning summary; these warnings do not make the config invalid.
 
+Rules can also match on failure reasons with `reasons`, for example `"reasons": ["context_length_exceeded"]` on a `400` rule so only context-overflow failures switch models while other `400`s stay errors. Reasons are parsed from quoted provider error codes (for example `"provider_error_code":"context_length_exceeded"`) or prose such as `exceeds this model's context length`. A rule never falls back to the failing model itself.
+
 Cooldown defaults when a rule omits `cooldownMs`:
 
 - `429` → 72 hours
@@ -24,4 +26,4 @@ Cooldown defaults when a rule omits `cooldownMs`:
 
 `Retry-After` and `x-ratelimit-reset*` response headers override `cooldownMs` and those defaults.
 
-The failed request is not automatically replayed.
+If `autoRetry` is disabled, the failed request is not automatically replayed.

package/extensions/index.ts

@@ -15,8 +15,9 @@ import {
   type ModelRef,
   type RuleWarning,
 } from "../lib/config.js";
-import { parseStatusFromErrorMessage } from "../lib/error-status.js";
+import { parseReasonFromErrorMessage, 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)));
@@ -32,6 +33,10 @@ export default function modelFallback(pi: ExtensionAPI) {
   let originalModelKey: string | undefined;
   let activeFallbackKey: string | undefined;
   let lastFallbackReason: string | undefined;
+  // Models already fallen back to during this run (plus the original). A cascade may only
+  // target a model never visited, which makes chains (free → kimi → glm) safe while
+  // preventing A→B→A ping-pong with circular rules.
+  let visitedFallbackKeys = new Set<string>();
 
   function syncPaths(ctx: ExtensionContext): void {
     if (pathsResolvedForCwd === ctx.cwd) return;
@@ -93,32 +98,49 @@ export default function modelFallback(pi: ExtensionAPI) {
       return;
     }
 
+    originalModelKey = modelKey(current);
+    activeFallbackKey = modelRefKey(active.fallback);
+    visitedFallbackKeys = new Set([originalModelKey, activeFallbackKey]);
+    lastFallbackReason = `persistent ${active.status} from ${originalModelKey} until ${active.until}`;
+    updateStatus(ctx);
     const ok = await pi.setModel(fallbackModel);
     if (!ok) {
       ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(active.fallback)}`, "warning");
+      originalModelKey = undefined;
+      activeFallbackKey = undefined;
+      lastFallbackReason = undefined;
+      visitedFallbackKeys = new Set();
+      updateStatus(ctx);
       return;
     }
-
-    originalModelKey = modelKey(current);
-    activeFallbackKey = modelRefKey(active.fallback);
-    lastFallbackReason = `persistent ${active.status} from ${originalModelKey} until ${active.until}`;
     updateStatus(ctx);
     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, reason?: string): Promise<boolean> {
     const loaded = config ?? (await loadConfig(ctx));
-    if (!loaded) return;
-    const match = findFallback(loaded, { provider: source.provider, id: source.model }, status);
-    if (!match) return;
-    if (activeFallbackKey && activeFallbackKey === modelRefKey(match.fallback)) return;
+    if (!loaded) return false;
+    const match = findFallback(loaded, { provider: source.provider, id: source.model }, status, reason);
+    if (!match) 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;
     }
 
+    // Loop guard: never fall back to a model already visited this run (the original or an
+    // earlier fallback). This both blocks circular rules from ping-ponging and stops the
+    // current fallback from re-selecting itself, while still allowing onward cascades
+    // (free → kimi → glm) when a different rule matches the fallback's own failure.
+    // Exception: when the failing model is the remembered original and the candidate is the
+    // already-preselected fallback, re-applying the same hop is idempotent and stays allowed
+    // (turn attribution can lag behind the preselection).
+    const fallbackKey = modelRefKey(match.fallback);
+    const sourceKey = modelRefKey(source);
+    const idempotentReapply = fallbackKey === activeFallbackKey && sourceKey === originalModelKey;
+    if (visitedFallbackKeys.has(fallbackKey) && !idempotentReapply) return false;
+
     const now = new Date();
     const until = new Date(now.getTime() + cooldownMsFor(match.rule.cooldownMs, status, headers)).toISOString();
     const loadedState = state ?? (await loadState(ctx)) ?? { version: 1 as const, entries: [] };
@@ -132,22 +154,37 @@ export default function modelFallback(pi: ExtensionAPI) {
     });
     await writeState(paths.state, state);
 
+    const prevOriginal = originalModelKey;
+    const prevActive = activeFallbackKey;
+    const prevReason = lastFallbackReason;
+    const prevVisited = visitedFallbackKeys;
+    // Mark before setModel so the model_select handler keeps fallback bookkeeping.
+    if (!originalModelKey) originalModelKey = sourceKey;
+    activeFallbackKey = fallbackKey;
+    visitedFallbackKeys = new Set(prevVisited);
+    visitedFallbackKeys.add(sourceKey);
+    visitedFallbackKeys.add(fallbackKey);
+    lastFallbackReason = `${status} from ${sourceKey}${reason ? ` (${reason})` : ""}; persistent until ${until}`;
+    updateStatus(ctx);
+
     const ok = await pi.setModel(fallbackModel);
     if (!ok) {
+      originalModelKey = prevOriginal;
+      activeFallbackKey = prevActive;
+      lastFallbackReason = prevReason;
+      visitedFallbackKeys = prevVisited;
+      updateStatus(ctx);
       ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
-      return;
+      return false;
     }
-
-    originalModelKey = modelRefKey(source);
-    activeFallbackKey = modelRefKey(match.fallback);
-    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) => {
     await loadConfig(ctx);
     await loadState(ctx);
+    visitedFallbackKeys = new Set();
     await applyPersistentFallback(ctx);
     updateStatus(ctx);
   });
@@ -157,6 +194,7 @@ export default function modelFallback(pi: ExtensionAPI) {
       activeFallbackKey = undefined;
       originalModelKey = undefined;
       lastFallbackReason = undefined;
+      visitedFallbackKeys = new Set();
       updateStatus(ctx);
     }
   });
@@ -166,7 +204,6 @@ export default function modelFallback(pi: ExtensionAPI) {
     const loaded = config ?? (await loadConfig(ctx));
     if (!current || !loaded) return;
     if (event.status >= 200 && event.status < 300) return;
-    if (activeFallbackKey && modelKey(current) === activeFallbackKey) return;
 
     await persistFailure(modelToRef(current), event.status, event.headers, ctx);
   });
@@ -178,11 +215,18 @@ export default function modelFallback(pi: ExtensionAPI) {
     if (!errorMessage) return;
     const status = parseStatusFromErrorMessage(errorMessage);
     if (status === undefined) return;
+    const reason = parseReasonFromErrorMessage(errorMessage);
     const provider = typeof message.provider === "string" ? message.provider : ctx.model?.provider;
     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, reason);
+    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", {
@@ -204,6 +248,7 @@ export default function modelFallback(pi: ExtensionAPI) {
         ctx.ui.notify("Model fallback: persistent state cleared; no remembered original model.", "info");
         activeFallbackKey = undefined;
         lastFallbackReason = undefined;
+        visitedFallbackKeys = new Set();
         updateStatus(ctx);
         return;
       }
@@ -221,6 +266,7 @@ export default function modelFallback(pi: ExtensionAPI) {
       activeFallbackKey = undefined;
       originalModelKey = undefined;
       lastFallbackReason = undefined;
+      visitedFallbackKeys = new Set();
       updateStatus(ctx);
       ctx.ui.notify(`Model fallback reset: ${modelKey(model)}; persistent state cleared.`, "info");
     },
@@ -266,6 +312,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 +380,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 +396,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 +498,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;
@@ -13,6 +14,8 @@ export interface FallbackRule {
   matchProviders?: string[];
   matchModels?: ModelRef[];
   statuses?: number[];
+  /** Failure reason codes (for example `context_length_exceeded`); when set, the rule only fires if the parsed reason is listed. */
+  reasons?: string[];
   /** Persistent failover cooldown in milliseconds after a matching failure. Defaults: 429 => 72h, 5xx => 10m. */
   cooldownMs?: number;
   fallback: ModelRef;
@@ -21,6 +24,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[];
 }
 
@@ -49,12 +54,15 @@ interface NormalizedRuleForWarnings {
   modelKeys: Set<string>;
   models: ModelRef[];
   statuses: Set<number>;
+  /** undefined = the rule matches any failure reason. */
+  reasons?: Set<string>;
 }
 
 export function defaultConfig(): ModelFallbackConfig {
   return {
     version: CONFIG_VERSION,
     enabled: true,
+    autoRetry: true,
     rules: [
       {
         name: "zai-to-deepseek-flash",
@@ -76,15 +84,24 @@ 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)),
   };
 }
 
-export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>, "provider" | "id">, status: number): MatchedFallback | undefined {
+export function findFallback(
+  config: ModelFallbackConfig,
+  model: Pick<Model<any>, "provider" | "id">,
+  status: number,
+  reason?: string,
+): MatchedFallback | undefined {
   if (!config.enabled) return undefined;
   for (const rule of config.rules) {
     if (!statusesFor(rule).has(status)) continue;
     if (!modelMatches(rule, model)) continue;
+    if (!reasonMatches(rule, reason)) continue;
+    // Never "fall back" to the failing model itself; that would only re-trigger the same failure.
+    if (modelKey(model) === modelRefKey(rule.fallback)) continue;
     return { rule, fallback: rule.fallback };
   }
   return undefined;
@@ -104,17 +121,17 @@ export function analyzeRuleWarnings(config: ModelFallbackConfig): RuleWarning[]
       const earlierRule = config.rules[earlierIndex];
       const earlier = normalizedRules[earlierIndex];
 
-      if (setsEqual(earlier.statuses, later.statuses) && ruleScopesEqual(earlier, later)) {
+      if (setsEqual(earlier.statuses, later.statuses) && ruleScopesEqual(earlier, later) && reasonsEqual(earlier, later)) {
         warnings.push(duplicateRuleWarning(laterRule, ruleIndex, later, earlierRule, earlierIndex));
         continue rules;
       }
 
-      if (statusSetCovers(earlier.statuses, later.statuses) && ruleScopeCovers(earlier, later)) {
+      if (statusSetCovers(earlier.statuses, later.statuses) && ruleScopeCovers(earlier, later) && reasonsCover(earlier, later)) {
         warnings.push(scopeShadowWarning(laterRule, ruleIndex, later, earlierRule, earlierIndex, earlier));
         continue rules;
       }
 
-      if (earlier.providers.size === 0 || later.models.length === 0 || !statusSetCovers(earlier.statuses, later.statuses)) continue;
+      if (earlier.providers.size === 0 || later.models.length === 0 || !statusSetCovers(earlier.statuses, later.statuses) || !reasonsCover(earlier, later)) continue;
 
       const shadowedModels = later.models.filter((entry) => earlier.providers.has(entry.provider) && !reportedModelShadowKeys.has(modelRefKey(entry)));
       if (shadowedModels.length === 0) continue;
@@ -142,6 +159,7 @@ function validateRule(value: unknown, index: number): FallbackRule {
   if (value.matchProviders !== undefined) rule.matchProviders = readStringArray(value.matchProviders, `rules[${index}].matchProviders`);
   if (value.matchModels !== undefined) rule.matchModels = readModelRefArray(value.matchModels, `rules[${index}].matchModels`);
   if (value.statuses !== undefined) rule.statuses = readStatuses(value.statuses, `rules[${index}].statuses`);
+  if (value.reasons !== undefined) rule.reasons = readStringArray(value.reasons, `rules[${index}].reasons`);
   if (value.cooldownMs !== undefined) rule.cooldownMs = readPositiveInteger(value.cooldownMs, `rules[${index}].cooldownMs`);
   if ((!rule.matchProviders || rule.matchProviders.length === 0) && (!rule.matchModels || rule.matchModels.length === 0)) {
     throw new Error(`rules[${index}] must define matchProviders or matchModels.`);
@@ -155,6 +173,11 @@ function modelMatches(rule: FallbackRule, model: Pick<Model<any>, "provider" | "
   return false;
 }
 
+function reasonMatches(rule: FallbackRule, reason: string | undefined): boolean {
+  if (!rule.reasons || rule.reasons.length === 0) return true;
+  return reason !== undefined && rule.reasons.includes(reason);
+}
+
 function statusesFor(rule: FallbackRule): Set<number> {
   return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
 }
@@ -166,6 +189,7 @@ function normalizeRuleForWarnings(rule: FallbackRule): NormalizedRuleForWarnings
     modelKeys: new Set(modelsByKey.keys()),
     models: [...modelsByKey.values()],
     statuses: statusesFor(rule),
+    reasons: rule.reasons && rule.reasons.length > 0 ? new Set(rule.reasons) : undefined,
   };
 }
 
@@ -244,6 +268,17 @@ function statusSetCovers(earlier: Set<number>, later: Set<number>): boolean {
   return setCovers(earlier, later);
 }
 
+function reasonsCover(earlier: NormalizedRuleForWarnings, later: NormalizedRuleForWarnings): boolean {
+  if (earlier.reasons === undefined) return true;
+  if (later.reasons === undefined) return false;
+  return setCovers(earlier.reasons, later.reasons);
+}
+
+function reasonsEqual(earlier: NormalizedRuleForWarnings, later: NormalizedRuleForWarnings): boolean {
+  if (earlier.reasons === undefined || later.reasons === undefined) return earlier.reasons === later.reasons;
+  return setsEqual(earlier.reasons, later.reasons);
+}
+
 function setsEqual<T>(left: Set<T>, right: Set<T>): boolean {
   return left.size === right.size && setCovers(left, right);
 }
@@ -281,14 +316,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 +342,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,9 +1,36 @@
+const REASON_TEXT_PATTERNS: Array<[RegExp, string]> = [
+  [/exceeds\s+(?:this|the)\s+model'?s?\s+context\s+length/i, "context_length_exceeded"],
+  [/context[\s_-]*length[\s_-]*exceeded/i, "context_length_exceeded"],
+];
+
+export function parseReasonFromErrorMessage(message: string): string | undefined {
+  // Quoted machine-readable codes relayed by routers, for example
+  // "code":"context_length_exceeded" or "provider_error_code":"context_length_exceeded".
+  // Numeric "code":400 values are ignored; parseStatusFromErrorMessage handles the status.
+  const quoted = message.match(/"(?:[a-z0-9_]+_)?code"\s*:\s*"([a-z0-9_.:-]+)"/i);
+  if (quoted) return quoted[1];
+  for (const [pattern, reason] of REASON_TEXT_PATTERNS) {
+    if (pattern.test(message)) return reason;
+  }
+  return undefined;
+}
+
 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,
+    // Anchored "Error: <status> <prose>", e.g. "Error: 429 quota exceeded"
+    // (GitHub Copilot). The pattern above needs a colon AFTER the status and the
+    // "error <status>" pattern below needs whitespace directly after "error", so
+    // a message carrying both the prefix and a colon fell between them. The
+    // "error" prefix is required: without it this would also match prose such as
+    // "429 tokens remaining in context window", which must stay unmatched.
+    /^\s*error\s*:?\s*([1-5][0-9]{2})\b/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,
-    /\b([45][0-9]{2})\s+(?:error|too many requests|service unavailable|bad gateway|gateway timeout|internal server error)\b/i,
+    /\b([45][0-9]{2})\s+(?:error|quota|too many requests|service unavailable|bad gateway|gateway timeout|internal server error)\b/i,
     /\berror\s+([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.5.0",
   "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
   "type": "module",
   "license": "MIT",
@@ -50,12 +50,13 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.84.1",
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
-    "typebox": "latest",
+    "@earendil-works/pi-agent-core": "^0.86.1",
+    "@earendil-works/pi-ai": "^0.86.1",
+    "@earendil-works/pi-coding-agent": "^0.86.1",
+    "@earendil-works/pi-tui": "^0.86.1",
     "@types/node": "^26.0.0",
+    "jiti": "^2.7.0",
+    "typebox": "latest",
     "typescript": "^7.0.2"
   }
 }