pi-inferhub 0.1.1 → 0.3.0

package/LICENSE

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

package/README.md

@@ -7,9 +7,10 @@ InferHub **combos** as selectable chat models.
 InferHub pools AI subscriptions behind one OpenAI-compatible endpoint. Combos
 are its server-side routed bundles — failover, cache-sticky, billed in USDC —
 and they are the primary consumption surface. This extension exposes **combos
-only**: each combo on your account appears as exactly one model named
-`combo/<slug>`. Upstream `prefix/model` entries, bare-name aliases, and
-free-tier models from InferHub's model list are intentionally not exposed.
+only by default**: each combo on your account appears as exactly one model
+named `combo/<slug>`. Upstream `prefix/model` entries, bare-name aliases, and
+free-tier models are not exposed unless you opt in with
+[`publishUpstream`](#full-upstream-catalog-optional).
 
 ## Install
 
@@ -51,9 +52,30 @@ points you to `/login inferhub` if not.
 ## Model selection
 
 Send `/model` and filter by provider name `inferhub` or by `combo/`. Each
-model id is `combo/<slug>` — the routable inference name on
+combo model id is `combo/<slug>` — the routable inference name on
 `https://api.inferhub.dev/v1`.
 
+## Configuration
+
+Optional `~/.pi/agent/pi-inferhub.json` (or `$PI_AGENT_DIR/pi-inferhub.json`).
+A missing file means defaults; a malformed one logs an issue and keeps the
+defaults — it never breaks startup.
+
+```json
+{ "publishUpstream": true }
+```
+
+### Full upstream catalog (optional)
+
+`publishUpstream` (default `false`) additionally publishes every chat model
+from `/v1/models` as a direct-selectable `prefix/model` entry, listed after
+the combos. This bypasses combo routing — you pick one specific serving — and
+is intended for pinning a particular upstream. Alias rows, `free/` tiers, and
+image/video generation models are never published, even with the option on.
+
+The `INFERHUB_PUBLISH_UPSTREAM` environment variable overrides the file in
+both directions (`1/true/yes/on`, `0/false/no/off`).
+
 ## Catalog derivation
 
 On refresh the extension makes two authenticated GETs —
@@ -63,19 +85,29 @@ combo to one model:
 
 - **Context/output limits** — minimum across resolvable members
   (`input_token_limit` / `max_output_tokens`), so a combo is only as large as
-  its smallest member. When no resolvable member supplies limits, conservative
-  fallbacks apply: **128k context / 8k max output**.
+  its smallest member. When no resolvable member supplies limits, fallbacks
+  apply: **256k context / 128k max output**. A limit of `0` is treated as
+  missing data rather than a real ceiling.
+- **Output cap enforcement** — `max_tokens` is sent rather than
+  `max_completion_tokens`, because InferHub ignores the latter (a request
+  capped at 20 tokens still produced 107).
 - **Image input** — offered (`text` + `image`) only when *every* resolvable
   member's modality includes image; otherwise text-only.
-- **Reasoning** — the combo is marked reasoning-capable when any resolvable
-  member advertises `reasoning_levels`; Pi's thinking levels map onto the
-  advertised ladder (levels a combo doesn't advertise are unavailable).
+- **Reasoning** — combos are always marked reasoning-capable: a false
+  negative hides Pi's thinking knob (the worse error), while a false positive
+  only shows an inert one. Where members advertise `reasoning_levels`, Pi's
+  levels map onto that union; when none advertise a ladder the map is omitted
+  so every level stays selectable.
 - **Cost** — per-direction minimum of resolvable members' *official* rates
   (see below). `cacheRead`/`cacheWrite` are shown as `0`: the catalog carries
   no per-combo cache pricing, and none is fabricated.
 
-Combos whose members are all unresolvable aliases get safe defaults:
-text-only, reasoning-capable, `0` cost, and the fallback limits.
+Member resolution is conservative but forgiving: a member resolves directly
+from `/v1/models` when its prefixed row carries data; otherwise it joins the
+prefixed servings of the same model name (exact suffix first, then a
+normalized last-segment match, which covers multi-segment prefixes such as
+`cp/cline-pass/<model>`). Combos whose members resolve to nothing at all get
+safe defaults: text-only, reasoning-capable, `0` cost, and the fallback limits.
 
 ## Refresh semantics
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-inferhub",
-	"version": "0.1.1",
+	"version": "0.3.0",
 	"description": "Pi extension for the InferHub inference provider",
 	"license": "MIT",
 	"keywords": [
@@ -23,9 +23,15 @@
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
-		"@earendil-works/pi-ai": { "optional": false },
-		"@earendil-works/pi-coding-agent": { "optional": false },
-		"typebox": { "optional": false }
+		"@earendil-works/pi-ai": {
+			"optional": false
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": false
+		},
+		"typebox": {
+			"optional": false
+		}
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^1.0.4",
@@ -34,5 +40,17 @@
 		"typebox": "^1.3.36",
 		"typescript": "^6.0.3",
 		"vitest": "^5.0.3"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/damnmersault/pi-inferhub.git"
 	}
 }

package/src/catalog.ts

@@ -7,8 +7,8 @@ import { INFERENCE_BASE_URL, MGMT_BASE_URL, PROVIDER_NAME } from "./inferhub.js"
 /** pi thinking levels, in ladder order; `off` is handled separately. */
 const PI_THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly ThinkingLevel[];
 
-const CONTEXT_WINDOW_FALLBACK = 128_000;
-const MAX_TOKENS_FALLBACK = 8_192;
+const CONTEXT_WINDOW_FALLBACK = 262_144;
+const MAX_TOKENS_FALLBACK = 131_072;
 
 export const MemberSchema = Type.Union([
 	Type.Object({ kind: Type.Literal("model"), model: Type.String() }),
@@ -24,9 +24,15 @@ export const ComboSchema = Type.Object({
 });
 export type Combo = Static<typeof ComboSchema>;
 
+/** Live-pinned 2026-10-15: bare (prefix-less) catalog rows are aliases served by
+ *  prefixed upstream rows — they carry owned_by "alias" and NO limits/pricing/
+ *  reasoning fields at all. Unknown extra fields pass validation regardless. */
 export const CatalogModelSchema = Type.Object({
 	id: Type.String(),
+	owned_by: Type.Optional(Type.String()),
 	modality: Type.Optional(Type.String()),
+	output_modality: Type.Optional(Type.String()),
+	upstream_label: Type.Optional(Type.String()),
 	input_token_limit: Type.Optional(Type.Number()),
 	max_output_tokens: Type.Optional(Type.Number()),
 	reasoning_levels: Type.Optional(Type.Array(Type.String())),
@@ -34,6 +40,8 @@ export const CatalogModelSchema = Type.Object({
 		Type.Object({
 			official_in: Type.Number(),
 			official_out: Type.Number(),
+			min_ask_in: Type.Optional(Type.Number()),
+			min_ask_out: Type.Optional(Type.Number()),
 		}),
 	),
 });
@@ -45,22 +53,34 @@ export type CatalogModel = Static<typeof CatalogModelSchema>;
  * validation (no additionalProperties restrictions).
  */
 const CombosEnvelope = Type.Array(ComboSchema);
+/** Bare (prefix-less) alias row shape observed live 2026-10-15:
+ *  {id, object:"model", created, owned_by:"alias", supports_cache} — no limits,
+ *  pricing, modality, or reasoning fields at all. Prefixed servings of the same
+ *  model carry the data; catalog.ts resolves aliases through them (sibling join). */
 const ModelsEnvelope = Type.Object({ data: Type.Array(CatalogModelSchema) });
 
 const CombosValidator = Compile(CombosEnvelope);
 const ModelsValidator = Compile(ModelsEnvelope);
 
+export interface FetchCatalogOptions extends FetchJsonOptions {
+	/** Also publish direct-selectable upstream models from /v1/models. */
+	publishUpstream?: boolean;
+}
+
 /** GET /combos + GET /v1/models (independent), then map combos to pi models. */
 export async function fetchComboCatalog(
 	token: string,
 	signal?: AbortSignal,
-	opts?: FetchJsonOptions,
+	opts?: FetchCatalogOptions,
 ): Promise<Model<"openai-completions">[]> {
 	const [combos, models] = await Promise.all([
 		fetchJson<Combo[]>(`${MGMT_BASE_URL}/combos`, token, CombosValidator, signal, opts),
 		fetchJson<Static<typeof ModelsEnvelope>>(`${INFERENCE_BASE_URL}/models`, token, ModelsValidator, signal, opts),
 	]);
-	return combosToModels(combos, models.data);
+	const comboModels = combosToModels(combos, models.data);
+	// Combos are the product: they stay first. The upstream catalog only widens
+	// the list when the operator opts in.
+	return opts?.publishUpstream ? [...comboModels, ...catalogToModels(models.data)] : comboModels;
 }
 
 /** Pure combo → Model mapping; output order follows `combos` order. */
@@ -69,35 +89,98 @@ export function combosToModels(
 	catalogModels: CatalogModel[],
 ): Model<"openai-completions">[] {
 	const catalogById = new Map(catalogModels.map((model) => [model.id, model]));
-	return combos.map((combo) => comboToModel(combo, catalogById));
+	return combos.map((combo) => comboToModel(combo, catalogById, catalogModels));
 }
 
 function comboToModel(
 	combo: Combo,
 	catalogById: Map<string, CatalogModel>,
+	catalogModels: CatalogModel[],
 ): Model<"openai-completions"> {
+	// Alias rows (`owned_by: "alias"`, no data) and alias-kind members resolve
+	// through prefixed sibling servings of the same model name; min-of over the
+	// siblings bounds the combo exactly like directly-joined members.
+	//
+	// Live shape 2026-10-18: combos reference multi-segment prefixes
+	// (cp/cline-pass/<model>, cp/zai/<model>) that have no exact serving, while
+	// the same model is served under another prefix (zai/<model>,
+	// cmc/moonshotai/<model>). Exact suffix matches win; the normalized
+	// last-segment name is the recovery path, never a wider net.
 	const resolvable: CatalogModel[] = [];
 	for (const member of combo.members) {
-		if (member.kind !== "model") continue;
-		const entry = catalogById.get(member.model);
-		if (entry !== undefined) resolvable.push(entry);
+		const name = member.kind === "model" ? member.model : member.alias;
+		const entry = member.kind === "model" ? catalogById.get(member.model) : undefined;
+		if (entry !== undefined && entry.owned_by !== "alias") {
+			resolvable.push(entry);
+			continue;
+		}
+		const exact = catalogModels.filter(
+			(sibling) => sibling.owned_by !== "alias" && sibling.id.endsWith(`/${name}`),
+		);
+		if (exact.length > 0) {
+			resolvable.push(...exact);
+			continue;
+		}
+		const normalized = normalizeModelName(name);
+		if (normalized.length > 0) {
+			resolvable.push(
+				...catalogModels.filter(
+					(sibling) => sibling.owned_by !== "alias" && normalizeModelName(sibling.id) === normalized,
+				),
+			);
+		}
 	}
 
-	// Alias-only / all-missed-join combos reason optimistically: a false
-	// negative hides thinking levels, a false positive shows an inert knob.
+	// Optimistic by design: a false negative hides thinking levels (the worse
+	// error); a false positive shows an inert knob. Applies to every combo,
+	// including level-less resolved members (live-verified 2026-10-18 on
+	// combo/deepseek-v4-pro: no advertised levels, honors reasoning_effort).
+	const name = combo.name.trim().length > 0 ? combo.name : combo.slug;
+	return buildModel(`combo/${combo.slug}`, name, resolvable);
+}
+
+/**
+ * Direct-selectable upstream models from `/v1/models`, in catalog order.
+ * Skipped: alias rows (information-free duplicates of a prefixed serving),
+ * image-output rows (not chat models), and blank ids (live shape `cc/`).
+ */
+export function catalogToModels(catalogModels: CatalogModel[]): Model<"openai-completions">[] {
+	return catalogModels
+		.filter(
+			(row) =>
+				row.owned_by !== "alias" &&
+				// AGENTS.md product rule: never surface image/video generation or
+				// `free/` tier models, even when the upstream catalog is published.
+				row.output_modality !== "image" &&
+				row.output_modality !== "video" &&
+				!row.id.startsWith("free/") &&
+				// Live shape `cc/`: prefix with an empty model segment — not selectable.
+				(row.id.split("/").pop() ?? "").trim().length > 0,
+		)
+		.map((row) => {
+			const label = row.upstream_label?.trim();
+			return buildModel(row.id, label && label.length > 0 ? label : row.id, [row]);
+		});
+}
+
+/** Shared pi-model construction for combo and direct-catalog entries. */
+function buildModel(
+	id: string,
+	name: string,
+	sources: CatalogModel[],
+): Model<"openai-completions"> {
 	const advertised = new Set<string>();
-	for (const model of resolvable) {
+	for (const model of sources) {
 		for (const level of model.reasoning_levels ?? []) advertised.add(level);
 	}
-	const reasoning = resolvable.length === 0 || advertised.size > 0;
 
-	const image = resolvable.length > 0 && resolvable.every((model) => (model.modality ?? "").includes("image"));
+	const image = sources.length > 0 && sources.every((model) => (model.modality ?? "").includes("image"));
 
-	const priced = resolvable.flatMap((model) => (model.pricing ? [model.pricing] : []));
+	const priced = sources.flatMap((model) => (model.pricing ? [model.pricing] : []));
 
 	const model: Model<"openai-completions"> = {
-		id: `combo/${combo.slug}`,
-		name: combo.name.trim().length > 0 ? combo.name : combo.slug,
+		id,
+		name,
 		api: "openai-completions",
 		provider: PROVIDER_NAME,
 		baseUrl: INFERENCE_BASE_URL,
@@ -108,17 +191,27 @@ function comboToModel(
 			cacheRead: 0,
 			cacheWrite: 0,
 		},
-		reasoning,
-		contextWindow: minOf(resolvable.map((m) => m.input_token_limit)) ?? CONTEXT_WINDOW_FALLBACK,
-		maxTokens: minOf(resolvable.map((m) => m.max_output_tokens)) ?? MAX_TOKENS_FALLBACK,
+		reasoning: true,
+		contextWindow: minPositiveOf(sources.map((source) => source.input_token_limit)) ?? CONTEXT_WINDOW_FALLBACK,
+		maxTokens: minPositiveOf(sources.map((source) => source.max_output_tokens)) ?? MAX_TOKENS_FALLBACK,
+		// InferHub's [OI]-compatible surface ignores max_completion_tokens (verified
+		// live 2026-10-18: a 20-token cap sent that way produced 107 tokens; the
+		// same cap as max_tokens stopped at 20). pi-ai auto-detects per-provider
+		// and inferhub is not on its list, so pin the field explicitly.
+		compat: { maxTokensField: "max_tokens" },
 	};
-	// thinkingLevelMap: built only from an advertised union; an empty union
-	// (alias-only combos) omits the map so pi defaults keep thinking levels
-	// selectable — marking them all `null` would hide the knob entirely.
-	if (reasoning && advertised.size > 0) model.thinkingLevelMap = buildThinkingLevelMap(advertised);
+	// thinkingLevelMap: built only from an advertised union; a level-less union
+	// omits the map so pi defaults keep thinking levels selectable — marking
+	// them all `null` would hide the knob entirely.
+	if (advertised.size > 0) model.thinkingLevelMap = buildThinkingLevelMap(advertised);
 	return model;
 }
 
+/** Last path segment, lowercased, alphanumerics only: "cp/cline-pass/Kimi-K3" → "kimik3". */
+function normalizeModelName(id: string): string {
+	return (id.split("/").pop() ?? id).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
 /** Each pi level maps to itself when the combo advertises it, else `null`. */
 function buildThinkingLevelMap(advertised: ReadonlySet<string>): ThinkingLevelMap {
 	const map: ThinkingLevelMap = { off: "off" };
@@ -132,3 +225,9 @@ function minOf(values: Array<number | undefined>): number | undefined {
 	const present = values.filter((value): value is number => value !== undefined);
 	return present.length > 0 ? Math.min(...present) : undefined;
 }
+
+/** Limits: 0 (or non-finite) is missing data, never a real ceiling. Prices keep 0. */
+function minPositiveOf(values: Array<number | undefined>): number | undefined {
+	const present = values.filter((value): value is number => value !== undefined && Number.isFinite(value) && value > 0);
+	return present.length > 0 ? Math.min(...present) : undefined;
+}

package/src/config.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Canonical config file for this package, under pi's agent dir. */
+export const CONFIG_FILE_NAME = "pi-inferhub.json";
+
+/** Env override for `publishUpstream`; wins over the file when set. */
+export const PUBLISH_UPSTREAM_ENV = "INFERHUB_PUBLISH_UPSTREAM";
+
+export interface InferhubConfig {
+	/**
+	 * Also publish every chat model from `/v1/models` as a direct-selectable
+	 * `prefix/model` entry, alongside the `combo/<slug>` models. Combos stay
+	 * first; this only widens the catalog. Default: false.
+	 */
+	publishUpstream: boolean;
+	/** Human-readable problems found while loading; never fatal. */
+	issues: string[];
+}
+
+/** pi's agent dir: `PI_AGENT_DIR` when set, else `~/.pi/agent`. */
+export function defaultAgentDir(): string {
+	return process.env.PI_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+function parseEnvBoolean(raw: string): boolean | undefined {
+	const value = raw.trim().toLowerCase();
+	if (["1", "true", "yes", "on"].includes(value)) return true;
+	if (["0", "false", "no", "off"].includes(value)) return false;
+	return undefined;
+}
+
+/**
+ * Load `<agentDir>/pi-inferhub.json`. Missing file = defaults; malformed file =
+ * defaults + issue; unknown keys are ignored, wrong-typed values are reported
+ * and leave the default in place. Never throws for file content problems.
+ */
+export function loadInferhubConfig(agentDir: string = defaultAgentDir()): InferhubConfig {
+	const issues: string[] = [];
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(join(agentDir, CONFIG_FILE_NAME), "utf8"));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException)?.code;
+		if (code === "ENOENT") return { publishUpstream: false, issues };
+		const message = error instanceof Error ? error.message : String(error);
+		issues.push(`${CONFIG_FILE_NAME} is not valid JSON (${message}); using defaults`);
+		return { publishUpstream: false, issues };
+	}
+
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		issues.push(`${CONFIG_FILE_NAME} must contain a JSON object; using defaults`);
+		return { publishUpstream: false, issues };
+	}
+
+	let publishUpstream = false;
+	for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (key !== "publishUpstream") continue;
+		if (typeof value === "boolean") publishUpstream = value;
+		else issues.push(`publishUpstream must be a boolean (got ${typeof value}); using false`);
+	}
+
+	const envRaw = process.env[PUBLISH_UPSTREAM_ENV];
+	if (envRaw !== undefined) {
+		const envValue = parseEnvBoolean(envRaw);
+		if (envValue === undefined) {
+			issues.push(`${PUBLISH_UPSTREAM_ENV} must be a boolean-like value; ignoring`);
+		} else {
+			publishUpstream = envValue;
+		}
+	}
+
+	return { publishUpstream, issues };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
 import { inferhubApiKeyAuth, loginInferhub } from "./auth.js";
 import { fetchComboCatalog } from "./catalog.js";
+import { type InferhubConfig, loadInferhubConfig } from "./config.js";
 import { INFERENCE_BASE_URL, PROVIDER_DISPLAY_NAME, PROVIDER_NAME } from "./inferhub.js";
 
 /**
@@ -17,7 +18,13 @@ export interface InferhubRegistrationPi {
 	registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: ExtensionCommandContext) => Promise<void> }): void;
 }
 
-function inferhubProvider(): Provider<"openai-completions"> {
+export interface InferhubRegistrationOptions {
+	/** Config loader seam; production reads `<agentDir>/pi-inferhub.json`. */
+	loadConfig?: () => InferhubConfig;
+}
+
+function inferhubProvider(options: InferhubRegistrationOptions = {}): Provider<"openai-completions"> {
+	const loadConfig = options.loadConfig ?? (() => loadInferhubConfig());
 	return createProvider({
 		id: PROVIDER_NAME,
 		name: PROVIDER_DISPLAY_NAME,
@@ -36,15 +43,15 @@ function inferhubProvider(): Provider<"openai-completions"> {
 			const credential = context.credential;
 			const token = credential?.type === "api_key" ? credential.key : undefined;
 			if (!token) return [];
-			return fetchComboCatalog(token, context.signal);
+			return fetchComboCatalog(token, context.signal, { publishUpstream: loadConfig().publishUpstream });
 		},
 		api: openAICompletionsApi(),
 	});
 }
 
 /** Register the InferHub provider and its companion command. */
-export function registerInferhubProvider(pi: InferhubRegistrationPi): void {
-	pi.registerProvider(inferhubProvider());
+export function registerInferhubProvider(pi: InferhubRegistrationPi, options?: InferhubRegistrationOptions): void {
+	pi.registerProvider(inferhubProvider(options));
 
 	// pi's registerCommand takes a single command name; `/login inferhub` is
 	// provided by pi's auth system through the apiKey login wired above. This
@@ -55,7 +62,7 @@ export function registerInferhubProvider(pi: InferhubRegistrationPi): void {
 			const status = ctx.modelRegistry.getProviderAuthStatus(PROVIDER_NAME);
 			if (status?.configured) {
 				const source = status.label ? ` (${status.label})` : "";
-				ctx.ui.notify(`InferHub is configured${source}. Run /models to pick a combo.`, "info");
+				ctx.ui.notify(`InferHub is configured${source}. Run /model to pick a combo.`, "info");
 				return;
 			}
 			ctx.ui.notify(

package/AGENTS.md

@@ -1,136 +0,0 @@
-# pi-inferhub
-
-pi provider extension exposing the user's InferHub (https://inferhub.dev)
-**combos** as selectable chat models. Combos are the product: the extension
-never surfaces `prefix/model` upstream ids, bare aliases, `free/` tier
-models, or images/video generation. Combos are `combo/<slug>` models routed
-through InferHub's OpenAI-compatible inference surface; all failover,
-serialization, and selection happens server-side.
-
-Spec (binding design authority): `docs/superpowers/specs/2026-10-06-inferhub-provider-design.md`
-Plan: `docs/superpowers/plans/2026-10-06-inferhub-provider.md`
-
-## Architecture
-
-Four modules, acyclic, one-directional:
-
-```
-src/inferhub.ts   constants only — PROVIDER_NAME="inferhub", PROVIDER_DISPLAY_NAME="InferHub",
-                  INFERENCE_BASE_URL="https://api.inferhub.dev/v1", MGMT_BASE_URL="https://inferhub.dev/api"
-src/http.ts    ← transport only — fetchJson (Bearer GET + typebox validation), InferhubHttpError{status,code,message}
-src/auth.ts    ← loginInferhub (prompt → validate GET /me → store), inferhubApiKeyAuth (envApiKeyAuth)
-src/catalog.ts ← fetchComboCatalog (Promise.all of the two GETs), pure combosToModels for tests
-src/index.ts   ← default extension factory: createProvider registration + inferhub-login signpost command
-```
-
-No custom `streamSimple`. Everything streams through pi-ai's
-`openAICompletionsApi()` (imported from `@earendil-works/pi-ai/compat` —
-pi's extension loader does not virtualize lazy API subpaths). pi-ai owns
-message conversion, tool handling, usage, cancellation, retries. Adding a
-custom stream is a design-level decision, never a drive-by fix for an
-upstream quirk.
-
-## Wire contract (live-pinned 2026-10-07, verify before trusting)
-
-- Auth: `Authorization: Bearer sk-airo-…` on BOTH surfaces.
-- `GET MGMT_BASE_URL/combos` → **bare JSON array** of combos (id/name/slug/
-  members[]; member kinds `model` with `model: "prefix/upstream_id"` and
-  `alias` with bare name, no catalog linkage).
-- `GET INFERENCE_BASE_URL/models` → `{object:"list", data:[...]}`; items
-  carry `id, modality ("text" | "text,image"), input_token_limit,
-  max_output_tokens, reasoning_levels, pricing.official_in/official_out`.
-  Combos do NOT appear here — that is why refresh fetches /combos
-  separately. `/v1/models` requires auth (401 unauthenticated).
-- `GET MGMT_BASE_URL/me` → any JSON object; login validation endpoint.
-- Management API rate limit 30 req/min/account; inference 500 req/min/account.
-- Errors: `{"error":{"code","message"}}`; suspended/banned → 403
-  `account_blocked` with the ban reason in `message`.
-- Cost: inference responses report `usage.cost` USD (OpenRouter convention),
-  $0.00001 minimum on billed requests. All management-surface money is USDC
-  decimal strings.
-
-## Invariants (breaking any of these is a reverted commit)
-
-1. **Reserved-key play-safe**: combo-level metadata (maxInputPerMtok/
-   maxOutputPerMtok caps, selection mode, filters, sticky, members) never
-   rides on the pi-ai `Model` object. Mapped models carry exactly pi-ai
-   `Model<"openai-completions">` fields.
-2. **Cost honesty**: `cost.input/output` = per-direction MIN of resolvable
-   members' `official` rates (conservative upper bound — InferHub bills
-   discounts below official). `cost.cacheRead/cacheWrite` = 0 always —
-   InferHub's /v1/models pricing carries no cache fields; never fabricate.
-3. **Fallback constants**: `CONTEXT_WINDOW_FALLBACK = 128_000`,
-   `MAX_TOKENS_FALLBACK = 8_192` — used when no resolvable member supplies
-   the field. pi-ai's `Model` type requires both as numbers; never guess a
-   model's ceiling other than via these constants.
-4. **Image rule**: `input: ["text","image"]` only when ≥1 resolvable member
-   AND every resolvable member's `modality` includes `image`. Understating
-   input is acceptable; overstating sends requests the upstream rejects.
-5. **Alias-member fallback**: empty resolvable set (alias-only combos, or
-   all member joins missed) → `input:["text"]`, `reasoning:true`, zero
-   cost, fallback limits. `reasoning:true` is deliberate: a false negative
-   hides thinking levels (the worse error); a false positive shows an inert
-   knob.
-6. **thinkingLevelMap**: built from the union of resolvable members'
-   `reasoning_levels`; each pi level (`minimal|low|medium|high|xhigh|max`)
-   maps to itself when advertised, else `null`; `off:"off"`. Set only when
-   `reasoning` is true. Alias-only/level-less combos OMIT the map entirely —
-   an all-null map would hide every selectable level.
-7. **No key leakage**: the API key appears ONLY in the Authorization header
-   and pi's credential store (`auth.json` via pi's own store). Never log,
-   print, or persist it anywhere else. Tests inject fetch mocks; a test
-   asserting the header is fine, echoing the key in fixtures is not.
-8. **Unconfigured = zero models, no network**: `fetchModels` returns `[]`
-   and fetches nothing when auth resolves no key. pi-ai passes BOTH
-   stored-credential and env-resolved keys as `context.credential`
-   (verified in pi-ai 1.0.4 `dist/models.js` `resolveRefreshCredential`) —
-   do not add a second key-resolution path.
-9. **No cross-run catalog persistence**: refresh is always live. A stale
-   combo snapshot silently serving the wrong routing is worse than an
-   explicit refresh.
-
-## Commands
-
-```
-npx vitest run        # full suite (18 tests, <2s)
-npx tsc --noEmit      # typecheck
-npm pack --dry-run    # inspect package contents before publishing
-```
-
-pi packs the extension from `package.json` `pi.extensions:
-["./src/index.ts"]`. Local dev: `pi -e <repo path>`. Published install:
-`npm:pi-inferhub` in `~/.pi/agent/settings.json` packages (NOT yet
-published as of 2026-10-07 — v0.1.0).
-
-## Environment gotchas (learned the hard way)
-
-- **TypeScript 6.0.3**: tsconfig MUST carry `types: ["node"]` — TS 6 dropped
-  automatic `@types/*` inclusion; without it `node:module`/`fetch`/`AbortSignal`
-  don't resolve and `tsc --noEmit` fails.
-- **typebox 1.3.36**: compiled validators are typed `Validator<TProperties,
-  TSchema>` — pass the validator, not the schema, to `fetchJson`. Validation
-  error detail lives on `instancePath` (there is no `path` field). Extra
-  payload keys pass through by default; do NOT add
-  `additionalProperties: false` to wire schemas.
-- **Git signing**: fresh clones inherit `gpg.format=ssh` globally but need
-  `git config user.signingkey ~/.ssh/michaelmacleod.id_ecdsa.pub` locally
-  before the first commit fails.
-- **pi-ai `AuthEvent`** is a union; non-info variants carry no `message`.
-  Anything typing an interaction callback as `{type: string; message:
-  string}` breaks under contravariance — use `{type: string; message?:
-  string}`.
-- **Live pinning of wire shapes is allowed and encouraged** when a shape is
-  undocumented: run a free listing GET, pin the parsed envelope in a typebox
-  validator, and leave a dated comment. Drift surfaces as
-  `code: "schema_mismatch"` with `instancePath` — fail-loud by design.
-
-## Testing conventions
-
-- Typebox schemas live at module scope (`Compile(Type.Object({...}))`).
-- Tabs, ESM with `.js` import specifiers, single-responsibility modules.
-- Tests verify real behavior through public seams (`combosToModels` pure
-  function; real `createProvider` refresh path in test/index.test.ts with
-  injected `fetchImpl`). No seams into internals.
-- Deleting a brief-verbatim test line, or "fixing" a failing test by editing
-  the test to fit the code rather than the contract, is not allowed without
-  naming the contract being violated.