offrouter-core 0.0.0

package/src/policy.ts

@@ -0,0 +1,418 @@
+/**
+ * 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[];
+}
+
+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/protocol.ts

@@ -0,0 +1,7 @@
+/**
+ * OffRouter V1 route protocol constants.
+ * Wire vocabulary: docs/contracts/v1-routing-contract.md
+ */
+export const ROUTE_PROTOCOL_VERSION = "offrouter.route.v1" as const;
+
+export type RouteProtocolVersion = typeof ROUTE_PROTOCOL_VERSION;