agl 40.4.0 → 40.5.0

package/ts_authswitch/authority-subscription.ts

@@ -4,7 +4,8 @@
  * The authswitch command line and AGL's Accounts screen both show these, so their words are written here, once. Besides
  * types, the module imports nothing, and therefore bundles for a browser with nothing behind it.
  */
-import type { TAuthSwitchRecheckOutcome, TAuthSwitchUsageReading } from './classes.authorityusage.js';
+import type { IAuthSwitchPaymentProblem, TAuthSwitchRecheckOutcome,
+  TAuthSwitchUsageReading } from './classes.authorityusage.js';
 
 /**
  * What the `subscription_status` values Claude's profile states mean, in plain words, by value. It is empty: no value's
@@ -54,6 +55,14 @@ export const authSwitchSubscriptionFacts = (readingArg: TAuthSwitchUsageReading
       .map((factArg) => ({ label: factArg.label, value: factArg.value }))
     : [];
 
+/**
+ * Whether a payment problem still holds the account at `nowArg` (epoch milliseconds): every one does until it is
+ * cleared, except a `spend_cap`, which holds nothing once its `until` passed. Every reader of a held problem decides by
+ * this, the authority included.
+ */
+export const authSwitchPaymentProblemHeld = (problemArg: IAuthSwitchPaymentProblem, nowArg: number): boolean =>
+  problemArg.cause !== 'spend_cap' || (problemArg.until !== undefined && Date.parse(problemArg.until) > nowArg);
+
 /**
  * What an account's payment problem means, as one sentence (`IAuthSwitchPaymentProblem`); the time it was seen is the
  * caller's to show.
@@ -62,6 +71,22 @@ export const authSwitchPaymentProblemText = 'Anthropic refused a request on this
   + ' (HTTP 402), so AGL routes nothing to it until a usage read shows its subscription changed or a re-check reads it'
   + ' healthy.';
 
+/**
+ * What an API key's payment problem means, as one sentence (`IAuthSwitchPaymentProblem`), by its cause and the key's
+ * provider; when it was seen, and when a spend cap resets, are the caller's to show.
+ */
+export const authSwitchApiKeyPaymentProblemText = (problemArg: IAuthSwitchPaymentProblem, providerIdArg: string): string => {
+  const provider = providerIdArg === 'openai' ? 'OpenAI' : 'Anthropic';
+  switch (problemArg.cause) {
+    case undefined: return `${provider} refused a request on this key with a billing error, so AGL routes nothing to it`
+      + ' until it is re-checked.';
+    case 'spend_cap': return `${provider} stopped this key at its monthly spend cap, so AGL routes nothing to it until the`
+      + ' cap resets, or until it is re-checked.';
+    case 'quota': return `${provider} reports this key's credit or spend limit used up, so AGL routes nothing to it until`
+      + ' it is re-checked.';
+  }
+};
+
 /** How a re-check went, as one sentence. */
 export const authSwitchRecheckOutcomeText = (outcomeArg: TAuthSwitchRecheckOutcome): string => {
   switch (outcomeArg) {
@@ -71,5 +96,7 @@ export const authSwitchRecheckOutcomeText = (outcomeArg: TAuthSwitchRecheckOutco
     case 'profile_missing': return 'Claude did not answer the account\'s profile.';
     case 'mismatch': return 'Claude answered with a different account or organization.';
     case 'read_failed': return 'The account could not be read now; the next read is shown with its usage.';
+    case 'cleared': return 'The key\'s hold is lifted: AGL places requests on it again, and the provider\'s next answer '
+      + 'shows whether it takes them.';
   }
 };

package/ts_authswitch/authority-usagelimit.ts

@@ -2,17 +2,18 @@
  * Whether an account's usage reading still lets it take work: the one rule the inference proxy's placement, Flex's
  * dispatch and resume, the authswitch command line and AGL's Accounts screen all decide by.
  *
- * Besides types, the module imports only the window reader of `authority-usagewindows.ts`, 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 window reader of `authority-usagewindows.ts` and the spend rule 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 type { TAuthSwitchProviderUsageReading, TAuthSwitchUsageReading } from './classes.authorityusage.js';
 import { authSwitchUsageWindowName, authSwitchUsageWindowPercent, authSwitchUsageWindows,
   type IAuthSwitchUsageWindow } from './authority-usagewindows.js';
+import { authSwitchSpendExhausted, authSwitchSpendMonthEnded } from './authority-spend.js';
 
 /**
  * `available`: the account takes work. `reserved`: a counted window reached the account's `maxUsagePercent`, so
- * the rest of it is kept for use outside AGL. `exhausted`: a counted window is used up, or the provider refuses
- * requests until a time it names.
+ * the rest of it is kept for use outside AGL. `exhausted`: a counted window is used up, the provider refuses
+ * requests until a time it names, or an API key reached its monthly spend limit.
  */
 export type TAuthSwitchLimitState = 'available' | 'reserved' | 'exhausted';
 
@@ -51,6 +52,82 @@ export const authSwitchReserveLiftActive = (untilArg: string | null | undefined,
 export const authSwitchEffectiveMaxUsage = (maxArg: number | null, untilArg: string | null | undefined,
   nowArg: number): number | null => maxArg !== null && authSwitchReserveLiftActive(untilArg, nowArg) ? 100 : maxArg;
 
+/** The windows' latest reset among those it names, as ISO 8601; null when none names one. */
+const latestReset = (resetsArg: readonly (string | null)[]): string | null => {
+  const resetTimes = resetsArg.flatMap((resetArg) => {
+    const at = resetArg === null ? NaN : Date.parse(resetArg);
+    return Number.isFinite(at) ? [at] : [];
+  });
+  return resetTimes.length ? new Date(Math.max(...resetTimes)).toISOString() : null;
+};
+
+/** A subscription sign-in's limit: see `authSwitchUsageLimit`. */
+const subscriptionLimit = (readingArg: TAuthSwitchProviderUsageReading, maxUsagePercentArg: number | null,
+  nowArg: number, reserveLiftUntilArg: string | null): IAuthSwitchUsageLimit => {
+  const threshold = authSwitchEffectiveMaxUsage(maxUsagePercentArg, reserveLiftUntilArg, nowArg) ?? 100;
+  const windows = authSwitchCountedWindows(readingArg, maxUsagePercentArg);
+  const crossing = windows.filter((windowArg) => authSwitchUsageWindowPercent(windowArg) >= threshold);
+  const resets = crossing.map((windowArg) => windowArg.resetAt);
+  let refused: boolean;
+  switch (readingArg.kind) {
+    case 'openai': {
+      const details = readingArg.rateLimits.rateLimit;
+      const mainWindows = [details?.primaryWindow, details?.secondaryWindow]
+        .filter((windowArg) => windowArg !== undefined);
+      // The refusal is the used-up windows' where the reading states any, else the whole limit's; once each of those
+      // started a new period past the reset the reading stated, so did the refusal.
+      const used = mainWindows.filter((windowArg) => windowArg.usedPercent >= 100);
+      const causes = used.length ? used : mainWindows;
+      const rolled = causes.length > 0 && causes.every((windowArg) => windowArg.estimated === true);
+      refused = details !== undefined && !rolled && (!details.allowed || details.limitReached);
+      // A refusal that names no window is lifted by the latest reset of the windows the limit counts.
+      if (refused && crossing.length === 0) resets.push(...windows.map((windowArg) => windowArg.resetAt));
+      break;
+    }
+    case 'anthropic': {
+      const retryAt = readingArg.status.rateLimit?.retryAt ?? null;
+      refused = retryAt !== null && Date.parse(retryAt) > nowArg;
+      if (refused) resets.push(retryAt);
+      break;
+    }
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
+  }
+  const state: TAuthSwitchLimitState = refused || crossing.some((windowArg) => authSwitchUsageWindowPercent(windowArg) >= 100)
+    ? 'exhausted' : crossing.length ? 'reserved' : 'available';
+  return {
+    state,
+    threshold,
+    headroom: windows.length
+      ? Math.min(...windows.map((windowArg) => Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg)))) : null,
+    crossing,
+    resetAt: state !== 'available' ? latestReset(resets) : null,
+  };
+};
+
+/**
+ * An API key's limit, from its monthly spend (`authSwitchSpendExhausted`): with a spend limit the key is `exhausted`
+ * once its month spent the limit or holds an answer that could not be priced, until the month ends; without one it is
+ * always `available`. The threshold is always 100, and neither a usage threshold nor a reserve lift applies to a key.
+ */
+const spendLimit = (readingArg: Extract<TAuthSwitchUsageReading, { kind: 'spend' }>, nowArg: number): IAuthSwitchUsageLimit => {
+  const windows = authSwitchUsageWindows(readingArg);
+  const exhausted = authSwitchSpendExhausted(readingArg.spend, nowArg);
+  // A month that ended says nothing about the next one, which starts with nothing spent.
+  const ended = authSwitchSpendMonthEnded(readingArg.spend, nowArg);
+  return {
+    state: exhausted ? 'exhausted' : 'available',
+    threshold: 100,
+    headroom: windows.length
+      ? Math.min(...windows.map((windowArg) => ended ? 100 : Math.max(0, 100 - authSwitchUsageWindowPercent(windowArg))))
+      : null,
+    crossing: exhausted ? windows : [],
+    resetAt: exhausted ? readingArg.spend.resetAt : null,
+  };
+};
+
 /**
  * The limit an account's usage reading states, judged against its `maxUsagePercent` at `nowArg` (epoch
  * milliseconds). An active reserve lift raises only the threshold to 100 until its absolute expiry.
@@ -69,47 +146,25 @@ export const authSwitchEffectiveMaxUsage = (maxArg: number | null, untilArg: str
  * of a Claude reading is the provider refusing inference, as an answer's headers stated it; a refused usage read never
  * sets it.
  *
+ * An API key's spend reading is judged by its spend limit alone (`spendLimit`); `maxUsagePercentArg` and
+ * `reserveLiftUntilArg` do not apply to it.
+ *
  * Whether a reading is recent enough to decide on, and a cooldown after a provider 429, are the caller's: they belong
  * to how it reads usage, not to what a reading says.
  */
 export const authSwitchUsageLimit = (readingArg: TAuthSwitchUsageReading, maxUsagePercentArg: number | null,
   nowArg: number, reserveLiftUntilArg: string | null = null): IAuthSwitchUsageLimit => {
-  const threshold = authSwitchEffectiveMaxUsage(maxUsagePercentArg, reserveLiftUntilArg, nowArg) ?? 100;
-  const windows = authSwitchCountedWindows(readingArg, maxUsagePercentArg);
-  const crossing = windows.filter((windowArg) => authSwitchUsageWindowPercent(windowArg) >= threshold);
-  const resets = crossing.map((windowArg) => windowArg.resetAt);
-  let refused: boolean;
-  if (readingArg.kind === 'openai') {
-    const details = readingArg.rateLimits.rateLimit;
-    const mainWindows = [details?.primaryWindow, details?.secondaryWindow]
-      .filter((windowArg) => windowArg !== undefined);
-    // The refusal is the used-up windows' where the reading states any, else the whole limit's; once each of those
-    // started a new period past the reset the reading stated, so did the refusal.
-    const used = mainWindows.filter((windowArg) => windowArg.usedPercent >= 100);
-    const causes = used.length ? used : mainWindows;
-    const rolled = causes.length > 0 && causes.every((windowArg) => windowArg.estimated === true);
-    refused = details !== undefined && !rolled && (!details.allowed || details.limitReached);
-    // A refusal that names no window is lifted by the latest reset of the windows the limit counts.
-    if (refused && crossing.length === 0) resets.push(...windows.map((windowArg) => windowArg.resetAt));
-  } else {
-    const retryAt = readingArg.status.rateLimit?.retryAt ?? null;
-    refused = retryAt !== null && Date.parse(retryAt) > nowArg;
-    if (refused) resets.push(retryAt);
+  switch (readingArg.kind) {
+    case 'openai':
+    case 'anthropic':
+      return subscriptionLimit(readingArg, maxUsagePercentArg, nowArg, reserveLiftUntilArg);
+    case 'spend':
+      return spendLimit(readingArg, nowArg);
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
   }
-  const state: TAuthSwitchLimitState = refused || crossing.some((windowArg) => authSwitchUsageWindowPercent(windowArg) >= 100)
-    ? 'exhausted' : crossing.length ? 'reserved' : 'available';
-  const resetTimes = resets.flatMap((resetArg) => {
-    const at = resetArg === null ? NaN : Date.parse(resetArg);
-    return Number.isFinite(at) ? [at] : [];
-  });
-  return {
-    state,
-    threshold,
-    headroom: windows.length
-      ? Math.min(...windows.map((windowArg) => Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg)))) : null,
-    crossing,
-    resetAt: state !== 'available' && resetTimes.length ? new Date(Math.max(...resetTimes)).toISOString() : null,
-  };
 };
 
 const windowNames = (windowsArg: readonly IAuthSwitchUsageWindow[]): string => {

package/ts_authswitch/authority-usagewindows.ts

@@ -54,29 +54,52 @@ const openAiWindows = (limitNameArg: string | null,
     }))
 );
 
+/** The name of an API key's one window, its spend in the calendar month against its limit. */
+export const authSwitchSpendWindowLabel = 'Monthly spend';
+
 /**
  * The windows of a reading: for ChatGPT the main limit's two windows, then each named extra limit's; for Claude the
- * windows as the service reported them. A missing reading has none.
+ * windows as the service reported them; for an API key with a spend limit one account window, the month's spend in
+ * percent of the limit, which resets when the month ends -- a key without a limit has none. A missing reading has none.
  */
 export const authSwitchUsageWindows = (readingArg: TAuthSwitchUsageReading | null): IAuthSwitchUsageWindow[] => {
   if (readingArg === null) return [];
-  if (readingArg.kind === 'openai') {
-    return [
-      ...openAiWindows(null, readingArg.rateLimits.rateLimit),
-      ...readingArg.rateLimits.additionalRateLimits.flatMap((limitArg) => (
-        openAiWindows(limitArg.limitName, limitArg.rateLimit)
-      )),
-    ];
+  switch (readingArg.kind) {
+    case 'openai':
+      return [
+        ...openAiWindows(null, readingArg.rateLimits.rateLimit),
+        ...readingArg.rateLimits.additionalRateLimits.flatMap((limitArg) => (
+          openAiWindows(limitArg.limitName, limitArg.rateLimit)
+        )),
+      ];
+    case 'anthropic':
+      return (readingArg.status.windows ?? []).map((windowArg) => ({
+        label: windowArg.label,
+        limitName: null,
+        scope: windowArg.scope,
+        durationSeconds: windowArg.durationSeconds,
+        usedPercent: windowArg.usedPercent,
+        estimatedUsedPercent: windowArg.estimated ? windowArg.estimatedUsedPercent ?? null : null,
+        resetAt: windowArg.resetAt,
+      }));
+    case 'spend': {
+      const spend = readingArg.spend;
+      if (spend.limitMicroUsd === null) return [];
+      return [{
+        label: authSwitchSpendWindowLabel,
+        limitName: null,
+        scope: 'account',
+        durationSeconds: (Date.parse(spend.resetAt) - Date.parse(spend.periodStart)) / 1000,
+        usedPercent: spend.spentMicroUsd * 100 / spend.limitMicroUsd,
+        estimatedUsedPercent: null,
+        resetAt: spend.resetAt,
+      }];
+    }
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
   }
-  return (readingArg.status.windows ?? []).map((windowArg) => ({
-    label: windowArg.label,
-    limitName: null,
-    scope: windowArg.scope,
-    durationSeconds: windowArg.durationSeconds,
-    usedPercent: windowArg.usedPercent,
-    estimatedUsedPercent: windowArg.estimated ? windowArg.estimatedUsedPercent ?? null : null,
-    resetAt: windowArg.resetAt,
-  }));
 };
 
 /** The percent a window is used to as far as AGL knows: the estimate between reads, else the reported value. */
@@ -101,5 +124,7 @@ export const authSwitchUsageProblemText = (problemArg: TAuthSwitchUsageProblem):
     case 'expired': return 'The last reading is too old to show.';
     case 'held_in_container': return 'This login is in use in a container, so its usage is not read here.';
     case 'pending': return 'The account\'s usage has not been read yet.';
+    case 'spend_unavailable': return 'The key\'s spend could not be read, so AGL places nothing on it while it has a '
+      + 'spend limit.';
   }
 };