offrouter-core 0.2.1 → 0.2.2

package/src/router.ts

@@ -1,352 +0,0 @@
-/**
- * Deterministic model scoring and route explain for OffRouter V1.
- */
-import { evaluatePolicy, type PolicyConfig } from "./policy.js";
-import { ROUTE_PROTOCOL_VERSION } from "./protocol.js";
-import type {
-  FallbackChainEntry,
-  FallbackReason,
-  ProviderCandidate,
-  RouteDecision,
-  RouteRequest,
-} from "./types.js";
-
-export interface RouteOptions {
-  /** Optional decision id factory for tests; defaults to deterministic hash-ish id. */
-  decisionId?: string;
-}
-
-function candidateId(c: ProviderCandidate): string {
-  return `${c.providerId}:${c.modelId}`;
-}
-
-/**
- * Rank score: higher is better.
- * Order of preference:
- * 1. Healthy active subscription (status !== "near-limit")
- * 2. Healthy near-limit subscription
- * 3. Local
- * 4. Degraded subscription (active + degraded)
- * 5. API-key
- * Within same tier: lower estimatedCostUsd, then providerId, then modelId.
- */
-function rankKey(c: ProviderCandidate): [number, number, string, string] {
-  let tierRank: number;
-  if (c.authTier === "subscription") {
-    if (c.health === "healthy") {
-      tierRank = c.subscriptionStatus === "near-limit" ? 350 : 400;
-    } else if (c.health === "degraded") {
-      tierRank = 200;
-    } else {
-      tierRank = 0;
-    }
-  } else if (c.authTier === "local") {
-    tierRank = 300;
-  } else {
-    // api-key
-    tierRank = 100;
-  }
-
-  // Invert cost so higher is better; missing cost treated as mid-ish.
-  const cost = c.estimatedCostUsd ?? 0.05;
-  const costScore = -cost;
-
-  return [tierRank, costScore, c.providerId, c.modelId];
-}
-
-function sortCandidates(candidates: ProviderCandidate[]): ProviderCandidate[] {
-  return [...candidates].sort((a, b) => {
-    const ka = rankKey(a);
-    const kb = rankKey(b);
-    // tierRank desc
-    if (ka[0] !== kb[0]) return kb[0] - ka[0];
-    // costScore desc (higher costScore => cheaper)
-    if (ka[1] !== kb[1]) return (kb[1] as number) - (ka[1] as number);
-    if (a.providerId !== b.providerId) {
-      return a.providerId < b.providerId ? -1 : 1;
-    }
-    if (a.modelId !== b.modelId) {
-      return a.modelId < b.modelId ? -1 : 1;
-    }
-    return 0;
-  });
-}
-
-function selectionReason(winner: ProviderCandidate): {
-  reason: string;
-  fallbackReason: FallbackReason;
-  explanation: string;
-} {
-  if (winner.authTier === "subscription") {
-    if (winner.health === "degraded") {
-      return {
-        reason: "subscription_degraded",
-        fallbackReason: "subscription_degraded",
-        explanation: `Selected degraded subscription candidate ${candidateId(winner)} as the best available subscription-backed route.`,
-      };
-    }
-    return {
-      reason: "subscription_primary",
-      fallbackReason: "primary",
-      explanation: `Selected healthy subscription-backed candidate ${candidateId(winner)} over lower-priority routes.`,
-    };
-  }
-  if (winner.authTier === "local") {
-    return {
-      reason: "local_preferred",
-      fallbackReason: "local_preferred",
-      explanation: `Selected local runtime candidate ${candidateId(winner)}.`,
-    };
-  }
-  return {
-    reason: "api_key_fallback",
-    fallbackReason: "api_key_fallback",
-    explanation: `Selected API-key candidate ${candidateId(winner)} because no healthy subscription candidate could satisfy the task.`,
-  };
-}
-
-function buildFallbackChain(
-  sorted: ProviderCandidate[],
-  winner: ProviderCandidate,
-): FallbackChainEntry[] {
-  const { fallbackReason } = selectionReason(winner);
-  const chain: FallbackChainEntry[] = [
-    {
-      provider: winner.providerId,
-      model: winner.modelId,
-      authTier: winner.authTier,
-      reason: fallbackReason,
-    },
-  ];
-
-  // Include a short ordered list of alternative ranked candidates for explain.
-  for (const c of sorted) {
-    if (c.providerId === winner.providerId && c.modelId === winner.modelId) {
-      continue;
-    }
-    let reason: FallbackReason = "primary";
-    if (c.authTier === "api-key") {
-      reason = "api_key_fallback";
-    } else if (c.authTier === "local") {
-      reason = "local_preferred";
-    } else if (c.health === "degraded") {
-      reason = "subscription_degraded";
-    } else if (c.subscriptionStatus === "exhausted") {
-      reason = "subscription_exhausted";
-    } else if (c.subscriptionStatus === "unconfigured") {
-      reason = "subscription_unconfigured";
-    }
-    chain.push({
-      provider: c.providerId,
-      model: c.modelId,
-      authTier: c.authTier,
-      reason,
-    });
-    if (chain.length >= 5) break;
-  }
-  return chain;
-}
-
-function confidenceFor(winner: ProviderCandidate, nAllowed: number): number {
-  if (winner.authTier === "subscription" && winner.health === "healthy") {
-    return nAllowed === 1 ? 0.95 : 0.9;
-  }
-  if (winner.authTier === "local") return 0.8;
-  if (winner.authTier === "subscription") return 0.7;
-  return 0.6;
-}
-
-/**
- * Route a request against candidates under policy.
- * Pure and deterministic: same inputs -> same decision (except optional decisionId).
- */
-export function routeRequest(
-  request: RouteRequest,
-  candidates: ProviderCandidate[],
-  config: PolicyConfig,
-  options: RouteOptions = {},
-): RouteDecision {
-  const decisionId =
-    options.decisionId ??
-    `dec_${request.requestId}_${candidates.length}_${request.harness.profile}`;
-
-  // Empty catalog -> needs configuration (even before profile denials, so
-  // tests/docs can distinguish "no providers set up"). But work profiles still
-  // block on policy; empty list with blocked profile binary is fine either way.
-  // Spec: "no candidate returns actionable needsConfiguration"
-  // Spec: "denied work profile returns blocked decision" (needsConfiguration false).
-  if (candidates.length === 0) {
-    // Still surface hard policy denials. Work/untrusted contexts should not
-    // be framed as "needs configuration".
-    const policy = evaluatePolicy(request, candidates, config);
-    const hardBlock = policy.denials.some(
-      (d) =>
-        d.code === "work_profile_denied" ||
-        d.code === "privacy_label_denied" ||
-        d.code === "project_untrusted",
-    );
-    if (hardBlock) {
-      return {
-        protocolVersion: ROUTE_PROTOCOL_VERSION,
-        decisionId,
-        requestId: request.requestId,
-        route: null,
-        reason: "policy_blocked",
-        explanation: policy.denials.map((d) => d.message).join(" "),
-        fallbackChain: [],
-        policyDenials: policy.denials,
-        confidence: 1,
-        auditSummary: `Blocked profile=${request.harness.profile} digests=${request.task.promptDigest}`,
-        blocked: true,
-        needsConfiguration: false,
-      };
-    }
-    return {
-      protocolVersion: ROUTE_PROTOCOL_VERSION,
-      decisionId,
-      requestId: request.requestId,
-      route: null,
-      reason: "no_candidate_needs_configuration",
-      explanation:
-        "No provider candidates are available. Configure a subscription, local runtime, or API-key provider before routing.",
-      fallbackChain: [],
-      policyDenials: policy.denials,
-      confidence: 1,
-      auditSummary: `Needs configuration profile=${request.harness.profile} digest=${request.task.promptDigest}`,
-      blocked: true,
-      needsConfiguration: true,
-    };
-  }
-
-  const policy = evaluatePolicy(request, candidates, config);
-
-  if (policy.allowed.length === 0) {
-    const profileHardBlock = policy.denials.some(
-      (d) =>
-        d.code === "work_profile_denied" ||
-        d.code === "profile_not_allowlisted" ||
-        d.code === "project_untrusted",
-    );
-
-    // If candidates existed but all filtered: may be needsConfiguration when
-    // nothing is policy-profile blocked and no usable routes after hard filters.
-    const onlyCapabilityOrCostOrApiKey = policy.denials.every(
-      (d) =>
-        d.code === "capability_missing" ||
-        d.code === "cost_cap_exceeded" ||
-        d.code === "local_only_required" ||
-        d.code === "api_key_blocked_by_subscription_first_policy" ||
-        d.code === "provider_denied" ||
-        d.code === "subscription_scope_denied",
-    );
-
-    return {
-      protocolVersion: ROUTE_PROTOCOL_VERSION,
-      decisionId,
-      requestId: request.requestId,
-      route: null,
-      reason: profileHardBlock
-        ? "policy_blocked"
-        : onlyCapabilityOrCostOrApiKey
-          ? "no_allowed_candidate"
-          : "policy_blocked",
-      explanation:
-        policy.denials.map((d) => d.message).join(" ") ||
-        "No allowed candidate remaining after policy evaluation.",
-      fallbackChain: [],
-      policyDenials: policy.denials,
-      confidence: 1,
-      auditSummary: `Blocked profile=${request.harness.profile} denials=${policy.denials.length} digest=${request.task.promptDigest}`,
-      blocked: true,
-      needsConfiguration: !profileHardBlock && policy.denials.length === 0,
-    };
-  }
-
-  const sorted = sortCandidates(policy.allowed);
-  const winner = sorted[0]!;
-  const { reason, explanation, fallbackReason } = selectionReason(winner);
-
-  // If winner is api-key but there were subscription denials for exhausted etc
-  // keep explanation accurate.
-  let finalExplanation = explanation;
-  if (winner.authTier === "api-key") {
-    const subExhausted = candidates.some(
-      (c) =>
-        c.authTier === "subscription" &&
-        (c.subscriptionStatus === "exhausted" ||
-          c.subscriptionStatus === "rate-limited"),
-    );
-    if (subExhausted) {
-      finalExplanation = `Selected API-key candidate ${candidateId(winner)} after subscription capacity was exhausted or rate-limited.`;
-    }
-  }
-
-  // Prefer primary reason label for true cheapest api-key when no subscription involved
-  let finalReason = reason;
-  let finalFallback: FallbackReason = fallbackReason;
-  if (
-    winner.authTier === "api-key" &&
-    !candidates.some((c) => c.authTier === "subscription")
-  ) {
-    finalReason = "primary";
-    finalFallback = "primary";
-    finalExplanation = `Selected cheap allowed candidate ${candidateId(winner)} for low-risk task.`;
-  }
-
-  const fallbackChain = buildFallbackChain(sorted, winner);
-  // Fix primary entry reason if we rewrote fallback reason
-  if (fallbackChain[0]) {
-    fallbackChain[0] = { ...fallbackChain[0], reason: finalFallback };
-  }
-
-  // Compute near-limit warning
-  let nearLimitWarning: string | undefined;
-  if (
-    winner.authTier === "subscription" &&
-    winner.subscriptionStatus === "near-limit"
-  ) {
-    const hasHealthyAlt = sorted.some(
-      (c) =>
-        c !== winner &&
-        c.authTier === "subscription" &&
-        c.health === "healthy" &&
-        c.subscriptionStatus !== "near-limit",
-    );
-    if (!hasHealthyAlt) {
-      const acct = winner.accountId ?? winner.providerId;
-      const pct = winner.subscriptionQuotaPercentRemaining;
-      const pctText =
-        pct !== undefined ? ` (${Math.round(pct)}% remaining)` : "";
-      nearLimitWarning = `Your ${winner.providerId} subscription (${acct}) is near its limit${pctText}. Consider switching or adding another account.`;
-    }
-  }
-
-  if (nearLimitWarning) {
-    finalExplanation = `${finalExplanation} ${nearLimitWarning}`;
-  }
-
-  return {
-    protocolVersion: ROUTE_PROTOCOL_VERSION,
-    decisionId,
-    requestId: request.requestId,
-    route: {
-      provider: winner.providerId,
-      model: winner.modelId,
-      authTier: winner.authTier,
-      authScope: winner.authScope,
-      accountId: winner.accountId ?? winner.providerId,
-    },
-    reason: finalReason,
-    explanation: finalExplanation,
-    fallbackChain,
-    policyDenials: policy.denials,
-    confidence: confidenceFor(winner, policy.allowed.length),
-    auditSummary: `route=${winner.providerId}/${winner.modelId} tier=${winner.authTier} profile=${request.harness.profile} digest=${request.task.promptDigest}`,
-    blocked: false,
-    needsConfiguration: false,
-    nearLimitWarning,
-  };
-}
-
-/** @internal exported for focused testing */
-export { sortCandidates };

package/src/schemas.test.ts

@@ -1,291 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  AuthScopeSchema,
-  AuthTierSchema,
-  FallbackReasonSchema,
-  PolicyDenialSchema,
-  ProviderCandidateSchema,
-  ProviderHealthSchema,
-  RouteDecisionSchema,
-  RouteRequestSchema,
-  SelectedRouteSchema,
-  SubscriptionStatusSchema,
-} from "./schemas.js";
-import { ROUTE_PROTOCOL_VERSION } from "./protocol.js";
-
-describe("routing vocabulary schemas", () => {
-  it("accepts all AuthTier values", () => {
-    expect(AuthTierSchema.parse("subscription")).toBe("subscription");
-    expect(AuthTierSchema.parse("local")).toBe("local");
-    expect(AuthTierSchema.parse("api-key")).toBe("api-key");
-  });
-
-  it("accepts all AuthScope values", () => {
-    expect(AuthScopeSchema.parse("first-party")).toBe("first-party");
-    expect(AuthScopeSchema.parse("third-party")).toBe("third-party");
-    expect(AuthScopeSchema.parse("unknown")).toBe("unknown");
-  });
-
-  it("accepts all SubscriptionStatus values", () => {
-    for (const status of [
-      "active",
-      "near-limit",
-      "exhausted",
-      "rate-limited",
-      "expired",
-      "unconfigured",
-      "unknown",
-    ] as const) {
-      expect(SubscriptionStatusSchema.parse(status)).toBe(status);
-    }
-  });
-
-  it("accepts all ProviderHealth values", () => {
-    expect(ProviderHealthSchema.parse("healthy")).toBe("healthy");
-    expect(ProviderHealthSchema.parse("degraded")).toBe("degraded");
-    expect(ProviderHealthSchema.parse("dead")).toBe("dead");
-  });
-
-  it("accepts all FallbackReason values", () => {
-    for (const reason of [
-      "primary",
-      "subscription_exhausted",
-      "subscription_degraded",
-      "subscription_unconfigured",
-      "subscription_scope_denied",
-      "local_preferred",
-      "api_key_fallback",
-      "policy_denied",
-      "provider_error",
-    ] as const) {
-      expect(FallbackReasonSchema.parse(reason)).toBe(reason);
-    }
-  });
-});
-
-describe("routing schemas", () => {
-  it("accepts a minimal Claude personal route request", () => {
-    const request = RouteRequestSchema.parse({
-      protocolVersion: "offrouter.route.v1",
-      requestId: "req_1",
-      harness: { kind: "claude", profile: "claude-personal" },
-      task: {
-        promptPreview: "explain this repo",
-        promptDigest: "sha256:example",
-        kind: "explain",
-        risk: "low",
-      },
-      workspace: { cwd: "/tmp/project", trusted: true },
-      constraints: { maxCostUsd: 0.05, localOnly: false },
-    });
-
-    expect(request.harness.profile).toBe("claude-personal");
-    expect(request.protocolVersion).toBe(ROUTE_PROTOCOL_VERSION);
-    expect(request.task.promptPreview).toBe("explain this repo");
-    expect(request.task.promptDigest).toBe("sha256:example");
-  });
-
-  it("rejects a route request that carries raw prompt text", () => {
-    expect(() =>
-      RouteRequestSchema.parse({
-        protocolVersion: "offrouter.route.v1",
-        requestId: "req_2",
-        harness: { kind: "claude", profile: "claude-personal" },
-        task: {
-          prompt: "raw secret prompt",
-          promptPreview: "raw secret prompt",
-          promptDigest: "sha256:example",
-          kind: "explain",
-          risk: "low",
-        },
-        workspace: { cwd: "/tmp/project", trusted: true },
-        constraints: { maxCostUsd: 0.05, localOnly: false },
-      }),
-    ).toThrow();
-  });
-
-  it("rejects a route request that carries raw prompt text at the top level", () => {
-    expect(() =>
-      RouteRequestSchema.parse({
-        protocolVersion: "offrouter.route.v1",
-        requestId: "req_3",
-        harness: { kind: "claude", profile: "claude-personal" },
-        task: {
-          promptPreview: "explain this repo",
-          promptDigest: "sha256:example",
-          kind: "explain",
-          risk: "low",
-        },
-        workspace: { cwd: "/tmp/project", trusted: true },
-        constraints: { maxCostUsd: 0.05, localOnly: false },
-        prompt: "raw secret prompt",
-      }),
-    ).toThrow();
-  });
-
-  it("rejects raw prompt text in nested route request objects", () => {
-    const baseRequest = {
-      protocolVersion: "offrouter.route.v1",
-      requestId: "req_4",
-      harness: { kind: "claude", profile: "claude-personal" },
-      task: {
-        promptPreview: "explain this repo",
-        promptDigest: "sha256:example",
-        kind: "explain",
-        risk: "low",
-      },
-      workspace: { cwd: "/tmp/project", trusted: true },
-      constraints: { maxCostUsd: 0.05, localOnly: false },
-    };
-
-    for (const request of [
-      { ...baseRequest, harness: { ...baseRequest.harness, prompt: "raw" } },
-      { ...baseRequest, workspace: { ...baseRequest.workspace, prompt: "raw" } },
-      {
-        ...baseRequest,
-        constraints: { ...baseRequest.constraints, prompt: "raw" },
-      },
-    ]) {
-      expect(() => RouteRequestSchema.parse(request)).toThrow();
-    }
-  });
-
-  it("rejects a route decision without a reason", () => {
-    expect(() =>
-      RouteDecisionSchema.parse({
-        protocolVersion: "offrouter.route.v1",
-        decisionId: "dec_1",
-        requestId: "req_1",
-        route: { provider: "fake", model: "fast", authTier: "subscription" },
-        explanation: "Selected the healthy subscription-backed candidate.",
-      }),
-    ).toThrow();
-  });
-
-  it("rejects a route decision without an explanation", () => {
-    expect(() =>
-      RouteDecisionSchema.parse({
-        protocolVersion: "offrouter.route.v1",
-        decisionId: "dec_1",
-        requestId: "req_1",
-        route: { provider: "fake", model: "fast", authTier: "subscription" },
-        reason: "subscription_primary",
-      }),
-    ).toThrow();
-  });
-
-  it("accepts a route decision with explanation and reason", () => {
-    const decision = RouteDecisionSchema.parse({
-      protocolVersion: "offrouter.route.v1",
-      decisionId: "dec_1",
-      requestId: "req_1",
-      route: { provider: "fake", model: "fast", authTier: "subscription" },
-      reason: "subscription_primary",
-      explanation:
-        "Selected the healthy subscription-backed candidate over the API-key fallback.",
-      fallbackChain: [
-        {
-          provider: "fake",
-          model: "fast",
-          authTier: "subscription",
-          reason: "primary",
-        },
-      ],
-      policyDenials: [],
-      confidence: 0.9,
-    });
-
-    expect(decision.explanation).toContain("subscription-backed");
-    expect(decision.reason).toBe("subscription_primary");
-  });
-
-  it("accepts a provider candidate with subscription metadata", () => {
-    const candidate = ProviderCandidateSchema.parse({
-      providerId: "claude",
-      modelId: "sonnet",
-      authTier: "subscription",
-      authScope: "first-party",
-      subscriptionStatus: "active",
-      health: "healthy",
-      supportsTools: true,
-      supportsStreaming: true,
-      supportsJson: true,
-      supportsImages: false,
-    });
-
-    expect(candidate.authTier).toBe("subscription");
-    expect(candidate.authScope).toBe("first-party");
-  });
-
-  it("accepts a structured policy denial", () => {
-    const denial = PolicyDenialSchema.parse({
-      code: "api_key_blocked_by_subscription_first_policy",
-      target: "candidate",
-      id: "openrouter:fast",
-      message:
-        "API-key candidate blocked while healthy subscription capacity remains.",
-    });
-
-    expect(denial.code).toBe("api_key_blocked_by_subscription_first_policy");
-  });
-
-  it("rejects unknown policy denial codes", () => {
-    expect(() =>
-      PolicyDenialSchema.parse({
-        code: "not_a_real_code",
-        target: "profile",
-        id: "claude-work",
-        message: "nope",
-      }),
-    ).toThrow();
-  });
-
-  describe("multi-account schema fields", () => {
-    it("accepts ProviderCandidate with accountId and subscriptionQuotaPercentRemaining", () => {
-      const candidate = ProviderCandidateSchema.parse({
-        providerId: "anthropic",
-        modelId: "sonnet",
-        authTier: "subscription",
-        authScope: "first-party",
-        subscriptionStatus: "active",
-        accountId: "anthropic-1",
-        subscriptionQuotaPercentRemaining: 15,
-        health: "healthy",
-        supportsTools: true,
-        supportsStreaming: true,
-        supportsJson: true,
-        supportsImages: false,
-      });
-      expect(candidate.accountId).toBe("anthropic-1");
-      expect(candidate.subscriptionQuotaPercentRemaining).toBe(15);
-    });
-
-    it("accepts near-limit SubscriptionStatus", () => {
-      expect(SubscriptionStatusSchema.parse("near-limit")).toBe("near-limit");
-    });
-
-    it("accepts RouteDecision with nearLimitWarning", () => {
-      const decision = RouteDecisionSchema.parse({
-        protocolVersion: "offrouter.route.v1",
-        decisionId: "dec_nl",
-        requestId: "req_nl",
-        route: { provider: "anthropic", model: "sonnet", authTier: "subscription" },
-        reason: "subscription_primary",
-        explanation: "Selected near-limit subscription.",
-        nearLimitWarning:
-          "Your anthropic subscription (anthropic-1) is near its limit (15% remaining). Consider switching or adding another account.",
-      });
-      expect(decision.nearLimitWarning).toContain("near its limit");
-    });
-
-    it("accepts SelectedRoute with accountId", () => {
-      const route = {
-        provider: "anthropic",
-        model: "sonnet",
-        authTier: "subscription",
-        accountId: "anthropic-1",
-      };
-      expect(() => SelectedRouteSchema.parse(route)).not.toThrow();
-    });
-  });
-});