pi-openmodel-provider 0.2.15 → 0.2.17

package/.agents/skills/pi-openmodel-info/SKILL.md

@@ -26,12 +26,25 @@ Models are fetched live from OpenModel's API at startup:
 
 If the API key is not configured yet, models still load — protocols are inferred automatically from the provider name.
 
+### Caching
+
+Models are cached locally at `~/.pi/agent/cache/openmodel-models.json` with a **5-minute TTL**. On subsequent startups or `/reload`, the cached list is used instead of hitting the API again. The `/openmodel` command shows `(cached)` when the cache is active.
+
 ## Thinking levels
 
 Reasoning models support thinking levels:
 - **Messages protocol:** minimal → low, low → medium, medium → high
 - **Responses protocol:** `reasoning_effort` levels (low, medium, high)
 
+## Compat flags
+
+Compat flags are automatically set per provider for optimal protocol compatibility:
+- **OpenAI:** `supportsReasoningEffort: true`
+- **Anthropic:** `sendSessionAffinityHeaders`, `supportsCacheControlOnTools`, `supportsEagerToolInputStreaming`
+- **DeepSeek (reasoning):** `thinkingFormat: "deepseek"`
+- **Qwen (reasoning):** `thinkingFormat: "qwen-chat-template"`
+- **ZAI / GLM (reasoning):** `thinkingFormat: "zai"`
+
 ## Available commands
 
 - `/openmodel` — Show provider status

package/AGENTS.md

@@ -3,6 +3,8 @@
 - 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.

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.17] - 2026-06-23
+
+### 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
+- Local model cache at `~/.pi/agent/cache/openmodel-models.json` with 5-minute TTL
+- `src/cache.ts` module for cache read/write operations
+- Compat flags per provider (openai, anthropic, deepseek, qwen, zai) for optimal protocol compatibility
+- AbortSignal support in stability fetch functions
+- CI workflow (`.github/workflows/ci.yml`) for typecheck + tests on push and PR
+- Typecheck and test steps before publish in `.github/workflows/publish.yml`
+- `(cached)` indicator in `/openmodel` status output
+
+### Changed
+- Models now load from cache first, falling back to API fetch
+- Updated `actions/checkout` and `actions/setup-node` to v5 (Node 24 native)
+
 ## [0.2.14] - 2026-06-22
 
 ### Changed

package/README.md

