feat(combos): add random, least-used, and reset-window routing strategies

src/cli/combo.ts

@@ -14,7 +14,7 @@ const USAGE = `Usage:
   ocx combo [list] [--json]
   ocx combo show <id> [--json]
   ocx combo set <id> --targets <provider/model[:weight],...>
-      [--strategy <failover|round-robin>] [--sticky <1-100>]
+      [--strategy <failover|round-robin|random|least-used|reset-window>] [--sticky <1-100>]
       [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
       [--native-alias] [--display-name <label|->]
       [--rename-from <id>] [--json]
@@ -73,7 +73,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const targetsRaw = takeOption(args, "--targets");
   if (!targetsRaw) throw new CliUsageError("--targets is required", USAGE);
   const strategy = takeOption(args, "--strategy") ?? "failover";
-  if (strategy !== "failover" && strategy !== "round-robin") throw new CliUsageError("--strategy must be failover or round-robin", USAGE);
+  if (strategy !== "failover" && strategy !== "round-robin" && strategy !== "random" && strategy !== "least-used" && strategy !== "reset-window") throw new CliUsageError("--strategy must be failover, round-robin, random, least-used, or reset-window", USAGE);
   const stickyLimit = takeIntegerOption(args, "--sticky", { min: 1 }) ?? 1;
   if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
   const effort = takeOption(args, "--effort");
@@ -84,9 +84,9 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   rejectArgs(args, USAGE);
   const combo: Record<string, unknown> = {
     strategy,
-    stickyLimit,
     targets: parseTargets(targetsRaw),
   };
+  if (strategy === "round-robin") combo.stickyLimit = stickyLimit;
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
   if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
   if (nativeAlias) combo.nativeAlias = true;

src/cli/help.ts

@@ -52,7 +52,7 @@ Usage:
   ocx provider <sub>          Providers, connectivity, quota, and selected models
   ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
   ocx models <sub>            Live/custom models, visibility, context, and shadow calls
-  ocx combo <sub>             Combo failover/round-robin routing
+  ocx combo <sub>             Combo routing strategies and failover
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx route <sub>             Routing features (combo, policy)

src/cli/registry.ts

@@ -189,7 +189,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "combo",
     usage: "ocx combo <list|show|set|remove> ...",
-    summary: "Manage combo failover and round-robin virtual models.",
+    summary: "Manage combo virtual models and routing strategies.",
     details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
   },
   {

src/combos/index.ts

@@ -43,3 +43,4 @@ export {
   concreteComboRequestBody,
   resetComboEffortWarningStateForTests,
 } from "./request";
+export { earliestQuotaResetAt, quotaResetRemainingMs } from "./reset-window";

src/combos/reset-window.ts

@@ -0,0 +1,43 @@
+import type { ProviderQuota } from "../providers/quota";
+
+function collectResetCandidates(quota: ProviderQuota): number[] {
+  const candidates: number[] = [];
+  if (typeof quota.fiveHourResetAt === "number") candidates.push(quota.fiveHourResetAt);
+  if (typeof quota.weeklyResetAt === "number") candidates.push(quota.weeklyResetAt);
+  if (typeof quota.monthlyResetAt === "number") candidates.push(quota.monthlyResetAt);
+  if (quota.customWindows) {
+    for (const w of quota.customWindows) {
+      if (typeof w.resetAt === "number") candidates.push(w.resetAt);
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Earliest future reset timestamp from a cached provider quota snapshot,
+ * or null when no fresh quota data exists or all resets have elapsed.
+ */
+export function earliestQuotaResetAt(
+  quota: ProviderQuota | null,
+  now: number,
+): number | null {
+  if (!quota) return null;
+  const future = collectResetCandidates(quota).filter(ts => ts > now);
+  if (future.length > 0) return Math.min(...future);
+  return null;
+}
+
+/**
+ * Milliseconds until the soonest known quota-window reset.
+ * Returns Infinity when no quota data exists, quota is stale, or all known
+ * reset timestamps have elapsed. An elapsed reset is stale evidence — it
+ * does not prove the next request has fresh capacity.
+ */
+export function quotaResetRemainingMs(
+  quota: ProviderQuota | null,
+  now: number,
+): number {
+  const nearest = earliestQuotaResetAt(quota, now);
+  if (nearest === null) return Number.POSITIVE_INFINITY;
+  return nearest - now;
+}

src/combos/resolve.ts

@@ -1,5 +1,7 @@
 import type { OcxComboTarget, OcxConfig } from "../types";
+import { getCachedProviderQuota } from "../providers/quota-routing-cache";
 import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import { quotaResetRemainingMs } from "./reset-window";
 import { getCombo, resolveComboId, targetKey } from "./types";
 import type { NormalizedComboConfig } from "./types";
 import {
@@ -19,6 +21,7 @@ interface SelectionState {
   activeKey?: string;
   successes: number;
   currentWeights: Map<string, number>;
+  successfulUses: Map<string, number>;
 }
 
 const selectionState = new Map<string, SelectionState>();
@@ -82,6 +85,36 @@ function smoothWeightedIndex(
   return best;
 }
 
+/**
+ * Select the eligible target whose earliest known quota reset is nearest.
+ *
+ * Only reads the last successfully cached provider-quota snapshot; it never
+ * triggers an upstream quota probe. When no target has fresh reset data,
+ * every remaining value is Infinity and configured order becomes the
+ * fallback. Targets with elapsed or stale reset timestamps are treated as
+ * unknown (Infinity).
+ */
+function resetWindowIndex(
+  targets: Required<OcxComboTarget>[],
+  eligible: (target: Required<OcxComboTarget>) => boolean,
+  now = Date.now(),
+): number {
+  let selected = -1;
+  let smallestRemaining = Number.POSITIVE_INFINITY;
+  for (let index = 0; index < targets.length; index++) {
+    const target = targets[index]!;
+    if (!eligible(target)) continue;
+    const remaining = quotaResetRemainingMs(getCachedProviderQuota(target.provider, now), now);
+    // Strict comparison deliberately retains configured order for ties,
+    // including the no-snapshot fallback where every value is Infinity.
+    if (selected < 0 || remaining < smallestRemaining) {
+      selected = index;
+      smallestRemaining = remaining;
+    }
+  }
+  return selected;
+}
+
 export function pickComboTarget(
   config: OcxConfig,
   comboId: string,
@@ -103,7 +136,7 @@ export function pickComboTarget(
   if (combo.strategy === "round-robin") {
     let state = selectionState.get(comboId);
     if (!state) {
-      state = { successes: 0, currentWeights: new Map() };
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
       selectionState.set(comboId, state);
     }
     if (state.activeKey) {
@@ -120,6 +153,41 @@ export function pickComboTarget(
         state.successes = 0;
       }
     }
+  } else if (combo.strategy === "random") {
+    // Weighted random selection happens independently for every request.
+    const eligibleTargets = combo.targets
+      .map((target, index) => ({ target, index }))
+      .filter(({ target }) => eligible(target));
+    if (eligibleTargets.length > 0) {
+      const totalWeight = eligibleTargets.reduce((sum, entry) => sum + entry.target.weight, 0);
+      let random = Math.random() * totalWeight;
+      for (const entry of eligibleTargets) {
+        random -= entry.target.weight;
+        if (random <= 0) {
+          targetIndex = entry.index;
+          break;
+        }
+      }
+      if (targetIndex < 0) targetIndex = eligibleTargets[eligibleTargets.length - 1]!.index;
+    }
+  } else if (combo.strategy === "least-used") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
+      selectionState.set(comboId, state);
+    }
+    let fewestUses = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < combo.targets.length; index++) {
+      const target = combo.targets[index]!;
+      if (!eligible(target)) continue;
+      const uses = state.successfulUses.get(targetKey(target)) ?? 0;
+      if (targetIndex < 0 || uses < fewestUses) {
+        targetIndex = index;
+        fewestUses = uses;
+      }
+    }
+  } else if (combo.strategy === "reset-window") {
+    targetIndex = resetWindowIndex(combo.targets, eligible);
   } else {
     targetIndex = combo.targets.findIndex(eligible);
   }
@@ -141,9 +209,18 @@ export function noteComboSuccess(
   target: Required<OcxComboTarget>,
   writerGeneration = captureConfigGeneration(),
 ): void {
-  if (combo.strategy !== "round-robin") return;
   const key = targetKey(target);
   if (!mayCommitComboState(comboId, key, writerGeneration)) return;
+  if (combo.strategy === "least-used") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map(), successfulUses: new Map() };
+      selectionState.set(comboId, state);
+    }
+    state.successfulUses.set(key, (state.successfulUses.get(key) ?? 0) + 1);
+    return;
+  }
+  if (combo.strategy !== "round-robin") return;
   const state = selectionState.get(comboId);
   if (!state || state.activeKey !== key) return;
   state.successes += 1;
@@ -206,6 +283,11 @@ export function reconcileComboRotationState(context: GenerationContext): number
       state.currentWeights.delete(key);
       removed += 1;
     }
+    for (const key of state.successfulUses.keys()) {
+      if (context.comboTargets.has(comboTargetOwnerKey(comboId, key))) continue;
+      state.successfulUses.delete(key);
+      removed += 1;
+    }
   }
   liveComboTargets = new Set(context.comboTargets);
   lastReconciledGeneration = context.generation;

src/combos/types.ts

@@ -205,8 +205,11 @@ export function comboConfigIssues(
   const body = raw as Record<string, unknown>;
   if (body.strategy !== undefined
     && body.strategy !== "failover"
-    && body.strategy !== "round-robin") {
-    issues.push({ path: ["strategy"], message: 'strategy must be "failover" or "round-robin"' });
+    && body.strategy !== "round-robin"
+    && body.strategy !== "random"
+    && body.strategy !== "least-used"
+    && body.strategy !== "reset-window") {
+    issues.push({ path: ["strategy"], message: 'strategy must be "failover", "round-robin", "random", "least-used", or "reset-window"' });
   }
   if (body.stickyLimit !== undefined
     && (typeof body.stickyLimit !== "number" || !Number.isInteger(body.stickyLimit)

src/providers/quota-routing-cache.ts

@@ -0,0 +1,32 @@
+import type { ProviderQuota, ProviderQuotaReport } from "./quota";
+
+const quotaCache = new Map<string, ProviderQuota>();
+
+export function clearCachedProviderQuotas(): void {
+  quotaCache.clear();
+}
+
+export function replaceCachedProviderQuotas(reports: ProviderQuotaReport[]): void {
+  quotaCache.clear();
+  for (const report of reports) {
+    quotaCache.set(report.provider, report.quota);
+  }
+}
+
+export function getCachedProviderQuota(
+  provider: string,
+  now: number,
+  maxAgeMs = 30 * 60_000,
+): ProviderQuota | null {
+  const quota = quotaCache.get(provider);
+  if (!quota) return null;
+  if (now - quota.updatedAt > maxAgeMs) return null;
+  return quota;
+}
+
+export function setCachedProviderQuotaForTests(
+  provider: string,
+  quota: ProviderQuota,
+): void {
+  quotaCache.set(provider, quota);
+}

src/providers/quota.ts

@@ -22,6 +22,10 @@ import {
   type GenerationContext,
 } from "../lib/state-store-sweeper";
 import { readBoundedResponseBody } from "../lib/bounded-body";
+import {
+  clearCachedProviderQuotas,
+  replaceCachedProviderQuotas,
+} from "./quota-routing-cache";
 import {
   aggregateCodexPoolCapacity,
   CODEX_CAPACITY_MAX_QUOTA_AGE_MS,
@@ -123,6 +127,7 @@ let invalidationEpoch = 0;
 /** Invalidate the report cache (e.g. after switching a provider's active account). */
 export function clearProviderQuotaCache(): void {
   cache = null;
+  clearCachedProviderQuotas();
   invalidationEpoch += 1;
 }
 
@@ -1446,6 +1451,7 @@ export function reconcileProviderAccountQuotaRows(context: GenerationContext): n
     const reports = cache.response.reports.filter(report => context.providerNames.has(report.provider));
     removed += cache.response.reports.length - reports.length;
     cache = { ...cache, response: { ...cache.response, reports } };
+    replaceCachedProviderQuotas(reports);
   }
   liveAccountQuotaKeys = new Set(context.oauthAccountKeys);
   liveProviderQuotaKeys = new Set(context.providerNames);
@@ -2283,6 +2289,7 @@ export async function fetchProviderQuotaReports(config: OcxConfig, forceRefresh
     ) {
       const reports = response.reports.filter(item => mayCommitProviderQuotaKey(item.provider, writerGeneration));
       cache = { key, ts: Date.now(), response: { ...response, reports } };
+      replaceCachedProviderQuotas(reports);
     }
     return response;
   })();

src/router.ts

@@ -482,7 +482,7 @@ export function comboRouteDecisionTrace(
       reason: "combo-pick",
       candidateIndex: pick.targetIndex,
       ...(combo
-        ? { tieBreak: combo.strategy === "round-robin" ? "round-robin" : "failover" }
+        ? { tieBreak: combo.strategy }
         : {}),
     },
     candidates: combo ? comboRouteCandidates(config, pick, combo) : undefined,
@@ -725,7 +725,7 @@ export function routeModel(
       reason: route.routeReason,
       ...(route.combo ? { candidateIndex: route.combo.targetIndex } : {}),
       ...(combo
-        ? { tieBreak: combo.strategy === "round-robin" ? "round-robin" : "failover" }
+        ? { tieBreak: combo.strategy }
         : {}),
     },
     candidates: route.routeKind === "combo" && route.combo && combo

src/types/config.ts

@@ -587,7 +587,7 @@ export interface OcxConfig {
 
 export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
 
-export type OcxComboStrategy = "failover" | "round-robin";
+export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
 
 export interface OcxComboTarget {
@@ -599,7 +599,7 @@ export interface OcxComboTarget {
 
 export interface OcxComboConfig {
   targets: OcxComboTarget[];
-  /** Ordered failover (default) or deterministic smooth weighted round-robin. */
+  /** Ordered failover (default), round-robin, weighted random, least-used, or quota reset-window selection. */
   strategy?: OcxComboStrategy;
   /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
   stickyLimit?: number;