pi-model-fallback 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -1,10 +1,16 @@
-# 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.4` for the next patch release.
+- 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`.
@@ -21,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

@@ -1,5 +1,7 @@
 # pi-model-fallback
 
+[![Join dotfield.xyz on Discord](https://img.shields.io/badge/Join%20dotfield.xyz%20on%20Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4945dXZVW5)
+
 [![CI](https://github.com/eiei114/pi-model-fallback/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-model-fallback/actions/workflows/ci.yml)
 [![Publish](https://github.com/eiei114/pi-model-fallback/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-model-fallback/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pi-model-fallback.svg)](https://www.npmjs.com/package/pi-model-fallback)
@@ -90,6 +92,8 @@ 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:
@@ -137,4 +141,4 @@ pi -e .
 
 ## License
 
-MIT
+MIT

package/docs/usage.md

@@ -15,6 +15,8 @@ Commands:
 /model-fallback:reset
 ```
 
+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

package/extensions/index.ts

@@ -5,6 +5,7 @@ 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,
@@ -12,6 +13,7 @@ import {
   validateConfigShape,
   type ModelFallbackConfig,
   type ModelRef,
+  type RuleWarning,
 } 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";
@@ -188,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");
     },
   });
 
@@ -242,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) });
     },
   });
 }
@@ -299,6 +300,7 @@ function formatStatus(
   state: FallbackState,
   configPath: string,
   statePath: string,
+  warnings: RuleWarning[],
   activeFallbackKey?: string,
   originalModelKey?: string,
   reason?: string,
@@ -308,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"}`,
@@ -316,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 ?? {} };
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-model-fallback",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
   "type": "module",
   "license": "MIT",
@@ -50,12 +50,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-agent-core": "^0.83.0",
     "@earendil-works/pi-ai": "^0.80.6",
-    "@earendil-works/pi-coding-agent": "^0.80.6",
-    "@earendil-works/pi-tui": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-tui": "^0.83.0",
     "typebox": "latest",
     "@types/node": "^26.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   }
 }