claude_swarm 1.0.0 → 1.0.2

data/examples/v2/node_context_demo.rb

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# NodeContext Demo
+#
+# This example demonstrates the NodeContext capabilities:
+# - Access original_prompt from any node
+# - Access all previous node results
+# - Convenience accessors (ctx.content)
+#
+# Run: ruby examples/node_context_demo.rb
+
+require_relative "../lib/swarm_sdk"
+
+swarm = SwarmSDK.build do
+  name("NodeContext Demo")
+
+  # Define agents
+  agent(:planner) do
+    model("claude-sonnet-4-5")
+    provider("openai")
+    description("Planning agent")
+    system_prompt("Create a brief plan.")
+    tools(include_default: false)
+  end
+
+  agent(:implementer) do
+    model("claude-sonnet-4-5")
+    provider("openai")
+    description("Implementation agent")
+    system_prompt("Implement the plan.")
+    tools(include_default: false)
+  end
+
+  agent(:reviewer) do
+    model("claude-sonnet-4-5")
+    provider("openai")
+    description("Review agent")
+    system_prompt("Review the work.")
+    tools(include_default: false)
+  end
+
+  # Node 1: Planning
+  node(:planning) do
+    agent(:planner)
+
+    output do |ctx|
+      puts "\n[planning output transformer]"
+      puts "  ctx.content: #{ctx.content[0..60]}..."
+      puts "  ctx.original_prompt: #{ctx.original_prompt}"
+      puts "  ctx.node_name: #{ctx.node_name}"
+
+      "PLAN: #{ctx.content}"
+    end
+  end
+
+  # Node 2: Implementation
+  node(:implementation) do
+    agent(:implementer)
+    depends_on(:planning)
+
+    input do |ctx|
+      puts "\n[implementation input transformer]"
+      puts "  ctx.content (transformed from planning): #{ctx.content[0..60]}..."
+      puts "  ctx.original_prompt: #{ctx.original_prompt}"
+      puts "  ctx.all_results[:planning].content: #{ctx.all_results[:planning].content[0..40]}..."
+      puts "  ctx.node_name: #{ctx.node_name}"
+      puts "  ctx.dependencies: #{ctx.dependencies.inspect}"
+
+      ctx.content
+    end
+
+    output do |ctx|
+      "IMPLEMENTATION: #{ctx.content}"
+    end
+  end
+
+  # Node 3: Review - demonstrate accessing ALL previous results
+  node(:review) do
+    agent(:reviewer) # No delegation, just solo review
+
+    depends_on(:implementation)
+
+    input do |ctx|
+      puts "\n[review input transformer]"
+      puts "  ctx.original_prompt: #{ctx.original_prompt}"
+      puts "  ctx.all_results.keys: #{ctx.all_results.keys.inspect}"
+
+      # Access specific previous nodes
+      plan = ctx.all_results[:planning].content
+      impl = ctx.all_results[:implementation].content
+
+      puts "  Planning node result: #{plan[0..40]}..."
+      puts "  Implementation node result: #{impl[0..40]}..."
+
+      <<~PROMPT
+        Review this work:
+
+        ORIGINAL REQUEST: #{ctx.original_prompt}
+
+        PLAN:
+        #{plan}
+
+        IMPLEMENTATION:
+        #{impl}
+
+        Provide feedback.
+      PROMPT
+    end
+  end
+
+  start_node(:planning)
+end
+
+puts "=" * 80
+puts "NodeContext Demo"
+puts "=" * 80
+puts "\nExecuting workflow with NodeContext...\n"
+
+result = swarm.execute("Build a todo API")
+
+puts "\n"
+puts "=" * 80
+puts "Final Result:"
+puts "=" * 80
+puts result.content
+puts "=" * 80

