Add hourly past-24-hour usage view (#6170)

Author: juliusmarminge

apps/mobile/src/features/usage/UsageRouteScreen.tsx

@@ -1,9 +1,11 @@
 import { useNavigation } from "@react-navigation/native";
-import type { MergedUsage } from "@t3tools/shared/usageMerge";
+import type { DailyTotals, MergedUsage } from "@t3tools/shared/usageMerge";
 import {
   enumerateDays,
+  enumerateHourStarts,
   formatCount,
   formatDayShort,
+  formatHourShort,
   formatPercent,
   formatTokens,
   formatUsd,
@@ -23,6 +25,7 @@ import type { UsageChartMetric } from "./usageChartData";
 import { PROVIDER_LABEL, useProviderColors } from "./usageProviders";
 
 const WINDOW_OPTIONS = [
+  { days: 1, label: "Past 24h" },
   { days: 7, label: "7 days" },
   { days: 30, label: "30 days" },
   { days: 90, label: "90 days" },
@@ -33,23 +36,62 @@ const CHART_HEIGHT = 180;
 export function UsageRouteScreen() {
   const navigation = useNavigation();
   const insets = useSafeAreaInsets();
-  const [windowDays, setWindowDays] = useState<number>(30);
+  const [windowSelection, setWindowSelection] = useState(() => ({
+    days: 30,
+    window: makeWindow(30),
+  }));
   const [metric, setMetric] = useState<UsageChartMetric>("cost");
-
-  // Recomputed only when the window length changes, so a re-render does not
-  // shift the range and refetch every environment.
-  const window = useMemo(() => makeWindow(windowDays), [windowDays]);
+  const { days: windowDays, window } = windowSelection;
+  const isPast24Hours = windowDays === 1;
   const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
 
   const days = useMemo(
     () => enumerateDays(window.sinceDay, window.untilDay),
     [window.sinceDay, window.untilDay],
   );
+  const chartDays = useMemo(
+    () =>
+      isPast24Hours && window.sinceTime !== undefined && window.untilTime !== undefined
+        ? enumerateHourStarts(window.sinceTime, window.untilTime)
+        : days,
+    [days, isPast24Hours, window.sinceTime, window.untilTime],
+  );
+  const chartTotals = useMemo(
+    (): readonly DailyTotals[] =>
+      isPast24Hours
+        ? merged.hourly.map((hour) => ({
+            day: hour.hourStart,
+            costUsd: hour.costUsd,
+            totalTokens: hour.totalTokens,
+            byProvider: hour.byProvider,
+          }))
+        : merged.daily,
+    [isPast24Hours, merged.daily, merged.hourly],
+  );
 
   // The pull spinner tracks re-scans of environments that have answered
   // before. The initial scan renders its own placeholder, and an unreachable
   // environment stays pending forever — neither may pin the spinner on.
   const refreshing = environments.some((entry) => entry.isPending && entry.summary !== null);
+  const selectWindow = (days: number) => {
+    setWindowSelection({
+      days,
+      window: makeWindow(days, undefined, days === 1 ? "hour" : "day"),
+    });
+  };
+  const refreshWindow = () => {
+    const nextWindow = makeWindow(windowDays, undefined, isPast24Hours ? "hour" : "day");
+    if (
+      nextWindow.sinceDay === window.sinceDay &&
+      nextWindow.untilDay === window.untilDay &&
+      nextWindow.sinceTime === window.sinceTime &&
+      nextWindow.untilTime === window.untilTime
+    ) {
+      refresh();
+    } else {
+      setWindowSelection({ days: windowDays, window: nextWindow });
+    }
+  };
 
   return (
     <View collapsable={false} className="flex-1 bg-sheet">
@@ -65,12 +107,12 @@ export function UsageRouteScreen() {
         className="flex-1"
         contentContainerClassName="gap-6 px-5 pt-4"
         contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
-        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refresh} />}
+        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refreshWindow} />}
       >
         <SegmentedControl
           options={WINDOW_OPTIONS.map((option) => ({ value: option.days, label: option.label }))}
           selected={windowDays}
-          onSelect={setWindowDays}
+          onSelect={selectWindow}
         />
 
         <UsageCoverageNotice environments={environments} merged={merged} isPartial={isPartial} />
@@ -87,14 +129,17 @@ export function UsageRouteScreen() {
           <>
             <ChartCard
               merged={merged}
-              days={days}
+              days={chartDays}
+              daily={chartTotals}
               metric={metric}
               onMetricChange={setMetric}
               sinceDay={window.sinceDay}
               untilDay={window.untilDay}
+              isPast24Hours={isPast24Hours}
+              timeZone={window.timeZone}
             />
             <ProviderSection merged={merged} metric={metric} />
-            <TotalsSection merged={merged} />
+            <TotalsSection merged={merged} isPast24Hours={isPast24Hours} />
             <ModelsSection merged={merged} />
           </>
         )}
@@ -142,14 +187,17 @@ function SegmentedControl<Value extends number | string>(props: {
 function ChartCard(props: {
   readonly merged: MergedUsage;
   readonly days: readonly string[];
+  readonly daily: readonly DailyTotals[];
   readonly metric: UsageChartMetric;
   readonly onMetricChange: (metric: UsageChartMetric) => void;
   readonly sinceDay: string;
   readonly untilDay: string;
+  readonly isPast24Hours: boolean;
+  readonly timeZone: string;
 }) {
   const { merged, metric } = props;
   const colors = useProviderColors();
-  const hasActivity = merged.daily.some((day) => day.totalTokens > 0);
+  const hasActivity = props.daily.some((period) => period.totalTokens > 0);
 
   return (
     <View className="gap-4 rounded-[24px] border-continuous bg-card p-4">
@@ -173,7 +221,7 @@ function ChartCard(props: {
       {hasActivity ? (
         <UsageDailyChart
           days={props.days}
-          daily={merged.daily}
+          daily={props.daily}
           metric={metric}
           height={CHART_HEIGHT}
         />
@@ -184,7 +232,11 @@ function ChartCard(props: {
       )}
 
       <View className="flex-row items-center justify-between">
-        <Text className="text-xs text-foreground-tertiary">{formatDayShort(props.sinceDay)}</Text>
+        <Text className="text-xs text-foreground-tertiary">
+          {props.isPast24Hours
+            ? formatHourShort(props.days[0] ?? "", props.timeZone)
+            : formatDayShort(props.sinceDay)}
+        </Text>
         <View className="flex-row items-center gap-4">
           {merged.providers.map((provider) => (
             <View key={provider.provider} className="flex-row items-center gap-1.5">
@@ -198,7 +250,11 @@ function ChartCard(props: {
             </View>
           ))}
         </View>
-        <Text className="text-xs text-foreground-tertiary">{formatDayShort(props.untilDay)}</Text>
+        <Text className="text-xs text-foreground-tertiary">
+          {props.isPast24Hours
+            ? formatHourShort(props.days[props.days.length - 1] ?? "", props.timeZone)
+            : formatDayShort(props.untilDay)}
+        </Text>
       </View>
     </View>
   );
@@ -292,10 +348,12 @@ function ProviderSection(props: {
   );
 }
 
-function TotalsSection(props: { readonly merged: MergedUsage }) {
+function TotalsSection(props: { readonly merged: MergedUsage; readonly isPast24Hours: boolean }) {
   const { merged } = props;
-  const activeDays = merged.daily.filter((day) => day.totalTokens > 0).length;
-  const dailyAverage = activeDays === 0 ? 0 : merged.totalTokens / activeDays;
+  const activePeriods = (props.isPast24Hours ? merged.hourly : merged.daily).filter(
+    (period) => period.totalTokens > 0,
+  ).length;
+  const periodAverage = activePeriods === 0 ? 0 : merged.totalTokens / activePeriods;
   const observedInput = merged.uncachedInputTokens + merged.cachedInputTokens;
   const cachedShare = observedInput === 0 ? 0 : merged.cachedInputTokens / observedInput;
 
@@ -305,7 +363,7 @@ function TotalsSection(props: { readonly merged: MergedUsage }) {
         <MetricCell
           label="Processed tokens"
           value={formatTokens(merged.totalTokens)}
-          detail={`${formatTokens(dailyAverage)} per active day`}
+          detail={`${formatTokens(periodAverage)} per active ${props.isPast24Hours ? "hour" : "day"}`}
         />
         <MetricCell
           label="Cache savings"

apps/mobile/src/state/usage.ts

@@ -81,8 +81,18 @@ export function useUsage(input: UsageSummaryInput): UsageView {
         sinceDay: input.sinceDay,
         untilDay: input.untilDay,
         timeZone: input.timeZone,
+        resolution: input.resolution,
+        sinceTime: input.sinceTime,
+        untilTime: input.untilTime,
       }),
-    [input.sinceDay, input.untilDay, input.timeZone],
+    [
+      input.sinceDay,
+      input.untilDay,
+      input.timeZone,
+      input.resolution,
+      input.sinceTime,
+      input.untilTime,
+    ],
   );
   const atom = usageByWindowAtom(windowKey);
   const environments = useAtomValue(atom);

apps/server/src/usage/UsageService.ts

@@ -1,5 +1,5 @@
 /**
- * UsageService - scans provider transcripts and returns priced daily usage.
+ * UsageService - scans provider transcripts and returns priced usage buckets.
  *
  * The scan reads the provider CLIs' own session files rather than T3 Code's
  * orchestration projections, so usage covers turns driven outside T3 Code too.
@@ -64,6 +64,7 @@ const RATES_TTL_MS = 24 * 60 * 60 * 1000;
  * last write lands just before local midnight on the window's first day.
  */
 const MTIME_SLACK_MS = 36 * 60 * 60 * 1000;
+const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000;
 
 /** Longest window the UI offers, plus slack. Older entries are pruned. */
 const CACHE_RETENTION_DAYS = 90;
@@ -297,6 +298,30 @@ export const make = Effect.gen(function* () {
       });
     }
 
+    let hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null = null;
+    if (input.resolution === "hour") {
+      const sinceTime =
+        input.sinceTime === undefined ? Option.none() : DateTime.make(input.sinceTime);
+      const untilTime =
+        input.untilTime === undefined ? Option.none() : DateTime.make(input.untilTime);
+      if (Option.isNone(sinceTime) || Option.isNone(untilTime)) {
+        return yield* new UsageReadError({
+          reason: "invalidWindow",
+          detail: "Hourly usage requires valid sinceTime and untilTime instants",
+        });
+      }
+      const sinceTimeMs = DateTime.toEpochMillis(sinceTime.value);
+      const untilTimeMs = DateTime.toEpochMillis(untilTime.value);
+      const durationMs = untilTimeMs - sinceTimeMs;
+      if (durationMs <= 0 || durationMs > MAX_HOURLY_WINDOW_MS) {
+        return yield* new UsageReadError({
+          reason: "invalidWindow",
+          detail: "Hourly usage window must be greater than zero and at most 24 hours",
+        });
+      }
+      hourlyWindow = { sinceTimeMs, untilTimeMs };
+    }
+
     const startedAtMs = yield* Clock.currentTimeMillis;
     yield* ensureRates();
     yield* ensureScanCacheLoaded;
@@ -312,12 +337,15 @@ export const make = Effect.gen(function* () {
         detail: `sinceDay '${input.sinceDay}' is not a valid date`,
       });
     }
-    const windowStartMs = DateTime.toEpochMillis(windowStart.value) - MTIME_SLACK_MS;
+    const windowStartMs =
+      (hourlyWindow?.sinceTimeMs ?? DateTime.toEpochMillis(windowStart.value)) - MTIME_SLACK_MS;
 
     const aggregator = new UsageAggregator({
       timeZone: input.timeZone,
       sinceDay: input.sinceDay,
       untilDay: input.untilDay,
+      resolution: input.resolution ?? "day",
+      ...hourlyWindow,
       rates,
     });
 

apps/server/src/usage/usageAggregation.test.ts

@@ -36,18 +36,44 @@ function record(overrides: Partial<UsageRecord> = {}): UsageRecord {
   };
 }
 
-function aggregate(records: readonly UsageRecord[], timeZone = "UTC") {
+function aggregate(
+  records: readonly UsageRecord[],
+  timeZone = "UTC",
+  resolution: "day" | "hour" = "day",
+) {
+  const hourlyBounds =
+    resolution === "hour"
+      ? {
+          sinceTimeMs: Date.parse("2026-08-06T04:37:00.000Z"),
+          untilTimeMs: Date.parse("2026-08-07T04:37:00.000Z"),
+        }
+      : {};
   const aggregator = new UsageAggregator({
     timeZone,
     sinceDay: "2026-08-01",
     untilDay: "2026-08-31",
+    resolution,
+    ...hourlyBounds,
     rates,
   });
   for (const item of records) aggregator.add(item);
   return aggregator.finish();
 }
 
 describe("UsageAggregator", () => {
+  it("requires exact bounds for hourly aggregation", () => {
+    expect(
+      () =>
+        new UsageAggregator({
+          timeZone: "UTC",
+          sinceDay: "2026-08-01",
+          untilDay: "2026-08-31",
+          resolution: "hour",
+          rates,
+        }),
+    ).toThrow("requires exact time bounds");
+  });
+
   it("keeps only the first record for a repeated dedupe key", () => {
     const result = aggregate([
       record({ dedupeKey: "msg_1:" }),
@@ -76,6 +102,52 @@ describe("UsageAggregator", () => {
     expect(losAngeles.buckets[0]?.day).toBe("2026-08-06");
   });
 
+  it("splits an hourly request into fixed buckets anchored to its exact start", () => {
+    const result = aggregate(
+      [
+        record({ timestampMs: Date.parse("2026-08-07T02:40:13.944Z") }),
+        record({ timestampMs: Date.parse("2026-08-07T03:40:13.944Z") }),
+      ],
+      "America/Los_Angeles",
+      "hour",
+    );
+
+    expect(result.buckets.map((bucket) => [bucket.day, bucket.hourStart])).toEqual([
+      ["2026-08-06", "2026-08-07T02:37:00.000Z"],
+      ["2026-08-06", "2026-08-07T03:37:00.000Z"],
+    ]);
+  });
+
+  it("uses an inclusive start and exclusive end for rolling windows", () => {
+    const result = aggregate(
+      [
+        record({ timestampMs: Date.parse("2026-08-06T04:36:59.999Z") }),
+        record({ timestampMs: Date.parse("2026-08-06T04:37:00.000Z") }),
+        record({ timestampMs: Date.parse("2026-08-07T04:36:59.999Z") }),
+        record({ timestampMs: Date.parse("2026-08-07T04:37:00.000Z") }),
+      ],
+      "UTC",
+      "hour",
+    );
+
+    expect(result.outOfWindow).toBe(2);
+    expect(result.buckets.map((bucket) => bucket.hourStart)).toEqual([
+      "2026-08-06T04:37:00.000Z",
+      "2026-08-07T03:37:00.000Z",
+    ]);
+  });
+
+  it("keeps daily payloads collapsed when hourly resolution is not requested", () => {
+    const result = aggregate([
+      record({ timestampMs: Date.parse("2026-08-07T04:05:13.944Z") }),
+      record({ timestampMs: Date.parse("2026-08-07T05:05:13.944Z") }),
+    ]);
+
+    expect(result.buckets).toHaveLength(1);
+    expect(result.buckets[0]?.hourStart).toBeUndefined();
+    expect(result.buckets[0]?.records).toBe(2);
+  });
+
   it("prices against the rate table", () => {
     const result = aggregate([record()]);