Skip to content

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

Add Pi runtime identity and discovery

Claude79381ff585ee
diff --git a/cli/beacon/internal/endpoint/harness/harness.go b/cli/beacon/internal/endpoint/harness/harness.go
index 9edccce5..51566b28 100644
--- a/cli/beacon/internal/endpoint/harness/harness.go
+++ b/cli/beacon/internal/endpoint/harness/harness.go
@@ -55,6 +55,7 @@ func DiscoverAll() []Harness {
DiscoverAntigravity(),
DiscoverCopilotCLI(),
DiscoverOpenCode(),
+ DiscoverPi(),
DiscoverHermes(),
DiscoverFactory(),
DiscoverVSCode(),
diff --git a/cli/beacon/internal/endpoint/harness/pi.go b/cli/beacon/internal/endpoint/harness/pi.go
new file mode 100644
index 00000000..3c5bff22
--- /dev/null
+++ b/cli/beacon/internal/endpoint/harness/pi.go
@@ -0,0 +1,66 @@
+package harness
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+)
+
+// DiscoverPi reports whether Pi (pi.dev) is present and whether Beacon is observing it.
+//
+// Pi's capability is "plugin" rather than "hooks" or "otel_env" because it has neither surface:
+// there is no hooks configuration file to merge into and no OpenTelemetry support to point at the
+// local collector. Its documented observation surface is the TypeScript extension API, so what
+// Beacon installs is one extension file, and what this function reports is the state of that file.
+func DiscoverPi() Harness {
+ h := Harness{Name: "pi_cli", DisplayName: "Pi", Capability: "plugin"}
+ detectExecutable(&h, "pi")
+
+ home, _ := os.UserHomeDir()
+ agentDir := filepath.Join(home, ".pi", "agent")
+
+ // A missing home directory leaves the config path empty rather than resolving to a relative
+ // path like ".pi/agent/extensions/beacon.ts", which would make discovery report on whatever
+ // happens to sit under the current working directory.
+ extensionPath, err := hooks.PiExtensionPath(hooks.LevelUser)
+ if err != nil {
+ h.TelemetryStatus = TelemetryMissing
+ h.Message = "Pi extension directory could not be resolved: " + err.Error()
+ return h
+ }
+ h.ConfigPath = extensionPath
+
+ // Pi installed through npm/pnpm/bun may not be on the PATH this process inherited -- a shell
+ // alias, a version manager, or a per-project install all hide it -- while its state directory
+ // is still there. Treating that directory as evidence keeps `endpoint discover` from reporting
+ // "not detected" for a runtime the user is actively using, which is the same fallback the
+ // opencode, Cursor and Hermes probes make for the same reason.
+ if !h.Detected && dirExists(agentDir) {
+ h.Detected = true
+ }
+
+ h.TelemetryStatus, h.Message = piStatus(extensionPath)
+ return h
+}
+
+// piStatus classifies the extension file at path.
+//
+// The middle case is the one worth spelling out: a beacon.ts that exists without Beacon's marker is
+// somebody else's extension sharing the filename, so it is reported as disabled rather than
+// enabled. Reporting it as enabled would claim telemetry Beacon is not collecting, and install
+// refuses to overwrite the same file for the same reason.
+func piStatus(path string) (TelemetryStatus, string) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return TelemetryMissing, "Beacon Pi extension was not found"
+ }
+ return TelemetryMissing, err.Error()
+ }
+ if !strings.Contains(string(data), hooks.PiManagedExtensionMarker) {
+ return TelemetryDisabled, "Pi extension file exists but Beacon endpoint extension was not found"
+ }
+ return TelemetryEnabled, "Beacon Pi extension is configured"
+}
diff --git a/cli/beacon/internal/endpoint/harness/pi_test.go b/cli/beacon/internal/endpoint/harness/pi_test.go
new file mode 100644
index 00000000..7866c40f
--- /dev/null
+++ b/cli/beacon/internal/endpoint/harness/pi_test.go
@@ -0,0 +1,170 @@
+package harness
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/hooks"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// writePiExtension creates a user-level Pi extension file with the given contents.
+func writePiExtension(t *testing.T, home, contents string) string {
+ t.Helper()
+ path := filepath.Join(home, ".pi", "agent", "extensions", "beacon.ts")
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ t.Fatalf("mkdir pi extensions dir: %v", err)
+ }
+ if err := os.WriteFile(path, []byte(contents), 0644); err != nil {
+ t.Fatalf("write pi extension: %v", err)
+ }
+ return path
+}
+
+// Every Pi discovery test empties PATH. Without that, the result depends on whether the machine
+// running the suite happens to have a `pi` command installed, which is exactly the kind of
+// environment-dependent assertion the repo's deterministic-test rule exists to prevent.
+func setupPiDiscovery(t *testing.T) string {
+ t.Helper()
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ t.Setenv("PATH", t.TempDir())
+ return home
+}
+
+func TestDiscoverPiReportsMissingExtension(t *testing.T) {
+ home := setupPiDiscovery(t)
+
+ h := DiscoverPi()
+ if h.Detected {
+ t.Fatalf("DiscoverPi detected Pi with no executable and no state directory: %#v", h)
+ }
+ want := filepath.Join(home, ".pi", "agent", "extensions", "beacon.ts")
+ if h.ConfigPath != want {
+ t.Fatalf("ConfigPath = %q, want %q", h.ConfigPath, want)
+ }
+ if h.TelemetryStatus != TelemetryMissing {
+ t.Fatalf("TelemetryStatus = %q, want %q", h.TelemetryStatus, TelemetryMissing)
+ }
+ if h.Capability != "plugin" {
+ t.Fatalf("Capability = %q, want %q -- Pi has no hooks file and no OTel support, so the "+
+ "integration is extension-shaped", h.Capability, "plugin")
+ }
+}
+
+// Pi installed through a version manager or a per-project npm install is not on the PATH this
+// process inherited, so the state directory has to count as evidence. The alternative is reporting
+// "not detected" for a runtime the user is actively running, which reads as "Beacon cannot see
+// this" when the truth is "Beacon has not been installed into it yet".
+func TestDiscoverPiDetectsStateDirectoryWithoutExecutable(t *testing.T) {
+ home := setupPiDiscovery(t)
+ if err := os.MkdirAll(filepath.Join(home, ".pi", "agent"), 0755); err != nil {
+ t.Fatalf("mkdir pi agent dir: %v", err)
+ }
+
+ h := DiscoverPi()
+ if !h.Detected {
+ t.Fatalf("DiscoverPi did not detect Pi from its state directory: %#v", h)
+ }
+ if h.TelemetryStatus != TelemetryMissing {
+ t.Fatalf("TelemetryStatus = %q, want %q; a detected runtime with no extension is not "+
+ "instrumented", h.TelemetryStatus, TelemetryMissing)
+ }
+}
+
+func TestDiscoverPiDetectsExecutableOnPath(t *testing.T) {
+ testenv.RequirePOSIXExecutableFixtures(t)
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ binDir := t.TempDir()
+ t.Setenv("PATH", binDir)
+ piPath := filepath.Join(binDir, "pi")
+ if err := os.WriteFile(piPath, []byte("#!/bin/sh\necho pi 0.4.1\n"), 0755); err != nil {
+ t.Fatalf("write fake pi executable: %v", err)
+ }
+
+ h := DiscoverPi()
+ if !h.Detected {
+ t.Fatalf("DiscoverPi did not detect executable on PATH: %#v", h)
+ }
+ if h.ExecutablePath != piPath {
+ t.Fatalf("ExecutablePath = %q, want %q", h.ExecutablePath, piPath)
+ }
+ if h.Version != "pi 0.4.1" {
+ t.Fatalf("Version = %q, want fake executable version", h.Version)
+ }
+}
+
+func TestDiscoverPiReportsEnabledForManagedExtension(t *testing.T) {
+ home := setupPiDiscovery(t)
+ writePiExtension(t, home, "// "+hooks.PiManagedExtensionMarker+"\nexport default () => {}\n")
+
+ h := DiscoverPi()
+ if h.TelemetryStatus != TelemetryEnabled {
+ t.Fatalf("TelemetryStatus = %q, want %q; message=%q", h.TelemetryStatus, TelemetryEnabled, h.Message)
+ }
+ if !h.Detected {
+ t.Fatalf("DiscoverPi did not detect Pi despite a managed extension being installed: %#v", h)
+ }
+}
+
+// A beacon.ts that Beacon did not write is somebody else's extension sharing the filename.
+// Reporting it as enabled would claim telemetry that is not being collected -- the failure mode
+// where a dashboard shows a runtime as covered and no events ever arrive.
+func TestDiscoverPiReportsDisabledForUnmanagedExtension(t *testing.T) {
+ home := setupPiDiscovery(t)
+ writePiExtension(t, home, "export default function (pi) { /* not Beacon's */ }\n")
+
+ h := DiscoverPi()
+ if h.TelemetryStatus != TelemetryDisabled {
+ t.Fatalf("TelemetryStatus = %q, want %q; message=%q", h.TelemetryStatus, TelemetryDisabled, h.Message)
+ }
+}
+
+// The marker is a version contract with the extension source. A file carrying an older marker must
+// not read as enabled, or a repair would leave a stale extension in place believing it current.
+func TestDiscoverPiReportsDisabledForStaleMarkerVersion(t *testing.T) {
+ home := setupPiDiscovery(t)
+ writePiExtension(t, home, "// beacon-managed-pi-extension:v0\nexport default () => {}\n")
+
+ h := DiscoverPi()
+ if h.TelemetryStatus != TelemetryDisabled {
+ t.Fatalf("TelemetryStatus = %q, want %q for a superseded marker version; message=%q",
+ h.TelemetryStatus, TelemetryDisabled, h.Message)
+ }
+}
+
+// Discovery has to be registered to be reachable: DiscoverPi existing but missing from DiscoverAll
+// is invisible in `endpoint discover`, `endpoint status`, and the agent.detected events they write.
+func TestDiscoverAllIncludesPi(t *testing.T) {
+ setupPiDiscovery(t)
+
+ for _, h := range DiscoverAll() {
+ if h.Name == "pi_cli" {
+ return
+ }
+ }
+ t.Fatal("DiscoverAll() does not include pi_cli")
+}
+
+// The canonical harness name is what events are grouped by, so discovery must report the same
+// spelling the normalizer produces. Reporting "pi" here while the hook path writes "pi_cli" would
+// split one runtime across two names in every query and dashboard that groups on it -- the same
+// defect that once recorded a single Claude Code session as both "claude" and "claude_code".
+//
+// Asserted against the normalizer rather than against a literal so the two cannot drift apart in
+// one direction only.
+func TestDiscoverPiUsesCanonicalHarnessName(t *testing.T) {
+ setupPiDiscovery(t)
+
+ name := DiscoverPi().Name
+ if name != "pi_cli" {
+ t.Fatalf("DiscoverPi().Name = %q, want %q", name, "pi_cli")
+ }
+ if got := asymptoteobserve.NormalizeHarnessName(name); got != name {
+ t.Fatalf("NormalizeHarnessName(%q) = %q; discovery must report the canonical name so the "+
+ "hook and OTLP paths agree", name, got)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/hooks/pi.go b/cli/beacon/internal/endpoint/hooks/pi.go
new file mode 100644
index 00000000..72d5dffc
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/pi.go
@@ -0,0 +1,63 @@
+package hooks
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+)
+
+// Pi (pi.dev) has no hooks configuration file and no OpenTelemetry support, so neither of Beacon's
+// two established integration shapes applies to it. Its only observation surface is the TypeScript
+// extension API, which makes the integration plugin-shaped: Beacon writes one extension file that
+// forwards runtime events to the `beacon-hooks` binary. That is the same shape as the opencode
+// plugin, and the pieces below are the facts about that file which more than one package needs.
+const (
+ piExtensionFileName = "beacon.ts"
+
+ // PiManagedExtensionMarker identifies an extension file as one Beacon wrote.
+ //
+ // Exported because three packages need the same answer and must not disagree: `hooks` writes
+ // the marker and refuses to overwrite a file without it, `harness` reads it to report telemetry
+ // status, and `inventory` reads it to decide whether a file it found is Beacon-managed. The
+ // existing opencode and grok markers are spelled out as literals in each of those places
+ // instead; a marker that drifts between writer and reader turns install into a no-op that
+ // reports success, so this one has a single definition.
+ //
+ // The version suffix is part of the contract with the extension source, not decoration. Bump it
+ // when the extension's behavior changes in a way that makes an older installed copy wrong,
+ // which is what lets a repair recognize a stale file rather than leave it in place.
+ PiManagedExtensionMarker = "beacon-managed-pi-extension:v1"
+)
+
+// PiExtensionPath returns the extension file Beacon manages for a given install level.
+//
+// Pi loads extensions from two documented locations, and the distinction matters beyond the path:
+// a project-level extension is subject to Pi's project-trust prompt, so a user-level install is the
+// one that works without further interaction. Callers that only report status still need both
+// spellings, because a file found at either location is a Beacon install.
+func PiExtensionPath(level Level) (string, error) {
+ dir, err := piExtensionDir(level)
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(dir, piExtensionFileName), nil
+}
+
+func piExtensionDir(level Level) (string, error) {
+ switch level {
+ case "", LevelUser:
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(home, ".pi", "agent", "extensions"), nil
+ case LevelProject:
+ cwd, err := os.Getwd()
+ if err != nil {
+ return "", err
+ }
+ return filepath.Join(cwd, ".pi", "extensions"), nil
+ default:
+ return "", fmt.Errorf("unknown hook level %q", level)
+ }
+}
diff --git a/cli/beacon/internal/endpoint/hooks/pi_test.go b/cli/beacon/internal/endpoint/hooks/pi_test.go
new file mode 100644
index 00000000..73f9729f
--- /dev/null
+++ b/cli/beacon/internal/endpoint/hooks/pi_test.go
@@ -0,0 +1,62 @@
+package hooks
+
+import (
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// An empty level means "the default", and the default has to be the user level. Every caller that
+// does not care about scope passes the zero value, so treating "" as unknown would turn status,
+// repair and uninstall into errors for the ordinary install.
+func TestPiExtensionPathDefaultsToUserLevel(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+
+ want := filepath.Join(home, ".pi", "agent", "extensions", "beacon.ts")
+ for _, level := range []Level{"", LevelUser} {
+ got, err := PiExtensionPath(level)
+ if err != nil {
+ t.Fatalf("PiExtensionPath(%q) returned error: %v", level, err)
+ }
+ if got != want {
+ t.Fatalf("PiExtensionPath(%q) = %q, want %q", level, got, want)
+ }
+ }
+}
+
+// Pi's project-level extension directory is `.pi/extensions`, not `.pi/agent/extensions`: the
+// `agent` segment exists only under the home directory. Deriving one path from the other would
+// write the project extension where Pi does not look for it, so the install would report success
+// and collect nothing.
+func TestPiExtensionPathProjectLevelOmitsAgentSegment(t *testing.T) {
+ cwd := t.TempDir()
+ t.Chdir(cwd)
+
+ got, err := PiExtensionPath(LevelProject)
+ if err != nil {
+ t.Fatalf("PiExtensionPath(project) returned error: %v", err)
+ }
+ want := filepath.Join(cwd, ".pi", "extensions", "beacon.ts")
+ if got != want {
+ t.Fatalf("PiExtensionPath(project) = %q, want %q", got, want)
+ }
+}
+
+func TestPiExtensionPathRejectsUnknownLevel(t *testing.T) {
+ if _, err := PiExtensionPath(Level("machine")); err == nil {
+ t.Fatal("PiExtensionPath accepted an unknown level; a typo in a scope flag must fail loudly " +
+ "rather than silently installing at the default scope")
+ }
+}
+
+// The marker is the only thing that distinguishes a file Beacon may overwrite from one it must
+// not, and it is read by two other packages. Pinning the literal here means a change to it is a
+// deliberate edit to a test rather than a silent break of install/uninstall/status agreement.
+func TestPiManagedExtensionMarkerIsStable(t *testing.T) {
+ if PiManagedExtensionMarker != "beacon-managed-pi-extension:v1" {
+ t.Fatalf("PiManagedExtensionMarker = %q; changing it strands extensions installed by "+
+ "earlier builds, which uninstall then refuses to remove", PiManagedExtensionMarker)
+ }
+}
diff --git a/pkg/asymptoteobserve/harness.go b/pkg/asymptoteobserve/harness.go
index 2eb59d00..2df894d5 100644
--- a/pkg/asymptoteobserve/harness.go
+++ b/pkg/asymptoteobserve/harness.go
@@ -58,6 +58,19 @@ func NormalizeHarnessName(name string) string {
return "vscode_copilot"
case strings.Contains(lower, "github-copilot") || strings.Contains(lower, "copilot_cli") || strings.Contains(lower, "copilot"):
return "copilot_cli"
+ // Pi is matched by equality against a fixed set of spellings, not by substring, because "pi" is
+ // two characters and appears inside names that belong to other runtimes: "copilot" contains it,
+ // so a Contains rule here would report every GitHub Copilot and VS Code Copilot session as Pi.
+ // The set is closed for the same reason -- a prefix rule would claim any future runtime whose
+ // name happens to start with those two letters.
+ //
+ // Its position after the Copilot rules is also deliberate. Equality makes this case
+ // order-independent today, but if it is ever loosened to a substring match, sitting below the
+ // broader rules means Copilot still resolves correctly and only genuine Pi names reach here.
+ // The reverse ordering would turn that same edit into silent misattribution.
+ case lower == "pi" || lower == "pi.dev" || lower == "pi_cli" || lower == "pi-cli" ||
+ lower == "pi_agent" || lower == "pi-agent" || lower == "pi agent":
+ return "pi_cli"
case name != "":
// An unrecognized runtime keeps its own name rather than being coerced or dropped. A new
// harness should show up in the log as itself, not as "unknown".
diff --git a/pkg/asymptoteobserve/harness_test.go b/pkg/asymptoteobserve/harness_test.go
index 2b5f6134..f6881e81 100644
--- a/pkg/asymptoteobserve/harness_test.go
+++ b/pkg/asymptoteobserve/harness_test.go
@@ -16,6 +16,7 @@ func TestHookPlatformsConvergeOnCanonicalNames(t *testing.T) {
"gemini": "gemini_cli",
"antigravity": "antigravity_cli",
"vscode": "vscode_copilot",
+ "pi": "pi_cli",
} {
t.Run(platform, func(t *testing.T) {
if got := NormalizeHarnessName(platform); got != want {
@@ -34,7 +35,7 @@ func TestCanonicalNamesAreStableUnderRenormalization(t *testing.T) {
for _, canonical := range []string{
"claude_code", "codex_cli", "gemini_cli", "antigravity_cli", "vscode_copilot",
"copilot_cli", "claude_web", "chatgpt_web", "claude_cowork", "claude_agent_sdk",
- "openclaw_gateway",
+ "openclaw_gateway", "pi_cli",
} {
t.Run(canonical, func(t *testing.T) {
if got := NormalizeHarnessName(canonical); got != canonical {
@@ -65,6 +66,51 @@ func TestNarrowerRuntimesWinOverBroaderRules(t *testing.T) {
}
}
+// Pi's canonical name is reachable from the spellings the two write paths actually produce: the
+// hook path installs with --platform pi, and the OTLP path would read a service.name.
+func TestPiSpellingsConvergeOnPiCLI(t *testing.T) {
+ for _, in := range []string{
+ "pi", "PI", " pi ", "pi.dev", "pi_cli", "pi-cli", "pi_agent", "pi-agent", "pi agent",
+ } {
+ t.Run(in, func(t *testing.T) {
+ if got := NormalizeHarnessName(in); got != "pi_cli" {
+ t.Errorf("NormalizeHarnessName(%q) = %q, want %q", in, got, "pi_cli")
+ }
+ })
+ }
+}
+
+// "pi" is a two-character name that appears inside other runtimes' names, so matching it by
+// substring would attribute their sessions to Pi. "copilot" contains "pi" -- every Copilot and VS
+// Code Copilot session is the concrete blast radius of getting this wrong, and both are runtimes
+// Beacon already supports. This test is what keeps the Pi case an equality match.
+func TestPiDoesNotSwallowNamesContainingPi(t *testing.T) {
+ for input, want := range map[string]string{
+ "copilot": "copilot_cli",
+ "github-copilot": "copilot_cli",
+ "copilot_cli": "copilot_cli",
+ "copilot-chat": "vscode_copilot",
+ "vscode_copilot": "vscode_copilot",
+ } {
+ t.Run(input, func(t *testing.T) {
+ if got := NormalizeHarnessName(input); got != want {
+ t.Errorf("NormalizeHarnessName(%q) = %q, want %q -- a substring rule for Pi would "+
+ "reassign this runtime's sessions to pi_cli", input, got, want)
+ }
+ })
+ }
+}
+
+// The Pi spelling set is closed, not a prefix rule. A future runtime whose name merely starts with
+// "pi" must keep its own name rather than being recorded as Pi activity.
+func TestNamesMerelyStartingWithPiAreNotPi(t *testing.T) {
+ for _, name := range []string{"pip-agent", "pipeline", "pixel-cli", "pied-piper"} {
+ if got := NormalizeHarnessName(name); got != name {
+ t.Errorf("NormalizeHarnessName(%q) = %q, want it preserved", name, got)
+ }
+ }
+}
+
// An unrecognized runtime keeps its own name. Coercing it to "unknown" would erase the one clue
// available when a new harness starts reporting, and these names reach customer dashboards.
func TestUnknownRuntimesKeepTheirName(t *testing.T) {