claude_swarm 1.0.8 → 1.0.10

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

@@ -32,6 +32,116 @@ result = swarm.execute("Task prompt")
 
 ## Top-Level Methods
 
+### SwarmSDK.build
+
+Build a simple multi-agent swarm.
+
+**Signature:**
+```ruby
+SwarmSDK.build(allow_filesystem_tools: nil) {|builder| ... } → Swarm
+```
+
+**Returns:**
+- `Swarm` - Always returns a Swarm instance (simple multi-agent collaboration)
+
+**Parameters:**
+- `allow_filesystem_tools` (Boolean, optional): Override global filesystem tools setting for this swarm
+- `block` (required): Configuration block using the DSL
+
+**Description:**
+Creates a simple multi-agent swarm where agents can collaborate through delegation. Use this for most use cases where you need multiple AI agents working together.
+
+**Example:**
+```ruby
+swarm = SwarmSDK.build do
+  name "Development Team"
+  lead :backend
+
+  agent :backend do
+    model "gpt-4"
+    description "Backend developer"
+    tools :Read, :Write, :Bash
+    delegates_to :tester
+  end
+
+  agent :tester do
+    model "gpt-4o-mini"
+    description "Test specialist"
+    tools :Read, :Bash
+  end
+end
+
+result = swarm.execute("Build authentication API")
+```
+
+**Notes:**
+- Cannot use `node` definitions (raises `ConfigurationError`)
+- Must specify `lead` agent
+- For multi-stage workflows, use `SwarmSDK.workflow` instead
+
+---
+
+### SwarmSDK.workflow
+
+Build a multi-stage workflow with nodes.
+
+**Signature:**
+```ruby
+SwarmSDK.workflow(allow_filesystem_tools: nil) {|builder| ... } → Workflow
+```
+
+**Returns:**
+- `Workflow` - Always returns a Workflow instance (multi-stage pipeline)
+
+**Parameters:**
+- `allow_filesystem_tools` (Boolean, optional): Override global filesystem tools setting for this workflow
+- `block` (required): Configuration block using the DSL
+
+**Description:**
+Creates a multi-stage workflow where different teams of agents execute in sequence. Each node is an independent swarm execution with its own agent configuration and delegation topology. Use this for complex pipelines with distinct stages (planning → implementation → testing).
+
+**Example:**
+```ruby
+workflow = SwarmSDK.workflow do
+  name "Build Pipeline"
+  start_node :planning
+
+  agent :architect do
+    model "gpt-4"
+    description "System architect"
+  end
+
+  agent :coder do
+    model "gpt-4"
+    description "Implementation specialist"
+  end
+
+  node :planning do
+    agent(:architect)
+  end
+
+  node :implementation do
+    agent(:coder)
+    depends_on :planning
+
+    # Transform input from planning node
+    input do |ctx|
+      "Implement this plan:\n#{ctx.content}"
+    end
+  end
+end
+
+result = workflow.execute("Build authentication system")
+```
+
+**Notes:**
+- Cannot use `lead` (raises `ConfigurationError`)
+- Must specify `start_node`
+- Nodes execute in topological order based on `depends_on`
+- Each node can have different agents and delegation topology
+
+---
+
 ### SwarmSDK.configure
 
 Configure global SwarmSDK settings.
@@ -105,7 +215,7 @@ Build a swarm using the DSL.
 
 **Signature:**
 ```ruby
-SwarmSDK.build(allow_filesystem_tools: nil, &block) → Swarm | NodeOrchestrator
+SwarmSDK.build(allow_filesystem_tools: nil, &block) → Swarm | Workflow
 ```
 
 **Parameters:**
@@ -114,7 +224,7 @@ SwarmSDK.build(allow_filesystem_tools: nil, &block) → Swarm | NodeOrchestrator
 
 **Returns:**
 - `Swarm`: For single-swarm configurations
