session

package
v1.1.65 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentVersion = 3

Variables

This section is empty.

Functions

func ApplyMigrations 

func ApplyMigrations(db *sql.DB) error

ApplyMigrations runs any pending migrations in order. Already-applied migrations are skipped based on the schema_migrations table. It is safe to call on every DB open — it is a no-op if all migrations are applied.

func DeleteSession 

func DeleteSession(path string, sessionDir string) error

DeleteSession deletes a session file if it is under sessionDir.

func GenerateID 

func GenerateID() string

GenerateID generates a random 8-character hex ID.

func OpenRootDB added in v1.1.61 

func OpenRootDB(sessionDir string) (*sql.DB, error)

OpenRootDB opens the shared sessions.db for a session root directory and applies all pending migrations.

func SaveSessionCapabilities added in v1.1.61 

func SaveSessionCapabilities(sessionDir string, caps SessionCapabilities) error

SaveSessionCapabilities persists per-session runtime capability state.

func SaveSessionCapabilityEvent added in v1.1.61 

func SaveSessionCapabilityEvent(sessionDir string, ev SessionCapabilityEvent) (string, error)

SaveSessionCapabilityEvent appends a capability transition event to the independent event table.

func SaveSessionRunEvent added in v1.1.61 

func SaveSessionRunEvent(sessionDir string, ev SessionRunEvent) (string, error)

SaveSessionRunEvent appends a run lifecycle event to the independent run event table.

Types

type BranchSummaryEntry 

type BranchSummaryEntry struct {
	EntryBase
	Summary string `json:"summary"`
	FromID  string `json:"fromId"`
}

BranchSummaryEntry records a branch switch summary.

type CompactionEntry 

type CompactionEntry struct {
	EntryBase
	Summary              string `json:"summary"`
	FirstKeptEntry       string `json:"firstKeptEntryId"`
	TokensBefore         int    `json:"tokensBefore"`
	SummaryVersion       int    `json:"summaryVersion,omitempty"`
	PreviousCompactionID string `json:"previousCompactionId,omitempty"`
	LastSummarizedEntry  string `json:"lastSummarizedEntryId,omitempty"`
}

CompactionEntry records a context compaction.

type EntryBase 

type EntryBase struct {
	Type      EntryType `json:"type"`
	ID        string    `json:"id"`
	ParentID  *string   `json:"parentId"`
	Timestamp time.Time `json:"timestamp"`
}

EntryBase contains common fields for all session entries.

type EntryType 

type EntryType string

EntryType identifies the type of a session entry. 

const (
	EntrySession        EntryType = "session"
	EntryMessage        EntryType = "message"
	EntryModelChange    EntryType = "model_change"
	EntryThinkingChange EntryType = "thinking_level_change"
	EntryCompaction     EntryType = "compaction"
	EntryBranchSummary  EntryType = "branch_summary"
	EntryCustom         EntryType = "custom"
	EntryCustomMessage  EntryType = "custom_message"
	EntryLabel          EntryType = "label"
	EntrySessionInfo    EntryType = "session_info"
)
type Header struct {
	Type          EntryType `json:"type"`
	Version       int       `json:"version"`
	ID            string    `json:"id"`
	Timestamp     time.Time `json:"timestamp"`
	Cwd           string    `json:"cwd"`
	ParentSession string    `json:"parentSession,omitempty"`
}

Header is the first line of a session file.

type LabelEntry 

type LabelEntry struct {
	EntryBase
	TargetID string  `json:"targetId"`
	Label    *string `json:"label,omitempty"`
}

LabelEntry records a user-defined label on an entry.

type Manager 

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

Manager manages a single session's state and persistence.

func ContinueRecent 

func ContinueRecent(cwd, sessionDir string) (*Manager, error)

ContinueRecent continues the most recent session for a directory, or creates new.

func New 

func New(cwd, sessionDir string) *Manager

New creates a new session manager for a new session.

func NewSubAgent added in v1.1.62 

func NewSubAgent(cwd, sessionDir string) *Manager

NewSubAgent creates a session manager whose records are stored separately from user-continuable sessions.

func Open 

func Open(path string) (*Manager, error)

Open opens an existing session file.

func OpenByID 

func OpenByID(cwd, sessionDir, sessionID string) (*Manager, error)

OpenByID opens the session for cwd whose session ID matches sessionID. Supports prefix matching — if sessionID matches multiple sessions, an error is returned.

func OpenByIDExact 

func OpenByIDExact(sessionDir, sessionID string) (*Manager, error)

OpenByIDExact opens a session by exact session ID regardless of cwd.

func OpenByPathOrID 

func OpenByPathOrID(cwd, sessionDir, value string) (*Manager, error)

OpenByPathOrID opens a session using either an explicit file path or a session ID for the supplied working directory.

func (*Manager) AppendCompaction 

func (m *Manager) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

AppendCompaction records a context compaction.

func (*Manager) AppendMessage 

func (m *Manager) AppendMessage(msg provider.Message) (string, error)

AppendMessage adds a message entry.

func (*Manager) AppendModelChange 

func (m *Manager) AppendModelChange(providerName, modelID string) (string, error)

AppendModelChange records a model change.

func (*Manager) AppendSessionInfo 

func (m *Manager) AppendSessionInfo(name string) (string, error)

AppendSessionInfo records session metadata (e.g. display name).

func (*Manager) AppendThinkingLevelChange 

func (m *Manager) AppendThinkingLevelChange(level string) (string, error)

AppendThinkingLevelChange records a thinking level change.

func (*Manager) GetFile 

func (m *Manager) GetFile() string

GetFile returns the session file path.

func (*Manager) GetHeader 

func (m *Manager) GetHeader() *Header

GetHeader returns the session header.

func (*Manager) GetLatestCompaction 

func (m *Manager) GetLatestCompaction() (CompactionEntry, bool)

GetLatestCompaction returns the newest compaction entry in the current session.

func (*Manager) GetLeafID 

func (m *Manager) GetLeafID() *string

GetLeafID returns the current leaf entry ID.

func (*Manager) GetMessages 

func (m *Manager) GetMessages() []provider.Message

GetMessages extracts all messages from the current branch.

func (*Manager) GetReplayState 

func (m *Manager) GetReplayState() ReplayState

GetReplayState returns the current branch after applying compaction entries.

func (*Manager) Init 

func (m *Manager) Init() error

Init initializes a new session with an auto-generated session ID. Must be called before appending entries.

func (*Manager) InitWithID 

func (m *Manager) InitWithID(id string) error

InitWithID initializes a new session using the provided session ID. If id is empty, a new random ID is generated.

func (*Manager) RecordUsage 

func (m *Manager) RecordUsage(provider, protocol, model string, inputTokens, outputTokens, totalTokens, durationMs int) error

RecordUsage records a single LLM request's token usage and timing.

func (*Manager) RecordUsageFromProviderUsage 

func (m *Manager) RecordUsageFromProviderUsage(provider, protocol, model string, usage *provider.Usage, durationMs int) error

RecordUsageFromProviderUsage records usage from a provider.Usage struct.

type MemoryStore 

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

MemoryStore is an in-memory implementation of Store for testing. It does not persist data to disk.

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new in-memory session store.

func (*MemoryStore) AppendCompaction 

func (m *MemoryStore) AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

func (*MemoryStore) AppendMessage 

func (m *MemoryStore) AppendMessage(msg provider.Message) (string, error)

func (*MemoryStore) AppendModelChange 

func (m *MemoryStore) AppendModelChange(providerName, modelID string) (string, error)

func (*MemoryStore) AppendSessionInfo 

func (m *MemoryStore) AppendSessionInfo(name string) (string, error)

func (*MemoryStore) AppendThinkingLevelChange 

func (m *MemoryStore) AppendThinkingLevelChange(level string) (string, error)

func (*MemoryStore) GetFile 

func (m *MemoryStore) GetFile() string

func (*MemoryStore) GetHeader 

