swarm_sdk 2.6.2 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23d75c935c390ebae6b26d6d1c39e246d4b5a6c8cabec7876e92ca9c03daede1
-  data.tar.gz: e286c53432c5c56bfaf25f9ddb0f84b3f9600cb6bd5554cfc601ad317bdbf1cc
+  metadata.gz: ef0eb1b3b6d3a5ac2eba62e62c37ed6bbbcb69708b0c98e235ec67986081f19a
+  data.tar.gz: 9d1189a686c272d2b06c9caf93772a10bec51cc7377b3899e861ac348776c835
 SHA512:
-  metadata.gz: 54e20c520a97150fdcb3f6b2bdc59539021245e886b7f8f8d9ff8a264ab3ca94162ef3f57015dbb896dc097698f33c4d2f848a0a661fb9b008116df1995b3775
-  data.tar.gz: 39e7353bd1ebf89ab6eea038b0829103bb5bcc9a2405cdd98ba56a8a3082350f1f2c5e449f2141de2a1de281d786483e0e7cb34adef9079a037b16694a89cec5
+  metadata.gz: 06565a32cd96de20a6e6cba46ff1df1e61f876e4e293e150e556277e8d4675a1f92332fd2ed76348e8b0b8d102867039099a2683b705e0658f4f2e05e032c40c
+  data.tar.gz: 77853dd26169adca4274979b1f602b3b6de14cbbf3951f2bdea3df890895ba188a5a7f865217dae5e09f7cba4554f35054908d074249ed0e34cf46929bbd7e64

data/lib/swarm_sdk/agent/builder.rb

@@ -61,6 +61,7 @@ module SwarmSDK
         @default_permissions = {} # Set by SwarmBuilder from all_agents
         @memory_config = nil
         @shared_across_delegations = nil # nil = not set (will default to false in Definition)
+        @streaming = nil # nil = not set (will use global config default)
         @context_management_config = nil # Context management DSL hooks
       end
 
@@ -129,9 +130,17 @@ module SwarmSDK
 
       # Add an MCP server configuration
       #
-      # @example stdio transport
+      # @param name [Symbol] Server name
+      # @param type [Symbol] Transport type (:stdio, :sse, :http)
+      # @param tools [Array<Symbol>, nil] Tool names to expose (nil = discover all tools)
+      # @param options [Hash] Transport-specific options
+      #
+      # @example stdio transport with discovery
       #   mcp_server :filesystem, type: :stdio, command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]
       #
+      # @example stdio transport with filtered tools (faster boot)
+      #   mcp_server :codebase, type: :stdio, command: "mcp-server-codebase", tools: [:search_code, :list_files]
+      #
       # @example SSE transport
       #   mcp_server :web, type: :sse, url: "https://example.com/mcp", headers: { authorization: "Bearer token" }
       #
@@ -328,6 +337,28 @@ module SwarmSDK
         self
       end
 
+      # Enable or disable streaming for LLM API responses
+      #
+      # @param value [Boolean] If true (default), enables streaming; if false, disables it
+      # @return [self] Returns self for method chaining
+      #
+      # @example Enable streaming (default)
+      #   streaming true
+      #
+      # @example Disable streaming
+      #   streaming false
+      def streaming(value = true)
+        @streaming = value
+        self
+      end
+
+      # Check if streaming has been explicitly set
+      #
+      # @return [Boolean] true if streaming was explicitly set, false otherwise
+      def streaming_set?
+        !@streaming.nil?
+      end
+
       # Configure context management handlers
       #
       # Define custom handlers for context warning thresholds (60%, 80%, 90%).
@@ -507,6 +538,7 @@ module SwarmSDK
         agent_config[:default_permissions] = @default_permissions if @default_permissions.any?
         agent_config[:memory] = @memory_config if @memory_config
         agent_config[:shared_across_delegations] = @shared_across_delegations unless @shared_across_delegations.nil?
+        agent_config[:streaming] = @streaming unless @streaming.nil?
 
         # Convert DSL hooks to HookDefinition format
         agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?

data/lib/swarm_sdk/agent/chat.rb