-- `NodeOrchestrator`: For multi-node workflow configurations
+- `Workflow`: For multi-node workflow configurations
 
 **Example:**
 ```ruby
@@ -400,7 +510,7 @@ scratchpad(mode) → void
 **Parameters:**
 - `mode` (Symbol, required): Scratchpad mode
   - For regular Swarms: `:enabled` or `:disabled`
-  - For NodeOrchestrator (workflows with nodes): `:enabled`, `:per_node`, or `:disabled`
+  - For Workflow (workflows with nodes): `:enabled`, `:per_node`, or `:disabled`
 
 **Default:** `:disabled`
 
@@ -409,8 +519,8 @@ Controls scratchpad availability and sharing behavior:
 
 - **`:enabled`**: Scratchpad tools available (ScratchpadWrite, ScratchpadRead, ScratchpadList)
   - Regular Swarm: All agents share one scratchpad
-  - NodeOrchestrator: All nodes share one scratchpad across the workflow
-- **`:per_node`**: (NodeOrchestrator only) Each node gets isolated scratchpad storage
+  - Workflow: All nodes share one scratchpad across the workflow
+- **`:per_node`**: (Workflow only) Each node gets isolated scratchpad storage
 - **`:disabled`**: No scratchpad tools available
 
 Scratchpad is volatile (in-memory only) and provides temporary storage for cross-agent or cross-node communication.
@@ -423,7 +533,7 @@ SwarmSDK.build do
   scratchpad :disabled # Disable scratchpad (default)
 end
 
-# NodeOrchestrator - shared across nodes
+# Workflow - shared across nodes
 SwarmSDK.build do
   scratchpad :enabled  # All nodes share one scratchpad
 
@@ -432,7 +542,7 @@ SwarmSDK.build do
   start_node :planning
 end
 
-# NodeOrchestrator - isolated per node
+# Workflow - isolated per node
 SwarmSDK.build do
   scratchpad :per_node  # Each node gets its own scratchpad
 
@@ -910,7 +1020,7 @@ delegates_to(*agent_names) → void
 
 **Behavior:**
 - Multiple calls are cumulative
-- Creates a `DelegateTaskTo{Agent}` tool for each target (e.g., `DelegateTaskToDatabase`)
+- Creates a `WorkWith{Agent}` tool for each target (e.g., `WorkWithDatabase`)
 
 **Example:**
 ```ruby
@@ -1962,16 +2072,19 @@ Execute a task using the lead agent.
 
 **Signature:**
 ```ruby
-swarm.execute(prompt, &block) → Result
+swarm.execute(prompt, wait: true, &block) → Result | Async::Task
 ```
 
 **Parameters:**
 - `prompt` (String, required): Task prompt
+- `wait` (Boolean, optional): If true (default), blocks until execution completes. If false, returns Async::Task immediately for non-blocking execution.
 - `block` (optional): Log entry handler for streaming
 
-**Returns:** `Result` object
+**Returns:**
+- `Result` if `wait: true` (default)
+- `Async::Task` if `wait: false`
 
-**Example:**
+**Example - Blocking execution (default):**
 ```ruby
 # Basic execution
 result = swarm.execute("Build a REST API")
@@ -1992,6 +2105,36 @@ else
 end
 ```
 
+**Example - Non-blocking execution with cancellation:**
+```ruby
+# Start non-blocking execution
+task = swarm.execute("Build a REST API", wait: false) do |log_entry|
+  puts "#{log_entry[:type]}: #{log_entry[:agent]}"
+end
+
+# ... do other work ...
+
+# Cancel anytime
+task.stop
+
+# Wait for result (returns nil if cancelled)
+result = task.wait
+if result.nil?
+  puts "Execution was cancelled"
+elsif result.success?
+  puts result.content
+else
+  puts "Error: #{result.error.message}"
+end
+```
+
+**Non-blocking execution details:**
+- **`wait: false`**: Returns `Async::Task` immediately, enabling cancellation via `task.stop`
+- **Cooperative cancellation**: Stops when fiber yields (HTTP I/O, tool boundaries), not immediate
+- **Proper cleanup**: MCP clients, fiber storage, and logging cleaned in task's ensure block
+- **`task.wait` returns nil**: Cancelled tasks return `nil` from `wait` method
+- **Use cases**: Long-running tasks, user-initiated cancellation, timeout handling
+
 ---
 
 ## Result Object
@@ -2421,7 +2564,7 @@ Jump to a different node with custom content, bypassing normal dependency order.
 - `node_name` (Symbol, required): Target node name
 - `content` (String, required): Content to pass to target node (validated non-nil)
 
