brute_flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 214695b96e9f5c22e58314e6028e4068ee0c4fc093ef0ee0c6e4905d8375cebd
+  data.tar.gz: 411ff39327de393a5ead111eb57a089b846ab50a6ae1dbe2ee3d3106fff9a3c5
+SHA512:
+  metadata.gz: b4a3c48b9aed668ba2602735899cedc3992808e44ed87cb7ad8392952ce75c929d88f7ebf21fa04f3f0a04c667b4b89cf45c1426e86ec006f5035120962a6da9
+  data.tar.gz: d3361873ca16e7bc97119979f0ffb2b5698592b9379a231b8f73e4c64839c0f87a17b578233f6563d4cf4540ee5de3a7e6c6948c23dc9b076db5fdc14a95869c

data/lib/brute_flow/builder.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Brute
+  module Flow
+    # Builds BPMN::Definitions directly from a Ruby DSL — no XML involved.
+    #
+    # Usage:
+    #   defs = Builder.build("my_flow") do
+    #     service :router, type: "Brute::Flow::Services::RouterService"
+    #     exclusive_gateway :mode, default: :simple_path do
+    #       branch :fibre_path, condition: '=agent_mode = "fibre"' do
+    #         parallel do
+    #           service :tools,  type: "Brute::Flow::Services::ToolSuggestService"
+    #           service :memory, type: "Brute::Flow::Services::MemoryRecallService"
+    #         end
+    #         service :agent, type: "Brute::Flow::Services::AgentService"
+    #       end
+    #       branch :simple_path do
+    #         service :agent, type: "Brute::Flow::Services::AgentService"
+    #       end
+    #     end
+    #     loop_while '=self_check_passed = false', max: 3, timeout: "PT5M" do
+    #       service :check, type: "Brute::Flow::Services::SelfCheckService"
+    #     end
+    #   end
+    #
+    class Builder
+      def self.build(process_id = "brute_flow", &block)
+        new(process_id).tap { |b| b.instance_eval(&block) }.finalize
+      end
+
+      def initialize(process_id)
+        @process_id = process_id
+        @counter = 0
+        # Collect raw hashes by BPMN type
+        @start_events = []
+        @end_events = []
+        @service_tasks = []
+        @exclusive_gateways = []
+        @parallel_gateways = []
+        @boundary_events = []
+        @sub_processes = []
+        @sequence_flows = []
+        # Ordered list of element ids representing the top-level sequence
+        @sequence = []
+      end
+
+      # -- DSL methods --
+
+      def service(id, type:, headers: {})
+        task_id = uid(id)
+        header_arr = headers.map { |k, v| { key: k.to_s, value: v.to_s } }
+        ext = {}
+        ext[:task_definition] = { type: type }
+        ext[:task_headers] = { header: header_arr } unless header_arr.empty?
+
+        @service_tasks << {
+          id: task_id,
+          name: id.to_s,
+          extension_elements: ext,
+        }
+        @sequence << task_id
+        task_id
+      end
+
+      def exclusive_gateway(id, default: nil, &block)
+        split_id = uid(:"#{id}_split")
+        join_id = uid(:"#{id}_join")
+        default_branch_id = default
+
+        ctx = GatewayContext.new(self)
+        ctx.instance_eval(&block)
+        branches = ctx.branches
+
+        # Add split gateway
+        default_flow_id = nil
+        @exclusive_gateways << { id: split_id, name: "#{id}_split" }
+        @sequence << split_id
+
+        # Each branch: split → [branch elements] → join
+        branches.each do |br|
+          flow_id = uid(:"flow_#{br[:id]}")
+          flow = { id: flow_id, source_ref: split_id, target_ref: br[:elements].first }
+          flow[:condition_expression] = br[:condition] if br[:condition]
+          @sequence_flows << flow
+
+          if br[:id].to_s == default_branch_id.to_s
+            default_flow_id = flow_id
+          end
+
+          # Chain branch elements internally
+          br[:elements].each_cons(2) do |from, to|
+            @sequence_flows << { id: uid(:flow), source_ref: from, target_ref: to }
+          end
+
+          # Last branch element → join
+          @sequence_flows << { id: uid(:flow), source_ref: br[:elements].last, target_ref: join_id }
+        end
+
+        # Set default on split gateway
+        @exclusive_gateways.last[:default] = default_flow_id if default_flow_id
+
+        # Add join gateway
+        @exclusive_gateways << { id: join_id, name: "#{id}_join" }
+        @sequence << join_id
+      end
+
+      def parallel(&block)
+        fork_id = uid(:parallel_fork)
+        join_id = uid(:parallel_join)
+
+        ctx = ParallelContext.new(self)
+        ctx.instance_eval(&block)
+        branches = ctx.branches
+
+        @parallel_gateways << { id: fork_id, name: "parallel_fork" }
+        @sequence << fork_id
+
+        branches.each do |br|
+          # fork → branch elements → join
+          @sequence_flows << { id: uid(:flow), source_ref: fork_id, target_ref: br.first }
+          br.each_cons(2) do |from, to|
+            @sequence_flows << { id: uid(:flow), source_ref: from, target_ref: to }
+          end
+          @sequence_flows << { id: uid(:flow), source_ref: br.last, target_ref: join_id }
+        end
+
+        @parallel_gateways << { id: join_id, name: "parallel_join" }
+        @sequence << join_id
+      end
+
+      def loop_while(condition, max: 3, timeout: nil, &block)
+        # Build the loop body into a subprocess
+        sub_id = uid(:loop_sub)
+        inner = Builder.new(sub_id)
+        inner.instance_eval(&block)
+
+        # The loop gate: after the subprocess, check condition to loop back
+        gate_id = uid(:loop_gate)
+        back_flow_id = uid(:loop_back)
+        exit_flow_id = uid(:loop_exit)
+
+        # Counter variable for max iterations
+        counter_var = "_loop_#{@counter}_count"
+        # FEEL condition: original condition AND counter < max
+        guarded = "=#{strip_feel(condition)} and #{counter_var} < #{max}"
+
+        # Add subprocess hash (it's a Process-like thing)
+        sub_process_hash = inner.to_sub_process_hash(sub_id)
+        @sub_processes << sub_process_hash
+        @sequence << sub_id
+
+        # Add gate after subprocess
+        @exclusive_gateways << { id: gate_id, name: "loop_gate", default: exit_flow_id }
+        @sequence << gate_id
+
+        # Back-edge: gate → subprocess (with condition)
+        @sequence_flows << { id: back_flow_id, source_ref: gate_id, target_ref: sub_id, condition_expression: guarded }
+        # Exit edge: gate → (whatever comes next, wired in finalize)
+        # We store exit_flow_id so the next element connects from here
+        @loop_exit_flow = exit_flow_id
+
+        # Timeout boundary event on the subprocess
+        if timeout
+          boundary_id = uid(:loop_timeout)
+          @boundary_events << {
+            id: boundary_id,
+            name: "loop_timeout",
+            attached_to_ref: sub_id,
+            cancel_activity: "true",
+            timer_event_definition: { time_duration: timeout },
+          }
+        end
+      end
+
+      # -- Internal: used by GatewayContext / ParallelContext --
+
+      def _build_branch(&block)
+        saved_sequence = @sequence
+        @sequence = []
+        instance_eval(&block)
+        branch_elements = @sequence
+        @sequence = saved_sequence
+        branch_elements
+      end
+
+      def uid(prefix = :el)
+        @counter += 1
+        "#{prefix}_#{@counter}"
+      end
+
+      # -- Finalize: assemble into BPMN::Definitions --
+
+      def finalize
+        start_id = uid(:start)
+        end_id = uid(:end)
+
+        @start_events << { id: start_id, name: "Start" }
+        @end_events << { id: end_id, name: "End" }
+
+        # Build the main sequence: start → elements → end
+        all = [start_id] + @sequence + [end_id]
+        all.each_cons(2) do |from, to|
+          # Skip if there's already a flow from `from` (gateways wire their own)
+          next if @sequence_flows.any? { |f| f[:source_ref] == from }
+          # For loop exit flows
+          if @loop_exit_flow && @sequence_flows.none? { |f| f[:id] == @loop_exit_flow }
+            @sequence_flows << { id: @loop_exit_flow, source_ref: from, target_ref: to }
+            @loop_exit_flow = nil
+            next
+          end
+          @sequence_flows << { id: uid(:flow), source_ref: from, target_ref: to }
+        end
+
+        # Build incoming/outgoing arrays for each element
+        incoming = Hash.new { |h, k| h[k] = [] }
+        outgoing = Hash.new { |h, k| h[k] = [] }
+        @sequence_flows.each do |f|
+          outgoing[f[:source_ref]] << f[:id]
+          incoming[f[:target_ref]] << f[:id]
+        end
+
+        # Attach incoming/outgoing to all elements
+        all_elements = @start_events + @end_events + @service_tasks +
+                       @exclusive_gateways + @parallel_gateways + @sub_processes
+        all_elements.each do |el|
+          el[:incoming] = incoming[el[:id]] unless incoming[el[:id]].empty?
+          el[:outgoing] = outgoing[el[:id]] unless outgoing[el[:id]].empty?
+        end
+
+        process_hash = {
+          id: @process_id,
+          name: @process_id,
+          is_executable: "true",
+          start_event: @start_events,
+          end_event: @end_events,
+          service_task: @service_tasks,
+          exclusive_gateway: @exclusive_gateways,
+          parallel_gateway: @parallel_gateways,
+          sub_process: @sub_processes,
+          boundary_event: @boundary_events,
+          sequence_flow: @sequence_flows,
+        }
+
+        defs = BPMN::Definitions.new(process: [process_hash])
+        defs.processes.each { |p| p.wire_references(defs) }
+        defs
+      end
+
+      # Build a sub-process hash from the current builder state (for loop bodies).
+      def to_sub_process_hash(id)
+        start_id = uid(:sub_start)
+        end_id = uid(:sub_end)
+
+        sub_start = [{ id: start_id, name: "SubStart" }]
+        sub_end = [{ id: end_id, name: "SubEnd" }]
+
+        all = [start_id] + @sequence + [end_id]
+        all.each_cons(2) do |from, to|
+          next if @sequence_flows.any? { |f| f[:source_ref] == from }
+          @sequence_flows << { id: uid(:flow), source_ref: from, target_ref: to }
+        end
+
+        incoming = Hash.new { |h, k| h[k] = [] }
+        outgoing = Hash.new { |h, k| h[k] = [] }
+        @sequence_flows.each do |f|
+          outgoing[f[:source_ref]] << f[:id]
+          incoming[f[:target_ref]] << f[:id]
+        end
+
+        all_els = sub_start + sub_end + @service_tasks + @exclusive_gateways +
+                  @parallel_gateways + @sub_processes
+        all_els.each do |el|
+          el[:incoming] = incoming[el[:id]] unless incoming[el[:id]].empty?
+          el[:outgoing] = outgoing[el[:id]] unless outgoing[el[:id]].empty?
+        end
+
+        {
+          id: id,
+          name: id,
+          start_event: sub_start,
+          end_event: sub_end,
+          service_task: @service_tasks,
+          exclusive_gateway: @exclusive_gateways,
+          parallel_gateway: @parallel_gateways,
+          sequence_flow: @sequence_flows,
+        }
+      end
+
+      private
+
+      def strip_feel(expr)
+        expr.to_s.delete_prefix("=")
+      end
+
+      # -- Context objects for gateway/parallel DSL blocks --
+
+      class GatewayContext
+        attr_reader :branches
+
+        def initialize(builder)
+          @builder = builder
+          @branches = []
+        end
+
+        def branch(id, condition: nil, &block)
+          elements = @builder._build_branch(&block)
+          @branches << { id: id, condition: condition, elements: elements }
+        end
+      end
+
+      class ParallelContext
+        attr_reader :branches
+
+        def initialize(builder)
+          @builder = builder
+          @branches = []
+        end
+
+        def service(id, type:, headers: {})
+          # Single-element branch
+          task_id = @builder.service(id, type: type, headers: headers)
+          # Pop it from the main sequence (we manage our own)
+          @builder.instance_variable_get(:@sequence).pop
+          @branches << [task_id]
+        end
+
+        def branch(&block)
+          elements = @builder._build_branch(&block)
+          @branches << elements
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow/runner.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/barrier"
+
+module Brute
+  module Flow
+    # Async-native BPMN execution runner.
+    #
+    # Takes a BPMN::Definitions (built by Builder), starts the process,
+    # and drives automated ServiceTasks to completion — running parallel
+    # branches concurrently via Async::Barrier.
+    #
+    # WorkflowKit's engine is synchronous by design: ServiceTask#run is
+    # called inline and ParallelGateway branches execute sequentially.
+    # We monkey-patch ServiceTask#run to be a no-op and handle execution
+    # ourselves, giving us true async parallelism.
+    #
+    class Runner
+      attr_reader :execution, :context
+
+      def initialize(definitions, cwd: Dir.pwd, variables: {})
+        @definitions = definitions
+        @cwd = cwd
+        @initial_variables = variables.merge(cwd: cwd)
+        @context = nil
+        @execution = nil
+      end
+
+      # Execute the flow to completion. Blocks until done.
+      # Returns the final variables hash.
+      def run
+        @context = BPMN::Context.new([], processes: @definitions.processes)
+        @execution = @context.start(variables: @initial_variables)
+
+        Async do
+          run_loop
+        end
+
+        @execution.variables
+      end
+
+      # Serialize execution state for session persistence.
+      def serialize
+        @execution&.serialize
+      end
+
+      # Restore from serialized state.
+      def restore(state)
+        @context = BPMN::Context.new([], processes: @definitions.processes)
+        @execution = @context.restore(state)
+      end
+
+      # Final output variables.
+      def variables
+        @execution&.variables || {}
+      end
+
+      private
+
+      def run_loop
+        loop do
+          # Check expired timers (for loop timeouts)
+          @execution.check_expired_timers if @execution.respond_to?(:check_expired_timers)
+
+          # Find all waiting automated (ServiceTask) executions
+          waiting = find_waiting_automated(@execution)
+          break if waiting.empty?
+
+          # Group by whether they share a parallel gateway parent
+          # (i.e., sibling branches that should run concurrently)
+          groups = group_by_parallel_parent(waiting)
+
+          groups.each do |_parent_id, tasks|
+            if tasks.size > 1
+              run_parallel(tasks)
+            else
+              run_single(tasks.first)
+            end
+          end
+        end
+      end
+
+      def run_parallel(tasks)
+        barrier = Async::Barrier.new
+        results = {}
+
+        tasks.each do |exec|
+          barrier.async do
+            results[exec] = run_service(exec)
+          end
+        end
+
+        barrier.wait
+      ensure
+        barrier&.stop
+
+        # Signal each execution with its result
+        results.each do |exec, result|
+          signal_with_result(exec, result)
+        end
+      end
+
+      def run_single(exec)
+        result = run_service(exec)
+        signal_with_result(exec, result)
+      end
+
+      def run_service(exec)
+        step = exec.step
+        return nil unless step.respond_to?(:task_type) && step.task_type
+
+        klass = step.task_type.constantize
+        vars = exec.parent&.variables || {}
+        hdrs = step.respond_to?(:headers) ? (step.headers || {}) : {}
+
+        klass.new.call(vars, hdrs)
+      rescue => e
+        { error: true, message: e.message, class: e.class.name }
+      end
+
+      def signal_with_result(exec, result)
+        return unless exec.waiting?
+        exec.signal(result)
+      rescue => e
+        warn "[brute/flow] Signal failed for #{exec.step&.id}: #{e.message}"
+      end
+
+      # Recursively find all waiting executions whose step is an automated task.
+      def find_waiting_automated(execution)
+        found = []
+        return found unless execution.respond_to?(:children)
+
+        execution.children.each do |child|
+          if child.waiting? && child.step.respond_to?(:is_automated?) && child.step.is_automated?
+            found << child
+          end
+          # Recurse into sub-process children
+          found.concat(find_waiting_automated(child))
+        end
+
+        found
+      end
+
+      # Group waiting tasks by their parent execution id.
+      # Tasks sharing the same parent after a ParallelGateway fork
+      # are siblings that should run concurrently.
+      def group_by_parallel_parent(tasks)
+        tasks.group_by { |t| t.parent&.object_id || :root }
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Monkey-patch: make ServiceTask#run a no-op.
+    #
+    # WorkflowKit's ServiceTask#run calls task_type.constantize.new.call()
+    # synchronously. We override it so the engine only puts the task into
+    # `waiting` state. Our Runner then picks up waiting tasks and runs
+    # them with async parallelism.
+    # ----------------------------------------------------------------
+    module ServiceTaskAsyncPatch
+      def run(execution)
+        # No-op: Runner handles execution externally.
+        # The task is already in `waiting` state from execute().
+        nil
+      end
+    end
+  end
+end
+
+# Apply the monkey-patch
+BPMN::ServiceTask.prepend(Brute::Flow::ServiceTaskAsyncPatch)

