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
Add beacon endpoint tokens report command
Claude03e104db4fb3
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mdindex 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 activitywithout a hosted backend. The overview screen summarizes recent runtime eventsand 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. Theactive file rotates at 10 MiB with five numbered local archives, keeping thediff --git a/cli/beacon/cmd/endpoint_tokens.go b/cli/beacon/cmd/endpoint_tokens.gonew file mode 100644index 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.gonew file mode 100644index 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)+ }+}