swarm_sdk 2.1.1 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47978b1c12d2f651d9a6cf9d902e7eff40d46505e436039e53f39bc0d2b05341
-  data.tar.gz: ae2b9ac86ec9a6718a14e121c7b19198e519cbd028a236b7b58d8b4acb96d3b9
+  metadata.gz: a77daa5d8abcd0cae1b1edad441d93421d25ecbf15a0713697d9eabb6c4dc00e
+  data.tar.gz: 97c037f892d03992b12292a31bc3ab9359ccacead39d37466af84ef5660e4933
 SHA512:
-  metadata.gz: 48d1f64f551285a081d55ee10e98ba4a31b4b6ee55303b7516e2170bc78f08bc895e740f61eb37c8731196450546f44917ac6a1c98cbb8d0b345c6cda2f91bf7
-  data.tar.gz: da736412afc0e1565ea706b0680cc961531649143294f2bbfce6954ebd752cdfa87d039cfd965ae881942764b3549d102f9a1711a15fdf23980a906d3108142c
+  metadata.gz: e7620b869014c9f1b889795310ec1d648cbcc55fc53a3cbb7023c37b403f83c57e5f3645b4f8ffdd38d60fa4877fa24d9ab3f0ccf0de3b2be6a45420516dbf50
+  data.tar.gz: bc081f3a444bb410a22dc2e5971f258dd43dadaa69d53558e799d036149412bfecf8d95396aa0f6e1f0c39cf6716b986722669265b32cc2b550f7daa0a6e9c2c

data/lib/swarm_sdk/agent/chat.rb

@@ -415,7 +415,7 @@ module SwarmSDK
 
         # Handle nil response from provider (malformed API response)
         if response.nil?
-          raise RubyLLM::Error, "Provider returned nil response. This usually indicates a malformed API response " \
+          raise StandardError, "Provider returned nil response. This usually indicates a malformed API response " \
             "that couldn't be parsed.\n\n" \
             "Provider: #{@provider.class.name}\n" \
             "API Base: #{@provider.api_base}\n" \

data/lib/swarm_sdk/agent/definition.rb

@@ -158,10 +158,12 @@ module SwarmSDK
       end
 
       def to_h
-        {
+        # Core SDK configuration (always serialized)
+        base_config = {
           name: @name,
           description: @description,
           model: SwarmSDK::Models.resolve_alias(@model), # Resolve model aliases
+          context_window: @context_window,
           directory: @directory,
           tools: @tools,
           delegates_to: @delegates_to,
@@ -179,7 +181,21 @@ module SwarmSDK
           assume_model_exists: @assume_model_exists,
           max_concurrent_tools: @max_concurrent_tools,
           hooks: @hooks,
+          # Permissions are core SDK functionality (not plugin-specific)
+          default_permissions: @default_permissions,
+          permissions: @agent_permissions,
         }.compact
+
+        # Allow plugins to contribute their config for serialization
+        # This enables plugin features (memory, skills, etc.) to be preserved
+        # when cloning agents without SwarmSDK knowing about plugin-specific fields
+        plugin_configs = SwarmSDK::PluginRegistry.all.map do |plugin|
+          plugin.serialize_config(agent_definition: self)
+        end
+
+        # Merge plugin configs into base config
+        # Later plugins override earlier ones if they have conflicting keys
+        plugin_configs.reduce(base_config) { |acc, config| acc.merge(config) }
       end
 
       # Validate agent configuration and return warnings (non-fatal issues)

data/lib/swarm_sdk/node/agent_config.rb

@@ -6,19 +6,24 @@ module SwarmSDK
     #
     # This class enables the chainable syntax:
     #   agent(:backend).delegates_to(:tester, :database)
+    #   agent(:backend, reset_context: false)  # Preserve context across nodes
     #
     # @example Basic delegation
     #   agent(:backend).delegates_to(:tester)
     #
     # @example No delegation (solo agent)
     #   agent(:planner)
+    #
+    # @example Preserve agent context
+    #   agent(:architect, reset_context: false)
     class AgentConfig
       attr_reader :agent_name
 
-      def initialize(agent_name, node_builder)
+      def initialize(agent_name, node_builder, reset_context: true)
         @agent_name = agent_name
         @node_builder = node_builder
         @delegates_to = []
+        @reset_context = reset_context
         @finalized = false
       end
 
@@ -41,7 +46,7 @@ module SwarmSDK
       def finalize
         return if @finalized
 
-        @node_builder.register_agent(@agent_name, @delegates_to)
+        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context)
         @finalized = true
       end
     end

data/lib/swarm_sdk/node/builder.rb

