Skip to content

Commit f39c219

Browse files
committed
fix(usage): merge claude usage copies by per-field maximum
Subagent transcripts write a partial stream-start copy of each message first, so keeping the first copy undercounted output about five times.
1 parent cfafb4b commit f39c219

7 files changed

Lines changed: 464 additions & 76 deletions

File tree

‎apps/server/src/provider/Drivers/claudeUsage.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,10 @@ import {
1313
import * as HostProcess from "@t3tools/shared/HostProcess";
1414

1515
/**
16-
* T3 Code writes one record per assistant *content block*, and every one of those records repeats
17-
* the same complete `usage` object for the parent message. Summing them overcounts by roughly
18-
* 2.4x on a real workload, so the caller must drop repeats by `dedupeKey` and keep the first.
16+
* Claude Code writes one record per assistant *content block*, all sharing the message's
17+
* `dedupeKey`, so summing them overcounts. The copies do not always agree: subagent transcripts
18+
* put the stream-start snapshot, a few output tokens, on the first block and the final usage on
19+
* the last. The caller keeps each channel's maximum per key (`mergeUsageCopies`).
1920
*/
2021
export function parseClaudeLine(line: string): UsageRecord | null {
2122
let parsed: unknown;

‎apps/server/src/usage/UsageService.test.ts‎

Lines changed: 201 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,42 @@ function claudeLine(id: number, outputTokens: number, model = "claude-fable-5"):
6161
})}\n`;
6262
}
6363

64+
/** One content-block line of message `msg_1`; Claude Code writes several per message. */
65+
function claudeCopy(usage: Readonly<Record<string, number>>, sessionId = "session-1"): string {
66+
return `${JSON.stringify({
67+
type: "assistant",
68+
timestamp: "2026-08-01T10:00:00Z",
69+
requestId: "req_1",
70+
sessionId,
71+
message: { id: "msg_1", model: "claude-fable-5", usage },
72+
})}\n`;
73+
}
74+
75+
/** The two lines of one subagent message from #20246: its stream-start copy, then its final copy. */
76+
const PARTIAL_USAGE = {
77+
input_tokens: 2,
78+
cache_creation_input_tokens: 1097,
79+
cache_read_input_tokens: 67934,
80+
output_tokens: 3,
81+
};
82+
const COMPLETE_USAGE = { ...PARTIAL_USAGE, output_tokens: 264 };
83+
const COPY_RATES = {
84+
"claude-fable-5": {
85+
input_cost_per_token: 1e-5,
86+
output_cost_per_token: 5e-5,
87+
cache_read_input_token_cost: 1e-6,
88+
cache_creation_input_token_cost: 1.25e-5,
89+
},
90+
};
91+
const COMPLETE_COST_USD = 2 * 1e-5 + 67934 * 1e-6 + 1097 * 1.25e-5 + 264 * 5e-5;
92+
const COMPLETE_TOTALS = {
93+
uncachedInputTokens: 2,
94+
cachedInputTokens: 67934,
95+
cacheCreationTokens: 1097,
96+
outputTokens: 264,
97+
reasoningTokens: 0,
98+
};
99+
64100
const WINDOW: UsageSummaryInput = {
65101
timeZone: "UTC",
66102
sinceDay: UsageDay.make("2026-07-31"),
@@ -1363,6 +1399,125 @@ describe("UsageService", () => {
13631399
}).pipe(Effect.scoped),
13641400
);
13651401

1402+
it.live("counts a message's complete copy while it is still the unterminated tail", () =>
1403+
Effect.gen(function* () {
1404+
const { transcript, settings, home } = yield* setup;
1405+
yield* Effect.promise(() =>
1406+
NodeFSP.writeFile(
1407+
transcript,
1408+
claudeCopy(PARTIAL_USAGE) + claudeCopy(COMPLETE_USAGE).trimEnd(),
1409+
),
1410+
);
1411+
yield* Effect.gen(function* () {
1412+
const service = yield* UsageService.make;
1413+
const tail = yield* service.readSummary(WINDOW);
1414+
assert.deepStrictEqual(tail.buckets[0]?.totals, COMPLETE_TOTALS);
1415+
assert.strictEqual(tail.buckets[0]?.records, 1);
1416+
assert.closeTo(tail.buckets[0]?.costUsd ?? 0, COMPLETE_COST_USD, 1e-12);
1417+
1418+
yield* Effect.promise(() => NodeFSP.appendFile(transcript, "\n"));
1419+
assert.deepStrictEqual((yield* service.readSummary(WINDOW)).buckets, tail.buckets);
1420+
yield* service.awaitPersisted;
1421+
const restored = yield* (yield* UsageService.make).readSummary(WINDOW);
1422+
assert.deepStrictEqual(restored.buckets, tail.buckets);
1423+
}).pipe(
1424+
Effect.provide(
1425+
layerService({
1426+
prefix: "usage-service-copy-tail-test",
1427+
home,
1428+
settings,
1429+
ratesDocument: COPY_RATES,
1430+
}),
1431+
),
1432+
);
1433+
}).pipe(Effect.scoped),
1434+
);
1435+
1436+
it.live("drops a tail copy's counts when the writer replaces that tail", () =>
1437+
Effect.gen(function* () {
1438+
const { transcript, settings, home } = yield* setup;
1439+
const partial = claudeCopy(PARTIAL_USAGE);
1440+
yield* Effect.promise(() =>
1441+
NodeFSP.writeFile(transcript, partial + claudeCopy(COMPLETE_USAGE).trimEnd()),
1442+
);
1443+
yield* Effect.gen(function* () {
1444+
const service = yield* UsageService.make;
1445+
assert.strictEqual(totalOutputTokens(yield* service.readSummary(WINDOW)), 264);
1446+
1447+
// Same settled prefix, longer file: the scan resumes and re-reads the old tail's bytes.
1448+
yield* Effect.promise(() =>
1449+
NodeFSP.writeFile(transcript, partial + claudeLine(2, 7) + claudeLine(3, 5)),
1450+
);
1451+
const replaced = yield* service.readSummary(WINDOW);
1452+
assert.strictEqual(totalOutputTokens(replaced), 3 + 7 + 5);
1453+
yield* service.awaitPersisted;
1454+
const restored = yield* (yield* UsageService.make).readSummary(WINDOW);
1455+
assert.deepStrictEqual(restored.buckets, replaced.buckets);
1456+
}).pipe(
1457+
Effect.provide(
1458+
layerService({ prefix: "usage-service-replaced-tail-test", home, settings }),
1459+
),
1460+
);
1461+
}).pipe(Effect.scoped),
1462+
);
1463+
1464+
it.live("completes a cached partial copy from bytes appended later", () =>
1465+
Effect.gen(function* () {
1466+
const { transcript, settings, home } = yield* setup;
1467+
yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeCopy(PARTIAL_USAGE)));
1468+
yield* Effect.gen(function* () {
1469+
const service = yield* UsageService.make;
1470+
assert.strictEqual(totalOutputTokens(yield* service.readSummary(WINDOW)), 3);
1471+
yield* service.awaitPersisted;
1472+
1473+
yield* Effect.promise(() => NodeFSP.appendFile(transcript, claudeCopy(COMPLETE_USAGE)));
1474+
const grown = yield* (yield* UsageService.make).readSummary(WINDOW);
1475+
assert.deepStrictEqual(grown.buckets[0]?.totals, COMPLETE_TOTALS);
1476+
assert.strictEqual(grown.buckets[0]?.records, 1);
1477+
assert.closeTo(grown.buckets[0]?.costUsd ?? 0, COMPLETE_COST_USD, 1e-12);
1478+
}).pipe(
1479+
Effect.provide(
1480+
layerService({
1481+
prefix: "usage-service-copy-resume-test",
1482+
home,
1483+
settings,
1484+
ratesDocument: COPY_RATES,
1485+
}),
1486+
),
1487+
);
1488+
}).pipe(Effect.scoped),
1489+
);
1490+
1491+
it.live("does not let a zeroed replay read first hide the original copy's usage", () =>
1492+
Effect.gen(function* () {
1493+
const { transcript, settings, home } = yield* setup;
1494+
const dir = NodePath.dirname(transcript);
1495+
const [first = "", second = ""] = yield* Effect.promise(async () => {
1496+
await NodeFSP.writeFile(NodePath.join(dir, "a.jsonl"), "");
1497+
await NodeFSP.writeFile(NodePath.join(dir, "b.jsonl"), "");
1498+
return (await NodeFSP.readdir(dir)).map((name) => NodePath.join(dir, name));
1499+
});
1500+
yield* Effect.promise(async () => {
1501+
await NodeFSP.writeFile(first, claudeCopy({ input_tokens: 0, output_tokens: 0 }, "fork"));
1502+
await NodeFSP.writeFile(second, claudeCopy(PARTIAL_USAGE) + claudeCopy(COMPLETE_USAGE));
1503+
});
1504+
const summary = yield* UsageService.make.pipe(
1505+
Effect.flatMap((service) => service.readSummary(WINDOW)),
1506+
Effect.provide(
1507+
layerService({
1508+
prefix: "usage-service-zeroed-replay-test",
1509+
home,
1510+
settings,
1511+
ratesDocument: COPY_RATES,
1512+
}),
1513+
),
1514+
);
1515+
assert.deepStrictEqual(summary.buckets[0]?.totals, COMPLETE_TOTALS);
1516+
assert.strictEqual(summary.buckets[0]?.records, 1);
1517+
assert.closeTo(summary.buckets[0]?.costUsd ?? 0, COMPLETE_COST_USD, 1e-12);
1518+
}).pipe(Effect.scoped),
1519+
);
1520+
13661521
it.live(
13671522
"keeps large-record totals and costs exact through append, dedupe, restart and cleanup",
13681523
() =>
@@ -1456,7 +1611,7 @@ describe("UsageService", () => {
14561611

14571612
yield* Effect.gen(function* () {
14581613
const { stateDir } = yield* ServerConfig.ServerConfig;
1459-
const cachePath = NodePath.join(stateDir, "usage-scan-cache-v5.json");
1614+
const cachePath = NodePath.join(stateDir, "usage-scan-cache-v6.json");
14601615
const legacyPath = NodePath.join(stateDir, "usage-scan-cache.json");
14611616
const first = yield* UsageService.make;
14621617
yield* first.readSummary(WINDOW);
@@ -1507,6 +1662,51 @@ describe("UsageService", () => {
15071662
}).pipe(Effect.scoped),
15081663
);
15091664

1665+
it.live(
1666+
"upgrades a v5 cache: re-parses live partial copies, keeps deleted transcripts, leaves v5 intact",
1667+
() =>
1668+
Effect.gen(function* () {
1669+
const { transcript, settings, home } = yield* setup;
1670+
const deleted = NodePath.join(NodePath.dirname(transcript), "deleted.jsonl");
1671+
yield* Effect.promise(async () => {
1672+
await NodeFSP.writeFile(
1673+
transcript,
1674+
claudeCopy(PARTIAL_USAGE) + claudeCopy(COMPLETE_USAGE),
1675+
);
1676+
await NodeFSP.writeFile(deleted, claudeLine(2, 7));
1677+
});
1678+
1679+
yield* Effect.gen(function* () {
1680+
const { stateDir } = yield* ServerConfig.ServerConfig;
1681+
const cachePath = NodePath.join(stateDir, "usage-scan-cache-v6.json");
1682+
const v5Path = NodePath.join(stateDir, "usage-scan-cache-v5.json");
1683+
const first = yield* UsageService.make;
1684+
yield* first.readSummary(WINDOW);
1685+
yield* first.awaitPersisted;
1686+
1687+
// A v5 server kept the first copy, so its row for msg_1 holds the partial count.
1688+
const v5 = yield* Effect.promise(async () => {
1689+
const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
1690+
files: Record<string, { r: unknown[][] }>;
1691+
};
1692+
const entry = document.files[transcript]!;
1693+
entry.r = entry.r.map((row) => [...row.slice(0, 6), 3, ...row.slice(7)]);
1694+
const text = encodeUnknownJsonString({ ...document, version: 5 });
1695+
await NodeFSP.writeFile(v5Path, text);
1696+
await NodeFSP.rm(cachePath);
1697+
await NodeFSP.rm(deleted);
1698+
return text;
1699+
});
1700+
1701+
const summary = yield* (yield* UsageService.make).readSummary(WINDOW);
1702+
assert.strictEqual(totalOutputTokens(summary), 264 + 7);
1703+
assert.strictEqual(yield* Effect.promise(() => NodeFSP.readFile(v5Path, "utf8")), v5);
1704+
}).pipe(
1705+
Effect.provide(layerService({ prefix: "usage-service-v5-upgrade-test", home, settings })),
1706+
);
1707+
}).pipe(Effect.scoped),
1708+
);
1709+
15101710
it.live("preserves saved tokens, costs and sessions after transcript cleanup and restart", () =>
15111711
Effect.gen(function* () {
15121712
const { transcript, settings, home } = yield* setup;

‎apps/server/src/usage/UsageService.ts‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,8 @@ import {
5050
import {
5151
decodeScanCache,
5252
dedupeWithinFile,
53-
LEGACY_SCAN_CACHE_FILE_NAME,
5453
makeScanCacheWriter,
54+
PREVIOUS_SCAN_CACHE_FILE_NAMES,
5555
pruneScanCache,
5656
SCAN_CACHE_FILE_NAME,
5757
type CachedFile,
@@ -202,7 +202,9 @@ export const make = Effect.gen(function* () {
202202

203203
const ratesCachePath = path.join(config.stateDir, "usage-model-rates.json");
204204
const scanCachePath = path.join(config.stateDir, SCAN_CACHE_FILE_NAME);
205-
const legacyScanCachePath = path.join(config.stateDir, LEGACY_SCAN_CACHE_FILE_NAME);
205+
const previousScanCachePaths = PREVIOUS_SCAN_CACHE_FILE_NAMES.map((name) =>
206+
path.join(config.stateDir, name),
207+
);
206208
const writeCacheFile = (filePath: string, contents: string) =>
207209
writeFileStringAtomically({ filePath, contents }).pipe(
208210
Effect.provideService(FileSystem.FileSystem, fileSystem),
@@ -378,8 +380,9 @@ export const make = Effect.gen(function* () {
378380
Effect.catchCause(() => Effect.succeed(null)),
379381
);
380382
let document = yield* readDocument(scanCachePath);
381-
if (document === null) {
382-
document = yield* readDocument(legacyScanCachePath);
383+
for (const previousPath of previousScanCachePaths) {
384+
if (document !== null) break;
385+
document = yield* readDocument(previousPath);
383386
cacheDirty = document !== null;
384387
}
385388
if (document === null) return;
@@ -435,7 +438,7 @@ export const make = Effect.gen(function* () {
435438
/**
436439
* Reads run concurrently, and the caller stores updates in walk order rather
437440
* than completion order: saved records of deleted transcripts aggregate in
438-
* cache order, where the first copy of a duplicate wins.
441+
* cache order, where the first copy of a duplicate decides its bucket.
439442
*/
440443
const readFileRecords = (
441444
filePath: string,
@@ -485,9 +488,8 @@ export const make = Effect.gen(function* () {
485488
};
486489

487490
const base = parsed.resumed && cached !== undefined ? cached.records : [];
488-
const seen = new Set<string>();
489-
const records = dedupeWithinFile([...base, ...parsed.records], seen);
490-
const tailRecords = dedupeWithinFile(parsed.tailRecords, seen);
491+
const records = dedupeWithinFile([...base, ...parsed.records]);
492+
const tailRecords = parsed.tailRecords;
491493

492494
return {
493495
records: tailRecords.length === 0 ? records : [...records, ...tailRecords],
@@ -604,7 +606,7 @@ export const make = Effect.gen(function* () {
604606

605607
// Independent sources scan together. Transcript directories go one at a
606608
// time, so open files stay at `TRANSCRIPT_READ_CONCURRENCY`. The result
607-
// keeps this order, since aggregation keeps the first copy of a duplicate.
609+
// keeps this order, since the first copy decides a duplicate's bucket.
608610
const [transcripts, scanDirs] = yield* Effect.all(
609611
[Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs)), scans],
610612
{ concurrency: "unbounded" },

0 commit comments

Comments
 (0)