state

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrMalformedTranscriptEntry = errors.New("malformed transcript entry")

ErrMalformedTranscriptEntry indicates a persisted transcript entry could not be decoded and the session state cannot be restored safely.

Functions

This section is empty.

Types

type Backend 

type Backend interface {
	SaveSession(sessionID types.SessionID, metadata *types.SessionMetadata) error
	LoadSession(sessionID types.SessionID) (*types.SessionMetadata, error)
	DeleteSession(sessionID types.SessionID) error
	ListSessions() ([]types.SessionID, error)
	AppendTranscriptEntries(sessionID types.SessionID, entries []types.TranscriptEntry) error
	ReplaceTranscript(sessionID types.SessionID, entries []types.TranscriptEntry) error
	LoadTranscript(sessionID types.SessionID) ([]types.TranscriptEntry, error)
	SaveCheckpoint(sessionID types.SessionID, checkpoint *Checkpoint) error
	LoadCheckpoint(sessionID types.SessionID) (*Checkpoint, error)
	// SearchTranscriptsByContent returns IDs of sessions whose transcript JSON
	// contains needle (case-insensitive). limit <= 0 means no cap.
	// This replaces the N+1 pattern of ListSessions + LoadTranscript per session.
	SearchTranscriptsByContent(needle string, limit int) ([]types.SessionID, error)
}

Backend persists session artifacts independently from the higher-level store logic so Seshat can support filesystem, in-memory, or database-backed implementations behind the same restore/save contract.

type Checkpoint 

type Checkpoint struct {
	SessionID    types.SessionID `json:"session_id"`
	TurnNumber   int             `json:"turn_number"`
	MessagesHash string          `json:"messages_hash"`
	Timestamp    int64           `json:"timestamp"`
	Metadata     map[string]any  `json:"metadata,omitempty"`
}

Checkpoint represents a session checkpoint for recovery.

type FileState 

type FileState struct {
	Path    string
	Size    int64
	ModTime int64
}

FileState represents cached file state

type FileStateCache 

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

FileStateCache provides thread-safe file state caching

func NewFileStateCache 

func NewFileStateCache() *FileStateCache

NewFileStateCache creates a new file state cache

func (*FileStateCache) Clear 

func (c *FileStateCache) Clear()

Clear removes all cached file state

func (*FileStateCache) Delete 

func (c *FileStateCache) Delete(path string)

Delete removes file state from cache

func (*FileStateCache) Get 

func (c *FileStateCache) Get(path string) (*FileState, bool)

Get retrieves cached file state

func (*FileStateCache) Set 

func (c *FileStateCache) Set(path string, state FileState)

Set stores file state in cache

type FilesystemBackend 

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

FilesystemBackend stores each session as a directory with metadata, transcript, and checkpoint files.

func NewFilesystemBackend 

func NewFilesystemBackend(baseDir string) (*FilesystemBackend, error)

NewFilesystemBackend creates the default filesystem-backed session backend.

func (*FilesystemBackend) AppendTranscriptEntries 

func (b *FilesystemBackend) AppendTranscriptEntries(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*FilesystemBackend) DeleteSession 

func (b *FilesystemBackend) DeleteSession(sessionID types.SessionID) error

func (*FilesystemBackend) ListSessions 

func (b *FilesystemBackend) ListSessions() ([]types.SessionID, error)

func (*FilesystemBackend) LoadCheckpoint 

func (b *FilesystemBackend) LoadCheckpoint(sessionID types.SessionID) (*Checkpoint, error)

func (*FilesystemBackend) LoadSession 

func (b *FilesystemBackend) LoadSession(sessionID types.SessionID) (*types.SessionMetadata, error)

func (*FilesystemBackend) LoadTranscript 

func (b *FilesystemBackend) LoadTranscript(sessionID types.SessionID) ([]types.TranscriptEntry, error)

func (*FilesystemBackend) ReplaceTranscript 

func (b *FilesystemBackend) ReplaceTranscript(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*FilesystemBackend) SaveCheckpoint 

func (b *FilesystemBackend) SaveCheckpoint(sessionID types.SessionID, checkpoint *Checkpoint) error

func (*FilesystemBackend) SaveSession 

func (b *FilesystemBackend) SaveSession(sessionID types.SessionID, metadata *types.SessionMetadata) error

func (*FilesystemBackend) SearchTranscriptsByContent 

func (b *FilesystemBackend) SearchTranscriptsByContent(needle string, limit int) ([]types.SessionID, error)

SearchTranscriptsByContent scans transcript files for needle (grep-style). This is O(sessions × file_size) but avoids full JSON deserialization.

type MemoryBackend 

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

MemoryBackend is a simple in-memory backend useful for tests and as a reference implementation for future database adapters.

