Skip to content

Commit f8b6a36

Browse files
fix(usage): reconcile completed Claude fallback copies
1 parent bbc718f commit f8b6a36

8 files changed

Lines changed: 179 additions & 32 deletions

File tree

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

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ describe("Claude advisor iterations", () => {
220220
describe("Claude fallback iterations", () => {
221221
// Shaped like Claude Code's records of a server-side fallback: after a mid-stream decline the
222222
// top-level usage names the requested model and merges cache writes across both attempts.
223-
const fallbackTurn = (declinedOutputTokens: number) => ({
223+
const fallbackTurn = (declinedOutputTokens: number, fallbackModel: string | undefined) => ({
224224
type: "assistant",
225225
timestamp: "2026-11-02T03:04:05.000Z",
226226
sessionId: "5a128faa-8253-489e-b935-6c08e8e670c0",
@@ -244,7 +244,7 @@ describe("Claude fallback iterations", () => {
244244
},
245245
{
246246
type: "fallback_message",
247-
model: "claude-opus-4-8",
247+
model: fallbackModel,
248248
input_tokens: 6,
249249
cache_read_input_tokens: 0,
250250
cache_creation_input_tokens: 10000,
@@ -268,14 +268,28 @@ describe("Claude fallback iterations", () => {
268268
},
269269
reportedCostUsd: null,
270270
speed: "standard",
271+
dedupeKey: "msg_fallback:req_fallback:fallback",
272+
supersedesDedupeKey: "msg_fallback:req_fallback",
273+
};
274+
const unattributed = {
275+
...served,
276+
model: "claude-opus-5-5",
277+
totals: { ...served.totals, cacheCreationTokens: 30000 },
271278
dedupeKey: "msg_fallback:req_fallback",
279+
supersedesDedupeKey: undefined,
272280
};
273281

274282
it.each([
275-
{ declined: "before any output", declinedOutputTokens: 0, expected: [served] },
283+
{
284+
declined: "before any output",
285+
declinedOutputTokens: 0,
286+
fallbackModel: "claude-opus-4-8",
287+
expected: [served],
288+
},
276289
{
277290
declined: "mid-stream",
278291
declinedOutputTokens: 250,
292+
fallbackModel: "claude-opus-4-8",
279293
expected: [
280294
served,
281295
{
@@ -289,13 +303,20 @@ describe("Claude fallback iterations", () => {
289303
reasoningTokens: 0,
290304
},
291305
dedupeKey: "msg_fallback:req_fallback:attempt:0",
306+
supersedesDedupeKey: undefined,
292307
},
293308
],
294309
},
310+
...[undefined, "", "<synthetic>"].map((fallbackModel) => ({
311+
declined: `mid-stream with unavailable serving model ${String(fallbackModel)}`,
312+
declinedOutputTokens: 250,
313+
fallbackModel,
314+
expected: [unattributed],
315+
})),
295316
])(
296-
"prices the serving fallback under its own model when the request declined $declined",
297-
({ declinedOutputTokens, expected }) => {
298-
const turn = fallbackTurn(declinedOutputTokens);
317+
"attributes usage when the request declined $declined",
318+
({ declinedOutputTokens, fallbackModel, expected }) => {
319+
const turn = fallbackTurn(declinedOutputTokens, fallbackModel);
299320

300321
expect(claudeUsageFormat.parseLine(JSON.stringify(turn), undefined)).toEqual(expected);
301322
expect(claudeUsageFormat.parseProjected(turn, undefined)).toEqual(expected);

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

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,20 +61,24 @@ function parseClaudeRecord(parsed: unknown): readonly UsageRecord[] {
6161
: [];
6262
// After a server-side fallback the top-level usage can name the declined model and merge
6363
// attempts; the serving `fallback_message` iteration holds what its own model billed.
64-
const servingIndex = iterations.findLastIndex(
64+
const fallbackIndex = iterations.findLastIndex(
6565
(iteration) => iterationRecord(iteration)?.["type"] === "fallback_message",
6666
);
67-
const serving = iterationRecord(iterations[servingIndex]);
67+
const fallback = iterationRecord(iterations[fallbackIndex]);
68+
const fallbackModel = fallback === null ? null : iterationModel(fallback);
69+
const serving = fallbackModel === null ? null : fallback;
70+
const servingIndex = serving === null ? -1 : fallbackIndex;
6871

6972
const executor: UsageRecord = {
7073
provider: "claude",
7174
timestampMs,
72-
model: (serving === null ? null : iterationModel(serving)) ?? model,
75+
model: fallbackModel ?? model,
7376
sessionId: typeof record["sessionId"] === "string" ? record["sessionId"] : "",
7477
totals: usageTotals(serving ?? usageRecord),
7578
reportedCostUsd: typeof cost === "number" && Number.isFinite(cost) ? cost : null,
7679
speed: usageRecord["speed"] === "fast" ? "fast" : "standard",
77-
dedupeKey,
80+
dedupeKey: serving === null || dedupeKey === null ? dedupeKey : `${dedupeKey}:fallback`,
81+
...(serving === null || dedupeKey === null ? {} : { supersedesDedupeKey: dedupeKey }),
7882
};
7983

8084
// Advisor calls and declined attempts bill at their own model's rates. Anthropic bills a

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2782,7 +2782,7 @@ describe("UsageService", () => {
27822782
60 + 20 * (version === 4 ? 1 : 2),
27832783
);
27842784
yield* upgraded.awaitPersisted;
2785-
assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v13.json");
2785+
assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v14.json");
27862786
assert.deepStrictEqual(
27872787
(yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
27882788
.filter((name) => name.startsWith("usage-scan-cache"))

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

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
import { describe, expect, it } from "@effect/vitest";
22

33
import { resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
4+
import { decodeScanCache, dedupeWithinFile, makeScanCacheWriter } from "./usageScanCache.ts";
5+
import { TEST_FORMAT_MAP } from "./usageTestFormats.ts";
6+
import { parseClaudeLine } from "../provider/Drivers/claudeUsage.ts";
47
import type { RateTable } from "./usagePricing.ts";
58
import type { UsageRecord } from "@t3tools/provider-core/server/usage";
69

@@ -149,6 +152,102 @@ describe("UsageAggregator", () => {
149152
expect(result.buckets).toHaveLength(0);
150153
});
151154

155+
it.each([false, true])(
156+
"replaces a fallback's stream-start copy across cached files (reverse=%s)",
157+
(reverse) => {
158+
const attempt = {
159+
type: "message",
160+
model: "claude-opus-5-5",
161+
input_tokens: 3,
162+
cache_creation_input_tokens: 20000,
163+
output_tokens: 250,
164+
};
165+
const fallback = {
166+
type: "fallback_message",
167+
model: "claude-fable-5",
168+
input_tokens: 6,
169+
cache_creation_input_tokens: 10000,
170+
output_tokens: 900,
171+
};
172+
const line = (usage: unknown) =>
173+
JSON.stringify({
174+
type: "assistant",
175+
timestamp: "2026-08-07T04:05:13.944Z",
176+
sessionId: "session-a",
177+
requestId: "req_fallback",
178+
message: { id: "msg_fallback", model: attempt.model, usage },
179+
});
180+
const early = parseClaudeLine(line({ ...attempt, output_tokens: 3 }));
181+
const complete = parseClaudeLine(
182+
line({ ...fallback, cache_creation_input_tokens: 30000, iterations: [attempt, fallback] }),
183+
);
184+
const original = new Map(
185+
[
186+
...new Map<string, readonly UsageRecord[]>([
187+
["/partial.jsonl", early],
188+
["/complete.jsonl", dedupeWithinFile([...early, ...complete, ...complete])],
189+
[
190+
"/deleted.jsonl",
191+
[{ ...early[0]!, totals: { ...early[0]!.totals, cacheCreationTokens: 30000 } }],
192+
],
193+
]),
194+
].map(
195+
([path, records]) =>
196+
[
197+
path,
198+
{
199+
provider: "claude" as const,
200+
size: 100,
201+
mtimeMs: 100,
202+
records,
203+
tailRecords: [],
204+
malformedRecords: 0,
205+
position: { resumeOffset: 100, guardLength: 0, guardHash: 0, state: null },
206+
},
207+
] as const,
208+
),
209+
);
210+
const cache = decodeScanCache(
211+
JSON.parse([...makeScanCacheWriter()(original, {})].join("")),
212+
TEST_FORMAT_MAP,
213+
);
214+
const copies = [...cache.values()];
215+
if (reverse) copies.reverse();
216+
for (const model of [undefined, attempt.model, fallback.model]) {
217+
const aggregator = new UsageAggregator({
218+
timeZone: "UTC",
219+
sinceDay: "2026-08-01",
220+
untilDay: "2026-08-31",
221+
rates,
222+
...(model === undefined ? {} : { modelFilter: { include: [{ model }] } }),
223+
});
224+
for (const file of copies) for (const record of file.records) aggregator.add(record);
225+
const buckets = aggregator.finish().buckets;
226+
const expected =
227+
model === undefined
228+
? [attempt, fallback]
229+
: [model === attempt.model ? attempt : fallback];
230+
expect(
231+
buckets.map((bucket) => [
232+
bucket.model,
233+
bucket.totals.cacheCreationTokens,
234+
bucket.totals.outputTokens,
235+
bucket.records,
236+
]),
237+
).toEqual(
238+
expected
239+
.toSorted((a, b) => a.model.localeCompare(b.model))
240+
.map((entry) => [
241+
entry.model,
242+
entry.cache_creation_input_tokens,
243+
entry.output_tokens,
244+
1,
245+
]),
246+
);
247+
}
248+
},
249+
);
250+
152251
it("buckets by the day in the requested time zone", () => {
153252
const utc = aggregate([record()], "UTC");
154253
const losAngeles = aggregate([record()], "America/Los_Angeles");

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@ interface Contribution {
173173
export class UsageAggregator {
174174
readonly #buckets = new Map<string, MutableBucket>();
175175
readonly #seen = new Map<string, Contribution>();
176+
readonly #supersededKeys = new Set<string>();
176177
readonly #toDay: (timestampMs: number) => string;
177178
readonly #hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null;
178179
readonly #options: AggregateOptions;
@@ -204,6 +205,15 @@ export class UsageAggregator {
204205
}
205206

206207
add(input: UsageRecord, sourcePath?: string): boolean {
208+
// A completed fallback replaces provisional snapshots even when its serving model is filtered out.
209+
if (input.supersedesDedupeKey !== undefined) {
210+
this.#supersededKeys.add(input.supersedesDedupeKey);
211+
if (this.#seen.delete(input.supersedesDedupeKey)) this.#duplicatesDropped += 1;
212+
}
213+
if (input.dedupeKey !== null && this.#supersededKeys.has(input.dedupeKey)) {
214+
this.#duplicatesDropped += 1;
215+
return false;
216+
}
207217
if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
208218
const record = this.#mapModel(input);
209219
if (record.dedupeKey !== null) {
@@ -344,8 +354,10 @@ export class UsageAggregator {
344354
if (bucket !== null) this.#accumulate(bucket, record);
345355
}
346356
this.#seen.clear();
357+
this.#supersededKeys.clear();
347358
const buckets: UsageBucket[] = [];
348359
for (const [key, bucket] of this.#buckets) {
360+
if (bucket.records === 0) continue;
349361
const [day = "", hourStart = "", provider = "", model = "", sourcePath = ""] =
350362
key.split("\u0000");
351363
const category = bucket.categoryCostUsd;

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

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -244,17 +244,20 @@ describe("scan cache round trip", () => {
244244
},
245245
);
246246

247-
it.each([11, 12])("re-parses v%s Claude transcripts for corrected attempt usage", (version) => {
248-
const original = cacheWith([["/claude.jsonl", 100, [record()]]]);
249-
const legacy = { ...parse(makeScanCacheWriter()(original, {})), version };
247+
it.each([11, 12, 13])(
248+
"re-parses v%s Claude transcripts for corrected attempt usage",
249+
(version) => {
250+
const original = cacheWith([["/claude.jsonl", 100, [record()]]]);
251+
const legacy = { ...parse(makeScanCacheWriter()(original, {})), version };
250252

251-
const restored = decodeScanCache(JSON.parse(JSON.stringify(legacy)), TEST_FORMAT_MAP);
252-
expect(restored.get("/claude.jsonl")).toEqual({
253-
...original.get("/claude.jsonl"),
254-
size: -1,
255-
position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
256-
});
257-
});
253+
const restored = decodeScanCache(JSON.parse(JSON.stringify(legacy)), TEST_FORMAT_MAP);
254+
expect(restored.get("/claude.jsonl")).toEqual({
255+
...original.get("/claude.jsonl"),
256+
size: -1,
257+
position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
258+
});
259+
},
260+
);
258261

259262
it("rewrites only changed entries and still restores the whole cache", () => {
260263
const write = makeScanCacheWriter();

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

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,17 @@ import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
1010
import { mergeUsageCopies } from "./usageAggregation.ts";
1111
import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
1212

13-
const USAGE_SCAN_CACHE_VERSION = 13 as const;
13+
const USAGE_SCAN_CACHE_VERSION = 14 as const;
1414
const SPEED_COMPATIBLE_SINCE_VERSION = 4;
1515

1616
/**
1717
* An older server sharing that directory cannot read a newer cache and would
1818
* replace it, dropping saved usage for deleted transcripts. Separate files keep
1919
* the newer one; older files are removed once it is saved.
2020
*/
21-
export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v13.json";
21+
export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v14.json";
2222
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23+
"usage-scan-cache-v13.json",
2324
"usage-scan-cache-v12.json",
2425
"usage-scan-cache-v11.json",
2526
"usage-scan-cache-v10.json",
@@ -60,7 +61,8 @@ type SerializedRecord = readonly [
6061
reportedCostUsd: number | null,
6162
speed: number,
6263
rateModelIndex?: number | null,
63-
unresolvedServiceTierTurnId?: string,
64+
unresolvedServiceTierTurnId?: string | null,
65+
supersedesDedupeKey?: string,
6466
];
6567

6668
interface SerializedFile {
@@ -119,9 +121,11 @@ function serializeFile(entry: CachedFile, tables: InternTables): SerializedFile
119121
record.rateModel === undefined
120122
? null
121123
: intern(tables.models, tables.modelIndex, record.rateModel),
122-
...(record.unresolvedServiceTierTurnId === undefined
123-
? ([] as const)
124-
: ([record.unresolvedServiceTierTurnId] as const)),
124+
...(record.supersedesDedupeKey !== undefined
125+
? ([record.unresolvedServiceTierTurnId ?? null, record.supersedesDedupeKey] as const)
126+
: record.unresolvedServiceTierTurnId === undefined
127+
? ([] as const)
128+
: ([record.unresolvedServiceTierTurnId] as const)),
125129
];
126130
return {
127131
s: entry.size,
@@ -212,6 +216,7 @@ export function decodeScanCache(
212216
speedIndex,
213217
rateModelIndex,
214218
unresolvedServiceTierTurnId,
219+
supersedesDedupeKey,
215220
] = row as SerializedRecord;
216221
const speed = typeof speedIndex === "number" ? SPEEDS[speedIndex] : undefined;
217222

@@ -221,8 +226,8 @@ export function decodeScanCache(
221226
typeof timestampMs !== "number" ||
222227
!Number.isFinite(timestampMs) ||
223228
model === undefined ||
224-
(unresolvedServiceTierTurnId !== undefined &&
225-
typeof unresolvedServiceTierTurnId !== "string") ||
229+
(unresolvedServiceTierTurnId != null && typeof unresolvedServiceTierTurnId !== "string") ||
230+
(supersedesDedupeKey !== undefined && typeof supersedesDedupeKey !== "string") ||
226231
(rateModelIndex != null && rateModel === undefined) ||
227232
!Number.isFinite(uncached) ||
228233
!Number.isFinite(cached) ||
@@ -253,9 +258,10 @@ export function decodeScanCache(
253258
},
254259
reportedCostUsd: typeof reportedCostUsd === "number" ? reportedCostUsd : null,
255260
speed,
256-
...(version >= 7 && unresolvedServiceTierTurnId !== undefined
261+
...(version >= 7 && unresolvedServiceTierTurnId != null
257262
? { unresolvedServiceTierTurnId }
258263
: {}),
264+
...(supersedesDedupeKey === undefined ? {} : { supersedesDedupeKey }),
259265
dedupeKey: typeof dedupeKey === "string" ? dedupeKey : null,
260266
});
261267
}
@@ -292,9 +298,9 @@ export function decodeScanCache(
292298
}
293299
// Keep history for deleted rollouts, but re-parse incompatible reducer state.
294300
// v9 and v11 repair skipped Codex requests; clean v8+ entries stay served while unchanged.
295-
// Claude history before v13 lacks per-attempt fallback usage.
301+
// Claude history before v14 lacks authoritative fallback replacement keys.
296302
const legacy =
297-
(entry.p === "claude" && version < 13) ||
303+
(entry.p === "claude" && version < 14) ||
298304
(format.state !== undefined &&
299305
(version < 6 ||
300306
(entry.p === "codex" && (version < 8 || (version < 11 && malformedRecords > 0)))));

‎packages/provider-core/src/server/usage.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ export interface UsageRecord {
2222
readonly speed: UsageSpeed;
2323
readonly unresolvedServiceTierTurnId?: string;
2424
readonly dedupeKey: string | null;
25+
/** An authoritative attempt replaces this provisional message, including cached copies. */
26+
readonly supersedesDedupeKey?: string;
2527
}
2628

2729
export const EMPTY_TOTALS: UsageTokenTotals = {

0 commit comments

Comments
 (0)