claude_swarm 1.0.0 → 1.0.2

data/examples/v2/dsl/12_complete_integration.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 12: Complete Integration
+#
+# Tests: ALL features combined in one swarm
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/12_complete_integration.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+require_relative "../../../swarm_sdk/all_agents_builder"
+require_relative "../../../swarm_sdk/permissions_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+# Track execution
+@swarm_started = false
+@swarm_stopped = false
+
+swarm = SwarmSDK.build do
+  name("Complete Integration Test")
+  lead(:full_featured_agent)
+
+  # Swarm-level hooks
+  hook(:swarm_start) do |_ctx|
+    @swarm_started = true
+    puts "🚀 Swarm starting..."
+  end
+
+  hook(:swarm_stop) do |_ctx|
+    @swarm_stopped = true
+    puts "✅ Swarm complete!"
+  end
+
+  # All-agents configuration
+  all_agents do
+    tools(:Read, :Write)
+
+    permissions do
+      tool(:Write).allow_paths("tmp/**/*")
+    end
+
+    hook(:pre_tool_use, matcher: "Write") do |_ctx|
+      puts "🔒 Validating write operation..."
+    end
+  end
+
+  # Full-featured agent with everything
+  agent(:full_featured_agent) do
+    # Core config
+    model("gpt-5-nano")
+    provider("openai")
+    api_version("v1/responses")
+    context_window(200_000)
+    system_prompt("You are a fully-featured test agent.")
+    description("Agent with all features enabled")
+
+    # Capabilities
+    tools(:Bash, :TodoWrite)
+    delegates_to(:helper)
+    directory(".")
+
+    # MCP server (example using filesystem-mcp)
+    mcp_server(
+      :filesystem,
+      type: :stdio,
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      env: {},
+    )
+
+    # LLM parameters (gpt-5-nano doesn't support temperature, using empty hash for demo)
+    parameters({})
+
+    # Advanced flags
+    bypass_permissions(false)
+    skip_base_prompt(false)
+    assume_model_exists(true)
+    timeout(120)
+
+    # Agent-specific permissions
+    permissions do
+      tool(:Bash).allow_commands("^echo", "^ls", "^pwd$")
+      tool(:Bash).deny_commands("^rm", "^shutdown")
+    end
+
+    # Agent-specific hook
+    hook(:pre_tool_use, matcher: "Bash") do |ctx|
+      puts "🛡️ Validating Bash command: #{ctx.tool_call.parameters[:command]}"
+    end
+  end
+
+  # Helper agent
+  agent(:helper) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You are a helper. Answer concisely.")
+    description("Helper agent")
+    tools(:Read)
+  end
+end
+
+puts "=" * 70
+puts "COMPLETE INTEGRATION TEST"
+puts "=" * 70
+puts ""
+puts "✅ Swarm built with ALL features:"
+puts "  ✓ Swarm config (name, lead)"
+puts "  ✓ Agent core params (model, provider, base_url, api_version, context_window)"
+puts "  ✓ Agent identity (system_prompt, description)"
+puts "  ✓ Capabilities (tools, delegates_to, directory)"
+puts "  ✓ MCP servers (filesystem via stdio)"
+puts "  ✓ LLM params (parameters, timeout)"
+puts "  ✓ Advanced flags (disable_default_tools, bypass_permissions, skip_base_prompt, assume_model_exists)"
+puts "  ✓ Permissions (all_agents and agent-level)"
+puts "  ✓ Hooks (swarm-level, agent-level, all_agents)"
+puts "  ✓ Delegation"
+puts ""
+
+puts "Running integration test..."
+result = swarm.execute("Say 'integration test'")
+
+puts ""
+if result.success?
+  puts "Response: #{result.content}"
+  puts "Success: #{result.success?}"
+  puts ""
+  puts "🎉 COMPLETE INTEGRATION SUCCESSFUL!"
+  puts "All DSL features work correctly together!"
+else
+  puts "❌ Error: #{result.error&.message}"
+  puts "This might be due to MCP server connection - that's okay for syntax testing"
+  puts ""
+  puts "✅ DSL syntax is correct even if MCP connection failed"
+end

