The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 23:30 UTC
fix(usage): Claude subagent output is no longer undercounted (#20276)
Co-authored-by: Julius Marminge <julius0216@outlook.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Richard Frost committed
Nov 11, 2026 at 09:43 UTC
729f6757d91d9c45614150da297ea7d919bbe81d
7 files changed
+251
-50
apps/server/src/provider/Drivers/claudeUsage.ts
+3
-3
@@ -16,9 +16,9 @@ import * as HostProcess from "@t3tools/shared/HostProcess";
16
export const CLAUDE_SYNTHETIC_MODEL = "<synthetic>";
17
18
/**
19
- * T3 Code writes one record per assistant *content block*, and every one of those records repeats
20
- * the same complete `usage` object for the parent message. Summing them overcounts by roughly
21
- * 2.4x on a real workload, so the caller must drop repeats by `dedupeKey` and keep the first.
19
+ * Claude Code repeats a message's `dedupeKey` for each assistant content block.
20
+ * Subagent blocks can progress from stream-start to final usage, so callers
21
+ * must count each key once using the maximum of each token channel.
22
*/
23
export function parseClaudeLine(line: string): readonly UsageRecord[] {
24
let parsed: unknown;
apps/server/src/usage/UsageService.test.ts
+96
-1
@@ -93,6 +93,42 @@ function claudeLine(
93
})}\n`;
94
}
95
96
+/** One content-block line of message `msg_1`; Claude Code writes several per message. */
97
+function claudeCopy(usage: Readonly<Record<string, number>>): string {
98
+ return `${JSON.stringify({
99
+ type: "assistant",
100
+ timestamp: "2026-08-01T10:00:00Z",
101
+ requestId: "req_1",
102
+ sessionId: "session-1",
103
+ message: { id: "msg_1", model: "claude-fable-5", usage },
104
+ })}\n`;
105
+}
106
+
107
+// A subagent message: its stream-start copy, then its final copy.
108
+const PARTIAL_USAGE = {
109
+ input_tokens: 2,
110
+ cache_creation_input_tokens: 1097,
111
+ cache_read_input_tokens: 67934,
112
+ output_tokens: 3,
113
+};
114
+const COMPLETE_USAGE = { ...PARTIAL_USAGE, output_tokens: 264 };
115
+const COPY_RATES = {
116
+ "claude-fable-5": {
117
+ input_cost_per_token: 1e-5,
118
+ output_cost_per_token: 5e-5,
119
+ cache_read_input_token_cost: 1e-6,
120
+ cache_creation_input_token_cost: 1.25e-5,
121
+ },
122
+};
123
+const COMPLETE_COST_USD = 2 * 1e-5 + 67934 * 1e-6 + 1097 * 1.25e-5 + 264 * 5e-5;
124
+const COMPLETE_TOTALS = {
125
+ uncachedInputTokens: 2,
126
+ cachedInputTokens: 67934,
127
+ cacheCreationTokens: 1097,
128
+ outputTokens: 264,
129
+ reasoningTokens: 0,
130
+};
131
+
132
const WINDOW: UsageSummaryInput = {
133
timeZone: "UTC",
134
sinceDay: UsageDay.make("2026-07-31"),
@@ -2531,6 +2567,65 @@ describe("UsageService", () => {
2567
}).pipe(Effect.scoped),
2568
);
2569
2570
+ it.live(
2571
+ "merges partial Claude copies through tail replacement, newline completion and restart",
2572
+ () =>
2573
+ Effect.gen(function* () {
2574
+ const { transcript, settings, home } = yield* setup;
2575
+ const partial = claudeCopy(PARTIAL_USAGE);
2576
+ const complete = claudeCopy(COMPLETE_USAGE);
2577
+ yield* Effect.promise(() => NodeFSP.writeFile(transcript, partial));
2578
+ yield* Effect.gen(function* () {
2579
+ const first = yield* UsageService.make;
2580
+ assert.strictEqual(totalOutputTokens(yield* first.readSummary(WINDOW)), 3);
2581
+ yield* first.awaitPersisted;
2582
+
2583
+ yield* Effect.promise(() => NodeFSP.appendFile(transcript, complete.trimEnd()));
2584
+ const resumed = yield* UsageService.make;
2585
+ const tail = yield* resumed.readSummary(WINDOW);
2586
+ assert.deepStrictEqual(tail.buckets[0]?.totals, COMPLETE_TOTALS);
2587
+ assert.strictEqual(tail.buckets[0]?.records, 1);
2588
+ assert.closeTo(tail.buckets[0]?.costUsd ?? 0, COMPLETE_COST_USD, 1e-12);
2589
+ yield* resumed.awaitPersisted;
2590
+ const restarted = yield* UsageService.make;
2591
+ assert.deepStrictEqual((yield* restarted.readSummary(WINDOW)).buckets, tail.buckets);
2592
+
2593
+ // Grow the file without changing its settled prefix: the old tail must be discarded.
2594
+ yield* Effect.promise(() =>
2595
+ NodeFSP.writeFile(transcript, partial + claudeLine(2, 7) + claudeLine(3, 5)),
2596
+ );
2597
+ const replaced = yield* restarted.readSummary(WINDOW);
2598
+ assert.strictEqual(totalOutputTokens(replaced), 3 + 7 + 5);
2599
+ assert.strictEqual(replaced.buckets[0]?.records, 3);
2600
+
2601
+ yield* Effect.promise(() => NodeFSP.appendFile(transcript, complete.trimEnd()));
2602
+ const grown = yield* restarted.readSummary(WINDOW);
2603
+ assert.deepStrictEqual(grown.buckets[0]?.totals, {
2604
+ ...COMPLETE_TOTALS,
2605
+ uncachedInputTokens: 22,
2606
+ outputTokens: 264 + 7 + 5,
2607
+ });
2608
+ assert.strictEqual(grown.buckets[0]?.records, 3);
2609
+ yield* Effect.promise(() => NodeFSP.appendFile(transcript, "\n"));
2610
+ assert.deepStrictEqual((yield* restarted.readSummary(WINDOW)).buckets, grown.buckets);
2611
+ yield* restarted.awaitPersisted;
2612
+ assert.deepStrictEqual(
2613
+ (yield* (yield* UsageService.make).readSummary(WINDOW)).buckets,
2614
+ grown.buckets,
2615
+ );
2616
+ }).pipe(
2617
+ Effect.provide(
2618
+ layerService({
2619
+ prefix: "usage-service-copy-lifecycle-test",
2620
+ home,
2621
+ settings,
2622
+ ratesDocument: COPY_RATES,
2623
+ }),
2624
+ ),
2625
+ );
2626
+ }).pipe(Effect.scoped),
2627
+ );
2628
+
2629
it.live(
2630
"keeps large-record totals and costs exact through append, dedupe, restart and cleanup",
2631
() =>
@@ -2687,7 +2782,7 @@ describe("UsageService", () => {
2782
60 + 20 * (version === 4 ? 1 : 2),
2783
);
2784
yield* upgraded.awaitPersisted;
2690
- assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v11.json");
2785
+ assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v12.json");
2786
assert.deepStrictEqual(
2787
(yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
2788
.filter((name) => name.startsWith("usage-scan-cache"))
apps/server/src/usage/UsageService.ts
+4
-5
@@ -473,7 +473,7 @@ export const make = Effect.gen(function* () {
473
/**
474
* Reads run concurrently, and the caller stores updates in walk order rather
475
* than completion order: saved records of deleted transcripts aggregate in
476
- * cache order, where the first copy of a duplicate wins. Untraced: a scan
476
+ * cache order, where the first copy of a duplicate decides its bucket. Untraced: a scan
477
* reads thousands of files, so scanTranscriptDir records the counts instead.
478
*/
479
const readFileRecords = Effect.fnUntraced(function* (
@@ -551,9 +551,8 @@ export const make = Effect.gen(function* () {
551
}
552
}
553
const base = parsed.resumed && cached !== undefined ? cached.records : [];
554
- const seen = new Set<string>();
555
- const records = dedupeWithinFile([...base, ...parsed.records], seen);
556
- const tailRecords = dedupeWithinFile(parsed.tailRecords, seen);
554
+ const records = dedupeWithinFile([...base, ...parsed.records]);
555
+ const tailRecords = parsed.tailRecords;
556
557
return {
558
records: tailRecords.length === 0 ? records : [...records, ...tailRecords],
@@ -686,7 +685,7 @@ export const make = Effect.gen(function* () {
685
{ concurrency: "unbounded" },
686
);
687
689
- // Scan independent sources together, directories sequentially to bound open files; preserve order for first-copy dedupe.
688
+ // Scan independent sources together, directories sequentially to bound open files; keep order, since the first copy decides a duplicate's bucket.
689
const [transcripts, scanDirs] = yield* Effect.all(
690
[Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs)), scans],
691
{ concurrency: "unbounded" },
apps/server/src/usage/usageAggregation.test.ts
+59
-8
@@ -85,17 +85,68 @@ describe("UsageAggregator", () => {
85
expect(bucket).not.toHaveProperty("ultrafastCostUsd");
86
});
87
88
- it("keeps only the first record for a repeated dedupe key", () => {
88
+ it("merges partial copies of a key by channel maximum in the first copy's bucket", () => {
89
+ const zeroTotals = {
90
+ uncachedInputTokens: 0,
91
+ cachedInputTokens: 0,
92
+ cacheCreationTokens: 0,
93
+ outputTokens: 0,
94
+ reasoningTokens: 0,
95
+ };
96
+ const partial = record({
97
+ dedupeKey: "msg_1:",
98
+ speed: "fast",
99
+ reportedCostUsd: 1,
100
+ totals: { ...record().totals, cachedInputTokens: 1200, outputTokens: 3, reasoningTokens: 5 },
101
+ });
102
+ const complete = record({
103
+ dedupeKey: "msg_1:",
104
+ model: "claude-fable-5[1m]",
105
+ timestampMs: Date.parse("2026-08-08T12:00:00Z"),
106
+ sessionId: "session-fork",
107
+ reportedCostUsd: 2,
108
+ totals: {
109
+ uncachedInputTokens: 2,
110
+ cachedInputTokens: 1000,
111
+ cacheCreationTokens: 40,
112
+ outputTokens: 264,
113
+ reasoningTokens: 135,
114
+ },
115
+ });
116
+ const zero = { ...partial, totals: zeroTotals, reportedCostUsd: null };
117
+ const merged = {
118
+ reportedCostUsd: 2,
119
+ totals: { ...complete.totals, uncachedInputTokens: 100, cachedInputTokens: 1200 },
120
+ };
121
+
122
+ for (const copies of [
123
+ [zero, partial, complete, complete],
124
+ [complete, partial, zero, zero],
125
+ ]) {
126
+ const aggregator = new UsageAggregator({
127
+ timeZone: "UTC",
128
+ sinceDay: "2026-08-01",
129
+ untilDay: "2026-08-31",
130
+ rates,
131
+ });
132
+ copies.forEach((copy, index) => aggregator.add(copy, `${index}.jsonl`));
133
+ const result = aggregator.finish();
134
+ const expected = aggregate([{ ...copies[0]!, ...merged }]).buckets[0];
135
+
136
+ expect(result.duplicatesDropped).toBe(3);
137
+ expect(result.buckets).toEqual([{ ...expected, sourcePath: "0.jsonl" }]);
138
+ }
139
+ });
140
+
141
+ it("does not count a key whose first copy fell outside the window", () => {
142
const result = aggregate([
90
- record({ dedupeKey: "msg_1:" }),
91
- record({ dedupeKey: "msg_1:" }),
92
- record({ dedupeKey: "msg_1:" }),
143
+ record({ dedupeKey: "msg_1:", timestampMs: Date.parse("2026-07-01T12:00:00Z") }),
144
+ record({ dedupeKey: "msg_1:", totals: { ...record().totals, outputTokens: 500 } }),
145
]);
146
95
- expect(result.duplicatesDropped).toBe(2);
96
- expect(result.buckets).toHaveLength(1);
97
- expect(result.buckets[0]?.records).toBe(1);
98
- expect(result.buckets[0]?.totals.outputTokens).toBe(50);
147
+ expect(result.duplicatesDropped).toBe(1);
148
+ expect(result.outOfWindow).toBe(1);
149
+ expect(result.buckets).toHaveLength(0);
150
});
151
152
it("buckets by the day in the requested time zone", () => {
apps/server/src/usage/usageAggregation.ts
+66
-10
@@ -129,10 +129,50 @@ export interface AggregateResult {
129
readonly outOfWindow: number;
130
}
131
132
+/**
133
+ * Partial copies share a billed message's key: keep each token channel's maximum and the larger
134
+ * reported cost, and the first copy's time, model, session and speed so it stays in its bucket.
135
+ */
136
+export function mergeUsageCopies(held: UsageRecord, copy: UsageRecord): UsageRecord {
137
+ const a = held.totals;
138
+ const b = copy.totals;
139
+ const reportedCostUsd =
140
+ held.reportedCostUsd === null || copy.reportedCostUsd === null
141
+ ? (held.reportedCostUsd ?? copy.reportedCostUsd)
142
+ : Math.max(held.reportedCostUsd, copy.reportedCostUsd);
143
+ if (
144
+ b.uncachedInputTokens <= a.uncachedInputTokens &&
145
+ b.cachedInputTokens <= a.cachedInputTokens &&
146
+ b.cacheCreationTokens <= a.cacheCreationTokens &&
147
+ b.outputTokens <= a.outputTokens &&
148
+ b.reasoningTokens <= a.reasoningTokens &&
149
+ reportedCostUsd === held.reportedCostUsd
150
+ ) {
151
+ return held;
152
+ }
153
+ return {
154
+ ...held,
155
+ totals: {
156
+ uncachedInputTokens: Math.max(a.uncachedInputTokens, b.uncachedInputTokens),
157
+ cachedInputTokens: Math.max(a.cachedInputTokens, b.cachedInputTokens),
158
+ cacheCreationTokens: Math.max(a.cacheCreationTokens, b.cacheCreationTokens),
159
+ outputTokens: Math.max(a.outputTokens, b.outputTokens),
160
+ reasoningTokens: Math.max(a.reasoningTokens, b.reasoningTokens),
161
+ },
162
+ reportedCostUsd,
163
+ };
164
+}
165
+
166
+interface Contribution {
167
+ record: UsageRecord;
168
+ /** Null when the first copy fell outside the window. */
169
+ readonly bucket: MutableBucket | null;
170
+}
171
+
172
/** Deduplicates across the whole scan; Claude copies records into resumed/forked transcripts. */
173
export class UsageAggregator {
174
readonly #buckets = new Map<string, MutableBucket>();
135
- readonly #seen = new Set<string>();
175
+ readonly #seen = new Map<string, Contribution>();
176
readonly #toDay: (timestampMs: number) => string;
177
readonly #hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null;
178
readonly #options: AggregateOptions;
@@ -167,20 +207,33 @@ export class UsageAggregator {
207
if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
208
const record = this.#mapModel(input);
209
if (record.dedupeKey !== null) {
170
- if (this.#seen.has(record.dedupeKey)) {
210
+ const held = this.#seen.get(record.dedupeKey);
211
+ if (held !== undefined) {
212
this.#duplicatesDropped += 1;
213
+ if (held.bucket !== null) held.record = mergeUsageCopies(held.record, record);
214
return false;
215
}
174
- this.#seen.add(record.dedupeKey);
216
}
217
218
+ const bucket = this.#placeInWindow(record, sourcePath ?? "");
219
+ if (record.dedupeKey !== null) this.#seen.set(record.dedupeKey, { record, bucket });
220
+ if (bucket === null) {
221
+ this.#outOfWindow += 1;
222
+ return false;
223
+ }
224
+ // Keyed usage is counted in finish(), once all its copies are merged.
225
+ if (record.dedupeKey === null) this.#accumulate(bucket, record);
226
+ if (record.sessionId.length > 0) bucket.sessions.add(record.sessionId);
227
+ return true;
228
+ }
229
+
230
+ #placeInWindow(record: UsageRecord, source: string): MutableBucket | null {
231
if (
232
this.#hourlyWindow !== null &&
233
(record.timestampMs < this.#hourlyWindow.sinceTimeMs ||
234
record.timestampMs >= this.#hourlyWindow.untilTimeMs)
235
) {
182
- this.#outOfWindow += 1;
183
- return false;
236
+ return null;
237
}
238
239
const day = this.#toDay(record.timestampMs);
@@ -188,16 +241,17 @@ export class UsageAggregator {
241
this.#hourlyWindow === null &&
242
(day < this.#options.sinceDay || day > this.#options.untilDay)
243
) {
191
- this.#outOfWindow += 1;
192
- return false;
244
+ return null;
245
}
246
247
const hourIndex =
248
this.#hourlyWindow === null
249
? -1
250
: Math.floor((record.timestampMs - this.#hourlyWindow.sinceTimeMs) / HOUR_MS);
199
- const bucket = this.#bucketFor(day, hourIndex, record.provider, record.model, sourcePath ?? "");
251
+ return this.#bucketFor(day, hourIndex, record.provider, record.model, source);
252
+ }
253
254
+ #accumulate(bucket: MutableBucket, record: UsageRecord): void {
255
const priced = priceUsage(this.#options.rates, record, this.#options.priceOverrides);
256
257
const totals = bucket.totals;
@@ -231,8 +285,6 @@ export class UsageAggregator {
285
bucket.records += 1;
286
if (priced.costSource === "unpriced") bucket.unpricedRecords += 1;
287
if (priced.costSource === "providerReported") bucket.providerReportedRecords += 1;
234
- if (record.sessionId.length > 0) bucket.sessions.add(record.sessionId);
235
- return true;
288
}
289
290
// Aliases use the target's rate, replacing provider-specific rateModel.
@@ -288,6 +340,10 @@ export class UsageAggregator {
340
}
341
342
finish(): AggregateResult {
343
+ for (const { record, bucket } of this.#seen.values()) {
344
+ if (bucket !== null) this.#accumulate(bucket, record);
345
+ }
346
+ this.#seen.clear();
347
const buckets: UsageBucket[] = [];
348
for (const [key, bucket] of this.#buckets) {
349
const [day = "", hourStart = "", provider = "", model = "", sourcePath = ""] =
apps/server/src/usage/usageScanCache.test.ts
+8
-12
@@ -217,15 +217,11 @@ describe("scan cache round trip", () => {
217
};
218
219
const restored = decodeScanCache(JSON.parse(JSON.stringify(legacy)), TEST_FORMAT_MAP);
220
- expect(restored.get("/gone.jsonl")).toEqual(
221
- version >= 10
222
- ? original.get("/gone.jsonl")
223
- : {
224
- ...original.get("/gone.jsonl"),
225
- size: -1,
226
- position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
227
- },
228
- );
220
+ expect(restored.get("/gone.jsonl")).toEqual({
221
+ ...original.get("/gone.jsonl"),
222
+ size: -1,
223
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
224
+ });
225
expect(restored.get("/gone-codex.jsonl")).toEqual({
226
...original.get("/gone-codex.jsonl"),
227
size: -1,
@@ -248,11 +244,11 @@ describe("scan cache round trip", () => {
244
},
245
);
246
251
- it("re-parses a Claude transcript cached before advisor usage was counted", () => {
247
+ it("re-parses a Claude transcript cached before partial copies were merged", () => {
248
const original = cacheWith([["/claude.jsonl", 100, [record()]]]);
253
- const v9 = { ...parse(makeScanCacheWriter()(original, {})), version: 9 };
249
+ const v11 = { ...parse(makeScanCacheWriter()(original, {})), version: 11 };
250
255
- const restored = decodeScanCache(JSON.parse(JSON.stringify(v9)), TEST_FORMAT_MAP);
251
+ const restored = decodeScanCache(JSON.parse(JSON.stringify(v11)), TEST_FORMAT_MAP);
252
expect(restored.get("/claude.jsonl")).toEqual({
253
...original.get("/claude.jsonl"),
254
size: -1,
apps/server/src/usage/usageScanCache.ts
+15
-11
@@ -7,9 +7,10 @@ import type {
7
import * as Schema from "effect/Schema";
8
9
import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
10
+import { mergeUsageCopies } from "./usageAggregation.ts";
11
import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
12
12
-const USAGE_SCAN_CACHE_VERSION = 11 as const;
13
+const USAGE_SCAN_CACHE_VERSION = 12 as const;
14
const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
16
/**
@@ -17,8 +18,9 @@ const SPEED_COMPATIBLE_SINCE_VERSION = 4;
18
* replace it, dropping saved usage for deleted transcripts. Separate files keep
19
* the newer one; older files are removed once it is saved.
20
*/
20
-export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v11.json";
21
+export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v12.json";
22
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23
+ "usage-scan-cache-v11.json",
24
"usage-scan-cache-v10.json",
25
"usage-scan-cache-v9.json",
26
"usage-scan-cache-v8.json",
@@ -289,9 +291,9 @@ export function decodeScanCache(
291
}
292
// Keep history for deleted rollouts, but re-parse incompatible reducer state.
293
// v9 and v11 repair skipped Codex requests; clean v8+ entries stay served while unchanged.
292
- // v10 adds Claude advisor calls, which no older Claude entry holds.
294
+ // v10 adds Claude advisor calls; before v12 a repeated Claude key kept its first, possibly partial, copy.
295
const legacy =
294
- (entry.p === "claude" && version < 10) ||
296
+ (entry.p === "claude" && version < 12) ||
297
(format.state !== undefined &&
298
(version < 6 ||
299
(entry.p === "codex" && (version < 8 || (version < 11 && malformedRecords > 0)))));
@@ -353,16 +355,18 @@ export function pruneScanCache(cache: ScanCache, retentionCutoffMs: number): num
355
return removed;
356
}
357
356
-/** Mutates seen; share it across incremental line/tail batches to deduplicate the whole file. */
357
-export function dedupeWithinFile(
358
- records: readonly UsageRecord[],
359
- seen: Set<string> = new Set(),
360
-): readonly UsageRecord[] {
358
+/** Pass only newline-terminated records: an unterminated tail can still change, so the aggregator merges it per scan. */
359
+export function dedupeWithinFile(records: readonly UsageRecord[]): readonly UsageRecord[] {
360
const kept: UsageRecord[] = [];
361
+ const firstIndex = new Map<string, number>();
362
for (const record of records) {
363
if (record.dedupeKey !== null) {
364
- if (seen.has(record.dedupeKey)) continue;
365
- seen.add(record.dedupeKey);
364
+ const index = firstIndex.get(record.dedupeKey);
365
+ if (index !== undefined) {
366
+ kept[index] = mergeUsageCopies(kept[index]!, record);
367
+ continue;
368
+ }
369
+ firstIndex.set(record.dedupeKey, kept.length);
370
}
371
kept.push(record);
372
}