ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/http_transport_base/param_headers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module HttpTransportBase
+    # MCP 2026-07-28 "Custom Headers from Tool Parameters" (SEP-2243): the
+    # Mcp-Param-* headers a tools/call derives from its annotated arguments,
+    # the clearing of that reserved namespace so a configured header cannot
+    # stand in for an argument that was not sent, and the
+    # refresh-tools-and-retry-once recovery a HeaderMismatch asks for.
+    module ParamHeaders
+      private
+
+      # Attach the computed `Mcp-Param-*` headers (MCP 2026-07-28 "Custom
+      # Headers from Tool Parameters"). On a modern session that namespace is
+      # derived from the call's arguments and from nothing else -- the client
+      # MUST omit the header for an argument that is absent or null -- so a
+      # configured header of that name is cleared first: leaving it would let
+      # it stand for an argument the extraction omitted, which no tools/list
+      # refresh can correct. The clearing matches HTTP's case-insensitive field
+      # names, whatever spelling the host configured.
+      # @param req [Faraday::Request] the outgoing request
+      # @param param_headers [Hash{String => String}] the computed headers
+      # @return [void]
+      def apply_param_headers(req, param_headers)
+        if modern?
+          # The names are collected before any is dropped: the header set is
+          # being mutated.
+          configured = req.headers.keys.select { |name| MCPClient::HeaderParams.mirrored_header?(name) }
+          configured.each { |name| req.headers.delete(name) }
+        end
+        param_headers.each { |k, v| req.headers[k] = v }
+      end
+    end
+  end
+end