func (m *MemoryStore) GetHeader() *Header

func (*MemoryStore) GetLatestCompaction 

func (m *MemoryStore) GetLatestCompaction() (CompactionEntry, bool)

func (*MemoryStore) GetLeafID 

func (m *MemoryStore) GetLeafID() *string

func (*MemoryStore) GetMessages 

func (m *MemoryStore) GetMessages() []provider.Message

func (*MemoryStore) GetReplayState 

func (m *MemoryStore) GetReplayState() ReplayState

func (*MemoryStore) Init 

func (m *MemoryStore) Init() error

func (*MemoryStore) InitWithID 

func (m *MemoryStore) InitWithID(id string) error

type MessageEntry 

type MessageEntry struct {
	EntryBase
	Message provider.Message `json:"message"`
}

MessageEntry contains a conversation message.

type ModelChangeEntry 

type ModelChangeEntry struct {
	EntryBase
	Provider string `json:"provider"`
	ModelID  string `json:"modelId"`
}

ModelChangeEntry records a model switch.

type ReplayState 

type ReplayState struct {
	Messages []provider.Message
	EntryIDs []string
}

ReplayState is the reconstructed conversation state after applying compactions.

type SequencedMessage added in v1.1.61 

type SequencedMessage struct {
	Seq     int64
	EntryID string
	Message provider.Message
}

SequencedMessage is a persisted conversation message with its entries.seq cursor.

func ListSessionMessagesAfter added in v1.1.61 

func ListSessionMessagesAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedMessage, error)

ListSessionMessagesAfter returns persisted message rows after entries.seq.

func ListSessionMessagesWithSeq added in v1.1.61 

func ListSessionMessagesWithSeq(sessionDir, sessionID string) ([]SequencedMessage, error)

ListSessionMessagesWithSeq returns the visible replay messages for a session, preserving each message row's entries.seq cursor.

type SequencedSessionCapabilityEvent added in v1.1.61 

type SequencedSessionCapabilityEvent struct {
	Seq   int64
	Event SessionCapabilityEvent
}

SequencedSessionCapabilityEvent is a capability event with its table cursor.

func ListSessionCapabilityEventsAfter added in v1.1.61 

func ListSessionCapabilityEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsAfter returns capability events after session_capability_events.seq.

func ListSessionCapabilityEventsWithSeq added in v1.1.61 

func ListSessionCapabilityEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionCapabilityEvent, error)

ListSessionCapabilityEventsWithSeq returns capability events with their seq cursor.

type SequencedSessionRunEvent added in v1.1.61 

type SequencedSessionRunEvent struct {
	Seq   int64
	Event SessionRunEvent
}

SequencedSessionRunEvent is a run lifecycle event with its table cursor.

func ListSessionRunEventsAfter added in v1.1.61 

func ListSessionRunEventsAfter(sessionDir, sessionID string, afterSeq int64, limit int) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsAfter returns run events after session_run_events.seq.

func ListSessionRunEventsWithSeq added in v1.1.61 

func ListSessionRunEventsWithSeq(sessionDir, sessionID string) ([]SequencedSessionRunEvent, error)

ListSessionRunEventsWithSeq returns run events with their session_run_events.seq cursor.

type SessionCapabilities added in v1.1.61 

type SessionCapabilities struct {
	SessionID    string
	Mode         string
	DelegateMode bool
	MultiAgent   bool
	Workflows    bool
	WebSearch    bool
	Browser      bool
	A2AMaster    bool
	UpdatedAt    time.Time
}

SessionCapabilities stores persisted per-session runtime capability state.

func LoadSessionCapabilities added in v1.1.61 

func LoadSessionCapabilities(sessionDir, sessionID string) (*SessionCapabilities, bool, error)

LoadSessionCapabilities loads persisted capabilities for a session.

type SessionCapabilityEvent added in v1.1.61 

type SessionCapabilityEvent struct {
	ID         string
	SessionID  string
	RunID      string
	EventType  string
	Source     string
	Actor      string
	Capability string
	OldValue   string
	NewValue   string
	Timestamp  time.Time
	Data       json.RawMessage
}

