@@ -522,7 +567,7 @@ export function UsagePage() {
))}
) : (
- <>
+
{sourceMessages.map((message) => (
{message}
@@ -531,13 +576,20 @@ export function UsagePage() {
-
+
{metric === "cost"
? formatUsd(merged.costUsd)
: formatTokens(merged.totalTokens)}
- {formatCount(merged.sessions)} sessions
+
+ {formatCount(merged.sessions)} sessions
+
{metric === "cost" && (
<>
{" · API estimate"}
@@ -600,6 +652,8 @@ export function UsagePage() {
const sessionLabel = `${formatCount(providerSessions)} ${
providerSessions === 1 ? "session" : "sessions"
}`;
+ const providerLoading = isProviderLoading(provider);
+ const awaitingData = providerLoading && !providersWithData.includes(provider);
return (
@@ -616,18 +670,38 @@ export function UsagePage() {
{PROVIDER_PRESENTATION[provider].label}
-
+
{sessionLabel}
-
- {metric === "cost"
- ? formatUsd(totals?.costUsd ?? 0)
- : formatTokens(totals?.totalTokens ?? 0)}
+
+ {awaitingData
+ ? "—"
+ : metric === "cost"
+ ? formatUsd(totals?.costUsd ?? 0)
+ : formatTokens(totals?.totalTokens ?? 0)}
-
+ {/* Kept while awaiting data so the row does not grow when it lands. */}
+
{metric === "cost"
? `${formatPercent(share)} of cost · ${formatTokens(totals?.totalTokens ?? 0)} tokens`
: `${formatPercent(share)} of tokens · ${formatUsd(totals?.costUsd ?? 0)}`}
@@ -639,19 +713,20 @@ export function UsagePage() {
- {isPast24Hours ? "Hourly" : "Daily"}{" "}
+ {shownHourly ? "Hourly" : "Daily"}{" "}
{metric === "tokens" ? "processed tokens" : "cost"}
@@ -659,14 +734,28 @@ export function UsagePage() {
Totals
-
-
+
+
-
+
@@ -674,7 +763,12 @@ export function UsagePage() {
{merged.totalTokens > 0 ? (
-
+
{metric === "tokens" ? (
(
@@ -752,6 +846,7 @@ export function UsagePage() {
model,
metric === "tokens" ? "tokens" : "cost",
);
+ const rowFigures = figureClass(isProviderLoading(model.provider));
return (
|
{model.model}
-
+
-
+ |
{isModelCostUnknown(model) ? (
Unpriced
) : (
formatUsd(model.costUsd)
)}
|
-
+ |
{share === null ? "" : formatPercent(share)}
|
-
{formatTokens(model.totalTokens)} |
+
+ {formatTokens(model.totalTokens)}
+ |
);
})
@@ -813,7 +913,7 @@ export function UsagePage() {
- | {isPast24Hours ? "Hour" : "Day"} |
+ {shownHourly ? "Hour" : "Day"} |
{activeProviders.map((provider) => (
{PROVIDER_PRESENTATION[provider].label}
@@ -841,21 +941,34 @@ export function UsagePage() {
>
|
{"hourStart" in period
- ? formatHourShort(period.hourStart, window.timeZone)
+ ? formatHourShort(period.hourStart, shownWindow.timeZone)
: formatDayShort(period.day)}
|
{activeProviders.map((provider) => (
{formatUsd(period.byProvider.get(provider)?.costUsd ?? 0)}
|
))}
-
+ |
{formatUsd(period.costUsd)}
|
-
+ |
{formatTokens(period.totalTokens)}
|
@@ -865,7 +978,7 @@ export function UsagePage() {
)}
-
+
)}
@@ -878,9 +991,9 @@ export function UsagePage() {
chartWindow={{
days,
hours,
- resolution: isPast24Hours ? "hour" : "day",
- timeZone: window.timeZone,
- referenceTime: window.untilTime,
+ resolution: shownHourly ? "hour" : "day",
+ timeZone: shownWindow.timeZone,
+ referenceTime: shownWindow.untilTime,
}}
onSetPrice={() => {
setSelectedModelKey(null);
@@ -1052,11 +1165,28 @@ function ProviderMark({
);
}
-function Metric({ label, value }: { readonly label: string; readonly value: string }) {
+/** Mutes a figure that is still coming in. The delay keeps a quick answer from flashing. */
+function figureClass(loading: boolean) {
+ return cn("transition-opacity", loading && "opacity-40 delay-150");
+}
+
+function Metric({
+ label,
+ value,
+ loading,
+}: {
+ readonly label: string;
+ readonly value: string;
+ readonly loading: boolean;
+}) {
return (
{label}
- {value}
+
+ {value}
+
);
}
@@ -1108,13 +1238,14 @@ function UsageCoverageNotice({
);
}
-/** Environment selection and scan progress share a permanent header control. */
+/** Environment selection, with each environment's scan status in the menu. */
function UsageEnvironmentFilter({
environments,
selectedEnvironments,
selectedEnvironmentIds,
onSelectionChange,
showUsageStatus,
+ refreshing,
isPartial,
duplicateSources,
contractMismatches,
@@ -1125,6 +1256,7 @@ function UsageEnvironmentFilter({
readonly selectedEnvironmentIds: ReadonlySet | null;
readonly onSelectionChange: (ids: ReadonlySet | null) => void;
readonly showUsageStatus: boolean;
+ readonly refreshing: boolean;
readonly isPartial: boolean;
readonly duplicateSources: readonly string[];
readonly contractMismatches: MergedUsage["contractMismatches"];
@@ -1136,10 +1268,6 @@ function UsageEnvironmentFilter({
: selectedEnvironments.length === 1
? selectedEnvironments[0]!.label
: `${selectedEnvironments.length} environments`;
- const pendingCount = selectedEnvironments.filter(
- (environment) =>
- environment.error === null && (environment.isPending || environment.summary === null),
- ).length;
const hasIssue =
selectedEnvironments.some((environment) => environment.error !== null) ||
contractMismatches.length > 0;
@@ -1149,15 +1277,7 @@ function UsageEnvironmentFilter({
} className="group/usage-environment min-w-0 max-w-full">
{label}
- {showUsageStatus && pendingCount > 0 ? (
- <>
-
-
- {pendingCount} {pendingCount === 1 ? "environment" : "environments"} still scanning
- {isPartial ? "; totals are partial" : ""}
-
-
- ) : showUsageStatus && hasIssue ? (
+ {showUsageStatus && hasIssue ? (
{
+ const column = (codex: number) => ({
+ total: codex,
+ bands: [{ provider: "codex" as const, value: codex }],
+ });
+
+ it("holds unlabeled placeholder gridlines while loading providers have nothing to show", () => {
+ const scale = chartScale([column(0)], new Set(["codex" as const]));
+
+ expect(scale.labeled).toBe(false);
+ expect(scale.ticks.length).toBeGreaterThan(1);
+ });
+
+ it("scales to what is on screen, loading or not", () => {
+ expect(chartScale([column(40)], new Set(["codex" as const]))).toMatchObject({
+ max: 40,
+ labeled: true,
+ });
+ });
+});
+
describe("niceScale", () => {
it("never puts the peak above the top of the scale", () => {
// Regression: an earlier version stopped at the last step below the peak,
diff --git a/apps/web/src/components/usage/UsageProviderChart.tsx b/apps/web/src/components/usage/UsageProviderChart.tsx
index 62772a6478dc..d8571f0b36d8 100644
--- a/apps/web/src/components/usage/UsageProviderChart.tsx
+++ b/apps/web/src/components/usage/UsageProviderChart.tsx
@@ -10,17 +10,21 @@ import {
formatTokens,
formatUsd,
} from "@t3tools/shared/usageFormat";
+import { cn } from "~/lib/utils";
import { PROVIDER_ORDER, PROVIDER_PRESENTATION } from "./usageProviders";
const VIEW_WIDTH = 960;
const VIEW_HEIGHT = 260;
const TICK_COUNT = 4;
const PLOT_TOP = 8;
+const NONE_LOADING: ReadonlySet = new Set();
export type UsageChartMetric = "tokens" | "cost";
interface UsageProviderChartProps {
readonly providers: readonly UsageProviderKind[];
+ /** Providers whose figures are still coming in: their lines are muted. */
+ readonly loadingProviders?: ReadonlySet;
readonly days: readonly string[];
readonly daily: readonly DailyTotals[];
readonly hours: readonly string[];
@@ -148,6 +152,10 @@ function curvePath(segments: readonly CurveSegment[]): string {
return path;
}
+function areaPath(line: string) {
+ return line === "" ? "" : `${line} L${VIEW_WIDTH},${VIEW_HEIGHT} L0,${VIEW_HEIGHT} Z`;
+}
+
/**
* Builds a scale whose maximum is a readable 1/2/5 x 10^n step at or above the
* peak.
@@ -170,8 +178,71 @@ export function niceScale(peak: number, count: number): { max: number; ticks: re
return { max, ticks };
}
+const PLACEHOLDER_TICKS = Array.from({ length: TICK_COUNT + 1 }, (_, index) => index);
+
+/**
+ * Scales to the largest single provider-period. With nothing to show yet while
+ * providers load, unlabeled placeholder gridlines hold their usual spacing so
+ * nothing shifts on arrival.
+ */
+export function chartScale(
+ columns: readonly DayColumn[],
+ loadingProviders: ReadonlySet,
+) {
+ // Not the sum: layered series each measure from zero, so a combined peak
+ // would leave the plot permanently half empty.
+ const peak = columns.reduce(
+ (max, column) => column.bands.reduce((inner, band) => Math.max(inner, band.value), max),
+ 0,
+ );
+ return peak === 0 && loadingProviders.size > 0
+ ? { max: TICK_COUNT, ticks: PLACEHOLDER_TICKS, labeled: false }
+ : { ...niceScale(peak, TICK_COUNT), labeled: true };
+}
+
+// Leave room above the top gridline so the constant-width stroke is not
+// clipped when a series reaches the peak.
+function valueToY(value: number, max: number) {
+ return max === 0 ? VIEW_HEIGHT : VIEW_HEIGHT - (value / max) * (VIEW_HEIGHT - PLOT_TOP);
+}
+
+/** Per-provider paths in paint order, heaviest first. */
+function buildChart(
+ periods: readonly string[],
+ byPeriod: ReadonlyMap,
+ metric: UsageChartMetric,
+ providers: readonly UsageProviderKind[],
+ loadingProviders: ReadonlySet,
+) {
+ const columns = buildPeriodColumns(periods, byPeriod, metric);
+ const scale = chartScale(columns, loadingProviders);
+ const stepX = periods.length < 2 ? 0 : VIEW_WIDTH / (periods.length - 1);
+ const paths = providers.map((provider) => {
+ const slot = PROVIDER_ORDER.indexOf(provider);
+ const line = curvePath(
+ smoothCurve(
+ columns.map((column, periodIndex) => ({
+ x: periodIndex * stepX,
+ y: valueToY(column.bands[slot]?.value ?? 0, scale.max),
+ })),
+ ),
+ );
+ return {
+ provider,
+ loading: loadingProviders.has(provider),
+ total: columns.reduce((sum, column) => sum + (column.bands[slot]?.value ?? 0), 0),
+ line,
+ area: areaPath(line),
+ };
+ });
+
+ // Paint the heavier series first so the lighter one is not buried.
+ return { columns, scale, stepX, paths: paths.toSorted((a, b) => b.total - a.total) };
+}
+
export function UsageProviderChart({
providers,
+ loadingProviders = NONE_LOADING,
days,
daily,
hours,
@@ -194,59 +265,14 @@ export function UsageProviderChart({
const tooltipRef = useRef(null);
const hoverPositionRef = useRef<{ x: number; y: number } | null>(null);
- const { paths, ticks, stepX, toY, series } = useMemo(() => {
- if (periods.length === 0) {
- return {
- paths: [],
- series: [] as readonly DayColumn[],
- stepX: 0,
- ticks: [0] as readonly number[],
- toY: () => VIEW_HEIGHT,
- };
- }
-
- const columns = buildPeriodColumns(periods, byPeriod, metric);
- // The scale tops out at the largest single provider-period, not the sum:
- // layered series each measure from zero, so a combined peak would leave
- // the plot permanently half empty.
- const peak = columns.reduce(
- (max, column) => column.bands.reduce((inner, band) => Math.max(inner, band.value), max),
- 0,
- );
- const { max, ticks: tickValues } = niceScale(peak, TICK_COUNT);
- const step = periods.length === 1 ? 0 : VIEW_WIDTH / (periods.length - 1);
- // Leave room above the top gridline so the constant-width stroke is not
- // clipped when a series reaches the peak.
- const toY = (value: number) =>
- max === 0 ? VIEW_HEIGHT : VIEW_HEIGHT - (value / max) * (VIEW_HEIGHT - PLOT_TOP);
-
- const built = providers.map((provider) => {
- const providerIndex = PROVIDER_ORDER.indexOf(provider);
- const line = curvePath(
- smoothCurve(
- columns.map((column, periodIndex) => ({
- x: periodIndex * step,
- y: toY(column.bands[providerIndex]?.value ?? 0),
- })),
- ),
- );
- return {
- provider,
- total: columns.reduce((sum, column) => sum + (column.bands[providerIndex]?.value ?? 0), 0),
- area: line === "" ? "" : `${line} L${VIEW_WIDTH},${VIEW_HEIGHT} L0,${VIEW_HEIGHT} Z`,
- line,
- };
- });
-
- // Paint the heavier series first so the lighter one is not buried.
- return {
- paths: built.toSorted((a, b) => b.total - a.total),
- series: columns,
- stepX: step,
- ticks: tickValues,
- toY,
- };
- }, [byPeriod, metric, periods, providers]);
+ const { columns, scale, paths, stepX } = useMemo(
+ () => buildChart(periods, byPeriod, metric, providers, loadingProviders),
+ [byPeriod, loadingProviders, metric, periods, providers],
+ );
+ const toY = (value: number) => valueToY(value, scale.max);
+ // The delay keeps a quick answer from flashing, as with the page's figures.
+ const seriesClassName = (loading: boolean) =>
+ cn("transition-opacity", loading && "opacity-40 delay-150");
const format = metric === "tokens" ? formatTokens : formatUsd;
@@ -307,7 +333,8 @@ export function UsageProviderChart({
);
const hoveredPeriod = hoverIndex === null ? undefined : periods[hoverIndex];
- const hoveredColumn = hoverIndex === null ? undefined : series[hoverIndex];
+ const hoveredColumn = hoverIndex === null ? undefined : columns[hoverIndex];
+ const partial = providers.some((provider) => loadingProviders.has(provider));
const formatPeriod = (period: string) =>
resolution === "hour" ? formatHourShort(period, timeZone) : formatDayShort(period);
const formatTooltipPeriod = (period: string) =>
@@ -320,15 +347,17 @@ export function UsageProviderChart({
{/* Axis labels sit outside the plot so they stay aligned to gridlines. */}
- {ticks.map((tick) => (
-
- {tick === 0 ? "0" : format(tick)}
-
- ))}
+ {scale.labeled
+ ? scale.ticks.map((tick) => (
+
+ {tick === 0 ? "0" : format(tick)}
+
+ ))
+ : null}
- {ticks.map((tick) => {
+ {scale.ticks.map((tick) => {
const y = toY(tick);
return (
(
+ {paths.map(({ provider, loading, area }) => (
))}
- {paths.map(({ provider, line }) => (
+ {paths.map(({ provider, loading, line }) => (
{label}
-
+
{format(
hoveredColumn?.bands.find((band) => band.provider === provider)?.value ?? 0,
)}
@@ -430,7 +468,12 @@ export function UsageProviderChart({
})}
Total
-
+
{format(hoveredColumn?.total ?? 0)}
diff --git a/apps/web/src/state/usage.test.tsx b/apps/web/src/state/usage.test.tsx
index c084d0a5e9ab..7b2efd76b16d 100644
--- a/apps/web/src/state/usage.test.tsx
+++ b/apps/web/src/state/usage.test.tsx
@@ -33,6 +33,7 @@ function environment(
label: id,
isPending: cost === null,
canReadDiagnostics: true,
+ isConnected: true,
error: null,
needsCursorKeychainAccess: false,
summary:
@@ -90,11 +91,13 @@ let latest: UsageView;
function Probe({
selected,
hidden,
+ window = input,
}: {
selected: ReadonlySet | null;
hidden?: ReadonlySet;
+ window?: typeof input;
}) {
- const usage = useUsage(input, selected, hidden);
+ const usage = useUsage(window, selected, hidden);
useLayoutEffect(() => {
latest = usage;
}, [usage]);
@@ -181,6 +184,45 @@ describe("usage environment selection", () => {
expect(latest.isPending).toBe(false);
expect(latest.isPartial).toBe(false);
});
+
+ it("shows the last answered usage until the next window answers, for the same selection", async () => {
+ const selected = new Set([EnvironmentId.make("a")]);
+ await act(() => renderer?.update());
+ expect(latest.shown?.merged.costUsd).toBe(10);
+
+ // A new window that nothing has answered yet.
+ const nextWindow = { ...input, sinceDay: UsageDay.make("2026-08-28") };
+ testState.environments = [environment("a", null)];
+ await act(() => renderer?.update());
+ expect(latest.isPending).toBe(true);
+ expect(latest.shown?.window).toBe(input);
+ expect(latest.shown?.merged.costUsd).toBe(10);
+
+ // A window that fails everywhere keeps it too.
+ testState.environments = [{ ...environment("a", null), isPending: false, error: "Offline" }];
+ await act(() => renderer?.update());
+ expect(latest.isPending).toBe(false);
+ expect(latest.shown?.window).toBe(input);
+ expect(latest.shown?.merged.costUsd).toBe(10);
+
+ // Once the new window answers, it replaces the kept one.
+ testState.environments = [environment("a", 30)];
+ await act(() => renderer?.update());
+ expect(latest.shown?.window).toBe(nextWindow);
+ expect(latest.shown?.merged.costUsd).toBe(30);
+
+ // A different provider filter does not reuse usage merged with the old one.
+ testState.environments = [environment("a", null)];
+ await act(() =>
+ renderer?.update(),
+ );
+ expect(latest.shown).toBeNull();
+
+ // Another selection has nothing of its own to show.
+ testState.environments = [environment("a", null)];
+ await select("a");
+ expect(latest.shown).toBeNull();
+ });
});
describe("usage provider filter", () => {
diff --git a/apps/web/src/state/usage.ts b/apps/web/src/state/usage.ts
index 6c964b3ebb03..28cf39a9f05a 100644
--- a/apps/web/src/state/usage.ts
+++ b/apps/web/src/state/usage.ts
@@ -20,7 +20,7 @@ import { needsCursorKeychainAccess, refreshUsage } from "@t3tools/client-runtime
import { resolveUsageAccess } from "@t3tools/client-runtime/state/usage-access";
import * as Option from "effect/Option";
import { AsyncResult, Atom } from "effect/reactivity";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useState } from "react";
import { mergeUsage, type EnvironmentUsage, type MergedUsage } from "@t3tools/shared/usageMerge";
import { appAtomRegistry } from "../rpc/atomRegistry";
@@ -33,6 +33,7 @@ export interface EnvironmentUsageStatus {
readonly label: string;
readonly isPending: boolean;
readonly canReadDiagnostics: boolean;
+ readonly isConnected: boolean;
readonly error: string | null;
readonly summary: UsageSummary | null;
readonly needsCursorKeychainAccess: boolean;
@@ -52,6 +53,7 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
const statuses: EnvironmentUsageStatus[] = [];
for (const [environmentId, presentation] of presentations) {
+ const isConnected = presentation.connection.phase === "connected";
const sessionResult = get(environmentSession.sessionStateAtom(environmentId));
const access = resolveUsageAccess({
connectionPhase: presentation.connection.phase,
@@ -62,6 +64,7 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
statuses.push({
environmentId,
label: presentation.entry.target.label,
+ isConnected,
...access,
summary: null,
needsCursorKeychainAccess: false,
@@ -75,6 +78,7 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
label: presentation.entry.target.label,
isPending: result.waiting,
canReadDiagnostics: true,
+ isConnected,
error: result._tag === "Failure" ? "This environment could not report usage." : null,
summary,
needsCursorKeychainAccess: needsCursorKeychainAccess(
@@ -93,6 +97,12 @@ export interface UsageView {
readonly selectedEnvironments: readonly EnvironmentUsageStatus[];
/** True until at least one selected environment has answered. */
readonly isPending: boolean;
+ /**
+ * The usage to draw: this window's once a selected environment answers,
+ * until then the last window answered for the same selection. Null while
+ * nothing has answered and something still could.
+ */
+ readonly shown: { readonly window: UsageSummaryInput; readonly merged: MergedUsage } | null;
/**
* True while environments that have not failed are still answering. Failed
* environments are reported through their own error rows: totals will not
@@ -225,12 +235,48 @@ export function useUsage(
const stillReporting = selectedEnvironments.filter(
(environment) => environment.summary === null && environment.error === null,
).length;
+ const isPending = answeredCount === 0 && stillReporting > 0;
+
+ // Stored during render, as React recommends for state that follows props, so
+ // the kept usage is on screen in the same frame the new window starts pending.
+ const [lastAnswered, setLastAnswered] = useState<
+ | (NonNullable & {
+ readonly selection: typeof selectedEnvironmentIds;
+ readonly hidden: typeof hiddenProviders;
+ })
+ | null
+ >(null);
+ if (
+ answeredCount > 0 &&
+ (lastAnswered?.merged !== merged ||
+ lastAnswered.window !== input ||
+ lastAnswered.selection !== selectedEnvironmentIds ||
+ lastAnswered.hidden !== hiddenProviders)
+ ) {
+ setLastAnswered({
+ window: input,
+ merged,
+ selection: selectedEnvironmentIds,
+ hidden: hiddenProviders,
+ });
+ }
+ // Kept usage only stands in for the same environments and provider filter.
+ const kept =
+ lastAnswered?.selection === selectedEnvironmentIds && lastAnswered.hidden === hiddenProviders
+ ? lastAnswered
+ : null;
+ // With no answers, even failed ones keep the last answered usage on screen.
+ const shown =
+ answeredCount > 0
+ ? { window: input, merged }
+ : (kept ?? (isPending ? null : { window: input, merged }));
return {
merged,
environments,
selectedEnvironments,
- isPending: answeredCount === 0 && stillReporting > 0,
+ isPending,
+ shown,
isPartial: answeredCount > 0 && stillReporting > 0,
refresh,
};
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 1ac918d5c52c..7474a30e8bc6 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -39,7 +39,8 @@ your app understands. Update the app to include newly supported providers.
On web and desktop, use the environment dropdown to filter costs, tokens, and limits. All
environments are selected by default. The dropdown shows which environments are still scanning;
-results appear as each one responds.
+results appear as each one responds, and figures still updating are dimmed. Cursor shows its last
+saved totals first, then updates them when Cursor's API responds.
If recent work is missing or a new model shows no cost, refresh to rescan session history and
update model pricing.
diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json
index 806920e5d449..d9735deb6819 100644
--- a/packages/client-runtime/package.json
+++ b/packages/client-runtime/package.json
@@ -231,6 +231,10 @@
"types": "./src/state/usage.ts",
"default": "./src/state/usage.ts"
},
+ "./state/usage-progress": {
+ "types": "./src/state/usageProgress.ts",
+ "default": "./src/state/usageProgress.ts"
+ },
"./state/server": {
"types": "./src/state/server.ts",
"default": "./src/state/server.ts"
diff --git a/packages/client-runtime/src/state/runtime.ts b/packages/client-runtime/src/state/runtime.ts
index 2f224e80b661..27a2348f4d42 100644
--- a/packages/client-runtime/src/state/runtime.ts
+++ b/packages/client-runtime/src/state/runtime.ts
@@ -53,12 +53,18 @@ interface EnvironmentCommandAtomOptions extends Omit<
) => Effect.Effect;
}
-interface EnvironmentQueryAtomOptions extends EnvironmentAtomOptions<
- Input,
- A,
- E,
- R
+interface EnvironmentQueryAtomOptions extends Omit<
+ EnvironmentAtomOptions,
+ "execute"
> {
+ /**
+ * `emit` shows a provisional value while the query keeps waiting. The settled
+ * result replaces it, so catch failures that should keep it on screen.
+ */
+ readonly execute: (
+ input: Input,
+ emit: (value: A) => Effect.Effect,
+ ) => Effect.Effect;
readonly staleTimeMs?: number;
readonly idleTtlMs?: number;
readonly refreshIntervalMs?: number;
@@ -547,10 +553,18 @@ export function createEnvironmentQueryAtomFamily(
return Effect.never;
}
const [connectionState, session] = connection;
+ const emit = (value: A) =>
+ Effect.sync(() => get.setSelf(AsyncResult.success(value, { waiting: true }))).pipe(
+ // A value set while the atom builds wins over the build's own
+ // result, so a query that then settled synchronously would stay
+ // waiting forever. Suspend on a promise (`yieldNow` is drained
+ // inside the build) so the settled result arrives asynchronously.
+ Effect.andThen(Effect.promise(() => Promise.resolve())),
+ );
switch (connectionState.phase) {
case "connected":
return Option.isSome(session)
- ? runInEnvironment(target.environmentId, options.execute(target.input))
+ ? runInEnvironment(target.environmentId, options.execute(target.input, emit))
: Effect.never;
case "connecting":
case "backoff":
@@ -650,6 +664,7 @@ export function createEnvironmentRpcQueryAtomFamily<
readonly tag: TTag;
readonly execute?: (
input: EnvironmentRpcInput,
+ emit: (value: EnvironmentRpcSuccess) => Effect.Effect,
) => Effect.Effect<
EnvironmentRpcSuccess,
EnvironmentRpcFailure | EnvironmentRpcUnavailableError,
@@ -672,8 +687,10 @@ export function createEnvironmentRpcQueryAtomFamily<
? {}
: { refreshIntervalMs: options.refreshIntervalMs }),
...(options.refreshTrigger === undefined ? {} : { refreshTrigger: options.refreshTrigger }),
- execute: (input: EnvironmentRpcInput) =>
- options.execute?.(input) ?? request(options.tag, input),
+ execute: (
+ input: EnvironmentRpcInput,
+ emit: (value: EnvironmentRpcSuccess) => Effect.Effect,
+ ) => options.execute?.(input, emit) ?? request(options.tag, input),
});
}
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index 17037af3c986..91464b16a9b1 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -1091,11 +1091,33 @@ export function createServerEnvironmentAtoms(
}),
// A cold transcript scan is measured in seconds, so keep the result around
// long enough that switching windows or re-rendering does not rescan.
+ // Slow sources answer from cache first: that summary stays on screen, with
+ // the query waiting, until one `awaitRefresh` request replaces it.
usageSummary: createEnvironmentRpcQueryAtomFamily(runtime, {
label: "environment-data:server:usage-summary",
tag: WS_METHODS.serverGetUsageSummary,
staleTimeMs: 60_000,
refreshTrigger: ({ environmentId }) => usageScanSettingsAtom(environmentId),
+ execute: (input, emit) =>
+ request(WS_METHODS.serverGetUsageSummary, input).pipe(
+ Effect.flatMap((summary) =>
+ summary.sources.some((source) => source.refreshing === true)
+ ? emit(summary).pipe(
+ Effect.andThen(
+ request(WS_METHODS.serverGetUsageSummary, { ...input, awaitRefresh: true }),
+ ),
+ // The cached summary is still the best data, and a failure
+ // would read as the environment not reporting usage at all.
+ Effect.catch((error) =>
+ Effect.logWarning("Could not refresh slow usage sources.").pipe(
+ Effect.annotateLogs({ ...safeErrorLogAttributes(error) }),
+ Effect.as(summary),
+ ),
+ ),
+ )
+ : Effect.succeed(summary),
+ ),
+ ),
}),
resourceTelemetry: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
label: "environment-data:server:resource-telemetry",
diff --git a/packages/client-runtime/src/state/serverUsage.test.ts b/packages/client-runtime/src/state/serverUsage.test.ts
index d6600e57e85c..3410fd3506fe 100644
--- a/packages/client-runtime/src/state/serverUsage.test.ts
+++ b/packages/client-runtime/src/state/serverUsage.test.ts
@@ -2,11 +2,13 @@ import {
DEFAULT_SERVER_SETTINGS,
EnvironmentId,
UsageDay,
+ UsageReadError,
USAGE_CONTRACT_VERSION,
WS_METHODS,
type ServerConfig,
type ServerConfigStreamEvent,
type ServerSettings,
+ type UsageSource,
type UsageSummary,
type UsageSummaryInput,
} from "@t3tools/contracts";
@@ -16,6 +18,7 @@ import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
+import * as Result from "effect/Result";
import * as Stream from "effect/Stream";
import * as SubscriptionRef from "effect/SubscriptionRef";
import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
@@ -26,12 +29,14 @@ import {
type PreparedConnection,
type SupervisorConnectionState,
} from "../connection/model.ts";
+import type { EnvironmentPresentation } from "../connection/presentation.ts";
import * as EnvironmentRegistry from "../connection/registry.ts";
import * as EnvironmentSupervisor from "../connection/supervisor.ts";
import * as Persistence from "../platform/persistence.ts";
import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
import type { RpcSession } from "../rpc/session.ts";
import { createServerEnvironmentAtoms } from "./server.ts";
+import { refreshUsage } from "./usage.ts";
const TARGET = new PrimaryConnectionTarget({
environmentId: EnvironmentId.make("usage-environment"),
@@ -51,13 +56,37 @@ const CONFIG = {
environment: { serverVersion: "0.0.1", capabilities: {} },
} as ServerConfig;
+const PRICING = { status: "unavailable" as const, source: "test", fetchedAt: null, knownModels: 0 };
+
+const cursorSource = (refreshing: boolean): UsageSource => ({
+ fingerprint: {
+ hostId: "cursor.com",
+ provider: "cursor",
+ resolvedHomePath: "cursor-account:abc",
+ volumeId: "abc",
+ },
+ status: "ok",
+ scannedFiles: 1,
+ skippedFiles: 0,
+ malformedRecords: 0,
+ distinctSessions: 1,
+ message: null,
+ ...(refreshing ? { refreshing: true as const } : {}),
+});
+
const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
- beforeRead: (request: number) => Effect.Effect = () => Effect.void,
+ beforeRead: (
+ request: number,
+ input: UsageSummaryInput,
+ ) => Effect.Effect = () => Effect.void,
+ sources: (input: UsageSummaryInput) => readonly UsageSource[] = () => [],
) {
const events = yield* Queue.unbounded();
let settings = DEFAULT_SERVER_SETTINGS;
let requests = 0;
+ const inputs: UsageSummaryInput[] = [];
const client = {
+ [WS_METHODS.serverRefreshUsageRates]: () => Effect.succeed(PRICING),
[WS_METHODS.subscribeServerConfig]: () =>
Stream.concat(
Stream.make({ version: 1 as const, type: "snapshot" as const, config: CONFIG }),
@@ -66,8 +95,9 @@ const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
[WS_METHODS.serverGetUsageSummary]: (input: UsageSummaryInput) =>
Effect.gen(function* () {
requests += 1;
+ inputs.push(input);
const price = settings.usagePriceOverrides["custom-model"]?.inputCostPerMillionTokens ?? 0;
- yield* beforeRead(requests);
+ yield* beforeRead(requests, input);
return {
contractVersion: USAGE_CONTRACT_VERSION,
readAt: "2026-09-04T12:00:00Z",
@@ -92,8 +122,8 @@ const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
sessions: 1,
},
],
- sources: [],
- pricing: { status: "unavailable", source: "test", fetchedAt: null, knownModels: 0 },
+ sources: sources(input),
+ pricing: PRICING,
scanDurationMs: 0,
} satisfies UsageSummary;
}),
@@ -167,12 +197,44 @@ const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
});
return {
registry,
+ atoms,
requests: () => requests,
+ inputs: () => inputs,
updateSettings,
summary: (input = INPUT) => atoms.usageSummary({ environmentId: TARGET.environmentId, input }),
};
});
+function settledSummary(
+ registry: AtomRegistry.AtomRegistry,
+ atom: Atom.Atom>,
+) {
+ return AtomRegistry.toStream(registry, atom).pipe(
+ Stream.filterMap((result) =>
+ AsyncResult.isSuccess(result) && !result.waiting
+ ? Result.succeed(result.value)
+ : Result.failVoid,
+ ),
+ Stream.runHead,
+ Effect.map(Option.getOrThrow),
+ );
+}
+
+/** Answers with a refreshing Cursor source; the `awaitRefresh` request runs `followUp` first. */
+const makeRefreshingHarness = Effect.fn("ServerUsageTest.makeRefreshingHarness")(function* (
+ followUp: Effect.Effect,
+) {
+ const followUpStarted = yield* Deferred.make();
+ const harness = yield* makeHarness(
+ (_request, input) =>
+ input.awaitRefresh === true
+ ? Deferred.succeed(followUpStarted, undefined).pipe(Effect.andThen(followUp))
+ : Effect.void,
+ (input) => [cursorSource(input.awaitRefresh !== true)],
+ );
+ return { ...harness, followUpStarted };
+});
+
function waitForCost(
registry: AtomRegistry.AtomRegistry,
atom: Atom.Atom>,
@@ -261,3 +323,87 @@ it.effect("restarts a pending usage read after a price change", () =>
}),
),
);
+
+it.effect("settles after one usage read when no source is refreshing", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const harness = yield* makeHarness();
+ const summary = harness.summary();
+ const unmount = harness.registry.mount(summary);
+ yield* settledSummary(harness.registry, summary);
+ expect(harness.inputs()).toEqual([INPUT]);
+ unmount();
+ }),
+ ),
+);
+
+it.effect("shows the cached usage summary until one awaited refresh replaces it", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const refreshed = yield* Deferred.make();
+ const harness = yield* makeRefreshingHarness(Deferred.await(refreshed));
+ const summary = harness.summary();
+ const unmount = harness.registry.mount(summary);
+ yield* Deferred.await(harness.followUpStarted);
+
+ const provisional = harness.registry.get(summary);
+ expect(AsyncResult.isSuccess(provisional) && provisional.waiting).toBe(true);
+ expect(Option.getOrNull(AsyncResult.value(provisional))?.sources).toEqual([
+ cursorSource(true),
+ ]);
+ expect(harness.inputs()).toEqual([INPUT, { ...INPUT, awaitRefresh: true }]);
+
+ yield* Deferred.succeed(refreshed, undefined);
+ expect((yield* settledSummary(harness.registry, summary)).sources).toEqual([
+ cursorSource(false),
+ ]);
+ expect(harness.requests()).toBe(2);
+ unmount();
+ }),
+ ),
+);
+
+it.effect("keeps the cached usage summary when the awaited refresh fails", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const harness = yield* makeRefreshingHarness(
+ Effect.fail(new UsageReadError({ reason: "scanFailed", detail: "Cursor is down" })),
+ );
+ const summary = harness.summary();
+ const unmount = harness.registry.mount(summary);
+ expect((yield* settledSummary(harness.registry, summary)).sources).toEqual([
+ cursorSource(true),
+ ]);
+ expect(AsyncResult.isSuccess(harness.registry.get(summary))).toBe(true);
+ expect(harness.requests()).toBe(2);
+ unmount();
+ }),
+ ),
+);
+
+it.effect("finishes a manual usage refresh only after the awaited refresh", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const refreshed = yield* Deferred.make();
+ const harness = yield* makeRefreshingHarness(Deferred.await(refreshed));
+ const presentation = Atom.make({
+ connection: { phase: "connected" },
+ } as EnvironmentPresentation | null);
+ let finished = false;
+ const refreshing = refreshUsage({
+ registry: harness.registry,
+ server: harness.atoms,
+ presentations: { presentationAtom: () => presentation },
+ environmentIds: [TARGET.environmentId],
+ input: INPUT,
+ }).then(() => {
+ finished = true;
+ });
+ yield* Deferred.await(harness.followUpStarted);
+ expect(finished).toBe(false);
+ yield* Deferred.succeed(refreshed, undefined);
+ yield* Effect.promise(() => refreshing);
+ expect(harness.requests()).toBe(2);
+ }),
+ ),
+);
diff --git a/packages/client-runtime/src/state/usageProgress.test.ts b/packages/client-runtime/src/state/usageProgress.test.ts
new file mode 100644
index 000000000000..889e696bfdd4
--- /dev/null
+++ b/packages/client-runtime/src/state/usageProgress.test.ts
@@ -0,0 +1,150 @@
+import {
+ USAGE_CONTRACT_VERSION,
+ UsageDay,
+ type UsageProviderKind,
+ type UsageSummary,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { usageEnvironmentProgress, usageLoadingState, usageProgress } from "./usageProgress.ts";
+
+function summary(refreshing: readonly UsageProviderKind[] = []): UsageSummary {
+ return {
+ contractVersion: USAGE_CONTRACT_VERSION,
+ readAt: "2026-09-05T12:00:00Z",
+ timeZone: "UTC",
+ sinceDay: UsageDay.make("2026-09-05"),
+ untilDay: UsageDay.make("2026-09-05"),
+ buckets: [],
+ sources: (["codex", ...refreshing] as const).map((provider) => ({
+ fingerprint: { hostId: "host", provider, resolvedHomePath: "/home", volumeId: "1:1" },
+ status: "ok" as const,
+ scannedFiles: 1,
+ skippedFiles: 0,
+ malformedRecords: 0,
+ distinctSessions: 1,
+ message: null,
+ ...(provider === "codex" ? {} : { refreshing: true as const }),
+ })),
+ pricing: { status: "fresh", source: "test", fetchedAt: null, knownModels: 1 },
+ scanDurationMs: 1,
+ };
+}
+
+function environment(
+ label: string,
+ overrides: Partial<{
+ isConnected: boolean;
+ isPending: boolean;
+ error: string | null;
+ summary: UsageSummary | null;
+ }> = {},
+) {
+ return {
+ label,
+ isConnected: true,
+ isPending: false,
+ error: null as string | null,
+ summary: summary(),
+ ...overrides,
+ };
+}
+
+const options = { providerLabel: (provider: UsageProviderKind) => `${provider} label` };
+
+describe("usageProgress", () => {
+ it("dims a lone environment while it refetches over its old totals", () => {
+ expect(usageProgress([environment("a", { isPending: true })], options)).toEqual({
+ dimmed: true,
+ label: "Updating…",
+ });
+ expect(usageProgress([environment("a")], options)).toEqual({ dimmed: false, label: null });
+ });
+
+ it("undims once one device answers and names the slow one", () => {
+ const waiting = [environment("a", { isPending: true }), environment("b", { isPending: true })];
+ expect(usageProgress(waiting, options)).toEqual({
+ dimmed: true,
+ label: "Updating 2 environments…",
+ });
+ expect(
+ usageProgress([environment("a"), ...waiting.slice(1), environment("c")], options),
+ ).toEqual({ dimmed: false, label: "Updating b…" });
+ expect(
+ usageProgress(
+ [environment("a"), environment("b", { summary: null, isPending: true })],
+ options,
+ ),
+ ).toEqual({ dimmed: false, label: "Updating b…" });
+ });
+
+ it("names a slow source without dimming once its environment answers from cache", () => {
+ const partway = environment("a", { isPending: true, summary: summary(["cursor"]) });
+ expect(usageEnvironmentProgress(partway)).toEqual({ phase: "partway", providers: ["cursor"] });
+ expect(usageProgress([partway, environment("b")], options)).toEqual({
+ dimmed: false,
+ label: "Updating cursor label…",
+ });
+ expect(
+ usageProgress(
+ [partway, environment("b", { isPending: true, summary: summary(["cursor", "grok"]) })],
+ options,
+ ),
+ ).toEqual({ dimmed: false, label: "Updating 2 providers…" });
+ // Without a follow-up in flight, a leftover refreshing source is not waited on.
+ expect(usageProgress([{ ...partway, isPending: false }], options)).toEqual({
+ dimmed: false,
+ label: null,
+ });
+ });
+
+ it("ignores reconnecting and failed environments", () => {
+ const ignored = [
+ environment("reconnecting", { isPending: true, isConnected: false }),
+ environment("failed", { error: "Offline", summary: null }),
+ ];
+ expect(usageProgress([environment("a"), ...ignored], options)).toEqual({
+ dimmed: false,
+ label: null,
+ });
+ expect(
+ usageProgress(
+ [environment("a"), ...ignored, environment("slow", { summary: null, isPending: true })],
+ options,
+ ),
+ ).toEqual({ dimmed: false, label: "Updating slow…" });
+ expect(usageEnvironmentProgress(ignored[0]!)).toEqual({ phase: "inactive" });
+ });
+
+ it("dims every answered environment while a manual refresh runs", () => {
+ // Pricing refreshes first, so neither query is pending yet.
+ expect(
+ usageProgress([environment("a"), environment("b")], { ...options, refreshing: true }),
+ ).toEqual({ dimmed: true, label: "Updating 2 environments…" });
+ });
+});
+
+describe("usageLoadingState", () => {
+ it("marks only refreshing providers while the rest have answered", () => {
+ const state = usageLoadingState([
+ environment("a", { isPending: true, summary: summary(["cursor"]) }),
+ environment("b"),
+ ]);
+ expect(state).toEqual({ partial: true, everyProvider: false, providers: new Set(["cursor"]) });
+ });
+
+ it("marks every provider while an environment has not answered", () => {
+ const state = usageLoadingState([environment("a"), environment("b", { summary: null })]);
+ expect(state.everyProvider).toBe(true);
+ expect(state.partial).toBe(true);
+ });
+
+ it("ignores environments that cannot answer and settles once all have", () => {
+ const state = usageLoadingState([
+ environment("a"),
+ environment("b", { summary: null, isConnected: false }),
+ environment("c", { summary: null, error: "Offline" }),
+ ]);
+ expect(state).toEqual({ partial: false, everyProvider: false, providers: new Set() });
+ });
+});
diff --git a/packages/client-runtime/src/state/usageProgress.ts b/packages/client-runtime/src/state/usageProgress.ts
new file mode 100644
index 000000000000..7e5f885c2874
--- /dev/null
+++ b/packages/client-runtime/src/state/usageProgress.ts
@@ -0,0 +1,114 @@
+import type { UsageProviderKind, UsageSummary } from "@t3tools/contracts";
+
+interface UsageProgressEnvironment {
+ readonly label: string;
+ readonly isConnected: boolean;
+ readonly isPending: boolean;
+ readonly error: string | null;
+ readonly summary: UsageSummary | null;
+}
+
+/**
+ * Where one environment's answer stands for the usage on screen.
+ *
+ * - `inactive`: disconnected or failed, so waiting on it changes nothing.
+ * - `loading`: no summary yet.
+ * - `stale`: its summary on screen predates the current request.
+ * - `partway`: answered this round while slow sources finish refreshing.
+ * - `ready`: answered.
+ *
+ * While a manual `refreshing` runs, every summary counts as stale.
+ */
+export function usageEnvironmentProgress(
+ environment: UsageProgressEnvironment,
+ refreshing = false,
+) {
+ const { summary } = environment;
+ if (!environment.isConnected || environment.error !== null) return { phase: "inactive" } as const;
+ if (summary === null) return { phase: "loading" } as const;
+ if (refreshing) return { phase: "stale" } as const;
+ // A refreshing source without a pending follow-up has nothing left to wait on.
+ if (!environment.isPending) return { phase: "ready" } as const;
+ const providers = [
+ ...new Set(
+ summary.sources.flatMap((source) => (source.refreshing ? [source.fingerprint.provider] : [])),
+ ),
+ ];
+ return providers.length > 0
+ ? ({ phase: "partway", providers } as const)
+ : ({ phase: "stale" } as const);
+}
+
+export function updatingProvidersLabel(
+ providers: readonly UsageProviderKind[],
+ providerLabel: (provider: UsageProviderKind) => string,
+) {
+ return providers.length === 1
+ ? `Updating ${providerLabel(providers[0]!)}…`
+ : `Updating ${providers.length} providers…`;
+}
+
+/**
+ * Loading state for the selected environments' merged usage.
+ *
+ * The page dims only while old numbers are all that is on screen. Once any
+ * environment answers, the label carries what is still coming, so one slow
+ * device never holds the page dimmed.
+ */
+export function usageProgress(
+ environments: readonly UsageProgressEnvironment[],
+ {
+ refreshing = false,
+ providerLabel,
+ }: {
+ readonly refreshing?: boolean;
+ readonly providerLabel: (provider: UsageProviderKind) => string;
+ },
+) {
+ const progress = environments.map((environment) => ({
+ label: environment.label,
+ ...usageEnvironmentProgress(environment, refreshing),
+ }));
+ const waiting = progress.filter(({ phase }) => phase === "loading" || phase === "stale");
+ const providers = [
+ ...new Set(progress.flatMap((entry) => (entry.phase === "partway" ? entry.providers : []))),
+ ];
+ const answered = progress.some(({ phase }) => phase === "partway" || phase === "ready");
+ return {
+ dimmed: !answered && progress.some(({ phase }) => phase === "stale"),
+ label:
+ waiting.length === 0
+ ? providers.length === 0
+ ? null
+ : updatingProvidersLabel(providers, providerLabel)
+ : environments.length === 1
+ ? "Updating…"
+ : waiting.length === 1
+ ? `Updating ${waiting[0]!.label}…`
+ : `Updating ${waiting.length} environments…`,
+ };
+}
+
+/**
+ * Which figures in the merged usage on screen are still coming in, so clients
+ * can mute just those.
+ *
+ * - `partial`: totals will change because some environment is still answering.
+ * - `providers`: providers whose own figures will change. An environment that
+ * has not answered yet, or whose whole summary is stale, could change any
+ * provider, so it sets `everyProvider`.
+ */
+export function usageLoadingState(
+ environments: readonly UsageProgressEnvironment[],
+ refreshing = false,
+) {
+ const providers = new Set();
+ let everyProvider = false;
+ for (const environment of environments) {
+ const progress = usageEnvironmentProgress(environment, refreshing);
+ if (progress.phase === "loading" || progress.phase === "stale") everyProvider = true;
+ if (progress.phase === "partway")
+ for (const provider of progress.providers) providers.add(provider);
+ }
+ return { partial: everyProvider || providers.size > 0, everyProvider, providers };
+}
diff --git a/packages/contracts/src/usage.ts b/packages/contracts/src/usage.ts
index f6282b7b2935..9aecc49ce5c3 100644
--- a/packages/contracts/src/usage.ts
+++ b/packages/contracts/src/usage.ts
@@ -183,6 +183,12 @@ export const UsageSource = Schema.Struct({
message: Schema.NullOr(TrimmedNonEmptyString),
/** An action the client can offer to make this source available. */
action: Schema.optionalKey(Schema.Literal("enableCursorKeychain")),
+ /**
+ * Present when this source answered from its cache while a slow refresh (an
+ * account API, for example) runs. Repeat the request with `awaitRefresh` to
+ * get the refreshed source.
+ */
+ refreshing: Schema.optionalKey(Schema.Literal(true)),
});
export type UsageSource = typeof UsageSource.Type;
@@ -217,6 +223,12 @@ export const UsageSummaryInput = Schema.Struct({
sinceTime: Schema.optional(TrimmedNonEmptyString),
/** Exclusive UTC instant for an hourly rolling window. */
untilTime: Schema.optional(TrimmedNonEmptyString),
+ /**
+ * Wait for slow sources to finish refreshing instead of answering from their
+ * cache. Clients send it as the follow-up to a summary with a `refreshing`
+ * source. Older servers ignore it and always wait.
+ */
+ awaitRefresh: Schema.optional(Schema.Boolean),
});
export type UsageSummaryInput = typeof UsageSummaryInput.Type;