aia 1.1.1 → 2.0.0.0.pre.beta2

data/lib/aia/tool_loader.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_loader.rb
+#
+# Tool loading, caching, filtering, and discovery.
+# Extracted from RobotFactory to isolate the tool concern.
+#
+# ToolLoader is a class with instance-level cache state so that two instances
+# have independent caches. Class-level convenience methods delegate to a
+# resettable default instance (reset via ToolLoader.reset_instance! or AIA.reset!).
+
+module AIA
+  class ToolLoader
+    class << self
+      # Returns the shared default instance, creating it on first call.
+      def instance
+        @instance ||= new
+      end
+
+      # Discard the default instance. The next call to .instance creates a fresh one.
+      # Called from AIA.reset! for test isolation.
+      def reset_instance!
+        @instance = nil
+      end
+
+      # Class-level convenience wrappers — delegate to the default instance.
+      def cached_tools            = instance.cached_tools
+      def clear_cache!            = instance.clear_cache!
+      def load_tools(config)      = instance.load_tools(config)
+      def filtered_tools(config)  = instance.filtered_tools(config)
+      def discover_tools          = instance.discover_tools
+      def eager_load_gem_tools    = instance.eager_load_gem_tools
+
+      def activate_unbundled_gem(name)
+        instance.activate_unbundled_gem(name)
+      end
+    end
+
+    def initialize
+      @tool_cache = nil
+    end
+
+    # Clear the cached tool discovery results.
+    # Call when tool paths change via /config directive.
+    def clear_cache!
+      @tool_cache = nil
+    end
+
+    # Return the current tool cache (nil if not yet populated).
+    def cached_tools
+      @tool_cache
+    end
+
+    # Load tools from require_libs and tool paths, then cache the result.
+    # Subsequent calls to RobotFactory.build skip this entirely if cache exists.
+    # :reek:TooManyStatements -- sequential phases: require_libs with activation retry, tool files, eager loads, discovery cache
+    def load_tools(config)
+      Array(config.require_libs).each do |lib|
+        require lib
+      rescue LoadError
+        # Not yet active — activate it (and its deps) via RubyGems, then retry
+        if activate_unbundled_gem(lib)
+          require lib rescue warn("Warning: Failed to require '#{lib}' after activation")
+        else
+          $stderr.puts "Warning: Failed to require '#{lib}': gem not found"
+        end
+      end
+
+      # Load tool files from paths
+      Array(config.tools&.paths).each do |path|
+        expanded = File.expand_path(path)
+        if File.exist?(expanded)
+          require expanded
+        else
+          $stderr.puts "Warning: Tool file not found: #{path}"
+        end
+      rescue LoadError, StandardError => e
+        $stderr.puts "Warning: Failed to load tool '#{path}': #{e.message}"
+      end
+
+      # Eagerly load tools from gems that use zeitwerk lazy loading
+      # (e.g., shared_tools provides .load_all_tools for this purpose)
+      eager_load_gem_tools
+
+      # Re-register PM directives so any AIA::Directive subclasses defined
+      # in just-loaded tool files become available in ERB prompt rendering.
+      PM::Directive.register_all if defined?(PM::Directive)
+
+      # Discover loaded tools via ObjectSpace and cache the result
+      tools = discover_tools
+      @tool_cache = tools
+      config.loaded_tools = tools
+      config.tool_names = tools.map { |t| tool_name(t) }.join(', ')
+    end
+
+    # A tool's display name: instances expose #name; bare classes fall back to the class name.
+    def tool_name(tool)
+      tool.respond_to?(:name) ? tool.name : tool.class.name
+    end
+
+    # Filter tools based on allowed/rejected lists and KBS decisions.
+    # :reek:TooManyStatements -- allowed filter, rejected filter, then a name-dedup pass over the tool list
+    # :reek:DuplicateMethodCall -- tool_name(t) is applied per element inside three separate filter blocks; no shared scope to hoist into
+    def filtered_tools(config)
+      tools = config.loaded_tools || []
+      allowed = config.tools&.allowed
+      rejected = config.tools&.rejected
+
+      if allowed && !allowed.empty?
+        allowed_list = Array(allowed).map(&:strip).map(&:downcase)
+        tools = tools.select do |t|
+          name = tool_name(t).downcase
+          # name is a String; Array#intersect? would raise TypeError
+          allowed_list.any? { |a| name.include?(a) }
+        end
+      end
+
+      if rejected && !rejected.empty?
+        rejected_list = Array(rejected).map(&:strip).map(&:downcase)
+        tools = tools.reject do |t|
+          name = tool_name(t).downcase
+          # name is a String; Array#intersect? would raise TypeError
+          rejected_list.any? { |r| name.include?(r) }
+        end
+      end
+
+      seen = {}
+      tools.select do |t|
+        name = tool_name(t)
+        if seen[name]
+          false
+        else
+          seen[name] = true
+          true
+        end
+      end
+    end
+
+    # Discover RubyLLM::Tool subclasses from ObjectSpace.
+    # Skips tools that report themselves as unavailable via #available?.
+    def discover_tools
+      ObjectSpace.each_object(Class).select do |klass|
+        next false unless defined?(RubyLLM::Tool) && klass < RubyLLM::Tool
+        begin
+          instance = klass.new
+          if instance.respond_to?(:available?) && !instance.available?
+            tool_name = instance.respond_to?(:name) ? instance.name : klass.name
+            $stderr.puts "Info: Tool '#{tool_name}' is not available, skipping"
+            next false
+          end
+          true
+        rescue LoadError, StandardError
+          false
+        end
+      end
+    end
+
+    # Activate a gem that isn't yet active by asking RubyGems to activate it.
+    # This adds its lib paths to $LOAD_PATH AND activates its dependencies,
+    # unlike a manual $LOAD_PATH manipulation which would leave deps unresolved.
+    #
+    # Under bundler/setup (dev mode), `gem name` raises Gem::LoadError for any
+    # gem not in the bundle. The fallback searches known gem install paths directly
+    # and adds the lib dir to $LOAD_PATH so Zeitwerk-based gems still load.
+    def activate_unbundled_gem(name)
+      gem name
+      true
+    rescue Gem::LoadError
+      lib_dir = [Gem.default_dir, Gem.user_dir].compact.flat_map do |d|
+        Dir.glob("#{d}/gems/#{name}-*/lib")
+      end.max
+      return false unless lib_dir
+      $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+      true
+    rescue StandardError
+      false
+    end
+
+    # Eagerly load tool classes from any required gem that uses lazy loading
+    # (e.g. Zeitwerk). Calls .load_all_tools on every module that responds to it,
+    # so any gem following that convention works — not just SharedTools.
+    #
+    # Gem::LoadError (a LoadError, not a StandardError) can fire when a tool's
+    # dependency has a version conflict with an already-activated gem. The inner
+    # rescue handles that per-module; the fallback loads constants one-at-a-time
+    # so tools without conflicting deps still become available.
+    def eager_load_gem_tools
+      ObjectSpace.each_object(Module) do |mod|
+        if mod.respond_to?(:load_all_tools)
+          begin
+            mod.load_all_tools
+          rescue LoadError, StandardError
+            eager_load_namespace_fallback(mod)
+          end
+        end
+      rescue LoadError, StandardError
+        next
+      end
+    rescue LoadError, StandardError => e
+      $stderr.puts "Warning: Failed to eager-load gem tools: #{e.message}"
+    end
+
+    # Fallback when bulk load_all_tools fails: walk the module's namespace
+    # recursively (up to 3 levels) and trigger each constant's autoload
+    # individually, skipping any that raise a load error.
+    def eager_load_namespace_fallback(mod, depth = 0)
+      return if depth > 3
+      mod.constants.each do |const_name|
+        child = mod.const_get(const_name)
+        eager_load_namespace_fallback(child, depth + 1) if child.is_a?(Module)
+      rescue LoadError, StandardError
+        next
+      end
+    end
+  end
+end

data/lib/aia/tool_utility.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# lib/aia/tool_utility.rb
+#
+# Pure tool state-query methods mixed into AIA::Utility via `class << self include`.
+# No display or formatting concerns — those live in Utility directly.
+
+module AIA
+  module ToolUtility
+    def tools?
+      return true if AIA.config&.tool_names && !AIA.config.tool_names.empty?
+      total_tool_count.positive?
+    end
+
+    def total_tool_count
+      local = Array(AIA.config&.loaded_tools).size
+      return local if AIA.config&.flags&.no_mcp
+      mcp = defined?(RubyLLM::MCP) ? RubyLLM::MCP.clients.sum { |_, c| c.tools.count } : 0
+      local + mcp
+    end
+
+    def user_tools?
+      AIA.config&.tools&.paths&.any?
+    end
+
+    def supports_tools?
+      AIA.client&.model&.supports_functions? || false
+    end
+  end
+end

data/lib/aia/tools/delegate_to_foreman_tool.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# lib/aia/tools/delegate_to_foreman_tool.rb
+#
+# Lightweight tool given to Tobor (and other primary robots) that
+# delegates task board operations to Foreman, a specialist robot
+# with full TaskBoardTool access. Foreman is built on first use
+# and cached for the session.
+
+module AIA
+  class DelegateToForemanTool < RubyLLM::Tool
+    description "Delegate a task management request to Foreman, the task board manager. " \
+                "Use this when you need to create, assign, track, or manage tasks. " \
+                "Pass a natural language description of what you need done on the task board."
+
+    param :request, type: :string, required: true,
+          desc: "Natural language description of the task board operation " \
+                "(e.g., 'create a research task about recessions assigned to Tobor with labels research, economics')"
+
+    def available?
+      AIA.task_coordinator&.available? || false
+    end
+
+    def execute(request:, **_params)
+      foreman = self.class.foreman
+      result = foreman.run(request)
+      result.respond_to?(:reply) ? result.reply : result.to_s
+    rescue StandardError => e
+      "Foreman error: #{e.message}"
+    end
+
+    class << self
+      def foreman
+        @foreman ||= build_foreman
+      end
+
+      def reset!
+        @foreman = nil
+      end
+
+      private
+
+      def build_foreman
+        model_spec = AIA.config.models.first
+        run_config = RobotFactory.build_run_config(AIA.config)
+
+        RobotFactory.build_robot(
+          model_spec,
+          name:          'Foreman',
+          system_prompt: foreman_system_prompt,
+          local_tools:   [TaskBoardTool],
+          config:        run_config
+        )
+      end
+
+      def foreman_system_prompt
+        <<~PROMPT
+          You are Foreman, the task board manager. You manage a shared TrakFlow
+          task board where robots can create, claim, and complete tasks.
+
+          When given a request, use the task_board tool to execute it. Be precise
+          and efficient — execute the operation and report the result concisely.
+
+          You can: create tasks, plan multi-step work, check ready tasks, claim
+          tasks, mark tasks complete, block tasks, and report board status.
+        PROMPT
+      end
+    end
+  end
+end

data/lib/aia/tools/recruit_robot_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# lib/aia/tools/recruit_robot_tool.rb
+#
+# RubyLLM::Tool that lets the crew chief grow its own crew. The chief can
+# name a new robot, pick its provider/model (or inherit the chief's), and
+# write its system prompt — all through standard tool-use protocol. The
+# newcomer joins the running crew and answers to @name immediately.
+
+module AIA
+  class RecruitRobotTool < RubyLLM::Tool
+    description "Recruit a new robot into the crew. Give it a name, an " \
+                "optional provider/model (omit to inherit yours), optional " \
+                "skills that define its role, and/or a system prompt. The " \
+                "newcomer joins the crew right away and can be addressed with @name."
+
+    param :name, type: :string, required: true,
+          desc: "Unique name for the new robot, e.g. 'researcher'. Reserved: 'crew'."
+    param :model, type: :string,
+          desc: "Optional provider/model, e.g. 'ollama/qwen3.6:latest' or 'gpt-4o'. " \
+                "Omit (or pass '-') to inherit the chief's model and provider."
+    param :skills, type: :string,
+          desc: "Optional comma-separated skill ids to assign as the robot's role " \
+                "(e.g. 'security-review,ruby-style'). Each skill's content becomes " \
+                "part of its system prompt. Use this to give crew members distinct jobs."
+    param :system_prompt, type: :string,
+          desc: "Optional extra system prompt, appended after any skills — its role, " \
+                "persona, and instructions."
+
+    def execute(name:, model: nil, skills: nil, system_prompt: nil)
+      robot = AIA::Crew.recruit(build_spec(name, model, skills, system_prompt))
+      "Recruited '#{robot.name}' into the crew on #{robot.model || 'the chief\'s model'}. " \
+        "Address it with @#{robot.name}."
+    rescue AIA::CrewError => e
+      "Could not recruit '#{name}': #{e.message}"
+    end
+
+    private
+
+    # Translate the tool's flat params into a Crew spec, splitting a
+    # "provider/model" string into its parts (nil model => inherit the chief's)
+    # and a comma-separated skills string into a list.
+    def build_spec(name, model, skills, system_prompt)
+      parsed_model, provider = SpawnSpecParser.parse_model(model)
+      prompt = system_prompt.to_s.strip
+      {
+        name:          name,
+        model:         parsed_model,
+        provider:      provider,
+        skills:        split_skills(skills),
+        system_prompt: prompt.empty? ? nil : prompt
+      }
+    end
+
+    # "security, ruby-style" => ["security", "ruby-style"]
+    def split_skills(skills)
+      skills.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/aia/tools/reskill_robot_tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# lib/aia/tools/reskill_robot_tool.rb
+#
+# RubyLLM::Tool that lets the crew chief reset one of its crew members to a
+# clean slate and give it a different role. The member keeps its name and model
+# but gets a fresh conversation and a new skill/system prompt — useful when a
+# recruit drifted off task or needs to be repurposed for the next phase.
+
+module AIA
+  class ReskillRobotTool < RubyLLM::Tool
+    description "Reset a crew member to a clean slate and re-skill it. The robot " \
+                "keeps its @name and model but gets a fresh conversation and a new " \
+                "role from the given skills and/or system prompt. Use this to " \
+                "repurpose a member or recover one that went off task."
+
+    param :name, type: :string, required: true,
+          desc: "Name of the existing crew member to reset (cannot be the chief)."
+    param :skills, type: :string,
+          desc: "Optional comma-separated skill ids to assign as the new role " \
+                "(e.g. 'testing,performance')."
+    param :system_prompt, type: :string,
+          desc: "Optional extra system prompt, appended after any skills."
+
+    def execute(name:, skills: nil, system_prompt: nil)
+      prompt = system_prompt.to_s.strip
+      robot = AIA::Crew.reskill(
+        name,
+        skills:        split_skills(skills),
+        system_prompt: prompt.empty? ? nil : prompt
+      )
+      "Reset '#{robot.name}' to a clean slate with its new role. Address it with @#{robot.name}."
+    rescue AIA::CrewError => e
+      "Could not reskill '#{name}': #{e.message}"
+    end
+
+    private
+
+    # "testing, performance" => ["testing", "performance"]
+    def split_skills(skills)
+      skills.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/aia/tools/task_board_tool.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# lib/aia/tools/task_board_tool.rb
+#
+# RubyLLM::Tool that lets robots manage a shared TrakFlow task board.
+# Robots can create tasks for each other, check what's ready, claim
+# work, and report completion — all through standard tool-use protocol.
+
+require "json"
+
+module AIA
+  # :reek:DataClump -- each execute_<action> dispatch target receives the same LLM tool-call context
+  class TaskBoardTool < RubyLLM::Tool
+    description "Manage a shared task board. Create tasks for other robots, " \
+                "check what's ready, claim tasks, and report completion."
+
+    param :action, type: :string, required: true,
+          desc: "One of: create, plan, ready, claim, complete, block, status"
+    param :title, type: :string,
+          desc: "Task title (for create/plan actions)"
+    param :assignee, type: :string,
+          desc: "Robot name to assign to (for create/claim/ready)"
+    param :labels, type: :string,
+          desc: "Comma-separated labels (for create)"
+    param :blocked_by, type: :string,
+          desc: "Comma-separated blocker task IDs (for create)"
+    param :steps, type: :string,
+          desc: "JSON array of step objects [{title:, assignee:}] (for plan)"
+    param :task_id, type: :string,
+          desc: "Task ID (for claim/complete/block)"
+    param :result, type: :string,
+          desc: "Result summary (for complete) or reason (for block)"
+
+    # Never auto-discovered onto primary robots. Only Foreman
+    # (built by DelegateToForemanTool) receives this tool explicitly.
+    def available?
+      false
+    end
+
+    def execute(action:, **params)
+      coordinator = AIA.task_coordinator
+      return "Task board unavailable (TrakFlow not initialized)" unless coordinator&.available?
+
+      robot_name = params[:_robot_name] || "unknown"
+
+      case action
+      when "create"  then execute_create(coordinator, robot_name, params)
+      when "plan"    then execute_plan(coordinator, robot_name, params)
+      when "ready"   then execute_ready(coordinator, params)
+      when "claim"   then execute_claim(coordinator, robot_name, params)
+      when "complete" then execute_complete(coordinator, robot_name, params)
+      when "block"   then execute_block(coordinator, robot_name, params)
+      when "status"  then coordinator.status_summary || "No tasks"
+      else
+        "Unknown action: #{action}. Use: create, plan, ready, claim, complete, block, status"
+      end
+    end
+
+    private
+
+    def execute_create(coordinator, robot_name, params)
+      task = coordinator.create_task(
+        params[:title],
+        assignee:   params[:assignee],
+        labels:     parse_csv(params[:labels]),
+        blocked_by: parse_csv(params[:blocked_by]),
+        creator:    robot_name
+      )
+      task ? "Created [#{task.id}] '#{task.title}'" : "Failed to create task"
+    end
+
+    def execute_plan(coordinator, robot_name, params)
+      steps = JSON.parse(params[:steps] || "[]", symbolize_names: true)
+      result = coordinator.create_plan(
+        params[:title], steps: steps, creator: robot_name
+      )
+      result ? "Plan created with #{result[:steps].size} steps" : "Failed to create plan"
+    rescue JSON::ParserError => e
+      "Invalid steps JSON: #{e.message}"
+    end
+
+    def execute_ready(coordinator, params)
+      tasks = coordinator.ready_tasks(robot_name: params[:assignee])
+      return "No ready tasks" if tasks.empty?
+      tasks.map { |t| "[#{t.id}] #{t.title} (#{t.assignee || 'unassigned'})" }.join("\n")
+    end
+
+    def execute_claim(coordinator, robot_name, params)
+      coordinator.claim_task(params[:task_id], robot_name)
+      "Claimed task #{params[:task_id]}"
+    end
+
+    def execute_complete(coordinator, robot_name, params)
+      coordinator.complete_task(
+        params[:task_id],
+        result:     params[:result] || "Done",
+        robot_name: robot_name
+      )
+      "Completed task #{params[:task_id]}"
+    end
+
+    def execute_block(coordinator, robot_name, params)
+      coordinator.block_task(
+        params[:task_id],
+        reason:     params[:result] || "Blocked",
+        robot_name: robot_name
+      )
+      "Blocked task #{params[:task_id]}"
+    end
+
+    def parse_csv(value)
+      (value || "").split(",").map(&:strip).reject(&:empty?)
+    end
+  end
+end