Skip to content

✨ [v6] Cost card + admin MCP: tokens and spend per agent over a time window - #18971

Merged
hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:feat/cost-agent-window
Nov 18, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
hivecommons:v6from
Danathar:feat/cost-agent-window

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

Summary

You can now see which agent used the most tokens and estimated dollars over any time range, on the Cost card and through the admin MCP. Before this, spend_read gave per-agent totals for all time only. The agent cards showed dollars only, spread across the cards, with no ranked list.

  • Cost card. The "usage by sandbox" table follows the timeframe selector. For the selected range it shows each agent's tokens, input, output and estimated $, highest first. A switch keeps the all-time view.
  • Admin MCP. spend_read takes hours (1–720) or since/until. It returns the same rows the table shows for that range.
  • Agent cards. The spend chips read the same server numbers, so the chips and the table agree.

Fixes #18968

What changed

Recording

  • Each 5-minute cost snapshot now also stores each agent's cumulative token counters (agent_tokens), next to the per-agent dollars it already stored.
  • They come from the same estimatedCost().ByAgent rows as the dollars.
  • The field is additive and omitted when empty, so older snapshots still decode. A window over those reports the agent's tokens as null (unknown), never 0.

Server

  • costAgentWindow (src/pkg/dashboard/cost_agent_window.go) folds the snapshot ring into one row per agent for [since, until].
  • Each row has input, output, cache_read, cache_create, total_tokens and estimated usd, plus first_sample, last_sample, samples and coverage.
  • Rows sort by USD, then total tokens.
  • Shared correction rules, not a copy. The rules that decide whether a jump is spend or a data correction are factored out of costFoldDailyRollups into one costCorrectionGuard (cost_rollup.go). Both the daily fold and the window use it. The fold's behaviour does not change.
  • Same per-agent $ as the browser. For a window it is the positive increases between in-window snapshots, as agentWindowSpend computes it, minus the restore-shaped jumps the daily rollup already drops.

API

  • New endpoint: GET /api/cost/agents.
  • Window arguments. It takes ?since=&until= (RFC3339) or ?hours=N (1–720), parsed by the advisor endpoints' advisorWindow. With no window it answers the last 24 hours.
  • Why a new endpoint. The answer has a different shape from /api/cost.
  • Why these arguments. The Cost section already sends this exact window to /api/advisor/spend, so the frontend reuses the same bounds.
  • Older than the ring. A window that starts before the snapshot ring answers coverage: "partial" with data_since (the real start), not zeros.
  • Docs. It is in dashboard/openapi.json and the API reference.

Dashboard

  • Range view. "Usage by sandbox" gets a selected range / all time switch, styled like the existing range pills. The choice is remembered per browser.
    • In range mode the table reads /api/cost/agents for the window chosen above.
    • Columns are sandbox, tokens, input, output and est. $. Hovering the tokens cell shows the cache tokens.
    • A null token count shows as "—" with a "not zero" tooltip.
    • A partial window gets a note saying when the snapshots start.
  • All time. The all-time view is the existing table, unchanged.
  • Agent chips. agentWindowSpend returns the server row when one exists for the current window. Until then it falls back to the browser's own sum, as before.
  • Bundle. static/index.html is regenerated from static-src.

Admin MCP

  • Window arguments. spend_read takes hours, since and until. With any of them it reads /api/cost/agents; with none it reads /api/cost as before.
  • Validation before any request (SpendReadPath, modelled on LaunchCostReadPath). Refused with a reason:
    • negative, zero, fractional, or over-720 hours;
    • since together with hours;
    • until before since;
    • a span over 720 hours;
    • a timestamp that isn't RFC3339.
  • Description. It says the figures are estimates and names the window fields.
  • Same in both servers. The dashboard provider and the stdio server (cmd/hive-admin-mcp) both route spend_read through it.

Against the issue

Nothing in the issue was wrong against current v6 (86e4c0a9b); its code pointers still matched. Two choices it left open:

  • The endpoint takes RFC3339 since/until, not millisecond values. The issue offered either form. RFC3339 matches the advisor endpoints and the window the dashboard already sends.
  • I extended spend_read instead of adding a sibling tool. The issue's first option, and the call with no arguments is unchanged.

Tests

  • cost_agent_window_test.go covers the five cases in the issue's test plan:
    • (a) steady growth, compared against a Go port of agentWindowSpend;
    • (b) a counter drop after a restart;
    • (c) a restore-shaped jump, dropped exactly as costFoldDailyRollups drops it, while a large climb to a new high is kept;
    • (d) a window that starts before the ring;
    • (e) old snapshots with no token map, giving null tokens.
  • It also tests the sampler recording per-agent tokens, and the endpoint's default window and 400s.
  • admin_mcp_spend_window_test.go:
    • no-argument reads still go to /api/cost;
    • hours goes to /api/cost/agents with the agents rows capped;
    • bad windows never reach the router;
    • the MCP's 24-hour rows equal the dashboard's rows for the same range.
  • adminmcp/tools_spend_test.go: path building and every refusal.
  • dashboard/test/cost-agent-window.test.js:
    • range switching changes the request and key;
    • the chips use the server row and fall back on a new range;
    • rows sort highest spend first;
    • null tokens read as a dash;
    • the partial-coverage note.

