posthog-ruby 3.23.7 → 3.24.0

data/lib/posthog/mcp/event_builder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Translates a processed internal event (string keys) into one or two
+    # PostHog payloads: the main `$mcp_*` event plus an optional `$exception`
+    # sibling.
+    #
+    # @api private
+    module EventBuilder
+      module_function
+
+      # @return [Array<Hash>] payloads `{'event', 'distinct_id', 'properties', 'timestamp'}`
+      def build(event, enable_exception_autocapture: true)
+        batch = [build_capture_event(event)]
+        if event['is_error'] && truthy?(event['error']) && enable_exception_autocapture != false
+          batch << build_exception_event(event)
+        end
+        batch
+      end
+
+      def distinct_id(event)
+        present(event['identify_actor_given_id']) || present(event['session_id']) || 'anonymous'
+      end
+
+      def timestamp(event)
+        event['timestamp'] || Time.now.utc
+      end
+
+      def build_capture_event(event)
+        properties = { Property::SOURCE => SOURCE }
+        add_session_id(event, properties)
+        add_conversation_id(event, properties)
+        add_person_processing(event, properties)
+        add_groups(event, properties)
+        add_common_properties(event, properties)
+        add_custom_properties(event, properties)
+
+        name = present(event['event_name']) || EventType::EVENT_NAME_BY_TYPE.fetch(event['event_type'], Event::CUSTOM)
+        { 'event' => name, 'distinct_id' => distinct_id(event), 'properties' => properties,
+          'timestamp' => timestamp(event) }
+      end
+
+      def add_session_id(event, properties)
+        session_id = event['session_id']
+        properties[Property::SESSION_ID] = session_id if session_id.is_a?(String) && !session_id.empty?
+      end
+
+      def add_conversation_id(event, properties)
+        conversation_id = event['conversation_id']
+        properties[Property::CONVERSATION_ID] = conversation_id unless conversation_id.nil? || conversation_id == ''
+      end
+
+      def add_groups(event, properties)
+        groups = event['groups']
+        properties['$groups'] = groups if truthy?(groups)
+      end
+
+      # Without a resolved identity the distinct id is just the session id, so
+      # processing a person profile would mint one anonymous person per session.
+      def add_person_processing(event, properties)
+        properties['$process_person_profile'] = false unless present(event['identify_actor_given_id'])
+      end
+
+      def tool_call?(event)
+        event['event_type'] == EventType::MCP_TOOLS_CALL
+      end
+
+      def add_common_properties(event, properties)
+        if present(event['resource_name'])
+          properties[Property::RESOURCE_NAME] = event['resource_name']
+          properties[Property::TOOL_NAME] = event['resource_name'] if tool_call?(event)
+        end
+        if present(event['tool_description']) && tool_call?(event)
+          properties[Property::TOOL_DESCRIPTION] =
+            event['tool_description']
+        end
+        if present(event['tool_category']) && tool_call?(event)
+          properties[Property::TOOL_CATEGORY] = event['tool_category']
+        end
+        listed = event['listed_tool_names']
+        if listed.is_a?(Array) && !listed.empty? && event['event_type'] == EventType::MCP_TOOLS_LIST
+          properties[Property::LISTED_TOOL_NAMES] = listed
+        end
+        properties[Property::DURATION_MS] = event['duration'] unless event['duration'].nil?
+        properties[Property::SERVER_NAME] = event['server_name'] if present(event['server_name'])
+        properties[Property::SERVER_VERSION] = event['server_version'] if present(event['server_version'])
+        properties[Property::CLIENT_NAME] = event['client_name'] if present(event['client_name'])
+        properties[Property::CLIENT_VERSION] = event['client_version'] if present(event['client_version'])
+        properties[Property::CLIENT_USER_AGENT] = event['client_user_agent'] if present(event['client_user_agent'])
+        properties[Property::VENDOR_CLIENT] = event['vendor_client'] if present(event['vendor_client'])
+        properties[Property::PROTOCOL_VERSION] = event['protocol_version'] if present(event['protocol_version'])
+        properties[Property::INTENT] = event['user_intent'] if present(event['user_intent'])
+        properties[Property::INTENT_SOURCE] = event['user_intent_source'] if present(event['user_intent_source'])
+        properties[Property::LLM_MODEL] = event['llm_model'] if present(event['llm_model'])
+        properties[Property::LLM_MODEL_SOURCE] = event['llm_model_source'] if present(event['llm_model_source'])
+        properties[Property::IS_ERROR] = event['is_error'] unless event['is_error'].nil?
+        add_error_details(event, properties) if event['is_error']
+        properties[Property::PARAMETERS] = event['parameters'] unless event['parameters'].nil?
+        properties[Property::RESPONSE] = event['response'] unless event['response'].nil?
+        actor_data = event['identify_actor_data']
+        properties['$set'] = actor_data.dup if actor_data.is_a?(Hash) && !actor_data.empty?
+      end
+
+      # Surface the failure reason on the primary event itself, so dashboards
+      # need not join to the `$exception` sibling (which can be switched off).
+      def add_error_details(event, properties)
+        first = Exceptions.primary_exception(event['error'])
+        error_type = present(event['error_type']) || present(first['type'])
+        properties[Property::ERROR_TYPE] = error_type if error_type
+        message = first['value']
+        properties[Property::ERROR_MESSAGE] = message if present(message)
+      end
+
+      def add_custom_properties(event, properties)
+        custom = event['properties']
+        return unless custom.is_a?(Hash)
+
+        custom.each { |key, value| properties[key.to_s] = value }
+      end
+
+      def build_exception_event(event)
+        properties = {}
+        add_session_id(event, properties)
+        add_conversation_id(event, properties)
+        add_person_processing(event, properties)
+        add_groups(event, properties)
+
+        error = event['error']
+        properties.merge!(error) if error.is_a?(Hash)
+
+        if present(event['resource_name'])
+          properties[Property::RESOURCE_NAME] = event['resource_name']
+          properties[Property::TOOL_NAME] = event['resource_name'] if tool_call?(event)
+        end
+        if present(event['tool_description']) && tool_call?(event)
+          properties[Property::TOOL_DESCRIPTION] =
+            event['tool_description']
+        end
+        if present(event['tool_category']) && tool_call?(event)
+          properties[Property::TOOL_CATEGORY] = event['tool_category']
+        end
+        properties[Property::SERVER_NAME] = event['server_name'] if present(event['server_name'])
+        properties[Property::SERVER_VERSION] = event['server_version'] if present(event['server_version'])
+        properties[Property::CLIENT_NAME] = event['client_name'] if present(event['client_name'])
+        properties[Property::CLIENT_VERSION] = event['client_version'] if present(event['client_version'])
+        properties[Property::PROTOCOL_VERSION] = event['protocol_version'] if present(event['protocol_version'])
+
+        add_custom_properties(event, properties)
+
+        { 'event' => Event::EXCEPTION, 'distinct_id' => distinct_id(event), 'properties' => properties,
+          'timestamp' => timestamp(event) }
+      end
+
+      def present(value)
+        return nil if value.nil?
+        return nil if value.respond_to?(:empty?) && value.empty?
+        return nil if value == false
+
+        value
+      end
+
+      def truthy?(value)
+        !present(value).nil?
+      end
+    end
+  end
+end

