ruby-mcp-client 0.9.0 → 1.0.0

data/lib/mcp_client/audio_content.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Representation of MCP audio content (MCP 2025-11-25)
+  # Used for base64-encoded audio data in messages and tool results
+  class AudioContent
+    # @!attribute [r] data
+    #   @return [String] base64-encoded audio data
+    # @!attribute [r] mime_type
+    #   @return [String] MIME type of the audio (e.g., 'audio/wav', 'audio/mpeg', 'audio/ogg')
+    # @!attribute [r] annotations
+    #   @return [Hash, nil] optional annotations that provide hints to clients
+    attr_reader :data, :mime_type, :annotations
+
+    # Initialize audio content
+    # @param data [String] base64-encoded audio data
+    # @param mime_type [String] MIME type of the audio
+    # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    def initialize(data:, mime_type:, annotations: nil)
+      raise ArgumentError, 'AudioContent requires data' if data.nil? || data.empty?
+      raise ArgumentError, 'AudioContent requires mime_type' if mime_type.nil? || mime_type.empty?
+
+      @data = data
+      @mime_type = mime_type
+      @annotations = annotations
+    end
+
+    # Create an AudioContent instance from JSON data
+    # @param data [Hash] JSON data from MCP server
+    # @return [MCPClient::AudioContent] audio content instance
+    def self.from_json(json_data)
+      new(
+        data: json_data['data'],
+        mime_type: json_data['mimeType'],
+        annotations: json_data['annotations']
+      )
+    end
+
+    # Get the decoded audio content
+    # @return [String] decoded binary audio data
+    def content
+      require 'base64'
+      Base64.decode64(@data)
+    end
+  end
+end

data/lib/mcp_client/client.rb

@@ -16,13 +16,17 @@ module MCPClient
     #   @return [Hash<String, MCPClient::Resource>] cache of resources by composite key (server_id:uri)
     # @!attribute [r] logger
     #   @return [Logger] logger for client operations
-    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger
+    # @!attribute [r] roots
+    #   @return [Array<MCPClient::Root>] list of MCP roots (MCP 2025-06-18)
+    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger, :roots
 
     # Initialize a new MCPClient::Client
     # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
     # @param elicitation_handler [Proc, nil] optional handler for elicitation requests (MCP 2025-06-18)
-    def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil)
+    # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
+    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25)
+    def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil)
       @logger = logger || Logger.new($stdout, level: Logger::WARN)
       @logger.progname = self.class.name
       @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
@@ -37,6 +41,10 @@ module MCPClient
       @notification_listeners = []
       # Elicitation handler (MCP 2025-06-18)
       @elicitation_handler = elicitation_handler
+      # Sampling handler (MCP 2025-11-25)
+      @sampling_handler = sampling_handler
+      # Roots (MCP 2025-06-18)
+      @roots = normalize_roots(roots)
       # Register default and user-defined notification handlers on each server
       @servers.each do |server|
         server.on_notification do |method, params|
@@ -49,6 +57,10 @@ module MCPClient
         if server.respond_to?(:on_elicitation_request)
           server.on_elicitation_request(&method(:handle_elicitation_request))
         end
+        # Register roots list handler on each server (MCP 2025-06-18)
+        server.on_roots_list_request(&method(:handle_roots_list_request)) if server.respond_to?(:on_roots_list_request)
+        # Register sampling handler on each server (MCP 2025-11-25)
+        server.on_sampling_request(&method(:handle_sampling_request)) if server.respond_to?(:on_sampling_request)
       end
     end
 
@@ -330,6 +342,16 @@ module MCPClient
       @notification_listeners << block
     end
 
+    # Set the roots for this client (MCP 2025-06-18)
+    # When roots are changed, a notification is sent to all connected servers
+    # @param new_roots [Array<MCPClient::Root, Hash>] the new roots to set
+    # @return [void]
+    def roots=(new_roots)
+      @roots = normalize_roots(new_roots)
+      # Notify servers that roots have changed
+      notify_roots_changed
+    end
+
     # Find a server by name
     # @param name [String] the name of the server to find
     # @return [MCPClient::ServerBase, nil] the server with the given name, or nil if not found
@@ -353,8 +375,10 @@ module MCPClient
     end
 
     # Call multiple tools in batch