func NewMemoryBackend 

func NewMemoryBackend() *MemoryBackend

func (*MemoryBackend) AppendTranscriptEntries 

func (b *MemoryBackend) AppendTranscriptEntries(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*MemoryBackend) DeleteSession 

func (b *MemoryBackend) DeleteSession(sessionID types.SessionID) error

func (*MemoryBackend) ListSessions 

func (b *MemoryBackend) ListSessions() ([]types.SessionID, error)

func (*MemoryBackend) LoadCheckpoint 

func (b *MemoryBackend) LoadCheckpoint(sessionID types.SessionID) (*Checkpoint, error)

func (*MemoryBackend) LoadSession 

func (b *MemoryBackend) LoadSession(sessionID types.SessionID) (*types.SessionMetadata, error)

func (*MemoryBackend) LoadTranscript 

func (b *MemoryBackend) LoadTranscript(sessionID types.SessionID) ([]types.TranscriptEntry, error)

func (*MemoryBackend) ReplaceTranscript 

func (b *MemoryBackend) ReplaceTranscript(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*MemoryBackend) SaveCheckpoint 

func (b *MemoryBackend) SaveCheckpoint(sessionID types.SessionID, checkpoint *Checkpoint) error

func (*MemoryBackend) SaveSession 

func (b *MemoryBackend) SaveSession(sessionID types.SessionID, metadata *types.SessionMetadata) error

func (*MemoryBackend) SearchTranscriptsByContent 

func (b *MemoryBackend) SearchTranscriptsByContent(needle string, limit int) ([]types.SessionID, error)

SearchTranscriptsByContent scans in-memory transcripts for needle.

type SQLiteBackend 

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

SQLiteBackend persists session state in a shared application database.

func NewSQLiteBackend 

func NewSQLiteBackend(database *dbpkg.DB) (*SQLiteBackend, error)

NewSQLiteBackend creates a session-state backend on top of a shared DB handle. The DB schema must already be initialized, which db.Open handles when AutoMigrate is enabled.

func OpenSQLiteBackend 

func OpenSQLiteBackend(path string) (*SQLiteBackend, error)

OpenSQLiteBackend opens a SQLite database with the shared DB module and wraps it as a session-state backend.

func (*SQLiteBackend) AppendTranscriptEntries 

func (b *SQLiteBackend) AppendTranscriptEntries(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*SQLiteBackend) Close 

func (b *SQLiteBackend) Close() error

Close releases the owned database handle.

func (*SQLiteBackend) DeleteSession 

func (b *SQLiteBackend) DeleteSession(sessionID types.SessionID) error

func (*SQLiteBackend) ListSessions 

func (b *SQLiteBackend) ListSessions() ([]types.SessionID, error)

func (*SQLiteBackend) LoadCheckpoint 

func (b *SQLiteBackend) LoadCheckpoint(sessionID types.SessionID) (*Checkpoint, error)

func (*SQLiteBackend) LoadSession 

func (b *SQLiteBackend) LoadSession(sessionID types.SessionID) (*types.SessionMetadata, error)

func (*SQLiteBackend) LoadTranscript 

func (b *SQLiteBackend) LoadTranscript(sessionID types.SessionID) ([]types.TranscriptEntry, error)

func (*SQLiteBackend) ReplaceTranscript 

func (b *SQLiteBackend) ReplaceTranscript(sessionID types.SessionID, entries []types.TranscriptEntry) error

func (*SQLiteBackend) SaveCheckpoint 

func (b *SQLiteBackend) SaveCheckpoint(sessionID types.SessionID, checkpoint *Checkpoint) error

func (*SQLiteBackend) SaveSession 

func (b *SQLiteBackend) SaveSession(sessionID types.SessionID, metadata *types.SessionMetadata) error

func (*SQLiteBackend) SearchTranscriptsByContent 

func (b *SQLiteBackend) SearchTranscriptsByContent(needle string, limit int) ([]types.SessionID, error)

SearchTranscriptsByContent returns IDs of sessions whose stored transcript JSON contains needle. Uses the session_transcript_fts FTS5 index when available (O(log n)); falls back to a LIKE full scan on older databases.

type SessionInfo 

type SessionInfo struct {
	ID          types.SessionID     `json:"id"`
	Status      types.SessionStatus `json:"status"`
	CreatedAt   int64               `json:"created_at"`
	UpdatedAt   int64               `json:"updated_at"`
	TotalTurns  int                 `json:"total_turns"`
	TotalTokens int                 `json:"total_tokens"`
	// Title is the human-readable name assigned at creation (e.g. "untitled_session_1").
	// Empty for sessions created before this field was introduced.
	Title string `json:"title,omitempty"`
	// Preview is the first user message text, truncated to ~120 runes.
	// Empty for sessions saved before this field was introduced.
	Preview string `json:"preview,omitempty"`
}

