runtime

package
v0.60.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Overview

Package runtime executes agent conversations in already-resolved sessions.

The only entry point for callers is Runtime.Chat. Callers must obtain a validated session.Info from session.Registry before calling Chat. Runtime never creates or repairs session metadata.

Index

Constants

This section is empty.

Variables

View Source 
var ErrChatTimeout = agenterr.ErrChatTimeout

ErrChatTimeout is emitted when a chat turn exceeds its deadline.

View Source 
var ErrSessionBusy = agenterr.ErrSessionBusy

ErrSessionBusy is returned when a session already has an active chat turn.

Functions

func MessageText 

func MessageText(message MessageContent) string

MessageText extracts and joins all text from a MessageContent.

Types

type BeforeRunFunc 

type BeforeRunFunc func(ctx context.Context, info session.Info, model, msgText, system string, history []ai.Message) (systemOut string, err error)

BeforeRunFunc is called before each chat turn to inject/override the system prompt.

type CompactionConfig 

type CompactionConfig struct {
	MaxTokens int
	// KeepTail is the number of recent user turns preserved verbatim.
	KeepTail int
}

CompactionConfig controls automatic compaction thresholds.

func (CompactionConfig) WithDefaults 

func (c CompactionConfig) WithDefaults() CompactionConfig

WithDefaults returns the config with zero values replaced by defaults.

type Config 

type Config struct {
	NewRunner       NewRunnerFunc
	Memory          memory.Provider
	IdleTimeout     time.Duration
	Compaction      CompactionConfig
	DefaultModel    string
	DefaultThinking ai.ThinkingLevel
	FastModel       string
	HooksFn         func() []hooks.HookPlugin
	BeforeRun       BeforeRunFunc
	SnapshotPrompt  SnapshotPromptFunc
}

Config holds all dependencies for a Runtime instance.

type Event 

type Event struct {
	Text       string
	Reasoning  string
	Image      *ImageEvent
	File       *FileEvent
	ToolUse    *ToolUseEvent
	References []renderrefs.Reference
	Step       *StepEvent
	Store      ai.Message // non-nil → append to session history
	Err        error
}

Event is the consumer-facing stream event.

type FileEvent 

type FileEvent struct {
	Path string
	Name string
}

FileEvent carries a local file path.

type ImageEvent 

type ImageEvent struct {
	Data     string
	MimeType string
}

ImageEvent carries a base64-encoded image.

type MessageContent 

type MessageContent = any

MessageContent is a user message: string (text) or []ai.ContentBlock (multimodal).

type NewRunnerFunc 

type NewRunnerFunc func(ctx context.Context, params RunnerParams) (Runner, error)

NewRunnerFunc creates a new Runner with the given params.

type Option 

type Option func(*chatOptions)

Option configures a single Chat call.

func WithCurrentSpeaker added in v0.43.0 

func WithCurrentSpeaker(speaker memory.CurrentSpeaker) Option

WithCurrentSpeaker attaches the per-turn group speaker for this Chat call. It is a personalization target only — the runtime never promotes it to the session/runtime identity (D9). DM turns leave it unset.

func WithExcludedTools 

func WithExcludedTools(names ...string) Option

WithExcludedTools hides the named tools for this Chat call.

func WithExtraTools added in v0.46.0 

func WithExtraTools(ts ...tools.Tool) Option

WithExtraTools binds additional tools to the runner for this Chat call. The runner is rebuilt for the call (per-call tools defeat the session cache), so callers should evict the session runner afterwards via CloseSession to avoid the tools leaking into later tool-less turns.

func WithModel 

func WithModel(model string) Option

WithModel overrides the model for this Chat call.

func WithSystemOverride 

func WithSystemOverride(system string) Option

WithSystemOverride overrides the system prompt for this Chat call.

type Runner 

type Runner interface {
	Chat(ctx context.Context, history []ai.Message, message MessageContent) <-chan Event
	Alive() bool
	Busy() bool
	LastActivity() time.Time
	SystemPrompt() string
	Close() error
}

Runner executes prompts against an AI backend.

type RunnerParams 

type RunnerParams struct {
	Model          string
	Thinking       ai.ThinkingLevel
	Memory         any // memory.Provider — typed as any to avoid circular imports
	UserID         string
	GroupID        string // non-empty for group sessions; runtime uses this to isolate identity surfaces
	SessionID      string
	AgentID        string
	ProjectID      string
	HooksFn        func() []hooks.HookPlugin
	ExtraTools     []tools.Tool
	DelegateRunner delegatetool.SessionRunner
}

RunnerParams holds dependencies for creating a new Runner.

type Runtime 

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

Runtime executes agent conversations in already-resolved sessions. It owns the runner cache, runner factory, and event streaming. It does NOT own session creation, kind validation, or list/archive APIs.

func New 

func New(cfg Config) (*Runtime, error)

New creates a Runtime from the given config.

func (*Runtime) Chat 

func (rt *Runtime) Chat(ctx context.Context, info session.Info, msg MessageContent, opts ...Option) <-chan Event

func (*Runtime) Close 

func (rt *Runtime) Close() error

Close shuts down all runners and releases resources.

func (*Runtime) CloseSession 

func (rt *Runtime) CloseSession(_ context.Context, sessionID string) error

CloseSession closes the runner for a single session without affecting others.

func (*Runtime) CloseSessionWithSandbox added in v0.60.0 

func (rt *Runtime) CloseSessionWithSandbox(_ context.Context, sessionID string, cb SandboxSessionCallback) error

