agl 40.4.0 → 40.5.1

package/ts/classes.inferenceusagecache.ts

@@ -13,6 +13,13 @@ const supersedes = (nextArg: TUsageSnapshot, heldArg: TUsageSnapshot | undefined
 export interface IInferenceUsageCacheOptions {
   /** Reads one account's usage from the account service. */
   read: (accountIdArg: string, signalArg: AbortSignal) => Promise<TUsageSnapshot>;
+  /**
+   * What a held reading reads as when it is handed out (`get`, `current`, `peek`), worked out in the same synchronous
+   * step that reads it: an API key's spend with the answers its accounts service has not acknowledged yet
+   * (`InferenceSpendOutbox.judged`). Their acknowledgement replaces the held reading and drops them in one step
+   * (`accept`), so a reading handed out never misses an answer. The held reading as it is when unset.
+   */
+  view?: (accountIdArg: string, snapshotArg: TUsageSnapshot) => TUsageSnapshot;
   /** How old a held reading may grow before a request reads it again (0: every request starts one shared read). */
   refreshAfterMs?: number;
   /** How long a request waits for that read before it routes on the held reading. */
@@ -68,17 +75,18 @@ export class InferenceUsageCache {
     if (entry.snapshot) {
       if (now - entry.readAt >= this.refreshAfterMs) this.refresh(accountIdArg, entry);
       if (entry.inflight && this.freshWaitMs > 0) await this.wait(entry.inflight, this.freshWaitMs, signalArg);
-      return entry.snapshot;
+      return this.viewed(accountIdArg, entry.snapshot);
     }
     this.refresh(accountIdArg, entry);
     if (entry.inflight) await this.wait(entry.inflight, this.firstReadTimeoutMs, signalArg);
-    if (entry.snapshot) return entry.snapshot;
+    if (entry.snapshot) return this.viewed(accountIdArg, entry.snapshot);
     throw entry.error instanceof Error ? entry.error : new Error('The account usage could not be read.');
   }
 
   /** The reading held for an account, without reading it again; `undefined` while none is held. */
   public peek(accountIdArg: string): TUsageSnapshot | undefined {
-    return this.entries.get(accountIdArg)?.snapshot;
+    const snapshot = this.entries.get(accountIdArg)?.snapshot;
+    return snapshot && this.viewed(accountIdArg, snapshot);
   }
 
   /**
@@ -95,7 +103,7 @@ export class InferenceUsageCache {
     }
     if (!entry.snapshot || this.now() - entry.readAt >= this.refreshAfterMs) this.refresh(accountIdArg, entry);
     if (entry.inflight && this.freshWaitMs > 0) await this.wait(entry.inflight, this.freshWaitMs, signalArg);
-    return entry.snapshot;
+    return entry.snapshot && this.viewed(accountIdArg, entry.snapshot);
   }
 
   /**
@@ -114,6 +122,10 @@ export class InferenceUsageCache {
     entry.readAt = this.now();
   }
 
+  private viewed(accountIdArg: string, snapshotArg: TUsageSnapshot): TUsageSnapshot {
+    return this.options.view ? this.options.view(accountIdArg, snapshotArg) : snapshotArg;
+  }
+
   /** Waits for a read, at most `msArg`; the read itself goes on and lands in the cache. */
   private async wait(inflightArg: Promise<void>, msArg: number, signalArg: AbortSignal): Promise<void> {
     await new Promise<void>((resolve) => {

package/ts/classes.inferenceusagetap.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import type { IInferenceTokenCounts } from './classes.inferenceusage.js';
+import type { IInferenceAnsweredUsage, IInferenceResponsesAnswered } from './classes.inferencespend.js';
 
 type TTokenUsage = plugins.authswitchUsageTokens.IAuthSwitchTokenUsage;
 
@@ -31,7 +32,8 @@ interface IStatedUsage {
 /** What the relay hands each chunk of an answer it passed on, and the end of the answer. */
 export interface IInferenceUsageTap {
   chunk(bytesArg: Uint8Array): void;
-  end(): void;
+  /** The answer ended; `wholeArg`: the provider's body was read to its end, not cut or cancelled. */
+  end(wholeArg: boolean): void;
 }
 
 /**
@@ -42,6 +44,11 @@ export interface IInferenceUsageTap {
  * cumulative), so only those events' data lines are parsed and every other line is skipped unread; a cut stream reports
  * what arrived. A JSON answer states `usage` and `model` at its top level and is read at its end. Anything unreadable
  * reports nothing: the estimate is the authority's, and the answer is never at stake.
+ *
+ * `answered`, given for an answer an API key served, takes at the end what the answer stated for its price: the model
+ * that answered and its usage object as sent, a stream's merged field by field from `message_start` and the
+ * `message_delta`s after it (one that omits `service_tier` keeps the one `message_start` stated), and whether the answer
+ * arrived whole (`message_stop`, or a JSON body read to its end). It is called also when the answer could not be read.
  */
 export class InferenceClaudeUsageTap implements IInferenceUsageTap {
   private readonly decoder = new TextDecoder();
@@ -50,11 +57,17 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
   private event = '';
   private model?: string;
   private readonly stated: IStatedUsage = {};
+  /** The usage objects the answer stated, merged as sent, for its price. */
+  private raw?: Record<string, unknown>;
+  /** The stream reached `message_stop`, or the JSON body was read to its end. */
+  private complete = false;
   private readonly json: Uint8Array[] = [];
   private jsonBytes = 0;
   private stopped = false;
+  private ended = false;
 
-  constructor(private readonly format: 'sse' | 'json', private readonly report: (usageArg: TTokenUsage) => void) {}
+  constructor(private readonly format: 'sse' | 'json', private readonly report: (usageArg: TTokenUsage) => void,
+    private readonly answered?: (answeredArg: IInferenceAnsweredUsage) => void) {}
 
   /** Reads a chunk the relay passed on; never throws. */
   public chunk(bytesArg: Uint8Array): void {
@@ -62,7 +75,8 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
     try {
       if (this.format === 'json') {
         this.jsonBytes += bytesArg.byteLength;
-        if (this.jsonBytes > maximumJsonBytes) { this.stopped = true; this.json.length = 0; return; }
+        // A body too large to read is an answer that arrived all the same, whose usage could not be read.
+        if (this.jsonBytes > maximumJsonBytes) { this.stopped = true; this.complete = true; this.json.length = 0; return; }
         this.json.push(bytesArg.slice());
         return;
       }
@@ -72,9 +86,12 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
 
   /** Reports the usage that arrived, once: at the end of the answer, also when it was cut or cancelled. */
   public end(): void {
-    if (this.stopped) return;
+    if (this.ended) return;
+    this.ended = true;
     try {
+      if (this.stopped) return;
       if (this.format === 'json') {
+        this.complete = true;
         const body = record(JSON.parse(new TextDecoder().decode(Buffer.concat(this.json))));
         this.json.length = 0;
         if (typeof body?.model === 'string') this.model = body.model;
@@ -86,7 +103,12 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
       this.stopped = true;
       const usage = this.usage();
       if (usage) this.report(usage);
-    } catch { this.stopped = true; }
+    } catch { this.stopped = true; } finally {
+      try {
+        this.answered?.({ ...(this.model === undefined ? {} : { model: this.model }), ...(this.raw ? { usage: this.raw } : {}),
+          complete: this.complete });
+      } catch { /* the answer is never at stake */ }
+    }
   }
 
   private text(textArg: string): void {
@@ -115,7 +137,11 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
 
   private handle(lineArg: string): void {
     if (lineArg === '') { this.event = ''; return; }
-    if (lineArg.startsWith('event:')) { this.event = lineArg.slice(6).trim(); return; }
+    if (lineArg.startsWith('event:')) {
+      this.event = lineArg.slice(6).trim();
+      if (this.event === 'message_stop') this.complete = true;
+      return;
+    }
     if (!lineArg.startsWith('data:') || !usageEvents.has(this.event)) return;
     const data = record(JSON.parse(lineArg.slice(5)));
     if (this.event === 'message_start') {
@@ -129,6 +155,14 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
 
   private state(usageArg: Record<string, unknown> | undefined): void {
     if (!usageArg) return;
+    // As sent, later fields over earlier ones; an object field (`cache_creation`, `server_tool_use`) merges its own fields.
+    const raw = this.raw ?? {};
+    for (const [name, value] of Object.entries(usageArg)) {
+      const held = record(raw[name]);
+      const next = record(value);
+      raw[name] = held && next ? { ...held, ...next } : value;
+    }
+    this.raw = raw;
     for (const name of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'] as const) {
       const value = count(usageArg[name]);
       if (value !== undefined) this.stated[name] = value;
@@ -158,15 +192,28 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
 /** The Responses stream events that end an answer and carry the whole response with its `usage`. */
 const responsesTerminalEvents: ReadonlySet<string> = new Set(['response.completed', 'response.incomplete', 'response.failed']);
 
+/** The Responses stream event that carries each finished output item, a web or file search call among them. */
+const responsesItemDoneEvent = 'response.output_item.done';
+
+/** The output item types of a search OpenAI runs and bills per call, and the call fee each counts under. */
+const searchCallTypes: ReadonlyMap<string, 'web' | 'file'> = new Map([['web_search_call', 'web'], ['file_search_call', 'file']]);
+
 /**
  * Reads the tokens one OpenAI Responses answer used as its bytes pass to the client, as `InferenceClaudeUsageTap` does for
  * Messages: never holding, changing or delaying the answer, and reporting once at its end.
  *
  * A stream (`sse`) states usage only in its terminal event (`response.completed`, `response.incomplete`,
- * `response.failed`) as `response.usage`. A frame named by an `event:` line is read only when that name is terminal;
- * a data-only frame is kept up to the frame limit and parsed only when it names a terminal type. A JSON answer states
- * `usage` at its top level. `input_tokens` counts every input token, so the cached reads (`cached_tokens`) and cache
- * writes (`cache_write_tokens`) of `input_tokens_details` are taken out of it.
+ * `response.failed`) as `response.usage`. A frame named by an `event:` line is read only when that name is terminal or
+ * `response.output_item.done`; a data-only frame is kept up to the frame limit and parsed only when it names a terminal
+ * type, or a finished output item that is a search call. A JSON answer states `usage` at its top level. `input_tokens`
+ * counts every input token, so the cached reads (`cached_tokens`) and cache writes (`cache_write_tokens`) of
+ * `input_tokens_details` are taken out of it.
+ *
+ * `answered`, given for an answer an OpenAI API key served, takes at the end what the answer stated for its price
+ * (`IInferenceResponsesAnswered`): whether its terminal event or its JSON body was read, arrived too large to read, or
+ * never arrived (`end`'s `wholeArg` says whether a JSON body was read to its end); the model, service tier, status and
+ * usage the response stated; and the ids of its web and file search calls, from the finished output items and the
+ * terminal response's `output`, each once.
  */
 export class InferenceResponsesUsageTap implements IInferenceUsageTap {
   private readonly decoder = new TextDecoder();
@@ -174,11 +221,23 @@ export class InferenceResponsesUsageTap implements IInferenceUsageTap {
   private skipping = false;
   private event = '';
   private usage?: Record<string, unknown>;
+  /** The response a terminal event or the JSON body stated, for the answer's price. */
+  private response?: Record<string, unknown>;
+  /** A terminal event was read (`read`), or one arrived too large or malformed to read (`unreadable`). */
+  private terminal: 'none' | 'read' | 'unreadable' = 'none';
+  private readonly webSearchCalls = new Set<string>();
+  private readonly fileSearchCalls = new Set<string>();
+  private unidentifiedCalls = false;
   private readonly json: Uint8Array[] = [];
   private jsonBytes = 0;
+  private jsonOverflow = false;
   private stopped = false;
+  /** Reading failed on something that passed: what the answer stated is not known whole. */
+  private failed = false;
+  private ended = false;
 
-  constructor(private readonly format: 'sse' | 'json', private readonly report: (countsArg: IInferenceTokenCounts) => void) {}
+  constructor(private readonly format: 'sse' | 'json', private readonly report: (countsArg: IInferenceTokenCounts) => void,
+    private readonly answered?: (answeredArg: IInferenceResponsesAnswered) => void) {}
 
   /** Reads a chunk the relay passed on; never throws. */
   public chunk(bytesArg: Uint8Array): void {
@@ -186,30 +245,53 @@ export class InferenceResponsesUsageTap implements IInferenceUsageTap {
     try {
       if (this.format === 'json') {
         this.jsonBytes += bytesArg.byteLength;
-        if (this.jsonBytes > maximumJsonBytes) { this.stopped = true; this.json.length = 0; return; }
+        if (this.jsonBytes > maximumJsonBytes) { this.stopped = true; this.jsonOverflow = true; this.json.length = 0; return; }
         this.json.push(bytesArg.slice());
         return;
       }
       this.text(this.decoder.decode(bytesArg, { stream: true }));
-    } catch { this.stopped = true; }
+    } catch { this.stopped = true; this.failed = true; }
   }
 
-  /** Reports the usage the answer stated, once; a stream cut before its terminal event reports nothing. */
-  public end(): void {
-    if (this.stopped) return;
+  /**
+   * Reports the usage the answer stated, once; a stream cut before its terminal event reports nothing. `wholeArg`: the
+   * provider's body was read to its end, which only a JSON answer needs to be told.
+   */
+  public end(wholeArg = true): void {
+    if (this.ended) return;
+    this.ended = true;
     try {
-      if (this.format === 'json') {
-        const body = record(JSON.parse(new TextDecoder().decode(Buffer.concat(this.json))));
-        this.json.length = 0;
-        this.usage = record(body?.usage);
-      } else {
-        this.text(this.decoder.decode());
-        if (this.line && !this.skipping) this.handle(this.line);
+      if (!this.stopped) {
+        if (this.format === 'json') {
+          if (wholeArg) {
+            try {
+              const body = record(JSON.parse(new TextDecoder().decode(Buffer.concat(this.json))));
+              if (body) this.state(body); else this.terminal = 'unreadable';
+            } catch { this.terminal = 'unreadable'; }
+          }
+          this.json.length = 0;
+        } else {
+          this.text(this.decoder.decode());
+          if (this.line && !this.skipping) this.handle(this.line);
+        }
+        this.stopped = true;
+        const counts = this.counts();
+        if (counts) this.report(counts);
       }
-      this.stopped = true;
-      const counts = this.counts();
-      if (counts) this.report(counts);
-    } catch { this.stopped = true; }
+    } catch { this.stopped = true; this.failed = true; } finally {
+      try {
+        const outcome = this.format === 'json' && this.jsonOverflow ? (wholeArg ? 'unreadable' : 'cut')
+          : this.terminal === 'read' && !this.failed ? 'answered'
+            : this.terminal === 'unreadable' || this.failed ? 'unreadable' : 'cut';
+        const response = this.response;
+        this.answered?.({ outcome,
+          ...(typeof response?.status === 'string' ? { status: response.status } : {}),
+          ...(typeof response?.model === 'string' ? { model: response.model } : {}),
+          ...(response && 'service_tier' in response ? { serviceTier: response.service_tier } : {}),
+          ...(this.usage ? { usage: this.usage } : {}),
+          webSearchCalls: this.webSearchCalls, fileSearchCalls: this.fileSearchCalls, unidentifiedCalls: this.unidentifiedCalls });
+      } catch { /* the answer is never at stake */ }
+    }
   }
 
   private text(textArg: string): void {
@@ -219,9 +301,14 @@ export class InferenceResponsesUsageTap implements IInferenceUsageTap {
       if (newline === -1) {
         if (!this.skipping) {
           this.line += textArg.slice(start);
-          // A data line of a named event without usage, or one longer than any frame read, is not kept.
-          if ((this.line.startsWith('data:') && this.event !== '' && !responsesTerminalEvents.has(this.event))
-            || this.line.length > maximumResponsesFrameLength) {
+          // A data line of a named event without usage or a finished item, or one longer than any frame read, is not
+          // kept; a terminal one that long arrived and could not be read.
+          if (this.line.startsWith('data:') && this.event !== '' && !responsesTerminalEvents.has(this.event)
+            && this.event !== responsesItemDoneEvent) {
+            this.skipping = true;
+            this.line = '';
+          } else if (this.line.length > maximumResponsesFrameLength) {
+            this.overflow(this.line);
             this.skipping = true;
             this.line = '';
           }
@@ -233,20 +320,58 @@ export class InferenceResponsesUsageTap implements IInferenceUsageTap {
       if (this.skipping) { this.skipping = false; this.line = ''; continue; }
       const line = this.line + piece;
       this.line = '';
+      if (line.length > maximumResponsesFrameLength) { this.overflow(line); continue; }
       this.handle(line.endsWith('\r') ? line.slice(0, -1) : line);
     }
   }
 
+  /** A line longer than any frame read is not read; a terminal event that long arrived and could not be read. */
+  private overflow(lineArg: string): void {
+    if (lineArg.startsWith('data:') && this.terminal === 'none' && (this.event !== '' ? responsesTerminalEvents.has(this.event)
+      : [...responsesTerminalEvents].some((typeArg) => lineArg.includes(`"${typeArg}"`)))) this.terminal = 'unreadable';
+  }
+
   private handle(lineArg: string): void {
     if (lineArg === '') { this.event = ''; return; }
     if (lineArg.startsWith('event:')) { this.event = lineArg.slice(6).trim(); return; }
     if (!lineArg.startsWith('data:')) return;
-    if (this.event !== '' ? !responsesTerminalEvents.has(this.event)
-      : ![...responsesTerminalEvents].some((typeArg) => lineArg.includes(typeArg))) return;
-    const data = record(JSON.parse(lineArg.slice(5)));
+    const terminal = this.event !== '' ? responsesTerminalEvents.has(this.event)
+      : [...responsesTerminalEvents].some((typeArg) => lineArg.includes(typeArg));
+    const searchCall = (this.event === '' || this.event === responsesItemDoneEvent) && lineArg.includes(responsesItemDoneEvent)
+      && [...searchCallTypes.keys()].some((typeArg) => lineArg.includes(typeArg));
+    if (!terminal && !searchCall) return;
+    let data: Record<string, unknown> | undefined;
+    try {
+      data = record(JSON.parse(lineArg.slice(5)));
+    } catch {
+      // A terminal event or a search call that cannot be read: what the answer cost is not known.
+      if (this.event !== '' ? terminal : true) this.terminal = this.terminal === 'read' ? 'read' : 'unreadable';
+      if (searchCall) this.unidentifiedCalls = true;
+      return;
+    }
+    if (data?.type === responsesItemDoneEvent) { this.item(data.item); return; }
     if (typeof data?.type !== 'string' || !responsesTerminalEvents.has(data.type)) return;
-    const usage = record(record(data.response)?.usage);
+    const response = record(data.response);
+    if (!response) { if (this.terminal === 'none') this.terminal = 'unreadable'; return; }
+    this.state(response);
+  }
+
+  /** Takes what a terminal response (or a JSON answer) states: its usage, model, tier and status, and its search calls. */
+  private state(responseArg: Record<string, unknown>): void {
+    this.terminal = 'read';
+    this.response = responseArg;
+    const usage = record(responseArg.usage);
     if (usage) this.usage = usage;
+    if (Array.isArray(responseArg.output)) for (const item of responseArg.output) this.item(item);
+  }
+
+  /** Counts a finished output item that is a web or file search call, once per id. */
+  private item(itemArg: unknown): void {
+    const item = record(itemArg);
+    const kind = typeof item?.type === 'string' ? searchCallTypes.get(item.type) : undefined;
+    if (!kind) return;
+    if (typeof item!.id !== 'string' || !item!.id) { this.unidentifiedCalls = true; return; }
+    (kind === 'web' ? this.webSearchCalls : this.fileSearchCalls).add(item!.id);
   }
 
   private counts(): IInferenceTokenCounts | undefined {

package/ts/classes.proxycontrol.ts

@@ -75,8 +75,9 @@ export interface IReq_AglProxyCredential extends ITypedRequest {
 
 /**
  * The models a pool offers now, without a credential: what a configuration names for the pool. `credential` names the
- * pool's kind as a lease policy does: subscription accounts when omitted, Anthropic API keys with `api_key`.
- * `accountId` reads the ChatGPT pool of that one account, as a lease restricted to it (`accountIds`) is served.
+ * pool's kind as a lease policy does: when omitted, its best credential tier with a readable account (subscription
+ * accounts, else API keys); `api_key`, the provider's API keys alone. `accountId` reads the ChatGPT pool of that one
+ * account, as a lease restricted to it (`accountIds`) is served.
  */
 export interface IReq_AglProxyCatalog extends ITypedRequest {
   method: 'agl.proxy.catalog';
@@ -224,7 +225,6 @@ export class AglProxyControlServer {
         || Object.keys(requestArg).some((keyArg) => !['provider', 'credential', 'accountId'].includes(keyArg))
         || !inferenceProviders.includes(requestArg.provider)
         || (requestArg.credential !== undefined && !inferenceCredentials.includes(requestArg.credential))
-        || (requestArg.credential === 'api_key' && requestArg.provider !== 'anthropic')
         || (requestArg.accountId !== undefined
           && (requestArg.provider !== 'openai' || requestArg.credential !== undefined || !isAuthorityAccountId(requestArg.accountId)))) {
         throw new AglProxyControlRefusal('Invalid proxy catalog request.');

package/ts/classes.proxydaemon.ts

@@ -105,7 +105,7 @@ export class AglProxyDaemon {
     this.usage.start();
     this.service = new InferenceService({ authorityPaths: this.options.authorityPaths, installationId: identity.installationId,
       port: this.options.port, signatureKey: identity.signatureKey, affinity: this.store.affinity(),
-      placements: this.store.placements(), usageLedger: this.usage,
+      placements: this.store.placements(), usageLedger: this.usage, spendStore: this.store.spend(),
       ...(this.options.providerFetch ? { providerFetch: this.options.providerFetch } : {}),
       ...(this.options.limits ? { limits: this.options.limits } : {}) });
     const baseUrl = await this.service.start(signal);
@@ -247,6 +247,7 @@ export class AglProxyDaemon {
         ? { provider: 'anthropic', models: await service.router.claudeModels({ provider: 'anthropic',
           ...(requestArg.credential ? { credential: requestArg.credential } : {}) }, signal) }
         : { provider: 'openai', models: await service.router.models({ provider: 'openai',
+          ...(requestArg.credential ? { credential: requestArg.credential } : {}),
           ...(requestArg.accountId === undefined ? {} : { accountIds: [requestArg.accountId] }) }, signal) } };
     } catch (errorArg) {
       throw catalogRefusal(errorArg);

package/ts/classes.proxystore.ts

@@ -4,6 +4,7 @@ import { InferenceAffinityModel, InferenceAffinityStore } from './classes.infere
 import { InferenceSessionModel } from './classes.inferencesession.js';
 import { InferencePlacementModel, InferencePlacementStore } from './classes.inferenceplacement.js';
 import { InferenceUsageModel, InferenceUsageStore } from './classes.inferenceusage.js';
+import { InferenceSpendModel, InferenceSpendStore } from './classes.inferencespend.js';
 import { assertInferenceRoutingPolicy } from './classes.inferencegateway.js';
 import type { IInferenceRoutingPolicy } from './classes.inferencerouter.js';
 import {
@@ -191,7 +192,7 @@ export class ProxyLeaseModel extends plugins.nosqldb.SmartDataDbDoc<ProxyLeaseMo
 }
 
 const proxyModels = [ProxyIdentityModel, ProxyClientModel, ProxyDeliveryModel, ProxyLeaseModel, InferenceAffinityModel,
-  InferenceSessionModel, InferencePlacementModel, InferenceUsageModel];
+  InferenceSessionModel, InferencePlacementModel, InferenceUsageModel, InferenceSpendModel];
 const inactiveManager = {
   get db(): plugins.nosqldb.SmartdataDb { throw new Error('The proxy store is not open.'); },
 };
@@ -288,6 +289,15 @@ export class ProxyStore {
     return new InferenceUsageStore();
   }
 
+  /**
+   * Where the proxy keeps the spend of the answers it relayed on API keys until the accounts service acknowledged it
+   * (`InferenceSpendOutbox`).
+   */
+  public spend(): InferenceSpendStore {
+    this.identity();
+    return new InferenceSpendStore();
+  }
+
   /** Every client's credential, creating the named clients that have none. */
   public async credentials(ensureArg: readonly string[] = defaultProxyClients): Promise<IProxyClientCredential[]> {
     for (const name of ensureArg) await this.ensureClient(name);

package/ts/fleet/classes.claudeworkers.ts

@@ -8,7 +8,7 @@ import { FleetDispatchError, boundedFleetReport, fleetMessageDigest, fleetReport
 import { runFleetWorkerCommand, type IFleetWorkerCommand, type TFleetWorkerRunner } from './classes.workercommand.js';
 import { sanitizeFailureText } from '../functions.failuredescription.js';
 import type { FleetWorkerLaunches } from './classes.workerlaunches.js';
-import { claudeCodeVerifiedRelease, claudeCodeVersionOutput, compareClaudeCodeReleases, parseClaudeCodeRelease } from '../functions.claudecoderelease.js';
+import { claudeCodeFleetFloor, claudeCodeVersionOutput, compareClaudeCodeReleases, isNewerClaudeCodeRelease, parseClaudeCodeRelease } from '../functions.claudecoderelease.js';
 
 const record = plugins.z.record(plugins.z.string(), plugins.z.unknown());
 const agentSchema = plugins.z.object({ sessionId: plugins.z.string().uuid(), id: plugins.z.string().min(1).optional(), cwd: plugins.z.string(), name: plugins.z.string().optional(),
@@ -36,19 +36,19 @@ const commandFailure = (subcommand: string, result: IFleetWorkerCommand, diagnos
   return `Claude ${subcommand} failed (exit ${result.code})${output ? `: ${output}` : '.'}`;
 };
 /**
- * The release a `claude --version` run printed, which the fleet runs on when it is the verified release or a newer one.
+ * The release a `claude --version` run printed, which the fleet runs on when it is the fleet's floor or a newer one.
  * The output must read exactly `X.Y.Z (Claude Code)`; anything else, an older release and a failed run are refused,
  * naming what was printed.
  */
 export const fleetClaudeVersion = (result: IFleetWorkerCommand): string => {
   const release = result.code === 0 ? claudeCodeVersionOutput(result.stdout) : null;
   const parsed = release === null ? null : parseClaudeCodeRelease(release);
-  if (release !== null && parsed !== null && compareClaudeCodeReleases(parsed, parseClaudeCodeRelease(claudeCodeVerifiedRelease)!) >= 0) return release;
+  if (release !== null && parsed !== null && compareClaudeCodeReleases(parsed, parseClaudeCodeRelease(claudeCodeFleetFloor)!) >= 0) return release;
   const output = commandOutput(result, true);
   const found = result.code !== 0 ? `exited with code ${result.code}${output ? `: ${output}` : '.'}`
     : release !== null ? `printed release ${release}, which is older.`
     : output ? `printed ${JSON.stringify(output)}, not "X.Y.Z (Claude Code)".` : 'printed nothing.';
-  throw new FleetDispatchError(`Claude fleet workers need Claude Code ${claudeCodeVerifiedRelease} or newer; \`claude --version\` ${found}`, false);
+  throw new FleetDispatchError(`Claude fleet workers need Claude Code ${claudeCodeFleetFloor} or newer; \`claude --version\` ${found}`, false);
 };
 /** Claude colours its output when FORCE_COLOR is set, through a pipe too; its control sequences are no text. */
 const plain = (text: string): string => text.replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, '');
@@ -70,9 +70,10 @@ const address = (inventory: TClaudeAgent[], agent: TClaudeAgent): string => {
 };
 
 /**
- * Version-coupled transcript interpretation stays here. Claude Code 2.1.282 is the release it was verified on; a newer
- * one is used optimistically and these parsers are its checks at the point of use, failing visibly where its output
- * changed. An older or unreadable version is refused (`fleetClaudeVersion`).
+ * Version-coupled transcript interpretation stays here. It was verified on Claude Code 2.1.306 and on 2.1.282, the
+ * fleet's floor, whose output the tests still pin; a newer release is used optimistically and these parsers are its
+ * checks at the point of use, failing visibly where its output changed. An older or unreadable version is refused
+ * (`fleetClaudeVersion`).
  */
 export const parseFleetClaudeTranscript = (payload: string): Record<string, unknown>[] => payload.split('\n').slice(0, -1).filter(Boolean).map((line) => record.parse(JSON.parse(line)));
 export const fleetClaudePermissionMode = (records: Record<string, unknown>[]): string => {
@@ -225,7 +226,7 @@ export class FleetClaudeWorkers implements IFleetWorkerBackend {
       const release = fleetClaudeVersion(await this.runner(executable, ['--version'], cwd, env, this.signal));
       if (await identity() !== fingerprint) throw new FleetDispatchError('Claude executable changed during version verification.', false);
       this.versions.set(key, fingerprint);
-      if (release !== claudeCodeVerifiedRelease) this.observeRelease?.(release);
+      if (isNewerClaudeCodeRelease(release)) this.observeRelease?.(release);
     }
     return executable;
   }

package/ts/functions.claudecoderelease.ts

@@ -1,14 +1,21 @@
 /**
  * Claude Code releases as AGL's controller reads them.
  *
- * AGL verified Claude Code's transcript, inventory and command output on one release, `claudeCodeVerifiedRelease`
- * (`ts_authswitch/native-contracts.md`). It uses every later release optimistically and refuses an earlier one; each
- * later release it meets is mentioned once to the driver (`HarnessReleaseNotices`), so the driver can file a
- * compatibility check for it.
+ * AGL verified Claude Code's transcript, inventory and command output on `claudeCodeVerifiedRelease`
+ * (`ts_authswitch/native-contracts.md`). Its fleet runs every release from `claudeCodeFleetFloor` on, later ones
+ * optimistically, and refuses an earlier one; each release newer than the verified one it meets is mentioned once to
+ * the driver (`HarnessReleaseNotices`), so the driver can file a compatibility check for it.
  */
 
-/** The newest Claude Code release AGL verified; the floor of the fleet and the line above which a release is new. */
-export const claudeCodeVerifiedRelease = '2.1.282';
+/** The newest Claude Code release AGL verified: the line above which a release is new and mentioned once. */
+export const claudeCodeVerifiedRelease = '2.1.306';
+
+/**
+ * The oldest Claude Code release the fleet runs: the oldest whose fleet output the tests still pin. It rises only when
+ * the fleet's adapter stops handling an older release's output, never because a newer release was verified. The
+ * accounts service's usage read takes every release from the same line on (`CLAUDE_NATIVE_READ_AS_VERIFIED_FROM`).
+ */
+export const claudeCodeFleetFloor = '2.1.282';
 
 export type TClaudeCodeRelease = readonly [number, number, number];
 

package/ts/functions.inferencecli.ts

@@ -46,8 +46,8 @@ const placementText = (accountArg: NonNullable<TReportedProxyStatus['accounts']>
  * estimate between its reads, and a note when the service's last read was refused for too many requests.
  */
 const readingText = (accountArg: NonNullable<TReportedProxyStatus['accounts']>[number]): string =>
-  accountArg.readingObservedAt === null ? 'no usage reading'
-    : `usage as of ${accountArg.readingObservedAt} `
+  accountArg.readingObservedAt === null ? `no ${accountArg.credential === 'api_key' ? 'spend' : 'usage'} reading`
+    : `${accountArg.credential === 'api_key' ? 'spend' : 'usage'} as of ${accountArg.readingObservedAt} `
       + `(${accountArg.readingSource === 'headers' ? 'from provider answers' : 'read by the account service'}`
       + `${accountArg.readingReadAt === null || accountArg.readingSource !== 'headers' ? ''
         : `, last read ${accountArg.readingReadAt}`})`
@@ -76,12 +76,16 @@ export const formatProxyStatus = (unitArg: string, statusArg: TReportedProxyStat
     return lines.join('\n') + '\n';
   }
   for (const account of statusArg.accounts) {
-    lines.push(`Account ${account.label} (${account.provider === 'openai' ? 'ChatGPT'
-      : account.credential === 'api_key' ? 'Anthropic API key' : 'Claude'}`
+    lines.push(`Account ${account.label} (${account.credential === 'api_key'
+      ? `${account.provider === 'openai' ? 'OpenAI' : 'Anthropic'} API key` : account.provider === 'openai' ? 'ChatGPT' : 'Claude'}`
       + `${account.plan === null ? '' : `, ${account.plan}`}): ${account.stateText}`
-      + `${account.resetAt === null ? '' : `, until ${account.resetAt}`}; max usage `
-      + `${account.maxUsagePercent === null ? 'not set' : `${account.maxUsagePercent}%`}`
-      + `${account.headroom === null ? '' : `, ${Math.round(account.headroom)}% headroom`}, ${account.inFlight} in flight`
+      + `${account.resetAt === null ? '' : `, until ${account.resetAt}`}; `
+      // A key has no maximum usage: its headroom is what is left of its monthly spend limit.
+      + `${account.credential === 'api_key'
+        ? `${account.headroom === null ? '' : `${Math.round(account.headroom)}% of its spend limit left, `}`
+        : `max usage ${account.maxUsagePercent === null ? 'not set' : `${account.maxUsagePercent}%`}`
+          + `${account.headroom === null ? '' : `, ${Math.round(account.headroom)}% headroom`}, `}`
+      + `${account.inFlight} in flight`
       + `${placementText(account)}; ${readingText(account)}`);
   }
   const accountLabel = (idArg: string | null): string => idArg === null ? 'none'

package/ts/interfaces.auth.ts

@@ -72,6 +72,8 @@ export const controllerAuditEventTypes = [
   'accounts.rename',
   'accounts.maxusage',
   'accounts.reserve.lift',
+  'accounts.apikey.add',
+  'accounts.spendlimit',
   'accounts.remove',
   'accounts.add',
   'accounts.reauth',

package/ts/plugins.ts

@@ -61,6 +61,11 @@ import * as authswitchUsageTokens from '../ts_authswitch/authority-usagetokens.j
 // Claude Code's native contract: which releases' credential custody was read, for the mention of a new release. The
 // package root already loads this module through the authority service, so the value import adds none.
 import * as authswitchClaudeNative from '../ts_authswitch/classes.claudenative.js';
+// An API key's monthly spend: its calendar month in UTC, the spend limit rule and dollar amounts, which the proxy, the
+// controller and the screens share.
+import * as authswitchSpend from '../ts_authswitch/authority-spend.js';
+// Whether a held payment problem still holds an account, the one rule the authority and the proxy share.
+import * as authswitchSubscription from '../ts_authswitch/authority-subscription.js';
 import * as crossharness from '@modelprofile.com/mcp-crossharness';
 import * as mcpSystem from '@modelprofile.com/mcp-system';
 import * as flexharnessMigration from '@modelprofile.com/flexharness/migration';
@@ -80,6 +85,8 @@ export {
   authswitchUsageHeaders,
   authswitchUsageTokens,
   authswitchClaudeNative,
+  authswitchSpend,
+  authswitchSubscription,
   flexharness,
   browserRuntime,
   smartbrowser,