pi-cliproxyapi-provider 0.1.0 → 0.2.0

package/extensions/index.ts

@@ -2,9 +2,10 @@ 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 { discoverModels } from "../src/discovery.ts";
-import { buildProviderModels, buildUnavailableProviderModels } from "../src/provider.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";
 
@@ -13,17 +14,33 @@ const packageRoot = dirname(extensionDir);
 const bundledModelsDevPath = join(packageRoot, "data", "models-dev-fallback.json");
 
 export default async function (pi: ExtensionAPI) {
-  registerCliproxyapiCommand(pi, bundledModelsDevPath);
-
   let config = DEFAULT_CONFIG;
   try {
     config = loadConfig(process.cwd());
-    const discovery = await discoverModels({ config, bundledModelsDevPath, discoveryApiKey: await getDiscoveryApiKey(config.providerName) });
-    const built = buildProviderModels(discovery.cpaModels, discovery.modelsDevCatalog, config.modelAliases);
-    const registration = buildProviderRegistration(config, built.models);
-    pi.registerProvider(registration.providerName, registration.config);
+    const catalog = new ProviderCatalog({
+      config,
+      bundledModelsDevPath,
+      getApiKey: () => getDiscoveryApiKey(config.providerName),
+    });
+    const runtime = new ProviderRuntime({ pi, config, catalog });
+    registerCliproxyapiCommand(pi, runtime, catalog);
+    await runtime.start();
+
+    let backgroundRefreshStarted = false;
+    pi.on("session_start", (event, ctx) => {
+      if (event.reason !== "startup" || backgroundRefreshStarted) return;
+      backgroundRefreshStarted = true;
+      void runtime.refresh("models", "background").then((result) => {
+        if (result.models.error && ctx.hasUI) {
+          ctx.ui.setStatus("cliproxyapi", "CPA: cached models");
+        } else if (ctx.hasUI) {
+          ctx.ui.setStatus("cliproxyapi", undefined);
+        }
+      });
+    });
   } catch (error) {
+    registerCliproxyapiCommand(pi);
     pi.registerProvider(config.providerName, buildProviderRegistration(config, buildUnavailableProviderModels()).config);
-    console.warn(`[pi-cliproxyapi-provider] registered placeholder provider after discovery failure: ${error instanceof Error ? error.message : String(error)}`);
+    console.warn(`[pi-cliproxyapi-provider] registered placeholder provider after startup failure: ${error instanceof Error ? error.message : String(error)}`);
   }
 }

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "pi-cliproxyapi-provider",
-  "version": "0.1.0",
+  "version": "0.2.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"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "cliproxyapi",
+    "provider",
+    "models.dev"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/0xRichardH/pi-cliproxyapi-provider.git"
@@ -14,17 +21,28 @@
     "url": "https://github.com/0xRichardH/pi-cliproxyapi-provider/issues"
   },
   "homepage": "https://github.com/0xRichardH/pi-cliproxyapi-provider#readme",
-  "files": ["src", "extensions", "data", "README.md", "LICENSE"],
+  "files": [
+    "src",
+    "extensions",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
   "pi": {
-    "extensions": ["./extensions"]
+    "extensions": [
+      "./extensions"
+    ]
   },
   "scripts": {
     "test": "node --test test/*.test.ts",
-    "test:unit": "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-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -35,7 +53,8 @@
     }
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.6",
     "@earendil-works/pi-coding-agent": "0.80.6",
-    "@earendil-works/pi-ai": "0.80.6"
+    "typescript": "^5.9.3"
   }
 }

package/src/cache.ts

