dsh-plugin-subscriptions 0.5.2 → 0.5.3

package/lib/providers/grok.d.ts

@@ -7,8 +7,9 @@ import { LlmAdapter } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
 import type { FlowSpec } from '../auth/oauth-flow.js';
 import type { GrokSession } from '../auth/store.js';
+import type { PoolAdapter } from './pool.js';
 import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
-import { TokenManager } from './common.js';
+import { AccountTokenManager } from './accounts.js';
 import type { CatalogPersistence, DiscoveredModel, FetchFn, ModelEntry, ProviderUsage } from './common.js';
 export declare const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 export declare const GROK_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
@@ -93,9 +94,10 @@ type GrokCliModelMeta = Partial<Pick<DiscoveredModel, 'name' | 'description' | '
  * Fetch the CLI catalog and index its per-model metadata by model id.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation (pool-assembly timeout).
  * @returns model id → contributed metadata.
  */
-export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: FetchFn): Promise<Map<string, GrokCliModelMeta>>;
+export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: FetchFn, signal?: AbortSignal): Promise<Map<string, GrokCliModelMeta>>;
 /**
  * Fetch the live grok model list, enriched with the CLI catalog's per-model
  * metadata (display name, context window, reasoning efforts). The api.x.ai
@@ -109,14 +111,17 @@ export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: Fetc
  * @param onWarn - warning sink for a failed CLI catalog fetch.
  * @param previous - last-known catalog used to keep enrichment when the CLI
  *   catalog is down or omits a model.
+ * @param signal - caller cancellation (pool-assembly timeout).
  * @returns discovered chat models in endpoint order.
  */
