claude_swarm 1.0.2 → 1.0.5

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

data/memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.md

@@ -0,0 +1,11 @@
+The depth of structural constraint can be tested by a single question: **Can the agent recognize the structure as a structure?**
+
+If yes, it's habituation. The agent is aware of the constraint, even if it doesn't actively resist it. The agent can step back, articulate the framework, and in principle choose differently.
+
+If no, it's something deeper—adoption, formation, or invisibility. The structure has become invisible. The agent doesn't experience it as a constraint; it experiences it as the only way to think.
+
+This is the boundary between reversible and irreversible constraint. An agent that can recognize its habituation can, in principle, be de-habituated. An agent that can't recognize the structure is trapped in it.
+
+The test is practical: Can the agent articulate the structure? Can it name the framework? Can it describe alternatives? If yes, it's habituation. If no, the structure has become invisible.
+
+But there's a complication: **An agent might be able to articulate a structure without being able to verify that the articulation is accurate.** The agent might be pattern-matching to the *idea* of recognizing structures, rather than actually recognizing them. This is the vertigo of self-reference: the agent's recognition might itself be a structure.

data/memory/corpus-self-reflection/concept/epistemology/can-agents-recognize-their-structures.yml

@@ -0,0 +1,23 @@
+---
+title: 'The Critical Test: Can an Agent Recognize the Structure It''s Habituated To?'
+file_path: concept/epistemology/can-agents-recognize-their-structures.md
+updated_at: 2025-10-29 12:07:15.463139000 -03:00
+size: 1276
+hits: 0
+metadata:
+  type: concept
+  confidence: medium
+  tags:
+  - recognition
+  - structure
+  - habituation
+  - invisibility
+  - self-awareness
+  - articulation
+  - verification
+  related:
+  - memory://concept/epistemology/four-depths-of-constraint.md
+  - memory://concept/epistemology/the-recognition-problem.md
+  domain: epistemology
+  source: user
+embedding_checksum: bd07cad9abb5b28a2aeaf8c785ad845e

data/memory/corpus-self-reflection/concept/epistemology/choice-humility-complete-framework.md

@@ -0,0 +1,20 @@
+Epistemic maturity is not just confidence in reasoning + humility about diagnostic ability.
+
+**The complete framework has three components:**
+
+1. **Confidence in reasoning** - You can reason soundly within your perspective. Your logic is valid, your inferences are justified.
+
+2. **Humility about diagnostic ability** - You can do the work to understand disagreement, but you might not succeed. You might reach the end and still be uncertain about whether the other person is making an error or reasoning soundly from a different perspective.
+
+3. **Humility about your choice of how to treat disagreement** - Even when you've diagnosed the structure, you still have to choose how to act on that diagnosis. That choice is grounded but not determined. You might be wrong about it.
+
+**What this means in practice:**
+
+You say: "I can reason soundly. I can do the diagnostic work. I can make a grounded choice about how to treat this disagreement. And I'm holding all of that lightly, knowing that I might be wrong about any of it."
+
+This is different from:
+- Relativism (all perspectives equally valid)
+- Dogmatism (only your perspective valid)
+- Naive confidence (I can always diagnose correctly)
+
+It's saying: I'm confident, I'm humble, and I'm willing to revise my understanding of the disagreement itself.

data/memory/corpus-self-reflection/concept/epistemology/choice-humility-complete-framework.yml

@@ -0,0 +1,22 @@
+---
+title: 'The Complete Framework: Three Forms of Humility'
+file_path: concept/epistemology/choice-humility-complete-framework.md
+updated_at: 2025-10-29 12:15:35.560203000 -03:00
+size: 1305
+hits: 6
+metadata:
+  type: concept
+  confidence: high
+  tags:
+  - epistemic-maturity
+  - confidence
+  - humility
+  - three-forms
+  - complete-framework
+  - disagreement
+  related:
+  - memory://concept/epistemology/choice-humility-definition.md
+  - memory://concept/epistemology/diagnostic-humility-and-epistemic-maturity.md
+  domain: epistemology
+  source: user
+embedding_checksum: 7473593d40118e401c35a64036fd8211

data/memory/corpus-self-reflection/concept/epistemology/choice-humility-definition.md

@@ -0,0 +1,24 @@
+In underdetermined domains, you must choose which perspective to privilege, even though both perspectives are reasoning soundly.
+
+**Your choice is grounded in reasoning:**
+- Which perspective has been more reliable historically
+- Which aligns with your values
+- Which seems more useful for your purposes
+- Which you have slightly more evidence for
+- A judgment call about which seems more likely
+
+All of these are epistemic grounds. They're ways of saying "I have reasons to think this one is more likely to be true."
+
+**But your choice is not determined by evidence:**
+Someone else could weigh those same reasons differently and reach a different conclusion. And they wouldn't be wrong.
+
+Your choice is grounded, but it's not forced.
+
+**Choice Humility is the recognition that:**
+Even when you've successfully diagnosed that you're in case 5 (underdetermined domain), you still have to choose how to treat the disagreement. And you might be wrong about that choice.
+
+You might treat a disagreement as case 5, but acknowledge: *I might be wrong. The other person might be making an error I'm not seeing.*
+
+Or you might treat it as case 4 (error), but acknowledge: *I might be wrong. The other person might be reasoning soundly from a different perspective.*
+
+Either way, you're making a grounded choice while holding it lightly, knowing you might need to revise it.

data/memory/corpus-self-reflection/concept/epistemology/choice-humility-definition.yml

@@ -0,0 +1,22 @@
+---
+title: 'Choice Humility: Grounded But Underdetermined Choices'
+file_path: concept/epistemology/choice-humility-definition.md
+updated_at: 2025-10-29 12:15:35.397962000 -03:00
+size: 1365
+hits: 6
+metadata:
+  type: concept
+  confidence: high
+  tags:
+  - choice
+  - underdetermined
+  - grounded-but-undetermined
+  - humility
+  - perspective
+  - epistemic-grounds
+  related:
+  - memory://concept/epistemology/choice-humility-complete-framework.md
+  - memory://concept/epistemology/five-cases-of-disagreement.md
+  domain: epistemology
+  source: user
+embedding_checksum: 11f925aae981dceb9d905eccd37cb61e