agent-council 0.1.0

data/lib/agent_council/pi_models.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module AgentCouncil
+  # Reads and formats the models available to pi.
+  module PiModels
+    FIELD_NAMES = {
+      provider:       'provider',
+      id:             'id',
+      name:           'name',
+      api:            'api',
+      reasoning:      'reasoning',
+      context_window: 'contextWindow',
+      max_tokens:     'maxTokens',
+    }.freeze
+
+    Model = Data.define(*FIELD_NAMES.keys) do
+      def self.from_hash(raw)
+        missing = FIELD_NAMES.values - raw.keys
+        raise ArgumentError, "missing model field(s): #{missing.join(', ')}" unless missing.empty?
+
+        new(**FIELD_NAMES.to_h { |member, field| [member, raw[field]] })
+      end
+
+      # Keep pi's JSON field names in --json output while exposing Ruby-style
+      # accessors to callers.
+      def to_h
+        FIELD_NAMES.to_h { |member, field| [field, public_send(member)] }
+      end
+    end
+
+    # Raised for failures talking to pi (missing executable, early exit, RPC error).
+    class Error < RuntimeError; end
+
+    RPC_GET_MODELS = { 'type' => 'get_available_models' }.freeze
+    RPC_REQUEST_ID = 'list-models'
+
+    module_function def fetch_models
+      Open3.popen3('pi', '--mode', 'rpc', '--no-session') do |stdin, stdout, stderr, wait_thr|
+        # pi's output is UTF-8, whatever the locale.
+        [stdout, stderr].each { |io| io.set_encoding(Encoding::UTF_8) }
+        # Drain stderr concurrently so a chatty pi can't block on a full pipe,
+        # and so we can report it if pi fails.
+        # An I/O failure while reading is treated as "no diagnostics" so it
+        # can't escape as something other than PiModels::Error.
+        stderr_reader = Thread.new do
+          stderr.read
+        rescue IOError, SystemCallError
+          ''
+        end
+        begin
+          send_rpc_command(stdin, RPC_GET_MODELS.merge('id' => RPC_REQUEST_ID))
+        rescue Errno::EPIPE, IOError
+          # pi exited (or closed stdin) before we could send the request; fall
+          # through so the exit-status/diagnostics check below explains why.
+        end
+
+        # No chomp: true: JRuby rejects it on a blockless each_line, and
+        # JSON.parse ignores the newline anyway.
+        events = stdout.each_line.lazy.filter_map { |line| parse_event(line) }
+        response = events.detect { |event| event['id'] == RPC_REQUEST_ID && event['type'] == 'response' }
+        return event_to_models(response) if response
+
+        diagnostics = stderr_reader.value.to_s.strip
+        message = "pi exited (#{describe_status(wait_thr.value)}) before responding"
+        message += ": #{diagnostics}" unless diagnostics.empty?
+        raise Error, message
+      ensure
+        stderr_reader&.kill
+      end
+    rescue Errno::ENOENT
+      raise Error, 'pi executable not found; is `pi` installed and on your PATH?'
+    rescue SystemCallError => e
+      # Covers EACCES (not executable) and other spawn-time failures that
+      # Errno::ENOENT doesn't catch.
+      raise Error, "pi could not be started: #{e.message}"
+    end
+
+    # Describes a Process::Status for diagnostics, covering both normal exits
+    # and termination by signal (where #exitstatus is nil).
+    module_function def describe_status(status)
+      return "signal #{status.termsig}" if status.signaled?
+
+      status.exitstatus.to_s
+    end
+
+    # Returns the parsed event, or nil for lines that aren't JSON objects
+    # (blank lines, stray non-protocol output).
+    module_function def parse_event(line)
+      event = JSON.parse(line)
+      event if event.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+
+    module_function def send_rpc_command(stdin, command)
+      stdin.sync = true
+      stdin.puts(JSON.generate(command))
+      stdin.close
+    end
+
+    module_function def event_to_models(event)
+      raise Error, "pi error: #{event['error']}" unless event['success']
+
+      raw_models = event.dig('data', 'models')
+      raise Error, "pi response missing data.models: #{event.inspect}" unless raw_models.is_a?(Array)
+
+      raw_models.map do |raw_model|
+        Model.from_hash(raw_model)
+      rescue ArgumentError => e
+        raise Error, "pi returned a malformed model: #{e.message}"
+      end
+    end
+
+    module_function def help_text
+      <<~HELP
+        Usage: pi-models [options]
+
+        List provider/model pairs available to `pi`.
+
+        Options:
+          -t, --table     Formatted table (default)
+          -j, --json      Pretty-printed JSON array of model hashes, with pi's fields:
+                          #{FIELD_NAMES.values.join(', ')}
+          -i, --ids       One "provider/id" per line (shell-friendly)
+          -h, --help      Show this help and exit
+
+        Examples:
+          pi-models
+          pi-models --json | jq '.[0]'
+          pi-models --ids | head -5
+          pi-models --table            # explicit default
+      HELP
+    end
+
+    module_function def format_as_table(models)
+      return "No models configured. Run `pi` interactively and add a provider first.\n" if models.empty?
+
+      columns = [
+        { label: 'PROVIDER',   value: ->(model) { model.provider.to_s },              align: :left  },
+        { label: 'MODEL ID',   value: ->(model) { model.id.to_s },                    align: :left  },
+        { label: 'API',        value: ->(model) { model.api.to_s },                   align: :left  },
+        { label: 'REASONING',  value: ->(model) { model.reasoning ? 'yes' : 'no' }, align: :left  },
+        { label: 'CONTEXT',    value: ->(model) { model.context_window.to_s },      align: :right },
+        { label: 'MAX TOKENS', value: ->(model) { model.max_tokens.to_s },          align: :right },
+        { label: 'NAME',       value: ->(model) { model.name.to_s },                  align: :left  },
+      ]
+
+      widths = columns.map do |column|
+        max_value_length = models.map { |model| column[:value].(model).length }.max
+        [max_value_length, column[:label].length].max
+      end
+
+      last_index = columns.length - 1
+      format_string = columns.each_with_index.map do |column, index|
+        # Don't pad the final left-aligned column; it would only add trailing whitespace.
+        next '%s' if index == last_index && column[:align] == :left
+
+        align_sign = column[:align] == :right ? '' : '-'
+        "%#{align_sign}#{widths[index]}s"
+      end.join('  ') + "\n"
+
+      separator = widths.map { |width| '-' * width }.join('  ') + "\n"
+      header = format(format_string, *columns.map { |column| column[:label] })
+      body_lines = models.map do |model|
+        format(format_string, *columns.map do |column|
+          column[:value].(model)
+        end)
+      end
+
+      separator + header + separator + body_lines.join + separator
+    end
+
+    module_function def format_as_json(models)
+      JSON.pretty_generate(models.map(&:to_h)) + "\n"
+    end
+
+    # Empty for an empty list, so shell loops and `wc -l` see no models.
+    module_function def format_as_ids(models)
+      models.map { |model| "#{model.provider}/#{model.id}\n" }.join
+    end
+  end
+end

