opencode-auth-load-balancer 0.2.2 → 0.4.0

package/dist/notify.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderRecovery } from './pending/recovery';
 import type { PoolAccount } from './types';
 /** The slice of the opencode SDK client we need to show a toast. */
 export interface ToastClient {
@@ -45,3 +46,10 @@ export declare function notifyOnSwitch(client: ToastClient, providerID: string,
  * toast never affects the request.
  */
 export declare function notifyModelFallback(client: ToastClient, providerID: string, account: PoolAccount, fromModel: string, toModel: string, fromTier?: string): Promise<void>;
+/** Announce a durable provider wait. Coordinator-level signatures dedupe it. */
+export declare function notifyPending(client: ToastClient, providerID: string, recovery: Extract<ProviderRecovery, {
+    state: 'quota-blocked';
+}>, now?: number): Promise<void>;
+export declare function notifyPendingResumed(client: ToastClient, providerID: string): Promise<void>;
+export declare function notifyPendingRestored(client: ToastClient, providerID: string, count: number): Promise<void>;
+export declare function notifyPendingRestoreError(client: ToastClient, providerID: string, messageID: string): Promise<void>;

package/dist/pending/coordinator.d.ts

@@ -0,0 +1,135 @@
+import type { LockHandle } from '../pool/lock';
+import type { ProviderAdapter } from '../providers/types';
+import type { SchedulerConfig } from '../scheduler/config';
+import type { PoolFile } from '../types';
+import { type ProviderRecovery } from './recovery';
+import type { PendingRef, PendingSchedule, PendingTurn } from './types';
+export type CapacityWaitResult = 'available' | 'unusable';
+interface RestoreUserMessage {
+    id: string;
+    sessionID: string;
+    role: 'user';
+    agent: string;
+    model: {
+        providerID: string;
+        modelID: string;
+    };
+    system?: string;
+    tools?: Record<string, boolean>;
+}
+interface RestoreAssistantMessage {
+    id: string;
+    sessionID: string;
+    role: 'assistant';
+    parentID: string;
+    finish?: string;
+    error?: unknown;
+}
+type RestoreMessage = RestoreUserMessage | RestoreAssistantMessage;
+interface RestoreResult<T> {
+    data?: T;
+    error?: unknown;
+    response?: {
+        status: number;
+    };
+}
+interface RestoreReadOptions {
+    path: {
+        id: string;
+        messageID: string;
+    };
+    query: {
+        directory: string;
+    };
+}
+interface RestoreSessionOptions {
+    path: {
+        id: string;
+    };
+    query: {
+        directory: string;
+    };
+}
+interface RestorePromptOptions extends RestoreSessionOptions {
+    body: {
+        messageID: string;
+        model: {
+            providerID: string;
+            modelID: string;
+        };
+        agent: string;
+        system?: string;
+        tools?: Record<string, boolean>;
+        parts: [];
+    };
+}
+export interface PendingRestoreClient {
+    session: {
+        message(options: RestoreReadOptions): Promise<RestoreResult<{
+            info: RestoreMessage;
+            parts: unknown[];
+        }>>;
+        messages(options: RestoreSessionOptions): Promise<RestoreResult<{
+            info: RestoreMessage;
+            parts: unknown[];
+        }[]>>;
+        prompt(options: RestorePromptOptions): Promise<RestoreResult<unknown>>;
+    };
+}
+export interface PendingCoordinatorDependencies {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    readPool(): Promise<PoolFile>;
+    refreshUsage(now: number): Promise<void>;
+    upsert(ref: PendingRef, schedule: PendingSchedule): Promise<PendingTurn>;
+    remove(ref: PendingRef | string): Promise<boolean>;
+    acquireLease(key: string): Promise<LockHandle>;
+    list(workspace: string, providerID?: string): Promise<PendingTurn[]>;
+    removeSession(workspace: string, sessionID: string): Promise<number>;
+    onPending(ref: PendingRef, recovery: Extract<ProviderRecovery, {
+        state: 'quota-blocked';
+    }>): Promise<void> | void;
+    onResumed(ref: PendingRef): Promise<void> | void;
+    onRestored(count: number): Promise<void> | void;
+    onRestoreError(ref: PendingRef, error: unknown): Promise<void> | void;
+}
+export interface PendingCoordinatorOptions {
+    workspace: string;
+    adapter: ProviderAdapter;
+    config: SchedulerConfig;
+    dependencies?: Partial<PendingCoordinatorDependencies>;
+}
+export declare class PendingCoordinator {
+    readonly workspace: string;
+    readonly providerID: string;
+    private readonly adapter;
+    private readonly config;
+    private readonly dependencies;
+    private readonly leases;
+    private readonly acquiring;
+    private readonly active;
+    private readonly restoring;
+    private readonly pendingToasts;
+    private disposing;
+    constructor(options: PendingCoordinatorOptions);
+    private ensureLease;
+    private releaseLease;
+    private notifyPending;
+    private clear;
+    waitForCapacity(ref: PendingRef, initial: Extract<ProviderRecovery, {
+        state: 'quota-blocked';
+    }>, outerSignal?: AbortSignal): Promise<CapacityWaitResult>;
+    /** Remove a completed/terminal turn and release any execution lease it owns. */
+    complete(ref: PendingRef): Promise<void>;
+    /** Explicit user cancellation removes durable state; shutdown preserves it. */
+    abort(ref: PendingRef): Promise<void>;
+    private restoreOnce;
+    private restoreWithRetry;
+    /** Restore this workspace/provider's durable references independently. */
+    restore(client: PendingRestoreClient): Promise<void>;
+    /** Remove all pending providers for a deleted session in this workspace. */
+    removeSession(sessionID: string): Promise<number>;
+    /** Mark shutdown before aborting sleepers so their abort path preserves rows. */
+    dispose(): Promise<void>;
+}
+export {};

package/dist/pending/lease.d.ts

@@ -0,0 +1,3 @@
+import { type LockHandle, type LockOptions } from '../pool/lock';
+export declare function pendingLeasePath(key: string): string;
+export declare function acquirePendingLease(key: string, options?: LockOptions): Promise<LockHandle>;

package/dist/pending/recovery.d.ts

@@ -0,0 +1,16 @@
+import type { ScoreConfig } from '../scheduler/score-core';
+import type { PoolAccount } from '../types';
+export type ProviderRecovery = {
+    state: 'available';
+} | {
+    state: 'quota-blocked';
+    nextCheckAt: number;
+    resumeAt: number | null;
+} | {
+    state: 'unusable';
+};
+/**
+ * Determine whether a provider can serve now, is provably blocked only by
+ * account-wide quota, or has no account that waiting for quota can repair.
+ */
+export declare function classifyProviderRecovery(accounts: readonly PoolAccount[], providerID: string, cfg: Pick<ScoreConfig, 'exhaustedAt'>, now: number, pollMs: number): ProviderRecovery;

package/dist/pending/store.d.ts

@@ -0,0 +1,12 @@
+import type { PendingFile, PendingRef, PendingSchedule, PendingTurn } from './types';
+export declare class PendingReadError extends Error {
+    readonly path: string;
+    readonly reason: unknown;
+    constructor(path: string, reason: unknown);
+}
+export declare function pendingKey(ref: PendingRef): string;
+export declare function readPending(): Promise<PendingFile>;
+export declare function upsertPending(ref: PendingRef, schedule: PendingSchedule): Promise<PendingTurn>;
+export declare function removePending(refOrKey: PendingRef | string): Promise<boolean>;
+export declare function removePendingSession(workspace: string, sessionID: string): Promise<number>;
+export declare function listPendingForWorkspace(workspace: string, providerID?: string): Promise<PendingTurn[]>;

package/dist/pending/types.d.ts

@@ -0,0 +1,23 @@
+export interface PendingRef {
+    workspace: string;
+    providerID: string;
+    sessionID: string;
+    messageID: string;
+}
+/** Durable scheduling metadata. Prompt content remains owned by OpenCode. */
+export interface PendingTurn extends PendingRef {
+    key: string;
+    createdAt: number;
+    updatedAt: number;
+    nextCheckAt: number;
+    resumeAt: number | null;
+}
+export interface PendingFile {
+    version: 1;
+    turns: PendingTurn[];
+}
+export interface PendingSchedule {
+    now: number;
+    nextCheckAt: number;
+    resumeAt: number | null;
+}

package/dist/pool/lock.d.ts

@@ -25,7 +25,7 @@ export interface LockOptions {
     /** Re-touch the held lock this often so a live holder never looks stale. */
     readonly heartbeatMs: number;
 }
-interface LockHandle {
+export interface LockHandle {
     release(): Promise<void>;
 }
 export declare class LockTimeoutError extends Error {
@@ -36,4 +36,3 @@ export declare class LockTimeoutError extends Error {
 export declare function acquireLock(lockDir: string, opts: LockOptions): Promise<LockHandle>;
 /** Run `fn` while holding `lockDir`, releasing it even if `fn` throws. */
 export declare function withLock<T>(lockDir: string, opts: LockOptions, fn: () => Promise<T>): Promise<T>;
-export {};

package/dist/pool/paths.d.ts

@@ -13,4 +13,15 @@ interface DataDirEnv {
 export declare function resolveDataDir(env: DataDirEnv, home: string): string;
 /** Path to the load-balancer's credential pool file. */
 export declare function poolFilePath(): string;
+/** Path to the reference-only durable pending-turn file. */
+export declare function pendingFilePath(): string;
+/**
+ * Path to the cached Claude Code version discovered from the npm registry
+ * (see `providers/anthropic/version.ts`). A THIRD file rather than a field in
+ * the pool: the pool's every read-modify-write takes a cross-process lock, and
+ * this cache is a best-effort, provider-owned scratch value that must never
+ * contend with — let alone fail — a credential/usage write. Same data dir and
+ * same env-keyed memo as the two files above.
+ */
+export declare function versionCacheFilePath(): string;
 export {};

package/dist/providers/anthropic/constants.d.ts

@@ -35,10 +35,15 @@ export declare const DEFAULT_FAMILY_ORDER: readonly string[];
 /** 429 header naming which rate-limit window is the binding constraint. */
 export declare const REPRESENTATIVE_CLAIM_HEADER = "anthropic-ratelimit-unified-representative-claim";
 /**
- * `representative-claim` values that name a MODEL-TIER window (a per-model
- * weekly/5h cap, e.g. `seven_day_opus`, `seven_day_fable`) rather than an
- * account-wide one (bare `five_hour` / `seven_day`). The capture group is the
- * tier name — the key of `PoolAccount.modelCooldownsUntil`.
+ * `representative-claim` values that name a TIER-scoped window (a per-model
+ * weekly/5h cap OR the premium/overage bucket — e.g. `seven_day_opus`,
+ * `seven_day_fable`, `seven_day_overage_included`) rather than a bare
+ * account-wide one (`five_hour` / `seven_day`). Used ONLY as a GATE by
+ * `planReactiveFallback`; the captured suffix is NOT the cooldown key. Anthropic
+ * emits non-model-family suffixes (`overage_included`) that no request's model
+ * family ever equals, so keying on the suffix records a dead
+ * `modelCooldownsUntil` entry the proactive skip can never consult — the cooldown
+ * is keyed by the REQUEST's model family instead (see `planReactiveFallback`).
  */
 export declare const MODEL_TIER_CLAIM_RE: RegExp;
 /** 429 header with the unix-seconds reset time of the binding window. */
@@ -48,15 +53,55 @@ export declare const OPENCODE_IDENTITY_PREFIX = "You are OpenCode";
 export declare const CLAUDE_CODE_IDENTITY = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
 export declare const CCH_SALT = "59cf53e54c78";
 export declare const CCH_POSITIONS: number[];
-export declare const CLAUDE_CODE_VERSION = "2.1.87";
 export declare const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
-/** User-Agent for /v1/messages (matches the reference plugin's validated value). */
-export declare const USER_AGENT = "claude-cli/2.1.87 (external, cli)";
 /**
- * User-Agent for the /api/oauth/usage endpoint. This endpoint hard-rejects
- * (429) requests whose UA is not `claude-code/<version>`.
+ * Version used when nothing better is known — the floor the resolver in
+ * `version.ts` never goes below.
+ *
+ * Anthropic GATES NEW MODELS ON THE CLIENT VERSION we report (in the
+ * `claude-cli/<version>` UA and the `cc_version=` billing header): requesting a
+ * too-new model with a too-old version is rejected outright with
+ * `{"error_code":"claude_code_version_too_old"}` — e.g. `claude-fable-5-1`
+ * requires ≥ 2.1.251. A hard-pinned constant therefore BREAKS on every future
+ * model launch, which is why the live value is resolved from the npm registry
+ * (`version.ts`) and this is only the offline floor.
+ *
+ * Verified against the real API: `claude-fable-5-1` returns 400
+ * (`claude_code_version_too_old`) at `2.1.87` and 200 at this value, using the
+ * SAME `CCH_SALT`/`CCH_POSITIONS` above — the fingerprint algorithm did not
+ * change across that range, so bumping the version string alone is sufficient.
+ * Keep this at a version confirmed to work; the resolver only ever moves UP
+ * from here.
  */
-export declare const USAGE_USER_AGENT = "claude-code/2.1.87";
+export declare const FALLBACK_CLAUDE_CODE_VERSION = "2.1.258";
+/**
+ * Pin the reported Claude Code version explicitly, bypassing BOTH the npm
+ * lookup and the `FALLBACK_CLAUDE_CODE_VERSION` floor — the escape hatch for
+ * the two directions the resolver cannot guess: pinning FORWARD to a version
+ * npm has not tagged `latest` yet, or pinning BACK (e.g. to reproduce this
+ * `claude_code_version_too_old` failure, or if a future release changes the
+ * `cch` fingerprint algorithm and the newest version starts 400ing).
+ */
+export declare const CLAUDE_CODE_VERSION_ENV = "OPENCODE_AUTH_LB_ANTHROPIC_CLAUDE_CODE_VERSION";
+/**
+ * npm dist-tags for the Claude Code CLI — `{"latest":"2.1.258",…}`, ~56 bytes.
+ * Deliberately NOT `/@anthropic-ai/claude-code/latest`, which returns the whole
+ * 3.3 KB version packument for the one field we read.
+ */
+export declare const CLAUDE_CODE_REGISTRY_URL = "https://registry.npmjs.org/-/package/@anthropic-ai%2Fclaude-code/dist-tags";
+/**
+ * How long a registry answer stays authoritative on disk. Claude Code ships
+ * roughly daily, and a stale-by-a-day version only matters on the day a new
+ * model launches — so a day-long TTL keeps startup network-free almost always
+ * while still converging well inside the window that matters.
+ */
+export declare const CLAUDE_CODE_VERSION_TTL_MS: number;
+/**
+ * Bound the registry lookup. Shorter than the 30 s OAuth/usage budgets because
+ * nothing waits on this: it runs fire-and-forget at startup and a miss simply
+ * leaves the previous (cached or fallback) version in place.
+ */
+export declare const REGISTRY_HTTP_TIMEOUT_MS = 10000;
 export declare const PARAGRAPH_REMOVAL_ANCHORS: string[];
 export declare const TEXT_REPLACEMENTS: {
     match: string;

package/dist/providers/anthropic/fallback.d.ts

@@ -40,7 +40,9 @@ export declare function resolveFallbackSetting(): FallbackSetting;
  * on a cheap condition (a stored tier cooldown or a response header) BEFORE
  * this parse.
  */
-export declare function downgradeModel(body: string, models: readonly string[]): ModelFallback | null;
+export declare function downgradeModel(body: string, models: readonly string[]): (ModelFallback & {
+    fromTier: string;
+}) | null;
 /**
  * REACTIVE: on a rejected response, when the binding limit is a MODEL-TIER cap
  * (`representative-claim: seven_day_<tier>` / `five_hour_<tier>`) and the sent

package/dist/providers/anthropic/version.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The version to report right now. Reads the env override on every call (like
+ * `resolveBaseUrl`/`poolFilePath` do for theirs) so a pin takes effect without
+ * a restart.
+ */
+export declare function claudeCodeVersion(): string;
+/** User-Agent for /v1/messages. */
+export declare function userAgent(): string;
+/**
+ * User-Agent for the /api/oauth/usage endpoint. That endpoint hard-rejects
+ * (429) requests whose UA is not `claude-code/<version>` — note the different
+ * product token and the absence of the ` (external, cli)` suffix.
+ */
+export declare function usageUserAgent(): string;
+/**
+ * Ask npm for the newest Claude Code, adopt it if newer, and persist the
+ * result. Best-effort throughout: a registry outage, a shape change, or an
+ * unwritable data dir all leave the in-memory version untouched and simply
+ * defer the next attempt to the next startup (the cache is written only on a
+ * usable answer, so a failure does NOT refresh the TTL).
+ */
+export declare function refreshClaudeCodeVersion(now: number): Promise<void>;
+/**
+ * Startup hook. Awaits only the LOCAL cache read — cheap, and enough to have
+ * the right version in hand before the loader returns the fetch — then leaves
+ * any registry round-trip running in the background so neither opencode's
+ * startup nor the first request ever blocks on npm.
+ */
+export declare function primeClaudeCodeVersion(now: number): Promise<void>;

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

@@ -1,16 +1,22 @@
 import type { PoolAccount, UsageSnapshot } from '../../types';
 /**
  * Parse usage from Codex response headers (x-codex-{primary,secondary}-*).
- * primary = ~5h window (hourly), secondary = weekly window. The parse itself
- * (null-short-circuit, "no capturedAt", "`{}` collapses to null") lives in the
- * shared `parseWindowPairHeaders` — only the header names and the percent
- * scale are Codex-specific.
+ * The historical default is primary = ~5h and secondary = weekly; when the
+ * primary-window-minutes header identifies a seven-day primary, swap the pair
+ * before using the shared parser (see `isWeeklyMinutes`). An absent/
+ * unparsable duration header keeps the historical default — `Number(null)` is
+ * 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.
  */
 export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
 /**
- * Poll GET /wham/usage for authoritative 5h (primary) + weekly (secondary)
- * utilization without consuming inference quota. Null on failure. 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.
+ * Poll GET /wham/usage for authoritative 5h + weekly utilization without
+ * consuming inference quota, assigning each returned window to its role BY
+ * DURATION (see `isWeeklyMinutes`) rather than by position. Null on failure.
+ * 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.
  */
 export declare function fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;

package/dist/providers/registry.d.ts

@@ -0,0 +1,26 @@
+import type { ProviderAdapter } from './types';
+/**
+ * Every provider adapter this plugin ships, in one place.
+ *
+ * The per-provider plugin exports in `index.ts` each own exactly ONE adapter
+ * (opencode registers an auth hook per provider), but the provider-agnostic
+ * surfaces — the usage-endpoint refresh and the `auth_lb_status` dashboard —
+ * must reach ALL of them. Without a shared registry those call sites
+ * hand-listed the pair and drifted: the request path only ever refreshed the
+ * adapter whose fetch it belonged to, so a provider you did not actively send
+ * requests to (e.g. Codex while you work in Claude) had NO refresh cycle at
+ * all after its startup seed and its usage froze for the whole opencode
+ * process lifetime. Adding a third provider now means editing this array only.
+ *
+ * `readonly` so a consumer cannot mutate the shared list; iteration order is
+ * irrelevant (each account is matched to its own adapter by `providerID`).
+ */
+export declare const ADAPTERS: readonly ProviderAdapter[];
+/**
+ * The adapter that owns `providerID`, or undefined for a pool row whose
+ * provider this build does not know (a hand-edited file, or a row left behind
+ * by a newer version). A linear scan, not a Map: the registry has a handful of
+ * entries and this runs per account on the request hot path, where building a
+ * Map per call would cost more than the scan it replaces.
+ */
+export declare function adapterFor(adapters: readonly ProviderAdapter[], providerID: string): ProviderAdapter | undefined;

package/dist/providers/types.d.ts

@@ -48,12 +48,16 @@ export interface ModelFallback {
 }
 /**
  * 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.
+ * indicate a MODEL-TIER cap (not an account-wide limit). `tier` is the REQUEST's
+ * own model family (e.g. "opus", "fable") — the exact key the fetch loop's
+ * proactive skip reads as `requestModelTier(body)` — NOT the raw claim suffix
+ * (Anthropic emits non-family suffixes like `overage_included` that no request
+ * ever maps to; keying on them recorded a dead `modelCooldownsUntil` entry the
+ * skip could never consult). `resetAt` (epoch ms) is when the tier 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;
@@ -93,6 +97,19 @@ export interface ProviderAdapter {
     fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;
     /** Classify an HTTP status for rotation decisions. */
     classifyError(status: number): ErrorClass;
+    /**
+     * One-time startup warm-up, awaited by the auth loader BEFORE it returns the
+     * load-balanced fetch — so anything a request's shaping depends on is in
+     * place before the first request is served. Anthropic uses it to resolve the
+     * Claude Code version it must claim (Anthropic gates new models on it; see
+     * `providers/anthropic/version.ts`); OpenAI leaves it unset, and the loader
+     * treats an absent hook as "nothing to warm up".
+     *
+     * MUST stay cheap and MUST NOT throw — it sits on opencode's startup path.
+     * Implementations do local I/O only and push anything network-bound into the
+     * background themselves.
+     */
+    prime?(now: number): Promise<void>;
     /**
      * The model TIER `body` asks for (the `modelCooldownsUntil` key the fetch
      * loop consults BEFORE sending, to steer the request onto an account with

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

@@ -1,8 +1,9 @@
 /**
- * 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.
+ * 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 fetchUsageJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;
+export declare function fetchJson<T>(url: string, headers: Record<string, string>, timeoutMs: number): Promise<T | null>;

package/dist/scheduler/select.d.ts

@@ -13,13 +13,16 @@ 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.
+ * 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.
  * 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;
+export declare function selectAccount(accounts: PoolAccount[], providerID: string, now: number, cfg?: SchedulerConfig, exclude?: ReadonlySet<string>, incumbentId?: string | null): Selection | null;
 /**
  * Session-aware selection. Balances prompt-cache stickiness against headroom safety
  * and quota perishability:

package/dist/session.d.ts

@@ -4,6 +4,8 @@
  * fetch. Stripped before the request leaves for the provider.
  */
 export declare const SESSION_HEADER = "x-allb-session";
+/** OpenCode user-message id paired with SESSION_HEADER for durable turn identity. */
+export declare const MESSAGE_HEADER = "x-allb-message";
 /**
  * Derive a stable key identifying the conversation a request belongs to.
  *

package/dist/status.d.ts

@@ -1,5 +1,6 @@
+import type { PendingTurn } from './pending/types';
 import { type SchedulerConfig } from './scheduler/config';
-import type { PoolFile } from './types';
+import { type PoolFile } from './types';
 interface AccountStatus {
     id: string;
     label: string;
@@ -50,6 +51,8 @@ export declare function pct(u: number | null | undefined): string;
  */
 export declare function displayWidth(s: string): number;
 export declare function providerName(providerID: string): string;
+/** Compact workspace-scoped pending summary appended by `auth_lb_status`. */
+export declare function renderPendingStatus(turns: readonly PendingTurn[], now?: number): 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

@@ -35,6 +35,7 @@ export interface TokenSet {
     accountId?: string;
 }
 /** One pooled credential. */
+export type CooldownKind = 'quota' | 'auth' | 'transient';
 export interface PoolAccount {
     /** Stable internal id (uuid). */
     id: string;
@@ -58,6 +59,8 @@ export interface PoolAccount {
     usage: UsageSnapshot;
     /** 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. */
+    cooldownKind?: CooldownKind;
     /**
      * 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
@@ -78,17 +81,71 @@ export interface PoolAccount {
      * parse without a cast.
      */
     opusCooldownUntil?: number;
-    /** Non-null when the account needs manual re-login (e.g. revoked refresh token). */
+    /**
+     * Non-null when the scheduler skips this account. Two sources, both gated by
+     * `isAvailable`: the automatic `invalid_grant: re-login required (…)` reason
+     * written on a revoked refresh token (`src/refresh.ts`), and the manual
+     * `MANUAL_DISABLED_REASON` sentinel written by the disable action (TUI menu /
+     * `auth_lb_disable` tool). The dashboards distinguish the two to render
+     * `disabled` (a user turned it off) vs `re-login` (needs a fresh OAuth login).
+     */
     disabledReason: string | null;
 }
+/**
+ * Sentinel `disabledReason` written by the MANUAL disable action (the TUI
+ * sidebar menu and the `auth_lb_disable` tool), distinct from the automatic
+ * `invalid_grant: re-login required (…)` reason `src/refresh.ts` writes when a
+ * refresh token is revoked. Both are non-null so `isAvailable` skips the
+ * account; the value is kept distinct only so the dashboards can render
+ * `disabled` (a user turned it off) rather than `re-login` (needs a fresh login).
+ */
+export declare const MANUAL_DISABLED_REASON = "manually disabled";
+/**
+ * Re-login intents expire after ten minutes. A bounded lifetime prevents an
+ * abandoned TUI OAuth flow from redirecting a later, unrelated provider login
+ * onto the account row that happened to be clicked earlier.
+ */
+export declare const RELOGIN_TTL_MS = 600000;
+export interface ReloginIntent {
+    /** `PoolAccount.id` the freshly exchanged tokens must land on. */
+    accountId: string;
+    /** Provider the re-login was started for; an intent for another provider is ignored. */
+    providerID: string;
+    /** epoch ms after which the intent is stale and dropped at the read boundary. */
+    expiresAt: number;
+}
 /** A conversation's sticky account assignment (preserves prompt cache across turns). */
 export interface SessionAssignment {
     accountId: string;
     updatedAt: number;
+    /**
+     * Set when THIS session's most recent successful request was served on an
+     * auto-downgraded fallback model (the requested model tier's weekly cap is
+     * exhausted pool-wide, so the request descended the fallback ladder). Read by
+     * the TUI bottom bar to PERSISTENTLY surface the degrade — the `onModelFallback`
+     * toast is transient and gone by the next turn, yet the session keeps running
+     * on the fallback model. `from`/`to` are the raw model ids (original requested
+     * model → served model), matching the toast wording. The whole session row is
+     * overwritten on every success, so the next request served on the requested
+     * model naturally clears this back to `undefined`.
+     */
+    fallback?: {
+        from: string;
+        to: string;
+    };
 }
 export interface PoolFile {
     version: 1;
     accounts: PoolAccount[];
+    /**
+     * Short-lived TUI → server handshake consumed by the first `addAccount` for
+     * this provider. It identifies the clicked pool row when a provider rotates
+     * refresh tokens and exposes no stable account id (Anthropic); without it a
+     * completed re-login appends a duplicate while leaving the revoked row
+     * behind. Absent in the steady state so `JSON.stringify` keeps the pool file
+     * compact.
+     */
+    relogin?: ReloginIntent;
     /**
      * providerID -> account that most recently served a request. Drives the ▶
      * "in use" marker in the status tool/CLI and the TUI bottom bar/sidebar;