vector_mcp 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de0f694bd85fb9d217c352fc907f7d77c27ee3837eea3512c8ca1791c53313c2
-  data.tar.gz: 86f0a7ab8c95e744ef8d80cb77faddaa195cef6636ea9fe175631b01bc0b0982
+  metadata.gz: '09966af580b3bf36b9e17f89ef7b592391c42e63b974a17a1db6a852466b9a56'
+  data.tar.gz: 0d04775542e96421bed373179fbfb13864ddfb0aa8256eabea4fddf966d47860
 SHA512:
-  metadata.gz: c0f1f384fd9d654cc3385a87937c656dee9beaf38e0aeed6f0e92542366c17051615b774b58d1ecc2eb89dd23e6a6737e85e1dcdfb6d4c239a182d0d3c98f31f
-  data.tar.gz: 8d0047290e1033266498f197b94b3d51eb88b700c46e44f15229de985a74eb57889f8381887beb92b0007883244de8f0c53b652a9a8939963f30d3c81fecb406
+  metadata.gz: 33da62c2ffd5dcab4f5e0f7a74426e52885effb4d09c0d82cb479611df838401bfb0de9edb2777a7bb9f21cca190499fa33ff25ee14c46c42a26183b58efa152
+  data.tar.gz: 695aa730c3116bdad34191e3b2b38a0ffea1f10772a2b0e27306f2044b934ab7f576999c13c7bf7568a904af8f82eb8c144830e4a4aebd3aaaec4e8997865430

data/CHANGELOG.md

@@ -1,4 +1,48 @@
-## [Unreleased]
+## [0.6.0] – 2026-07-19
+
+### Added
+
+* **Per-request `VectorMCP::Invocation`**: Each incoming request is now dispatched through its own request-scoped view of the session, carrying that request's `RequestContext` and resolved `Security::SessionContext`. Handlers receive it as their `session` argument; it delegates all session-lived state (`id`, `data`, `initialize!`, `sample`, ...) and additionally exposes the resolved auth API directly (`user`, `authenticated?`, `can?`, ...).
+* **`RequestContext.coerce` and hash-style access**: `RequestContext` is now the single normalization boundary for authentication. It coerces legacy request shapes (raw Rack env, `{headers:, params:}` hashes) in one place and supports `[]`/`dig`/`key?` so custom auth handlers written against the legacy request hash keep working unchanged.
+* **Session lifecycle on `VectorMCP::Session`**: `created_at`, `last_accessed_at`, `touch!`, `expired?(timeout)`, `age`, and a transport-owned `metadata` hash.
+
+### Changed
+
+* **Security fix — request identity isolation**: Concurrent POSTs on one session could previously be authenticated against each other's headers, because request data was stored as mutable state on the shared session. Request-scoped data now travels on the per-request `Invocation` and is never written onto the session.
+* **One `Session` class**: The transport-internal `Session` wrapper structs (in `BaseSessionManager` and `HttpStream::SessionManager`) are gone; session managers store and return `VectorMCP::Session` directly. HTTP streaming connection state lives in the `SessionManager::SessionStreaming` module.
+* **Unified handler interface**: Resource handlers' second argument is now the per-request invocation instead of a bare `Security::SessionContext`. Existing handlers keep working — the invocation forwards the full auth API (`user`, `authenticated?`, `can?`, `user_identifier`, ...; note: not `to_h`) — and additionally gain access to session identity and request data.
+* **Session managers no longer auto-create sessions from client-supplied IDs** (session-fixation hardening in `BaseSessionManager`, matching the existing HTTP stream behavior).
+* Authentication strategies consume `RequestContext` directly; the auth request no longer carries the undocumented `:session_id` key.
+
+### Deprecated (removal in 0.7)
+
+* The request-scoped API on `Session`: `request_context=`, `update_request_context`, `request_headers?`, `request_params?`, `request_header`, `request_param`. These now emit warnings via `VectorMCP.deprecation_warning`; use the per-request invocation passed to handlers instead.
+* The third `session_id` argument of `Server#handle_message` (now optional, defaults to `session.id`; silent deprecation).
+
+## [0.5.0] – 2026-04-22
+
+### Added
+
+* **Token-Based Field Anonymization**: Added a general-purpose anonymization pipeline that substitutes sensitive string fields with stable opaque tokens before tool results reach the LLM and restores them on inbound tool invocations.
+  - `VectorMCP::TokenStore` — thread-safe bidirectional value ↔ token store with idempotent tokenization.
+  - `VectorMCP::Util::TokenSweeper` — stateless recursive traversal utility for parsed JSON structures.
+  - `VectorMCP::Middleware::Anonymizer` — middleware wiring the store and sweeper with application-supplied field rules and optional atomic-key handling; registers via `anonymizer.install_on(server)`.
+
+* **OAuth 2.1 Resource Server mode (HTTP Stream transport)**: `enable_authentication!` now accepts a `resource_metadata_url:` option. When set, unauthenticated requests to `/mcp` return HTTP `401` with a `WWW-Authenticate: Bearer realm="mcp", resource_metadata="<url>"` header (RFC 9728), enabling MCP clients such as Claude Desktop to discover the authorization server and initiate OAuth 2.1 + PKCE flows. Opt-in: when `resource_metadata_url` is not set, the existing JSON-RPC `-32401` behavior is unchanged. See [docs/oauth_resource_server.md](docs/oauth_resource_server.md) and [docs/rails_oauth_integration.md](docs/rails_oauth_integration.md) for end-to-end guidance.
+
+### Changed
+
+* **Auth Result Value Object**: Replaced the internal authentication result hashes with a dedicated `AuthResult` value object for clearer, type-safe handoff between auth strategies and the security middleware.
+* **Consolidated Middleware Hook Types**: `HOOK_TYPES` and `HOOK_OPERATION_TYPES` are now derived from a single source of truth, eliminating drift between the two lists.
+* **Puma Thread Pool Tuning**: Standalone HTTP stream transport now configures the Puma thread pool explicitly for more predictable concurrency behavior.
+* **Event Store Offset Tracking**: Replaced the O(n) event store index rebuild with O(1) offset tracking, reducing overhead for sessions with long event histories.
+* **HTTP Stream Request Tracking**: Removed the redundant `@request_mutex` from HTTP stream request tracking and simplified the surrounding locking.
+* **Handlers::Core Cleanup**: Renamed misleading identifiers and removed dead legacy branches in `Handlers::Core`.
+* **General Complexity Reduction**: Reduced accidental complexity across six refactoring targets in the core request path.
+
+### Fixed
+
+* **TokenStore Read-After-Write Consistency**: Closed a read-after-write consistency hole in `TokenStore` so concurrent tokenization and resolution no longer race.
 
 ## [0.4.0] – 2026-04-10
 

data/README.md

@@ -14,7 +14,9 @@ VectorMCP is a Ruby implementation of the Model Context Protocol (MCP) server-si
 - Class-based tools via `VectorMCP::Tool`, plus the original block-based `register_tool` API
 - Rack and Rails mounting through `server.rack_app`
 - Opt-in authentication and authorization, structured logging, and middleware hooks
+- Request-scoped identity: every request is dispatched through its own invocation, so concurrent requests on one session can never observe each other's headers or auth
 - Image-aware tools/resources/prompts, roots, and server-initiated sampling
+- Token-based field anonymization middleware to keep sensitive values out of LLM context
 
 ## Requirements
 
@@ -161,6 +163,24 @@ end
 
 `VectorMCP::Tool` also supports `type: :date` and `type: :datetime`, which are validated as strings in JSON Schema and coerced to `Date` and `Time` before `#call` runs.
 
+Handlers that take a second argument receive the per-request invocation, which exposes session identity, the request's headers/params, and the authenticated user in one place:
+
+```ruby
+server.register_tool(
+  name: "whoami",
+  description: "Reports the caller's identity",
+  input_schema: { type: "object", properties: {} }
+) do |_args, invocation|
+  {
+    session: invocation.id,
+    user: invocation.user,
+    api_key_header: invocation.request_header("X-API-Key")
+  }
+end
+```
+
+Resource handlers get the same invocation as their second argument (it also answers the familiar `user` / `authenticated?` / `can?` queries, so handlers written against the older security-context argument keep working unchanged).
+
 ## Security and Middleware
 
 VectorMCP keeps security opt-in, but the primitives are built in:
