pi-cliproxyapi 0.2.0 → 0.3.1

package/README.md

@@ -1,3 +1,12 @@
+```
+██████╗ ██╗     ██████╗██╗     ██╗██████╗ ██████╗  ██████╗ ██╗  ██╗██╗   ██╗
+██╔══██╗██║    ██╔════╝██║     ██║██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝╚██╗ ██╔╝
+██████╔╝██║    ██║     ██║     ██║██████╔╝██████╔╝██║   ██║ ╚███╔╝  ╚████╔╝
+██╔═══╝ ██║    ██║     ██║     ██║██╔═══╝ ██╔══██╗██║   ██║ ██╔██╗   ╚██╔╝
+██║     ██║    ╚██████╗███████╗██║██║     ██║  ██║╚██████╔╝██╔╝ ██╗   ██║
+╚═╝     ╚═╝     ╚═════╝╚══════╝╚═╝╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝
+```
+
 # pi-cliproxyapi
 
 [![npm](https://img.shields.io/npm/v/pi-cliproxyapi)](https://www.npmjs.com/package/pi-cliproxyapi)
@@ -7,39 +16,62 @@ Pi extension for corporate management of model providers via a single [CliProxyA
 
 One `(endpoint, apiKey)` pair — every provider and model inherits it automatically.
 
+![pi-cliproxyapi — the /cliproxy hub, Models tab](docs/pi-cliproxyapi-1.png)
+
 ## Features
 
+- **Unified hub** — one `/cliproxy` overlay with **Models / Usage / Diagnostics** tabs (number hotkeys `1` `2` `3`) plus global actions: `r` refresh, `e` setup, `s` save
 - **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
+- **Exclusive model pool** — a model assigned to one group automatically disappears from others, grouped by `owned_by` with type-to-filter (`/`)
+- **Live save state** — the header shows `● unsaved` while you edit and `✓ settings saved` after `s`, no console noise
+- **Per-account usage tab** — 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
 
+Two commands; everything else lives inside the hub as tabs and actions.
+
 | Command | Description |
 | --- | --- |
-| `/cliproxy` | Three-panel picker — providers, assigned models, available pool |
+| `/cliproxy` | Hub overlay — **Models** / **Usage** / **Diagnostics** tabs plus global actions |
 | `/cliproxy-setup` | Configure endpoint, API key, provider prefix, usage key |
-| `/cliproxy-refresh` | Re-fetch upstream models, re-register providers |
-| `/cliproxy-usage` | Per-account quota windows with progress bars (`d` = show disabled, `v` = verbose) |
-| `/cliproxy-doctor` | Connectivity, key resolution, discovery diagnostics |
 
-### `/cliproxy` picker
+### The `/cliproxy` hub
+
+Global keys: `[` / `]` or `1` `2` `3` switch tabs · `r` refresh discovery + reapply · `e` setup · `s` save · `q` / `Esc` close.
 
-The picker has three panels you cycle through with `Tab` / arrow keys:
+**Models tab** — three panels cycled with `Tab` / arrows:
 
 - **left** — every provider (built-in + custom). `+ new custom group…` is the last row.
-- **right top** — models currently assigned to the focused provider. `Enter` / `Space` removes one.
-- **right bottom** — available model pool, grouped by upstream `owned_by`. `Enter` / `Space` attaches a model to the focused provider.
+- **right top** — models assigned to the focused provider. `Enter` / `Space` removes one.
+- **right bottom** — available pool, grouped by upstream `owned_by`. `Enter` / `Space` attaches. Press `/` to filter the pool by id/name. A `⚠` marks an API mismatch (attach still allowed).
+
+Extra Models keys: `d` removes a custom group (with confirmation).
+
+**Usage tab** — per-account quota bars; `d` shows disabled accounts, `v` shows verbose errors.
+
+**Diagnostics tab** — connectivity, key resolution, and discovery shape.
+
+## Screenshots
+
+**Models — custom group, pool grouped by owner (`/` filters the pool)**
+
+![Models tab: custom proxy group with grouped available pool](docs/pi-cliproxyapi-2.png)
+
+**Usage — per-account quota windows**
+
+![Usage tab: per-account quota bars with reset windows](docs/pi-cliproxyapi-3.png)
+
+**Diagnostics — connectivity, keys, discovery shape**
 
-Extra keys: `d` removes a custom group (with confirmation), `s` saves, `q` / `Esc` cancels. A `⚠` marker shows when a model's recommended API differs from the provider's API — attach is allowed anyway.
+![Diagnostics tab: endpoint, key resolution, discovery and conflicts](docs/pi-cliproxyapi-4.png)
 
 ## Prerequisites
 
 You need a running [CliProxyAPI](https://github.com/router-for-me/CLIProxyAPI) instance — this is the corporate LLM proxy that aggregates multiple providers behind a single OpenAI-compatible endpoint.
 
-For full functionality (`/cliproxy-usage`, enriched model metadata from [models.dev](https://models.dev)), also deploy the companion sidecar: **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)**. See [Deploying the sidecar](#deploying-the-sidecar-service) below.
+For full functionality (Usage tab, enriched model metadata from [models.dev](https://models.dev)), also deploy the companion sidecar: **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)**. See [Deploying the sidecar](#deploying-the-sidecar-service) below.
 
 ## Install
 
@@ -85,18 +117,18 @@ The plugin tries `GET <endpoint-origin>/.well-known/pi` first (requires the side
 The **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)** sidecar runs alongside CliProxyAPI and provides:
 
 - `/.well-known/pi` — model discovery with metadata from [models.dev](https://models.dev) (context windows, costs, reasoning flags)
-- `/api/usage` — per-account quota windows used by `/cliproxy-usage`
+- `/api/usage` — per-account quota windows used by the hub Usage tab
 
 ```
 ┌──────────────┐     ┌───────────────────────────┐
-│  Pi + plugin  │────▶│  CliProxyAPI (:8317)       │
-│               │     │  /v1/models, /v1/chat/...  │
-│               │     └───────────────────────────┘
-│               │     ┌───────────────────────────┐
-│               │────▶│  wellknown sidecar (:3458)  │
-│               │     │  /.well-known/pi            │
-│               │     │  /api/usage                 │
-│               │     └───────────────────────────┘
+│  Pi + plugin │────▶│  CliProxyAPI (:8317)      │
+│              │     │  /v1/models, /v1/chat/... │
+│              │     └───────────────────────────┘
+│              │     ┌───────────────────────────┐
+│              │────▶│  wellknown sidecar (:3458)│
+│              │     │  /.well-known/pi          │
+│              │     │  /api/usage               │
+│              │     └───────────────────────────┘
 └──────────────┘
 ```
 
@@ -143,16 +175,16 @@ Run `/cliproxy-setup` in Pi and enter:
 - **endpoint** — your public proxy URL ending with `/v1`
 - **apiKey** — CliProxyAPI bearer key
 - **providerPrefix** — short slug for custom provider names (e.g. `corp`, `myproxy`)
-- **usageKey** — same value as `PI_PLUGIN_USAGE_KEY` above (enables `/cliproxy-usage`)
+- **usageKey** — same value as `PI_PLUGIN_USAGE_KEY` above (enables the Usage tab)
 
 The sidecar is **optional for basic usage** — without it the plugin falls back to raw `/v1/models` with local heuristics. What changes:
 
 | | With sidecar | Without sidecar |
 | --- | --- | --- |
 | Model discovery | Enriched from [models.dev](https://models.dev) (real context windows, costs, reasoning) | Defaults: `contextWindow=128k`, `maxTokens=16k`, `cost=0`, `reasoning=false` |
-| `/cliproxy-usage` | Works — per-account quota bars | **Does not work** (no `/api/usage` endpoint) |
+| Usage tab | Works — per-account quota bars | **Does not work** (no `/api/usage` endpoint) |
 | Classification | Server-side, accurate | Local heuristics by `owned_by` |
-| `/cliproxy`, `/cliproxy-doctor` | Work | Work |
+| `/cliproxy` hub | Works | Works (Usage tab shows an error) |
 
 ## Layout
 
@@ -160,26 +192,30 @@ The sidecar is **optional for basic usage** — without it the plugin falls back
 index.ts            ExtensionFactory entry point
 src/
   config.ts         ~/.config/pi-cliproxyapi/config.json
-  commands.ts       5 slash commands
+  commands.ts       2 slash commands (hub + setup)
   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-frame.ts       single source of truth for overlay frames
-  ui-overlay.ts     scrollable overlay shell with toggles
   ui-setup.ts       setup wizard
   ui-usage.ts       ANSI-coloured usage renderer
-  ui-picker/        three-panel /cliproxy overlay
-    index.ts        public runPicker entry
+  ui-hub/           the /cliproxy hub overlay
+    index.ts        public runHub entry
+    hub.ts          tabs, status header, global actions
+    types.ts        HubView contract
+    shell.ts        tab bar, status header, scroll/slice helpers
+    view-models.ts  three-panel picker (single pool ordering + filter)
+    view-usage.ts   usage tab (lazy fetch + d/v toggles)
+    view-diagnostics.ts  diagnostics tab
+  ui-picker/        picker building blocks reused by the Models view
     types.ts        shared TS types
     catalog.ts      build a model lookup from discovery
     providers.ts    resolve the providers shown in the left panel
-    mutate.ts       attach / detach / claim helpers + pool grouping
+    mutate.ts       attach / detach / claim + pool grouping + display order
     render-text.ts  ANSI-aware pad / truncate
     rows.ts         per-row renderers for left / right panels
-    picker.ts       state + navigation, glues catalogue to UI
-    picker-component.ts  render + input dispatch
     prompt-confirm.ts    remove-group confirmation
     prompt-name.ts       new-group name prompt
   log.ts            tagged logger

package/index.ts

@@ -6,8 +6,8 @@
  *   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-usage /cliproxy-doctor
+ *   4. register slash commands /cliproxy and /cliproxy-setup
+ *      (refresh, usage, and diagnostics are tabs/actions inside the hub)
  *
  * All discovery + apply errors are logged but never abort extension load —
  * a missing/broken proxy must not prevent Pi from starting.
@@ -43,7 +43,7 @@ export default async function cliproxyapi(pi: ExtensionAPI): Promise<void> {
 		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.
+		// Commands stay registered; user can open /cliproxy and press r to refresh.
 	}
 
 	if (cfg.refreshIntervalMinutes > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cliproxyapi",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Pi extension for corporate management of model providers via a single CliProxyAPI endpoint",
   "license": "MIT",

package/src/commands.ts

@@ -1,9 +1,8 @@
-// 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-usage     — fetch /api/usage and render in overlay
-//   /cliproxy-doctor    — connectivity + key-resolution diagnostics
+// Slash commands (2):
+//   /cliproxy         — open the hub (Models / Usage / Diagnostics + actions)
+//   /cliproxy-setup   — first-run / re-run wizard for endpoint+keys
+//
+// Refresh, usage, and diagnostics are now actions/tabs inside the hub.
 
 import type {
 	ExtensionAPI,
@@ -11,20 +10,16 @@ import type {
 } 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/index.ts";
+import { loadConfig, resolveConfigValue } from "./config.ts";
+import { fetchDiscovery } from "./fetch-models.ts";
+import { clearUsageCache } from "./fetch-usage.ts";
+import { runHub } from "./ui-hub/index.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",
+			"Manage proxy models, usage, and diagnostics in one hub overlay",
 		handler: handleCliproxy.bind(null, pi),
 	});
 
@@ -33,22 +28,6 @@ export function registerCommands(pi: ExtensionAPI): void {
 			"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-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
@@ -61,7 +40,7 @@ async function handleCliproxy(
 	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",
+			"endpoint or API key not set \u2014 launching setup first",
 			"info",
 		);
 		const ok = await runSetup(ctx, true);
@@ -76,17 +55,7 @@ async function handleCliproxy(
 		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",
-	);
+	await runHub(pi, ctx, current, discovery);
 }
 
 // --------------------------------------------------------------------------- /cliproxy-setup
@@ -118,103 +87,3 @@ async function handleSetup(
 		);
 	}
 }
-
-// --------------------------------------------------------------------------- /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-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"));
-}

package/src/fetch-models.ts

@@ -20,7 +20,7 @@ import {
 import type { ProxyConfig } from "./config.ts";
 import { log } from "./log.ts";
 
-export const PLUGIN_USER_AGENT = "pi-cliproxyapi/0.1.0";
+export const PLUGIN_USER_AGENT = "pi-cliproxyapi/0.3.1";
 const REQUEST_TIMEOUT_MS = 5_000;
 
 export interface DiscoveryModelEntry {
@@ -215,10 +215,7 @@ async function fetchRawModels(
 		.filter((m) => m.id);
 }
 
-function classifyLocally(
-	raw: RawUpstreamModel[],
-	cfg: ProxyConfig,
-): Discovery {
+function classifyLocally(raw: RawUpstreamModel[], cfg: ProxyConfig): Discovery {
 	const excludes = cfg.discoveryExcludes;
 	const builtinByName = new Map<string, DiscoveryBuiltinProvider>();
 	const customPool: DiscoveryCustomEntry[] = [];

package/src/log.ts

@@ -1,19 +1,32 @@
 // Tiny logger that prefixes all messages with the extension tag.
 // Uses console.* directly — pi pipes stdout/stderr into its log sink.
+//
+// While an interactive overlay is open, console output corrupts the TUI (it
+// prints over the box and forces a redraw below it — stacking headers). The
+// overlay code wraps its lifetime in setLogQuiet(true) to mute us; user-facing
+// results are surfaced inside the overlay instead.
 
 const TAG = "[pi-cliproxyapi]";
 
+let quiet = false;
+
+/** Mute/unmute all console output (used around interactive overlays). */
+export function setLogQuiet(v: boolean): void {
+	quiet = v;
+}
+
 export const log = {
 	info(...args: unknown[]): void {
-		console.log(TAG, ...args);
+		if (!quiet) console.log(TAG, ...args);
 	},
 	warn(...args: unknown[]): void {
-		console.warn(TAG, ...args);
+		if (!quiet) console.warn(TAG, ...args);
 	},
 	error(...args: unknown[]): void {
-		console.error(TAG, ...args);
+		if (!quiet) console.error(TAG, ...args);
 	},
 	debug(...args: unknown[]): void {
-		if (process.env.PI_CLIPROXYAPI_DEBUG) console.log(TAG, "[debug]", ...args);
+		if (!quiet && process.env.PI_CLIPROXYAPI_DEBUG)
+			console.log(TAG, "[debug]", ...args);
 	},
 };