copilotkit-runtime 0.1.0.rc.1

data/lib/copilotkit/intelligence.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+require 'json'
+require 'net/http'
+require 'uri'
+require 'securerandom'
+require 'thread'
+require 'timeout'
+require_relative 'inspector_metadata'
+require_relative 'runtime_entitlements'
+
+module CopilotKit
+  # Safe platform error. Response bodies and credentials are not included.
+  class Error < StandardError
+    attr_reader :status
+    def initialize(status, message)
+      @status = status
+      super(message)
+    end
+  end
+
+  # Safe entitlement failure with platform status and retry guidance.
+  class RuntimeEntitlementError < Error
+    attr_reader :retryable
+    def initialize(status, message, retryable)
+      @retryable = retryable
+      super(status, message)
+    end
+  end
+
+  # Trusted per-call permissions for user and project memories.
+  class MemoryGrant
+    VALUES = { none: 'none', read: 'read', read_write: 'read-write' }.freeze
+    attr_reader :user, :project
+
+    def initialize(user:, project:)
+      @user = VALUES.fetch(user, user)
+      @project = VALUES.fetch(project, project)
+      raise ArgumentError, 'Invalid memory grant' unless VALUES.value?(@user) && VALUES.value?(@project)
+      freeze
+    end
+
+    def to_h
+      { 'user' => user, 'project' => project }
+    end
+  end
+
+  # Native HTTP transport. Each call closes its connection and never follows redirects.
+  class Platform
+    def initialize(url, key)
+      @url, @key = url.sub(%r{/$}, ''), key
+      uri = URI(@url)
+      raise ArgumentError, 'HTTP(S) URL is required' unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+    end
+
+    def request(method, path, payload = nil, headers = {})
+      uri = URI(@url + path)
+      request = Net::HTTPGenericRequest.new(method, !payload.nil?, true, uri.request_uri, headers.merge('authorization' => "Bearer #{@key}", 'content-type' => 'application/json'))
+      request.body = JSON.generate(payload) unless payload.nil?
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', open_timeout: 5, read_timeout: 15) do |http|
+        http.max_retries = 0
+        return inspector_response(http, request) if method == 'GET' && path == '/api/inspector/metadata'
+        return entitlement_response(http, request) if method == 'GET' && path == '/api/entitlements/runtime'
+        http.request(request)
+      end
+      raise Error.new(response.code.to_i, 'Intelligence platform request failed') unless response.code.to_i.between?(200, 299)
+      response.body.nil? || response.body.empty? ? nil : JSON.parse(response.body)
+    rescue JSON::ParserError
+      if method == 'GET' && path == '/api/entitlements/runtime'
+        raise RuntimeEntitlementError.new(502, 'Invalid Runtime entitlement response', false), cause: nil
+      end
+      raise Error.new(502, 'Invalid platform response')
+    rescue IOError, SystemCallError, Timeout::Error, SocketError
+      raise Error.new(502, 'Intelligence platform is unreachable')
+    end
+
+    # Skip absent/error bodies while the SDK bounds the full connection lifetime.
+    def inspector_response(http, request)
+      http.request(request) do |response|
+        status = response.code.to_i
+        return nil if [204, 404].include?(status)
+        raise Error.new(status, 'Inspector metadata request failed') unless status.between?(200, 299)
+        body = response.body
+        raise Error.new(502, 'Invalid Inspector metadata response') if body.nil? || body.empty?
+        return JSON.parse(body)
+      end
+    end
+    private :inspector_response
+
+    # Inspect rejected statuses before reading bodies that can stall or contain secrets.
+    def entitlement_response(http, request)
+      http.request(request) do |response|
+        status = response.code.to_i
+        unless status.between?(200, 299)
+          raise RuntimeEntitlementError.new(status, 'Runtime entitlement request rejected', [408, 425, 429].include?(status) || status >= 500), cause: nil
+        end
+        body = response.body
+        raise RuntimeEntitlementError.new(502, 'Invalid Runtime entitlement response', false), cause: nil if body.nil? || body.empty?
+        return JSON.parse(body)
+      end
+    end
+    private :entitlement_response
+  end
+
+  # Programmatic Intelligence SDK. Requiring this file does not load Runtime or Rack.
+  class Intelligence
+    API_URL = 'https://api.intelligence.copilotkit.ai'
+    RUNNER_URL = 'wss://realtime.intelligence.copilotkit.ai/runner'
+    CLIENT_URL = 'wss://realtime.intelligence.copilotkit.ai/client'
+    attr_reader :api_key, :api_url, :runner_url, :client_url
+
+    def initialize(api_key:, api_url: API_URL, runner_url: RUNNER_URL, client_url: CLIENT_URL, transport: nil)
+      raise ArgumentError, 'api_key is required' unless api_key.is_a?(String) && !api_key.strip.empty?
+      [[api_url, %w[http https]], [runner_url, %w[ws wss]], [client_url, %w[ws wss]]].each do |endpoint, schemes|
+        uri = URI(endpoint)
+        raise ArgumentError, 'Invalid Intelligence endpoint URL' unless schemes.include?(uri.scheme) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+      end
+      @api_key, @api_url = api_key.dup.freeze, api_url.sub(%r{/$}, '').freeze
+      @runner_url, @client_url = runner_url.dup.freeze, client_url.dup.freeze
+      @transport = transport || Platform.new(@api_url, api_key)
+      @listeners = { created: [], updated: [], deleted: [] }
+      @listener_mutex = Mutex.new
+      @entitlement_mutex = Mutex.new
+      @entitlement_cache = nil
+    end
+
+    # Shared SDK transport used by Runtime. Credentials always come from this client.
+    def request(method, path, payload = nil, headers = {})
+      result = @transport.request(method, path, payload, headers)
+      notify_thread_mutation(method, path, payload, result)
+      result
+    end
+
+    # Read sanitized project metadata within five seconds, including the response body.
+    # @return [Hash, nil] Supported V1 fields, or nil for 204, 404, or an unsupported schema.
+    def get_inspector_metadata
+      Timeout.timeout(5) do
+        InspectorMetadata.parse(request('GET', '/api/inspector/metadata'))
+      end
+    rescue Timeout::Error
+      raise Timeout::Error, 'Inspector metadata request timed out', cause: nil
+    rescue Error => error
+      return nil if error.status == 404
+      raise Error.new(error.status, 'Inspector metadata request failed'), cause: nil
+    rescue StandardError
+      raise Error.new(502, 'Inspector metadata request failed'), cause: nil
+    end
+
+    # @return [Hash] A normalized ready grant or structured non-ready result.
+    def get_runtime_entitlements
+      @entitlement_mutex.synchronize do
+        unless @entitlement_cache && entitlement_now < @entitlement_cache.first
+          begin
+            value = fetch_runtime_entitlements
+            active = value['status'] == 'ready' && value['entitlement']['active']
+            @entitlement_cache = [entitlement_now + (active ? 30 : 5), value]
+          rescue RuntimeEntitlementError => error
+            @entitlement_cache = [entitlement_now + 5, error]
+          end
+        end
+        value = @entitlement_cache.last
+        if value.is_a?(RuntimeEntitlementError)
+          raise RuntimeEntitlementError.new(value.status, value.message, value.retryable), cause: nil
+        end
+        RuntimeEntitlements.copy(value)
+      end
+    end
+
+    # Bound the whole platform request and keep cached failures safe for every caller.
+    def fetch_runtime_entitlements
+      Timeout.timeout(1.5) do
+        value = RuntimeEntitlements.parse(request('GET', '/api/entitlements/runtime'))
+        raise RuntimeEntitlementError.new(502, 'Invalid Runtime entitlement response', false), cause: nil unless value
+        value
+      end
+    rescue RuntimeEntitlementError => error
+      raise RuntimeEntitlementError.new(error.status, 'Runtime entitlement request failed', error.retryable), cause: nil
+    rescue Timeout::Error
+      raise RuntimeEntitlementError.new(504, 'Runtime entitlement request timed out', true), cause: nil
+    rescue Error => error
+      raise RuntimeEntitlementError.new(error.status, 'Runtime entitlement request rejected', [408, 425, 429].include?(error.status) || error.status >= 500), cause: nil
+    rescue StandardError
+      raise RuntimeEntitlementError.new(502, 'Runtime entitlement connection failed', true), cause: nil
+    end
+
+    def entitlement_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    private :fetch_runtime_entitlements, :entitlement_now
+
+    # Register a creation listener; the returned Proc removes it.
+    def on_thread_created(&callback)
+      subscribe(:created, callback)
+    end
+
+    # Register a listener for thread updates and archives.
+    def on_thread_updated(&callback)
+      subscribe(:updated, callback)
+    end
+
+    # Register a listener with the deleted thread and explicit caller identity.
+    def on_thread_deleted(&callback)
+      subscribe(:deleted, callback)
+    end
+
+    # List a user's threads for one agent, retaining the platform pagination cursor.
+    def list_threads(user_id:, agent_id:, include_archived: false, limit: nil, cursor: nil)
+      query = { userId: user_id, agentId: agent_id, limit: limit, cursor: cursor }.compact
+      query[:includeArchived] = 'true' if include_archived
+      object('GET', '/api/threads?' + URI.encode_www_form(query))
+    end
+
+    def get_thread(thread_id:, user_id:)
+      thread('GET', '/api/threads/' + segment(thread_id) + '?' + URI.encode_www_form(userId: user_id))
+    end
+
+    # Assign a new thread to an existing Learning Container through its stable ID.
+    def create_thread(thread_id:, user_id:, agent_id:, name: nil, learning_container_id: nil)
+      body = { 'threadId' => thread_id, 'userId' => user_id, 'agentId' => agent_id }
+      body['name'] = name unless name.nil?
+      body['learningContainerId'] = learning_container_id unless learning_container_id.nil?
+      thread('POST', '/api/threads', body)
+    end
+
+    # Resolve concurrent creation only after a 404 read followed by a 409 create.
+    def get_or_create_thread(thread_id:, user_id:, agent_id:, name: nil, learning_container_id: nil)
+      begin
+        return { 'thread' => get_thread(thread_id: thread_id, user_id: user_id), 'created' => false }
+      rescue Error => error
+        raise unless error.status == 404
+      end
+      begin
+        value = create_thread(thread_id: thread_id, user_id: user_id, agent_id: agent_id, name: name, learning_container_id: learning_container_id)
+        { 'thread' => value, 'created' => true }
+      rescue Error => error
+        raise unless error.status == 409
+        { 'thread' => get_thread(thread_id: thread_id, user_id: user_id), 'created' => false }
+      end
+    end
+
+    def update_thread(thread_id:, user_id:, agent_id:, updates:)
+      body = updates.transform_keys(&:to_s).merge('userId' => user_id, 'agentId' => agent_id)
+      thread('PATCH', '/api/threads/' + segment(thread_id), body)
+    end
+
+    def archive_thread(thread_id:, user_id:, agent_id:)
+      update_thread(thread_id: thread_id, user_id: user_id, agent_id: agent_id, updates: { archived: true })
+      nil
+    end
+
+    # Permanently delete a thread and its history.
+    def delete_thread(thread_id:, user_id:, agent_id:)
+      request('DELETE', '/api/threads/' + segment(thread_id), {
+        'userId' => user_id, 'agentId' => agent_id,
+        'reason' => "Deleted via CopilotKit SDK (userId=#{user_id}, agentId=#{agent_id})"
+      })
+      nil
+    end
+
+    def get_thread_messages(thread_id:, user_id:)
+      object('GET', '/api/threads/' + segment(thread_id) + '/messages?' + URI.encode_www_form(userId: user_id))
+    end
+
+    def get_thread_events(thread_id:)
+      object('GET', '/api/_inspect/threads/' + segment(thread_id) + '/events')
+    end
+
+    def get_thread_state(thread_id:)
+      object('GET', '/api/_inspect/threads/' + segment(thread_id) + '/state')
+    end
+
+    def list_memories(user_id:, include_invalidated: false, memory_grant: nil)
+      path = '/api/memories' + (include_invalidated ? '?includeInvalidated=true' : '')
+      object('GET', path, nil, memory_headers(user_id, memory_grant))
+    end
+
+    def create_memory(user_id:, content:, kind:, scope: nil, source_thread_ids: [], memory_grant: nil)
+      body = { 'content' => content, 'kind' => kind, 'sourceThreadIds' => source_thread_ids }
+      body['scope'] = scope unless scope.nil?
+      object('POST', '/api/memories', body, memory_headers(user_id, memory_grant))
+    end
+
+    # Supersede a memory and retain the platform's retiredId marker.
+    def update_memory(user_id:, memory_id:, content:, kind:, scope: nil, source_thread_ids: [], memory_grant: nil)
+      body = { 'content' => content, 'kind' => kind, 'sourceThreadIds' => source_thread_ids }
+      body['scope'] = scope unless scope.nil?
+      object('PATCH', '/api/memories/' + segment(memory_id), body, memory_headers(user_id, memory_grant))
+    end
+
+    # Retire a memory without deleting its history.
+    def remove_memory(user_id:, memory_id:, memory_grant: nil)
+      request('DELETE', '/api/memories/' + segment(memory_id), nil, memory_headers(user_id, memory_grant))
+      nil
+    end
+
+    def recall_memories(user_id:, query:, limit: nil, scope: nil, memory_grant: nil)
+      body = { 'query' => query, 'limit' => limit, 'scope' => scope }.compact
+      object('POST', '/api/memories/recall', body, memory_headers(user_id, memory_grant))
+    end
+
+    # Reuse client_event_id when retrying the same annotation.
+    def annotate(user_id:, thread_id:, type:, client_event_id: nil, payload: nil, occurred_at: nil)
+      body = { 'userId' => user_id, 'threadId' => thread_id, 'type' => type }
+      body['payload'] = payload unless payload.nil?
+      body['occurredAt'] = occurred_at unless occurred_at.nil?
+      object('PUT', '/connector/annotate/' + segment(client_event_id || SecureRandom.uuid), body)
+    end
+
+    private
+
+    # Synchronize registration without holding the mutex during application callbacks.
+    def subscribe(event, callback)
+      raise ArgumentError, 'A thread listener block is required' unless callback
+      @listener_mutex.synchronize do
+        @listeners[event] << callback unless @listeners[event].any? { |listener| listener.equal?(callback) }
+      end
+      -> { @listener_mutex.synchronize { @listeners[event].delete_if { |listener| listener.equal?(callback) } }; nil }
+    end
+
+    # Observe SDK and Runtime writes once; locks and subscriptions are not thread mutations.
+    def notify_thread_mutation(method, path, body, result)
+      target = %r{\A/api/threads/([^/?]+)\z}.match(path)
+      event = payload = nil
+      if (method == 'POST' && path == '/api/threads') || (method == 'PATCH' && target)
+        thread = result['thread'] if result.is_a?(Hash)
+        if thread.is_a?(Hash) && thread['id'].is_a?(String) && !thread['id'].strip.empty?
+          event = method == 'POST' ? :created : :updated
+          payload = thread
+        end
+      elsif method == 'DELETE' && target && body.is_a?(Hash) && body['userId'].is_a?(String) && body['agentId'].is_a?(String)
+        event = :deleted
+        payload = { 'threadId' => URI.decode_www_form_component(target[1]), 'userId' => body['userId'], 'agentId' => body['agentId'] }
+      end
+      return unless event
+      listeners = @listener_mutex.synchronize { @listeners[event].dup }
+      listeners.each do |callback|
+        begin
+          callback.call(payload)
+        rescue StandardError => error
+          warn "Intelligence thread #{event} listener failed (#{error.class})"
+        end
+      end
+    end
+
+    def segment(value)
+      raise ArgumentError, 'A nonempty identifier is required' unless value.is_a?(String) && !value.strip.empty?
+      URI.encode_www_form_component(value).gsub('+', '%20')
+    end
+
+    def object(method, path, payload = nil, headers = {})
+      value = request(method, path, payload, headers)
+      raise Error.new(502, 'Invalid Intelligence response') unless value.is_a?(Hash)
+      value
+    end
+
+    def thread(method, path, payload = nil)
+      value = object(method, path, payload)['thread']
+      raise Error.new(502, 'Invalid thread response') unless value.is_a?(Hash) && value['id'].is_a?(String) && !value['id'].strip.empty?
+      value
+    end
+
+    def memory_headers(user_id, grant)
+      segment(user_id)
+      headers = { 'x-cpki-user-id' => user_id }
+      unless grant.nil?
+        raise ArgumentError, 'memory_grant must be a MemoryGrant' unless grant.is_a?(MemoryGrant)
+        headers['x-cpki-memory-grant'] = JSON.generate(grant.to_h)
+      end
+      headers
+    end
+  end
+end

