swarm_memory 2.2.7 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab7cec394382b667f3b48cbe15e62112082eb7ff1a10ff46879ba54f973e9ff0
-  data.tar.gz: 0cf05d7b5b2e78cbca336e5ac904a968f8698c9119508f9dfe168b1661afbcbc
+  metadata.gz: 30179963b0bf2e8b4558189e1a5719d6b206cc80a08d101b648e3d2e2fc253df
+  data.tar.gz: bdc60e7faa0e2360a6c3e8a236cd1b15a972d37a99cc18db808a4a208a484e7f
 SHA512:
-  metadata.gz: f095a013ac1103d933613cd4e3b44f434b73415f05e9073fc43dda14304cc0d795fa5617375e820822a60ae3d92ff96f8b8a728d1e0e00d68badd819ed5224ab
-  data.tar.gz: f0b59d40b498f9e741f62444084b3d2e9436e672b5573895cba7eec3edc5fb4aefa37901f98d3f90d1df0efd1723ddbe028dcbc955c9dcaae1cf0d566415c679
+  metadata.gz: 81b71bbf9fbd4ec14c03610f5dc7288ef4167686035e91bb934319ee6f2a973ed8998aad20303d8b97c16f802910e65988869f73b34681e0652b8afca657f95d
+  data.tar.gz: a6d4d533d2b19e92a6e0c89aa46e99ef667dccc0e6cc457ca9150fe0145b3aa4cf2ac5a79bc168e53e58549be54f8b1d2920efd1f7e22c768197b059adf3bae1

data/lib/swarm_memory/dsl/memory_config.rb

@@ -142,6 +142,7 @@ module SwarmMemory
         {
           adapter: @adapter_type,
           mode: @mode,
+          loadskill_preserve_delegation: @loadskill_preserve_delegation,
           **@adapter_options,
         }
       end

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -201,24 +201,6 @@ module SwarmMemory
         ERB.new(template_content).result(agent_definition.instance_eval { binding })
       end
 
-      # Tools that should be marked immutable (mode-aware)
-      #
-      # Memory tools for the current mode plus LoadSkill (if applicable) are immutable.
-      # This prevents LoadSkill from accidentally removing memory tools.
-      #
-      # @param mode [Symbol] Memory mode
-      # @return [Array<Symbol>] Immutable tool names for this mode
-      def immutable_tools_for_mode(mode)
-        base_tools = tools_for_mode(mode)
-
-        # LoadSkill only for read_write and full_access modes (not read_only)
-        if mode == :read_only
-          base_tools
-        else
-          base_tools + [:LoadSkill]
-        end
-      end
-
       # Check if memory is configured for this agent
       #
       # Delegates adapter-specific validation to the adapter itself.
@@ -332,7 +314,14 @@ module SwarmMemory
 
             # Pass through all custom adapter options
             # Handle both symbol and string keys (YAML may have either)
-            standard_keys = [:directory, :adapter, :mode, "directory", "adapter", "mode"]
+            standard_keys = [
+              :directory,
+              :adapter,
+              :mode,
+              "directory",
+              "adapter",
+              "mode",
+            ]
             custom_keys = memory_config.keys - standard_keys
             custom_keys.each do |key|
               option(key.to_sym, memory_config[key]) # Normalize to symbol
@@ -379,17 +368,16 @@ module SwarmMemory
         @modes[base_name] = mode # ← Changed from agent_name to base_name
         @threshold_configs[base_name] = extract_threshold_config(memory_config)
 
-        # Get mode-specific tools
-        allowed_tools = tools_for_mode(mode)
-
-        # Get all registered memory tool names
-        all_memory_tools = tools # Returns all possible memory tools
+        # NOTE: Memory tools are already registered by ToolConfigurator.register_plugin_tools
+        # We need to unregister tools not allowed in this mode (Plan 025)
 
-        # Remove tools not allowed in this mode
+        all_memory_tools = tools
+        allowed_tools = tools_for_mode(mode)
         tools_to_remove = all_memory_tools - allowed_tools
 
+        # Unregister tools not allowed in this mode
         tools_to_remove.each do |tool_name|
-          agent.remove_tool(tool_name)
+          agent.tool_registry.unregister(tool_name.to_s)
         end
 
         # Create and register LoadSkill tool (NOT for read_only mode)
@@ -403,11 +391,15 @@ module SwarmMemory
             agent_definition: agent_definition,
           )
 
