swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/observer/manager.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Observer
+    # Manages observer agent executions
+    #
+    # Handles:
+    # - Event subscription via LogCollector
+    # - Spawning async tasks for observer agents
+    # - Self-consumption protection (observers don't trigger themselves)
+    # - Task lifecycle and cleanup
+    #
+    # @example
+    #   manager = Observer::Manager.new(swarm)
+    #   manager.add_config(profiler_config)
+    #   manager.setup
+    #   # ... main execution happens ...
+    #   manager.wait_for_completion
+    #   manager.cleanup
+    class Manager
+      # Initialize manager with swarm reference
+      #
+      # @param swarm [Swarm] Parent swarm instance
+      def initialize(swarm)
+        @swarm = swarm
+        @configs = []
+        @subscription_ids = []
+        @barrier = nil
+        @task_ids = {}
+      end
+
+      # Add an observer configuration
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @return [void]
+      def add_config(config)
+        @configs << config
+      end
+
+      # Setup event subscriptions for all observer configs
+      #
+      # Creates LogCollector subscriptions for each event type, filtered by type.
+      # Must be called after setup_logging() in Swarm.execute().
+      #
+      # @return [void]
+      def setup
+        @barrier = Async::Barrier.new
+
+        @configs.each do |config|
+          config.event_handlers.each do |event_type, handler|
+            sub_id = LogCollector.subscribe(filter: { type: event_type.to_s }) do |event|
+              handle_event(config, handler, event)
+            end
+            @subscription_ids << sub_id
+          end
+        end
+      end
+
+      # Wait for all observer tasks to complete
+      #
+      # Uses Async::Barrier.wait to wait for all spawned tasks.
+      # Handles errors gracefully without stopping other observers.
+      #
+      # @return [void]
+      def wait_for_completion
+        return unless @barrier
+
+        # Wait for all tasks, handling errors gracefully
+        # Barrier.wait re-raises first exception by default, so we use block form
+        @barrier.wait do |task|
+          task.wait
+        rescue StandardError => error
+          # Log but don't stop waiting for other observers
+          RubyLLM.logger.error("Observer task failed: #{error.message}")
+        end
+      end
+
+      # Cleanup all subscriptions
+      #
+      # Unsubscribes from LogCollector to prevent memory leaks.
+      # Called by Executor.cleanup_after_execution.
+      #
+      # @return [void]
+      def cleanup
+        @subscription_ids.each { |id| LogCollector.unsubscribe(id) }
+        @subscription_ids.clear
+      end
+
+      private
+
+      # Handle an incoming event
+      #
+      # Checks self-consumption protection, calls handler block,
+      # and spawns execution if handler returns a prompt.
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param handler [Proc] Event handler block
+      # @param event [Hash] Event data
+      # @return [void]
+      def handle_event(config, handler, event)
+        # CRITICAL: Prevent self-consumption - observer must not consume its own events
+        # This prevents infinite loops where an observer triggers itself
+        return if event[:agent] == config.agent_name
+
+        prompt = handler.call(event)
+        return unless prompt # nil means skip
+
+        spawn_execution(config, prompt, event)
+      end
+
+      # Spawn an async task for observer execution
+      #
+      # Creates a child async task via barrier for the observer agent.
+      # Sets observer-specific Fiber context.
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param prompt [String] Prompt to send to observer agent
+      # @param trigger_event [Hash] Event that triggered this execution
+      # @return [void]
+      def spawn_execution(config, prompt, trigger_event)
+        @barrier.async do
+          # Set observer-specific context in child fiber
+          # No need to restore - child fiber dies when task completes
+          Fiber[:swarm_id] = "#{Fiber[:swarm_id]}/observer:#{config.agent_name}"
+
+          execute_observer_agent(config, prompt, trigger_event)
+        end
+      end
+
+      # Execute the observer agent with the prompt
+      #
+      # Creates an isolated chat instance and sends the prompt.
+      # Emits lifecycle events (start, complete, error).
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param prompt [String] Prompt to execute
+      # @param trigger_event [Hash] Event that triggered this execution
+      # @return [RubyLLM::Message, nil] Response or nil on error
+      def execute_observer_agent(config, prompt, trigger_event)
+        agent_chat = create_isolated_chat(config.agent_name)
+
+        start_time = Time.now
+        emit_observer_start(config, trigger_event)
+
+        result = agent_chat.ask(prompt)
+
+        emit_observer_complete(config, trigger_event, result, Time.now - start_time)
+        result
+      rescue StandardError => e
+        emit_observer_error(config, trigger_event, e)
+        nil
+      end
+
+      # Create an isolated chat instance for the observer agent
+      #
+      # Uses AgentInitializer to create a fully configured agent chat
+      # without delegation tools (observers don't delegate).
+      #
+      # @param agent_name [Symbol] Name of the observer agent
+      # @return [Agent::Chat] Isolated chat instance
+      def create_isolated_chat(agent_name)
+        initializer = Swarm::AgentInitializer.new(@swarm)
+        initializer.initialize_isolated_agent(agent_name)
+      end
+
+      # Emit observer_agent_start event
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param trigger_event [Hash] Triggering event
+      # @return [void]
+      def emit_observer_start(config, trigger_event)
+        return unless LogStream.emitter
+
+        LogStream.emit(
+          type: "observer_agent_start",
+          agent: config.agent_name,
+          trigger_event: trigger_event[:type],
+          trigger_timestamp: trigger_event[:timestamp],
+          task_id: generate_task_id(config),
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
+
+      # Emit observer_agent_complete event
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param trigger_event [Hash] Triggering event
+      # @param result [RubyLLM::Message] Agent response
+      # @param duration [Float] Execution duration in seconds
+      # @return [void]
+      def emit_observer_complete(config, trigger_event, result, duration)
+        return unless LogStream.emitter
+
+        LogStream.emit(
+          type: "observer_agent_complete",
+          agent: config.agent_name,
+          trigger_event: trigger_event[:type],
+          task_id: generate_task_id(config),
+          duration: duration.round(3),
+          success: true,
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
+
+      # Emit observer_agent_error event
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @param trigger_event [Hash] Triggering event
+      # @param error [StandardError] Error that occurred
+      # @return [void]
+      def emit_observer_error(config, trigger_event, error)
+        return unless LogStream.emitter
+
+        LogStream.emit(
+          type: "observer_agent_error",
+          agent: config.agent_name,
+          trigger_event: trigger_event[:type],
+          task_id: generate_task_id(config),
+          error: error.message,
+          backtrace: error.backtrace&.first(5),
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
+
+      # Generate a unique task ID for an observer
+      #
+      # Cached per observer agent name for correlation.
+      #
+      # @param config [Observer::Config] Observer configuration
+      # @return [String] Task ID
+      def generate_task_id(config)
+        @task_ids[config.agent_name] ||= "observer_#{SecureRandom.hex(6)}"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/patterns/agent_observer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Patterns
+    # Observes another agent's actions with optional real-time processing
+    #
+    # @example Basic observation
+    #   observer = AgentObserver.new(target: :backend)
+    #   observer.start
+    #   swarm.execute("task")
+    #   observer.stop
+    #   puts observer.observations
+    #
+    # @example Real-time analysis
+    #   observer = AgentObserver.new(
+    #     target: :backend,
+    #     on_event: ->(e) { analyze_security(e) }
+    #   )
+    #
+    # @example Filter specific event types
+    #   observer = AgentObserver.new(
+    #     target: :backend,
+    #     event_types: ["tool_call", "tool_result"]
+    #   )
+    class AgentObserver
+      attr_reader :observations, :target_agent
+
+      # Initialize observer
+      #
+      # @param target [Symbol] Agent to observe
+      # @param event_types [Array<String>] Event types to capture (default: all)
+      # @param on_event [Proc] Optional callback for real-time processing
+      def initialize(target:, event_types: nil, on_event: nil)
+        @target_agent = target
+        @event_types = event_types
+        @on_event = on_event
+        @observations = []
+        @subscription_id = nil
+        @started_at = nil
+      end
+
+      # Start observing
+      #
+      # @return [void]
+      def start
+        return if @subscription_id
+
+        @started_at = Time.now
+        @observations.clear
+
+        filter = { agent: @target_agent }
+        filter[:type] = @event_types if @event_types
+
+        @subscription_id = LogCollector.subscribe(filter: filter) do |event|
+          @observations << event.merge(observed_at: Time.now)
+          @on_event&.call(event)
+        end
+      end
+
+      # Stop observing
+      #
+      # @return [void]
+      def stop
+        return unless @subscription_id
+
+        LogCollector.unsubscribe(@subscription_id)
+        @subscription_id = nil
+      end
+
+      # Check if currently observing
+      #
+      # @return [Boolean] true if actively observing
+      def observing?
+        !@subscription_id.nil?
+      end
+
+      # Get summary of observations
+      #
+      # @return [Hash] Summary statistics
+      def summary
+        {
+          target: @target_agent,
+          started_at: @started_at,
+          duration_seconds: @started_at ? (Time.now - @started_at).round(2) : 0,
+          total_events: @observations.size,
+          event_breakdown: @observations.group_by { |e| e[:type] }.transform_values(&:count),
+          tool_calls: @observations.select { |e| e[:type] == "tool_call" }.map { |e| e[:tool_name] },
+          errors: @observations.select { |e| e[:type] == "internal_error" },
+        }
+      end
+
+      # Format observations for LLM consumption
+      #
+      # Useful for providing observation data to another agent for analysis
+      #
+      # @return [String] Formatted observation log
+      def to_llm_context
+        @observations.map do |event|
+          case event[:type]
+          when "tool_call"
+            "- Called #{event[:tool_name]} with: #{truncate_json(event[:arguments])}"
+          when "tool_result"
+            "- #{event[:tool_name]} returned: #{truncate(event[:result])}"
+          when "agent_step"
+            "- Thinking: #{truncate(event[:content])}"
+          when "agent_stop"
+            "- Final response: #{truncate(event[:content])}"
+          else
+            "- [#{event[:type]}] #{event.except(:type, :timestamp, :observed_at).to_json}"
+          end
+        end.join("\n")
+      end
+
+      # Clear collected observations
+      #
+      # @return [void]
+      def clear_observations
+        @observations.clear
+      end
+
+      # Execute block while observing
+      #
+      # Automatically starts and stops observation around the block
+      #
+      # @example
+      #   observer = AgentObserver.new(target: :backend)
+      #   observer.observe do
+      #     swarm.execute("Build API")
+      #   end
+      #   puts observer.summary
+      #
+      # @yield Block to execute while observing
+      # @return [Object] Result from the block
+      def observe
+        start
+        yield
+      ensure
+        stop
+      end
+
+      private
+
+      def truncate(text, max_length = 200)
+        return "" if text.nil?
+
+        text = text.to_s
+        return text if text.length <= max_length
+
+        "#{text[0...max_length]}..."
+      end
+
+      def truncate_json(obj, max_length = 100)
+        return "{}" if obj.nil?
+
+        json = obj.to_json
+        truncate(json, max_length)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/plugin.rb

@@ -10,7 +10,7 @@ module SwarmSDK
   # ## Adding Custom Attributes to Agents
   #
   # Plugins can add custom attributes to Agent::Definition that are preserved
-  # when agents are cloned (e.g., in NodeOrchestrator). To do this:
+  # when agents are cloned (e.g., in Workflow). To do this:
   #
   # 1. Add attr_reader to Agent::Definition for your attribute
   # 2. Parse the attribute in Agent::Definition#initialize
@@ -62,7 +62,7 @@ module SwarmSDK
   #     my_custom_config { option: "value" }
   #   end
   #
-  # And it will be preserved when NodeOrchestrator clones the agent!
+  # And it will be preserved when Workflow clones the agent!
   #
   # @example Real-world: SwarmMemory plugin
   #   # SwarmMemory adds 'memory' attribute to agents
@@ -197,7 +197,7 @@ module SwarmSDK
     # Contribute to agent serialization (optional)
     #
     # Called when Agent::Definition.to_h is invoked (e.g., for cloning agents
-    # in NodeOrchestrator). Plugins can return config keys that should be
+    # in Workflow). Plugins can return config keys that should be
     # included in the serialized hash to preserve their state.
     #
     # This allows plugins to maintain their configuration when agents are
@@ -215,5 +215,95 @@ module SwarmSDK
     def serialize_config(agent_definition:)
       {}
     end
+
+    # Snapshot plugin-specific state for an agent
+    #
+    # Called during state snapshot creation (e.g., session persistence).
+    # Return any state your plugin needs to persist for this agent.
+    # The returned hash will be JSON serialized.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @return [Hash] Plugin-specific state (empty hash if nothing to snapshot)
+    #
+    # @example Memory read tracking
+    #   def snapshot_agent_state(agent_name)
+    #     entries = StorageReadTracker.get_read_entries(agent_name)
+    #     return {} if entries.empty?
+    #
+    #     { read_entries: entries }
+    #   end
+    def snapshot_agent_state(agent_name)
+      {}
+    end
+
+    # Restore plugin-specific state for an agent
+    #
+    # Called during state restoration. Restore any persisted state.
+    # This method is idempotent - calling it multiple times with
+    # the same state should produce the same result.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param state [Hash] Previously snapshotted state (with symbol keys)
+    # @return [void]
+    #
+    # @example Memory read tracking
+    #   def restore_agent_state(agent_name, state)
+    #     entries = state[:read_entries] || state["read_entries"]
+    #     return unless entries
+    #
+    #     StorageReadTracker.restore_read_entries(agent_name, entries)
+    #   end
+    def restore_agent_state(agent_name, state)
+      # Override if needed
+    end
+
+    # Get digest for a tool result (e.g., file hash, memory entry hash)
+    #
+    # Called during tool result metadata collection. Returns a digest
+    # that can be used to detect if the resource has changed since
+    # it was last read. This enables change detection hooks.
+    #
+    # @param agent_name [Symbol] Agent identifier
+    # @param tool_name [String] Name of the tool (e.g., "MemoryRead")
+    # @param path [String] Path or identifier of the resource
+    # @return [String, nil] Digest string or nil if not tracked by this plugin
+    #
+    # @example Memory read tracking
+    #   def get_tool_result_digest(agent_name:, tool_name:, path:)
+    #     return unless tool_name == "MemoryRead"
+    #
+    #     StorageReadTracker.get_read_entries(agent_name)[path]
+    #   end
+    def get_tool_result_digest(agent_name:, tool_name:, path:)
+      nil
+    end
+
+    # Translate YAML configuration into DSL calls
+    #
+    # Called during YAML-to-DSL translation. Plugins can translate their
+    # specific YAML configuration keys into DSL method calls on the builder.
+    # This allows SDK to remain plugin-agnostic while plugins can add
+    # YAML configuration support.
+    #
+    # @param builder [Agent::Builder] Builder instance (self in DSL context)
+    # @param agent_config [Hash] Full agent config from YAML
+    # @return [void]
+    #
+    # @example Memory plugin YAML translation
+    #   def translate_yaml_config(builder, agent_config)
+    #     memory_config = agent_config[:memory]
+    #     return unless memory_config
+    #
+    #     builder.instance_eval do
+    #       memory do
+    #         directory(memory_config[:directory])
+    #         adapter(memory_config[:adapter]) if memory_config[:adapter]
+    #         mode(memory_config[:mode]) if memory_config[:mode]
+    #       end
+    #     end
+    #   end
+    def translate_yaml_config(builder, agent_config)
+      # Override if plugin needs YAML configuration support
+    end
   end
 end

data/lib/swarm_sdk/snapshot.rb

@@ -102,7 +102,7 @@ module SwarmSDK
       @data[:version] || @data["version"]
     end
 
-    # Get snapshot type (swarm or node_orchestrator)
+    # Get snapshot type (swarm or workflow)
     #
     # @return [String] Snapshot type
     def type
@@ -139,18 +139,18 @@ module SwarmSDK
       delegations ? delegations.keys.map(&:to_s) : []
     end
 
-    # Check if snapshot is for a swarm (vs node_orchestrator)
+    # Check if snapshot is for a swarm (vs workflow)
     #
     # @return [Boolean] true if swarm snapshot
     def swarm?
       type == "swarm"
     end
 
-    # Check if snapshot is for a node orchestrator
+    # Check if snapshot is for a workflow
     #
-    # @return [Boolean] true if node orchestrator snapshot
-    def node_orchestrator?
-      type == "node_orchestrator"
+    # @return [Boolean] true if workflow snapshot
+    def workflow?
+      type == "workflow"
     end
   end
 end

data/lib/swarm_sdk/snapshot_from_events.rb

@@ -69,16 +69,17 @@ module SwarmSDK
     # @return [Hash] StateSnapshot hash
     def reconstruct
       {
-        version: "1.0.0",
+        version: "2.1.0",
         type: "swarm",
         snapshot_at: @events.last&.fetch(:timestamp, Time.now.utc.iso8601),
         swarm_sdk_version: SwarmSDK::VERSION,
-        swarm: reconstruct_swarm_metadata,
+        metadata: reconstruct_swarm_metadata,
         agents: reconstruct_all_agents,
         delegation_instances: reconstruct_all_delegations,
         scratchpad: reconstruct_scratchpad,
         read_tracking: reconstruct_read_tracking,
         memory_read_tracking: reconstruct_memory_read_tracking,
+        plugin_states: reconstruct_plugin_states,
       }
     end
 
@@ -363,6 +364,16 @@ module SwarmSDK
       tracking
     end
 
+    # Reconstruct plugin states
+    #
+    # Plugin states cannot be fully reconstructed from events alone as they
+    # contain internal plugin data. Returns empty hash for compatibility.
+    #
+    # @return [Hash] Empty plugin states hash
+    def reconstruct_plugin_states
+      {}
+    end
+
     # Parse timestamp string to Time object
     #
     # @param timestamp [String, nil] ISO 8601 timestamp