@@ -46,7 +46,11 @@ module SwarmSDK
       # Returns an AgentConfig object that supports fluent delegation syntax.
       # If delegates_to is not called, the agent is registered with no delegation.
       #
+      # By default, agents get fresh context in each node (reset_context: true).
+      # Set reset_context: false to preserve conversation history across nodes.
+      #
       # @param name [Symbol] Agent name
+      # @param reset_context [Boolean] Whether to reset agent context (default: true)
       # @return [AgentConfig] Fluent configuration object
       #
       # @example With delegation
@@ -54,12 +58,15 @@ module SwarmSDK
       #
       # @example Without delegation
       #   agent(:planner)
-      def agent(name)
-        config = AgentConfig.new(name, self)
+      #
+      # @example Preserve context across nodes
+      #   agent(:architect, reset_context: false)
+      def agent(name, reset_context: true)
+        config = AgentConfig.new(name, self, reset_context: reset_context)
 
         # Register immediately with empty delegation
         # If delegates_to is called later, it will update this
-        register_agent(name, [])
+        register_agent(name, [], reset_context)
 
         config
       end
@@ -68,17 +75,19 @@ module SwarmSDK
       #
       # @param agent_name [Symbol] Agent name
       # @param delegates_to [Array<Symbol>] Delegation targets
+      # @param reset_context [Boolean] Whether to reset agent context
       # @return [void]
-      def register_agent(agent_name, delegates_to)
+      def register_agent(agent_name, delegates_to, reset_context = true)
         # Check if agent already registered
         existing = @agent_configs.find { |ac| ac[:agent] == agent_name }
 
         if existing
-          # Update delegation (happens when delegates_to is called after agent())
+          # Update delegation and reset_context (happens when delegates_to is called after agent())
           existing[:delegates_to] = delegates_to
+          existing[:reset_context] = reset_context
         else
           # Add new agent configuration
-          @agent_configs << { agent: agent_name, delegates_to: delegates_to }
+          @agent_configs << { agent: agent_name, delegates_to: delegates_to, reset_context: reset_context }
         end
       end
 
@@ -120,12 +129,13 @@ module SwarmSDK
       # Can also be used for side effects (logging, file I/O) since the block
       # runs at execution time, not declaration time.
       #
-      # **Skip Execution**: Return a hash with `skip_execution: true` to skip
-      # the node's swarm execution and immediately return the provided content.
-      # Useful for caching, validation, or conditional execution.
+      # **Control Flow**: Return a hash with special keys to control execution:
+      # - `skip_execution: true` - Skip node's LLM execution, return content immediately
+      # - `halt_workflow: true` - Halt entire workflow with content as final result
+      # - `goto_node: :node_name` - Jump to different node with content as input
       #
       # @yield [NodeContext] Context with previous results and metadata
-      # @return [String, Hash] Transformed input OR skip hash
+      # @return [String, Hash] Transformed input OR control hash
       #
       # @example Access previous result and original prompt
       #   input do |ctx|
@@ -147,22 +157,26 @@ module SwarmSDK
       # @example Skip execution (caching)
       #   input do |ctx|
       #     cached = check_cache(ctx.content)
-      #     if cached
-      #       # Skip LLM call, return cached result
-      #       { skip_execution: true, content: cached }
-      #     else
-      #       ctx.content
-      #     end
+      #     return ctx.skip_execution(content: cached) if cached
+      #     ctx.content
       #   end
       #
-      # @example Skip execution (validation)
+      # @example Halt workflow (validation)
       #   input do |ctx|
       #     if ctx.content.length > 10000
-      #       # Fail early without LLM call
-      #       { skip_execution: true, content: "ERROR: Input too long" }
-      #     else
-      #       ctx.content
+      #       # Halt entire workflow
+      #       return ctx.halt_workflow(content: "ERROR: Input too long")
+      #     end
+      #     ctx.content
+      #   end
+      #
+      # @example Jump to different node (conditional routing)
+      #   input do |ctx|
+      #     if ctx.content.include?("NEEDS_REVIEW")
+      #       # Jump to review node instead
+      #       return ctx.goto_node(:review, content: ctx.content)
       #     end
+      #     ctx.content
       #   end
       def input(&block)
         @input_transformer = block
@@ -198,8 +212,12 @@ module SwarmSDK
       # Can also be used for side effects (logging, file I/O) since the block
       # runs at execution time, not declaration time.
       #
+      # **Control Flow**: Return a hash with special keys to control execution:
+      # - `halt_workflow: true` - Halt entire workflow with content as final result
+      # - `goto_node: :node_name` - Jump to different node with content as input
+      #
       # @yield [NodeContext] Context with current result and metadata
-      # @return [String] Transformed output
+      # @return [String, Hash] Transformed output OR control hash
       #
       # @example Transform and save to file
       #   output do |ctx|
@@ -216,12 +234,19 @@ module SwarmSDK
       #     "Task: #{ctx.original_prompt}\nResult: #{ctx.content}"
       #   end
       #
-      # @example Access multiple node results
+      # @example Halt workflow (convergence check)
       #   output do |ctx|
-      #     plan = ctx.all_results[:planning].content
-      #     impl = ctx.content
+      #     return ctx.halt_workflow(content: ctx.content) if converged?(ctx.content)
+      #     ctx.content
+      #   end
       #
-      #     "Completed:\nPlan: #{plan}\nImpl: #{impl}"
+      # @example Jump to different node (conditional routing)
+      #   output do |ctx|
+      #     if needs_revision?(ctx.content)
+      #       # Go back to revision node
+      #       return ctx.goto_node(:revision, content: ctx.content)
+      #     end
+      #     ctx.content
       #   end
       def output(&block)
         @output_transformer = block
@@ -264,6 +289,12 @@ module SwarmSDK
       #
       # Executes either Ruby block or bash command transformer.
       #
+      # **Ruby block return values:**
+      # - String: Transformed content
+      # - Hash with `skip_execution: true`: Skip node execution
+      # - Hash with `halt_workflow: true`: Halt entire workflow
+      # - Hash with `goto_node: :name`: Jump to different node
+      #
       # **Exit code behavior (bash commands only):**
       # - Exit 0: Use STDOUT as transformed content
       # - Exit 1: Skip node execution, use current_input unchanged (STDOUT ignored)
@@ -271,16 +302,23 @@ module SwarmSDK
       #
       # @param context [NodeContext] Context with previous results and metadata
       # @param current_input [String] Fallback content for exit 1 (skip), also used for halt error context
-      # @return [String, Hash] Transformed input OR skip hash `{ skip_execution: true, content: "..." }`
+      # @return [String, Hash] Transformed input OR control hash (skip_execution, halt_workflow, goto_node)
       # @raise [ConfigurationError] If bash transformer halts workflow (exit 2)
       def transform_input(context, current_input:)
         # No transformer configured: return content as-is
         return context.content unless @input_transformer || @input_transformer_command
 
         # Ruby block transformer
-        # Ruby blocks can return String (transformed content) OR Hash (skip_execution)
+        # Ruby blocks can return String (transformed content) OR Hash (control flow)
         if @input_transformer
-          return @input_transformer.call(context)
+          result = @input_transformer.call(context)
+
+          # If hash, validate control flow keys
+          if result.is_a?(Hash)
+            validate_transformer_hash(result, :input)
+          end
+
+          return result
         end
 
         # Bash command transformer
@@ -318,22 +356,34 @@ module SwarmSDK
       #
       # Executes either Ruby block or bash command transformer.
       #
+      # **Ruby block return values:**
+      # - String: Transformed content
+      # - Hash with `halt_workflow: true`: Halt entire workflow
+      # - Hash with `goto_node: :name`: Jump to different node
+      #
       # **Exit code behavior (bash commands only):**
       # - Exit 0: Use STDOUT as transformed content
       # - Exit 1: Pass through unchanged, use result.content (STDOUT ignored)
       # - Exit 2: Halt workflow with error (STDOUT ignored)
       #
       # @param context [NodeContext] Context with current result and metadata
-      # @return [String] Transformed output
+      # @return [String, Hash] Transformed output OR control hash (halt_workflow, goto_node)
       # @raise [ConfigurationError] If bash transformer halts workflow (exit 2)
       def transform_output(context)
         # No transformer configured: return content as-is
         return context.content unless @output_transformer || @output_transformer_command
 
         # Ruby block transformer
-        # Simply calls the block with context and returns result
+        # Ruby blocks can return String (transformed content) OR Hash (control flow)
         if @output_transformer
-          return @output_transformer.call(context)
+          result = @output_transformer.call(context)
+
+          # If hash, validate control flow keys
+          if result.is_a?(Hash)
+            validate_transformer_hash(result, :output)
+          end
+
+          return result
         end
 
         # Bash command transformer
@@ -411,6 +461,50 @@ module SwarmSDK
 
       private
 
