diff --git a/docs/user/usage.md b/docs/user/usage.md index 5160becc21567..0fb69d3452019 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -166,7 +166,9 @@ refresh provider status. 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 -Cursor endpoint, use an explicit `CURSOR_AUTH_TOKEN` for limits. +Cursor endpoint, use an explicit `CURSOR_AUTH_TOKEN` for limits. Accounts without a monthly +allowance, such as Enterprise, show a **Spend** bar for this billing cycle against your personal +spend limit. If Cursor reports no personal limit, Usage links to Cursor's usage dashboard instead. Grok reports the remaining subscription allowance and reset time for its current billing period after signing in with `grok login`. Explicit `XAI_API_KEY` connections and custom authentication diff --git a/packages/provider-cursor/src/server/usageLimits.test.ts b/packages/provider-cursor/src/server/usageLimits.test.ts index e969106812e6e..9fc32f4878105 100644 --- a/packages/provider-cursor/src/server/usageLimits.test.ts +++ b/packages/provider-cursor/src/server/usageLimits.test.ts @@ -7,7 +7,7 @@ import { cursorUsageResponseToLimits, readCursorUsageLimits } from "./usageLimit describe("Cursor usage limits", () => { const checkedAt = "2026-09-16T00:00:00.000Z"; - it("uses the advertised percentages and billing-cycle reset", () => { + it("uses the advertised percentages and reset, or Spend when no allowance is included", () => { const limits = cursorUsageResponseToLimits( { billingCycleEnd: "1789876386000", @@ -40,6 +40,68 @@ describe("Cursor usage limits", () => { }, ]), ); + const withSpendLimit = cursorUsageResponseToLimits( + { + billingCycleEnd: "1789876386000", + planUsage: { totalPercentUsed: 72.4, autoPercentUsed: 69.5, apiPercentUsed: 100 }, + spendLimitUsage: { individualLimit: 5000, individualUsed: 100 }, + }, + checkedAt, + ); + expect(withSpendLimit.windows).toEqual(limits.windows); + const zeroPercents = { totalPercentUsed: 0, autoPercentUsed: 0, apiPercentUsed: 0 }; + const zeroPlanWindows = [ + { id: "apiPercentUsed", kind: "monthly", label: "Other Models", usedPercent: 0 }, + { id: "autoPercentUsed", kind: "monthly", label: "Cursor Models", usedPercent: 0 }, + { id: "totalPercentUsed", kind: "monthly", label: "Overall", usedPercent: 0 }, + ]; + const windowIds = (response: Parameters[0]) => + cursorUsageResponseToLimits(response, checkedAt).windows.map((window) => window.id); + // Usage already counted against a pooled plan keeps the plan bars. + expect( + windowIds({ + planUsage: { totalPercentUsed: 6, autoPercentUsed: 6, apiPercentUsed: 0 }, + spendLimitUsage: { pooledLimit: "3000000", overallLimit: 50000, overallUsed: 3211 }, + }), + ).toEqual(["apiPercentUsed", "autoPercentUsed", "totalPercentUsed"]); + // Fresh-cycle Pro: an included allowance, or no pool marker, keeps the plan bars. + for (const response of [ + { + planUsage: { ...zeroPercents, limit: "2000" }, + spendLimitUsage: { individualLimit: 5000, individualUsed: 0, pooledLimit: "3000000" }, + }, + { planUsage: zeroPercents, spendLimitUsage: { individualLimit: 5000 } }, + ]) { + expect(cursorUsageResponseToLimits(response, checkedAt).windows).toEqual(zeroPlanWindows); + } + expect( + windowIds({ + planUsage: { ...zeroPercents, limit: "0" }, + spendLimitUsage: { pooledLimit: "3000000", overallLimit: 50000, overallUsed: 3211 }, + }), + ).toEqual(["spendLimit"]); + // Without includePooledUsage, Cursor reports start = end = now instead of the cycle. + expect( + cursorUsageResponseToLimits( + { + billingCycleStart: "1793491200000", + billingCycleEnd: "1793491200000", + spendLimitUsage: { individualLimit: "2000", individualUsed: "500" }, + }, + checkedAt, + ).windows, + ).toEqual([{ id: "spendLimit", kind: "monthly", label: "Spend", usedPercent: 25 }]); + // Limit and used come from the same pair; protobuf JSON omits a zero used. + for (const [spendLimitUsage, usedPercent] of [ + [{ overallLimit: 50000, individualUsed: 3211 }, 0], + [{ overallLimit: 0, individualLimit: "2000", individualUsed: "500" }, 25], + ] as const) { + expect( + cursorUsageResponseToLimits({ spendLimitUsage }, checkedAt).windows.map( + (window) => window.usedPercent, + ), + ).toEqual([usedPercent]); + } }); it("reports the billing-cycle length so pace can be computed", () => { @@ -54,7 +116,7 @@ describe("Cursor usage limits", () => { }); it("omits the cycle length when the start is missing or invalid", () => { - for (const billingCycleStart of [undefined, "", "0", "not-a-number", "1796637847072"]) { + for (const billingCycleStart of [undefined, "", "0", "not-a-number"]) { expect( cursorUsageResponseToLimits( { @@ -91,9 +153,33 @@ describe("Cursor usage limits", () => { }); it("does not invent unused allowance for absent buckets", () => { - expect(cursorUsageResponseToLimits({ planUsage: {} }, checkedAt).unavailable?.reason).toBe( - "unsupported", + const linkOnly = { + checkedAt, + windows: [], + unavailable: { + reason: "unsupported", + message: + "Cursor doesn't report a personal spend limit for this account. Open Cursor's dashboard with the same account to see its usage.", + }, + externalUsage: { label: "Cursor usage", url: "https://cursor.com/dashboard?tab=usage" }, + }; + expect(cursorUsageResponseToLimits({ planUsage: {} }, checkedAt)).toEqual(linkOnly); + // Real Enterprise (token-based contract) response: no planUsage at all. + expect(cursorUsageResponseToLimits({ billingCycleEnd: "1793495876373" }, checkedAt)).toEqual( + linkOnly, ); + // Enterprise seat with only the team pool: zeroed percentages and no personal limit. + expect( + cursorUsageResponseToLimits( + { + billingCycleStart: "1793491200000", + billingCycleEnd: "1796083200000", + planUsage: { totalPercentUsed: 0, autoPercentUsed: 0, apiPercentUsed: 0 }, + spendLimitUsage: { pooledLimit: "3000000" }, + }, + checkedAt, + ), + ).toEqual(linkOnly); expect( cursorUsageResponseToLimits({ planUsage: { totalPercentUsed: 0 } }, checkedAt).windows, ).toEqual([{ id: "totalPercentUsed", kind: "monthly", label: "Overall", usedPercent: 0 }]); @@ -102,6 +188,59 @@ describe("Cursor usage limits", () => { ).toEqual([{ id: "totalPercentUsed", kind: "monthly", label: "Overall", usedPercent: 100 }]); }); + it.effect( + "requests pooled usage and shows Enterprise spend against the personal spend limit", + () => + Effect.gen(function* () { + const limits = yield* readCursorUsageLimits( + { apiEndpoint: "" }, + { CURSOR_AUTH_TOKEN: "token" }, + ).pipe( + Effect.provideService( + HttpClient.HttpClient, + HttpClient.make((request) => { + expect( + request.body._tag === "Uint8Array" && new TextDecoder().decode(request.body.body), + ).toBe('{"includePooledUsage":true}'); + return Effect.succeed( + HttpClientResponse.fromWeb( + request, + Response.json({ + billingCycleStart: "1793491200000", + billingCycleEnd: "1796083200000", + displayThreshold: 50, + planUsage: { totalPercentUsed: 0, autoPercentUsed: 0, apiPercentUsed: 0 }, + spendLimitUsage: { + limitType: "team", + overallLimit: 50000, + overallUsed: 3211, + overallRemaining: 46789, + pooledLimit: "3000000", + pooledUsed: 0, + pooledRemaining: "3000000", + }, + displayMessage: "You've used 6% of your included usage", + }), + ), + ); + }), + ), + ); + expect(limits).toEqual({ + checkedAt: expect.any(String), + windows: [ + { + id: "spendLimit", + kind: "monthly", + label: "Spend", + usedPercent: 6.422, + resetsAt: "2026-12-01T00:00:00.000Z", + }, + ], + }); + }), + ); + it.effect("requires explicit credentials and accepts an auth token", () => Effect.gen(function* () { for (const token of [undefined, "explicit-token"]) { diff --git a/packages/provider-cursor/src/server/usageLimits.ts b/packages/provider-cursor/src/server/usageLimits.ts index 48ab708554206..72c671ff98340 100644 --- a/packages/provider-cursor/src/server/usageLimits.ts +++ b/packages/provider-cursor/src/server/usageLimits.ts @@ -15,37 +15,69 @@ import { } from "@t3tools/provider-core/server/usageLimits"; import { DEFAULT_CURSOR_API_ENDPOINT, exchangeCursorApiKey } from "./apiKey.ts"; +const NO_LIMITS_MESSAGE = + "Cursor doesn't report a personal spend limit for this account. Open Cursor's dashboard with the same account to see its usage."; +const CursorInt64 = Schema.Union([Schema.String, Schema.Number]); const CursorUsageResponse = Schema.Struct({ - billingCycleStart: Schema.optional(Schema.Union([Schema.String, Schema.Number])), - billingCycleEnd: Schema.optional(Schema.Union([Schema.String, Schema.Number])), + billingCycleStart: Schema.optional(CursorInt64), + billingCycleEnd: Schema.optional(CursorInt64), planUsage: Schema.optional( Schema.Struct({ + limit: Schema.optional(CursorInt64), totalPercentUsed: Schema.optional(Schema.Number), autoPercentUsed: Schema.optional(Schema.Number), apiPercentUsed: Schema.optional(Schema.Number), }), ), + spendLimitUsage: Schema.optional( + Schema.Struct({ + overallLimit: Schema.optional(CursorInt64), + overallUsed: Schema.optional(CursorInt64), + individualLimit: Schema.optional(CursorInt64), + individualUsed: Schema.optional(CursorInt64), + pooledLimit: Schema.optional(CursorInt64), + }), + ), }); -/** Cursor's dashboard percentages include bonus usage; spend / limit does not. */ +function spendPair( + limit: typeof CursorInt64.Type | undefined, + used: typeof CursorInt64.Type | undefined, +) { + const cents = Number(limit); + return Number.isFinite(cents) && cents > 0 + ? { limit: cents, used: Number(used ?? 0) } + : undefined; +} + +/** Plan bars use Cursor's own percentages; the Spend bar is computed from cents. */ export function cursorUsageResponseToLimits( response: typeof CursorUsageResponse.Type, checkedAt: string, ) { - const reset = DateTime.make(Number(response.billingCycleEnd)); + const end = Number(response.billingCycleEnd); + const cycleStart = Number(response.billingCycleStart); + const reset = DateTime.make(end); + // Without includePooledUsage, Cursor reports start = end = now instead of the cycle. const resetsAt = - Number(response.billingCycleEnd) > 0 && Option.isSome(reset) + end > 0 && !(cycleStart >= end) && Option.isSome(reset) ? DateTime.formatIso(reset.value) : undefined; - const cycleStart = Number(response.billingCycleStart); + const { planUsage, spendLimitUsage: spend } = response; + // Enterprise sends a team pool and zeroed percentages without an included allowance. + const usageBased = + spend?.pooledLimit !== undefined && + !(Number(planUsage?.limit) > 0) && + !planUsage?.totalPercentUsed && + !planUsage?.autoPercentUsed && + !planUsage?.apiPercentUsed; const windowDurationMins = - resetsAt && cycleStart > 0 - ? Math.round((Number(response.billingCycleEnd) - cycleStart) / 60_000) - : 0; + resetsAt && cycleStart > 0 ? Math.round((end - cycleStart) / 60_000) : 0; const windows: ServerProviderUsageWindow[] = []; - if (response.planUsage) { + if (planUsage && !usageBased) { for (const { id, label } of CURSOR_USAGE_WINDOWS) { - const usedPercent = response.planUsage[id]; + if (id === "spendLimit") continue; + const usedPercent = planUsage[id]; if (usedPercent === undefined || !Number.isFinite(usedPercent)) continue; windows.push({ id, @@ -57,9 +89,23 @@ export function cursorUsageResponseToLimits( }); } } - return windows.length > 0 - ? makeUsageLimits({ checkedAt, windows }) - : makeUnavailableUsageLimits({ checkedAt, reason: "unsupported" }); + const personal = + spendPair(spend?.overallLimit, spend?.overallUsed) ?? + spendPair(spend?.individualLimit, spend?.individualUsed); + if (windows.length === 0 && personal && Number.isFinite(personal.used)) { + windows.push({ + id: "spendLimit", + kind: "monthly", + label: "Spend", + usedPercent: clampPercent((personal.used / personal.limit) * 100), + ...(resetsAt ? { resetsAt } : {}), + }); + } + if (windows.length > 0) return makeUsageLimits({ checkedAt, windows }); + return { + ...makeUnavailableUsageLimits({ checkedAt, reason: "unsupported", message: NO_LIMITS_MESSAGE }), + externalUsage: { label: "Cursor usage", url: "https://cursor.com/dashboard?tab=usage" }, + }; } export const readCursorUsageLimits = Effect.fn("readCursorUsageLimits")(function* ( @@ -94,7 +140,7 @@ export const readCursorUsageLimits = Effect.fn("readCursorUsageLimits")(function "connect-protocol-version": "1", "x-cursor-client-type": "cli", }), - HttpClientRequest.bodyJsonUnsafe({}), + HttpClientRequest.bodyJsonUnsafe({ includePooledUsage: true }), ), ); const body = yield* HttpClientResponse.schemaBodyJson(CursorUsageResponse)( diff --git a/packages/shared/src/usageLimits.test.ts b/packages/shared/src/usageLimits.test.ts index 0078c21b566b7..ee7f3143f24ea 100644 --- a/packages/shared/src/usageLimits.test.ts +++ b/packages/shared/src/usageLimits.test.ts @@ -129,6 +129,7 @@ describe("new thread model fallback", () => { ["cursor", ["autoPercentUsed"], "claude-opus-5-5", false, undefined, undefined], ["cursor", ["autoPercentUsed"], "composer-2.5", false, undefined, undefined], ["cursor", ["autoPercentUsed", "apiPercentUsed"], "composer-2.5", true, undefined, undefined], + ["cursor", ["spendLimit"], "composer-2.5", true, undefined, undefined], ["antigravity", ["gemini-weekly"], "claude-opus-5-5", false, undefined, undefined], ["antigravity", ["3p-weekly"], "claude-opus-5-5", true, undefined, undefined], ["antigravity", ["gemini-weekly"], "antigravity-default", true, undefined, undefined], diff --git a/packages/shared/src/usageLimits.ts b/packages/shared/src/usageLimits.ts index 693d82b956971..5254a11b539ee 100644 --- a/packages/shared/src/usageLimits.ts +++ b/packages/shared/src/usageLimits.ts @@ -43,6 +43,8 @@ export function exhaustedUsageWindow( if (model === undefined) return exhausted[0]; switch (provider?.driver) { case "cursor": { + const spend = exhausted.find((window) => window.id === "spendLimit"); + if (spend) return spend; const api = exhausted.find((window) => window.id === "apiPercentUsed"); const auto = exhausted.find((window) => window.id === "autoPercentUsed"); return /^(auto|default|grok|composer)/.test(model) ? auto && api : api; @@ -143,6 +145,11 @@ export const CURSOR_USAGE_WINDOWS = [ label: "Other Models", description: "Usage allowance for third-party models such as Claude, GPT, and Gemini.", }, + { + id: "spendLimit", + label: "Spend", + description: "Spending this billing cycle against your Cursor spend limit.", + }, ] as const; export function cursorUsageWindowDetails(id: string, pool: LimitPool) { diff --git a/packages/shared/src/usageLimitsCopy.ts b/packages/shared/src/usageLimitsCopy.ts index d772c48b29aac..ce0dfb5d739cd 100644 --- a/packages/shared/src/usageLimitsCopy.ts +++ b/packages/shared/src/usageLimitsCopy.ts @@ -36,6 +36,10 @@ const CURSOR_USAGE_WINDOW_COPY: Readonly< label: msg("Other Models"), description: msg("Usage allowance for third-party models such as Claude, GPT, and Gemini."), }, + spendLimit: { + label: msg("Spend"), + description: msg("Spending this billing cycle against your Cursor spend limit."), + }, }; /** @public */