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-cost-agent-window.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The Cost card's usage-by-sandbox table now follows the timeframe selector: each agent's tokens and estimated $ for the selected range, highest first, with an "all time" switch for the old totals. The agent cards' spend chips read the same numbers. They come from a new `GET /api/cost/agents` (`since`/`until` or `hours`), which applies the daily rollup's correction rules and says when the range starts before the recorded snapshots. The admin MCP's `spend_read` takes `hours` or `since`/`until` and returns the same rows (#18968).
57 changes: 57 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -33638,6 +33638,63 @@
}
}
},
"/api/cost/agents": {
"get": {
"tags": [
"Tokens"
],
"summary": "Get per-agent tokens and estimated cost over a window",
"description": "Each agent's tokens (input, output, cache read, cache create, total) and estimated USD over a window, highest spend first, from the 5-minute cost snapshots (about 30 days). The window is since/until (RFC3339) or hours (1-720); none means the last 24 hours. coverage is partial, with data_since, when the window starts before the oldest snapshot. Token fields are null for an agent whose snapshots in the window predate per-agent token recording.",
"parameters": [
{
"name": "since",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "RFC3339 start of the window (inclusive)."
},
{
"name": "until",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "RFC3339 end of the window (inclusive); default now."
},
{
"name": "hours",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 720
},
"description": "Lookback from now in hours, instead of since."
}
],
"responses": {
"200": {
"description": "Per-agent window spend",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Invalid window parameters"
}
}
}
},
"/api/hive-id": {
"get": {
"tags": [
Expand Down
116 changes: 116 additions & 0 deletions dashboard/test/cost-agent-window.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
'use strict';

// Cost card: usage by sandbox follows the timeframe selector (#18968). The
// table and the agent cards' spend chips read GET /api/cost/agents for the
// active window; until it has answered for that window the chips fall back to
// the browser's own sum.

const { test } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const vm = require('node:vm');

const indexHtml = fs.readFileSync(path.join(__dirname, '..', '..', 'src', 'pkg', 'dashboard', 'static', 'index.html'), 'utf8');

function extractFunction(name) {
const start = indexHtml.indexOf('function ' + name + '(');
assert.notEqual(start, -1, `${name} function exists`);
const brace = indexHtml.indexOf('{', start);
let depth = 0;
for (let i = brace; i < indexHtml.length; i++) {
const ch = indexHtml[i];
if (ch === '{') depth++;
if (ch === '}') depth--;
if (depth === 0) return indexHtml.slice(start, i + 1);
}
throw new Error(`unterminated ${name}`);
}

const DAY = 24 * 3600 * 1000;
const NOW = Date.UTC(2026, 10, 18, 12, 0, 0);

function load() {
const context = { exports: {}, Date, Math, Number, String, encodeURIComponent };
vm.runInNewContext([
'let _costAgentWindow = null;',
"let _costRange = 'daily';",
'let WIN = null;',
'let HIST = [];',
"const COST_SORTS = { sandbox: { key: 'usd', dir: 'desc' } };",
"const COST_RANGES = { daily: { label: 'daily' } };",
'function costWindow() { return WIN; }',
'function costHist() { return HIST; }',
"function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/\"/g, '&quot;'); }",
"function fmtTokens(n) { return String(n); }",
"function fmtUSD(n) { return '$' + Number(n).toFixed(2); }",
"function fmtCostDateTime(ms) { return new Date(ms).toISOString(); }",
extractFunction('costCmp'),
extractFunction('sortCostRows'),
extractFunction('costAgentWindowQuery'),
extractFunction('costAgentWindowData'),
extractFunction('agentWindowSpend'),
extractFunction('costWindowTokensCell'),
extractFunction('costSandboxRangeRowsHtml'),
extractFunction('costSandboxCoverageNote'),
'exports.setWin = (w) => { WIN = w; };',
'exports.setHist = (h) => { HIST = h; };',
'exports.setData = (key, data) => { const byName = {}; for (const a of data.agents) byName[a.name] = a; _costAgentWindow = { key, data, byName }; };',
'exports.query = costAgentWindowQuery;',
'exports.spend = agentWindowSpend;',
'exports.rows = costSandboxRangeRowsHtml;',
'exports.note = costSandboxCoverageNote;',
].join('\n'), context);
return context.exports;
}

const daily = { key: 'daily', start: NOW - 7 * DAY, end: NOW + DAY };
const weekly = { key: 'weekly', start: NOW - 28 * DAY, end: NOW + 3 * DAY };
const pastCustom = { key: 'custom', start: NOW - 3 * DAY, end: NOW - DAY };

test('a window that runs to now is asked without until and keyed "now"', () => {
const m = load();
m.setWin(daily);
const q = m.query(daily, NOW);
assert.equal(q.key, `daily|${daily.start}|now`);
assert.equal(q.qs, `since=${encodeURIComponent(new Date(daily.start).toISOString())}`);
});

test('a custom range that ended sends its end', () => {
const m = load();
const q = m.query(pastCustom, NOW);
assert.equal(q.key, `custom|${pastCustom.start}|${pastCustom.end}`);
assert.match(q.qs, /&until=/);
});

test('the chips read the server row for the active window, and fall back when the range changes', () => {
const m = load();
m.setWin(daily);
m.setHist([
{ timestamp: NOW - 2 * DAY, agents: { scanner: 1 } },
{ timestamp: NOW - DAY, agents: { scanner: 4 } },
]);
m.setData(m.query().key, { agents: [{ name: 'scanner', usd: 2.5 }] });
assert.equal(m.spend('scanner'), 2.5, 'server row wins for the window it answered');
assert.equal(m.spend('reviewer'), null, 'an agent the server did not list has no spend in the window');

m.setWin(weekly);
assert.equal(m.spend('scanner'), 3, 'a new range falls back to the browser sum until the server answers');
});

test('rows are highest spend first, and unknown tokens read as a dash, never 0', () => {
const m = load();
const out = m.rows({ agents: [
{ name: 'scanner', usd: 1, total_tokens: 900, input: 100, output: 50, cache_read: 750, cache_create: 0 },
{ name: 'reviewer', usd: 4, total_tokens: null, input: null, output: null, cache_read: null, cache_create: null },
] });
assert.ok(out.indexOf('reviewer') < out.indexOf('scanner'), 'reviewer ($4) before scanner ($1)');
assert.match(out, /Not zero\./);
assert.match(out, /cache read 750/);
});

test('a range that starts before the snapshots says so', () => {
const m = load();
assert.equal(m.note({ coverage: 'full' }), '');
assert.match(m.note({ coverage: 'partial', data_since: '2026-10-19T12:00:00Z' }), /The cost snapshots start 2026-10-19/);
});
16 changes: 16 additions & 0 deletions src/cmd/hive-admin-mcp/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,22 @@ func (p readProvider) Read(ctx context.Context, tool string, args map[string]any
}
return adminmcp.LaunchCostResult(data, args)
}
if tool == adminmcp.ToolSpendRead {
// The window is checked before the call; see the dashboard provider.
path, err := adminmcp.SpendReadPath(args)
if err != nil {
return nil, err
}
client, _, err := p.roster.activeClient()
if err != nil {
return nil, err
}
data, err := getPath(ctx, client, path)
if err != nil {
return nil, err
}
return adminmcp.CapResult(data, adminmcp.LimitFromArgs(args)), nil
}
if tool == adminmcp.ToolGitHubAPIUsage {
client, _, err := p.roster.activeClient()
if err != nil {
Expand Down
46 changes: 33 additions & 13 deletions src/docs/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -338,19 +338,19 @@ capped at 256 KiB.

**Status and version**

| Tool | Returns |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `hive_status` | Hive status summary |
| `fleet_status` | Fleet state, including memory limit and out-of-memory kills (see note 1) |
| `version_read` | Running build from `/api/version` (see note 2) |
| `claude_auth_status` | Claude auth mode (`long-lived token` or `dashboard sign-in`); no token |
| `autonomy_readiness` | Autonomy readiness |
| `spend_read` | Spend |
| `launch_cost_read` | Cost per issue and PR, as on the Cost card (see [Cost by work item](#cost-by-work-item)); optional `ref`, `offset` |
| `pr_models_read` | PRs by model, as on the Governor card: outcomes, rework and effectiveness rank per model (see note 8); optional `window` |
| `contributor_model_stats_read` | Contributor run stats by model: runs, verified-PR share, failure rate; optional `days` (0-365, default 7) |
| `effective_models_read` | Operations → Most effective models: hive-agent or contributor PRs, coverage (see note 8); optional `window`, `filter` |
| `github_api_usage` | GitHub API budget and who is spending it (see note 7); optional `limit` |
| Tool | Returns |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hive_status` | Hive status summary |
| `fleet_status` | Fleet state, including memory limit and out-of-memory kills (see note 1) |
| `version_read` | Running build from `/api/version` (see note 2) |
| `claude_auth_status` | Claude auth mode (`long-lived token` or `dashboard sign-in`); no token |
| `autonomy_readiness` | Autonomy readiness |
| `spend_read` | Spend and budget; with `hours` or `since`/`until`, tokens and $ per agent over that window (see [Spend by agent](#spend-by-agent-over-a-window)) |
| `launch_cost_read` | Cost per issue and PR, as on the Cost card (see [Cost by work item](#cost-by-work-item)); optional `ref`, `offset` |
| `pr_models_read` | PRs by model, as on the Governor card: outcomes, rework and effectiveness rank per model (see note 8); optional `window` |
| `contributor_model_stats_read` | Contributor run stats by model: runs, verified-PR share, failure rate; optional `days` (0-365, default 7) |
| `effective_models_read` | Operations → Most effective models: hive-agent or contributor PRs, coverage (see note 8); optional `window`, `filter` |
| `github_api_usage` | GitHub API budget and who is spending it (see note 7); optional `limit` |

**Agents, runs and plans**

Expand Down Expand Up @@ -657,6 +657,26 @@ What the answer holds:

`spend_read` has spend by agent and by model, but not by work item.

### Spend by agent over a window

`spend_read` with no arguments reads `GET /api/cost`: the estimated all-time
totals by model and by agent, the daily rollup and the budget. With a window it
reads `GET /api/cost/agents` instead, the rows the Cost card's usage-by-sandbox
table shows for the same range (#18968):

- `hours` (1-720) looks back from now; `since` and `until` (RFC3339) bound the
window instead. `since` and `hours` can't be combined, `until` must not be
before `since`, and the window spans at most 720 hours. A bad window is
refused with its reason before any request is made.
- Each row in `agents` is one agent, highest estimated `usd` first, with
`input`, `output`, `cache_read`, `cache_create` and `total_tokens`, the first
and last snapshot in the window and `samples`. `limit` caps the rows.
- The figures come from the 5-minute cost snapshots, which keep about 30 days.
A window that starts before the oldest one answers `coverage: partial` with
`data_since`, not zeros. An agent's token fields are `null` where its
snapshots predate per-agent token recording.
- Everything is an estimate (token counts × list price), not billed spend.

### What a read masks

Every read result is scrubbed in two ways.
Expand Down
Loading
Loading