swarm_sdk 2.1.3 → 2.3.0

data/lib/swarm_sdk/validation_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Internal result object for validation phase during snapshot restore
+  #
+  # Used during restore to track which agents can be restored and which
+  # need to be skipped due to configuration mismatches.
+  #
+  # @api private
+  class ValidationResult
+    attr_reader :warnings,
+      :skipped_agents,
+      :restorable_agents,
+      :skipped_delegations,
+      :restorable_delegations
+
+    # Initialize validation result
+    #
+    # @param warnings [Array<Hash>] Warning messages with details
+    # @param skipped_agents [Array<Symbol>] Names of agents that can't be restored
+    # @param restorable_agents [Array<Symbol>] Names of agents that can be restored
+    # @param skipped_delegations [Array<String>] Names of delegations that can't be restored
+    # @param restorable_delegations [Array<String>] Names of delegations that can be restored
+    def initialize(warnings:, skipped_agents:, restorable_agents:,
+      skipped_delegations:, restorable_delegations:)
+      @warnings = warnings
+      @skipped_agents = skipped_agents
+      @restorable_agents = restorable_agents
+      @skipped_delegations = skipped_delegations
+      @restorable_delegations = restorable_delegations
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.1.3"
+  VERSION = "2.3.0"
 end

data/lib/swarm_sdk/{node → workflow}/agent_config.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  module Node
+  class Workflow
     # AgentConfig provides fluent API for configuring agents within a node
     #
     # This class enables the chainable syntax:
     #   agent(:backend).delegates_to(:tester, :database)
     #   agent(:backend, reset_context: false)  # Preserve context across nodes
+    #   agent(:backend).tools(:Read, :Edit)    # Override tools for this node
     #
     # @example Basic delegation
     #   agent(:backend).delegates_to(:tester)
@@ -16,6 +17,12 @@ module SwarmSDK
     #
     # @example Preserve agent context
     #   agent(:architect, reset_context: false)
+    #
+    # @example Override tools for this node
+    #   agent(:backend).tools(:Read, :Think)
+    #
+    # @example Combine delegation and tool override
+    #   agent(:backend).delegates_to(:tester).tools(:Read, :Edit, :Write)
     class AgentConfig
       attr_reader :agent_name
 
@@ -24,6 +31,7 @@ module SwarmSDK
         @node_builder = node_builder
         @delegates_to = []
         @reset_context = reset_context
+        @tools = nil # nil means use global agent definition tools
         @finalized = false
       end
 
@@ -33,21 +41,38 @@ module SwarmSDK
       # @return [self] For method chaining
       def delegates_to(*agent_names)
         @delegates_to = agent_names.map(&:to_sym)
-        finalize
+        update_registration
         self
       end
 
-      # Finalize agent configuration (called automatically)
+      # Override tools for this agent in this node
+      #
+      # @param tool_names [Array<Symbol>] Tool names to use (overrides global agent definition)
+      # @return [self] For method chaining
       #
-      # Registers this agent configuration with the parent node builder.
-      # If delegates_to was never called, registers with empty delegation.
+      # @example
+      #   agent(:backend).tools(:Read, :Edit)
+      def tools(*tool_names)
+        @tools = tool_names.map(&:to_sym)
+        update_registration
+        self
+      end
+
+      # Update agent registration (called after each fluent method)
+      #
+      # Always updates the registration with current state.
+      # This allows chaining: .delegates_to(...).tools(...)
       #
       # @return [void]
-      def finalize
-        return if @finalized
+      def update_registration
+        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context, @tools)
+      end
 
-        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context)
-        @finalized = true
+      # Finalize agent configuration (backward compatibility)
+      #
+      # @return [void]
+      def finalize
+        update_registration
       end
     end
   end

