claude_swarm 1.0.6 → 1.0.7

data/examples/v2/dsl/06_permissions.rb

@@ -8,10 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/06_permissions.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
-require_relative "../../../swarm_sdk/all_agents_builder"
-require_relative "../../../swarm_sdk/permissions_builder"
 require "fileutils"
 
 ENV["OPENAI_API_KEY"] = "test-key"

data/examples/v2/dsl/07_mcp_server.rb

@@ -8,8 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/07_mcp_server.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 

data/examples/v2/dsl/08_swarm_hooks.rb

@@ -8,8 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/08_swarm_hooks.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 

data/examples/v2/dsl/09_agent_hooks.rb

@@ -8,8 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/09_agent_hooks.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 

data/examples/v2/dsl/10_all_agents_hooks.rb

@@ -8,9 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/10_all_agents_hooks.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
-require_relative "../../../swarm_sdk/all_agents_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 

data/examples/v2/dsl/11_delegation.rb

@@ -8,8 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/11_delegation.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 

data/examples/v2/dsl/12_complete_integration.rb

@@ -8,10 +8,6 @@
 # Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/12_complete_integration.rb
 
 require "swarm_sdk"
-require_relative "../../../swarm_sdk/swarm_builder"
-require_relative "../../../swarm_sdk/agent_builder"
-require_relative "../../../swarm_sdk/all_agents_builder"
-require_relative "../../../swarm_sdk/permissions_builder"
 
 ENV["OPENAI_API_KEY"] = "test-key"
 
@@ -76,7 +72,7 @@ swarm = SwarmSDK.build do
 
     # Advanced flags
     bypass_permissions(false)
-    skip_base_prompt(false)
+    coding_agent(false)
     assume_model_exists(true)
     timeout(120)
 
@@ -113,7 +109,7 @@ puts "  ✓ Agent identity (system_prompt, description)"
 puts "  ✓ Capabilities (tools, delegates_to, directory)"
 puts "  ✓ MCP servers (filesystem via stdio)"
 puts "  ✓ LLM params (parameters, timeout)"
-puts "  ✓ Advanced flags (disable_default_tools, bypass_permissions, skip_base_prompt, assume_model_exists)"
+puts "  ✓ Advanced flags (disable_default_tools, bypass_permissions, coding_agent, assume_model_exists)"
 puts "  ✓ Permissions (all_agents and agent-level)"
 puts "  ✓ Hooks (swarm-level, agent-level, all_agents)"
 puts "  ✓ Delegation"

data/examples/v2/node_context_demo.rb

@@ -10,7 +10,7 @@
 #
 # Run: ruby examples/node_context_demo.rb
 
-require_relative "../lib/swarm_sdk"
+require "swarm_sdk"
 
 swarm = SwarmSDK.build do
   name("NodeContext Demo")

data/examples/v2/node_workflow.rb

@@ -13,7 +13,7 @@
 #
 # Run: ruby examples/node_workflow.rb
 
-require_relative "../lib/swarm_sdk"
+require "swarm_sdk"
 
 swarm = SwarmSDK.build do
   name("Haiku Workflow")
@@ -27,7 +27,6 @@ swarm = SwarmSDK.build do
       Your job is to break down tasks into smaller subtasks. Extract the intent of the user's prompt and break it down into smaller subtasks.
       Return a list of subtasks.
     PROMPT
-    tools(include_default: false)
   end
 
   agent(:implementer) do
@@ -37,7 +36,6 @@ swarm = SwarmSDK.build do
     system_prompt(<<~PROMPT)
       Your job is to execute the subtasks given to you.
     PROMPT
-    tools(include_default: false)
   end
 
   agent(:verifier) do
@@ -47,12 +45,12 @@ swarm = SwarmSDK.build do
     system_prompt(<<~PROMPT)
       Your job is to verify work given to you and return a summary of your findings
     PROMPT
-    tools(include_default: false)
   end
 
   # Stage 1: Planning
   node(:planning) do
     # Input transformer - ctx.content is the initial prompt
+    # Demonstrates using return for early exit with skip_execution
     input do |ctx|
       <<~PROMPT
         Please break down the following prompt into smaller subtasks:

