agl 40.4.0 → 40.5.0

package/ts_authswitch/classes.authoritycli.ts

@@ -2,7 +2,9 @@ import type { IAuthSwitchAccount, IAuthSwitchClaudeHostLogin, IAuthSwitchClaudeH
   IAuthSwitchDoctorPage, IAuthSwitchUsageRecheck, IAuthSwitchUsageSnapshot, IAuthSwitchOperation, IAuthSwitchPreuseOperation, IAuthSwitchSnapshot, IReq_AuthSwitchDoctor,
   IReq_AuthSwitchAddApiKey, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchStartPreuse,
   IReq_AuthSwitchSwitchCodexNative, IReq_AuthSwitchReleaseCodexNative } from './authority-contract.js';
-import { asAuthSwitchRefusal, authSwitchClaudeSignInArguments, isAuthSwitchLapsesAt } from './authority-contract.js';
+import { asAuthSwitchRefusal, authSwitchClaudeSignInArguments, isAuthSwitchLapsesAt,
+  type TAuthSwitchApiKeyProvider } from './authority-contract.js';
+import { authSwitchParseUsd, authSwitchUsdText } from './authority-spend.js';
 import type { IAuthSwitchImportInventory, IAuthSwitchImportResult, IAuthSwitchImportStatus,
   IReq_AuthSwitchImportStatus, TAuthSwitchImportAction } from './authority-import-contract.js';
 import { AuthSwitchClient } from './classes.authorityclient.js';
@@ -13,7 +15,8 @@ import { describePreuseFailure, describePreuseLimit } from './preuse-text.js';
 import { plainText } from './formatting.js';
 import { authSwitchLimitList, authSwitchUsageLogin, readAuthSwitchAccountOverview, renderAuthSwitchAccountOverview,
   renderAuthSwitchLimitList } from './authority-overview.js';
-import { authSwitchPaymentProblemText, authSwitchRecheckOutcomeText } from './authority-subscription.js';
+import { authSwitchApiKeyPaymentProblemText, authSwitchPaymentProblemText,
+  authSwitchRecheckOutcomeText } from './authority-subscription.js';
 import { localDateTime } from './timetext.js';
 import { authSwitchAccountLifecycle, lapseHorizonMs } from './authority-placement.js';
 import { authSwitchPackageIdentity, authSwitchRelease } from './packageidentity.js';
@@ -31,7 +34,8 @@ export interface IAuthSwitchAuthorityCliClient {
   importStatus(request: IReq_AuthSwitchImportStatus['request']): Promise<IAuthSwitchImportStatus>;
   submitImport(sourceId: string, sourceDigest: string): Promise<IAuthSwitchImportResult>;
   beginAddOpenAi(operationId: string): Promise<IAuthSwitchOperation>;
-  addAnthropicApiKey(apiKey: string, label?: string): Promise<IReq_AuthSwitchAddApiKey['response']>;
+  addApiKey(providerId: TAuthSwitchApiKeyProvider, apiKey: string,
+    options: { label?: string; spendLimitMicroUsd?: number }): Promise<IReq_AuthSwitchAddApiKey['response']>;
   beginReauthOpenAi(operationId: string, accountId: string, loginId: string,
     purpose: 'openai_managed'): Promise<IAuthSwitchOperation>;
   getOperation(operationId: string): Promise<IAuthSwitchOperation>;
@@ -55,6 +59,8 @@ export interface IAuthSwitchAuthorityCliClient {
   setAccountMaxUsage(accountId: string, expectedRevision: number,
     maxUsagePercent: number | null): Promise<IAuthSwitchAccount>;
   setAccountLapse(accountId: string, expectedRevision: number, lapsesAt: string | null): Promise<IAuthSwitchAccount>;
+  setAccountSpendLimit(accountId: string, expectedRevision: number,
+    spendLimitMicroUsd: number | null): Promise<IAuthSwitchAccount>;
   close(reason?: Error): void;
 }
 
@@ -69,10 +75,10 @@ export interface IAuthSwitchAuthorityCliOptions {
   /** The Claude Code `account add claude` runs to sign in: `claude` as found on PATH unless stated. */
   claudeExecutable?: string;
   /**
-   * Reads the key `account add anthropic-api-key` adds: by default from standard input, a line typed at a terminal
-   * without echo or everything piped in. The signal aborts when the command is cancelled.
+   * Reads the key `account add anthropic-api-key|openai-api-key` adds: by default from standard input, a line typed at
+   * a terminal without echo or everything piped in. The signal aborts when the command is cancelled.
    */
-  readApiKey?: (signal: AbortSignal) => Promise<string>;
+  readApiKey?: (signal: AbortSignal, providerId: TAuthSwitchApiKeyProvider) => Promise<string>;
 }
 
 type TAuthorityCliCommand =
@@ -85,7 +91,7 @@ type TAuthorityCliCommand =
   | { kind: 'importSubmit'; sourceId: string; sourceDigest: string; json: boolean }
   | { kind: 'add'; json: boolean }
   | { kind: 'addClaude'; json: boolean }
-  | { kind: 'addApiKey'; label?: string; json: boolean }
+  | { kind: 'addApiKey'; providerId: TAuthSwitchApiKeyProvider; label?: string; spendLimitMicroUsd?: number; json: boolean }
   | { kind: 'useCodex'; accountId: string; json: boolean }
   | { kind: 'releaseCodex'; accountId: string; endRunningTurns: boolean; json: boolean }
   | { kind: 'releaseClaude'; accountId: string; endNativeSessions: boolean; json: boolean }
@@ -95,6 +101,7 @@ type TAuthorityCliCommand =
   | { kind: 'remove'; accountId: string; revoke: boolean; json: boolean }
   | { kind: 'setMaxUsage'; accountId: string; maxUsagePercent: number | null; json: boolean }
   | { kind: 'setLapse'; accountId: string; lapsesAt: string | null; json: boolean }
+  | { kind: 'setSpendLimit'; accountId: string; spendLimitMicroUsd: number | null; json: boolean }
   | { kind: 'get'; operationId: string; json: boolean }
   | { kind: 'cancel'; operationId: string; json: boolean }
   | { kind: 'resume'; operationId: string; json: boolean }
@@ -111,7 +118,7 @@ class AuthorityCliFailure extends Error {
   }
 }
 