@@ -99,7 +99,8 @@ module SwarmSDK
         :context_manager,
         :agent_context,
         :last_todowrite_message_index,
-        :active_skill_path,
+        :tool_registry,
+        :skill_state,
         :provider # Extracted from RubyLLM::Chat for instrumentation (not publicly accessible)
 
       # Setters for snapshot/restore
@@ -134,6 +135,10 @@ module SwarmSDK
         # Turn timeout (external timeout for entire ask() call)
         @turn_timeout = definition[:turn_timeout]
 
+        # Streaming configuration
+        @streaming_enabled = definition[:streaming]
+        @last_chunk_type = nil # Track chunk type transitions
+
         # Context manager for ephemeral messages
         @context_manager = ContextManager.new
 
@@ -153,11 +158,15 @@ module SwarmSDK
         # Context tracker (created after agent_context is set)
         @context_tracker = nil
 
-        # Track immutable tools
-        @immutable_tool_names = Set.new(["Think", "Clock", "TodoWrite"])
+        # Tool registry for lazy tool activation (Phase 3 - Plan 025)
+        @tool_registry = Agent::ToolRegistry.new
+
+        # Track loaded skill state (Phase 2 - Plan 025)
+        @skill_state = nil
 
-        # Track active skill (only used if memory enabled)
-        @active_skill_path = nil
+        # Tool activation dependencies (set by setup_tool_activation after initialization)
+        @tool_configurator = nil
+        @agent_definition = nil
 
         # Create internal RubyLLM::Chat instance
         @llm_chat = create_llm_chat(
@@ -233,11 +242,28 @@ module SwarmSDK
       # Use with caution - prefer has_tool?, tool_names, remove_tool for most cases.
       # This is provided for:
       # - Direct tool execution in tests
-      # - Advanced tool manipulation (remove_mutable_tools)
+      # - Advanced tool manipulation
       #
-      # @return [Hash] Tool name to tool instance mapping
+      # Returns a hash wrapper that supports both string and symbol keys for test convenience.
+      #
+      # @return [Hash] Tool name to tool instance mapping (supports symbol and string keys)
       def tools
-        @llm_chat.tools
+        # Return a fresh wrapper each time (since @llm_chat.tools may change)
+        SymbolKeyHash.new(@llm_chat.tools)
+      end
+
+      # Hash wrapper that supports both string and symbol keys
+      #
+      # This allows tests to use tools[:ToolName] or tools["ToolName"]
+      # while RubyLLM internally uses string keys.
+      class SymbolKeyHash < SimpleDelegator
+        def [](key)
+          __getobj__[key.to_s] || __getobj__[key.to_sym]
+        end
+
+        def key?(key)
+          __getobj__.key?(key.to_s) || __getobj__.key?(key.to_sym)
+        end
       end
 
       # Message introspection
@@ -341,6 +367,18 @@ module SwarmSDK
         inject_llm_instrumentation
       end
 
+      # Setup tool activation dependencies (Plan 025)
+      #
+      # Must be called after tool registration to enable permission wrapping during activation.
+      #
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @param agent_definition [Agent::Definition] Agent definition object
+      # @return [void]
+      def setup_tool_activation(tool_configurator:, agent_definition:)
+        @tool_configurator = tool_configurator
+        @agent_definition = agent_definition
+      end
+
       # Emit model lookup warning if one occurred during initialization
       #
       # @param agent_name [Symbol, String] The agent name for logging context
@@ -410,33 +448,33 @@ module SwarmSDK
         end
       end
 
-      # Mark tools as immutable (cannot be removed by dynamic tool swapping)
-      #
-      # @param tool_names [Array<String>] Tool names to mark as immutable
-      def mark_tools_immutable(*tool_names)
-        @immutable_tool_names.merge(tool_names.flatten.map(&:to_s))
-      end
-
-      # Remove all mutable tools (keeps immutable tools)
+      # Load skill state (called by LoadSkill tool)
       #
+      # @param state [Object, nil] Skill state object (from SwarmMemory), or nil to clear
       # @return [void]
-      def remove_mutable_tools
-        mutable_tool_names = tools.keys.reject { |name| @immutable_tool_names.include?(name.to_s) }
-        mutable_tool_names.each { |name| tools.delete(name) }
+      def load_skill_state(state)
+        @skill_state = state
       end
 
-      # Mark skill as loaded (tracking for debugging/logging)
+      # Clear loaded skill (return to all tools)
       #
-      # @param file_path [String] Path to loaded skill
-      def mark_skill_loaded(file_path)
-        @active_skill_path = file_path
+      # @return [void]
+      def clear_skill
+        @skill_state = nil
       end
 
       # Check if a skill is currently loaded
       #
       # @return [Boolean] True if a skill has been loaded
       def skill_loaded?
-        !@active_skill_path.nil?
+        !@skill_state.nil?
+      end
+
+      # Get active skill path (for backward compatibility)
+      #
+      # @return [String, nil] Path to loaded skill
+      def active_skill_path
+        @skill_state&.file_path
       end
 
       # Clear conversation history
@@ -447,6 +485,33 @@ module SwarmSDK
         @context_manager&.clear_ephemeral
       end
 
+      # Activate tools for the current prompt (Plan 025: Lazy Tool Activation)
+      #
+      # Called before each LLM request to set active toolset based on skill state.
+      # Replaces @llm_chat.tools with active subset from registry.
+      #
+      # This is public so it can be called during initialization to populate tools.
+      #
+      # Logic:
+      # - If no skill loaded: ALL tools from registry
+      # - If skill restricts tools: skill's tools + non-removable tools
+      # - Skill permissions applied during activation (wrapping base_instance)
+      #
+      # @return [void]
+      def activate_tools_for_prompt
+        # Get active tools based on skill state
+        active = @tool_registry.active_tools(
+          skill_state: @skill_state,
+          tool_configurator: @tool_configurator,
+          agent_definition: @agent_definition,
+        )
+
+        # Replace RubyLLM::Chat tools with active subset
+        # CRITICAL: RubyLLM looks up tools by SYMBOL keys, must store with symbols!
+        @llm_chat.tools.clear
+        active.each { |name, instance| @llm_chat.tools[name.to_sym] = instance }
+      end
+
       # --- Core Conversation Methods ---
 
       # Send a message to the LLM and get a response
@@ -613,7 +678,15 @@ module SwarmSDK
         response = execute_with_global_semaphore do
           catch(:finish_agent) do
             catch(:finish_swarm) do
-              @llm_chat.complete(**options)
+              if @streaming_enabled
+                # Reset chunk type tracking for new streaming request
+                @last_chunk_type = nil
+                @llm_chat.complete(**options) do |chunk|
+                  emit_content_chunk(chunk)
+                end
+              else
+                @llm_chat.complete(**options)
+              end
             end
           end
         end
@@ -703,25 +776,30 @@ module SwarmSDK
       # Setup around_llm_request hook for ephemeral message injection
       #
       # This hook intercepts all LLM API calls to:
+      # - Activate tools based on skill state (Plan 025: Lazy Tool Activation)
       # - Inject ephemeral content (system reminders) that shouldn't be persisted
       # - Clear ephemeral content after each LLM call
       # - Add retry logic for transient failures
       def setup_llm_request_hook
         @llm_chat.around_llm_request do |_messages, &send_request|
+          # Activate tools for this LLM request (Plan 025)
+          # This happens before each LLM request to ensure tools match current skill state
+          activate_tools_for_prompt
+
           # Make the actual LLM API call with retry logic
           # NOTE: prepare_for_llm must be called INSIDE the retry block so that
           # ephemeral content is recalculated after orphan tool call pruning
-          response = call_llm_with_retry do
-            # Inject ephemeral content fresh for each attempt
-            # Use @llm_chat.messages to get current state (may have been modified by pruning)
-            prepared_messages = @context_manager.prepare_for_llm(@llm_chat.messages)
-            send_request.call(prepared_messages)
+          begin
+            call_llm_with_retry do
+              # Inject ephemeral content fresh for each attempt
+              # Use @llm_chat.messages to get current state (may have been modified by pruning)
+              prepared_messages = @context_manager.prepare_for_llm(@llm_chat.messages)
+              send_request.call(prepared_messages)
+            end
+          ensure
+            # Always clear ephemeral content, even if streaming fails
+            @context_manager.clear_ephemeral
           end
-
-          # Clear ephemeral content after successful call
-          @context_manager.clear_ephemeral
-
-          response
         end
       end
 
@@ -1037,6 +1115,72 @@ module SwarmSDK
         )
       end
 
