@pwguler/pi-pengepul-provider 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,96 @@
+# @pwguler/pi-pengepul-provider
+
+A custom provider for [pi](https://github.com/earendil-works/pi) that connects to
+[pengepul](https://github.com/pwguler/pengepul), a local relay that pools your
+Claude / Codex subscription accounts and serves them over native wire protocols.
+
+pengepul pools several subscription accounts per provider and spreads requests
+across them, so pi runs on your subscription instead of a per-token API key.
+This extension registers pengepul as a provider so `/model` shows the models
+your relay serves.
+
+## Install
+
+From npm:
+
+```sh
+pi install npm:@pwguler/pi-pengepul-provider
+```
+
+Or straight from GitHub (no npm account needed):
+
+```sh
+pi install git:github.com/pwguler/pi-pengepul-provider
+```
+
+Pin a release so updates don't move under you:
+
+```sh
+pi install git:github.com/pwguler/pi-pengepul-provider@v0.1.0
+```
+
+To update a git-installed package later:
+
+```sh
+pi install git:github.com/pwguler/pi-pengepul-provider@v0.2.0
+```
+
+Start or reload pi, then select a model with `/model`. Pengepul models are
+prefixed `pengepul/<id>`. To try it without installing, use
+`pi -e git:github.com/pwguler/pi-pengepul-provider`.
+
+## What it does
+
+- Registers the `pengepul` provider against your relay's base URL
+  (`http://127.0.0.1:8317` by default).
+- Discovers models from `GET /v1/models`, maps each to the right wire:
+  - `claude-*` / `anthropic/*` and `owned_by: anthropic` → Anthropic Messages
+    (`POST /v1/messages`),
+  - `gpt-*` / `o<N>` / `codex-*` and `<provider>/<model>` → OpenAI Chat
+    Completions (`POST /v1/chat/completions`).
+- Takes context window, max output, pricing, and image input from what the
+  relay advertises (pengepul >= 0.6.0 sends `context_window`,
+  `max_output_tokens`, `input_modalities`, `pricing`). Fields the relay omits
+  fall back to pi's builtin catalog for the same id, then to family
+  heuristics.
+- Caches the last successful catalog at `<agent-dir>/pengepul-models.json`, so
+  startup does not wait on the network and a briefly absent relay is covered.
+- Reuses pi's built-in stream functions for both wires — no custom transport.
+- Registers no commands: the catalog refreshes on every startup.
+
+## Configuration
+
+| Setting | Env var | Default |
+|---|---|---|
+| Relay base URL | `PENGEPUL_BASE_URL` | `http://127.0.0.1:8317` |
+| API key | `PENGEPUL_API_KEY` | read from `~/.pengepul/config.yaml` |
+| Config path | `PENGEPUL_CONFIG` | `~/.pengepul/config.yaml` |
+| Model cache path | `PENGEPUL_MODELS_CACHE` | `<agent-dir>/pengepul-models.json` |
+| Discovery timeout | `PENGEPUL_MODELS_TIMEOUT_MS` | `10000` |
+
+The API key is read from `~/.pengepul/config.yaml` (`api-keys[0]`, the
+`sk-local-...` key pengepul generates on first run) unless `PENGEPUL_API_KEY`
+is set.
+
+## Notes
+
+- pengepul >= 0.6.0 advertises per-model context windows, output caps,
+  modalities, and pricing on `/v1/models`, and that is what the provider
+  registers; older relays (or ids the metadata has not reached) fall back to
+  pi's builtin catalog. Your subscription, not a per-token meter, is what
+  pengepul bills against — displayed costs are upstream list prices.
+- The relay must be running and reachable for discovery to succeed. Without a
+  cached catalog on a first start, pengepul models stay unavailable until a
+  start with the relay up.
+
+## Development
+
+```sh
+bun test
+npx tsc --noEmit
+bun scripts/e2e-live.ts # live e2e against a running relay; sends one tiny completion
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pwguler/pi-pengepul-provider",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "pi custom provider for pengepul, a local relay that pools your Claude/Codex subscriptions. Connects pi to http://127.0.0.1:8317 over the native Anthropic Messages and OpenAI Chat Completions wires.",
+  "license": "MIT",
+  "author": "pwguler",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pwguler/pi-pengepul-provider.git"
+  },
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "pi-pengepul-provider",
+    "pengepul",
+    "provider"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/bun": "^1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api-key.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolve pengepul's local API key.
+ *
+ * pengepul authenticates every request with a static key from its config:
+ * `~/.pengepul/config.yaml`, under `api-keys:` (the first is generated on first
+ * run and is `sk-local-...`). Clients send it as `Authorization: Bearer <key>`
+ * or `x-api-key: <key>`.
+ *
+ * Precedence: an explicit env override wins, then the config file. The config
+ * read is injected so this module stays io-free and testable.
+ */
+
+const DEFAULT_CONFIG_PATH = "~/.pengepul/config.yaml"
+
+export type ApiKeySource = "env" | "config" | "none"
+
+export interface ApiKeyResolution {
+  /** The resolved key, or undefined when none could be found. */
+  key?: string
+  source: ApiKeySource
+}
+
+export const API_KEY_ENV = "PENGEPUL_API_KEY"
+export const CONFIG_PATH_ENV = "PENGEPUL_CONFIG"
+
+/**
+ * Resolve the key from an env map and a config-file reader.
+ *
+ * @param env          the environment (or a test substitution for it).
+ * @param readConfig   reads a config file's text by path, or undefined when the
+ *                     path is unwritable/absent. Injected to keep this pure.
+ */
+export function resolveApiKey(
+  env: Record<string, string | undefined>,
+  readConfig: (path: string) => string | undefined,
+): ApiKeyResolution {
+  const envKey = env[API_KEY_ENV]
+  if (envKey && envKey.trim() !== "") return { key: envKey, source: "env" }
+
+  const configPath = env[CONFIG_PATH_ENV] ?? DEFAULT_CONFIG_PATH
+  const configText = readConfig(configPath)
+  if (configText === undefined) return { source: "none" }
+
+  const keys = extractApiKeys(configText)
+  const first = keys[0]
+  if (first) return { key: first, source: "config" }
+
+  return { source: "none" }
+}
+
+/**
+ * Extract `api-keys:` entries from pengepul's YAML config, without a YAML
+ * dependency. Handles both the inline-flow form and the block-sequence form:
+ *
+ *   api-keys: [sk-local-a, sk-local-b]
+ *   api-keys:
+ *     - sk-local-a
+ *     - sk-local-b
+ */
+export function extractApiKeys(configText: string): string[] {
+  const lines = configText.split(/\r?\n/)
+  const keys: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line === undefined) continue
+
+    const match = /^\s*api-keys:\s*(.*)$/.exec(line)
+    if (!match) continue
+
+    const rest = (match[1] ?? "").trim()
+    if (rest.startsWith("[")) {
+      // Inline flow sequence: [a, b, c]
+      for (const token of rest.slice(1, -1).split(",")) {
+        const key = token.trim().replace(/^["']|["']$/g, "")
+        if (key) keys.push(key)
+      }
+    } else if (rest === "" || rest === "|" || rest === ">") {
+      // Block sequence follows. Sequence entries may sit at any indent —
+      // pengepul itself writes them flush with the key (`- sk-local-…`) —
+      // so scan forward through blanks, comments, and `- ` entries and
+      // stop at the first line that starts another key.
+      for (let j = i + 1; j < lines.length; j++) {
+        const item = lines[j]
+        if (item === undefined) continue
+        const token = item.trim()
+        if (token === "" || token.startsWith("#")) continue
+        if (!token.startsWith("-")) break
+        const value = token.slice(1).trim().replace(/^["']|["']$/g, "")
+        if (value) keys.push(value)
+      }
+    } else {
+      // Single inline scalar: api-keys: sk-local-a
+      const value = rest.replace(/^["']|["']$/g, "")
+      if (value) keys.push(value)
+    }
+    break
+  }
+
+  return keys
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve pengepul connection and cache settings from the environment.
+ *
+ * Kept small and pure: takes an env map and the host's agent dir, returns the
+ * connection defaults a test can pin down.
+ */
+
+import { join } from "node:path"
+
+import { DEFAULT_RELAY_BASE } from "./models.ts"
+
+export const RELAY_BASE_ENV = "PENGEPUL_BASE_URL"
+export const MODELS_CACHE_ENV = "PENGEPUL_MODELS_CACHE"
+export const MODELS_TIMEOUT_MS_ENV = "PENGEPUL_MODELS_TIMEOUT_MS"
+
+export interface PengepulSettings {
+  /** The relay base URL (may or may not end in /v1). */
+  relayBase: string
+  /** Where the model catalog is cached; defaults to `<agent-dir>/pengepul-models.json`. */
+  modelsCachePath: string
+  /** Discovery timeout in milliseconds. */
+  modelsTimeoutMs: number
+}
+
+export function resolveSettings(
+  env: Record<string, string | undefined>,
+  agentDir: string,
+): PengepulSettings {
+  const relayBase = env[RELAY_BASE_ENV] ?? DEFAULT_RELAY_BASE
+  const modelsCachePath =
+    env[MODELS_CACHE_ENV] ?? join(agentDir, "pengepul-models.json")
+  const rawTimeout = env[MODELS_TIMEOUT_MS_ENV]
+  const parsedTimeout = rawTimeout ? Number(rawTimeout) : NaN
+  const modelsTimeoutMs =
+    Number.isFinite(parsedTimeout) && parsedTimeout > 0
+      ? parsedTimeout
+      : 10_000
+
+  return { relayBase, modelsCachePath, modelsTimeoutMs }
+}

package/src/dialect.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure pengepul dialect mapping.
+ *
+ * pengepul is a local relay that speaks *both* native wires and routes each
+ * request by model id. This module maps a model id (and the owned_by value
+ * pengepul advertises on `/v1/models`) to the pi-ai API dialect pi should use,
+ * and to the base URL pi's built-in stream functions should point at.
+ *
+ * No pi imports, no io: this is unit-testable with a table of inputs.
+ *
+ * pengepul routing (from its `resolve_id` / heuristic):
+ *   - `anthropic/...` and bare `claude-*` / `anthropic`  -> Anthropic Messages
+ *     (`POST /v1/messages`). pi's Anthropic SDK appends `/v1/messages`, so the
+ *     base URL is the relay root (no trailing `/v1`).
+ *   - `codex/...`, bare `gpt-*` / `o<N>` / `codex-*`, and any other
+ *     `<provider>/<model>` prefix      -> OpenAI Chat Completions
+ *     (`POST /v1/chat/completions`). pi's OpenAI SDK appends `/chat/completions`,
+ *     so the base URL must end in `/v1`.
+ */
+
+export type PengepulDialect = "anthropic-messages" | "openai-completions"
+
+/** Which wire pengepul serves a given model id on. */
+export function dialectForModelId(id: string): PengepulDialect {
+  const slash = id.indexOf("/")
+  if (slash !== -1) {
+    const prefix = id.slice(0, slash).toLowerCase()
+    return prefix === "anthropic" ? "anthropic-messages" : "openai-completions"
+  }
+
+  const lower = id.toLowerCase()
+  if (lower.startsWith("claude-") || lower.startsWith("anthropic")) {
+    return "anthropic-messages"
+  }
+  if (lower.startsWith("gpt-") || lower.startsWith("codex-") || isOpenAIModelPattern(lower)) {
+    return "openai-completions"
+  }
+
+  // Unknown bare id: prefer Messages only when the upstream explicitly says so;
+  // otherwise assume Chat Completions (the relay's generic-namespace default).
+  return "openai-completions"
+}
+
+function isOpenAIModelPattern(lower: string): boolean {
+  // o1, o3-mini, o4, ... — the OpenAI reasoning-family names pengepul routes to codex.
+  const first = lower[0]
+  const second = lower[1]
+  if (first === undefined || second === undefined) return false
+  if (lower.length >= 2 && first === "o" && /^[1-9]/.test(second)) return true
+  return false
+}
+
+/**
+ * The base URL pi's built-in stream should use for a dialect.
+ *
+ * Accepts a relay base that may or may not end in `/v1` (pengepul's own config
+ * notes "the base url may end in /v1"); we normalize so the Anthropic Messages
+ * SDK gets the root and the OpenAI Chat Completions SDK gets `/v1`, and neither
+ * produces a doubled `/v1/v1`.
+ */
+export function baseUrlForDialect(baseUrl: string, dialect: PengepulDialect): string {
+  const root = normalizeRootBaseUrl(baseUrl)
+  return dialect === "anthropic-messages" ? root : `${root}/v1`
+}
+
+/** Strip a trailing `/v1` (and any trailing slashes) so we can re-add it per dialect. */
+export function normalizeRootBaseUrl(baseUrl: string): string {
+  let out = baseUrl.replace(/\/+$/g, "")
+  if (out.endsWith("/v1")) out = out.slice(0, -3)
+  return out.replace(/\/+$/g, "")
+}
+
+/** The discovery endpoint for a relay base. */
+export function modelsUrl(baseUrl: string): string {
+  return `${normalizeRootBaseUrl(baseUrl)}/v1/models`
+}

package/src/index.ts

@@ -0,0 +1,146 @@
+/**
+ * @pwguler/pi-pengepul-provider entry point - the real edge adapter.
+ *
+ * Registers pengepul as a pi custom provider. pengepul is a local relay
+ * (`http://127.0.0.1:8317`) that pools your Claude/Codex subscriptions and
+ * speaks both native wires. The pure core lives in `./dialect.ts`, `./models.ts`
+ * and `./runtime.ts`; this file adapts them to the pi ExtensionAPI seam.
+ */
+
+import {
+  getAgentDir,
+  type ExtensionAPI,
+  type ProviderConfig,
+} from "@earendil-works/pi-coding-agent"
+import { getBuiltinModel, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all"
+import { readFileSync } from "node:fs"
+
+import { resolveApiKey } from "./api-key.ts"
+import { resolveSettings } from "./config.ts"
+import { modelsUrl } from "./dialect.ts"
+import {
+  loadCachedPengepulModels,
+  loadPengepulModels,
+  toProviderModelConfigs,
+  type PengepulModel,
+} from "./models.ts"
+import { createPengepulRuntime } from "./runtime.ts"
+
+function expandHome(path: string): string {
+  if (path === "~") return process.env.HOME ?? path
+  if (path.startsWith("~/")) return `${process.env.HOME ?? ""}${path.slice(1)}`
+  return path
+}
+
+function readConfigText(path: string): string | undefined {
+  try {
+    return readFileSync(expandHome(path), "utf-8")
+  } catch {
+    return undefined
+  }
+}
+
+/** The metadata fields the lookup extracts from a pi catalog entry. */
+function metaFromModel(model: NonNullable<ReturnType<typeof getBuiltinModel>>) {
+  return {
+    reasoning: model.reasoning,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+    input: model.input,
+    cost: model.cost,
+    ...(model.thinkingLevelMap ? { thinkingLevelMap: model.thinkingLevelMap } : {}),
+  }
+}
+
+/**
+ * Multi-catalog lookup over pi's builtin models. A commandcode id can live
+ * in several catalogs: verbatim under an aggregator (`openrouter`, `baseten`,
+ * `together`, ...), bare under a vendor catalog (`deepseek`, `google`,
+ * `xai`, ...), or bare lowercased. Try those shapes in that order and take
+ * the first hit; reasoning metadata and the thinkingLevelMap flow from it.
+ */
+function createBuiltinLookup(): (id: string, dialect: string) => ReturnType<typeof metaFromModel> | undefined {
+  type Entry = { provider: string; id: string };
+  const exact = new Map<string, Entry>()
+  const lower = new Map<string, Entry>()
+  for (const provider of getBuiltinProviders()) {
+    for (const model of getBuiltinModels(provider) ?? []) {
+      if (!exact.has(model.id)) exact.set(model.id, { provider, id: model.id })
+      if (!lower.has(model.id.toLowerCase())) lower.set(model.id.toLowerCase(), { provider, id: model.id })
+    }
+  }
+  const segments = new Map<string, Entry>()
+  for (const [key, entry] of exact) {
+    const slash = key.lastIndexOf("/")
+    const segment = slash === -1 ? key : key.slice(slash + 1)
+    if (!segments.has(segment)) segments.set(segment, entry)
+  }
+
+  return (id, dialect) => {
+    const candidates: Array<Entry | undefined> = [
+      exact.get(id),
+      exact.get(bareOf(id)),
+      segments.get(bareOf(id)),
+      lower.get(id.toLowerCase()),
+      lower.get(bareOf(id).toLowerCase()),
+    ]
+    for (const candidate of candidates) {
+      if (candidate === undefined) continue
+      const model = getBuiltinModel(candidate.provider as never, candidate.id as never)
+      if (model) return metaFromModel(model)
+    }
+    return undefined
+  }
+}
+
+function bareOf(id: string): string {
+  const slash = id.lastIndexOf("/")
+  return slash === -1 ? id : id.slice(slash + 1)
+}
+
+function createProviderConfigFactory(relayBase: string, apiKey: string | undefined) {
+  return (models: readonly PengepulModel[]): ProviderConfig => ({
+    name: "Pengepul",
+    baseUrl: relayBase,
+    apiKey: apiKey ?? "$PENGEPUL_API_KEY",
+    api: "anthropic-messages",
+    models: toProviderModelConfigs(models, relayBase),
+  })
+}
+
+/**
+ * Model discovery and provider registration are async: the relay's catalog is
+ * fetched live (and cached), so the runtime handles the cache-first, then
+ * live-refresh dance. The config factory pins the base URL and key once.
+ */
+export default async function (pi: ExtensionAPI) {
+  const settings = resolveSettings(process.env, getAgentDir())
+  const apiKey = resolveApiKey(process.env, readConfigText).key
+
+  // The relay advertises only ids; context/pricing/modality numbers come from
+  // pi's builtin catalogs, searched across providers until one knows the id
+  // (aggregator, vendor, and last-segment shapes). The lookup is injected so
+  // the catalog logic stays free of pi-ai imports.
+  const lookupBuiltin = createBuiltinLookup()
+
+  const runtime = createPengepulRuntime(pi, {
+    loadModels: (signal) =>
+      loadPengepulModels({
+        url: modelsUrl(settings.relayBase),
+        apiKey,
+        cachePath: settings.modelsCachePath,
+        relayBase: settings.relayBase,
+        timeoutMs: settings.modelsTimeoutMs,
+        lookupBuiltin,
+        signal,
+      }),
+    loadCachedModels: () => loadCachedPengepulModels(settings.modelsCachePath),
+    createProviderConfig: createProviderConfigFactory(settings.relayBase, apiKey),
+  })
+
+  pi.on("session_shutdown", () => {
+    runtime.dispose()
+  })
+
+  await runtime.initialize()
+}

package/src/models.ts

@@ -0,0 +1,596 @@
+/**
+ * pengepul model discovery.
+ *
+ * Fetches the relay's model catalog (`GET /v1/models`) and maps it into the
+ * pi-ai `ProviderModelConfig` shape, mirroring the commandcode provider's
+ * cached-catalog design: a fresh fetch wins, a valid cache covers a briefly
+ * absent relay, and an empty result leaves pengepul models unavailable until
+ * the next successful startup refresh.
+ *
+ * The relay advertises id/owned_by and, since pengepul 0.6.0, optional
+ * per-model metadata: `context_window`, `max_output_tokens`,
+ * `input_modalities`, and `pricing`. That is the first-party truth for what
+ * this relay actually serves, so it wins. The rollout is partial (some ids
+ * still come back with ids only), so two fallbacks remain: pi's builtin
+ * catalog - pengepul forwards the same ids upstream, so pi's numbers are the
+ * next best source - and then family heuristics. The catalog lookup is
+ * injected, so this module imports nothing from pi-ai and tests pin it.
+ *
+ * The network/cache are injected so the catalog logic stays testable.
+ */
+
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { randomUUID } from "node:crypto"
+import { dirname } from "node:path"
+
+import { baseUrlForDialect, dialectForModelId } from "./dialect.ts"
+import type { PengepulDialect } from "./dialect.ts"
+
+export const DEFAULT_RELAY_BASE = "http://127.0.0.1:8317"
+export const DEFAULT_MODELS_TIMEOUT_MS = 10_000
+
+const DEFAULT_CONTEXT_WINDOW = 200_000
+const DEFAULT_MAX_TOKENS = 64_000
+const ZERO_COST: ModelCostRates = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+/** v2 cached pre-multi-catalog lookups (commandcode ids missed reasoning); reject it. */
+const MODEL_CACHE_VERSION = 3
+
+export type ModelInput = ("text" | "image")[]
+
+export interface ModelCostRates {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+/** The metadata pi's builtin catalog carries for a model the relay advertises. */
+export interface BuiltinModelMeta {
+  reasoning: boolean
+  contextWindow: number
+  maxTokens: number
+  input: ModelInput
+  cost: ModelCostRates
+  /** Level-to-wire mapping for reasoning params; undefined = pi's default. */
+  thinkingLevelMap?: Record<string, string | null>
+}
+
+/**
+ * Resolves a model's metadata from pi's builtin catalogs. The core passes the
+ * relay id and its dialect; the edge decides which catalogs to search
+ * (commandcode ids carry a routing prefix, so one id may exist verbatim under
+ * `openrouter`/`baseten`/... and bare under a vendor catalog like `deepseek`).
+ * Undefined when no pi catalog knows the id.
+ */
+export type BuiltinModelLookup = (id: string, dialect: PengepulDialect) => BuiltinModelMeta | undefined
+
+/** A pengepul model ready to become a pi `ProviderModelConfig`. */
+export interface PengepulModel {
+  id: string
+  name: string
+  dialect: PengepulDialect
+  reasoning: boolean
+  input: ModelInput
+  cost: ModelCostRates
+  contextWindow: number
+  maxTokens: number
+  /** Level-to-wire mapping inherited from the catalog; undefined = pi's default. */
+  thinkingLevelMap?: Record<string, string | null>
+}
+
+export interface PengepulModelSource {
+  models: readonly PengepulModel[]
+  /** "live" = fetched from the relay; "cache" = read from disk; "empty" = none. */
+  source: "live" | "cache" | "empty"
+  warning?: string
+}
+
+/** `anthropic/claude-opus-5` -> `claude-opus-5` (the id upstream actually serves). */
+export function bareId(id: string): string {
+  const slash = id.indexOf("/")
+  return slash === -1 ? id : id.slice(slash + 1)
+}
+
+/**
+ * Fallback for models pi's catalog does not know. Family-shaped but
+ * conservative; the builtin lookup wins whenever it has the id. The final
+ * branch treats unknown ids as non-reasoning, so an unrecognized id never
+ * gets reasoning params the upstream may reject.
+ */
+function heuristicMeta(id: string): BuiltinModelMeta {
+  const lower = bareId(id).toLowerCase()
+  if (lower.startsWith("claude-")) {
+    return { reasoning: true, contextWindow: 200_000, maxTokens: 64_000, input: ["text"], cost: ZERO_COST }
+  }
+  if (lower.startsWith("gpt-") || lower.startsWith("codex-") || /^o[1-9]/.test(lower)) {
+    return { reasoning: true, contextWindow: 272_000, maxTokens: 64_000, input: ["text"], cost: ZERO_COST }
+  }
+  return {
+    reasoning: false,
+    contextWindow: DEFAULT_CONTEXT_WINDOW,
+    maxTokens: DEFAULT_MAX_TOKENS,
+    input: ["text"],
+    cost: ZERO_COST,
+  }
+}
+
+/**
+ * Metadata pengepul itself advertises for a model (pengepul >= 0.6.0).
+ * Every field is optional: the rollout is partial and older relays send none.
+ * Returns undefined when the entry carries no usable metadata at all.
+ */
+export function metaFromRelayEntry(
+  entry: Record<string, unknown>,
+): Partial<BuiltinModelMeta> | undefined {
+  const contextWindow = optionalPositiveNumber(entry["context_window"])
+  const maxTokens = optionalPositiveNumber(entry["max_output_tokens"])
+  const input = optionalInputModalities(entry["input_modalities"])
+  const cost = optionalPricing(entry["pricing"])
+
+  if (
+    contextWindow === undefined &&
+    maxTokens === undefined &&
+    input === undefined &&
+    cost === undefined
+  ) {
+    return undefined
+  }
+  return {
+    ...(contextWindow !== undefined ? { contextWindow } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    ...(input !== undefined ? { input } : {}),
+    ...(cost !== undefined ? { cost } : {}),
+  }
+}
+
+function optionalPositiveNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+function optionalInputModalities(value: unknown): ModelInput | undefined {
+  if (!Array.isArray(value)) return undefined
+  const input = value.filter(
+    (entry): entry is "text" | "image" => entry === "text" || entry === "image",
+  )
+  return input.length > 0 ? input : undefined
+}
+
+function optionalPricing(value: unknown): ModelCostRates | undefined {
+  if (!isRecord(value)) return undefined
+  const input = optionalRate(value["input_per_million"])
+  const output = optionalRate(value["output_per_million"])
+  const cacheRead = optionalRate(value["cache_read_per_million"])
+  const cacheWrite = optionalRate(value["cache_write_per_million"])
+  if (input === undefined && output === undefined) return undefined
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+  }
+}
+
+function optionalRate(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined
+}
+
+/**
+ * Resolve a model's metadata, most trustworthy source first:
+ *   1. what pengepul advertises (first-party for this relay),
+ *   2. pi's builtin catalogs for the id (the same id upstream),
+ *   3. family heuristics.
+ * Sources merge per field, so a relay that sends only `context_window` still
+ * picks up pricing and modalities from the catalog.
+ */
+function metaFor(
+  entry: Record<string, unknown>,
+  id: string,
+  dialect: PengepulDialect,
+  lookup: BuiltinModelLookup | undefined,
+): BuiltinModelMeta {
+  const base = lookup?.(id, dialect) ?? heuristicMeta(id)
+  const relay = metaFromRelayEntry(entry)
+  return relay ? { ...base, ...relay } : base
+}
+
+function toPengepulModel(
+  entry: Record<string, unknown>,
+  lookup: BuiltinModelLookup | undefined,
+): PengepulModel {
+  const id = stringField(entry, "id")
+  const dialect = dialectForModelId(id)
+  const meta = metaFor(entry, id, dialect, lookup)
+  const ownedBy = entry["owned_by"]
+
+  // A model the relay tags `anthropic` is Claude-family, hence reasoning-
+  // capable, even when pi's catalog does not know its exact id yet.
+  const reasoning = meta.reasoning || ownedBy === "anthropic"
+
+  return {
+    id,
+    name: displayName(id),
+    dialect,
+    reasoning,
+    input: [...meta.input],
+    cost: { ...meta.cost },
+    contextWindow: meta.contextWindow,
+    maxTokens: meta.maxTokens,
+    ...(meta.thinkingLevelMap ? { thinkingLevelMap: { ...meta.thinkingLevelMap } } : {}),
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function stringField(record: Record<string, unknown>, key: string): string {
+  const value = record[key]
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Expected ${key} to be a non-empty string`)
+  }
+  return value
+}
+
+/** Parse the raw `/v1/models` body into models. Throws on a malformed body. */
+export function modelsFromApiResponse(
+  value: unknown,
+  lookupBuiltin?: BuiltinModelLookup,
+): readonly PengepulModel[] {
+  if (!isRecord(value)) throw new Error("Expected models response to be an object")
+  if (value["object"] !== "list") throw new Error("Expected models response object to be 'list'")
+
+  const data = value["data"]
+  if (!Array.isArray(data)) throw new Error("Expected models response data to be an array")
+  if (data.length === 0) throw new Error("pengepul returned an empty model catalog")
+
+  return data.map((entry) => {
+    if (!isRecord(entry)) throw new Error("Expected model entry to be an object")
+    return toPengepulModel(entry, lookupBuiltin)
+  })
+}
+
+/** Map models to pi `ProviderModelConfig` entries. Pure. */
+export function toProviderModelConfigs(
+  models: readonly PengepulModel[],
+  relayBase: string,
+): Array<{
+  id: string
+  name: string
+  api: PengepulDialect
+  baseUrl: string
+  reasoning: boolean
+  input: ("text" | "image")[]
+  cost: {
+    input: number
+    output: number
+    cacheRead: number
+    cacheWrite: number
+  }
+  contextWindow: number
+  maxTokens: number
+  thinkingLevelMap?: Record<string, string | null>
+  compat?: { forceAdaptiveThinking?: boolean }
+}> {
+  return models.map((model) => {
+    const adaptive = model.dialect === "anthropic-messages" && model.reasoning
+    return {
+      id: model.id,
+      name: model.name,
+      api: model.dialect,
+      baseUrl: baseUrlForDialect(relayBase, model.dialect),
+      reasoning: model.reasoning,
+      input: model.input,
+      cost: model.cost,
+      contextWindow: model.contextWindow,
+      maxTokens: model.maxTokens,
+      // Inherited level mapping (e.g. deepseek {high:"high"}) flows through;
+      // adaptive Claude models additionally mark "off" unsupported so the
+      // stream omits thinking:{type:"disabled"} (upstream rejects it).
+      ...(model.thinkingLevelMap || adaptive
+        ? { thinkingLevelMap: { ...(model.thinkingLevelMap ?? {}), ...(adaptive ? { off: null } : {}) } }
+        : {}),
+      // Reasoning-capable Claude models run on the adaptive-thinking wire:
+      // pi's streamSimple always passes thinkingEnabled:false when no level is
+      // selected, and the stream would send thinking:{type:"disabled"}, which
+      // the upstream rejects (400: "thinking.type.disabled is not supported
+      // for this model"). thinkingLevelMap.off = null marks "off" as
+      // unsupported so pi omits the thinking param entirely (server default
+      // = adaptive), and forceAdaptiveThinking routes an explicit level to
+      // {type:"adaptive"} + effort instead of budget_tokens.
+      ...(adaptive ? { compat: { forceAdaptiveThinking: true as const } } : {}),
+    }
+  })
+}
+
+/** Picker label: the bare model part of a relay id, suffixed. `anthropic/claude-opus-5` -> `claude-opus-5 (pengepul)`. */
+function displayName(id: string): string {
+  const slash = id.indexOf("/")
+  const bare = slash === -1 ? id : id.slice(slash + 1)
+  return `${bare} (pengepul)`
+}
+
+interface FetchModelsOptions {
+  url?: string
+  apiKey?: string
+  fetchImpl?: typeof fetch
+  signal?: AbortSignal
+  timeoutMs?: number
+  lookupBuiltin?: BuiltinModelLookup
+}
+
+interface LoadModelsOptions extends FetchModelsOptions {
+  cachePath: string
+  relayBase: string
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function abortError(reason: unknown): Error {
+  if (reason instanceof Error) return reason
+  return new DOMException("The operation was aborted", "AbortError")
+}
+
+function configuredTimeoutMs(timeoutMs: number | undefined): number {
+  return timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : DEFAULT_MODELS_TIMEOUT_MS
+}
+
+export function getModelsTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env["PENGEPUL_MODELS_TIMEOUT_MS"]
+  if (!raw) return DEFAULT_MODELS_TIMEOUT_MS
+  const parsed = Number(raw)
+  return configuredTimeoutMs(parsed)
+}
+
+class ModelDiscoveryTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`pengepul model discovery timed out after ${timeoutMs}ms`)
+    this.name = "ModelDiscoveryTimeoutError"
+  }
+}
+
+function runWithTimeout<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+  externalSignal: AbortSignal | undefined,
+): Promise<T> {
+  const controller = new AbortController()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let settled = false
+  let onExternalAbort: (() => void) | undefined
+
+  return new Promise<T>((resolve, reject) => {
+    const cleanup = () => {
+      if (timer !== undefined) clearTimeout(timer)
+      if (onExternalAbort && externalSignal) {
+        externalSignal.removeEventListener("abort", onExternalAbort)
+      }
+    }
+
+    const resolveOnce = (value: T) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(value)
+    }
+
+    const rejectOnce = (error: unknown) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      reject(error)
+    }
+
+    const abort = (reason: unknown) => {
+      const error = abortError(reason)
+      controller.abort(error)
+      rejectOnce(error)
+    }
+
+    if (externalSignal?.aborted) {
+      abort(externalSignal.reason)
+      return
+    }
+
+    onExternalAbort = () => abort(externalSignal?.reason)
+    externalSignal?.addEventListener("abort", onExternalAbort, { once: true })
+    timer = setTimeout(() => abort(new ModelDiscoveryTimeoutError(timeoutMs)), timeoutMs)
+
+    Promise.resolve()
+      .then(() => operation(controller.signal))
+      .then(resolveOnce, rejectOnce)
+  })
+}
+
+export async function fetchPengepulModels(
+  options: FetchModelsOptions = {},
+): Promise<readonly PengepulModel[]> {
+  const url = options.url ?? `${DEFAULT_RELAY_BASE}/v1/models`
+  const fetchImpl = options.fetchImpl ?? fetch
+  const apiKey = options.apiKey
+
+  const headers: Record<string, string> = {
+    accept: "application/json",
+  }
+  if (apiKey) headers["x-api-key"] = apiKey
+
+  const body: unknown = await runWithTimeout(
+    async (signal) => {
+      const response = await fetchImpl(url, { headers, signal })
+
+      if (response.status === 401 || response.status === 403) {
+        throw new Error(
+          `pengepul rejected the API key (${
+            response.status
+          }). Set PENGEPUL_API_KEY or check ~/.pengepul/config.yaml.`,
+        )
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch pengepul models: ${response.status} ${response.statusText}`,
+        )
+      }
+
+      return await response.json()
+    },
+    configuredTimeoutMs(options.timeoutMs),
+    options.signal,
+  )
+
+  return modelsFromApiResponse(body, options.lookupBuiltin)
+}
+
+function numberField(record: Record<string, unknown>, key: string): number {
+  const value = record[key]
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Expected ${key} to be a finite number`)
+  }
+  return value
+}
+
+function inputField(record: Record<string, unknown>, key: string): ModelInput {
+  const value = record[key]
+  if (!Array.isArray(value)) throw new Error(`Expected ${key} to be an array`)
+  return value.map((entry) => {
+    if (entry !== "text" && entry !== "image") {
+      throw new Error(`Expected ${key} entries to be "text" or "image"`)
+    }
+    return entry
+  })
+}
+
+function costField(record: Record<string, unknown>, key: string): ModelCostRates {
+  const value = record[key]
+  if (!isRecord(value)) throw new Error(`Expected ${key} to be an object`)
+  return {
+    input: numberField(value, "input"),
+    output: numberField(value, "output"),
+    cacheRead: numberField(value, "cacheRead"),
+    cacheWrite: numberField(value, "cacheWrite"),
+  }
+}
+
+function levelMapField(
+  record: Record<string, unknown>,
+  key: string,
+): Record<string, string | null> {
+  const value = record[key]
+  if (!isRecord(value)) throw new Error(`Expected ${key} to be an object`)
+  const map: Record<string, string | null> = {}
+  for (const [level, mapped] of Object.entries(value)) {
+    if (mapped !== null && typeof mapped !== "string") {
+      throw new Error(`Expected ${key} values to be strings or null`)
+    }
+    map[level] = mapped
+  }
+  return map
+}
+
+export function modelsFromCache(value: unknown): readonly PengepulModel[] {
+  if (!isRecord(value)) throw new Error("Expected model cache to be an object")
+  if (value["version"] !== MODEL_CACHE_VERSION) {
+    throw new Error(`Expected model cache version ${MODEL_CACHE_VERSION}`)
+  }
+  if (!Array.isArray(value["models"])) throw new Error("Expected cached models to be an array")
+
+  const parsed: PengepulModel[] = value["models"].map((entry) => {
+    if (!isRecord(entry)) throw new Error("Expected cached model entry to be an object")
+    return {
+      id: stringField(entry, "id"),
+      name: stringField(entry, "name"),
+      dialect: stringField(entry, "dialect") as PengepulDialect,
+      reasoning: entry["reasoning"] === true,
+      input: inputField(entry, "input"),
+      cost: costField(entry, "cost"),
+      contextWindow: numberField(entry, "contextWindow"),
+      maxTokens: numberField(entry, "maxTokens"),
+      ...(entry["thinkingLevelMap"] !== undefined
+        ? { thinkingLevelMap: levelMapField(entry, "thinkingLevelMap") }
+        : {}),
+    }
+  })
+  if (parsed.length === 0) throw new Error("pengepul cache holds no valid models")
+  return parsed
+}
+
+async function readCache(cachePath: string): Promise<readonly PengepulModel[]> {
+  const contents = await readFile(cachePath, "utf-8")
+  return modelsFromCache(JSON.parse(contents))
+}
+
+/** Reads the cached catalog without touching the network; empty when missing/invalid. */
+export async function loadCachedPengepulModels(
+  cachePath: string,
+): Promise<readonly PengepulModel[]> {
+  try {
+    return await readCache(cachePath)
+  } catch {
+    return []
+  }
+}
+
+async function writeCache(cachePath: string, models: readonly PengepulModel[]): Promise<void> {
+  await mkdir(dirname(cachePath), { recursive: true })
+  // Unique per write: the runtime can issue two overlapping writes in one
+  // process (cache-first + background refresh), and a shared pid-keyed name
+  // would let the first rename remove the second's source mid-flight.
+  const temporaryPath = `${cachePath}.${process.pid}.${randomUUID()}.tmp`
+
+  try {
+    await writeFile(
+      temporaryPath,
+      `${JSON.stringify({ version: MODEL_CACHE_VERSION, models }, null, 2)}\n`,
+      { encoding: "utf-8", mode: 0o600 },
+    )
+    await rename(temporaryPath, cachePath)
+  } finally {
+    try {
+      await rm(temporaryPath, { force: true })
+    } catch {
+      // Best-effort cleanup must not hide the original cache write error.
+    }
+  }
+}
+
+export async function loadPengepulModels(
+  options: LoadModelsOptions,
+): Promise<PengepulModelSource> {
+  const cachePath = options.cachePath
+
+  try {
+    const models = await fetchPengepulModels(options)
+
+    try {
+      await writeCache(cachePath, models)
+      return { models, source: "live" }
+    } catch (error) {
+      return {
+        models,
+        source: "live",
+        warning: `Loaded the live pengepul model catalog but could not update ${cachePath}: ${errorMessage(error)}`,
+      }
+    }
+  } catch (liveError) {
+    if (options.signal?.aborted) throw abortError(options.signal.reason ?? liveError)
+
+    try {
+      const models = await readCache(cachePath)
+      return {
+        models,
+        source: "cache",
+        warning: `Could not refresh the pengepul model catalog (${errorMessage(liveError)}). Using the cached catalog from ${cachePath}.`,
+      }
+    } catch (cacheError) {
+      return {
+        models: [],
+        source: "empty",
+        warning: `Could not refresh the pengepul model catalog (${errorMessage(liveError)}), and no valid cached catalog is available at ${cachePath} (${errorMessage(cacheError)}). pengepul models will remain unavailable until the next startup refresh succeeds.`,
+      }
+    }
+  }
+}
+
+

package/src/runtime.ts

@@ -0,0 +1,211 @@
+/**
+ * Cached-model runtime for the pengepul provider.
+ *
+ * Registers the provider immediately from the cache (so startup never waits on
+ * the network), refreshes it in the background, and disposes cleanly. There
+ * are no user-facing commands: the startup refresh is the only refresh.
+ *
+ * The pi seam is an interface, so the whole thing is testable with a fake host.
+ */
+
+import type { PengepulModel, PengepulModelSource } from "./models.ts"
+
+export interface PengepulRuntimeApi {
+  registerProvider(name: string, config: unknown): void
+}
+
+export interface PengepulRuntimeOptions {
+  /** A provider config built from a model list. */
+  createProviderConfig: (models: readonly PengepulModel[]) => unknown
+  /** Live fetch; resolves to the catalog plus a source marker. */
+  loadModels: (signal: AbortSignal) => Promise<PengepulModelSource>
+  /** Cached catalog only; empty when no valid cache exists. */
+  loadCachedModels: () => Promise<readonly PengepulModel[]>
+  now?: () => number
+  logWarning?: (message: string) => void
+}
+
+export interface PengepulRefreshResult {
+  refreshed: boolean
+  source: PengepulModelSource["source"]
+  modelCount: number
+  warning?: string
+}
+
+interface RuntimeStatus {
+  source: PengepulModelSource["source"]
+  modelCount: number
+  providerRegistered: boolean
+  lastSuccess?: number
+  lastAttempt?: number
+  warning?: string
+  refreshing: boolean
+}
+
+const REDACTED = "[redacted]"
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function redactDiagnosticText(value: string): string {
+  return value
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED}`)
+    .replace(/\b(?:sk-local|sk-|api[-_ ]?key|token|secret|password)[_-]?[\w.~+/=-]{8,}\b/gi, REDACTED)
+    .replace(/\b(?:api[-_ ]?key|token|secret|password)\s*[=:]\s*[^\s,;)]+/gi, (match) => {
+      const separator = match.match(/\s*[=:]\s*/)?.[0] ?? "="
+      return `${match.slice(0, match.indexOf(separator))}${separator}${REDACTED}`
+    })
+}
+
+export class PengepulRuntime {
+  private readonly now: () => number
+  private readonly logWarning: (message: string) => void
+  private status: RuntimeStatus
+  private providerRegistered = false
+  private refreshPromise: Promise<PengepulRefreshResult> | undefined
+  private readonly shutdown = new AbortController()
+
+  constructor(
+    private readonly pi: PengepulRuntimeApi,
+    private readonly options: PengepulRuntimeOptions,
+  ) {
+    this.now = options.now ?? Date.now
+    this.logWarning = options.logWarning ?? ((message) => console.warn(`[pengepul] ${message}`))
+    this.status = {
+      source: "empty",
+      modelCount: 0,
+      providerRegistered: false,
+      refreshing: false,
+    }
+  }
+
+  /**
+   * Registers the cached catalog immediately (so host startup does not wait on
+   * the network) and refreshes it in the background. Without a valid cache the
+   * live refresh is awaited so models are available right away.
+   */
+  async initialize(): Promise<void> {
+    const cached = await this.options.loadCachedModels()
+    if (cached.length === 0) {
+      await this.refresh()
+      return
+    }
+
+    this.pi.registerProvider("pengepul", this.options.createProviderConfig(cached))
+    this.providerRegistered = true
+    this.status = {
+      ...this.status,
+      source: "cache",
+      modelCount: cached.length,
+      providerRegistered: true,
+      lastSuccess: this.now(),
+    }
+    void this.refresh()
+  }
+
+  /** Aborts any background refresh so a stopping host does not wait on the network. */
+  dispose(): void {
+    this.shutdown.abort(new Error("pengepul provider shut down"))
+  }
+
+  refresh(): Promise<PengepulRefreshResult> {
+    if (this.refreshPromise) return this.refreshPromise
+
+    const refreshPromise = this.refreshCatalog().finally(() => {
+      if (this.refreshPromise === refreshPromise) this.refreshPromise = undefined
+    })
+    this.refreshPromise = refreshPromise
+    return refreshPromise
+  }
+
+  private async refreshCatalog(): Promise<PengepulRefreshResult> {
+    this.status = { ...this.status, lastAttempt: this.now(), refreshing: true }
+
+    try {
+      const loaded = await this.options.loadModels(this.shutdown.signal)
+      const warning = loaded.warning ? redactDiagnosticText(loaded.warning) : undefined
+
+      const shouldRegister =
+        !this.providerRegistered ||
+        loaded.source === "live" ||
+        (this.status.modelCount === 0 && loaded.models.length > 0)
+
+      if (shouldRegister) {
+        this.pi.registerProvider("pengepul", this.options.createProviderConfig(loaded.models))
+        this.providerRegistered = true
+
+        if (loaded.models.length === 0) {
+          const preservedWarning = warning ?? "pengepul model discovery returned no models"
+          this.status = {
+            ...this.status,
+            source: loaded.source,
+            modelCount: 0,
+            providerRegistered: true,
+            warning: preservedWarning,
+            refreshing: false,
+          }
+          this.warn(preservedWarning)
+          return { refreshed: false, source: loaded.source, modelCount: 0, warning: preservedWarning }
+        }
+
+        this.status = {
+          ...this.status,
+          source: loaded.source,
+          modelCount: loaded.models.length,
+          providerRegistered: true,
+          lastSuccess: this.now(),
+          warning,
+          refreshing: false,
+        }
+        if (warning) this.warn(warning)
+        return { refreshed: true, source: loaded.source, modelCount: loaded.models.length, warning }
+      }
+
+      const preservedWarning = warning ?? "pengepul model discovery returned no models"
+      this.status = { ...this.status, warning: preservedWarning, refreshing: false }
+      this.warn(preservedWarning)
+      return {
+        refreshed: false,
+        source: this.status.source,
+        modelCount: this.status.modelCount,
+        warning: preservedWarning,
+      }
+    } catch (error) {
+      if (this.shutdown.signal.aborted) {
+        this.status = { ...this.status, refreshing: false }
+        return {
+          refreshed: false,
+          source: this.status.source,
+          modelCount: this.status.modelCount,
+        }
+      }
+      const warning = redactDiagnosticText(
+        `Could not refresh the pengepul model catalog: ${errorMessage(error)}`,
+      )
+      this.status = { ...this.status, warning, refreshing: false }
+      this.warn(warning)
+      return {
+        refreshed: false,
+        source: this.status.source,
+        modelCount: this.status.modelCount,
+        warning,
+      }
+    }
+  }
+
+  private warn(message: string): void {
+    try {
+      this.logWarning(redactDiagnosticText(message))
+    } catch {
+      // Diagnostics must never make a catalog refresh fail.
+    }
+  }
+}
+
+export function createPengepulRuntime(
+  pi: PengepulRuntimeApi,
+  options: PengepulRuntimeOptions,
+): PengepulRuntime {
+  return new PengepulRuntime(pi, options)
+}