data/lib/swarm_sdk/workflow/builder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Workflow
+    # Builder provides DSL for building multi-node workflows
+    # This is the top-level builder accessed via SwarmSDK.workflow
+    #
+    # The DSL enables:
+    # - Node-based workflow configuration
+    # - Agent delegation per node
+    # - Input/output transformers for data flow
+    # - Context preservation across nodes
+    #
+    # @example Multi-stage workflow
+    #   workflow = SwarmSDK.workflow do
+    #     name "Build Pipeline"
+    #     start_node :planning
+    #
+    #     agent :architect do
+    #       model "gpt-5"
+    #       prompt "You design systems"
+    #     end
+    #
+    #     agent :coder do
+    #       model "gpt-4"
+    #       prompt "You implement code"
+    #     end
+    #
+    #     node :planning do
+    #       agent(:architect)
+    #     end
+    #
+    #     node :implementation do
+    #       agent(:coder)
+    #       depends_on :planning
+    #     end
+    #   end
+    #
+    #   workflow.execute("Build auth system")
+    class Builder < Builders::BaseBuilder
+      # Main entry point for DSL
+      #
+      # @example
+      #   workflow = SwarmSDK.workflow do
+      #     name "Pipeline"
+      #     start_node :planning
+      #     node(:planning) { agent(:architect) }
+      #   end
+      class << self
+        def build(allow_filesystem_tools: nil, &block)
+          builder = new(allow_filesystem_tools: allow_filesystem_tools)
+          builder.instance_eval(&block)
+          builder.build_swarm
+        end
+      end
+
+      def initialize(allow_filesystem_tools: nil)
+        super
+        @nodes = {}
+        @start_node = nil
+      end
+
+      # Define a node (mini-swarm execution stage)
+      #
+      # Nodes enable multi-stage workflows where different agent teams
+      # collaborate in sequence. Each node is an independent swarm execution.
+      #
+      # @param name [Symbol] Node name
+      # @yield Block for node configuration
+      # @return [void]
+      #
+      # @example Solo agent node
+      #   node :planning do
+      #     agent(:architect)
+      #   end
+      #
+      # @example Multi-agent node with delegation
+      #   node :implementation do
+      #     agent(:backend).delegates_to(:tester, :database)
+      #     agent(:tester).delegates_to(:database)
+      #     agent(:database)
+      #     depends_on :planning
+      #   end
+      def node(name, &block)
+        builder = Workflow::NodeBuilder.new(name)
+        builder.instance_eval(&block)
+        @nodes[name] = builder
+      end
+
+      # Set the starting node for workflow execution
+      #
+      # Required when nodes are defined. Specifies which node to execute first.
+      #
+      # @param name [Symbol] Name of starting node
+      # @return [void]
+      #
+      # @example
+      #   start_node :planning
+      def start_node(name)
+        @start_node = name.to_sym
+      end
+
+      # Build the actual Workflow instance
+      def build_swarm # Returns Workflow despite method name
+        raise ConfigurationError, "Workflow name not set. Use: name 'My Workflow'" unless @swarm_name
+        raise ConfigurationError, "No nodes defined. Use: node :name { ... }" if @nodes.empty?
+        raise ConfigurationError, "start_node not set. Use: start_node :name" unless @start_node
+
+        # Validate filesystem tools BEFORE building
+        validate_all_agents_filesystem_tools if @all_agents_config
+        validate_agent_filesystem_tools
+
+        build_workflow
+      end
+
+      private
+
+      # Build a node-based workflow
+      #
+      # @return [Workflow] Configured workflow instance
+      def build_workflow
+        # Build agent definitions
+        agent_definitions = build_agent_definitions
+
+        # Create workflow
+        workflow = Workflow.new(
+          swarm_name: @swarm_name,
+          swarm_id: @swarm_id,
+          agent_definitions: agent_definitions,
+          nodes: @nodes,
+          start_node: @start_node,
+          scratchpad: @scratchpad,
+          allow_filesystem_tools: @allow_filesystem_tools,
+        )
+
+        # Pass swarm registry config to workflow if external swarms registered
+        workflow.swarm_registry_config = @swarm_registry_config if @swarm_registry_config.any?
+
+        workflow
+      end
+    end
+  end
+end