offrouter-core 0.0.0

package/src/router.test.ts

@@ -0,0 +1,562 @@
+import { describe, expect, it } from "vitest";
+import type { PolicyConfig } from "./policy.js";
+import { routeRequest } from "./router.js";
+import type { ProviderCandidate, RouteRequest } from "./types.js";
+
+function baseRequest(
+  overrides: Partial<RouteRequest> & {
+    harness?: Partial<RouteRequest["harness"]>;
+    task?: Partial<RouteRequest["task"]>;
+    workspace?: Partial<RouteRequest["workspace"]>;
+    constraints?: Partial<RouteRequest["constraints"]>;
+  } = {},
+): RouteRequest {
+  return {
+    protocolVersion: "offrouter.route.v1",
+    requestId: overrides.requestId ?? "req_1",
+    harness: {
+      kind: "claude",
+      profile: "claude-personal",
+      ...overrides.harness,
+    },
+    task: {
+      promptPreview: "explain this repo",
+      promptDigest: "sha256:example",
+      kind: "explain",
+      risk: "low",
+      ...overrides.task,
+    },
+    workspace: {
+      cwd: "/tmp/project",
+      trusted: true,
+      ...overrides.workspace,
+    },
+    constraints: {
+      maxCostUsd: 1,
+      localOnly: false,
+      subscriptionFirst: true,
+      allowApiKeyFallback: true,
+      ...overrides.constraints,
+    },
+  };
+}
+
+function candidate(
+  partial: Partial<ProviderCandidate> &
+    Pick<ProviderCandidate, "providerId" | "modelId" | "authTier">,
+): ProviderCandidate {
+  return {
+    authScope: "first-party",
+    health: "healthy",
+    supportsTools: true,
+    supportsStreaming: true,
+    supportsJson: true,
+    supportsImages: false,
+    estimatedCostUsd: 0.01,
+    ...partial,
+  };
+}
+
+const personalConfig: PolicyConfig = {
+  allowlistedProfiles: ["claude-personal", "codex-personal", "gemini-personal"],
+  deniedProfilePatterns: ["*-work"],
+};
+
+describe("routeRequest", () => {
+  it("picks a cheap fast allowed candidate for a simple low-risk explain task", () => {
+    const decision = routeRequest(
+      baseRequest({
+        task: { kind: "explain", risk: "low" },
+      }),
+      [
+        candidate({
+          providerId: "slow",
+          modelId: "heavy",
+          authTier: "api-key",
+          estimatedCostUsd: 0.2,
+        }),
+        candidate({
+          providerId: "cheap",
+          modelId: "fast",
+          authTier: "api-key",
+          estimatedCostUsd: 0.001,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.blocked).toBeFalsy();
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "cheap",
+        model: "fast",
+        authTier: "api-key",
+      }),
+    );
+    expect(decision.reason).toBeTruthy();
+    expect(decision.explanation).toBeTruthy();
+    expect(decision.fallbackChain?.[0]).toEqual(
+      expect.objectContaining({
+        provider: "cheap",
+        model: "fast",
+        reason: "primary",
+      }),
+    );
+  });
+
+  it("prefers a healthy subscription-backed candidate over a cheaper API-key candidate", () => {
+    const decision = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+      }),
+      [
+        candidate({
+          providerId: "openrouter",
+          modelId: "fast",
+          authTier: "api-key",
+          authScope: "third-party",
+          estimatedCostUsd: 0.0001,
+        }),
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+          health: "healthy",
+          estimatedCostUsd: 0,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "claude",
+        model: "sonnet",
+        authTier: "subscription",
+      }),
+    );
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "api_key_blocked_by_subscription_first_policy",
+      }),
+    );
+  });
+
+  it("falls through exhausted subscription to API-key only when allowApiKeyFallback is true", () => {
+    const candidates = [
+      candidate({
+        providerId: "claude",
+        modelId: "sonnet",
+        authTier: "subscription",
+        subscriptionStatus: "exhausted",
+        health: "healthy",
+      }),
+      candidate({
+        providerId: "openrouter",
+        modelId: "fast",
+        authTier: "api-key",
+        authScope: "third-party",
+        estimatedCostUsd: 0.01,
+      }),
+    ];
+
+    const allowed = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+      }),
+      candidates,
+      personalConfig,
+    );
+    expect(allowed.route).toEqual(
+      expect.objectContaining({
+        provider: "openrouter",
+        model: "fast",
+        authTier: "api-key",
+      }),
+    );
+    expect(allowed.fallbackChain?.[0]?.reason).toBe("api_key_fallback");
+    expect(allowed.explanation.toLowerCase()).toMatch(/api-?key|fallback/);
+
+    const blocked = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: false },
+      }),
+      candidates,
+      personalConfig,
+    );
+    expect(blocked.blocked).toBe(true);
+    expect(blocked.route == null).toBe(true);
+    expect(blocked.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "api_key_blocked_by_subscription_first_policy",
+      }),
+    );
+  });
+
+  it("prefers the next healthy subscription over API-key when one subscription is degraded", () => {
+    const decision = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+      }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "opus",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+          health: "degraded",
+          estimatedCostUsd: 0,
+        }),
+        candidate({
+          providerId: "openrouter",
+          modelId: "fast",
+          authTier: "api-key",
+          authScope: "third-party",
+          estimatedCostUsd: 0.001,
+        }),
+        candidate({
+          providerId: "codex",
+          modelId: "default",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+          health: "healthy",
+          estimatedCostUsd: 0,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "codex",
+        model: "default",
+        authTier: "subscription",
+      }),
+    );
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "api_key_blocked_by_subscription_first_policy",
+      }),
+    );
+  });
+
+  it("prefers local runtime over degraded subscription before API-key fallback", () => {
+    const decision = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+      }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+          health: "degraded",
+          estimatedCostUsd: 0,
+        }),
+        candidate({
+          providerId: "ollama",
+          modelId: "local-fast",
+          authTier: "local",
+          estimatedCostUsd: 0,
+        }),
+        candidate({
+          providerId: "openrouter",
+          modelId: "fast",
+          authTier: "api-key",
+          authScope: "third-party",
+          estimatedCostUsd: 0.001,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "ollama",
+        model: "local-fast",
+        authTier: "local",
+      }),
+    );
+    expect(decision.policyDenials).not.toContainEqual(
+      expect.objectContaining({
+        code: "api_key_blocked_by_subscription_first_policy",
+      }),
+    );
+  });
+
+  it("denies API-key with api_key_blocked_by_subscription_first_policy when subscription-first applies", () => {
+    const decision = routeRequest(
+      baseRequest({
+        constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+      }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+          health: "healthy",
+        }),
+        candidate({
+          providerId: "openrouter",
+          modelId: "fast",
+          authTier: "api-key",
+          authScope: "third-party",
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "api_key_blocked_by_subscription_first_policy",
+        id: "openrouter:fast",
+      }),
+    );
+  });
+
+  it("excludes candidates without tool support for tool tasks", () => {
+    const decision = routeRequest(
+      baseRequest({
+        task: { kind: "tools", risk: "medium", requiresTools: true },
+      }),
+      [
+        candidate({
+          providerId: "text-only",
+          modelId: "chat",
+          authTier: "api-key",
+          supportsTools: false,
+          estimatedCostUsd: 0.001,
+        }),
+        candidate({
+          providerId: "toolful",
+          modelId: "agent",
+          authTier: "api-key",
+          supportsTools: true,
+          estimatedCostUsd: 0.02,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "toolful",
+        model: "agent",
+      }),
+    );
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "capability_missing",
+        id: "text-only:chat",
+      }),
+    );
+  });
+
+  it("excludes text-only models for image tasks", () => {
+    const decision = routeRequest(
+      baseRequest({
+        task: { kind: "image", risk: "low", requiresImages: true },
+      }),
+      [
+        candidate({
+          providerId: "text",
+          modelId: "no-vision",
+          authTier: "api-key",
+          supportsImages: false,
+          estimatedCostUsd: 0.001,
+        }),
+        candidate({
+          providerId: "vision",
+          modelId: "see",
+          authTier: "api-key",
+          supportsImages: true,
+          estimatedCostUsd: 0.05,
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.route).toEqual(
+      expect.objectContaining({
+        provider: "vision",
+        model: "see",
+      }),
+    );
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "capability_missing",
+        id: "text:no-vision",
+      }),
+    );
+  });
+
+  it("returns a blocked decision for a denied work profile", () => {
+    const decision = routeRequest(
+      baseRequest({ harness: { profile: "claude-work" } }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.blocked).toBe(true);
+    expect(decision.route == null).toBe(true);
+    expect(decision.needsConfiguration).toBeFalsy();
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "work_profile_denied",
+        id: "claude-work",
+      }),
+    );
+    expect(decision.explanation.toLowerCase()).toMatch(/work|denied|blocked/);
+  });
+
+  it("returns a blocked decision for an untrusted workspace", () => {
+    const decision = routeRequest(
+      baseRequest({ workspace: { trusted: false } }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+        }),
+      ],
+      personalConfig,
+    );
+
+    expect(decision.blocked).toBe(true);
+    expect(decision.route == null).toBe(true);
+    expect(decision.needsConfiguration).toBe(false);
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "project_untrusted",
+      }),
+    );
+  });
+
+  it("returns needsConfiguration when no candidate is available", () => {
+    const decision = routeRequest(baseRequest(), [], personalConfig);
+
+    expect(decision.blocked).toBe(true);
+    expect(decision.needsConfiguration).toBe(true);
+    expect(decision.route == null).toBe(true);
+    expect(decision.reason).toMatch(/configuration|no_candidate|none/i);
+    expect(decision.explanation.toLowerCase()).toMatch(
+      /configur|no candidate|provider/,
+    );
+  });
+
+  it("returns needsConfiguration for an unallowlisted personal profile when no candidate is available", () => {
+    const decision = routeRequest(
+      baseRequest({ harness: { profile: "cursor-personal" } }),
+      [],
+      personalConfig,
+    );
+
+    expect(decision.blocked).toBe(true);
+    expect(decision.needsConfiguration).toBe(true);
+    expect(decision.route == null).toBe(true);
+    expect(decision.reason).toMatch(/configuration|no_candidate|none/i);
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "profile_not_allowlisted",
+        id: "cursor-personal",
+      }),
+    );
+  });
+
+  it("hard-blocks a work profile even when no candidate is available", () => {
+    const decision = routeRequest(
+      baseRequest({ harness: { profile: "claude-work" } }),
+      [],
+      personalConfig,
+    );
+
+    expect(decision.blocked).toBe(true);
+    expect(decision.needsConfiguration).toBe(false);
+    expect(decision.route == null).toBe(true);
+    expect(decision.policyDenials).toContainEqual(
+      expect.objectContaining({
+        code: "work_profile_denied",
+        id: "claude-work",
+      }),
+    );
+  });
+
+  it("is deterministic for the same inputs", () => {
+    const request = baseRequest();
+    const candidates = [
+      candidate({
+        providerId: "b",
+        modelId: "two",
+        authTier: "api-key",
+        estimatedCostUsd: 0.02,
+      }),
+      candidate({
+        providerId: "a",
+        modelId: "one",
+        authTier: "api-key",
+        estimatedCostUsd: 0.01,
+      }),
+    ];
+
+    const a = routeRequest(request, candidates, personalConfig);
+    const b = routeRequest(request, candidates, personalConfig);
+
+    expect(a.route).toEqual(b.route);
+    expect(a.reason).toEqual(b.reason);
+    expect(a.fallbackChain).toEqual(b.fallbackChain);
+  });
+
+  it("keeps audit summaries digest-only and excludes prompt previews", () => {
+    const request = baseRequest({
+      task: {
+        promptPreview: "raw user text that should not appear in audit",
+        promptDigest: "sha256:redacted",
+      },
+    });
+
+    const success = routeRequest(
+      request,
+      [
+        candidate({
+          providerId: "cheap",
+          modelId: "fast",
+          authTier: "api-key",
+          estimatedCostUsd: 0.001,
+        }),
+      ],
+      personalConfig,
+    );
+    const blocked = routeRequest(
+      baseRequest({
+        harness: { profile: "claude-work" },
+        task: request.task,
+      }),
+      [
+        candidate({
+          providerId: "claude",
+          modelId: "sonnet",
+          authTier: "subscription",
+          subscriptionStatus: "active",
+        }),
+      ],
+      personalConfig,
+    );
+    const needsConfiguration = routeRequest(request, [], personalConfig);
+
+    for (const decision of [success, blocked, needsConfiguration]) {
+      expect(decision.auditSummary).toContain("sha256:redacted");
+      expect(decision.auditSummary).not.toContain("raw user text");
+    }
+  });
+});