pi-cliproxyapi-provider 0.1.0

package/src/cache.ts

@@ -0,0 +1,55 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export interface CacheEnvelope<T> {
+  fetchedAt: number;
+  data: T;
+}
+
+export async function readCache<T>(path: string): 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>;
+  } 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> {
+  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" };
+  }
+
+  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;
+  }
+}

package/src/commands.ts

@@ -0,0 +1,159 @@
+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";
+
+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 changed config or just ran /login ${config.providerName}, run /reload before selecting 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`;
+}
+
+export async function runConfig(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("/cliproxyapi config 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;
+
+  const config: ConfigLayer = {
+    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");
+  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");
+  }
+}
+
+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");
+  }
+}
+
+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");
+  }
+}
+
+export function cliproxyapiArgumentCompletions(prefix: string): Array<{ value: string; label: string }> {
+  return ["config", "status", "refresh", "aliases", "help"]
+    .filter((item) => item.startsWith(prefix))
+    .map((value) => ({ value, label: value }));
+}
+
+export function registerCliproxyapiCommand(pi: ExtensionAPI, bundledModelsDevPath: string): void {
+  pi.registerCommand("cliproxyapi", {
+    description: "Configure and inspect the CLIProxyAPI provider.",
+    getArgumentCompletions(prefix) {
+      return cliproxyapiArgumentCompletions(prefix);
+    },
+    async handler(args, ctx) {
+      const subcommand = args.trim().split(/\s+/, 1)[0] || "help";
+      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");
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { CpaProviderConfig } from "./types.ts";
+
+export type ConfigLayer = Partial<CpaProviderConfig>;
+
+export const DEFAULT_CONFIG: CpaProviderConfig = {
+  providerName: "cpa",
+  baseUrl: "http://localhost:8317/v1",
+  authRequired: true,
+  authHeader: true,
+  headers: {},
+  cpaCacheTtlSeconds: 60 * 60,
+  modelsDevCacheTtlSeconds: 24 * 60 * 60,
+  modelsDevEnabled: true,
+  modelAliases: {},
+};
+
+export function globalConfigPath(): string {
+  return join(homedir(), ".pi", "agent", "pi-cliproxyapi-provider", "config.json");
+}
+
+export function projectConfigPath(cwd: string): string {
+  return join(cwd, ".pi", "pi-cliproxyapi-provider", "config.json");
+}
+
+export function cacheDir(): string {
+  return join(homedir(), ".cache", "pi-cliproxyapi-provider");
+}
+
+export function providerCacheKey(config: Pick<CpaProviderConfig, "providerName" | "baseUrl">): string {
+  return Buffer.from(`${config.providerName}\n${config.baseUrl}`).toString("base64url");
+}
+
+export function parseBooleanEnv(value: string | undefined): boolean | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return undefined;
+}
+
+function normalizeConfig(config: CpaProviderConfig): CpaProviderConfig {
+  return {
+    ...config,
+    authHeader: config.authRequired ? config.authHeader : false,
+  };
+}
+
+function safeProjectConfig(projectConfig?: ConfigLayer): ConfigLayer | undefined {
+  if (!projectConfig) return undefined;
+  return {
+    ...(projectConfig.modelAliases !== undefined ? { modelAliases: projectConfig.modelAliases } : {}),
+  };
+}
+
+function projectConfigLayer(value: unknown, path: string): ConfigLayer {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Project config file must contain a JSON object: ${path}`);
+  }
+
+  const record = value as Record<string, unknown>;
+  if (record.modelAliases !== undefined && !isStringMap(record.modelAliases)) {
+    throw new Error(`modelAliases must be an object with string values in project config file: ${path}`);
+  }
+
+  return safeProjectConfig(record as ConfigLayer) ?? {};
+}
+
+function mergeLayer(base: CpaProviderConfig, layer?: ConfigLayer): CpaProviderConfig {
+  if (!layer) return base;
+  return {
+    ...base,
+    ...layer,
+    headers: { ...base.headers, ...(layer.headers ?? {}) },
+    modelAliases: { ...base.modelAliases, ...(layer.modelAliases ?? {}) },
+  };
+}
+
+function envLayer(env: NodeJS.ProcessEnv): ConfigLayer {
+  const authRequired = parseBooleanEnv(env.CLIPROXYAPI_AUTH_REQUIRED);
+  const authHeader = parseBooleanEnv(env.CLIPROXYAPI_AUTH_HEADER);
+  const modelsDevEnabled = parseBooleanEnv(env.CLIPROXYAPI_MODELS_DEV_ENABLED);
+  return {
+    ...(env.CLIPROXYAPI_BASE_URL ? { baseUrl: env.CLIPROXYAPI_BASE_URL } : {}),
+    ...(env.CLIPROXYAPI_PROVIDER_NAME ? { providerName: env.CLIPROXYAPI_PROVIDER_NAME } : {}),
+    ...(authRequired !== undefined ? { authRequired } : {}),
+    ...(authHeader !== undefined ? { authHeader } : {}),
+    ...(modelsDevEnabled !== undefined ? { modelsDevEnabled } : {}),
+  };
+}
+
+export function mergeConfigLayers(
+  globalConfig?: ConfigLayer,
+  projectConfig?: ConfigLayer,
+  env: NodeJS.ProcessEnv = process.env,
+): CpaProviderConfig {
+  const envConfig = envLayer(env);
+  return normalizeConfig(mergeLayer(mergeLayer(mergeLayer(DEFAULT_CONFIG, globalConfig), safeProjectConfig(projectConfig)), envConfig));
+}
+
+function isStringMap(value: unknown): value is Record<string, string> {
+  return !!value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function validateConfigLayer(value: unknown, path: string): ConfigLayer {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Config file must contain a JSON object: ${path}`);
+  }
+
+  const record = value as Record<string, unknown>;
+  const stringFields = ["providerName", "baseUrl"];
+  for (const field of stringFields) {
+    if (record[field] !== undefined && typeof record[field] !== "string") {
+      throw new Error(`${field} must be a string in config file: ${path}`);
+    }
+  }
+
+  const booleanFields = ["authRequired", "authHeader", "modelsDevEnabled"];
+  for (const field of booleanFields) {
+    if (record[field] !== undefined && typeof record[field] !== "boolean") {
+      throw new Error(`${field} must be a boolean in config file: ${path}`);
+    }
+  }
+
+  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}`);
+  }
+  if (record.modelAliases !== undefined && !isStringMap(record.modelAliases)) {
+    throw new Error(`modelAliases must be an object with string values in config file: ${path}`);
+  }
+
+  return record as ConfigLayer;
+}
+
+export function readConfigFile(path: string): ConfigLayer | undefined {
+  if (!existsSync(path)) return undefined;
+  return validateConfigLayer(JSON.parse(readFileSync(path, "utf8")), path);
+}
+
+export function readProjectConfigFile(path: string): ConfigLayer | undefined {
+  if (!existsSync(path)) return undefined;
+  return projectConfigLayer(JSON.parse(readFileSync(path, "utf8")), path);
+}
+
+export function loadConfig(cwd: string, env: NodeJS.ProcessEnv = process.env): CpaProviderConfig {
+  return mergeConfigLayers(readConfigFile(globalConfigPath()), readProjectConfigFile(projectConfigPath(cwd)), env);
+}
+
+export function writeConfigFile(path: string, config: ConfigLayer): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+}

