@samrito/pi-cliproxyapi-provider 0.16.0

package/src/config.ts

@@ -0,0 +1,296 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type {
+  CpaProviderConfig,
+  ProviderModelOverride,
+  ProviderModelOverrideLayer,
+  ProviderModelOverrideLayers,
+  ProviderModelOverrides,
+} from "./types.ts";
+
+export type ConfigLayer = Partial<CpaProviderConfig>;
+
+export const CONTEXT_WINDOW_PRESETS = [128000, 272000, 512000, 1000000] as const;
+export const MAX_TOKEN_PRESETS = [4096, 8192, 16384, 32768, 65536, 128000] as const;
+
+export const DEFAULT_CONFIG: CpaProviderConfig = {
+  providerName: "cpa",
+  baseUrl: "http://localhost:8317/v1",
+  authRequired: true,
+  authHeader: true,
+  headers: {},
+  modelsDevEnabled: true,
+  metadataFallbackProvider: "openrouter",
+  modelAliases: {},
+  modelOverrides: {},
+};
+
+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 normalizeMetadataFallbackProvider(value: string | null): string | null {
+  return value?.trim().toLowerCase() === "none" ? null : value;
+}
+
+function normalizeConfig(config: CpaProviderConfig): CpaProviderConfig {
+  return {
+    ...config,
+    authHeader: config.authRequired ? config.authHeader : false,
+    metadataFallbackProvider: normalizeMetadataFallbackProvider(config.metadataFallbackProvider),
+  };
+}
+
+function safeProjectConfig(projectConfig?: ConfigLayer): ConfigLayer | undefined {
+  if (!projectConfig) return undefined;
+  return {
+    ...(projectConfig.metadataFallbackProvider !== undefined
+      ? { metadataFallbackProvider: projectConfig.metadataFallbackProvider }
+      : {}),
+    ...(projectConfig.modelAliases !== undefined ? { modelAliases: projectConfig.modelAliases } : {}),
+    ...(projectConfig.modelOverrides !== undefined ? { modelOverrides: projectConfig.modelOverrides } : {}),
+  };
+}
+
+function mergeModelOverrides(
+  base: ProviderModelOverrides,
+  layer: ProviderModelOverrideLayers | undefined,
+): ProviderModelOverrides {
+  if (!layer) return base;
+  const merged = { ...base };
+  for (const [modelId, override] of Object.entries(layer)) {
+    const next = { ...merged[modelId] } as ProviderModelOverride;
+    for (const field of ["reasoning", "contextWindow", "maxTokens"] as const) {
+      const value = override[field];
+      if (value === null) delete next[field];
+      else if (value !== undefined) (next as Record<string, boolean | number>)[field] = value;
+    }
+    if (Object.keys(next).length === 0) delete merged[modelId];
+    else merged[modelId] = next;
+  }
+  return merged;
+}
+
+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.metadataFallbackProvider !== undefined &&
+    record.metadataFallbackProvider !== null &&
+    (typeof record.metadataFallbackProvider !== "string" || !record.metadataFallbackProvider.trim())
+  ) {
+    throw new Error(`metadataFallbackProvider must be a non-empty string or null in project config file: ${path}`);
+  }
+  if (record.modelAliases !== undefined && !isStringMap(record.modelAliases)) {
+    throw new Error(`modelAliases must be an object with string values in project config file: ${path}`);
+  }
+  const modelOverrides = record.modelOverrides === undefined
+    ? undefined
+    : parseModelOverrides(record.modelOverrides, "project");
+
+  return safeProjectConfig({ ...record, ...(modelOverrides ? { modelOverrides } : {}) } 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 ?? {}) },
+    modelOverrides: mergeModelOverrides(base.modelOverrides, layer.modelOverrides),
+  };
+}
+
+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);
+  const metadataFallbackProvider = env.CLIPROXYAPI_METADATA_FALLBACK_PROVIDER?.trim();
+  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 } : {}),
+    ...(metadataFallbackProvider ? { metadataFallbackProvider } : {}),
+  };
+}
+
+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 isAllowedPreset(value: unknown, presets: readonly number[]): value is number {
+  return typeof value === "number" && presets.includes(value);
+}
+
+function parseModelOverrides(value: unknown, scope: string): ProviderModelOverrideLayers {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`modelOverrides must be an object in ${scope} config file`);
+  }
+
+  const parsed: ProviderModelOverrideLayers = {};
+  for (const [modelId, rawOverride] of Object.entries(value)) {
+    if (!modelId.trim()) throw new Error(`modelOverrides keys must be non-empty model IDs in ${scope} config file`);
+    if (!rawOverride || typeof rawOverride !== "object" || Array.isArray(rawOverride)) {
+      throw new Error(`modelOverrides.${modelId} must be an object in ${scope} config file`);
+    }
+
+    const record = rawOverride as Record<string, unknown>;
+    const unknown = Object.keys(record).filter(
+      (key) => key !== "reasoning" && key !== "contextWindow" && key !== "maxTokens",
+    );
+    if (unknown.length > 0) {
+      throw new Error(`modelOverrides.${modelId} contains unsupported fields: ${unknown.join(", ")}`);
+    }
+    const nullable = scope === "project";
+    if (record.reasoning !== undefined && typeof record.reasoning !== "boolean" && !(nullable && record.reasoning === null)) {
+      throw new Error(`modelOverrides.${modelId}.reasoning must be a boolean${nullable ? " or null" : ""} in ${scope} config file`);
+    }
+    const presets = { contextWindow: CONTEXT_WINDOW_PRESETS, maxTokens: MAX_TOKEN_PRESETS };
+    for (const field of ["contextWindow", "maxTokens"] as const) {
+      const value = record[field];
+      if (value !== undefined && !isAllowedPreset(value, presets[field]) && !(nullable && value === null)) {
+        throw new Error(`modelOverrides.${modelId}.${field} must be one of ${presets[field].join(", ")}${nullable ? " or null" : ""} in ${scope} config file`);
+      }
+    }
+
+    parsed[modelId] = {
+      ...(record.reasoning !== undefined ? { reasoning: record.reasoning as boolean | null } : {}),
+      ...(record.contextWindow !== undefined ? { contextWindow: record.contextWindow as number | null } : {}),
+      ...(record.maxTokens !== undefined ? { maxTokens: record.maxTokens as number | null } : {}),
+    } satisfies ProviderModelOverrideLayer;
+  }
+  return parsed;
+}
+
+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}`);
+    }
+  }
+  if (
+    record.metadataFallbackProvider !== undefined &&
+    record.metadataFallbackProvider !== null &&
+    (typeof record.metadataFallbackProvider !== "string" || !record.metadataFallbackProvider.trim())
+  ) {
+    throw new Error(`metadataFallbackProvider must be a non-empty string or null 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}`);
+    }
+  }
+
+  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}`);
+  }
+  const modelOverrides = record.modelOverrides === undefined
+    ? undefined
+    : parseModelOverrides(record.modelOverrides, "global");
+
+  return { ...record, ...(modelOverrides ? { modelOverrides } : {}) } 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 });
+}
+
+export function loadModelOverrideLayers(cwd: string): {
+  global: ProviderModelOverrideLayers;
+  project: ProviderModelOverrideLayers;
+} {
+  return {
+    global: (readConfigFile(globalConfigPath())?.modelOverrides ?? {}) as ProviderModelOverrideLayers,
+    project: (readProjectConfigFile(projectConfigPath(cwd))?.modelOverrides ?? {}) as ProviderModelOverrideLayers,
+  };
+}
+
+export function saveModelOverride(
+  cwd: string,
+  modelId: string,
+  override: ProviderModelOverrideLayer,
+): { path: string; overrides: ProviderModelOverrideLayers } {
+  const path = projectConfigPath(cwd);
+  let raw: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`Config file must contain a JSON object: ${path}`);
+    }
+    raw = parsed as Record<string, unknown>;
+  }
+
+  const existing = raw.modelOverrides === undefined
+    ? {}
+    : parseModelOverrides(raw.modelOverrides, "project");
+  const next = { ...existing };
+  if (Object.keys(override).length === 0) delete next[modelId];
+  else next[modelId] = override;
+  writeConfigFile(path, { ...raw, modelOverrides: next } as ConfigLayer);
+  return { path, overrides: next };
+}

