Skip to content

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

handoff: add Hermes Agent

Claude13610ed3bc6c
diff --git a/cli/beacon/internal/handoff/hermes.go b/cli/beacon/internal/handoff/hermes.go
new file mode 100644
index 00000000..3b3d7483
--- /dev/null
+++ b/cli/beacon/internal/handoff/hermes.go
@@ -0,0 +1,118 @@
+package handoff
+
+import (
+ "errors"
+ "os"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/hermessession"
+)
+
+// Hermes Agent keeps every session in one SQLite database, state.db, so a session's SourcePath is
+// that database rather than a file of its own.
+
+type hermesSource struct{ path string }
+
+func (s *hermesSource) Harness() string { return HarnessHermes }
+
+// dbPath reads path as Hermes's state database, as `beacon endpoint hermes sync --db` does.
+func (s *hermesSource) dbPath() string {
+ if s.path == "" {
+ return hermessession.DefaultDBPath()
+ }
+ return s.path
+}
+
+// open opens the state database, or returns nil when there is none.
+func (s *hermesSource) open() (*hermessession.Store, error) {
+ path := s.dbPath()
+ if _, err := os.Stat(path); err != nil {
+ if errors.Is(err, os.ErrNotExist) {
+ return nil, nil
+ }
+ return nil, err
+ }
+ return hermessession.OpenStore(path)
+}
+
+func (s *hermesSource) List() ([]Session, error) {
+ store, err := s.open()
+ if err != nil || store == nil {
+ return nil, err
+ }
+ defer store.Close()
+ found, err := store.ListSessions()
+ if err != nil {
+ return nil, err
+ }
+ details, err := store.SessionDetails()
+ if err != nil {
+ return nil, err
+ }
+ sessions := make([]Session, 0, len(found))
+ for _, h := range found {
+ detail := details[h.ID]
+ title := h.Title
+ if title == "" {
+ title = detail.FirstPrompt
+ }
+ updated := max(h.StartedAtMS, h.EndedAtMS, detail.LastMessageAtMS)
+ // Only a delegate subagent is a child session here. A compression continuation or a /branch
+ // fork also names a parent, but carries the conversation on and is listed as a session.
+ parent := ""
+ if detail.DelegateFrom != "" {
+ parent = h.ParentSessionID
+ if parent == "" && detail.DelegateFrom != hermesOrphanedDelegate {
+ parent = detail.DelegateFrom
+ }
+ }
+ sessions = append(sessions, Session{
+ Harness: HarnessHermes,
+ ID: h.ID,
+ Title: oneLine(title),
+ Directory: h.CWD,
+ Branch: detail.Branch,
+ SourcePath: store.Path(),
+ UpdatedAt: unixMS(updated),
+ Subagent: detail.DelegateFrom != "",
+ ParentID: parent,
+ })
+ }
+ return sessions, nil
+}
+
+// hermesOrphanedDelegate is the _delegate_from value Hermes leaves on a subagent whose parent was
+// deleted.
+const hermesOrphanedDelegate = "__orphaned__"
+
+func (s *hermesSource) Events(session Session) ([]schema.Event, error) {
+ store, err := s.open()
+ if err != nil {
+ return nil, err
+ }
+ if store == nil {
+ return nil, errSessionGone(session)
+ }
+ defer store.Close()
+ found, err := store.ListSessions()
+ if err != nil {
+ return nil, err
+ }
+ for _, h := range found {
+ if h.ID != session.ID {
+ continue
+ }
+ messages, err := store.ReadMessages(h.ID, 0)
+ if err != nil {
+ return nil, err
+ }
+ // A nil cursor maps the whole session, as a first sync would.
+ mapped, _ := hermessession.MapSession(h, messages, nil)
+ events := make([]schema.Event, 0, len(mapped))
+ for _, m := range mapped {
+ events = append(events, m.Event)
+ }
+ return events, nil
+ }
+ return nil, errSessionGone(session)
+}
diff --git a/cli/beacon/internal/handoff/hermes_test.go b/cli/beacon/internal/handoff/hermes_test.go
new file mode 100644
index 00000000..437644d2
--- /dev/null
+++ b/cli/beacon/internal/handoff/hermes_test.go
@@ -0,0 +1,219 @@
+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")
+ 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)"},
+ {"--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"},
+ {"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 --git a/cli/beacon/internal/handoff/resume.go b/cli/beacon/internal/handoff/resume.go
index 2b30824d..33429431 100644
--- a/cli/beacon/internal/handoff/resume.go
+++ b/cli/beacon/internal/handoff/resume.go
@@ -75,6 +75,16 @@ func PlanResume(session Session, opts PlanOptions) (Plan, error) {
if !ok {
return Plan{}, fmt.Errorf("%s sessions cannot be started by beacon handoff (supported: %s)", target, strings.Join(StartableNames(), ", "))
}
+ reason := nativeBlocker(session, target, opts)
+ // Said before anything else is checked, since no directory or install fixes it.
+ if reason != "" && targetCommand.NewSession == nil {
+ others := strings.Join(BriefTargetNames(), ", ")
+ if reason == ReasonOtherRuntime {
+ return Plan{}, fmt.Errorf("%s can only reopen its own sessions; it cannot start a new session from a brief (pass --agent with one of: %s)", RuntimeLabel(target), others)
+ }
+ return Plan{}, fmt.Errorf("%s cannot start a new session from a brief, which this session needs because %s; pass --agent to continue in one of: %s",
+ RuntimeLabel(target), ReasonText(reason), others)
+ }
dir, err := resumeDir(session, opts.Dir)
if err != nil {
return Plan{}, err
@@ -92,7 +102,6 @@ func PlanResume(session Session, opts PlanOptions) (Plan, error) {
plan.Env[name] = value
}
}
- reason := nativeBlocker(session, target, opts)
if reason == "" {
plan.Mode, plan.Args = ModeNative, nativeArgs(targetCommand, session)
return plan, nil
@@ -106,9 +115,6 @@ func PlanResume(session Session, opts PlanOptions) (Plan, error) {
}
plan.Mode, plan.Reason = ModeNewSession, reason
plan.BriefPath = opts.BriefPath
- if targetCommand.NewSession == nil {
- return Plan{}, fmt.Errorf("%s cannot start a new session from a brief (%s)", RuntimeLabel(target), ReasonText(reason))
- }
plan.Args = targetCommand.NewSession(NewSessionPrompt(session, opts.BriefPath))
return plan, nil
}
@@ -194,6 +200,17 @@ func ReasonText(reason string) string {
return reason
}
+// BriefTargetNames names the runtimes Beacon can start a new session in from a brief, for messages.
+func BriefTargetNames() []string {
+ var names []string
+ for i, r := range runtimes {
+ if r.Command != nil && r.Command.NewSession != nil {
+ names = append(names, RuntimeNames()[i])
+ }
+ }
+ return names
+}
+
// StartableNames names the runtimes Beacon can start, for messages.
func StartableNames() []string {
var names []string
diff --git a/cli/beacon/internal/handoff/resume_test.go b/cli/beacon/internal/handoff/resume_test.go
index 54ed8c2d..43ced577 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", "pi", "prime-agent")
+var allRuntimes = installed("claude", "codex", "opencode", "cline", "pi", "prime-agent", "hermes")
// resumableSession is a session whose directory and session file both exist.
func resumableSession(t *testing.T, harness, id string) Session {
diff --git a/cli/beacon/internal/handoff/runtimes.go b/cli/beacon/internal/handoff/runtimes.go
index 76162102..c07ad4c8 100644
--- a/cli/beacon/internal/handoff/runtimes.go
+++ b/cli/beacon/internal/handoff/runtimes.go
@@ -7,6 +7,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/claudesession"
"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/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"
@@ -53,6 +54,7 @@ const (
HarnessCline = clinesession.Harness
HarnessPi = pisession.Harness
HarnessPrime = primesession.Harness
+ HarnessHermes = hermessession.Harness
)
// runtimes lists every runtime handoff supports, in display order.
@@ -149,6 +151,29 @@ 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": ""},
+ },
+ },
}
// Harnesses lists the runtimes handoff supports, in display order.
diff --git a/cli/beacon/internal/hermessession/collect.go b/cli/beacon/internal/hermessession/collect.go
index e6c1ce30..be876ca0 100644
--- a/cli/beacon/internal/hermessession/collect.go
+++ b/cli/beacon/internal/hermessession/collect.go
@@ -424,6 +424,96 @@ ORDER BY id`, sessionID, afterID)
return out, rows.Err()
}
+// SessionDetail is what a session listing needs beyond ListSessions: where the session stands and
+// what spawned it.
+type SessionDetail struct {
+ // Branch is the git branch Hermes recorded for the session's directory. Older databases have no
+ // git_branch column and leave it empty.
+ Branch string
+ // DelegateFrom names the session that spawned this one as a delegate subagent, from the
+ // _delegate_from marker Hermes writes into model_config ("__orphaned__" once that parent is
+ // deleted). Compression continuations and /branch forks also carry a parent_session_id, but no
+ // marker: they continue the conversation rather than run a delegated task.
+ DelegateFrom string
+ // FirstPrompt is the session's first user message.
+ FirstPrompt string
+ // LastMessageAtMS is when the session's latest active message was written.
+ LastMessageAtMS int64
+}
+
+// SessionDetails returns a SessionDetail for every session ListSessions lists, keyed by id.
+func (s *Store) SessionDetails() (map[string]SessionDetail, error) {
+ columns := map[string]bool{}
+ rows, err := s.db.Query(`SELECT name FROM pragma_table_info('sessions')`)
+ if err != nil {
+ return nil, err
+ }
+ for rows.Next() {
+ var name string
+ if err := rows.Scan(&name); err != nil {
+ rows.Close()
+ return nil, err
+ }
+ columns[name] = true
+ }
+ if err := rows.Close(); err != nil {
+ return nil, err
+ }
+ branch := "NULL"
+ if columns["git_branch"] {
+ branch = "git_branch"
+ }
+ out := map[string]SessionDetail{}
+ rows, err = s.db.Query(`SELECT id, model_config, ` + branch + ` FROM sessions WHERE archived = 0`)
+ if err != nil {
+ return nil, err
+ }
+ for rows.Next() {
+ var id string
+ var modelConfig, gitBranch sql.NullString
+ if err := rows.Scan(&id, &modelConfig, &gitBranch); err != nil {
+ rows.Close()
+ return nil, err
+ }
+ var config struct {
+ DelegateFrom string `json:"_delegate_from"`
+ }
+ _ = json.Unmarshal([]byte(modelConfig.String), &config)
+ out[id] = SessionDetail{Branch: strings.TrimSpace(gitBranch.String), DelegateFrom: strings.TrimSpace(config.DelegateFrom)}
+ }
+ if err := rows.Close(); err != nil {
+ return nil, err
+ }
+ rows, err = s.db.Query(`
+SELECT session_id, max(timestamp),
+ (SELECT f.content FROM messages f
+ WHERE f.session_id = m.session_id AND f.active = 1 AND f.role = 'user' AND trim(COALESCE(f.content, '')) != ''
+ ORDER BY f.id LIMIT 1)
+FROM messages m
+WHERE active = 1
+GROUP BY session_id`)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+ for rows.Next() {
+ var id string
+ var last sql.NullFloat64
+ var prompt sql.NullString
+ if err := rows.Scan(&id, &last, &prompt); err != nil {
+ return nil, err
+ }
+ detail, ok := out[id]
+ if !ok {
+ continue
+ }
+ detail.LastMessageAtMS = secondsToMillis(last)
+ detail.FirstPrompt = strings.TrimSpace(prompt.String)
+ out[id] = detail
+ }
+ return out, rows.Err()
+}
+
func (s *Store) LastMessageID(sessionID string) (int64, error) {
var last sql.NullInt64
if err := s.db.QueryRow(`SELECT max(id) FROM messages WHERE session_id = ? AND active = 1`, sessionID).Scan(&last); err != nil {
@@ -594,6 +684,11 @@ func (m *mapper) mapMessage(message Message) {
ev.Prompt = &schema.PromptInfo{Text: text}
ev.Content = asymptoteobserve.RetainedContent(text, asymptoteobserve.DefaultStringLimit)
m.append(message.ID, "prompt.submitted", ev)
+ if info, ok := asymptoteobserve.ParseHandoffMarker(text); ok {
+ link := m.base(message.TimestampMS, "session.handoff", "session", schema.SeverityInfo, "Session continued from a "+info.SourceHarness+" session")
+ link.Handoff = &info
+ m.append(message.ID, "prompt.submitted.handoff", link)
+ }
}
case "assistant":
for idx, text := range reasoningParts(message) {
diff --git a/cli/beacon/internal/hermessession/handoff_test.go b/cli/beacon/internal/hermessession/handoff_test.go
new file mode 100644
index 00000000..252f55a6
--- /dev/null
+++ b/cli/beacon/internal/hermessession/handoff_test.go
@@ -0,0 +1,73 @@
+package hermessession
+
+import (
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+func TestMapSessionRecordsAHandoffLink(t *testing.T) {
+ session := Session{ID: "new-1", Source: "cli", CWD: "/work", Model: "gpt-5", StartedAtMS: 1780632830000}
+ prompt := "Continue the work.\n\n" + asymptoteobserve.HandoffMarker("claude_code", "src-1")
+ messages := []Message{
+ {ID: 1, SessionID: "new-1", Role: "user", Content: prompt, TimestampMS: 1780632831000, Active: true},
+ {ID: 2, SessionID: "new-1", Role: "assistant", Content: "Reading the brief.", TimestampMS: 1780632832000, Active: true},
+ {ID: 3, SessionID: "new-1", Role: "user", Content: "no marker here", TimestampMS: 1780632833000, Active: true},
+ }
+ mapped, _ := MapSession(session, messages, nil)
+ 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.SourceMessageID != 1 || 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 || (link.Event.GenAI != nil && link.Event.GenAI.Input != 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(session, messages, nil)
+ 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")
+ }
+ }
+}
+
+// A database from before Hermes recorded git branches still lists, with no branch.
+func TestSessionDetailsWithoutAGitBranchColumn(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "state.db")
+ createHermesFixtureDB(t, path)
+ store, err := OpenStore(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer store.Close()
+ details, err := store.SessionDetails()
+ if err != nil {
+ t.Fatalf("SessionDetails: %v", err)
+ }
+ detail, ok := details["hermes-session-1"]
+ if !ok || detail.Branch != "" || detail.DelegateFrom != "" || detail.FirstPrompt != "run tests" || detail.LastMessageAtMS != 1780632833000 {
+ t.Fatalf("details = %+v", details)
+ }
+}
diff --git a/docs/cli/handoff.mdx b/docs/cli/handoff.mdx
index 4b458e2b..7cb7cdd0 100644
--- a/docs/cli/handoff.mdx
+++ b/docs/cli/handoff.mdx
@@ -25,10 +25,11 @@ Sessions come from each runtime's own local session store, not from Beacon's run
| 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.
## `beacon handoff list`
@@ -43,7 +44,7 @@ beacon handoff list --json
| Flag | Description |
|------|-------------|
-| `--harness` | Only this runtime: `claude`, `codex`, `opencode`, or `cline`. |
+| `--harness` | Only this runtime: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime` or `hermes`. |
| `--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. |
@@ -110,6 +111,7 @@ There are two ways to resume:
| Cline | `cline --tui --auto-approve false --id <id>` |
| Pi | `pi --session <session file>` |
| Prime Agent | `prime-agent --resume <session file>` |
+ | Hermes Agent | `hermes --resume <id>` |
- **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:
@@ -124,15 +126,19 @@ There are two ways to resume:
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, 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.
+Hermes Agent has no row in the second table: its CLI has no way to start an interactive session with a first message, only one-shot runs, so it can't continue a session from a brief. A Hermes session continues from a brief in another runtime (`--agent`), and `--agent hermes` reopens only Hermes's own sessions.
+
+Claude Code, Cline, Prime Agent and Hermes 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.
+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 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.
| Flag | Description |
|------|-------------|
-| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, `cline`, `pi` or `prime`. Defaults to the session's own runtime. |
+| `--agent` | Runtime to continue in: `claude`, `codex`, `opencode`, `cline`, `pi`, `prime` or `hermes` (its own sessions only). 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. |
@@ -163,7 +169,7 @@ The link event keeps the new session's id, workspace and harness, and leaves the
Two 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`, `cline sync`, `pi sync` and `prime 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` and `hermes 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 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.