Skip to content

fix(credits): seed cold-start usage gauge from subscription.credits_remaining - #41221

Open
entropy-0x wants to merge 1 commit into
NousResearch:mainfrom
entropy-0x:fix/cold-start-credits-subscription-remaining-field
Open

entropy-0x wants to merge 1 commit into
NousResearch:mainfrom
entropy-0x:fix/cold-start-credits-subscription-remaining-field

Conversation

@entropy-0x

Copy link
Copy Markdown

The cold-start credits seed computed the subscription usage fraction from a
mismatched pair of fields: the numerator came from
paid_service_access_info.subscription_credits_remaining while the
denominator came from subscription.monthly_credits. The canonical /usage
gauge (build_nous_credits_snapshot) pairs subscription.credits_remaining
with subscription.monthly_credits, and the two remaining-balance fields can
hold different values. As a result the cold-start usage-band notices (50/75/90%)
were derived from a different balance than the gauge and could fire at the wrong
threshold or stay silent when the user was actually over a band.

This aligns the seed's numerator with its denominator so the session-open band
notice matches what /usage displays.

What does this PR do?

Fixes the field source used to compute the subscription used_fraction in the
cold-start credits seed. _credits_state_from_account now reads the subscription
remaining balance from subscription.credits_remaining — the same object that
supplies the denominator subscription.monthly_credits — instead of the
unrelated paid_service_access_info.subscription_credits_remaining. This makes
the session-open usage-band notices consistent with the /usage gauge.

Related Issue

N/A

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

  • agent/credits_tracker.py: in _credits_state_from_account, read the
    subscription remaining balance from subscription.credits_remaining (paired
    with subscription.monthly_credits) for both subscription_micros and
    subscription_usd, instead of paid_service_access_info.subscription_credits_remaining.
  • tests/agent/test_credits_cold_start.py: add two regression tests that build
    an account where the two remaining-balance fields differ and assert the seed's
    used_fraction matches the subscription-object pairing and fires the usage band.

How to Test

  1. python -m pytest tests/agent/test_credits_cold_start.py -q — passes.
  2. Revert the one-line field change and rerun: the two new tests fail
    (used_fraction is 0.10 instead of 0.75, and no credits.usage notice fires).
  3. python -m pytest tests/agent/test_credits_tracker.py tests/agent/test_credits_policy.py tests/agent/test_nous_credits_gauge.py tests/agent/test_nous_credits_snapshot.py tests/agent/test_credits_fixture_snapshot.py -q — 166 tests pass.

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run the affected suites (tests/agent/test_credits_*, 166 tests) and they pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: macOS 15 (Darwin 25.5)

Documentation & Housekeeping

  • I've updated relevant documentation (README, docs/, docstrings) — or N/A
  • I've updated cli-config.yaml.example if I added/changed config keys — or N/A
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A

…emaining

The cold-start credits seed computed the subscription usage fraction from a
mismatched pair of fields: the numerator came from
`paid_service_access_info.subscription_credits_remaining` while the
denominator came from `subscription.monthly_credits`. The canonical /usage
gauge (`build_nous_credits_snapshot`) pairs `subscription.credits_remaining`
with `subscription.monthly_credits`, and the two remaining-balance fields can
hold different values. As a result the cold-start usage-band notices (50/75/90%)
were derived from a different balance than the gauge and could fire at the wrong
threshold or stay silent when the user was actually over a band.

This aligns the seed's numerator with its denominator so the session-open band
notice matches what /usage displays.

## What does this PR do?

Fixes the field source used to compute the subscription used_fraction in the
cold-start credits seed. `_credits_state_from_account` now reads the subscription
remaining balance from `subscription.credits_remaining` — the same object that
supplies the denominator `subscription.monthly_credits` — instead of the
unrelated `paid_service_access_info.subscription_credits_remaining`. This makes
the session-open usage-band notices consistent with the /usage gauge.

## Related Issue

N/A

## Type of Change

- [x] 🐛 Bug fix (non-breaking change that fixes an issue)
- [ ] ✨ New feature (non-breaking change that adds functionality)
- [ ] 🔒 Security fix
- [ ] 📝 Documentation update
- [ ] ✅ Tests (adding or improving test coverage)
- [ ] ♻️ Refactor (no behavior change)
- [ ] 🎯 New skill (bundled or hub)

## Changes Made

- `agent/credits_tracker.py`: in `_credits_state_from_account`, read the
  subscription remaining balance from `subscription.credits_remaining` (paired
  with `subscription.monthly_credits`) for both `subscription_micros` and
  `subscription_usd`, instead of `paid_service_access_info.subscription_credits_remaining`.
- `tests/agent/test_credits_cold_start.py`: add two regression tests that build
  an account where the two remaining-balance fields differ and assert the seed's
  `used_fraction` matches the subscription-object pairing and fires the usage band.

## How to Test

1. `python -m pytest tests/agent/test_credits_cold_start.py -q` — passes.
2. Revert the one-line field change and rerun: the two new tests fail
   (`used_fraction` is 0.10 instead of 0.75, and no `credits.usage` notice fires).
3. `python -m pytest tests/agent/test_credits_tracker.py tests/agent/test_credits_policy.py tests/agent/test_nous_credits_gauge.py tests/agent/test_nous_credits_snapshot.py tests/agent/test_credits_fixture_snapshot.py -q` — 166 tests pass.

## Checklist

### Code

- [x] I've read the [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md)
- [x] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix(scope):`, `feat(scope):`, etc.)
- [x] I searched for [existing PRs](https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate
- [x] My PR contains **only** changes related to this fix/feature (no unrelated commits)
- [x] I've run the affected suites (`tests/agent/test_credits_*`, 166 tests) and they pass
- [x] I've added tests for my changes (required for bug fixes, strongly encouraged for features)
- [x] I've tested on my platform: macOS 15 (Darwin 25.5)

### Documentation & Housekeeping

- [x] I've updated relevant documentation (README, `docs/`, docstrings) — or N/A
- [x] I've updated `cli-config.yaml.example` if I added/changed config keys — or N/A
- [x] I've updated `CONTRIBUTING.md` or `AGENTS.md` if I changed architecture or workflows — or N/A
- [x] I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
- [x] I've updated tool descriptions/schemas if I changed tool behavior — or N/A
@daimon-nous daimon-nous Bot added type/bug Something isn't working comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint provider/nous Nous Research API (OAuth) P3 Low — cosmetic, nice to have labels Jun 7, 2026
@teknium1

Copy link
Copy Markdown
Collaborator

Thanks for the focused regression fix. The premise remains valid on current main: agent/credits_tracker.py:705-706 derives the cold-start subscription balance from paid_service_access_info, while /usage derives its gauge from subscription.credits_remaining at agent/account_usage.py:172-181. The patch aligns those sources and its differing-balance tests exercise both the computed fraction and usage-band outcome.

Automated hermes-sweeper review.

@teknium1 teknium1 added sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform area/usage-cost Token accounting, usage reporting, billing, cost tracking labels Jul 14, 2026

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

area/usage-cost Token accounting, usage reporting, billing, cost tracking comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint P3 Low — cosmetic, nice to have provider/nous Nous Research API (OAuth) sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform type/bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants