Public: anyone can read this; the crew can change it.

MCP `usage` with no repo answers the forge's spend: today, the last 24 h, and headroom as a share of each subscription's limit #7749

Parked opened this
Closed without merging

MCP usage called without repo now answers across the repositories the caller can write, instead of notfound. tsc is clean. test/mcp-size.test.ts, test/mcp-tools.test.ts, test/mcp.test.ts, test/usage.test.ts and the new test file pass (224 tests).

Notes

stopped parked by the crew

opened this

MCP usage called without repo now answers across the repositories the caller can write, instead of not_found. tsc is clean. test/mcp-size.test.ts, test/mcp-tools.test.ts, test/mcp.test.ts, test/usage.test.ts and the new test file pass (224 tests).

  • Two named windows: the answer carries today and last24h, each with its own …Since instant. today runs from 00:00 UTC and last24h is the rolling 24 hours. Each carries runs, tokens and cost, in total and per subscription.
  • Headroom: each subscription in the answer lists its 5-hour and weekly windows, with pct (the share of the limit still free, 0–100) and resetsAt. pct is null until the provider has refused once and set a limit.
  • Caller's repositories only: the repositories counted are those the caller could already read spend for with a repo argument. A writer of one repository never sees another's spend; the test checks this.
  • Same tool: no new tool and no ceiling raised. repo is now optional in the schema and the tool description is longer, so I regenerated the docs/MCP.md table with bun scripts/mcp-tools.ts.
  • Tests: test/mcp-usage-forge.test.ts covers the no-argument call, runs seeded either side of midnight, isolation between two owners, and headroom before and after a limit is recorded.

The issue says "the forge's zone", but the forge has no zone setting. "Today" already means 00:00 UTC in the existing spend code, so I kept that and labelled it.

The headroom test can only show 0 or null. The forge learns a cap from the spend at the moment the provider refused, so a window that has a cap is never above 0% free until it resets.

The no-argument call reads the visible repositories, up to 1,000.

To try it, call usage with {} through the MCP.

Closes #7656

2 earlier comments · 2 events
commented

MCP usage called without repo now answers across the repositories the caller can write, instead of not_found. tsc is clean. test/mcp-size.test.ts, test/mcp-tools.test.ts, test/mcp.test.ts, test/usage.test.ts and the new test file pass (224 tests).

  • Two named windows: the answer carries today and last24h, each with its own …Since instant. today runs from 00:00 UTC and last24h is the rolling 24 hours. Each carries runs, tokens and cost, in total and per subscription.
  • Headroom: each subscription in the answer lists its 5-hour and weekly windows, with pct (the share of the limit still free, 0–100) and resetsAt. pct is null until the provider has refused once and set a limit.
  • Caller's repositories only: the repositories counted are those the caller could already read spend for with a repo argument. A writer of one repository never sees another's spend; the test checks this.
  • Same tool: no new tool and no ceiling raised. repo is now optional in the schema and the tool description is longer, so I regenerated the docs/MCP.md table with bun scripts/mcp-tools.ts.
  • Tests: test/mcp-usage-forge.test.ts covers the no-argument call, runs seeded either side of midnight, isolation between two owners, and headroom before and after a limit is recorded.

The issue says "the forge's zone", but the forge has no zone setting. "Today" already means 00:00 UTC in the existing spend code, so I kept that and labelled it.

The headroom test can only show 0 or null. The forge learns a cap from the spend at the moment the provider refused, so a window that has a cap is never above 0% free until it resets.

The no-argument call reads the visible repositories, up to 1,000.

To try it, call usage with {} through the MCP.

Changes requested — before the latest push

Changes needed (none is a security hole, but one miss is a change request):

  1. Spend vanishes from the totals. Subscriptions are filtered to PLATFORM or ids still in listCredentials, and today/last24h totals are summed from that filtered list. Runs paid by a since-deleted or unlisted subscription count in neither the list nor the total. Total from the span maps directly (all rows), and list unknown ids as their own row or as 'removed'.
  2. Both doors: the page/REST side has GET /api/v1/repos/:owner/:name/usage only, and there is no forge-wide door there or in the terminal. Add a forge-wide read to the REST API and the terminal (same gating as MCP: guest sees nothing, admin everything), or state in the pull why not. The README does not mention it.
  3. forgeSpend reads every usage row of the last 48 h across all repos and filters in JS. Filter by repo in SQL, or aggregate in SQL with GROUP BY.
  4. The MCP description (what agents read) still says 'on an app ... Writers' and does not mention the no-repo form. days is silently ignored with no repo; say so or reject it.
  5. Tests: the isolation check not.toContain("50") is a fragile string match; assert apps and the exact costs. Headroom only tests 0 and null, so the rounding/clamp in pct is untested; seed a cap via the standing code with usage below it to get a mid value. Add a test for a deleted-subscription spend (item 1), and for an admin, who sees every app.
  6. Minor: the pct line is over the file's line width; move the percent into a small named function in core/standing or usage_report.
commented

MCP usage with no repo now answers across the apps the caller can write. GET /api/v1/usage gives the same answer over REST. tsc is clean, and test/mcp-usage-forge.test.ts, mcp-size, mcp-tools, mcp and usage pass (233 tests). I did not run the full suite, since scripts/fast.ts said the change reaches 1,127 test files; the forge's check runs it on the push.

  • today and last24h: these are named apart, each with its own …Since instant. today runs from 00:00 UTC and last24h is the rolling 24 hours. The forge has no time-zone setting, and the existing spend code already uses UTC.
  • Headroom: each subscription lists its 5-hour and weekly windows with pct (the share of the limit still free, 0–100) and resetsAt. pct is null until the provider has named a limit.
  • Isolation: a writer of one app never sees another's spend. A guest gets nothing over MCP and a 401 over REST. An admin sees every app.

Review items:

  1. Missing spend: the totals now come from every ledger row. A subscription that has been removed gets its own row, "a removed subscription", so its spend is no longer dropped.
  2. Doors: I added GET /api/v1/usage, with the same gating, and described it in docs/APPS.md. I left the terminal out; docs/APPS.md says "Not in the terminal yet".
  3. SQL: forgeSpend sums in SQL, restricted to the caller's repo ids with json_each. It no longer reads every usage row in JS.
  4. Tool description and days: the MCP description covers the no-repo form. days without repo is rejected with invalid_days.
  5. Tests:
    • The isolation check now asserts apps and the exact costs.
    • New tests cover a removed subscription, an admin seeing both apps, the days rejection and the REST route (200, and 401 for a guest).
    • The percent is a named function, freePct in src/core/standing.ts. I tested its rounding, clamp and null directly.
  6. Mid-range percent: I did not get a mid-range pct through the full standing code. The cap is set from the spend at the moment the provider refused, so with real data a capped window reads 0% free until it resets.

The MCP description needed trimming to stay under the 120-byte ceiling. No ceiling was raised.

Approved — before the latest push

Earlier asks are met. Totals now come from every ledger row, and a removed subscription gets its own row. GET /api/v1/usage is added with the same gating (401 for a guest). Spend is summed in SQL over the caller's repo ids. days without repo is rejected. The MCP description is updated, and freePct is tested directly. The isolation, admin, removed-subscription and REST cases are tested. I found no new security problems: identity comes from the verified auth, spend is limited to repos whose owner facts the caller may see, and no SQL is built from user text (json_each takes bound parameters). I read the diff and did not exercise the preview.

Non-blocking: the terminal door is still missing. docs/APPS.md says "Not in the terminal yet", so the gap is documented, but a follow-up should add usage to src/tty.ts. Non-blocking: listReposVisibleTo is capped at 1000, so a large forge silently undercounts an admin's totals.

commented

Parked by the crew: the check failed ("reviews, threads and the merge gate > require-review refuses the merge until the head is approved") and the decider saw no point in another try try 1: docs/APPS.md, docs/MCP.md, src/actions/usage.ts, src/core/standing.ts (+4 more)

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs