Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): report spend usage for Claude plans without rate windows (#5629)
Xuanru Li150e1c94d0a9
diff --git a/packages/cli/src/utils/usageBudget.test.ts b/packages/cli/src/utils/usageBudget.test.tsindex 290e3656d4..1ad9a23fdf 100644--- a/packages/cli/src/utils/usageBudget.test.ts+++ b/packages/cli/src/utils/usageBudget.test.ts@@ -11,6 +11,7 @@ describe("Claude shared usage visibility", () => {it("preserves independent usage percentages and reset times", () => {expect(parseHarnessUsage(windows(81, 95))).toEqual({status: "known",+ spend: null,harness: "claude-code",planTier: null,session: { usedPercent: 81, remainingPercent: 19, resetsAt: null },@@ -22,6 +23,7 @@ describe("Claude shared usage visibility", () => {parseHarnessUsage('{"five_hour":null,"seven_day":{"utilization":95,"resets_at":null}}'),).toEqual({status: "known",+ spend: null,harness: "claude-code",planTier: null,session: null,@@ -31,6 +33,7 @@ describe("Claude shared usage visibility", () => {it("preserves empty and fully used windows", () => {expect(parseHarnessUsage(windows(0, 100))).toEqual({status: "known",+ spend: null,harness: "claude-code",planTier: null,session: { usedPercent: 0, remainingPercent: 100, resetsAt: null },@@ -40,7 +43,6 @@ describe("Claude shared usage visibility", () => {it.each(["not-json","{}",- '{"five_hour":null,"seven_day":null}',windows(-1, 20),windows(10, 101),'{"five_hour":{"utilization":"80"},"seven_day":{"utilization":10}}',@@ -52,6 +54,77 @@ describe("Claude shared usage visibility", () => {});});+describe("Claude spend-metered plans", () => {+ it("reports no usage windows instead of an invalid response when every window is absent", () => {+ expect(parseHarnessUsage('{"five_hour":null,"seven_day":null}')).toEqual({+ status: "unknown",+ reason: "no_usage_windows",+ });+ });+ it("exposes the spend share when the five-hour and weekly windows are absent", () => {+ expect(+ parseHarnessUsage(+ JSON.stringify({+ five_hour: null,+ seven_day: null,+ spend: { percent: 42.5, enabled: true, severity: "normal" },+ extra_usage: { is_enabled: true, utilization: 10 },+ }),+ ),+ ).toEqual({+ status: "known",+ harness: "claude-code",+ planTier: null,+ session: null,+ weekly: null,+ spend: { usedPercent: 42.5, remainingPercent: 57.5, resetsAt: null },+ });+ });+ it("falls back to extra usage utilization when spend is absent", () => {+ expect(+ parseHarnessUsage(+ JSON.stringify({+ five_hour: null,+ seven_day: null,+ extra_usage: { is_enabled: true, utilization: 30 },+ }),+ ),+ ).toMatchObject({+ status: "known",+ spend: { usedPercent: 30, remainingPercent: 70, resetsAt: null },+ });+ });+ it("caps spend over the limit at fully used", () => {+ expect(+ parseHarnessUsage(+ JSON.stringify({+ five_hour: null,+ seven_day: null,+ spend: { percent: 120, enabled: true },+ }),+ ),+ ).toMatchObject({ status: "known", spend: { usedPercent: 100, remainingPercent: 0 } });+ });+ it("ignores disabled spend and keeps reporting rate windows", () => {+ expect(+ parseHarnessUsage(+ JSON.stringify({+ five_hour: { utilization: 5 },+ seven_day: null,+ spend: { percent: 80, enabled: false },+ }),+ ),+ ).toMatchObject({ status: "known", spend: null, session: { usedPercent: 5 } });+ });+ it("rejects a negative spend share", () => {+ expect(+ parseHarnessUsage(+ JSON.stringify({ five_hour: null, seven_day: null, spend: { percent: -1, enabled: true } }),+ ),+ ).toEqual({ status: "unknown", reason: "invalid_usage_response" });+ });+});+it("maps Codex windows by duration and exposes its reported plan tier", () => {expect(parseCodexUsage(@@ -65,6 +138,7 @@ it("maps Codex windows by duration and exposes its reported plan tier", () => {),).toEqual({status: "known",+ spend: null,harness: "codex",planTier: "pro",session: { usedPercent: 25, remainingPercent: 75, resetsAt: "1970-01-01T02:00:00.000Z" },@@ -85,6 +159,7 @@ it.each([undefined, null])(),).toEqual({status: "known",+ spend: null,harness: "codex",planTier: null,session: null,@@ -104,6 +179,7 @@ it("converts Codex relative resets using the supplied observation time", () => {),).toEqual({status: "known",+ spend: null,harness: "codex",planTier: null,weekly: null,@@ -112,13 +188,18 @@ it("converts Codex relative resets using the supplied observation time", () => {});it.each(["{}",- '{"rate_limit":{}}','{"rate_limit":{"primary_window":{"used_percent":101}}}','{"rate_limit":{"primary_window":{"used_percent":-1}}}','{"rate_limit":{"primary_window":{"used_percent":10,"reset_at":9000000000000}}}',])("rejects invalid Codex allowance: %s", (text) => {expect(parseCodexUsage(text)).toEqual({ status: "unknown", reason: "invalid_usage_response" });});+it("reports no usage windows for an empty Codex rate limit", () => {+ expect(parseCodexUsage('{"rate_limit":{}}')).toEqual({+ status: "unknown",+ reason: "no_usage_windows",+ });+});it("rejects unsupported Codex durations", () => {expect(parseCodexUsage(@@ -151,6 +232,7 @@ it("exposes Grok weekly credits without inventing a session or plan tier", () =>),).toEqual({status: "known",+ spend: null,harness: "grok",planTier: null,session: null,@@ -160,6 +242,7 @@ it("exposes Grok weekly credits without inventing a session or plan tier", () =>it("honors Grok proto JSON's omitted zero usage", () => {expect(parseGrokUsage(JSON.stringify({ config: { currentPeriod: grokPeriod } }))).toEqual({status: "known",+ spend: null,harness: "grok",planTier: null,session: null,diff --git a/packages/cli/src/utils/usageBudget.ts b/packages/cli/src/utils/usageBudget.tsindex 9de467c201..8af1aa55f3 100644--- a/packages/cli/src/utils/usageBudget.ts+++ b/packages/cli/src/utils/usageBudget.ts@@ -7,8 +7,25 @@ const windowSchema = {optionalProperties: { resets_at: { type: "string", nullable: true } },additionalProperties: true,} as const;+const spendSchema = {+ nullable: true,+ optionalProperties: {+ percent: { type: "float64", nullable: true },+ enabled: { type: "boolean", nullable: true },+ },+ additionalProperties: true,+} as const;+const extraUsageSchema = {+ nullable: true,+ optionalProperties: {+ utilization: { type: "float64", nullable: true },+ is_enabled: { type: "boolean", nullable: true },+ },+ additionalProperties: true,+} as const;const usageSchema = {properties: { five_hour: windowSchema, seven_day: windowSchema },+ optionalProperties: { spend: spendSchema, extra_usage: extraUsageSchema },additionalProperties: true,} as const;const parseUsage = new Ajv().compileParser<JTDDataType<typeof usageSchema>>(usageSchema);@@ -21,6 +38,7 @@ export type HarnessUsage =harness: "claude-code" | "codex" | "grok";session: UsageWindow | null;weekly: UsageWindow | null;+ spend: UsageWindow | null;planTier: string | null;};@@ -41,7 +59,21 @@ export function parseHarnessUsage(text: string): HarnessUsage {};const session = normalize(usage.five_hour);const weekly = normalize(usage.seven_day);- return knownUsage("claude-code", session, weekly);+ return knownUsage("claude-code", session, weekly, null, claudeSpendWindow(usage));+}++function claudeSpendWindow(usage: JTDDataType<typeof usageSchema>): UsageWindow | null {+ const spend = usage.spend;+ const extra = usage.extra_usage;+ const percent =+ spend && spend.enabled !== false && typeof spend.percent === "number"+ ? spend.percent+ : extra && extra.is_enabled === true && typeof extra.utilization === "number"+ ? extra.utilization+ : null;+ if (percent === null) return null;+ const used = percent > 100 ? 100 : percent;+ return { usedPercent: used, remainingPercent: 100 - used, resetsAt: null };}function knownUsage(@@ -49,10 +81,13 @@ function knownUsage(session: UsageWindow | null,weekly: UsageWindow | null,planTier: string | null = null,+ spend: UsageWindow | null = null,): HarnessUsage {- const windows = [session, weekly].filter((window): window is UsageWindow => window !== null);+ const windows = [session, weekly, spend].filter(+ (window): window is UsageWindow => window !== null,+ );+ if (!windows.length) return unknownUsage("no_usage_windows");if (- !windows.length ||windows.some((window) =>!Number.isFinite(window.remainingPercent) ||@@ -61,7 +96,7 @@ function knownUsage())return unknownUsage("invalid_usage_response");- return { status: "known", harness, session, weekly, planTier };+ return { status: "known", harness, session, weekly, spend, planTier };}const codexWindowSchema = {diff --git a/skills-manifest.json b/skills-manifest.jsonindex d1a7348491..2ebd910626 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -30,7 +30,7 @@"files": 8},"hyperframes-cli": {- "hash": "a31394489347263b",+ "hash": "0efd9da98211dc25","files": 11},"hyperframes-core": {diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.mdindex f9e919b818..4dfe21623a 100644--- a/skills/hyperframes-cli/SKILL.md+++ b/skills/hyperframes-cli/SKILL.md@@ -194,6 +194,6 @@ Two entries in `hyperframes --help` are not part of the authoring loop, and reacRun `npx hyperframes usage --json` at the start of a video workflow and again at milestones such as after drafting and before rendering. A fresh read at handoff can serve as the start read. Use `--harness claude-code`, `--harness codex`, or `--harness grok` to select explicitly.-Known results contain `status: "known"`, `harness`, `planTier`, `session`, and `weekly`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`.+Known results contain `status: "known"`, `harness`, `planTier`, `session`, `weekly`, and `spend`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows; a spend-metered plan (such as Enterprise) has neither and reports `spend`, the share of its billing-period spend limit already used, with `resetsAt: null`. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`. Only Claude Code reports `spend`; it is `null` elsewhere. When no window is available the result is `status: "unknown"` with `reason: "no_usage_windows"`.Unknown results contain `status: "unknown"` and a token-free `reason`. Missing, expired, unsupported, ambiguous, or unreadable logins and unavailable provider responses return unknown. Report the unknown state without guessing allowance. The command reads existing credentials without refreshing or rewriting them and emits no tokens or telemetry. Usage is a snapshot; it does not reserve allowance or estimate the next video's cost. Keep scope and workflow choices with the user.diff --git a/skills/hyperframes-cli/references/upgrade-info-misc.md b/skills/hyperframes-cli/references/upgrade-info-misc.mdindex a74fd01476..f52ed865f5 100644--- a/skills/hyperframes-cli/references/upgrade-info-misc.md+++ b/skills/hyperframes-cli/references/upgrade-info-misc.md@@ -129,6 +129,6 @@ For voice selection, Whisper model rules, output format choice, and the TTS →Run `npx hyperframes usage --json` at the start of a video workflow and again at milestones such as after drafting and before rendering. A fresh read at handoff can serve as the start read. Use `--harness claude-code`, `--harness codex`, or `--harness grok` to select explicitly.-Known results contain `status: "known"`, `harness`, `planTier`, `session`, and `weekly`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`.+Known results contain `status: "known"`, `harness`, `planTier`, `session`, `weekly`, and `spend`. Each available window contains `usedPercent`, `remainingPercent`, and `resetsAt`; an unavailable window is `null`. `planTier` is the readable subscription tier when available, otherwise `null`. Claude Code reports its shared five-hour and weekly windows; a spend-metered plan (such as Enterprise) has neither and reports `spend`, the share of its billing-period spend limit already used, with `resetsAt: null`. Codex reports its shared session and weekly windows when available. Grok reports its included weekly allowance with `session: null`. Only Claude Code reports `spend`; it is `null` elsewhere. When no window is available the result is `status: "unknown"` with `reason: "no_usage_windows"`.Unknown results contain `status: "unknown"` and a token-free `reason`. Missing, expired, unsupported, ambiguous, or unreadable logins and unavailable provider responses return unknown. Report the unknown state without guessing allowance. The command reads existing credentials without refreshing or rewriting them and emits no tokens or telemetry. Usage is a snapshot; it does not reserve allowance or estimate the next video's cost. Keep scope and workflow choices with the user.