@victor-software-house/pi-openai-proxy 2.0.0 → 3.0.0

package/README.md

@@ -5,10 +5,10 @@ A local OpenAI-compatible HTTP proxy built on [pi](https://github.com/badlogic/p
 ## Why
 
 - **Single gateway** to 20+ LLM providers (Anthropic, OpenAI, Google, Bedrock, Mistral, xAI, Groq, OpenRouter, Vertex, etc.) via one OpenAI-compatible API
-- **No duplicate config** -- reuses pi's `~/.pi/agent/auth.json` and `models.json` for credentials and model definitions
-- **Self-hosted** -- runs locally, no third-party proxy services
-- **Streaming** -- full SSE streaming with token usage and cost tracking
-- **Strict validation** -- unsupported parameters are rejected clearly, not silently ignored
+- **No duplicate config** — reuses pi's `~/.pi/agent/auth.json` and `models.json` for credentials and model definitions
+- **Self-hosted** — runs locally, no third-party proxy services
+- **Streaming** — full SSE streaming with token usage and cost tracking
+- **Strict validation** — unsupported parameters are rejected clearly, not silently ignored
 
 ## Prerequisites
 
@@ -81,8 +81,8 @@ OPENAI_API_BASE=http://localhost:4141/v1 aider --model anthropic/claude-sonnet-4
 
 The proxy resolves model references in this order:
 
-1. **Exact public ID match** -- the ID from `GET /v1/models`
-2. **Canonical ID fallback** -- `provider/model-id` format (only for exposed models)
+1. **Exact public ID match** — the ID from `GET /v1/models`
+2. **Canonical ID fallback** — `provider/model-id` format (only for exposed models)
 
 With the default `collision-prefixed` mode and no collisions, model IDs are exposed without prefixes:
 
@@ -109,7 +109,7 @@ curl http://localhost:4141/v1/chat/completions \
 | `messages` (base64 images) | Base64 data URI image content parts (`image/png`, `image/jpeg`, `image/gif`, `image/webp`) |
 | `stream` | SSE with `text_delta` and `toolcall_delta` mapping |
 | `temperature` | Direct passthrough |
-| `max_tokens` / `max_completion_tokens` | Normalized to `maxTokens` |
+| `max_completion_tokens` | Preferred; `max_tokens` accepted as deprecated fallback |
 | `stop` | Via passthrough |
 | `user` | Via passthrough |
 | `stream_options.include_usage` | Final usage chunk in SSE stream |
@@ -284,29 +284,33 @@ The extension detects externally running instances and shows their status via `/
 
 ## Architecture
 
-```
-HTTP Client                       pi-openai-proxy
-(curl, Aider, Continue,      +--------------------------+
- LiteLLM, Open WebUI, etc.)  |                          |
-         |                    |  Hono HTTP Server         |
-         |  POST /v1/chat/   |  +-- Request parser       |
-         +--completions------>|  +-- Message converter    |
-         |                    |  +-- Model resolver       |
-         |  GET /v1/models    |  +-- Tool converter       |
-         +------------------>|  +-- SSE encoder          |
-         |                    |                          |
-         |                    |  Pi SDK                   |
-         |  SSE / JSON        |  +-- ModelRegistry        |
-         |<------------------+  +-- AuthStorage          |
-                              |  +-- streamSimple()       |
-                              |  +-- completeSimple()     |
-                              +--------------------------+
+```text
+┌─────────────────────────────┐         ┌──────────────────────────────────┐
+│       HTTP Client           │         │        pi-openai-proxy           │
+│  (curl, Aider, Continue,    │         │                                  │
+│   LiteLLM, Open WebUI, etc.)│         │  ┌────────────────────────────┐  │
+└─────────────┬───────────────┘         │  │     Hono HTTP Server       │  │
+              │                         │  │  ├─ Request parser         │  │
+              │  POST /v1/chat/         │  │  ├─ Message converter      │  │
+              │  completions            │  │  ├─ Model resolver         │  │
+              ├────────────────────────►│  │  ├─ Tool converter         │  │
+              │                         │  │  └─ SSE encoder            │  │
+              │  GET /v1/models         │  └────────────────────────────┘  │
+              ├────────────────────────►│                                  │
+              │                         │  ┌────────────────────────────┐  │
+              │                         │  │        Pi SDK              │  │
+              │  SSE / JSON             │  │  ├─ ModelRegistry          │  │
+              │◄────────────────────────┤  │  ├─ AuthStorage            │  │
+              │                         │  │  ├─ streamSimple()         │  │
+                                        │  │  └─ completeSimple()       │  │
+                                        │  └────────────────────────────┘  │
+                                        └──────────────────────────────────┘
 ```
 
 ### Pi SDK layers used
 
-- **`@mariozechner/pi-ai`** -- `streamSimple()`, `completeSimple()`, `Model`, `Usage`, `AssistantMessageEvent`
-- **`@mariozechner/pi-coding-agent`** -- `ModelRegistry`, `AuthStorage`
+- **`@mariozechner/pi-ai`** — `streamSimple()`, `completeSimple()`, `Model`, `Usage`, `AssistantMessageEvent`
+- **`@mariozechner/pi-coding-agent`** — `ModelRegistry`, `AuthStorage`
 
 ## Security defaults
 
@@ -330,14 +334,14 @@ bun test              # Run all tests
 
 ### Tooling
 
-- **Bun** -- runtime, test runner, package manager
-- **tsdown** -- npm build (ESM + .d.ts)
-- **Biome** -- format + lint
-- **oxlint** -- type-aware lint with strict rules (`.oxlintrc.json`)
-- **lefthook** -- pre-commit hooks (format, lint, typecheck), pre-push hooks (test)
-- **commitlint** -- conventional commits
-- **semantic-release** -- automated versioning and npm publish
-- **mise** -- tool version management (node, bun)
+- **Bun** — runtime, test runner, package manager
+- **tsdown** — npm build (ESM + .d.ts)
+- **Biome** — format + lint
+- **oxlint** — type-aware lint with strict rules (`.oxlintrc.json`)
+- **lefthook** — pre-commit hooks (format, lint, typecheck), pre-push hooks (test)
+- **commitlint** — conventional commits
+- **semantic-release** — automated versioning and npm publish
+- **mise** — tool version management (node, bun)
 
 ## License
 

package/dist/config.mjs

@@ -18,7 +18,7 @@ const DEFAULT_CONFIG = {
 	upstreamTimeoutSec: 120,
 	lifetime: "detached",
 	publicModelIdMode: "collision-prefixed",
-	modelExposureMode: "all",
+	modelExposureMode: "scoped",
 	scopedProviders: [],
 	customModels: [],
 	providerPrefixes: {}

package/dist/exposure.d.mts

@@ -0,0 +1,56 @@
+
+import { ModelExposureMode, PublicModelIdMode } from "./config.mjs";
+import { Api, Model } from "@mariozechner/pi-ai";
+
+//#region src/openai/model-exposure.d.ts
+interface ExposedModel {
+  /** The public ID exposed on the HTTP API. */
+  readonly publicId: string;
+  /** The canonical internal ID: "provider/model-id". */
+  readonly canonicalId: string;
+  /** The underlying pi model. */
+  readonly model: Model<Api>;
+  /** The provider key. */
+  readonly provider: string;
+}
+interface ModelExposureConfig {
+  readonly publicModelIdMode: PublicModelIdMode;
+  readonly modelExposureMode: ModelExposureMode;
+  readonly scopedProviders: readonly string[];
+  readonly customModels: readonly string[];
+  readonly providerPrefixes: Readonly<Record<string, string>>;
+}
+interface ModelExposureResult {
+  readonly ok: true;
+  /** All exposed models with public IDs. */
+  readonly models: readonly ExposedModel[];
+  /** Public ID -> ExposedModel for O(1) lookup. */
+  readonly byPublicId: ReadonlyMap<string, ExposedModel>;
+  /** Canonical ID -> ExposedModel for backward-compat fallback. */
+  readonly byCanonicalId: ReadonlyMap<string, ExposedModel>;
+}
+interface ModelExposureError {
+  readonly ok: false;
+  readonly message: string;
+}
+type ModelExposureOutcome = ModelExposureResult | ModelExposureError;
+/**
+ * Compute the full model-exposure result from config and available models.
+ *
+ * @param available - Models with auth configured (pi's getAvailable())
+ * @param allRegistered - All registered models regardless of auth (pi's getAll())
+ * @param config - Model exposure configuration
+ *
+ * Call this at startup and whenever config or the model registry changes.
+ */
+declare function computeModelExposure(available: readonly Model<Api>[], allRegistered: readonly Model<Api>[], config: ModelExposureConfig): ModelExposureOutcome;
+/**
+ * Resolve a model ID from an incoming request against the exposure result.
+ *
+ * Resolution order:
+ *   1. Exact public ID match
+ *   2. Exact canonical ID match (backward compat, only if model is exposed)
+ */
+declare function resolveExposedModel(exposure: ModelExposureResult, requestModelId: string): ExposedModel | undefined;
+//#endregion
+export { ExposedModel, ModelExposureConfig, ModelExposureError, ModelExposureOutcome, ModelExposureResult, computeModelExposure, resolveExposedModel };

package/dist/exposure.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env bun
+//#region src/openai/model-exposure.ts
+function filterExposedModels(available, allRegistered, config) {
+	switch (config.modelExposureMode) {
+		case "scoped": return [...available];
+		case "all": return [...allRegistered];
+		case "custom": {
+			const allowed = new Set(config.customModels);
+			return available.filter((m) => allowed.has(`${m.provider}/${m.id}`));
+		}
+	}
+}
+/**
+* Get the public prefix label for a provider.
+* Uses the configured override if present, otherwise the provider key itself.
+*/
+function getPublicPrefix(provider, prefixes) {
+	const override = prefixes[provider];
+	return override !== void 0 && override.length > 0 ? override : provider;
+}
+/**
+* Find connected conflict groups: sets of providers that share at least one raw model ID.
+*
+* If provider A and B share a model ID, and B and C share a different model ID,
+* then {A, B, C} form one connected conflict group.
+*/
+function findConflictGroups(models) {
+	const modelToProviders = /* @__PURE__ */ new Map();
+	for (const m of models) {
+		const existing = modelToProviders.get(m.id);
+		if (existing !== void 0) existing.add(m.provider);
+		else modelToProviders.set(m.id, new Set([m.provider]));
+	}
+	const parent = /* @__PURE__ */ new Map();
+	function find(x) {
+		let root = x;
+		while (parent.get(root) !== root) {
+			const p = parent.get(root);
+			if (p === void 0) break;
+			root = p;
+		}
+		let current = x;
+		while (current !== root) {
+			const next = parent.get(current);
+			if (next === void 0) break;
+			parent.set(current, root);
+			current = next;
+		}
+		return root;
+	}
+	function union(a, b) {
+		const ra = find(a);
+		const rb = find(b);
+		if (ra !== rb) parent.set(ra, rb);
+	}
+	for (const m of models) if (!parent.has(m.provider)) parent.set(m.provider, m.provider);
+	for (const providers of modelToProviders.values()) {
+		if (providers.size <= 1) continue;
+		const arr = [...providers];
+		const first = arr[0];
+		if (first === void 0) continue;
+		for (let i = 1; i < arr.length; i++) {
+			const other = arr[i];
+			if (other !== void 0) union(first, other);
+		}
+	}
+	const groupsByRoot = /* @__PURE__ */ new Map();
+	for (const provider of parent.keys()) {
+		const root = find(provider);
+		const existing = groupsByRoot.get(root);
+		if (existing !== void 0) existing.add(provider);
+		else groupsByRoot.set(root, new Set([provider]));
+	}
+	return [...groupsByRoot.values()].filter((g) => g.size > 1);
+}
+function generateCollisionPrefixedIds(models, prefixes) {
+	const conflictGroups = findConflictGroups(models);
+	const prefixedProviders = /* @__PURE__ */ new Set();
+	for (const group of conflictGroups) for (const provider of group) prefixedProviders.add(provider);
+	const result = /* @__PURE__ */ new Map();
+	for (const m of models) if (prefixedProviders.has(m.provider)) {
+		const prefix = getPublicPrefix(m.provider, prefixes);
+		result.set(m, `${prefix}/${m.id}`);
+	} else result.set(m, m.id);
+	return result;
+}
+function generateUniversalIds(models) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const m of models) {
+		const existing = seen.get(m.id);
+		if (existing !== void 0) return `Universal mode conflict: model ID '${m.id}' is provided by both '${existing}' and '${m.provider}'. Use 'collision-prefixed' or 'always-prefixed' mode, or reduce the exposed model set.`;
+		seen.set(m.id, m.provider);
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (const m of models) result.set(m, m.id);
+	return result;
+}
+function generateAlwaysPrefixedIds(models, prefixes) {
+	const result = /* @__PURE__ */ new Map();
+	for (const m of models) {
+		const prefix = getPublicPrefix(m.provider, prefixes);
+		result.set(m, `${prefix}/${m.id}`);
+	}
+	return result;
+}
+function validatePrefixUniqueness(models, prefixes, mode) {
+	if (mode === "universal") return void 0;
+	const providers = /* @__PURE__ */ new Set();
+	if (mode === "always-prefixed") for (const m of models) providers.add(m.provider);
+	else {
+		const conflictGroups = findConflictGroups(models);
+		for (const group of conflictGroups) for (const provider of group) providers.add(provider);
+	}
+	const labelToProvider = /* @__PURE__ */ new Map();
+	for (const provider of providers) {
+		const label = getPublicPrefix(provider, prefixes);
+		const existing = labelToProvider.get(label);
+		if (existing !== void 0) return `Duplicate prefix label '${label}' used by providers '${existing}' and '${provider}'. Configure distinct providerPrefixes.`;
+		labelToProvider.set(label, provider);
+	}
+}
+/**
+* Compute the full model-exposure result from config and available models.
+*
+* @param available - Models with auth configured (pi's getAvailable())
+* @param allRegistered - All registered models regardless of auth (pi's getAll())
+* @param config - Model exposure configuration
+*
+* Call this at startup and whenever config or the model registry changes.
+*/
+function computeModelExposure(available, allRegistered, config) {
+	const exposed = filterExposedModels(available, allRegistered, config);
+	const prefixError = validatePrefixUniqueness(exposed, config.providerPrefixes, config.publicModelIdMode);
+	if (prefixError !== void 0) return {
+		ok: false,
+		message: prefixError
+	};
+	let idMap;
+	switch (config.publicModelIdMode) {
+		case "collision-prefixed":
+			idMap = generateCollisionPrefixedIds(exposed, config.providerPrefixes);
+			break;
+		case "universal": {
+			const result = generateUniversalIds(exposed);
+			if (typeof result === "string") return {
+				ok: false,
+				message: result
+			};
+			idMap = result;
+			break;
+		}
+		case "always-prefixed":
+			idMap = generateAlwaysPrefixedIds(exposed, config.providerPrefixes);
+			break;
+	}
+	const models = [];
+	const byPublicId = /* @__PURE__ */ new Map();
+	const byCanonicalId = /* @__PURE__ */ new Map();
+	for (const m of exposed) {
+		const publicId = idMap.get(m);
+		if (publicId === void 0) continue;
+		const canonicalId = `${m.provider}/${m.id}`;
+		const entry = {
+			publicId,
+			canonicalId,
+			model: m,
+			provider: m.provider
+		};
+		models.push(entry);
+		byPublicId.set(publicId, entry);
+		byCanonicalId.set(canonicalId, entry);
+	}
+	return {
+		ok: true,
+		models,
+		byPublicId,
+		byCanonicalId
+	};
+}
+/**
+* Resolve a model ID from an incoming request against the exposure result.
+*
+* Resolution order:
+*   1. Exact public ID match
+*   2. Exact canonical ID match (backward compat, only if model is exposed)
+*/
+function resolveExposedModel(exposure, requestModelId) {
+	const byPublic = exposure.byPublicId.get(requestModelId);
+	if (byPublic !== void 0) return byPublic;
+	return exposure.byCanonicalId.get(requestModelId);
+}
+//#endregion
+export { computeModelExposure, resolveExposedModel };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { getConfigPath, loadConfigFromFile } from "./config.mjs";
+import { computeModelExposure, resolveExposedModel } from "./exposure.mjs";
 import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 import { randomBytes } from "node:crypto";
 import * as z from "zod";
@@ -65,6 +66,12 @@ function getRegistry() {
 function getAvailableModels() {
 	return getRegistry().getAvailable();
 }
+/**
+* Get all registered models (regardless of auth state).
+*/
+function getAllModels() {
+	return getRegistry().getAll();
+}
 //#endregion
 //#region src/server/errors.ts
 function makeError(message, type, param, code) {
@@ -468,196 +475,6 @@ function parseAndValidateDataUri(uri) {
 	};
 }
 //#endregion
-//#region src/openai/model-exposure.ts
-function filterExposedModels(available, config) {
-	switch (config.modelExposureMode) {
-		case "all": return [...available];
-		case "scoped": {
-			const providers = new Set(config.scopedProviders);
-			return available.filter((m) => providers.has(m.provider));
-		}
-		case "custom": {
-			const allowed = new Set(config.customModels);
-			return available.filter((m) => allowed.has(`${m.provider}/${m.id}`));
-		}
-	}
-}
-/**
-* Get the public prefix label for a provider.
-* Uses the configured override if present, otherwise the provider key itself.
-*/
-function getPublicPrefix(provider, prefixes) {
-	const override = prefixes[provider];
-	return override !== void 0 && override.length > 0 ? override : provider;
-}
-/**
-* Find connected conflict groups: sets of providers that share at least one raw model ID.
-*
-* If provider A and B share a model ID, and B and C share a different model ID,
-* then {A, B, C} form one connected conflict group.
-*/
-function findConflictGroups(models) {
-	const modelToProviders = /* @__PURE__ */ new Map();
-	for (const m of models) {
-		const existing = modelToProviders.get(m.id);
-		if (existing !== void 0) existing.add(m.provider);
-		else modelToProviders.set(m.id, new Set([m.provider]));
-	}
-	const parent = /* @__PURE__ */ new Map();
-	function find(x) {
-		let root = x;
-		while (parent.get(root) !== root) {
-			const p = parent.get(root);
-			if (p === void 0) break;
-			root = p;
-		}
-		let current = x;
-		while (current !== root) {
-			const next = parent.get(current);
-			if (next === void 0) break;
-			parent.set(current, root);
-			current = next;
-		}
-		return root;
-	}
-	function union(a, b) {
-		const ra = find(a);
-		const rb = find(b);
-		if (ra !== rb) parent.set(ra, rb);
-	}
-	for (const m of models) if (!parent.has(m.provider)) parent.set(m.provider, m.provider);
-	for (const providers of modelToProviders.values()) {
-		if (providers.size <= 1) continue;
-		const arr = [...providers];
-		const first = arr[0];
-		if (first === void 0) continue;
-		for (let i = 1; i < arr.length; i++) {
-			const other = arr[i];
-			if (other !== void 0) union(first, other);
-		}
-	}
-	const groupsByRoot = /* @__PURE__ */ new Map();
-	for (const provider of parent.keys()) {
-		const root = find(provider);
-		const existing = groupsByRoot.get(root);
-		if (existing !== void 0) existing.add(provider);
-		else groupsByRoot.set(root, new Set([provider]));
-	}
-	return [...groupsByRoot.values()].filter((g) => g.size > 1);
-}
-function generateCollisionPrefixedIds(models, prefixes) {
-	const conflictGroups = findConflictGroups(models);
-	const prefixedProviders = /* @__PURE__ */ new Set();
-	for (const group of conflictGroups) for (const provider of group) prefixedProviders.add(provider);
-	const result = /* @__PURE__ */ new Map();
-	for (const m of models) if (prefixedProviders.has(m.provider)) {
-		const prefix = getPublicPrefix(m.provider, prefixes);
-		result.set(m, `${prefix}/${m.id}`);
-	} else result.set(m, m.id);
-	return result;
-}
-function generateUniversalIds(models) {
-	const seen = /* @__PURE__ */ new Map();
-	for (const m of models) {
-		const existing = seen.get(m.id);
-		if (existing !== void 0) return `Universal mode conflict: model ID '${m.id}' is provided by both '${existing}' and '${m.provider}'. Use 'collision-prefixed' or 'always-prefixed' mode, or reduce the exposed model set.`;
-		seen.set(m.id, m.provider);
-	}
-	const result = /* @__PURE__ */ new Map();
-	for (const m of models) result.set(m, m.id);
-	return result;
-}
-function generateAlwaysPrefixedIds(models, prefixes) {
-	const result = /* @__PURE__ */ new Map();
-	for (const m of models) {
-		const prefix = getPublicPrefix(m.provider, prefixes);
-		result.set(m, `${prefix}/${m.id}`);
-	}
-	return result;
-}
-function validatePrefixUniqueness(models, prefixes, mode) {
-	if (mode === "universal") return void 0;
-	const providers = /* @__PURE__ */ new Set();
-	if (mode === "always-prefixed") for (const m of models) providers.add(m.provider);
-	else {
-		const conflictGroups = findConflictGroups(models);
-		for (const group of conflictGroups) for (const provider of group) providers.add(provider);
-	}
-	const labelToProvider = /* @__PURE__ */ new Map();
-	for (const provider of providers) {
-		const label = getPublicPrefix(provider, prefixes);
-		const existing = labelToProvider.get(label);
-		if (existing !== void 0) return `Duplicate prefix label '${label}' used by providers '${existing}' and '${provider}'. Configure distinct providerPrefixes.`;
-		labelToProvider.set(label, provider);
-	}
-}
-/**
-* Compute the full model-exposure result from config and available models.
-*
-* Call this at startup and whenever config or the model registry changes.
-*/
-function computeModelExposure(available, config) {
-	const exposed = filterExposedModels(available, config);
-	const prefixError = validatePrefixUniqueness(exposed, config.providerPrefixes, config.publicModelIdMode);
-	if (prefixError !== void 0) return {
-		ok: false,
-		message: prefixError
-	};
-	let idMap;
-	switch (config.publicModelIdMode) {
-		case "collision-prefixed":
-			idMap = generateCollisionPrefixedIds(exposed, config.providerPrefixes);
-			break;
-		case "universal": {
-			const result = generateUniversalIds(exposed);
-			if (typeof result === "string") return {
-				ok: false,
-				message: result
-			};
-			idMap = result;
-			break;
-		}
-		case "always-prefixed":
-			idMap = generateAlwaysPrefixedIds(exposed, config.providerPrefixes);
-			break;
-	}
-	const models = [];
-	const byPublicId = /* @__PURE__ */ new Map();
-	const byCanonicalId = /* @__PURE__ */ new Map();
-	for (const m of exposed) {
-		const publicId = idMap.get(m);
-		if (publicId === void 0) continue;
-		const canonicalId = `${m.provider}/${m.id}`;
-		const entry = {
-			publicId,
-			canonicalId,
-			model: m,
-			provider: m.provider
-		};
-		models.push(entry);
-		byPublicId.set(publicId, entry);
-		byCanonicalId.set(canonicalId, entry);
-	}
-	return {
-		ok: true,
-		models,
-		byPublicId,
-		byCanonicalId
-	};
-}
-/**
-* Resolve a model ID from an incoming request against the exposure result.
-*
-* Resolution order:
-*   1. Exact public ID match
-*   2. Exact canonical ID match (backward compat, only if model is exposed)
-*/
-function resolveExposedModel(exposure, requestModelId) {
-	const byPublic = exposure.byPublicId.get(requestModelId);
-	if (byPublic !== void 0) return byPublic;
-	return exposure.byCanonicalId.get(requestModelId);
-}
-//#endregion
 //#region src/openai/models.ts
 /**
 * Convert an ExposedModel to an OpenAI model object.
@@ -1483,7 +1300,7 @@ function buildExposureConfig(config) {
 * Returns the exposure result or throws on config errors.
 */
 function getExposure(config) {
-	const outcome = computeModelExposure(getAvailableModels(), buildExposureConfig(config));
+	const outcome = computeModelExposure(getAvailableModels(), getAllModels(), buildExposureConfig(config));
 	if (!outcome.ok) throw new Error(`Model exposure configuration error: ${outcome.message}`);
 	return outcome;
 }

package/extensions/proxy.ts

@@ -6,26 +6,37 @@
  *   /proxy start      Start the proxy server
  *   /proxy stop       Stop the proxy server
  *   /proxy status     Show proxy status
+ *   /proxy verify     Validate model exposure config against available models
  *   /proxy config     Open settings panel (alias)
- *   /proxy show       Summarize current config
+ *   /proxy show       Summarize current config and exposure policy
  *   /proxy path       Show config file location
  *   /proxy reset      Restore default settings
  *   /proxy help       Usage line
  *
  * Config schema imported from @victor-software-house/pi-openai-proxy/config (SSOT).
+ * Model-exposure engine imported from @victor-software-house/pi-openai-proxy/exposure.
  */
 
 import { type ChildProcess, spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { Api, Model } from "@mariozechner/pi-ai";
 import {
+	AuthStorage,
 	type ExtensionAPI,
 	type ExtensionCommandContext,
 	type ExtensionContext,
 	getSettingsListTheme,
+	ModelRegistry,
 } from "@mariozechner/pi-coding-agent";
-import { Container, type SettingItem, SettingsList, Text } from "@mariozechner/pi-tui";
+import {
+	type Component,
+	Container,
+	type SettingItem,
+	SettingsList,
+	Text,
+} from "@mariozechner/pi-tui";
 
 // Config schema -- single source of truth
 import {
@@ -33,9 +44,17 @@ import {
 	DEFAULT_CONFIG,
 	getConfigPath,
 	loadConfigFromFile,
+	type ModelExposureMode,
+	type PublicModelIdMode,
 	saveConfigToFile,
 } from "@victor-software-house/pi-openai-proxy/config";
 
+// Model-exposure engine
+import {
+	computeModelExposure,
+	type ModelExposureConfig,
+} from "@victor-software-house/pi-openai-proxy/exposure";
+
 // ---------------------------------------------------------------------------
 // Runtime status
 // ---------------------------------------------------------------------------
@@ -56,6 +75,32 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 	const extensionDir = dirname(fileURLToPath(import.meta.url));
 	const packageRoot = resolve(extensionDir, "..");
 
+	// --- Model registry access (for verify/show/selectors) ---
+
+	function getAvailableModels(): Model<Api>[] {
+		const auth = AuthStorage.create();
+		const registry = new ModelRegistry(auth);
+		return registry.getAvailable();
+	}
+
+	function getUniqueProviders(models: readonly Model<Api>[]): string[] {
+		const seen = new Set<string>();
+		for (const m of models) {
+			seen.add(m.provider);
+		}
+		return [...seen].sort();
+	}
+
+	function buildExposureConfig(): ModelExposureConfig {
+		return {
+			publicModelIdMode: config.publicModelIdMode,
+			modelExposureMode: config.modelExposureMode,
+			scopedProviders: config.scopedProviders,
+			customModels: config.customModels,
+			providerPrefixes: config.providerPrefixes,
+		};
+	}
+
 	// Resolve pi-proxy binary: try workspace node_modules, then global
 	function findProxyBinary(): string {
 		// In workspace: node_modules/pi-proxy/dist/index.mjs
@@ -85,8 +130,18 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 
 	// --- Command family ---
 
-	const SUBCOMMANDS = ["start", "stop", "status", "config", "show", "path", "reset", "help"];
-	const USAGE = "/proxy [start|stop|status|config|show|path|reset|help]";
+	const SUBCOMMANDS = [
+		"start",
+		"stop",
+		"status",
+		"verify",
+		"config",
+		"show",
+		"path",
+		"reset",
+		"help",
+	];
+	const USAGE = "/proxy [start|stop|status|verify|config|show|path|reset|help]";
 
 	pi.registerCommand("proxy", {
 		description: "Manage the OpenAI-compatible proxy",
@@ -108,8 +163,11 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 				case "status":
 					await showStatus(ctx);
 					return;
+				case "verify":
+					verifyExposure(ctx);
+					return;
 				case "show":
-					await showConfig(ctx);
+					showConfig(ctx);
 					return;
 				case "path":
 					ctx.ui.notify(getConfigPath(), "info");
@@ -358,11 +416,13 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 		await refreshStatus(ctx);
 	}
 
-	async function showConfig(ctx: ExtensionContext): Promise<void> {
+	function showConfig(ctx: ExtensionContext): void {
 		config = loadConfigFromFile();
 		const authDisplay =
 			config.authToken.length > 0 ? `enabled (token: ${config.authToken})` : "disabled";
-		const lines = [
+
+		// Server settings
+		const serverLines = [
 			`lifetime: ${config.lifetime}`,
 			`host: ${config.host}`,
 			`port: ${String(config.port)}`,
@@ -371,8 +431,96 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 			`max body: ${String(config.maxBodySizeMb)} MB`,
 			`timeout: ${String(config.upstreamTimeoutSec)}s`,
 		];
-		ctx.ui.notify(lines.join(" | "), "info");
-		await refreshStatus(ctx);
+
+		// Exposure policy
+		const exposureLines = [
+			`id mode: ${config.publicModelIdMode}`,
+			`exposure: ${config.modelExposureMode}`,
+		];
+
+		if (config.modelExposureMode === "scoped" && config.scopedProviders.length > 0) {
+			exposureLines.push(`providers: ${config.scopedProviders.join(", ")}`);
+		}
+		if (config.modelExposureMode === "custom" && config.customModels.length > 0) {
+			exposureLines.push(`models: ${String(config.customModels.length)} custom`);
+		}
+
+		const prefixKeys = Object.keys(config.providerPrefixes);
+		if (prefixKeys.length > 0) {
+			const pairs = prefixKeys.map((k) => `${k}=${config.providerPrefixes[k] ?? k}`);
+			exposureLines.push(`prefixes: ${pairs.join(", ")}`);
+		}
+
+		// Public ID preview (first 5 exposed models)
+		const models = getAvailableModels();
+		const outcome = computeModelExposure(models, buildExposureConfig());
+		if (outcome.ok && outcome.models.length > 0) {
+			const preview = outcome.models.slice(0, 5).map((m) => m.publicId);
+			const suffix =
+				outcome.models.length > 5 ? ` (+${String(outcome.models.length - 5)} more)` : "";
+			exposureLines.push(`exposed: ${preview.join(", ")}${suffix}`);
+		} else if (outcome.ok) {
+			exposureLines.push("exposed: none");
+		} else {
+			exposureLines.push(`error: ${outcome.message}`);
+		}
+
+		ctx.ui.notify(`${serverLines.join(" | ")}\n${exposureLines.join(" | ")}`, "info");
+	}
+
+	// --- /proxy verify ---
+
+	function verifyExposure(ctx: ExtensionContext): void {
+		config = loadConfigFromFile();
+		const models = getAvailableModels();
+		const issues: string[] = [];
+
+		// Check available models
+		if (models.length === 0) {
+			issues.push("No models have auth configured. The proxy will expose 0 models.");
+		}
+
+		// Check scoped providers reference valid providers
+		if (config.modelExposureMode === "scoped") {
+			const availableProviders = new Set(getUniqueProviders(models));
+			for (const p of config.scopedProviders) {
+				if (!availableProviders.has(p)) {
+					issues.push(`Scoped provider '${p}' has no available models (no auth or unknown).`);
+				}
+			}
+			if (config.scopedProviders.length === 0) {
+				issues.push("Scoped mode with empty provider list will expose 0 models.");
+			}
+		}
+
+		// Check custom models reference valid canonical IDs
+		if (config.modelExposureMode === "custom") {
+			const canonicalSet = new Set(models.map((m) => `${m.provider}/${m.id}`));
+			for (const id of config.customModels) {
+				if (!canonicalSet.has(id)) {
+					issues.push(`Custom model '${id}' is not available (no auth or unknown).`);
+				}
+			}
+			if (config.customModels.length === 0) {
+				issues.push("Custom mode with empty model list will expose 0 models.");
+			}
+		}
+
+		// Run the full exposure computation to catch ID/prefix errors
+		const outcome = computeModelExposure(models, buildExposureConfig());
+		if (!outcome.ok) {
+			issues.push(outcome.message);
+		}
+
+		if (issues.length === 0) {
+			const count = outcome.ok ? outcome.models.length : 0;
+			ctx.ui.notify(`Verification passed. ${String(count)} models exposed.`, "info");
+		} else {
+			ctx.ui.notify(
+				`Verification found ${String(issues.length)} issue(s):\n${issues.join("\n")}`,
+				"warning",
+			);
+		}
 	}
 
 	async function waitForReady(timeoutMs: number): Promise<RuntimeStatus> {
@@ -390,8 +538,94 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 
 	let lastGeneratedToken = "";
 
+	function customModelsDisplay(): string {
+		if (config.modelExposureMode !== "custom") return "n/a";
+		return config.customModels.length > 0
+			? `${String(config.customModels.length)} selected`
+			: "(none)";
+	}
+
+	/**
+	 * Build a submenu Component for selecting custom models.
+	 * Shows all available models as a toggleable checklist.
+	 */
+	function buildModelSelectorSubmenu(
+		_currentValue: string,
+		done: (selectedValue?: string) => void,
+	): Component {
+		const models = getAvailableModels();
+		const selected = new Set(config.customModels);
+		let selectedIndex = 0;
+
+		function toggle(canonicalId: string): void {
+			if (selected.has(canonicalId)) {
+				selected.delete(canonicalId);
+			} else {
+				selected.add(canonicalId);
+			}
+			config = { ...config, customModels: [...selected] };
+			saveConfigToFile(config);
+			config = loadConfigFromFile();
+		}
+
+		return {
+			render(width: number): string[] {
+				const lines: string[] = [];
+				lines.push("  Select models (Space: toggle, Esc: done)");
+				lines.push("");
+
+				if (models.length === 0) {
+					lines.push("  No models available (no auth configured)");
+					return lines;
+				}
+
+				const maxVisible = 15;
+				const start = Math.max(
+					0,
+					Math.min(selectedIndex - Math.floor(maxVisible / 2), models.length - maxVisible),
+				);
+				const end = Math.min(start + maxVisible, models.length);
+
+				for (let i = start; i < end; i++) {
+					const m = models[i];
+					if (m === undefined) continue;
+					const canonical = `${m.provider}/${m.id}`;
+					const check = selected.has(canonical) ? "[x]" : "[ ]";
+					const cursor = i === selectedIndex ? "> " : "  ";
+					const line = `${cursor}${check} ${canonical}`;
+					const truncated = line.length > width ? line.slice(0, width - 1) : line;
+					lines.push(truncated);
+				}
+
+				lines.push("");
+				lines.push(`  ${String(selected.size)} of ${String(models.length)} selected`);
+				return lines;
+			},
+			invalidate(): void {
+				// no-op
+			},
+			handleInput(data: string): void {
+				if (data === "\x1B" || data === "q") {
+					done(`${String(selected.size)} selected`);
+					return;
+				}
+				if (data === "\x1B[A" && selectedIndex > 0) {
+					selectedIndex--;
+				} else if (data === "\x1B[B" && selectedIndex < models.length - 1) {
+					selectedIndex++;
+				} else if (data === " " || data === "\r") {
+					const m = models[selectedIndex];
+					if (m !== undefined) {
+						toggle(`${m.provider}/${m.id}`);
+					}
+				}
+			},
+		};
+	}
+
 	function buildSettingItems(): SettingItem[] {
 		return [
+			// --- Server ---
 			{
 				id: "lifetime",
 				label: "Lifetime",
@@ -444,9 +678,47 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 				currentValue: `${String(config.upstreamTimeoutSec)}s`,
 				values: ["30s", "60s", "120s", "300s"],
 			},
+			// --- Model exposure ---
+			{
+				id: "publicModelIdMode",
+				label: "Public ID mode",
+				description: "How public model IDs are generated from canonical provider/model-id",
+				currentValue: config.publicModelIdMode,
+				values: ["collision-prefixed", "universal", "always-prefixed"],
+			},
+			{
+				id: "modelExposureMode",
+				label: "Exposure mode",
+				description:
+					"scoped = pi's available models, all = all registered, custom = manual selection",
+				currentValue: config.modelExposureMode,
+				values: ["scoped", "all", "custom"],
+			},
+			{
+				id: "customModels",
+				label: "Select models",
+				description:
+					config.modelExposureMode === "custom"
+						? "Press Enter to open model selector"
+						: "Switch exposure mode to 'custom' to select models",
+				currentValue: customModelsDisplay(),
+				submenu: config.modelExposureMode === "custom" ? buildModelSelectorSubmenu : undefined,
+			},
 		];
 	}
 
+	const VALID_ID_MODES = new Set<string>(["collision-prefixed", "universal", "always-prefixed"]);
+
+	function isPublicModelIdMode(v: string): v is PublicModelIdMode {
+		return VALID_ID_MODES.has(v);
+	}
+
+	const VALID_EXPOSURE_MODES = new Set<string>(["all", "scoped", "custom"]);
+
+	function isModelExposureMode(v: string): v is ModelExposureMode {
+		return VALID_EXPOSURE_MODES.has(v);
+	}
+
 	function applySetting(id: string, value: string): void {
 		switch (id) {
 			case "lifetime":
@@ -489,64 +761,110 @@ export default function proxyExtension(pi: ExtensionAPI): void {
 				if (Number.isFinite(sec) && sec > 0) config = { ...config, upstreamTimeoutSec: sec };
 				break;
 			}
+			case "publicModelIdMode":
+				if (isPublicModelIdMode(value)) {
+					config = { ...config, publicModelIdMode: value };
+				}
+				break;
+			case "modelExposureMode":
+				if (isModelExposureMode(value)) {
+					config = { ...config, modelExposureMode: value };
+				}
+				break;
+			case "customModels":
+				// Handled by submenu -- no cycling
+				break;
 		}
 		saveConfigToFile(config);
 		config = loadConfigFromFile();
 	}
 
+	/**
+	 * Get the display value for a setting after it has been applied.
+	 */
+	function getDisplayValue(id: string): string {
+		switch (id) {
+			case "lifetime":
+				return config.lifetime;
+			case "host":
+				return config.host;
+			case "port":
+				return String(config.port);
+			case "authToken":
+				return config.authToken.length > 0 ? "enabled" : "disabled";
+			case "remoteImages":
+				return config.remoteImages ? "on" : "off";
+			case "maxBodySizeMb":
+				return `${String(config.maxBodySizeMb)} MB`;
+			case "upstreamTimeoutSec":
+				return `${String(config.upstreamTimeoutSec)}s`;
+			case "publicModelIdMode":
+				return config.publicModelIdMode;
+			case "modelExposureMode":
+				return config.modelExposureMode;
+			case "customModels":
+				return customModelsDisplay();
+			default:
+				return "";
+		}
+	}
+
 	async function openSettingsPanel(ctx: ExtensionCommandContext): Promise<void> {
 		config = loadConfigFromFile();
 
 		await ctx.ui.custom<void>(
 			(tui, theme, _kb, done) => {
-				function build(): { container: Container; settingsList: SettingsList } {
-					const container = new Container();
-					container.addChild(new Text(theme.fg("accent", theme.bold("Proxy Settings")), 1, 0));
-					container.addChild(new Text(theme.fg("dim", getConfigPath()), 1, 0));
-
-					const settingsList = new SettingsList(
-						buildSettingItems(),
-						10,
-						getSettingsListTheme(),
-						(id, newValue) => {
-							lastGeneratedToken = "";
-							applySetting(id, newValue);
-							if (lastGeneratedToken.length > 0) {
-								ctx.ui.notify(`Auth token: ${lastGeneratedToken}`, "info");
-							}
-							current = build();
-							tui.requestRender();
-						},
-						() => done(undefined),
-						{ enableSearch: true },
-					);
-
-					container.addChild(settingsList);
-					container.addChild(
-						new Text(
-							theme.fg(
-								"dim",
-								"Esc: close | Arrow keys: navigate | Space: toggle | Restart proxy to apply",
-							),
-							1,
-							0,
-						),
-					);
+				const container = new Container();
+				container.addChild(new Text(theme.fg("accent", theme.bold("Proxy Settings")), 1, 0));
+				container.addChild(new Text(theme.fg("dim", getConfigPath()), 1, 0));
+
+				const items = buildSettingItems();
+				const settingsList = new SettingsList(
+					items,
+					12,
+					getSettingsListTheme(),
+					(id, newValue) => {
+						lastGeneratedToken = "";
+						applySetting(id, newValue);
+						if (lastGeneratedToken.length > 0) {
+							ctx.ui.notify(`Auth token: ${lastGeneratedToken}`, "info");
+						}
+
+						// Update display value in-place (no rebuild, preserves selection)
+						settingsList.updateValue(id, getDisplayValue(id));
+
+						// When exposure mode changes, update the "Select models" item
+						if (id === "modelExposureMode") {
+							settingsList.updateValue("customModels", customModelsDisplay());
+						}
 
-					return { container, settingsList };
-				}
+						tui.requestRender();
+					},
+					() => done(undefined),
+					{ enableSearch: true },
+				);
 
-				let current = build();
+				container.addChild(settingsList);
+				container.addChild(
+					new Text(
+						theme.fg(
+							"dim",
+							"Esc: close | Arrow keys: navigate | Space: toggle | Restart proxy to apply",
+						),
+						1,
+						0,
+					),
+				);
 
 				return {
 					render(width: number): string[] {
-						return current.container.render(width);
+						return container.render(width);
 					},
 					invalidate(): void {
-						current.container.invalidate();
+						container.invalidate();
 					},
 					handleInput(data: string): void {
-						current.settingsList.handleInput?.(data);
+						settingsList.handleInput?.(data);
 						tui.requestRender();
 					},
 				};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-openai-proxy",
-	"version": "2.0.0",
+	"version": "3.0.0",
 	"description": "OpenAI-compatible HTTP proxy for pi's multi-provider model registry",
 	"license": "MIT",
 	"author": "Victor Software House",
@@ -37,6 +37,10 @@
 		"./config": {
 			"import": "./dist/config.mjs",
 			"types": "./dist/config.d.mts"
+		},
+		"./exposure": {
+			"import": "./dist/exposure.mjs",
+			"types": "./dist/exposure.d.mts"
 		}
 	},
 	"main": "dist/index.mjs",