swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -33,6 +33,7 @@ module SwarmSDK
         @parameters = nil
         @headers = nil
         @coding_agent = nil
+        @disable_default_tools = nil
       end
 
       # Set model for all agents
@@ -75,6 +76,15 @@ module SwarmSDK
         @coding_agent = enabled
       end
 
+      # Disable default tools for all agents
+      #
+      # @param value [Boolean, Array<Symbol>]
+      #   - true: Disable ALL default tools
+      #   - Array of symbols: Disable specific tools (e.g., [:Think, :TodoWrite])
+      def disable_default_tools(value)
+        @disable_default_tools = value
+      end
+
       # Add tools that all agents will have
       def tools(*tool_names)
         @tools_list.concat(tool_names)
@@ -92,6 +102,7 @@ module SwarmSDK
           :pre_tool_use,
           :post_tool_use,
           :user_prompt,
+          :agent_step,
           :agent_stop,
           :first_message,
           :pre_delegation,
@@ -108,7 +119,11 @@ module SwarmSDK
 
       # Configure permissions for all agents
       #
-      # @example
+      # Supports two forms:
+      # 1. Block form (DSL): permissions do ... end
+      # 2. Direct hash (internal/YAML): set_permissions_hash(hash)
+      #
+      # @example Block form
       #   permissions do
       #     Write.allow_paths "tmp/**/*"
       #     Write.deny_paths "tmp/secrets/**"
@@ -118,6 +133,17 @@ module SwarmSDK
         @permissions_config = PermissionsBuilder.build(&block)
       end
 
+      # Set permissions directly from hash (for YAML translation)
+      #
+      # This is intentionally separate from permissions() to keep the DSL clean.
+      # Called by Configuration when translating YAML permissions.
+      #
+      # @param hash [Hash] Permissions configuration hash
+      # @return [void]
+      def permissions_hash=(hash)
+        @permissions_config = hash || {}
+      end
+
       # Convert to hash for merging with agent configs
       #
       # @return [Hash] Configuration hash
@@ -131,6 +157,7 @@ module SwarmSDK
           parameters: @parameters,
           headers: @headers,
           coding_agent: @coding_agent,
+          disable_default_tools: @disable_default_tools,
           tools: @tools_list,
           permissions: @permissions_config,
         }.compact

data/lib/swarm_sdk/swarm/builder.rb

@@ -28,7 +28,7 @@ module SwarmSDK
     #   end
     #
     #   swarm.execute("Build auth API")
-    class Builder
+    class Builder < Builders::BaseBuilder
       # Main entry point for DSL
       #
       # @example
@@ -37,27 +37,18 @@ module SwarmSDK
       #     agent :backend { ... }
       #   end
       class << self
-        def build(&block)
-          builder = new
+        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
-        @swarm_name = nil
+      def initialize(allow_filesystem_tools: nil)
+        super
         @lead_agent = nil
-        @agents = {}
-        @all_agents_config = nil
         @swarm_hooks = []
-        @nodes = {}
-        @start_node = nil
-        @scratchpad_enabled = true # Default: enabled
-      end
-
-      # Set swarm name
-      def name(swarm_name)
-        @swarm_name = swarm_name
+        @observer_configs = []
       end
 
       # Set lead agent
@@ -65,57 +56,42 @@ module SwarmSDK
         @lead_agent = agent_name
       end
 
-      # Enable or disable shared scratchpad
-      #
-      # @param enabled [Boolean] Whether to enable scratchpad tools
-      def use_scratchpad(enabled)
-        @scratchpad_enabled = enabled
-      end
-
-      # Define an agent with fluent API or load from markdown content
-      #
-      # Supports two forms:
-      # 1. Inline DSL: agent :name do ... end
-      # 2. Markdown content: agent :name, <<~MD ... MD
+      # Define observer agent behavior
       #
-      # The name parameter is always required. If the markdown has a name field
-      # in frontmatter, it will be replaced by the name parameter.
+      # Configures an agent to run in parallel with main execution,
+      # triggered by specific events. The block defines event handlers.
       #
-      # @example Inline DSL
-      #   agent :backend do
-      #     model "gpt-5"
-      #     system_prompt "You build APIs"
-      #     tools :Read, :Write
+      # @param agent_name [Symbol] Name of agent to use as observer (must be defined)
+      # @param options [Hash] Optional observer settings (timeout, max_concurrent, etc.)
+      # @yield Observer configuration block
       #
