offrouter-core 0.2.0 → 0.2.2

package/src/providers/adapter.ts

@@ -1,328 +0,0 @@
-/**
- * Provider adapter contract shared by fake and OpenAI-compatible backends.
- * Keeps harness-specific shapes out of the core router.
- */
-
-import type {
-  AuthScope,
-  AuthTier,
-  ProviderCandidate,
-  ProviderHealth,
-  RouteRequest,
-  SubscriptionStatus,
-} from "../types.js";
-import { redact } from "../secrets.js";
-
-// ---------------------------------------------------------------------------
-// Canonical provider errors
-// ---------------------------------------------------------------------------
-
-export type ProviderErrorCode =
-  | "auth_failed"
-  | "rate_limited"
-  | "quota_exhausted"
-  | "billing"
-  | "overload"
-  | "model_not_found"
-  | "context_window"
-  | "safety_refusal"
-  | "stream_interrupted"
-  | "cancelled"
-  | "timeout"
-  | "network"
-  | "invalid_request"
-  | "unknown";
-
-export interface ProviderErrorOptions {
-  code: ProviderErrorCode;
-  message: string;
-  retryable?: boolean;
-  httpStatus?: number;
-  providerCode?: string;
-  cause?: unknown;
-}
-
-export class ProviderError extends Error {
-  readonly code: ProviderErrorCode;
-  readonly retryable: boolean;
-  readonly httpStatus?: number;
-  readonly providerCode?: string;
-
-  constructor(options: ProviderErrorOptions) {
-    super(
-      options.message,
-      options.cause !== undefined ? { cause: options.cause } : undefined,
-    );
-    this.name = "ProviderError";
-    this.code = options.code;
-    this.retryable = options.retryable ?? false;
-    this.httpStatus = options.httpStatus;
-    this.providerCode = options.providerCode;
-  }
-}
-
-export function isProviderError(value: unknown): value is ProviderError {
-  return value instanceof ProviderError;
-}
-
-/**
- * Map HTTP status + optional provider body into a ProviderError.
- * Presence-only; never logs credential material.
- */
-export function mapHttpToProviderError(
-  status: number,
-  bodyText?: string,
-  providerCode?: string,
-): ProviderError {
-  const snippet =
-    typeof bodyText === "string" && bodyText.length > 0
-      ? redact(bodyText.slice(0, 240))
-      : undefined;
-  const base = snippet ?? `HTTP ${status}`;
-
-  if (status === 401 || status === 403) {
-    return new ProviderError({
-      code: "auth_failed",
-      message: base,
-      retryable: false,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 404) {
-    return new ProviderError({
-      code: "model_not_found",
-      message: base,
-      retryable: false,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 408 || status === 504) {
-    return new ProviderError({
-      code: "timeout",
-      message: base,
-      retryable: true,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 429) {
-    const lower = (bodyText ?? "").toLowerCase();
-    if (
-      lower.includes("quota") ||
-      lower.includes("billing") ||
-      lower.includes("insufficient")
-    ) {
-      return new ProviderError({
-        code: "quota_exhausted",
-        message: base,
-        retryable: false,
-        httpStatus: status,
-        providerCode,
-      });
-    }
-    return new ProviderError({
-      code: "rate_limited",
-      message: base,
-      retryable: true,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 402) {
-    return new ProviderError({
-      code: "billing",
-      message: base,
-      retryable: false,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 413) {
-    return new ProviderError({
-      code: "context_window",
-      message: base,
-      retryable: false,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status === 503 || status === 529) {
-    return new ProviderError({
-      code: "overload",
-      message: base,
-      retryable: true,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status >= 500) {
-    return new ProviderError({
-      code: "network",
-      message: base,
-      retryable: true,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  if (status >= 400) {
-    return new ProviderError({
-      code: "invalid_request",
-      message: base,
-      retryable: false,
-      httpStatus: status,
-      providerCode,
-    });
-  }
-  return new ProviderError({
-    code: "unknown",
-    message: base,
-    retryable: false,
-    httpStatus: status,
-    providerCode,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Supporting types
-// ---------------------------------------------------------------------------
-
-export interface ModelCapability {
-  modelId: string;
-  displayName?: string;
-  supportsTools: boolean;
-  supportsStreaming: boolean;
-  supportsJson: boolean;
-  supportsImages: boolean;
-  contextWindowTokens?: number;
-  maxOutputTokens?: number;
-  estimatedCostUsd?: number;
-}
-
-export interface AuthStatus {
-  authTier: AuthTier;
-  authScope: AuthScope;
-  configured: boolean;
-  /** Presence-only; never returns key material. */
-  hasApiKey: boolean;
-  subscriptionStatus?: SubscriptionStatus;
-  limitsDiscoverable: boolean;
-  health: ProviderHealth;
-  accountId?: string;
-  detail?: string;
-  /**
-   * Which credential source satisfied auth (if any).
-   * "none" when no credential was found.
-   */
-  credentialSource?: "env" | "config" | "keychain" | "oauth" | "none";
-  /** Whether this auth path uses a subscription-backed credential. */
-  subscriptionEligible: boolean;
-}
-
-/**
- * Limit snapshot. Opaque providers report discoverable=false and omit remaining.
- */
-export interface LimitSnapshot {
-  authTier: AuthTier;
-  /** When false, remaining/reset fields are unknown; rely on errors for fallback. */
-  discoverable: boolean;
-  opaque: boolean;
-  remaining?: number;
-  limit?: number;
-  resetAt?: string;
-  unit?: string;
-  accountId?: string;
-  metadata?: Record<string, string | number | boolean | null>;
-}
-
-export interface CostEstimate {
-  model: string;
-  authTier: AuthTier;
-  estimatedCostUsd: number;
-  currency: "USD";
-  inputTokensEstimate?: number;
-  outputTokensEstimate?: number;
-  note?: string;
-}
-
-export interface ProviderInvokeMessage {
-  role: "system" | "user" | "assistant" | "tool";
-  content: string;
-}
-
-export interface ProviderInvokeRequest {
-  callId: string;
-  model: string;
-  messages: ProviderInvokeMessage[];
-  stream?: boolean;
-  maxOutputTokens?: number;
-  temperature?: number;
-  /** Optional abort signal for cancellation races. */
-  signal?: AbortSignal;
-}
-
-export type ProviderEvent =
-  | { type: "start"; callId: string; model: string }
-  | { type: "text-delta"; callId: string; text: string }
-  | { type: "tool-call"; callId: string; name: string; arguments: string }
-  | {
-      type: "usage";
-      callId: string;
-      inputTokens?: number;
-      outputTokens?: number;
-      totalTokens?: number;
-    }
-  | { type: "done"; callId: string; finishReason?: string }
-  | { type: "error"; callId: string; error: ProviderError };
-
-export interface ProviderAdapter {
-  readonly id: string;
-  listModels(): Promise<ModelCapability[]>;
-  checkAuth(): Promise<AuthStatus>;
-  queryLimits(authTier: AuthTier): Promise<LimitSnapshot>;
-  estimate(
-    request: RouteRequest,
-    model: string,
-    authTier: AuthTier,
-  ): Promise<CostEstimate>;
-  invoke(request: ProviderInvokeRequest): AsyncIterable<ProviderEvent>;
-  cancel(callId: string): Promise<void>;
-}
-
-/** Required method names on every adapter. */
-export const PROVIDER_ADAPTER_METHODS = [
-  "listModels",
-  "checkAuth",
-  "queryLimits",
-  "estimate",
-  "invoke",
-  "cancel",
-] as const satisfies readonly (keyof ProviderAdapter)[];
-
-/** Convert catalog models to ProviderCandidate rows for routing tests. */
-export function capabilityToCandidate(
-  providerId: string,
-  capability: ModelCapability,
-  extras: Pick<ProviderCandidate, "authTier" | "authScope"> &
-    Partial<ProviderCandidate>,
-): ProviderCandidate {
-  return {
-    providerId,
-    modelId: capability.modelId,
-    displayName: capability.displayName,
-    authTier: extras.authTier,
-    authScope: extras.authScope,
-    subscriptionStatus: extras.subscriptionStatus,
-    health: extras.health ?? "healthy",
-    supportsTools: capability.supportsTools,
-    supportsStreaming: capability.supportsStreaming,
-    supportsJson: capability.supportsJson,
-    supportsImages: capability.supportsImages,
-    contextWindowTokens: capability.contextWindowTokens,
-    maxOutputTokens: capability.maxOutputTokens,
-    estimatedCostUsd: extras.estimatedCostUsd ?? capability.estimatedCostUsd,
-    accountId: extras.accountId,
-    subscriptionQuotaPercentRemaining: extras.subscriptionQuotaPercentRemaining,
-  };
-}

package/src/providers/catalog-data.test.ts

@@ -1,258 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  BUILTIN_PROVIDERS,
-  BUILTIN_PROVIDER_IDS,
-  BuiltinCatalogConfigSchema,
-  ProviderCatalogConfigSchema,
-  getBuiltinProvider,
-  parseBuiltinCatalogConfig,
-  selectBuiltinProviders,
-  type BuiltinCatalogConfig,
-  type BuiltinProviderEntry,
-  type ProviderCatalogConfig,
-} from "./catalog-data.js";
-import {
-  STATIC_CATALOG,
-  loadBuiltinCatalog,
-} from "./catalog.js";
-
-// Substrings that should never appear in metadata-only catalog values.
-const SECRET_VALUE_PATTERNS = ["sk-", "Bearer ", "x-api-key:", "password="];
-// Field names that must not exist in a metadata-only catalog.
-const SECRET_KEY_RE = /(?:^|_)(key|secret|token|password|credential)(?:_|$)/i;
-
-function collectKeyNames(value: unknown, into: string[]): void {
-  if (Array.isArray(value)) {
-    for (const v of value) collectKeyNames(v, into);
-    return;
-  }
-  if (value && typeof value === "object") {
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      into.push(k);
-      collectKeyNames(v, into);
-    }
-  }
-}
-
-function hasNoSecrets(value: unknown): boolean {
-  const text = JSON.stringify(value ?? "");
-  if (SECRET_VALUE_PATTERNS.some((p) => text.includes(p))) return false;
-  const names: string[] = [];
-  collectKeyNames(value, names);
-  return !names.some((n) => SECRET_KEY_RE.test(n));
-}
-
-describe("builtin provider catalog data", () => {
-  it("loads a non-empty builtin catalog offline", () => {
-    expect(BUILTIN_PROVIDERS.length).toBeGreaterThan(0);
-    for (const provider of BUILTIN_PROVIDERS) {
-      expect(provider.providerId).toBeTruthy();
-      expect(provider.displayName).toBeTruthy();
-      expect(provider.flavor).toBeTruthy();
-      expect(Array.isArray(provider.knownModels)).toBe(true);
-    }
-  });
-
-  it("covers the required provider families", () => {
-    const ids = new Set(BUILTIN_PROVIDER_IDS);
-    for (const id of [
-      "openai",
-      "anthropic",
-      "google",
-      "xai",
-      "openrouter",
-      "zai",
-      "moonshot",
-      "ollama",
-      "lm-studio",
-      "custom",
-    ]) {
-      expect(ids.has(id), `missing provider ${id}`).toBe(true);
-    }
-  });
-
-  it("assigns correct default authTier and authScope per family", () => {
-    const byId = new Map(
-      BUILTIN_PROVIDERS.map((p) => [p.providerId, p] as const),
-    );
-    // Pure API providers default to api-key.
-    expect(byId.get("openai")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("anthropic")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("google")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("xai")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("zai")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("moonshot")?.defaultAuthTier).toBe("api-key");
-    // Aggregator is third-party api-key.
-    expect(byId.get("openrouter")?.defaultAuthTier).toBe("api-key");
-    expect(byId.get("openrouter")?.defaultAuthScope).toBe("third-party");
-    // Local runtimes.
-    expect(byId.get("ollama")?.defaultAuthTier).toBe("local");
-    expect(byId.get("lm-studio")?.defaultAuthTier).toBe("local");
-    // Custom endpoint is a local OpenAI-compatible gateway by default; scope
-    // is unknown until configured.
-    expect(byId.get("custom")?.defaultAuthTier).toBe("local");
-    expect(byId.get("custom")?.defaultAuthScope).toBe("unknown");
-    // First-party API vendors carry first-party scope (direct vendor apis;
-    // aggregators like openrouter stay third-party).
-    expect(byId.get("openai")?.defaultAuthScope).toBe("first-party");
-    expect(byId.get("anthropic")?.defaultAuthScope).toBe("first-party");
-    expect(byId.get("google")?.defaultAuthScope).toBe("first-party");
-    expect(byId.get("zai")?.defaultAuthScope).toBe("first-party");
-    expect(byId.get("moonshot")?.defaultAuthScope).toBe("first-party");
-  });
-
-  it("documents the official subscription surface without auto-promoting api-key", () => {
-    for (const provider of BUILTIN_PROVIDERS) {
-      expect(typeof provider.supportsSubscriptionRouting).toBe("boolean");
-      // API-key and local providers never claim a routing surface they lack.
-      if (provider.defaultAuthTier !== "subscription") {
-        // The flag is informational; subscription routing itself is the job of
-        // the harness adapters, not this metadata.
-        expect(provider.supportsSubscriptionRouting).toBe(false);
-      }
-    }
-  });
-
-  it("looks up a builtin provider by id", () => {
-    expect(getBuiltinProvider("ollama")?.flavor).toBe("ollama");
-    expect(getBuiltinProvider("missing")).toBeUndefined();
-  });
-
-  it("excludes disabled providers from selectBuiltinProviders", () => {
-    const config: BuiltinCatalogConfig = { openai: { enabled: false } };
-    const selected = selectBuiltinProviders(config);
-    expect(selected.find((p) => p.providerId === "openai")).toBeUndefined();
-    expect(selected.find((p) => p.providerId === "anthropic")).toBeDefined();
-  });
-
-  it("applies base URL overrides from provider config", () => {
-    const config: BuiltinCatalogConfig = {
-      custom: { enabled: true, baseUrl: "https://gateway.example.test/v1" },
-    };
-    const selected = selectBuiltinProviders(config);
-    const custom = selected.find((p) => p.providerId === "custom");
-    expect(custom?.defaultBaseUrl).toBe("https://gateway.example.test/v1");
-  });
-
-  it("returns copies so callers cannot mutate the static source", () => {
-    const selected = selectBuiltinProviders();
-    const before = getBuiltinProvider("openai")?.defaultBaseUrl;
-    selected[0]!.defaultBaseUrl = "mutated";
-    expect(getBuiltinProvider("openai")?.defaultBaseUrl).toBe(before);
-  });
-
-  it("custom OpenAI-compatible endpoint entry is usable when configured", () => {
-    const custom = getBuiltinProvider("custom") as BuiltinProviderEntry;
-    expect(custom.flavor).toBe("openai");
-    const entries = loadBuiltinCatalog({
-      providers: {
-        custom: {
-          enabled: true,
-          baseUrl: "https://gateway.example.test/v1",
-        } satisfies ProviderCatalogConfig,
-      },
-    });
-    const customRow = entries.find((e) => e.providerId === "custom");
-    expect(customRow).toBeDefined();
-  });
-
-  it("does not auto-promote api-key over subscription for the same family", () => {
-    const entries = loadBuiltinCatalog({ families: ["frontier-coder"] });
-    const tiers = new Set(entries.map((e) => e.authTier));
-    expect(tiers.has("subscription")).toBe(true);
-    expect(tiers.has("api-key")).toBe(true);
-    // Subscription entries must survive the merge (never replaced by api-key).
-    expect(entries.some((e) => e.authTier === "subscription")).toBe(true);
-  });
-
-  it("subscription-backed and api-key candidates coexist for shared families", () => {
-    for (const family of ["frontier-coder", "fast-coder"] as const) {
-      const entries = loadBuiltinCatalog({ families: [family] });
-      const tiers = new Set(entries.map((e) => e.authTier));
-      expect(tiers.has("subscription"), `${family} subscription`).toBe(true);
-      expect(tiers.has("api-key"), `${family} api-key`).toBe(true);
-    }
-  });
-
-  it("merges builtin entries with the existing static catalog", () => {
-    const merged = loadBuiltinCatalog();
-    // Static subscription rows must still be present.
-    const staticIds = new Set(STATIC_CATALOG.map((e) => e.providerId));
-    for (const id of staticIds) {
-      expect(
-        merged.some((e) => e.providerId === id),
-        `static provider ${id} dropped`,
-      ).toBe(true);
-    }
-    // Builtin-only providers must appear too.
-    expect(merged.some((e) => e.providerId === "openai")).toBe(true);
-    expect(merged.some((e) => e.providerId === "anthropic")).toBe(true);
-  });
-
-  it("excludes disabled providers across both catalog sources", () => {
-    const entries = loadBuiltinCatalog({
-      providers: { openrouter: { enabled: false } },
-    });
-    expect(entries.every((e) => e.providerId !== "openrouter")).toBe(true);
-  });
-
-  it("dedups identical rows across static and builtin sources", () => {
-    // ollama/llava:latest appears in BOTH STATIC_CATALOG (vision-helper, local)
-    // and the builtin ollama entry with identical providerId/modelId/tier/
-    // family, so the structured dedup key must collapse them to a single row.
-    const merged = loadBuiltinCatalog();
-    const llava = merged.filter(
-      (e) =>
-        e.providerId === "ollama" &&
-        e.modelId === "llava:latest" &&
-        e.authTier === "local" &&
-        e.family === "vision-helper",
-    );
-    expect(llava.length).toBe(1);
-  });
-
-  it("contains no secrets anywhere in the catalog", () => {
-    expect(hasNoSecrets(BUILTIN_PROVIDERS)).toBe(true);
-    expect(hasNoSecrets(selectBuiltinProviders())).toBe(true);
-    expect(hasNoSecrets(loadBuiltinCatalog())).toBe(true);
-  });
-
-  it("every builtin catalog row carries authTier and authScope", () => {
-    const entries = loadBuiltinCatalog();
-    expect(entries.length).toBeGreaterThan(0);
-    for (const e of entries) {
-      expect(["subscription", "local", "api-key"]).toContain(e.authTier);
-      expect(["first-party", "third-party", "unknown"]).toContain(e.authScope);
-    }
-  });
-
-  it("Zod schemas reject invalid catalog config", () => {
-    // Wrong type for enabled.
-    expect(() =>
-      ProviderCatalogConfigSchema.parse({ enabled: "yes" }),
-    ).toThrow();
-    // Unknown key rejected by strict schema.
-    expect(() =>
-      ProviderCatalogConfigSchema.parse({ nope: true }),
-    ).toThrow();
-    // baseUrl must be a string.
-    expect(() =>
-      ProviderCatalogConfigSchema.parse({ baseUrl: 42 }),
-    ).toThrow();
-    // Record schema rejects non-object provider entries.
-    expect(() =>
-      BuiltinCatalogConfigSchema.parse({ openai: "on" }),
-    ).toThrow();
-  });
-
-  it("parseBuiltinCatalogConfig accepts valid config and rejects invalid", () => {
-    expect(() =>
-      parseBuiltinCatalogConfig({
-        openai: { enabled: true, baseUrl: "https://api.openai.com/v1" },
-      }),
-    ).not.toThrow();
-    expect(() =>
-      parseBuiltinCatalogConfig({ openai: { enabled: "true" } }),
-    ).toThrow();
-  });
-});