@@ -1,18 +1,18 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+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): Promise<CacheEnvelope<T> | undefined> {
+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 parsed as CacheEnvelope<T>;
+    return { fetchedAt: parsed.fetchedAt, data: parseData(parsed.data) };
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
     return undefined;
@@ -20,36 +20,14 @@ export async function readCache<T>(path: string): Promise<CacheEnvelope<T> | und
 }
 
 export async function writeCache<T>(path: string, data: T, fetchedAt = Date.now()): Promise<void> {
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await writeFile(path, `${JSON.stringify({ fetchedAt, data }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-}
-
-export function isFresh(cache: Pick<CacheEnvelope<unknown>, "fetchedAt"> | undefined, ttlSeconds: number, now = Date.now()): boolean {
-  if (!cache || ttlSeconds <= 0 || cache.fetchedAt > now) return false;
-  return now - cache.fetchedAt < ttlSeconds * 1000;
-}
-
-export async function getCachedOrFetch<T>(options: {
-  path: string;
-  ttlSeconds: number;
-  fetchFresh: () => Promise<T>;
-  now?: number;
-  force?: boolean;
-}): Promise<{ data: T; source: "fresh" | "cache" | "stale"; error?: unknown }> {
-  const cached = await readCache<T>(options.path);
-  const now = options.now ?? Date.now();
-  if (!options.force && isFresh(cached, options.ttlSeconds, now)) {
-    return { data: cached!.data, source: "cache" };
-  }
-
+  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 {
-    const fresh = await options.fetchFresh();
-    await writeCache(options.path, fresh, now);
-    return { data: fresh, source: "fresh" };
-  } catch (error) {
-    if (cached) {
-      return { data: cached.data, source: "stale", error };
-    }
-    throw error;
+    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,185 @@
+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, parseModelsDevCatalog, readBundledModelsDevFallback } from "./models-dev.ts";
+import { buildProviderModels, type BuildProviderModelsResult } from "./provider.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;
+  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;
+  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 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"): Promise<CatalogRefreshResult> {
+    if (this.activeRefresh) {
+      if (this.activeRefreshTarget === target && this.activeRefreshMode === mode) return this.activeRefresh;
+      await this.activeRefresh;
+    }
+
+    this.activeRefreshTarget = target;
+    this.activeRefreshMode = mode;
+    this.activeRefresh = this.performRefresh(target, mode).finally(() => {
+      this.activeRefresh = undefined;
+      this.activeRefreshTarget = undefined;
+      this.activeRefreshMode = undefined;
+    });
+    return this.activeRefresh;
+  }
+
+  current(): CatalogSnapshot | undefined {
+    return this.snapshot;
+  }
+
+  private async performRefresh(target: RefreshTarget, mode: "background" | "manual"): 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 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,
+        );
+        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) {
+        models.error = error;
+      }
+    }
+
+    if (metadataResult.attempted) {
+      try {
+        const fresh = await fetchModelsDevCatalog(this.options.manualTimeoutMs ?? 10_000);
+        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) {
+        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) 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,
+      built: buildProviderModels(cpaModels, metadata, this.options.config.modelAliases),
+    };
+    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/commands.ts

@@ -1,9 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { existsSync, statSync } from "node:fs";
 import { DEFAULT_CONFIG, loadConfig, globalConfigPath, readConfigFile, writeConfigFile, type ConfigLayer } from "./config.ts";
-import { cpaModelsCachePath, discoverModels, modelsDevCachePath } from "./discovery.ts";
-import { buildProviderModels } from "./provider.ts";
-import { getDiscoveryApiKey } from "./auth.ts";
+import type { ProviderCatalog, CatalogSnapshot, RefreshTarget, SourceRefreshResult } from "./catalog.ts";
+import type { ProviderRuntime } from "./runtime.ts";
 
 function errorText(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
@@ -17,26 +15,30 @@ export function formatStatusFailure(config: ReturnType<typeof loadConfig>, error
     `Auth required: ${config.authRequired ? "yes" : "no"}`,
     "",
     "Run /cliproxyapi config to set the CLIProxyAPI base URL.",
-    `If you changed config or just ran /login ${config.providerName}, run /reload before selecting models.`,
+    `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(path: string): string {
-  if (!existsSync(path)) return "missing";
-  const seconds = Math.round((Date.now() - statSync(path).mtimeMs) / 1000);
-  if (seconds < 60) return `${seconds}s`;
-  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
-  return `${Math.round(seconds / 3600)}h`;
+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> {
@@ -61,9 +63,7 @@ export async function runConfig(ctx: ExtensionCommandContext): Promise<void> {
   }
   const defaults = existing ?? current;
 
-  if (existing) {
-    ctx.ui.notify(`Editing existing global config at ${path}:\n${JSON.stringify(redactConfig(existing), null, 2)}`, "info");
-  }
+  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;
@@ -71,89 +71,102 @@ export async function runConfig(ctx: ExtensionCommandContext): Promise<void> {
   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."
+    "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."
+        "Choose yes for CLIProxyAPI API keys.",
       )
     : false;
 
-  const config: ConfigLayer = {
+  writeConfigFile(path, {
     providerName: providerNameInput || defaults.providerName,
     baseUrl: baseUrlInput || defaults.baseUrl,
     authRequired,
     authHeader,
-  };
-  writeConfigFile(path, config);
-  ctx.ui.notify(`Saved CLIProxyAPI config to ${path}. Reloading pi to apply it...`, "info");
+  });
+  ctx.ui.notify(`Saved CLIProxyAPI config to ${path}. Reloading pi to apply connection changes...`, "info");
   await ctx.reload();
 }
 
-async function runStatus(ctx: ExtensionCommandContext, bundledModelsDevPath: string): Promise<void> {
-  const config = loadConfig(ctx.cwd);
-  try {
-    const discovery = await discoverModels({ config, bundledModelsDevPath, discoveryApiKey: await getDiscoveryApiKey(config.providerName) });
-    const built = buildProviderModels(discovery.cpaModels, discovery.modelsDevCatalog, config.modelAliases);
-    ctx.ui.notify([
-      `CLIProxyAPI provider: ${config.providerName}`,
-      `Base URL: ${config.baseUrl}`,
-      `Auth required: ${config.authRequired ? "yes" : "no"}`,
-      `CPA models: ${built.stats.total} (${built.stats.enriched} enriched, ${built.stats.unmatched} unmatched)`,
-      `CPA cache: ${discovery.sources.cpa}, age ${age(cpaModelsCachePath(config))}`,
-      `models.dev cache: ${discovery.sources.modelsDev}, age ${age(modelsDevCachePath())}`,
-    ].join("\n"), "info");
-  } catch (error) {
-    ctx.ui.notify(formatStatusFailure(config, error), "error");
-  }
+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)}` : ""}`,
+  ].join("\n");
 }
 
