agentilda 2.0.1 → 2.0.4

data/lib/agentilda/presentation/console.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # What the keys do to the screen, and to the running agents.
+    #
+    # Selection and the dialog live here, never on the screen: the screen
+    # draws whatever board it is handed, and this decides what the board
+    # says. Pending changes are visible only in the dialog and take effect
+    # only on ENTER, so a stray `k` kills nobody.
+    class Console
+      # Seconds each `x` adds.
+      EXTENSION = 600
+
+      # @param screen [Agentilda::Presentation::Screen::Ratatui]
+      def initialize(screen:)
+        @screen = screen
+        @dispatcher = nil
+        @board = nil
+        @selected = nil
+        @dialog = false
+        @help = false
+        @about = false
+        @pending = { kill: false, extend: 0 }
+        @mutex = Mutex.new
+      end
+
+      # @return [String, nil] the selected row's key
+      attr_reader :selected
+
+      # @return [Hash] `{kill: Boolean, extend: Integer}`
+      attr_reader :pending
+
+      # @return [Agentilda::Presentation::Screen::Ratatui]
+      attr_reader :screen
+
+      # @return [Boolean]
+      def dialog? = @dialog
+
+      # @return [Boolean]
+      def help? = @help
+
+      # @return [Boolean]
+      def about? = @about
+
+      # The dispatcher exists only once the run starts, after the keyboard is
+      # already listening, so it arrives late.
+      #
+      # @param dispatcher [Agentilda::Engine::Dispatcher]
+      # @return [void]
+      def attach(dispatcher) = @dispatcher = dispatcher
+
+      # Called by the dispatcher each tick.
+      #
+      # @param board [Agentilda::Engine::Board]
+      # @return [void]
+      def paint(board)
+        @mutex.synchronize do
+          @board = board
+          @selected = nil if @selected && board.rows.none? { |r| r.key == @selected && r.running? }
+          @screen.draw(board.with(selected: @selected,
+            dialog: (dialog_text if @dialog),
+            help: (help_text if @help),
+            about: (about_text if @about)))
+        end
+      end
+
+      # @return [void]
+      def select_next = move(1)
+
+      # @return [void]
+      def select_prev = move(-1)
+
+      # @return [void]
+      def toggle_kill
+        select_next unless @selected
+        return unless @selected
+
+        @pending[:kill] = !@pending[:kill]
+        @dialog = true
+      end
+
+      # @return [void]
+      def extend
+        select_next unless @selected
+        return unless @selected
+
+        @pending[:extend] += EXTENSION
+        @dialog = true
+      end
+
+      # ENTER.
+      #
+      # @return [void]
+      def apply
+        return unless @dialog && @selected && @dispatcher
+
+        @dispatcher.kill(@selected) if @pending[:kill]
+        @dispatcher.extend(@selected, @pending[:extend]) if @pending[:extend].positive?
+        UI.log("applied to #{@selected}: #{dialog_text.tr("\n", ", ")}")
+        close_dialog
+      end
+
+      # ESC: the dialog first, then the help, then the about screen, then the
+      # selection.
+      #
+      # @return [void]
+      def escape
+        if @dialog
+          close_dialog
+        elsif @help
+          @help = false
+        elsif @about
+          @about = false
+        else
+          @selected = nil
+        end
+      end
+
+      # @return [void]
+      def toggle_help = @help = !@help
+
+      # @return [void]
+      def toggle_about = @about = !@about
+
+      private
+
+      # @return [void]
+      def close_dialog
+        @dialog = false
+        @pending = { kill: false, extend: 0 }
+      end
+
+      # @param step [Integer]
+      # @return [void]
+      def move(step)
+        keys = (@board&.rows || []).select(&:running?).map(&:key)
+        return @selected = nil if keys.empty?
+
+        index = keys.index(@selected)
+        @selected = index.nil? ? keys.first : keys[(index + step) % keys.size]
+      end
+
+      # @return [String]
+      def dialog_text
+        row = @board&.rows&.find { |r| r.key == @selected }
+        who = row ? "#{row.ordinal} #{row.agent}" : @selected.to_s
+        extension = @pending[:extend].positive? ? "+#{@pending[:extend] / 60}m" : "none"
+        "#{who}\n\nkill: #{@pending[:kill] ? "yes" : "no"}\nextend: #{extension}"
+      end
+
+      # @return [String]
+      def help_text = Keyboard.new(input: $stdin).help
+
+      # @return [String]
+      def about_text = Keyboard.new(input: $stdin).about
+    end
+  end
+end

