claude_swarm 1.0.4 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a52559fb6574ce20ff8c8f2582a8657475a359f2ee8fcbb07cb9594abfb236d
-  data.tar.gz: 784bb012843d17c605626ea43edfc6460e0c5229db08d89d8e324d2f7cc6f60d
+  metadata.gz: 0642e42ada976e14c7859fcee3a49563f629813dd5b11bac10e491893fb5f970
+  data.tar.gz: 2a6658b5940ca39bea71d992e50c1e42b4abd95c25e8f72388e49c0f2e6021fa
 SHA512:
-  metadata.gz: 96b0037178cdb76a8c5c6d0bfefbbe51261ec5904502e63ae0313338c59b3b580cf8c9a78f86c6c2fd73864e9d259300b79d64b917a55d87ddbc3c2513cecdc8
-  data.tar.gz: 32e006014e9856d1a6c0822bf3c6b713035722e6241de91d8e89282251c16ae9479c1bcb930b11781a73babc0c468892eca44e434117e92c582a1ba5b14f123a
+  metadata.gz: 1478b5345bea76c1c6de67b5a025736b90db1db14b2432ba0f4bf6634d1668e41f4226823a3dfac4049b40987001fd629e782c9b175bb63e1d6002a189a3a3f7
+  data.tar.gz: 44224e8eaf81a0a29f230c137f347da7c6115b1d9854ca2b4396e5bf3c38cf9a51f782a1321fe7a13fe2fb013f745ea20571c47767cb6e1b8f0dfb83384e87a7

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [1.0.6]
+
+### Fixed
+- **Fixed Ruby environment variable conflicts in MCP servers**: Removed RUBYOPT and RUBYLIB from MCP server configurations to prevent Bundler interference
+  - MCP servers no longer inherit RUBYOPT and RUBYLIB environment variables from the parent process
+  - Also removed BUNDLE_* environment variables to ensure MCP servers use the system-installed gem
+  - Prevents conflicts when Claude Swarm is run from within a bundled Ruby project
+  - Ensures MCP servers run with clean Ruby environments without unexpected gem loading behavior
+
+## [1.0.3]
+
+### Fixed
+- **Fixed uninitialized constant VERSION error**: Resolved an issue where the VERSION constant was not properly initialized in the Zeitwerk autoloader setup
+  - The gem version is now correctly loaded before Zeitwerk setup
+  - Prevents "uninitialized constant ClaudeSwarm::VERSION" errors during gem loading
+  - Ensures version information is available throughout the application
+
+### Changed
+- **Process spawning now uses chdir option**: Replaced `Dir.chdir` blocks with the `chdir:` option when spawning processes
+  - Commands are now executed with explicit working directory using `Open3.capture2e`, `Open3.popen2e`, and `system` with `chdir:` parameter
+  - Avoids changing the process's working directory which could cause issues in concurrent operations
+  - More explicit and safer approach for executing commands in specific directories
+  - Removed `CLAUDE_SWARM_ROOT_DIR` environment variable in favor of passing root directory explicitly
+
 ## [1.0.2]
 
 ### Changed

data/Rakefile

@@ -14,8 +14,8 @@ namespace :claude_swarm do
     # Expand globs and subtract to get only claude_swarm tests
     all_tests = Dir.glob("test/**/*_test.rb")
     exclude_tests = Dir.glob("test/swarm_sdk/**/*_test.rb") +
-                    Dir.glob("test/swarm_memory/**/*_test.rb") +
-                    Dir.glob("test/swarm_cli/**/*_test.rb")
+      Dir.glob("test/swarm_memory/**/*_test.rb") +
+      Dir.glob("test/swarm_cli/**/*_test.rb")
     t.test_globs = all_tests - exclude_tests
     t.warning = false
   end
@@ -24,8 +24,8 @@ namespace :claude_swarm do
     # Expand patterns and subtract
     all_patterns = Dir.glob("lib/claude_swarm.rb") + Dir.glob("lib/claude_swarm/**/*.rb") + Dir.glob("test/**/*_test.rb")
     exclude_patterns = Dir.glob("test/swarm_sdk/**/*.rb") +
-                       Dir.glob("test/swarm_memory/**/*.rb") +
-                       Dir.glob("test/swarm_cli/**/*.rb")
+      Dir.glob("test/swarm_memory/**/*.rb") +
+      Dir.glob("test/swarm_cli/**/*.rb")
     t.patterns = all_patterns - exclude_patterns
   end
 

data/docs/v2/CHANGELOG.swarm_cli.md

@@ -5,6 +5,25 @@ All notable changes to SwarmCLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.2]
+
+### Changed
+
+- **Internal: Updated to use new SwarmSDK loading API**
+  - `ConfigLoader` now uses `SwarmSDK.load_file` instead of `SwarmSDK::Swarm.load`
+  - `mcp serve` command updated to use `SwarmSDK.load_file`
+  - No user-facing changes - all CLI commands work identically
+  - Benefits from improved SDK separation (SDK handles strings, CLI handles files)
+
+## [2.1.1]
+
+### Fixed
+- **`swarm mcp tools` command initialization** - Fixed crash on startup
+  - Bug: Used non-existent `SwarmSDK::Scratchpad` class
+  - Fix: Changed to `SwarmSDK::Tools::Stores::ScratchpadStorage` (correct class)
+  - Added comprehensive test suite to prevent similar initialization bugs
+  - Tests verify command initializes without errors
+
 ## [2.1.0]
 - Bump gem version with the rest of the gems.
 

data/docs/v2/CHANGELOG.swarm_memory.md

@@ -5,6 +5,19 @@ All notable changes to SwarmMemory will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.2]
+
+### Changed
+- **Stub redirect logic moved to Storage layer** - Architectural improvement for adapter-agnostic redirects
+  - Redirect following moved from `FilesystemAdapter` to `Storage#read_entry`
+  - Uses metadata-based detection (`stub: true`, `redirect_to`) instead of content parsing
+  - All future adapters (PostgreSQL, Redis, S3) get redirect support for free
+  - Improved error handling with helpful diagnostic messages
+  - Detects circular redirects immediately with full cycle path
+  - Enforces depth limit (5 redirects) to prevent infinite chains
+  - Added comprehensive test suite with 10 tests covering all edge cases
+  - Added validation to `Defragmenter#create_stub` to prevent malformed stubs
+
 ## [2.1.1]
 
 ### Added
@@ -14,6 +27,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Helpful error message guides users to split large content into multiple linked memories
   - Promotes better organization through multiple focused entries with `related` field links
 
+- **MemoryGlob result truncation**: Prevents overwhelming output from broad searches
+  - Maximum 1000 results per query (matches Glob tool behavior)
+  - System reminder added when results are truncated
+  - Encourages users to use more specific patterns
+  - Sorted by most recently modified (first 1000 shown)
+
 ### Changed
 - **Memory Assistant prompt improvements**: Updated examples and guidance
   - Updated examples from 5000-word to 250-word entries

data/docs/v2/CHANGELOG.swarm_sdk.md

