ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/client/task_lifetimes.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+require_relative '../session_pin'
+
+module MCPClient
+  class Client
+    # Which task a task id names, over the life of one server session.
+    #
+    # A task id is unique within a session, so a server that answers with an
+    # id it has already handed out has ended that task and started another:
+    # every CreateTaskResult begins a lifetime of its own, and a wait, a hold,
+    # an answer or a cancel of one lifetime never reaches another. A lifetime
+    # is a number drawn from the session's own counter, never reused and
+    # never restarted, so two lifetimes stay distinguishable even after the
+    # counters of the ids created longest ago are pruned.
+    #
+    # A request is bound to the lifetime it is about (see {#task_lifetime_pin})
+    # rather than cleared by a preflight: the binding is checked at the wire,
+    # where a CreateTaskResult a concurrent call records is already visible,
+    # and again before the answer is acted on. Mixed into {TaskRegistry},
+    # whose task states and in-flight key registry it reads to decide what a
+    # prune may forget.
+    module TaskLifetimes
+      # How many task ids one client keeps a lifetime counter for. The counter
+      # has to outlive the task's own bookkeeping — that is the point: a
+      # creation under an id this client has already seen is a different task,
+      # whether or not anything of the previous one is still around — so on a
+      # sessionless connection, where the epoch never moves and nothing else
+      # prunes it, the map would otherwise grow with every task ever created.
+      # It bounds the ids of tasks that are over: a task still running keeps
+      # its lifetime however many ids follow it (see {#prune_task_lifetimes}).
+      MAX_TRACKED_TASK_LIFETIMES = 4096
+      # How far a prune goes once the cap is passed: dropping a batch keeps the
+      # scan amortized instead of walking the map on every creation.
+      TRACKED_TASK_LIFETIMES_LOW_WATER = (MAX_TRACKED_TASK_LIFETIMES * 3) / 4
+
+      private
+
+      # Which task the id names now, as a number of its session's counter.
+      # @param lookup [Array] server, session epoch and task id
+      # @return [Integer, nil] nil for an id no creation is on the books for
+      #   (never seen, or crowded out of the counter map)
+      def task_lifetime(lookup)
+        @task_lifetimes&.fetch(lookup, nil)
+      end
+
+      # Begin the lifetime a CreateTaskResult just created, and answer with
+      # it. A task id is unique within a session, so a server that answers
+      # with an id it has already handed out in this session has ended that
+      # task and started another: the bookkeeping of the previous lifetime is
+      # dropped and the id's lifetime moves, which gives the new task an
+      # answered set, an in-flight registry entry and a pending update
+      # entirely of its own. Without the move, an input key a handler of the
+      # previous task is still presenting would be suppressed as already in
+      # flight on the new one, and that handler's answer would be delivered to
+      # the new task.
+      #
+      # Every creation this client observed counts, whether or not anything of
+      # the previous one is still around: a second CreateTaskResult that
+      # arrives before any wait allocated state, or after a terminal poll (or
+      # a TTL expiry) forgot it, is just as much a different task, and two
+      # handles that named the same lifetime would let the older one update or
+      # cancel the task that replaced it.
+      #
+      # The lifetime is returned rather than read back afterwards: two
+      # concurrent creations of one id take this lock one after the other, and
+      # a second reading would stamp both handles with the later of the two.
+      # @return [Integer] the lifetime this creation started
+      def start_task_lifetime(srv, task_id, epoch)
+        answered_keys_mutex.synchronize do
+          lookup = [srv.object_id, registry_epoch(srv, epoch), task_id]
+          @task_states ||= {}
+          drop_ended_session_state(lookup)
+          lifetimes = (@task_lifetimes ||= {})
+          generation = next_task_lifetime(lookup)
+          # Re-inserted, so the ids created most recently are the last a prune
+          # reaches (a Hash keeps a rewritten key where it was).
+          lifetimes.delete(lookup)
+          lifetimes[lookup] = generation
+          # The task exists from here until something says it is over, and its
+          # own bookkeeping — never the replaced task's — says so: a live
+          # entry is what keeps the prune below off the lifetime the handle
+          # this creation produces names.
+          @task_states[lookup] = new_task_state(lookup)
+          prune_task_lifetimes(lifetimes)
+          generation
+        end
+      end
+
+      # The next lifetime number of a server session: one counter for the
+      # whole session rather than one per id, so a number is never handed out
+      # twice in it and a task id crowded out of the map (see
+      # {#prune_task_lifetimes}) cannot be created again at a number some
+      # handle of the pruned lifetime still names.
+      # @param lookup [Array] server, session epoch and task id
+      # @return [Integer] (callers hold answered_keys_mutex)
+      def next_task_lifetime(lookup)
+        counters = (@task_lifetime_counters ||= {})
+        session = lookup.first(2)
+        counter = counters[session] || 0
+        counters[session] = counter + 1
+        counter
+      end
+
+      # A previous session of this server is over: the lifetimes counted in it
+      # go too, the session's counter with them — the epoch alone already
+      # separates them from the next session's.
+      # @return [void] (callers hold answered_keys_mutex)
+      def drop_ended_lifetimes(lookup)
+        @task_lifetimes&.delete_if { |other, _| other[0] == lookup[0] && other[1] < lookup[1] }
+        @task_lifetime_counters&.delete_if { |other, _| other[0] == lookup[0] && other[1] < lookup[1] }
+      end
+
+      # Forget the lifetimes of the task ids created longest ago, once more of
+      # them are kept than {MAX_TRACKED_TASK_LIFETIMES}. A handle of a
+      # forgotten lifetime is refused rather than let through (see
+      # {#check_task_lifetime_locked!}): the session's counter never restarts,
+      # so a later creation under a pruned id is a number of its own and can
+      # never read as the lifetime such a handle names.
+      #
+      # Only the lifetimes of tasks this client no longer tracks are
+      # forgotten. A creation records the task's bookkeeping (see
+      # {#start_task_lifetime}) and a terminal poll, a cancellation, a TTL
+      # expiry or a `TaskNotFound` drops it again, so what the cap bounds is
+      # the ids of tasks that have ended — never a handle whose task is still
+      # running, whose absence from the registry the client has no business
+      # reading as the task being over. An id whose keys a handler is still
+      # presenting stays too: an abandoned handler outlives the bookkeeping,
+      # and its holds name the lifetime they belong to.
+      # @return [void] (callers hold answered_keys_mutex)
+      def prune_task_lifetimes(lifetimes)
+        return if lifetimes.size <= MAX_TRACKED_TASK_LIFETIMES
+
+        # A snapshot: the entries are deleted as the scan walks them.
+        tracked = lifetimes.keys
+        tracked.each do |lookup|
+          break if lifetimes.size <= TRACKED_TASK_LIFETIMES_LOW_WATER
+          next if @task_states&.key?(lookup) || presenting_earlier_lifetime?(lookup)
+
+          lifetimes.delete(lookup)
+        end
+      end
+
+      # Whether a handler is still presenting the input keys of some lifetime
+      # of this task id (an abandoned handler outlives its state).
+      # @return [Boolean] (callers hold answered_keys_mutex)
+      def presenting_earlier_lifetime?(lookup)
+        return false unless @in_flight_keys
+
+        @in_flight_keys.any? { |key, held| key.first(3) == lookup && !held.empty? }
+      end
+
+      # Whether the bookkeeping a request was built from is still what its
+      # task id names: a CreateTaskResult that handed the id out again since
+      # started a different task, and the request belongs to the previous one.
+      # @param state [Hash] the bookkeeping the request captured
+      # @return [Boolean]
+      def task_lifetime_current?(state)
+        answered_keys_mutex.synchronize { task_lifetime(state[:lookup]) == state[:generation] }
+      end
+
+      # The lifetime a handle refreshed from another one keeps: the one the
+      # source handle named, when that handle is this server's. A request
+      # that named its task with a bare id (or with another server's handle)
+      # asks about whatever the id means now and produces a handle that says
+      # the same, exactly as before — but a handle built from one that named
+      # a definite task must keep naming it, or a later creation under the id
+      # would silently move it to the task that replaced it.
+      # @param task [Object] what the caller named the task with
+      # @return [Integer, nil]
+      def handle_task_generation(task, srv)
+        return nil unless task.is_a?(MCPClient::Task) && task.server.equal?(srv)
+
+        task.task_generation
+      end
+
+      # Bind a request to the task it is about, and refuse it here and now if
+      # that task is already gone.
+      #
+      # A handle from a creation names a definite task: the request is for
+      # that lifetime and no other, and the pin holds the transport to it at
+      # the wire (see {#pinned_to_lifetime}) as well as the answer to it
+      # afterwards (see {#verify_task_lifetime!}). A bare id, a handle from
+      # another server and a handle that never came from a creation name
+      # whatever the id means now and are let through, exactly as before —
+      # their pin only records which lifetime that was, so what the request
+      # forgets on the way out is that lifetime's and never a replacement's.
+      # @param task [Object] what the caller named the task with
+      # @param task_id [String] the id the request carries
+      # @param epoch [Integer, nil] the session the request is pinned to
+      # @param operation [String] for the error message ('updating', 'waiting for')
+      # @return [Hash] the pin
+      # @raise [MCPClient::Errors::TaskReplacedError] if the handle's task was replaced
+      def task_lifetime_pin(task, task_id, srv, epoch, operation)
+        named = handle_task_generation(task, srv)
+        pin = { lookup: [srv.object_id, registry_epoch(srv, epoch), task_id], generation: named, named: !named.nil?,
+                task_id: task_id, operation: operation }
+        answered_keys_mutex.synchronize do
+          pin[:generation] = task_lifetime(pin[:lookup]) unless pin[:named]
+          check_task_lifetime_locked!(pin)
+        end
+        pin
+      end
+
+      # Run the block with the transport refusing to write once the task id
+      # names another task than the request is about. The check happens where
+      # the session pin's does — immediately before the wire, so a
+      # CreateTaskResult a concurrent call records while this request is being
+      # built (or while its session is being established) is seen, and the
+      # request is not sent for a task that is already gone. A transport that
+      # knows no write guard sends as before.
+      # @param pin [Hash, nil] the request's lifetime pin
+      # @return [Object] the block's value
+      def pinned_to_lifetime(srv, pin, &block)
+        return block.call if pin.nil? || !pin[:named] || !srv.respond_to?(:guarded_writes)
+
+        srv.guarded_writes(-> { check_task_lifetime!(pin) }, &block)
+      end
+
+      # The answer of a request is acted on only while the task it named is
+      # still what its id names: a creation that landed while the answer was
+      # in flight makes the answer the previous task's, and the handle,
+      # the delivered result and the bookkeeping cleanup it drives would all
+      # be about a task that is gone.
+      # @param pin [Hash, nil] the request's lifetime pin
+      # @return [void]
+      # @raise [MCPClient::Errors::TaskReplacedError]
+      def verify_task_lifetime!(pin)
+        check_task_lifetime!(pin) if pin
+      end
+
+      # @return [void]
+      # @raise [MCPClient::Errors::TaskReplacedError]
+      def check_task_lifetime!(pin)
+        answered_keys_mutex.synchronize { check_task_lifetime_locked!(pin) }
+      end
+
+      # {#check_task_lifetime!} for a caller already holding the registry lock.
+      # @return [void] (callers hold answered_keys_mutex)
+      # @raise [MCPClient::Errors::TaskReplacedError]
+      def check_task_lifetime_locked!(pin)
+        return unless pin[:named]
+
+        current = task_lifetime(pin[:lookup])
+        return if current == pin[:generation]
+
+        raise MCPClient::Errors::TaskReplacedError, replaced_task_message(pin, current)
+      end
+
+      # @param current [Integer, nil] the lifetime the id names now
+      # @return [String]
+      def replaced_task_message(pin, current)
+        shown = shown_task_id(pin[:task_id])
+        if current.nil?
+          # Crowded out of the counter map (or forgotten with the client's
+          # state): what the id names now cannot be told from what the handle
+          # names, so the request is refused rather than sent on a guess.
+          return "Error #{pin[:operation]} task '#{shown}': this client no longer tracks the task this handle " \
+                 'names (the session created task ids enough to crowd it out), so the request is refused rather ' \
+                 'than sent for whatever answers to the id now'
+        end
+
+        "Error #{pin[:operation]} task '#{shown}': the server has created a new task with this id since, so the " \
+          'task this handle names was replaced and is gone'
+      end
+    end
+  end
+end