-    # @param calls [Array<Hash>] array of calls in the form:
-    #   { name: tool_name, parameters: {...}, server: optional_server_name }
+    # @param calls [Array<Hash>] array of call hashes with keys:
+    #   - name: tool name (required)
+    #   - parameters: tool parameters (optional, default empty hash)
+    #   - server: server name for routing (optional)
     # @return [Array<Object>] array of results for each tool invocation
     def call_tools(calls)
       calls.map do |call|
@@ -459,6 +483,100 @@ module MCPClient
       srv.rpc_notify(method, params)
     end
 
+    # Request completion suggestions from a server (MCP 2025-06-18)
+    # @param ref [Hash] reference object (e.g., { 'type' => 'ref/prompt', 'name' => 'prompt_name' })
+    # @param argument [Hash] the argument being completed (e.g., { 'name' => 'arg_name', 'value' => 'partial' })
+    # @param context [Hash, nil] optional context for the completion (MCP 2025-11-25),
+    #   e.g., { 'arguments' => { 'arg1' => 'value1' } } for previously-resolved arguments
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def complete(ref:, argument:, context: nil, server: nil)
+      srv = select_server(server)
+      srv.complete(ref: ref, argument: argument, context: context)
+    end
+
+    # Create a new task on a server (MCP 2025-11-25)
+    # Tasks represent long-running operations that can report progress
+    # @param method [String] the method to execute as a task
+    # @param params [Hash] parameters for the task method
+    # @param progress_token [String, nil] optional token for receiving progress notifications
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the created task
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskError] if task creation fails
+    def create_task(method, params: {}, progress_token: nil, server: nil)
+      srv = select_server(server)
+      rpc_params = { method: method, params: params }
+      rpc_params[:progressToken] = progress_token if progress_token
+
+      begin
+        result = srv.rpc_request('tasks/create', rpc_params)
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error creating task: #{e.message}"
+      end
+    end
+
+    # Get the current state of a task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to query
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with current state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
+    def get_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/get', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # Cancel a running task (MCP 2025-11-25)
+    # @param task_id [String] the ID of the task to cancel
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [MCPClient::Task] the task with updated (cancelled) state
+    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
+    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
+    # @raise [MCPClient::Errors::TaskError] if cancellation fails
+    def cancel_task(task_id, server: nil)
+      srv = select_server(server)
+
+      begin
+        result = srv.rpc_request('tasks/cancel', { id: task_id })
+        MCPClient::Task.from_json(result, server: srv)
+      rescue MCPClient::Errors::ServerError => e
+        if e.message.include?('not found') || e.message.include?('unknown task')
+          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        end
+
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # Set the logging level on all connected servers (MCP 2025-06-18)
+    # To set on a specific server, use: client.find_server('name').log_level = 'debug'
+    # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
+    #   'critical', 'alert', 'emergency')
+    # @return [Array<Hash>] results from servers
+    # @raise [MCPClient::Errors::ServerError] if server returns an error
+    def log_level=(level)
+      @servers.map { |srv| srv.log_level = level }
+    end
+
     private
 
     # Process incoming JSON-RPC notifications with default handlers
@@ -480,12 +598,43 @@ module MCPClient
       when 'notifications/resources/list_changed'
         logger.warn("[#{server_id}] Resource list has changed, clearing resource cache")
         @resource_cache.clear
+      when 'notifications/message'
+        # MCP 2025-06-18: Handle logging messages from server
+        handle_log_message(server_id, params)
       else
         # Log unknown notification types for debugging purposes
         logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
       end
     end
 
+    # Handle logging message notification from server (MCP 2025-06-18)
+    # @param server_id [String] server identifier for log prefix
+    # @param params [Hash] log message params (level, logger, data)
+    # @return [void]
+    def handle_log_message(server_id, params)
+      level = params['level'] || 'info'
+      logger_name = params['logger']
+      data = params['data']
+
+      # Format the message
+      prefix = logger_name ? "[#{server_id}:#{logger_name}]" : "[#{server_id}]"
+      message = data.is_a?(String) ? data : data.inspect
+
+      # Map MCP log levels to Ruby Logger levels
+      case level.to_s.downcase
+      when 'debug'
+        logger.debug("#{prefix} #{message}")
+      when 'info', 'notice'
+        logger.info("#{prefix} #{message}")
+      when 'warning'
+        logger.warn("#{prefix} #{message}")
+      when 'error', 'critical', 'alert', 'emergency'
+        logger.error("#{prefix} #{message}")
+      else
+        logger.info("#{prefix} [#{level}] #{message}")
+      end
+    end
+
     # Select a server based on index, name, type, or instance
     # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::ServerBase]
