agl 40.4.0 → 40.5.0

package/ts_authswitch/authority-apikeys.ts

@@ -0,0 +1,85 @@
+import * as plugins from './plugins.js';
+import type { TAuthSwitchApiKeyProvider } from './authority-contract.js';
+
+/**
+ * What the authority asks of a provider before it holds an API key, and how it tells the two providers' keys apart.
+ *
+ * Nothing here keeps, logs or returns a key, and no answer repeats a provider's error text, which could quote it.
+ */
+
+/**
+ * What a provider answered when asked for the models a key may use: `accepted`; `rejected`, the provider does not
+ * accept the key (HTTP 401); `forbidden`, the key is accepted but may not read the model list (HTTP 403, a restricted
+ * key). A verifier throws when the question could not be answered: the provider was not reached, timed out or answered
+ * anything else.
+ */
+export type TAuthSwitchApiKeyVerdict = 'accepted' | 'rejected' | 'forbidden';
+
+/** Asks `providerId` whether it accepts `apiKey`, within `signal` (`TAuthSwitchApiKeyVerdict`). */
+export type TAuthSwitchApiKeyVerifier = (providerId: TAuthSwitchApiKeyProvider, apiKey: string,
+  signal: AbortSignal) => Promise<TAuthSwitchApiKeyVerdict>;
+
+/**
+ * The verifier the authority runs: a read of the models the key may use, from Anthropic's `GET /v1/models` or
+ * OpenAI's, over `fetchArg` (the global fetch when unset), which nothing else reaches. Both reads come from
+ * `@modelprofile.com/flexharness-providers`, which sends the key only to its provider's API, follows no redirect, and
+ * throws fixed words that never carry the key or the provider's answer.
+ */
+export const authSwitchApiKeyVerifier = (fetchArg?: typeof fetch): TAuthSwitchApiKeyVerifier =>
+  async (providerId, apiKey, signal) => {
+    switch (providerId) {
+      case 'anthropic':
+        try {
+          await plugins.flexAnthropic.listAnthropicApiKeyModels({ apiKey }, { signal, ...(fetchArg ? { fetch: fetchArg } : {}) });
+          return 'accepted';
+        } catch (error) {
+          // Anthropic's model list refuses a key it does not accept with 401 and states no other key refusal.
+          if (error instanceof plugins.flexAnthropic.AnthropicApiKeyAuthError && error.status === 401) return 'rejected';
+          throw error;
+        }
+      case 'openai':
+        try {
+          await plugins.flexOpenAi.listOpenAiApiKeyModels({ apiKey }, { signal, ...(fetchArg ? { fetch: fetchArg } : {}) });
+          return 'accepted';
+        } catch (error) {
+          // OpenAI refuses a key it does not accept with 401, and a key that may not read models with 403.
+          if (error instanceof plugins.flexOpenAi.OpenAiApiKeyAuthError) {
+            if (error.status === 401) return 'rejected';
+            if (error.status === 403) return 'forbidden';
+          }
+          throw error;
+        }
+      default: {
+        const unhandledProvider: never = providerId;
+        return unhandledProvider;
+      }
+    }
+  };
+
+/** How each provider names itself and where its keys are made, as an instruction states it. */
+export const authSwitchApiKeyProviderNames: Readonly<Record<TAuthSwitchApiKeyProvider, { name: string; console: string }>> =
+  Object.freeze({
+    anthropic: { name: 'Anthropic', console: 'the Claude Console' },
+    openai: { name: 'OpenAI', console: 'the OpenAI platform' },
+  });
+
+/**
+ * How the providers' keys begin, as each documents them: Anthropic's API and Admin API keys begin `sk-ant-`
+ * (`sk-ant-api03`, `sk-ant-admin`; the Claude API reference, read 2026-10-21); OpenAI's project, service account and
+ * admin keys `sk-proj-`, `sk-svcacct-` and `sk-admin-` (OpenAI's own Codex, `OPENAI_API_KEY_PREFIXES`, and its API
+ * specification). OpenAI's older keys begin with a bare `sk-`, which Anthropic's share, so it tells nothing apart.
+ */
+const keyPrefixes: Readonly<Record<TAuthSwitchApiKeyProvider, readonly string[]>> = Object.freeze({
+  anthropic: ['sk-ant-'],
+  openai: ['sk-proj-', 'sk-svcacct-', 'sk-admin-'],
+});
+
+/**
+ * The provider whose keys begin the way `apiKey` does, when it is not `providerIdArg`: a key offered as the other
+ * provider's. The authority refuses it before any request, so a key is never sent to the provider it is not for.
+ */
+export const authSwitchApiKeyOtherProvider = (providerIdArg: TAuthSwitchApiKeyProvider,
+  apiKey: string): TAuthSwitchApiKeyProvider | null => {
+  const other: TAuthSwitchApiKeyProvider = providerIdArg === 'anthropic' ? 'openai' : 'anthropic';
+  return keyPrefixes[other].some((prefix) => apiKey.startsWith(prefix)) ? other : null;
+};

package/ts_authswitch/authority-contract.ts

