pi-model-fallback 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,7 +1,18 @@
-# Changelog
-
+# Changelog
+
 ## Unreleased
 
+### 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.
+
+### Changed
+
+- Bump package version to `0.3.5` for the next patch release.
+
+- 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`.
 
 ## [0.3.3] - 2026-07-04
@@ -16,52 +27,51 @@
 
 - Publish only from release refs, print Node/npm versions, and publish with `--provenance --access public` so npm Trusted Publishing uses the same known-good path as `pi-spotify-widget`.
 - Release instructions now use `npm version patch --no-git-tag-version` so local tags do not race the auto-release workflow.
-
-## 0.3.0
-
-- Use `agent_start` for persistent preselect; `session_start` was not a Pi extension event.
-- Persist fallback state from assistant error messages on `turn_end`, covering provider SDK errors that do not emit `after_provider_response`.
-
-## 0.2.0
-
-- Add persistent failover state. A matching provider failure now writes `model-fallback/state.json`, and future sessions preselect the fallback model before the first provider call until the cooldown expires.
-- Parse retry/reset headers when available; otherwise default 429 cooldown to 72h and 5xx cooldown to 10m.
-- `/model-fallback:reset` now clears persistent state.
-
-All notable changes to this project will be documented in this file.
-
-This project follows semantic versioning.
-
-## [0.1.3] - 2026-06-19
-
-### Changed
-
-- CONTRIBUTING now reminds maintainers to run `npm pack --dry-run` after changing which `docs/` files ship in the package.
-
-### Fixed
-
-- README License section no longer ends with a literal `\n` placeholder.
-
-## [0.1.2] - 2026-06-04
-
-### Changed
-
-- README and `docs/template-checklist.md` now follow the Pi OSS minimal-docs policy: `docs/` is optional, with explicit post-generation cleanup for template bootstrap docs.
-- Template bootstrap docs (`github-template.md`, `repository-settings.md`, `typescript.md`) are labeled for delete-or-merge after setup.
-
-## [0.1.1] - 2026-06-01
-
-### Changed
-
-- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
-- 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
-
-### Added
-
-- Initial Pi package template.
-- Example extension, Agent Skill, prompt, and theme.
-- CI and npm Trusted Publishing workflow.
-
+
+## 0.3.0
+
+- Use `agent_start` for persistent preselect; `session_start` was not a Pi extension event.
+- Persist fallback state from assistant error messages on `turn_end`, covering provider SDK errors that do not emit `after_provider_response`.
+
+## 0.2.0
+
+- Add persistent failover state. A matching provider failure now writes `model-fallback/state.json`, and future sessions preselect the fallback model before the first provider call until the cooldown expires.
+- Parse retry/reset headers when available; otherwise default 429 cooldown to 72h and 5xx cooldown to 10m.
+- `/model-fallback:reset` now clears persistent state.
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.1.3] - 2026-06-19
+
+### Changed
+
+- CONTRIBUTING now reminds maintainers to run `npm pack --dry-run` after changing which `docs/` files ship in the package.
+
+### Fixed
+
+- README License section no longer ends with a literal `\n` placeholder.
+
+## [0.1.2] - 2026-06-04
+
+### Changed
+
+- README and `docs/template-checklist.md` now follow the Pi OSS minimal-docs policy: `docs/` is optional, with explicit post-generation cleanup for template bootstrap docs.
+- Template bootstrap docs (`github-template.md`, `repository-settings.md`, `typescript.md`) are labeled for delete-or-merge after setup.
+
+## [0.1.1] - 2026-06-01
+
+### Changed
+
+- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
+- 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
+
+### Added
+
+- Initial Pi package template.
+- Example extension, Agent Skill, prompt, and theme.
+- CI and npm Trusted Publishing workflow.

package/README.md

@@ -90,6 +90,17 @@ Rule fields:
 - `cooldownMs`: optional persistent fallback window
 - `fallback`: target model Pi should switch to
 
+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
+
+When a rule does not set `cooldownMs`, the extension uses these defaults:
+
+- `429` → 72 hours
+- `5xx` → 10 minutes
+
+When the provider response includes `Retry-After` or `x-ratelimit-reset*` headers, those values override `cooldownMs` and the defaults for the persisted fallback window.
+
 ## State and paths
 
 The extension stores:
@@ -103,7 +114,7 @@ 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.
+- 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.
 
 ## Development

package/docs/usage.md

@@ -3,7 +3,7 @@
 Install:
 
 ```bash
-pi install git:github.com/eiei114/pi-model-fallback
+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.
@@ -15,4 +15,13 @@ Commands:
 /model-fallback:reset
 ```
 
-The failed provider response is not automatically replayed in v0.1.0.
+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.
+
+Cooldown defaults when a rule omits `cooldownMs`:
+
+- `429` → 72 hours
+- `5xx` → 10 minutes
+
+`Retry-After` and `x-ratelimit-reset*` response headers override `cooldownMs` and those defaults.
+
+The failed request is not automatically replayed.

package/extensions/index.ts

@@ -1,9 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
+  analyzeRuleWarnings,
   defaultConfig,
   findFallback,
   modelKey,
@@ -11,8 +13,10 @@ import {
   validateConfigShape,
   type ModelFallbackConfig,
   type ModelRef,
+  type RuleWarning,
 } from "../lib/config.js";
-import { findActiveStateEntry, readState, upsertStateEntry, writeState, type FallbackState } from "../lib/state.js";
+import { parseStatusFromErrorMessage } from "../lib/error-status.js";
+import { emptyState, findActiveStateEntry, pruneExpiredState, readState, upsertStateEntry, validateStateShape, writeState, type FallbackState } from "../lib/state.js";
 import { modelFallbackPaths, readConfig, writeConfig, type ModelFallbackPaths } from "../lib/storage.js";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -22,6 +26,7 @@ const DEFAULT_5XX_COOLDOWN_MS = 10 * 60 * 1000;
 
 export default function modelFallback(pi: ExtensionAPI) {
   let paths: ModelFallbackPaths = modelFallbackPaths(getAgentDir());
+  let pathsResolvedForCwd: string | undefined;
   let config: ModelFallbackConfig | undefined;
   let state: FallbackState | undefined;
   let originalModelKey: string | undefined;
@@ -29,6 +34,8 @@ export default function modelFallback(pi: ExtensionAPI) {
   let lastFallbackReason: string | undefined;
 
   function syncPaths(ctx: ExtensionContext): void {
+    if (pathsResolvedForCwd === ctx.cwd) return;
+    pathsResolvedForCwd = ctx.cwd;
     paths = shouldUseProjectLocalState(ctx) ? modelFallbackPaths(join(ctx.cwd, ".pi")) : modelFallbackPaths(getAgentDir());
   }
 
@@ -46,8 +53,18 @@ export default function modelFallback(pi: ExtensionAPI) {
   async function loadState(ctx: ExtensionContext): Promise<FallbackState | undefined> {
     try {
       syncPaths(ctx);
-      state = await readState(paths.state);
-      await writeState(paths.state, state);
+      const statePath = paths.state;
+      if (!existsSync(statePath)) {
+        state = emptyState();
+        return state;
+      }
+
+      const before = validateStateShape(JSON.parse(await readFile(statePath, "utf8")));
+      const after = pruneExpiredState(before);
+      state = after;
+      if (JSON.stringify(before) !== JSON.stringify(after)) {
+        await writeState(statePath, after);
+      }
       return state;
     } catch (error) {
       ctx.ui.notify(`Model fallback state error: ${errorMessage(error)}`, "warning");
@@ -173,7 +190,7 @@ export default function modelFallback(pi: ExtensionAPI) {
     handler: async (_args, ctx) => {
       const loaded = config ?? (await loadConfig(ctx)) ?? defaultConfig();
       const loadedState = state ?? (await loadState(ctx)) ?? { version: 1 as const, entries: [] };
-      ctx.ui.notify(formatStatus(loaded, loadedState, paths.config, paths.state, activeFallbackKey, originalModelKey, lastFallbackReason), "info");
+      ctx.ui.notify(formatStatus(loaded, loadedState, paths.config, paths.state, analyzeRuleWarnings(loaded), activeFallbackKey, originalModelKey, lastFallbackReason), "info");
     },
   });
 
@@ -227,25 +244,24 @@ export default function modelFallback(pi: ExtensionAPI) {
       if (params.action === "read" || params.action === "status") {
         const current = await readConfig(paths.config);
         const currentState = await readState(paths.state);
-        return textResult(JSON.stringify(current, null, 2), {
-          configPath: paths.config,
-          statePath: paths.state,
-          state: currentState,
-          activeFallbackKey,
-          originalModelKey,
-          lastFallbackReason,
-        });
+        const warnings = analyzeRuleWarnings(current);
+        const details = configToolDetails(paths.config, paths.state, currentState, warnings, activeFallbackKey, originalModelKey, lastFallbackReason);
+        const text = params.action === "status"
+          ? formatStatus(current, currentState, paths.config, paths.state, warnings, activeFallbackKey, originalModelKey, lastFallbackReason)
+          : JSON.stringify(current, null, 2);
+        return textResult(text, details);
       }
       if (!params.configJson) throw new Error("configJson is required for validate/save.");
       const nextConfig = validateConfigShape(JSON.parse(params.configJson));
+      const warnings = analyzeRuleWarnings(nextConfig);
       validateRegisteredModels(ctx, nextConfig);
-      if (params.action === "validate") return textResult("Config is valid.", { config: nextConfig });
-      if (!ctx.hasUI) return textResult("Config not saved: confirmation UI is unavailable.", { configPath: paths.config });
-      const ok = await ctx.ui.confirm("Save model fallback config?", summarizeConfig(nextConfig));
-      if (!ok) return textResult("Config not saved.", { configPath: paths.config });
+      if (params.action === "validate") return textResult(configResultText("Config is valid.", warnings), { config: nextConfig, ...warningDetails(warnings) });
+      if (!ctx.hasUI) return textResult("Config not saved: confirmation UI is unavailable.", { configPath: paths.config, ...warningDetails(warnings) });
+      const ok = await ctx.ui.confirm("Save model fallback config?", summarizeConfig(nextConfig, warnings));
+      if (!ok) return textResult("Config not saved.", { configPath: paths.config, ...warningDetails(warnings) });
       await writeConfig(paths.config, nextConfig);
       config = nextConfig;
-      return textResult("Config saved.", { configPath: paths.config });
+      return textResult(configResultText("Config saved.", warnings), { configPath: paths.config, ...warningDetails(warnings) });
     },
   });
 }
@@ -284,6 +300,7 @@ function formatStatus(
   state: FallbackState,
   configPath: string,
   statePath: string,
+  warnings: RuleWarning[],
   activeFallbackKey?: string,
   originalModelKey?: string,
   reason?: string,
@@ -293,6 +310,7 @@ function formatStatus(
     `Config: ${configPath}`,
     `State: ${statePath}`,
     `Rules: ${config.rules.length}`,
+    `Config warnings: ${warningSummary(warnings)}`,
     `Persistent entries: ${state.entries.length}`,
     ...state.entries.map((entry) => `- ${modelRefKey(entry.source)} -> ${modelRefKey(entry.fallback)} until ${entry.until} (${entry.status})`),
     `Active fallback: ${activeFallbackKey ?? "none"}`,
@@ -301,13 +319,53 @@ function formatStatus(
   ].join("\n");
 }
 
-function summarizeConfig(config: ModelFallbackConfig): string {
+function summarizeConfig(config: ModelFallbackConfig, warnings: RuleWarning[]): string {
   return [
     `enabled: ${config.enabled}`,
     ...config.rules.map((rule) => `${rule.name ?? "rule"}: ${rule.matchProviders?.join(",") ?? "models"} -> ${modelRefKey(rule.fallback)}`),
+    `warnings: ${warningSummary(warnings)}`,
   ].join("\n");
 }
 
+function configToolDetails(
+  configPath: string,
+  statePath: string,
+  state: FallbackState,
+  warnings: RuleWarning[],
+  activeFallbackKey?: string,
+  originalModelKey?: string,
+  lastFallbackReason?: string,
+): Record<string, unknown> {
+  return {
+    configPath,
+    statePath,
+    state,
+    activeFallbackKey,
+    originalModelKey,
+    lastFallbackReason,
+    ...warningDetails(warnings),
+  };
+}
+
+function warningDetails(warnings: RuleWarning[]): Record<string, unknown> {
+  return {
+    warningCount: warnings.length,
+    warningSummary: warningSummary(warnings),
+    warnings,
+  };
+}
+
+function configResultText(prefix: string, warnings: RuleWarning[]): string {
+  if (warnings.length === 0) return prefix;
+  return `${prefix} ${warningSummary(warnings)}`;
+}
+
+function warningSummary(warnings: RuleWarning[]): string {
+  if (warnings.length === 0) return "none";
+  if (warnings.length === 1) return `1 warning: ${warnings[0].message}`;
+  return `${warnings.length} warnings: ${warnings.map((warning) => warning.message).join("; ")}`;
+}
+
 function textResult(text: string, details?: Record<string, unknown>) {
   return { content: [{ type: "text" as const, text }], details: details ?? {} };
 }
@@ -343,7 +401,7 @@ function parseRetryAfter(value: string | undefined): number | undefined {
   return undefined;
 }
 
-function parseResetHeader(value: string | undefined): number | undefined {
+function parseResetHeader(value: string | undefined): number | undefined {
   if (!value) return undefined;
   const trimmed = value.trim();
   const numeric = Number(trimmed);
@@ -354,17 +412,10 @@ function parseResetHeader(value: string | undefined): number | undefined {
   }
   const dateMs = Date.parse(trimmed);
   if (!Number.isNaN(dateMs) && dateMs > Date.now()) return dateMs - Date.now();
-  return undefined;
-}
-
-function parseStatusFromErrorMessage(message: string): number | undefined {
-  const match = message.match(/\b([1-5][0-9]{2})\b/);
-  if (!match) return undefined;
-  const status = Number(match[1]);
-  return Number.isInteger(status) ? status : undefined;
-}
-
-function modelToRef(model: { provider: string; id: string }): ModelRef {
+  return undefined;
+}
+
+function modelToRef(model: { provider: string; id: string }): ModelRef {
   return { provider: model.provider, model: model.id };
 }
 

package/lib/config.ts

@@ -29,6 +29,28 @@ export interface MatchedFallback {
   fallback: ModelRef;
 }
 
+export type RuleWarningCode = "provider_rule_shadows_model" | "shadowed_rule" | "duplicate_rule";
+
+export interface RuleWarning {
+  severity: "warning";
+  code: RuleWarningCode;
+  message: string;
+  ruleIndex: number;
+  ruleName?: string;
+  shadowedByRuleIndex: number;
+  shadowedByRuleName?: string;
+  statuses: number[];
+  matchProviders?: string[];
+  matchModels?: ModelRef[];
+}
+
+interface NormalizedRuleForWarnings {
+  providers: Set<string>;
+  modelKeys: Set<string>;
+  models: ModelRef[];
+  statuses: Set<number>;
+}
+
 export function defaultConfig(): ModelFallbackConfig {
   return {
     version: CONFIG_VERSION,
@@ -68,6 +90,43 @@ export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>
   return undefined;
 }
 
+export function analyzeRuleWarnings(config: ModelFallbackConfig): RuleWarning[] {
+  const normalizedRules = config.rules.map((rule) => normalizeRuleForWarnings(rule));
+  const warnings: RuleWarning[] = [];
+
+  rules:
+  for (let ruleIndex = 1; ruleIndex < config.rules.length; ruleIndex += 1) {
+    const laterRule = config.rules[ruleIndex];
+    const later = normalizedRules[ruleIndex];
+    const reportedModelShadowKeys = new Set<string>();
+
+    for (let earlierIndex = 0; earlierIndex < ruleIndex; earlierIndex += 1) {
+      const earlierRule = config.rules[earlierIndex];
+      const earlier = normalizedRules[earlierIndex];
+
+      if (setsEqual(earlier.statuses, later.statuses) && ruleScopesEqual(earlier, later)) {
+        warnings.push(duplicateRuleWarning(laterRule, ruleIndex, later, earlierRule, earlierIndex));
+        continue rules;
+      }
+
+      if (statusSetCovers(earlier.statuses, later.statuses) && ruleScopeCovers(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;
+
+      const shadowedModels = later.models.filter((entry) => earlier.providers.has(entry.provider) && !reportedModelShadowKeys.has(modelRefKey(entry)));
+      if (shadowedModels.length === 0) continue;
+      for (const entry of shadowedModels) reportedModelShadowKeys.add(modelRefKey(entry));
+
+      warnings.push(providerModelShadowWarning(laterRule, ruleIndex, later, earlierRule, earlierIndex, shadowedModels));
+    }
+  }
+
+  return warnings;
+}
+
 export function modelRefKey(ref: ModelRef): string {
   return `${ref.provider}/${ref.model}`;
 }
@@ -100,6 +159,128 @@ function statusesFor(rule: FallbackRule): Set<number> {
   return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
 }
 
+function normalizeRuleForWarnings(rule: FallbackRule): NormalizedRuleForWarnings {
+  const modelsByKey = new Map((rule.matchModels ?? []).map((entry) => [modelRefKey(entry), entry]));
+  return {
+    providers: new Set(rule.matchProviders ?? []),
+    modelKeys: new Set(modelsByKey.keys()),
+    models: [...modelsByKey.values()],
+    statuses: statusesFor(rule),
+  };
+}
+
+function ruleScopesEqual(left: NormalizedRuleForWarnings, right: NormalizedRuleForWarnings): boolean {
+  return setsEqual(left.providers, right.providers) && setsEqual(left.modelKeys, right.modelKeys);
+}
+
+function ruleScopeCovers(earlier: NormalizedRuleForWarnings, later: NormalizedRuleForWarnings): boolean {
+  return setCovers(earlier.providers, later.providers) && later.models.every((entry) => earlier.providers.has(entry.provider) || earlier.modelKeys.has(modelRefKey(entry)));
+}
+
+function duplicateRuleWarning(laterRule: FallbackRule, ruleIndex: number, later: NormalizedRuleForWarnings, earlierRule: FallbackRule, earlierIndex: number): RuleWarning {
+  return {
+    severity: "warning",
+    code: "duplicate_rule",
+    message: `${ruleLabel(laterRule, ruleIndex)} is shadowed by ${ruleLabel(earlierRule, earlierIndex)} because both rules match the same providers/models and statuses; the earlier rule wins first.`,
+    ruleIndex,
+    ruleName: laterRule.name,
+    shadowedByRuleIndex: earlierIndex,
+    shadowedByRuleName: earlierRule.name,
+    statuses: sortedNumbers(later.statuses),
+    matchProviders: sortedStrings(later.providers),
+    matchModels: sortedModels(later.models),
+  };
+}
+
+function scopeShadowWarning(
+  laterRule: FallbackRule,
+  ruleIndex: number,
+  later: NormalizedRuleForWarnings,
+  earlierRule: FallbackRule,
+  earlierIndex: number,
+  earlier: NormalizedRuleForWarnings,
+): RuleWarning {
+  const providerCoveredModels = later.models.filter((entry) => earlier.providers.has(entry.provider));
+  const allModelsProviderCovered = later.providers.size === 0 && later.models.length > 0 && providerCoveredModels.length === later.models.length;
+  if (allModelsProviderCovered) return providerModelShadowWarning(laterRule, ruleIndex, later, earlierRule, earlierIndex, providerCoveredModels);
+
+  return {
+    severity: "warning",
+    code: "shadowed_rule",
+    message: `${ruleLabel(laterRule, ruleIndex)} is shadowed by ${ruleLabel(earlierRule, earlierIndex)} because the earlier rule covers its provider/model scope and statuses; the earlier rule wins first.`,
+    ruleIndex,
+    ruleName: laterRule.name,
+    shadowedByRuleIndex: earlierIndex,
+    shadowedByRuleName: earlierRule.name,
+    statuses: sortedNumbers(later.statuses),
+    matchProviders: sortedStrings(later.providers),
+    matchModels: sortedModels(later.models),
+  };
+}
+
+function providerModelShadowWarning(
+  laterRule: FallbackRule,
+  ruleIndex: number,
+  later: NormalizedRuleForWarnings,
+  earlierRule: FallbackRule,
+  earlierIndex: number,
+  shadowedModels: ModelRef[],
+): RuleWarning {
+  return {
+    severity: "warning",
+    code: "provider_rule_shadows_model",
+    message: `${ruleLabel(laterRule, ruleIndex)} has model match ${formatModelList(shadowedModels)} shadowed by ${ruleLabel(earlierRule, earlierIndex)} for statuses ${formatStatusList(later.statuses)}; the earlier provider-wide rule wins first.`,
+    ruleIndex,
+    ruleName: laterRule.name,
+    shadowedByRuleIndex: earlierIndex,
+    shadowedByRuleName: earlierRule.name,
+    statuses: sortedNumbers(later.statuses),
+    matchProviders: sortedStrings(new Set(shadowedModels.map((entry) => entry.provider))),
+    matchModels: sortedModels(shadowedModels),
+  };
+}
+
+function statusSetCovers(earlier: Set<number>, later: Set<number>): boolean {
+  return setCovers(earlier, later);
+}
+
+function setsEqual<T>(left: Set<T>, right: Set<T>): boolean {
+  return left.size === right.size && setCovers(left, right);
+}
+
+function setCovers<T>(earlier: Set<T>, later: Set<T>): boolean {
+  for (const value of later) {
+    if (!earlier.has(value)) return false;
+  }
+  return true;
+}
+
+function sortedNumbers(values: Set<number>): number[] {
+  return [...values].sort((left, right) => left - right);
+}
+
+function sortedStrings(values: Set<string>): string[] | undefined {
+  const sorted = [...values].sort();
+  return sorted.length > 0 ? sorted : undefined;
+}
+
+function sortedModels(models: ModelRef[]): ModelRef[] | undefined {
+  const sorted = [...new Map(models.map((entry) => [modelRefKey(entry), entry])).values()].sort((left, right) => modelRefKey(left).localeCompare(modelRefKey(right)));
+  return sorted.length > 0 ? sorted : undefined;
+}
+
+function ruleLabel(rule: FallbackRule, index: number): string {
+  return rule.name ? `rules[${index}] (${rule.name})` : `rules[${index}]`;
+}
+
+function formatStatusList(statuses: Set<number>): string {
+  return sortedNumbers(statuses).join(", ");
+}
+
+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 {
@@ -129,10 +310,10 @@ function readStatuses(value: unknown, path: string): number[] {
   });
 }
 
-function readPositiveInteger(value: unknown, path: string): number {
-  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new Error(`${path} must be a positive integer.`);
-  return value;
-}
+function readPositiveInteger(value: unknown, path: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new Error(`${path} must be a positive integer.`);
+  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.`);

package/lib/error-status.ts

@@ -0,0 +1,18 @@
+export function parseStatusFromErrorMessage(message: string): number | undefined {
+  const patterns: RegExp[] = [
+    /\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,
+    /\berror\s+([45][0-9]{2})\b/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = message.match(pattern);
+    if (!match) continue;
+    const status = Number(match[1]);
+    if (Number.isInteger(status) && status >= 100 && status <= 599) return status;
+  }
+
+  return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-model-fallback",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
   "type": "module",
   "license": "MIT",
@@ -43,15 +43,17 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "latest",
-    "@earendil-works/pi-coding-agent": "latest",
-    "@earendil-works/pi-tui": "latest",
+    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
     "typebox": "latest",
     "@types/node": "^26.0.0",
     "typescript": "^6.0.3"