@pwguler/pi-pengepul-provider 0.4.0 → 0.5.1

package/README.md

@@ -58,6 +58,10 @@ prefixed `pengepul/<id>`. To try it without installing, use
   relay already serves — takes them from the same family's previous minor, so
   it does not sit at `high` until the next pi catalog update. Nothing to
   configure: `thinkingLevelMap` is resolved per id here.
+- Publishes Anthropic's cache lifetimes (5 minutes, 1 hour) on the Messages
+  wire, so pi's cache warmer can keep a Claude conversation's entry alive
+  instead of re-billing its whole prefix after five idle minutes. See
+  [Prompt cache](#prompt-cache).
 - 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
@@ -89,25 +93,86 @@ To reach a relay on another machine, put that machine's address in `baseUrl`
 `~/.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.
+Optional overrides, for CI or a one-off shell. The first two outrank the
+credential: set either and it wins, whatever `auth.json` holds.
 
 | Setting | Env var | Default |
 |---|---|---|
-| 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` |
-| Legacy cache path | `PENGEPUL_MODELS_CACHE` | `<agent-dir>/pengepul-models.json` |
+| Relay base URL | `PENGEPUL_BASE_URL` | `http://127.0.0.1:8317`, or the credential's `baseUrl` |
+| API key | `PENGEPUL_API_KEY` | the credential's `key` |
 | Discovery timeout | `PENGEPUL_MODELS_TIMEOUT_MS` | `10000` |
 
-`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.
+```sh
+PENGEPUL_BASE_URL=http://10.0.0.9:8317 PENGEPUL_API_KEY=sk-local-... pi
+```
 
 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 `/`.
 
+## Prompt cache
+
+The upstream prompt cache is one entry per account and lives five minutes by
+default, so a conversation that waits longer than that pays for its whole prefix
+again — on a 700k-token Opus session, dollars per return, logged by the relay as
+a `cache_write` with a near-zero `cache_read`.
+
+This provider declares Anthropic's lifetimes (5 minutes, 1 hour) on every
+Messages-wire model, which is what lets pi keep an entry alive at all: pi
+refreshes an entry by re-sending the prompt with a one-token cap before it
+expires, and it only warms a model whose lifetime it can resolve. Two pi
+settings decide when that happens, and neither covers an idle gap out of the
+box:
+
+| Setting | Where | Effect |
+|---|---|---|
+| `cacheWarming: "idle"` | `~/.pi/agent/settings.json` | Warms between agent runs. The default, `"streaming"`, stops as soon as a run settles — exactly when a five-minute entry is about to expire. |
+| `env: { "PI_CACHE_RETENTION": "long" }` | the `pengepul` credential in `auth.json` | Asks for the 1-hour tier instead of the 5-minute one. The relay forwards the extended TTL to Anthropic. |
+
+```json
+{
+  "pengepul": {
+    "type": "api_key",
+    "key": "sk-local-...",
+    "baseUrl": "http://127.0.0.1:8317",
+    "env": { "PI_CACHE_RETENTION": "long" }
+  }
+}
+```
+
+Idle warming covers gaps up to 30 minutes, pi's own safety limit, and pi only
+triggers it when the expected saving clears a threshold of its own — a small
+prompt is left to expire rather than refreshed. The long tier is what carries a
+longer break. Both are cheap next to a miss: a refresh is one cache read plus a
+one-token completion, while the long tier only raises the write premium, on the
+few hundred tokens a turn actually adds.
+
+`/session` reports the mode, the refresh cost, and the miss penalty it is
+weighing, and `showCacheMissNotices` in `settings.json` prints each miss with
+its re-billed token count.
+
+## Upgrading from 0.4.0 or earlier
+
+This release is breaking: the relay's own `~/.pengepul/config.yaml` is no longer
+a source. That file belongs to the machine running the relay, and reading it let
+a key on that box configure every client sharing it.
+
+- A key that came from `api-keys:` in it is no longer picked up. Run
+  `/login pengepul`, or put it in `auth.json` as `"pengepul".key`, or export
+  `PENGEPUL_API_KEY`. `pengepul config api-key` prints it.
+- The relay base built from its `host` and `port` is no longer picked up
+  either. Set `baseUrl` in `auth.json`, or `PENGEPUL_BASE_URL`, if the relay is
+  not on `http://127.0.0.1:8317`.
+- A pre-0.3 `<agent-dir>/pengepul-models.json` is no longer imported. The
+  catalog now comes from the relay on the next start, so the relay has to be
+  reachable once; pi's model store covers the rest.
+
+Resolution order changed as well, and that is the part to check after an
+upgrade: `PENGEPUL_BASE_URL` and `PENGEPUL_API_KEY` now win over `auth.json`,
+where they previously lost to it. An exported key from an old shell now
+overrides the one in the credential.
+
 ## Notes
 
 - pengepul >= 0.6.0 advertises per-model context windows, output caps,

package/extensions/config.ts

@@ -1,34 +1,17 @@
 /**
- * Where the pengepul provider's fallback sources live.
+ * The environment overrides this provider reads.
  *
- * `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.
+ * `~/.pi/agent/auth.json` is the configuration surface: the pengepul entry
+ * carries the relay API key and the relay base it applies to, and
+ * `/login pengepul` writes both. These variables outrank it, so a shell or a CI
+ * run can re-point the provider without editing the file.
  */
 
-import { join } from "node:path"
-
-import { CONFIG_PATH_ENV, DEFAULT_CONFIG_PATH } from "./api-key.ts"
-
-export { CONFIG_PATH_ENV, DEFAULT_CONFIG_PATH }
-
+/** Relay base URL. Outranks the credential's `baseUrl`. */
 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 {
-  /** 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
-}
+/** Relay API key. Outranks the credential's `key`. */
+export const API_KEY_ENV = "PENGEPUL_API_KEY"
 
-export function resolveSettings(
-  env: Record<string, string | undefined>,
-  agentDir: string,
-): PengepulSettings {
-  return {
-    configPath: env[CONFIG_PATH_ENV] ?? DEFAULT_CONFIG_PATH,
-    legacyCachePath: env[MODELS_CACHE_ENV] ?? join(agentDir, "pengepul-models.json"),
-  }
-}
+/** Milliseconds before model discovery gives up. */
+export const MODELS_TIMEOUT_MS_ENV = "PENGEPUL_MODELS_TIMEOUT_MS"

package/extensions/credential.ts

@@ -4,13 +4,13 @@
  * 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.
+ * this module is pure: an env map and credential fields 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.
+ * Precedence is the same for both, highest first: the `PENGEPUL_*` environment
+ * override, then the credential, then the loopback default pengepul binds to.
  */
 
+import { API_KEY_ENV } from "./config.ts"
 import { normalizeRootBaseUrl } from "./dialect.ts"
 import { DEFAULT_RELAY_BASE } from "./models.ts"
 
@@ -38,76 +38,52 @@ export function credentialApiKey(credential: PengepulCredential | undefined): st
   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 base stored on the pengepul credential. */
+  credential?: 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.
+ * The relay root every wire appends to: the environment override, else the
+ * credential, else 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) ??
+    nonEmptyString(sources.credential) ??
     DEFAULT_RELAY_BASE
   return normalizeRootBaseUrl(chosen)
 }
 
 export interface ApiKeySources {
+  /** The `PENGEPUL_API_KEY` environment value. */
+  environment?: string | undefined
   /** 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)
+/** Which source answered, as the auth status labels it. */
+export type ApiKeySource = "PENGEPUL_API_KEY" | "stored credential"
+
+export interface ResolvedApiKey {
+  key: string
+  source: ApiKeySource
+}
+
+/**
+ * The key requests and catalog fetches use, or undefined when none is
+ * configured. The value and the label it reports come from one walk, so the
+ * status UI cannot name a source the request did not use.
+ */
+export function resolveApiKey(sources: ApiKeySources): ResolvedApiKey | undefined {
+  const environment = nonEmptyString(sources.environment)
+  if (environment) return { key: environment, source: API_KEY_ENV }
+
+  const credential = nonEmptyString(sources.credential)
+  if (credential) return { key: credential, source: "stored credential" }
+
+  return undefined
 }

package/extensions/index.ts

@@ -4,36 +4,18 @@
  * 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.
+ * back on every refresh, so `auth.json` carries the key and the relay base, and
+ * the `PENGEPUL_*` environment variables override both. The pure core is
+ * `./credential.ts`, `./dialect.ts`, and `./models.ts`; this file adapts them to
+ * the pi ExtensionAPI seam and reads nothing of its own.
  */
 
-import {
-  getAgentDir,
-  type ExtensionAPI,
-} from "@earendil-works/pi-coding-agent"
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { getBuiltinModel, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all"
-import { readFileSync } from "node:fs"
 
-import { resolveSettings } from "./config.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
-  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 {
@@ -88,17 +70,13 @@ function createBuiltinLookup(): (id: string, dialect: string) => ReturnType<type
 
 /**
  * Model discovery belongs to pi: it calls `refreshModels` with the resolved
- * credential, first against pi's cached catalog and then, when the network is
+ * credential, first against pi's model store 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 function (pi: ExtensionAPI) {
-  const settings = resolveSettings(process.env, getAgentDir())
-
   const provider = createPengepulProvider({
     env: process.env,
-    configText: readConfigText(settings.configPath),
-    legacyCachePath: settings.legacyCachePath,
     lookupBuiltin: createBuiltinLookup(),
   })
 

package/extensions/models.ts

@@ -2,10 +2,11 @@
  * 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.
+ * pi-ai `ProviderModelConfig` shape. Discovery is pi's to drive: the catalog
+ * lives in pi's model store between runs, so a briefly absent relay is covered
+ * by the store the provider registered rather than by a file this module owns.
+ * 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`,
@@ -17,11 +18,10 @@
  * 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.
+ * The catalog fetch is injected as well, so this module holds no hidden
+ * network access and tests pin the transport.
  */
 
-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"
@@ -32,8 +32,6 @@ 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 }
-/** v5 cached entries predate the relay-uniform off/minimal overlay (foreign catalog maps offered levels the relay 400s); reject it. */
-const MODEL_CACHE_VERSION = 6
 
 export type ModelInput = ("text" | "image")[]
 
@@ -491,10 +489,10 @@ function isBatchRoute(id: string): boolean {
 }
 
 /**
- * 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.
+ * Drop the ids this relay cannot serve on either wire, on the way in from the
+ * relay. The store replays what pi persisted, so a route this filter drops
+ * survives in a store written before the filter existed only until the next
+ * successful fetch replaces it.
  */
 function servableModels(models: readonly PengepulModel[]): PengepulModel[] {
   return models.filter((model) => !isBatchRoute(model.id))
@@ -524,8 +522,22 @@ export function modelsFromApiResponse(
 
 import type { Api, Model } from "@earendil-works/pi-ai"
 
+/**
+ * Prompt cache lifetime in seconds for each retention tier a request can ask
+ * for, the shape pi reads off a model to decide when to refresh its cache
+ * entry. Declared here because pi-ai 0.85.1's `Model` has no `promptCache`;
+ * a host that predates the field ignores it.
+ */
+export interface PromptCacheTiers {
+  short: number
+  long: number
+}
+
 /** The pi-ai model shapes this provider serves: one per dialect the relay speaks. */
-export type PengepulModelEntry = Model<"anthropic-messages"> | Model<"openai-completions">
+export type PengepulModelEntry = (
+  | Model<"anthropic-messages">
+  | Model<"openai-completions">
+) & { promptCache?: PromptCacheTiers }
 
 /** The provider id every pengepul model is stamped with. */
 export const PENGEPUL_PROVIDER_ID = "pengepul"
@@ -564,18 +576,17 @@ function sharedModelFields(model: PengepulModel, relayBase: string) {
  * 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.
+ * `prompt_cache_key` at all, and pi-ai hardcodes `x-session-affinity` there up
+ * to 0.85.1, which this relay does not read. Messages traffic therefore rests
+ * on the relay's prefix fallback until 0.87, where `sessionAffinityFormat`
+ * starts being read on that dialect too and the same `openrouter` value lands
+ * as `x-session-id`.
  *
- * 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.
+ * The field is re-declared below rather than taken from
+ * `AnthropicMessagesCompat` so the pin does not depend on the host's pi-ai
+ * version: 0.85.1 ignores a value it never types, 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 {
@@ -584,6 +595,32 @@ function affinityPin() {
   }
 }
 
+/**
+ * Anthropic's prompt cache lifetimes: five minutes by default, one hour when
+ * the request asks for the extended TTL. Copied per model rather than shared,
+ * so nothing downstream can mutate one model's lifetimes into another's.
+ *
+ * pi reads `model.promptCache[tier]` to know when the entry a request wrote
+ * expires, and skips warming a model whose lifetime it cannot resolve
+ * (`cache-warmer.js` `getPromptCacheTtlMs`). No pi catalog answers for a relay
+ * id, so a Claude model served here would otherwise never be warmed: any idle
+ * past the TTL — five minutes on the default tier — re-bills the whole prefix
+ * at the write rate, which for a 700k-token Opus conversation is dollars per
+ * miss.
+ *
+ * Only the Messages wire gets them. Those ids are the ones the relay forwards
+ * to Anthropic's own API, whose lifetimes these are; the Chat Completions wire
+ * serves aggregated vendors (commandcode, openrouter) through upstreams whose
+ * cache lifetimes this provider has no measurement for, and pi does not warm a
+ * lifetime it cannot resolve.
+ *
+ * Measured, not assumed: a `cache_control` ttl of `1h` on this wire comes back
+ * with the whole prefix in `usage.cache_creation.ephemeral_1h_input_tokens`,
+ * so the relay passes the extended TTL through and `PI_CACHE_RETENTION=long`
+ * buys the hour declared here.
+ */
+const ANTHROPIC_PROMPT_CACHE: PromptCacheTiers = { short: 300, long: 3600 }
+
 /**
  * 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
@@ -635,6 +672,10 @@ export function toPengepulModels(
         // 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.
+        //
+        // The lifetimes pi's cache warmer schedules its refreshes against, on
+        // this wire only, for the reason just given.
+        promptCache: { ...ANTHROPIC_PROMPT_CACHE },
         compat: {
           ...affinityPin(),
           ...(adaptive ? { forceAdaptiveThinking: true as const } : {}),
@@ -692,11 +733,6 @@ interface FetchModelsOptions {
   lookupBuiltin?: BuiltinModelLookup
 }
 
-interface LoadModelsOptions extends FetchModelsOptions {
-  cachePath: string
-  relayBase: string
-}
-
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
@@ -816,95 +852,3 @@ export async function fetchPengepulModels(
 
   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") }
-        : {}),
-    }
-  })
-  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[]> {
-  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 []
-  }
-}
-
-

package/extensions/provider.ts

@@ -2,11 +2,11 @@
  * 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.
+ * hands the credential back to `refreshModels`. Discovery and requests
+ * therefore resolve the same key and the same relay base: environment first,
+ * then the credential. A provider declared as plain config values has no
+ * credential at discovery time, so a key stored in `auth.json` left its
+ * catalog fetch with nothing to send but an environment variable, and a 401.
  *
  * 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
@@ -27,12 +27,10 @@ import type {
 } 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 { API_KEY_ENV, RELAY_BASE_ENV } from "./config.ts"
 import {
   credentialApiKey,
   credentialRelayBase,
-  relayBaseFromConfigText,
   resolveApiKey,
   resolveRelayBase,
   type PengepulCredential,
@@ -43,7 +41,6 @@ import {
   fetchPengepulModels,
   getModelsTimeoutMs,
   isPengepulModelEntry,
-  loadCachedPengepulModels,
   PENGEPUL_PROVIDER_ID,
   restampRelayBase,
   toPengepulModels,
@@ -58,16 +55,9 @@ export interface PengepulApiKeyCredential extends ApiKeyCredential {
   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. */
@@ -90,9 +80,9 @@ function isPengepulDialect(api: Api): api is PengepulDialect {
 /**
  * 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.
+ * The environment overrides are read from the captured environment, 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
@@ -104,23 +94,23 @@ export function createPengepulProvider(options: PengepulProviderOptions): Provid
 
   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 {}
+  /** The relay base in force: the environment override, else the credential, else loopback. */
+  function relayBaseFor(credential: unknown): string {
+    return resolveRelayBase({
+      environment: environmentRelayBase,
+      credential: credentialRelayBase(credential as PengepulCredential | undefined),
+    })
   }
 
-  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()
+  /** The key in force, with the label the status UI shows for it. */
+  function resolveKey(credential: unknown) {
+    return resolveApiKey({
+      environment: environmentApiKey,
+      credential: credentialApiKey(credential as PengepulCredential | undefined),
+    })
   }
 
   const streams: Record<PengepulDialect, ProviderStreams> = {
@@ -138,38 +128,26 @@ export function createPengepulProvider(options: PengepulProviderOptions): Provid
     })
   }
 
-  async function restoreOrSeed(context: RefreshModelsContext): Promise<boolean> {
-    const relayBase = resolveRelayBase({
-      credential: credentialRelayBase(context.credential as PengepulCredential | undefined),
-      environment: environmentRelayBase,
-      config: configRelayBase,
-    })
-
+  /**
+   * Re-publish pi's stored catalog with every base URL re-derived from the
+   * base in force, so a relay that moved is not reached at its old address.
+   * Returns false only when pi refused the publication, the one case that
+   * skips the network phase.
+   */
+  async function restoreStored(context: RefreshModelsContext): Promise<boolean> {
     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 } })
+    if (stored.length === 0) return true
+    const restored = restampRelayBase(stored, relayBaseFor(context.credential))
+    return context.publish({ update: () => { models = restored } })
   }
 
   async function refreshFromRelay(context: RefreshModelsContext): Promise<void> {
-    const relayBase = resolveRelayBase({
-      credential: credentialRelayBase(context.credential as PengepulCredential | undefined),
-      environment: environmentRelayBase,
-      config: configRelayBase,
-    })
+    const relayBase = relayBaseFor(context.credential)
 
     const resolved = resolveKey(context.credential)
-    if (!resolved.key) {
+    if (!resolved) {
       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.`,
+        `No pengepul API key is configured (${API_KEY_ENV} or auth.json), so the model catalog cannot be refreshed. Run /login pengepul.`,
       )
       return
     }
@@ -201,10 +179,7 @@ export function createPengepulProvider(options: PengepulProviderOptions): Provid
   return {
     id: PENGEPUL_PROVIDER_ID,
     name: "Pengepul",
-    baseUrl: resolveRelayBase({
-      environment: environmentRelayBase,
-      config: configRelayBase,
-    }),
+    baseUrl: resolveRelayBase({ environment: environmentRelayBase }),
     auth: {
       apiKey: {
         name: "Pengepul relay",
@@ -231,25 +206,20 @@ export function createPengepulProvider(options: PengepulProviderOptions): Provid
         },
         check: async (input): Promise<AuthCheck | undefined> => {
           const resolved = resolveKey(input.credential)
-          return resolved.key
-            ? { type: "api_key", ...(resolved.source ? { source: resolved.source } : {}) }
-            : undefined
+          return resolved ? { type: "api_key", source: resolved.source } : undefined
         },
         resolve: async (input): Promise<AuthResult | undefined> => {
           const resolved = resolveKey(input.credential)
-          if (!resolved.key) return undefined
+          if (!resolved) 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 } : {}),
-          }
+          return { auth: { apiKey: resolved.key }, source: resolved.source }
         },
       },
     },
     getModels: () => models,
     refreshModels: async (context) => {
-      if (!(await restoreOrSeed(context))) return
+      if (!(await restoreStored(context))) return
       if (!context.allowNetwork || context.signal.aborted) return
       await refreshFromRelay(context)
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pwguler/pi-pengepul-provider",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "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",

package/extensions/api-key.ts

@@ -1,70 +0,0 @@
-/**
- * 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>`.
- *
- * 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.
- */
-
-export const DEFAULT_CONFIG_PATH = "~/.pengepul/config.yaml"
-
-export const API_KEY_ENV = "PENGEPUL_API_KEY"
-export const CONFIG_PATH_ENV = "PENGEPUL_CONFIG"
-
-/**
- * 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
-}