data/examples/v2/plan_and_execute.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "swarm_sdk"
+
+# Example: Plan and Execute Pattern
+# Two nodes, one agent - first node plans, second node executes the plan
+
+swarm = SwarmSDK.build do
+  name("Plan and Execute")
+
+  # Define a single agent that will be used in both nodes
+  agent(:assistant) do
+    description("A versatile assistant that can plan and execute tasks")
+    provider(:openai)
+    model("gpt-5")
+    coding_agent(false)
+
+    system_prompt(<<~PROMPT)
+      You are a helpful assistant who can both plan and execute tasks.
+
+      When planning, you should:
+      - Break down the task into clear, actionable steps
+      - Identify any dependencies or prerequisites
+      - Consider potential challenges
+
+      When executing, you should:
+      - Follow the plan carefully
+      - Use available tools effectively
+      - Report on progress and completion
+    PROMPT
+
+    # Give the assistant tools for execution
+    disable_default_tools(true)
+  end
+
+  # Node 1: Planning stage
+  # The agent receives the original input and creates a plan
+  node(:planning) do
+    # Use the assistant agent in planning mode (fresh context)
+    agent(:assistant)
+
+    # Transform input for planning
+    #
+    # NOTE: Input/output blocks are automatically converted to lambdas,
+    # which means you can use `return` safely for early exits!
+    #
+    # Example of using return for conditional skip:
+    # return ctx.skip_execution(content: "cached result") if cached
+    input do |ctx|
+      <<~INPUT
+        Please create a detailed plan for the following task:
+
+        #{ctx.original_prompt}
+
+        Your plan should:
+        1. Break down the task into specific steps
+        2. Identify what needs to be done first
+        3. List any tools or resources needed
+        4. Be clear and actionable
+
+        Output your plan in a structured format.
+      INPUT
+    end
+
+    # Transform output to extract key information
+    output do |ctx|
+      # Save the plan to a file for reference
+      File.write("plan.txt", ctx.content)
+
+      # Pass the plan to the next node
+      <<~OUTPUT
+        PLAN CREATED:
+        #{ctx.content}
+
+        Now execute this plan step by step.
+      OUTPUT
+    end
+  end
+
+  # Node 2: Execution stage
+  # The agent receives the plan and executes it
+  node(:implementation) do
+    # Depends on planning node
+    depends_on(:planning)
+
+    # Use the assistant agent in execution mode (fresh context)
+    agent(:assistant)
+
+    # Transform input to provide context from planning
+    input do |ctx|
+      plan = ctx.all_results[:planning].content
+
+      <<~INPUT
+        You previously created the following plan:
+
+        #{plan}
+
+        Now execute this plan. Use the available tools (Write, Edit, Bash) to complete each step.
+        Report on what you accomplished.
+      INPUT
+    end
+
+    # Output transformer for final results
+    output do |ctx|
+      <<~OUTPUT
+        EXECUTION COMPLETE
+
+        #{ctx.content}
+
+        Plan reference: #{File.exist?("plan.txt") ? "Saved in plan.txt" : "Not saved"}
+      OUTPUT
+    end
+  end
+
+  # Set the starting node
+  start_node(:planning)
+end
+
+# Execute the swarm
+if __FILE__ == $PROGRAM_NAME
+  # Example task
+  task = "Create a simple Ruby script that reads a CSV file and outputs a summary"
+
+  puts "Starting Plan and Execute swarm..."
+  puts "Task: #{task}"
+  puts "\n" + "=" * 80 + "\n"
+
+  result = swarm.execute(task) do |log|
+    # Optional: Log events as they happen
+    case log[:type]
+    when "node_start"
+      puts "\n🔵 Starting node: #{log[:node]}"
+    when "node_complete"
+      puts "✅ Completed node: #{log[:node]} (#{log[:duration].round(2)}s)"
+    when "tool_call"
+      puts "  🔧 Tool: #{log[:tool]}"
+    end
+  end
+
+  puts "\n" + "=" * 80 + "\n"
+
+  if result.success?
+    puts "✅ Swarm execution successful!\n\n"
+    puts result.content
+    puts "\n" + "-" * 80
+    puts "Stats:"
+    puts "  Duration: #{result.duration.round(2)}s"
+    puts "  Total cost: $#{result.total_cost.round(4)}"
+    puts "  Total tokens: #{result.total_tokens}"
+    puts "  Agents involved: #{result.agents_involved.join(", ")}"
+  else
+    puts "❌ Swarm execution failed!"
+    puts "Error: #{result.error.message}"
+    puts result.error.backtrace.first(5).join("\n")
+  end
+end

