From ada5c2eeab9c0d1304dcd7dcdbb74dd4f58ef339 Mon Sep 17 00:00:00 2001 From: shivam <91240327+shivamhwp@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:41:50 +0000 Subject: [PATCH 1/4] fix(server): banked Claude resets you can't use yet stay listed with the reason Co-Authored-By: Claude Fable 5.2 --- .../src/features/usage/UsageLimitsSection.tsx | 14 ++- .../src/provider/claudeResetCredits.test.ts | 85 ++++++++++++++++--- .../server/src/provider/claudeResetCredits.ts | 73 ++++++++++++++-- apps/web/src/components/usage/UsageLimits.tsx | 14 ++- .../components/usage/UsageLimitsPooled.tsx | 6 +- docs/user/usage.md | 1 + packages/contracts/src/providerUsageLimits.ts | 2 + packages/shared/src/usageLimits.ts | 8 ++ 8 files changed, 172 insertions(+), 31 deletions(-) diff --git a/apps/mobile/src/features/usage/UsageLimitsSection.tsx b/apps/mobile/src/features/usage/UsageLimitsSection.tsx index be4bf0c929d11..9d219a644dc5a 100644 --- a/apps/mobile/src/features/usage/UsageLimitsSection.tsx +++ b/apps/mobile/src/features/usage/UsageLimitsSection.tsx @@ -221,8 +221,7 @@ export function AccountLimits(props: { ); } -const OUTCOME_TEXT: Record = { - reset: "Reset applied. Your windows have cleared.", +const OUTCOME_TEXT: Record, string> = { nothingToReset: "Nothing to reset right now.", noCredit: "No reset credit left.", alreadyRedeemed: "That credit was already redeemed.", @@ -251,7 +250,12 @@ export function ResetCredits(props: { const result = await consume({ environmentId, input: choice.input }); setBusy(false); if (result._tag === "Success") { - setStatus(result.value.warning ?? OUTCOME_TEXT[result.value.outcome]); + setStatus( + result.value.warning ?? + (result.value.outcome === "reset" + ? choice.appliedText + : OUTCOME_TEXT[result.value.outcome]), + ); return; } setStatus( @@ -274,7 +278,9 @@ export function ResetCredits(props: { {resetCreditChoices(credits, input, now).map((choice) => ( {choice.summary} - {choice.availableCount > 0 ? ( + {choice.unavailableReason ? ( + {choice.unavailableReason} + ) : choice.availableCount > 0 ? ( { NOW, ), ).toEqual({ - availableCount: 2, + availableCount: 5, nextCreditId: "grant_a", nextExpiresAt: "2026-10-01T00:00:00.000Z", options: [ - expect.objectContaining({ + { creditId: "grant_a", label: "Full reset", - availableCount: 2, + description: "Refills your 5-hour and weekly limits.", + availableCount: 5, expiresAt: "2026-10-01T00:00:00.000Z", - }), + }, ], }); }); @@ -107,18 +108,74 @@ describe("claudeResetCreditsToContract", () => { expect(credits).toMatchObject({ availableCount: 4, nextCreditId: "weekly_a" }); }); - it("offers nothing to redeem without a usable next grant or an eligible account", () => { - expect( - ClaudeResetCredits.claudeResetCreditsToContract( - { eligible: true, next_grant_id: "grant_a", grants: [grant({ usable_now: false })] }, + it.each([ + [{}, {}, "Usable once you reach a limit it refills"], + [{ use_requires_limit: false }, {}, "Can't be used right now"], + [{}, { cooldown_until: "2026-09-22T12:01:00Z" }, "Try again in a minute"], + [{}, { cooldown_until: "2026-09-22T11:59:00Z" }, "Usable once you reach a limit it refills"], + [{ blocking: ["five_hour"] }, {}, "Can't be used while you're at your 5-hour limit"], + [ + { blocking: ["seven_day"], gives_back_weekly: true }, + {}, + "No Fable usage this week to give back", + ], + [ + { blocking: ["seven_day_cowork"] }, + {}, + "Can't be used while you're at a limit it doesn't refill", + ], + [ + { clears: ["five_hour"] }, + { at_limit: true, exhausted: ["seven_day"] }, + "Doesn't refill the limit you've reached", + ], + [{ unavailable_reason: "cooldown", blocking: ["five_hour"] }, {}, "Try again in a minute"], + ])( + "keeps a banked reset that can't be used yet and says why: %j %j", + (overrides, status, why) => { + const credits = ClaudeResetCredits.claudeResetCreditsToContract( + { + eligible: true, + next_grant_id: "grant_a", + grants: [grant({ usable_now: false, ...overrides })], + ...status, + }, NOW, - ), - ).toEqual({ availableCount: 0 }); + ); + expect(credits).toEqual({ + availableCount: 1, + options: [expect.objectContaining({ creditId: "grant_a", unavailableReason: why })], + }); + }, + ); + + it("offers a usable reset beside one that is waiting, whichever Claude names next", () => { + const credits = ClaudeResetCredits.claudeResetCreditsToContract( + { + eligible: true, + next_grant_id: "full_a", + grants: [ + grant({ id: "full_a", type: "full", usable_now: false }), + grant({ id: "fable_wait", gives_back_weekly: true, usable_now: false }), + grant({ id: "fable_a", gives_back_weekly: true }), + ], + }, + NOW, + ); + expect(credits?.nextCreditId).toBeUndefined(); expect( - ClaudeResetCredits.claudeResetCreditsToContract({ eligible: true, grants: [grant({})] }, NOW), - ).toEqual({ - availableCount: 0, - }); + credits?.options?.map(({ creditId, availableCount, unavailableReason }) => [ + creditId, + availableCount, + unavailableReason, + ]), + ).toEqual([ + ["fable_a", 2, undefined], + ["full_a", 1, "Usable once you reach a limit it refills"], + ]); + }); + + it("offers nothing to redeem without an eligible account", () => { expect( ClaudeResetCredits.claudeResetCreditsToContract( { eligible: false, grants: [grant({})] }, diff --git a/apps/server/src/provider/claudeResetCredits.ts b/apps/server/src/provider/claudeResetCredits.ts index d2000804cf4f6..a6477d4a17d04 100644 --- a/apps/server/src/provider/claudeResetCredits.ts +++ b/apps/server/src/provider/claudeResetCredits.ts @@ -35,15 +35,21 @@ const Grant = Schema.Struct({ ends_at: Schema.optional(Schema.NullOr(Schema.String)), paused: Schema.optional(Schema.Boolean), usable_now: Schema.optional(Schema.Boolean), + use_requires_limit: Schema.optional(Schema.Boolean), clears: Schema.optional(Schema.Array(Schema.Unknown)), + blocking: Schema.optional(Schema.Array(Schema.Unknown)), type: Schema.optional(Schema.Unknown), gives_back_weekly: Schema.optional(Schema.Boolean), + unavailable_reason: Schema.optional(Schema.Unknown), }); const decodeGrant = Schema.decodeUnknownOption(Grant); const CedarEmber = Schema.Struct({ eligible: Schema.Boolean, grants: Schema.optional(Schema.Array(Schema.Unknown)), next_grant_id: Schema.optional(Schema.NullOr(Schema.String)), + at_limit: Schema.optional(Schema.Unknown), + exhausted: Schema.optional(Schema.Unknown), + cooldown_until: Schema.optional(Schema.Unknown), }); const UsageResponse = Schema.Struct({ cedar_ember: Schema.optional(Schema.NullOr(Schema.Unknown)), @@ -127,6 +133,58 @@ const grantKind = (grant: typeof Grant.Type): ResetKind => { return session && !other ? "session" : other && !session ? "weekly" : "full"; }; +const WAITING_REASONS = { + cooldown: "Try again in a minute", + blocked_five_hour: "Can't be used while you're at your 5-hour limit", + blocked_seven_day: "Can't be used while you're at your weekly limit", + blocked_opus: "Can't be used while you're at your weekly Opus limit", + blocked_sonnet: "Can't be used while you're at your weekly Sonnet limit", + blocked_other: "Can't be used while you're at a limit it doesn't refill", + cannot_clear: "Doesn't refill the limit you've reached", + needs_limit: "Usable once you reach a limit it refills", + unavailable: "Can't be used right now", +} as const; +const BLOCKING_REASONS: Record = { + five_hour: "blocked_five_hour", + seven_day: "blocked_seven_day", + seven_day_opus: "blocked_opus", + seven_day_sonnet: "blocked_sonnet", +}; + +// Claude Code's own order: the server's stated reason, else a cooldown, what blocks the grant, +// a limit it can't clear, and last whether it needs a limit at all. +const waitingReason = ( + grant: typeof Grant.Type, + status: typeof CedarEmber.Type, + nowMs: number, +): string => { + const stated = grant.unavailable_reason; + if (typeof stated === "string" && stated in WAITING_REASONS) { + return WAITING_REASONS[stated as keyof typeof WAITING_REASONS]; + } + const cooldown = status.cooldown_until; + if (typeof cooldown === "string" && isFutureTimestamp(cooldown, nowMs)) { + return WAITING_REASONS.cooldown; + } + const blocking = grant.blocking ?? []; + for (const limit of blocking) { + const reason = typeof limit === "string" ? BLOCKING_REASONS[limit] : undefined; + if (reason === "blocked_seven_day" && grant.gives_back_weekly) { + return "No Fable usage this week to give back"; + } + if (reason) return WAITING_REASONS[reason]; + } + if (blocking.length > 0) return WAITING_REASONS.blocked_other; + const exhausted = Array.isArray(status.exhausted) ? status.exhausted : []; + const clears = (limit: unknown) => + (grant.clears ?? []).includes(limit) || (limit === "seven_day" && grant.gives_back_weekly); + if (status.at_limit === true && !exhausted.some(clears)) return WAITING_REASONS.cannot_clear; + return grant.use_requires_limit === false + ? WAITING_REASONS.unavailable + : WAITING_REASONS.needs_limit; +}; + +/** Every reset still banked stays listed; one Claude won't take right now says why instead. */ export function claudeResetCreditsToContract( block: unknown, nowMs: number, @@ -137,11 +195,9 @@ export function claudeResetCreditsToContract( .flatMap((raw) => Option.toArray(decodeGrant(raw))) .filter( (grant) => - !grant.paused && - grant.usable_now && - (grant.ends_at == null || isFutureTimestamp(grant.ends_at, nowMs)), + !grant.paused && (grant.ends_at == null || isFutureTimestamp(grant.ends_at, nowMs)), ); - const next = live.find((grant) => grant.id === parsed.value.next_grant_id); + const next = live.find((grant) => grant.usable_now && grant.id === parsed.value.next_grant_id); const expiresAt = (grant: typeof Grant.Type | undefined) => { const at = grant?.ends_at ? DateTime.make(grant.ends_at) : Option.none(); return Option.isSome(at) ? DateTime.formatIso(at.value) : undefined; @@ -155,7 +211,7 @@ export function claudeResetCreditsToContract( const options = (Object.keys(RESET_KINDS) as Array).flatMap( (kind): Array => { const grants = byKind.get(kind); - const target = grants?.[0]; + const target = grants?.find((grant) => grant.usable_now) ?? grants?.[0]; if (!grants || !target) return []; const optionExpiresAt = expiresAt(target); return [ @@ -164,16 +220,19 @@ export function claudeResetCreditsToContract( ...RESET_KINDS[kind], availableCount: grants.reduce((sum, grant) => sum + grant.resets_left, 0), ...(optionExpiresAt ? { expiresAt: optionExpiresAt } : {}), + ...(target.usable_now + ? {} + : { unavailableReason: waitingReason(target, parsed.value, nowMs) }), }, ]; }, ); const nextExpiresAt = expiresAt(next); return { - availableCount: next ? live.reduce((sum, grant) => sum + grant.resets_left, 0) : 0, + availableCount: live.reduce((sum, grant) => sum + grant.resets_left, 0), ...(nextExpiresAt ? { nextExpiresAt } : {}), ...(next ? { nextCreditId: next.id } : {}), - ...(next ? { options } : {}), + ...(options.length > 0 ? { options } : {}), }; } diff --git a/apps/web/src/components/usage/UsageLimits.tsx b/apps/web/src/components/usage/UsageLimits.tsx index e41aa20998b1c..05b829b31820e 100644 --- a/apps/web/src/components/usage/UsageLimits.tsx +++ b/apps/web/src/components/usage/UsageLimits.tsx @@ -231,8 +231,7 @@ export function LimitWindows({ ); } -const OUTCOME_TEXT: Record = { - reset: "Reset applied. Your windows have cleared.", +const OUTCOME_TEXT: Record, string> = { nothingToReset: "Nothing to reset right now.", noCredit: "No reset credit left.", alreadyRedeemed: "That credit was already redeemed.", @@ -255,7 +254,12 @@ export function useResetCredit(environmentId: EnvironmentId) { const result = await consume({ environmentId, input: choice.input }); setBusy(false); if (result._tag === "Success") { - setStatus(result.value.warning ?? OUTCOME_TEXT[result.value.outcome]); + setStatus( + result.value.warning ?? + (result.value.outcome === "reset" + ? choice.appliedText + : OUTCOME_TEXT[result.value.outcome]), + ); return; } setStatus( @@ -326,7 +330,9 @@ export function ResetCredits({ {resetCreditChoices(credits, input, now).map((choice) => (
{choice.summary} - {choice.availableCount > 0 ? ( + {choice.unavailableReason ? ( + {choice.unavailableReason} + ) : choice.availableCount > 0 ? (