offrouter-core 0.0.0

package/src/providers/fake.ts

@@ -0,0 +1,312 @@
+/**
+ * Deterministic fake provider adapter for offline tests and MCP demos.
+ * Supports one-shot, streaming, configured errors, and cancellation.
+ */
+
+import type { AuthTier, RouteRequest } from "../types.js";
+import {
+  ProviderError,
+  type AuthStatus,
+  type CostEstimate,
+  type LimitSnapshot,
+  type ModelCapability,
+  type ProviderAdapter,
+  type ProviderEvent,
+  type ProviderInvokeRequest,
+} from "./adapter.js";
+
+export interface FakeModelConfig extends ModelCapability {
+  authTier?: AuthTier;
+}
+
+export interface FakeProviderOptions {
+  id?: string;
+  authTier?: AuthTier;
+  /** Presence-only flag; never stores a secret value. */
+  hasApiKey?: boolean;
+  limitsDiscoverable?: boolean;
+  opaqueLimits?: boolean;
+  remaining?: number;
+  limit?: number;
+  models?: FakeModelConfig[];
+  /** Fixed one-shot body when stream is false/omitted. */
+  responseText?: string;
+  /** Chunks for streaming invokes (token-ish pieces). */
+  streamChunks?: string[];
+  /** Delay between stream chunks in ms (default 0). */
+  streamDelayMs?: number;
+  /** If set, invoke throws/errors with this ProviderError. */
+  error?: ProviderError;
+  /** When true, delay long enough for cancel to win (default false). */
+  hangUntilCancel?: boolean;
+  estimatedCostUsd?: number;
+}
+
+const DEFAULT_MODELS: FakeModelConfig[] = [
+  {
+    modelId: "fake-coder",
+    displayName: "Fake Coder",
+    supportsTools: true,
+    supportsStreaming: true,
+    supportsJson: true,
+    supportsImages: false,
+    contextWindowTokens: 32_768,
+    maxOutputTokens: 8_192,
+    estimatedCostUsd: 0,
+  },
+];
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(
+        new ProviderError({
+          code: "cancelled",
+          message: "aborted",
+          retryable: false,
+        }),
+      );
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(
+        new ProviderError({
+          code: "cancelled",
+          message: "aborted",
+          retryable: false,
+        }),
+      );
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export class FakeProviderAdapter implements ProviderAdapter {
+  readonly id: string;
+  private readonly options: Required<
+    Pick<
+      FakeProviderOptions,
+      | "authTier"
+      | "hasApiKey"
+      | "limitsDiscoverable"
+      | "opaqueLimits"
+      | "responseText"
+      | "streamChunks"
+      | "streamDelayMs"
+      | "hangUntilCancel"
+      | "estimatedCostUsd"
+    >
+  > &
+    FakeProviderOptions;
+
+  private readonly active = new Map<string, AbortController>();
+  private cancelled = new Set<string>();
+
+  constructor(options: FakeProviderOptions = {}) {
+    this.id = options.id ?? "fake";
+    this.options = {
+      authTier: options.authTier ?? "api-key",
+      hasApiKey: options.hasApiKey ?? true,
+      limitsDiscoverable: options.limitsDiscoverable ?? true,
+      opaqueLimits: options.opaqueLimits ?? false,
+      responseText: options.responseText ?? "fake-ok",
+      streamChunks: options.streamChunks ?? ["fake ", "stream ", "ok"],
+      streamDelayMs: options.streamDelayMs ?? 0,
+      hangUntilCancel: options.hangUntilCancel ?? false,
+      estimatedCostUsd: options.estimatedCostUsd ?? 0,
+      ...options,
+    };
+  }
+
+  async listModels(): Promise<ModelCapability[]> {
+    return (this.options.models ?? DEFAULT_MODELS).map((m) => ({ ...m }));
+  }
+
+  async checkAuth(): Promise<AuthStatus> {
+    const tier = this.options.authTier;
+    const hasApiKey = tier === "api-key" ? this.options.hasApiKey : false;
+    return {
+      authTier: tier,
+      authScope: tier === "api-key" ? "third-party" : "first-party",
+      configured:
+        tier === "local" || tier === "subscription" ? true : hasApiKey,
+      hasApiKey,
+      subscriptionStatus: tier === "subscription" ? "active" : undefined,
+      limitsDiscoverable: this.options.limitsDiscoverable,
+      health: "healthy",
+      credentialSource: hasApiKey ? "config" : "none",
+      subscriptionEligible: tier === "subscription",
+    };
+  }
+
+  async queryLimits(authTier: AuthTier): Promise<LimitSnapshot> {
+    if (this.options.opaqueLimits || !this.options.limitsDiscoverable) {
+      return {
+        authTier,
+        discoverable: false,
+        opaque: true,
+        metadata: {
+          reason: "provider_does_not_expose_quota",
+        },
+      };
+    }
+    return {
+      authTier,
+      discoverable: true,
+      opaque: false,
+      remaining: this.options.remaining ?? 100,
+      limit: this.options.limit ?? 100,
+      unit: "requests",
+      resetAt: "1970-01-01T01:00:00.000Z",
+      metadata: {
+        source: "fake",
+      },
+    };
+  }
+
+  async estimate(
+    request: RouteRequest,
+    model: string,
+    authTier: AuthTier,
+  ): Promise<CostEstimate> {
+    void request;
+    return {
+      model,
+      authTier,
+      estimatedCostUsd:
+        authTier === "api-key" ? this.options.estimatedCostUsd : 0,
+      currency: "USD",
+      note: "fake estimate",
+    };
+  }
+
+  async *invoke(request: ProviderInvokeRequest): AsyncIterable<ProviderEvent> {
+    if (this.cancelled.has(request.callId) || request.signal?.aborted) {
+      yield {
+        type: "error",
+        callId: request.callId,
+        error: new ProviderError({
+          code: "cancelled",
+          message: `call ${request.callId} cancelled`,
+          retryable: false,
+        }),
+      };
+      return;
+    }
+
+    const controller = new AbortController();
+    this.active.set(request.callId, controller);
+    const onExternalAbort = () => controller.abort();
+    request.signal?.addEventListener("abort", onExternalAbort, { once: true });
+
+    try {
+      yield {
+        type: "start",
+        callId: request.callId,
+        model: request.model,
+      };
+
+      if (this.options.error) {
+        yield {
+          type: "error",
+          callId: request.callId,
+          error: this.options.error,
+        };
+        return;
+      }
+
+      if (this.options.hangUntilCancel) {
+        await sleep(60_000, controller.signal);
+      }
+
+      if (this.cancelled.has(request.callId) || controller.signal.aborted) {
+        yield {
+          type: "error",
+          callId: request.callId,
+          error: new ProviderError({
+            code: "cancelled",
+            message: `call ${request.callId} cancelled`,
+            retryable: false,
+          }),
+        };
+        return;
+      }
+
+      const stream = request.stream ?? false;
+      if (stream) {
+        for (const chunk of this.options.streamChunks) {
+          if (this.cancelled.has(request.callId) || controller.signal.aborted) {
+            yield {
+              type: "error",
+              callId: request.callId,
+              error: new ProviderError({
+                code: "cancelled",
+                message: `call ${request.callId} cancelled`,
+                retryable: false,
+              }),
+            };
+            return;
+          }
+          if (this.options.streamDelayMs > 0) {
+            await sleep(this.options.streamDelayMs, controller.signal);
+          }
+          yield {
+            type: "text-delta",
+            callId: request.callId,
+            text: chunk,
+          };
+        }
+      } else {
+        yield {
+          type: "text-delta",
+          callId: request.callId,
+          text: this.options.responseText,
+        };
+      }
+
+      yield {
+        type: "usage",
+        callId: request.callId,
+        inputTokens: 10,
+        outputTokens: 5,
+        totalTokens: 15,
+      };
+      yield {
+        type: "done",
+        callId: request.callId,
+        finishReason: "stop",
+      };
+    } catch (err) {
+      if (err instanceof ProviderError && err.code === "cancelled") {
+        yield {
+          type: "error",
+          callId: request.callId,
+          error: err,
+        };
+        return;
+      }
+      throw err;
+    } finally {
+      request.signal?.removeEventListener("abort", onExternalAbort);
+      this.active.delete(request.callId);
+    }
+  }
+
+  async cancel(callId: string): Promise<void> {
+    this.cancelled.add(callId);
+    this.active.get(callId)?.abort();
+  }
+}
+
+export function createFakeProvider(
+  options?: FakeProviderOptions,
+): FakeProviderAdapter {
+  return new FakeProviderAdapter(options);
+}

package/src/providers/openai-compatible.test.ts

@@ -0,0 +1,366 @@
+import { describe, expect, it, vi } from "vitest";
+import type { RouteRequest } from "../types.js";
+import { ProviderError } from "./adapter.js";
+import {
+  OLLAMA_DUMMY_BEARER,
+  createOpenAiCompatibleAdapter,
+} from "./openai-compatible.js";
+
+function sampleRoute(): RouteRequest {
+  return {
+    protocolVersion: "offrouter.route.v1",
+    requestId: "req_oai_1",
+    harness: { kind: "claude", profile: "claude-personal" },
+    task: {
+      promptPreview: "route this",
+      promptDigest: "sha256:def",
+      kind: "code",
+      risk: "low",
+    },
+    workspace: { cwd: "/tmp", trusted: true },
+    constraints: {},
+  };
+}
+
+function sseResponse(lines: string[]): Response {
+  const encoder = new TextEncoder();
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        for (const line of lines) {
+          controller.enqueue(encoder.encode(line));
+        }
+        controller.close();
+      },
+    }),
+    {
+      status: 200,
+      headers: { "content-type": "text/event-stream" },
+    },
+  );
+}
+
+describe("OpenAI-compatible adapter", () => {
+  it("sends Authorization Bearer header for OpenRouter/xAI-style keys", async () => {
+    const seen: { auth?: string; path?: string } = {};
+    const fetchImpl = vi.fn(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input);
+        seen.path = url;
+        const headers = new Headers(init?.headers);
+        seen.auth = headers.get("authorization") ?? undefined;
+        return new Response(
+          JSON.stringify({
+            choices: [{ message: { content: "hi" }, finish_reason: "stop" }],
+            usage: { prompt_tokens: 3, completion_tokens: 1, total_tokens: 4 },
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+    );
+
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "sk-or-test",
+      fetch: fetchImpl as unknown as typeof fetch,
+      models: [
+        {
+          modelId: "openai/gpt-4.1-mini",
+          supportsTools: true,
+          supportsStreaming: true,
+          supportsJson: true,
+          supportsImages: false,
+        },
+      ],
+    });
+
+    for await (const event of adapter.invoke({
+      callId: "auth-header",
+      model: "openai/gpt-4.1-mini",
+      messages: [{ role: "user", content: "hello" }],
+    })) {
+      void event;
+      // drain
+    }
+
+    expect(fetchImpl).toHaveBeenCalled();
+    expect(seen.auth).toBe("Bearer sk-or-test");
+    expect(seen.path).toContain("/chat/completions");
+
+    // OpenRouter metadata headers
+    const firstCall = fetchImpl.mock.calls[0]!;
+    const headers = new Headers(firstCall[1]?.headers);
+    expect(headers.get("http-referer")).toBeTruthy();
+    expect(headers.get("x-title")).toBe("OffRouter");
+  });
+
+  it("uses Ollama dummy key when no API key is configured", async () => {
+    let auth: string | null = null;
+    const fetchImpl = vi.fn(
+      async (_input: RequestInfo | URL, init?: RequestInit) => {
+        auth = new Headers(init?.headers).get("authorization");
+        return new Response(
+          JSON.stringify({ choices: [{ message: { content: "local" } }] }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+    );
+
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "ollama",
+      baseUrl: "http://127.0.0.1:11434/v1",
+      flavor: "ollama",
+      fetch: fetchImpl as unknown as typeof fetch,
+      models: [
+        {
+          modelId: "llama3.2",
+          supportsTools: false,
+          supportsStreaming: true,
+          supportsJson: false,
+          supportsImages: false,
+        },
+      ],
+    });
+
+    const status = await adapter.checkAuth();
+    expect(status.configured).toBe(true);
+    expect(status.detail).toBe("using_dummy_key");
+    expect(status.authTier).toBe("local");
+    expect(status.authScope).toBe("first-party");
+    expect(status.hasApiKey).toBe(false);
+
+    for await (const event of adapter.invoke({
+      callId: "ollama-1",
+      model: "llama3.2",
+      messages: [{ role: "user", content: "hi" }],
+    })) {
+      void event;
+      // drain
+    }
+    expect(auth).toBe(OLLAMA_DUMMY_BEARER);
+  });
+
+  it("maps provider HTTP failures to canonical ProviderError on invoke", async () => {
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "xai",
+      baseUrl: "https://api.x.ai/v1",
+      flavor: "xai",
+      apiKey: "xai-key",
+      fetch: (async () =>
+        new Response(JSON.stringify({ error: "rate limit" }), {
+          status: 429,
+          headers: { "content-type": "application/json" },
+        })) as typeof fetch,
+      models: [
+        {
+          modelId: "grok-2",
+          supportsTools: true,
+          supportsStreaming: true,
+          supportsJson: true,
+          supportsImages: false,
+        },
+      ],
+    });
+
+    const errors: ProviderError[] = [];
+    for await (const event of adapter.invoke({
+      callId: "rate-1",
+      model: "grok-2",
+      messages: [{ role: "user", content: "x" }],
+    })) {
+      if (event.type === "error") errors.push(event.error);
+    }
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.code).toBe("rate_limited");
+    expect(errors[0]!.httpStatus).toBe(429);
+  });
+
+  it("blocks invoke live network by default without injected fetch", async () => {
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "http://127.0.0.1:9",
+      flavor: "openrouter",
+      apiKey: "test-key",
+      models: [],
+    });
+    const events = [];
+    for await (const event of adapter.invoke({
+      callId: "offline-guard",
+      model: "m",
+      messages: [{ role: "user", content: "x" }],
+    })) {
+      events.push(event);
+    }
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe("error");
+    if (events[0]!.type === "error") {
+      expect(events[0]!.error.code).toBe("invalid_request");
+      expect(events[0]!.error.message).toContain("requires injected fetch");
+    }
+  });
+
+  it("streams OpenAI-compatible SSE text deltas", async () => {
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "test-key",
+      fetch: (async () =>
+        sseResponse([
+          'data: {"choices":[{"delta":{"content":"hi "}}]}\n\n',
+          'data: {"choices":[{"delta":{"content":"there"}}]}\n\n',
+          "data: [DONE]\n\n",
+        ])) as typeof fetch,
+      models: [],
+    });
+
+    const texts: string[] = [];
+    let done = false;
+    for await (const event of adapter.invoke({
+      callId: "sse-1",
+      model: "openai/gpt-4.1-mini",
+      messages: [{ role: "user", content: "hello" }],
+      stream: true,
+    })) {
+      if (event.type === "text-delta") texts.push(event.text);
+      if (event.type === "done") done = true;
+    }
+    expect(texts).toEqual(["hi ", "there"]);
+    expect(done).toBe(true);
+  });
+
+  it("cancels OpenAI-compatible SSE reads while a stream is pending", async () => {
+    const encoder = new TextEncoder();
+    let streamCancelled = false;
+    const body = new ReadableStream<Uint8Array>({
+      start(c) {
+        c.enqueue(
+          encoder.encode(
+            'data: {"choices":[{"delta":{"content":"first"}}]}\n\n',
+          ),
+        );
+      },
+      cancel() {
+        streamCancelled = true;
+      },
+    });
+
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "test-key",
+      fetch: (async () =>
+        new Response(body, {
+          status: 200,
+          headers: { "content-type": "text/event-stream" },
+        })) as typeof fetch,
+      models: [],
+    });
+
+    const callId = "sse-cancel";
+    const iterable = adapter.invoke({
+      callId,
+      model: "openai/gpt-4.1-mini",
+      messages: [{ role: "user", content: "hello" }],
+      stream: true,
+    });
+    const iterator = iterable[Symbol.asyncIterator]();
+
+    expect((await iterator.next()).value?.type).toBe("start");
+    expect((await iterator.next()).value).toMatchObject({
+      type: "text-delta",
+      text: "first",
+    });
+
+    const pending = iterator.next();
+    await adapter.cancel(callId);
+    const cancelled = await pending;
+    expect(cancelled.value).toMatchObject({
+      type: "error",
+      error: expect.objectContaining({ code: "cancelled" }),
+    });
+    expect(streamCancelled).toBe(true);
+  });
+
+  it("reports opaque limits for SaaS OpenRouter by default", async () => {
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "k",
+      models: [],
+    });
+    const limits = await adapter.queryLimits("api-key");
+    expect(limits.opaque).toBe(true);
+    expect(limits.discoverable).toBe(false);
+    expect(limits.metadata?.flavor).toBe("openrouter");
+  });
+
+  it("estimates cost heuristically without network", async () => {
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "k",
+      estimatedCostUsdPer1kTokens: 1,
+      models: [],
+    });
+    const est = await adapter.estimate(sampleRoute(), "m", "api-key");
+    expect(est.estimatedCostUsd).toBeGreaterThan(0);
+    expect(est.currency).toBe("USD");
+  });
+
+  it("does not make live network calls for listModels when models are injected", async () => {
+    const fetchImpl = vi.fn();
+    const adapter = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      apiKey: "k",
+      fetch: fetchImpl as unknown as typeof fetch,
+      models: [
+        {
+          modelId: "m1",
+          supportsTools: true,
+          supportsStreaming: true,
+          supportsJson: true,
+          supportsImages: false,
+        },
+      ],
+    });
+    const models = await adapter.listModels();
+    expect(models).toHaveLength(1);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("api-key presence is boolean only in checkAuth", async () => {
+    const missing = createOpenAiCompatibleAdapter({
+      id: "openrouter",
+      baseUrl: "https://openrouter.example/api/v1",
+      flavor: "openrouter",
+      models: [],
+    });
+    const status = await missing.checkAuth();
+    expect(status.hasApiKey).toBe(false);
+    expect(status.configured).toBe(false);
+    // Ensure we never invent secret fields on the auth surface.
+    for (const key of Object.keys(status)) {
+      expect([
+        "authScope",
+        "authTier",
+        "configured",
+        "credentialSource",
+        "detail",
+        "hasApiKey",
+        "health",
+        "limitsDiscoverable",
+        "subscriptionEligible",
+        "subscriptionStatus",
+      ]).toContain(key);
+    }
+    expect("apiKey" in status).toBe(false);
+  });
+});