@@ -3,6 +3,7 @@
 A [pi](https://github.com/earendil-works/pi-mono) custom provider that connects pi to [OpenModel.ai](https://www.openmodel.ai) — a unified AI API gateway.
 
 [![npm version](https://img.shields.io/npm/v/pi-openmodel-provider)](https://www.npmjs.com/package/pi-openmodel-provider)
+[![CI](https://github.com/IvanGabrielYarupaitanRivera/pi-openmodel-provider/actions/workflows/ci.yml/badge.svg)](https://github.com/IvanGabrielYarupaitanRivera/pi-openmodel-provider/actions/workflows/ci.yml)
 
 > **Disclaimer:** This is an unofficial, community-maintained package. I am not affiliated with, endorsed by, or connected to OpenModel in any way. This provider simply forwards requests to the public OpenModel API using your own API key.
 
@@ -64,6 +65,12 @@ On startup, the provider fetches models from two endpoints:
 
 Pricing, context window, reasoning support, and vision capabilities are all provided by the API — no hardcoded data.
 
+### Caching
+
+Models are cached locally at `~/.pi/agent/cache/openmodel-models.json` with a **5-minute TTL**. On subsequent startups or `/reload`, the cached list is used instead of hitting the API again. The `/openmodel` command shows `(cached)` when the cache is active.
+
+To force a fresh fetch, wait 5 minutes or delete the cache file manually.
+
 ## Pricing
 
 Model pricing is fetched live from OpenModel's public API (`/web/v1/models`). Each model returns its real per-token rates in microdollars, converted to dollars per million tokens for display.
@@ -75,13 +82,18 @@ Model pricing is fetched live from OpenModel's public API (`/web/v1/models`). Ea
 
 ## Features
 
-- **41 models** from 9+ providers (dynamically fetched)
+- **41+ models** from 9+ providers (dynamically fetched)
 - **3 protocols**: Messages (Anthropic), Responses (OpenAI), Gemini (Google)
 - **Model stability metrics** via `/openmodel-stability`
 - **1M context window** for DeepSeek V4 models
 - **Thinking levels** for reasoning models (DeepSeek, Claude, GPT, Gemini, etc.)
+- **Compat flags** per provider for optimal protocol compatibility
+- **Local caching** with 5-minute TTL to reduce API calls
+- **AbortSignal support** in stability commands for cancellation
 - **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
 
@@ -151,6 +163,37 @@ npm run test:stability
 npm run test:edge
 ```
 
+### 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()
+├── 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,27 +5,39 @@
  */
 
 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"
+} from "./src/api/stability.ts"
+import { formatHealthStatus } from "./src/formatters/stability.ts"
 import { friendlyMessage } from "./src/errors.ts"
+import { readModelCache, writeModelCache } from "./src/cache.ts"
+import { readFileSync } from "node:fs"
 import { homedir } from "node:os"
 
 export default async function (pi: ExtensionAPI) {
   let models: Awaited<ReturnType<typeof fetchOpenModelModels>> = []
   let modelError: string | null = null
+  let fromCache = false
 
-  try {
-    models = await fetchOpenModelModels()
-  } catch (error) {
-    if (error instanceof TypeError && error.message.includes("fetch")) {
-      modelError = "🌐 Network error: check your internet connection"
-    } else {
-      modelError = `⚠️ ${error instanceof Error ? error.message : "Could not load models"}`
+  // Try local cache first to avoid hitting the API on every startup
+  const cached = await readModelCache()
+  if (cached) {
+    models = cached
+    fromCache = true
+  } else {
+    try {
+      models = await fetchOpenModelModels()
+      // Fire-and-forget cache write (failures are silently ignored)
+      writeModelCache(models)
+    } catch (error) {
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        modelError = "🌐 Network error: check your internet connection"
+      } else {
+        modelError = `⚠️ ${error instanceof Error ? error.message : "Could not load models"}`
+      }
     }
   }
 
@@ -54,6 +66,9 @@ export default async function (pi: ExtensionAPI) {
       if (model.thinkingLevelMap) {
         config.thinkingLevelMap = model.thinkingLevelMap
       }
+      if (model.compat) {
+        config.compat = model.compat
+      }
       return config
     }),
   })
@@ -70,7 +85,6 @@ export default async function (pi: ExtensionAPI) {
       // 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 data = JSON.parse(content)
@@ -83,7 +97,7 @@ export default async function (pi: ExtensionAPI) {
         "╔══════════════════════════════════╗",
         "║        OpenModel.ai              ║",
         "╠══════════════════════════════════╣",
-        `║  Models: ${String(count).padStart(3)} loaded                    ║`,
+        `║  Models: ${String(count).padStart(3)} loaded${fromCache ? " (cached)" : ""}         ║`,
         hasApiKey ? "║  API Key: ✅ Configured              ║" : "║  API Key: ❌ Not configured          ║",
         "╠══════════════════════════════════╣",
         "║  Commands:                       ║",
@@ -115,7 +129,7 @@ export default async function (pi: ExtensionAPI) {
       try {
         if (args?.trim()) {
           const name = args.trim()
-          const detail = await fetchModelStabilityDetail(name)
+          const detail = await fetchModelStabilityDetail(name, { signal: ctx.signal })
           const lines = [
             `📊 ${detail.model_name}`,
             `━━━━━━━━━━━━━━━━━━━━━━`,
@@ -128,7 +142,7 @@ export default async function (pi: ExtensionAPI) {
           ]
           ctx.ui.notify(lines.join("\n"), "info")
         } else {
-          const summary = await fetchModelStabilitySummary()
+          const summary = await fetchModelStabilitySummary({ signal: ctx.signal })
           if (summary.length === 0) {
             ctx.ui.notify("📊 No stability data available for any model yet.", "warning")
             return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openmodel-provider",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "pi custom provider for OpenModel.ai - Multi-model AI gateway",
   "type": "module",
   "keywords": [

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,9 +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
@@ -58,41 +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
-}
-
-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
@@ -113,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
@@ -131,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
@@ -147,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
@@ -162,7 +157,17 @@ async function fetchLegacyModels(options?: {
   return modelMap
 }
 
-/** Fetch models from OpenModel API (public, no auth required) */
+// ──────────────────────────────────────────────
+// Orchestration
+// ──────────────────────────────────────────────
+
+/**
+ * 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
@@ -178,33 +183,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)
     }
 
+    // Parse pricing
     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)
 
+    // Build model config
     const reasoning = web.supports.supports_reasoning ?? false
+    const compat = compatForProvider(web.provider_key, api, reasoning)
 
     const base = {
       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),
@@ -219,6 +229,7 @@ export async function fetchOpenModelModels(options?: {
     const model = {
       ...base,
       ...(reasoning ? { thinkingLevelMap: thinkingLevelMapForApi(api) } : {}),
+      ...(compat ? { compat } : {}),
     } as unknown as OpenModelProviderModel
 
     models.push(model)

package/src/api/stability.ts

@@ -0,0 +1,184 @@
+/**
+ * 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"
+
+export const STABILITY_SUMMARY_URL =
+  "https://api.openmodel.ai/web/v1/model-stability/summary"
+
+/** Health status derived from success rate */
+export type HealthStatus =
+  | "operational"
+  | "healthy"
+  | "degraded"
+  | "unstable"
+  | "no_data"
+
+/** 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: determineHealthFallback(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: determineHealthFallback(
+      body.data.summary.success_rate,
+      body.data.confidence,
+    ),
+  }
+}
+
+/**
+ * Inline fallback to avoid circular dependency with formatters.
+ * determineHealth() in formatters/stability.ts is the canonical version.
+ */
+function determineHealthFallback(
+  successRate: number,
+  confidence: ConfidenceLevel,
+): HealthStatus {
+  if (confidence === "low") return "no_data"
+  if (successRate >= 99.9) return "operational"
+  if (successRate >= 99) return "healthy"
+  if (successRate >= 95) return "degraded"
+  return "unstable"
+}