pi-openmodel-provider 0.2.16 → 0.2.17

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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

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
 
@@ -162,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,15 +5,16 @@
  */
 
 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) {
@@ -84,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openmodel-provider",
-  "version": "0.2.16",
+  "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,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
-}
-
-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: Web API (public, pageable)
+// ──────────────────────────────────────────────
 
-/** 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,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
@@ -220,26 +183,30 @@ 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)
 
@@ -247,7 +214,7 @@ export async function fetchOpenModelModels(options?: {
       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),

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"
+}

package/src/auth/login.ts

@@ -0,0 +1,132 @@
+/**
+ * OpenModel authentication for pi's /login flow.
+ *
+ * Flow:
+ * 1. Opens the OpenModel Console in the browser
+ * 2. Prompts the user to paste their API key
+ * 3. Validates the key format (must start with "om-")
+ * 4. Stores credentials in pi's auth.json
+ *
+ * Since OpenModel API keys don't expire, "refresh" is a no-op.
+ */
+
+import { sanitizeApiKey, isValidApiKey } from "./validate.ts"
+
+export interface OAuthLoginCallbacks {
+  onAuth(params: { url: string }): void;
+  onPrompt(params: { message: string }): Promise<string>;
+  onSelect?(params: {
+    message: string;
+    options: { id: string; label: string }[];
+  }): Promise<string | undefined>;
+}
+
+export interface OAuthCredentials {
+  refresh: string;
+  access: string;
+  expires: number;
+}
+
+export const CONSOLE_URL = "https://console.openmodel.ai"
+const FIVE_YEARS_MS = 5 * 365 * 24 * 60 * 60 * 1000 // API keys don't expire
+
+function credentialsFromApiKey(apiKey: string): OAuthCredentials {
+  return {
+    refresh: apiKey,
+    access: apiKey,
+    expires: Date.now() + FIVE_YEARS_MS,
+  }
+}
+
+async function promptForKey(
+  callbacks: OAuthLoginCallbacks,
+  message: string,
+): Promise<string> {
+  return sanitizeApiKey(await callbacks.onPrompt({ message }))
+}
+
+async function handleKey(
+  apiKey: string,
+  callbacks: OAuthLoginCallbacks,
+): Promise<OAuthCredentials> {
+  if (!apiKey) {
+    throw new Error("No OpenModel API key provided")
+  }
+
+  if (!isValidApiKey(apiKey)) {
+    // Offer retry when onSelect is available
+    if (callbacks.onSelect) {
+      const retry = await callbacks.onSelect({
+        message: `Invalid API key format. Key should start with "om-". Try again?`,
+        options: [
+          { id: "retry", label: "🔄 Try again" },
+          { id: "cancel", label: "❌ Cancel" },
+        ],
+      })
+      if (retry === "retry") {
+        return login(callbacks)
+      }
+    }
+    throw new Error("Login cancelled - invalid API key")
+  }
+
+  return credentialsFromApiKey(apiKey)
+}
+
+/**
+ * /login openmodel handler.
+ *
+ * Offers two options:
+ * 1. Browser: opens the OpenModel Console so the user can create/copy a key
+ * 2. Manual: prompts the user to paste their API key
+ */
+export async function login(
+  callbacks: OAuthLoginCallbacks,
+): Promise<OAuthCredentials> {
+  // Determine login method (onSelect is optional)
+  let method: string | undefined
+  if (callbacks.onSelect) {
+    method = await callbacks.onSelect({
+      message: "How would you like to authenticate with OpenModel?",
+      options: [
+        { id: "browser", label: "🌐 Open console in browser" },
+        { id: "paste", label: "📋 Paste API key manually" },
+      ],
+    })
+  }
+
+  if (!method) {
+    throw new Error("Login cancelled")
+  }
+
+  if (method === "browser") {
+    callbacks.onAuth({ url: CONSOLE_URL })
+
+    const apiKey = await promptForKey(
+      callbacks,
+      `1. Open ${CONSOLE_URL}\n2. In the sidebar, click on API Keys\n3. Click Create API Key, give it a name, and copy the generated key\n4. Paste the key here (starts with "om-"):`,
+    )
+
+    return handleKey(apiKey, callbacks)
+  }
+
+  // Manual paste
+  const apiKey = await promptForKey(callbacks, 'Paste your OpenModel API key (starts with "om-"):')
+  return handleKey(apiKey, callbacks)
+}
+
+/**
+ * OpenModel API keys don't expire, so "refresh" is a no-op.
+ */
+export async function refreshToken(
+  credentials: OAuthCredentials,
+): Promise<OAuthCredentials> {
+  return credentialsFromApiKey(credentials.refresh)
+}
+
+/**
+ * Extract the API key from stored credentials.
+ */
+export function getApiKey(credentials: OAuthCredentials): string {
+  return credentials.access
+}