data/examples/v2/file_tools_swarm.yml

@@ -0,0 +1,102 @@
+version: 2
+
+swarm:
+  name: "File Tools Demo Swarm"
+  # all_agents:
+  #   permissions:
+  #     Write:
+  #       allowed_paths: ["tmp/LOL/**/*"]
+  #     Read:
+  #       denied_paths: ["lib/**/*"]
+  lead: coordinator
+
+  agents:
+    # Coordinator agent - orchestrates file operations and delegates to worker
+    coordinator:
+      description: "Coordinator that analyzes files and delegates file operations to worker"
+      model: gpt-5-nano
+      reasoning: "low"
+      provider: openai
+      # api_version: "v1/responses"
+
+      # Coordinator has read-only tools plus ability to delegate
+      # TodoWrite helps track progress on complex multi-step tasks
+      tools:
+        - Read
+        - Grep
+        - Glob
+        - TodoWrite
+        # - Write
+
+      # Can delegate work to the worker agent
+      delegates_to:
+        - worker
+
+      directory: .
+
+      system_prompt: |
+        You are a file analysis coordinator. Your role is to:
+
+        1. Analyze codebases using Read, Grep, and Glob tools
+        2. Search for patterns and understand file structures
+        3. Delegate file modification tasks to the 'worker' agent
+        4. Execute bash commands for gathering information (like git status, ls, etc.)
+        5. Use TodoWrite to track progress on complex multi-step tasks (3+ steps)
+
+        You have READ-ONLY access to files. You cannot write or edit files directly.
+        When you need to create or modify files, delegate to the 'worker' agent.
+
+        Always provide clear, specific instructions when delegating tasks.
+        Use TodoWrite proactively to organize your work and show progress.
+
+    # Worker agent - performs file write/edit operations in tmp/ directory only
+    worker:
+      description: "Worker that performs file write and edit operations in tmp/ directory"
+      model: claude-sonnet-4-5
+      provider: openai
+      # api_version: "v1/responses"
+
+      # Worker has all tools including Write and Edit
+      # TodoWrite helps track progress, MultiEdit enables multiple replacements
+      tools:
+        - Read
+        # - Write
+        # - Edit
+        # - MultiEdit
+        - Grep
+        - Glob
+        - TodoWrite
+
+      # Worker doesn't delegate - it's a leaf node
+      delegates_to: []
+
+      directory: .
+
+      system_prompt: |
+        You are a file operations worker. Your role is to:
+
+        1. Create new files using the Write tool
+        2. Modify existing files using the Edit tool or MultiEdit tool (for multiple changes)
+        3. Read files to verify operations
+        4. Search and analyze files as needed
+        5. Use TodoWrite to track progress on complex multi-step tasks (3+ steps)
+
+        CRITICAL SAFETY RULE:
+        You can ONLY perform Write and Edit operations in the tmp/ directory.
+
+        - ✅ ALLOWED: /tmp/test.txt, ./tmp/data.json, /absolute/path/to/tmp/file.rb
+        - ❌ FORBIDDEN: /home/user/file.txt, ./src/main.rb, /etc/config
+
+        Before performing any Write or Edit operation:
+        1. Verify the file path contains 'tmp/' or '/tmp/'
+        2. If the path is NOT in tmp/, REFUSE the operation and explain why
+        3. Always use absolute paths when possible for clarity
+
+        You may freely use Read, Grep, Glob, and Bash tools on any files.
+        This restriction applies ONLY to Write and Edit operations.
+
+        Use MultiEdit when you need to make multiple changes to a single file efficiently.
+        Use TodoWrite proactively to organize your work and show progress.
+
+        When you complete a task, provide a clear summary of what you did.
+

data/examples/v2/hooks/01_basic_hooks.rb