data/lib/claude_swarm/configuration.rb

@@ -69,19 +69,43 @@ module ClaudeSwarm
       validate_directories unless has_before_commands?
     end
 
-    def interpolate_env_vars!(obj)
+    def interpolate_env_vars!(obj, path = [])
       case obj
       when String
-        interpolate_env_string(obj)
+        # Skip interpolation for any values inside MCP configurations
+        # Check if we're inside an mcps array element (path like: [..., "instances", <name>, "mcps", <index>, ...])
+        if in_mcp_config?(path)
+          obj
+        else
+          interpolate_env_string(obj)
+        end
       when Hash
-        obj.transform_values! { |v| interpolate_env_vars!(v) }
+        obj.each do |key, value|
+          obj[key] = interpolate_env_vars!(value, path + [key])
+        end
+        obj
       when Array
-        obj.map! { |v| interpolate_env_vars!(v) }
+        obj.map!.with_index { |v, i| interpolate_env_vars!(v, path + [i]) }
       else
         obj
       end
     end
 
+    def in_mcp_config?(path)
+      # Check if we're inside an MCP configuration
+      # Pattern: [..., "instances", instance_name, "mcps", index, ...]
+      return false if path.size < 4
+
+      # Find the position of "mcps" in the path
+      mcps_index = path.rindex("mcps")
+      return false unless mcps_index
+
+      # Check if this is under instances and followed by an array index
+      return false if mcps_index < 2
+
+      path[mcps_index - 2] == "instances" && path[mcps_index + 1].is_a?(Integer)
+    end
+
     def interpolate_env_string(str)
       str.gsub(ENV_VAR_WITH_DEFAULT_PATTERN) do |_match|
         env_var = Regexp.last_match(1)

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "1.0.6"
+  VERSION = "1.0.7"
 end

data/lib/swarm_cli/formatters/human_formatter.rb

@@ -95,11 +95,20 @@ module SwarmCLI
           handle_breakpoint_enter(entry)
         when "breakpoint_exit"
           handle_breakpoint_exit(entry)
+        when "llm_retry_attempt"
+          handle_llm_retry_attempt(entry)
+        when "llm_retry_exhausted"
+          handle_llm_retry_exhausted(entry)
+        when "response_parse_error"
+          handle_response_parse_error(entry)
         end
       end
 
       # Called when swarm execution completes successfully
       def on_success(result:)
+        # Defensive: ensure all spinners are stopped before showing result
+        @spinner_manager.stop_all
+
         if @mode == :non_interactive
           # Full result display with summary
           @output.puts
@@ -115,6 +124,9 @@ module SwarmCLI
 
       # Called when swarm execution fails
       def on_error(error:, duration: nil)
+        # Defensive: ensure all spinners are stopped before showing error
+        @spinner_manager.stop_all
+
         @output.puts
         @output.puts @divider.full
         print_error(error)
@@ -575,6 +587,97 @@ module SwarmCLI
         @output.puts
       end
 
