Documentation
¶
Overview ¶
Package hooks provides typed agent hook registration, emission, and loop Config bridging.
Index ¶
- Constants
- Variables
- func BridgeConfig(runCtx context.Context, reg *Registry, base msg.Config) msg.Config
- func ChainAfterToolCall(inner, outer msg.AfterToolCallFn) msg.AfterToolCallFn
- func ChainBeforeToolCall(inner, outer msg.BeforeToolCallFn) msg.BeforeToolCallFn
- func ChainPrepareNextTurn(inner, outer msg.PrepareNextTurnFn) msg.PrepareNextTurnFn
- func ChainTransformContext(inner, outer msg.TransformContextFn) msg.TransformContextFn
- func MergeHookFields(dst, src *msg.Config)
- func Observe(reg *Registry, handler observationHandler)
- func OnBeforeAgentStart(reg *Registry, handler beforeAgentStartHandler)
- func OnContext(reg *Registry, handler contextHandler)
- func OnObservation(reg *Registry, eventType string, ...)
- func OnToolCall(reg *Registry, handler toolCallHandler)
- func OnToolResult(reg *Registry, handler toolResultHandler)
- type BeforeAgentStartEvent
- type BeforeAgentStartResult
- type ContextEvent
- type ContextResult
- type ContextUsageInfo
- type ObservationEvent
- type Registry
- func (r *Registry) EmitBeforeAgentStart(ctx context.Context, event BeforeAgentStartEvent) (*BeforeAgentStartResult, error)
- func (r *Registry) EmitContext(ctx context.Context, messages []msg.AgentMessage) ([]msg.AgentMessage, error)
- func (r *Registry) EmitObservation(ctx context.Context, event ObservationEvent, logWarn func(string, ...any))
- func (r *Registry) EmitToolCall(ctx context.Context, event ToolCallEvent) (*ToolCallResult, error)
- func (r *Registry) EmitToolResult(ctx context.Context, event ToolResultEvent) (*ToolResultResult, error)
- func (r *Registry) HasHandlers() bool
- func (r *Registry) HasLoopHandlers() bool
- type ToolCallEvent
- type ToolCallResult
- type ToolResultEvent
- type ToolResultResult
Constants ¶
const ( EventBeforeAgentStart = "before_agent_start" EventContext = "context" EventToolCall = "tool_call" EventToolResult = "tool_result" EventSavePoint = "save_point" EventContextUsage = "context_usage" EventContextCompacted = "context_compacted" EventModelUpdate = "model_update" EventToolsUpdate = "tools_update" )
Event name constants for harness and observation hooks.
Variables ¶
var ErrRunCancelled = errors.New("agent hooks: run cancelled")
ErrRunCancelled indicates a hook cancelled the run before the agent loop started.
Functions ¶
func BridgeConfig ¶
BridgeConfig composes registry hook handlers onto an existing loop configuration.
func ChainAfterToolCall ¶
func ChainAfterToolCall(inner, outer msg.AfterToolCallFn) msg.AfterToolCallFn
ChainAfterToolCall runs inner before outer so hook patches apply after base patches.
func ChainBeforeToolCall ¶
func ChainBeforeToolCall(inner, outer msg.BeforeToolCallFn) msg.BeforeToolCallFn
ChainBeforeToolCall runs inner before outer and preserves the first block result.
func ChainPrepareNextTurn ¶
func ChainPrepareNextTurn(inner, outer msg.PrepareNextTurnFn) msg.PrepareNextTurnFn
ChainPrepareNextTurn runs inner before outer at turn boundaries.
func ChainTransformContext ¶
func ChainTransformContext(inner, outer msg.TransformContextFn) msg.TransformContextFn
ChainTransformContext runs inner before outer so base transforms apply before hook transforms.
func MergeHookFields ¶
MergeHookFields copies hook-related callbacks from src onto dst without replacing queue drains.
func Observe ¶
func Observe(reg *Registry, handler observationHandler)
Observe registers a read-only listener for harness observation events.
func OnBeforeAgentStart ¶
func OnBeforeAgentStart(reg *Registry, handler beforeAgentStartHandler)
OnBeforeAgentStart registers a handler that can mutate prompts before a run.
func OnContext ¶
func OnContext(reg *Registry, handler contextHandler)
OnContext registers a handler that transforms messages before each LLM call.
func OnObservation ¶
func OnObservation(reg *Registry, eventType string, handler func(context.Context, ObservationEvent) error)
OnObservation registers an observer filtered to a single event type.
func OnToolCall ¶
func OnToolCall(reg *Registry, handler toolCallHandler)
OnToolCall registers a handler that can block tool execution.
func OnToolResult ¶
func OnToolResult(reg *Registry, handler toolResultHandler)
OnToolResult registers a handler that can patch tool results.
Types ¶
type BeforeAgentStartEvent ¶
type BeforeAgentStartEvent struct {
Messages []msg.AgentMessage
SystemPrompt string
ModelName string
}
BeforeAgentStartEvent fires before an agent run begins.
type BeforeAgentStartResult ¶
type BeforeAgentStartResult struct {
Messages []msg.AgentMessage
SystemPrompt *string
Cancel bool
}
BeforeAgentStartResult can mutate prompts or cancel the run.
type ContextEvent ¶
type ContextEvent struct {
Messages []msg.AgentMessage
}
ContextEvent fires before each LLM request with the working message list.
type ContextResult ¶
type ContextResult struct {
Messages []msg.AgentMessage
}
ContextResult replaces the message list when Messages is non-nil.
type ContextUsageInfo ¶
ContextUsageInfo reports estimated context consumption for observation hooks.
type ObservationEvent ¶
type ObservationEvent struct {
Type string
Messages []msg.AgentMessage
SystemPrompt string
ModelName string
ActiveTools []string
ContextUsage *ContextUsageInfo
}
ObservationEvent is a read-only harness notification delivered to Observe handlers.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry stores typed hook handlers and observation listeners.
func (*Registry) EmitBeforeAgentStart ¶
func (r *Registry) EmitBeforeAgentStart(ctx context.Context, event BeforeAgentStartEvent) (*BeforeAgentStartResult, error)
EmitBeforeAgentStart runs before_agent_start handlers and merges results.
func (*Registry) EmitContext ¶
func (r *Registry) EmitContext(ctx context.Context, messages []msg.AgentMessage) ([]msg.AgentMessage, error)
EmitContext runs context handlers and chains message replacements.
func (*Registry) EmitObservation ¶
func (r *Registry) EmitObservation(ctx context.Context, event ObservationEvent, logWarn func(string, ...any))
EmitObservation notifies observers and logs handler errors without failing the run.
func (*Registry) EmitToolCall ¶
func (r *Registry) EmitToolCall(ctx context.Context, event ToolCallEvent) (*ToolCallResult, error)
EmitToolCall runs tool_call handlers and stops on the first block.
func (*Registry) EmitToolResult ¶
func (r *Registry) EmitToolResult(ctx context.Context, event ToolResultEvent) (*ToolResultResult, error)
EmitToolResult runs tool_result handlers and merges patches.
func (*Registry) HasHandlers ¶
HasHandlers reports whether any hook or observer is registered.
func (*Registry) HasLoopHandlers ¶
HasLoopHandlers reports whether any loop-bridging hook handler is registered.
type ToolCallEvent ¶
type ToolCallEvent struct {
Assistant msg.AssistantMessage
ToolCall msg.ToolCallPart
Args map[string]any
Context *msg.Context
}
ToolCallEvent fires before a tool executes.
type ToolCallResult ¶
ToolCallResult can block tool execution.
type ToolResultEvent ¶
type ToolResultEvent struct {
Assistant msg.AssistantMessage
ToolCall msg.ToolCallPart
Args map[string]any
Result msg.ToolResultMessage
Context *msg.Context
}
ToolResultEvent fires after a tool executes.
type ToolResultResult ¶
type ToolResultResult struct {
Parts []msg.ContentPart
IsError *bool
Terminate bool
}
ToolResultResult patches tool output or requests early loop termination.
Source Files