offrouter-core 0.0.0

package/src/providers/adapter.test.ts

@@ -0,0 +1,293 @@
+import { describe, expect, it } from "vitest";
+import type { RouteRequest } from "../types.js";
+import {
+  PROVIDER_ADAPTER_METHODS,
+  ProviderError,
+  isProviderError,
+  mapHttpToProviderError,
+  type ProviderAdapter,
+} from "./adapter.js";
+import { createFakeProvider } from "./fake.js";
+import { createOpenAiCompatibleAdapter } from "./openai-compatible.js";
+
+function sampleRoute(): RouteRequest {
+  return {
+    protocolVersion: "offrouter.route.v1",
+    requestId: "req_adapter_1",
+    harness: { kind: "claude", profile: "claude-personal" },
+    task: {
+      promptPreview: "hello",
+      promptDigest: "sha256:abc",
+      kind: "explain",
+      risk: "low",
+    },
+    workspace: { cwd: "/tmp", trusted: true },
+    constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+  };
+}
+
+function adaptersUnderTest(): ProviderAdapter[] {
+  return [
+    createFakeProvider({ id: "fake-a" }),
+    createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "http://127.0.0.1:9",
+      flavor: "openrouter",
+      apiKey: "test-key",
+      models: [
+        {
+          modelId: "openai/gpt-4.1-mini",
+          supportsTools: true,
+          supportsStreaming: true,
+          supportsJson: true,
+          supportsImages: false,
+        },
+      ],
+      fetch: async () =>
+        new Response(
+          JSON.stringify({ choices: [{ message: { content: "ok" } }] }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          },
+        ),
+    }),
+    createOpenAiCompatibleAdapter({
+      id: "ollama",
+      baseUrl: "http://127.0.0.1:11434/v1",
+      flavor: "ollama",
+      models: [
+        {
+          modelId: "qwen2.5-coder:7b",
+          supportsTools: true,
+          supportsStreaming: true,
+          supportsJson: true,
+          supportsImages: false,
+        },
+      ],
+      fetch: async () =>
+        new Response(
+          JSON.stringify({ choices: [{ message: { content: "local" } }] }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          },
+        ),
+    }),
+  ];
+}
+
+describe("ProviderAdapter contract", () => {
+  it("lists every required method on the contract constant", () => {
+    expect([...PROVIDER_ADAPTER_METHODS]).toEqual([
+      "listModels",
+      "checkAuth",
+      "queryLimits",
+      "estimate",
+      "invoke",
+      "cancel",
+    ]);
+  });
+
+  it("every provider implements listModels, checkAuth, queryLimits, estimate, invoke, and cancel", async () => {
+    for (const adapter of adaptersUnderTest()) {
+      for (const method of PROVIDER_ADAPTER_METHODS) {
+        expect(
+          typeof adapter[method],
+          `${adapter.id}.${method} must be a function`,
+        ).toBe("function");
+      }
+
+      const models = await adapter.listModels();
+      expect(Array.isArray(models)).toBe(true);
+      expect(models.length).toBeGreaterThan(0);
+
+      const auth = await adapter.checkAuth();
+      expect(auth.authTier).toBeTruthy();
+      expect(auth.authScope).toBeTruthy();
+      expect(typeof auth.hasApiKey).toBe("boolean");
+      expect(typeof auth.limitsDiscoverable).toBe("boolean");
+
+      const limits = await adapter.queryLimits(auth.authTier);
+      expect(limits.authTier).toBe(auth.authTier);
+      expect(typeof limits.opaque).toBe("boolean");
+      expect(typeof limits.discoverable).toBe("boolean");
+
+      const modelId = models[0]!.modelId;
+      const estimate = await adapter.estimate(
+        sampleRoute(),
+        modelId,
+        auth.authTier,
+      );
+      expect(estimate.model).toBe(modelId);
+      expect(estimate.currency).toBe("USD");
+      expect(typeof estimate.estimatedCostUsd).toBe("number");
+
+      const events: unknown[] = [];
+      for await (const event of adapter.invoke({
+        callId: `${adapter.id}-call`,
+        model: modelId,
+        messages: [{ role: "user", content: "hi" }],
+        stream: false,
+      })) {
+        events.push(event);
+      }
+      expect(events.length).toBeGreaterThan(0);
+
+      await expect(
+        adapter.cancel(`${adapter.id}-call`),
+      ).resolves.toBeUndefined();
+    }
+  });
+});
+
+describe("canonical ProviderError mapping", () => {
+  it("is identifiable via isProviderError", () => {
+    const err = new ProviderError({
+      code: "rate_limited",
+      message: "slow down",
+      retryable: true,
+      httpStatus: 429,
+    });
+    expect(isProviderError(err)).toBe(true);
+    expect(isProviderError(new Error("nope"))).toBe(false);
+    expect(err.code).toBe("rate_limited");
+  });
+
+  it("maps HTTP statuses onto canonical codes", () => {
+    expect(mapHttpToProviderError(401).code).toBe("auth_failed");
+    expect(mapHttpToProviderError(403).code).toBe("auth_failed");
+    expect(mapHttpToProviderError(404).code).toBe("model_not_found");
+    expect(mapHttpToProviderError(429, "rate limit").code).toBe("rate_limited");
+    expect(mapHttpToProviderError(429, "quota exceeded").code).toBe(
+      "quota_exhausted",
+    );
+    expect(mapHttpToProviderError(402).code).toBe("billing");
+    expect(mapHttpToProviderError(413).code).toBe("context_window");
+    expect(mapHttpToProviderError(503).code).toBe("overload");
+    expect(mapHttpToProviderError(500).code).toBe("network");
+    expect(mapHttpToProviderError(400).code).toBe("invalid_request");
+  });
+
+  it("redacts likely API keys from provider error bodies", () => {
+    const err = mapHttpToProviderError(
+      500,
+      "upstream echoed sk-proj-1234567890abcdef and failed",
+    );
+    expect(err.message).toContain("[REDACTED]");
+    expect(err.message).not.toContain("sk-proj-1234567890abcdef");
+  });
+});
+
+describe("fake adapter behavior", () => {
+  it("streams text deltas", async () => {
+    const adapter = createFakeProvider({
+      streamChunks: ["a", "b", "c"],
+    });
+    const texts: string[] = [];
+    for await (const event of adapter.invoke({
+      callId: "stream-1",
+      model: "fake-coder",
+      messages: [{ role: "user", content: "x" }],
+      stream: true,
+    })) {
+      if (event.type === "text-delta") texts.push(event.text);
+    }
+    expect(texts).toEqual(["a", "b", "c"]);
+  });
+
+  it("supports one-shot responses", async () => {
+    const adapter = createFakeProvider({ responseText: "complete" });
+    const texts: string[] = [];
+    for await (const event of adapter.invoke({
+      callId: "oneshot-1",
+      model: "fake-coder",
+      messages: [{ role: "user", content: "x" }],
+    })) {
+      if (event.type === "text-delta") texts.push(event.text);
+    }
+    expect(texts).toEqual(["complete"]);
+  });
+
+  it("surfaces configured provider errors", async () => {
+    const adapter = createFakeProvider({
+      error: new ProviderError({
+        code: "safety_refusal",
+        message: "nope",
+        retryable: false,
+      }),
+    });
+    const errors: ProviderError[] = [];
+    for await (const event of adapter.invoke({
+      callId: "err-1",
+      model: "fake-coder",
+      messages: [{ role: "user", content: "x" }],
+    })) {
+      if (event.type === "error") errors.push(event.error);
+    }
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.code).toBe("safety_refusal");
+  });
+
+  it("honors cancel during hang", async () => {
+    const adapter = createFakeProvider({ hangUntilCancel: true });
+    const callId = "cancel-me";
+    const iterable = adapter.invoke({
+      callId,
+      model: "fake-coder",
+      messages: [{ role: "user", content: "x" }],
+      stream: true,
+    });
+    const iter = iterable[Symbol.asyncIterator]();
+
+    // start
+    await iter.next();
+    await adapter.cancel(callId);
+
+    let sawCancel = false;
+    while (true) {
+      const next = await iter.next();
+      if (next.done) break;
+      if (
+        next.value.type === "error" &&
+        next.value.error.code === "cancelled"
+      ) {
+        sawCancel = true;
+      }
+    }
+    expect(sawCancel).toBe(true);
+  });
+
+  it("reports opaque limit metadata when configured", async () => {
+    const adapter = createFakeProvider({
+      opaqueLimits: true,
+      limitsDiscoverable: false,
+    });
+    const limits = await adapter.queryLimits("subscription");
+    expect(limits.opaque).toBe(true);
+    expect(limits.discoverable).toBe(false);
+    expect(limits.metadata).toBeDefined();
+    expect(limits.remaining).toBeUndefined();
+  });
+
+  it("uses deterministic reset metadata for fake limits", async () => {
+    const adapter = createFakeProvider();
+    const a = await adapter.queryLimits("api-key");
+    const b = await adapter.queryLimits("api-key");
+    expect(a.resetAt).toBe("1970-01-01T01:00:00.000Z");
+    expect(b.resetAt).toBe(a.resetAt);
+  });
+
+  it("auth scope is present on checkAuth", async () => {
+    const sub = createFakeProvider({ authTier: "subscription" });
+    const status = await sub.checkAuth();
+    expect(status.authScope).toBe("first-party");
+    expect(status.subscriptionStatus).toBe("active");
+    expect(status.hasApiKey).toBe(false);
+
+    const key = createFakeProvider({ authTier: "api-key", hasApiKey: false });
+    const keyStatus = await key.checkAuth();
+    expect(keyStatus.hasApiKey).toBe(false);
+    expect(keyStatus.configured).toBe(false);
+  });
+});

package/src/providers/adapter.ts

@@ -0,0 +1,324 @@
+/**
+ * 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;
+  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;
+  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,
+  };
+}