session

package
v0.3.2 Latest Latest
Warning

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

Go to latest
Published: Sep 11, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package session owns Peen's durable transport-neutral session transcript.

Index

Constants

View Source
const (
	// DefaultPageLimit is the API default for transcript pagination.
	DefaultPageLimit = 50
	// MaximumPageLimit bounds one transcript page at the storage boundary.
	MaximumPageLimit = 200
)

Variables

View Source
var (
	// ErrSessionBusy reports a concurrent turn attempt for one session.
	ErrSessionBusy = commerr.ErrLockHeld
	// ErrInvalidPage reports invalid transcript pagination arguments.
	ErrInvalidPage = commerr.ErrValidationFailed
)

Functions

This section is empty.

Types

type CompactionInput

type CompactionInput struct {
	ID                     uuid.UUID
	FromMessageID          uuid.UUID
	ToMessageID            uuid.UUID
	FromSequence           int64
	ToSequence             int64
	Summary                string
	SourceMessageCount     int64
	InputTokenCount        int64
	SummaryTokenCount      int64
	ModelID                string
	PromptHash             string
	SupersedesCompactionID *uuid.UUID
}

CompactionInput stores one immutable replacement summary.

type EventInput

type EventInput struct {
	ID               uuid.UUID
	RequestID        uuid.UUID
	EventType        string
	PayloadJSON      string
	ParentToolCallID string
}

EventInput describes one exact internal or protocol event.

type FinalizeTurnInput

type FinalizeTurnInput struct {
	State                 models.TurnState
	FailureClassification string
	ContextSnapshotHash   *string
	PromptSnapshotHash    *string
	Messages              []MessageInput
	Events                []EventInput
}

FinalizeTurnInput describes terminal turn state and durable references.

type History

type History struct {
	Compaction *models.Compaction
	Messages   []*models.Message
}

History is the active compaction followed by its uncovered completed tail.

type Lease

type Lease struct {
	SessionID uuid.UUID
	TurnID    uuid.UUID
}

Lease uniquely identifies one active turn in a session.

type ListMessagesOptions

type ListMessagesOptions struct {
	Limit  int
	Offset int
	Order  PageOrder
}

ListMessagesOptions controls a bounded session-local message page.

type MessageInput

type MessageInput struct {
	ID            uuid.UUID
	Workspace     string
	Role          models.MessageRole
	Content       string
	ModelID       string
	Thinking      string
	ToolCallsJSON string
	ToolCallID    string
	IsError       bool
	Incomplete    bool
}

MessageInput describes a durable transcript record.

type MessagePage

type MessagePage struct {
	Items   []*models.Message
	Limit   int
	Offset  int
	HasMore bool
}

MessagePage is one complete limit-offset transcript page.

type OpenSessionOptions

type OpenSessionOptions struct {
	RootAgent string
	ModelID   string
}

OpenSessionOptions supplies immutable session attribution on creation.

type OpenSessionResult

type OpenSessionResult struct {
	Session *models.Session
	Created bool
}

OpenSessionResult is a resolved session and whether this call created it.

type Options

type Options struct {
	Clock func() time.Time
	NewID func() uuid.UUID

	// MaxStoredMessageBytes bounds one message row of any role. An assistant
	// or tool message has no caller-facing size limit, so without this a
	// single tool result could grow the transcript without bound. Zero takes
	// the package default.
	MaxStoredMessageBytes int
}

Options supplies deterministic seams for the transport-neutral store.

type PageOrder

type PageOrder string

PageOrder controls transcript pagination direction.

const (
	PageOrderAscending  PageOrder = "asc"
	PageOrderDescending PageOrder = "desc"
)

type StartTurnInput

type StartTurnInput struct {
	RequestID uuid.UUID
	Workspace string
	Messages  []MessageInput
	Events    []EventInput
}

StartTurnInput describes the durable beginning of an agent turn.

type Store

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

Store persists sessions and protects each active session turn in-process.

func NewStore

func NewStore(handle *db.Handle, options Options) (*Store, error)

NewStore builds a store over an already-open migrated database handle.

func (*Store) AcquireTurn

func (s *Store) AcquireTurn(
	ctx context.Context,
	sessionID uuid.UUID,
	input StartTurnInput,
) (Lease, error)

AcquireTurn starts one durable turn and records its initial transcript data.

func (*Store) AppendCheckpoint

func (s *Store) AppendCheckpoint(
	ctx context.Context,
	lease Lease,
	messages []MessageInput,
	events []EventInput,
) error

AppendCheckpoint records visible messages and events without ending a turn.

func (*Store) Cancel

func (s *Store) Cancel(ctx context.Context, sessionID uuid.UUID) (bool, error)

Cancel requests cancellation for the active turn without waiting for it.

func (*Store) CompletedHistory

func (s *Store) CompletedHistory(
	ctx context.Context,
	sessionID uuid.UUID,
) (*History, error)

CompletedHistory returns the current summary and the raw completed tail.

func (*Store) CreateCompaction

func (s *Store) CreateCompaction(
	ctx context.Context,
	sessionID uuid.UUID,
	input CompactionInput,
) (*models.Compaction, error)

CreateCompaction stores an immutable completed-history replacement summary.

func (*Store) CreateOrResume

func (s *Store) CreateOrResume(
	ctx context.Context,
	requestedSessionID *uuid.UUID,
	options OpenSessionOptions,
) (*OpenSessionResult, error)

CreateOrResume creates a session or resumes its requested durable ID.

func (*Store) FinalizeTurn

func (s *Store) FinalizeTurn(
	ctx context.Context,
	lease Lease,
	input FinalizeTurnInput,
) error

FinalizeTurn atomically writes terminal transcript data and state.

func (*Store) Get

func (s *Store) Get(
	ctx context.Context,
	sessionID uuid.UUID,
) (*models.Session, error)

Get returns durable metadata for one existing session.

func (*Store) IsActive

func (s *Store) IsActive(sessionID uuid.UUID) bool

IsActive reports whether the process currently owns a running turn.

func (*Store) LatestCompaction

func (s *Store) LatestCompaction(
	ctx context.Context,
	sessionID uuid.UUID,
) (*models.Compaction, error)

LatestCompaction returns the current chain head, not a superseded row.

func (*Store) ListMessages

func (s *Store) ListMessages(
	ctx context.Context,
	sessionID uuid.UUID,
	options ListMessagesOptions,
) (*MessagePage, error)

ListMessages returns a stable bounded page of one session's transcript.

func (*Store) RecoverInterrupted

func (s *Store) RecoverInterrupted(ctx context.Context) (int, error)

RecoverInterrupted marks active turns and their messages incomplete.

func (*Store) RegisterCancellation

func (s *Store) RegisterCancellation(lease Lease, cancel context.CancelFunc)

RegisterCancellation associates cancellation with one exact active lease.

func (*Store) ReleaseTurn

func (s *Store) ReleaseTurn(lease Lease)

ReleaseTurn removes a lease only when it is still the registered turn.

func (*Store) SaveContextSnapshot

func (s *Store) SaveContextSnapshot(
	ctx context.Context,
	snapshot *models.ContextSnapshot,
) error

SaveContextSnapshot stores an immutable resolved harness context.

func (*Store) SavePromptSnapshot

func (s *Store) SavePromptSnapshot(
	ctx context.Context,
	snapshot *models.PromptSnapshot,
) error

SavePromptSnapshot stores an immutable effective prompt.

Jump to

Keyboard shortcuts

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