pi-model-fallback 0.1.0 → 0.3.3

package/CHANGELOG.md

@@ -1,38 +1,67 @@
-# Changelog
+# Changelog
+
+## Unreleased
 
-All notable changes to this project will be documented in this file.
+- Add Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
 
-This project follows semantic versioning.
-
-## [0.1.3] - 2026-06-19
+## [0.3.3] - 2026-07-04
 
 ### 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
+- Rewrite the README with real `pi-model-fallback` install, command, configuration, and state-path documentation instead of template placeholders.
 
-- 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.3.2] - 2026-07-04
 
-## [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
+### Fixed
 
-- Initial Pi package template.
-- Example extension, Agent Skill, prompt, and theme.
-- CI and npm Trusted Publishing workflow.
+- 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.
+

package/README.md

@@ -1,88 +1,110 @@
-# PACKAGE_DISPLAY_NAME
+# pi-model-fallback
 
-[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
-[![Publish](https://github.com/OWNER/REPO/actions/workflows/publish.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/publish.yml)
-[![npm version](https://img.shields.io/npm/v/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
-[![npm downloads](https://img.shields.io/npm/dm/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
+[![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)
+[![npm downloads](https://img.shields.io/npm/dm/pi-model-fallback.svg)](https://www.npmjs.com/package/pi-model-fallback)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
-[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
 
-> One-line pitch for this TypeScript-first Pi package.
+> Pi extension that switches to a fallback model after provider failures such as 429 rate limits.
 
-## What this is
+## What this does
 
-Briefly explain what this TypeScript-first package adds to Pi and who should use it.
+`pi-model-fallback` watches provider failures and automatically moves Pi to a safer fallback model when a matching rule fires.
 
-## Features
+Current default:
 
-- Feature 1
-- Feature 2
-- Feature 3
+- source provider: `zai`
+- matching statuses: `429`, `500`, `502`, `503`, `504`
+- fallback model: `deepseek/deepseek-v4-flash`
+
+When a failure matches, the extension also stores persistent fallback state so future sessions can preselect the fallback model until the cooldown expires.
 
 ## Install
 
-Install the published npm package with Pi:
+Install from npm:
 
 ```bash
-pi install npm:PACKAGE_NAME
+pi install npm:pi-model-fallback
 ```
 
-Replace `PACKAGE_NAME` with the exact `name` from `package.json`.
-For a scoped npm package, keep the `npm:` prefix:
+Install into the current project only:
 
 ```bash
-pi install npm:@your-scope/your-pi-package
+pi install npm:pi-model-fallback -l
 ```
 
-Pin a specific version when you want reproducible installs:
+Or install from GitHub:
 
 ```bash
-pi install npm:PACKAGE_NAME@0.1.0
+pi install git:github.com/eiei114/pi-model-fallback
 ```
 
-Install into the current project instead of your user Pi settings:
+Try it without permanently installing:
 
 ```bash
-pi install npm:PACKAGE_NAME -l
+pi -e npm:pi-model-fallback
 ```
 
-Or install from GitHub:
+## Commands
 
-```bash
-pi install git:github.com/OWNER/REPO
+```text
+/model-fallback:status
+/model-fallback:reset
 ```
 
-Try it without permanently installing:
-
-```bash
-pi -e npm:PACKAGE_NAME
+- `status`: shows whether fallback is enabled, active persistent entries, and current paths
+- `reset`: clears persistent fallback state and switches back to the remembered original model when possible
+
+## Configuration
+
+The extension exposes the `model_fallback_config` tool for reading, validating, and saving config JSON.
+
+Default config shape:
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "rules": [
+    {
+      "name": "zai-to-deepseek-flash",
+      "matchProviders": ["zai"],
+      "statuses": [429, 500, 502, 503, 504],
+      "fallback": {
+        "provider": "deepseek",
+        "model": "deepseek-v4-flash"
+      }
+    }
+  ]
+}
 ```
 
-## Quick start
+Rule fields:
 
-Try this package locally:
+- `matchProviders`: match all models from a provider
+- `matchModels`: match specific `provider` + `model` pairs
+- `statuses`: optional; defaults to `429, 500, 502, 503, 504`
+- `cooldownMs`: optional persistent fallback window
+- `fallback`: target model Pi should switch to
 
-```bash
-pi -e .
-```
+## State and paths
 
-Then run:
+The extension stores:
 
-```txt
-/your-command
-```
+- config: `model-fallback/config.json`
+- state: `model-fallback/state.json`
 
-## Package contents
+If the package is installed project-locally and the current project references it from `.pi/settings.json`, those files live under the project `.pi/` directory. Otherwise they live under the user agent directory.
 
-| Path | Purpose |
-|---|---|
-| `extensions/` | Pi TypeScript extension entrypoints (`*.ts` and `index.ts`) |
-| `lib/` | Shared TypeScript helpers |
-| `skills/` | Agent Skills |
-| `prompts/` | Prompt templates |
-| `themes/` | Pi themes |
-| `docs/` | Optional supporting docs (usage, examples, release, ADRs) |
+## Behavior notes
+
+- 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.
+- The failed request is not automatically replayed.
 
 ## Development
 
@@ -91,72 +113,18 @@ npm install
 npm run ci
 ```
 
-## Development flow
-
-Use this default flow when building a new Pi extension OSS project from this template:
-
-1. Create the Vault project notes under `4_Project/<ProjectName>/`.
-2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
-3. Write the PRD in `4_Project/<ProjectName>/Docs/`.
-4. Split approved tracer-bullet issues into `4_Project/<ProjectName>/Issues/`.
-5. Implement in the OSS repo.
-6. Run `npm run ci`, `npm test`, and `npm pack --dry-run`.
-7. Release with Trusted Publishing.
-8. Save release notes and follow-up decisions back to the Vault project.
-
-Short version:
-
-```txt
-Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
-```
-
-## Release
-
-This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
+Run locally in Pi:
 
 ```bash
-npm version patch
-git push
+pi -e .
 ```
 
-See [`docs/release.md`](docs/release.md) for setup details.
-
-## Docs
-
-`docs/` is optional supporting documentation, not a fixed six-file set. README stays the GitHub/npm entrypoint; add `docs/*.md` only when they help users or maintainers.
-
-After creating a repository from this template:
-
-1. Follow [`docs/template-checklist.md`](docs/template-checklist.md) for setup.
-2. Run the **post-generation docs cleanup** in that checklist: delete or merge template bootstrap docs that no longer add project value.
-
-Useful docs to keep when they add value:
-
-- [`docs/examples.md`](docs/examples.md) — examples for extensions, skills, prompts, and themes
-- [`docs/release.md`](docs/release.md) — Trusted Publishing details (README Release summarizes the flow)
-- `docs/usage.md` — create when usage does not fit in README
-
-Optional maintainer guidance (not a public-user navigation target in mature repos):
-
-- [`docs/template-checklist.md`](docs/template-checklist.md)
-
-Template bootstrap docs to delete or merge after setup unless they still teach something project-specific:
-
-- `docs/github-template.md`
-- `docs/repository-settings.md`
-- `docs/typescript.md`
-
-## Security
-
-Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
-
-For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
-
 ## Links
 
-- npm: https://www.npmjs.com/package/PACKAGE_NAME
-- GitHub: https://github.com/OWNER/REPO
-- Issues: https://github.com/OWNER/REPO/issues
+- npm: https://www.npmjs.com/package/pi-model-fallback
+- GitHub: https://github.com/eiei114/pi-model-fallback
+- Issues: https://github.com/eiei114/pi-model-fallback/issues
+- Usage notes: [`docs/usage.md`](docs/usage.md)
 
 ## License
 

package/extensions/index.ts

@@ -3,15 +3,27 @@ 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 { defaultConfig, findFallback, modelKey, modelRefKey, validateConfigShape, type ModelFallbackConfig } from "../lib/config.js";
+import {
+  defaultConfig,
+  findFallback,
+  modelKey,
+  modelRefKey,
+  validateConfigShape,
+  type ModelFallbackConfig,
+  type ModelRef,
+} from "../lib/config.js";
+import { findActiveStateEntry, readState, upsertStateEntry, 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)));
 const STATUS_KEY = "model-fallback";
+const DEFAULT_429_COOLDOWN_MS = 72 * 60 * 60 * 1000;
+const DEFAULT_5XX_COOLDOWN_MS = 10 * 60 * 1000;
 
 export default function modelFallback(pi: ExtensionAPI) {
   let paths: ModelFallbackPaths = modelFallbackPaths(getAgentDir());
   let config: ModelFallbackConfig | undefined;
+  let state: FallbackState | undefined;
   let originalModelKey: string | undefined;
   let activeFallbackKey: string | undefined;
   let lastFallbackReason: string | undefined;
@@ -31,12 +43,95 @@ 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);
+      return state;
+    } catch (error) {
+      ctx.ui.notify(`Model fallback state error: ${errorMessage(error)}`, "warning");
+      return undefined;
+    }
+  }
+
   function updateStatus(ctx: ExtensionContext): void {
     ctx.ui.setStatus(STATUS_KEY, activeFallbackKey ? `fallback:${activeFallbackKey}` : undefined);
   }
 
-  pi.on("session_start", async (_event, ctx) => {
+  async function applyPersistentFallback(ctx: ExtensionContext): Promise<void> {
+    const current = ctx.model;
+    if (!current) return;
+    const loadedConfig = config ?? (await loadConfig(ctx));
+    if (!loadedConfig?.enabled) return;
+    const loadedState = state ?? (await loadState(ctx));
+    if (!loadedState) return;
+
+    const active = findActiveStateEntry(loadedState, modelToRef(current));
+    if (!active) return;
+
+    const fallbackModel = ctx.modelRegistry.find(active.fallback.provider, active.fallback.model);
+    if (!fallbackModel) {
+      ctx.ui.notify(`Model fallback state target missing: ${modelRefKey(active.fallback)}`, "warning");
+      return;
+    }
+
+    const ok = await pi.setModel(fallbackModel);
+    if (!ok) {
+      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(active.fallback)}`, "warning");
+      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> {
+    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;
+
+    const fallbackModel = ctx.modelRegistry.find(match.fallback.provider, match.fallback.model);
+    if (!fallbackModel) {
+      ctx.ui.notify(`Model fallback missing: ${modelRefKey(match.fallback)}`, "warning");
+      return;
+    }
+
+    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: [] };
+    state = upsertStateEntry(loadedState, {
+      source,
+      fallback: match.fallback,
+      status,
+      until,
+      createdAt: now.toISOString(),
+      ruleName: match.rule.name,
+    });
+    await writeState(paths.state, state);
+
+    const ok = await pi.setModel(fallbackModel);
+    if (!ok) {
+      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
+      return;
+    }
+
+    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");
+  }
+
+  pi.on("agent_start", async (_event, ctx) => {
     await loadConfig(ctx);
+    await loadState(ctx);
+    await applyPersistentFallback(ctx);
     updateStatus(ctx);
   });
 
@@ -56,41 +151,43 @@ export default function modelFallback(pi: ExtensionAPI) {
     if (event.status >= 200 && event.status < 300) return;
     if (activeFallbackKey && modelKey(current) === activeFallbackKey) return;
 
-    const match = findFallback(loaded, current, event.status);
-    if (!match) return;
-
-    const fallbackModel = ctx.modelRegistry.find(match.fallback.provider, match.fallback.model);
-    if (!fallbackModel) {
-      ctx.ui.notify(`Model fallback missing: ${modelRefKey(match.fallback)}`, "warning");
-      return;
-    }
-
-    const ok = await pi.setModel(fallbackModel);
-    if (!ok) {
-      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
-      return;
-    }
+    await persistFailure(modelToRef(current), event.status, event.headers, ctx);
+  });
 
-    originalModelKey = modelKey(current);
-    activeFallbackKey = modelRefKey(match.fallback);
-    lastFallbackReason = `${event.status} from ${originalModelKey}`;
-    updateStatus(ctx);
-    ctx.ui.notify(`Model fallback: ${originalModelKey} → ${activeFallbackKey} (${event.status}). Re-run the prompt to use fallback.`, "warning");
+  pi.on("turn_end", async (event, ctx) => {
+    const message = event.message as unknown;
+    if (!isRecord(message) || message.role !== "assistant") return;
+    const errorMessage = typeof message.errorMessage === "string" ? message.errorMessage : undefined;
+    if (!errorMessage) return;
+    const status = parseStatusFromErrorMessage(errorMessage);
+    if (status === undefined) return;
+    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);
   });
 
   pi.registerCommand("model-fallback:status", {
     description: "Show model fallback status",
     handler: async (_args, ctx) => {
       const loaded = config ?? (await loadConfig(ctx)) ?? defaultConfig();
-      ctx.ui.notify(formatStatus(loaded, paths.config, activeFallbackKey, originalModelKey, lastFallbackReason), "info");
+      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");
     },
   });
 
   pi.registerCommand("model-fallback:reset", {
-    description: "Return from fallback model to the pre-fallback model when remembered",
+    description: "Return from fallback model to the pre-fallback model when remembered and clear persistent state",
     handler: async (_args, ctx) => {
+      syncPaths(ctx);
+      state = { version: 1, entries: [] };
+      await writeState(paths.state, state);
       if (!originalModelKey) {
-        ctx.ui.notify("Model fallback: no remembered original model.", "info");
+        ctx.ui.notify("Model fallback: persistent state cleared; no remembered original model.", "info");
+        activeFallbackKey = undefined;
+        lastFallbackReason = undefined;
+        updateStatus(ctx);
         return;
       }
       const [provider, ...modelParts] = originalModelKey.split("/");
@@ -108,7 +205,7 @@ export default function modelFallback(pi: ExtensionAPI) {
       originalModelKey = undefined;
       lastFallbackReason = undefined;
       updateStatus(ctx);
-      ctx.ui.notify(`Model fallback reset: ${modelKey(model)}`, "info");
+      ctx.ui.notify(`Model fallback reset: ${modelKey(model)}; persistent state cleared.`, "info");
     },
   });
 
@@ -129,7 +226,15 @@ export default function modelFallback(pi: ExtensionAPI) {
       syncPaths(ctx);
       if (params.action === "read" || params.action === "status") {
         const current = await readConfig(paths.config);
-        return textResult(JSON.stringify(current, null, 2), { configPath: paths.config, activeFallbackKey, originalModelKey, lastFallbackReason });
+        const currentState = await readState(paths.state);
+        return textResult(JSON.stringify(current, null, 2), {
+          configPath: paths.config,
+          statePath: paths.state,
+          state: currentState,
+          activeFallbackKey,
+          originalModelKey,
+          lastFallbackReason,
+        });
       }
       if (!params.configJson) throw new Error("configJson is required for validate/save.");
       const nextConfig = validateConfigShape(JSON.parse(params.configJson));
@@ -174,11 +279,22 @@ function validateRegisteredModels(ctx: ExtensionContext, nextConfig: ModelFallba
   }
 }
 
-function formatStatus(config: ModelFallbackConfig, configPath: string, activeFallbackKey?: string, originalModelKey?: string, reason?: string): string {
+function formatStatus(
+  config: ModelFallbackConfig,
+  state: FallbackState,
+  configPath: string,
+  statePath: string,
+  activeFallbackKey?: string,
+  originalModelKey?: string,
+  reason?: string,
+): string {
   return [
     `Model fallback: ${config.enabled ? "enabled" : "disabled"}`,
     `Config: ${configPath}`,
+    `State: ${statePath}`,
     `Rules: ${config.rules.length}`,
+    `Persistent entries: ${state.entries.length}`,
+    ...state.entries.map((entry) => `- ${modelRefKey(entry.source)} -> ${modelRefKey(entry.fallback)} until ${entry.until} (${entry.status})`),
     `Active fallback: ${activeFallbackKey ?? "none"}`,
     `Original model: ${originalModelKey ?? "none"}`,
     `Reason: ${reason ?? "none"}`,
@@ -196,6 +312,62 @@ function textResult(text: string, details?: Record<string, unknown>) {
   return { content: [{ type: "text" as const, text }], details: details ?? {} };
 }
 
+function cooldownMsFor(ruleCooldownMs: number | undefined, status: number, headers: Record<string, string>): number {
+  const headerMs = cooldownMsFromHeaders(headers);
+  if (headerMs !== undefined) return headerMs;
+  if (ruleCooldownMs !== undefined) return ruleCooldownMs;
+  if (status === 429) return DEFAULT_429_COOLDOWN_MS;
+  if (status >= 500 && status <= 599) return DEFAULT_5XX_COOLDOWN_MS;
+  return DEFAULT_5XX_COOLDOWN_MS;
+}
+
+function cooldownMsFromHeaders(headers: Record<string, string>): number | undefined {
+  const normalized = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+  const retryAfter = parseRetryAfter(normalized["retry-after"]);
+  if (retryAfter !== undefined) return retryAfter;
+
+  for (const name of ["x-ratelimit-reset", "x-ratelimit-reset-requests", "x-ratelimit-reset-tokens", "ratelimit-reset", "x-rate-limit-reset"]) {
+    const parsed = parseResetHeader(normalized[name]);
+    if (parsed !== undefined) return parsed;
+  }
+  return undefined;
+}
+
+function parseRetryAfter(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds * 1000);
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs) && dateMs > Date.now()) return dateMs - Date.now();
+  return undefined;
+}
+
+function parseResetHeader(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const numeric = Number(trimmed);
+  if (Number.isFinite(numeric) && numeric > 0) {
+    if (numeric > 1_000_000_000_000) return Math.max(0, numeric - Date.now());
+    if (numeric > 1_000_000_000) return Math.max(0, numeric * 1000 - Date.now());
+    return Math.ceil(numeric * 1000);
+  }
+  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 { provider: model.provider, model: model.id };
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/lib/config.ts

@@ -1,136 +1,144 @@
-import type { Model } from "@earendil-works/pi-ai";
-
-export const CONFIG_VERSION = 1;
-export const DEFAULT_FALLBACK_STATUSES = [429, 500, 502, 503, 504] as const;
-
-export interface ModelRef {
-  provider: string;
-  model: string;
-}
-
-export interface FallbackRule {
-  name?: string;
-  matchProviders?: string[];
-  matchModels?: ModelRef[];
-  statuses?: number[];
-  fallback: ModelRef;
-}
-
-export interface ModelFallbackConfig {
-  version: 1;
-  enabled: boolean;
-  rules: FallbackRule[];
-}
-
-export interface MatchedFallback {
-  rule: FallbackRule;
-  fallback: ModelRef;
-}
-
-export function defaultConfig(): ModelFallbackConfig {
-  return {
-    version: CONFIG_VERSION,
-    enabled: true,
-    rules: [
-      {
-        name: "zai-to-deepseek-flash",
-        matchProviders: ["zai"],
-        statuses: [...DEFAULT_FALLBACK_STATUSES],
-        fallback: { provider: "deepseek", model: "deepseek-v4-flash" },
-      },
-    ],
-  };
-}
-
-export function validateConfigShape(value: unknown): ModelFallbackConfig {
-  if (!isRecord(value)) throw new Error("Config must be an object.");
-  if (value.version !== CONFIG_VERSION) throw new Error(`Unsupported config version: ${String(value.version)}.`);
-  const enabled = typeof value.enabled === "boolean" ? value.enabled : true;
-  if (!Array.isArray(value.rules)) throw new Error("rules must be an array.");
-  if (value.rules.length === 0) throw new Error("rules must include at least one fallback rule.");
-
-  return {
-    version: CONFIG_VERSION,
-    enabled,
-    rules: value.rules.map((ruleValue, index) => validateRule(ruleValue, index)),
-  };
-}
-
-export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>, "provider" | "id">, status: number): MatchedFallback | undefined {
-  if (!config.enabled) return undefined;
-  for (const rule of config.rules) {
-    if (!statusesFor(rule).has(status)) continue;
-    if (!modelMatches(rule, model)) continue;
-    return { rule, fallback: rule.fallback };
-  }
-  return undefined;
-}
-
-export function modelRefKey(ref: ModelRef): string {
-  return `${ref.provider}/${ref.model}`;
-}
-
-export function modelKey(model: Pick<Model<any>, "provider" | "id">): string {
-  return `${model.provider}/${model.id}`;
-}
-
-function validateRule(value: unknown, index: number): FallbackRule {
-  if (!isRecord(value)) throw new Error(`rules[${index}] must be an object.`);
-  const rule: FallbackRule = { fallback: readModelRef(value.fallback, `rules[${index}].fallback`) };
-  if (typeof value.name === "string" && value.name.trim() !== "") rule.name = value.name.trim();
-  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 ((!rule.matchProviders || rule.matchProviders.length === 0) && (!rule.matchModels || rule.matchModels.length === 0)) {
-    throw new Error(`rules[${index}] must define matchProviders or matchModels.`);
-  }
-  return rule;
-}
-
-function modelMatches(rule: FallbackRule, model: Pick<Model<any>, "provider" | "id">): boolean {
-  if (rule.matchModels?.some((entry) => entry.provider === model.provider && entry.model === model.id)) return true;
-  if (rule.matchProviders?.includes(model.provider)) return true;
-  return false;
-}
-
-function statusesFor(rule: FallbackRule): Set<number> {
-  return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
-}
-
-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.`);
-  return value.map((entry, index) => readModelRef(entry, `${path}[${index}]`));
-}
-
-function readStringArray(value: unknown, path: string): string[] {
-  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
-  if (value.length === 0) throw new Error(`${path} must not be empty.`);
-  return value.map((entry, index) => readNonEmptyString(entry, `${path}[${index}]`));
-}
-
-function readStatuses(value: unknown, path: string): number[] {
-  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
-  if (value.length === 0) throw new Error(`${path} must not be empty.`);
-  return value.map((entry, index) => {
-    if (!Number.isInteger(entry) || entry < 100 || entry > 599) throw new Error(`${path}[${index}] must be an HTTP status code.`);
-    return entry;
-  });
-}
-
-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);
-}
+import type { Model } from "@earendil-works/pi-ai";
+
+export const CONFIG_VERSION = 1;
+export const DEFAULT_FALLBACK_STATUSES = [429, 500, 502, 503, 504] as const;
+
+export interface ModelRef {
+  provider: string;
+  model: string;
+}
+
+export interface FallbackRule {
+  name?: string;
+  matchProviders?: string[];
+  matchModels?: ModelRef[];
+  statuses?: number[];
+  /** Persistent failover cooldown in milliseconds after a matching failure. Defaults: 429 => 72h, 5xx => 10m. */
+  cooldownMs?: number;
+  fallback: ModelRef;
+}
+
+export interface ModelFallbackConfig {
+  version: 1;
+  enabled: boolean;
+  rules: FallbackRule[];
+}
+
+export interface MatchedFallback {
+  rule: FallbackRule;
+  fallback: ModelRef;
+}
+
+export function defaultConfig(): ModelFallbackConfig {
+  return {
+    version: CONFIG_VERSION,
+    enabled: true,
+    rules: [
+      {
+        name: "zai-to-deepseek-flash",
+        matchProviders: ["zai"],
+        statuses: [...DEFAULT_FALLBACK_STATUSES],
+        fallback: { provider: "deepseek", model: "deepseek-v4-flash" },
+      },
+    ],
+  };
+}
+
+export function validateConfigShape(value: unknown): ModelFallbackConfig {
+  if (!isRecord(value)) throw new Error("Config must be an object.");
+  if (value.version !== CONFIG_VERSION) throw new Error(`Unsupported config version: ${String(value.version)}.`);
+  const enabled = typeof value.enabled === "boolean" ? value.enabled : true;
+  if (!Array.isArray(value.rules)) throw new Error("rules must be an array.");
+  if (value.rules.length === 0) throw new Error("rules must include at least one fallback rule.");
+
+  return {
+    version: CONFIG_VERSION,
+    enabled,
+    rules: value.rules.map((ruleValue, index) => validateRule(ruleValue, index)),
+  };
+}
+
+export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>, "provider" | "id">, status: number): MatchedFallback | undefined {
+  if (!config.enabled) return undefined;
+  for (const rule of config.rules) {
+    if (!statusesFor(rule).has(status)) continue;
+    if (!modelMatches(rule, model)) continue;
+    return { rule, fallback: rule.fallback };
+  }
+  return undefined;
+}
+
+export function modelRefKey(ref: ModelRef): string {
+  return `${ref.provider}/${ref.model}`;
+}
+
+export function modelKey(model: Pick<Model<any>, "provider" | "id">): string {
+  return `${model.provider}/${model.id}`;
+}
+
+function validateRule(value: unknown, index: number): FallbackRule {
+  if (!isRecord(value)) throw new Error(`rules[${index}] must be an object.`);
+  const rule: FallbackRule = { fallback: readModelRef(value.fallback, `rules[${index}].fallback`) };
+  if (typeof value.name === "string" && value.name.trim() !== "") rule.name = value.name.trim();
+  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.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.`);
+  }
+  return rule;
+}
+
+function modelMatches(rule: FallbackRule, model: Pick<Model<any>, "provider" | "id">): boolean {
+  if (rule.matchModels?.some((entry) => entry.provider === model.provider && entry.model === model.id)) return true;
+  if (rule.matchProviders?.includes(model.provider)) return true;
+  return false;
+}
+
+function statusesFor(rule: FallbackRule): Set<number> {
+  return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
+}
+
+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.`);
+  return value.map((entry, index) => readModelRef(entry, `${path}[${index}]`));
+}
+
+function readStringArray(value: unknown, path: string): string[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  if (value.length === 0) throw new Error(`${path} must not be empty.`);
+  return value.map((entry, index) => readNonEmptyString(entry, `${path}[${index}]`));
+}
+
+function readStatuses(value: unknown, path: string): number[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  if (value.length === 0) throw new Error(`${path} must not be empty.`);
+  return value.map((entry, index) => {
+    if (!Number.isInteger(entry) || entry < 100 || entry > 599) throw new Error(`${path}[${index}] must be an HTTP status code.`);
+    return entry;
+  });
+}
+
+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.`);
+  return value.trim();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/state.ts

@@ -0,0 +1,118 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ModelRef } from "./config.js";
+
+export const STATE_VERSION = 1;
+
+export interface FallbackStateEntry {
+  source: ModelRef;
+  fallback: ModelRef;
+  status: number;
+  until: string;
+  createdAt: string;
+  ruleName?: string;
+}
+
+export interface FallbackState {
+  version: 1;
+  entries: FallbackStateEntry[];
+}
+
+export function emptyState(): FallbackState {
+  return { version: STATE_VERSION, entries: [] };
+}
+
+export async function readState(path: string, now = new Date()): Promise<FallbackState> {
+  const json = await readJsonIfExists(path);
+  const state = json === undefined ? emptyState() : validateStateShape(json);
+  return pruneExpiredState(state, now);
+}
+
+export async function writeState(path: string, state: FallbackState): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(validateStateShape(state), null, 2)}\n`, "utf8");
+}
+
+export function upsertStateEntry(state: FallbackState, entry: FallbackStateEntry): FallbackState {
+  const sourceKey = modelRefKey(entry.source);
+  return {
+    version: STATE_VERSION,
+    entries: [entry, ...state.entries.filter((item) => modelRefKey(item.source) !== sourceKey)],
+  };
+}
+
+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());
+}
+
+export function pruneExpiredState(state: FallbackState, now = new Date()): FallbackState {
+  const nowMs = now.getTime();
+  return {
+    version: STATE_VERSION,
+    entries: state.entries.filter((entry) => Date.parse(entry.until) > nowMs),
+  };
+}
+
+export function validateStateShape(value: unknown): FallbackState {
+  if (!isRecord(value)) throw new Error("State must be an object.");
+  if (value.version !== STATE_VERSION) throw new Error(`Unsupported state version: ${String(value.version)}.`);
+  if (!Array.isArray(value.entries)) throw new Error("entries must be an array.");
+  return {
+    version: STATE_VERSION,
+    entries: value.entries.map((entry, index) => validateEntry(entry, index)),
+  };
+}
+
+function validateEntry(value: unknown, index: number): FallbackStateEntry {
+  if (!isRecord(value)) throw new Error(`entries[${index}] must be an object.`);
+  const until = readNonEmptyString(value.until, `entries[${index}].until`);
+  const createdAt = readNonEmptyString(value.createdAt, `entries[${index}].createdAt`);
+  if (Number.isNaN(Date.parse(until))) throw new Error(`entries[${index}].until must be an ISO date.`);
+  if (Number.isNaN(Date.parse(createdAt))) throw new Error(`entries[${index}].createdAt must be an ISO date.`);
+  const status = value.status;
+  if (typeof status !== "number" || !Number.isInteger(status) || status < 100 || status > 599) throw new Error(`entries[${index}].status must be an HTTP status code.`);
+  const entry: FallbackStateEntry = {
+    source: readModelRef(value.source, `entries[${index}].source`),
+    fallback: readModelRef(value.fallback, `entries[${index}].fallback`),
+    status,
+    until,
+    createdAt,
+  };
+  if (typeof value.ruleName === "string" && value.ruleName.trim() !== "") entry.ruleName = value.ruleName.trim();
+  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,36 +1,37 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { defaultConfig, validateConfigShape, type ModelFallbackConfig } from "./config.js";
-
-export interface ModelFallbackPaths {
-  dir: string;
-  config: string;
-}
-
-export function modelFallbackPaths(agentDir: string): ModelFallbackPaths {
-  const dir = join(agentDir, "model-fallback");
-  return { dir, config: join(dir, "config.json") };
-}
-
-export async function readConfig(path: string): Promise<ModelFallbackConfig> {
-  const json = await readJsonIfExists(path);
-  return json === undefined ? defaultConfig() : validateConfigShape(json);
-}
-
-export async function writeConfig(path: string, config: ModelFallbackConfig): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  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;
-}
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defaultConfig, validateConfigShape, type ModelFallbackConfig } from "./config.js";
+
+export interface ModelFallbackPaths {
+  dir: string;
+  config: string;
+  state: string;
+}
+
+export function modelFallbackPaths(agentDir: string): ModelFallbackPaths {
+  const dir = join(agentDir, "model-fallback");
+  return { dir, config: join(dir, "config.json"), state: join(dir, "state.json") };
+}
+
+export async function readConfig(path: string): Promise<ModelFallbackConfig> {
+  const json = await readJsonIfExists(path);
+  return json === undefined ? defaultConfig() : validateConfigShape(json);
+}
+
+export async function writeConfig(path: string, config: ModelFallbackConfig): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  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,59 +1,59 @@
-{
-  "name": "pi-model-fallback",
-  "version": "0.1.0",
-  "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
-  "type": "module",
-  "license": "MIT",
-  "author": "Keisu",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "model-fallback",
-    "fallback",
-    "typescript"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eiei114/pi-model-fallback.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eiei114/pi-model-fallback/issues"
-  },
-  "homepage": "https://github.com/eiei114/pi-model-fallback#readme",
-  "files": [
-    "extensions/",
-    "lib/",
-    "docs/",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "node --test tests/*.test.mjs",
-    "ci": "npm run typecheck && npm test && npm run pack:check",
-    "pack:check": "npm pack --dry-run"
-  },
-  "pi": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@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",
-    "typebox": "latest",
-    "@types/node": "^26.0.0",
-    "typescript": "^6.0.3"
-  }
-}
+{
+  "name": "pi-model-fallback",
+  "version": "0.3.3",
+  "description": "Pi extension that switches to a fallback model after provider failures such as 429 rate limits.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Keisu",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "model-fallback",
+    "fallback",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-model-fallback.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-model-fallback/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-model-fallback#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@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",
+    "typebox": "latest",
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}