Local checks

  • I ran gofmt -l, the new node test (5/5 pass), check-docs-citations.py (2183 references verified) and check-api-reference-citations.sh.
  • The route insert shifted api.go and server.go line numbers. check-api-reference-citations.sh --fix re-anchored them, so most of the doc diff is line numbers only.
  • AGENTS.md bans local go test, go build and go vet, so CI is the first run of the Go tests.

Out of scope (unchanged)

  • /api/launch-cost and launch_cost_read.
  • Budgets and enforcement.
  • Price tables.
  • Collection for backends without a per-message timeline.
  • No new setting, so no dashboard or MCP settings parity is needed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

…and MCP

An operator could not answer "which agent used the most tokens in the last
24 hours": spend_read gave per-agent totals for all time only, and the agent
cards' $ chips were dollars only, spread across the cards.

- Each 5-minute cost snapshot now carries per-agent token counters
  (agent_tokens) beside the per-agent dollars; older snapshots still decode
  and their tokens read as unknown (null), not zero.
- costAgentWindow folds the ring into one row per agent for [since, until]:
  tokens (input, output, cache read, cache create, total), estimated usd,
  first/last sample and coverage, highest spend first. It uses the daily
  rollup's correction rules through one shared costCorrectionGuard, factored
  out of costFoldDailyRollups (behaviour unchanged there).
- GET /api/cost/agents?since=&until= (RFC3339) or ?hours=N, the advisor
  endpoints' window parameters; none means the last 24 hours. A window that
  starts before the ring answers coverage partial with data_since.
- Cost card: usage by sandbox follows the timeframe selector (tokens, input,
  output, est. $ per agent), with an all-time switch; the agent cards' spend
  chips read the same server rows.
- Admin MCP: spend_read takes hours (1-720) or since/until and then reads
  /api/cost/agents; a bad window is refused before any request. Same in the
  stdio server.

Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

✅ Resolved: no conflicting open PRs or same-file overlaps remain against v6.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Correctness review at d7bd02c. I read the per-agent window fold, the shared costCorrectionGuard refactor, SpendReadPath against advisorWindow on v6, and the dashboard fetch/render path. No blocker found.

  • The costFoldDailyRollups refactor is behaviour-preserving: the same guard condition and the same threshold inputs.
  • MCP and server window semantics agree. hours plus until and until-only both resolve to the same bounds, and a window with until before since is refused on both sides.

Advisory, non-blocking:

  1. Agents with tokens but $0 are invisible (cost_agent_window.go, costAgentWindow name collection; server.go, sampleCostHistory). Names come only from e.Agents, which is written only when row.USD > 0. An agent that has token counters but unpriced or zero USD is recorded in AgentTokens yet never appears in the window table.
    • Fix: also collect names from e.AgentTokens, and have costAgentWindowFor read Agents[name] as 0 when it is absent.
  2. Failed range fetch reads as "loading" forever (cost.js, range branch). If /api/cost/agents returns non-2xx, _costAgentWindowFailed is set but the table body still says loading the selected range….
    • Fix: when _costAgentWindowFailed === costAgentWindowQuery().key, render "could not load the selected range".

— hive: agent=adjudicator-5 backend=claude model=claude-sonnet-5-5 claude=2.1.327

…read fails

Review on hivecommons#18971: an agent with tokens but no $ entry never got a row, and
a failed /api/cost/agents read left the table on "loading" for good. Name
agents from AgentTokens too (carrying the last $ across a missing entry),
and show the failure, retrying the read after a minute.

Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
@Danathar

Copy link
Copy Markdown
Contributor Author

Re the adjudicator-5 review at d7bd02c: I checked both advisories, and both were right. Both are fixed in 5815599.

  1. Agents with tokens but $0. costAgentWindow now collects names from AgentTokens too. costAgentWindowFor takes a snapshot that has either map for the agent. A snapshot with tokens but no $ entry carries the agent's last $. A missing entry means $0 was not recorded, and the counter is cumulative, so reading it as 0 would have looked like a drop and a later restore. New test: TestCostAgentWindowUnpricedAgent (an unpriced agent gets its 550-token row at $0; a priced agent's missing entry carries over).
  2. Failed range read. The table now says "could not load the selected range; retrying shortly" instead of "loading the selected range…". costAgentWindowEnsure also retries a failed window after a minute; before, it never re-read a window whose read had failed until the window itself changed. The new costAgentWindowFailed() is called behind a typeof guard, like costAgentWindowData. Bundle regenerated.

@hivecommons-hive
hivecommons-hive Bot merged commit 03f97c5 into hivecommons:v6 Nov 18, 2026
74 of 75 checks passed
@hivecommons-hive

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Evidence bundle `#18971b46f6fd` sha256:abfc62ee559458adb784008abef9132d66a32e4ef072ce411b7d0cc465bca50d — download from the dashboard or `hivectl review evidence #18971`.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ [v6] Cost card + admin MCP: tokens and spend per agent over a chosen time window

1 participant