-      #     hook :pre_tool_use, matcher: "Bash" do |ctx|
-      #       # Inline validation logic!
+      # @example Basic observer
+      #   observer :profiler do
+      #     on :swarm_start do |event|
+      #       "Analyze this prompt: #{event[:prompt]}"
       #     end
       #   end
       #
-      # @example Markdown content
-      #   agent :backend, <<~MD
-      #     ---
-      #     description: "Backend developer"
-      #     model: "gpt-4"
-      #     ---
-      #
-      #     You build APIs.
-      #   MD
-      def agent(name, content = nil, &block)
-        # Case 1: agent :name, <<~MD do ... end (markdown + overrides)
-        if content.is_a?(String) && block_given? && markdown_content?(content)
-          load_agent_from_markdown_with_overrides(content, name, &block)
-        # Case 2: agent :name, <<~MD (markdown only)
-        elsif content.is_a?(String) && !block_given? && markdown_content?(content)
-          load_agent_from_markdown(content, name)
-        # Case 3: agent :name do ... end (inline DSL)
-        elsif block_given?
-          builder = Agent::Builder.new(name)
-          builder.instance_eval(&block)
-          @agents[name] = builder
-        else
-          raise ArgumentError, "Invalid agent definition. Use: agent :name { ... } OR agent :name, <<~MD ... MD OR agent :name, <<~MD do ... end"
+      # @example Observer with options
+      #   observer :monitor, timeout: 120 do
+      #     on :tool_call do |event|
+      #       next unless event[:tool_name] == "Bash"
+      #       "Check command: #{event[:arguments][:command]}"
+      #     end
+      #   end
+      def observer(agent_name, **options, &block)
+        unless @agents.key?(agent_name)
+          raise ConfigurationError,
+            "Observer agent '#{agent_name}' not defined. " \
+              "Define the agent first with `agent :#{agent_name} do ... end`"
         end
+
+        config = Observer::Config.new(agent_name)
+        config.options.merge!(options) if options.any?
+        builder = Observer::Builder.new(agent_name, config)
+        builder.instance_eval(&block)
+
+        @observer_configs << config
       end
 
       # Add swarm-level hook (swarm_start, swarm_stop only)
@@ -136,197 +112,50 @@ module SwarmSDK
         @swarm_hooks << { event: event, command: command, timeout: timeout, block: block }
       end
 
-      # Configure all agents with a block
-      #
-      # @example
-      #   all_agents do
-      #     tools :Read, :Write
-      #
-      #     hook :pre_tool_use, matcher: "Write" do |ctx|
-      #       # Validation for all agents
-      #     end
-      #   end
-      def all_agents(&block)
-        builder = AllAgentsBuilder.new
-        builder.instance_eval(&block)
-        @all_agents_config = builder
-      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)
-      #     after :planning
-      #   end
-      def node(name, &block)
-        builder = Node::Builder.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 Swarm instance or NodeOrchestrator
+      # Build the actual Swarm instance
       def build_swarm
         raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
+        raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
+        raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
 
-        # Check if nodes are defined
-        if @nodes.any?
-          # Node-based workflow (agents optional for agent-less workflows)
-          build_node_orchestrator
-        else
-          # Traditional single-swarm execution (requires agents and lead)
-          raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
-          raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
+        # Validate filesystem tools BEFORE building
+        validate_all_agents_filesystem_tools if @all_agents_config
+        validate_agent_filesystem_tools
 
-          build_single_swarm
-        end
+        build_single_swarm
       end
 
       private
 
