agl 40.4.0 → 40.5.1

package/ts_web/classes.accountsreadmodel.ts

@@ -5,9 +5,10 @@ import * as plugins from './accounts.plugins.js';
  * The Accounts screen as data.
  *
  * The accounts service is the one place accounts and their logins live; every harness only uses
- * them. So the screen is one list of the service's accounts, each ChatGPT or Claude account one
- * row: who it is, one status in plain words, a chip for each harness that uses it, and its usage as
- * meters. Identifiers, logins and technical facts appear only in a row's details.
+ * them. So the screen is one list of the service's accounts, each ChatGPT or Claude account and each
+ * OpenAI or Anthropic API key one row: who it is, one status in plain words, a chip for each harness
+ * that uses it, and its usage as meters -- a key's usage is its month's spend in dollars.
+ * Identifiers, logins and technical facts appear only on its page.
  *
  * Everything the screen says is decided here. The browser holds no account state of its own, keeps
  * no uncertainty flag and runs no timer, so a failed read can never leave a view locked -- the next
@@ -114,8 +115,12 @@ export interface IAccountsServiceStatus {
 
 export type TAccountsListState = 'unavailable' | 'empty' | 'complete' | 'partial';
 
-/** The accounts of one provider -- ChatGPT or Claude -- under that provider's name. */
+/**
+ * The accounts of one kind under its name: ChatGPT and Claude sign-ins, then OpenAI and Anthropic API keys. `id` is the
+ * provider for a sign-in group and `<provider>-api-key` for a key group.
+ */
 export interface IAccountGroup {
+  id: string;
   providerId: string;
   label: string;
   rows: IAccountRow[];
@@ -123,7 +128,7 @@ export interface IAccountGroup {
 
 export interface IAccountsList {
   state: TAccountsListState;
-  /** The listed accounts, one group per provider, in a fixed provider order. */
+  /** The listed accounts, one group per kind, in a fixed order: sign-ins by provider, then API keys by provider. */
   groups: IAccountGroup[];
   /** Removed accounts, kept behind a disclosure: a removal is often why a project lost access. */
   removedRows: IAccountRow[];
@@ -139,6 +144,9 @@ export type TAccountActionId =
   | 'liftReserve'
   | 'maxUsage'
   | 'clearMaxUsage'
+  | 'spendLimit'
+  | 'clearSpendLimit'
+  | 'addApiKey'
   | 'remove'
   | 'usage'
   | 'recheck'
@@ -188,6 +196,18 @@ export interface IAccountMeter {
   resetText: string;
 }
 
+/**
+ * An API key's month as its page says it: `$12.40 of $50.00 this month · AGL traffic only · as of 14:02`, or `Spent
+ * $12.40 this month · no limit · as of 14:02`, and how loud: attention from `spendAttentionPercent` of the limit,
+ * critical once the key is held at it.
+ */
+export interface IAccountSpend {
+  text: string;
+  tone: TAccountsTone;
+  /** What stands in place of the meter of a key without a limit, which has nothing to meter; empty with one. */
+  unmeteredText: string;
+}
+
 /** An account's usage as its row shows it. */
 export interface IAccountUsage {
   /**
@@ -200,6 +220,8 @@ export interface IAccountUsage {
   /** Why there is no current reading, when the service says. Empty otherwise. */
   problemText: string;
   meters: IAccountMeter[];
+  /** An API key's spend this month, under its meter; `null` for a sign-in. */
+  spend: IAccountSpend | null;
 }
 
 /** A device sign-in that has not finished, as the screen shows it. */
@@ -234,7 +256,9 @@ export interface IAccountStatus {
 
 /**
  * What a row's one status stands for, worst first: the service, a payment problem, a sign-in, a switch held on this
- * host, a hand-over, a renewal retrying, the usage limit, the reserve, a lifted reserve, no sign-in, and ready.
+ * host, a hand-over, a renewal retrying, the usage limit, the reserve, a lifted reserve, no sign-in, and ready. For an
+ * API key, a payment problem includes its provider's spend cap, a sign-in is a key its provider rejected, and the usage
+ * limit is its monthly spend limit (or an answer that could not be priced); a key has no reserve.
  */
 export type TAccountPillKind =
   | 'service'
@@ -254,13 +278,19 @@ export interface IAccountPill extends IAccountStatus {
   kind: TAccountPillKind;
 }
 
-/** The tightest usage window of an account, as its list row's one meter. */
+/**
+ * The tightest usage window of an account, as its list row's one meter. An API key's is its month: what it spent, in
+ * percent of its limit, or with no limit its spend alone, with nothing to meter (`percent` null).
+ */
 export interface IAccountPrimaryMeter {
   label: string;
-  percent: number;
-  /** `96%`. */
+  percent: number | null;
+  /** `96%`; a key's spend, `$12.40`. */
   valueText: string;
-  /** Full is neutral, at the account's maximum or past 90% wants attention, anything below is fine. */
+  /**
+   * Full is neutral; at the account's maximum or past 90% wants attention, a key's spend from `spendAttentionPercent` of
+   * its limit; anything below is fine.
+   */
   tone: TAccountsTone;
   /** The account's maximum usage, drawn as a tick; `null` without one. */
   threshold: number | null;
@@ -290,11 +320,11 @@ export interface IAccountLoginView {
   causeText: string;
   /** A new device sign-in for a login the service renews; absent for any other login. */
   reauth: IAccountActionSlot | null;
-  /** Who renews the login: the accounts service, the tool that holds it, or nobody. */
+  /** Who renews the login: the accounts service, the tool that holds it, or nobody; empty for an API key, never renewed. */
   renewedBy: string;
   /**
    * When the accounts service renews this login next. It is labelled as a renewal: read as "access
-   * expires" it sounds like the user's own sign-in is about to end, which it is not.
+   * expires" it sounds like the user's own sign-in is about to end, which it is not. Empty for an API key.
    */
   renewalText: string;
   /** When the service last looked at this login. */
@@ -317,8 +347,19 @@ export interface IAccountFact {
 export interface IAccountRow {
   key: string;
   providerId: string;
+  /** The group the row is listed in (`IAccountGroup.id`). */
+  groupId: string;
+  /** An API key's account: a spend limit instead of a maximum usage, and nothing to sign in again. */
+  apiKey: boolean;
+  /** An API key's monthly spend limit in micro-dollars, or `null` for none and for every sign-in. */
+  spendLimitMicroUsd: number | null;
+  /** What a removal does that the owner must know, said with the removal; empty for a sign-in. */
+  removeNote: string;
   label: string;
-  /** Email and plan as one line, each named when the provider did not report it. */
+  /**
+   * Email and plan as one line, each named when the provider did not report it; for an API key its provider and how the
+   * key ends.
+   */
   identityText: string;
   /** The account's email as the provider reported it; empty when it reported none. */
   email: string;
@@ -347,8 +388,9 @@ export interface IAccountRow {
    */
   limitStatus: IAccountStatus | null;
   /**
-   * A payment problem the account is held with -- Anthropic refused a request on it with a billing error (HTTP 402) --
-   * as a badge, and what it means with when it was seen; `null` and `''` while none is held or its usage was not read.
+   * A payment problem the account is held with -- Anthropic refused a request on it with a billing error (HTTP 402), or
+   * a key's provider refused it for billing, its spend cap or a used-up credit -- as a badge, and what it means with when
+   * it was seen; `null` and `''` while none is held or its usage was not read.
    */
   paymentStatus: IAccountStatus | null;
   paymentDetail: string;
@@ -364,7 +406,10 @@ export interface IAccountRow {
   operations: IAccountOperationView[];
   /** Details: the service account's logins. */
   logins: IAccountLoginView[];
-  /** Details: renaming, the usage threshold, removing, reading usage again and re-checking a payment problem. */
+  /**
+   * The page's own actions: renaming, the usage threshold (a key's spend limit), removing, reading usage again and
+   * re-checking a payment problem.
+   */
   manage: IAccountActionSlot[];
   /** Details: reading Flex's models of the account again. */
   flexActions: IAccountActionSlot[];
@@ -392,7 +437,7 @@ export interface IAccountsSummary {
   /** Listed accounts that take work now, of all listed. */
   ready: number;
   total: number;
-  /** How the ready ones split by provider: `2 ChatGPT · 3 Claude`. */
+  /** How the ready ones split: by provider for sign-ins, the keys together: `2 ChatGPT · 3 Claude · 1 API key`. */
   readyText: string;
   /** Accounts their usage holds back: at a limit, or reserved at their maximum. */
   limited: number;
@@ -412,6 +457,8 @@ export interface IAccountsView {
   add: IAccountActionSlot;
   /** Adding a Claude account: Claude Code signs in, in a terminal, to a home the accounts service made for it. */
   addClaude: IAccountActionSlot;
+  /** Adding an OpenAI or Anthropic API key, which the accounts service checks with the provider first. */
+  addApiKey: IAccountActionSlot;
   /**
    * Adding the account Codex on this host is signed in to, offered until the accounts service manages Codex's
    * sign-in on this host; `null` from then on.
@@ -624,10 +671,21 @@ const purposeLabel = (loginArg: TLogin): string => {
     case 'claude_host_native': return 'Claude Code on this host';
     case 'claude_container_setup': return 'Claude Code in containers';
     case 'opencode_native': return 'OpenCode sign-in';
-    case 'anthropic_api_key': return 'Anthropic API key for Flex';
+    case 'anthropic_api_key': return 'Anthropic API key';
+    case 'openai_api_key': return 'OpenAI API key';
   }
 };
 
+/** Whether a login is an API key's: a key is never renewed and never signed in again, only replaced by another key. */
+const isApiKeyLogin = (loginArg: TLogin): boolean => (
+  loginArg.purpose === 'anthropic_api_key' || loginArg.purpose === 'openai_api_key'
+);
+
+/** A key's provider by name, and where its keys are made and revoked. */
+const keyProvider = (providerIdArg: string): { name: string; console: string } => providerIdArg === 'openai'
+  ? { name: 'OpenAI', console: 'the OpenAI platform' }
+  : { name: 'Anthropic', console: 'the Claude Console' };
+
 type TNativeTool = NonNullable<TLogin['ownerTool']>;
 
 /**
@@ -661,7 +719,8 @@ const loginCauseText = (loginArg: TLogin): string => {
     case 'none': return '';
     case 'provider_unavailable': return 'The provider could not be reached.';
     case 'exchange_uncertain': return 'A sign-in was interrupted and its outcome is unknown.';
-    case 'provider_rejected': return 'The provider rejected the saved sign-in.';
+    case 'provider_rejected': return isApiKeyLogin(loginArg) ? 'The provider rejected the key.'
+      : 'The provider rejected the saved sign-in.';
     case 'native_owner': return 'Another tool on this host holds this login.';
   }
 };
@@ -685,6 +744,13 @@ const needsReauthCopy = (): ILoginStateCopy => ({
   statusText: 'This login needs a new sign-in.',
 });
 
+/** A key its provider no longer accepts: a key is never renewed, so it needs as much as a sign-in, said as a key. */
+const keyRejectedCopy = (): ILoginStateCopy => ({
+  state: 'needsReauth',
+  status: { text: 'Key rejected', tone: 'attention' },
+  statusText: 'The provider no longer accepts this key.',
+});
+
 /** A login a native tool renews: ownership, not health, and the screen says so. */
 const nativeOwnedCopy = (toolArg: TNativeTool): ILoginStateCopy => ({
   state: 'nativeOwned',
@@ -735,7 +801,7 @@ const daemonOwnedCopy = (loginArg: TLogin): ILoginStateCopy => {
  */
 const loginStateCopy = (loginArg: TLogin): ILoginStateCopy => {
   if (loginArg.health === 'handoff_quarantined') return quarantinedCopy();
-  if (loginArg.health === 'needs_reauth') return needsReauthCopy();
+  if (loginArg.health === 'needs_reauth') return isApiKeyLogin(loginArg) ? keyRejectedCopy() : needsReauthCopy();
   if (loginArg.ownerTool !== null) return nativeOwnedCopy(loginArg.ownerTool);
   return daemonOwnedCopy(loginArg);
 };
@@ -775,6 +841,10 @@ const preuseReason = (loginArg: TLogin): string => {
  */
 const signInWhere = (loginArg: TLogin): string => {
   if (loginArg.ownerTool !== null) return `Sign in again in ${nativeToolName(loginArg.ownerTool)}.`;
+  if (isApiKeyLogin(loginArg)) {
+    return `${keyProvider(loginArg.providerId).name} no longer accepts this key. Add a key it accepts with Add account,`
+      + ' then remove this one.';
+  }
   if (loginArg.capabilities.canReauthenticate || claudeSignsInAgain(loginArg)) return '';
   if (loginArg.providerId === 'anthropic') {
     return 'A hand-over of this sign-in could not be settled; This host shows what holds it.';
@@ -785,11 +855,11 @@ const signInWhere = (loginArg: TLogin): string => {
 
 /**
  * Whether a Claude sign-in of the account replaces this login: the service takes up a login it renews once that login
- * has ended, and a Claude sign-in of the same account lands on the same login.
+ * has ended, and a Claude sign-in of the same account lands on the same login. An Anthropic API key is no sign-in.
  */
 const claudeSignsInAgain = (loginArg: TLogin): boolean => (
-  loginArg.providerId === 'anthropic' && (loginArg.owner === 'daemon' || loginArg.owner === 'none')
-  && loginArg.health === 'needs_reauth'
+  loginArg.providerId === 'anthropic' && !isApiKeyLogin(loginArg)
+  && (loginArg.owner === 'daemon' || loginArg.owner === 'none') && loginArg.health === 'needs_reauth'
 );
 
 /** A new device sign-in for a login the service renews, or `null` where the service offers none. */
@@ -832,8 +902,8 @@ const loginView = (
       : copy.statusText,
     causeText: loginCauseText(loginArg),
     reauth: reauthSlot(loginArg, serviceArg),
-    renewedBy: renewedByLabel(loginArg),
-    renewalText: clockTime(loginArg.accessExpiresAt) || 'Not reported',
+    renewedBy: isApiKeyLogin(loginArg) ? '' : renewedByLabel(loginArg),
+    renewalText: isApiKeyLogin(loginArg) ? '' : clockTime(loginArg.accessExpiresAt) || 'Not reported',
     observedText: clockTime(loginArg.statusObservedAt) || 'Not reported',
     preuse: !loginArg.capabilities.canPreuse && loginArg.purpose !== 'openai_managed'
       ? null
@@ -850,8 +920,23 @@ const providerLabel = (providerIdArg: string): string => {
   }
 };
 
-/** The fixed order of the provider groups; any other provider follows under its own id. */
-const providerOrder = ['openai', 'anthropic'];
+/** The fixed order of the groups: sign-ins, then API keys; any other provider follows under its own id. */
+const groupOrder = ['openai', 'anthropic', 'openai-api-key', 'anthropic-api-key'];
+
+/** A group's heading. */
+const groupLabel = (groupIdArg: string): string => {
+  switch (groupIdArg) {
+    case 'openai-api-key': return 'OpenAI API keys';
+    case 'anthropic-api-key': return 'Anthropic API keys';
+    default: return providerLabel(groupIdArg);
+  }
+};
+
+/**
+ * Whether an account is an API key's: the accounts service names `api-key` as the tenancy of every key account, whose
+ * key names no organization (`IAuthSwitchAccount.organizationId`).
+ */
+const isApiKeyAccount = (accountArg: TAccount): boolean => accountArg.organizationId === 'api-key';
 
 const harnessLabel = (harnessArg: TAccountHarnessId): string => {
   switch (harnessArg) {
@@ -1036,7 +1121,8 @@ const codexSlot = (
   projectionArg: interfaces.IControllerAuthorityProjection,
   serviceArg: IAccountsServiceStatus,
 ): IAccountActionSlot | null => {
-  if (accountArg.providerId !== 'openai' || accountArg.removed) return null;
+  // An OpenAI API key is no ChatGPT sign-in: Codex on this host never switches to one.
+  if (accountArg.providerId !== 'openai' || accountArg.removed || isApiKeyAccount(accountArg)) return null;
   const host = interfaces.findHostCodexAssignment(projectionArg);
   if (host?.accountId === accountArg.id) return null;
   const reason = interfaces.findAuthorityDaemonLogin(projectionArg, accountArg.id) === 'no_login'
@@ -1077,7 +1163,10 @@ const codexReleaseSlot = (
 const claudeSignInStatusText = (signInArg: interfaces.TControllerClaudeSignIn): string => (
   signInArg.state === 'committing'
     ? 'Adding the account…'
-    : 'Waiting for Claude Code to sign in. Run the command in a terminal and follow Claude Code there.'
+    : signInArg.heldBy
+      ? 'Claude Code signed in. The account is added once these Claude Code processes have ended: '
+        + `${plugins.authswitchAuthority.authSwitchClaudeSignInHoldersText(signInArg.heldBy)}.`
+      : 'Waiting for Claude Code to sign in. Run the command in a terminal and follow Claude Code there.'
 );
 
 /** One Claude sign-in in progress, with the command that completes it and a terminal to run it in. */
@@ -1148,10 +1237,13 @@ interface IPillParts {
   service: IAccountsServiceStatus;
   status: IAccountStatus;
   worst: TAccountLoginState | null;
-  payment: boolean;
+  /** The payment problem's badge while one is held: `Payment problem`, or a key's `Spend cap reached`. */
+  payment: IAccountStatus | null;
   /** A switch of a tool on this host that runs on the account could not be settled. */
   held: boolean;
   limit: plugins.authswitchUsageLimit.IAuthSwitchUsageLimit | null;
+  /** What the pill calls the limit while the account is at it: `At limit`, a key's `At spend limit` or `Unpriced answer`. */
+  limitText: string;
   /** Until when the reserve is lifted, while it is. */
   liftedUntil: string | null;
 }
@@ -1169,14 +1261,14 @@ const accountPill = (partsArg: IPillParts): IAccountPill => {
     : textArg;
   if (partsArg.removed) return pill('removed', 'Removed', 'neutral');
   if (partsArg.service.state !== 'current') return pill('service', partsArg.status.text, partsArg.status.tone);
-  if (partsArg.payment) return pill('payment', 'Payment problem', 'critical');
+  if (partsArg.payment) return pill('payment', partsArg.payment.text, 'critical');
   if (partsArg.worst === 'quarantined' || partsArg.worst === 'needsReauth') {
     return pill('signIn', partsArg.status.text, partsArg.status.tone);
   }
   if (partsArg.held) return pill('held', 'Switch held', 'critical');
   if (partsArg.worst === 'pendingHandoff') return pill('handover', partsArg.status.text, partsArg.status.tone);
   if (partsArg.worst === 'retryWait') return pill('renewing', partsArg.status.text, partsArg.status.tone);
-  if (partsArg.limit?.state === 'exhausted') return pill('atLimit', back('At limit'), 'neutral');
+  if (partsArg.limit?.state === 'exhausted') return pill('atLimit', back(partsArg.limitText), 'neutral');
   if (partsArg.limit?.state === 'reserved') return pill('reserved', back('Reserved'), 'neutral');
   if (partsArg.liftedUntil) {
     return pill('lifted', `Reserve lifted · until ${plugins.authswitchPreuseText.localDateTime(partsArg.liftedUntil)}`, 'info');
@@ -1202,10 +1294,41 @@ const primaryMeter = (usageArg: IAccountUsage | null, thresholdArg: number | nul
   };
 };
 
-/** The list row's second line. */
+/**
+ * The share of a key's spend limit from which its spend wants attention: a display tone only, judged on the last reading
+ * the screen holds, never a limit the accounts service stores.
+ */
+export const spendAttentionPercent = 80;
+
+/**
+ * A key's month as the list row's meter: what it spent, in percent of its limit, which is neutral once full like a used
+ * window and wants attention from `spendAttentionPercent`; without a limit its spend alone.
+ */
+const spendMeter = (spendArg: interfaces.TControllerAccountSpendReading): IAccountPrimaryMeter => {
+  const spent = plugins.authswitchSpend.authSwitchUsdText(spendArg.spentMicroUsd);
+  const percent = plugins.authswitchSpend.authSwitchSpendPercent(spendArg);
+  if (percent === null) return { label: 'This month', percent: null, valueText: spent, tone: 'neutral', threshold: null };
+  return {
+    label: plugins.authswitchUsageWindows.authSwitchSpendWindowLabel,
+    percent: clampPercent(percent),
+    valueText: spent,
+    tone: percent >= 100 ? 'neutral' : percent >= spendAttentionPercent ? 'attention' : 'positive',
+    threshold: null,
+  };
+};
+
+/** An API key as it is named beside its name: its provider and how the key ends, when the service knows that. */
+const keyIdentityText = (accountArg: TAccount): string => {
+  const provider = keyProvider(accountArg.providerId).name;
+  return accountArg.keyHint === null ? `${provider} API key` : `${provider} API key ending ${accountArg.keyHint}`;
+};
+
+/** The list row's second line: who the account is -- email and plan, or a key's identity -- and who uses it. */
 const listMeta = (accountArg: TAccount, chipsArg: readonly IAccountHarnessChip[]): string => [
-  accountArg.email && accountArg.email !== accountArg.label ? accountArg.email : '',
-  accountArg.plan ? `${accountArg.plan} plan` : '',
+  ...isApiKeyAccount(accountArg) ? [keyIdentityText(accountArg)] : [
+    accountArg.email && accountArg.email !== accountArg.label ? accountArg.email : '',
+    accountArg.plan ? `${accountArg.plan} plan` : '',
+  ],
   chipsArg.filter((chipArg) => chipArg.unavailableReason === undefined)
     .map((chipArg) => harnessLabel(chipArg.harnessId)).join(', '),
 ].filter(Boolean).join(' · ');
@@ -1246,21 +1369,96 @@ const usageLimit = (
   return limit.state === 'available' ? null : limit;
 };
 
-const limitStatus = (limit: plugins.authswitchUsageLimit.IAuthSwitchUsageLimit | null): IAccountStatus | null => {
+/** Whether a key's month holds it for an answer that could not be priced rather than for what it spent. */
+const heldUnpriced = (spendArg: interfaces.TControllerAccountSpendReading): boolean => (
+  spendArg.limitMicroUsd !== null && spendArg.spentMicroUsd < spendArg.limitMicroUsd
+);
+
+/**
+ * The limit as the page's badge; a key's (`spendArg`, its month) is its spend limit, or an answer that could not be
+ * priced.
+ */
+const limitStatus = (
+  limit: plugins.authswitchUsageLimit.IAuthSwitchUsageLimit | null,
+  spendArg: interfaces.TControllerAccountSpendReading | null,
+): IAccountStatus | null => {
   if (!limit) return null;
   const reset = limit.resetAt ? `, resets ${plugins.authswitchPreuseText.localDateTime(limit.resetAt)}` : '';
+  if (spendArg) {
+    return { text: heldUnpriced(spendArg) ? `An answer could not be priced, so the key is held${reset}`
+      : `At its spend limit${reset}`, tone: 'critical' };
+  }
   return { text: `${sentence(plugins.authswitchUsageLimit.authSwitchUsageLimitText(limit))}${reset}`,
     tone: limit.state === 'reserved' ? 'attention' : 'critical' };
 };
 
-/** The payment problem a usage reading holds the account with, as a badge and what it means; `null` without one. */
-const paymentView = (usageArg: TUsage | null): { status: IAccountStatus; detail: string } | null => {
+/**
+ * The payment problem a usage reading holds the account with, as a badge and what it means; `null` without one, and
+ * once a key's spend cap reset (`authSwitchPaymentProblemHeld`). A key's says its cause.
+ */
+const paymentView = (accountArg: TAccount, usageArg: TUsage | null, nowArg: number): {
+  status: IAccountStatus; detail: string;
+} | null => {
   const problem = usageArg?.paymentProblem;
-  return problem ? { status: { text: 'Payment problem', tone: 'critical' },
-    detail: `${plugins.authswitchSubscription.authSwitchPaymentProblemText} Seen`
-      + ` ${plugins.authswitchPreuseText.localDateTime(problem.at)}.` } : null;
+  if (!problem || !plugins.authswitchSubscription.authSwitchPaymentProblemHeld(problem, nowArg)) return null;
+  const seen = `Seen ${plugins.authswitchPreuseText.localDateTime(problem.at)}.`;
+  if (!isApiKeyAccount(accountArg)) {
+    return { status: { text: 'Payment problem', tone: 'critical' },
+      detail: `${plugins.authswitchSubscription.authSwitchPaymentProblemText} ${seen}` };
+  }
+  const resets = problem.until ? ` The cap resets ${plugins.authswitchPreuseText.localDateTime(problem.until)}.` : '';
+  return { status: { text: problem.cause === 'spend_cap' ? 'Spend cap reached' : 'Payment problem', tone: 'critical' },
+    detail: `${plugins.authswitchSubscription.authSwitchApiKeyPaymentProblemText(problem, accountArg.providerId)} ${seen}`
+      + resets };
+};
+
+/** A key's spend limit as its field shows it, in dollars and cents: `50.00`. */
+export const spendLimitDraft = (spendLimitMicroUsdArg: number): string => (
+  (spendLimitMicroUsdArg / plugins.authswitchSpend.authSwitchMicroUsdPerUsd).toFixed(2)
+);
+
+/**
+ * Why a spend limit draft, in dollars, cannot be saved yet, or `''` when it can: an amount to the cent the service's own
+ * rule allows, other than the limit the key has.
+ */
+export const spendLimitReason = (draftArg: string, currentArg: number | null): string => {
+  if (draftArg.trim().length === 0) return 'Enter an amount in dollars.';
+  const value = plugins.authswitchSpend.authSwitchParseUsd(draftArg);
+  if (value === null) return 'Enter dollars and cents, such as 50 or 12.50.';
+  if (!interfaces.isControllerSpendLimitMicroUsd(value)) {
+    return `Enter an amount from ${plugins.authswitchSpend.authSwitchUsdText(interfaces.controllerSpendLimitRange.min)} to`
+      + ` ${plugins.authswitchSpend.authSwitchUsdText(interfaces.controllerSpendLimitRange.max)}.`;
+  }
+  return value === currentArg ? 'The spend limit is unchanged.' : '';
+};
+
+/** A key's spend limit in words, as its page and the screen after an added key state it. */
+export const spendLimitText = (spendLimitMicroUsdArg: number | null): string => spendLimitMicroUsdArg === null
+  ? 'No monthly limit'
+  : `${plugins.authswitchSpend.authSwitchUsdText(spendLimitMicroUsdArg)} per calendar month (UTC)`;
+
+/**
+ * Why the Add API key dialog cannot add yet, or `''` when it can: a key typed, an optional name the service's label rule
+ * accepts, and an optional spend limit in dollars its spend limit rule accepts.
+ */
+export const apiKeyReason = (keyTypedArg: boolean, labelArg: string, limitArg: string): string => {
+  if (!keyTypedArg) return 'Paste the key.';
+  if (labelArg.trim().length > 0) {
+    const name = renameReason(labelArg, '');
+    if (name) return name;
+  }
+  return limitArg.trim().length > 0 ? spendLimitReason(limitArg, null) : '';
 };
 
+/** What the screen says once a key is added: the account, how its key ends, and the spend limit it actually has. */
+export const apiKeyAddedNotice = (accountArg: TAccount): IAccountsNotice => ({
+  tone: 'positive',
+  // A key added again keeps the limit it had unless the add named one, so this is the account's limit, not the request's.
+  text: `Added ${accountArg.label}${accountArg.keyHint ? `, the key ending ${accountArg.keyHint}` : ''}. `
+    + (accountArg.spendLimitMicroUsd === null ? 'It has no monthly spend limit.'
+      : `Its monthly spend limit is ${spendLimitText(accountArg.spendLimitMicroUsd)}.`),
+});
+
 /**
  * Why a usage threshold draft cannot be saved yet, or `''` when it can: a whole percent the service's own rule
  * allows, other than the threshold the account has.
@@ -1315,11 +1513,17 @@ const serviceRow = (
   ));
   const usageLogin = accountArg.removed ? undefined : logins.find((loginArg) => loginArg.health !== 'removed');
   const usageRead = contextArg.usage.get(accountArg.id);
-  const usage = usageRead?.state === 'read' ? usageView(usageRead.usage, usageLogin?.owner ?? null) : null;
+  const usage = usageRead?.state === 'read' ? usageView(usageRead.usage, usageLogin?.owner ?? null, contextArg.now) : null;
   const rawLimit = accountArg.removed || usageRead?.state !== 'read' ? null
     : usageLimit(accountArg, usageRead.usage, contextArg.now);
-  const limit = limitStatus(rawLimit);
-  const payment = accountArg.removed || usageRead?.state !== 'read' ? null : paymentView(usageRead.usage);
+  // A key's month, while the read holds one: its limit, its meter and how the pill names the limit are its spend's.
+  const spend = usageRead?.state === 'read' && usageRead.usage.reading?.kind === 'spend' ? usageRead.usage.reading.spend : null;
+  const limit = limitStatus(rawLimit, spend);
+  const payment = accountArg.removed || usageRead?.state !== 'read' ? null
+    : paymentView(accountArg, usageRead.usage, contextArg.now);
+  const apiKey = isApiKeyAccount(accountArg);
+  const provider = keyProvider(accountArg.providerId);
+  const identity = apiKey ? keyIdentityText(accountArg) : identityText(accountArg.email, accountArg.plan);
   const liftedUntil = !accountArg.removed && accountArg.maxUsagePercent !== null
     && plugins.authswitchUsageLimit.authSwitchReserveLiftActive(accountArg.reserveLiftUntil, contextArg.now)
     ? accountArg.reserveLiftUntil! : null;
@@ -1329,8 +1533,14 @@ const serviceRow = (
   return {
     key: `service:${accountArg.id}`,
     providerId: accountArg.providerId,
+    groupId: apiKey ? `${accountArg.providerId}-api-key` : accountArg.providerId,
+    apiKey,
+    spendLimitMicroUsd: apiKey ? accountArg.spendLimitMicroUsd : null,
+    removeNote: apiKey
+      ? `AGL stops using the key. It stays valid at ${provider.name} until you revoke it in ${provider.console}.`
+      : '',
     label: accountArg.label,
-    identityText: identityText(accountArg.email, accountArg.plan),
+    identityText: identity,
     email: accountArg.email ?? '',
     removed: accountArg.removed,
     status,
@@ -1340,13 +1550,14 @@ const serviceRow = (
       service: contextArg.service,
       status,
       worst: worstLoginState(liveLogins),
-      payment: payment !== null,
+      payment: payment?.status ?? null,
       held: [...uses.values()].some((useArg) => useArg.host === 'quarantined'),
       limit: rawLimit,
+      limitText: !spend ? 'At limit' : heldUnpriced(spend) ? 'Unpriced answer' : 'At spend limit',
       liftedUntil,
     }),
-    listMeta: accountArg.removed ? identityText(accountArg.email, accountArg.plan) : listMeta(accountArg, harnesses),
-    primaryMeter: primaryMeter(usage, accountArg.maxUsagePercent),
+    listMeta: accountArg.removed ? identity : listMeta(accountArg, harnesses),
+    primaryMeter: spend ? spendMeter(spend) : primaryMeter(usage, accountArg.maxUsagePercent),
     backAt: rawLimit?.resetAt ?? null,
     harnesses,
     usageLoginId: usageLogin?.id ?? null,
@@ -1373,8 +1584,10 @@ const serviceRow = (
     logins: logins.map((loginArg) => loginView(loginArg, contextArg.service)),
     manage: [
       serviceSlot('rename', 'Rename', 'lucide:PenLine', contextArg.service, removed),
-      serviceSlot('maxUsage', 'Max usage', 'lucide:SlidersHorizontal', contextArg.service, removed),
-      ...(accountArg.maxUsagePercent !== null && accountArg.maxUsagePercent < 100
+      // A key's limit is its spend; a usage threshold and its reserve are a sign-in's.
+      ...(apiKey ? [serviceSlot('spendLimit', 'Spend limit', 'lucide:Wallet', contextArg.service, removed)]
+        : [serviceSlot('maxUsage', 'Max usage', 'lucide:SlidersHorizontal', contextArg.service, removed)]),
+      ...(!apiKey && accountArg.maxUsagePercent !== null && accountArg.maxUsagePercent < 100
         ? [serviceSlot('liftReserve', 'Lift reserve', 'lucide:Clock', contextArg.service, removed)] : []),
       serviceSlot('remove', 'Remove', 'lucide:Trash2', contextArg.service, removed),
       ...(usageLogin ? [serviceSlot('usage', 'Show latest usage', 'lucide:Gauge', contextArg.service)] : []),
@@ -1386,11 +1599,12 @@ const serviceRow = (
       : [],
     flexStatusText: flexConnectionId ? contextArg.flex.refreshStatuses.get(flexConnectionId) ?? '' : '',
     facts: [
-      { label: 'Provider', value: providerLabel(accountArg.providerId) },
+      { label: 'Provider', value: apiKey ? `${provider.name} (API key)` : providerLabel(accountArg.providerId) },
       ...(usageLogin ? [{ label: 'Usage', value: usageFact(usageRead, usage) }] : []),
       ...(usageRead?.state === 'read'
         ? plugins.authswitchSubscription.authSwitchSubscriptionFacts(usageRead.usage.reading) : []),
-      { label: 'Max usage', value: maxUsageFact(accountArg.maxUsagePercent) },
+      apiKey ? { label: 'Monthly spend limit', value: spendLimitText(accountArg.spendLimitMicroUsd) }
+        : { label: 'Max usage', value: maxUsageFact(accountArg.maxUsagePercent) },
       { label: 'Account reference', value: accountArg.id },
     ],
     accountId: accountArg.id,
@@ -1402,23 +1616,22 @@ const serviceRow = (
   };
 };
 
-/** The listed rows, one group per provider, ChatGPT first. */
+/** The listed rows, one group per kind: ChatGPT, Claude, OpenAI API keys, Anthropic API keys. */
 const accountGroups = (rowsArg: readonly IAccountRow[]): IAccountGroup[] => {
-  const providers = [...new Set(rowsArg.map((rowArg) => rowArg.providerId))].sort((leftArg, rightArg) => {
-    const left = providerOrder.indexOf(leftArg);
-    const right = providerOrder.indexOf(rightArg);
-    if (left !== right) return (left < 0 ? providerOrder.length : left) - (right < 0 ? providerOrder.length : right);
+  const groups = [...new Set(rowsArg.map((rowArg) => rowArg.groupId))].sort((leftArg, rightArg) => {
+    const left = groupOrder.indexOf(leftArg);
+    const right = groupOrder.indexOf(rightArg);
+    if (left !== right) return (left < 0 ? groupOrder.length : left) - (right < 0 ? groupOrder.length : right);
     return leftArg.localeCompare(rightArg);
   });
-  return providers.map((providerIdArg) => ({
-    providerId: providerIdArg,
-    label: providerLabel(providerIdArg),
-    rows: rowsArg.filter((rowArg) => rowArg.providerId === providerIdArg),
-  }));
+  return groups.map((groupIdArg) => {
+    const rows = rowsArg.filter((rowArg) => rowArg.groupId === groupIdArg);
+    return { id: groupIdArg, providerId: rows[0]!.providerId, label: groupLabel(groupIdArg), rows };
+  });
 };
 
 /**
- * The account list: the service's accounts, under their provider.
+ * The account list: the service's accounts, under their provider, the API keys apart from the sign-ins.
  *
  * The rows and the sentence under them come from the same read. The controller reads every page of
  * the service's snapshot, so a list that still does not end at its last row says so explicitly
@@ -1459,12 +1672,17 @@ const accountsSummary = (serviceArg: IAccountsServiceStatus, listArg: IAccountsL
   const needsYou = rows.filter((rowArg) => needsYouPills.includes(rowArg.pill.kind));
   const firstBack = limited.map((rowArg) => rowArg.backAt).filter((atArg): atArg is string => atArg !== null)
     .sort((leftArg, rightArg) => Date.parse(leftArg) - Date.parse(rightArg))[0];
+  const keys = rows.filter((rowArg) => rowArg.apiKey);
+  const readyKeys = keys.filter((rowArg) => readyPills.includes(rowArg.pill.kind)).length;
   return {
     ready: ready.length,
     total: rows.length,
-    readyText: listArg.groups.map((groupArg) => (
-      `${groupArg.rows.filter((rowArg) => readyPills.includes(rowArg.pill.kind)).length} ${groupArg.label}`
-    )).join(' · '),
+    readyText: [
+      ...listArg.groups.filter((groupArg) => !groupArg.rows[0]!.apiKey).map((groupArg) => (
+        `${groupArg.rows.filter((rowArg) => readyPills.includes(rowArg.pill.kind)).length} ${groupArg.label}`
+      )),
+      ...keys.length ? [`${readyKeys} API ${readyKeys === 1 ? 'key' : 'keys'}`] : [],
+    ].join(' · '),
     limited: limited.length,
     limitedText: firstBack ? `First back ${plugins.authswitchPreuseText.localDateTime(firstBack)}` : '',
     needsYou: needsYou.length,
@@ -1472,10 +1690,13 @@ const accountsSummary = (serviceArg: IAccountsServiceStatus, listArg: IAccountsL
   };
 };
 
-/** The accounts whose usage a screen reads: each listed account's usage login, by account id. */
-export const usageTargets = (viewArg: IAccountsView): { accountId: string; loginId: string }[] => (
+/**
+ * The accounts whose usage a screen reads: each listed account's usage login, by account id. `apiKey` marks a key, whose
+ * spend changes with every answer AGL relays on it, so the screen reads it again on every change it is told of.
+ */
+export const usageTargets = (viewArg: IAccountsView): { accountId: string; loginId: string; apiKey: boolean }[] => (
   viewArg.list.groups.flatMap((groupArg) => groupArg.rows).flatMap((rowArg) => (
-    rowArg.usageLoginId ? [{ accountId: rowArg.accountId, loginId: rowArg.usageLoginId }] : []
+    rowArg.usageLoginId ? [{ accountId: rowArg.accountId, loginId: rowArg.usageLoginId, apiKey: rowArg.apiKey }] : []
   ))
 );
 
@@ -1512,6 +1733,7 @@ export const accountsView = (
       'addClaude', 'Add Claude account', 'lucide:UserPlus', service,
       claudeSignIns.length ? 'A Claude sign-in is already waiting below.' : '',
     ),
+    addApiKey: serviceSlot('addApiKey', 'Add API key', 'lucide:KeyRound', service),
     adoptCodex: projection && interfaces.findHostCodexAssignment(projection)
       ? null
       : serviceSlot('adoptCodex', 'Add Codex\'s current sign-in', 'lucide:LogIn', service),
@@ -1752,13 +1974,14 @@ const asOfTime = (isoArg: string | null): string => {
  * `ownerArg` is who renews the login it was read for, which names why the usage of Claude Code's own sign-in is
  * missing.
  */
-export const usageView = (usageArg: TUsage, ownerArg: TLogin['owner'] | null = null): IAccountUsage => {
+export const usageView = (usageArg: TUsage, ownerArg: TLogin['owner'] | null = null,
+  nowArg: number = Date.now()): IAccountUsage => {
   const observed = asOfTime(usageArg.observedAt);
   const reading = usageArg.reading;
   const current = usageArg.state === 'current';
   if (ownerArg === 'claude_native' && usageArg.problem === 'access_unavailable') {
     return { freshness: usageArg.state === 'stale' && observed ? `Last known, as of ${observed}` : 'Unavailable',
-      current, problemText: claudeHomeUsageText, meters: usageMeters(reading) };
+      current, problemText: claudeHomeUsageText, meters: usageMeters(reading), spend: null };
   }
   const next = asOfTime(usageArg.nextAttemptAt);
   return {
@@ -1770,6 +1993,38 @@ export const usageView = (usageArg: TUsage, ownerArg: TLogin['owner'] | null = n
       ? `The provider limited usage reads, so the last one was refused${next ? `; the next read is at ${next}` : ''}.`
       : plugins.authswitchUsageWindows.authSwitchUsageProblemText(usageArg.problem),
     meters: usageMeters(reading),
+    spend: reading?.kind === 'spend' ? spendView(reading.spend, nowArg, observed) : null,
+  };
+};
+
+/**
+ * An API key's month in words: what AGL's traffic on it cost against its limit, or without one, how many answers could
+ * not be priced, and when the accounts service read the key's ledger for it (`asOfArg`, the reading's `observedAt`): the
+ * screen reads the month again on Refresh, Show latest usage and each change the controller announces, never on a
+ * timer, so the figure says its time. Attention from `spendAttentionPercent` of the limit, critical once the key is
+ * held, as of that reading. A reading whose month has ended says nothing of this one (`authSwitchSpendMonthEnded`).
+ */
+const spendView = (spendArg: interfaces.TControllerAccountSpendReading, nowArg: number, asOfArg: string): IAccountSpend => {
+  const usd = plugins.authswitchSpend.authSwitchUsdText;
+  const unpriced = spendArg.unpricedAnswers === 0 ? ''
+    : ` · ${spendArg.unpricedAnswers} ${spendArg.unpricedAnswers === 1 ? 'answer' : 'answers'} could not be priced`;
+  const asOf = asOfArg ? ` · as of ${asOfArg}` : '';
+  const unmeteredText = spendArg.limitMicroUsd === null
+    ? 'No monthly spend limit, so there is nothing to meter: AGL counts what the key costs.' : '';
+  if (plugins.authswitchSpend.authSwitchSpendMonthEnded(spendArg, nowArg)) {
+    return { text: `${usd(spendArg.spentMicroUsd)} in a month that has ended · Refresh reads this one${asOf}`,
+      tone: 'neutral', unmeteredText };
+  }
+  if (spendArg.limitMicroUsd === null) {
+    return { text: `Spent ${usd(spendArg.spentMicroUsd)} this month · no limit${unpriced}${asOf}`, tone: 'neutral',
+      unmeteredText };
+  }
+  const percent = plugins.authswitchSpend.authSwitchSpendPercent(spendArg) ?? 0;
+  return {
+    text: `${usd(spendArg.spentMicroUsd)} of ${usd(spendArg.limitMicroUsd)} this month · AGL traffic only${unpriced}${asOf}`,
+    tone: plugins.authswitchSpend.authSwitchSpendExhausted(spendArg, nowArg) ? 'critical'
+      : percent >= spendAttentionPercent ? 'attention' : 'neutral',
+    unmeteredText,
   };
 };