agl 40.4.0 → 40.5.0

package/dist_ts/classes.inferencerouter.d.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import type { TInferenceCredential, TInferenceProvider } from './functions.proxycontract.js';
 import type { IGatewayAuthorityAccess } from './classes.flexaccountaccess.js';
+import type { IInferenceSpendRecord } from './classes.inferencespend.js';
 export type TInferenceModel = plugins.openAiProvider.IOpenAiChatGptModel;
 /** A model a Claude account or an Anthropic API key may use, as the Anthropic API lists it. */
 export type TInferenceClaudeModel = plugins.anthropicProvider.IAnthropicOAuthModel;
@@ -15,30 +16,49 @@ export declare const parseHttpDate: (valueArg: string, nowArg: number) => number
  * counted from `nowArg` (a date already past is 0). `undefined` when the header is absent or neither form.
  */
 export declare const inferenceRetryAfterSeconds: (valueArg: string | null, nowArg: number) => number | undefined;
+/**
+ * The credential tiers a pool is served from, best first: the one a policy names alone, or with none the provider's
+ * subscription sign-ins first and its API keys after them. A key takes a request only when no subscription can take it,
+ * for whatever reason, and a session placed on a key returns to a subscription at the next request one can take.
+ */
+export declare const inferenceCredentialTiers: (credentialArg: TInferenceCredential | undefined) => readonly TInferenceCredential[];
 export interface IInferenceAccount {
     id: string;
     label: string;
     revision: string;
     providerId: TInferenceProvider;
-    /** What the account authenticates with: a subscription sign-in, or an Anthropic API key. */
+    /** What the account authenticates with: a subscription sign-in, or an API key. */
     credential: TInferenceCredential;
     /** The account's usage threshold (`IAuthSwitchAccount.maxUsagePercent`); `null` when unset. */
     maxUsagePercent: number | null;
     reserveLiftUntil: string | null;
     /** When the account's subscription ends (`IAuthSwitchAccount.lapsesAt`); `null` while it renews. */
     lapsesAt: string | null;
+    /**
+     * An API key's monthly spend limit in micro-dollars (`IAuthSwitchAccount.spendLimitMicroUsd`); `null` without one,
+     * and for a sign-in. It decides only whether a key whose spend the proxy holds no reading of may take work: one with
+     * a limit may not (`spend_unread`). A spend reading carries the limit the key is judged against.
+     */
+    spendLimitMicroUsd: number | null;
+    /**
+     * The login the account's requests are served on (the account service's gateway login of it), as the pool was read;
+     * `null` when the account service names none. An API key's spend is reported on it.
+     */
+    loginId: string | null;
 }
 export interface IInferenceRoutingPolicy {
     /** The pool's provider; omitted means ChatGPT accounts (`openai`). */
     provider?: TInferenceProvider;
     /**
-     * What the pool's accounts authenticate with; omitted means subscription sign-ins. `api_key` is an Anthropic pool's
-     * alone: its Anthropic API keys, which Flex's Claude models run on, never a Claude account.
+     * What the pool's accounts authenticate with. Omitted, a Claude pool is served by its Claude accounts first and its
+     * Anthropic API keys when no Claude account can take a request (`inferenceCredentialTiers`), a ChatGPT pool by its
+     * ChatGPT accounts. `subscription` names the sign-ins alone; `api_key` is an Anthropic pool's alone: its Anthropic API
+     * keys, which Flex's Claude models run on, never a Claude account.
      */
     credential?: TInferenceCredential;
     /** Omitted means all eligible authority-owned accounts of the provider. */
     accountIds?: readonly string[];
-    /** Exact current provider plan names; omission accepts every entitled plan. */
+    /** Exact current provider plan names; omission accepts every entitled plan. A key has no plan, so this leaves keys out. */
     plans?: readonly string[];
 }
 export interface IInferenceRouterOptions {
@@ -64,18 +84,48 @@ export interface IInferenceRouterOptions {
      */
     reportAccount?: (changeArg: IInferenceAccountChange) => void;
     /**
-     * Tells the account service that Anthropic refused a request on the Claude account with a billing error (HTTP 402
-     * `billing_error`) at `observedAtArg`; resolves once the service holds it, so the account's usage carries it from then
-     * on (`IAuthSwitchUsageSnapshot.paymentProblem`). Unset, the router holds the account out of rotation itself.
+     * Tells the account service that the provider refused a request on the account for a payment problem at
+     * `observedAtArg` -- a Claude account's billing error (HTTP 402 `billing_error`), or an API key's refusal for
+     * `causeArg` (`TInferencePaymentCause`); resolves once the service holds it, so the account's usage carries it from
+     * then on (`IAuthSwitchUsageSnapshot.paymentProblem`). Unset, the router holds the account out of rotation itself.
      */
-    reportPaymentProblem?: (accountIdArg: string, observedAtArg: string) => Promise<void>;
+    reportPaymentProblem?: (accountIdArg: string, observedAtArg: string, causeArg: TInferencePaymentCause) => Promise<void>;
     /**
      * Where a payment problem the account service could not be told of is reported: once per account, never per request.
      * One line on standard error, the proxy's journal, when unset.
      */
     reportPaymentFailure?: (failureArg: IInferencePaymentReportFailure) => void;
+    /**
+     * Where the spend of the answers relayed on API keys is kept until the accounts service acknowledged it
+     * (`InferenceSpendOutbox`). A key's usage arrives judged with that spend already (`InferenceUsageCache` `view`).
+     */
+    spend?: IInferenceSpendLedger;
     now?: () => number;
 }
+/** What the router asks of the proxy's spend outbox (`InferenceSpendOutbox`). */
+export interface IInferenceSpendLedger {
+    /**
+     * Counts a relayed answer's spend and keeps it until the accounts service acknowledged it, reported on the login the
+     * route was served on (`IInferenceClaudeRoute.loginId`); `null` when none could be named, which still counts.
+     */
+    record(accountIdArg: string, loginIdArg: string | null, recordArg: IInferenceSpendRecord): void;
+    /**
+     * Whether spend relayed on the key is recorded nowhere yet: the accounts service refused a report the outbox still
+     * holds, an answer is in neither the outbox's store, whose write failed, nor the ledger, or no login of the key could
+     * be named for an answer, so it cannot be reported.
+     */
+    held(accountIdArg: string): boolean;
+    /** Says that an answer relayed on the key ended before its provider stated its usage, so nothing of it is counted. */
+    uncounted(accountIdArg: string, modelArg: string): void;
+}
+/**
+ * What a payment problem's report adds for the account service (`IReq_AuthSwitchReportPaymentProblem`): the cause of an
+ * API key's spend cap or quota, nothing for a billing error, whose cause a missing one means -- so a Claude account's
+ * report is the one an accounts service of 40.3.0, which refuses a cause, takes.
+ */
+export declare const inferencePaymentReportOptions: (causeArg: TInferencePaymentCause) => {
+    cause?: Exclude<TInferencePaymentCause, 'billing'>;
+};
 /** A payment problem the account service could not be told of, as the proxy reports it: the account by its id's digest. */
 export interface IInferencePaymentReportFailure {
     /** The first 12 hex characters of the SHA-256 digest of the account's id. */
@@ -87,16 +137,41 @@ export interface IInferencePaymentReportFailure {
  * Why an account takes no request although no limit says so. `usage_unread`: the account service holds no usage reading
  * the proxy routes on. `catalog_failed`: the account's model list could not be read and none read before is held for its
  * revision. `needs_login`: its sign-in needs renewing. `access_failed`: the account service answered no access for it.
- * `model_missing`: its model list lacks the requested model. `payment_problem`: Anthropic refused a request on the Claude
- * account with a billing error (HTTP 402 `billing_error`); it takes none until a usage read or a re-check clears it.
+ * `model_missing`: its model list lacks the requested model. `payment_problem`: the provider refused a request on the
+ * account for a payment problem (`TInferencePaymentCause`); it takes none until a usage read or a re-check clears it, or
+ * a spend cap ends. `spend_unread`: an API key with a monthly spend limit whose spend the proxy holds no reading of --
+ * the account service could not read its ledger (`spend_unavailable`) or did not answer -- so it may be at its limit.
+ * `spend_unrecorded`: an API key with a monthly spend limit whose spend the proxy relayed is recorded nowhere yet --
+ * the account service refused its report, which the proxy holds to send again, an answer is held in neither the
+ * proxy's store, whose write failed, nor the account service's ledger, or no login of the key could be named for an
+ * answer to report it on (`InferenceSpendOutbox.held`). `model_unpriced`: an API key with a monthly spend limit, and a
+ * request whose model, service tier, speed, region or server tool the proxy's price table cannot price (`failure` names
+ * it), so its cost could not be counted against the limit.
+ */
+export type TInferenceUnavailableReason = 'usage_unread' | 'catalog_failed' | 'needs_login' | 'access_failed' | 'model_missing' | 'payment_problem' | 'spend_unread' | 'spend_unrecorded' | 'model_unpriced';
+/**
+ * Why a provider refused a request on an account for a payment problem, as the gateway reads the provider's answer.
+ * `billing`: Anthropic's billing error (HTTP 402 `billing_error`), on a Claude account's subscription or an Anthropic API
+ * key's organization. `spend_cap`: an Anthropic API key's organization reached its usage tier's monthly spend cap (HTTP
+ * 429 `rate_limit_error` with `error.details.error_code: "enforced_spend_limit_reached"`), which holds until 00:00 UTC on
+ * the first day of the next month. `quota`: OpenAI refused an API key for its quota (HTTP 429 `insufficient_quota`): no
+ * prepaid credit left, or an organization or project spend limit or the organization's usage limit reached.
  */
-export type TInferenceUnavailableReason = 'usage_unread' | 'catalog_failed' | 'needs_login' | 'access_failed' | 'model_missing' | 'payment_problem';
+export type TInferencePaymentCause = plugins.authswitchAuthority.TAuthSwitchPaymentProblemCause;
 export interface IInferenceAccountUnavailable {
     reason: TInferenceUnavailableReason;
-    /** `usage_unread`: when the account service reads the account's usage next, or `null` when it does not say. */
+    /**
+     * `usage_unread`: when the account service reads the account's usage next, or `null` when it does not say.
+     * `payment_problem` of a spend cap: when the cap ends and the account takes requests again.
+     */
     retryAt?: string | null;
-    /** `catalog_failed`: the HTTP status the model list answered with (`HTTP 429`), or what failed instead. */
+    /**
+     * `catalog_failed`: the HTTP status the model list answered with (`HTTP 429`), or what failed instead.
+     * `model_unpriced`: what of the request the price table cannot price.
+     */
     failure?: string;
+    /** `payment_problem`: what the provider refused the account for. */
+    cause?: TInferencePaymentCause;
 }
 /** A change of why an account is refused, as the proxy reports it: the account by its id's digest, never its id. */
 export interface IInferenceAccountChange {
@@ -115,6 +190,17 @@ export interface IInferenceAccountChange {
  * 429 (`cooling`).
  */
 export type TInferenceAccountLimit = 'exhausted' | 'reserved' | 'cooling';
+/** An API key a request found held by its monthly spend limit: the account, and its month as the account service read it. */
+export interface IInferenceSpendLimited {
+    accountId: string;
+    label: string;
+    spend: plugins.authswitchSpend.IAuthSwitchSpendReading;
+}
+/**
+ * What a refusal says of the API keys it found held by their monthly spend limit: each key with its month, and when the
+ * first of them takes requests again. Empty without any.
+ */
+export declare const inferenceSpendLimitText: (keysArg: readonly IInferenceSpendLimited[]) => string;
 export declare class InferenceRoutingError extends Error {
     readonly status: number;
     readonly code: string;
@@ -125,8 +211,13 @@ export declare class InferenceRoutingError extends Error {
     readonly accountLimit?: TInferenceAccountLimit | undefined;
     /** The account a refusal for a reason of its own (`reason`) names. */
     readonly accountId?: string | undefined;
-    /** For `no_eligible_accounts` of a pinned account: why that account takes no request, though no limit says so. */
-    readonly reason?: TInferenceUnavailableReason | undefined;
+    /**
+     * For `no_eligible_accounts` of a pinned account: why that account takes no request though no limit says so, in
+     * full -- a payment problem's cause, say.
+     */
+    readonly unavailable?: IInferenceAccountUnavailable | undefined;
+    /** For `accounts_exhausted`: the API keys found held by their monthly spend limit, which its message names. */
+    readonly spendLimited: readonly IInferenceSpendLimited[];
     constructor(status: number, code: string, messageArg: string, retryAfterSeconds?: number | undefined, 
     /** For `accounts_exhausted`: the provider plans of the accounts found at their limits. */
     plans?: readonly string[], 
@@ -134,17 +225,39 @@ export declare class InferenceRoutingError extends Error {
     accountLimit?: TInferenceAccountLimit | undefined, 
     /** The account a refusal for a reason of its own (`reason`) names. */
     accountId?: string | undefined, 
-    /** For `no_eligible_accounts` of a pinned account: why that account takes no request, though no limit says so. */
-    reason?: TInferenceUnavailableReason | undefined);
+    /**
+     * For `no_eligible_accounts` of a pinned account: why that account takes no request though no limit says so, in
+     * full -- a payment problem's cause, say.
+     */
+    unavailable?: IInferenceAccountUnavailable | undefined, 
+    /** For `accounts_exhausted`: the API keys found held by their monthly spend limit, which its message names. */
+    spendLimited?: readonly IInferenceSpendLimited[]);
+    /** The reason of `unavailable`: a refusal names a reason of its own only with the refusal in full. */
+    get reason(): TInferenceUnavailableReason | undefined;
 }
+/**
+ * A ChatGPT account or an OpenAI API key chosen for one request: a ChatGPT sign-in through the ChatGPT backend, a key
+ * through OpenAI's API (`OPENAI_API_BASE_URL`), each through `connection`.
+ */
 export interface IInferenceRoute {
     provider: 'openai';
+    /** What the chosen account authenticates with: a ChatGPT sign-in, or an OpenAI API key. */
+    credential: TInferenceCredential;
     accountId: string;
     plan: string;
     /** The account's placement score when it was chosen (`IAuthSwitchPlacement.score`). */
     score: number | null;
     model: TInferenceModel;
     connection: plugins.openAiProvider.IOpenAiModelConnection;
+    /** The session left its account on a later credential tier for one of a better tier (`returnToBetterTier`). */
+    returned: boolean;
+    /** The login the account was served on as the pool was read (`IInferenceAccount.loginId`): an answer's spend names it. */
+    loginId: string | null;
+    /**
+     * An OpenAI API key with a monthly spend limit: the request goes out as the price check read it, on the service tier it
+     * was checked for (`inferenceOpenAiCheckedBytes`).
+     */
+    spendLimit: boolean;
     release: () => void;
 }
 /**
@@ -160,6 +273,18 @@ export interface IInferenceClaudeRoute {
     score: number | null;
     model: TInferenceClaudeModel;
     connection: plugins.anthropicProvider.IAnthropicModelConnection;
+    /**
+     * The session's account is an Anthropic API key, and a Claude account of a better credential tier took the request
+     * instead (`returnToBetterTier`): the session returns to it.
+     */
+    returned: boolean;
+    /** The login the account was served on as the pool was read (`IInferenceAccount.loginId`): an answer's spend names it. */
+    loginId: string | null;
+    /**
+     * An Anthropic API key with a monthly spend limit: the request goes out as the price check read it, on the standard
+     * service tier only (`inferenceAnthropicCheckedBytes`), the one the price table prices.
+     */
+    spendLimit: boolean;
     release: () => void;
 }
 /** One account of the proxy as `agl proxy status` shows it, judged on the held reading without reading again. */
@@ -219,37 +344,99 @@ export interface IInferenceAccountStatus {
 export type TInferenceNativeModel = Record<string, unknown> & {
     slug: string;
 };
+/** How a request is placed on a Claude pool (`InferenceRouter.acquireClaude`). */
+export interface IInferenceClaudeAcquireOptions {
+    /** The session's account: the request is judged on it alone, unless `returnToBetterTier` finds a better one. */
+    accountId?: string;
+    /** The accounts this request left already; it never goes back to them. */
+    exclude?: ReadonlySet<string>;
+    /**
+     * The accounts of `exclude` the request left for a reason of their own, and that reason: each counts as its own
+     * judgement counts the reason, never as at its limit. An account of `exclude` it does not name counts as at its limit.
+     */
+    excludedBecause?: ReadonlyMap<string, IInferenceAccountUnavailable>;
+    /** A request that uses no quota (`count_tokens`): an account at its limit takes it as well. */
+    ignoreLimits?: boolean;
+    /**
+     * What of the request the proxy's price table cannot price (`inferenceAnthropicUnpricedRequest`): an API key with a
+     * monthly spend limit takes no such request (`model_unpriced`). A request that uses no quota ignores it.
+     */
+    unpriced?: string;
+    /**
+     * The session may move: when its account is of a later credential tier -- an Anthropic API key of a pool that names
+     * no credential -- a Claude account that can take the request takes it instead, and the route is `returned`.
+     */
+    returnToBetterTier?: boolean;
+}
+/** How a request is placed on a ChatGPT pool (`InferenceRouter.acquire`). */
+export interface IInferenceAcquireOptions {
+    /** The session's account: the request is judged on it alone, unless `returnToBetterTier` finds a better one. */
+    accountId?: string;
+    /** The accounts this request left already; it never goes back to them. */
+    exclude?: ReadonlySet<string>;
+    /** The accounts of `exclude` the request left for a reason of their own, as for a Claude pool (`IInferenceClaudeAcquireOptions`). */
+    excludedBecause?: ReadonlyMap<string, IInferenceAccountUnavailable>;
+    /** The request's `reasoning.effort`, which a ChatGPT account's model must accept; a key's model is OpenAI's to judge. */
+    reasoningEffort?: string;
+    /** The request's `service_tier`, which a ChatGPT account's model must offer (`auto` and `default` always). */
+    serviceTier?: string;
+    /** The Codex release the client read its catalog as: the model it names is checked against the catalog it was offered. */
+    clientVersion?: string;
+    /** A Responses request, which an OpenAI API key may take; a translated Messages request never goes to a key. */
+    apiKeys?: boolean;
+    /**
+     * What of the request the proxy's price table cannot price (`inferenceOpenAiUnpricedRequest`): an OpenAI API key with a
+     * monthly spend limit takes no such request (`model_unpriced`).
+     */
+    unpriced?: string;
+    /**
+     * The session may move: when its account is an OpenAI API key of a pool that names no credential, a ChatGPT account
+     * that can take the request takes it instead, and the route is `returned`. The gateway asks it only of a request that
+     * carries no account state, which never leaves its account.
+     */
+    returnToBetterTier?: boolean;
+}
 /** Model-preserving account selection. Refresh grants and native sign-ins remain the authority's. */
 export declare class InferenceRouter {
     private readonly options;
     /** ChatGPT catalogs by account and the Codex release they were read as. */
     private readonly catalogs;
     private readonly nativeCatalogs;
+    /** The model lists of the Claude accounts and the Anthropic API keys (`claudeCatalog`). */
     private readonly claudeCatalogs;
+    /** The model lists of the OpenAI API keys (`keyCatalog`). */
+    private readonly keyCatalogs;
     /** Why each Claude account was last reported refused, or routed on its last model list (`noteAccount`). */
     private readonly noted;
     private readonly active;
     private readonly cooldowns;
     /**
-     * The Claude accounts a billing error (HTTP 402) took out of rotation, by when it was seen, until the account service
-     * holds the problem; one it could not be told of stays here for the proxy's lifetime (`reportPaymentProblem`).
+     * The accounts a payment problem took out of rotation (`reportPaymentProblem`): a Claude account until the account
+     * service holds the problem -- one it could not be told of stays here for the proxy's lifetime -- and an API key until
+     * its spend cap ends, or for the proxy's lifetime.
      */
     private readonly paymentMarks;
     /** The accounts whose payment problem the account service could not be told of, each reported once. */
     private readonly paymentReportsFailed;
     /**
-     * The Anthropic API keys among the accounts the last pool read listed: the account service reads no usage for them,
-     * so nothing a request on one shows is handed to it.
+     * The API keys, Anthropic's and OpenAI's, among the accounts the last pool read listed: the account service reads no
+     * subscription usage for them, so no usage a request on one shows -- headers, tokens, a 429 -- is handed to it.
      */
     private apiKeyAccounts;
     private readonly now;
     constructor(options: IInferenceRouterOptions);
     private accounts;
     /**
-     * The policy's accounts of its provider and credential, and every eligible account's id of that pool: an account
-     * absent from both left the pool. An account whose lapse date passed is in neither -- it is never routed to again --
-     * and is named in `lapsed`. A Claude account and an Anthropic API key never share a pool, so a session placed on one
-     * kind never moves to the other.
+     * The credential tiers of the policy's pool, best first (`inferenceCredentialTiers`). A plan restriction leaves the
+     * API keys out, as a key has no plan, so a lease with `plans` never reaches a key.
+     */
+    private tiers;
+    /**
+     * The policy's accounts of its provider and credential tiers (`tiers`), and every eligible account's id of that pool:
+     * an account absent from both left the pool. An account whose lapse date passed is in neither -- it is never routed to
+     * again -- and is named in `lapsed`. A pool that names its credential serves that kind alone: Flex's API-key pool
+     * never takes a Claude account. One that names none spans both, and a session placed on a key returns to a Claude
+     * account once one can take its request.
      */
     private pool;
     /**
@@ -262,93 +449,145 @@ export declare class InferenceRouter {
     private sessionPool;
     /** An account's ChatGPT catalog as the Codex release `clientVersionArg` is offered it, or the package's default. */
     private catalog;
+    /** The models a Claude account or an Anthropic API key may use (`heldModels`). */
+    private claudeCatalog;
+    /** The models an OpenAI API key may use, as its `GET /v1/models` lists them (`heldModels`, `openAiKeyModel`). */
+    private keyCatalog;
     /**
-     * The models a Claude account or an Anthropic API key may use: the list read within the last minute, else read now.
+     * The models an account may use, from its list in `listsArg`: the list read within the last minute, else read now.
      * A model-list read that fails keeps the list read before for the account's revision, which the account routes on
      * meanwhile; with none, the account is unavailable for the failure's reason. A failure of the account's access or
      * sign-in makes it unavailable whether a list is held or not. Either way the failure is noted and its account is not
-     * read again, however many requests ask, for a minute -- or 5 s after a failed access (`holdClaudeFailure`).
+     * read again, however many requests ask, for a minute -- or 5 s after a failed access (`holdListFailure`).
      */
-    private claudeCatalog;
+    private heldModels;
     /**
-     * Records why a Claude account's model list or access failed, keeping the list held for its revision, and notes it:
+     * Records why an account's model list or access failed, keeping the list held for its revision, and notes it:
      * neither is read again for a minute after a failed model-list read or sign-in, or for 5 s after a failed access
      * (`access_failed`). The access is then tried again by reading the list again, even one read within the minute: a
      * single list read on recovery. Answers the held list when the account routes on it meanwhile -- only after a failed
-     * model-list read (`claudeCatalogRefusal`).
+     * model-list read (`heldListRefusal`).
      */
-    private holdClaudeFailure;
+    private holdListFailure;
     /**
-     * Reads the models a Claude account or an Anthropic API key may use. A rejected access is reported once: a sign-in is
-     * renewed, while a key is ended, so the account service refuses the second read. Every failure but an abort is a
-     * `ClaudeCatalogError` naming its reason.
+     * Reads the models an account may use through `listArg`. A rejected access (`accessRejected`) is reported once: a
+     * sign-in is renewed, while a key is ended, so the account service refuses the second read. Every failure but an abort
+     * is a `ModelListError` naming its reason.
      */
-    private readClaudeCatalog;
+    private readModelList;
     /**
      * Notes why a Claude account is refused, or routed on its last model list, now (`null`: neither), and reports a change
      * of it -- never the same reason again, however many requests meet it.
      */
     private noteAccount;
-    /** The model list a Claude account's revision was last read with, without reading it: `undefined` when none is held. */
-    private heldClaudeCatalog;
+    /** The model list an account's revision was last read with, without reading it: `undefined` when none is held. */
+    private heldList;
     /**
-     * Why a Claude account's model list or access keeps it from routing, as a request would find it now, before its next
-     * read is due: a failed access or sign-in, or a failed model-list read with no list held for its revision.
+     * Why an account's model list or access keeps it from routing, as a request would find it now, before its next read is
+     * due: a failed access or sign-in, or a failed model-list read with no list held for its revision. Only the accounts
+     * whose model list the router reads have one: Claude accounts and API keys.
      */
-    private catalogRefusal;
+    private listRefusal;
     /**
-     * The models every readable account of the Claude pool -- its Claude accounts, or its Anthropic API keys -- offers: a
-     * session may move to any of them, so a model one account lacks is not offered. Limits are the smallest any of them
-     * states; efforts are those all of them accept, and adaptive thinking is offered when all of them accept it. What one
-     * account does not state, the pool does not state.
+     * The Claude pool's models, from its best credential tier with a readable account (`inferenceCredentialTiers`): the
+     * Claude accounts' while one of them can read its model list, else the Anthropic API keys'. Within the tier, the
+     * models every readable account offers: a session may move to any of them, so a model one account lacks is not
+     * offered. Limits are the smallest any of them states; efforts are those all of them accept, and adaptive thinking is
+     * offered when all of them accept it. What one account does not state, the pool does not state.
      */
     claudeModels(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal): Promise<TInferenceClaudeModel[]>;
+    /** The models every readable account of one credential tier of a Claude pool offers; `undefined` when none is readable. */
+    private tierClaudeModels;
     /**
-     * Current model entitlements, merged conservatively across the account pool. A pool whose every account read needs a
-     * fresh sign-in -- ChatGPT rejected its access even when renewed, or the account service could not renew it -- answers
+     * The ChatGPT pool's models, from its best credential tier with a readable account (`inferenceCredentialTiers`): the
+     * ChatGPT sign-ins' current entitlements while one of them can read its catalog, else the OpenAI API keys' models
+     * (`keyTierModels`). A pool whose every ChatGPT account read needs a fresh sign-in -- ChatGPT rejected its access even
+     * when renewed, or the account service could not renew it -- and no key to fall back to answers
      * `account_needs_login`, so its caller asks for a sign-in rather than for the proxy.
      */
     models(policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal): Promise<TInferenceModel[]>;
     /**
-     * The pool's Codex model catalog in the Codex backend's own entry shape, read for the client's version.
-     * An entry shared by several accounts keeps only what every one of them offers.
+     * Current model entitlements, merged conservatively across the pool's ChatGPT sign-ins, and whether every account read
+     * needed a fresh sign-in.
+     */
+    private signInModels;
+    /**
+     * The models every readable OpenAI API key of the pool lists and flexharness describes (`openAiKeyModel`), newest first
+     * as `OPENAI_API_MODELS` orders them, the first the default: a session may move to any of the keys, so a model one key
+     * lacks is not offered. `undefined` when no key is readable.
+     */
+    private keyTierModels;
+    /**
+     * The pool's Codex model catalog in the Codex backend's own entry shape, read for the client's version through its
+     * ChatGPT sign-ins alone: an OpenAI API key never reaches the ChatGPT catalog connection, so a pool of keys alone has
+     * no Codex catalog here (`no_eligible_accounts`; Codex then uses its bundled one). An entry shared by several
+     * accounts keeps only what every one of them offers.
      */
     nativeModels(policyArg: IInferenceRoutingPolicy, clientVersionArg: string, signalArg: AbortSignal): Promise<TInferenceNativeModel[]>;
     private nativeCatalog;
     /**
-     * A ChatGPT account for one request. `clientVersion` is the Codex release the client read its catalog as, so the
-     * model it names is checked against the catalog it was offered.
-     */
-    acquire(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal, optionsArg?: {
-        accountId?: string;
-        exclude?: ReadonlySet<string>;
-        reasoningEffort?: string;
-        serviceTier?: string;
-        clientVersion?: string;
-    }): Promise<IInferenceRoute>;
-    /**
-     * A Claude account for one of Claude Code's requests, or an Anthropic API key for one of Flex's, chosen as `acquire`
-     * chooses: the pinned session account if it is still eligible, else the least busy account with the most headroom
-     * whose current reading shows it available -- every counted window under its threshold, no provider retry ahead --
-     * with no cooldown after a provider 429, and which lists the model. A key has no reading (`apiKeyLimits`): it is
-     * available unless it cools down after a 429.
+     * A ChatGPT account or an OpenAI API key for one request, chosen as `acquireClaude` chooses: the pinned session account
+     * if it is still eligible, else the best credential tier's least busy account with the most headroom
+     * (`inferenceCredentialTiers`). A ChatGPT account is judged on its usage reading and the Codex catalog of the release
+     * the client read it as (`clientVersion`). An OpenAI API key takes only a Responses request (`apiKeys`), never a
+     * translated Messages request, and is judged as an Anthropic API key is (`judgeListed`): a payment problem -- OpenAI's
+     * quota refusal -- or its month's spend at its limit keeps it out, a key with a limit takes no request it cannot price
+     * (`unpriced`, `model_unpriced`), and its model list (`GET /v1/models`, held a minute) must list the model. The accounts
+     * of `exclude` count as `excludedBecause` says, as for a Claude pool. `returnToBetterTier`: a session pinned to a key
+     * goes back to a ChatGPT account as soon as one can take its request, and the route says so (`returned`).
+     */
+    acquire(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal, optionsArg?: IInferenceAcquireOptions): Promise<IInferenceRoute>;
+    /** `acquire` among `accountsArg`, the pool's accounts or those of its better tiers. */
+    private routeOpenAi;
+    /**
+     * Counts an account the request left already (`exclude`) as its own judgement counts the reason the request left it
+     * for (`excludedBecause`): a payment problem joins the 402 list, a key whose spend could not be read or recorded is
+     * named in the 503, one that could not price the request joins the 400 list, one without the model leads to the 404,
+     * and every other reason to the 503 for want of an account. An account left for no reason of its own counts as at its
+     * limit (429). The switch is exhaustive: a new reason must be placed here.
+     */
+    private countLeft;
+    /**
+     * Judges an account whose model list the router reads -- a Claude account, an Anthropic or an OpenAI API key -- for one
+     * request, as placement takes it, recording on `stateArg` what keeps it out. A payment problem refuses it before anything
+     * else; without limits to route on (`limitsArg`) it is unavailable (`usage_unread`, a key's `spend_unread`); a key with
+     * a spend limit whose spend is recorded nowhere yet is refused (`spend_unrecorded`). Limits and cool-down are judged
+     * before any model list is read: an account that cannot take the request now is never read for it, its held list says
+     * whether it would serve the model, and without one it counts as at its limit, so a session on it moves rather than
+     * waiting for a list. A key's spend reading says nothing of the provider's rate limits, so only its own end ends a key's
+     * cool-down. A key with a spend limit then takes no request whose cost the price table cannot count (`unpriced`,
+     * Decision Q4), and the model list (`read`) must list the model. Answers the candidate's model and limits, or the refusal
+     * of an account that takes no request for a reason of its own -- a pinned refusal names it -- or `undefined`.
+     */
+    private judgeListed;
+    /**
+     * A Claude account or an Anthropic API key for one of Claude Code's requests, or an Anthropic API key for one of
+     * Flex's, chosen as `acquire` chooses: the pinned session account if it is still eligible, else the least busy account
+     * with the most headroom whose current reading shows it available -- every counted window under its threshold, no
+     * provider retry ahead -- with no cooldown after a provider 429, and which lists the model. A key is judged on its
+     * month's spend (`keyLimits`): at its spend limit it takes no request until the month ends, as an account at its limit,
+     * and a session on it moves; with a limit and no readable spend it is refused (`spend_unread`). A pool that names no
+     * credential places on its Claude accounts first and on its keys only when no Claude account can take the request, for
+     * whatever reason (`inferenceCredentialTiers`).
      * `ignoreLimits` serves a request that uses no quota (`count_tokens`) on an account at its limit as well. A pinned
      * account that takes no request for a reason of its own -- no usage reading, no model list, no access, or no such
      * model -- is refused naming the account and the reason (`InferenceRoutingError.reason`). An unpinned request whose
-     * chosen account's access fails goes to the next candidate.
+     * chosen account's access fails goes to the next candidate. `returnToBetterTier`: a session pinned to a key goes back
+     * to a Claude account as soon as one can take its request, and the route says so (`returned`).
      *
-     * A Claude account held with a payment problem -- Anthropic answered a request on it with a billing error (HTTP 402),
-     * as its usage reading says or this proxy saw (`reportPaymentProblem`) -- takes no request, `count_tokens` included,
-     * and is refused for the reason `payment_problem`. So is an account of `exclude` that `paymentExcluded` names: the
-     * request left it for a payment problem. Neither counts as at its limit: when such accounts are all that is left the
-     * refusal is a 402 `payment_problem` naming them, and while another account is merely at its limit the 429 stands.
-     */
-    acquireClaude(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal, optionsArg?: {
-        accountId?: string;
-        exclude?: ReadonlySet<string>;
-        paymentExcluded?: ReadonlySet<string>;
-        ignoreLimits?: boolean;
-    }): Promise<IInferenceClaudeRoute>;
+     * An account held with a payment problem -- Anthropic answered a request on it with a billing error (HTTP 402), or on
+     * a key with its organization's spend cap (HTTP 429 `enforced_spend_limit_reached`), as its usage reading says or this
+     * proxy saw (`reportPaymentProblem`) -- takes no request, `count_tokens` included, and is refused for the reason
+     * `payment_problem`. So is an account of `exclude` that `excludedBecause` names with a payment problem: the request
+     * left it for one. Neither counts as at its limit: when such accounts are all that is left the refusal is a 402
+     * `payment_problem` naming them, and while another account is merely at its limit the 429 stands. Any other account
+     * of `exclude` that `excludedBecause` names counts as its reason counts on the account's own judgement: a key whose
+     * spend could not be read is named in the 503, an account without the model leads to the 404, and every other reason
+     * to the 503 for want of an account -- never to the 429 of accounts at their limits.
+     */
+    acquireClaude(modelIdArg: string, policyArg: IInferenceRoutingPolicy, signalArg: AbortSignal, optionsArg?: IInferenceClaudeAcquireOptions): Promise<IInferenceClaudeRoute>;
+    /** `acquireClaude` among `accountsArg`, the pool's accounts or those of its better tiers. */
+    private routeClaude;
     /**
      * Tells the account service that Anthropic rejected the key of `generationArg`: it marks the account for a new key,
      * so the pool leaves it out from then on, and refuses the access the report asks for -- the answer expected here. A
@@ -357,17 +596,18 @@ export declare class InferenceRouter {
      */
     private rejectApiKey;
     /**
-     * The candidate a request goes to by the placement order (`authSwitchPlacementOrder`), or the refusal that says why there is
-     * none. A pinned request has its session's account as its one candidate, so the order only ever places new sessions.
-     * An account at its reserve is refused like one at its limit, and the refusal names the reserve. A pinned account
+     * The candidate a request goes to -- of the best credential tier, then by the placement order
+     * (`authSwitchPlacementOrder`) -- or the refusal that says why there is none. A pinned request has its session's
+     * account as its one candidate, so the order only ever places new sessions. An account at its reserve is refused like one at its limit, and the refusal names the reserve. A pinned account
      * that takes no request for a reason of its own (`refusal`) is refused with that account and reason.
      */
     private select;
     /**
      * The accounts as `agl proxy status` shows them: each judged as placement would judge it on the reading `heldArg`
-     * answers for it, which the caller read beforehand -- an Anthropic API key, which has none, as `apiKeyLimits` judges it -- with
+     * answers for it, which the caller read beforehand -- an API key on its month's spend (`keyLimits`), in dollars -- with
      * its cooldown, the requests it serves now, its lifecycle and where a new session of an unrestricted client of its
-     * pool would go (`placementRank`).
+     * provider would go (`placementRank`): a client that names no credential, so a provider's subscriptions rank before its
+     * keys (`inferenceCredentialTiers`).
      */
     accountStatus(accountsArg: readonly IInferenceAccount[], heldArg: (accountIdArg: string) => plugins.authswitchAuthority.IAuthSwitchUsageSnapshot | undefined): IInferenceAccountStatus[];
     /** Counts one request on an account until its release, which may be called more than once. */
@@ -379,15 +619,22 @@ export declare class InferenceRouter {
      */
     observe(accountIdArg: string, providerArg: TInferenceProvider, headersArg: Headers, statusArg: number): void;
     /**
-     * Anthropic refused a request on the Claude account with a billing error (HTTP 402 `billing_error`): the account is out
-     * of rotation at once, and the account service is told (`reportPaymentProblem`). Once it holds the problem the
-     * account's usage carries it, and that decides from then on, so the router's own mark is dropped; when the service
-     * cannot be told -- it is not running, or an older release that does not know the report -- the mark holds for as long
-     * as the proxy runs, and the failure is reported once. An API key's 402 is no payment problem the service holds.
+     * A provider refused a request on the account for a payment problem (`TInferencePaymentCause`): the account is out of
+     * rotation at once, and the refusal it now carries is answered. The problem is reported to the account service
+     * (`reportPaymentProblem`); once it holds the problem the account's usage carries it, and that decides from then on --
+     * until a re-check clears it, or a spend cap's month ends -- so the router's own mark is dropped. When the service
+     * cannot be told -- it is not running, or an older release that does not know the report or the account's kind --
+     * the mark holds, a spend cap until 00:00 UTC on the first day of the next month (`authSwitchSpendPeriod`), anything
+     * else for as long as the proxy runs, and the failure is reported once.
+     */
+    reportPaymentProblem(accountIdArg: string, causeArg: TInferencePaymentCause): IInferenceAccountUnavailable;
+    /**
+     * The payment problem an account is held with, as a refusal: by this proxy's own mark while it holds -- a spend cap's
+     * ends at its time -- or by the account's usage reading, which carries it once the account service holds it, with its
+     * cause (absent: `billing`) and, for a spend cap, when it ends; one whose spend cap ended holds nothing
+     * (`authSwitchPaymentProblemHeld`, the rule the account service holds it by).
      */
-    reportPaymentProblem(accountIdArg: string): void;
-    /** Whether a Claude account is held with a payment problem: by its usage reading, or by this proxy's own mark. */
-    private paymentRefused;
+    private paymentProblem;
     /** A provider answer's `Retry-After`, in seconds from now, in either of its forms. */
     retryAfterSeconds(headersArg: Headers): number | undefined;
     /**
@@ -395,11 +642,22 @@ export declare class InferenceRouter {
      * windows. An API key has no windows to estimate.
      */
     countTokens(accountIdArg: string, usageArg: plugins.authswitchUsageTokens.IAuthSwitchTokenUsage): void;
+    /**
+     * Takes the spend of an answer an API key served on the login `loginIdArg` (`inferenceAnthropicSpend`): it counts
+     * against the key's limit from now on and is reported to the account service (`spend`).
+     */
+    recordSpend(accountIdArg: string, loginIdArg: string | null, recordArg: IInferenceSpendRecord): void;
+    /**
+     * Says that an answer an API key served ended before its provider stated its usage, so nothing of it counts against
+     * the key's limit (`IInferenceSpendLedger.uncounted`).
+     */
+    uncountedSpend(accountIdArg: string, modelArg: string): void;
     /**
      * A provider 429 on the account. Only a definitive pre-stream refusal permits another account to be tried. The
      * account cools down for the provider's `Retry-After`, at most a day; without one, or with one already due, for 60
      * seconds or until the account service holds a usage read made after the 429 (see `cooldownUntil`), which the 429
-     * asks it to make at once. An API key, whose usage the account service does not read, cools down the 60 seconds.
+     * asks it to make at once. An API key, whose spend reading says nothing of the provider's rate limits, cools down
+     * the 60 seconds.
      */
     reportQuota(accountIdArg: string, retryAfterSecondsArg?: number): void;
 }