@@ -5,6 +5,98 @@ All notable changes to SwarmSDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.2]
+
+### Added
+
+- **Validation API**: New methods to validate YAML configurations without creating swarms
+  - `SwarmSDK.validate(yaml_content, base_dir:)` - Validate YAML string and return structured errors
+  - `SwarmSDK.validate_file(path)` - Validate YAML file (convenience method)
+  - Returns array of error hashes with type, field path, message, and optional agent name
+  - Error types: `:syntax_error`, `:missing_field`, `:invalid_value`, `:invalid_reference`, `:directory_not_found`, `:file_not_found`, `:file_load_error`, `:circular_dependency`, `:validation_error`, `:unknown_error`
+  - Field paths use JSON-style notation: `"swarm.agents.backend.description"`
+  - Enables pre-flight validation for UIs, tools, and programmatic usage
+  - Comprehensive test coverage with 19 tests covering all error scenarios
+
+- **String-based Configuration Loading**: Load YAML from strings, not just files
+  - `SwarmSDK.load(yaml_content, base_dir:)` - Load swarm from YAML string (primary API)
+  - `SwarmSDK.load_file(path)` - Load swarm from YAML file (convenience method)
+  - `base_dir` parameter for resolving agent file paths (defaults to `Dir.pwd`)
+  - Enables loading YAML from databases, APIs, environment variables, or any string source
+  - Cleaner separation: SDK works with strings, CLI handles file I/O
+
+### Changed
+
+- **BREAKING: Removed `Swarm.load` class method**
+  - Old: `swarm = SwarmSDK::Swarm.load("config.yml")`
+  - New: `swarm = SwarmSDK.load_file("config.yml")`
+  - Cleaner API: All creation methods now at module level (`SwarmSDK.build`, `SwarmSDK.load`, `SwarmSDK.load_file`)
+
+- **BREAKING: `Configuration` class refactored for string-based loading**
+  - Old: `Configuration.load(path)` → New: `Configuration.load_file(path)`
+  - Old: `Configuration.new(path)` → New: `Configuration.new(yaml_content, base_dir: Dir.pwd)`
+  - Removed `config_path` attribute (no longer stored)
+  - Internal: `@config_dir` renamed to `@base_dir`
+  - Core SDK now works with YAML strings, not file paths
+  - File I/O isolated to convenience methods (`load_file`)
+
+- **Agent file path resolution**: Paths resolved relative to `base_dir`
+  - When loading from file: `base_dir` = file's directory (unchanged behavior)
+  - When loading from string: `base_dir` = `Dir.pwd` (default) or explicit parameter
+  - Example: `agent_file: "agents/backend.md"` resolves to `#{base_dir}/agents/backend.md`
+
+### Fixed
+
+- **Configuration validation**: Better error messages with file context
+  - YAML syntax errors now include parser details
+  - File not found errors include absolute paths
+  - Agent file load errors include agent name and field path
+
+## [2.1.2]
+
+### Added
+
+- **Node Workflow Control Flow**: Dynamic control methods in NodeContext
+  - `ctx.goto_node(:node_name, content:)` - Jump to any node with custom content
+  - `ctx.halt_workflow(content:)` - Stop entire workflow and return final result
+  - `ctx.skip_execution(content:)` - Skip node LLM execution and use provided content
+  - Enables loops, conditional branching, and dynamic routing in workflows
+  - All methods validate that content is not nil (raises ArgumentError with helpful message if nil)
+  - Use for implementing retry logic, convergence checks, caching, and iterative refinement
+
+- **Context Preservation Across Nodes**: `reset_context` parameter for node agents
+  - `agent(:name, reset_context: false)` preserves conversation history across nodes
+  - Default: `reset_context: true` (fresh context for each node - safe default)
+  - NodeOrchestrator caches and reuses agent instances when `reset_context: false`
+  - Enables stateful workflows where agents remember previous node conversations
+  - Perfect for iterative refinement, self-reflection loops, and chain-of-thought reasoning
+
+### Changed
+
+- **Result object**: Cost and tokens now calculated dynamically from logs
+  - `result.cost` and `result.tokens` now properly populated after swarm execution
+  - Values are calculated from usage data in logs, not stored during initialization
+  - Fixed issue where these attributes were always 0/empty
+
+- **Plugin serialization**: New `serialize_config` hook for plugin extensibility
+  - Plugins can now contribute to `Agent::Definition.to_h` via `serialize_config` hook
+  - Removes memory-specific code from SwarmSDK core (moved to SwarmMemory plugin)
+  - Maintains backward compatibility - permissions remain in core SDK (not plugin-specific)
+  - Enables clean separation between core SDK and plugin features (memory, skills, etc.)
+  - Plugins can preserve their configuration when agents are cloned in NodeOrchestrator
+
+- **NodeOrchestrator**: Passes scratchpad configuration to mini-swarms
+  - Bug fix: `scratchpad_enabled` now correctly propagated to node-level swarms
+  - Ensures `use_scratchpad false` works properly in node workflows
+
+- **CLI ConfigLoader**: Accepts both Swarm and NodeOrchestrator instances
+  - Bug fix: CLI now correctly handles NodeOrchestrator execution
+  - Enables node workflows to work seamlessly with CLI commands
+
+- **Error handling in Agent::Chat**: More robust exception handling
+  - Changed nil response error from `RubyLLM::Error` to `StandardError`
+  - Prevents "undefined method 'body'" error when handling malformed API responses
+
 ## [2.1.1]
 
 ### Added

data/docs/v2/README.md

@@ -1,8 +1,8 @@
-# SwarmSDK & SwarmCLI Documentation
+# SwarmSDK, SwarmCLI & SwarmMemory Documentation
 
-**Version 2.0**
+**Version 2.1**
 
-Welcome to the official documentation for SwarmSDK and SwarmCLI - a Ruby framework for orchestrating multiple AI agents as a collaborative team.
+Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory - a Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.
 
 ---
 
@@ -41,18 +41,32 @@ Welcome to the official documentation for SwarmSDK and SwarmCLI - a Ruby framewo
 
 **Quick lookups and complete API reference:**
 
