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 ¶
- Variables
- type Channel
- type Info
- type Kind
- type ListOptions
- type MainRequest
- type Registry
- func (r *Registry) Archive(ctx context.Context, scope Scope, id string) error
- func (r *Registry) Ensure(ctx context.Context, req Request) (Info, error)
- func (r *Registry) Get(ctx context.Context, scope Scope, id string) (Info, error)
- func (r *Registry) List(ctx context.Context, scope Scope, opts ListOptions) ([]Info, error)
- func (r *Registry) ListForReview(ctx context.Context, req ReviewRequest) ([]Info, error)
- func (r *Registry) MemoryScope(info Info) memory.Session
- func (r *Registry) ResolveMain(ctx context.Context, req MainRequest) (Info, error)
- type Request
- type ReviewPolicy
- type ReviewRequest
- type Scope
Constants ¶
This section is empty.
Variables ¶
var ErrArchived = errors.New("session is archived")
ErrArchived is returned when an attempt is made to write to an archived session.
var ErrForbidden = errors.New("session access forbidden")
ErrForbidden is returned when a caller attempts to access a session they do not own.
var ErrNotFound = errors.New("session not found")
ErrNotFound is returned when a session cannot be located.
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 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.
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 ¶
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 ¶
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 ¶
NewRegistryWithStore creates a Registry with an explicit store (for testing).
func (*Registry) Ensure ¶
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 ¶
Get returns session metadata by ID. The session must belong to the given scope (userID + agentID match).
func (*Registry) ListForReview ¶
ListForReview returns sessions that are candidates for reflect review.
func (*Registry) MemoryScope ¶
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 ¶
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.