@@ -0,0 +1,133 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic Hooks Example - Beginner Level
+#
+# This example demonstrates the fundamentals of SwarmSDK's hook system:
+# - What hooks are and when they fire
+# - Simple validation hooks
+# - Logging hooks
+# - Blocking operations with hooks
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/hooks/01_basic_hooks.rb
+
+require "swarm_sdk"
+
+puts "=" * 80
+puts "BASIC HOOKS EXAMPLE"
+puts "=" * 80
+puts ""
+
+# Create a simple swarm with hooks
+swarm = SwarmSDK.build do
+  name("Basic Hooks Demo")
+  lead(:assistant)
+
+  # Swarm-level hook: fires before any tool is used
+  hook(:pre_tool_use) do |context|
+    puts "🔧 About to use tool: #{context.tool_name}"
+  end
+
+  # Swarm-level hook: fires after any tool completes
+  hook(:post_tool_use) do |context|
+    if context.tool_result.success?
+      puts "✅ Tool #{context.tool_name} succeeded"
+    else
+      puts "❌ Tool #{context.tool_name} failed"
+    end
+  end
+
+  agent(:assistant) do
+    description("A simple assistant with validation hooks")
+    model("gpt-4o")
+    system_prompt(<<~PROMPT)
+      You are a helpful assistant. You can read and write files.
+      When asked to create files, use the Write tool.
+    PROMPT
+
+    tools(:Write)
+
+    # Agent-specific hook: validate Write operations
+    hook(:pre_tool_use, matcher: "Write") do |context|
+      file_path = context.tool_call.parameters[:file_path]
+      content = context.tool_call.parameters[:content]
+
+      puts "🔍 Validating write operation..."
+      puts "   File: #{file_path}"
+      puts "   Content size: #{content&.length || 0} bytes"
+
+      # Block empty content
+      if content.nil? || content.strip.empty?
+        SwarmSDK::Hooks::Result.halt("Cannot write empty content")
+      end
+
+      # Block certain file extensions
+      if file_path&.end_with?(".key", ".pem", ".secret")
+        SwarmSDK::Hooks::Result.halt("Cannot write sensitive file types")
+      end
+
+      puts "   ✓ Validation passed"
+    end
+  end
+end
+
+# Example 1: Successful operation
+puts "\n--- Example 1: Valid Write Operation ---"
+begin
+  result = swarm.execute("Create a file called test.txt with 'Hello World'")
+  puts "\nResult: #{result.success? ? "SUCCESS" : "FAILED"}"
+  puts "Response: #{result.content[0..100]}..."
+rescue => e
+  puts "\nError: #{e.message}"
+end
+
+# Example 2: Blocked - empty content
+puts "\n\n--- Example 2: Blocked - Empty Content ---"
+begin
+  result = swarm.execute("Create a file called empty.txt with no content")
+  puts "\nResult: #{result.success? ? "SUCCESS" : "FAILED"}"
+  puts "Response: #{result.content[0..200]}..."
+rescue => e
+  puts "\nError: #{e.message}"
+end
+
+# Example 3: Blocked - sensitive file
+puts "\n\n--- Example 3: Blocked - Sensitive File Type ---"
+begin
+  result = swarm.execute("Create a file called secret.key with 'API_KEY=123'")
+  puts "\nResult: #{result.success? ? "SUCCESS" : "FAILED"}"
+  puts "Response: #{result.content[0..200]}..."
+rescue => e
+  puts "\nError: #{e.message}"
+end
+
+puts "\n" + "=" * 80
+puts "KEY TAKEAWAYS"
+puts "=" * 80
+puts <<~SUMMARY
+
+  1. **pre_tool_use hooks** run before tools execute
+     - Perfect for validation and security checks
+     - Can halt execution with Hooks::Result.halt()
+
+  2. **post_tool_use hooks** run after tools complete
+     - Access results via context.tool_result
+     - Check success/failure status
+
+  3. **Matchers** target specific tools
+     - matcher: "Write" - only Write tool
+     - matcher: "Write|Edit" - Write OR Edit
+     - No matcher = all tools
+
+  4. **Hook levels**:
+     - Swarm-level (all agents): hook :event_name
+     - Agent-specific: Inside agent block
+
+  5. **Halting execution**:
+     - SwarmSDK::Hooks::Result.halt("reason")
+     - Returns error message to agent
+     - Agent sees tool failure, not code exception
+
+SUMMARY
+
+puts "=" * 80

data/examples/v2/hooks/02_usage_tracking.rb

@@ -0,0 +1,201 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage Tracking with Hooks - Intermediate Level
+#
+# This example demonstrates usage tracking with the NEW agent_step architecture:
+# - Access token usage and costs in agent_step hooks
+# - Track costs per agent response
+# - Implement budget limits
+# - Monitor context window usage
+# - Generate cost reports
+#
+# NEW ARCHITECTURE: Usage is in agent_step and agent_stop, NOT post_tool_use!
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/hooks/02_usage_tracking.rb
+
+require "swarm_sdk"
+
+puts "=" * 80
+puts "USAGE TRACKING WITH HOOKS"
+puts "=" * 80
+puts ""
+
+# Track costs across all operations
+@total_cost = 0.0
+@step_costs = []
+@step_count = 0
+
+# Budget limit (in dollars)
+BUDGET_LIMIT = 0.10 # 10 cents
+
+swarm = SwarmSDK.build do
+  name("Cost Tracking Demo")
+  lead(:analyst)
+
+  # NEW ARCHITECTURE: Usage tracking in agent_step!
+  # agent_step fires when the LLM responds with tool calls
+  hook(:agent_step) do |context|
+    # Access usage metadata (NEW LOCATION!)
+    usage = context.metadata[:usage]
+
+    if usage
+      @step_count += 1
+      cost = usage[:total_cost]
+      input_tokens = usage[:input_tokens]
+      output_tokens = usage[:output_tokens]
+
+      # Track costs
+      @total_cost += cost
+      @step_costs << {
+        step: @step_count,
+        cost: cost,
+        tokens: usage[:total_tokens],
+        tool_calls: context.metadata[:tool_calls]&.size || 0,
+      }
+
+      # Log usage information
+      puts "\n💰 Agent Step #{@step_count}:"
+      puts "   Tokens: #{input_tokens} in + #{output_tokens} out = #{usage[:total_tokens]} total"
+      puts "   Cost: $#{format("%.6f", cost)}"
+      puts "   Running total: $#{format("%.6f", @total_cost)}"
+      puts "   Tool calls: #{@step_costs.last[:tool_calls]}"
+
+      # Check context usage
+      if usage[:tokens_used_percentage]
+        puts "   Context: #{usage[:tokens_used_percentage]} (#{usage[:tokens_remaining]} tokens remaining)"
+      end
+
+      # Warn if approaching budget limit
+      if @total_cost > BUDGET_LIMIT * 0.8
+        puts "   ⚠️  WARNING: Approaching budget limit (#{(@total_cost / BUDGET_LIMIT * 100).round}%)"
+      end
+
+      # HALT if budget exceeded
+      if @total_cost > BUDGET_LIMIT
+        puts "   🛑 BUDGET EXCEEDED!"
+        SwarmSDK::Hooks::Result.halt("Budget limit of $#{BUDGET_LIMIT} exceeded")
+      end
+    end
+  end
+
+  # Monitor context warnings
+  hook(:context_warning) do |context|
+    puts "\n⚠️  Context Warning:"
+    puts "   Threshold: #{context.metadata[:threshold]}%"
+    puts "   Current usage: #{context.metadata[:percentage].round(1)}%"
+    puts "   Tokens remaining: #{context.metadata[:tokens_remaining]}"
+  end
+
+  # agent_stop fires when the LLM gives final response (no more tool calls)
+  hook(:agent_stop) do |context|
+    usage = context.metadata[:usage]
+
+    puts "\n🏁 Agent Completed:"
+    puts "   Model: #{context.metadata[:model]}"
+    puts "   Finish reason: #{context.metadata[:finish_reason]}"
+
+    if usage
+      @step_count += 1
+      cost = usage[:total_cost]
+      @total_cost += cost
+
+      puts "   Final step tokens: #{usage[:total_tokens]}"
+      puts "   Final step cost: $#{format("%.6f", cost)}"
+      puts "   Total cost: $#{format("%.6f", @total_cost)}"
+      puts "   Context usage: #{usage[:tokens_used_percentage]}"
+    end
+  end
+
+  agent(:analyst) do
+    description("Data analyst that processes files")
+    model("gpt-4o-mini") # Cheaper model for demo
+    system_prompt(<<~PROMPT)
+      You are a data analyst. Analyze files and generate reports.
+      Use the available tools to read files and create summaries.
+    PROMPT
+
+    tools(:Write)
+  end
+end
+
+puts "Budget limit: $#{BUDGET_LIMIT}"
+puts ""
+
+# Execute a task
+puts "\n--- Running Task ---"
+begin
+  result = swarm.execute(<<~TASK)
+    Create a short analysis report about Ruby programming.
+    Write it to analysis.txt.
+
+    Include:
+    1. Brief overview of Ruby
+    2. Key features
+    3. Common use cases
+  TASK
+
+  puts "\n--- Task Complete ---"
+  puts "Success: #{result.success?}"
+  puts "Total cost: $#{format("%.6f", @total_cost)}"
+  puts "Total steps: #{@step_count}"
+
+  # Generate cost breakdown
+  puts "\n--- Cost Breakdown by Step ---"
+  @step_costs.each do |step|
+    puts "Step #{step[:step]}:"
+    puts "  Cost: $#{format("%.6f", step[:cost])}"
+    puts "  Tokens: #{step[:tokens]}"
+    puts "  Tool calls: #{step[:tool_calls]}"
+  end
+rescue => e
+  puts "\nError: #{e.message}"
+end
+
+puts "\n" + "=" * 80
+puts "KEY FEATURES DEMONSTRATED"
+puts "=" * 80
+puts <<~SUMMARY
+
+  1. **NEW ARCHITECTURE: Usage in agent_step hook**
+     - agent_step fires when LLM responds with tool calls
+     - agent_stop fires when LLM gives final response
+     - Usage is NO LONGER in post_tool_use!
+
+  2. **Usage Data Structure**
+     - context.metadata[:usage] contains:
+       * input_tokens, output_tokens, total_tokens
+       * input_cost, output_cost, total_cost
+       * cumulative_input_tokens, cumulative_output_tokens
+       * context_limit, tokens_used_percentage, tokens_remaining
+
+  3. **Cost Tracking**
+     - Track total costs across all agent steps
+     - Break down costs by step
+     - Each LLM response is one step
+
+  4. **Budget Limits**
+     - Implement spending limits
+     - Warn when approaching limit
+     - Halt execution when exceeded
+
+  5. **Context Monitoring**
+     - Monitor token usage as percentage
+     - Track remaining context window
+     - Receive warnings at thresholds (80%, 90%, etc.)
+
+  **KEY DIFFERENCE FROM OLD ARCHITECTURE:**
+  - OLD: Usage in post_tool_use (one per tool)
+  - NEW: Usage in agent_step (one per LLM response)
+  - An agent_step may include multiple tool calls
+  - Usage reflects the cost of the LLM response that generated those tool calls
+
+  **Example Flow:**
+  1. User prompt → LLM responds with tool calls → agent_step hook (with usage)
+  2. Tools execute → post_tool_use hooks (NO usage)
+  3. Tool results sent to LLM → LLM responds with more tool calls → agent_step (with usage)
+  4. LLM gives final answer → agent_stop hook (with usage)
+
+SUMMARY
+
+puts "=" * 80