@pwguler/pi-pengepul-provider 0.2.3 → 0.3.0

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 {
@@ -140,6 +133,26 @@ function heuristicMeta(id: string): BuiltinModelMeta {
   }
 }
 
+/**
+ * The catalog-id shapes to try for a relay id, in the order they are tried.
+ *
+ * The order is load-bearing, and it is not "most specific first": the last
+ * segment is tried before the namespace-stripped id, which is what the
+ * catalogs were measured to give. For 141 of the relay's 527 ids the two
+ * shapes resolve to different entries and the last segment wins - 
+ * `commandcode/deepseek/deepseek-v4-pro` takes the deepseek catalog's bare
+ * `deepseek-v4-pro` (input 0.435) rather than openrouter's
+ * `deepseek/deepseek-v4-pro` (input 0.890, and a different level map).
+ * Reordering these shapes repoints those ids, so the test pins the order.
+ *
+ * The namespace-stripped shape is the third fallback: the only one that
+ * reaches an id whose catalog entry both the full id and the last segment
+ * miss, which is three of the relay's 527 at the time of writing.
+ */
+export function catalogIdForms(id: string): readonly string[] {
+  return [...new Set([id, modelName(id), bareId(id)])]
+}
+
 /**
  * Metadata pengepul itself advertises for a model (pengepul >= 0.6.0).
  * Every field is optional: the rollout is partial and older relays send none.
@@ -209,6 +222,43 @@ function optionalRate(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined
 }
 
+/**
+ * Extended effort levels for an id no pi catalog carries, on the one relay
+ * namespace where that vocabulary has been measured.
+ *
+ * pi hides `xhigh` and `max` unless a model's map names them, so an id no
+ * catalog answers for dropped to low/medium/high and could never send the top
+ * of the scale. Two of the 296 reasoning openai-completions ids the provider
+ * registers rest on this today; the lookup's namespace-stripped shapes answer
+ * for the rest.
+ *
+ * Only `max` is named. DeepSeek documents low/high/max for the
+ * OpenAI-compatible wire and folds `minimal` into low, `medium` and `xhigh`
+ * into high - which is what pi's own deepseek catalog encodes, hiding `xhigh`
+ * outright and nulling `medium` - but the relay validates one enum for every
+ * family it routes, so the namespace rule cannot tell a vendor alias from a
+ * level in its own right. Naming the top of the scale is the part that is
+ * true whatever the upstream does with it; the rest stays with pi's default.
+ *
+ * Measured against the running relay: on `commandcode/` ids every requested
+ * effort except `minimal` is accepted, and one error text — the relay's own
+ * enum — answers all nine families probed (deepseek, Qwen, MiniMax, google,
+ * moonshotai, xiaomi, stepfun, nvidia, inclusionai), nine of the eighteen the
+ * namespace carries, so the vocabulary belongs to the relay rather than to any
+ * one model. `minimal` 400s, and the overlay below nulls it.
+ *
+ * `openrouter/` ids are left alone, but not because that namespace is
+ * unmeasurable: it validates no effort enum at all, so a probe there answers
+ * 200 whether the level exists upstream or not. What it serves is also
+ * heterogeneous - image generators, R1-class models that take no effort
+ * parameter at all - and pi's openrouter entries spell DeepSeek's top level
+ * `xhigh` rather than `max`, so a namespace-wide rule there has nothing solid
+ * to stand on.
+ */
+function fallbackLevelMap(id: string): Record<string, string | null> | undefined {
+  return id.toLowerCase().startsWith("commandcode/") ? { max: "max" } : undefined
+}
+
 /**
  * Resolve a model's metadata, most trustworthy source first:
  *   1. what pengepul advertises (first-party for this relay),
@@ -223,9 +273,28 @@ function metaFor(
   dialect: PengepulDialect,
   lookup: BuiltinModelLookup | undefined,
 ): BuiltinModelMeta {
-  const base = lookup?.(id, dialect) ?? heuristicMeta(id)
+  const known = lookup?.(id, dialect)
+  const base = known ?? heuristicMeta(id)
   const relay = metaFromRelayEntry(entry)
-  return relay ? { ...base, ...relay } : base
+  const meta = relay ? { ...base, ...relay } : base
+
+  // 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 || entry["owned_by"] === "anthropic"
+
+  // The lookup searches every provider's catalog, so a hit need not come from
+  // the id's own vendor: github-copilot answers for
+  // `commandcode/google/gemini-3.8-flash` and carries no map, which is silence
+  // about another provider, not an answer about this relay. The fallback still
+  // stops there, deliberately. Measuring this relay shows which efforts it
+  // accepts and never which ones the upstream honours, so an entry's silence
+  // is left as silence and those ids keep pi's default until per-vendor
+  // evidence exists - the way DeepSeek's documented scale settled the ids the
+  // fallback does serve.
+  const fallback =
+    known || !reasoning || dialect !== "openai-completions" ? undefined : fallbackLevelMap(id)
+
+  return { ...meta, reasoning, ...(fallback ? { thinkingLevelMap: fallback } : {}) }
 }
 
 function toPengepulModel(
@@ -235,25 +304,25 @@ function toPengepulModel(
   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"
-
-  // The relay enforces reasoning_effort low|medium|high|xhigh|max at its
-  // request layer, uniformly across families: `minimal` 400s and its thinking
-  // toggle never actually disables thinking. That holds no matter where the
-  // reasoning knowledge came from, so every openai-completions reasoning model
-  // gets the relay's shape: inherited strings case-folded to the enum (pi's
-  // catalogs spell Google efforts `HIGH` and Qwen's `default`), values that
-  // match under no casing hidden, and off/minimal always null. Overlay, never
-  // replace: inherited nulls keep their levels hidden. The Messages dialect
-  // needs none of this: it folds `minimal` into `low` and already nulls `off`
-  // via forceAdaptiveThinking.
+  const reasoning = meta.reasoning
+
+  // The relay's request layer validates reasoning_effort on `commandcode/`
+  // ids: `minimal` 400s there, and its thinking toggle never actually disables
+  // thinking. On `openrouter/` ids it validates nothing, so `minimal` is a real
+  // level there and is left in place. `off` is different and stays nulled
+  // everywhere: `none` is refused by some upstreams (gemini-3.8-flash 400s on
+  // it) and accepted by others (deepseek), which is no basis for sending it.
+  // Either way every openai-completions reasoning model gets the relay's shape:
+  // inherited strings case-folded to the enum (pi's catalogs spell Google
+  // efforts `HIGH` and Qwen's `default`), values that match under no casing
+  // hidden. Overlay, never replace: inherited nulls keep their levels hidden.
+  // The Messages dialect needs none of this: it folds `minimal` into `low` and
+  // already nulls `off` via forceAdaptiveThinking.
+  const enforceRelayEnum = reasoning && dialect === "openai-completions"
   const thinkingLevelMap = relaySafeLevelMap(
     meta.thinkingLevelMap,
-    reasoning && dialect === "openai-completions",
+    enforceRelayEnum,
+    relayAcceptsMinimal(id),
   )
 
   return {
@@ -272,32 +341,51 @@ function toPengepulModel(
 /** The efforts the relay accepts; anything else is rejected at its request layer. */
 const RELAY_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"])
 