data/lib/posthog/mcp/exceptions.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'posthog/exception_capture'
+
+module PostHog
+  module MCP
+    # Builds PostHog error-tracking properties (`$exception_list` /
+    # `$exception_level`) from anything a tool can fail with, reusing
+    # {PostHog::ExceptionCapture} so MCP failures group like every other
+    # exception the Ruby SDK reports.
+    #
+    # @api private
+    module Exceptions
+      GENERIC_MECHANISM = { 'type' => 'generic', 'handled' => true }.freeze
+
+      # Messages the Ruby `mcp` gem wraps around whatever a tool raised.
+      DISPATCH_WRAPPER_TYPE = 'MCP::Server::RequestHandlerError'
+      DISPATCH_WRAPPER_PREFIXES = ['Internal error calling tool', 'Internal error handling'].freeze
+
+      module_function
+
+      # @param error [Exception, String, Hash, Object] exception, message, or an
+      #   `isError` tool result (`{content: [...], isError: true}`)
+      # @return [Hash] `{'$exception_list' => [...], '$exception_level' => 'error'}`
+      def capture_exception(error)
+        return from_message(call_tool_result_message(error)) if call_tool_result?(error)
+        return from_exception(error) if error.is_a?(Exception)
+        return from_message(error) if error.is_a?(String)
+
+        from_message(safe_to_s(error))
+      end
+
+      def from_exception(error)
+        list = PostHog::ExceptionCapture.build_exception_list(error) || []
+        original = error.respond_to?(:original_error) ? error.original_error : nil
+        if original.is_a?(Exception) && !chain_includes?(error, original)
+          list.concat(PostHog::ExceptionCapture.build_exception_list(original) || [])
+        end
+        list = [message_entry(error.class.to_s, error.message.to_s)] if list.empty?
+        { '$exception_list' => list, '$exception_level' => 'error' }
+      end
+
+      def from_message(message)
+        { '$exception_list' => [message_entry('Error', message)], '$exception_level' => 'error' }
+      end
+
+      def message_entry(type, message)
+        { 'mechanism' => GENERIC_MECHANISM.dup, 'type' => type, 'value' => message }
+      end
+
+      # Whether an `$exception_list` entry is the gem's dispatch wrapper, whose
+      # message says nothing the tool name does not already say.
+      def dispatch_wrapper?(entry)
+        return false unless entry.is_a?(Hash)
+
+        value = entry['value'].to_s
+        entry['type'] == DISPATCH_WRAPPER_TYPE && DISPATCH_WRAPPER_PREFIXES.any? { |p| value.start_with?(p) }
+      end
+
+      # The `$exception_list` entry carrying the actual failure reason, stepping
+      # past consecutive dispatch wrappers.
+      def primary_exception(error)
+        return {} unless error.is_a?(Hash)
+
+        list = error['$exception_list']
+        return {} unless list.is_a?(Array) && !list.empty?
+
+        index = 0
+        index += 1 while index + 1 < list.length && list[index + 1].is_a?(Hash) && dispatch_wrapper?(list[index])
+        list[index].is_a?(Hash) ? list[index] : {}
+      end
+
+      def call_tool_result?(value)
+        return false unless value.is_a?(Hash)
+
+        content = value['content'] || value[:content]
+        (value.key?('isError') || value.key?(:isError)) && content.is_a?(Array)
+      end
+
+      def call_tool_result_message(result)
+        content = result['content'] || result[:content] || []
+        texts = content.filter_map do |part|
+          next unless part.is_a?(Hash)
+
+          type = part['type'] || part[:type]
+          text = part['text'] || part[:text]
+          text if type == 'text' && text.is_a?(String)
+        end
+        joined = texts.join(' ').strip
+        joined.empty? ? 'Unknown error' : joined
+      end
+
+      def chain_includes?(error, target)
+        current = error.cause
+        seen = {}.compare_by_identity
+        while current && !seen.key?(current)
+          return true if current.equal?(target)
+
+          seen[current] = true
+          current = current.cause
+        end
+        false
+      end
+
+      def safe_to_s(value)
+        value.to_s
+      rescue StandardError
+        'Unknown error'
+      end
+    end
+  end
+end

