maxpool 1.8.9 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.8.9",
+  "version": "1.10.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

@@ -1,6 +1,10 @@
 import { refreshAccessToken, isTokenExpiringSoon, modelFamily, tokenFingerprint } from './oauth.js';
 import { CapacityLedger } from './capacity-ledger.js';
 
+// Nominal window length per kind — mirrors capacity-ledger's WINDOW_MS (kept here as a
+// local table so account-manager does not import a private constant).
+const WINDOW_MS_BY_KIND = { ses: 5 * 3600_000, wk: 7 * 86400_000 };
+
 // A capacity window boundary must move by at least this much to count as a real
 // window ADVANCE rather than reset-stamp jitter (see noteCapacityWindowAdvance).
 const WINDOW_ADVANCE_EPSILON_MS = 60_000;
@@ -2699,12 +2703,14 @@ export class AccountManager {
       if (usage.sevenDay.utilization != null) q.unified7d = clamp01(usage.sevenDay.utilization);
       if (usage.sevenDay.resetAt != null) q.unified7dReset = usage.sevenDay.resetAt;
     }
-    // Stamp-advance close (same guard as the provider path): a FRESHER stamp means
-    // the old window rolled over — close its cycle at the old boundary.
-    // noteCapacityWindowAdvance already no-ops on a missing/unchanged/older stamp, so
-    // there is nothing to gate here — pass the raw (possibly undefined) value through.
     this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.fiveHour?.resetAt);
     this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.sevenDay?.resetAt);
+    // Utilization readings feed the capacity ESTIMATE. The probe path passes per-window
+    // marks so the DELTA method can difference consecutive readings.
+    this.capacity.noteUtilizationObserved(Date.now(), [
+      { name: account.name, window: 'ses', utilization: usage.fiveHour?.utilization },
+      { name: account.name, window: 'wk', utilization: usage.sevenDay?.utilization },
+    ]);
     // Only a SUCCESSFUL probe carrying the flag speaks to this. A header-driven update
     // can't see the limits[] array, and a FAILED read knows nothing about the account's
     // caps — either one claiming "uncapped" would mislabel a capped account as having no
@@ -2847,12 +2853,12 @@ export class AccountManager {
       q.weeklyAbsent = true;
     }
     q.lastProbeOkAt = Date.now();
-    // Stamp-advance close: a FRESHER reset stamp means the old window rolled over —
-    // the tokens accrued since the last close belong to the cycle that just ended.
-    // noteCapacityWindowAdvance already no-ops on a missing/unchanged/older stamp
-    // (same-window re-report, clock-skew backward re-report) — pass values through.
     this.noteCapacityWindowAdvance(account.name, 'ses', prevSesReset, usage.ses?.resetAt);
     this.noteCapacityWindowAdvance(account.name, 'wk', prevWkReset, usage.wk?.resetAt);
+    this.capacity.noteUtilizationObserved(Date.now(), [
+      { name: account.name, window: 'ses', utilization: usage.ses?.utilization },
+      { name: account.name, window: 'wk', utilization: usage.wk?.utilization },
+    ]);
   }
 
   /**
@@ -2879,6 +2885,17 @@ export class AccountManager {
     const account = this.accounts[accountIndex];
     if (!account) return;
 
+    // Utilization from RESPONSE HEADERS (every request) feeds the capacity estimate's
+    // delta marks too — header-driven moves arrive far more often than probe cycles.
+    const hdrU5 = parseFloat(headers['anthropic-ratelimit-unified-5h-utilization']);
+    const hdrU7 = parseFloat(headers['anthropic-ratelimit-unified-7d-utilization']);
+    if (!isNaN(hdrU5) || !isNaN(hdrU7)) {
+      this.capacity.noteUtilizationObserved(Date.now(), [
+        { name: account.name, window: 'ses', utilization: isNaN(hdrU5) ? undefined : clamp01(hdrU5) },
+        { name: account.name, window: 'wk', utilization: isNaN(hdrU7) ? undefined : clamp01(hdrU7) },
+      ]);
+    }
+
     // Unified rate limits (Claude Max)
     const u5h = parseFloat(headers['anthropic-ratelimit-unified-5h-utilization']);
     const u7d = parseFloat(headers['anthropic-ratelimit-unified-7d-utilization']);
@@ -3018,6 +3035,19 @@ export class AccountManager {
 
   /** Accrue ONE request's tokens into the capacity ledger (per-request values; the
    *  server seam has already applied max-semantics for streamed output). */
