The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Serve token coverage from the dashboard
Claudebad5341e4bb0
diff --git a/cli/beacon/internal/endpoint/dashboard/server.go b/cli/beacon/internal/endpoint/dashboard/server.goindex 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.mdxindex 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 deliberateAdd `--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.+## ExamplesShow token usage from the default per-user endpoint log: