Documentation
¶
Overview ¶
Package session defines session domain types and interfaces. Active session names are unique by slug, which identifies their tmux session and clone directory.
Index ¶
- Constants
- Variables
- func NameWithSuffix(name, suffix string) string
- func Slugify(name string) string
- func ToSessionName(raw string, fallbacks ...string) string
- func ValidateName(name string) error
- type Session
- func (s *Session) ActivatedAt() time.Time
- func (s *Session) CanRecycle() bool
- func (s *Session) ClearMeta(key string)
- func (s *Session) GetMeta(key string) string
- func (s *Session) Group() string
- func (s *Session) InboxTopic() string
- func (s *Session) MarkActive(now time.Time)
- func (s *Session) MarkCorrupted(now time.Time)
- func (s *Session) MarkRecycled(now time.Time)
- func (s *Session) SetGroup(group string)
- func (s *Session) SetMeta(key, value string)
- type State
- type Store
Constants ¶
const ( MetaTmuxSession = "tmux_session" // tmux session name // DiscoverSession reads legacy "tmux_pane" metadata as a fallback so sessions // persisted before the tmux_window rename remain discoverable; the fallback can // be dropped after one release cycle. MetaTmuxWindow = "tmux_window" )
Metadata keys for terminal integration.
const ( CloneStrategyFull = "full" CloneStrategyWorktree = "worktree" )
Clone strategy constants.
const MaxNameLength = 60
MaxNameLength keeps a long title from producing an unwieldy tmux name or path.
const MetaActivatedAt = "activated_at" // start of the current active lifecycle
Metadata keys for session lifecycle.
const MetaGroup = "group" // user-assigned group for tree view grouping
Metadata keys for session organization.
const (
MetaWorktreeBranch = "worktree_branch" // branch name used by the git worktree
)
Metadata keys for worktree sessions.
Variables ¶
var ( ErrNotFound = errors.New("session not found") ErrDuplicateName = errors.New("session name already exists") )
Sentinel errors for session operations.
Functions ¶
func NameWithSuffix ¶
NameWithSuffix appends "-suffix", shortening name to stay within MaxNameLength.
func Slugify ¶
Slugify lowercases name, folds accents, and joins the remaining letters and digits with single hyphens: "Café/Menu" -> "cafe-menu".
func ToSessionName ¶
ToSessionName turns generated text into a valid, length-capped slug, trying each fallback when raw has no letters or digits. It returns "" if none does.
func ValidateName ¶
ValidateName checks a name's length and characters, not its uniqueness.
Types ¶
type Session ¶
type Session struct {
ID string `json:"id"`
Name string `json:"name"`
Slug string `json:"slug"`
Path string `json:"path"`
Remote string `json:"remote"`
State State `json:"state"`
CloneStrategy string `json:"clone_strategy,omitempty"` // "full" (default) or "worktree"
Tags []string `json:"tags,omitempty"` // user-defined labels for external provider tracking
Metadata map[string]string `json:"metadata,omitempty"` // integration data (e.g., tmux session name)
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Session represents an isolated git environment for an AI agent.
Terminology:
- Session: The hive-managed git clone + terminal environment
- Agent: The AI tool (Claude, Aider, etc.) running within the session
- Tmux session: The terminal multiplexer session (if tmux integration enabled)
Relationship: Hive Session → spawns → Tmux Session → runs → Agent
Future: Hive will support multiple agents per session, enabling concurrent agents like a primary assistant and a test runner.
func (*Session) ActivatedAt ¶ added in v0.61.0
ActivatedAt returns when the current active lifecycle started. Sessions from before activation tracking use UpdatedAt because reuse already refreshed it.
func (*Session) CanRecycle ¶
CanRecycle returns true if the session can be marked for recycling.
func (*Session) GetMeta ¶
GetMeta returns the value for the given metadata key, or empty string if not set.
func (*Session) Group ¶
Group returns the user-assigned group for tree view organization, or empty string if unset.
func (*Session) InboxTopic ¶
InboxTopic returns the conventional inbox topic name for this session.
Format: agent.<session-id>.inbox
The "agent" prefix refers to the AI agent running in the session. When multi-agent support is added, named agents will use: agent.<session-id>.<agent-name>.inbox
Example: agent.26kj0c.inbox
func (*Session) MarkActive ¶ added in v0.61.0
MarkActive starts a new active lifecycle while retaining the reusable clone.
func (*Session) MarkCorrupted ¶
MarkCorrupted transitions the session to the corrupted state.
func (*Session) MarkRecycled ¶
MarkRecycled transitions the session to the recycled state.
type Store ¶
type Store interface {
// List returns all sessions.
List(ctx context.Context) ([]Session, error)
// Get returns a session by ID. Returns ErrNotFound if not found.
Get(ctx context.Context, id string) (Session, error)
// Save creates or updates a session.
Save(ctx context.Context, s Session) error
// Delete removes a session by ID. Returns ErrNotFound if not found.
Delete(ctx context.Context, id string) error
}
Store defines persistence operations for sessions.
Source Files