@pwguler/pi-pengepul-provider 0.2.4 → 0.3.0

package/README.md

@@ -41,8 +41,8 @@ prefixed `pengepul/<id>`. To try it without installing, use
 
 ## What it does
 
-- Registers the `pengepul` provider against your relay's base URL
-  (`http://127.0.0.1:8317` by default).
+- Registers the `pengepul` provider against the relay base URL on your
+  credential (`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`),
@@ -53,24 +53,55 @@ prefixed `pengepul/<id>`. To try it without installing, use
   `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.
+- Caches the catalog in pi's model store, so startup does not wait on the
+  network and a briefly absent relay is covered. The cached models are
+  re-pointed at the relay base configured now, so moving the relay does not
+  leave requests aimed at the old address.
 - Reuses pi's built-in stream functions for both wires — no custom transport.
-- Registers no commands: the catalog refreshes on every startup.
+- Registers no commands: pi refreshes the catalog on every startup.
 
 ## Configuration
 
+Everything lives in `~/.pi/agent/auth.json`: the relay's API key and the relay
+base it applies to.
+
+```json
+{
+  "pengepul": {
+    "type": "api_key",
+    "key": "sk-local-...",
+    "baseUrl": "http://127.0.0.1:8317"
+  }
+}
+```
+
+`/login pengepul` writes both fields for you — it asks for the key, then for the
+relay URL, and defaults the URL to `http://127.0.0.1:8317`. Editing the file by
+hand works the same way; `baseUrl` may end in `/v1` or not.
+
+To reach a relay on another machine, put that machine's address in `baseUrl`
+(and make the relay listen beyond loopback there: `host: 0.0.0.0` in
+`~/.pengepul/config.yaml` on the relay, or forward the port over SSH). The key
+is the relay's own key — `pengepul config api-key` prints it.
+
+Optional overrides, for CI or a one-off shell. Each is a fallback: the
+credential wins when it carries a value.
+
 | 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` |
+| Relay base URL | `PENGEPUL_BASE_URL` | `http://127.0.0.1:8317`, or the relay's own `config.yaml` |
+| API key | `PENGEPUL_API_KEY` | `api-keys[0]` in `~/.pengepul/config.yaml` |
 | Config path | `PENGEPUL_CONFIG` | `~/.pengepul/config.yaml` |
-| Model cache path | `PENGEPUL_MODELS_CACHE` | `<agent-dir>/pengepul-models.json` |
+| Legacy 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.
+`PENGEPUL_MODELS_CACHE` names the pre-0.3 cache file. It is read once, when pi's
+model store has no pengepul catalog yet, and never written again.
+
+Do not set `providers.pengepul.baseUrl` in `models.json`. pi applies that value
+to every model of the provider, which collapses the two wires onto one URL —
+Anthropic Messages traffic would be sent to `/v1` and Chat Completions traffic
+to `/`.
 
 ## Notes
 
@@ -81,7 +112,9 @@ is set.
   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.
+  start with the relay up. A relay that answers with 401 leaves the last known
+  catalog registered and logs a warning; discovery does not take pi down with
+  it.
 
 ## Development
 

package/extensions/api-key.ts

@@ -1,53 +1,22 @@
 /**
- * Resolve pengepul's local API key.
+ * Read pengepul's own 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.
+ * This is the fallback for the machine that runs the relay itself: a client box
+ * configures the key in `auth.json`, which pi resolves and hands to the
+ * provider. Only extraction lives here, so the file read stays with the caller
+ * and this module stays io-free.
  */
 
-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 DEFAULT_CONFIG_PATH = "~/.pengepul/config.yaml"
 
 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:

package/extensions/config.ts

@@ -1,40 +1,34 @@
 /**
- * Resolve pengepul connection and cache settings from the environment.
+ * Where the pengepul provider's fallback sources live.
  *
- * Kept small and pure: takes an env map and the host's agent dir, returns the
- * connection defaults a test can pin down.
+ * `auth.json` is the configuration surface. These are the escape hatches kept
+ * for tests, CI, and a machine that happens to run the relay itself: env vars
+ * for the relay base and key, and pengepul's own config on disk.
  */
 
 import { join } from "node:path"
 
