Skip to content

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

Add beacon endpoint tokens report command

Claude03e104db4fb3
diff --git a/CLAUDE.md b/CLAUDE.md
index f742f7d9..72875fb9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,6 +35,7 @@ Supported runtime surfaces today:
- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.
- Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.
- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log.
+- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon endpoint tokens` report command for local and CI logs.
Current non-goals unless explicitly requested:
diff --git a/README.md b/README.md
index f530417f..af6cc187 100644
--- a/README.md
+++ b/README.md
@@ -182,7 +182,15 @@ through standard MDM workflows.
Beacon includes a local, read-only dashboard for validating endpoint activity
without a hosted backend. The overview screen summarizes recent runtime events
and collection status, while log search helps teams inspect normalized event
-records during rollout, testing, and investigations.
+records during rollout, testing, and investigations. The token usage screen
+breaks captured token telemetry down by model, session (with per-step
+drilldown), CI run, and harness, including context-window utilization and
+runtime-reported cost.
+
+For scripted or CI reporting, `beacon endpoint tokens` prints the same token
+usage rollups as text or JSON from any runtime JSONL log, for example
+`beacon endpoint tokens --log-path "$BEACON_CI_LOG_PATH" --json` after a CI
+session.
Beacon writes endpoint activity to a stable local `runtime.jsonl` file. The
active file rotates at 10 MiB with five numbered local archives, keeping the
diff --git a/cli/beacon/cmd/endpoint_tokens.go b/cli/beacon/cmd/endpoint_tokens.go
new file mode 100644
index 00000000..71a92f55
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_tokens.go
@@ -0,0 +1,116 @@
+package cmd
+
+import (
+ "encoding/json"
+ "strings"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/tokens"
+)
+
+var endpointTokensOpts struct {
+ userMode bool
+ systemMode bool
+ logPath string
+ jsonOutput bool
+ since string
+ until string
+ session string
+ model string
+ harness string
+ repository string
+ runID string
+ bucket string
+ top int
+}
+
+var endpointTokensCmd = &cobra.Command{
+ Use: "tokens",
+ Short: "Report token usage and attribution from the endpoint runtime log",
+ SilenceUsage: true,
+ RunE: runEndpointTokens,
+}
+
+func runEndpointTokens(cmd *cobra.Command, args []string) error {
+ userMode := endpointTokensOpts.userMode
+ if endpointTokensOpts.systemMode {
+ userMode = false
+ }
+ runtimeLog := lifecycle.ResolveRuntimeLog(userMode, endpointTokensOpts.logPath)
+ query := dashboard.EventQuery{
+ NoLimit: true,
+ Session: endpointTokensOpts.session,
+ Model: endpointTokensOpts.model,
+ Harness: endpointTokensOpts.harness,
+ Repository: endpointTokensOpts.repository,
+ }
+ if since := strings.TrimSpace(endpointTokensOpts.since); since != "" {
+ parsed, err := time.Parse(time.RFC3339, since)
+ if err != nil {
+ return err
+ }
+ query.Since = parsed
+ }
+ if until := strings.TrimSpace(endpointTokensOpts.until); until != "" {
+ parsed, err := time.Parse(time.RFC3339, until)
+ if err != nil {
+ return err
+ }
+ query.Until = parsed
+ }
+ result, err := dashboard.ReadEvents(runtimeLog.EffectiveLogPath, query)
+ if err != nil {
+ return err
+ }
+ events := make([]schema.Event, 0, len(result.Events))
+ for _, record := range result.Events {
+ if runID := strings.TrimSpace(endpointTokensOpts.runID); runID != "" {
+ if record.Event.Run == nil || record.Event.Run.RunID != runID {
+ continue
+ }
+ }
+ events = append(events, record.Event)
+ }
+ opts := tokens.Options{
+ SessionID: endpointTokensOpts.session,
+ TopLimit: endpointTokensOpts.top,
+ }
+ if bucket := strings.TrimSpace(endpointTokensOpts.bucket); bucket != "" {
+ parsed, err := time.ParseDuration(bucket)
+ if err != nil {
+ return err
+ }
+ opts.BucketSize = parsed
+ }
+ report := tokens.Aggregate(events, opts)
+ out := cmd.OutOrStdout()
+ if endpointTokensOpts.jsonOutput {
+ encoder := json.NewEncoder(out)
+ encoder.SetIndent("", " ")
+ return encoder.Encode(report)
+ }
+ tokens.RenderText(out, report)
+ return nil
+}
+
+func init() {
+ endpointCmd.AddCommand(endpointTokensCmd)
+ endpointTokensCmd.Flags().BoolVar(&endpointTokensOpts.userMode, "user", true, "Use per-user endpoint paths")
+ endpointTokensCmd.Flags().BoolVar(&endpointTokensOpts.systemMode, "system", false, "Use system endpoint paths and launch daemon")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.logPath, "log-path", "", "Runtime JSONL log path (defaults to the endpoint runtime log; in CI point at the session log)")
+ endpointTokensCmd.Flags().BoolVar(&endpointTokensOpts.jsonOutput, "json", false, "Print the token usage report as JSON")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.since, "since", "", "Only include events at or after this RFC3339 timestamp")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.until, "until", "", "Only include events at or before this RFC3339 timestamp")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.session, "session", "", "Filter to one session and include per-step detail")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.model, "model", "", "Filter by model name")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.harness, "harness", "", "Filter by harness name")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.repository, "repository", "", "Filter by repository")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.runID, "run-id", "", "Filter by CI run id")
+ endpointTokensCmd.Flags().StringVar(&endpointTokensOpts.bucket, "bucket", "", "Time-series bucket size (for example 1h or 15m)")
+ endpointTokensCmd.Flags().IntVar(&endpointTokensOpts.top, "top", 0, "Limit each grouping to the top N entries (0 keeps all)")
+}
diff --git a/cli/beacon/cmd/endpoint_tokens_test.go b/cli/beacon/cmd/endpoint_tokens_test.go
new file mode 100644
index 00000000..4319940b
--- /dev/null
+++ b/cli/beacon/cmd/endpoint_tokens_test.go
@@ -0,0 +1,113 @@
+package cmd
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/tokens"
+)
+
+func TestEndpointTokensCommandRegistered(t *testing.T) {
+ cmd, _, err := endpointCmd.Find([]string{"tokens"})
+ if err != nil {
+ t.Fatalf("Find tokens returned error: %v", err)
+ }
+ if cmd == nil || cmd.Use != "tokens" {
+ t.Fatalf("tokens command not registered: %#v", cmd)
+ }
+ for _, flag := range []string{"log-path", "json", "since", "until", "session", "model", "harness", "repository", "run-id", "bucket", "top"} {
+ if cmd.Flags().Lookup(flag) == nil {
+ t.Fatalf("tokens command missing --%s flag", flag)
+ }
+ }
+}
+
+func writeTokensFixtureLog(t *testing.T) string {
+ t.Helper()
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ lines := []string{
+ `{"timestamp":"2026-06-11T10:00:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"os":"darwin"},"harness":{"name":"claude_code"},"session":{"id":"session-1"},"model":"claude-sonnet-4-5","gen_ai":{"usage":{"input_tokens":100}},"message":"claude_code.token.usage","raw":{"metric_name":"claude_code.token.usage","metric_temporality":"Delta"}}`,
+ `{"timestamp":"2026-06-11T10:00:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"os":"darwin"},"harness":{"name":"claude_code"},"session":{"id":"session-1"},"model":"claude-sonnet-4-5","gen_ai":{"usage":{"output_tokens":40}},"message":"claude_code.token.usage","raw":{"metric_name":"claude_code.token.usage","metric_temporality":"Delta"}}`,
+ `{"timestamp":"2026-06-11T10:05:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"cost.usage","category":"metric"},"severity":"info","endpoint":{"os":"darwin"},"harness":{"name":"claude_code"},"session":{"id":"session-1"},"model":"claude-sonnet-4-5","run":{"provider":"github_actions","run_id":"777"},"gen_ai":{"usage":{"cost_usd":0.5}},"message":"claude_code.cost.usage","raw":{"metric_name":"claude_code.cost.usage","metric_temporality":"Delta"}}`,
+ }
+ if err := os.WriteFile(logPath, []byte(strings.Join(lines, "\n")+"\n"), 0644); err != nil {
+ t.Fatalf("write fixture log: %v", err)
+ }
+ return logPath
+}
+
+func runTokensCommand(t *testing.T, args ...string) string {
+ t.Helper()
+ endpointTokensOpts = struct {
+ userMode bool
+ systemMode bool
+ logPath string
+ jsonOutput bool
+ since string
+ until string
+ session string
+ model string
+ harness string
+ repository string
+ runID string
+ bucket string
+ top int
+ }{userMode: true}
+ if err := endpointTokensCmd.Flags().Parse(args); err != nil {
+ t.Fatalf("parse flags: %v", err)
+ }
+ var out bytes.Buffer
+ endpointTokensCmd.SetOut(&out)
+ defer endpointTokensCmd.SetOut(nil)
+ if err := runEndpointTokens(endpointTokensCmd, nil); err != nil {
+ t.Fatalf("runEndpointTokens returned error: %v", err)
+ }
+ return out.String()
+}
+
+func TestEndpointTokensTextReport(t *testing.T) {
+ logPath := writeTokensFixtureLog(t)
+ output := runTokensCommand(t, "--log-path", logPath)
+ for _, want := range []string{
+ "3 of 3 events carry usage",
+ "claude-sonnet-4-5",
+ "session-1",
+ "claude_code",
+ "github_actions/777",
+ "0.5000",
+ } {
+ if !strings.Contains(output, want) {
+ t.Fatalf("text report missing %q:\n%s", want, output)
+ }
+ }
+}
+
+func TestEndpointTokensJSONReport(t *testing.T) {
+ logPath := writeTokensFixtureLog(t)
+ output := runTokensCommand(t, "--log-path", logPath, "--json", "--session", "session-1")
+ var report tokens.Report
+ if err := json.Unmarshal([]byte(output), &report); err != nil {
+ t.Fatalf("unmarshal JSON report: %v\n%s", err, output)
+ }
+ if report.Totals.InputTokens != 100 || report.Totals.OutputTokens != 40 || report.Totals.CostUSD != 0.5 {
+ t.Fatalf("totals = %#v", report.Totals)
+ }
+ if len(report.ByRun) != 1 || report.ByRun[0].Key != "github_actions/777" {
+ t.Fatalf("by_run = %#v", report.ByRun)
+ }
+ if report.SessionDetail == nil || report.SessionDetail.SessionID != "session-1" || len(report.SessionDetail.Steps) != 3 {
+ t.Fatalf("session detail = %#v", report.SessionDetail)
+ }
+}
+
+func TestEndpointTokensEmptyLogSucceeds(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ output := runTokensCommand(t, "--log-path", logPath)
+ if !strings.Contains(output, "0 of 0 events carry usage") {
+ t.Fatalf("empty report = %q", output)
+ }
+}