claude_swarm 1.0.9 → 1.0.11

data/decisions/2025-11-22-001-global-agent-registry.md

@@ -0,0 +1,172 @@
+# Decision: Global Agent Registry for SwarmSDK
+
+**Date:** 2025-11-22
+**Status:** Implemented
+
+## Context
+
+Users wanted the ability to declare agents in separate files and reference them by name in swarm definitions. This promotes:
+- Code reuse across multiple swarms
+- Separation of concerns (agent definitions vs swarm composition)
+- Cleaner organization for large projects
+
+## Decision
+
+Implement a global `AgentRegistry` that stores agent configuration blocks and allows referencing them in `SwarmSDK.build` and `SwarmSDK.workflow` definitions.
+
+### API Design
+
+```ruby
+# Register agent in separate file (e.g., agents/backend.rb)
+SwarmSDK.agent :backend do
+  model "claude-sonnet-4"
+  description "Backend developer"
+  system_prompt "You build APIs"
+  tools :Read, :Edit, :Bash
+end
+
+# Reference in swarm definition
+SwarmSDK.build do
+  name "Dev Team"
+  lead :backend
+
+  agent :backend  # Lookup from registry
+end
+
+# Extend with overrides
+SwarmSDK.build do
+  name "Extended Team"
+  lead :backend
+
+  agent :backend do
+    tools :CustomTool  # Adds to registry tools
+  end
+end
+```
+
+### Key Design Decisions
+
+1. **Proc Storage (not Lambda)**
+   - Procs work naturally with `instance_eval` DSL semantics
+   - Flexible arity handling suits DSL blocks
+   - Blocks passed to methods are already Procs
+
+2. **Class with Class Methods (not Singleton)**
+   - Simpler than full Singleton pattern
+   - Easier to test with `AgentRegistry.clear`
+   - Class methods feel natural for global registry
+
+3. **Duplicate Registration Error**
+   - Raises `ArgumentError` if registering same name twice
+   - Prevents accidental overwrites across files
+   - User must call `SwarmSDK.clear_agent_registry!` to reset
+
+4. **Registry Takes Precedence**
+   - When `agent :name do ... end` is called and agent is registered:
+     - Registry config is applied first
+     - Block becomes overrides (additive)
+   - Promotes DRY principle - registry is source of truth
+
+5. **No Thread Safety**
+   - SwarmSDK uses fiber-based concurrency (Async gem)
+   - Single-threaded execution means no race conditions
+   - Documented limitation for multi-threaded environments
+
+6. **Delegation is Swarm-Specific (Best Practice)**
+   - Don't set `delegates_to` in registry agent definitions
+   - Delegation targets depend on which agents exist in each swarm
+   - Set `delegates_to` as an override when referencing the agent in a swarm
+   - This makes agents truly reusable across different swarm compositions
+
+## Implementation
+
+### New Files
+- `lib/swarm_sdk/agent_registry.rb` - AgentRegistry class
+
+### Modified Files
+- `lib/swarm_sdk.rb` - Added `SwarmSDK.agent` and `SwarmSDK.clear_agent_registry!`
+- `lib/swarm_sdk/builders/base_builder.rb` - Added registry lookup to `#agent` method
+
+### Test Coverage
+- 26 tests covering:
+  - Registry class methods (register, get, registered?, names, clear)
+  - Module methods (agent, clear_agent_registry!)
+  - Registry lookup in Swarm and Workflow builders
+  - Registry + overrides behavior
+  - Multiple swarms sharing registry
+  - Error handling
+  - Edge cases
+
+## Alternatives Considered
+
+1. **Explicit Syntax (`agent :name, from: :registry`)**
+   - Rejected: Too verbose for common use case
+   - Current behavior is intuitive (no args = lookup)
+
+2. **Warning on Shadow**
+   - Rejected: Too noisy, users might ignore
+   - Error-free operation preferred
+
+3. **Thread-Safe Implementation**
+   - Rejected: Unnecessary complexity for fiber-based model
+   - The definitions should be eager loaded in the app that is using the SDK
+   - Documented limitation acceptable
+
+## Enhancement: Workflow Node Registry Fallback
+
+Added automatic agent resolution in workflow nodes. When `agent(:name)` is called inside a node:
+
+1. First checks if agent is defined at workflow level
+2. If not found, checks the global AgentRegistry
+3. If still not found, raises ConfigurationError
+
+This allows powerful patterns like:
+
+```ruby
+# agents/shared.rb
+SwarmSDK.agent :shared_analyzer do
+  model "claude-sonnet-4"
+  description "Shared analyzer"
+end
+
+# workflow.rb
+SwarmSDK.workflow do
+  name "Pipeline"
+  start_node :analyze
+
+  # No need to define shared_analyzer here!
+
+  node :analyze do
+    agent(:shared_analyzer)  # Auto-resolved from registry
+  end
+end
+```
+
+The fallback also resolves delegation targets:
+
+```ruby
+node :process do
+  agent(:main_agent).delegates_to(:helper_agent)
+  # Both resolved from registry
+end
+```
+
+### Implementation
+- Modified `Workflow::Builder#build_workflow` to call `resolve_missing_agents_from_registry`
+- Added `collect_referenced_agents` to gather all agents from nodes (including delegates_to)
+- Resolution happens at build time before agent definitions are built
+
+## Consequences
+
+### Positive
+- Clean separation of agent definitions from swarm composition
+- Easy code reuse across swarms
+- Intuitive API that matches existing DSL patterns
+- Works with both Swarm and Workflow builders
+- Workflow nodes automatically resolve agents from registry
+- Delegation targets also auto-resolve from registry
+
+### Negative
+- Global state (mitigated by clear method for testing)
+- Not thread-safe (documented limitation)
+- Must require agent files before building swarms

