pi-cliproxyapi-autoconnect 0.0.0-stage → 1.2.1

package/index.ts

@@ -0,0 +1,1313 @@
+/**
+ * pi-cliproxyapi-autoconnect — CLIProxyAPI provider for pi
+ *
+ * Adds a "CLIProxy" entry to pi's /login flow (under "Sign in with an API key"):
+ *   1. ask for the bound domain (for example proxy.example.com)
+ *   2. ask for the API key
+ *   3. derive every compatible base URL and try them automatically,
+ *      OpenAI first, then Gemini, then Anthropic
+ *   4. register every returned model in /model
+ *
+ * If model discovery fails everywhere, the user picks one of the formatted
+ * compatible addresses (OpenAI / Anthropic / Gemini) or enters a custom base
+ * URL, and can type model IDs manually.
+ *
+ * The API key is stored by pi in ~/.pi/agent/auth.json. This extension only
+ * stores non-secret connection metadata in ~/.pi/agent/cliproxy.json.
+ *
+ * CLIProxyAPI reference: https://github.com/router-for-me/CLIProxyAPI
+ */
+
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	anthropicMessagesApi,
+	createProvider,
+	googleGenerativeAIApi,
+	openAICompletionsApi,
+	type Api,
+	type ApiKeyCredential,
+	type Model,
+	type Provider,
+	type ProviderAuthInteraction,
+	type ProviderStreams,
+	type RefreshModelsContext,
+} from "@earendil-works/pi-ai/compat";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const PROVIDER_ID = "cliproxy";
+const PROVIDER_NAME = "CLIProxy";
+const AUTH_NAME = "CLIProxy (domain + API key)";
+const CONFIG_FILE_NAME = "cliproxy.json";
+const CONFIG_VERSION = 2;
+const REQUEST_TIMEOUT_MS = 10_000;
+const PROBE_TIMEOUT_MS = 4_000;
+/** Reuse a fresh catalog for a few minutes unless a refresh is forced. */
+const MODEL_REFRESH_TTL_MS = 5 * 60_000;
+
+/** Last non-fatal error from a background model refresh, used by /cliproxy. */
+let lastRefreshError: string | undefined;
+
+type SupportedApi = "openai-completions" | "anthropic-messages" | "google-generative-ai";
+
+const PROVIDER_APIS: Readonly<Record<SupportedApi, string>> = {
+	"openai-completions": "OpenAI compatible",
+	"anthropic-messages": "Anthropic compatible",
+	"google-generative-ai": "Gemini compatible",
+};
+
+// =============================================================================
+// Persisted configuration (never contains the API key)
+// =============================================================================
+
+interface StoredModel {
+	/** Upstream model ID exactly as returned by the proxy. */
+	id: string;
+	/** Optional display name. */
+	name?: string;
+	/** Optional upstream owner reported by /v1/models. */
+	ownedBy?: string;
+	/** Persisted capability metadata, so cliproxy.json is self-contained. */
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+interface CliproxyConfig {
+	version: number;
+	/** Domain exactly as the user typed it. */
+	domain: string;
+	/** Normalized root URL without a compatibility suffix, e.g. https://proxy.example.com */
+	rootUrl: string;
+	/** Base URL used by pi for every model, e.g. https://proxy.example.com/v1 */
+	baseUrl: string;
+	/** Wire protocol used by the configured base URL. */
+	api: SupportedApi;
+	models: StoredModel[];
+	/** Whether models came from automatic discovery or from manual IDs. */
+	source: "auto" | "manual";
+	updatedAt: number;
+	lastError?: string;
+}
+
+interface NormalizedDomain {
+	rootUrl: string;
+	implicitScheme: boolean;
+}
+
+/** One derivable compatible address, in the order it should be probed. */
+interface DiscoveryCandidate {
+	api: SupportedApi;
+	rootUrl: string;
+	baseUrl: string;
+}
+
+interface DiscoveryAttempt {
+	candidate: DiscoveryCandidate;
+	failure: FetchFailure;
+}
+
+type DiscoveryOutcome =
+	| { ok: true; candidate: DiscoveryCandidate; models: StoredModel[] }
+	| { ok: false; attempts: DiscoveryAttempt[]; empty?: DiscoveryCandidate };
+
+interface FetchedModels {
+	ok: true;
+	models: StoredModel[];
+}
+
+interface FetchFailure {
+	ok: false;
+	error: string;
+	kind: "auth" | "forbidden" | "not-found" | "server" | "network" | "format" | "http" | "unsupported";
+	status?: number;
+}
+
+type FetchResult = FetchedModels | FetchFailure;
+
+/** Capability metadata borrowed from an existing models.json entry with the same model ID. */
+interface ModelMetadata {
+	name?: string;
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+let metadataCache: { path: string; mtimeMs: number; metadata: Map<string, ModelMetadata> } | undefined;
+let storeMetadataCache: { path: string; mtimeMs: number; metadata: Map<string, ModelMetadata> } | undefined;
+let builtinMetadataCache: Map<string, ModelMetadata> | undefined;
+
+// =============================================================================
+// Config file
+// =============================================================================
+
+function configPath(): string {
+	return join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+function isSupportedApi(value: unknown): value is SupportedApi {
+	return value === "openai-completions" || value === "anthropic-messages" || value === "google-generative-ai";
+}
+
+function sanitizeModels(value: unknown): StoredModel[] {
+	if (!Array.isArray(value)) return [];
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object") continue;
+		const record = entry as Record<string, unknown>;
+		const id = typeof record.id === "string" ? record.id.trim() : "";
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const name = typeof record.name === "string" && record.name.trim() ? record.name.trim() : undefined;
+		const ownedBy = typeof record.ownedBy === "string" && record.ownedBy.trim() ? record.ownedBy.trim() : undefined;
+		const reasoning = typeof record.reasoning === "boolean" ? record.reasoning : undefined;
+		const input = Array.isArray(record.input)
+			? record.input.filter((value): value is "text" | "image" => value === "text" || value === "image")
+			: undefined;
+		const cost = readMetadataCost(record.cost);
+		const contextWindow =
+			typeof record.contextWindow === "number" && record.contextWindow > 0 ? record.contextWindow : undefined;
+		const maxTokens =
+			typeof record.maxTokens === "number" && record.maxTokens > 0 ? record.maxTokens : undefined;
+		models.push({
+			id,
+			...(name ? { name } : {}),
+			...(ownedBy ? { ownedBy } : {}),
+			...(reasoning !== undefined ? { reasoning } : {}),
+			...(input && input.length > 0 ? { input } : {}),
+			...(cost ? { cost } : {}),
+			...(contextWindow ? { contextWindow } : {}),
+			...(maxTokens ? { maxTokens } : {}),
+		});
+	}
+	return models;
+}
+
+function readConfig(): CliproxyConfig | undefined {
+	const path = configPath();
+	if (!existsSync(path)) return undefined;
+	try {
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		if (!parsed || typeof parsed !== "object") return undefined;
+		if (typeof parsed.rootUrl !== "string" || typeof parsed.baseUrl !== "string") return undefined;
+		if (!isSupportedApi(parsed.api)) return undefined;
+		const source = parsed.source === "manual" ? "manual" : "auto";
+		const lastError = typeof parsed.lastError === "string" && parsed.lastError ? parsed.lastError : undefined;
+		return {
+			version: typeof parsed.version === "number" ? parsed.version : CONFIG_VERSION,
+			domain: typeof parsed.domain === "string" ? parsed.domain : parsed.rootUrl,
+			rootUrl: parsed.rootUrl,
+			baseUrl: parsed.baseUrl,
+			api: parsed.api,
+			models: sanitizeModels(parsed.models),
+			source,
+			updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0,
+			...(lastError ? { lastError } : {}),
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function writeConfig(config: CliproxyConfig): void {
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	// Keep one previous generation for manual recovery.
+	if (existsSync(path)) {
+		try {
+			copyFileSync(path, `${path}.bak`);
+		} catch {
+			// Backups are best effort; never fail the actual write because of one.
+		}
+	}
+	const data = `${JSON.stringify(config, null, 2)}\n`;
+	const temporaryPath = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporaryPath, data, { encoding: "utf8", mode: 0o600 });
+	try {
+		renameSync(temporaryPath, path);
+	} catch {
+		// Windows can refuse to replace an existing file while another process holds it.
+		writeFileSync(path, data, { encoding: "utf8", mode: 0o600 });
+		try {
+			unlinkSync(temporaryPath);
+		} catch {
+			// Best effort only.
+		}
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from models.json
+// =============================================================================
+
+function readMetadataCost(value: unknown): ModelMetadata["cost"] | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	const input = record.input;
+	const output = record.output;
+	const cacheRead = record.cacheRead;
+	const cacheWrite = record.cacheWrite;
+	if (typeof input !== "number" || typeof output !== "number") return undefined;
+	return {
+		input,
+		output,
+		cacheRead: typeof cacheRead === "number" ? cacheRead : 0,
+		cacheWrite: typeof cacheWrite === "number" ? cacheWrite : 0,
+	};
+}
+
+/**
+ * CLIProxyAPI's /v1/models only returns model IDs. If the user already has a
+ * models.json entry for the same ID (for example a hand-written provider that
+ * points at the same proxy), reuse its capability metadata instead of the
+ * conservative guesses below.
+ */
+function readModelsJsonMetadata(): Map<string, ModelMetadata> {
+	const path = join(getAgentDir(), "models.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		if (metadataCache && metadataCache.path === path && metadataCache.mtimeMs === mtimeMs) {
+			return metadataCache.metadata;
+		}
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const providers =
+			parsed.providers && typeof parsed.providers === "object"
+				? (parsed.providers as Record<string, unknown>)
+				: parsed;
+		const metadata = new Map<string, ModelMetadata>();
+		for (const provider of Object.values(providers)) {
+			if (!provider || typeof provider !== "object") continue;
+			const models = (provider as Record<string, unknown>).models;
+			if (!Array.isArray(models)) continue;
+			for (const value of models) {
+				if (!value || typeof value !== "object") continue;
+				const model = value as Record<string, unknown>;
+				if (typeof model.id !== "string" || !model.id.trim()) continue;
+				if (typeof model.type === "string" && model.type !== "chat") continue;
+				const id = model.id.trim();
+				if (metadata.has(id)) continue;
+				const entry: ModelMetadata = {};
+				if (typeof model.name === "string" && model.name.trim()) entry.name = model.name.trim();
+				if (typeof model.reasoning === "boolean") entry.reasoning = model.reasoning;
+				if (Array.isArray(model.input)) {
+					const input = model.input.filter(
+						(value): value is "text" | "image" => value === "text" || value === "image",
+					);
+					if (input.length > 0) entry.input = input;
+				}
+				const cost = readMetadataCost(model.cost);
+				if (cost) entry.cost = cost;
+				if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
+					entry.contextWindow = model.contextWindow;
+				}
+				if (typeof model.maxTokens === "number" && model.maxTokens > 0) {
+					entry.maxTokens = model.maxTokens;
+				}
+				if (Object.keys(entry).length > 0) metadata.set(id, entry);
+			}
+		}
+		metadataCache = { path, mtimeMs, metadata };
+		return metadata;
+	} catch {
+		if (metadataCache?.path === path) return metadataCache.metadata;
+		return new Map();
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from pi's models-store cache
+// =============================================================================
+
+function readModelsStoreMetadata(): Map<string, ModelMetadata> {
+	const path = join(getAgentDir(), "models-store.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		if (storeMetadataCache && storeMetadataCache.path === path && storeMetadataCache.mtimeMs === mtimeMs) {
+			return storeMetadataCache.metadata;
+		}
+		let raw = readFileSync(path, "utf8");
+		if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+		const parsed = JSON.parse(raw) as Record<string, unknown>;
+		const providerEntry = parsed[PROVIDER_ID];
+		const models =
+			providerEntry && typeof providerEntry === "object"
+				? (providerEntry as Record<string, unknown>).models
+				: undefined;
+		const metadata = new Map<string, ModelMetadata>();
+		if (Array.isArray(models)) {
+			for (const value of models) {
+				if (!value || typeof value !== "object") continue;
+				const model = value as Record<string, unknown>;
+				if (typeof model.id !== "string" || !model.id.trim()) continue;
+				if (typeof model.type === "string" && model.type !== "chat") continue;
+				const id = model.id.trim();
+				const entry: ModelMetadata = {};
+				if (typeof model.name === "string" && model.name.trim()) entry.name = model.name.trim();
+				if (typeof model.reasoning === "boolean") entry.reasoning = model.reasoning;
+				if (Array.isArray(model.input)) {
+					const input = model.input.filter(
+						(value): value is "text" | "image" => value === "text" || value === "image",
+					);
+					if (input.length > 0) entry.input = input;
+				}
+				const cost = readMetadataCost(model.cost);
+				if (cost) entry.cost = cost;
+				if (typeof model.contextWindow === "number" && model.contextWindow > 0) {
+					entry.contextWindow = model.contextWindow;
+				}
+				if (typeof model.maxTokens === "number" && model.maxTokens > 0) {
+					entry.maxTokens = model.maxTokens;
+				}
+				if (Object.keys(entry).length > 0) metadata.set(id, entry);
+			}
+		}
+		storeMetadataCache = { path, mtimeMs, metadata };
+		return metadata;
+	} catch {
+		if (storeMetadataCache?.path === path) return storeMetadataCache.metadata;
+		return new Map();
+	}
+}
+
+// =============================================================================
+// Optional metadata inheritance from pi's built-in catalog
+// =============================================================================
+
+function normalizeModelId(id: string): string {
+	// CLIProxy often exposes prefixes such as "global:", "cn:" or "models/".
+	return id
+		.trim()
+		.replace(/^models\//iu, "")
+		.replace(/^[a-z\d._-]+:/iu, "");
+}
+
+function readBuiltinMetadata(): Map<string, ModelMetadata> {
+	if (builtinMetadataCache) return builtinMetadataCache;
+	const metadata = new Map<string, ModelMetadata>();
+	try {
+		for (const provider of builtinProviders()) {
+			for (const model of provider.getModels()) {
+				if (model.type && model.type !== "chat") continue;
+				const entry: ModelMetadata = {
+					name: model.name,
+					reasoning: model.reasoning,
+					input: model.input,
+					cost: model.cost,
+					contextWindow: model.contextWindow,
+					maxTokens: model.maxTokens,
+				};
+				const normalized = normalizeModelId(model.id);
+				if (!metadata.has(model.id)) metadata.set(model.id, entry);
+				if (normalized && !metadata.has(normalized)) metadata.set(normalized, entry);
+			}
+		}
+	} catch {
+		// Built-in catalog is optional; heuristics remain available.
+	}
+	builtinMetadataCache = metadata;
+	return metadata;
+}
+
+// =============================================================================
+// Domain and URL formatting
+// =============================================================================
+
+function trimTrailingSlashes(value: string): string {
+	return value.replace(/\/+$/u, "");
+}
+
+function swapScheme(url: string): string | undefined {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol === "https:") {
+			parsed.protocol = "http:";
+			return trimTrailingSlashes(parsed.toString());
+		}
+		if (parsed.protocol === "http:") {
+			parsed.protocol = "https:";
+			return trimTrailingSlashes(parsed.toString());
+		}
+	} catch {
+		return undefined;
+	}
+	return undefined;
+}
+
+function isLocalHostname(hostname: string): boolean {
+	const host = hostname.toLowerCase();
+	return (
+		host === "localhost" ||
+		host === "127.0.0.1" ||
+		host === "::1" ||
+		host === "[::1]" ||
+		host.endsWith(".local") ||
+		host.endsWith(".lan") ||
+		/^127\./u.test(host) ||
+		/^10\./u.test(host) ||
+		/^192\.168\./u.test(host) ||
+		/^172\.(1[6-9]|2\d|3[01])\./u.test(host)
+	);
+}
+
+/**
+ * Accepts `proxy.example.com`, `https://proxy.example.com/`, a pasted
+ * `https://proxy.example.com/v1` or `.../v1/models`, and even a domain with a
+ * reverse-proxy path prefix. Returns the root URL used to derive compatible
+ * addresses.
+ */
+function normalizeDomain(input: string): NormalizedDomain {
+	const original = input.trim();
+	if (!original) throw new Error("Domain is required.");
+	const implicitScheme = !/^[a-z][a-z\d+.-]*:\/\//iu.test(original);
+	const withScheme = implicitScheme
+		? `${isLocalHostname(original.split("/")[0]?.split(":")[0] ?? "") ? "http" : "https"}://${original}`
+		: original;
+	let parsed: URL;
+	try {
+		parsed = new URL(withScheme);
+	} catch {
+		throw new Error(`Could not parse domain: "${input}". Example: proxy.example.com or https://proxy.example.com`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(`Only http/https URLs are supported; received: ${parsed.protocol}`);
+	}
+	parsed.username = "";
+	parsed.password = "";
+	parsed.hash = "";
+	parsed.search = "";
+	let pathname = parsed.pathname.replace(/\/+$/u, "");
+	// Users often paste the complete compatible URL instead of the domain.
+	pathname = pathname.replace(/\/v1(?:beta|alpha)?\/models$/iu, "");
+	pathname = pathname.replace(/\/models$/iu, "");
+	pathname = pathname.replace(/\/v1(?:beta|alpha)?$/iu, "");
+	parsed.pathname = pathname;
+	const rootUrl = trimTrailingSlashes(parsed.toString());
+	return { rootUrl, implicitScheme };
+}
+
+function openAIBaseUrl(rootUrl: string): string {
+	return `${trimTrailingSlashes(rootUrl)}/v1`;
+}
+
+function anthropicBaseUrl(rootUrl: string): string {
+	// The Anthropic SDK appends /v1/messages to this value.
+	return trimTrailingSlashes(rootUrl);
+}
+
+function geminiBaseUrl(rootUrl: string): string {
+	return `${trimTrailingSlashes(rootUrl)}/v1beta`;
+}
+
+// =============================================================================
+// Network helpers
+// =============================================================================
+
+function abortSignalWithTimeout(signal: AbortSignal, timeoutMs: number): { signal: AbortSignal; cleanup: () => void } {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new Error("Request timed out")), timeoutMs);
+	const onAbort = () => controller.abort(signal.reason);
+	if (signal.aborted) controller.abort(signal.reason);
+	else signal.addEventListener("abort", onAbort, { once: true });
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+		},
+	};
+}
+
+async function safeText(response: Response): Promise<string> {
+	try {
+		return (await response.text()).trim().slice(0, 500);
+	} catch {
+		return "";
+	}
+}
+
+function describeFetchError(error: unknown, ownSignal: AbortSignal, outerSignal: AbortSignal): string {
+	if (outerSignal.aborted) return "Cancelled";
+	if (ownSignal.aborted) return "Request timed out";
+	if (error instanceof Error) {
+		const cause = error.cause;
+		if (cause instanceof Error && cause.message && cause.message !== error.message) {
+			return `${error.message} (${cause.message})`;
+		}
+		return error.message;
+	}
+	return String(error);
+}
+
+function failureKindForStatus(status: number): FetchFailure["kind"] {
+	if (status === 401) return "auth";
+	if (status === 403) return "forbidden";
+	if (status === 404) return "not-found";
+	if (status === 429 || status >= 500) return "server";
+	return "http";
+}
+
+function makeHttpFailure(status: number, body: string): FetchFailure {
+	return {
+		ok: false,
+		error: `HTTP ${status}${body ? `: ${body}` : ""}`,
+		kind: failureKindForStatus(status),
+		status,
+	};
+}
+
+async function probeCliproxy(rootUrl: string, signal: AbortSignal): Promise<string | undefined> {
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, PROBE_TIMEOUT_MS);
+	try {
+		const response = await fetch(`${trimTrailingSlashes(rootUrl)}/healthz`, {
+			headers: { Accept: "application/json" },
+			signal: requestSignal,
+		});
+		if (!response.ok) return undefined;
+		const body = (await response.json().catch(() => undefined)) as { status?: unknown } | undefined;
+		if (body?.status === "ok") return "Detected CLIProxyAPI (/healthz OK)";
+		return "Detected /healthz, but the response is not CLIProxyAPI format";
+	} catch {
+		return undefined;
+	} finally {
+		cleanup();
+	}
+}
+
+function parseOpenAIModelList(payload: unknown): StoredModel[] | undefined {
+	if (!payload || typeof payload !== "object") return undefined;
+	const record = payload as Record<string, unknown>;
+	const entries = Array.isArray(record.data) ? record.data : Array.isArray(record.models) ? record.models : undefined;
+	if (!entries) return undefined;
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const entry of entries) {
+		if (typeof entry === "string") {
+			const id = entry.trim();
+			if (id && !seen.has(id)) {
+				seen.add(id);
+				models.push({ id });
+			}
+			continue;
+		}
+		if (!entry || typeof entry !== "object") continue;
+		const item = entry as Record<string, unknown>;
+		const rawId = typeof item.id === "string" ? item.id : typeof item.name === "string" ? item.name : "";
+		const id = rawId.trim().replace(/^models\//iu, "");
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const name =
+			typeof item.display_name === "string" && item.display_name.trim()
+				? item.display_name.trim()
+				: typeof item.displayName === "string" && item.displayName.trim()
+					? item.displayName.trim()
+					: undefined;
+		const ownedBy = typeof item.owned_by === "string" && item.owned_by.trim() ? item.owned_by.trim() : undefined;
+		models.push({ id, ...(name ? { name } : {}), ...(ownedBy ? { ownedBy } : {}) });
+	}
+	return models;
+}
+
+async function fetchOpenAIModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const url = `${trimTrailingSlashes(baseUrl)}/models`;
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, {
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"User-Agent": "pi-cliproxyapi-autoconnect/1.2.1",
+			},
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "Response is not an OpenAI-compatible model list (missing data array)", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+async function fetchGeminiModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const url = `${trimTrailingSlashes(baseUrl)}/models?key=${encodeURIComponent(apiKey)}`;
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(url, {
+			headers: { Accept: "application/json", "User-Agent": "pi-cliproxyapi-autoconnect/1.2.1" },
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "Response is not a Gemini-compatible model list (missing models array)", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+/**
+ * Anthropic's public API does expose GET /v1/models, but CLIProxyAPI's
+ * Anthropic-compatible endpoint does not always proxy it. Try anyway so the
+ * automatic discovery can use Anthropic when it is available; callers fall
+ * back to manual model IDs when it is not.
+ */
+function anthropicModelsUrl(baseUrl: string): string {
+	const root = trimTrailingSlashes(baseUrl);
+	// Anthropic's list endpoint paginates (default 20); ask for the largest page.
+	return /\/v1$/u.test(root) ? `${root}/models?limit=1000` : `${root}/v1/models?limit=1000`;
+}
+
+async function fetchAnthropicModels(baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	const { signal: requestSignal, cleanup } = abortSignalWithTimeout(signal, REQUEST_TIMEOUT_MS);
+	try {
+		const response = await fetch(anthropicModelsUrl(baseUrl), {
+			headers: {
+				Accept: "application/json",
+				"x-api-key": apiKey,
+				// Some reverse proxies accept the key as a bearer token instead of
+				// Anthropic's x-api-key header; sending both is harmless upstream.
+				Authorization: `Bearer ${apiKey}`,
+				"anthropic-version": "2023-06-01",
+				"User-Agent": "pi-cliproxyapi-autoconnect/1.2.1",
+			},
+			signal: requestSignal,
+		});
+		if (!response.ok) {
+			const body = await safeText(response);
+			if (response.status === 404 || response.status === 405 || response.status === 501) {
+				return {
+					ok: false,
+					error: `The Anthropic-compatible endpoint does not expose a usable model list (HTTP ${response.status})`,
+					kind: "unsupported",
+					status: response.status,
+				};
+			}
+			return makeHttpFailure(response.status, body);
+		}
+		const payload = await response.json().catch(() => undefined);
+		const models = parseOpenAIModelList(payload);
+		if (!models) return { ok: false, error: "Response is not an Anthropic-compatible model list (missing data array)", kind: "format" };
+		return { ok: true, models };
+	} catch (error) {
+		return { ok: false, error: describeFetchError(error, requestSignal, signal), kind: "network" };
+	} finally {
+		cleanup();
+	}
+}
+
+async function fetchModelsForApi(api: SupportedApi, baseUrl: string, apiKey: string, signal: AbortSignal): Promise<FetchResult> {
+	if (api === "google-generative-ai") return fetchGeminiModels(baseUrl, apiKey, signal);
+	if (api === "anthropic-messages") return fetchAnthropicModels(baseUrl, apiKey, signal);
+	return fetchOpenAIModels(baseUrl, apiKey, signal);
+}
+
+// =============================================================================
+// Model conversion
+// =============================================================================
+
+function guessLimits(api: SupportedApi, modelId: string): { contextWindow: number; maxTokens: number } {
+	const id = modelId.toLowerCase();
+	if (api === "anthropic-messages" || id.includes("claude")) return { contextWindow: 200_000, maxTokens: 64_000 };
+	if (api === "google-generative-ai" || id.includes("gemini")) return { contextWindow: 1_000_000, maxTokens: 65_536 };
+	if (/gpt-5|gpt-6|gpt-7/u.test(id)) return { contextWindow: 272_000, maxTokens: 128_000 };
+	if (/(^|[-_/])o[1-9](-|$)/u.test(id)) return { contextWindow: 200_000, maxTokens: 100_000 };
+	return { contextWindow: 131_072, maxTokens: 32_768 };
+}
+
+function toModel(
+	entry: StoredModel,
+	config: CliproxyConfig,
+	metadata: ReadonlyMap<string, ModelMetadata> = new Map(),
+	storeMetadata: ReadonlyMap<string, ModelMetadata> = new Map(),
+	builtin: ReadonlyMap<string, ModelMetadata> = new Map(),
+): Model<Api> {
+	const normalizedId = normalizeModelId(entry.id);
+	const meta = metadata.get(entry.id) ?? metadata.get(normalizedId);
+	const stored = storeMetadata.get(entry.id) ?? storeMetadata.get(normalizedId);
+	const builtinMeta = builtin.get(entry.id) ?? builtin.get(normalizedId);
+	const limits = guessLimits(config.api, entry.id);
+	return {
+		id: entry.id,
+		name: meta?.name ?? entry.name?.trim() ?? stored?.name ?? builtinMeta?.name ?? entry.id,
+		api: config.api,
+		provider: PROVIDER_ID,
+		baseUrl: config.baseUrl,
+		reasoning: meta?.reasoning ?? entry.reasoning ?? stored?.reasoning ?? builtinMeta?.reasoning ?? false,
+		input: meta?.input ?? entry.input ?? stored?.input ?? builtinMeta?.input ?? ["text"],
+		cost: meta?.cost ??
+			entry.cost ??
+			stored?.cost ??
+			builtinMeta?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow:
+			meta?.contextWindow ??
+			entry.contextWindow ??
+			stored?.contextWindow ??
+			builtinMeta?.contextWindow ??
+			limits.contextWindow,
+		maxTokens:
+			meta?.maxTokens ?? entry.maxTokens ?? stored?.maxTokens ?? builtinMeta?.maxTokens ?? limits.maxTokens,
+		type: "chat",
+	};
+}
+
+/** Freeze the effective capability metadata into cliproxy.json. */
+function enrichModel(
+	entry: StoredModel,
+	config: CliproxyConfig,
+	metadata: ReadonlyMap<string, ModelMetadata>,
+	storeMetadata: ReadonlyMap<string, ModelMetadata>,
+	builtin: ReadonlyMap<string, ModelMetadata>,
+): StoredModel {
+	const model = toModel(entry, config, metadata, storeMetadata, builtin);
+	return {
+		id: model.id,
+		name: model.name,
+		...(entry.ownedBy ? { ownedBy: entry.ownedBy } : {}),
+		reasoning: model.reasoning,
+		input: model.input,
+		cost: model.cost,
+		contextWindow: model.contextWindow,
+		maxTokens: model.maxTokens,
+	};
+}
+
+function parseManualModelIds(input: string): StoredModel[] {
+	const seen = new Set<string>();
+	const models: StoredModel[] = [];
+	for (const part of input.split(/[,\s;，、]+/u)) {
+		const id = part.trim();
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		models.push({ id });
+	}
+	return models;
+}
+
+function credentialKey(credential: RefreshModelsContext["credential"]): string | undefined {
+	if (credential?.type === "api_key" && credential.key) return credential.key;
+	return undefined;
+}
+
+// =============================================================================
+// Login flow
+// =============================================================================
+
+function isAuthFailure(failure: FetchFailure | undefined): boolean {
+	return failure?.kind === "auth" || failure?.kind === "forbidden";
+}
+
+function authFailureMessage(failure: FetchFailure): string {
+	if (failure.error.includes("unsafe_example_api_key")) {
+		return "CLIProxyAPI is still using the example API key (unsafe_example_api_key). Update access.api-keys on the server and restart CLIProxyAPI.";
+	}
+	return `API key verification failed: ${failure.error}`;
+}
+
+function normalizeApiKey(value: string): string {
+	return value.trim().replace(/^Bearer\s+/iu, "").trim();
+}
+
+function compactMessage(value: string, maxLength = 180): string {
+	const singleLine = value.replace(/\s+/gu, " ").trim();
+	return singleLine.length > maxLength ? `${singleLine.slice(0, maxLength)}...` : singleLine;
+}
+
+/**
+ * Probe every compatible address, but keep OpenAI first: all OpenAI candidates
+ * (primary scheme, then the implicit http/https alternative) run before Gemini,
+ * and Gemini runs before Anthropic. The first non-empty model list wins.
+ */
+function buildDiscoveryCandidates(roots: string[]): DiscoveryCandidate[] {
+	const candidates: DiscoveryCandidate[] = [];
+	for (const rootUrl of roots) {
+		candidates.push({ api: "openai-completions", rootUrl, baseUrl: openAIBaseUrl(rootUrl) });
+	}
+	for (const rootUrl of roots) {
+		candidates.push({ api: "google-generative-ai", rootUrl, baseUrl: geminiBaseUrl(rootUrl) });
+	}
+	for (const rootUrl of roots) {
+		candidates.push({ api: "anthropic-messages", rootUrl, baseUrl: anthropicBaseUrl(rootUrl) });
+	}
+	return candidates;
+}
+
+function summarizeDiscoveryAttempts(attempts: DiscoveryAttempt[]): string {
+	return attempts
+		.map(
+			({ candidate, failure }) =>
+				`${PROVIDER_APIS[candidate.api]} ${candidate.baseUrl}: ${compactMessage(failure.error)}`,
+		)
+		.join("\n");
+}
+
+function firstAuthFailure(attempts: DiscoveryAttempt[]): FetchFailure | undefined {
+	return attempts.find(({ failure }) => isAuthFailure(failure))?.failure;
+}
+
+async function autoDiscoverModels(
+	candidates: DiscoveryCandidate[],
+	apiKey: string,
+	signal: AbortSignal,
+	onAttempt?: (candidate: DiscoveryCandidate, index: number, total: number) => void,
+): Promise<DiscoveryOutcome> {
+	const attempts: DiscoveryAttempt[] = [];
+	let emptySuccess: DiscoveryCandidate | undefined;
+
+	for (const [index, candidate] of candidates.entries()) {
+		onAttempt?.(candidate, index, candidates.length);
+		const result = await fetchModelsForApi(candidate.api, candidate.baseUrl, apiKey, signal);
+		if (result.ok) {
+			if (result.models.length > 0) return { ok: true, candidate, models: result.models };
+			emptySuccess ??= candidate;
+			continue;
+		}
+		attempts.push({ candidate, failure: result });
+	}
+
+	return { ok: false, attempts, ...(emptySuccess ? { empty: emptySuccess } : {}) };
+}
+
+async function runLogin(interaction: ProviderAuthInteraction): Promise<ApiKeyCredential> {
+	const domainInput = await interaction.prompt({
+		type: "text",
+		message: "CLIProxy bound domain (for example proxy.example.com or https://proxy.example.com)",
+		placeholder: "proxy.example.com",
+	});
+	if (!domainInput.trim()) throw new Error("Domain is required.");
+
+	const { rootUrl: initialRootUrl, implicitScheme } = normalizeDomain(domainInput);
+	const promptForApiKey = async (message: string): Promise<string> => {
+		const value = normalizeApiKey(
+			await interaction.prompt({
+				type: "secret",
+				message,
+				placeholder: "sk-...",
+			}),
+		);
+		if (!value) throw new Error("API key is required.");
+		return value;
+	};
+	let apiKey = await promptForApiKey("CLIProxy API key (stored in pi's auth.json)");
+
+	// A bare host may be either http or https; only try the alternate scheme
+	// automatically when the user did not spell one out.
+	const roots = [initialRootUrl];
+	if (implicitScheme) {
+		const alternate = swapScheme(initialRootUrl);
+		if (alternate) roots.push(alternate);
+	}
+
+	let activeRoot = initialRootUrl;
+	let api: SupportedApi = "openai-completions";
+	let baseUrl = openAIBaseUrl(initialRootUrl);
+	let models: StoredModel[] = [];
+	let source: "auto" | "manual" = "auto";
+	let lastError: string | undefined;
+
+	const candidates = buildDiscoveryCandidates(roots);
+	const discover = async (): Promise<DiscoveryOutcome> =>
+		autoDiscoverModels(candidates, apiKey, interaction.signal, (candidate, index, total) => {
+			interaction.notify({
+				type: "progress",
+				message: `Trying ${PROVIDER_APIS[candidate.api]}: ${candidate.baseUrl} (${index + 1}/${total})...`,
+			});
+		});
+
+	let outcome = await discover();
+
+	// A rejected key applies to every protocol, so only ask again after all
+	// compatible addresses have been tried. This keeps the login flow automatic
+	// while still surfacing a real credential problem instead of hiding it in
+	// the address picker.
+	if (!outcome.ok) {
+		let authFailure = firstAuthFailure(outcome.attempts);
+		if (authFailure?.error.includes("unsafe_example_api_key")) {
+			throw new Error(authFailureMessage(authFailure));
+		}
+		if (authFailure) {
+			interaction.notify({
+				type: "info",
+				message: `All compatible endpoints failed authentication: ${compactMessage(authFailure.error)}\nEnter the API key again.`,
+			});
+			apiKey = await promptForApiKey("Re-enter the CLIProxy API key");
+			outcome = await discover();
+			authFailure = outcome.ok ? undefined : firstAuthFailure(outcome.attempts);
+			if (authFailure) throw new Error(authFailureMessage(authFailure));
+		}
+	}
+
+	if (outcome.ok) {
+		activeRoot = outcome.candidate.rootUrl;
+		baseUrl = outcome.candidate.baseUrl;
+		api = outcome.candidate.api;
+		models = outcome.models;
+		lastError = undefined;
+		interaction.notify({
+			type: "info",
+			message: `Selected ${PROVIDER_APIS[api]}: ${baseUrl} (${models.length} models).`,
+		});
+	} else if (outcome.empty) {
+		// Every address answered, but no upstream credentials are available.
+		// Picking another address would not help; go straight to manual IDs.
+		activeRoot = outcome.empty.rootUrl;
+		baseUrl = outcome.empty.baseUrl;
+		api = outcome.empty.api;
+		models = [];
+		lastError = "All compatible endpoints returned an empty model list";
+	} else {
+		const responding = outcome.attempts.find(({ failure }) => failure.kind !== "network");
+		activeRoot = responding?.candidate.rootUrl ?? initialRootUrl;
+		lastError = summarizeDiscoveryAttempts(outcome.attempts) || "Unknown error";
+
+		const diagnostic = await probeCliproxy(activeRoot, interaction.signal);
+		interaction.notify({
+			type: "info",
+			message: `Tried ${outcome.attempts.length} compatible endpoints, but none returned a model list:\n${lastError}${diagnostic ? `\n${diagnostic}` : ""}`,
+		});
+
+		const choice = await interaction.prompt({
+			type: "select",
+			message: "Select a CLIProxy-compatible endpoint",
+			options: [
+				{ id: "retry-openai", label: `Retry OpenAI compatible: ${openAIBaseUrl(activeRoot)}` },
+				{ id: "anthropic", label: `Anthropic compatible: ${anthropicBaseUrl(activeRoot)}` },
+				{ id: "gemini", label: `Gemini compatible: ${geminiBaseUrl(activeRoot)}` },
+				{ id: "custom", label: "Custom compatible endpoint..." },
+			],
+		});
+
+		if (choice === "retry-openai") {
+			api = "openai-completions";
+			baseUrl = openAIBaseUrl(activeRoot);
+			const retry = await fetchOpenAIModels(baseUrl, apiKey, interaction.signal);
+			if (!retry.ok && isAuthFailure(retry)) throw new Error(authFailureMessage(retry));
+			if (retry.ok) {
+				models = retry.models;
+				lastError = undefined;
+			} else {
+				lastError = retry.error;
+			}
+		} else if (choice === "anthropic") {
+			api = "anthropic-messages";
+			baseUrl = anthropicBaseUrl(activeRoot);
+			const anthropic = await fetchAnthropicModels(baseUrl, apiKey, interaction.signal);
+			if (!anthropic.ok && isAuthFailure(anthropic)) throw new Error(authFailureMessage(anthropic));
+			if (anthropic.ok) {
+				models = anthropic.models;
+				lastError = undefined;
+			} else {
+				lastError = anthropic.error;
+				if (anthropic.kind === "unsupported") {
+					interaction.notify({
+						type: "info",
+						message: "This Anthropic-compatible endpoint has no model list endpoint. Enter model IDs manually in the next step.",
+					});
+				}
+			}
+		} else if (choice === "gemini") {
+			api = "google-generative-ai";
+			baseUrl = geminiBaseUrl(activeRoot);
+			const gemini = await fetchGeminiModels(baseUrl, apiKey, interaction.signal);
+			if (!gemini.ok && isAuthFailure(gemini)) throw new Error(authFailureMessage(gemini));
+			if (gemini.ok) {
+				models = gemini.models;
+				lastError = undefined;
+			} else {
+				lastError = gemini.error;
+			}
+		} else {
+			const customInput = (
+				await interaction.prompt({
+					type: "text",
+					message: "Custom compatible endpoint (full base URL, for example https://proxy.example.com/v1)",
+					placeholder: "https://proxy.example.com/v1",
+				})
+			).trim();
+			if (!customInput) throw new Error("A custom endpoint is required.");
+			const protocolChoice = await interaction.prompt({
+				type: "select",
+				message: "Compatible protocol for this endpoint",
+				options: [
+					{ id: "openai", label: "OpenAI compatible (/v1/chat/completions)" },
+					{ id: "anthropic", label: "Anthropic compatible (/v1/messages)" },
+					{ id: "gemini", label: "Gemini compatible (/v1beta)" },
+				],
+			});
+			api =
+				protocolChoice === "anthropic"
+					? "anthropic-messages"
+					: protocolChoice === "gemini"
+						? "google-generative-ai"
+						: "openai-completions";
+			baseUrl = trimTrailingSlashes(customInput);
+			const retry = await fetchModelsForApi(api, baseUrl, apiKey, interaction.signal);
+			if (!retry.ok && isAuthFailure(retry)) throw new Error(authFailureMessage(retry));
+			if (retry.ok) {
+				models = retry.models;
+				lastError = undefined;
+			} else {
+				lastError = retry.error;
+			}
+		}
+	}
+
+	if (models.length === 0) {
+		const manual = await interaction.prompt({
+			type: "text",
+			message: "No model list was retrieved. Enter model IDs manually (comma or space separated; leave empty to add none for now)",
+			placeholder: "claude-sonnet-4-5, gemini-2.5-pro",
+		});
+		models = parseManualModelIds(manual);
+		source = "manual";
+	}
+
+	const configBase: CliproxyConfig = {
+		version: CONFIG_VERSION,
+		domain: domainInput.trim(),
+		rootUrl: activeRoot,
+		baseUrl,
+		api,
+		models: [],
+		source,
+		updatedAt: 0,
+	};
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const enriched = models.map((entry) => enrichModel(entry, configBase, metadata, storeMetadata, builtin));
+	const config: CliproxyConfig = {
+		...configBase,
+		models: enriched,
+		updatedAt: Date.now(),
+		...(lastError && enriched.length === 0 ? { lastError } : {}),
+	};
+	try {
+		writeConfig(config);
+	} catch (error) {
+		throw new Error(
+			`Failed to write CLIProxy config: ${error instanceof Error ? error.message : String(error)} (${configPath()})`,
+		);
+	}
+
+	if (models.length > 0) {
+		interaction.notify({
+			type: "info",
+			message: `CLIProxy config saved: ${baseUrl} (${models.length} models, ${PROVIDER_APIS[api]}).`,
+		});
+	} else {
+		interaction.notify({
+			type: "info",
+			message: `CLIProxy config saved: ${baseUrl}, but no models were imported. Use /cliproxy refresh to retry.`,
+		});
+	}
+
+	return { type: "api_key", key: apiKey };
+}
+
+// =============================================================================
+// Dynamic model discovery
+// =============================================================================
+
+async function refreshProviderModels(context: RefreshModelsContext): Promise<readonly Model<Api>[]> {
+	const config = readConfig();
+	if (!config) return [];
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const cached = config.models.map((entry) => toModel(entry, config, metadata, storeMetadata, builtin));
+	const apiKey = credentialKey(context.credential);
+	if (!apiKey) return cached;
+
+	// Opening /model asks for a refresh every time. Reuse a recent snapshot
+	// unless the caller explicitly forces it (/cliproxy refresh) or it is stale.
+	const fresh = config.updatedAt > 0 && Date.now() - config.updatedAt < MODEL_REFRESH_TTL_MS;
+	if (!context.force && fresh) return cached;
+
+	const result = await fetchModelsForApi(config.api, config.baseUrl, apiKey, context.signal);
+	if (context.signal.aborted) return cached;
+	if (!result.ok) {
+		// CLIProxyAPI's Anthropic endpoint may not expose /v1/models at all.
+		// That is expected, not a refresh error; keep the cached catalog.
+		if (result.kind === "unsupported") return cached;
+		lastRefreshError = result.error;
+		if (config.lastError !== result.error) {
+			try {
+				writeConfig({ ...config, lastError: result.error });
+			} catch {
+				// Keep serving the cached catalog even if the error cannot be persisted.
+			}
+		}
+		return cached;
+	}
+	lastRefreshError = undefined;
+	const fetched = result.models;
+	// An empty upstream list is legitimate (no credentials/cooldown). Keep
+	// manually entered models but do honor real automatic empties.
+	if (fetched.length === 0 && config.source === "manual") {
+		try {
+			writeConfig({
+				...config,
+				updatedAt: Date.now(),
+				lastError: "Upstream returned an empty model list (manual models kept)",
+			});
+		} catch {
+			// Best effort.
+		}
+		return cached;
+	}
+
+	const enriched = fetched.map((entry) => enrichModel(entry, config, metadata, storeMetadata, builtin));
+	const updated: CliproxyConfig = {
+		...config,
+		models: enriched,
+		source: "auto",
+		updatedAt: Date.now(),
+		...(enriched.length === 0 ? { lastError: "Upstream returned an empty model list" } : {}),
+	};
+	if (enriched.length > 0) delete updated.lastError;
+	try {
+		writeConfig(updated);
+	} catch {
+		// Model discovery still works in memory even if the cache cannot be persisted.
+	}
+	return enriched.map((entry) => toModel(entry, updated, metadata, storeMetadata, builtin));
+}
+
+// =============================================================================
+// Provider registration
+// =============================================================================
+
+function buildProvider(config: CliproxyConfig | undefined): Provider {
+	const metadata = readModelsJsonMetadata();
+	const storeMetadata = readModelsStoreMetadata();
+	const builtin = readBuiltinMetadata();
+	const models = config
+		? config.models.map((entry) => toModel(entry, config, metadata, storeMetadata, builtin))
+		: [];
+	const api: Partial<Record<Api, ProviderStreams>> = {
+		"openai-completions": openAICompletionsApi(),
+		"anthropic-messages": anthropicMessagesApi(),
+		"google-generative-ai": googleGenerativeAIApi(),
+	};
+	return createProvider({
+		id: PROVIDER_ID,
+		name: PROVIDER_NAME,
+		auth: {
+			apiKey: {
+				name: AUTH_NAME,
+				login: runLogin,
+				resolve: async ({ credential }) =>
+					credential?.key
+						? { auth: { apiKey: credential.key }, source: "stored credential" }
+						: undefined,
+			},
+		},
+		// Baseline models come from cliproxy.json so offline startup and
+		// `pi --list-models` work without a models-store entry. Dynamic
+		// fetchModels() refreshes them; model-level baseUrl is authoritative.
+		models,
+		fetchModels: refreshProviderModels,
+		api,
+	});
+}
+
+// =============================================================================
+// Extension entry point
+// =============================================================================
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerProvider(buildProvider(readConfig()));
+
+	pi.registerCommand("cliproxy", {
+		description: "Show CLIProxy config, or run /cliproxy refresh to refresh models",
+		handler: async (args, ctx) => {
+			const subcommand = args.trim().toLowerCase();
+			const config = readConfig();
+
+			if (subcommand === "refresh") {
+				if (!config) {
+					ctx.ui.notify("CLIProxy is not configured. Run /login and choose \"Sign in with an API key\" -> CLIProxy.", "warning");
+					return;
+				}
+				let refreshError: string | undefined;
+				try {
+					const result = await ctx.modelRegistry.refresh({
+						providers: [PROVIDER_ID],
+						force: true,
+						signal: AbortSignal.timeout(20_000),
+					});
+					refreshError = result.errors.get(PROVIDER_ID)?.message;
+				} catch (error) {
+					refreshError = error instanceof Error ? error.message : String(error);
+				}
+				const count = ctx.modelRegistry.getAll().filter((model) => model.provider === PROVIDER_ID).length;
+				if (refreshError) {
+					ctx.ui.notify(`CLIProxy model refresh failed: ${refreshError}`, "error");
+				} else if (lastRefreshError) {
+					ctx.ui.notify(`CLIProxy model refresh failed; using cached models (${count}): ${lastRefreshError}`, "warning");
+				} else if (count === 0) {
+					ctx.ui.notify("CLIProxy refreshed, but no models were found. Check the API key or run /login again.", "warning");
+				} else {
+					ctx.ui.notify(`CLIProxy models refreshed: ${count}.`, "info");
+				}
+				return;
+			}
+
+			if (!config) {
+				ctx.ui.notify(
+					`CLIProxy is not configured.\nRun /login -> "Sign in with an API key" -> CLIProxy and enter the bound domain and API key.\nConfig will be written to: ${configPath()}`,
+					"info",
+				);
+				return;
+			}
+
+			const count = ctx.modelRegistry.getAll().filter((model) => model.provider === PROVIDER_ID).length;
+			const lastError = lastRefreshError ?? config.lastError;
+			const lines = [
+				`CLIProxy: ${config.baseUrl}`,
+				`Protocol: ${PROVIDER_APIS[config.api]} (${config.api})`,
+				`Models: ${count}${config.models.length !== count ? ` (${config.models.length} cached)` : ""}`,
+				`Config: ${configPath()}`,
+				lastError ? `Last error: ${lastError}` : undefined,
+				"Reconfigure: /login -> \"Sign in with an API key\" -> CLIProxy",
+				"Refresh models: /cliproxy refresh",
+			].filter((line): line is string => Boolean(line));
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}