Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions apps/server/src/serverSettings.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2365,7 +2365,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))("server settings"
}).pipe(Effect.provide(layerServerSettings())),
);

it.effect("leaves an unreadable settings.json untouched instead of folding over it", () =>
it.effect.each([
{ label: "malformed JSON", broken: '{"defaultAutoPull": tru' },
{ label: "invalid retention", broken: '{"usageHistoryRetentionDays": 0}' },
])("leaves settings.json with $label untouched and disables destructive defaults", ({ broken }) =>
Effect.gen(function* () {
const serverConfig = yield* ServerConfig.ServerConfig;
const fileSystem = yield* FileSystem.FileSystem;
Expand All @@ -2380,12 +2383,12 @@ it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))("server settings"
${"2026-08-25T00:00:00.000Z"}, ${"2026-08-25T00:00:00.000Z"}
)
`;
const broken = '{"defaultAutoPull": tru';
yield* fileSystem.writeFileString(serverConfig.settingsPath, broken);

const settings = yield* serverSettings.getSettings;
assert.isFalse(settings.projectSettingsFolded);
assert.isFalse(settings.continueThreadsAfterServerUpdate);
assert.equal(settings.usageHistoryRetentionDays, "unlimited");
assert.deepEqual(settings.projectSettingsOverrides, {});

assert.equal(yield* fileSystem.readFileString(serverConfig.settingsPath), broken);
Expand Down
6 changes: 5 additions & 1 deletion apps/server/src/serverSettings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -806,7 +806,11 @@ const make = Effect.gen(function* () {
if (decoded._tag === "Failure" || legacySettings._tag === "Failure") {
const failure = decoded._tag === "Failure" ? decoded : legacySettings;
// The file may hold an opt-out we can no longer read; never resume threads on a guess.
settings = { ...managed.defaults, continueThreadsAfterServerUpdate: false };
settings = {
...managed.defaults,
continueThreadsAfterServerUpdate: false,
usageHistoryRetentionDays: "unlimited",
};
if (failure._tag === "Failure") {
parseFailure = Option.some(Cause.squash(failure.cause));
yield* Effect.logWarning("failed to parse settings.json, using defaults", {
Expand Down
249 changes: 218 additions & 31 deletions apps/server/src/usage/UsageService.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import {
} from "@t3tools/contracts";
import * as Duration from "effect/Duration";
import * as Clock from "effect/Clock";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
Expand Down Expand Up @@ -289,12 +290,14 @@ function makeFakeCursor() {
events: [] as { readonly timestampMs: number; readonly outputTokens: number }[],
error: null as string | null,
gate: undefined as Deferred.Deferred<void> | undefined,
started: undefined as Deferred.Deferred<void> | undefined,
calls: [] as { readonly sinceMs: number; readonly untilMs: number }[],
credentials: [] as unknown[],
};
const read = (credential: unknown, sinceMs: number, untilMs: number) =>
Effect.gen(function* () {
state.calls.push({ sinceMs, untilMs });
if (state.started !== undefined) yield* Deferred.succeed(state.started, undefined);
state.credentials.push(credential);
if (state.gate !== undefined) yield* Deferred.await(state.gate);
const { accountKey, error } = state;
Expand Down Expand Up @@ -1864,45 +1867,119 @@ describe("UsageService", () => {
}),
);

it.effect("restores the Cursor account cache after a restart", () =>
it.effect.each([
{ label: "default", retention: undefined, cutoff: CURSOR_NOW - 92 * 24 * HOUR_MS },
{ label: "unlimited", retention: "unlimited" as const, cutoff: 0 },
{ label: "36500 days", retention: 36500, cutoff: 0 },
])(
"propagates the $label cutoff and restores the Cursor account cache after a restart",
({ retention, cutoff }) =>
Effect.gen(function* () {
const { settings, home } = yield* setup;
yield* TestClock.setTime(CURSOR_NOW);
const before = makeFakeCursor();
before.state.events = [
{ timestampMs: CURSOR_NOW - 30 * HOUR_MS, outputTokens: 5 },
{ timestampMs: CURSOR_NOW - 3 * HOUR_MS, outputTokens: 7 },
];
yield* Effect.gen(function* () {
const first = yield* makeWithCursor(before.read);
const original = yield* first.readSummary({ ...WINDOW, awaitRefresh: true });
assert.deepStrictEqual(before.state.calls, [{ sinceMs: cutoff, untilMs: CURSOR_NOW }]);
yield* first.awaitPersisted;

const after = makeFakeCursor();
after.state.events = before.state.events;
const restarted = yield* makeWithCursor(after.read);
const restored = yield* restarted.readSummary(WINDOW);
assert.isUndefined(cursorSource(restored)?.refreshing);
assert.deepStrictEqual(restored.buckets, original.buckets);
assert.deepStrictEqual(cursorSource(restored), cursorSource(original));
assert.strictEqual(after.state.calls.length, 0);

yield* TestClock.adjust(Duration.minutes(2));
const refreshed = yield* restarted.readSummary({ ...WINDOW, awaitRefresh: true });
assert.deepStrictEqual(refreshed.buckets, original.buckets);
assert.deepStrictEqual(after.state.calls, [
{ sinceMs: CURSOR_NOW - HOUR_MS, untilMs: CURSOR_NOW + 2 * 60 * 1000 },
]);
}).pipe(
Effect.provide(
layerService({
prefix: "usage-service-cursor-restart",
environment: { CURSOR_API_KEY: "test-key" },
home,
settings: {
...settings,
...(retention === undefined ? {} : { usageHistoryRetentionDays: retention }),
},
}),
),
);
}),
);

it.effect("widens Cursor history after awaiting a shared narrower refresh", () =>
Effect.gen(function* () {
const { settings, home } = yield* setup;
yield* TestClock.setTime(CURSOR_NOW);
const before = makeFakeCursor();
before.state.events = [
{ timestampMs: CURSOR_NOW - 30 * HOUR_MS, outputTokens: 5 },
const cursor = makeFakeCursor();
cursor.state.gate = yield* Deferred.make<void>();
cursor.state.started = yield* Deferred.make<void>();
cursor.state.events = [
{ timestampMs: CURSOR_NOW - 120 * 24 * HOUR_MS, outputTokens: 5 },
{ timestampMs: CURSOR_NOW - 3 * HOUR_MS, outputTokens: 7 },
];
yield* Effect.gen(function* () {
const first = yield* makeWithCursor(before.read);
const original = yield* first.readSummary({ ...WINDOW, awaitRefresh: true });
yield* first.awaitPersisted;

const after = makeFakeCursor();
after.state.events = before.state.events;
const restarted = yield* makeWithCursor(after.read);
const restored = yield* restarted.readSummary(WINDOW);
assert.isUndefined(cursorSource(restored)?.refreshing);
assert.deepStrictEqual(restored.buckets, original.buckets);
assert.deepStrictEqual(cursorSource(restored), cursorSource(original));
assert.strictEqual(after.state.calls.length, 0);

yield* TestClock.adjust(Duration.minutes(2));
const refreshed = yield* restarted.readSummary({ ...WINDOW, awaitRefresh: true });
assert.deepStrictEqual(refreshed.buckets, original.buckets);
assert.deepStrictEqual(after.state.calls, [
{ sinceMs: CURSOR_NOW - HOUR_MS, untilMs: CURSOR_NOW + 2 * 60 * 1000 },
]);
}).pipe(
Effect.provide(
layerService({
prefix: "usage-service-cursor-restart",
home,
settings,
const context = yield* Layer.build(
layerCursorUsageAccounts(
Layer.succeed(CursorAccountReader.CursorAccountReader, { read: cursor.read }),
).pipe(
Layer.provide(
layerService({
prefix: "usage-service-cursor-shared-refresh",
home,
settings,
platform: "darwin",
}),
),
),
);
const accounts = Context.get(context, CursorUsageAccounts.CursorUsageAccounts);
const input = {
instances: [
{
instanceId: ProviderInstanceId.make("cursor"),
environment: { CURSOR_API_KEY: "test-key" },
}),
},
],
windowStartMs: 0,
retentionCutoffMs: CURSOR_NOW - 92 * 24 * HOUR_MS,
awaitRefresh: false,
};
const narrow = yield* accounts.scan(input);
assert.isTrue(narrow[0]?.refreshing);
yield* Deferred.await(cursor.state.started);
const wider = yield* accounts
.scan({ ...input, retentionCutoffMs: 0, awaitRefresh: true })
.pipe(Effect.forkChild({ startImmediately: true }));
assert.strictEqual(cursor.state.calls.length, 1);
yield* Deferred.succeed(cursor.state.gate, undefined);
const sources = yield* Fiber.join(wider);
assert.deepStrictEqual(cursor.state.calls, [
{ sinceMs: input.retentionCutoffMs, untilMs: CURSOR_NOW },
{ sinceMs: 0, untilMs: CURSOR_NOW },
]);
assert.strictEqual(sources[0]?.status, "ok");
assert.deepStrictEqual(
sources[0]?.files?.flatMap((file) =>
file.records.map(({ timestampMs, totals }) => ({
timestampMs,
outputTokens: totals.outputTokens,
})),
),
cursor.state.events,
);
yield* accounts.awaitPersisted;
}),
);

Expand Down Expand Up @@ -3536,6 +3613,116 @@ describe("UsageService", () => {
}),
);

it.effect.each([
{ label: "the default 92 days", retention: undefined, expected: 1 },
{ label: "unlimited", retention: "unlimited" as const, expected: 15 },
])(
"retains deleted transcripts according to $label across restart and settings changes",
({ retention, expected }) =>
Effect.gen(function* () {
const { transcript, settings, home } = yield* setup;
const now = Date.parse("2026-08-02T12:00:00Z");
yield* TestClock.setTime(now);
const window = { ...WINDOW, sinceDay: UsageDay.make("2024-01-01") };
const files = [92, 93, 180, 730].map((days, index) => ({
path: `${transcript}-${index}.jsonl`,
timestamp: now - days * 86400000,
content: claudeLine(index, 2 ** index).replace(
"2026-08-01T10:00:00Z",
DateTime.formatIso(DateTime.makeUnsafe(now - days * 86400000)),
),
}));
yield* Effect.promise(async () => {
for (const file of files) {
await NodeFSP.writeFile(file.path, file.content);
await NodeFSP.utimes(file.path, file.timestamp / 1000, file.timestamp / 1000);
}
});
yield* Effect.gen(function* () {
const service = yield* UsageService.make;
const first = yield* service.readSummary(window);
assert.strictEqual(totalOutputTokens(first), 15);
yield* service.awaitPersisted;
yield* Effect.promise(() => Promise.all(files.map((file) => NodeFSP.rm(file.path))));
const restarted = yield* UsageService.make;
const saved = yield* restarted.readSummary(window);
assert.strictEqual(totalOutputTokens(saved), expected);
assert.deepStrictEqual(saved.sources[0]?.fingerprint, first.sources[0]?.fingerprint);
const narrow = yield* restarted.readSummary(WINDOW);
assert.strictEqual(totalOutputTokens(narrow), 0);
assert.strictEqual(narrow.sources[0]?.distinctSessions, 0);

const config = yield* ServerSettings.ServerSettingsService;
yield* config.updateSettings({ usageHistoryRetentionDays: 1 });
assert.strictEqual(totalOutputTokens(yield* restarted.readSummary(window)), 0);
yield* restarted.awaitPersisted;
yield* config.updateSettings({ usageHistoryRetentionDays: "unlimited" });
const afterPruning = yield* UsageService.make;
assert.strictEqual(totalOutputTokens(yield* afterPruning.readSummary(window)), 0);
}).pipe(
Effect.provide(
layerService({
prefix: "usage-service-retention",
home,
settings: {
...settings,
...(retention === undefined ? {} : { usageHistoryRetentionDays: retention }),
},
}),
),
);
}),
);

it.effect("keeps retained history when an obsolete scan finishes after retention widens", () =>
Effect.gen(function* () {
const { transcript, settings, home } = yield* setup;
yield* TestClock.setTime(CURSOR_NOW);
const timestamp = CURSOR_NOW - 180 * 24 * HOUR_MS;
yield* Effect.promise(async () => {
await NodeFSP.writeFile(
transcript,
claudeLine(1, 11).replace(
"2026-08-01T10:00:00Z",
DateTime.formatIso(DateTime.makeUnsafe(timestamp)),
),
);
await NodeFSP.utimes(transcript, timestamp / 1000, timestamp / 1000);
});
const started = yield* Deferred.make<void>();
const release = yield* Deferred.make<void>();
let scans = 0;
yield* Effect.gen(function* () {
const config = yield* ServerSettings.ServerSettingsService;
const service = yield* UsageService.make.pipe(
Effect.provideService(CursorUsageAccounts.CursorUsageAccounts, {
scan: () =>
Effect.gen(function* () {
if (++scans === 1) {
yield* Deferred.succeed(started, undefined);
yield* Deferred.await(release);
}
return [];
}),
awaitPersisted: Effect.void,
}),
);
const window = { ...WINDOW, sinceDay: UsageDay.make("2024-01-01") };
const oldScan = yield* service.readSummary(window).pipe(Effect.forkChild);
yield* Deferred.await(started);
yield* config.updateSettings({ usageHistoryRetentionDays: "unlimited" });
assert.strictEqual(totalOutputTokens(yield* service.readSummary(window)), 11);
yield* service.awaitPersisted;
yield* Effect.promise(() => NodeFSP.rm(transcript));
yield* Deferred.succeed(release, undefined);
yield* Fiber.join(oldScan);
yield* service.awaitPersisted;
const restarted = yield* UsageService.make;
assert.strictEqual(totalOutputTokens(yield* restarted.readSummary(window)), 11);
}).pipe(Effect.provide(layerService({ prefix: "usage-retention-race", home, settings })));
}),
);

it.effect("credits the same copy of a duplicate after its transcripts are deleted", () =>
Effect.gen(function* () {
const { transcript, settings, home } = yield* setup;
Expand Down
34 changes: 24 additions & 10 deletions apps/server/src/usage/UsageService.ts
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,6 @@ const RATES_REFRESH_FLOOR_MS = 60 * 1000;
const MTIME_SLACK_MS = 36 * 60 * 60 * 1000;
const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000;

const CACHE_RETENTION_DAYS = 92;
const STALE_TEMP_DIRECTORY_MS = 60 * 60 * 1000;

const TRANSCRIPT_READ_CONCURRENCY = 4;
Expand Down Expand Up @@ -872,7 +871,10 @@ export const make = Effect.gen(function* () {
const windowStartMs =
(hourlyWindow?.sinceTimeMs ?? DateTime.toEpochMillis(windowStart.value)) - MTIME_SLACK_MS;

const retentionCutoffMs = startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
const retentionCutoffMs =
settings.usageHistoryRetentionDays === "unlimited"
? 0
: Math.max(0, startedAtMs - settings.usageHistoryRetentionDays * 24 * 60 * 60 * 1000);

const awaitRefresh = input.awaitRefresh === true;
const collect = Effect.gen(function* () {
Expand Down Expand Up @@ -1144,14 +1146,26 @@ export const make = Effect.gen(function* () {
});
}

const pruned = pruneScanCache(fileCache, retentionCutoffMs);
if (pruned > 0) {
cacheDirty = true;
// Pruned files are no longer saved, so nothing before the cutoff stays covered.
for (const [key, since] of coveredSince) {
if (since < retentionCutoffMs) coveredSince.set(key, retentionCutoffMs);
}
}
yield* settingsService
.withSettingsSnapshot((currentSettings) =>
Effect.sync(() => {
if (settings.usageHistoryRetentionDays === currentSettings.usageHistoryRetentionDays) {
const pruned = pruneScanCache(fileCache, retentionCutoffMs);
if (pruned > 0) {
cacheDirty = true;
// Pruned files are no longer saved, so nothing before the cutoff stays covered.
for (const [key, since] of coveredSince) {
if (since < retentionCutoffMs) coveredSince.set(key, retentionCutoffMs);
}
}
}
}),
)
.pipe(
Effect.catchCause((cause) =>
Effect.logWarning("failed to read settings before pruning the usage cache", { cause }),
),
);

const aggregated = aggregator.finish();
const readAt = yield* DateTime.now;
Expand Down
7 changes: 7 additions & 0 deletions docs/user/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,13 @@ record are missing from the totals.
Text generation (thread titles, commit messages, PR text, branch names and review guides) is not in
the totals for Codex or Claude Code 2.0.63 and newer, because those runs save no session history.

The server keeps scanned usage history for 92 days by default. Claude Code deletes its own
transcripts after 30 days, so for older Claude usage this history is the only record left. To keep
it longer, set `usageHistoryRetentionDays` in `<T3 home>/userdata/settings.json` to a number of days
such as `365`, or to `"unlimited"`. Usage views still show at most 90 days. Lowering the value
prunes older history on the next refresh, and raising it again does not bring pruned history back.
While `settings.json` cannot be read, nothing is pruned.

OpenCode reads its SQLite database and older JSON history. Antigravity reads local conversation
databases, including T3-managed profiles. Set `OPENCODE_DATA_DIR` or `ANTIGRAVITY_DATA_DIR` on the
server to read a different data directory; comma-separated paths read multiple directories.
Expand Down
Loading
Loading