maxpool 1.5.37 → 1.5.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maxpool",
-  "version": "1.5.37",
+  "version": "1.5.38",
   "description": "Multi-account Claude Code proxy with adaptive, rate-aware load balancing across Claude accounts",
   "type": "module",
   "main": "src/index.js",
@@ -15,7 +15,8 @@
     "start": "node src/index.js",
     "test": "bash scripts/run-tests.sh",
     "lint": "eslint src/ test/",
-    "release": "bash scripts/release.sh"
+    "release": "bash scripts/release.sh",
+    "version": "bash scripts/update-changelog.sh"
   },
   "keywords": [
     "claude",
@@ -38,5 +39,8 @@
   },
   "engines": {
     "node": ">=20.3.0"
+  },
+  "devDependencies": {
+    "git-cliff": "2.13.1"
   }
 }

package/src/account-manager.js

@@ -15,6 +15,15 @@ const BOUNDED_REPOLL_HOLD_MS = 60_000;
 // session can never ping-pong between two similarly-loaded accounts.
 const REBALANCE_SCORE_MARGIN = 0.5;   // candidate score must be ≤ 50% of the bound account's
 const REBALANCE_MIN_ABS_GAP = 0.5;    // …with a small absolute floor so near-zero scores don't micro-churn
+// Warmup-pull: a freshly-ADDED account (mid-session, no reload) would otherwise idle
+// until a reload clears bindings, because bound sessions only leave a HOT account. So
+// for a bounded window pull migration-safe sessions onto it. Keyed on the account's
+// own onboarding state (addedAt + completedRequests), NOT relative load — so it
+// PROVABLY TERMINATES (once it has served WARMUP_REQUESTS, or WARMUP_MS elapses, it
+// stops warming and never fires again) and cannot oscillate for any #sessions/#accounts
+// ratio, unlike a share/concurrency-gap rebalance (which flaps on the lagging load signal).
+const WARMUP_MS = 5 * 60 * 1000;      // a just-added account stays "warming" this long…
+const WARMUP_REQUESTS = 5;            // …or until it has served this many requests, whichever comes first
 // Weekly-pressure tiers, healthiest first. A fresh (unknown) account is the best
 // migration target; migration requires the candidate be a STRICTLY healthier tier.
 const WEEKLY_TIER = { unknown: 0, normal: 0, soft: 1, reserve: 2, critical: 3, exhausted: 4 };