data/lib/brute_flow/services/agent_service.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Brute
+  module Flow
+    module Services
+      # Runs a full Brute::Orchestrator for the user's message.
+      # This is the core service — it invokes the coding agent with
+      # all tools, middleware, retry, compaction, etc.
+      class AgentService
+        def call(variables, headers)
+          cwd = variables[:cwd] || variables["cwd"] || Dir.pwd
+          message = variables[:user_message] || variables["user_message"]
+          tools_filter = variables[:suggested_tools] || variables["suggested_tools"]
+          context_files = variables[:relevant_files] || variables["relevant_files"]
+
+          # Build enriched prompt with context from upstream services
+          prompt = message.dup
+          if context_files.is_a?(Array) && !context_files.empty?
+            prompt = "Relevant files:\n#{context_files.map { |f| "- #{f}" }.join("\n")}\n\n#{prompt}"
+          end
+
+          orch = Brute.agent(cwd: cwd)
+          response = orch.run(prompt)
+
+          { agent_result: response&.content }
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow/services/memory_recall_service.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Brute
+  module Flow
+    module Services
+      # Searches the workspace for files relevant to the task.
+      # Uses ripgrep to find matches. No LLM call.
+      class MemoryRecallService
+        MAX_FILES = 20
+        MAX_SNIPPET = 200
+
+        def call(variables, _headers)
+          cwd = variables[:cwd] || variables["cwd"] || Dir.pwd
+          task = variables[:user_message] || variables["user_message"] || ""
+
+          # Extract keywords: words > 3 chars, skip common stop words
+          keywords = extract_keywords(task)
+          return { relevant_files: [] } if keywords.empty?
+
+          files = {}
+          keywords.first(5).each do |kw|
+            search_keyword(kw, cwd).each do |path, snippet|
+              files[path] ||= snippet
+            end
+            break if files.size >= MAX_FILES
+          end
+
+          { relevant_files: files.keys.first(MAX_FILES) }
+        end
+
+        private
+
+        STOP_WORDS = %w[
+          the and for that this with from are was were been have has
+          had not but all can will just more some than them into also
+          make like over such after first well back even give most
+          file files code should would could please help want need use
+        ].to_set.freeze
+
+        def extract_keywords(text)
+          text.scan(/\b[a-zA-Z_]\w{2,}\b/)
+              .map(&:downcase)
+              .reject { |w| STOP_WORDS.include?(w) }
+              .tally
+              .sort_by { |_, count| -count }
+              .map(&:first)
+        end
+
+        def search_keyword(keyword, cwd)
+          cmd = ["rg", "--line-number", "--max-count=3", "--max-columns=200",
+                 "--ignore-case", "--no-heading", keyword, cwd]
+          stdout, _, status = Open3.capture3(*cmd)
+          return [] unless status.success?
+
+          results = []
+          stdout.lines.first(10).each do |line|
+            if line =~ /\A(.+?):(\d+):(.*)/
+              path = Regexp.last_match(1)
+              snippet = Regexp.last_match(3).strip[0...MAX_SNIPPET]
+              results << [path, snippet]
+            end
+          end
+          results
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow/services/router_service.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Brute
+  module Flow
+    module Services
+      # Classifies the incoming task and decides the execution mode.
+      # Single LLM call, no tools. Returns { agent_mode: "simple"|"fibre" }.
+      class RouterService
+        PROMPT = <<~PROMPT
+          Classify this software engineering task into one of two modes:
+
+          - "simple": Straightforward tasks that one agent can handle linearly.
+            Examples: fix a bug, add a function, rename a variable, run tests.
+
+          - "fibre": Complex tasks requiring parallel research, multi-file changes,
+            or analysis from multiple angles before acting.
+            Examples: large refactors, new feature across many files, architecture review.
+
+          Return ONLY a JSON object: {"agent_mode": "simple"} or {"agent_mode": "fibre"}
+
+          Task: %<task>s
+        PROMPT
+
+        def call(variables, _headers)
+          task = variables[:user_message] || variables["user_message"]
+          prompt = format(PROMPT, task: task)
+
+          begin
+            response = Brute.provider.complete(prompt)
+            parsed = JSON.parse(response.content)
+            { agent_mode: parsed["agent_mode"] || "simple" }
+          rescue => e
+            warn "[brute/flow/router] Classification failed (#{e.message}), defaulting to simple"
+            { agent_mode: "simple" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow/services/self_check_service.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Brute
+  module Flow
+    module Services
+      # Deterministic post-execution validation. No LLM call.
+      # Checks that output files exist and have valid syntax.
+      # Returns { self_check_passed: bool, self_check_errors: [...] }
+      class SelfCheckService
+        SYNTAX_CHECKERS = {
+          ".rb"   => ->(path) { check_cmd("ruby -c #{path.shellescape}") },
+          ".json" => ->(path) { check_json(path) },
+          ".yml"  => ->(path) { check_yaml(path) },
+          ".yaml" => ->(path) { check_yaml(path) },
+        }.freeze
+
+        def call(variables, _headers)
+          cwd = variables[:cwd] || variables["cwd"] || Dir.pwd
+          result = variables[:agent_result] || variables["agent_result"] || ""
+          errors = []
+
+          # Increment loop counter
+          counter_key = variables.keys.find { |k| k.to_s.start_with?("_loop_") && k.to_s.end_with?("_count") }
+          if counter_key
+            variables[counter_key] = (variables[counter_key] || 0).to_i + 1
+          end
+
+          # Extract file paths mentioned in agent output
+          paths = result.to_s.scan(%r{(?:^|\s)((?:/|\.{1,2}/)\S+\.\w+)}).flatten.uniq
+          paths.each do |rel_path|
+            full = File.expand_path(rel_path, cwd)
+            unless File.exist?(full)
+              errors << "File not found: #{rel_path}"
+              next
+            end
+
+            ext = File.extname(full).downcase
+            checker = SYNTAX_CHECKERS[ext]
+            next unless checker
+
+            err = checker.call(full)
+            errors << "#{rel_path}: #{err}" if err
+          end
+
+          { self_check_passed: errors.empty?, self_check_errors: errors }
+        end
+
+        private
+
+        def self.check_cmd(cmd)
+          _out, err, status = Open3.capture3(cmd)
+          status.success? ? nil : err.lines.first&.strip
+        end
+
+        def self.check_json(path)
+          JSON.parse(File.read(path))
+          nil
+        rescue JSON::ParserError => e
+          e.message.lines.first&.strip
+        end
+
+        def self.check_yaml(path)
+          YAML.safe_load(File.read(path))
+          nil
+        rescue Psych::SyntaxError => e
+          e.message.lines.first&.strip
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow/services/tool_suggest_service.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Brute
+  module Flow
+    module Services
+      # Pre-filters the available tool set to the most relevant subset
+      # for the given task. Single LLM call, no tools.
+      class ToolSuggestService
+        TOOL_NAMES = %w[read write patch remove fs_search undo shell fetch todo_write todo_read delegate].freeze
+
+        PROMPT = <<~PROMPT
+          Given this software engineering task, which of these tools are most likely needed?
+
+          Available tools: %<tools>s
+
+          Task: %<task>s
+
+          Return ONLY a JSON array of tool names, e.g. ["read", "shell", "patch"]
+        PROMPT
+
+        def call(variables, _headers)
+          task = variables[:user_message] || variables["user_message"]
+          prompt = format(PROMPT, tools: TOOL_NAMES.join(", "), task: task)
+
+          begin
+            response = Brute.provider.complete(prompt)
+            parsed = JSON.parse(response.content)
+            { suggested_tools: Array(parsed) & TOOL_NAMES }
+          rescue => e
+            warn "[brute/flow/tool_suggest] Failed (#{e.message}), returning all tools"
+            { suggested_tools: TOOL_NAMES }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brute_flow.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "brute"
+require "bpmn"
+require "active_support/core_ext/time/zones"
+
+# Ensure a time zone is set for WorkflowKit.
+Time.zone ||= "UTC"
+
+module Brute
+  module Flow
+    module Services; end
+  end
+end
+
+require_relative "brute_flow/builder"
+require_relative "brute_flow/runner"
+require_relative "brute_flow/services/agent_service"
+require_relative "brute_flow/services/router_service"
+require_relative "brute_flow/services/self_check_service"
+require_relative "brute_flow/services/tool_suggest_service"
+require_relative "brute_flow/services/memory_recall_service"
+
+module Brute
+  # Create a BPMN-driven multi-agent flow.
+  #
+  #   runner = Brute.flow(cwd: "/project", variables: { user_message: msg }) do
+  #     service :router, type: "Brute::Flow::Services::RouterService"
+  #     service :agent,  type: "Brute::Flow::Services::AgentService"
+  #   end
+  #   result = runner.run
+  #
+  def self.flow(cwd: Dir.pwd, variables: {}, &block)
+    definitions = Flow::Builder.build("brute_flow", &block)
+    Flow::Runner.new(definitions, cwd: cwd, variables: variables)
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: brute_flow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brute Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: brute
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: bpmn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+description: Extends the brute gem with a declarative BPMN workflow engine for multi-agent
+  orchestration — parallel branches, conditional routing, loops with timeouts, and
+  pluggable service tasks.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/brute_flow.rb
+- lib/brute_flow/builder.rb
+- lib/brute_flow/runner.rb
+- lib/brute_flow/services/agent_service.rb
+- lib/brute_flow/services/memory_recall_service.rb
+- lib/brute_flow/services/router_service.rb
+- lib/brute_flow/services/self_check_service.rb
+- lib/brute_flow/services/tool_suggest_service.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: BPMN-based multi-agent flow engine for Brute
+test_files: []