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

package/README.md

@@ -77,9 +77,14 @@ OPENAI_API_BASE=http://localhost:4141/v1 aider --model anthropic/claude-sonnet-4
 # Set "OpenAI API Base URL" to http://localhost:4141/v1
 ```
 
-### Shorthand model names
+### Model resolution
 
-If a model ID is unique across providers, you can omit the provider prefix:
+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)
+
+With the default `collision-prefixed` mode and no collisions, model IDs are exposed without prefixes:
 
 ```bash
 curl http://localhost:4141/v1/chat/completions \
@@ -87,21 +92,19 @@ curl http://localhost:4141/v1/chat/completions \
   -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'
 ```
 
-Ambiguous shorthand requests fail with a clear error listing the matching canonical IDs.
-
 ## Supported Endpoints
 
 | Endpoint | Description |
 |---|---|
-| `GET /v1/models` | List all available models (only those with configured credentials) |
-| `GET /v1/models/{model}` | Model details by canonical ID (supports URL-encoded IDs with `/`) |
+| `GET /v1/models` | List exposed models (filtered by exposure mode, only those with configured credentials) |
+| `GET /v1/models/{model}` | Model details by public ID or canonical ID (supports URL-encoded IDs with `/`) |
 | `POST /v1/chat/completions` | Chat completions (streaming and non-streaming) |
 
 ## Supported Chat Completions Features
 
 | Feature | Notes |
 |---|---|
-| `model` | Canonical (`provider/model-id`) or unique shorthand |
+| `model` | Public ID, canonical (`provider/model-id`), or collision-prefixed shorthand |
 | `messages` (text) | `system`, `developer`, `user`, `assistant`, `tool` roles |
 | `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 |
@@ -112,8 +115,8 @@ Ambiguous shorthand requests fail with a clear error listing the matching canoni
 | `stream_options.include_usage` | Final usage chunk in SSE stream |
 | `tools` / `tool_choice` | JSON Schema -> TypeBox conversion (supported subset) |
 | `tool_calls` in messages | Assistant tool call + tool result roundtrip |
-| `reasoning_effort` | Maps to pi's `ThinkingLevel` (`low`, `medium`, `high`) |
-| `response_format` | `text` and `json_object` via passthrough |
+| `reasoning_effort` | Maps to pi's `ThinkingLevel` (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) |
+| `response_format` | `text`, `json_object`, and `json_schema` via passthrough |
 | `top_p` | Via passthrough |
 | `frequency_penalty` | Via passthrough |
 | `presence_penalty` | Via passthrough |
@@ -121,9 +124,33 @@ Ambiguous shorthand requests fail with a clear error listing the matching canoni
 
 **Not supported:** `n > 1`, `logprobs`, `logit_bias`, remote image URLs (disabled by default).
 
-## Model Naming
+## Model Naming and Exposure
+
+### Public model IDs
+
+The proxy generates public model IDs based on a configurable ID mode:
+
+| Mode | Behavior | Example |
+|---|---|---|
+| `collision-prefixed` (default) | Raw model IDs; prefix only providers that share a model name | `gpt-4o` or `openai/gpt-4o` if `codex` also has `gpt-4o` |
+| `universal` | Raw model IDs only; rejects config if duplicates exist | `gpt-4o`, `claude-sonnet-4-20250514` |
+| `always-prefixed` | Always `<prefix>/<model-id>` | `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514` |
+
+The `collision-prefixed` mode prefixes **all** models from providers that form a connected conflict group (not just the colliding model names).
+
+### Exposure modes
+
+Control which models appear in the API:
 
-Models use the `provider/model-id` canonical format, matching pi's registry:
+| Mode | Behavior |
+|---|---|
+| `all` (default) | Expose every model with configured credentials |
+| `scoped` | Expose models from selected providers only (`scopedProviders`) |
+| `custom` | Expose an explicit allowlist of canonical IDs (`customModels`) |
+
+### Canonical model IDs
+
+Internal canonical IDs use the `provider/model-id` format matching pi's registry:
 
 ```
 anthropic/claude-sonnet-4-20250514
@@ -133,6 +160,8 @@ xai/grok-3
 openrouter/anthropic/claude-sonnet-4-20250514
 ```
 
