proxitor 0.15.0 → 0.16.0

package/README.md

@@ -8,6 +8,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/proxitor"><img src="https://img.shields.io/npm/v/proxitor?color=6366f1&labelColor=1e2327&label=npm" alt="npm version"></a>
+  <a href="https://github.com/neiromaster/proxitor/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/neiromaster/proxitor/ci.yml?branch=main&color=22c55e&labelColor=1e2327&label=CI" alt="CI status"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?labelColor=1e2327" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D22-3b82f6?labelColor=1e2327" alt="Node.js ≥ 22">
   <a href="https://github.com/neiromaster/proxitor/issues"><img src="https://img.shields.io/github/issues/neiromaster/proxitor?color=f59e0b&labelColor=1e2327&label=issues" alt="GitHub issues"></a>
@@ -19,9 +20,34 @@
 
 ---
 
+## Contents
+
+- [Why proxitor](#why-proxitor)
+- [How it works](#how-it-works)
+- [The caching problem](#the-caching-problem)
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Minimal config](#minimal-config)
+- [Configuration](#configuration)
+- [Diagnostics](#diagnostics)
+- [Commands](#commands)
+- [Common pitfalls](#common-pitfalls)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why proxitor
+
+AI CLIs already speak Anthropic or OpenAI APIs. proxitor keeps that interface intact and fixes the expensive parts in the middle:
+
+- **Provider pinning** keeps OpenRouter from bouncing the same conversation between upstreams.
+- **Prompt-cache shaping** adds sticky sessions, cache breakpoints, TTL fixes, and volatile-prefix normalization where needed.
+- **Per-model routing** lets Claude, GPT, Qwen, GLM, and other model families use different providers and policies.
+- **Operational checks** (`doctor`, `/health`, config validation, hot reload) make the proxy safe to leave running during long coding sessions.
+
 ## How it works
 
-```
+```text
 your AI CLI  →  proxitor  →  OpenRouter  →  the provider you picked
 ```
 
@@ -33,6 +59,8 @@ OpenRouter load-balances across providers, and **prompt caching is provider-scop
 
 Pin `claude-*` to `anthropic`, and that system prompt gets cached after the first hit. Subsequent requests cost a fraction.
 
+A typical 50k-token Claude Code system prompt at $3/M input costs **$0.15 per turn** with no cache. After a warm Anthropic cache, the same prefix costs ~10% of input price — about **$0.015 per turn**. The cache amortizes in 1-2 turns and pays for itself the rest of the session.
+
 ## Features
 
 - 🔒 **Stable caching** — pin models to a single provider so prompt caches survive across requests
@@ -48,6 +76,7 @@ Requires **Node.js 22+**.
 
 ```sh
 npm install -g proxitor
+# or:  pnpm install -g proxitor
 # or:  bun install -g proxitor
 # or run it once, no install:  npx proxitor
 ```
@@ -63,8 +92,9 @@ proxitor config wizard
 **2. Run it**
 
 ```sh
-proxitor
-# Listening on http://0.0.0.0:8828
+proxitor                  # default: http://0.0.0.0:8828
+proxitor --port 9000      # or pick a custom port
+proxitor up               # aliases: up, run
 ```
 
 **3. Point your tool at it**
@@ -79,6 +109,18 @@ OPENAI_BASE_URL=http://localhost:8828/v1 codex
 
 That's the whole setup. Requests flow through proxitor; streaming responses pass through untouched.
 
+## Minimal config
+
+The wizard writes a full config; the minimum is just an API key and a routing rule. Drop this into `proxitor.config.yaml` (or `.yaml`/`.yml`/`.json`, also accepted as `.proxitor.yaml`/`.proxitor.json` in the project root):
+
+```yaml
+openrouterKey: sk-or-v1-...   # or set OPENROUTER_API_KEY in your shell
+provider:
+  order: "anthropic"           # pin everything to Anthropic for stable caching
+```
+
+Run `proxitor config validate` to check it, then `proxitor` to start.
+
 ## Configuration
 
 The friendly way: an interactive menu — no YAML required.
@@ -95,6 +137,10 @@ From the menu you can set your API key and connection, pick routing per model (w
 
 Prefer to edit a file? The full **[configuration reference](./docs/configuration.md)** covers provider routing, per-model overrides, headers, caching modes, and every option. [`proxitor.config.example.yaml`](./proxitor.config.example.yaml) is a commented template.
 
+**Hot-reload** — proxitor watches the config file and reloads on save; no restart needed. Bad edits fall back to the last valid config and the proxy keeps running. `proxitor config validate` shows the current state.
+
+**Environment variables** — `OPENROUTER_API_KEY` is used when the config key is empty; `XDG_CONFIG_HOME` overrides the user-config directory on Linux/macOS. CLI flags take precedence over both.
+
 ## Diagnostics
 
 ```sh
@@ -105,7 +151,7 @@ It prints a clear report and exits non-zero if anything fails — handy from CI
 
 While proxitor runs, it logs cache usage from upstream so you can see whether caching is actually helping:
 
-```
+```text
 [abc123] Cache read: 50000, write: 25000 tokens (99.6% hit)
 ```
 
@@ -113,7 +159,7 @@ Quick health poke: `curl http://localhost:8828/health`.
 
 ### Tuning the cache
 
-If the cache hit looks low, three levers fix it — tune them from `proxitor config` → **💾 Caching** (or `proxitor config cache`):
+If the cache hit looks low, four levers fix it — tune them from `proxitor config` → **💾 Caching** (or `proxitor config cache`):
 
 - **`cacheControl`** — inject `cache_control` to activate caching (Anthropic-native).
 - **`sessionId`** — inject `session_id` so the provider pins from the first request.
@@ -125,15 +171,33 @@ See the [configuration reference](./docs/configuration.md#prompt-caching) for th
 ## Commands
 
 | Command | Description |
-|---|---|
+| --- | --- |
 | `proxitor` | Start the proxy (default command) |
 | `proxitor config` | Interactive config menu |
 | `proxitor config wizard` | Guided setup |
 | `proxitor config browse` | Explore models + pricing |
+| `proxitor config add` | Add a model override |
+| `proxitor config edit` | Edit an existing model override |
+| `proxitor config remove` | Remove a model override |
+| `proxitor config list` | List all model overrides (also `--json`) |
+| `proxitor config cache` | Tune prompt-caching settings |
+| `proxitor config show` | Print the resolved config |
+| `proxitor config validate` | Check the config (exit 0 ok, 1 invalid — CI-friendly) |
 | `proxitor doctor` | Diagnose everything |
+| `proxitor --version` | Print version |
 | `proxitor --help` | Full list of flags |
 
-Common flags: `--port`, `--host`, `--config <path>`, `--openrouter-key <key>`.
+Common flags: `--port`, `--host`, `--config <path>`, `--openrouter-key <key>` / `-k <key>`, `--verbose`, `--no-config`.
+
+## Common pitfalls
+
+**Cache reads stay at 0 even after several requests.** The prefix usually churns every turn (Claude Code's `cch`/`cc_version` hashes) — enable `normalizeVolatileSystem: true` and confirm the request actually lands on the same provider. `proxitor doctor` reports the loaded config; the cache-read log in the proxy console reports hits.
+
+**Anthropic returns `400` about mixed TTLs when `cacheControlTtl: 1h`.** Set `rewriteBlockTtl: auto` (or `always`) to normalize the client's block-level `cache_control` breakpoints to the same TTL — see the [configuration reference](./docs/configuration.md#prompt-caching).
+
+**The provider keeps switching between requests.** Make sure `sessionId` is not `skip` — both `auto` (default) and `always` inject a sticky session ID; without it OpenRouter only pins after the first cache hit.
+
+**Config edits don't take effect.** They should — proxitor hot-reloads on save. If the file is invalid the proxy keeps the last valid config; `proxitor config validate` shows what was rejected.
 
 ## Contributing
 

package/dist/cli.mjs

@@ -16329,6 +16329,16 @@ var MissingConfigError = class extends Error {
 	}
 };
 //#endregion
+//#region src/model-id.ts
+/** `"anthropic/claude-sonnet-4"` → `"anthropic"`; a bare `"gpt-4o"` → `"gpt-4o"`. */
+function parseModelAuthor(modelId) {
+	return modelId.split("/")[0] ?? "";
+}
+/** Text after the first `/`, or `""` for a bare id. `"openai/gpt-4o"` → `"gpt-4o"`. */
+function parseModelSlug(modelId) {
+	return modelId.split("/").slice(1).join("/");
+}
+//#endregion
 //#region src/utils.ts
 /** Format an API key with the appropriate auth prefix based on authType. Defaults to Bearer. */
 function formatAuthHeader(key, authType) {
@@ -16411,14 +16421,49 @@ function buildProviderRouting(provider) {
 	if (result.order) result.allow_fallbacks = provider.allowFallbacks ?? true;
 	return Object.keys(result).length > 0 ? result : void 0;
 }
+/** Slug after the vendor prefix; bare ids keep their text. Delegates to parseModelSlug. */
+function modelSlug(s) {
+	return parseModelSlug(s) || s;
+}
 function matchScore(pattern, modelName) {
-	if (pattern === modelName) return modelName.length + 1e3;
-	if (pattern.endsWith("*") && modelName.startsWith(pattern.slice(0, -1))) return pattern.length;
+	if (pattern === modelName) return 3e3 + pattern.length;
+	if (pattern.endsWith("*") && modelName.startsWith(pattern.slice(0, -1))) return 2e3 + pattern.length;
+	if (pattern.includes("/") && modelName.includes("/")) return -1;
+	const sp = modelSlug(pattern);
+	const sm = modelSlug(modelName);
+	if (sp === sm) return 1e3 + sp.length;
+	if (sp.endsWith("*") && sm.startsWith(sp.slice(0, -1))) return sp.length;
 	return -1;
 }
 function matchesPattern(pattern, modelName) {
 	return matchScore(pattern, modelName) >= 0;
 }
+/** Override keys sharing a slug. `winner` is the key a bare name resolves to — not always `keys[0]`, since a bare key wins on the full-exact tier. Pure; callers log it. */
+function detectSlugCollisions(overrides) {
+	if (!overrides) return [];
+	const groups = /* @__PURE__ */ new Map();
+	for (const key of Object.keys(overrides)) {
+		const slug = modelSlug(key);
+		const keys = groups.get(slug);
+		if (keys) keys.push(key);
+		else groups.set(slug, [key]);
+	}
+	const collisions = [];
+	for (const [slug, keys] of groups) {
+		if (keys.length <= 1) continue;
+		const winner = findBestMatch(keys, slug);
+		if (winner) collisions.push({
+			slug,
+			keys,
+			winner
+		});
+	}
+	return collisions;
+}
+/** Warning text for a same-slug collision. */
+function formatSlugCollisionWarning(c) {
+	return `Overrides ${c.keys.map((k) => `"${k}"`).join(" and ")} share model slug "${c.slug}"; a bare name resolves to "${c.winner}". Use the vendor-prefixed name to pick a specific one.`;
+}
 function resolveModelConfig(config, modelName) {
 	const result = {
 		provider: config.provider,
@@ -16431,7 +16476,10 @@ function resolveModelConfig(config, modelName) {
 	};
 	if (!modelName || !config.modelOverrides) return result;
 	const bestPattern = findBestMatch(Object.keys(config.modelOverrides), modelName);
-	if (bestPattern) applyOverride(result, config.modelOverrides[bestPattern]);
+	if (bestPattern) {
+		applyOverride(result, config.modelOverrides[bestPattern]);
+		result.matchedOverride = bestPattern;
+	}
 	return result;
 }
 function findBestMatch(patterns, modelName) {
@@ -16677,14 +16725,6 @@ async function fetchModels(client) {
 	writeCache(CACHE_KEY$1, models);
 	return models;
 }
-/** `"anthropic/claude-sonnet-4"` → `"anthropic"` */
-function parseModelAuthor(modelId) {
-	return modelId.split("/")[0] ?? "";
-}
-/** `"anthropic/claude-sonnet-4"` → `"claude-sonnet-4"` */
-function parseModelSlug(modelId) {
-	return modelId.split("/").slice(1).join("/");
-}
 /** `"0.000003"` → `"$3.00"`, `"0"` → `"free"` */
 function formatPrice(pricePerToken) {
 	const per1M = Number.parseFloat(pricePerToken) * 1e6;
@@ -19514,7 +19554,7 @@ async function runConfigMenu(client) {
 }
 //#endregion
 //#region src/version.ts
-const version = "0.15.0";
+const version = "0.16.0";
 //#endregion
 //#region src/commands/doctor.ts
 const DEFAULT_TIMEOUT_MS = 3e3;
@@ -19601,6 +19641,24 @@ function checkConfigValidity(path) {
 		};
 	}
 }
+function checkSlugCollisions(cfg) {
+	if (!cfg?.modelOverrides) return {
+		name: "override-collisions",
+		status: "ok",
+		message: "no model overrides"
+	};
+	const collisions = detectSlugCollisions(cfg.modelOverrides);
+	if (collisions.length === 0) return {
+		name: "override-collisions",
+		status: "ok",
+		message: "no slug collisions"
+	};
+	return {
+		name: "override-collisions",
+		status: "warn",
+		message: collisions.map(formatSlugCollisionWarning).join(" | ")
+	};
+}
 function checkApiKey(cfg) {
 	const fromEnv = process.env.OPENROUTER_API_KEY ? "set" : "not set";
 	const fromFile = cfg?.openrouterKey ? "set" : "not set";
@@ -19709,7 +19767,11 @@ async function doctorCommand(opts = {}) {
 	];
 	const configPath = tryFindConfigFile();
 	const { check: validityCheck, config: cfg } = checkConfigValidity(configPath);
-	const configChecks = [checkConfigDiscovery(), validityCheck];
+	const configChecks = [
+		checkConfigDiscovery(),
+		validityCheck,
+		checkSlugCollisions(cfg)
+	];
 	const apiKeyCheck = checkApiKey(cfg);
 	const upstreamCheck = await checkUpstream(cfg, timeoutMs, offline);
 	const portCheck = cfg ? await checkPort(cfg.host, cfg.port) : {
@@ -19835,8 +19897,10 @@ var FileWatchingConfigSource = class {
 	loading = false;
 	pending = false;
 	watching = false;
+	lastCollisionSig = "";
 	constructor(options) {
 		this.current = options.initial;
+		this.warnSlugCollisions(options.initial.modelOverrides);
 		this.loadOptions = options.loadOptions;
 		this.load = options.load ?? loadConfig;
 		this.pollIntervalMs = options.pollIntervalMs ?? 1e3;
@@ -19848,6 +19912,18 @@ var FileWatchingConfigSource = class {
 	get() {
 		return this.current;
 	}
+	/** Warn only when the collision set changes, so reloading an unchanged config doesn't re-log. */
+	warnSlugCollisions(overrides) {
+		const collisions = detectSlugCollisions(overrides ?? void 0);
+		const sig = collisions.map((c) => [
+			c.slug,
+			c.winner,
+			[...c.keys].sort((a, b) => a.localeCompare(b)).join(",")
+		].join("|")).sort((a, b) => a.localeCompare(b)).join("||");
+		if (sig === this.lastCollisionSig) return;
+		this.lastCollisionSig = sig;
+		for (const collision of collisions) logger.warn(formatSlugCollisionWarning(collision));
+	}
 	async reload() {
 		if (this.loading) {
 			this.pending = true;
@@ -19864,6 +19940,7 @@ var FileWatchingConfigSource = class {
 				diff = "";
 			}
 			this.current = next;
+			this.warnSlugCollisions(next.modelOverrides);
 			if (restartNeeded) logger.warn("host/port changed — restart proxitor to apply (live reload does not re-bind the socket)");
 			logger.info(`Config reloaded${diff ? ` — ${diff}` : " (no material changes)"}`);
 			return { ok: true };
@@ -23340,6 +23417,7 @@ const readBody = createMiddleware(async (c, next) => {
 const resolveConfig = createMiddleware(async (c, next) => {
 	const resolved = resolveModelConfig(c.var.config, c.var.modelName);
 	c.set("resolvedConfig", resolved);
+	if (c.var.config.verbose && c.var.modelName) logger.info(resolved.matchedOverride ? `override "${resolved.matchedOverride}" matched incoming "${c.var.modelName}"` : `no override matched for "${c.var.modelName}"`);
 	await next();
 });
 //#endregion