pi-model-fallback 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# PACKAGE_DISPLAY_NAME
+
+[![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)
+[![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)
+
+> One-line pitch for this TypeScript-first Pi package.
+
+## What this is
+
+Briefly explain what this TypeScript-first package adds to Pi and who should use it.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Install
+
+Install the published npm package with Pi:
+
+```bash
+pi install npm:PACKAGE_NAME
+```
+
+Replace `PACKAGE_NAME` with the exact `name` from `package.json`.
+For a scoped npm package, keep the `npm:` prefix:
+
+```bash
+pi install npm:@your-scope/your-pi-package
+```
+
+Pin a specific version when you want reproducible installs:
+
+```bash
+pi install npm:PACKAGE_NAME@0.1.0
+```
+
+Install into the current project instead of your user Pi settings:
+
+```bash
+pi install npm:PACKAGE_NAME -l
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/OWNER/REPO
+```
+
+Try it without permanently installing:
+
+```bash
+pi -e npm:PACKAGE_NAME
+```
+
+## Quick start
+
+Try this package locally:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/your-command
+```
+
+## Package contents
+
+| 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) |
+
+## Development
+
+```bash
+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.
+
+```bash
+npm version patch
+git push
+```
+
+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
+
+## License
+
+MIT

package/docs/usage.md

@@ -0,0 +1,18 @@
+# Usage
+
+Install:
+
+```bash
+pi install git:github.com/eiei114/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.
+
+Commands:
+
+```text
+/model-fallback:status
+/model-fallback:reset
+```
+
+The failed provider response is not automatically replayed in v0.1.0.

package/extensions/index.ts

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync } from "node:fs";
+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 { modelFallbackPaths, readConfig, writeConfig, type ModelFallbackPaths } from "../lib/storage.js";
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const STATUS_KEY = "model-fallback";
+
+export default function modelFallback(pi: ExtensionAPI) {
+  let paths: ModelFallbackPaths = modelFallbackPaths(getAgentDir());
+  let config: ModelFallbackConfig | undefined;
+  let originalModelKey: string | undefined;
+  let activeFallbackKey: string | undefined;
+  let lastFallbackReason: string | undefined;
+
+  function syncPaths(ctx: ExtensionContext): void {
+    paths = shouldUseProjectLocalState(ctx) ? modelFallbackPaths(join(ctx.cwd, ".pi")) : modelFallbackPaths(getAgentDir());
+  }
+
+  async function loadConfig(ctx: ExtensionContext): Promise<ModelFallbackConfig | undefined> {
+    try {
+      syncPaths(ctx);
+      config = await readConfig(paths.config);
+      return config;
+    } catch (error) {
+      ctx.ui.notify(`Model fallback config 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) => {
+    await loadConfig(ctx);
+    updateStatus(ctx);
+  });
+
+  pi.on("model_select", async (event, ctx) => {
+    if (activeFallbackKey && modelKey(event.model) !== activeFallbackKey) {
+      activeFallbackKey = undefined;
+      originalModelKey = undefined;
+      lastFallbackReason = undefined;
+      updateStatus(ctx);
+    }
+  });
+
+  pi.on("after_provider_response", async (event, ctx) => {
+    const current = ctx.model;
+    const loaded = config ?? (await loadConfig(ctx));
+    if (!current || !loaded) return;
+    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;
+    }
+
+    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.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");
+    },
+  });
+
+  pi.registerCommand("model-fallback:reset", {
+    description: "Return from fallback model to the pre-fallback model when remembered",
+    handler: async (_args, ctx) => {
+      if (!originalModelKey) {
+        ctx.ui.notify("Model fallback: no remembered original model.", "info");
+        return;
+      }
+      const [provider, ...modelParts] = originalModelKey.split("/");
+      const model = ctx.modelRegistry.find(provider, modelParts.join("/"));
+      if (!model) {
+        ctx.ui.notify(`Model fallback original missing: ${originalModelKey}`, "warning");
+        return;
+      }
+      const ok = await pi.setModel(model);
+      if (!ok) {
+        ctx.ui.notify(`Model fallback original auth unavailable: ${originalModelKey}`, "warning");
+        return;
+      }
+      activeFallbackKey = undefined;
+      originalModelKey = undefined;
+      lastFallbackReason = undefined;
+      updateStatus(ctx);
+      ctx.ui.notify(`Model fallback reset: ${modelKey(model)}`, "info");
+    },
+  });
+
+  pi.registerTool({
+    name: "model_fallback_config",
+    label: "Model Fallback Config",
+    description: "Read, validate, or save pi-model-fallback configuration.",
+    promptSnippet: "Read, validate, or save pi-model-fallback configuration after user asks.",
+    promptGuidelines: [
+      "Use model_fallback_config when the user asks to inspect or configure model fallback rules.",
+      "Use action=save only after preparing the full JSON config; the tool asks for confirmation before writing.",
+    ],
+    parameters: Type.Object({
+      action: Type.Union([Type.Literal("read"), Type.Literal("status"), Type.Literal("validate"), Type.Literal("save")]),
+      configJson: Type.Optional(Type.String({ description: "Full ModelFallbackConfig JSON for validate or save." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      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 });
+      }
+      if (!params.configJson) throw new Error("configJson is required for validate/save.");
+      const nextConfig = validateConfigShape(JSON.parse(params.configJson));
+      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 });
+      await writeConfig(paths.config, nextConfig);
+      config = nextConfig;
+      return textResult("Config saved.", { configPath: paths.config });
+    },
+  });
+}
+
+function shouldUseProjectLocalState(ctx: ExtensionContext): boolean {
+  const projectSettingsPath = join(ctx.cwd, ".pi", "settings.json");
+  return existsSync(projectSettingsPath) && projectSettingsIncludesThisPackage(projectSettingsPath);
+}
+
+function projectSettingsIncludesThisPackage(projectSettingsPath: string): boolean {
+  try {
+    const settings = JSON.parse(readFileSync(projectSettingsPath, "utf8")) as unknown;
+    if (!isRecord(settings) || !Array.isArray(settings.packages)) return false;
+    return settings.packages.some((entry) => packageEntryMatchesThisPackage(entry, dirname(projectSettingsPath)));
+  } catch {
+    return false;
+  }
+}
+
+function packageEntryMatchesThisPackage(entry: unknown, settingsDir: string): boolean {
+  const source = typeof entry === "string" ? entry : isRecord(entry) && typeof entry.source === "string" ? entry.source : undefined;
+  if (!source) return false;
+  if (source.includes("pi-model-fallback")) return true;
+  return resolve(settingsDir, source) === resolve(PACKAGE_ROOT);
+}
+
+function validateRegisteredModels(ctx: ExtensionContext, nextConfig: ModelFallbackConfig): void {
+  for (const rule of nextConfig.rules) {
+    const fallback = ctx.modelRegistry.find(rule.fallback.provider, rule.fallback.model);
+    if (!fallback) throw new Error(`Unknown fallback model: ${modelRefKey(rule.fallback)}`);
+  }
+}
+
+function formatStatus(config: ModelFallbackConfig, configPath: string, activeFallbackKey?: string, originalModelKey?: string, reason?: string): string {
+  return [
+    `Model fallback: ${config.enabled ? "enabled" : "disabled"}`,
+    `Config: ${configPath}`,
+    `Rules: ${config.rules.length}`,
+    `Active fallback: ${activeFallbackKey ?? "none"}`,
+    `Original model: ${originalModelKey ?? "none"}`,
+    `Reason: ${reason ?? "none"}`,
+  ].join("\n");
+}
+
+function summarizeConfig(config: ModelFallbackConfig): string {
+  return [
+    `enabled: ${config.enabled}`,
+    ...config.rules.map((rule) => `${rule.name ?? "rule"}: ${rule.matchProviders?.join(",") ?? "models"} -> ${modelRefKey(rule.fallback)}`),
+  ].join("\n");
+}
+
+function textResult(text: string, details?: Record<string, unknown>) {
+  return { content: [{ type: "text" as const, text }], details: details ?? {} };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/config.ts

@@ -0,0 +1,136 @@
+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);
+}

package/lib/storage.ts

@@ -0,0 +1,36 @@
+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;
+}

package/package.json

@@ -0,0 +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"
+  }
+}