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

state

package
v1.11.3 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 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"`
	// Subagent is true for a session that a sub-agent or a background agent task
	// ran in, as opposed to a conversation the user opened. Such a session is not
	// something to resume from a list of conversations.
	Subagent bool `json:"subagent,omitempty"`
	// ParentID is the session that launched this one, when it was recorded. Empty
	// for a conversation, and for a sub-agent session saved before it was recorded.
	ParentID types.SessionID `json:"parent_id,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) LoadHistory added in v1.10.2 

func (s *Store) LoadHistory(sessionID types.SessionID) (archived, current []types.Message, err error)

LoadHistory restores the whole conversation of a session: the messages compactions archived, oldest first, and the canonical messages the model still sees.

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. Title is preserved from any already-persisted record rather than taken from the incoming metadata: UpdateSessionTitle is the only place in this package that ever writes a real Title, and the in-memory Session.state.Metadata a caller's snapshot comes from is never updated in place when that happens (the async auto-title flow only touches the store, by design, since a session may be closed/reloaded by the time it completes). Without this, a routine save issued after the title lands - e.g. persisting state at the end of the very turn that raced the title generation - would silently regress the title back to its stale placeholder. A session with no existing record yet (first save, at creation) keeps whatever Title the caller supplied.

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) SearchTranscriptsByContent 

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

SearchTranscriptsByContent returns session IDs whose transcript contains needle.

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.