@samrito/pi-cliproxyapi-provider 0.16.0

package/extensions/index.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { DEFAULT_CONFIG, loadConfig } from "../src/config.ts";
+import { ProviderCatalog } from "../src/catalog.ts";
+import { ProviderRuntime } from "../src/runtime.ts";
+import { buildProviderRegistration } from "../src/registration.ts";
+import { buildUnavailableProviderModels } from "../src/provider.ts";
+import { registerCliproxyapiCommand } from "../src/commands.ts";
+import { getDiscoveryApiKey } from "../src/auth.ts";
+import { loadProviderSettings } from "../src/settings.ts";
+import { registerCodexCompatiblePayloadAdapter } from "../src/codex-compat.ts";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(extensionDir);
+const bundledModelsDevPath = join(packageRoot, "data", "models-dev-fallback.json");
+
+export default async function (pi: ExtensionAPI) {
+  let config = DEFAULT_CONFIG;
+  try {
+    const cwd = process.cwd();
+    config = loadConfig(cwd);
+    const settings = loadProviderSettings(cwd);
+    const catalog = new ProviderCatalog({
+      config,
+      gpt56ContextWindow: settings.gpt56ContextWindow,
+      bundledModelsDevPath,
+      getApiKey: () => getDiscoveryApiKey(config.providerName),
+    });
+    const runtime = new ProviderRuntime({ pi, config, catalog });
+    registerCodexCompatiblePayloadAdapter(pi, config.providerName);
+    registerCliproxyapiCommand(pi, runtime, catalog);
+    await runtime.start();
+  } catch (error) {
+    registerCodexCompatiblePayloadAdapter(pi, config.providerName);
+    registerCliproxyapiCommand(pi);
+    pi.registerProvider(config.providerName, buildProviderRegistration(config, buildUnavailableProviderModels()).config);
+    console.warn(`[pi-cliproxyapi-provider] registered placeholder provider after startup failure: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@samrito/pi-cliproxyapi-provider",
+  "version": "0.16.0",
+  "description": "Pi provider package for CLIProxyAPI with automatic model discovery and models.dev enrichment.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "cliproxyapi",
+    "provider",
+    "models.dev"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiangsam/pi-cliproxyapi-provider.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xiangsam/pi-cliproxyapi-provider/issues"
+  },
+  "homepage": "https://github.com/xiangsam/pi-cliproxyapi-provider#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "extensions",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "test:unit": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "update:models-dev": "node scripts/update-models-dev-fallback.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "@earendil-works/pi-tui": ">=0.84.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,11 @@
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+
+export async function getDiscoveryApiKey(providerName: string, env: NodeJS.ProcessEnv = process.env): Promise<string | undefined> {
+  try {
+    const credential = await readStoredCredential(providerName);
+    if (credential?.type === "api_key") return credential.key;
+    return env.CLIPROXYAPI_API_KEY;
+  } catch {
+    return env.CLIPROXYAPI_API_KEY;
+  }
+}

package/src/cache.ts

@@ -0,0 +1,33 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface CacheEnvelope<T> {
+  fetchedAt: number;
+  data: T;
+}
+
+export async function readCache<T>(path: string, parseData: (value: unknown) => T): Promise<CacheEnvelope<T> | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.fetchedAt !== "number" || !("data" in parsed)) {
+      return undefined;
+    }
+    return { fetchedAt: parsed.fetchedAt, data: parseData(parsed.data) };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    return undefined;
+  }
+}
+
+export async function writeCache<T>(path: string, data: T, fetchedAt = Date.now()): Promise<void> {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const temporaryPath = join(directory, `.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify({ fetchedAt, data }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryPath, path);
+    await chmod(path, 0o600);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,248 @@
+import { cpaModelsCachePath, discoveryHeaders, modelsDevCachePath } from "./discovery.ts";
+import { readCache, writeCache, type CacheEnvelope } from "./cache.ts";
+import { fetchCpaModels, parseCpaModelsCache, type CpaModel } from "./cpa.ts";
+import { fetchModelsDevCatalog, hasSourceProviderMetadata, parseModelsDevCatalog, readBundledModelsDevFallback } from "./models-dev.ts";
+import { buildProviderModels, type BuildProviderModelsResult } from "./provider.ts";
+import type { Gpt56ContextWindowMode } from "./settings.ts";
+import type { CpaProviderConfig, ModelsDevCatalog } from "./types.ts";
+
+export type MetadataSource = "cache" | "bundled" | "disabled";
+export type RefreshTarget = "models" | "metadata" | "all";
+
+export interface CatalogSnapshot {
+  cpaModels: CpaModel[];
+  cpaUpdatedAt?: number;
+  metadata: ModelsDevCatalog;
+  metadataUpdatedAt?: number;
+  metadataSource: MetadataSource;
+  gpt56ContextWindow: Gpt56ContextWindowMode;
+  built: BuildProviderModelsResult;
+}
+
+export interface SourceRefreshResult {
+  attempted: boolean;
+  updated: boolean;
+  changed: boolean;
+  error?: unknown;
+}
+
+export interface CatalogRefreshResult {
+  snapshot: CatalogSnapshot;
+  models: SourceRefreshResult;
+  metadata: SourceRefreshResult;
+}
+
+export interface ProviderCatalogOptions {
+  config: CpaProviderConfig;
+  gpt56ContextWindow: Gpt56ContextWindowMode;
+  bundledModelsDevPath: string;
+  getApiKey: () => Promise<string | undefined>;
+  backgroundTimeoutMs?: number;
+  manualTimeoutMs?: number;
+  writeSnapshot?: typeof writeCache;
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sameCpaModels(left: CpaModel[], right: CpaModel[]): boolean {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function sameMetadata(left: ModelsDevCatalog, right: ModelsDevCatalog): boolean {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+export class ProviderCatalog {
+  private snapshot?: CatalogSnapshot;
+  private activeRefresh?: Promise<CatalogRefreshResult>;
+  private activeRefreshTarget?: RefreshTarget;
+  private activeRefreshMode?: "background" | "manual";
+  private activeRefreshController?: AbortController;
+  private readonly activeRefreshWaiters = new Set<symbol>();
+  private readonly options: ProviderCatalogOptions;
+
+  constructor(options: ProviderCatalogOptions) {
+    this.options = options;
+  }
+
+  async load(): Promise<CatalogSnapshot> {
+    const cpaCache = await readCache(cpaModelsCachePath(this.options.config), parseCpaModelsCache);
+    const metadataSnapshot = await this.loadMetadata();
+    return this.setSnapshot(cpaCache?.data ?? [], cpaCache?.fetchedAt, metadataSnapshot.data, metadataSnapshot.fetchedAt, metadataSnapshot.source);
+  }
+
+  async refresh(
+    target: RefreshTarget = "all",
+    mode: "background" | "manual" = "manual",
+    getDiscoveryApiKey?: () => Promise<string | undefined>,
+    signal?: AbortSignal,
+  ): Promise<CatalogRefreshResult> {
+    if (this.activeRefresh) {
+      if (this.activeRefreshTarget === target && this.activeRefreshMode === mode) {
+        return this.waitForActiveRefresh(signal);
+      }
+      await this.activeRefresh;
+    }
+
+    const controller = new AbortController();
+    this.activeRefreshTarget = target;
+    this.activeRefreshMode = mode;
+    this.activeRefreshController = controller;
+    this.activeRefresh = this.performRefresh(target, mode, getDiscoveryApiKey, controller.signal).finally(() => {
+      this.activeRefresh = undefined;
+      this.activeRefreshTarget = undefined;
+      this.activeRefreshMode = undefined;
+      this.activeRefreshController = undefined;
+      this.activeRefreshWaiters.clear();
+    });
+    return this.waitForActiveRefresh(signal);
+  }
+
+  current(): CatalogSnapshot | undefined {
+    return this.snapshot;
+  }
+
+  private async waitForActiveRefresh(signal?: AbortSignal): Promise<CatalogRefreshResult> {
+    const refresh = this.activeRefresh;
+    if (!refresh) throw new Error("No active refresh");
+    if (signal?.aborted) throw signal.reason ?? new Error("Refresh aborted");
+
+    const waiter = Symbol("refresh-waiter");
+    this.activeRefreshWaiters.add(waiter);
+    let onAbort: (() => void) | undefined;
+    const aborted = signal
+      ? new Promise<never>((_resolve, reject) => {
+        onAbort = () => {
+          this.activeRefreshWaiters.delete(waiter);
+          if (this.activeRefreshWaiters.size === 0) {
+            this.activeRefreshController?.abort(signal.reason ?? new Error("Refresh aborted"));
+          }
+          reject(signal.reason ?? new Error("Refresh aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+      : undefined;
+
+    try {
+      return await (aborted ? Promise.race([refresh, aborted]) : refresh);
+    } finally {
+      this.activeRefreshWaiters.delete(waiter);
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    }
+  }
+
+  private async performRefresh(
+    target: RefreshTarget,
+    mode: "background" | "manual",
+    getDiscoveryApiKey?: () => Promise<string | undefined>,
+    signal?: AbortSignal,
+  ): Promise<CatalogRefreshResult> {
+    const current = this.snapshot ?? await this.load();
+    let cpaModels = current.cpaModels;
+    let cpaUpdatedAt = current.cpaUpdatedAt;
+    let metadata = current.metadata;
+    let metadataUpdatedAt = current.metadataUpdatedAt;
+    let metadataSource = current.metadataSource;
+
+    const models: SourceRefreshResult = { attempted: target !== "metadata", updated: false, changed: false };
+    const metadataResult: SourceRefreshResult = { attempted: target !== "models" && this.options.config.modelsDevEnabled, updated: false, changed: false };
+
+    if (models.attempted) {
+      try {
+        const apiKey = await (getDiscoveryApiKey ?? this.options.getApiKey)();
+        const fresh = await fetchCpaModels(
+          this.options.config.baseUrl,
+          discoveryHeaders(this.options.config, apiKey),
+          mode === "background" ? this.options.backgroundTimeoutMs ?? 2_000 : this.options.manualTimeoutMs ?? 10_000,
+          signal,
+        );
+        if (mode === "background" && current.cpaModels.length > 0 && fresh.length === 0) {
+          throw new Error("CPA automatic discovery returned no models; retained the last successful snapshot");
+        }
+        const freshUpdatedAt = Date.now();
+        const changed = !sameCpaModels(current.cpaModels, fresh);
+        await (this.options.writeSnapshot ?? writeCache)(cpaModelsCachePath(this.options.config), fresh, freshUpdatedAt);
+        cpaModels = fresh;
+        cpaUpdatedAt = freshUpdatedAt;
+        models.changed = changed;
+        models.updated = true;
+      } catch (error) {
+        if (signal?.aborted) throw signal.reason ?? error;
+        models.error = error;
+      }
+    }
+
+    if (metadataResult.attempted) {
+      try {
+        const fresh = await fetchModelsDevCatalog(this.options.manualTimeoutMs ?? 10_000, signal);
+        const freshUpdatedAt = Date.now();
+        const changed = !sameMetadata(current.metadata, fresh);
+        await (this.options.writeSnapshot ?? writeCache)(modelsDevCachePath(), fresh, freshUpdatedAt);
+        metadata = fresh;
+        metadataUpdatedAt = freshUpdatedAt;
+        metadataSource = "cache";
+        metadataResult.changed = changed;
+        metadataResult.updated = true;
+      } catch (error) {
+        if (signal?.aborted) throw signal.reason ?? error;
+        metadataResult.error = error;
+      }
+    }
+
+    const snapshot = this.setSnapshot(cpaModels, cpaUpdatedAt, metadata, metadataUpdatedAt, metadataSource);
+    return { snapshot, models, metadata: metadataResult };
+  }
+
+  private async loadMetadata(): Promise<{ data: ModelsDevCatalog; fetchedAt?: number; source: MetadataSource }> {
+    if (!this.options.config.modelsDevEnabled) return { data: {}, source: "disabled" };
+    const cached = await readCache(modelsDevCachePath(), parseModelsDevCatalog);
+    if (cached && hasSourceProviderMetadata(cached.data)) {
+      return { data: cached.data, fetchedAt: cached.fetchedAt, source: "cache" };
+    }
+    return { data: await readBundledModelsDevFallback(this.options.bundledModelsDevPath), source: "bundled" };
+  }
+
+  private setSnapshot(
+    cpaModels: CpaModel[],
+    cpaUpdatedAt: number | undefined,
+    metadata: ModelsDevCatalog,
+    metadataUpdatedAt: number | undefined,
+    metadataSource: MetadataSource,
+  ): CatalogSnapshot {
+    this.snapshot = {
+      cpaModels,
+      cpaUpdatedAt,
+      metadata,
+      metadataUpdatedAt,
+      metadataSource,
+      gpt56ContextWindow: this.options.gpt56ContextWindow,
+      built: buildProviderModels(
+        cpaModels,
+        metadata,
+        this.options.config.modelAliases,
+        this.options.gpt56ContextWindow,
+        this.options.config.modelOverrides,
+        this.options.config.metadataFallbackProvider,
+      ),
+    };
+    return this.snapshot;
+  }
+}
+
+export function cacheAge(envelope: Pick<CacheEnvelope<unknown>, "fetchedAt"> | undefined, now = Date.now()): string {
+  if (!envelope) return "missing";
+  const seconds = Math.max(0, Math.round((now - envelope.fetchedAt) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86_400)}d ago`;
+}

package/src/codex-compat.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isResponsesModel(
+  model: Pick<NonNullable<ExtensionContext["model"]>, "provider" | "api"> | null | undefined,
+  providerName: string,
+): boolean {
+  return model?.provider.trim().toLowerCase() === providerName.trim().toLowerCase()
+    && model.api.toLowerCase().includes("responses");
+}
+
+/**
+ * Match the Codex-compatible Responses wire contract used by
+ * pi-codex-conversion: function tools explicitly publish `strict: null`.
+ * Generic OpenAI Responses omits the field when strict mode is unsupported,
+ * which does not preserve optional argument behavior for Codex-like models.
+ */
+export function rewriteCodexCompatibleToolPayload(
+  payload: unknown,
+  model: Pick<NonNullable<ExtensionContext["model"]>, "provider" | "api"> | null | undefined,
+  providerName: string,
+): unknown | undefined {
+  if (!isResponsesModel(model, providerName) || !isRecord(payload) || !Array.isArray(payload.tools)) {
+    return undefined;
+  }
+
+  let changed = false;
+  const tools = payload.tools.map((tool) => {
+    if (!isRecord(tool) || tool.type !== "function" || tool.strict === null) return tool;
+    changed = true;
+    return { ...tool, strict: null };
+  });
+
+  return changed ? { ...payload, tools } : undefined;
+}
+
+export function registerCodexCompatiblePayloadAdapter(pi: ExtensionAPI, providerName: string): void {
+  pi.on("before_provider_request", (event, ctx) =>
+    rewriteCodexCompatibleToolPayload(event.payload, ctx.model, providerName));
+}

package/src/commands.ts

@@ -0,0 +1,213 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_CONFIG, loadConfig, globalConfigPath, readConfigFile, writeConfigFile, type ConfigLayer } from "./config.ts";
+import type { ProviderCatalog, CatalogSnapshot, RefreshTarget, SourceRefreshResult } from "./catalog.ts";
+import type { ProviderRuntime } from "./runtime.ts";
+import { openModelInspector, openProviderConfig } from "./model-ui.ts";
+import { loadProviderSettings } from "./settings.ts";
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function formatStatusFailure(config: ReturnType<typeof loadConfig>, error: unknown): string {
+  return [
+    `CLIProxyAPI status failed: ${errorText(error)}`,
+    `Provider: ${config.providerName}`,
+    `Base URL: ${config.baseUrl}`,
+    `Auth required: ${config.authRequired ? "yes" : "no"}`,
+    "",
+    "Run /cliproxyapi config to set the CLIProxyAPI base URL.",
+    `If you just ran /login ${config.providerName}, run /cliproxyapi refresh models.`,
+  ].join("\n");
+}
+
+function redactConfig(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redactConfig);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+    const isSecretLike = /authorization|api[-_]?key|token|secret|cookie/i.test(key);
+    return [key, isSecretLike ? "<redacted>" : redactConfig(entry)];
+  }));
+}
+
+function age(timestamp?: number): string {
+  if (timestamp === undefined) return "missing";
+  const seconds = Math.max(0, Math.round((Date.now() - timestamp) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m ago`;
+  if (seconds < 86_400) return `${Math.round(seconds / 3600)}h ago`;
+  return `${Math.round(seconds / 86_400)}d ago`;
+}
+
+function capabilityCount(snapshot: CatalogSnapshot, key: "reasoning" | "image"): number {
+  return snapshot.built.models.filter((model) => key === "reasoning" ? model.reasoning : model.input.includes("image")).length;
+}
+
+export async function runConfig(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("/cliproxyapi config connection requires an interactive UI.", "warning");
+    return;
+  }
+
+  let current = DEFAULT_CONFIG;
+  try {
+    current = loadConfig(ctx.cwd);
+  } catch (error) {
+    ctx.ui.notify(`Existing CLIProxyAPI config is invalid; using defaults for repair: ${errorText(error)}`, "warning");
+  }
+
+  const path = globalConfigPath();
+  let existing: ConfigLayer | undefined;
+  try {
+    existing = readConfigFile(path);
+  } catch (error) {
+    ctx.ui.notify(`Existing global CLIProxyAPI config is invalid and will be replaced if you save: ${errorText(error)}`, "warning");
+  }
+  const defaults = existing ?? current;
+
+  if (existing) ctx.ui.notify(`Editing existing global config at ${path}:\n${JSON.stringify(redactConfig(existing), null, 2)}`, "info");
+
+  const providerNameInput = await ctx.ui.input(`Provider name (leave blank to keep: ${defaults.providerName})`, `leave blank to keep ${defaults.providerName}`);
+  if (providerNameInput === undefined) return;
+  const baseUrlInput = await ctx.ui.input(`CLIProxyAPI base URL (leave blank to keep: ${defaults.baseUrl})`, `leave blank to keep ${defaults.baseUrl}`);
+  if (baseUrlInput === undefined) return;
+  const authRequired = await ctx.ui.confirm(
+    `Require /login credentials? (current: ${defaults.authRequired ? "yes" : "no"})`,
+    "Choose yes unless this CLIProxyAPI instance accepts unauthenticated requests.",
+  );
+  const authHeader = authRequired
+    ? await ctx.ui.confirm(
+        `Send Authorization bearer header? (current: ${defaults.authHeader ? "yes" : "no"})`,
+        "Choose yes for CLIProxyAPI API keys.",
+      )
+    : false;
+
+  writeConfigFile(path, {
+    ...existing,
+    providerName: providerNameInput || defaults.providerName,
+    baseUrl: baseUrlInput || defaults.baseUrl,
+    authRequired,
+    authHeader,
+  });
+  ctx.ui.notify(`Saved CLIProxyAPI config to ${path}. Reloading pi to apply connection changes...`, "info");
+  await ctx.reload();
+}
+
+function statusText(config: ReturnType<typeof loadConfig>, snapshot: CatalogSnapshot): string {
+  return [
+    `CLIProxyAPI provider: ${config.providerName}`,
+    `Base URL: ${config.baseUrl}`,
+    `Auth required: ${config.authRequired ? "yes" : "no"}`,
+    `Models: ${snapshot.built.stats.total} (${snapshot.built.stats.enriched} enriched, ${snapshot.built.stats.unmatched} unmatched)`,
+    `Reasoning models: ${capabilityCount(snapshot, "reasoning")}`,
+    `Image-capable models: ${capabilityCount(snapshot, "image")}`,
+    `CPA snapshot: ${age(snapshot.cpaUpdatedAt)}`,
+    `models.dev metadata: ${snapshot.metadataSource}${snapshot.metadataUpdatedAt ? `, ${age(snapshot.metadataUpdatedAt)}` : ""}`,
+    `GPT-5.6 context window: ${snapshot.gpt56ContextWindow === "full" ? "full models.dev limit" : "canonical 272000"}`,
+  ].join("\n");
+}
+
+function refreshPart(label: string, result: SourceRefreshResult): string {
+  if (!result.attempted) return `${label}: not requested`;
+  if (result.error) return `${label}: failed (${errorText(result.error)}); retained previous snapshot`;
+  return `${label}: ${result.changed ? "updated" : "unchanged"}`;
+}
+
+function parseRefreshTarget(value: string | undefined): RefreshTarget | undefined {
+  if (!value || value === "all") return "all";
+  if (value === "models") return "models";
+  if (value === "metadata") return "metadata";
+  return undefined;
+}
+
+const CLIPROXYAPI_HELP = [
+  "CLIProxyAPI provider commands:",
+  "  /cliproxyapi status            Show provider and model-catalog status",
+  "  /cliproxyapi refresh           Refresh CPA models and models.dev metadata",
+  "  /cliproxyapi refresh models    Refresh CPA models only",
+  "  /cliproxyapi refresh metadata  Refresh models.dev metadata only",
+  "  /cliproxyapi aliases           Show unmatched model IDs for alias configuration",
+  "  /cliproxyapi models            Inspect models and set bounded overrides",
+  "  /cliproxyapi config            Configure model behavior and display",
+  "  /cliproxyapi config connection Configure provider endpoint and auth",
+  "  /cliproxyapi help              Show this help",
+].join("\n");
+
+export function cliproxyapiArgumentCompletions(prefix: string): Array<{ value: string; label: string }> {
+  return ["config", "config connection", "status", "refresh", "refresh models", "refresh metadata", "aliases", "models", "help"]
+    .filter((item) => item.startsWith(prefix))
+    .map((value) => ({ value, label: value }));
+}
+
+export function registerCliproxyapiCommand(pi: ExtensionAPI, runtime?: ProviderRuntime, catalog?: ProviderCatalog): void {
+  pi.registerCommand("cliproxyapi", {
+    description: "Configure, refresh, and inspect the CLIProxyAPI provider.",
+    getArgumentCompletions(prefix) {
+      return cliproxyapiArgumentCompletions(prefix);
+    },
+    async handler(args, ctx) {
+      const commandArgs = args.trim();
+      const [subcommand, option] = commandArgs ? commandArgs.split(/\s+/) : ["help"];
+      if (subcommand === "help") {
+        ctx.ui.notify(CLIPROXYAPI_HELP, "info");
+        return;
+      }
+      if (subcommand === "config") {
+        if (option === "connection") return runConfig(ctx);
+        if (option) {
+          ctx.ui.notify("Usage: /cliproxyapi config [connection]", "warning");
+          return;
+        }
+        const action = await openProviderConfig(ctx, loadProviderSettings(ctx.cwd), loadConfig(ctx.cwd));
+        if (action === "connection") return runConfig(ctx);
+        return;
+      }
+      if (!["status", "refresh", "aliases", "models"].includes(subcommand)) {
+        ctx.ui.notify(`${CLIPROXYAPI_HELP}\n\nUnknown command: ${subcommand}`, "warning");
+        return;
+      }
+      if (!runtime || !catalog) {
+        ctx.ui.notify("CLIProxyAPI provider is unavailable. Run /cliproxyapi config and reload pi.", "error");
+        return;
+      }
+      const config = loadConfig(ctx.cwd);
+      if (subcommand === "status") {
+        const snapshot = catalog.current() ?? await catalog.load();
+        ctx.ui.notify(statusText(config, snapshot), "info");
+        return;
+      }
+      if (subcommand === "refresh") {
+        const target = parseRefreshTarget(option);
+        if (!target) {
+          ctx.ui.notify("Usage: /cliproxyapi refresh [models|metadata]", "warning");
+          return;
+        }
+        const getDiscoveryApiKey = target === "metadata"
+          ? undefined
+          : () => ctx.modelRegistry.getApiKeyForProvider(config.providerName);
+        const result = await runtime.refresh(target, "manual", getDiscoveryApiKey);
+        const level = result.models.error || result.metadata.error ? "warning" : "info";
+        ctx.ui.notify([
+          "CLIProxyAPI provider refresh complete.",
+          refreshPart("CPA models", result.models),
+          refreshPart("models.dev metadata", result.metadata),
+          `Registered: ${result.snapshot.built.stats.total} models, ${result.snapshot.built.stats.enriched} enriched, ${result.snapshot.built.stats.unmatched} unmatched.`,
+        ].join("\n"), level);
+        return;
+      }
+      if (subcommand === "aliases") {
+        const snapshot = catalog.current() ?? await catalog.load();
+        const sample = snapshot.built.stats.unmatchedModelIds.slice(0, 30);
+        const body = sample.length === 0
+          ? "All CPA models matched models.dev metadata."
+          : `Unmatched CPA models (${snapshot.built.stats.unmatched}):\n${sample.map((id) => `  "${id}": "<models.dev-id>"`).join("\n")}`;
+        ctx.ui.notify(body, snapshot.built.stats.unmatched ? "warning" : "info");
+        return;
+      }
+      if (subcommand === "models") {
+        await openModelInspector(ctx, catalog, config.modelOverrides, loadProviderSettings(ctx.cwd).showStrictMode);
+        return;
+      }
+    },
+  });
+}