The best way to control Claude Code, Codex and more from any computer or phone
fix(server): Cursor history on large accounts loads in pieces and keeps what was read (#38567)
Julius Marminge committed
Nov 18, 2026 at 03:46 UTC
52f0f8afb8cde93389479b6bd8dd8d44a17946dd
4 files changed
+171
-58
apps/server/src/usage/UsageService.test.ts
+73
-1
@@ -1967,7 +1967,7 @@ describe("UsageService", () => {
1967
const sources = yield* Fiber.join(wider);
1968
assert.deepStrictEqual(cursor.state.calls, [
1969
{ sinceMs: input.retentionCutoffMs, untilMs: CURSOR_NOW },
1970
- { sinceMs: 0, untilMs: CURSOR_NOW },
1970
+ { sinceMs: 0, untilMs: input.retentionCutoffMs },
1971
]);
1972
assert.strictEqual(sources[0]?.status, "ok");
1973
assert.deepStrictEqual(
@@ -2077,6 +2077,78 @@ describe("UsageService", () => {
2077
}),
2078
);
2079
2080
+ it.effect("loads Cursor history that cannot be read in one request within the deadline", () =>
2081
+ Effect.gen(function* () {
2082
+ const { settings, home } = yield* setup;
2083
+ yield* TestClock.setTime(CURSOR_NOW);
2084
+ const cursor = makeFakeCursor();
2085
+ cursor.state.events = [
2086
+ { timestampMs: CURSOR_NOW - 40 * HOUR_MS, outputTokens: 7 },
2087
+ { timestampMs: CURSOR_NOW - 3 * HOUR_MS, outputTokens: 5 },
2088
+ ];
2089
+ // A large account: a window wider than half a day has too many pages for the read deadlines.
2090
+ const read: CursorAccountReader.CursorAccountReader["Service"]["read"] = (
2091
+ credential,
2092
+ sinceMs,
2093
+ untilMs,
2094
+ ) =>
2095
+ untilMs - sinceMs > 12 * HOUR_MS
2096
+ ? Effect.succeed({
2097
+ accountKey: cursor.state.accountKey,
2098
+ records: [],
2099
+ missing: false,
2100
+ error: "Cursor account usage could not be read.",
2101
+ })
2102
+ : cursor.read(credential, sinceMs, untilMs);
2103
+ yield* Effect.gen(function* () {
2104
+ const service = yield* makeWithCursor(read);
2105
+ let summary = yield* service.readSummary({ ...WINDOW, awaitRefresh: true });
2106
+ for (let attempt = 1; attempt < 10 && totalOutputTokens(summary) < 12; attempt++) {
2107
+ yield* TestClock.adjust("2 minutes");
2108
+ summary = yield* service.readSummary({ ...WINDOW, awaitRefresh: true });
2109
+ }
2110
+ assert.strictEqual(totalOutputTokens(summary), 12);
2111
+
2112
+ // Failed reads during an outage narrow the span; it widens back once reads work again.
2113
+ cursor.state.error = "Cursor account usage could not be read.";
2114
+ for (let attempt = 0; attempt < 20; attempt++) {
2115
+ yield* TestClock.adjust("2 minutes");
2116
+ yield* service.readSummary({ ...WINDOW, awaitRefresh: true });
2117
+ }
2118
+ cursor.state.error = null;
2119
+ yield* TestClock.adjust("10 hours");
2120
+ cursor.state.events.push({ timestampMs: CURSOR_NOW + 10 * HOUR_MS, outputTokens: 3 });
2121
+ const callsBeforeRecovery = cursor.state.calls.length;
2122
+ summary = yield* service.readSummary({ ...WINDOW, awaitRefresh: true });
2123
+ assert.strictEqual(totalOutputTokens(summary), 15);
2124
+ assert.isBelow(cursor.state.calls.length - callsBeforeRecovery, 20);
2125
+ }).pipe(
2126
+ Effect.provide(
2127
+ layerService({
2128
+ prefix: "usage-service-cursor-large-account",
2129
+ home,
2130
+ settings,
2131
+ platform: "darwin",
2132
+ environment: {},
2133
+ secretStore: {
2134
+ get: () =>
2135
+ Effect.succeedSome(
2136
+ new TextEncoder().encode(
2137
+ encodeUnknownJsonString({
2138
+ version: 1,
2139
+ backendUrl: "https://api2.cursor.sh",
2140
+ apiKey: "large-account-key",
2141
+ createdAtMs: 0,
2142
+ }),
2143
+ ),
2144
+ ),
2145
+ },
2146
+ }),
2147
+ ),
2148
+ );
2149
+ }),
2150
+ );
2151
+
2152
it.effect("keeps a new Cursor key's refresh visible beside a failing key", () =>
2153
Effect.gen(function* () {
2154
const { settings, home } = yield* setup;
packages/provider-cursor/src/server/CursorUsageAccounts.ts
+59
-37
@@ -18,6 +18,7 @@ import * as Semaphore from "effect/Semaphore";
18
import {
19
CURSOR_ACCOUNT_CACHE_FILE_NAME,
20
CURSOR_ACCOUNT_TTL_MS,
21
+ CURSOR_MIN_FETCH_SPAN_MS,
22
cursorFetchRange,
23
decodeCursorAccountCaches,
24
encodeCursorAccountCaches,
@@ -64,6 +65,8 @@ const make = Effect.gen(function* () {
65
/** Failed refreshes share the cache TTL to prevent repeated requests; null means no login. */
66
const failures = new Map<string, { readonly atMs: number; readonly error: string | null }>();
67
const refreshes = new Map<string, Deferred.Deferred<void>>();
68
+ /** Widest range the next read asks for, narrowed after failures until the cache is complete. */
69
+ const fetchSpans = new Map<string, number>();
70
71
const ensureLoaded = yield* Effect.cached(
72
fileSystem.readFileString(cachePath).pipe(
@@ -111,45 +114,64 @@ const make = Effect.gen(function* () {
114
retentionStartMs: number,
115
) {
116
const nowMs = yield* Clock.currentTimeMillis;
114
- const fetchMissing = (cache: CursorAccountCache | undefined) => {
115
- const range = cursorFetchRange(cache, retentionStartMs, nowMs);
116
- return accountReader
117
- .read(credential, range.sinceMs, range.untilMs)
118
- .pipe(Effect.map((result) => ({ range, result })));
119
- };
120
- let base = caches.get(credentialKey);
121
- let fetched = yield* fetchMissing(base);
122
- if (
123
- base !== undefined &&
124
- fetched.result.accountKey !== null &&
125
- fetched.result.accountKey !== base.accountKey
126
- ) {
127
- caches.delete(credentialKey);
128
- cacheDirty = true;
129
- base = undefined;
130
- fetched = yield* fetchMissing(base);
131
- }
132
- const { range, result } = fetched;
133
- if (result.missing || result.error !== null || result.accountKey === null) {
134
- failures.set(credentialKey, {
135
- atMs: nowMs,
136
- error: result.missing || result.error !== null ? result.error : CURSOR_ACCOUNT_READ_ERROR,
137
- });
117
+ let checkedAccount = false;
118
+ let span = fetchSpans.get(credentialKey) ?? Number.POSITIVE_INFINITY;
119
+ // Widen after each success so a span narrowed by earlier failures recovers in a few reads.
120
+ let widening = true;
121
+ let widened = false;
122
+ for (;;) {
123
+ const base = caches.get(credentialKey);
124
+ const range = cursorFetchRange(base, retentionStartMs, nowMs, span);
125
+ const result = yield* accountReader.read(credential, range.sinceMs, range.untilMs);
126
+ if (
127
+ !checkedAccount &&
128
+ base !== undefined &&
129
+ result.accountKey !== null &&
130
+ result.accountKey !== base.accountKey
131
+ ) {
132
+ caches.delete(credentialKey);
133
+ cacheDirty = true;
134
+ checkedAccount = true;
135
+ continue;
136
+ }
137
+ checkedAccount = true;
138
+ if (result.missing || result.error !== null || result.accountKey === null) {
139
+ // A large account's full history can outlast the read deadlines; try a narrower range.
140
+ span = Math.max(CURSOR_MIN_FETCH_SPAN_MS, (range.untilMs - range.sinceMs) / 2);
141
+ fetchSpans.set(credentialKey, span);
142
+ if (widened) {
143
+ // The span before widening just worked: keep going with it instead of failing.
144
+ widened = false;
145
+ widening = false;
146
+ continue;
147
+ }
148
+ failures.set(credentialKey, {
149
+ atMs: nowMs,
150
+ error: result.missing || result.error !== null ? result.error : CURSOR_ACCOUNT_READ_ERROR,
151
+ });
152
+ yield* schedulePersist;
153
+ return;
154
+ }
155
+ const merged = mergeCursorFetch(
156
+ base,
157
+ result.accountKey,
158
+ range,
159
+ result.records,
160
+ nowMs,
161
+ retentionStartMs,
162
+ );
163
+ caches.set(credentialKey, merged.cache);
164
+ failures.delete(credentialKey);
165
+ if (merged.changed) cacheDirty = true;
166
yield* schedulePersist;
139
- return;
167
+ if (merged.cache.sinceMs <= retentionStartMs && merged.cache.untilMs >= nowMs) break;
168
+ widened = widening && Number.isFinite(span);
169
+ if (widened) {
170
+ span *= 2;
171
+ fetchSpans.set(credentialKey, span);
172
+ }
173
}
141
- const merged = mergeCursorFetch(
142
- base,
143
- result.accountKey,
144
- range,
145
- result.records,
146
- nowMs,
147
- retentionStartMs,
148
- );
149
- caches.set(credentialKey, merged.cache);
150
- failures.delete(credentialKey);
151
- if (merged.changed) cacheDirty = true;
152
- yield* schedulePersist;
174
+ fetchSpans.delete(credentialKey);
175
}, refreshLock.withPermit);
176
177
const startRefresh = (
packages/provider-cursor/src/server/accountCache.test.ts
+2
-5
@@ -23,7 +23,7 @@ const record = (timestampMs: number): UsageRecord => ({
23
});
24
25
describe("cursorAccountCache", () => {
26
- it("refetches everything once the cache no longer reaches the retention start", () => {
26
+ it("reads only the history the cache is missing", () => {
27
const cache = {
28
accountKey: "a",
29
sinceMs: 0,
@@ -35,10 +35,7 @@ describe("cursorAccountCache", () => {
35
const narrow = { ...cache, sinceMs: DAY_MS };
36
assert.isFalse(isCursorCacheFresh(narrow, 10 * DAY_MS, 0));
37
const widenedRange = cursorFetchRange(narrow, 0, 10 * DAY_MS);
38
- assert.deepStrictEqual(widenedRange, {
39
- sinceMs: 0,
40
- untilMs: 10 * DAY_MS,
41
- });
38
+ assert.deepStrictEqual(widenedRange, { sinceMs: 0, untilMs: DAY_MS });
39
const widened = mergeCursorFetch(narrow, "a", widenedRange, cache.records, 10 * DAY_MS, 0);
40
assert.isTrue(isCursorCacheFresh(widened.cache, 10 * DAY_MS, 0));
41
assert.deepStrictEqual(cursorFetchRange(widened.cache, 0, 11 * DAY_MS), {
packages/provider-cursor/src/server/accountCache.ts
+37
-15
@@ -34,16 +34,31 @@ export function isCursorCacheFresh(
34
);
35
}
36
37
+/** Narrowest read a refresh falls back to after failed reads of wider ranges. */
38
+export const CURSOR_MIN_FETCH_SPAN_MS = 60 * 1000;
39
+
40
+/**
41
+ * The next range to read, at most `maxSpanMs` wide unless it only tops up a complete cache:
42
+ * the newest history first, then older history down to the retention start.
43
+ */
44
export function cursorFetchRange(
45
cache: CursorAccountCache | undefined,
46
retentionStartMs: number,
47
nowMs: number,
48
+ maxSpanMs = Number.POSITIVE_INFINITY,
49
): CursorFetchRange {
42
- return cache === undefined ||
43
- cache.sinceMs > retentionStartMs ||
44
- cache.untilMs - REFETCH_OVERLAP_MS < retentionStartMs
45
- ? { sinceMs: retentionStartMs, untilMs: nowMs }
46
- : { sinceMs: cache.untilMs - REFETCH_OVERLAP_MS, untilMs: nowMs };
50
+ if (cache === undefined || cache.untilMs - REFETCH_OVERLAP_MS < retentionStartMs) {
51
+ return { sinceMs: Math.max(retentionStartMs, nowMs - maxSpanMs), untilMs: nowMs };
52
+ }
53
+ if (cache.untilMs < nowMs || cache.sinceMs <= retentionStartMs) {
54
+ // Overlap at most half the span so a narrow read still moves forward.
55
+ const sinceMs = cache.untilMs - Math.min(REFETCH_OVERLAP_MS, maxSpanMs / 2);
56
+ return { sinceMs, untilMs: Math.min(nowMs, sinceMs + maxSpanMs) };
57
+ }
58
+ return {
59
+ sinceMs: Math.max(retentionStartMs, cache.sinceMs - maxSpanMs),
60
+ untilMs: cache.sinceMs,
61
+ };
62
}
63
64
export function mergeCursorFetch(
@@ -56,7 +71,12 @@ export function mergeCursorFetch(
71
) {
72
const inRange = (record: UsageRecord) =>
73
record.timestampMs >= range.sinceMs && record.timestampMs <= range.untilMs;
59
- const previous = cache?.records ?? [];
74
+ const base =
75
+ cache !== undefined && range.sinceMs <= cache.untilMs && range.untilMs >= cache.sinceMs
76
+ ? cache
77
+ : undefined;
78
+ const older = base !== undefined && range.untilMs <= base.sinceMs;
79
+ const previous = base?.records ?? [];
80
const added = fetched.filter(inRange);
81
const replacedKeys = new Set<string | null>();
82
let pruned = false;
@@ -65,22 +85,24 @@ export function mergeCursorFetch(
85
else if (record.timestampMs < retentionStartMs) pruned = true;
86
}
87
const changed =
68
- cache === undefined ||
69
- cache.sinceMs > retentionStartMs ||
88
+ base === undefined ||
89
+ base.sinceMs > retentionStartMs ||
90
pruned ||
91
replacedKeys.size !== added.length ||
92
added.some((record) => !replacedKeys.has(record.dedupeKey));
73
- const records = !changed
74
- ? previous
75
- : previous
76
- .filter((record) => !inRange(record) && record.timestampMs >= retentionStartMs)
77
- .concat(added);
93
+ let records = previous;
94
+ if (changed) {
95
+ const kept = previous.filter(
96
+ (record) => !inRange(record) && record.timestampMs >= retentionStartMs,
97
+ );
98
+ records = older ? added.concat(kept) : kept.concat(added);
99
+ }
100
return {
101
changed,
102
cache: {
103
accountKey,
82
- sinceMs: retentionStartMs,
83
- untilMs: range.untilMs,
104
+ sinceMs: Math.max(retentionStartMs, Math.min(base?.sinceMs ?? range.sinceMs, range.sinceMs)),
105
+ untilMs: older ? base.untilMs : range.untilMs,
106
fetchedAtMs: nowMs,
107
records,
108
} satisfies CursorAccountCache,