Skip to content

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

7.3 KB
Raw Blame
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
}