session

package
v0.60.1 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: AGPL-3.0 Imports: 10 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.

Info is a session-domain type, not an alias to memory.SessionInfo. Every use boundary fails closed: the persistence mapping (Record / InfoFromRecord) and the memory-scope conversion (MemoryScope) validate the session invariant and return an error rather than emit an unchecked value. The memory scope is produced only by MemoryScope; production code must not hand-build memory.Session values.

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"
	ChannelWebhook   Channel = "webhook"
)

type Info 

type Info struct {
	ID         string
	AgentID    string
	UserID     string
	GroupID    string
	Channel    string
	Kind       string
	ProjectID  string
	Title      string
	CreatedAt  time.Time
	LastActive time.Time
	Archived   bool
	// LatestSeq is populated by review listings and is not session metadata.
	LatestSeq int64
}

Info holds validated metadata about an agent session. It is a session-domain value distinct from the memory-layer persistence type memory.SessionInfo; callers cross the persistence boundary through Record and InfoFromRecord.

GroupID identifies the group a group session belongs to. It is now durable (ctx_conversation.group_id) and load/save round-trip it. The durable invariant is that a group session is owned by the group itself: UserID equals GroupID, and GroupID is the canonical ctx_group_state UUID. That equality is what makes group read, write, and compaction resolve one memory partition; it is enforced by Validate at every use boundary rather than left as an undeclared convention.

func InfoFromRecord added in v0.60.0 

func InfoFromRecord(r memory.SessionInfo) (Info, error)

InfoFromRecord maps a memory-layer persistence record back to a session-domain Info. It is the persistence→domain half of the session store boundary and the only sanctioned way to turn an unvalidated memory.SessionInfo into an Info; it validates the resulting Info and fails closed on a record that violates the session invariant.

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.

func (Info) MemoryScope added in v0.60.0 

func (i Info) MemoryScope() (memory.Session, error)

MemoryScope is the single canonical conversion from a validated session Info to a memory.Session operation scope. It fails closed: an Info that violates the session invariant yields an error, never a half-formed scope.

For a private session, read (Assemble), write (Append/Bootstrap), and compaction all derive their scope here and land on the same partition. A group session shares one durable canonical scope for read and write (partition keyed on session/user/agent, with GroupID selecting the group assembly/isolation path); group compaction is a separate matter and is unsupported (rejected by agent.Service.CompactSession), because group history is assembled from the group event log rather than the LCM conversation.

func (Info) Record added in v0.60.0 

func (i Info) Record() (memory.SessionInfo, error)

Record maps a validated session-domain Info onto the memory-layer persistence type. It is the domain→persistence half of the session store boundary and fails closed on an invalid Info.

func (Info) Validate added in v0.60.0 

func (i Info) Validate() error

Validate enforces the durable session-scope invariant. Every session needs an ID, an agent, and a user owner. A group session is owned by its group: UserID must equal GroupID and GroupID must be a canonical ctx_group_state UUID. This is the single fail-closed gate the persistence and memory-scope boundaries run.

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
	// ExcludeInternal omits task/delegate worker sessions from human lists.
	ExcludeInternal bool
	// ProjectID filters to one project when non-empty.
	ProjectID string
	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, error)

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; it delegates to the canonical Info.MemoryScope conversion. Private read, write, and compaction resolve one partition; group read and write share the durable canonical group scope (group compaction is unsupported, so MemoryScope makes no claim about it). It fails closed on an invalid Info.

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
	// GroupID marks this as a group session owned by the group. When set it is
	// the canonical ctx_group_state UUID and must equal UserID; it is persisted
	// so the group identity survives reload. Empty for private sessions.
	GroupID 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.

Source Files

View all Source files

Directories

Path Synopsis
Package access is the authoritative Session and Workspace application service.
 Package access is the authoritative Session and Workspace application service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.