+      def handle_llm_retry_attempt(entry)
+        agent = entry[:agent]
+        attempt = entry[:attempt]
+        max_retries = entry[:max_retries]
+        error_class = entry[:error_class]
+        error_message = entry[:error_message]
+        retry_delay = entry[:retry_delay]
+
+        # Stop agent thinking spinner (if active)
+        unless @quiet
+          spinner_key = "agent_#{agent}".to_sym
+          @spinner_manager.stop(spinner_key) if @spinner_manager.active?(spinner_key)
+        end
+
+        lines = [
+          @pastel.yellow("LLM API request failed (attempt #{attempt}/#{max_retries})"),
+          @pastel.dim("Error: #{error_class}: #{error_message}"),
+          @pastel.dim("Retrying in #{retry_delay}s..."),
+        ]
+
+        @output.puts @panel.render(
+          type: :warning,
+          title: "RETRY #{@agent_badge.render(agent)}",
+          lines: lines,
+          indent: @depth_tracker.get(agent),
+        )
+
+        # Restart spinner for next attempt
+        unless @quiet
+          spinner_key = "agent_#{agent}".to_sym
+          @spinner_manager.start(spinner_key, "#{agent} is retrying...")
+        end
+      end
+
+      def handle_llm_retry_exhausted(entry)
+        agent = entry[:agent]
+        attempts = entry[:attempts]
+        error_class = entry[:error_class]
+        error_message = entry[:error_message]
+
+        # Stop agent thinking spinner (if active)
+        unless @quiet
+          spinner_key = "agent_#{agent}".to_sym
+          @spinner_manager.stop(spinner_key) if @spinner_manager.active?(spinner_key)
+        end
+
+        lines = [
+          @pastel.red("LLM API request failed after #{attempts} attempts"),
+          @pastel.dim("Error: #{error_class}: #{error_message}"),
+          @pastel.dim("No more retries available"),
+        ]
+
+        @output.puts @panel.render(
+          type: :error,
+          title: "RETRY EXHAUSTED #{@agent_badge.render(agent)}",
+          lines: lines,
+          indent: @depth_tracker.get(agent),
+        )
+      end
+
+      def handle_response_parse_error(entry)
+        agent = entry[:agent]
+        error_class = entry[:error_class]
+        error_message = entry[:error_message]
+
+        # Stop agent thinking spinner (if active)
+        unless @quiet
+          spinner_key = "agent_#{agent}".to_sym
+          @spinner_manager.stop(spinner_key) if @spinner_manager.active?(spinner_key)
+        end
+
+        lines = [
+          @pastel.red("Failed to parse LLM API response"),
+          @pastel.dim("Error: #{error_class}: #{error_message}"),
+        ]
+
+        # Add response body preview if available (truncated)
+        if entry[:response_body]
+          body_preview = entry[:response_body].to_s[0..200]
+          body_preview += "..." if entry[:response_body].to_s.length > 200
+          lines << @pastel.dim("Response: #{body_preview}")
+        end
+
+        @output.puts @panel.render(
+          type: :error,
+          title: "PARSE ERROR #{@agent_badge.render(agent)}",
+          lines: lines,
+          indent: @depth_tracker.get(agent),
+        )
+      end
+
       def display_todo_list(agent, timestamp)
         todos = SwarmSDK::Tools::Stores::TodoManager.get_todos(agent.to_sym)
         indent = @depth_tracker.indent(agent)

data/lib/swarm_cli/interactive_repl.rb

@@ -81,6 +81,9 @@ module SwarmCLI
       display_session_summary
       exit(130)
     ensure
+      # Defensive: ensure all spinners are stopped on exit
+      @formatter&.spinner_manager&.stop_all
+
       # Save history on exit
       save_persistent_history
     end
@@ -432,11 +435,12 @@ module SwarmCLI
         end
       end
 
+      # CRITICAL: Stop all spinners after execution completes
+      # This ensures spinner doesn't interfere with error/success display or REPL prompt
+      @formatter.spinner_manager.stop_all
+
       # Handle cancellation (result is nil when cancelled)
       if result.nil?
-        # Stop all active spinners
-        @formatter.spinner_manager.stop_all
-
         puts ""
         puts @colors[:warning].call("✗ Request cancelled by user")
         puts ""
@@ -459,6 +463,8 @@ module SwarmCLI
       # Add response to history
       @conversation_history << { role: "agent", content: result.content }
     rescue StandardError => e
+      # Defensive: ensure spinners are stopped on exception
+      @formatter.spinner_manager.stop_all
       @formatter.on_error(error: e)
     end
 

data/lib/swarm_cli/version.rb

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

data/lib/swarm_memory/core/storage_read_tracker.rb

@@ -2,40 +2,77 @@
 
 module SwarmMemory
   module Core
-    # StorageReadTracker manages read-entry tracking for all agents
+    # StorageReadTracker manages read-entry tracking for all agents with content digest verification
     #
     # This module maintains a global registry of which memory entries each agent
-    # has read during their conversation. This enables enforcement of the
-    # "read-before-edit" rule that ensures agents have context before modifying entries.
+    # has read during their conversation along with SHA256 digests of the content.
+    # This enables enforcement of the "read-before-edit" rule that ensures agents
+    # have context before modifying entries, AND prevents editing entries that have
+    # changed externally since being read.
     #
-    # Each agent maintains an independent set of read entries, keyed by agent identifier.
+    # Each agent maintains an independent map of read entries to content digests.
     module StorageReadTracker
-      @read_entries = {}
+      @read_entries = {} # { agent_id => { entry_path => sha256_digest } }
       @mutex = Mutex.new
 
       class << self
-        # Register that an agent has read a storage entry
+        # Register that an agent has read a storage entry with content digest
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [void]
-        def register_read(agent_id, entry_path)
+        # @param content [String] Entry content (for digest calculation)
+        # @return [String] The calculated SHA256 digest
+        def register_read(agent_id, entry_path, content)
           @mutex.synchronize do
-            @read_entries[agent_id] ||= Set.new
-            @read_entries[agent_id] << entry_path
+            @read_entries[agent_id] ||= {}
+            digest = Digest::SHA256.hexdigest(content)
+            @read_entries[agent_id][entry_path] = digest
+            digest
           end
         end
 
-        # Check if an agent has read a storage entry
+        # Check if an agent has read an entry AND content hasn't changed
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [Boolean] true if the agent has read this entry
-        def entry_read?(agent_id, entry_path)
+        # @param storage [Storage] Storage instance to read current content
+        # @return [Boolean] true if agent read entry and content matches
+        def entry_read?(agent_id, entry_path, storage)
           @mutex.synchronize do
             return false unless @read_entries[agent_id]
 
-            @read_entries[agent_id].include?(entry_path)
+            stored_digest = @read_entries[agent_id][entry_path]
+            return false unless stored_digest
+
+            # Check if entry still matches stored digest
+            begin
+              current_content = storage.read(file_path: entry_path)
+              current_digest = Digest::SHA256.hexdigest(current_content)
+              current_digest == stored_digest
+            rescue StandardError
+              false # Entry deleted or inaccessible
+            end
+          end
+        end
+
+        # Get all read entries with digests for snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @return [Hash] { entry_path => digest }
+        def get_read_entries(agent_id)
+          @mutex.synchronize do
+            @read_entries[agent_id]&.dup || {}
+          end
+        end
+
+        # Restore read entries with digests from snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @param entries_with_digests [Hash] { entry_path => digest }
+        # @return [void]
+        def restore_read_entries(agent_id, entries_with_digests)
+          @mutex.synchronize do
+            @read_entries[agent_id] = entries_with_digests.dup
           end
         end
 

data/lib/swarm_memory/integration/cli_registration.rb

@@ -13,8 +13,9 @@ module SwarmMemory
         #
         # @return [void]
         def register!
-          # Only register if SwarmCLI is present
-          return unless defined?(SwarmCLI)
+          # Only register if SwarmCLI::CommandRegistry is available
+          # Check for the specific class, not just the module
+          return unless defined?(SwarmCLI::CommandRegistry)
 
           # Load CLI commands explicitly (Zeitwerk might not have loaded it yet)
           require_relative "../cli/commands"

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -250,9 +250,12 @@ module SwarmMemory
           :interactive # Default
         end
 
-        # Store storage and mode for this agent
-        @storages[agent_name] = storage
-        @modes[agent_name] = mode
+        # V7.0: Extract base name for storage tracking (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+
+        # Store storage and mode using BASE NAME
+        @storages[base_name] = storage # ← Changed from agent_name to base_name
+        @modes[base_name] = mode # ← Changed from agent_name to base_name
 
         # Get mode-specific tools
         allowed_tools = tools_for_mode(mode)
@@ -298,9 +301,12 @@ module SwarmMemory
       # @param is_first_message [Boolean] True if first message
       # @return [Array<String>] System reminders (0-2 reminders)
       def on_user_message(agent_name:, prompt:, is_first_message:)
-        storage = @storages[agent_name]
+        # V7.0: Extract base name for storage lookup (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+        storage = @storages[base_name] # ← Changed from agent_name to base_name
+
         return [] unless storage&.semantic_index
-        return [] if prompt.empty?
+        return [] if prompt.nil? || prompt.empty?
 
         # Adaptive threshold based on query length
         # Short queries use lower threshold as they have less semantic richness

data/lib/swarm_memory/tools/memory_edit.rb

@@ -124,8 +124,8 @@ module SwarmMemory
         # Read current content (this will raise ArgumentError if entry doesn't exist)
         content = @storage.read(file_path: file_path)
 
-        # Enforce read-before-edit
-        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+        # Enforce read-before-edit with content verification
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path, @storage)
           return validation_error(
             "Cannot edit memory entry without reading it first. " \
               "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \