session

Documentation

Overview

Package session implements the SessionDB — persistent per-project session tracking.

Stores raw events captured by hooks during a Claude Code session, session metadata, and resume snapshots.

Index

• Constants
• func BuildResumeSnapshot(events []model.StoredEvent, opts *BuildSnapshotOpts) string
• func BuildSessionDirective(source string, events []model.StoredEvent) string
• func ExtractEvents(input model.HookInput) []model.SessionEvent
• func ExtractUserEvents(message string) []model.SessionEvent
• type BuildSnapshotOpts
• type GetEventsOpts
• type SessionDB
  • func New(dbPath string) (*SessionDB, error)
  • func (sdb *SessionDB) CleanupOldSessions(maxAgeDays int) (int, error)
  • func (sdb *SessionDB) Close()
  • func (sdb *SessionDB) DBPath() string
  • func (sdb *SessionDB) DeleteSession(sessionID string) error
  • func (sdb *SessionDB) EnsureSession(sessionID, projectDir string) error
  • func (sdb *SessionDB) EvictStaleSessions(maxAgeDays int) (int, error)
  • func (sdb *SessionDB) GetActivity(sessionID string) (*model.SessionActivity, error)
  • func (sdb *SessionDB) GetEventCount(sessionID string) (int, error)
  • func (sdb *SessionDB) GetEvents(sessionID string, opts *GetEventsOpts) ([]model.StoredEvent, error)
  • func (sdb *SessionDB) GetResume(sessionID string) (*model.ResumeRow, error)
  • func (sdb *SessionDB) GetSessionStats(sessionID string) (*model.SessionMeta, error)
  • func (sdb *SessionDB) IncrementCompactCount(sessionID string) error
  • func (sdb *SessionDB) InsertEvent(sessionID string, event model.SessionEvent, sourceHook string) error
  • func (sdb *SessionDB) MarkResumeConsumed(sessionID string) error
  • func (sdb *SessionDB) TouchActivity(sessionID, appName, projectDir string, isQuery bool) error
  • func (sdb *SessionDB) UpsertResume(sessionID, snapshot string, eventCount int) error
• type WorkspaceSessionMap
  • func NewWorkspaceSessionMap(db *SessionDB) *WorkspaceSessionMap
  • func (w *WorkspaceSessionMap) RenameSession(oldKey, newKey string) error
  • func (w *WorkspaceSessionMap) ResolveSession(workspaceKey, projectDir string) (string, error)

Constants

const (
	// MaxEventsPerSession before FIFO eviction kicks in.
	MaxEventsPerSession = 1000
	// DedupWindow is the number of recent events to check for deduplication.
	DedupWindow = 5
)

Constants matching the TypeScript implementation.

const (
	DefaultMaxBytes = 2048
	MaxActiveFiles  = 10
)

Budget constants for snapshot assembly.

Functions

func BuildResumeSnapshot

func BuildResumeSnapshot(events []model.StoredEvent, opts *BuildSnapshotOpts) string

BuildResumeSnapshot builds a resume snapshot XML string from stored session events.

Algorithm: 1. Group events by category 2. Render each section 3. Assemble by priority tier with budget trimming 4. If over maxBytes, drop lowest priority sections first

func BuildSessionDirective

func BuildSessionDirective(source string, events []model.StoredEvent) string

BuildSessionDirective builds an XML directive for compact/resume context injection. The source parameter indicates whether this is "compact", "resume", "startup", or "clear".

func ExtractEvents

func ExtractEvents(input model.HookInput) []model.SessionEvent

ExtractEvents extracts session events from a PostToolUse hook input. Returns zero or more SessionEvents. Never panics.

func ExtractUserEvents

func ExtractUserEvents(message string) []model.SessionEvent

ExtractUserEvents extracts session events from a user message. Handles: decision, role, intent, data categories.

Types

type BuildSnapshotOpts

type BuildSnapshotOpts struct {
	MaxBytes     int
	CompactCount int
}

BuildSnapshotOpts configures snapshot generation.

type GetEventsOpts

type GetEventsOpts struct {
	Type        string
	MinPriority int
	Limit       int
}

GetEventsOpts configures event retrieval.

type SessionDB

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

SessionDB manages session events, metadata, and resume snapshots in SQLite.

func New