+  /** The capacity ESTIMATE for an account+window, from live utilization. Falls back
+   *  to null when the vendor reports no utilization for that window (the no-weekly GLM
+   *  plans), the account has not accrued, or it is already throttled. */
+  capacityEstimate(accountIndex, window) {
+    const a = this.accounts[accountIndex];
+    if (!a) return null;
+    const q = a.quota || {};
+    const util = window === 'wk'
+      ? (a.type === 'provider' ? q.providerWk : q.unified7d)
+      : (a.type === 'provider' ? q.providerSes : q.unified5h);
+    return this.capacity.estimateFromUtilization(a.name, window, util) || null;
+  }
+
   accrueCapacity(accountIndex, { input = 0, output = 0 } = {}) {
     const account = this.accounts[accountIndex];
     if (!account) return;
@@ -3034,6 +3064,16 @@ export class AccountManager {
       const pairs = a.type === 'provider'
         ? [['ses', 'providerSesReset'], ['wk', 'providerWkReset']]
         : [['ses', 'unified5hReset'], ['wk', 'unified7dReset']];
+      // Keep the open cycle's windowStartedAt fresh: a NEW reset stamp whose window
+      // start precedes the cycle's open means we joined mid-window (the absolute
+      // estimate is then only a lower bound — see the delta method).
+      for (const [win, stampKey] of pairs) {
+        const resetAt = q[stampKey];
+        const open = this.capacity.openCycle(a.name, win);
+        if (resetAt && open && open.startedAt > resetAt - WINDOW_MS_BY_KIND[win]) {
+          open.windowStartedAt = resetAt - WINDOW_MS_BY_KIND[win];
+        }
+      }
       for (const [win, stampKey] of pairs) {
         const resetAt = q[stampKey];
         // Close ONLY. This path deliberately does NOT null the stamp: the rollover

package/src/capacity-ledger.js

@@ -53,6 +53,7 @@ export class CapacityLedger {
     // True only for a ledger restored with no usable history — see fromSerialized.
     // Cleared per account+window once that window's first boundary is behind us.
     this._joinedMidWindow = false;
+    this._utilObservedAt = 0;   // last utilization-reading arrival (see estimateFromUtilization)
   }
 
   /** Restore from a serialized payload (state.json). Tolerant: unknown schemaVersion →
@@ -231,6 +232,91 @@ export class CapacityLedger {
     return rec[window].closed[rec[window].closed.length - 1];
   }
 
+  /**
+   * ESTIMATED window capacity from live utilization: tokens observed in the OPEN
+   * cycle ÷ the vendor's own fullness fraction (0..1). A window at 96% holding 812k
+   * tokens implies a ~846k tank — no completed cycle needed. This is the same math the
+   * user does in their head ("if 10% took A tokens, 100% is A×10") and it makes the
+   * page useful from minute one, while completed cycles remain the precise column.
+   *
+   * Returns { tokens, utilization, fresh } or null when no estimate exists.
+   *   null cases — utilization 0/unknown (0÷0), no accrual yet, or util ≥ 1 (the
+   *   account is throttled; the fraction says nothing about the tank size).
+   * `fresh` = the utilization reading and the accrual are from the same window
+   * (utilization refreshes on probe/header; the open cycle closes at the boundary —
+   * a stale util from the PREVIOUS window silently understates the estimate).
+   */
+  estimateFromUtilization(name, window, utilization) {
+    if (!(utilization > 0) || !(utilization < 1)) return null;
+    const open = this.openCycle(name, window);
+    if (!open || !(open.tokensSoFar > 0)) return null;
+
+    // DELTA METHOD (preferred). The absolute form (tokens ÷ utilization) silently
+    // assumes we watched the WHOLE window — false whenever the ledger joined late (a
+    // restart, a migration, a new account). Measured 2026-08-24: all four weekly
+    // estimates joined 8.9-95h into their window, so every one understated the tank,
+    // max@dubner.io by ~2x.
+    //
+    // Between two readings the tank is invariant, so pre-join usage cancels:
+    //     tank = (tokens observed between them) / (u2 - u1)
+    // No assumption about what happened before we started counting. Requires a rising
+    // utilization AND tokens accrued across the same span; falls back to absolute when
+    // we genuinely did watch from the start.
+    const mark = this._utilMarks?.get(`${name}:${window}`);
+    if (mark && utilization > mark.utilization) {
+      const deltaTokens = open.tokensSoFar - mark.tokensSoFar;
+      const deltaUtil = utilization - mark.utilization;
+      // A meaningful denominator only: a 0.5pp move on a coarse-rounded percentage
+      // (vendors report whole percents) turns rounding noise into a 200x multiplier.
+      if (deltaTokens > 0 && deltaUtil >= 0.02) {
+        return {
+          tokens: Math.round(deltaTokens / deltaUtil),
+          utilization, fresh: true, method: 'delta',
+          basis: { deltaTokens, deltaUtil },
+        };
+      }
+    }
+    // Fresh = we can prove the reading and the accrual describe the SAME window: the
+    // reading arrived after the open cycle began. A reading that predates the cycle (or
+    // was never noted at all) describes the previous window — mark it and let the UI
+    // caveat it, never silently trust it.
+    const fresh = this._utilObservedAt > 0 && open.startedAt != null && this._utilObservedAt >= open.startedAt;
+    // ABSOLUTE fallback. Only a LOWER BOUND unless we observed the window from its very
+    // start — flagged so the UI can say "≥" rather than present a floor as the answer.
+    const wholeWindow = open.startedAt != null && open.windowStartedAt != null
+      && open.startedAt <= open.windowStartedAt + 60_000;
+    return {
+      tokens: Math.round(open.tokensSoFar / utilization),
+      utilization, fresh, method: 'absolute', lowerBound: !wholeWindow,
+    };
+  }
+
+  /** Record when a utilization reading arrived, so estimateFromUtilization can tell
+   *  same-window freshness from a stale previous-window reading. */
+  noteUtilizationObserved(at = this._now(), marks = null) {
+    this._utilObservedAt = at;
+    // Snapshot (utilization, tokensSoFar) per account+window so the NEXT reading can be
+    // differenced against it. `marks` is [{name, window, utilization}] from the caller,
+    // which owns the per-account-type quota fields.
+    if (!marks) return;
+    this._utilMarks = this._utilMarks || new Map();
+    for (const m of marks) {
+      if (!(m.utilization >= 0) || !(m.utilization < 1)) continue;
+      const open = this.openCycle(m.name, m.window);
+      if (!open) continue;
+      const key = `${m.name}:${m.window}`;
+      const prev = this._utilMarks.get(key);
+      // Keep the OLDEST usable mark within this cycle: a wider span means a larger
+      // denominator and less rounding sensitivity. Reset when the cycle rolls.
+      if (!prev || prev.cycleStartedAt !== open.startedAt || m.utilization < prev.utilization) {
+        this._utilMarks.set(key, {
+          utilization: m.utilization, tokensSoFar: open.tokensSoFar,
+          cycleStartedAt: open.startedAt, at,
+        });
+      }
+    }
+  }
+
   // ── Queries ─────────────────────────────────────────────────────────────────
 
   /** The columns the TUI renders: last, prev, prev1, avg3, avg10, allTime — over

package/src/tui.js

@@ -2056,7 +2056,25 @@ export class TUI {
       }
       const st = ledger.windowStats(a.name, win);
       if (!st) {
-        out.push('  ' + name + ' ' + prov + ' ' + dim('no completed cycle yet'));
+        // No completed cycle yet — but the vendor's own fullness reading still yields
+        // an ESTIMATE (tokens seen ÷ utilization): useful from minute one, honest about
+        // being an estimate. `~` marks it; a measured column replaces it after the first
+        // full window. A stale-util caveat only when we cannot prove same-window.
+        const est = this.am.capacityEstimate?.(i, win);
+        if (est) {
+          anyData = true;
+          const caveat = est.fresh ? '' : ' (utilization reading may be from the previous window)';
+          // ≥ = absolute method on a window we joined late: the true tank is at least
+          // this. No ≥ when the delta method fired — it is join-independent, or the
+          // window was observed from its start.
+          const op = est.lowerBound ? '≥' : '~';
+          const via = est.method === 'delta'
+            ? `Δ ${(est.utilization * 100).toFixed(0)}% full` : `${(est.utilization * 100).toFixed(0)}% full`;
+          out.push('  ' + name + ' ' + prov + ' ' + cyan(op + formatTokens(est.tokens).padStart(CW - 1))
+            + dim(` est from ${via}${caveat} — measured after this window completes`));
+        } else {
+          out.push('  ' + name + ' ' + prov + ' ' + dim('no completed cycle yet'));
+        }
         continue;
       }
       anyData = true;
@@ -2075,6 +2093,7 @@ export class TUI {
           : ' A session figure appears after an account\'s 5h window resets once.'));
     }
     out.push(' ' + dim('A cycle counts only if maxpool ran for all of it and the account stayed enabled.'));
+    out.push(' ' + dim('~ = estimated from utilization; ≥ = at least this (window joined late); Δ = exact-by-difference; measured replaces both.'));
     return out;
   }