The best way to control Claude Code, Codex and more from any computer or phone
feat(usage): filter Usage totals by provider and model (#28952)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Nov 1, 2026 at 16:50 UTC
e6e2ab05cceb3f8245e87f8499d4891f27de33cb
14 files changed
+307
-15
apps/mobile/src/state/usage.ts
+14
-2
@@ -6,7 +6,11 @@ import {
6
type UsageSummary,
7
type UsageSummaryInput,
8
} 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";
14
import { resolveUsageAccess } from "@t3tools/client-runtime/state/usage-access";
15
import { mergeUsage, type EnvironmentUsage, type MergedUsage } from "@t3tools/shared/usageMerge";
16
import { AsyncResult, Atom } from "effect/reactivity";
@@ -52,7 +56,15 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
56
});
57
continue;
58
}
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
+ );
68
const summary = AsyncResult.getOrElse(result, () => null);
69
statuses.push({
70
environmentId,
apps/server/src/usage/UsageService.test.ts
+112
-2
@@ -67,12 +67,17 @@ const encodeUnknownJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unkno
67
const encodeUnknownJsonString = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
68
const decodeUnknownJsonString = Schema.decodeSync(Schema.fromJsonString(Schema.Unknown));
69
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 {
76
return `${JSON.stringify({
77
type: "assistant",
78
timestamp: "2026-08-01T10:00:00Z",
79
requestId: `req_${id}`,
75
- sessionId: "session-1",
80
+ sessionId,
81
message: {
82
id: `msg_${id}`,
83
model,
@@ -2077,6 +2082,111 @@ describe("UsageService", () => {
2082
}).pipe(Effect.scoped),
2083
);
2084
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
+
2190
it.live("reprices unchanged transcripts when custom prices are added, edited, or removed", () =>
2191
Effect.gen(function* () {
2192
const { transcript, settings, home } = yield* setup;
apps/server/src/usage/UsageService.ts
+10
-2
@@ -39,7 +39,7 @@ import type {
39
TranscriptUsageFormat,
40
UsageRecord,
41
} from "@t3tools/provider-core/server/usage";
42
-import { resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
42
+import { canonicalModelFilter, resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
43
import { createOverrideRateTable, parseRateTable, type RateTable } from "./usagePricing.ts";
44
import {
45
listTranscriptFiles,
@@ -724,6 +724,7 @@ export const make = Effect.gen(function* () {
724
rates,
725
priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
726
modelAliases: resolveModelAliases(settings.usageModelAliases),
727
+ ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
728
});
729
730
const sources: UsageSource[] = [];
@@ -882,6 +883,7 @@ export const make = Effect.gen(function* () {
883
sources,
884
pricing: pricing(),
885
scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
886
+ ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
887
} satisfies UsageSummary;
888
});
889
@@ -897,9 +899,15 @@ export const make = Effect.gen(function* () {
899
input.untilTime ?? null,
900
settings,
901
input.awaitRefresh === true,
902
+ input.modelFilter ?? null,
903
]);
904
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 };
911
const settings = yield* readSettings;
912
const key = scanKey(input, settings);
913
const deferred = yield* Effect.uninterruptible(
apps/server/src/usage/usageAggregation.ts
+36
@@ -3,6 +3,8 @@ import type {
3
UsageBucket,
4
UsageCategoryCost,
5
UsageDay,
6
+ UsageModelFilter,
7
+ UsageModelSelector,
8
UsageResolution,
9
UsageTokenTotals,
10
} from "@t3tools/contracts";
@@ -67,6 +69,7 @@ export interface AggregateOptions {
69
readonly rates: RateTable;
70
readonly priceOverrides?: RateTable;
71
readonly modelAliases?: ReadonlyMap<string, string>;
72
+ readonly modelFilter?: UsageModelFilter;
73
readonly resolution?: UsageResolution;
74
readonly sinceTimeMs?: number;
75
readonly untilTimeMs?: number;
@@ -88,6 +91,38 @@ export function resolveModelAliases(
91
return resolved;
92
}
93
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
+
126
export interface AggregateResult {
127
readonly buckets: readonly UsageBucket[];
128
readonly duplicatesDropped: number;
@@ -129,6 +164,7 @@ export class UsageAggregator {
164
}
165
166
add(input: UsageRecord, sourcePath?: string): boolean {
167
+ if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
168
const record = this.#mapModel(input);
169
if (record.dedupeKey !== null) {
170
if (this.#seen.has(record.dedupeKey)) {
apps/web/src/state/usage.ts
+14
-2
@@ -8,7 +8,11 @@ import {
8
type UsageProviderKind,
9
type UsageSummaryInput,
10
} 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";
16
import { resolveUsageAccess } from "@t3tools/client-runtime/state/usage-access";
17
import { AsyncResult, Atom } from "effect/reactivity";
18
import { useState } from "react";
@@ -55,7 +59,15 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
59
});
60
continue;
61
}
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
+ );
71
const summary = AsyncResult.getOrElse(result, () => null);
72
statuses.push({
73
environmentId,
docs/user/usage.md
+24
@@ -87,6 +87,30 @@ marked **Not saved**. Reconnect them and choose **Retry failed saves** to finish
87
without writing again to environments that already saved. Changes are not queued after you close
88
the dialog.
89
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
+
114
## Track subscription limits
115
116
**Usage → Limits** pools every subscription account it can see per provider, so with several Codex
packages/client-runtime/src/state/server.ts
+8
@@ -1112,6 +1112,13 @@ export function createServerEnvironmentAtoms<R, E>(
1112
]);
1113
}).pipe(Atom.withLabel(`environment-data:server:usage-scan-settings:${environmentId}`)),
1114
);
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
+ );
1122
const providersValueAtom = Atom.family((environmentId: EnvironmentId) =>
1123
Atom.make((get) => get(configValueAtom(environmentId))?.providers ?? null).pipe(
1124
Atom.withLabel(`environment-data:server:providers:${environmentId}`),
@@ -1194,6 +1201,7 @@ export function createServerEnvironmentAtoms<R, E>(
1201
}),
1202
updateStateAtom,
1203
settingsValueAtom,
1204
+ usageModelFilterAtom,
1205
providersValueAtom,
1206
providerAuthState: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
1207
label: "environment-data:provider:auth-state",
packages/client-runtime/src/state/usage.test.ts
+28
-4
@@ -5,7 +5,9 @@ import {
5
UsageDay,
6
USAGE_CONTRACT_VERSION,
7
type ServerProvider,
8
+ type UsageModelFilter,
9
type UsageSummary,
10
+ type UsageSummaryInput,
11
} from "@t3tools/contracts";
12
import * as Effect from "effect/Effect";
13
import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
@@ -39,7 +41,7 @@ afterEach(() => {
41
for (const registry of registries.splice(0)) registry.dispose();
42
});
43
42
-function harness(ids = ["a"]) {
44
+function harness(ids = ["a"], modelFilters: Record<string, UsageModelFilter> = {}) {
45
const registry = AtomRegistry.make();
46
registries.push(registry);
47
const environments = ids.map((id) => {
@@ -65,13 +67,18 @@ function harness(ids = ["a"]) {
67
if (!environment) throw new Error(`Unknown environment: ${environmentId}`);
68
return environment;
69
}
70
+ const requested: { environmentId: EnvironmentId; input: UsageSummaryInput }[] = [];
71
const options = {
72
registry,
73
environmentIds: environments.map((entry) => entry.environmentId),
74
input,
75
server: {
73
- usageSummary: ({ environmentId }: { environmentId: EnvironmentId }) =>
74
- get(environmentId).query,
76
+ usageSummary: (target: { environmentId: EnvironmentId; input: UsageSummaryInput }) => {
77
+ requested.push(target);
78
+ return get(target.environmentId).query;
79
+ },
80
+ usageModelFilterAtom: (environmentId: EnvironmentId) =>
81
+ Atom.make<UsageModelFilter | undefined>(modelFilters[environmentId]),
82
refreshUsageRates: {
83
label: "test:rates",
84
requiredScopes: () => [],
@@ -86,7 +93,7 @@ function harness(ids = ["a"]) {
93
presentationAtom: (environmentId: EnvironmentId) => get(environmentId).presentation,
94
},
95
} satisfies Parameters<typeof refreshUsage>[0];
89
- return { registry, environments, refresh: () => refreshUsage(options) };
96
+ return { registry, environments, requested, refresh: () => refreshUsage(options) };
97
}
98
99
describe("manual usage refresh", () => {
@@ -113,6 +120,23 @@ describe("manual usage refresh", () => {
120
expect(finished).toBe(true);
121
});
122
123
+ it("rescans each environment with its own configured model filter", async () => {
124
+ const modelFilter = { include: [{ provider: "claude" as const, model: "orbit-1" }] };
125
+ const { environments, requested, refresh } = harness(["filtered", "plain"], {
126
+ filtered: modelFilter,
127
+ });
128
+ const refreshing = refresh();
129
+ for (const entry of environments) {
130
+ entry.rates.resolve(AsyncResult.success(pricing));
131
+ entry.scan.resolve(summary);
132
+ }
133
+ await refreshing;
134
+ expect(requested).toEqual([
135
+ { environmentId: "filtered", input: { ...input, modelFilter } },
136
+ { environmentId: "plain", input },
137
+ ]);
138
+ });
139
+
140
it("settles when an environment disconnects during the rescan", async () => {
141
const {
142
registry,
packages/client-runtime/src/state/usage.ts
+14
-2
@@ -1,6 +1,7 @@
1
import type {
2
EnvironmentId,
3
ServerProvider,
4
+ UsageModelFilter,
5
UsageSummary,
6
UsageSummaryInput,
7
} from "@t3tools/contracts";
@@ -43,6 +44,14 @@ export function cursorKeychainAccessEnvironments<
44
: environments.filter((environment) => environment.needsCursorKeychainAccess);
45
}
46
47
+/** The Usage tab asks each environment with that environment's configured model filter. */
48
+export function usageSummaryInput(
49
+ input: UsageSummaryInput,
50
+ modelFilter: UsageModelFilter | undefined,
51
+): UsageSummaryInput {
52
+ return modelFilter === undefined ? input : { ...input, modelFilter };
53
+}
54
+
55
const limitsRefreshAfter = new Map<EnvironmentId, number>();
56
const limitsRefreshes = new Map<EnvironmentId, Promise<unknown>>();
57
@@ -86,7 +95,7 @@ export async function refreshUsage({
95
registry: AtomRegistry.AtomRegistry;
96
server: Pick<
97
ReturnType<typeof createServerEnvironmentAtoms>,
89
- "usageSummary" | "refreshUsageRates"
98
+ "usageSummary" | "refreshUsageRates" | "usageModelFilterAtom"
99
>;
100
presentations: Pick<ReturnType<typeof createEnvironmentPresentationAtoms>, "presentationAtom">;
101
environmentIds: readonly EnvironmentId[];
@@ -94,7 +103,10 @@ export async function refreshUsage({
103
}): Promise<void> {
104
await Promise.all(
105
environmentIds.map(async (environmentId) => {
97
- const query = server.usageSummary({ environmentId, input });
106
+ const query = server.usageSummary({
107
+ environmentId,
108
+ input: usageSummaryInput(input, registry.get(server.usageModelFilterAtom(environmentId))),
109
+ });
110
const presentation = presentations.presentationAtom(environmentId);
111
const controller = new AbortController();
112
const abortWhenDisconnected = () => {
packages/contracts/src/settings.test.ts
+11
@@ -126,6 +126,17 @@ describe("ServerSettings usage price overrides", () => {
126
expect(() => decodeServerSettingsPatch({ usagePriceOverrides })).toThrow();
127
}
128
});
129
+
130
+ it("ignores an invalid model filter without dropping the other settings", () => {
131
+ const valid = { include: [{ provider: "newer-provider", model: "orbit-1" }] };
132
+ expect(decodeServerSettings({ usageModelFilter: valid }).usageModelFilter).toEqual(valid);
133
+ const settings = decodeServerSettings({
134
+ usageModelFilter: { exclude: [{ model: "" }] },
135
+ usageModelAliases: { "drift-9": "orbit-1" },
136
+ });
137
+ expect(settings.usageModelFilter).toBeUndefined();
138
+ expect(settings.usageModelAliases).toEqual({ "drift-9": "orbit-1" });
139
+ });
140
});
141
142
describe("ServerSettings secret providers", () => {
packages/contracts/src/settings.ts
+4
@@ -20,6 +20,7 @@ import {
20
TrimmedString,
21
} from "./baseSchemas.ts";
22
import { UsageLimitSourceId } from "./usageLimitSourceId.ts";
23
+import { UsageModelFilter } from "./usage.ts";
24
import { SecretProviderId, SecretProviderSlug } from "./secretReference.ts";
25
import { EnvironmentMachineKind, ThreadEnvMode, WorktreeSubmodules } from "./environment.ts";
26
import { KeybindingShortcut } from "./keybindings.ts";
@@ -1361,6 +1362,9 @@ export const ServerSettings = Schema.Struct({
1362
usageModelAliases: Schema.Record(TrimmedNonEmptyString, TrimmedNonEmptyString).pipe(
1363
Schema.withDecodingDefault(Effect.succeed({})),
1364
),
1365
+
1366
+ /** Sent by the Usage tab with each summary request to this environment; edit in settings.json. Invalid values are ignored. */
1367
+ usageModelFilter: ForwardCompatibleOptional(UsageModelFilter),
1368
});
1369
export type ServerSettings = typeof ServerSettings.Type;
1370
packages/contracts/src/usage.ts
+20
@@ -108,6 +108,23 @@ export const UsagePricing = Schema.Struct({
108
});
109
export type UsagePricing = typeof UsagePricing.Type;
110
111
+/**
112
+ * Matches a provider's original model ID, before usage model aliases apply. Omit provider to
113
+ * match any; a string provider lets older clients carry selectors for providers they lack.
114
+ */
115
+export const UsageModelSelector = Schema.Struct({
116
+ provider: Schema.optional(TrimmedNonEmptyString),
117
+ model: TrimmedNonEmptyString,
118
+});
119
+export type UsageModelSelector = typeof UsageModelSelector.Type;
120
+
121
+/** Keeps records matching `include` (all when omitted) and not matching `exclude`. */
122
+export const UsageModelFilter = Schema.Struct({
123
+ include: Schema.optional(Schema.Array(UsageModelSelector)),
124
+ exclude: Schema.optional(Schema.Array(UsageModelSelector)),
125
+});
126
+export type UsageModelFilter = typeof UsageModelFilter.Type;
127
+
128
export const UsageSummaryInput = Schema.Struct({
129
sinceDay: UsageDay,
130
untilDay: UsageDay,
@@ -117,6 +134,7 @@ export const UsageSummaryInput = Schema.Struct({
134
sinceTime: Schema.optional(TrimmedNonEmptyString),
135
untilTime: Schema.optional(TrimmedNonEmptyString),
136
awaitRefresh: Schema.optional(Schema.Boolean),
137
+ modelFilter: Schema.optional(UsageModelFilter),
138
});
139
export type UsageSummaryInput = typeof UsageSummaryInput.Type;
140
@@ -130,6 +148,8 @@ export const UsageSummary = Schema.Struct({
148
sources: ForwardCompatibleArray(UsageSource),
149
pricing: UsagePricing,
150
scanDurationMs: NonNegativeInt,
151
+ /** The filter the server applied; absent means unfiltered, including servers that predate filters. */
152
+ modelFilter: Schema.optional(UsageModelFilter),
153
});
154
export type UsageSummary = typeof UsageSummary.Type;
155
packages/shared/src/usageMerge.test.ts
+8
@@ -271,6 +271,14 @@ describe("mergeUsage", () => {
271
);
272
expect(merged.duplicateSources).toEqual(["new: /home/theo/.claude"]);
273
}
274
+
275
+ const filtered = environment("new", {
276
+ ...partial.summary,
277
+ modelFilter: { exclude: [{ model: "claude-fable-5" }] },
278
+ });
279
+ const merged = mergeUsage([complete, filtered], USAGE_CONTRACT_VERSION);
280
+ expect(merged.costUsd).toBe(10);
281
+ expect(merged.sessions).toBe(1);
282
});
283
284
it("retains a complete cell when a larger partial cell may have skipped old records", () => {
packages/shared/src/usageMerge.ts
+4
-1
@@ -178,9 +178,12 @@ function claimSources(environments: readonly EnvironmentUsage[]): {
178
if (source.status !== "partial") continue;
179
const key = fingerprintKey(source.fingerprint);
180
const owner = ownerScanByFingerprint.get(key);
181
+ // A scan under another model filter counts different records, so its cells are not missing ones.
182
if (
183
owner?.source.status !== "ok" ||
183
- Date.parse(environment.summary.readAt) <= Date.parse(owner.environment.summary.readAt)
184
+ Date.parse(environment.summary.readAt) <= Date.parse(owner.environment.summary.readAt) ||
185
+ JSON.stringify(environment.summary.modelFilter) !==
186
+ JSON.stringify(owner.environment.summary.modelFilter)
187
) {
188
continue;
189
}