runtime

package
v0.64.0 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: AGPL-3.0 Imports: 27 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
	SessionImages   SessionImages
}

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 WithInboxID added in v0.63.3 

func WithInboxID(id string) Option

WithInboxID binds a runtime-authored durable Session inbox row to this input. It is internal admission metadata, never a model argument.

func WithInputActor added in v0.63.3 

func WithInputActor(actor eventlog.MessageActor) Option

WithInputActor attaches runtime-derived provenance to the input message. The value comes from trusted authority/session state, never model arguments.

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
	GuestID        string // durable guest identity; non-empty selects the no-capabilities runner
	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
}

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

Chat preserves the historic stream-only API. A rejected admission surfaces as the historic immediate error event; callers that must distinguish a rejected admission from an admitted turn (e.g. webhook ingress) use ChatAdmitted.

func (*Runtime) ChatAdmitted added in v0.61.0 

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

func (*Runtime) ChatAdmittedControlled added in v0.63.3 

func (rt *Runtime) ChatAdmittedControlled(ctx context.Context, info session.Info, msg MessageContent, beforeStart func() error, opts ...Option) (stream <-chan Event, admissionErr error)

ChatAdmittedControlled is ChatAdmitted with a final admission fence. The fence runs after the busy guard is acquired but before transcript/runtime side effects, allowing a synchronous queue to reject a caller that timed out at the admission boundary without replay or ambiguous execution.

func (*Runtime) Close 

func (rt *Runtime) Close() error

Close shuts down all runners and rejects every later admission.

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) InvalidateSkillPolicy added in v0.64.0 

func (rt *Runtime) InvalidateSkillPolicy() error

InvalidateSkillPolicy schedules existing runners for refresh without interrupting an in-flight turn, which continues with its copied snapshot.

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) RunManagedSession added in v0.63.3 

func (rt *Runtime) RunManagedSession(ctx context.Context, sourceSessionID string, req delegatetool.ManagedSessionRequest) (delegatetool.ManagedSessionResult, error)

RunManagedSession executes a Session-tool request through the currently active source runner. The source runner owns the effective delegate preset, system override, timeout, and excluded-tool set for this turn.

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) SetPromptBuilders added in v0.64.0 

func (rt *Runtime) SetPromptBuilders(beforeRun BeforeRunFunc, snapshotPrompt SnapshotPromptFunc)

SetPromptBuilders replaces the snapshot-derived prompt builders for turns admitted after a configuration refresh. Callers serialize this with runner replacement through the Agent admission barrier.

func (*Runtime) StartReaper 

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

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

func (*Runtime) StopSession added in v0.63.0 

func (rt *Runtime) StopSession(ctx context.Context, sessionID string) bool

StopSession cancels the active turn for sessionID. It returns false when the session has no in-flight turn. Disconnecting an observer never calls this; cancellation is an explicit, authorized action at the Session boundary.

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) TerminalCloseWhere added in v0.64.0 

func (rt *Runtime) TerminalCloseWhere(include func(session.Info) bool) error

TerminalCloseWhere immediately detaches matching runners, including busy and reserved ones. It is solely for destructive owner deletion after admission is blocked by the caller.

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 after navigation or connection loss, one driven server-side, or one started from another browser tab.

Publishing never blocks the turn: a slow subscriber drops events rather than stalling the agent. While a turn is active, the hub retains a bounded replay so a newly attached subscriber can reconstruct output emitted before it connected. Subscribers still reconcile final state from persisted history.

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. Events already emitted by the active turn are queued before live delivery. The returned channel closes when the turn ends or the caller invokes cancel.

type SessionImages added in v0.61.0 

type SessionImages interface {
	Enrich(context.Context, string, string, []ai.ContentBlock) ([]ai.ContentBlock, error)
}

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. SessionImages converts raw image blocks into canonical references at the ordinary-session write chokepoint. The full pipeline also hydrates active media for runners; Runtime only needs its enrichment operation.

type SnapshotPromptFunc 

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

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.