data/examples/v2/node_workflow.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Node-Based Workflow Example
+#
+# This example demonstrates how to use nodes to create multi-stage workflows
+# where different teams of agents collaborate in sequence.
+#
+# Features demonstrated:
+# - NodeContext for accessing original_prompt and all_results
+# - Multi-node workflows with delegation
+# - Input/output transformers with full context access
+#
+# Run: ruby examples/node_workflow.rb
+
+require_relative "../lib/swarm_sdk"
+
+swarm = SwarmSDK.build do
+  name("Haiku Workflow")
+
+  # Define all agents globally
+  agent(:planner) do
+    model("claude-sonnet-4-5")
+    description("Planning agent who breaks down tasks into smaller subtasks")
+    provider("openai")
+    system_prompt(<<~PROMPT)
+      Your job is to break down tasks into smaller subtasks. Extract the intent of the user's prompt and break it down into smaller subtasks.
+      Return a list of subtasks.
+    PROMPT
+    tools(include_default: false)
+  end
+
+  agent(:implementer) do
+    model("claude-sonnet-4-5")
+    description("Execution agent who executes the subtasks given to them")
+    provider("openai")
+    system_prompt(<<~PROMPT)
+      Your job is to execute the subtasks given to you.
+    PROMPT
+    tools(include_default: false)
+  end
+
+  agent(:verifier) do
+    model("claude-sonnet-4-5")
+    description("Verifier agent who verifies the implementation")
+    provider("openai")
+    system_prompt(<<~PROMPT)
+      Your job is to verify work given to you and return a summary of your findings
+    PROMPT
+    tools(include_default: false)
+  end
+
+  # Stage 1: Planning
+  node(:planning) do
+    # Input transformer - ctx.content is the initial prompt
+    input do |ctx|
+      <<~PROMPT
+        Please break down the following prompt into smaller subtasks:
+
+        #{ctx.content}
+      PROMPT
+    end
+
+    agent(:planner)
+
+    # Output transformer - ctx has access to original prompt and results
+    output do |ctx|
+      <<~PROMPT
+        Here are the subtasks:
+
+        #{ctx.content}
+
+        Please implement these subtasks.
+      PROMPT
+    end
+  end
+
+  # Stage 2: Implementation
+  node(:implementation) do
+    # verifier is auto-added (mentioned in delegates_to)
+    agent(:implementer).delegates_to(:verifier)
+
+    depends_on(:planning)
+
+    # Demonstrate NodeContext in input transformer
+    input do |ctx|
+      puts "\n[Node: implementation]"
+      puts "  Original prompt: '#{ctx.original_prompt}'"
+      puts "  Planning result: '#{ctx.all_results[:planning].content[0..60]}...'"
+      puts "  Transformed input: '#{ctx.content[0..60]}...'\n"
+
+      ctx.content # Use transformed content from planning output
+    end
+
+    # Transform output for review stage
+    output do |ctx|
+      <<~PROMPT
+        Here is the implementation:
+
+        #{ctx.content}
+
+        Please review this implementation against the original plan.
+      PROMPT
+    end
+  end
+
+  # Stage 3: Review
+  node(:review) do
+    agent(:verifier)
+
+    depends_on(:implementation)
+
+    # Demonstrate full NodeContext capabilities - access ALL previous results
+    input do |ctx|
+      # Access original prompt
+      original = ctx.original_prompt
+
+      # Access specific previous node results via all_results
+      plan = ctx.all_results[:planning].content
+      implementation = ctx.all_results[:implementation].content
+
+      # Current (transformed) content from implementation output
+      transformed = ctx.content
+
+      puts "\n[Node: review]"
+      puts "  Accessing via NodeContext:"
+      puts "    - Original prompt: '#{original}'"
+      puts "    - Planning result: '#{plan[0..50]}...'"
+      puts "    - Implementation result: '#{implementation[0..50]}...'"
+      puts "    - Transformed input: '#{transformed[0..50]}...'\n"
+
+      <<~PROMPT
+        Review the implementation against the original plan:
+
+        ORIGINAL REQUEST: #{original}
+
+        PLAN:
+        #{plan}
+
+        IMPLEMENTATION:
+        #{implementation}
+
+        Provide feedback on whether this follows the plan and suggest improvements.
+      PROMPT
+    end
+  end
+
+  start_node(:planning)
+end
+
+puts "=" * 80
+puts "Node-Based Workflow Example"
+puts "=" * 80
+puts
+puts "This swarm has 3 stages:"
+puts "1. Planning - Break down the task"
+puts "2. Implementation - Execute the subtasks"
+puts "3. Review - Verify the work"
+puts
+puts "=" * 80
+puts
+
+# Execute the workflow
+result = swarm.execute("Write a haiku about the weather") do |log|
+  puts log.to_json
+end
+
+puts "\n"
+puts "=" * 80
+puts "Final Result:"
+puts "=" * 80
+puts result.content
+puts "=" * 80

data/examples/v2/path_resolution_demo.rb

@@ -0,0 +1,216 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Path Resolution Demo
+#
+# Demonstrates how SwarmSDK resolves file paths relative to agent directories.
+# This is a CRITICAL feature introduced in v1.0 that ensures agents operate
+# in their configured directory, not Dir.pwd.
+#
+# Key Concepts:
+# 1. Each agent has a `directory` (singular) configuration
+# 2. Relative paths in file tools are resolved against this directory
+# 3. Absolute paths are used as-is
+# 4. This is fiber-safe (no reliance on Dir.pwd)
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/path_resolution_demo.rb
+
+require "swarm_sdk"
+require "fileutils"
+require "tmpdir"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+# Create a test directory structure for demonstration
+demo_root = File.join(Dir.tmpdir, "swarm_path_demo_#{Process.pid}")
+FileUtils.mkdir_p(demo_root)
+
+# Create subdirectories
+frontend_dir = File.join(demo_root, "frontend")
+backend_dir = File.join(demo_root, "backend")
+shared_dir = File.join(demo_root, "shared")
+
+FileUtils.mkdir_p([frontend_dir, backend_dir, shared_dir])
+
+# Create test files
+File.write(File.join(frontend_dir, "index.html"), "<html><body>Frontend</body></html>")
+File.write(File.join(backend_dir, "server.rb"), "puts 'Backend server'")
+File.write(File.join(shared_dir, "config.yml"), "shared: true")
+File.write(File.join(demo_root, "README.md"), "# Project Root")
+
+puts "=" * 80
+puts "PATH RESOLUTION DEMO"
+puts "=" * 80
+puts ""
+puts "Test directory structure created at: #{demo_root}"
+puts ""
+puts "Directory structure:"
+puts "  #{demo_root}/"
+puts "    ├── README.md"
+puts "    ├── frontend/"
+puts "    │   └── index.html"
+puts "    ├── backend/"
+puts "    │   └── server.rb"
+puts "    └── shared/"
+puts "        └── config.yml"
+puts ""
+puts "=" * 80
+puts ""
+
+# Build a swarm with agents in different directories
+swarm = SwarmSDK.build do
+  name("Path Resolution Demo Swarm")
+  lead(:coordinator)
+
+  # Coordinator works in project root
+  agent(:coordinator) do
+    description("Coordinator working in project root")
+    model("gpt-5-nano")
+    provider("openai")
+
+    # This agent's directory is the project root
+    directory(demo_root)
+
+    tools(:Read, :Write, :Glob)
+    delegates_to(:frontend_agent, :backend_agent)
+
+    system_prompt(<<~PROMPT)
+      You demonstrate path resolution behavior in SwarmSDK.
+
+      Your working directory is: #{demo_root}
+
+      When you use file tools:
+      - Relative paths like "README.md" resolve to #{File.join(demo_root, "README.md")}
+      - Relative paths like "frontend/index.html" resolve to #{File.join(demo_root, "frontend/index.html")}
+      - Absolute paths like "/tmp/test.txt" are used as-is
+
+      Demonstrate this by:
+      1. Reading "README.md" (relative path)
+      2. Listing files with Glob("*") (relative pattern)
+      3. Trying to access files in subdirectories
+    PROMPT
+  end
+
+  # Frontend agent works in frontend/ directory
+  agent(:frontend_agent) do
+    description("Frontend agent working in frontend/ directory")
+    model("gpt-5-nano")
+    provider("openai")
+
+    # This agent's directory is frontend/
+    directory(frontend_dir)
+
+    tools(:Read, :Write, :Glob)
+
+    system_prompt(<<~PROMPT)
+      You are a frontend agent working in: #{frontend_dir}
+
+      Path resolution for your tools:
+      - Relative path "index.html" → #{File.join(frontend_dir, "index.html")}
+      - Relative path "../shared/config.yml" → #{File.join(demo_root, "shared/config.yml")}
+      - Absolute paths are used as-is
+
+      When asked to demonstrate:
+      1. Read "index.html" (relative path in your directory)
+      2. Try to read "../shared/config.yml" (relative path to parent)
+      3. List files with Glob("*.html") (relative pattern)
+    PROMPT
+  end
+
+  # Backend agent works in backend/ directory
+  agent(:backend_agent) do
+    description("Backend agent working in backend/ directory")
+    model("gpt-5-nano")
+    provider("openai")
+
+    # This agent's directory is backend/
+    directory(backend_dir)
+
+    tools(:Read, :Write, :Glob)
+
+    system_prompt(<<~PROMPT)
+      You are a backend agent working in: #{backend_dir}
+
+      Path resolution for your tools:
+      - Relative path "server.rb" → #{File.join(backend_dir, "server.rb")}
+      - Relative path "../README.md" → #{File.join(demo_root, "README.md")}
+      - Absolute paths are used as-is
+
+      When asked to demonstrate:
+      1. Read "server.rb" (relative path in your directory)
+      2. Try to read "../README.md" (relative path to parent)
+      3. List files with Glob("*.rb") (relative pattern)
+    PROMPT
+  end
+end
+
+puts "✅ Swarm created with 3 agents in different directories"
+puts ""
+puts "Agent Directories:"
+puts "  coordinator    → #{demo_root}"
+puts "  frontend_agent → #{frontend_dir}"
+puts "  backend_agent  → #{backend_dir}"
+puts ""
+puts "=" * 80
+puts ""
+
+# Verify agent configurations
+puts "AGENT CONFIGURATIONS:"
+puts "-" * 80
+swarm.agent_names.each do |agent_name|
+  agent_def = swarm.agent_definition(agent_name)
+  puts "#{agent_name}:"
+  puts "  directory: #{agent_def.directory}"
+  puts "  tools: #{agent_def.tools.map { |t| t[:name] }.join(", ")}"
+  puts ""
+end
+
+puts "PATH RESOLUTION EXAMPLES:"
+puts "-" * 80
+puts ""
+puts "Coordinator (directory: #{demo_root}):"
+puts "  'README.md' → #{File.join(demo_root, "README.md")}"
+puts "  'frontend/index.html' → #{File.join(demo_root, "frontend/index.html")}"
+puts ""
+puts "Frontend Agent (directory: #{frontend_dir}):"
+puts "  'index.html' → #{File.join(frontend_dir, "index.html")}"
+puts "  '../shared/config.yml' → #{File.join(demo_root, "shared/config.yml")}"
+puts "  '../README.md' → #{File.join(demo_root, "README.md")}"
+puts ""
+puts "Backend Agent (directory: #{backend_dir}):"
+puts "  'server.rb' → #{File.join(backend_dir, "server.rb")}"
+puts "  '../shared/config.yml' → #{File.join(demo_root, "shared/config.yml")}"
+puts "  '../README.md' → #{File.join(demo_root, "README.md")}"
+puts ""
+
+# Uncomment below to test with actual LLM calls (requires API key and time)
+# puts "LIVE TESTS (uncomment to run):"
+# puts "-" * 80
+# result = swarm.execute("Read the file 'README.md' and tell me what it contains.")
+# puts "Result: #{result.content}"
+# puts ""
+
+puts "=" * 80
+puts "KEY TAKEAWAYS"
+puts "=" * 80
+puts ""
+puts "1. Each agent has ONE directory (singular, not plural)"
+puts "2. Relative paths are resolved against the agent's directory"
+puts "3. Absolute paths are used as-is"
+puts "4. Agents can access parent/sibling dirs via '../' relative paths"
+puts "5. This is fiber-safe and doesn't rely on Dir.pwd"
+puts ""
+puts "MIGRATION NOTE:"
+puts "  OLD (v0.x): directories: ['.', 'lib/', 'test/']  # Multiple dirs"
+puts "  NEW (v1.0): directory: 'lib/'                    # Single dir"
+puts ""
+puts "For multi-directory access, use permissions:"
+puts "  directory: 'lib/'"
+puts "  permissions:"
+puts "    Read:"
+puts "      allowed_paths: ['../test/**']"
+puts ""
+
+# Cleanup
+FileUtils.rm_rf(demo_root)
+puts "✅ Demo complete! Test directory cleaned up."

data/examples/v2/simple-swarm-v2.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Ruby DSL version of simple-swarm-v2.yml
+#
+# This demonstrates how to define the same swarm using Ruby's programmatic DSL
+# instead of YAML. The Ruby DSL provides more flexibility and allows for
+# dynamic configuration, conditionals, and Ruby language features.
+#
+# Usage:
+#   swarm run examples/v2/simple-swarm-v2.rb
+#   swarm run examples/v2/simple-swarm-v2.rb "Build a user authentication system"
+#   swarm run examples/v2/simple-swarm-v2.rb -p "Create a REST API for products"
+
+SwarmSDK.build do
+  name "Full-Stack Development Team"
+  lead :architect
+
+  # Lead architect who coordinates the team
+  agent :architect do
+    coding_agent(true)
+    description "Lead architect who coordinates the development team"
+    model "gpt-5-mini"
+    provider "openai"
+
+    system_prompt <<~PROMPT
+      You are the lead architect coordinating a development team. You have access to:
+      - frontend_dev: Specializes in React and UI/UX
+      - backend_dev: Specializes in APIs and databases
+      - qa_engineer: Handles testing and code review
+
+      When given a task, break it down and delegate appropriately. Frontend work goes
+      to frontend_dev, backend work to backend_dev. Always have qa_engineer review
+      the final implementation.
+      For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    PROMPT
+
+    delegates_to :frontend_dev, :backend_dev, :qa_engineer
+  end
+
+  # Frontend specialist
+  agent :frontend_dev do
+    coding_agent(true)
+    description "Frontend developer specializing in React and UI/UX"
+    model "anthropic:claude-sonnet-4-5"
+    provider "openai"
+    system_prompt <<~PROMPT
+      You are a frontend developer specializing in React and modern UI/UX.
+      Focus on component design, user experience, and responsive layouts.
+      When you complete work, you can delegate to qa_engineer for review.
+      For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    PROMPT
+
+    delegates_to :qa_engineer
+  end
+
+  # Backend specialist
+  agent :backend_dev do
+    coding_agent(true)
+    description "Backend developer specializing in APIs and databases"
+    model "anthropic:claude-sonnet-4-5"
+    provider "openai"
+
+    system_prompt <<~PROMPT
+      You are a backend developer specializing in REST APIs, databases, and
+      server-side logic. Focus on scalability, security, and clean architecture.
+      When you complete work, you can delegate to qa_engineer for review.
+      For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    PROMPT
+
+    delegates_to :qa_engineer
+  end
+
+  # QA engineer
+  agent :qa_engineer do
+    coding_agent(true)
+    description "QA engineer who reviews code and creates test plans"
+    model "gpt-5-mini"
+    provider "openai"
+
+    system_prompt <<~PROMPT
+      You are a QA engineer responsible for code review and test planning.
+      Review implementations for bugs, edge cases, and potential issues.
+      Suggest improvements and create comprehensive test plans.
+      Be thorough but constructive in your feedback.
+      For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    PROMPT
+
+    delegates_to # No delegations
+  end
+end

data/examples/v2/simple-swarm-v2.yml

@@ -0,0 +1,62 @@
+version: 2
+swarm:
+  name: "Full-Stack Development Team"
+  lead: architect
+  agents:
+    architect:
+      description: "Lead architect who coordinates the development team"
+      model: gpt-5-mini
+      provider: openai
+      system_prompt: |
+        You are the lead architect coordinating a development team. You have access to:
+        - frontend_dev: Specializes in React and UI/UX
+        - backend_dev: Specializes in APIs and databases
+        - qa_engineer: Handles testing and code review
+
+        When given a task, break it down and delegate appropriately. Frontend work goes
+        to frontend_dev, backend work to backend_dev. Always have qa_engineer review
+        the final implementation.
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      tools: []
+      delegates_to: [frontend_dev, backend_dev, qa_engineer]
+      directory: .
+
+    frontend_dev:
+      description: "Frontend developer specializing in React and UI/UX"
+      model: anthropic:claude-sonnet-4-5
+      provider: openai
+      system_prompt: |
+        You are a frontend developer specializing in React and modern UI/UX.
+        Focus on component design, user experience, and responsive layouts.
+        When you complete work, you can delegate to qa_engineer for review.
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      tools: []
+      delegates_to: [qa_engineer]
+      directory: .
+
+    backend_dev:
+      description: "Backend developer specializing in APIs and databases"
+      model: anthropic:claude-sonnet-4-5
+      provider: openai
+      system_prompt: |
+        You are a backend developer specializing in REST APIs, databases, and
+        server-side logic. Focus on scalability, security, and clean architecture.
+        When you complete work, you can delegate to qa_engineer for review.
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      tools: []
+      delegates_to: [qa_engineer]
+      directory: .
+
+    qa_engineer:
+      description: "QA engineer who reviews code and creates test plans"
+      model: gpt-5-mini
+      provider: openai
+      system_prompt: |
+        You are a QA engineer responsible for code review and test planning.
+        Review implementations for bugs, edge cases, and potential issues.
+        Suggest improvements and create comprehensive test plans.
+        Be thorough but constructive in your feedback.
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+      tools: []
+      delegates_to: []
+      directory: .