-          agent.add_tool(load_skill_tool)
+          # Register in tool registry (Plan 025)
+          agent.tool_registry.register(
+            load_skill_tool,
+            source: :plugin,
+            metadata: { plugin_name: :memory, mode: mode },
+          )
         end
 
-        # Mark mode-specific memory tools + LoadSkill as immutable
-        agent.mark_tools_immutable(immutable_tools_for_mode(mode).map(&:to_s))
+        # NOTE: No need to mark tools immutable - they declare removable? themselves (Plan 025)
       end
 
       # Lifecycle: User message

data/lib/swarm_memory/skill_state.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SwarmMemory
+  # Immutable representation of a loaded skill's state
+  #
+  # This object encapsulates all skill-related state for clean management.
+  # Immutability prevents accidental mutation bugs during activation.
+  #
+  # @example Creating skill state
+  #   state = SkillState.new(
+  #     file_path: "skill/security/audit.md",
+  #     tools: ["Read", "Grep", "WorkWithBackend"],
+  #     permissions: { "Bash" => { deny_commands: ["rm"] } }
+  #   )
+  #
+  # @example Checking if skill restricts tools
+  #   state.restricts_tools?  # => true (has tool list)
+  #
+  # @example Checking if tool is allowed
+  #   state.allows_tool?("Read")  # => true
+  #   state.allows_tool?("Write") # => false
+  class SkillState
+    attr_reader :file_path, :tools, :permissions
+
+    # Create a new SkillState
+    #
+    # @param file_path [String] Path to the skill in memory
+    # @param tools [Array<String>, nil] Required tools (nil = no tool restriction)
+    # @param permissions [Hash] Tool permission overrides
+    #
+    # @example No tool restriction
+    #   SkillState.new(file_path: "skill/debug.md")  # All tools available
+    #
+    # @example Specific tools only
+    #   SkillState.new(
+    #     file_path: "skill/audit.md",
+    #     tools: ["Read", "Grep"]
+    #   )
+    #
+    # @example With permissions
+    #   SkillState.new(
+    #     file_path: "skill/safe.md",
+    #     tools: ["Bash"],
+    #     permissions: { "Bash" => { deny_commands: ["rm", "sudo"] } }
+    #   )
+    def initialize(file_path:, tools: nil, permissions: {})
+      @file_path = file_path
+      @tools = tools&.map(&:to_s)&.freeze # Normalize and freeze
+      @permissions = permissions.freeze
+      freeze # Make entire object immutable
+    end
+
+    # Check if skill specifies a tool restriction
+    #
+    # Returns true if the skill has a NON-EMPTY tools array.
+    # Both nil and empty array mean "no restriction" (don't swap tools).
+    #
+    # @return [Boolean] True if skill restricts toolset
+    #
+    # @example No restriction (nil)
+    #   state = SkillState.new(file_path: "skill/debug.md")
+    #   state.restricts_tools?  # => false (nil = no restriction)
+    #
+    # @example No restriction (empty array)
+    #   state = SkillState.new(file_path: "skill/minimal.md", tools: [])
+    #   state.restricts_tools?  # => false (empty = no restriction)
+    #
+    # @example Restriction (specific tools)
+    #   state = SkillState.new(file_path: "skill/audit.md", tools: ["Read"])
+    #   state.restricts_tools?  # => true (has specific tools)
+    def restricts_tools?
+      !@tools.nil? && !@tools.empty?
+    end
+
+    # Check if a specific tool is allowed by this skill
+    #
+    # If the skill has no tool restriction (tools is nil), all tools are allowed.
+    # If the skill has a tool list, only tools in that list are allowed.
+    #
+    # @param name [String, Symbol] Tool name
+    # @return [Boolean] True if tool is in skill's list (or no restriction)
+    #
+    # @example No restriction
+    #   state = SkillState.new(file_path: "skill/debug.md")
+    #   state.allows_tool?("AnyTool")  # => true (no restriction)
+    #
+    # @example Restricted
+    #   state = SkillState.new(file_path: "skill/audit.md", tools: ["Read"])
+    #   state.allows_tool?("Read")   # => true
+    #   state.allows_tool?("Write")  # => false
+    def allows_tool?(name)
+      @tools.nil? || @tools.include?(name.to_s)
+    end
+
+    # Get permission config for a tool
+    #
+    # Returns the permission configuration hash for a specific tool,
+    # or nil if no custom permissions are set.
+    #
+    # @param name [String, Symbol] Tool name
+    # @return [Hash, nil] Permission config or nil
+    #
+    # @example No custom permissions
+    #   state = SkillState.new(file_path: "skill/debug.md")
+    #   state.permissions_for("Bash")  # => nil
+    #
+    # @example Custom permissions
+    #   state = SkillState.new(
+    #     file_path: "skill/safe.md",
+    #     permissions: { "Bash" => { deny_commands: ["rm"] } }
+    #   )
+    #   state.permissions_for("Bash")  # => { deny_commands: ["rm"] }
+    def permissions_for(name)
+      @permissions[name.to_s] || @permissions[name.to_sym]
+    end
+  end
+end