-const usage = 'Usage: authswitch --help | authswitch --version [--json] | authswitch list [--json] | authswitch limits [--json] | authswitch account list [--json] | authswitch account add openai|claude [--json] | authswitch account add anthropic-api-key [--label <label>] [--json] | authswitch account use codex <account-id> [--json] | authswitch account release codex <account-id> [--end-running-turns] [--json] | authswitch account release claude <account-id> [--end-native-sessions] [--json] | authswitch account repair claude [--json] | authswitch account reauth <account-id> <login-id> [--json] | authswitch account recheck <account-id> [--json] | authswitch account remove <account-id> [--revoke] [--json] | authswitch account set <account-id> --max-usage <percent>|--clear|--lapses-at <date-time>|--clear-lapse [--json] | authswitch account operation get|cancel|resume <operation-id> [--json] | authswitch account preuse <account-id> <login-id>|--all [--prompt <text>] [--model <id>] [--json] | authswitch account preuse operation get|cancel|resume <operation-id> [--json] | authswitch authority doctor [--json] | authswitch authority import inventory [--json] | authswitch authority import status [--json] | authswitch authority import submit <source-id> --digest <source-digest> [--json] | authswitch authority service install|status|enable|start|stop | authswitch authority daemon';
+const usage = 'Usage: authswitch --help | authswitch --version [--json] | authswitch list [--json] | authswitch limits [--json] | authswitch account list [--json] | authswitch account add openai|claude [--json] | authswitch account add anthropic-api-key|openai-api-key [--label <label>] [--spend-limit <dollars>] [--json] | authswitch account use codex <account-id> [--json] | authswitch account release codex <account-id> [--end-running-turns] [--json] | authswitch account release claude <account-id> [--end-native-sessions] [--json] | authswitch account repair claude [--json] | authswitch account reauth <account-id> <login-id> [--json] | authswitch account recheck <account-id> [--json] | authswitch account remove <account-id> [--revoke] [--json] | authswitch account set <account-id> --max-usage <percent>|--clear|--lapses-at <date-time>|--clear-lapse|--spend-limit <dollars>|--clear-spend-limit [--json] | authswitch account operation get|cancel|resume <operation-id> [--json] | authswitch account preuse <account-id> <login-id>|--all [--prompt <text>] [--model <id>] [--json] | authswitch account preuse operation get|cancel|resume <operation-id> [--json] | authswitch authority doctor [--json] | authswitch authority import inventory [--json] | authswitch authority import status [--json] | authswitch authority import submit <source-id> --digest <source-digest> [--json] | authswitch authority service install|status|enable|start|stop | authswitch authority daemon';
 
 /** Every command, one per line, with what it does; `authswitch --help` prints it. */
 const help = (): string => `authswitch ${authSwitchRelease.version}
@@ -126,9 +133,11 @@ Usage
   authswitch account add openai|claude [--json]
                                              sign in a new account: a ChatGPT device sign-in, or Claude
                                              Code's own sign-in on this terminal
-  authswitch account add anthropic-api-key [--label <label>] [--json]
-                                             add an Anthropic API key, read from standard input and never
-                                             shown; AGL's proxy runs Flex's Claude models on it alone
+  authswitch account add anthropic-api-key|openai-api-key [--label <label>] [--spend-limit <dollars>] [--json]
+                                             add an Anthropic or OpenAI API key, read from standard input
+                                             and never shown, once its provider accepts it; AGL's proxy
+                                             relays requests on it at API prices, up to its monthly spend
+                                             limit in dollars when one is given
   authswitch account use codex <account-id> [--json]
                                              switch Codex on this host to that account
   authswitch account release codex <account-id> [--end-running-turns] [--json]
@@ -149,7 +158,8 @@ Usage
   authswitch account recheck <account-id> [--json]
                                              read a Claude account's profile and usage now; a healthy
                                              read clears a payment problem (a 402 billing error), so the
-                                             AGL proxy routes to it again
+                                             AGL proxy routes to it again; on an API key it lifts the
+                                             hold, and the provider's next answer shows whether it holds
   authswitch account remove <account-id> [--revoke] [--json]
                                              remove an account; --revoke also revokes its ChatGPT sign-in
   authswitch account set <account-id> --max-usage <percent>|--clear [--json]
@@ -161,6 +171,11 @@ Usage
                                              new sessions on it only as a last resort in its last day,
                                              and from then on routes nothing to it and moves its
                                              sessions; --clear-lapse makes it active again
+  authswitch account set <account-id> --spend-limit <dollars>|--clear-spend-limit [--json]
+                                             an API key's monthly spend limit (calendar month, UTC) on
+                                             what AGL's proxy relayed on it: at the limit the proxy places
+                                             nothing more on the key until the month ends;
+                                             --clear-spend-limit removes it
   authswitch account operation get|cancel|resume <operation-id> [--json]
                                              follow a sign-in that is still running
   authswitch account preuse <account-id> <login-id>|--all [--prompt <text>] [--model <id>] [--json]
@@ -286,13 +301,27 @@ const parse = (argv: readonly string[]): TAuthorityCliCommand | null => {
     && (argv.length === 3 || (argv.length === 4 && argv[3] === '--json'))) {
     return { kind: argv[2] === 'openai' ? 'add' : 'addClaude', json: argv[3] === '--json' };
   }
-  if (argv[0] === 'account' && argv[1] === 'add' && argv[2] === 'anthropic-api-key') {
+  if (argv[0] === 'account' && argv[1] === 'add' && (argv[2] === 'anthropic-api-key' || argv[2] === 'openai-api-key')) {
     // The key itself is never an argument: the shell history and the process list would keep it.
     const json = argv.at(-1) === '--json';
     const options = argv.slice(3, json ? -1 : undefined);
-    if (options.length === 0) return { kind: 'addApiKey', json };
-    if (options.length === 2 && options[0] === '--label') return { kind: 'addApiKey', label: options[1], json };
-    return null;
+    const command: Extract<TAuthorityCliCommand, { kind: 'addApiKey' }> = { kind: 'addApiKey',
+      providerId: argv[2] === 'anthropic-api-key' ? 'anthropic' : 'openai', json };
+    for (let index = 0; index < options.length; index += 2) {
+      const value = options[index + 1];
+      if (value === undefined) return null;
+      if (options[index] === '--label' && command.label === undefined) {
+        command.label = value;
+      } else if (options[index] === '--spend-limit' && command.spendLimitMicroUsd === undefined) {
+        // The authority states the range; a value it refuses comes back as its instruction.
+        const spendLimitMicroUsd = authSwitchParseUsd(value);
+        if (spendLimitMicroUsd === null) return null;
+        command.spendLimitMicroUsd = spendLimitMicroUsd;
+      } else {
+        return null;
+      }
+    }
+    return command;
   }
   if (argv[0] === 'account' && argv[1] === 'use' && argv[2] === 'codex' && isId(argv[3])
     && (argv.length === 4 || (argv.length === 5 && argv[4] === '--json'))) {
@@ -350,6 +379,12 @@ const parse = (argv: readonly string[]): TAuthorityCliCommand | null => {
     if (options.length === 2 && options[0] === '--lapses-at' && isAuthSwitchLapsesAt(options[1])) {
       return { kind: 'setLapse', accountId: argv[2], lapsesAt: options[1], json };
     }
+    if (options.length === 1 && options[0] === '--clear-spend-limit') {
+      return { kind: 'setSpendLimit', accountId: argv[2], spendLimitMicroUsd: null, json };
+    }
+    if (options.length === 2 && options[0] === '--spend-limit' && authSwitchParseUsd(options[1]!) !== null) {
+      return { kind: 'setSpendLimit', accountId: argv[2], spendLimitMicroUsd: authSwitchParseUsd(options[1]!), json };
+    }
     return null;
   }
   if (argv[0] === 'account' && argv[1] === 'operation'
@@ -475,8 +510,14 @@ class ScopedAuthorityCliClient implements IAuthSwitchAuthorityCliClient {
     return this.client.setAccountLapse(accountId, expectedRevision, lapsesAt, this.controller.signal);
   }
 
-  public addAnthropicApiKey(apiKey: string, label?: string): Promise<IReq_AuthSwitchAddApiKey['response']> {
-    return this.client.addAnthropicApiKey(apiKey, label, this.controller.signal);
+  public addApiKey(providerId: TAuthSwitchApiKeyProvider, apiKey: string,
+    options: { label?: string; spendLimitMicroUsd?: number }): Promise<IReq_AuthSwitchAddApiKey['response']> {
+    return this.client.addApiKey(providerId, apiKey, options, this.controller.signal);
+  }
+
+  public setAccountSpendLimit(accountId: string, expectedRevision: number,
+    spendLimitMicroUsd: number | null): Promise<IAuthSwitchAccount> {
+    return this.client.setAccountSpendLimit(accountId, expectedRevision, spendLimitMicroUsd, this.controller.signal);
   }
 
   public close(reason = new Error('Authswitch authority CLI closed.')): void {
@@ -491,16 +532,26 @@ const revocationLines: Record<IReq_AuthSwitchRemoveAccount['response']['revoked'
   not_applicable: 'The authority held no ChatGPT sign-in of its own for it, so nothing was revoked.',
 };
 
+/** An API key account's spend limit in words, as `account add` and `account set --spend-limit` state it. */
+const spendLimitText = (account: IAuthSwitchAccount): string => account.spendLimitMicroUsd === null
+  ? 'no monthly spend limit'
+  : `monthly spend limit ${authSwitchUsdText(account.spendLimitMicroUsd)} (calendar month, UTC); at it AGL places `
+    + 'nothing more on the key until the month ends';
+
 const renderApiKeyAdded = (account: IAuthSwitchAccount): string =>
-  `Added the Anthropic API key as account ${safe(account.label)} (${safe(account.id)}). AGL's inference proxy runs `
-  + 'Flex\'s Claude models on it; Claude Code keeps its own sign-ins.\n';
+  `Added the ${account.providerId === 'openai' ? 'OpenAI' : 'Anthropic'} API key`
+  + `${account.keyHint === null ? '' : ` ending ${safe(account.keyHint)}`} as account ${safe(account.label)} `
+  + `(${safe(account.id)}): ${spendLimitText(account)}. AGL's inference proxy relays requests on it at API prices.\n`;
+
+const renderSpendLimit = (account: IAuthSwitchAccount): string =>
+  `Account ${safe(account.label)} (${safe(account.id)}): ${spendLimitText(account)}.\n`;
 
 /**
  * The key `account add anthropic-api-key` adds, from standard input: a line typed at a terminal, which is not echoed
  * (a muted output for the line editor), or everything a pipe or file supplies. A cancelled command stops reading, so
  * neither an open pipe nor the terminal holds it.
  */
