claude_swarm 1.0.0 → 1.0.2

data/lib/swarm_sdk/permissions/error_formatter.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # ErrorFormatter generates user-friendly error messages for permission violations
+    class ErrorFormatter
+      class << self
+        # Generate a permission denied error message
+        #
+        # @param path [String] The path that was denied
+        # @param allowed_patterns [Array<String>] List of allowed path patterns
+        # @param denied_patterns [Array<String>] List of denied path patterns
+        # @param matching_pattern [String, nil] The specific pattern that blocked this path
+        # @param tool_name [String] Name of the tool that was denied
+        # @return [String] Formatted error message with system reminder
+        def permission_denied(path:, allowed_patterns:, denied_patterns: [], matching_pattern: nil, tool_name:)
+          operation_verb = case tool_name.to_s
+          when "Read" then "read"
+          when "Write" then "write to"
+          when "Edit", "MultiEdit" then "edit"
+          when "Glob" then "access directory"
+          when "Grep" then "search in"
+          else "access"
+          end
+
+          # Build policy explanation
+          policy_info = if matching_pattern && matching_pattern != "(not in allowed list)"
+            # Show the specific denied pattern that blocked this path
+            "Blocked by policy: #{matching_pattern}"
+          elsif matching_pattern == "(not in allowed list)" && allowed_patterns.any?
+            # Show allowed patterns when path doesn't match any
+            patterns = allowed_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Path not in allowed list. Allowed paths:\n#{patterns}"
+          elsif denied_patterns.any?
+            # Show denied patterns
+            patterns = denied_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Denied paths:\n#{patterns}"
+          elsif allowed_patterns.any?
+            # Show allowed patterns
+            patterns = allowed_patterns.map { |p| "  - #{p}" }.join("\n")
+            "Allowed paths (not matched):\n#{patterns}"
+          else
+            "No access policy configured"
+          end
+
+          reminder = <<~REMINDER
+
+            <system-reminder>
+            PERMISSION DENIED: You do not have permission to #{operation_verb} '#{path}'.
+
+            #{policy_info}
+
+            This is an UNRECOVERABLE error set by user policy. You MUST stop trying to access files matching this pattern.
+
+            Policy explanation:
+            - This policy blocks ALL files matching the pattern, not just this specific file
+            - Do not attempt to access other files matching this pattern - they will also be denied
+            - Do not try to work around this restriction by using different tool arguments
+            - The user has explicitly denied access to these resources via security policy
+
+            You should inform the user that you cannot proceed due to permission restrictions on this file pattern.
+            </system-reminder>
+          REMINDER
+
+          "Permission denied: Cannot #{operation_verb} '#{path}'#{reminder}"
+        end
+
+        # Generate a command permission denied error message
+        #
+        # @param command [String] The command that was denied
+        # @param allowed_patterns [Array<Regexp>] List of allowed command regex patterns
+        # @param denied_patterns [Array<Regexp>] List of denied command regex patterns
+        # @param matching_pattern [String, nil] The specific pattern that blocked this command
+        # @param tool_name [String] Name of the tool (typically "bash")
+        # @return [String] Formatted error message with system reminder
+        def command_permission_denied(command:, allowed_patterns:, denied_patterns: [], matching_pattern: nil, tool_name:)
+          # Build policy explanation
+          policy_info = if matching_pattern && matching_pattern != "(not in allowed list)"
+            # Show the specific denied pattern that blocked this command
+            "Blocked by policy: #{matching_pattern}"
+          elsif matching_pattern == "(not in allowed list)" && allowed_patterns.any?
+            # Show allowed patterns when command doesn't match any
+            patterns = allowed_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Command not in allowed list. Allowed command patterns:\n#{patterns}"
+          elsif denied_patterns.any?
+            # Show denied patterns
+            patterns = denied_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Denied command patterns:\n#{patterns}"
+          elsif allowed_patterns.any?
+            # Show allowed patterns
+            patterns = allowed_patterns.map { |p| "  - #{p.source}" }.join("\n")
+            "Allowed command patterns (not matched):\n#{patterns}"
+          else
+            "No command policy configured"
+          end
+
+          reminder = <<~REMINDER
+
+            <system-reminder>
+            PERMISSION DENIED: You do not have permission to execute command '#{command}'.
+
+            #{policy_info}
+
+            This is an UNRECOVERABLE error set by user policy. You MUST stop trying to execute commands matching this pattern.
+
+            Policy explanation:
+            - This policy blocks ALL commands matching the pattern, not just this specific command
+            - Do not attempt to execute other commands matching this pattern - they will also be denied
+            - Do not try to work around this restriction by modifying the command slightly
+            - The user has explicitly denied access to these commands via security policy
+
+            You should inform the user that you cannot proceed due to permission restrictions on this command.
+            </system-reminder>
+          REMINDER
+
+          "Permission denied: Cannot execute command '#{command}'#{reminder}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions/path_matcher.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # PathMatcher handles glob pattern matching for file paths
+    #
+    # Supports gitignore-style glob patterns with:
+    # - Standard globs: *, **, ?, [abc], {a,b}
+    # - Recursive matching: **/* matches all nested files
+    # - Negation: !pattern to explicitly deny
+    #
+    # Examples:
+    #   PathMatcher.matches?("tmp/**/*", "tmp/foo/bar.rb")  # => true
+    #   PathMatcher.matches?("*.log", "debug.log")          # => true
+    #   PathMatcher.matches?("src/**/*.{rb,js}", "src/a/b.rb")  # => true
+    class PathMatcher
+      class << self
+        # Check if a path matches a glob pattern
+        #
+        # @param pattern [String] Glob pattern to match against
+        # @param path [String] File path to check
+        # @return [Boolean] True if path matches pattern
+        def matches?(pattern, path)
+          # Remove leading ! for negation patterns (handled by caller)
+          pattern = pattern.delete_prefix("!")
+
+          # Use File.fnmatch with pathname and extglob flags
+          # FNM_PATHNAME: ** matches directories recursively
+          # FNM_EXTGLOB: Support {a,b} patterns
+          File.fnmatch(pattern, path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions/validator.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Permissions
+    # Validator decorates tools to enforce permission checks before execution
+    #
+    # Uses the Decorator pattern (via SimpleDelegator) to wrap tool instances
+    # and validate file paths and commands before allowing tool execution.
+    #
+    # Example:
+    #   write_tool = Tools::Write.new
+    #   permissions = Config.new(
+    #     {
+    #       allowed_paths: ["tmp/**/*"],
+    #       allowed_commands: ["^git (status|diff)$"]
+    #     },
+    #     base_directories: ["."]
+    #   )
+    #   validated_tool = Validator.new(write_tool, permissions)
+    #
+    #   # This will be denied:
+    #   validated_tool.call({"file_path" => "/etc/passwd", "content" => "..."})
+    class Validator < SimpleDelegator
+      # Initialize validator decorator
+      #
+      # @param tool [RubyLLM::Tool] Tool instance to wrap
+      # @param permissions_config [Config] Permission configuration
+      def initialize(tool, permissions_config)
+        super(tool)
+        @permissions = permissions_config
+        @tool = tool
+      end
+
+      # Intercept RubyLLM's call method to validate permissions
+      #
+      # RubyLLM calls tool.call(args) where args have string keys.
+      # We must override call (not execute) because SimpleDelegator doesn't
+      # automatically intercept methods defined in the superclass.
+      #
+      # @param args [Hash] Tool arguments with string keys
+      # @return [String] Tool result or permission denied message
+      def call(args)
+        # Validate Bash commands if this is the Bash tool
+        if bash_tool?
+          command = args["command"]
+          if command && !@permissions.command_allowed?(command)
+            # Find the specific pattern that blocks this command
+            matching_pattern = @permissions.find_blocking_command_pattern(command)
+
+            return ErrorFormatter.command_permission_denied(
+              command: command,
+              allowed_patterns: @permissions.allowed_commands,
+              denied_patterns: @permissions.denied_commands,
+              matching_pattern: matching_pattern,
+              tool_name: @tool.name,
+            )
+          end
+        end
+
+        # Extract paths from arguments (handles both string and symbol keys)
+        paths = extract_paths_from_args(args)
+
+        # Determine if this is a directory search tool (Glob/Grep)
+        directory_search = directory_search_tool?
+
+        # Validate each path
+        paths.each do |path|
+          next if @permissions.allowed?(path, directory_search: directory_search)
+
+          # Show absolute path in error message for clarity
+          absolute_path = @permissions.to_absolute(path)
+
+          # Find the specific pattern that blocks this path
+          matching_pattern = @permissions.find_blocking_pattern(path, directory_search: directory_search)
+
+          return ErrorFormatter.permission_denied(
+            path: absolute_path,
+            allowed_patterns: @permissions.allowed_patterns,
+            denied_patterns: @permissions.denied_patterns,
+            matching_pattern: matching_pattern,
+            tool_name: @tool.name,
+          )
+        end
+
+        # All permissions validated, call wrapped tool
+        __getobj__.call(args)
+      end
+
+      private
+
+      # Check if the tool is the Bash tool
+      #
+      # @return [Boolean] True if tool is Bash
+      def bash_tool?
+        @tool.name.to_s == "Bash"
+      end
+
+      # Check if the tool is a directory search tool (Glob or Grep)
+      #
+      # @return [Boolean] True if tool searches directories
+      def directory_search_tool?
+        tool_name = @tool.name.to_s
+        tool_name == "Glob" || tool_name == "Grep"
+      end
+
+      # Extract file paths from tool arguments
+      #
+      # RubyLLM always passes arguments with string keys to call().
+      #
+      # Different tools have different parameter structures:
+      # - Write/Edit/Read: file_path parameter
+      # - MultiEdit: edits array with file_path in each edit
+      # - Glob/Grep: path parameter (directory to search)
+      # - Glob: pattern parameter may contain directory (e.g., "lib/**/*.rb")
+      # - Bash: command parameter (validated separately via command_allowed?)
+      #
+      # @param args [Hash] Tool arguments with string keys
+      # @return [Array<String>] List of file paths to validate
+      def extract_paths_from_args(args)
+        paths = []
+
+        # Single file path parameter (Write, Edit, Read)
+        paths << args["file_path"] if args["file_path"]
+
+        # Path parameter (Glob, Grep)
+        paths << args["path"] if args["path"]
+
+        # Glob pattern may contain directory prefix (e.g., "lib/**/*.rb")
+        # Extract the base directory from the pattern for validation
+        # Note: Only do this for Glob, not Grep (Grep pattern is a regex, not a path)
+        if @tool.name.to_s == "Glob"
+          pattern = args["pattern"]
+          if pattern && !pattern.start_with?("/")
+            # Extract first directory component from relative patterns
+            base_dir = extract_base_directory(pattern)
+            paths << base_dir if base_dir
+          end
+        end
+
+        # MultiEdit has array of edits
+        edits = args["edits"]
+        edits&.each do |edit|
+          paths << edit["file_path"] if edit.is_a?(Hash) && edit["file_path"]
+        end
+
+        paths.compact.uniq
+      end
+
+      # Extract base directory from a glob pattern
+      #
+      # Examples:
+      #   "lib/**/*.rb" => "lib"
+      #   "src/main.rb" => "src"
+      #   "**/*.rb" => nil (no specific directory)
+      #   "*.rb" => nil (current directory)
+      #
+      # @param pattern [String] Glob pattern
+      # @return [String, nil] Base directory or nil
+      def extract_base_directory(pattern)
+        return if pattern.nil? || pattern.empty?
+
+        # Split on / and take first component
+        parts = pattern.split("/")
+        first_part = parts.first
+
+        # Skip if pattern starts with wildcard (means current directory)
+        return if first_part.include?("*") || first_part.include?("?")
+
+        first_part
+      end
+    end
+  end
+end

data/lib/swarm_sdk/permissions_builder.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # DSL builder for tool permissions configuration
+  #
+  # Provides fluent API for configuring tool permissions using underscore syntax:
+  #
+  # @example Basic usage
+  #   permissions do
+  #     tool(:Write).allow_paths "tmp/**/*"
+  #     tool(:Write).deny_paths "tmp/secrets/**"
+  #     tool(:Read).deny_paths "lib/**/*"
+  #   end
+  #
+  # @example Bash commands
+  #   permissions do
+  #     tool(:Bash).allow_commands "^git (status|diff|log)$"
+  #     tool(:Bash).deny_commands "^rm -rf"
+  #   end
+  #
+  class PermissionsBuilder
+    def initialize
+      @permissions = {}
+    end
+
+    class << self
+      # Build permissions from block
+      #
+      # @yield Block for configuring permissions
+      # @return [Hash] Permissions configuration
+      def build(&block)
+        builder = new
+        builder.instance_eval(&block)
+        builder.to_h
+      end
+    end
+
+    # Convert to hash format expected by AgentDefinition
+    #
+    # @return [Hash] Permissions config
+    def to_h
+      @permissions
+    end
+
+    # Get a tool permissions proxy for configuring a specific tool
+    #
+    # @param tool_name [Symbol, String] Tool name
+    # @return [ToolPermissionsProxy] Proxy for configuring this tool
+    #
+    # @example
+    #   tool(:Write).allow_paths "tmp/**/*"
+    #   tool(:Bash).deny_commands "^rm -rf"
+    def tool(tool_name)
+      ToolPermissionsProxy.new(tool_name, @permissions)
+    end
+  end
+
+  # Proxy for configuring permissions on a specific tool
+  #
+  # @example
+  #   tool(:Write).allow_paths "tmp/**/*"
+  #   tool(:Write).deny_paths "tmp/secrets/**"
+  #   tool(:Bash).allow_commands "^git status$"
+  #
+  class ToolPermissionsProxy
+    def initialize(tool_name, permissions_hash)
+      @tool_name = tool_name.to_sym
+      @permissions = permissions_hash
+    end
+
+    # Add allowed path patterns
+    #
+    # @param patterns [Array<String>] Glob patterns for allowed paths
+    # @return [self]
+    def allow_paths(*patterns)
+      ensure_tool_config
+      @permissions[@tool_name][:allowed_paths] ||= []
+      @permissions[@tool_name][:allowed_paths].concat(patterns.flatten)
+      self
+    end
+
+    # Add denied path patterns
+    #
+    # @param patterns [Array<String>] Glob patterns for denied paths
+    # @return [self]
+    def deny_paths(*patterns)
+      ensure_tool_config
+      @permissions[@tool_name][:denied_paths] ||= []
+      @permissions[@tool_name][:denied_paths].concat(patterns.flatten)
+      self
+    end
+
+    # Add allowed command patterns (Bash tool only)
+    #
+    # @param patterns [Array<String>] Regex patterns for allowed commands
+    # @return [self]
+    def allow_commands(*patterns)
+      ensure_tool_config
+      @permissions[@tool_name][:allowed_commands] ||= []
+      @permissions[@tool_name][:allowed_commands].concat(patterns.flatten)
+      self
+    end
+
+    # Add denied command patterns (Bash tool only)
+    #
+    # @param patterns [Array<String>] Regex patterns for denied commands
+    # @return [self]
+    def deny_commands(*patterns)
+      ensure_tool_config
+      @permissions[@tool_name][:denied_commands] ||= []
+      @permissions[@tool_name][:denied_commands].concat(patterns.flatten)
+      self
+    end
+
+    private
+
+    # Ensure tool entry exists in permissions hash
+    def ensure_tool_config
+      @permissions[@tool_name] ||= {}
+    end
+  end
+end

data/lib/swarm_sdk/plugin.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Base class for SwarmSDK plugins
+  #
+  # Plugins provide tools, storage, configuration parsing, and lifecycle hooks.
+  # Plugins are self-registering - they call SwarmSDK::PluginRegistry.register
+  # when the gem is loaded.
+  #
+  # @example Implementing a plugin
+  #   class MyPlugin < SwarmSDK::Plugin
+  #     def name
+  #       :my_plugin
+  #     end
+  #
+  #     def tools
+  #       [:MyTool, :OtherTool]
+  #     end
+  #
+  #     def create_tool(tool_name, context)
+  #       # Create and return tool instance
+  #     end
+  #   end
+  #
+  #   SwarmSDK::PluginRegistry.register(MyPlugin.new)
+  class Plugin
+    # Plugin name (must be unique)
+    #
+    # @return [Symbol] Plugin identifier
+    def name
+      raise NotImplementedError, "#{self.class} must implement #name"
+    end
+
+    # List of tools provided by this plugin
+    #
+    # @return [Array<Symbol>] Tool names (e.g., [:MemoryWrite, :MemoryRead])
+    def tools
+      []
+    end
+
+    # Create a tool instance
+    #
+    # @param tool_name [Symbol] Tool name (e.g., :MemoryWrite)
+    # @param context [Hash] Creation context
+    #   - :agent_name [Symbol] Agent identifier
+    #   - :storage [Object] Plugin storage instance (if created)
+    #   - :agent_definition [Agent::Definition] Full agent definition
+    #   - :chat [Agent::Chat] Chat instance (for tools that need it)
+    #   - :tool_configurator [Swarm::ToolConfigurator] For tools that register other tools
+    # @return [RubyLLM::Tool] Tool instance
+    def create_tool(tool_name, context)
+      raise NotImplementedError, "#{self.class} must implement #create_tool"
+    end
+
+    # Create plugin storage for an agent (optional)
+    #
+    # Called during agent initialization. Return nil if plugin doesn't need storage.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param config [Object] Plugin configuration from agent definition
+    # @return [Object, nil] Storage instance or nil
+    def create_storage(agent_name:, config:)
+      nil
+    end
+
+    # Parse plugin configuration from agent definition
+    #
+    # @param raw_config [Object] Raw config (DSL object or Hash from YAML)
+    # @return [Object] Parsed configuration
+    def parse_config(raw_config)
+      raw_config
+    end
+
+    # Contribute to agent system prompt (optional)
+    #
+    # @param agent_definition [Agent::Definition] Agent definition
+    # @param storage [Object, nil] Plugin storage instance (if created)
+    # @return [String, nil] Prompt contribution or nil
+    def system_prompt_contribution(agent_definition:, storage:)
+      nil
+    end
+
+    # Tools that should be marked immutable (optional)
+    #
+    # Immutable tools cannot be removed by other tools (e.g., LoadSkill).
+    #
+    # @return [Array<Symbol>] Tool names
+    def immutable_tools
+      []
+    end
+
+    # Agent storage enabled for this agent? (optional)
+    #
+    # @param agent_definition [Agent::Definition] Agent definition
+    # @return [Boolean] True if storage should be created
+    def storage_enabled?(agent_definition)
+      false
+    end
+
+    # Lifecycle: Called when agent is initialized
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param agent [Agent::Chat] Chat instance
+    # @param context [Hash] Initialization context
+    #   - :storage [Object, nil] Plugin storage
+    #   - :agent_definition [Agent::Definition] Definition
+    #   - :tool_configurator [Swarm::ToolConfigurator] Configurator
+    def on_agent_initialized(agent_name:, agent:, context:)
+      # Override if needed
+    end
+
+    # Lifecycle: Called when swarm starts
+    #
+    # @param swarm [Swarm] Swarm instance
+    def on_swarm_started(swarm:)
+      # Override if needed
+    end
+
+    # Lifecycle: Called when swarm stops
+    #
+    # @param swarm [Swarm] Swarm instance
+    def on_swarm_stopped(swarm:)
+      # Override if needed
+    end
+
+    # Lifecycle: Called on every user message
+    #
+    # Plugins can return system reminders to inject based on the user's prompt.
+    # This enables features like semantic skill discovery, context injection, etc.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param prompt [String] The user's message
+    # @param is_first_message [Boolean] True if this is the first message in the conversation
+    # @return [Array<String>] System reminders to inject (empty array if none)
+    #
+    # @example Semantic skill discovery
+    #   def on_user_message(agent_name:, prompt:, is_first_message:)
+    #     skills = semantic_search(prompt, threshold: 0.65)
+    #     return [] if skills.empty?
+    #
+    #     [build_skill_reminder(skills)]
+    #   end
+    def on_user_message(agent_name:, prompt:, is_first_message:)
+      []
+    end
+  end
+end

data/lib/swarm_sdk/plugin_registry.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Plugin registry for managing SwarmSDK extensions
+  #
+  # Plugins register themselves when loaded, providing tools, storage,
+  # and lifecycle hooks without SwarmSDK needing to know about them.
+  module PluginRegistry
+    @plugins = {}
+    @tool_map = {}
+
+    class << self
+      # Register a plugin
+      #
+      # @param plugin [Plugin] Plugin instance
+      # @raise [ArgumentError] If plugin with same name already registered
+      def register(plugin)
+        raise ArgumentError, "Plugin must inherit from SwarmSDK::Plugin" unless plugin.is_a?(Plugin)
+
+        name = plugin.name
+        raise ArgumentError, "Plugin name required" unless name
+        raise ArgumentError, "Plugin #{name} already registered" if @plugins.key?(name)
+
+        @plugins[name] = plugin
+
+        # Build tool → plugin mapping
+        plugin.tools.each do |tool_name|
+          if @tool_map.key?(tool_name)
+            raise ArgumentError, "Tool #{tool_name} already registered by #{@tool_map[tool_name].name}"
+          end
+
+          @tool_map[tool_name] = plugin
+        end
+      end
+
+      # Get plugin by name
+      #
+      # @param name [Symbol] Plugin name
+      # @return [Plugin, nil] Plugin instance or nil
+      def get(name)
+        @plugins[name]
+      end
+
+      # Get all registered plugins
+      #
+      # @return [Array<Plugin>] All plugins
+      def all
+        @plugins.values
+      end
+
+      # Check if plugin is registered
+      #
+      # @param name [Symbol] Plugin name
+      # @return [Boolean] True if registered
+      def registered?(name)
+        @plugins.key?(name)
+      end
+
+      # Get plugin that provides a tool
+      #
+      # @param tool_name [Symbol] Tool name
+      # @return [Plugin, nil] Plugin that provides tool or nil
+      def plugin_for_tool(tool_name)
+        @tool_map[tool_name]
+      end
+
+      # Check if tool is provided by a plugin
+      #
+      # @param tool_name [Symbol] Tool name
+      # @return [Boolean] True if tool is plugin-provided
+      def plugin_tool?(tool_name)
+        @tool_map.key?(tool_name)
+      end
+
+      # Get all tools provided by plugins
+      #
+      # @return [Hash<Symbol, Plugin>] Tool name → Plugin mapping
+      def tools
+        @tool_map.dup
+      end
+
+      # Clear all plugins (for testing)
+      #
+      # @return [void]
+      def clear
+        @plugins.clear
+        @tool_map.clear
+      end
+
+      # Emit lifecycle event to all plugins
+      #
+      # @param event [Symbol] Event name
+      # @param args [Hash] Event arguments
+      def emit_event(event, **args)
+        @plugins.each_value do |plugin|
+          plugin.public_send(event, **args) if plugin.respond_to?(event)
+        end
+      end
+    end
+  end
+end