Skip to content

fix(cli): support monthly Codex usage windows - #6333

Open
serdarkarisik54-spec wants to merge 5 commits into
heygen-com:mainfrom
serdarkarisik54-spec:fix/codex-monthly-usage-window
Open

serdarkarisik54-spec wants to merge 5 commits into
heygen-com:mainfrom
serdarkarisik54-spec:fix/codex-monthly-usage-window

Conversation

@serdarkarisik54-spec

Copy link
Copy Markdown

What

Recognize Codex's 30-day (2,592,000-second) usage window as a separate monthly field in hyperframes usage --json.

Why

Some Codex accounts return a 30-day allowance window. The CLI currently recognizes only 5-hour and 7-day windows, so this account returns unsupported_usage_window even though its usage data is valid.

How

  • Add monthly to Codex window parsing and result validation.
  • Preserve the existing session and weekly fields.
  • Add tests for a 30-day window and duplicate monthly windows; update the usage docs.

Test plan

  • Unit tests added/updated
  • Documentation updated
  • bunx vitest run usageBudget.test.ts — 34 tests passed in an isolated workspace with the CLI's Ajv and Vitest dependencies.

@miguel-heygen miguel-heygen left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. It's a clear, well-scoped fix. The 30-day constant matches how Codex itself labels a monthly window (30 days), the new case reuses the existing duplicate-window guard, and the duplicate-monthly test covers it nicely.

One thing to change before merge:

monthly should always be present, like spend (packages/cli/src/utils/usageBudget.ts:41, :86, :106). Right now Codex results always include monthly, but Claude Code and Grok results leave the key out entirely. The usage docs promise that an unavailable window is null, and spend already follows that rule for harnesses that never report it. A script that checks result.monthly === null would get undefined on Claude Code and Grok. The existing tests don't notice because toEqual treats a missing key and an undefined key the same. A simpler shape is:

  • monthly: UsageWindow | null (required) in HarnessUsage
  • monthly: UsageWindow | null = null as the knownUsage parameter
  • keep the original window !== null filter and return monthly unconditionally

Then add monthly: null to the Claude Code and Grok toEqual expectations, so the shape stays pinned.

Smaller docs follow-ups:

  • docs/packages/cli.mdx (the usage section: JSON example and the paragraph that explains session/weekly/spend) doesn't mention monthly yet.
  • skills/hyperframes-cli/references/upgrade-info-misc.md:132: please add monthly to the "Known results contain ..." field list and note that it is null outside Codex, the same way the text describes spend.

Optional: a test that pairs a 5-hour primary with a 30-day secondary would confirm both session and monthly come through together.

Also, the full CI suite hasn't run on this fork yet, so I'll take another look once it's green.

Verdict: COMMENT
Reasoning: The monthly mapping is correct, but monthly should be emitted as null on every harness to match the documented contract and spend, and the full CI has not run on the fork.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants