Skip to content

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

19.6 KB
Raw Blame
package image

import (
	"archive/tar"
	"compress/gzip"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"os/exec"
	"path/filepath"
	"sort"
	"strconv"
	"strings"
	"time"
)

// The collector carries the telemetry normalization, so which build you run matters more than it
// looks: a stale or downloaded collector will not contain local exporter changes, and a run
// against it silently verifies the wrong code.
const (
	collectorRelPath = "collector-builder/dist/beacon-otelcol/linux_amd64/beacon-otelcol"
	beaconRelPath    = "cli/beacon/beacon-linux-amd64"

	// releaseAPI is queried for the newest published tarball. Only used to fill in a missing
	// collector; nothing here ever fetches the `beacon` CLI, which must come from your tree.
	releaseAPI = "https://api.github.com/repos/Asymptote-Labs/agent-beacon/releases/latest"
)

// BeaconPath and CollectorPath report where each artifact is expected.
func BeaconPath(repoRoot string) string    { return filepath.Join(repoRoot, beaconRelPath) }
func CollectorPath(repoRoot string) string { return filepath.Join(repoRoot, collectorRelPath) }

// BuildBeaconHint is the command that produces the Beacon binary under test.
const BuildBeaconHint = "cd cli/beacon && make build-linux-amd64"

// EnsureCollector returns the collector path, downloading a released build if absent.
//
// Deliberately does not attempt to *build* the collector: that needs the OpenTelemetry Collector
// Builder and a multi-step invocation, which is the single biggest setup cliff. Published
// releases ship `beacon-otelcol` inside the Linux tarball, so a download covers everyone who has
// not modified the exporter.
func EnsureCollector(repoRoot string, log func(string, ...any)) (string, error) {
	if log == nil {
		log = func(string, ...any) {}
	}
	dst := CollectorPath(repoRoot)
	if fi, err := os.Stat(dst); err == nil && fi.Size() > 0 {
		return dst, nil
	}

	rel, err := latestLinuxTarball()
	if err != nil {
		return "", fmt.Errorf("collector missing at %s and no release could be resolved: %w\n"+
			"build it instead:\n"+
			"  go install go.opentelemetry.io/collector/cmd/[email protected]\n"+
			"  cd collector-builder && mkdir -p dist && GOOS=linux GOARCH=amd64 CGO_ENABLED=0 \"$(go env GOPATH)/bin/builder\" --config builder.yaml", dst, err)
	}
	log("collector not found; downloading beacon-otelcol from release %s", rel.Version)
	if err := downloadCollector(rel, dst, log); err != nil {
		return "", fmt.Errorf("download collector from %s: %w", rel.URL, err)
	}
	if err := writeProvenance(repoRoot, rel.Version); err != nil {
		// Not fatal: the binary is usable. But freshness checking degrades without it, so say so.
		log("warning: could not record collector provenance (%v); freshness checking will be weaker", err)
	}
	log("collector ready at %s", dst)
	return dst, nil
}

// provenancePath records where the collector binary came from. Without it, a downloaded release
// binary is indistinguishable from one built from the current tree, which is the difference
// between "verifies your change" and "verifies last release".
func provenancePath(repoRoot string) string {
	return CollectorPath(repoRoot) + ".provenance"
}

// writeProvenance records the release a binary was downloaded from, together with enough of the
// binary's identity to tell later whether the marker still describes it.
//
// The identity matters more than it looks. A first version recorded only the release tag, and
// nothing clears the marker when someone rebuilds locally -- which is exactly what the freshness
// warning tells them to do. CollectorIsStale then kept reporting "downloaded from release X, and
// collector-builder/ has changed since" forever, so the warning could never be cleared by doing
// the thing it asked for. A warning that cannot be satisfied trains people to ignore it, which is
// worse than the false pass it replaced. Reported by Cursor Bugbot.
func writeProvenance(repoRoot, version string) error {
	fi, err := os.Stat(CollectorPath(repoRoot))
	if err != nil {
		return err
	}
	body := fmt.Sprintf("release:%s\nsize:%d\nmtime:%d\n",
		version, fi.Size(), fi.ModTime().UnixNano())
	return os.WriteFile(provenancePath(repoRoot), []byte(body), 0o644)
}

