claude_swarm 1.0.5 → 1.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb6e856b4f12c1e30c5fb61a01d76e94cc7e660659d64e2458d535a0bf6d3af4
-  data.tar.gz: 65820e42a8d90b659464dcb871d9fde02219a61f74d5522c08a8f46f13e37d37
+  metadata.gz: 0642e42ada976e14c7859fcee3a49563f629813dd5b11bac10e491893fb5f970
+  data.tar.gz: 2a6658b5940ca39bea71d992e50c1e42b4abd95c25e8f72388e49c0f2e6021fa
 SHA512:
-  metadata.gz: 617e5743416494dea623905ed448057ce54479b956549b48377739667767582de8039500904805e8e521329c2b5e1c7f1c2d931c239ef2436e737842ba3cc4b8
-  data.tar.gz: 8572a1c389b3b31684cb18a210d8872fd66c9d1deea4ffb737205efc129e2f0e00201d5e6ed88b32cd9a9df14e7c10a80a4b6a633c55d8845a2cbcbeefd19d44
+  metadata.gz: 1478b5345bea76c1c6de67b5a025736b90db1db14b2432ba0f4bf6634d1668e41f4226823a3dfac4049b40987001fd629e782c9b175bb63e1d6002a189a3a3f7
+  data.tar.gz: 44224e8eaf81a0a29f230c137f347da7c6115b1d9854ca2b4396e5bf3c38cf9a51f782a1321fe7a13fe2fb013f745ea20571c47767cb6e1b8f0dfb83384e87a7

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [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

data/docs/v2/CHANGELOG.swarm_cli.md

@@ -5,6 +5,16 @@ 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

data/docs/v2/CHANGELOG.swarm_sdk.md

@@ -9,6 +9,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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

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)