+Canonical IDs are accepted as backward-compatible fallback in requests, but only for models that are currently exposed. Hidden models cannot be reached by canonical ID.
+
 ## Configuration
 
 ### What comes from pi
@@ -159,22 +188,27 @@ Proxy-specific settings are configured via environment variables or the `/proxy
 | Max body size | `PI_PROXY_MAX_BODY_SIZE` | `52428800` (50 MB) | Maximum request body size in bytes |
 | Upstream timeout | `PI_PROXY_UPSTREAM_TIMEOUT_MS` | `120000` (120s) | Upstream request timeout in milliseconds |
 
-When used as a pi package, these settings are persisted in `~/.pi/agent/proxy-config.json` and applied when the extension spawns the proxy.
+Model exposure settings are configured via the JSON config file (`~/.pi/agent/proxy-config.json`):
+
+| Setting | Default | Description |
+|---|---|---|
+| `publicModelIdMode` | `collision-prefixed` | Public ID format: `collision-prefixed`, `universal`, `always-prefixed` |
+| `modelExposureMode` | `all` | Which models to expose: `all`, `scoped`, `custom` |
+| `scopedProviders` | `[]` | Provider keys for `scoped` mode |
+| `customModels` | `[]` | Canonical model IDs for `custom` mode |
+| `providerPrefixes` | `{}` | Provider key -> custom prefix label overrides |
+
+When used as a pi package, all settings are persisted in `~/.pi/agent/proxy-config.json` and applied when the extension spawns the proxy.
 
 ### Discovering available models
 
-List all models the proxy can reach (models with configured credentials):
+List all models the proxy exposes (filtered by the active exposure mode):
 
 ```bash
 curl http://localhost:4141/v1/models | jq '.data[].id'
 ```
 
-Each model includes extended metadata under `x_pi`:
-
-```bash
-curl http://localhost:4141/v1/models/anthropic%2Fclaude-sonnet-4-20250514 | jq '.x_pi'
-# { "api": "anthropic", "reasoning": true, "input": ["text", "image"], ... }
-```
+Model objects follow the standard OpenAI shape (`id`, `object`, `created`, `owned_by`) with no proprietary extensions.
 
 ### Per-request API key override
 

package/dist/config.d.mts

@@ -0,0 +1,59 @@
+
+//#region src/config/schema.d.ts
+/**
+ * Proxy configuration schema -- single source of truth.
+ *
+ * Used by both the proxy server and the pi extension.
+ * The server reads the JSON config file as defaults, with env vars and CLI args as overrides.
+ * The pi extension reads and writes the JSON config file via the /proxy config panel.
+ */
+/**
+ * How public model IDs are generated from canonical provider/model-id pairs.
+ *
+ * - "collision-prefixed": prefix only providers in conflict groups that share a raw model ID
+ * - "universal": expose raw model IDs only; duplicates are a config error
+ * - "always-prefixed": always expose <prefix>/<model-id> for every model
+ */
+type PublicModelIdMode = "collision-prefixed" | "universal" | "always-prefixed";
+/**
+ * Which models are exposed on the public HTTP API.
+ *
+ * - "all": every available model
+ * - "scoped": all available models from selected providers only
+ * - "custom": explicit allowlist of canonical model IDs
+ */
+type ModelExposureMode = "all" | "scoped" | "custom";
+interface ProxyConfig {
+  /** Bind address. Default: "127.0.0.1" */
+  readonly host: string;
+  /** Listen port. Default: 4141 */
+  readonly port: number;
+  /** Bearer token for proxy auth. Empty string = disabled. */
+  readonly authToken: string;
+  /** Allow remote image URL fetching. Default: false */
+  readonly remoteImages: boolean;
+  /** Max request body in MB. Default: 50 */
+  readonly maxBodySizeMb: number;
+  /** Upstream timeout in seconds. Default: 120 */
+  readonly upstreamTimeoutSec: number;
+  /** "detached" = background daemon, "session" = dies with pi session. Default: "detached" */
+  readonly lifetime: "detached" | "session";
+  /** How public model IDs are generated. Default: "collision-prefixed" */
+  readonly publicModelIdMode: PublicModelIdMode;
+  /** Which models are exposed. Default: "all" */
+  readonly modelExposureMode: ModelExposureMode;
+  /** Provider keys to expose when modelExposureMode is "scoped". */
+  readonly scopedProviders: readonly string[];
+  /** Canonical model IDs to expose when modelExposureMode is "custom". */
+  readonly customModels: readonly string[];
+  /** Provider key -> custom public prefix label. Default prefix = provider key. */
+  readonly providerPrefixes: Readonly<Record<string, string>>;
+}
+declare const DEFAULT_CONFIG: Readonly<ProxyConfig>;
+declare function normalizeConfig(raw: unknown): ProxyConfig;
+declare function getConfigPath(): string;
+declare function loadConfigFromFile(): ProxyConfig;
+declare function saveConfigToFile(config: ProxyConfig): void;
+declare function configToEnv(config: ProxyConfig): Record<string, string>;
+//#endregion
+export { DEFAULT_CONFIG, ModelExposureMode, ProxyConfig, PublicModelIdMode, configToEnv, getConfigPath, loadConfigFromFile, normalizeConfig, saveConfigToFile };

package/dist/config.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+//#region src/config/schema.ts
+/**
+* Proxy configuration schema -- single source of truth.
+*
+* Used by both the proxy server and the pi extension.
+* The server reads the JSON config file as defaults, with env vars and CLI args as overrides.
+* The pi extension reads and writes the JSON config file via the /proxy config panel.
+*/
+const DEFAULT_CONFIG = {
+	host: "127.0.0.1",
+	port: 4141,
+	authToken: "",
+	remoteImages: false,
+	maxBodySizeMb: 50,
+	upstreamTimeoutSec: 120,
+	lifetime: "detached",
+	publicModelIdMode: "collision-prefixed",
+	modelExposureMode: "all",
+	scopedProviders: [],
+	customModels: [],
+	providerPrefixes: {}
+};
+function isRecord(value) {
+	return value !== null && value !== void 0 && typeof value === "object" && !Array.isArray(value);
+}
+function clampInt(raw, min, max, fallback) {
+	if (typeof raw !== "number" || !Number.isFinite(raw)) return fallback;
+	return Math.max(min, Math.min(max, Math.round(raw)));
+}
+const VALID_PUBLIC_ID_MODES = new Set([
+	"collision-prefixed",
+	"universal",
+	"always-prefixed"
+]);
+function isPublicModelIdMode(value) {
+	return VALID_PUBLIC_ID_MODES.has(value);
+}
+const VALID_EXPOSURE_MODES = new Set([
+	"all",
+	"scoped",
+	"custom"
+]);
+function isModelExposureMode(value) {
+	return VALID_EXPOSURE_MODES.has(value);
+}
+function normalizeStringArray(raw) {
+	if (!Array.isArray(raw)) return [];
+	const result = [];
+	for (const item of raw) if (typeof item === "string" && item.length > 0) result.push(item);
+	return result;
+}
+function normalizeStringRecord(raw) {
+	if (!isRecord(raw)) return {};
+	const result = {};
+	for (const [key, val] of Object.entries(raw)) if (typeof val === "string" && val.length > 0) result[key] = val;
+	return result;
+}
+function normalizeConfig(raw) {
+	const v = isRecord(raw) ? raw : {};
+	const rawHost = v["host"];
+	const rawAuthToken = v["authToken"];
+	const rawRemoteImages = v["remoteImages"];
+	const rawPublicIdMode = v["publicModelIdMode"];
+	const rawExposureMode = v["modelExposureMode"];
+	return {
+		host: typeof rawHost === "string" && rawHost.length > 0 ? rawHost : DEFAULT_CONFIG.host,
+		port: clampInt(v["port"], 1, 65535, DEFAULT_CONFIG.port),
+		authToken: typeof rawAuthToken === "string" ? rawAuthToken : DEFAULT_CONFIG.authToken,
+		remoteImages: typeof rawRemoteImages === "boolean" ? rawRemoteImages : DEFAULT_CONFIG.remoteImages,
+		maxBodySizeMb: clampInt(v["maxBodySizeMb"], 1, 500, DEFAULT_CONFIG.maxBodySizeMb),
+		upstreamTimeoutSec: clampInt(v["upstreamTimeoutSec"], 5, 600, DEFAULT_CONFIG.upstreamTimeoutSec),
+		lifetime: v["lifetime"] === "session" ? "session" : "detached",
+		publicModelIdMode: typeof rawPublicIdMode === "string" && isPublicModelIdMode(rawPublicIdMode) ? rawPublicIdMode : DEFAULT_CONFIG.publicModelIdMode,
+		modelExposureMode: typeof rawExposureMode === "string" && isModelExposureMode(rawExposureMode) ? rawExposureMode : DEFAULT_CONFIG.modelExposureMode,
+		scopedProviders: normalizeStringArray(v["scopedProviders"]),
+		customModels: normalizeStringArray(v["customModels"]),
+		providerPrefixes: normalizeStringRecord(v["providerPrefixes"])
+	};
+}
+function getConfigPath() {
+	return resolve(process.env["PI_CODING_AGENT_DIR"] ?? resolve(process.env["HOME"] ?? "~", ".pi", "agent"), "proxy-config.json");
+}
+function loadConfigFromFile() {
+	const p = getConfigPath();
+	if (!existsSync(p)) return { ...DEFAULT_CONFIG };
+	try {
+		return normalizeConfig(JSON.parse(readFileSync(p, "utf-8")));
+	} catch {
+		return { ...DEFAULT_CONFIG };
+	}
+}
+function saveConfigToFile(config) {
+	const p = getConfigPath();
+	const normalized = normalizeConfig(config);
+	const tmp = `${p}.tmp`;
+	try {
+		mkdirSync(dirname(p), { recursive: true });
+		writeFileSync(tmp, `${JSON.stringify(normalized, null, "	")}\n`, "utf-8");
+		renameSync(tmp, p);
+	} catch {
+		if (existsSync(tmp)) unlinkSync(tmp);
+	}
+}
+function configToEnv(config) {
+	const env = {};
+	env["PI_PROXY_HOST"] = config.host;
+	env["PI_PROXY_PORT"] = String(config.port);
+	if (config.authToken.length > 0) env["PI_PROXY_AUTH_TOKEN"] = config.authToken;
+	env["PI_PROXY_REMOTE_IMAGES"] = String(config.remoteImages);
+	env["PI_PROXY_MAX_BODY_SIZE"] = String(config.maxBodySizeMb * 1024 * 1024);
+	env["PI_PROXY_UPSTREAM_TIMEOUT_MS"] = String(config.upstreamTimeoutSec * 1e3);
+	return env;
+}
+//#endregion
+export { DEFAULT_CONFIG, configToEnv, getConfigPath, loadConfigFromFile, normalizeConfig, saveConfigToFile };

package/dist/index.d.mts

@@ -1,11 +1,2 @@
 
-//#region src/index.d.ts
-/**
- * pi-openai-proxy entry point.
- *
- * Initializes the pi model registry, creates the Hono app, and starts serving.
- * Implements graceful shutdown on SIGTERM/SIGINT.
- */
-declare const server: Bun.Server<undefined>;
-//#endregion
-export { server as default };
+export { };