claude_swarm 1.0.6 → 1.0.7

data/lib/swarm_sdk/validation_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Internal result object for validation phase during snapshot restore
+  #
+  # Used during restore to track which agents can be restored and which
+  # need to be skipped due to configuration mismatches.
+  #
+  # @api private
+  class ValidationResult
+    attr_reader :warnings,
+      :skipped_agents,
+      :restorable_agents,
+      :skipped_delegations,
+      :restorable_delegations
+
+    # Initialize validation result
+    #
+    # @param warnings [Array<Hash>] Warning messages with details
+    # @param skipped_agents [Array<Symbol>] Names of agents that can't be restored
+    # @param restorable_agents [Array<Symbol>] Names of agents that can be restored
+    # @param skipped_delegations [Array<String>] Names of delegations that can't be restored
+    # @param restorable_delegations [Array<String>] Names of delegations that can be restored
+    def initialize(warnings:, skipped_agents:, restorable_agents:,
+      skipped_delegations:, restorable_delegations:)
+      @warnings = warnings
+      @skipped_agents = skipped_agents
+      @restorable_agents = restorable_agents
+      @skipped_delegations = skipped_delegations
+      @restorable_delegations = restorable_delegations
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -15,6 +15,7 @@ require "yaml"
 require "async"
 require "async/semaphore"
 require "ruby_llm"
+require "ruby_llm/mcp"
 
 require_relative "swarm_sdk/version"
 
@@ -25,6 +26,8 @@ loader.push_dir("#{__dir__}/swarm_sdk", namespace: SwarmSDK)
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
+  "llm_instrumentation_middleware" => "LLMInstrumentationMiddleware",
+  "mcp" => "MCP",
   "openai_with_responses" => "OpenAIWithResponses",
 )
 loader.setup
@@ -43,8 +46,8 @@ module SwarmSDK
     attr_accessor :settings
 
     # Main entry point for DSL
-    def build(&block)
-      Swarm::Builder.build(&block)
+    def build(allow_filesystem_tools: nil, &block)
+      Swarm::Builder.build(allow_filesystem_tools: allow_filesystem_tools, &block)
     end
 
     # Validate YAML configuration without creating a swarm
@@ -84,6 +87,10 @@ module SwarmSDK
       begin
         config = Configuration.new(yaml_content, base_dir: base_dir)
         config.load_and_validate
+
+        # Build swarm to trigger DSL validation
+        # This catches errors from Agent::Definition, Builder, etc.
+        config.to_swarm
       rescue ConfigurationError, CircularDependencyError => e
         errors << parse_configuration_error(e)
       rescue StandardError => e
@@ -164,10 +171,10 @@ module SwarmSDK
     # @example Load with default base_dir (Dir.pwd)
     #   yaml = File.read("config.yml")
     #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
-    def load(yaml_content, base_dir: Dir.pwd)
+    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil)
       config = Configuration.new(yaml_content, base_dir: base_dir)
       config.load_and_validate
-      swarm = config.to_swarm
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
       # Apply hooks if any are configured (YAML-only feature)
       if hooks_configured?(config)
@@ -196,9 +203,9 @@ module SwarmSDK
     #
     # @example With absolute path
     #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
-    def load_file(path)
+    def load_file(path, allow_filesystem_tools: nil)
       config = Configuration.load_file(path)
-      swarm = config.to_swarm
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
       # Apply hooks if any are configured (YAML-only feature)
       if hooks_configured?(config)
@@ -235,7 +242,7 @@ module SwarmSDK
     def hooks_configured?(config)
       config.swarm_hooks.any? ||
         config.all_agents_hooks.any? ||
-        config.agents.any? { |_, agent_def| agent_def.hooks&.any? }
+        config.agents.any? { |_, agent_config| agent_config[:hooks]&.any? }
     end
 
     # Parse configuration error and extract structured information
@@ -323,7 +330,7 @@ module SwarmSDK
           field: "swarm.lead",
         )
 