-      # Check if a string is markdown content (has frontmatter)
-      #
-      # @param str [String] String to check
-      # @return [Boolean] true if string contains markdown frontmatter
-      def markdown_content?(str)
-        str.start_with?("---") || str.include?("\n---\n")
-      end
-
-      # Load an agent from markdown content
-      #
-      # Returns a hash of the agent config (not a Definition yet) so that
-      # all_agents config can be applied later in the build process.
-      #
-      # @param content [String] Markdown content with frontmatter
-      # @param name_override [Symbol, nil] Optional name to override frontmatter name
-      # @return [void]
-      def load_agent_from_markdown(content, name_override = nil)
-        # Parse markdown content - will extract name from frontmatter if not overridden
-        definition = MarkdownParser.parse(content, name_override)
-
-        # Store the config hash (not Definition) so all_agents can be applied
-        # We'll wrap this in a special marker so we know it came from markdown
-        @agents[definition.name] = { __file_config__: definition.to_h }
-      end
-
-      # Load an agent from markdown content with DSL overrides
-      #
-      # This allows loading from a file and then overriding specific settings:
-      #   agent :reviewer, File.read("reviewer.md") do
-      #     provider :openai
-      #     model "gpt-4o"
-      #   end
-      #
-      # @param content [String] Markdown content with frontmatter
-      # @param name_override [Symbol, nil] Optional name to override frontmatter name
-      # @yield Block with DSL overrides
-      # @return [void]
-      def load_agent_from_markdown_with_overrides(content, name_override = nil, &block)
-        # Parse markdown content first
-        definition = MarkdownParser.parse(content, name_override)
-
-        # Create a builder with the markdown config
-        builder = Agent::Builder.new(definition.name)
-
-        # Apply markdown settings to builder (these become the base)
-        apply_definition_to_builder(builder, definition.to_h)
-
-        # Apply DSL overrides (these override the markdown settings)
-        builder.instance_eval(&block)
-
-        # Store the builder (not file config) so overrides are preserved
-        @agents[definition.name] = builder
-      end
-
-      # Apply agent definition hash to a builder
-      #
-      # @param builder [Agent::Builder] Builder to configure
-      # @param config [Hash] Configuration hash from definition
-      # @return [void]
-      def apply_definition_to_builder(builder, config)
-        builder.description(config[:description]) if config[:description]
-        builder.model(config[:model]) if config[:model]
-        builder.provider(config[:provider]) if config[:provider]
-        builder.base_url(config[:base_url]) if config[:base_url]
-        builder.api_version(config[:api_version]) if config[:api_version]
-        builder.context_window(config[:context_window]) if config[:context_window]
-        builder.system_prompt(config[:system_prompt]) if config[:system_prompt]
-        builder.directory(config[:directory]) if config[:directory]
-        builder.timeout(config[:timeout]) if config[:timeout]
-        builder.parameters(config[:parameters]) if config[:parameters]
-        builder.headers(config[:headers]) if config[:headers]
-        builder.coding_agent(config[:coding_agent]) unless config[:coding_agent].nil?
-        # Don't apply assume_model_exists from markdown - let DSL overrides or auto-enable handle it
-        # builder.assume_model_exists(config[:assume_model_exists]) unless config[:assume_model_exists].nil?
-        builder.bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
-        builder.disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
-
-        # Add tools from markdown
-        if config[:tools]&.any?
-          # Extract tool names from the tools array (which may be hashes with permissions)
-          tool_names = config[:tools].map do |tool|
-            tool.is_a?(Hash) ? tool[:name] : tool
-          end
-          builder.tools(*tool_names)
-        end
-
-        # Add delegates_to
-        builder.delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
-
-        # Add MCP servers
-        config[:mcp_servers]&.each do |server|
-          builder.mcp_server(server[:name], **server.except(:name))
-        end
-      end
-
       # Build a traditional single-swarm execution
       #
       # @return [Swarm] Configured swarm instance
       def build_single_swarm
-        # Create swarm using SDK
-        swarm = Swarm.new(name: @swarm_name, scratchpad_enabled: @scratchpad_enabled)
+        # Validate swarm_id is set if external swarms are registered (required for composable swarms)
+        if @swarm_registry_config.any? && @swarm_id.nil?
+          raise ConfigurationError, "Swarm id must be set using id(...) when using composable swarms"
+        end
 
-        # Merge all_agents config into each agent (including file-loaded ones)
-        merge_all_agents_config_into_agents if @all_agents_config
+        # Create swarm using SDK (swarm_id auto-generates if nil)
+        swarm = Swarm.new(
+          name: @swarm_name,
+          swarm_id: @swarm_id,
+          scratchpad_mode: @scratchpad,
+          allow_filesystem_tools: @allow_filesystem_tools,
+        )
 
-        # Build definitions and add to swarm
-        # Handle both Agent::Builder (inline DSL) and file configs (from files)
-        @agents.each do |agent_name, agent_builder_or_config|
-          definition = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent config (with all_agents merged)
-            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
-          else
-            # Builder object (from inline DSL) - convert to definition
-            agent_builder_or_config.to_definition
+        # Setup swarm registry if external swarms are registered
+        if @swarm_registry_config.any?
+          registry = SwarmRegistry.new(parent_swarm_id: @swarm_id)
+          @swarm_registry_config.each do |reg|
+            registry.register(reg[:name], source: reg[:source], keep_context: reg[:keep_context])
           end
+          swarm.swarm_registry = registry
+        end
 
+        # Build agent definitions and add to swarm
+        agent_definitions = build_agent_definitions
+        agent_definitions.each_value do |definition|
           swarm.add_agent(definition)
         end
 
@@ -334,191 +163,21 @@ module SwarmSDK
         swarm.lead = @lead_agent
 
         # Apply swarm hooks (Ruby blocks)
-        # These are swarm-level hooks (swarm_start, swarm_stop)
         @swarm_hooks.each do |hook_config|
           apply_swarm_hook(swarm, hook_config)
         end
 
         # Apply all_agents hooks (Ruby blocks)
-        # These become swarm-level default callbacks that apply to all agents
         @all_agents_config&.hooks&.each do |hook_config|
           apply_all_agents_hook(swarm, hook_config)
         end
 
-        # NOTE: Agent-specific hooks are already stored in Agent::Definition.callbacks
-        # They'll be applied automatically during agent initialization (pass_4_configure_hooks)
-        # This ensures they're applied at the right time, after LogStream is set up
+        # Add observer configurations to swarm
+        @observer_configs.each { |c| swarm.add_observer_config(c) }
 
         swarm
       end
 
