maxpool 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "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

@@ -325,6 +325,20 @@ function parseResetHeader(value) {
   return Number.isNaN(asDate) ? null : asDate;
 }
 
+/**
+ * A capUtilization is valid only as a real number strictly inside (0,1). Everything
+ * else — strings, NaN, negative, 0, >=1 — means "no cap"; an invalid EXPLICIT value
+ * also logs once so a hand-edited config doesn't silently fail open (a NaN cap makes
+ * every `util >= cap` comparison false = uncapped, with no error anywhere).
+ */
+function _sanitizeCap(value, name) {
+  if (value == null) return null;
+  const n = Number(value);
+  if (Number.isFinite(n) && n > 0 && n < 1) return n;
+  console.log(`[Maxpool] Ignoring invalid capUtilization ${JSON.stringify(value)} for "${name}" — expected 0-1`);
+  return null;
+}
+
 export class AccountManager {
   constructor(accounts, switchThreshold = 0.90, schedulerOptions = {}, dependencies = {}) {
     this.scheduler = { ...DEFAULT_SCHEDULER, ...schedulerOptions };
@@ -354,6 +368,13 @@ export class AccountManager {
       authHeader: acct.authHeader || null,
       profiles: acct.profiles || (acct.type === 'provider' ? ['all'] : ['claude', 'all']),
       priority: Number.isFinite(acct.priority) ? acct.priority : 0,
+      // USAGE CAP (owner-directed 2026-08-26): reserve capacity on this account —
+      // the proxy benches it at capUtilization of BOTH the 5h and 7d windows, keeping
+      // the rest for out-of-band use. null/undefined = fully utilized (the default;
+      // no behavior change). SANITIZED at parse: non-finite/out-of-range values drop
+      // to null HERE, visibly (below), so a hand-edited "50" or "abc" in the config
+      // can never fail the >= comparisons open as NaN.
+      capUtilization: _sanitizeCap(acct.capUtilization, acct.name),
       model: acct.model || null,
       modelMap: acct.modelMap || null,
       stripBetaHeaders: Boolean(acct.stripBetaHeaders),
@@ -837,7 +858,7 @@ export class AccountManager {
     // headroom (e.g. 69% used, resets in days) must stay in the healthy-spread
     // pool even if it's burning fast. Pace is a soft SCORE cost, never a bench.
     const weeklyState = this._weeklyRawState(account);
-    if (weeklyState === 'exhausted') return false;
+    if (weeklyState === 'exhausted' || weeklyState === 'capped') return false;
     if (weeklyState === 'critical' && !options.allowWeeklyCritical) return false;
     if (weeklyState === 'reserve' && !options.allowWeeklyReserve) return false;
 
@@ -1266,28 +1287,47 @@ export class AccountManager {
     }
   }
 
+  /**
+   * The session-bench threshold for THIS account: the global switchThreshold, lowered
+   * to its usage cap when one is set. Shared by _isSessionQuotaUnavailable (the bench)
+   * and _shortTermRetry (the retry oracle) — one helper, both call sites, so the
+   * oracle can never desync from the bench (a capped-benched account MUST report a
+   * finite retry time or a live session holding on it gets error-fasted).
+   */
+  _sessionBenchThreshold(account) {
+    const cap = account?.capUtilization;
+    return (cap != null && cap < this.switchThreshold) ? cap : this.switchThreshold;
+  }
+
+  /** True when the account's usage cap has it benched on the given window reading. */
+  _capped(account, utilization) {
+    const cap = account?.capUtilization;
+    return cap != null && utilization != null && utilization >= cap;
+  }
+
   _isSessionQuotaUnavailable(account) {
     const q = account.quota;
     this._clearExpiredQuotas(account);
+    const bench = this._sessionBenchThreshold(account);
 
     // Unified 5h quota is immediate availability. Weekly quota is handled
     // separately as long-horizon admission control.
-    if (q.unified5h != null && q.unified5h >= this.switchThreshold) return true;
+    if (q.unified5h != null && q.unified5h >= bench) return true;
 
     // Standard quotas (API key accounts)
     if (q.tokensLimit != null && q.tokensRemaining != null) {
       const used = 1 - (q.tokensRemaining / q.tokensLimit);
-      if (used >= this.switchThreshold) return true;
+      if (used >= bench) return true;
     }
 
     if (q.requestsLimit != null && q.requestsRemaining != null) {
       const used = 1 - (q.requestsRemaining / q.requestsLimit);
-      if (used >= this.switchThreshold) return true;
+      if (used >= bench) return true;
     }
 
     // Provider (z.ai/Kimi) session quota — the 5h token window. Without this a
     // provider at 95% of its 5h cap reads as fully available.
-    if (q.providerSes != null && q.providerSes >= this.switchThreshold) return true;
+    if (q.providerSes != null && q.providerSes >= bench) return true;
 
     return false;
   }
@@ -1578,9 +1618,10 @@ export class AccountManager {
         queueable: true,
       };
     }
-    if (weeklyState === 'exhausted') {
+    if (weeklyState === 'exhausted' || weeklyState === 'capped') {
       // Hard block: only a weekly reset unblocks it — a sooner short-term clear
-      // does not help — so key the hold on the weekly reset.
+      // does not help — so key the hold on the weekly reset. 'capped' (usage cap)
+      // shares this arm: the cap's recovery time IS the window reset.
       //
       // Read the PROVIDER reset too. `unified7dReset` is an Anthropic-only field;
       // a GLM/Kimi account stores its weekly reset in `providerWkReset`
@@ -1672,6 +1713,11 @@ export class AccountManager {
   // queueable} the retry oracle can hold on. Kept separate from the weekly state
   // so weekly-critical accounts surface their real near-term recovery time.
   _shortTermRetry(account, now, q) {
+    // USAGE CAP: the oracle reads the SAME per-account bench threshold as
+    // _isSessionQuotaUnavailable (_sessionBenchThreshold) — a capped account benched
+    // at 50% MUST report a finite retryAt here or a live session holding on it gets
+    // error-fasted instead of waiting out the window (red-team blocker 2).
+    const bench = this._sessionBenchThreshold(account);
     if (account.status === 'throttled' && account.rateLimitedUntil && now < account.rateLimitedUntil) {
       return { cause: 'rate_limited', retryAt: account.rateLimitedUntil, queueable: true };
     }
@@ -1684,13 +1730,13 @@ export class AccountManager {
       return { cause: 'upstream_failure', retryAt: account.provisionalUpstreamUntil, queueable: true };
     }
 
-    if (q.unified5h != null && q.unified5h >= this.switchThreshold) {
+    if (q.unified5h != null && q.unified5h >= bench) {
       return { cause: 'session_limit', retryAt: q.unified5hReset || null, queueable: Boolean(q.unified5hReset) };
     }
 
     if (q.tokensLimit != null && q.tokensRemaining != null && q.tokensLimit > 0) {
       const used = 1 - q.tokensRemaining / q.tokensLimit;
-      if (used >= this.switchThreshold) {
+      if (used >= bench) {
         const retryAt = q.resetsAt ? new Date(q.resetsAt).getTime() : null;
         return { cause: 'token_limit', retryAt, queueable: Boolean(retryAt) };
       }
@@ -1698,7 +1744,7 @@ export class AccountManager {
 
     if (q.requestsLimit != null && q.requestsRemaining != null && q.requestsLimit > 0) {
       const used = 1 - q.requestsRemaining / q.requestsLimit;
-      if (used >= this.switchThreshold) {
+      if (used >= bench) {
         const retryAt = q.resetsAt ? new Date(q.resetsAt).getTime() : null;
         return { cause: 'request_limit', retryAt, queueable: Boolean(retryAt) };
       }
@@ -2819,7 +2865,7 @@ export class AccountManager {
 
   _weeklyState(account) {
     const rawState = this._weeklyRawState(account);
-    if (rawState === 'unknown' || rawState === 'exhausted') return rawState;
+    if (rawState === 'unknown' || rawState === 'exhausted' || rawState === 'capped') return rawState;
 
     const pressure = Math.max(clamp01(account.quota.unified7d ?? 0), this._effectiveWeeklyUsage(account));
     if (pressure >= this.scheduler.weeklyCriticalThreshold) return 'critical';
@@ -2858,6 +2904,11 @@ export class AccountManager {
       const sesUsed = q.providerSes != null ? clamp01(q.providerSes) : null;
       const wkUsed = q.providerWk != null ? clamp01(q.providerWk) : null;
       const used = Math.max(sesUsed ?? 0, wkUsed ?? 0);
+      // USAGE CAP — checked FIRST, before every tier: a reservation is owner intent
+      // and outranks both the tier ladder and the upstream verdict. There is no
+      // upstreamAllows carve-out for providers anyway, but the ordering documents
+      // that a cap can never be talked out of by the vendor's "allowed".
+      if (this._capped(account, used)) return 'capped';
       if (used >= this.scheduler.weeklyExhaustedThreshold) return 'exhausted';
       if (used >= this.scheduler.weeklyCriticalThreshold) return 'critical';
       if (used >= this.scheduler.weeklyReserveThreshold) return 'reserve';
@@ -2878,6 +2929,12 @@ export class AccountManager {
     // was waiting on, withheld because a threshold outranked the upstream's own answer.
     // 'exhausted' is the only state that removes an account from routing, so the override
     // is scoped to it — critical/reserve still apply their soft costs unchanged.
+    // USAGE CAP — before the upstreamAllows carve-out BY DESIGN (red-team blocker 1):
+    // a capped account is below its REAL limit, so upstream keeps saying "allowed"
+    // right through the cap — the override exists for genuine over-limit-but-allowed
+    // states and would otherwise make the cap a no-op on exactly the account it is
+    // for (measured: this exact shape sat at unified7d=1.00 'allowed_warning').
+    if (this._capped(account, used)) return 'capped';
     const upstreamAllows = typeof q.unifiedStatus === 'string' && q.unifiedStatus.startsWith('allowed');
     if (used >= this.scheduler.weeklyExhaustedThreshold && !upstreamAllows) return 'exhausted';
     if (used >= this.scheduler.weeklyCriticalThreshold) return 'critical';
@@ -3748,6 +3805,7 @@ export class AccountManager {
       runtime: Boolean(acctData.runtime),
       configSourced: Boolean(acctData.configSourced),
       secretName: acctData.secretName || null,
+      capUtilization: _sanitizeCap(acctData.capUtilization, acctData.name),
       enabled: acctData.enabled !== false,
       refreshToken: acctData.refreshToken || null,
       expiresAt: acctData.expiresAt || null,
@@ -3808,6 +3866,12 @@ export class AccountManager {
     // all` header path (prepareRuntimeProviders) omits enabled, so a re-sent token
     // NEVER silently re-enables a provider the user benched in the TUI.
     if (acctData.enabled !== undefined) account.enabled = acctData.enabled !== false;
+    // Same guard for the usage cap: the restore path carries an explicit persisted
+    // value; the `cc all` header path omits it, so a re-sent token never clears a
+    // cap the user set in the TUI.
+    if (acctData.capUtilization !== undefined) {
+      account.capUtilization = _sanitizeCap(acctData.capUtilization, account.name);
+    }
     if (account.status === 'error' && changed) {
       account.status = 'active';
       account.lastError = null;
@@ -3845,6 +3909,9 @@ export class AccountManager {
         // benched across a restart — without this an intentionally-disabled GLM/Kimi
         // silently comes back enabled on the next boot (restore defaults enabled:true).
         enabled: a.enabled,
+        // And the usage cap, same reasoning: a TUI-set reservation must survive both
+        // the restart AND the next `cc all` header re-send (the upsert guard).
+        capUtilization: a.capUtilization ?? null,
       }));
   }
 
@@ -4057,6 +4124,7 @@ export class AccountManager {
         upstream: a.upstream,
         profiles: a.profiles,
         priority: a.priority,
+        capUtilization: a.capUtilization ?? null,
         runtime: a.runtime,
         status: a.status,
         refreshDead: Boolean(a.refreshDead),

package/src/index.js

@@ -2099,6 +2099,14 @@ async function syncAccountsFromDisk(diskConfig, memConfig, accountManager) {
       accountManager.setAccountEnabled(mgr.index, enabled);
       console.log(`[Maxpool] ${enabled ? 'Enabled' : 'Disabled'} account "${mgr.name}" from config`);
     }
+    // Propagate a hand-edited usage cap the same way as enabled (red-team: without
+    // this a config-edit cap is stale until the next full reload).
+    const diskCap = Number.isFinite(diskAcct.capUtilization) && diskAcct.capUtilization > 0 && diskAcct.capUtilization < 1
+      ? diskAcct.capUtilization : null;
+    if (mgr.capUtilization !== diskCap) {
+      mgr.capUtilization = diskCap;
+      console.log(`[Maxpool] Usage cap for "${mgr.name}" ${diskCap ? `set to ${Math.round(diskCap * 100)}%` : 'removed'} from config`);
+    }
     memConfig.accounts[memIdx] = { ...memConfig.accounts[memIdx], ...diskAcct };
 
     if (freshCred.accessToken) {

package/src/tui.js

@@ -183,6 +183,12 @@ function loadText(load) {
 export function weeklyPolicyText(am, account) {
   if (!am?._weeklyState || !account || account.type === 'provider') return '';
   const state = am._weeklyState(account);
+  // USAGE CAP: the reservation outranks every tier label — a capped account is NOT
+  // exhausted, it's deliberately held, and labelling it "Wk exhausted 50%" (red team)
+  // while the bar shows half-full misstates the owner's own setting.
+  if (state === 'capped') {
+    return yellow(`Cap ${Math.round((account.capUtilization || 0) * 100)}%`);
+  }
   if (!state || state === 'unknown' || state === 'normal') return '';
   const rawState = am._weeklyRawState?.(account) || state;
   const used = Number(account.quota?.unified7d);
@@ -647,6 +653,11 @@ export class TUI {
       this._startSelection('rename');
     } else if (k === 't' && this.am.accounts.length > 0) {
       this._startSelection('toggle');
+    } else if (k === 'u' && this.am.accounts.length > 0) {
+      // USAGE CAP (owner-directed 2026-08-26): reserve capacity — the proxy benches
+      // this account at the chosen % of both the 5h and weekly windows, keeping the
+      // rest for personal use. Enter 1-99 to set; enter 0 to remove (fully utilized).
+      this._startSelection('cap');
     } else if (k === 'd' && this.am.accounts.length > 0) {
       this._startSelection('delete');
     } else if (k === 'esc' || k === 'q') {
@@ -1025,6 +1036,15 @@ export class TUI {
         this.inputBuf = '';
         this.inputSensitive = false;
         this.inputCb = value => this._doRename(targetIdx, String(value || '').trim());
+      } else if (this.selAction === 'cap') {
+        const targetIdx = this.selIdx;
+        const current = account.name;
+        const existing = this.am.accounts[targetIdx]?.capUtilization;
+        this.mode = 'input';
+        this.inputPrompt = `Usage cap % for "${current}" (1-99, 0 = off, now ${existing ? Math.round(existing * 100) + '%' : 'off'})`;
+        this.inputBuf = '';
+        this.inputSensitive = false;
+        this.inputCb = value => this._doSetCap(targetIdx, String(value || '').trim());
       }
     }
     else if (k === 'esc' || k === 'q') { this.mode = 'normal'; }
@@ -1196,6 +1216,49 @@ export class TUI {
   }
 
   // Rename an account in config and in the running manager.
+  /**
+   * USAGE CAP setter — persists to config (rollback on write failure) and applies
+   * live. `0` / `off` / `100` REMOVE the cap (fully utilized); 1-99 set it. Runtime
+   * providers (not in config) keep the cap in memory like their `enabled` flag —
+   * it rides state.json across restarts and must also survive `cc all` header
+   * re-upserts (the upsert guard in account-manager).
+   */
+  async _doSetCap(idx, raw) {
+    const account = this.am.accounts[idx];
+    if (!account) { this._addLog('Account no longer exists'); return; }
+    const v = String(raw || '').trim().toLowerCase();
+    const off = v === '' || v === '0' || v === 'off' || v === '100';
+    let pct = null;
+    if (!off) {
+      pct = parseInt(v, 10);
+      if (!Number.isInteger(pct) || pct < 1 || pct > 99) {
+        this._addLog(`Usage cap must be 1-99 (or 0 to remove) — got "${raw}"`);
+        return;
+      }
+    }
+    const cap = off ? null : pct / 100;
+
+    const loc = this._configLocation(account);
+    if (loc) {
+      const prev = this.config[loc.array][loc.index].capUtilization ?? null;
+      if (cap == null) delete this.config[loc.array][loc.index].capUtilization;
+      else this.config[loc.array][loc.index].capUtilization = cap;
+      try {
+        await this.saveConfig(this.config);
+      } catch (error) {
+        // rollback both config and (below) skip the live apply
+        if (prev == null) delete this.config[loc.array][loc.index].capUtilization;
+        else this.config[loc.array][loc.index].capUtilization = prev;
+        throw error;
+      }
+    }
+    // No loc: a runtime provider — in-memory + state.json persistence (same as enabled).
+    account.capUtilization = cap;
+    this._addLog(cap == null
+      ? `Usage cap removed for "${account.name}" — fully utilized`
+      : `Usage cap ${pct}% set for "${account.name}" — the proxy stops routing to it at ${pct}% of the 5h and weekly windows`);
+  }
+
   async _doRename(idx, newName) {
     const account = this.am.accounts[idx];
     if (!account) { this._addLog('Account no longer exists'); return; }
@@ -1968,6 +2031,7 @@ export class TUI {
         const m = this.am._fastRefillMultiplier(a);
         if (m < 1) note += `  ${cyan(`fast·refill ×${m.toFixed(2)}`)}`;
       }
+      if (a.capUtilization != null) note += `  ${yellow(`cap ${Math.round(a.capUtilization * 100)}%`)}`;
     } else if (q.providerQuotaSource === 'console-only') {
       sesCell = emptyBar('n/a', bw);
       wkCell = emptyBar('n/a', bw);
@@ -2066,7 +2130,7 @@ export class TUI {
       if (win === 'wk' && a.type === 'provider' && a.quota?.weeklyAbsent) {
         const sesTank = this.am.capacityTank?.(i, 'ses');
         const approx = sesTank && sesTank.n > 0
-          ? `≈${formatTokens(Math.round(sesTank.avg * (7 * 24) / 5))}` : '--';
+          ? formatTokens(Math.round(sesTank.avg * (7 * 24) / 5)) : '--';
         const cellsByName = { Current: cyan(approx), Prev: '--', Avg: '--', N: sesTank?.n ? String(sesTank.n) : '--' };
         out.push('  ' + name + ' ' + prov + ' '
           + COLS.map(c => cellsByName[c].padStart(CW)).join('')
@@ -2085,11 +2149,11 @@ export class TUI {
       // vendor says it is. `~` estimate-from-open-window, `≥` lower bound (joined late).
       let cur = '--';
       if (tank && !(tank.source === 'live' && unprovenLive)) {
-        cur = (tank.lowerBound ? '≥' : tank.source === 'live' ? '~' : '') + formatTokens(tank.avg);
+        cur = formatTokens(tank.avg);
       } else if (nowOpen?.tokensSoFar > 0 && util > 0) {
-        cur = '~' + formatTokens(Math.round(nowOpen.tokensSoFar / util));
+        cur = formatTokens(Math.round(nowOpen.tokensSoFar / util));
       }
-      const curPct = util != null && cur !== '--' ? dim(`${Math.round(util * 100)}%`) : '';
+      const curPct = util != null && cur !== '--' ? dim(`@${Math.round(util * 100)}%`) : '';
       const st = ledger.windowStats(a.name, win);
       const cellsByName = {
         Current: cur.padStart(CW - (curPct ? curPct.length + 1 : 0)),
@@ -2104,7 +2168,7 @@ export class TUI {
 
     out.push('');
     out.push(' ' + dim('Capacity = tokens ÷ how full the provider said the window was, at close.'));
-    out.push(' ' + dim('~ = running estimate · ≥ = at least (maxpool joined late) · ≈ = avg 5h × 33.6.'));
+    out.push(' ' + dim('Current @% = live window, % full now · no-weekly weekly = avg 5h × 33.6.'));
     return out;
   }