@@ -188,10 +208,27 @@ server.enable_authentication!(strategy: :custom) do |request|
 end
 ```
 
+For MCP clients that speak OAuth 2.1 (e.g. Claude Desktop), pass a `resource_metadata_url:` to turn on RFC 9728 discovery. Unauthenticated requests to `/mcp` return `401` with a `WWW-Authenticate` header pointing at the configured metadata document, and the client drives the rest of the OAuth dance automatically. See [docs/oauth_resource_server.md](./docs/oauth_resource_server.md) for the feature reference and [docs/rails_oauth_integration.md](./docs/rails_oauth_integration.md) for a full Rails + Doorkeeper recipe.
+
 Middleware can hook into tool, resource, prompt, sampling, auth, and transport events, including `before_auth`, `after_auth`, `on_auth_error`, `before_request`, `after_response`, and `on_transport_error`.
 
 See [security/README.md](./security/README.md) for the full security guide.
 
+### Field Anonymization
+
+Keep sensitive string values out of the LLM context by substituting them with stable opaque tokens. Values are tokenized on outbound tool results and restored on inbound tool arguments, so the LLM sees only tokens while your handlers receive the original data.
+
+```ruby
+anonymizer = VectorMCP::Middleware::Anonymizer.new(
+  store: VectorMCP::TokenStore.new,
+  field_rules: [
+    { pattern: /email/i, prefix: "EMAIL" },
+    { pattern: /\bssn\b/i, prefix: "SSN" }
+  ]
+)
+anonymizer.install_on(server)
+```
+
 ## Transport Notes
 
 - VectorMCP ships with streamable HTTP as its built-in transport
@@ -223,6 +260,8 @@ curl -X POST http://localhost:8080/mcp \
 - [CHANGELOG.md](./CHANGELOG.md)
 - [examples/](./examples/)
 - [docs/rails-setup-guide.md](./docs/rails-setup-guide.md)
+- [docs/rails_oauth_integration.md](./docs/rails_oauth_integration.md)
+- [docs/oauth_resource_server.md](./docs/oauth_resource_server.md)
 - [docs/streamable-http-spec-compliance.md](./docs/streamable-http-spec-compliance.md)
 - [security/README.md](./security/README.md)
 - [MCP Specification](https://modelcontextprotocol.io/)

data/lib/vector_mcp/definitions.rb

@@ -29,6 +29,36 @@ module VectorMCP
         }.compact # Remove nil values
       end
 
+      # Class method to create a tool whose input_schema already declares a
+      # base64-encoded image property. Mirrors Resource.from_image_file and
+      # Prompt.with_image_support — keeps schema-building logic with the
+      # definition, not with the registry.
+      #
+      # @param name [String] Unique name for the tool.
+      # @param description [String] Human-readable description.
+      # @param image_parameter [String] Name of the image parameter.
+      # @param additional_parameters [Hash] Additional JSON Schema properties.
+      # @param required_parameters [Array<String>] Required parameter names.
+      # @param handler [Proc] Tool handler block.
+      # @return [Tool]
+      def self.with_image_support(name:, description:, image_parameter: "image",
+                                  additional_parameters: {}, required_parameters: [], &handler)
+        image_property = {
+          type: "string",
+          description: "Base64 encoded image data or file path to image",
+          contentEncoding: "base64",
+          contentMediaType: "image/*"
+        }
+
+        input_schema = {
+          type: "object",
+          properties: { image_parameter => image_property }.merge(additional_parameters),
+          required: required_parameters
+        }
+
+        new(name, description, input_schema, handler)
+      end
+
       # Checks if this tool supports image inputs based on its input schema.
       # @return [Boolean] True if the tool's input schema includes image properties.
       def supports_image_input?

data/lib/vector_mcp/handlers/core.rb

@@ -55,7 +55,7 @@ module VectorMCP
         context = create_tool_context(tool_name, params, session, server)
 
         begin
-          session_context = authenticate_session!(session, server, operation_type: :tool_call, operation_name: tool_name)
+          session_context = authenticate_request!(session, server, operation_type: :tool_call, operation_name: tool_name)
 
           context = server.middleware_manager.execute_hooks(:before_tool_call, context)
           return handle_middleware_error(context) if context.error?
@@ -64,7 +64,7 @@ module VectorMCP
           arguments = context.params["arguments"] || {}
           tool = find_tool!(tool_name, server)
           authorize_action!(session_context, :call, tool, server)
-          validate_input_arguments!(tool_name, tool, arguments)
+          validate_tool_arguments!(tool_name, tool, arguments)
 
           result = execute_tool_handler(tool, arguments, session)
           context.result = build_tool_result(result)
@@ -105,7 +105,7 @@ module VectorMCP
         context = create_resource_context(uri_s, params, session, server)
 
         begin
-          session_context = authenticate_session!(session, server, operation_type: :resource_read, operation_name: uri_s)
+          session_context = authenticate_request!(session, server, operation_type: :resource_read, operation_name: uri_s)
 
           context = server.middleware_manager.execute_hooks(:before_resource_read, context)
           return handle_middleware_error(context) if context.error?
@@ -114,7 +114,7 @@ module VectorMCP
           resource = find_resource!(uri_s, server)
           authorize_action!(session_context, :read, resource, server)
 
-          content_raw = execute_resource_handler(resource, context.params, session_context)
+          content_raw = execute_resource_handler(resource, context.params, session)
           contents = process_resource_content(content_raw, resource, uri_s)
 
           context.result = { contents: contents }
@@ -206,7 +206,7 @@ module VectorMCP
           prompt = fetch_prompt(prompt_name, server)
 
           arguments = context_params["arguments"] || {}
-          validate_arguments!(prompt_name, prompt, arguments)
+          validate_prompt_arguments!(prompt_name, prompt, arguments)
 
           # Call the registered handler after arguments were validated
           result_data = prompt.handler.call(arguments)
@@ -280,7 +280,7 @@ module VectorMCP
       # @param arguments [Hash] The arguments supplied by the client.
       # @return [void]
       # @raise [VectorMCP::InvalidParamsError] if arguments are invalid (e.g., missing, unknown, wrong type).
-      def self.validate_arguments!(prompt_name, prompt, arguments)
+      def self.validate_prompt_arguments!(prompt_name, prompt, arguments)
         ensure_hash!(prompt_name, arguments, "arguments")
 
         arg_defs = prompt.respond_to?(:arguments) ? (prompt.arguments || []) : []
@@ -291,7 +291,7 @@ module VectorMCP
         raise VectorMCP::InvalidParamsError.new("Invalid arguments",
                                                 details: build_invalid_arg_details(prompt_name, missing, unknown))
       end
-      private_class_method :validate_arguments!
+      private_class_method :validate_prompt_arguments!
 
       # Ensures a given value is a Hash.
       # @api private
@@ -369,7 +369,7 @@ module VectorMCP
       # @param arguments [Hash] The arguments supplied by the client.
       # @return [void]
       # @raise [VectorMCP::InvalidParamsError] if arguments fail validation.
-      def self.validate_input_arguments!(tool_name, tool, arguments)
+      def self.validate_tool_arguments!(tool_name, tool, arguments)
         return unless tool.input_schema.is_a?(Hash)
         return if tool.input_schema.empty?
 
@@ -397,72 +397,23 @@ module VectorMCP
           }
         )
       end
-      private_class_method :validate_input_arguments!
+      private_class_method :validate_tool_arguments!
       private_class_method :raise_tool_validation_error
 
-      # Security helper methods
-
-      # Check security for tool access
-      # @api private
-      # @param session [VectorMCP::Session] The current session
-      # @param tool [VectorMCP::Definitions::Tool] The tool being accessed
-      # @param server [VectorMCP::Server] The server instance
-      # @return [Hash] Security check result
-      def self.check_tool_security(session, tool, server)
-        # Extract request context from session for security middleware
-        request = extract_request_from_session(session)
-        server.security_middleware.process_request(request, action: :call, resource: tool)
-      end
-      private_class_method :check_tool_security
-
-      # Check security for resource access
-      # @api private
-      # @param session [VectorMCP::Session] The current session
-      # @param resource [VectorMCP::Definitions::Resource] The resource being accessed
-      # @param server [VectorMCP::Server] The server instance
-      # @return [Hash] Security check result
-      def self.check_resource_security(session, resource, server)
-        request = extract_request_from_session(session)
-        server.security_middleware.process_request(request, action: :read, resource: resource)
-      end
-      private_class_method :check_resource_security
-
-      # Extract request context from session for security processing
+      # Extract the request context from the session for security processing.
       # @api private
       # @param session [VectorMCP::Session] The current session
-      # @return [Hash] Request context for security middleware
-      def self.extract_request_from_session(session)
+      # @return [VectorMCP::RequestContext] Request context for security middleware
+      def self.extract_auth_credentials(session)
         # All sessions should have a request_context - this is enforced by Session initialization
         unless session.respond_to?(:request_context) && session.request_context
           raise VectorMCP::InternalError,
                 "Session missing request_context - transport layer integration error. Session ID: #{session.id}"
         end
 
-        {
-          headers: session.request_context.headers,
-          params: session.request_context.params,
-          session_id: session.id
-        }
-      end
-      private_class_method :extract_request_from_session
-
-      # Handle security failure by raising appropriate error
-      # @api private
-      # @param security_result [Hash] The security check result
-      # @return [void]
-      # @raise [VectorMCP::UnauthorizedError, VectorMCP::ForbiddenError]
-      def self.handle_security_failure(security_result)
-        case security_result[:error_code]
-        when "AUTHENTICATION_REQUIRED"
-          raise VectorMCP::UnauthorizedError, security_result[:error]
-        when "AUTHORIZATION_FAILED"
-          raise VectorMCP::ForbiddenError, security_result[:error]
-        else
-          # Fallback to generic unauthorized error
-          raise VectorMCP::UnauthorizedError, security_result[:error] || "Security check failed"
-        end
+        session.request_context
       end
-      private_class_method :handle_security_failure
+      private_class_method :extract_auth_credentials
 
       # Handle middleware error by returning appropriate response or raising error
       # @api private
@@ -499,24 +450,19 @@ module VectorMCP
         tool
       end
 
-      # Resolve the session authentication state before operation middleware runs.
-      def self.authenticate_session!(session, server, operation_type:, operation_name:)
-        request = extract_request_from_session(session)
-        context = create_auth_context(operation_type, operation_name, request, session, server)
+      # Authenticate the current request and return the caller's identity.
+      def self.authenticate_request!(session, server, operation_type:, operation_name:)
+        request = extract_auth_credentials(session)
+        # before_auth middleware hooks see (and may modify) the request as a hash;
+        # AuthManager coerces it back into a RequestContext at its boundary.
+        context = create_auth_context(operation_type, operation_name, request.to_h, session, server)
         context = server.middleware_manager.execute_hooks(:before_auth, context)
         raise context.error if context.error?
 
-        request = context.params
-        session_context = if server.security_middleware.respond_to?(:authenticate_request)
-                            server.security_middleware.authenticate_request(request)
-                          else
-                            legacy_result = server.security_middleware.process_request(request)
-                            legacy_result[:session_context]
-                          end
-        session.security_context = session_context if session.respond_to?(:security_context=)
+        session_context = server.security_middleware.authenticate_request(context.params)
+        session.security_context = session_context
 
-        auth_required = server.respond_to?(:auth_manager) ? server.auth_manager.required? : false
-        raise VectorMCP::UnauthorizedError, "Authentication required" if auth_required && !session_context.authenticated?
+        raise VectorMCP::UnauthorizedError, "Authentication required" if server.auth_manager.required? && !session_context.authenticated?
 
         context.result = session_context
         server.middleware_manager.execute_hooks(:after_auth, context)
@@ -572,25 +518,22 @@ module VectorMCP
         server.resources[uri_s]
       end
 
-      # Validate resource security
+      # Check authorization and raise ForbiddenError if denied
       def self.authorize_action!(session_context, action, resource, server)
-        authorized = if server.security_middleware.respond_to?(:authorize_action)
-                       server.security_middleware.authorize_action(session_context, action, resource)
-                     else
-                       legacy_result = server.security_middleware.process_request({}, action: action, resource: resource)
-                       legacy_result[:success]
-                     end
-        return if authorized
+        return if server.security_middleware.authorize_action(session_context, action, resource)
 
         raise VectorMCP::ForbiddenError, "Access denied"
       end
 
-      # Execute resource handler with proper arity handling
-      def self.execute_resource_handler(resource, params, session_context)
+      # Execute resource handler with proper arity handling.
+      # The second argument is the per-request invocation, which also exposes
+      # the SessionContext auth API for handlers written against the legacy
+      # (params, session_context) signature.
+      def self.execute_resource_handler(resource, params, invocation)
         if [1, -1].include?(resource.handler.arity)
           resource.handler.call(params)
         else
-          resource.handler.call(params, session_context)
+          resource.handler.call(params, invocation)
         end
       end
 
@@ -633,7 +576,7 @@ module VectorMCP
         raise error
       end
 
-      private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :authenticate_session!,
+      private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :authenticate_request!,
                            :execute_tool_handler, :build_tool_result, :handle_tool_error, :create_resource_context,
                            :find_resource!, :authorize_action!, :execute_resource_handler,
                            :process_resource_content, :handle_resource_error, :create_auth_context,

data/lib/vector_mcp/invocation.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "request_context"
+require_relative "security/session_context"
+
+module VectorMCP
+  # A per-request view of a {Session}.
+  #
+  # Carries the request-scoped state — the incoming request's
+  # {RequestContext} and the {Security::SessionContext} resolved for it —
+  # while delegating session-lived state (identity, initialization,
+  # user data, sampling) to the underlying session. Transports build one
+  # Invocation per incoming request and pass it through message dispatch,
+  # so concurrent requests on the same session each observe their own
+  # request data and authentication result.
+  #
+  # The Invocation intentionally quacks like a {Session}: tool handlers and
+  # request/notification hooks receive it as their `session` argument and
+  # can keep using `session.id`, `session.data`, `session.sample`,
+  # `session.request_header`, and `session.security_context` unchanged.
+  class Invocation
+    extend Forwardable
+
+    # @return [VectorMCP::Session] the underlying session this request belongs to
+    attr_reader :session
+
+    # @return [VectorMCP::RequestContext] this request's context (headers, params, ...)
+    attr_reader :request_context
+
+    # @return [VectorMCP::Security::SessionContext] the security context resolved for this request
+    attr_accessor :security_context
+
+    def_delegators :@session,
+                   :id, :server, :transport, :data,
+                   :initialized?, :initialize!, :sample,
+                   :server_info, :server_capabilities, :protocol_version,
+                   :client_info, :client_capabilities
+
+    # The resolved auth API is exposed directly so handlers written against
+    # Security::SessionContext (the legacy second argument of resource
+    # handlers) keep working when they receive the invocation instead.
+    def_delegators :@security_context,
+                   :user, :authenticated, :authenticated?, :auth_strategy, :authenticated_at,
+                   :permissions, :can?, :can_access?, :add_permission, :add_permissions,
+                   :remove_permission, :clear_permissions, :user_identifier, :auth_method,
+                   :auth_recent?
+
+    # @param session [VectorMCP::Session] the session the request arrived on
+    # @param request_context [RequestContext, Hash, nil] this request's context;
+    #   defaults to the session's stored context when not provided
+    def initialize(session, request_context: nil)
+      @session = session
+      @request_context = request_context ? RequestContext.coerce(request_context) : session.request_context
+      @security_context = Security::SessionContext.anonymous
+    end
+
+    # Replace this request's context (e.g. from middleware).
+    # @param context [RequestContext, Hash] the new request context
+    def request_context=(context)
+      @request_context = RequestContext.coerce(context)
+    end
+
+    # Merge attributes into this request's context.
+    # @param attributes [Hash] attributes to merge
+    # @return [RequestContext] the updated request context
+    def update_request_context(**attributes)
+      @request_context = @request_context.merge(attributes)
+    end
+
+    # @return [Boolean] whether this request carried any headers
+    def request_headers?
+      @request_context.headers?
+    end
+
+    # @return [Boolean] whether this request carried any query parameters
+    def request_params?
+      @request_context.params?
+    end
+
+    # @param name [String] the header name
+    # @return [String, nil] the header value for this request
+    def request_header(name)
+      @request_context.header(name)
+    end
+
+    # @param name [String] the parameter name
+    # @return [String, nil] the parameter value for this request
+    def request_param(name)
+      @request_context.param(name)
+    end
+
+    # Invocations compare by their underlying session, so collections that
+    # deduplicate sessions (e.g. prompt subscribers) treat every request
+    # view of one session as the same subscriber.
+    def ==(other)
+      other_session = other.is_a?(Invocation) ? other.session : other
+      @session == other_session
+    end
+    alias eql? ==
+
+    def hash
+      @session.hash
+    end
+  end
+end