data/lib/agentilda/presentation/dashboard.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # The ratatui dashboard for agent work that is not a `run`: `unblock`
+    # handing plans to lando-broker, `create` drafting a spec.md. `run` has a
+    # {Dispatcher} to build its {Board}; this builds one from the items
+    # {UI.concurrently} hands it, so every agent a person waits on is drawn
+    # the same way, with the same keys.
+    #
+    # It stands in for the dispatcher behind {Console}, which is why it
+    # answers {#kill} and {#extend}: a row whose work passed its
+    # {Tracker#handle} on to {Executor#call} can be killed or given more time.
+    class Dashboard
+      # Seconds between frames handed to the screen.
+      REFRESH = 0.25
+
+      # Seconds a finished row stays on screen, so a fast agent is still seen.
+      LINGER = 3
+
+      # One item's row, and the {UI::Line} its work streams progress through.
+      # Nothing is drawn by the line itself; the dashboard reads it each frame.
+      class Tracker < UI::Line
+        # @return [String]
+        attr_reader :key
+
+        # @return [Agentilda::Execution::Executor::Handle] handed to {Executor#call} by a
+        #   caller that wants the kill and extend keys to reach its agent.
+        #   Not `@handle`: {UI::Line} keeps its dry-cli-ui line under that name.
+        def handle = @executor_handle
+
+        # @return [Symbol] :running, :done or :failed
+        attr_reader :state
+
+        # @return [Float, nil] monotonic reading of when it stopped running
+        attr_reader :finished_at
+
+        # @param key [String]
+        # @param fields [Hash] plan, status, agent and round, for the log and the row
+        # @param file [String] what the row's feature column says
+        # @param message [String] shown until the agent says something
+        # @param timeout [Integer, nil]
+        def initialize(key:, fields:, file:, message:, timeout: nil)
+          super(fields:, timeout:)
+          @key = key
+          @file = file
+          @message = message
+          @executor_handle = Execution::Executor::Handle.new
+          @state = :running
+          @update = nil
+          @history = []
+          @finished_at = nil
+        end
+
+        # @param update [Agentilda::Execution::Transcript::Progress]
+        # @return [void]
+        def call(update)
+          super
+          @update = update
+          return unless update.activity
+
+          @message = update.activity
+          @history = Engine::Board::Row.remember(@history, @message)
+        end
+
+        # @return [void]
+        def done
+          super
+          finish(:done)
+        end
+
+        # @param reason [String]
+        # @return [void]
+        def failed(reason)
+          super
+          @message = reason
+          @history = Engine::Board::Row.remember(@history, reason)
+          finish(:failed)
+        end
+
+        # @return [Agentilda::Engine::Board::Row]
+        def row
+          Engine::Board::Row.new(key:,
+            at: Time.now,
+            ordinal: @fields[:plan].to_s,
+            file: @file,
+            agent: @fields[:agent].to_s,
+            role: @fields[:agent].to_s,
+            round: @fields[:round] || 1,
+            rounds: @fields[:round] || 1,
+            model: "default",
+            remaining: handle.remaining || remaining,
+            phase: handle.phase,
+            up: @update&.up.to_i,
+            down: @update&.down.to_i,
+            message: @message,
+            state:,
+            elapsed: seconds.round,
+            subagents: @update&.subagents.to_i,
+            history: @history)
+        end
+
+        private
+
+        # @param state [Symbol]
+        # @return [void]
+        def finish(state)
+          @state = state
+          @finished_at = UI.monotonic
+        end
+      end
+
+      # Opens the screen, runs the block, and always closes it again.
+      #
+      # @param root [String] shown in the bottom bar
+      # @param screen [Agentilda::Presentation::Screen::Ratatui]
+      # @yieldparam dashboard [Agentilda::Presentation::Dashboard]
+      # @return [Object] the block's value
+      def self.open(root: Dir.pwd, screen: Screen::Ratatui.new)
+        dashboard = new(root:, screen:)
+        dashboard.start
+        begin
+          yield dashboard
+        ensure
+          dashboard.stop
+        end
+      end
+
+      # @param root [String]
+      # @param screen [Agentilda::Presentation::Screen::Ratatui]
+      def initialize(root:, screen:)
+        @root = root
+        @screen = screen
+        @console = Console.new(screen:)
+        @console.attach(self)
+        @trackers = []
+        @lock = Mutex.new
+        @started_at = UI.monotonic
+        @closing = false
+      end
+
+      # @return [void]
+      def start
+        # ratatui owns the terminal's input, so the keyboard is fed from its
+        # loop rather than reading STDIN on a thread of its own.
+        @keyboard = Keyboard.new(sink: @console)
+        @screen.attach_keyboard(@keyboard)
+        @screen.open
+        @painter = Thread.new do
+          Thread.current.report_on_exception = false
+          until @closing
+            paint
+            sleep(REFRESH)
+          end
+        end
+      end
+
+      # @return [void]
+      def stop
+        @closing = true
+        @painter&.join
+        paint
+        @screen.close
+      end
+
+      # @param key [String]
+      # @param fields [Hash]
+      # @param file [String]
+      # @param message [String]
+      # @param timeout [Integer, nil]
+      # @return [Tracker]
+      def track(key:, fields: {}, file: "", message: "starting", timeout: nil)
+        Tracker.new(key:, fields:, file:, message:, timeout:).tap do |tracker|
+          @lock.synchronize { @trackers << tracker }
+        end
+      end
+
+      # @return [void]
+      def paint = @console.paint(board)
+
+      # @return [Agentilda::Engine::Board]
+      def board
+        rows = visible.map(&:row)
+        running = rows.select(&:running?)
+        Engine::Board.new(started_at: @started_at,
+          status: Execution::Control.quit? ? :quitting : :running,
+          plans: rows.map(&:ordinal).reject(&:empty?).uniq,
+          up: rows.sum(&:up),
+          down: rows.sum(&:down),
+          rows:,
+          root: @root,
+          running: running.size,
+          live_up: running.sum(&:up),
+          live_down: running.sum(&:down))
+      end
+
+      # @param key [String]
+      # @return [void]
+      def kill(key) = find(key)&.handle&.kill!
+
+      # @param key [String]
+      # @param seconds [Integer]
+      # @return [void]
+      def extend(key, seconds) = find(key)&.handle&.extend!(seconds)
+
+      private
+
+      # @return [Array<Tracker>] running, plus whatever finished a moment ago
+      def visible
+        now = UI.monotonic
+        @lock.synchronize do
+          @trackers.reject { |t| t.finished_at && now - t.finished_at > LINGER }
+        end
+      end
+
+      # @param key [String]
+      # @return [Tracker, nil]
+      def find(key) = @lock.synchronize { @trackers.find { |t| t.key == key } }
+    end
+  end
+end

