aia 1.1.0 → 2.0.0.0.pre.alpha

data/lib/aia/tools/task_board_tool.rb

@@ -0,0 +1,114 @@
+# 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
+  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

data/lib/aia/trakflow_bridge.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# lib/aia/trakflow_bridge.rb
+#
+# Bridge between AIA and TrakFlow task tracking.
+# Uses the trak_flow gem directly as a Ruby library —
+# no MCP server or LLM intermediation needed.
+
+require "trak_flow"
+
+module AIA
+  class TrakFlowBridge
+    def initialize
+      @db = connect_database
+    end
+
+    # Whether a TrakFlow project is initialized and the database is accessible.
+    #
+    # @return [Boolean]
+    def available?
+      !@db.nil?
+    end
+
+    # Create a TrakFlow plan from a pipeline of prompt IDs.
+    # Each step blocks the next, enforcing sequential execution.
+    #
+    # @param pipeline [Array<String>] prompt IDs in pipeline order
+    # @return [String, nil] summary of created plan
+    def create_plan_from_pipeline(pipeline)
+      return nil unless available?
+
+      plan_title = "Pipeline: #{pipeline.join(' → ')}"
+      plan = TrakFlow::Models::Task.new(title: plan_title, plan: true, type: "task")
+      plan = @db.create_task(plan)
+
+      prev_step = nil
+      pipeline.each_with_index do |prompt_id, i|
+        step = @db.create_child_task(plan.id, {
+          title: "Step #{i + 1}: #{prompt_id}",
+          type:  "task"
+        })
+
+        if prev_step
+          @db.add_dependency(TrakFlow::Models::Dependency.new(
+                               source_id: prev_step.id,
+                               target_id: step.id,
+                               type:      "blocks"
+                             ))
+        end
+
+        prev_step = step
+      end
+
+      "Plan '#{plan_title}' created with #{pipeline.size} steps."
+    rescue StandardError => e
+      $stderr.puts "Warning: TrakFlow plan creation failed: #{e.message}"
+      nil
+    end
+
+    # Update a task's status in TrakFlow.
+    #
+    # @param step_name [String] task title to find
+    # @param status [Symbol] :started, :completed, or :failed
+    # @param reason [String, nil] reason for failure
+    def update_step_status(step_name, status, reason: nil)
+      return unless available?
+
+      task = find_task_by_title(step_name)
+      return unless task
+
+      case status
+      when :started
+        task.status = "in_progress"
+        @db.update_task(task)
+      when :completed
+        task.close!(reason: reason || "Completed")
+        @db.update_task(task)
+      when :failed
+        task.status = "blocked"
+        task.append_trace("blocked", reason) if reason
+        @db.update_task(task)
+      end
+    rescue StandardError => e
+      $stderr.puts "Warning: TrakFlow status update failed: #{e.message}"
+    end
+
+    # List ready tasks (tasks with no open blockers).
+    #
+    # @return [String, nil] formatted list of ready tasks
+    def check_ready_tasks
+      return nil unless available?
+
+      tasks = @db.ready_tasks
+      return nil if tasks.empty?
+
+      lines = tasks.map { |t| "  - [#{t.id}] #{t.title} (#{t.status})" }
+      "Ready tasks (#{tasks.size}):\n#{lines.join("\n")}"
+    rescue StandardError => e
+      $stderr.puts "Warning: TrakFlow ready tasks query failed: #{e.message}"
+      nil
+    end
+
+    # Get a summary of the current TrakFlow project state.
+    #
+    # @return [String, nil] project summary
+    def project_summary
+      return nil unless available?
+
+      all = @db.list_tasks({})
+      by_status = all.group_by(&:status)
+
+      lines = ["TrakFlow Project Summary (#{all.size} tasks):"]
+      by_status.sort.each do |status, tasks|
+        lines << "  #{status}: #{tasks.size}"
+      end
+
+      ready = @db.ready_tasks
+      lines << "  ready (unblocked): #{ready.size}" unless ready.empty?
+
+      lines.join("\n")
+    rescue StandardError => e
+      $stderr.puts "Warning: TrakFlow summary failed: #{e.message}"
+      nil
+    end
+
+    # Create a task in TrakFlow.
+    #
+    # @param title [String] task title
+    # @param description [String, nil] task description
+    # @param labels [Array<String>] labels to attach
+    # @return [String, nil] confirmation message
+    def create_task(title, description: nil, labels: [])
+      return nil unless available?
+
+      task = TrakFlow::Models::Task.new(
+        title:       title,
+        description: description,
+        type:        "task"
+      )
+      task = @db.create_task(task)
+
+      labels.each do |label_name|
+        @db.add_label(TrakFlow::Models::Label.new(task_id: task.id, name: label_name))
+      end
+
+      "Task created: [#{task.id}] #{title}"
+    rescue StandardError => e
+      $stderr.puts "Warning: TrakFlow task creation failed: #{e.message}"
+      nil
+    end
+
+    attr_reader :db
+
+    private
+
+    # Connect to the TrakFlow database if a project is initialized.
+    def connect_database
+      return nil unless TrakFlow.initialized?
+
+      db = TrakFlow::Storage::Database.new(TrakFlow.database_path)
+      db.connect
+      db
+    rescue StandardError
+      nil
+    end
+
+    # Find a task by its title (partial match).
+    def find_task_by_title(title)
+      tasks = @db.list_tasks(title: title)
+      tasks.first
+    end
+  end
+end

