Documentation
¶
Index ¶
- Constants
- Variables
- func NormalizeToolResult(result ai.ToolResultMessage) ai.ToolResultMessage
- type AgentErrored
- type AgentFinished
- type AgentStarted
- type AssistantDelta
- type AssistantFinished
- type AssistantStarted
- type CanonicalImageConfig
- type ChildToolFinished
- type ChildToolStarted
- type CodeToolSurface
- type LoopEvent
- type MediaLoader
- type Option
- func WithCanonicalImages(cfg CanonicalImageConfig) Option
- func WithCodeToolSurface(surface CodeToolSurface) 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) SetSecretValues(values []string)
- 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 ¶
const CodeToolName = "code"
CodeToolName is the one provider-facing entry point for every tool outside the hot set. It is exported because callers outside this package (tests, tracing, docs guards) must name the tool the model reaches them through.
Variables ¶
var ( ErrAssistantImageBlock = projectionError("assistant image block is invalid") ErrImageRefUnresolved = projectionError("image reference reached provider boundary") ErrUnsupportedImage = projectionError("unsupported model received image content") )
var HotToolNames = []string{"bash", "memory_read", "memory_search", "skill_load", "view_image"}
HotToolNames is the Code Mode hot set: the tools worth putting in front of the model every turn instead of behind tools.search. It is small on purpose, and it is exported because the system prompt and the configuration docs quote it — a guard can compare prose against this list rather than against a copy.
Recall is two tools now, not one union, so both memory names are hot: a model that can search but not read a returned ref cannot finish a recall (rules/agent-tools.md §8).
Functions ¶
func NormalizeToolResult ¶ added in v0.66.0
func NormalizeToolResult(result ai.ToolResultMessage) ai.ToolResultMessage
NormalizeToolResult removes render-reference sentinels from every text block and carries their deduplicated references on the result sideband. It is safe to call again at event boundaries, which keeps native and code paths aligned.
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 ChildToolFinished ¶ added in v0.66.0
type ChildToolFinished struct {
ParentToolCallID string
Result ai.ToolResultMessage
}
ChildToolFinished is emitted for every settled Code child attempt, including policy blocks and missing tools. It is runtime-only and has no storage form.
func (ChildToolFinished) Kind ¶ added in v0.66.0
func (ChildToolFinished) Kind() string
type ChildToolStarted ¶ added in v0.66.0
ChildToolStarted is emitted when an outer Code call reaches a child handler. Runtime adapters may render it, but must never persist it as provider history.
func (ChildToolStarted) Kind ¶ added in v0.66.0
func (ChildToolStarted) Kind() string
type CodeToolSurface ¶ added in v0.66.0
type CodeToolSurface string
CodeToolSurface selects which effective tools remain provider-visible in Code Mode. Hot is the production default; Bash and Only exist for controlled behavior evaluation on the same binary.
const ( CodeToolSurfaceHot CodeToolSurface = "hot" CodeToolSurfaceBash CodeToolSurface = "bash" CodeToolSurfaceOnly CodeToolSurface = "only" )
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 WithCodeToolSurface ¶ added in v0.66.0
func WithCodeToolSurface(surface CodeToolSurface) Option
WithCodeToolSurface selects the provider-visible subset used by Code Mode. The zero value keeps the production hot-tool surface.
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.
func (*Runner) SetSecretValues ¶ added in v0.66.0
SetSecretValues replaces the exact runtime credentials removed from script-visible child event arguments. Safe between Run invocations only.
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