data/lib/swarm_memory/tools/load_skill.rb

@@ -13,7 +13,8 @@ module SwarmMemory
     # - Have type: 'skill' in metadata
     # - Include tools array in metadata (optional)
     # - Include permissions hash in metadata (optional)
-    class LoadSkill < RubyLLM::Tool
+    class LoadSkill < SwarmSDK::Tools::Base
+      removable false # LoadSkill is always available
       description <<~DESC
         Load a skill from memory and dynamically adapt your toolset to execute it.
 
@@ -127,33 +128,20 @@ module SwarmMemory
         desc: "Path to skill - MUST start with 'skill/' (one of 4 fixed memory categories). Examples: 'skill/debugging/api-errors.md', 'skill/meta/deep-learning.md'",
         required: true
 
-      # Initialize with all context needed for tool swapping
+      # Initialize with storage and chat context
       #
       # @param storage [Core::Storage] Memory storage
       # @param agent_name [Symbol] Agent identifier
       # @param chat [SwarmSDK::Agent::Chat] The agent's chat instance
-      # @param tool_configurator [SwarmSDK::ToolConfigurator] For creating tools
-      # @param agent_definition [SwarmSDK::Agent::Definition] For permissions
-      def initialize(storage:, agent_name:, chat:, tool_configurator:, agent_definition:)
+      # @param tool_configurator [SwarmSDK::ToolConfigurator] For creating tools (unused in Plan 025)
+      # @param agent_definition [SwarmSDK::Agent::Definition] For permissions (unused in Plan 025)
+      def initialize(storage:, agent_name:, chat:, tool_configurator: nil, agent_definition: nil)
         super()
         @storage = storage
         @agent_name = agent_name
         @chat = chat
-        @tool_configurator = tool_configurator
-        @agent_definition = agent_definition
-
-        # Mark memory tools and LoadSkill as immutable
-        # This ensures they won't be removed during skill swapping
-        @chat.mark_tools_immutable(
-          "MemoryWrite",
-          "MemoryRead",
-          "MemoryEdit",
-          "MemoryDelete",
-          "MemoryGlob",
-          "MemoryGrep",
-          "MemoryDefrag",
-          "LoadSkill",
-        )
+        # NOTE: tool_configurator and agent_definition kept for API compatibility
+        # but unused in Plan 025 (tools come from registry, not recreation)
       end
 
       # Override name to return simple "LoadSkill"
@@ -161,7 +149,7 @@ module SwarmMemory
         "LoadSkill"
       end
 
-      # Execute the tool
+      # Execute the tool (Plan 025: Simplified - no tool swapping)
       #
       # @param file_path [String] Path to skill in memory
       # @return [String] Skill content with line numbers, or error message
@@ -184,30 +172,42 @@ module SwarmMemory
           return validation_error("memory://#{file_path} is not a skill (type: #{type})")
         end
 
-        # 4. Extract tool requirements
+        # 4. Extract tool requirements and permissions
         required_tools = entry.metadata["tools"]
         permissions = entry.metadata["permissions"] || {}
 
-        # 5. Validate and swap tools (only if tools are specified)
+        # 5. Validate tools exist in registry (only if tools are specified and non-empty)
         if required_tools && !required_tools.empty?
           begin
-            swap_tools(required_tools, permissions)
+            validate_skill_tools(required_tools)
           rescue ArgumentError => e
             return validation_error(e.message)
           end
         end
-        # If no tools specified (nil or []), keep current tools (no swap)
 
