Documentation
¶
Overview ¶
Package session stores agent conversations and per-session state.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrConflict = errors.New("session was modified concurrently")
ErrConflict is returned by Save when the stored session changed since the session being saved was loaded or last saved, for example by another Runner or process, or when GetOrCreate made a session that another writer created in the meantime. Load the session again and reapply the change.
MemoryStore detects conflicts for the sessions it returns from Get, sessions made by GetOrCreate and sessions it has saved before. Saving any other Session overwrites the stored one. Stores in other packages do the same with Loaded, ExpectedRevision and MarkSaved.
var ErrNotFound = errors.New("session not found")
ErrNotFound is returned when a session does not exist.
Functions ¶
func ExpectedRevision ¶
ExpectedRevision reports the stored revision a Store must find to save s without ErrConflict. ok is false for sessions not loaded or saved by a store, such as those from New or FromSnapshot, which overwrite the stored session. rev is -1 for a session GetOrCreate made, which conflicts with any stored session. When the session is not stored at all, for example because it was deleted, it is saved whatever rev is, as revision max(rev, 0)+1 so that copies loaded before the deletion conflict.
Types ¶
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore keeps sessions in process memory as JSON snapshots, with the state representation and session IDs of a persistent store. Later changes to a session are visible only after Save, which returns ErrConflict for concurrent modification. The zero value is ready to use.
func (*MemoryStore) Delete ¶
func (s *MemoryStore) Delete(_ context.Context, id string) error
Delete implements Store.
type Session ¶
type Session interface {
ID() string
// Messages returns a copy of the conversation. Values within message
// metadata may remain shared, as in model.Message.Clone.
Messages() []*model.Message
// Append adds messages to the conversation.
Append(msgs ...*model.Message)
// Replace swaps the whole conversation, for example after compaction.
Replace(msgs []*model.Message)
// State holds arbitrary per-session values.
State() *State
CreatedAt() time.Time
UpdatedAt() time.Time
}
Session is a conversation with an agent.
Implementations must be safe for concurrent use.
func FromSnapshot ¶
FromSnapshot builds an in-memory session from a snapshot. It copies the messages and state map; state values and message metadata values remain shared.
func GetOrCreate ¶
GetOrCreate loads a session, creating an empty one if it does not exist. The boolean reports whether the session was created.
type Snapshot ¶
type Snapshot struct {
ID string `json:"id"`
Messages []*model.Message `json:"messages"`
State map[string]any `json:"state,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
// Revision counts the saves of the session in its store. Stores use it
// to detect concurrent modification; see ErrConflict.
Revision int64 `json:"revision,omitempty"`
}
Snapshot is the serializable form of a session.
func TakeSnapshot ¶
TakeSnapshot captures a session through separate accessor calls. Callers must prevent concurrent changes if they need a consistent snapshot. State values and message metadata values remain shared.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State is a key-value map whose operations are safe for concurrent use. Values are stored and returned without copying; callers must treat mutable values as immutable or synchronize access to them. Values should be JSON serializable when the session is persisted.
func (*State) Decode ¶
Decode unmarshals the value for key into dst, converting through JSON. This recovers typed values from sessions loaded from disk.
type Store ¶
type Store interface {
// Get loads a session or returns ErrNotFound.
Get(ctx context.Context, id string) (Session, error)
Save(ctx context.Context, s Session) error
Delete(ctx context.Context, id string) error
// List returns sessions, most recently updated first.
List(ctx context.Context) ([]Info, error)
}
Store persists sessions. Session IDs are 1 to 128 ASCII letters, digits, '_', '-' and '.', not starting with '.'; the built-in stores reject others.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package sessiontest checks session.Store implementations against the contract the built-in stores follow.
|
Package sessiontest checks session.Store implementations against the contract the built-in stores follow. |