ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/client/task_updates.rb

@@ -0,0 +1,457 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module MCPClient
+  class Client
+    # The tasks/update delivery path of the MCP 2026-07-28 tasks extension:
+    # which keys count as answered, the pending payload an unconfirmed
+    # delivery leaves behind, and the session guard that keeps the answers of
+    # an ended session out of the next one. Mixed into {TaskSupport}, which
+    # owns the polling loop these deliveries run in.
+    module TaskUpdates
+      private
+
+      # Record keys whose answers were handed to the transport by
+      # {#update_task}: they stay answered even if a handler that reserved
+      # them fails afterwards.
+      # @return [void]
+      def remember_answered_keys(srv, task_id, keys)
+        remember_answered_keys_in(task_state(srv, task_id), keys)
+      end
+
+      # @param state [Hash] the task state the update is bound to
+      # @return [void]
+      def remember_answered_keys_in(state, keys)
+        answered_keys_mutex.synchronize do
+          state[:answered].merge(keys)
+          state[:submitted].merge(keys)
+        end
+      end
+
+      # Whether a tasks/update failure means the server definitely did not
+      # take the answers: a JSON-RPC error with a code from the server
+      # itself. A 5xx, a closed response stream or any untyped server error
+      # is ambiguous (the update may have been applied).
+      # @param error [MCPClient::Errors::ServerError]
+      # @return [Boolean]
+      def definite_rejection?(error)
+        error.code.is_a?(Integer) && !error.is_a?(MCPClient::Errors::TransientServerError)
+      end
+
+      # Give back the keys a definite rejection did not carry away, and drop
+      # what they left pending: one step, so an answer another delivery
+      # queues meanwhile keeps both its marker and its payload — deciding
+      # ownership and acting on it apart would let a newer answer land in
+      # between and be unmarked by this one. Nothing is given back once the
+      # wait abandoned this send and a retry holds the task's update lock:
+      # what that retry left is not this send's to release.
+      # @param state [Hash] the task state the rejected update was bound to
+      # @param lock [Mutex] the update lock this send holds
+      # @param input_responses [Hash] what the rejected update carried
+      # @return [void]
+      def release_rejected_update(state, lock, input_responses)
+        answered_keys_mutex.synchronize do
+          next unless state[:update_mutex].equal?(lock)
+
+          keys = rejected_keys_of(state, input_responses)
+          state[:answered].subtract(keys)
+          state[:submitted].subtract(keys)
+          drop_pending_keys(state, keys)
+        end
+      end
+
+      # Which of a rejected delivery's keys it still owns: the ones whose
+      # pending value is still the very value it carried. A key another
+      # update answered while this one was on the wire belongs to that
+      # newer delivery — it holds the pending value, it is sending it, and
+      # unmarking the key here would leave it unrecorded, so a later poll
+      # would put the same input request to the host again.
+      # @param state [Hash] the task state the rejected update was bound to
+      # @param input_responses [Hash] what that update carried
+      # @return [Array<String>] the keys to give back (callers hold answered_keys_mutex)
+      def rejected_keys_of(state, input_responses)
+        pending = state[:pending_update] || {}
+        input_responses.reject { |key, value| pending.key?(key) && !pending[key].equal?(value) }
+                       .keys.map(&:to_s)
+      end
+
+      # Give back keys the server definitely did not take, in the state the
+      # rejected update was built from: a rejection that lands after a
+      # restart must not unmark keys the new session has answered for what
+      # is a different request.
+      # @param state [Hash] the task state the update was bound to
+      # @return [void]
+      def release_answered_keys_in(state, keys)
+        answered_keys_mutex.synchronize do
+          state[:answered].subtract(keys)
+          state[:submitted].subtract(keys)
+        end
+      end
+
+      # Send the answers a handler produced (or, with pending_only, only what
+      # an earlier ambiguous delivery left pending), bounded by the caller's
+      # timeout and carrying the session the answers belong to. An ambiguous
+      # delivery (the server may or may not have applied it) is not the end
+      # of the wait: the payload stays pending and goes out again with the
+      # next poll, like a lost tasks/get. A definite rejection surfaces.
+      # @return [void]
+      def deliver_task_update(srv, task_id, responses, wait, pending_only: false, outstanding: nil, observed_at: nil)
+        # The bookkeeping this delivery is bound to is captured here, before
+        # anything is sent: a session that restarts meanwhile must not make
+        # the send record its keys, drop its pending payload or release them
+        # in another session's state (the epoch guard drops the payload
+        # instead), and an abandoned send finishes against this very state.
+        # It is the wait's own state — the one the answers were built in —
+        # not whatever the live session now keys under the same id: a
+        # delivery the pin drops must not give back keys a concurrent wait
+        # has reserved in the session that replaced it.
+        state = wait[:state] || task_state(srv, task_id)
+        bounded_by_wait(wait, deadline: wait[:deadline],
+                              on_abandon: ->(_runner) { abandon_task_update(state) }) do
+          send_task_update(srv, task_id, responses, epoch: wait[:epoch], pending_only: pending_only, state: state,
+                                                    outstanding: outstanding, observed_at: observed_at,
+                                                    timeout: request_timeout(wait_deadline(wait), srv))
+        end
+      rescue MCPClient::Errors::TaskError => e
+        raise unless ambiguous_update_failure?(e)
+
+        logger.debug("tasks/update for task #{shown_task_id(task_id)} could not be confirmed; " \
+                     'it is sent again on the next poll')
+      end
+
+      # One tasks/update, owning the pending-payload lifecycle: the keys are
+      # answered as soon as the payload is handed to the transport; the
+      # request carries every response still pending from an earlier
+      # ambiguous delivery (the server ignores keys it already has, so a
+      # resend is safe and no unconfirmed answer is left behind); a
+      # confirmed delivery clears the pending payload (a later answer
+      # supersedes a lost one); a definite JSON-RPC rejection gives the keys
+      # back and drops the payload; an ambiguous outcome (timeout, transport
+      # or connection failure, 5xx, untyped server error) keeps it pending
+      # for retransmission.
+      # @param timeout [Numeric, nil] request timeout, bounded by the wait when there is one
+      # @param pending_only [Boolean] send whatever is pending under the lock and nothing else
+      #   (a retransmission; nothing pending sends nothing)
+      # @param epoch [Integer, nil] the session epoch the answers were produced in; the update is
+      #   dropped when the server's session moved on since (nil: no expectation, e.g. #update_task)
+      # @param state [Hash, nil] the bookkeeping the answers were built from; every mutation
+      #   (answered keys, pending payload) lands there and nowhere else
+      # @param outstanding [Set<String>, nil] for a retransmission, the input request keys the task
+      #   still lists: a pending answer to any other key was consumed and is dropped, not resent
+      #   (nil: not known, everything pending is sent)
+      # @return [true]
+      # @raise [MCPClient::Errors::TaskError, MCPClient::Errors::ServerError]
+      def send_task_update(srv, task_id, input_responses, timeout: nil, pending_only: false, epoch: nil, state: nil,
+                           strict_session: false, outstanding: nil, observed_at: nil)
+        shown = shown_task_id(task_id)
+        state ||= task_state(srv, task_id)
+        # The answers are pending — and their keys answered — from the moment
+        # this delivery is queued, before it waits for the task's update
+        # lock: a wait that gives up while queued behind a hanging update
+        # (its wall clock ran out) must leave answers the next wait can
+        # retransmit, not keys marked answered with nothing to send. An
+        # explicit answer is newer than a pending one for the same key and
+        # wins the merge.
+        queue_task_update(state, input_responses) unless pending_only
+        # One update at a time per task: a concurrent update that read an
+        # empty pending slot could otherwise confirm and wipe an answer
+        # another delivery had just left pending.
+        lock = state[:update_mutex]
+        lock.synchronize do
+          payload = answered_keys_mutex.synchronize { state[:pending_update] }
+          if pending_only && outstanding && payload
+            payload = still_outstanding(state, payload, outstanding, shown, observed_at)
+          end
+          # An explicit answer goes out even when it adds nothing to send
+          # (#update_task with no responses is the caller's request, not a
+          # retransmission).
+          payload = input_responses if payload.nil? && !pending_only
+          return true if payload.nil?
+
+          dispatch_task_update(srv, task_id, payload, shown: shown, state: state, lock: lock,
+                                                      timeout: timeout, epoch: epoch,
+                                                      strict_session: strict_session)
+        end
+      end
+
+      # What a retransmission may carry: the pending answers the task still
+      # asks for. The rest was consumed (its acknowledgement was lost, not
+      # the update) and is dropped from the payload for good — the keys stay
+      # answered — so the update names only outstanding requests, as the
+      # extension requires, and a server rejecting a stale key cannot fail
+      # a task that is progressing normally.
+      # @param observed_at [Integer, nil] the answer sequence this observation
+      #   was issued at: an answer queued after the poll went out is newer than
+      #   anything the poll can testify about (nil: not known, nothing is retired)
+      # @return [Hash, nil] the payload left to send (callers hold the update lock)
+      def still_outstanding(state, payload, outstanding, shown, observed_at = nil)
+        consumed = payload.keys.reject do |key|
+          outstanding.include?(key.to_s) || newer_than_observation?(state, key, observed_at)
+        end
+        return payload if consumed.empty?
+
+        logger.debug("Task #{shown}: the server consumed the answers to #{consumed.join(', ')} " \
+                     'before acknowledging them; they are not sent again')
+        answered_keys_mutex.synchronize { drop_pending_keys(state, consumed.map(&:to_s)) }
+        remaining = payload.except(*consumed)
+        remaining.empty? ? nil : remaining
+      end
+
+      # Whether an answer is newer than the observation in hand: it was queued
+      # after that poll was issued, so the poll's snapshot was taken before the
+      # answer existed and cannot say the server consumed it. Retiring it on
+      # that evidence would drop the answer for good while its key stays
+      # answered — the host is never asked again and the update is never
+      # resent, and an input request the task keeps asking for strands it for
+      # its whole TTL. Concurrent waits make this ordinary: one wait's poll can
+      # be in flight while another answers the request it is about.
+      # @param key [Object] the pending key
+      # @param observed_at [Integer, nil] the answer sequence the poll was issued at
+      # @return [Boolean]
+      def newer_than_observation?(state, key, observed_at)
+        return false if observed_at.nil?
+
+        queued_at = answered_keys_mutex.synchronize { (state[:pending_at] || {})[key.to_s] }
+        !queued_at.nil? && queued_at > observed_at
+      end
+
+      # Record a delivery's answers before it queues for the task's update
+      # lock: answered (so no handler is asked again) and pending (so any
+      # wait can deliver them).
+      # @return [void]
+      def queue_task_update(state, input_responses)
+        return if input_responses.nil? || input_responses.empty?
+
+        # Marked and kept in one step: a rejection of an older answer to one
+        # of these keys decides what it still owns by the pending payload
+        # (see #rejected_keys_of), and between a mark and a keep done apart
+        # it would still find the older payload there — and unmark a key
+        # this newer answer has just claimed, which nothing marks again once
+        # this answer is acknowledged.
+        keys = input_responses.keys.map(&:to_s)
+        answered_keys_mutex.synchronize do
+          state[:answered].merge(keys)
+          state[:submitted].merge(keys)
+          state[:pending_update] = (state[:pending_update] || {}).merge(input_responses)
+          # When each answer became pending, so an observation can say whether
+          # it is old enough to testify about it (see #still_outstanding).
+          seq = (state[:answer_seq] = state[:answer_seq].to_i + 1)
+          pending_at = (state[:pending_at] ||= {})
+          keys.each { |key| pending_at[key] = seq }
+        end
+      end
+
+      # Whether the answers may still go out: the session they were produced
+      # in must be the one the request is about to reach. The connection is
+      # established first, because the built-in rpc_request initializes (and
+      # so may reconnect, ending the session) inside the very call this
+      # guards; the request itself is then pinned to the session (see
+      # {MCPClient::JsonRpcCommon#pinned_to_session}), so a reconnect between
+      # this compare and the write drops the payload at the wire rather than
+      # sending it into the next session. Task ids and input keys are
+      # session-scoped and reusable, so an answer that arrives in the wrong
+      # session could answer an unrelated request.
+      # @return [Boolean]
+      def task_update_session_current?(srv, shown, epoch)
+        return true unless epoch
+
+        begin
+          establish_session(srv)
+        rescue StandardError
+          # Not swallowed, only overtaken by the session it ended: with the
+          # session still the answers', the caller surfaces the failure
+          # (nothing was sent, the answers stay pending for the next poll).
+          raise if answered_keys_mutex.synchronize { current_session_epoch(srv) } == epoch
+        end
+        return true if answered_keys_mutex.synchronize { current_session_epoch(srv) } == epoch
+
+        logger.warn("Task #{shown}: the session restarted before the answers were sent; they are discarded")
+        false
+      end
+
+      # Bring the transport's session up before the epoch is compared, so a
+      # reconnect happens on this side of the guard. A failure is not
+      # swallowed: nothing is sent, and the caller (which has already
+      # recorded the answers as pending) surfaces it as the ambiguous
+      # delivery failure it is, so the next poll delivers them again.
+      # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError]
+      def establish_session(srv)
+        srv.ensure_session_ready if srv.respond_to?(:ensure_session_ready)
+      end
+
+      # The wire part of {#send_task_update}: the keys are answered and the
+      # payload is pending from the moment it is handed to the transport, so
+      # a wait that abandons this send on its wall clock leaves answers that
+      # are still deliverable (the next wait retransmits them) rather than
+      # keys marked answered with nothing to send. Only the thread that
+      # still holds the task's update lock clears or releases them: once the
+      # wait abandoned this send, the retry that took the lock over owns the
+      # bookkeeping.
+      # @return [true]
+      def dispatch_task_update(srv, task_id, input_responses, shown:, state:, lock:, timeout:, epoch: nil,
+                               strict_session: false)
+        keys = input_responses.keys.map(&:to_s)
+        begin
+          # Checked before the session is established, since it needs nothing
+          # from the wire: a task id the server handed out again names a task
+          # of its own, and these answers were built for the previous one.
+          unless task_lifetime_current?(state)
+            logger.warn("Task #{shown}: the server created a new task with this id before the answers were " \
+                        'sent; they are discarded')
+            drop_ended_session_update(state, lock, keys)
+            return ended_session_update_result(shown, strict_session, replaced: true)
+          end
+          unless task_update_session_current?(srv, shown, epoch)
+            drop_ended_session_update(state, lock, keys)
+            return ended_session_update_result(shown, strict_session)
+          end
+
+          # And held to at the wire, where a creation that lands while the
+          # session is being established is already visible: the check above
+          # cannot see one, and these answers would then be written for the
+          # task that replaced their own.
+          task_rpc(srv, 'tasks/update', { taskId: task_id, inputResponses: input_responses },
+                   timeout: timeout, epoch: epoch, lifetime: state_lifetime_pin(state, task_id))
+          clear_pending_update(state, lock, keys)
+          true
+        rescue MCPClient::Errors::TaskReplacedError
+          # Nothing went out: the transport refused to write answers of a task
+          # the server has replaced (in the new one the keys are a different
+          # request's).
+          logger.warn("Task #{shown}: the server created a new task with this id before the answers were " \
+                      'sent; they are discarded')
+          drop_ended_session_update(state, lock, keys)
+          ended_session_update_result(shown, strict_session, replaced: true)
+        rescue MCPClient::Errors::SessionChangedError
+          # The transport refused to write into the session that replaced the
+          # answers' own: nothing went out, and in the new session these keys
+          # would answer a different request.
+          logger.warn("Task #{shown}: the session restarted before the answers were sent; they are discarded")
+          drop_ended_session_update(state, lock, keys)
+          ended_session_update_result(shown, strict_session)
+        rescue MCPClient::Errors::ServerError => e
+          release_rejected_update(state, lock, input_responses) if definite_rejection?(e)
+          raise if e.protocol_error?
+
+          raise task_failure(e, srv, task_id, 'updating', method: 'tasks/update', state: state)
+        rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+          # Ambiguous (a failure to establish the session included): the
+          # payload stays pending for the next poll.
+          raise MCPClient::Errors::TaskError,
+                "Error updating task '#{shown}': #{sanitize_peer_log_text(e.message)}"
+        end
+      end
+
+      # The lifetime an update is bound to: the one its answers were built in
+      # (see {#task_lifetime_current?}), named so that the transport holds the
+      # write to it as well.
+      # @param state [Hash] the bookkeeping the answers belong to
+      # @return [Hash] the lifetime pin
+      def state_lifetime_pin(state, task_id)
+        { lookup: state[:lookup], generation: state[:generation], named: true,
+          task_id: task_id, operation: 'updating' }
+      end
+
+      # What a delivery the session guard (or the pin at the wire) dropped
+      # reports. A wait polls again and ends on the session move it will see
+      # next, so the drop is not an error for it; a caller that asked for
+      # this very delivery is told that nothing was sent, rather than being
+      # left to believe the server has the answers.
+      # @param replaced [Boolean] the task id was handed out again rather than
+      #   the session having ended
+      # @return [true]
+      # @raise [MCPClient::Errors::TaskError] for a direct #update_task
+      def ended_session_update_result(shown, strict_session, replaced: false)
+        return true unless strict_session
+
+        if replaced
+          raise MCPClient::Errors::TaskError,
+                "Error updating task '#{shown}': the server created a new task with this id before the answers " \
+                'were sent, so they were discarded (they belong to the task it replaced)'
+        end
+
+        raise MCPClient::Errors::TaskError,
+              "Error updating task '#{shown}': the server session the answers belong to ended before they were " \
+              'sent, so they were discarded (a restarted server may reuse the task id for an unrelated task)'
+      end
+
+      # Nothing was written: the keys go back and the payload is dropped, in
+      # the state the answers were built from (the ended session's, which
+      # dies with it).
+      # @return [void]
+      def drop_ended_session_update(state, lock, keys)
+        return unless update_lock_current?(state, lock)
+
+        release_answered_keys_in(state, keys)
+        clear_pending_update(state, lock, keys)
+      end
+
+      # @return [void]
+      def keep_pending_update(state, input_responses)
+        answered_keys_mutex.synchronize do
+          state[:pending_update] = (state[:pending_update] || {}).merge(input_responses)
+        end
+      end
+
+      # Drop from the pending payload what this delivery settled — its own
+      # keys and no others: an answer another delivery queued while this one
+      # was on the wire never went out and must stay deliverable. Nothing is
+      # dropped when the wait abandoned this send and a retry holds the
+      # task's update lock now: what that retry left pending is not this
+      # send's to clear.
+      # @param keys [Array<String>] the keys this delivery carried
+      # @return [void]
+      def clear_pending_update(state, lock, keys)
+        answered_keys_mutex.synchronize do
+          next unless state[:update_mutex].equal?(lock)
+
+          drop_pending_keys(state, keys)
+        end
+      end
+
+      # @param keys [Array<String>] the keys to drop from the pending payload
+      # @return [void] (callers hold answered_keys_mutex)
+      def drop_pending_keys(state, keys)
+        # The order stamps go with the answers they date: a key queued again
+        # later is stamped again, and nothing is ordered against an answer
+        # that is no longer pending.
+        stamps = state[:pending_at]
+        keys.each { |key| stamps.delete(key.to_s) } if stamps
+        pending = state[:pending_update]
+        return if pending.nil?
+
+        remaining = pending.reject { |key, _| keys.include?(key.to_s) }
+        state[:pending_update] = remaining.empty? ? nil : remaining
+      end
+
+      # @return [Boolean] whether this send still holds the task's update lock
+      def update_lock_current?(state, lock)
+        answered_keys_mutex.synchronize { state[:update_mutex].equal?(lock) }
+      end
+
+      # A wait that ran out of wall clock abandons its tasks/update: the
+      # thread keeps the task's update lock for as long as the request hangs
+      # (a transport implementing only rpc_request(method, params) may never
+      # come back), which would block the retransmission the next wait owes
+      # the server. The lock is replaced so that retry can deliver the
+      # answers this send left pending; the abandoned thread finishes
+      # against the state it captured and touches none of it.
+      # @return [void]
+      def abandon_task_update(state)
+        answered_keys_mutex.synchronize { state[:update_mutex] = Mutex.new }
+      end
+
+      # Whether a failed tasks/update may still have been applied.
+      # @param error [MCPClient::Errors::TaskError]
+      # @return [Boolean]
+      def ambiguous_update_failure?(error)
+        cause = error.cause
+        return true if cause.is_a?(MCPClient::Errors::TransportError) || cause.is_a?(MCPClient::Errors::ConnectionError)
+
+        cause.is_a?(MCPClient::Errors::ServerError) && !definite_rejection?(cause)
+      end
+    end
+  end
+end

