fix: correct the Altimate Base wallet-exhaustion message (does not reset daily)

Merged
AN
2mo ago
+43-11

Issue for this PR

Closes #

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

Fixes a real user-facing bug the e2e suite surfaced (test/altimate/altimate-base-rate-limit-messages.test.ts, PR #1248): when a user exhausts their per-user Altimate Base wallet, describeRateLimit told them the free allowance "resets tomorrow." That's false for this case.

Confirmed semantics (altimate-gateway, not guessed):

  • Per-user wallet — never resets. issuer/config.py:57 — grant_budget_duration defaults to "". The comment above it (issuer/config.py:54-56) states: "Empty = never reset. Enforcement is lifetime-cumulative (see budget_sync.py); daily free-tier quotas are implemented as daily CREDIT grants from the billing owner, not LiteLLM budget resets." issuer/config.py:142-146 — validate() raises RuntimeError if grant_budget_duration is ever set, because "max_budget mirrors a lifetime allowance, and daily quotas require daily credit grants." issuer/accounting_db.py:576 — the wallet is funded by a one-time registration grant, docstring: "Create the one-time registration grant without later top-ups." issuer/budget_sync.py:15-24 — sync_current_wallet_budget mirrors the lifetime allowance into LiteLLM's max_budget with no budget_duration, explicitly because a resetting duration "would re-grant the full wallet every period."
  • Global ceiling — genuinely resets daily. litellm/config.yaml:96-106 — a shared max_budget: 50 with budget_duration: 1d, comment: "Global daily ceiling across EVERY key, on top of the per-principal budget... Verified enforcing: further requests return 429 with 'Budget has been exceeded! Current cost: ... Max budget: ...'."

So the two budget_exceeded branches in describeRateLimit really are semantically different — the wallet case never renews, the global case renews every day — and only the global message should promise a reset.

Old wallet message:

You've used today's free Altimate Base allowance. It resets tomorrow—switch models to keep going.

Final wallet message (corrected, then a sign-up nudge added on top):

You've used your free Altimate Base allowance — it's a one-time grant and won't renew. Sign up at app.myaltimate.com to keep going, or switch models.

Global ceiling message — unchanged (still correct):

Altimate Base has reached its shared daily limit. It resets tomorrow—switch models to keep going.

Where this lands: the message and the test that pins it are both new in #1199 (codex/altimate-base-release-final) — client.ts doesn't exist on main at all. #1248 (test/altimate-base-e2e, stacked on #1199) owns altimate-base-rate-limit-messages.test.ts, including the comment on the wallet-budget test that explicitly flagged this message as misleading while pinning current behavior. This PR is branched off test/altimate-base-e2e so the message fix and its test update land together in the branch that already owns both, rather than fragmenting the change across two feature branches.

Follow-up commit: sign-up nudge + public usage-limits doc

Once the wallet-exhaustion case had no reset to promise, the only actionable next step for a user is switching models or upgrading — so the message now points to the paid Altimate LLM Gateway sign-up flow, app.myaltimate.com (register?client=altimate-code, confirmed in src/altimate/plugin/altimate.ts's DEFAULT_WEB_URL). The global-ceiling message is untouched.

Also adds a public, sanitized "Usage limits" section to docs/docs/configure/providers.md under Altimate Base, covering: personal one-time allowance vs. shared daily capacity (which resets daily), rate limiting, and request size limits — each mapped to what the user should do about it. No model name, architecture, or exact numeric thresholds (those stay in the internal gateway-repo doc); only the already-public context/output limits (131K/65K) are stated. In the same section, also removed a pre-existing "Qwen 3.8" model-name mention from the Altimate Base intro paragraph (introduced in #1199), which violated the no-model-name-in-public-docs constraint this new section is written to.

app.myaltimate.com is the public product domain, already present elsewhere in source, and is not one of the hosts script/check-tracker-leaks.ts blocks (it only flags our internal-only hostname, Jira ticket keys, and the Atlassian instance URL) — verified clean.

How did you verify your code works?

  • bun test test/altimate/altimate-base-rate-limit-messages.test.ts — 21 pass, 0 fail (from packages/opencode)
  • bun run typecheck (from packages/opencode) — clean
  • bun run script/upstream/analyze.ts --markers --base origin/main --strict — ok, client.ts is not an upstream-shared file so no markers were needed
  • bun script/check-tracker-leaks.ts — clean (exit 0, silent); confirms app.myaltimate.com is not flagged and no internal hostname/ticket references leaked
  • Read the message change alongside the other three describeRateLimit messages in client.ts (throttle-tokens, throttle-burst, budget-global, budget-unknown) to keep tone/format consistent; only the wallet branch changed
  • Test now asserts the exact new wallet message plus explicit toContain("app.myaltimate.com") / not.toContain("resets tomorrow") checks; the global-ceiling and budget-unknown test cases are untouched and still assert "resets tomorrow"

Screenshots / recordings

N/A — text and docs changes only, no UI.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

[!NOTE]
Low Risk
User-facing text and documentation only; no auth, billing, or inference logic changes beyond error-message strings for one 429 branch.

Overview
Fixes misleading Altimate Base copy when a user hits the per-installation wallet (ExceededBudget: User=): the UI no longer says the allowance “resets tomorrow.” It now states the grant is one-time, won’t renew, and points users to app.myaltimate.com or another model. The shared daily ceiling message is unchanged.

describeRateLimit in client.ts and the budget-wallet test in altimate-base-rate-limit-messages.test.ts are updated together, with comments documenting gateway semantics (lifetime wallet vs daily global pool).

Providers docs expand the Altimate Base section: clearer intro (including public 131K/65K limits, no model name), plus a new Usage limits subsection (personal allowance, shared daily capacity, rate limits, request size) aligned with the actionable errors users see.

Reviewed by Cursor Bugbot for commit 59b046ae0e1f117f4f1508be55c3f5e13fad60c5. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by cubic

Fixes the Altimate Base wallet-exhaustion message so it no longer claims the per-user allowance resets daily; the per-user wallet is a one-time lifetime grant and only the shared global daily ceiling renews. The message now points users to sign up at app.myaltimate.com.

  • Expands the Altimate Base docs with a "Usage limits" section and corrects the intro to describe Altimate Base as pseudonymous, not anonymous.
  • Updates the wallet-budget test assertion to match the corrected message.