data/docs/v2/CHANGELOG.swarm_cli.md

@@ -5,6 +5,26 @@ 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.7]
+
+### Dependencies
+
+- Updated `swarm_sdk` to `~> 2.5.1`
+
+## [2.1.6]
+- Bump SDK and memory gem versions
+
+## [2.1.5]
+- Bump SDK gem version
+
+## [2.1.4]
+
+### Changed
+
+- `ConfigLoader` now accepts both `SwarmSDK::Swarm` and `SwarmSDK::Workflow` instances from Ruby DSL files
+  - Updated error messages to reference `Workflow` instead of `NodeOrchestrator`
+  - Both swarms and workflows work seamlessly with CLI commands
+
 ## [2.1.3]
 
 ### Fixed

data/docs/v2/CHANGELOG.swarm_memory.md

@@ -5,7 +5,152 @@ 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).
 
-## [Unreleased]
+## [2.2.3]
+
+### Fixed
+
+- **Hybrid search weight configuration**: Fixed bug where `semantic_weight` and `keyword_weight` from config weren't being passed to SemanticIndex
+  - **Issue**: SDK plugin extracted weights from config but didn't pass them to Storage/SemanticIndex
+  - **Fix**: Storage now accepts and passes weight parameters through to SemanticIndex
+  - **Impact**: Per-agent weight configuration now works correctly (was only used for logging before)
+  - **Files**: `lib/swarm_memory/core/storage.rb:23-35`, `lib/swarm_memory/integration/sdk_plugin.rb:130-150`
+
+- **YAML config with string keys**: Fixed bug where Hash configs with string keys would fail adapter initialization
+  - **Issue**: Adapters expect symbol keyword arguments, but YAML configs have string keys
+  - **Fix**: Symbolize adapter option keys in create_storage for Hash configs
+  - **Impact**: YAML configurations now work correctly with all adapters
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:113-118`
+
+### Added
+
+- **DSL methods for weights**: Added `semantic_weight()` and `keyword_weight()` methods to MemoryConfig
+  - **Before**: `option(:semantic_weight, 0.8)`
+  - **After**: `semantic_weight(0.8)` (cleaner syntax, consistent with `directory()` and `mode()`)
+  - **Backward compatible**: `option()` method still works
+  - **Files**: `lib/swarm_memory/dsl/memory_config.rb:87-122`
+
+### Changed
+
+- **Automatic semantic fallback**: Hybrid search now falls back to pure semantic scoring when keyword_score is 0
+  - **Before**: semantic=0.92, keyword=0.0 → final=0.46 (penalized by 50/50 weights)
+  - **After**: semantic=0.92, keyword=0.0 → final=0.92 (no penalty when no tag matches)
+  - **Rationale**: Prevents excellent semantic matches from being penalized when there's no keyword/tag overlap
+  - **Impact**: Improved recall for queries with no tag matches
+  - **Files**: `lib/swarm_memory/core/semantic_index.rb:195-201`
+
+## [2.2.2]
+
+### Dependencies
+
+- Updated `swarm_sdk` to `~> 2.5.1`
+
+## [2.2.1]
+
+### Fixed
+
+- **MemoryEdit metadata preservation**: MemoryEdit now preserves all metadata when updating entry content
+  - **Issue**: MemoryEdit was only preserving title, losing tags, confidence, domain, and other metadata
+  - **Fix**: Pass `metadata: entry.metadata` to storage.write to preserve all existing metadata
+  - **Impact**: Prevents metadata loss when editing memory entries
+  - **Files**: `lib/swarm_memory/tools/memory_edit.rb:169`
+
+## [2.2.0]
+
+### Added
+
+- **Per-Adapter Threshold Configuration**: Semantic search thresholds can now be configured per-adapter in YAML
+  - **Fallback chain**: `adapter_config → ENV var → hardcoded_default` (config wins over ENV)
+  - **Supported threshold keys**:
+    - `discovery_threshold` (default: 0.35) - Main similarity threshold for normal queries
+    - `discovery_threshold_short` (default: 0.25) - Threshold for queries with <10 words
+    - `adaptive_word_cutoff` (default: 10) - Word count to switch between thresholds
+    - `semantic_weight` (default: 0.5) - Hybrid search semantic weight
+    - `keyword_weight` (default: 0.5) - Hybrid search keyword weight
+  - **Use cases**: Per-agent threshold tuning, adapter-specific optimization (pgvector vs FAISS), multi-tenant customization
+  - **Backward compatible**: ENV vars still work as deployment-level override
+  - **Zero config required**: Sensible defaults work out of the box
+  - **Example**:
+    ```yaml
+    memory:
+      adapter: multi_bank_postgres
+      agent_id: researcher
+      discovery_threshold: 0.5
+      discovery_threshold_short: 0.3
+      semantic_weight: 0.6
+    ```
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb`
+  - **Tests**: 4 new tests validating threshold extraction and fallback behavior
+
+- **Custom Adapter Support**: SwarmMemory now fully supports custom storage adapters
+  - **Custom adapter options pass-through**: All YAML config keys (except `directory`, `adapter`, `mode`) are now passed to adapter constructor
+  - **Example configuration**:
+    ```yaml
+    memory:
+      adapter: multi_bank_postgres
+      agent_id: business_consultant
+      default_bank: working
+      banks:
+        working: { max_size: 10485760 }
+        long_term: { max_size: 52428800 }
+      bank_access:
+        archive: read_only
+    ```
+  - **Enables**: PostgreSQL, MySQL, Redis, S3, and any custom storage backend
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:290-310`
+  - **Tests**: 2 new tests for custom adapter option pass-through
+
+### Changed
+
+- **BREAKING: `storage_enabled?` renamed to `memory_configured?`** in SDKPlugin
+  - **Improved logic**: Filesystem adapter requires `directory`, custom adapters can use any configuration keys
+  - **Better validation**: Custom adapters are recognized as valid even without `directory` key
+  - **Adapter validation**: Each adapter validates its own requirements during initialization
+  - **No backward compatibility**: `storage_enabled?` method removed entirely (breaking change)
+  - **Migration**: Update any code calling `plugin.storage_enabled?()` to use `plugin.memory_configured?()`
+  - **Files**: `lib/swarm_memory/integration/sdk_plugin.rb:202-235`
+  - **Tests**: 3 new tests for custom adapter recognition
+
+### Removed
+
+- **MemoryMultiEdit tool**: Removed in favor of simpler MemoryEdit tool
+  - **Rationale**: Memory entries are small (typically < 100 lines), making batch edits unnecessary
+  - **Alternative**: Use multiple `MemoryEdit` calls for sequential edits
+  - **Simplification**: Reduces API complexity and LLM error surface (JSON parameter was error-prone)
+  - **Files removed**: `lib/swarm_memory/tools/memory_multi_edit.rb`
+  - **Tool count**: Memory tools reduced from 8 to 7 (MemoryWrite, MemoryRead, MemoryEdit, MemoryDelete, MemoryGlob, MemoryGrep, MemoryDefrag)
+
+### Benefits
+
+- ✅ **Eliminates need for monkey patches** when building custom adapters
+- ✅ **Makes SwarmMemory fully extensible** for any storage backend
+- ✅ **Per-agent threshold tuning** for optimal semantic search accuracy
+- ✅ **Multi-tenant customization** with per-adapter configuration
+- ✅ **Clearer semantics** (memory vs storage terminology)
+- ✅ **Better error messages** (adapters validate themselves)
+
+## [2.1.7]
+
+### Dependencies
+
+- Updated `ruby_llm_swarm` to `~> 1.9.5`
+
+## [2.1.6]
+- Fix files included in the gem
+
+## [2.1.5]
+
+### Fixed
+- **Fixed Zeitwerk naming convention**: Renamed `lib/swarm_memory/errors.rb` to `lib/swarm_memory/error.rb` to match the `SwarmMemory::Error` constant it defines
+  - Fixes `Zeitwerk::Loader.eager_load_all` failures with "uninitialized constant SwarmMemory::Errors" errors
+  - Properly follows Zeitwerk file naming conventions where `error.rb` defines `Error` class
+
+## [2.1.4]
+
+### Changed
+
+- Updated documentation to reference `Workflow` instead of `NodeOrchestrator`
+- Memory configuration preserved when agents are cloned in `Workflow` (formerly `NodeOrchestrator`)
+- No functional changes - fully compatible with SwarmSDK refactoring
 
 ## [2.1.3] - 2025-11-06