func New(dbPath string) (*SessionDB, error)

New creates a SessionDB at the given path.

func (*SessionDB) CleanupOldSessions

func (sdb *SessionDB) CleanupOldSessions(maxAgeDays int) (int, error)

CleanupOldSessions removes sessions older than maxAgeDays. Returns the count deleted.

func (*SessionDB) Close

func (sdb *SessionDB) Close()

Close closes the database connection.

func (*SessionDB) DBPath

func (sdb *SessionDB) DBPath() string

DBPath returns the database file path.

func (*SessionDB) DeleteSession

func (sdb *SessionDB) DeleteSession(sessionID string) error

DeleteSession removes all data for a session (events, meta, resume).

func (*SessionDB) EnsureSession

func (sdb *SessionDB) EnsureSession(sessionID, projectDir string) error

EnsureSession creates a session metadata entry if it doesn't exist (idempotent).

func (*SessionDB) EvictStaleSessions

func (sdb *SessionDB) EvictStaleSessions(maxAgeDays int) (int, error)

EvictStaleSessions removes sessions (events, meta, resume, activity) that haven't been used in maxAgeDays. Returns the count evicted.

func (*SessionDB) GetActivity

func (sdb *SessionDB) GetActivity(sessionID string) (*model.SessionActivity, error)

GetActivity returns the activity row for a session.

func (*SessionDB) GetEventCount

func (sdb *SessionDB) GetEventCount(sessionID string) (int, error)

GetEventCount returns the total event count for a session.

func (*SessionDB) GetEvents

func (sdb *SessionDB) GetEvents(sessionID string, opts *GetEventsOpts) ([]model.StoredEvent, error)

GetEvents retrieves events for a session with optional filtering.

func (*SessionDB) GetResume

func (sdb *SessionDB) GetResume(sessionID string) (*model.ResumeRow, error)

GetResume retrieves the resume snapshot for a session.

func (*SessionDB) GetSessionStats

func (sdb *SessionDB) GetSessionStats(sessionID string) (*model.SessionMeta, error)

GetSessionStats returns session metadata.

func (*SessionDB) IncrementCompactCount

func (sdb *SessionDB) IncrementCompactCount(sessionID string) error

IncrementCompactCount increments the compact_count for a session.

func (*SessionDB) InsertEvent

func (sdb *SessionDB) InsertEvent(sessionID string, event model.SessionEvent, sourceHook string) error

InsertEvent inserts a session event with deduplication and FIFO eviction.

Deduplication: skips if the same type + data_hash appears in the last DedupWindow events for this session.

Eviction: if session exceeds MaxEventsPerSession, evicts the lowest-priority (then oldest) event.

func (*SessionDB) MarkResumeConsumed

func (sdb *SessionDB) MarkResumeConsumed(sessionID string) error

MarkResumeConsumed marks the resume snapshot as consumed.

func (*SessionDB) TouchActivity

func (sdb *SessionDB) TouchActivity(sessionID, appName, projectDir string, isQuery bool) error

TouchActivity records a tool call or query for the given session, updating last_used_at.

func (*SessionDB) UpsertResume

func (sdb *SessionDB) UpsertResume(sessionID, snapshot string, eventCount int) error

UpsertResume upserts a resume snapshot for a session. Resets consumed flag on update.

type WorkspaceSessionMap

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

WorkspaceSessionMap manages OpenClaw workspace-to-session mappings. It provides stable session IDs for workspace keys so that sessions persist across gateway restarts.

func NewWorkspaceSessionMap

func NewWorkspaceSessionMap(db *SessionDB) *WorkspaceSessionMap

NewWorkspaceSessionMap creates a WorkspaceSessionMap backed by the given SessionDB.

func (*WorkspaceSessionMap) RenameSession

func (w *WorkspaceSessionMap) RenameSession(oldKey, newKey string) error

RenameSession updates the workspace key for an existing mapping. This is used when a workspace is re-keyed (e.g., after gateway restart) but should continue using the same session.

func (*WorkspaceSessionMap) ResolveSession

func (w *WorkspaceSessionMap) ResolveSession(workspaceKey, projectDir string) (string, error)

ResolveSession returns a stable session ID for a workspace key. If no mapping exists, a new session ID is generated from the workspace key and project directory, and the mapping is persisted.