-const readStandardInputApiKey = async (signal: AbortSignal): Promise<string> => {
+const readStandardInputApiKey = async (signal: AbortSignal, providerId: TAuthSwitchApiKeyProvider): Promise<string> => {
   signal.throwIfAborted();
   const input = process.stdin;
   if (!input.isTTY) {
@@ -516,7 +567,7 @@ const readStandardInputApiKey = async (signal: AbortSignal): Promise<string> =>
       for (const chunk of chunks) chunk.fill(0);
     }
   }
-  process.stderr.write('Anthropic API key (not shown): ');
+  process.stderr.write(`${providerId === 'openai' ? 'OpenAI' : 'Anthropic'} API key (not shown): `);
   const muted = new plugins.stream.Writable({ write: (_chunk, _encoding, done) => done() });
   const lines = plugins.readline.createInterface({ input, output: muted, terminal: true });
   let cancel = (): void => undefined;
@@ -558,7 +609,9 @@ const renderLapse = (account: IAuthSwitchAccount, nowArg: number): string =>
 const renderRecheck = (account: IAuthSwitchAccount, recheck: IAuthSwitchUsageRecheck): string =>
   `Account ${safe(account.email ?? account.label)} (${safe(account.id)}): ${authSwitchRecheckOutcomeText(recheck.outcome)}\n`
   + (recheck.usage.paymentProblem
-    ? `Payment problem since ${localDateTime(recheck.usage.paymentProblem.at)}: ${authSwitchPaymentProblemText}\n`
+    ? `Payment problem since ${localDateTime(recheck.usage.paymentProblem.at)}: ${account.organizationId === 'api-key'
+      ? authSwitchApiKeyPaymentProblemText(recheck.usage.paymentProblem, account.providerId)
+      : authSwitchPaymentProblemText}\n`
     : 'No payment problem is held; the AGL proxy routes to it as its usage allows.\n');
 
 const renderRemoval = (removal: IReq_AuthSwitchRemoveAccount['response']): string =>
@@ -880,14 +933,17 @@ const renderCodexRelease = (result: IReq_AuthSwitchReleaseCodexNative['response'
 };
 
 /**
- * Runs Claude Code's own sign-in in the home the authority made for it, on this terminal. With `--json` its output
- * goes to stderr, so stdout stays JSON Lines. Answers why it could not start, or null once it exited, with its code.
+ * Runs Claude Code's own sign-in in the home the authority made for it, on this terminal, with its credential store
+ * pinned there too: an inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` would write the new login into another store, over
+ * whatever login that one holds, while the sign-in home never gets it. With `--json` its output goes to stderr, so
+ * stdout stays JSON Lines. Answers why it could not start, or null once it exited, with its code.
  */
 const runClaudeSignIn = (executable: string, directory: string, json: boolean,
   signal: AbortSignal): Promise<{ started: false; reason: string } | { started: true; exitCode: number | null }> =>
   new Promise(resolve => {
     const child = plugins.childProcess.spawn(executable, [...authSwitchClaudeSignInArguments], {
-      env: { ...process.env, CLAUDE_CONFIG_DIR: directory }, stdio: ['inherit', json ? 2 : 'inherit', 'inherit'],
+      env: { ...process.env, CLAUDE_CONFIG_DIR: directory, CLAUDE_SECURESTORAGE_CONFIG_DIR: directory },
+      stdio: ['inherit', json ? 2 : 'inherit', 'inherit'],
     });
     const stop = (): void => { child.kill('SIGTERM'); };
     signal.addEventListener('abort', stop, { once: true });
@@ -1379,8 +1435,9 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
         await writeDiagnostic('No authority account has this id. Run `authswitch account list` for the ids.\n');
         return 1;
       }
-      if (account.providerId !== 'anthropic' || !login || login.purpose !== 'claude_host_native') {
-        await writeDiagnostic('Only a Claude account with a Claude sign-in is re-checked.\n');
+      if (!login || !(login.purpose === 'anthropic_api_key' || login.purpose === 'openai_api_key'
+        || (account.providerId === 'anthropic' && login.purpose === 'claude_host_native'))) {
+        await writeDiagnostic('Only a Claude account with a Claude sign-in, or an API key, is re-checked.\n');
         return 1;
       }
       const recheck = await activeClient.recheckUsage(account.id, login.id);
@@ -1389,7 +1446,7 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
       }
       await writeOutput(command.json ? JSON.stringify({ accountId: account.id, loginId: login.id, ...recheck }) + '\n'
         : renderRecheck(account, recheck));
-      return recheck.outcome === 'healthy' ? 0 : 1;
+      return recheck.outcome === 'healthy' || recheck.outcome === 'cleared' ? 0 : 1;
     }
     if (command.kind === 'setMaxUsage') {
       const account = (await activeClient.snapshotAll()).accounts.find(item => item.id === command.accountId && !item.removed);
@@ -1418,10 +1475,29 @@ export const runAuthSwitchAuthorityCli = async (argv: readonly string[],
       await writeOutput(command.json ? JSON.stringify({ account: changed }) + '\n' : renderLapse(changed, now()));
       return 0;
     }
+    if (command.kind === 'setSpendLimit') {
+      const account = (await activeClient.snapshotAll()).accounts.find(item => item.id === command.accountId && !item.removed);
+      if (!account) {
+        await writeDiagnostic('No authority account has this id. Run `authswitch account list` for the ids.\n');
+        return 1;
+      }
+      const changed = await activeClient.setAccountSpendLimit(account.id, account.revision, command.spendLimitMicroUsd);
+      if (changed.id !== account.id || changed.spendLimitMicroUsd !== command.spendLimitMicroUsd) {
+        throw new AuthorityCliFailure('response');
+      }
+      await writeOutput(command.json ? JSON.stringify({ account: changed }) + '\n' : renderSpendLimit(changed));
+      return 0;
+    }
     if (command.kind === 'addApiKey') {
-      const apiKey = (await withinDeadline(() => (options.readApiKey ?? readStandardInputApiKey)(operationController.signal))).trim();
-      const added = await activeClient.addAnthropicApiKey(apiKey, command.label);
-      if (added.account.providerId !== 'anthropic' || added.account.removed) throw new AuthorityCliFailure('response');
+      const apiKey = (await withinDeadline(() => (options.readApiKey ?? readStandardInputApiKey)(operationController.signal,
+        command.providerId))).trim();
+      const added = await activeClient.addApiKey(command.providerId, apiKey, {
+        ...(command.label === undefined ? {} : { label: command.label }),
+        ...(command.spendLimitMicroUsd === undefined ? {} : { spendLimitMicroUsd: command.spendLimitMicroUsd }) });
+      if (added.account.providerId !== command.providerId || added.account.removed
+        || (command.spendLimitMicroUsd !== undefined && added.account.spendLimitMicroUsd !== command.spendLimitMicroUsd)) {
+        throw new AuthorityCliFailure('response');
+      }
       await writeOutput(command.json ? JSON.stringify(added) + '\n' : renderApiKeyAdded(added.account));
       return 0;
     }

package/ts_authswitch/classes.authorityclient.ts

@@ -10,6 +10,8 @@ import type {
   IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount, IReq_AuthSwitchSetAccountLapse, IReq_AuthSwitchSetAccountMaxUsage, IReq_AuthSwitchLiftAccountReserve,
   IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchSnapshot,
   IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage, IReq_AuthSwitchObserveUsage, IReq_AuthSwitchReportPaymentProblem,
+  IReq_AuthSwitchRecordSpend, IAuthSwitchSpendAnswer, TAuthSwitchPaymentProblemCause, TAuthSwitchApiKeyProvider,
+  IReq_AuthSwitchSetAccountSpendLimit,
   IReq_AuthSwitchRecheckUsage, IReq_AuthSwitchMoveClaudeHomeIn, IReq_AuthSwitchMoveClaudeHomeOut,
   IReq_AuthSwitchRegisterClaudeHome, IReq_AuthSwitchResolveClaudeHome, IReq_AuthSwitchUnregisterClaudeHome,
   IReq_AuthSwitchCancelClaudeSignIn, IReq_AuthSwitchGetClaudeSignIn, IReq_AuthSwitchStartClaudeSignIn,
@@ -118,7 +120,8 @@ export class AuthSwitchDaemonOutdatedError extends Error {
 /**
  * A snapshot page carries every member of this release's contract. `schemaVersion` is not bumped for an
  * additive member; version 3 adds the gateway runtime, every account states its `maxUsagePercent` from 38.3.0
- * on, its `lapsesAt` from 38.4.0 on, and its `reserveLiftUntil` with reserve lifts. Consumers still check their supported version.
+ * on, its `lapsesAt` from 38.4.0 on, its `reserveLiftUntil` with reserve lifts, and its `spendLimitMicroUsd` and
+ * `keyHint` with API keys of both providers. Consumers still check their supported version.
  */
 const assertCurrentSnapshot = (snapshot: IAuthSwitchSnapshot): IAuthSwitchSnapshot => {
   const page: Partial<IAuthSwitchSnapshot> = snapshot;
@@ -126,7 +129,9 @@ const assertCurrentSnapshot = (snapshot: IAuthSwitchSnapshot): IAuthSwitchSnapsh
     || !Array.isArray(page.accounts)
     || page.accounts.some(account => (account as Partial<IAuthSwitchAccount>).maxUsagePercent === undefined
       || (account as Partial<IAuthSwitchAccount>).lapsesAt === undefined
-      || (account as Partial<IAuthSwitchAccount>).reserveLiftUntil === undefined)) {
+      || (account as Partial<IAuthSwitchAccount>).reserveLiftUntil === undefined
+      || (account as Partial<IAuthSwitchAccount>).spendLimitMicroUsd === undefined
+      || (account as Partial<IAuthSwitchAccount>).keyHint === undefined)) {
     throw new AuthSwitchDaemonOutdatedError();
   }
   return snapshot;
@@ -239,14 +244,27 @@ export class AuthSwitchClient {
   }
 
   /**
-   * Reports that Anthropic refused an inference request on the Claude login with a billing error (HTTP 402) at
-   * `observedAt`, and returns the held usage, which then carries the payment problem (see
-   * `IReq_AuthSwitchReportPaymentProblem`). An authority of 40.2.0 or older refuses the method.
+   * Reports that the provider refused an inference request on the login for money at `observedAt` -- Anthropic's
+   * billing error (HTTP 402) on a Claude login, or on an API key's login the refusal `options.cause` names -- and
+   * returns the held usage, which then carries the payment problem (see `IReq_AuthSwitchReportPaymentProblem`). An
+   * authority of 40.2.0 or older refuses the method, one of 40.3.0 a `cause`.
    */
   public async reportPaymentProblem(accountId: string, loginId: string, observedAt: string,
-    signal?: AbortSignal): Promise<IReq_AuthSwitchReportPaymentProblem['response']['usage']> {
+    signal?: AbortSignal, options: { cause?: TAuthSwitchPaymentProblemCause } = {}): Promise<IReq_AuthSwitchReportPaymentProblem['response']['usage']> {
     return (await this.request<IReq_AuthSwitchReportPaymentProblem>('authswitch.authority.usage.paymentProblem',
-      { accountId, loginId, observedAt }, 10_000, false, signal)).usage;
+      { accountId, loginId, observedAt, ...(options.cause === undefined ? {} : { cause: options.cause }) },
+      10_000, false, signal)).usage;
+  }
+
+  /**
+   * Records what answers relayed on an API key's login cost (one to `authSwitchSpendAnswerBatchLimit`) and returns the
+   * key's usage once the batch committed (see `IReq_AuthSwitchRecordSpend`). An authority of 40.3.0 or older refuses
+   * the method.
+   */
+  public async recordSpend(accountId: string, loginId: string, answers: IAuthSwitchSpendAnswer[],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchRecordSpend['response']['usage']> {
+    return (await this.request<IReq_AuthSwitchRecordSpend>('authswitch.authority.usage.spend',
+      { accountId, loginId, answers }, 10_000, false, signal)).usage;
   }
 
   /**
@@ -429,13 +447,19 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchBeginAdd>('authswitch.authority.add',
       { operationId, providerId: 'openai', flow: 'device' }, 35_000, false, signal)).operation;
   }
-  /** Adds an Anthropic API key as an account (see `IReq_AuthSwitchAddApiKey`); the key is not answered back. */
-  public addAnthropicApiKey(apiKey: string, label?: string,
+  /**
+   * Adds an Anthropic or OpenAI API key as an account (see `IReq_AuthSwitchAddApiKey`); the key is not answered back.
+   * It waits up to 35 seconds: the authority gives the provider 15 seconds to answer whether it accepts the key.
+   */
+  public addApiKey(providerId: TAuthSwitchApiKeyProvider, apiKey: string,
+    options: { label?: string; spendLimitMicroUsd?: number } = {},
     signal?: AbortSignal): Promise<IReq_AuthSwitchAddApiKey['response']> {
     return this.request<IReq_AuthSwitchAddApiKey>('authswitch.authority.apikey.add',
-      label === undefined ? { providerId: 'anthropic', apiKey } : { providerId: 'anthropic', apiKey, label },
+      { providerId, apiKey, ...(options.label === undefined ? {} : { label: options.label }),
+        ...(options.spendLimitMicroUsd === undefined ? {} : { spendLimitMicroUsd: options.spendLimitMicroUsd }) },
       35_000, false, signal);
   }
+
   public async beginReauthOpenAi(operationId: string, accountId: string, loginId: string,
     purpose: 'openai_managed', signal?: AbortSignal): Promise<IReq_AuthSwitchBeginReauth['response']['operation']> {
     return (await this.request<IReq_AuthSwitchBeginReauth>('authswitch.authority.reauth',
@@ -484,6 +508,13 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchRenameAccount>('authswitch.authority.rename',
       { accountId, expectedRevision, label }, 35_000, false, signal)).account;
   }
+  /** Sets an API key account's monthly spend limit, or clears it with `null` (see `IReq_AuthSwitchSetAccountSpendLimit`). */
+  public async setAccountSpendLimit(accountId: string, expectedRevision: number, spendLimitMicroUsd: number | null,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchSetAccountSpendLimit['response']['account']> {
+    return (await this.request<IReq_AuthSwitchSetAccountSpendLimit>('authswitch.authority.spendlimit',
+      { accountId, expectedRevision, spendLimitMicroUsd }, 10_000, false, signal)).account;
+  }
+
   /** Sets an account's usage threshold, or clears it with `null` (see `IReq_AuthSwitchSetAccountMaxUsage`). */
   public async setAccountMaxUsage(accountId: string, expectedRevision: number, maxUsagePercent: number | null,
     signal?: AbortSignal): Promise<IReq_AuthSwitchSetAccountMaxUsage['response']['account']> {

package/ts_authswitch/classes.authoritydaemon.ts

@@ -8,9 +8,9 @@ import type {
   IReq_AuthSwitchRepairClaudeHost,
   IReq_AuthSwitchEvents, IReq_AuthSwitchGetBinding, IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations,
   IReq_AuthSwitchRemoveAccount,
-  IReq_AuthSwitchRenameAccount, IReq_AuthSwitchSetAccountLapse, IReq_AuthSwitchSetAccountMaxUsage, IReq_AuthSwitchLiftAccountReserve, IReq_AuthSwitchSnapshot,
+  IReq_AuthSwitchRenameAccount, IReq_AuthSwitchSetAccountLapse, IReq_AuthSwitchSetAccountMaxUsage, IReq_AuthSwitchSetAccountSpendLimit, IReq_AuthSwitchLiftAccountReserve, IReq_AuthSwitchSnapshot,
   IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage,
-  IReq_AuthSwitchObserveUsage, IReq_AuthSwitchReportPaymentProblem, IReq_AuthSwitchRecheckUsage,
+  IReq_AuthSwitchObserveUsage, IReq_AuthSwitchReportPaymentProblem, IReq_AuthSwitchRecheckUsage, IReq_AuthSwitchRecordSpend,
   IReq_AuthSwitchMoveClaudeHomeIn, IReq_AuthSwitchMoveClaudeHomeOut, IReq_AuthSwitchRegisterClaudeHome,
   IReq_AuthSwitchResolveClaudeHome, IReq_AuthSwitchUnregisterClaudeHome,
   IReq_AuthSwitchCancelClaudeSignIn, IReq_AuthSwitchGetClaudeSignIn, IReq_AuthSwitchStartClaudeSignIn,
@@ -20,14 +20,15 @@ import type {
 import type { IAuthSwitchManagedCodexRuntime, IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
   IReq_AuthSwitchResolveAccess, IReq_AuthSwitchStartManagedCodex, IReq_AuthSwitchStopManagedCodex,
   IReq_AuthSwitchUnbind } from './authority-runtime-contract.js';
-import { AuthSwitchRefusal } from './authority-contract.js';
+import { AuthSwitchRefusal, authSwitchMalformedRequestText, isAuthSwitchPaymentProblemCause,
+  isAuthSwitchSpendAnswerBatch } from './authority-contract.js';
 import type { IReq_AuthSwitchImportInventory, IReq_AuthSwitchImportStatus, IReq_AuthSwitchImportSubmit,
   TAuthSwitchImportSubmission } from './authority-import-contract.js';
 import { AuthSwitchAuthorityImport, AuthSwitchGrantImport,
   type IAuthSwitchAuthorityImportOptions } from './classes.authorityimport.js';
 import { authSwitchBindingCapabilityHash, AuthSwitchAuthorityBroker,
   type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
-import { AuthSwitchAuthorityDatabase, type IAuthSwitchAuthorityDatabaseOptions } from './classes.authoritydatabase.js';
+import { AuthSwitchAuthorityDatabase, authSwitchBindPurposes, type IAuthSwitchAuthorityDatabaseOptions } from './classes.authoritydatabase.js';
 import { ClaudeNativeAuthority, type IClaudeNativeAuthorityOptions } from './classes.claudeauthority.js';
 import { ClaudeHostCustody, publicClaudeHostRepair, publicClaudeNativeRelease } from './classes.claudehostcustody.js';
 import { ClaudeContainerAuthority, publicClaudeContainerHome,
@@ -124,9 +125,13 @@ function assertStatedLegacyImport(value: unknown): asserts value is TAuthSwitchA
 const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value)
   && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+/** Every one of `keys`, any of `optional`, and nothing else. */
+const hasOptionalKeys = (value: unknown, keys: readonly string[], optional: readonly string[]): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) && keys.every(key => Object.hasOwn(value, key))
+  && Object.keys(value).every(key => keys.includes(key) || optional.includes(key));
 // A malformed request is a caller's own bug, not an instruction for an owner, so it stays what it was:
 // its own text, no refusal marker. A client must not present it as something the owner can act on.
-const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError('Invalid authswitch authority request.'); };
+const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError(authSwitchMalformedRequestText); };
 const validBindingId = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
 const validBindingCapability = (value: unknown): value is string => typeof value === 'string'
   && /^[A-Za-z0-9_-]{43}$/.test(value);
@@ -241,6 +246,14 @@ export class AuthSwitchAuthorityDaemon {
         return this.claudeNative.withNativeUsageSource(context, action);
       },
       claudeStatus: options.claudeStatus ?? new ClaudeAccountStatus(),
+      spend: {
+        read: (accountId, loginId, nowArg) => this.database.readSpend(accountId, loginId, nowArg),
+        record: async (accountId, loginId, answers, nowArg) => {
+          const recorded = await this.database.recordSpend(accountId, loginId, answers, nowArg);
+          if (recorded.changed) this.broker.notifyChanged();
+          return recorded.reading;
+        },
+      },
       store: {
         read: (accountId, loginId) => this.database.readUsage(accountId, loginId),
         publishIfCurrent: async (context, previousUpdateId, next) => {
@@ -421,11 +434,19 @@ export class AuthSwitchAuthorityDaemon {
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchReportPaymentProblem>(
       'authswitch.authority.usage.paymentProblem', async request => {
-        if (!hasKeys(request, ['accountId', 'loginId', 'observedAt']) || !validHash(request.accountId)
+        if (!hasOptionalKeys(request, ['accountId', 'loginId', 'observedAt'], ['cause']) || !validHash(request.accountId)
           || !validHash(request.loginId) || typeof request.observedAt !== 'string'
           || !Number.isFinite(Date.parse(request.observedAt))
-          || new Date(request.observedAt).toISOString() !== request.observedAt) invalid();
-        return { usage: await this.usage.reportPaymentProblem(request.accountId, request.loginId, request.observedAt) };
+          || new Date(request.observedAt).toISOString() !== request.observedAt
+          || (request.cause !== undefined && !isAuthSwitchPaymentProblemCause(request.cause))) invalid();
+        return { usage: await this.usage.reportPaymentProblem(request.accountId, request.loginId, request.observedAt,
+          request.cause) };
+      }));
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchRecordSpend>(
+      'authswitch.authority.usage.spend', async request => {
+        if (!hasKeys(request, ['accountId', 'loginId', 'answers']) || !validHash(request.accountId)
+          || !validHash(request.loginId) || !isAuthSwitchSpendAnswerBatch(request.answers)) invalid();
+        return { usage: await this.usage.recordSpend(request.accountId, request.loginId, request.answers) };
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchRecheckUsage>(
       'authswitch.authority.usage.recheck', async request => {
@@ -611,10 +632,11 @@ export class AuthSwitchAuthorityDaemon {
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchAddApiKey>(
       'authswitch.authority.apikey.add', async request => {
-        if ((!hasKeys(request, ['providerId', 'apiKey']) && !hasKeys(request, ['providerId', 'apiKey', 'label']))
-          || request.providerId !== 'anthropic' || typeof request.apiKey !== 'string'
-          || (request.label !== undefined && typeof request.label !== 'string')) invalid();
-        return this.broker.addAnthropicApiKey(request.apiKey, request.label);
+        if (!hasOptionalKeys(request, ['providerId', 'apiKey'], ['label', 'spendLimitMicroUsd'])
+          || (request.providerId !== 'anthropic' && request.providerId !== 'openai') || typeof request.apiKey !== 'string'
+          || (request.label !== undefined && typeof request.label !== 'string')
+          || (request.spendLimitMicroUsd !== undefined && typeof request.spendLimitMicroUsd !== 'number')) invalid();
+        return this.broker.addApiKey(request.providerId, request.apiKey, request.label, request.spendLimitMicroUsd);
       }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchBeginReauth>(
       'authswitch.authority.reauth', async request => {
@@ -703,6 +725,14 @@ export class AuthSwitchAuthorityDaemon {
         return { account: await this.broker.setAccountMaxUsage(request.accountId, request.expectedRevision,
           request.maxUsagePercent) };
       }));
+    this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchSetAccountSpendLimit>(
+      'authswitch.authority.spendlimit', async request => {
+        if (!hasKeys(request, ['accountId', 'expectedRevision', 'spendLimitMicroUsd']) || typeof request.accountId !== 'string'
+          || typeof request.expectedRevision !== 'number'
+          || (request.spendLimitMicroUsd !== null && typeof request.spendLimitMicroUsd !== 'number')) invalid();
+        return { account: await this.broker.setAccountSpendLimit(request.accountId, request.expectedRevision,
+          request.spendLimitMicroUsd) };
+      }));
     this.managementRouter.addTypedHandler(this.handler<IReq_AuthSwitchLiftAccountReserve>(
       'authswitch.authority.reserve.lift', async request => {
         if (!hasKeys(request, ['accountId', 'expectedRevision', 'hours']) || typeof request.accountId !== 'string'
@@ -743,7 +773,7 @@ export class AuthSwitchAuthorityDaemon {
       'authswitch.authority.bind', async request => {
         if (!hasKeys(request, ['accountId', 'loginId', 'purpose', 'runtime', 'scopeId', 'incarnationId'])
           || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
-          || !['openai_managed', 'claude_host_native', 'anthropic_api_key'].includes(request.purpose)
+          || !authSwitchBindPurposes.includes(request.purpose)
           || typeof request.scopeId !== 'string'
           || typeof request.incarnationId !== 'string') invalid();
         return this.broker.bindAccount(request);