session

Documentation

Overview

Package session persists conversation history as append-only JSONL files with a meta sidecar carrying the summary and logical truncation offset.

Index

• type Store
  • func NewStore(dir string) (*Store, error)
  • func (s *Store) Append(key string, msg provider.Message) error
  • func (s *Store) Clear(key string) error
  • func (s *Store) Compact(key string) error
  • func (s *Store) History(key string) ([]provider.Message, error)
  • func (s *Store) LastActivity(key string) (time.Time, bool)
  • func (s *Store) List() ([]string, error)
  • func (s *Store) SetSkip(key string, skip int) error
  • func (s *Store) SetSummary(key, summary string, keepLast int) error
  • func (s *Store) SetSummaryAt(key, summary string, skip int) error
  • func (s *Store) Skip(key string) int
  • func (s *Store) Summary(key string) string
  • func (s *Store) TotalLen(key string) (int, error)

Types

type Store

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

Store is safe for concurrent use; operations on different sessions do not block each other.

func NewStore

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

func (*Store) Append

func (s *Store) Append(key string, msg provider.Message) error

Append adds one message to the session log.

func (*Store) Clear

func (s *Store) Clear(key string) error

Clear removes a session entirely.

func (*Store) Compact

func (s *Store) Compact(key string) error

Compact physically rewrites the log, moving truncated messages to the archive.

func (*Store) History

func (s *Store) History(key string) ([]provider.Message, error)

History returns the live (non-truncated) portion of the session.

func (*Store) LastActivity

func (s *Store) LastActivity(key string) (time.Time, bool)

LastActivity reports when the session was last written to, which is what tells a resumed turn how long the user has been away. It is the log file's modification time rather than a stamp on the messages: the log is append-only, so the file already carries the answer, and asking the filesystem costs nothing on a path that runs every turn.

Compaction rewrites the log in place, so it restores this time deliberately (see Compact) — otherwise housekeeping done while nobody was there would report the conversation as recent.

func (*Store) List

func (s *Store) List() ([]string, error)

List returns all session keys (sanitized form).

func (*Store) SetSkip

func (s *Store) SetSkip(key string, skip int) error

SetSkip logically truncates the first skip messages, keeping the summary.

func (*Store) SetSummary

func (s *Store) SetSummary(key, summary string, keepLast int) error

SetSummary records a summary and logically truncates all but the last keepLast messages (counted at call time).

func (*Store) SetSummaryAt

func (s *Store) SetSummaryAt(key, summary string, skip int) error

SetSummaryAt records a summary with an absolute physical skip offset. Because the log is append-only, an offset computed from an earlier snapshot stays valid even if messages were appended meanwhile — this is what compaction must use so a mid-summarize append can never shift the cut past the chosen turn-safe boundary.

func (*Store) Skip

func (s *Store) Skip(key string) int

Skip returns the current physical truncation offset.

func (*Store) Summary

func (s *Store) Summary(key string) string

Summary returns the rolling summary of truncated history.

func (*Store) TotalLen

func (s *Store) TotalLen(key string) (int, error)

TotalLen returns the physical message count (including truncated ones).