dsh-plugin-subscriptions 0.5.1 → 0.5.3

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;
+}

package/lib/providers/pool-usage.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { isMissingOrInvalidCredential } from './common.js';
+/** A member is taken out of rotation once any window crosses this fill level. */
+export const QUOTA_FULL_PERCENT = 95;
+/** How long a usage snapshot is trusted before a background refresh. */
+export const USAGE_TTL_MS = 5 * 60_000;
+/** Assumed window length when the provider discloses no `resetsAt`. */
+const FALLBACK_HORIZON_MS = {
+    session: 5 * 60 * 60_000,
+    weekly: 7 * 24 * 60 * 60_000,
+    other: 30 * 24 * 60 * 60_000,
+};
+/**
+ * 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 class PoolUsageTracker {
+    fetcherFor;
+    ttlMs;
+    entries = new Map();
+    inflight = new Map();
+    constructor(fetcherFor, ttlMs = USAGE_TTL_MS) {
+        this.fetcherFor = fetcherFor;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * 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.
+     */
+    async quotaFor(member) {
+        const key = `${member.provider}/${member.account}`;
+        const fetcher = this.fetcherFor(member.provider, member.account);
+        if (fetcher === undefined)
+            return { available: true, urgency: 0, fetchedAt: 0 };
+        const entry = this.entries.get(key);
+        if (entry !== undefined && Date.now() - entry.at < this.ttlMs) {
+            return this.score(member, entry);
+        }
+        if (entry !== undefined) {
+            void this.refresh(key, fetcher).catch(() => undefined);
+            return this.score(member, entry);
+        }
+        try {
+            const snapshot = await this.refresh(key, fetcher);
+            return this.score(member, { snapshot, at: Date.now() });
+        }
+        catch (error) {
+            // Logged out: the member cannot serve at all. Any other failure
+            // (network, endpoint rate limit) must not block routing — the member
+            // stays available with a zero score, degrading the strategy to plain
+            // priority order for it.
+            return isMissingOrInvalidCredential(error)
+                ? { available: false, urgency: 0, fetchedAt: 0 }
+                : { available: true, urgency: 0, fetchedAt: 0 };
+        }
+    }
+    /** Drop cached snapshots: one account, or a whole provider when `account` is omitted. */
+    invalidate(provider, account) {
+        if (account !== undefined) {
+            this.entries.delete(`${provider}/${account}`);
+            return;
+        }
+        for (const key of [...this.entries.keys()]) {
+            if (key.startsWith(`${provider}/`))
+                this.entries.delete(key);
+        }
+    }
+    /** Run (or join) the single in-flight fetch for one account key. */
+    refresh(key, fetcher) {
+        let pending = this.inflight.get(key);
+        if (pending === undefined) {
+            pending = fetcher().then((snapshot) => {
+                this.entries.set(key, { snapshot, at: Date.now() });
+                return snapshot;
+            }).finally(() => {
+                this.inflight.delete(key);
+            });
+            this.inflight.set(key, pending);
+        }
+        return pending;
+    }
+    /** Score one member against a snapshot's windows. */
+    score(member, entry) {
+        const windows = (entry.snapshot.windows ?? []).filter(window => windowApplies(window, member.model));
+        let available = true;
+        let urgency = 0;
+        for (const window of windows) {
+            if (window.usedPercent >= QUOTA_FULL_PERCENT)
+                available = false;
+            urgency = Math.max(urgency, windowUrgency(window));
+        }
+        return { available, urgency, fetchedAt: entry.at };
+    }
+}
+/**
+ * Whether a window constrains this model: unscoped windows always do; a
+ * model-scoped window (Claude's Opus/Sonnet lanes) applies when its scope
+ * names the model family.
+ */
+function windowApplies(window, model) {
+    if (window.scope === undefined)
+        return true;
+    return model.toLowerCase().includes(window.scope.toLowerCase());
+}
+/** The required burn rate of one window (fraction per ms). */
+function windowUrgency(window, now = Date.now()) {
+    const remaining = Math.max(0, 1 - window.usedPercent / 100);
+    const horizon = window.resetsAt !== undefined
+        ? Math.max(window.resetsAt - now, 1)
+        : FALLBACK_HORIZON_MS[window.kind];
+    return remaining / horizon;
+}

package/lib/providers/pool.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The pool adapter: same-subscription account routing, plus optional
+ * configured tier extras. The picker is the union of every account's
+ * catalog. A model listed by several accounts failovers; a model listed by
+ * one account is pinned to it. Tiers are extra picker rows. Member
+ * selection is sticky per session (so prompt caches survive) and optionally
+ * quota-aware; failures fail over to the next member as long as no stream
+ * chunk has been emitted.
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ProviderId } from '../auth/store.js';
+import type { AccountAwareAdapter } from './accounts.js';
+import type { PoolDefinition, PoolMemberRef } from './pool-family.js';
+import { PoolHealthRegistry } from './pool-health.js';
+import type { PoolUsageTracker } from './pool-usage.js';
+/** Member-selection strategy: plain priority failover or quota-aware scheduling. */
+export type PoolStrategy = 'priority' | 'quota_aware';
+export interface PoolAdapterOptions {
+    /** The live subscription adapters, by provider route. */
+    adapters: Partial<Record<ProviderId, AccountAwareAdapter>>;
+    health: PoolHealthRegistry;
+    usage: PoolUsageTracker;
+    strategy: PoolStrategy;
+    /** A challenger must out-urgency the sticky member by this factor to take over. */
+    switchMargin: number;
+    /** The default account of one provider (for config members omitting `account`). */
+    defaultAccount: (provider: ProviderId) => Promise<string | undefined>;
+    /** Account pools (auto-aggregated plus config overrides), resolved lazily. */
+    families: () => Promise<Map<string, PoolDefinition>>;
+    /** User-configured extra picker entries (heterogeneous fallbacks), by pool id. */
+    tiers: Record<string, PoolMemberRef[]>;
+    onWarn: (message: string) => void;
+}
+export declare class PoolAdapter extends LlmAdapter {
+    private readonly options;
+    /** sessionId|poolId → member key of the last member that served a chunk. */
+    private readonly sticky;
+    /** Messages already warned about — configuration diagnostics repeat every request otherwise. */
+    private readonly warned;
+    /**
+     * Short-lived pools snapshot. `owns()` runs on every resolveModel — the
+     * model picker issues one per entry — and pool assembly touches every
+     * provider's catalog and account store, so recompute at most this often.
+     * Auth changes bump {@link generation} so a stale snapshot cannot land.
+     */
+    private poolsCache;
+    private poolsInflight;
+    private generation;
+    constructor(options: PoolAdapterOptions);
+    /** Drop the pools snapshot so the next read reflects the current accounts. */
+    invalidate(): void;
+    /** Warn once per distinct message (pools() runs on every request). */
+    private warnOnce;
+    /** Drop members whose adapter is not registered (copy — caller state is shared). */
+    private usable;
+    /** Account pools (auto-aggregated plus config overrides) with usable members. */
+    private familyPools;
+    /** All pools (account pools merged with extra tiers) with usable members. */
+    private pools;
+    /** Recompute the pools snapshot (account pools merged with extra tiers). */
+    private assemblePools;
+    /**
+     * Extra picker rows one provider lists (configured tiers). Account pools
+     * reuse the catalog entry of the same wire id, so they are not listed
+     * again — the picker stays one row per model in ChatGPT / Claude / ….
+     */
+    modelsForProvider(provider: ProviderId): Promise<LlmModelInfo[]>;
+    /**
+     * Whether `model` on `provider`'s route is served here (several accounts
+     * fail over, one account is pinned, or a configured tier).
+     */
+    owns(provider: ProviderId, model: string): Promise<boolean>;
+    /**
+     * Resolve every member's account (config members may omit it to mean "the
+     * default account") and drop members with no resolvable login. Duplicates
+     * collapse — an explicitly pinned account and the default may coincide.
+     */
+    private concrete;
+    /**
+     * Resolve a pool model to the conservative INTERSECTION of its members'
+     * capabilities: the smallest context window and output cap, the reasoning
+     * efforts every member supports, and the modalities all of them accept —
+     * so a request valid for the pool stays valid after a failover. Capability
+     * metadata is provider-level, so each provider resolves once regardless of
+     * how many accounts it pools.
+     */
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Order the candidates for one request. Health filters both strategies;
+     * `quota_aware` then ranks by urgency (members without telemetry, e.g.
+     * copilot, score zero and sink to the bottom of their class), while
+     * quota-exhausted members stay as a last-resort tail in pool order. The
+     * sticky member keeps its lead unless a challenger out-scores it by
+     * `switchMargin`.
+     */
+    private select;
+    /** Pin the serving member to the session (with bounded memory). */
+    private remember;
+    /**
+     * The error for an exhausted pool, carrying the earliest recovery hint of
+     * THIS pool's members (the health registry is shared across pools, so the
+     * hint is scoped to the keys this pool can actually recover through).
+     */
+    private exhausted;
+}