package/src/cpa.ts

@@ -0,0 +1,49 @@
+import { withNetworkTimeout } from "./network.ts";
+
+export interface CpaModel {
+  id: string;
+  object?: string;
+  owned_by?: string;
+  created?: number;
+}
+
+export interface CpaModelsResponse {
+  object?: string;
+  data?: unknown[];
+}
+
+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) => {
+    if (!entry || typeof entry !== "object") return [];
+    const record = entry as Record<string, unknown>;
+    if (typeof record.id !== "string" || record.id.trim() === "") return [];
+    return [{
+      id: record.id,
+      object: typeof record.object === "string" ? record.object : undefined,
+      owned_by: typeof record.owned_by === "string" ? record.owned_by : undefined,
+      created: typeof record.created === "number" ? record.created : undefined,
+    }];
+  });
+}
+
+export async function fetchCpaModels(baseUrl: string, headers: Record<string, string> = {}, timeoutMs?: number): Promise<CpaModel[]> {
+  return withNetworkTimeout(async (signal) => {
+    const response = await fetch(modelsEndpoint(baseUrl), {
+      headers: { Accept: "application/json", ...headers },
+      signal,
+    });
+    if (!response.ok) {
+      throw new Error(`CPA model discovery failed: HTTP ${response.status} ${response.statusText}`);
+    }
+    return parseCpaModelsResponse(await response.json());
+  }, timeoutMs, "CPA model discovery");
+}

package/src/discovery.ts

