@samrito/pi-cliproxyapi-provider 0.16.0

package/src/reasoning-levels.ts

@@ -0,0 +1,59 @@
+import type { ThinkingLevelMap } from "@earendil-works/pi-ai";
+import type { ModelsDevReasoningOption } from "./types.ts";
+
+/** pi thinking levels in ascending depth, excluding `off`. */
+const PI_THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+/** The models.dev effort value that means "thinking disabled". */
+const EFFORT_OFF = "none";
+
+/**
+ * Convert models.dev `reasoning_options` into a pi `ThinkingLevelMap`.
+ *
+ * models.dev publishes an exhaustive `type: "effort"` list for models whose
+ * reasoning depth is selectable, using the same vocabulary pi exposes (`none`
+ * plus `minimal`..`max`). The conversion is total in both directions:
+ *
+ *   - a level present in the list maps to itself, so pi sends that exact value
+ *   - a level absent from the list maps to `null`, which hides it in pi's UI
+ *   - pi's `off` maps to models.dev `none`, which the list may signal either as
+ *     an effort value or as a separate `toggle` entry
+ *
+ * Null-ing absent levels is the point of this function. Because the list is
+ * exhaustive, leaving a level `undefined` would let pi offer it using the
+ * provider default, and a proxy that validates the level rejects the request.
+ * CLIProxyAPI does exactly that: it answers an unsupported level with
+ * `400 level "medium" not supported, valid levels: low, high, max`.
+ *
+ * `off` needs both signals because models.dev splits the ability to disable
+ * thinking from the level list. A model can publish `["low","high","max"]`
+ * alongside `{type: "toggle"}`, meaning thinking is selectable only within those
+ * levels but can still be switched off; reading the effort list alone would hide
+ * `off` from a model that supports it. 296 catalog entries have this shape,
+ * including `deepseek/deepseek-flash`, which a live CLIProxyAPI instance accepts
+ * `reasoning_effort: "none"` for.
+ *
+ * Returns `undefined` when the model publishes no effort list, so callers keep
+ * their own default. A lone `toggle` or `budget_tokens` entry enumerates no
+ * levels and cannot be expressed as a level map, so it is ignored.
+ */
+export function thinkingLevelMapFromReasoningOptions(
+  options: ModelsDevReasoningOption[] | undefined,
+): ThinkingLevelMap | undefined {
+  const effort = options?.find(
+    (option) => option.type === "effort" && Array.isArray(option.values) && option.values.length > 0,
+  );
+  const values = effort?.values;
+  if (!values) return undefined;
+
+  const offered = new Set(values);
+  const canDisableThinking =
+    offered.has(EFFORT_OFF) || (options?.some((option) => option.type === "toggle") ?? false);
+  const map: ThinkingLevelMap = {
+    off: canDisableThinking ? EFFORT_OFF : null,
+  };
+  for (const level of PI_THINKING_LEVELS) {
+    map[level] = offered.has(level) ? level : null;
+  }
+  return map;
+}

package/src/registration.ts