package/src/cpa.ts

@@ -0,0 +1,68 @@
+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`;
+}
+
+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 [];
+    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,
+    }];
+  });
+
+  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,
+  signal?: AbortSignal,
+): Promise<CpaModel[]> {
+  return withNetworkTimeout(async (reqSignal) => {
+    const response = await fetch(modelsEndpoint(baseUrl), {
+      headers: { Accept: "application/json", ...headers },
+      signal: reqSignal,
+    });
+    if (!response.ok) {
+      throw new Error(`CPA model discovery failed: HTTP ${response.status} ${response.statusText}`);
+    }
+    return parseCpaModelsResponse(await response.json());
+  }, timeoutMs, "CPA model discovery", signal);
+}

package/src/discovery.ts

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import { cacheDir, providerCacheKey } from "./config.ts";
+import type { CpaProviderConfig } from "./types.ts";
+
+export function cpaModelsCachePath(config: CpaProviderConfig): string {
+  return join(cacheDir(), providerCacheKey(config), "cpa-models.json");
+}
+
+export function modelsDevCachePath(): string {
+  // Keep provider-catalog metadata separate from the former lab-level
+  // models.json cache, which omitted provider pricing.
+  return join(cacheDir(), "models-dev-api.json");
+}
+
+export function discoveryHeaders(config: CpaProviderConfig, apiKey?: string): Record<string, string> {
+  return {
+    ...config.headers,
+    ...(config.authHeader && apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+  };
+}

package/src/matching.ts

@@ -0,0 +1,150 @@
+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" | "owner-hint" | "suffix" | "normalized-suffix" | "provider-fallback";
+
+export interface MetadataMatch {
+  metadataId: string;
+  metadata: ModelsDevMetadata;
+  method: MetadataMatchMethod;
+}
+
+export function normalizeModelName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function metadataModelName(metadataId: string, metadata: ModelsDevMetadata): string {
+  return metadata.id.split("/").at(-1) ?? metadataId.split("/").at(-1) ?? metadataId;
+}
+
+function oneMatch(candidates: string[]): string | undefined {
+  const unique = [...new Set(candidates)];
+  return unique.length === 1 ? unique[0] : undefined;
+}
+
+function identifierTokens(value: string): string[] {
+  return value.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+function containsContiguousTokens(container: string[], sequence: string[]): boolean {
+  if (sequence.length === 0 || sequence.length > container.length) return false;
+  return container.some((_, start) =>
+    start + sequence.length <= container.length &&
+    sequence.every((token, offset) => container[start + offset] === token)
+  );
+}
+
+function sourceProvider(metadataId: string, metadata: ModelsDevMetadata): string {
+  // sourceProvider is retained by current catalog snapshots. The prefix fallback
+  // keeps older bundled/cache snapshots useful until they are refreshed.
+  return metadata.sourceProvider ?? metadataId.split("/")[0] ?? metadataId;
+}
+
+function ownerHintMatch(
+  owner: string | undefined,
+  candidates: string[],
+  catalog: ModelsDevCatalog,
+): string | undefined {
+  if (!owner) return undefined;
+  const ownerTokens = identifierTokens(owner);
+  const matches = candidates.flatMap((metadataId) => {
+    const metadata = catalog[metadataId];
+    if (!metadata) return [];
+    const provider = sourceProvider(metadataId, metadata);
+    const providerTokens = identifierTokens(provider);
+    if (!containsContiguousTokens(ownerTokens, providerTokens)) return [];
+    return [{ metadataId, tokenCount: providerTokens.length, characterCount: provider.length }];
+  });
+  if (matches.length === 0) return undefined;
+
+  const bestTokenCount = Math.max(...matches.map((match) => match.tokenCount));
+  const mostTokens = matches.filter((match) => match.tokenCount === bestTokenCount);
+  const bestCharacterCount = Math.max(...mostTokens.map((match) => match.characterCount));
+  return oneMatch(
+    mostTokens
+      .filter((match) => match.characterCount === bestCharacterCount)
+      .map((match) => match.metadataId),
+  );
+}
+
+export function findMetadataMatch(
+  cpaModel: Pick<CpaModel, "id" | "owned_by">,
+  catalog: ModelsDevCatalog,
+  aliases: Record<string, string>,
+  fallbackProvider?: string | null,
+): 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 catalogKeys = Object.keys(catalog);
+  const exactMetadataCandidates = catalogKeys.filter((key) => catalog[key]?.id === cpaModel.id);
+  const exactMetadataKey = oneMatch(exactMetadataCandidates);
+  if (exactMetadataKey) {
+    return { metadataId: exactMetadataKey, metadata: catalog[exactMetadataKey], method: "exact" };
+  }
+
+  const suffixCandidates = catalogKeys.filter((key) =>
+    metadataModelName(key, catalog[key]) === cpaModel.id
+  );
+  const normalizedId = normalizeModelName(cpaModel.id);
+  const normalizedSuffixCandidates = catalogKeys.filter(
+    (key) => normalizeModelName(metadataModelName(key, catalog[key])) === normalizedId,
+  );
+  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 hintedKey = ownerHintMatch(owner, normalizedSuffixCandidates, catalog);
+  if (hintedKey) {
+    return { metadataId: hintedKey, metadata: catalog[hintedKey], method: "owner-hint" };
+  }
+
+  const suffixKey = oneMatch(suffixCandidates);
+  if (suffixKey) {
+    return { metadataId: suffixKey, metadata: catalog[suffixKey], method: "suffix" };
+  }
+
+  const normalizedSuffixKey = oneMatch(normalizedSuffixCandidates);
+  if (normalizedSuffixKey) {
+    return { metadataId: normalizedSuffixKey, metadata: catalog[normalizedSuffixKey], method: "normalized-suffix" };
+  }
+
+  if (fallbackProvider) {
+    const normalizedFallbackProvider = fallbackProvider.trim().toLowerCase();
+    const fallbackKey = oneMatch(normalizedSuffixCandidates.filter((metadataId) => {
+      const metadata = catalog[metadataId];
+      return metadata && sourceProvider(metadataId, metadata).toLowerCase() === normalizedFallbackProvider;
+    }));
+    if (fallbackKey) {
+      return { metadataId: fallbackKey, metadata: catalog[fallbackKey], method: "provider-fallback" };
+    }
+  }
+
+  return undefined;
+}

package/src/model-api.ts

@@ -0,0 +1,26 @@
+import type { ProviderModelConfigLike } from "./types.ts";
+
+export interface ModelApiContext {
+  availableModelId: string;
+  metadataModelId?: string;
+}
+
+const GPT_5_6_MODEL = /^gpt-5\.6(?:-|$)/;
+
+function modelName(id: string): string {
+  return id.slice(id.lastIndexOf("/") + 1);
+}
+
+export function isGpt56Model(context: ModelApiContext): boolean {
+  const ids = [context.availableModelId, context.metadataModelId].filter((id): id is string => id !== undefined);
+  return ids.some((id) => GPT_5_6_MODEL.test(modelName(id)));
+}
+
+/**
+ * Select a model-level API when a mixed CLIProxyAPI catalog cannot share the
+ * provider default. GPT-5.6, including Codex variants, uses the Responses API
+ * so Pi receives the Responses usage shape needed for token-cost accounting.
+ */
+export function getModelApiOverride(context: ModelApiContext): ProviderModelConfigLike["api"] | undefined {
+  return isGpt56Model(context) ? "openai-responses" : undefined;
+}

package/src/model-capabilities.ts

@@ -0,0 +1,65 @@
+import type { ThinkingLevelMap } from "@earendil-works/pi-ai";
+
+export interface ModelCapabilityContext {
+  availableModelId: string;
+  metadataModelId?: string;
+}
+
+export interface ModelCapabilityOverrides {
+  reasoning?: boolean;
+  thinkingLevelMap?: ThinkingLevelMap;
+}
+
+interface ModelCapabilityRule {
+  matches: (context: ModelCapabilityContext) => boolean;
+  overrides: ModelCapabilityOverrides;
+}
+
+/**
+ * Fallback level map for the GPT-5.6 family, used only when models.dev publishes
+ * no effort list for the model.
+ *
+ * `minimal` is explicitly unsupported. Measured against a live CLIProxyAPI
+ * instance, gpt-5.6-sol, -terra, and -luna all answer
+ * `400 level "minimal" not supported, valid levels: low, medium, high, xhigh, max`,
+ * so offering it produces a failing request. models.dev omits `minimal` for the
+ * same models, which is why this rule is the fallback rather than the source of
+ * truth; it stays correct by hiding what the model does not accept.
+ */
+const GPT_5_6_THINKING_LEVEL_MAP: ThinkingLevelMap = {
+  off: "none",
+  minimal: null,
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max",
+};
+
+function includesModelFamily(context: ModelCapabilityContext, family: string): boolean {
+  return [context.availableModelId, context.metadataModelId]
+    .filter((id): id is string => id !== undefined)
+    .some((id) => id.includes(family));
+}
+
+const MODEL_CAPABILITY_RULES: readonly ModelCapabilityRule[] = [
+  {
+    matches: (context) => includesModelFamily(context, "gpt-5.6"),
+    overrides: {
+      reasoning: true,
+      thinkingLevelMap: GPT_5_6_THINKING_LEVEL_MAP,
+    },
+  },
+];
+
+export function getModelCapabilityOverrides(context: ModelCapabilityContext): ModelCapabilityOverrides {
+  const resolved: ModelCapabilityOverrides = {};
+
+  for (const rule of MODEL_CAPABILITY_RULES) {
+    if (!rule.matches(context)) continue;
+    if (rule.overrides.reasoning !== undefined) resolved.reasoning = rule.overrides.reasoning;
+    if (rule.overrides.thinkingLevelMap) resolved.thinkingLevelMap = { ...rule.overrides.thinkingLevelMap };
+  }
+
+  return resolved;
+}