pi-openmodel-provider 0.2.16 → 0.2.18

package/AGENTS.md

@@ -1,13 +1,14 @@
 # Agent Instructions
 
-- This package is **pi-openmodel-provider** for OpenModel.ai, **NOT** OpenRouter.
-- OpenModel is a multi-model AI gateway, similar to OpenRouter but a different service.
-- Models are fetched dynamically from OpenModel's API at startup — no hardcoded model list.
-- Models are cached locally at `~/.pi/agent/cache/openmodel-models.json` with a 5-minute TTL to avoid hitting the API on every startup.
-- Compat flags are set per provider (openai, anthropic, deepseek, qwen, zai) for optimal protocol compatibility.
-- If the `/v1/models` endpoint fails (no API key), protocols are inferred from the provider.
-- See `.agents/skills/pi-openmodel-info/SKILL.md` for full documentation.
-- Follow [CONTRIBUTING.md](CONTRIBUTING.md) before changing code.
-- Use [RELEASE.md](RELEASE.md) for release process.
+This package is **pi-openmodel-provider** for [OpenModel.ai](https://www.openmodel.ai) — **NOT** OpenRouter.
+
+## Key facts for LLMs
+
+- Models are fetched dynamically from OpenModel's API at startup. No hardcoded model list.
+- Cached at `~/.pi/agent/cache/openmodel-models.json` with 5-min TTL.
+- Compat flags per provider (openai, anthropic, deepseek, qwen, zai) for optimal protocol compatibility.
+- If `/v1/models` fails (no API key), protocols are inferred from the provider.
+- Full docs at `.agents/skills/pi-openmodel-info/SKILL.md`.
+- General project docs: [README.md](README.md), [CONTRIBUTING.md](CONTRIBUTING.md), [RELEASE.md](RELEASE.md).
 
 **Maintained by** [Ivan Gabriel Yarupaitan Rivera](https://www.vanchi.pro/)

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.18] - 2026-06-26
+
+### Added
+- `src/health.ts` — shared `HealthStatus` type and `determineHealth()` function, extracted from `src/api/stability.ts` and `src/formatters/stability.ts` to eliminate code duplication
+- `tests/test-cache.ts` — 12 tests covering cache read (valid, expired, corrupted, missing) and write (success, directory creation, error suppression)
+- `CacheFs` interface in `src/cache.ts` for dependency injection (matching `fetchImpl` pattern)
+- `test:cache` npm script
+
+### Changed
+- `src/api/stability.ts` — removed local `determineHealthFallback()` copy, imports from `src/health.ts` instead
+- `src/formatters/stability.ts` — removed local `determineHealth()` copy, imports from `src/health.ts` instead
+- `src/api/models.ts` — eliminated unsafe `as unknown as OpenModelProviderModel` cast and 4 `as number` price casts via type annotation and `getNumberPrice()` helper; removed `as const` on model base object
+- `src/providers/compat.ts` — removed unused `api` parameter from `compatForProvider()`
+- `index.ts` — replaced blocking `readFileSync` with `await readFile` from `fs/promises`
+- `LICENSE` — added copyright holder name
+- `tsconfig.json` — enabled `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`
+- `AGENTS.md` — reduced to LLM-focused bullet points with references to README and SKILL.md
+- `README.md` — added `health.ts` to architecture tree, added `test:cache` to development section
+
+### Changed
+- **Major refactor (SRP):** Reorganized `src/` into single-responsibility modules
+  - `api/` — network fetching only (models, stability)
+  - `providers/` — pure business logic (compat, protocols, pricing)
+  - `auth/` — login orchestration + input validation separated
+  - `formatters/` — pure display formatting (stability health/confidence)
+  - Each file now has exactly one responsibility (was 1-4 before)
+- `index.ts` — replaced dynamic `import("node:fs")` with static top-level import
+
+### Documentation
+- `README.md` — added Codebase Architecture section with module descriptions
+- `CONTRIBUTING.md` — added Codebase Architecture section with contributor guidelines
+
 ## [0.2.16] - 2026-06-23
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Ivan Gabriel Yarupaitan Rivera
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -93,6 +93,7 @@ Model pricing is fetched live from OpenModel's public API (`/web/v1/models`). Ea
 - **Friendly error messages** with emojis and actionable guidance
 - **No hardcoding** — new models, pricing, and capabilities appear automatically
 - **CI workflow** — typecheck and tests run on every push and PR
+- **Modular architecture** — each module has a single responsibility (SRP), making the codebase easy to maintain and extend
 
 ## Error handling
 
@@ -160,8 +161,41 @@ npm run test:auth
 npm run test:pricing
 npm run test:stability
 npm run test:edge
+npm run test:cache
 ```
 
+### Codebase Architecture
+
+The source code is organized by responsibility following the Single Responsibility Principle:
+
+```
+src/
+├── api/                    # Network fetching (models, stability)
+│   ├── models.ts           #   fetchOpenModelModels() — model discovery orchestration
+│   └── stability.ts        #   fetchModelStabilitySummary/Detail()
+├── providers/              # Provider-specific business logic
+│   ├── compat.ts           #   compatForProvider() — per-provider compatibility flags
+│   ├── protocols.ts        #   determineApi() + thinkingLevelMapForApi()
+│   └── pricing.ts          #   pricePerMillion() — cost-per-token conversion
+├── auth/                   # Authentication flow
+│   ├── login.ts            #   login() + refreshToken() + getApiKey()
+│   └── validate.ts         #   sanitizeApiKey() + isValidApiKey()
+├── formatters/             # Pure display formatting
+│   └── stability.ts        #   formatHealthStatus() + formatConfidence()
+├── health.ts               # Shared health status determination
+├── cache.ts                # Local model cache (read/write)
+├── errors.ts               # API error parsing + friendly messages
+└── stub.d.ts               # Type stubs for pi peer dependency
+```
+
+**Key principles:**
+- Each file has exactly one responsibility
+- `api/` modules only handle HTTP — no business logic
+- `providers/` modules are pure functions — no side effects
+- `formatters/` modules are pure — no network calls
+- `auth/` separates input validation from login orchestration
+- Tests mirror the source structure and mock network boundaries
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR expectations, and commit message rules.

package/index.ts

@@ -5,15 +5,15 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
-import { fetchOpenModelModels } from "./src/models.ts"
-import { login, refreshToken, getApiKey } from "./src/auth.ts"
+import { fetchOpenModelModels } from "./src/api/models.ts"
+import { login, refreshToken, getApiKey } from "./src/auth/login.ts"
 import {
   fetchModelStabilitySummary,
   fetchModelStabilityDetail,
-  formatHealthStatus,
-} from "./src/stability.ts"
-import { friendlyMessage } from "./src/errors.ts"
+} from "./src/api/stability.ts"
+import { formatHealthStatus } from "./src/formatters/stability.ts"
 import { readModelCache, writeModelCache } from "./src/cache.ts"
+import { readFile } from "node:fs/promises"
 import { homedir } from "node:os"
 
 export default async function (pi: ExtensionAPI) {
@@ -77,16 +77,12 @@ export default async function (pi: ExtensionAPI) {
     description: "Show OpenModel provider status",
     handler: async (_args: string, ctx: any) => {
       const count = models.length
-      const status = count > 0
-        ? `✅ ${count} models loaded`
-        : modelError ?? "❌ No models loaded"
 
       // Detect if user has configured an API key in auth.json
       let hasApiKey = false
       try {
-        const { readFileSync } = await import("node:fs")
         const authPath = `${homedir()}/.pi/agent/auth.json`
-        const content = readFileSync(authPath, "utf-8")
+        const content = await readFile(authPath, "utf-8")
         const data = JSON.parse(content)
         hasApiKey = !!(data.openmodel?.access || data.openmodel?.refresh)
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openmodel-provider",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "pi custom provider for OpenModel.ai - Multi-model AI gateway",
   "type": "module",
   "keywords": [
@@ -40,7 +40,8 @@
     "test:pricing": "tsx tests/test-pricing.ts",
     "test:stability": "tsx tests/test-stability.ts",
     "test:edge": "tsx tests/test-edge-cases.ts",
-    "test": "tsx tests/test-models.ts && tsx tests/test-auth.ts && tsx tests/test-pricing.ts && tsx tests/test-stability.ts && tsx tests/test-edge-cases.ts"
+    "test:cache": "tsx tests/test-cache.ts",
+    "test": "tsx tests/test-models.ts && tsx tests/test-auth.ts && tsx tests/test-pricing.ts && tsx tests/test-stability.ts && tsx tests/test-edge-cases.ts && tsx tests/test-cache.ts"
   },
   "pi": {
     "extensions": [

package/src/{models.ts → api/models.ts}

@@ -3,13 +3,25 @@
  *
  * Fetches available models from OpenModel's public API (no auth required).
  * Pricing, context window, and capabilities are all provided by the API.
+ *
+ * This module owns the orchestration — ping both endpoints, merge results,
+ * and return canonical model objects. Provider-specific logic (compat,
+ * protocols, pricing) is delegated to src/providers/*.
  */
 
-import { parseWebError, parseProxyError, friendlyMessage } from "./errors.ts"
+import { parseWebError, parseProxyError, friendlyMessage } from "../errors.ts"
+import { pricePerMillion } from "../providers/pricing.ts"
+import { determineApi, inferApiFromProvider, thinkingLevelMapForApi } from "../providers/protocols.ts"
+import { compatForProvider } from "../providers/compat.ts"
+import type { ApiProtocol } from "../providers/protocols.ts"
 
 const DEFAULT_WEB_MODELS_URL = "https://api.openmodel.ai/web/v1/models"
 export const DEFAULT_LEGACY_MODELS_URL = "https://api.openmodel.ai/v1/models"
 
+// ──────────────────────────────────────────────
+// Public model interface
+// ──────────────────────────────────────────────
+
 export interface OpenModelProviderModel {
   id: string
   name: string
@@ -19,10 +31,14 @@ export interface OpenModelProviderModel {
   cost: { input: number; output: number; cacheRead: number; cacheWrite: number }
   contextWindow: number
   maxTokens: number
-  api: "anthropic-messages" | "openai-responses" | "google-generative-ai"
+  api: ApiProtocol
   compat?: Record<string, unknown>
 }
 
+// ──────────────────────────────────────────────
+// Internal API response types
+// ──────────────────────────────────────────────
+
 interface WebApiModel {
   key: string
   provider_key: string
@@ -59,82 +75,10 @@ interface LegacyApiResponse {
   object: string
 }
 
-function pricePerMillion(costPerToken: number | undefined): number {
-  if (costPerToken === undefined || costPerToken === null) return 0
-  return Math.round(costPerToken * 1_000_000 * 1000) / 1000
-}
+// ──────────────────────────────────────────────
+// Fetch: Web API (public, pageable)
+// ──────────────────────────────────────────────
 
-function determineApi(protocols: string[], provider: string): "anthropic-messages" | "openai-responses" | "google-generative-ai" | null {
-  if (protocols.includes("messages")) return "anthropic-messages"
-  if (protocols.includes("responses")) return "openai-responses"
-  if (protocols.includes("gemini")) return "google-generative-ai"
-  return null
-}
-
-/**
- * Determine compat flags based on provider and API.
- * These tell pi about provider-specific quirks and capabilities.
- */
-function compatForProvider(
-  providerKey: string,
-  api: "anthropic-messages" | "openai-responses" | "google-generative-ai",
-  reasoning: boolean,
-): Record<string, unknown> | undefined {
-  switch (providerKey) {
-    case "openai":
-      return { supportsReasoningEffort: true }
-    case "deepseek":
-      if (reasoning) {
-        return { thinkingFormat: "deepseek" }
-      }
-      return undefined
-    case "anthropic":
-      return {
-        sendSessionAffinityHeaders: true,
-        supportsCacheControlOnTools: true,
-        supportsEagerToolInputStreaming: true,
-      }
-    case "google":
-    case "gemini":
-      return undefined
-    case "qwen":
-      if (reasoning) {
-        return { thinkingFormat: "qwen-chat-template" }
-      }
-      return undefined
-    case "zai":
-      if (reasoning) {
-        return { thinkingFormat: "zai" }
-      }
-      return undefined
-    default:
-      return undefined
-  }
-}
-
-function thinkingLevelMapForApi(api: "anthropic-messages" | "openai-responses" | "google-generative-ai"): Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh", string | null>> {
-  if (api === "anthropic-messages") {
-    return {
-      minimal: "low",
-      low: "medium",
-      medium: "high",
-      high: "high",
-      xhigh: "max",
-    }
-  }
-  if (api === "openai-responses") {
-    return {
-      minimal: "low",
-      low: "low",
-      medium: "medium",
-      high: "high",
-      xhigh: "high",
-    }
-  }
-  return {}
-}
-
-/** Fetch all models from the web API (public, no auth required) */
 async function fetchWebModels(options?: {
   url?: string
   fetchImpl?: typeof fetch
@@ -155,12 +99,16 @@ async function fetchWebModels(options?: {
       let body: any
       try { body = await response.json() } catch {}
       const err = parseWebError(body)
-      throw new Error(`Failed to fetch models: ${response.status} ${err.code} — ${friendlyMessage(err.code, err.message)}`)
+      throw new Error(
+        `Failed to fetch models: ${response.status} ${err.code} — ${friendlyMessage(err.code, err.message)}`,
+      )
     }
 
     const body = (await response.json()) as WebApiResponse
     if (!body.success) {
-      throw new Error(`Failed to fetch models — ${friendlyMessage("INTERNAL_ERROR", "Unknown error")}`)
+      throw new Error(
+        `Failed to fetch models — ${friendlyMessage("INTERNAL_ERROR", "Unknown error")}`,
+      )
     }
 
     totalPages = body.meta.pagination.totalPages
@@ -173,7 +121,10 @@ async function fetchWebModels(options?: {
   return modelMap
 }
 
-/** Fetch protocol info from legacy models endpoint */
+// ──────────────────────────────────────────────
+// Fetch: Legacy API (requires API key)
+// ──────────────────────────────────────────────
+
 async function fetchLegacyModels(options?: {
   url?: string
   fetchImpl?: typeof fetch
@@ -189,7 +140,9 @@ async function fetchLegacyModels(options?: {
     let body: any
     try { body = await response.json() } catch {}
     const err = parseProxyError(body)
-    throw new Error(`Failed to fetch models: ${response.status} — ${friendlyMessage(err.code, err.message)}`)
+    throw new Error(
+      `Failed to fetch models: ${response.status} — ${friendlyMessage(err.code, err.message)}`,
+    )
   }
 
   const body = (await response.json()) as LegacyApiResponse
@@ -204,7 +157,26 @@ async function fetchLegacyModels(options?: {
   return modelMap
 }
 
-/** Fetch models from OpenModel API (public, no auth required) */
+// ──────────────────────────────────────────────
+// Orchestration
+// ──────────────────────────────────────────────
+
+/** Safely extract a numeric price from the prices record */
+function getNumberPrice(
+  prices: Record<string, number | Record<string, number>>,
+  key: string,
+): number | undefined {
+  const val = prices[key]
+  return typeof val === "number" ? val : undefined
+}
+
+/**
+ * Fetch all models from OpenModel API (public, no auth required for web endpoint).
+ *
+ * Combines pricing/capabilities from the web API with protocol info from
+ * the legacy endpoint. If the legacy endpoint fails (e.g., no API key),
+ * protocols are inferred from the provider name.
+ */
 export async function fetchOpenModelModels(options?: {
   webUrl?: string
   legacyUrl?: string
@@ -220,34 +192,38 @@ export async function fetchOpenModelModels(options?: {
   const models: OpenModelProviderModel[] = []
 
   for (const [id, web] of webModels) {
-    // Skip image-only models
-    if (web.supports.supports_image_generation && !web.supports.supports_vision && !web.supports.supports_reasoning) {
+    // Skip image-only models (e.g., DALL-E)
+    if (
+      web.supports.supports_image_generation &&
+      !web.supports.supports_vision &&
+      !web.supports.supports_reasoning
+    ) {
       continue
     }
 
+    // Determine API protocol
     const legacy = legacyModels.get(id)
     const protocols = legacy?.supported_protocols ?? []
     let api = determineApi(protocols, web.provider_key)
     if (!api) {
-      // Fallback: infer protocol from provider
-      if (["openai"].includes(web.provider_key)) api = "openai-responses"
-      else if (["gemini"].includes(web.provider_key)) api = "google-generative-ai"
-      else api = "anthropic-messages"
+      api = inferApiFromProvider(web.provider_key)
     }
 
-    const inputPrice = pricePerMillion(web.prices.input_cost_per_token as number)
-    const outputPrice = pricePerMillion(web.prices.output_cost_per_token as number)
-    const cacheRead = pricePerMillion(web.prices.cache_read_input_token_cost as number)
-    const cacheWrite = pricePerMillion(web.prices.cache_creation_input_token_cost as number)
+    // Parse pricing (safely — some price fields may be Record<string, number>)
+    const inputPrice = pricePerMillion(getNumberPrice(web.prices, "input_cost_per_token"))
+    const outputPrice = pricePerMillion(getNumberPrice(web.prices, "output_cost_per_token"))
+    const cacheRead = pricePerMillion(getNumberPrice(web.prices, "cache_read_input_token_cost"))
+    const cacheWrite = pricePerMillion(getNumberPrice(web.prices, "cache_creation_input_token_cost"))
 
+    // Build model config
     const reasoning = web.supports.supports_reasoning ?? false
-    const compat = compatForProvider(web.provider_key, api, reasoning)
+    const compat = compatForProvider(web.provider_key, reasoning)
 
-    const base = {
+    const model: OpenModelProviderModel = {
       id,
       name: id,
       reasoning,
-      input: web.supports.supports_vision ? ["text", "image"] as const : ["text"] as const,
+      input: web.supports.supports_vision ? (["text", "image"] as const) : (["text"] as const),
       cost: {
         input: inputPrice * (web.price_multiplier ?? 1),
         output: outputPrice * (web.price_multiplier ?? 1),
@@ -257,13 +233,9 @@ export async function fetchOpenModelModels(options?: {
       contextWindow: web.max.max_input_tokens ?? 128_000,
       maxTokens: web.max.max_output_tokens ?? web.max.max_tokens ?? 16_384,
       api,
-    } as const
-
-    const model = {
-      ...base,
       ...(reasoning ? { thinkingLevelMap: thinkingLevelMapForApi(api) } : {}),
       ...(compat ? { compat } : {}),
-    } as unknown as OpenModelProviderModel
+    }
 
     models.push(model)
   }

package/src/api/stability.ts

@@ -0,0 +1,163 @@
+/**
+ * OpenModel.ai Model Stability API client.
+ *
+ * Fetches real-time stability metrics (success rate, latency, throughput)
+ * for all models. Publicly accessible without authentication.
+ *
+ * Reference:
+ *   GET https://api.openmodel.ai/web/v1/model-stability/summary
+ *   GET https://api.openmodel.ai/web/v1/model-stability/:modelKey
+ *
+ * This module is pure fetching — formatting is in formatters/stability.ts.
+ */
+
+import { parseWebError, friendlyMessage } from "../errors.ts"
+import { determineHealth } from "../health.ts"
+import type { HealthStatus } from "../health.ts"
+
+export const STABILITY_SUMMARY_URL =
+  "https://api.openmodel.ai/web/v1/model-stability/summary"
+
+/** Confidence level based on sample size */
+export type ConfidenceLevel = "high" | "medium" | "low"
+
+/** Stability summary for a single model */
+export interface ModelStability {
+  model_name: string
+  success_rate: number
+  avg_latency_ms: number
+  avg_tps: number
+  confidence: ConfidenceLevel
+  health_status: HealthStatus
+}
+
+/** Stability summary for a single model with time series */
+export interface ModelStabilityDetail {
+  model_name: string
+  confidence: ConfidenceLevel
+  summary: {
+    success_rate: number
+    avg_latency_ms: number
+    avg_ttft_ms: number
+    avg_tps: number
+  }
+  series: Array<{
+    ts: number
+    success_rate: number
+    avg_latency_ms: number
+    avg_ttft_ms: number
+    avg_tps: number
+    confidence: ConfidenceLevel
+  }>
+  updated_at: number
+  health_status: HealthStatus
+}
+
+/** Fetch stability summary for all models */
+export async function fetchModelStabilitySummary(options?: {
+  url?: string
+  fetchImpl?: typeof fetch
+  hours?: number
+  signal?: AbortSignal
+}): Promise<ModelStability[]> {
+  const url = options?.url ?? STABILITY_SUMMARY_URL
+  const fetchImpl = options?.fetchImpl ?? fetch
+  const hours = options?.hours ?? 24
+
+  const params = new URLSearchParams({ hours: String(hours) })
+  const response = await fetchImpl(`${url}?${params}`, {
+    headers: { accept: "application/json" },
+    signal: options?.signal ?? null,
+  })
+
+  if (!response.ok) {
+    let errBody: any
+    try { errBody = await response.json() } catch {}
+    const err = parseWebError(errBody)
+    throw new Error(`stability — ${friendlyMessage(err.code, err.message)}`)
+  }
+
+  const body = (await response.json()) as {
+    success: boolean
+    data: Array<{
+      model_name: string
+      success_rate: number
+      avg_latency_ms: number
+      avg_tps: number
+      confidence: ConfidenceLevel
+    }>
+  }
+
+  if (!body.success) {
+    throw new Error(`stability — ${friendlyMessage("INTERNAL_ERROR", "Summary request failed")}`)
+  }
+
+  return body.data.map((item) => ({
+    ...item,
+    health_status: determineHealth(item.success_rate, item.confidence),
+  }))
+}
+
+/** Fetch stability detail for a specific model */
+export async function fetchModelStabilityDetail(
+  modelKey: string,
+  options?: {
+    fetchImpl?: typeof fetch
+    hours?: number
+    signal?: AbortSignal
+  },
+): Promise<ModelStabilityDetail> {
+  const fetchImpl = options?.fetchImpl ?? fetch
+  const hours = options?.hours ?? 24
+
+  const params = new URLSearchParams({ hours: String(hours) })
+  const response = await fetchImpl(
+    `https://api.openmodel.ai/web/v1/model-stability/${encodeURIComponent(modelKey)}?${params}`,
+    {
+      headers: { accept: "application/json" },
+      signal: options?.signal ?? null,
+    },
+  )
+
+  if (!response.ok) {
+    let errBody: any
+    try { errBody = await response.json() } catch {}
+    const err = parseWebError(errBody)
+    throw new Error(`stability — ${friendlyMessage(err.code, err.message)}`)
+  }
+
+  const body = (await response.json()) as {
+    success: boolean
+    data: {
+      model_name: string
+      confidence: ConfidenceLevel
+      summary: {
+        success_rate: number
+        avg_latency_ms: number
+        avg_ttft_ms: number
+        avg_tps: number
+      }
+      series: Array<{
+        ts: number
+        success_rate: number
+        avg_latency_ms: number
+        avg_ttft_ms: number
+        avg_tps: number
+        confidence: ConfidenceLevel
+      }>
+      updated_at: number
+    }
+  }
+
+  if (!body.success) {
+    throw new Error(`stability — ${friendlyMessage("NOT_FOUND", `Model "${modelKey}" not found`)}`)
+  }
+
+  return {
+    ...body.data,
+    health_status: determineHealth(
+      body.data.summary.success_rate,
+      body.data.confidence,
+    ),
+  }
+}