package/src/auth/validate.ts

@@ -0,0 +1,33 @@
+/**
+ * API key validation and sanitization.
+ *
+ * Sanitizes user-pasted input (handling terminal paste wrappers, control chars)
+ * and validates that the key matches OpenModel's "om-..." format.
+ */
+
+/**
+ * Sanitize API key input, removing terminal paste wrappers and control chars.
+ */
+export function sanitizeApiKey(input: string): string {
+  const esc = String.fromCharCode(27)
+  return Array.from(
+    input
+      .replaceAll(`${esc}[200~`, "")
+      .replaceAll(`${esc}[201~`, "")
+      .replaceAll("[200~", "")
+      .replaceAll("[201~", ""),
+  )
+    .filter((char) => {
+      const code = char.charCodeAt(0)
+      return code > 31 && code !== 127
+    })
+    .join("")
+    .trim()
+}
+
+/**
+ * Validate that an API key looks like a valid OpenModel key.
+ */
+export function isValidApiKey(key: string): boolean {
+  return /^om-[A-Za-z0-9_-]+$/.test(key)
+}

package/src/cache.ts

@@ -8,7 +8,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { homedir } from "node:os"
-import type { OpenModelProviderModel } from "./models.ts"
+import type { OpenModelProviderModel } from "./api/models.ts"
 
 export const CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
 

package/src/formatters/stability.ts

@@ -0,0 +1,48 @@
+/**
+ * Formatters for model stability presentation.
+ *
+ * Pure functions — no side effects, no network calls.
+ * Transforms health/confidence data into display-ready strings.
+ */
+
+import type { HealthStatus, ConfidenceLevel } from "../api/stability.ts"
+
+/** Determine health status from success rate and confidence */
+export function determineHealth(
+  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"
+}
+
+/** Format health status with emoji */
+export function formatHealthStatus(status: HealthStatus): string {
+  switch (status) {
+    case "operational":
+      return "✅ Operational"
+    case "healthy":
+      return "🟢 Healthy"
+    case "degraded":
+      return "🟡 Degraded"
+    case "unstable":
+      return "🔴 Unstable"
+    case "no_data":
+      return "⚪ No Data"
+  }
+}
+
+/** Format confidence level */
+export function formatConfidence(level: ConfidenceLevel): string {
+  switch (level) {
+    case "high":
+      return "🟢 High"
+    case "medium":
+      return "🟡 Medium"
+    case "low":
+      return "⚪ Low"
+  }
+}

package/src/providers/compat.ts

@@ -0,0 +1,50 @@
+/**
+ * Provider-specific compatibility flags for pi.
+ *
+ * These flags tell pi about each provider's quirks and capabilities,
+ * enabling optimal protocol compatibility (thinking formats, session
+ * affinity, cache control, etc.).
+ */
+
+import type { ApiProtocol } from "./protocols.ts"
+
+/**
+ * Determine compat flags based on provider and API.
+ * Returns undefined when no special flags are needed.
+ */
+export function compatForProvider(
+  providerKey: string,
+  api: ApiProtocol,
+  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
+  }
+}

package/src/providers/pricing.ts