+/**
+ * Whether the relay's request layer takes `minimal` for this id.
+ *
+ * Measured: `commandcode/` validates its enum and answers 400 Invalid option:
+ * expected one of "low"|"medium"|"high"|"xhigh"|"max", while `openrouter/`
+ * validates nothing and answers 200 - so hiding `minimal` there costs 166 of
+ * the 227 openrouter models that reason, a level the relay accepts.
+ *
+ * `none` is not the same story: gemini-3.8-flash answers 400 on it while
+ * deepseek accepts it, so `off` stays hidden in every namespace. An unmeasured
+ * namespace keeps the conservative default too.
+ */
+function relayAcceptsMinimal(id: string): boolean {
+  return id.toLowerCase().startsWith("openrouter/")
+}
+
 /**
  * Shape an inherited level map for the relay's wire. With `enforce` (an
  * openai-completions reasoning model) the relay's enum is the only vocabulary
  * that reaches it: inherited strings are case-folded to the enum or hidden,
- * and off/minimal are always hidden. Without it the map passes through.
+ * and `off` is always hidden. `minimal` is hidden unless the namespace is
+ * known to take it. Without `enforce` the map passes through.
  */
 function relaySafeLevelMap(
   inherited: Record<string, string | null> | undefined,
   enforce: boolean,
+  acceptsMinimal = false,
 ): Record<string, string | null> | undefined {
   if (!enforce) return inherited ? { ...inherited } : undefined
 
   const map: Record<string, string | null> = {}
   for (const [level, mapped] of Object.entries(inherited ?? {})) {
-    map[level] = typeof mapped === "string" ? relayEffort(mapped) : mapped
+    map[level] = typeof mapped === "string" ? relayEffort(mapped, acceptsMinimal) : mapped
   }
   map["off"] = null
-  map["minimal"] = null
+  if (!acceptsMinimal) map["minimal"] = null
   return map
 }
 
 /** The relay's effort enum, case-folded; null keeps the level out of the picker. */
