Help us shape the future of Go! Take the 2026 Go Developer Survey

session

package
v0.69.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source 
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.

View Source 
const (
	CloneStrategyFull     = "full"
	CloneStrategyWorktree = "worktree"
)

Clone strategy constants.

View Source 
const LocalServer = "local"

LocalServer is the server name of this machine in a Ref. No entry under servers: may use it.

View Source 
const MaxNameLength = 60

MaxNameLength keeps a long title from producing an unwieldy tmux name or path.

View Source 
const MaxTagLength = 40

MaxTagLength keeps a tag short enough to show as a chip beside a session name.

View Source 
const MetaActivatedAt = "activated_at" // start of the current active lifecycle

Metadata keys for session lifecycle.

View Source 
const MetaGroup = "group" // user-assigned group for tree view grouping

Metadata keys for session organization.

View Source 
const (
	MetaWorktreeBranch = "worktree_branch" // branch name used by the git worktree
)

Metadata keys for worktree sessions.

Variables

View Source 
var (
	ErrNotFound      = errors.New("session not found")
	ErrDuplicateName = errors.New("session name already exists")
	// ErrNotActive is a session that is recycled or corrupted, so it has no
	// checkout to open a terminal in.
	ErrNotActive = errors.New("session is not active")
)

Sentinel errors for session operations.

View Source 
var ErrInvalidCloneProtocol = fmt.Errorf("not a valid CloneProtocol, try [%s]", strings.Join(_CloneProtocolNames, ", "))
View Source 
var ErrInvalidTag = errors.New("invalid tag")

ErrInvalidTag wraps every error ValidateTag returns.

Functions

func CloneProtocolNames added in v0.66.0 

func CloneProtocolNames() []string

CloneProtocolNames returns a list of possible string values of CloneProtocol.

func NameWithSuffix 

func NameWithSuffix(name, suffix string) string

NameWithSuffix appends "-suffix", shortening name to stay within MaxNameLength.

func NormalizeTags added in v0.67.0 

func NormalizeTags(tags []string) ([]string, error)

NormalizeTags trims each tag and drops empty ones and repeats. Tags compare case-insensitively, and the first spelling wins.

func ParseTags added in v0.67.0 

func ParseTags(s string) ([]string, error)

ParseTags splits a comma-separated list, as typed into an editor or a flag, and normalizes it.

func Slugify 

func Slugify(name string) string

Slugify lowercases name, folds accents, and joins the remaining letters and digits with single hyphens: "Café/Menu" -> "cafe-menu".

func ToSessionName 

func ToSessionName(raw string, fallbacks ...string) string

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 

func ValidateName(name string) error

ValidateName checks a name's length and characters, not its uniqueness.

func ValidateServerName added in v0.68.0 

func ValidateServerName(name string) error

ValidateServerName checks a name under servers:. A name is letters, digits, and _ . -, starts with a letter or digit, and is not LocalServer, so a "<server>:<id>" Ref stays one plain argument on a command line and in a hive:// link.

func ValidateTag added in v0.67.0 

func ValidateTag(tag string) error

ValidateTag checks one tag. A comma is refused because editors and command lines use it to separate tags.

Types

type CloneProtocol added in v0.66.0 

type CloneProtocol string

CloneProtocol is the transport hive uses for clone URLs it generates.

ENUM(https, ssh) 

const (
	// CloneProtocolHttps is a CloneProtocol of type https.
	CloneProtocolHttps CloneProtocol = "https"
	// CloneProtocolSsh is a CloneProtocol of type ssh.
	CloneProtocolSsh CloneProtocol = "ssh"
)

func ParseCloneProtocol added in v0.66.0 

func ParseCloneProtocol(name string) (CloneProtocol, error)

ParseCloneProtocol attempts to convert a string to a CloneProtocol.

func (*CloneProtocol) AppendText added in v0.66.0 

func (x *CloneProtocol) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (CloneProtocol) IsValid added in v0.66.0 

