Skip to content

⏳ feat: Reset Balance Allowances Without Rollover - #16781

Merged
danny-avila merged 5 commits into
devfrom
danny-avila/balance-reset
Oct 5, 2026
Merged

danny-avila merged 5 commits into
devfrom
danny-avila/balance-reset

Conversation

@danny-avila

@danny-avila danny-avila commented Oct 5, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Weekly auto-refill adds credits only when a request would exhaust the balance, allowing unused credits to carry over. I added balance.refillMode: reset to replace the balance with the configured allowance once the period is due, even when credits remain. A balance read or request applies the reset; inactive periods grant one allowance, and the next interval starts at the applied reset.

  • Preserve additive refill as the default for existing configurations and stored balances.
  • Apply one fenced reset across concurrent requests and preserve in-flight reservations.
  • Synchronize current policy before scheduled or interactive resets, persist disabling auto-refill, and reject nonpositive or fractional reset intervals with a runtime guard for invalid stored settings.
  • Record the actual balance adjustment in an idempotent ledger entry, including expiration of excess credits.
  • Show reset timing in the composer and billing settings while keeping percentage mode free of credit and currency figures.

How it works

balance:
  enabled: true
  startBalance: 300000000
  autoRefillEnabled: true
  refillIntervalValue: 1
  refillIntervalUnit: weeks
  refillAmount: 300000000
  refillMode: reset
  display: percent

This gives a $300 allowance and a 0–100% usage display. Once a week is due, the next balance read or admitted request replaces the balance with 300,000,000 credits. It does not add $300 to the remaining balance or accumulate missed periods. Reservations survive the reset, so in-flight requests continue to count against the allowance. No background job or database migration is required.

Related to #16762 and the development rollout in ClickHouse/data-plane-configuration#95589.

Type of change

  • Feature
  • Translation
  • Tests / tooling / CI

Testing

Tested environments/configuration: Node on macOS; real mongodb-memory-server; additive and reset modes; weekly reset with percentage display.

Automated tests:

  • Passed data-schemas transaction.spec.ts: 79 tests, including due resets with remaining/excess/negative credits, concurrent reads and admissions, retained reservations, no repeated/missed-period accumulation, failed ledger replay, and configuration changes during the fenced write.
  • Passed API balance.spec.ts and checkBalance.spec.ts: 61 tests, including direct admission with changed/disabled/reset-to-add policy and concurrent holds, without visiting a balance route.
  • Passed schedule service.spec.ts: 115 tests, including real-database policy synchronization before increased, decreased, unchanged, and disabled resets with held reservations.
  • Passed data-provider config-schemas.spec.ts: 164 tests.
  • Passed client balance utility tests: 12 tests, and the three new reset Summary component tests.
  • Passed data-provider build and tsc --noEmit in data-provider and data-schemas.
  • Passed scoped import sorting, Prettier, and git diff --check.

CI backend/client typechecks and Lighthouse pass on 0bed6aeee4. Local API/client full typechecks are blocked by unrelated missing/outdated agent exports. The full Summary suite has one existing ARIA assertion failure with the reused shared UI build; all new reset tests pass. Local ESLint/static checks and Lighthouse preparation are blocked by the missing @tsdown/css/@shadcn/lint dependencies; the local formatter also uses different class ordering from CI. CI static checks, client tests, API test shards, and Lighthouse pass with the complete installed dependency set.

Screenshots / recordings

Not captured locally: the frontend build is blocked by missing shared UI dependencies. User-visible changes are localized reset wording and timing; layout and theme styles are preserved.

Risk / compatibility

Deploy this version to all server replicas before enabling reset mode. Older servers understand only additive refill. Existing records without refillMode retain additive behavior. The reset replaces stored credits; existing reservations and charges from in-flight requests remain counted. The reset is applied on activity rather than by a wall-clock scheduler.

Checklist

  • I reviewed my own changes
  • Relevant tests have been added or updated
  • Existing relevant backend and configuration tests pass
  • User-facing or complex behavior is documented in the config example and localized UI copy
  • No dependency changes are required
  • CI static checks, client tests, API test shards, backend/client typechecks, and Lighthouse pass on 0bed6aeee4

