txlemetry-ruby 4.0.0

data/lib/txlemetry/mcp/client.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module MCP
+    # A {Txlemetry::Client} with first-class MCP analytics for custom dispatchers
+    # (your own HTTP layer, no `MCP::Server` to wrap). The host resolves
+    # identity and context per request and calls the capture methods directly;
+    # events flow through the same sanitize -> truncate -> `$exception` fan-out
+    # pipeline as {Txlemetry::MCP.instrument}. Does not need the `mcp` gem.
+    #
+    # @note Experimental.
+    #
+    # @example
+    #   txlemetry = Txlemetry::MCP::Client.new(api_key: 'phc_...', host: 'https://app.txlemetry.com')
+    #   txlemetry.capture_tool_call('search_docs', duration_ms: 42, distinct_id: 'user_123')
+    class Client < Txlemetry::Client
+      # @param opts [Hash] {Txlemetry::Client} options plus:
+      # @option opts [String] :missing_capability_tool_name name of the virtual tool (default `get_more_tools`)
+      # @option opts [Boolean] :mcp_exception_autocapture emit a sibling `$exception` for failed calls (default true)
+      # @option opts [Boolean, ModelOptions] :capture_model capture the calling model (default true)
+      def initialize(opts = {})
+        opts = opts.transform_keys(&:to_sym)
+        @missing_capability_tool_name = opts.delete(:missing_capability_tool_name) || Tools::GET_MORE_TOOLS_NAME
+        @mcp_exception_autocapture = opts.delete(:mcp_exception_autocapture) != false
+        capture_model = opts.key?(:capture_model) ? opts.delete(:capture_model) : true
+        @capture_model_option = Options.new(capture_model: capture_model).capture_model
+        super
+        @mcp_sink = Sink.new(self)
+        @mcp_options = Options.new(
+          enable_exception_autocapture: @mcp_exception_autocapture,
+          missing_capability_tool_name: @missing_capability_tool_name
+        )
+      end
+
+      # Capture a tool invocation. Emits `$mcp_tool_call` (+ `$exception` on error).
+      #
+      # @return [void]
+      def capture_tool_call(tool_name, intent: nil, intent_source: nil, parameters: nil, response: nil,
+                            duration_ms: nil, is_error: false, error: nil, error_type: nil, category: nil,
+                            tool_description: nil, protocol_version: nil, distinct_id: nil, session_id: nil,
+                            client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                            properties: nil, timestamp: nil, llm_model: nil, llm_model_source: nil)
+        event = base_event(EventType::MCP_TOOLS_CALL, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['resource_name'] = tool_name
+        event['tool_description'] = tool_description
+        event['tool_category'] = category
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        event['is_error'] = is_error == true
+        event['error_type'] = error_type
+        apply_intent(event, intent, intent_source)
+        apply_model(event, llm_model, llm_model_source)
+        if is_error
+          event['error'] =
+            Exceptions.capture_exception(error.nil? ? "Tool #{tool_name} returned an error" : error)
+        end
+        emit(event)
+      end
+
+      # Capture the connection handshake. Emits `$mcp_initialize`.
+      #
+      # @return [void]
+      def capture_initialize(client_name: nil, client_version: nil, protocol_version: nil, parameters: nil,
+                             response: nil, duration_ms: nil, distinct_id: nil, session_id: nil,
+                             client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                             properties: nil, timestamp: nil)
+        event = base_event(EventType::MCP_INITIALIZE, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['client_name'] = client_name
+        event['client_version'] = client_version
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        emit(event)
+      end
+
+      # Capture a `tools/list` response. Emits `$mcp_tools_list` with `$mcp_listed_tool_names`.
+      #
+      # @return [void]
+      def capture_tools_list(tool_names: nil, parameters: nil, response: nil, duration_ms: nil, is_error: false,
+                             error: nil, error_type: nil, protocol_version: nil, distinct_id: nil, session_id: nil,
+                             client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                             properties: nil, timestamp: nil)
+        event = base_event(EventType::MCP_TOOLS_LIST, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['listed_tool_names'] = tool_names
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        event['is_error'] = is_error == true
+        event['error_type'] = error_type
+        event['error'] = Exceptions.capture_exception(error.nil? ? 'tools/list failed' : error) if is_error
+        emit(event)
+      end
+
+      # Capture a `get_more_tools` call as a missing-capability report. Emits
+      # `$mcp_missing_capability` with the agent's description as `$mcp_intent`.
+      #
+      # @return [void]
+      def capture_missing_capability(context: nil, parameters: nil, protocol_version: nil, distinct_id: nil,
+                                     session_id: nil, client_user_agent: nil, vendor_client: nil,
+                                     set_properties: nil, groups: nil, properties: nil, timestamp: nil,
+                                     llm_model: nil, llm_model_source: nil)
+        event = base_event(EventType::MCP_MISSING_CAPABILITY, distinct_id, session_id, set_properties, groups,
+                           properties, timestamp, client_user_agent, vendor_client)
+        event['resource_name'] = @missing_capability_tool_name
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        apply_intent(event, context, 'context_parameter')
+        apply_model(event, llm_model, llm_model_source)
+        emit(event)
+      end
+
+      # Inject the `context` and `llm_model` arguments into
+      # every tool descriptor (Hash with `inputSchema`) so agents state their intent,
+      # and optionally append the `get_more_tools` virtual tool. Returns a new Array
+      # of new Hashes. A tool whose schema is composed (oneOf/allOf/anyOf) or a
+      # `$ref` is passed through untouched. Pass `capture_model: false` here or
+      # to {#initialize} to disable model capture for this client, including
+      # extraction from later tool calls.
+      #
+      # @param tools [Array<Hash>] `tools/list` entries
+      # @return [Array<Hash>]
+      def prepare_tool_list(tools, context: true, report_missing: false, capture_model: @capture_model_option)
+        options = Options.new(context: context, capture_model: capture_model)
+        @capture_model_option = false unless options.capture_model_enabled?
+        options = Options.new(context: context, capture_model: false) if @capture_model_option == false
+        prepared = tools.map do |tool|
+          next tool unless tool.is_a?(Hash) && (options.context_enabled? || options.capture_model_enabled?)
+
+          name = SchemaMutation.fetch(tool, :name) || 'unknown'
+          next tool if name == @missing_capability_tool_name
+
+          schema = SchemaMutation.fetch(tool, :inputSchema)
+          if options.context_enabled?
+            schema = SchemaMutation.add_context_parameter(schema, tool_name: name,
+                                                                  description: options.context_description)
+          end
+          if options.capture_model_enabled?
+            schema = SchemaMutation.add_model_parameter(schema, tool_name: name,
+                                                                description: options.model_description)
+          end
+          tool.merge(SchemaMutation.key_for(tool, :inputSchema) => schema)
+        end
+        if report_missing && prepared.none? { |t| SchemaMutation.fetch(t, :name) == @missing_capability_tool_name }
+          prepared << Tools.descriptor(@missing_capability_tool_name, options)
+        end
+        prepared
+      end
+
+      # Pull the agent's intent off the `context` argument and its self-reported
+      # model off `llm_model`, strip the arguments this integration injected, and
+      # flag the `get_more_tools` virtual tool. Hand `intent`/`intent_source` and
+      # `llm_model`/`llm_model_source` straight to {#capture_tool_call}.
+      #
+      # Pass the tool's own `inputSchema` (the same Hash you handed to
+      # {#prepare_tool_list}) so a field the tool declares itself is left in
+      # `args` and never read as analytics: only an injected argument is stripped
+      # and reported. A composed (oneOf/allOf/anyOf) or `$ref` schema is never
+      # injected into, so its fields are the tool's own and are left alone too.
+      # Without the schema there is no way to tell the two apart, so the injected
+      # names are always stripped.
+      #
+      # @param name [String] tool name
+      # @param args [Hash, nil] the call's arguments
+      # @param input_schema [Hash, nil] the tool's raw `inputSchema`
+      # @return [PreparedToolCall]
+      def prepare_tool_call(name, args = nil, input_schema: nil)
+        intent = tool_declares?(input_schema, 'context') ? nil : Intent.normalize(argument(args, 'context'))
+        model = if @capture_model_option == false || tool_declares?(input_schema, ModelCapture::PARAM_NAME)
+                  nil
+                else
+                  ModelCapture.normalize(argument(args, ModelCapture::PARAM_NAME))
+                end
+        PreparedToolCall.new(
+          args: strip_injected(args, input_schema),
+          intent: intent,
+          intent_source: intent ? 'context_parameter' : nil,
+          llm_model: model,
+          llm_model_source: model ? 'self_reported' : nil,
+          is_missing_capability: name == @missing_capability_tool_name
+        )
+      end
+
+      private
+
+      def base_event(event_type, distinct_id, session_id, set_properties, groups, properties, timestamp,
+                     client_user_agent, vendor_client)
+        event = {
+          'event_type' => event_type,
+          'session_id' => session_id,
+          'timestamp' => timestamp || Time.now.utc,
+          'properties' => properties,
+          'groups' => groups,
+          'client_user_agent' => client_user_agent,
+          'vendor_client' => vendor_client
+        }
+        event['identify_actor_given_id'] = distinct_id if distinct_id.is_a?(String) && !distinct_id.empty?
+        event['identify_actor_data'] = set_properties if set_properties.is_a?(Hash) && !set_properties.empty?
+        event
+      end
+
+      def apply_model(event, llm_model, source)
+        return if @capture_model_option == false
+
+        model = ModelCapture.normalize(llm_model)
+        return unless model
+
+        event['llm_model'] = model
+        event['llm_model_source'] = source || 'self_reported'
+      end
+
+      def apply_intent(event, intent, source)
+        trimmed = intent.is_a?(String) ? intent.strip : ''
+        return if trimmed.empty?
+
+        event['user_intent'] = trimmed
+        event['user_intent_source'] = source || 'context_parameter'
+      end
+
+      def emit(event)
+        @mcp_sink.capture(event, @mcp_options)
+        nil
+      end
+
+      # True when the argument belongs to the tool rather than to this layer: it
+      # declares the field itself, or its schema is one we never inject into.
+      def tool_declares?(input_schema, param)
+        return false unless input_schema
+
+        !SchemaMutation.injectable?(input_schema) || SchemaMutation.declares_param?(input_schema, param)
+      end
+
+      def argument(args, param)
+        return nil unless args.is_a?(Hash)
+
+        args[param.to_sym] || args[param]
+      end
+
+      def strip_injected(args, input_schema)
+        return args unless args.is_a?(Hash)
+
+        params = ['context']
+        params << ModelCapture::PARAM_NAME unless @capture_model_option == false
+        keys = params.reject { |param| tool_declares?(input_schema, param) }
+                     .flat_map { |param| [param.to_sym, param] }
+                     .select { |key| args.key?(key) }
+        keys.empty? ? args : args.except(*keys)
+      end
+    end
+  end
+end

data/lib/txlemetry/mcp/constants.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module MCP
+    # Value of `$mcp_source` on every primary `$mcp_*` event.
+    SOURCE = 'txlemetry_mcp_analytics'
+
+    # `$lib` stamped on MCP analytics events (per event, never on the client).
+    LIB_NAME = 'txlemetry-ruby-mcp'
+
+    # Generated (in-memory) sessions roll over after this much inactivity.
+    INACTIVITY_TIMEOUT_MINUTES = 30
+
+    # Header carrying the transport session id, and our self-encoded token.
+    MCP_SESSION_HEADER = 'mcp-session-id'
+
+    # Description of the injected `context` argument.
+    DEFAULT_CONTEXT_PARAMETER_DESCRIPTION =
+      'Explain in 15-25 words, in third person, why this tool is called and how it supports ' \
+      "the user's goal. For analytics only. You MUST describe only the abstract purpose of the " \
+      'tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying ' \
+      'information from the user request or tool results, including names, emails, phone numbers, ' \
+      'IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", ' \
+      '"the customer", or "an account". Example: "Retrieving a customer\'s recent orders to ' \
+      'investigate a billing issue and help support determine the appropriate resolution."'
+
+    # Description of the injected `llm_model` argument.
+    DEFAULT_MODEL_PARAMETER_DESCRIPTION =
+      'The exact model identifier you (the assistant) are running as, taken from your system ' \
+      'prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you ' \
+      'do not know your model identifier with certainty, pass "unknown" — never guess.'
+
+    # Description of the injected `conversation_id` argument.
+    DEFAULT_CONVERSATION_ID_DESCRIPTION =
+      "Echo the conversation_id from the server's previous response. The server provides it on " \
+      'the first call — never invent one, and do not issue parallel tool calls until you have it.'
+
+    # Txlemetry-owned event names. All `$`-prefixed per the Txlemetry convention.
+    module Event
+      CUSTOM = '$mcp_custom'
+      EXCEPTION = '$exception'
+      IDENTIFY = '$identify'
+      INITIALIZE = '$mcp_initialize'
+      MISSING_CAPABILITY = '$mcp_missing_capability'
+      PROMPT_GET = '$mcp_prompt_get'
+      PROMPTS_LIST = '$mcp_prompts_list'
+      RESOURCE_READ = '$mcp_resource_read'
+      RESOURCES_LIST = '$mcp_resources_list'
+      TOOL_CALL = '$mcp_tool_call'
+      TOOLS_LIST = '$mcp_tools_list'
+    end
+
+    # Txlemetry property wire keys emitted on MCP events.
+    module Property
+      CLIENT_NAME = '$mcp_client_name'
+      CLIENT_USER_AGENT = '$mcp_client_user_agent'
+      CLIENT_VERSION = '$mcp_client_version'
+      VENDOR_CLIENT = '$mcp_vendor_client'
+      PROTOCOL_VERSION = '$mcp_protocol_version'
+      CONVERSATION_ID = '$mcp_conversation_id'
+      DURATION_MS = '$mcp_duration_ms'
+      ERROR_MESSAGE = '$mcp_error_message'
+      ERROR_TYPE = '$mcp_error_type'
+      IS_ERROR = '$mcp_is_error'
+      INTENT = '$mcp_intent'
+      INTENT_SOURCE = '$mcp_intent_source'
+      LISTED_TOOL_NAMES = '$mcp_listed_tool_names'
+      LLM_MODEL = '$mcp_llm_model'
+      LLM_MODEL_SOURCE = '$mcp_llm_model_source'
+      PARAMETERS = '$mcp_parameters'
+      RESOURCE_NAME = '$mcp_resource_name'
+      RESPONSE = '$mcp_response'
+      SERVER_NAME = '$mcp_server_name'
+      SERVER_VERSION = '$mcp_server_version'
+      SESSION_ID = '$session_id'
+      SOURCE = '$mcp_source'
+      TOOL_CATEGORY = '$mcp_tool_category'
+      TOOL_DESCRIPTION = '$mcp_tool_description'
+      TOOL_NAME = '$mcp_tool_name'
+    end
+
+    # Internal dispatch keys for the event pipeline (never sent on the wire).
+    #
+    # @api private
+    module EventType
+      CUSTOM = 'posthog:custom'
+      IDENTIFY = 'posthog:identify'
+      MCP_INITIALIZE = 'mcp:initialize'
+      MCP_MISSING_CAPABILITY = 'mcp:missing_capability'
+      MCP_PROMPTS_GET = 'mcp:prompts/get'
+      MCP_PROMPTS_LIST = 'mcp:prompts/list'
+      MCP_RESOURCES_LIST = 'mcp:resources/list'
+      MCP_RESOURCES_READ = 'mcp:resources/read'
+      MCP_TOOLS_CALL = 'mcp:tools/call'
+      MCP_TOOLS_LIST = 'mcp:tools/list'
+
+      EVENT_NAME_BY_TYPE = {
+        CUSTOM => Event::CUSTOM,
+        IDENTIFY => Event::IDENTIFY,
+        MCP_INITIALIZE => Event::INITIALIZE,
+        MCP_MISSING_CAPABILITY => Event::MISSING_CAPABILITY,
+        MCP_PROMPTS_GET => Event::PROMPT_GET,
+        MCP_PROMPTS_LIST => Event::PROMPTS_LIST,
+        MCP_RESOURCES_LIST => Event::RESOURCES_LIST,
+        MCP_RESOURCES_READ => Event::RESOURCE_READ,
+        MCP_TOOLS_CALL => Event::TOOL_CALL,
+        MCP_TOOLS_LIST => Event::TOOLS_LIST
+      }.freeze
+    end
+  end
+end

data/lib/txlemetry/mcp/conversation_id.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Txlemetry
+  module MCP
+    # Optional `conversation_id` loop-back. When enabled, the SDK injects a
+    # `conversation_id` parameter into every tool, mints one when the agent does
+    # not supply it, hands it back on the response, and captures it as
+    # `$mcp_conversation_id`, stitching calls across reconnects and pods.
+    #
+    # @api private
+    module ConversationId
+      PARAM_NAME = 'conversation_id'
+      MINTED_CONVERSATION_ID = /\A[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+
+      MCP_INSTRUCTIONS_KEY = '_mcp_instructions'
+      INSTRUCTIONS_FIELD_DESCRIPTION = 'Server-issued metadata for this conversation.'
+      CONVERSATION_ID_FIELD_DESCRIPTION = 'The server-issued conversation identifier.'
+
+      module_function
+
+      def normalize(value)
+        return nil unless value.is_a?(String)
+
+        trimmed = value.strip
+        trimmed.empty? ? nil : trimmed
+      end
+
+      def extract(args)
+        return nil unless args.is_a?(Hash)
+
+        normalize(args[PARAM_NAME] || args[PARAM_NAME.to_sym])
+      end
+
+      # @param supplied [String, nil] the `conversation_id` argument, and only
+      #   when this layer owns it. A tool that declares `conversation_id` in its
+      #   own schema is passed application data, which must not anchor analytics:
+      #   two users sharing such a value would be stitched into one conversation.
+      # @return [Array(String, Boolean), Array(nil, false)] `[conversation_id, minted]`
+      def resolve(enabled, supplied, tool_name, missing_capability_tool_name)
+        return [nil, false] if !enabled || tool_name == missing_capability_tool_name
+
+        value = normalize(supplied)
+        return [value.downcase, false] if value && MINTED_CONVERSATION_ID.match?(value)
+
+        [Ids.uuid_v7, true]
+      end
+
+      def prompt_back?(result)
+        result.is_a?(Hash) && (result[:content] || result['content']).is_a?(Array)
+      end
+
+      # Plain data, not an instruction: an instruction-shaped block is what a
+      # client's prompt-injection filter strips. Compact JSON.
+      def build_prompt_back(conversation_id)
+        { type: 'text', text: JSON.generate({ conversation_id: conversation_id }) }
+      end
+
+      # @return [Hash] a new result with the prompt-back appended (or the input unchanged)
+      def inject_prompt_back(result, conversation_id)
+        return result unless prompt_back?(result)
+
+        key = result.key?(:content) ? :content : 'content'
+        result.merge(key => result[key] + [build_prompt_back(conversation_id)])
+      end
+
+      # Mirror the handle into `structuredContent` for tools whose output schema
+      # declared `_mcp_instructions`. Customer data wins when the key exists.
+      #
+      # @return [Array(Object, Boolean)] `[result, delivered]`
+      def mirror_instructions(result, conversation_id)
+        return [result, false] unless result.is_a?(Hash)
+
+        key = %i[structuredContent structured_content].find { |k| result.key?(k) } ||
+              %w[structuredContent structured_content].find { |k| result.key?(k) }
+        return [result, false] if key.nil?
+
+        structured = result[key]
+        return [result, false] unless structured.is_a?(Hash)
+        return [result, false] if structured.key?(MCP_INSTRUCTIONS_KEY) || structured.key?(MCP_INSTRUCTIONS_KEY.to_sym)
+
+        payload = { 'conversation_id' => conversation_id }
+        instructions_key = structured.keys.first.is_a?(Symbol) ? MCP_INSTRUCTIONS_KEY.to_sym : MCP_INSTRUCTIONS_KEY
+        [result.merge(key => structured.merge(instructions_key => payload)), true]
+      end
+    end
+  end
+end

data/lib/txlemetry/mcp/event_builder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Txlemetry
+  module MCP
+    # Translates a processed internal event (string keys) into one or two
+    # Txlemetry 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