-      # Build a node-based workflow orchestrator
-      #
-      # @return [NodeOrchestrator] Configured orchestrator
-      def build_node_orchestrator
-        raise ConfigurationError, "start_node required when nodes are defined. Use: start_node :name" unless @start_node
-
-        # Merge all_agents config into each agent (applies to all nodes)
-        merge_all_agents_config_into_agents if @all_agents_config
-
-        # Build agent definitions
-        # Handle both Agent::Builder (inline DSL) and file configs (from files)
-        agent_definitions = {}
-        @agents.each do |agent_name, agent_builder_or_config|
-          agent_definitions[agent_name] = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent config (with all_agents merged)
-            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
-          else
-            # Builder object (from inline DSL) - convert to definition
-            agent_builder_or_config.to_definition
-          end
-        end
-
-        # Create node orchestrator
-        NodeOrchestrator.new(
-          swarm_name: @swarm_name,
-          agent_definitions: agent_definitions,
-          nodes: @nodes,
-          start_node: @start_node,
-          scratchpad_enabled: @scratchpad_enabled,
-        )
-      end
-
-      # Merge all_agents configuration into each agent
-      #
-      # All_agents values are used as defaults - agent-specific values override.
-      # This applies to both inline DSL agents (Builder) and file-loaded agents (config hash).
-      #
-      # @return [void]
-      def merge_all_agents_config_into_agents
-        return unless @all_agents_config
-
-        all_agents_hash = @all_agents_config.to_h
-
-        @agents.each_value do |agent_builder_or_config|
-          if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent - merge into the config hash
-            file_config = agent_builder_or_config[:__file_config__]
-
-            # Merge all_agents into file config (file config overrides)
-            # Use same merge strategy as Configuration class
-            merged_config = merge_all_agents_into_config(all_agents_hash, file_config)
-
-            # Update the stored config
-            agent_builder_or_config[:__file_config__] = merged_config
-          else
-            # Builder object (inline DSL agent)
-            agent_builder = agent_builder_or_config
-
-            # Apply all_agents defaults that haven't been set at agent level
-            # Agent values override all_agents values
-            apply_all_agents_defaults(agent_builder, all_agents_hash)
-
-            # Merge tools (prepend all_agents tools)
-            all_agents_tools = @all_agents_config.tools_list
-            agent_builder.prepend_tools(*all_agents_tools) if all_agents_tools.any?
-
-            # Pass all_agents permissions as default_permissions
-            if @all_agents_config.permissions_config.any?
-              agent_builder.default_permissions = @all_agents_config.permissions_config
-            end
-          end
-        end
-      end
-
-      # Merge all_agents config into file-loaded agent config
-      #
-      # Follows same merge strategy as Configuration class:
-      # - Arrays (tools, delegates_to): Concatenate (all_agents + file)
-      # - Hashes (parameters, headers): Merge (file values override)
-      # - Scalars (model, provider, etc.): File overrides
-      #
-      # @param all_agents_hash [Hash] All_agents configuration
-      # @param file_config [Hash] File-loaded agent configuration
-      # @return [Hash] Merged configuration
-      def merge_all_agents_into_config(all_agents_hash, file_config)
-        merged = all_agents_hash.dup
-
-        file_config.each do |key, value|
-          case key
-          when :tools
-            # Concatenate tools: all_agents.tools + file.tools
-            merged[:tools] = Array(merged[:tools]) + Array(value)
-          when :delegates_to
-            # Concatenate delegates_to
-            merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
-          when :parameters
-            # Merge parameters: file values override all_agents
-            merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
-          when :headers
-            # Merge headers: file values override all_agents
-            merged[:headers] = (merged[:headers] || {}).merge(value || {})
-          else
-            # For everything else, file value overrides all_agents value
-            merged[key] = value
-          end
-        end
-
-        # Pass all_agents permissions as default_permissions
-        if all_agents_hash[:permissions] && !merged[:default_permissions]
-          merged[:default_permissions] = all_agents_hash[:permissions]
-        end
-
-        merged
-      end
-
-      # Apply all_agents defaults to an agent builder
-      #
-      # Only sets values that haven't been explicitly set at the agent level.
-      # This implements the override semantics: agent values take precedence.
-      #
-      # @param agent_builder [Agent::Builder] The agent builder to configure
-      # @param all_agents_hash [Hash] All_agents configuration
-      # @return [void]
-      def apply_all_agents_defaults(agent_builder, all_agents_hash)
-        # Model: only set if agent hasn't explicitly set it
-        if all_agents_hash[:model] && !agent_builder.model_set?
-          agent_builder.model(all_agents_hash[:model])
-        end
-
-        # Provider: only set if agent hasn't set it
-        if all_agents_hash[:provider] && !agent_builder.provider_set?
-          agent_builder.provider(all_agents_hash[:provider])
-        end
-
-        # Base URL: only set if agent hasn't set it
-        if all_agents_hash[:base_url] && !agent_builder.base_url_set?
-          agent_builder.base_url(all_agents_hash[:base_url])
-        end
-
-        # API Version: only set if agent hasn't set it
-        if all_agents_hash[:api_version] && !agent_builder.api_version_set?
-          agent_builder.api_version(all_agents_hash[:api_version])
-        end
-
-        # Timeout: only set if agent hasn't set it
-        if all_agents_hash[:timeout] && !agent_builder.timeout_set?
-          agent_builder.timeout(all_agents_hash[:timeout])
-        end
-
-        # Parameters: merge (all_agents + agent, agent values override)
-        if all_agents_hash[:parameters]
-          merged_params = all_agents_hash[:parameters].merge(agent_builder.parameters)
-          agent_builder.parameters(merged_params)
-        end
-
-        # Headers: merge (all_agents + agent, agent values override)
-        if all_agents_hash[:headers]
-          merged_headers = all_agents_hash[:headers].merge(agent_builder.headers)
-          agent_builder.headers(merged_headers)
-        end
-
-        # Coding_agent: only set if agent hasn't set it
-        if !all_agents_hash[:coding_agent].nil? && !agent_builder.coding_agent_set?
-          agent_builder.coding_agent(all_agents_hash[:coding_agent])
-        end
-      end
-
       def apply_swarm_hook(swarm, config)
         event = config[:event]
 
@@ -564,7 +223,7 @@ module SwarmSDK
       end
 
       def build_hook_input(context, event)
-        # Build JSON input for shell hooks (similar to HooksAdapter)
+        # Build JSON input for shell hooks
         base = { event: event.to_s }
 
         case event
@@ -583,5 +242,8 @@ module SwarmSDK
         end
       end
     end
+
+    # Helper class for swarms block in DSL (kept in this file for reference)
+    # Actual implementation is in swarm_registry_builder.rb for Zeitwerk
   end
 end