@@ -0,0 +1,43 @@
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import type { CpaProviderConfig } from "./types.ts";
+import type { ProviderModelConfigLike } from "./types.ts";
+
+export interface ProviderRegistration {
+  providerName: string;
+  config: ProviderConfig;
+}
+
+export function normalizeProviderModels(models: ProviderModelConfigLike[]): ProviderModelConfig[] {
+  return models.map((model) => ({
+    ...model,
+    // CLIProxyAPI accepts OpenAI-compatible function tools for both Chat
+    // Completions and Responses models, but Pi's strict all-properties-required
+    // rewrite destroys optional argument semantics for multi-mode extension
+    // tools. Keep each model's API selection and disable only that rewrite.
+    compat: {
+      ...model.compat,
+      supportsStrictMode: false,
+    },
+  })) as ProviderModelConfig[];
+}
+
+export function buildProviderRegistration(
+  config: CpaProviderConfig,
+  models: ProviderModelConfigLike[],
+  refreshModels?: (context: RefreshModelsContext) => Promise<ProviderModelConfig[]>,
+): ProviderRegistration {
+  return {
+    providerName: config.providerName,
+    config: {
+      name: `CLIProxyAPI (${config.providerName})`,
+      baseUrl: config.baseUrl,
+      api: "openai-completions",
+      apiKey: config.authRequired ? "$CLIPROXYAPI_API_KEY" : "cliproxyapi-no-auth",
+      authHeader: config.authRequired && config.authHeader,
+      headers: Object.keys(config.headers).length > 0 ? config.headers : undefined,
+      models: normalizeProviderModels(models),
+      refreshModels,
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,69 @@
+import type { RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { getDiscoveryApiKey } from "./auth.ts";
+import { ProviderCatalog, type CatalogRefreshResult, type CatalogSnapshot, type RefreshTarget } from "./catalog.ts";
+import { buildUnavailableProviderModels } from "./provider.ts";
+import { buildProviderRegistration, normalizeProviderModels } from "./registration.ts";
+import type { CpaProviderConfig } from "./types.ts";
+
+export interface ProviderRuntimeOptions {
+  pi: ExtensionAPI;
+  config: CpaProviderConfig;
+  catalog: ProviderCatalog;
+}
+
+export class ProviderRuntime {
+  private registeredFingerprint?: string;
+  private readonly options: ProviderRuntimeOptions;
+
+  constructor(options: ProviderRuntimeOptions) {
+    this.options = options;
+  }
+
+  async start(): Promise<CatalogSnapshot> {
+    const snapshot = await this.options.catalog.load();
+    this.register(snapshot, true);
+    return snapshot;
+  }
+
+  async refresh(
+    target: RefreshTarget = "all",
+    mode: "background" | "manual" = "manual",
+    getDiscoveryApiKey?: () => Promise<string | undefined>,
+  ): Promise<CatalogRefreshResult> {
+    const result = await this.options.catalog.refresh(target, mode, getDiscoveryApiKey);
+    if (result.models.updated || result.metadata.updated) this.register(result.snapshot, false);
+    return result;
+  }
+
+  async refreshModels(context: RefreshModelsContext): Promise<ProviderModelConfig[]> {
+    if (!context.allowNetwork) {
+      const snapshot = await this.options.catalog.load();
+      return normalizeProviderModels(
+        snapshot.built.models.length > 0 ? snapshot.built.models : buildUnavailableProviderModels(),
+      );
+    }
+    const mode = context.force ? "manual" : "background";
+    const credential = context.credential;
+    const keyFn: () => Promise<string | undefined> = credential?.type === "api_key"
+      ? async () => credential.key
+      : () => getDiscoveryApiKey(this.options.config.providerName);
+    const result = await this.options.catalog.refresh("models", mode, keyFn, context.signal);
+    // Pi publishes refreshModels' return value synchronously. Registering here as
+    // well would create a second, competing catalog publication.
+    return normalizeProviderModels(
+      result.snapshot.built.models.length > 0
+        ? result.snapshot.built.models
+        : buildUnavailableProviderModels(),
+    );
+  }
+
+  private register(snapshot: CatalogSnapshot, force: boolean): void {
+    const models = snapshot.built.models.length > 0 ? snapshot.built.models : buildUnavailableProviderModels();
+    const fingerprint = JSON.stringify(models);
+    if (!force && fingerprint === this.registeredFingerprint) return;
+    const registration = buildProviderRegistration(this.options.config, models, (ctx) => this.refreshModels(ctx));
+    this.options.pi.registerProvider(registration.providerName, registration.config);
+    this.registeredFingerprint = fingerprint;
+  }
+}

package/src/settings.ts

@@ -0,0 +1,76 @@
+import { CONFIG_DIR_NAME, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const PROVIDER_SETTINGS_NAMESPACE = "pi-cliproxyapi-provider";
+
+export type Gpt56ContextWindowMode = "canonical" | "full";
+
+export interface ProviderSettings {
+  gpt56ContextWindow: Gpt56ContextWindowMode;
+  showStrictMode: boolean;
+}
+
+export const DEFAULT_PROVIDER_SETTINGS: ProviderSettings = {
+  gpt56ContextWindow: "canonical",
+  showStrictMode: false,
+};
+
+function parseSettingsLayer(settings: unknown, scope: string): Partial<ProviderSettings> {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) return {};
+  const namespace = (settings as Record<string, unknown>)[PROVIDER_SETTINGS_NAMESPACE];
+  if (namespace === undefined) return {};
+  if (!namespace || typeof namespace !== "object" || Array.isArray(namespace)) {
+    throw new Error(`${PROVIDER_SETTINGS_NAMESPACE} must be an object in ${scope} settings.json`);
+  }
+
+  const record = namespace as Record<string, unknown>;
+  const gpt56ContextWindow = record.gpt56ContextWindow;
+  if (gpt56ContextWindow !== undefined && gpt56ContextWindow !== "canonical" && gpt56ContextWindow !== "full") {
+    throw new Error(
+      `${PROVIDER_SETTINGS_NAMESPACE}.gpt56ContextWindow must be "canonical" or "full" in ${scope} settings.json`,
+    );
+  }
+  if (record.showStrictMode !== undefined && typeof record.showStrictMode !== "boolean") {
+    throw new Error(`${PROVIDER_SETTINGS_NAMESPACE}.showStrictMode must be a boolean in ${scope} settings.json`);
+  }
+  return {
+    ...(gpt56ContextWindow !== undefined ? { gpt56ContextWindow } : {}),
+    ...(record.showStrictMode !== undefined ? { showStrictMode: record.showStrictMode } : {}),
+  };
+}
+
+export function loadProviderSettings(cwd: string, agentDir?: string): ProviderSettings {
+  const manager = SettingsManager.create(cwd, agentDir);
+  return {
+    ...DEFAULT_PROVIDER_SETTINGS,
+    ...parseSettingsLayer(manager.getGlobalSettings(), "global"),
+    ...parseSettingsLayer(manager.getProjectSettings(), "project"),
+  };
+}
+
+function settingsPath(cwd: string): string {
+  const projectPath = join(cwd, CONFIG_DIR_NAME, "settings.json");
+  return existsSync(projectPath) ? projectPath : join(getAgentDir(), "settings.json");
+}
+
+export function saveProviderSettings(cwd: string, patch: Partial<ProviderSettings>): string {
+  const path = settingsPath(cwd);
+  let root: 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(`Settings file must contain a JSON object: ${path}`);
+    }
+    root = parsed as Record<string, unknown>;
+  }
+
+  const existing = parseSettingsLayer(root, path);
+  const next = { ...existing, ...patch };
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify({ ...root, [PROVIDER_SETTINGS_NAMESPACE]: next }, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  return path;
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+import type { ThinkingLevelMap } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+export type InputModality = "text" | "image";
+
+export interface ProviderModelOverride {
+  reasoning?: boolean;
+  contextWindow?: number;
+  maxTokens?: number;
+}
+
+export interface ProviderModelOverrideLayer {
+  reasoning?: boolean | null;
+  contextWindow?: number | null;
+  maxTokens?: number | null;
+}
+
+export type ProviderModelOverrides = Record<string, ProviderModelOverride>;
+export type ProviderModelOverrideLayers = Record<string, ProviderModelOverrideLayer>;
+
+export interface CpaProviderConfig {
+  providerName: string;
+  baseUrl: string;
+  authRequired: boolean;
+  authHeader: boolean;
+  headers: Record<string, string>;
+  modelsDevEnabled: boolean;
+  metadataFallbackProvider: string | null;
+  modelAliases: Record<string, string>;
+  modelOverrides: ProviderModelOverrides;
+}
+
+export interface ModelsDevMetadata {
+  id: string;
+  /** models.dev provider key retained for owner-hint matching. */
+  sourceProvider?: string;
+  name?: string;
+  reasoning?: boolean;
+  /**
+   * How the model exposes reasoning control. Only `type: "effort"` entries carry
+   * a level list that maps onto pi thinking levels; `toggle` and `budget_tokens`
+   * describe other shapes and are not converted.
+   */
+  reasoning_options?: ModelsDevReasoningOption[];
+  modalities?: {
+    input?: string[];
+    output?: string[];
+  };
+  limit?: {
+    context?: number;
+    output?: number;
+  };
+  cost?: {
+    input?: number;
+    output?: number;
+    cache_read?: number;
+    cache_write?: number;
+    tiers?: Array<{
+      input?: number;
+      output?: number;
+      cache_read?: number;
+      cache_write?: number;
+      tier?: {
+        type?: string;
+        size?: number;
+      };
+    }>;
+  };
+}
+
+export type ModelsDevCatalog = Record<string, ModelsDevMetadata>;
+
+/**
+ * One entry of a models.dev `reasoning_options` array.
+ *
+ * `type` is kept as a plain string because models.dev adds shapes over time
+ * (currently `effort`, `toggle`, and `budget_tokens`) and unknown ones must be
+ * ignored rather than rejected.
+ */
+export interface ModelsDevReasoningOption {
+  type: string;
+  /** Levels for `type: "effort"`, drawn from the same vocabulary pi uses. */
+  values?: string[];
+  /** Token bounds for `type: "budget_tokens"`. */
+  min?: number;
+  max?: number;
+}
+
+export interface ProviderModelConfigLike {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  api?: ProviderModelConfig["api"];
+  compat?: ProviderModelConfig["compat"];
+  thinkingLevelMap?: ThinkingLevelMap;
+  input: InputModality[];
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    tiers?: Array<{
+      inputTokensAbove: number;
+      input: number;
+      output: number;
+      cacheRead: number;
+      cacheWrite: number;
+    }>;
+  };
+  contextWindow: number;
+  maxTokens: number;
+}