data/lib/mcp_client/http_transport_base/request_recovery.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module HttpTransportBase
+    # The recoveries one JSON-RPC exchange may need before it is handed to
+    # with_retry: the MCP 2026-07-28 re-issue of a request whose response
+    # stream broke, the HeaderMismatch refresh-and-retry-once, and the
+    # protocol-version renegotiation. It also owns the boundary the transport
+    # crosses when it hands control to host code, since an error from the far
+    # side of that boundary is what these recoveries must not act on.
+    module RequestRecovery
+      # Marks an error that escaped another exchange run from inside this one:
+      # host code this transport handed control to while a response was still
+      # being parsed, or the tools/list a tools/call reads first to derive its
+      # headers. It belongs to that exchange -- which had its own recovery --
+      # and never to the one it surfaced in.
+      module NestedExchange; end
+
+      private
+
+      # One attempt of a request with the transport-level recoveries that
+      # re-send the same params: version renegotiation, HeaderMismatch refresh
+      # and a response stream that closed without the response.
+      #
+      # Both re-sends `retry` the same guarded block rather than running inside
+      # their own rescue clause, so either recovery's re-send is still covered
+      # by the other — a HeaderMismatch retry whose stream closes is re-issued,
+      # and a re-issue that is rejected for its headers still refreshes
+      # tools/list. Each recovery fires at most once, so the pair is bounded at
+      # three sends.
+      #
+      # The refresh is spent once for the whole logical request: the caller's
+      # flag rides in, and the block marks it. A re-issue is scoped to the
+      # attempt, which is all a tools/call ever gets — with_retry refuses to
+      # re-attempt a NON_IDEMPOTENT_METHODS request.
+      #
+      # The deadline is this attempt's, shared by every send it makes: a
+      # recovery replaces the request, it does not buy it more time.
+      # @param method [String] JSON-RPC method name
+      # @param params [Hash] parameters for this attempt (may carry inputResponses)
+      # @param timeout [Numeric, nil] per-request timeout override
+      # @param header_refresh_done [Boolean] whether the one HeaderMismatch refresh was spent
+      # @yield marks the HeaderMismatch refresh as spent
+      # @return [Object] the attempt's result
+      def attempt_request(method, params, timeout, header_refresh_done)
+        with_retry(method) do
+          # One budget for this request and every replacement it may need: the
+          # maximum timeout the spec asks for holds "regardless of progress",
+          # and neither a lost stream nor a rejected header set is progress.
+          # A continuation is a request of its own and gets its own budget --
+          # the wait before it is bounded separately (see InputWaits).
+          budget = timeout || @read_timeout
+          # The real monotonic clock, never the stubbable #monotonic_now the
+          # caching layer exposes: a test that freezes cache time must not
+          # make every request's deadline expire on arrival.
+          deadline = budget && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + budget)
+          stream_reissued = false
+          header_refreshed = header_refresh_done
+          begin
+            send_request_with_version_retry(method, params, timeout, deadline)
+          rescue MCPClient::Errors::HeaderMismatchError => e
+            # A rejection that escaped host code reached from this response --
+            # a listener's own tools/call -- rejects that request, not this
+            # one. This one the server has already executed, and re-sending it
+            # on someone else's error would execute it twice.
+            raise if e.is_a?(NestedExchange)
+            raise unless modern? && method == 'tools/call' && !header_refreshed
+
+            header_refreshed = true
+            yield
+            refreshed = refresh_tools_after_header_mismatch(e)
+            # The rejected attempt did not run the tool; this retry is the
+            # send that would. A refreshed definition whose inputSchema
+            # declares an unreadable dialect must therefore stop the call
+            # here, not after it has been executed. The list this refresh
+            # read is carried into the check so that the definition pinned
+            # for the retry is this caller's own, not whichever concurrent
+            # refresh happened to write the cache last.
+            reject_unreadable_refreshed_schema!(params, refreshed)
+            retry
+          rescue MCPClient::Errors::ResponseStreamClosedError => e
+            # Modern Streamable HTTP has no resumption: "a broken response
+            # stream loses the in-flight request; clients MUST re-issue it as a
+            # new request with a new request ID" (2026-07-28 changelog, major
+            # change 9). The rule has no exception for tools/call, and this
+            # revision makes closing the response stream itself the
+            # cancellation signal — the server MUST treat the broken stream as
+            # a cancellation and stop work — so the re-issue is the behaviour
+            # the protocol expects rather than a blind replay.
+            #
+            # A stream that closed between (or inside) SSE events reaches here
+            # from the parser; one that died at the socket reaches here from
+            # connection_failure_error. Both are the same loss. A stream a
+            # listener's own request lost is that request's to re-issue, and it
+            # already did: this exchange still has its response.
+            raise if stream_reissued || e.is_a?(NestedExchange)
+
+            stream_reissued = true
+            @logger.warn("#{e.message}; re-issuing #{method} as a new request")
+            retry
+          end
+        end
+      ensure
+        # A pin the retry never consumed (it raised before sending) must not
+        # outlive the request it was for.
+        clear_pinned_retry_definition
+      end
+
+      # Send the request, renegotiating the protocol version once if the server
+      # rejects the one it went out with.
+      # @param method [String] JSON-RPC method name
+      # @param params [Hash] parameters for the request
+      # @param timeout [Numeric, nil] per-request timeout override
+      # @param deadline [Float, nil] monotonic instant the exchange and its
+      #   renegotiated replacement must finish by
+      # @return [Object] result from the JSON-RPC response
+      def send_request_with_version_retry(method, params, timeout, deadline = nil)
+        sent_version = protocol_version
+        begin
+          send_request_and_parse(method, params, timeout, deadline)
+        rescue MCPClient::Errors::UnsupportedProtocolVersionError => e
+          # MCP 2026-07-28 basic/versioning: select a mutually supported
+          # version from the error's list and retry. The server rejected the
+          # request before processing it, so a re-send cannot duplicate a side
+          # effect. Compared against the version THIS request went out with:
+          # a concurrent request may already have moved the transport on.
+          version = select_protocol_version(e.supported)
+          raise unless modern? && version && version != sent_version
+
+          @logger.info("Server does not support protocol version #{sent_version}; " \
+                       "retrying #{method} with #{version}")
+          @protocol_version = version
+          send_request_and_parse(method, params, timeout, deadline)
+        end
+      end
+
+      # Hand control to host code -- a notification listener, a handler for a
+      # server-initiated request -- reached while a response is still being
+      # parsed.
+      #
+      # A request that code issues is an exchange of its own: it gets a slot of
+      # its own for the definition it goes out under
+      # (MCPClient::CalledToolDefinition), and an error escaping it is marked
+      # NestedExchange so the exchange whose response parsing reached here does
+      # not mistake it for its own rejection and recover from it.
+      # @yield the host code
+      # @return [Object] the block's value
+      def dispatching_to_host(&)
+        outside_called_tool_definition(&)
+      rescue StandardError => e
+        e.extend(NestedExchange) unless e.frozen?
+        raise
+      end
+    end
+  end
+end

