hooks

Documentation

Overview

Package hooks provides an event-driven lifecycle hook system for Roger.

Hooks allow external plugins and internal subsystems to react to key events in the agent lifecycle (model resolution, prompt building, tool calls, message delivery, session management, gateway events).

Usage:

bus := hooks.New()
bus.On(hooks.BeforeModelResolve, func(ctx context.Context, e hooks.Event) error {
    log.Infof("resolving model for session %s", e.SessionKey)
    return nil
})
bus.Emit(ctx, hooks.Event{Type: hooks.BeforeModelResolve, SessionKey: key})

Index

• type Bus
  • func New(logger *zap.SugaredLogger) *Bus
  • func (b *Bus) Emit(ctx context.Context, e Event)
  • func (b *Bus) EmitAsync(ctx context.Context, e Event)
  • func (b *Bus) HandlerCount(eventType EventType) int
  • func (b *Bus) HasHandlers(eventType EventType) bool
  • func (b *Bus) Off(eventType EventType, name string)
  • func (b *Bus) On(eventType EventType, name string, fn Handler)
• type Event
• type EventType
• type Handler

Types

type Bus

type Bus struct {
	// contains filtered or unexported fields
}

Bus is the central event dispatcher. Thread-safe.

func New

func New(logger *zap.SugaredLogger) *Bus

New creates an empty hook bus.

func (*Bus) Emit

func (b *Bus) Emit(ctx context.Context, e Event)

Emit dispatches an event to all registered handlers synchronously. Each handler is called in registration order. Errors are logged but do not prevent subsequent handlers from running.

func (*Bus) EmitAsync

func (b *Bus) EmitAsync(ctx context.Context, e Event)

EmitAsync dispatches an event to all registered handlers in parallel. Errors are logged. The method blocks until all handlers complete or the context is cancelled.

func (*Bus) HandlerCount

func (b *Bus) HandlerCount(eventType EventType) int

HandlerCount returns the number of handlers registered for an event type.

func (*Bus) HasHandlers

func (b *Bus) HasHandlers(eventType EventType) bool

HasHandlers returns true if at least one handler is registered for the event.

func (*Bus) Off

func (b *Bus) Off(eventType EventType, name string)

Off removes all handlers with the given name from a specific event type.

func (*Bus) On

func (b *Bus) On(eventType EventType, name string, fn Handler)

On registers a handler for a specific event type. name is used for logging and debugging; it need not be unique.

type Event

type Event struct {
	Type       EventType
	SessionKey string
	AgentID    string
	Model      string
	ToolName   string
	Channel    string         // "telegram", "discord", "slack", "gateway"
	Data       map[string]any // extensible payload
	Timestamp  time.Time
}

Event carries data for a lifecycle hook invocation.

type EventType

type EventType string

EventType identifies the lifecycle event.

const (
	// Model lifecycle
	BeforeModelResolve EventType = "before_model_resolve"
	AfterModelResolve  EventType = "after_model_resolve"

	// Prompt lifecycle
	BeforePromptBuild EventType = "before_prompt_build"
	AfterPromptBuild  EventType = "after_prompt_build"

	// Tool lifecycle
	BeforeToolCall EventType = "before_tool_call"
	AfterToolCall  EventType = "after_tool_call"

	// Message lifecycle
	BeforeMessageSend  EventType = "before_message_send"
	AfterMessageSend   EventType = "after_message_send"
	BeforeMessageStore EventType = "before_message_store"

	// Session lifecycle
	SessionCreated EventType = "session_created"
	SessionReset   EventType = "session_reset"
	SessionPruned  EventType = "session_pruned"

	// Gateway lifecycle
	GatewayStarted EventType = "gateway_started"
	GatewayStopped EventType = "gateway_stopped"
)

type Handler

type Handler func(ctx context.Context, e Event) error

Handler is a function called when an event fires. Returning an error logs a warning but does not abort the operation.