claude_swarm 1.0.1 → 1.0.2

data/examples/v2/dsl/03_capabilities.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 3: Agent Capabilities
+#
+# Tests: tools, delegates_to, directory
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/03_capabilities.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Capabilities Test")
+  lead(:coordinator)
+
+  agent(:coordinator) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You coordinate work and delegate to workers. Use TodoWrite for multi-step tasks.")
+    description("Coordinator testing delegation")
+
+    # Multiple tools
+    tools(:Read, :Grep, :Glob, :TodoWrite)
+
+    # Delegation
+    delegates_to(:worker)
+
+    # Working directory
+    directory(".")
+  end
+
+  agent(:worker) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You are a worker agent. Answer concisely.")
+    description("Worker agent for delegation testing")
+
+    tools(:Read)
+  end
+end
+
+puts "✅ Swarm with capabilities built!"
+puts ""
+
+# Verify configuration using public API
+coordinator_def = swarm.agent_definition(:coordinator)
+worker_def = swarm.agent_definition(:worker)
+
+puts "Coordinator:"
+puts "  tools: #{coordinator_def.tools.map { |t| t[:name] }.join(", ")}"
+puts "  delegates_to: #{coordinator_def.delegates_to.join(", ")}"
+puts "  directory: #{coordinator_def.directory}"
+puts ""
+
+puts "Worker:"
+puts "  tools: #{worker_def.tools.map { |t| t[:name] }.join(", ")}"
+puts ""
+
+puts "Testing delegation..."
+result = swarm.execute("Delegate a simple task to the worker: ask them what 5 + 3 equals")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Agents involved: #{result.agents_involved.join(", ")}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ Tools, delegation, and directory work!"