@@ -0,0 +1,98 @@
+import { join } from "node:path";
+import { cacheDir, providerCacheKey, type CpaProviderConfig } from "./config.ts";
+import { fetchCpaModels, type CpaModel } from "./cpa.ts";
+import { getCachedOrFetch, isFresh, readCache } from "./cache.ts";
+import { fetchModelsDevCatalog, readBundledModelsDevFallback } from "./models-dev.ts";
+import type { ModelsDevCatalog } from "./types.ts";
+
+export interface DiscoveryResult {
+  cpaModels: CpaModel[];
+  modelsDevCatalog: ModelsDevCatalog;
+  sources: {
+    cpa: "fresh" | "cache" | "stale";
+    modelsDev: "fresh" | "cache" | "stale" | "bundled" | "disabled";
+  };
+  errors: {
+    cpa?: unknown;
+    modelsDev?: unknown;
+  };
+}
+
+export function cpaModelsCachePath(config: CpaProviderConfig): string {
+  return join(cacheDir(), providerCacheKey(config), "cpa-models.json");
+}
+
+export function modelsDevCachePath(): string {
+  return join(cacheDir(), "models-dev.json");
+}
+
+export function discoveryHeaders(config: CpaProviderConfig, apiKey?: string): Record<string, string> {
+  return {
+    ...config.headers,
+    ...(config.authHeader && apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+  };
+}
+
+export async function discoverModels(options: {
+  config: CpaProviderConfig;
+  bundledModelsDevPath: string;
+  force?: boolean;
+  discoveryApiKey?: string;
+}): Promise<DiscoveryResult> {
+  const cpa = await getCachedOrFetch({
+    path: cpaModelsCachePath(options.config),
+    ttlSeconds: options.config.cpaCacheTtlSeconds,
+    force: options.force,
+    fetchFresh: () => fetchCpaModels(options.config.baseUrl, discoveryHeaders(options.config, options.discoveryApiKey)),
+  });
+
+  if (!options.config.modelsDevEnabled) {
+    return {
+      cpaModels: cpa.data,
+      modelsDevCatalog: {},
+      sources: { cpa: cpa.source, modelsDev: "disabled" },
+      errors: { cpa: cpa.error },
+    };
+  }
+
+  if (!options.force) {
+    const cachedModelsDev = await readCache<ModelsDevCatalog>(modelsDevCachePath());
+    if (isFresh(cachedModelsDev, options.config.modelsDevCacheTtlSeconds)) {
+      return {
+        cpaModels: cpa.data,
+        modelsDevCatalog: cachedModelsDev.data,
+        sources: { cpa: cpa.source, modelsDev: "cache" },
+        errors: { cpa: cpa.error },
+      };
+    }
+
+    return {
+      cpaModels: cpa.data,
+      modelsDevCatalog: await readBundledModelsDevFallback(options.bundledModelsDevPath),
+      sources: { cpa: cpa.source, modelsDev: "bundled" },
+      errors: { cpa: cpa.error },
+    };
+  }
+
+  try {
+    const modelsDev = await getCachedOrFetch({
+      path: modelsDevCachePath(),
+      ttlSeconds: options.config.modelsDevCacheTtlSeconds,
+      force: true,
+      fetchFresh: fetchModelsDevCatalog,
+    });
+    return {
+      cpaModels: cpa.data,
+      modelsDevCatalog: modelsDev.data,
+      sources: { cpa: cpa.source, modelsDev: modelsDev.source },
+      errors: { cpa: cpa.error, modelsDev: modelsDev.error },
+    };
+  } catch (error) {
+    return {
+      cpaModels: cpa.data,
+      modelsDevCatalog: await readBundledModelsDevFallback(options.bundledModelsDevPath),
+      sources: { cpa: cpa.source, modelsDev: "bundled" },
+      errors: { cpa: cpa.error, modelsDev: error },
+    };
+  }
+}

package/src/matching.ts

@@ -0,0 +1,73 @@
+import type { CpaModel } from "./cpa.ts";
+import type { ModelsDevCatalog, ModelsDevMetadata } from "./types.ts";
+
+const CANONICAL_OWNER_PREFIXES: Record<string, string> = {
+  openai: "openai",
+  anthropic: "anthropic",
+  google: "google",
+  deepseek: "deepseek",
+  mistral: "mistral",
+  xai: "xai",
+  zhipuai: "zhipuai",
+  alibaba: "alibaba",
+  moonshotai: "moonshotai",
+  minimax: "minimax",
+  nvidia: "nvidia",
+  cohere: "cohere",
+};
+
+export type MetadataMatchMethod = "alias" | "exact" | "owner-prefix" | "suffix" | "normalized-suffix";
+
+export interface MetadataMatch {
+  metadataId: string;
+  metadata: ModelsDevMetadata;
+  method: MetadataMatchMethod;
+}
+
+export function normalizeModelName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function oneMatch(candidates: string[]): string | undefined {
+  const unique = [...new Set(candidates)];
+  return unique.length === 1 ? unique[0] : undefined;
+}
+
+export function findMetadataMatch(
+  cpaModel: Pick<CpaModel, "id" | "owned_by">,
+  catalog: ModelsDevCatalog,
+  aliases: Record<string, string>,
+): MetadataMatch | undefined {
+  const alias = aliases[cpaModel.id];
+  if (alias && catalog[alias]) {
+    return { metadataId: alias, metadata: catalog[alias], method: "alias" };
+  }
+
+  if (catalog[cpaModel.id]) {
+    return { metadataId: cpaModel.id, metadata: catalog[cpaModel.id], method: "exact" };
+  }
+
+  const owner = cpaModel.owned_by?.trim().toLowerCase();
+  const canonicalOwner = owner ? CANONICAL_OWNER_PREFIXES[owner] : undefined;
+  if (canonicalOwner) {
+    const ownerKey = `${canonicalOwner}/${cpaModel.id}`;
+    if (catalog[ownerKey]) {
+      return { metadataId: ownerKey, metadata: catalog[ownerKey], method: "owner-prefix" };
+    }
+  }
+
+  const suffixKey = oneMatch(Object.keys(catalog).filter((key) => key.endsWith(`/${cpaModel.id}`)));
+  if (suffixKey) {
+    return { metadataId: suffixKey, metadata: catalog[suffixKey], method: "suffix" };
+  }
+
+  const normalizedId = normalizeModelName(cpaModel.id);
+  const normalizedSuffixKey = oneMatch(
+    Object.keys(catalog).filter((key) => normalizeModelName(key.split("/").at(-1) ?? key) === normalizedId),
+  );
+  if (normalizedSuffixKey) {
+    return { metadataId: normalizedSuffixKey, metadata: catalog[normalizedSuffixKey], method: "normalized-suffix" };
+  }
+
+  return undefined;
+}

package/src/models-dev.ts

@@ -0,0 +1,50 @@
+import { readFile } from "node:fs/promises";
+import type { ModelsDevCatalog, ModelsDevMetadata } from "./types.ts";
+import { withNetworkTimeout } from "./network.ts";
+
+export const MODELS_DEV_URL = "https://models.dev/models.json";
+
+function isMetadata(value: unknown): value is ModelsDevMetadata {
+  return !!value && typeof value === "object" && typeof (value as { id?: unknown }).id === "string";
+}
+
+export function parseModelsDevCatalog(payload: unknown): ModelsDevCatalog {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("models.dev catalog must be a JSON object");
+  }
+
+  const record = payload as Record<string, unknown>;
+  const catalog: ModelsDevCatalog = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    const provider = value as { models?: unknown };
+    if (provider && typeof provider === "object" && provider.models && typeof provider.models === "object") {
+      for (const [modelId, metadata] of Object.entries(provider.models as Record<string, unknown>)) {
+        if (!isMetadata(metadata)) continue;
+        const canonicalId = metadata.id.includes("/") ? metadata.id : `${key}/${modelId}`;
+        catalog[canonicalId] = { ...metadata, id: canonicalId };
+      }
+      continue;
+    }
+
+    if (isMetadata(value)) {
+      catalog[key] = value;
+    }
+  }
+
+  return catalog;
+}
+
+export async function fetchModelsDevCatalog(timeoutMs?: number): Promise<ModelsDevCatalog> {
+  return withNetworkTimeout(async (signal) => {
+    const response = await fetch(MODELS_DEV_URL, { headers: { Accept: "application/json" }, signal });
+    if (!response.ok) {
+      throw new Error(`models.dev fetch failed: HTTP ${response.status} ${response.statusText}`);
+    }
+    return parseModelsDevCatalog(await response.json());
+  }, timeoutMs, "models.dev fetch");
+}
+
+export async function readBundledModelsDevFallback(path: string): Promise<ModelsDevCatalog> {
+  return parseModelsDevCatalog(JSON.parse(await readFile(path, "utf8")));
+}

package/src/network.ts

@@ -0,0 +1,28 @@
+export async function withNetworkTimeout<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  timeoutMs = 10_000,
+  label = "network request",
+): Promise<T> {
+  const controller = new AbortController();
+  const timeoutError = new Error(`${label} timed out after ${timeoutMs}ms`);
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const operationPromise = operation(controller.signal);
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      controller.abort(timeoutError);
+      reject(timeoutError);
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([operationPromise, timeoutPromise]);
+  } catch (error) {
+    if (controller.signal.aborted && controller.signal.reason instanceof Error) {
+      throw controller.signal.reason;
+    }
+    throw error;
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}