aia 1.1.1 → 2.0.0.0.pre.beta2

data/lib/aia/crew.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative 'skill_utils'
+
+module AIA
+  # Runtime management of the chat session's crew — the Network behind
+  # AIA.client. After RobotFactory wraps every session in a crew, members can be
+  # added and removed mid-conversation. Both the user (via /add_recruit and
+  # /drop_recruit) and a robot (via a tool) funnel through here.
+  module Crew
+    module_function
+
+    # Recruit a new robot into the running crew. The newcomer is spawned from
+    # the crew's chief (sharing its bus), optionally on an explicit
+    # model/provider, then added to the crew so it shows in /robots and answers
+    # to @name. With no model it inherits the chief's model and provider.
+    #
+    # @param spec [Hash] {name:, model:, provider:, system_prompt:, skills:} (e.g. from SpawnSpecParser)
+    # @return [RobotLab::Robot] the recruited robot
+    # @raise [AIA::CrewError]
+    def recruit(spec)
+      crew  = require_crew
+      chief = crew.chief
+      name  = spec[:name].to_s
+      if name.casecmp?(MentionRouter::BROADCAST_TOKEN)
+        raise CrewError, "'#{name}' is reserved (@crew broadcasts to every member)."
+      end
+      raise CrewError, "A crewmate named '#{name}' already exists." if member?(crew, name)
+
+      robot = chief.spawn(
+        name:          name,
+        system_prompt: compose_system_prompt(spec),
+        local_tools:   chief_local_tools(chief),
+        **model_opts(spec)
+      )
+      inherit_mcp(robot, chief)
+      crew.add_robot(robot)
+      robot
+    end
+
+    # Reset an existing crewmate to a clean slate and re-skill it. The member is
+    # dropped and re-recruited from the chief on the same model/provider, with a
+    # fresh conversation and the given skills/system prompt as its new role. The
+    # chief cannot be reskilled.
+    #
+    # @param name [String]
+    # @param skills [Array<String>, nil] skill ids to assign as the new role
+    # @param system_prompt [String, nil] extra system prompt appended after skills
+    # @return [RobotLab::Robot] the re-skilled robot
+    # @raise [AIA::CrewError]
+    def reskill(name, skills: nil, system_prompt: nil)
+      crew = require_crew
+      name = name.to_s
+      old  = find_member(crew, name)
+      raise CrewError, "No crewmate named '#{name}'." unless old
+      raise CrewError, "Cannot reskill the chief '#{name}'." if crew.chief&.name == name
+
+      crew.remove_robot(name)
+      recruit(
+        name: name, model: old.model, provider: old.provider,
+        skills: skills, system_prompt: system_prompt
+      )
+    end
+
+    # Drop a crewmate by name. The chief (the session's lead robot) cannot be
+    # dropped.
+    #
+    # @param name [String]
+    # @return [RobotLab::Robot] the removed robot
+    # @raise [AIA::CrewError]
+    def drop(name)
+      crew = require_crew
+      name = name.to_s
+      raise CrewError, "No crewmate named '#{name}'." unless member?(crew, name)
+      raise CrewError, "Cannot drop the chief '#{name}'." if crew.chief&.name == name
+
+      crew.remove_robot(name)
+    end
+
+    # The crew (Network) backing the current session.
+    #
+    # @return [RobotLab::Network]
+    # @raise [AIA::CrewError] when the session isn't a crew
+    def require_crew
+      crew = AIA.client
+      raise CrewError, "The active session is not a crew; cannot manage members." unless crew.respond_to?(:add_robot)
+
+      crew
+    end
+
+    # @return [Boolean]
+    def member?(crew, name)
+      crew.crew.any? { |robot| robot.name == name }
+    end
+
+    # @return [RobotLab::Robot, nil]
+    def find_member(crew, name)
+      crew.crew.find { |robot| robot.name == name }
+    end
+
+    # Build the recruit's system prompt (its role) from any assigned skills
+    # followed by an explicit system prompt. Falls back to a simple default when
+    # neither is given.
+    #
+    # @return [String]
+    def compose_system_prompt(spec)
+      parts = [skills_prompt(spec[:skills]), spec[:system_prompt]].compact
+      parts.empty? ? "You are #{spec[:name]}." : parts.join("\n\n")
+    end
+
+    # Load the bodies of the named skills, joined, to seed a recruit's role.
+    # Raises so the caller (user or chief) hears about an unknown skill rather
+    # than silently recruiting a robot without the role it was meant to have.
+    #
+    # @param skill_ids [Array<String>, nil]
+    # @return [String, nil]
+    # @raise [AIA::CrewError]
+    def skills_prompt(skill_ids)
+      ids = Array(skill_ids).map(&:to_s).reject(&:empty?)
+      return nil if ids.empty?
+
+      base = AIA::SkillUtils.skills_base_dir(AIA.config)
+      raise CrewError, "No skills directory is configured." unless base
+
+      missing = ids.reject { |id| AIA::SkillUtils.find_skill_dir(id, base) }
+      raise CrewError, "Skill(s) not found: #{missing.join(', ')}." unless missing.empty?
+
+      AIA::SkillUtils.load_skills_content(ids, base)
+    end
+
+    # Model/provider override for an explicit recruit. When a model is given the
+    # provider is passed too (even nil) so it overrides the inherited chief
+    # provider; with no model, {} lets the spawn inherit chief model + provider.
+    #
+    # @return [Hash]
+    def model_opts(spec)
+      return {} unless spec[:model]
+
+      { model: spec[:model], provider: spec[:provider] }
+    end
+
+    # The chief's local tool instances, shared with the recruit so it can do the
+    # same work (file/shell/etc.). Tool instances are effectively stateless, so
+    # sharing them across crew members is safe.
+    #
+    # @return [Array]
+    def chief_local_tools(chief)
+      chief.respond_to?(:local_tools) ? Array(chief.local_tools) : []
+    end
+
+    # Hand the recruit the chief's already-connected MCP clients and tools rather
+    # than opening fresh connections.
+    #
+    # @return [void]
+    def inherit_mcp(robot, chief)
+      return unless robot.respond_to?(:inject_mcp!) && chief.respond_to?(:mcp_clients)
+
+      clients = chief.mcp_clients
+      return if clients.nil? || clients.empty?
+
+      robot.inject_mcp!(clients: clients, tools: Array(chief.mcp_tools))
+    end
+  end
+end