+### Architecture & Execution
+- **[Architecture Flow Diagram](reference/architecture-flow.md)** ⭐ NEW
+  Complete system architecture: components, dependencies, and relationships across SwarmSDK, SwarmCLI, and SwarmMemory
+
+- **[Execution Flow Diagram](reference/execution-flow.md)** ⭐ NEW
+  Runtime execution journey: what happens when you execute a prompt (21 detailed steps across 6 phases)
+
+- **[Event Payload Structures](reference/event_payload_structures.md)**
+  Complete reference for all log event types and their payloads
+
 ### Command-Line Interface
 - **[CLI Reference](reference/cli.md)**
   Complete reference for all swarm commands: `run`, `migrate`, `mcp serve`, `mcp tools`
 
 ### Ruby DSL API
 - **[Ruby DSL Reference](reference/ruby-dsl.md)**
-  Complete programmatic API: `SwarmSDK.build`, agent DSL, permissions DSL, node DSL, hooks
+  Complete programmatic API: `SwarmSDK.build`, `SwarmSDK.load`, agent DSL, permissions DSL, node DSL, hooks
 
 ### YAML Configuration
 - **[YAML Configuration Reference](reference/yaml.md)**
   Complete YAML structure: agents, tools, permissions, hooks, MCP servers
 
+### SwarmMemory
+- **[SwarmMemory Technical Details](reference/swarm_memory_technical_details.md)**
+  Deep dive: storage architecture, semantic search, FAISS indexing, adapter interface
+
 ---
 
 ## 🛠️ Integration Guides
@@ -172,6 +186,12 @@ Welcome to the official documentation for SwarmSDK and SwarmCLI - a Ruby framewo
 **Build a custom storage adapter**
 → [Memory Adapter Guide](guides/memory-adapters.md)
 
+**Understand the system architecture**
+→ [Architecture Flow Diagram](reference/architecture-flow.md)
+
+**Understand how execution works**
+→ [Execution Flow Diagram](reference/execution-flow.md)
+
 ---
 
 ## 📊 Documentation Structure
@@ -184,20 +204,25 @@ docs/v2/
 │   ├── getting-started.md             # SDK quick start (YAML + Ruby DSL)
 │   ├── quick-start-cli.md             # CLI quick start
 │   ├── complete-tutorial.md           # 100% feature coverage tutorial
-│   ├── swarm-memory.md                # SwarmMemory guide ⭐ NEW
-│   ├── plugins.md                     # Plugin system guide ⭐ NEW
-│   ├── memory-adapters.md             # Adapter development ⭐ NEW
+│   ├── swarm-memory.md                # SwarmMemory guide ⭐
+│   ├── plugins.md                     # Plugin system guide ⭐
+│   ├── memory-adapters.md             # Adapter development ⭐
 │   ├── rails-integration.md           # Rails integration guide
-│   └── claude-code-agents.md          # Claude Code compatibility
+│   ├── claude-code-agents.md          # Claude Code compatibility
+│   └── MEMORY_DEFRAG_GUIDE.md         # Memory defragmentation guide
 │
 ├── reference/                          # Complete API references
+│   ├── architecture-flow.md            # System architecture diagram ⭐ NEW
+│   ├── execution-flow.md               # Runtime execution flow ⭐ NEW
+│   ├── event_payload_structures.md     # Log event payloads
+│   ├── swarm_memory_technical_details.md  # SwarmMemory deep dive
 │   ├── cli.md                          # CLI command reference
 │   ├── ruby-dsl.md                     # Ruby DSL API reference
 │   └── yaml.md                         # YAML configuration reference
 │
 └── CHANGELOG.swarm_sdk.md              # SwarmSDK version history
     CHANGELOG.swarm_cli.md              # SwarmCLI version history
