agl 40.4.0 → 40.5.1

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';
@@ -729,6 +767,27 @@ export interface IAuthSwitchClaudeSignInPrompt {
 /** The arguments a Claude sign-in runs Claude Code with, in the home its prompt names. */
 export const authSwitchClaudeSignInArguments: readonly string[] = ['auth', 'login'];
 
+/**
+ * A Claude Code process that keeps a sign-in from importing the login in its home, as the process table lists it:
+ * `on_home` when its home or credential store is the sign-in home, so it may still write there; `uninspectable` when
+ * its home or store could not be resolved and it did not start before the home was made, so it may run on it.
+ */
+export interface IAuthSwitchClaudeSignInHolder {
+  /** Null where the process table names none. */
+  pid: number | null;
+  /** When it started, to the second; null when the process table did not say. */
+  startedAt: string | null;
+  reason: 'on_home' | 'uninspectable';
+}
+
+/**
+ * The processes holding a sign-in, in the words the authswitch command line, the sign-in's own error and AGL's
+ * Accounts screen share: each by pid and start, and why it holds the sign-in.
+ */
+export const authSwitchClaudeSignInHoldersText = (holders: readonly IAuthSwitchClaudeSignInHolder[]): string =>
+  holders.map(holder => `pid ${holder.pid ?? 'unknown'}${holder.startedAt === null ? '' : ` (started ${holder.startedAt})`} `
+    + (holder.reason === 'on_home' ? 'runs on the sign-in home' : 'could not be inspected')).join('; ');
+
 /**
  * One Claude sign-in: Claude Code signs in to a Claude home the authority created for it alone, and once the login
  * is there and no Claude Code process runs on that home, the authority imports it with one rotating refresh -- the
@@ -737,16 +796,24 @@ export const authSwitchClaudeSignInArguments: readonly string[] = ['auth', 'logi
  * authority holds and which has ended (`needs_reauth`) signs that account in again; a working login, or one Claude
  * Code holds, is kept, and the sign-in fails saying so.
  *
- * `pending` while the authority waits for the login, with `prompt`; `committing` while it imports it; then
- * `complete` with `result`, `failed` or `outcome_unknown` with `error`, `cancelled`, or `interrupted` when the
- * authority stopped. A pending sign-in that holds no login at `expiresAt`, fifteen minutes after it started, fails.
- * A finished sign-in answers for ten minutes after `finishedAt`; after that its id is unknown (`not_found`).
- * Sign-ins live in the running authority only: after a restart their ids are unknown and their homes are gone.
+ * `pending` while the authority waits for the login, with `prompt`, and with `heldBy` once the login is there but
+ * Claude Code processes keep the authority from importing it; `committing` while it imports it; then `complete` with
+ * `result`, `failed` or `outcome_unknown` with `error`, `cancelled`, or `interrupted` when the authority stopped. A
+ * pending sign-in still pending at `expiresAt`, fifteen minutes after it started, fails and imports nothing: its error
+ * says whether a login had arrived and, if processes held it, names them. A finished sign-in answers for ten minutes
+ * after `finishedAt`; after that its id is unknown (`not_found`). Sign-ins live in the running authority only: after a
+ * restart their ids are unknown and their homes are gone.
  */
 export interface IAuthSwitchClaudeSignInOperation {
   id: string;
   state: 'pending' | 'committing' | 'complete' | 'failed' | 'cancelled' | 'interrupted' | 'outcome_unknown';
   prompt: IAuthSwitchClaudeSignInPrompt | null;
+  /**
+   * While `pending` with Claude Code's login in the home: the processes that keep the authority from importing it, as
+   * its last look found them; never empty. Null while no login is there, while nothing holds it, and once the sign-in
+   * is no longer pending.
+   */
+  heldBy: IAuthSwitchClaudeSignInHolder[] | null;
   result: { accountId: string; loginId: string } | null;
   error: string | null;
   createdAt: string;
@@ -1204,16 +1271,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 +1386,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 +1465,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 +1474,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;