@pwguler/pi-pengepul-provider 0.2.3 → 0.2.4

package/README.md

@@ -86,11 +86,33 @@ is set.
 ## Development
 
 ```sh
+npm install
 bun test
 npx tsc --noEmit
 bun scripts/e2e-live.ts # live e2e against a running relay; sends one tiny completion
 ```
 
+The `@earendil-works/*` copies `npm install` writes into `node_modules` are for
+`tsc` and the tests only. At runtime pi serves the extension those modules from
+its own bundle (`loader.js` maps `@earendil-works/pi-ai/providers/all` to a
+virtual module), so the local copies exist to be *type-checked against*, not to
+be the ones in play.
+
+Nothing here can enforce that the two match: the peer ranges are `*` and the
+host's version is not knowable at install time. The lockfile records whichever
+version was current when it was last refreshed, so the comparison is a manual
+one, worth making whenever a measurement has to be trusted:
+
+```sh
+pi --version                                            # host pi release
+cat node_modules/@earendil-works/pi-ai/package.json     # local copy
+```
+
+When they drift, anything measured from this directory describes a different
+model catalog than the running extension sees — the 0.84.4 copy carried 40
+`:batch` entries where 0.85.1 carries 68 — and local verification quietly
+disagrees with production.
+
 ## Releasing
 
 Releases publish from CI on a version tag. Bump, tag, push:

package/extensions/index.ts

@@ -19,6 +19,7 @@ import { resolveApiKey } from "./api-key.ts"
 import { resolveSettings } from "./config.ts"
 import { modelsUrl } from "./dialect.ts"
 import {
+  catalogIdForms,
   loadCachedPengepulModels,
   loadPengepulModels,
   toProviderModelConfigs,
@@ -53,11 +54,10 @@ function metaFromModel(model: NonNullable<ReturnType<typeof getBuiltinModel>>) {
 }
 
 /**
- * Multi-catalog lookup over pi's builtin models. A commandcode id can live
- * in several catalogs: verbatim under an aggregator (`openrouter`, `baseten`,
- * `together`, ...), bare under a vendor catalog (`deepseek`, `google`,
- * `xai`, ...), or bare lowercased. Try those shapes in that order and take
- * the first hit; reasoning metadata and the thinkingLevelMap flow from it.
+ * Multi-catalog lookup over pi's builtin models. A relay id can match several
+ * catalogs, so each of the id's shapes is tried in turn - verbatim, bare under
+ * a vendor catalog, last segment, and with the routing namespace removed - and
+ * the first hit wins. Reasoning metadata and the thinkingLevelMap flow from it.
  */
 function createBuiltinLookup(): (id: string, dialect: string) => ReturnType<typeof metaFromModel> | undefined {
   type Entry = { provider: string; id: string };
@@ -77,27 +77,22 @@ function createBuiltinLookup(): (id: string, dialect: string) => ReturnType<type
   }
 
   return (id, dialect) => {
-    const candidates: Array<Entry | undefined> = [
-      exact.get(id),
-      exact.get(bareOf(id)),
-      segments.get(bareOf(id)),
-      lower.get(id.toLowerCase()),
-      lower.get(bareOf(id).toLowerCase()),
-    ]
-    for (const candidate of candidates) {
-      if (candidate === undefined) continue
-      const model = getBuiltinModel(candidate.provider as never, candidate.id as never)
-      if (model) return metaFromModel(model)
+    for (const form of catalogIdForms(id)) {
+      const candidates: Array<Entry | undefined> = [
+        exact.get(form),
+        segments.get(form),
+        lower.get(form.toLowerCase()),
+      ]
+      for (const candidate of candidates) {
+        if (candidate === undefined) continue
+        const model = getBuiltinModel(candidate.provider as never, candidate.id as never)
+        if (model) return metaFromModel(model)
+      }
     }
     return undefined
   }
 }
 
-function bareOf(id: string): string {
-  const slash = id.lastIndexOf("/")
-  return slash === -1 ? id : id.slice(slash + 1)
-}
-
 function createProviderConfigFactory(relayBase: string, apiKey: string | undefined) {
   return (models: readonly PengepulModel[]): ProviderConfig => ({
     name: "Pengepul",

package/extensions/models.ts

@@ -140,6 +140,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 +229,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 +280,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 +311,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 +348,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 +407,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,12 +442,16 @@ 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. */
@@ -431,9 +555,7 @@ export function toProviderModelConfigs(
 
 /** 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 {
@@ -639,8 +761,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[]> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pwguler/pi-pengepul-provider",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "pi custom provider for pengepul, a local relay that pools your Claude/Codex subscriptions. Connects pi to http://127.0.0.1:8317 over the native Anthropic Messages and OpenAI Chat Completions wires.",
   "license": "MIT",