pi-hypercharm-provider 1.3.27 → 1.3.28

package/AGENTS.md

@@ -21,6 +21,9 @@ When a model needs overrides, new properties, or corrections, edit the appropria
 | `index.ts` | Provider extension code: model sync, streaming wrapper, footer-status wiring. |
 | `status.ts` | Footer-status presentation: config schema, hypercredit/rate-limit formatters, progressive-disclosure tiers, width-aware widget. Pure module — no pi imports; exercised by `tests/status.smoke.ts`. |
 | `scripts/update-models.js` | The sync script itself (edit only if changing how models are fetched/transformed). |
+| `identity.ts` | Every identifier this extension registers into a shared pi surface (provider id, custom api name, status/widget keys, command, prism entry type, auth key + env var, config/cache file names). `tests/identity.test.ts` enforces namespacing, uniqueness, and disjointness from the official `@charmland/pi-hyper-provider` — never hardcode one of these elsewhere. |
+| `notify.ts` | Deduplicated warning sink: fetch/parse failures go to the session UI once one is active, stderr before that, never thrown. |
+| `prism.ts` | Hyper routing-header validation (sanitizer + persisted-entry re-validation). Pure module — no pi imports; exercised by `tests/prism.test.ts`. |
 
 ## Data Flow
 
@@ -53,6 +56,27 @@ Provider API  ──fetch──►  models.json  ──apply──►  patch.jso
 
 ## TL;DR
 
+- **Never register into a shared pi surface with a hardcoded name** — add it to `identity.ts`; the co-installation tests enforce the namespace.
 - **Never edit `models.json`** — edit `patch.json` instead.
 - **Never edit the README model table** — run the update script instead.
 - `patch.json` and `custom-models.json` are the source files you should modify.
+
+## Tests
+
+`npm run check` runs `tsc --noEmit`, the dependency-free status smoke test, and
+the node:test suites (through `jiti/register` so the extension's extensionless
+TS imports resolve). `npm test` runs only the test suites.
+
+| File | Scope |
+|------|-------|
+| `tests/status.smoke.ts` | Footer widget layout, width math, tier building, config coercion |
+| `tests/identity.test.ts` | Co-install invariant: namespaced + unique + disjoint from the official provider's reserved names |
+| `tests/prism.test.ts` | Prism header/label sanitization and persisted-entry validation |
+| `tests/notify.test.ts` | Warning dedupe, UI routing, stale-ctx stderr fallback |
+| `tests/provider.integration.test.ts` | Real pi runtime (DefaultResourceLoader + createAgentSession + ExtensionRunner): embedded catalog, catalog hot-swap/cache/retention, deprecated grace window, warning surfacing, prism entry durability, and co-installation against `tests/fixtures/official-surface.ts` |
+
+The integration suite stubs `globalThis.fetch` and emits the session lifecycle
+events the pi CLI emits (`session_start`, `turn_start`, `after_provider_response`,
+`message_end`, `turn_end`). It must be run with jiti; `--import jiti/register`
+is already wired into `npm test`.
+

package/identity.ts

