@devries-cameron20 / t3code Mirror · read-only / commits / 729f6757d9
Fork 0

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 }