session

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package session runs one conversation on an agentcore.Agent. It knows no features; everything a run needs comes in a RunSpec.

A Session is an actor: each method queues an operation for one goroutine, so only Wait blocks on a run. Messages and compactions are written to the log before they enter the Agent's history, so History always equals a replay of the log.

Index

Constants

This section is empty.

Variables

View Source
var ErrClosed = errors.New("session closed")

Functions

This section is empty.

Types

type Event

type Event struct {
	Kind  Kind
	Agent agentcore.Event // Kind == Agent
	Err   error           // Kind == Error
}

type Input

type Input struct {
	Source Source
	Msg    agentcore.Message
}

type Kind

type Kind int
const (
	// Agent carries a loop event unchanged; manual compactions report
	// through the loop's compaction events too.
	Agent Kind = iota
	RunStarted
	// Idle follows a run or manual compaction when nothing is left to run.
	Idle
	StatusChanged
	// Error reports a failure outside any run, such as logging a model
	// change.
	Error
)

type RunSpec

type RunSpec struct {
	// Provider, Model and Effort are logged whenever one of them changes.
	Provider string
	Model    string
	Effort   string
	Window   int

	// Config.Compactor must be set. The Agent fills in Emit, Steering and
	// FollowUp.
	Config agentcore.Config
	// WrapRun returns the run's context and a callback for the run's error.
	WrapRun func(ctx context.Context) (context.Context, func(err error))
	// Context returns messages describing the current environment that the
	// history does not already carry. They are prepended to each run's
	// inputs, and appended to a compacted history, since compaction drops
	// the earlier copies.
	Context func(history []agentcore.Message) []agentcore.Message
}

type Session

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

func Open

func Open(store *storage.Store, state storage.State, spec RunSpec) (*Session, error)

Open logs the model selection if spec changes it.

func (*Session) Cancel

func (s *Session) Cancel()

Cancel stops the live run or compaction and drops queued User inputs. Queued Background inputs wait for the next User input.

func (*Session) Close

func (s *Session) Close()

Close waits for the canceled run to end. Events already published are still delivered.

func (*Session) Compact

func (s *Session) Compact(ctx context.Context) error

Compact cancels a live run first. The session keeps accepting calls while the summary is written; inputs posted meanwhile run after it is committed.

func (*Session) Configure

func (s *Session) Configure(spec RunSpec)

Configure leaves a live run on the spec it started with.

func (*Session) History

func (s *Session) History() []agentcore.Message

History includes what a live run has recorded so far.

func (*Session) Post

func (s *Session) Post(in Input)

Post never blocks; after Close it does nothing.

func (*Session) Query

func (s *Session) Query(ctx context.Context, prompt string, maxTokens int) (string, error)

Query asks a one-off question on top of the current history, reusing the conversation's prompt cache. Neither the question nor the answer is kept.

func (*Session) Status

func (s *Session) Status() Status

func (*Session) Subscribe

func (s *Session) Subscribe(fn func(Event)) (unsubscribe func())

Subscribe delivers events in order on a goroutine per subscriber, so a slow subscriber delays only itself.

func (*Session) Wait

func (s *Session) Wait(ctx context.Context) error

Wait returns once the session is idle, every earlier input is handled and every subscriber has received the events up to that point. Calling it from a subscriber deadlocks.

type Source

type Source int

Source decides when an input is processed.

const (
	// User input steers a live run at its next tool boundary, or starts a
	// run. It clears a previous Cancel.
	User Source = iota
	// Background input, such as a finished background task, joins a live run
	// before it ends, or starts a run. After a Cancel it waits for the next
	// User input.
	Background
)

type Status

type Status struct {
	SessionID string
	Provider  string
	Model     string
	Effort    string
	Window    int
	// Context is the estimated token count of the next request.
	Context int
	Running bool
	// Usage includes responses that a compaction later replaced.
	Usage   agentcore.Usage
	LastRun *agentcore.RunEnd
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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