Skip to content

Commit bded3b6

Browse files
committed
fix(usage): date a cached usage API percent by when the API sent it
When the payload carries no 5-hour percent, the forecast history took the usage API's as seen at the render. fetchUsageData serves its cache, though: up to three minutes old normally, and during a rate limit or an API failure, whatever the cache holds, which can be hours old. Each render then moved that old reading's last sighting to now. The history showed the percent unchanged until fetching recovered, which flattened the forecast meanwhile, and the climb since then looked like it happened in the last few minutes, which exaggerated the pace afterwards. fetchUsageData now keeps when the API sent the values it returns: now for a fresh answer, the cache file's write time for a cached one. getUsageFetchedAtMs exposes it, and the history dates an API percent by it, as it already dates a payload percent by the transcript's last response. The stretch since then stays a gap that a later change is spread across. A new percent is now also dated by when it was seen rather than when it is first written, from either source: a profile can find another profile's fetch in the shared usage cache, say. It is never dated before the last reading's last sighting.
1 parent 8c2f370 commit bded3b6

5 files changed

Lines changed: 179 additions & 37 deletions

File tree

‎src/utils/__tests__/session-usage-history.test.ts‎

Lines changed: 38 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
recordSessionUsageReading,
1717
type SessionUsageHistoryDeps
1818
} from '../session-usage-history';
19+
import { getUsageFetchedAtMs } from '../usage';
1920

2021
const CACHE_PATH = '/cache/ccstatusline/session-usage-history.json';
2122
const MINUTE = 60 * 1000;
@@ -135,6 +136,37 @@ describe('recordSessionUsageReading', () => {
135136
expect(recordSessionUsageReading('/p', RESET_AT, 20, deps)).toEqual([[NOW - 50 * MINUTE, NOW - 40 * MINUTE, 20]]);
136137
});
137138

