Skip to content

Commit 7348933

Browse files
feat(cli): expose harness subscription usage to agents (#4919)
* feat(cli): plan video creation around remaining harness usage * feat(cli): read Codex and Grok subscription allowances * test(cli): load usage fixtures through portable file URLs * test(cli): keep fixture writes on filesystem paths * refactor(cli): separate usage window and login decisions * fix(cli): guard parsed credential array entries * refactor(cli): report harness usage without workflow policy * fix(cli): preserve usage when subscription tier is null * test(cli): separate usage fixture code from inputs * style(cli): format usage transport fixture * refactor(cli): isolate usage fixture credential checks
1 parent ada4e0d commit 7348933

14 files changed

Lines changed: 994 additions & 7 deletions

File tree

‎packages/cli/src/cli.ts‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ const commandLoaders = {
168168
browser: () => import("./commands/browser.js").then((m) => m.default),
169169
"remove-background": () => import("./commands/remove-background.js").then((m) => m.default),
170170
transcribe: () => import("./commands/transcribe.js").then((m) => m.default),
171+
usage: () => import("./commands/usage.js").then((m) => m.default),
171172
models: () => import("./commands/models.js").then((m) => m.default),
172173
tts: () => import("./commands/tts.js").then((m) => m.default),
173174
docs: () => import("./commands/docs.js").then((m) => m.default),
@@ -246,7 +247,13 @@ let telemetryReady: Promise<void> = Promise.resolve();
246247
// `events` is a telemetry-internal beacon: it self-tracks + self-flushes, so it
247248
// skips the per-command wrapper (no duplicate cli_command, no first-run notice
248249
// printed into a skill's captured output).
249-
if (!isHelp && command !== "telemetry" && command !== "events" && command !== "unknown") {
250+
if (
251+
!isHelp &&
252+
command !== "telemetry" &&
253+
command !== "events" &&
254+
command !== "usage" &&
255+
command !== "unknown"
256+
) {
250257
telemetryReady = import("./telemetry/index.js").then((mod) => {
251258
_flushSync = mod.flushSync;
252259
_trackCliError = mod.trackCliError;
@@ -273,7 +280,8 @@ if (
273280
command !== "upgrade" &&
274281
command !== "events" &&
275282
command !== "telemetry" &&
276-
command !== "skills"
283+
command !== "skills" &&
284+
command !== "usage"
277285
) {
278286
// Report any completed auto-install from the previous run first, before
279287
// kicking off the next check — so the user sees "updated to vX" once and
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import { appendFileSync, writeFileSync } from "node:fs";
2+
3+
const env = process.env;
4+
function checkCredentials(headers) {
5+
if (headers.Authorization !== "Bearer fixture-token") throw new Error("wrong credential");
6+
if (env.HF_USAGE_HARNESS === "codex" && headers["ChatGPT-Account-Id"] !== "fixture-account")
7+
throw new Error("missing account header");
8+
if (env.HF_USAGE_HARNESS === "grok" && headers["X-XAI-Token-Auth"] !== "xai-grok-cli")
9+
throw new Error("missing Grok header");
10+
}
11+
12+
globalThis.fetch = async (url, options) => {
13+
if (env.HF_USAGE_FORBID_REQUESTS === "true") {
14+
writeFileSync(env.HF_USAGE_REQUESTS, "unexpected");
15+
throw new Error("unexpected network request");
16+
}
17+
appendFileSync(env.HF_USAGE_REQUESTS, JSON.stringify(String(url)) + "\n");
18+
const settings =
19+
env.HF_USAGE_HARNESS === "grok" &&
20+
String(url) === "https://cli-chat-proxy.grok.com/v1/settings";
21+
if (String(url) !== env.HF_USAGE_URL && !settings) throw new Error("unexpected network request");
22+
checkCredentials(options.headers);
23+
if (settings && env.HF_USAGE_SETTINGS_FAIL === "true")
24+
return new Response("unavailable", { status: 503 });
25+
return new Response(
26+
settings ? JSON.stringify({ subscription_tier_display: "SuperGrok" }) : env.HF_USAGE_RESPONSE,
27+
);
28+
};
Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
import { execFileSync } from "node:child_process";
2+
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join, resolve } from "node:path";
5+
import { expect, it } from "vitest";
6+
7+
const fixtureTiers: Record<string, string> = {
8+
"claude-code": "max",
9+
codex: "plus",
10+
grok: "SuperGrok",
11+
};
12+
13+
it.each(
14+
[
15+
{
16+
harness: "claude-code",
17+
path: ".credentials.json",
18+
auth: {
19+
claudeAiOauth: {
20+
accessToken: "fixture-token",
21+
subscriptionType: "max",
22+
scopes: ["user:profile"],
23+
},
24+
},
25+
url: "https://api.anthropic.com/api/oauth/usage",
26+
response: { five_hour: { utilization: 90 }, seven_day: { utilization: 20 } },
27+
},
28+
{
29+
harness: "codex",
30+
path: "auth.json",
31+
auth: { tokens: { access_token: "fixture-token", account_id: "fixture-account" } },
32+
url: "https://chatgpt.com/backend-api/wham/usage",
33+
response: {
34+
plan_type: "plus",
35+
rate_limit: {
36+
primary_window: { used_percent: 90, limit_window_seconds: 18000 },
37+
secondary_window: { used_percent: 20, limit_window_seconds: 604800 },
38+
},
39+
},
40+
},
41+
{
42+
harness: "grok",
43+
path: "auth.json",
44+
auth: {
45+
fixture: { key: "fixture-token", auth_mode: "oidc", oidc_issuer: "https://auth.x.ai" },
46+
},
47+
url: "https://cli-chat-proxy.grok.com/v1/billing?format=credits",
48+
response: {
49+
config: {
50+
currentPeriod: {
51+
type: "USAGE_PERIOD_TYPE_WEEKLY",
52+
start: "2026-10-01T00:00:00Z",
53+
end: "2026-10-08T00:00:00Z",
54+
},
55+
creditUsagePercent: 90,
56+
},
57+
},
58+
},
59+
].flatMap((fixture) => {
60+
if (fixture.harness === "grok")
61+
return [
62+
{ ...fixture, settingsFail: false, missingTier: false },
63+
{ ...fixture, settingsFail: true, missingTier: false },
64+
];
65+
if (fixture.harness === "claude-code")
66+
return [
67+
{ ...fixture, settingsFail: false, missingTier: false },
68+
{
69+
...fixture,
70+
settingsFail: false,
71+
missingTier: true,
72+
auth: {
73+
claudeAiOauth: {
74+
accessToken: "fixture-token",
75+
subscriptionType: null,
76+
scopes: ["user:profile"],
77+
},
78+
},
79+
},
80+
];
81+
return [{ ...fixture, settingsFail: false, missingTier: false }];
82+
}),
83+
)(
84+
"prints the real $harness CLI usage and subscription tier without exposing tokens",
85+
({ harness, path, auth, url, response, settingsFail, missingTier }) => {
86+
const profile = mkdtempSync(join(tmpdir(), "hf-usage-"));
87+
try {
88+
const originalAuth = JSON.stringify(auth);
89+
writeFileSync(join(profile, path), originalAuth);
90+
const requests = join(profile, "requests.jsonl");
91+
const env: NodeJS.ProcessEnv = {
92+
...process.env,
93+
HF_USAGE_FORBID_REQUESTS: "false",
94+
HF_USAGE_REQUESTS: requests,
95+
HF_USAGE_HARNESS: harness,
96+
HF_USAGE_URL: url,
97+
HF_USAGE_RESPONSE: JSON.stringify(response),
98+
HF_USAGE_SETTINGS_FAIL: String(settingsFail),
99+
CLAUDE_CONFIG_DIR: profile,
100+
CODEX_HOME: profile,
101+
GROK_AUTH_PATH: join(profile, path),
102+
};
103+
for (const key of [
104+
"ANTHROPIC_API_KEY",
105+
"ANTHROPIC_AUTH_TOKEN",
106+
"ANTHROPIC_BASE_URL",
107+
"CLAUDE_CODE_CUSTOM_OAUTH_URL",
108+
"USE_LOCAL_OAUTH",
109+
"USE_STAGING_OAUTH",
110+
])
111+
delete env[key];
112+
const stdout = execFileSync(
113+
process.execPath,
114+
[
115+
"--import",
116+
"tsx",
117+
"--import",
118+
new URL("./fixtures/usage-transport.mjs", import.meta.url).href,
119+
resolve("src/cli.ts"),
120+
"usage",
121+
"--harness",
122+
harness,
123+
"--json",
124+
],
125+
{
126+
cwd: resolve("."),
127+
env,
128+
encoding: "utf8",
129+
timeout: 15000,
130+
},
131+
);
132+
expect(JSON.parse(stdout)).toMatchObject({
133+
status: "known",
134+
planTier: settingsFail || missingTier ? null : fixtureTiers[harness],
135+
weekly: {
136+
usedPercent: harness === "grok" ? 90 : 20,
137+
remainingPercent: harness === "grok" ? 10 : 80,
138+
},
139+
});
140+
expect(stdout).not.toContain("fixture-token");
141+
expect(readFileSync(join(profile, path), "utf8")).toBe(originalAuth);
142+
const expectedRequests = [url];
143+
if (harness === "grok") expectedRequests.push("https://cli-chat-proxy.grok.com/v1/settings");
144+
expect(readFileSync(requests, "utf8").trim().split("\n")).toEqual(
145+
expectedRequests.map((request) => JSON.stringify(request)),
146+
);
147+
} finally {
148+
rmSync(profile, { recursive: true, force: true });
149+
}
150+
},
151+
);
152+
153+
it.each([
154+
{
155+
harness: "codex",
156+
auth: { tokens: { access_token: "fixture.eyJleHAiOjF9.signature" } },
157+
reason: "expired_login",
158+
},
159+
{
160+
harness: "grok",
161+
auth: {
162+
fixture: {
163+
key: "fixture-token",
164+
auth_mode: "oidc",
165+
oidc_issuer: "https://auth.x.ai",
166+
expires_at: "2000-01-01T00:00:00Z",
167+
},
168+
},
169+
reason: "expired_login",
170+
},
171+
{
172+
harness: "grok",
173+
auth: { fixture: { key: "fixture-token", auth_mode: "api_key" } },
174+
reason: "unsupported_auth",
175+
},
176+
{
177+
harness: "grok",
178+
auth: {
179+
a: { key: "fixture-token", auth_mode: "oidc", oidc_issuer: "https://auth.x.ai" },
180+
b: { key: "fixture-token-2", auth_mode: "oidc", oidc_issuer: "https://auth.x.ai" },
181+
},
182+
reason: "ambiguous_login",
183+
},
184+
])(
185+
"keeps $harness $reason unknown without requests or auth writes",
186+
({ harness, auth, reason }) => {
187+
const profile = mkdtempSync(join(tmpdir(), "hf-usage-"));
188+
try {
189+
const authFile = join(profile, "auth.json");
190+
const originalAuth = JSON.stringify(auth);
191+
writeFileSync(authFile, originalAuth);
192+
const requests = join(profile, "requests.jsonl");
193+
const stdout = execFileSync(
194+
process.execPath,
195+
[
196+
"--import",
197+
"tsx",
198+
"--import",
199+
new URL("./fixtures/usage-transport.mjs", import.meta.url).href,
200+
resolve("src/cli.ts"),
201+
"usage",
202+
"--harness",
203+
harness,
204+
"--json",
205+
],
206+
{
207+
env: {
208+
...process.env,
209+
HF_USAGE_REQUESTS: requests,
210+
HF_USAGE_FORBID_REQUESTS: "true",
211+
CODEX_HOME: profile,
212+
GROK_AUTH_PATH: authFile,
213+
},
214+
encoding: "utf8",
215+
timeout: 15000,
216+
},
217+
);
218+
expect(JSON.parse(stdout)).toEqual({
219+
status: "unknown",
220+
reason,
221+
});
222+
expect(stdout).not.toContain("fixture-token");
223+
expect(readFileSync(authFile, "utf8")).toBe(originalAuth);
224+
expect(existsSync(requests)).toBe(false);
225+
} finally {
226+
rmSync(profile, { recursive: true, force: true });
227+
}
228+
},
229+
);

‎packages/cli/src/commands/usage.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { defineCommand } from "citty";
2+
import { readHarnessUsage } from "../utils/harnessUsage.js";
3+
4+
export default defineCommand({
5+
meta: {
6+
name: "usage",
7+
description: "Read remaining harness subscription usage without telemetry",
8+
},
9+
args: {
10+
harness: {
11+
type: "string",
12+
description:
13+
"Harness to read (claude-code, codex, grok); otherwise detect the current harness",
14+
},
15+
json: { type: "boolean", description: "Print subscription usage as JSON", default: false },
16+
},
17+
async run({ args }) {
18+
const harness = args.harness ?? detectHarness();
19+
const usage = await readHarnessUsage(harness);
20+
if (args.json) console.log(JSON.stringify(usage));
21+
else if (usage.status === "unknown") console.log(`Usage unknown (${usage.reason}).`);
22+
else console.log(JSON.stringify(usage, null, 2));
23+
},
24+
});
25+
26+
function detectHarness(): string {
27+
if (process.env.CODEX_THREAD_ID) return "codex";
28+
if (process.env.GROK_AGENT === "1") return "grok";
29+
if (process.env.CLAUDECODE) return "claude-code";
30+
return "unknown";
31+
}

0 commit comments

Comments
 (0)