CloseSessionWithSandbox closes the runner for one session, first exposing the live sandbox to cb when the runner has one. The runner is closed after cb returns even when cb reports an error.

func (*Runtime) Memory 

func (rt *Runtime) Memory() memory.Provider

Memory returns the memory provider backing this runtime.

func (*Runtime) NewRunnerFunc added in v0.41.3 

func (rt *Runtime) NewRunnerFunc() NewRunnerFunc

NewRunnerFunc returns the current runner builder. Used by the task system to create standalone runners with custom tools.

func (*Runtime) ResetRunners 

func (rt *Runtime) ResetRunners() error

ResetRunners closes all live runners while keeping session metadata in storage.

func (*Runtime) ResetRunnersForUser 

func (rt *Runtime) ResetRunnersForUser(userID string) error

ResetRunnersForUser closes live runners for a specific user.

func (*Runtime) SessionLive added in v0.49.3 

func (rt *Runtime) SessionLive(sessionID string) bool

SessionLive reports whether a turn is currently in flight on the session.

func (*Runtime) SetDefaultModel 

func (rt *Runtime) SetDefaultModel(model string, thinking ai.ThinkingLevel)

SetDefaultModel updates the default model for new runners.

func (*Runtime) SetDelegateRunner 

func (rt *Runtime) SetDelegateRunner(r delegatetool.SessionRunner)

SetDelegateRunner wires the delegate session runner into new runners. Call after construction so runners can spawn persistent child sessions.

func (*Runtime) SetHooks 

func (rt *Runtime) SetHooks(fn func() []hooks.HookPlugin)

SetHooks updates the hook getter used when creating new runners.

func (*Runtime) SetNewRunner added in v0.41.3 

func (rt *Runtime) SetNewRunner(f NewRunnerFunc)

SetNewRunner replaces the runner builder. Existing runners are not affected until their session is next reused.

func (*Runtime) StartReaper 

func (rt *Runtime) StartReaper(ctx context.Context)

StartReaper begins the idle-runner eviction loop. Call in a goroutine.

func (*Runtime) Subscribe added in v0.49.3 

func (rt *Runtime) Subscribe(sessionID string) (<-chan Event, func())

Subscribe registers a read-only listener for a session's live turn events. The channel is closed when the in-flight turn ends; callers must invoke the returned cancel func when they stop reading. See SessionHub.

func (*Runtime) WaitTurns added in v0.60.0 

func (rt *Runtime) WaitTurns(ctx context.Context) error

WaitTurns blocks until this runtime has no in-flight chat turn or ctx expires. Graceful shutdown calls it between draining HTTP and cancelling the work contexts, so turns with no HTTP connection to hold the drain open (channel messages, webhook runs, scheduler run-now) still finish. It covers the turn itself, not the caller's sub-second delivery tail after the event stream closes; lift tracking to the adapter operation if truncated final sends are ever observed.

type SandboxSessionCallback added in v0.60.0 

type SandboxSessionCallback func(sandbox.Session) error

SandboxSessionCallback is invoked with a live runner-owned sandbox immediately before Runtime closes that session's runner. The callback must not retain the handle after returning; CloseSessionWithSandbox closes it next.

type SessionHub added in v0.49.3 

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

SessionHub fans out a session's live turn events to any number of read-only subscribers. The runtime publishes every event of an in-flight turn; HTTP SSE handlers subscribe to watch a turn they did not initiate — a scheduler/task turn driven server-side, or a turn started from another browser tab.

Publishing never blocks the turn: a slow subscriber drops events rather than stalling the agent. Subscribers reconcile final state by reloading persisted history, so dropped deltas are cosmetic.

Placement invariant: the hub lives on the Runtime that executes a session's turns, and the SSE handler subscribes via the Service of `session.AgentID`. This is correct only because every turn for a session — chat, scheduler, task, and delegate — runs on that agent's Runtime. If a turn ever runs on a different Runtime (e.g. a cross-agent delegate, or a standalone task runner), it would publish to a hub the watcher never subscribes to and the live stream would silently fall back to 204. Such a change must hoist the hub to a single per-pool instance keyed by session ID.

func NewSessionHub added in v0.49.3 

func NewSessionHub() *SessionHub

NewSessionHub returns an empty hub.

func (*SessionHub) IsLive added in v0.49.3 

func (h *SessionHub) IsLive(sessionID string) bool

IsLive reports whether a turn is currently in flight on the session.

func (*SessionHub) Subscribe added in v0.49.3 

func (h *SessionHub) Subscribe(sessionID string) (<-chan Event, func())

Subscribe registers a listener for a session's live events. The returned channel delivers events until the turn ends (then it is closed) or the caller invokes cancel. Callers must always invoke cancel to avoid leaking the subscription.

type SnapshotPromptFunc 

type SnapshotPromptFunc func(ctx context.Context, info session.Info, snap memory.SessionSnapshot) string

SnapshotPromptFunc builds a system prompt from the session's snapshot version.

type StepEvent 

type StepEvent struct {
	Kind string // "start" or "finish"
}

StepEvent marks the boundary of an agentic step.

type ToolUseEvent 

type ToolUseEvent struct {
	ID         string
	Tool       string
	Status     string
	Input      string
	Arguments  map[string]any
	Detail     string
	Content    string
	References []renderrefs.Reference
}

ToolUseEvent describes a tool invocation in progress or completed.

Source Files

View all Source files

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.