data/lib/copilotkit/mcp_apps.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+require 'digest'
+module CopilotKit
+  # Request-scoped MCP Streamable HTTP session. Never accepts a browser URL or credentials.
+  class MCPClient
+    def initialize(config)
+      raise ArgumentError, 'Only MCP Streamable HTTP is supported' unless config['type'] == 'http'
+      @uri = URI(config.fetch('url'))
+      raise ArgumentError, 'MCP URL must use HTTP(S)' unless @uri.is_a?(URI::HTTP) && !@uri.userinfo
+      @headers = config.fetch('headers', {}).dup
+      @session, @reference, @version = nil, 0, '2025-03-26'
+    end
+
+    def connect
+      result = rpc('initialize', { 'protocolVersion' => @version,
+                   'capabilities' => { 'extensions' => { 'io.modelcontextprotocol/ui' => { 'mimeTypes' => ['text/html;profile=mcp-app'] } } },
+                   'clientInfo' => { 'name' => 'copilotkit-runtime-ruby', 'version' => '0.1.0.rc.1' } })
+      raise Error.new(502, 'Malformed MCP initialization') unless result.is_a?(Hash) && result['protocolVersion'].is_a?(String)
+      @version = result['protocolVersion']
+      rpc('notifications/initialized', nil, notification: true)
+      self
+    end
+
+    def rpc(method, params = nil, notification: false)
+      @reference += 1
+      envelope = { 'jsonrpc' => '2.0', 'method' => method }
+      envelope['id'] = @reference unless notification
+      envelope['params'] = params unless params.nil?
+      raw = transport('POST', JSON.generate(envelope))
+      return { 'success' => true } if notification
+      candidates = if raw[:type].include?('text/event-stream')
+                     raw[:body].split(/\r?\n\r?\n/).filter_map do |frame|
+                       data = frame.lines.select { |line| line.start_with?('data:') }.map { |line| line.delete_prefix('data:').strip }.join("\n")
+                       JSON.parse(data) unless data.empty?
+                     end
+                   else
+                     [JSON.parse(raw[:body])]
+                   end
+      response = candidates.find { |message| message.is_a?(Hash) && message['id'] == envelope['id'] }
+      raise Error.new(502, 'Malformed MCP response') unless response && response['jsonrpc'] == '2.0'
+      raise Error.new(502, 'MCP request failed') if response.key?('error')
+      raise Error.new(502, 'Missing MCP result') unless response.key?('result')
+      response['result']
+    rescue JSON::ParserError
+      raise Error.new(502, 'Malformed MCP JSON response')
+    end
+
+    def close
+      transport('DELETE') if @session
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def transport(method, body = nil)
+      headers = @headers.merge('content-type' => 'application/json', 'accept' => 'application/json, text/event-stream', 'mcp-protocol-version' => @version)
+      headers['mcp-session-id'] = @session if @session
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, @uri.request_uri, headers)
+      request.body = body if body
+      result = nil
+      expected_id = body && JSON.parse(body)['id']
+      catch(:mcp_response_complete) do
+       Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == 'https', open_timeout: 5, read_timeout: 15) do |http|
+        http.request(request) do |response|
+          raise Error.new(502, 'MCP server request failed') unless response.code.to_i.between?(200, 299)
+          @session = response['mcp-session-id'] if response['mcp-session-id']
+          data = +''
+          response.read_body do |chunk|
+            data << chunk
+            raise Error.new(502, 'MCP response exceeded size limit') if data.bytesize > 4_194_304
+            if expected_id && response['content-type'].to_s.include?('text/event-stream')
+              frames = data.split(/\r?\n\r?\n/, -1)[0...-1]
+              complete = frames.any? do |frame|
+                payload = frame.lines.select { |line| line.start_with?('data:') }.map { |line| line.delete_prefix('data:').strip }.join("\n")
+                message = payload.empty? ? nil : JSON.parse(payload)
+                message.is_a?(Hash) && message['id'] == expected_id
+              end
+              if complete
+                result = { body: frames.join("\n\n"), type: 'text/event-stream' }
+                throw :mcp_response_complete
+              end
+            end
+          end
+          result = { body: data, type: response['content-type'].to_s }
+        end
+       end
+      end
+      result
+    end
+  end
+
+  # MCP Apps discovery, tool execution, activity, and allowlisted iframe reentry.
+  class MCPApps
+    METHODS = %w[tools/call resources/read notifications/message ping].freeze
+    def initialize(servers)
+      @servers, @tools, @calls, @resolved = servers, {}, {}, Set.new
+    end
+
+    def server_hash(server)
+      Digest::MD5.hexdigest(JSON.generate('type' => server['type'], 'url' => server['url']))
+    end
+
+    def proxy(request)
+      raise Error.new(400, 'Invalid MCP proxy request') unless request.is_a?(Hash)
+      raise Error.new(403, 'MCP method is not allowed') unless METHODS.include?(request['method'])
+      matches = @servers.select do |entry|
+        request['serverId'] ? entry['serverId'] == request['serverId'] : server_hash(entry) == request['serverHash']
+      end
+      server = matches.first if matches.length == 1
+      raise Error.new(404, 'Unknown MCP server') unless server
+      with_client(server) { |client| client.rpc(request['method'], request['params'], notification: request['method'] == 'notifications/message') }
+    rescue Error, ArgumentError, KeyError, SocketError, IOError, SystemCallError, Timeout::Error, Net::HTTPBadResponse, OpenSSL::SSL::SSLError
+      { 'error' => 'MCP proxy request rejected or failed' }
+    end
+
+    def prepare(input)
+      @servers.each do |server|
+        with_client(server) do |client|
+          cursor, pages = nil, 0
+          loop do
+            result = client.rpc('tools/list', cursor ? { 'cursor' => cursor } : {})
+            raise Error.new(502, 'Invalid MCP tool listing') unless result.is_a?(Hash) && result['tools'].is_a?(Array)
+            result['tools'].each do |tool|
+              next unless tool.is_a?(Hash)
+              ui = tool.dig('_meta', 'ui')
+              if ui.is_a?(Hash) && ui.key?('visibility')
+                next unless ui['visibility'].is_a?(Array) && ui['visibility'].include?('model')
+              end
+              resource = tool.dig('_meta', 'ui', 'resourceUri')
+              resource = tool.dig('_meta', 'ui/resourceUri') unless resource.is_a?(String)
+              next unless resource.is_a?(String) && tool['name'].is_a?(String)
+              raise Error.new(502, 'Duplicate MCP UI tool name') if @tools.key?(tool['name'])
+              @tools[tool['name']] = { server: server, resource: resource, tool: {
+                'name' => tool['name'], 'description' => tool.fetch('description', '') + "\n[UI Resource: #{resource}]",
+                'parameters' => tool.fetch('inputSchema', { 'type' => 'object', 'properties' => {} }) } }
+            end
+            cursor = result['nextCursor']
+            break unless cursor
+            pages += 1
+            raise Error.new(502, 'MCP tool pagination limit exceeded') if pages >= 32
+          end
+        end
+      end
+      input.fetch('messages', []).each do |message|
+        @resolved << message['toolCallId'] if message['role'] == 'tool'
+        message.fetch('toolCalls', []).each do |call|
+          function = call['function'] || {}
+          @calls[call['id']] = { name: function['name'], args: function.fetch('arguments', '') }
+        end
+      end
+      names = @tools.keys
+      input.merge('tools' => input.fetch('tools', []).reject { |tool| names.include?(tool['name']) } + @tools.values.map { |entry| entry[:tool] })
+    end
+
+    def accept(event)
+      id = event['toolCallId']
+      case event['type']
+      when 'TOOL_CALL_START' then @calls[id] = { name: event['toolCallName'], args: '' }
+      when 'TOOL_CALL_ARGS'
+        if @calls[id]
+          @calls[id][:args] += event.fetch('delta', '')
+          raise Error.new(502, 'MCP tool arguments exceeded size limit') if @calls[id][:args].bytesize > 1_048_576
+        end
+      when 'TOOL_CALL_RESULT' then @resolved << id
+      end
+    end
+
+    def finish
+      @calls.each do |id, call|
+        info = @tools[call[:name]]
+        next unless info && !@resolved.include?(id)
+        begin
+          arguments = JSON.parse(call[:args].empty? ? '{}' : call[:args])
+          raise Error.new(400, 'MCP tool arguments must be an object') unless arguments.is_a?(Hash)
+          result = with_client(info[:server]) { |client| client.rpc('tools/call', { 'name' => call[:name], 'arguments' => arguments }) }
+          content = result['content']
+          text = content.is_a?(Array) ? content.filter_map { |entry| entry['text'] if entry.is_a?(Hash) && entry['type'] == 'text' }.join("\n") : ''
+          yield({ 'type' => 'TOOL_CALL_RESULT', 'messageId' => SecureRandom.uuid, 'toolCallId' => id, 'content' => text.empty? ? JSON.generate(content) : text })
+          activity = { 'result' => result, 'resourceUri' => info[:resource], 'serverHash' => server_hash(info[:server]), 'toolInput' => arguments }
+          activity['serverId'] = info[:server]['serverId'] if info[:server]['serverId']
+          yield({ 'type' => 'ACTIVITY_SNAPSHOT', 'messageId' => SecureRandom.uuid, 'activityType' => 'mcp-apps', 'content' => activity, 'replace' => true })
+        rescue StandardError
+          yield({ 'type' => 'TOOL_CALL_RESULT', 'messageId' => SecureRandom.uuid, 'toolCallId' => id, 'content' => JSON.generate('error' => 'MCP tool execution failed') })
+        end
+      end
+    end
+
+    private
+
+    def with_client(server)
+      client = MCPClient.new(server)
+      client.connect
+      yield client
+    ensure
+      client&.close
+    end
+  end
+end