opencode-auth-load-balancer 0.9.0 → 0.10.0

package/dist/providers/kimi/usage.d.ts

@@ -6,7 +6,7 @@ import type { PoolAccount, UsageSnapshot } from '../../types';
  * broken body keeps the last-known snapshot instead of reading as 0% used.
  */
 export declare function parseUsages(json: unknown, now: number): UsageSnapshot | null;
-/** `GET {baseUrl}/usages` — free, spends no quota. Null on any failure. */
+/** `GET {baseUrl}/usages`: surface 401 for OAuth recovery; other failures return null. */
 export declare function getUsages(baseUrl: string, key: string): Promise<unknown>;
 /** The adapter's `fetchUsage` for one deployment. */
 export declare function usageFetcher(baseUrl: string): (account: PoolAccount, now: number) => Promise<UsageSnapshot | null>;

package/dist/providers/openai/usage.d.ts

@@ -8,13 +8,16 @@ import type { PoolAccount, UsageSnapshot } from '../../types';
  * NaN, and every comparison against NaN is false. The parse itself (null-short-circuit,
  * "no capturedAt", "`{}` collapses to null") lives in the shared
  * `parseWindowPairHeaders` — only the header names, the percent scale, and
- * this role detection are Codex-specific.
+ * this role detection are Codex-specific. The credits headers
+ * (x-codex-credits-*) ride along, even on a response without windows.
  */
 export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
 /**
- * Poll GET /wham/usage for authoritative 5h + weekly utilization without
+ * Poll GET /wham/usage for authoritative 5h + weekly utilization (and the
+ * credits spent past them) without
  * consuming inference quota, assigning each returned window to its role BY
- * DURATION (see `isWeeklyMinutes`) rather than by position. Null on failure.
+ * DURATION (see `isWeeklyMinutes`) rather than by position. A 401 is surfaced
+ * for bounded OAuth recovery; other failures return null.
  * Sends the Codex CLI's `codex-cli` UA and the `chatgpt-account-id` (from the
  * stored id or, as a fallback, decoded from the access-token JWT) — required
  * for team/workspace accounts.

package/dist/providers/types.d.ts

@@ -151,6 +151,11 @@ export interface ProviderAdapter {
     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>;
+    /**
+     * The usage endpoint reports credits (Codex): a row whose credits are still
+     * unknown is polled even when its windows are fresh.
+     */
+    reportsCredits?: boolean;
     /** Classify an HTTP status for rotation decisions. */
     classifyError(status: number): ErrorClass;
     /**

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

@@ -1,9 +1,6 @@
-/**
- * Shared HTTP shell for the plugin's read-only JSON GETs — the provider usage
- * endpoints (Anthropic `/usage`, OpenAI `/wham/usage`) and the npm dist-tags
- * lookup behind `providers/anthropic/version.ts`. 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. Callers keep only
- * their own headers and shape guards; the transport contract lives here ONCE.
- */
 export declare function fetchJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;
+export declare class UsageAuthenticationError extends Error {
+    readonly status = 401;
+    constructor();
+}
+export declare function fetchUsageJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;

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

@@ -45,6 +45,13 @@ export interface ScoreWindow {
     utilization: number;
     resetAt: number;
 }
+/** Codex credits, which keep an account serving once its plan windows are exhausted. */
+export interface ScoreCredits {
+    hasCredits: boolean;
+    unlimited: boolean;
+    /** The credit spending cap is hit: the balance cannot be spent. */
+    limitReached?: boolean;
+}
 /**
  * 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
@@ -55,6 +62,7 @@ export interface ScoreAccount {
         hourly: ScoreWindow | null;
         weekly: ScoreWindow | null;
     };
+    credits?: ScoreCredits;
     cooldownUntil: number;
     disabledReason: string | null;
 }
@@ -97,7 +105,15 @@ export declare function displayUtil(window: ScoreWindow | null, now: number): nu
 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. */
+/**
+ * Whether credits keep the account serving past exhausted plan windows. Same test as
+ * Codex itself (`unlimited || has_credits`, the backend then bills the credits), unless
+ * the account's credit spending cap is hit.
+ */
+export declare function hasCreditHeadroom(account: ScoreAccount): boolean;
+/** Plan headroom, or credits to spend once the plan is exhausted. */
+export declare function hasHeadroom(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
+/** Available = not disabled, not in cooldown, and with plan or credit headroom. */
 export declare function isAvailable(account: ScoreAccount, cfg: ScoreConfig, now: number): boolean;
 /**
  * Weekly "urgency" — how perishable an account's remaining weekly quota is. It favors
@@ -150,18 +166,21 @@ export declare function scoreAccount(account: ScoreAccount, cfg: ScoreConfig, no
  * 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:
+ * pipelines map each account into `{ available, onCredits, 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 available accounts, plan headroom comes before serving on credits alone
+ *     (`onCredits`: credits cost money), then 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;
+    onCredits: boolean;
     score: number;
     weeklyUtil: number;
 }>(x: T, y: T): number;

package/dist/scheduler/select.d.ts

@@ -13,10 +13,13 @@ export interface Selection {
  * 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 — but KEEP the incumbent
- *    (`incumbentId`, the provider's current in-use account) when its score is
- *    within `INCUMBENT_HYSTERESIS` of the best, so near-equal scores don't churn
- *    the account and waste prompt cache.
+ * 3. Among those, prefer plan headroom over serving on credits alone (an
+ *    exhausted Codex account whose credits keep it usable — credits cost money,
+ *    plan quota is already paid for), then pick the highest urgency score — but
+ *    KEEP the incumbent (`incumbentId`, the provider's current in-use account)
+ *    when it is in that same group and its score is within
+ *    `INCUMBENT_HYSTERESIS` of the best, so near-equal scores don't churn the
+ *    account and waste prompt cache.
  * 4. If none are available, fall back to the least-bad account (lowest weekly
  *    utilization) and flag the selection as `degraded`.
  *

package/dist/status.d.ts

@@ -18,6 +18,8 @@ interface AccountStatus {
     warnings: string[];
     /** Why each lost login stopped working, printed under the table. */
     lostNotes: string[];
+    /** What credits leave once the plan is exhausted (`creditsText`); '' otherwise. */
+    credits: string;
     /** The account that most recently served a request for this provider. */
     current: boolean;
     /** 1 = next candidate the scheduler would pick. */

package/dist/types.d.ts

@@ -9,6 +9,18 @@ export interface UsageWindow {
     utilization: number;
     resetAt: number;
 }
+/**
+ * Codex credits: what a ChatGPT account spends once its plan's usage windows
+ * are exhausted. `balance` is the amount left, when the backend reports it;
+ * `limitReached` (`overage_limit_reached`) means the account's credit
+ * spending cap is hit, so the balance cannot be spent.
+ */
+export interface UsageCredits {
+    hasCredits: boolean;
+    unlimited: boolean;
+    balance?: number;
+    limitReached?: boolean;
+}
 /** Normalized usage snapshot for one account. */
 export interface UsageSnapshot {
     /** Short rolling window (~5h for both Anthropic and Codex). */
@@ -23,6 +35,11 @@ export interface UsageSnapshot {
      * snapshot fresh, or an out-of-band weekly reset is never picked up.
      */
     capturedAt: number;
+    /**
+     * Codex credits as just measured. Stored on the row (`PoolAccount.credits`),
+     * not here: versions before credits rebuild `usage` and would drop them.
+     */
+    credits?: UsageCredits;
 }
 export declare function emptyUsage(): UsageSnapshot;
 /** Result of an OAuth authorization-code exchange or refresh. */
@@ -142,6 +159,8 @@ export interface PoolAccount {
      */
     orgId?: string;
     usage: UsageSnapshot;
+    /** Codex credits, absent until the provider reports them. */
+    credits?: UsageCredits;
     /** epoch ms; the account is skipped until this time. 0 = no cooldown. */
     cooldownUntil: number;
     /** Why the active account-wide cooldown was written. Absent on legacy rows. */

package/dist/usage-merge.d.ts

@@ -1,4 +1,8 @@
-import type { UsageWindow } from './types';
+import { type ScoreConfig } from './scheduler/score-core';
+import type { PoolAccount, UsageWindow } from './types';
+export declare const MAX_TRANSIENT_COOLDOWN_MS: number;
+/** Call only after fresh usage was measured; cached headroom cannot disprove a later 429. */
+export declare function reconcileQuotaCooldown(account: PoolAccount, cfg: ScoreConfig, now: number): void;
 /**
  * Roll a FIXED weekly reset anchor forward to its next occurrence strictly after
  * `now`. Weekly windows are anchored per account (verified live: Anthropic's

package/dist/usage-poll.d.ts

@@ -0,0 +1,11 @@
+import { type LoopTimers } from './sync/loop';
+interface UsagePollDeps {
+    now?: () => number;
+    refresh?: (now: number) => Promise<void>;
+    timers?: LoopTimers;
+}
+export declare function startUsagePoll(deps?: UsagePollDeps): {
+    tick: () => Promise<void>;
+    dispose(): Promise<void>;
+};
+export {};

package/dist/usage-refresh.d.ts

@@ -1,18 +1,7 @@
 import type { ProviderAdapter } from './providers/types';
 import { type PoolFile } from './types';
 export declare const USAGE_REFRESH_TTL_MS: number;
-/**
- * Max lifetime of a TRANSIENT (non-quota) cooldown. fetch.ts cools a thrown
- * network error or a header-less 429/402 for at most `ACCOUNT_COOLDOWN_MS`
- * (5min) and an auth 401/403 for `AUTH_COOLDOWN_MS` (2min); ONLY a quota 429's
- * `Retry-After` writes a cooldown beyond this. So a cooldown whose remainder
- * still exceeds this bound is necessarily quota-derived — the one class that can
- * outlive its own usage window after an out-of-band reset (see the stale-cooldown
- * reconciliation below). Kept `=== ACCOUNT_COOLDOWN_MS` by a drift-guard test;
- * defined locally because importing it from fetch.ts (which imports THIS module)
- * would form a cycle.
- */
-export declare const MAX_TRANSIENT_COOLDOWN_MS: number;
+export { MAX_TRANSIENT_COOLDOWN_MS } from './usage-merge';
 /**
  * Test-only window into the module-private `lastPoll` throttle map. Never
  * imported by production code — only by usage-refresh tests that need to