pi-cliproxyapi 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# pi-cliproxyapi
+
+Pi extension for corporate management of model providers via a single [CliProxyAPI](https://github.com/nicepkg/cliproxyapi) endpoint.
+
+One `(endpoint, apiKey)` pair — every provider and model inherits it automatically.
+
+## Features
+
+- **Built-in provider routing** — whitelist which Anthropic / OpenAI / etc. models are available through the proxy
+- **Custom provider groups** — create named groups (e.g. `corp-glm`, `corp-gemini`) for proxy-only models with automatic metadata from [models.dev](https://models.dev)
+- **Exclusive model pool** — a model assigned to one group automatically disappears from others
+- **Per-account usage overlay** — colored quota bars, toggle disabled accounts, verbose errors — no LLM call
+- **Setup wizard** — `/cliproxy-setup` configures endpoint, API key, provider prefix, and usage key interactively
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/cliproxy` | Interactive overlay — enable providers, toggle models, create custom groups |
+| `/cliproxy-setup` | Configure endpoint, API key, provider prefix, usage key |
+| `/cliproxy-refresh` | Re-fetch upstream models, re-register providers |
+| `/cliproxy-list` | Read-only view of current configuration |
+| `/cliproxy-usage` | Per-account quota windows with progress bars (`d` = show disabled, `v` = verbose) |
+| `/cliproxy-doctor` | Connectivity, key resolution, discovery diagnostics |
+
+## Install
+
+```bash
+pi install pi-cliproxyapi
+```
+
+Then run `/cliproxy-setup` to configure your proxy endpoint.
+
+## Config
+
+`~/.config/pi-cliproxyapi/config.json` — created by `/cliproxy-setup`, editable by hand:
+
+```jsonc
+{
+  "proxy": {
+    "endpoint": "https://proxy.example.com/v1",
+    "apiKey": "!cat ~/.config/pi-cliproxyapi/key",
+    "providerPrefix": "corp",
+    "usageKey": "!cat ~/.config/pi-cliproxyapi/usage-key"
+  },
+  "builtinProviders": {
+    "anthropic": { "enabled": true, "models": ["claude-opus-4-7"] },
+    "openai": { "enabled": true, "models": ["gpt-5.2"] }
+  },
+  "customProviders": {
+    "corp-glm": {
+      "api": "openai-completions",
+      "models": [{ "id": "glm-4.7", "name": "GLM 4.7" }]
+    }
+  }
+}
+```
+
+Values support `!command` (shell exec), `$ENV_VAR`, `~/path` (auto-wrapped to `!cat`), or literal strings.
+
+## Discovery
+
+The plugin tries `GET <endpoint-origin>/.well-known/pi` first (requires the companion sidecar service). If unavailable, falls back to `GET <endpoint>/models` with local heuristics.
+
+### Optional: companion discovery service
+
+For richer model metadata (context windows, costs, reasoning flags from models.dev) and per-account usage, deploy **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)** alongside your CliProxyAPI instance.
+
+```
+┌──────────────┐     ┌───────────────────────────┐
+│  Pi + plugin  │────▶│  CliProxyAPI (:8317)       │
+│               │     │  /v1/models, /v1/chat/...  │
+│               │     └───────────────────────────┘
+│               │     ┌───────────────────────────┐
+│               │────▶│  wellknown sidecar (:3458)  │
+│               │     │  /.well-known/pi            │
+│               │     │  /api/usage                 │
+│               │     └───────────────────────────┘
+└──────────────┘
+```
+
+The sidecar is **optional** — the plugin works without it using `/v1/models` + local classification.
+
+## Layout
+
+```
+index.ts            ExtensionFactory entry point
+src/
+  config.ts         ~/.config/pi-cliproxyapi/config.json
+  commands.ts       6 slash commands
+  apply.ts          pi.registerProvider calls
+  fetch-models.ts   well-known + /v1/models fallback
+  fetch-usage.ts    /api/usage client with TTL cache
+  compat.ts         baseUrl derivation, model classification
+  conflicts.ts      read-only ~/.pi/{models,auth}.json scan
+  ui-picker.ts      overlay picker with collapsible provider groups
+  ui-usage.ts       ANSI-colored usage renderer
+  ui-overlay.ts     scrollable overlay shell with toggles
+  ui-setup.ts       setup wizard
+  log.ts            tagged logger
+```

package/index.ts

@@ -0,0 +1,67 @@
+/**
+ * pi-cliproxyapi — Pi extension that manages model providers through a single
+ * CliProxyAPI endpoint with one corporate key.
+ *
+ * On factory boot we:
+ *   1. load ~/.config/pi-cliproxyapi/config.json (defaults if missing)
+ *   2. fetch discovery (well-known → fall back to /v1/models)
+ *   3. call pi.registerProvider for each enabled built-in + custom provider
+ *   4. register slash commands /cliproxy /cliproxy-setup /cliproxy-refresh
+ *      /cliproxy-list /cliproxy-usage /cliproxy-doctor
+ *
+ * All discovery + apply errors are logged but never abort extension load —
+ * a missing/broken proxy must not prevent Pi from starting.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { applyAll } from "./src/apply.ts";
+import { registerCommands } from "./src/commands.ts";
+import { loadConfig, resolveConfigValue } from "./src/config.ts";
+import { detectConflicts } from "./src/conflicts.ts";
+import { fetchDiscovery } from "./src/fetch-models.ts";
+import { log } from "./src/log.ts";
+
+export default async function cliproxyapi(pi: ExtensionAPI): Promise<void> {
+	registerCommands(pi);
+
+	const cfg = loadConfig();
+	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
+	if (!resolvedKey) {
+		log.warn(
+			"apiKey is empty after resolution — skipping initial apply. Run /cliproxy-setup to configure.",
+		);
+		return;
+	}
+
+	// Conflict scan is read-only and cheap; do it once at startup.
+	const conflicts = detectConflicts(cfg);
+	for (const c of conflicts) log.warn(`conflict (${c.kind}): ${c.detail}`);
+
+	try {
+		const discovery = await fetchDiscovery(cfg, resolvedKey);
+		await applyAll(pi, cfg, discovery);
+	} catch (err) {
+		log.error("initial apply failed:", (err as Error).message);
+		// Commands stay registered; user can /cliproxy-doctor or /cliproxy-refresh.
+	}
+
+	if (cfg.refreshIntervalMinutes > 0) {
+		const ms = cfg.refreshIntervalMinutes * 60_000;
+		setInterval(() => {
+			void (async () => {
+				try {
+					const c = loadConfig();
+					const k = resolveConfigValue(c.proxy.apiKey);
+					if (!k) return;
+					const d = await fetchDiscovery(c, k);
+					await applyAll(pi, c, d);
+					log.debug("background refresh ok");
+				} catch (e) {
+					log.warn("background refresh failed:", (e as Error).message);
+				}
+			})();
+		}, ms);
+		log.info(`background refresh every ${cfg.refreshIntervalMinutes}m`);
+	}
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-cliproxyapi",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension for corporate management of model providers via a single CliProxyAPI endpoint",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abix5/pi-cliproxyapi.git"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "cliproxyapi"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/src/apply.ts

@@ -0,0 +1,209 @@
+// applyAll: take a fully-loaded config + a fresh Discovery and call
+// pi.registerProvider for each enabled builtin + each custom provider.
+
+import type { Api } from "@earendil-works/pi-ai";
+import { getModels } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ProviderConfig,
+	ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+
+import { ALLOWED_APIS, baseUrlFor, modelDefaults } from "./compat.ts";
+import type { CustomProviderModelConfig, ProxyConfig } from "./config.ts";
+import { resolveConfigValue } from "./config.ts";
+import type { Discovery, DiscoveryCustomEntry } from "./fetch-models.ts";
+import { discoveryToIdSet } from "./fetch-models.ts";
+import { log } from "./log.ts";
+
+export interface ApplyReport {
+	registered: Array<{ provider: string; modelCount: number; api: Api }>;
+	skipped: Array<{ provider: string; reason: string }>;
+}
+
+export async function applyAll(
+	pi: ExtensionAPI,
+	cfg: ProxyConfig,
+	discovery: Discovery,
+): Promise<ApplyReport> {
+	const report: ApplyReport = { registered: [], skipped: [] };
+	const proxyIds = discoveryToIdSet(discovery);
+	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
+	if (!resolvedKey) {
+		log.warn(
+			"proxy apiKey is empty — pi.registerProvider calls will be skipped",
+		);
+		return report;
+	}
+
+	// -------- builtin providers (anthropic, openai, etc.)
+	for (const [name, p] of Object.entries(cfg.builtinProviders)) {
+		if (!p?.enabled) {
+			report.skipped.push({ provider: name, reason: "disabled" });
+			continue;
+		}
+		if (!Array.isArray(p.models) || p.models.length === 0) {
+			report.skipped.push({ provider: name, reason: "empty whitelist" });
+			continue;
+		}
+		let builtin: ReadonlyArray<{
+			id: string;
+			name: string;
+			api: Api;
+			reasoning: boolean;
+			input: ("text" | "image")[];
+			cost: any;
+			contextWindow: number;
+			maxTokens: number;
+			thinkingLevelMap?: any;
+		}>;
+		try {
+			builtin = getModels(name as any) as any;
+		} catch {
+			report.skipped.push({
+				provider: name,
+				reason: `pi-ai has no provider "${name}"`,
+			});
+			continue;
+		}
+		const selected = builtin.filter(
+			(m) => p.models.includes(m.id) && proxyIds.has(m.id),
+		);
+		if (selected.length === 0) {
+			report.skipped.push({
+				provider: name,
+				reason: "no whitelisted models present on proxy",
+			});
+			continue;
+		}
+		const api: Api = (p.apiOverride ?? selected[0]!.api) as Api;
+		if (!ALLOWED_APIS.has(api)) {
+			report.skipped.push({
+				provider: name,
+				reason: `api "${api}" not in allowlist`,
+			});
+			continue;
+		}
+		const modelDefs: ProviderModelConfig[] = selected.map((m) => {
+			const ov = cfg.overrides[m.id] ?? {};
+			const base: ProviderModelConfig = {
+				id: m.id,
+				name: typeof ov.name === "string" ? ov.name : m.name,
+				api,
+				reasoning:
+					typeof ov.reasoning === "boolean" ? ov.reasoning : m.reasoning,
+				input: m.input,
+				cost: ov.cost ?? m.cost,
+				contextWindow:
+					typeof ov.contextWindow === "number"
+						? ov.contextWindow
+						: m.contextWindow,
+				maxTokens:
+					typeof ov.maxTokens === "number" ? ov.maxTokens : m.maxTokens,
+			};
+			if (m.thinkingLevelMap) base.thinkingLevelMap = m.thinkingLevelMap;
+			return base;
+		});
+		const providerConfig: ProviderConfig = {
+			name,
+			baseUrl: baseUrlFor(api, cfg.proxy.endpoint),
+			apiKey: resolvedKey,
+			authHeader: true,
+			api,
+			models: modelDefs,
+		};
+		pi.registerProvider(name, providerConfig);
+		report.registered.push({
+			provider: name,
+			modelCount: modelDefs.length,
+			api,
+		});
+	}
+
+	// -------- custom providers
+	const proxyCustomById = new Map<string, DiscoveryCustomEntry>(
+		discovery.customPool.map((m) => [m.id, m]),
+	);
+	for (const [name, c] of Object.entries(cfg.customProviders)) {
+		if (!ALLOWED_APIS.has(c.api)) {
+			report.skipped.push({
+				provider: name,
+				reason: `api "${c.api}" not in allowlist`,
+			});
+			continue;
+		}
+		const present: CustomProviderModelConfig[] = c.models.filter((m) =>
+			proxyIds.has(m.id),
+		);
+		if (present.length === 0) {
+			report.skipped.push({
+				provider: name,
+				reason: "no configured models present on proxy",
+			});
+			continue;
+		}
+		const modelDefs: ProviderModelConfig[] = present.map((m) => {
+			const fromPool = proxyCustomById.get(m.id);
+			const base = modelDefaults(m.id);
+			const ov = cfg.overrides[m.id] ?? {};
+			return {
+				id: m.id,
+				name: m.name ?? fromPool?.name ?? base.name ?? m.id,
+				api: c.api,
+				reasoning:
+					pickBool(
+						m.reasoning,
+						fromPool?.reasoning,
+						base.reasoning,
+						ov.reasoning,
+					) ?? false,
+				input: ["text"],
+				cost: m.cost ??
+					fromPool?.cost ??
+					base.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow:
+					pickNum(
+						m.contextWindow,
+						fromPool?.contextWindow,
+						base.contextWindow,
+						ov.contextWindow,
+					) ?? 128000,
+				maxTokens:
+					pickNum(
+						m.maxTokens,
+						fromPool?.maxTokens,
+						base.maxTokens,
+						ov.maxTokens,
+					) ?? 16000,
+			};
+		});
+		const providerConfig: ProviderConfig = {
+			name,
+			baseUrl: baseUrlFor(c.api, cfg.proxy.endpoint),
+			apiKey: resolvedKey,
+			authHeader: true,
+			api: c.api,
+			models: modelDefs,
+		};
+		pi.registerProvider(name, providerConfig);
+		report.registered.push({
+			provider: name,
+			modelCount: modelDefs.length,
+			api: c.api,
+		});
+	}
+
+	log.info(
+		`applyAll: registered ${report.registered.length} providers, skipped ${report.skipped.length}`,
+	);
+	return report;
+}
+
+function pickNum(...vals: Array<number | undefined>): number | undefined {
+	for (const v of vals) if (typeof v === "number") return v;
+	return undefined;
+}
+function pickBool(...vals: Array<boolean | undefined>): boolean | undefined {
+	for (const v of vals) if (typeof v === "boolean") return v;
+	return undefined;
+}

package/src/commands.ts

@@ -0,0 +1,247 @@
+// Slash commands.
+//   /cliproxy           — open the picker overlay
+//   /cliproxy-setup     — first-run / re-run setup wizard for endpoint+keys
+//   /cliproxy-refresh   — refetch discovery + re-apply
+//   /cliproxy-list      — show all upstream models in an overlay
+//   /cliproxy-usage     — fetch /api/usage and render in overlay
+//   /cliproxy-doctor    — connectivity + key-resolution diagnostics
+
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+import { applyAll } from "./apply.ts";
+import { loadConfig, resolveConfigValue, saveConfig } from "./config.ts";
+import { detectConflicts } from "./conflicts.ts";
+import { fetchDiscovery, PLUGIN_USER_AGENT } from "./fetch-models.ts";
+import { clearUsageCache, fetchUsage } from "./fetch-usage.ts";
+import { log } from "./log.ts";
+import { showOverlay } from "./ui-overlay.ts";
+import { runPicker } from "./ui-picker.ts";
+import { runSetup } from "./ui-setup.ts";
+import { renderUsage } from "./ui-usage.ts";
+
+export function registerCommands(pi: ExtensionAPI): void {
+	pi.registerCommand("cliproxy", {
+		description:
+			"Pick which models to expose via the CliProxyAPI corporate proxy",
+		handler: handleCliproxy.bind(null, pi),
+	});
+
+	pi.registerCommand("cliproxy-setup", {
+		description:
+			"Set endpoint, API key, and (optional) usage key for the proxy",
+		handler: handleSetup.bind(null, pi),
+	});
+
+	pi.registerCommand("cliproxy-refresh", {
+		description:
+			"Re-fetch upstream model list and re-apply provider registrations",
+		handler: handleRefresh.bind(null, pi),
+	});
+
+	pi.registerCommand("cliproxy-list", {
+		description: "Show every upstream model in a scrollable overlay",
+		handler: handleList,
+	});
+
+	pi.registerCommand("cliproxy-usage", {
+		description: "Show per-account quota windows from the upstream",
+		handler: handleUsage,
+	});
+
+	pi.registerCommand("cliproxy-doctor", {
+		description: "Check connectivity, key resolution, and discovery shape",
+		handler: handleDoctor,
+	});
+}
+
+// --------------------------------------------------------------------------- /cliproxy
+
+async function handleCliproxy(
+	pi: ExtensionAPI,
+	_args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const cfg = loadConfig();
+	if (!cfg.proxy.endpoint || !resolveConfigValue(cfg.proxy.apiKey)) {
+		ctx.ui.notify(
+			"endpoint or API key not set \u2014 launching /cliproxy-setup first",
+			"info",
+		);
+		const ok = await runSetup(ctx, true);
+		if (!ok) return;
+	}
+	const current = loadConfig();
+	const resolvedKey = resolveConfigValue(current.proxy.apiKey);
+	let discovery;
+	try {
+		discovery = await fetchDiscovery(current, resolvedKey);
+	} catch (err) {
+		ctx.ui.notify(`discovery failed: ${(err as Error).message}`, "error");
+		return;
+	}
+	const updated = await runPicker(ctx, current, discovery);
+	if (!updated) {
+		ctx.ui.notify("changes discarded", "info");
+		return;
+	}
+	saveConfig(updated);
+	const rep = await applyAll(pi, updated, discovery);
+	ctx.ui.notify(
+		`saved \u00b7 ${rep.registered.length} providers registered, ${rep.skipped.length} skipped`,
+		"info",
+	);
+}
+
+// --------------------------------------------------------------------------- /cliproxy-setup
+
+async function handleSetup(
+	pi: ExtensionAPI,
+	_args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const ok = await runSetup(ctx, true);
+	if (!ok) return;
+	// After saving, eagerly reapply so the new endpoint/key actually takes effect.
+	const cfg = loadConfig();
+	try {
+		const discovery = await fetchDiscovery(
+			cfg,
+			resolveConfigValue(cfg.proxy.apiKey),
+		);
+		const rep = await applyAll(pi, cfg, discovery);
+		clearUsageCache();
+		ctx.ui.notify(
+			`setup ok \u00b7 ${rep.registered.length} providers registered (source=${discovery.source})`,
+			"info",
+		);
+	} catch (err) {
+		ctx.ui.notify(
+			`setup saved, but apply failed: ${(err as Error).message}`,
+			"warning",
+		);
+	}
+}
+
+// --------------------------------------------------------------------------- /cliproxy-refresh
+
+async function handleRefresh(
+	pi: ExtensionAPI,
+	_args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const cfg = loadConfig();
+	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
+	try {
+		const discovery = await fetchDiscovery(cfg, resolvedKey);
+		const rep = await applyAll(pi, cfg, discovery);
+		clearUsageCache();
+		ctx.ui.notify(
+			`cliproxy: ${rep.registered.length} providers registered, ${rep.skipped.length} skipped (source=${discovery.source})`,
+			"info",
+		);
+	} catch (err) {
+		ctx.ui.notify(`refresh failed: ${(err as Error).message}`, "error");
+	}
+}
+
+// --------------------------------------------------------------------------- /cliproxy-list
+
+async function handleList(
+	_args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const cfg = loadConfig();
+	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
+	let discovery;
+	try {
+		discovery = await fetchDiscovery(cfg, resolvedKey);
+	} catch (err) {
+		ctx.ui.notify(`list failed: ${(err as Error).message}`, "error");
+		return;
+	}
+	await runPicker(ctx, cfg, discovery, {
+		readOnly: true,
+		title: " /cliproxy-list \u00b7 read-only ",
+	});
+}
+
+// --------------------------------------------------------------------------- /cliproxy-usage
+
+async function handleUsage(
+	args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const force = /(^|\s)--refresh(\s|$)/.test(args);
+	const cfg = loadConfig();
+	const usageKey = resolveConfigValue(cfg.proxy.usageKey);
+	let doc;
+	try {
+		doc = await fetchUsage(cfg, usageKey, { force });
+	} catch (err) {
+		ctx.ui.notify(`usage failed: ${(err as Error).message}`, "error");
+		return;
+	}
+	await showOverlay(ctx, "cliproxy-usage", {
+		render: (state) =>
+			renderUsage(doc, {
+				showDisabled: state["d"] === true,
+				verbose: state["v"] === true,
+			}).join("\n"),
+		toggles: [
+			{ key: "d", hint: "d disabled" },
+			{ key: "v", hint: "v verbose" },
+		],
+	});
+}
+
+// --------------------------------------------------------------------------- /cliproxy-doctor
+
+async function handleDoctor(
+	_args: string,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const cfg = loadConfig();
+	const lines: string[] = [];
+	lines.push(`endpoint: ${cfg.proxy.endpoint}`);
+	lines.push(
+		`apiKey resolves: ${resolveConfigValue(cfg.proxy.apiKey) ? "yes" : "NO (empty after resolution)"}`,
+	);
+	lines.push(
+		`usageKey resolves: ${cfg.proxy.usageKey ? (resolveConfigValue(cfg.proxy.usageKey) ? "yes" : "NO") : "not configured"}`,
+	);
+	lines.push(`user-agent: ${PLUGIN_USER_AGENT}`);
+
+	try {
+		const discovery = await fetchDiscovery(
+			cfg,
+			resolveConfigValue(cfg.proxy.apiKey),
+		);
+		lines.push("");
+		lines.push(`discovery source: ${discovery.source}`);
+		lines.push(`upstream version: ${discovery.upstreamVersion ?? "(unknown)"}`);
+		lines.push(`upstream total ids: ${discovery.upstreamTotal}`);
+		lines.push(
+			`built-in providers seen: ${discovery.builtinProviders.map((p) => `${p.name}=${p.models.length}`).join(", ") || "(none)"}`,
+		);
+		lines.push(`custom pool size: ${discovery.customPool.length}`);
+	} catch (err) {
+		lines.push("");
+		lines.push(`discovery FAILED: ${(err as Error).message}`);
+	}
+
+	const conflicts = detectConflicts(cfg);
+	if (conflicts.length > 0) {
+		lines.push("");
+		lines.push("conflicts:");
+		for (const c of conflicts) lines.push(`  [${c.kind}] ${c.detail}`);
+	} else {
+		lines.push("");
+		lines.push("conflicts: none");
+	}
+
+	log.info("doctor:", lines.join(" | "));
+	await showOverlay(ctx, "cliproxy-doctor", lines.join("\n"));
+}