// CollectorIsStale reports whether the on-disk beacon-otelcol may not contain the exporter code
// in the current tree, and why.
//
// The first version only looked at uncommitted `git status` under collector-builder/, which left
// the two most likely false passes wide open: exporter changes that were already committed, and a
// binary fetched by `doctor --fix` from a release that predates the branch entirely. Either way
// `collector_freshness` reported green while the binary under test lacked the change -- exactly
// the trap this check exists to catch, and the trap that already cost one wasted investigation.
// Cursor Bugbot flagged the gap.
//
// Three signals now, cheapest first:
//
//   - uncommitted changes under collector-builder/
//   - a downloaded release binary with any collector-builder/ change since that release tag
//   - a locally built binary older than the newest collector-builder/ source file
func CollectorIsStale(repoRoot string) (bool, string) {
	if files := uncommittedCollectorChanges(repoRoot); files != "" {
		return true, "uncommitted changes under collector-builder/: " + files
	}

	binary := CollectorPath(repoRoot)
	fi, err := os.Stat(binary)
	if err != nil {
		// No binary is a separate check's problem, not a freshness question.
		return false, ""
	}

	tag, state := recordedRelease(repoRoot)
	if state == provenanceTrusted {
		changed, resolved := collectorChangesSince(repoRoot, tag)
		switch {
		case resolved && changed != "":
			return true, fmt.Sprintf("binary was downloaded from release %s, but collector-builder/ "+
				"has changed since: %s", tag, changed)
		case resolved:
			return false, ""
		default:
			// The tag cannot be resolved, so drift is unknowable. Reported rather than assumed
			// clean: "I could not check" must never render as "nothing to check".
			return true, fmt.Sprintf("binary was downloaded from release %s, which this clone "+
				"cannot resolve, so drift cannot be checked (try `git fetch --tags`, or rebuild "+
				"the collector locally)", tag)
		}
	}

	// A source file newer than the binary means the binary predates it, whatever its origin.
	if newer := sourcesNewerThan(repoRoot, fi.ModTime()); newer != "" {
		return true, "collector-builder/ sources are newer than the built binary: " + newer
	}

	// Sources are older than the binary, which for a local rebuild means fresh -- but with no
	// trustworthy provenance there is no way to tell a local build from a release download, and a
	// downloaded binary is essentially always newer than local sources. So this signal cannot rule
	// out release drift, and saying "fresh" here is exactly the false green this check exists to
	// prevent.
	if state == provenanceAbsent {
		// Warning on every unprovenanced binary would penalise the common legitimate case -- a
		// local build -- to guard a case that is now closed for fresh downloads, since
		// EnsureCollector always records provenance. So the warning is narrowed to the situation
		// where the ambiguity can actually bite: the tree carries exporter changes since the most
		// recent release it knows about, and the binary might predate them.
		//
		// A contributor who has not touched the exporter sees nothing. One who has, with a binary
		// of unknown origin, is told the truth: this cannot be ruled out either way.
		if tag, ok := newestLocalReleaseTag(repoRoot); ok {
			if changed, resolved := collectorChangesSince(repoRoot, tag); resolved && changed != "" {
				return true, fmt.Sprintf("collector-builder/ has changed since release %s (%s) and "+
					"this binary's origin is unrecorded, so it cannot be confirmed to contain "+
					"those changes (rebuild it, or delete it and rerun `doctor --fix`)", tag, changed)
			}
		}
	}
	// provenanceStale: the binary was replaced after a recorded download, which is the documented
	// rebuild. The mtime comparison above is then meaningful, and it passed.
	return false, ""
}

