@devries-cameron20 / t3code-1 / commits / 53bcb9af7a
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

perf(cursor): improve account usage scanning (#33636)

Normalize Cursor usage pages as they arrive, retain bounded raw page data, and preserve count-proven boundary deduplication and stable event keys. Use direct hex hashing, limit concurrent account refreshes to two, reuse unchanged cached records, and persist retention pruning. Validation: check:changed passed with 61 focused tests; 40 differential reader cases matched the original output. CI and agentic reviews passed on the merged head. GPT 6.1 Sol via Codex in T3 Code.

Yash Singh committed Nov 9, 2026 at 19:10 UTC 53bcb9af7a37dd0b4df11a7d6fa0106e9e5b7356
6 files changed +133 -53
apps/server/src/usage/UsageService.test.ts
+30 -7
@@ -1580,6 +1580,8 @@ describe("UsageService", () => {
1580 Effect.gen(function* () {
1581 const { settings, home } = yield* setup;
1582 const cursor = makeFakeCursor();
1583 + let inFlight = 0;
1584 + let mostInFlight = 0;
1585 const started = yield* Deferred.make<void>();
1586 const gate = yield* Deferred.make<void>();
1587 yield* Effect.gen(function* () {
@@ -1587,17 +1589,28 @@ describe("UsageService", () => {
1589 layerCursorUsageAccounts(
1590 Layer.succeed(CursorAccountReader.CursorAccountReader, {
1591 read: (credential, sinceMs, untilMs) =>
1590 - (credential as { apiKey?: string }).apiKey === "failing-key"
1591 - ? Effect.succeed({
1592 + Effect.gen(function* () {
1593 + inFlight++;
1594 + mostInFlight = Math.max(mostInFlight, inFlight);
1595 + if (credential.apiKey === "failing-key") {
1596 + yield* Deferred.await(started);
1597 + return {
1598 accountKey: null,
1599 records: [],
1600 missing: false,
1601 error: "Cursor account usage could not be read.",
1596 - })
1597 - : Deferred.succeed(started, undefined).pipe(
1598 - Effect.andThen(Deferred.await(gate)),
1599 - Effect.andThen(cursor.read(credential, sinceMs, untilMs)),
1600 - ),
1602 + };
1603 + }
1604 + yield* Deferred.succeed(started, undefined);
1605 + yield* Deferred.await(gate);
1606 + return yield* cursor.read(credential, sinceMs, untilMs);
1607 + }).pipe(
1608 + Effect.ensuring(
1609 + Effect.sync(() => {
1610 + inFlight--;
1611 + }),
1612 + ),
1613 + ),
1614 }),
1615 ),
1616 );
@@ -1613,6 +1626,14 @@ describe("UsageService", () => {
1626 instanceId: ProviderInstanceId.make("cursor-work"),
1627 environment: { CURSOR_API_KEY: "new-key" },
1628 },
1629 + {
1630 + instanceId: ProviderInstanceId.make("cursor-third"),
1631 + environment: { CURSOR_API_KEY: "third-key" },
1632 + },
1633 + {
1634 + instanceId: ProviderInstanceId.make("cursor-fourth"),
1635 + environment: { CURSOR_API_KEY: "fourth-key" },
1636 + },
1637 ],
1638 windowStartMs: 0,
1639 retentionCutoffMs: 0,
@@ -1624,6 +1645,8 @@ describe("UsageService", () => {
1645 assert.isTrue(sources.some((source) => source.refreshing === true));
1646 yield* Deferred.succeed(gate, undefined);
1647 yield* Fiber.join(first);
1648 + assert.strictEqual(mostInFlight, 2);
1649 + assert.strictEqual(inFlight, 0);
1650 }).pipe(
1651 Effect.provide(
1652 layerService({
packages/provider-cursor/src/server/CursorUsageAccounts.ts
+3 -1
@@ -104,6 +104,7 @@ const make = Effect.gen(function* () {
104 );
105 yield* Effect.addFinalizer(() => awaitPersisted);
106
107 + const refreshLock = yield* Semaphore.make(2);
108 const refreshAccount = Effect.fn("CursorUsageAccounts.refreshAccount")(function* (
109 credential: CursorCredentialSource,
110 credentialKey: string,
@@ -149,7 +150,7 @@ const make = Effect.gen(function* () {
150 failures.delete(credentialKey);
151 if (merged.changed) cacheDirty = true;
152 yield* schedulePersist;
152 - });
153 + }, refreshLock.withPermit);
154
155 const startRefresh = (
156 credential: CursorCredentialSource,
@@ -256,6 +257,7 @@ const make = Effect.gen(function* () {
257 retentionCutoffMs,
258 awaitRefresh,
259 ),
260 + { concurrency: 2 },
261 );
262 // Keys for one account share its source, and a repeated source would count sessions twice.
263 // A failed key can hold older records, so a current read wins, then a refresh the client
packages/provider-cursor/src/server/accountCache.test.ts
+10
@@ -65,6 +65,16 @@ describe("cursorAccountCache", () => {
65 assert.isFalse(
66 mergeCursorFetch(cache, "a", range, [record(10 * DAY_MS)], 11 * DAY_MS, 0).changed,
67 );
68 + const pruned = mergeCursorFetch(
69 + cache,
70 + "a",
71 + range,
72 + [record(10 * DAY_MS)],
73 + 11 * DAY_MS,
74 + 2 * DAY_MS,
75 + );
76 + assert.isTrue(pruned.changed);
77 + assert.deepStrictEqual(pruned.cache.records, [record(10 * DAY_MS)]);
78 assert.isTrue(
79 mergeCursorFetch(
80 cache,
packages/provider-cursor/src/server/accountCache.ts
+13 -5
@@ -53,11 +53,22 @@ export function mergeCursorFetch(
53 record.timestampMs >= range.sinceMs && record.timestampMs <= range.untilMs;
54 const previous = cache?.records ?? [];
55 const added = fetched.filter(inRange);
56 - const replacedKeys = new Set(previous.filter(inRange).map((record) => record.dedupeKey));
56 + const replacedKeys = new Set<string | null>();
57 + let pruned = false;
58 + for (const record of previous) {
59 + if (inRange(record)) replacedKeys.add(record.dedupeKey);
60 + else if (record.timestampMs < retentionStartMs) pruned = true;
61 + }
62 const changed =
63 cache === undefined ||
64 + pruned ||
65 replacedKeys.size !== added.length ||
66 added.some((record) => !replacedKeys.has(record.dedupeKey));
67 + const records = !changed
68 + ? previous
69 + : previous
70 + .filter((record) => !inRange(record) && record.timestampMs >= retentionStartMs)
71 + .concat(added);
72 return {
73 changed,
74 cache: {
@@ -65,10 +76,7 @@ export function mergeCursorFetch(
76 sinceMs: retentionStartMs,
77 untilMs: range.untilMs,
78 fetchedAtMs: nowMs,
68 - records: [
69 - ...previous.filter((record) => !inRange(record) && record.timestampMs >= retentionStartMs),
70 - ...added,
71 - ],
79 + records,
80 } satisfies CursorAccountCache,
81 };
82 }
packages/provider-cursor/src/server/accountUsage.test.ts
+23 -4
@@ -115,6 +115,10 @@ describe("Cursor account history", () => {
115 reasoningTokens: 0,
116 });
117 assert.strictEqual(result.records[0]?.reportedCostUsd, 0.25);
118 + assert.strictEqual(
119 + result.records[0]?.dedupeKey,
120 + "cursor-account:2188c26da759c4fae3aa0252fc6d725eff0922ef0b022551e6f0987d02bfab33:3149aaf8419ad6b66ef7330853d8fe85e6f2e9876e2ad5e85f88bee8c8d6d133:0",
121 + );
122 assert.isFalse(result.accountKey?.includes("demo") ?? true);
123 }).pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
124 );
@@ -209,7 +213,8 @@ describe("Cursor account history", () => {
213 model: "gpt-5",
214 tokenUsage: { inputTokens: 10, outputTokens: 5, totalCents: 1 },
215 });
212 - for (const total of [2000, 2001]) {
216 + for (const total of [2000, 2001, undefined]) {
217 + const expectedCount = total ?? 2001;
218 let requests = 0;
219 const result = yield* readAccountUsage(credential, 0, 1781000000000, async () => {
220 requests++;
@@ -219,19 +224,33 @@ describe("Cursor account history", () => {
224 requests === 1
225 ? Array.from({ length: 1000 }, (_, index) => event(index))
226 : requests === 2
222 - ? Array.from({ length: 1000 }, (_, index) => event(999 + index))
227 + ? Array.from({ length: 1000 }, (_, index) => {
228 + const row = event(999 + index);
229 + return {
230 + tokenUsage: {
231 + totalCents: row.tokenUsage.totalCents,
232 + outputTokens: row.tokenUsage.outputTokens,
233 + inputTokens: row.tokenUsage.inputTokens,
234 + },
235 + model: row.model,
236 + timestamp: row.timestamp,
237 + };
238 + })
239 : [event(1999)],
240 });
241 });
242 assert.isNull(result.error);
227 - assert.strictEqual(result.records.length, total);
243 + assert.strictEqual(result.records.length, expectedCount);
244 assert.strictEqual(requests, 3);
245 assert.strictEqual(result.records.at(-1)?.timestampMs, 1780000001999);
246 assert.strictEqual(
247 result.records.filter((record) => record.timestampMs === 1780000000999).length,
248 total === 2000 ? 1 : 2,
249 );
234 - assert.strictEqual(new Set(result.records.map((record) => record.dedupeKey)).size, total);
250 + assert.strictEqual(
251 + new Set(result.records.map((record) => record.dedupeKey)).size,
252 + expectedCount,
253 + );
254 }
255 let requests = 0;
256 const inconsistent = yield* readAccountUsage(credential, 0, 1781000000000, async () => {
packages/provider-cursor/src/server/accountUsage.ts
+54 -36
@@ -3,7 +3,6 @@ import * as Digest from "effect/crypto/Digest";
3 import * as Duration from "effect/Duration";
4 import * as Effect from "effect/Effect";
5 import * as Base64Url from "effect/encoding/Base64Url";
6 -import * as Hex from "effect/encoding/Hex";
6 import * as Fiber from "effect/Fiber";
7 import * as FetchHttpClient from "effect/http/FetchHttpClient";
8 import * as HttpClient from "effect/http/HttpClient";
@@ -55,12 +54,6 @@ const billedEventIdentity = (...fields: readonly unknown[]) => JSON.stringify(fi
54
55 const textEncoder = new TextEncoder();
56
58 -// Untraced: each usage scan hashes every billed event.
59 -const accountHash = Effect.fnUntraced(function* (value: string) {
60 - const digest = yield* Digest.Digest;
61 - return Hex.encode(yield* digest.digest(Digest.sha256, textEncoder.encode(value)));
62 -});
63 -
57 function canonicalJson(value: unknown): string {
58 if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
59 if (value !== null && typeof value === "object") {
@@ -93,6 +86,9 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
86 endDate: number,
87 ): Effect.fn.Return<CursorAccountUsageReadResult, never, Digest.Digest | HttpClient.HttpClient> {
88 const httpClient = yield* HttpClient.HttpClient;
89 + const digest = yield* Digest.Digest;
90 + // Per-event hashes share the scan span and use the native hex encoder.
91 + const accountHash = (value: string) => digest.digestHex(Digest.sha256, textEncoder.encode(value));
92 const credential = yield* Effect.result(exchangeCursorApiKey(credentialSource.apiKey));
93 if (Result.isFailure(credential)) {
94 return {
@@ -124,8 +120,9 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
120 );
121 const records: UsageRecord[] = [];
122 const occurrences = new Map<string, number>();
127 - const pages: unknown[][] = [];
128 - let completed = false;
123 + const normalized: Array<(Omit<UsageRecord, "dedupeKey"> & { dedupeKey: string }) | null> = [];
124 + const pages: Array<{ start: number; end: number; overlap: number }> = [];
125 + let previousEvents: unknown[] = [];
126 const pageSize = 1000;
127 let total: number | undefined;
128 const readPage = Effect.fn("CursorAccountUsage.readPage")(
@@ -210,30 +207,23 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
207 const next = ahead.shift();
208 const events = yield* next === undefined ? readPage(page) : Fiber.join(next);
209 if (!Array.isArray(events)) return events;
213 - pages.push(events);
214 - if (events.length < pageSize) {
215 - completed = true;
216 - break;
217 - }
218 - }
219 - if (!completed) return yield* invalid("Account usage page limit exceeded");
220 - const rawCount = pages.reduce((sum, page) => sum + page.length, 0);
221 - if (total !== undefined && rawCount < total)
222 - return yield* invalid("Incomplete account usage pages");
223 - let removalsRemaining = total === undefined ? 0 : rawCount - total;
224 - let previousKeys: string[] = [];
225 - for (const events of pages) {
226 - const eventKeys =
227 - removalsRemaining > 0
228 - ? yield* Effect.forEach(events, (event) => accountHash(canonicalJson(event)))
229 - : [];
230 - const removalCount = Math.min(removalsRemaining, boundaryOverlap(previousKeys, eventKeys));
231 - removalsRemaining -= removalCount;
232 - previousKeys = eventKeys;
233 - for (const raw of events.slice(removalCount)) {
210 + const start = normalized.length;
211 + const firstTimestamp = object(events[0]).timestamp;
212 + // Equal raw events must have equal timestamps; avoid canonicalizing disjoint pages.
213 + const mayOverlap =
214 + (typeof firstTimestamp !== "string" && typeof firstTimestamp !== "number") ||
215 + previousEvents.some((event) => object(event).timestamp === firstTimestamp);
216 + const overlap = mayOverlap
217 + ? boundaryOverlap(previousEvents.map(canonicalJson), events.map(canonicalJson))
218 + : 0;
219 + previousEvents = events;
220 + for (const raw of events) {
221 const event = object(raw);
222 const usage = object(event.tokenUsage);
236 - if (event.tokenUsage === undefined || event.tokenUsage === null) continue;
223 + if (event.tokenUsage === undefined || event.tokenUsage === null) {
224 + normalized.push(null);
225 + continue;
226 + }
227 for (const key of [
228 "inputTokens",
229 "outputTokens",
@@ -260,7 +250,10 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
250 !event.model
251 )
252 return yield* invalid("Invalid account usage event");
263 - if (timestampMs < sinceMs || timestampMs > endDate) continue;
253 + if (timestampMs < sinceMs || timestampMs > endDate) {
254 + normalized.push(null);
255 + continue;
256 + }
257 const totals = {
258 uncachedInputTokens: tokens(usage.inputTokens),
259 cachedInputTokens: tokens(usage.cacheReadTokens),
@@ -275,9 +268,7 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
268 const key = yield* accountHash(
269 billedEventIdentity(timestampMs, event.model, sessionId, totals, reportedCostUsd),
270 );
278 - const occurrence = occurrences.get(key) ?? 0;
279 - occurrences.set(key, occurrence + 1);
280 - records.push({
271 + normalized.push({
272 provider: "cursor",
273 timestampMs,
274 model: event.model,
@@ -286,12 +277,39 @@ export const readCursorAccountUsage = Effect.fn("readCursorAccountUsage")(functi
277 totals,
278 reportedCostUsd,
279 speed: "standard",
289 - dedupeKey: `cursor-account:${accountKey}:${key}:${occurrence}`,
280 + dedupeKey: key,
281 });
282 }
283 + pages.push({ start, end: normalized.length, overlap });
284 + if (events.length < pageSize) break;
285 + yield* Effect.yieldNow;
286 + }
287 + const rawCount = normalized.length;
288 + if (total !== undefined && rawCount < total)
289 + return yield* invalid("Incomplete account usage pages");
290 + let removalsRemaining = total === undefined ? 0 : rawCount - total;
291 + // The final count proves which boundary copies to remove, including non-token events.
292 + for (const page of pages) {
293 + const removalCount = Math.min(removalsRemaining, page.overlap);
294 + removalsRemaining -= removalCount;
295 + for (let index = page.start; index < page.end; index++) {
296 + const record = normalized[index];
297 + normalized[index] = null;
298 + if (index < page.start + removalCount || record == null) continue;
299 + const key = record.dedupeKey;
300 + const occurrence = occurrences.get(key) ?? 0;
301 + occurrences.set(key, occurrence + 1);
302 + record.dedupeKey = `cursor-account:${accountKey}:${key}:${occurrence}`;
303 + records.push(record);
304 + }
305 yield* Effect.yieldNow;
306 }
307 if (removalsRemaining !== 0) return yield* invalid("Inconsistent account usage boundaries");
308 + yield* Effect.annotateCurrentSpan({
309 + "cursor.usage.pages": pages.length,
310 + "cursor.usage.events": rawCount,
311 + "cursor.usage.records": records.length,
312 + });
313 return {
314 accountKey,
315 records,