@@ -529,7 +678,17 @@ module MCPClient
       required = schema['required'] || schema[:required]
       return unless required.is_a?(Array)
 
+      properties = schema['properties'] || schema[:properties] || {}
+
       missing = required.map(&:to_s) - parameters.keys.map(&:to_s)
+
+      # Exclude required params that have a default value in the schema,
+      # since the server will apply the default.
+      missing = missing.reject do |param|
+        prop = properties[param] || properties[param.to_sym]
+        prop.is_a?(Hash) && (prop.key?('default') || prop.key?(:default))
+      end
+
       return unless missing.any?
 
       raise MCPClient::Errors::ValidationError, "Missing required parameters: #{missing.join(', ')}"
@@ -606,8 +765,9 @@ module MCPClient
       end
     end
 
-    # Handle elicitation request from server (MCP 2025-06-18)
-    # @param request_id [String, Integer] the JSON-RPC request ID
+    # Handle elicitation request from server (MCP 2025-11-25)
+    # Supports both form mode (structured data) and URL mode (out-of-band interaction).
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused at client layer)
     # @param params [Hash] the elicitation parameters
     # @return [Hash] the elicitation response
     def handle_elicitation_request(_request_id, params)
@@ -617,43 +777,17 @@ module MCPClient
         return { 'action' => 'decline' }
       end
 
+      mode = params['mode'] || 'form'
       message = params['message']
-      schema = params['schema'] || params['requestedSchema']
-      metadata = params['metadata']
 
       begin
-        # Call the user-defined handler
-        result = case @elicitation_handler.arity
-                 when 0
-                   @elicitation_handler.call
-                 when 1
-                   @elicitation_handler.call(message)
-                 when 2, -1
-                   @elicitation_handler.call(message, schema)
+        result = if mode == 'url'
+                   handle_url_elicitation(params, message)
                  else
-                   @elicitation_handler.call(message, schema, metadata)
+                   handle_form_elicitation(params, message)
                  end
 
-        # Validate and format response
-        case result
-        when Hash
-          if result['action']
-            normalised_action_response(result)
-          elsif result[:action]
-            # Convert symbol keys to strings
-            {
-              'action' => result[:action].to_s,
-              'content' => result[:content]
-            }.compact.then { |payload| normalised_action_response(payload) }
-          else
-            # Assume it's content for an accept action
-            { 'action' => 'accept', 'content' => result }
-          end
-        when nil
-          { 'action' => 'cancel' }
-        else
-          { 'action' => 'accept', 'content' => result }
-        end
+        format_elicitation_response(result, params)
       rescue StandardError => e
         @logger.error("Elicitation handler error: #{e.message}")
         @logger.debug(e.backtrace.join("\n"))
@@ -661,6 +795,103 @@ module MCPClient
       end
     end
 
