Documentation
¶
Index ¶
- Constants
- func Execute(ctx context.Context, event EventType, data map[string]interface{}) error
- func ExecuteAsync(ctx context.Context, event EventType, data map[string]interface{})
- func FormatEvent(event Event) string
- func LoadHooksDir(dir string) error
- func Register(h Hook)
- func RegisterDecisionHook(fn DecisionHookFn)
- func ResetDecisionHooks()
- type DecisionHookFn
- type Event
- type EventBus
- func (eb *EventBus) Emit(event Event)
- func (eb *EventBus) GetHistory(eventType string, limit int) []Event
- func (eb *EventBus) OnError(fn func(err error))
- func (eb *EventBus) OnFileWrite(fn func(path string))
- func (eb *EventBus) OnSessionEnd(fn func(duration time.Duration, tokens int))
- func (eb *EventBus) OnToolCall(fn func(tool string, duration time.Duration))
- func (eb *EventBus) Register(hook *LifecycleHook)
- func (eb *EventBus) Stats() EventStats
- func (eb *EventBus) Subscribe(eventType string) <-chan Event
- func (eb *EventBus) Unregister(hookID string)
- func (eb *EventBus) Unsubscribe(eventType string, ch <-chan Event)
- type EventStats
- type EventType
- type Hook
- type HookDecision
- type LifecycleHook
- type Registry
Constants ¶
const ( SessionStart = "session.start" SessionEnd = "session.end" TurnStart = "turn.start" TurnEnd = "turn.end" ToolCallStart = "tool_call.start" ToolCallEnd = "tool_call.end" ToolCallError = "tool_call.error" FileRead = "file.read" FileWrite = "file.write" FileEdit = "file.edit" FileDelete = "file.delete" CompactionStart = "compaction.start" CompactionEnd = "compaction.end" BudgetWarning = "budget.warning" BudgetExceeded = "budget.exceeded" ErrorOccurred = "error.occurred" ErrorRecovered = "error.recovered" ModelSwitch = "model.switch" ProviderSwitch = "provider.switch" UserInput = "user.input" AgentResponse = "agent.response" )
LifecycleEventType constants representing agent lifecycle events.
Variables ¶
This section is empty.
Functions ¶
func ExecuteAsync ¶
ExecuteAsync runs hooks asynchronously on the global registry.
func FormatEvent ¶ added in v0.2.0
FormatEvent returns a human-readable log line for the event.
func RegisterDecisionHook ¶
func RegisterDecisionHook(fn DecisionHookFn)
RegisterDecisionHook adds a decision hook to the global list.
func ResetDecisionHooks ¶
func ResetDecisionHooks()
ResetDecisionHooks clears all registered decision hooks. Intended for testing.
Types ¶
type DecisionHookFn ¶
type DecisionHookFn func(event string, data map[string]interface{}) *HookDecision
DecisionHookFn is a function that inspects an event and optionally returns a decision. Returning nil means "no opinion" (proceed normally).
type EventBus ¶ added in v0.2.0
type EventBus struct {
Hooks map[string][]*LifecycleHook
Listeners map[string][]chan Event
History []Event
MaxHistory int
// contains filtered or unexported fields
}
EventBus is the central publish/subscribe mechanism for lifecycle events.
func NewEventBus ¶ added in v0.2.0
func NewEventBus() *EventBus
NewEventBus creates a new EventBus with sensible defaults.
func (*EventBus) Emit ¶ added in v0.2.0
Emit fires all hooks for the event type and sends to listeners. Synchronous hooks run in priority order; async hooks run in goroutines.
func (*EventBus) GetHistory ¶ added in v0.2.0
GetHistory returns the most recent events of the given type, limited to `limit`. If eventType is empty, all events are considered.
func (*EventBus) OnError ¶ added in v0.2.0
OnError registers a convenience hook that fires on ErrorOccurred events.
func (*EventBus) OnFileWrite ¶ added in v0.2.0
OnFileWrite registers a convenience hook that fires on FileWrite events.
func (*EventBus) OnSessionEnd ¶ added in v0.2.0
OnSessionEnd registers a convenience hook that fires when a session ends.
func (*EventBus) OnToolCall ¶ added in v0.2.0
OnToolCall registers a convenience hook that fires when a tool call completes.
func (*EventBus) Register ¶ added in v0.2.0
func (eb *EventBus) Register(hook *LifecycleHook)
Register adds a hook to the bus for its configured event type.
func (*EventBus) Stats ¶ added in v0.2.0
func (eb *EventBus) Stats() EventStats
Stats returns aggregate statistics about the event bus.
func (*EventBus) Subscribe ¶ added in v0.2.0
Subscribe returns a channel that receives events of the given type.
func (*EventBus) Unregister ¶ added in v0.2.0
Unregister removes a hook by its ID from all event types.
func (*EventBus) Unsubscribe ¶ added in v0.2.0
Unsubscribe removes a previously subscribed channel.
type EventStats ¶ added in v0.2.0
type EventStats struct {
TotalEvents int
ByType map[string]int
HookCount int
AsyncHooks int
AvgHookTime time.Duration
}
EventStats provides aggregate statistics about the event bus.
type EventType ¶
type EventType string
EventType represents a hook event.
const ( EventPreQuery EventType = "pre_query" EventPostQuery EventType = "post_query" EventPreTool EventType = "pre_tool" EventPostTool EventType = "post_tool" EventPreCompact EventType = "pre_compact" EventPostCompact EventType = "post_compact" EventFileChanged EventType = "file_changed" EventSessionStart EventType = "session_start" EventSessionEnd EventType = "session_end" EventPermissionAsk EventType = "permission_ask" EventError EventType = "error" )
type Hook ¶
type Hook struct {
Name string
Event EventType
Priority int // lower = earlier
Fn func(ctx context.Context, data map[string]interface{}) error
}
Hook is a registered hook function.
func BuiltinHooks ¶
func BuiltinHooks() []Hook
BuiltinHooks returns the default set of built-in hooks.
type HookDecision ¶
type HookDecision struct {
Action string `json:"action"` // "allow", "deny", "modify"
Reason string `json:"reason,omitempty"`
ModifiedInput json.RawMessage `json:"modified_input,omitempty"`
}
HookDecision represents the outcome of a decision hook.
func ExecuteDecisionHooks ¶
func ExecuteDecisionHooks(event string, data map[string]interface{}) *HookDecision
ExecuteDecisionHooks runs all registered decision hooks for the given event. It returns the first non-nil decision. If all hooks return nil, the result is nil (meaning no opinion, proceed normally).
type LifecycleHook ¶ added in v0.2.0
type LifecycleHook struct {
ID string
Name string
Event string
Handler func(Event) error
Priority int
Async bool
Enabled bool
}
LifecycleHook is a registered handler for lifecycle events on the EventBus.
Source Files