data/lib/posthog/mcp/identity.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PostHog
+  module MCP
+    # Bounded LRU of session identities, isolated per server.
+    #
+    # @api private
+    class IdentityCache
+      def initialize(max_size = 1000)
+        @cache = {}
+        @max_size = max_size
+        @mutex = Mutex.new
+      end
+
+      def get(session_id)
+        @mutex.synchronize do
+          identity = @cache.delete(session_id)
+          next nil if identity.nil?
+
+          @cache[session_id] = identity
+        end
+      end
+
+      def set(session_id, identity)
+        @mutex.synchronize do
+          @cache.delete(session_id)
+          @cache.shift if @cache.length >= @max_size
+          @cache[session_id] = identity
+        end
+      end
+
+      # Atomically read the cached identity, merge the new one, store it, and
+      # report whether it changed. Keeps concurrent requests for one session
+      # from interleaving their read-merge-write.
+      #
+      # @return [Array(UserIdentity, Boolean)] `[merged, changed]`
+      def merge!(session_id, identity)
+        @mutex.synchronize do
+          previous = @cache.delete(session_id)
+          merged = Identity.merge_identities(previous, identity)
+          changed = !(previous && Identity.identities_equal?(previous, merged))
+          @cache.shift if @cache.length >= @max_size
+          @cache[session_id] = merged
+          [merged, changed]
+        end
+      end
+
+      def has?(session_id)
+        @mutex.synchronize { @cache.key?(session_id) }
+      end
+
+      def size
+        @mutex.synchronize { @cache.length }
+      end
+    end
+
+    # Identity resolution: runs the `identify` option, dedupes against the
+    # per-server cache, and decides when a standalone `$identify` event fires.
+    #
+    # @api private
+    module Identity
+      module_function
+
+      def identities_equal?(first, second)
+        return false if first.distinct_id != second.distinct_id
+        return false if sorted_json(first.groups || {}) != sorted_json(second.groups || {})
+
+        a_props = first.properties || {}
+        b_props = second.properties || {}
+        return false if a_props.keys.map(&:to_s).sort != b_props.keys.map(&:to_s).sort
+
+        a_props.all? do |key, value|
+          other = if b_props.key?(key)
+                    b_props[key]
+                  else
+                    b_props[key.is_a?(Symbol) ? key.to_s : key.to_s.to_sym]
+                  end
+          sorted_json(value) == sorted_json(other)
+        end
+      end
+
+      def merge_identities(previous, nxt)
+        return nxt if previous.nil?
+
+        UserIdentity.new(
+          distinct_id: nxt.distinct_id,
+          properties: (previous.properties || {}).merge(nxt.properties || {}),
+          groups: nxt.groups.nil? ? previous.groups : nxt.groups
+        )
+      end
+
+      # Resolve the optional `identify` callback for one request: the identity the
+      # request's events belong to, plus an `$identify` event to emit only when
+      # that identity has materially changed.
+      #
+      # The actor is handed back rather than left for the caller to read out of
+      # {IdentityCache} later. The cache is keyed by session, and a request's
+      # events are built after its handler returns, so a concurrent request on
+      # the same session would otherwise decide who this one is attributed to.
+      # When resolution yields nothing the cache is read once, here, so whatever
+      # a request is attributed to it is attributed to consistently.
+      #
+      # @return [Array(Hash, UserIdentity), Array(nil, UserIdentity), Array(nil, nil)] `[event, actor]`
+      def identify_for_request(data, session_id, request, extra)
+        identify = data.options.identify
+        return [nil, nil] unless identify
+
+        result = if identify.is_a?(UserIdentity) || identify.is_a?(Hash)
+                   identify
+                 else
+                   Callbacks.call(identify, request,
+                                  extra)
+                 end
+        identity = UserIdentity.coerce(result)
+        unless identity
+          Log.debug(data.options, "Warning: Supplied identify function returned null for session #{session_id}")
+          return [nil, data.identified_sessions.get(session_id)]
+        end
+
+        merged, changed = data.identified_sessions.merge!(session_id, identity)
+        return [nil, merged] unless changed
+
+        Log.debug(data.options, "Identified session #{session_id}")
+        [{
+          'session_id' => session_id,
+          'resource_name' => request_resource_name(request),
+          'event_type' => EventType::IDENTIFY,
+          'parameters' => { 'request' => request, 'extra' => captured_extra(extra) },
+          'timestamp' => Time.now.utc
+        }, merged]
+      rescue StandardError => e
+        Log.debug(data.options, "Error: identify function threw while identifying session #{session_id} - #{e.message}")
+        [nil, data.identified_sessions.get(session_id)]
+      end
+
+      # @return [Hash, nil] the `$identify` event alone; see {identify_for_request}.
+      def handle_identify(data, session_id, request, extra)
+        identify_for_request(data, session_id, request, extra).first
+      end
+
+      def request_resource_name(request)
+        return 'Unknown' unless request.is_a?(Hash)
+
+        params = request[:params] || request['params']
+        return 'Unknown' unless params.is_a?(Hash)
+
+        name = params[:name] || params['name']
+        name.is_a?(String) ? name : 'Unknown'
+      end
+
+      # Only JSON scalars from `extra` are captured; never opaque transport objects.
+      def captured_extra(extra)
+        return nil unless extra.is_a?(Hash)
+
+        extra.select do |_, value|
+          value.nil? || value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false
+        end
+      end
+
+      def sorted_json(value)
+        JSON.generate(sort_deep(value))
+      rescue StandardError
+        value.to_s
+      end
+
+      def sort_deep(value)
+        case value
+        when Hash then value.map { |k, v| [k.to_s, sort_deep(v)] }.sort_by(&:first).to_h
+        when Array then value.map { |v| sort_deep(v) }
+        when String, Numeric, true, false, nil then value
+        else value.to_s
+        end
+      end
+    end
+
+    # Invokes user callbacks with `(request, extra)`, tolerating 1-arity lambdas.
+    #
+    # @api private
+    module Callbacks
+      module_function
+
+      def call(callable, request, extra)
+        arity = callable.respond_to?(:arity) ? callable.arity : 2
+        case arity
+        when 0 then callable.call
+        when 1 then callable.call(request)
+        else callable.call(request, extra)
+        end
+      end
+    end
+  end
+end

data/lib/posthog/mcp/ids.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module PostHog
+  module MCP
+    # Id generation: `evt_<uuidv7>` / `ses_<uuidv7>` and the deterministic FNV-1a
+    # derivation used for session ids that must agree across servers and restarts.
+    #
+    # @api private
+    module Ids
+      module_function
+
+      # RFC 9562 UUIDv7 (time-ordered), implemented inline so Ruby 3.0/3.1 work too.
+      #
+      # @return [String] lowercase, hyphenated uuid
+      def uuid_v7
+        unix_ts_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) & ((1 << 48) - 1)
+        rand_a = SecureRandom.random_number(1 << 12)
+        rand_b = SecureRandom.random_number(1 << 62)
+
+        value = unix_ts_ms << 80
+        value |= 0x7 << 76
+        value |= rand_a << 64
+        value |= 0b10 << 62
+        value |= rand_b
+
+        hex = format('%032x', value)
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+
+      # @param prefix [String] `'evt'` or `'ses'`
+      def new_prefixed_id(prefix)
+        "#{prefix}_#{uuid_v7}"
+      end
+
+      # Deterministic id derived from an arbitrary string. FNV-1a 64-bit mixed
+      # twice to fill 32 hex chars. Not cryptographic; only stable and low-collision.
+      #
+      # Iterates code points; session/conversation ids are ASCII in practice.
+      def deterministic_prefixed_id(prefix, value)
+        "#{prefix}_#{fnv1a_hex(value)}#{fnv1a_hex("#{value}::salt")}"
+      end
+
+      def fnv1a_hex(value)
+        h1 = 0x84222325
+        h2 = 0xcbf29ce4
+        value.to_s.each_codepoint do |c|
+          h1 = ((h1 ^ c) * 0x000001b3) & 0xffffffff
+          h2 = ((h2 ^ c) * 0x00000193) & 0xffffffff
+        end
+        format('%<h1>08x%<h2>08x', h1: h1, h2: h2)
+      end
+    end
+  end
+end