-function relayEffort(value: string): string | null {
+function relayEffort(value: string, acceptsMinimal: boolean): string | null {
   if (RELAY_EFFORTS.has(value)) return value
   const lower = value.toLowerCase()
-  return RELAY_EFFORTS.has(lower) ? lower : null
+  if (RELAY_EFFORTS.has(lower)) return lower
+  return acceptsMinimal && lower === "minimal" ? lower : null
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -312,6 +400,31 @@ function stringField(record: Record<string, unknown>, key: string): string {
   return value
 }
 
+/**
+ * The relay lists OpenRouter's batch routes as models, and OpenRouter refuses
+ * them on the chat wire with 404 "This model is only available through the
+ * Batch API". Confirmed on 10 of the relay's 77 batch ids across anthropic,
+ * openai, qwen, deepseek and z-ai; the rest are inferred from the same route
+ * rule, because probing them in bulk does not work - the refusals put the
+ * relay's pooled openrouter account on cooldown, which turns every following
+ * probe into 503 "no available openrouter account" and measures the cooldown
+ * rather than the model. Nothing pi sends can reach them, so they are left
+ * out of the catalog rather than offered as an entry that always fails.
+ */
+function isBatchRoute(id: string): boolean {
+  return id.endsWith(":batch")
+}
+
+/**
+ * Drop the ids this relay cannot serve on either wire. Applied on the way in
+ * from the relay and on the way in from the cache: the cache is what covers a
+ * briefly absent relay, so it must not be the path that resurrects a route
+ * the live catalog would have dropped.
+ */
+function servableModels(models: readonly PengepulModel[]): PengepulModel[] {
+  return models.filter((model) => !isBatchRoute(model.id))
+}
+
 /** Parse the raw `/v1/models` body into models. Throws on a malformed body. */
 export function modelsFromApiResponse(
   value: unknown,
@@ -322,118 +435,177 @@ export function modelsFromApiResponse(
 
   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)
-  })
+  const models = servableModels(
+    data.map((entry) => {
+      if (!isRecord(entry)) throw new Error("Expected model entry to be an object")
+      return toPengepulModel(entry, lookupBuiltin)
+    }),
+  )
+
+  if (models.length === 0) throw new Error("pengepul returned an empty model catalog")
+  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 {
-  const slash = id.indexOf("/")
-  const bare = slash === -1 ? id : id.slice(slash + 1)
-  return `${bare} (pengepul)`
+  return `${bareId(id)} (pengepul)`
 }
 
 interface FetchModelsOptions {
@@ -466,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)
@@ -552,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) {
@@ -639,8 +811,9 @@ export function modelsFromCache(value: unknown): readonly PengepulModel[] {
         : {}),
     }
   })
-  if (parsed.length === 0) throw new Error("pengepul cache holds no valid models")
-  return parsed
+  const servable = servableModels(parsed)
+  if (servable.length === 0) throw new Error("pengepul cache holds no valid models")
+  return servable
 }
 
 async function readCache(cachePath: string): Promise<readonly PengepulModel[]> {
@@ -659,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.`,
-      }
-    }
-  }
-}
-