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
handoff: add Pi and Prime Agent
Claudebee2e1df7ba1
diff --git a/cli/beacon/internal/handoff/claude.go b/cli/beacon/internal/handoff/claude.goindex 0d1c395e..920af6e7 100644--- a/cli/beacon/internal/handoff/claude.go+++ b/cli/beacon/internal/handoff/claude.go@@ -9,7 +9,7 @@ import ("strings")-// Bounds for reading the head of a Claude transcript while listing. A listing opens every+// Bounds for reading the head of a transcript while listing. A listing opens every// transcript, so it reads only enough to find where the session ran and what it was about.const (claudeHeadMaxLines = 64@@ -28,27 +28,33 @@ type claudeHead struct {// a dash, which cannot be decoded back when the path itself contains one, so a session without an// index entry needs the cwd its transcript records.func readClaudeHead(path string) claudeHead {+ var head claudeHead+ scanHead(path, func(line []byte) bool {+ head.consume(line)+ return head.CWD != "" && head.GitBranch != "" && head.FirstPrompt != ""+ })+ return head+}++// scanHead passes the first lines of a JSONL transcript to consume until it returns true, within+// the listing bounds above. A listing opens every transcript, so it reads only its head.+func scanHead(path string, consume func(line []byte) (done bool)) {f, err := os.Open(path)if err != nil {- return claudeHead{}+ return}defer f.Close()- var head claudeHeadreader := bufio.NewReaderSize(io.LimitReader(f, claudeHeadMaxBytes), 64<<10)for lines := 0; lines < claudeHeadMaxLines; lines++ {line, err := readBoundedLine(reader, claudeHeadMaxLineSize)- if len(line) > 0 {- head.consume(line)- }- if head.CWD != "" && head.GitBranch != "" && head.FirstPrompt != "" {- break+ if len(line) > 0 && consume(line) {+ return}if err != nil {- break+ return}}- return head}func (h *claudeHead) consume(line []byte) {diff --git a/cli/beacon/internal/handoff/fixtures_test.go b/cli/beacon/internal/handoff/fixtures_test.goindex ab743558..e9c90e3f 100644--- a/cli/beacon/internal/handoff/fixtures_test.go+++ b/cli/beacon/internal/handoff/fixtures_test.go@@ -20,6 +20,15 @@ var (claudeUpdated = time.Date(2026, 9, 23, 9, 0, 0, 0, time.UTC))+// isolateRuntimeEnv clears the environment variables that move a runtime's default store, so a+// runtime the fixture leaves at its default reads only the test's HOME.+func isolateRuntimeEnv(t *testing.T) {+ t.Helper()+ for _, name := range []string{"PI_CODING_AGENT_DIR", "PRIME_AGENT_CODING_AGENT_DIR"} {+ t.Setenv(name, "")+ }+}+// storeFixture lays down one session store per supported runtime, in the formats each runtime// writes, under a temporary directory.type storeFixture struct {diff --git a/cli/beacon/internal/handoff/pi.go b/cli/beacon/internal/handoff/pi.gonew file mode 100644index 00000000..4c05b4f5--- /dev/null+++ b/cli/beacon/internal/handoff/pi.go@@ -0,0 +1,205 @@+package handoff++import (+ "encoding/json"+ "path/filepath"+ "strings"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pisession"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/primesession"+)++// Pi and Prime Agent keep one JSONL transcript per session, opened by a header line that names the+// session, where it ran and its git branch. Prime Agent is a Pi fork with the same transcript+// format and a second root for subagent transcripts.++type piSource struct{ dir string }++func (s *piSource) Harness() string { return HarnessPi }++// store reads dir as Pi's sessions directory, as `beacon endpoint pi sync --sessions-dir` does.+func (s *piSource) store() (*pisession.Store, error) { return pisession.NewStore(s.dir) }++func (s *piSource) List() ([]Session, error) {+ store, err := s.store()+ if err != nil {+ return nil, err+ }+ if !store.Exists() {+ return nil, nil+ }+ refs, err := store.List()+ if err != nil {+ return nil, err+ }+ sessions := make([]Session, 0, len(refs))+ for _, ref := range refs {+ sessions = append(sessions, Session{+ Harness: HarnessPi,+ ID: ref.ID,+ Title: oneLine(readPiFirstPrompt(ref.Path)),+ Directory: ref.Workspace,+ Branch: piHeaderBranch(ref.Header),+ SourcePath: ref.Path,+ UpdatedAt: unixMS(ref.ModTimeMS),+ })+ }+ return sessions, nil+}++func (s *piSource) Events(session Session) ([]schema.Event, error) {+ store, err := s.store()+ if err != nil {+ return nil, err+ }+ refs, err := store.List()+ if err != nil {+ return nil, err+ }+ for _, ref := range refs {+ if ref.ID != session.ID || ref.Path != session.SourcePath {+ continue+ }+ entries, _, err := store.Read(ref)+ if err != nil {+ return nil, err+ }+ mapped := pisession.MapSession(ref, entries, pisession.MapOptions{})+ events := make([]schema.Event, 0, len(mapped))+ for _, m := range mapped {+ events = append(events, m.Event)+ }+ return events, nil+ }+ return nil, errSessionGone(session)+}++type primeSource struct{ dir string }++func (s *primeSource) Harness() string { return HarnessPrime }++// store reads dir as Prime Agent's agent directory, which holds both of its session roots. Empty+// means the default, honouring PRIME_AGENT_CODING_AGENT_DIR as `beacon endpoint prime sync` does.+func (s *primeSource) store() (*primesession.Store, error) {+ if s.dir == "" {+ return primesession.NewStore("", "")+ }+ return primesession.NewStore(filepath.Join(s.dir, "sessions"), filepath.Join(s.dir, "session-artifacts"))+}++func (s *primeSource) List() ([]Session, error) {+ store, err := s.store()+ if err != nil {+ return nil, err+ }+ if !store.Exists() {+ return nil, nil+ }+ refs, err := store.List()+ if err != nil {+ return nil, err+ }+ sessions := make([]Session, 0, len(refs))+ for _, ref := range refs {+ parent := piHeaderString(ref.Header, "parentSession")+ sessions = append(sessions, Session{+ Harness: HarnessPrime,+ ID: ref.ID,+ Title: oneLine(readPiFirstPrompt(ref.Path)),+ Directory: piHeaderString(ref.Header, "cwd"),+ Branch: piHeaderBranch(ref.Header),+ SourcePath: ref.Path,+ Store: ref.Kind,+ UpdatedAt: unixMS(ref.ModTimeMS),+ // Subagent transcripts live under session-artifacts and name the session that spawned them.+ Subagent: ref.Kind == primeArtifactKind || parent != "",+ ParentID: parent,+ })+ }+ return sessions, nil+}++const primeArtifactKind = "artifact"++func (s *primeSource) Events(session Session) ([]schema.Event, error) {+ store, err := s.store()+ if err != nil {+ return nil, err+ }+ refs, err := store.List()+ if err != nil {+ return nil, err+ }+ for _, ref := range refs {+ if ref.ID != session.ID || ref.Path != session.SourcePath {+ continue+ }+ entries, _, err := store.Read(ref)+ if err != nil {+ return nil, err+ }+ mapped := primesession.MapSession(ref, entries, primesession.MapOptions{+ SubagentOf: piHeaderString(ref.Header, "parentSession"),+ })+ events := make([]schema.Event, 0, len(mapped))+ for _, m := range mapped {+ events = append(events, m.Event)+ }+ return events, nil+ }+ return nil, errSessionGone(session)+}++func piHeaderString(header map[string]interface{}, key string) string {+ value, _ := header[key].(string)+ return strings.TrimSpace(value)+}++func piHeaderBranch(header map[string]interface{}) string {+ git, _ := header["git"].(map[string]interface{})+ branch, _ := git["branch"].(string)+ return strings.TrimSpace(branch)+}++// readPiFirstPrompt returns the first thing a person typed in a Pi-format transcript.+func readPiFirstPrompt(path string) string {+ var prompt string+ scanHead(path, func(line []byte) bool {+ var entry struct {+ Type string `json:"type"`+ Message struct {+ Role string `json:"role"`+ Content json.RawMessage `json:"content"`+ } `json:"message"`+ }+ if json.Unmarshal(line, &entry) != nil || entry.Type != "message" || entry.Message.Role != "user" {+ return false+ }+ prompt = piContentText(entry.Message.Content)+ return prompt != ""+ })+ return prompt+}++// piContentText is a message's first text: the content itself when it is a string, else its first+// text block. Pi writes blocks with and without a "type".+func piContentText(content json.RawMessage) string {+ var text string+ if json.Unmarshal(content, &text) == nil {+ return strings.TrimSpace(text)+ }+ var blocks []struct {+ Type string `json:"type"`+ Text string `json:"text"`+ }+ if json.Unmarshal(content, &blocks) != nil {+ return ""+ }+ for _, block := range blocks {+ if (block.Type == "" || block.Type == "text") && strings.TrimSpace(block.Text) != "" {+ return strings.TrimSpace(block.Text)+ }+ }+ return ""+}diff --git a/cli/beacon/internal/handoff/pi_test.go b/cli/beacon/internal/handoff/pi_test.gonew file mode 100644index 00000000..7bc93316--- /dev/null+++ b/cli/beacon/internal/handoff/pi_test.go@@ -0,0 +1,180 @@+package handoff++import (+ "errors"+ "path/filepath"+ "reflect"+ "strings"+ "testing"+ "time"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++var (+ piUpdated = time.Date(2026, 9, 24, 9, 0, 0, 0, time.UTC)+ primeUpdated = time.Date(2026, 9, 24, 10, 0, 0, 0, time.UTC)+)++// piFixture lays down a Pi sessions directory and a Prime Agent agent directory, in the layout each+// runtime writes.+func piFixture(t *testing.T) (StoreDirs, string, string) {+ t.Helper()+ testenv.SetHome(t, t.TempDir())+ isolateRuntimeEnv(t)+ root := t.TempDir()+ dirs := StoreDirs{+ HarnessPi: filepath.Join(root, "pi-sessions"),+ HarnessPrime: filepath.Join(root, "prime-agent"),+ }++ piPath := filepath.Join(dirs[HarnessPi], "--work-api--", "2026-09-24T09-00-00_pi-sess-1.jsonl")+ writeFixture(t, piPath,+ jsonLine(t, map[string]interface{}{"type": "session", "id": "pi-sess-1", "cwd": "/work/api", "git": map[string]interface{}{"branch": "feat/pi"}})++ jsonLine(t, map[string]interface{}{"type": "model_change", "modelId": "gpt-5"})++ jsonLine(t, map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "user", "content": []interface{}{map[string]interface{}{"text": " tidy the\nrouter "}},+ }})++ jsonLine(t, map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "assistant", "content": []interface{}{map[string]interface{}{"type": "text", "text": "Done."}},+ }}))+ setModTime(t, piPath, piUpdated)++ primePath := filepath.Join(dirs[HarnessPrime], "sessions", "prime-sess-1.jsonl")+ writeFixture(t, primePath,+ jsonLine(t, map[string]interface{}{"type": "session", "id": "prime-sess-1", "cwd": "/work/web"})++ jsonLine(t, map[string]interface{}{"type": "message", "message": map[string]interface{}{"role": "user", "content": "plot the latency"}}))+ setModTime(t, primePath, primeUpdated)++ artifactPath := filepath.Join(dirs[HarnessPrime], "session-artifacts", "prime-sess-1", "prime-sub-1.jsonl")+ writeFixture(t, artifactPath,+ jsonLine(t, map[string]interface{}{"type": "session", "id": "prime-sub-1", "cwd": "/work/web", "parentSession": "prime-sess-1"})++ jsonLine(t, map[string]interface{}{"type": "message", "message": map[string]interface{}{"role": "user", "content": "read the csv"}}))+ setModTime(t, artifactPath, primeUpdated.Add(time.Minute))+ return dirs, piPath, primePath+}++func TestListReadsPiAndPrimeSessions(t *testing.T) {+ dirs, piPath, primePath := piFixture(t)+ sessions, err := List(DefaultSources(dirs), Filter{IncludeSubagents: true})+ if err != nil {+ t.Fatalf("List: %v", err)+ }+ byKey := map[string]Session{}+ for _, s := range sessions {+ byKey[s.Harness+"/"+s.ID] = s+ }+ pi, ok := byKey["pi_cli/pi-sess-1"]+ if !ok {+ t.Fatalf("sessions = %v, want the Pi session", sessionKeys(sessions))+ }+ want := Session{Harness: HarnessPi, ID: "pi-sess-1", Title: "tidy the router", Directory: "/work/api", Branch: "feat/pi", SourcePath: piPath, UpdatedAt: piUpdated}+ if !reflect.DeepEqual(pi, want) {+ t.Fatalf("pi session = %+v\nwant %+v", pi, want)+ }+ prime := byKey["prime_agent/prime-sess-1"]+ if prime.Title != "plot the latency" || prime.Directory != "/work/web" || prime.SourcePath != primePath || prime.Subagent || !prime.UpdatedAt.Equal(primeUpdated) {+ t.Fatalf("prime session = %+v", prime)+ }+ sub := byKey["prime_agent/prime-sub-1"]+ if !sub.Subagent || sub.ParentID != "prime-sess-1" || sub.Title != "read the csv" {+ t.Fatalf("prime subagent = %+v, want a subagent of prime-sess-1", sub)+ }++ top, err := List(DefaultSources(dirs), Filter{})+ if err != nil {+ t.Fatal(err)+ }+ for _, s := range top {+ if s.Subagent {+ t.Fatalf("subagent %s listed without IncludeSubagents", s.ID)+ }+ }+ if got := strings.Join(sessionKeys(top), ","); got != "prime_agent/prime-sess-1,pi_cli/pi-sess-1" {+ t.Fatalf("top-level sessions = %s, want newest first", got)+ }+}++func TestPiAndPrimeSessionsBuildABrief(t *testing.T) {+ dirs, _, _ := piFixture(t)+ sources := DefaultSources(dirs)+ for _, tc := range []struct {+ harness, id, request string+ }{+ {HarnessPi, "pi-sess", "tidy the"},+ {HarnessPrime, "prime-sess-1", "plot the latency"},+ } {+ t.Run(tc.harness, func(t *testing.T) {+ // A unique prefix finds the session too.+ session, err := Find(sources, tc.harness, tc.id)+ if err != nil {+ t.Fatalf("Find: %v", err)+ }+ events, err := Events(sources, session)+ if err != nil {+ t.Fatalf("Events: %v", err)+ }+ brief := BuildBrief(session, events, FromSessionStore, time.Now())+ if brief.Prompts != 1 || !strings.Contains(brief.FirstRequest, tc.request) {+ t.Fatalf("brief prompts=%d first=%q", brief.Prompts, brief.FirstRequest)+ }+ if !strings.Contains(brief.Render(), RuntimeLabel(tc.harness)) {+ t.Fatalf("the brief should name %s:\n%s", RuntimeLabel(tc.harness), brief.Render())+ }+ })+ }+}++func TestPiSessionGoneFromItsStore(t *testing.T) {+ dirs, piPath, _ := piFixture(t)+ session := Session{Harness: HarnessPi, ID: "pi-sess-1", SourcePath: piPath + ".moved"}+ if _, err := Events(DefaultSources(dirs), session); !errors.Is(err, ErrNotFound) {+ t.Fatalf("Events = %v, want ErrNotFound", err)+ }+}++func TestPlanResumeReopensAPiSessionByItsFile(t *testing.T) {+ session := resumableSession(t, HarnessPi, "pi-1")+ plan, err := PlanResume(session, PlanOptions{LookPath: installed("pi")})+ if err != nil {+ t.Fatalf("PlanResume: %v", err)+ }+ if plan.Mode != ModeNative || plan.Executable != "/bin/pi" || !reflect.DeepEqual(plan.Args, []string{"--session", session.SourcePath}) {+ t.Fatalf("plan = %+v", plan)+ }++ gone := session+ gone.SourcePath = filepath.Join(t.TempDir(), "missing.jsonl")+ brief := filepath.Join(t.TempDir(), "brief.md")+ plan, err = PlanResume(gone, PlanOptions{BriefPath: brief, LookPath: installed("pi")})+ if err != nil {+ t.Fatalf("PlanResume: %v", err)+ }+ // -- keeps a prompt that starts with @ or - from being read as a file or a flag.+ if plan.Mode != ModeNewSession || plan.Reason != ReasonSessionGone || !reflect.DeepEqual(plan.Args, []string{"--", NewSessionPrompt(gone, brief)}) {+ t.Fatalf("plan = %+v", plan)+ }+}++func TestPlanResumeReopensAPrimeSessionByItsFile(t *testing.T) {+ session := resumableSession(t, HarnessPrime, "prime-1")+ plan, err := PlanResume(session, PlanOptions{LookPath: installed("prime-agent")})+ if err != nil {+ t.Fatalf("PlanResume: %v", err)+ }+ if plan.Mode != ModeNative || plan.Executable != "/bin/prime-agent" || !reflect.DeepEqual(plan.Args, []string{"--resume", session.SourcePath}) {+ t.Fatalf("plan = %+v", plan)+ }++ // A subagent transcript continues from a brief, in a new top-level session.+ sub := session+ sub.Subagent, sub.ParentID = true, "prime-0"+ brief := filepath.Join(t.TempDir(), "brief.md")+ plan, err = PlanResume(sub, PlanOptions{BriefPath: brief, LookPath: installed("prime-agent")})+ if err != nil {+ t.Fatalf("PlanResume: %v", err)+ }+ if plan.Mode != ModeNewSession || plan.Reason != ReasonNotResumable || !reflect.DeepEqual(plan.Args, []string{"--", NewSessionPrompt(sub, brief)}) {+ t.Fatalf("plan = %+v", plan)+ }+}diff --git a/cli/beacon/internal/handoff/resume_test.go b/cli/beacon/internal/handoff/resume_test.goindex 17fdbb09..c0d74ca4 100644--- a/cli/beacon/internal/handoff/resume_test.go+++ b/cli/beacon/internal/handoff/resume_test.go@@ -24,7 +24,7 @@ func installed(names ...string) func(string) (string, error) {}}-var allRuntimes = installed("claude", "codex", "opencode", "cline")+var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent")// resumableSession is a session whose directory and session file both exist.func resumableSession(t *testing.T, harness, id string) Session {@@ -78,6 +78,8 @@ func TestPlanResumeStartsANewSessionInEachRuntime(t *testing.T) {{HarnessCodex, "codex", nil},{HarnessOpenCode, "opencode", []string{"--prompt"}},{HarnessCline, "cline", []string{"--tui", "--auto-approve", "false"}},+ {HarnessPi, "pi", []string{"--"}},+ {HarnessPrime, "prime-agent", []string{"--"}},} {t.Run(tc.target, func(t *testing.T) {source := HarnessCodexdiff --git a/cli/beacon/internal/handoff/runtimes.go b/cli/beacon/internal/handoff/runtimes.goindex 46a42f50..ae9f9fbd 100644--- a/cli/beacon/internal/handoff/runtimes.go+++ b/cli/beacon/internal/handoff/runtimes.go@@ -8,6 +8,8 @@ import ("github.com/asymptote-labs/agent-beacon/cli/beacon/internal/clinesession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/codexsession""github.com/asymptote-labs/agent-beacon/cli/beacon/internal/opencodesession"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pisession"+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/primesession""github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve")@@ -46,6 +48,8 @@ const (HarnessCodex = codexsession.HarnessHarnessOpenCode = opencodesession.HarnessHarnessCline = clinesession.Harness+ HarnessPi = pisession.Harness+ HarnessPrime = primesession.Harness)// runtimes lists every runtime handoff supports, in display order.@@ -110,6 +114,38 @@ var runtimes = []Runtime{},},},+ {+ Harness: HarnessPi,+ Label: "Pi",+ Aliases: []string{"pi", "pi-cli"},+ NewSource: func(dir string) Source { return &piSource{dir: dir} },+ Command: &runtimeCommand{+ Executable: "pi",+ // --session takes the transcript's path as well as its id; the path names it exactly,+ // wherever Pi's session directory is.+ Resume: func(s Session) ([]string, bool) { return []string{"--session", s.SourcePath}, true },+ // -- ends Pi's options, so the prompt is never read as one.+ NewSession: func(prompt string) []string { return []string{"--", prompt} },+ },+ },+ {+ Harness: HarnessPrime,+ Label: "Prime Agent",+ Aliases: []string{"prime", "prime-agent"},+ NewSource: func(dir string) Source { return &primeSource{dir: dir} },+ Command: &runtimeCommand{+ Executable: "prime-agent",+ Resume: func(s Session) ([]string, bool) {+ // A subagent transcript belongs to the session that spawned it, not to one the CLI+ // reopens on its own.+ if s.Subagent {+ return nil, false+ }+ return []string{"--resume", s.SourcePath}, true+ },+ NewSession: func(prompt string) []string { return []string{"--", prompt} },+ },+ },}// Harnesses lists the runtimes handoff supports, in display order.diff --git a/cli/beacon/internal/handoff/session_test.go b/cli/beacon/internal/handoff/session_test.goindex 7036bb01..8bc4277b 100644--- a/cli/beacon/internal/handoff/session_test.go+++ b/cli/beacon/internal/handoff/session_test.go@@ -16,6 +16,7 @@ func fixtureSources(t *testing.T) (storeFixture, []Source) {t.Helper()// Cline also reads VS Code's global storage under HOME; keep it inside the test.testenv.SetHome(t, t.TempDir())+ isolateRuntimeEnv(t)f := newStoreFixture(t)return f, DefaultSources(f.dirs)}diff --git a/cli/beacon/internal/pisession/handoff_test.go b/cli/beacon/internal/pisession/handoff_test.gonew file mode 100644index 00000000..c3242ea9--- /dev/null+++ b/cli/beacon/internal/pisession/handoff_test.go@@ -0,0 +1,57 @@+package pisession++import (+ "testing"++ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+)++func TestMapSessionRecordsAHandoffLink(t *testing.T) {+ ref := SessionRef{ID: "new-1", Path: "/tmp/new-1.jsonl", Header: map[string]interface{}{"type": "session", "id": "new-1", "cwd": "/work"}}+ prompt := "Continue the work.\n\n" + asymptoteobserve.HandoffMarker("claude_code", "src-1")+ entries := []Entry{+ {Line: 1, Data: ref.Header},+ {Line: 2, Data: map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "user", "content": []interface{}{map[string]interface{}{"text": "an unrelated block"}, map[string]interface{}{"text": prompt}},+ }}},+ {Line: 3, Data: map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "user", "content": []interface{}{map[string]interface{}{"text": "no marker here"}},+ }}},+ }+ mapped := MapSession(ref, entries, MapOptions{})+ var links []MappedEvent+ for _, m := range mapped {+ if m.Event.Event.Action == "session.handoff" {+ links = append(links, m)+ }+ }+ if len(links) != 1 {+ t.Fatalf("links = %d, want 1: %+v", len(links), mapped)+ }+ link := links[0]+ if link.SourceLine != 2 || link.Event.Handoff == nil || link.Event.Handoff.SourceHarness != "claude_code" || link.Event.Handoff.SourceSessionID != "src-1" {+ t.Fatalf("link = %+v handoff=%+v", link, link.Event.Handoff)+ }+ if link.Event.Session == nil || link.Event.Session.ID != "new-1" || link.Event.Session.WorkingDirectory != "/work" {+ t.Fatalf("link session = %+v", link.Event.Session)+ }+ if link.Event.Harness.Name != Harness || link.Event.Harness.CollectionMethod != "poll" || link.Event.Event.Fidelity != "observed" {+ t.Fatalf("link provenance = %+v %+v", link.Event.Harness, link.Event.Event)+ }+ if link.Event.Prompt != nil || link.Event.Content != nil {+ t.Fatalf("the link must not repeat the prompt: %+v", link.Event)+ }+ ids := map[string]bool{}+ for _, m := range mapped {+ if ids[m.Event.Event.ID] {+ t.Fatalf("duplicate event id %s", m.Event.Event.ID)+ }+ ids[m.Event.Event.ID] = true+ }+ again := MapSession(ref, entries, MapOptions{})+ for i := range mapped {+ if again[i].Event.Event.ID != mapped[i].Event.Event.ID {+ t.Fatal("event ids must be deterministic, so a second sync never duplicates the link")+ }+ }+}diff --git a/cli/beacon/internal/pisession/mapper.go b/cli/beacon/internal/pisession/mapper.goindex 819166ca..a4a88255 100644--- a/cli/beacon/internal/pisession/mapper.go+++ b/cli/beacon/internal/pisession/mapper.go@@ -286,6 +286,11 @@ func (m *mapper) emitPrompt(line, index int, timestamp time.Time, text string) {ev.GenAI = ensureGenAI(ev.GenAI)ev.GenAI.Input = &schema.GenAIInputInfo{Messages: asymptoteobserve.TextInputMessages(text)}m.append(line, fmt.Sprintf("user.%d", index), ev)+ if info, ok := asymptoteobserve.ParseHandoffMarker(text); ok {+ link := m.base(timestamp, "session.handoff", "session", schema.SeverityInfo, "Session continued from a "+info.SourceHarness+" session")+ link.Handoff = &info+ m.append(line, fmt.Sprintf("user.%d.handoff", index), link)+ }}func (m *mapper) emitToolResult(line int, timestamp time.Time, callID string, message map[string]interface{}) {diff --git a/cli/beacon/internal/primesession/handoff_test.go b/cli/beacon/internal/primesession/handoff_test.gonew file mode 100644index 00000000..fb08e797--- /dev/null+++ b/cli/beacon/internal/primesession/handoff_test.go@@ -0,0 +1,57 @@+package primesession++import (+ "testing"++ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"+)++func TestMapSessionRecordsAHandoffLink(t *testing.T) {+ ref := SessionRef{ID: "new-1", Path: "/tmp/new-1.jsonl", Header: map[string]interface{}{"type": "session", "id": "new-1", "cwd": "/work"}}+ prompt := "Continue the work.\n\n" + asymptoteobserve.HandoffMarker("claude_code", "src-1")+ entries := []Entry{+ {Line: 1, Data: ref.Header},+ {Line: 2, Data: map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "user", "content": []interface{}{map[string]interface{}{"text": "an unrelated block"}, map[string]interface{}{"text": prompt}},+ }}},+ {Line: 3, Data: map[string]interface{}{"type": "message", "message": map[string]interface{}{+ "role": "user", "content": []interface{}{map[string]interface{}{"text": "no marker here"}},+ }}},+ }+ mapped := MapSession(ref, entries, MapOptions{})+ var links []MappedEvent+ for _, m := range mapped {+ if m.Event.Event.Action == "session.handoff" {+ links = append(links, m)+ }+ }+ if len(links) != 1 {+ t.Fatalf("links = %d, want 1: %+v", len(links), mapped)+ }+ link := links[0]+ if link.SourceLine != 2 || link.Event.Handoff == nil || link.Event.Handoff.SourceHarness != "claude_code" || link.Event.Handoff.SourceSessionID != "src-1" {+ t.Fatalf("link = %+v handoff=%+v", link, link.Event.Handoff)+ }+ if link.Event.Session == nil || link.Event.Session.ID != "new-1" || link.Event.Session.WorkingDirectory != "/work" {+ t.Fatalf("link session = %+v", link.Event.Session)+ }+ if link.Event.Harness.Name != Harness || link.Event.Harness.CollectionMethod != "poll" || link.Event.Event.Fidelity != "observed" {+ t.Fatalf("link provenance = %+v %+v", link.Event.Harness, link.Event.Event)+ }+ if link.Event.Prompt != nil || link.Event.Content != nil {+ t.Fatalf("the link must not repeat the prompt: %+v", link.Event)+ }+ ids := map[string]bool{}+ for _, m := range mapped {+ if ids[m.Event.Event.ID] {+ t.Fatalf("duplicate event id %s", m.Event.Event.ID)+ }+ ids[m.Event.Event.ID] = true+ }+ again := MapSession(ref, entries, MapOptions{})+ for i := range mapped {+ if again[i].Event.Event.ID != mapped[i].Event.Event.ID {+ t.Fatal("event ids must be deterministic, so a second sync never duplicates the link")+ }+ }+}diff --git a/cli/beacon/internal/primesession/mapper.go b/cli/beacon/internal/primesession/mapper.goindex 8947217c..4194020c 100644--- a/cli/beacon/internal/primesession/mapper.go+++ b/cli/beacon/internal/primesession/mapper.go@@ -215,6 +215,11 @@ func (m *mapper) emitPrompt(line, index int, timestamp time.Time, text string) {ev.GenAI = ensureGenAI(ev.GenAI)ev.GenAI.Input = &schema.GenAIInputInfo{Messages: asymptoteobserve.TextInputMessages(text)}m.append(line, fmt.Sprintf("user.%d", index), ev)+ if info, ok := asymptoteobserve.ParseHandoffMarker(text); ok {+ link := m.base(timestamp, "session.handoff", "session", schema.SeverityInfo, "Session continued from a "+info.SourceHarness+" session")+ link.Handoff = &info+ m.append(line, fmt.Sprintf("user.%d.handoff", index), link)+ }}func (m *mapper) emitToolResult(line int, timestamp time.Time, callID string, message map[string]interface{}) {diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdxindex a4da50a8..0d2ab688 100644--- a/docs/cli/handoff.mdx+++ b/docs/cli/handoff.mdx@@ -23,8 +23,12 @@ Sessions come from each runtime's own local session store, not from Beacon's run| Codex CLI | `~/.codex/sessions` | `codex` || OpenCode | `~/.config/opencode` (SQLite and the legacy file store) | `opencode` || Cline | `~/.cline/data` | `cline` |+| Pi | `~/.pi/agent/sessions` (or under `PI_CODING_AGENT_DIR`) | `pi` |+| Prime Agent | `~/.prime/agent`, both `sessions` and `session-artifacts` (or `PRIME_AGENT_CODING_AGENT_DIR`) | `prime` |-When a Codex thread has more than one rollout file, `beacon handoff` lists it once, under its newest file. Cline can hold the same task both as a CLI session and in its older task history; the CLI session is the copy that is listed. Cline kanban cards are not sessions and are not listed.+When a Codex thread has more than one rollout file, `beacon handoff` lists it once, under its newest file. Cline can hold the same task both as a CLI session and in its older task history; the CLI session is the copy that is listed. Cline kanban cards are not sessions and are not listed. Prime Agent subagent transcripts, under `session-artifacts`, are listed as subagents of the session that started them.++`--store-dir <runtime>=<path>` takes the location in the table: for Pi its sessions directory, as `beacon endpoint pi sync --sessions-dir` does, and for Prime Agent the agent directory holding both of its roots.## `beacon handoff list`@@ -104,6 +108,8 @@ There are two ways to resume:| Codex CLI | `codex resume <id>` || OpenCode | `opencode --session <id>` || Cline | `cline --tui --auto-approve false --id <id>` |+ | Pi | `pi --session <session file>` |+ | Prime Agent | `prime-agent --resume <session file>` |- **Start a new session from a brief.** Otherwise, or with `--agent` naming another runtime or with `--new`, Beacon writes a brief (see `export`) and starts a new session. The first message of that session points at the brief:@@ -113,10 +119,12 @@ There are two ways to resume:| Codex CLI | `codex "<prompt>"` || OpenCode | `opencode --prompt "<prompt>"` || Cline | `cline --tui --auto-approve false "<prompt>"` |+ | Pi | `pi -- "<prompt>"` |+ | Prime Agent | `prime-agent -- "<prompt>"` |The prompt names the brief by its path and asks the agent to read it, then confirm the task before changing anything. The brief is never inlined into the command line, because a command line is visible to every local user through the process table. The prompt ends with a handoff marker (see below).-Claude Code and Cline subagent sessions, and Cline's older task history, can't be reopened by their CLIs, so they always continue from a brief. A session known only from Beacon's runtime log also continues from a brief, and it needs `--agent` if its own runtime isn't one of the four above.+Claude Code, Cline and Prime Agent subagent sessions, and Cline's older task history, can't be reopened by their CLIs, so they always continue from a brief. A session known only from Beacon's runtime log also continues from a brief, and it needs `--agent` if its own runtime isn't one Beacon can start.Cline approves every tool call by default. Beacon always passes `--auto-approve false`, so a session Beacon starts never gets auto-approval on Beacon's say-so. You can still turn it on inside the Cline TUI.@@ -124,7 +132,7 @@ The runtime runs in this terminal, in the session's recorded directory. If that| Flag | Description ||------|-------------|-| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, or `cline`. Defaults to the session's own runtime. |+| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, `cline`, `pi` or `prime`. Defaults to the session's own runtime. || `--new` | Start a new session from a brief even when the session could be reopened. || `--cwd` | Directory to start the runtime in. || `--print` | Show the plan and command without writing a brief or launching anything. |@@ -155,8 +163,8 @@ The link event keeps the new session's id, workspace and harness, and leaves theTwo paths record the link:- **Live hooks.** The prompt hook for Claude Code and the Cline and OpenCode plugins record it as the prompt is sent (`harness.collection_method: hook`).-- **Session-store sync.** `beacon endpoint claude sync`, `codex sync`, `opencode sync` and `cline sync` record it when they read the prompt back from the runtime's store (`harness.collection_method: poll`).+- **Session-store sync.** `beacon endpoint claude sync`, `codex sync`, `opencode sync`, `cline sync`, `pi sync` and `prime sync` record it when they read the prompt back from the runtime's store (`harness.collection_method: poll`).-Codex CLI prompts reach Beacon over OTLP and through `beacon endpoint codex sync`, not a prompt hook, so a session continued in Codex is linked by the sync. For the other three runtimes, a sync can record the same link a hook already did; the two carry different `collection_method` values, as every other event those runtimes report through both paths does. A sync's link has a deterministic `event.id`, so syncing again never duplicates it.+Codex CLI prompts reach Beacon over OTLP and through `beacon endpoint codex sync`, not a prompt hook, so a session continued in Codex is linked by the sync. For a runtime that also has a prompt hook or plugin, a sync can record the same link the hook already did; the two carry different `collection_method` values, as every other event those runtimes report through both paths does. A sync's link has a deterministic `event.id`, so syncing again never duplicates it.The marker is a claim made in prompt text, not a verified identity: anyone can type it. `fidelity: observed` records that the marker was seen, not that `beacon handoff resume` wrote it. A native resume keeps the session's own id, so it needs no link.