pi-model-fallback 0.1.0 → 0.3.2

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.2",
+  "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"
+  }
+}