Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/user/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down
27 changes: 23 additions & 4 deletions packages/provider-fx/src/server/status.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ describe("checkFxProviderStatus", () => {
"status --json",
"status --json",
"models --json",
"credits --json",
],
},
{
Expand Down Expand Up @@ -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"),
Expand All @@ -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]),
[
Expand All @@ -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);
}),
);
Expand Down Expand Up @@ -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,
Expand All @@ -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({
Expand All @@ -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"));
}),
);

Expand Down
60 changes: 50 additions & 10 deletions packages/provider-fx/src/server/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -38,6 +39,7 @@ import {
resolveProviderProbeTimeoutMs,
spawnAndCollect,
} from "@t3tools/provider-core/server/snapshotProbe";
import { fxCreditsToLimits } from "./usageLimits.ts";

const fxPresentation = (fullAccess: boolean) => ({
displayName: "fx",
Expand Down Expand Up @@ -65,6 +67,10 @@ interface FxBackendProbe {
readonly signedIn: boolean | undefined;
readonly signInHint: string;
readonly models: ReadonlyArray<string> | 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;
}

/**
Expand Down Expand Up @@ -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 }))),
}),
);
Expand Down Expand Up @@ -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<string>();
return fxCreditsToLimits({ credits, checkedAt, team });
}),
],
{ concurrency: "unbounded" },
);
return {
id: backend.id,
name: backend.name,
Expand All @@ -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,
Expand Down Expand Up @@ -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." }
Expand All @@ -382,7 +416,13 @@ export const checkFxProviderStatus = Effect.fn("checkFxProviderStatus")(function
return snapshot(
settings,
checkedAt,
{ installed: true, version, auth, ...probe },
{
installed: true,
version,
auth,
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
...probe,
...(tokenPass?.usageLimits === undefined ? {} : { usageLimits: tokenPass.usageLimits }),
},
defaultModel,
backends,
status?.modes?.some((mode) => mode.id === FX_FULL_ACCESS_MODE_ID) ?? false,
Expand Down
87 changes: 87 additions & 0 deletions packages/provider-fx/src/server/usageLimits.test.ts
Original file line number Diff line number Diff line change
@@ -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." });
});
});
73 changes: 73 additions & 0 deletions packages/provider-fx/src/server/usageLimits.ts
Original file line number Diff line number Diff line change
@@ -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<string>;
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}` } : {}),
};
}
1 change: 1 addition & 0 deletions packages/shared/src/usageLimits.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down
Loading
Loading