data/lib/agent_council/platform.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Kept free of other project requires so both executables can load it:
+# pi-models doesn't load lib/agent_council.rb.
+
+require 'rbconfig'
+
+module AgentCouncil
+  # host_os rather than RUBY_PLATFORM, which is "java" on JRuby whatever the
+  # OS, and rather than Gem.win_platform?, so as not to depend on RubyGems.
+  module_function def windows?
+    /mswin|mingw/.match?(RbConfig::CONFIG['host_os'])
+  end
+
+  # Native Windows is unsupported; WSL works as Linux does. Ruby runs npm's
+  # pi.cmd through cmd.exe, which truncates arguments at newlines (breaking
+  # the multi-line system prompt), and WorkerPool relies on process groups
+  # and SIGTERM.
+  module_function def abort_if_native_windows(command = 'agent-council')
+    return unless windows?
+
+    abort <<~MESSAGE
+      #{command} does not support native Windows; please run it inside WSL.
+      See "Prerequisites" in #{File.expand_path('../../README.md', __dir__)}
+    MESSAGE
+  end
+end

data/lib/agent_council/templates/analyst_format.md

@@ -0,0 +1,12 @@
+# Report format
+
+Your response will be saved as a standalone Markdown report. A metadata
+table (role, agent, query, harness, provider, model, timestamp, duration)
+is prepended to it
+automatically, so:
+
+- Do not add a document title or any top-level (`#`) heading.
+- Begin directly with your first `##` section heading.
+- Use Markdown throughout: headings, lists, and fenced code blocks with
+  language tags.
+- Keep file paths and line references concrete and exact.