-import { DEFAULT_RELAY_BASE } from "./models.ts"
+import { CONFIG_PATH_ENV, DEFAULT_CONFIG_PATH } from "./api-key.ts"
+
+export { CONFIG_PATH_ENV, DEFAULT_CONFIG_PATH }
 
 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
+  /** Where pengepul's own config lives, when this machine runs the relay. */
+  configPath: string
+  /** Where the pre-0.3 catalog cache lives; read once to seed pi's store. */
+  legacyCachePath: string
 }
 
 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 }
+  return {
+    configPath: env[CONFIG_PATH_ENV] ?? DEFAULT_CONFIG_PATH,
+    legacyCachePath: env[MODELS_CACHE_ENV] ?? join(agentDir, "pengepul-models.json"),
+  }
 }

package/extensions/credential.ts

@@ -0,0 +1,113 @@
+/**
+ * Pengepul credential and relay-base resolution.
+ *
+ * The credential is the pengepul entry in pi's `auth.json`: an API key for the
+ * relay plus the relay base it applies to. pi core resolves the key itself but
+ * knows nothing about `baseUrl`, so the extension reads it here. Everything in
+ * this module is pure: an env map and config text in, a value out.
+ *
+ * Precedence, highest first: credential, then environment, then the relay's own
+ * config file (which only exists on the machine running the relay), then the
+ * loopback default pengepul binds to.
+ */
+
+import { normalizeRootBaseUrl } from "./dialect.ts"
+import { DEFAULT_RELAY_BASE } from "./models.ts"
+
+/** The fields this provider reads off a stored credential. */
+export interface PengepulCredential {
+  /** Always `"api_key"` in pi's store; read as unknown so a hand-edited file cannot lie its way past a cast. */
+  type?: unknown
+  key?: unknown
+  baseUrl?: unknown
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  const trimmed = value.trim()
+  return trimmed === "" ? undefined : trimmed
+}
+
+/** The relay base stored on the credential, when the user set one. */
+export function credentialRelayBase(credential: PengepulCredential | undefined): string | undefined {
+  return nonEmptyString(credential?.baseUrl)
+}
+
+/** The API key stored on the credential, when the user set one. */
+export function credentialApiKey(credential: PengepulCredential | undefined): string | undefined {
+  return nonEmptyString(credential?.key)
+}
+
+/**
+ * Build a relay base from pengepul's own `config.yaml`. Only the machine running
+ * the relay has this file; clients reach a relay elsewhere and skip this source.
+ *
+ * pengepul writes `host: ''` when it binds loopback ("empty binds 127.0.0.1, not
+ * every interface"), so an empty host means loopback rather than "unset". A
+ * bind-all address is not a connect address either: `0.0.0.0`, `::`, and `*` mean
+ * "every interface", and a client reaches that listener on loopback.
+ */
+export function relayBaseFromConfigText(configText: string | undefined): string | undefined {
+  if (configText === undefined) return undefined
+
+  let host = "127.0.0.1"
+  let port: number | undefined
+
+  for (const line of configText.split(/\r?\n/)) {
+    const hostMatch = /^\s*host:\s*(.*)$/.exec(line)
+    if (hostMatch) {
+      const value = (hostMatch[1] ?? "").trim().replace(/^["']|["']$/g, "")
+      if (value !== "" && !isBindAll(value)) host = value
+      continue
+    }
+
+    const portMatch = /^\s*port:\s*(.*)$/.exec(line)
+    if (portMatch) {
+      const value = (portMatch[1] ?? "").trim().replace(/^["']|["']$/g, "")
+      const parsed = Number(value)
+      if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535) port = parsed
+    }
+  }
+
+  return port === undefined ? undefined : `http://${host}:${port}`
+}
+
+/** Whether a configured host is a bind-all address rather than a destination. */
+function isBindAll(host: string): boolean {
+  return host === "0.0.0.0" || host === "::" || host === "[::]" || host === "*"
+}
+
+export interface RelayBaseSources {
+  /** The relay base stored on the pengepul credential. */
+  credential?: string | undefined
+  /** The `PENGEPUL_BASE_URL` environment value. */
+  environment?: string | undefined
+  /** The relay base derived from pengepul's own config file. */
+  config?: string | undefined
+}
+
+/**
+ * The relay root every wire appends to: highest-precedence non-blank source, or
+ * loopback. A trailing `/v1` is accepted and stripped, so a base copied from a
+ * client config cannot produce `/v1/v1` downstream.
+ */
+export function resolveRelayBase(sources: RelayBaseSources): string {
+  const chosen =
+    nonEmptyString(sources.credential) ??
+    nonEmptyString(sources.environment) ??
+    nonEmptyString(sources.config) ??
+    DEFAULT_RELAY_BASE
+  return normalizeRootBaseUrl(chosen)
+}
+
+export interface ApiKeySources {
+  /** The key stored on the pengepul credential. */
+  credential?: string | undefined
+  /** The key resolved from `PENGEPUL_API_KEY` or pengepul's own config file. */
+  ambient?: string | undefined
+}
+
+/** The key requests and catalog fetches use, or undefined when none is configured. */
+export function resolveApiKey(sources: ApiKeySources): string | undefined {
+  return nonEmptyString(sources.credential) ?? nonEmptyString(sources.ambient)
+}

package/extensions/index.ts

@@ -1,31 +1,24 @@
 /**
  * @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.
+ * Registers pengepul as a pi provider. pengepul is a relay that pools your
+ * Claude/Codex subscriptions and speaks both native wires. The provider itself
+ * lives in `./provider.ts`: pi resolves auth through it and hands the credential
+ * back on every refresh, so `auth.json` carries the key and the relay base. The
+ * pure core is `./credential.ts`, `./dialect.ts`, and `./models.ts`; this file
+ * adapts them to the pi ExtensionAPI seam and reads the one file pi cannot.
  */
 
 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 {
-  catalogIdForms,
-  loadCachedPengepulModels,
-  loadPengepulModels,
-  toProviderModelConfigs,
-  type PengepulModel,
-} from "./models.ts"
-import { createPengepulRuntime } from "./runtime.ts"
+import { catalogIdForms, type PengepulModel } from "./models.ts"
+import { createPengepulProvider } from "./provider.ts"
 
 function expandHome(path: string): string {
   if (path === "~") return process.env.HOME ?? path
@@ -93,49 +86,24 @@ function createBuiltinLookup(): (id: string, dialect: string) => ReturnType<type
   }
 }
 
-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.
+ * Model discovery belongs to pi: it calls `refreshModels` with the resolved
+ * credential, first against pi's cached catalog and then, when the network is
+ * allowed, against the relay. Registration is synchronous; nothing here waits
+ * on the relay, and the catalog survives a restart through pi's model store.
  */
-export default async function (pi: ExtensionAPI) {
+export default 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()
+  const provider = createPengepulProvider({
+    env: process.env,
+    configText: readConfigText(settings.configPath),
+    legacyCachePath: settings.legacyCachePath,
+    lookupBuiltin: createBuiltinLookup(),
   })
 
-  await runtime.initialize()
+  pi.registerProvider(provider)
 }
+
+/** The pengepul catalog shape, re-exported for callers that build on the core. */
+export type { PengepulModel }

package/extensions/models.ts

@@ -20,10 +20,9 @@
  * 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 { readFile } from "node:fs/promises"
 
+import { MODELS_TIMEOUT_MS_ENV } from "./config.ts"
 import { baseUrlForDialect, dialectForModelId } from "./dialect.ts"
 import type { PengepulDialect } from "./dialect.ts"
 
@@ -65,7 +64,7 @@ export interface BuiltinModelMeta {
  */
 export type BuiltinModelLookup = (id: string, dialect: PengepulDialect) => BuiltinModelMeta | undefined
 
-/** A pengepul model ready to become a pi `ProviderModelConfig`. */
+/** A pengepul model ready to become a pi model entry. */
 export interface PengepulModel {
   id: string
   name: string
@@ -79,12 +78,6 @@ export interface PengepulModel {
   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 {
@@ -454,105 +447,162 @@ export function modelsFromApiResponse(
   return models
 }
 
-/** 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
+import type { Api, Model } from "@earendil-works/pi-ai"
+
+/** The pi-ai model shapes this provider serves: one per dialect the relay speaks. */
+export type PengepulModelEntry = Model<"anthropic-messages"> | Model<"openai-completions">
+
+/** The provider id every pengepul model is stamped with. */
+export const PENGEPUL_PROVIDER_ID = "pengepul"
+
+/** What every model carries regardless of wire: identity, pricing, and the limits. */
+function sharedModelFields(model: PengepulModel, relayBase: string) {
+  return {
+    id: model.id,
+    name: model.name,
+    provider: PENGEPUL_PROVIDER_ID,
+    baseUrl: baseUrlForDialect(relayBase, model.dialect),
+    reasoning: model.reasoning,
+    input: model.input,
+    cost: model.cost,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
   }
-  contextWindow: number
-  maxTokens: number
-  thinkingLevelMap?: Record<string, string | null>
-  compat?: {
-    forceAdaptiveThinking?: boolean
-    supportsLongCacheRetention?: boolean
-    sendSessionAffinityHeaders?: boolean
-    sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter"
+}
+
+/**
+ * The relay's prompt-cache affinity pin, on both wires.
+ *
+ * The relay's conversation_key resolves `x-claude-code-session-id`, then
+ * `x-session-id`, then the body's `prompt_cache_key`, then a hash of the
+ * cacheable prefix. pi emits one of those headers only for the `openrouter`
+ * affinity format, and only when the send flag is set. Both auto-detected
+ * defaults are wrong here: openai-completions picks `openai` (session_id +
+ * x-client-request-id + x-session-affinity) and anthropic-messages picks
+ * nothing at all. The header is the cheaper and more explicit of the two
+ * signals and it outranks the body field, so the pin keeps a session's account
+ * stable by the relay's first rule rather than its third. Losing it costs a
+ * session that migrates between pooled accounts its whole prefix: the upstream
+ * cache is per account.
+ *
+ * Measured, not assumed — `test/affinity-wire.test.ts` dumps both bodies:
+ * openai-completions carries `prompt_cache_key: <sessionId>` (and
+ * `prompt_cache_retention: "24h"`) under PI_CACHE_RETENTION=long, so the body
+ * field alone would name the conversation; anthropic-messages carries no
+ * `prompt_cache_key` at all, and pi-ai hardcodes `x-session-affinity` there,
+ * which this relay does not read. Messages traffic therefore rests entirely on
+ * the relay's prefix fallback until a pi release honours
+ * `sessionAffinityFormat` on that dialect.
+ *
+ * The two dialects do not land at the same time. openai-completions honors
+ * `sessionAffinityFormat` in every released pi. anthropic-messages only reads it
+ * from the unreleased change on pi main (commit bbb61e34a), which is why the
+ * field is re-declared below rather than taken from `AnthropicMessagesCompat`:
+ * against pi-ai 0.85.1 the pin is inert, and the cost of an ignored header is
+ * zero. Pin now rather than later — the cost of forgetting is silently
+ * re-billed Claude prefixes.
+ */
+function affinityPin() {
+  return {
+    sendSessionAffinityHeaders: true as const,
+    sessionAffinityFormat: "openrouter" as const,
   }
-}> {
+}
+
+/**
+ * Anthropic compat as pi-ai 0.85.1 types it, plus the affinity format a later
+ * pi reads. Declared here so the pin does not depend on the host's pi-ai
+ * version; the field is optional, so a host that predates it ignores the value.
+ */
+type AnthropicCompat = NonNullable<Model<"anthropic-messages">["compat"]> & {
+  sessionAffinityFormat?: "openrouter"
+}
+
+/**
+ * Map the relay catalog to pi models, one base URL per dialect. Pure.
+ *
+ * The per-model `baseUrl` is the only place the dialect split can live: pi
+ * applies a base URL returned from `auth.resolve()` to every model at once
+ * (`models.js` `applyAuth`), so a provider-wide value would send Anthropic
+ * Messages traffic to `/v1` and Chat Completions traffic to the root.
+ */
+export function toPengepulModels(
+  models: readonly PengepulModel[],
+  relayBase: string,
+): PengepulModelEntry[] {
   return models.map((model) => {
-    const adaptive = model.dialect === "anthropic-messages" && model.reasoning
-    // The 1h cache TTL is a Messages-dialect feature: `cache_control.ttl`
-    // has nowhere to go on the Chat Completions wire. Reasoning is not part
-    // of it — a non-reasoning Claude model caches the same way.
-    const longCacheRetention = model.dialect === "anthropic-messages"
+    const shared = sharedModelFields(model, relayBase)
+    if (model.dialect === "anthropic-messages") {
+      const adaptive = model.reasoning
+      return {
+        ...shared,
+        api: "anthropic-messages" as const,
+        // 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.
+        //
+        // The 1h cache TTL is a Messages-dialect feature too: `cache_control.ttl`
+        // has nowhere to go on the Chat Completions wire. Reasoning is not part
+        // of it — a non-reasoning Claude model caches the same way.
+        compat: {
+          ...affinityPin(),
+          ...(adaptive ? { forceAdaptiveThinking: true as const } : {}),
+          supportsLongCacheRetention: true as const,
+        } satisfies AnthropicCompat,
+      }
+    }
+
     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.
-      // Both dialects pin both fields, and that is why `compat` is
-      // unconditional. The relay's prompt-cache affinity key resolves in this
-      // order: `x-claude-code-session-id`, `x-session-id`, the body's
-      // `prompt_cache_key`, then a hash of the cacheable request prefix
-      // (app.rs `conversation_key`). pi emits `x-session-id` only for the
-      // `openrouter` affinity format, and only when the send flag is set;
-      // the auto-detected defaults are wrong here in both cases
-      // (openai-completions picks `openai`: session_id + x-client-request-id +
-      // x-session-affinity; anthropic-messages picks nothing). The header is
-      // the cheaper and more explicit of the two signals and it outranks the
-      // body field, so pinning it keeps a session's account stable by the
-      // relay's first rule rather than its third. Losing the pin costs a
-      // session that migrates between pooled accounts its whole prefix: the
-      // upstream cache is per account.
-      //
-      // Measured, not assumed — `test/affinity-wire.test.ts` dumps both bodies:
-      // openai-completions carries `prompt_cache_key: <sessionId>` (and
-      // `prompt_cache_retention: "24h"`) under PI_CACHE_RETENTION=long, so the
-      // body field alone would name the conversation; anthropic-messages
-      // carries no `prompt_cache_key` at all, and pi-ai hardcodes
-      // `x-session-affinity` there, which this relay does not read. Messages
-      // traffic therefore rests entirely on the relay's prefix fallback until
-      // a pi release honours `sessionAffinityFormat` on that dialect.
-      //
-      // The two dialects do not land at the same time. openai-completions
-      // honors `sessionAffinityFormat` in every released pi. anthropic-messages
-      // only reads it from the unreleased change on pi main (commit
-      // bbb61e34a); through pi-ai 0.85.1 that client hardcodes the header name
-      // `x-session-affinity`, which this relay does not read, so the Claude
-      // pin below is inert until pi ships it. Pin now rather than later: the
-      // cost of an ignored header is zero, and the cost of forgetting is
-      // silently re-billed Claude prefixes.
-      compat: {
-        ...(adaptive ? { forceAdaptiveThinking: true as const } : {}),
-        ...(longCacheRetention ? { supportsLongCacheRetention: true as const } : {}),
-        sendSessionAffinityHeaders: true as const,
-        sessionAffinityFormat: "openrouter" as const,
-      },
+      ...shared,
+      api: "openai-completions" as const,
+      ...(model.thinkingLevelMap ? { thinkingLevelMap: model.thinkingLevelMap } : {}),
+      compat: { ...affinityPin() },
     }
   })
 }
 
+/** Whether a stored pi model is one this provider published. */
+export function isPengepulModelEntry(model: Model<Api>): model is PengepulModelEntry {
+  return (
+    model.provider === PENGEPUL_PROVIDER_ID &&
+    (model.api === "anthropic-messages" || model.api === "openai-completions")
+  )
+}
+
+/**
+ * Re-derive every model's base URL from the base currently configured.
+ *
+ * pi's model store keeps whole models, baseUrl included, and replays them
+ * before the network phase. A relay that moved would otherwise be reached at
+ * its old address until a fetch succeeds — which never happens when the old
+ * address is gone.
+ */
+export function restampRelayBase(
+  models: readonly PengepulModelEntry[],
+  relayBase: string,
+): PengepulModelEntry[] {
+  return models.map((model) => ({
+    ...model,
+    baseUrl: baseUrlForDialect(relayBase, model.api),
+  }))
+}
+
 /** Picker label: the bare model part of a relay id, suffixed. `anthropic/claude-opus-5` -> `claude-opus-5 (pengepul)`. */
 function displayName(id: string): string {
   return `${bareId(id)} (pengepul)`
@@ -588,7 +638,7 @@ function configuredTimeoutMs(timeoutMs: number | undefined): number {
 }
 
 export function getModelsTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
-  const raw = env["PENGEPUL_MODELS_TIMEOUT_MS"]
+  const raw = env[MODELS_TIMEOUT_MS_ENV]
   if (!raw) return DEFAULT_MODELS_TIMEOUT_MS
   const parsed = Number(raw)
   return configuredTimeoutMs(parsed)
@@ -674,7 +724,7 @@ export async function fetchPengepulModels(
         throw new Error(
           `pengepul rejected the API key (${
             response.status
-          }). Set PENGEPUL_API_KEY or check ~/.pengepul/config.yaml.`,
+          }). Run /login pengepul, or set the key in ~/.pi/agent/auth.json or PENGEPUL_API_KEY.`,
         )
       }
       if (!response.ok) {
@@ -782,65 +832,4 @@ export async function loadCachedPengepulModels(
   }
 }
 
-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/extensions/provider.ts

@@ -0,0 +1,269 @@
+/**
+ * The pengepul provider, as pi-ai sees it.
+ *
+ * Registered as a native provider, so pi resolves auth through this module and
+ * hands the credential back to `refreshModels`. That closes two gaps the
+ * config-value form had: model discovery now uses the same resolved key pi uses
+ * for requests (it used to read only `PENGEPUL_API_KEY` and pengepul's own
+ * config, so a key stored in `auth.json` produced a 401), and the relay base
+ * comes from the credential instead of the environment.
+ *
+ * The relay base lives on the credential as `baseUrl`, a field pi core does not
+ * read. Per-model base URLs are derived from it, because pi applies a base URL
+ * returned from `resolve()` to every model at once and pengepul's two wires need
+ * different paths (`/` for Messages, `/v1` for Chat Completions).
+ */
+
+import type {
+  Api,
+  ApiKeyCredential,
+  AuthCheck,
+  AuthResult,
+  Model,
+  Provider,
+  ProviderAuthInteraction,
+  ProviderStreams,
+  RefreshModelsContext,
+} from "@earendil-works/pi-ai"
+import { anthropicMessagesApi, lazyStream, openAICompletionsApi } from "@earendil-works/pi-ai/compat"
+
+import { API_KEY_ENV, extractApiKeys } from "./api-key.ts"
+import { RELAY_BASE_ENV } from "./config.ts"
+import {
+  credentialApiKey,
+  credentialRelayBase,
+  relayBaseFromConfigText,
+  resolveApiKey,
+  resolveRelayBase,
+  type PengepulCredential,
+} from "./credential.ts"
+import { modelsUrl, type PengepulDialect } from "./dialect.ts"
+import {
+  DEFAULT_RELAY_BASE,
+  fetchPengepulModels,
+  getModelsTimeoutMs,
+  isPengepulModelEntry,
+  loadCachedPengepulModels,
+  PENGEPUL_PROVIDER_ID,
+  restampRelayBase,
+  toPengepulModels,
+  type BuiltinModelLookup,
+  type PengepulModelEntry,
+} from "./models.ts"
+
+/** The credential this provider writes: the relay key plus the base it applies to. */
+export interface PengepulApiKeyCredential extends ApiKeyCredential {
+  type: "api_key"
+  key?: string
+  baseUrl?: string
+}
+
+/** Where the config-file fallback key comes from, for the status label. */
+const CONFIG_FILE_LABEL = "~/.pengepul/config.yaml"
+
+export interface PengepulProviderOptions {
+  /** Environment map holding the optional `PENGEPUL_*` overrides. */
+  env?: Record<string, string | undefined>
+  /** Text of pengepul's own config, when this machine happens to run the relay. */
+  configText?: string
+  /** Where the pre-0.3 catalog cache lives; read once to seed pi's store. */
+  legacyCachePath: string
+  /** Catalog fetch transport, for tests. */
+  fetchImpl?: typeof fetch
+  /** Builtin metadata lookup, injected so the catalog logic stays free of pi imports. */
+  lookupBuiltin?: BuiltinModelLookup
+  /** Warning sink; defaults to `console.warn`. */
+  logWarning?: (message: string) => void
+  /** Clock, for tests. */
+  now?: () => number
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** The `Api` union is open-ended, so narrow it before indexing by wire. */
+function isPengepulDialect(api: Api): api is PengepulDialect {
+  return api === "anthropic-messages" || api === "openai-completions"
+}
+
+/**
+ * A provider whose catalog comes from pengepul and whose auth is the relay key.
+ *
+ * Ambient sources are read from the captured environment and config text, not
+ * from `AuthContext.env`, because `refreshModels` receives no auth context and
+ * both paths must agree on what the key and base are.
+ */
+export function createPengepulProvider(options: PengepulProviderOptions): Provider {
+  const env = options.env ?? process.env
+  const logWarning =
+    options.logWarning ?? ((message: string) => console.warn(`[pengepul] ${message}`))
+  const now = options.now ?? Date.now
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = getModelsTimeoutMs(env as NodeJS.ProcessEnv)
+
+  const environmentRelayBase = env[RELAY_BASE_ENV]
+  const environmentApiKey = env[API_KEY_ENV]
+  const configText = options.configText
+  const configRelayBase = relayBaseFromConfigText(configText)
+  const configApiKey = configText ? extractApiKeys(configText)[0] : undefined
+
+  let models: PengepulModelEntry[] = []
+
+  /** The key from outside auth.json, with the label the status UI shows. */
+  function ambientKey(): { key?: string; source?: string } {
+    if (environmentApiKey?.trim()) return { key: environmentApiKey.trim(), source: API_KEY_ENV }
+    if (configApiKey) return { key: configApiKey, source: CONFIG_FILE_LABEL }
+    return {}
+  }
+
+  function resolveKey(credential: unknown): { key?: string; source?: string } {
+    const stored = credentialApiKey(credential as PengepulCredential | undefined)
+    if (stored) return { key: stored, source: "stored credential" }
+    return ambientKey()
+  }
+
+  const streams: Record<PengepulDialect, ProviderStreams> = {
+    "anthropic-messages": anthropicMessagesApi(),
+    "openai-completions": openAICompletionsApi(),
+  }
+
+  function streamsFor(model: Model<Api>): ProviderStreams | undefined {
+    return isPengepulDialect(model.api) ? streams[model.api] : undefined
+  }
+
+  function unsupported(model: Model<Api>) {
+    return lazyStream(model, async () => {
+      throw new Error(`pengepul serves no "${model.api}" wire, so ${model.id} cannot be streamed`)
+    })
+  }
+
+  async function restoreOrSeed(context: RefreshModelsContext): Promise<boolean> {
+    const relayBase = resolveRelayBase({
+      credential: credentialRelayBase(context.credential as PengepulCredential | undefined),
+      environment: environmentRelayBase,
+      config: configRelayBase,
+    })
+
+    const stored = (context.stored?.models ?? []).filter(isPengepulModelEntry)
+    if (stored.length > 0) {
+      const restored = restampRelayBase(stored, relayBase)
+      return context.publish({ update: () => { models = restored } })
+    }
+
+    // Pre-0.3 installs kept their own cache file. Read it once so an upgrade
+    // does not start blind; pi's store owns the catalog from here on.
+    const legacy = await loadCachedPengepulModels(options.legacyCachePath)
+    if (legacy.length === 0) return true
+    const seeded = toPengepulModels(legacy, relayBase)
+    return context.publish({ update: () => { models = seeded } })
+  }
+
+  async function refreshFromRelay(context: RefreshModelsContext): Promise<void> {
+    const relayBase = resolveRelayBase({
+      credential: credentialRelayBase(context.credential as PengepulCredential | undefined),
+      environment: environmentRelayBase,
+      config: configRelayBase,
+    })
+
+    const resolved = resolveKey(context.credential)
+    if (!resolved.key) {
+      logWarning(
+        `No pengepul API key is configured (${API_KEY_ENV}, ${CONFIG_FILE_LABEL}, or auth.json), so the model catalog cannot be refreshed. Run /login pengepul.`,
+      )
+      return
+    }
+
+    try {
+      const catalog = await fetchPengepulModels({
+        url: modelsUrl(relayBase),
+        apiKey: resolved.key,
+        fetchImpl,
+        timeoutMs,
+        signal: context.signal,
+        ...(options.lookupBuiltin ? { lookupBuiltin: options.lookupBuiltin } : {}),
+      })
+      if (context.signal.aborted) return
+
+      const entries = toPengepulModels(catalog, relayBase)
+      await context.publish({
+        persist: { models: entries, checkedAt: now() },
+        update: () => { models = entries },
+      })
+    } catch (error) {
+      if (context.signal.aborted) return
+      logWarning(
+        `Could not refresh the pengepul model catalog (${errorMessage(error)}). Keeping the last known catalog.`,
+      )
+    }
+  }
+
+  return {
+    id: PENGEPUL_PROVIDER_ID,
+    name: "Pengepul",
+    baseUrl: resolveRelayBase({
+      environment: environmentRelayBase,
+      config: configRelayBase,
+    }),
+    auth: {
+      apiKey: {
+        name: "Pengepul relay",
+        login: async (
+          interaction: ProviderAuthInteraction,
+        ): Promise<PengepulApiKeyCredential> => {
+          const key = (await interaction.prompt({
+            type: "secret",
+            message: "Pengepul API key",
+          })).trim()
+          const answer = (await interaction.prompt({
+            type: "text",
+            message: "Pengepul relay URL",
+            placeholder: DEFAULT_RELAY_BASE,
+          })).trim()
+          // Written, not defaulted at read time: pi replaces the whole
+          // credential on login, so the URL has to be in the stored entry or a
+          // key rotation silently points the relay back at loopback.
+          return {
+            type: "api_key",
+            ...(key === "" ? {} : { key }),
+            baseUrl: resolveRelayBase({ credential: answer }),
+          }
+        },
+        check: async (input): Promise<AuthCheck | undefined> => {
+          const resolved = resolveKey(input.credential)
+          return resolved.key
+            ? { type: "api_key", ...(resolved.source ? { source: resolved.source } : {}) }
+            : undefined
+        },
+        resolve: async (input): Promise<AuthResult | undefined> => {
+          const resolved = resolveKey(input.credential)
+          if (!resolved.key) return undefined
+          // No `baseUrl` here on purpose: pi would apply it to every model and
+          // collapse the two dialect base URLs into one.
+          return {
+            auth: { apiKey: resolved.key },
+            ...(resolved.source ? { source: resolved.source } : {}),
+          }
+        },
+      },
+    },
+    getModels: () => models,
+    refreshModels: async (context) => {
+      if (!(await restoreOrSeed(context))) return
+      if (!context.allowNetwork || context.signal.aborted) return
+      await refreshFromRelay(context)
+    },
+    stream: (model, context, streamOptions) => {
+      const implementation = streamsFor(model)
+      return implementation
+        ? implementation.stream(model, context, streamOptions)
+        : unsupported(model)
+    },
+    streamSimple: (model, context, streamOptions) => {
+      const implementation = streamsFor(model)
+      return implementation
+        ? implementation.streamSimple(model, context, streamOptions)
+        : unsupported(model)
+    },
+  }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pwguler/pi-pengepul-provider",
-  "version": "0.2.4",
+  "version": "0.3.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.",
+  "description": "pi custom provider for pengepul, a relay that pools your Claude/Codex subscriptions. Key and relay base live in auth.json; both native wires (Anthropic Messages, OpenAI Chat Completions) come from one catalog.",
   "license": "MIT",
   "author": "pwguler",
   "repository": {

package/extensions/runtime.ts

@@ -1,211 +0,0 @@
-/**
- * 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)
-}