aia 2.0.0.0.pre.alpha → 2.0.0.0.pre.beta2

data/lib/aia/directives/web_and_file_directives.rb

@@ -10,29 +10,34 @@ module AIA
     PUREMD_API_KEY = ENV.fetch('PUREMD_API_KEY', nil)
 
     desc "Fetch and include content from a webpage"
+    # :reek:TooManyStatements -- guard, fetch via pure.md, then success/error reporting in one flow
     def webpage(args, _context_manager = nil)
       if PUREMD_API_KEY.nil?
-        'ERROR: PUREMD_API_KEY is required in order to include a webpage'
-      else
-        url = args.shift.to_s.strip
-        puremd_url = "https://pure.md/#{url}"
+        msg = 'ERROR: PUREMD_API_KEY is required in order to include a webpage'
+        AIA::LoggerManager.aia_logger.error(msg)
+        puts msg
+        return nil
+      end
 
-        response = Faraday.get(puremd_url) do |req|
-          req.headers['x-puremd-api-token'] = PUREMD_API_KEY
-        end
+      url = args.shift.to_s.strip
+      puremd_url = "https://pure.md/#{url}"
 
-        if response.status == 200
-          response.body
-        else
-          "Error: Status was #{response.status}\n#{ap response}"
-        end
+      response = Faraday.get(puremd_url) do |req|
+        req.headers['x-puremd-api-token'] = PUREMD_API_KEY
       end
+
+      return response.body if response.status == 200
+
+      msg = "Error: Fetching #{url} returned status #{response.status}"
+      AIA::LoggerManager.aia_logger.error(msg)
+      puts msg
+      nil
     end
     alias website webpage
     alias web webpage
 
     desc "List available AIA skills"
-    # rubocop:disable Metrics/AbcSize
+    # :reek:TooManyStatements -- sequential listing: directory guard, term filtering, per-skill output
     def skills(args = [], _context_manager = nil)
       dir = aia_skills_dir
       unless Dir.exist?(dir)
@@ -41,18 +46,7 @@ module AIA
       end
 
       positive_terms, negative_terms = parse_search_terms(Array(args))
-
-      skill_dirs = Dir.children(dir).select do |e|
-        File.directory?(File.join(dir, e)) &&
-          File.exist?(File.join(dir, e, 'SKILL.md'))
-      end
-      entries = skill_dirs.select do |e|
-        next true if positive_terms.empty? && negative_terms.empty?
-        text = read_front_matter_text(File.join(dir, e, 'SKILL.md'))
-        # text is a String; Array#intersect? would raise TypeError
-        positive_terms.all? { |t| text.include?(t) } &&
-          negative_terms.none? { |t| text.include?(t) }
-      end.sort
+      entries = matching_skill_ids(dir, positive_terms, negative_terms)
 
       if entries.empty?
         all_terms = positive_terms + negative_terms
@@ -61,38 +55,23 @@ module AIA
       end
 
       wrap_width = terminal_width - 2
-
-      entries.each do |skill_id|
-        fm = parse_skill_front_matter(File.join(dir, skill_id, 'SKILL.md'))
-        name        = fm['name']        || ''
-        description = fm['description'] || '(no description)'
-        puts "#{skill_id}: #{name}"
-        puts word_wrap(description, width: wrap_width, indent: '  ')
-        puts
-      end
+      entries.each { |skill_id| print_skill_entry(dir, skill_id, wrap_width) }
 
       nil
     end
-    # rubocop:enable Metrics/AbcSize
 
     desc "Include an AIA skill from the configured skills directory"
     def skill(args = [], _context_manager = nil)
       args = Array(args)
       skill_name = args.first&.strip
       if skill_name.nil? || skill_name.empty?
-        msg = "Error: /skill requires a skill name. Use /skills to list available skills."
-        AIA::LoggerManager.aia_logger.error(msg)
-        puts msg
-        return nil
+        return report_skill_error("Error: /skill requires a skill name. Use /skills to list available skills.")
       end
 
       dir = aia_skills_dir
       skill_dir = find_skill_dir(skill_name, dir)
       unless skill_dir
-        msg = "Error: No skill matching '#{skill_name}' found in #{dir}. Use /skills to list available skills."
-        AIA::LoggerManager.aia_logger.error(msg)
-        puts msg
-        return nil
+        return report_skill_error("Error: No skill matching '#{skill_name}' found in #{dir}. Use /skills to list available skills.")
       end
 
       return File.read(skill_dir) if File.file?(skill_dir)
@@ -104,9 +83,7 @@ module AIA
               else
                 "Error: Skill '#{File.basename(skill_dir)}' has no SKILL.md in #{dir}."
               end
-        AIA::LoggerManager.aia_logger.error(msg)
-        puts msg
-        return nil
+        return report_skill_error(msg)
       end
 
       File.read(skill_path)
@@ -117,17 +94,53 @@ module AIA
       content = Clipboard.paste
       content.to_s
     rescue StandardError => e
-      "Error: Unable to paste from clipboard - #{e.message}"
+      msg = "Error: Unable to paste from clipboard - #{e.message}"
+      AIA::LoggerManager.aia_logger.error(msg)
+      puts msg
+      nil
     end
     alias clipboard paste
 
     private
 
+    # Skill directories under dir with a SKILL.md whose front matter passes
+    # the positive/negative term filters, sorted.
+    def matching_skill_ids(dir, positive_terms, negative_terms)
+      skill_dirs = Dir.children(dir).select do |e|
+        File.directory?(File.join(dir, e)) &&
+          File.exist?(File.join(dir, e, 'SKILL.md'))
+      end
+
+      skill_dirs.select do |e|
+        next true if positive_terms.empty? && negative_terms.empty?
+        text = read_front_matter_text(File.join(dir, e, 'SKILL.md'))
+        # text is a String; Array#intersect? would raise TypeError
+        positive_terms.all? { |t| text.include?(t) } &&
+          negative_terms.none? { |t| text.include?(t) }
+      end.sort
+    end
+
+    def print_skill_entry(dir, skill_id, wrap_width)
+      fm = parse_skill_front_matter(File.join(dir, skill_id, 'SKILL.md'))
+      name        = fm['name']        || ''
+      description = fm['description'] || '(no description)'
+      puts "#{skill_id}: #{name}"
+      puts word_wrap(description, width: wrap_width, indent: '  ')
+      puts
+    end
+
+    # Log and print a /skill error message; returns nil so callers can
+    # `return report_skill_error(msg)` from any guard.
+    def report_skill_error(msg)
+      AIA::LoggerManager.aia_logger.error(msg)
+      puts msg
+      nil
+    end
+
     # Resolve the AIA skills directory from config, env vars, or defaults.
     def aia_skills_dir
-      if AIA.respond_to?(:config) && AIA.config&.skills.respond_to?(:dir) && AIA.config.skills.dir
-        return AIA.config.skills.dir
-      end
+      skills = AIA.respond_to?(:config) ? AIA.config&.skills : nil
+      return skills.dir if skills.respond_to?(:dir) && skills.dir
 
       ENV.fetch('AIA_SKILLS__DIR', File.expand_path('~/.prompts/skills'))
     end

data/lib/aia/layered_orchestrator.rb

@@ -34,6 +34,12 @@ module AIA
     MAX_LAYERS = 5
     MAX_TASKS_PER_LAYER = 4
 
+    BUILD_BANNER = <<~BANNER
+      ╔══════════════════════════════════════════════════════════╗
+      ║           LAYERED ORCHESTRATION — 3-TIER BUILD           ║
+      ╚══════════════════════════════════════════════════════════╝
+    BANNER
+
     # Tier 1 prompt: decompose requirements into layers
     # Deliberately short and directive to minimise qwen3 think-block noise.
     LAYER_DECOMPOSE_PROMPT = <<~PROMPT
@@ -124,19 +130,14 @@ module AIA
     #
     # @param context [HandlerContext] — reads context.prompt as requirements text
     # @return [String, nil] final synthesis or nil on failure
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    # :reek:TooManyStatements -- single orchestration script (banner, tier 1-3 waves, synthesis, report); the narrative order is the value
+    # :reek:DuplicateMethodCall -- say("") prints deliberate blank separator lines between build phases; not a hoistable value
     def handle(context)
       requirements = context.prompt
       primary      = @robot.chief
 
       FileUtils.mkdir_p(@build_dir)
-      say("")
-      say("╔══════════════════════════════════════════════════════════╗")
-      say("║           LAYERED ORCHESTRATION — 3-TIER BUILD           ║")
-      say("╚══════════════════════════════════════════════════════════╝")
-      say("Requirements: #{requirements.lines.first.strip}")
-      say("Build output: #{@build_dir}")
-      say("")
+      print_build_banner(requirements)
 
       # Tier 1: Tobor decomposes requirements into layers
       layers = decompose_to_layers(primary, requirements)
@@ -173,23 +174,38 @@ module AIA
       save_final_report(final_text)
       say("Build complete: #{@build_dir}")
 
+      record_final_turn(requirements, final_text)
+      final_text
+    rescue StandardError => e
+      report_orchestration_error(e)
+      nil
+    end
+
+    private
+
+    def print_build_banner(requirements)
+      say("")
+      BUILD_BANNER.each_line { |line| say(line.chomp) }
+      say("Requirements: #{requirements.lines.first.strip}")
+      say("Build output: #{@build_dir}")
+      say("")
+    end
+
+    def record_final_turn(requirements, final_text)
       @tracker.record_turn(
         model:  AIA.config.models.first.name,
         input:  requirements,
         result: final_text
       )
-
-      final_text
-    rescue StandardError => e
-      say("✗ Orchestration error: #{e.class}: #{e.message}")
-      e.backtrace&.first(5)&.each { |line| say("    #{line}") }
-      nil
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-    private
+    def report_orchestration_error(error)
+      say("✗ Orchestration error: #{error.class}: #{error.message}")
+      error.backtrace&.first(5)&.each { |line| say("    #{line}") }
+    end
 
     # Tier 1: use a probe robot to decompose requirements into layer specs
+    # :reek:TooManyStatements -- probe run plus parse-failure diagnostics and rescue reporting
     def decompose_to_layers(robot, requirements)
       say("Tier 1 ▶ #{robot.name} decomposing requirements into layers...")
       probe  = build_probe(robot.name + "-layer-probe")
@@ -227,6 +243,7 @@ module AIA
     #
     # @param layers [Array<Hash>] layer specs from Tier 1
     # @return [Hash{ String => Array<Hash> }] layer_name => task list ([] on failure)
+    # :reek:TooManyStatements -- per-layer async fan-out with per-layer error capture; the barrier plumbing is inherent
     def run_leads_wave(layers)
       results = {}
 
@@ -234,19 +251,21 @@ module AIA
         barrier = Async::Barrier.new
         layers.each do |layer|
           barrier.async do
-            probe  = build_probe("#{layer['name']}-lead")
+            name   = layer['name']
+            title  = layer['title']
+            probe  = build_probe("#{name}-lead")
             prompt = TASK_DECOMPOSE_PROMPT % {
-              layer_title:  layer['title'],
+              layer_title:  title,
               requirements: layer['requirements'].to_s,
               max_tasks:    MAX_TASKS_PER_LAYER
             }
             result = probe.run(prompt, mcp: :none, tools: :none)
             tasks  = parse_json_array(extract_content(result)).first(MAX_TASKS_PER_LAYER)
-            say("  ✓ #{layer['title']} lead: #{tasks.size} task(s)")
-            results[layer['name']] = tasks
+            say("  ✓ #{title} lead: #{tasks.size} task(s)")
+            results[name] = tasks
           rescue => e