SessionCapabilityEvent records one capability state transition.

func ListSessionCapabilityEvents added in v1.1.61 

func ListSessionCapabilityEvents(sessionDir, sessionID string) ([]SessionCapabilityEvent, error)

ListSessionCapabilityEvents returns capability events for a session, ordered by insertion.

type SessionDetail 

type SessionDetail struct {
	SessionInfo
	ID           string
	MessageCount int
	Preview      string // first user message (truncated)
}

SessionDetail contains detailed metadata about a session for display.

func ListAllDetailed added in v1.1.61 

func ListAllDetailed(sessionDir string) ([]SessionDetail, error)

ListAllDetailed lists sessions with details across all working directories.

func ListForDirDetailed 

func ListForDirDetailed(cwd, sessionDir string) ([]SessionDetail, error)

ListForDirDetailed lists sessions with details (ID, message count, preview).

type SessionInfo 

type SessionInfo struct {
	Path    string
	ModTime time.Time
	Name    string
	Cwd     string
}

SessionInfo contains metadata about a session file.

func ListAll added in v1.1.61 

func ListAll(sessionDir string) ([]SessionInfo, error)

ListAll lists session files across all working directories.

func ListForDir 

func ListForDir(cwd, sessionDir string) ([]SessionInfo, error)

ListForDir lists session files for a given working directory.

type SessionInfoEntry 

type SessionInfoEntry struct {
	EntryBase
	Name string `json:"name"`
}

SessionInfoEntry stores session metadata.

type SessionRunEvent added in v1.1.61 

type SessionRunEvent struct {
	ID        string
	SessionID string
	RunID     string
	EventType string
	Source    string
	Status    string
	Model     string
	Mode      string
	Timestamp time.Time
	Data      json.RawMessage
}

SessionRunEvent records one lifecycle event for a single chat/run execution.

func ListSessionRunEvents added in v1.1.61 

func ListSessionRunEvents(sessionDir, sessionID string) ([]SessionRunEvent, error)

ListSessionRunEvents returns run events for a session, ordered by insertion.

type Store 

type Store interface {
	// Init initializes the session store, creating the underlying
	// database or storage if needed.
	Init() error

	// InitWithID initializes the session with a specific ID.
	// An empty id generates a new one.
	InitWithID(id string) error

	// AppendMessage persists a conversation message and returns its entry ID.
	AppendMessage(msg provider.Message) (string, error)

	// AppendCompaction records a context compaction event.
	AppendCompaction(summary, firstKeptEntryID string, tokensBefore int) (string, error)

	// AppendModelChange records a model switch.
	AppendModelChange(providerName, modelID string) (string, error)

	// AppendThinkingLevelChange records a thinking level change.
	AppendThinkingLevelChange(level string) (string, error)

	// AppendSessionInfo records session metadata.
	AppendSessionInfo(name string) (string, error)

	// GetMessages returns all messages in the current branch,
	// with compaction summaries applied.
	GetMessages() []provider.Message

	// GetReplayState returns the full replay state including
	// messages and their entry IDs.
	GetReplayState() ReplayState

	// GetLeafID returns the current leaf entry ID, or nil if empty.
	GetLeafID() *string

	// GetLatestCompaction returns the most recent compaction entry,
	// or (zero, false) if none exists.
	GetLatestCompaction() (CompactionEntry, bool)

	// GetFile returns the session file path (handle file for SQLite).
	GetFile() string

	// GetHeader returns the session header with metadata.
	GetHeader() *Header
}

Store is the interface for session persistence backends. Manager implements this interface using SQLite. Alternative backends (in-memory for testing, cloud storage, etc.) can implement Store to swap the persistence layer without changing agent or UI code.

type ThinkingLevelChangeEntry 

type ThinkingLevelChangeEntry struct {
	EntryBase
	ThinkingLevel string `json:"thinkingLevel"`
}

ThinkingLevelChangeEntry records a thinking level change.

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.