@@ -1,12 +1,15 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
-import type { IAuthSwitchUsageRecheck, IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
+import type { IAuthSwitchUsageRecheck, IAuthSwitchUsageSnapshot,
+  TAuthSwitchPaymentProblemCause } from './classes.authorityusage.js';
 import type { IAuthSwitchCodexAppServerDetail, TAuthSwitchCodexAppServerRestart } from './authority-import-contract.js';
 export type { IAuthSwitchPaymentProblem, IAuthSwitchUsageRecheck, IAuthSwitchUsageSnapshot,
-  TAuthSwitchRecheckOutcome } from './classes.authorityusage.js';
+  TAuthSwitchPaymentProblemCause, TAuthSwitchRecheckOutcome } from './classes.authorityusage.js';
 import type { TAuthSwitchUsageObservation } from './authority-usageheaders.js';
 export type { TAuthSwitchUsageObservation } from './authority-usageheaders.js';
 import type { IAuthSwitchTokenUsage } from './authority-usagetokens.js';
 export type { IAuthSwitchTokenUsage } from './authority-usagetokens.js';
+import { isAuthSwitchModelId } from './authority-usagetokens.js';
+export type { IAuthSwitchSpendPeriod, IAuthSwitchSpendReading } from './authority-spend.js';
 
 /**
  * Why the authority declined, as a closed set a client branches on without reading the text.
@@ -85,8 +88,9 @@ export type TAuthSwitchRefusalCode =
    */
   | 'claude_home_unreadable'
   /**
-   * Anthropic did not accept the API key offered for an account, or could not be asked: nothing was stored, and the
-   * instruction says which of the two it was.
+   * The provider of the API key offered for an account -- Anthropic or OpenAI -- rejected it (401), accepted it without
+   * letting it read the model list (OpenAI's 403, a restricted key), or could not be asked: nothing was stored, and the
+   * instruction says which of the three it was and what to do, never repeating the provider's words.
    */
   | 'api_key_unverified';
 
@@ -169,6 +173,20 @@ export const asAuthSwitchRefusal = (error: unknown): IAuthSwitchRefusal | null =
   return { code, instruction };
 };
 
+/**
+ * The text the authority answers a malformed request with -- a member missing or unknown, a value of the wrong shape,
+ * a spend report naming an answer twice -- and no refusal beside it: the caller's own bug, never an instruction for an
+ * owner.
+ */
+export const authSwitchMalformedRequestText = 'Invalid authswitch authority request.';
+
+/**
+ * Whether an error answer is the authority's answer to a malformed request (`authSwitchMalformedRequestText`): its text
+ * alone, with no refusal marker. The same request is answered the same way every time it is sent.
+ */
+export const isAuthSwitchMalformedRequest = (error: unknown): boolean => typeof error === 'object' && error !== null
+  && 'errorText' in error && error.errorText === authSwitchMalformedRequestText && asAuthSwitchRefusal(error) === null;
+
 /** The longest account label, in UTF-16 code units. */
 export const authSwitchAccountLabelMaxLength = 128;
 
@@ -181,6 +199,13 @@ export const isAuthSwitchAccountLabel = (value: unknown): value is string => typ
   && value.trim() === value && value.length > 0 && value.length <= authSwitchAccountLabelMaxLength
   && !/[\u0000-\u001f\u007f]/.test(value);
 
+/** An API key account's `keyHint`: `…` and the key's last four characters, which tell keys apart and reveal nothing usable. */
+export const authSwitchKeyHint = (apiKey: string): string => `\u2026${apiKey.slice(-4)}`;
+
+/** Whether a value is a key hint as `authSwitchKeyHint` makes one: `…` and four printable characters. */
+export const isAuthSwitchKeyHint = (value: unknown): value is string => typeof value === 'string'
+  && /^\u2026[\x21-\x7e]{4}$/.test(value);
+
 /** The range of an account's usage threshold, in whole percent of each counted usage window. */
 export const authSwitchMaxUsageRange: Readonly<{ min: number; max: number }> = Object.freeze({ min: 1, max: 100 });
 
@@ -210,7 +235,7 @@ export const isAuthSwitchLapsesAt = (value: unknown): value is string => {
 
 /** Credential-free account management contract. Safe to import in browser code. */
 export type TAuthSwitchLoginPurpose = 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native'
-  | 'anthropic_api_key';
+  | 'anthropic_api_key' | 'openai_api_key';
 export type TAuthSwitchLoginHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'unverified' | 'pending_handoff' | 'handoff_quarantined' | 'removed';
 
 export interface IAuthSwitchAccount {
@@ -225,7 +250,7 @@ export interface IAuthSwitchAccount {
    * - `anthropic`: the organization UUID, Claude Code's `oauthAccount.organizationUuid` and the `orgId` of
    *   `claude auth status --json`; for an account on an Anthropic API key, which names no organization, `api-key`.
    * - `openai`: the ChatGPT account id (the `chatgpt_account_id` claim, a personal or team ChatGPT workspace),
-   *   which is not an OpenAI API organization.
+   *   which is not an OpenAI API organization; for an account on an OpenAI API key, `api-key`.
    *
    * Every daemon from 10.3.0 on states it; an older daemon leaves it out.
    */
@@ -246,6 +271,17 @@ export interface IAuthSwitchAccount {
    * request. Clearing the date makes it active again. See `authority-placement.ts`.
    */
   lapsesAt: string | null;
+  /**
+   * An API key account's spend limit per calendar month in UTC, in micro-dollars (`isAuthSwitchSpendLimitMicroUsd`);
+   * `null` for none, and always for an account on a sign-in. The limit counts what AGL's inference proxy relayed on the
+   * key, nothing else: at it, the proxy places nothing more on the key until the month ends.
+   */
+  spendLimitMicroUsd: number | null;
+  /**
+   * How an API key account's key ends, `…` and its last four characters, so the owner tells keys apart; `null` for an
+   * account on a sign-in, and for an Anthropic key the accounts service held before it kept hints.
+   */
+  keyHint: string | null;
   removed: boolean;
   revision: number;
   statusObservedAt: string;
@@ -290,8 +326,8 @@ export interface IAuthSwitchLogin {
    * `canBind`: a bind of this login is accepted now, decided by the conditions the bind checks. That is a ready,
    * daemon-held login an account that is not removed has selected, of the account's own provider: its ChatGPT login
    * for every runtime; its Claude login, with a verified import receipt and while the daemon's Claude renewer
-   * runs, for the `gateway` runtime alone; or its Anthropic API key (`anthropic_api_key`), for the `gateway` runtime
-   * alone as well.
+   * runs, for the `gateway` runtime alone; or its Anthropic or OpenAI API key (`anthropic_api_key`, `openai_api_key`),
+   * for the `gateway` runtime alone as well.
    */
   capabilities: { canReauthenticate: boolean; canBind: boolean; canPreuse: boolean };
 }
@@ -303,7 +339,7 @@ export interface IAuthSwitchBinding {
    * The runtime a login backs. `flex`, `opencode`, `claude` and `gateway` bindings are held and released by their
    * caller over the runtime socket; `codex` is the daemon's own managed Codex. A ChatGPT login backs every runtime;
    * a Claude login backs `gateway` alone, AGL's inference proxy, which sends Claude Code's own requests to the
-   * account, and so does an Anthropic API key, on which the proxy runs Flex's Claude models. `gateway` bindings are preemptible: removing the account, switching this host's Codex to its login, or
+   * account, and so does an Anthropic or OpenAI API key, on which the proxy relays requests at API prices. `gateway` bindings are preemptible: removing the account, switching this host's Codex to its login, or
    * moving its Claude login into a container home releases them in the same transaction instead of refusing, so a
    * login the authority hands to a native tool never has a second renewer.
    */
@@ -716,9 +752,11 @@ export type TAuthSwitchClaudeProofFailure =
 
 /**
  * What a Claude sign-in shows the person signing in: a command to run in a terminal, and the private Claude home
- * it signs in to. `command` is `claude auth login` with `CLAUDE_CONFIG_DIR` set to `directory`, quoted for a POSIX
- * shell; a caller that starts Claude Code itself runs `claude` with `authSwitchClaudeSignInArguments` and that
- * variable instead. The directory is a local path of the authority's user, like a managed Codex socket path.
+ * it signs in to. `command` is `claude auth login` with `CLAUDE_CONFIG_DIR` and `CLAUDE_SECURESTORAGE_CONFIG_DIR` both
+ * set to `directory`, quoted for a POSIX shell; a caller that starts Claude Code itself runs `claude` with
+ * `authSwitchClaudeSignInArguments` and those two variables instead. The second keeps the credential store in the home:
+ * inherited, it would send the new login to another store. The directory is a local path of the authority's user,
+ * like a managed Codex socket path.
  */
 export interface IAuthSwitchClaudeSignInPrompt {
   flow: 'terminal';
@@ -1204,16 +1242,94 @@ export interface IReq_AuthSwitchObserveUsage extends ITypedRequest {
 }
 
 /**
- * Management-only: Anthropic refused an inference request on the Claude login with a billing error (HTTP 402,
- * `billing_error`) at `observedAt`. The authority holds the login with the payment problem on its usage record
- * (`IAuthSwitchPaymentProblem`) and answers the held usage, which then carries it; the proxy routes nothing to the account
- * while it is held. Refused (`login_unavailable`) for any login but a Claude login the authority renews, and for one
- * with no usage record of its sign-in. The provider is not asked. An authority of 40.2.0 or older does not know the
- * method; the proxy then holds the account out of rotation itself, for as long as it runs.
+ * Management-only: the provider refused an inference request on the login for money at `observedAt`. On a Claude login
+ * that is a billing error (HTTP 402, `billing_error`): the authority holds the login with the payment problem on its usage
+ * record (`IAuthSwitchPaymentProblem`) until a usage read shows its subscription changed or a re-check reads it healthy.
+ * On an API key's login `cause` names the refusal (`TAuthSwitchPaymentProblemCause`; absent means `billing`): the
+ * authority holds the key with it, a `spend_cap` until 00:00 UTC on the first of the next month (`until`), any other
+ * cause until a re-check. Either way it answers the held usage, which then carries the problem, and the proxy routes
+ * nothing to the account while it is held. Refused (`login_unavailable`) for any other login, for a Claude login with
+ * no usage record of its sign-in, and for a Claude login with a cause other than `billing`. The provider is not asked.
+ * An authority of 40.2.0 or older does not know the method, and one of 40.3.0 refuses `cause` and every API key's
+ * login; the proxy then holds the account out of rotation itself, for as long as it runs.
  */
 export interface IReq_AuthSwitchReportPaymentProblem extends ITypedRequest {
   method: 'authswitch.authority.usage.paymentProblem';
-  request: { accountId: string; loginId: string; observedAt: string };
+  request: { accountId: string; loginId: string; observedAt: string; cause?: TAuthSwitchPaymentProblemCause };
+  response: { usage: IAuthSwitchUsageSnapshot };
+}
+
+/** Whether a value is a payment problem's cause (`TAuthSwitchPaymentProblemCause`). */
+export const isAuthSwitchPaymentProblemCause = (value: unknown): value is TAuthSwitchPaymentProblemCause =>
+  value === 'billing' || value === 'spend_cap' || value === 'quota';
+
+/**
+ * One answer AGL's inference proxy relayed on an API key, as it reports the answer's cost to the authority
+ * (`authswitch.authority.usage.spend`). The proxy prices the answer once, by the model that answered and the service
+ * tier the provider reported, and sends the same report until the authority acknowledged it.
+ */
+export interface IAuthSwitchSpendAnswer {
+  /** The proxy's id of the answer, a UUID: the same on every send of it, and the answer's identity in the ledger. */
+  answerId: string;
+  /** When the answer ended, ISO 8601 UTC; its calendar month in UTC is the period its cost counts in. */
+  endedAt: string;
+  /** The model that answered, as the provider named it (`isAuthSwitchModelId`). */
+  model: string;
+  /** The service tier the provider reported for the answer; null when it reported none. */
+  serviceTier: string | null;
+  /**
+   * What the answer cost, in whole micro-dollars (at most `authSwitchSpendAnswerMaxMicroUsd`); null when the proxy
+   * could not price it. An unpriced answer stops a key with a spend limit until the month ends or the limit is removed.
+   */
+  microUsd: number | null;
+  /** The price entry the answer was priced by (its checked date); null exactly when `microUsd` is null. */
+  priceSource: string | null;
+}
+
+/** The most answers one spend report carries. */
+export const authSwitchSpendAnswerBatchLimit = 64;
+
+/** The most one answer may cost, in micro-dollars: ten thousand dollars, far above any one answer's price. */
+export const authSwitchSpendAnswerMaxMicroUsd = 10_000_000_000;
+
+const spendAnswerKeys: readonly (keyof IAuthSwitchSpendAnswer)[] =
+  ['answerId', 'endedAt', 'model', 'serviceTier', 'microUsd', 'priceSource'];
+
+/** Whether a value is one spend report answer as the authority accepts it: the check it applies to every answer. */
+export const isAuthSwitchSpendAnswer = (value: unknown): value is IAuthSwitchSpendAnswer => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const answer = value as Record<string, unknown>;
+  return Object.keys(answer).length === spendAnswerKeys.length && spendAnswerKeys.every((key) => Object.hasOwn(answer, key))
+    && typeof answer.answerId === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(answer.answerId)
+    && typeof answer.endedAt === 'string' && Number.isFinite(Date.parse(answer.endedAt))
+    && new Date(answer.endedAt).toISOString() === answer.endedAt
+    && isAuthSwitchModelId(answer.model)
+    && (answer.serviceTier === null || (typeof answer.serviceTier === 'string'
+      && /^[a-z][a-z0-9_-]{0,63}$/.test(answer.serviceTier)))
+    && (answer.microUsd === null ? answer.priceSource === null
+      : Number.isSafeInteger(answer.microUsd) && (answer.microUsd as number) >= 0
+        && (answer.microUsd as number) <= authSwitchSpendAnswerMaxMicroUsd
+        && typeof answer.priceSource === 'string' && /^[\x21-\x7e](?:[\x20-\x7e]{0,126}[\x21-\x7e])?$/.test(answer.priceSource));
+};
+
+/** Whether a value is a spend report's answers: one to `authSwitchSpendAnswerBatchLimit` valid answers, each id once. */
+export const isAuthSwitchSpendAnswerBatch = (value: unknown): value is IAuthSwitchSpendAnswer[] => Array.isArray(value)
+  && value.length >= 1 && value.length <= authSwitchSpendAnswerBatchLimit && value.every(isAuthSwitchSpendAnswer)
+  && new Set(value.map((answer: IAuthSwitchSpendAnswer) => answer.answerId)).size === value.length;
+
+/**
+ * Management-only: what answers AGL's inference proxy relayed on an API key's login cost (`IAuthSwitchSpendAnswer`).
+ * The authority records the whole batch in one transaction in the key's monthly ledger and answers the key's usage,
+ * its spend reading included, once it committed. An answer it recorded already is no change, so the proxy sends a
+ * report again until it is acknowledged; an answer by a recorded id with other content refuses the whole batch
+ * (`invalid_input`, naming the id). Spend is recorded for a removed key too, whose ledger stays. Refused
+ * (`login_unavailable`) for any login but an API key's. An authority of 40.3.0 or older does not know the method; the
+ * proxy then serves no key with a spend limit.
+ */
+export interface IReq_AuthSwitchRecordSpend extends ITypedRequest {
+  method: 'authswitch.authority.usage.spend';
+  request: { accountId: string; loginId: string; answers: IAuthSwitchSpendAnswer[] };
   response: { usage: IAuthSwitchUsageSnapshot };
 }
 
@@ -1241,18 +1357,25 @@ export interface IReq_AuthSwitchBeginAdd extends ITypedRequest {
   response: { operation: IAuthSwitchOperation };
 }
 
+/** The providers whose API keys the authority holds as accounts. */
+export type TAuthSwitchApiKeyProvider = 'anthropic' | 'openai';
+
 /**
- * Adds an account on an Anthropic API key from the Claude Console, served on the MANAGEMENT socket alone. The
- * authority asks Anthropic for the key's models first and stores nothing unless Anthropic accepts the key
- * (`api_key_unverified`); it then seals the key like every login it holds and never answers it again, here or
- * anywhere else. The account's subject is a digest of the key, so the same key is one account: offered again while
- * held, it is refused (`invalid_input`); offered after its removal, it brings the account back. The login's purpose
- * is `anthropic_api_key`: it backs the `gateway` runtime alone, where AGL's inference proxy runs Flex's Claude
- * models on it, and nothing renews or revokes it -- the key is revoked in the Claude Console.
+ * Adds an account on an API key, served on the MANAGEMENT socket alone: an Anthropic key from the Claude Console or an
+ * OpenAI key from the OpenAI platform. A key that starts the way the other provider's keys do is refused before any
+ * request (`invalid_input`). The authority then asks the provider for the key's models and stores nothing unless the
+ * provider accepts the key (`api_key_unverified`; an OpenAI key that may not read models is refused with what to grant
+ * it); it seals the key like every login it holds and never answers it again, here or anywhere else, and keeps only
+ * how the key ends (`keyHint`). The account's subject is a digest of the key, so the same key is one account: offered
+ * again while held, it is refused (`invalid_input`); offered after its removal or after the provider rejected it, it
+ * brings the account back, with its month's spend. `spendLimitMicroUsd` sets the key's monthly spend limit
+ * (`isAuthSwitchSpendLimitMicroUsd`); left out, a new key has none and a returning key keeps the one it had. The login's
+ * purpose is `anthropic_api_key` or `openai_api_key`: it backs the `gateway` runtime alone, where AGL's inference
+ * proxy relays requests on it, and nothing renews or revokes it -- the key is revoked at the provider.
  */
 export interface IReq_AuthSwitchAddApiKey extends ITypedRequest {
   method: 'authswitch.authority.apikey.add';
-  request: { providerId: 'anthropic'; apiKey: string; label?: string };
+  request: { providerId: TAuthSwitchApiKeyProvider; apiKey: string; label?: string; spendLimitMicroUsd?: number };
   response: { account: IAuthSwitchAccount; loginId: string };
 }
 
@@ -1313,7 +1436,8 @@ export interface IReq_AuthSwitchRenameAccount extends ITypedRequest {
 /**
  * Sets an account's usage threshold (`maxUsagePercent`, see `isAuthSwitchMaxUsagePercent`), or clears it with `null`.
  * `expectedRevision` is the revision the caller read, so a change of an account that changed meanwhile is refused as
- * `account_changed`; a value that breaks the rule is refused as `invalid_input`.
+ * `account_changed`; a value that breaks the rule, and any threshold on an API key account, whose limit is its spend
+ * limit (`authswitch.authority.spendlimit`), is refused as `invalid_input`.
  */
 export interface IReq_AuthSwitchSetAccountMaxUsage extends ITypedRequest {
   method: 'authswitch.authority.maxusage';
@@ -1321,7 +1445,21 @@ export interface IReq_AuthSwitchSetAccountMaxUsage extends ITypedRequest {
   response: { account: IAuthSwitchAccount };
 }
 
-/** Lift only the saved reserve for whole hours 1..24, using the authority clock and expected revision. */
+/**
+ * Sets an API key account's monthly spend limit (`spendLimitMicroUsd`, see `isAuthSwitchSpendLimitMicroUsd`), or clears
+ * it with `null`. Refused (`invalid_input`) for an account on a sign-in, and for a value that breaks the rule; a change
+ * of an account that changed since `expectedRevision` is refused as `account_changed`.
+ */
+export interface IReq_AuthSwitchSetAccountSpendLimit extends ITypedRequest {
+  method: 'authswitch.authority.spendlimit';
+  request: { accountId: string; expectedRevision: number; spendLimitMicroUsd: number | null };
+  response: { account: IAuthSwitchAccount };
+}
+
+/**
+ * Lift only the saved reserve for whole hours 1..24, using the authority clock and expected revision. Refused
+ * (`invalid_input`) for an API key account, which has a spend limit instead of a reserve.
+ */
 export interface IReq_AuthSwitchLiftAccountReserve extends ITypedRequest {
   method: 'authswitch.authority.reserve.lift';
   request: { accountId: string; expectedRevision: number; hours: number };

package/ts_authswitch/authority-overview.ts

@@ -14,6 +14,7 @@ import { authSwitchPlacement, type IAuthSwitchPlacement, type TAuthSwitchAccount
 import { authSwitchSubscriptionFacts, type IAuthSwitchSubscriptionFact } from './authority-subscription.js';
 import type { IAuthSwitchPaymentProblem } from './classes.authorityusage.js';
 import { plainText } from './formatting.js';
+import { authSwitchUsdText } from './authority-spend.js';
 import { asOfTime, compactUntil } from './timetext.js';
 
 /** Where a tool runs on an account: a tool's own home the service switches, or a runtime AGL bound to it. */
@@ -269,6 +270,12 @@ const usageCell = (accountArg: IAuthSwitchAccountOverview, nowArg: number): stri
   const lines = accountArg.windows.map((windowArg) => `${plainText(windowName(windowArg))} `
     + `${windowPercentText(windowArg)} · ${compactUntil(windowArg.resetAt, nowArg)}`);
   const usage = accountArg.usage;
+  // A key's month in dollars, which its window, a percent of its limit, does not say -- nor anything without a limit.
+  if (usage?.reading?.kind === 'spend') {
+    const spend = usage.reading.spend;
+    lines.push(spend.limitMicroUsd === null ? `${authSwitchUsdText(spend.spentMicroUsd)} this month · no limit`
+      : `${authSwitchUsdText(spend.spentMicroUsd)} of ${authSwitchUsdText(spend.limitMicroUsd)} this month`);
+  }
   if (usage?.reading && usage.observedAt !== null) lines.push(`as of ${asOfTime(usage.observedAt, nowArg)}`);
   if (usage?.lastReadError?.rateLimited) {
     lines.push(`last read rate-limited; next ${asOfTime(usage.nextAttemptAt, nowArg, 'not scheduled')}`);

package/ts_authswitch/authority-placement.ts

@@ -4,12 +4,14 @@
  * command line and `agl proxy status` show it; an existing session keeps its account for the prompt cache and is never
  * placed again by it.
  *
- * Besides types, the module imports only the limit rule of `authority-usagelimit.ts` and the window reader it uses,
- * whose own imports carry nothing to a page, so it bundles for a browser with nothing behind it.
+ * Besides types, the module imports only the limit rule of `authority-usagelimit.ts`, the window reader it uses and the
+ * spend month of `authority-spend.ts`, whose own imports carry nothing to a page, so it bundles for a browser with
+ * nothing behind it.
  */
 import type { TAuthSwitchUsageReading } from './classes.authorityusage.js';
 import { authSwitchCountedWindows, authSwitchEffectiveMaxUsage } from './authority-usagelimit.js';
 import { authSwitchUsageWindowPercent, type IAuthSwitchUsageWindow } from './authority-usagewindows.js';
+import { authSwitchSpendMonthEnded, authSwitchSpendPeriod } from './authority-spend.js';
 
 /**
  * `active`: the account has no lapse date. `canceled`: its subscription ends at `lapsesAt`, which is still ahead.
@@ -66,6 +68,10 @@ const windowResetAt = (windowArg: IAuthSwitchUsageWindow, nowArg: number): numbe
  * divided by the hours until the window's deadline: its reset, or the account's lapse when that comes first, and at
  * least an hour. Usage that resets soon, or is lost when the account lapses, is worth more now than usage that stays for
  * days; placing by it uses that first and spares the accounts that reset later.
+ *
+ * An API key's spend reading whose month ended (`authSwitchSpendMonthEnded`, as `authSwitchUsageLimit` judges it) says
+ * nothing about the current month, which starts with nothing spent: its window counts as 0% used, with the end of the
+ * current month (`authSwitchSpendPeriod`) as its reset.
  */
 export const authSwitchPlacement = (readingArg: TAuthSwitchUsageReading | null, maxUsagePercentArg: number | null,
   lapsesAtArg: string | null, nowArg: number, reserveLiftUntilArg: string | null = null): IAuthSwitchPlacement => {
@@ -75,9 +81,11 @@ export const authSwitchPlacement = (readingArg: TAuthSwitchUsageReading | null,
     : lapsesAt - nowArg <= lapseHorizonMs ? 'last_resort' : 'normal';
   const threshold = authSwitchEffectiveMaxUsage(maxUsagePercentArg, reserveLiftUntilArg, nowArg) ?? 100;
   const windows = readingArg === null ? [] : authSwitchCountedWindows(readingArg, maxUsagePercentArg);
+  const spendMonthEnded = readingArg?.kind === 'spend' && authSwitchSpendMonthEnded(readingArg.spend, nowArg);
   const scores = windows.map((windowArg) => {
-    const headroom = Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg));
-    const deadline = Math.min(windowResetAt(windowArg, nowArg), lapsesAt);
+    const headroom = spendMonthEnded ? threshold : Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg));
+    const resetAt = spendMonthEnded ? Date.parse(authSwitchSpendPeriod(nowArg).end) : windowResetAt(windowArg, nowArg);
+    const deadline = Math.min(resetAt, lapsesAt);
     return headroom / (Math.max(deadline - nowArg, minimumDeadlineMs) / 3_600_000);
   });
   return { lifecycle, eligibility, score: scores.length ? Math.min(...scores) : null };

package/ts_authswitch/authority-runtime-contract.ts

@@ -19,9 +19,9 @@ export interface IReq_AuthSwitchBindAccount extends ITypedRequest {
     loginId: string;
     /**
      * The login's purpose: `openai_managed` for a ChatGPT login, `claude_host_native` for a Claude login,
-     * `anthropic_api_key` for an Anthropic API key.
+     * `anthropic_api_key` for an Anthropic API key, `openai_api_key` for an OpenAI API key.
      */
-    purpose: 'openai_managed' | 'claude_host_native' | 'anthropic_api_key';
+    purpose: 'openai_managed' | 'claude_host_native' | 'anthropic_api_key' | 'openai_api_key';
     runtime: IAuthSwitchBinding['runtime'];
     scopeId: string;
     incarnationId: string;

package/ts_authswitch/authority-spend.ts

@@ -0,0 +1,168 @@
+/**
+ * What an API key spent: the calendar month in UTC a key's spend counts in, the reading the accounts service answers
+ * for a key's login, the spend limit rule, and how an amount reads in US dollars.
+ *
+ * Every amount is a whole number of micro-dollars (a millionth of a US dollar), so sums stay exact. The module imports
+ * nothing, so it bundles for a browser with nothing behind it.
+ */
+
+/** Micro-dollars in one US dollar. */
+export const authSwitchMicroUsdPerUsd = 1_000_000;
+
+/** Micro-dollars in one US cent: a spend limit is a whole number of cents. */
+export const authSwitchMicroUsdPerCent = 10_000;
+
+/** One calendar month in UTC: the period a key's spend counts in and its limit applies to. */
+export interface IAuthSwitchSpendPeriod {
+  /** `YYYY-MM`. */
+  key: string;
+  /** 00:00 UTC on the month's first day, ISO 8601. */
+  start: string;
+  /** 00:00 UTC on the next month's first day, ISO 8601: when the month's spend resets. */
+  end: string;
+}
+
+const twoDigits = (valueArg: number): string => String(valueArg).padStart(2, '0');
+
+/** The calendar month in UTC that `nowArg` (epoch milliseconds) falls in. */
+export const authSwitchSpendPeriod = (nowArg: number): IAuthSwitchSpendPeriod => {
+  const at = new Date(nowArg);
+  const year = at.getUTCFullYear();
+  if (!Number.isFinite(nowArg) || year < 2000 || year > 9999) throw new RangeError('A spend period needs a time from 2000 to 9999.');
+  const month = at.getUTCMonth();
+  return {
+    key: `${year}-${twoDigits(month + 1)}`,
+    start: new Date(Date.UTC(year, month, 1)).toISOString(),
+    end: new Date(Date.UTC(year, month + 1, 1)).toISOString(),
+  };
+};
+
+/** Whether a value is a spend period's key, `YYYY-MM` from 2000-01 to 9999-12. */
+export const isAuthSwitchSpendPeriodKey = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^(?:[2-9]\d{3})-(?:0[1-9]|1[0-2])$/.test(valueArg);
+
+/**
+ * An API key's spend in one calendar month, as the accounts service holds it from what AGL's inference proxy reported:
+ * the answers the proxy relayed on the key in the month and what each cost by the proxy's price table. It counts AGL's
+ * traffic alone; whatever else used the key is not in it.
+ */
+export interface IAuthSwitchSpendReading {
+  /** The month, `YYYY-MM` (`IAuthSwitchSpendPeriod.key`). */
+  period: string;
+  /** 00:00 UTC on the month's first day, ISO 8601. */
+  periodStart: string;
+  /** 00:00 UTC on the next month's first day, ISO 8601: when the month's spend resets. */
+  resetAt: string;
+  /** What the month's priced answers cost, in micro-dollars. */
+  spentMicroUsd: number;
+  /** The key's monthly spend limit when the reading was answered, in micro-dollars; null for none. */
+  limitMicroUsd: number | null;
+  /** The answers counted in the month, priced or not. */
+  answers: number;
+  /**
+   * The answers of the month the proxy could not price: their cost is unknown, so a key with a limit takes no work
+   * until the month ends or its limit is removed.
+   */
+  unpricedAnswers: number;
+  /** When the month's newest answer ended, ISO 8601; null before the month's first answer. */
+  lastAnswerAt: string | null;
+}
+
+/** A spend limit's range in micro-dollars: one cent to one million dollars. */
+export const authSwitchSpendLimitRange: Readonly<{ min: number; max: number }> = Object.freeze({
+  min: authSwitchMicroUsdPerCent,
+  max: 1_000_000 * authSwitchMicroUsdPerUsd,
+});
+
+/**
+ * The spend limit rule, the one the authority applies to a key's monthly limit: a whole number of cents from
+ * `authSwitchSpendLimitRange.min` to `.max`, in micro-dollars. `null` clears a limit. A consumer validates with this
+ * rather than restating it; the authority answers any other value with the `invalid_input` refusal.
+ */
+export const isAuthSwitchSpendLimitMicroUsd = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= authSwitchSpendLimitRange.min && (valueArg as number) <= authSwitchSpendLimitRange.max
+  && (valueArg as number) % authSwitchMicroUsdPerCent === 0;
+
+/**
+ * A dollar amount as a person types it -- `50`, `12.5`, `$1000.00`, no thousands separator -- in micro-dollars, or
+ * `null` when the text is no such amount. It reads at most two decimals: an amount finer than a cent is no amount.
+ */
+export const authSwitchParseUsd = (textArg: string): number | null => {
+  const match = /^\$?(\d{1,13})(?:\.(\d{1,2}))?$/.exec(textArg.trim());
+  if (!match) return null;
+  const microUsd = Number(match[1]) * authSwitchMicroUsdPerUsd
+    + Number((match[2] ?? '').padEnd(2, '0')) * authSwitchMicroUsdPerCent;
+  return Number.isSafeInteger(microUsd) ? microUsd : null;
+};
+
+/**
+ * An amount in US dollars to the cent, with thousands separators: `$12.40`, `$1,000,000.00`. A part of a cent counts
+ * as a whole one, so a spend never reads lower than it is.
+ */
+export const authSwitchUsdText = (microUsdArg: number): string => {
+  if (!Number.isSafeInteger(microUsdArg) || microUsdArg < 0) throw new RangeError('An amount is a whole number of micro-dollars.');
+  const cents = Math.ceil(microUsdArg / authSwitchMicroUsdPerCent);
+  const dollars = String(Math.floor(cents / 100)).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return `$${dollars}.${twoDigits(cents % 100)}`;
+};
+
+/** The share of its limit a reading's month spent, in percent (above 100 once over it); null without a limit. */
+export const authSwitchSpendPercent = (readingArg: IAuthSwitchSpendReading): number | null =>
+  readingArg.limitMicroUsd === null ? null : readingArg.spentMicroUsd * 100 / readingArg.limitMicroUsd;
+
+/**
+ * Whether a reading's month ended by `nowArg` (epoch milliseconds): its `resetAt` passed. Such a reading says nothing
+ * about the next month, which starts with nothing spent; every rule that judges a reading decides this by it.
+ */
+export const authSwitchSpendMonthEnded = (readingArg: IAuthSwitchSpendReading, nowArg: number): boolean =>
+  Date.parse(readingArg.resetAt) <= nowArg;
+
+/**
+ * An answer AGL's inference proxy relayed on a key whose report the accounts service has not acknowledged yet: when it
+ * ended and what it cost.
+ */
+export interface IAuthSwitchSpendPending {
+  /** When the answer ended, ISO 8601 UTC: its calendar month in UTC is the one it counts in. */
+  endedAt: string;
+  /** What the answer cost, in micro-dollars; null when it could not be priced. */
+  microUsd: number | null;
+}
+
+/**
+ * A key's month as the proxy judges it at `nowArg` (epoch milliseconds): the held reading with the answers added whose
+ * report the accounts service has not acknowledged yet. Only the month `nowArg` falls in counts. When the held
+ * reading's month has ended, that month starts at nothing spent and no answer unpriced, under the reading's limit; of
+ * the pending answers only those that ended in it are added, priced and unpriced alike, so an answer from before
+ * midnight on the 1st counts in the month that ended, never in the new one. The reading's limit is kept: it is the limit
+ * the accounts service answered last.
+ */
+export const authSwitchSpendWithPending = (readingArg: IAuthSwitchSpendReading,
+  pendingArg: readonly IAuthSwitchSpendPending[], nowArg: number): IAuthSwitchSpendReading => {
+  const period = authSwitchSpendPeriod(nowArg);
+  const start = Date.parse(period.start);
+  const end = Date.parse(period.end);
+  const held = readingArg.period === period.key ? readingArg : null;
+  let spentMicroUsd = held?.spentMicroUsd ?? 0;
+  let answers = held?.answers ?? 0;
+  let unpricedAnswers = held?.unpricedAnswers ?? 0;
+  let lastAnswerAt = held?.lastAnswerAt ?? null;
+  for (const answer of pendingArg) {
+    const endedAt = Date.parse(answer.endedAt);
+    if (!(endedAt >= start && endedAt < end)) continue;
+    answers += 1;
+    if (answer.microUsd === null) unpricedAnswers += 1;
+    else spentMicroUsd += answer.microUsd;
+    if (lastAnswerAt === null || endedAt > Date.parse(lastAnswerAt)) lastAnswerAt = new Date(endedAt).toISOString();
+  }
+  return { period: period.key, periodStart: period.start, resetAt: period.end, spentMicroUsd,
+    limitMicroUsd: readingArg.limitMicroUsd, answers, unpricedAnswers, lastAnswerAt };
+};
+
+/**
+ * Whether a key's reading keeps it from taking work at `nowArg` (epoch milliseconds): it has a limit, its month has
+ * not ended, and the month spent the limit or holds an answer that could not be priced. A key without a limit is never
+ * stopped by its spend; once the month ended the reading says nothing about the next one.
+ */
+export const authSwitchSpendExhausted = (readingArg: IAuthSwitchSpendReading, nowArg: number): boolean =>
+  readingArg.limitMicroUsd !== null && !authSwitchSpendMonthEnded(readingArg, nowArg)
+  && (readingArg.spentMicroUsd >= readingArg.limitMicroUsd || readingArg.unpricedAnswers > 0);