@@ -1138,6 +1147,54 @@ export class AccountManager {
    *  All gates must hold: thinking-safe + not mid queue-admission + bound is hot +
    *  a genuinely-healthy alternative that is BOTH much cheaper AND a strictly
    *  healthier weekly tier (so concurrency jitter alone can never trigger a move). */
+  /** Is this account still in its post-add onboarding window? A freshly-ADDED
+   *  account (addedAt set only by addAccount, never on boot) that has served fewer
+   *  than WARMUP_REQUESTS within WARMUP_MS. Providers are never "warming" targets. */
+  _isWarming(account, now = Date.now()) {
+    if (!account || account.type === 'provider') return false;
+    if (account.addedAt == null) return false;                 // boot/config account → never warming
+    if (account.completedRequests >= WARMUP_REQUESTS) return false; // onboarded → terminates the pull
+    return (now - account.addedAt) < WARMUP_MS;
+  }
+
+  /** Warmup-pull target: the best (lowest-score) healthy, migration-eligible,
+   *  still-WARMING NON-provider account to onboard a freshly-added account WITHOUT a
+   *  reload, or null. Returned DIRECTLY (not via the score-loop fallthrough) so the
+   *  destination is GUARANTEED non-provider even under 'always' cross-provider policy
+   *  — a signed-thinking session can never be shuttled onto a provider here (which
+   *  the shared candidate loop, keyed only on _matchesRequest, would not prevent).
+   *  Fires only when the bound account is itself established (not warming) AND is
+   *  actually carrying recent load — relieving a real carrier onto the fresh account,
+   *  never churning fresh↔fresh or re-homing an idle session. */
+  _warmupPullTarget(bound, profile, excludedIndexes, requestInfo, now = Date.now()) {
+    // Cheapest early-out first: the overwhelmingly common steady state has NO warming
+    // account, so bail before the migration-safety / load / fleet-scoring work. This
+    // runs on every bound request's selection — keep the no-warming path near-free.
+    if (!this.accounts.some(a => this._isWarming(a, now))) return null;
+    if (!this._migrationSafeForRequest(requestInfo)) return null;
+    if (requestInfo.queueTicket || requestInfo.queueAdmitted) return null;
+    if (this._isWarming(bound, now)) return null;
+    if (this._loadSummary(bound, this.scheduler.spreadWindowMs, now).weight <= 0) return null;
+    const ctx = this._scoringContext();
+    let best = null;
+    let bestScore = Infinity;
+    for (const account of this.accounts) {
+      if (account.index === bound.index) continue;
+      if (account.type === 'provider') continue;               // GUARANTEED non-provider destination
+      if (excludedIndexes.has(account.index)) continue;
+      if (!this._isWarming(account, now)) continue;
+      if (!this._matchesRequest(account, profile, requestInfo)) continue;
+      // Genuinely-healthy target only (same bar as the hot-rebalance candidate scan).
+      if (!this._isAvailable(account, { allowWeeklyReserve: false, allowWeeklyCritical: false, model: requestInfo.model })) continue;
+      const score = this._scoreAccount(account, requestInfo, ctx);
+      if (score < bestScore) {
+        bestScore = score;
+        best = account;
+      }
+    }
+    return best;
+  }
+
   _shouldRebalanceBoundSession(bound, profile, excludedIndexes, requestInfo, scoringCtx) {
     if (!this._migrationSafeForRequest(requestInfo)) return false;
     if (requestInfo.queueTicket || requestInfo.queueAdmitted) return false;
@@ -1350,10 +1407,24 @@ export class AccountManager {
       }
     }
     const bound = this._boundAccount(requestInfo.sessionKey, profile, excludedIndexes, requestInfo);
-    if (bound
-      && !this._hasHigherPriorityAvailable(bound, profile, excludedIndexes, requestInfo)
-      && !this._shouldRebalanceBoundSession(bound, profile, excludedIndexes, requestInfo, scoringCtx)) {
-      return bound;
+    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,
+      // before the sticky "stay bound" return. Directed (not via the score loop) so
+      // the destination is guaranteed non-provider. Bounded + self-terminating via
+      // _isWarming; each session re-homes at most once → no flap. Skipped for a
+      // preferred/pinned request (handled above) and any non-migration-safe request.
+      const warmupTarget = this._warmupPullTarget(
+        bound, profile, excludedIndexes, requestInfo, scoringCtx?.now,
+      );
+      if (warmupTarget) {
+        this.currentIndex = warmupTarget.index;
+        return warmupTarget;   // _bindSession re-homes the session on acquire
+      }
+      if (!this._hasHigherPriorityAvailable(bound, profile, excludedIndexes, requestInfo)
+        && !this._shouldRebalanceBoundSession(bound, profile, excludedIndexes, requestInfo, scoringCtx)) {
+        return bound;
+      }
     }
     // Else fall through to the candidate score loop, which re-homes the session
     // onto the best healthy account via _bindSession on acquire.
@@ -2488,6 +2559,10 @@ export class AccountManager {
       provisionalRateLimitFingerprint: null,
       recoveredAt: null,
       lastQuotaLogKey: null,
+      // Onboarding clock for the warmup-pull — set ONLY here (mid-session add),
+      // never on the boot/config construction path, so an established fleet account
+      // is never "warming". Lets a just-added account draw load without a reload.
+      addedAt: Date.now(),
     });
     return index;
   }

package/src/server.js

