@juvio15/pi-cliproxyapi-provider 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Aagaard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@juvio15/pi-cliproxyapi-provider",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "pi provider for CLIProxyAPI: per-family APIs, model catalog, costs, web search, usage footer",
+  "keywords": [
+    "cliproxyapi",
+    "pi",
+    "pi-package",
+    "provider"
+  ],
+  "license": "MIT",
+  "author": "Bjørn Aagaard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bjoernaagaard/cliproxyapi-provider.git"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@types/node": "^22.15.21",
+    "oxfmt": "^0.71.0",
+    "oxlint": "^1.89.0",
+    "typebox": "1.3.27",
+    "typescript": "6.0.3",
+    "ultracite": "^8.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=0.82.0",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ]
+  }
+}

package/src/core/catalog.ts

@@ -0,0 +1,400 @@
+import type {
+  Model,
+  ModelPromptCache,
+  ThinkingLevelMap,
+} from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import { Value } from "typebox/value";
+
+import { resolveEndpoints } from "./connection.ts";
+import { matchModelCost, ZERO_COST } from "./costs.ts";
+import type { CostCatalog } from "./costs.ts";
+
+export type CliproxyApi =
+  | "anthropic-messages"
+  | "openai-responses"
+  | "openai-completions";
+
+export type ThoughtSummary = "omitted" | "summarized";
+
+export type ModelFamilies = Readonly<Record<string, CliproxyApi>>;
+
+/**
+ * Family patterns. The wildcard is the fallback regardless of table order.
+ * Kimi uses Anthropic Messages. On Responses CLIProxyAPI rejects its
+ * prompt_cache_retention, and on Chat Completions it rejects the developer
+ * role pi-ai sends for system prompts. Messages takes both and caches.
+ */
+export const MODEL_API_BY_FAMILY = {
+  "*": "openai-responses",
+  "claude-*": "anthropic-messages",
+  "kimi-*": "anthropic-messages",
+} satisfies ModelFamilies;
+
+const OptionalString = Type.Optional(Type.String());
+const OptionalNumber = Type.Optional(Type.Number());
+const EffortName = Type.String();
+
+export const CatalogModelSchema = Type.Object({
+  additional_speed_tiers: Type.Optional(Type.Array(Type.String())),
+  context_window: OptionalNumber,
+  cpa_capabilities: Type.Optional(
+    Type.Object({
+      web_search: Type.Optional(Type.Boolean()),
+    })
+  ),
+  default_service_tier: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  description: OptionalString,
+  display_name: OptionalString,
+  id: OptionalString,
+  input_modalities: Type.Optional(Type.Array(Type.String())),
+  max_completion_tokens: OptionalNumber,
+  max_context_window: OptionalNumber,
+  max_output_tokens: OptionalNumber,
+  max_tokens: OptionalNumber,
+  name: OptionalString,
+  service_tiers: Type.Optional(
+    Type.Array(
+      Type.Union([
+        Type.String(),
+        Type.Object({
+          description: OptionalString,
+          id: OptionalString,
+          name: OptionalString,
+        }),
+      ])
+    )
+  ),
+  slug: OptionalString,
+  supported_reasoning_levels: Type.Optional(
+    Type.Array(
+      Type.Union([
+        EffortName,
+        Type.Object({ description: OptionalString, effort: OptionalString }),
+      ])
+    )
+  ),
+  supports_reasoning_effort_updates: Type.Optional(Type.Boolean()),
+  visibility: OptionalString,
+});
+
+export type CatalogModel = Static<typeof CatalogModelSchema>;
+
+const CatalogEntries = Type.Array(CatalogModelSchema);
+
+const CatalogEnvelope = Type.Union([
+  CatalogEntries,
+  Type.Object({ models: CatalogEntries }),
+  Type.Object({ data: CatalogEntries }),
+]);
+
+export interface CliproxyModel extends Model<CliproxyApi> {
+  thoughtSummary: ThoughtSummary;
+  supportsFast: boolean;
+  supportsWebSearch?: boolean;
+  supportsReasoningEffortUpdates?: boolean;
+  thinkingLevelMap?: ThinkingLevelMap & { ultra?: string | null };
+  stale?: boolean;
+  lastSeenAt?: number;
+  staleSince?: number;
+}
+
+export interface MappingOptions {
+  baseUrl: string;
+  providerId?: string;
+  families?: ModelFamilies;
+  costs?: CostCatalog;
+  fast?: () => boolean;
+  thoughtSummaries?: Readonly<Record<string, ThoughtSummary>>;
+  /** Prompt cache lifetimes by model id. Core has no built-in numbers. */
+  promptCache?: (id: string) => ModelPromptCache | undefined;
+}
+
+export interface MappedCatalog {
+  models: CliproxyModel[];
+  fastModelIds: string[];
+}
+
+export interface CatalogFetchOptions {
+  baseUrl: string;
+  apiKey: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface MergeOptions {
+  now?: number;
+  staleTtlMs?: number;
+}
+
+export const DEFAULT_MODEL_STALE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "ultra",
+] as const;
+
+export const selectModelApi = (
+  id: string,
+  families: ModelFamilies = MODEL_API_BY_FAMILY
+): CliproxyApi => {
+  const modelId = id.trim().toLowerCase();
+  // Prefixed aliases (<channel>/<model>, e.g. devin/claude-fable-5-1) hide
+  // the family at the start, so also match the segment after the last "/".
+  // Full-id matches win, so an explicit prefixed pattern still takes over.
+  const segment = modelId.slice(modelId.lastIndexOf("/") + 1);
+  const candidates = segment === modelId ? [modelId] : [modelId, segment];
+
+  for (const candidate of candidates) {
+    for (const [pattern, api] of Object.entries(families)) {
+      if (pattern === "*") {
+        continue;
+      }
+
+      if (
+        pattern.endsWith("*")
+          ? candidate.startsWith(pattern.slice(0, -1))
+          : candidate === pattern
+      ) {
+        return api;
+      }
+    }
+  }
+
+  return families["*"] ?? "openai-responses";
+};
+
+const thinkingMap = (efforts: string[]): CliproxyModel["thinkingLevelMap"] => {
+  if (efforts.length === 0) {
+    return undefined;
+  }
+
+  const map: NonNullable<CliproxyModel["thinkingLevelMap"]> = {};
+
+  for (const level of THINKING_LEVELS) {
+    const effort = level === "off" ? "none" : level;
+    map[level] = efforts.includes(effort) ? effort : null;
+  }
+
+  return map;
+};
+
+const positive = (...values: (number | undefined)[]): number | undefined =>
+  values.find(
+    (value) => value !== undefined && Number.isFinite(value) && value > 0
+  );
+
+const capabilities = (entry: CatalogModel) => {
+  const efforts = (entry.supported_reasoning_levels ?? [])
+    .map((level) => {
+      const effort = Value.Check(EffortName, level)
+        ? level
+        : (level.effort ?? "");
+
+      return effort.trim().toLowerCase();
+    })
+    .filter(Boolean);
+
+  const input: ("text" | "image")[] = [];
+
+  for (const modality of entry.input_modalities ?? []) {
+    const value = modality.trim().toLowerCase();
+
+    if ((value === "text" || value === "image") && !input.includes(value)) {
+      input.push(value);
+    }
+  }
+
+  if (!input.includes("text")) {
+    input.unshift("text");
+  }
+
+  return {
+    contextWindow:
+      positive(entry.context_window, entry.max_context_window) ?? 128_000,
+    input,
+    maxTokens:
+      positive(
+        entry.max_tokens,
+        entry.max_output_tokens,
+        entry.max_completion_tokens
+      ) ?? 16_384,
+    reasoning: efforts.some((effort) => effort !== "none"),
+    thinkingLevelMap: thinkingMap(efforts),
+  };
+};
+
+const webSearchCapability = (
+  entry: CatalogModel
+): { supportsWebSearch?: boolean } =>
+  entry.cpa_capabilities?.web_search === undefined
+    ? {}
+    : { supportsWebSearch: entry.cpa_capabilities.web_search };
+
+/** Read once per mapping, so every model in one catalog gets the same tier. */
+const readFast = (options: MappingOptions): boolean =>
+  options.fast?.() ?? false;
+
+const addAnthropicSettings = (
+  model: CliproxyModel,
+  options: MappingOptions
+): void => {
+  // pi-ai sends the session id as X-Session-Affinity only when asked.
+  // CLIProxyAPI's session affinity reads it to keep a session, and the
+  // prompt cache, on one upstream account. Responses always sends one.
+  model.compat = { sendSessionAffinityHeaders: true };
+
+  // pi warms the prompt cache only for models that declare its lifetimes.
+  const promptCache = options.promptCache?.(model.id);
+
+  if (promptCache) {
+    model.promptCache = promptCache;
+  }
+};
+
+export const mapCatalog = (
+  entries: readonly CatalogModel[],
+  options: MappingOptions
+): MappedCatalog => {
+  const endpoints = resolveEndpoints(options.baseUrl);
+  const models = new Map<string, CliproxyModel>();
+  const fastPricing = readFast(options);
+
+  for (const entry of entries) {
+    const id = (entry.slug ?? entry.id ?? "").trim();
+
+    if (!id || entry.visibility?.toLowerCase() === "hide") {
+      continue;
+    }
+
+    const api = selectModelApi(id, options.families);
+
+    const supportsFast = (entry.service_tiers?.length ?? 0) > 0;
+
+    const model: CliproxyModel = {
+      ...capabilities(entry),
+      api,
+      baseUrl:
+        api === "anthropic-messages"
+          ? endpoints.anthropicBaseUrl
+          : endpoints.openaiBaseUrl,
+      cost: options.costs
+        ? matchModelCost(
+            id,
+            options.costs,
+            fastPricing && supportsFast && api === "openai-responses"
+          )
+        : { ...ZERO_COST },
+      id,
+      name: (entry.display_name ?? entry.name ?? id).trim() || id,
+      provider: options.providerId ?? "cliproxyapi",
+      supportsFast,
+      supportsReasoningEffortUpdates:
+        entry.supports_reasoning_effort_updates === true,
+      thoughtSummary: options.thoughtSummaries?.[id] ?? "omitted",
+      ...webSearchCapability(entry),
+    };
+
+    if (api === "anthropic-messages") {
+      addAnthropicSettings(model, options);
+    }
+
+    models.set(id, model);
+  }
+
+  const result = [...models.values()];
+
+  return {
+    fastModelIds: result.flatMap((model) =>
+      model.supportsFast ? [model.id] : []
+    ),
+    models: result,
+  };
+};
+
+export class CatalogHttpError extends Error {
+  readonly status: number;
+  constructor(status: number, statusText: string) {
+    super(`Catalog request failed: ${status} ${statusText}`);
+    this.name = "CatalogHttpError";
+    this.status = status;
+  }
+}
+
+export const fetchCatalog = async (
+  options: CatalogFetchOptions
+): Promise<CatalogModel[]> => {
+  const timeout = AbortSignal.timeout(options.timeoutMs ?? 60_000);
+
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, timeout])
+    : timeout;
+
+  const response = await (options.fetch ?? globalThis.fetch)(
+    resolveEndpoints(options.baseUrl).modelsUrl,
+    {
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${options.apiKey}`,
+      },
+      signal,
+    }
+  );
+
+  if (!response.ok) {
+    throw new CatalogHttpError(response.status, response.statusText);
+  }
+
+  const payload: unknown = await response.json();
+
+  if (!Value.Check(CatalogEnvelope, payload)) {
+    throw new TypeError(
+      "Invalid model catalog: expected an array, models, or data of catalog entries"
+    );
+  }
+
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  return "models" in payload ? payload.models : payload.data;
+};
+
+export const mergeCatalog = (
+  previous: readonly CliproxyModel[],
+  fresh: readonly CliproxyModel[],
+  options: MergeOptions = {}
+): CliproxyModel[] => {
+  const now = options.now ?? Date.now();
+  const ttl = options.staleTtlMs ?? DEFAULT_MODEL_STALE_TTL_MS;
+  const merged = new Map<string, CliproxyModel>();
+
+  for (const model of fresh) {
+    const updated = { ...model, lastSeenAt: now, stale: false };
+    delete updated.staleSince;
+    merged.set(model.id, updated);
+  }
+
+  for (const model of previous) {
+    if (merged.has(model.id)) {
+      continue;
+    }
+
+    const lastSeenAt = model.lastSeenAt ?? now;
+    const staleSince = model.stale ? (model.staleSince ?? lastSeenAt) : now;
+
+    if (now - staleSince < ttl) {
+      merged.set(model.id, { ...model, lastSeenAt, stale: true, staleSince });
+    }
+  }
+
+  return [...merged.values()];
+};

package/src/core/connection.ts

@@ -0,0 +1,119 @@
+export interface Endpoints {
+  rootUrl: string;
+  anthropicBaseUrl: string;
+  openaiBaseUrl: string;
+  modelsUrl: string;
+  messagesUrl: string;
+  responsesUrl: string;
+  chatCompletionsUrl: string;
+}
+
+export interface ConnectionValues {
+  baseUrl?: string;
+  apiKey?: string;
+}
+
+export interface ResolvedConnection extends Endpoints {
+  baseUrl: string;
+  apiKey: string;
+}
+
+/** Where a connection value came from: the environment, cliproxyapi.json, pi's /login, or the built-in default. */
+export type ValueSource = "env" | "cliproxyapi.json" | "login" | "default";
+
+export interface ConnectionSources {
+  baseUrl: ValueSource;
+  /** Undefined when no API key is configured. */
+  apiKey?: ValueSource;
+}
+
+const HTTP_SCHEME = /^https?:\/\//iu;
+const OTHER_SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
+const TRAILING_SLASHES = /\/+$/u;
+
+const ENDPOINT_SUFFIX =
+  /\/(?:v1(?:\/(?:models|messages|responses|chat\/completions))?|backend-api(?:\/codex\/responses)?)$/u;
+
+export const DEFAULT_BASE_URL = "http://127.0.0.1:8317";
+
+export const resolveEndpoints = (baseUrl: string): Endpoints => {
+  const input = baseUrl.trim();
+
+  if (!input) {
+    throw new Error("baseUrl is empty");
+  }
+
+  if (OTHER_SCHEME.test(input) && !HTTP_SCHEME.test(input)) {
+    throw new Error("baseUrl must use HTTP or HTTPS");
+  }
+
+  const url = new URL(HTTP_SCHEME.test(input) ? input : `http://${input}`);
+
+  if (url.username || url.password) {
+    throw new Error("baseUrl must not contain credentials");
+  }
+
+  const path = url.pathname
+    .replace(TRAILING_SLASHES, "")
+    .replace(ENDPOINT_SUFFIX, "");
+
+  const rootUrl = `${url.origin}${path}`;
+
+  return {
+    anthropicBaseUrl: rootUrl,
+    chatCompletionsUrl: `${rootUrl}/v1/chat/completions`,
+    messagesUrl: `${rootUrl}/v1/messages`,
+    modelsUrl: `${rootUrl}/v1/models?client_version=cpa`,
+    openaiBaseUrl: `${rootUrl}/v1`,
+    responsesUrl: `${rootUrl}/v1/responses`,
+    rootUrl,
+  };
+};
+
+const firstSource = (
+  candidates: readonly (readonly [ValueSource, string | undefined])[]
+): ValueSource | undefined =>
+  candidates.find(([, value]) => value?.trim())?.[0];
+
+/** The sources resolveConnection takes its values from, in the same priority order. Never returns the values. */
+export const resolveConnectionSources = (
+  env: Readonly<Record<string, string | undefined>>,
+  file: ConnectionValues = {},
+  stored: ConnectionValues = {}
+): ConnectionSources => {
+  const baseUrl =
+    firstSource([
+      ["env", env.CLIPROXYAPI_BASE_URL],
+      ["cliproxyapi.json", file.baseUrl],
+      ["login", stored.baseUrl],
+    ]) ?? "default";
+
+  const apiKey = firstSource([
+    ["env", env.CLIPROXYAPI_API_KEY],
+    ["cliproxyapi.json", file.apiKey],
+    ["login", stored.apiKey],
+  ]);
+
+  return apiKey ? { apiKey, baseUrl } : { baseUrl };
+};
+
+export const resolveConnection = (
+  env: Readonly<Record<string, string | undefined>>,
+  file: ConnectionValues = {},
+  stored: ConnectionValues = {}
+): ResolvedConnection | null => {
+  const baseUrl =
+    [env.CLIPROXYAPI_BASE_URL, file.baseUrl, stored.baseUrl, DEFAULT_BASE_URL]
+      .map((value) => value?.trim())
+      .find(Boolean) ?? DEFAULT_BASE_URL;
+
+  const apiKey = [env.CLIPROXYAPI_API_KEY, file.apiKey, stored.apiKey]
+    .map((value) => value?.trim())
+    .find(Boolean);
+
+  if (!apiKey) {
+    return null;
+  }
+
+  return { apiKey, baseUrl, ...resolveEndpoints(baseUrl) };
+};