+    # Handle form mode elicitation (MCP 2025-11-25)
+    # @param params [Hash] the elicitation parameters
+    # @param message [String] the human-readable message
+    # @return [Object] handler result
+    def handle_form_elicitation(params, message)
+      schema = params['requestedSchema'] || params['schema']
+      metadata = params['metadata']
+
+      # Validate schema if present
+      if schema
+        schema_errors = ElicitationValidator.validate_schema(schema)
+        @logger.warn("Elicitation schema validation warnings: #{schema_errors.join('; ')}") unless schema_errors.empty?
+      end
+
+      # Call the user-defined handler
+      case @elicitation_handler.arity
+      when 0
+        @elicitation_handler.call
+      when 1
+        @elicitation_handler.call(message)
+      when 2, -1
+        @elicitation_handler.call(message, schema)
+      else
+        @elicitation_handler.call(message, schema, metadata)
+      end
+    end
+
+    # Handle URL mode elicitation (MCP 2025-11-25)
+    # @param params [Hash] the elicitation parameters
+    # @param message [String] the human-readable message
+    # @return [Object] handler result
+    def handle_url_elicitation(params, message)
+      url = params['url']
+      elicitation_id = params['elicitationId']
+
+      # Call handler with URL-mode specific params
+      case @elicitation_handler.arity
+      when 0
+        @elicitation_handler.call
+      when 1
+        @elicitation_handler.call(message)
+      when 2, -1
+        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id })
+      else
+        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id },
+                                  params['metadata'])
+      end
+    end
+
+    # Format and validate the elicitation response
+    # @param result [Object] handler result
+    # @param params [Hash] original request params (for schema validation)
+    # @return [Hash] formatted response
+    def format_elicitation_response(result, params)
+      response = case result
+                 when Hash
+                   if result['action']
+                     normalised_action_response(result)
+                   elsif result[:action]
+                     {
+                       'action' => result[:action].to_s,
+                       'content' => result[:content]
+                     }.compact.then { |payload| normalised_action_response(payload) }
+                   else
+                     { 'action' => 'accept', 'content' => result }
+                   end
+                 when nil
+                   { 'action' => 'cancel' }
+                 else
+                   { 'action' => 'accept', 'content' => result }
+                 end
+
+      # Validate content against schema for form mode accept responses
+      validate_elicitation_content(response, params)
+
+      response
+    end
+
+    # Validate elicitation response content against the requestedSchema
+    # @param response [Hash] the formatted response
+    # @param params [Hash] original request params
+    # @return [void]
+    def validate_elicitation_content(response, params)
+      return unless response['action'] == 'accept' && response['content'].is_a?(Hash)
+
+      mode = params['mode'] || 'form'
+      return unless mode == 'form'
+
+      schema = params['requestedSchema'] || params['schema']
+      return unless schema.is_a?(Hash)
+
+      errors = ElicitationValidator.validate_content(response['content'], schema)
+      return if errors.empty?
+
+      @logger.warn("Elicitation content validation warnings: #{errors.join('; ')}")
+    end
+
     # Ensure the action value conforms to MCP spec (accept, decline, cancel)
     # Falls back to accept for unknown action values.
     def normalised_action_response(result)
@@ -670,5 +901,169 @@ module MCPClient
       @logger.warn("Unknown elicitation action '#{action}', defaulting to accept")
       result.merge('action' => 'accept')
     end