@@ -0,0 +1,12 @@
+/**
+ * Pricing utilities for converting cost-per-token to $/M tokens.
+ *
+ * OpenModel API returns prices in cost-per-token (microdollars).
+ * We convert to dollars per million tokens for pi's display.
+ */
+
+/** Convert cost-per-token to dollars per million tokens */
+export function pricePerMillion(costPerToken: number | undefined): number {
+  if (costPerToken === undefined || costPerToken === null) return 0
+  return Math.round(costPerToken * 1_000_000 * 1000) / 1000
+}

package/src/providers/protocols.ts

@@ -0,0 +1,53 @@
+/**
+ * Protocol detection and thinking level mapping per provider.
+ *
+ * Determines the correct pi protocol (anthropic-messages, openai-responses,
+ * google-generative-ai) based on provider protocol lists and fallback inference.
+ */
+
+export type ApiProtocol = "anthropic-messages" | "openai-responses" | "google-generative-ai"
+
+/** Infer protocol from a list of supported protocol strings */
+export function determineApi(
+  protocols: string[],
+  _provider: string,
+): ApiProtocol | 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
+}
+
+/** Fallback: infer API protocol from provider name when legacy endpoint fails */
+export function inferApiFromProvider(providerKey: string): ApiProtocol {
+  if (["openai"].includes(providerKey)) return "openai-responses"
+  if (["gemini"].includes(providerKey)) return "google-generative-ai"
+  return "anthropic-messages"
+}
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+
+/** Build a thinking-level map appropriate for the protocol */
+export function thinkingLevelMapForApi(
+  api: ApiProtocol,
+): Partial<Record<ThinkingLevel, 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 {}
+}

package/src/auth.ts

@@ -1,179 +0,0 @@
-/**
- * OpenModel authentication for pi's /login flow.
- *
- * Provides OAuth integration so users can authenticate via:
- *   /login openmodel
- *
- * Flow:
- * 1. Opens the OpenModel Console in the browser
- * 2. Prompts the user to paste their API key
- * 3. Validates the key format (must start with "om-")
- * 4. Stores credentials in pi's auth.json
- *
- * Since OpenModel API keys don't expire, "refresh" is a no-op.
- */
-
-export interface OAuthLoginCallbacks {
-  onAuth(params: { url: string }): void;
-  onPrompt(params: { message: string }): Promise<string>;
-  onSelect?(params: {
-    message: string;
-    options: { id: string; label: string }[];
-  }): Promise<string | undefined>;
-}
-
-export interface OAuthCredentials {
-  refresh: string;
-  access: string;
-  expires: number;
-}
-
-const CONSOLE_URL = "https://console.openmodel.ai";
-const FIVE_YEARS_MS = 5 * 365 * 24 * 60 * 60 * 1000; // API keys don't expire
-
-/**
- * Sanitize API key input, removing terminal paste wrappers and control chars.
- */
-export function sanitizeApiKey(input: string): string {
-  const esc = String.fromCharCode(27);
-  return Array.from(
-    input
-      .replaceAll(`${esc}[200~`, "")
-      .replaceAll(`${esc}[201~`, "")
-      .replaceAll("[200~", "")
-      .replaceAll("[201~", ""),
-  )
-    .filter((char) => {
-      const code = char.charCodeAt(0);
-      return code > 31 && code !== 127;
-    })
-    .join("")
-    .trim();
-}
-
-/**
- * Validate that an API key looks like a valid OpenModel key.
- */
-export function isValidApiKey(key: string): boolean {
-  return /^om-[A-Za-z0-9_-]+$/.test(key);
-}
-
-function credentialsFromApiKey(apiKey: string): OAuthCredentials {
-  return {
-    refresh: apiKey,
-    access: apiKey,
-    expires: Date.now() + FIVE_YEARS_MS,
-  };
-}
-
-/**
- * /login openmodel handler.
- *
- * Offers two options:
- * 1. Browser: opens the OpenModel Console so the user can create/copy a key
- * 2. Manual: prompts the user to paste their API key
- */
-export async function login(
-  callbacks: OAuthLoginCallbacks,
-): Promise<OAuthCredentials> {
-  // Offer login method choice (onSelect is optional)
-  let method: string | undefined;
-  if (callbacks.onSelect) {
-    method = await callbacks.onSelect({
-      message: "How would you like to authenticate with OpenModel?",
-      options: [
-        { id: "browser", label: "🌐 Open console in browser" },
-        { id: "paste", label: "📋 Paste API key manually" },
-      ],
-    });
-  }
-
-  if (!method) {
-    throw new Error("Login cancelled");
-  }
-
-  if (method === "browser") {
-    // Open the OpenModel Console in the browser
-    callbacks.onAuth({ url: CONSOLE_URL });
-
-    // Then prompt for the API key
-    const apiKey = sanitizeApiKey(
-      await callbacks.onPrompt({
-        message: `1. Open ${CONSOLE_URL}\n2. In the sidebar, click on API Keys\n3. Click Create API Key, give it a name, and copy the generated key\n4. Paste the key here (starts with "om-"):`,
-      }),
-    );
-
-    if (!apiKey) {
-      throw new Error("No OpenModel API key provided");
-    }
-
-    if (!isValidApiKey(apiKey)) {
-      let retry: string | undefined;
-      if (callbacks.onSelect) {
-        retry = await callbacks.onSelect({
-          message: `Invalid API key format. Key should start with "om-". Try again?`,
-          options: [
-            { id: "retry", label: "🔄 Try again" },
-            { id: "cancel", label: "❌ Cancel" },
-          ],
-        });
-      }
-
-      if (retry !== "retry") {
-        throw new Error("Login cancelled - invalid API key");
-      }
-
-      // Recursive retry
-      return login(callbacks);
-    }
-
-    return credentialsFromApiKey(apiKey);
-  }
-
-  // Manual paste
-  const apiKey = sanitizeApiKey(
-    await callbacks.onPrompt({
-      message: 'Paste your OpenModel API key (starts with "om-"):',
-    }),
-  );
-
-  if (!apiKey) {
-    throw new Error("No OpenModel API key provided");
-  }
-
-  if (!isValidApiKey(apiKey)) {
-    const retry = callbacks.onSelect
-      ? await callbacks.onSelect({
-          message: `Invalid API key format. Key should start with "om-". Try again?`,
-          options: [
-            { id: "retry", label: "🔄 Try again" },
-            { id: "cancel", label: "❌ Cancel" },
-          ],
-        })
-      : undefined;
-
-    if (retry !== "retry") {
-      throw new Error("Login cancelled - invalid API key");
-    }
-
-    return login(callbacks);
-  }
-
-  return credentialsFromApiKey(apiKey);
-}
-
-/**
- * OpenModel API keys don't expire, so "refresh" is a no-op.
- */
-export async function refreshToken(
-  credentials: OAuthCredentials,
-): Promise<OAuthCredentials> {
-  return credentialsFromApiKey(credentials.refresh);
-}
-
-/**
- * Extract the API key from stored credentials.
- */
-export function getApiKey(credentials: OAuthCredentials): string {
-  return credentials.access;
-}

package/src/stability.ts

@@ -1,204 +0,0 @@
-/**
- * OpenModel.ai Model Stability API.
- *
- * 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
- */
-
-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;
-}
-
-/** Determine health status from success rate */
-function determineHealth(
-  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";
-}
-
-/** 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,
-    ),
-  };
-}
-
-/** Format health status with emoji */
-export function formatHealthStatus(status: HealthStatus): string {
-  switch (status) {
-    case "operational":
-      return "✅ Operational";
-    case "healthy":
-      return "🟢 Healthy";
-    case "degraded":
-      return "🟡 Degraded";
-    case "unstable":
-      return "🔴 Unstable";
-    case "no_data":
-      return "⚪ No Data";
-  }
-}
-
-/** Format confidence level */
-export function formatConfidence(level: ConfidenceLevel): string {
-  switch (level) {
-    case "high":
-      return "🟢 High";
-    case "medium":
-      return "🟡 Medium";
-    case "low":
-      return "⚪ Low";
-  }
-}