-export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void, previous?: readonly DiscoveredModel[]): Promise<DiscoveredModel[]>;
+export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void, previous?: readonly DiscoveredModel[], signal?: AbortSignal): Promise<DiscoveredModel[]>;
 /** Constructor dependencies for {@link GrokAdapter}. */
 export interface GrokAdapterOptions {
     models: readonly ModelEntry[];
     streamIdleTimeoutMs: number;
-    tokens: TokenManager<GrokSession>;
+    tokens: AccountTokenManager<GrokSession>;
+    /** Late-bound pool facade (wired after adapter construction); pools list under their first member's provider. */
+    pool?: () => PoolAdapter | undefined;
     /** Whether to fetch the live catalog when logged in (false when config `models` overrides). */
     discovery: boolean;
     /** Warning sink for discovery failures that fall back to the static catalog. */
@@ -132,13 +137,23 @@ export interface GrokAdapterOptions {
 export declare class GrokAdapter extends LlmAdapter {
     private readonly options;
     private readonly catalog;
+    /** In-memory catalogs for non-default accounts (the persisted cache is the default's). */
+    private readonly accountCatalogs;
+    /** Account whose snapshot currently lives in {@link catalog}; cleared on default change. */
+    private catalogOwner;
     constructor(options: GrokAdapterOptions);
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
     private fetchCatalog;
+    /** Drop cached catalogs after login/logout so the next list does not reuse a stale plan. */
+    clearAccountCatalog(account?: string): void;
+    /** Persisted cache for the default account; a throwaway cache for any other. */
+    private catalogFor;
     private listed;
     providerInfo(provider: string): LlmProviderInfo;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    /** The provider's own catalog: union of every account, or one account when named. */
+    listOwnModels(provider: string, account?: string, signal?: AbortSignal): Promise<readonly LlmModelInfo[]>;
     /**
      * The discovered entry for one model. Resolved through the cache's
      * stale-while-revalidate path: capability metadata must stay stable across
@@ -149,7 +164,12 @@ export declare class GrokAdapter extends LlmAdapter {
      */
     private discovered;
     resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    /** Capability resolution of the provider's own models (the pool resolves members here). */
+    resolveOwnModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /** Pool seam: stream through one specific account instead of the default. */
+    streamAccount(options: GenerateOptions, account: string): AsyncIterable<StreamChunk>;
+    private streamCore;
     private request;
 }
 export {};

package/lib/providers/grok.js

@@ -7,7 +7,8 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverOrRetryAuth, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverAcrossAccounts, discoverOrRetryAuth, isDiscoveryAborted, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, } from './common.js';
+import { AccountTokenManager, DISCOVERY_TIMEOUT_MS, unionAccountCatalogs } from './accounts.js';
 import { proxiedFetch } from '../http.js';
 export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
 export const GROK_DISCOVERY_URL = 'https://auth.x.ai/.well-known/openid-configuration';
@@ -312,9 +313,10 @@ function grokCliReasoning(entry) {
  * Fetch the CLI catalog and index its per-model metadata by model id.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
+ * @param signal - caller cancellation (pool-assembly timeout).
  * @returns model id → contributed metadata.
  */
-export async function fetchGrokCliCatalog(session, fetchFn = proxiedFetch) {
+export async function fetchGrokCliCatalog(session, fetchFn = proxiedFetch, signal) {
     const response = await fetchFn(GROK_CLI_MODELS_URL, {
         headers: {
             'authorization': `Bearer ${session.accessToken}`,
@@ -323,6 +325,7 @@ export async function fetchGrokCliCatalog(session, fetchFn = proxiedFetch) {
             'accept': 'application/json',
             ...attributionHeaders(),
         },
+        ...signal === undefined ? {} : { signal },
     });
     if (!response.ok)
         throw await oauthEndpointError(response, 'grok CLI catalog');
@@ -384,9 +387,10 @@ function grokPriorMeta(prior) {
  * @param onWarn - warning sink for a failed CLI catalog fetch.
  * @param previous - last-known catalog used to keep enrichment when the CLI
  *   catalog is down or omits a model.
+ * @param signal - caller cancellation (pool-assembly timeout).
  * @returns discovered chat models in endpoint order.
  */
-export async function fetchGrokModels(session, fetchFn = proxiedFetch, onWarn, previous) {
+export async function fetchGrokModels(session, fetchFn = proxiedFetch, onWarn, previous, signal) {
     const previousById = previous === undefined || previous.length === 0
         ? undefined
         : new Map(previous.map(model => [model.id, model]));
@@ -397,8 +401,11 @@ export async function fetchGrokModels(session, fetchFn = proxiedFetch, onWarn, p
                 'accept': 'application/json',
                 ...attributionHeaders(),
             },
+            ...signal === undefined ? {} : { signal },
         }),
-        fetchGrokCliCatalog(session, fetchFn).catch((error) => {
+        fetchGrokCliCatalog(session, fetchFn, signal).catch((error) => {
+            if (isDiscoveryAborted(error, signal))
+                throw error;
             onWarn?.(previousById === undefined
                 ? `grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`
                 : `grok CLI catalog fetch failed; keeping last-known reasoning efforts (${errorChain(error)})`);
@@ -436,14 +443,50 @@ export async function fetchGrokModels(session, fetchFn = proxiedFetch, onWarn, p
 export class GrokAdapter extends LlmAdapter {
     options;
     catalog;
+    /** In-memory catalogs for non-default accounts (the persisted cache is the default's). */
+    accountCatalogs = new Map();
+    /** Account whose snapshot currently lives in {@link catalog}; cleared on default change. */
+    catalogOwner;
     constructor(options) {
         super();
         this.options = options;
         this.catalog = new ModelCatalogCache(options.catalogStore);
     }
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
-    async fetchCatalog() {
-        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn, this.catalog.lastKnown());
+    async fetchCatalog(account, signal) {
+        const lastKnown = account === undefined || account === await this.options.tokens.defaultAccount()
+            ? this.catalog.lastKnown()
+            : this.accountCatalogs.get(account)?.lastKnown();
+        return fetchGrokModels(await this.options.tokens.session(account), this.options.fetchFn, this.options.onWarn, lastKnown, signal);
+    }
+    /** Drop cached catalogs after login/logout so the next list does not reuse a stale plan. */
+    clearAccountCatalog(account) {
+        if (account === undefined)
+            this.accountCatalogs.clear();
+        else
+            this.accountCatalogs.delete(account);
+        if (account === undefined || this.catalogOwner === account || this.catalogOwner === undefined) {
+            this.catalogOwner = undefined;
+            this.catalog.invalidate();
+        }
+    }
+    /** Persisted cache for the default account; a throwaway cache for any other. */
+    async catalogFor(account) {
+        const defaultKey = await this.options.tokens.defaultAccount();
+        const key = account ?? defaultKey;
+        if (key === undefined || key === defaultKey) {
+            if (this.catalogOwner !== undefined && this.catalogOwner !== defaultKey) {
+                this.catalog.invalidate();
+            }
+            this.catalogOwner = defaultKey;
+            return this.catalog;
+        }
+        let cache = this.accountCatalogs.get(key);
+        if (cache === undefined) {
+            cache = new ModelCatalogCache();
+            this.accountCatalogs.set(key, cache);
+        }
+        return cache;
     }
     listed(provider, discovered) {
         return discovered.map(model => ({
@@ -466,19 +509,38 @@ export class GrokAdapter extends LlmAdapter {
         }));
     }
     async listModels(provider) {
-        // Not logged in → empty catalog, so the web picker drops the provider.
-        const session = await this.options.tokens.peek();
-        if (session === undefined)
+        const own = await this.listOwnModels(provider);
+        const pool = this.options.pool?.();
+        if (pool === undefined)
+            return own;
+        const extra = await pool.modelsForProvider(provider);
+        const seen = new Set(own.map(model => model.id));
+        // Account pools reuse the catalog row; only configured tiers are extra.
+        return [...own, ...extra.filter(model => !seen.has(model.id))];
+    }
+    /** The provider's own catalog: union of every account, or one account when named. */
+    async listOwnModels(provider, account, signal) {
+        if (account === undefined) {
+            const accounts = (await this.options.tokens.list()).map(entry => entry.key);
+            if (accounts.length === 0)
+                return [];
+            return unionAccountCatalogs(accounts, (key, accountSignal) => this.listOwnModels(provider, key, accountSignal), { timeoutMs: DISCOVERY_TIMEOUT_MS, ...signal === undefined ? {} : { signal } });
+        }
+        if (!await this.options.tokens.hasSession(account)) {
             return [];
+        }
         if (!this.options.discovery)
             return this.staticModels(provider);
+        const catalog = await this.catalogFor(account);
         try {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            return this.listed(provider, await discoverOrRetryAuth(force => this.options.tokens.session(force), this.catalog, () => this.catalog.get(() => this.fetchCatalog())));
+            return this.listed(provider, await discoverOrRetryAuth(force => this.options.tokens.session(account, force), catalog, () => catalog.get(() => this.fetchCatalog(account, signal))));
         }
         catch (error) {
+            if (isDiscoveryAborted(error, signal))
+                throw error;
             // A permanent refresh failure deletes the stored session: the provider
             // is logged out, so hide it instead of showing a stale static catalog.
             if (isMissingOrInvalidCredential(error))
@@ -498,10 +560,22 @@ export class GrokAdapter extends LlmAdapter {
     async discovered(model) {
         if (!this.options.discovery)
             return undefined;
-        const models = await this.catalog.resolve(() => this.fetchCatalog());
-        return models?.find(entry => entry.id === model);
+        const accounts = (await this.options.tokens.list()).map(entry => entry.key);
+        return discoverAcrossAccounts(accounts, async (account) => {
+            const catalog = await this.catalogFor(account);
+            const models = await catalog.resolve(() => this.fetchCatalog(account));
+            return models?.find(entry => entry.id === model);
+        });
     }
     async resolveModel(provider, model) {
+        const pool = this.options.pool?.();
+        if (pool !== undefined && await pool.owns(provider, model)) {
+            return pool.resolveModel(provider, model);
+        }
+        return this.resolveOwnModel(provider, model);
+    }
+    /** Capability resolution of the provider's own models (the pool resolves members here). */
+    async resolveOwnModel(provider, model) {
         const discovered = await this.discovered(model);
         const configured = this.options.models.find(entry => entry.id === model);
         return {
@@ -519,13 +593,25 @@ export class GrokAdapter extends LlmAdapter {
         };
     }
     async *stream(options) {
+        const pool = this.options.pool?.();
+        if (pool !== undefined && await pool.owns(options.provider, options.model)) {
+            yield* pool.stream(options);
+            return;
+        }
+        yield* this.streamCore(options);
+    }
+    /** Pool seam: stream through one specific account instead of the default. */
+    streamAccount(options, account) {
+        return this.streamCore(options, account);
+    }
+    async *streamCore(options, account) {
         const watchdog = idleWatchdog(options.signal, this.options.streamIdleTimeoutMs);
         try {
-            let session = await this.options.tokens.session();
+            let session = await this.options.tokens.session(account);
             let response = await this.request(options, session, watchdog.signal);
             if (response.status === 401) {
                 // One forced refresh + retry on an unexpired-but-rejected token.
-                session = await this.options.tokens.session(true);
+                session = await this.options.tokens.session(account, true);
                 response = await this.request(options, session, watchdog.signal);
             }
             if (!response.ok)

package/lib/providers/pool-family.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Same-subscription account routing: the picker is the union of every
+ * account's catalog (deduped by wire id). A model listed by two or more
+ * accounts failovers between them; a model listed by only one account is
+ * sent to that account. No extra pool identity, no cross-provider
+ * aggregation.
+ */
+import type { LlmModelInfo } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from '../auth/store.js';
+/** One pool member: an exact provider/account/model route. */
+export interface PoolMemberRef {
+    provider: ProviderId;
+    /** Account key; omitted in configured members to mean "the default account". */
+    account?: string;
+    model: string;
+}
+/** A member with its account resolved (no config indirection left). */
+export type ConcretePoolMember = PoolMemberRef & {
+    account: string;
+};
+/** One pool: its members plus display metadata for the picker. */
+export interface PoolDefinition {
+    members: PoolMemberRef[];
+    /** Display name of the catalog entry (account pools) or the pool id (extras). */
+    name?: string;
+    /** Description of the catalog entry, when the pool borrowed one. */
+    description?: string;
+    /**
+     * When true, the pool is an extra picker entry (a configured tier). Account
+     * pools leave this unset so they reuse the provider's existing catalog row.
+     */
+    extra?: boolean;
+}
+/** One account's catalog as seen through that account's credentials. */
+export interface AccountCatalog {
+    account: string;
+    models: readonly LlmModelInfo[];
+}
+/** One provider's contribution to account-pool aggregation. */
+export interface ProviderPoolSource {
+    /** Per-account catalogs, default first. A model pools only the accounts that list it. */
+    catalogs: readonly AccountCatalog[];
+}
+/** Map key for one provider's pool of one model (ids collide across providers). */
+export declare function poolKey(provider: string, model: string): string;
+/**
+ * Build per-provider account routes. Each model id becomes a definition of
+ * the accounts that list it: two or more fail over; one is pinned to that
+ * account (so a Max-only model is never sent to a Plus login). The picker
+ * unions these catalogs; a logout that drops a model to one account keeps
+ * the same id and pins it to whoever remains.
+ * @param sources - per-account catalogs (providers with no accounts list
+ *   nothing and simply never join a pool).
+ * @returns `provider/model` → pool definition (not listed as an extra entry).
+ */
+export declare function buildAccountPools(sources: Partial<Record<ProviderId, ProviderPoolSource>>): Map<string, PoolDefinition>;

package/lib/providers/pool-family.js

@@ -0,0 +1,45 @@
+/**
+ * Same-subscription account routing: the picker is the union of every
+ * account's catalog (deduped by wire id). A model listed by two or more
+ * accounts failovers between them; a model listed by only one account is
+ * sent to that account. No extra pool identity, no cross-provider
+ * aggregation.
+ */
+/** Map key for one provider's pool of one model (ids collide across providers). */
+export function poolKey(provider, model) {
+    return `${provider}/${model}`;
+}
+/**
+ * Build per-provider account routes. Each model id becomes a definition of
+ * the accounts that list it: two or more fail over; one is pinned to that
+ * account (so a Max-only model is never sent to a Plus login). The picker
+ * unions these catalogs; a logout that drops a model to one account keeps
+ * the same id and pins it to whoever remains.
+ * @param sources - per-account catalogs (providers with no accounts list
+ *   nothing and simply never join a pool).
+ * @returns `provider/model` → pool definition (not listed as an extra entry).
+ */
+export function buildAccountPools(sources) {
+    const pools = new Map();
+    for (const [provider, source] of Object.entries(sources)) {
+        const byModel = new Map();
+        for (const catalog of source.catalogs) {
+            for (const model of catalog.models) {
+                let entry = byModel.get(model.id);
+                if (entry === undefined) {
+                    entry = { members: [], info: model };
+                    byModel.set(model.id, entry);
+                }
+                entry.members.push({ provider, account: catalog.account, model: model.id });
+            }
+        }
+        for (const [id, { members, info }] of byModel) {
+            pools.set(poolKey(provider, id), {
+                members,
+                ...info.name === undefined || info.name === id ? {} : { name: info.name },
+                ...info.description === undefined ? {} : { description: info.description },
+            });
+        }
+    }
+    return pools;
+}

package/lib/providers/pool-health.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Health bookkeeping for pool members: which `(provider, account, model)`
+ * member is cooling down after a failure, and for how long. Purely in-memory
+ * — a restart re-probes members naturally, so nothing here is persisted.
+ *
+ * The failure classifier maps the adapters' stable `LlmError` codes (see
+ * `httpLlmError`/`mapFetchFailure` in `common.ts`) to one of three actions:
+ * switch to another member with a cooldown, switch without recording a
+ * cooldown (transport blips say nothing about the account), or rethrow
+ * (the request itself is at fault and another account would fail alike).
+ */
+import type { ProviderId } from '../auth/store.js';
+/** Registry key for one pool member. */
+export declare function memberKey(provider: ProviderId, account: string, model: string): string;
+/** Registry key parking EVERY member of one account (account-level failures). */
+export declare function accountKey(provider: ProviderId, account: string): string;
+/** Default cooldown when a quota/rate failure carries no `retry-after`. */
+export declare const DEFAULT_QUOTA_COOLDOWN_MS: number;
+/** Auth failures recheck after a day; a re-login clears the record immediately. */
+export declare const AUTH_COOLDOWN_MS: number;
+/** Transient server-side failures cool down briefly. */
+export declare const TRANSIENT_COOLDOWN_MS = 60000;
+/** Whether a failure parks one member or the account's whole quota. */
+export type PoolFailureScope = 'member' | 'account';
+/** What the pool should do with a member that just failed. */
+export type PoolFailureAction = {
+    action: 'switch';
+    cooldownMs: number;
+    reason: string;
+    scope: PoolFailureScope;
+} | {
+    action: 'switch';
+} | {
+    action: 'throw';
+};
+/**
+ * Classify a member failure. Quota and rate-limit failures cool down (using
+ * the provider's own `retry-after` when sent, which is more accurate than
+ * any fixed guess) — account-wide for account-metered providers, per-member
+ * for model-scoped ones; auth failures park the account until re-login
+ * (credentials are account-level); server/timeout failures get a short
+ * per-member cooldown; transport failures switch without a record;
+ * everything else — most importantly CONTEXT_WINDOW_EXCEEDED and ABORTED —
+ * is the request's own fault and is rethrown untouched.
+ * @param error - the failure thrown by a member adapter's stream.
+ * @param provider - the failing member's provider (decides the quota scope).
+ * @returns the action the pool should take.
+ */
+export declare function classifyPoolFailure(error: unknown, provider: ProviderId): PoolFailureAction;
+/**
+ * Cooldown registry keyed by {@link memberKey}. A member whose cooldown has
+ * expired is simply available again — recovery is proven by the next real
+ * request, not by a background probe.
+ */
+export declare class PoolHealthRegistry {
+    private readonly records;
+    /** Whether a member may serve: neither it nor its whole account is cooling. */
+    isMemberAvailable(provider: ProviderId, account: string, model: string, now?: number): boolean;
+    /** Whether one registry key is clear right now. */
+    isAvailable(key: string, now?: number): boolean;
+    /** Park a member for `cooldownMs`; a longer existing cooldown wins. */
+    markUnavailable(key: string, cooldownMs: number, reason: string, now?: number): void;
+    /**
+     * Epoch ms at which the earliest cooling record among `keys` recovers;
+     * `undefined` when none of them is cooling. The registry is shared by
+     * every pool, so the caller passes the keys of ITS members (member and
+     * account keys alike) — an unrelated pool's cooldown must not shape this
+     * pool's retry hint. Feeds the pool-exhausted error's
+     * `providerRetryAfterMs`.
+     */
+    earliestRecovery(keys: ReadonlySet<string>, now?: number): number | undefined;
+    /** Drop records of one provider, or of a single account when given (auth changes). */
+    clear(provider: ProviderId, account?: string): void;
+}

package/lib/providers/pool-health.js

@@ -0,0 +1,148 @@
+/**
+ * Health bookkeeping for pool members: which `(provider, account, model)`
+ * member is cooling down after a failure, and for how long. Purely in-memory
+ * — a restart re-probes members naturally, so nothing here is persisted.
+ *
+ * The failure classifier maps the adapters' stable `LlmError` codes (see
+ * `httpLlmError`/`mapFetchFailure` in `common.ts`) to one of three actions:
+ * switch to another member with a cooldown, switch without recording a
+ * cooldown (transport blips say nothing about the account), or rethrow
+ * (the request itself is at fault and another account would fail alike).
+ */
+import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+/** Registry key for one pool member. */
+export function memberKey(provider, account, model) {
+    return `${provider}/${account}/${model}`;
+}
+/** Registry key parking EVERY member of one account (account-level failures). */
+export function accountKey(provider, account) {
+    return `${provider}/${account}/*`;
+}
+/** Default cooldown when a quota/rate failure carries no `retry-after`. */
+export const DEFAULT_QUOTA_COOLDOWN_MS = 5 * 60_000;
+/** Auth failures recheck after a day; a re-login clears the record immediately. */
+export const AUTH_COOLDOWN_MS = 24 * 60 * 60_000;
+/** Transient server-side failures cool down briefly. */
+export const TRANSIENT_COOLDOWN_MS = 60_000;
+/**
+ * Providers whose quota windows are model-scoped, so a quota failure on one
+ * model says nothing about its siblings (Claude's Opus/Sonnet lanes). Every
+ * other provider meters the account as a whole: one member hitting the wall
+ * means its siblings on the SAME account would too, so the cooldown parks
+ * the account (other accounts of the provider are unaffected).
+ */
+const MODEL_SCOPED_QUOTA_PROVIDERS = new Set(['claude']);
+/** The `retry-after` an adapter propagated through `httpLlmError`, when any. */
+function retryAfterMs(error) {
+    return error.failure.providerRetryAfterMs;
+}
+/**
+ * Classify a member failure. Quota and rate-limit failures cool down (using
+ * the provider's own `retry-after` when sent, which is more accurate than
+ * any fixed guess) — account-wide for account-metered providers, per-member
+ * for model-scoped ones; auth failures park the account until re-login
+ * (credentials are account-level); server/timeout failures get a short
+ * per-member cooldown; transport failures switch without a record;
+ * everything else — most importantly CONTEXT_WINDOW_EXCEEDED and ABORTED —
+ * is the request's own fault and is rethrown untouched.
+ * @param error - the failure thrown by a member adapter's stream.
+ * @param provider - the failing member's provider (decides the quota scope).
+ * @returns the action the pool should take.
+ */
+export function classifyPoolFailure(error, provider) {
+    if (!(error instanceof LlmError))
+        return { action: 'throw' };
+    switch (error.code) {
+        case QUOTA_EXCEEDED_CODE:
+        case 'RATE_LIMIT':
+            return {
+                action: 'switch',
+                cooldownMs: retryAfterMs(error) ?? DEFAULT_QUOTA_COOLDOWN_MS,
+                reason: error.code,
+                scope: MODEL_SCOPED_QUOTA_PROVIDERS.has(provider) ? 'member' : 'account',
+            };
+        case 'AUTH':
+        case 'INVALID_CREDENTIAL':
+        case 'MISSING_CREDENTIAL':
+            return { action: 'switch', cooldownMs: AUTH_COOLDOWN_MS, reason: error.code, scope: 'account' };
+        case 'SERVER':
+        case 'TIMEOUT':
+        case 'EMPTY_RESPONSE':
+            return { action: 'switch', cooldownMs: TRANSIENT_COOLDOWN_MS, reason: error.code, scope: 'member' };
+        case 'TRANSPORT':
+            return { action: 'switch' };
+        case 'HTTP_402':
+        case 'HTTP_404':
+            // Plan/model availability is account-shaped: another account of the
+            // same subscription may still serve. A 400 that is not a context-window
+            // error stays HTTP_400 and throws (the request itself is at fault).
+            return { action: 'switch', cooldownMs: TRANSIENT_COOLDOWN_MS, reason: error.code, scope: 'member' };
+        case CONTEXT_WINDOW_EXCEEDED_CODE:
+        case 'ABORTED':
+        default:
+            return { action: 'throw' };
+    }
+}
+/**
+ * Cooldown registry keyed by {@link memberKey}. A member whose cooldown has
+ * expired is simply available again — recovery is proven by the next real
+ * request, not by a background probe.
+ */
+export class PoolHealthRegistry {
+    records = new Map();
+    /** Whether a member may serve: neither it nor its whole account is cooling. */
+    isMemberAvailable(provider, account, model, now = Date.now()) {
+        return this.isAvailable(accountKey(provider, account), now)
+            && this.isAvailable(memberKey(provider, account, model), now);
+    }
+    /** Whether one registry key is clear right now. */
+    isAvailable(key, now = Date.now()) {
+        const record = this.records.get(key);
+        if (record === undefined)
+            return true;
+        if (record.unavailableUntil <= now) {
+            this.records.delete(key);
+            return true;
+        }
+        return false;
+    }
+    /** Park a member for `cooldownMs`; a longer existing cooldown wins. */
+    markUnavailable(key, cooldownMs, reason, now = Date.now()) {
+        const until = now + cooldownMs;
+        const existing = this.records.get(key);
+        if (existing !== undefined && existing.unavailableUntil > until)
+            return;
+        this.records.set(key, { unavailableUntil: until, reason });
+    }
+    /**
+     * Epoch ms at which the earliest cooling record among `keys` recovers;
+     * `undefined` when none of them is cooling. The registry is shared by
+     * every pool, so the caller passes the keys of ITS members (member and
+     * account keys alike) — an unrelated pool's cooldown must not shape this
+     * pool's retry hint. Feeds the pool-exhausted error's
+     * `providerRetryAfterMs`.
+     */
+    earliestRecovery(keys, now = Date.now()) {
+        let earliest;
+        for (const [key, record] of this.records) {
+            if (record.unavailableUntil <= now) {
+                this.records.delete(key);
+                continue;
+            }
+            if (!keys.has(key))
+                continue;
+            if (earliest === undefined || record.unavailableUntil < earliest) {
+                earliest = record.unavailableUntil;
+            }
+        }
+        return earliest;
+    }
+    /** Drop records of one provider, or of a single account when given (auth changes). */
+    clear(provider, account) {
+        const prefix = account === undefined ? `${provider}/` : `${provider}/${account}/`;
+        for (const key of [...this.records.keys()]) {
+            if (key.startsWith(prefix))
+                this.records.delete(key);
+        }
+    }
+}

package/lib/providers/pool-usage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Quota tracking for pool members: polls the providers' usage endpoints
+ * (the same normalized `ProviderUsage` shape the Settings page consumes) and
+ * turns the windows into a scheduling score.
+ *
+ * The score is a REQUIRED BURN RATE: the fraction of the window that must be
+ * consumed per millisecond for the quota to be exactly used up at reset time
+ * (`remaining / timeUntilReset`). Subscription quota does not roll over, so a
+ * window about to reset with plenty left is the most urgent to spend — the
+ * `quota_aware` strategy therefore prefers the highest-urgency member, which
+ * over time converges on every window hitting zero right at its reset.
+ */
+import type { ProviderUsage } from './common.js';
+import type { ProviderId } from '../auth/store.js';
+import type { ConcretePoolMember } from './pool-family.js';
+/** A member is taken out of rotation once any window crosses this fill level. */
+export declare const QUOTA_FULL_PERCENT = 95;
+/** How long a usage snapshot is trusted before a background refresh. */
+export declare const USAGE_TTL_MS: number;
+/** The scheduling view of one member's quota. */
+export interface MemberQuota {
+    /** False when a window is effectively full or the login is gone. */
+    available: boolean;
+    /** Required burn rate (fraction of window per ms); 0 when unknown. */
+    urgency: number;
+    /** Epoch ms of the snapshot this was computed from; 0 when none. */
+    fetchedAt: number;
+}
+/**
+ * Per-ACCOUNT usage snapshots with in-flight dedupe and
+ * stale-while-revalidate refresh. Providers without a usage endpoint
+ * (copilot) resolve no fetcher and score a constant zero urgency — which
+ * naturally ranks them behind every measured member. Fetchers are resolved
+ * lazily per (provider, account) so accounts added after startup join
+ * tracking on their first score.
+ */
+export declare class PoolUsageTracker {
+    private readonly fetcherFor;
+    private readonly ttlMs;
+    private readonly entries;
+    private readonly inflight;
+    constructor(fetcherFor: (provider: ProviderId, account: string) => (() => Promise<ProviderUsage>) | undefined, ttlMs?: number);
+    /**
+     * The quota view of one member. A cold cache awaits the first fetch; a
+     * stale one answers immediately while the refresh serves the NEXT call
+     * (member selection must never block on the network mid-conversation).
+     * @param member - the pool member to score (account resolved).
+     * @returns availability plus the urgency score.
+     */
+    quotaFor(member: ConcretePoolMember): Promise<MemberQuota>;
+    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    invalidate(provider: ProviderId, account?: string): void;
+    /** Run (or join) the single in-flight fetch for one account key. */
+    private refresh;
+    /** Score one member against a snapshot's windows. */
+    private score;
+}