139+
// A cached usage API percent was fetched before now, maybe long before
140+
it('dates a new percent by when it was seen', () => {
141+
const deps = makeDeps(history({ '/p': [{ resetAt: RESET_AT, readings: [[NOW - 50 * MINUTE, NOW - 45 * MINUTE, 20]] }] }));
142+
deps.percentSeenAt = () => NOW - 3 * MINUTE;
143+
144+
expect(recordSessionUsageReading('/p', RESET_AT, 25, deps)).toEqual([
145+
[NOW - 50 * MINUTE, NOW - 45 * MINUTE, 20],
146+
[NOW - 3 * MINUTE, NOW - 3 * MINUTE, 25]
147+
]);
148+
});
149+
150+
it('dates a new percent no earlier than the last one was seen', () => {
151+
const deps = makeDeps(history({ '/p': [{ resetAt: RESET_AT, readings: [[NOW - 50 * MINUTE, NOW - 2 * MINUTE, 20]] }] }));
152+
deps.percentSeenAt = () => NOW - 3 * MINUTE;
153+
154+
expect(recordSessionUsageReading('/p', RESET_AT, 25, deps)).toEqual([
155+
[NOW - 50 * MINUTE, NOW - 2 * MINUTE, 20],
156+
[NOW - 2 * MINUTE, NOW - 2 * MINUTE, 25]
157+
]);
158+
});
159+
160+
it('dates a new percent now when nothing shows when it was seen', () => {
161+
const deps = makeDeps(history({ '/p': [{ resetAt: RESET_AT, readings: [[NOW - 50 * MINUTE, NOW - 45 * MINUTE, 20]] }] }));
162+
deps.percentSeenAt = () => undefined;
163+
164+
expect(recordSessionUsageReading('/p', RESET_AT, 25, deps)).toEqual([
165+
[NOW - 50 * MINUTE, NOW - 45 * MINUTE, 20],
166+
[NOW, NOW, 25]
167+
]);
168+
});
169+
138170
it('skips the write when an idle session\'s percent has been seen up to its last response', () => {
139171
const deps = makeDeps(history({ '/p': [{ resetAt: RESET_AT, readings: [[NOW - 50 * MINUTE, NOW - 40 * MINUTE, 20]] }] }));
140172
deps.percentSeenAt = () => NOW - 40 * MINUTE;
@@ -443,13 +475,14 @@ describe('getDefaultSessionUsageHistoryDeps', () => {
443475
expect(getDefaultSessionUsageHistoryDeps(payload(transcriptPath)).percentSeenAt?.()).toBe(NOW - 40 * MINUTE);
444476
});
445477

446-
// Without a five-hour percent in the payload, it comes from the usage API
447-
it('takes a percent the payload doesn\'t carry as seen now', () => {
478+
// Without a five-hour percent in the payload, it comes from the usage API,
479+
// maybe from its cache
480+
it('dates a percent the payload doesn\'t carry by when the usage API sent it', () => {
448481
fs.writeFileSync(transcriptPath, `${transcriptEntry('assistant', NOW - 40 * MINUTE, { message: { model: 'claude-opus-4-1' } })}\n`);
449482

450-
expect(getDefaultSessionUsageHistoryDeps(payload(transcriptPath, { seven_day: { used_percentage: 20 } })).percentSeenAt).toBeUndefined();
451-
expect(getDefaultSessionUsageHistoryDeps(payload(transcriptPath, null)).percentSeenAt).toBeUndefined();
452-
expect(getDefaultSessionUsageHistoryDeps().percentSeenAt).toBeUndefined();
483+
expect(getDefaultSessionUsageHistoryDeps(payload(transcriptPath, { seven_day: { used_percentage: 20 } })).percentSeenAt).toBe(getUsageFetchedAtMs);
484+
expect(getDefaultSessionUsageHistoryDeps(payload(transcriptPath, null)).percentSeenAt).toBe(getUsageFetchedAtMs);
485+
expect(getDefaultSessionUsageHistoryDeps().percentSeenAt).toBe(getUsageFetchedAtMs);
453486
});
454487

455488
// The payload's percent is still from a response: one before this

‎src/utils/__tests__/usage-fetch.test.ts‎

Lines changed: 80 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ interface UsageProbeResult {
3737
requestHost: string | null;
3838
homedir: string;
3939
lockContents: string | null;
40+
fetchedAtMs: number | null;
4041
}
4142

4243
interface TokenHome {
@@ -155,7 +156,7 @@ https.request = (...args) => {
155156
return request;
156157
};
157158
158-
const { fetchUsageData } = await import(${JSON.stringify(usageModulePath)});
159+
const { fetchUsageData, getUsageFetchedAtMs } = await import(${JSON.stringify(usageModulePath)});
159160
160161
const lockFile = path.join(os.homedir(), '.cache', 'ccstatusline', 'usage.lock');
161162
const cacheFile = path.join(os.homedir(), '.cache', 'ccstatusline', 'usage.json');
@@ -174,7 +175,8 @@ process.stdout.write(JSON.stringify({
174175
proxyAgentConfigured,
175176
requestHost,
176177
homedir: os.homedir(),
177-
lockContents: fs.existsSync(lockFile) ? fs.readFileSync(lockFile, 'utf8') : null
178+
lockContents: fs.existsSync(lockFile) ? fs.readFileSync(lockFile, 'utf8') : null,
179+
fetchedAtMs: getUsageFetchedAtMs() ?? null
178180
}));
179181
`;
180182

@@ -1489,6 +1491,82 @@ describe('fetchUsageData error handling', () => {
14891491
}
14901492
});
14911493

1494+
it('dates a fetched answer by when it came, and an error by nothing', () => {
1495+
const harness = createProbeHarness();
1496+
1497+
try {
1498+
const successHome = harness.createTokenHome('fetched-at-success');
1499+
const errorHome = harness.createTokenHome('fetched-at-error');
1500+
1501+
const success = harness.runProbe({
1502+
claudeConfigDir: successHome.claudeConfig,
1503+
home: successHome.home,
1504+
mode: 'success',
1505+
nowMs,
1506+
pathDir: successHome.bin,
1507+
responseBody: successResponseBody
1508+
});
1509+
const error = harness.runProbe({
1510+
claudeConfigDir: errorHome.claudeConfig,
1511+
home: errorHome.home,
1512+
mode: 'error',
1513+
nowMs,
1514+
pathDir: errorHome.bin
1515+
});
1516+
1517+
expect(success.requestCount).toBe(1);
1518+
expect(success.fetchedAtMs).toBe(nowMs);
1519+
expect(error.first).toEqual({ error: 'api-error' });
1520+
expect(error.fetchedAtMs).toBeNull();
1521+
} finally {
1522+
harness.cleanup();
1523+
}
1524+
});
1525+
1526+
// The forecast history goes by when a percent was seen, and a cached one
1527+
// isn't current: through a rate limit it can be hours old.
1528+
it('dates cached usage by when the cache was written, fresh or served through a rate limit', () => {
1529+
const harness = createProbeHarness();
1530+
1531+
try {
1532+
const freshHome = harness.createTokenHome('fetched-at-fresh-cache');
1533+
const staleHome = harness.createTokenHome('fetched-at-stale-cache');
1534+
const matchingHash = createHash('sha256').update('test-token').digest('hex').slice(0, 16);
1535+
const fresh = seedUsageCache(freshHome.home, { sessionUsage: 5, tokenHash: matchingHash });
1536+
const stale = seedUsageCache(staleHome.home, { sessionUsage: 5, tokenHash: matchingHash });
1537+
const backedOffNowMs = stale.mtimeMs + 2 * 60 * 60 * 1000;
1538+
fs.writeFileSync(path.join(staleHome.home, '.cache', 'ccstatusline', 'usage.lock'), JSON.stringify({
1539+
blockedUntil: Math.floor(backedOffNowMs / 1000) + 3600,
1540+
error: 'rate-limited'
1541+
}));
1542+
1543+
const freshResult = harness.runProbe({
1544+
claudeConfigDir: freshHome.claudeConfig,
1545+
home: freshHome.home,
1546+
mode: 'unexpected',
1547+
nowMs: fresh.mtimeMs + 60000,
1548+
pathDir: freshHome.bin,
1549+
requiredFields: ['sessionUsage']
1550+
});
1551+
const staleResult = harness.runProbe({
1552+
claudeConfigDir: staleHome.claudeConfig,
1553+
home: staleHome.home,
1554+
mode: 'unexpected',
1555+
nowMs: backedOffNowMs,
1556+
pathDir: staleHome.bin,
1557+
requiredFields: ['sessionUsage']
1558+
});
1559+
1560+
expect(freshResult.first).toEqual({ sessionUsage: 5 });
1561+
expect(freshResult.fetchedAtMs).toBe(fresh.mtimeMs);
1562+
expect(staleResult.first).toEqual({ sessionUsage: 5 });
1563+
expect(staleResult.fetchedAtMs).toBe(stale.mtimeMs);
1564+
expect(freshResult.requestCount + staleResult.requestCount).toBe(0);
1565+
} finally {
1566+
harness.cleanup();
1567+
}
1568+
});
1569+
14921570
it('refetches when the refresh token changes (account switch)', () => {
14931571
const harness = createProbeHarness();
14941572

‎src/utils/session-usage-history.ts‎

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
LOOKBACK_MS,
1414
type SessionUsageReading
1515
} from './session-forecast';
16+
import { getUsageFetchedAtMs } from './usage';
1617

1718
const HISTORY_SCHEMA_VERSION = 1 as const;
1819
// One window's reset time jitters by under a second between sources (the API
@@ -48,11 +49,11 @@ export interface SessionUsageHistoryDeps {
4849
statSync: (path: string) => { mtimeMs: number };
4950
mkdirSync: (path: string) => void;
5051
now: () => number;
51-
// When the percent given was seen, for one that can be older than now: a
52+
// When the percent given was seen, which can be well before now: a
5253
// payload's is from its session's last API response, and Claude Code's
53-
// refresh interval re-renders an idle session with that same percent.
54-
// Undefined when nothing shows when that was. Left out, the percent is
55-
// current, as the usage API's is.
54+
// refresh interval re-renders an idle session with that same percent; the
55+
// usage API's can come from its cache. Undefined when nothing shows when
56+
// that was. Left out, the percent is current.
5657
percentSeenAt?: () => number | undefined;
5758
cachePath: string;
5859
}
@@ -93,7 +94,8 @@ function getLastResponseAtMs(transcriptPath: string | undefined): number | undef
9394

9495
// Built per call rather than at import, so the path follows HOME at render time.
9596
// The payload's 5-hour percent, which wins over the usage API's, dates from its
96-
// session's last response; the API's counts as seen now.
97+
// session's last response; the API's from when the API sent it, which for a
98+
// cached one can be hours ago.
9799
export function getDefaultSessionUsageHistoryDeps(payload?: StatusJSON): SessionUsageHistoryDeps {
98100
const isPayloadPercent = typeof payload?.rate_limits?.five_hour?.used_percentage === 'number';
99101
return {
@@ -105,7 +107,7 @@ export function getDefaultSessionUsageHistoryDeps(payload?: StatusJSON): Session
105107
statSync: (p: string) => fs.statSync(p),
106108
mkdirSync: (p: string) => { fs.mkdirSync(p, { recursive: true }); },
107109
now: () => Date.now(),
108-
percentSeenAt: isPayloadPercent ? () => getLastResponseAtMs(payload.transcript_path) : undefined,
110+
percentSeenAt: isPayloadPercent ? () => getLastResponseAtMs(payload.transcript_path) : getUsageFetchedAtMs,
109111
cachePath: path.join(os.homedir(), '.cache', 'ccstatusline', 'session-usage-history.json')
110112
};
111113
}
@@ -174,19 +176,25 @@ function pruneWindows(windows: SessionUsageWindow[], nowMs: number): SessionUsag
174176
});
175177
}
176178

177-
// An unchanged percent was seen again when it was observed, which can be well
178-
// before now: an idle session's refresh renders repeat its last response's.
179-
// The stretch since stays a gap, which the forecast spreads a change across
180-
// (usage on another device, say) rather than taking the percent as unchanged
181-
// until now. With no time for it (a new transcript after /clear has no
182-
// response yet), the reading's own last sighting stands.
183-
function getUnchangedSeenAtMs(deps: SessionUsageHistoryDeps, nowMs: number, lastSeenMs: number): number {
184-
if (!deps.percentSeenAt) {
185-
return nowMs;
186-
}
179+
// When the percent was observed, which can be well before now: an idle
180+
// session's refresh renders repeat its last response's, and a rate-limited
181+
// usage API leaves its cache's in place. The stretch since stays a gap, which
182+
// the forecast spreads a change across (usage on another device, say) rather
183+
// than taking the percent as unchanged until now. Undefined with no time for
184+
// it (a new transcript after /clear has no response yet). Looked up once per
185+
// render, and only when needed: a payload's means reading the transcript.
186+
function getSeenAtLookup(deps: SessionUsageHistoryDeps, nowMs: number): () => number | undefined {
187+
let looked = false;
188+
let seenAtMs: number | undefined;
189+
return () => {
190+
if (!looked) {
191+
looked = true;
192+
seenAtMs = deps.percentSeenAt ? deps.percentSeenAt() : nowMs;
193+
seenAtMs = seenAtMs !== undefined && Number.isFinite(seenAtMs) ? Math.min(nowMs, seenAtMs) : undefined;
194+
}
187195

188-
const seenAtMs = deps.percentSeenAt();
189-
return seenAtMs !== undefined && Number.isFinite(seenAtMs) ? Math.min(nowMs, seenAtMs) : lastSeenMs;
196+
return seenAtMs;
197+
};
190198
}
191199

192200
// Removes the history's temp files that other renders left a minute or more
@@ -232,6 +240,7 @@ export function recordSessionUsageReading(
232240
): SessionUsageReading[] {
233241
const nowMs = deps.now();
234242
const clampedPercent = Math.max(0, Math.min(100, percent));
243+
const seenAt = getSeenAtLookup(deps, nowMs);
235244

236245
const profiles: Record<string, SessionUsageWindow[]> = {};
237246
for (const [key, windows] of Object.entries(readHistory(deps).profiles)) {
@@ -258,18 +267,21 @@ export function recordSessionUsageReading(
258267
}
259268

260269
if (last?.[2] !== clampedPercent) {
261-
readings.push([nowMs, nowMs, clampedPercent]);
270+
// A new percent can't have been seen before the last one was
271+
const firstSeenMs = Math.max(seenAt() ?? nowMs, last?.[1] ?? Number.NEGATIVE_INFINITY);
272+
readings.push([firstSeenMs, firstSeenMs, clampedPercent]);
262273
} else if (nowMs - last[1] < LAST_SEEN_WRITE_INTERVAL_MS) {
263274
// Not even now is a minute past the last sighting, so there's no need
264275
// to look up when the percent was seen
265276
return readings;
266277
} else {
267-
const seenAtMs = getUnchangedSeenAtMs(deps, nowMs, last[1]);
268-
if (seenAtMs - last[1] < LAST_SEEN_WRITE_INTERVAL_MS) {
278+
// With no time for the percent, the reading's own last sighting stands
279+
const lastSeenMs = seenAt() ?? last[1];
280+
if (lastSeenMs - last[1] < LAST_SEEN_WRITE_INTERVAL_MS) {
269281
return readings;
270282
}
271283

272-
last[1] = seenAtMs;
284+
last[1] = lastSeenMs;
273285
}
274286

275287
const tempPath = `${deps.cachePath}.${process.pid}.tmp`;

‎src/utils/usage-fetch.ts‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -357,6 +357,9 @@ export function parseUsageApiResponse(rawJson: string): UsageData | null {
357357
let cachedUsageData: UsageData | null = null;
358358
let usageCacheTime = 0;
359359
let usageErrorCacheMaxAge = LOCK_MAX_AGE;
360+
// When the usage API sent cachedUsageData's values, in ms: a cache file's are
361+
// as old as the file, which may have been written hours ago
362+
let usageFetchedAtMs: number | undefined;
360363

361364
type UsageLockError = z.infer<typeof UsageLockErrorSchema>;
362365

@@ -378,16 +381,27 @@ function setCachedUsageError(error: UsageError, now: number, maxAge = LOCK_MAX_A
378381
cachedUsageData = errorData;
379382
usageCacheTime = now;
380383
usageErrorCacheMaxAge = maxAge;
384+
usageFetchedAtMs = undefined;
381385
return errorData;
382386
}
383387

384-
function cacheUsageData(data: UsageData, now: number): UsageData {
388+
function cacheUsageData(data: UsageData, now: number, fetchedAtMs: number): UsageData {
385389
cachedUsageData = data;
386390
usageCacheTime = now;
387391
usageErrorCacheMaxAge = LOCK_MAX_AGE;
392+
usageFetchedAtMs = fetchedAtMs;
388393
return data;
389394
}
390395

396+
/**
397+
* When the usage API sent the values fetchUsageData last returned, in ms, or
398+
* undefined after an error. Served from the cache, during a rate limit say,
399+
* they can be hours old.
400+
*/
401+
export function getUsageFetchedAtMs(): number | undefined {
402+
return usageFetchedAtMs;
403+
}
404+
391405
function hasRequiredUsageField(data: UsageData, field: UsageDataField): boolean {
392406
if (data[field] !== undefined) {
393407
return true;
@@ -423,8 +437,8 @@ function getStaleUsageOrError(
423437
requiredFields: readonly UsageDataField[] = []
424438
): UsageData {
425439
const stale = readStaleUsageCache(cacheIdentity);
426-
if (stale && !stale.error && hasRequiredUsageFields(stale, requiredFields)) {
427-
return cacheUsageData(stale, now);
440+
if (stale && !stale.data.error && hasRequiredUsageFields(stale.data, requiredFields)) {
441+
return cacheUsageData(stale.data, now, stale.fetchedAtMs);
428442
}
429443

430444
return setCachedUsageError(error, now, errorCacheMaxAge);
@@ -663,13 +677,15 @@ function getUsageCredentialsWithBackoff(now: number): UsageCredentials | null {
663677
return credentials;
664678
}
665679

666-
function readStaleUsageCache(cacheIdentity: UsageCacheIdentity | null): UsageData | null {
680+
function readStaleUsageCache(cacheIdentity: UsageCacheIdentity | null): { data: UsageData; fetchedAtMs: number } | null {
667681
try {
682+
const fetchedAtMs = fs.statSync(CACHE_FILE).mtimeMs;
668683
const rawCache = fs.readFileSync(CACHE_FILE, 'utf8');
669684
if (!tokenHashMatches(readCachedTokenHash(rawCache), cacheIdentity)) {
670685
return null;
671686
}
672-
return parseCachedUsageData(rawCache);
687+
const data = parseCachedUsageData(rawCache);
688+
return data ? { data, fetchedAtMs } : null;
673689
} catch {
674690
return null;
675691
}
@@ -898,7 +914,7 @@ export async function fetchUsageData(options: FetchUsageDataOptions = {}): Promi
898914
if (fileData && !fileData.error
899915
&& tokenHashMatches(readCachedTokenHash(rawCache), cacheIdentity)
900916
&& hasRequiredUsageFields(fileData, requiredFields)) {
901-
return cacheUsageData(fileData, now);
917+
return cacheUsageData(fileData, now, stat.mtimeMs);
902918
}
903919
}
904920
} catch {
@@ -962,7 +978,7 @@ export async function fetchUsageData(options: FetchUsageDataOptions = {}): Promi
962978
clearOwnUsageLock(inFlightLock);
963979
}
964980

965-
return cacheUsageData(usageData, now);
981+
return cacheUsageData(usageData, now, Date.now());
966982
} catch {
967983
writeUsageLock(now + LOCK_MAX_AGE, 'parse-error');
968984
return getStaleUsageOrError('parse-error', now, cacheIdentity, LOCK_MAX_AGE, requiredFields);

‎src/utils/usage.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
export { fetchUsageData } from './usage-fetch';
1+
export {
2+
fetchUsageData,
3+
getUsageFetchedAtMs
4+
} from './usage-fetch';
25
export {
36
formatUsageDuration,
47
formatUsageResetAt,

0 commit comments

Comments
 (0)