+
+    # Normalize roots array - convert Hashes to Root objects (MCP 2025-06-18)
+    # @param roots [Array<MCPClient::Root, Hash>, nil] the roots to normalize
+    # @return [Array<MCPClient::Root>] normalized roots array
+    def normalize_roots(roots)
+      return [] if roots.nil?
+
+      roots.map do |root|
+        case root
+        when MCPClient::Root
+          root
+        when Hash
+          MCPClient::Root.from_json(root)
+        else
+          raise ArgumentError, "Invalid root type: #{root.class}. Expected MCPClient::Root or Hash."
+        end
+      end
+    end
+
+    # Handle roots/list request from server (MCP 2025-06-18)
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
+    # @param _params [Hash] the request parameters (unused)
+    # @return [Hash] the roots list response
+    def handle_roots_list_request(_request_id, _params)
+      { 'roots' => @roots.map(&:to_h) }
+    end
+
+    # Send notification to all servers that roots have changed (MCP 2025-06-18)
+    # @return [void]
+    def notify_roots_changed
+      @servers.each do |server|
+        server.rpc_notify('notifications/roots/list_changed', {})
+      rescue StandardError => e
+        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class
+        @logger.warn("[#{server_id}] Failed to send roots/list_changed notification: #{e.message}")
+      end
+    end
+
+    # Handle sampling/createMessage request from server (MCP 2025-11-25)
+    # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
+    # @param params [Hash] the sampling parameters
+    # @return [Hash] the sampling response (role, content, model, stopReason)
+    def handle_sampling_request(_request_id, params)
+      # If no handler is configured, return an error
+      unless @sampling_handler
+        @logger.warn('Received sampling request but no handler configured')
+        return { 'error' => { 'code' => -1, 'message' => 'Sampling not supported' } }
+      end
+
+      messages = params['messages'] || []
+      model_preferences = normalize_model_preferences(params['modelPreferences'])
+      system_prompt = params['systemPrompt']
+      max_tokens = params['maxTokens']
+      include_context = params['includeContext']
+      temperature = params['temperature']
+      stop_sequences = params['stopSequences']
+      metadata = params['metadata']
+
+      begin
+        # Call the user-defined handler with parameters based on arity
+        result = call_sampling_handler(messages, model_preferences, system_prompt, max_tokens,
+                                       include_context, temperature, stop_sequences, metadata)
+
+        # Validate and format response
+        validate_sampling_response(result)
+      rescue StandardError => e
+        @logger.error("Sampling handler error: #{e.message}")
+        @logger.debug(e.backtrace.join("\n"))
+        { 'error' => { 'code' => -1, 'message' => "Sampling error: #{e.message}" } }
+      end
+    end
+
+    # Call sampling handler with appropriate arity
+    # @param messages [Array] the messages
+    # @param model_preferences [Hash, nil] normalized model preferences
+    # @param system_prompt [String, nil] system prompt
+    # @param max_tokens [Integer, nil] max tokens
+    # @param include_context [String, nil] context inclusion setting
+    # @param temperature [Float, nil] temperature
+    # @param stop_sequences [Array, nil] stop sequences
+    # @param metadata [Hash, nil] metadata
+    # @return [Hash] the handler result
+    def call_sampling_handler(messages, model_preferences, system_prompt, max_tokens,
+                              include_context, temperature, stop_sequences, metadata)
+      arity = @sampling_handler.arity
+      # Normalize negative arity (optional params) to minimum required args
+      arity = -(arity + 1) if arity.negative?
+      case arity
+      when 0
+        @sampling_handler.call
+      when 1
+        @sampling_handler.call(messages)
+      when 2
+        @sampling_handler.call(messages, model_preferences)
+      when 3
+        @sampling_handler.call(messages, model_preferences, system_prompt)
+      when 4
+        @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens)
+      else
+        @sampling_handler.call(messages, model_preferences, system_prompt, max_tokens,
+                               { 'includeContext' => include_context, 'temperature' => temperature,
+                                 'stopSequences' => stop_sequences, 'metadata' => metadata })
+      end
+    end
+
+    # Normalize and validate modelPreferences from sampling request (MCP 2025-11-25)
+    # Ensures hints is an array of hashes with 'name', and priority values are clamped to 0.0..1.0
+    # @param prefs [Hash, nil] raw modelPreferences from request
+    # @return [Hash, nil] normalized modelPreferences or nil
+    def normalize_model_preferences(prefs)
+      return nil if prefs.nil?
+      return nil unless prefs.is_a?(Hash)
+
+      normalized = {}
+
+      # Normalize hints: array of { 'name' => String }
+      if prefs['hints']
+        normalized['hints'] = Array(prefs['hints']).filter_map do |hint|
+          next nil unless hint.is_a?(Hash) && hint['name']
+
+          { 'name' => hint['name'].to_s }
+        end
+      end
+
+      # Normalize priority values (0.0 to 1.0)
+      %w[costPriority speedPriority intelligencePriority].each do |key|
+        next unless prefs.key?(key)
+
+        value = prefs[key]
+        normalized[key] = value.is_a?(Numeric) ? value.to_f.clamp(0.0, 1.0) : nil
+      end
+
+      normalized
+    end
+
+    # Validate sampling response from handler (MCP 2025-11-25)
+    # @param result [Hash] the result from the sampling handler
+    # @return [Hash] validated sampling response
+    def validate_sampling_response(result)
+      return { 'error' => { 'code' => -1, 'message' => 'Sampling rejected' } } if result.nil?
+
+      # Convert symbol keys to string keys
+      result = result.transform_keys(&:to_s) if result.is_a?(Hash) && result.keys.first.is_a?(Symbol)
+
+      # Ensure required fields are present
+      unless result.is_a?(Hash) && result['content']
+        return {
+          'role' => 'assistant',
+          'content' => { 'type' => 'text', 'text' => result.to_s },
+          'model' => 'unknown',
+          'stopReason' => 'endTurn'
+        }
+      end
+
+      # Set defaults for missing fields
+      result['role'] ||= 'assistant'
+      result['model'] ||= 'unknown'
+      result['stopReason'] ||= 'endTurn'
+
+      # Normalize content if it's a string
+      result['content'] = { 'type' => 'text', 'text' => result['content'] } if result['content'].is_a?(String)
+
+      result
+    end
   end
 end