agl 41.1.0 → 41.2.0

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