data/lib/aia/turn_state.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# lib/aia/turn_state.rb
+#
+# Request-scoped state object for inter-component signaling.
+# Replaces ad-hoc instance variable flags on AIA.config.
+#
+# Only one special mode may be requested per turn (mutual exclusion).
+# Use TurnState#request(mode, **opts) to enqueue a mode — this clears
+# all other force_* flags before setting the new one. Assigning the
+# attr_accessors directly bypasses mutual exclusion (for backward compat
+# and direct test assertions).
+
+module AIA
+  class TurnState
+    # Exclusive mode flags — only one may be active at a time via #request.
+    EXCLUSIVE_MODES = %i[
+      verify decompose concurrent_mcp debate delegate spawn orchestrate
+    ].freeze
+
+    attr_accessor :force_verify, :force_decompose, :force_concurrent_mcp,
+                  :force_debate, :force_delegate, :force_spawn, :spawn_type,
+                  :spawn_spec, :force_orchestrate, :active_mcp_servers
+
+    def initialize
+      clear!
+    end
+
+    # Request a special mode for this turn.
+    # Clears all other exclusive force_* flags before activating the new mode,
+    # enforcing mutual exclusion at the point of enqueue.
+    #
+    # @param mode [Symbol] one of EXCLUSIVE_MODES
+    # @param type [String, nil] specialist type (only relevant for :spawn)
+    # @raise [ArgumentError] if mode is not one of EXCLUSIVE_MODES
+    def request(mode, type: nil)
+      unless EXCLUSIVE_MODES.include?(mode)
+        raise ArgumentError, "Unknown TurnState mode: #{mode.inspect}. Valid: #{EXCLUSIVE_MODES.join(', ')}"
+      end
+
+      clear_exclusive_flags!
+
+      case mode
+      when :verify         then @force_verify = true
+      when :decompose      then @force_decompose = true
+      when :concurrent_mcp then @force_concurrent_mcp = true
+      when :debate         then @force_debate          = true
+      when :delegate       then @force_delegate        = true
+      when :spawn          then @force_spawn = true
+                                @spawn_type = type
+      when :orchestrate    then @force_orchestrate     = true
+      end
+    end
+
+    def clear!
+      @force_verify        = false
+      @force_decompose     = false
+      @force_concurrent_mcp = false
+      @force_debate        = false
+      @force_delegate      = false
+      @force_spawn         = false
+      @spawn_type          = nil
+      @spawn_spec          = nil
+      @force_orchestrate   = false
+      @active_mcp_servers  = nil
+    end
+
+    # Returns which exclusive mode is currently active, or nil if none.
+    def active_mode
+      return :verify         if @force_verify
+      return :decompose      if @force_decompose
+      return :concurrent_mcp if @force_concurrent_mcp
+      return :debate         if @force_debate
+      return :delegate       if @force_delegate
+      return :spawn          if @force_spawn
+      return :orchestrate    if @force_orchestrate
+      nil
+    end
+
+    private
+
+    def clear_exclusive_flags!
+      @force_verify         = false
+      @force_decompose      = false
+      @force_concurrent_mcp = false
+      @force_debate         = false
+      @force_delegate       = false
+      @force_spawn          = false
+      @spawn_type           = nil
+      @spawn_spec           = nil
+      @force_orchestrate    = false
+    end
+  end
+end