Documentation
¶
Index ¶
- Variables
- type AgentErrored
- type AgentFinished
- type AgentStarted
- type AssistantDelta
- type AssistantFinished
- type AssistantStarted
- type CanonicalImageConfig
- type LoopEvent
- type MediaLoader
- type Option
- func WithCanonicalImages(cfg CanonicalImageConfig) Option
- func WithHooks(hs *hooks.HookSet, meta hooks.HookMeta) Option
- func WithInterrupt(ch <-chan struct{}) Option
- func WithStreamOptions(opts ai.StreamOptions) Option
- func WithSystem(s string) Option
- func WithToolLifecycle(tl *ToolLifecycle) Option
- func WithTurnNotify(fn func(turn int, elapsed time.Duration) *string) Option
- type ProjectionError
- type Runner
- func (r *Runner) Continue(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)
- func (r *Runner) RunWithActiveStart(ctx context.Context, messages []ai.Message, activeStart int, ...) ([]ai.Message, error)
- func (r *Runner) SetHookMeta(meta hooks.HookMeta)
- func (r *Runner) SetTurnNotify(fn func(turn int, elapsed time.Duration) *string)
- type RunnerConfig
- type ToolCallContext
- type ToolCallMutation
- type ToolFinished
- type ToolFunc
- type ToolImageCanonicalizer
- type ToolLifecycle
- type ToolResultContext
- type ToolResultMutation
- type ToolSet
- type ToolStarted
- type TurnFinished
- type TurnStarted
Constants ¶
This section is empty.
Variables ¶
var ( ErrAssistantImageBlock = projectionError("assistant image block is invalid") ErrImageRefUnresolved = projectionError("image reference reached provider boundary") ErrUnsupportedImage = projectionError("unsupported model received image content") )
Functions ¶
This section is empty.
Types ¶
type AgentErrored ¶
type AgentErrored struct {
Err error
}
AgentErrored is emitted for terminal loop errors.
func (AgentErrored) Kind ¶
func (AgentErrored) Kind() string
type AgentFinished ¶
type AgentFinished struct{}
AgentFinished is emitted when loop completes.
func (AgentFinished) Kind ¶
func (AgentFinished) Kind() string
type AgentStarted ¶
type AgentStarted struct{}
AgentStarted is emitted when a loop begins.
func (AgentStarted) Kind ¶
func (AgentStarted) Kind() string
type AssistantDelta ¶
type AssistantDelta struct {
Event ai.AssistantEvent
Message ai.AssistantMessage
}
AssistantDelta forwards an incremental provider event with the current partial message.
func (AssistantDelta) Kind ¶
func (AssistantDelta) Kind() string
type AssistantFinished ¶
type AssistantFinished struct {
Message ai.AssistantMessage
}
AssistantFinished is emitted when the final assistant message is assembled.
func (AssistantFinished) Kind ¶
func (AssistantFinished) Kind() string
type AssistantStarted ¶
type AssistantStarted struct {
Message ai.AssistantMessage
}
AssistantStarted is emitted when assistant streaming begins.
func (AssistantStarted) Kind ¶
func (AssistantStarted) Kind() string
type CanonicalImageConfig ¶ added in v0.61.0
type CanonicalImageConfig struct {
Load MediaLoader
CanonicalizeToolResult ToolImageCanonicalizer
}
CanonicalImageConfig is the complete ordinary-session image policy. Keeping hydration and tool canonicalization together prevents invalid partial modes.
type LoopEvent ¶
type LoopEvent interface {
Kind() string
}
LoopEvent is the runtime event contract emitted by the agent loop.
type MediaLoader ¶ added in v0.61.0
MediaLoader opens one immutable session image for the current user. The implementation owns authorization and integrity verification.
type Option ¶
type Option func(*Runner)
Option configures optional Runner fields.
func WithCanonicalImages ¶ added in v0.61.0
func WithCanonicalImages(cfg CanonicalImageConfig) Option
WithCanonicalImages enables the complete durable ordinary-session image policy. Both callbacks are required so hydration and tool canonicalization cannot be configured independently.
func WithInterrupt ¶
func WithInterrupt(ch <-chan struct{}) Option
WithInterrupt sets an interrupt channel to stop the loop.
func WithStreamOptions ¶
func WithStreamOptions(opts ai.StreamOptions) Option
WithStreamOptions sets stream options (temperature, headers, etc.).
func WithToolLifecycle ¶
func WithToolLifecycle(tl *ToolLifecycle) Option
WithToolLifecycle sets optional tool lifecycle hooks for the loop.
type ProjectionError ¶ added in v0.61.0
type ProjectionError struct {
// contains filtered or unexported fields
}
ProjectionError identifies a broken canonical/provider boundary. Its detail is intentionally private: callers can classify only the exported sentinels.
func (*ProjectionError) Error ¶ added in v0.61.0
func (e *ProjectionError) Error() string
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner is a configured agent loop executor. It is safe for concurrent use. All configuration is set at construction time via RunnerConfig + options.
func NewRunner ¶
func NewRunner(cfg RunnerConfig, opts ...Option) (*Runner, error)
NewRunner constructs a Runner with the given config and options.
func (*Runner) Continue ¶
func (r *Runner) Continue(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)
Continue validates the history tail and resumes the agent loop.
func (*Runner) RunWithActiveStart ¶ added in v0.61.0
func (r *Runner) RunWithActiveStart(ctx context.Context, messages []ai.Message, activeStart int, emit func(LoopEvent)) ([]ai.Message, error)
RunWithActiveStart executes a loop with an explicit boundary between assembled history and the current turn. activeStart indexes messages before any synthetic progress nudges are inserted.
func (*Runner) SetHookMeta ¶
SetHookMeta updates the hook metadata (session/agent/user context). Safe to call between Run invocations; not safe during a Run.
type RunnerConfig ¶
type RunnerConfig struct {
Stream providers.StreamFunc
Model ai.Model
Tools ToolSet
ToolDefinitions []ai.ToolDefinition
}
RunnerConfig holds the required fields for constructing a Runner.
type ToolCallContext ¶
type ToolCallContext struct {
SessionID string
Channel string
UserID string
AgentID string
ToolName string
ToolCallID string
Arguments map[string]any
}
ToolCallContext describes one tool call before execution.
type ToolCallMutation ¶
ToolCallMutation describes how a pre-tool lifecycle hook changes execution.
type ToolFinished ¶
type ToolFinished struct {
Result ai.ToolResultMessage
}
ToolFinished is emitted when tool returns.
func (ToolFinished) Kind ¶
func (ToolFinished) Kind() string
type ToolFunc ¶
ToolFunc executes one tool invocation, returning its result as content blocks (text and/or images).
type ToolImageCanonicalizer ¶ added in v0.61.0
type ToolImageCanonicalizer func(context.Context, ai.ToolResultMessage) (ai.ToolResultMessage, error)
ToolImageCanonicalizer converts final tool images into durable references after lifecycle mutations and before the result enters the loop or history.
type ToolLifecycle ¶
type ToolLifecycle struct {
BeforeCall func(ctx context.Context, call ToolCallContext) (ToolCallMutation, error)
AfterCall func(ctx context.Context, result ToolResultContext) (ToolResultMutation, error)
}
ToolLifecycle carries optional tool-call lifecycle hooks for the agent loop.
type ToolResultContext ¶
type ToolResultContext struct {
SessionID string
Channel string
UserID string
AgentID string
ToolName string
ToolCallID string
Arguments map[string]any
Result string
IsError bool
Duration time.Duration
}
ToolResultContext describes one completed tool call.
type ToolResultMutation ¶
ToolResultMutation describes how a post-tool lifecycle hook changes the final result.
type ToolSet ¶
ToolSet maps tool names to handlers.
func ToolSetFromRegistry ¶
ToolSetFromRegistry builds a ToolSet from a tools.Registry. Every registered tool is included. The returned ToolSet dispatches calls through the registry's Execute method.
func ToolSetFromRegistryFiltered ¶
func ToolSetFromRegistryFiltered(reg *tools.Registry, names []string) (ToolSet, []tools.Definition, error)
ToolSetFromRegistryFiltered builds a ToolSet including only the named tools. Returns the matching definitions and an error if any name is not found.
type ToolStarted ¶
ToolStarted is emitted for each tool invocation.
func (ToolStarted) Kind ¶
func (ToolStarted) Kind() string
type TurnFinished ¶
type TurnFinished struct {
Turn int
}
TurnFinished is emitted at the end of each loop turn.
func (TurnFinished) Kind ¶
func (TurnFinished) Kind() string
type TurnStarted ¶
type TurnStarted struct {
Turn int
}
TurnStarted is emitted at the start of each loop turn.
func (TurnStarted) Kind ¶
func (TurnStarted) Kind() string