agent

Documentation

Index

• type ModelFactory
• type Session
  • func NewSession(cfg SessionConfig) *Session
  • func (s *Session) APIKey() string
  • func (s *Session) Abort()
  • func (s *Session) AbortSilent()
  • func (s *Session) BaseURL() string
  • func (s *Session) ClearConversation()
  • func (s *Session) Close()
  • func (s *Session) Compact() error
  • func (s *Session) ContextUsage() *agentcore.ContextUsage
  • func (s *Session) CostEstimate() (inputTokens, outputTokens int, cost float64)
  • func (s *Session) CurrentSessionInfo() (storage.SessionInfo, error)
  • func (s *Session) IsRunning() bool
  • func (s *Session) LastAssistantText() string
  • func (s *Session) ListSessions() ([]storage.SessionInfo, error)
  • func (s *Session) ModelName() string
  • func (s *Session) NewSession() error
  • func (s *Session) Prompt(text string) error
  • func (s *Session) PromptWithBlocks(blocks []agentcore.ContentBlock) error
  • func (s *Session) Provider() string
  • func (s *Session) Registry() *provider.ModelRegistry
  • func (s *Session) Reload()
  • func (s *Session) ReplaceAllTools(tools []agentcore.Tool)
  • func (s *Session) ResolveAndSetModel(pattern string) (string, error)
  • func (s *Session) RestoreAllTools(extra ...agentcore.Tool)
  • func (s *Session) SetBeforePrompt(fn func())
  • func (s *Session) SetModel(prov, model string) error
  • func (s *Session) SetSystemSuffix(suffix string)
  • func (s *Session) SetThinkingLevel(level agentcore.ThinkingLevel)
  • func (s *Session) SetTools(tools ...agentcore.Tool)
  • func (s *Session) Settings() config.Resolved
  • func (s *Session) Skills() []config.Skill
  • func (s *Session) Steer(text string)
  • func (s *Session) Subscribe(fn func(SessionEvent)) func()
  • func (s *Session) SwitchSession(id string) error
  • func (s *Session) ToolsByName(names ...string) []agentcore.Tool
  • func (s *Session) TotalTokens() int
• type SessionConfig
• type SessionEvent
• type SessionEventType

Types

type ModelFactory

type ModelFactory func(prov, model, apiKey, baseURL string) (agentcore.ChatModel, error)

ModelFactory creates a chat model instance for a provider/model tuple.

type Session

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

Session is the business-logic core that wraps Agent + session persistence. It is independent of any UI framework and drives interactive, print, and RPC modes.

func NewSession

func NewSession(cfg SessionConfig) *Session

NewSession creates a Session and wires auto-persist to the agent.

func (*Session) APIKey

func (s *Session) APIKey() string

APIKey returns the API key for the current provider.

func (*Session) Abort

func (s *Session) Abort()

Abort cancels the running agent and emits an abort marker message.

func (*Session) AbortSilent

func (s *Session) AbortSilent()

AbortSilent cancels the running agent without emitting an abort marker. Use for programmatic cancellation (e.g. plan mode transitions).

func (*Session) BaseURL

func (s *Session) BaseURL() string

BaseURL returns the base URL for the current provider.

func (*Session) ClearConversation

func (s *Session) ClearConversation()

ClearConversation clears in-memory conversation messages and queued inputs.

func (*Session) Close

func (s *Session) Close()

Close cleans up the session (unsubscribes from agent, closes store).

func (*Session) Compact

func (s *Session) Compact() error

Compact performs manual compaction using the same strategy as agentcore memory compaction. It persists a compaction checkpoint to session log for deterministic restore.

func (*Session) ContextUsage

func (s *Session) ContextUsage() *agentcore.ContextUsage

ContextUsage returns current context window occupancy.

func (*Session) CostEstimate

func (s *Session) CostEstimate() (inputTokens, outputTokens int, cost float64)

CostEstimate returns accumulated token counts and an estimated cost (USD) for the storage. Cost is computed using the current model's rates (approximate if models were switched).

func (*Session) CurrentSessionInfo

func (s *Session) CurrentSessionInfo() (storage.SessionInfo, error)

CurrentSessionInfo returns metadata of the active storage.

func (*Session) IsRunning

func (s *Session) IsRunning() bool

IsRunning reports whether the underlying agent is currently processing.

func (*Session) LastAssistantText

func (s *Session) LastAssistantText() string

LastAssistantText returns the text of the most recent assistant message, or "".

func (*Session) ListSessions

func (s *Session) ListSessions() ([]storage.SessionInfo, error)

ListSessions returns sessions sorted by most recent update first.

func (*Session) ModelName

func (s *Session) ModelName() string

ModelName returns the current model name.

func (*Session) NewSession

func (s *Session) NewSession() error

NewSession closes the current session and creates a new one.

func (*Session) Prompt

func (s *Session) Prompt(text string) error

Prompt sends a user message to the agent.

func (*Session) PromptWithBlocks

func (s *Session) PromptWithBlocks(blocks []agentcore.ContentBlock) error

PromptWithBlocks sends a multimodal user message (text + images) to the agent.

func (*Session) Provider

func (s *Session) Provider() string

Provider returns the current provider name.

func (*Session) Registry

func (s *Session) Registry() *provider.ModelRegistry

Registry returns the model registry (may be nil).

func (*Session) Reload

func (s *Session) Reload()

Reload rescans context files, skills, and prompt templates from disk, then rebuilds the system prompt. Call this after adding/removing skill files.

func (*Session) ReplaceAllTools

func (s *Session) ReplaceAllTools(tools []agentcore.Tool)

ReplaceAllTools replaces the base tool set, updates active tools, and rebuilds the system prompt. Must be called from the main loop (not from a goroutine).

func (*Session) ResolveAndSetModel

func (s *Session) ResolveAndSetModel(pattern string) (string, error)

ResolveAndSetModel resolves a model pattern via the registry and switches to it. Returns the resolved model name.

func (*Session) RestoreAllTools

func (s *Session) RestoreAllTools(extra ...agentcore.Tool)

RestoreAllTools restores the full tool set, optionally appending extra tools, and rebuilds the system prompt to match.

func (*Session) SetBeforePrompt

func (s *Session) SetBeforePrompt(fn func())

SetBeforePrompt registers a function called before each agent turn.

func (*Session) SetModel

func (s *Session) SetModel(prov, model string) error

SetModel switches the LLM model and persists the change.

func (*Session) SetSystemSuffix

func (s *Session) SetSystemSuffix(suffix string)

SetSystemSuffix sets (or clears) a suffix appended after the base system prompt. Triggers a prompt rebuild with the current active tools.

func (*Session) SetThinkingLevel

func (s *Session) SetThinkingLevel(level agentcore.ThinkingLevel)

SetThinkingLevel changes the reasoning depth and persists the change.

func (*Session) SetTools

func (s *Session) SetTools(tools ...agentcore.Tool)

SetTools replaces the active tool set and rebuilds the system prompt to match.

func (*Session) Settings

func (s *Session) Settings() config.Resolved

Settings returns current resolved settings.

func (*Session) Skills

func (s *Session) Skills() []config.Skill

Skills returns the loaded skills list.

func (*Session) Steer

func (s *Session) Steer(text string)

Steer queues a steering message to interrupt the agent mid-run.

func (*Session) Subscribe

func (s *Session) Subscribe(fn func(SessionEvent)) func()

Subscribe registers a listener for session events. Returns an unsubscribe function.

func (*Session) SwitchSession

func (s *Session) SwitchSession(id string) error

SwitchSession closes the current session and restores another by ID.

func (*Session) ToolsByName

func (s *Session) ToolsByName(names ...string) []agentcore.Tool

ToolsByName returns the subset of allTools matching the given names.

func (*Session) TotalTokens

func (s *Session) TotalTokens() int

TotalTokens returns accumulated total tokens across current process lifetime.

type SessionConfig

type SessionConfig struct {
	Agent    *agentcore.Agent
	Store    *storage.Store
	Manager  *storage.Manager
	Registry *provider.ModelRegistry
	Settings config.Resolved
	Cwd      string
	// CreateModel allows tests/integrations to override model construction.
	// Defaults to provider.CreateModel when nil.
	CreateModel ModelFactory
	// LazyPersist buffers user messages and flushes them only when
	// an assistant response arrives. Disabled by default for safety.
	LazyPersist bool

	// Tools is the full set of tools registered with the agent.
	// Used by ToolsByName / RestoreAllTools for plan mode filtering.
	Tools []agentcore.Tool
	// ContextFiles holds loaded context files for dynamic system prompt rebuilding.
	// When tools change the prompt is regenerated from these inputs.
	ContextFiles config.ContextFiles
	// Skills holds loaded skills for system prompt injection and /skill: commands.
	Skills []config.Skill
}

SessionConfig configures a new Session.

type SessionEvent

type SessionEvent struct {
	Type       SessionEventType
	AgentEvent *agentcore.Event

	// Session-level fields (populated based on Type)
	ModelName string
	Provider  string
	Level     agentcore.ThinkingLevel
	SessionID string
	Error     error

	// Retry fields (populated for SEAutoRetryStart / SEAutoRetryEnd)
	RetryAttempt int
	RetryMax     int
	RetryDelay   time.Duration
	RetrySuccess bool

	// Compaction reason: "overflow" or "threshold"
	CompactionReason string
}

SessionEvent extends agent events with session-level metadata. When Type == SEAgentEvent, AgentEvent is non-nil.

type SessionEventType

type SessionEventType string

SessionEventType identifies a session-level event.

const (
	// SEAgentEvent wraps an agentcore.Event transparently.
	SEAgentEvent SessionEventType = "agent_event"

	// Session lifecycle events
	SEAutoCompactionStart SessionEventType = "auto_compaction_start"
	SEAutoCompactionEnd   SessionEventType = "auto_compaction_end"
	SEAutoRetryStart      SessionEventType = "auto_retry_start"
	SEAutoRetryEnd        SessionEventType = "auto_retry_end"
	SEModelChanged        SessionEventType = "model_changed"
	SEThinkingChanged     SessionEventType = "thinking_changed"
	SESessionSwitched     SessionEventType = "session_switched"
	SEError               SessionEventType = "session_error"
)