coulomb/state-hub
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(token-tracking): introduce token note taxonomy (measured/userbased/workplan/heuristic)

Browse Source 
Tier 1 (exact counts) now defaults to note="measured" instead of null,
signalling the counts were read from the Claude Code status bar.
Callers can pass note="userbased" when a human provided the numbers.

  measured  — agent read exact counts from the Claude Code status bar
  userbased — counts provided by a human
  workplan  — prorated from workplan total across task count
  heuristic — server fallback, 1000/500, no agent input

Added token_note field to TaskUpdate schema and exposed note param on
update_task_status and record_interactive_task MCP tools.
TOOLS.md documents the full taxonomy. 185 tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-03-29 18:47:40 +02:00
parent 8c87a9a799
commit af3fdfde80
5 changed files with 59 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
mcp_server/TOOLS.md
View File

@@ -83,6 +83,16 @@ Agents should call `record_token_event` (or pass `tokens_in`/`tokens_out` via
|------|----------|-------|
| `record_token_event(tokens_in, tokens_out, ...)` | `task_id`?, `workstream_id`?, `repo_id`?, `model`?, `agent`?, `ref_type`?, `ref_id`?, `note`?, `session_id`? | POSTs to `/token-events/`. `workstream_id` auto-filled from task. Returns event id + running total. |
| `get_token_summary(scope, id)` | `scope`: task\|workstream\|repo\|commit\|release\|session; `id`: UUID or ref string | Returns formatted table of tokens_in/out/total, event_count, by_model, by_agent. |
| `record_interactive_task(title, repo_slug, ...)` | `tokens_in`?, `tokens_out`?, `note`?, `model`?, `agent`?, `description`?, `session_id`? | Find-or-create `interactive-<repo>` workstream, create task, mark done, record token event. |
**Token note taxonomy:**
| note | meaning |
|------|---------|
| `"measured"` | Exact counts read from Claude Code status bar — default when `tokens_in`/`tokens_out` provided |
| `"userbased"` | Counts provided by a human (pass `note="userbased"` explicitly) |
| `"workplan"` | Prorated from workplan total across task count |
| `"heuristic"` | Server fallback — 1 000 in / 500 out, no agent input |
---