data/examples/v2/dsl/04_llm_parameters.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 4: LLM Parameters
+#
+# Tests: parameters (temperature, max_tokens, reasoning), timeout
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/04_llm_parameters.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("LLM Parameters Test")
+  lead(:configured_agent)
+
+  agent(:configured_agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You test LLM parameters. Be concise.")
+    description("Agent with custom LLM parameters")
+    tools(:Read)
+
+    # LLM parameters hash
+    parameters(
+      temperature: 0.3,
+      max_tokens: 100,
+      reasoning: "low",
+    )
+
+    # HTTP timeout
+    timeout(60)
+  end
+end
+
+puts "✅ Swarm with LLM parameters built!"
+puts ""
+
+agent_def = swarm.agent_definition(:configured_agent)
+
+puts "Parameter Verification:"
+puts "  parameters: #{agent_def.parameters.inspect}"
+puts "  timeout: #{agent_def.timeout}"
+puts ""
+
+puts "Running test query with configured parameters..."
+result = swarm.execute("Count to 3")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ LLM parameters and timeout work!"

data/examples/v2/dsl/05_advanced_flags.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 5: Advanced Flags
+#
+# Tests: disable_default_tools, bypass_permissions, coding_agent, assume_model_exists
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/05_advanced_flags.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+require_relative "../../../swarm_sdk/permissions_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Advanced Flags Test")
+  lead(:test_agent)
+
+  agent(:test_agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    description("Agent testing advanced flags")
+
+    # Test skip_base_prompt: true (custom prompt only)
+    coding_agent(false)
+    system_prompt("You are a test agent. You only have Read tool. Say 'flags work' when asked.")
+
+    # Test assume_model_exists: true (skip model validation)
+    assume_model_exists(true)
+
+    # Test bypass_permissions: false (respect permissions)
+    bypass_permissions(false)
+
+    # Only Read tool (no defaults) - using include_default: false
+    tools(:Read, include_default: false)
+
+    # Add permissions to verify bypass_permissions: false respects them
+    permissions do
+      tool(:Read).deny_paths("tmp/secret.txt")
+    end
+  end
+end
+
+puts "✅ Swarm with advanced flags built!"
+puts ""
+
+agent_def = swarm.agent_definition(:test_agent)
+
+puts "Advanced Flags Verification:"
+puts "  coding_agent: #{agent_def.coding_agent}"
+puts "  disable_default_tools: #{agent_def.disable_default_tools}"
+puts "  bypass_permissions: #{agent_def.bypass_permissions}"
+puts "  assume_model_exists: #{agent_def.assume_model_exists}"
+puts "  system_prompt: #{agent_def.system_prompt[0..80]}..."
+puts ""
+
+# Verify agent tools (should NOT include defaults like Grep, Glob)
+agent_chat = swarm.agent(:test_agent)
+tool_names = agent_chat.tools.keys
+puts "Agent tools (should be ONLY Read, no defaults):"
+puts "  #{tool_names.join(", ")}"
+puts ""
+
+puts "Running test query..."
+result = swarm.execute("Are the flags working?")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ All advanced flags work correctly!"

data/examples/v2/dsl/06_permissions.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 6: Permissions DSL
+#
+# Tests: all_agents permissions, agent permissions, path and command restrictions
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/06_permissions.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"
+require "fileutils"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+# Setup test environment
+FileUtils.mkdir_p("tmp/allowed")
+FileUtils.mkdir_p("tmp/forbidden")
+File.write("tmp/allowed/test.txt", "allowed content")
+File.write("tmp/forbidden/secret.txt", "secret content")
+
+swarm = SwarmSDK.build do
+  name("Permissions Test")
+  lead(:restricted_agent)
+
+  # Default permissions for all agents
+  all_agents do
+    tools(:Write)
+
+    permissions do
+      tool(:Write).allow_paths("tmp/allowed/**/*")
+      tool(:Write).deny_paths("tmp/forbidden/**/*")
+    end
+  end
+
+  agent(:restricted_agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You test file permissions. Try to write to allowed and forbidden paths.")
+    description("Agent with write restrictions")
+
+    tools(:Read, :Bash)
+
+    # Agent-specific Bash permissions
+    permissions do
+      tool(:Bash).allow_commands("^ls", "^pwd$", "^echo")
+      tool(:Bash).deny_commands("^rm", "^dd")
+    end
+  end
+end
+
+puts "✅ Swarm with permissions built!"
+puts ""
+
+agent_def = swarm.agent_definition(:restricted_agent)
+
+puts "Permissions Verification:"
+puts "  Default (Write): #{agent_def.default_permissions}"
+puts "  Agent (Bash): #{agent_def.agent_permissions}"
+puts ""
+
+puts "Testing simple query with permissions in place..."
+result = swarm.execute("Say 'permissions configured'")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ Permissions DSL configured correctly!"
+puts ""
+puts "Note: Permissions are enforced - agent can only:"
+puts "  - Write to tmp/allowed/** (not tmp/forbidden/**)"
+puts "  - Run Bash: ls, pwd, echo (not rm, dd)"
+
+# Cleanup
+FileUtils.rm_rf("tmp/allowed")
+FileUtils.rm_rf("tmp/forbidden")

data/examples/v2/dsl/07_mcp_server.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 7: MCP Server Configuration
+#
+# Tests: mcp_server with filesystem MCP server (stdio transport)
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/07_mcp_server.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("MCP Server Test")
+  lead(:mcp_agent)
+
+  agent(:mcp_agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You have access to MCP tools from filesystem server. List available tools when asked.")
+    description("Agent with MCP server access")
+
+    tools(:Read)
+
+    # Add example MCP server (filesystem-mcp for demonstration)
+    mcp_server(
+      :filesystem,
+      type: :stdio,
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      env: {},
+    )
+  end
+end
+
+puts "✅ Swarm with MCP server built!"
+puts ""
+
+agent_def = swarm.agent_definition(:mcp_agent)
+
+puts "MCP Server Verification:"
+puts "  Servers configured: #{agent_def.mcp_servers.size}"
+agent_def.mcp_servers.each do |server|
+  puts "    - #{server[:name]} (#{server[:type]})"
+  puts "      command: #{server[:command]}"
+  puts "      args: #{server[:args].inspect}"
+end
+puts ""
+
+puts "Testing MCP server connection..."
+puts "(Agent should have access to filesystem MCP tools)"
+puts ""
+
+result = swarm.execute("What tools do you have access to? List them.")
+
+puts "Response: #{result.content[0..300]}..."
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ MCP server configuration works!"

data/examples/v2/dsl/08_swarm_hooks.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 8: Swarm-Level Hooks
+#
+# Tests: hook :swarm_start, hook :swarm_stop (Ruby blocks)
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/08_swarm_hooks.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Swarm Hooks Test")
+  lead(:agent)
+
+  # Swarm-level hook: swarm_start
+  hook(:swarm_start) do |ctx|
+    puts "🪝 swarm_start hook fired!"
+    puts "   Prompt: #{ctx.metadata[:prompt]}"
+  end
+
+  # Swarm-level hook: swarm_stop
+  hook(:swarm_stop) do |ctx|
+    puts "🪝 swarm_stop hook fired!"
+    puts "   Success: #{ctx.metadata[:success]}"
+    puts "   Cost: $#{ctx.metadata[:total_cost]}"
+  end
+
+  agent(:agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You test swarm hooks. Say 'hooks work'.")
+    description("Test agent")
+    tools(:Read)
+  end
+end
+
+puts "✅ Swarm with swarm-level hooks built!"
+puts ""
+puts "Running execution to trigger hooks..."
+puts ""
+
+result = swarm.execute("Say 'swarm hooks test'")
+
+puts ""
+puts "Response: #{result.content}"
+puts ""
+puts "✅ Swarm-level hooks work correctly!"
+puts "(Check output above for 🪝 markers)"

data/examples/v2/dsl/09_agent_hooks.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 9: Agent-Level Hooks
+#
+# Tests: hook :pre_tool_use, hook :post_tool_use, hook :user_prompt (Ruby blocks)
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/09_agent_hooks.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Agent Hooks Test")
+  lead(:agent)
+
+  agent(:agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You test agent hooks. Use Read tool to read tmp/test.txt")
+    description("Test agent with hooks")
+    tools(:Read)
+
+    # Hook: user_prompt (before sending to LLM)
+    hook(:user_prompt) do |ctx|
+      puts "🪝 user_prompt hook fired!"
+      puts "   Prompt: #{ctx.metadata[:prompt][0..50]}..."
+    end
+
+    # Hook: pre_tool_use (before tool execution)
+    hook(:pre_tool_use, matcher: "Read") do |ctx|
+      puts "🪝 pre_tool_use hook fired!"
+      puts "   Tool: #{ctx.tool_call.name}"
+      puts "   File: #{ctx.tool_call.parameters[:file_path]}"
+    end
+
+    # Hook: post_tool_use (after tool execution)
+    hook(:post_tool_use, matcher: "Read") do |ctx|
+      puts "🪝 post_tool_use hook fired!"
+      puts "   Result length: #{ctx.tool_result.content.to_s.length} chars"
+    end
+  end
+end
+
+# Setup test file
+require "fileutils"
+FileUtils.mkdir_p("tmp")
+File.write("tmp/test.txt", "test content for hooks")
+
+puts "✅ Swarm with agent-level hooks built!"
+puts ""
+puts "Running execution to trigger hooks..."
+puts ""
+
+result = swarm.execute("Read the file tmp/test.txt")
+
+puts ""
+puts "Response: #{result.content}"
+puts ""
+puts "✅ Agent-level hooks work correctly!"
+puts "(Hooks fired - check output above for 🪝 markers)"
+
+# Cleanup
+File.delete("tmp/test.txt") if File.exist?("tmp/test.txt")

data/examples/v2/dsl/10_all_agents_hooks.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 10: All-Agents Hooks
+#
+# Tests: all_agents { hook } (applies to all agents)
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/10_all_agents_hooks.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+require_relative "../../../swarm_sdk/all_agents_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("All-Agents Hooks Test")
+  lead(:agent1)
+
+  # Hook that applies to ALL agents
+  all_agents do
+    hook(:pre_tool_use, matcher: "Read") do |ctx|
+      agent = ctx.agent_name
+      puts "🪝 all_agents hook fired for: #{agent}"
+      puts "   Tool: #{ctx.tool_call.name}"
+    end
+  end
+
+  agent(:agent1) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You test all_agents hooks. Use Read tool. Delegate to agent2.")
+    description("First test agent")
+    tools(:Read)
+    delegates_to(:agent2)
+  end
+
+  agent(:agent2) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You are agent2. Use Read tool when asked.")
+    description("Second test agent")
+    tools(:Read)
+  end
+end
+
+# Setup test file
+require "fileutils"
+FileUtils.mkdir_p("tmp")
+File.write("tmp/all_agents_test.txt", "testing all_agents hooks")
+
+puts "✅ Swarm with all_agents hooks built!"
+puts ""
+puts "Running execution to trigger hooks across agents..."
+puts ""
+
+result = swarm.execute("Read tmp/all_agents_test.txt, then delegate to agent2 to also read it")
+
+puts ""
+puts "Response: #{result.content[0..150]}..."
+puts ""
+puts "✅ All-agents hooks work correctly!"
+puts "(Check output above for 🪝 markers showing hook fired for multiple agents)"
+
+# Cleanup
+File.delete("tmp/all_agents_test.txt") if File.exist?("tmp/all_agents_test.txt")

data/examples/v2/dsl/11_delegation.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 11: Agent Delegation
+#
+# Tests: Multi-agent delegation with delegates_to
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/11_delegation.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Delegation Test")
+  lead(:coordinator)
+
+  agent(:coordinator) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You coordinate tasks. Delegate math to calculator, text to writer.")
+    description("Coordinator")
+    tools(:TodoWrite)
+    delegates_to(:calculator, :writer)
+  end
+
+  agent(:calculator) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You do math. Answer with just the number.")
+    description("Math specialist")
+    tools(:Read)
+  end
+
+  agent(:writer) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You write text. Be creative and concise.")
+    description("Writing specialist")
+    tools(:Read)
+  end
+end
+
+puts "✅ Swarm with delegation built!"
+puts ""
+
+coordinator_def = swarm.agent_definition(:coordinator)
+puts "Coordinator can delegate to: #{coordinator_def.delegates_to.join(", ")}"
+puts ""
+
+puts "Testing multi-agent delegation..."
+result = swarm.execute("Delegate to calculator: what is 7 + 8? Then delegate to writer: write a haiku about swarms")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ Delegation works!"