-**Returns:** Control hash (processed by NodeOrchestrator)
+**Returns:** Control hash (processed by Workflow)
 
 **Valid in:** Both input and output transformers
 
@@ -2452,7 +2595,7 @@ Stop entire workflow execution immediately and return content as final result.
 **Parameters:**
 - `content` (String, required): Final content to return (validated non-nil)
 
-**Returns:** Control hash (processed by NodeOrchestrator)
+**Returns:** Control hash (processed by Workflow)
 
 **Valid in:** Both input and output transformers
 
@@ -2483,7 +2626,7 @@ Skip LLM execution for current node and use provided content instead.
 **Parameters:**
 - `content` (String, required): Content to use instead of LLM execution (validated non-nil)
 
-**Returns:** Control hash (processed by NodeOrchestrator)
+**Returns:** Control hash (processed by Workflow)
 
 **Valid in:** Input transformers only
 

data/docs/v2/reference/yaml.md

@@ -6,25 +6,55 @@ Complete YAML configuration reference for SwarmSDK v2.
 
 ## Document Structure
 
-SwarmSDK v2 configurations follow this structure:
+SwarmSDK v2 configurations support two types, distinguished by the root key:
+
+### Simple Swarm (Multi-Agent Collaboration)
 
 ```yaml
 version: 2
-swarm:
-  name: "Swarm Name"
-  lead: agent_name
+swarm:                    # Use 'swarm:' key for swarms
+  name: "Development Team"
+  lead: backend           # Required for swarms
   agents:
-    agent_name:
+    backend:
       # Agent configuration
-  all_agents:
-    # Shared agent configuration
-  hooks:
-    # Swarm-level hooks
-  nodes:
-    # Node configurations (optional)
-  start_node: node_name  # Required if nodes defined
+    tester:
+      # Agent configuration
+```
+
+**Returns:** `SwarmSDK::Swarm` when loaded with `SwarmSDK.load_file`
+
+### Workflow (Multi-Stage Pipeline)
+
+```yaml
+version: 2
+workflow:                 # Use 'workflow:' key for workflows
+  name: "Build Pipeline"
+  start_node: planning    # Required for workflows
+  agents:
+    architect:
+      # Agent configuration
+    coder:
+      # Agent configuration
+  nodes:                  # Required for workflows
+    planning:
+      agents:
+        - agent: architect
+    implementation:
+      agents:
+        - agent: coder
+      dependencies:
+        - planning
 ```
 
+**Returns:** `SwarmSDK::Workflow` when loaded with `SwarmSDK.load_file`
+
+**Type Detection:**
+- `swarm:` key → Creates `SwarmSDK::Swarm` (requires `lead:`, cannot have `nodes:`)
+- `workflow:` key → Creates `SwarmSDK::Workflow` (requires `start_node:` and `nodes:`)
+- Cannot have both `swarm:` and `workflow:` keys in same file
+- Same `SwarmSDK.load_file` API works for both types!
+
 ---
 
 ## Top-Level Fields
@@ -43,8 +73,10 @@ version: 2
 
 ### swarm
 
-**Type:** Object (required)
-**Description:** Root configuration object containing all swarm settings.
+**Type:** Object (required for Swarm type)
+**Description:** Root configuration object for multi-agent collaboration swarms. Use this key when you want agents to collaborate through delegation.
+
+**Mutually exclusive with:** `workflow:`
 
 ```yaml
 swarm:
@@ -56,9 +88,28 @@ swarm:
 
 ---
 
+### workflow
+
+**Type:** Object (required for Workflow type)
+**Description:** Root configuration object for multi-stage pipeline workflows. Use this key when you want to orchestrate agents through sequential or parallel nodes.
+
+**Mutually exclusive with:** `swarm:`
+
+```yaml
+workflow:
+  name: "Build Pipeline"
+  start_node: planning
+  agents:
+    # ...
+  nodes:
+    # ...
+```
+
+---
+
 ## Swarm Configuration
 
-Fields under the `swarm` key.
+Fields under the `swarm` key (for Swarm type configurations).
 
 ### id
 
@@ -224,25 +275,21 @@ swarm:
   scratchpad: enabled   # enable scratchpad
   scratchpad: disabled  # no scratchpad (default)
 
-# With nodes - shared across all nodes
-swarm:
+# Workflow - shared across all nodes
+workflow:
   scratchpad: enabled
-
+  start_node: planning
   nodes:
     planning: { ... }
     implementation: { ... }
 
-  start_node: planning
-
-# With nodes - isolated per node
-swarm:
+# Workflow - isolated per node
+workflow:
   scratchpad: per_node
-
+  start_node: planning
   nodes:
     planning: { ... }
     implementation: { ... }
-
-  start_node: planning
 ```
 
 ---
