session

Documentation

Overview

Package session provides session management for Hector v2.

Sessions represent a series of interactions between a user and agents. Each session has:

• A unique identifier
• Associated app and user
• State (key-value store with scope prefixes)
• Event history

Index

• Constants
• Variables
• type CreateRequest
• type CreateResponse
• type DeleteRequest
• type GetRequest
• type GetResponse
• type ListRequest
• type ListResponse
• type SQLSessionService
  • func NewSQLSessionService(db *sql.DB, dialect string) (*SQLSessionService, error)
  • func (s *SQLSessionService) AppendEvent(ctx context.Context, session Session, event *agent.Event) error
  • func (s *SQLSessionService) Close() error
  • func (s *SQLSessionService) Create(ctx context.Context, req *CreateRequest) (*CreateResponse, error)
  • func (s *SQLSessionService) Delete(ctx context.Context, req *DeleteRequest) error
  • func (s *SQLSessionService) Get(ctx context.Context, req *GetRequest) (*GetResponse, error)
  • func (s *SQLSessionService) List(ctx context.Context, req *ListRequest) (*ListResponse, error)
• type Service
  • func InMemoryService() Service
  • func NewSessionServiceFromConfig(cfg *config.Config, pool *config.DBPool) (Service, error)
• type Session

Constants

const (
	// KeyPrefixApp is for app-level state (shared across all users/sessions).
	KeyPrefixApp = "app:"

	// KeyPrefixUser is for user-level state (shared across sessions for a user).
	KeyPrefixUser = "user:"

	// KeyPrefixTemp is for temporary state (discarded after invocation).
	KeyPrefixTemp = "temp:"
)

State prefixes for scoping state keys.

Variables

var ErrSessionNotFound = errors.New("session not found")

ErrSessionNotFound is returned when a session doesn't exist.

var ErrStaleSession = fmt.Errorf("stale session: session has been modified since it was loaded")

ErrStaleSession is returned when attempting to modify a session that has been updated elsewhere since it was loaded.

var ErrStateKeyNotExist = errors.New("state key does not exist")

ErrStateKeyNotExist is returned when a state key doesn't exist.

Types

type CreateRequest

type CreateRequest struct {
	AppName   string
	UserID    string
	SessionID string // Optional - generated if empty
	State     map[string]any
}

CreateRequest contains parameters for creating a session.

type CreateResponse

type CreateResponse struct {
	Session Session
}

CreateResponse contains the created session.

type DeleteRequest

type DeleteRequest struct {
	AppName   string
	UserID    string
	SessionID string
}

DeleteRequest contains parameters for deleting a session.

type GetRequest

type GetRequest struct {
	AppName   string
	UserID    string
	SessionID string

	// NumRecentEvents returns at most N most recent events.
	// Optional: if zero, returns all events.
	NumRecentEvents int

	// After returns events with timestamp >= the given time.
	// Optional: if zero, the filter is not applied.
	After time.Time
}

GetRequest contains parameters for retrieving a session.

type GetResponse

type GetResponse struct {
	Session Session
}

GetResponse contains the retrieved session.

type ListRequest

type ListRequest struct {
	AppName   string
	UserID    string
	PageSize  int
	PageToken string
}

ListRequest contains parameters for listing sessions.

type ListResponse

type ListResponse struct {
	Sessions      []Session
	NextPageToken string
}

ListResponse contains the list of sessions.

type SQLSessionService

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

SQLSessionService implements Service using a SQL database. Concurrency is handled by database-level locking (transactions).

func NewSQLSessionService

func NewSQLSessionService(db *sql.DB, dialect string) (*SQLSessionService, error)

NewSQLSessionService creates a new SQL-based session service.

func (*SQLSessionService) AppendEvent

func (s *SQLSessionService) AppendEvent(ctx context.Context, session Session, event *agent.Event) error

AppendEvent adds an event to the session history. Uses optimistic concurrency control to detect stale sessions.

func (*SQLSessionService) Close

func (s *SQLSessionService) Close() error

Close closes the database connection.

func (*SQLSessionService) Create

func (s *SQLSessionService) Create(ctx context.Context, req *CreateRequest) (*CreateResponse, error)

Create creates a new session.

func (*SQLSessionService) Delete

func (s *SQLSessionService) Delete(ctx context.Context, req *DeleteRequest) error

Delete removes a session.

func (*SQLSessionService) Get

func (s *SQLSessionService) Get(ctx context.Context, req *GetRequest) (*GetResponse, error)

Get retrieves an existing session.

func (*SQLSessionService) List

func (s *SQLSessionService) List(ctx context.Context, req *ListRequest) (*ListResponse, error)

List returns sessions matching the filter criteria.

type Service

type Service interface {
	// Get retrieves an existing session.
	Get(ctx context.Context, req *GetRequest) (*GetResponse, error)

	// Create creates a new session.
	Create(ctx context.Context, req *CreateRequest) (*CreateResponse, error)

	// AppendEvent adds an event to the session history.
	AppendEvent(ctx context.Context, session Session, event *agent.Event) error

	// List returns sessions matching the filter criteria.
	List(ctx context.Context, req *ListRequest) (*ListResponse, error)

	// Delete removes a session.
	Delete(ctx context.Context, req *DeleteRequest) error
}

Service manages session lifecycle and persistence.

func InMemoryService

func InMemoryService() Service

InMemoryService returns an in-memory session service. Useful for testing and development.

func NewSessionServiceFromConfig

func NewSessionServiceFromConfig(cfg *config.Config, pool *config.DBPool) (Service, error)

NewSessionServiceFromConfig creates a session Service using the primary database. All sessions are persisted to cfg.Database (SQLite by default).

type Session

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

	// AppName returns the application name.
	AppName() string

	// UserID returns the user identifier.
	UserID() string

	// State returns the session state store.
	State() agent.State

	// Events returns the session event history.
	Events() agent.Events

	// LastUpdateTime returns when the session was last modified.
	LastUpdateTime() time.Time
}

Session represents a conversation session between user and agents.