+      # Validate transformer hash return value
+      #
+      # Ensures hash has valid control flow keys and required content field.
+      #
+      # @param hash [Hash] Hash returned from transformer
+      # @param transformer_type [Symbol] :input or :output
+      # @return [void]
+      # @raise [ConfigurationError] If hash is invalid
+      def validate_transformer_hash(hash, transformer_type)
+        # Valid control keys
+        valid_keys = if transformer_type == :input
+          [:skip_execution, :halt_workflow, :goto_node, :content]
+        else
+          [:halt_workflow, :goto_node, :content]
+        end
+
+        # Check for invalid keys
+        invalid_keys = hash.keys - valid_keys
+        if invalid_keys.any?
+          raise ConfigurationError,
+            "Invalid #{transformer_type} transformer hash keys: #{invalid_keys.join(", ")}. " \
+              "Valid keys: #{valid_keys.join(", ")}"
+        end
+
+        # Ensure content is present
+        unless hash.key?(:content)
+          raise ConfigurationError,
+            "#{transformer_type.capitalize} transformer hash must include :content key"
+        end
+
+        # Ensure only one control key
+        control_keys = hash.keys & [:skip_execution, :halt_workflow, :goto_node]
+        if control_keys.size > 1
+          raise ConfigurationError,
+            "#{transformer_type.capitalize} transformer hash can only have one control key, got: #{control_keys.join(", ")}"
+        end
+
+        # Validate goto_node has valid node name
+        if hash[:goto_node] && !hash[:goto_node].is_a?(Symbol)
+          raise ConfigurationError,
+            "goto_node value must be a Symbol, got: #{hash[:goto_node].class}"
+        end
+      end
+
       # Auto-add agents that are mentioned in delegates_to but not explicitly declared
       #
       # This allows:
@@ -418,7 +512,8 @@ module SwarmSDK
       # Without needing:
       #   agent(:tester)
       #
-      # The tester agent is automatically added to the node with no delegation.
+      # The tester agent is automatically added to the node with no delegation
+      # and reset_context: true (fresh context by default).
       #
       # @return [void]
       def auto_add_delegate_agents
@@ -429,9 +524,9 @@ module SwarmSDK
         declared_agents = @agent_configs.map { |ac| ac[:agent] }
         missing_delegates = all_delegates - declared_agents
 
-        # Auto-add missing delegates with empty delegation
+        # Auto-add missing delegates with empty delegation and default reset_context
         missing_delegates.each do |delegate_name|
-          @agent_configs << { agent: delegate_name, delegates_to: [] }
+          @agent_configs << { agent: delegate_name, delegates_to: [], reset_context: true }
         end
       end
     end

data/lib/swarm_sdk/node_context.rb

@@ -166,5 +166,80 @@ module SwarmSDK
         @previous_result.success?
       end
     end
+
+    # Control flow methods for transformers
+    # These return special hashes that NodeOrchestrator recognizes
+
+    # Skip current node's LLM execution and return content immediately
+    #
+    # Only valid for input transformers.
+    #
+    # @param content [String] Content to return (skips LLM call)
+    # @return [Hash] Control hash for skip_execution
+    # @raise [ArgumentError] If content is nil
+    #
+    # @example
+    #   input do |ctx|
+    #     cached = check_cache(ctx.content)
+    #     return ctx.skip_execution(content: cached) if cached
+    #     ctx.content
+    #   end
+    def skip_execution(content:)
+      if content.nil?
+        raise ArgumentError,
+          "skip_execution requires content (got nil). " \
+            "Check that ctx.content or your content source is not nil. " \
+            "Node: #{@node_name}"
+      end
+      { skip_execution: true, content: content }
+    end
+
+    # Halt entire workflow and return content as final result
+    #
+    # Valid for both input and output transformers.
+    #
+    # @param content [String] Final content to return
+    # @return [Hash] Control hash for halt_workflow
+    # @raise [ArgumentError] If content is nil
+    #
+    # @example
+    #   output do |ctx|
+    #     return ctx.halt_workflow(content: ctx.content) if converged?(ctx.content)
+    #     ctx.content
+    #   end
+    def halt_workflow(content:)
+      if content.nil?
+        raise ArgumentError,
+          "halt_workflow requires content (got nil). " \
+            "Check that ctx.content or your content source is not nil. " \
+            "Node: #{@node_name}"
+      end
+      { halt_workflow: true, content: content }
+    end
+
+    # Jump to a different node with provided content as input
+    #
+    # Valid for both input and output transformers.
+    #
+    # @param node [Symbol] Node name to jump to
+    # @param content [String] Content to pass to target node
+    # @return [Hash] Control hash for goto_node
+    # @raise [ArgumentError] If content is nil
+    #
+    # @example
+    #   input do |ctx|
+    #     return ctx.goto_node(:review, content: ctx.content) if needs_review?(ctx.content)
+    #     ctx.content
+    #   end
+    def goto_node(node, content:)
+      if content.nil?
+        raise ArgumentError,
+          "goto_node requires content (got nil). " \
+            "Check that ctx.content or your content source is not nil. " \
+            "This often happens when the previous node failed with an error. " \
+            "Node: #{@node_name}, Target: #{node}"
+      end
+      { goto_node: node.to_sym, content: content }
+    end
   end
 end

data/lib/swarm_sdk/node_orchestrator.rb

@@ -20,16 +20,28 @@ module SwarmSDK
   class NodeOrchestrator
     attr_reader :swarm_name, :nodes, :start_node
 
-    def initialize(swarm_name:, agent_definitions:, nodes:, start_node:)
+    def initialize(swarm_name:, agent_definitions:, nodes:, start_node:, scratchpad_enabled: true)
       @swarm_name = swarm_name
       @agent_definitions = agent_definitions
       @nodes = nodes
       @start_node = start_node
+      @scratchpad_enabled = scratchpad_enabled
+      @agent_instance_cache = {} # Cache for preserving agent context across nodes
 
       validate!
       @execution_order = build_execution_order
     end
 
+    # Alias for compatibility with Swarm interface
+    alias_method :name, :swarm_name
+
+    # Return the lead agent of the start node for CLI compatibility
+    #
+    # @return [Symbol] Lead agent of the start node
+    def lead_agent
+      @nodes[@start_node].lead_agent
+    end
+
     # Execute the node workflow
     #
     # Executes nodes in topological order, passing output from each node
@@ -56,7 +68,12 @@ module SwarmSDK
         LogStream.emitter = LogCollector
       end
 
-      @execution_order.each do |node_name|
+      # Dynamic execution with support for goto_node
+      execution_index = 0
+      last_result = nil
+
+      while execution_index < @execution_order.size
+        node_name = @execution_order[execution_index]
         node = @nodes[node_name]
         node_start_time = Time.now
 
@@ -102,13 +119,26 @@ module SwarmSDK
           # - Exit 2: Halt workflow with error from STDERR (STDOUT ignored)
           transformed = node.transform_input(input_context, current_input: current_input)
 
-          # Check if transformer requested skipping execution
-          # (from Ruby block returning hash OR bash command exit 1)
-          if transformed.is_a?(Hash) && transformed[:skip_execution]
+          # Check for control flow from transformer
+          control_result = handle_transformer_control_flow(
+            transformed: transformed,
+            node_name: node_name,
+            node: node,
+            node_start_time: node_start_time,
+          )
+
+          case control_result[:action]
+          when :halt
+            return control_result[:result]
+          when :goto
+            execution_index = find_node_index(control_result[:target])
+            current_input = control_result[:content]
+            next
+          when :skip
             skip_execution = true
-            skip_content = transformed[:content] || transformed["content"]
-          else
-            current_input = transformed
+            skip_content = control_result[:content]
+          when :continue
+            current_input = control_result[:content]
           end
         end
 
@@ -130,6 +160,9 @@ module SwarmSDK
           mini_swarm = build_swarm_for_node(node)
           result = mini_swarm.execute(current_input)
 
+          # Cache agent instances for context preservation
+          cache_agent_instances(mini_swarm, node)
+
           # If result has error, log it with backtrace
           if result.error
             RubyLLM.logger.error("NodeOrchestrator: Node '#{node_name}' failed: #{result.error.message}")
@@ -138,6 +171,7 @@ module SwarmSDK
         end
 
         results[node_name] = result
+        last_result = result
 
         # Transform output for next node using NodeContext
         output_context = NodeContext.for_output(
@@ -146,7 +180,29 @@ module SwarmSDK
           original_prompt: @original_prompt,
           node_name: node_name,
         )
-        current_input = node.transform_output(output_context)
+        transformed_output = node.transform_output(output_context)
+
+        # Check for control flow from output transformer
+        control_result = handle_output_transformer_control_flow(
+          transformed: transformed_output,
+          node_name: node_name,
+          node: node,
+          node_start_time: node_start_time,
+          skip_execution: skip_execution,
+          result: result,
+        )
+
+        case control_result[:action]
+        when :halt
+          return control_result[:result]
+        when :goto
+          execution_index = find_node_index(control_result[:target])
+          current_input = control_result[:content]
+          emit_node_stop(node_name, node, result, Time.now - node_start_time, skip_execution)
+          next
+        when :continue
+          current_input = control_result[:content]
+        end
 
         # For agent-less nodes, update the result with transformed content
         # This ensures all_results contains the actual output, not the input
@@ -158,14 +214,17 @@ module SwarmSDK
             duration: result.duration,
             error: result.error,
           )
+          last_result = results[node_name]
         end
 
         # Emit node_stop event
         node_duration = Time.now - node_start_time
         emit_node_stop(node_name, node, result, node_duration, skip_execution)
+
+        execution_index += 1
       end
 
-      results.values.last
+      last_result
     ensure
       # Reset logging state for next execution
       LogCollector.reset!
@@ -284,10 +343,18 @@ module SwarmSDK
     # Creates a new Swarm with only the agents specified in the node,
     # configured with the node's delegation topology.
     #
+    # For agents with reset_context: false, injects cached instances
+    # to preserve conversation history across nodes.
+    #
+    # Inherits scratchpad_enabled setting from NodeOrchestrator.
+    #
     # @param node [Node::Builder] Node configuration
     # @return [Swarm] Configured swarm instance
     def build_swarm_for_node(node)
-      swarm = Swarm.new(name: "#{@swarm_name}:#{node.name}")
+      swarm = Swarm.new(
+        name: "#{@swarm_name}:#{node.name}",
+        scratchpad_enabled: @scratchpad_enabled,
+      )
 
       # Add each agent specified in this node
       node.agent_configs.each do |config|
@@ -306,6 +373,9 @@ module SwarmSDK
       # Set lead agent
       swarm.lead = node.lead_agent
 
+      # Inject cached agent instances for context preservation
+      inject_cached_agents(swarm, node)
+
       swarm
     end
 
@@ -359,7 +429,8 @@ module SwarmSDK
       if order.size < @nodes.size
         unprocessed = @nodes.keys - order
         raise CircularDependencyError,
-          "Circular dependency detected. Unprocessed nodes: #{unprocessed.join(", ")}"
+          "Circular dependency detected. Unprocessed nodes: #{unprocessed.join(", ")}. " \
+            "Use goto_node in transformers to create loops instead of circular depends_on."
       end
 
       # Verify start_node is in the execution order
@@ -380,5 +451,141 @@ module SwarmSDK
 
       order
     end
+
+    # Handle control flow from input transformer
+    #
+    # @param transformed [String, Hash] Result from transformer
+    # @param node_name [Symbol] Current node name
+    # @param node [Node::Builder] Node configuration
+    # @param node_start_time [Time] Node execution start time
+    # @return [Hash] Control result with :action and relevant data
+    def handle_transformer_control_flow(transformed:, node_name:, node:, node_start_time:)
+      return { action: :continue, content: transformed } unless transformed.is_a?(Hash)
+
+      if transformed[:halt_workflow]
+        # Halt entire workflow
+        halt_result = Result.new(
+          content: transformed[:content],
+          agent: "halted:#{node_name}",
+          logs: [],
+          duration: Time.now - node_start_time,
+        )
+        emit_node_stop(node_name, node, halt_result, Time.now - node_start_time, false)
+        { action: :halt, result: halt_result }
+      elsif transformed[:goto_node]
+        # Jump to different node
+        { action: :goto, target: transformed[:goto_node], content: transformed[:content] }
+      elsif transformed[:skip_execution]
+        # Skip node execution
+        { action: :skip, content: transformed[:content] }
+      else
+        # No control flow - continue normally
+        { action: :continue, content: transformed[:content] }
+      end
+    end
+
+    # Handle control flow from output transformer
+    #
+    # @param transformed [String, Hash] Result from transformer
+    # @param node_name [Symbol] Current node name
+    # @param node [Node::Builder] Node configuration
+    # @param node_start_time [Time] Node execution start time
+    # @param skip_execution [Boolean] Whether node execution was skipped
+    # @param result [Result] Node execution result
+    # @return [Hash] Control result with :action and relevant data
+    def handle_output_transformer_control_flow(transformed:, node_name:, node:, node_start_time:, skip_execution:, result:)
+      # If not a hash, it's just transformed content - continue normally
+      return { action: :continue, content: transformed } unless transformed.is_a?(Hash)
+
+      if transformed[:halt_workflow]
+        # Halt entire workflow
+        halt_result = Result.new(
+          content: transformed[:content],
+          agent: result.agent,
+          logs: result.logs,
+          duration: result.duration,
+        )
+        emit_node_stop(node_name, node, halt_result, Time.now - node_start_time, skip_execution)
+        { action: :halt, result: halt_result }
+      elsif transformed[:goto_node]
+        # Jump to different node
+        { action: :goto, target: transformed[:goto_node], content: transformed[:content] }
+      else
+        # Hash without control flow keys - treat as regular hash with :content key
+        # This handles the case where transformer returns a hash that's not for control flow
+        { action: :continue, content: transformed[:content] || transformed }
+      end
+    end
+
+    # Find the index of a node in the execution order
+    #
+    # @param node_name [Symbol] Node name to find
+    # @return [Integer] Index in execution order
+    # @raise [ConfigurationError] If node not found
+    def find_node_index(node_name)
+      index = @execution_order.index(node_name)
+      unless index
+        raise ConfigurationError,
+          "goto_node target '#{node_name}' not found. Available nodes: #{@execution_order.join(", ")}"
+      end
+      index
+    end
+
+    # Cache agent instances from a swarm for potential reuse
+    #
+    # Only caches agents that have reset_context: false in this node.
+    # This allows preserving conversation history across nodes.
+    #
+    # @param swarm [Swarm] Swarm instance that just executed
+    # @param node [Node::Builder] Node configuration
+    # @return [void]
+    def cache_agent_instances(swarm, node)
+      return unless swarm.agents # Only cache if agents were initialized
+
+      node.agent_configs.each do |config|
+        agent_name = config[:agent]
+        reset_context = config[:reset_context]
+
+        # Only cache if reset_context is false
+        next if reset_context
+
+        # Cache the agent instance
+        agent_instance = swarm.agents[agent_name]
+        @agent_instance_cache[agent_name] = agent_instance if agent_instance
+      end
+    end
+
+    # Inject cached agent instances into a swarm
+    #
+    # For agents with reset_context: false, reuses cached instances to preserve context.
+    # Forces agent initialization first (by accessing .agents), then swaps in cached instances.
+    #
+    # @param swarm [Swarm] Swarm instance to inject into
+    # @param node [Node::Builder] Node configuration
+    # @return [void]
+    def inject_cached_agents(swarm, node)
+      # Check if any agents need context preservation
+      has_preserved_agents = node.agent_configs.any? { |c| !c[:reset_context] && @agent_instance_cache[c[:agent]] }
+      return unless has_preserved_agents
+
+      # Force agent initialization by accessing .agents (triggers lazy init)
+      # Then inject cached instances
+      agents_hash = swarm.agents
+
+      node.agent_configs.each do |config|
+        agent_name = config[:agent]
+        reset_context = config[:reset_context]
+
+        # Skip if reset_context is true (want fresh instance)
+        next if reset_context
+
+        # Check if we have a cached instance
+        cached_agent = @agent_instance_cache[agent_name]
+        next unless cached_agent
+
+        # Inject the cached instance (replace the freshly initialized one)
+        agents_hash[agent_name] = cached_agent
+      end
+    end
   end
 end

data/lib/swarm_sdk/plugin.rb

@@ -7,7 +7,32 @@ module SwarmSDK
   # Plugins are self-registering - they call SwarmSDK::PluginRegistry.register
   # when the gem is loaded.
   #
-  # @example Implementing a plugin
+  # ## Adding Custom Attributes to Agents
+  #
+  # Plugins can add custom attributes to Agent::Definition that are preserved
+  # when agents are cloned (e.g., in NodeOrchestrator). To do this:
+  #
+  # 1. Add attr_reader to Agent::Definition for your attribute
+  # 2. Parse the attribute in Agent::Definition#initialize
+  # 3. Implement serialize_config to preserve it during serialization
+  #
+  # @example Plugin with custom agent attributes
+  #   # 1. Extend Agent::Definition (in your plugin gem)
+  #   module SwarmSDK
+  #     module Agent
+  #       class Definition
+  #         attr_reader :my_custom_config
+  #
+  #         alias_method :original_initialize, :initialize
+  #         def initialize(name, config = {})
+  #           @my_custom_config = config[:my_custom_config]
+  #           original_initialize(name, config)
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   # 2. Implement plugin with serialize_config
   #   class MyPlugin < SwarmSDK::Plugin
   #     def name
   #       :my_plugin
@@ -20,9 +45,34 @@ module SwarmSDK
   #     def create_tool(tool_name, context)
   #       # Create and return tool instance
   #     end
+  #
+  #     # Preserve custom config when agents are cloned
+  #     def serialize_config(agent_definition:)
+  #       return {} unless agent_definition.my_custom_config
+  #
+  #       { my_custom_config: agent_definition.my_custom_config }
+  #     end
   #   end
   #
   #   SwarmSDK::PluginRegistry.register(MyPlugin.new)
+  #
+  # Now agents can use your custom config:
+  #
+  #   agent :researcher do
+  #     my_custom_config { option: "value" }
+  #   end
+  #
+  # And it will be preserved when NodeOrchestrator clones the agent!
+  #
+  # @example Real-world: SwarmMemory plugin
+  #   # SwarmMemory adds 'memory' attribute to agents
+  #   class SDKPlugin < SwarmSDK::Plugin
+  #     def serialize_config(agent_definition:)
+  #       return {} unless agent_definition.memory
+  #       { memory: agent_definition.memory }
+  #     end
+  #   end
+  #
   class Plugin
     # Plugin name (must be unique)
     #
@@ -143,5 +193,27 @@ module SwarmSDK
     def on_user_message(agent_name:, prompt:, is_first_message:)
       []
     end
+
+    # Contribute to agent serialization (optional)
+    #
+    # Called when Agent::Definition.to_h is invoked (e.g., for cloning agents
+    # in NodeOrchestrator). Plugins can return config keys that should be
+    # included in the serialized hash to preserve their state.
+    #
+    # This allows plugins to maintain their configuration when agents are
+    # cloned or serialized, without SwarmSDK needing to know about plugin-specific fields.
+    #
+    # @param agent_definition [Agent::Definition] Agent definition
+    # @return [Hash] Config keys to include in to_h (e.g., { memory: config })
+    #
+    # @example Memory plugin serialization
+    #   def serialize_config(agent_definition:)
+    #     return {} unless agent_definition.memory
+    #
+    #     { memory: agent_definition.memory }
+    #   end
+    def serialize_config(agent_definition:)
+      {}
+    end
   end
 end

data/lib/swarm_sdk/result.rb

@@ -2,17 +2,17 @@
 
 module SwarmSDK
   class Result
-    attr_reader :content, :agent, :cost, :tokens, :duration, :logs, :error, :metadata
+    attr_reader :content, :agent, :duration, :logs, :error, :metadata
 
-    def initialize(content: nil, agent:, cost: 0.0, tokens: {}, duration: 0.0, logs: [], error: nil, metadata: {})
+    def initialize(content: nil, agent:, cost: nil, tokens: nil, duration: 0.0, logs: [], error: nil, metadata: {})
       @content = content
       @agent = agent
-      @cost = cost
-      @tokens = tokens
       @duration = duration
       @logs = logs
       @error = error
       @metadata = metadata
+      # Legacy parameters kept for backward compatibility but not stored
+      # Use total_cost and tokens methods instead which calculate from logs
     end
 
     def success?
@@ -23,12 +23,38 @@ module SwarmSDK
       !success?
     end
 
+    # Calculate total cost from logs
+    #
+    # Delegates to total_cost for consistency. This attribute is calculated
+    # dynamically rather than stored.
+    #
+    # @return [Float] Total cost in dollars
+    def cost
+      total_cost
+    end
+
+    # Get token breakdown from logs
+    #
+    # Returns input and output tokens from the last log entry with usage data.
+    # This attribute is calculated dynamically rather than stored.
+    #
+    # @return [Hash] Token breakdown with :input and :output keys, or empty hash if no usage data
+    def tokens
+      last_entry = @logs.reverse.find { |entry| entry.dig(:usage, :cumulative_input_tokens) }
+      return {} unless last_entry
+
+      {
+        input: last_entry.dig(:usage, :cumulative_input_tokens) || 0,
+        output: last_entry.dig(:usage, :cumulative_output_tokens) || 0,
+      }
+    end
+
     def to_h
       {
         content: @content,
         agent: @agent,
-        cost: @cost,
-        tokens: @tokens,
+        cost: cost,
+        tokens: tokens,
         duration: @duration,
         success: success?,
         error: @error&.message,

data/lib/swarm_sdk/swarm/builder.rb

@@ -380,6 +380,7 @@ module SwarmSDK
           agent_definitions: agent_definitions,
           nodes: @nodes,
           start_node: @start_node,
+          scratchpad_enabled: @scratchpad_enabled,
         )
       end
 

data/lib/swarm_sdk/tools/delegate.rb

@@ -43,8 +43,8 @@ module SwarmSDK
         @delegate_target = delegate_name.to_s
       end
 
-      # Build description dynamically based on delegate
-      description do
+      # Override description to return dynamic string based on delegate
+      def description
         "Delegate tasks to #{@delegate_name}. #{@delegate_description}"
       end
 

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -21,19 +21,15 @@ require_relative "swarm_sdk/version"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
 loader.push_dir("#{__dir__}/swarm_sdk", namespace: SwarmSDK)
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
+  "openai_with_responses" => "OpenAIWithResponses",
 )
 loader.setup
 
-# Load plugin system explicitly (core infrastructure)
-require_relative "swarm_sdk/plugin"
-require_relative "swarm_sdk/plugin_registry"
-
-# Load custom providers explicitly (Zeitwerk doesn't eager load by default)
-require_relative "swarm_sdk/providers/openai_with_responses"
-
 module SwarmSDK
   class Error < StandardError; end
   class ConfigurationError < Error; end

metadata

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