Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

20.7 KB
Raw Blame
/**
 * CLIProxyAPI Management Health Preflight
 *
 * Pre-checks health of CLIProxy-backed OpenAI-compatible connections against the
 * /v0/management/auth-files endpoint before combo target dispatch.
 *
 * Key safety properties:
 * 1. Fail-open on any management failure or unknown status/models (never causes false-positive skips).
 * 2. In-memory TTL cache (30-60s) with singleflight concurrency coalescing.
 * 3. Only inspects demonstrably CLIProxy-backed connections (baseUrl containing "cliproxy"
 *    or port 8317 with explicit marker, or explicit cliproxy/management properties).
 * 4. Management probes use only the operator-configured CLIProxy endpoint
 *    (CLIPROXYAPI_HOST/PORT or the embedded loopback instance). A connection
 *    baseUrl is never a probe target; a cliproxy-shaped baseUrl that points
 *    at a different instance fails open instead of inheriting that snapshot.
 * 5. Provider family isolation: Claude unavailable never skips Gemini/Codex/XAI on the same instance.
 * 6. Model quota awareness: skips only when all relevant accounts for that model/family are unavailable
 *    or specifically rejected/in cooldown for that model.
 * 7. Stale-rejection awareness: per-model "rejected" flags are honored only while their retry window
 *    is open or the producing account-level cooldown is still active.
 */

import {
  getCliproxyAccountHealth,
  type CliproxyAccountHealth,
  type CliproxyAccountHealthResult,
} from "./cliproxyAccountHealth.ts";
import { CLIPROXY_DEFAULT_PORT } from "@/lib/services/installers/cliproxy";

export type CliproxyBackendFamily =
  "claude" | "antigravity" | "gemini" | "codex" | "xai" | "unknown";

export interface CliproxyPreflightDecision {
  shouldSkip: boolean;
  reason?: string;
  detail?: string;
}

/**
 * Check whether a connection is demonstrably CLIProxy-backed.
 *
 * Rejects generic OpenAI-compatible connections unconditionally unless they
 * explicitly indicate CLIProxy usage.
 */
function hasExplicitCliproxyMarker(psd: Record<string, unknown>): boolean {
  return (
    psd.isCliproxy === true ||
    psd.cliproxy === true ||
    psd.cliproxyapi === true ||
    psd.prefix === "cliproxy" ||
    psd.backend === "cliproxy" ||
    psd.backend === "cliproxyapi" ||
    psd.cliproxyapiMode === "claude-native" ||
    typeof psd.managementKey === "string" ||
    typeof psd.managementPort === "number"
  );
}

function hasPortMarker(psd: Record<string, unknown>): boolean {
  return (
    psd.isCliproxy !== undefined ||
    psd.cliproxy !== undefined ||
    psd.cliproxyapiMode !== undefined ||
    psd.backend !== undefined
  );
}

function parseUrlOrNull(value: string): URL | null {
  try {
    return new URL(value);
  } catch {
    return null;
  }
}

function baseUrlIndicatesCliproxy(psd: Record<string, unknown>): boolean {
  const rawBaseUrl = psd.baseUrl;
  if (typeof rawBaseUrl !== "string" || !rawBaseUrl.trim()) {
    return false;
  }
  const url = parseUrlOrNull(rawBaseUrl.trim());
  if (!url) {
    return false;
  }

  // Host contains "cliproxy" (e.g. cliproxy:8317, my-cliproxyapi.internal)
  if (url.hostname.toLowerCase().includes("cliproxy")) {
    return true;
  }

  // Port 8317 is CLIProxy default port, BUT port 8317 on a generic host
  // (such as localhost or an arbitrary IP) is ONLY considered CLIProxy-backed
  // when an explicit marker is present.
  return url.port === "8317" && hasPortMarker(psd);
}

/**
 * Check whether a connection is demonstrably CLIProxy-backed.
 *
 * Rejects generic OpenAI-compatible connections unconditionally unless they
 * explicitly indicate CLIProxy usage.
 */
export function isCliproxyBackedConnection(
  providerSpecificData?: Record<string, unknown> | null
): boolean {
  if (!providerSpecificData || typeof providerSpecificData !== "object") {
    return false;
  }
  return (
    hasExplicitCliproxyMarker(providerSpecificData) ||
    baseUrlIndicatesCliproxy(providerSpecificData)
  );
}

/**
 * Classify a model string into a CLIProxy backend family.
 *
 * Recognized families:
 *   - "claude"
 *   - "antigravity" (or gemini / agy)
 *   - "gemini"
 *   - "codex" (or openai / gpt)
 *   - "xai" (or grok)
 *   - "unknown" (triggers fail-open)
 */