@@ -313,33 +360,44 @@ swarm:
 
 ### nodes
 
-**Type:** Object (optional)
+**Type:** Object (required for Workflow type)
 **Description:** Map of node names to node configurations. Enables multi-stage workflows with multiple execution stages.
 **Format:** `{ node_name: node_config }`
 
+**Important:** This field is only valid under the `workflow:` key, not `swarm:`.
+
 Nodes allow you to create workflows where different agent teams collaborate in sequence. Each node is an independent swarm execution that can receive input from previous nodes and pass output to subsequent nodes.
 
 **Example:**
 ```yaml
-nodes:
-  planning:
-    agents:
-      - agent: architect
-    output_command: "tee plan.txt"
+workflow:
+  name: "Build Pipeline"
+  start_node: planning
+  agents:
+    architect: { ... }
+    backend: { ... }
+    tester: { ... }
+    reviewer: { ... }
 
-  implementation:
-    agents:
-      - agent: backend
-        delegates_to: [tester]
-        tools: [Read, Edit, Write]  # Override tools for this node
-      - agent: tester
-    dependencies: [planning]
-    input_command: "cat plan.txt"
+  nodes:
+    planning:
+      agents:
+        - agent: architect
+      output_command: "tee plan.txt"
 
-  review:
-    agents:
-      - agent: reviewer
-    dependencies: [implementation]
+    implementation:
+      agents:
+        - agent: backend
+          delegates_to: [tester]
+          tools: [Read, Edit, Write]  # Override tools for this node
+        - agent: tester
+      dependencies: [planning]
+      input_command: "cat plan.txt"
+
+    review:
+      agents:
+        - agent: reviewer
+      dependencies: [implementation]
 ```
 
 **Node configuration fields:**
@@ -376,14 +434,16 @@ nodes:
 
 ### start_node
 
-**Type:** String (required if nodes defined)
+**Type:** String (required for Workflow type)
 **Description:** Name of the starting node for workflow execution.
 
+**Important:** This field is only valid under the `workflow:` key, not `swarm:`.
+
 **Example:**
 ```yaml
-swarm:
+workflow:
   name: "Dev Workflow"
-  lead: coordinator
+  start_node: planning  # Required: Start with planning node
   agents:
     coordinator:
       description: "Coordinator"
@@ -399,7 +459,6 @@ swarm:
       agents:
         - agent: backend
       dependencies: [planning]
-  start_node: planning  # Start with planning node
 ```
 
 ---
@@ -1583,7 +1642,7 @@ agents:
 
 ## Node Configuration
 
-Fields under each node in `swarm.nodes`.
+Fields under each node in `workflow.nodes`.
 
 ### agents
 
@@ -1904,7 +1963,11 @@ permissions:
 
 ---
 
-## Complete Example
+## Complete Examples
+
+### Complete Swarm Example
+
+A multi-agent collaboration swarm where agents delegate tasks to each other:
 
 ```yaml
 version: 2
@@ -2043,8 +2106,65 @@ swarm:
 
       parameters:
         temperature: 0.2
+```
+
+---
+
+### Complete Workflow Example
+
+A multi-stage pipeline workflow with sequential and parallel node execution:
+
+```yaml
+version: 2
+
+workflow:
+  name: "Development Pipeline"
+  start_node: planning
+
+  # Global configuration for all agents
+  all_agents:
+    provider: openai
+    timeout: 180
+    coding_agent: true
+
+  # Agent definitions (shared across nodes)
+  agents:
+    coordinator:
+      description: "Lead coordinator for planning"
+      model: gpt-5
+      system_prompt: "You create detailed project plans"
+      tools: [Read, TodoWrite]
+
+    backend:
+      description: "Backend developer specializing in Ruby on Rails"
+      model: claude-sonnet-4
+      provider: anthropic
+      directory: "backend"
+      system_prompt: "You build clean, testable backend APIs"
+      tools: [Read, Write, Edit, Bash]
+      delegates_to: [database]
 
-  # Multi-stage workflow
+    frontend:
+      description: "Frontend developer specializing in React"
+      model: gpt-5
+      directory: "frontend"
+      system_prompt: "You build modern, accessible frontends"
+      tools: [Read, Write, Edit, Bash]
+
+    database:
+      description: "Database expert for schema design"
+      model: gpt-5
+      directory: "backend"
+      system_prompt: "You design efficient database schemas"
+      tools: [Read, Write, Bash]
+
+    reviewer:
+      description: "Code reviewer checking for bugs"
+      model: o4
+      system_prompt: "You review code for quality and security"
+      tools: [Read, Grep, Glob]
+
+  # Multi-stage workflow nodes
   nodes:
     planning:
       agents:
@@ -2072,8 +2192,6 @@ swarm:
       dependencies: [backend_implementation, frontend_implementation]
       input_command: "scripts/gather-changes.sh"
       output_command: "scripts/format-review.sh"
-
-  start_node: planning
 ```
 
 ---