data/lib/mcp_client/client/task_wait_boundaries.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module MCPClient
+  class Client
+    # The boundaries a wait on a task can cross, and what it may still act on
+    # once it has crossed one.
+    #
+    # A task lives in one server session and, within it, in one lifetime of
+    # its id: a restart ends it, and so does a CreateTaskResult that hands the
+    # id to another task. Either way what the wait was following is gone, and
+    # neither its TTL backstop, nor its pace, nor the answered keys of its
+    # bookkeeping say anything about what answers to that id now. This module
+    # is where the wait joins a session and a lifetime, notices that it has
+    # left one, and decides what a handle it was seeded with — or an answer
+    # that came back across the boundary — is still good for. Mixed into
+    # {TaskSupport}, which owns the polling loop.
+    module TaskWaitBoundaries
+      private
+
+      # What a wait whose session has just ended returns — or raises.
+      #
+      # A task lives in one server session: the session that replaced it may
+      # name an entirely different task with the same id, so the wait never
+      # polls it there. What the ended session already answered is another
+      # matter: a terminal payload that came back from a poll the transport
+      # pinned to that session is this very task's result or error (the pin
+      # holds a request back until the wire, so an answer in hand is the
+      # answer of the session the wait was in), and it is the outcome. Short
+      # of that — no observation, a non-terminal one, or a transport that
+      # cannot pin a request to its session and so cannot vouch for which
+      # session answered — the wait ends: the task did not survive.
+      # @param current [MCPClient::Task, nil] the observation in hand
+      # @param wait [Hash]
+      # @param polled_state [Hash] the bookkeeping the poll belonged to
+      # @param polled_epoch [Integer, nil] the session the poll was sent in
+      # @return [MCPClient::Task] the terminal task
+      # @raise [MCPClient::Errors::TaskError]
+      def outcome_of_ended_session(current, wait, polled_state, polled_epoch)
+        # An answer counts as this wait's outcome only when it is stamped
+        # with the very session the poll was pinned to: a handle carrying
+        # another session's epoch describes another lifetime of the id. A
+        # task id the server handed out again is not that case: the pin is
+        # about sessions, and nothing on the wire tells which of the two
+        # tasks under that id the answer describes — so the wait ends.
+        terminal = wait[:ended] == :session && current&.terminal? &&
+                   observation_of_session?(current, polled_epoch)
+        # Only the bookkeeping of the session the poll asked is forgotten;
+        # the replacement session's is untouched.
+        forget_task_keys(wait[:srv], wait[:task_id], state: polled_state) if terminal
+        end_of_task!(wait) unless terminal && session_pinning?(wait[:srv])
+
+        # A terminal task that came back after the caller's deadline
+        # (transport retries) does not rescue a timed-out wait.
+        raise_if_past_caller_deadline!(wait)
+        current
+      end
+
+      # End a wait whose task is gone: its server session is over and the task
+      # went with it, or the server handed the task id out again — a task id
+      # is unique within a session, so a fresh CreateTaskResult under it ended
+      # the task this wait was following.
+      # @return [void]
+      # @raise [MCPClient::Errors::TaskError]
+      def end_of_task!(wait)
+        shown = shown_task_id(wait[:task_id])
+        if wait[:ended] == :replaced
+          raise MCPClient::Errors::TaskError,
+                "Error waiting for task '#{shown}': the server created a new task with this id, so the task " \
+                'being waited for was replaced and is gone'
+        end
+
+        raise MCPClient::Errors::TaskError,
+              "Error waiting for task '#{shown}': the server session it belongs to ended " \
+              'before the task did, so the task is gone (a restarted server may reuse its id for an unrelated task)'
+      end
+
+      # Whether an observation is about the session it was polled in: the
+      # handle carries the session its request was pinned to. A handle
+      # without one (a server that reports no session), or a poll that
+      # belonged to no session, is taken at its word, as before.
+      # @return [Boolean]
+      def observation_of_session?(task, epoch)
+        task.session_epoch.nil? || epoch.nil? || task.session_epoch == epoch
+      end
+
+      # Whether the transport holds a request back from the session that
+      # replaced the one it belongs to (see {MCPClient::SessionPin}), which
+      # is what makes an answer in hand provably the answer of the session
+      # the wait was in.
+      # @return [Boolean]
+      def session_pinning?(srv)
+        srv.respond_to?(:pinned_to_session)
+      end
+
+      # Point a wait at the task state of the server's current session and
+      # lifetime, and report whether that is one it has not been in before.
+      # What the previous session — or the previous task under this id — said
+      # goes with it: its TTL backstop (createdAt + ttlMs of a task that no
+      # longer exists) must not end the wait in place of the boundary being
+      # crossed, and its last observation must not pace anything. A wait that
+      # reserves keys afterwards reserves them in the new set, since the id
+      # and its keys now name a different request.
+      # @param wait [Hash]
+      # @return [Boolean] whether the wait crossed a boundary, so that
+      #   nothing the previous lifetime said (an observation in hand, its TTL,
+      #   its pace) may be acted on
+      def refresh_wait_session(wait)
+        # The epoch, the lifetime and the state keyed under them are read in
+        # one step, so a restart (or a creation) between them cannot leave the
+        # wait pointing at one task's set while recording another's stamp.
+        answered_keys_mutex.synchronize do
+          epoch = current_session_epoch(wait[:srv])
+          generation = task_lifetime([wait[:srv].object_id, epoch, wait[:task_id]])
+          next false if wait[:epoch] == epoch && wait[:generation] == generation && wait[:answered]
+
+          moved = wait_boundary_crossed(wait, epoch, generation)
+          if moved
+            wait[:ttl_deadline] = nil
+            wait[:last] = nil
+          end
+          wait[:ended] = moved
+          wait[:epoch] = epoch
+          wait[:generation] = generation
+          state = task_state_locked(wait[:srv], wait[:task_id], epoch)
+          wait[:state] = state
+          wait[:answered] = state[:answered]
+          !moved.nil?
+        end
+      end
+
+      # Which boundary the wait has just crossed: the session it was in ended
+      # (:session), or the server handed the task id it is polling out again,
+      # so the task the wait follows is over and another one answers to that
+      # id now (:replaced).
+      # @return [Symbol, nil] nil when the wait is still where it was
+      def wait_boundary_crossed(wait, epoch, generation)
+        return :session if !wait[:epoch].nil? && wait[:epoch] != epoch
+        # The key is absent until the wait first joins a session: a lifetime
+        # of nil is an id no creation is on the books for, and a creation
+        # that gives it one has replaced the task the wait was following.
+        return :replaced if wait.key?(:generation) && wait[:generation] != generation
+
+        nil
+      end
+
+      # A handle that is already final: a DetailedTask of this server whose
+      # terminal payload is authoritative (and which the server may purge any
+      # moment), so there is nothing to poll. Its own lifetime's bookkeeping
+      # dies with the task; a handle kept across a restart — or across a
+      # creation that handed its task id out again — says nothing about what
+      # answers to that id now, where the reused id may name a live task
+      # whose answered keys another wait is deduplicating against.
+      # @return [MCPClient::Task, nil] the task when the wait is already over
+      def final_task_handle(task, srv, wait)
+        return nil unless task.is_a?(MCPClient::Task) && task.detailed? && task.terminal? && task.server.equal?(srv)
+
+        validate_terminal_task!(task)
+        refresh_wait_session(wait)
+        forget_task_keys(srv, wait[:task_id], state: wait[:state]) if seed_of_lifetime?(task, wait)
+        task
+      end
+
+      # Whether a task handle describes the very task whose bookkeeping the
+      # wait is pointing at: the session the wait joined and, within it, the
+      # lifetime the id has now. A handle that names no lifetime (a bare id,
+      # a handle that never came from a creation) cannot claim the live
+      # occupancy of the id: what it describes may be the task that answered
+      # to the id before, and the keys under it now would be another task's.
+      # @return [Boolean]
+      def seed_of_lifetime?(task, wait)
+        seed_of_session?(task, wait) && task.task_generation == wait[:generation]
+      end
+
+      # Take the seed's hints (its TTL backstop and its pace) from a handle
+      # that describes the task this wait is about: the same server, and the
+      # session the wait has joined.
+      # @return [void]
+      def seed_wait_from_handle(task, srv, wait)
+        return unless task.is_a?(MCPClient::Task) && task.server.equal?(srv) && seed_of_session?(task, wait)
+
+        seed_ttl_deadline(task, wait)
+        wait[:last] = task
+      end
+
+      # Whether a task handle may seed the wait: it must come from the
+      # session the wait has joined (a handle a host kept across a restart
+      # describes a task the new session knows nothing about, even when the
+      # id was reused). A server that reports no session (a bare double) is
+      # taken at its word, as before.
+      # @return [Boolean]
+      def seed_of_session?(task, wait)
+        task.session_epoch.nil? || task.session_epoch == wait[:epoch]
+      end
+    end
+  end
+end