data/lib/agent_council/templates/consolidate_prompt.md

@@ -0,0 +1,72 @@
+# Consolidation task
+
+You are consolidating several independent analyses of the same repository.
+Every analyst received the identical prompt (included below as "Original
+prompt"), followed by formatting instructions for its report. Their reports follow under "Analyst reports", each headed "Report
+from" its source label (`#<agent number> <provider> / <model>`), with a
+"Harness:" line below it. Agents that produced no report are listed last,
+under "Agents without a report", each with the reason shown there (its
+failure, when known).
+
+Produce a consolidated report in two parts, with exactly these sections in
+this order. The first part is the findings; the second describes the
+consultation itself. Between them, write a line containing exactly
+`=== META ===` and nothing else (once, and nowhere else in the report).
+
+## Findings
+
+- Output the findings of each section (consolidated or unique) in a _numbered_ list.
+- For each finding, add explanatory text if it would be helpful to the reader.
+
+### Consensus findings
+
+Issues identified independently by two or more analysts. 
+
+For each, list the sources and briefly note any differences in emphasis.
+
+### Unique findings
+
+Issues raised by exactly one analyst, attributed to its source. 
+
+- Assess whether each is plausible.
+- Group findings by agent; for each group:
+  - output a heading with the agent number, harness, provider, and model
+    name (the harness is shown under each report's heading)
+ 
+## Contradictions
+
+Points where analysts disagree, with each position attributed.
+
+## Overall assessment
+
+The most important findings overall and your confidence in each. If you can
+verify a claim against the repository, do so (read-only) and state the
+result.
+
+=== META ===
+
+## Agent Consultants
+
+A list of provider/model agents consulted. For each agent listed under
+"Agents without a report", say it produced no report and give the reason
+shown there; do not infer failures any other way. If a report shows its
+agent could not properly do the task, say so too.
+
+## Agent performance
+
+A brief review of each agent that produced a report: how deep its research
+went (e.g. did it read code, run commands, verify claims) and how much it
+added to the review (unique or confirmed findings vs. noise or errors).
+For each agent, print a header line with agent number, duration, harness, provider,
+and model. Then print a single text string below it with the performance information.
+
+Rules:
+- Begin directly with the "## Findings" section; do not add a
+  document title or top-level heading.
+- Attribute every claim to its source model(s); never drop attribution.
+- Explain findings, don't just list them: when listing findings, unanimous
+  or otherwise, add enough explanation that the reader can easily
+  understand what the issue is. Avoid limiting the text to single-phrase
+  attributions.
+- Do not invent findings that appear in no report.
+- Deduplicate, but do not dilute: keep concrete file and line references.

data/lib/agent_council/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentCouncil
+  VERSION = '0.1.0'
+end

data/lib/agent_council/worker_pool.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module AgentCouncil
+  # Worker threads and agent processes for a run, and what Ctrl-C (or
+  # SIGTERM, SIGHUP, or SIGQUIT) does to them. main's rescue Interrupt calls
+  # into this class for everything but its own message.
+  #
+  # Each agent process runs in its own process group (see #capture3), so a
+  # terminal's Ctrl-C reaches only agent-council, never the agents. Once
+  # #trap_signals is installed, the first INT, TERM, HUP, or QUIT (not on
+  # JRuby; see TERMINATING_SIGNALS) raises Interrupt in the main thread,
+  # whose rescue calls #shutdown: it sends every agent SIGTERM (pi then also
+  # stops any commands its bash tool started, which run detached and so would
+  # survive the agent), waits up to the grace period for the workers to
+  # finish, and SIGKILLs agents still running. A second trapped signal other
+  # than HUP SIGKILLs them at once. Any HUP after the first signal is
+  # ignored: a closing terminal can deliver two at once (one forwarded by the
+  # shell, one from the kernel), which must not skip the graceful stop. A
+  # signal agent-council was started ignoring (e.g. HUP under nohup) stays
+  # ignored. Either way, agent-council then dies by the signal (see
+  # .exit_by_signal).
+  #
+  # Agents run in worker threads, never the main thread, so the main thread
+  # is always free to take the Interrupt. Workers report completion through
+  # a queue and only the main thread prints, so nothing more is printed once
+  # the Interrupt has been taken.
+  class WorkerPool
+    # Not QUIT on JRuby: the JVM reserves it for thread dumps, so trapping
+    # it only prints a warning.
+    TERMINATING_SIGNALS = (RUBY_ENGINE == 'jruby' ? %w[INT TERM HUP] : %w[INT TERM HUP QUIT]).freeze
+
+    # Each agent leads a new process group, so terminal signals skip it and
+    # #signal_child reaches the processes in that group (not ones a tool
+    # detached into a group of their own).
+    SPAWN_OPTIONS = { pgroup: true }.freeze
+
+    # Ends the process as the signal would have, so the caller (e.g. a shell
+    # running agent-council in a loop) sees it was killed by the signal, not
+    # that it handled it. QUIT exits 131 instead, rather than dumping core.
+    def self.exit_by_signal(name)
+      unless name == 'QUIT'
+        trap(name, 'SYSTEM_DEFAULT')
+        Process.kill(name, Process.pid)
+        sleep 1 # in case delivery isn't immediate
+      end
+      exit!(128 + Signal.list.fetch(name))
+    end
+
+    def initialize(grace:)
+      @grace = grace
+      @threads = []
+      @finished = Queue.new # indexes of threads as they finish
+      @uncollected = 0 # threads not yet #collect'ed
+      @children = {} # agent pids (each also its process group id)
+      @children_lock = Mutex.new
+      @stop_signal = nil # set once shutdown starts signalling agents
+      @first_signal = nil # the signal that started the shutdown
+      # Taken by the first signal. A Queue, because JRuby can run two traps
+      # at once (so checking @first_signal could let both through), and
+      # MRI forbids Mutex#lock in a trap but not Queue#pop.
+      @first_signal_token = Queue.new << true
+    end
+
+    # Installs the traps described above. The Interrupt is raised with
+    # Thread#raise, so it respects the deferral in #start.
+    def trap_signals
+      TERMINATING_SIGNALS.each do |name|
+        previous = trap(name) do
+          if first_signal?
+            @first_signal = name
+            Thread.main.raise(Interrupt)
+          elsif name != 'HUP'
+            kill_children_and_exit(name)
+          end
+        end
+        trap(name, previous) if previous == 'IGNORE'
+      end
+    end
+
+    # Runs the block in a new worker thread. The Interrupt is deferred while
+    # the thread is started and recorded, so #shutdown sees every started
+    # thread. The thread would inherit that deferral, so it's undone inside.
+    def start(&block)
+      Thread.handle_interrupt(Interrupt => :never) do
+        index = @threads.size
+        @uncollected += 1
+        @threads << Thread.new do
+          # A worker's exception is re-raised by #collect; don't print it
+          # twice.
+          Thread.current.report_on_exception = false
+          Thread.handle_interrupt(Interrupt => :immediate, &block)
+        ensure
+          @finished << index
+        end
+      end
+    end
+
+    # Waits for the threads started since the last call, yielding each
+    # one's value as it finishes. Returns their values in start order.
+    # Re-raises if a worker raised.
+    def collect
+      count = @uncollected
+      @uncollected = 0
+      finished = Array.new(count) do
+        index = @finished.pop
+        [index, @threads[index].value.tap { |value| yield value if block_given? }]
+      end
+      finished.sort_by(&:first).map(&:last)
+    end
+
+    # Open3.capture3, but with the agent in its own process group and
+    # tracked for #shutdown while it runs, and its output read as UTF-8
+    # whatever the locale. An agent spawned after shutdown has started
+    # signalling gets the same signal at once.
+    def capture3(env, *argv, stdin_data:)
+      Open3.popen3(env, *argv, **SPAWN_OPTIONS) do |stdin, stdout, stderr, wait_thr|
+        [stdout, stderr].each { |io| io.set_encoding(Encoding::UTF_8) }
+        pid = wait_thr.pid
+        begin
+          # Read after registering; signal_children sets it before reading
+          # @children, so an agent is signalled by one or the other.
+          signal = @children_lock.synchronize do
+            @children[pid] = true
+            @stop_signal
+          end
+          signal_child(pid, signal) if signal
+          out_reader = Thread.new { stdout.read }
+          err_reader = Thread.new { stderr.read }
+          begin
+            stdin.write(stdin_data)
+          rescue Errno::EPIPE
+            nil # the agent exited without reading its input
+          end
+          stdin.close
+          [out_reader.value, err_reader.value, wait_thr.value]
+        ensure
+          @children_lock.synchronize { @children.delete(pid) }
+        end
+      end
+    end
+
+    # Called from main's rescue Interrupt: yields so the caller can report
+    # it, then stops the agents as described above. Returns once the
+    # workers are done or the agents have been killed; the caller then
+    # calls #exit_by_signal. A second signal meanwhile exits from the trap.
+    def shutdown
+      flush_stdout # dying by a signal skips this
+      yield if block_given?
+      signal_children('TERM')
+      return if all_joined_by?(monotonic_now + @grace)
+
+      signal_children('KILL')
+      all_joined_by?(monotonic_now + 1) # let killed agents' workers clean up
+    end
+
+    # .exit_by_signal for the signal that stopped the run.
+    def exit_by_signal
+      self.class.exit_by_signal(@first_signal || 'INT')
+    end
+
+    # name: the signal that called it, for when it arrived together with the
+    # first one, whose trap may not have set @first_signal yet.
+    private def kill_children_and_exit(name)
+      signal_children('KILL')
+      flush_stdout
+      self.class.exit_by_signal(@first_signal || name)
+    end
+
+    private def first_signal?
+      @first_signal_token.pop(true)
+    rescue ThreadError # already taken
+      false
+    end
+
+    # Signals every running agent's process group. Callable from a trap.
+    private def signal_children(signal)
+      @stop_signal = signal
+      children_snapshot.each { |pid| signal_child(pid, signal) }
+    end
+
+    # A snapshot, so a concurrent spawn can't modify the hash mid-iteration.
+    # MRI forbids Mutex#lock in a trap, but its GVL makes Hash#keys atomic.
+    # JRuby has no GVL, but its traps run in ordinary threads, which may lock.
+    private def children_snapshot
+      return @children.keys unless RUBY_ENGINE == 'jruby'
+
+      @children_lock.synchronize { @children.keys }
+    end
+
+    private def signal_child(pid, signal)
+      Process.kill(signal, -pid)
+    rescue SystemCallError
+      nil # already gone
+    end
+
+    # A hung-up terminal can make writing fail; that mustn't stop shutdown.
+    private def flush_stdout
+      $stdout.flush
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    # Joins every thread until the deadline; true if all finished. A worker
+    # that raised has finished (#collect reports its exception).
+    private def all_joined_by?(deadline)
+      @threads.map do |thread|
+        thread.join([deadline - monotonic_now, 0].max)
+      rescue
+        true
+      end.all?
+    end
+
+    private def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end