swarm_sdk 2.7.2 → 2.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 204f0173ac046d5eae63cf3ddca318e3ab0e76a88661e7f4a106d5079a68ee63
-  data.tar.gz: 515a43fac5824b6fab886901449ef808288e8e5e2beaacd02502c0e337a3d98f
+  metadata.gz: b5c93c6e9a850d624b8ac0fe9d31e53a4a764a1caa23319efcfa5b34edfd33b8
+  data.tar.gz: 2d4ec3258101a45507cbacbd98eeb86d8448627e35faedd2a693c0a18d8622a1
 SHA512:
-  metadata.gz: 94b2a3d8ee2d4cd61ec45a075b5e9cc370d992e47ae2da7e478abe7aa7f81ebaf2c0cd3571072ed02fdfac1eefc07c8eb5bcfd65aefa46c0cc60298b7e2b30ae
-  data.tar.gz: 7e527394023723bfabd8fa18c1696b0dc10b14499fe4c2ba3db46e3c8518158d1d5de8553c41d2139eba3c800f17a739c86503a7366c470ccb9e616446695510
+  metadata.gz: ac8f8c8dea846e5b0783b49dace5f2e01a0908ebed31eb377fdd4217480e99499fe9eb4bda14772cbfd71d52badc642687434a214f76cf136768c21967e1beff
+  data.tar.gz: 61a58b209810484c7bcf24727feaa8fb0e23aafc485dbb3ad8a510c095caeaa72778b0e3c97b22eb599a2d9153ef95093dc9aa6a3b34e717b23c4c5d9797b490

data/lib/swarm_sdk/agent/builder.rb

@@ -275,6 +275,10 @@ module SwarmSDK
       #                backend: "GetBackendHelp",
       #                :qa
       #
+      # @example With delegation options (preserve_context controls context persistence)
+      #   delegates_to :frontend,
+      #                { agent: :backend, tool_name: "AskBackend", preserve_context: false }
+      #
       # @param agent_names_and_options [Array<Symbol, Hash>] Agent names and/or hash with custom tool names
       # @return [void]
       def delegates_to(*agent_names_and_options)
@@ -282,11 +286,20 @@ module SwarmSDK
           case item
           when Symbol, String
             # Simple format: :frontend
-            @delegates_to << { agent: item.to_sym, tool_name: nil }
+            @delegates_to << { agent: item.to_sym, tool_name: nil, preserve_context: true }
           when Hash
-            # Hash format: { frontend: "AskFrontend", backend: nil }
-            item.each do |agent, tool_name|
-              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
+            if item.key?(:agent)
+              # Full config format: { agent: :backend, tool_name: "Custom", preserve_context: false }
+              @delegates_to << {
+                agent: item[:agent].to_sym,
+                tool_name: item[:tool_name],
+                preserve_context: item.fetch(:preserve_context, true),
+              }
+            else
+              # Hash format: { frontend: "AskFrontend", backend: nil }
+              item.each do |agent, tool_name|
+                @delegates_to << { agent: agent.to_sym, tool_name: tool_name, preserve_context: true }
+              end
             end
           else
             raise ConfigurationError, "delegates_to accepts Symbols or Hashes, got #{item.class}"

data/lib/swarm_sdk/agent/definition.rb

@@ -325,16 +325,20 @@ module SwarmSDK
           delegation_config.flat_map do |item|
             case item
             when Symbol, String
-              # Simple format: :frontend → {agent: :frontend, tool_name: nil}
-              [{ agent: item.to_sym, tool_name: nil }]
+              # Simple format: :frontend → {agent: :frontend, tool_name: nil, preserve_context: true}
+              [{ agent: item.to_sym, tool_name: nil, preserve_context: true }]
             when Hash
               # Could be already normalized or hash format
               if item.key?(:agent)
-                # Already normalized: {agent: :frontend, tool_name: "Custom"}
-                [item]
+                # Already normalized: {agent: :frontend, tool_name: "Custom", preserve_context: false}
+                [{
+                  agent: item[:agent].to_sym,
+                  tool_name: item[:tool_name],
+                  preserve_context: item.fetch(:preserve_context, true),
+                }]
               else
                 # Hash format in array: {frontend: "AskFrontend"}
-                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name, preserve_context: true } }
               end
             else
               raise ConfigurationError, "Invalid delegation config format: #{item.inspect}"
@@ -343,7 +347,7 @@ module SwarmSDK
         elsif delegation_config.is_a?(Hash)
           # Hash format: {frontend: "AskFrontend", backend: nil}
           delegation_config.map do |agent, tool_name|