data/lib/mcp_client/http_transport_base/session_recovery.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module MCPClient
+  module HttpTransportBase
+    # MCP 2025-11-25 session management for the HTTP transports: an HTTP 404
+    # answering a request that carried an Mcp-Session-Id means the session
+    # expired, and "the client MUST start a new session by sending a new
+    # InitializeRequest without a session ID attached". That new session is a
+    # new session in every sense — the session epoch moves with it, so
+    # everything scoped to the old one (the tasks extension's task ids and
+    # input keys, which the replacement session may reuse for entirely
+    # different requests) dies with it.
+    module SessionRecovery
+      # Resend a request against the freshly restarted session — unless doing
+      # so could execute a side effect twice.
+      #
+      # A 404 usually means the server rejected the request outright, but it
+      # does not prove that: a session can expire after the tool ran.
+      # Automatic session recovery is worth having for idempotent methods, and
+      # would otherwise be a hole straight through the no-replay guarantee
+      # that with_retry enforces for NON_IDEMPOTENT_METHODS.
+      #
+      # Raises ConnectionError (which with_retry never retries) so no other
+      # path can turn this into a second attempt.
+      # @param request [Hash] the JSON-RPC request that hit the expired session
+      # @return [Faraday::Response] the response to the resent request
+      # @raise [MCPClient::Errors::ConnectionError] for a non-idempotent method
+      # @raise [MCPClient::Errors::SessionChangedError] for a request of the session that ended
+      def resend_after_session_restart(request)
+        method = request['method']
+        # A request pinned to the session the 404 ended is not resent into the
+        # session that replaced it: its payload (task ids, input request keys)
+        # names something else there. Nothing was written, so the caller may
+        # drop it — see {MCPClient::SessionPin}.
+        check_session_pin!
+        return send_http_request(request) unless MCPClient::JsonRpcCommon::NON_IDEMPOTENT_METHODS.include?(method)
+
+        raise MCPClient::Errors::ConnectionError,
+              "Session expired during #{method}; a new session was started but the request was NOT resent " \
+              'because it may already have executed. Retry it explicitly if that is safe.'
+      end
+
+      private
+
+      # Start a new session after the server invalidated the current one, then
+      # resend the original request once. The @restarting_session flag prevents
+      # a second restart if the fresh session also answers 404.
+      #
+      # The 404 ended a session as surely as a cleanup or a restarted stdio
+      # process does, so the session epoch moves with it: a wait notices the
+      # move and the bookkeeping keyed by the old session dies rather than
+      # colouring a task id the new session may reuse.
+      # @param request [Hash] the JSON-RPC request that hit the expired session
+      # @param expired_session_id [String] the session id the 404'd request was sent with
+      # @return [Faraday::Response] the response to the resent request
+      def restart_session_and_resend(request, expired_session_id)
+        # Serialized on the transport monitor so concurrent 404s trigger a
+        # single restart; the monitor is reentrant, so the nested
+        # perform_initialize/id generation inside is safe.
+        @mutex.synchronize do
+          # Recheck now that the monitor is held: another caller may already
+          # have restarted the session while this one waited. If so, skip the
+          # extra initialize and just resend against the fresh session.
+          return resend_after_session_restart(request) if @session_id != expired_session_id
+
+          @logger.warn("Session #{@session_id} no longer valid (HTTP 404); starting a new session")
+          @restarting_session = true
+          @session_id = nil
+          @last_event_id = nil if instance_variable_defined?(:@last_event_id)
+          # The 404 ended the session, so the epoch moves here — before the
+          # replacement handshake, not after it. A handshake that fails (or
+          # that is still running) must never leave a request, or a task
+          # handle, treating the session the server has already dropped as
+          # the current one. No other request can slip in meanwhile: the
+          # monitor is held for the whole restart.
+          bump_session_epoch
+          # The handshake is not part of the session that ended: it is what
+          # establishes the one that follows, so this thread's pin — which
+          # the bump above has just invalidated — is lifted for it.
+          establish_replacement_session
+          resend_after_session_restart(request)
+        ensure
+          @restarting_session = false
+        end
+      end
+
+      # Send the InitializeRequest that replaces the session the 404 ended,
+      # with this thread's session pin lifted. A handshake that fails leaves
+      # no session behind: the transport is marked uninitialized so the next
+      # request rebuilds one through ensure_connected (whose cleanup ends
+      # this epoch too) instead of talking into a session that never came up.
+      # @return [void]
+      def establish_replacement_session
+        unpinned_session { perform_initialize }
+      rescue StandardError
+        @connection_established = false
+        @initialized = false
+        raise
+      end
+
+      # Whether a 404 should trigger a session restart: only when the 404'd
+      # request was actually sent with a session id and no restart is already
+      # in flight (a restart's own resend answering 404 must not loop).
+      # @param sent_session_id [String, nil] session id captured when the request was sent
+      # @return [Boolean] true if session restart recovery applies
+      def session_restart_applicable?(sent_session_id)
+        return false if sent_session_id.nil?
+
+        @mutex.synchronize { !@restarting_session }
+      end
+    end
+  end
+end

