agent

package
v0.66.1 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
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

View Source
var (
	ErrAssistantImageBlock = projectionError("assistant image block is invalid")
	ErrImageRefUnresolved  = projectionError("image reference reached provider boundary")
	ErrUnsupportedImage    = projectionError("unsupported model received image content")
)
View Source
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

type ChildToolStarted struct {
	ParentToolCallID string
	ToolCall         ai.ToolCall
}

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

type MediaLoader func(context.Context, string) (ai.ImageContent, error)

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 WithHooks

func WithHooks(hs *hooks.HookSet, meta hooks.HookMeta) Option

WithHooks sets the hook set and metadata for the loop.

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 WithSystem

func WithSystem(s string) Option

WithSystem sets the system prompt.

func WithToolLifecycle

func WithToolLifecycle(tl *ToolLifecycle) Option

WithToolLifecycle sets optional tool lifecycle hooks for the loop.

func WithTurnNotify added in v0.26.0

func WithTurnNotify(fn func(turn int, elapsed time.Duration) *string) Option

WithTurnNotify sets a callback invoked at the start of each turn. If it returns a non-nil string, that text is injected as a UserMessage before the model call for that turn.

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

func (r *Runner) SetHookMeta(meta hooks.HookMeta)

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

func (r *Runner) SetSecretValues(values []string)

SetSecretValues replaces the exact runtime credentials removed from script-visible child event arguments. Safe between Run invocations only.

func (*Runner) SetTurnNotify added in v0.26.0

func (r *Runner) SetTurnNotify(fn func(turn int, elapsed time.Duration) *string)

SetTurnNotify updates the turn notify callback. 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

type ToolCallMutation struct {
	Arguments    map[string]any
	Block        bool
	BlockMessage string
}

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

type ToolFunc func(ctx context.Context, call ai.ToolCall) ([]ai.ContentBlock, error)

ToolFunc executes one tool invocation, returning its result as content blocks (text and/or images).

func WrapTool

func WrapTool(t tools.Tool) ToolFunc

WrapTool adapts a single tools.Tool into a ToolFunc.

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

type ToolResultMutation struct {
	Result  *string
	IsError *bool
}

ToolResultMutation describes how a post-tool lifecycle hook changes the final result.

type ToolSet

type ToolSet map[string]ToolFunc

ToolSet maps tool names to handlers.

func ToolSetFromRegistry

func ToolSetFromRegistry(reg *tools.Registry) ToolSet

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

type ToolStarted struct {
	ToolCall ai.ToolCall
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL