signalwire-sdk 2.0.0

data/bin/swaig-test

@@ -0,0 +1,872 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+#
+# swaig-test — CLI tool for testing SWAIG agent endpoints.
+#
+# Two modes:
+#
+#   (1) URL mode — hit a live agent over HTTP:
+#
+#       swaig-test --url http://user:pass@host:port/route --dump-swml
+#       swaig-test --url http://user:pass@host:port/route --list-tools
+#       swaig-test --url http://user:pass@host:port/route --exec tool_name --param key=value
+#
+#   (2) File mode with serverless simulation — load an agent source file
+#       and route invocations through the platform adapter (no HTTP server):
+#
+#       swaig-test agent.rb --simulate-serverless lambda
+#       swaig-test agent.rb --simulate-serverless lambda --dump-swml
+#       swaig-test agent.rb --simulate-serverless lambda --exec tool_name --param key=value
+#
+#   Only platforms the SDK has actually implemented are accepted. Today
+#   that's `lambda` only; `gcf`, `cgi`, and `azure` are rejected with a
+#   pointer to the phase-9 gap.
+#
+#   (3) In-process file mode — `--file PATH --list-tools` loads the script
+#       in the current Ruby process, finds the user's SWML::Service subclass
+#       (including non-AgentBase services), and reads the runtime tool
+#       registry directly. NO HTTP, NO simulator. This is the only mode
+#       that surfaces SWAIG tools registered on a plain SWML::Service
+#       (e.g. ai_sidecar hosts, standalone SWAIG services):
+#
+#       swaig-test --file examples/swmlservice_swaig_standalone.rb --list-tools
+#
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'optparse'
+require 'base64'
+
+module SwaigTest
+  # Platforms the port has a Phase-9 handler adapter for. Anything else
+  # must be rejected with a clear error so users don't accidentally exercise
+  # the fall-through HTTP path and think the simulator worked.
+  IMPLEMENTED_SERVERLESS_PLATFORMS = %w[lambda].freeze
+
+  # All platforms the porting guide recognises, so the CLI can emit a
+  # helpful "recognised but not implemented" error rather than
+  # "unrecognised value" for the in-progress ones.
+  RECOGNISED_SERVERLESS_PLATFORMS = %w[lambda cgi gcf google_cloud_function azure azure_function].freeze
+
+  # Environment variables the simulator touches. Captured so the simulator
+  # can snapshot and restore them no matter what path the invocation took.
+  LAMBDA_SIMULATION_ENV_VARS = %w[
+    AWS_LAMBDA_FUNCTION_NAME
+    AWS_LAMBDA_FUNCTION_URL
+    AWS_REGION
+    LAMBDA_TASK_ROOT
+    _HANDLER
+    SWML_PROXY_URL_BASE
+  ].freeze
+
+  # Snapshot + restore the env vars a serverless simulation touches, so
+  # tests in the same process (and users who invoke the CLI repeatedly in
+  # a shell session) never inherit leaked state.
+  module RuntimeEnvIsolation
+    def self.snapshot(keys = LAMBDA_SIMULATION_ENV_VARS)
+      keys.each_with_object({}) { |k, h| h[k] = ENV[k] }
+    end
+
+    def self.restore(snapshot)
+      snapshot.each do |k, v|
+        if v.nil?
+          ENV.delete(k)
+        else
+          ENV[k] = v
+        end
+      end
+    end
+  end
+
+  # Serverless platform simulator. Responsible for:
+  #   * setting the mode-detection env vars for the target platform,
+  #   * clearing conflicting env vars (notably SWML_PROXY_URL_BASE),
+  #   * restoring the original environment on deactivate.
+  #
+  # Mirrors signalwire/cli/simulation/mock_env.py's ServerlessSimulator.
+  class ServerlessSimulator
+    LAMBDA_PRESETS = {
+      'AWS_LAMBDA_FUNCTION_NAME' => 'test-agent-function',
+      'LAMBDA_TASK_ROOT'         => '/var/task',
+      'AWS_REGION'               => 'us-east-1',
+      '_HANDLER'                 => 'lambda_function.handler'
+    }.freeze
+
+    attr_reader :platform, :overrides
+
+    def initialize(platform, overrides: {}, verbose: false, io: $stderr)
+      @platform  = platform
+      @overrides = overrides || {}
+      @verbose   = verbose
+      @io        = io
+      @snapshot  = nil
+      @active    = false
+    end
+
+    def activate
+      return if @active
+
+      @snapshot = RuntimeEnvIsolation.snapshot
+
+      # Clear conflicting env vars BEFORE applying presets so that a
+      # SWML_PROXY_URL_BASE set in the outer shell can't override the
+      # platform-derived base URL during the simulation.
+      ENV.delete('SWML_PROXY_URL_BASE')
+
+      preset_for_platform.each { |k, v| ENV[k] = v }
+      @overrides.each { |k, v| ENV[k] = v }
+
+      # Match Python: warn if SWML_PROXY_URL_BASE somehow survived (e.g.
+      # an override re-set it). A live warning here is far cheaper than
+      # silently generating the wrong webhook URLs.
+      if ENV['SWML_PROXY_URL_BASE'] && !ENV['SWML_PROXY_URL_BASE'].empty?
+        @io.puts "WARNING: SWML_PROXY_URL_BASE still set after simulation clear: #{ENV['SWML_PROXY_URL_BASE'].inspect}"
+      end
+
+      @active = true
+
+      return unless @verbose
+
+      @io.puts "Activated #{@platform} environment simulation"
+      preset_for_platform.each_key do |k|
+        @io.puts "  #{k}: #{ENV[k]}"
+      end
+    end
+
+    def deactivate
+      return unless @active
+      RuntimeEnvIsolation.restore(@snapshot) if @snapshot
+      @snapshot = nil
+      @active   = false
+      @io.puts "Deactivated #{@platform} environment simulation" if @verbose
+    end
+
+    # Scope helper so callers can wrap a block in activate/deactivate
+    # without hand-rolling begin/ensure.
+    def with_simulation
+      activate
+      yield self
+    ensure
+      deactivate
+    end
+
+    private
+
+    def preset_for_platform
+      case @platform
+      when 'lambda' then LAMBDA_PRESETS
+      else {}  # unreachable — validated in CLI
+      end
+    end
+  end
+
+  # Dispatches synthetic Lambda Function URL events into a
+  # SignalWire::Serverless::LambdaHandler. Used by --simulate-serverless
+  # lambda to exercise the adapter instead of the HTTP server.
+  class LambdaAdapterDispatcher
+    def initialize(agent)
+      @agent   = agent
+      @handler = SignalWire::Serverless::LambdaHandler.for(agent)
+    end
+
+    # GET the agent's root route and return the response body as a
+    # parsed hash (the SWML document). Raises RuntimeError on non-2xx.
+    def dump_swml
+      route   = @agent.route == '/' ? '/' : @agent.route
+      event   = build_event('GET', route)
+      resp    = @handler.call(event, nil)
+      ensure_success!(resp, "dump-swml GET #{route}")
+      decode_body(resp)
+    end
+
+    # POST to <route>/swaig with a SWAIG invocation. Returns the
+    # response body parsed as a hash.
+    def exec_tool(func_name, params)
+      route = @agent.route == '/' ? '' : @agent.route
+      path  = "#{route}/swaig"
+      body  = JSON.generate(
+        'function' => func_name,
+        'argument' => { 'parsed' => [params || {}] }
+      )
+      auth  = basic_auth_header
+      headers = { 'content-type' => 'application/json' }
+      headers['authorization'] = auth if auth
+
+      event = build_event('POST', path, body: body, headers: headers)
+      resp  = @handler.call(event, nil)
+      ensure_success!(resp, "exec POST #{path}")
+      decode_body(resp)
+    end
+
+    private
+
+    def build_event(method, path, body: nil, headers: nil)
+      base_headers = {
+        'host' => ENV['AWS_LAMBDA_FUNCTION_URL']&.then { |u| URI.parse(u).host } ||
+                  "#{ENV['AWS_LAMBDA_FUNCTION_NAME']}.lambda-url.#{ENV['AWS_REGION']}.on.aws"
+      }
+      base_headers.merge!(headers) if headers
+
+      # Ensure auth is present for authenticated endpoints (SWML, swaig).
+      unless base_headers.key?('authorization') || path == '/health' || path == '/ready'
+        auth = basic_auth_header
+        base_headers['authorization'] = auth if auth
+      end
+
+      event = {
+        'version'        => '2.0',
+        'routeKey'       => '$default',
+        'rawPath'        => path,
+        'rawQueryString' => '',
+        'headers'        => base_headers,
+        'requestContext' => {
+          'http'  => { 'method' => method, 'path' => path, 'protocol' => 'HTTP/1.1' },
+          'stage' => '$default'
+        }
+      }
+      if body
+        event['body']            = body
+        event['isBase64Encoded'] = false
+      end
+      event
+    end
+
+    def basic_auth_header
+      # The agent auto-generates a random password at construction time;
+      # read it back via the public accessor so we can authenticate
+      # ourselves against it.
+      if @agent.respond_to?(:get_basic_auth_credentials)
+        user, pass = @agent.get_basic_auth_credentials
+        return "Basic " + ["#{user}:#{pass}"].pack('m0').chomp if user && pass
+      end
+      nil
+    end
+
+    def ensure_success!(resp, description)
+      status = resp['statusCode'].to_i
+      return if status >= 200 && status < 300
+      raise "Simulator: #{description} returned HTTP #{status}: #{resp['body']}"
+    end
+
+    def decode_body(resp)
+      body = resp['body'].to_s
+      body = Base64.decode64(body) if resp['isBase64Encoded']
+      JSON.parse(body)
+    end
+  end
+
+  class CLI
+    attr_reader :options
+
+    def initialize(argv = ARGV)
+      @options = {
+        url:                 nil,
+        agent_file:          nil,
+        file:                nil,
+        simulate_serverless: nil,
+        dump_swml:           false,
+        list_tools:          false,
+        exec:                nil,
+        params:              {},
+        raw:                 false,
+        verbose:             false
+      }
+      parse_options(argv)
+    end
+
+    def run
+      validate_options!
+
+      if @options[:file]
+        run_in_process_file_mode
+      elsif @options[:simulate_serverless]
+        run_simulated_serverless
+      elsif @options[:dump_swml]
+        dump_swml
+      elsif @options[:list_tools]
+        list_tools
+      elsif @options[:exec]
+        exec_function
+      else
+        $stderr.puts "Error: specify --dump-swml, --list-tools, or --exec NAME"
+        exit 1
+      end
+    end
+
+    private
+
+    def parse_options(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: swaig-test [agent_file] [options]"
+
+        opts.on("--url URL", "Agent URL with embedded auth (http://user:pass@host:port/route)") do |v|
+          @options[:url] = v
+        end
+
+        opts.on("--simulate-serverless PLATFORM",
+                "Simulate the named serverless platform (loads agent file locally). Supported: #{IMPLEMENTED_SERVERLESS_PLATFORMS.join(', ')}") do |v|
+          @options[:simulate_serverless] = v
+        end
+
+        opts.on("--file PATH", "--example PATH",
+                "Load a SWML::Service subclass from PATH in-process and read its tool registry directly (no HTTP, no simulator). Required for --list-tools on a non-AgentBase Service.") do |v|
+          @options[:file] = v
+        end
+
+        opts.on("--dump-swml", "GET SWML document and pretty-print it") do
+          @options[:dump_swml] = true
+        end
+
+        opts.on("--list-tools", "List available SWAIG functions") do
+          @options[:list_tools] = true
+        end
+
+        opts.on("--exec NAME", "Execute a SWAIG function by name") do |v|
+          @options[:exec] = v
+        end
+
+        opts.on("--param KEY=VALUE", "Set a parameter (repeatable)") do |v|
+          key, value = v.split('=', 2)
+          if key && value
+            @options[:params][key] = parse_param_value(value)
+          else
+            $stderr.puts "Warning: ignoring malformed --param '#{v}' (expected key=value)"
+          end
+        end
+
+        opts.on("--raw", "Output compact JSON instead of pretty-printed") do
+          @options[:raw] = true
+        end
+
+        opts.on("--verbose", "Show request/response details") do
+          @options[:verbose] = true
+        end
+
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          exit 0
+        end
+      end
+
+      remaining = parser.parse(argv)
+
+      # Any leftover positional argument is treated as an agent source
+      # file path. This is the only way to invoke file mode, so we keep
+      # it outside of validate_options! for clearer error messages.
+      if remaining.length > 1
+        $stderr.puts "Error: at most one positional agent file may be given; got #{remaining.inspect}"
+        exit 1
+      elsif remaining.length == 1
+        @options[:agent_file] = remaining.first
+      end
+    end
+
+    def validate_options!
+      if @options[:file]
+        validate_file_mode_options!
+        return
+      end
+
+      if @options[:simulate_serverless]
+        validate_simulate_serverless_options!
+        return
+      end
+
+      # Classic URL mode from here down.
+      unless @options[:url]
+        $stderr.puts "Error: --url is required (or pass --file PATH for in-process file mode, or pass an agent file with --simulate-serverless PLATFORM)"
+        exit 1
+      end
+
+      actions = [@options[:dump_swml], @options[:list_tools], !!@options[:exec]].count(true)
+      if actions == 0
+        $stderr.puts "Error: specify one of --dump-swml, --list-tools, or --exec NAME"
+        exit 1
+      elsif actions > 1
+        $stderr.puts "Error: specify only one of --dump-swml, --list-tools, or --exec NAME"
+        exit 1
+      end
+    end
+
+    def validate_file_mode_options!
+      # In-process file mode is currently scoped to listing tools off the
+      # runtime registry, since that is the gap on non-AgentBase services.
+      # URL/simulator combinations are rejected to avoid ambiguous dispatch.
+      if @options[:url]
+        $stderr.puts "Error: --file and --url are mutually exclusive"
+        exit 1
+      end
+
+      if @options[:simulate_serverless]
+        $stderr.puts "Error: --file and --simulate-serverless are mutually exclusive"
+        exit 1
+      end
+
+      unless File.exist?(@options[:file])
+        $stderr.puts "Error: file not found: #{@options[:file]}"
+        exit 1
+      end
+
+      unless @options[:list_tools]
+        $stderr.puts "Error: --file mode currently supports only --list-tools"
+        exit 1
+      end
+
+      if @options[:dump_swml] || @options[:exec]
+        $stderr.puts "Error: --file mode does not support --dump-swml or --exec (use --url or --simulate-serverless lambda for those)"
+        exit 1
+      end
+    end
+
+    def validate_simulate_serverless_options!
+      platform = @options[:simulate_serverless]
+
+      unless IMPLEMENTED_SERVERLESS_PLATFORMS.include?(platform)
+        if RECOGNISED_SERVERLESS_PLATFORMS.include?(platform)
+          $stderr.puts "Error: --simulate-serverless #{platform.inspect} is not implemented in this SDK yet."
+          $stderr.puts "       Phase 9 (serverless support) has only shipped for: #{IMPLEMENTED_SERVERLESS_PLATFORMS.join(', ')}."
+          $stderr.puts "       Add the #{platform} handler adapter before enabling it here."
+        else
+          $stderr.puts "Error: unknown serverless platform #{platform.inspect}."
+          $stderr.puts "       Supported: #{IMPLEMENTED_SERVERLESS_PLATFORMS.join(', ')}."
+        end
+        exit 1
+      end
+
+      unless @options[:agent_file]
+        $stderr.puts "Error: --simulate-serverless requires a positional agent file argument"
+        $stderr.puts "Usage: swaig-test AGENT_FILE --simulate-serverless #{platform} [--dump-swml | --exec NAME]"
+        exit 1
+      end
+
+      unless File.exist?(@options[:agent_file])
+        $stderr.puts "Error: agent file not found: #{@options[:agent_file]}"
+        exit 1
+      end
+
+      # Simulated mode cannot combine with --url (different dispatch paths).
+      if @options[:url]
+        $stderr.puts "Error: --simulate-serverless and --url are mutually exclusive"
+        exit 1
+      end
+
+      actions = [@options[:dump_swml], @options[:list_tools], !!@options[:exec]].count(true)
+      if actions > 1
+        $stderr.puts "Error: specify at most one of --dump-swml, --list-tools, or --exec NAME"
+        exit 1
+      end
+    end
+
+    def parse_param_value(value)
+      case value
+      when 'true'  then true
+      when 'false' then false
+      when 'null', 'nil' then nil
+      when /\A-?\d+\z/ then value.to_i
+      when /\A-?\d+\.\d+\z/ then value.to_f
+      else value
+      end
+    end
+
+    def parsed_uri
+      @parsed_uri ||= URI.parse(@options[:url])
+    end
+
+    def base_path
+      path = parsed_uri.path
+      path = '/' if path.nil? || path.empty?
+      path.chomp('/')
+    end
+
+    def auth_header
+      user = parsed_uri.user
+      pass = parsed_uri.password
+      if user && pass
+        "Basic " + ["#{URI.decode_www_form_component(user)}:#{URI.decode_www_form_component(pass)}"].pack('m0')
+      else
+        nil
+      end
+    end
+
+    def make_request(method, path, body: nil)
+      full_path = base_path == '/' ? path : "#{base_path}#{path}"
+      full_path = '/' if full_path.empty?
+
+      uri = parsed_uri.dup
+      uri.path = full_path
+      uri.user = nil
+      uri.password = nil
+
+      if @options[:verbose]
+        $stderr.puts ">> #{method.upcase} #{uri}"
+        $stderr.puts ">> Authorization: Basic <redacted>" if auth_header
+        if body
+          $stderr.puts ">> Content-Type: application/json"
+          $stderr.puts ">> Body: #{body}"
+        end
+        $stderr.puts ""
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      if method == :get
+        req = Net::HTTP::Get.new(uri.request_uri)
+      else
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req.body = body
+        req['Content-Type'] = 'application/json'
+      end
+
+      req['Authorization'] = auth_header if auth_header
+
+      response = http.request(req)
+
+      if @options[:verbose]
+        $stderr.puts "<< HTTP #{response.code} #{response.message}"
+        response.each_header { |k, v| $stderr.puts "<< #{k}: #{v}" }
+        $stderr.puts ""
+      end
+
+      response
+    end
+
+    def format_json(data)
+      if @options[:raw]
+        JSON.generate(data)
+      else
+        JSON.pretty_generate(data)
+      end
+    end
+
+    def dump_swml
+      response = make_request(:get, '/')
+
+      unless response.is_a?(Net::HTTPSuccess)
+        $stderr.puts "Error: HTTP #{response.code} #{response.message}"
+        $stderr.puts response.body if @options[:verbose]
+        exit 1
+      end
+
+      data = JSON.parse(response.body)
+      puts format_json(data)
+    rescue JSON::ParserError => e
+      $stderr.puts "Error: invalid JSON response: #{e.message}"
+      $stderr.puts response.body if @options[:verbose]
+      exit 1
+    end
+
+    def list_tools
+      response = make_request(:get, '/')
+
+      unless response.is_a?(Net::HTTPSuccess)
+        $stderr.puts "Error: HTTP #{response.code} #{response.message}"
+        exit 1
+      end
+
+      swml = JSON.parse(response.body)
+      functions = extract_functions(swml)
+
+      if functions.empty?
+        puts "No SWAIG functions found."
+        return
+      end
+
+      puts "SWAIG Functions:"
+      puts "-" * 60
+      functions.each do |func|
+        name = func['function'] || '(unnamed)'
+        desc = func['description'] || '(no description)'
+        puts "  #{name}"
+        puts "    #{desc}"
+
+        params = func['parameters']
+        if params.is_a?(Hash) && params['properties'].is_a?(Hash) && !params['properties'].empty?
+          puts "    Parameters:"
+          params['properties'].each do |pname, pdef|
+            ptype = pdef['type'] || 'any' rescue 'any'
+            pdesc = pdef['description'] || '' rescue ''
+            required = (params['required'] || []).include?(pname) ? ' (required)' : ''
+            puts "      - #{pname}: #{ptype}#{required} #{pdesc}"
+          end
+        end
+        puts ""
+      end
+    rescue JSON::ParserError => e
+      $stderr.puts "Error: invalid JSON response: #{e.message}"
+      exit 1
+    end
+
+    def exec_function
+      func_name = @options[:exec]
+      payload = {
+        'function' => func_name,
+        'argument' => {
+          'parsed' => [@options[:params]]
+        }
+      }
+
+      response = make_request(:post, '/swaig', body: JSON.generate(payload))
+
+      unless response.is_a?(Net::HTTPSuccess)
+        $stderr.puts "Error: HTTP #{response.code} #{response.message}"
+        $stderr.puts response.body if @options[:verbose]
+        exit 1
+      end
+
+      data = JSON.parse(response.body)
+      puts format_json(data)
+    rescue JSON::ParserError => e
+      $stderr.puts "Error: invalid JSON response: #{e.message}"
+      exit 1
+    end
+
+    def extract_functions(swml)
+      functions = []
+
+      # Navigate the SWML structure to find AI → SWAIG → functions
+      sections = swml['sections'] || {}
+      main = sections['main'] || []
+
+      main.each do |verb|
+        if verb.is_a?(Hash) && verb.key?('ai')
+          ai = verb['ai']
+          swaig = ai['SWAIG'] || {}
+          funcs = swaig['functions'] || []
+          functions.concat(funcs)
+        end
+      end
+
+      functions
+    end
+
+    # --------------------------------------------------------------
+    # --simulate-serverless ... dispatch
+    # --------------------------------------------------------------
+
+    def run_simulated_serverless
+      require 'signalwire'
+
+      simulator = ServerlessSimulator.new(
+        @options[:simulate_serverless],
+        verbose: @options[:verbose]
+      )
+
+      simulator.with_simulation do
+        agent = load_agent_file(@options[:agent_file])
+        unless agent
+          $stderr.puts "Error: agent file #{@options[:agent_file].inspect} did not expose an AGENT constant (expected SignalWire::AgentBase)."
+          exit 1
+        end
+
+        dispatcher = LambdaAdapterDispatcher.new(agent)
+
+        if @options[:dump_swml]
+          puts format_json(dispatcher.dump_swml)
+        elsif @options[:exec]
+          puts format_json(dispatcher.exec_tool(@options[:exec], @options[:params]))
+        elsif @options[:list_tools]
+          swml = dispatcher.dump_swml
+          render_functions_list(extract_functions(swml))
+        else
+          # No sub-action: render the SWML and print it (matches the porting-guide
+          # "render SWML and exit" default).
+          puts format_json(dispatcher.dump_swml)
+        end
+      end
+    end
+
+    def load_agent_file(path)
+      # Use load rather than require so repeated CLI invocations in the
+      # same process (tests) don't silently no-op.
+      absolute = File.expand_path(path)
+      load(absolute)
+
+      # Preferred convention: the agent file defines a top-level
+      # constant named AGENT. Fall back to any SignalWire::AgentBase
+      # instance at top-level for forgiveness.
+      if Object.const_defined?(:AGENT)
+        candidate = Object.const_get(:AGENT)
+        return candidate if candidate.is_a?(SignalWire::AgentBase)
+      end
+
+      Object.constants.each do |c|
+        next if c == :AGENT
+        value = Object.const_get(c)
+        return value if value.is_a?(SignalWire::AgentBase)
+      end
+
+      nil
+    end
+
+    def render_functions_list(functions)
+      if functions.empty?
+        puts "No SWAIG functions found."
+        return
+      end
+      puts "SWAIG Functions:"
+      puts "-" * 60
+      functions.each do |func|
+        name = func['function'] || '(unnamed)'
+        desc = func['description'] || '(no description)'
+        puts "  #{name}"
+        puts "    #{desc}"
+
+        properties, required = extract_param_properties(func['parameters'])
+        unless properties.empty?
+          puts "    Parameters:"
+          properties.each do |pname, pdef|
+            ptype = (pdef.is_a?(Hash) ? pdef['type'] : nil) || 'any'
+            pdesc = (pdef.is_a?(Hash) ? pdef['description'] : nil) || ''
+            req_marker = required.include?(pname.to_s) ? ' (required)' : ''
+            puts "      - #{pname}: #{ptype}#{req_marker} #{pdesc}".rstrip
+          end
+        end
+        puts ""
+      end
+    end
+
+    # Accepts either JSON-Schema-shaped `{type:object, properties:{...}}` or
+    # the raw flat shape SWML::Service stores (`{name => {type, description}}`).
+    # Returns [properties_hash, required_array].
+    def extract_param_properties(params)
+      return [{}, []] unless params.is_a?(Hash)
+      if params['properties'].is_a?(Hash)
+        [params['properties'], Array(params['required']).map(&:to_s)]
+      elsif params['type'] == 'object'
+        [{}, []]
+      else
+        # Flat shape — keys are parameter names, values are schema fragments.
+        [params.transform_keys(&:to_s), []]
+      end
+    end
+
+    # --------------------------------------------------------------
+    # --file ... --list-tools dispatch (in-process, no HTTP)
+    # --------------------------------------------------------------
+    #
+    # Loads PATH with Kernel#load (so re-loads in the same process work
+    # cleanly), discovers a `SignalWire::SWML::Service` subclass, instantiates
+    # it (or reuses a top-level instance the script already exposed), and
+    # reads the runtime tool registry directly. This is the only path that
+    # surfaces SWAIG tools registered on a non-AgentBase Service, since URL
+    # mode looks for them in rendered SWML and they aren't there for plain
+    # Service subclasses (`render_main_swml` returns the document only).
+    def run_in_process_file_mode
+      require 'signalwire'
+
+      service = load_service_from_file(@options[:file])
+      unless service
+        $stderr.puts "Error: file #{@options[:file].inspect} did not expose a SignalWire::SWML::Service subclass."
+        exit 1
+      end
+
+      tools = collect_runtime_tools(service)
+      render_functions_list(tools)
+    end
+
+    # Find a user-defined SWML::Service subclass and return an instance.
+    # Selection order:
+    #   1. A top-level `service` or `agent` constant/variable already
+    #      pointing at a Service instance (rare, but a script may set one).
+    #   2. The most recently defined Service subclass that ISN'T
+    #      SignalWire::SWML::Service or SignalWire::AgentBase itself.
+    def load_service_from_file(path)
+      absolute = File.expand_path(path)
+
+      # Snapshot the existing Service subclasses so we can pick the one
+      # the file just defined, instead of accidentally grabbing a class
+      # left over from earlier requires (e.g. AgentBase).
+      service_class = SignalWire::SWML::Service
+      pre_existing = ObjectSpace.each_object(Class).select { |c| service_subclass?(c, service_class) }.to_set
+
+      load(absolute)
+
+      # Top-level instance fallback (some scripts assign a global).
+      %i[SERVICE AGENT].each do |name|
+        if Object.const_defined?(name)
+          val = Object.const_get(name)
+          return val if val.is_a?(service_class)
+        end
+      end
+
+      newly_defined = ObjectSpace.each_object(Class).select do |c|
+        service_subclass?(c, service_class) && !pre_existing.include?(c)
+      end
+
+      # Sort by class name so output is deterministic when a file defines
+      # multiple subclasses; users can disambiguate by setting `SERVICE`.
+      candidate = newly_defined.sort_by { |c| c.name.to_s }.last
+
+      # Fallback: if no NEW subclass was defined (e.g. running the same
+      # file twice in the same process), pick any user subclass.
+      candidate ||= ObjectSpace.each_object(Class)
+                    .select { |c| service_subclass?(c, service_class) }
+                    .sort_by { |c| c.name.to_s }
+                    .last
+
+      return nil unless candidate
+
+      instantiate_service(candidate)
+    rescue StandardError => e
+      $stderr.puts "Error loading #{path}: #{e.class}: #{e.message}"
+      $stderr.puts e.backtrace.first(8).join("\n") if @options[:verbose]
+      exit 1
+    end
+
+    def service_subclass?(klass, service_class)
+      return false unless klass.is_a?(Class)
+      return false if klass == service_class
+      return false if defined?(SignalWire::AgentBase) && klass == SignalWire::AgentBase
+      klass.ancestors.include?(service_class)
+    rescue StandardError
+      false
+    end
+
+    # Try a parameterless instantiation first (the convention in the
+    # examples). Fall back to a few common keyword shapes if that fails.
+    def instantiate_service(klass)
+      klass.new
+    rescue ArgumentError
+      begin
+        klass.new(host: '127.0.0.1', port: 0)
+      rescue ArgumentError
+        klass.new(name: klass.name.to_s)
+      end
+    end
+
+    # Read the runtime tool registry off a Service instance. Service
+    # exposes `define_tools` (the merged definition list across @tools and
+    # @swaig_functions). That's the source of truth — we use it instead
+    # of poking @tools directly so AgentBase / future subclasses that
+    # override the accessor still work.
+    def collect_runtime_tools(service)
+      if service.respond_to?(:define_tools)
+        Array(service.define_tools).map { |d| stringify_tool(d) }
+      elsif service.instance_variable_defined?(:@tools)
+        service.instance_variable_get(:@tools).values.map { |t| stringify_tool(t[:definition]) }
+      else
+        []
+      end
+    end
+
+    def stringify_tool(defn)
+      return {} unless defn.is_a?(Hash)
+      defn.transform_keys(&:to_s)
+    end
+  end
+end
+
+# Run when invoked directly
+if __FILE__ == $PROGRAM_NAME
+  SwaigTest::CLI.new.run
+end