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 ChainBeforeProviderRequest(inner, outer msg.BeforeProviderRequestFn) msg.BeforeProviderRequestFn
- 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 OnBeforeProviderRequest(reg *Registry, handler beforeProviderRequestHandler)
- func OnContext(reg *Registry, handler contextHandler)
- func OnObservation(reg *Registry, eventType string, ...)
- func OnSessionBeforeCompact(reg *Registry, handler sessionBeforeCompactHandler)
- func OnSessionBeforeTree(reg *Registry, handler sessionBeforeTreeHandler)
- func OnToolCall(reg *Registry, handler toolCallHandler)
- func OnToolResult(reg *Registry, handler toolResultHandler)
- type BeforeAgentStartEvent
- type BeforeAgentStartResult
- type BeforeProviderRequestEvent
- type BeforeProviderRequestResult
- type ContextEvent
- type ContextResult
- type ContextUsageInfo
- type ObservationEvent
- type Registry
- func (r *Registry) EmitBeforeAgentStart(ctx context.Context, event BeforeAgentStartEvent) (*BeforeAgentStartResult, error)
- func (r *Registry) EmitBeforeProviderRequest(ctx context.Context, event BeforeProviderRequestEvent) (*BeforeProviderRequestResult, 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) EmitSessionBeforeCompact(ctx context.Context, event SessionBeforeCompactEvent) (*SessionBeforeCompactResult, error)
- func (r *Registry) EmitSessionBeforeTree(ctx context.Context, event SessionBeforeTreeEvent) (*SessionBeforeTreeResult, error)
- 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
- func (r *Registry) HasSessionHandlers() bool
- type SessionBeforeCompactEvent
- type SessionBeforeCompactResult
- type SessionBeforeTreeEvent
- type SessionBeforeTreeResult
- type ToolCallEvent
- type ToolCallResult
- type ToolResultEvent
- type ToolResultResult
Constants ¶
const ( EventBeforeAgentStart = "before_agent_start" EventContext = "context" EventBeforeProviderRequest = "before_provider_request" EventToolCall = "tool_call" EventToolResult = "tool_result" EventSessionBeforeCompact = "session_before_compact" EventSessionBeforeTree = "session_before_tree" 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 ChainBeforeProviderRequest ¶
func ChainBeforeProviderRequest(inner, outer msg.BeforeProviderRequestFn) msg.BeforeProviderRequestFn
ChainBeforeProviderRequest runs inner before outer so base patches apply before hook 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 OnBeforeProviderRequest ¶
func OnBeforeProviderRequest(reg *Registry, handler beforeProviderRequestHandler)
OnBeforeProviderRequest registers a handler that patches LLM stream options.
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 OnSessionBeforeCompact ¶
func OnSessionBeforeCompact(reg *Registry, handler sessionBeforeCompactHandler)
OnSessionBeforeCompact registers a handler that can cancel or customize compaction.
func OnSessionBeforeTree ¶
func OnSessionBeforeTree(reg *Registry, handler sessionBeforeTreeHandler)
OnSessionBeforeTree registers a handler that can cancel or customize branch summary.
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 BeforeProviderRequestEvent ¶
type BeforeProviderRequestEvent struct {
ModelName string
Options msg.ProviderRequestOptions
}
BeforeProviderRequestEvent fires after stream options are built and before the LLM call.
type BeforeProviderRequestResult ¶
type BeforeProviderRequestResult struct {
Options *msg.ProviderRequestOptions
}
BeforeProviderRequestResult replaces stream options when Options is non-nil.
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) EmitBeforeProviderRequest ¶
func (r *Registry) EmitBeforeProviderRequest(ctx context.Context, event BeforeProviderRequestEvent) (*BeforeProviderRequestResult, error)
EmitBeforeProviderRequest runs before_provider_request handlers and chains option patches.
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) EmitSessionBeforeCompact ¶
func (r *Registry) EmitSessionBeforeCompact(ctx context.Context, event SessionBeforeCompactEvent) (*SessionBeforeCompactResult, error)
EmitSessionBeforeCompact runs session_before_compact handlers (first cancel, else last compaction).
func (*Registry) EmitSessionBeforeTree ¶
func (r *Registry) EmitSessionBeforeTree(ctx context.Context, event SessionBeforeTreeEvent) (*SessionBeforeTreeResult, error)
EmitSessionBeforeTree runs session_before_tree handlers (first cancel, else last summary).
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.
func (*Registry) HasSessionHandlers ¶
HasSessionHandlers reports whether any session compact/tree hook is registered.
type SessionBeforeCompactEvent ¶
type SessionBeforeCompactEvent struct {
Preparation *ctxmgr.CompactionPreparation
BranchEntries []session.TreeEntry
Reason ctxmgr.CompactReason
WillRetry bool
}
SessionBeforeCompactEvent fires after compaction preparation and before summarization.
type SessionBeforeCompactResult ¶
type SessionBeforeCompactResult struct {
Cancel bool
Compaction *ctxmgr.CompactionResult
}
SessionBeforeCompactResult can cancel compaction or supply a custom summary.
type SessionBeforeTreeEvent ¶
type SessionBeforeTreeEvent struct {
TargetEntryID string
OldLeafID string
CommonAncestorID string
EntriesToSummarize []session.TreeEntry
UserWantsSummary bool
}
SessionBeforeTreeEvent fires before auto branch summarization on MoveTo.
type SessionBeforeTreeResult ¶
SessionBeforeTreeResult can cancel navigation summarization or supply a custom summary.
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 ¶
type ToolCallResult struct {
Block bool
Reason string
// Terminate stops the agent loop after delivering the blocked tool result.
Terminate bool
}
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