offrouter-core 0.2.0 → 0.2.2

package/src/policy.ts

@@ -1,420 +0,0 @@
-/**
- * Profile and candidate policy engine for OffRouter V1.
- * Hard filters first; subscription-first rules gate API-key candidates.
- */
-import type {
-  PolicyDecision,
-  PolicyDenial,
-  ProviderCandidate,
-  RouteRequest,
-  SubscriptionStatus,
-} from "./types.js";
-
-export interface PolicyConfig {
-  /** Profiles explicitly allowed to route through OffRouter. */
-  allowlistedProfiles: string[];
-  /**
-   * Glob-like patterns for denied profiles (supports `*` wildcards).
-   * Default use case: `*-work`.
-   */
-  deniedProfilePatterns?: string[];
-  /**
-   * When false (default), subscription-tier candidates must be first-party.
-   * Third-party subscription adapters are denied unless opted in.
-   */
-  allowThirdPartySubscriptionAdapters?: boolean;
-  /** Optional explicit provider deny list by providerId. */
-  deniedProviders?: string[];
-  /** Fraction of subscription quota remaining at/under which an account is "near-limit". Default 0.2. */
-  nearLimitThreshold?: number;
-}
-
-const HEALTHY_SUBSCRIPTION_STATUSES: ReadonlySet<SubscriptionStatus> = new Set([
-  "active",
-]);
-
-const UNAVAILABLE_SUBSCRIPTION_STATUSES: ReadonlySet<SubscriptionStatus> =
-  new Set(["exhausted", "rate-limited", "expired", "unconfigured", "unknown"]);
-
-function candidateId(c: ProviderCandidate): string {
-  return `${c.providerId}:${c.modelId}`;
-}
-
-function matchesGlob(pattern: string, value: string): boolean {
-  // Escape regex special chars except *, then turn * into .*
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-  const re = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
-  return re.test(value);
-}
-
-function isWorkProfileDenied(
-  profile: string,
-  patterns: string[] | undefined,
-): boolean {
-  // Work profiles are denied by default. Custom patterns are additive.
-  // Align with the Claude installer: a profile is work-like if it ends with
-  // "-work" (e.g. claude-work) or contains "-work-" (e.g. claude-work-staging).
-  const effectivePatterns = ["*-work", ...(patterns ?? [])];
-  return (
-    profile.endsWith("-work") ||
-    profile.includes("-work-") ||
-    effectivePatterns.some((pattern) => matchesGlob(pattern, profile))
-  );
-}
-
-function isAllowedProfile(profile: string, config: PolicyConfig): boolean {
-  return config.allowlistedProfiles.includes(profile);
-}
-
-/**
- * Whether a candidate meets hard capability requirements from the task.
- */
-export function meetsCapabilities(
-  candidate: ProviderCandidate,
-  request: RouteRequest,
-): boolean {
-  const { task } = request;
-  if (task.requiresTools && !candidate.supportsTools) return false;
-  if (task.requiresImages && !candidate.supportsImages) return false;
-  if (task.requiresStreaming && !candidate.supportsStreaming) return false;
-  if (task.requiresJson && !candidate.supportsJson) return false;
-  // Task kind shortcuts when requires* not set explicitly
-  if (task.kind === "tools" && task.requiresTools !== false && !candidate.supportsTools) {
-    return false;
-  }
-  if (task.kind === "image" && task.requiresImages !== false && !candidate.supportsImages) {
-    return false;
-  }
-  return true;
-}
-
-function missingCapabilityMessage(
-  candidate: ProviderCandidate,
-  request: RouteRequest,
-): string {
-  const missing: string[] = [];
-  if (
-    (request.task.requiresTools || request.task.kind === "tools") &&
-    !candidate.supportsTools
-  ) {
-    missing.push("tools");
-  }
-  if (
-    (request.task.requiresImages || request.task.kind === "image") &&
-    !candidate.supportsImages
-  ) {
-    missing.push("images");
-  }
-  if (request.task.requiresStreaming && !candidate.supportsStreaming) {
-    missing.push("streaming");
-  }
-  if (request.task.requiresJson && !candidate.supportsJson) {
-    missing.push("json");
-  }
-  return `Candidate ${candidateId(candidate)} missing required capabilities: ${missing.join(", ") || "unknown"}.`;
-}
-
-/**
- * Healthy subscription capacity: active status (or omitted treated carefully)
- * with non-dead health, and policy/capability eligible.
- *
- * Degraded health is still "usable" for routing later but is not treated as
- * fully healthy capacity for blocking API-key candidates when another healthy
- * subscription exists — that nuance lives in the router score. For policy
- * gatekeeping "can a healthy subscription satisfy the task?", we accept
- * health === "healthy" and subscriptionStatus in active (defaulting missing
- * status on subscription tier to unknown, not healthy).
- */
-export function isHealthySubscriptionCapacity(
-  candidate: ProviderCandidate,
-  request: RouteRequest,
-  config: PolicyConfig,
-): boolean {
-  if (candidate.authTier !== "subscription") return false;
-  if (candidate.health !== "healthy") return false;
-
-  const status = candidate.subscriptionStatus ?? "unknown";
-  if (!HEALTHY_SUBSCRIPTION_STATUSES.has(status)) return false;
-
-  if (
-    candidate.authScope === "third-party" &&
-    !config.allowThirdPartySubscriptionAdapters
-  ) {
-    return false;
-  }
-  if (candidate.authScope === "unknown") {
-    return false;
-  }
-
-  if (!meetsCapabilities(candidate, request)) return false;
-
-  // Subscription positions are never local; localOnly excludes them.
-  if (request.constraints.localOnly) {
-    return false;
-  }
-
-  if (
-    request.constraints.maxCostUsd !== undefined &&
-    candidate.estimatedCostUsd !== undefined &&
-    candidate.estimatedCostUsd > request.constraints.maxCostUsd
-  ) {
-    return false;
-  }
-
-  if (config.deniedProviders?.includes(candidate.providerId)) {
-    return false;
-  }
-
-  return true;
-}
-
-/**
- * Whether any remaining subscription candidate has healthy capacity after hard
- * filters, so API-key stays blocked only while a healthy subscription route can
- * satisfy the task.
- */
-function hasUsableSubscriptionForTask(
-  candidates: ProviderCandidate[],
-  request: RouteRequest,
-  config: PolicyConfig,
-): boolean {
-  return candidates.some((c) => {
-    if (c.authTier !== "subscription") return false;
-    if (c.health !== "healthy") return false;
-    const status = c.subscriptionStatus ?? "unknown";
-    // Only active + healthy subscription capacity blocks API-key candidates
-    // under subscription-first.
-    if (!HEALTHY_SUBSCRIPTION_STATUSES.has(status)) return false;
-    if (
-      c.authScope === "third-party" &&
-      !config.allowThirdPartySubscriptionAdapters
-    ) {
-      return false;
-    }
-    if (c.authScope === "unknown") return false;
-    if (!meetsCapabilities(c, request)) return false;
-    if (request.constraints.localOnly) return false;
-    if (
-      request.constraints.maxCostUsd !== undefined &&
-      c.estimatedCostUsd !== undefined &&
-      c.estimatedCostUsd > request.constraints.maxCostUsd
-    ) {
-      return false;
-    }
-    if (config.deniedProviders?.includes(c.providerId)) return false;
-    return true;
-  });
-}
-
-function hardFilterDenial(
-  candidate: ProviderCandidate,
-  request: RouteRequest,
-  config: PolicyConfig,
-): PolicyDenial | null {
-  const id = candidateId(candidate);
-
-  if (config.deniedProviders?.includes(candidate.providerId)) {
-    return {
-      code: "provider_denied",
-      target: "provider",
-      id: candidate.providerId,
-      message: `Provider ${candidate.providerId} is denied by policy.`,
-    };
-  }
-
-  if (request.constraints.localOnly && candidate.authTier !== "local") {
-    return {
-      code: "local_only_required",
-      target: "candidate",
-      id,
-      message: `Candidate ${id} is not a local runtime; localOnly is required.`,
-    };
-  }
-
-  if (
-    request.constraints.maxCostUsd !== undefined &&
-    candidate.authTier === "api-key" &&
-    candidate.estimatedCostUsd === undefined
-  ) {
-    return {
-      code: "cost_cap_exceeded",
-      target: "candidate",
-      id,
-      message: `API-key candidate ${id} has unknown cost and cannot satisfy maxCostUsd ${request.constraints.maxCostUsd}.`,
-    };
-  }
-
-  if (
-    request.constraints.maxCostUsd !== undefined &&
-    candidate.estimatedCostUsd !== undefined &&
-    candidate.estimatedCostUsd > request.constraints.maxCostUsd
-  ) {
-    return {
-      code: "cost_cap_exceeded",
-      target: "candidate",
-      id,
-      message: `Candidate ${id} estimated cost ${candidate.estimatedCostUsd} exceeds maxCostUsd ${request.constraints.maxCostUsd}.`,
-    };
-  }
-
-  if (!meetsCapabilities(candidate, request)) {
-    return {
-      code: "capability_missing",
-      target: "candidate",
-      id,
-      message: missingCapabilityMessage(candidate, request),
-    };
-  }
-
-  // First-party subscription surface via third-party adapter
-  if (
-    candidate.authTier === "subscription" &&
-    candidate.authScope === "third-party" &&
-    !config.allowThirdPartySubscriptionAdapters
-  ) {
-    return {
-      code: "subscription_scope_denied",
-      target: "candidate",
-      id,
-      message: `Subscription candidate ${id} uses a third-party adapter surface without policy allow.`,
-    };
-  }
-
-  if (
-    candidate.authTier === "subscription" &&
-    candidate.authScope === "unknown"
-  ) {
-    return {
-      code: "subscription_scope_denied",
-      target: "candidate",
-      id,
-      message: `Subscription candidate ${id} has unknown auth scope and cannot route until the adapter proves support.`,
-    };
-  }
-
-  // Dead candidates never route
-  if (candidate.health === "dead") {
-    // Treat as policy-ineligible for selection; keep as structured denial so
-    // explain paths can show why. Prefer provider_denied-ish message without
-    // inventing a new code — map to provider_denied for dead health is
-    // slightly imprecise; capability isn't right. Use provider_denied for
-    // explicit denylist only. For dead, we skip without adding denial so
-    // they simply don't appear as allowed. Router will then handle empty set.
-    // Actually: don't allow them, no denial needed for "dead" — just exclude.
-    return {
-      code: "provider_denied",
-      target: "candidate",
-      id,
-      message: `Candidate ${id} is dead and cannot be selected.`,
-    };
-  }
-
-  // Exhausted/rate-limited/expired subscription tiers are not allowed as primary
-  if (candidate.authTier === "subscription") {
-    const status = candidate.subscriptionStatus ?? "unknown";
-    if (UNAVAILABLE_SUBSCRIPTION_STATUSES.has(status)) {
-      return {
-        code: "provider_denied",
-        target: "candidate",
-        id,
-        message: `Subscription candidate ${id} is ${status} and cannot satisfy the task.`,
-      };
-    }
-  }
-
-  return null;
-}
-
-/**
- * Evaluate profile and candidate policy.
- * Returns allowed candidates plus structured denials (never string-only).
- */
-export function evaluatePolicy(
-  request: RouteRequest,
-  candidates: ProviderCandidate[],
-  config: PolicyConfig,
-): PolicyDecision {
-  const denials: PolicyDenial[] = [];
-  const profile = request.harness.profile;
-
-  // 1. Profile gates
-  if (isWorkProfileDenied(profile, config.deniedProfilePatterns)) {
-    denials.push({
-      code: "work_profile_denied",
-      target: "profile",
-      id: profile,
-      message: `Work profile ${profile} is denied by default. OffRouter V1 only routes allowlisted personal profiles.`,
-    });
-    return { allowed: [], denials };
-  }
-
-  if (!isAllowedProfile(profile, config)) {
-    denials.push({
-      code: "profile_not_allowlisted",
-      target: "profile",
-      id: profile,
-      message: `Profile ${profile} is not allowlisted. Add it explicitly before installing or routing.`,
-    });
-    return { allowed: [], denials };
-  }
-
-  // Workspace trust is a hard filter when untrusted
-  if (!request.workspace.trusted) {
-    denials.push({
-      code: "project_untrusted",
-      target: "workspace",
-      id: request.workspace.cwd,
-      message: `Workspace ${request.workspace.cwd} is untrusted; routing is blocked.`,
-    });
-    return { allowed: [], denials };
-  }
-
-  // 2. Hard filters per candidate
-  const hardPassed: ProviderCandidate[] = [];
-  for (const c of candidates) {
-    const denial = hardFilterDenial(c, request, config);
-    if (denial) {
-      denials.push(denial);
-    } else {
-      hardPassed.push(c);
-    }
-  }
-
-  // 3. Subscription-first: gate API-key when usable subscription capacity exists,
-  //    or when allowApiKeyFallback is false.
-  const subscriptionFirst = request.constraints.subscriptionFirst !== false;
-  const allowApiKeyFallback = request.constraints.allowApiKeyFallback === true;
-
-  const usableSubscription = hasUsableSubscriptionForTask(
-    hardPassed,
-    request,
-    config,
-  );
-
-  const allowed: ProviderCandidate[] = [];
-  for (const c of hardPassed) {
-    if (c.authTier === "api-key") {
-      if (subscriptionFirst && usableSubscription) {
-        denials.push({
-          code: "api_key_blocked_by_subscription_first_policy",
-          target: "candidate",
-          id: candidateId(c),
-          message: `API-key candidate ${candidateId(c)} blocked while healthy subscription capacity remains.`,
-        });
-        continue;
-      }
-      if (subscriptionFirst && !allowApiKeyFallback) {
-        denials.push({
-          code: "api_key_blocked_by_subscription_first_policy",
-          target: "candidate",
-          id: candidateId(c),
-          message: `API-key candidate ${candidateId(c)} blocked: allowApiKeyFallback is false.`,
-        });
-        continue;
-      }
-    }
-    allowed.push(c);
-  }
-
-  return { allowed, denials };
-}

package/src/providers/adapter.test.ts

@@ -1,293 +0,0 @@
-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);
-  });
-});