const EXPLICIT_FAMILY_ALIASES: Readonly<Record<string, CliproxyBackendFamily>> = {
  claude: "claude",
  antigravity: "antigravity",
  agy: "antigravity",
  gemini: "gemini",
  codex: "codex",
  openai: "codex",
  gpt: "codex",
  xai: "xai",
  grok: "xai",
};

const MODEL_FAMILY_MATCHERS: ReadonlyArray<{
  readonly family: CliproxyBackendFamily;
  readonly prefixes: readonly string[];
  readonly substrings: readonly string[];
}> = [
  {
    family: "antigravity",
    prefixes: ["antigravity-", "antigravity/", "agy/"],
    substrings: ["antigravity"],
  },
  {
    family: "claude",
    prefixes: ["claude", "anthropic/"],
    substrings: ["claude-"],
  },
  {
    family: "gemini",
    prefixes: ["gemini", "google/gemini"],
    substrings: ["gemini-"],
  },
  {
    family: "codex",
    prefixes: ["codex/", "openai/", "gpt-", "o1-", "o3-", "o4-", "text-embedding"],
    substrings: ["codex"],
  },
  {
    family: "xai",
    prefixes: ["xai/", "grok-"],
    substrings: ["grok"],
  },
];

function resolveExplicitFamily(
  providerSpecificData?: Record<string, unknown> | null
): CliproxyBackendFamily | null {
  if (!providerSpecificData || typeof providerSpecificData !== "object") {
    return null;
  }
  const explicitFamily =
    providerSpecificData.cliproxyFamily ??
    providerSpecificData.backendFamily ??
    providerSpecificData.upstreamProvider;
  if (typeof explicitFamily !== "string" || !explicitFamily.trim()) {
    return null;
  }
  return EXPLICIT_FAMILY_ALIASES[explicitFamily.trim().toLowerCase()] ?? null;
}

function resolveModelFamily(cleanModel: string): CliproxyBackendFamily {
  for (const matcher of MODEL_FAMILY_MATCHERS) {
    const byPrefix = matcher.prefixes.some((prefix) => cleanModel.startsWith(prefix));
    const bySubstring = matcher.substrings.some((needle) => cleanModel.includes(needle));
    if (byPrefix || bySubstring) {
      return matcher.family;
    }
  }
  return "unknown";
}

/**
 * Classify a model string into a CLIProxy backend family.
 *
 * Recognized families:
 *   - "claude"
 *   - "antigravity" (or gemini / agy)
 *   - "gemini"
 *   - "codex" (or openai / gpt)
 *   - "xai" (or grok)
 *   - "unknown" (triggers fail-open)
 */
export function resolveCliproxyBackendFamily(
  modelStr: string | null | undefined,
  providerSpecificData?: Record<string, unknown> | null
): CliproxyBackendFamily {
  const explicit = resolveExplicitFamily(providerSpecificData);
  if (explicit !== null) {
    return explicit;
  }
  if (!modelStr || typeof modelStr !== "string") {
    return "unknown";
  }
  return resolveModelFamily(modelStr.toLowerCase().trim());
}

function parseModelId(modelStr: string): string {
  const trimmed = modelStr.trim();
  if (trimmed.includes("/")) {
    return trimmed.slice(trimmed.indexOf("/") + 1).trim();
  }
  return trimmed;
}

/**
 * Evaluate whether an account is actively cooling or unavailable.
 */
function isAccountUnavailable(account: CliproxyAccountHealth, now: number): boolean {
  if (account.disabled) return true;
  if (account.status.toLowerCase() === "disabled") return true;
  if (account.unavailable) {
    // If nextRetryAfter is provided and in the past, it's eligible to retry
    if (account.nextRetryAfter) {
      const retryTime = Date.parse(account.nextRetryAfter);
      if (!Number.isNaN(retryTime) && retryTime > now) {
        return true;
      }
    } else {
      return true;
    }
  }
  return false;
}

/**
 * Check whether a specific model quota signal indicates that the model is rejected
 * or currently cooling down.
 *
 * A per-model rejection is only authoritative while it is fresh (#14206): either
 * its own retry window (observed_at + Retry-After) is still open, or the
 * account-level cooldown that produced the observation is still active.
 * CLIProxyAPI rewrites model_quotas only when the next upstream response for
 * that model arrives, so a "rejected" flag can survive account recovery for
 * hours. Treating it as unconditionally blocking skips a credential that is
 * provably serving traffic (live 2026-09-21: 68 dispatched HTTP 200s while
 * auth-files still carried rejected=true with retry_after_s=0).
 */
