Skip to content

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

Merge remote-tracking branch 'origin/main' into claude/gallant-curie-cqv4rr-j-fx

Claude19ebac7ef7b3
diff --cc cli/beacon/internal/handoff/fx_test.go
index b35f97a6,00000000..0f959ad8
mode 100644,000000..100644
--- a/cli/beacon/internal/handoff/fx_test.go
+++ b/cli/beacon/internal/handoff/fx_test.go
@@@ -1,208 -1,0 +1,213 @@@
+package handoff
+
+import (
+ "errors"
+ "fmt"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+var fxUpdated = time.Date(2026, 9, 24, 11, 0, 0, 0, time.UTC)
+
+const (
+ fxSessionA = "1770000000000-1770000000000000000-a1b2c3d4e5f60718"
+ fxSessionB = "1770000500000-1770000500000000000-0f1e2d3c4b5a6978"
+)
+
+// fxFrame is one events.jsonl line in fx's envelope, fields in fx's own order.
+func fxFrame(seq int, kind, payload string) string {
+ return fmt.Sprintf(`{"schema_version":1,"log_generation":"1f4b2c8e6d3a5a7c9b613f0d5e8c2a14","seq":%d,"event_id":"%032x","timestamp_ms":%d,"kind":%q,"payload":%s}`+"\n",
+ seq, seq, 1770000000000+int64(seq)*1000, kind, payload)
+}
+
+func fxStartedFrame(id, workspace string) string {
+ return fxFrame(1, "session_started", fmt.Sprintf(`{"id":%q,"created_at_ms":1770000000000,"origin_workspace_root":%q,"workspace_root":%q,"conversation_language":"en","preferences":null,"usage":null}`, id, workspace, workspace))
+}
+
+func fxTurnFrame(seq int, prompt, reply string) string {
+ return fxFrame(seq, "history_turn_committed", fmt.Sprintf(`{"conversation_language":"en","total_input_tokens":0,"total_output_tokens":0,"work_id":"w",`+
+ `"turn":{"kind":"assistant","user":{"text":%q,"images":[]},"assistant":%q,"execution":null}}`, prompt, reply))
+}
+
+// fxFixture lays down an fx sessions directory: one session whose manifest records that it was
+// rebound to another workspace, and one fx has only just created, with no manifest yet.
+func fxFixture(t *testing.T) (StoreDirs, string, string) {
+ t.Helper()
+ testenv.SetHome(t, t.TempDir())
+ isolateRuntimeEnv(t)
+ sessions := filepath.Join(t.TempDir(), "fx-sessions")
+ dirs := StoreDirs{HarnessFx: sessions}
+
+ logA := filepath.Join(sessions, fxSessionA, "events.jsonl")
+ writeFixture(t, logA, fxStartedFrame(fxSessionA, "/work/old")+
+ fxTurnFrame(2, " add a\nhealth endpoint ", "Added GET /healthz.")+
+ fxTurnFrame(3, "now run the tests", "They pass."))
+ writeFixture(t, filepath.Join(sessions, fxSessionA, "session.json"), fmt.Sprintf(
+ `{"schema_version":3,"storage_format":"event_log_v1","id":%q,"log_generation":"1f4b2c8e6d3a5a7c9b613f0d5e8c2a14",`+
+ `"created_at_ms":1770000000000,"updated_at_ms":%d,"origin_workspace_root":"/work/old","workspace_root":"/work/api",`+
+ `"conversation_language":"en","history_len":2,"total_input_tokens":0,"total_output_tokens":0,"last_event_seq":3,"event_log_bytes":0,"preferences":null}`,
+ fxSessionA, fxUpdated.UnixMilli()))
+
+ logB := filepath.Join(sessions, fxSessionB, "events.jsonl")
+ writeFixture(t, logB, fxStartedFrame(fxSessionB, "/work/web")+fxTurnFrame(2, "fix the login form", "Fixed."))
+ setModTime(t, logB, fxUpdated.Add(-time.Hour))
+ return dirs, logA, logB
+}
+
+func TestListReadsFxSessions(t *testing.T) {
+ dirs, logA, logB := fxFixture(t)
+ sessions, err := List(DefaultSources(dirs), Filter{Harness: HarnessFx})
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ want := []Session{
+ // The manifest's workspace wins over where the session started.
+ {Harness: HarnessFx, ID: fxSessionA, Title: "add a health endpoint", Directory: "/work/api", SourcePath: logA, UpdatedAt: fxUpdated},
+ // Without a manifest, the session_started event names the workspace and the log's mtime the update.
+ {Harness: HarnessFx, ID: fxSessionB, Title: "fix the login form", Directory: "/work/web", SourcePath: logB, UpdatedAt: fxUpdated.Add(-time.Hour)},
+ }
+ if !reflect.DeepEqual(sessions, want) {
+ t.Fatalf("sessions = %+v\nwant %+v", sessions, want)
+ }
+}
+
+func TestFxOversizedFirstTurnStillListsTitle(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ isolateRuntimeEnv(t)
+ sessions := filepath.Join(t.TempDir(), "fx-sessions")
+ id := fxSessionA
+ log := filepath.Join(sessions, id, "events.jsonl")
+
+ bigReply := strings.Repeat("x", 2<<20) // 2 MiB reply makes the turn exceed 1 MiB
+ writeFixture(t, log, fxStartedFrame(id, "/work/big")+fxTurnFrame(2, "deploy to prod", bigReply))
+
+ head := readFxHead(log)
+ if head.FirstPrompt != "deploy to prod" {
+ t.Fatalf("readFxHead missed oversized turn: FirstPrompt = %q", head.FirstPrompt)
+ }
+}
+
+func TestFxStoreMissingListsNothing(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ sessions, err := (&fxSource{dir: filepath.Join(t.TempDir(), "absent")}).List()
+ if err != nil || sessions != nil {
+ t.Fatalf("List = %v, %v; want nil, nil", sessions, err)
+ }
+ // The default store is under HOME, which here has none.
+ sessions, err = (&fxSource{}).List()
+ if err != nil || sessions != nil {
+ t.Fatalf("default List = %v, %v; want nil, nil", sessions, err)
+ }
+}
+
+func TestFxSessionBuildsABrief(t *testing.T) {
+ dirs, _, _ := fxFixture(t)
+ sources := DefaultSources(dirs)
+ // A unique prefix finds the session too.
+ session, err := Find(sources, HarnessFx, fxSessionA[:20])
+ if err != nil {
+ t.Fatalf("Find: %v", err)
+ }
+ if session.ID != fxSessionA {
+ t.Fatalf("Find = %s, want %s", session.ID, fxSessionA)
+ }
+ events, err := Events(sources, session)
+ if err != nil {
+ t.Fatalf("Events: %v", err)
+ }
+ brief := BuildBrief(session, events, FromSessionStore, time.Now())
+ if brief.Prompts != 2 || !strings.Contains(brief.FirstRequest, "health endpoint") {
+ t.Fatalf("brief prompts=%d first=%q", brief.Prompts, brief.FirstRequest)
+ }
+ rendered := brief.Render()
+ if !strings.Contains(rendered, "They pass.") || !strings.Contains(rendered, RuntimeLabel(HarnessFx)) {
+ t.Fatalf("brief is missing the last reply or the runtime:\n%s", rendered)
+ }
+}
+
+func TestFxSessionGoneFromItsStore(t *testing.T) {
+ dirs, logA, _ := fxFixture(t)
+ for _, session := range []Session{
+ {Harness: HarnessFx, ID: fxSessionA, SourcePath: logA + ".moved"},
+ {Harness: HarnessFx, ID: "1770000900000-gone", SourcePath: logA},
+ } {
+ if _, err := Events(DefaultSources(dirs), session); !errors.Is(err, ErrNotFound) {
+ t.Fatalf("Events(%s) = %v, want ErrNotFound", session.ID, err)
+ }
+ }
+}
+
+func TestPlanResumeReopensAnFxSessionInItsWorkspace(t *testing.T) {
+ session := resumableSession(t, HarnessFx, fxSessionA)
+ plan, err := PlanResume(session, PlanOptions{LookPath: installed("fx")})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ // fx scopes sessions to a workspace, so it must start in the session's.
+ if plan.Mode != ModeNative || plan.Executable != "/bin/fx" || !reflect.DeepEqual(plan.Args, []string{"--resume", fxSessionA}) || plan.Dir != session.Directory {
+ t.Fatalf("plan = %+v", plan)
+ }
+}
+
+func TestPlanResumeReopensAnFxSessionWithNoRecordedDirectory(t *testing.T) {
+ session := resumableSession(t, HarnessFx, fxSessionA)
+ cwdDir := session.Directory
+ session.Directory = ""
+ plan, err := PlanResume(session, PlanOptions{Dir: cwdDir, LookPath: installed("fx")})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ if plan.Mode != ModeNative || plan.Executable != "/bin/fx" || plan.Dir != cwdDir {
+ t.Fatalf("plan = %+v, want native resume in %s", plan, cwdDir)
+ }
+}
+
+func TestPlanResumeRefusesToStartANewFxSession(t *testing.T) {
+ brief := filepath.Join(t.TempDir(), "brief.md")
+ fxSession := resumableSession(t, HarnessFx, fxSessionA)
+ gone := fxSession
+ gone.SourcePath = filepath.Join(t.TempDir(), "missing", "events.jsonl")
+ for _, tc := range []struct {
+ name string
+ session Session
+ opts PlanOptions
+ reason string
+ }{
+ {"another runtime's session", resumableSession(t, HarnessClaude, "claude-1"), PlanOptions{Target: HarnessFx}, ReasonOtherRuntime},
+ {"a new session requested", fxSession, PlanOptions{ForceNew: true}, ReasonRequested},
+ {"the session file is gone", gone, PlanOptions{}, ReasonSessionGone},
+ {"known only from the runtime log", fxSession, PlanOptions{FromRuntimeLog: true}, ReasonFromRuntimeLog},
+ // fx resumes only sessions of the workspace it starts in.
+ {"--cwd outside its workspace", fxSession, PlanOptions{Dir: t.TempDir()}, ReasonOtherDirectory},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ tc.opts.BriefPath, tc.opts.LookPath = brief, allRuntimes
+ plan, err := PlanResume(tc.session, tc.opts)
+ if err == nil {
+ t.Fatalf("PlanResume = %+v, want an error: fx cannot start a session from a brief", plan)
+ }
- if !strings.Contains(err.Error(), "fx cannot start a new session from a brief") || !strings.Contains(err.Error(), ReasonText(tc.reason)) {
- t.Fatalf("error = %v", err)
++ // Another runtime's session is refused outright; fx's own names why it needs a brief.
++ want := "fx can only reopen its own sessions"
++ if tc.reason != ReasonOtherRuntime {
++ want = "fx cannot start a new session from a brief, which this session needs because " + ReasonText(tc.reason)
++ }
++ if !strings.Contains(err.Error(), want) {
++ t.Fatalf("error = %v, want it to say %q", err, want)
+ }
+ })
+ }
+
+ // fx's own sessions still continue in a runtime that can start one.
+ plan, err := PlanResume(fxSession, PlanOptions{Target: HarnessClaude, BriefPath: brief, LookPath: allRuntimes})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ if plan.Mode != ModeNewSession || plan.Executable != "/bin/claude" || !reflect.DeepEqual(plan.Args, []string{NewSessionPrompt(fxSession, brief)}) {
+ t.Fatalf("plan = %+v", plan)
+ }
+}
diff --cc cli/beacon/internal/handoff/resume_test.go
index 209d2c38,7a66f36b..f014eab3
--- a/cli/beacon/internal/handoff/resume_test.go
+++ b/cli/beacon/internal/handoff/resume_test.go
@@@ -25,7 -25,8 +25,8 @@@ func installed(names ...string) func(st
}
var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent", "droid",
- "omp", "gemini", "qwen", "kiro-cli", "agy", "devin", "muse", "openhands", "goose", "copilot", "fx")
+ "omp", "gemini", "qwen", "kiro-cli", "agy", "devin", "muse", "openhands", "goose", "copilot",
- "hermes")
++ "hermes", "fx")
// resumableSession is a session whose directory and session file both exist.
func resumableSession(t *testing.T, harness, id string) Session {
diff --cc cli/beacon/internal/handoff/runtimes.go
index 066985b8,8a0e8d6b..e46f6234
--- a/cli/beacon/internal/handoff/runtimes.go
+++ b/cli/beacon/internal/handoff/runtimes.go
@@@ -10,7 -10,7 +10,8 @@@ import
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/copilotsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/dshsession"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/factorysession"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/fxsession"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession"
"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"
@@@ -62,8 -59,8 +63,9 @@@ const
HarnessPrime = primesession.Harness
HarnessFactory = factorysession.Harness
HarnessCopilot = copilotsession.Harness
+ HarnessHermes = hermessession.Harness
HarnessDSH = dshsession.Harness
+ HarnessFx = fxsession.Harness
// Runtimes Beacon starts but whose sessions it reads only from the runtime log.
HarnessOhMyPi = "omp"
diff --cc docs/cli/handoff.mdx
index 245fc96a,258f4c52..9834c474
--- a/docs/cli/handoff.mdx
+++ b/docs/cli/handoff.mdx
@@@ -27,14 -27,12 +27,15 @@@ Sessions come from each runtime's own l
| Prime Agent | `~/.prime/agent`, both `sessions` and `session-artifacts` (or `PRIME_AGENT_CODING_AGENT_DIR`) | `prime` |
| Factory Droid | `~/.factory/sessions` | `droid` |
| GitHub Copilot CLI | `~/.copilot/session-state` | `copilot` |
+ | Hermes Agent | `~/.hermes/state.db` | `hermes` |
| DeepSeek Harness | `~/.dsh/sessions` (or under `DSH_HOME`) | `dsh` |
+| fx | `~/.fx/sessions` | `fx` |
- 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. A DeepSeek Harness session that DSH spawned for delegated work is listed as a subagent of the session that started it; a fork of a session is listed as a session of its own.
+ 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. Hermes Agent delegate subagents are listed as subagents of the session that spawned them. When Hermes compresses a long conversation it continues it in a new session; each of those sessions is listed, and reopening any of them reopens the latest. A DeepSeek Harness session that DSH spawned for delegated work is listed as a subagent of the session that started it; a fork of a session is listed as a session of its own.
- `--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. For Factory Droid it is the sessions directory, as `beacon endpoint factory sync --sessions-dir` does. For GitHub Copilot CLI it is the `~/.copilot` directory that holds `session-state`, as `beacon endpoint copilot sync --copilot-dir` does. For DeepSeek Harness it is its `DSH_HOME`, as `beacon endpoint dsh sync --dsh-home` does. For fx it is its sessions directory, as `beacon endpoint fx sync --sessions-dir` does.
-`--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. For Factory Droid it is the sessions directory, as `beacon endpoint factory sync --sessions-dir` does. For GitHub Copilot CLI it is the `~/.copilot` directory that holds `session-state`, as `beacon endpoint copilot sync --copilot-dir` does. For Hermes Agent it is the `state.db` file, as `beacon endpoint hermes sync --db` does. For DeepSeek Harness it is its `DSH_HOME`, as `beacon endpoint dsh sync --dsh-home` does.
++`--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. For Factory Droid it is the sessions directory, as `beacon endpoint factory sync --sessions-dir` does. For GitHub Copilot CLI it is the `~/.copilot` directory that holds `session-state`, as `beacon endpoint copilot sync --copilot-dir` does. For Hermes Agent it is the `state.db` file, as `beacon endpoint hermes sync --db` does. For DeepSeek Harness it is its `DSH_HOME`, as `beacon endpoint dsh sync --dsh-home` does. For fx it is its sessions directory, as `beacon endpoint fx sync --sessions-dir` does.
+
+fx records no session title, so an fx session is listed under its first prompt, and its directory is the workspace fx last bound it to.
### Runtimes Beacon starts but does not read
@@@ -67,7 -65,7 +68,7 @@@ beacon handoff list --jso
| Flag | Description |
|------|-------------|
- | `--harness` | Only this runtime: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime`, `droid`, `copilot`, `dsh` or `fx`. |
-| `--harness` | Only this runtime: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime`, `droid`, `copilot`, `hermes` or `dsh`. |
++| `--harness` | Only this runtime: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime`, `droid`, `copilot`, `hermes`, `dsh` or `fx`. |
| `--here` | Only sessions that ran in the current directory or below it. |
| `--dir` | Only sessions that ran in this directory or below it. |
| `--subagents` | Include subagent sessions. They are hidden by default, because resuming one resumes a fragment of its parent's task. |
@@@ -136,7 -134,7 +137,8 @@@ There are two ways to resume
| Prime Agent | `prime-agent --resume <session file>` |
| Factory Droid | `droid --resume <id>` |
| GitHub Copilot CLI | `copilot --resume=<id>` |
+ | Hermes Agent | `hermes --resume <id>` |
+ | fx | `fx --resume <id>`, in the session's workspace |
- **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:
@@@ -209,7 -209,7 +215,7 @@@ The link event keeps the new session's
Two paths record the link:
- **Live hooks and plugins.** Every runtime whose prompts Beacon captures as they are sent records it: the shared prompt hook (Claude Code, Cursor, Factory Droid, Qwen Code, Kiro, Kimi Code, Devin, Muse Code, OpenHands, Grok Build, DeepSeek Harness, Hermes Agent, VS Code), Antigravity (including the prompt it recovers from its transcript when the prompt hook does not fire), the Cline, OpenCode and OpenClaw plugins, and the Pi, Oh My Pi, Prime Agent and Senpi extensions (`harness.collection_method` `hook` or `plugin`).
- - **Session-store sync.** `beacon endpoint claude sync`, `codex sync`, `opencode sync`, `cline sync`, `pi sync`, `prime sync`, `factory sync`, `copilot sync`, `dsh sync` and `fx 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`, `prime sync`, `factory sync`, `copilot sync`, `hermes sync` and `dsh 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`, `prime sync`, `factory sync`, `copilot sync`, `hermes sync`, `dsh sync` and `fx 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. The same holds for GitHub Copilot CLI, whose live path is OTLP: `beacon endpoint copilot sync` records the link. 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.