maxpool 1.5.79 → 1.5.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.5.79",
+  "version": "1.5.80",
   "description": "Multi-account Claude Code proxy with adaptive, rate-aware load balancing across Claude accounts",
   "type": "module",
   "main": "src/index.js",

package/src/account-manager.js

@@ -111,6 +111,7 @@ const DEFAULT_SCHEDULER = {
   perAccountConcurrencyTarget: 3,  // D: soft per-account in-flight target; past it, capPenalty bites
   capPenaltyWeight: 10,            // steep penalty per unit of in-flight depth past D (throttle safety floor)
   paceCostWeight: 1.5,            // soft de-preference of accounts burning ahead of pace (was the ×6 term)
+  utilizationWeight: 3,           // RAW utilization cost — drives load balancing in the mid-range
   scarcityWeight: 6,              // legacy; superseded by paceCostWeight (kept so old configs don't error)
   // Reserve-account OVERFLOW model. A weekly-RESERVE account (util 0.85-0.95) used to
   // sit idle behind a healthy-only first pass; now it's eligible in the first pass but
@@ -140,22 +141,30 @@ const DEFAULT_SCHEDULER = {
   crossAccountThinkingMigration: true,
   // Cross-PROVIDER fallback policy for 'cc all' (profile=all), i.e. whether a session
   // may be served by a provider FAMILY other than its home (Claude ↔ GLM ↔ Kimi).
-  //   'never'         — (DEFAULT) a Claude session never spills onto a provider. NOTE:
-  //                     this governs the Claude→provider direction ONLY — it is NOT a
-  //                     same-family pin (a provider-origin session still reaches Claude).
-  //   'when-exhausted'— home family preferred; a Claude session falls back to GLM/Kimi
-  //                     only once all Claude accounts are unavailable, and a GLM session
-  //                     may fall to Kimi once GLM is exhausted.
-  //   'always'        — providers peer with Claude for a Claude/unknown session
-  //                     (load-balanced, not last-resort).
-  // DEFAULT is 'never' (2026-07-24): a Claude Code session stays on Anthropic. Routing
-  // Claude→GLM/Kimi proved unreliable (the coding legs 403/429 + ignore the model id),
-  // so cross-routing OUT of Claude is OFF by default; re-enable via the TUI routing
-  // cycle or config. This governs ONLY the Claude→provider direction.
-  // INVARIANT (all policies): a GLM/Kimi-origin session NEVER routes to an Anthropic
-  // account — Anthropic 400s on a non-`srvtoolu_` server_tool_use id; that direction
-  // is unfixable, not policy-tunable.
+  //
+  // SUPERSEDED by `routingMode` below — kept for backward-compat migration only. An
+  // old config carrying `crossProviderFallbackPolicy` but no `routingMode` is upgraded
+  // at boot: 'always' → 'balance', 'when-exhausted'/'never' → 'prefer-claude'. The
+  // per-provider `providers[<key>].claudeFallback` field still controls the same thing
+  // for its one provider under the legacy modes.
   crossProviderFallbackPolicy: 'never',
+  // ROUTING MODE — the single knob that governs how sessions are distributed across
+  // the account pool. Replaces the hidden per-session binding that made 'always' not
+  // actually balance. Reported 2026-08-10: with cross-provider 'always' set, 20
+  // long-lived sessions that happened to start on the same Anthropic account hammered
+  // it at 82% while two GLM accounts at 2%/9% sat idle — because 'always' only governed
+  // the FIRST request; after that the session was pinned to one account.
+  //
+  //   'balance'         — score EVERY request across the full pool. No session binding.
+  //                       Accounts drain evenly. The behaviour 'always' should always
+  //                       have been.
+  //   'prefer-claude'   — score every request, but Anthropic accounts outrank providers
+  //                       unless they are all loaded/exhausted.
+  //   'prefer-zai'      — GLM accounts preferred; Claude/Kimi fill overflow.
+  //   'prefer-kimi'     — Kimi preferred; Claude/GLM fill overflow.
+  //   'sticky'          — the old behaviour, made explicit. Sessions stay on the account
+  //                       they first land on until it goes hot, then rebalance.
+  routingMode: 'sticky',
   // The OTHER cross direction, independent of the policy above: may a provider-origin
   // (GLM/Kimi) session cross to the OTHER provider (GLM↔Kimi)? Default ON — both legs are
   // lenient and accept each other's ids, and it's the reliable direction the user wants
@@ -244,6 +253,20 @@ function parseResetHeader(value) {
 export class AccountManager {
   constructor(accounts, switchThreshold = 0.90, schedulerOptions = {}, dependencies = {}) {
     this.scheduler = { ...DEFAULT_SCHEDULER, ...schedulerOptions };
+    // Migrate the legacy single-value policy to the new mode if the caller (config)
+    // set `crossProviderFallbackPolicy` but not `routingMode`. The per-provider
+    // `providers[<key>].claudeFallback` still works under the prefer-* modes.
+    // IMPORTANT: when schedulerOptions is empty (no explicit crossProviderFallbackPolicy),
+    // the DEFAULT_SCHEDULER value 'never' triggers migration. But the old behaviour
+    // under 'never' WAS sticky pinning — so the default must map to 'sticky', not
+    // 'prefer-claude'. Only an EXPLICIT 'always' in the caller's config changes the mode.
+    if (!schedulerOptions.routingMode) {
+      const leg = schedulerOptions.crossProviderFallbackPolicy;
+      if (leg === 'always') this.scheduler.routingMode = 'balance';
+      else if (leg === 'when-exhausted') this.scheduler.routingMode = 'prefer-claude';
+      // 'never' or unset → sticky (the historical default: sessions pin to one account)
+      else this.scheduler.routingMode = 'sticky';
+    }
     this._refreshAccessToken = dependencies.refreshAccessToken || refreshAccessToken;
     this.accounts = accounts.map((acct, index) => ({
       index,
@@ -1230,7 +1253,29 @@ export class AccountManager {
    *  score loop), so a healthy bound account never ping-pongs. */
   _isBoundAccountHot(account) {
     return this._isSessionQuotaUnavailable(account)
-      || ['reserve', 'critical', 'exhausted'].includes(this._weeklyPaceState(account));
+      || ['reserve', 'critical', 'exhausted'].includes(this._weeklyPaceState(account))
+      // SESSION-window pressure counts too. _isSessionQuotaUnavailable only fires at
+      // switchThreshold (0.90), and the weekly bands don't see the 5h window at all —
+      // so an account at 82% of a 5h window was "not hot" and every bound session
+      // stayed on it while idle accounts sat at 2%. Measured 2026-08-10: Anthropic at
+      // Ses 82% / Wk 66% hammered flat-out beside two GLM accounts at 2% and 9%.
+      // Uses the SOFT band (0.65), not reserve (0.85): the point is to shed load while
+      // there is still headroom, not at the cliff edge. _shouldRebalanceBoundSession
+      // still requires a clearly-cheaper, strictly-healthier target, so a hot account
+      // with no better alternative keeps its sessions — this only opens the question.
+      || this._sessionWindowUsage(account) >= this.scheduler.weeklySoftThreshold;
+  }
+
+  /** Fraction of the SESSION (5h) window consumed, across both quota shapes.
+   *  Anthropic reports unified5h; a provider reports providerSes. Returns 0 when
+   *  unknown — an unreadable window must never make an account look hot. */
+  _sessionWindowUsage(account) {
+    const q = account?.quota;
+    if (!q) return 0;
+    const vals = [];
+    if (q.unified5h != null) vals.push(clamp01(q.unified5h));
+    if (q.providerSes != null) vals.push(clamp01(q.providerSes));
+    return vals.length ? Math.max(...vals) : 0;
   }
 
   /** Decide whether a bound session should leave its (hot) account THIS request.
@@ -1334,6 +1379,18 @@ export class AccountManager {
     // candidate loop lands on the least-loaded healthy account, spreading the move.
     if ((WEEKLY_TIER[this._weeklyRawState(bound)] ?? 0) >= WEEKLY_TIER.reserve) return true;
 
+    // Same absolute escape for the SESSION window. The tier test below compares WEEKLY
+    // tiers, so a bound account burning down its 5h window can never satisfy it while
+    // its weekly is merely soft — which is exactly how an account at Ses 82% kept every
+    // session while idle accounts sat at 2%. Requires a MATERIALLY cheaper target so
+    // this can't churn between two similarly-loaded accounts.
+    // No score margin here, for the reason the weekly escape documents directly above:
+    // boundScore*0.5 on an IDLE near-cap account sits below every candidate's minimum
+    // score, so the margin is unsatisfiable and pins the session to the account it is
+    // meant to relieve. The candidate loop has already kept only RAW-healthy targets,
+    // and preserving the last of a 5h window beats concurrency spread.
+    if (this._sessionWindowUsage(bound) >= this.scheduler.weeklyReserveThreshold) return true;
+
     // Otherwise the trigger was PACE-only on a RAW-healthy account — a fast-burner
     // that still has real absolute headroom (RAW soft but pace reserve/critical,
     // e.g. 79% used resetting in ~3.5d). Keep the conservative gate so it isn't
@@ -1531,7 +1588,15 @@ export class AccountManager {
         return preferred;
       }
     }
-    const bound = this._boundAccount(requestInfo.sessionKey, profile, excludedIndexes, requestInfo);
+    // Session binding only applies in 'sticky' mode. Every other mode scores each
+    // request independently — the whole point of 'balance' is that 20 sessions that
+    // happened to start on the same account do NOT keep hammering it while others
+    // idle. Warmup-pull still works under the non-sticky modes because it keys on
+    // `_isWarming`, not on a binding.
+    const isStickyMode = this.scheduler.routingMode === 'sticky';
+    const bound = isStickyMode
+      ? this._boundAccount(requestInfo.sessionKey, profile, excludedIndexes, requestInfo)
+      : null;
     if (bound) {
       // Warmup-pull: onboard a freshly-ADDED account (added mid-session, no reload)
       // by DIRECTLY re-homing this migration-safe session onto the warming account,
@@ -1787,18 +1852,52 @@ export class AccountManager {
   // (10/20) → fallback-only. A foreign session is provider-only regardless.
   _effectivePriority(account, requestInfo = {}) {
     const base = Number.isFinite(account.priority) ? account.priority : 0;
+    const mode = this.scheduler.routingMode;
+    const incompatible = this._effectiveIncompatible(requestInfo).incompatible;
+    // An incompatible session is pinned to its provider family — no mode overrides that.
+    if (incompatible) {
+      const isHome = account.type === 'provider'
+        && (mode === 'prefer-zai' ? account.provider === 'zai'
+          : mode === 'prefer-kimi' ? account.provider === 'kimi' : true);
+      return isHome ? 0 : base;
+    }
+    // Balance: every account peers at priority 0. Accounts are ranked by score alone.
+    if (mode === 'balance') return 0;
+    // Prefer-* modes: the preferred family sits at 0, everything else at its base
+    // priority (10 for GLM, 20 for Kimi). So the preferred family is chosen first and
+    // the others only when every preferred account is unavailable (the score loop's
+    // pass-1 admits reserve accounts, so a loaded preferred account DOES give way).
+    if (mode === 'prefer-claude') {
+      return account.type === 'provider' ? base : 0;
+    }
+    if (mode === 'prefer-zai') {
+      return account.provider === 'zai' ? 0 : base;
+    }
+    if (mode === 'prefer-kimi') {
+      return account.provider === 'kimi' ? 0 : base;
+    }
+    // Sticky: legacy behaviour — the 'always' policy promoted providers to 0.
     if (account.type === 'provider'
-        && this._claudeFallbackFor(account.provider) === 'always'
-        && !this._effectiveIncompatible(requestInfo).incompatible) {
+        && this._claudeFallbackFor(account.provider) === 'always') {
       return 0;
     }
     return base;
   }
 
+  setProviderRoutingMode(mode) {
+    if (!['balance', 'prefer-claude', 'prefer-zai', 'prefer-kimi', 'sticky'].includes(mode)) return false;
+    this.scheduler.routingMode = mode;
+    console.log(`[Maxpool] Routing mode set to "${mode}"`);
+    return true;
+  }
+
+  // Legacy shim — the TUI routing screen still cycles this. Maps to the new mode.
   setCrossProviderFallbackPolicy(policy) {
     if (!['never', 'when-exhausted', 'always'].includes(policy)) return false;
     this.scheduler.crossProviderFallbackPolicy = policy;
-    console.log(`[Maxpool] Cross-provider fallback policy set to "${policy}"`);
+    // Map to the new mode so the binding/priority logic agrees.
+    this.scheduler.routingMode = policy === 'always' ? 'balance' : policy === 'when-exhausted' ? 'prefer-claude' : 'sticky';
+    console.log(`[Maxpool] Cross-provider fallback policy set to "${policy}" (routing mode: ${this.scheduler.routingMode})`);
     return true;
   }
 
@@ -1872,15 +1971,20 @@ export class AccountManager {
 
     // Compatible session — includes Kimi and GLM-without-server-tools, whose regular
     // tool_use ids pass Anthropic's loose validation, AND ordinary Claude sessions.
-    // Claude is eligible + preferred (priority 0). Provider fallback is the SAFE
-    // direction (lenient providers accept Anthropic ids/signatures) and is
-    // policy-gated ONLY: 'never' keeps a Claude session on Claude; 'when-exhausted'
-    // lets providers serve as a priority-fallback; 'always' peers them
-    // (_effectivePriority). Signed thinking no longer bars providers here — but its
-    // live MIGRATION stays Claude-only (see the rebalance guard).
-    // PER-PROVIDER Claude→provider gate (GLM and Kimi steer independently). Unset ⇒
-    // inherits the legacy global policy, so behavior is unchanged on upgrade.
-    if (account.type === 'provider' && this._claudeFallbackFor(account.provider) === 'never') return false;
+    // Under the new routing modes, providers are eligible whenever the mode allows
+    // them to peer (balance + prefer-{zai,kimi}) or serve as fallback
+    // (prefer-claude + sticky). The legacy per-provider `claudeFallback: 'never'`
+    // gate only applies under 'sticky' — the old behaviour it was written for.
+    if (account.type === 'provider') {
+      const mode = this.scheduler.routingMode;
+      // Balance and prefer-{zai,kimi}: providers are always eligible (scored, not gated).
+      if (mode === 'balance' || mode === 'prefer-zai' || mode === 'prefer-kimi') return true;
+      // Prefer-claude: providers serve as overflow. Still eligible — priority handles the
+      // preference; an available Claude account always wins on priority.
+      if (mode === 'prefer-claude') return true;
+      // Sticky: the legacy per-provider gate applies — this is the mode it was written for.
+      if (this._claudeFallbackFor(account.provider) === 'never') return false;
+    }
     return true;
   }
 
@@ -2057,6 +2161,14 @@ export class AccountManager {
     // soft de-preference of accounts burning ahead of an even pace. Never a bench.
     const paceCost = this._accountScarcity(account, now) * this.scheduler.paceCostWeight;
 
+    // RAW utilization cost — direct, not pace-adjusted. The pace cost above discounts
+    // by how far into the window you are, so an account at 80% with 2h left is only
+    // "slightly ahead of pace" → tiny cost. That's right for avoiding premature
+    // benching, but wrong for load balancing: an account at 80% should be clearly less
+    // attractive than one at 10% even if both are "on pace". Measured 2026-08-10: cc at
+    // 80% scored 52.30 vs glm at 10% at 52.15 — a 0.15 gap drowned by round-robin.
+    const utilizationCost = this._rawUtilization(account) * this.scheduler.utilizationWeight;
+
     // Per-model weekly de-preference: an account whose scoped weekly for THIS
     // request's model (e.g. Fable) is high-but-not-exhausted is a poor pick for
     // that model — shed its load toward healthier accounts BEFORE the hard bench
@@ -2083,7 +2195,7 @@ export class AccountManager {
     // default) learns the real number within a cycle. `probing`/requalify still
     // flags a never-seen account for learning — that path is unchanged.
 
-    return concurrency + capPenalty + paceCost + scopedPace + spread + ramp + reserveCost + failurePenalty;
+    return concurrency + capPenalty + paceCost + utilizationCost + scopedPace + spread + ramp + reserveCost + failurePenalty;
   }
 
   /**
@@ -2137,6 +2249,29 @@ export class AccountManager {
     return scarcity;
   }
 
+  /** RAW utilization (0..1) — not pace-adjusted. Reads the same fields as
+   *  _accountScarcity but WITHOUT the elapsed-fraction discount. This is the signal
+   *  the load balancer needs: an account at 80% is more expensive than one at 10%,
+   *  full stop. */
+  _rawUtilization(account) {
+    const q = account?.quota;
+    if (!q) return 0;
+    // SESSION windows use raw utilization — headroom is consumed immediately and an
+    // 80%-used 5h window is genuinely more expensive than a 10%-used one right now.
+    let util = 0;
+    if (q.unified5h != null) util = Math.max(util, clamp01(q.unified5h));
+    if (q.providerSes != null) util = Math.max(util, clamp01(q.providerSes));
+    // WEEKLY windows use PACE-ADJUSTED utilization (via _windowScarcity), not raw —
+    // a 79% account resetting in 2h has plenty of headroom and should be cheap to
+    // spend (the use-it-or-lose-it principle). Using raw weekly would break that.
+    // The pace cost already carries this signal; here we add only the session signal
+    // the pace cost was too weak to express.
+    if (q.tokensLimit != null && q.tokensLimit > 0 && q.tokensRemaining != null) {
+      util = Math.max(util, 1 - q.tokensRemaining / q.tokensLimit);
+    }
+    return util;
+  }
+
   _windowScarcity(util, resetMs, windowLen, now = Date.now()) {
     const used = clamp01(util);
     if (!resetMs || resetMs <= now) return used; // unknown / just-reset → face value