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
package ci
import (
"fmt"
"net/url"
"os"
"path/filepath"
"strings"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/claudeotel"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
)
const (
DefaultHarness = "claude"
DefaultSessionHarness = "claude,codex"
HarnessClaude = "claude"
HarnessClaudeCode = "claude_code"
HarnessCodex = "codex"
HarnessCodexCLI = "codex_cli"
)
type HarnessConfig struct {
Harnesses []string `json:"harnesses"`
Env map[string]string `json:"env,omitempty"`
Paths map[string]string `json:"paths,omitempty"`
}
// claudeEnv adds Claude Code's telemetry variables to env, the overlay laid over caller, which is
// the environment the session runs under and where a deliberately tuned export timing is read from.
func claudeEnv(env, caller map[string]string, endpoint string) map[string]string {
for key, value := range claudeotel.OTLPEnv(endpoint, caller) {
env[key] = value
}
for key, value := range claudeEnvDefaults {
if strings.TrimSpace(caller[key]) != "" {
value = caller[key]
}
env[key] = value
}
return env
}
// claudeEnvDefaults are set only when the caller has not set them. Someone who has deliberately
// tuned these has a reason, and this is a wrapper around their session rather than an owner of
// their telemetry configuration.
var claudeEnvDefaults = map[string]string{
// Export on a timer that fits the session, instead of relying on the flush at shutdown.
//
// The OpenTelemetry default metric interval is 60 seconds, and `ci exec` wraps sessions that
// finish in five or ten. Nothing is exported on a timer in that window, so every event depends on
// the exporter flushing during shutdown, before the process exits and before `ci exec` stops the
// collector behind it. That is a race, and it was being lost about two runs in three: three
// dispatched runs of the same commit captured 21 events once and zero twice, with the agent doing
// identical work each time and the passing run being the longest of the three (#320).
//
// A shutdown flush is still the backstop and still has to work. This just stops it being the only
// thing between a captured session and an empty log.
"OTEL_METRIC_EXPORT_INTERVAL": "5000",
// The batch processors default to 1s and 5s respectively, which is already inside a short
// session -- pinned anyway so the whole pipeline's timing is stated in one place rather than
// inherited from three different SDK defaults.
"OTEL_BLRP_SCHEDULE_DELAY": "1000",
"OTEL_BSP_SCHEDULE_DELAY": "1000",
}
func BuildHarnessConfig(base []string, harnessList, grpcEndpoint, baseDir string, run *schema.RunInfo) (HarnessConfig, error) {
harnesses, err := NormalizeHarnesses(harnessList, DefaultHarness)
if err != nil {
return HarnessConfig{}, err
}
baseEnv := envMap(base)
env := map[string]string{}
if existing := strings.TrimSpace(baseEnv["OTEL_RESOURCE_ATTRIBUTES"]); existing != "" {
env["OTEL_RESOURCE_ATTRIBUTES"] = existing
}
paths := map[string]string{}
for _, harness := range harnesses {
switch harness {
case HarnessClaude:
// RunChild lays env over the caller's own environment, so the defaults have to be
// decided against that environment, not against the handful of keys env holds.
env = claudeEnv(env, baseEnv, grpcEndpoint)
case HarnessCodex:
codexHome := filepath.Join(baseDir, "codex-home")
if err := writeCodexConfig(codexHome, grpcEndpoint); err != nil {
return HarnessConfig{}, err
}
env["CODEX_HOME"] = codexHome
paths["codex_home"] = codexHome
}
}
env = envMap(WithCIResourceAttributes(flattenEnv(env), run))
env["BEACON_CI_BASE_DIR"] = baseDir
return HarnessConfig{Harnesses: harnesses, Env: env, Paths: paths}, nil
}
func NormalizeHarnesses(value, fallback string) ([]string, error) {
if strings.TrimSpace(value) == "" {
value = fallback
}
seen := map[string]struct{}{}
var out []string
for _, part := range strings.Split(value, ",") {
normalized, err := NormalizeHarness(part)
if err != nil {
return nil, err
}
if normalized == "" {
continue
}
if _, ok := seen[normalized]; ok {
continue
}
seen[normalized] = struct{}{}
out = append(out, normalized)
}
if len(out) == 0 {
return nil, fmt.Errorf("at least one CI harness is required")
}
return out, nil
}
func NormalizeHarness(value string) (string, error) {
switch strings.ToLower(strings.TrimSpace(value)) {
case "":
return "", nil
case HarnessClaude, HarnessClaudeCode:
return HarnessClaude, nil
case HarnessCodex, HarnessCodexCLI:
return HarnessCodex, nil
default:
return "", fmt.Errorf("unsupported CI harness %q; supported values are claude and codex", value)
}
}
func HarnessesString(harnesses []string) string {
if len(harnesses) == 0 {
return ""
}
return strings.Join(harnesses, ",")
}
func writeCodexConfig(codexHome, endpoint string) error {
if err := os.MkdirAll(codexHome, 0755); err != nil {
return err
}
body := strings.Join([]string{
"[otel]",
"environment = \"ci\"",
"log_user_prompt = true",
"",
"[otel.exporter.\"otlp-grpc\"]",
fmt.Sprintf("endpoint = %q", endpoint),
"",
}, "\n")
return os.WriteFile(filepath.Join(codexHome, "config.toml"), []byte(body), 0600)
}
func WithCIResourceAttributes(base []string, run *schema.RunInfo) []string {
attrs := RunResourceAttributes(run)
if attrs == "" {
return base
}
env := envMap(base)
if existing := strings.TrimSpace(env["OTEL_RESOURCE_ATTRIBUTES"]); existing != "" {
env["OTEL_RESOURCE_ATTRIBUTES"] = existing + "," + attrs
} else {
env["OTEL_RESOURCE_ATTRIBUTES"] = attrs
}
return flattenEnv(env)
}
func RunResourceAttributes(run *schema.RunInfo) string {
if run == nil {
return ""
}
fields := []struct {
key string
value string
}{
{schema.AttributeOrigin, string(schema.OriginCI)},
{schema.AttributeRunProvider, run.Provider},
{schema.AttributeRunID, run.RunID},
{schema.AttributeRunAttempt, run.RunAttempt},
{schema.AttributeRunWorkflow, run.Workflow},
{schema.AttributeRunJob, run.Job},
{schema.AttributeRunEventName, run.EventName},
{schema.AttributeRunCommit, run.Commit},
{schema.AttributeRunRepository, run.Repository},
{schema.AttributeRunBranch, run.Branch},
{schema.AttributeRunPR, run.PR},
{schema.AttributeRunPRNumber, run.PRNumber},
{schema.AttributeRunActor, run.Actor},
}
attrs := make([]string, 0, len(fields)+1)
for _, field := range fields {
if strings.TrimSpace(field.value) == "" {
continue
}
attrs = append(attrs, field.key+"="+percentEncodeResourceValue(field.value))
}
if run.Ephemeral {
attrs = append(attrs, schema.AttributeRunEphemeral+"=true")
}
return strings.Join(attrs, ",")
}
func percentEncodeResourceValue(value string) string {
// OTEL_RESOURCE_ATTRIBUTES uses W3C Baggage-style percent encoding. QueryEscape
// escapes delimiters such as comma and equals; spaces must remain percent-encoded.
return strings.ReplaceAll(url.QueryEscape(value), "+", "%20")
}
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
}