signalwire-sdk 2.0.0

data/lib/signalwire/agent/agent_base.rb

@@ -0,0 +1,2134 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require 'json'
+require 'securerandom'
+require 'openssl'
+require 'rack'
+require 'uri'
+require_relative '../logging'
+require_relative '../runtime'
+require_relative '../swml/document'
+require_relative '../swml/schema'
+require_relative '../swml/service'
+require_relative '../swaig/function_result'
+require_relative '../security/session_manager'
+require_relative '../security/webhook_validator'
+require_relative '../security/webhook_middleware'
+require_relative '../contexts/context_builder'
+require_relative '../skills/skill_base'
+require_relative '../skills/skill_manager'
+require_relative '../skills/skill_registry'
+
+module SignalWire
+  # Central agent class that composes SWML rendering, tool dispatch,
+  # prompt management, AI config, and HTTP serving.
+  #
+  # AgentBase extends SWMLService with agent-specific capabilities:
+  #  - Prompt management (POM sections and raw text)
+  #  - Tool (SWAIG function) registration & dispatch
+  #  - AI configuration (hints, languages, pronunciations, params)
+  #  - Verb management (pre/post answer, post-AI)
+  #  - Context & step workflows
+  #  - Skill integration
+  #  - Dynamic configuration via per-request ephemeral copies
+  #
+  # All configuration methods return +self+ for method chaining.
+  class AgentBase < SWML::Service
+    # Python parity:
+    # - ``logger`` — agent-specific structured logger (Python: ``self.log``).
+    # - ``skill_manager`` — owning SkillManager (Python's ``self.skill_manager``).
+    # - ``agent_id`` — UUID identifier from constructor or auto-generated.
+    # - ``default_webhook_url`` — base URL for SWAIG webhook fallbacks.
+    # - ``native_functions`` — names of built-in SWAIG functions to advertise.
+    # - ``use_pom`` — whether prompt-object-model rendering is enabled.
+    attr_reader :logger, :skill_manager, :agent_id, :default_webhook_url,
+                :native_functions, :use_pom, :signing_key
+
+    # Maximum request body size (1 MB)
+    MAX_BODY_SIZE = 1_048_576
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def initialize(name: 'agent', route: '/', host: '0.0.0.0', port: nil,
+                   basic_auth: nil,
+                   use_pom: true,
+                   token_expiry_secs: 3600,
+                   auto_answer: true, record_call: false,
+                   record_format: 'mp4', record_stereo: true,
+                   default_webhook_url: nil,
+                   agent_id: nil,
+                   native_functions: nil,
+                   schema_path: nil,
+                   suppress_logs: false,
+                   enable_post_prompt_override: false,
+                   check_for_input_override: false,
+                   config_file: nil,
+                   schema_validation: true,
+                   signing_key: nil,
+                   trust_proxy_for_signature: false)
+      # Resolve auth before super so we can warn about auto-generated
+      # passwords. Service's built-in auth fallback uses a fresh UUID per
+      # process, which is fine, but we want the agent-specific warning.
+      password_auto_generated = false
+      resolved_auth = if basic_auth
+                        basic_auth
+                      elsif ENV['SWML_BASIC_AUTH_USER'] && ENV['SWML_BASIC_AUTH_PASSWORD']
+                        [ENV['SWML_BASIC_AUTH_USER'], ENV['SWML_BASIC_AUTH_PASSWORD']]
+                      else
+                        password_auto_generated = true
+                        [(ENV['SWML_BASIC_AUTH_USER'] || SecureRandom.uuid), SecureRandom.uuid]
+                      end
+
+      super(name: name, route: route, host: host, port: port, basic_auth: resolved_auth,
+            schema_path: schema_path, config_file: config_file,
+            schema_validation: schema_validation)
+      @logger = Logging.logger("AgentBase[#{name}]")
+      @suppress_logs = suppress_logs
+
+      if password_auto_generated
+        # Warn loudly so external callers (tests, RPC clients, MCP)
+        # know why they are getting HTTP 401. This is the silent cause
+        # of every external caller failing when .env wasn't loaded —
+        # the password lives only in this process and changes on every
+        # restart.
+        @logger.warn(
+          "basic_auth_password_autogenerated: username=#{@basic_auth[0].inspect}. " \
+          "No SWML_BASIC_AUTH_PASSWORD found in environment and no basic_auth " \
+          "passed to the agent constructor. The SDK generated a random " \
+          "password that exists only in this process; external callers will " \
+          "get HTTP 401 unless they read the value from this process's env. " \
+          "To fix, set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD in " \
+          "your environment, or pass basic_auth: [user, pass] to " \
+          "AgentBase.new."
+        )
+      end
+
+      # --- call settings ------------------------------------------------
+      @auto_answer   = auto_answer
+      @record_call   = record_call
+      @record_format = record_format
+      @record_stereo = record_stereo
+
+      # --- POM / prompt-mode flags --------------------------------------
+      # Python parity: AgentBase constructor stores ``use_pom`` to
+      # toggle POM-vs-raw prompt rendering. Ruby's POM is implicit (we
+      # always have a @pom_sections array), but we honour the flag so
+      # set_prompt_pom and friends can refuse when POM mode is off.
+      @use_pom = use_pom
+
+      # --- agent identity / config --------------------------------------
+      # Python parity: ``agent_id`` (optional explicit UUID) and
+      # ``default_webhook_url`` (used when SWAIG functions don't carry
+      # an explicit URL). ``native_functions`` lists native SWAIG
+      # callables that should appear in the SWAIG block alongside
+      # user tools.
+      @agent_id            = agent_id || SecureRandom.uuid
+      @default_webhook_url = default_webhook_url
+      @native_functions    = native_functions || []
+
+      # --- override / validation flags ----------------------------------
+      # Python parity: ``enable_post_prompt_override`` and
+      # ``check_for_input_override`` are wired through the FastAPI
+      # endpoint dispatcher. Ruby stashes them so subclass-controlled
+      # routes can opt into the same behaviour.
+      @enable_post_prompt_override = enable_post_prompt_override
+      @check_for_input_override    = check_for_input_override
+
+      # --- session manager ----------------------------------------------
+      @session_manager = Security::SessionManager.new(token_expiry_secs: token_expiry_secs)
+
+      # --- webhook signature validation (porting-sdk/webhooks.md) -------
+      # Resolution order: explicit constructor arg → SIGNALWIRE_SIGNING_KEY env.
+      # When set, _build_rack_app mounts WebhookMiddleware on the signed
+      # routes (POST /, /swaig, /post_prompt). When unset, the SDK logs a
+      # warning so production users notice unsigned traffic is being
+      # accepted.
+      @signing_key = signing_key || ENV['SIGNALWIRE_SIGNING_KEY']
+      @trust_proxy_for_signature = trust_proxy_for_signature
+      if @signing_key && !@signing_key.empty?
+        @logger.info('webhook_signature_validation_enabled') unless @suppress_logs
+      else
+        unless @suppress_logs
+          @logger.warn(
+            '[signalwire] webhook signature validation is disabled — ' \
+            'set signing_key or SIGNALWIRE_SIGNING_KEY to enable'
+          )
+        end
+      end
+
+      # --- prompt state -------------------------------------------------
+      @prompt_text      = nil    # raw text mode
+      @prompt_pom       = nil    # direct POM array
+      @pom_sections     = []     # built via prompt_add_section
+      @post_prompt_text = nil
+
+      # --- tools --------------------------------------------------------
+      # @tools and @swaig_functions are now initialised by Service (parent).
+      # AgentBase's enhanced define_tool overrides Service's plain version.
+
+      # --- AI config ----------------------------------------------------
+      @hints               = []
+      @languages           = []
+      @pronounce           = []
+      @params              = {}
+      @global_data         = {}
+      @function_includes   = []
+      @internal_fillers    = {}
+      @prompt_llm_params   = {}
+      @post_prompt_llm_params = {}
+
+      # --- debug --------------------------------------------------------
+      @debug_events_enabled = false
+      @debug_events_level   = 1
+      @debug_event_callback = nil
+
+      # --- verbs --------------------------------------------------------
+      @pre_answer_verbs  = []    # [[verb_name, config], ...]
+      @answer_config     = {}
+      @post_answer_verbs = []
+      @post_ai_verbs     = []
+
+      # --- contexts -----------------------------------------------------
+      @context_builder   = nil
+
+      # --- skills -------------------------------------------------------
+      # Python parity: ``SkillManager(agent)`` keeps a back-pointer
+      # to the owning agent so loaded skills can attach SWAIG tools
+      # and prompt sections directly through the manager.
+      @skill_manager     = Skills::SkillManager.new(self)
+      @loaded_skills     = {}    # skill_name => SkillBase
+
+      # --- web ----------------------------------------------------------
+      @dynamic_config_callback = nil
+      @proxy_url_base          = ENV['SWML_PROXY_URL_BASE']
+      @web_hook_url_override   = nil
+      @post_prompt_url_override = nil
+      @swaig_query_params      = {}
+      @debug_routes_enabled    = false
+      @summary_callback        = nil
+
+      # --- SIP ----------------------------------------------------------
+      @sip_routing_enabled = false
+      @sip_auto_map        = false
+      @sip_path            = '/sip'
+      @sip_usernames       = []
+
+      # --- MCP ----------------------------------------------------------
+      @mcp_servers         = []     # external MCP server configs
+      @mcp_server_enabled  = false  # expose /mcp endpoint
+
+      @logger.info "Agent '#{@name}' initialised (route=#{@route}, port=#{@port})"
+    end
+
+    # ==================================================================
+    # Prompt methods
+    # ==================================================================
+
+    # Set prompt as raw text. Clears any POM state.
+    def set_prompt_text(text)
+      @prompt_text  = text
+      @pom_sections = []
+      @prompt_pom   = nil
+      self
+    end
+
+    # Set post-prompt text.
+    def set_post_prompt(text)
+      @post_prompt_text = text
+      self
+    end
+
+    # Set POM array directly.
+    def set_prompt_pom(pom)
+      @prompt_pom   = pom
+      @prompt_text  = nil
+      @pom_sections = []
+      self
+    end
+
+    # Add a POM section.
+    #
+    # Python parity:
+    # ``prompt_add_section(title, body="", bullets=None,
+    # numbered=False, numbered_bullets=False, subsections=None)``.
+    #
+    # @param title [String] section title
+    # @param body  [String, nil] optional body text
+    # @param bullets [Array<String>, nil] optional bullet items
+    # @param numbered [Boolean] render as a numbered top-level entry
+    # @param numbered_bullets [Boolean] render bullets as numbered
+    # @param subsections [Array<Hash>, nil] optional pre-rendered
+    #   subsection hashes (each ``{title:, body:, bullets:}``)
+    def prompt_add_section(title, body = nil, bullets: nil,
+                           numbered: false, numbered_bullets: false,
+                           subsections: nil)
+      @prompt_text = nil
+      @prompt_pom  = nil
+      section = { 'title' => title }
+      section['body']             = body              if body
+      section['bullets']          = bullets           if bullets
+      section['numbered']         = true              if numbered
+      section['numbered_bullets'] = true              if numbered_bullets
+
+      if subsections.is_a?(Array) && !subsections.empty?
+        section['subsections'] = subsections.map do |sub|
+          h = { 'title' => sub['title'] || sub[:title] }
+          h['body']    = sub['body']    || sub[:body]    if (sub['body'] || sub[:body])
+          h['bullets'] = sub['bullets'] || sub[:bullets] if (sub['bullets'] || sub[:bullets])
+          h
+        end
+      end
+
+      @pom_sections << section
+      self
+    end
+
+    # Append content to an existing POM section, creating it if absent.
+    #
+    # Python parity:
+    # ``prompt_add_to_section(title, body=None, bullet=None,
+    # bullets=None)``. Supports appending body text, a single bullet,
+    # or a list of bullets.
+    #
+    # @param title [String] section title
+    # @param body  [String, nil] body text to append
+    # @param bullet [String, nil] single bullet to append
+    # @param bullets [Array<String>, nil] bullets to append
+    #
+    # **Backwards compat:** the original Ruby signature was
+    # ``prompt_add_to_section(title, text)``. When called with two
+    # positional arguments the second becomes ``body``; this preserves
+    # existing call sites while still supporting Python's keyword form.
+    def prompt_add_to_section(title, body_arg = nil, body: nil, bullet: nil, bullets: nil)
+      effective_body = body || body_arg
+
+      sec = @pom_sections.find { |s| s['title'] == title }
+      unless sec
+        sec = { 'title' => title }
+        @pom_sections << sec
+      end
+
+      if effective_body
+        sec['body'] = (sec['body'] || '') + effective_body.to_s
+      end
+
+      to_add = []
+      to_add << bullet if bullet
+      to_add.concat(bullets) if bullets.is_a?(Array)
+      unless to_add.empty?
+        sec['bullets'] = (sec['bullets'] || []) + to_add
+      end
+
+      self
+    end
+
+    # Add a subsection under a parent section.
+    def prompt_add_subsection(parent_title, title, body = nil, bullets: nil)
+      parent = @pom_sections.find { |s| s['title'] == parent_title }
+      if parent
+        parent['subsections'] ||= []
+        sub = { 'title' => title }
+        sub['body']    = body    if body
+        sub['bullets'] = bullets if bullets
+        parent['subsections'] << sub
+      end
+      self
+    end
+
+    # Check whether a POM section with the given title exists.
+    def prompt_has_section?(title)
+      @pom_sections.any? { |s| s['title'] == title }
+    end
+
+    # Return the current prompt: either a string (text mode) or an array (POM).
+    def get_prompt
+      return @prompt_text if @prompt_text
+      return @prompt_pom  if @prompt_pom
+      return @pom_sections.dup unless @pom_sections.empty?
+      nil
+    end
+
+    # Read-only snapshot of the agent's POM as a typed
+    # {SignalWire::POM::PromptObjectModel} instance.
+    #
+    # Python parity: ``agent.pom`` instance attribute (agent_base.py
+    # line 209) is a ``PromptObjectModel`` instance. Returns ``nil`` when
+    # raw-text prompt mode is in effect (``set_prompt_text`` was called)
+    # — mirrors Python's ``self.pom = None when use_pom=False``.
+    #
+    # The returned PromptObjectModel is a fresh build of the agent's
+    # current section state, so caller mutations do not leak into agent
+    # state. Use ``agent.pom.to_h`` to retrieve the legacy
+    # array-of-hashes representation.
+    def pom
+      return nil if @prompt_text
+
+      sections = @prompt_pom || @pom_sections
+      pom = SignalWire::POM::PromptObjectModel.new
+      sections.each do |sec|
+        # Each section is a Hash with possibly String or Symbol keys.
+        h = sec.transform_keys(&:to_s)
+        kwargs = {
+          body: h.fetch('body', ''),
+          bullets: h['bullets'] || [],
+          numbered: h['numbered'],
+          numbered_bullets: h['numbered_bullets'] || h['numberedBullets'] || false
+        }
+        section = pom.add_section(h['title'], **kwargs)
+        (h['subsections'] || []).each do |sub|
+          sh = sub.transform_keys(&:to_s)
+          section.add_subsection(
+            sh['title'],
+            body: sh.fetch('body', ''),
+            bullets: sh['bullets'] || [],
+            numbered: sh['numbered'] || false,
+            numbered_bullets: sh['numbered_bullets'] || sh['numberedBullets'] || false
+          )
+        end
+      end
+      pom
+    end
+
+    # Returns the post-prompt text whatever set_post_prompt stored, or
+    # nil when no post-prompt has been set.
+    #
+    # Mirrors Python's PromptManager#get_post_prompt /
+    # PromptMixin#get_post_prompt — used by SWML rendering when a
+    # post-prompt is configured.
+    def get_post_prompt
+      @post_prompt_text
+    end
+
+    # Returns the raw prompt text whatever set_prompt_text stored, or
+    # nil when no raw prompt has been set. Distinct from #get_prompt
+    # which may return the POM array when use_pom is true.
+    #
+    # Mirrors Python's PromptManager#get_raw_prompt.
+    def get_raw_prompt
+      @prompt_text
+    end
+
+    # Returns the contexts dictionary as a serialised hash, or nil when
+    # no contexts have been defined yet.
+    #
+    # Mirrors Python's PromptManager#get_contexts which returns the
+    # contexts dict or None.
+    def get_contexts
+      return nil if @context_builder.nil?
+      @context_builder.to_h
+    end
+
+    # ==================================================================
+    # Tool methods
+    # ==================================================================
+
+    # Register a SWAIG tool (function) that the AI can invoke during a
+    # call.
+    #
+    # == How this becomes a tool the model sees
+    #
+    # A SWAIG function is *exactly the same concept* as a "tool" in
+    # native OpenAI / Anthropic tool calling. On every LLM turn, the
+    # SDK renders each registered SWAIG function into the OpenAI tool
+    # schema:
+    #
+    #     {
+    #       "type": "function",
+    #       "function": {
+    #         "name":        "your_name_here",
+    #         "description": "your description text",
+    #         "parameters":  { ... your JSON schema ... }
+    #       }
+    #     }
+    #
+    # That schema is sent to the model as part of the same API call
+    # that produces the next assistant message. The model reads:
+    #
+    #   - the function +description+ to decide WHEN to call this tool
+    #   - each parameter +description+ (inside +parameters+) to decide
+    #     HOW to fill in that argument from the user's utterance
+    #
+    # This means *descriptions are prompt engineering*, not developer
+    # comments. A vague description is the #1 cause of "the model has
+    # the right tool but doesn't call it" failures.
+    #
+    # == Bad vs good descriptions
+    #
+    #   BAD : description: "Lookup function"
+    #   GOOD: description: "Look up a customer's account details by " \
+    #                      "account number. Use this BEFORE quoting "  \
+    #                      "any account-specific info (balance, plan, " \
+    #                      "status). Do not use for general product "  \
+    #                      "questions."
+    #
+    #   BAD : parameters: { id: { type: 'string', description: 'the id' } }
+    #   GOOD: parameters: { account_number: { type: 'string',
+    #             description: "The customer's 8-digit account " \
+    #             "number, no dashes or spaces. Ask the user if they " \
+    #             "don't provide it." } }
+    #
+    # == Tool count matters
+    #
+    # LLM tool selection accuracy degrades past ~7-8
+    # simultaneously-active tools per call. Use
+    # Contexts::Step#set_functions to partition tools across steps so
+    # only the relevant subset is active at any moment.
+    #
+    # @param name [String] function name (snake_case verb recommended)
+    # @param description [String] LLM-facing description of when to
+    #   call this tool
+    # @param parameters [Hash] JSON-Schema properties with LLM-facing
+    #   descriptions for each parameter
+    # @param secure [Boolean]
+    # @param fillers [Hash, nil] language_code => [phrases]
+    # @param swaig_fields [Hash, nil] extra fields merged into definition
+    # @yield [args, raw_data] the tool handler
+    # Define a SWAIG tool.
+    #
+    # Python parity:
+    # ``define_tool(name, description, parameters, handler,
+    # secure=True, fillers=None, wait_file=None, wait_file_loops=None,
+    # webhook_url=None, required=None, is_typed_handler=False,
+    # **swaig_fields)``.
+    #
+    # @param name [String] tool name
+    # @param description [String] LLM-facing description
+    # @param parameters [Hash] JSON-Schema parameters
+    # @param handler [Proc, nil] explicit handler (alternative to a
+    #   block); kept for backward compat
+    # @param secure [Boolean] require token validation. Ruby defaults
+    #   to ``false`` (kept for backward compat); Python defaults to
+    #   ``True``. Pass ``secure: true`` to match Python.
+    # @param fillers [Hash, nil] language-keyed filler phrases
+    # @param wait_file [String, nil] URL of audio file to play while
+    #   the tool runs server-side
+    # @param wait_file_loops [Integer, nil] loop count for ``wait_file``
+    # @param webhook_url [String, nil] external endpoint to use
+    #   instead of dispatching to the local handler
+    # @param required [Array<String>, nil] required parameter names
+    # @param is_typed_handler [Boolean] handler accepts type-coerced
+    #   keyword args (parity flag; Ruby uses dynamic typing so this
+    #   is a no-op at runtime but is preserved for surface parity)
+    # @param swaig_fields [Hash, nil] additional fields merged into
+    #   the SWAIG function definition
+    # @yield [args, raw_data] tool handler body (alternative to
+    #   passing ``handler:``)
+    def define_tool(name:, description:, parameters: {}, handler: nil,
+                    secure: false, fillers: nil,
+                    wait_file: nil, wait_file_loops: nil,
+                    webhook_url: nil, required: nil,
+                    is_typed_handler: false,
+                    swaig_fields: nil, &block)
+      # Block is canonical — falls back to explicit handler kwarg.
+      effective_handler = block || handler
+
+      # Normalise parameters into JSON-Schema form
+      param_schema = _normalise_parameters(parameters)
+
+      # If the caller supplied required: (Python parity), inject it
+      # into the parameter schema so SWML rendering carries the list.
+      if required.is_a?(Array) && !required.empty?
+        if param_schema.is_a?(Hash) && param_schema['type'] == 'object'
+          existing = param_schema['required'] || []
+          param_schema['required'] = (existing + required).uniq
+        end
+      end
+
+      tool_def = {
+        'function'    => name,
+        'description' => description,
+        'parameters'  => param_schema
+      }
+      tool_def['fillers']          = fillers          if fillers && !fillers.empty?
+      tool_def['wait_file']        = wait_file        if wait_file
+      tool_def['wait_file_loops']  = wait_file_loops  if wait_file_loops
+      tool_def['webhook_url']      = webhook_url      if webhook_url
+      tool_def['is_typed_handler'] = true             if is_typed_handler
+
+      # Merge extra swaig fields
+      if swaig_fields.is_a?(Hash)
+        swaig_fields.each { |k, v| tool_def[k.to_s] = v }
+      end
+
+      @tools[name] = {
+        definition: tool_def,
+        handler:    effective_handler,
+        secure:     secure
+      }
+      self
+    end
+
+    # Register a raw SWAIG function definition (e.g. from DataMap#to_swaig_function).
+    def register_swaig_function(func_def)
+      fname = func_def['function'] || func_def[:function]
+      return self unless fname
+      @swaig_functions[fname] = func_def.transform_keys(&:to_s)
+      self
+    end
+
+    # Return an array of all tool definitions (for SWML rendering).
+    def define_tools
+      defs = @tools.values.map { |t| t[:definition].dup }
+      defs + @swaig_functions.values.map(&:dup)
+    end
+
+    # Mint a per-call SWAIG-function token via the agent's SessionManager.
+    #
+    # Python parity: state_mixin.StateMixin#_create_tool_token —
+    # delegates to SessionManager#create_token and returns "" on any
+    # raised error (Python rescues all exceptions and returns "").
+    def create_tool_token(tool_name, call_id)
+      @session_manager.create_token(tool_name, call_id)
+    rescue StandardError
+      ''
+    end
+
+    # Validate a per-call SWAIG-function token. Returns false when the
+    # function is not registered, when the SessionManager rejects the
+    # token, or on any underlying exception.
+    #
+    # Python parity: state_mixin.StateMixin#validate_tool_token —
+    # rejects unknown function names up-front and rescues exceptions.
+    def validate_tool_token(function_name, token, call_id)
+      return false unless has_function(function_name)
+      @session_manager.validate_token(function_name, token, call_id)
+    rescue StandardError
+      false
+    end
+
+    # Dispatch a function call to the registered handler.
+    def on_function_call(name, args, raw_data)
+      tool = @tools[name]
+      unless tool
+        return { 'response' => "Function '#{name}' not found" }
+      end
+
+      # Validate secure token if needed
+      if tool[:secure]
+        call_id = raw_data && (raw_data['call_id'] || (raw_data['call'] && raw_data['call']['call_id']))
+        token   = raw_data && raw_data['meta_data_token']
+        if call_id && token
+          unless @session_manager.validate_token(name, token, call_id)
+            return { 'response' => 'Invalid or expired token' }
+          end
+        end
+      end
+
+      result = tool[:handler].call(args, raw_data)
+      if result.is_a?(Hash)
+        result
+      elsif result.respond_to?(:to_h) && !result.nil?
+        # FunctionResult-like object that responds to to_h.
+        result.to_h
+      else
+        # Neither a Hash nor a FunctionResult-like object. Warn and
+        # fall back to wrapping the stringified value, matching
+        # Python's web_mixin / serverless_mixin / tool_mixin behavior.
+        @logger.warn(
+          "unexpected_function_result_type: function=#{name.inspect} " \
+          "result_type=#{result.class.name.inspect}. SWAIG function " \
+          "returned a value that is neither a FunctionResult (responds " \
+          "to to_h) nor a Hash; falling back to wrapping the " \
+          "stringified value. The AI will see the stringified value as " \
+          "its tool response. Return a " \
+          "SignalWire::SWAIG::FunctionResult object or a Hash with at " \
+          "least a 'response' key."
+        )
+        { 'response' => result.to_s }
+      end
+    rescue => e
+      @logger.error "Tool '#{name}' error: #{e.message}"
+      { 'response' => "Error executing '#{name}': #{e.message}" }
+    end
+
+    # ==================================================================
+    # AI Config methods
+    # ==================================================================
+
+    def add_hint(hint)
+      @hints << hint if hint.is_a?(String) && !hint.empty?
+      self
+    end
+
+    def add_hints(hints)
+      if hints.is_a?(Array)
+        hints.each { |h| add_hint(h) }
+      end
+      self
+    end
+
+    # Add a complex (pattern-matched) hint.
+    #
+    # Python parity:
+    # ``add_pattern_hint(hint, pattern, replace, ignore_case=False)``.
+    # Ruby supports both the Python-style positional form and the
+    # legacy keyword form (``add_pattern_hint(pattern, hint:, language:)``)
+    # for backward compat.
+    #
+    # @overload add_pattern_hint(hint, pattern, replace, ignore_case: false)
+    #   @param hint [String] hint to match
+    #   @param pattern [String] regex pattern
+    #   @param replace [String] replacement text
+    #   @param ignore_case [Boolean] match without regard to case
+    # @overload add_pattern_hint(pattern, hint:, language: 'en-US')
+    #   Legacy Ruby form — pattern + optional hint string and language.
+    def add_pattern_hint(*args, hint: nil, pattern: nil, replace: nil,
+                        ignore_case: false, language: 'en-US')
+      # Three positional args = Python positional shape.
+      if args.length == 3
+        h_hint, h_pattern, h_replace = args
+        @hints << {
+          'hint'        => h_hint,
+          'pattern'     => h_pattern,
+          'replace'     => h_replace,
+          'ignore_case' => ignore_case
+        }
+        return self
+      end
+
+      # Single positional ≡ legacy ``add_pattern_hint(pattern, hint:, language:)``.
+      if args.length == 1 && pattern.nil? && replace.nil?
+        legacy_pattern = args.first
+        entry = { 'pattern' => legacy_pattern }
+        entry['hint']     = hint     if hint
+        entry['language'] = language if language
+        @hints << entry
+        return self
+      end
+
+      # Pure-keyword form (Python-named keywords)
+      if pattern && hint && replace
+        @hints << {
+          'hint'        => hint,
+          'pattern'     => pattern,
+          'replace'     => replace,
+          'ignore_case' => ignore_case
+        }
+        return self
+      end
+
+      raise ArgumentError, 'add_pattern_hint: pass either (hint, pattern, replace) or use legacy (pattern, hint:, language:) form'
+    end
+
+    # Add a language configuration.
+    #
+    # Python parity: ``add_language(name, code, voice, speech_fillers=None,
+    # function_fillers=None, engine=None, model=None)``. Ruby supports
+    # both the Python-style positional shape AND the original
+    # ``add_language(config)`` hash form.
+    #
+    # Voice argument can be either a simple voice id (``"en-US-Neural2-F"``)
+    # or a combined ``"engine.voice:model"`` string
+    # (``"elevenlabs.josh:eleven_turbo_v2_5"``); the combined form is
+    # parsed into ``engine``/``voice``/``model`` keys when ``engine``
+    # and ``model`` aren't supplied explicitly.
+    #
+    # @overload add_language(config)
+    #   @param config [Hash] preformed language config
+    # @overload add_language(name, code, voice, speech_fillers: nil,
+    #   function_fillers: nil, engine: nil, model: nil, params: nil)
+    #   @param name [String] language name (e.g. ``"English"``)
+    #   @param code [String] BCP47 language code (e.g. ``"en-US"``)
+    #   @param voice [String] voice id or ``engine.voice:model`` string
+    #   @param speech_fillers [Array<String>, nil] filler phrases for
+    #     natural speech
+    #   @param function_fillers [Array<String>, nil] filler phrases
+    #     during function calls
+    #   @param engine [String, nil] explicit engine override
+    #   @param model [String, nil] explicit model override
+    #   @param params [Hash, nil] optional per-language params (engine-
+    #     specific tuning, voice settings, etc.). Emitted as the language
+    #     object's ``params`` key in SWML; the key is only emitted when
+    #     non-empty so existing entries stay byte-identical.
+    def add_language(name_or_config, code = nil, voice = nil,
+                     speech_fillers: nil, function_fillers: nil,
+                     engine: nil, model: nil, params: nil)
+      # Hash form (legacy / direct config)
+      if name_or_config.is_a?(Hash) && code.nil? && voice.nil?
+        @languages << name_or_config
+        return self
+      end
+
+      raise ArgumentError, 'add_language: name, code, voice are required (or pass a Hash)' if code.nil? || voice.nil?
+
+      lang = { 'name' => name_or_config, 'code' => code }
+
+      if engine || model
+        lang['voice']  = voice
+        lang['engine'] = engine if engine
+        lang['model']  = model  if model
+      elsif voice.is_a?(String) && voice.include?('.') && voice.include?(':')
+        # "engine.voice:model"
+        engine_voice, model_part = voice.split(':', 2)
+        engine_part, voice_part  = engine_voice.split('.', 2)
+        lang['voice']  = voice_part
+        lang['engine'] = engine_part
+        lang['model']  = model_part
+      else
+        lang['voice'] = voice
+      end
+
+      if speech_fillers && function_fillers
+        lang['speech_fillers']   = speech_fillers
+        lang['function_fillers'] = function_fillers
+      elsif speech_fillers || function_fillers
+        lang['fillers'] = speech_fillers || function_fillers
+      end
+
+      # Per-language params (engine-specific tuning, voice settings,
+      # etc.). Only emit the key when non-empty so we don't pollute
+      # SWML with empty objects.
+      lang['params'] = params if params.is_a?(Hash) && !params.empty?
+
+      @languages << lang
+      self
+    end
+
+    # Set (or replace) the per-language ``params`` dict on an
+    # already-added language. Useful when language entries are built up
+    # via add_language first and engine-specific tuning is added later
+    # (e.g. from a config loader). Returns self for chaining.
+    #
+    # @param code [String] language code as previously passed to
+    #   ``add_language`` (e.g. ``"en-US"``).
+    # @param params [Hash] engine-specific params hash to attach.
+    #   Empty hash removes the key.
+    # @return [self] No-op if the code isn't found.
+    def set_language_params(code, params)
+      @languages.each do |lang|
+        next unless lang.is_a?(Hash) && lang['code'] == code
+        if params.is_a?(Hash) && !params.empty?
+          lang['params'] = params
+        else
+          lang.delete('params')
+        end
+        break
+      end
+      self
+    end
+
+    # Read the per-language ``params`` hash for a previously-added
+    # language.
+    #
+    # @param code [String] language code as previously passed to ``add_language``.
+    # @return [Hash, nil] the params hash if set, ``nil`` otherwise
+    #   (including when the code is unknown).
+    def get_language_params(code)
+      @languages.each do |lang|
+        return lang['params'] if lang.is_a?(Hash) && lang['code'] == code
+      end
+      nil
+    end
+
+    def set_languages(languages)
+      @languages = languages.dup if languages.is_a?(Array)
+      self
+    end
+
+    def add_pronunciation(phrase, pronunciation, language_code: 'en-US')
+      rule = { 'replace' => phrase, 'with' => pronunciation }
+      rule['ignore_case'] = false
+      @pronounce << rule
+      self
+    end
+
+    def set_pronunciations(pronunciations)
+      @pronounce = pronunciations.dup if pronunciations.is_a?(Array)
+      self
+    end
+
+    def set_param(key, value)
+      @params[key.to_s] = value
+      self
+    end
+
+    def set_params(params)
+      if params.is_a?(Hash)
+        params.each { |k, v| @params[k.to_s] = v }
+      end
+      self
+    end
+
+    def set_global_data(data)
+      @global_data.merge!(data) if data.is_a?(Hash)
+      self
+    end
+
+    def update_global_data(data)
+      set_global_data(data)
+    end
+
+    def set_native_functions(names)
+      @native_functions = names.dup if names.is_a?(Array)
+      self
+    end
+
+    # The complete set of internal SWAIG function names that accept
+    # fillers, matching the SWAIGInternalFiller schema definition.
+    #
+    # Any name outside this set is silently ignored by the runtime —
+    # +set_internal_fillers+ and +add_internal_filler+ warn if you pass
+    # an unknown name.
+    #
+    # Notable absences: +change_step+, +gather_submit+, or arbitrary
+    # user-defined SWAIG function names are NOT supported.
+    SUPPORTED_INTERNAL_FILLER_NAMES = %w[
+      hangup
+      check_time
+      wait_for_user
+      wait_seconds
+      adjust_response_latency
+      next_step
+      change_context
+      get_visual_input
+      get_ideal_strategy
+    ].freeze
+
+    # Set internal fillers for native SWAIG functions.
+    #
+    # Internal fillers are short phrases the AI agent speaks (via TTS)
+    # while an internal/native function is running, so the caller
+    # doesn't hear dead air during transitions or background work.
+    #
+    # Supported function names (match the SWAIGInternalFiller schema):
+    # +hangup+, +check_time+, +wait_for_user+, +wait_seconds+,
+    # +adjust_response_latency+, +next_step+, +change_context+,
+    # +get_visual_input+, +get_ideal_strategy+. See
+    # SUPPORTED_INTERNAL_FILLER_NAMES.
+    #
+    # Notably NOT supported: +change_step+, +gather_submit+, or
+    # arbitrary user-defined SWAIG function names. The runtime only
+    # honors fillers for the names listed above; everything else is
+    # silently ignored at the SWML level. This method warns at
+    # registration time if you pass an unknown name so you catch the
+    # typo early.
+    #
+    # Expected format: +{ function_name => { language_code => [phrases] } }+
+    def set_internal_fillers(fillers)
+      if fillers.is_a?(Hash)
+        unknown = (fillers.keys.map(&:to_s) - SUPPORTED_INTERNAL_FILLER_NAMES).sort
+        if unknown.any?
+          @logger.warn(
+            "unknown_internal_filler_names: #{unknown.inspect}. " \
+            "set_internal_fillers received names that the SWML schema " \
+            "does not recognize. Those entries will be ignored by the " \
+            "runtime. Supported names: #{SUPPORTED_INTERNAL_FILLER_NAMES.sort.inspect}."
+          )
+        end
+        @internal_fillers.merge!(fillers)
+      end
+      self
+    end
+
+    # Add internal fillers for a single internal function and language.
+    #
+    # See +set_internal_fillers+ for the complete list of supported
+    # +func_name+ values (SUPPORTED_INTERNAL_FILLER_NAMES) and what
+    # fillers do. Names outside the supported set log a warning and are
+    # stored but the runtime will not play them.
+    def add_internal_filler(func_name, lang_code, fillers)
+      if func_name && lang_code && fillers.is_a?(Array) && !fillers.empty?
+        unless SUPPORTED_INTERNAL_FILLER_NAMES.include?(func_name.to_s)
+          @logger.warn(
+            "unknown_internal_filler_name: #{func_name.inspect}. " \
+            "add_internal_filler received a function name the SWML " \
+            "schema does not recognize. The entry will be stored but " \
+            "the runtime will not play these fillers. Supported " \
+            "names: #{SUPPORTED_INTERNAL_FILLER_NAMES.sort.inspect}."
+          )
+        end
+        @internal_fillers[func_name] ||= {}
+        @internal_fillers[func_name][lang_code] = fillers
+      end
+      self
+    end
+
+    def enable_debug_events(level = 1)
+      @debug_events_enabled = true
+      @debug_events_level   = level
+      self
+    end
+
+    def add_function_include(url, functions, meta_data: nil)
+      include = { 'url' => url, 'functions' => functions }
+      include['meta_data'] = meta_data if meta_data.is_a?(Hash)
+      @function_includes << include
+      self
+    end
+
+    def set_function_includes(includes)
+      @function_includes = includes.dup if includes.is_a?(Array)
+      self
+    end
+
+    def set_prompt_llm_params(**params)
+      @prompt_llm_params.merge!(params.transform_keys(&:to_s))
+      self
+    end
+
+    def set_post_prompt_llm_params(**params)
+      @post_prompt_llm_params.merge!(params.transform_keys(&:to_s))
+      self
+    end
+
+    # ==================================================================
+    # Verb management
+    # ==================================================================
+
+    def add_pre_answer_verb(verb_name, config)
+      @pre_answer_verbs << [verb_name.to_s, config]
+      self
+    end
+
+    def clear_pre_answer_verbs
+      @pre_answer_verbs = []
+      self
+    end
+
+    def add_answer_verb(config)
+      @answer_config = config
+      self
+    end
+
+    def add_post_answer_verb(verb_name, config)
+      @post_answer_verbs << [verb_name.to_s, config]
+      self
+    end
+
+    def clear_post_answer_verbs
+      @post_answer_verbs = []
+      self
+    end
+
+    def add_post_ai_verb(verb_name, config)
+      @post_ai_verbs << [verb_name.to_s, config]
+      self
+    end
+
+    def clear_post_ai_verbs
+      @post_ai_verbs = []
+      self
+    end
+
+    # ==================================================================
+    # Contexts
+    # ==================================================================
+
+    # Define / retrieve the ContextBuilder for this agent.
+    #
+    # Python parity: ``define_contexts(contexts)`` accepts either a
+    # ``ContextBuilder`` (calls ``.to_dict()`` to materialise) or a
+    # raw ``dict`` and stores it on the agent. Ruby supports both
+    # forms PLUS the original lazy-getter idiom:
+    #
+    # 1. **Lazy getter** (Ruby idiom) — ``agent.define_contexts``
+    #    returns the existing builder, creating one if needed.
+    # 2. **Override with builder** — ``agent.define_contexts(other_cb)``
+    #    replaces the current builder with the supplied one (Python
+    #    parity).
+    # 3. **Override with hash** — ``agent.define_contexts({...})``
+    #    builds a fresh builder using the provided contexts hash
+    #    (Python parity for raw-dict input).
+    #
+    # @param contexts [SignalWire::Contexts::ContextBuilder, Hash, nil]
+    #   optional override
+    # @return [SignalWire::Contexts::ContextBuilder] the active builder
+    def define_contexts(contexts = nil)
+      if contexts.is_a?(Contexts::ContextBuilder)
+        @context_builder = contexts
+        @context_builder.attach_agent(self) if @context_builder.respond_to?(:attach_agent)
+        return @context_builder
+      end
+
+      if contexts.is_a?(Hash)
+        cb = Contexts::ContextBuilder.new(self)
+        contexts.each do |name, body|
+          ctx = cb.add_context(name.to_s)
+          steps = (body.is_a?(Hash) ? body['steps'] : nil) || []
+          steps.each do |step_h|
+            step_name = step_h['name'] || step_h[:name] || raise(ArgumentError, 'step missing name')
+            step = ctx.add_step(step_name)
+            step.set_text(step_h['text']) if step_h['text']
+          end
+        end
+        @context_builder = cb
+        return cb
+      end
+
+      unless contexts.nil?
+        raise ArgumentError, 'contexts must be a ContextBuilder, Hash, or nil'
+      end
+
+      @context_builder ||= begin
+        cb = Contexts::ContextBuilder.new(self)
+        cb.attach_agent(self) if cb.respond_to?(:attach_agent)
+        cb
+      end
+    end
+
+    alias contexts define_contexts
+
+    # Remove all contexts, returning the agent to a no-contexts state.
+    # This is a convenience wrapper around +define_contexts.reset+.
+    # Use it in a dynamic config callback when you need to rebuild
+    # contexts from scratch for a specific request.
+    def reset_contexts
+      @context_builder&.reset
+      self
+    end
+
+    # Return the names of all registered SWAIG tools in insertion
+    # order. Used by ContextBuilder#validate! to detect collisions with
+    # reserved native tool names.
+    def list_tool_names
+      (@tools.keys + @swaig_functions.keys).uniq
+    end
+
+    # ==================================================================
+    # Skill integration
+    # ==================================================================
+
+    # Load and register a skill by name.
+    def add_skill(skill_name, params = {})
+      # Ensure builtins are registered
+      Skills::SkillRegistry.register_builtins!
+
+      factory = Skills::SkillRegistry.get_factory(skill_name)
+      raise ArgumentError, "Unknown skill: '#{skill_name}'" unless factory
+
+      skill = factory.call(params)
+      @skill_manager.load(skill.instance_key, skill)
+      @loaded_skills[skill_name] = skill
+
+      # Register tools from the skill
+      tool_defs = skill.register_tools
+      if tool_defs.is_a?(Array)
+        tool_defs.each do |td|
+          td_name    = td[:name]    || td['name']
+          td_desc    = td[:description] || td['description']
+          td_params  = td[:parameters]  || td['parameters'] || {}
+          td_handler = td[:handler]     || td['handler']
+          next unless td_name && td_handler
+
+          define_tool(
+            name: td_name,
+            description: td_desc || '',
+            parameters: td_params,
+            &td_handler
+          )
+        end
+      end
+
+      # Merge hints
+      skill_hints = skill.get_hints
+      @hints.concat(skill_hints) if skill_hints.is_a?(Array) && !skill_hints.empty?
+
+      # Merge global data
+      skill_data = skill.get_global_data
+      @global_data.merge!(skill_data) if skill_data.is_a?(Hash) && !skill_data.empty?
+
+      # Merge prompt sections
+      skill_sections = skill.get_prompt_sections
+      if skill_sections.is_a?(Array) && !skill_sections.empty?
+        @prompt_text = nil  # switch to POM mode
+        @prompt_pom  = nil
+        skill_sections.each do |sec|
+          @pom_sections << sec
+        end
+      end
+
+      self
+    end
+
+    def remove_skill(skill_name)
+      skill = @loaded_skills.delete(skill_name)
+      @skill_manager.unload(skill.instance_key) if skill
+      self
+    end
+
+    def list_skills
+      @loaded_skills.keys
+    end
+
+    def has_skill?(skill_name)
+      @loaded_skills.key?(skill_name)
+    end
+
+    # ==================================================================
+    # Web / HTTP configuration
+    # ==================================================================
+
+    def set_dynamic_config_callback(callable = nil, &block)
+      @dynamic_config_callback = callable || block
+      self
+    end
+
+    def manual_set_proxy_url(url)
+      @proxy_url_base = url
+      self
+    end
+
+    def set_web_hook_url(url)
+      @web_hook_url_override = url
+      self
+    end
+
+    def set_post_prompt_url(url)
+      @post_prompt_url_override = url
+      self
+    end
+
+    def add_swaig_query_params(params)
+      @swaig_query_params.merge!(params) if params.is_a?(Hash)
+      self
+    end
+
+    def clear_swaig_query_params
+      @swaig_query_params = {}
+      self
+    end
+
+    def enable_debug_routes
+      @debug_routes_enabled = true
+      self
+    end
+
+    # ==================================================================
+    # SIP
+    # ==================================================================
+
+    def enable_sip_routing(auto_map: true, path: '/sip')
+      @sip_routing_enabled = true
+      @sip_auto_map        = auto_map
+      @sip_path            = path
+      self
+    end
+
+    def register_sip_username(username)
+      @sip_usernames << username
+      self
+    end
+
+    # Extract a SIP username from a SIP URI string.
+    #
+    # Parses URIs of the form "sip:user@domain" and returns the user part.
+    # Handles optional "sip:" or "sips:" scheme prefixes.
+    #
+    # @param sip_uri [String] a SIP URI, e.g. "sip:alice@example.com"
+    # @return [String, nil] the username, or nil if the URI cannot be parsed
+    def self.extract_sip_username(sip_uri)
+      return nil if sip_uri.nil? || sip_uri.empty?
+
+      # Strip optional sip:/sips: scheme
+      uri = sip_uri.to_s.strip
+      uri = uri.sub(%r{\Asips?:}, '')
+
+      # Extract user part before @
+      if uri.include?('@')
+        user = uri.split('@', 2).first
+        user && !user.empty? ? user : nil
+      else
+        nil
+      end
+    end
+
+    # Extract the SIP username from request body data.
+    #
+    # Looks for SIP URI in common request body fields
+    # (e.g., "to", "from", "sip_uri", "call.to", "call.from").
+    #
+    # @param request_data [Hash] the parsed request body
+    # @return [String, nil] the extracted SIP username, or nil
+    def self.extract_sip_username_from_request(request_data)
+      return nil unless request_data.is_a?(Hash)
+
+      # Check common SIP URI fields
+      candidates = [
+        request_data['to'],
+        request_data['from'],
+        request_data['sip_uri'],
+        request_data.dig('call', 'to'),
+        request_data.dig('call', 'from')
+      ].compact
+
+      candidates.each do |uri|
+        username = extract_sip_username(uri.to_s)
+        return username if username
+      end
+
+      nil
+    end
+
+    # ==================================================================
+    # MCP integration
+    # ==================================================================
+
+    # Add an external MCP server for tool discovery and invocation.
+    #
+    # @param url [String] MCP server HTTP endpoint URL
+    # @param headers [Hash, nil] optional HTTP headers
+    # @param resources [Boolean] whether to fetch resources into global_data
+    # @param resource_vars [Hash, nil] variables for URI template substitution
+    # @return [self]
+    def add_mcp_server(url, headers: nil, resources: false, resource_vars: nil)
+      server = { 'url' => url }
+      server['headers']       = headers       if headers && !headers.empty?
+      server['resources']     = true          if resources
+      server['resource_vars'] = resource_vars if resource_vars && !resource_vars.empty?
+      @mcp_servers << server
+      self
+    end
+
+    # Expose this agent's tools as an MCP server endpoint at /mcp.
+    #
+    # @return [self]
+    def enable_mcp_server
+      @mcp_server_enabled = true
+      self
+    end
+
+    # @api private
+    # Build MCP tool list from registered tools.
+    def _build_mcp_tool_list
+      tools = []
+      @tools.each do |name, tool|
+        t = {
+          'name'        => name,
+          'description' => tool[:definition]['description'] || name,
+        }
+        params = tool[:definition]['parameters']
+        if params && !params.empty?
+          t['inputSchema'] = params.key?('type') ? params : { 'type' => 'object', 'properties' => params }
+        else
+          t['inputSchema'] = { 'type' => 'object', 'properties' => {} }
+        end
+        tools << t
+      end
+      tools
+    end
+
+    # @api private
+    # Handle a single MCP JSON-RPC 2.0 request and return the response hash.
+    def _handle_mcp_request(body)
+      jsonrpc = body['jsonrpc']
+      method  = body['method'] || ''
+      req_id  = body['id']
+      params  = body['params'] || {}
+
+      unless jsonrpc == '2.0'
+        return _mcp_error(req_id, -32600, 'Invalid JSON-RPC version')
+      end
+
+      case method
+      when 'initialize'
+        {
+          'jsonrpc' => '2.0', 'id' => req_id,
+          'result' => {
+            'protocolVersion' => '2025-06-18',
+            'capabilities'   => { 'tools' => {} },
+            'serverInfo'     => { 'name' => @name, 'version' => '1.0.0' }
+          }
+        }
+      when 'notifications/initialized'
+        { 'jsonrpc' => '2.0', 'id' => req_id, 'result' => {} }
+      when 'tools/list'
+        {
+          'jsonrpc' => '2.0', 'id' => req_id,
+          'result' => { 'tools' => _build_mcp_tool_list }
+        }
+      when 'tools/call'
+        tool_name = params['name'] || ''
+        arguments = params['arguments'] || {}
+
+        tool = @tools[tool_name]
+        unless tool
+          return _mcp_error(req_id, -32602, "Unknown tool: #{tool_name}")
+        end
+
+        begin
+          raw_data = {
+            'function' => tool_name,
+            'argument' => { 'parsed' => [arguments] }
+          }
+          result = tool[:handler].call(arguments, raw_data)
+
+          response_text = ''
+          if result.respond_to?(:to_h)
+            h = result.to_h
+            response_text = h['response'] || ''
+          elsif result.is_a?(Hash)
+            response_text = result['response'] || result.to_s
+          elsif result.is_a?(String)
+            response_text = result
+          end
+
+          {
+            'jsonrpc' => '2.0', 'id' => req_id,
+            'result' => {
+              'content' => [{ 'type' => 'text', 'text' => response_text }],
+              'isError' => false
+            }
+          }
+        rescue => e
+          @logger.error "MCP tool call error: #{tool_name}: #{e.message}"
+          {
+            'jsonrpc' => '2.0', 'id' => req_id,
+            'result' => {
+              'content' => [{ 'type' => 'text', 'text' => "Error: #{e.message}" }],
+              'isError' => true
+            }
+          }
+        end
+      when 'ping'
+        { 'jsonrpc' => '2.0', 'id' => req_id, 'result' => {} }
+      else
+        _mcp_error(req_id, -32601, "Method not found: #{method}")
+      end
+    end
+
+    # @api private
+    def _mcp_error(req_id, code, message)
+      {
+        'jsonrpc' => '2.0',
+        'id'      => req_id,
+        'error'   => { 'code' => code, 'message' => message }
+      }
+    end
+
+    # ==================================================================
+    # Lifecycle
+    # ==================================================================
+
+    # Python parity: ``on_summary(self, summary, raw_data=None)`` is a
+    # virtual hook called when a post-prompt summary is received.
+    # Ruby supports two equivalent shapes:
+    #
+    # 1. **Registration** (Ruby idiom) — pass a block to install a
+    #    callback. The block receives ``(summary, raw_data)`` when a
+    #    summary is delivered. ``on_summary { |sum, raw| ... }``
+    # 2. **Override** (Python idiom) — subclass and override
+    #    ``on_summary(summary, raw_data = nil)``. Default
+    #    implementation calls the registered block (if any) and
+    #    otherwise no-ops.
+    #
+    # @param summary [Hash, nil] the post-prompt summary
+    # @param raw_data [Hash, nil] the complete raw POST data
+    # @yield [summary, raw_data] optional callback registration
+    def on_summary(summary = nil, raw_data = nil, &block)
+      if block
+        @summary_callback = block
+        return self
+      end
+
+      @summary_callback&.call(summary, raw_data)
+      nil
+    end
+
+    def on_debug_event(&block)
+      @debug_event_callback = block
+      self
+    end
+
+    # Universal run method — mirrors Python's
+    # ``WebMixin.run(event=None, context=None, force_mode=None,
+    # host=None, port=None)``.
+    #
+    # Detects execution mode (server / lambda / cgi) and routes
+    # accordingly. ``force_mode`` overrides auto-detection.
+    #
+    # @param event [Object, nil] serverless event
+    # @param context [Object, nil] serverless context
+    # @param force_mode [String, nil] one of ``"server"``, ``"lambda"``,
+    #   ``"cgi"``
+    # @param host [String, nil] override bind host (server mode)
+    # @param port [Integer, nil] override bind port (server mode)
+    def run(event: nil, context: nil, force_mode: nil, host: nil, port: nil)
+      mode = force_mode || _detect_run_mode
+
+      case mode
+      when 'lambda'
+        _run_lambda(event, context)
+      when 'cgi'
+        _run_cgi
+      else
+        serve(host: host, port: port)
+      end
+    end
+
+    # @api private
+    def _detect_run_mode
+      return 'lambda' if ENV['AWS_LAMBDA_FUNCTION_NAME'] && !ENV['AWS_LAMBDA_FUNCTION_NAME'].empty?
+      return 'cgi'    if ENV['GATEWAY_INTERFACE']
+      'server'
+    end
+
+    # @api private
+    def _run_lambda(event, _context)
+      require 'stringio'
+      event ||= {}
+      path = event['path'] || event['rawPath'] || '/'
+      method = event['httpMethod'] || event.dig('requestContext', 'http', 'method') || 'GET'
+      body = event['body'] || ''
+      env = {
+        'PATH_INFO'      => path,
+        'REQUEST_METHOD' => method,
+        'QUERY_STRING'   => '',
+        'rack.input'     => StringIO.new(body),
+        'rack.errors'    => $stderr
+      }
+      status, headers, response_body = rack_app.call(env)
+      body_str = response_body.respond_to?(:join) ? response_body.join : response_body.to_s
+      {
+        'statusCode' => Integer(status),
+        'headers'    => headers,
+        'body'       => body_str
+      }
+    end
+
+    # @api private
+    def _run_cgi
+      require 'stringio'
+      env = {
+        'PATH_INFO'      => ENV['PATH_INFO'] || '/',
+        'REQUEST_METHOD' => ENV['REQUEST_METHOD'] || 'GET',
+        'QUERY_STRING'   => ENV['QUERY_STRING'] || '',
+        'rack.input'     => StringIO.new(''),
+        'rack.errors'    => $stderr
+      }
+      status, headers, body = rack_app.call(env)
+      body_str = body.respond_to?(:join) ? body.join : body.to_s
+      out = +"Status: #{status}\r\n"
+      headers.each { |k, v| out << "#{k}: #{v}\r\n" }
+      out << "\r\n"
+      out << body_str
+      out
+    end
+
+    # Start the HTTP server (blocking).
+    #
+    # Python parity: ``serve(host=None, port=None)``. ``host`` /
+    # ``port`` overrides default to constructor-supplied values.
+    def serve(host: nil, port: nil)
+      require 'webrick'
+      bind_host = host || @host
+      bind_port = port || @port
+      @logger.info "Starting server on #{bind_host}:#{bind_port} ..."
+      user, _pass = @basic_auth
+      @logger.info "Basic-auth credentials — user: #{user}  password: [REDACTED]"
+
+      @server = ::WEBrick::HTTPServer.new(
+        Host: bind_host,
+        Port: bind_port,
+        Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
+        AccessLog: []
+      )
+
+      # Rack 3+ moved Handler to the rackup gem
+      handler = begin
+                  require 'rackup/handler/webrick'
+                  Rackup::Handler::WEBrick
+                rescue LoadError
+                  require 'rack/handler/webrick'
+                  Rack::Handler::WEBrick
+                end
+      @server.mount '/', handler, rack_app
+
+      trap('INT')  { @server.shutdown }
+      trap('TERM') { @server.shutdown }
+
+      @server.start
+    end
+
+    # Return a Rack-compatible application for mounting.
+    def rack_app
+      @rack_app ||= _build_rack_app
+    end
+
+    alias as_rack_app rack_app
+
+    # ==================================================================
+    # SWML Rendering
+    # ==================================================================
+
+    # Build the complete SWML document hash.
+    #
+    # @param request_data [Hash, nil] parsed request body
+    # @param request [Rack::Request, nil] the HTTP request
+    # @return [Hash]
+    def render_swml(request_data = nil, request: nil)
+      agent = self
+
+      # Dynamic config: clone into ephemeral copy
+      if @dynamic_config_callback
+        agent = _create_ephemeral_copy
+        begin
+          query_params = request ? _parse_query_string(request) : {}
+          body_params  = request_data || {}
+          headers      = request ? _extract_headers(request) : {}
+          @dynamic_config_callback.call(query_params, body_params, headers, agent)
+        rescue => e
+          @logger.error "Dynamic config error: #{e.message}"
+        end
+      end
+
+      agent._render_swml_internal
+    end
+
+    # @api private
+    def _render_swml_internal
+      sections_main = []
+
+      # PHASE 1: Pre-answer verbs
+      @pre_answer_verbs.each do |verb_name, config|
+        sections_main << { verb_name => config }
+      end
+
+      # PHASE 2: Answer verb
+      if @auto_answer
+        answer_conf = @answer_config.empty? ? {} : @answer_config
+        sections_main << { 'answer' => answer_conf }
+      end
+
+      # PHASE 3: Post-answer verbs
+      if @record_call
+        sections_main << {
+          'record_call' => {
+            'format' => @record_format,
+            'stereo' => @record_stereo
+          }
+        }
+      end
+      @post_answer_verbs.each do |verb_name, config|
+        sections_main << { verb_name => config }
+      end
+
+      # PHASE 4: AI verb
+      ai_config = _build_ai_config
+      sections_main << { 'ai' => ai_config }
+
+      # PHASE 5: Post-AI verbs
+      @post_ai_verbs.each do |verb_name, config|
+        sections_main << { verb_name => config }
+      end
+
+      {
+        'version'  => '1.0.0',
+        'sections' => {
+          'main' => sections_main
+        }
+      }
+    end
+
+    # Get the configured basic-auth credentials.
+    #
+    # Python parity: ``get_basic_auth_credentials(include_source=False)``.
+    # When ``include_source`` is true, returns a 3-tuple ``[user,
+    # pass, source]`` (``"environment"`` / ``"auto-generated"`` /
+    # ``"provided"``). Otherwise returns ``[user, pass]``.
+    def get_basic_auth_credentials(include_source: false)
+      u, p = @basic_auth
+      return [u, p] unless include_source
+
+      env_user = ENV['SWML_BASIC_AUTH_USER']
+      env_pass = ENV['SWML_BASIC_AUTH_PASSWORD']
+      source =
+        if env_user && !env_user.empty? && env_pass && !env_pass.empty? && u == env_user && p == env_pass
+          'environment'
+        elsif u&.start_with?('user_') && p && p.length > 20
+          'auto-generated'
+        else
+          'provided'
+        end
+      [u, p, source]
+    end
+
+    # ==================================================================
+    # Private helpers
+    # ==================================================================
+
+    private
+
+    # Build the AI verb configuration hash.
+    def _build_ai_config
+      ai = {}
+
+      # --- prompt -------------------------------------------------------
+      prompt = get_prompt
+      if prompt.is_a?(Array) && !prompt.empty?
+        prompt_obj = { 'pom' => prompt }
+        prompt_obj.merge!(@prompt_llm_params) unless @prompt_llm_params.empty?
+        ai['prompt'] = prompt_obj
+      elsif prompt.is_a?(String) && !prompt.empty?
+        prompt_obj = { 'text' => prompt }
+        prompt_obj.merge!(@prompt_llm_params) unless @prompt_llm_params.empty?
+        ai['prompt'] = prompt_obj
+      end
+
+      # --- post-prompt --------------------------------------------------
+      if @post_prompt_text && !@post_prompt_text.empty?
+        pp_obj = { 'text' => @post_prompt_text }
+        pp_obj.merge!(@post_prompt_llm_params) unless @post_prompt_llm_params.empty?
+        ai['post_prompt'] = pp_obj
+
+        # post_prompt_url
+        if @post_prompt_url_override
+          ai['post_prompt_url'] = @post_prompt_url_override
+        else
+          ai['post_prompt_url'] = _build_webhook_url('post_prompt')
+        end
+      end
+
+      # --- SWAIG --------------------------------------------------------
+      swaig = {}
+
+      # default webhook url
+      default_url = @web_hook_url_override || _build_webhook_url('swaig', @swaig_query_params.empty? ? nil : @swaig_query_params)
+      swaig['defaults'] = { 'web_hook_url' => default_url }
+
+      # functions
+      functions = _build_functions_array
+      swaig['functions'] = functions unless functions.empty?
+
+      # native functions
+      swaig['native_functions'] = @native_functions unless @native_functions.empty?
+
+      # includes
+      swaig['includes'] = @function_includes unless @function_includes.empty?
+
+      # internal_fillers
+      swaig['internal_fillers'] = @internal_fillers unless @internal_fillers.empty?
+
+      ai['SWAIG'] = swaig unless swaig.keys == ['defaults']  && functions.empty?
+
+      # --- hints --------------------------------------------------------
+      ai['hints'] = @hints.dup unless @hints.empty?
+
+      # --- languages ----------------------------------------------------
+      ai['languages'] = @languages.dup unless @languages.empty?
+
+      # --- pronunciations -----------------------------------------------
+      ai['pronounce'] = @pronounce.dup unless @pronounce.empty?
+
+      # --- params -------------------------------------------------------
+      merged_params = @params.dup
+      if @debug_events_enabled
+        merged_params['debug_webhook_url']   = _build_webhook_url('debug_events')
+        merged_params['debug_webhook_level'] = @debug_events_level
+      end
+      ai['params'] = merged_params unless merged_params.empty?
+
+      # --- global_data --------------------------------------------------
+      ai['global_data'] = @global_data.dup unless @global_data.empty?
+
+      # --- contexts -----------------------------------------------------
+      if @context_builder
+        begin
+          ai['contexts'] = @context_builder.to_h
+        rescue ArgumentError
+          # invalid context config — skip silently
+        end
+      end
+
+      # --- MCP servers ---------------------------------------------------
+      ai['mcp_servers'] = @mcp_servers.map(&:dup) unless @mcp_servers.empty?
+
+      ai
+    end
+
+    # Build the functions array for the SWAIG section.
+    def _build_functions_array
+      functions = []
+
+      @tools.each do |name, tool|
+        func_entry = tool[:definition].dup
+        # Add per-function webhook URL if it has a token or query params
+        if tool[:secure] || !@swaig_query_params.empty?
+          qp = @swaig_query_params.dup
+          if tool[:secure]
+            # Note: token is generated per-call; in render we can't know call_id yet,
+            # so secure tools get per-function URLs at request time.
+            # For now, the default webhook URL handles dispatch.
+          end
+          func_entry['web_hook_url'] = _build_webhook_url('swaig', qp) unless qp.empty?
+        end
+        functions << func_entry
+      end
+
+      @swaig_functions.each do |_name, func_def|
+        functions << func_def.dup
+      end
+
+      functions
+    end
+
+    # Build a webhook URL with optional query params.
+    def _build_webhook_url(endpoint, query_params = nil)
+      base = _base_url
+      path = @route == '/' ? "/#{endpoint}" : "#{@route}/#{endpoint}"
+
+      url = "#{base}#{path}"
+
+      if query_params && !query_params.empty?
+        qs = URI.encode_www_form(query_params)
+        url = "#{url}?#{qs}"
+      end
+
+      url
+    end
+
+    # Compute the base URL for webhook construction.
+    #
+    # Precedence (matches the Python SDK):
+    #   1. +SWML_PROXY_URL_BASE+ or a call to +manual_set_proxy_url+
+    #      (an explicit override always wins)
+    #   2. AWS Lambda-derived URL when execution mode is +:lambda+
+    #      (either +AWS_LAMBDA_FUNCTION_URL+ or the Function URL built
+    #      from +AWS_LAMBDA_FUNCTION_NAME+ + +AWS_REGION+)
+    #   3. +http://user:pass@host:port+ for local server mode
+    #
+    # This method intentionally returns only the *base* — the agent's
+    # +@route+ is appended by {#_build_webhook_url}. Never bake the
+    # route into the base here, or a non-root agent deployed behind a
+    # proxy will have its mount point silently dropped from webhook
+    # URLs.
+    def _base_url
+      return @proxy_url_base.chomp('/') if @proxy_url_base && !@proxy_url_base.empty?
+
+      if Runtime.lambda?
+        lambda_base = Runtime.lambda_base_url
+        if lambda_base
+          user, pass = @basic_auth
+          return _embed_auth(lambda_base, user, pass)
+        end
+      end
+
+      user, pass = @basic_auth
+      "http://#{user}:#{pass}@#{@host}:#{@port}"
+    end
+
+    # Embed basic-auth credentials into +base+ immediately after the
+    # scheme. Returns +base+ untouched when either credential is blank
+    # or the URL already contains an @-delimited userinfo component.
+    def _embed_auth(base, user, pass)
+      return base if user.nil? || user.empty? || pass.nil? || pass.empty?
+
+      uri = URI.parse(base)
+      return base if uri.userinfo && !uri.userinfo.empty?
+
+      uri.userinfo = "#{URI.encode_www_form_component(user)}:#{URI.encode_www_form_component(pass)}"
+      uri.to_s
+    rescue URI::InvalidURIError
+      base
+    end
+
+    # Normalise tool parameters into JSON-Schema form.
+    def _normalise_parameters(params)
+      return params if params.is_a?(Hash) && params['type'] == 'object'
+      return { 'type' => 'object', 'properties' => {} } if params.nil? || params.empty?
+
+      # If the hash looks like {name => {type, description}}, wrap it.
+      if params.is_a?(Hash) && !params.key?('type')
+        { 'type' => 'object', 'properties' => params.transform_keys(&:to_s) }
+      else
+        params
+      end
+    end
+
+    # Create an ephemeral deep copy for dynamic config.
+    def _create_ephemeral_copy
+      copy = dup
+      # Deep-copy mutable collections
+      copy.instance_variable_set(:@pom_sections,         @pom_sections.map(&:dup))
+      copy.instance_variable_set(:@tools,                @tools.transform_values(&:dup))
+      copy.instance_variable_set(:@swaig_functions,      @swaig_functions.transform_values(&:dup))
+      copy.instance_variable_set(:@hints,                @hints.dup)
+      copy.instance_variable_set(:@languages,            @languages.map { |l| l.dup })
+      copy.instance_variable_set(:@pronounce,            @pronounce.map { |p| p.dup })
+      copy.instance_variable_set(:@params,               @params.dup)
+      copy.instance_variable_set(:@global_data,          @global_data.dup)
+      copy.instance_variable_set(:@native_functions,     @native_functions.dup)
+      copy.instance_variable_set(:@function_includes,    @function_includes.map { |i| i.dup })
+      copy.instance_variable_set(:@internal_fillers,     _deep_dup_hash(@internal_fillers))
+      copy.instance_variable_set(:@prompt_llm_params,    @prompt_llm_params.dup)
+      copy.instance_variable_set(:@post_prompt_llm_params, @post_prompt_llm_params.dup)
+      copy.instance_variable_set(:@pre_answer_verbs,     @pre_answer_verbs.map(&:dup))
+      copy.instance_variable_set(:@post_answer_verbs,    @post_answer_verbs.map(&:dup))
+      copy.instance_variable_set(:@post_ai_verbs,        @post_ai_verbs.map(&:dup))
+      copy.instance_variable_set(:@answer_config,        @answer_config.dup)
+      copy.instance_variable_set(:@swaig_query_params,   @swaig_query_params.dup)
+      copy.instance_variable_set(:@loaded_skills,        @loaded_skills.dup)
+      copy.instance_variable_set(:@mcp_servers,          @mcp_servers.map(&:dup))
+      copy.instance_variable_set(:@mcp_server_enabled,   @mcp_server_enabled)
+      # Don't copy the dynamic config callback to prevent infinite recursion
+      copy.instance_variable_set(:@dynamic_config_callback, nil)
+      copy
+    end
+
+    # Deep-dup a hash of hashes
+    def _deep_dup_hash(hash)
+      hash.each_with_object({}) do |(k, v), result|
+        result[k] = v.is_a?(Hash) ? v.dup : v
+      end
+    end
+
+    # Parse query string from Rack request
+    def _parse_query_string(request)
+      return {} unless request.respond_to?(:env)
+
+      qs = request.env['QUERY_STRING'] || ''
+      URI.decode_www_form(qs).to_h
+    rescue
+      {}
+    end
+
+    # Extract headers from Rack request
+    def _extract_headers(request)
+      return {} unless request.respond_to?(:env)
+
+      request.env.select { |k, _| k.start_with?('HTTP_') }
+             .transform_keys { |k| k.sub('HTTP_', '').downcase.tr('_', '-') }
+    rescue
+      {}
+    end
+
+    # ==================================================================
+    # Rack app
+    # ==================================================================
+
+    def _build_rack_app
+      agent = self
+      main_route = @route
+      signing_key = @signing_key
+      trust_proxy = @trust_proxy_for_signature
+
+      Rack::Builder.new do
+        # --- public endpoints (no auth) --------------------------------
+        map '/health' do
+          run ->(_env) {
+            body = JSON.generate({ status: 'healthy' })
+            [200, { 'content-type' => 'application/json' }, [body]]
+          }
+        end
+
+        map '/ready' do
+          run ->(_env) {
+            body = JSON.generate({ status: 'ready' })
+            [200, { 'content-type' => 'application/json' }, [body]]
+          }
+        end
+
+        # --- authenticated endpoints -----------------------------------
+        map main_route do
+          use AgentSecurityHeadersMiddleware
+          use AgentBodyLimitMiddleware, AgentBase::MAX_BODY_SIZE
+          # Webhook signature validation runs BEFORE basic auth so a
+          # spoofed but unsigned request is rejected with 403 (the spec)
+          # rather than 401 (which would expose that the key is missing).
+          # Only POSTs to the signed routes go through.
+          if signing_key && !signing_key.empty?
+            use SignalWire::Security::WebhookMiddleware,
+                signing_key: signing_key,
+                trust_proxy: trust_proxy,
+                paths: ['/', '/swaig', '/post_prompt'],
+                methods: ['POST']
+          end
+          use AgentTimingSafeBasicAuth, agent
+
+          run ->(env) {
+            request  = Rack::Request.new(env)
+            sub_path = env['PATH_INFO'] || '/'
+            sub_path = '/' if sub_path.empty?
+
+            request_data = nil
+            if request.post? || request.put?
+              # Prefer the raw body stashed by WebhookMiddleware (which
+              # already read+rewound the stream). Fall back to reading the
+              # rack input directly when no validator was mounted.
+              body = env['signalwire.raw_body']
+              if body.nil?
+                body = request.body.read
+                request.body.rewind if request.body.respond_to?(:rewind)
+              end
+              request_data = JSON.parse(body) rescue nil
+            end
+
+            # /swaig — handled by Service (lifted from AgentBase). The dispatch
+            # uses on_function_call which AgentBase overrides for token validation.
+            if sub_path == '/swaig'
+              next agent.send(:_handle_swaig_endpoint, request, request_data, env)
+            end
+
+            # AgentBase's extra routes (/post_prompt, /debug_events, /mcp).
+            extra = agent.handle_additional_route(sub_path, request_data, env)
+            next extra if extra
+
+            # SWML endpoint
+            swml = agent.render_swml(request_data, request: request)
+            body = JSON.generate(swml)
+            [200, { 'content-type' => 'application/json' }, [body]]
+          }
+        end
+      end
+    end
+
+    # Override Service's hook to add agent-specific routes.
+    public
+
+    def handle_additional_route(sub_path, request_data, env)
+      case sub_path
+      when '/post_prompt'  then _handle_post_prompt(request_data, env)
+      when '/debug_events' then _handle_debug_events(request_data, env)
+      when '/mcp'          then _handle_mcp_endpoint(request_data, env)
+      end
+    end
+
+    private
+
+    # These methods must be accessible from the Rack lambda
+    public
+
+    # _handle_swaig is now provided by Service (lifted as _handle_swaig_endpoint).
+    # AgentBase still hooks the dispatch path via the on_function_call override
+    # below, which adds session-token validation on top of Service's plain
+    # registry lookup.
+
+    # Handle post_prompt callback.
+    # @api private
+    def _handle_post_prompt(request_data, _env)
+      if @summary_callback && request_data
+        begin
+          post_prompt_data = request_data['post_prompt_data']
+          summary = nil
+          if post_prompt_data.is_a?(Hash)
+            summary = post_prompt_data['parsed'] || post_prompt_data['raw']
+          end
+          @summary_callback.call(summary, request_data)
+        rescue => e
+          @logger.error "Post-prompt callback error: #{e.message}"
+        end
+      end
+
+      body = JSON.generate({ 'status' => 'ok' })
+      [200, { 'content-type' => 'application/json' }, [body]]
+    end
+
+    # Handle debug events.
+    # @api private
+    def _handle_debug_events(request_data, _env)
+      if @debug_event_callback && request_data
+        begin
+          event_type = request_data['event_type'] || 'unknown'
+          @debug_event_callback.call(event_type, request_data)
+        rescue => e
+          @logger.error "Debug event callback error: #{e.message}"
+        end
+      end
+
+      body = JSON.generate({ 'status' => 'ok' })
+      [200, { 'content-type' => 'application/json' }, [body]]
+    end
+
+    # Handle MCP JSON-RPC 2.0 endpoint.
+    # @api private
+    def _handle_mcp_endpoint(request_data, _env)
+      unless @mcp_server_enabled
+        body = JSON.generate({ 'error' => 'MCP server not enabled' })
+        return [404, { 'content-type' => 'application/json' }, [body]]
+      end
+
+      unless request_data
+        body = JSON.generate(_mcp_error(nil, -32700, 'Parse error'))
+        return [400, { 'content-type' => 'application/json' }, [body]]
+      end
+
+      resp = _handle_mcp_request(request_data)
+      body = JSON.generate(resp)
+      [200, { 'content-type' => 'application/json' }, [body]]
+    end
+
+    private
+
+    # ==================================================================
+    # Rack Middleware
+    # ==================================================================
+
+    class AgentSecurityHeadersMiddleware
+      HEADERS = {
+        'x-content-type-options' => 'nosniff',
+        'x-frame-options'        => 'DENY',
+        'cache-control'          => 'no-store, no-cache, must-revalidate'
+      }.freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        HEADERS.each { |k, v| headers[k] = v }
+        [status, headers, body]
+      end
+    end
+
+    class AgentBodyLimitMiddleware
+      def initialize(app, max_size)
+        @app      = app
+        @max_size = max_size
+      end
+
+      def call(env)
+        if env['CONTENT_LENGTH'] && env['CONTENT_LENGTH'].to_i > @max_size
+          body = JSON.generate({ 'error' => 'Request body too large' })
+          return [413, { 'content-type' => 'application/json' }, [body]]
+        end
+        @app.call(env)
+      end
+    end
+
+    class AgentTimingSafeBasicAuth
+      def initialize(app, agent)
+        @app   = app
+        @agent = agent
+      end
+
+      def call(env)
+        auth = Rack::Auth::Basic::Request.new(env)
+        unless auth.provided? && auth.basic?
+          return _unauthorized
+        end
+
+        user, pass = @agent.get_basic_auth_credentials
+        input_user, input_pass = auth.credentials
+
+        user_ok = Rack::Utils.secure_compare(user.to_s, input_user.to_s)
+        pass_ok = Rack::Utils.secure_compare(pass.to_s, input_pass.to_s)
+
+        if user_ok && pass_ok
+          @app.call(env)
+        else
+          _unauthorized
+        end
+      end
+
+      private
+
+      def _unauthorized
+        [
+          401,
+          {
+            'content-type'     => 'text/plain',
+            'www-authenticate' => 'Basic realm="SignalWire Agent"'
+          },
+          ['Unauthorized']
+        ]
+      end
+    end
+  end
+end