-            { agent: agent.to_sym, tool_name: tool_name }
+            { agent: agent.to_sym, tool_name: tool_name, preserve_context: true }
           end
         else
           raise ConfigurationError, "delegates_to must be an Array or Hash, got #{delegation_config.class}"

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -91,8 +91,9 @@ module SwarmSDK
       # @param agent_name [Symbol] Name of the delegating agent
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating
       # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
+      # @param preserve_context [Boolean] Whether to preserve conversation context between delegations (default: true)
       # @return [Tools::Delegate] Delegation tool
-      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil, custom_tool_name: nil)
+      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil, custom_tool_name: nil, preserve_context: true)
         Tools::Delegate.new(
           delegate_name: name,
           delegate_description: description,
@@ -101,6 +102,7 @@ module SwarmSDK
           swarm: @swarm,
           delegating_chat: delegating_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
       end
 
@@ -219,7 +221,7 @@ module SwarmSDK
       #
       # @param delegator_name [Symbol, String] Name of the agent doing the delegating
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
-      # @param delegation_config [Hash] Delegation configuration with :agent and :tool_name keys
+      # @param delegation_config [Hash] Delegation configuration with :agent, :tool_name, and :preserve_context keys
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances for nested delegation
       # @return [void]
@@ -227,10 +229,11 @@ module SwarmSDK
         delegate_name_sym = delegation_config[:agent]
         delegate_name_str = delegate_name_sym.to_s
         custom_tool_name = delegation_config[:tool_name]
+        preserve_context = delegation_config.fetch(:preserve_context, true)
 
         # Check if target is a registered swarm
         if @swarm.swarm_registry&.registered?(delegate_name_str)
-          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str, custom_tool_name)
+          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str, custom_tool_name, preserve_context)
         elsif @swarm.agent_definitions.key?(delegate_name_sym)
           wire_agent_delegation(
             delegator_name: delegator_name,
@@ -239,6 +242,7 @@ module SwarmSDK
             custom_tool_name: custom_tool_name,
             tool_configurator: tool_configurator,
             create_nested_instances: create_nested_instances,
+            preserve_context: preserve_context,
           )
         else
           raise ConfigurationError,
@@ -252,8 +256,9 @@ module SwarmSDK
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
       # @param swarm_name [String] Name of the registered swarm
       # @param custom_tool_name [String, nil] Optional custom tool name
+      # @param preserve_context [Boolean] Whether to preserve context between delegations
       # @return [void]
-      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name, custom_tool_name)
+      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name, custom_tool_name, preserve_context)
         tool = create_delegation_tool(
           name: swarm_name,
           description: "External swarm: #{swarm_name}",
@@ -261,13 +266,14 @@ module SwarmSDK
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
 
         # Register in tool registry (Plan 025)
         delegator_chat.tool_registry.register(
           tool,
           source: :delegation,
-          metadata: { delegate_name: swarm_name, delegation_type: :swarm },
+          metadata: { delegate_name: swarm_name, delegation_type: :swarm, preserve_context: preserve_context },
         )
       end
 
@@ -282,8 +288,9 @@ module SwarmSDK
       # @param custom_tool_name [String, nil] Optional custom tool name
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances if not found
+      # @param preserve_context [Boolean] Whether to preserve context between delegations
       # @return [void]
-      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:)
+      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:, preserve_context:)
         delegate_definition = @swarm.agent_definitions[delegate_name_sym]
 
         # Determine which chat instance to use
@@ -316,6 +323,7 @@ module SwarmSDK
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
 
         # Register in tool registry (Plan 025)
@@ -325,6 +333,7 @@ module SwarmSDK
           metadata: {
             delegate_name: delegate_name_sym,
             delegation_mode: delegate_definition.shared_across_delegations ? :shared : :isolated,
+            preserve_context: preserve_context,
           },
         )
       end

data/lib/swarm_sdk/tools/delegate.rb

@@ -37,7 +37,7 @@ module SwarmSDK
         end
       end
 
-      attr_reader :delegate_name, :delegate_target, :tool_name
+      attr_reader :delegate_name, :delegate_target, :tool_name, :preserve_context
 
       # Initialize a delegation tool
       #
@@ -48,6 +48,7 @@ module SwarmSDK
       # @param swarm [Swarm] The swarm instance (provides hook_registry, delegation_call_stack, swarm_registry)
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
       # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
+      # @param preserve_context [Boolean] Whether to preserve conversation context between delegations (default: true)
       def initialize(
         delegate_name:,
         delegate_description:,
@@ -55,7 +56,8 @@ module SwarmSDK
         agent_name:,
         swarm:,
         delegating_chat: nil,
-        custom_tool_name: nil
+        custom_tool_name: nil,
+        preserve_context: true
       )
         super()
 
@@ -65,6 +67,7 @@ module SwarmSDK
         @agent_name = agent_name
         @swarm = swarm
         @delegating_chat = delegating_chat
+        @preserve_context = preserve_context
 
         # Use custom tool name if provided, otherwise generate using canonical method
         @tool_name = custom_tool_name || self.class.tool_name_for(delegate_name)
@@ -81,6 +84,11 @@ module SwarmSDK
         desc: "Message to send to the agent - can be a work request, question, or collaboration message",
         required: true
 
+      param :reset_context,
+        type: "boolean",
+        desc: "Reset the agent's conversation history before sending the message. Use it to recover from 'prompt too long' errors or other 4XX errors.",
+        required: false
+
       # Override name to return custom delegation tool name
       def name
         @tool_name
@@ -89,8 +97,9 @@ module SwarmSDK
       # Execute delegation with pre/post hooks
       #
       # @param message [String] Message to send to the agent
+      # @param reset_context [Boolean] Whether to reset the agent's conversation history before delegation
       # @return [String] Result from delegate agent or error message
-      def execute(message:)
+      def execute(message:, reset_context: false)
         # Access swarm infrastructure
         call_stack = @swarm.delegation_call_stack
         hook_registry = @swarm.hook_registry
@@ -137,10 +146,10 @@ module SwarmSDK
         # Determine delegation type and proceed
         delegation_result = if @delegate_chat
           # Delegate to agent
-          delegate_to_agent(message, call_stack)
+          delegate_to_agent(message, call_stack, reset_context: reset_context)
         elsif swarm_registry&.registered?(@delegate_target)
           # Delegate to registered swarm
-          delegate_to_swarm(message, call_stack, swarm_registry)
+          delegate_to_swarm(message, call_stack, swarm_registry, reset_context: reset_context)
         else
           raise ConfigurationError, "Unknown delegation target: #{@delegate_target}"
         end
@@ -219,11 +228,16 @@ module SwarmSDK
       #
       # @param message [String] Message to send to the agent
       # @param call_stack [Array] Delegation call stack for circular dependency detection
+      # @param reset_context [Boolean] Whether to reset the agent's conversation history before delegation
       # @return [String] Result from agent
-      def delegate_to_agent(message, call_stack)
+      def delegate_to_agent(message, call_stack, reset_context: false)
         # Push delegate target onto call stack to track delegation chain
         call_stack.push(@delegate_target)
         begin
+          # Clear conversation if reset_context is true OR if preserve_context is false
+          # reset_context takes precedence as it's an explicit request
+          @delegate_chat.clear_conversation if reset_context || !@preserve_context
+
           response = @delegate_chat.ask(message, source: "delegation")
           response.content
         ensure
@@ -237,20 +251,24 @@ module SwarmSDK
       # @param message [String] Message to send to the swarm
       # @param call_stack [Array] Delegation call stack for circular dependency detection
       # @param swarm_registry [SwarmRegistry] Registry for sub-swarms
+      # @param reset_context [Boolean] Whether to reset the swarm's conversation history before delegation
       # @return [String] Result from swarm's lead agent
-      def delegate_to_swarm(message, call_stack, swarm_registry)
+      def delegate_to_swarm(message, call_stack, swarm_registry, reset_context: false)
         # Load sub-swarm (lazy load + cache)
         subswarm = swarm_registry.load_swarm(@delegate_target)
 
         # Push delegate target onto call stack to track delegation chain
         call_stack.push(@delegate_target)
         begin
+          # Reset swarm if reset_context is true
+          swarm_registry.reset(@delegate_target) if reset_context
+
           # Execute sub-swarm's lead agent
           lead_agent = subswarm.agents[subswarm.lead_agent]
           response = lead_agent.ask(message, source: "delegation")
           result = response.content
 
-          # Reset if keep_context: false
+          # Reset if keep_context: false (standard behavior)
           swarm_registry.reset_if_needed(@delegate_target)
 
           result

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.7.2"
+  VERSION = "2.7.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.7.2
+  version: 2.7.4
 platform: ruby
 authors:
 - Paulo Arruda