-async function runRefresh(ctx: ExtensionCommandContext, bundledModelsDevPath: string): Promise<void> {
-  const config = loadConfig(ctx.cwd);
-  try {
-    const discovery = await discoverModels({ config, bundledModelsDevPath, force: true, discoveryApiKey: await getDiscoveryApiKey(config.providerName) });
-    const built = buildProviderModels(discovery.cpaModels, discovery.modelsDevCatalog, config.modelAliases);
-    ctx.ui.notify(`Refreshed CLIProxyAPI caches. ${built.stats.total} CPA models, ${built.stats.enriched} enriched, ${built.stats.unmatched} unmatched. Run /reload to load refreshed models.`, "info");
-  } catch (error) {
-    ctx.ui.notify(`CLIProxyAPI refresh failed: ${errorText(error)}`, "error");
-  }
+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"}`;
 }
 
-async function runAliases(ctx: ExtensionCommandContext, bundledModelsDevPath: string): Promise<void> {
-  const config = loadConfig(ctx.cwd);
-  try {
-    const discovery = await discoverModels({ config, bundledModelsDevPath, discoveryApiKey: await getDiscoveryApiKey(config.providerName) });
-    const built = buildProviderModels(discovery.cpaModels, discovery.modelsDevCatalog, config.modelAliases);
-    const sample = built.stats.unmatchedModelIds.slice(0, 30);
-    const body = sample.length === 0
-      ? "All CPA models matched models.dev metadata."
-      : `Unmatched CPA models (${built.stats.unmatched}):\n${sample.map((id) => `  "${id}": "<models.dev-id>"`).join("\n")}`;
-    ctx.ui.notify(body, built.stats.unmatched ? "warning" : "info");
-  } catch (error) {
-    ctx.ui.notify(`CLIProxyAPI aliases failed: ${errorText(error)}`, "error");
-  }
+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;
 }
 
 export function cliproxyapiArgumentCompletions(prefix: string): Array<{ value: string; label: string }> {
-  return ["config", "status", "refresh", "aliases", "help"]
+  return ["config", "status", "refresh", "refresh models", "refresh metadata", "aliases", "help"]
     .filter((item) => item.startsWith(prefix))
     .map((value) => ({ value, label: value }));
 }
 