data/lib/mcp_client/http_transport_base/sse_event_scanner.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require_relative 'bounded_inflate'
+
+module MCPClient
+  module HttpTransportBase
+    # Splits an SSE body into complete events as its bytes arrive. Line
+    # terminators are CRLF, CR or LF (SSE "Parsing an event stream"): a CR
+    # ends a line on its own, so an event it terminates is dispatched at
+    # once, and the LF of a CRLF that arrives in the next chunk is skipped.
+    # A gzip body (Streamable HTTP offers gzip on every request) is inflated
+    # as it arrives. Only a body that starts like an event stream is scanned;
+    # a JSON body never yields anything. Events are counted, terminated or
+    # not dispatched, in the same order the completed body splits into them.
+    class SseEventScanner
+      # An event stream opens with a comment or a field — any field: one
+      # the client does not know is ignored, not a reason to stop reading
+      # (SSE "Parsing an event stream"). A body that opens a JSON value is
+      # never an event stream.
+      SSE_START = /\A(?::|[^\n:{\[]+:)/n
+      BOM = "\xEF\xBB\xBF".b
+      GZIP_MAGIC = "\x1F\x8B".b
+
+      # @return [Integer] complete events seen so far
+      attr_reader :count
+
+      # @param max_inflated_bytes [Integer, nil] bound on a gzip body's expansion,
+      #   beyond which the stream is no longer scanned
+      def initialize(max_inflated_bytes: nil)
+        @normalized = +''.b
+        @head = +''.b
+        @scanned = 0
+        @after_cr = false
+        @count = 0
+        @sse = nil
+        @inflater = nil
+        @inflated = 0
+        @max_inflated_bytes = max_inflated_bytes
+      end
+
+      # @param chunk [String] the bytes that just arrived
+      # @yieldparam event [String] one complete event, LF-normalized, without its terminator
+      # @return [void]
+      def feed(chunk)
+        return if @sse == false
+
+        # Bytes, not characters: the body is peer-controlled and may not be
+        # text at all.
+        text = decoded(chunk.b)
+        return if text.nil? || @sse == false
+
+        text = text[1..] if @after_cr && text.start_with?("\n")
+        @after_cr = text.end_with?("\r")
+        @normalized << text.gsub(/\r\n|\r/, "\n")
+        return unless scanning?
+
+        while (index = @normalized.index("\n\n", @scanned))
+          event = @normalized[@scanned...index]
+          @scanned = index + 2
+          @count += 1
+          # Blank lines before an event's first field dispatch nothing (SSE
+          # "Parsing an event stream"), so they are not part of the event.
+          yield event.sub(/\A\n+/, '').force_encoding(Encoding::UTF_8)
+        end
+      end
+
+      private
+
+      # The chunk as text: inflated when the body turned out to be gzip,
+      # which its first two bytes tell. Until they have arrived nothing can be
+      # scanned.
+      # @param chunk [String] the raw bytes
+      # @return [String, nil] nil while the body's encoding is not known yet
+      def decoded(chunk)
+        return inflate(chunk) if @inflater
+        return chunk if @head.frozen?
+
+        @head << chunk
+        return nil if @head.bytesize < GZIP_MAGIC.bytesize
+
+        head = @head
+        @head = ''.b.freeze
+        return head unless head.start_with?(GZIP_MAGIC)
+
+        @inflater = Zlib::Inflate.new(Zlib::MAX_WBITS + 32)
+        inflate(head)
+      end
+
+      # @param bytes [String] gzip bytes as they arrived
+      # @return [String, nil] the text they expand to; nil once the stream is unusable
+      def inflate(bytes)
+        text = BoundedInflate.inflate(@inflater, bytes, @max_inflated_bytes, @inflated)
+        return stop_scanning if text.nil?
+
+        @inflated += text.bytesize
+        text
+      rescue Zlib::Error
+        stop_scanning
+      end
+
+      # @return [nil]
+      def stop_scanning
+        @sse = false
+        @normalized.clear
+        nil
+      end
+
+      # Whether the body is an event stream worth scanning, settled from its
+      # first line after any leading blank lines: one that does not start like
+      # an event stream (JSON, anything else) is never scanned and never
+      # buffered here.
+      #
+      # The verdict waits for that first line to be decidable. A field name is
+      # what says "event stream", and a name split across chunks ("x-igno" +
+      # "re: 1\n") is not one yet: settling on its first bytes would answer
+      # "not an event stream" for a stream that is one, and nothing on it —
+      # a server's request awaiting its answer, a progress notification —
+      # would ever be delivered. A JSON body is refused on its first byte,
+      # since no field name may open with one.
+      # @return [Boolean] false while too little has arrived to tell
+      def scanning?
+        return @sse unless @sse.nil?
+
+        # The UTF-8 decode step of the SSE algorithm drops one leading BOM.
+        @normalized.delete_prefix!(BOM) if @scanned.zero?
+        content = @normalized.sub(/\A\n+/, '')
+        return settle(false) if content.match?(/\A[{\[]/n)
+        # A colon ends a field name; so does the line itself, since a line
+        # with no colon is a field whose value is empty.
+        return false unless content.match?(/[:\n]/n)
+
+        settle(content.match?(SSE_START) || !content.match?(/\A[^\n]*:/n))
+      end
+
+      # @param verdict [Boolean] whether this body is an event stream
+      # @return [Boolean] the verdict
+      def settle(verdict)
+        @sse = verdict
+        @normalized.clear unless verdict
+        verdict
+      end
+    end
+  end
+end

data/lib/mcp_client/http_transport_base/stream_capture.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require_relative 'bounded_inflate'
+
+module MCPClient
+  module HttpTransportBase
+    # How one HTTP exchange is bounded and read as it arrives: the socket
+    # timeout and overall deadline of a request, the listener that gets the
+    # response stream's events while the body is still open, and the count
+    # of events it already handled once the completed body is parsed.
+    module StreamCapture
+      private
+
+      # The socket timeout and the overall deadline of one HTTP exchange.
+      #
+      # MCP 2026-07-28 cancellation/timeouts: implementations "SHOULD always
+      # enforce a maximum timeout regardless of progress". Faraday's socket
+      # timeout only bounds the gap between reads, which a stream of keep-alive
+      # comments resets forever, so every request gets a deadline the capture
+      # middleware checks as the body arrives. A caller-supplied deadline (the
+      # probe and its re-issue share one) is honoured as the time left on it:
+      # the socket timeout is clamped to it, so a silent server cannot stretch
+      # the replacement out to a full timeout of its own.
+      # @param timeout [Numeric, nil] per-request timeout override
+      # @param deadline [Float, nil] monotonic instant the exchange must finish by
+      # @return [Array(Numeric, Float)] the socket timeout and the deadline
+      # @raise [MCPClient::Errors::RequestTimeoutError] when the deadline already passed
+      def request_bounds(timeout, deadline)
+        budget = timeout || @read_timeout
+        return [budget, budget && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + budget)] unless deadline
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise MCPClient::Errors::RequestTimeoutError, 'Request timed out: its deadline has passed' if remaining <= 0
+
+        [budget ? [budget, remaining].min : remaining, deadline]
+      end
+
+      # Run one HTTP exchange under its deadline, whatever the socket does.
+      #
+      # Faraday's socket timeout bounds the gap between reads, and every read
+      # restarts it: a server that sends an event late in the budget, or head
+      # bytes forever, outlives the bound the caller asked for — the second
+      # never even reaches the body callback that checks the deadline. MCP
+      # 2026-07-28 cancellation/timeouts asks for a maximum timeout "regardless
+      # of progress", so a watchdog ends the exchange at the deadline whatever
+      # the socket is doing.
+      #
+      # Raising into the requesting thread is the only way to break its
+      # blocking read from outside. The watchdog fires at most once, never
+      # after the request settled, and is always torn down; if it loses the
+      # race by the microseconds between the answer arriving and the request
+      # being marked settled, the answer stands rather than the timeout.
+      # @param deadline [Float, nil] monotonic instant the exchange must finish by
+      # @return [Object] whatever the block returns
+      # @raise [Faraday::TimeoutError] when the deadline passes first
+      def with_request_watchdog(deadline)
+        return yield unless deadline
+
+        target = Thread.current
+        lock = Mutex.new
+        settled = false
+        watchdog = Thread.new do
+          remaining = deadline - monotonic_now
+          sleep(remaining) if remaining.positive?
+          lock.synchronize do
+            target.raise(Faraday::TimeoutError, 'Request exceeded its deadline') unless settled
+          end
+        end
+
+        begin
+          answered = yield
+          lock.synchronize { settled = true }
+          answered
+        rescue Faraday::TimeoutError
+          raise if answered.nil?
+
+          lock.synchronize { settled = true }
+          answered
+        ensure
+          lock.synchronize { settled = true }
+          watchdog.kill
+        end
+      end
+
+      # A callback handed every complete SSE event of the response stream as
+      # it arrives, or nil to read the stream only once it has ended. The base
+      # transport parses completed bodies; ServerHTTP overrides this.
+      # @param _request [Hash] the JSON-RPC message being sent
+      # @return [Proc, nil]
+      def response_stream_listener(_request)
+        nil
+      end
+
+      # The bound on a gzip body's expansion, for the stream scanner and the
+      # salvage of a delivered compressed answer (Streamable HTTP configures
+      # one; plain HTTP never asks for gzip).
+      # @return [Integer, nil]
+      def inflate_limit
+        respond_to?(:max_decompressed_body_bytes, true) ? max_decompressed_body_bytes : nil
+      end
+
+      # A response body that arrived gzip-encoded, inflated so the salvage
+      # can tell whether the answer is in it. Streamable HTTP offers gzip on
+      # every request, so a delivered answer is usually a delivered
+      # *compressed* answer; treating those bytes as a lost stream would
+      # re-issue a tools/call the server already ran.
+      # An expansion the bound refuses is not a lost answer either: the
+      # server ran the request and sent its result, and only this client's
+      # ceiling stands in the way. Re-issuing there would run the request a
+      # second time, so the caller is told the response was too large — the
+      # same answer the ordinary (unbroken) path gives.
+      # @param body [String] the captured bytes
+      # @return [String, nil] the expanded body; nil when the deflate stream
+      #   itself stopped short of what it needs to be read
+      # @raise [MCPClient::Errors::ResponseTooLargeError] when the body expands
+      #   past the configured bound
+      def inflate_delivered_gzip(body)
+        inflater = Zlib::Inflate.new(Zlib::MAX_WBITS + 32)
+        text = BoundedInflate.inflate(inflater, body, inflate_limit)
+        return text unless text.nil?
+
+        raise MCPClient::Errors::ResponseTooLargeError,
+              "Gzip response expanded beyond #{inflate_limit} bytes"
+      rescue Zlib::Error
+        nil
+      ensure
+        inflater&.close
+      end
+
+      # How many events of the response stream were already handed to the
+      # stream listener while the body arrived (see ResponseBodyCapture).
+      # @param response [Faraday::Response, NormalizedResponse] the completed response
+      # @return [Integer]
+      def live_event_count(response)
+        capture_state(response)[:mcp_live_events].to_i
+      end
+
+      # The failure the stream listener raised while the body arrived, if
+      # any: it could not abort the read (see ResponseBodyCapture), so the
+      # transport raises it in place of the response it was interleaved with.
+      # @param response [Faraday::Response, NormalizedResponse] the completed response
+      # @return [StandardError, nil]
+      def stream_listener_error(response)
+        capture_state(response)[:mcp_stream_error]
+      end
+
+      # @param response [Faraday::Response, NormalizedResponse] a completed response
+      # @return [Hash] the ResponseBodyCapture state of its exchange (empty when none)
+      def capture_state(response)
+        context = if response.respond_to?(:env) && response.env.respond_to?(:request)
+                    response.env.request&.context
+                  elsif response.respond_to?(:context)
+                    response.context
+                  end
+        context.is_a?(Hash) ? context : {}
+      end
+    end
+  end
+end