func (x CloneProtocol) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (CloneProtocol) MarshalText added in v0.66.0 

func (x CloneProtocol) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (CloneProtocol) String added in v0.66.0 

func (x CloneProtocol) String() string

String implements the Stringer interface.

func (*CloneProtocol) UnmarshalText added in v0.66.0 

func (x *CloneProtocol) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type Ref added in v0.68.0 

type Ref struct {
	Server string
	ID     string
}

Ref names one session among every server a client works with. A session id is unique only on its own server.

func ParseRef added in v0.68.0 

func ParseRef(s, defaultServer string) (Ref, error)

ParseRef reads "<server>:<id>", or a bare id for a session on defaultServer.

func (Ref) String added in v0.68.0 

func (r Ref) String() string

String is the form ParseRef reads. A local session prints as its bare id, so local output does not change.

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"`
	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 

func (s *Session) ActivatedAt() time.Time

ActivatedAt returns when the current active lifecycle started. Sessions from before activation tracking use UpdatedAt because reuse already refreshed it.

func (*Session) CanRecycle 

func (s *Session) CanRecycle() bool

CanRecycle returns true if the session can be marked for recycling.

func (*Session) ClearMeta 

func (s *Session) ClearMeta(key string)

ClearMeta removes a metadata key. It is a no-op when the key is absent.

func (*Session) EditTags added in v0.67.0 

func (s *Session) EditTags(add, remove []string) error

EditTags adds and then removes tags. Removing a tag the session does not carry is not an error. Only the added tags are validated, so a tag stored before validation existed can still be removed.

func (*Session) GetMeta 

func (s *Session) GetMeta(key string) string

GetMeta returns the value for the given metadata key, or empty string if not set.

func (*Session) Group 

func (s *Session) Group() string

Group returns the user-assigned group for tree view organization, or empty string if unset.

func (*Session) HasAllTags added in v0.67.0 

func (s *Session) HasAllTags(required []string) bool

HasAllTags reports whether the session carries every tag in required.

func (*Session) HasTag added in v0.67.0 

func (s *Session) HasTag(tag string) bool

HasTag reports whether the session carries tag, ignoring case.

func (*Session) InboxTopic 

func (s *Session) InboxTopic() string

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 

func (s *Session) MarkActive(now time.Time)

MarkActive starts a new active lifecycle while retaining the reusable clone.

func (*Session) MarkCorrupted 

func (s *Session) MarkCorrupted(now time.Time)

MarkCorrupted transitions the session to the corrupted state.

func (*Session) MarkRecycled 

func (s *Session) MarkRecycled(now time.Time)

MarkRecycled transitions the session to the recycled state.

func (*Session) SetGroup 

func (s *Session) SetGroup(group string)

SetGroup sets the user-assigned group for tree view organization. An empty value clears the group assignment.

func (*Session) SetMeta 

func (s *Session) SetMeta(key, value string)

SetMeta sets a metadata key-value pair, initializing the map if needed.

type State 

type State string

State represents the lifecycle state of a session. 

const (
	StateActive    State = "active"
	StateRecycled  State = "recycled"
	StateCorrupted State = "corrupted"
)

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
	// Update reads a session, applies edit, and saves the result as one
	// write that no other process can interleave with. Returns ErrNotFound
	// if not found, and edit's error unchanged.
	Update(ctx context.Context, id string, edit func(*Session) error) (Session, error)
	// Delete removes a session by ID. Returns ErrNotFound if not found.
	Delete(ctx context.Context, id string) error
	// ReplaceRecycled removes the recycled session recycledID and saves next
	// as one write, so two rows never share one clone. Returns ErrNotFound and
	// saves nothing if recycledID is gone or no longer recycled, as when
	// another create took the clone first.
	ReplaceRecycled(ctx context.Context, recycledID string, next Session) error
}

Store defines persistence operations for sessions.

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.