Class: SwarmSDK::Swarm::ToolConfigurator

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/swarm/tool_configurator.rb

Overview

Handles tool creation, registration, and permissions wrapping

Responsibilities:

  • Register explicit tools for agents
  • Register default tools (Read, Grep, Glob, etc.)
  • Create tool instances (with agent context)
  • Wrap tools with permissions validators

This encapsulates all tool-related logic that was previously in Swarm.

Constant Summary collapse

DEFAULT_TOOLS =

Default tools available to all agents (unless disable_default_tools is set)

[
  :Read,
  :Grep,
  :Glob,
].freeze
SCRATCHPAD_TOOLS =

Scratchpad tools (added if scratchpad is enabled)

[
  :ScratchpadWrite,
  :ScratchpadRead,
  :ScratchpadList,
].freeze
FILESYSTEM_TOOLS =

Filesystem tools that can be globally disabled for security

[
  :Read,
  :Write,
  :Edit,
  :MultiEdit,
  :Grep,
  :Glob,
  :Bash,
].freeze

Instance Method Summary collapse

Constructor Details

#initialize(swarm, scratchpad_storage, plugin_storages = {}) ⇒ ToolConfigurator

Returns a new instance of ToolConfigurator.



40
41
42
43
44
45
46
 
# File 'lib/swarm_sdk/swarm/tool_configurator.rb', line 40

def initialize(swarm, scratchpad_storage, plugin_storages = {})
  @swarm = swarm
  @scratchpad_storage = scratchpad_storage
  # Plugin storages: { plugin_name => { agent_name => storage } }
  # e.g., { memory: { agent1: storage1, agent2: storage2 } }
  @plugin_storages = plugin_storages
end

Instance Method Details

#create_tool_instance(tool_name, agent_name, directory, chat: nil, agent_definition: nil) ⇒ RubyLLM::Tool

Create a tool instance by name

Uses the Registry factory pattern to instantiate tools based on their declared requirements. This eliminates the need for a giant case statement.

Tool lookup order:

  1. Plugin tools (registered via SwarmSDK::PluginRegistry)
  2. Custom tools (registered via SwarmSDK.register_tool)
  3. Built-in tools (SwarmSDK::Tools::Registry)

File tools and TodoWrite require agent context for tracking state. Scratchpad tools require shared scratchpad instance. Plugin tools are delegated to their respective plugins.

This method is public for testing delegation from Swarm.

Parameters:

  • tool_name (Symbol, String) —

    Tool name

  • agent_name (Symbol) —

    Agent name for context

  • directory (String) —

    Agent's working directory

  • chat (Agent::Chat, nil) (defaults to: nil) —

    Optional chat instance for tools that need it

  • agent_definition (Agent::Definition, nil) (defaults to: nil) —

    Optional agent definition

Returns:

  • (RubyLLM::Tool) —

    Tool instance



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/swarm_sdk/swarm/tool_configurator.rb', line 80

def create_tool_instance(tool_name, agent_name, directory, chat: nil, agent_definition: nil)
  tool_name_sym = tool_name.to_sym

  # Check if tool is provided by a plugin
  if PluginRegistry.plugin_tool?(tool_name_sym)
    return create_plugin_tool(tool_name_sym, agent_name, directory, chat, agent_definition)
  end

  # Check if tool is a custom registered tool
  if CustomToolRegistry.registered?(tool_name_sym)
    context = {
      agent_name: agent_name,
      directory: directory,
    }
    return CustomToolRegistry.create(tool_name_sym, context)
  end

  # Use Registry factory pattern for built-in tools
  context = {
    agent_name: agent_name,
    directory: directory,
    scratchpad_storage: @scratchpad_storage,
  }

  Tools::Registry.create(tool_name_sym, context)
end

#register_all_tools(chat:, agent_name:, agent_definition:) ⇒ Object

Register all tools for an agent (both explicit and default)

Parameters:

  • chat (AgentChat) —

    The chat instance to register tools with

  • agent_name (Symbol) —

    Name of the agent

  • agent_definition (AgentDefinition) —

    Agent definition object



53
54
55
56
 
# File 'lib/swarm_sdk/swarm/tool_configurator.rb', line 53

def register_all_tools(chat:, agent_name:, agent_definition:)
  register_explicit_tools(chat, agent_definition.tools, agent_name: agent_name, agent_definition: agent_definition)
  register_default_tools(chat, agent_name: agent_name, agent_definition: agent_definition)
end

#wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition) ⇒ RubyLLM::Tool

Wrap a tool instance with permissions validator if configured

This method is public for testing delegation from Swarm.

Parameters:

  • tool_instance (RubyLLM::Tool) —

    Tool instance to wrap

  • permissions_config (Hash, nil) —

    Permission configuration

  • agent_definition (AgentDefinition) —

    Agent definition

Returns:

  • (RubyLLM::Tool) —

    Either the wrapped tool or original tool



115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/swarm_sdk/swarm/tool_configurator.rb', line 115

def wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
  # Skip wrapping if no permissions or agent bypasses permissions
  return tool_instance unless permissions_config
  return tool_instance if agent_definition.bypass_permissions

  # Create permissions config and wrap tool with validator
  permissions = Permissions::Config.new(
    permissions_config,
    base_directory: agent_definition.directory,
  )

  Permissions::Validator.new(tool_instance, permissions)
end