@@ -0,0 +1,49 @@
+/**
+ * Single source of truth for every identifier this extension registers into
+ * shared Pi surfaces.
+ *
+ * Co-installation with the official `@charmland/pi-hyper-provider` is a hard
+ * requirement, so no identifier we register may be a bare shared name. Every
+ * key derives from PROVIDER_ID: provider id, custom api name, status and widget
+ * keys, command name, prism entry type, auth key and env var, and the on-disk
+ * config/cache file names. tests/identity.test.ts and
+ * tests/provider.integration.test.ts enforce the invariant (namespacing,
+ * uniqueness, and disjointness from the official provider's reserved names).
+ */
+export const PROVIDER_ID = "hypercharm";
+export const PROVIDER_DISPLAY_NAME = "HyperCharm";
+
+/** Custom api name: keeps our streamSimple handler distinct from pi's built-in openai-completions pipeline. */
+export const API_NAME = PROVIDER_ID;
+
+export const API_KEY_ENV = "HYPERCHARM_API_KEY";
+export const API_KEY_PLACEHOLDER = `$${API_KEY_ENV}`;
+
+export const STATUS_COMMAND = `${PROVIDER_ID}-status`;
+export const STATUS_KEY_SESSION = `${PROVIDER_ID}-session`;
+export const STATUS_KEY_ACCOUNT = `${PROVIDER_ID}-account`;
+export const WIDGET_KEY = PROVIDER_ID;
+export const PRISM_ENTRY_TYPE = `${PROVIDER_ID}-prism-route`;
+
+export const CONFIG_FILE_NAME = `${PROVIDER_ID}.json`;
+export const CACHE_FILE_NAME = `${PROVIDER_ID}-models.json`;
+
+/**
+ * Every distinct namespaced identifier this extension registers or writes.
+ * API_NAME and WIDGET_KEY alias PROVIDER_ID by design — pi keys the custom api
+ * handler and the below-editor widget by provider id — so the set is deduped;
+ * what matters is that no *value* is shared with another extension.
+ */
+export const IDENTIFIERS: readonly string[] = Object.freeze([
+	...new Set([
+		PROVIDER_ID,
+		API_KEY_ENV,
+		API_KEY_PLACEHOLDER,
+		STATUS_COMMAND,
+		STATUS_KEY_SESSION,
+		STATUS_KEY_ACCOUNT,
+		PRISM_ENTRY_TYPE,
+		CONFIG_FILE_NAME,
+		CACHE_FILE_NAME,
+	]),
+]);

package/index.ts

@@ -103,7 +103,23 @@
 
 import { clampThinkingLevel, streamOpenAICompletions } from "@earendil-works/pi-ai/compat";
 import type { AssistantMessageEventStream, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import { Text } from "@earendil-works/pi-tui";
 import { USER_AGENT, loginHypercharm, refreshHypercharmToken } from "./oauth";
+import {
+	API_KEY_PLACEHOLDER,
+	API_NAME,
+	CACHE_FILE_NAME,
+	CONFIG_FILE_NAME,
+	PRISM_ENTRY_TYPE,
+	PROVIDER_DISPLAY_NAME,
+	PROVIDER_ID,
+	STATUS_COMMAND,
+	STATUS_KEY_ACCOUNT,
+	STATUS_KEY_SESSION,
+	WIDGET_KEY,
+} from "./identity";
+import { createNotifier } from "./notify";
+import { prismRouteFromHeaders, prismRouteLabel, readPrismRoute, type PrismRoute } from "./prism";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext, type ModelRegistry } from "@earendil-works/pi-coding-agent";
 import modelsData from "./models.json" with { type: "json" };
 import customModelsData from "./custom-models.json" with { type: "json" };
@@ -132,6 +148,18 @@ import path from "path";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
+// Warning sink for fetch/parse failures: deduplicated, routed to the session UI
+// once one is active, stderr before that. Warnings must never throw.
+const notifier = createNotifier();
+
+function describeError(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+function warnAccountFetch(label: string, reason: string): void {
+	notifier.warn(`Unable to refresh HyperCharm ${label}: ${reason}.`);
+}
+
 interface JsonModel {
 	id: string;
 	name: string;
@@ -248,11 +276,10 @@ function buildModels(base: JsonModel[], custom: JsonModel[], patch: PatchData):
 
 // ─── Stale-While-Revalidate Model Sync ────────────────────────────────────────
 
-const PROVIDER_ID = "hypercharm";
 const BASE_URL = "https://hyper.charm.land/v1";
 const MODELS_URL = `${BASE_URL}/provider`;
 const CACHE_DIR = path.join(getAgentDir(), "cache");
-const CACHE_PATH = path.join(CACHE_DIR, `${PROVIDER_ID}-models.json`);
+const CACHE_PATH = path.join(CACHE_DIR, CACHE_FILE_NAME);
 const LIVE_FETCH_TIMEOUT_MS = 8000;
 
 const PI_THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -322,12 +349,22 @@ async function fetchLiveModels(apiKey: string, signal?: AbortSignal): Promise<Js
 			headers: { Authorization: `Bearer ${apiKey}`, "User-Agent": USER_AGENT },
 			signal: signal ? AbortSignal.any([AbortSignal.timeout(LIVE_FETCH_TIMEOUT_MS), signal]) : AbortSignal.timeout(LIVE_FETCH_TIMEOUT_MS),
 		});
-		if (!response.ok) return null;
+		if (!response.ok) {
+			notifier.warn(`HyperCharm model catalog refresh failed: HTTP ${response.status} — serving cached/embedded models.`);
+			return null;
+		}
 		const data = await response.json();
 		const apiModels = Array.isArray(data) ? data : (data.models || data.data || []);
-		if (!Array.isArray(apiModels) || apiModels.length === 0) return null;
+		if (!Array.isArray(apiModels) || apiModels.length === 0) {
+			notifier.warn("HyperCharm model catalog refresh returned no usable models — serving cached/embedded models.");
+			return null;
+		}
 		return apiModels.map(transformApiModel).filter((m): m is JsonModel => m !== null);
-	} catch {
+	} catch (err) {
+		// An aborted signal means the session was replaced, not that Hyper failed.
+		if (!signal?.aborted) {
+			notifier.warn(`HyperCharm model catalog refresh failed: ${describeError(err)} — serving cached/embedded models.`);
+		}
 		return null;
 	}
 }
@@ -336,7 +373,10 @@ function loadCachedModels(): JsonModel[] | null {
 	try {
 		const data = JSON.parse(fs.readFileSync(CACHE_PATH, "utf8"));
 		return Array.isArray(data) ? data : null;
-	} catch {
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+			notifier.warn(`Ignoring unreadable HyperCharm model cache at ${CACHE_PATH}: ${describeError(err)}.`);
+		}
 		return null;
 	}
 }
@@ -345,8 +385,9 @@ function cacheModels(models: JsonModel[]): void {
 	try {
 		fs.mkdirSync(CACHE_DIR, { recursive: true });
 		fs.writeFileSync(CACHE_PATH, JSON.stringify(models, null, 2) + "\n");
-	} catch {
-		// Cache write failure is non-fatal
+	} catch (err) {
+		// Non-fatal: the freshly fetched catalog still serves this session.
+		notifier.warn(`Could not write the HyperCharm model cache to ${CACHE_PATH}: ${describeError(err)}.`);
 	}
 }
 
@@ -451,8 +492,11 @@ function loadStatusConfig(): StatusConfig {
 	try {
 		const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
 		statusConfig = coerceStatusConfig(raw);
-	} catch {
-		// Missing or unreadable file → defaults
+	} catch (err) {
+		// A missing file is normal; anything else is worth surfacing once.
+		if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+			notifier.warn(`Ignoring unreadable HyperCharm status config at ${CONFIG_PATH}: ${describeError(err)} — using defaults.`);
+		}
 	}
 	return statusConfig;
 }
@@ -473,8 +517,9 @@ function writeStatusConfig(): void {
 		raw.glyphs = statusConfig.glyphs;
 		fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
 		fs.writeFileSync(CONFIG_PATH, JSON.stringify(raw, null, 2) + "\n");
-	} catch {
-		// Config write failure is non-fatal — the in-memory config still applies
+	} catch (err) {
+		// Non-fatal: the in-memory config still applies to this session.
+		notifier.warn(`Could not save the HyperCharm status config to ${CONFIG_PATH}: ${describeError(err)}.`);
 	}
 }
 
@@ -650,7 +695,7 @@ let lastCreditsFetchAt = 0;
 let creditsInFlight: Promise<void> | null = null;
 let metaFetched = false;
 
