diff --git a/docs/user/usage.md b/docs/user/usage.md index 43f4c94a19328..8985e56fe414f 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -175,6 +175,14 @@ or endpoint configurations do not report subscription limits. Muse Code reports its session and weekly windows and its tier once the Muse CLI has run in a thread. Until then it shows no limits. Readings are not kept across a server restart. +fx reports how much of its Vercel team's [Token Pass](https://vercel.com/docs/ai-gateway/token-pass) +credit is left and when it resets. This needs fx 0.0.17 or later, a Vercel AI Gateway sign-in in +fx (`fx login` or an API key), and an active Token Pass on that sign-in's team. The bar measures +against the $150 a pass refills to each billing period, so a pass bought partway through a period +starts partly used. After the pass is used up, fx keeps running on the team's AI Gateway credits, +except with a Token Pass API key, which stops until the pass resets. Those credits and fx's Codex +and Grok subscriptions are not reported. + API-key accounts may not report subscription limits. This also applies to Claude connections using a proxy through `ANTHROPIC_AUTH_TOKEN`. diff --git a/packages/provider-fx/src/server/status.test.ts b/packages/provider-fx/src/server/status.test.ts index f4bab296fdd29..fe5aa5dc50de7 100644 --- a/packages/provider-fx/src/server/status.test.ts +++ b/packages/provider-fx/src/server/status.test.ts @@ -129,6 +129,7 @@ describe("checkFxProviderStatus", () => { "status --json", "status --json", "models --json", + "credits --json", ], }, { @@ -172,8 +173,13 @@ describe("checkFxProviderStatus", () => { model: "gpt-5.5", model_source: "Codex subscription", }), - "gateway status --json": status("fx login"), + "gateway status --json": status("fx login", { team: "example-team" }), "gateway models --json": GATEWAY_MODELS, + "gateway credits --json": JSON.stringify({ + kind: "credits", + balance: "12.50", + token_pass: { remaining: "75", resets_at: "2026-12-05T08:00:00.000Z" }, + }), "codex status --json": status("chatgpt subscription"), "codex models --json": models(["gpt-5.5", "gpt-5.4-mini"]), "grok status --json": status("missing"), @@ -183,19 +189,25 @@ describe("checkFxProviderStatus", () => { }, ["local"], ); - // Never `fx acp`, which saves a session; signed-out backends list nothing. + // Never `fx acp`, which saves a session; signed-out backends list nothing, and only the + // gateway has Token Pass credit, whichever backend is fx's default. assert.deepEqual(invoked.map(({ backend, args }) => `${backend ?? ""} ${args}`).toSorted(), [ " --version", " status --json", "codex models --json", "codex status --json", + "gateway credits --json", "gateway models --json", "gateway status --json", "grok status --json", "local status --json", ]); assert.equal(draft.status, "ready"); - assert.deepEqual(draft.auth, { status: "authenticated", label: "chatgpt subscription" }); + assert.deepEqual(draft.auth, { + status: "authenticated", + label: "chatgpt subscription", + workspaceId: "example-team", + }); assert.deepEqual( draft.models.map((model) => [model.slug, model.name, model.subProvider]), [ @@ -219,6 +231,7 @@ describe("checkFxProviderStatus", () => { }, { name: "local", unavailableReason: "The configured provider credential is unavailable." }, ]); + assert.equal(draft.usageLimits?.credentialFingerprint, "vercel-team:example-team"); assert.isDefined(draft.versionAdvisory); }), ); @@ -249,7 +262,7 @@ describe("checkFxProviderStatus", () => { it.effect("stays usable while fx's default backend is signed out", () => Effect.gen(function* () { - const { draft } = yield* check({ + const { draft, invoked } = yield* check({ " status --json": status("missing", { model: "spacexai/grok-4.7" }), "gateway status --json": status("missing"), "gateway models --json": GATEWAY_MODELS, @@ -268,6 +281,9 @@ describe("checkFxProviderStatus", () => { draft.models.map((model) => model.slug), ["default", "codex:gpt-5.5"], ); + // A signed-out gateway has no credit to read, so Limits shows no fx row. + assert.isFalse(invoked.some(({ args }) => args === "credits --json")); + assert.isUndefined(draft.usageLimits); // An earlier backend whose sign-in fx could not report does not hide Codex's. const unreadable = yield* check({ @@ -281,6 +297,9 @@ describe("checkFxProviderStatus", () => { status: "authenticated", label: "Codex subscription", }); + // Unlike a signed-out gateway, this is a failed read, so the server keeps the last reading. + assert.equal(unreadable.draft.usageLimits?.unavailable?.reason, "probeFailed"); + assert.isFalse(unreadable.invoked.some(({ args }) => args === "credits --json")); }), ); diff --git a/packages/provider-fx/src/server/status.ts b/packages/provider-fx/src/server/status.ts index 49b4b172fcc04..ce0c395149851 100644 --- a/packages/provider-fx/src/server/status.ts +++ b/packages/provider-fx/src/server/status.ts @@ -2,6 +2,7 @@ import { type ServerProviderAuth, type ServerProviderModel, type ServerProviderSubProvider, + type ServerProviderUsageLimits, } from "@t3tools/contracts"; import type { FxSettings } from "../settings.ts"; import { createModelCapabilities } from "@t3tools/shared/model"; @@ -38,6 +39,7 @@ import { resolveProviderProbeTimeoutMs, spawnAndCollect, } from "@t3tools/provider-core/server/snapshotProbe"; +import { fxCreditsToLimits } from "./usageLimits.ts"; const fxPresentation = (fullAccess: boolean) => ({ displayName: "fx", @@ -65,6 +67,10 @@ interface FxBackendProbe { readonly signedIn: boolean | undefined; readonly signInHint: string; readonly models: ReadonlyArray | undefined; + /** Token Pass is AI Gateway's, so only the gateway backend reports it, unless it is signed out. */ + readonly usageLimits: ServerProviderUsageLimits | undefined; + /** The Vercel team those limits belong to. */ + readonly team: string | undefined; } /** @@ -193,6 +199,7 @@ const FxStatus = Schema.fromJsonString( auth_help: Schema.optional(Schema.String), model: Schema.optional(Schema.String), model_source: Schema.optional(Schema.String), + team: Schema.optional(Schema.String), modes: Schema.optional(Schema.Array(Schema.Struct({ id: Schema.String }))), }), ); @@ -261,12 +268,32 @@ const probeFxBackend = Effect.fn("probeFxBackend")(function* ( ); const auth = fxAuth(status?.auth).status; const signedIn = auth === "unknown" ? undefined : auth === "authenticated"; - const models = - signedIn === false - ? undefined - : Option.getOrUndefined( - Option.flatMap(yield* readFxCli(settings, ["models", "--json"], env), decodeFxModels), - )?.ids.flatMap((id) => nonEmptyTrimmed(id) ?? []); + const team = backend.id === "gateway" ? nonEmptyTrimmed(status?.team) : undefined; + const [models, usageLimits] = yield* Effect.all( + [ + signedIn === false + ? Effect.undefined + : readFxCli(settings, ["models", "--json"], env).pipe( + Effect.map((output) => + Option.getOrUndefined(Option.flatMap(output, decodeFxModels))?.ids.flatMap( + (id) => nonEmptyTrimmed(id) ?? [], + ), + ), + ), + backend.id !== "gateway" || signedIn === false + ? Effect.undefined + : Effect.gen(function* () { + const checkedAt = DateTime.formatIso(yield* DateTime.now); + // An unreadable sign-in is a failed read, which keeps the last reading; signed out clears it. + const credits = + signedIn === true + ? yield* readFxCli(settings, ["credits", "--json"], env) + : Option.none(); + return fxCreditsToLimits({ credits, checkedAt, team }); + }), + ], + { concurrency: "unbounded" }, + ); return { id: backend.id, name: backend.name, @@ -276,12 +303,15 @@ const probeFxBackend = Effect.fn("probeFxBackend")(function* ( ? (nonEmptyTrimmed(status?.auth_help) ?? "fx has no credential for this backend.") : `Signed out. Run \`${backend.login}\` on this machine.`, models, + usageLimits, + team, } satisfies FxBackendProbe; }); /** - * Reads `fx --version`, `fx status --json` (the default backend and model) - * and, for every backend, its sign-in and `fx models --json`. + * Reads `fx --version`, `fx status --json` (the default backend and model), + * for every backend its sign-in and `fx models --json`, and the gateway's + * `fx credits --json`. */ export const checkFxProviderStatus = Effect.fn("checkFxProviderStatus")(function* ( settings: FxSettings, @@ -355,10 +385,14 @@ export const checkFxProviderStatus = Effect.fn("checkFxProviderStatus")(function listed.length === 0 || listed.some((backend) => backend.models === undefined); const signedIn = backends.find((backend) => backend.signedIn === true); const statusAuth = fxAuth(status?.auth); - const auth: ServerProviderAuth = + const tokenPass = backends.find((backend) => backend.usageLimits !== undefined); + const backendAuth: ServerProviderAuth = statusAuth.status !== "authenticated" && signedIn !== undefined ? { status: "authenticated", label: signedIn.name } : statusAuth; + // The server keeps the last reading after a failed read only while this stays the same team. + const auth: ServerProviderAuth = + tokenPass?.team === undefined ? backendAuth : { ...backendAuth, workspaceId: tokenPass.team }; const probe = auth.status === "unauthenticated" ? { status: "error" as const, message: "Run `fx login` to sign in." } @@ -382,7 +416,13 @@ export const checkFxProviderStatus = Effect.fn("checkFxProviderStatus")(function return snapshot( settings, checkedAt, - { installed: true, version, auth, ...probe }, + { + installed: true, + version, + auth, + ...probe, + ...(tokenPass?.usageLimits === undefined ? {} : { usageLimits: tokenPass.usageLimits }), + }, defaultModel, backends, status?.modes?.some((mode) => mode.id === FX_FULL_ACCESS_MODE_ID) ?? false, diff --git a/packages/provider-fx/src/server/usageLimits.test.ts b/packages/provider-fx/src/server/usageLimits.test.ts new file mode 100644 index 0000000000000..d0df5fbf44cd2 --- /dev/null +++ b/packages/provider-fx/src/server/usageLimits.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, it } from "@effect/vitest"; +import * as Option from "effect/Option"; + +import { fxCreditsToLimits } from "./usageLimits.ts"; + +const checkedAt = "2026-11-21T16:00:00.000Z"; +const limits = (credits: unknown) => + fxCreditsToLimits({ + credits: Option.some(typeof credits === "string" ? credits : JSON.stringify(credits)), + checkedAt, + team: "example-team", + }); +// `fx credits --json` from fx 0.0.17 (src/core/output/output_contracts.zig). +const credits = (tokenPass: unknown) => ({ + kind: "credits", + balance: "9.731069815", + used: "125.268930185", + plan: null, + token_pass: tokenPass, +}); + +describe("fx Token Pass limits", () => { + it("reads the credit left of the $150 a pass refills to", () => { + expect( + limits(credits({ remaining: "79.92906", resets_at: "2026-12-05T08:00:00.000Z" })), + ).toEqual({ + checkedAt, + windows: [ + { + id: "token_pass", + kind: "monthly", + label: "Token Pass", + usedPercent: expect.closeTo(46.71, 2), + resetsAt: "2026-12-05T08:00:00.000Z", + }, + ], + credentialFingerprint: "vercel-team:example-team", + }); + }); + + it.each([ + ["a used-up pass", { remaining: "0", resets_at: "2026-12-05T08:00:00.000Z" }, 100], + ["an overdrawn pass", { remaining: "-0.42", resets_at: "2026-12-05T08:00:00.000Z" }, 100], + ["an untouched pass", { remaining: "150", resets_at: "2026-12-05T08:00:00.000Z" }, 0], + ["more credit than a pass refills to", { remaining: "180.5" }, 0], + ])("reports %s", (_label, tokenPass, usedPercent) => { + expect(limits(credits(tokenPass)).windows.map((window) => window.usedPercent)).toEqual([ + usedPercent, + ]); + }); + + it("leaves out a reset time fx did not report and an account for an API key without a team", () => { + const withoutTeam = fxCreditsToLimits({ + credits: Option.some(JSON.stringify(credits({ remaining: "5", resets_at: null }))), + checkedAt, + team: undefined, + }); + expect(withoutTeam.windows[0]).not.toHaveProperty("resetsAt"); + expect(withoutTeam).not.toHaveProperty("credentialFingerprint"); + }); + + it.each([ + ["a team without an active pass", credits(null)], + ["an fx older than Token Pass", { kind: "credits", balance: "1", used: "2", plan: null }], + ])("shows no limits for %s", (_label, output) => { + expect(limits(output)).toEqual({ + checkedAt, + windows: [], + unavailable: { reason: "unsupported" }, + }); + }); + + it.each([ + ["a credit AI Gateway could not read", credits({ remaining: null })], + ["an amount that is not a number", credits({ remaining: "1.2.3" })], + ["a credits error", { kind: "credits", error: "failed to fetch credits from gateway" }], + ["output that is not JSON", "[credits] balance=1"], + ])("keeps the earlier reading for %s", (_label, output) => { + expect(limits(output).unavailable?.reason).toBe("probeFailed"); + }); + + it("keeps the earlier reading when `fx credits` fails", () => { + expect( + fxCreditsToLimits({ credits: Option.none(), checkedAt, team: "example-team" }).unavailable, + ).toEqual({ reason: "probeFailed", message: "fx could not read the Token Pass credit." }); + }); +}); diff --git a/packages/provider-fx/src/server/usageLimits.ts b/packages/provider-fx/src/server/usageLimits.ts new file mode 100644 index 0000000000000..cd96cce731d37 --- /dev/null +++ b/packages/provider-fx/src/server/usageLimits.ts @@ -0,0 +1,73 @@ +import type { ServerProviderUsageLimits } from "@t3tools/contracts"; +import * as DateTime from "effect/DateTime"; +import * as Option from "effect/Option"; +import * as Schema from "effect/Schema"; +import { + clampPercent, + makeUnavailableUsageLimits, + makeUsageLimits, +} from "@t3tools/provider-core/server/usageLimits"; + +// Vercel reports only the credit left. A pass refills to this each billing period, and a pass +// bought mid-period starts with a prorated share, so its first period reads as partly used. +const TOKEN_PASS_PERIOD_CREDIT_USD = 150; + +/** + * `fx credits --json`, fx 0.0.17+. `token_pass` is null for a team without an + * active pass and absent on an older fx. `remaining` is US dollars, or null + * when AI Gateway could not read the credit. + */ +const FxCredits = Schema.fromJsonString( + Schema.Struct({ + error: Schema.optional(Schema.String), + token_pass: Schema.optional( + Schema.NullOr( + Schema.Struct({ + remaining: Schema.optional(Schema.NullOr(Schema.String)), + resets_at: Schema.optional(Schema.NullOr(Schema.String)), + }), + ), + ), + }), +); +const decodeFxCredits = Schema.decodeUnknownOption(FxCredits); + +/** The Token Pass credit of the Vercel team fx is signed in to, as one Limits window. */ +export function fxCreditsToLimits(input: { + /** Stdout of a successful `fx credits --json`, or none when it failed. */ + readonly credits: Option.Option; + readonly checkedAt: string; + /** Every login on a team spends the same pass, so the team names the account. */ + readonly team: string | undefined; +}): ServerProviderUsageLimits { + const { checkedAt } = input; + const probeFailed = makeUnavailableUsageLimits({ + checkedAt, + reason: "probeFailed", + message: "fx could not read the Token Pass credit.", + }); + const credits = Option.getOrUndefined(Option.flatMap(input.credits, decodeFxCredits)); + if (credits === undefined || credits.error !== undefined) return probeFailed; + if (credits.token_pass === undefined || credits.token_pass === null) { + return makeUnavailableUsageLimits({ checkedAt, reason: "unsupported" }); + } + const remaining = credits.token_pass.remaining?.trim(); + // The amounts fx passes on: an overdrawn pass is negative, and a bare point is allowed. + if (!remaining || !/^-?(\d+\.?\d*|\.\d+)$/.test(remaining)) return probeFailed; + const reset = DateTime.make(credits.token_pass.resets_at ?? ""); + return { + ...makeUsageLimits({ + checkedAt, + windows: [ + { + id: "token_pass", + kind: "monthly", + label: "Token Pass", + usedPercent: clampPercent(100 - (Number(remaining) / TOKEN_PASS_PERIOD_CREDIT_USD) * 100), + ...(Option.isSome(reset) ? { resetsAt: DateTime.formatIso(reset.value) } : {}), + }, + ], + }), + ...(input.team ? { credentialFingerprint: `vercel-team:${input.team}` } : {}), + }; +} diff --git a/packages/shared/src/usageLimits.test.ts b/packages/shared/src/usageLimits.test.ts index 6b553fe5f1555..50f5c33f194e1 100644 --- a/packages/shared/src/usageLimits.test.ts +++ b/packages/shared/src/usageLimits.test.ts @@ -181,6 +181,7 @@ describe("new thread model fallback", () => { ["opencode", "console-custom"], ], ["opencode", ["budget_all"], "opencode/model", false, undefined, []], + ["fx", ["token_pass"], "gateway:moonshotai/kimi-k3.1-pro", false, undefined, undefined], ] as const)( "matches %s pools %s to %s", (driver, ids, model, usesFallback, modelIds, providerIds) => { diff --git a/packages/shared/src/usageLimits.ts b/packages/shared/src/usageLimits.ts index 711f3637d0a9f..466e8f74b01e6 100644 --- a/packages/shared/src/usageLimits.ts +++ b/packages/shared/src/usageLimits.ts @@ -71,6 +71,10 @@ export function exhaustedUsageWindow( return exhausted.find( (window) => !window.id.startsWith("go_") || model.startsWith("opencode-go/"), ); + case "fx": + // Only a Token Pass API key stops when the pass is used up; other sign-ins go on with AI + // Gateway credits, and fx's other backends never use it. The reading cannot tell them apart. + return exhausted.find((window) => window.id !== "token_pass"); default: return exhausted[0]; }