function isModelQuotaRejected(
  account: CliproxyAccountHealth,
  modelId: string,
  now: number
): boolean {
  const modelQuota = account.modelQuotas[modelId];
  if (!modelQuota || !modelQuota.signals) return false;

  const signals = modelQuota.signals;
  const accountLevelCooldownActive = isAccountUnavailable(account, now);

  // Resolve the observation's own retry window when a Retry-After signal and a
  // parseable observed_at are both present. A zeroed duration yields a window
  // in the past, i.e. not fresh.
  let rejectionWindowMs: number | null = null;
  const retryAfterSecStr = signals["Retry-After"] || signals["retry-after"];
  if (retryAfterSecStr && modelQuota.observedAt) {
    const observedTime = Date.parse(modelQuota.observedAt);
    const retryAfterSec = Number.parseInt(retryAfterSecStr, 10);
    if (!Number.isNaN(observedTime) && !Number.isNaN(retryAfterSec)) {
      rejectionWindowMs = observedTime + retryAfterSec * 1000;
    }
  }
  const windowStillOpen = rejectionWindowMs !== null && rejectionWindowMs > now;

  // 1. Explicit rejected status in signals, authoritative only while fresh:
  //    its own retry window is open, or the account-level cooldown that
  //    produced the observation has not elapsed yet.
  const unifiedStatus = signals["Anthropic-Ratelimit-Unified-Status"]?.toLowerCase();
  const overageStatus = signals["Anthropic-Ratelimit-Unified-Overage-Status"]?.toLowerCase();
  if (unifiedStatus === "rejected" || overageStatus === "rejected") {
    return windowStillOpen || accountLevelCooldownActive;
  }

  // 2. Retry-After signal without an explicit rejected status (other
  //    providers): block only while the observed window is still open.
  return windowStillOpen;
}

export interface EvaluateCliproxyTargetHealthOptions {
  modelStr: string;
  accounts: CliproxyAccountHealth[];
  providerSpecificData?: Record<string, unknown> | null;
  now?: number;
}

const FAMILY_ACCOUNT_ALIASES: Readonly<
  Record<Exclude<CliproxyBackendFamily, "unknown">, readonly string[]>
> = {
  claude: ["claude"],
  antigravity: ["antigravity", "gemini"],
  gemini: ["gemini", "antigravity"],
  codex: ["codex", "openai", "gpt"],
  xai: ["xai", "grok"],
};

function accountMatchesFamily(
  acct: CliproxyAccountHealth,
  family: Exclude<CliproxyBackendFamily, "unknown">
): boolean {
  const aliases = FAMILY_ACCOUNT_ALIASES[family];
  const provider = acct.provider.toLowerCase().trim();
  const type = acct.type.toLowerCase().trim();
  return aliases.includes(provider) || aliases.includes(type);
}

/**
 * Pure evaluation function for target health against known CLIProxy accounts.
 *
 * Rules:
 * - Fail open if model family is unknown.
 * - Fail open if no accounts exist for the family (do not assume it's unusable).
 * - Skip only if relevant accounts exist and ALL are unavailable or rejected for that model.
 * - A single healthy relevant account => do NOT skip.
 */
export function evaluateCliproxyTargetHealth(
  options: EvaluateCliproxyTargetHealthOptions
): CliproxyPreflightDecision {
  const { modelStr, accounts, providerSpecificData } = options;
  const now = options.now ?? Date.now();

  const family = resolveCliproxyBackendFamily(modelStr, providerSpecificData);
  if (family === "unknown") {
    return { shouldSkip: false };
  }

  // Filter accounts belonging to this family. The alias table keeps families
  // isolated: a cooling Claude account never skips Gemini/Codex/XAI targets.
  const relevantAccounts = accounts.filter((acct) => accountMatchesFamily(acct, family));

  if (relevantAccounts.length === 0) {
    // Fail open: no accounts for this family in auth-files, could be configured differently
    return { shouldSkip: false };
  }

  const rawModelId = parseModelId(modelStr);

  // Check if every relevant account is blocked for this concrete model
  // (either account is disabled/cooling/unavailable OR this specific model quota is rejected/cooling).
  // If at least one account is available and not quota-rejected, we must NOT skip.
  for (const acct of relevantAccounts) {
    if (!isAccountUnavailable(acct, now) && !isModelQuotaRejected(acct, rawModelId, now)) {
      return { shouldSkip: false };
    }
  }

  return {
    shouldSkip: true,
    reason: `All ${relevantAccounts.length} ${family} accounts are unavailable or model ${rawModelId} quota rejected`,
  };
}