+      # Emit content_chunk event during streaming
+      #
+      # This method is called for each chunk received during streaming.
+      # It emits a content_chunk event with the chunk's content and metadata.
+      #
+      # Additionally detects transitions from content → tool_call chunks and emits
+      # a separator event to help UI layers distinguish "thinking" from tool execution.
+      #
+      # IMPORTANT: chunk.tool_calls contains PARTIAL data during streaming:
+      # - tool_call.id and tool_call.name are available once the tool call starts
+      # - tool_call.arguments are RAW STRING FRAGMENTS, not parsed JSON
+      # Users should use `tool_call` events (after streaming) for complete data.
+      #
+      # @param chunk [RubyLLM::Chunk] A streaming chunk from the LLM
+      # @return [void]
+      def emit_content_chunk(chunk)
+        # Determine chunk type using RubyLLM's tool_call? method
+        # Content and tool_calls are mutually exclusive in chunks
+        is_tool_call_chunk = chunk.tool_call?
+        has_content = !chunk.content.nil?
+
+        # Only emit if there's content or tool calls
+        return unless is_tool_call_chunk || has_content
+
+        # Detect transition from content chunks to tool_call chunks
+        # This happens when the LLM finishes "thinking" text and starts calling tools
+        current_chunk_type = is_tool_call_chunk ? "tool_call" : "content"
+        if @last_chunk_type == "content" && current_chunk_type == "tool_call"
+          # Emit separator event to signal end of thinking text
+          LogStream.emit(
+            type: "content_chunk",
+            agent: @agent_name,
+            chunk_type: "separator",
+            content: nil,
+            tool_calls: nil,
+            model: chunk.model_id,
+          )
+        end
+        @last_chunk_type = current_chunk_type
+
+        # Transform tool_calls to serializable format
+        # NOTE: arguments are partial strings during streaming!
+        tool_calls_data = if is_tool_call_chunk
+          chunk.tool_calls.transform_values do |tc|
+            {
+              id: tc.id,
+              name: tc.name,
+              arguments: tc.arguments, # PARTIAL string fragments!
+            }
+          end
+        end
+
+        LogStream.emit(
+          type: "content_chunk",
+          agent: @agent_name,
+          chunk_type: current_chunk_type,
+          content: chunk.content,
+          tool_calls: tool_calls_data,
+          model: chunk.model_id,
+        )
+      rescue StandardError => e
+        # Never interrupt streaming due to event emission failure
+        # LogCollector already isolates subscriber errors, but we're defensive here
+        RubyLLM.logger.error("SwarmSDK: Failed to emit content_chunk: #{e.message}")
+      end
+
       # Recover from 400 Bad Request by pruning orphan tool calls
       #
       # @param error [RubyLLM::BadRequestError] The error that occurred

data/lib/swarm_sdk/agent/definition.rb

@@ -41,7 +41,8 @@ module SwarmSDK
         :assume_model_exists,
         :hooks,
         :plugin_configs,
-        :shared_across_delegations
+        :shared_across_delegations,
+        :streaming
 
       attr_accessor :bypass_permissions, :max_concurrent_tools
 
@@ -110,6 +111,9 @@ module SwarmSDK
         # Delegation isolation mode (default: false = isolated instances per delegation)
         @shared_across_delegations = config[:shared_across_delegations] || false
 
+        # Streaming configuration (default: true from global config)
+        @streaming = config.fetch(:streaming, SwarmSDK.config.streaming)
+
         # Build system prompt after directory and memory are set
         @system_prompt = build_full_system_prompt(config[:system_prompt])
 
@@ -192,6 +196,7 @@ module SwarmSDK
           max_concurrent_tools: @max_concurrent_tools,
           hooks: @hooks,
           shared_across_delegations: @shared_across_delegations,
+          streaming: @streaming,
           # Permissions are core SDK functionality (not plugin-specific)
           default_permissions: @default_permissions,
           permissions: @agent_permissions,
@@ -379,6 +384,7 @@ module SwarmSDK
           :default_permissions,
           :permissions,
           :shared_across_delegations,