-            say("  ✗ #{layer['title']} lead failed: #{e.message}")
-            results[layer['name']] = []
+            say("  ✗ #{title} lead failed: #{e.message}")
+            results[name] = []
           end
         end
         barrier.wait
@@ -261,6 +280,7 @@ module AIA
     #
     # @param layer_task_map [Hash{ String => Array<Hash> }] output of run_leads_wave
     # @return [Hash{ String => Hash }] "layer_name|artifact_path" => result hash
+    # :reek:TooManyStatements -- per-task async fan-out with success/failure result recording; the barrier plumbing is inherent
     def run_specialists_wave(layer_task_map)
       jobs = layer_task_map.flat_map do |layer_name, tasks|
         tasks.map { |task| { layer_name: layer_name, task: task } }
@@ -273,31 +293,32 @@ module AIA
         barrier = Async::Barrier.new
         jobs.each do |job|
           barrier.async do
-            task  = job[:task]
-            key   = "#{job[:layer_name]}|#{task['artifact']}"
-            probe = build_probe("#{task['specialist']}-specialist")
-
-            full_prompt = "Artifact to produce: #{task['artifact']}\n\n#{task['prompt']}"
+            task       = job[:task]
+            artifact   = task['artifact']
+            title      = task['title']
+            specialist = task['specialist']
+            key        = "#{job[:layer_name]}|#{artifact}"
+            probe      = build_probe("#{specialist}-specialist")
+
+            full_prompt = "Artifact to produce: #{artifact}\n\n#{task['prompt']}"
             result      = probe.run(full_prompt, mcp: :none, tools: :none)
             output      = extract_content(result)
 
-            save_artifact(task['artifact'], output)
-            say("    ✓ #{task['artifact']}")
+            save_artifact(artifact, output)
+            say("    ✓ #{artifact}")
 
             results[key] = {
-              task:       task['title'],
-              specialist: task['specialist'],
-              artifact:   task['artifact'],
+              task:       title,
+              specialist: specialist,
+              artifact:   artifact,
               output:     output
             }
           rescue => e
-            task = job[:task]
-            key  = "#{job[:layer_name]}|#{task['artifact']}"
-            say("    ✗ #{task['artifact']} failed: #{e.message}")
+            say("    ✗ #{artifact} failed: #{e.message}")
             results[key] = {
-              task:       task['title'],
-              specialist: task['specialist'],
-              artifact:   task['artifact'],
+              task:       title,
+              specialist: specialist,
+              artifact:   artifact,
               output:     "[FAILED: #{e.message}]"
             }
           end
@@ -317,9 +338,11 @@ module AIA
     # @return [Array<Hash>]
     def build_layer_results(layers, layer_task_map, specialist_results)
       layers.map do |layer|
-        tasks_for_layer = layer_task_map[layer['name']] || []
+        name  = layer['name']
+        title = layer['title']
+        tasks_for_layer = layer_task_map[name] || []
         task_results = tasks_for_layer.map do |task|
-          key = "#{layer['name']}|#{task['artifact']}"
+          key = "#{name}|#{task['artifact']}"
           specialist_results[key] || {
             task:       task['title'],
             specialist: task['specialist'],
@@ -328,9 +351,9 @@ module AIA
           }
         end
 
-        summary = synthesize_layer_from_results(layer['title'], task_results)
-        say("  ✓ #{layer['title']} synthesis complete")
-        { layer: layer['title'], tasks: task_results, summary: summary }
+        summary = synthesize_layer_from_results(title, task_results)
+        say("  ✓ #{title} synthesis complete")
+        { layer: title, tasks: task_results, summary: summary }
       end
     end
 

data/lib/aia/logger.rb

@@ -76,22 +76,23 @@ module AIA
       def configure_llm_logger
         return unless defined?(RubyLLM)
 
-        logger = llm_logger
+        logger     = llm_logger
+        llm_config = RubyLLM.config
 
         # Set our logger on the RubyLLM config object
-        if RubyLLM.config.respond_to?(:logger=)
-          RubyLLM.config.logger = logger
+        if llm_config.respond_to?(:logger=)
+          llm_config.logger = logger
         end
 
         # Also set log_file and log_level in case the logger gets recreated
