agl 41.0.1 → 41.2.0

package/ts/functions.inferencelaunch.ts

@@ -37,10 +37,41 @@ const claudeNativeLaunch = (optionsArg: IInferenceLaunchOptions & { catalog: { p
 };
 
 /**
- * Claude Code on a ChatGPT pool: the proxy's Anthropic Messages endpoint answered by the pool's models, the default model
- * for every model alias, the context window the catalog states for it, and the pool's models as the whole `/model`
- * picker. Its configuration lives in its own directory, never the host's, so the host's `settings.json` cannot route it
- * elsewhere; it sends nothing beyond its model requests: no experimental betas, no nonessential traffic, no attribution.
+ * The variables that put Claude Code on a ChatGPT pool: the proxy's Anthropic Messages endpoint and credential, the
+ * pool's default model for every model alias, the context window the catalog states for it, and nothing beyond its model
+ * requests: no experimental betas, no nonessential traffic, no attribution. `agl proxy run claude --provider openai` and a
+ * ChatGPT-pool confined run give Claude Code these alike.
+ */
+export const claudeChatGptEnvironment = (inputArg: {
+  baseUrl: string;
+  token: string;
+  models: readonly TInferenceModel[];
+}): Record<string, string> => {
+  const model = inputArg.models.find((entryArg) => entryArg.isDefault) ?? inputArg.models[0];
+  if (!model) throw new Error('The ChatGPT pool offers no model Claude Code can run on.');
+  return {
+    ANTHROPIC_BASE_URL: inputArg.baseUrl,
+    ANTHROPIC_AUTH_TOKEN: inputArg.token,
+    ANTHROPIC_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_OPUS_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: model.modelId,
+    ...(model.contextWindow === undefined ? {} : { CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(model.contextWindow) }),
+    CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1',
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
+  };
+};
+
+/** Every variable `claudeChatGptEnvironment` may set, the context window's included. */
+const claudeChatGptVariables: readonly string[] = ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'CLAUDE_CODE_MAX_CONTEXT_TOKENS', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS', 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
+  'CLAUDE_CODE_ATTRIBUTION_HEADER'];
+
+/**
+ * Claude Code on a ChatGPT pool (`claudeChatGptEnvironment`), with the pool's models as the whole `/model` picker. Its
+ * configuration lives in its own directory, never the host's, so the host's `settings.json` cannot route it elsewhere.
  */
 export const claudeChatGptLaunch = (inputArg: {
   baseUrl: string;
@@ -48,21 +79,10 @@ export const claudeChatGptLaunch = (inputArg: {
   configDirectory: string;
   models: readonly TInferenceModel[];
 }): { environment: Record<string, string>; args: string[] } => {
-  const model = inputArg.models.find((entryArg) => entryArg.isDefault) ?? inputArg.models[0];
-  if (!model) throw new Error('The ChatGPT pool offers no model Claude Code can run on.');
   return {
     environment: {
       CLAUDE_CONFIG_DIR: inputArg.configDirectory,
-      ANTHROPIC_BASE_URL: inputArg.baseUrl,
-      ANTHROPIC_AUTH_TOKEN: inputArg.token,
-      ANTHROPIC_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_OPUS_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_SONNET_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_HAIKU_MODEL: model.modelId,
-      ...(model.contextWindow === undefined ? {} : { CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(model.contextWindow) }),
-      CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1',
-      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
-      CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
+      ...claudeChatGptEnvironment(inputArg),
     },
     args: ['--settings', JSON.stringify({
       modelPicker: {
@@ -140,16 +160,23 @@ export const inferenceHarnessLaunch = (optionsArg: IInferenceLaunchOptions): { a
   return { environment, args: args[0] !== undefined && openCodeCommands.has(args[0]) ? args : [...selection, ...args] };
 };
 
+/** A confined run's pool, as its launcher configures Claude Code for it: a ChatGPT-pool run with the pool's models. */
+export type TConfinedLaunchPool = { provider: 'anthropic' } | { provider: 'openai'; models: readonly TInferenceModel[] };
+
 /**
  * A confined run's `docker run`: the given command, with the confined listener's directory mounted read-only at
  * `aglProxyConfinedMountPoint` and Claude Code's settings for it added right after `run`, before the launcher's own
  * options and image. Claude Code inside reaches the proxy through the socket alone (`ANTHROPIC_UNIX_SOCKET`, which
  * Claude Code sends its API requests through as plain HTTP to `ANTHROPIC_BASE_URL`'s path), on the run's credential
- * (`ANTHROPIC_AUTH_TOKEN`), reads the pool's models from the proxy and sends nothing beyond its model requests. The
- * container gets each variable by name from the docker command's environment, so the credential never appears on a
- * command line; that environment drops every variable that would give Claude Code another login or route, so `-e NAME`
- * of one of them passes nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy
- * restart, unlike a mount of the socket file. Only `docker run` and `docker container run` are taken.
+ * (`ANTHROPIC_AUTH_TOKEN`), and sends nothing beyond its model requests. On the Claude pool it reads the pool's models
+ * from the proxy; on the ChatGPT pool it gets the variables `agl proxy run claude --provider openai` gives it
+ * (`claudeChatGptEnvironment`: the pool's default model for every alias, its context window), but neither that command's
+ * configuration directory, which lies in the AGL home, nor its `/model` picker, an option of the container's command
+ * that the launcher does not touch. The container gets each variable by name from the docker command's environment, so
+ * the credential never appears on a command line; that environment drops every variable that would give Claude Code
+ * another login or route, and on the ChatGPT pool every model variable it sets, so `-e NAME` of one of them passes
+ * nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy restart, unlike a
+ * mount of the socket file. Only `docker run` and `docker container run` are taken.
  */
 export const confinedDockerLaunch = (optionsArg: {
   args: readonly string[];
@@ -159,6 +186,7 @@ export const confinedDockerLaunch = (optionsArg: {
   baseUrl: string;
   token: string;
   environment: NodeJS.ProcessEnv;
+  pool: TConfinedLaunchPool;
 }): { command: string; args: string[]; environment: NodeJS.ProcessEnv } => {
   const [command, ...args] = optionsArg.args;
   const runAt = args[0] === 'run' ? 1 : args[0] === 'container' && args[1] === 'run' ? 2 : 0;
@@ -168,13 +196,19 @@ export const confinedDockerLaunch = (optionsArg: {
   const directory = path.dirname(optionsArg.socketPath);
   // `--mount` separates its fields with commas and reads quotes; a directory naming either cannot be passed safely.
   if (/[,"'\n]/u.test(directory)) throw new Error(`The confined listener's directory ${directory} cannot be mounted: it holds a comma, quote or line break.`);
-  const variables: Record<string, string> = {
+  const socket = `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`;
+  const variables: Record<string, string> = optionsArg.pool.provider === 'anthropic' ? {
     ...claudeProxyEnvironment(optionsArg.baseUrl),
-    ANTHROPIC_UNIX_SOCKET: `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`,
+    ANTHROPIC_UNIX_SOCKET: socket,
     ANTHROPIC_AUTH_TOKEN: optionsArg.token,
+  } : {
+    ...claudeChatGptEnvironment({ baseUrl: `${optionsArg.baseUrl}/anthropic`, token: optionsArg.token,
+      models: optionsArg.pool.models }),
+    ANTHROPIC_UNIX_SOCKET: socket,
   };
   const environment = { ...optionsArg.environment };
   for (const name of claudeProxyReservedVariables) delete environment[name];
+  if (optionsArg.pool.provider === 'openai') for (const name of claudeChatGptVariables) delete environment[name];
   return {
     command,
     args: [...args.slice(0, runAt),

package/ts/interfaces.auth.ts

@@ -7,9 +7,10 @@ export type TControllerAuthLifecycleState = 'setupRequired' | 'ready';
 export type TWebAuthnCeremonyKind = 'setup' | 'authentication';
 export type TWebAuthnCeremonyState = 'pending' | 'consumed';
 /**
- * Single source of the audit event vocabulary: the persisted-document
+ * Single source of the audit types this release writes: the persisted-document
  * assertion consumes this list at runtime, so a type added here is
- * automatically storable — the two can no longer drift apart.
+ * automatically storable with its type-specific checks — the two can no longer
+ * drift apart. Other well-formed types are a later release's and still read.
  */
 export const controllerAuditEventTypes = [
   'controller.started',
@@ -249,11 +250,16 @@ export type TControllerAuditSessionId =
   | IControllerRuntimeId
   | plugins.browserRuntime.IBrowserClaudeSessionId;
 
+/**
+ * A stored audit event. The audit log is shared with later releases, so a stored `type` is any audit type, also one
+ * this release does not know (a later release's, read back after a rollback). This release writes only its own types
+ * (`IRecordAuditEventInput`).
+ */
 export interface IControllerAuditEvent {
   id: string;
   controllerId: string;
   timestamp: Date;
-  type: TControllerAuditEventType;
+  type: string;
   outcome: TControllerAuditOutcome;
   operationId?: string;
   peerId?: string;
@@ -263,6 +269,11 @@ export interface IControllerAuditEvent {
   /** The sender label an agent message declared (`session.message`). */
   senderLabel?: string;
   localCli?: IConfigurationLocalCliActor;
+  /**
+   * What a later release's type records beyond the envelope (bounded plain JSON). This release never writes or
+   * interprets it; it is declared so a rolled-back controller still reads and prunes such events.
+   */
+  details?: Record<string, unknown>;
 }
 
 export interface IControllerTempPasswordDocument {

package/ts_interfaces/index.ts

@@ -9,6 +9,7 @@ export * from './functions.browserpaintcopy.js';
 export * from './devtools.js';
 export * from './requests.js';
 export * from './mcprequests.js';
+export * from './management.js';
 export * from './codex.js';
 export * from './mcpworkspacerequests.js';
 export * from './mcpjobrequests.js';

package/ts_interfaces/interfaces.ts

@@ -5,7 +5,7 @@ import type {
   TControllerBrowserPaintAvailability,
   TControllerBrowserPaintTermination,
 } from './browserpaint.js';
-export const controllerProtocolVersion = 46 as const;
+export const controllerProtocolVersion = 47 as const;
 export const controllerUpgradeManagementVersion = 2 as const;
 export const controllerPackageName = 'agl' as const;
 /** The systemd user unit `agl service install` writes; a controller it runs reports it in its status. */
@@ -325,6 +325,11 @@ export interface IControllerStatus {
   packageVersion: string;
   protocolVersion: typeof controllerProtocolVersion;
   upgradeManagementVersion: number;
+  /**
+   * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent
+   * from a controller older than the endpoint, which is reached over its socket.
+   */
+  managementProtocolVersion?: number;
   controllerPid: number;
   processGroupId: number;
   processFingerprint: string;

package/ts_interfaces/management.ts

@@ -0,0 +1,52 @@
+import type { IReq_ControllerStatus } from './requests.status.js';
+import type {
+  IReq_ControllerUpgradeFinalize,
+  IReq_ControllerUpgradeLaunch,
+  IReq_ControllerUpgradePrepareBegin,
+} from './requests.upgrade.js';
+
+/**
+ * The controller's loopback management endpoint, on the controller's own port: one TypedRequest envelope
+ * (`method`, `request`, `response`, `correlation`, `requestInstanceId`) per HTTP POST of `application/json`, with
+ * `Host: 127.0.0.1:<port>`. The local CLI and the upgrade worker read the status and drive an upgrade through it,
+ * so an upgrade worker of one release can finalize the controller of the next whatever transport the browser
+ * speaks. Every later release keeps this path, these methods, their request and response shapes and the envelope
+ * (`test/test.controllermanagementwire.node.ts` pins the bytes an AGL 41 client sends and what it accepts).
+ */
+export const controllerManagementTypedRequestPath = '/management/typedrequest' as const;
+
+/**
+ * The protocol of this loopback management endpoint: its path, methods, envelope and their request and response
+ * shapes. 1 is the endpoint as its first release ships it; only an incompatible change to that contract raises it.
+ * A release declares it twice: as `controllerManagementProtocolVersion` in its `package.json`, which a client reads
+ * before the release's controller runs, and as `managementProtocolVersion` in that controller's status. A client
+ * reaches a controller over this endpoint only when it declares 1 or more, and over the controller socket otherwise
+ * (an older release has no endpoint).
+ *
+ * It is not `controllerUpgradeManagementVersion` (2), the upgrade contract: every upgrade worker requires exactly
+ * that number in its target's `package.json` and status, and upgrade transactions record it, so it cannot move
+ * without breaking the online upgrade of every earlier release. This number says only how the management methods
+ * are reached.
+ */
+export const controllerManagementProtocolVersion = 1 as const;
+
+/** The methods the endpoint answers; every other method is refused before it is routed. */
+export const controllerManagementMethods = [
+  'controller.status',
+  'controller.upgrade.launch',
+  'controller.upgrade.prepare.begin',
+  'controller.upgrade.finalize',
+] as const;
+
+export type TControllerManagementMethod = typeof controllerManagementMethods[number];
+
+export type TControllerManagementTypedRequest =
+  | IReq_ControllerStatus
+  | IReq_ControllerUpgradeLaunch
+  | IReq_ControllerUpgradePrepareBegin
+  | IReq_ControllerUpgradeFinalize;
+
+/** A management request carries a token, a version and a mode at most. */
+export const controllerManagementRequestMaximumBodyBytes = 16 * 1024;
+/** The status document with every harness profile and upgrade blocker it may report. */
+export const controllerManagementResponseMaximumBytes = 1024 * 1024;

package/ts_interfaces/metrics.ts

@@ -10,8 +10,27 @@ export type TControllerUsageWindow = '1h' | '24h' | '7d';
 export const controllerUsageWindows: readonly TControllerUsageWindow[] = ['1h', '24h', '7d'];
 export type TControllerUsageProvider = 'anthropic' | 'openai';
 
+/**
+ * The tokens of the answers one bucket counts. Input counts only the tokens read neither from nor written to the
+ * provider's prompt cache. `cacheReadTokens` and `cacheWriteTokens` add up the cache reads and writes the answers
+ * stated; `cacheReadUnknownCalls` and `cacheWriteUnknownCalls` (each at most `calls`) count the answers that did not
+ * state theirs, which read or wrote an unknown number, not none. With either above 0 the stated sum is not the whole
+ * count, and `controllerUsageTotalIsLowerBound` of the bucket's provider says whether its total is then one. A bucket
+ * stored before these were counted reads with all its answers unknown.
+ */
+export interface IControllerUsageCounts {
+  /** The answers counted. */
+  calls: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  cacheReadUnknownCalls: number;
+  cacheWriteUnknownCalls: number;
+}
+
 /** One span of one model's tokens on one harness, account and session; never a prompt, a credential or an answer. */
-export interface IControllerUsageBucket {
+export interface IControllerUsageBucket extends IControllerUsageCounts {
   /** The bucket's digest: SHA-256 of its span, start and dimensions. */
   id: string;
   span: TControllerUsageSpan;
@@ -25,14 +44,22 @@ export interface IControllerUsageBucket {
   accountId: string;
   /** The session id the client sent; `null` when it sent none. */
   session: string | null;
-  /** The answers counted. */
-  calls: number;
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadTokens: number;
-  cacheWriteTokens: number;
 }
 
+/**
+ * Whether a provider's answers state their input without the tokens read from or written to the cache, so that a bucket
+ * of that provider with unknown cache counts (`cacheReadUnknownCalls` or `cacheWriteUnknownCalls` above 0) has total
+ * tokens (input, output, cache reads and cache writes) that are a lower bound of what its answers used. An Anthropic
+ * account's answers leave the cache out of their input, so a cache count such an answer did not state is counted
+ * nowhere. An OpenAI account's answers state every input token in their input count, the Messages answers the proxy
+ * translates from them included, so their unknown cache counts lie inside the input and their total is exact. Every
+ * provider must be named here: a new one fails the type check instead of reading as exact.
+ */
+export const controllerUsageTotalIsLowerBound: Readonly<Record<TControllerUsageProvider, boolean>> = {
+  anthropic: true,
+  openai: false,
+};
+
 const minuteMs = 60_000;
 const hourMs = 60 * minuteMs;
 

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '41.0.1',
+  version: '41.2.0',
   description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
 }

package/ts_web/classes.controllersocketclient.ts

@@ -606,7 +606,8 @@ export const isControllerSessionFeedList = (
 
 const usageBucketKeys = contractKeys<interfaces.IControllerUsageBucket>({
   id: true, span: true, start: true, provider: true, model: true, harness: true, accountId: true, session: true,
-  calls: true, inputTokens: true, outputTokens: true, cacheReadTokens: true, cacheWriteTokens: true,
+  calls: true, inputTokens: true, outputTokens: true, cacheReadTokens: true, cacheWriteTokens: true, cacheReadUnknownCalls: true,
+  cacheWriteUnknownCalls: true,
 });
 const usageHex64 = /^[a-f0-9]{64}$/;
 const usageCount = (valueArg: unknown): boolean => Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
@@ -629,7 +630,9 @@ export const isControllerUsageBucket = (valueArg: unknown): valueArg is interfac
     && (candidate.session === null || usageText(candidate.session, 512))
     && usageCount(candidate.calls) && (candidate.calls as number) >= 1
     && usageCount(candidate.inputTokens) && usageCount(candidate.outputTokens)
-    && usageCount(candidate.cacheReadTokens) && usageCount(candidate.cacheWriteTokens);
+    && usageCount(candidate.cacheReadTokens) && usageCount(candidate.cacheWriteTokens)
+    && usageCount(candidate.cacheReadUnknownCalls) && (candidate.cacheReadUnknownCalls as number) <= (candidate.calls as number)
+    && usageCount(candidate.cacheWriteUnknownCalls) && (candidate.cacheWriteUnknownCalls as number) <= (candidate.calls as number);
 };
 
 export const isControllerUsageDelta = (valueArg: unknown): valueArg is interfaces.TControllerUsageDelta => {

package/ts_web/elements.metricsboard.ts

@@ -13,23 +13,29 @@ export interface IMetricsBoardSender {
   ): Promise<TRequest['response']>;
 }
 
-type TUsageCounts = Pick<interfaces.IControllerUsageBucket,
-  'calls' | 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens'>;
+type TUsageCounts = interfaces.IControllerUsageCounts;
+
+/**
+ * A table row's counts: its buckets' counts, their total tokens and whether that total is a lower bound
+ * (some bucket of it has unknown cache counts and a provider `controllerUsageTotalIsLowerBound` marks).
+ */
+interface IMetricsRowCounts extends TUsageCounts {
+  totalTokens: number;
+  totalLowerBound: boolean;
+}
 
 /** A model's usage over the window: one row of the models table. */
-export interface IMetricsModelRow extends TUsageCounts {
+export interface IMetricsModelRow extends IMetricsRowCounts {
   key: string;
   provider: interfaces.TControllerUsageProvider;
   model: string;
-  totalTokens: number;
 }
 
 /** One session on one harness of the opened model: one row of the drill-down table. */
-export interface IMetricsSessionRow extends TUsageCounts {
+export interface IMetricsSessionRow extends IMetricsRowCounts {
   key: string;
   harness: string;
   session: string;
-  totalTokens: number;
 }
 
 const windowOptions: { key: interfaces.TControllerUsageWindow; label: string; description: string }[] = [
@@ -42,12 +48,15 @@ const modelKey = (bucketArg: Pick<interfaces.IControllerUsageBucket, 'provider'
   `${bucketArg.provider}/${bucketArg.model}`
 );
 
-/** Every token a call counted: input, output, cache read and cache write. */
+/** Every token a call counted: input, output and the cache reads and writes it stated. */
 const totalTokens = (countsArg: TUsageCounts): number => (
   countsArg.inputTokens + countsArg.outputTokens + countsArg.cacheReadTokens + countsArg.cacheWriteTokens
 );
 
-const emptyCounts = (): TUsageCounts => ({ calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 });
+const emptyCounts = (): TUsageCounts => ({ calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
+  cacheReadUnknownCalls: 0, cacheWriteUnknownCalls: 0 });
+
+const emptyRowCounts = (): IMetricsRowCounts => ({ ...emptyCounts(), totalTokens: 0, totalLowerBound: false });
 
 const addCounts = (targetArg: TUsageCounts, bucketArg: TUsageCounts): void => {
   targetArg.calls += bucketArg.calls;
@@ -55,6 +64,31 @@ const addCounts = (targetArg: TUsageCounts, bucketArg: TUsageCounts): void => {
   targetArg.outputTokens += bucketArg.outputTokens;
   targetArg.cacheReadTokens += bucketArg.cacheReadTokens;
   targetArg.cacheWriteTokens += bucketArg.cacheWriteTokens;
+  targetArg.cacheReadUnknownCalls += bucketArg.cacheReadUnknownCalls;
+  targetArg.cacheWriteUnknownCalls += bucketArg.cacheWriteUnknownCalls;
+};
+
+const addBucket = (rowArg: IMetricsRowCounts, bucketArg: interfaces.IControllerUsageBucket): void => {
+  addCounts(rowArg, bucketArg);
+  rowArg.totalTokens += totalTokens(bucketArg);
+  rowArg.totalLowerBound ||= interfaces.controllerUsageTotalIsLowerBound[bucketArg.provider]
+    && (bucketArg.cacheReadUnknownCalls > 0 || bucketArg.cacheWriteUnknownCalls > 0);
+};
+
+/** The cache counts the board states: reads and writes, each with the calls that did not state theirs. */
+const cacheCounts = {
+  cacheReadTokens: 'cacheReadUnknownCalls',
+  cacheWriteTokens: 'cacheWriteUnknownCalls',
+} as const satisfies Record<string, keyof TUsageCounts>;
+
+/**
+ * A cache count as the board states it: what the calls stated; "≥" before it when some calls did not state theirs, as
+ * those read or wrote an unknown number, not none; and "Unknown" when no call stated any.
+ */
+const cacheText = (countsArg: TUsageCounts, keyArg: keyof typeof cacheCounts, formatArg: Intl.NumberFormat): string => {
+  const stated = countsArg[keyArg], unknownCalls = countsArg[cacheCounts[keyArg]];
+  return unknownCalls === 0 ? formatArg.format(stated)
+    : stated === 0 && unknownCalls === countsArg.calls ? 'Unknown' : `≥ ${formatArg.format(stated)}`;
 };
 
 const compactNumber = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 });
@@ -68,7 +102,8 @@ const pointTimeFormatters: Record<interfaces.TControllerUsageSpan, (epochMsArg:
   hour: (epochMsArg) => momentFormat.formatRange(epochMsArg, epochMsArg + interfaces.controllerUsageSpanMs.hour),
 };
 
-const countColumns = <TRow extends TUsageCounts & { totalTokens: number }>(): plugins.deesCatalog.Column<TRow>[] => (
+/** The count columns; a cache count as `cacheText` states it, and the total with "≥" when it is a lower bound. */
+const countColumns = <TRow extends IMetricsRowCounts>(): plugins.deesCatalog.Column<TRow>[] => (
   ([
     ['calls', 'Calls'],
     ['inputTokens', 'Input'],
@@ -80,7 +115,9 @@ const countColumns = <TRow extends TUsageCounts & { totalTokens: number }>(): pl
     key: keyArg,
     header: headerArg,
     align: 'end' as const,
-    renderer: (valueArg: number) => fullNumber.format(valueArg),
+    renderer: (valueArg: number, rowArg: TRow) => (keyArg === 'cacheReadTokens' || keyArg === 'cacheWriteTokens'
+      ? cacheText(rowArg, keyArg, fullNumber)
+      : keyArg === 'totalTokens' && rowArg.totalLowerBound ? `≥ ${fullNumber.format(valueArg)}` : fullNumber.format(valueArg)),
   }))
 );
 
@@ -375,11 +412,10 @@ export class AglMetricsBoard extends plugins.deesElement.DeesElement {
       const key = modelKey(bucket);
       let row = rows.get(key);
       if (!row) {
-        row = { key, provider: bucket.provider, model: bucket.model, ...emptyCounts(), totalTokens: 0 };
+        row = { key, provider: bucket.provider, model: bucket.model, ...emptyRowCounts() };
         rows.set(key, row);
       }
-      addCounts(row, bucket);
-      row.totalTokens += totalTokens(bucket);
+      addBucket(row, bucket);
     }
     return [...rows.values()];
   }
@@ -393,11 +429,10 @@ export class AglMetricsBoard extends plugins.deesElement.DeesElement {
       const key = JSON.stringify([bucket.harness, bucket.session]);
       let row = rows.get(key);
       if (!row) {
-        row = { key, harness, session, ...emptyCounts(), totalTokens: 0 };
+        row = { key, harness, session, ...emptyRowCounts() };
         rows.set(key, row);
       }
-      addCounts(row, bucket);
-      row.totalTokens += totalTokens(bucket);
+      addBucket(row, bucket);
     }
     return [...rows.values()];
   }
@@ -409,12 +444,27 @@ export class AglMetricsBoard extends plugins.deesElement.DeesElement {
     return [
       { id: 'input', title: 'Input', value: value(counts.inputTokens), unit: 'tokens', type: 'number', icon: 'lucide:ArrowDownToLine' },
       { id: 'output', title: 'Output', value: value(counts.outputTokens), unit: 'tokens', type: 'number', icon: 'lucide:ArrowUpFromLine' },
-      { id: 'cacheRead', title: 'Cache read', value: value(counts.cacheReadTokens), unit: 'tokens', type: 'number', icon: 'lucide:DatabaseZap' },
-      { id: 'cacheWrite', title: 'Cache write', value: value(counts.cacheWriteTokens), unit: 'tokens', type: 'number', icon: 'lucide:Database' },
+      this.cacheTile(counts, knownArg, 'cacheReadTokens'),
+      this.cacheTile(counts, knownArg, 'cacheWriteTokens'),
       { id: 'calls', title: 'Calls', value: value(counts.calls), type: 'number', icon: 'lucide:Activity' },
     ];
   }
 
+  /**
+   * A cache read or write tile: "Unknown" without a unit when no call stated its count, "≥" the stated count when some
+   * did not, and then how many calls left it unknown.
+   */
+  private cacheTile(countsArg: TUsageCounts, knownArg: boolean, keyArg: keyof typeof cacheCounts): plugins.deesCatalog.IStatsTile {
+    const text = knownArg ? cacheText(countsArg, keyArg, compactNumber) : '–';
+    const unknownCalls = countsArg[cacheCounts[keyArg]];
+    const tile = keyArg === 'cacheReadTokens' ? { id: 'cacheRead', title: 'Cache read', icon: 'lucide:DatabaseZap' }
+      : { id: 'cacheWrite', title: 'Cache write', icon: 'lucide:Database' };
+    return { ...tile, value: text, ...(text === 'Unknown' ? {} : { unit: 'tokens' }), type: 'number',
+      ...(knownArg && unknownCalls > 0
+        ? { description: `Unknown for ${fullNumber.format(unknownCalls)} of ${fullNumber.format(countsArg.calls)} calls` }
+        : {}) };
+  }
+
   /**
    * One series per model, the largest first, each drawn from zero: its tokens per minute in every span of the window,
    * the empty ones as 0. A minute that is still open is left out, as its count is partial; the totals and tables keep