@@ -56,6 +56,17 @@ const DEFAULT_QUEUE = {
   // Non-streaming requests have no SSE heartbeat to keep them alive, so a long
   // hold would die on the client timeout anyway. Cap their wait conservatively.
   nonStreamMaxWaitMs: 5 * 60 * 1000,
+  // Proactive streaming keep-alive: a STREAMING request gets ZERO client bytes
+  // while maxpool selects a route, cycles failover, and waits for the upstream's
+  // first byte (up to UPSTREAM_TTFB_MS=120s) — the queue heartbeat only starts
+  // once a request is QUEUED. If that client-silent window exceeds the client's
+  // own idle timeout (Claude Code aborts "Stream idle timeout - no chunks
+  // received", observed as low as ~23s), the client gives up on a request maxpool
+  // is still patiently serving. If the upstream hasn't delivered bytes within this
+  // grace, commit the SSE stream + start the heartbeat so the client never idles
+  // out. Kept above a normal fast TTFB (1-5s → common case never early-commits,
+  // behavior unchanged) and well below the client idle floor. Env-overridable.
+  streamForwardGraceMs: Math.max(1000, Number(process.env.MAXPOOL_STREAM_FORWARD_GRACE_MS) || 10000),
   // count_tokens is cheap non-streaming metadata — cap its queue wait VERY low so it
   // fast-fails with a retryable 429 instead of hanging silently past the client's idle
   // window. Kept well under any plausible client idle timeout (observed errors as low
@@ -492,6 +503,28 @@ async function forwardRequest(
     UPSTREAM_TTFB_MS,
   );
   ttfbTimer.unref?.();
+  // Proactive streaming keep-alive. UPSTREAM_TTFB_MS (120s) is FAR above the
+  // client's own idle timeout (~23-60s), and the queue heartbeat only starts once
+  // a request is QUEUED — so a streaming request whose selected upstream is slow to
+  // first byte, or that burns the client's timeout cycling failover, sends the
+  // client ZERO bytes and is aborted ("Stream idle timeout - no chunks received")
+  // on a request maxpool is still serving. If bytes haven't arrived within the
+  // grace, commit the SSE stream + heartbeat so the client stays alive. The
+  // deadline is anchored ONCE per request (??=) so it also bounds CUMULATIVE
+  // failover time across re-forwards, not each attempt independently.
+  const streamForwardGraceMs = queueConfig?.streamForwardGraceMs == null
+    ? 10000
+    : Math.max(0, Number(queueConfig.streamForwardGraceMs) || 0);
+  let streamGraceTimer = null;
+  if (requestInfo.stream && !res.headersSent) {
+    requestInfo.streamGraceDeadline ??= Date.now() + streamForwardGraceMs;
+    const graceDelay = Math.max(0, requestInfo.streamGraceDeadline - Date.now());
+    streamGraceTimer = setTimeout(
+      () => commitStreamGraceHeartbeat(res, requestInfo, queueConfig, accountManager),
+      graceDelay,
+    );
+    streamGraceTimer.unref?.();
+  }
   try {
     let upstreamRes;
     try {
@@ -504,6 +537,9 @@ async function forwardRequest(
       });
     } finally {
       clearTimeout(ttfbTimer);
+      // Stop the grace timer for THIS attempt — but LEAVE streamGraceDeadline set so
+      // a re-forward (failover) re-arms for the REMAINING time to the shared deadline.
+      if (streamGraceTimer) clearTimeout(streamGraceTimer);
     }
     // Response arrived — the pre-response leak window is over. Stop guarding for
     // client-disconnect via abort (streamResponse handles mid-stream disconnects).
@@ -1153,7 +1189,7 @@ function unavailableMessage(accountManager, requestInfo = {}, retryAfter, willRe
   return `All ${n} accounts exhausted. Retry in ${retryAfter}s.`;
 }
 
-export const __serverTest = { unavailableMessage, computeQueueWindowMs, isRetriableUpstreamStatus, headerValue, getMaxpoolProfile, ensureQueueHeartbeat, clearQueueHeartbeat, describeRequest, classifyRateLimit, detectTranscriptOrigin, isAnthropicIncompatBody, streamResponse, startIdleRequestReaper };
+export const __serverTest = { unavailableMessage, computeQueueWindowMs, isRetriableUpstreamStatus, headerValue, getMaxpoolProfile, ensureQueueHeartbeat, clearQueueHeartbeat, commitStreamGraceHeartbeat, describeRequest, classifyRateLimit, detectTranscriptOrigin, isAnthropicIncompatBody, streamResponse, startIdleRequestReaper };
 
 async function readErrorBody(upstreamRes, limitBytes = 64 * 1024) {
   if (!upstreamRes.body) return '';
@@ -1507,26 +1543,56 @@ async function queueAndRetry(
   ).then(() => true);
 }
 
+// The stream-forward grace-timer callback (extracted so its logic is unit-testable
+// in isolation). Fires when a STREAMING request's upstream is slow to first byte:
+// commits the SSE stream + heartbeat so the client never idle-times-out. Client-
+// abort-safe — an async timer has NO synchronous liveness precondition (unlike the
+// queue caller), so if the client vanished during the forward window (or the stream
+// is already committed) it reaps the queue slot and bails WITHOUT touching the dead
+// socket. ensureQueueHeartbeat is itself hardened against a throwing write, but this
+// guard is the cheaper first line of defense against the worker-bounce race.
+function commitStreamGraceHeartbeat(res, requestInfo, queueConfig, accountManager) {
+  if (res.destroyed || res.writableEnded || res.headersSent) {
+    clearQueueHeartbeat(requestInfo);
+    accountManager.removeQueuedRequest?.(requestInfo);
+    return;
+  }
+  ensureQueueHeartbeat(res, requestInfo, queueConfig, accountManager);
+}
+
 function ensureQueueHeartbeat(res, requestInfo, queueConfig, accountManager) {
   if (!requestInfo.stream || requestInfo.queueHeartbeatActive || res.headersSent) return;
   const heartbeatMs = Math.max(1000, Number(queueConfig.heartbeatMs) || 10_000);
-  res.writeHead(200, {
-    'Content-Type': 'text/event-stream',
-    'Cache-Control': 'no-cache',
-    Connection: 'keep-alive',
-    'X-Accel-Buffering': 'no',
-  });
-  res.flushHeaders?.();
-  res.write(': maxpool queued\n\n');
-  requestInfo.queueHeartbeatActive = true;
   // The heartbeat is the liveness probe: if the client is gone (socket
-  // destroyed/ended, or the write throws EPIPE/ERR_STREAM_DESTROYED), release
+  // destroyed/ended, or a write throws EPIPE/ERR_STREAM_DESTROYED), release
   // the queue slot + bytes IMMEDIATELY rather than letting a dead ticket occupy
   // the queue until its (up to 7d) deadline — the ghost-leak guard.
   const reapDead = () => {
     clearQueueHeartbeat(requestInfo);
     accountManager?.removeQueuedRequest?.(requestInfo);
   };
+  // The INITIAL commit can throw if the socket died between the caller's last
+  // liveness check and here. The synchronous queue caller (queueAndRetry) bails
+  // on res.destroyed right before calling, but the ASYNC stream-forward grace
+  // timer has no such precondition — the client can vanish mid-window. An
+  // unguarded throw here has NO 'error' listener → uncaughtException → the worker
+  // process.exits and bounces EVERY in-flight stream. Guard the initial write
+  // exactly like the interval callback below so ensureQueueHeartbeat is safe from
+  // ANY caller, sync or async.
+  try {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    res.flushHeaders?.();
+    res.write(': maxpool queued\n\n');
+  } catch {
+    reapDead();
+    return;
+  }
+  requestInfo.queueHeartbeatActive = true;
   requestInfo.queueHeartbeatTimer = setInterval(() => {
     if (res.destroyed || res.writableEnded) { reapDead(); return; }
     try {

package/src/tui.js

@@ -26,14 +26,27 @@ const vw = s => strip(s).length;
 
 // ── Accounts-table columns ───────────────────────────────────
 // Fixed column widths shared by the header row (acctHeader) AND every data row, so
-// the header labels stay aligned with the columns they name. The Account/Type/
-// Status/Quota start offsets (4/17/26/40) are pure functions of these widths + the
+// the header labels stay aligned with the columns they name. The Account/Provider/
+// Status/Quota start offsets (4/17/27/41) are pure functions of these widths + the
 // 4-col row prefix, independent of the quota-bar width.
 const NAME_W = 12;         // a.name.slice(0, NAME_W).padEnd(NAME_W)
-const TYPE_W = 8;          // a.type.padEnd(TYPE_W) — fits "provider"
+const PROVIDER_W = 9;      // providerLabel(a).padEnd(PROVIDER_W) — fits "Anthropic"
 const STATUS_W = 13;       // rpad(status, STATUS_W) — fits "throttled 59s"
 const ROW_PREFIX = '    '; // ' ' + sel(1) + cur(1) + ' ' — 4 cols before the name
 
+// Human provider name for the accounts-table "Provider" column. account.provider
+// is 'anthropic' for oauth/apikey accounts (they ARE Anthropic — the oauth-vs-key
+// billing split is still shown by the Ses/Wk vs Tok/Req quota-bar labels, not here),
+// and 'zai'/'kimi' for the GLM/Kimi fallback providers. Explicit map + a graceful
+// Titlecase default so a future provider (Codex/Grok) renders sanely; truncated to
+// the column width so a long name can never misalign the row.
+const PROVIDER_LABELS = { anthropic: 'Anthropic', zai: 'z.ai', kimi: 'Moonshot', openai: 'OpenAI', codex: 'Codex', grok: 'Grok', xai: 'Grok' };
+function providerLabel(a) {
+  const key = a.provider || (a.type === 'provider' ? 'provider' : 'anthropic');
+  const label = PROVIDER_LABELS[key] || (key.charAt(0).toUpperCase() + key.slice(1));
+  return label.slice(0, PROVIDER_W);
+}
+
 /**
  * Aligned column header for the accounts table. Names the three columns that carry
  * NO inline label (Account / Type / Status) plus a group label over the two quota
@@ -45,7 +58,7 @@ function acctHeader(W) {
   const quota = W >= 88 ? 'Quota (used% · resets-in)' : 'Quota';
   return ROW_PREFIX
     + 'Account'.padEnd(NAME_W) + ' '
-    + 'Type'.padEnd(TYPE_W) + ' '
+    + 'Provider'.padEnd(PROVIDER_W) + ' '
     + 'Status'.padEnd(STATUS_W) + ' '
     + quota;
 }
@@ -221,7 +234,7 @@ function emptyBar(label, w = 10) {
   return `${ESC}100m${' '.repeat(lp)}${text}${' '.repeat(rp)}${RESET}`;
 }
 
-export const __tuiTest = { formatReset, quotaLabel, bar, emptyBar, strip, loadText, countdown, acctHeader, fitLine };
+export const __tuiTest = { formatReset, quotaLabel, bar, emptyBar, strip, loadText, countdown, acctHeader, fitLine, providerLabel };
 
 function timestamp() {
   return new Date().toLocaleTimeString('en-US', { hour12: false });
@@ -554,9 +567,25 @@ export class TUI {
     this.selIdx = selectable.includes(this.am.currentIndex) ? this.am.currentIndex : selectable[0];
   }
 
+  // Real am.accounts indices in DISPLAY order: non-provider (Claude/OAuth/apikey)
+  // accounts first, providers (GLM/Kimi fallback) last, stable within each group.
+  // The single source of truth for row order — the render loop AND selection nav
+  // both iterate it, so the highlight can never desync from the visible list. The
+  // canonical am.accounts array order is never mutated (routing/index actions safe).
+  _displayOrder() {
+    const nonProv = [];
+    const prov = [];
+    this.am.accounts.forEach((a, i) => (a.type === 'provider' ? prov : nonProv).push(i));
+    return [...nonProv, ...prov];
+  }
+
   _selectableIndexes(action) {
-    return this.am.accounts
-      .map((account, index) => ({ account, index }))
+    // Map over _displayOrder() BEFORE filtering so the nav array is in DISPLAY order
+    // with the existing selectability filter intact — _keySelect steps this array, so
+    // visual order == nav order automatically and it can never land on a provider
+    // (prefer) or a non-configurable runtime account.
+    return this._displayOrder()
+      .map(index => ({ account: this.am.accounts[index], index }))
       .filter(({ account }) => {
         if (action === 'prefer') return account.type !== 'provider' && account.enabled;
         return this._configAccountIndex(account) >= 0;
@@ -991,11 +1020,17 @@ export class TUI {
       // misaligned second header).
       lines.push(dimUnderline(acctHeader(W)));
       const showBoth = W >= 70;
+      // 57/46 = the fixed pre-bar column span (prefix + Account + Provider + Status +
+      // gaps); grew by 1 with the Provider column (was 56/45 under the 8-wide Type col).
       const bw = showBoth
-        ? Math.max(5, Math.min(20, Math.floor((W - 56) / 2)))
-        : Math.max(5, Math.min(20, W - 45));
-
-      for (let i = 0; i < this.am.accounts.length; i++) {
+        ? Math.max(5, Math.min(20, Math.floor((W - 57) / 2)))
+        : Math.max(5, Math.min(20, W - 46));
+
+      // Claude/OAuth accounts first, providers (GLM/Kimi fallback) last — a stable
+      // display order over the canonical am.accounts array (which stays untouched so
+      // routing/index-keyed actions are unaffected). Selection navigation shares the
+      // SAME order via _selectableIndexes → _displayOrder.
+      for (const i of this._displayOrder()) {
         lines.push(this._renderAcct(i, bw, showBoth));
       }
       // Glossary FOOTER (expands the abbreviations the header + inline labels can't
@@ -1076,10 +1111,11 @@ export class TUI {
     const rawName = a.name.slice(0, NAME_W).padEnd(NAME_W);
     const name = isSel ? bold(rawName) : rawName;
 
-    // Type — pad to 8 so "provider" (8 chars) doesn't overflow a 7-wide column and
-    // shift the whole provider row (incl. its quota bars) 1 char out of alignment
-    // with the "oauth"/"apikey" rows.
-    const type = gray(a.type.padEnd(TYPE_W));
+    // Provider column — the real vendor (Anthropic / z.ai / Moonshot), padded to
+    // PROVIDER_W so "Anthropic" (9 chars) never overflows and shifts the row (incl.
+    // its quota bars) out of alignment with the shorter provider labels. This single
+    // cell is reused by both the oauth/apikey row below and _renderProviderAcct.
+    const type = gray(providerLabel(a).padEnd(PROVIDER_W));
 
     // Status
     let status;