session

package
v0.1.25 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultAgent = "hermes"

DefaultAgent is the registry key used when a session row has no agent field set. Exposed as a constant so cmd/* code branching on the default doesn't drift from the migration / Save / NormalizeAgent codepaths.

Note on the legacy "claude" remap: Save and NormalizeAgent map legacy "claude" values to "codex" (the v2→v3 migration target) — not DefaultAgent — so changing the default later doesn't silently move historical claude sessions onto whatever the current default happens to be.

View Source 
const SchemaVersion = 3

SchemaVersion is the current on-disk schema version of sessions.json. Bump this and append a Step to the Plan returned by MigrationPlan() whenever the shape of diskData or Session changes in a non-additive way.

v3: codex is the only supported agent. Any v2 rows with agent="claude" are migrated to agent="codex" — the claude implementation has been removed and continuing to reference it would fail at agent.For lookup.

Variables

This section is empty.

Functions

func MigrationPlan 

func MigrationPlan() migrate.Plan

MigrationPlan returns the migrate.Plan for sessions.json.

  • v0 → v1: stamp only (initial schema_version introduction).
  • v1 → v2: backfill agent="claude" on rows missing the field (historical — claude was the only agent at the time).
  • v2 → v3: rewrite any agent="claude" rows to agent="codex" after claude support was removed.

func SanitizeName 

func SanitizeName(name string) string

SanitizeName converts a string into a valid session name by replacing invalid characters with dashes and trimming.

func ValidateName 

func ValidateName(name string) error

ValidateName returns an error if name is not a valid session name.

Types

type AgentSessionStamper added in v0.1.22 

type AgentSessionStamper interface {
	UpdateAgentSessionID(name, id string) error
}

AgentSessionStamper persists a discovered agent-side session/thread identifier onto the named session row. *Store satisfies this via UpdateAgentSessionID. The Saver/Stamper split keeps tests honest — fakes can satisfy Saver alone and skip the discovery write path.

type Saver added in v0.1.2 

type Saver interface {
	Save(sess *Session) error
}

Saver is the narrow slice of *Store Yolo needs.

type Session 

type Session struct {
	Name             string    `json:"name"`
	UUID             string    `json:"uuid"`
	Mode             string    `json:"mode"`
	Workdir          string    `json:"workdir"`
	CreatedAt        time.Time `json:"created_at"`
	LastAttachedAt   time.Time `json:"last_attached_at,omitempty"`
	LastHealthStatus string    `json:"last_health_status,omitempty"`
	LastHealthAt     time.Time `json:"last_health_at,omitempty"`

	// Agent identifies the CLI driving this session. Set at creation
	// and never mutated. Empty value on read = legacy → normalized to
	// "claude" by Save and NormalizeAgent. Migration v1→v2 backfills
	// the on-disk value.
	Agent string `json:"agent,omitempty"`

	// AgentSessionID is the agent-backend session/thread identifier.
	// For claude this equals UUID (`claude --session-id <uuid>`). For
	// codex it is the thread UUID discovered post-spawn from the
	// rollout file; empty until the first discovery succeeds.
	AgentSessionID string `json:"agent_session_id,omitempty"`
}

Session holds metadata for a managed tmux session.

func New 

func New(name, workdir, mode string) *Session

New creates a new Session with a generated UUID and current timestamp.

func Yolo added in v0.1.2 

func Yolo(opts SpawnOpts) (Session, error)

Yolo creates a detached tmux session, launches the configured agent in yolo mode, and persists the session state. Returns the populated Session.

Preconditions:

  • Workdir must be absolute
  • Workdir must exist and be a directory
  • Agent (or DefaultAgent on empty) must be registered

Postconditions on success: tmux session exists detached, the agent is launched inside it, Store.Save has been called with mode="yolo". On error before Save: NO session state is persisted.

func (*Session) NormalizeAgent added in v0.1.22 

func (s *Session) NormalizeAgent() string

NormalizeAgent returns DefaultAgent when s.Agent is empty, else s.Agent verbatim. Cheap idempotent guard used by read paths that handle pre-migration in-memory values without touching disk.

Legacy "claude" values that escaped the v2→v3 migration are remapped to "codex" (the on-disk migration target) — not DefaultAgent — so a stale in-memory Session never surfaces as an agent.For miss at the call site, and changing DefaultAgent doesn't silently move historical claude sessions.

type SpawnOpts added in v0.1.2 

type SpawnOpts struct {
	Name        string
	Agent       string
	Workdir     string
	Tmux        TmuxSpawner
	Store       Saver
	OverlayPath string
	EnvExports  string

	// OnDiscoveryComplete fires when the background DiscoverSessionID
	// goroutine returns (success, timeout, or no stamper). Optional —
	// production callers leave it nil. Tests pass a chan-close func to
	// synchronize on completion before asserting on AgentSessionID.
	OnDiscoveryComplete func()
}

SpawnOpts bundles the tmux client and store so Yolo can be driven from either CLI or daemon without depending on config globals.

Agent selects the registered agent.Agent driving the pane. Empty is normalized to DefaultAgent (codex) by the call below.

EnvExports is a pre-built shell-export prelude produced by the caller (e.g. config.CodexEnvExports). Empty when no env file is present.

OverlayPath is currently unused by the codex agent; the field is retained as part of agent.SpawnSpec so a future agent that wants a settings overlay can wire it through.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store manages session persistence via a JSON file with flock-based locking.

func NewStore 

func NewStore(path string) *Store

NewStore creates a Store for the given file path.

func (*Store) Backup 

func (s *Store) Backup() (string, error)

Backup copies sessions.json to sessions.json.bak.<timestamp> and returns the backup path. It acquires the store lock for the duration of the read.

func (*Store) Delete 

func (s *Store) Delete(name string) error

Delete removes a session by name.

func (*Store) DeleteAll 

func (s *Store) DeleteAll() error

DeleteAll removes all sessions. It automatically creates a backup first so the user can recover from an accidental killall.

func (*Store) Get 

func (s *Store) Get(name string) (*Session, error)

Get retrieves a session by name, returning an error if not found.

func (*Store) List 

func (s *Store) List() ([]*Session, error)

List returns all sessions.

func (*Store) Names 

func (s *Store) Names() ([]string, error)

Names returns all session names (useful for completions).

func (*Store) Rename 

func (s *Store) Rename(oldName, newName string) error

Rename renames a session from oldName to newName.

func (*Store) Save 

func (s *Store) Save(sess *Session) error

Save adds or updates a session. Empty sess.Agent is normalized to DefaultAgent. Legacy "claude" values are rewritten to "codex" (the v2→v3 migration target) — not DefaultAgent — so changing the default later doesn't silently retarget historical claude sessions. A stray "claude" row would otherwise fail at spawn-time agent.For lookup.

func (*Store) UpdateAgentSessionID added in v0.1.22 

func (s *Store) UpdateAgentSessionID(name, id string) error

UpdateAgentSessionID stamps the agent-backend thread/session identifier on the named session. Idempotent — supplying the same id twice is a no-op on disk apart from the rewrite. Returns the "not found" error if name has no store entry.

func (*Store) UpdateAttached 

func (s *Store) UpdateAttached(name string) error

UpdateAttached updates the last attached timestamp of a session.

func (*Store) UpdateHealth 

func (s *Store) UpdateHealth(name, status string) error

UpdateHealth updates the health status and timestamp of a session.

func (*Store) UpdateMode 

func (s *Store) UpdateMode(name, mode string) error

UpdateMode changes the mode of a session.

type TmuxSpawner added in v0.1.2 

type TmuxSpawner interface {
	NewSession(name, workdir, shellCmd string) error
	SendKeys(target, keys string) error
	KillSession(name string) error
}

TmuxSpawner is the narrow slice of *tmux.Client Yolo needs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.