SessionInfo contains basic information about a session.

type Store 

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

Store manages session persistence

func NewStore 

func NewStore(baseDir string) (*Store, error)

NewStore creates a new session store

func NewStoreWithBackend 

func NewStoreWithBackend(backend Backend) (*Store, error)

NewStoreWithBackend creates a store using a custom backend so callers can plug alternative persistence layers such as SQL or document databases.

func (*Store) AppendTranscriptEntries 

func (s *Store) AppendTranscriptEntries(sessionID types.SessionID, entries []types.TranscriptEntry) error

AppendTranscriptEntries appends multiple transcript entries atomically.

func (*Store) AppendTranscriptEntry 

func (s *Store) AppendTranscriptEntry(sessionID types.SessionID, entry types.TranscriptEntry) error

AppendTranscriptEntry appends an entry to the transcript

func (*Store) CleanupOldSessions 

func (s *Store) CleanupOldSessions(maxAge int64) (int, error)

CleanupOldSessions removes sessions older than the specified duration

func (*Store) Close 

func (s *Store) Close() error

Close releases backend-owned resources when the configured backend supports explicit shutdown.

func (*Store) DeleteSession 

func (s *Store) DeleteSession(sessionID types.SessionID) error

DeleteSession deletes a session from disk

func (*Store) GetAllSessionsInfo 

func (s *Store) GetAllSessionsInfo() ([]*SessionInfo, error)

GetAllSessionsInfo gets information about all sessions

func (*Store) GetSessionInfo 

func (s *Store) GetSessionInfo(sessionID types.SessionID) (*SessionInfo, error)

GetSessionInfo gets basic information about a session

func (*Store) ListSessions 

func (s *Store) ListSessions() ([]types.SessionID, error)

ListSessions lists all sessions

func (*Store) LoadCanonicalMessages 

func (s *Store) LoadCanonicalMessages(sessionID types.SessionID) ([]types.Message, error)

LoadCanonicalMessages restores the canonical message list for a session.

func (*Store) LoadCheckpoint 

func (s *Store) LoadCheckpoint(sessionID types.SessionID) (*Checkpoint, error)

LoadCheckpoint loads the latest checkpoint for a session

func (*Store) LoadSession 

func (s *Store) LoadSession(sessionID types.SessionID) (*types.SessionMetadata, error)

LoadSession loads session metadata from disk

func (*Store) LoadTranscript 

func (s *Store) LoadTranscript(sessionID types.SessionID) ([]types.TranscriptEntry, error)

LoadTranscript loads the transcript for a session

func (*Store) ReplaceTranscript 

func (s *Store) ReplaceTranscript(sessionID types.SessionID, entries []types.TranscriptEntry) error

ReplaceTranscript replaces the transcript file with the provided entries.

func (*Store) RestoreSessionState 

func (s *Store) RestoreSessionState(sessionID types.SessionID) (*types.SessionMetadata, []types.Message, error)

RestoreSessionState reloads both metadata and canonical messages together so SDK/session callers do not reimplement transcript restoration piecemeal.

func (*Store) SaveCanonicalMessages 

func (s *Store) SaveCanonicalMessages(sessionID types.SessionID, messages []types.Message) error

SaveCanonicalMessages replaces the transcript with the canonical message list.

func (*Store) SaveCheckpoint 

func (s *Store) SaveCheckpoint(sessionID types.SessionID, checkpoint *Checkpoint) error

SaveCheckpoint saves a checkpoint for recovery

func (*Store) SaveSession 

func (s *Store) SaveSession(sessionID types.SessionID, metadata *types.SessionMetadata) error

SaveSession saves a session to disk

func (*Store) SaveSessionState 

func (s *Store) SaveSessionState(sessionID types.SessionID, metadata *types.SessionMetadata, previousMessages []types.Message, currentMessages []types.Message) error

SaveSessionState persists metadata and the canonical transcript together.

func (*Store) SyncTranscriptMessages 

func (s *Store) SyncTranscriptMessages(
	sessionID types.SessionID,
	previousMessages []types.Message,
	currentMessages []types.Message,
) error

SyncTranscriptMessages persists the current canonical message list. It appends only the new suffix when the previous messages are a prefix of the current messages, and falls back to a full replace when the runtime rewrote history.

func (*Store) UpdateSessionTitle 

func (s *Store) UpdateSessionTitle(sessionID types.SessionID, title string) error

UpdateSessionTitle atomically updates only the Title field of a session's persisted metadata. It is safe to call concurrently with other operations.

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.