data/lib/agentilda/presentation/diagram.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Presentation
+    # `agentilda states` — the state machine as a terminal picture.
+    #
+    # {Documentation} already renders this machine as a Markdown table and a
+    # mermaid block, for a browser. This is the same machine, walked the same
+    # way, shaped for a terminal instead: unicode arrows, no browser required.
+    #
+    # Every section below is read off {StateMachine} and {STATUSES} rather than
+    # drawn by hand, for the reason {Documentation} gives for doing the same
+    # thing: three hand-maintained pictures of this machine have already
+    # drifted apart once, and a fourth is not the fix.
+    class Diagram
+      include UI
+
+      # Drawn between two states on the same line.
+      ARROW = "──▶"
+
+      # @return [String] the whole diagram, newline-terminated
+      def render
+        [
+          heading,
+          spine_section,
+          rejoin_section,
+          other_section,
+          terminal_section,
+          family_section
+        ].compact.join("\n\n") + "\n"
+      end
+
+      private
+
+      # @return [String]
+      def heading
+        paint("Spec → Plan → Build — the state machine", :bold) + "\n" +
+          paint("(derived from lib/agentilda/state_machine.rb — `agentilda docs` for the Markdown form)",
+            :bright_black)
+      end
+
+      # The path a bare `promote!` walks: {StateMachine::SPINE}, followed from
+      # `:new` until a state has no entry left to follow.
+      #
+      # @return [String]
+      def spine_section
+        section("MAIN SPINE",
+          "a bare `promote` walks this path",
+          ["  " + spine_chain.map { |key| node(key) }.join(" #{ARROW} ")])
+      end
+
+      # {StateMachine::SPINE} entries whose source never appears on the walk
+      # above — states that sit off the spine but whose default `promote!`
+      # rejoins it, e.g. a rejected pull request resubmitted for review.
+      #
+      # @return [String, nil]
+      def rejoin_section
+        rows = Plans::StateMachine::SPINE
+               .except(*spine_chain)
+               .map { |from, to| "  #{node(from)} #{ARROW} #{node(to)}" }
+
+        section("REJOINING THE SPINE", "off-spine states whose default promotion lands back on it", rows)
+      end
+
+      # Everything {StateMachine} allows that the two sections above do not
+      # already draw: blocking, deferring, discarding, review outcomes,
+      # rollback — read off {StateMachine.outbound} state by state, in
+      # {STATUSES} order, so nothing the machine permits is left undrawn.
+      #
+      # @return [String, nil]
+      def other_section
+        drawn = Plans::StateMachine::SPINE.to_a
+
+        groups = Plans::STATUSES.filter_map { |s|
+          targets = Plans::StateMachine.outbound(s.key).reject { |to| drawn.include?([s.key, to]) }
+          [s.key, targets] unless targets.empty?
+        }
+
+        section("OTHER TRANSITIONS",
+          "everything else the machine permits",
+          groups.flat_map { |key, targets|
+            fan_out(key, targets)
+          })
+      end
+
+      # @return [String, nil]
+      def terminal_section
+        rows = Plans::STATUSES.select(&:terminal?).map { |s| "  #{node(s.key)}" }
+        section("TERMINAL", "nothing follows these", rows)
+      end
+
+      # {StateMachine::FAMILIES} share an invariant on purpose, and a folder's
+      # contents alone cannot tell their members apart — worth saying next to a
+      # diagram, or the members read like an oversight rather than a rule.
+      #
+      # @return [String, nil]
+      def family_section
+        rows = Plans::StateMachine::FAMILIES.map { |members| "  #{members.map { |key| node(key) }.join(" / ")}" }
+
+        section("LOOK-ALIKE FAMILIES", "same contents on disk; only the folder name tells them apart", rows)
+      end
+
+      # `:new`, followed through {StateMachine::SPINE} until nothing follows.
+      #
+      # @return [Array<Symbol>]
+      def spine_chain
+        @spine_chain ||= [].tap { |chain|
+          key = :new
+          while key
+            chain << key
+            key = Plans::StateMachine::SPINE[key]
+          end
+        }
+      end
+
+      # One state and its outbound arrows, drawn as a small tree so several
+      # targets from one source read as a fan-out rather than as unrelated
+      # lines that happen to repeat the source.
+      #
+      # @param key [Symbol]
+      # @param targets [Array<Symbol>]
+      # @return [Array<String>]
+      def fan_out(key, targets)
+        lines = targets.each_with_index.map { |to, i|
+          connector = i == targets.size - 1 ? "└─▶" : "├─▶"
+          "      #{connector} #{node(to)}"
+        }
+        ["  #{node(key)}", *lines]
+      end
+
+      # @param key [Symbol]
+      # @return [String]
+      def node(key)
+        status = Plans::STATUS_BY_KEY.fetch(key)
+        paint("#{status.emoji} #{status.label}", :bold)
+      end
+
+      # @param title [String]
+      # @param subtitle [String]
+      # @param rows [Array<String>]
+      # @return [String, nil] nil when there is nothing to show, so {#render} can drop it
+      def section(title, subtitle, rows)
+        return nil if rows.empty?
+
+        "#{paint(title, :bold)}  #{paint("(#{subtitle})", :bright_black)}\n\n#{rows.join("\n")}"
+      end
+    end
+  end
+end