Class: SwarmSDK::Hooks::Registry

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/hooks/registry.rb

Overview

Central registry for managing named hooks and swarm-level defaults

The Registry stores:

  • Named hooks that can be referenced by symbol in YAML or code
  • Swarm-level default hooks that apply to all agents

Examples:

Register a named hook

registry = SwarmSDK::Hooks::Registry.new
registry.register(:validate_code) do |context|
  raise SwarmSDK::Hooks::Error, "Invalid code" unless valid?(context.tool_call)
end

Add swarm-level default

registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |context|
  puts "Tool #{context.tool_call.name} called by #{context.agent_name}"
end

Constant Summary collapse

VALID_EVENTS =

Available hook event types

[
  # Swarm lifecycle events
  :swarm_start,       # When Swarm.execute is called (before first user message)
  :swarm_stop,        # When Swarm.execute completes (after execution)
  :first_message,     # When first user message is sent to swarm (Swarm.execute)

  # Agent/LLM events
  :user_prompt,       # Before sending user message to LLM
  :agent_step,        # After agent makes intermediate response with tool calls
  :agent_stop,        # After agent completes with final response (no more tool calls)

  # Tool events
  :pre_tool_use,      # Before tool execution (can block/modify)
  :post_tool_use,     # After tool execution

  # Delegation events
  :pre_delegation,    # Before delegating to another agent
  :post_delegation,   # After delegation completes

  # Context events
  :context_warning, # When context usage crosses threshold

  # Debug events
  :breakpoint_enter,  # When entering interactive debugging (binding.irb)
  :breakpoint_exit,   # When exiting interactive debugging
].freeze

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Registry

Returns a new instance of Registry.



50
51
52
53
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 50

def initialize
  @named_hooks = {} # { hook_name: proc }
  @defaults = Hash.new { |h, k| h[k] = [] } # { event_type: [Definition, ...] }
end

Instance Method Details

#add_default(event, matcher: nil, priority: 0, &block) ⇒ Object

Add a swarm-level default hook

These hooks apply to all agents unless overridden at agent level.

Examples:

Add default logging

registry.add_default(:pre_tool_use) { |ctx| log(ctx) }

Add validation for specific tools

registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |ctx|
  validate_tool_call(ctx.tool_call)
end

Parameters:

  • event (Symbol) —

    Event type (must be in VALID_EVENTS)

  • matcher (String, Regexp, nil) (defaults to: nil) —

    Optional regex pattern to match tool names

  • priority (Integer) (defaults to: 0) —

    Execution priority (higher runs first)

  • block (Proc) —

    Hook implementation

Raises:

  • (ArgumentError) —

    if event invalid or block missing



96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 96

def add_default(event, matcher: nil, priority: 0, &block)
  validate_event!(event)
  raise ArgumentError, "Block required" unless block

  definition = Definition.new(
    event: event,
    matcher: matcher,
    priority: priority,
    proc: block,
  )

  @defaults[event] << definition
  @defaults[event].sort_by! { |d| -d.priority } # Higher priority first
end

#get(name) ⇒ Proc?

Get a named hook by symbol

Parameters:

  • name (Symbol) —

    Hook name

Returns:

  • (Proc, nil) —

    The hook proc or nil if not found



75
76
77
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 75

def get(name)
  @named_hooks[name]
end

#get_defaults(event) ⇒ Array<Definition>

Get all default hooks for an event type

Parameters:

  • event (Symbol) —

    Event type

Returns:

  • (Array<Definition>) —

    List of hook definitions



115
116
117
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 115

def get_defaults(event)
  @defaults[event]
end

#named_hooks ⇒ Array<Symbol>

Get all registered named hook names

Returns:

  • (Array<Symbol>) —

    List of hook names



122
123
124
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 122

def named_hooks
  @named_hooks.keys
end

#register(name, &block) ⇒ Object

Register a named hook that can be referenced elsewhere

Examples:

registry.register(:log_tool_use) { |ctx| puts "Tool: #{ctx.tool_call.name}" }

Parameters:

  • name (Symbol) —

    Unique name for this hook

  • block (Proc) —

    Hook implementation

Raises:

  • (ArgumentError) —

    if name already registered or invalid



63
64
65
66
67
68
69
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 63

def register(name, &block)
  raise ArgumentError, "Hook name must be a symbol" unless name.is_a?(Symbol)
  raise ArgumentError, "Hook #{name} already registered" if @named_hooks.key?(name)
  raise ArgumentError, "Block required" unless block

  @named_hooks[name] = block
end

#registered?(name) ⇒ Boolean

Check if a hook name is registered

Parameters:

  • name (Symbol) —

    Hook name

Returns:

  • (Boolean) —

    true if registered



130
131
132
 
# File 'lib/swarm_sdk/hooks/registry.rb', line 130

def registered?(name)
  @named_hooks.key?(name)
end