@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head 24d8683. Confirm that this exact commit is the reviewed commit. Focus on period reset admission, durable ledger replay, preservation of in-flight reservations, and percentage-only UI.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-05T14:50:38.364159Z 0bed6ae Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head 24d8683. Confirm that this exact commit is the reviewed commit. This head synchronizes configuration before a due reset and includes the regression test for changing an allowance at the boundary.

@github-actions

github-actions Bot commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

Lighthouse CI failed. The last 80 log lines contain the measured budgets and assertion failures.


[WebServer] 2026-10-05 13:42:36 info: [StreamServices] Created in-memory stream services

[WebServer] 2026-10-05 13:42:36 info: [GenerationJobManager] Configured with in-memory stores

[WebServer] 2026-10-05 13:42:36 info: HTTP server timeout configuration

[WebServer] 2026-10-05 13:42:36 info: Server listening at http://localhost:3080

[WebServer] 2026-10-05 13:42:36 info: [MCPServersRegistry] Creating new instance

[WebServer] 2026-10-05 13:42:36 info: OAuth reconnect manager initialized successfully.

[WebServer] 2026-10-05 13:42:36 info: Created collection: projects

🤖: global setup has been started
🤖: using baseURL http://localhost:3080
🤖: using E2E user: testuser@example.com
[WebServer] 2026-10-05 13:42:39 info: [agent-triggers] durable delivery engine started

[WebServer] 2026-10-05 13:42:39 info: [schedules] engine started

[WebServer] 2026-10-05 13:42:39 info: Server readiness checks passing.

🤖: 🗝  authenticating user: testuser@example.com
🤖: ✔️  localStorage: set Nav as Visible /home/runner/work/LibreChat/LibreChat/e2e/storageState.json
🤖: ✔️  user successfully registered
[WebServer] 2026-10-05 13:42:52 info: [Login] [Login successful] [Username: testuser@example.com] [Request-IP: ::1] {"requestId":"f9a58e9a-0b3f-405f-99a9-f731fd74239f","request_id":"f9a58e9a-0b3f-405f-99a9-f731fd74239f","request_method":"POST","request_path":"/api/auth"}

🤖: ✔️  user successfully authenticated
🤖: ✔️  authentication state successfully saved in /home/runner/work/LibreChat/LibreChat/e2e/storageState.json
🤖: global setup has been finished

Running 1 test using 1 worker

[1/1] [chrome] › e2e/lighthouse/load.spec.ts:10:5 › serial database latency stays within web-vitals budgets
[chrome] › e2e/lighthouse/load.spec.ts:10:5 › serial database latency stays within web-vitals budgets
Lighthouse run 1/3 wrote /home/runner/work/LibreChat/LibreChat/.lighthouse/lhr-1.report.json

Lighthouse run 2/3 attempt 1 did not complete, retrying: Command failed: /opt/hostedtoolcache/node/24.16.0/x64/bin/node /home/runner/work/LibreChat/LibreChat/node_modules/lighthouse/cli/index.js http://localhost:3080/c/16390000-0000-4000-8000-000000000001 --quiet --preset=desktop --throttling-method=provided --only-categories=performance --chrome-flags=--headless=new --extra-headers={"Cookie":"token_provider=librechat; refreshToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZhYzNhOTU4MDhkZWFlNzFmYTcwNWQ2MyIsInNlc3Npb25JZCI6IjZhYzNhOTVmMDhkZWFlNzFmYTcwNWQ4NCIsImlzc3VlZEF0TXMiOjE3OTEyMDc3NzUxOTQsImlhdCI6MTc5MTIwNzc3NSwiZXhwIjoxNzkxMjExMzc0fQ.FIyMI8dhkJpAU9b6xK-95BLdKG24HfVeMl2pNukCOJY"} --output=json --output=html --output-path=/home/runner/work/LibreChat/LibreChat/.lighthouse/lhr-2

  1) [chrome] › e2e/lighthouse/load.spec.ts:10:5 › serial database latency stays within web-vitals budgets 

    Error: Command failed: /opt/hostedtoolcache/node/24.16.0/x64/bin/node /home/runner/work/LibreChat/LibreChat/node_modules/lighthouse/cli/index.js http://localhost:3080/c/16390000-0000-4000-8000-000000000001 --quiet --preset=desktop --throttling-method=provided --only-categories=performance --chrome-flags=--headless=new --extra-headers={"Cookie":"token_provider=librechat; refreshToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZhYzNhOTU4MDhkZWFlNzFmYTcwNWQ2MyIsInNlc3Npb25JZCI6IjZhYzNhOTVmMDhkZWFlNzFmYTcwNWQ4NCIsImlzc3VlZEF0TXMiOjE3OTEyMDc3NzUxOTQsImlhdCI6MTc5MTIwNzc3NSwiZXhwIjoxNzkxMjExMzc0fQ.FIyMI8dhkJpAU9b6xK-95BLdKG24HfVeMl2pNukCOJY"} --output=json --output=html --output-path=/home/runner/work/LibreChat/LibreChat/.lighthouse/lhr-2
    Runtime error encountered: Something went wrong with recording the trace over your page load. Please run Lighthouse again. (NO_NAVSTART)


    attachment #1: screenshot (image/png) ──────────────────────────────────────────────────────────
    e2e/lighthouse/.test-results/load-serial-database-latency-stays-within-web-vitals-budgets-chrome/test-failed-1.png
    ────────────────────────────────────────────────────────────────────────────────────────────────

    Error Context: e2e/lighthouse/.test-results/load-serial-database-latency-stays-within-web-vitals-budgets-chrome/error-context.md

    attachment #3: trace (application/zip) ─────────────────────────────────────────────────────────
    e2e/lighthouse/.test-results/load-serial-database-latency-stays-within-web-vitals-budgets-chrome/trace.zip
    Usage:

        npx playwright show-trace e2e/lighthouse/.test-results/load-serial-database-latency-stays-within-web-vitals-budgets-chrome/trace.zip

    ────────────────────────────────────────────────────────────────────────────────────────────────


🤖: global teardown has been started
2026-10-05 13:44:30 �[32minfo�[39m: �[32mMongo Connection options�[39m
2026-10-05 13:44:30 �[32minfo�[39m: �[32m{�[39m
�[32m  "bufferCommands": false�[39m
�[32m}�[39m
🤖:  ✅  Connected to Database
🤖:  ✅  Found user in Database
🤖:  ✅  Deleted 1 convos & 2 messages
🤖:  ✅  Deleted user from Database
🤖: global teardown has been started
2026-10-05 13:44:31 �[32minfo�[39m: �[32mMongo Connection options�[39m
2026-10-05 13:44:31 �[32minfo�[39m: �[32m{�[39m
�[32m  "bufferCommands": false�[39m
�[32m}�[39m
🤖:  ✅  Connected to Database
🤖:  ⚠️  User not found in Database
  1 failed
    [chrome] › e2e/lighthouse/load.spec.ts:10:5 › serial database latency stays within web-vitals budgets 

Open the full run

@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head b0bc920. Confirm that this exact commit is the reviewed commit. This head restores the existing class ordering required by CI; reset behavior is unchanged.

@codegraph-librechat codegraph-librechat Bot added 🗺️ Billing Engine codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🛡️ security review labels Oct 5, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 25f71a397f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/api/src/middleware/balance.ts
Comment thread packages/data-schemas/src/methods/transaction.ts
Comment thread packages/data-provider/src/config.ts Outdated
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head d72ba3d. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads. The three findings are addressed together with real-database scheduled policy transition tests and runtime interval guards.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d72ba3d4ac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/data-provider/src/config.ts Outdated
Comment thread packages/data-schemas/src/methods/transaction.ts
Comment thread packages/api/src/middleware/checkBalance.ts Outdated
@danny-avila

Copy link
Copy Markdown
Collaborator Author

@codex review

Please review the current PR head 0bed6ae. Confirm that this exact commit is the reviewed commit and ignore findings that apply only to earlier heads. Current policy now synchronizes inside direct admission, and reset intervals require positive integers. Mixed-version activation is explicitly staged: reset stays off until all replicas support it, as documented in the config example and the gated draft DPC rollout.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 0bed6aeee4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@danny-avila
danny-avila merged commit 0fea024 into dev Oct 5, 2026
45 checks passed
@danny-avila
danny-avila deleted the danny-avila/balance-reset branch October 5, 2026 15:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🗺️ Billing Engine codegraph: the taxonomy area this belongs to (classifier, confidence ≥ 0.9) 🛡️ security review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant