swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/permissions/error_formatter.rb

@@ -1,121 +0,0 @@
-# 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

@@ -1,35 +0,0 @@
-# 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

@@ -1,173 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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