-        # 6. Mark skill as loaded
-        @chat.mark_skill_loaded(file_path)
+        # 6. Create and set skill state
+        # Note: tools: nil or tools: [] both mean "no restriction" (keep all tools)
+        skill_state = SwarmMemory::SkillState.new(
+          file_path: file_path,
+          tools: required_tools, # May be nil or [] (no restriction)
+          permissions: permissions,
+        )
+        @chat.load_skill_state(skill_state)
+
+        # 7. Activate tools if skill restricts them
+        # If no restriction (nil or []), tools remain unchanged
+        if skill_state.restricts_tools?
+          @chat.activate_tools_for_prompt
+        end
+        # Otherwise, tools stay as-is (no swap)
 
-        # 7. Return content with confirmation message
+        # 8. Return content with confirmation message
         title = entry.title || "Untitled Skill"
         result = "Loaded skill: #{title}\n\n"
         result += format_with_line_numbers(entry.content)
 
-        # 8. Add system reminder if tools were swapped
-        if required_tools && !required_tools.empty?
+        # 9. Add system reminder if tools were restricted
+        if skill_state.restricts_tools?
           result += "\n\n"
           result += build_toolset_update_reminder(required_tools)
         end
@@ -217,75 +217,46 @@ module SwarmMemory
 
       private
 
-      # Build system reminder for toolset updates
+      # Validate tools exist in registry (Plan 025)
       #
-      # @param new_tools [Array<String>] Tools that were added
+      # @param required_tools [Array<String>] Tools needed by the skill
+      # @raise [ArgumentError] If any tool is not available
+      # @return [void]
+      def validate_skill_tools(required_tools)
+        required_tools.each do |tool_name|
+          next if @chat.tool_registry.has_tool?(tool_name)
+
+          available = @chat.tool_registry.tool_names.join(", ")
+          raise ArgumentError,
+            "Skill requires tool '#{tool_name}' but it's not available for this agent. " \
+              "Available tools: #{available}"
+        end
+      end
+
+      # Build system reminder for toolset updates (Plan 025)
+      #
+      # @param new_tools [Array<String>] Tools that were loaded
       # @return [String] System reminder message
       def build_toolset_update_reminder(new_tools)
-        # Get current tool list from chat
-        # Handle both real Chat (hash) and MockChat (array)
-        tools_collection = @chat.tools
-        current_tools = if tools_collection.is_a?(Hash)
-          tools_collection.values.map(&:name).sort
-        else
-          tools_collection.map(&:name).sort
-        end
+        # Get non-removable tools that are always included
+        non_removable = @chat.tool_registry.non_removable_tool_names.sort
 
         reminder = "<system-reminder>\n"
-        reminder += "Your available tools have been updated.\n\n"
-        reminder += "New tools loaded from skill:\n"
+        reminder += "Your available tools have been updated by loading this skill.\n\n"
+        reminder += "Tools specified by skill:\n"
         new_tools.each do |tool_name|
           reminder += "  - #{tool_name}\n"
         end
-        reminder += "\nYour complete toolset is now:\n"
-        current_tools.each do |tool_name|
+        reminder += "\nNon-removable tools (always available):\n"
+        non_removable.each do |tool_name|
           reminder += "  - #{tool_name}\n"
         end
-        reminder += "\nOnly use tools from this list. Do not attempt to use tools that are not listed here.\n"
+        reminder += "\nOnly use tools from these lists. Other tools have been deactivated for this skill.\n"
         reminder += "</system-reminder>"
 
         reminder
       end
 
-      # Swap agent tools to match skill requirements
-      #
-      # @param required_tools [Array<String>] Tools needed by the skill
-      # @param permissions [Hash] Tool permissions from skill metadata
-      # @return [void]
-      # @raise [ArgumentError] If validation fails
-      def swap_tools(required_tools, permissions)
-        # Future: Could validate tool availability against agent's configured tools
-        # For now, all tools in SwarmSDK are available (unless bypassed by permissions)
-
-        # Remove all mutable tools (keeps immutable tools)
-        @chat.remove_mutable_tools
-
-        # Add required tools from skill
-        required_tools.each do |tool_name|
-          tool_sym = tool_name.to_sym
-
-          # Get permissions for this tool (skill overrides agent permissions)
-          tool_permissions = permissions[tool_name] || permissions[tool_sym.to_s]
-
-          # Create tool instance
-          tool_instance = @tool_configurator.create_tool_instance(
-            tool_sym,
-            @agent_name,
-            @agent_definition.directory,
-          )
-
-          # Wrap with permissions (unless bypassed)
-          tool_instance = @tool_configurator.wrap_tool_with_permissions(
-            tool_instance,
-            tool_permissions,
-            @agent_definition,
-          )
-
-          # Add to chat
-          @chat.add_tool(tool_instance)
-        end
-      end
-
       # Format validation error message
       #
       # @param message [String] Error message