+          :streaming,
           :directories,
         ]
 

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -33,17 +33,39 @@ module SwarmSDK
       # @return [Faraday::Response] HTTP response
       def call(env)
         start_time = Time.now
+        accumulated_raw_chunks = []
 
         # Emit request event
         emit_request_event(env, start_time)
 
+        # Wrap existing on_data to capture raw SSE chunks for streaming
+        # This allows us to capture the full streaming response for instrumentation
+        # Check if env.request exists and has on_data (only set for streaming requests)
+        if env.request&.on_data
+          original_on_data = env.request.on_data
+          env.request.on_data = proc do |chunk, bytes, response_env|
+            # Capture raw chunk BEFORE RubyLLM processes it
+            accumulated_raw_chunks << chunk
+            # Call original handler (RubyLLM's stream processing)
+            original_on_data.call(chunk, bytes, response_env)
+          end
+        end
+
         # Execute request
         @app.call(env).on_complete do |response_env|
           end_time = Time.now
           duration = end_time - start_time
 
+          # For streaming: use accumulated raw SSE chunks
+          # For non-streaming: use response body
+          raw_body = if accumulated_raw_chunks.any?
+            accumulated_raw_chunks.join
+          else
+            response_env.body
+          end
+
           # Emit response event
-          emit_response_event(response_env, start_time, end_time, duration)
+          emit_response_event(response_env, start_time, end_time, duration, raw_body)
         end
       end
 
@@ -74,22 +96,40 @@ module SwarmSDK
       # @param start_time [Time] Request start time
       # @param end_time [Time] Request end time
       # @param duration [Float] Request duration in seconds
+      # @param raw_body [String, nil] Raw response body (SSE stream for streaming, JSON for non-streaming)
       # @return [void]
-      def emit_response_event(env, start_time, end_time, duration)
+      def emit_response_event(env, start_time, end_time, duration, raw_body)
+        # Detect if this is a streaming response (starts with "data:")
+        streaming = raw_body.is_a?(String) && raw_body.start_with?("data:")
+
         response_data = {
           provider: @provider_name,
-          body: parse_body(env.body),
+          body: parse_body(raw_body),
+          streaming: streaming,
           duration_seconds: duration.round(3),
           timestamp: end_time.utc.iso8601,
+          status: env.status,
         }
 
         # Extract usage information from response body if available
-        if env.body.is_a?(String) && !env.body.empty?
+        if raw_body.is_a?(String) && !raw_body.empty?
           begin
-            parsed = JSON.parse(env.body)
-            response_data[:usage] = extract_usage(parsed) if parsed.is_a?(Hash)
-            response_data[:model] = parsed["model"] if parsed.is_a?(Hash)
-            response_data[:finish_reason] = extract_finish_reason(parsed) if parsed.is_a?(Hash)
+            if streaming
+              # For streaming, parse the LAST SSE event which contains usage
+              # Skip "[DONE]" marker and find the last actual data event
+              last_data_line = raw_body.split("\n").reverse.find { |l| l.start_with?("data:") && !l.include?("[DONE]") }
+              if last_data_line
+                parsed = JSON.parse(last_data_line.sub(/^data:\s*/, ""))
+                response_data[:usage] = extract_usage(parsed) if parsed.is_a?(Hash)
+                response_data[:model] = parsed["model"] if parsed.is_a?(Hash)
+              end
+            else
+              # For non-streaming, parse the full JSON response
+              parsed = JSON.parse(raw_body)
+              response_data[:usage] = extract_usage(parsed) if parsed.is_a?(Hash)
+              response_data[:model] = parsed["model"] if parsed.is_a?(Hash)
+              response_data[:finish_reason] = extract_finish_reason(parsed) if parsed.is_a?(Hash)
+            end
           rescue JSON::ParserError
             # Not JSON, skip usage extraction
           end