agl 41.1.0 → 41.2.0

package/dist_ts_interfaces/metrics.d.ts

@@ -8,8 +8,26 @@ export type TControllerUsageSpan = 'minute' | 'hour';
 export type TControllerUsageWindow = '1h' | '24h' | '7d';
 export declare const controllerUsageWindows: readonly TControllerUsageWindow[];
 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;
@@ -23,13 +41,17 @@ 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 declare const controllerUsageTotalIsLowerBound: Readonly<Record<TControllerUsageProvider, boolean>>;
 /** The span each window reads and how many spans it shows, the current one included. */
 export declare const controllerUsageWindowSpans: Record<TControllerUsageWindow, {
     span: TControllerUsageSpan;

package/dist_ts_interfaces/metrics.js

@@ -1,4 +1,17 @@
 export const controllerUsageWindows = ['1h', '24h', '7d'];
+/**
+ * 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 = {
+    anthropic: true,
+    openai: false,
+};
 const minuteMs = 60_000;
 const hourMs = 60 * minuteMs;
 /** The span each window reads and how many spans it shows, the current one included. */
@@ -32,4 +45,4 @@ export const applyControllerUsageDelta = (viewArg, deltaArg) => {
     viewArg.revision = deltaArg.revision;
     return 'applied';
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWV0cmljcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBc0MsQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLElBQUksQ0FBQyxDQUFDO0FBMEI3RixNQUFNLFFBQVEsR0FBRyxNQUFNLENBQUM7QUFDeEIsTUFBTSxNQUFNLEdBQUcsRUFBRSxHQUFHLFFBQVEsQ0FBQztBQUU3Qix3RkFBd0Y7QUFDeEYsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQWtGO0lBQ3ZILElBQUksRUFBRSxFQUFFLElBQUksRUFBRSxRQUFRLEVBQUUsS0FBSyxFQUFFLEVBQUUsRUFBRTtJQUNuQyxLQUFLLEVBQUUsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxFQUFFLEVBQUU7SUFDbEMsSUFBSSxFQUFFLEVBQUUsSUFBSSxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsQ0FBQyxHQUFHLEVBQUUsRUFBRTtDQUN0QyxDQUFDO0FBRUYsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQXlDLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLENBQUM7QUFFOUcsd0dBQXdHO0FBQ3hHLE1BQU0sQ0FBQyxNQUFNLDBCQUEwQixHQUFHLENBQUMsU0FBaUMsRUFBRSxNQUFjLEVBQVUsRUFBRTtJQUN0RyxNQUFNLEVBQUUsSUFBSSxFQUFFLEtBQUssRUFBRSxHQUFHLDBCQUEwQixDQUFDLFNBQVMsQ0FBQyxDQUFDO0lBQzlELE1BQU0sTUFBTSxHQUFHLHFCQUFxQixDQUFDLElBQUksQ0FBQyxDQUFDO0lBQzNDLE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDLEdBQUcsTUFBTSxHQUFHLENBQUMsS0FBSyxHQUFHLENBQUMsQ0FBQyxHQUFHLE1BQU0sQ0FBQztBQUNyRSxDQUFDLENBQUM7QUFFRjs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxxQkFBcUIsR0FBRyxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUUsWUFBWSxFQUFFLEdBQUcsRUFBVyxDQUFDO0FBcUJyRjs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxDQUFDLE9BQTZCLEVBQUUsUUFBK0IsRUFBNEIsRUFBRTtJQUNwSSxJQUFJLE9BQU8sSUFBSSxRQUFRLElBQUksUUFBUSxDQUFDLEtBQUssS0FBSyxPQUFPLENBQUMsS0FBSyxJQUFJLFFBQVEsQ0FBQyxNQUFNLEtBQUssT0FBTyxDQUFDLE1BQU07V0FDNUYsUUFBUSxDQUFDLFFBQVEsS0FBSyxPQUFPLENBQUMsUUFBUSxHQUFHLENBQUM7UUFBRSxPQUFPLFlBQVksQ0FBQztJQUNyRSxLQUFLLE1BQU0sTUFBTSxJQUFJLFFBQVEsQ0FBQyxPQUFPO1FBQUUsT0FBTyxDQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLEVBQUUsRUFBRSxNQUFNLENBQUMsQ0FBQztJQUM5RSxPQUFPLENBQUMsUUFBUSxHQUFHLFFBQVEsQ0FBQyxRQUFRLENBQUM7SUFDckMsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWV0cmljcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2ludGVyZmFjZXMvbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBc0MsQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLElBQUksQ0FBQyxDQUFDO0FBdUM3Rjs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxNQUFNLGdDQUFnQyxHQUF3RDtJQUNuRyxTQUFTLEVBQUUsSUFBSTtJQUNmLE1BQU0sRUFBRSxLQUFLO0NBQ2QsQ0FBQztBQUVGLE1BQU0sUUFBUSxHQUFHLE1BQU0sQ0FBQztBQUN4QixNQUFNLE1BQU0sR0FBRyxFQUFFLEdBQUcsUUFBUSxDQUFDO0FBRTdCLHdGQUF3RjtBQUN4RixNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBa0Y7SUFDdkgsSUFBSSxFQUFFLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxLQUFLLEVBQUUsRUFBRSxFQUFFO0lBQ25DLEtBQUssRUFBRSxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLEVBQUUsRUFBRTtJQUNsQyxJQUFJLEVBQUUsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLEtBQUssRUFBRSxDQUFDLEdBQUcsRUFBRSxFQUFFO0NBQ3RDLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSxxQkFBcUIsR0FBeUMsRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsQ0FBQztBQUU5Ryx3R0FBd0c7QUFDeEcsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsQ0FBQyxTQUFpQyxFQUFFLE1BQWMsRUFBVSxFQUFFO0lBQ3RHLE1BQU0sRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLEdBQUcsMEJBQTBCLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDOUQsTUFBTSxNQUFNLEdBQUcscUJBQXFCLENBQUMsSUFBSSxDQUFDLENBQUM7SUFDM0MsT0FBTyxJQUFJLENBQUMsS0FBSyxDQUFDLE1BQU0sR0FBRyxNQUFNLENBQUMsR0FBRyxNQUFNLEdBQUcsQ0FBQyxLQUFLLEdBQUcsQ0FBQyxDQUFDLEdBQUcsTUFBTSxDQUFDO0FBQ3JFLENBQUMsQ0FBQztBQUVGOzs7R0FHRztBQUNILE1BQU0sQ0FBQyxNQUFNLHFCQUFxQixHQUFHLEVBQUUsT0FBTyxFQUFFLE1BQU0sRUFBRSxZQUFZLEVBQUUsR0FBRyxFQUFXLENBQUM7QUFxQnJGOzs7R0FHRztBQUNILE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHLENBQUMsT0FBNkIsRUFBRSxRQUErQixFQUE0QixFQUFFO0lBQ3BJLElBQUksT0FBTyxJQUFJLFFBQVEsSUFBSSxRQUFRLENBQUMsS0FBSyxLQUFLLE9BQU8sQ0FBQyxLQUFLLElBQUksUUFBUSxDQUFDLE1BQU0sS0FBSyxPQUFPLENBQUMsTUFBTTtXQUM1RixRQUFRLENBQUMsUUFBUSxLQUFLLE9BQU8sQ0FBQyxRQUFRLEdBQUcsQ0FBQztRQUFFLE9BQU8sWUFBWSxDQUFDO0lBQ3JFLEtBQUssTUFBTSxNQUFNLElBQUksUUFBUSxDQUFDLE9BQU87UUFBRSxPQUFPLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxNQUFNLENBQUMsRUFBRSxFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQzlFLE9BQU8sQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFDLFFBQVEsQ0FBQztJQUNyQyxPQUFPLFNBQVMsQ0FBQztBQUNuQixDQUFDLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agl",
-  "version": "41.1.0",
+  "version": "41.2.0",
   "controllerUpgradeManagementVersion": 2,
   "controllerManagementProtocolVersion": 1,
   "private": false,
@@ -34,10 +34,10 @@
     "@lossless.org/objectstorage": "10.7.1",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@modelprofile.com/catalog": "^1.1.0",
-    "@modelprofile.com/flexharness": "16.4.0",
-    "@modelprofile.com/flexharness-agent": "16.4.0",
-    "@modelprofile.com/flexharness-models": "16.4.0",
-    "@modelprofile.com/flexharness-providers": "16.4.0",
+    "@modelprofile.com/flexharness": "17.0.0",
+    "@modelprofile.com/flexharness-agent": "17.0.0",
+    "@modelprofile.com/flexharness-models": "17.0.0",
+    "@modelprofile.com/flexharness-providers": "17.0.0",
     "@modelprofile.com/mcp-crossharness": "5.9.0",
     "@modelprofile.com/mcp-system": "3.1.0",
     "@opencode-ai/sdk": "1.18.15",

package/readme.md

@@ -628,7 +628,15 @@ proxy then keeps the account out of rotation itself until it restarts, and says
 The proxy also records the tokens every answer states -- input, output, cache reads and cache writes -- per minute and per
 hour, model, client name, account and the session id the client sent, minutes for a day and hours for eight days, also
 for an Anthropic API key; it keeps no prompt, answer or credential, and a write that fails is reported on its standard
-error and retried with the next. The controller reads these only while a browser watches a usage window:
+error and retried with the next. An answer that does not state its cache reads or writes (a ChatGPT answer without
+`input_tokens_details.cache_write_tokens`, a Claude answer whose `cache_read_input_tokens` or
+`cache_creation_input_tokens` is missing or null) has unknown cache reads or writes, not none: each bucket counts the
+reads and writes its answers stated (`cacheReadTokens`, `cacheWriteTokens`) and, beside them, the answers that did not
+state theirs (`cacheReadUnknownCalls`, `cacheWriteUnknownCalls`). An OpenAI account's unknown cache counts stay in its
+input count, since OpenAI counts every input token there; a Claude account's input leaves the cache out, so a bucket of
+one with unknown cache counts adds up to less than its answers used (`controllerUsageTotalIsLowerBound`). A bucket
+stored before AGL counted them reads with all its answers unknown. The controller reads these only while a browser
+watches a usage window:
 `controller.metrics.usage.watch { window }` (`1h` by minute, `24h` or `7d` by hour) answers the window's buckets with
 a `watchId`, the feed's `epoch` and a `revision`, and the changes follow on that connection alone as `usage.changed`
 events, each continuing the revision before it, until `controller.metrics.usage.unwatch { watchId }` or the
@@ -642,7 +650,10 @@ is told to watch again and refused. An unreachable proxy refuses a watch with `p
 
 The web app's header has a **Metrics** button. It shows the token usage in the main pane, as the Board button
 shows the board; leaving it ends its watch. A toggle chooses the last hour, day or week. Totals for input, output,
-cache reads, cache writes and calls head the view; below them a line chart shows the tokens per minute by model, each
+cache reads, cache writes and calls head the view; cache reads and writes read **Unknown** when no call stated any, and
+**≥** the stated count when some calls did not, with the number of calls whose count is unknown under the tile (the
+model and session tables say the same, and their **Total** reads **≥** when it leaves out a Claude answer's unknown
+cache count); below them a line chart shows the tokens per minute by model, each
 model's line drawn from zero (each completed minute for the hour, the hourly average for the day and week, the current
 hour's over its minutes so far), and pointing at a moment lists every model's value there with the time. A table lists
 every model the window counted, sorted by total tokens. A model's row opens a second table of its sessions by client and session id. The
@@ -737,8 +748,8 @@ accepted without effect. What cannot be translated faithfully is refused with a
 Code then continues without them), server-side context management, code execution containers, remote MCP servers and
 deferred tool loading, whose betas `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` keeps Claude Code from sending. Of an
 answer Claude Code gets the model's text, its tool calls, its reasoning summary as thinking, the stop reason and the
-token counts (input, output, cache reads); the backend's response id, its own headers and the rest of its response do
-not reach it.
+token counts (input, output, cache reads and writes, a cache count `null` when the backend did not state it); the
+backend's response id, its own headers and the rest of its response do not reach it.
 
 Reasoning effort: Claude Code sends its effort as `output_config.effort` (`low` to `max`, chosen with `/effort`,
 `--effort` or `CLAUDE_CODE_EFFORT_LEVEL`), together with adaptive thinking; Claude Code 2.1.288, the release of AGL's

package/ts/00_commitinfo_data.ts

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

package/ts/aglapi/aglapisurface.document.ts

@@ -3765,7 +3765,7 @@ export const AGL_API_SURFACE: plugins.flexTypedRequest.IFlexTypedRequestSurface
           },
           "protocolVersion": {
             "type": "number",
-            "const": 46
+            "const": 47
           },
           "upgradeManagementVersion": {
             "type": "number"
@@ -3891,7 +3891,7 @@ export const AGL_API_SURFACE: plugins.flexTypedRequest.IFlexTypedRequestSurface
         ],
         "additionalProperties": false
       },
-      "declaration": "interface IControllerStatus {\n  packageName: string;\n  packageVersion: string;\n  protocolVersion: 46;\n  upgradeManagementVersion: number;\n  /**\n   * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent\n   * from a controller older than the endpoint, which is reached over its socket.\n   */\n  managementProtocolVersion?: number;\n  controllerPid: number;\n  processGroupId: number;\n  processFingerprint: string;\n  processMode: TControllerProcessMode;\n  lifecycleState: TControllerLifecycleState;\n  startedAt: number;\n  setupRequired: boolean;\n  /** Present when the controller runs as the systemd user unit (`agl service install`); absent for a detached or foreground one. */\n  serviceUnit?: \"agl-controller.service\";\n  /** The TLS mode of the runtime configuration the controller runs with; absent until it is resolved. */\n  tlsMode?: TControllerTlsMode;\n  upgrade?: IControllerUpgradeStatus;\n  /** AGL's inference proxy, by state only; details need a signed-in owner (`controller.proxy.status.get`). */\n  proxy?: { state: TControllerProxyState };\n  harnesses: Array<{\n    harnessId: TControllerSessionHarnessId;\n    pid?: number;\n    state: TControllerHarnessLifecycleState;\n    healthy: boolean;\n    version?: string;\n    supportsLocalAttachments?: boolean;\n    connectionMode?: 'local' | 'shared' | 'remote';\n    diagnostic?: IControllerCodexDiagnostic;\n    /** Codex only: automatic reconnection of this entry's profile to the local shared app-server. */\n    rejoin?: IControllerCodexRejoinStatus;\n    /**\n     * Codex only, on the controller status: every connected or required profile. The entry's\n     * `healthy` is then true only when each of them is, apart from a profile on an account Codex\n     * cannot run on now, listed `stopped` with an `account_unavailable` diagnostic that says why;\n     * its other members describe the default profile.\n     */\n    profiles?: IControllerCodexProfileStatus[];\n  }>;\n}"
+      "declaration": "interface IControllerStatus {\n  packageName: string;\n  packageVersion: string;\n  protocolVersion: 47;\n  upgradeManagementVersion: number;\n  /**\n   * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent\n   * from a controller older than the endpoint, which is reached over its socket.\n   */\n  managementProtocolVersion?: number;\n  controllerPid: number;\n  processGroupId: number;\n  processFingerprint: string;\n  processMode: TControllerProcessMode;\n  lifecycleState: TControllerLifecycleState;\n  startedAt: number;\n  setupRequired: boolean;\n  /** Present when the controller runs as the systemd user unit (`agl service install`); absent for a detached or foreground one. */\n  serviceUnit?: \"agl-controller.service\";\n  /** The TLS mode of the runtime configuration the controller runs with; absent until it is resolved. */\n  tlsMode?: TControllerTlsMode;\n  upgrade?: IControllerUpgradeStatus;\n  /** AGL's inference proxy, by state only; details need a signed-in owner (`controller.proxy.status.get`). */\n  proxy?: { state: TControllerProxyState };\n  harnesses: Array<{\n    harnessId: TControllerSessionHarnessId;\n    pid?: number;\n    state: TControllerHarnessLifecycleState;\n    healthy: boolean;\n    version?: string;\n    supportsLocalAttachments?: boolean;\n    connectionMode?: 'local' | 'shared' | 'remote';\n    diagnostic?: IControllerCodexDiagnostic;\n    /** Codex only: automatic reconnection of this entry's profile to the local shared app-server. */\n    rejoin?: IControllerCodexRejoinStatus;\n    /**\n     * Codex only, on the controller status: every connected or required profile. The entry's\n     * `healthy` is then true only when each of them is, apart from a profile on an account Codex\n     * cannot run on now, listed `stopped` with an `account_unavailable` diagnostic that says why;\n     * its other members describe the default profile.\n     */\n    profiles?: IControllerCodexProfileStatus[];\n  }>;\n}"
     },
     {
       "name": "IControllerTerminalResource",

package/ts/classes.inferencegateway.ts

@@ -1009,10 +1009,11 @@ export class InferenceGateway {
               if (spent) this.options.router.recordSpend(accountId, route.loginId, spent);
               else this.options.router.uncountedSpend(accountId, answeredArg.model ?? route.model.modelId);
             } : undefined)
-          : new InferenceClaudeUsageTap(answerFormat, (usageArg) => {
+          : new InferenceClaudeUsageTap(answerFormat, (usageArg, cacheStatedArg) => {
             if (route.provider === 'anthropic') this.options.router.countTokens(accountId, usageArg);
             recordUsage({ inputTokens: usageArg.inputTokens, outputTokens: usageArg.outputTokens,
-              cacheReadTokens: usageArg.cacheReadTokens, cacheWriteTokens: usageArg.cacheWrite5mTokens + usageArg.cacheWrite1hTokens });
+              cacheReadTokens: cacheStatedArg.reads ? usageArg.cacheReadTokens : null,
+              cacheWriteTokens: cacheStatedArg.writes ? usageArg.cacheWrite5mTokens + usageArg.cacheWrite1hTokens : null });
           // An API key's answer is priced as it ends, and its spend counts against the key's limit from then on.
           }, route.provider === 'anthropic' && route.credential === 'api_key' ? (answeredArg) => {
             const spent = inferenceAnthropicSpend(answeredArg, route.model.modelId, Date.now(), inferenceAnthropicServerToolTypes(body));

package/ts/classes.inferenceusage.ts

@@ -1,16 +1,19 @@
 import * as plugins from './plugins.js';
 import { inferenceProviders, type TInferenceProvider } from './functions.proxycontract.js';
-import type { IControllerUsageBucket, TControllerUsageSpan } from '../ts_interfaces/index.js';
+import type { IControllerUsageBucket, IControllerUsageCounts, TControllerUsageSpan } from '../ts_interfaces/index.js';
 
 /**
  * The tokens one answer used, by kind. Input counts only the tokens read neither from nor written to the provider's
  * prompt cache; the cache reads and writes are counted on their own, so the four add up to everything the answer used.
+ * `cacheReadTokens` and `cacheWriteTokens` are `null` when the answer did not state them, which is not the same as
+ * stating none. Whether the input count then holds them depends on the provider (`controllerUsageTotalIsLowerBound`):
+ * an OpenAI account's input counts every input token, an Anthropic account's leaves the cache out.
  */
 export interface IInferenceTokenCounts {
   inputTokens: number;
   outputTokens: number;
-  cacheReadTokens: number;
-  cacheWriteTokens: number;
+  cacheReadTokens: number | null;
+  cacheWriteTokens: number | null;
 }
 
 /**
@@ -33,8 +36,12 @@ export interface IInferenceUsageLedger {
   record(recordArg: IInferenceUsageRecord): void;
 }
 
+/** The counts a bucket stored before unknown cache counts were kept lacks. */
+type TUnknownCountKey = 'cacheReadUnknownCalls' | 'cacheWriteUnknownCalls';
+const unknownCountKeys: readonly TUnknownCountKey[] = ['cacheReadUnknownCalls', 'cacheWriteUnknownCalls'];
+
 /** One minute or hour of one model's tokens on one harness, account and session, as the proxy keeps it. */
-export interface IInferenceUsageBucket extends IInferenceTokenCounts {
+export interface IInferenceUsageBucket extends IControllerUsageCounts {
   /** The bucket's digest: SHA-256 of its span, start and dimensions. */
   id: string;
   span: TControllerUsageSpan;
@@ -45,16 +52,29 @@ export interface IInferenceUsageBucket extends IInferenceTokenCounts {
   harness: string | null;
   accountId: string;
   session: string | null;
-  /** The answers counted. */
-  calls: number;
   /** When a flush last added to the bucket. */
   updatedAt: Date;
 }
 
-export interface IInferenceUsageDocument extends IInferenceUsageBucket {
+/**
+ * A stored bucket. One written before unknown cache counts were kept has neither `cacheReadUnknownCalls` nor
+ * `cacheWriteUnknownCalls`: it did not record whether its answers stated their cache reads and writes, so each of its
+ * answers reads as one that stated neither.
+ */
+export interface IInferenceUsageDocument extends Omit<IInferenceUsageBucket, TUnknownCountKey>,
+  Partial<Pick<IInferenceUsageBucket, TUnknownCountKey>> {
   expiresAt: Date;
 }
 
+/** A stored bucket's counts, those of a bucket written before unknown cache counts were kept with every answer unknown. */
+const storedCounts = (documentArg: Omit<IInferenceUsageDocument, 'id' | 'span' | 'start' | 'provider' | 'model' | 'harness'
+  | 'accountId' | 'session' | 'updatedAt' | 'expiresAt'>): IControllerUsageCounts => ({
+  calls: documentArg.calls, inputTokens: documentArg.inputTokens, outputTokens: documentArg.outputTokens,
+  cacheReadTokens: documentArg.cacheReadTokens, cacheWriteTokens: documentArg.cacheWriteTokens,
+  cacheReadUnknownCalls: documentArg.cacheReadUnknownCalls ?? documentArg.calls,
+  cacheWriteUnknownCalls: documentArg.cacheWriteUnknownCalls ?? documentArg.calls,
+});
+
 /** A usage flush that failed, as the proxy reports it: no session id, prompt or account id. */
 export interface IInferenceUsageFlushFailure {
   /** The buckets kept for the next flush. */
@@ -96,10 +116,14 @@ const pageDocuments = 128;
 
 const validDate = (valueArg: unknown): valueArg is Date => valueArg instanceof Date && Number.isFinite(valueArg.getTime());
 const validCount = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
+/** A count of a bucket's answers: whole, and at most the answers it counts. */
+const countWithin = (countArg: unknown, callsArg: unknown): boolean => validCount(countArg) && validCount(callsArg) && countArg <= callsArg;
 
 const assertDocument: (valueArg: unknown) => asserts valueArg is IInferenceUsageDocument = (valueArg) => {
   const value = valueArg as Partial<IInferenceUsageDocument> | null;
-  if (!value || typeof value !== 'object' || Object.keys(value).length !== 15
+  // A bucket written before unknown cache counts were kept has neither of them; every bucket written since has both.
+  const kept = !!value && typeof value === 'object' && Object.hasOwn(value, 'cacheWriteUnknownCalls');
+  if (!value || typeof value !== 'object' || Object.keys(value).length !== 15 + (kept ? unknownCountKeys.length : 0)
     || typeof value.id !== 'string' || !hex64.test(value.id)
     || !usageSpans.includes(value.span as TControllerUsageSpan)
     || !validDate(value.start) || value.start.getTime() % spanMs[value.span as TControllerUsageSpan] !== 0
@@ -111,6 +135,7 @@ const assertDocument: (valueArg: unknown) => asserts valueArg is IInferenceUsage
     || !validCount(value.calls) || value.calls < 1
     || !validCount(value.inputTokens) || !validCount(value.outputTokens)
     || !validCount(value.cacheReadTokens) || !validCount(value.cacheWriteTokens)
+    || (kept && !unknownCountKeys.every((keyArg) => countWithin(value[keyArg], value.calls)))
     || !validDate(value.updatedAt) || !validDate(value.expiresAt)) {
     throw new Error('Invalid inference usage bucket.');
   }
@@ -134,6 +159,9 @@ export class InferenceUsageModel extends plugins.nosqldb.SmartDataDbDoc<Inferenc
   @plugins.nosqldb.svDb() public outputTokens!: number;
   @plugins.nosqldb.svDb() public cacheReadTokens!: number;
   @plugins.nosqldb.svDb() public cacheWriteTokens!: number;
+  /** These two are absent only on a bucket written before unknown cache counts were kept; every write sets them. */
+  @plugins.nosqldb.svDb() public cacheReadUnknownCalls?: number;
+  @plugins.nosqldb.svDb() public cacheWriteUnknownCalls?: number;
   @plugins.nosqldb.svDb()
   @plugins.nosqldb.index() public updatedAt!: Date;
   @plugins.nosqldb.svDb()
@@ -259,9 +287,11 @@ export class InferenceUsageStore implements IInferenceUsageLedger {
   public record(recordArg: IInferenceUsageRecord): void {
     try {
       if (this.stopped) return;
-      const counts = [recordArg.inputTokens, recordArg.outputTokens, recordArg.cacheReadTokens, recordArg.cacheWriteTokens];
+      const counts = [recordArg.inputTokens, recordArg.outputTokens, recordArg.cacheReadTokens ?? 0, recordArg.cacheWriteTokens ?? 0];
       if (!inferenceProviders.includes(recordArg.provider) || !usageModelPattern.test(recordArg.model)
         || (recordArg.harness !== null && !usageHarnessPattern.test(recordArg.harness)) || !hex64.test(recordArg.accountId)
+        || (recordArg.cacheReadTokens !== null && !validCount(recordArg.cacheReadTokens))
+        || (recordArg.cacheWriteTokens !== null && !validCount(recordArg.cacheWriteTokens))
         || !counts.every(validCount) || counts.every((countArg) => countArg === 0)) {
         this.droppedRecords += 1;
         return;
@@ -280,12 +310,12 @@ export class InferenceUsageStore implements IInferenceUsageLedger {
         this.droppedRecords += 1;
         return;
       }
+      const answer = answerCounts(recordArg);
       for (const { span, start, id } of buckets) {
         const held = this.pending.get(id);
-        if (held) { addCounts(held, recordArg, 1); continue; }
+        if (held) { addCounts(held, answer); continue; }
         this.pending.set(id, { id, span, start: new Date(start), provider: recordArg.provider, model: recordArg.model,
-          harness: recordArg.harness, accountId: recordArg.accountId, session, calls: 1, inputTokens: recordArg.inputTokens,
-          outputTokens: recordArg.outputTokens, cacheReadTokens: recordArg.cacheReadTokens, cacheWriteTokens: recordArg.cacheWriteTokens });
+          harness: recordArg.harness, accountId: recordArg.accountId, session, ...answer });
       }
     } catch {
       this.droppedRecords += 1;
@@ -364,7 +394,7 @@ export class InferenceUsageStore implements IInferenceUsageLedger {
     // The buckets that were not written join those recorded since, as far as the pending limit allows.
     for (const bucket of failed) {
       const held = this.pending.get(bucket.id);
-      if (held) addCounts(held, bucket, bucket.calls);
+      if (held) addCounts(held, bucket);
       else if (this.pending.size < maximumPendingBuckets) this.pending.set(bucket.id, bucket);
       else this.droppedRecords += bucket.calls;
     }
@@ -388,7 +418,10 @@ export class InferenceUsageStore implements IInferenceUsageLedger {
         return;
       }
       const result = await InferenceUsageModel.exact.transition({ current, change: (modelArg) => {
-        addCounts(modelArg, bucketArg, bucketArg.calls);
+        // A bucket written before unknown cache counts were kept gets them, its own answers as unknown.
+        const counts = storedCounts(modelArg);
+        addCounts(counts, bucketArg);
+        Object.assign(modelArg, counts);
         modelArg.updatedAt = updatedAt;
       } }, { signal: signalArg });
       if (result.status === 'transitioned') {
@@ -418,15 +451,21 @@ export class InferenceUsageStore implements IInferenceUsageLedger {
 }
 
 /** A stored bucket as a reader receives it: its start in Unix milliseconds, without its bookkeeping. */
-const wireBucket = (documentArg: IInferenceUsageBucket): IControllerUsageBucket => ({ id: documentArg.id, span: documentArg.span,
+const wireBucket = (documentArg: IInferenceUsageDocument): IControllerUsageBucket => ({ id: documentArg.id, span: documentArg.span,
   start: documentArg.start.getTime(), provider: documentArg.provider, model: documentArg.model, harness: documentArg.harness,
-  accountId: documentArg.accountId, session: documentArg.session, calls: documentArg.calls, inputTokens: documentArg.inputTokens,
-  outputTokens: documentArg.outputTokens, cacheReadTokens: documentArg.cacheReadTokens, cacheWriteTokens: documentArg.cacheWriteTokens });
+  accountId: documentArg.accountId, session: documentArg.session, ...storedCounts(documentArg) });
+
+/** One answer as a bucket counts it: the cache counts it stated, and for each it did not, one answer unknown. */
+const answerCounts = (countsArg: IInferenceTokenCounts): IControllerUsageCounts => ({ calls: 1, inputTokens: countsArg.inputTokens,
+  outputTokens: countsArg.outputTokens, cacheReadTokens: countsArg.cacheReadTokens ?? 0, cacheWriteTokens: countsArg.cacheWriteTokens ?? 0,
+  cacheReadUnknownCalls: countsArg.cacheReadTokens === null ? 1 : 0, cacheWriteUnknownCalls: countsArg.cacheWriteTokens === null ? 1 : 0 });
 
-const addCounts = (targetArg: IInferenceTokenCounts & { calls: number }, addArg: IInferenceTokenCounts, callsArg: number): void => {
-  targetArg.calls += callsArg;
+const addCounts = (targetArg: IControllerUsageCounts, addArg: IControllerUsageCounts): void => {
+  targetArg.calls += addArg.calls;
   targetArg.inputTokens += addArg.inputTokens;
   targetArg.outputTokens += addArg.outputTokens;
   targetArg.cacheReadTokens += addArg.cacheReadTokens;
   targetArg.cacheWriteTokens += addArg.cacheWriteTokens;
+  targetArg.cacheReadUnknownCalls += addArg.cacheReadUnknownCalls;
+  targetArg.cacheWriteUnknownCalls += addArg.cacheWriteUnknownCalls;
 };

package/ts/classes.inferenceusagetap.ts

@@ -29,6 +29,16 @@ interface IStatedUsage {
   ephemeral_1h_input_tokens?: number;
 }
 
+/**
+ * Which cache counts an Anthropic Messages answer stated: `reads` its `cache_read_input_tokens`, `writes` its
+ * `cache_creation_input_tokens` or its `cache_creation` split. Anthropic documents both as `number or null`, and a
+ * translated answer gives null for a count the model did not state.
+ */
+export interface IInferenceClaudeCacheStated {
+  reads: boolean;
+  writes: boolean;
+}
+
 /** 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;
@@ -43,7 +53,9 @@ export interface IInferenceUsageTap {
  * A stream (`sse`) states usage in `message_start` (`message.usage`, `message.model`) and in `message_delta` (`usage`,
  * 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.
+ * reports nothing: the estimate is the authority's, and the answer is never at stake. The report says which cache
+ * counts the answer stated (`IInferenceClaudeCacheStated`): one it did not state is unknown, not none. The usage
+ * reported for the estimate counts an unknown one as none, as the account service's token usage has no unknown.
  *
  * `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
@@ -66,7 +78,8 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
   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, cacheStatedArg: IInferenceClaudeCacheStated) => void,
     private readonly answered?: (answeredArg: IInferenceAnsweredUsage) => void) {}
 
   /** Reads a chunk the relay passed on; never throws. */
@@ -102,7 +115,11 @@ export class InferenceClaudeUsageTap implements IInferenceUsageTap {
       }
       this.stopped = true;
       const usage = this.usage();
-      if (usage) this.report(usage);
+      if (usage) {
+        this.report(usage, { reads: this.stated.cache_read_input_tokens !== undefined,
+          writes: this.stated.cache_creation_input_tokens !== undefined || this.stated.ephemeral_5m_input_tokens !== undefined
+            || this.stated.ephemeral_1h_input_tokens !== undefined });
+      }
     } catch { this.stopped = true; } finally {
       try {
         this.answered?.({ ...(this.model === undefined ? {} : { model: this.model }), ...(this.raw ? { usage: this.raw } : {}),
@@ -207,7 +224,8 @@ const searchCallTypes: ReadonlyMap<string, 'web' | 'file'> = new Map([['web_sear
  * `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.
+ * `input_tokens_details` are taken out of it. An answer that does not state `cached_tokens` or `cache_write_tokens`
+ * reports those as unknown (`null`), never as none, and its input count then holds whatever it read or wrote.
  *
  * `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
@@ -380,10 +398,11 @@ export class InferenceResponsesUsageTap implements IInferenceUsageTap {
     const output = count(usage?.output_tokens);
     if (input === undefined && output === undefined) return undefined;
     const details = record(usage?.input_tokens_details);
-    const cacheRead = count(details?.cached_tokens) ?? 0;
-    const cacheWrite = count(details?.cache_write_tokens) ?? 0;
-    const counts: IInferenceTokenCounts = { inputTokens: Math.max(0, (input ?? 0) - cacheRead - cacheWrite),
+    const cacheRead = count(details?.cached_tokens) ?? null;
+    const cacheWrite = count(details?.cache_write_tokens) ?? null;
+    const counts: IInferenceTokenCounts = { inputTokens: Math.max(0, (input ?? 0) - (cacheRead ?? 0) - (cacheWrite ?? 0)),
       outputTokens: output ?? 0, cacheReadTokens: cacheRead, cacheWriteTokens: cacheWrite };
-    return counts.inputTokens + counts.outputTokens + counts.cacheReadTokens + counts.cacheWriteTokens > 0 ? counts : undefined;
+    return counts.inputTokens + counts.outputTokens + (counts.cacheReadTokens ?? 0) + (counts.cacheWriteTokens ?? 0) > 0
+      ? counts : undefined;
   }
 }

package/ts/classes.usagefeed.ts

@@ -68,7 +68,8 @@ const bucketOrder = (leftArg: IControllerUsageBucket, rightArg: IControllerUsage
 
 const sameCounts = (leftArg: IControllerUsageBucket, rightArg: IControllerUsageBucket): boolean => leftArg.calls === rightArg.calls
   && leftArg.inputTokens === rightArg.inputTokens && leftArg.outputTokens === rightArg.outputTokens
-  && leftArg.cacheReadTokens === rightArg.cacheReadTokens && leftArg.cacheWriteTokens === rightArg.cacheWriteTokens;
+  && leftArg.cacheReadTokens === rightArg.cacheReadTokens && leftArg.cacheWriteTokens === rightArg.cacheWriteTokens
+  && leftArg.cacheReadUnknownCalls === rightArg.cacheReadUnknownCalls && leftArg.cacheWriteUnknownCalls === rightArg.cacheWriteUnknownCalls;
 
 /**
  * The metrics board's usage feed in the controller. The proxy keeps the token usage and has no push, so the feed reads

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. */

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.1.0',
+  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 => {