data/lib/swarm_memory/tools/memory_defrag.rb

@@ -6,7 +6,8 @@ module SwarmMemory
     #
     # Provides defragmentation operations to maintain memory quality.
     # Each agent has its own isolated memory storage.
-    class MemoryDefrag < RubyLLM::Tool
+    class MemoryDefrag < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
       description <<~DESC
         Analyze and optimize your memory storage for better precision, recall, and organization.
 

data/lib/swarm_memory/tools/memory_delete.rb

@@ -6,7 +6,8 @@ module SwarmMemory
     #
     # Removes entries that are no longer relevant.
     # Each agent has its own isolated memory storage.
-    class MemoryDelete < RubyLLM::Tool
+    class MemoryDelete < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
       description <<~DESC
         Delete entries from your memory storage when they're no longer needed.
 

data/lib/swarm_memory/tools/memory_edit.rb

@@ -6,7 +6,8 @@ module SwarmMemory
     #
     # Performs exact string replacements in memory content.
     # Each agent has its own isolated memory storage.
-    class MemoryEdit < RubyLLM::Tool
+    class MemoryEdit < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
       description <<~DESC
         Perform exact string replacements in memory entries (works like Edit tool but for memory content).
 

data/lib/swarm_memory/tools/memory_glob.rb

@@ -6,7 +6,8 @@ module SwarmMemory
     #
     # Finds memory entries matching a glob pattern (like filesystem glob).
     # Each agent has its own isolated memory storage.
-    class MemoryGlob < RubyLLM::Tool
+    class MemoryGlob < SwarmSDK::Tools::Base
+      removable false  # Memory tools are always available
       description <<~DESC
         Search your memory entries using glob patterns (like filesystem glob).
 

data/lib/swarm_memory/tools/memory_grep.rb

@@ -6,7 +6,9 @@ module SwarmMemory
     #
     # Searches content stored in memory entries using regex patterns.
     # Each agent has its own isolated memory storage.
-    class MemoryGrep < RubyLLM::Tool
+    class MemoryGrep < SwarmSDK::Tools::Base
+      removable false  # Memory tools are always available
+
       include TitleLookup
 
       description <<~DESC

data/lib/swarm_memory/tools/memory_read.rb

@@ -6,7 +6,9 @@ module SwarmMemory
     #
     # Retrieves content stored by this agent using memory_write.
     # Each agent has its own isolated memory storage.
-    class MemoryRead < RubyLLM::Tool
+    class MemoryRead < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
+
       include TitleLookup
 
       description <<~DESC

data/lib/swarm_memory/tools/memory_search.rb

@@ -7,7 +7,8 @@ module SwarmMemory
     # Searches content stored in memory using AI embeddings to find
     # conceptually related entries even when exact keywords don't match.
     # Each agent has its own isolated memory storage.
-    class MemorySearch < RubyLLM::Tool
+    class MemorySearch < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
       description <<~DESC
         Perform semantic search across memory entries using natural language queries.
 

data/lib/swarm_memory/tools/memory_write.rb

@@ -6,7 +6,8 @@ module SwarmMemory
     #
     # Stores content and metadata in persistent, per-agent memory storage.
     # Each agent has its own isolated memory storage that persists across sessions.
-    class MemoryWrite < RubyLLM::Tool
+    class MemoryWrite < SwarmSDK::Tools::Base
+      removable false # Memory tools are always available
       description <<~DESC
         Store content in persistent memory with structured metadata for semantic search and retrieval.
 

data/lib/swarm_memory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmMemory
-  VERSION = "2.2.7"
+  VERSION = "2.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_memory
 version: !ruby/object:Gem::Version
-  version: 2.2.7
+  version: 2.3.0
 platform: ruby
 authors:
 - Paulo Arruda
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.6'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -130,6 +130,7 @@ files:
 - lib/swarm_memory/search/semantic_search.rb
 - lib/swarm_memory/search/text_search.rb
 - lib/swarm_memory/search/text_similarity.rb
+- lib/swarm_memory/skill_state.rb
 - lib/swarm_memory/skills/meta/deep-learning.md
 - lib/swarm_memory/skills/meta/deep-learning.yml
 - lib/swarm_memory/tools/load_skill.rb