session

package
v0.50.7 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package session owns agent-session lifecycle.

It is the sole authority over session creation, resumption, kind/channel policy, main-session resolution, review candidate selection, and the conversion from a validated session record to a memory operation scope.

Production code outside this package and runtime should obtain memory.Session via Registry.MemoryScope. The runtime is allowed to construct it directly from validated Info because its inputs always come through the Registry.

Index

Constants

This section is empty.

Variables

View Source
var ErrArchived = errors.New("session is archived")

ErrArchived is returned when an attempt is made to write to an archived session.

View Source
var ErrForbidden = errors.New("session access forbidden")

ErrForbidden is returned when a caller attempts to access a session they do not own.

View Source
var ErrNotFound = errors.New("session not found")

ErrNotFound is returned when a session cannot be located.

View Source
var ErrWrongKind = errors.New("session kind mismatch")

ErrWrongKind is returned when a resumed session has a different kind than required.

Functions

This section is empty.

Types

type Channel

type Channel string

Channel is the typed originating channel.

const (
	ChannelWeb       Channel = "web"
	ChannelCLI       Channel = "cli"
	ChannelTelegram  Channel = "telegram"
	ChannelDelegate  Channel = "delegate"
	ChannelTask      Channel = "task"
	ChannelScheduler Channel = "scheduler"
)

type Info

type Info = memory.SessionInfo

Info holds metadata about an agent session. It wraps memory.SessionInfo so callers interact with a session-domain type while the underlying storage stays in the memory layer.

func NewInfo

func NewInfo(id, agentID, userID, channel string, kind Kind, projectID string, now time.Time) Info

NewInfo constructs a fresh Info with the required fields set.

type Kind

type Kind string

Kind is the typed session kind.

const (
	KindMain      Kind = "main"
	KindChat      Kind = "chat"
	KindDelegate  Kind = "delegate"
	KindTask      Kind = "task"
	KindScheduler Kind = "scheduler"
)

type ListOptions

type ListOptions struct {
	// Kinds filters by session kind; empty = all kinds.
	Kinds []Kind
	// IncludeArchived includes archived sessions.
	IncludeArchived bool
	Limit           int
	Offset          int
}

ListOptions controls session listing.

type MainRequest

type MainRequest struct {
	UserID  string
	AgentID string
}

MainRequest describes a main-session resolution request.

type Registry

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

Registry is the sole owner of agent-session lifecycle. It creates, resumes, lists, and archives sessions; it also converts validated session records into memory operation scopes.

Registry has no knowledge of LLM execution, runners, or tools.

func NewRegistry

func NewRegistry(mem memory.Provider, agentID string) (*Registry, error)

NewRegistry creates a Registry backed by the given memory.Provider. mem must implement memory.SessionManager; if it does not, an error is returned. agentID may be empty for a cross-agent registry.

func NewRegistryWithStore

func NewRegistryWithStore(s store, agentID string) *Registry

NewRegistryWithStore creates a Registry with an explicit store (for testing).

func (*Registry) Archive

func (r *Registry) Archive(ctx context.Context, scope Scope, id string) error

Archive marks a session as archived.

func (*Registry) Ensure

func (r *Registry) Ensure(ctx context.Context, req Request) (Info, error)

Ensure finds or creates a session according to the request policy.

- If req.ID is set and the session exists: validates kind and user, returns it. - If req.ID is set but missing and AllowExactIDCreate: creates with that ID. - If req.ID is empty and CreateIfMissing: generates a new ID and creates. - Otherwise: returns ErrNotFound.

func (*Registry) Get

func (r *Registry) Get(ctx context.Context, scope Scope, id string) (Info, error)

Get returns session metadata by ID. The session must belong to the given scope (userID + agentID match).

func (*Registry) List

func (r *Registry) List(ctx context.Context, scope Scope, opts ListOptions) ([]Info, error)

List returns sessions matching the scope and options.

func (*Registry) ListForReview

func (r *Registry) ListForReview(ctx context.Context, req ReviewRequest) ([]Info, error)

ListForReview returns sessions that are candidates for reflect review.

func (*Registry) MemoryScope

func (r *Registry) MemoryScope(info Info) memory.Session

MemoryScope converts a validated session Info into a memory.Session scope. This is the ONLY authorised way to produce memory.Session for production agent sessions.

func (*Registry) ResolveMain

func (r *Registry) ResolveMain(ctx context.Context, req MainRequest) (Info, error)

ResolveMain returns the main session for a user+agent pair. It first looks for an existing main-kind session, then promotes the most recent candidate, and finally creates a new one if CreateIfMissing is set.

type Request

type Request struct {
	// ID is the exact session ID to resume. If empty, a new ID is generated.
	ID string
	// UserID and AgentID are required for user-scoped operations.
	UserID  string
	AgentID string
	// ProjectID scopes the session to a project when non-empty.
	ProjectID string
	// Kind is the session kind to use when creating a new session.
	// If the session already exists, it must match RequireKind when set.
	Kind Kind
	// Channel is the originating channel (e.g. ChannelWeb, ChannelDelegate).
	Channel Channel
	// Title is optional; pool_chat auto-derives it from the first message.
	Title string
	// CreateIfMissing creates a new session if none matches.
	CreateIfMissing bool
	// AllowExactIDCreate allows creating a new session with the explicit ID
	// when that ID does not yet exist. Required for delegate session persistence.
	AllowExactIDCreate bool
	// RequireKind enforces that a resumed session must have this kind.
	// Empty means any kind is acceptable.
	RequireKind Kind
}

Request describes what session to find or create.

type ReviewPolicy

type ReviewPolicy struct {
	// ExcludeKinds lists session kinds to skip.
	ExcludeKinds []Kind
	// RequirePrivateMain, when true, includes only sessions on private user channels.
	RequirePrivateMain bool
}

ReviewPolicy controls which sessions are included in reflect review.

func DefaultReviewPolicy

func DefaultReviewPolicy() ReviewPolicy

DefaultReviewPolicy returns the policy used by the reflect system. Delegate, task, and scheduler sessions are excluded by default.

func (ReviewPolicy) Includes

func (p ReviewPolicy) Includes(kind Kind) bool

Includes reports whether a session with the given kind passes this policy.

func (ReviewPolicy) IsZero

func (p ReviewPolicy) IsZero() bool

IsZero reports whether no review policy was supplied.

type ReviewRequest

type ReviewRequest struct {
	AgentID string
	// Policy controls inclusion/exclusion rules.
	Policy ReviewPolicy
}

ReviewRequest describes which sessions are candidates for reflect review.

type Scope

type Scope struct {
	UserID  string
	AgentID string
	// System marks this as a background-only scope (e.g. reflect).
	// System scopes bypass user requirement but still require AgentID.
	System bool
}

Scope identifies a caller's access scope for registry queries.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL