@victor-software-house/pi-openai-proxy 0.0.3 → 0.1.0

package/README.md

@@ -1,12 +1,6 @@
 # pi-openai-proxy
 
-A local OpenAI-compatible HTTP proxy built on [pi](https://github.com/badlogic/pi-mono)'s SDK. Routes requests through pi's multi-provider model registry and credential management, exposing a single `http://localhost:<port>/v1/...` endpoint that any OpenAI-compatible client can connect to.
-
-## Project docs
-
-- `README.md` -- project overview and API surface
-- `ROADMAP.md` -- short phase summary and delivery order
-- `PLAN.md` -- detailed implementation contract (internal)
+A local OpenAI-compatible HTTP proxy built on [pi](https://github.com/badlogic/pi-mono)'s SDK. Routes requests through pi's multi-provider model registry and credential management, exposing a single `http://localhost:4141/v1/...` endpoint that any OpenAI-compatible client can connect to.
 
 ## Why
 
@@ -14,70 +8,122 @@ A local OpenAI-compatible HTTP proxy built on [pi](https://github.com/badlogic/p
 - **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
-- **Agentic mode** (planned) -- expose pi's full agent loop (tools, sessions, compaction) behind a separate experimental endpoint
+- **Strict validation** -- unsupported parameters are rejected clearly, not silently ignored
 
-## Supported Endpoints
+## Prerequisites
 
-| Endpoint | Status | Description |
-|---|---|---|
-| `GET /v1/models` | Implemented | List all available models from pi's ModelRegistry |
-| `GET /v1/models/{model}` | Implemented | Model details for a canonical model ID (supports URL-encoded IDs with `/`) |
-| `POST /v1/chat/completions` | Implemented | Chat completions (streaming and non-streaming) |
+1. [pi](https://github.com/badlogic/pi-mono) must be installed
+2. At least one provider must be configured via `pi /login`
+3. [Bun](https://bun.sh) (for development) or [Node.js](https://nodejs.org) >= 20 (for production)
 
-## Supported Chat Completions Features
+## Installation
 
-| Feature | Status | Notes |
-|---|---|---|
-| `model` | Implemented | Resolved via `ModelRegistry.find()`, canonical or shorthand |
-| `messages` (text) | Implemented | System, developer, user, assistant, tool messages |
-| `messages` (base64 images) | Implemented | Base64 data URI image content parts |
-| `messages` (remote images) | Rejected | Disabled by default; returns clear error |
-| `stream` | Implemented | SSE with `text_delta` / `toolcall_delta` mapping |
-| `temperature` | Implemented | Direct passthrough to `StreamOptions` |
-| `max_tokens` / `max_completion_tokens` | Implemented | Normalized to `StreamOptions.maxTokens` |
-| `stop` sequences | Implemented | Via `onPayload` passthrough |
-| `user` | Implemented | Via `onPayload` passthrough |
-| `stream_options.include_usage` | Implemented | Final usage chunk in SSE stream |
-| `tools` / `tool_choice` | Implemented | JSON Schema -> TypeBox conversion (supported subset) |
-| `tool_calls` in messages | Implemented | Assistant tool call + tool result roundtrip |
-| `reasoning_effort` | Implemented | Maps to pi's `ThinkingLevel` (`low`, `medium`, `high`) |
-| `response_format` | Implemented | `text` and `json_object` via `onPayload` passthrough |
-| `top_p` | Implemented | Via `onPayload` passthrough |
-| `frequency_penalty` | Implemented | Via `onPayload` passthrough |
-| `presence_penalty` | Implemented | Via `onPayload` passthrough |
-| `seed` | Implemented | Via `onPayload` passthrough |
-| `n > 1` | Not planned | Pi streams one completion at a time |
-| `logprobs` | Not planned | Not in pi-ai's abstraction layer |
+```bash
+# Install globally
+npm install -g @victor-software-house/pi-openai-proxy
 
-## Architecture
+# Or run directly with npx
+npx @victor-software-house/pi-openai-proxy
+```
 
+## Quickstart
+
+```bash
+# Start the proxy (defaults to http://127.0.0.1:4141)
+pi-openai-proxy
 ```
-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()       |
-                              |  +-- AgentSession (P4)    |
-                              +--------------------------+
+
+### List available models
+
+```bash
+curl http://localhost:4141/v1/models | jq '.data[].id'
 ```
 
-### Pi SDK Layers Used
+### Chat completion (non-streaming)
 
-- **`@mariozechner/pi-ai`** -- `streamSimple()`, `completeSimple()`, `Model`, `Usage`, `AssistantMessageEvent`
-- **`@mariozechner/pi-coding-agent`** -- `ModelRegistry`, `AuthStorage`
+```bash
+curl http://localhost:4141/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "anthropic/claude-sonnet-4-20250514",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+
+### Chat completion (streaming)
+
+```bash
+curl http://localhost:4141/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "openai/gpt-4o",
+    "messages": [{"role": "user", "content": "Tell me a joke"}],
+    "stream": true
+  }'
+```
+
+### Use with any OpenAI-compatible client
+
+Point any client that supports `OPENAI_API_BASE` (or equivalent) at `http://localhost:4141/v1`:
+
+```bash
+# Example: Aider
+OPENAI_API_BASE=http://localhost:4141/v1 aider --model anthropic/claude-sonnet-4-20250514
+
+# Example: Continue (in settings.json)
+# "apiBase": "http://localhost:4141/v1"
+
+# Example: Open WebUI
+# Set "OpenAI API Base URL" to http://localhost:4141/v1
+```
+
+### Shorthand model names
+
+If a model ID is unique across providers, you can omit the provider prefix:
+
+```bash
+curl http://localhost:4141/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -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 `/`) |
+| `POST /v1/chat/completions` | Chat completions (streaming and non-streaming) |
+
+## Supported Chat Completions Features
+
+| Feature | Notes |
+|---|---|
+| `model` | Canonical (`provider/model-id`) or unique 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 |
+| `temperature` | Direct passthrough |
+| `max_tokens` / `max_completion_tokens` | Normalized to `maxTokens` |
+| `stop` | Via passthrough |
+| `user` | Via passthrough |
+| `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 |
+| `top_p` | Via passthrough |
+| `frequency_penalty` | Via passthrough |
+| `presence_penalty` | Via passthrough |
+| `seed` | Via passthrough |
+
+**Not supported:** `n > 1`, `logprobs`, `logit_bias`, remote image URLs (disabled by default).
 
 ## Model Naming
 
-Models are addressed as `provider/model-id`, matching pi's registry:
+Models use the `provider/model-id` canonical format, matching pi's registry:
 
 ```
 anthropic/claude-sonnet-4-20250514
@@ -87,15 +133,12 @@ xai/grok-3
 openrouter/anthropic/claude-sonnet-4-20250514
 ```
 
-Shorthand (bare model ID) is resolved by scanning all providers for a unique match. Ambiguous shorthand requests fail with a clear error listing the matching canonical IDs.
-
 ## Configuration
 
-Uses pi's existing configuration:
+The proxy reuses pi's existing configuration:
 
 - **API keys**: `~/.pi/agent/auth.json` (managed by `pi /login`)
 - **Custom models**: `~/.pi/agent/models.json`
-- **Per-request override**: `X-Pi-Upstream-Api-Key` header overrides the registry-resolved API key for a single request, keeping `Authorization` available for proxy authentication
 
 ### Environment Variables
 
@@ -104,11 +147,95 @@ Uses pi's existing configuration:
 | `PI_PROXY_HOST` | `127.0.0.1` | Bind address |
 | `PI_PROXY_PORT` | `4141` | Listen port |
 | `PI_PROXY_AUTH_TOKEN` | (disabled) | Bearer token for proxy authentication |
-| `PI_PROXY_AGENTIC` | `false` | Enable experimental agentic mode |
 | `PI_PROXY_REMOTE_IMAGES` | `false` | Enable remote image URL fetching |
 | `PI_PROXY_MAX_BODY_SIZE` | `52428800` (50 MB) | Maximum request body size in bytes |
 | `PI_PROXY_UPSTREAM_TIMEOUT_MS` | `120000` (120s) | Upstream request timeout in milliseconds |
 
+### Per-request API key override
+
+The `X-Pi-Upstream-Api-Key` header overrides the registry-resolved API key for a single request. This keeps `Authorization` available for proxy authentication:
+
+```bash
+curl http://localhost:4141/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "X-Pi-Upstream-Api-Key: sk-your-key-here" \
+  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'
+```
+
+### Proxy authentication
+
+Set `PI_PROXY_AUTH_TOKEN` to require a bearer token for all requests:
+
+```bash
+PI_PROXY_AUTH_TOKEN=my-secret-token pi-openai-proxy
+
+# Clients must include the token
+curl http://localhost:4141/v1/models \
+  -H "Authorization: Bearer my-secret-token"
+```
+
+## Pi Integration
+
+Install as a pi package to get the `/proxy` command and `--proxy` flag inside pi sessions:
+
+```bash
+pi install npm:@victor-software-house/pi-openai-proxy
+```
+
+### Start the proxy from inside pi
+
+```
+/proxy start     Start the proxy server
+/proxy stop      Stop the proxy server
+/proxy status    Show proxy status (default)
+/proxy           Show proxy status
+```
+
+### Auto-start with pi
+
+```bash
+pi --proxy
+```
+
+The proxy starts automatically on session start and stops when the session ends. A status indicator in the footer shows the proxy URL and model count.
+
+The proxy can also run standalone (see [Installation](#installation) above). The extension detects externally running instances and shows their status without trying to manage them.
+
+## 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()     |
+                              +--------------------------+
+```
+
+### Pi SDK layers used
+
+- **`@mariozechner/pi-ai`** -- `streamSimple()`, `completeSimple()`, `Model`, `Usage`, `AssistantMessageEvent`
+- **`@mariozechner/pi-coding-agent`** -- `ModelRegistry`, `AuthStorage`
+
+## Security defaults
+
+- Binds to `127.0.0.1` (localhost only) by default
+- Remote image URLs disabled by default
+- Request body size limited to 50 MB
+- Upstream timeout of 120 seconds
+- Secrets are never included in error responses
+- Client disconnects abort upstream work immediately
+
 ## Dev Workflow
 
 ```bash

package/extensions/proxy.ts

@@ -0,0 +1,222 @@
+/**
+ * Pi extension: /proxy command and --proxy flag.
+ *
+ * Manages the pi-openai-proxy server from inside a pi session.
+ *
+ * - /proxy          Show status
+ * - /proxy start    Start the proxy server
+ * - /proxy stop     Stop the proxy server (session-managed only)
+ * - /proxy status   Show status
+ * - --proxy         Auto-start on session start
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { spawn, type ChildProcess } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export default function proxyExtension(pi: ExtensionAPI) {
+	let proxyProcess: ChildProcess | undefined;
+
+	const host = process.env["PI_PROXY_HOST"] ?? "127.0.0.1";
+	const port = process.env["PI_PROXY_PORT"] ?? "4141";
+	const proxyUrl = `http://${host}:${port}`;
+
+	const extensionDir = dirname(fileURLToPath(import.meta.url));
+	const packageRoot = resolve(extensionDir, "..");
+	const proxyEntry = resolve(packageRoot, "dist", "index.mjs");
+
+	// --- Flag: --proxy ---
+
+	pi.registerFlag("proxy", {
+		description: "Start the OpenAI proxy on session start",
+		type: "boolean",
+		default: false,
+	});
+
+	// --- Lifecycle ---
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (pi.getFlag("--proxy")) {
+			await startProxy(ctx);
+		} else {
+			await refreshStatus(ctx);
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		killProxy();
+	});
+
+	// --- Command: /proxy ---
+
+	pi.registerCommand("proxy", {
+		description: "Manage the OpenAI-compatible proxy (start/stop/status)",
+		getArgumentCompletions: (prefix) => {
+			const subs = [
+				{ value: "start", label: "Start the proxy server" },
+				{ value: "stop", label: "Stop the proxy server" },
+				{ value: "status", label: "Show proxy status" },
+			];
+			if (prefix.length === 0) return subs;
+			return subs.filter((s) => s.value.startsWith(prefix));
+		},
+		handler: async (args, ctx) => {
+			const sub = args.trim().split(/\s+/)[0] ?? "";
+
+			switch (sub) {
+				case "":
+				case "status":
+					await showStatus(ctx);
+					break;
+				case "start":
+					await startProxy(ctx);
+					break;
+				case "stop":
+					await stopProxy(ctx);
+					break;
+				default:
+					ctx.ui.notify("/proxy [start|stop|status]", "info");
+			}
+		},
+	});
+
+	// --- Proxy management ---
+
+	async function probe(): Promise<{ reachable: boolean; models: number }> {
+		try {
+			const res = await fetch(`${proxyUrl}/v1/models`, {
+				signal: AbortSignal.timeout(2000),
+			});
+			if (res.ok) {
+				const body = (await res.json()) as { data?: unknown[] };
+				return { reachable: true, models: body.data?.length ?? 0 };
+			}
+		} catch {
+			// not reachable
+		}
+		return { reachable: false, models: 0 };
+	}
+
+	async function refreshStatus(ctx: ExtensionContext): Promise<void> {
+		const status = await probe();
+		if (status.reachable) {
+			ctx.ui.setStatus("proxy", `proxy: ${proxyUrl} (${String(status.models)} models)`);
+		} else if (proxyProcess !== undefined) {
+			ctx.ui.setStatus("proxy", "proxy: starting...");
+		} else {
+			ctx.ui.setStatus("proxy", undefined);
+		}
+	}
+
+	async function startProxy(ctx: ExtensionContext): Promise<void> {
+		const status = await probe();
+		if (status.reachable) {
+			ctx.ui.notify(
+				`Proxy already running at ${proxyUrl} (${String(status.models)} models)`,
+				"info",
+			);
+			await refreshStatus(ctx);
+			return;
+		}
+
+		if (proxyProcess !== undefined) {
+			ctx.ui.notify("Proxy is already starting...", "info");
+			return;
+		}
+
+		ctx.ui.setStatus("proxy", "proxy: starting...");
+
+		try {
+			proxyProcess = spawn("bun", ["run", proxyEntry], {
+				stdio: ["ignore", "pipe", "pipe"],
+				detached: false,
+				env: { ...process.env },
+			});
+
+			proxyProcess.on("exit", (code) => {
+				proxyProcess = undefined;
+				if (code !== null && code !== 0) {
+					ctx.ui.notify(`Proxy exited with code ${String(code)}`, "warn");
+				}
+				ctx.ui.setStatus("proxy", undefined);
+			});
+
+			proxyProcess.on("error", (err) => {
+				proxyProcess = undefined;
+				ctx.ui.notify(`Failed to start proxy: ${err.message}`, "error");
+				ctx.ui.setStatus("proxy", undefined);
+			});
+
+			// Wait for the server to become reachable
+			const ready = await waitForReady(3000);
+			if (ready.reachable) {
+				ctx.ui.notify(
+					`Proxy started at ${proxyUrl} (${String(ready.models)} models)`,
+					"info",
+				);
+			} else {
+				ctx.ui.notify(`Proxy spawned but not yet reachable at ${proxyUrl}`, "warn");
+			}
+			await refreshStatus(ctx);
+		} catch (err: unknown) {
+			const message = err instanceof Error ? err.message : String(err);
+			ctx.ui.notify(`Failed to start proxy: ${message}`, "error");
+			ctx.ui.setStatus("proxy", undefined);
+		}
+	}
+
+	async function stopProxy(ctx: ExtensionContext): Promise<void> {
+		if (proxyProcess !== undefined) {
+			killProxy();
+			ctx.ui.notify("Proxy stopped", "info");
+			ctx.ui.setStatus("proxy", undefined);
+			return;
+		}
+
+		const status = await probe();
+		if (status.reachable) {
+			ctx.ui.notify(
+				`Proxy at ${proxyUrl} is running externally (not managed by this session)`,
+				"info",
+			);
+		} else {
+			ctx.ui.notify("Proxy is not running", "info");
+		}
+	}
+
+	async function showStatus(ctx: ExtensionContext): Promise<void> {
+		const status = await probe();
+		const managed = proxyProcess !== undefined ? " (managed)" : " (external)";
+
+		if (status.reachable) {
+			ctx.ui.notify(
+				`${proxyUrl}${managed} -- ${String(status.models)} models available`,
+				"info",
+			);
+		} else {
+			ctx.ui.notify("Proxy not running. Use /proxy start or pi --proxy", "info");
+		}
+		await refreshStatus(ctx);
+	}
+
+	function killProxy(): void {
+		if (proxyProcess !== undefined) {
+			proxyProcess.kill("SIGTERM");
+			proxyProcess = undefined;
+		}
+	}
+
+	async function waitForReady(
+		timeoutMs: number,
+	): Promise<{ reachable: boolean; models: number }> {
+		const start = Date.now();
+		const interval = 300;
+		while (Date.now() - start < timeoutMs) {
+			const status = await probe();
+			if (status.reachable) return status;
+			await new Promise((r) => setTimeout(r, interval));
+		}
+		return { reachable: false, models: 0 };
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@victor-software-house/pi-openai-proxy",
-	"version": "0.0.3",
+	"version": "0.1.0",
 	"description": "Local OpenAI-compatible HTTP proxy built on pi's SDK",
 	"license": "MIT",
 	"author": "Victor Software House",
@@ -20,6 +20,11 @@
 		"llm",
 		"gateway"
 	],
+	"pi": {
+		"extensions": [
+			"./extensions"
+		]
+	},
 	"engines": {
 		"node": ">=20"
 	},
@@ -29,7 +34,8 @@
 		"pi-openai-proxy": "dist/index.mjs"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"extensions"
 	],
 	"scripts": {
 		"dev": "bun src/index.ts",