data/lib/aia/debate_handler.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# lib/aia/debate_handler.rb
+#
+# Multi-round debate between robots in a network.
+# Each robot responds to the previous round's outputs until
+# convergence is reached or a round limit is hit.
+# Uses TypedBus for bus attachment and SharedMemory for state.
+# Uses Async::Barrier for concurrent robot execution per round.
+
+require 'async'
+
+module AIA
+  class DebateHandler
+    include ContentExtractor
+    include HandlerProtocol
+
+    MAX_ROUNDS           = 5
+    MIN_ROUNDS           = 2
+    SIMILARITY_THRESHOLD = 0.85
+    CONVERGENCE_SIGNAL   = "CONVERGED"
+
+    # Sentinel value for a robot that failed to respond in a round.
+    # Treated as empty string for convergence; rendered with [FAILED] marker.
+    FailedResponse = Data.define(:robot_name, :error_message)
+
+    def initialize(robot:, ui_presenter:, tracker:)
+      @robot        = robot
+      @ui_presenter = ui_presenter
+      @tracker      = tracker
+    end
+
+    attr_writer :robot
+
+    # Run a debate between robots in the network.
+    #
+    # @param context [HandlerContext] — reads context.prompt
+    # @return [String, nil] formatted debate results, or nil if not applicable
+    # :reek:TooManyStatements -- debate orchestration: per-round async fan-out, convergence check, tracking; stages share round state
+    def handle(context)
+      prompt = context.prompt
+      return nil unless @robot.network?
+
+      robots = @robot.crew
+      return nil if robots.size < 2
+
+      # Ensure all robots share a bus
+      bus = TypedBus::MessageBus.new
+      robots.each { |r| r.with_bus(bus) }
+
+      @ui_presenter.display_info(
+        "Debate between #{robots.map(&:name).join(', ')}..."
+      )
+
+      rounds = []
+
+      MAX_ROUNDS.times do |round|
+        round_no      = round + 1
+        round_context = build_round_context(prompt, rounds)
+
+        round_results = run_debate_round(robots, round_context, round, round_no)
+
+        raise DebateError, "All robots failed in round #{round_no}" if
+          round_results.all?(FailedResponse)
+
+        previous = rounds.last
+        rounds << round_results
+
+        if converged?(round, round_results, previous)
+          @ui_presenter.display_info("  Converged in round #{round_no}.")
+          break
+        end
+      end
+
+      @tracker.record_turn(
+        model: AIA.config.models.first.name,
+        input: prompt,
+        result: rounds
+      )
+
+      format_rounds(rounds)
+    end
+
+    private
+
+    # Run every robot once against the round context, concurrently.
+    # Returns one entry per robot: a result hash, or FailedResponse on error.
+    # :reek:TooManyStatements -- async fan-out with per-robot progress, memory write, and failure capture
+    def run_debate_round(robots, round_context, round, round_no)
+      Sync do
+        barrier = Async::Barrier.new
+        tasks = robots.map do |robot|
+          barrier.async do
+            name = robot.name
+            @ui_presenter.display_info("  Round #{round_no}: #{name}...")
+            result  = robot.run(round_context, mcp: :inherit, tools: :inherit)
+            content = extract_content(result)
+            write_to_memory(round, name, content)
+            { robot: name, content: content }
+          rescue => e
+            FailedResponse.new(robot_name: name, error_message: e.message)
+          end
+        end
+        barrier.wait
+        tasks.map(&:wait)
+      end
+    end
+
+    def build_round_context(prompt, rounds)
+      return prompt if rounds.empty?
+
+      previous = rounds.last.map do |r|
+        if r.is_a?(FailedResponse)
+          "#{r.robot_name}: [FAILED: #{r.error_message}]"
+        else
+          "#{r[:robot]}: #{r[:content]}"
+        end
+      end.join("\n\n")
+
+      <<~CONTEXT
+        Topic: #{prompt}
+
+        Previous round:
+        #{previous}
+
+        Respond to the points above. Say CONVERGED if you agree with the overall consensus and provide a final summary. Otherwise refine your position.
+      CONTEXT
+    end
+
+    def converged?(round_index, current_results, previous_results)
+      return false if round_index < MIN_ROUNDS - 1
+
+      # Fast path: every robot explicitly signaled convergence.
+      return true if all_signaled_convergence?(current_results)
+
+      return false if previous_results.nil?
+
+      current_text  = current_results.map  { |r| r.is_a?(FailedResponse) ? "" : r[:content].to_s }.join(" ")
+      previous_text = previous_results.map { |r| r.is_a?(FailedResponse) ? "" : r[:content].to_s }.join(" ")
+
+      scores = SimilarityScorer.score([previous_text, current_text])
+      (scores[1] || 0.0) >= SIMILARITY_THRESHOLD
+    end
+
+    def all_signaled_convergence?(round_results)
+      round_results.all? do |r|
+        next false if r.is_a?(FailedResponse)
+        r[:content].to_s.upcase.include?(CONVERGENCE_SIGNAL)
+      end
+    end
+
+    def write_to_memory(round, robot_name, content)
+      return unless @robot.respond_to?(:memory)
+
+      @robot.memory.current_writer = robot_name
+      @robot.memory.set(:"debate_r#{round}_#{robot_name}", content)
+    end
+
+    def format_rounds(rounds)
+      lines = []
+      rounds.each_with_index do |round, i|
+        lines << "### Round #{i + 1}"
+        round.each do |entry|
+          lines << if entry.is_a?(FailedResponse)
+                     "**#{entry.robot_name}**: [FAILED] #{entry.error_message}\n"
+                   else
+                     "**#{entry[:robot]}**: #{entry[:content]}\n"
+                   end
+        end
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/aia/delegate_handler.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# lib/aia/delegate_handler.rb
+#
+# Lead robot analyzes a prompt, creates a TrakFlow plan with steps
+# assigned to specific robots, then each robot executes its tasks
+# in dependency order. Combines TypedBus, SharedMemory, and TrakFlow.
+#
+# Decomposition is delegated to TaskDecomposer.
+# Step execution is delegated to TaskExecutor.
+
+module AIA
+  class DelegateHandler
+    include ContentExtractor
+    include HandlerProtocol
+
+    def initialize(robot:, ui_presenter:, tracker:, task_coordinator:)
+      @robot            = robot
+      @ui_presenter     = ui_presenter
+      @tracker          = tracker
+      @task_coordinator = task_coordinator
+    end
+
+    attr_writer :robot
+
+    # Decompose a prompt into subtasks, assign to robots, and execute.
+    #
+    # @param context [HandlerContext] — reads context.prompt
+    # @return [String, nil] combined results, or nil if not applicable
+    # :reek:TooManyStatements -- three-step delegation pipeline (decompose, plan, execute) sharing intermediate results
+    def handle(context)
+      prompt = context.prompt
+      return nil unless @robot.network?
+      return nil unless @task_coordinator&.available?
+
+      robots      = @robot.robots
+      robot_names = robots.values.map(&:name)
+      lead        = robots.values.first
+
+      # Step 1: Decompose the work
+      decomposer = TaskDecomposer.new(lead_robot: lead, ui_presenter: @ui_presenter)
+      steps = decomposer.decompose(prompt, robot_names)
+
+      if steps.empty?
+        @ui_presenter.display_info("Could not decompose into subtasks.")
+        return nil
+      end
+
+      # Step 2: Create TrakFlow plan
+      plan = @task_coordinator.create_plan(
+        "Delegated: #{prompt[0, 60]}",
+        steps: steps, creator: lead.name, ephemeral: true
+      )
+
+      @ui_presenter.display_info("Plan with #{steps.size} tasks:")
+      steps.each_with_index do |s, i|
+        @ui_presenter.display_info("  #{i + 1}. #{s[:title]} -> #{s[:assignee]}")
+      end
+
+      # Step 3: Execute tasks in order
+      executor = TaskExecutor.new(task_coordinator: @task_coordinator)
+      results  = execute_steps(executor, prompt, plan, steps, robots)
+
+      @tracker.record_turn(
+        model: AIA.config.models.first.name,
+        input: prompt,
+        result: results
+      )
+
+      format_results(results)
+    end
+
+    private
+
+    # :reek:TooManyStatements -- per-step loop: resolve assignee, announce, execute, record to memory and results
+    def execute_steps(executor, prompt, plan, steps, robots)
+      results = []
+
+      plan[:steps].each_with_index do |task, i|
+        step_def = steps[i]
+        assignee = robots.values.find { |r| r.name == step_def[:assignee] }
+        assignee ||= robots.values.first
+        name  = assignee.name
+        title = step_def[:title]
+
+        @ui_presenter.display_info("  #{name}: #{title}...")
+
+        content = executor.execute(task, assignee, step_def, prompt, results)
+
+        write_to_memory(i, name, title, content)
+        results << { robot: name, task: title, content: content }
+      end
+
+      results
+    end
+
+    def write_to_memory(index, robot_name, task_title, content)
+      return unless @robot.respond_to?(:memory)
+
+      @robot.memory.current_writer = robot_name
+      @robot.memory.set(:"delegate_step_#{index}", {
+        robot: robot_name, task: task_title, content: content
+      })
+    end
+
+    def format_results(results)
+      lines = []
+      results.each_with_index do |r, i|
+        lines << "### Step #{i + 1}: #{r[:task]} (#{r[:robot]})"
+        lines << r[:content]
+        lines << ""
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/aia/directive.rb

@@ -34,9 +34,28 @@
 
 module AIA
   class Directive < PM::Directive
-    DIRECTIVE_PREFIX = '/'
+    DIRECTIVE_PREFIX = '/'.freeze
 
     class << self
+      # ---- State-setting DSL -----------------------------------------------
+      # Directives that mutate turn-state or set a mode flag (rather than
+      # returning text for the AI) should declare themselves here so that
+      # ChatLoop can ask the processor instead of hardcoding a name list.
+      #
+      # Usage (in a subclass body):
+      #   state_setting! :verify, :decompose, :concurrent, :conc
+      #
+      # The names must match the directive method names (without the / prefix).
+
+      def state_setting!(*method_names)
+        @state_setting_methods ||= []
+        @state_setting_methods.concat(method_names.map(&:to_s))
+      end
+
+      def state_setting_methods
+        @state_setting_methods || []
+      end
+
       # ---- Dispatch override ------------------------------------------------
       # AIA directive methods use (args_array, context_manager) convention,
       # not (ctx, *args). Override build_dispatch_block to adapt.
@@ -49,6 +68,7 @@ module AIA
       # Application-level concern: formats help text using DIRECTIVE_PREFIX
       # and all registered directive subclasses.
 
+      # :reek:TooManyStatements -- sequential terminal report: header, one section per directive category, footer
       def help
         puts
         puts "Available Directives"