func uncommittedCollectorChanges(repoRoot string) string {
	out, err := exec.Command("git", "-C", repoRoot, "status", "--porcelain", "--", "collector-builder").Output()
	if err != nil {
		return ""
	}
	var files []string
	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
		line = strings.TrimSpace(line)
		if line == "" {
			continue
		}
		// dist/ is the build output itself, so changes there are the *result* of rebuilding,
		// never a reason to rebuild. Excluded explicitly rather than relying on the repo's
		// .gitignore: a checkout that does not ignore it would otherwise report the collector
		// binary as a reason the collector is stale, which is circular and always true.
		if strings.Contains(line, "collector-builder/dist") {
			continue
		}
		files = append(files, line)
	}
	return summarize3(files)
}

// provenanceState describes how much the recorded provenance can be trusted.
type provenanceState int

const (
	// provenanceAbsent means no usable marker: never recorded, or recorded before the binary's
	// identity was captured. The binary's origin is unknown.
	provenanceAbsent provenanceState = iota
	// provenanceStale means a marker exists but describes a different binary, so the binary was
	// replaced after it was written -- almost always a local rebuild.
	provenanceStale
	// provenanceTrusted means the marker still describes the binary on disk.
	provenanceTrusted
)

// recordedRelease returns the release a binary was downloaded from, and how much that can be
// trusted.
//
// Collapsing all three states into an empty tag was a false-green generator. When the tag was
// empty, CollectorIsStale skipped release-drift detection entirely and fell back to comparing
// mtimes -- and a downloaded release binary is essentially always newer than local sources, so
// committed exporter changes since that release went unreported and the check went green while the
// run verified the wrong binary. Reported by Cursor Bugbot, and the same shape as the
// unresolvable-tag case: unknowable rendered as clean.
func recordedRelease(repoRoot string) (tag string, state provenanceState) {
	b, err := os.ReadFile(provenancePath(repoRoot))
	if err != nil {
		return "", provenanceAbsent
	}
	fields := map[string]string{}
	for _, line := range strings.Split(string(b), "\n") {
		if k, v, ok := strings.Cut(strings.TrimSpace(line), ":"); ok {
			fields[k] = v
		}
	}
	tag = strings.TrimSpace(fields["release"])
	if tag == "" {
		return "", provenanceAbsent
	}
	fi, err := os.Stat(CollectorPath(repoRoot))
	if err != nil {
		return "", provenanceAbsent
	}
	// A marker written before identity was recorded cannot be validated either way.
	if fields["size"] == "" || fields["mtime"] == "" {
		return tag, provenanceAbsent
	}
	if fields["size"] != strconv.FormatInt(fi.Size(), 10) ||
		fields["mtime"] != strconv.FormatInt(fi.ModTime().UnixNano(), 10) {
		// Replaced after the marker was written, so the marker's release says nothing about what
		// is on disk now. Treated as a local rebuild, which the mtime comparison can judge.
		return tag, provenanceStale
	}
	return tag, provenanceTrusted
}

// collectorChangesSince lists collector-builder/ files that changed between a release tag and HEAD,
// and reports whether the tag could be resolved at all.
//
// The distinction is load-bearing. An unresolvable tag used to return an empty list, which the
// caller read as "no drift" and turned into a confident *fresh* -- skipping the mtime fallback
// entirely. `doctor --fix` can easily record a tag the local clone does not have yet (no
// `git fetch --tags`, or a release newer than the checkout), so with exporter changes present the
// freshness check reported green and a run verified the wrong beacon-otelcol. That is precisely the
// false pass this check exists to prevent. Reported by Cursor Bugbot.
func collectorChangesSince(repoRoot, tag string) (changed string, resolved bool) {
	if err := exec.Command("git", "-C", repoRoot, "rev-parse", "--verify", tag+"^{commit}").Run(); err != nil {
		return "", false
	}
	out, err := exec.Command("git", "-C", repoRoot, "diff", "--name-only", tag+"..HEAD", "--", "collector-builder").Output()
	if err != nil {
		return "", false
	}
	var files []string
	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
		line = strings.TrimSpace(line)
		// Same reasoning as the uncommitted signal: dist/ is the build output, so listing it
		// would report the collector binary as a reason the collector is stale.
		if line == "" || strings.Contains(line, "collector-builder/dist") {
			continue
		}
		files = append(files, line)
	}
	return summarize3(files), true
}

// sourcesNewerThan lists collector-builder Go/config files modified after the binary was built.
func sourcesNewerThan(repoRoot string, built time.Time) string {
	var newer []string
	root := filepath.Join(repoRoot, "collector-builder")
	_ = filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
		if err != nil || d.IsDir() {
			// dist/ holds the build output itself, so walking it would compare the binary
			// against its own siblings and report churn that means nothing.
			if err == nil && d != nil && d.IsDir() && d.Name() == "dist" {
				return filepath.SkipDir
			}
			return nil
		}
		switch filepath.Ext(p) {
		case ".go", ".yaml", ".yml", ".mod", ".sum":
		default:
			return nil
		}
		if fi, err := d.Info(); err == nil && fi.ModTime().After(built) {
			rel, _ := filepath.Rel(repoRoot, p)
			newer = append(newer, rel)
		}
		return nil
	})
	sort.Strings(newer)
	return summarize3(newer)
}

func summarize3(files []string) string {
	if len(files) == 0 {
		return ""
	}
	if len(files) > 3 {
		files = append(files[:3:3], fmt.Sprintf("… and %d more", len(files)-3))
	}
	return strings.Join(files, "; ")
}

func latestLinuxTarball() (rel releaseAsset, err error) {
	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Get(releaseAPI)
	if err != nil {
		return releaseAsset{}, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return releaseAsset{}, fmt.Errorf("release API returned %s", resp.Status)
	}
	var body struct {
		TagName string `json:"tag_name"`
		Assets  []struct {
			Name string `json:"name"`
			URL  string `json:"browser_download_url"`
		} `json:"assets"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
		return releaseAsset{}, err
	}
	out := releaseAsset{Version: body.TagName}
	for _, a := range body.Assets {
		switch {
		case strings.HasSuffix(a.Name, "_linux_amd64.tar.gz"):
			out.Name, out.URL = a.Name, a.URL
		case a.Name == "checksums.txt":
			out.ChecksumsURL = a.URL
		}
	}
	if out.URL == "" {
		return releaseAsset{}, fmt.Errorf("no linux_amd64 tarball in release %s", body.TagName)
	}
	// Refusing rather than proceeding unverified: this binary gets executed inside the sandbox,
	// so an unauthenticated download is a supply-chain hole, not a convenience.
	if out.ChecksumsURL == "" {
		return releaseAsset{}, fmt.Errorf("release %s publishes no checksums.txt, so the "+
			"collector download cannot be verified; build it locally instead", body.TagName)
	}
	return out, nil
}

// releaseAsset is the tarball to fetch plus the means to verify it.
type releaseAsset struct {
	Version      string
	Name         string
	URL          string
	ChecksumsURL string
}

// expectedSHA256 pulls one file's digest out of a GoReleaser checksums.txt ("<hex>  <name>").
func expectedSHA256(client *http.Client, checksumsURL, name string) (string, error) {
	resp, err := client.Get(checksumsURL)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("checksums.txt returned %s", resp.Status)
	}
	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
	if err != nil {
		return "", err
	}
	for _, line := range strings.Split(string(body), "\n") {
		f := strings.Fields(line)
		if len(f) == 2 && f[1] == name {
			return strings.ToLower(f[0]), nil
		}
	}
	return "", fmt.Errorf("checksums.txt has no entry for %s", name)
}

// downloadCollector fetches the release tarball, verifies its SHA-256 against the release's own
// checksums.txt, and only then extracts beacon-otelcol.
//
// Verification is not optional even for contributor tooling: this binary is executed inside the
// sandbox, so accepting whatever the network returned would make a compromised proxy or mirror
// enough to run arbitrary code. The tarball is buffered to a temp file rather than streamed,
// because a digest cannot be checked until the whole body has been read and extracting first
// would defeat the point. Reported by the Copilot reviewer.
func downloadCollector(rel releaseAsset, dst string, log func(string, ...any)) error {
	client := &http.Client{Timeout: 10 * time.Minute}
	want, err := expectedSHA256(client, rel.ChecksumsURL, rel.Name)
	if err != nil {
		return fmt.Errorf("resolve expected checksum: %w", err)
	}
	resp, err := client.Get(rel.URL)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("download returned %s", resp.Status)
	}
	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
		return err
	}

	// Buffer the tarball and hash it as it lands, so the digest can be checked before anything
	// is extracted from it.
	tarball, err := os.CreateTemp(filepath.Dir(dst), "beacon-otelcol-*.tar.gz")
	if err != nil {
		return err
	}
	defer os.Remove(tarball.Name())
	sum := sha256.New()
	if _, err := io.Copy(io.MultiWriter(tarball, sum), resp.Body); err != nil {
		tarball.Close()
		return err
	}
	if err := tarball.Close(); err != nil {
		return err
	}
	got := hex.EncodeToString(sum.Sum(nil))
	if got != want {
		return fmt.Errorf("checksum mismatch for %s: release checksums.txt says %s, downloaded "+
			"bytes hash to %s; refusing to use it", rel.Name, want, got)
	}
	log("verified %s against release checksums.txt (sha256 %s…)", rel.Name, got[:12])

	verified, err := os.Open(tarball.Name())
	if err != nil {
		return err
	}
	defer verified.Close()
	gz, err := gzip.NewReader(verified)
	if err != nil {
		return err
	}
	defer gz.Close()
	tr := tar.NewReader(gz)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			return fmt.Errorf("beacon-otelcol not found in the tarball")
		}
		if err != nil {
			return err
		}
		if filepath.Base(hdr.Name) != "beacon-otelcol" || hdr.Typeflag != tar.TypeReg {
			continue
		}
		// Write to a temp file and rename, so an interrupted download never leaves a
		// truncated binary that would fail confusingly inside the sandbox.
		tmp := dst + ".partial"
		f, err := os.OpenFile(tmp, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o755)
		if err != nil {
			return err
		}
		if _, err := io.Copy(f, tr); err != nil {
			// Report both: a close failure here can itself indicate why the copy failed
			// (a full disk surfaces on either call depending on buffering).
			closeErr := f.Close()
			os.Remove(tmp)
			if closeErr != nil {
				return fmt.Errorf("%w (and closing %s failed: %v)", err, tmp, closeErr)
			}
			return err
		}
		if err := f.Close(); err != nil {
			os.Remove(tmp)
			return err
		}
		return os.Rename(tmp, dst)
	}
}

// newestLocalReleaseTag returns the most recent v* tag reachable from HEAD.
//
// Used as a conservative reference point when a binary's origin is unrecorded: if the exporter has
// not changed since the last release this clone knows about, then a binary of unknown origin cannot
// be carrying stale exporter code, whatever its provenance. That keeps the unprovenanced warning
// off the common local-build path while still catching the case that matters.
func newestLocalReleaseTag(repoRoot string) (string, bool) {
	out, err := exec.Command("git", "-C", repoRoot, "describe", "--tags", "--abbrev=0", "--match", "v*").Output()
	if err != nil {
		return "", false
	}
	tag := strings.TrimSpace(string(out))
	return tag, tag != ""
}