-        if RubyLLM.config.respond_to?(:log_file=)
+        if llm_config.respond_to?(:log_file=)
           file = effective_log_file(logger_config_for(:llm))
-          RubyLLM.config.log_file = resolve_log_file_io(file)
+          llm_config.log_file = resolve_log_file_io(file)
         end
 
-        if RubyLLM.config.respond_to?(:log_level=)
+        if llm_config.respond_to?(:log_level=)
           level = effective_log_level(logger_config_for(:llm))
-          RubyLLM.config.log_level = LOG_LEVELS.fetch(level, Lumberjack::Severity::WARN)
+          llm_config.log_level = LOG_LEVELS.fetch(level, Lumberjack::Severity::WARN)
         end
 
         # Reset the memoized @logger on RubyLLM module so next call uses our config
@@ -307,23 +308,21 @@ module AIA
       # @param file [String] The file config value
       # @param flush [Boolean] If true, flush immediately (no buffering)
       # @return [Lumberjack::Device] The device instance
+      # :reek:BooleanParameter -- flush: maps directly onto Lumberjack's autoflush; two constructors would obscure that single toggle
       def create_device(file, flush: true)
-        # buffer_size: 0 means immediate flush (no buffering)
-        buffer_size = flush ? 0 : 8192
-
         case file.to_s.upcase
         when 'STDOUT'
-          Lumberjack::Device::Writer.new($stdout, buffer_size: buffer_size)
+          Lumberjack::Device::Writer.new($stdout, autoflush: flush)
         when 'STDERR'
-          Lumberjack::Device::Writer.new($stderr, buffer_size: buffer_size)
+          Lumberjack::Device::Writer.new($stderr, autoflush: flush)
         else
           path = File.expand_path(file)
-          # Use date rolling for file-based logs
-          # Multiple loggers can safely write to the same file
-          Lumberjack::Device::DateRollingLogFile.new(
+          # Daily date rolling via Logger::LogDevice, which also makes the
+          # file safe for multiple loggers to write to
+          Lumberjack::Device::LogFile.new(
             path,
-            roll: :daily,
-            buffer_size: buffer_size
+            shift_age: 'daily',
+            autoflush: flush
           )
         end
       end
@@ -333,12 +332,13 @@ module AIA
       # @param system [Symbol] The system (:aia, :llm, :mcp)
       # @return [ConfigSection, nil] The configuration section
       def logger_config_for(system)
-        return nil unless AIA.config&.logger
+        logger_cfg = AIA.config&.logger
+        return nil unless logger_cfg
 
         case system
-        when :aia then AIA.config.logger.aia
-        when :llm then AIA.config.logger.llm
-        when :mcp then AIA.config.logger.mcp
+        when :aia then logger_cfg.aia
+        when :llm then logger_cfg.llm
+        when :mcp then logger_cfg.mcp
         end
       rescue NoMethodError
         nil

data/lib/aia/mcp_connection_manager.rb

@@ -10,6 +10,7 @@ require 'timeout'
 require 'tty-spinner'
 
 module AIA
+  # :reek:TooManyMethods -- one small helper per connection-lifecycle concern (connect, wrap tools, record outcomes)
   class MCPConnectionManager
     # Maximum seconds to wait for a single MCP server to connect.
     DEFAULT_TIMEOUT = 30
@@ -30,6 +31,7 @@ module AIA
     #
     # @param servers [Array<Hash>] MCP server configurations
     # @return [self]
+    # :reek:TooManyStatements -- connection ceremony: spinner setup, thread launch, global timeout guard, summary logging
     def connect_all(servers)
       return self unless servers.is_a?(Array) && servers.any?
 
@@ -76,9 +78,10 @@ module AIA
       connected_keys, tool_counts, failed = @mutex.synchronize do
         [@connected_clients.keys.dup, @server_tool_counts.dup, @failed_servers.dup]
       end
-      AIA.config.connected_mcp_servers  = connected_keys
-      AIA.config.mcp_server_tool_counts = tool_counts
-      AIA.config.failed_mcp_servers     = failed
+      cfg = AIA.config
+      cfg.connected_mcp_servers  = connected_keys
+      cfg.mcp_server_tool_counts = tool_counts
+      cfg.failed_mcp_servers     = failed
       self
     end
 
@@ -98,6 +101,7 @@ module AIA
     # the connected state so inject_into will include them in the robot.
     #
     # @return [self]
+    # :reek:TooManyStatements -- per-client absorb loop: start if needed, extract tools, merge into connected state with error capture
     def absorb_ruby_llm_mcp_clients
       return self unless defined?(RubyLLM::MCP)
 
@@ -189,14 +193,17 @@ module AIA
       logger = AIA::LoggerManager.mcp_logger
       logger.warn("MCP: Global connection timeout (#{global_limit}s) reached")
 
-      connected_names = @mutex.synchronize { @connected_clients.keys.to_set }
-      failed_names    = @mutex.synchronize { @failed_servers.to_set { |f| f[:name] } }
+      connected_names, failed_names = @mutex.synchronize do
+        [@connected_clients.keys.to_set, @failed_servers.to_set { |f| f[:name] }]
+      end
 
-      servers.each do |server_config|
+      stragglers = servers.filter_map do |server_config|
         srv_name = server_config.is_a?(Hash) ? (server_config[:name] || server_config['name']) : server_config.to_s
         next if connected_names.include?(srv_name) || failed_names.include?(srv_name)
-        @mutex.synchronize { @failed_servers << { name: srv_name, error: "global connection timeout (#{global_limit}s)" } }
+
+        { name: srv_name, error: "global connection timeout (#{global_limit}s)" }
       end
+      @mutex.synchronize { @failed_servers.concat(stragglers) }
     end
 
     # Read global MCP connection timeout from config.
@@ -208,61 +215,64 @@ module AIA
     end
 
     # Connect a single MCP server, updating the spinner on completion.
-    # rubocop:disable Metrics/MethodLength
+    # :reek:TooManyStatements -- one connect attempt with per-outcome reporting (success, refused, timeout, error)
     def connect_one(server_config, name, spinner, logger)
       timeout = server_timeout(server_config)
       spinner.auto_spin
 
       logger.info("MCP: connecting to '#{name}'...")
-      # rubocop:disable Metrics/BlockLength
       Timeout.timeout(timeout) do
         client = RobotLab::MCP::Client.new(server_config)
         client.connect
 
         if client.connected?
-          tools = client.list_tools
-          built_tools = tools.map do |tool_def|
-            tool_name  = tool_def[:name]
-            mcp_client = client
-            RobotLab::Tool.create(
-              name:        tool_name,
-              description: tool_def[:description],
-              parameters:  tool_def[:inputSchema],
-              mcp:         name
-            ) { |args| mcp_client.call_tool(tool_name, args) }
-          end
-
-          @mutex.synchronize do
-            @connected_clients[name]  = client
-            @server_tool_counts[name] = tools.size
-            add_tools_deduped(built_tools, name, logger)
-          end
-
-          logger.info("MCP: '#{name}' connected (#{tools.size} tools)")
-          spinner.success("(#{tools.size} tools)")
+          record_connected(name, client, build_mcp_tools(client, name), spinner, logger)
         else
-          @mutex.synchronize do
-            @failed_servers << { name: name, error: "connection failed" }
-          end
+          record_failed_server(name, "connection failed")
           logger.warn("MCP: '#{name}' failed to connect")
           spinner.error("(connection failed)")
         end
       end
-      # rubocop:enable Metrics/BlockLength
     rescue Timeout::Error
-      @mutex.synchronize do
-        @failed_servers << { name: name, error: "timed out after #{timeout}s" }
-      end
+      record_failed_server(name, "timed out after #{timeout}s")
       logger.warn("MCP: '#{name}' timed out after #{timeout}s")
       spinner.error("(timed out)")
     rescue StandardError => e
+      msg = e.message
+      record_failed_server(name, msg)
+      logger.warn("MCP: '#{name}' error: #{msg}")
+      spinner.error("(#{msg})")
+    end
+
+    # Wrap each remote tool definition in a RobotLab::Tool proxying to the client.
+    def build_mcp_tools(client, server_name)
+      client.list_tools.map do |tool_def|
+        tool_name = tool_def[:name]
+        RobotLab::Tool.create(
+          name:        tool_name,
+          description: tool_def[:description],
+          parameters:  tool_def[:inputSchema],
+          mcp:         server_name
+        ) { |args| client.call_tool(tool_name, args) }
+      end
+    end
+
+    def record_connected(name, client, tools, spinner, logger)
+      tool_count = tools.size
+
       @mutex.synchronize do
-        @failed_servers << { name: name, error: e.message }
+        @connected_clients[name]  = client
+        @server_tool_counts[name] = tool_count
+        add_tools_deduped(tools, name, logger)
       end
-      logger.warn("MCP: '#{name}' error: #{e.message}")
-      spinner.error("(#{e.message})")
+
+      logger.info("MCP: '#{name}' connected (#{tool_count} tools)")
+      spinner.success("(#{tool_count} tools)")
+    end
+
+    def record_failed_server(name, error)
+      @mutex.synchronize { @failed_servers << { name: name, error: error } }
     end
-    # rubocop:enable Metrics/MethodLength
 
     # Add tools to @connected_tools, skipping any whose name is already present.
     # Logs a warning for each duplicate so the user knows which server wins.

data/lib/aia/mcp_server_config.rb

@@ -0,0 +1,30 @@
+# lib/aia/mcp_server_config.rb
+
+module AIA
+  # Normalized view of one MCP server hash. Server configs arrive with
+  # symbol or string keys, and with connection fields either nested under
+  # :transport or at the top level; this object owns all of that fallback
+  # logic so callers never touch the raw hash shape.
+  McpServerConfig = Data.define(:name, :command, :args, :env, :timeout_raw) do
+    def self.from_hash(server)
+      transport = fetch_key(server, :transport) || {}
+      new(
+        name:        AIA::Utility.server_name(server),
+        command:     fetch_key(transport, :command) || fetch_key(server, :command),
+        args:        Array(fetch_key(transport, :args) || fetch_key(server, :args)),
+        env:         fetch_key(transport, :env) || fetch_key(server, :env) || {},
+        timeout_raw: fetch_key(server, :timeout)
+      )
+    end
+
+    # Read a hash entry by symbol or string key.
+    def self.fetch_key(hash, key) = hash[key] || hash[key.to_s]
+
+    # Timeout in milliseconds; raw values below 1000 are treated as seconds.
+    def timeout_ms(default: 8_000, cap: 30_000)
+      raw = (timeout_raw || default).to_i
+      ms  = raw < 1000 ? raw * 1000 : raw
+      [ms, cap].min
+    end
+  end
+end

data/lib/aia/mcp_utility.rb

@@ -26,14 +26,17 @@ module AIA
       AIA.config&.failed_mcp_servers || []
     end
 
+    # :reek:TooManyStatements -- server-name resolution applying no_mcp, use-list, and skip-list filters in precedence order
     def effective_mcp_server_names
-      return [] if AIA.config&.flags&.no_mcp
-      servers = AIA.config&.mcp_servers || []
+      cfg = AIA.config
+      return [] if cfg&.flags&.no_mcp
+
+      servers = cfg&.mcp_servers || []
       return [] if servers.empty?
 
       names     = servers.map { |s| server_name(s) }.compact
-      use_list  = Array(AIA.config.mcp_use)
-      skip_list = Array(AIA.config.mcp_skip)
+      use_list  = Array(cfg.mcp_use)
+      skip_list = Array(cfg.mcp_skip)
 
       if use_list.any?
         names.select { |n| use_list.include?(n) }