session

type Checkpoint struct {
	// ID is the unique checkpoint identifier.
	ID string `json:"id"`
	// SessionID links to the parent session.
	SessionID string `json:"sessionId"`
	// Timestamp is when the checkpoint was created.
	Timestamp time.Time `json:"timestamp"`
	// EntryID is the session entry this checkpoint was created at.
	EntryID string `json:"entryId"`
	// Checksum verifies integrity of entries up to this checkpoint.
	Checksum string `json:"checksum"`
	// Metadata contains optional checkpoint-specific data.
	Metadata map[string]any `json:"metadata,omitempty"`
}

type CheckpointConfig struct {
	// AutoSave enables automatic checkpoint creation.
	AutoSave bool `yaml:"auto_save"`

	// Interval is the auto-save interval (e.g., "5m").
	Interval string `yaml:"interval"`
}

type CheckpointableAgent interface {
	// CreateCheckpoint captures the agent's internal state for later restoration.
	// Returns the state as a map that will be stored in the checkpoint.
	CreateCheckpoint(ctx context.Context) (map[string]any, error)

	// RestoreFromCheckpoint restores the agent's internal state from a checkpoint.
	RestoreFromCheckpoint(ctx context.Context, state map[string]any) error
}

type Config struct {
	// Enabled determines whether sessions are active.
	// Default: true (sessions are enabled by default).
	Enabled bool `yaml:"enabled"`

	// Store specifies the storage backend type.
	// Options: "file", "firestore", "postgres"
	// Default: "file"
	Store string `yaml:"store"`

	// BaseDir is the base directory for file-based storage.
	// Default: ~/.aixgo/sessions
	BaseDir string `yaml:"base_dir"`

	// Checkpoint contains checkpoint configuration.
	Checkpoint CheckpointConfig `yaml:"checkpoint,omitempty"`
}

type CreateOptions struct {
	// UserID identifies the user for this session.
	UserID string
	// Metadata contains optional session metadata.
	Metadata map[string]any
}

type EntryType string

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

type ListOptions struct {
	// UserID filters sessions by user.
	UserID string
	// Limit caps the number of results.
	Limit int
	// Offset skips the first N results.
	Offset int
}

type Manager interface {
	// Create creates a new session for an agent.
	Create(ctx context.Context, agentName string, opts CreateOptions) (Session, error)

	// Get retrieves an existing session by ID.
	// Returns ErrSessionNotFound if the session doesn't exist.
	Get(ctx context.Context, sessionID string) (Session, error)

	// GetOrCreate returns an existing session or creates a new one.
	// If userID is provided, it looks for existing sessions for that user.
	GetOrCreate(ctx context.Context, agentName, userID string) (Session, error)

	// List returns sessions for an agent matching the filter options.
	List(ctx context.Context, agentName string, opts ListOptions) ([]*SessionMetadata, error)

	// Delete removes a session and all its data.
	Delete(ctx context.Context, sessionID string) error

	// Close releases resources held by the manager.
	Close() error
}

type MemoryAwareAgent interface {
	// SetMemory provides the agent with access to long-term memory.
	// Called before execution when sessions are enabled.
	SetMemory(ctx context.Context, memory MemoryReader) error
}

type MemoryEntry struct {
	Key       string
	Value     string
	Timestamp string
	Source    string
}

type MemoryReader interface {
	// Read retrieves a value from memory by key.
	Read(ctx context.Context, key string) (string, error)

	// Search performs semantic search over memory.
	Search(ctx context.Context, query string, limit int) ([]MemoryEntry, error)

	// List returns all memory keys.
	List(ctx context.Context) ([]string, error)
}

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

type RedisConfig struct {
	// Addr is the Redis server address (host:port).
	Addr string
	// Password is the Redis password (optional).
	Password string
	// DB is the Redis database number.
	DB int
	// Prefix is the key prefix for all session keys (default: "aixgo:session:").
	Prefix string
	// SessionTTL is the session expiry duration (0 = never expire).
	SessionTTL time.Duration
	// PoolSize is the connection pool size (default: 10).
	PoolSize int
}

type Session interface {
	// ID returns the unique session identifier.
	ID() string

	// AgentName returns the name of the agent this session belongs to.
	AgentName() string

	// UserID returns the user identifier (may be empty).
	UserID() string

	// AppendMessage adds a message to the session history.
	AppendMessage(ctx context.Context, msg *agent.Message) error

	// GetMessages retrieves all messages in the session.
	GetMessages(ctx context.Context) ([]*agent.Message, error)

	// Checkpoint creates a restorable state snapshot.
	Checkpoint(ctx context.Context) (*Checkpoint, error)

	// Restore reverts the session to a previous checkpoint.
	Restore(ctx context.Context, checkpointID string) error

	// Close releases any resources held by the session.
	Close(ctx context.Context) error
}

type SessionAwareAgent interface {
	// ExecuteWithSession performs execution with access to session context.
	// The session provides access to conversation history and memory.
	ExecuteWithSession(ctx context.Context, input *agent.Message, sess Session) (*agent.Message, error)
}

type SessionEntry struct {
	// ID is the unique identifier for this entry.
	ID string `json:"id"`
	// ParentID links to the previous entry (for future branching support).
	ParentID string `json:"parentId,omitempty"`
	// Timestamp is when the entry was created.
	Timestamp time.Time `json:"timestamp"`
	// Type indicates what kind of entry this is.
	Type EntryType `json:"type"`
	// Data contains the entry payload.
	Data map[string]any `json:"data"`
}

type SessionKey struct{}

type SessionMetadata struct {
	// ID is the unique session identifier.
	ID string `json:"id"`
	// AgentName is the name of the agent this session belongs to.
	AgentName string `json:"agentName"`
	// UserID identifies the user (optional).
	UserID string `json:"userId,omitempty"`
	// CreatedAt is when the session was created.
	CreatedAt time.Time `json:"createdAt"`
	// UpdatedAt is when the session was last modified.
	UpdatedAt time.Time `json:"updatedAt"`
	// MessageCount is the number of messages in the session.
	MessageCount int `json:"messageCount"`
	// CurrentLeaf is the ID of the current leaf entry (for future branching).
	CurrentLeaf string `json:"currentLeaf,omitempty"`
}

type StorageBackend interface {
	// SaveSession creates or updates session metadata.
	SaveSession(ctx context.Context, meta *SessionMetadata) error

	// LoadSession retrieves session metadata by ID.
	// Returns ErrSessionNotFound if the session doesn't exist.
	LoadSession(ctx context.Context, sessionID string) (*SessionMetadata, error)

	// DeleteSession removes a session and all its entries.
	DeleteSession(ctx context.Context, sessionID string) error

	// ListSessions returns sessions for an agent matching the filter options.
	ListSessions(ctx context.Context, agentName string, opts ListOptions) ([]*SessionMetadata, error)

	// AppendEntry adds an entry to a session (append-only).
	AppendEntry(ctx context.Context, sessionID string, entry *SessionEntry) error

	// LoadEntries retrieves all entries for a session in order.
	LoadEntries(ctx context.Context, sessionID string) ([]*SessionEntry, error)

	// SaveCheckpoint stores a checkpoint.
	SaveCheckpoint(ctx context.Context, checkpoint *Checkpoint) error

	// LoadCheckpoint retrieves a checkpoint by ID.
	// Returns ErrCheckpointNotFound if the checkpoint doesn't exist.
	LoadCheckpoint(ctx context.Context, checkpointID string) (*Checkpoint, error)

	// Close releases any resources held by the backend.
	Close() error
}