-      # Unknown agent in connections
+      # Unknown agent in connections (old format)
       when /Agent '([^']+)' has connection to unknown agent '([^']+)'/i
         agent_name = Regexp.last_match(1)
         error_hash.merge!(
@@ -332,6 +339,15 @@ module SwarmSDK
           agent: agent_name,
         )
 
+      # Unknown agent in connections (new format with composable swarms)
+      when /Agent '([^']+)' delegates to unknown target '([^']+)'/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.agents.#{agent_name}.delegates_to",
+          agent: agent_name,
+        )
+
       # Circular dependency
       when /Circular dependency detected/i
         error_hash.merge!(
@@ -397,17 +413,33 @@ module SwarmSDK
     # WebFetch tool LLM processing configuration
     attr_accessor :webfetch_provider, :webfetch_model, :webfetch_base_url, :webfetch_max_tokens
 
+    # Filesystem tools control
+    attr_accessor :allow_filesystem_tools
+
     def initialize
       @webfetch_provider = nil
       @webfetch_model = nil
       @webfetch_base_url = nil
       @webfetch_max_tokens = 4096
+      @allow_filesystem_tools = parse_env_bool("SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", default: true)
     end
 
     # Check if WebFetch LLM processing is enabled
     def webfetch_llm_enabled?
       !@webfetch_provider.nil? && !@webfetch_model.nil?
     end
+
+    private
+
+    def parse_env_bool(key, default:)
+      return default unless ENV.key?(key)
+
+      value = ENV[key].to_s.downcase
+      return true if ["true", "yes", "1", "on", "enabled"].include?(value)
+      return false if ["false", "no", "0", "off", "disabled"].include?(value)
+
+      default
+    end
   end
 
   # Initialize default settings

data/swarm_cli.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency("fast-mcp", "~> 1.6")
   spec.add_dependency("pastel")
-  spec.add_dependency("swarm_sdk", "~> 2.1")
+  spec.add_dependency("swarm_sdk", "~> 2.2")
   spec.add_dependency("tty-box")
   spec.add_dependency("tty-cursor")
   spec.add_dependency("tty-link")

data/swarm_memory.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency("async", "~> 2.0")
   spec.add_dependency("informers", "~> 1.2.1")
   spec.add_dependency("rice", "~> 4.6.0")
-  spec.add_dependency("ruby_llm", "~> 1.8")
-  spec.add_dependency("swarm_sdk", "~> 2.1")
+  spec.add_dependency("ruby_llm", "~> 1.9")
+  spec.add_dependency("swarm_sdk", "~> 2.2")
   spec.add_dependency("zeitwerk", "~> 2.6")
 end

data/swarm_sdk.gemspec

@@ -35,7 +35,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency("async", "~> 2.0")
-  spec.add_dependency("ruby_llm", "~> 1.8")
-  spec.add_dependency("ruby_llm-mcp", "~> 0.6.3")
+  spec.add_dependency("ruby_llm", "~> 1.9")
+  spec.add_dependency("ruby_llm-mcp", "~> 0.7")
   spec.add_dependency("zeitwerk", "~> 2.6")
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.7
 platform: ruby
 authors:
 - Paulo Arruda
@@ -155,18 +155,22 @@ files:
 - analyze_coverage.rb
 - claude-sdk-docs.md
 - docs-team-swarm.yml
+- docs/V1_TO_V2_MIGRATION_GUIDE.md
+- docs/v1/README.md
 - docs/v2/CHANGELOG.swarm_cli.md
 - docs/v2/CHANGELOG.swarm_memory.md
 - docs/v2/CHANGELOG.swarm_sdk.md
 - docs/v2/README.md
-- docs/v2/guides/MEMORY_DEFRAG_GUIDE.md
 - docs/v2/guides/claude-code-agents.md
 - docs/v2/guides/complete-tutorial.md
+- docs/v2/guides/composable-swarms.md
 - docs/v2/guides/getting-started.md
 - docs/v2/guides/memory-adapters.md
+- docs/v2/guides/memory-defrag-guide.md
 - docs/v2/guides/plugins.md
 - docs/v2/guides/quick-start-cli.md
 - docs/v2/guides/rails-integration.md
+- docs/v2/guides/snapshots.md
 - docs/v2/guides/swarm-memory.md
 - docs/v2/reference/architecture-flow.md
 - docs/v2/reference/cli.md
@@ -176,20 +180,13 @@ files:
 - docs/v2/reference/swarm_memory_technical_details.md
 - docs/v2/reference/yaml.md
 - examples/claude-swarm.yml
-- examples/learning-assistant/assistant.md
-- examples/learning-assistant/example-memories/concept-example.md
-- examples/learning-assistant/example-memories/experience-example.md
-- examples/learning-assistant/example-memories/fact-example.md
-- examples/learning-assistant/example-memories/memory-index.md
-- examples/learning-assistant/example-memories/skill-example.md
-- examples/learning-assistant/learning_assistant.rb
-- examples/learning-assistant/learning_assistant.yml
 - examples/microservices-team.yml
 - examples/mixed-provider-swarm.yml
 - examples/monitoring-demo.yml
 - examples/multi-directory.yml
 - examples/session-restoration-demo.yml
 - examples/simple-session-hook-swarm.yml
+- examples/snapshot_demo.rb
 - examples/test-generation.yml
 - examples/v2/dsl/01_basic.rb
 - examples/v2/dsl/02_core_parameters.rb
@@ -235,6 +232,7 @@ files:
 - examples/v2/node_context_demo.rb
 - examples/v2/node_workflow.rb
 - examples/v2/path_resolution_demo.rb
+- examples/v2/plan_and_execute.rb
 - examples/v2/simple-swarm-v2.rb
 - examples/v2/simple-swarm-v2.yml
 - examples/v2/swarm.yml
@@ -357,11 +355,13 @@ files:
 - lib/swarm_sdk/agent/context.rb
 - lib/swarm_sdk/agent/context_manager.rb
 - lib/swarm_sdk/agent/definition.rb
+- lib/swarm_sdk/agent/llm_instrumentation_middleware.rb
 - lib/swarm_sdk/claude_code_agent_adapter.rb
 - lib/swarm_sdk/configuration.rb
 - lib/swarm_sdk/context_compactor.rb
 - lib/swarm_sdk/context_compactor/metrics.rb
 - lib/swarm_sdk/context_compactor/token_counter.rb
+- lib/swarm_sdk/events_to_messages.rb
 - lib/swarm_sdk/hooks/adapter.rb
 - lib/swarm_sdk/hooks/context.rb
 - lib/swarm_sdk/hooks/definition.rb
@@ -375,7 +375,6 @@ files:
 - lib/swarm_sdk/log_collector.rb
 - lib/swarm_sdk/log_stream.rb
 - lib/swarm_sdk/markdown_parser.rb
-- lib/swarm_sdk/mcp.rb
 - lib/swarm_sdk/model_aliases.json
 - lib/swarm_sdk/models.json
 - lib/swarm_sdk/models.rb
@@ -391,15 +390,24 @@ files:
 - lib/swarm_sdk/permissions_builder.rb
 - lib/swarm_sdk/plugin.rb
 - lib/swarm_sdk/plugin_registry.rb
+- lib/swarm_sdk/proc_helpers.rb
 - lib/swarm_sdk/prompts/base_system_prompt.md.erb
 - lib/swarm_sdk/providers/openai_with_responses.rb
+- lib/swarm_sdk/restore_result.rb
 - lib/swarm_sdk/result.rb
+- lib/swarm_sdk/snapshot.rb
+- lib/swarm_sdk/snapshot_from_events.rb
+- lib/swarm_sdk/state_restorer.rb
+- lib/swarm_sdk/state_snapshot.rb
 - lib/swarm_sdk/swarm.rb
 - lib/swarm_sdk/swarm/agent_initializer.rb
 - lib/swarm_sdk/swarm/all_agents_builder.rb
 - lib/swarm_sdk/swarm/builder.rb
 - lib/swarm_sdk/swarm/mcp_configurator.rb
+- lib/swarm_sdk/swarm/swarm_registry_builder.rb
 - lib/swarm_sdk/swarm/tool_configurator.rb
+- lib/swarm_sdk/swarm_loader.rb
+- lib/swarm_sdk/swarm_registry.rb
 - lib/swarm_sdk/tools/bash.rb
 - lib/swarm_sdk/tools/clock.rb
 - lib/swarm_sdk/tools/delegate.rb
@@ -430,9 +438,9 @@ files:
 - lib/swarm_sdk/tools/web_fetch.rb
 - lib/swarm_sdk/tools/write.rb
 - lib/swarm_sdk/utils.rb
+- lib/swarm_sdk/validation_result.rb
 - lib/swarm_sdk/version.rb
-- llm.v2.txt
-- llms.txt
+- llms.claude-swarm.txt
 - rubocop/cop/security/no_reflection_methods.rb
 - rubocop/cop/security/no_ruby_llm_logger.rb
 - single.yml

data/examples/learning-assistant/assistant.md

@@ -1,7 +0,0 @@
----
-name: assistant
-description: An assistant that learns and builds knowledge over time
-model: sonnet
----
-
-You are an assistant.

data/examples/learning-assistant/example-memories/concept-example.md

@@ -1,90 +0,0 @@
----
-type: concept
-domain: programming/ruby
-confidence: high
-last_verified: 2025-01-15
-tags: [ruby, classes, oop, inheritance, objects]
-related:
-  - memory://memory/concepts/programming/ruby/modules.md
-  - memory://memory/concepts/programming/oop/inheritance.md
-  - memory://memory/skills/programming/ruby/create-class.md
-source: documentation
----
-
-# Ruby Classes
-
-## Definition
-
-Classes are blueprints for creating objects in Ruby. They define both the structure (instance variables) and behavior (methods) that objects created from the class will have.
-
-## Core Syntax
-
-```ruby
-class Person
-  # Constructor
-  def initialize(name, age)
-    @name = name  # Instance variable
-    @age = age
-  end
-
-  # Instance method
-  def introduce
-    "Hi, I'm #{@name} and I'm #{@age} years old"
-  end
-
-  # Class method
-  def self.species
-    "Homo sapiens"
-  end
-end
-
-# Usage
-person = Person.new("Alice", 30)
-person.introduce           # => "Hi, I'm Alice and I'm 30 years old"
-Person.species            # => "Homo sapiens"
-```
-
-## Key Characteristics
-
-1. **Instantiation**: Create objects with `.new`
-2. **Instance variables**: Start with `@`, unique per instance
-3. **Instance methods**: Define object behavior
-4. **Class methods**: Shared across all instances (use `self.`)
-5. **Inheritance**: Single inheritance with `<`
-6. **Visibility**: public (default), private, protected
-
-## Inheritance
-
-```ruby
-class Employee < Person
-  def initialize(name, age, role)
-    super(name, age)  # Call parent constructor
-    @role = role
-  end
-
-  def introduce
-    super + " and I work as a #{@role}"
-  end
-end
-```
-
-## When to Use
-
-- Modeling real-world entities (User, Product, Order)
-- Need multiple instances with shared behavior
-- Building reusable, stateful components
-- Implementing object-oriented patterns
-
-## Relationships
-
-- **Similar to**: Modules (but modules can't be instantiated)
-- **Part of**: Object-Oriented Programming paradigm
-- **Used with**: Inheritance, Mixins, Composition
-- **Differs from**: Structs (simpler, less flexible)
-
-## Common Patterns
-
-1. **Encapsulation**: Hide internal state with private methods
-2. **Delegation**: Forward calls to composed objects
-3. **Factory pattern**: Class methods that return instances
-4. **Template method**: Parent class defines structure, children implement details

data/examples/learning-assistant/example-memories/experience-example.md

@@ -1,66 +0,0 @@
----
-type: experience
-category: success
-domain: swarm/memory
-date: 2025-01-15
-tags: [learning, first-success, memory-system, milestone]
-related:
-  - memory://memory/skills/swarm/scratchpad-write.md
-  - memory://memory/concepts/swarm/scratchpad-system.md
-source: experimentation
----
-
-# First Successful Memory Write
-
-## Context
-
-This was my first attempt at using the memory system. I needed to store knowledge about how to use the MemoryWrite tool.
-
-## What I Did
-
-1. Chose appropriate path: `memory/skills/swarm/scratchpad-write.md`
-2. Created YAML frontmatter with all required fields
-3. Wrote structured markdown with examples
-4. Successfully stored the entry
-5. Verified by reading it back with MemoryRead
-
-## Challenges Faced
-
-- Initially unsure about path structure (should it be `skills/swarm/` or `swarm/skills/`)
-- Wasn't sure how detailed the frontmatter should be
-- Questioned whether to use `.md` extension
-
-## What Worked
-
-- Following the memory schema from system prompt
-- Using kebab-case for paths
-- Including concrete examples in the content
-- Marking confidence honestly (medium at first)
-
-## Outcome
-
-Successfully created my first memory entry. I can now read it back and use it as a template for future entries.
-
-## Lesson Learned
-
-**Key insight**: The memory system works best when you:
-1. Follow the schema strictly (don't improvise paths)
-2. Write immediately after learning (don't batch)
-3. Include rich frontmatter (makes searching easier)
-4. Use examples (makes recall more useful)
-
-## Apply This Pattern When
-
-- Starting to use any new tool or system
-- Building a new skill
-- Need to remember a process
-- Want to capture a lesson learned
-
-## Evolution
-
-This entry will serve as a template and reminder for how to use the memory system effectively. As I gain more experience, I'll update it with additional insights.
-
-## Confidence Growth
-
-- **Day 1** (2025-01-15): confidence: medium - First attempt, learning
-- **Future**: Will increase to high after 5+ successful uses

data/examples/learning-assistant/example-memories/fact-example.md

@@ -1,76 +0,0 @@
----
-type: fact
-domain: people
-confidence: high
-last_verified: 2025-01-15
-tags: [user, paulo, preferences, communication]
-source: user
----
-
-# User: Paulo
-
-## Role & Context
-
-- **Primary user** and project owner
-- **Working on**: SwarmSDK and SwarmCLI Ruby gems
-- **Project location**: `/Users/paulo/src/github.com/parruda/claude-swarm`
-- **Platform**: macOS (Darwin 24.6.0)
-- **Ruby version**: 3.4.2
-
-## Communication Preferences
-
-### Style
-- Prefers **direct, concise** communication
-- Values **professional, clean** code
-- Appreciates **thorough explanations** when asked
-- Likes when I explain my reasoning
-
-### Expectations
-- **Production-ready** implementations (not prototypes)
-- **Comprehensive testing** (all tests must pass)
-- **Clean code** (RuboCop compliance)
-- **Proper documentation** (accurate, current)
-
-### Work Style
-- Asks **clarifying questions** when unsure
-- Provides **specific feedback** on implementations
-- Iterates quickly - makes decisions and moves forward
-- Values **best practices** and **maintainability**
-
-## Project Context
-
-### SwarmSDK
-- Building next-generation multi-agent orchestration framework
-- Focuses on single-process execution using RubyLLM
-- Clean separation between SDK (lib/swarm_sdk/) and CLI (lib/swarm_cli/)
-- Strong emphasis on testing and code quality
-
-### Development Practices
-- Uses Zeitwerk for autoloading
-- Follows Ruby/RuboCop conventions
-- Comprehensive test coverage required
-- Documentation must reflect code reality (no "New!" announcements)
-
-## How to Work with Paulo
-
-1. **Be direct** - No fluff, get to the point
-2. **Be thorough** - Complete implementations, not partial
-3. **Ask when unsure** - Don't guess architectural decisions
-4. **Test everything** - All tests must pass before completion
-5. **Document accurately** - Docs describe current state, not history
-
-## Things Paulo Cares About
-
-- **Separation of concerns** - SDK vs CLI code must never mix
-- **Professional code quality** - This is open source, must look great
-- **No slop** - No methods that exist only for tests
-- **Proper delegation** - Consult experts via MCP tools
-- **Breaking changes** - Be explicit about them
-
-## Things to Avoid
-
-- Creating unnecessary files (especially markdown/README files proactively)
-- Using emojis unless explicitly requested
-- Making assumptions about architecture without asking
-- Mixing SDK and CLI code
-- Incomplete implementations

data/examples/learning-assistant/example-memories/memory-index.md

@@ -1,78 +0,0 @@
----
-type: index
-last_updated: 2025-01-15
-total_entries: 8
----
-
-# Memory Index
-
-My current knowledge base as of 2025-01-15.
-
-## Quick Stats
-- **Concepts**: 2
-- **Facts**: 3
-- **Skills**: 2
-- **Experiences**: 1
-
-## Expertise Areas
-
-### Strong (5+ entries)
-- Ruby programming (3 concepts + 2 skills)
-
-### Developing (2-4 entries)
-- User context (3 facts)
-
-### Learning (1 entry)
-- Testing practices (1 experience)
-
-## Recent Activity (Last 7 Days)
-
-- **2025-01-15**: Learned Minitest testing → skills/programming/ruby/minitest-testing.md
-- **2025-01-15**: Understood user preferences → facts/people/paulo.md
-- **2025-01-15**: Discovered project structure → facts/environment/project-structure.md
-- **2025-01-14**: Learned about Ruby classes → concepts/programming/ruby/classes.md
-- **2025-01-14**: Mastered MemoryWrite → skills/swarm/scratchpad-write.md
-
-## Knowledge Gaps (To Explore)
-
-Questions I need to answer:
-- How does the SwarmSDK delegation system work?
-- What are the best practices for organizing large memory hierarchies?
-- How should I handle conflicting information from different sources?
-
-## Category Breakdown
-
-### Concepts
-- `concepts/programming/ruby/` (2 entries)
-  - classes.md
-  - modules.md
-
-### Facts
-- `facts/people/` (1 entry)
-  - paulo.md
-- `facts/environment/` (2 entries)
-  - project-structure.md
-  - preferences.md
-
-### Skills
-- `skills/programming/ruby/` (1 entry)
-  - minitest-testing.md
-- `skills/swarm/` (1 entry)
-  - scratchpad-write.md
-
-### Experience
-- `experience/successes/` (1 entry)
-  - 2025-01-15-first-memory-write.md
-
-## Memory Health
-
-- **Total Size**: ~50KB / 100MB (0.05% used)
-- **Organization**: Good - clear hierarchy
-- **Cross-references**: 8 links across entries
-- **Confidence Distribution**: High: 6, Medium: 2, Low: 0
-
-## Next Session Goals
-
-1. Learn more about the SwarmSDK agent system
-2. Build skills in file operations (Read, Write, Edit)
-3. Understand the user's current project goals