Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Serve token coverage from the dashboard

Claudebad5341e4bb0
diff --git a/cli/beacon/internal/endpoint/dashboard/server.go b/cli/beacon/internal/endpoint/dashboard/server.go
index 436d38cc..5c23650b 100644
--- a/cli/beacon/internal/endpoint/dashboard/server.go
+++ b/cli/beacon/internal/endpoint/dashboard/server.go
@@ -161,6 +161,31 @@ func Handler(opts Options) (http.Handler, error) {
}
writeJSON(w, tokens.AggregateScopedWithContexts(events, contexts, "", tokenOptions(r)))
})
+ // Coverage answers a different question from the rollup above -- "is this all of it" rather
+ // than "what did it cost" -- so it gets its own route rather than a flag on /api/tokens. A
+ // caller asking for spend and a caller asking whether spend is complete want different
+ // filters, and the answers have no fields in common.
+ mux.HandleFunc("/api/tokens/coverage", func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ methodNotAllowed(w)
+ return
+ }
+ // Only the time window and the harness scope are honored, matching the CLI. The other
+ // filters select usage-bearing events almost by definition -- an event carries no model
+ // unless it carried a model call -- so coverage computed over them would find every
+ // runtime covered and prove nothing. Silence is what this route exists to show, and a
+ // filter that hides the silent rows defeats it.
+ query := parseQuery(r, maxEventLimit)
+ events, _, err := ReadTokenEventsAppendOrder(opts.LogPath, EventQuery{
+ Since: query.Since,
+ Until: query.Until,
+ })
+ if err != nil {
+ writeError(w, http.StatusInternalServerError, err)
+ return
+ }
+ writeJSON(w, buildTokenCoverage(events, query.Harness))
+ })
mux.HandleFunc("/api/detections", func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
methodNotAllowed(w)
diff --git a/cli/beacon/internal/endpoint/dashboard/server_test.go b/cli/beacon/internal/endpoint/dashboard/server_test.go
index 66598a41..db51755c 100644
--- a/cli/beacon/internal/endpoint/dashboard/server_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/server_test.go
@@ -121,7 +121,7 @@ func TestStatusUsesRequestedRuntimeLogSource(t *testing.T) {
// TestSummaryEndpointAggregatesAllMatchedEvents guards /api/summary against
// truncated aggregation: total_events comes from the full match count, so the
// breakdown counts must be computed over the same full set even when the
- // request carries a small ?limit= from the Agent Activity Sessions view.
+// request carries a small ?limit= from the Agent Activity Sessions view.
func TestSummaryEndpointAggregatesAllMatchedEvents(t *testing.T) {
logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
mk := func(minute int) string {
diff --git a/cli/beacon/internal/endpoint/dashboard/tokencoverage.go b/cli/beacon/internal/endpoint/dashboard/tokencoverage.go
new file mode 100644
index 00000000..d7f0c0ae
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/tokencoverage.go
@@ -0,0 +1,62 @@
+package dashboard
+
+import (
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// buildTokenCoverage joins the runtimes Beacon configured against the ones that reported usage,
+// for the dashboard's read of `beacon token-usage --coverage`.
+//
+// Every judgment about whether a runtime's silence is a fault stays in tokens.Coverage and its
+// expectation table. This assembles the two inputs and nothing else, so the dashboard and the CLI
+// cannot come to different conclusions about the same log -- which they would within a release if
+// either grew its own copy of the rule.
+func buildTokenCoverage(events []schema.Event, harness string) tokens.CoverageReport {
+ // The harness scope is applied to both sides of the join by the same code, for the reason the
+ // CLI does it here rather than in the event reader: this join is only correct while both sides
+ // agree on what a harness name is, and an asymmetry between them reported a runtime that had
+ // spent tokens as inactive.
+ want := asymptoteobserve.NormalizeHarnessName(strings.TrimSpace(harness))
+ if want != "" {
+ scoped := make([]schema.Event, 0, len(events))
+ for _, event := range events {
+ if strings.EqualFold(asymptoteobserve.NormalizeHarnessName(event.Harness.Name), want) {
+ scoped = append(scoped, event)
+ }
+ }
+ events = scoped
+ }
+
+ // Installed runtimes come from the config scanner rather than from the log, because the whole
+ // question is which configured runtime is missing from the log.
+ configs := make([]tokens.InstalledConfig, 0)
+ for _, config := range scanInventory(inventory.Options{}).Configs {
+ configs = append(configs, tokens.InstalledConfig{
+ Runtime: config.Runtime,
+ Path: config.Path,
+ Kind: config.ConfigKind,
+ BeaconManaged: config.BeaconManaged,
+ Exists: config.Exists,
+ })
+ }
+ installed := tokens.InstalledRuntimes(configs)
+ if want != "" {
+ // A harness scope narrows the events, so it narrows the installed list with them.
+ // Otherwise every other installed runtime has no events in the filtered set and reports
+ // inactive, which reads as "installed but unused" when the truth is that the caller asked
+ // about a different runtime.
+ scoped := make([]string, 0, 1)
+ for _, name := range installed {
+ if strings.EqualFold(name, want) {
+ scoped = append(scoped, name)
+ }
+ }
+ installed = scoped
+ }
+ return tokens.Coverage(events, installed)
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/tokencoverage_test.go b/cli/beacon/internal/endpoint/dashboard/tokencoverage_test.go
new file mode 100644
index 00000000..33495289
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/tokencoverage_test.go
@@ -0,0 +1,131 @@
+package dashboard
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
+)
+
+// stubInventory makes the installed side of the join deterministic. Without it the test reads the
+// machine it runs on, which is how a coverage test can pass with the behaviour it checks reverted.
+func stubInventory(t *testing.T, runtimes ...string) {
+ t.Helper()
+ old := scanInventory
+ t.Cleanup(func() { scanInventory = old })
+ scanInventory = func(inventory.Options) inventory.Result {
+ result := inventory.Result{}
+ for _, runtime := range runtimes {
+ result.Configs = append(result.Configs, inventory.Config{
+ Runtime: runtime,
+ Path: "/stub/" + runtime + ".json",
+ ConfigKind: "hooks",
+ BeaconManaged: true,
+ Exists: true,
+ })
+ }
+ return result
+ }
+}
+
+func writeCoverageLog(t *testing.T, lines ...string) string {
+ t.Helper()
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ body := ""
+ for _, line := range lines {
+ body += line + "\n"
+ }
+ if err := os.WriteFile(logPath, []byte(body), 0o600); err != nil {
+ t.Fatalf("write log: %v", err)
+ }
+ return logPath
+}
+
+func getCoverage(t *testing.T, logPath, rawQuery string) tokens.CoverageReport {
+ t.Helper()
+ handler, err := Handler(Options{UserMode: true, LogPath: logPath})
+ if err != nil {
+ t.Fatalf("Handler returned error: %v", err)
+ }
+ req := httptest.NewRequest(http.MethodGet, "/api/tokens/coverage?"+rawQuery, nil)
+ rec := httptest.NewRecorder()
+ handler.ServeHTTP(rec, req)
+ if rec.Code != http.StatusOK {
+ t.Fatalf("status code = %d, body = %s", rec.Code, rec.Body.String())
+ }
+ var report tokens.CoverageReport
+ if err := json.Unmarshal(rec.Body.Bytes(), &report); err != nil {
+ t.Fatalf("unmarshal coverage response: %v", err)
+ }
+ return report
+}
+
+func lineFor(t *testing.T, report tokens.CoverageReport, harness string) tokens.RuntimeCoverage {
+ t.Helper()
+ for _, runtime := range report.Runtimes {
+ if runtime.Harness == harness {
+ return runtime
+ }
+ }
+ t.Fatalf("no coverage line for %q in %+v", harness, report.Runtimes)
+ return tokens.RuntimeCoverage{}
+}
+
+const (
+ claudeUsageLine = `{"vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","timestamp":"2026-06-11T10:00:00Z","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"harness":{"name":"claude_code"},"model":"claude-opus-5","session":{"id":"s1"},"gen_ai":{"usage":{"input_tokens":100,"output_tokens":20}}}`
+ codexPlainLine = `{"vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","timestamp":"2026-06-11T10:01:00Z","event":{"kind":"agent_runtime","action":"command.executed","category":"command"},"harness":{"name":"codex_cli"},"session":{"id":"s2"}}`
+)
+
+// The route exists to show what the spend rollup cannot: a runtime that ran and reported nothing is
+// absent from every total, indistinguishable from one nobody used.
+func TestTokensCoverageRouteReportsCoveredAndSilent(t *testing.T) {
+ stubInventory(t, "claude_code", "codex_cli")
+ report := getCoverage(t, writeCoverageLog(t, claudeUsageLine, codexPlainLine), "")
+
+ if got := lineFor(t, report, "claude_code"); got.Status != tokens.CoverageCovered {
+ t.Errorf("claude_code status = %q, want covered", got.Status)
+ }
+ if got := lineFor(t, report, "codex_cli"); got.Status != tokens.CoverageSilent {
+ t.Errorf("codex_cli status = %q, want silent", got.Status)
+ }
+ if report.Covered != 1 || report.Silent != 1 {
+ t.Errorf("covered=%d silent=%d, want 1/1", report.Covered, report.Silent)
+ }
+}
+
+// The filters the CLI drops are dropped here too. A model filter selects usage-bearing events
+// almost by definition, so honoring it would report every runtime covered and hide the silent row
+// this route exists to surface.
+func TestTokensCoverageRouteIgnoresFiltersThatWouldHideSilence(t *testing.T) {
+ stubInventory(t, "claude_code", "codex_cli")
+ logPath := writeCoverageLog(t, claudeUsageLine, codexPlainLine)
+
+ unfiltered := getCoverage(t, logPath, "")
+ filtered := getCoverage(t, logPath, "model=claude-opus-5&session=s1&repository=/repo")
+ if filtered.Silent != unfiltered.Silent || len(filtered.Runtimes) != len(unfiltered.Runtimes) {
+ t.Errorf("filtered report = %+v, want the same shape as unfiltered %+v", filtered, unfiltered)
+ }
+ if got := lineFor(t, filtered, "codex_cli"); got.Status != tokens.CoverageSilent {
+ t.Errorf("codex_cli status under a model filter = %q, want silent", got.Status)
+ }
+}
+
+// A harness scope narrows both sides of the join. Narrowing only the events would leave every
+// other installed runtime with none in the filtered set, reporting inactive -- which reads as
+// "installed but unused" when the caller only asked about one runtime.
+func TestTokensCoverageRouteScopesBothSidesByHarness(t *testing.T) {
+ stubInventory(t, "claude_code", "codex_cli")
+ report := getCoverage(t, writeCoverageLog(t, claudeUsageLine, codexPlainLine), "harness=claude_code")
+
+ if len(report.Runtimes) != 1 {
+ t.Fatalf("runtimes = %+v, want only the scoped one", report.Runtimes)
+ }
+ if got := lineFor(t, report, "claude_code"); got.Status != tokens.CoverageCovered {
+ t.Errorf("claude_code status = %q, want covered", got.Status)
+ }
+}
diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdx
index 5559102f..b2139474 100644
--- a/docs/cli/token-usage.mdx
+++ b/docs/cli/token-usage.mdx
@@ -115,6 +115,8 @@ Coverage applies the `--since`, `--until` and `--harness` scopes, and deliberate
Add `--json` for the machine-readable form, which carries the same per-runtime rows plus `silent`, `covered` and `total_events` counts. A `silent` count above zero is the alertable condition.
+The local dashboard serves the same report at `GET /api/tokens/coverage`, with the same body as `--coverage --json`. It honors `since`, `until` and `harness` and ignores the rest, for the reason the command does. Both read one join and one expectation table, so the two cannot reach different conclusions about the same log.
+
## Examples
Show token usage from the default per-user endpoint log: