fix(usage): persist the absolute context checkpoint in usage rows

Kiro rows in Logs showed only small per-request estimates because the
cumulative context figure never reached usage.jsonl.

Two individually-correct changes composed into the regression:

- fc51700 threaded a Kiro absolute context checkpoint
  (OcxUsage.contextTotalTokens) through the adapter and the bridge, and
  proved persistence with a test that re-parses the bridged SSE wire,
  where responsesUsage() folds the checkpoint into input_tokens /
  total_tokens. The separate field was not needed on that path.
- 0422ce1 (landed later on dev) made the bridge report RAW adapter
  usage via onUsage and made applyResponseLogMetadata skip wire
  re-parsing when usageFromBridge is set, so synthetic zero detail
  objects could no longer be misread as measured cache numbers.

After the second change the logged usage is the raw per-attempt object,
where the cumulative figure exists only as contextTotalTokens — and
normalizeUsageValue() omitted that key from its field whitelist, so it
was dropped at write time. Zero rows in a 5202-row live Kiro sample
carried it.

normalizeUsageValue() now carries contextTotalTokens, and the read-side
validator accepts it. The checkpoint is deliberately NOT folded into
totalTokens: it is an absolute snapshot, not a per-request total, and
must never be summed across requests.

Cache read/write detail is untouched: cost estimation and the
cache_detail_missing reason read only the three cache fields, so the
provenance behavior 0422ce1 protected still holds.

Tests: the new request-log case covers the production composition
(onUsage + usageFromBridge) end to end through usage.jsonl, which the
existing wire-reparse test could not catch.

Author: lidge-jun

src/usage/log.ts

@@ -128,6 +128,13 @@ function normalizeUsageValue(usage: OcxUsage | undefined): OcxUsage | undefined
   return {
     inputTokens: usage.inputTokens,
     outputTokens: usage.outputTokens,
+    // Absolute active-context checkpoint (types.ts). Stateful providers such as Kiro report
+    // per-attempt usage only, so this field is the ONLY carrier of the cumulative context
+    // figure once the log records raw adapter usage instead of re-parsing the bridged wire
+    // (usageFromBridge, request-log.ts). Omitting it here silently dropped Kiro's context
+    // growth from every persisted row. It is deliberately NOT folded into totalTokens:
+    // a checkpoint is not a per-request total and must never be summed across requests.
+    ...(typeof usage.contextTotalTokens === "number" ? { contextTotalTokens: usage.contextTotalTokens } : {}),
     ...(typeof usage.totalTokens === "number" ? { totalTokens: usage.totalTokens } : {}),
     ...(typeof usage.cachedInputTokens === "number" ? { cachedInputTokens: usage.cachedInputTokens } : {}),
     ...(typeof usage.cacheReadInputTokens === "number" ? { cacheReadInputTokens: usage.cacheReadInputTokens } : {}),
@@ -162,6 +169,7 @@ function normalizeAttemptUsage(raw: unknown): OcxUsage | null {
   if (!isNonNegativeFiniteNumber(usage.inputTokens)
     || !isNonNegativeFiniteNumber(usage.outputTokens)) return null;
   for (const key of [
+    "contextTotalTokens",
     "totalTokens",
     "cachedInputTokens",
     "cacheReadInputTokens",

tests/request-log.test.ts

@@ -24,8 +24,16 @@ import {
   type RequestLogContext,
 } from "../src/server/request-log";
 import { bridgeToResponsesSSE } from "../src/bridge";
-import type { AdapterEvent } from "../src/types";
-import type { PersistedUsageEntry } from "../src/usage/log";
+import type { AdapterEvent, OcxUsage } from "../src/types";
+import {
+  appendUsageEntry,
+  readUsageEntries,
+  resetUsageReadCacheForTests,
+  type PersistedUsageEntry,
+} from "../src/usage/log";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 async function* replayAdapterEvents(events: AdapterEvent[]): AsyncGenerator<AdapterEvent> {
   for (const event of events) yield event;
@@ -933,6 +941,94 @@ describe("request log metadata", () => {
     });
   });
 
+  test("deferred logging keeps the checkpoint when the bridge reports raw usage (production path)", async () => {
+    // Regression guard for the composition that shipped the bug. The test above exercises the
+    // OLD source of logged usage: re-parsing the bridged wire, where responsesUsage() folds
+    // contextTotalTokens into input_tokens/total_tokens. Production no longer does that —
+    // responses/core.ts wires bridgeToResponsesSSE's onUsage callback, stores the RAW adapter
+    // usage and sets usageFromBridge, which suppresses wire re-parsing. In that shape the
+    // cumulative figure exists ONLY as contextTotalTokens, so usage-log normalization has to
+    // carry the field or Kiro context growth vanishes from every persisted row.
+    const entries: RequestLogEntry[] = [];
+    let reportedRaw: OcxUsage | undefined;
+    const logCtx: Partial<RequestLogContext> = {
+      model: "kiro/claude-opus-5",
+      provider: "kiro-p9d8524",
+      usageLogInputTokens: 200,
+    };
+    const body = bridgeToResponsesSSE(
+      replayAdapterEvents([{
+        type: "done",
+        usage: {
+          inputTokens: 58,
+          outputTokens: 100,
+          contextTotalTokens: 50_000,
+          estimated: true,
+        },
+      }]),
+      "kiro/claude-opus-5",
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      {
+        onUsage: usage => {
+          // Mirror responses/core.ts: store RAW adapter usage and mark provenance so the
+          // deferred logger does not re-parse the wire.
+          reportedRaw = usage;
+          logCtx.usageFromBridge = true;
+          if (usage) logCtx.usage = usage;
+        },
+      },
+    );
+    const response = responseWithDeferredRequestLog(
+      new Response(body, { status: 200, headers: { "content-type": "text/event-stream" } }),
+      "ocx-test-kiro-raw-usage-checkpoint",
+      Date.now(),
+      logCtx,
+      entry => entries.push(entry),
+    );
+    await response.text();
+
+    // The bridge hands the logger the RAW adapter usage, not the projected wire shape.
+    expect(reportedRaw).toMatchObject({ inputTokens: 58, contextTotalTokens: 50_000 });
+    expect(entries).toHaveLength(1);
+    const logged = entries[0]?.usage;
+    expect(logged?.contextTotalTokens).toBe(50_000);
+    // Cache detail stays absent so cost estimation still reports cache_detail_missing —
+    // the provenance behavior that the raw-usage change was introduced to protect.
+    expect(logged && "cacheReadInputTokens" in logged).toBe(false);
+    expect(logged && "cacheCreationInputTokens" in logged).toBe(false);
+
+    // End-to-end: the checkpoint must also survive serialization to usage.jsonl. Asserting
+    // only the in-memory entry would pass even while persistence silently drops the field,
+    // which is exactly how the original regression escaped review.
+    const home = mkdtempSync(join(tmpdir(), "ocx-req-log-usage-"));
+    const previousHome = process.env.OPENCODEX_HOME;
+    process.env.OPENCODEX_HOME = home;
+    try {
+      resetUsageReadCacheForTests();
+      appendUsageEntry({
+        requestId: entries[0]!.requestId,
+        timestamp: entries[0]!.timestamp,
+        provider: entries[0]!.provider,
+        model: entries[0]!.model,
+        status: entries[0]!.status,
+        durationMs: entries[0]!.durationMs,
+        usageStatus: entries[0]!.usageStatus,
+        ...(logged ? { usage: logged } : {}),
+      });
+      const [persisted] = readUsageEntries();
+      expect(persisted?.usage?.contextTotalTokens).toBe(50_000);
+    } finally {
+      if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+      else process.env.OPENCODEX_HOME = previousHome;
+      resetUsageReadCacheForTests();
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
   test("final logging shows numeric Kiro estimates even when SSE usage is absent", async () => {
     const entries: RequestLogEntry[] = [];
     const response = responseWithDeferredRequestLog(

tests/usage-log.test.ts

@@ -102,6 +102,51 @@ describe("usage log", () => {
     })]);
   });
 
+  test("persists an absolute context checkpoint for stateful providers", () => {
+    // Kiro reports per-attempt usage only, so contextTotalTokens is the sole carrier of the
+    // cumulative context figure once the log stores raw adapter usage (usageFromBridge).
+    // Dropping it here erased Kiro context growth from every persisted row.
+    appendUsageEntry({
+      requestId: "ocx-context-checkpoint",
+      timestamp: 1,
+      provider: "kiro",
+      model: "claude-opus-5",
+      status: 200,
+      durationMs: 10,
+      usageStatus: "estimated",
+      usage: { inputTokens: 220, outputTokens: 252, contextTotalTokens: 127_000, estimated: true },
+      totalTokens: 472,
+    });
+    expect(readUsageEntries()).toEqual([expect.objectContaining({
+      requestId: "ocx-context-checkpoint",
+      usage: expect.objectContaining({
+        inputTokens: 220,
+        outputTokens: 252,
+        contextTotalTokens: 127_000,
+        estimated: true,
+      }),
+      // The checkpoint must NOT be folded into the per-request total.
+      totalTokens: 472,
+    })]);
+  });
+
+  test("never invents a context checkpoint when the adapter reported none", () => {
+    appendUsageEntry({
+      requestId: "ocx-no-checkpoint",
+      timestamp: 1,
+      provider: "kiro",
+      model: "claude-opus-5",
+      status: 200,
+      durationMs: 10,
+      usageStatus: "estimated",
+      usage: { inputTokens: 61, outputTokens: 48, estimated: true },
+      totalTokens: 109,
+    });
+    const [entry] = readUsageEntries();
+    expect(entry?.usage).toBeDefined();
+    expect(entry?.usage && "contextTotalTokens" in entry.usage).toBe(false);
+  });
+
   test("persists only canonical ordered attempt fields", () => {
     appendUsageEntry({
       requestId: "ocx-attempts",