data/examples/snapshot_demo.rb

@@ -27,7 +27,7 @@ swarm = SwarmSDK.build do
   agent(:assistant) do
     provider("openai")
     model("claude-haiku-4-5")
-    base_url("https://proxy-shopify-ai.local.shop.dev/v1")
+    base_url("https://api.example.com/v1")
     description("Helpful assistant")
     system_prompt("You are a helpful assistant")
     tools(:Think)
@@ -77,7 +77,7 @@ swarm2 = SwarmSDK.build do
   agent(:assistant) do
     provider("openai")
     model("claude-haiku-4-5")
-    base_url("https://proxy-shopify-ai.local.shop.dev/v1")
+    base_url("https://api.example.com/v1")
     description("Helpful assistant")
     system_prompt("You are a helpful assistant")
     tools(:Think)

data/lib/claude_swarm/claude_mcp_server.rb

@@ -36,6 +36,7 @@ module ClaudeSwarm
           openai_token_env: instance_config[:openai_token_env],
           base_url: instance_config[:base_url],
           reasoning_effort: instance_config[:reasoning_effort],
+          zdr: instance_config[:zdr],
         )
       else
         # Default Claude behavior - always use SDK

data/lib/claude_swarm/cli.rb

@@ -172,6 +172,10 @@ module ClaudeSwarm
     method_option :reasoning_effort,
       type: :string,
       desc: "Reasoning effort for OpenAI models"
+    method_option :zdr,
+      type: :boolean,
+      default: false,
+      desc: "Enable ZDR for OpenAI models"
     def mcp_serve
       # Validate reasoning_effort if provided
       if options[:reasoning_effort]
@@ -208,6 +212,7 @@ module ClaudeSwarm
         openai_token_env: options[:openai_token_env],
         base_url: options[:base_url],
         reasoning_effort: options[:reasoning_effort],
+        zdr: options[:zdr],
       }
 
       begin

data/lib/claude_swarm/configuration.rb

@@ -4,7 +4,7 @@ module ClaudeSwarm
   class Configuration
     # Frozen constants for validation
     VALID_PROVIDERS = ["claude", "openai"].freeze
-    OPENAI_SPECIFIC_FIELDS = ["temperature", "api_version", "openai_token_env", "base_url", "reasoning_effort"].freeze
+    OPENAI_SPECIFIC_FIELDS = ["temperature", "api_version", "openai_token_env", "base_url", "reasoning_effort", "zdr"].freeze
     VALID_API_VERSIONS = ["chat_completion", "responses"].freeze
     VALID_REASONING_EFFORTS = ["low", "medium", "high"].freeze
 
@@ -232,6 +232,7 @@ module ClaudeSwarm
         instance_config[:openai_token_env] = config["openai_token_env"] || "OPENAI_API_KEY"
         instance_config[:base_url] = config["base_url"]
         instance_config[:reasoning_effort] = config["reasoning_effort"] if config["reasoning_effort"]
+        instance_config[:zdr] = config["zdr"] if config.key?("zdr")
         # Default vibe to true for OpenAI instances if not specified
         instance_config[:vibe] = true if config["vibe"].nil?
       elsif config["vibe"].nil?