Skip to content

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

Merge main into this branch

Claudef825be18fec0
diff --cc cli/beacon/internal/handoff/hermes_test.go
index 437644d2,00000000..fba6e8fa
mode 100644,000000..100644
--- a/cli/beacon/internal/handoff/hermes_test.go
+++ b/cli/beacon/internal/handoff/hermes_test.go
@@@ -1,219 -1,0 +1,220 @@@
+package handoff
+
+import (
+ "database/sql"
+ "errors"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+var hermesUpdated = time.Date(2026, 9, 24, 11, 0, 0, 0, time.UTC)
+
+// hermesFixture writes a Hermes state.db with the columns Hermes 0.19 uses: a titled session with a
+// git branch, a compression continuation of it, and a delegate subagent it spawned.
+func hermesFixture(t *testing.T) (StoreDirs, string) {
+ t.Helper()
+ testenv.SetHome(t, t.TempDir())
+ isolateRuntimeEnv(t)
+ path := filepath.Join(t.TempDir(), ".hermes", "state.db")
+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ db, err := sql.Open("sqlite", path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer db.Close()
+ at := float64(hermesUpdated.Unix())
+ for _, stmt := range []string{
+ `CREATE TABLE sessions (
+ id TEXT PRIMARY KEY, source TEXT NOT NULL, user_id TEXT, model TEXT, model_config TEXT,
+ system_prompt TEXT, parent_session_id TEXT, started_at REAL NOT NULL, ended_at REAL,
+ end_reason TEXT, message_count INTEGER DEFAULT 0, tool_call_count INTEGER DEFAULT 0,
+ input_tokens INTEGER DEFAULT 0, output_tokens INTEGER DEFAULT 0, cache_read_tokens INTEGER DEFAULT 0,
+ cache_write_tokens INTEGER DEFAULT 0, reasoning_tokens INTEGER DEFAULT 0, cwd TEXT,
+ git_branch TEXT, git_repo_root TEXT, estimated_cost_usd REAL, actual_cost_usd REAL,
+ cost_status TEXT, cost_source TEXT, title TEXT, archived INTEGER NOT NULL DEFAULT 0)`,
+ `CREATE TABLE messages (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, role TEXT NOT NULL,
+ content TEXT, tool_call_id TEXT, tool_calls TEXT, tool_name TEXT, timestamp REAL NOT NULL,
+ token_count INTEGER, finish_reason TEXT, reasoning TEXT, reasoning_content TEXT,
+ reasoning_details TEXT, platform_message_id TEXT, observed INTEGER DEFAULT 0,
+ active INTEGER NOT NULL DEFAULT 1)`,
+ } {
+ if _, err := db.Exec(stmt); err != nil {
+ t.Fatal(err)
+ }
+ }
+ for _, row := range []struct {
+ query string
+ args []interface{}
+ }{
+ // The root was compressed into a continuation, which has no title yet.
+ {`INSERT INTO sessions (id, source, model, cwd, git_branch, title, started_at, ended_at, end_reason) VALUES (?, 'cli', 'gpt-5', '/work/api', 'feat/hermes', 'Tidy the router', ?, ?, 'compression')`,
+ []interface{}{"20260924_100000_aaaaaa", at - 3600, at - 1800}},
+ {`INSERT INTO sessions (id, source, model, cwd, git_branch, parent_session_id, started_at) VALUES (?, 'cli', 'gpt-5', '/work/api', 'feat/hermes', ?, ?)`,
+ []interface{}{"20260924_103000_bbbbbb", "20260924_100000_aaaaaa", at - 1800}},
+ {`INSERT INTO sessions (id, source, cwd, parent_session_id, model_config, started_at) VALUES (?, 'cli', '/work/api', ?, ?, ?)`,
+ []interface{}{"20260924_103500_cccccc", "20260924_103000_bbbbbb", `{"_delegate_from": "20260924_103000_bbbbbb"}`, at - 1500}},
+ {`INSERT INTO sessions (id, source, cwd, started_at, archived) VALUES ('20260901_000000_dddddd', 'cli', '/work/old', ?, 1)`,
+ []interface{}{at - 86400}},
+ {`INSERT INTO messages (session_id, role, content, timestamp) VALUES ('20260924_100000_aaaaaa', 'user', 'tidy the router', ?)`, []interface{}{at - 3500}},
+ {`INSERT INTO messages (session_id, role, content, timestamp) VALUES ('20260924_100000_aaaaaa', 'assistant', 'Reading it now.', ?)`, []interface{}{at - 3400}},
+ {`INSERT INTO messages (session_id, role, content, timestamp) VALUES ('20260924_103000_bbbbbb', 'user', ?, ?)`, []interface{}{" split the\nhandlers ", at - 1700}},
+ {`INSERT INTO messages (session_id, role, content, timestamp) VALUES ('20260924_103000_bbbbbb', 'assistant', 'Done.', ?)`, []interface{}{at}},
+ {`INSERT INTO messages (session_id, role, content, timestamp) VALUES ('20260924_103500_cccccc', 'user', 'list the handlers', ?)`, []interface{}{at - 1400}},
+ } {
+ if _, err := db.Exec(row.query, row.args...); err != nil {
+ t.Fatalf("%s: %v", row.query, err)
+ }
+ }
+ return StoreDirs{HarnessHermes: path}, path
+}
+
+func TestListReadsHermesSessions(t *testing.T) {
+ dirs, path := hermesFixture(t)
+ sessions, err := List(DefaultSources(dirs), Filter{Harness: HarnessHermes, IncludeSubagents: true})
+ if err != nil {
+ t.Fatalf("List: %v", err)
+ }
+ if got := strings.Join(sessionKeys(sessions), ","); got != "hermes/20260924_103000_bbbbbb,hermes/20260924_103500_cccccc,hermes/20260924_100000_aaaaaa" {
+ t.Fatalf("sessions = %s, want newest first and no archived session", got)
+ }
+ // The continuation has no title of its own, so its first prompt names it. It names a parent, but
+ // continues the conversation rather than running a delegated task, so it is not a subagent.
+ want := Session{Harness: HarnessHermes, ID: "20260924_103000_bbbbbb", Title: "split the handlers", Directory: "/work/api", Branch: "feat/hermes", SourcePath: path, UpdatedAt: hermesUpdated}
+ if !reflect.DeepEqual(sessions[0], want) {
+ t.Fatalf("continuation = %+v\nwant %+v", sessions[0], want)
+ }
+ root := sessions[2]
+ if root.Title != "Tidy the router" || root.Subagent || !root.UpdatedAt.Equal(hermesUpdated.Add(-1800*time.Second)) {
+ t.Fatalf("root = %+v, want its title and its end time", root)
+ }
+ sub := sessions[1]
+ if !sub.Subagent || sub.ParentID != "20260924_103000_bbbbbb" || sub.Title != "list the handlers" {
+ t.Fatalf("delegate = %+v, want a subagent of the continuation", sub)
+ }
+
+ top, err := List(DefaultSources(dirs), Filter{Harness: HarnessHermes})
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, s := range top {
+ if s.Subagent {
+ t.Fatalf("subagent %s listed without IncludeSubagents", s.ID)
+ }
+ }
+}
+
+func TestListWithoutAHermesDatabase(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ sessions, err := List(DefaultSources(StoreDirs{}), Filter{Harness: HarnessHermes})
+ if err != nil || len(sessions) != 0 {
+ t.Fatalf("List = %v, %v; want nothing and no error when Hermes has no state.db", sessions, err)
+ }
+}
+
+func TestHermesSessionBuildsABrief(t *testing.T) {
+ dirs, _ := hermesFixture(t)
+ sources := DefaultSources(dirs)
+ // A unique prefix finds the session too.
+ session, err := Find(sources, HarnessHermes, "20260924_1000")
+ 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, "tidy the router") {
+ t.Fatalf("brief prompts=%d first=%q", brief.Prompts, brief.FirstRequest)
+ }
+ if rendered := brief.Render(); !strings.Contains(rendered, "Hermes Agent") || !strings.Contains(rendered, "Reading it now.") {
+ t.Fatalf("the brief should name Hermes Agent and carry its reply:\n%s", rendered)
+ }
+}
+
+func TestHermesSessionGoneFromItsStore(t *testing.T) {
+ dirs, path := hermesFixture(t)
+ sources := DefaultSources(dirs)
+ session := Session{Harness: HarnessHermes, ID: "20260924_999999_eeeeee", SourcePath: path}
+ if _, err := Events(sources, session); !errors.Is(err, ErrNotFound) {
+ t.Fatalf("Events for a deleted session = %v, want ErrNotFound", err)
+ }
+ if err := os.Remove(path); err != nil {
+ t.Fatal(err)
+ }
+ session.ID = "20260924_100000_aaaaaa"
+ if _, err := Events(sources, session); !errors.Is(err, ErrNotFound) {
+ t.Fatalf("Events without the database = %v, want ErrNotFound", err)
+ }
+}
+
+func TestPlanResumeReopensAHermesSession(t *testing.T) {
+ session := resumableSession(t, HarnessHermes, "20260924_100000_aaaaaa")
+ plan, err := PlanResume(session, PlanOptions{LookPath: installed("hermes")})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ if plan.Mode != ModeNative || plan.Executable != "/bin/hermes" || !reflect.DeepEqual(plan.Args, []string{"--resume", session.ID}) {
+ t.Fatalf("plan = %+v", plan)
+ }
+ // An inherited HERMES_YOLO_MODE would turn every dangerous-command approval off.
+ if !reflect.DeepEqual(plan.Env, map[string]string{"HERMES_YOLO_MODE": ""}) {
+ t.Fatalf("env = %v, want HERMES_YOLO_MODE removed", plan.Env)
+ }
+ for _, arg := range plan.Args {
+ if arg == "--yolo" {
+ t.Fatal("Beacon never passes --yolo")
+ }
+ }
+}
+
+// Hermes has no interactive start with a first message, so it cannot take over a session from a
+// brief; each case says so before looking for a directory or the executable.
+func TestPlanResumeHermesCannotStartFromABrief(t *testing.T) {
+ brief := filepath.Join(t.TempDir(), "brief.md")
++ targets := strings.Join(BriefTargetNames(), ", ")
+ for _, tc := range []struct {
+ name string
+ edit func(*Session, *PlanOptions)
+ want string
+ }{
+ {"another runtime's session", func(s *Session, o *PlanOptions) { s.Harness = HarnessCodex; o.Target = HarnessHermes },
- "Hermes Agent can only reopen its own sessions; it cannot start a new session from a brief (pass --agent with one of: claude, codex, opencode, cline, pi, prime)"},
++ "Hermes Agent can only reopen its own sessions; it cannot start a new session from a brief (pass --agent with one of: " + targets + ")"},
+ {"--new", func(s *Session, o *PlanOptions) { o.ForceNew = true },
- "Hermes Agent cannot start a new session from a brief, which this session needs because a new session was requested; pass --agent to continue in one of: claude, codex, opencode, cline, pi, prime"},
++ "Hermes Agent cannot start a new session from a brief, which this session needs because a new session was requested; pass --agent to continue in one of: " + targets},
+ {"subagent", func(s *Session, o *PlanOptions) { s.Subagent = true },
+ "because this runtime's CLI cannot reopen this kind of session"},
+ {"database gone", func(s *Session, o *PlanOptions) { s.SourcePath = filepath.Join(t.TempDir(), "state.db") },
+ "because the session file is no longer on this machine"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ session := resumableSession(t, HarnessHermes, "20260924_100000_aaaaaa")
+ session.Directory = filepath.Join(t.TempDir(), "deleted")
+ opts := PlanOptions{BriefPath: brief, LookPath: installed()}
+ tc.edit(&session, &opts)
+ _, err := PlanResume(session, opts)
+ if err == nil || !strings.Contains(err.Error(), tc.want) {
+ t.Fatalf("err = %v\nwant it to contain %q", err, tc.want)
+ }
+ })
+ }
+
+ // A Hermes session still continues in another runtime from a brief.
+ session := resumableSession(t, HarnessHermes, "20260924_100000_aaaaaa")
+ plan, err := PlanResume(session, PlanOptions{Target: HarnessClaude, BriefPath: brief, LookPath: allRuntimes})
+ if err != nil {
+ t.Fatalf("PlanResume: %v", err)
+ }
+ if plan.Mode != ModeNewSession || plan.Executable != "/bin/claude" || !strings.Contains(plan.Args[0], "earlier Hermes Agent session") {
+ t.Fatalf("plan = %+v", plan)
+ }
+}
diff --cc cli/beacon/internal/handoff/resume_test.go
index 43ced577,f5afcc5b..014f8f34
--- a/cli/beacon/internal/handoff/resume_test.go
+++ b/cli/beacon/internal/handoff/resume_test.go
@@@ -24,7 -24,8 +24,7 @@@ func installed(names ...string) func(st
}
}
- var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent", "hermes")
-var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent",
- "omp", "gemini", "qwen", "kiro-cli", "agy", "devin", "muse", "openhands", "goose")
++var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent", "omp", "gemini", "qwen", "kiro-cli", "agy", "devin", "muse", "openhands", "goose", "hermes")
// 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 c07ad4c8,c23c418d..96f5cd88
--- a/cli/beacon/internal/handoff/runtimes.go
+++ b/cli/beacon/internal/handoff/runtimes.go
@@@ -54,7 -53,17 +54,18 @@@ const
HarnessCline = clinesession.Harness
HarnessPi = pisession.Harness
HarnessPrime = primesession.Harness
+ HarnessHermes = hermessession.Harness
+
+ // Runtimes Beacon starts but whose sessions it reads only from the runtime log.
+ HarnessOhMyPi = "omp"
+ HarnessGemini = "gemini_cli"
+ HarnessQwen = "qwen_code"
+ HarnessKiro = "kiro"
+ HarnessAntigravity = "antigravity_cli"
+ HarnessDevin = "devin-cli"
+ HarnessMuse = "muse_code"
+ HarnessOpenHands = "openhands"
+ HarnessGoose = "goose"
)
// runtimes lists every runtime handoff supports, in display order.
@@@ -151,29 -160,103 +162,126 @@@ var runtimes = []Runtime
NewSession: func(prompt string) []string { return []string{"--", prompt} },
},
},
+ {
+ Harness: HarnessHermes,
+ Label: "Hermes Agent",
+ Aliases: []string{"hermes-agent"},
+ NewSource: func(path string) Source { return &hermesSource{path: path} },
+ Command: &runtimeCommand{
+ Executable: "hermes",
+ Resume: func(s Session) ([]string, bool) {
+ // A delegate subagent ran one task for its parent; reopening it alone reopens a fragment.
+ if s.Subagent {
+ return nil, false
+ }
+ // Hermes looks the id up in its state database, follows a compressed session on to its
+ // latest continuation, and changes into the session's recorded directory itself.
+ return []string{"--resume", s.ID}, true
+ },
+ // NewSession is nil: Hermes has no interactive start with a first message, only one-shot
+ // runs (chat -q, -z), and -z bypasses approvals. It reopens its own sessions only.
+ //
+ // HERMES_YOLO_MODE, inherited from the shell, would bypass every dangerous-command approval.
+ Env: map[string]string{"HERMES_YOLO_MODE": ""},
+ },
+ },
+
+ // The runtimes below keep no session store Beacon reads. Their sessions come from Beacon's
+ // runtime log, so they always continue from a brief; each can also be the runtime another
+ // session continues in. Where a CLI lets its approval mode be set, the command pins the mode
+ // that asks, so a user or project setting that approves everything does not carry over to a
+ // session Beacon starts.
+ {
+ Harness: HarnessOhMyPi,
+ Label: "Oh My Pi",
+ Aliases: []string{"oh-my-pi"},
+ // Oh My Pi approves every tool call by default (tools.approvalMode "yolo").
+ Command: &runtimeCommand{
+ Executable: "omp",
+ NewSession: func(prompt string) []string { return []string{"--approval-mode=always-ask", prompt} },
+ },
+ },
+ {
+ Harness: HarnessGemini,
+ Label: "Gemini CLI",
+ Aliases: []string{"gemini", "gemini-cli"},
+ Command: &runtimeCommand{
+ Executable: "gemini",
+ NewSession: func(prompt string) []string {
+ return []string{"--approval-mode", "default", "--prompt-interactive", prompt}
+ },
+ },
+ },
+ {
+ Harness: HarnessQwen,
+ Label: "Qwen Code",
+ Aliases: []string{"qwen", "qwen-code"},
+ // A positional prompt is one-shot in Qwen Code; --prompt-interactive keeps the session open.
+ Command: &runtimeCommand{
+ Executable: "qwen",
+ NewSession: func(prompt string) []string {
+ return []string{"--approval-mode", "default", "--prompt-interactive", prompt}
+ },
+ },
+ },
+ {
+ Harness: HarnessKiro,
+ Label: "Kiro",
+ Aliases: []string{"kiro-cli"},
+ Command: &runtimeCommand{
+ Executable: "kiro-cli",
+ NewSession: func(prompt string) []string { return []string{"chat", prompt} },
+ },
+ },
+ {
+ Harness: HarnessAntigravity,
+ Label: "Antigravity CLI",
+ Aliases: []string{"antigravity", "agy"},
+ Command: &runtimeCommand{
+ Executable: "agy",
+ NewSession: func(prompt string) []string { return []string{"--prompt-interactive", prompt} },
+ },
+ },
+ {
+ Harness: HarnessDevin,
+ Label: "Devin CLI",
+ // Beacon's Devin CLI hooks record "devin-cli"; hooks written by older versions recorded
+ // "devin", which reaches this entry through its alias.
+ Aliases: []string{"devin"},
+ // DEVIN_PERMISSION_MODE can hold "dangerous", which approves every tool; the flag wins over
+ // it. Devin reads a bare argument as a path to open, so the prompt follows --.
+ Command: &runtimeCommand{
+ Executable: "devin",
+ NewSession: func(prompt string) []string { return []string{"--permission-mode", "auto", "--", prompt} },
+ },
+ },
+ {
+ Harness: HarnessMuse,
+ Label: "Muse Code",
+ Aliases: []string{"muse", "muse-code"},
+ Command: &runtimeCommand{
+ Executable: "muse",
+ NewSession: func(prompt string) []string { return []string{"--approval-mode", "on-request", prompt} },
+ },
+ },
+ {
+ Harness: HarnessOpenHands,
+ Label: "OpenHands",
+ Command: &runtimeCommand{
+ Executable: "openhands",
+ NewSession: func(prompt string) []string { return []string{"--task", prompt} },
+ },
+ },
+ {
+ Harness: HarnessGoose,
+ Label: "goose",
+ // goose approves every tool call by default and has no flag for its mode, only GOOSE_MODE.
+ Command: &runtimeCommand{
+ Executable: "goose",
+ NewSession: func(prompt string) []string { return []string{"run", "--interactive", "--text", prompt} },
+ Env: map[string]string{"GOOSE_MODE": "approve"},
+ },
+ },
}
// Harnesses lists the runtimes handoff supports, in display order.
diff --cc docs/cli/handoff.mdx
index 0a292bbd,26095a20..cae529b3
--- a/docs/cli/handoff.mdx
+++ b/docs/cli/handoff.mdx
@@@ -25,12 -25,29 +25,30 @@@ Sessions come from each runtime's own l
| 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` |
+| Hermes Agent | `~/.hermes/state.db` | `hermes` |
-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.
+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.
-`--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.
+`--store-dir <runtime>=<path>` takes the location in the table: for Pi its sessions directory, as `beacon endpoint pi sync --sessions-dir` does, for Prime Agent the agent directory holding both of its roots, and for Hermes Agent the `state.db` file, as `beacon endpoint hermes sync --db` does.
+ ### Runtimes Beacon starts but does not read
+
+ Beacon keeps no reader for these runtimes' own session stores, so `list` does not show their sessions. `export` and `resume` still find one by id in Beacon's runtime log, and they can be the runtime another session continues in (`--agent`):
+
+ | Runtime | `--agent` |
+ |---------|-----------|
+ | Oh My Pi | `omp` |
+ | Gemini CLI | `gemini` |
+ | Qwen Code | `qwen` |
+ | Kiro | `kiro` |
+ | Antigravity CLI | `agy` |
+ | Devin CLI | `devin` |
+ | Muse Code | `muse` |
+ | OpenHands | `openhands` |
+ | goose | `goose` |
+
+ Kimi Code can only take a prompt non-interactively, and Senpi (`omo`) moves Pi's agent directory into its own the first time it runs, so Beacon does not start them.
+
## `beacon handoff list`
Lists resumable sessions, newest first.
@@@ -132,7 -155,7 +159,8 @@@ Claude Code, Cline, Prime Agent and Her
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.
+Hermes Agent asks before dangerous commands by default. Beacon never passes `--yolo`, and it removes `HERMES_YOLO_MODE` from the environment it starts Hermes in, so an exported variable can't turn those prompts off. `hermes --resume` looks the id up in the state database Hermes itself uses (under `HERMES_HOME` when that is set), not in a `--store-dir` path.
+ The same holds for every runtime Beacon starts. Oh My Pi and goose approve every tool call by default, so Beacon passes `--approval-mode=always-ask` to Oh My Pi and sets `GOOSE_MODE=approve` for goose. Where a CLI takes an approval mode, Beacon names the mode that asks (Gemini CLI, Qwen Code, Muse Code, and Devin CLI, whose `DEVIN_PERMISSION_MODE` could otherwise hold `dangerous`), so a user or project setting that approves everything does not carry over. Beacon never passes a flag that turns approvals off.
The runtime runs in this terminal, in the session's recorded directory. If that directory no longer exists, Beacon stops rather than starting somewhere else; pass `--cwd` to choose a directory. Beacon prints the plan and asks `Continue? [Y/n]` before launching. Without a terminal, it launches only with `--yes`. `beacon handoff resume` exits with the runtime's own exit code.