opencode-auth-load-balancer 0.2.1

package/dist/providers/types.d.ts

@@ -0,0 +1,122 @@
+import type { PoolAccount, TokenSet, UsageSnapshot } from '../types';
+export type FetchInput = string | URL | Request;
+/**
+ * Error classification drives rotation:
+ *   "account" — this account is rate-limited/over quota (429/402). Cool it down, try next.
+ *   "auth"    — this account's credential is bad (401/403). Cool it down, try next.
+ *   "service" — provider-side/transient (5xx). Return as-is.
+ *   "ok"      — success or any other status (including 4xx client errors like
+ *               400/404): return the response as-is.
+ */
+export type ErrorClass = 'account' | 'auth' | 'service' | 'ok';
+/**
+ * Shared HTTP-status → ErrorClass mapping. Both Anthropic and OpenAI adapters
+ * delegate to this single source of truth so a future status (e.g. 408, 425)
+ * being added in one provider but missed in the other cannot silently diverge
+ * rotation behavior between Claude and Codex.
+ */
+export declare function classifyHttpStatus(status: number): ErrorClass;
+/**
+ * Parse a fetch input into a URL, or null when it is not a valid absolute URL.
+ * Shared by both providers' `rewriteUrl` so the `FetchInput → URL` prologue
+ * (string/URL vs Request handling, malformed-input bail) can never drift
+ * between Claude and Codex — same rationale as `classifyHttpStatus` above.
+ */
+export declare function urlFromInput(input: FetchInput): URL | null;
+export interface AuthorizeRequest {
+    url: string;
+    verifier: string;
+    state: string;
+    redirectUri: string;
+}
+/**
+ * A request-body rewrite that downgrades the requested model to a cheaper
+ * fallback (e.g. Claude Opus → Sonnet) when the primary model's tier quota is
+ * exhausted on the chosen account. `body` is the rewritten JSON string to send;
+ * `fromModel`/`toModel` drive the user-facing switch toast/log. `fromTier` is
+ * the specific tier name (e.g. "opus", "fable") that triggered the downgrade,
+ * when the adapter can identify it — optional so providers/callers that don't
+ * supply it (OpenAI, or tests predating this field) stay unaffected; consumers
+ * that key off a tier (`notifyModelFallback`'s de-dupe window) fall back to
+ * their previous heuristic when it's absent.
+ */
+export interface ModelFallback {
+    body: string;
+    fromModel: string;
+    toModel: string;
+    fromTier?: string;
+}
+/**
+ * Reactive-fallback plan returned from a rejected (429) response whose headers
+ * indicate a MODEL-TIER cap (not an account-wide limit). `tier` names the
+ * limited tier (e.g. "opus", "fable") and `resetAt` (epoch ms) is when it
+ * recovers — persisted as `PoolAccount.modelCooldownsUntil[tier]` so subsequent
+ * requests for that tier avoid the account without paying a rejected
+ * round-trip. `fallback` is the downgraded body the fetch loop adopts once the
+ * WHOLE pool proves limited for the tier.
+ */
+export interface ReactiveModelFallback {
+    tier: string;
+    resetAt: number;
+    fallback: ModelFallback;
+}
+/**
+ * A provider adapter encapsulates everything provider-specific: OAuth, request
+ * shaping (headers/body/url transforms), usage parsing, and error classification.
+ * The scheduler, pool store, and load-balanced fetch are all provider-agnostic and
+ * drive adapters through this interface.
+ */
+export interface ProviderAdapter {
+    /** opencode provider id, e.g. "anthropic" | "openai". */
+    readonly id: string;
+    /** Begin an authorization-code (PKCE) flow. */
+    authorize(): Promise<AuthorizeRequest>;
+    /** Exchange a pasted code/URL for tokens. Returns null on failure. */
+    exchange(input: string, verifier: string, redirectUri: string, state: string): Promise<TokenSet | null>;
+    /** Refresh an access token. Throws on failure (callers handle invalid_grant). */
+    refresh(refreshToken: string): Promise<TokenSet>;
+    /** Set auth + provider headers on an outgoing request for the chosen account. */
+    applyAuth(headers: Headers, account: PoolAccount): void;
+    /** Optionally rewrite the request URL (e.g. add ?beta=true, swap base URL). */
+    transformUrl(input: FetchInput): FetchInput;
+    /** Optionally rewrite a string request body (system-prompt spoof, tool prefixing). */
+    transformBody(body: string): string;
+    /** Optionally wrap the response (e.g. strip tool prefixes from the stream). */
+    transformResponse(response: Response): Response;
+    /**
+     * Parse usage from a normal inference response's headers (free, passive).
+     * Deliberately takes NO timestamp: the capture time is stamped downstream by
+     * `applyUsagePartial` (see the doc comments in each provider's usage.ts).
+     */
+    parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
+    /** Poll a dedicated usage endpoint for authoritative quota, if one exists. */
+    fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;
+    /** Classify an HTTP status for rotation decisions. */
+    classifyError(status: number): ErrorClass;
+    /**
+     * The model TIER `body` asks for (the `modelCooldownsUntil` key the fetch
+     * loop consults BEFORE sending, to steer the request onto an account with
+     * tier headroom), or null when the body has no recognizable tier. Absent on
+     * providers without per-tier caps (OpenAI) — the fetch loop treats an absent
+     * hook as "no tier logic".
+     */
+    requestModelTier?(body: string): string | null;
+    /**
+     * Pure body downgrade: rewrite `body`'s model ONE RUNG DOWN the fallback
+     * ladder — the best model of the next family below, chosen from `models`
+     * (the provider's catalog, e.g. opencode's configured model list) — or null
+     * when disabled / not downgradable. The fetch loop adopts it when EVERY
+     * candidate account is limited for the current body's tier — so the
+     * downgraded request can then reuse any of them, preferably the session's
+     * pinned account (keeping its prompt cache). Each call descends at least
+     * one family, so repeated adoption terminates.
+     */
+    planModelFallback?(body: string, models: readonly string[]): ModelFallback | null;
+    /**
+     * REACTIVE classification (post-429): when a rejected response's headers
+     * indicate a MODEL-TIER cap (not account-wide) that `body`'s model can fall
+     * down the ladder from, return the tier + its `resetAt` to persist and the
+     * downgraded body. null = treat the 429 as a normal account rotation.
+     */
+    planReactiveFallback?(res: Response, body: string, now: number, models: readonly string[]): ReactiveModelFallback | null;
+}

package/dist/providers/usage-headers.d.ts

@@ -0,0 +1,55 @@
+import type { UsageSnapshot, UsageWindow } from '../types';
+/**
+ * Header names + scale for one provider's hourly/weekly rate-limit header pair.
+ * `divisor` maps the utilization header onto the normalized 0..1 fraction:
+ * 1 when the header already IS a fraction (Anthropic), 100 when it is a
+ * percent (Codex).
+ */
+export interface WindowPairHeaderSpec {
+    hourlyUtil: string;
+    hourlyReset: string;
+    weeklyUtil: string;
+    weeklyReset: string;
+    divisor: number;
+}
+/**
+ * Parse an hourly/weekly usage pair from response headers (free, on every
+ * response). Shared by both providers — the parse is structurally identical,
+ * only the header names and the utilization scale (`spec`) differ.
+ *
+ * Deliberately NO `capturedAt` here: `applyUsagePartial` (fetch.ts) stamps its
+ * own timestamp, and ONLY when a weekly window arrived — the staleness gate
+ * `refreshUsageInBackground` relies on. A parser-side stamp would be dead data
+ * at best and, if a future consumer trusted it, would resurrect the
+ * weekly-less-partial-marks-fresh bug locked by plugin.test.ts.
+ *
+ * Returns null when no utilization header is present, AND when headers were
+ * present but NEITHER window parsed (e.g. a malformed utilization value) — the
+ * contract consumers gate on (`if (partial)`) is "null = nothing usable",
+ * never a truthy empty `{}`.
+ */
+export declare function parseWindowPairHeaders(headers: Headers, spec: WindowPairHeaderSpec): Partial<UsageSnapshot> | null;
+/**
+ * Build a single `UsageWindow` from ONE raw usage-endpoint window, sharing the
+ * three-step contract both providers' endpoint parsers need — only reached
+ * AFTER the caller's own shape guard confirmed the response body is
+ * recognizably the usage-endpoint shape (a genuinely broken/foreign body
+ * never reaches here; the caller discards the whole poll instead):
+ *
+ *   - `w` absent (null/undefined): the server is deliberately reporting NO
+ *     usage recorded in that window (e.g. right after an out-of-band quota
+ *     reset wipes the record, or an idle account past the window) — a TRUE
+ *     0%, not "unknown". Synthesize a zero window (`resetAt` 0 = no reset
+ *     scheduled yet) so dashboards render "0%" instead of "-" ("-" stays
+ *     reserved for never-polled accounts). Scoring is unaffected either way:
+ *     `utilOf`/`weeklyUrgency` already read a missing window as 0.
+ *   - `w` present but its utilization field is missing/non-finite: unusable —
+ *     return `null` (NOT 0%) so the scheduler never treats a malformed
+ *     response as "full headroom" and ranks the account first.
+ *   - otherwise: `clamp01(util / divisor)` plus the provider's own reset
+ *     parser (`resetOf`) — the one piece that genuinely differs between
+ *     providers (Anthropic's ISO/epoch-seconds/epoch-ms heuristic vs OpenAI's
+ *     plain-seconds `secondsToMs`), so it stays a caller-supplied callback
+ *     rather than something this helper tries to unify too.
+ */
+export declare function endpointWindowFrom<W>(w: W | null | undefined, utilOf: (w: W) => unknown, divisor: number, resetOf: (w: W) => number): UsageWindow | null;

package/dist/providers/usage-http.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared HTTP shell for the provider usage endpoints (Anthropic `/usage`,
+ * OpenAI `/wham/usage`): GET with a timeout, null on ANY failure — network
+ * throw/timeout, non-ok status (body cancelled so the connection is released),
+ * or a 200 whose body is not JSON. Providers keep only their own headers,
+ * shape guards, and window mapping; the transport contract lives here ONCE.
+ */
+export declare function fetchUsageJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;

package/dist/refresh.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderAdapter } from './providers/types';
+import type { PoolAccount } from './types';
+export declare function needsRefresh(account: PoolAccount, now: number): boolean;
+/**
+ * Ensure the account has a fresh access token, refreshing if needed. The rotated
+ * refresh token is persisted immediately. On a genuine invalid_grant (the current
+ * token was revoked) the account is marked disabled and the error rethrown; a token
+ * merely superseded by a concurrent refresh is adopted, not disabled.
+ *
+ * Mutates the passed `account` in place so the caller sees the new token. Concurrent
+ * callers that reuse the in-flight refresh have their OWN local objects updated too.
+ */
+export declare function ensureAccessToken(adapter: ProviderAdapter, account: PoolAccount, now: number): Promise<string>;

package/dist/scheduler/config.d.ts

@@ -0,0 +1,46 @@
+import { type ScoreConfig } from './score-core';
+/**
+ * Tunable parameters for the account scheduler. All overridable via env vars. Extends
+ * the scoring knobs (`ScoreConfig`, the single source shared with the TUI view) with the
+ * session/migration parameters that only the server scheduler needs.
+ */
+export interface SchedulerConfig extends ScoreConfig {
+    /** Session->account assignments older than this (ms) are pruned. */
+    sessionTtlMs: number;
+    /**
+     * Cost gate for NON-forced switches (proactive `migrateAt` and `drainMigrate`):
+     * only switch when the outgoing request body is <= this many bytes, so a large
+     * conversation isn't re-sent onto a fresh account (which has no prompt cache and
+     * would burn a big chunk of its quota in one shot). <= 0 disables the gate, i.e.
+     * always allow the switch. Forced switches (hard exhaustion) ignore this gate;
+     * so does a PROACTIVE switch when the pin is within `IMMINENT_EXHAUSTION_BAND` of
+     * hard exhaustion (see select.ts) — a forced, still-ungated switch is coming next
+     * turn anyway and the re-sent conversation only grows, so moving now is cheaper.
+     * Drain switches always stay byte-gated.
+     */
+    cheapSwitchMaxBytes: number;
+    /**
+     * Allow migrating a still-healthy session to drain another account whose weekly
+     * window is about to reset (use-it-or-lose-it). Off by default — when off, a
+     * healthy session only ever leaves on the proactive/forced thresholds above.
+     */
+    drainMigrate: boolean;
+    /**
+     * When drainMigrate is on, the candidate account's weekly urgency must exceed the
+     * pinned account's by at least this factor to justify breaking session affinity.
+     */
+    drainMigrateMargin: number;
+    /**
+     * Max wall-clock time (ms) a single request may BLOCK waiting for the pool to recover
+     * when EVERY account is rate-limited (a 429/402 `account`-class cooldown). Rather than
+     * failing the turn abruptly, the load-balanced fetch sleeps until the soonest account's
+     * cooldown expires (honoring `Retry-After`) — bounded by this budget — then retries. A
+     * client abort (opencode cancelling the turn) interrupts the wait immediately. Must
+     * exceed `ACCOUNT_COOLDOWN_MS` (5 min) to cover a 429 that carries no `Retry-After`.
+     * <= 0 disables waiting (fail fast, the old behavior).
+     */
+    maxWaitMs: number;
+}
+export declare const DEFAULT_CONFIG: SchedulerConfig;
+/** Read overrides from env (OPENCODE_AUTH_LB_*), falling back to defaults. */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): SchedulerConfig;

package/dist/scheduler/score-core.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Pure account-scoring core — the SINGLE SOURCE OF TRUTH for how the load balancer
+ * ranks accounts. Imported by the server scheduler AND the standalone TUI view, which
+ * loads a byte-identical copy installed alongside it
+ * (`tui/auth-load-balancer-scoring.ts`, kept in sync by a build step + a test). Keeping
+ * the formula in one place means the dashboard's ranking can never silently drift from
+ * what the scheduler actually picks (which it once did, as duplicated copies).
+ *
+ * This module MUST stay dependency-free (only `process.env`) so the TUI view can load a
+ * single copied file without resolving the rest of `src/`.
+ */
+/** Tunable scoring knobs (the subset of the scheduler config that affects ranking). */
+export interface ScoreConfig {
+    /**
+     * How much the 5h-window headroom modulates the weekly-urgency score, in [0,1].
+     * 0 = ignore the 5h window; 1 = an account with no 5h headroom scores 0. Applied
+     * multiplicatively so it de-rates within the weekly ordering but never flips it.
+     */
+    hourlyInfluence: number;
+    /** Floor for time-until-reset (ms). Caps how large urgency can grow near a reset. */
+    minResetMs: number;
+    /** Baseline horizon (ms) used when an account's weekly reset time is unknown/stale. */
+    weekWindowMs: number;
+    /**
+     * Hard exhaustion: utilization >= this excludes the account entirely while others
+     * have headroom, and forces a pinned session off it regardless of switch cost.
+     */
+    exhaustedAt: number;
+    /**
+     * Soft threshold for the SHORT 5h window: proactively migrate a pinned session once
+     * its 5h utilization crosses this — before it hard-exhausts at `exhaustedAt`. Must be
+     * < exhaustedAt. (The WEEKLY window migrates at the higher `weeklyDrainTarget`.)
+     */
+    migrateAt: number;
+    /**
+     * Weekly drain target (default 0.98): scoring treats weekly quota as "fully drained"
+     * at this utilization (the account stops being favored past it), and a pinned session
+     * proactively migrates once its WEEKLY util crosses it — so perishable weekly quota is
+     * drained close to full before the window resets. In (migrateAt, exhaustedAt].
+     */
+    weeklyDrainTarget: number;
+}
+/** A single rate-limit window slice the scoring reads. */
+export interface ScoreWindow {
+    utilization: number;
+    resetAt: number;
+}
+/**
+ * The slice of an account the scoring reads. The server's full `PoolAccount` and the
+ * TUI's parsed-pool account both satisfy this (the TUI normalizes its looser JSON into
+ * this shape before scoring).
+ */
+export interface ScoreAccount {
+    usage: {
+        hourly: ScoreWindow | null;
+        weekly: ScoreWindow | null;
+    };
+    cooldownUntil: number;
+    disabledReason: string | null;
+}
+/**
+ * Weekly windows repeat on FIXED per-account anchors every 7 days (see
+ * usage-merge.ts). Exported so `usage-merge.ts` (an ordinary `src/` file with
+ * no dependency-free constraint) can import this single source instead of
+ * computing the same 604800000ms constant independently — `score-core.ts`
+ * itself still imports nothing, so the TUI's byte-identical copy stays
+ * dependency-free.
+ */
+export declare const WEEK_MS: number;
+/** Scoring-config defaults (the scoring subset of the scheduler's DEFAULT_CONFIG). */
+export declare const SCORE_DEFAULTS: ScoreConfig;
+/**
+ * Parse one numeric env override: missing/empty → default, non-finite → default.
+ * The SINGLE parsing contract for every numeric `OPENCODE_AUTH_LB_*` knob — shared
+ * by `loadScoreConfig` below and the server-only `loadConfig` in
+ * `src/scheduler/config.ts`, so the two loaders can never silently diverge.
+ */
+export declare function readEnvNumber(env: Record<string, string | undefined>, key: string, dflt: number): number;
+/** Read scoring overrides from env (OPENCODE_AUTH_LB_*), falling back to SCORE_DEFAULTS. */
+export declare function loadScoreConfig(env?: Record<string, string | undefined>): ScoreConfig;
+/**
+ * Effective utilization of a window RIGHT NOW (0..1). A missing window — or one that has
+ * already reset (see `isWindowExpired`) — contributes 0, so a stale 100% left over from
+ * an elapsed window never makes an account look busy or exhausted (which would exclude it
+ * from selection, so it would never be picked, never re-polled, and stay "full" forever).
+ */
+export declare function utilOf(window: ScoreWindow | null, now: number): number;
+/**
+ * Effective utilization for DISPLAY: `null` when there is no window (dashboards render
+ * "-"), `0` once the window has reset (the stale stored value is discarded → "0%"),
+ * otherwise the stored utilization. Mirrors `utilOf`'s expiry rule but keeps the
+ * unknown-vs-zero distinction the dashboards need ("-" for no data, "0%" for a freshly
+ * reset window with full headroom).
+ */
+export declare function displayUtil(window: ScoreWindow | null, now: number): number | null;
+/** The busiest window's utilization right now (whichever of 5h / weekly is higher). */
+export declare function maxUtil(account: ScoreAccount, now: number): number;
+/** An account is exhausted when ANY still-live window is at/over the exhaustion threshold. */
+export declare function isExhausted(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
+/** Available = not disabled, not in cooldown, and not exhausted. */
+export declare function isAvailable(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
+/**
+ * Weekly "urgency" — how perishable an account's remaining weekly quota is. It favors
+ * draining the SOONEST-resetting account first (earliest-deadline-first), because unused
+ * weekly quota is LOST at the reset:
+ *
+ *   drainable = max(0, weeklyDrainTarget - weeklyUtil)   // quota left to safely burn
+ *   urgency   = drainable / (daysToReset + cushion)^2
+ *
+ * The SQUARED time term is the key: it approximates the cost of DELAYING — as a reset
+ * nears, the drain rate needed to avoid waste worsens nonlinearly, so a near-reset
+ * account outranks one that merely has more quota left but resets far away (which is what
+ * `remaining / time` failed to do). `drainable` caps the chase at `weeklyDrainTarget`
+ * (stop favoring an account near the top of its window) and the cushion prevents a blow-up
+ * at the reset instant.
+ *
+ * Imperfect reset metadata splits in three:
+ *  - Window PRESENT but `resetAt === 0` (utilization known, anchor unknown — the
+ *    post-quota-reset shape): weekly resets are FIXED per-account anchors, so
+ *    "unknown" does NOT imply "a full window away" — it may be hours away, wasting a
+ *    refillable budget every idle hour. Assume the reset is IMMINENT (`minResetMs`)
+ *    so the account is ranked FIRST and serves one request ASAP; that response's
+ *    headers reveal the real anchor and the score self-corrects immediately.
+ *    (`drainable` still gates this: an unknown-anchor account with no headroom
+ *    scores 0, so probing never routes to an exhausted account.)
+ *  - Window PRESENT with an ELAPSED anchor (`resetAt` in the past — e.g. an idle
+ *    account behind a failing usage endpoint): because the anchor is FIXED and
+ *    repeats every 7 days, the TRUE next reset is `WEEK_MS - (elapsed % WEEK_MS)`
+ *    away — roll it forward (same model as `rollWeeklyAnchorForward` in
+ *    usage-merge.ts, inlined here to keep score-core dependency-free). An anchor
+ *    that lapsed 6 days ago really resets in ~1 day and must rank accordingly,
+ *    not as "a full window away".
+ *  - Window MISSING entirely (never polled — utilization unknown too): keep the
+ *    conservative full-window baseline. The free usage-endpoint poll resolves this
+ *    case within seconds without routing any traffic to it.
+ */
+export declare function weeklyUrgency(account: ScoreAccount, cfg: ScoreConfig, now: number): number;
+/**
+ * Score one candidate account (higher is better):
+ *   score = weeklyUrgency * (1 - hourlyInfluence * hourlyPressure)
+ *
+ * The 5h window is only a SAFETY de-rate (avoid a short-window hard limit), NOT a quota
+ * objective — and it is RESET-AWARE: `hourlyPressure = hourlyUtil * (msToReset / 5h)`, so
+ * an account whose 5h window is busy but resets in minutes is barely penalized (its
+ * short-term pressure is about to clear), letting the perishable weekly urgency drive the
+ * choice. An unknown 5h reset is treated as a full window (full penalty).
+ */
+export declare function scoreAccount(account: ScoreAccount, cfg: ScoreConfig, now: number): number;
+/**
+ * Sort comparator shared by `src/status.ts` and the TUI sidebar ranking pipeline, so the
+ * dashboard's *ordering* rule can never silently drift from what the server displays —
+ * the same single-source guarantee `scoreAccount` provides for the *formula*. Both
+ * pipelines map each account into `{ available, score, weeklyUtil }` (the per-pipeline
+ * `weeklyUtil` field is computed locally — `src/status.ts` uses the raw stored value to
+ * keep tie-breaking deterministic for cooling-down accounts, the TUI uses `utilOf` to
+ * discard a window that already reset) and pass that shape here:
+ *
+ *   - available accounts come first (they're the only ones the scheduler will pick);
+ *   - among available accounts, higher `score` wins (matches `selectAccount`'s pick);
+ *   - among unavailable accounts, lower `weeklyUtil` wins — the "least bad cooling-down
+ *     account" surfaces first so a forced fall-through stays predictable.
+ */
+export declare function compareRanked<T extends {
+    available: boolean;
+    score: number;
+    weeklyUtil: number;
+}>(x: T, y: T): number;

package/dist/scheduler/select.d.ts

@@ -0,0 +1,41 @@
+import type { PoolAccount, PoolFile } from '../types';
+import { type SchedulerConfig } from './config';
+export interface Selection {
+    account: PoolAccount;
+    /** true when every account was exhausted/cooling-down and we picked the least-bad one. */
+    degraded: boolean;
+    /** true when the account came from this session's existing assignment (no switch). */
+    sticky: boolean;
+}
+/**
+ * Pick the best account for a provider by weekly urgency.
+ *
+ * 1. Restrict to the provider's non-disabled accounts, minus `exclude` (already
+ *    tried this request).
+ * 2. Prefer the subset that is currently available (not exhausted / cooling down).
+ * 3. Among those, pick the highest urgency score.
+ * 4. If none are available, fall back to the least-bad account (lowest weekly
+ *    utilization) and flag the selection as `degraded`.
+ *
+ * Returns null when the provider has no usable account left.
+ */
+export declare function selectAccount(accounts: PoolAccount[], providerID: string, now: number, cfg?: SchedulerConfig, exclude?: ReadonlySet<string>): Selection | null;
+/**
+ * Session-aware selection. Balances prompt-cache stickiness against headroom safety
+ * and quota perishability:
+ *
+ *  - No pin / pin excluded / pin unavailable (cooldown / disabled / hard-exhausted at
+ *    `exhaustedAt`)  -> FORCED switch to the best urgency pick.
+ *  - Pin healthy but a NON-forced switch is worthwhile AND it's a cheap moment
+ *    (small `requestBytes`):
+ *      (a) proactive: pin crossed the soft `migrateAt` (~95%) and another account has
+ *          more headroom -> move before slamming into the 100% wall (subagent safety);
+ *      (b) drain (opt-in `drainMigrate`): another account's weekly reset is imminent
+ *          and its urgency dominates the pin's by `drainMigrateMargin` -> switch to
+ *          drain that use-it-or-lose-it quota.
+ *  - Otherwise keep the pin (sticky), preserving its prompt cache.
+ *
+ * Forced switches ignore the cost gate; proactive/drain switches honor it so a large
+ * conversation isn't re-sent onto a fresh account all at once.
+ */
+export declare function selectForSession(pool: PoolFile, providerID: string, sessionKey: string | null, now: number, cfg?: SchedulerConfig, exclude?: ReadonlySet<string>, requestBytes?: number | (() => number)): Selection | null;

package/dist/session.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Header carrying opencode's session id. Injected by the plugin's `chat.headers`
+ * hook (which has the real sessionID) and read back here in the load-balanced
+ * fetch. Stripped before the request leaves for the provider.
+ */
+export declare const SESSION_HEADER = "x-allb-session";
+/**
+ * Derive a stable key identifying the conversation a request belongs to.
+ *
+ * Prefers the real opencode session id (via the SESSION_HEADER). Falls back to a
+ * hash of the request's stable prefix (system prompt + first user message), which
+ * is constant across the turns of one conversation. Returns null when neither is
+ * available (selection then proceeds without affinity).
+ */
+export declare function deriveSessionKey(headers: Headers, body: string | undefined): string | null;

package/dist/status.d.ts

@@ -0,0 +1,55 @@
+import { type SchedulerConfig } from './scheduler/config';
+import type { PoolFile } from './types';
+interface AccountStatus {
+    id: string;
+    label: string;
+    weeklyUtil: number | null;
+    hourlyUtil: number | null;
+    weeklyResetAt: number;
+    available: boolean;
+    cooldownUntil: number;
+    /** tier name → epoch ms until that model tier's cap resets (empty = none). */
+    modelCooldownsUntil: Record<string, number>;
+    disabledReason: string | null;
+    /** The account that most recently served a request for this provider. */
+    current: boolean;
+    /** 1 = next candidate the scheduler would pick. */
+    rank: number;
+}
+interface ProviderStatus {
+    providerID: string;
+    accounts: AccountStatus[];
+}
+/**
+ * Build the ranked status model: per provider, the candidate accounts sorted in
+ * the order the scheduler would pick them (available accounts by urgency score,
+ * then unavailable ones by weekly utilization). Mirrors `selectAccount`'s ordering.
+ */
+export declare function buildStatus(pool: PoolFile, now: number, cfg?: SchedulerConfig): ProviderStatus[];
+/** Read the live pool and build its ranked status. */
+export declare function readStatus(now?: number, cfg?: SchedulerConfig): Promise<ProviderStatus[]>;
+/**
+ * Render a utilization as `"45%"` (or `"-"` for null/undefined). Shared with
+ * `notify.ts` so the dashboard, the `auth_lb_status` tool, and the switch
+ * toast cannot silently disagree on the same account's percentage rounding.
+ * `tui/auth-load-balancer-tui.logic.ts` keeps its own copy
+ * (the TUI runtime cannot import `src/`).
+ */
+export declare function pct(u: number | null | undefined): string;
+/**
+ * Approximate on-screen terminal width of a string, treating common East-Asian
+ * "wide" characters (Hangul, CJK Unified Ideographs + Extension blocks,
+ * Hiragana/Katakana, fullwidth forms) as 2 columns and everything else as 1.
+ * Account labels are user-editable free-form text (rename tool / TUI / a
+ * hand-edited pool file), and this project's own stated locale is `ko-KR` —
+ * a CJK/Hangul label is plausible, and `.length` (UTF-16 code units) undercounts
+ * each such character by one column, breaking `renderStatus`'s table alignment.
+ * Not a full Unicode-grapheme-cluster/emoji-aware implementation — a pragmatic,
+ * dependency-free improvement over the previous zero handling for the common
+ * CJK case. Degenerates to `.length` for pure-ASCII input.
+ */
+export declare function displayWidth(s: string): number;
+export declare function providerName(providerID: string): string;
+/** Render the status model as a compact text dashboard (for tools/commands/CLI). */
+export declare function renderStatus(providers: ProviderStatus[], now?: number): string;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Provider-agnostic data model shared by the scheduler, pool store, and adapters.
+ *
+ * Both Anthropic and OpenAI usage is normalized into the same shape so a single
+ * scheduler can rank accounts regardless of provider.
+ */
+/** A single rate-limit window. utilization in [0,1]; resetAt is epoch ms (0 = unknown). */
+export interface UsageWindow {
+    utilization: number;
+    resetAt: number;
+}
+/** Normalized usage snapshot for one account. */
+export interface UsageSnapshot {
+    /** Short rolling window (~5h for both Anthropic and Codex). */
+    hourly: UsageWindow | null;
+    /** Weekly (7-day rolling) window — the PRIMARY scheduling signal. */
+    weekly: UsageWindow | null;
+    /**
+     * epoch ms when the WEEKLY window was last captured (0 = never). Deliberately
+     * weekly-scoped: this is the staleness gate for the usage-endpoint re-poll
+     * (`refreshUsageInBackground`), and weekly is the primary signal that poll
+     * backfills — a response that updates only hourly must not mark the
+     * snapshot fresh, or an out-of-band weekly reset is never picked up.
+     */
+    capturedAt: number;
+}
+export declare function emptyUsage(): UsageSnapshot;
+/** Result of an OAuth authorization-code exchange or refresh. */
+export interface TokenSet {
+    access: string;
+    refresh: string;
+    /** epoch ms expiry of the access token. */
+    expires: number;
+    /** Provider account id (e.g. chatgpt-account-id), when present. */
+    accountId?: string;
+}
+/** One pooled credential. */
+export interface PoolAccount {
+    /** Stable internal id (uuid). */
+    id: string;
+    /** opencode provider id, e.g. "anthropic" | "openai". */
+    providerID: string;
+    /** User-facing label (email / nickname). Editable in the pool file. */
+    label: string;
+    access: string;
+    refresh: string;
+    /** Access-token expiry, epoch ms. */
+    expires: number;
+    /**
+     * Monotonic token-rotation generation. Bumped on every successful refresh so a
+     * cross-process refresher that lost the single-use-token race can tell its token
+     * was superseded — and adopt the winner's token instead of permanently disabling
+     * a now-valid account. Absent on legacy pool files (read as 0).
+     */
+    tokenGen?: number;
+    /** Provider account id (e.g. chatgpt-account-id), or null. */
+    accountId: string | null;
+    usage: UsageSnapshot;
+    /** epoch ms; the account is skipped until this time. 0 = no cooldown. */
+    cooldownUntil: number;
+    /**
+     * Per MODEL-TIER cooldowns: tier name (e.g. "opus", "fable") → epoch ms until
+     * that tier's separate weekly cap resets. While an entry is `> now`, requests
+     * for that tier's models avoid this account (another account with tier
+     * headroom is preferred) and — when the WHOLE pool is tier-limited — are
+     * auto-downgraded to the fallback model (see
+     * `OPENCODE_AUTH_LB_ANTHROPIC_OPUS_FALLBACK_MODEL`) instead of cooling the
+     * account down: the account still serves every other model. Distinct from
+     * `cooldownUntil` (account-wide) and NOT a scheduling signal: scoring /
+     * `isAvailable` ignore it, so it never sidelines the account. Absent = no
+     * tier is known-exhausted. Anthropic-only; absent for OpenAI accounts.
+     */
+    modelCooldownsUntil?: Record<string, number>;
+    /**
+     * LEGACY (pre-tier-map) Opus-only cooldown. Folded into
+     * `modelCooldownsUntil.opus` and deleted by the pool-store normalizer on
+     * every read; never written anymore. Kept in the type so old pool files
+     * parse without a cast.
+     */
+    opusCooldownUntil?: number;
+    /** Non-null when the account needs manual re-login (e.g. revoked refresh token). */
+    disabledReason: string | null;
+}
+/** A conversation's sticky account assignment (preserves prompt cache across turns). */
+export interface SessionAssignment {
+    accountId: string;
+    updatedAt: number;
+}
+export interface PoolFile {
+    version: 1;
+    accounts: PoolAccount[];
+    /**
+     * providerID -> account that most recently served a request. Drives the ▶
+     * "in use" marker in the status tool/CLI and the TUI bottom bar/sidebar;
+     * written on every fetch success and by `primeInUse` at startup. Never read
+     * by scheduling.
+     */
+    lastSelected: Record<string, string>;
+    /** sessionKey -> assignment. Keeps a conversation pinned to one account. */
+    sessions: Record<string, SessionAssignment>;
+}

package/dist/usage-merge.d.ts

@@ -0,0 +1,23 @@
+import type { UsageWindow } from './types';
+/**
+ * Roll a FIXED weekly reset anchor forward to its next occurrence strictly after
+ * `now`. Weekly windows are anchored per account (verified live: Anthropic's
+ * promotional quota reset zeroed usage but the account's next reset stayed on
+ * its pre-reset anchor), so a reset time observed in the PAST still predicts
+ * every future reset — it repeats every 7 days. Returns 0 when there is no
+ * usable anchor (unknown stays unknown).
+ */
+export declare function rollWeeklyAnchorForward(anchor: number, now: number): number;
+/**
+ * Merge helper for the weekly window: when an incoming window LOST the reset
+ * time (`resetAt === 0`) but we have previously seen this account's anchor,
+ * keep the anchor (rolled forward past `now`) instead of downgrading to
+ * "unknown". This happens on every out-of-band quota reset — the usage
+ * endpoint reports `resets_at: null` until usage restarts, and a header
+ * response can carry utilization without its reset — and losing the anchor
+ * used to make the scheduler assume a full week of headroom for an account
+ * whose (fixed) reset could be hours away. Incoming utilization always wins;
+ * only the reset metadata is preserved. An incoming window that carries its
+ * own reset time is returned untouched (fresh server data beats memory).
+ */
+export declare function preserveWeeklyAnchor(incoming: UsageWindow | null, stored: UsageWindow | null | undefined, now: number): UsageWindow | null;