@devries-cameron20 / t3code-1 / commits / e6e2ab05cc
Fork 0

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 }