feat(usage): report usage and limits for the provider you actually run

apps/server/src/usage/usageAggregation.ts

@@ -187,6 +187,7 @@ export class UsageAggregator {
     readonly day: string;
     readonly hourIndex: number;
     readonly provider: string;
+    readonly upstreamProvider: string;
     readonly model: string;
     readonly source: string;
     readonly bucket: MutableBucket;
@@ -255,7 +256,14 @@ export class UsageAggregator {
       this.#hourlyWindow === null
         ? -1
         : Math.floor((record.timestampMs - this.#hourlyWindow.sinceTimeMs) / HOUR_MS);
-    return this.#bucketFor(day, hourIndex, record.provider, record.model, source);
+    return this.#bucketFor(
+      day,
+      hourIndex,
+      record.provider,
+      record.upstreamProvider ?? "",
+      record.model,
+      source,
+    );
   }
 
   #accumulate(bucket: MutableBucket, record: UsageRecord): void {
@@ -314,6 +322,7 @@ export class UsageAggregator {
     day: string,
     hourIndex: number,
     provider: string,
+    upstreamProvider: string,
     model: string,
     source: string,
   ): MutableBucket {
@@ -323,6 +332,7 @@ export class UsageAggregator {
       last.day === day &&
       last.hourIndex === hourIndex &&
       last.provider === provider &&
+      last.upstreamProvider === upstreamProvider &&
       last.model === model &&
       last.source === source
     ) {
@@ -331,7 +341,7 @@ export class UsageAggregator {
     const window = this.#hourlyWindow;
     const hourStart =
       window === null ? "" : new Date(window.sinceTimeMs + hourIndex * HOUR_MS).toISOString();
-    const key = `${day}\u0000${hourStart}\u0000${provider}\u0000${model}\u0000${source}`;
+    const key = `${day}\u0000${hourStart}\u0000${provider}\u0000${upstreamProvider}\u0000${model}\u0000${source}`;
     let bucket = this.#buckets.get(key);
     if (bucket === undefined) {
       bucket = {
@@ -350,7 +360,7 @@ export class UsageAggregator {
       };
       this.#buckets.set(key, bucket);
     }
-    this.#lastBucket = { day, hourIndex, provider, model, source, bucket };
+    this.#lastBucket = { day, hourIndex, provider, upstreamProvider, model, source, bucket };
     return bucket;
   }
 
@@ -361,8 +371,14 @@ export class UsageAggregator {
     this.#seen.clear();
     const buckets: UsageBucket[] = [];
     for (const [key, bucket] of this.#buckets) {
-      const [day = "", hourStart = "", provider = "", model = "", sourcePath = ""] =
-        key.split("\u0000");
+      const [
+        day = "",
+        hourStart = "",
+        provider = "",
+        upstreamProvider = "",
+        model = "",
+        sourcePath = "",
+      ] = key.split("\u0000");
       const category = bucket.categoryCostUsd;
       const fastCostUsd = roundUsd(bucket.fastCostUsd);
       const ultrafastCostUsd = roundUsd(bucket.ultrafastCostUsd);
@@ -372,6 +388,7 @@ export class UsageAggregator {
         ...(hourStart === "" ? {} : { hourStart }),
         provider: provider as UsageBucket["provider"],
         model,
+        ...(upstreamProvider === "" ? {} : { upstreamProvider }),
         ...(sourcePath === "" ? {} : { sourcePath }),
         totals: { ...bucket.totals },
         costUsd: bucket.costUsd,

apps/web/src/components/usage/UsageModelDialog.tsx

@@ -50,7 +50,10 @@ export function UsageModelDialog({
 }) {
   const usage = mergeAnsweredUsage(
     environments,
-    (bucket) => bucket.provider === model.provider && bucket.model === model.model,
+    (bucket) =>
+      bucket.provider === model.provider &&
+      bucket.model === model.model &&
+      bucket.upstreamProvider === model.upstreamProvider,
   );
   const providers = [model.provider];
   const presentation = PROVIDER_PRESENTATION[model.provider];
@@ -83,6 +86,7 @@ export function UsageModelDialog({
           </div>
           <DialogDescription>
             {presentation.label}
+            {model.upstreamProvider ? ` · ${model.upstreamProvider}` : ""}
             {costUnknown ? "" : ` · ${formatPercent(model.costShare)} of cost`}
           </DialogDescription>
         </DialogHeader>

apps/web/src/components/usage/UsagePage.tsx

@@ -159,7 +159,11 @@ function UsageModelDialogHost({
   const model =
     selectedKey === null
       ? undefined
-      : models.find((candidate) => `${candidate.provider}:${candidate.model}` === selectedKey);
+      : models.find(
+          (candidate) =>
+            `${candidate.provider}:${candidate.upstreamProvider ?? ""}:${candidate.model}` ===
+            selectedKey,
+        );
   if (model === undefined) return null;
   return (
     <UsageModelDialog
@@ -887,7 +891,7 @@ function UsageOverview({
                 </tr>
               ) : (
                 breakdownModels.map((model, index) => {
-                  const key = `${model.provider}:${model.model}`;
+                  const key = `${model.provider}:${model.upstreamProvider ?? ""}:${model.model}`;
                   const value = metric === "tokens" ? model.totalTokens : model.costUsd;
                   const hasBar = value > 0 && breakdownPeak > 0;
                   const share = modelShare(model, metric === "tokens" ? "tokens" : "cost");
@@ -909,6 +913,11 @@ function UsageOverview({
                         >
                           <ProviderMark provider={model.provider} className="size-3.5" />
                           {model.model}
+                          {model.upstreamProvider ? (
+                            <span className="text-xs text-muted-foreground">
+                              {model.upstreamProvider}
+                            </span>
+                          ) : null}
                         </button>
                         {hasBar ? (
                           <div aria-hidden className={cn("mt-1.5 h-0.5 max-w-48", rowFigures)}>

apps/web/src/state/usage.ts

@@ -98,14 +98,11 @@ export function mergeAnsweredUsage(
           {
             environmentId,
             label,
-            summary:
-              keepBucket === undefined
-                ? summary
-                : { ...summary, buckets: summary.buckets.filter(keepBucket) },
+            summary,
           },
         ],
   );
-  return mergeUsage(answered, USAGE_CONTRACT_VERSION);
+  return mergeUsage(answered, USAGE_CONTRACT_VERSION, keepBucket);
 }
 
 const NO_HIDDEN_PROVIDERS: ReadonlySet<UsageProviderKind> = new Set();

docs/user/usage.md

@@ -14,6 +14,8 @@ cost, split by token type and by speed. These estimates are not your subscriptio
 **Premium** is what Fast and Ultrafast requests cost above standard rates. Cost that cannot be
 split, such as a provider-reported cost for a model without public rates, shows as **Other**.
 Select a model under **Breakdown** to see its trend, cache hit rate, and cost per million tokens.
+An OpenCode model shows the upstream that served it, so the same model billed by OpenCode Go and
+by another provider is listed separately.
 
 Totals depend on the history available on each server. Grok turns without a saved completed-turn
 record are missing from the totals.
@@ -155,7 +157,12 @@ the environment. T3 cannot report limits for external OpenCode servers because t
 belong to the remote server. Limits need an OpenCode Go API key, or an OpenCode Console connected
 in OpenCode with an API key. A Console browser sign-in alone does not report them. You can also add
 your Go API key as `OPENCODE_API_KEY` in the OpenCode instance's **Environment variables**, then
-refresh provider status. Cursor reports
+refresh provider status.
+An OpenCode account on a MiniMax Token Plan reports that plan's interval and weekly allowance
+next to the Go budget. It needs its own key: sign in to OpenCode with the MiniMax Token Plan and
+store the plan key there. T3 reads the plan's quota only when OpenCode resolves that provider to
+MiniMax's own endpoint, so a provider pointed at another endpoint reports no plan limits.
+Cursor reports
 its monthly allowance, including separate Auto and API usage, for `CURSOR_AUTH_TOKEN` when it is set,
 otherwise for the account you signed in with in T3 or set as `CURSOR_API_KEY`.
 Sign-in and API keys report limits only with Cursor's default API endpoint. If you configure a custom

packages/contracts/src/providerUsageLimits.ts

@@ -17,6 +17,8 @@ export const ServerProviderUsageWindow = Schema.Struct({
   /** When present, this limit applies only to these provider model IDs. */
   modelIds: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
   providerIds: Schema.optional(Schema.Array(TrimmedNonEmptyString)),
+  /** The credential that meters this window; a pool counts one credential once. */
+  credentialFingerprint: Schema.optional(TrimmedNonEmptyString),
   usedPercent: Schema.Number.check(Schema.isBetween({ minimum: 0, maximum: 100 })),
   resetsAt: Schema.optional(IsoDateTime),
   windowDurationMins: Schema.optional(NonNegativeInt),

packages/contracts/src/usage.ts

@@ -3,7 +3,7 @@ import * as Schema from "effect/Schema";
 import { ForwardCompatibleArray, NonNegativeInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
 
 /** Bump for incompatible UsageSummary changes; skipped unknown array variants need no bump. */
-export const USAGE_CONTRACT_VERSION = 6 as const;
+export const USAGE_CONTRACT_VERSION = 7 as const;
 
 export const USAGE_MERGE_COMPATIBLE_SINCE = 4 as const;
 
@@ -55,6 +55,8 @@ export const UsageBucket = Schema.Struct({
   hourStart: Schema.optional(TrimmedNonEmptyString),
   provider: UsageProviderKind,
   model: TrimmedNonEmptyString,
+  /** The upstream integration that served the model, when the harness knows it. */
+  upstreamProvider: Schema.optional(TrimmedNonEmptyString),
   sourcePath: Schema.optional(TrimmedNonEmptyString),
   totals: UsageTokenTotals,
   costUsd: Schema.Number,

packages/provider-core/src/server/usage.ts

@@ -13,6 +13,13 @@ export type UsageSpeed = "standard" | "fast" | "ultrafast";
 
 export interface UsageRecord {
   readonly provider: UsageProviderKind;
+  /**
+   * The upstream integration that served the model, when the harness reports
+   * one. A provider harness can front several upstreams (OpenCode fronts
+   * OpenCode Go, Zen, MiniMax and others), and only this names which one a
+   * record belongs to.
+   */
+  readonly upstreamProvider?: string;
   readonly timestampMs: number;
   readonly model: string;
   readonly rateModel?: string;

packages/provider-opencode/src/server/driver.test.ts

@@ -88,14 +88,42 @@ const layer = Layer.mergeAll(
   Layer.succeed(OpenCodeRuntime.OpenCodeRuntime, openCode2Runtime),
 ).pipe(Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)));
 
-const create = (config: Partial<OpenCodeSettings>, http: HttpClient.HttpClient, enabled = true) =>
-  OpenCodeDriver.create({
-    instanceId: ProviderInstanceId.make("opencode-test"),
-    displayName: undefined,
-    environment: [],
-    enabled,
-    config: { ...OpenCodeDriver.defaultConfig(), ...config },
-  }).pipe(Effect.provideService(HttpClient.HttpClient, http));
+/**
+ * Keeps the provider from reading the developer's own OpenCode store: the
+ * quota probe would send those credentials to the provider's API.
+ */
+const sandboxStore = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-opencode-driver-home-" });
+  return [
+    { name: "HOME", value: home, sensitive: false },
+    { name: "XDG_DATA_HOME", value: home, sensitive: false },
+  ];
+});
+
+const create = (
+  config: Partial<OpenCodeSettings>,
+  http: HttpClient.HttpClient,
+  options: {
+    readonly enabled?: boolean;
+    readonly environment?: NodeJS.ProcessEnv;
+  } = {},
+) =>
+  Effect.gen(function* () {
+    const sandbox = yield* sandboxStore;
+    return yield* OpenCodeDriver.create({
+      instanceId: ProviderInstanceId.make("opencode-test"),
+      displayName: undefined,
+      environment: [
+        ...sandbox,
+        ...Object.entries(options.environment ?? {}).flatMap(([name, value]) =>
+          value === undefined ? [] : [{ name, value, sensitive: false }],
+        ),
+      ],
+      enabled: options.enabled ?? true,
+      config: { ...OpenCodeDriver.defaultConfig(), ...config },
+    }).pipe(Effect.provideService(HttpClient.HttpClient, http));
+  });
 
 const noHttp = HttpClient.make(() => Effect.die("A local binary must not be probed over HTTP"));
 
@@ -219,7 +247,7 @@ it.live("discovers models through a home-relative OpenCode wrapper", () =>
     const instance = yield* OpenCodeDriver.create({
       instanceId: ProviderInstanceId.make("opencode-home"),
       displayName: undefined,
-      environment: [],
+      environment: yield* sandboxStore,
       enabled: true,
       config: {
         ...OpenCodeDriver.defaultConfig(),
@@ -326,9 +354,9 @@ it.layer(layer)("OpenCodeDriver runtime selection", (it) => {
             return { stdout: "opencode v2.1.2\n", stderr: "", code: 0 };
           }),
       } as OpenCodeRuntime.OpenCodeRuntime["Service"];
-      const instance = yield* create({ serverUrl: "http://127.0.0.1:4096" }, noHttp, false).pipe(
-        Effect.provideService(OpenCodeRuntime.OpenCodeRuntime, runtime),
-      );
+      const instance = yield* create({ serverUrl: "http://127.0.0.1:4096" }, noHttp, {
+        enabled: false,
+      }).pipe(Effect.provideService(OpenCodeRuntime.OpenCodeRuntime, runtime));
 
       const snapshot = yield* instance.snapshot.refresh;
       assert.isFalse(snapshot.enabled);
@@ -970,6 +998,7 @@ it.layer(layer)("OpenCodeDriver runtime selection", (it) => {
         instanceId: ProviderInstanceId.make("opencode-usage-recovery"),
         displayName: undefined,
         environment: [
+          ...(yield* sandboxStore),
           {
             name: "OPENCODE_AUTH_CONTENT",
             sensitive: true,
@@ -1244,7 +1273,7 @@ it.layer(layerUpdate)("OpenCodeDriver updates", (it) => {
         const instance = yield* OpenCodeDriver.create({
           instanceId: ProviderInstanceId.make("opencode-update"),
           displayName: undefined,
-          environment: [],
+          environment: yield* sandboxStore,
           enabled: true,
           config: { ...OpenCodeDriver.defaultConfig(), binaryPath },
         }).pipe(Effect.provideService(HttpClient.HttpClient, noHttp));

packages/provider-opencode/src/server/driver.ts

 checkUsageLimits, 
 checkUsageLimits, 
@@ -33,7 +33,11 @@ import type * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAda
 import type { ProviderTextGeneration } from "@t3tools/provider-core/server/textGeneration";
 import { ProviderDriverError } from "@t3tools/provider-core/server/errors";
 import { openCodeUsageReader, type OpenCodeUsageReaderEnv } from "./usage.ts";
-import { readOpenCodeGoUsageLimits } from "./usageLimits.ts";
+import {
+  mergeUsageLimits,
+  readOpenCodeGoUsageLimits,
+  readOpenCodeIntegrationUsageLimits,
+} from "./usageLimits.ts";
 import { loadOpenCode2Catalog, loadOpenCode2DirectoryCatalog } from "./openCode2Catalog.ts";
 import {
   checkOpenCodeProviderStatus,
@@ -58,6 +62,7 @@ import {
 } from "./versionProbe.ts";
 import * as OpenCodeServerOwner from "./OpenCodeServerOwner.ts";
 import * as OpenCode2Client from "./v2/OpenCode2Client.ts";
+import { readProviderEndpoints } from "./v2/providerEndpoints.ts";
 import * as OpenCode2Server from "./v2/OpenCode2Server.ts";
 import { replaceOutdatedService } from "./v2/OpenCode2Service.ts";
 import {
@@ -474,7 +479,7 @@ export const OpenCodeDriver: ProviderDriver<
       Effect.provideService(Digest.Digest, digest),
     );
     let unsupportedUsageVersion: string | undefined;
-    const checkUsageLimits = Effect.gen(function* () {
+    const checkConsoleUsageLimits = Effect.gen(function* () {
       if (!effectiveConfig.enabled) return yield* legacyUsageLimits;
       const runtime = yield* runtimeProbe.get;
       if (runtime.generation === "v1" || runtime.version === unsupportedUsageVersion)
@@ -497,6 +502,36 @@ export const OpenCodeDriver: ProviderDriver<
         })),
       ),
     );
+    // A custom provider meters its own plan, so its quota has to be read from
+    // that provider rather than from the OpenCode Console budget. The endpoint
+    // OpenCode resolves for a provider says whose key a credential is, so it
+    // is read only for a provider that has a credential to check.
+    const checkIntegrationUsageLimits = readOpenCodeIntegrationUsageLimits({
+      enabled: effectiveConfig.enabled,
+      serverUrl: effectiveConfig.serverUrl,
+      environment: processEnv,
+      resolveEndpoint: (integrationId) =>
+        openCode2Server
+          .withConnection((connection) =>
+            readProviderEndpoints(connection, host.paths.cwd).pipe(
+              Effect.map((endpoints) => endpoints.get(integrationId)),
+            ),
+          )
+          .pipe(Effect.catchCause(() => Effect.undefined)),
+    }).pipe(
+      Effect.provideService(FileSystem.FileSystem, fileSystem),
+      Effect.provideService(Path.Path, pathService),
+      Effect.provideService(HttpClient.HttpClient, httpClient),
+      Effect.provideService(Digest.Digest, digest),
+    );
+    // One probe for the provider's limits, so the recovery that retries a
+    // failed read retries the Console budget and the integration quotas alike.
+    const checkUsageLimits = Effect.zipWith(
+      checkConsoleUsageLimits,
+      checkIntegrationUsageLimits,
+      (usageLimits, integration) => mergeUsageLimits(usageLimits, integration),
+      { concurrent: true },
+    );
     const checkProvider = Effect.all(
       {
         // A configured loopback server reports its running version. Probe the local