Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-claude-usage-credits-gauge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Overview usage gauge shows Claude's usage credits (extra usage) under the Claude dials when Claude reports them: on or off, and how much of the monthly cap is spent, for example "Usage credits: on · $0.00 of $350.00 used this month", with "limit reached" in amber once the cap is spent. The line is hidden when Claude does not report it, and it is display only. `/api/providers/headroom` carries the same reading as `extra_usage`. Claude's usage endpoint does not report a purchased credit balance or banked limit resets, so those are not shown.
2 changes: 1 addition & 1 deletion src/docs/api-reference/cost-tokens-telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,5 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/cost/history` | Dashboard auth/session | Cost History | `pkg/dashboard/api.go:151` |
| `GET` | `/api/trend/history` | Dashboard auth/session | Trend History | `pkg/dashboard/api.go:154` |
| `GET` | `/api/timeseries` | Dashboard auth/session | Time Series | `pkg/dashboard/api.go:156` |
| `GET` | `/api/providers/headroom` | Owner only | Last stored per-provider usage readings (`providers[]` with `limits[]`, `captured_at`, `stale`, `probe_error_cause`, and `plan_type` when a provider reports one), from provider rotation or the default publish-only reading, plus `used_by`: per provider, the enabled agents whose backend spends its plan; serving it never triggers a new measurement. Feeds the Overview usage gauge and the rotation settings table | `pkg/dashboard/api.go:65` |
| `GET` | `/api/providers/headroom` | Owner only | Last stored per-provider usage readings (`providers[]` with `limits[]`, `captured_at`, `stale`, `probe_error_cause`, `plan_type` when a provider reports one, and for Claude `extra_usage` when reported: `enabled`, `used_minor`, `limit_minor`, `exponent`, `currency`, `spend_limit_reached`, each left out when unknown), from provider rotation or the default publish-only reading, plus `used_by`: per provider, the enabled agents whose backend spends its plan; serving it never triggers a new measurement. Feeds the Overview usage gauge and the rotation settings table | `pkg/dashboard/api.go:65` |
| `GET` | `/api/budget/history` | Dashboard auth/session | Budget History | `pkg/dashboard/api.go:153` |
8 changes: 8 additions & 0 deletions src/docs/dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,14 @@ with the percentage left and when it resets:
- **Claude**: the weekly limit, plus a 5-hour or model-specific weekly limit
when the plan has one. A model-specific limit is named after its model the
way Claude Code's `/usage` names it, for example "Weekly (Fable)".
Under the dials, one line shows Claude's usage credits (extra usage, which
keeps the account working past a plan limit) when Claude reports them:
"Usage credits: on · $0.00 of $350.00 used this month", "off", or "limit
reached" in amber once the monthly cap is spent. The line is hidden when
Claude does not report them. It is display only: the hive never turns
credits on or spends them. Claude's usage endpoint does not report a
purchased credit balance or banked limit resets, so the gauge cannot show
those; claude.ai's Settings › Usage page does.
- **Copilot**: the monthly premium-request quota ("Premium requests"), as
Copilot itself reports it, resetting at the start of each month.

Expand Down
2 changes: 2 additions & 0 deletions src/pkg/dashboard/static-src/css/overview.css

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

31 changes: 31 additions & 0 deletions src/pkg/dashboard/static-src/js/subscription-gauge.js
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,31 @@
};
// Paid credit pools and prepaid balances are not plan limits.
const NOT_LIMITS = ['credits', 'balance'];
// Claude's extra usage (usage credits past the plan limits) as one
// line: on/off and spent of the monthly cap. null hides the line: the
// provider did not say, which is never shown as 0 or off. Display
// only; the dashboard never turns credits on or spends them.
const creditsFor = (x) => {
if (!x || typeof x !== 'object' || Array.isArray(x)) return null;
const enabled = typeof x.enabled === 'boolean' ? x.enabled : null;
const reached = x.spend_limit_reached === true;
const exp = Number.isInteger(x.exponent) && x.exponent >= 0 && x.exponent <= 6 ? x.exponent : 2;
const amount = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v / Math.pow(10, exp) : null);
const used = amount(x.used_minor);
const cap = amount(x.limit_minor);
const currency = String(x.currency || '').toUpperCase();
const money = (n) => (currency === 'USD' || currency === '' ? '$' + n.toFixed(exp) : n.toFixed(exp) + ' ' + currency);
const parts = [];
if (reached) parts.push('limit reached');
else if (enabled !== null) parts.push(enabled ? 'on' : 'off');
if (enabled !== false) {
if (used !== null && cap !== null) parts.push(money(used) + ' of ' + money(cap) + ' used this month');
else if (cap !== null) parts.push(money(cap) + ' monthly cap');
else if (used !== null) parts.push(money(used) + ' used this month');
}
if (!parts.length) return null;
return { text: 'Usage credits: ' + parts.join(' · '), status: reached ? 'warn' : 'ok', enabled: enabled, limitReached: reached, used: used, cap: cap, currency: currency };
};
// listed: the provider is in used_by, so agents spend it and a missing
// or failed reading is worth saying. Unlisted (a server without
// used_by) keeps the Claude-only rule: hidden when Claude is not used.
Expand Down Expand Up @@ -127,6 +152,7 @@
ageMs: ageMs,
outOfDate: !!reading.stale || (ageMs !== null && ageMs > OUT_OF_DATE_MS),
planName: String(reading.plan_type || ''),
credits: creditsFor(reading.extra_usage),
accountNote: 'Reflects the ' + name + ' account this hive is signed in with.',
});
};
Expand Down Expand Up @@ -339,6 +365,11 @@
grid.appendChild(cell);
});
box.appendChild(grid);
if (row.credits) {
const credits = el('div', 'overview-usage-gauge__credits', row.credits.text);
credits.setAttribute('data-status', row.credits.status);
box.appendChild(credits);
}
}
parts.push(box);
});
Expand Down
33 changes: 33 additions & 0 deletions src/pkg/dashboard/static/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -3863,6 +3863,8 @@
.overview-usage-gauge__provider { font-weight: var(--fw-semibold); }
.overview-usage-gauge__users { font-size: var(--fs-sm); color: var(--text-muted); overflow-wrap: anywhere; }
.overview-usage-gauge__spend { font-size: var(--fs-base); font-weight: 600; }
.overview-usage-gauge__credits { font-size: var(--fs-sm); color: var(--text-muted); }
.overview-usage-gauge__credits[data-status="warn"] { color: var(--status-warn); font-weight: 600; }
.overview-usage-gauge__dials { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: var(--sp-4); }
.overview-usage-gauge__dial { display: flex; flex-direction: column; align-items: center; gap: var(--sp-1); text-align: center; }
.overview-usage-gauge__label { font-weight: var(--fw-semibold); }
Expand Down Expand Up @@ -57747,6 +57749,31 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
};
// Paid credit pools and prepaid balances are not plan limits.
const NOT_LIMITS = ['credits', 'balance'];
// Claude's extra usage (usage credits past the plan limits) as one
// line: on/off and spent of the monthly cap. null hides the line: the
// provider did not say, which is never shown as 0 or off. Display
// only; the dashboard never turns credits on or spends them.
const creditsFor = (x) => {
if (!x || typeof x !== 'object' || Array.isArray(x)) return null;
const enabled = typeof x.enabled === 'boolean' ? x.enabled : null;
const reached = x.spend_limit_reached === true;
const exp = Number.isInteger(x.exponent) && x.exponent >= 0 && x.exponent <= 6 ? x.exponent : 2;
const amount = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v / Math.pow(10, exp) : null);
const used = amount(x.used_minor);
const cap = amount(x.limit_minor);
const currency = String(x.currency || '').toUpperCase();
const money = (n) => (currency === 'USD' || currency === '' ? '$' + n.toFixed(exp) : n.toFixed(exp) + ' ' + currency);
const parts = [];
if (reached) parts.push('limit reached');
else if (enabled !== null) parts.push(enabled ? 'on' : 'off');
if (enabled !== false) {
if (used !== null && cap !== null) parts.push(money(used) + ' of ' + money(cap) + ' used this month');
else if (cap !== null) parts.push(money(cap) + ' monthly cap');
else if (used !== null) parts.push(money(used) + ' used this month');
}
if (!parts.length) return null;
return { text: 'Usage credits: ' + parts.join(' · '), status: reached ? 'warn' : 'ok', enabled: enabled, limitReached: reached, used: used, cap: cap, currency: currency };
};
// listed: the provider is in used_by, so agents spend it and a missing
// or failed reading is worth saying. Unlisted (a server without
// used_by) keeps the Claude-only rule: hidden when Claude is not used.
Expand Down Expand Up @@ -57819,6 +57846,7 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
ageMs: ageMs,
outOfDate: !!reading.stale || (ageMs !== null && ageMs > OUT_OF_DATE_MS),
planName: String(reading.plan_type || ''),
credits: creditsFor(reading.extra_usage),
accountNote: 'Reflects the ' + name + ' account this hive is signed in with.',
});
};
Expand Down Expand Up @@ -58031,6 +58059,11 @@ <h3 class="modal-h">How Agents Use Knowledge (Priming)</h3>
grid.appendChild(cell);
});
box.appendChild(grid);
if (row.credits) {
const credits = el('div', 'overview-usage-gauge__credits', row.credits.text);
credits.setAttribute('data-status', row.credits.status);
box.appendChild(credits);
}
}
parts.push(box);
});
Expand Down
37 changes: 37 additions & 0 deletions src/pkg/dashboard/subscription_gauge.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -234,3 +234,40 @@ test('a one-provider hive reads exactly as before at the top level', () => {
assert.deepEqual(plain(m.dials.map(d => d.label)), ['Weekly', 'Weekly (Fable)']);
assert.equal(m.accountNote, 'Reflects the Claude account this hive is signed in with.');
});

// Claude's extra usage, shaped like the live /api/oauth/usage reading the
// prober serializes (2026-11-19): on, $0.00 of a $350.00 monthly cap.
const EXTRA_ON = { enabled: true, used_minor: 0, limit_minor: 35000, exponent: 2, currency: 'USD', spend_limit_reached: false };

test('extra usage on shows spent of the monthly cap', () => {
const m = model(resp({ limits: [limit('weekly_all', 'weekly', 54, 10080)], extra_usage: EXTRA_ON }), NOW);
assert.equal(m.credits.text, 'Usage credits: on · $0.00 of $350.00 used this month');
assert.equal(m.credits.status, 'ok');
assert.equal(m.rows[0].credits.text, m.credits.text);
});

test('extra usage off says off and no amounts', () => {
const m = model(resp({ limits: [limit('weekly_all', 'weekly', 54, 10080)], extra_usage: { enabled: false, exponent: 2 } }), NOW);
assert.equal(m.credits.text, 'Usage credits: off');
});

test('spend limit reached is a warning', () => {
const m = model(resp({ limits: [limit('weekly_all', 'weekly', 54, 10080)], extra_usage: Object.assign({}, EXTRA_ON, { used_minor: 35000, spend_limit_reached: true }) }), NOW);
assert.equal(m.credits.text, 'Usage credits: limit reached · $350.00 of $350.00 used this month');
assert.equal(m.credits.status, 'warn');
});

test('no extra usage reported hides the line (never shown as 0 or off)', () => {
for (const extra of [undefined, null, {}, { exponent: 2 }, 'on', []]) {
const r = { limits: [limit('weekly_all', 'weekly', 54, 10080)] };
if (extra !== undefined) r.extra_usage = extra;
const m = model(resp(r), NOW);
assert.equal(m.state, 'reading');
assert.equal(m.credits, null, JSON.stringify(extra));
}
});

test('amounts follow the stated exponent and currency', () => {
const m = model(resp({ limits: [limit('weekly_all', 'weekly', 54, 10080)], extra_usage: { enabled: true, used_minor: 1234, limit_minor: 50000, exponent: 2, currency: 'EUR' } }), NOW);
assert.equal(m.credits.text, 'Usage credits: on · 12.34 EUR of 500.00 EUR used this month');
});
7 changes: 7 additions & 0 deletions src/pkg/dashboard/subscription_gauge_overview_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,13 @@ func TestSubscriptionGaugeOverviewWiring(t *testing.T) {
if strings.Contains(overview, "innerHTML") {
t.Fatalf("Overview gauge must build its DOM without innerHTML:\n%s", overview)
}
// Claude's usage-credits line renders under the dials only when the
// model built one, and is a display: the gauge has no credits control.
for _, want := range []string{"if (row.credits)", "'overview-usage-gauge__credits', row.credits.text", "credits.setAttribute('data-status', row.credits.status)"} {
if !strings.Contains(overview, want) {
t.Fatalf("renderSubscriptionGaugeOverview missing %q:\n%s", want, overview)
}
}
dial := jsFunc(t, html, "subscriptionGaugeDialSvg")
if !strings.Contains(dial, "createElementNS") || strings.Contains(dial, "innerHTML") {
t.Fatalf("fuel dial must be built with createElementNS, not innerHTML:\n%s", dial)
Expand Down
Loading
Loading