@timo972/cc-router 0.7.0

package/dist/proxy/session-router.js

@@ -0,0 +1,171 @@
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+const MAX_SESSION_ID_BYTES = 256;
+/**
+ * Normalize Claude Code's session header without retaining malformed or
+ * unexpectedly large values. Arrays are rejected rather than choosing one
+ * value because a session must have exactly one unambiguous identity.
+ */
+export function normalizeSessionId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        return undefined;
+    if (Buffer.byteLength(normalized, "utf8") > MAX_SESSION_ID_BYTES)
+        return undefined;
+    return normalized;
+}
+/**
+ * In-memory session affinity for Claude requests. Bindings and their counts
+ * are intentionally process-local and are never exposed for persistence or
+ * diagnostics.
+ */
+export class SessionRouter {
+    pool;
+    bindings = new Map();
+    activeSessionCounts = new Map();
+    now;
+    ttlMs;
+    maxEntries;
+    nextBindingGeneration = 1;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        if (!Number.isFinite(this.ttlMs) || this.ttlMs <= 0) {
+            throw new RangeError("session binding TTL must be a positive finite number");
+        }
+        if (!Number.isInteger(this.maxEntries) || this.maxEntries <= 0) {
+            throw new RangeError("session binding capacity must be a positive integer");
+        }
+    }
+    acquire(sessionHeader) {
+        const sessionId = normalizeSessionId(sessionHeader);
+        const now = this.now();
+        this.sweepExpiredBindings(now);
+        if (!sessionId) {
+            return this.wrapUnscoped(this.pool.acquireBest(this.activeSessionCounts));
+        }
+        const existing = this.bindings.get(sessionId);
+        if (existing) {
+            const stickyLease = this.pool.tryAcquire(existing.accountId);
+            if (stickyLease) {
+                existing.lastSeen = now;
+                return this.wrapScoped(stickyLease, "sticky", sessionId, existing.generation);
+            }
+            this.removeBinding(sessionId);
+        }
+        const lease = this.pool.acquireBest(this.activeSessionCounts);
+        const binding = this.insertBinding(sessionId, lease.account.id, now);
+        return this.wrapScoped(lease, existing ? "failover" : "new-session", sessionId, binding.generation);
+    }
+    /**
+     * Remove a binding only if it still belongs to the expected account. This
+     * protects a new failover binding from a late response on the old account.
+     */
+    invalidate(sessionHeader, expectedAccountId, expectedGeneration) {
+        const sessionId = normalizeSessionId(sessionHeader);
+        if (!sessionId)
+            return false;
+        const binding = this.bindings.get(sessionId);
+        if (!binding)
+            return false;
+        if (expectedAccountId !== undefined && binding.accountId !== expectedAccountId) {
+            return false;
+        }
+        if (expectedGeneration !== undefined && binding.generation !== expectedGeneration) {
+            return false;
+        }
+        return this.removeBinding(sessionId);
+    }
+    invalidateAccount(accountId) {
+        let removed = 0;
+        for (const [sessionId, binding] of this.bindings) {
+            if (binding.accountId !== accountId)
+                continue;
+            if (this.removeBinding(sessionId))
+                removed++;
+        }
+        return removed;
+    }
+    getActiveSessionCount(accountId) {
+        this.sweepExpiredBindings(this.now());
+        return this.getRawActiveSessionCount(accountId);
+    }
+    getBindingCount() {
+        this.sweepExpiredBindings(this.now());
+        return this.bindings.size;
+    }
+    /** Sweep once and expose only aggregate account IDs/counts. */
+    getActiveSessionCountsSnapshot() {
+        this.sweepExpiredBindings(this.now());
+        return new Map(this.activeSessionCounts);
+    }
+    wrapUnscoped(lease) {
+        return {
+            account: lease.account,
+            fallback: lease.fallback,
+            release: lease.release,
+            reason: "unscoped",
+        };
+    }
+    wrapScoped(lease, reason, sessionId, bindingGeneration) {
+        return {
+            account: lease.account,
+            fallback: lease.fallback,
+            release: lease.release,
+            reason,
+            sessionId,
+            bindingGeneration,
+        };
+    }
+    insertBinding(sessionId, accountId, lastSeen) {
+        if (this.bindings.size >= this.maxEntries)
+            this.evictLeastRecentlyUsed();
+        const binding = {
+            accountId,
+            lastSeen,
+            generation: this.nextBindingGeneration++,
+        };
+        this.bindings.set(sessionId, binding);
+        this.activeSessionCounts.set(accountId, this.getRawActiveSessionCount(accountId) + 1);
+        return binding;
+    }
+    removeBinding(sessionId) {
+        const binding = this.bindings.get(sessionId);
+        if (!binding)
+            return false;
+        this.bindings.delete(sessionId);
+        const remaining = this.getRawActiveSessionCount(binding.accountId) - 1;
+        if (remaining <= 0)
+            this.activeSessionCounts.delete(binding.accountId);
+        else
+            this.activeSessionCounts.set(binding.accountId, remaining);
+        return true;
+    }
+    getRawActiveSessionCount(accountId) {
+        return this.activeSessionCounts.get(accountId) ?? 0;
+    }
+    sweepExpiredBindings(now) {
+        for (const [sessionId, binding] of this.bindings) {
+            if (now - binding.lastSeen >= this.ttlMs)
+                this.removeBinding(sessionId);
+        }
+    }
+    evictLeastRecentlyUsed() {
+        let oldestSessionId;
+        let oldestLastSeen = Infinity;
+        // Map iteration order is insertion order, so equal timestamps retain the
+        // first entry as the deterministic eviction candidate.
+        for (const [sessionId, binding] of this.bindings) {
+            if (binding.lastSeen < oldestLastSeen) {
+                oldestSessionId = sessionId;
+                oldestLastSeen = binding.lastSeen;
+            }
+        }
+        if (oldestSessionId !== undefined)
+            this.removeBinding(oldestSessionId);
+    }
+}

package/dist/proxy/stats.js

@@ -0,0 +1,25 @@
+const MAX_LOG_ENTRIES = 100;
+class ProxyStats {
+    totalRequests = 0;
+    totalErrors = 0;
+    totalRefreshes = 0;
+    totalCacheReadTokens = 0;
+    totalCacheCreationTokens = 0;
+    totalInputTokens = 0;
+    totalOutputTokens = 0;
+    startTime = Date.now();
+    logs = [];
+    addLog(entry) {
+        this.logs.push(entry);
+        if (this.logs.length > MAX_LOG_ENTRIES)
+            this.logs.shift();
+    }
+    getRecentLogs(n = 20) {
+        return [...this.logs].reverse().slice(0, n);
+    }
+    getUptimeSeconds() {
+        return Math.round((Date.now() - this.startTime) / 1000);
+    }
+}
+// Singleton — shared across server and health endpoint
+export const stats = new ProxyStats();

package/dist/proxy/stream-lifecycle.js

@@ -0,0 +1,83 @@
+export const MAX_RETAINED_SSE_LINE_BYTES = 64 * 1024;
+export function createStreamLifecycleTracker(startedAt, inspectSse, now = Date.now) {
+    const state = {
+        sawMessageStop: false,
+        upstreamEnd: false,
+        upstreamAborted: false,
+        upstreamClose: false,
+        downstreamFinish: false,
+        downstreamClose: false,
+    };
+    let lineBuffer = Buffer.alloc(0);
+    let discardingOversizedLine = false;
+    const clearParserState = () => {
+        lineBuffer = Buffer.alloc(0);
+        discardingOversizedLine = false;
+    };
+    const inspectLine = (line) => {
+        const text = line.toString("utf8");
+        if (!text.startsWith("data: "))
+            return;
+        try {
+            const event = JSON.parse(text.slice(6));
+            if (event.type === "message_stop") {
+                state.sawMessageStop = true;
+                clearParserState();
+            }
+        }
+        catch {
+            // Complete non-JSON data lines are irrelevant to terminal tracking.
+        }
+    };
+    const terminal = () => {
+        clearParserState();
+        state.bodyDurationMs = Math.max(0, now() - startedAt);
+    };
+    return {
+        state,
+        observeChunk(chunk) {
+            state.lastByteAt = now();
+            if (!inspectSse || state.sawMessageStop)
+                return;
+            let offset = 0;
+            while (offset < chunk.length) {
+                const newlineAt = chunk.indexOf(0x0a, offset);
+                if (discardingOversizedLine) {
+                    if (newlineAt === -1)
+                        return;
+                    discardingOversizedLine = false;
+                    offset = newlineAt + 1;
+                    continue;
+                }
+                const fragmentEnd = newlineAt === -1 ? chunk.length : newlineAt;
+                const fragment = chunk.subarray(offset, fragmentEnd);
+                const retainedBytes = lineBuffer.length + fragment.length;
+                if (retainedBytes > MAX_RETAINED_SSE_LINE_BYTES) {
+                    lineBuffer = Buffer.alloc(0);
+                    discardingOversizedLine = newlineAt === -1;
+                }
+                else {
+                    lineBuffer = lineBuffer.length === 0
+                        ? Buffer.from(fragment)
+                        : Buffer.concat([lineBuffer, fragment], retainedBytes);
+                    if (newlineAt !== -1) {
+                        inspectLine(lineBuffer);
+                        lineBuffer = Buffer.alloc(0);
+                        if (state.sawMessageStop)
+                            return;
+                    }
+                }
+                if (newlineAt === -1)
+                    return;
+                offset = newlineAt + 1;
+            }
+        },
+        attach(upstream, downstream) {
+            upstream.once("end", () => { state.upstreamEnd = true; terminal(); });
+            upstream.once("aborted", () => { state.upstreamAborted = true; terminal(); });
+            upstream.once("close", () => { state.upstreamClose = true; terminal(); });
+            downstream.once("finish", () => { state.downstreamFinish = true; terminal(); });
+            downstream.once("close", () => { state.downstreamClose = true; terminal(); });
+        },
+    };
+}

package/dist/proxy/token-pool.js

@@ -0,0 +1,407 @@
+import { DEFAULT_RATE_LIMITS, ACCOUNT_USER_DEFAULTS, clampPercent } from "./types.js";
+export class EmptyPoolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmptyPoolError";
+    }
+}
+/** Returns the earliest non-zero reset timestamp (seconds) for an account. */
+function earliestReset(a) {
+    const r = a.rateLimits;
+    if (r.fiveHourReset && r.sevenDayReset)
+        return Math.min(r.fiveHourReset, r.sevenDayReset);
+    return r.fiveHourReset || r.sevenDayReset || Infinity;
+}
+/**
+ * Returns the reset timestamp (seconds) that must pass before the account
+ * stops being rate_limited. Prefers the `claim` window (the one Anthropic
+ * said was actually limiting); falls back to the earliest non-zero reset.
+ * Returns 0 when no reset is known.
+ */
+function limitingReset(a) {
+    const r = a.rateLimits;
+    if (r.claim === "five_hour" && r.fiveHourReset)
+        return r.fiveHourReset;
+    if (r.claim === "seven_day" && r.sevenDayReset)
+        return r.sevenDayReset;
+    const earliest = earliestReset(a);
+    return Number.isFinite(earliest) ? earliest : 0;
+}
+/**
+ * Roll over any rate-limit window whose reset timestamp has passed.
+ *
+ * `rateLimits` is a snapshot of Anthropic's response headers — utilization
+ * values only refresh when a new response arrives. That creates a stuck
+ * state in two scenarios:
+ *
+ *   1. `status: "rate_limited"` — the pool refuses to route to the account,
+ *      so no new response ever updates the status.
+ *   2. `fiveHourUtil` / `sevenDayUtil` at or above the user cap — `overUserCap`
+ *      evicts the account from rotation, so the util stays stale at its last
+ *      recorded value instead of dropping to ~0 when Anthropic's window resets.
+ *
+ * This sweep resolves both: when `now >= reset` for a window, the util is
+ * zeroed and the window's reset timestamp is cleared. When the limiting
+ * window expires, `status` flips back to `"allowed"`. The callback fires
+ * once per recovery so the dashboard can surface it.
+ */
+function clearExpiredRateLimitWindows(a, nowMs, onExpired) {
+    const nowSec = Math.floor(nowMs / 1000);
+    const r = a.rateLimits;
+    let changed = false;
+    let recovered = false;
+    if (r.fiveHourReset > 0 && nowSec >= r.fiveHourReset) {
+        r.fiveHourUtil = 0;
+        r.fiveHourReset = 0;
+        changed = true;
+    }
+    if (r.sevenDayReset > 0 && nowSec >= r.sevenDayReset) {
+        r.sevenDayUtil = 0;
+        r.sevenDayReset = 0;
+        changed = true;
+    }
+    // If the account was rate_limited and its claimed window just reset,
+    // return it to rotation. If we can't tell which window was limiting
+    // (empty claim) but all known windows have rolled over, clear the flag.
+    if (r.status === "rate_limited") {
+        const stillBlocked = (r.claim === "five_hour" && r.fiveHourReset > 0) ||
+            (r.claim === "seven_day" && r.sevenDayReset > 0) ||
+            (r.claim === "" && (r.fiveHourReset > 0 || r.sevenDayReset > 0));
+        if (!stillBlocked) {
+            r.status = "allowed";
+            recovered = true;
+            changed = true;
+        }
+    }
+    if (changed)
+        r.lastUpdated = nowMs;
+    if (recovered && onExpired)
+        onExpired(a);
+}
+/** True when the account's user-defined caps have been reached. */
+function overUserCap(a) {
+    return (a.rateLimits.fiveHourUtil * 100 >= a.sessionLimitPercent ||
+        a.rateLimits.sevenDayUtil * 100 >= a.weeklyLimitPercent);
+}
+/** Filter out accounts the user has taken out of the rotation. */
+function isUsable(a) {
+    return a.enabled && !overUserCap(a);
+}
+export class TokenPool {
+    accounts;
+    inFlight = new Map();
+    cooldownUntil = new Map();
+    now;
+    currentIndex = 0;
+    constructor(accounts, options = {}) {
+        this.accounts = accounts;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Compatibility wrapper for request sites that do not yet retain leases.
+     * Selection considers accounts that are:
+     *   • healthy
+     *   • not busy
+     *   • not rate-limited by Anthropic
+     *   • enabled (user toggle)
+     *   • under the user-configured 5h/7d caps
+     *
+     * Fallback chain when nothing is available:
+     *   1. Any healthy+usable (enabled & under caps) account — pick earliest reset.
+     *   2. Any healthy account — pick earliest reset. This intentionally ignores
+     *      user caps when every option is capped; limits are advisory, not a hard
+     *      ban that would leave Claude Code with no working account. The fallback
+     *      is logged via the optional onCapBypass callback so the dashboard can
+     *      surface it instead of silently exceeding the cap.
+     *   3. Any account as a last resort (only if every account is unhealthy).
+     *
+     * Fallback sets prefer the lowest in-flight load, then the earliest reset.
+     *
+     * Throws `EmptyPoolError` when there are no accounts at all — callers in
+     * the request path should map this to a 503. The DELETE endpoint guards
+     * against this state by refusing to remove the last account.
+     */
+    getNext() {
+        const lease = this.acquireBest(new Map());
+        lease.release();
+        return lease.account;
+    }
+    /**
+     * Acquire the best eligible account using load, session affinity pressure,
+     * rate-limit headroom, and a rotating tie-break, in that order.
+     */
+    acquireBest(activeSessions) {
+        if (this.accounts.length === 0) {
+            throw new EmptyPoolError("token pool is empty — add an account first");
+        }
+        this.sweepExpiredCooldowns();
+        const eligible = this.accounts.filter(account => this.isEligibleWithoutSweep(account));
+        if (eligible.length > 0) {
+            const account = this.selectEligible(eligible, activeSessions);
+            this.advanceCursor(account);
+            return this.createLease(account, false);
+        }
+        const healthyUsable = this.accounts.filter(account => account.healthy && isUsable(account));
+        const healthy = this.accounts.filter(account => account.healthy);
+        const fallbackCandidates = healthyUsable.length > 0
+            ? healthyUsable
+            : healthy.length > 0
+                ? healthy
+                : this.accounts;
+        const account = this.selectFallback(fallbackCandidates);
+        this.advanceCursor(account);
+        if (overUserCap(account))
+            this.onCapBypass?.(account);
+        return this.createLease(account, true);
+    }
+    /** Acquire a specific account for an existing sticky session. */
+    tryAcquire(accountId) {
+        const account = this.findById(accountId);
+        if (!account)
+            return null;
+        clearExpiredRateLimitWindows(account, this.now(), this.onCooldownExpired);
+        if (!this.isEligibleWithoutSweep(account))
+            return null;
+        return this.createLease(account, false);
+    }
+    isEligible(accountId) {
+        const account = this.findById(accountId);
+        if (!account)
+            return false;
+        clearExpiredRateLimitWindows(account, this.now(), this.onCooldownExpired);
+        return this.isEligibleWithoutSweep(account);
+    }
+    getInFlight(accountId) {
+        return this.inFlight.get(accountId) ?? 0;
+    }
+    setCooldown(accountId, durationMs) {
+        const account = this.findById(accountId);
+        if (!account)
+            return;
+        this.setCooldownForAccount(account, durationMs);
+    }
+    /** Apply cooldown only to the exact account incarnation that was routed. */
+    setCooldownForAccount(account, durationMs) {
+        if (this.findById(account.id) !== account)
+            return;
+        if (!Number.isFinite(durationMs) || durationMs <= 0)
+            return;
+        const proposedExpiry = this.now() + durationMs;
+        const existingExpiry = this.cooldownUntil.get(account.id) ?? 0;
+        this.cooldownUntil.set(account.id, Math.max(existingExpiry, proposedExpiry));
+    }
+    isCoolingDown(accountId) {
+        const until = this.cooldownUntil.get(accountId);
+        if (until === undefined)
+            return false;
+        if (this.now() < until)
+            return true;
+        this.cooldownUntil.delete(accountId);
+        return false;
+    }
+    isEligibleWithoutSweep(account) {
+        return account.healthy &&
+            !account.busy &&
+            !this.isCoolingDown(account.id) &&
+            account.rateLimits.status !== "rate_limited" &&
+            isUsable(account);
+    }
+    selectEligible(candidates, activeSessions) {
+        return candidates.reduce((best, account) => {
+            const comparison = this.compareTuple([
+                this.getInFlight(account.id),
+                activeSessions.get(account.id) ?? 0,
+                this.headroomScore(account),
+                this.circularDistance(account),
+            ], [
+                this.getInFlight(best.id),
+                activeSessions.get(best.id) ?? 0,
+                this.headroomScore(best),
+                this.circularDistance(best),
+            ]);
+            return comparison < 0 ? account : best;
+        });
+    }
+    selectFallback(candidates) {
+        return candidates.reduce((best, account) => {
+            const comparison = this.compareTuple([this.getInFlight(account.id), earliestReset(account), this.circularDistance(account)], [this.getInFlight(best.id), earliestReset(best), this.circularDistance(best)]);
+            return comparison < 0 ? account : best;
+        });
+    }
+    headroomScore(account) {
+        const fiveHourCap = account.sessionLimitPercent / 100;
+        const sevenDayCap = account.weeklyLimitPercent / 100;
+        const fiveHourUtil = Number.isFinite(account.rateLimits.fiveHourUtil)
+            ? Math.max(0, account.rateLimits.fiveHourUtil)
+            : 0;
+        const sevenDayUtil = Number.isFinite(account.rateLimits.sevenDayUtil)
+            ? Math.max(0, account.rateLimits.sevenDayUtil)
+            : 0;
+        return Math.max(fiveHourUtil / fiveHourCap, sevenDayUtil / sevenDayCap);
+    }
+    circularDistance(account) {
+        const index = this.accounts.indexOf(account);
+        return (index - this.currentIndex + this.accounts.length) % this.accounts.length;
+    }
+    compareTuple(left, right) {
+        for (let i = 0; i < left.length; i++) {
+            if (left[i] !== right[i])
+                return left[i] - right[i];
+        }
+        return 0;
+    }
+    advanceCursor(account) {
+        const index = this.accounts.indexOf(account);
+        this.currentIndex = (index + 1) % this.accounts.length;
+    }
+    createLease(account, fallback) {
+        this.inFlight.set(account.id, this.getInFlight(account.id) + 1);
+        account.requestCount++;
+        account.lastUsed = this.now();
+        let released = false;
+        return {
+            account,
+            fallback,
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                // IDs may be reused after an account is removed. A lease belongs to
+                // the exact Account instance it acquired and must never decrement a
+                // replacement account's load counter.
+                if (this.findById(account.id) !== account)
+                    return;
+                const remaining = Math.max(0, this.getInFlight(account.id) - 1);
+                if (remaining === 0)
+                    this.inFlight.delete(account.id);
+                else
+                    this.inFlight.set(account.id, remaining);
+            },
+        };
+    }
+    /** Optional listener fired when a request is routed to a capped account
+     *  because every account in the pool was over its user-configured cap. */
+    onCapBypass;
+    /** Optional listener fired when a rate-limited account's cooldown expires
+     *  and it is automatically returned to the rotation. */
+    onCooldownExpired;
+    /**
+     * Sweep the pool for accounts whose rate_limited cooldown has passed and
+     * clear the flag in place. Intended for periodic calls from the dashboard
+     * poll loop so the UI reflects recovery without waiting for a new request.
+     */
+    sweepExpiredCooldowns() {
+        const now = this.now();
+        for (const a of this.accounts) {
+            clearExpiredRateLimitWindows(a, now, this.onCooldownExpired);
+            this.isCoolingDown(a.id);
+        }
+    }
+    getAll() {
+        return this.accounts;
+    }
+    getHealthy() {
+        return this.accounts.filter(a => a.healthy);
+    }
+    getStats() {
+        return this.accounts.map(a => ({
+            id: a.id,
+            healthy: a.healthy,
+            busy: a.busy,
+            inFlightRequests: this.getInFlight(a.id),
+            coolingDown: this.isCoolingDown(a.id),
+            requestCount: a.requestCount,
+            errorCount: a.errorCount,
+            expiresInMs: a.tokens.expiresAt - Date.now(),
+            lastUsedMs: a.lastUsed,
+            lastRefreshMs: a.lastRefresh,
+            rateLimits: a.rateLimits,
+            enabled: a.enabled,
+            sessionLimitPercent: a.sessionLimitPercent,
+            weeklyLimitPercent: a.weeklyLimitPercent,
+        }));
+    }
+    // ─── Mutation API (used by the authenticated HTTP endpoints) ───────────────
+    findById(id) {
+        return this.accounts.find(a => a.id === id) ?? null;
+    }
+    /**
+     * Apply a partial update to an account's user-controlled fields.
+     * Only `enabled`, `sessionLimitPercent`, and `weeklyLimitPercent` are
+     * touched — token fields are never accepted via this API.
+     * Returns the updated account, or null if the id was not found.
+     */
+    updateAccount(id, patch) {
+        const a = this.findById(id);
+        if (!a)
+            return null;
+        if (patch.enabled !== undefined)
+            a.enabled = !!patch.enabled;
+        if (patch.sessionLimitPercent !== undefined) {
+            a.sessionLimitPercent = clampPercent(patch.sessionLimitPercent);
+        }
+        if (patch.weeklyLimitPercent !== undefined) {
+            a.weeklyLimitPercent = clampPercent(patch.weeklyLimitPercent);
+        }
+        return a;
+    }
+    /**
+     * Append a new account built from a persisted AccountRecord.
+     * Rejects duplicates by id — callers should pre-check with findById().
+     */
+    addAccount(record) {
+        if (this.findById(record.id)) {
+            throw new Error(`Account "${record.id}" already exists`);
+        }
+        const account = {
+            id: record.id,
+            tokens: {
+                accessToken: record.accessToken,
+                refreshToken: record.refreshToken,
+                expiresAt: record.expiresAt,
+                scopes: record.scopes ?? ["user:inference", "user:profile"],
+            },
+            healthy: true,
+            busy: false,
+            requestCount: 0,
+            errorCount: 0,
+            lastUsed: 0,
+            lastRefresh: 0,
+            consecutiveErrors: 0,
+            rateLimits: { ...DEFAULT_RATE_LIMITS },
+            enabled: record.enabled !== false,
+            sessionLimitPercent: record.sessionLimitPercent !== undefined
+                ? clampPercent(record.sessionLimitPercent)
+                : ACCOUNT_USER_DEFAULTS.sessionLimitPercent,
+            weeklyLimitPercent: record.weeklyLimitPercent !== undefined
+                ? clampPercent(record.weeklyLimitPercent)
+                : ACCOUNT_USER_DEFAULTS.weeklyLimitPercent,
+        };
+        this.accounts.push(account);
+        return account;
+    }
+    /**
+     * Remove an account by id. Returns true if something was removed.
+     *
+     * CRITICAL: mutates `this.accounts` IN PLACE via splice() rather than
+     * reassigning it. The server passes the same array reference to
+     * `startRefreshLoop()` at startup; reassigning would desynchronize the
+     * refresh loop from the pool, and the loop's `saveAccounts(accounts)` call
+     * would later resurrect the deleted account on disk.
+     */
+    removeAccount(id) {
+        const idx = this.accounts.findIndex(a => a.id === id);
+        if (idx === -1)
+            return false;
+        this.accounts.splice(idx, 1);
+        this.inFlight.delete(id);
+        this.cooldownUntil.delete(id);
+        if (this.accounts.length > 0) {
+            this.currentIndex = this.currentIndex % this.accounts.length;
+        }
+        else {
+            this.currentIndex = 0;
+        }
+        return true;
+    }
+}