-export function registerCliproxyapiCommand(pi: ExtensionAPI, bundledModelsDevPath: string): void {
+export function registerCliproxyapiCommand(pi: ExtensionAPI, runtime?: ProviderRuntime, catalog?: ProviderCatalog): void {
   pi.registerCommand("cliproxyapi", {
-    description: "Configure and inspect the CLIProxyAPI provider.",
+    description: "Configure, refresh, and inspect the CLIProxyAPI provider.",
     getArgumentCompletions(prefix) {
       return cliproxyapiArgumentCompletions(prefix);
     },
     async handler(args, ctx) {
-      const subcommand = args.trim().split(/\s+/, 1)[0] || "help";
+      const [subcommand = "help", option] = args.trim().split(/\s+/);
       if (subcommand === "config") return runConfig(ctx);
-      if (subcommand === "status") return runStatus(ctx, bundledModelsDevPath);
-      if (subcommand === "refresh") return runRefresh(ctx, bundledModelsDevPath);
-      if (subcommand === "aliases") return runAliases(ctx, bundledModelsDevPath);
-      ctx.ui.notify("Usage: /cliproxyapi config|status|refresh|aliases\nAfter config or refresh, run /reload.", "info");
+      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 result = await runtime.refresh(target, "manual");
+        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;
+      }
+      ctx.ui.notify("Usage: /cliproxyapi config|status|refresh [models|metadata]|aliases", "info");
     },
   });
 }

package/src/config.ts

@@ -11,8 +11,6 @@ export const DEFAULT_CONFIG: CpaProviderConfig = {
   authRequired: true,
   authHeader: true,
   headers: {},
-  cpaCacheTtlSeconds: 60 * 60,
-  modelsDevCacheTtlSeconds: 24 * 60 * 60,
   modelsDevEnabled: true,
   modelAliases: {},
 };
@@ -127,13 +125,6 @@ function validateConfigLayer(value: unknown, path: string): ConfigLayer {
     }
   }
 
-  const ttlFields = ["cpaCacheTtlSeconds", "modelsDevCacheTtlSeconds"];
-  for (const field of ttlFields) {
-    if (record[field] !== undefined && (typeof record[field] !== "number" || !Number.isFinite(record[field]) || record[field] <= 0)) {
-      throw new Error(`${field} must be a positive number in config file: ${path}`);
-    }
-  }
-
   if (record.headers !== undefined && !isStringMap(record.headers)) {
     throw new Error(`headers must be an object with string values in config file: ${path}`);
   }

package/src/cpa.ts

@@ -16,13 +16,8 @@ export function modelsEndpoint(baseUrl: string): string {
   return `${baseUrl.replace(/\/+$/, "")}/models`;
 }
 
-export function parseCpaModelsResponse(payload: unknown): CpaModel[] {
-  const response = payload as CpaModelsResponse;
-  if (!response || typeof response !== "object" || !Array.isArray(response.data)) {
-    throw new Error("CPA /v1/models response must contain a data array");
-  }
-
-  return response.data.flatMap((entry) => {
+function parseCpaModelEntries(entries: unknown[]): CpaModel[] {
+  const models = entries.flatMap((entry) => {
     if (!entry || typeof entry !== "object") return [];
     const record = entry as Record<string, unknown>;
     if (typeof record.id !== "string" || record.id.trim() === "") return [];
@@ -33,6 +28,25 @@ export function parseCpaModelsResponse(payload: unknown): CpaModel[] {
       created: typeof record.created === "number" ? record.created : undefined,
     }];
   });
+
+  const unique = new Map<string, CpaModel>();
+  for (const model of models) unique.set(model.id, model);
+  return [...unique.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function parseCpaModelsCache(payload: unknown): CpaModel[] {
+  if (!Array.isArray(payload)) throw new Error("CPA model snapshot must be an array");
+  const models = parseCpaModelEntries(payload);
+  if (models.length !== payload.length) throw new Error("CPA model snapshot contains invalid entries");
+  return models;
+}
+
+export function parseCpaModelsResponse(payload: unknown): CpaModel[] {
+  const response = payload as CpaModelsResponse;
+  if (!response || typeof response !== "object" || !Array.isArray(response.data)) {
+    throw new Error("CPA /v1/models response must contain a data array");
+  }
+  return parseCpaModelEntries(response.data);
 }
 
 export async function fetchCpaModels(baseUrl: string, headers: Record<string, string> = {}, timeoutMs?: number): Promise<CpaModel[]> {