Skip to content

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

Add Claude CI telemetry commands

Cursor Agent8a1ea68c721f
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index a1b920e0..b2423795 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -69,6 +69,45 @@ approval decision, repository, session, or message. Quick filters surface
high-severity events, failures, approvals, MCP activity, file changes, and events
that may need review.
+## Claude Code in CI
+
+Use `beacon ci exec` to collect Claude Code OpenTelemetry for a single CI job
+without installing a persistent endpoint service or changing
+`~/.claude/settings.json`:
+
+```bash
+./beacon ci exec --harness claude -- claude --print "Summarize this repository in one sentence"
+```
+
+Beacon starts the bundled `beacon-otelcol` in the foreground, writes a
+job-scoped collector config under `$RUNNER_TEMP/beacon` when available, injects
+Claude telemetry environment variables into only the child process, validates
+that structured Beacon events reached the runtime JSONL log, and returns the
+Claude command's exit code when telemetry validation succeeds.
+
+Validate an existing CI artifact explicitly:
+
+```bash
+./beacon ci validate \
+ --harness claude \
+ --log-path "$RUNNER_TEMP/beacon/runtime.jsonl" \
+ --min-events 1
+```
+
+Upload the log from GitHub Actions for customer-controlled retention:
+
+```yaml
+- name: Run Claude with Beacon telemetry
+ run: beacon ci exec --harness claude -- claude --print "Summarize this repository"
+
+- name: Upload Beacon telemetry
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: beacon-runtime-log
+ path: ${{ runner.temp }}/beacon/runtime.jsonl
+```
+
## Wazuh
```bash
diff --git a/cli/beacon/cmd/ci.go b/cli/beacon/cmd/ci.go
new file mode 100644
index 00000000..707aaede
--- /dev/null
+++ b/cli/beacon/cmd/ci.go
@@ -0,0 +1,172 @@
+package cmd
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "os"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ beaconci "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/ci"
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+var ciOpts struct {
+ baseDir string
+ logPath string
+ workDir string
+ collectorPath string
+ harness string
+ contentRetention string
+ grpcPort int
+ httpPort int
+ jsonOutput bool
+ keepArtifacts bool
+ minEvents int
+ requireHarness string
+}
+
+var ciCmd = &cobra.Command{
+ Use: "ci",
+ Short: "Run ephemeral AI runtime telemetry collection in CI",
+ Long: `Run Beacon telemetry collection for a single CI job without installing a
+persistent endpoint service or modifying user harness configuration.`,
+}
+
+var ciExecCmd = &cobra.Command{
+ Use: "exec --harness claude -- <command> [args...]",
+ Short: "Run a command with Claude Code telemetry captured for CI",
+ Args: cobra.MinimumNArgs(1),
+ SilenceUsage: true,
+ RunE: runCIExec,
+}
+
+var ciValidateCmd = &cobra.Command{
+ Use: "validate",
+ Short: "Validate CI runtime telemetry artifacts",
+ SilenceUsage: true,
+ RunE: runCIValidate,
+}
+
+func init() {
+ rootCmd.AddCommand(ciCmd)
+ ciCmd.AddCommand(ciExecCmd)
+ ciCmd.AddCommand(ciValidateCmd)
+ for _, cmd := range []*cobra.Command{ciExecCmd, ciValidateCmd} {
+ cmd.Flags().StringVar(&ciOpts.logPath, "log-path", "", "CI runtime JSONL log path")
+ cmd.Flags().StringVar(&ciOpts.harness, "harness", beaconci.DefaultHarness, "CI harness to configure (currently only claude)")
+ cmd.Flags().BoolVar(&ciOpts.jsonOutput, "json", false, "Print result as JSON")
+ cmd.Flags().IntVar(&ciOpts.minEvents, "min-events", beaconci.DefaultValidationMin, "Minimum matching events required during validation")
+ cmd.Flags().StringVar(&ciOpts.requireHarness, "require-harness", "", "Require at least one event from this harness")
+ }
+ ciExecCmd.Flags().StringVar(&ciOpts.baseDir, "base-dir", "", "CI session base directory (defaults to $RUNNER_TEMP/beacon or a temp directory)")
+ ciExecCmd.Flags().StringVar(&ciOpts.workDir, "work-dir", "", "Working directory for the child command")
+ ciExecCmd.Flags().StringVar(&ciOpts.collectorPath, "collector", "", "Path to a beacon-otelcol binary")
+ ciExecCmd.Flags().IntVar(&ciOpts.grpcPort, "otlp-grpc-port", endpointconfig.DefaultGRPCPort, "Local OTLP gRPC port")
+ ciExecCmd.Flags().IntVar(&ciOpts.httpPort, "otlp-http-port", endpointconfig.DefaultHTTPPort, "Local OTLP HTTP port")
+ ciExecCmd.Flags().StringVar(&ciOpts.contentRetention, "content-retention", string(endpointconfig.ContentRetentionFull), "Content retention mode: metadata, redacted, or full")
+ ciExecCmd.Flags().BoolVar(&ciOpts.keepArtifacts, "keep-artifacts", true, "Keep CI runtime log and collector config after exit")
+}
+
+func runCIExec(cmd *cobra.Command, args []string) error {
+ if ciOpts.requireHarness == "" {
+ ciOpts.requireHarness = ciOpts.harness
+ }
+ session, err := beaconci.Provision(beaconci.Options{
+ BaseDir: ciOpts.baseDir,
+ LogPath: ciOpts.logPath,
+ WorkDir: ciOpts.workDir,
+ CollectorPath: ciOpts.collectorPath,
+ GRPCPort: ciOpts.grpcPort,
+ HTTPPort: ciOpts.httpPort,
+ Harness: ciOpts.harness,
+ ContentRetention: endpointconfig.ContentRetention(ciOpts.contentRetention),
+ KeepArtifacts: ciOpts.keepArtifacts,
+ })
+ if err != nil {
+ return err
+ }
+ if err := session.Start(cmd.Context(), os.Stdout, os.Stderr); err != nil {
+ return err
+ }
+ childExit, childErr := session.RunChild(cmd.Context(), args, os.Stdout, os.Stderr)
+ stopCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ stopErr := session.Stop(stopCtx)
+ cancel()
+ if childErr != nil {
+ return childErr
+ }
+ if stopErr != nil {
+ return stopErr
+ }
+ result := beaconci.Validate(beaconci.ValidationOptions{
+ LogPath: session.LogPath,
+ MinEvents: ciOpts.minEvents,
+ RequireHarness: ciOpts.requireHarness,
+ })
+ execResult := beaconci.ExecResult{
+ Session: *session,
+ ChildExitCode: childExit,
+ Validation: result,
+ ArtifactMessage: fmt.Sprintf("Beacon CI artifacts: log=%s config=%s", session.LogPath, session.ConfigPath),
+ }
+ if ciOpts.jsonOutput {
+ _ = json.NewEncoder(os.Stdout).Encode(execResult)
+ } else {
+ printCIValidation(result)
+ fmt.Println(execResult.ArtifactMessage)
+ }
+ if result.Status == "fail" {
+ fmt.Fprintln(os.Stderr, "Beacon CI telemetry validation failed")
+ if childExit != 0 {
+ os.Exit(childExit)
+ }
+ return fmt.Errorf("Beacon CI telemetry validation failed")
+ }
+ if childExit != 0 {
+ os.Exit(childExit)
+ }
+ return nil
+}
+
+func runCIValidate(cmd *cobra.Command, args []string) error {
+ logPath := ciOpts.logPath
+ if logPath == "" {
+ logPath = beaconci.DefaultLogPath()
+ }
+ requireHarness := ciOpts.requireHarness
+ if requireHarness == "" {
+ requireHarness = ciOpts.harness
+ }
+ result := beaconci.Validate(beaconci.ValidationOptions{
+ LogPath: logPath,
+ MinEvents: ciOpts.minEvents,
+ RequireHarness: requireHarness,
+ })
+ if ciOpts.jsonOutput {
+ _ = json.NewEncoder(os.Stdout).Encode(result)
+ } else {
+ printCIValidation(result)
+ }
+ if result.Status == "fail" {
+ return fmt.Errorf("Beacon CI telemetry validation failed")
+ }
+ return nil
+}
+
+func printCIValidation(result beaconci.ValidationResult) {
+ fmt.Printf("Beacon CI validation: %s\n", result.Status)
+ fmt.Printf("Runtime log: %s\n", result.LogPath)
+ for _, stage := range result.Stages {
+ fmt.Printf("%s: %s", stage.Name, stage.Status)
+ if stage.Target != "" {
+ fmt.Printf(" target=%s", stage.Target)
+ }
+ if stage.Message != "" {
+ fmt.Printf(" (%s)", stage.Message)
+ }
+ fmt.Println()
+ }
+}
diff --git a/cli/beacon/cmd/ci_test.go b/cli/beacon/cmd/ci_test.go
new file mode 100644
index 00000000..4b4830a9
--- /dev/null
+++ b/cli/beacon/cmd/ci_test.go
@@ -0,0 +1,42 @@
+package cmd
+
+import "testing"
+
+func TestCICommandsRegistered(t *testing.T) {
+ for _, path := range [][]string{
+ {"ci"},
+ {"ci", "exec"},
+ {"ci", "validate"},
+ } {
+ cmd, _, err := rootCmd.Find(path)
+ if err != nil {
+ t.Fatalf("Find %v returned error: %v", path, err)
+ }
+ if cmd == nil {
+ t.Fatalf("command %v not registered", path)
+ }
+ }
+ for _, name := range []string{"harness", "log-path", "min-events", "require-harness", "json"} {
+ if ciExecCmd.Flags().Lookup(name) == nil {
+ t.Fatalf("ci exec missing --%s", name)
+ }
+ if ciValidateCmd.Flags().Lookup(name) == nil {
+ t.Fatalf("ci validate missing --%s", name)
+ }
+ }
+ for _, name := range []string{"base-dir", "work-dir", "collector", "otlp-grpc-port", "otlp-http-port", "content-retention", "keep-artifacts"} {
+ if ciExecCmd.Flags().Lookup(name) == nil {
+ t.Fatalf("ci exec missing --%s", name)
+ }
+ }
+}
+
+func TestCIHarnessDefaultIsClaudeOnly(t *testing.T) {
+ flag := ciExecCmd.Flags().Lookup("harness")
+ if flag == nil {
+ t.Fatal("ci exec missing --harness")
+ }
+ if flag.DefValue != "claude" {
+ t.Fatalf("ci exec --harness default = %q, want claude", flag.DefValue)
+ }
+}
diff --git a/cli/beacon/internal/ci/harness.go b/cli/beacon/internal/ci/harness.go
new file mode 100644
index 00000000..9e0a1e5f
--- /dev/null
+++ b/cli/beacon/internal/ci/harness.go
@@ -0,0 +1,43 @@
+package ci
+
+import (
+ "fmt"
+ "strings"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+func ClaudeEnv(base []string, endpoint string, retention endpointconfig.ContentRetention) []string {
+ env := envMap(base)
+ env["CLAUDE_CODE_ENABLE_TELEMETRY"] = "1"
+ env["OTEL_LOGS_EXPORTER"] = "otlp"
+ env["OTEL_METRICS_EXPORTER"] = "otlp"
+ env["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
+ env["OTEL_EXPORTER_OTLP_ENDPOINT"] = endpoint
+ if retention == endpointconfig.ContentRetentionMetadata {
+ delete(env, "OTEL_LOG_USER_PROMPTS")
+ } else {
+ env["OTEL_LOG_USER_PROMPTS"] = "1"
+ }
+ return flattenEnv(env)
+}
+
+func envMap(values []string) map[string]string {
+ out := map[string]string{}
+ for _, value := range values {
+ key, val, ok := strings.Cut(value, "=")
+ if !ok || key == "" {
+ continue
+ }
+ out[key] = val
+ }
+ return out
+}
+
+func flattenEnv(values map[string]string) []string {
+ out := make([]string, 0, len(values))
+ for key, value := range values {
+ out = append(out, fmt.Sprintf("%s=%s", key, value))
+ }
+ return out
+}
diff --git a/cli/beacon/internal/ci/harness_test.go b/cli/beacon/internal/ci/harness_test.go
new file mode 100644
index 00000000..f7b9a3ed
--- /dev/null
+++ b/cli/beacon/internal/ci/harness_test.go
@@ -0,0 +1,28 @@
+package ci
+
+import (
+ "strings"
+ "testing"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+func TestClaudeEnvFullRetentionIncludesPromptLogging(t *testing.T) {
+ env := strings.Join(ClaudeEnv([]string{"PATH=/bin", "OTEL_LOG_USER_PROMPTS=0"}, "http://127.0.0.1:4317", endpointconfig.ContentRetentionFull), "\n")
+ for _, want := range []string{
+ "CLAUDE_CODE_ENABLE_TELEMETRY=1",
+ "OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317",
+ "OTEL_LOG_USER_PROMPTS=1",
+ } {
+ if !strings.Contains(env, want) {
+ t.Fatalf("ClaudeEnv missing %q in:\n%s", want, env)
+ }
+ }
+}
+
+func TestClaudeEnvMetadataRetentionOmitsPromptLogging(t *testing.T) {
+ env := strings.Join(ClaudeEnv([]string{"OTEL_LOG_USER_PROMPTS=1"}, "http://127.0.0.1:4317", endpointconfig.ContentRetentionMetadata), "\n")
+ if strings.Contains(env, "OTEL_LOG_USER_PROMPTS=") {
+ t.Fatalf("ClaudeEnv metadata retention should omit OTEL_LOG_USER_PROMPTS:\n%s", env)
+ }
+}
diff --git a/cli/beacon/internal/ci/session.go b/cli/beacon/internal/ci/session.go
new file mode 100644
index 00000000..588b6525
--- /dev/null
+++ b/cli/beacon/internal/ci/session.go
@@ -0,0 +1,306 @@
+package ci
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "io"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strings"
+ "syscall"
+ "time"
+
+ endpointcollector "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/collector"
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
+)
+
+const (
+ DefaultHarness = "claude"
+ DefaultValidationMin = 1
+)
+
+var (
+ resolveCollectorBinary = endpointcollector.ResolveBinary
+ writeCollectorConfig = endpointcollector.WriteConfig
+ waitCollectorReady = endpointcollector.WaitUntilReady
+ commandContext = exec.CommandContext
+)
+
+type Options struct {
+ BaseDir string
+ LogPath string
+ WorkDir string
+ CollectorPath string
+ GRPCPort int
+ HTTPPort int
+ Harness string
+ ContentRetention endpointconfig.ContentRetention
+ KeepArtifacts bool
+}
+
+type Session struct {
+ BaseDir string `json:"base_dir"`
+ LogPath string `json:"log_path"`
+ ConfigPath string `json:"config_path"`
+ CollectorBinary string `json:"collector_binary,omitempty"`
+ GRPCEndpoint string `json:"grpc_endpoint"`
+ HTTPEndpoint string `json:"http_endpoint"`
+ Harness string `json:"harness"`
+ WorkDir string `json:"work_dir,omitempty"`
+ StartedAt string `json:"started_at"`
+ Run *schema.RunInfo `json:"run,omitempty"`
+
+ cfg endpointconfig.Config
+ cancel context.CancelFunc
+ cmd *exec.Cmd
+ done chan error
+}
+
+type ExecResult struct {
+ Session Session `json:"session"`
+ ChildExitCode int `json:"child_exit_code"`
+ Validation ValidationResult `json:"validation"`
+ ArtifactMessage string `json:"artifact_message,omitempty"`
+}
+
+func Provision(opts Options) (*Session, error) {
+ if err := validateHarness(opts.Harness); err != nil {
+ return nil, err
+ }
+ if opts.ContentRetention == "" {
+ opts.ContentRetention = endpointconfig.ContentRetentionFull
+ }
+ if err := endpointconfig.ValidateContentRetention(opts.ContentRetention); err != nil {
+ return nil, err
+ }
+ baseDir, err := resolveBaseDir(opts.BaseDir)
+ if err != nil {
+ return nil, err
+ }
+ logPath := opts.LogPath
+ if logPath == "" {
+ logPath = filepath.Join(baseDir, "runtime.jsonl")
+ }
+ grpcPort := opts.GRPCPort
+ if grpcPort == 0 {
+ grpcPort = endpointconfig.DefaultGRPCPort
+ }
+ httpPort := opts.HTTPPort
+ if httpPort == 0 {
+ httpPort = endpointconfig.DefaultHTTPPort
+ }
+ cfg := endpointconfig.Default(true, logPath)
+ cfg.Harnesses = []string{DefaultHarness}
+ cfg.ContentRetention = opts.ContentRetention
+ cfg.Collector.BinaryPath = opts.CollectorPath
+ cfg.Collector.ConfigPath = filepath.Join(baseDir, "otelcol.yaml")
+ cfg.Collector.SpoolPath = filepath.Join(baseDir, "spool", "otlp.jsonl")
+ cfg.Collector.GRPCPort = grpcPort
+ cfg.Collector.HTTPPort = httpPort
+ if err := os.MkdirAll(filepath.Dir(logPath), 0755); err != nil {
+ return nil, err
+ }
+ file, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND, 0644)
+ if err != nil {
+ return nil, err
+ }
+ if err := file.Close(); err != nil {
+ return nil, err
+ }
+ if err := writeCollectorConfig(cfg); err != nil {
+ return nil, err
+ }
+ binary, err := resolveCollectorBinary(opts.CollectorPath)
+ if err != nil {
+ return nil, err
+ }
+ startedAt := time.Now().UTC()
+ return &Session{
+ BaseDir: baseDir,
+ LogPath: logPath,
+ ConfigPath: cfg.Collector.ConfigPath,
+ CollectorBinary: binary,
+ GRPCEndpoint: fmt.Sprintf("http://127.0.0.1:%d", grpcPort),
+ HTTPEndpoint: fmt.Sprintf("http://127.0.0.1:%d", httpPort),
+ Harness: DefaultHarness,
+ WorkDir: opts.WorkDir,
+ StartedAt: startedAt.Format(time.RFC3339),
+ Run: detectRunInfo(),
+ cfg: cfg,
+ }, nil
+}
+
+func (s *Session) Start(ctx context.Context, stdout, stderr io.Writer) error {
+ if s == nil {
+ return errors.New("ci session is nil")
+ }
+ if stdout == nil {
+ stdout = io.Discard
+ }
+ if stderr == nil {
+ stderr = io.Discard
+ }
+ runCtx, cancel := context.WithCancel(ctx)
+ cmd := commandContext(runCtx, s.CollectorBinary, "--config", s.ConfigPath)
+ cmd.Stdout = stdout
+ cmd.Stderr = stderr
+ if err := cmd.Start(); err != nil {
+ cancel()
+ return err
+ }
+ s.cancel = cancel
+ s.cmd = cmd
+ s.done = make(chan error, 1)
+ go func() {
+ s.done <- cmd.Wait()
+ }()
+ if err := waitCollectorReady(s.cfg, 10*time.Second); err != nil {
+ _ = s.Stop(context.Background())
+ return err
+ }
+ return nil
+}
+
+func (s *Session) Stop(ctx context.Context) error {
+ if s == nil || s.cmd == nil {
+ return nil
+ }
+ if s.cmd.Process != nil {
+ _ = terminateProcess(s.cmd.Process)
+ }
+ if s.cancel != nil {
+ s.cancel()
+ }
+ select {
+ case err := <-s.done:
+ if err != nil && !isExpectedStopError(err) {
+ return err
+ }
+ return nil
+ case <-ctx.Done():
+ if s.cmd.Process != nil {
+ _ = s.cmd.Process.Kill()
+ }
+ return ctx.Err()
+ }
+}
+
+func (s *Session) RunChild(ctx context.Context, args []string, stdout, stderr io.Writer) (int, error) {
+ if len(args) == 0 {
+ return 0, errors.New("child command is required after --")
+ }
+ cmd := commandContext(ctx, args[0], args[1:]...)
+ cmd.Dir = s.WorkDir
+ cmd.Env = append(ClaudeEnv(os.Environ(), s.GRPCEndpoint, s.cfg.ContentRetention),
+ "BEACON_CI_BASE_DIR="+s.BaseDir,
+ "BEACON_CI_CONFIG_PATH="+s.ConfigPath,
+ "BEACON_CI_LOG_PATH="+s.LogPath,
+ )
+ cmd.Stdout = stdout
+ cmd.Stderr = stderr
+ err := cmd.Run()
+ if err == nil {
+ return 0, nil
+ }
+ var exitErr *exec.ExitError
+ if errors.As(err, &exitErr) {
+ return exitErr.ExitCode(), nil
+ }
+ return 0, err
+}
+
+func (s *Session) Config() endpointconfig.Config {
+ if s == nil {
+ return endpointconfig.Config{}
+ }
+ return s.cfg
+}
+
+func validateHarness(harness string) error {
+ harness = strings.TrimSpace(harness)
+ if harness == "" || harness == DefaultHarness || harness == "claude_code" {
+ return nil
+ }
+ return fmt.Errorf("unsupported CI harness %q; only claude is supported", harness)
+}
+
+func resolveBaseDir(configured string) (string, error) {
+ if strings.TrimSpace(configured) != "" {
+ if err := os.MkdirAll(configured, 0755); err != nil {
+ return "", err
+ }
+ return filepath.Abs(configured)
+ }
+ if runnerTemp := strings.TrimSpace(os.Getenv("RUNNER_TEMP")); runnerTemp != "" {
+ base := filepath.Join(runnerTemp, "beacon")
+ if err := os.MkdirAll(base, 0755); err != nil {
+ return "", err
+ }
+ return filepath.Abs(base)
+ }
+ return os.MkdirTemp("", "beacon-ci-*")
+}
+
+func DefaultLogPath() string {
+ if runnerTemp := strings.TrimSpace(os.Getenv("RUNNER_TEMP")); runnerTemp != "" {
+ return filepath.Join(runnerTemp, "beacon", "runtime.jsonl")
+ }
+ return filepath.Join(os.TempDir(), "beacon", "runtime.jsonl")
+}
+
+func detectRunInfo() *schema.RunInfo {
+ if os.Getenv("GITHUB_ACTIONS") == "true" {
+ return &schema.RunInfo{
+ Provider: "github_actions",
+ RunID: os.Getenv("GITHUB_RUN_ID"),
+ Workflow: os.Getenv("GITHUB_WORKFLOW"),
+ Commit: os.Getenv("GITHUB_SHA"),
+ PR: os.Getenv("GITHUB_REF"),
+ Actor: os.Getenv("GITHUB_ACTOR"),
+ Ephemeral: true,
+ }
+ }
+ if os.Getenv("CI") != "" {
+ return &schema.RunInfo{Provider: "ci", Ephemeral: true}
+ }
+ return nil
+}
+
+func terminateProcess(process *os.Process) error {
+ if process == nil {
+ return nil
+ }
+ if runtime.GOOS == "windows" {
+ return process.Kill()
+ }
+ return process.Signal(syscall.SIGTERM)
+}
+
+func isExpectedStopError(err error) bool {
+ if err == nil {
+ return true
+ }
+ var exitErr *exec.ExitError
+ if errors.As(err, &exitErr) {
+ return true
+ }
+ return strings.Contains(err.Error(), "signal: terminated") || strings.Contains(err.Error(), "killed")
+}
+
+func NewSessionEvent(action, message string, run *schema.RunInfo) schema.Event {
+ return schema.NewEvent(schema.NewEventOptions{
+ Action: action,
+ Category: "ci",
+ Severity: schema.SeverityInfo,
+ AgentVersion: version.GetVersion(),
+ Harness: schema.HarnessInfo{Name: DefaultHarness},
+ Message: message,
+ Origin: schema.OriginCI,
+ Run: run,
+ })
+}
diff --git a/cli/beacon/internal/ci/session_test.go b/cli/beacon/internal/ci/session_test.go
new file mode 100644
index 00000000..0ed0191b
--- /dev/null
+++ b/cli/beacon/internal/ci/session_test.go
@@ -0,0 +1,125 @@
+package ci
+
+import (
+ "context"
+ "os"
+ "path/filepath"
+ "runtime"
+ "strings"
+ "testing"
+ "time"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+func TestProvisionUsesRunnerTempAndWritesCollectorConfig(t *testing.T) {
+ runnerTemp := t.TempDir()
+ t.Setenv("RUNNER_TEMP", runnerTemp)
+ collector := fakeExecutable(t, "collector", "#!/bin/sh\nsleep 60\n")
+ oldResolve := resolveCollectorBinary
+ resolveCollectorBinary = func(configured string) (string, error) {
+ if configured != collector {
+ t.Fatalf("configured collector = %q, want %q", configured, collector)
+ }
+ return collector, nil
+ }
+ t.Cleanup(func() { resolveCollectorBinary = oldResolve })
+
+ session, err := Provision(Options{CollectorPath: collector, Harness: "claude"})
+ if err != nil {
+ t.Fatalf("Provision returned error: %v", err)
+ }
+ if want := filepath.Join(runnerTemp, "beacon"); session.BaseDir != want {
+ t.Fatalf("BaseDir = %q, want %q", session.BaseDir, want)
+ }
+ if session.LogPath != filepath.Join(runnerTemp, "beacon", "runtime.jsonl") {
+ t.Fatalf("LogPath = %q", session.LogPath)
+ }
+ data, err := os.ReadFile(session.ConfigPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(data), session.LogPath) {
+ t.Fatalf("collector config does not reference log path:\n%s", data)
+ }
+}
+
+func TestProvisionRejectsUnsupportedHarness(t *testing.T) {
+ if _, err := Provision(Options{Harness: "codex"}); err == nil {
+ t.Fatal("Provision accepted unsupported harness")
+ }
+}
+
+func TestStartStopCollectorProcess(t *testing.T) {
+ if runtime.GOOS == "windows" {
+ t.Skip("shell fake uses POSIX signal semantics")
+ }
+ collector := fakeExecutable(t, "collector", "#!/bin/sh\ntrap 'exit 0' TERM\nwhile true; do sleep 1; done\n")
+ oldWait := waitCollectorReady
+ waitCollectorReady = func(endpointconfig.Config, time.Duration) error { return nil }
+ t.Cleanup(func() { waitCollectorReady = oldWait })
+
+ session := &Session{
+ CollectorBinary: collector,
+ ConfigPath: filepath.Join(t.TempDir(), "otelcol.yaml"),
+ cfg: endpointconfig.Default(true, filepath.Join(t.TempDir(), "runtime.jsonl")),
+ }
+ if err := os.WriteFile(session.ConfigPath, []byte("receivers: {}\n"), 0644); err != nil {
+ t.Fatal(err)
+ }
+ if err := session.Start(context.Background(), nil, nil); err != nil {
+ t.Fatalf("Start returned error: %v", err)
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+ if err := session.Stop(ctx); err != nil {
+ t.Fatalf("Stop returned error: %v", err)
+ }
+}
+
+func TestRunChildInjectsClaudeEnvAndBeaconPaths(t *testing.T) {
+ dir := t.TempDir()
+ output := filepath.Join(dir, "env.txt")
+ child := fakeExecutable(t, "child", "#!/bin/sh\nenv > \"$1\"\n")
+ session := &Session{
+ BaseDir: dir,
+ ConfigPath: filepath.Join(dir, "otelcol.yaml"),
+ LogPath: filepath.Join(dir, "runtime.jsonl"),
+ GRPCEndpoint: "http://127.0.0.1:4317",
+ cfg: endpointconfig.Default(true, filepath.Join(dir, "runtime.jsonl")),
+ }
+ exitCode, err := session.RunChild(context.Background(), []string{child, output}, nil, nil)
+ if err != nil {
+ t.Fatalf("RunChild returned error: %v", err)
+ }
+ if exitCode != 0 {
+ t.Fatalf("exitCode = %d, want 0", exitCode)
+ }
+ data, err := os.ReadFile(output)
+ if err != nil {
+ t.Fatal(err)
+ }
+ env := string(data)
+ for _, want := range []string{
+ "CLAUDE_CODE_ENABLE_TELEMETRY=1",
+ "OTEL_LOGS_EXPORTER=otlp",
+ "OTEL_METRICS_EXPORTER=otlp",
+ "OTEL_EXPORTER_OTLP_PROTOCOL=grpc",
+ "OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317",
+ "OTEL_LOG_USER_PROMPTS=1",
+ "BEACON_CI_LOG_PATH=" + session.LogPath,
+ } {
+ if !strings.Contains(env, want) {
+ t.Fatalf("child env missing %q:\n%s", want, env)
+ }
+ }
+}
+
+func fakeExecutable(t *testing.T, name, script string) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), name)
+ if err := os.WriteFile(path, []byte(script), 0755); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
diff --git a/cli/beacon/internal/ci/validate.go b/cli/beacon/internal/ci/validate.go
new file mode 100644
index 00000000..95daf747
--- /dev/null
+++ b/cli/beacon/internal/ci/validate.go
@@ -0,0 +1,167 @@
+package ci
+
+import (
+ "bufio"
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "os"
+ "strings"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+type ValidationOptions struct {
+ LogPath string
+ MinEvents int
+ RequireHarness string
+ Since time.Time
+}
+
+type ValidationStage struct {
+ Name string `json:"name"`
+ Target string `json:"target,omitempty"`
+ Status string `json:"status"`
+ Severity string `json:"severity"`
+ Message string `json:"message,omitempty"`
+ Evidence string `json:"evidence,omitempty"`
+}
+
+type ValidationResult struct {
+ Status string `json:"status"`
+ LogPath string `json:"log_path"`
+ EventCount int `json:"event_count"`
+ Stages []ValidationStage `json:"stages"`
+ GeneratedAt string `json:"generated_at"`
+}
+
+func Validate(opts ValidationOptions) ValidationResult {
+ if opts.MinEvents <= 0 {
+ opts.MinEvents = DefaultValidationMin
+ }
+ result := ValidationResult{
+ LogPath: opts.LogPath,
+ GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+ }
+ info, err := os.Stat(opts.LogPath)
+ if err != nil {
+ result.Stages = append(result.Stages, ValidationStage{Name: "runtime_log_exists", Target: opts.LogPath, Status: "fail", Severity: "high", Message: err.Error(), Evidence: "stat_failed"})
+ result.Status = aggregateValidationStatus(result.Stages)
+ return result
+ }
+ if info.IsDir() {
+ result.Stages = append(result.Stages, ValidationStage{Name: "runtime_log_exists", Target: opts.LogPath, Status: "fail", Severity: "high", Message: "runtime log path is a directory", Evidence: "path_is_directory"})
+ result.Status = aggregateValidationStatus(result.Stages)
+ return result
+ }
+ result.Stages = append(result.Stages, ValidationStage{Name: "runtime_log_exists", Target: opts.LogPath, Status: "ok", Severity: "info", Evidence: "file_exists"})
+
+ events, malformed := readStructuredEvents(opts.LogPath, opts.Since)
+ if len(malformed) > 0 {
+ result.Stages = append(result.Stages, ValidationStage{Name: "runtime_log_parseable", Target: opts.LogPath, Status: "fail", Severity: "high", Message: malformed[0], Evidence: fmt.Sprintf("malformed_lines=%d", len(malformed))})
+ result.Status = aggregateValidationStatus(result.Stages)
+ return result
+ }
+ result.Stages = append(result.Stages, ValidationStage{Name: "runtime_log_parseable", Target: opts.LogPath, Status: "ok", Severity: "info", Evidence: "jsonl_parse_succeeded"})
+
+ filtered := filterHarness(events, opts.RequireHarness)
+ result.EventCount = len(filtered)
+ if result.EventCount < opts.MinEvents {
+ target := opts.LogPath
+ if opts.RequireHarness != "" {
+ target = opts.RequireHarness
+ }
+ result.Stages = append(result.Stages, ValidationStage{Name: "event_count", Target: target, Status: "fail", Severity: "high", Message: fmt.Sprintf("observed %d events, want at least %d", result.EventCount, opts.MinEvents), Evidence: fmt.Sprintf("events=%d", result.EventCount)})
+ result.Status = aggregateValidationStatus(result.Stages)
+ return result
+ }
+ result.Stages = append(result.Stages, ValidationStage{Name: "event_count", Target: opts.LogPath, Status: "ok", Severity: "info", Message: fmt.Sprintf("observed %d events", result.EventCount), Evidence: fmt.Sprintf("events=%d", result.EventCount)})
+ if opts.RequireHarness != "" {
+ result.Stages = append(result.Stages, ValidationStage{Name: "harness_events", Target: opts.RequireHarness, Status: "ok", Severity: "info", Message: "required harness events observed"})
+ }
+ result.Status = aggregateValidationStatus(result.Stages)
+ return result
+}
+
+func readStructuredEvents(path string, since time.Time) ([]schema.Event, []string) {
+ file, err := os.Open(path)
+ if err != nil {
+ return nil, []string{err.Error()}
+ }
+ defer file.Close()
+ var events []schema.Event
+ var malformed []string
+ scanner := bufio.NewScanner(file)
+ scanner.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
+ lineNo := 0
+ for scanner.Scan() {
+ lineNo++
+ line := bytes.TrimSpace(scanner.Bytes())
+ if len(line) == 0 {
+ continue
+ }
+ var event schema.Event
+ if err := json.Unmarshal(line, &event); err != nil {
+ malformed = append(malformed, fmt.Sprintf("line %d: %v", lineNo, err))
+ continue
+ }
+ if err := event.Validate(); err != nil {
+ malformed = append(malformed, fmt.Sprintf("line %d: %v", lineNo, err))
+ continue
+ }
+ if !since.IsZero() {
+ ts, err := time.Parse(time.RFC3339, event.Timestamp)
+ if err != nil {
+ malformed = append(malformed, fmt.Sprintf("line %d: timestamp is not RFC3339", lineNo))
+ continue
+ }
+ if ts.Before(since) {
+ continue
+ }
+ }
+ events = append(events, event)
+ }
+ if err := scanner.Err(); err != nil {
+ malformed = append(malformed, err.Error())
+ }
+ return events, malformed
+}
+
+func filterHarness(events []schema.Event, harness string) []schema.Event {
+ harness = strings.TrimSpace(harness)
+ if harness == "" {
+ return events
+ }
+ var out []schema.Event
+ for _, event := range events {
+ if harnessMatches(event.Harness.Name, harness) {
+ out = append(out, event)
+ }
+ }
+ return out
+}
+
+func harnessMatches(got, want string) bool {
+ switch want {
+ case "claude":
+ return got == "claude" || got == "claude_code"
+ case "claude_code":
+ return got == "claude" || got == "claude_code"
+ default:
+ return got == want
+ }
+}
+
+func aggregateValidationStatus(stages []ValidationStage) string {
+ status := "ok"
+ for _, stage := range stages {
+ switch stage.Status {
+ case "fail":
+ return "fail"
+ case "warn":
+ status = "warn"
+ }
+ }
+ return status
+}
diff --git a/cli/beacon/internal/ci/validate_test.go b/cli/beacon/internal/ci/validate_test.go
new file mode 100644
index 00000000..59861ad3
--- /dev/null
+++ b/cli/beacon/internal/ci/validate_test.go
@@ -0,0 +1,65 @@
+package ci
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+)
+
+func TestValidateRequiresStructuredHarnessEvent(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ event := NewSessionEvent("ci.test", "test event", nil)
+ event.Harness.Name = "claude_code"
+ writeEventLine(t, path, event)
+
+ result := Validate(ValidationOptions{LogPath: path, MinEvents: 1, RequireHarness: "claude"})
+ if result.Status != "ok" {
+ t.Fatalf("Validate status = %q, stages=%#v", result.Status, result.Stages)
+ }
+ if result.EventCount != 1 {
+ t.Fatalf("EventCount = %d, want 1", result.EventCount)
+ }
+}
+
+func TestValidateFailsOnMalformedJSONL(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ if err := os.WriteFile(path, []byte("{not-json}\n"), 0644); err != nil {
+ t.Fatal(err)
+ }
+ result := Validate(ValidationOptions{LogPath: path, MinEvents: 1})
+ if result.Status != "fail" {
+ t.Fatalf("Validate status = %q, want fail", result.Status)
+ }
+ if len(result.Stages) < 2 || result.Stages[1].Name != "runtime_log_parseable" {
+ t.Fatalf("unexpected stages: %#v", result.Stages)
+ }
+}
+
+func TestValidateFailsWhenHarnessEventMissing(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "runtime.jsonl")
+ event := NewSessionEvent("ci.test", "test event", nil)
+ event.Harness.Name = "codex_cli"
+ writeEventLine(t, path, event)
+
+ result := Validate(ValidationOptions{LogPath: path, MinEvents: 1, RequireHarness: "claude"})
+ if result.Status != "fail" {
+ t.Fatalf("Validate status = %q, want fail", result.Status)
+ }
+ if result.EventCount != 0 {
+ t.Fatalf("EventCount = %d, want 0", result.EventCount)
+ }
+}
+
+func writeEventLine(t *testing.T, path string, event schema.Event) {
+ t.Helper()
+ data, err := json.Marshal(event)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(path, append(data, '\n'), 0644); err != nil {
+ t.Fatal(err)
+ }
+}