// ──────────────── In-Memory Cache with Singleflight ────────────────

export interface HealthCacheEntry {
  result: CliproxyAccountHealthResult;
  expiresAt: number;
}

export type HealthFetcher = (options: {
  host?: string;
  port?: number;
  managementKey?: string | null;
  timeoutMs?: number;
}) => Promise<CliproxyAccountHealthResult>;

const CLIPROXY_DEFAULT_HOST = "127.0.0.1";

function canonicalizeCliproxyHost(host: string): string {
  const lower = host.trim().toLowerCase();
  if (lower === "localhost" || lower === "::1" || lower === "[::1]") {
    return CLIPROXY_DEFAULT_HOST;
  }
  return lower;
}

function parseManagementEndpoint(value: string): { host: string; port: number } | null {
  const url = parseUrlOrNull(value.trim());
  if (!url?.hostname) return null;
  const parsedPort = url.port ? Number.parseInt(url.port, 10) : CLIPROXY_DEFAULT_PORT;
  if (!Number.isInteger(parsedPort) || parsedPort <= 0) return null;
  return { host: canonicalizeCliproxyHost(url.hostname), port: parsedPort };
}

function resolveTrustedManagementEndpoint(): { host: string; port: number } {
  const host = canonicalizeCliproxyHost(process.env.CLIPROXYAPI_HOST || CLIPROXY_DEFAULT_HOST);
  const parsedPort = Number.parseInt(
    process.env.CLIPROXYAPI_PORT?.trim() || String(CLIPROXY_DEFAULT_PORT),
    10
  );
  const port = Number.isInteger(parsedPort) && parsedPort > 0 ? parsedPort : CLIPROXY_DEFAULT_PORT;
  return { host, port };
}

/**
 * A connection may only reuse trusted management health when its data plane
 * rides the operator instance. Marker-only and deep-mode connections
 * (`cliproxyapiMode`) keep their native provider baseUrl; the executor still
 * sends them through CLIPROXYAPI_HOST / cliproxyapi_url, so they reuse the
 * trusted snapshot. A cliproxy-shaped baseUrl is compared to the trusted
 * endpoint and fails open on mismatch: the untrusted URL must never receive
 * CLIPROXYAPI_MANAGEMENT_KEY, and a foreign instance's snapshot must not
 * decide this target.
 */
function connectionMayUseTrustedManagementHealth(
  psd: Record<string, unknown> | null | undefined,
  trusted: { host: string; port: number }
): boolean {
  if (!psd || !baseUrlIndicatesCliproxy(psd)) {
    return true;
  }
  const rawBaseUrl = typeof psd.baseUrl === "string" ? psd.baseUrl : "";
  const connection = parseManagementEndpoint(rawBaseUrl);
  return (
    connection !== null && connection.host === trusted.host && connection.port === trusted.port
  );
}

export class CliproxyManagementHealthCache {
  private cache = new Map<string, HealthCacheEntry>();
  private inFlight = new Map<string, Promise<CliproxyAccountHealthResult>>();
  private readonly ttlMs: number;
  private readonly fetcher: HealthFetcher;

  constructor(options?: { ttlMs?: number; fetcher?: HealthFetcher }) {
    // Fail-open 30-60s TTL.
    this.ttlMs = options?.ttlMs ?? 45_000;
    this.fetcher = options?.fetcher ?? getCliproxyAccountHealth;
  }

  async getHealth(
    baseUrl: string,
    managementKey?: string | null,
    timeoutMs = 500
  ): Promise<CliproxyAccountHealthResult> {
    const key = this.makeCacheKey(baseUrl, managementKey);
    const cached = this.cache.get(key);
    if (cached && cached.expiresAt > Date.now()) {
      return cached.result;
    }

    const ongoing = this.inFlight.get(key);
    if (ongoing) return ongoing;

    return this.fetchAndCache(key, baseUrl, managementKey, timeoutMs);
  }

  /**
   * Fetches management health with request-scoped singleflight. The key uses a
   * deterministic marker for the embedded service and does not include the
   * secret itself, so no management credential reaches cache keys, logs, or
   * diagnostic output.
   */
  async getDefaultHealth(timeoutMs = 500): Promise<CliproxyAccountHealthResult> {
    const key = "default";
    const cached = this.cache.get(key);
    if (cached && cached.expiresAt > Date.now()) {
      return cached.result;
    }

    const ongoing = this.inFlight.get(key);
    if (ongoing) return ongoing;

    const promise = (async () => {
      try {
        const result = await this.fetcher({ timeoutMs });
        this.cache.set(key, { result, expiresAt: Date.now() + this.ttlMs });
        return result;
      } catch {
        return { state: "unreachable" as const, accounts: [], version: null };
      } finally {
        this.inFlight.delete(key);
      }
    })();
    this.inFlight.set(key, promise);
    return promise;
  }

  private makeCacheKey(baseUrl: string, managementKey?: string | null): string {
    // Partition by normalized host:port so equivalent URL spellings (path,
    // case, trailing slash, localhost alias) share one snapshot without ever
    // retaining the management secret itself.
    const endpoint = parseManagementEndpoint(baseUrl) ?? {
      host: CLIPROXY_DEFAULT_HOST,
      port: CLIPROXY_DEFAULT_PORT,
    };
    return `${endpoint.host}:${endpoint.port}::${managementKey ? "credentialed" : "default"}`;
  }

  private fetchAndCache(
    key: string,
    baseUrl: string,
    managementKey: string | null | undefined,
    timeoutMs: number
  ): Promise<CliproxyAccountHealthResult> {
    const endpoint = parseManagementEndpoint(baseUrl) ?? {
      host: CLIPROXY_DEFAULT_HOST,
      port: CLIPROXY_DEFAULT_PORT,
    };

    const promise = (async () => {
      try {
        const result = await this.fetcher({
          host: endpoint.host,
          port: endpoint.port,
          managementKey,
          timeoutMs,
        });
        this.cache.set(key, { result, expiresAt: Date.now() + this.ttlMs });
        return result;
      } catch {
        return { state: "unreachable" as const, accounts: [], version: null };
      } finally {
        this.inFlight.delete(key);
      }
    })();
    this.inFlight.set(key, promise);
    return promise;
  }

  clear(): void {
    this.cache.clear();
    this.inFlight.clear();
  }
}

/** Global singleton cache instance for combo execution */
export const defaultCliproxyManagementHealthCache = new CliproxyManagementHealthCache({
  ttlMs: 45_000,
});

export interface EvaluateCliproxyPreflightGateOptions {
  connection: {
    id: string;
    provider: string;
    providerSpecificData?: Record<string, unknown> | null;
  };
  modelStr: string;
  healthCache?: CliproxyManagementHealthCache;
  timeoutMs?: number;
}

async function fetchTrustedManagementHealth(
  cache: CliproxyManagementHealthCache,
  trusted: { host: string; port: number },
  timeoutMs: number
): Promise<CliproxyAccountHealthResult> {
  const hasExternalManagementHost = Boolean(process.env.CLIPROXYAPI_HOST?.trim());
  const managementKey = process.env.CLIPROXYAPI_MANAGEMENT_KEY || null;
  if (!hasExternalManagementHost && !managementKey) {
    return cache.getDefaultHealth(timeoutMs);
  }
  return cache.getHealth(`http://${trusted.host}:${trusted.port}`, managementKey, timeoutMs);
}

/**
 * Gate entry point for evaluateExecuteTargetGates.
 *
 * Checks connection, fetches management health (cached + singleflight, bounded timeout),
 * and decides whether to skip.
 */
export async function evaluateCliproxyPreflightGate(
  options: EvaluateCliproxyPreflightGateOptions
): Promise<CliproxyPreflightDecision> {
  const { connection, modelStr } = options;
  const psd = connection.providerSpecificData;

  // 1. Only run for demonstrably CLIProxy-backed connections
  if (!isCliproxyBackedConnection(psd)) {
    return { shouldSkip: false };
  }

  // 2. Probe only the operator-configured management endpoint. A cliproxy
  //    baseUrl that points elsewhere fails open: the management key must not
  //    travel to a connection-controlled host, and a foreign instance's
  //    snapshot must not decide this target.
  const trusted = resolveTrustedManagementEndpoint();
  if (!connectionMayUseTrustedManagementHealth(psd, trusted)) {
    return { shouldSkip: false };
  }

  const cache = options.healthCache ?? defaultCliproxyManagementHealthCache;
  const timeoutMs = options.timeoutMs ?? 500; // Fast initial preflight timeout (spec requirement #5)
  const health = await fetchTrustedManagementHealth(cache, trusted, timeoutMs);

  // 3. Management errors fail open
  if (health.state !== "ready") {
    return { shouldSkip: false };
  }

  // 4. Pure health evaluation
  return evaluateCliproxyTargetHealth({
    modelStr,
    accounts: health.accounts,
    providerSpecificData: psd,
  });
}