data/lib/mcp_client/client/task_registry.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative 'task_lifetimes'
+
+module MCPClient
+  class Client
+    # The per-task bookkeeping of the tasks extension: the answered and
+    # in-flight input keys, the rounds spent and the pending update of each
+    # task, all keyed by the server session they belong to. Task ids are per
+    # session and reusable, so every entry dies with its session — and every
+    # request that names a task carries the session it is about. Inside one
+    # session an id is reusable too: every CreateTaskResult starts a fresh
+    # lifetime under it, and a wait, a hold or an answer of one lifetime never
+    # reaches another — which lifetime a task id names, and which one a
+    # request is bound to, lives in {TaskLifetimes}. Mixed into
+    # {MCPClient::Client} through {TaskSupport}.
+    module TaskRegistry
+      # Which task a reusable id names, and how a request is bound to it.
+      include TaskLifetimes
+
+      private
+
+      # Per-task bookkeeping shared by every wait on the task: the answered
+      # keys, the input rounds spent, an update still to be delivered and
+      # the lock that serializes its updates. Task ids are per server
+      # session (a restarted stdio process may reuse them), so the state is
+      # keyed by the transport's session epoch too and dies with it. The
+      # epoch is read under the lock and never runs backwards: a caller
+      # that read it before a restart gets the current session's state and
+      # cannot delete it or bring an older session back.
+      # @return [Hash]
+      def task_state(srv, task_id)
+        answered_keys_mutex.synchronize { task_state_locked(srv, task_id, current_session_epoch(srv)) }
+      end
+
+      # {#task_state} for a caller already holding the registry lock and the
+      # epoch it read under it.
+      # @return [Hash]
+      def task_state_locked(srv, task_id, epoch)
+        @task_states ||= {}
+        lookup = [srv.object_id, epoch, task_id]
+        drop_ended_session_state(lookup)
+        @task_states[lookup] ||= new_task_state(lookup)
+      end
+
+      # A task's bookkeeping, stamped with the lifetime of its id (see
+      # {#start_task_lifetime}). The state carries both keys: `lookup`, under
+      # which the live task of an id is found, so a request that captured the
+      # state can drop exactly what it was working on (see #forget_task_keys)
+      # and never a later lifetime of the same id; and `key`, which names the
+      # lifetime itself and under which the in-flight holds of a running
+      # handler live, so two lifetimes of one id never share them.
+      # @param lookup [Array] server, session epoch and task id
+      # @return [Hash] (callers hold answered_keys_mutex)
+      def new_task_state(lookup)
+        generation = task_lifetime(lookup)
+        { key: [*lookup, generation], lookup: lookup, generation: generation, answered: Set.new,
+          submitted: Set.new, rounds: 0, pending_update: nil, update_mutex: Mutex.new,
+          answer_seq: 0, pending_at: {} }
+      end
+
+      # A previous session of this server is over: its state (answered keys,
+      # pending answers) and the id lifetimes counted in it are dropped, not
+      # left behind — the epoch alone already separates them from the next
+      # session's.
+      # @return [void] (callers hold answered_keys_mutex)
+      def drop_ended_session_state(lookup)
+        @task_states.delete_if { |other, _| other[0] == lookup[0] && other[1] < lookup[1] }
+        drop_ended_lifetimes(lookup)
+      end
+
+      # Forget the bookkeeping of the sessions a cleanup ended.
+      #
+      # Ending a connection is not ending a session — a 2026-07-28 HTTP
+      # transport is sessionless, and its tasks outlive a cleanup — and the
+      # bookkeeping of a task that survives survives with it: the keys it has
+      # already answered are still answered (a wait resumed after the cleanup
+      # would otherwise put the same input request to the host a second time)
+      # and an update the server never acknowledged is still owed to it. What
+      # a session that did end left behind goes now rather than on the next
+      # lookup, so a cleanup still releases what nothing can reach.
+      #
+      # What an id names is not bookkeeping and does not go with either. The
+      # lifetimes and, above all, the session counters that number them stay:
+      # restarting a counter would hand a task created after the cleanup the
+      # number a handle from before it still names, and that handle would then
+      # update or cancel the task that replaced its own. A session that does
+      # end takes its lifetimes with it as before (see
+      # {#drop_ended_session_state}), and the ids of tasks nothing tracks any
+      # more are pruned (see {#prune_task_lifetimes}), so what is kept stays
+      # bounded.
+      # @return [void]
+      def clear_task_states
+        answered_keys_mutex.synchronize do
+          # Read after the transports cleaned up: a session the cleanup ended
+          # has moved the epoch by now, and its state is what goes.
+          live = servers.to_h { |srv| [srv.object_id, current_session_epoch(srv)] }
+          @task_states&.delete_if { |lookup, _| live[lookup[0]] != lookup[1] }
+          # The keys a handler is still presenting belong to a lifetime of a
+          # session, and are kept exactly as long as that session is.
+          @in_flight_keys&.delete_if { |key, _| live[key[0]] != key[1] }
+          @task_states = nil if @task_states.is_a?(Hash) && @task_states.empty?
+          @in_flight_keys = nil if @in_flight_keys.is_a?(Hash) && @in_flight_keys.empty?
+        end
+      end
+
+      # The server's session epoch as this client knows it, monotonic: the
+      # highest value ever read wins, so a stale reading never reopens an
+      # ended session. Callers hold answered_keys_mutex or do not care about
+      # a concurrent bump (the next task_state resolves it).
+      # @return [Integer]
+      def current_session_epoch(srv)
+        read = srv.respond_to?(:session_epoch) ? srv.session_epoch : 0
+        @task_session_epochs ||= {}.compare_by_identity
+        seen = @task_session_epochs[srv] || 0
+        @task_session_epochs[srv] = [read, seen].max
+      end
+
+      # The session an explicit request for a task handle belongs to. Task
+      # ids are per session and reusable, so a handle a host kept across a
+      # restart names a task that no longer exists: the request is refused
+      # rather than sent into the session that replaced it, where the same id
+      # may name something else. A bare task id, a handle from another
+      # server, or a server that reports no session names whatever the live
+      # session knows and carries no pin.
+      # @param task [Object] what the caller named the task with
+      # @param operation [String] for the error message ('updating', 'cancelling')
+      # @return [Integer, nil] the epoch to pin the request to
+      # @raise [MCPClient::Errors::TaskError] if the handle's session has ended
+      def handle_session_epoch(task, srv, operation)
+        return nil unless task.is_a?(MCPClient::Task) && task.server.equal?(srv) && task.session_epoch
+
+        epoch = task.session_epoch
+        return epoch if answered_keys_mutex.synchronize { current_session_epoch(srv) } == epoch
+
+        raise MCPClient::Errors::TaskError,
+              "Error #{operation} task '#{shown_task_id(task.task_id)}': the server session it belongs to has " \
+              'ended, so the task is gone (a restarted server may reuse its id for an unrelated task)'
+      end
+
+      # The session a task request that named its task with a bare id belongs
+      # to: the one live when the caller asked. Task ids are per session and
+      # reusable, so a request that is only written (or replayed, after an
+      # HTTP 404 restarted the session) once the session has moved would
+      # read, cancel or answer whatever the replacement session named with
+      # the same id. A server that reports no session carries no pin.
+      # @return [Integer, nil] the epoch to pin the request to
+      def invocation_session_epoch(srv)
+        return nil unless srv.respond_to?(:session_epoch)
+
+        begin
+          # The session comes up before it is sampled: the transports connect
+          # lazily inside the request itself, and that first connection ends
+          # the session the epoch was read in — a pin taken before it would
+          # refuse the very request that establishes the session.
+          establish_session(srv)
+        rescue StandardError
+          # Not this method's failure to report: the request that follows
+          # sends (and fails) exactly as it would have.
+          nil
+        end
+        answered_keys_mutex.synchronize { current_session_epoch(srv) }
+      end
+
+      # The epoch a request's bookkeeping is keyed by: the session it was
+      # pinned to, or — for a request that carries no pin, e.g. on a
+      # transport that reports no session — the one live now. A transport
+      # without a session epoch reports 0 from every lookup path, so a nil
+      # pin must resolve to that same key and never to a key of its own.
+      # @param epoch [Integer, nil] the session the request is pinned to
+      # @return [Integer]
+      def registry_epoch(srv, epoch)
+        epoch.nil? ? current_session_epoch(srv) : epoch
+      end
+
+      # @return [Array] where a task id's live bookkeeping is found in the
+      #   session live at this call (callers hold answered_keys_mutex)
+      def task_state_lookup(srv, task_id)
+        [srv.object_id, current_session_epoch(srv), task_id]
+      end
+
+      # @return [Array] the registry key of the current lifetime of a task id,
+      #   under which its in-flight holds live (callers hold answered_keys_mutex)
+      def task_state_key(srv, task_id)
+        lookup = task_state_lookup(srv, task_id)
+        [*lookup, task_lifetime(lookup)]
+      end
+
+      # @return [Mutex] guards the answered-key registry (request threads share the client)
+      def answered_keys_mutex
+        @answered_keys_mutex ||= Mutex.new
+      end
+
+      # Drop a task's bookkeeping: it is terminal, cancelled, gone or past
+      # its TTL, so nothing of it may colour a later task with the same id.
+      # @param state [Hash, nil] the bookkeeping the caller was working on;
+      #   only that very state is dropped, so a request abandoned on the
+      #   wait's wall clock cannot, on its late completion, wipe what a new
+      #   session — or a new lifetime of a reused task id — has recorded
+      #   since. Without one, the state of the session the request was about
+      #   is dropped (the current one when that session is not known either).
+      # @param epoch [Integer, nil] the session the request that reported the
+      #   task gone (or terminal) was pinned to
+      # @param pin [Hash, nil] the lifetime the request was bound to, when no
+      #   state was captured: a creation that landed while the answer was in
+      #   flight made the task the answer describes a past one, and what the
+      #   id keys now belongs to the task that replaced it — a live occupancy
+      #   a terminal (or missing) answer about its predecessor must not wipe
+      # @return [void]
+      def forget_task_keys(srv, task_id, state: nil, epoch: nil, pin: nil)
+        answered_keys_mutex.synchronize do
+          unless state
+            lookup = epoch.nil? ? task_state_lookup(srv, task_id) : [srv.object_id, epoch, task_id]
+            next if pin && task_lifetime(lookup) != pin[:generation]
+
+            @task_states&.delete(lookup)
+            next
+          end
+          next unless @task_states && @task_states[state[:lookup]].equal?(state)
+
+          @task_states.delete(state[:lookup])
+        end
+      end
+
+      NO_KEYS = Set.new.freeze
+      private_constant :NO_KEYS
+
+      # Keys a running handler presents, kept apart from the task's
+      # bookkeeping so no forget lets a retry present them again meanwhile.
+      # A read allocates nothing; the reservation that holds keys asks for
+      # the set to be created and receives its registry key with it.
+      # @param key [Array, nil] the registry key to use; without one the
+      #   current lifetime's is resolved (a caller working on the state a wait
+      #   captured passes that state's key, so neither a restart nor a task id
+      #   handed out again can move its reservation to what replaced it)
+      # @return [Set<String>, Array(Set<String>, Array)] (callers hold answered_keys_mutex)
+      def in_flight_task_keys(srv, task_id, create: false, key: nil)
+        key ||= task_state_key(srv, task_id)
+        return [(@in_flight_keys ||= {})[key] ||= Set.new, key] if create
+
+        @in_flight_keys&.fetch(key, nil) || NO_KEYS
+      end
+
+      # Drop a registry entry once its own set is empty; another task's or
+      # session's entry is never touched.
+      # @return [void] (callers hold answered_keys_mutex)
+      def release_in_flight_entry(held, held_key)
+        return unless held.empty? && @in_flight_keys && @in_flight_keys[held_key].equal?(held)
+
+        @in_flight_keys.delete(held_key)
+      end
+    end
+  end
+end

data/lib/mcp_client/client/task_shape.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative '../task'
+require_relative '../errors'
+
+module MCPClient
+  class Client
+    # The shape checks of MCP 2026-07-28 task payloads (Task, DetailedTask
+    # and the payload a status implies), shared by the task support.
+    module TaskShape
+      private
+
+      # A modern tasks/get result is a DetailedTask: every field the Task
+      # shape requires must be there (ttlMs may be null but must be
+      # present), since a defaulted status or a missing TTL would drive the
+      # wait on made-up state.
+      # @param result [Object] the raw tasks/get result
+      # @return [void]
+      # @raise [MCPClient::Errors::InvalidResultError]
+      def validate_detailed_task_shape!(result)
+        problem = detailed_task_shape_problem(result)
+        raise MCPClient::Errors::InvalidResultError, "Invalid tasks/get result: #{problem}" if problem
+      end
+
+      # @return [String, nil] what is wrong with a DetailedTask's shape
+      def detailed_task_shape_problem(result)
+        task_shape_problem(result) || task_status_payload_problem(result)
+      end
+
+      # The fields every Task carries (CreateTaskResult and DetailedTask
+      # alike): a status, parseable timestamps, a ttlMs key and, when the
+      # server offers one, a usable pollIntervalMs.
+      # @param result [Object]
+      # @return [String, nil]
+      def task_shape_problem(result)
+        return 'not an object' unless result.is_a?(Hash)
+        return 'taskId is not a string' unless result['taskId'].is_a?(String)
+        return 'status is not a task status' unless MCPClient::Task::VALID_STATUSES.include?(result['status'])
+
+        problem = task_timestamp_problem(result)
+        return problem if problem
+        return 'ttlMs is missing' unless result.key?('ttlMs')
+        return 'ttlMs is not an integer or null' unless result['ttlMs'].nil? || result['ttlMs'].is_a?(Integer)
+
+        task_poll_interval_problem(result)
+      end
+
+      # pollIntervalMs is the pace the client is asked to keep ("Clients
+      # SHOULD respect the pollIntervalMs provided in responses"), so a
+      # malformed one is a malformed task rather than a hint to ignore:
+      # silently falling back to the default would poll at a rate the server
+      # never asked for. An absent field (and an explicit null) asks for
+      # nothing and is not a problem.
+      # @return [String, nil]
+      def task_poll_interval_problem(result)
+        interval = result['pollIntervalMs']
+        return nil if interval.nil?
+        return nil if interval.is_a?(Integer) && !interval.negative?
+
+        'pollIntervalMs is not a non-negative integer'
+      end
+
+      # The timestamps of a Task are ISO 8601; one that does not parse could
+      # never bound a wait, so it is not a task at all.
+      # @return [String, nil]
+      def task_timestamp_problem(result)
+        %w[createdAt lastUpdatedAt].each do |field|
+          return "#{field} is not a string" unless result[field].is_a?(String)
+          return "#{field} is not an ISO 8601 timestamp" unless iso8601?(result[field])
+        end
+        nil
+      end
+
+      # @return [Boolean]
+      def iso8601?(text)
+        Time.iso8601(text)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      # The payload a DetailedTask's status implies ("If status is completed,
+      # result MUST be included; if failed, error; if input_required,
+      # inputRequests").
+      # @return [String, nil]
+      def task_status_payload_problem(result)
+        case result['status']
+        when 'completed'
+          unless MCPClient::Task.complete_result_object?(result['result'])
+            'a completed task needs an object result whose resultType, if any, is "complete"'
+          end
+        when 'failed'
+          unless MCPClient::Task.jsonrpc_error_object?(result['error'])
+            'a failed task needs a JSON-RPC error object (integer code, string message)'
+          end
+        when 'input_required'
+          'an input_required task needs an inputRequests object' unless result['inputRequests'].is_a?(Hash)
+        end
+      end
+    end
+  end
+end