-    CHANGELOG.swarm_memory.md           # SwarmMemory version history ⭐ NEW
+    CHANGELOG.swarm_memory.md           # SwarmMemory version history ⭐
 ```
 
 ---
@@ -214,10 +239,18 @@ docs/v2/
 2. [Rails Integration](guides/rails-integration.md) - Production integration patterns
 3. [Complete Tutorial Parts 7-8](guides/complete-tutorial.md) - Production features and best practices
 
-### Path 3: Reference & API
+### Path 3: SwarmMemory Deep Dive
+1. [SwarmMemory Guide](guides/swarm-memory.md) - Installation, memory tools, usage patterns
+2. [Memory Defragmentation](guides/MEMORY_DEFRAG_GUIDE.md) - Relationship discovery and knowledge graphs
+3. [SwarmMemory Technical Details](reference/swarm_memory_technical_details.md) - Architecture and internals
+4. [Memory Adapter Development](guides/memory-adapters.md) - Build custom storage backends
+
+### Path 4: Reference & API
 1. [Ruby DSL Reference](reference/ruby-dsl.md) - Complete programmatic API
 2. [YAML Reference](reference/yaml.md) - Complete configuration format
 3. [CLI Reference](reference/cli.md) - All command-line options
+4. [Architecture Flow](reference/architecture-flow.md) - System architecture diagram
+5. [Execution Flow](reference/execution-flow.md) - Runtime execution journey
 
 ---
 
@@ -235,6 +268,14 @@ A command-line interface for running SwarmSDK swarms with two modes:
 - **Interactive (REPL)**: Conversational interface for exploration and iteration
 - **Non-Interactive**: One-shot execution perfect for automation and scripting
 
+### SwarmMemory
+A persistent memory system for agents with semantic search capabilities:
+- **Storage**: Hierarchical knowledge organization (concept, fact, skill, experience)
+- **Semantic Search**: FAISS-based vector similarity with local ONNX embeddings
+- **Memory Tools**: 9 tools for writing, reading, editing, and searching knowledge
+- **LoadSkill**: Dynamic tool swapping based on semantic skill discovery
+- **Plugin Architecture**: Integrates seamlessly via SwarmSDK plugin system
+
 ### Configuration Formats
 - **YAML**: Declarative, easy to read, great for shell-based hooks
 - **Ruby DSL**: Programmatic, dynamic, full Ruby power, IDE support
@@ -247,6 +288,8 @@ A command-line interface for running SwarmSDK swarms with two modes:
 |-------|-------|-----------|
 | **Installation** | [SDK Guide](guides/getting-started.md#installation) | - |
 | **First Swarm** | [SDK Guide](guides/getting-started.md#your-first-swarm) | - |
+| **Architecture** | - | [Architecture Flow](reference/architecture-flow.md) |
+| **Execution Flow** | - | [Execution Flow](reference/execution-flow.md) |
 | **CLI Commands** | [CLI Guide](guides/quick-start-cli.md#commands-overview) | [CLI Ref](reference/cli.md) |
 | **REPL Mode** | [CLI Guide](guides/quick-start-cli.md#interactive-mode-repl) | [CLI Ref](reference/cli.md#interactive-mode) |
 | **Tools** | [Tutorial Part 2](guides/complete-tutorial.md#part-2-tools-and-permissions) | [YAML Ref](reference/yaml.md#tools) |
@@ -255,6 +298,9 @@ A command-line interface for running SwarmSDK swarms with two modes:
 | **Hooks** | [Tutorial Part 4](guides/complete-tutorial.md#part-4-hooks-system) | [YAML Ref](reference/yaml.md#hooks-configuration) |
 | **Workflows** | [Tutorial Part 5](guides/complete-tutorial.md#part-5-node-workflows) | [Ruby DSL Ref](reference/ruby-dsl.md#node-builder-dsl) |
 | **MCP Servers** | [Tutorial Part 6](guides/complete-tutorial.md#mcp-server-integration) | [YAML Ref](reference/yaml.md#mcp_servers) |
+| **Memory** | [SwarmMemory Guide](guides/swarm-memory.md) | [Technical Details](reference/swarm_memory_technical_details.md) |
+| **Memory Adapters** | [Adapter Guide](guides/memory-adapters.md) | [Technical Details](reference/swarm_memory_technical_details.md) |
+| **Plugins** | [Plugin Guide](guides/plugins.md) | - |
 | **Rails** | [Rails Guide](guides/rails-integration.md) | - |
 | **Testing** | [Tutorial Part 8](guides/complete-tutorial.md#testing-strategies) | - |
 
@@ -285,18 +331,6 @@ Found an issue or want to improve the documentation?
 
 ---
 
-## 📄 Version History
-
-### v2.0 (January 2025)
-- Complete documentation rewrite
-- Consolidated from 261 files to 7 focused documents
-- 100% feature coverage
-- Added Rails integration guide
-- Added comprehensive tutorial
-- Complete CLI, Ruby DSL, and YAML references
-
----
-
 ## 📚 Additional Resources
 
 - **GitHub Repository**: [parruda/claude-swarm](https://github.com/parruda/claude-swarm)