claude_swarm 1.0.10 → 1.0.11

data/docs/v2/reference/ruby-dsl.md

@@ -32,6 +32,132 @@ result = swarm.execute("Task prompt")
 
 ## Top-Level Methods
 
+### SwarmSDK.agent
+
+Register an agent globally for reuse across multiple swarms.
+
+**Signature:**
+```ruby
+SwarmSDK.agent(name) {|builder| ... } → void
+```
+
+**Parameters:**
+- `name` (Symbol, required): Unique agent name
+- `block` (required): Agent configuration block (uses [Agent Builder DSL](#agent-builder-dsl))
+
+**Description:**
+Registers an agent definition in a global registry, allowing it to be referenced by name in any swarm or workflow without re-defining it. This promotes code reuse and separation of concerns.
+
+**Duplicate Registration:**
+Raises `ArgumentError` if an agent with the same name is already registered. Use `SwarmSDK.clear_agent_registry!` to reset.
+
+**Example - Define agents in separate files:**
+```ruby
+# agents/backend.rb
+SwarmSDK.agent :backend do
+  model "claude-sonnet-4"
+  description "Backend developer"
+  system_prompt "You build APIs and databases"
+  tools :Read, :Edit, :Bash
+  # Note: Don't set delegates_to here - it's swarm-specific!
+end
+
+# agents/database.rb
+SwarmSDK.agent :database do
+  model "claude-sonnet-4"
+  description "Database specialist"
+  system_prompt "You design schemas and write migrations"
+  tools :Read, :Edit
+end
+```
+
+**Example - Reference in swarms:**
+```ruby
+# Load agent definitions
+require_relative "agents/backend"
+require_relative "agents/database"
+
+# Reference by name and configure delegation (swarm-specific)
+swarm = SwarmSDK.build do
+  name "Dev Team"
+  lead :backend
+
+  agent :backend do
+    delegates_to :database  # Delegation is swarm-specific
+  end
+  agent :database    # Pulls from registry as-is
+end
+```
+
+**Example - Override registry settings:**
+```ruby
+swarm = SwarmSDK.build do
+  name "Extended Team"
+  lead :backend
+
+  # Registry config applied first, then override block
+  agent :backend do
+    delegates_to :database, :cache  # Set delegation for this swarm
+    tools :CustomTool               # Adds to registry tools
+    timeout 300                     # Overrides registry timeout
+  end
+end
+```
+
+**Workflow Auto-Resolution:**
+Agents referenced in workflow nodes are automatically resolved from the registry if not defined at workflow level:
+
+```ruby
+SwarmSDK.workflow do
+  name "Pipeline"
+  start_node :build
+
+  # No need to define :backend here - auto-resolved from registry!
+  node :build do
+    agent(:backend)  # Resolved from global registry
+  end
+
+  node :test do
+    agent(:backend).delegates_to(:database)  # Both resolved from registry
+  end
+end
+```
+
+**Use Cases:**
+- **Code reuse**: Define agents once, use in multiple swarms
+- **Separation of concerns**: Agent definitions in dedicated files
+- **Testing**: Clear registry between tests with `SwarmSDK.clear_agent_registry!`
+- **Organization**: Large projects with many agents
+
+---
+
+### SwarmSDK.clear_agent_registry!
+
+Clear all registered agents from the global registry.
+
+**Signature:**
+```ruby
+SwarmSDK.clear_agent_registry! → void
+```
+
+**Description:**
+Removes all agents from the global registry. Primarily used for testing to ensure isolation between test cases.
+
+**Example:**
+```ruby
+# In test setup
+def setup
+  SwarmSDK.clear_agent_registry!
+end
+
+# Or in RSpec
+before(:each) do
+  SwarmSDK.clear_agent_registry!
+end
+```
+
+---
+
 ### SwarmSDK.build
 
 Build a simple multi-agent swarm.
@@ -161,6 +287,8 @@ SwarmSDK.configure {|config| ... } → void
 - `webfetch_max_tokens` (Integer): Maximum tokens for WebFetch LLM responses (default: 4096)
 - `allow_filesystem_tools` (Boolean): Enable/disable filesystem tools globally (default: true)
 
+**See [Configuration Reference](configuration_reference.md) for the complete list of 45+ configuration options including API keys, timeouts, limits, and more.**
+
 **Description:**
 Global configuration that applies to all swarms.
 
@@ -198,13 +326,220 @@ SwarmSDK.configure do |config|
 end
 
 # Can also set directly
-SwarmSDK.settings.allow_filesystem_tools = false
+SwarmSDK.config.allow_filesystem_tools = false
 
 # Or via environment variable
 ENV['SWARM_SDK_ALLOW_FILESYSTEM_TOOLS'] = 'false'
 
 # Reset to defaults (disables WebFetch LLM processing, enables filesystem tools)
-SwarmSDK.reset_settings!
+SwarmSDK.reset_config!
+```
+
+---
+
+### Custom Tool Registration
+
+Simple API for registering custom tools without creating full plugins.
+
+#### SwarmSDK.register_tool
+
+Register a custom RubyLLM::Tool for use in swarms.
+
+**Signatures:**
+```ruby
+SwarmSDK.register_tool(tool_class) → Symbol
+SwarmSDK.register_tool(name, tool_class) → Symbol
+```
+
+**Parameters:**
+- `tool_class` (Class): RubyLLM::Tool subclass to register
+- `name` (Symbol, optional): Explicit tool name (if not provided, name is inferred)
+
+**Returns:**
+- `Symbol`: The registered tool name
+
+**Description:**
+Registers a custom tool globally so it can be used in any swarm. Tools are registered by name and can be referenced in agent configurations.
+
+**Tool Lookup Order:**
+1. Plugin tools (from PluginRegistry)
+2. Custom tools (from CustomToolRegistry)
+3. Built-in tools (from Tools::Registry)
+
+**Name Inference:**
+If no name is provided, the tool name is inferred from the class name by:
+1. Taking the last component (e.g., `MyApp::Tools::WeatherTool` → `WeatherTool`)
+2. Removing the `Tool` suffix if present (e.g., `WeatherTool` → `Weather`)
+
+**Context Support:**
+Tools can declare `creation_requirements` to receive agent context:
+- `:agent_name` - Agent identifier (Symbol)
+- `:directory` - Agent's working directory (String)
+
+**Validation:**
+- Tool class must inherit from `RubyLLM::Tool`
+- Cannot override built-in tools (Read, Write, Edit, etc.)
+- Cannot override plugin tools (MemoryWrite, etc.)
+- Cannot register the same name twice
+
+**When to Use:**
+- Simple, stateless tools
+- No persistent storage needed
+- No lifecycle hooks required
+- Quick setup without plugin infrastructure
+
+**When to Use Plugins Instead:**
+- Need per-agent storage
+- Need lifecycle hooks (on_agent_initialized, on_user_message, etc.)
+- Want to contribute to system prompts
+- Building suite of related tools
+
+**Example - Simple Tool:**
+```ruby
+class WeatherTool < RubyLLM::Tool
+  description "Get weather for a city"
+  param :city, type: "string", required: true
+
+  def execute(city:)
+    # Call weather API
+    "Weather in #{city}: Sunny, 72°F"
+  end
+end
+
+# Register with inferred name (:Weather)
+SwarmSDK.register_tool(WeatherTool)
+
+# Use in swarm
+SwarmSDK.build do
+  agent :assistant do
+    model "claude-sonnet-4"
+    tools :Weather, :Read  # Mix custom and built-in tools
+  end
+end
+```
+
+**Example - Context-Aware Tool:**
+```ruby
+class AgentLogTool < RubyLLM::Tool
+  # Declare required context
+  def self.creation_requirements
+    [:agent_name, :directory]
+  end
+
+  description "Log a message for this agent"
+  param :message, type: "string", required: true
+
+  def initialize(agent_name:, directory:)
+    super()
+    @agent_name = agent_name
+    @log_file = File.join(directory, ".agent.log")
+  end
+
+  def execute(message:)
+    File.append(@log_file, "[#{@agent_name}] #{message}\n")
+    "Logged message to #{@log_file}"
+  end
+end
+
+SwarmSDK.register_tool(:AgentLog, AgentLogTool)
+```
+
+**Example - Explicit Name:**
+```ruby
+# Register with custom name
+SwarmSDK.register_tool(:GetWeather, WeatherTool)
+
+SwarmSDK.build do
+  agent :assistant do
+    tools :GetWeather  # Use the custom name
+  end
+end
+```
+
+#### SwarmSDK.custom_tool_registered?
+
+Check if a custom tool is registered.
+
+**Signature:**
+```ruby
+SwarmSDK.custom_tool_registered?(name) → Boolean
+```
+
+**Parameters:**
+- `name` (Symbol | String): Tool name to check
+
+**Returns:**
+- `true` if tool is registered, `false` otherwise
+
+**Example:**
+```ruby
+SwarmSDK.register_tool(WeatherTool)
+SwarmSDK.custom_tool_registered?(:Weather)  # => true
+SwarmSDK.custom_tool_registered?("Weather") # => true
+SwarmSDK.custom_tool_registered?(:Unknown)  # => false
+```
+
+#### SwarmSDK.custom_tools
+
+List all registered custom tool names.
+
+**Signature:**
+```ruby
+SwarmSDK.custom_tools → Array<Symbol>
+```
+
+**Returns:**
+- Array of registered tool names (as symbols)
+
+**Example:**
+```ruby
+SwarmSDK.register_tool(WeatherTool)
+SwarmSDK.register_tool(:Stock, StockPriceTool)
+
+SwarmSDK.custom_tools  # => [:Weather, :Stock]
+```
+
+#### SwarmSDK.unregister_tool
+
+Remove a registered custom tool.
+
+**Signature:**
+```ruby
+SwarmSDK.unregister_tool(name) → Class | nil
+```
+
+**Parameters:**
+- `name` (Symbol | String): Tool name to unregister
+
+**Returns:**
+- The unregistered tool class, or `nil` if not found
+
+**Example:**
+```ruby
+removed = SwarmSDK.unregister_tool(:Weather)
+removed  # => WeatherTool
+```
+
+#### SwarmSDK.clear_custom_tools!
+
+Clear all registered custom tools.
+
+**Signature:**
+```ruby
+SwarmSDK.clear_custom_tools! → void
+```
+
+**Description:**
+Removes all custom tool registrations. Primarily useful for testing to ensure clean state between test runs.
+
+**Example:**
+```ruby
+SwarmSDK.register_tool(WeatherTool)
+SwarmSDK.register_tool(StockPriceTool)
+
+SwarmSDK.clear_custom_tools!
+
+SwarmSDK.custom_tools  # => []
 ```
 
 ---
@@ -980,7 +1315,7 @@ tools(*tool_names, include_default: true) → void
 - `ScratchpadWrite`, `ScratchpadRead`, `ScratchpadList`
 
 **Memory tools** (added if agent has `memory` configured):
-- `MemoryWrite`, `MemoryRead`, `MemoryEdit`, `MemoryMultiEdit`, `MemoryGlob`, `MemoryGrep`, `MemoryDelete`
+- `MemoryWrite`, `MemoryRead`, `MemoryEdit`, `MemoryGlob`, `MemoryGrep`, `MemoryDelete`
 
 **Additional tools:**
 - `Write`, `Edit`, `MultiEdit`, `Bash`
@@ -1129,7 +1464,7 @@ memory(&block) → void
 - `directory(string)` - Directory where memory.json will be stored (required)
 
 **Description:**
-Enables persistent memory for the agent. When configured, the agent automatically gets all 7 memory tools (MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete) and a memory system prompt is appended to help the agent use memory effectively.
+Enables persistent memory for the agent. When configured, the agent automatically gets all 6 memory tools (MemoryWrite, MemoryRead, MemoryEdit, MemoryGlob, MemoryGrep, MemoryDelete) and a memory system prompt is appended to help the agent use memory effectively.
 
 Memory is per-agent (isolated) and persistent (survives across sessions).
 
@@ -2231,6 +2566,124 @@ result.to_json → String
 ```
 Convert to JSON string.
 
+**per_agent_usage**
+```ruby
+result.per_agent_usage → Hash<Symbol, Hash>
+```
+Returns per-agent usage breakdown extracted from execution logs.
+
+Each agent entry contains:
+- `input_tokens` - Input tokens for this agent
+- `output_tokens` - Output tokens for this agent
+- `total_tokens` - Total tokens (input + output)
+- `cached_tokens` - Cached tokens used
+- `context_limit` - Context window limit
+- `usage_percentage` - Percentage of context window used
+- `tokens_remaining` - Tokens remaining in context window
+- `input_cost` - Input cost in dollars
+- `output_cost` - Output cost in dollars
+- `total_cost` - Total cost in dollars
+
+**Example:**
+```ruby
+result = swarm.execute("Build authentication")
+usage = result.per_agent_usage
+
+usage[:backend]
+# => {
+#   input_tokens: 15000,
+#   output_tokens: 5000,
+#   total_tokens: 20000,
+#   cached_tokens: 2000,
+#   context_limit: 200000,
+#   usage_percentage: 10.0,
+#   tokens_remaining: 180000,
+#   input_cost: 0.045,
+#   output_cost: 0.075,
+#   total_cost: 0.12
+# }
+```
+
+---
+
+## Swarm Methods
+
+### context_breakdown
+
+Get real-time context usage breakdown for all agents.
+
+**Signature:**
+```ruby
+swarm.context_breakdown → Hash<Symbol, Hash>
+```
+
+**Returns:**
+Hash with agent names as keys and context usage info as values.
+
+**Description:**
+Returns live context metrics for all agents in the swarm, including both primary agents and delegation instances. Useful for monitoring token consumption and costs during execution.
+
+Each agent entry contains:
+- `input_tokens` - Cumulative input tokens
+- `output_tokens` - Cumulative output tokens
+- `total_tokens` - Total tokens (input + output)
+- `cached_tokens` - Cached tokens used
+- `cache_creation_tokens` - Tokens written to cache
+- `effective_input_tokens` - Actual input tokens charged (input - cached)
+- `context_limit` - Context window limit for the model
+- `usage_percentage` - Percentage of context window used
+- `tokens_remaining` - Tokens remaining in context window
+- `input_cost` - Cumulative input cost in dollars
+- `output_cost` - Cumulative output cost in dollars
+- `total_cost` - Cumulative total cost in dollars
+
+**Example:**
+```ruby
+swarm = SwarmSDK.build do
+  name "Dev Team"
+  lead :backend
+
+  agent :backend do
+    model "claude-sonnet-4"
+    delegates_to :tester
+  end
+
+  agent :tester do
+    model "gpt-4o-mini"
+  end
+end
+
+# During or after execution
+breakdown = swarm.context_breakdown
+
+# Primary agent
+breakdown[:backend]
+# => {
+#   input_tokens: 15000,
+#   output_tokens: 5000,
+#   total_tokens: 20000,
+#   cached_tokens: 2000,
+#   cache_creation_tokens: 1000,
+#   effective_input_tokens: 13000,
+#   context_limit: 200000,
+#   usage_percentage: 10.0,
+#   tokens_remaining: 180000,
+#   input_cost: 0.045,
+#   output_cost: 0.075,
+#   total_cost: 0.12
+# }
+
+# Delegation instance
+breakdown[:"tester@backend"]
+# => { ... same structure ... }
+```
+
+**Use Cases:**
+- Monitor token consumption during long-running tasks
+- Track costs per agent in real-time
+- Identify context-heavy agents approaching limits
+- Debug context window issues
+
 ---
 
 ## Context Management

data/docs/v2/reference/swarm_memory_technical_details.md

@@ -855,28 +855,7 @@ end
 
 ---
 
-### 4. MemoryMultiEdit
-
-**File:** `lib/swarm_memory/tools/memory_multi_edit.rb`
-
-Apply multiple edits sequentially to one entry.
-
-**Input (JSON array):**
-```json
-[
-  {"old_string": "status: pending", "new_string": "status: resolved"},
-  {"old_string": "confidence: medium", "new_string": "confidence: high"}
-]
-```
-
-**Behavior:**
-- Edits applied **sequentially** (each sees previous results)
-- **All-or-nothing** - if any edit fails, NO changes saved
-- Shows which edits succeeded before failure
-
----
-
-### 5. MemoryGlob
+### 4. MemoryGlob
 
 **File:** `lib/swarm_memory/tools/memory_glob.rb`
 
@@ -915,7 +894,7 @@ MAX_RESULTS = 500  # Truncates with system reminder if exceeded
 
 ---
 
-### 6. MemoryGrep
+### 5. MemoryGrep
 
 **File:** `lib/swarm_memory/tools/memory_grep.rb`
 
@@ -949,7 +928,7 @@ path: "skill/debug.md"     # Just that file
 
 ---
 
-### 7. MemoryDelete
+### 6. MemoryDelete
 
 **File:** `lib/swarm_memory/tools/memory_delete.rb`
 
@@ -964,7 +943,7 @@ MemoryDelete(file_path: "experience/temp-experiment.md")
 
 ---
 
-### 8. MemoryDefrag
+### 7. MemoryDefrag
 
 **File:** `lib/swarm_memory/tools/memory_defrag.rb`
 
@@ -1035,7 +1014,7 @@ MemoryDefrag(action: "full", dry_run: true)  # Preview all
 
 ---
 
-### 9. LoadSkill
+### 8. LoadSkill
 
 **File:** `lib/swarm_memory/tools/load_skill.rb`
 
@@ -1079,7 +1058,7 @@ sequenceDiagram
 **Immutable Tools:**
 ```ruby
 # These tools NEVER removed during skill loading:
-- MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit
+- MemoryWrite, MemoryRead, MemoryEdit
 - MemoryDelete, MemoryGlob, MemoryGrep, MemoryDefrag
 - LoadSkill (self)
 ```
@@ -1243,7 +1222,7 @@ class SDKPlugin < SwarmSDK::Plugin
     # Return memory prompt based on mode
   end
 
-  def storage_enabled?(agent_definition)
+  def memory_configured?(agent_definition)
     agent_definition.memory_enabled?
   end
 end
@@ -2025,7 +2004,6 @@ lib/swarm_memory/
 │   ├── memory_write.rb
 │   ├── memory_read.rb
 │   ├── memory_edit.rb
-│   ├── memory_multi_edit.rb
 │   ├── memory_delete.rb
 │   ├── memory_glob.rb
 │   ├── memory_grep.rb

data/docs/v2/reference/yaml.md

@@ -649,7 +649,7 @@ agents:
 - `ScratchpadWrite`, `ScratchpadRead`, `ScratchpadList`
 
 **Memory tools** (added if agent has `memory` configured):
-- `MemoryWrite`, `MemoryRead`, `MemoryEdit`, `MemoryMultiEdit`, `MemoryGlob`, `MemoryGrep`, `MemoryDelete`
+- `MemoryWrite`, `MemoryRead`, `MemoryEdit`, `MemoryGlob`, `MemoryGrep`, `MemoryDelete`
 
 **Additional tools:**
 - `Write`, `Edit`, `MultiEdit`, `Bash`
@@ -761,7 +761,7 @@ Plugin storage (like SwarmMemory) is always shared by base agent name:
 **Default:** `null` (memory disabled)
 **Description:** Configure persistent memory storage for this agent.
 
-When configured, the agent automatically gets all 7 memory tools (MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete) and a memory system prompt is appended.
+When configured, the agent automatically gets all 6 memory tools (MemoryWrite, MemoryRead, MemoryEdit, MemoryGlob, MemoryGrep, MemoryDelete) and a memory system prompt is appended.
 
 Memory is per-agent (isolated) and persistent (survives across sessions).
 

data/lib/claude_swarm/mcp_generator.rb

@@ -123,7 +123,7 @@ module ClaudeSwarm
       # Add optional arguments
       # Handle prompt_file by reading the file contents
       if instance[:prompt_file]
-        prompt_file_path = File.join(@config.root_directory, instance[:prompt_file])
+        prompt_file_path = File.join(@config.base_dir, instance[:prompt_file])
         if File.exist?(prompt_file_path)
           prompt_content = File.read(prompt_file_path)
           args.push("--prompt", prompt_content)

data/lib/claude_swarm/orchestrator.rb

@@ -568,7 +568,14 @@ module ClaudeSwarm
       end
 
       # Always add instance prompt if it exists
-      if instance[:prompt]
+      if instance[:prompt_file]
+        prompt_file_path = File.join(@config.base_dir, instance[:prompt_file])
+        if File.exist?(prompt_file_path)
+          prompt_content = File.read(prompt_file_path)
+          parts << "--append-system-prompt"
+          parts << prompt_content
+        end
+      elsif instance[:prompt]
         parts << "--append-system-prompt"
         parts << instance[:prompt]
       end

data/lib/claude_swarm/version.rb

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

data/lib/swarm_cli/version.rb

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

data/lib/swarm_memory/core/semantic_index.rb

@@ -181,6 +181,9 @@ module SwarmMemory
 
       # Calculate hybrid scores combining semantic similarity and keyword matching
       #
+      # When keyword_score is 0 (no tag matches), falls back to pure semantic scoring
+      # to avoid penalizing results that have excellent semantic matches but no tag overlap.
+      #
       # @param results [Array<Hash>] Results with semantic :similarity scores
       # @param query_keywords [Array<String>] Keywords from query
       # @return [Array<Hash>] Results with updated :similarity (hybrid score) and debug info
@@ -189,8 +192,13 @@ module SwarmMemory
           semantic_score = result[:similarity]
           keyword_score = calculate_keyword_score(result, query_keywords)
 
-          # Hybrid score: weighted combination
-          hybrid_score = (@semantic_weight * semantic_score) + (@keyword_weight * keyword_score)
+          # Fallback to pure semantic when no keyword matches
+          # This prevents penalizing results with excellent semantic matches but no tag overlap
+          hybrid_score = if keyword_score.zero?
+            semantic_score
+          else
+            (@semantic_weight * semantic_score) + (@keyword_weight * keyword_score)
+          end
 
           # Update result with hybrid score and debug info
           result.merge(

data/lib/swarm_memory/core/storage.rb

@@ -18,7 +18,9 @@ module SwarmMemory
       #
       # @param adapter [Adapters::Base] Storage adapter
       # @param embedder [Embeddings::Embedder, nil] Optional embedder for semantic search
-      def initialize(adapter:, embedder: nil)
+      # @param semantic_weight [Float, nil] Weight for semantic similarity in hybrid search (0.0-1.0)
+      # @param keyword_weight [Float, nil] Weight for keyword matching in hybrid search (0.0-1.0)
+      def initialize(adapter:, embedder: nil, semantic_weight: nil, keyword_weight: nil)
         raise ArgumentError, "adapter is required" unless adapter.is_a?(Adapters::Base)
 
         @adapter = adapter
@@ -26,7 +28,10 @@ module SwarmMemory
 
         # Create semantic index if embedder is provided
         @semantic_index = if embedder
-          SemanticIndex.new(adapter: adapter, embedder: embedder)
+          index_options = { adapter: adapter, embedder: embedder }
+          index_options[:semantic_weight] = semantic_weight if semantic_weight
+          index_options[:keyword_weight] = keyword_weight if keyword_weight
+          SemanticIndex.new(**index_options)
         end
       end