-async function fetchJsonGet(url: string, apiKey: string, signal?: AbortSignal): Promise<any | null> {
+async function fetchJsonGet(url: string, apiKey: string, signal: AbortSignal | undefined, label: string): Promise<any | null> {
 	try {
 		const response = await fetch(url, {
 			headers: { Authorization: `Bearer ${apiKey}`, "User-Agent": USER_AGENT },
@@ -658,9 +703,14 @@ async function fetchJsonGet(url: string, apiKey: string, signal?: AbortSignal):
 				? AbortSignal.any([AbortSignal.timeout(ACCOUNT_FETCH_TIMEOUT_MS), signal])
 				: AbortSignal.timeout(ACCOUNT_FETCH_TIMEOUT_MS),
 		});
-		if (!response.ok) return null;
+		if (!response.ok) {
+			warnAccountFetch(label, `HTTP ${response.status}`);
+			return null;
+		}
 		return await response.json();
-	} catch {
+	} catch (err) {
+		// An abort means the session was replaced or shut down, not a failure.
+		if (!signal?.aborted) warnAccountFetch(label, describeError(err));
 		return null;
 	}
 }
@@ -673,7 +723,7 @@ function refreshCredits(apiKey: string | undefined, signal: AbortSignal | undefi
 	if (creditsInFlight) return creditsInFlight;
 	creditsInFlight = (async () => {
 		try {
-			const data = await fetchJsonGet(`${BASE_URL}/credits`, apiKey, signal);
+			const data = await fetchJsonGet(`${BASE_URL}/credits`, apiKey, signal, "Hypercredit balance");
 			if (data === null) return;
 			// /credits can report hypercredits ("balance") or USD ("balance_usd",
 			// USD-billed accounts). Handle both at the observed 20 hc = $1 rate so a
@@ -693,8 +743,8 @@ function refreshCredits(apiKey: string | undefined, signal: AbortSignal | undefi
 async function refreshAccountMeta(apiKey: string | undefined, signal?: AbortSignal): Promise<void> {
 	if (!apiKey || metaFetched) return;
 	const [teams, devices] = await Promise.all([
-		fetchJsonGet(`${BASE_URL}/teams`, apiKey, signal),
-		fetchJsonGet(`${BASE_URL}/devices`, apiKey, signal),
+		fetchJsonGet(`${BASE_URL}/teams`, apiKey, signal, "team metadata"),
+		fetchJsonGet(`${BASE_URL}/devices`, apiKey, signal, "device sessions"),
 	]);
 	if (signal?.aborted) return;
 
@@ -719,10 +769,6 @@ async function refreshAccountMeta(apiKey: string | undefined, signal?: AbortSign
 
 // ─── Status Rendering ─────────────────────────────────────────────────────────
 
-const WIDGET_KEY = "hypercharm";
-const STATUS_KEY_SESSION = "hypercharm-session";
-const STATUS_KEY_ACCOUNT = "hypercharm-account";
-
 function currentProviderId(ctx: ExtensionContext): string | undefined {
 	// ctx.model is a getter that can throw on stale contexts
 	try {
@@ -1055,15 +1101,15 @@ let currentModels: JsonModel[] = [];
 function makeProviderConfig(models: JsonModel[] = currentModels) {
 	return {
 		baseUrl: BASE_URL,
-		apiKey: "$HYPERCHARM_API_KEY",
+		apiKey: API_KEY_PLACEHOLDER,
 		// Custom API name so our streamSimple registers as its own handler and
 		// never shadows pi's built-in openai-completions pipeline for other
 		// providers. streamHypercharm delegates to pi-ai's OpenAI-compat streamer.
-		api: "hypercharm",
+		api: API_NAME,
 		models,
 		streamSimple: streamHypercharm,
 		oauth: {
-			name: "HyperCharm",
+			name: PROVIDER_DISPLAY_NAME,
 			login: (callbacks) => loginHypercharm(callbacks),
 			refreshToken: (credentials, signal) => refreshHypercharmToken(credentials, signal),
 			getApiKey: (credentials) => String(credentials.access ?? ""),
@@ -1076,13 +1122,17 @@ export default function (pi: ExtensionAPI) {
 	const customModels = customModelsData as JsonModel[];
 	const patches = patchData as PatchData;
 
+	// Prism routing state: collected per assistant request, committed at turn_end.
+	let collectingPrismRoute = false;
+	let prismRoute: PrismRoute | undefined;
+
 	const staleBase = loadStaleModels(embeddedModels);
 	const staleModels = buildModels(staleBase, customModels, patches);
 	currentModels = staleModels;
 
 	pi.registerProvider(PROVIDER_ID, makeProviderConfig(staleModels));
 
-	pi.registerCommand("hypercharm-status", {
+	pi.registerCommand(STATUS_COMMAND, {
 		description: "Configure the HyperCharm footer status (session spend, balance, rate limits)",
 		handler: async (args, ctx) => {
 			await handleStatusCommand(args, ctx);
@@ -1090,6 +1140,7 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		notifier.activate(ctx);
 		const epoch = ++statusEpoch;
 		revalidateAbort?.abort();
 		revalidateAbort = new AbortController();
@@ -1105,7 +1156,14 @@ export default function (pi: ExtensionAPI) {
 		// over anything that touched provider registration during load.
 		pi.registerProvider(PROVIDER_ID, makeProviderConfig());
 
-		resolveApiKey(ctx.modelRegistry).then(() => {
+		// A failure here used to vanish: no key resolved meant no refresh and no
+		// diagnostics. Surface it, then continue — without a key we serve the
+		// embedded/cached catalog.
+		resolveApiKey(ctx.modelRegistry)
+			.catch((err) => {
+				notifier.warn(`Unable to resolve HyperCharm credentials: ${describeError(err)} — serving cached/embedded models.`);
+			})
+			.then(() => {
 			// A session replacement while the key resolved invalidated the
 			// captured ctx (fast-resume, /new, /fork); nothing below may touch it.
 			if (epoch !== statusEpoch) return;
@@ -1165,4 +1223,42 @@ export default function (pi: ExtensionAPI) {
 		ctx.ui.setStatus(STATUS_KEY_ACCOUNT, undefined);
 		ctx.ui.setWidget(WIDGET_KEY, undefined);
 	});
+
+	// Prism routing: Hyper's edge reports which upstream model actually served the
+	// assistant request via response headers. Collection is scoped to that request
+	// so auxiliary calls between turns cannot leak a route into the transcript,
+	// and the route lands at turn_end as a durable session entry — never a
+	// notification — so it survives reopening the session.
+	pi.registerEntryRenderer(PRISM_ENTRY_TYPE, (entry, _options, theme) => {
+		const route = readPrismRoute(entry.data);
+		const label = route ? prismRouteLabel(route) : undefined;
+		if (label === undefined) return undefined;
+		return new Text(`${theme.fg("muted", "Prism")} ${theme.fg("dim", "→")} ${theme.fg("muted", label)}`, 0, 0);
+	});
+
+	pi.on("turn_start", () => {
+		collectingPrismRoute = true;
+		prismRoute = undefined;
+	});
+
+	pi.on("after_provider_response", (event) => {
+		if (!collectingPrismRoute) return;
+		prismRoute = prismRouteFromHeaders(event.headers);
+	});
+
+	pi.on("message_end", (event) => {
+		if (event.message.role === "assistant") collectingPrismRoute = false;
+	});
+
+	pi.on("turn_end", (event) => {
+		const route = prismRoute;
+		prismRoute = undefined;
+		collectingPrismRoute = false;
+		if (route === undefined) return;
+		if (event.message.role !== "assistant") return;
+		if (event.message.provider !== PROVIDER_ID) return;
+		if (event.message.stopReason === "error" || event.message.stopReason === "aborted") return;
+		pi.appendEntry(PRISM_ENTRY_TYPE, route);
+	});
+
 }

package/notify.ts

@@ -0,0 +1,50 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type WarningSink = (message: string) => void;
+
+export interface Notifier {
+	/** Emit a deduplicated warning through the currently available output. */
+	warn: WarningSink;
+	/** Route future warnings through this session's UI (no-op without a UI). */
+	activate(ctx: ExtensionContext): void;
+}
+
+/**
+ * Fetch and parse failures must never be silent, and must never spam: warnings
+ * are deduplicated by message for the life of the process. Until a UI session
+ * activates the notifier they go to stderr (visible in print/json modes); after
+ * activation they go through ctx.ui.notify. A stale ctx — a refresh landing
+ * after its session was replaced — falls back to stderr instead of throwing.
+ */
+export function createNotifier(): Notifier {
+	const seenWarnings = new Set<string>();
+	const toStderr: WarningSink = (message) => {
+		process.stderr.write(`HyperCharm warning: ${message}\n`);
+	};
+	let emit: WarningSink = toStderr;
+
+	return {
+		warn(message) {
+			if (seenWarnings.has(message)) return;
+			seenWarnings.add(message);
+			emit(message);
+		},
+
+		activate(ctx) {
+			let hasUI = false;
+			try {
+				hasUI = ctx.hasUI;
+			} catch {
+				return;
+			}
+			if (!hasUI) return;
+			emit = (message) => {
+				try {
+					ctx.ui.notify(message, "warning");
+				} catch {
+					toStderr(message);
+				}
+			};
+		},
+	};
+}

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "pi-hypercharm-provider",
-  "version": "1.3.27",
+  "version": "1.3.28",
   "description": "HyperCharm provider extension for pi - Access DeepSeek, GLM, Kimi, Qwen, MiniMax, Gemma, and GPT-OSS models through the Charm Hyper API",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "tsc --noEmit && npm run smoke && npm test",
+    "smoke": "node tests/status.smoke.ts",
+    "test": "node --import jiti/register --test tests/identity.test.ts tests/prism.test.ts tests/notify.test.ts tests/provider.integration.test.ts",
+    "update-models": "node scripts/update-models.js"
+  },
   "keywords": [
     "pi",
     "extension",
@@ -21,10 +29,15 @@
     "gemma",
     "gpt-oss"
   ],
+  "peerDependencies": {
+    "@earendil-works/pi-tui": "*"
+  },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.85.1",
     "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "^24.10.1",
+    "jiti": "2.7.0",
     "typescript": "6.0.3"
   },
   "author": "",
@@ -33,12 +46,5 @@
     "extensions": [
       "./index.ts"
     ]
-  },
-  "scripts": {
-    "clean": "echo 'nothing to clean'",
-    "build": "echo 'nothing to build'",
-    "check": "tsc --noEmit && node tests/status.smoke.ts",
-    "smoke": "node tests/status.smoke.ts",
-    "update-models": "node scripts/update-models.js"
   }
-}
+}

package/prism.ts

@@ -0,0 +1,43 @@
+import { PRISM_ENTRY_TYPE } from "./identity";
+
+export { PRISM_ENTRY_TYPE };
+
+/** Longest routing label we accept (mirrors the official provider's limit). */
+const MAX_LABEL_LENGTH = 200;
+/** Control, format, line-separator, and paragraph-separator characters. */
+const UNSAFE_LABEL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+
+export interface PrismRoute {
+	modelName?: string;
+	modelId?: string;
+}
+
+/** Trimmed, length- and character-checked routing label; undefined when unusable. */
+export function prismLabel(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const label = value.trim();
+	if (label === "" || label.length > MAX_LABEL_LENGTH || UNSAFE_LABEL.test(label)) return undefined;
+	return label;
+}
+
+/** Route captured from a provider response; undefined when neither header is usable. */
+export function prismRouteFromHeaders(headers: Record<string, string> | undefined): PrismRoute | undefined {
+	if (!headers) return undefined;
+	const modelName = prismLabel(headers["x-prism-model-name"]);
+	const modelId = prismLabel(headers["x-prism-model-id"]);
+	return modelName !== undefined || modelId !== undefined ? { modelName, modelId } : undefined;
+}
+
+/** Re-validate persisted entry data: session files are user-editable input. */
+export function readPrismRoute(data: unknown): PrismRoute | undefined {
+	if (typeof data !== "object" || data === null) return undefined;
+	const record = data as Record<string, unknown>;
+	const modelName = prismLabel(record.modelName);
+	const modelId = prismLabel(record.modelId);
+	return modelName !== undefined || modelId !== undefined ? { modelName, modelId } : undefined;
+}
+
+/** What to show for a route: the human name when present, else the model id. */
+export function prismRouteLabel(route: PrismRoute): string | undefined {
+	return route.modelName ?? route.modelId;
+}

package/tests/fixtures/official-surface.ts

@@ -0,0 +1,42 @@
+/**
+ * Stand-in for the official @charmland/pi-hyper-provider@0.4.0 registration
+ * surface, used by tests/provider.integration.test.ts to prove both extensions
+ * can be installed at once.
+ *
+ * It deliberately registers under the OFFICIAL identifiers — provider id
+ * "hyper", status key "hyper", /hyper-status command, hyper-prism-route entry
+ * renderer, HYPER_API_KEY — and publishes a model with an id we also serve
+ * ("glm-5.3"), so the test asserts provider-scoped model resolution instead of
+ * accidental global-key behaviour.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function officialSurfaceFixture(pi: ExtensionAPI) {
+	pi.registerProvider("hyper", {
+		baseUrl: "https://hyper.charm.land/v1",
+		apiKey: "$HYPER_API_KEY",
+		api: "openai-completions",
+		models: [
+			{
+				id: "glm-5.3",
+				name: "Official fixture GLM 5.3",
+				reasoning: false,
+				input: ["text"],
+				cost: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 4096,
+				maxTokens: 512,
+			},
+		],
+	});
+
+	pi.registerEntryRenderer("hyper-prism-route", () => undefined);
+
+	pi.registerCommand("hyper-status", {
+		description: "Configure the Charm Hyper footer status",
+		handler: async () => {},
+	});
+
+	pi.on("turn_end", (_event, ctx) => {
+		ctx.ui.setStatus("hyper", "Hyper fixture status");
+	});
+}

package/tests/identity.test.ts

@@ -0,0 +1,76 @@
+/**
+ * First-principles co-installation guard: every identifier this extension
+ * registers into a shared Pi surface must be namespaced under PROVIDER_ID and
+ * disjoint from the official provider's reserved names.
+ *
+ * OFFICIAL_RESERVED mirrors @charmland/pi-hyper-provider@0.4.0's registration
+ * surface (src/hyper.ts, src/index.ts, src/settings.ts, src/credits.ts). Keep
+ * it in sync when the official package adds or renames a shared identifier: a
+ * failure here means the two extensions could collide on that surface.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	API_KEY_ENV,
+	API_NAME,
+	IDENTIFIERS,
+	PRISM_ENTRY_TYPE,
+	PROVIDER_ID,
+	STATUS_COMMAND,
+	STATUS_KEY_ACCOUNT,
+	STATUS_KEY_SESSION,
+	WIDGET_KEY,
+} from "../identity.ts";
+
+const OFFICIAL_RESERVED = [
+	"hyper", // provider id and status key (PROVIDER_NAME)
+	"Charm Hyper", // provider + oauth display name
+	"hyper-status", // /hyper-status command
+	"hyper-prism-route", // prism entry customType
+	"hyper-provider", // ~/.pi/agent/hyper-provider settings dir
+	"HYPER_API_KEY", // envApiKeyAuth env var (auth key)
+	"openai-completions", // api name (openAICompletionsApi)
+	"@charmland/pi-hyper-provider", // npm package name
+];
+
+test("every registered identifier is namespaced under the provider id", () => {
+	for (const identifier of IDENTIFIERS) {
+		assert.equal(typeof identifier, "string");
+		assert.ok(identifier.length > 0);
+		// Normalize the two conventions we use: env vars are upper-cased
+		// (HYPERCHARM_API_KEY) and pi's env-var placeholders carry a "$" sigil.
+		const normalized = identifier.replace(/^\$/, "").toLowerCase();
+		assert.ok(normalized.startsWith(PROVIDER_ID), identifier + " must start with " + PROVIDER_ID);
+	}
+});
+
+test("identifiers are unique", () => {
+	assert.equal(new Set(IDENTIFIERS).size, IDENTIFIERS.length);
+});
+
+test("no identifier collides with the official provider's reserved names", () => {
+	for (const identifier of IDENTIFIERS) {
+		assert.ok(!OFFICIAL_RESERVED.includes(identifier), identifier + " collides with the official provider");
+	}
+});
+
+test("the specific shared surfaces differ from the official registration", () => {
+	assert.equal(PROVIDER_ID, "hypercharm");
+	assert.notEqual(PROVIDER_ID, "hyper");
+	assert.notEqual(API_NAME, "openai-completions");
+	assert.notEqual(API_KEY_ENV, "HYPER_API_KEY");
+	assert.notEqual(STATUS_COMMAND, "hyper-status");
+	assert.notEqual(PRISM_ENTRY_TYPE, "hyper-prism-route");
+	assert.notEqual(STATUS_KEY_SESSION, "hyper");
+	assert.notEqual(STATUS_KEY_ACCOUNT, "hyper");
+	assert.notEqual(WIDGET_KEY, "hyper");
+});
+
+test("status and widget keys stay disjoint so pi cannot cross-clear them", () => {
+	assert.ok(WIDGET_KEY.startsWith(PROVIDER_ID));
+	assert.ok(STATUS_KEY_SESSION.startsWith(PROVIDER_ID + "-"));
+	assert.ok(STATUS_KEY_ACCOUNT.startsWith(PROVIDER_ID + "-"));
+	assert.notEqual(STATUS_KEY_SESSION, STATUS_KEY_ACCOUNT);
+	assert.notEqual(STATUS_KEY_SESSION, WIDGET_KEY);
+	assert.notEqual(STATUS_KEY_ACCOUNT, WIDGET_KEY);
+});