@@ -65,14 +85,7 @@ module AIA
           puts "-" * cat.length
 
           klass.directive_descriptions.each do |method_name, description|
-            aliases    = klass.directive_aliases[method_name] || []
-            alias_text = if aliases.any?
-                           " (aliases: #{aliases.map { |a| "#{DIRECTIVE_PREFIX}#{a}" }.join(', ')})"
-                         else
-                           ""
-                         end
-
-            puts "  #{DIRECTIVE_PREFIX}#{method_name}#{alias_text}"
+            puts "  #{DIRECTIVE_PREFIX}#{method_name}#{alias_text_for(klass, method_name)}"
             puts "      #{description}"
             puts
 
@@ -83,31 +96,35 @@ module AIA
         puts "\nTotal: #{total} directives available"
         ""
       end
+
+      # Format the "(aliases: ...)" suffix for a directive, or "" when it has none.
+      def alias_text_for(klass, method_name)
+        aliases = klass.directive_aliases[method_name] || []
+        return "" if aliases.empty?
+
+        " (aliases: #{aliases.map { |a| "#{DIRECTIVE_PREFIX}#{a}" }.join(', ')})"
+      end
     end
 
     private
 
-    # Split args into positive and negative search terms.
-    # Tokens prefixed with -, ~, or ! are negative (exclusion) terms.
-    # All other tokens (bare or +-prefixed) are positive (inclusion) terms.
-    # All terms are downcased.
-    #
-    # @param args [Array<String>] raw argument tokens
-    # @return [Array<Array<String>>] [positive_terms, negative_terms]
+    # Split raw args into [positive_terms, negative_terms].
+    # Leading '+' is stripped; the term is treated as positive.
+    # Leading '-', '~', or '!' marks the term as negative (AND NOT).
+    # Bare terms are positive. All terms are lowercased.
     def parse_search_terms(args)
       positive = []
       negative = []
 
-      Array(args).each do |arg|
-        arg.split.each do |token|
-          downcased = token.downcase
-          if downcased =~ /\A[-~!]/
-            negative << downcased[1..]
-          elsif downcased.start_with?('+')
-            positive << downcased[1..]
-          else
-            positive << downcased
-          end
+      args.flat_map { |a| a.to_s.split }.each do |raw|
+        if raw.start_with?('+')
+          term = raw[1..].downcase
+          positive << term unless term.empty?
+        elsif raw.start_with?('-', '~', '!')
+          term = raw[1..].downcase
+          negative << term unless term.empty?
+        else
+          positive << raw.downcase
         end
       end
 

data/lib/aia/directive_processor.rb

@@ -2,7 +2,6 @@
 
 require 'faraday'
 require 'word_wrapper'
-require 'set'
 require_relative 'directive'
 require_relative 'directives/configuration_directives'
 require_relative 'directives/context_directives'
@@ -10,6 +9,7 @@ require_relative 'directives/execution_directives'
 require_relative 'directives/utility_directives'
 require_relative 'directives/web_and_file_directives'
 require_relative 'directives/model_directives'
+require_relative 'directives/trakflow_directives'
 
 module AIA
   class DirectiveProcessor
@@ -19,7 +19,6 @@ module AIA
       @prefix_size = DIRECTIVE_PREFIX.size
     end
 
-
     # Checks whether a string looks like a chat-time directive.
     # Uses PM.directives as the source of truth for known directive names.
     def directive?(string)
@@ -30,12 +29,21 @@ module AIA
 
       # Extract the directive name and check it's registered
       sans_prefix = stripped[@prefix_size..]
-      method_name = sans_prefix.split(' ').first&.downcase
+      method_name = sans_prefix.split.first&.downcase
       return false if method_name.nil? || method_name.empty?
 
       PM.directives.key?(method_name.to_sym)
     end
 
+    # Returns true when the directive mutates turn-state or sets a mode flag
+    # rather than returning text for the AI.  ChatLoop uses this to decide
+    # whether to skip forwarding the directive output to the robot.
+    def state_setting?(input)
+      name = extract_content(input).strip.split.first.to_s.delete_prefix('/')
+      AIA::Directive.subclasses.any? do |klass|
+        klass.state_setting_methods.include?(name)
+      end
+    end
 
     # Process a chat-time directive by dispatching through PM.directives.
     # Returns the block's return value: non-blank string for content directives,
@@ -46,7 +54,7 @@ module AIA
       content = extract_content(string)
       key = content.strip
       sans_prefix = key[@prefix_size..]
-      args = sans_prefix.split(' ')
+      args = sans_prefix.split
       method_name = args.shift.downcase
 
       block = PM.directives[method_name.to_sym]
@@ -58,7 +66,6 @@ module AIA
       block.call(render_context, *args)
     end
 
-
     private
 
     def render_context
@@ -67,17 +74,19 @@ module AIA
         params:    {},
         included:  Set.new,
         depth:     0,
-        metadata:  OpenStruct.new(includes: [])
+        metadata:  Struct.new(:includes).new([])
       )
     end
 
     def extract_content(string)
-      if string.is_a?(RubyLLM::Message)
+      if defined?(RubyLLM::Message) && string.is_a?(RubyLLM::Message)
         begin
           string.content
         rescue StandardError
           string.to_s
         end
+      elsif string.respond_to?(:content)
+        string.content.to_s
       else
         string.to_s
       end