Skip to content

Commit e6e2ab0

Browse files
t3dotggclaude
andauthored
feat(usage): filter Usage totals by provider and model (pingdotgg#28952)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent fa31b66 commit e6e2ab0

14 files changed

Lines changed: 307 additions & 15 deletions

File tree

‎apps/mobile/src/state/usage.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ import {
66
type UsageSummary,
77
type UsageSummaryInput,
88
} from "@t3tools/contracts";
9-
import { needsCursorKeychainAccess, refreshUsage } from "@t3tools/client-runtime/state/usage";
9+
import {
10+
needsCursorKeychainAccess,
11+
refreshUsage,
12+
usageSummaryInput,
13+
} from "@t3tools/client-runtime/state/usage";
1014
import { resolveUsageAccess } from "@t3tools/client-runtime/state/usage-access";
1115
import { mergeUsage, type EnvironmentUsage, type MergedUsage } from "@t3tools/shared/usageMerge";
1216
import { AsyncResult, Atom } from "effect/reactivity";
@@ -52,7 +56,15 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
5256
});
5357
continue;
5458
}
55-
const result = get(serverEnvironment.usageSummary({ environmentId, input }));
59+
const result = get(
60+
serverEnvironment.usageSummary({
61+
environmentId,
62+
input: usageSummaryInput(
63+
input,
64+
get(serverEnvironment.usageModelFilterAtom(environmentId)),
65+
),
66+
}),
67+
);
5668
const summary = AsyncResult.getOrElse(result, () => null);
5769
statuses.push({
5870
environmentId,

‎apps/server/src/usage/UsageService.test.ts‎

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,12 +67,17 @@ const encodeUnknownJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unkno
6767
const encodeUnknownJsonString = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
6868
const decodeUnknownJsonString = Schema.decodeSync(Schema.fromJsonString(Schema.Unknown));
6969

70-
function claudeLine(id: number, outputTokens: number, model = "claude-fable-5"): string {
70+
function claudeLine(
71+
id: number,
72+
outputTokens: number,
73+
model = "claude-fable-5",
74+
sessionId = "session-1",
75+
): string {
7176
return `${JSON.stringify({
7277
type: "assistant",
7378
timestamp: "2026-08-01T10:00:00Z",
7479
requestId: `req_${id}`,
75-
sessionId: "session-1",
80+
sessionId,
7681
message: {
7782
id: `msg_${id}`,
7883
model,
@@ -2077,6 +2082,111 @@ describe("UsageService", () => {
20772082
}).pipe(Effect.scoped),
20782083
);
20792084

2085+
it.live("filters original model IDs before aliases, pricing, buckets and session counts", () =>
2086+
Effect.gen(function* () {
2087+
const { transcript, settings, home } = yield* setup;
2088+
yield* Effect.promise(() =>
2089+
NodeFSP.writeFile(
2090+
transcript,
2091+
claudeLine(1, 3, "orbit-1", "mixed") +
2092+
claudeLine(2, 5, "orbit-2", "mixed") +
2093+
claudeLine(3, 7, "drift-9", "mixed") +
2094+
claudeLine(4, 11, "drift-9", "excluded-only"),
2095+
),
2096+
);
2097+
const rates = {
2098+
"orbit-1": { input_cost_per_token: 0.000001, output_cost_per_token: 0.00001 },
2099+
"orbit-2": { input_cost_per_token: 0.000002, output_cost_per_token: 0.00002 },
2100+
};
2101+
const include = {
2102+
// The codex selector must not match the Claude drift-9 records.
2103+
include: [
2104+
{ provider: "claude", model: "orbit-1" },
2105+
{ model: "orbit-2" },
2106+
{ provider: "codex", model: "drift-9" },
2107+
],
2108+
};
2109+
const exclude = { exclude: [{ model: "drift-9" }] };
2110+
const HOURLY: UsageSummaryInput = {
2111+
...WINDOW,
2112+
resolution: "hour",
2113+
sinceTime: "2026-08-01T09:00:00Z",
2114+
untilTime: "2026-08-01T11:00:00Z",
2115+
};
2116+
const cells = (summary: UsageSummary) =>
2117+
summary.buckets.map(({ model, totals, costUsd, records, sessions }) => ({
2118+
model,
2119+
outputTokens: totals.outputTokens,
2120+
costUsd: Math.round(costUsd * 1e6),
2121+
records,
2122+
sessions,
2123+
}));
2124+
2125+
yield* Effect.gen(function* () {
2126+
const service = yield* UsageService.make;
2127+
// Same service, concurrent reads: the in-flight key must keep these scans apart.
2128+
const [unfiltered, noOp, keepNothing, included, reordered, excluded, hourly] =
2129+
yield* Effect.all(
2130+
[
2131+
service.readSummary(WINDOW),
2132+
service.readSummary({ ...WINDOW, modelFilter: { exclude: [] } }),
2133+
service.readSummary({ ...WINDOW, modelFilter: { include: [] } }),
2134+
service.readSummary({ ...WINDOW, modelFilter: include }),
2135+
service.readSummary({
2136+
...WINDOW,
2137+
modelFilter: { include: [...include.include].reverse() },
2138+
}),
2139+
service.readSummary({ ...WINDOW, modelFilter: exclude }),
2140+
service.readSummary({ ...HOURLY, modelFilter: include }),
2141+
],
2142+
{ concurrency: "unbounded" },
2143+
);
2144+
2145+
// Unfiltered keeps today's behavior: the alias folds drift-9 into orbit-1.
2146+
assert.deepStrictEqual(cells(unfiltered), [
2147+
{ model: "orbit-1", outputTokens: 21, costUsd: 240, records: 3, sessions: 2 },
2148+
{ model: "orbit-2", outputTokens: 5, costUsd: 120, records: 1, sessions: 1 },
2149+
]);
2150+
assert.strictEqual(unfiltered.sources[0]?.distinctSessions, 2);
2151+
assert.strictEqual(unfiltered.modelFilter, undefined);
2152+
assert.strictEqual(noOp, unfiltered);
2153+
assert.deepStrictEqual(keepNothing.buckets, []);
2154+
assert.strictEqual(keepNothing.sources[0]?.distinctSessions, 0);
2155+
2156+
const kept = [
2157+
{ model: "orbit-1", outputTokens: 3, costUsd: 40, records: 1, sessions: 1 },
2158+
{ model: "orbit-2", outputTokens: 5, costUsd: 120, records: 1, sessions: 1 },
2159+
];
2160+
assert.deepStrictEqual(cells(included), kept);
2161+
assert.deepStrictEqual(cells(excluded), kept);
2162+
assert.deepStrictEqual(cells(hourly), kept);
2163+
assert.strictEqual(hourly.buckets[0]?.hourStart, "2026-08-01T10:00:00.000Z");
2164+
for (const summary of [included, excluded, hourly]) {
2165+
assert.strictEqual(summary.sources[0]?.distinctSessions, 1);
2166+
}
2167+
// Equal filters share one scan and echo one canonical form.
2168+
assert.strictEqual(reordered, included);
2169+
assert.deepStrictEqual(included.modelFilter, {
2170+
include: [
2171+
{ provider: "claude", model: "orbit-1" },
2172+
{ provider: "codex", model: "drift-9" },
2173+
{ model: "orbit-2" },
2174+
],
2175+
});
2176+
}).pipe(
2177+
Effect.scoped,
2178+
Effect.provide(
2179+
layerService({
2180+
prefix: "usage-service-model-filter-test",
2181+
home,
2182+
settings: { ...settings, usageModelAliases: { "drift-9": "orbit-1" } },
2183+
ratesDocument: rates,
2184+
}),
2185+
),
2186+
);
2187+
}).pipe(Effect.scoped),
2188+
);
2189+
20802190
it.live("reprices unchanged transcripts when custom prices are added, edited, or removed", () =>
20812191
Effect.gen(function* () {
20822192
const { transcript, settings, home } = yield* setup;

‎apps/server/src/usage/UsageService.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ import type {
3939
TranscriptUsageFormat,
4040
UsageRecord,
4141
} from "@t3tools/provider-core/server/usage";
42-
import { resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
42+
import { canonicalModelFilter, resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
4343
import { createOverrideRateTable, parseRateTable, type RateTable } from "./usagePricing.ts";
4444
import {
4545
listTranscriptFiles,
@@ -724,6 +724,7 @@ export const make = Effect.gen(function* () {
724724
rates,
725725
priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
726726
modelAliases: resolveModelAliases(settings.usageModelAliases),
727+
...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
727728
});
728729

729730
const sources: UsageSource[] = [];
@@ -882,6 +883,7 @@ export const make = Effect.gen(function* () {
882883
sources,
883884
pricing: pricing(),
884885
scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
886+
...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
885887
} satisfies UsageSummary;
886888
});
887889

@@ -897,9 +899,15 @@ export const make = Effect.gen(function* () {
897899
input.untilTime ?? null,
898900
settings,
899901
input.awaitRefresh === true,
902+
input.modelFilter ?? null,
900903
]);
901904

902-
const readSummary = Effect.fn("UsageService.readSummary")(function* (input: UsageSummaryInput) {
905+
const readSummary = Effect.fn("UsageService.readSummary")(function* (
906+
requested: UsageSummaryInput,
907+
) {
908+
const { modelFilter: requestedFilter, ...unfiltered } = requested;
909+
const modelFilter = canonicalModelFilter(requestedFilter);
910+
const input = modelFilter === undefined ? unfiltered : { ...unfiltered, modelFilter };
903911
const settings = yield* readSettings;
904912
const key = scanKey(input, settings);
905913
const deferred = yield* Effect.uninterruptible(

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ import type {
33
UsageBucket,
44
UsageCategoryCost,
55
UsageDay,
6+
UsageModelFilter,
7+
UsageModelSelector,
68
UsageResolution,
79
UsageTokenTotals,
810
} from "@t3tools/contracts";
@@ -67,6 +69,7 @@ export interface AggregateOptions {
6769
readonly rates: RateTable;
6870
readonly priceOverrides?: RateTable;
6971
readonly modelAliases?: ReadonlyMap<string, string>;
72+
readonly modelFilter?: UsageModelFilter;
7073
readonly resolution?: UsageResolution;
7174
readonly sinceTimeMs?: number;
7275
readonly untilTimeMs?: number;
@@ -88,6 +91,38 @@ export function resolveModelAliases(
8891
return resolved;
8992
}
9093

94+
/** Matches original IDs, so an alias cannot pull excluded usage into a kept model. */
95+
function keepsUsageRecord(filter: UsageModelFilter | undefined, record: UsageRecord): boolean {
96+
if (filter === undefined) return true;
97+
const model = record.model.trim();
98+
const matches = (selector: UsageModelSelector) =>
99+
selector.model === model &&
100+
(selector.provider === undefined || selector.provider === record.provider);
101+
return (filter.include?.some(matches) ?? true) && !(filter.exclude?.some(matches) ?? false);
102+
}
103+
104+
const selectorKey = (selector: UsageModelSelector) =>
105+
JSON.stringify([selector.provider ?? null, selector.model]);
106+
107+
const canonicalSelectors = (selectors: readonly UsageModelSelector[]) =>
108+
[...new Map(selectors.map((selector) => [selectorKey(selector), selector]))]
109+
// Code-unit order, so servers in different locales echo the same form.
110+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
111+
.map(([, selector]) => selector);
112+
113+
/** Equal filters get one form, so they share scans and clients can compare echoed filters. */
114+
export function canonicalModelFilter(
115+
filter: UsageModelFilter | undefined,
116+
): UsageModelFilter | undefined {
117+
if (filter === undefined) return undefined;
118+
const exclude = filter.exclude?.length ? canonicalSelectors(filter.exclude) : undefined;
119+
if (filter.include === undefined && exclude === undefined) return undefined;
120+
return {
121+
...(filter.include === undefined ? {} : { include: canonicalSelectors(filter.include) }),
122+
...(exclude === undefined ? {} : { exclude }),
123+
};
124+
}
125+
91126
export interface AggregateResult {
92127
readonly buckets: readonly UsageBucket[];
93128
readonly duplicatesDropped: number;
@@ -129,6 +164,7 @@ export class UsageAggregator {
129164
}
130165

131166
add(input: UsageRecord, sourcePath?: string): boolean {
167+
if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
132168
const record = this.#mapModel(input);
133169
if (record.dedupeKey !== null) {
134170
if (this.#seen.has(record.dedupeKey)) {

‎apps/web/src/state/usage.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,11 @@ import {
88
type UsageProviderKind,
99
type UsageSummaryInput,
1010
} from "@t3tools/contracts";
11-
import { needsCursorKeychainAccess, refreshUsage } from "@t3tools/client-runtime/state/usage";
11+
import {
12+
needsCursorKeychainAccess,
13+
refreshUsage,
14+
usageSummaryInput,
15+
} from "@t3tools/client-runtime/state/usage";
1216
import { resolveUsageAccess } from "@t3tools/client-runtime/state/usage-access";
1317
import { AsyncResult, Atom } from "effect/reactivity";
1418
import { useState } from "react";
@@ -55,7 +59,15 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
5559
});
5660
continue;
5761
}
58-
const result = get(serverEnvironment.usageSummary({ environmentId, input }));
62+
const result = get(
63+
serverEnvironment.usageSummary({
64+
environmentId,
65+
input: usageSummaryInput(
66+
input,
67+
get(serverEnvironment.usageModelFilterAtom(environmentId)),
68+
),
69+
}),
70+
);
5971
const summary = AsyncResult.getOrElse(result, () => null);
6072
statuses.push({
6173
environmentId,

‎docs/user/usage.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,30 @@ marked **Not saved**. Reconnect them and choose **Retry failed saves** to finish
8787
without writing again to environments that already saved. Changes are not queued after you close
8888
the dialog.
8989

90+
## Show only some models
91+
92+
To count only some models, or to leave some out, add `usageModelFilter` to the server's
93+
`settings.json` in its `userdata` directory, such as `~/.t3/userdata/settings.json`:
94+
95+
```json
96+
{
97+
"usageModelFilter": {
98+
"include": [{ "provider": "claude", "model": "orbit-1" }, { "model": "orbit-2" }],
99+
"exclude": [{ "model": "drift-9" }]
100+
}
101+
}
102+
```
103+
104+
`include` keeps only the listed models and `exclude` leaves the listed models out. `provider` is
105+
one of `claude`, `codex`, `cursor`, `grok`, `opencode`, `antigravity`, `pi`, or `muse`; omit it
106+
to match a model ID from any provider. Use the model ID that Usage shows without **Map to**, such
107+
as a provider-prefixed ID for Pi. Filters apply before **Map to**, so a model you leave out is not
108+
counted under its mapped name. Usage applies each environment's own filter. Remove the setting to
109+
show every model again.
110+
111+
If the setting is invalid, Usage ignores it and shows every model, and the next save of any other
112+
setting removes it from `settings.json`.
113+
90114
## Track subscription limits
91115

92116
**Usage → Limits** pools every subscription account it can see per provider, so with several Codex

‎packages/client-runtime/src/state/server.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1112,6 +1112,13 @@ export function createServerEnvironmentAtoms<R, E>(
11121112
]);
11131113
}).pipe(Atom.withLabel(`environment-data:server:usage-scan-settings:${environmentId}`)),
11141114
);
1115+
// Settings snapshots rebuild the filter object; only a changed filter should touch the Usage tab.
1116+
const usageModelFilterAtom = Atom.family((environmentId: EnvironmentId) =>
1117+
Atom.make((get) => get(settingsValueAtom(environmentId))?.usageModelFilter).pipe(
1118+
Atom.withEquality((a, b) => JSON.stringify(a) === JSON.stringify(b)),
1119+
Atom.withLabel(`environment-data:server:usage-model-filter:${environmentId}`),
1120+
),
1121+
);
11151122
const providersValueAtom = Atom.family((environmentId: EnvironmentId) =>
11161123
Atom.make((get) => get(configValueAtom(environmentId))?.providers ?? null).pipe(
11171124
Atom.withLabel(`environment-data:server:providers:${environmentId}`),
@@ -1194,6 +1201,7 @@ export function createServerEnvironmentAtoms<R, E>(
11941201
}),
11951202
updateStateAtom,
11961203
settingsValueAtom,
1204+
usageModelFilterAtom,
11971205
providersValueAtom,
11981206
providerAuthState: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
11991207
label: "environment-data:provider:auth-state",

0 commit comments

Comments
 (0)