agentilda 2.0.1 → 2.0.4

data/lib/agentilda/cli/resync/subcommands/dirs.rb

@@ -21,8 +21,8 @@ module Agentilda
         # @param options [Hash]
         # @return [void]
         def call(**options)
-          changes = Agentilda::Resync::Dirs.new(tree: tree_for(options))
-                                           .call(commit: commit?(options))
+          changes = Agentilda::Lifecycle.resync_dirs(tree: tree_for(options))
+                                        .call(commit: commit?(options))
 
           if changes.empty?
             success("Every folder is already named NNN.MM-<emoji> → <slug> and the emoji matches.") unless quiet?(options)

data/lib/agentilda/cli/resync/subcommands/prs.rb

@@ -31,13 +31,13 @@ module Agentilda
         # @param options [Hash]
         # @return [void]
         def call(**options)
-          github = GitHub.new
+          github = Vcs.github
           tree = tree_for(options)
-          changes = Agentilda::Resync::Prs.new(tree:,
+          changes = Agentilda::Lifecycle.resync_prs(tree:,
             github:,
             adopt: options.fetch(:adopt, true),
             root: File.dirname(tree.dir))
-                                          .call(commit: commit?(options))
+                                        .call(commit: commit?(options))
 
           if changes.empty?
             success("Every pull request title already carries a prefix.") unless quiet?(options)

data/lib/agentilda/cli/run/run.rb

@@ -54,7 +54,7 @@ module Agentilda
       option :scroll_height,
         aliases: ["-s"],
         desc:    "Lines of each agent's latest statuses shown under its row, newest first " \
-                 "(default: #{Screen::Ratatui::SCROLL_HEIGHT})"
+                 "(default: #{Presentation::Screen::Ratatui::SCROLL_HEIGHT})"
       option :log, desc: "Append progress to this file (default: a per-project file under the system temp dir)"
 
       example [
@@ -89,7 +89,7 @@ module Agentilda
 
         tree   = tree_for(options)
         root   = options[:root] || File.dirname(tree.dir)
-        agents = Agentilda::Agents.new
+        agents = Agentilda::Agents.registry
         agents = filtered(agents, options[:agent]) if options[:agent]
         agents = skipped(agents, options[:skip], options[:agent]) if options[:skip]
         plans  = options[:plan] ? scoped(tree, options[:plan]) : nil
@@ -99,7 +99,7 @@ module Agentilda
         jobs      = (options[:jobs] || config[:jobs] || UI.default_jobs).to_i
         timeout   = (options[:timeout] || config[:timeout])&.to_i
 
-        if isolation == :worktree && !::Agentilda::Worktree.new(root:).repository?
+        if isolation == :worktree && !Agentilda::Vcs.worktree(root:).repository?
           refuse("#{root} is not a git repository, so plans cannot be isolated.\n\n" \
                  "Run with --isolation shared to work in one tree, serially.",
             66)
@@ -119,9 +119,9 @@ module Agentilda
         # so it never rides along in a commit. Editing somebody's .gitignore
         # is announced, the once it happens. The runner drops the file on a
         # dry run, which is why it can be built unconditionally.
-        state = StateFile.new(path: StateFile.for(tree))
-        if commit?(options) && StateFile.ensure_ignored!(root) && !quiet?(options)
-          info("Added #{StateFile::IGNORE.join(" and ")} to .gitignore: the run keeps its state there.")
+        state = Engine.state_file(tree)
+        if commit?(options) && Engine::StateFile.ensure_ignored!(root) && !quiet?(options)
+          info("Added #{Engine::StateFile::IGNORE.join(" and ")} to .gitignore: the run keeps its state there.")
         end
 
         # The screen only on a terminal that is actually running agents: a dry
@@ -129,33 +129,33 @@ module Agentilda
         # screen the keys still work, so the one line says which.
         # With a screen, ratatui owns the terminal's input, so the keyboard is
         # fed from its loop rather than started on STDIN of its own.
-        Control.reset!
-        scroll_height = options.fetch(:scroll_height, Screen::Ratatui::SCROLL_HEIGHT)
+        Execution::Control.reset!
+        scroll_height = options.fetch(:scroll_height, Presentation::Screen::Ratatui::SCROLL_HEIGHT)
         unless scroll_height.to_s.match?(/\A[1-9]\d*\z/)
           refuse("--scroll-height must be a whole number of lines, 1 or more, not #{scroll_height.inspect}.", 64)
         end
-        screen   = (Screen::Ratatui.new(scroll_height: scroll_height.to_i) if UI.animate? && commit?(options))
-        console  = (Console.new(screen:) if screen)
+        screen   = (Presentation::Screen::Ratatui.new(scroll_height: scroll_height.to_i) if UI.animate? && commit?(options))
+        console  = (Presentation::Console.new(screen:) if screen)
         # A dry run gets no keyboard at all: every key it offers speaks to a
         # running agent, and listening costs the terminal's raw mode, whose
         # output post-processing the report below needs left alone.
         keyboard = if screen
-                     Keyboard.new(sink: console).tap { |kb| screen.attach_keyboard(kb) }
+                     Presentation::Keyboard.new(sink: console).tap { |kb| screen.attach_keyboard(kb) }
                    elsif commit?(options)
-                     Keyboard.listen(sink: console)
+                     Presentation::Keyboard.listen(sink: console)
                    end
         UI.line("keys: h for help - s select, k kill, x extend, w wrap up, n stop, q quit") if keyboard && console.nil? && !quiet?(options)
 
-        runner = Runner.new(
+        runner = Engine.runner(
           tree:,
           agents:,
           isolation:,
           jobs:,
           plans:,
           state:,
-          worktree:  (::Agentilda::Worktree.new(root:) if isolation == :worktree),
+          worktree:  (Agentilda::Vcs.worktree(root:) if isolation == :worktree),
           rounds:    (options[:rounds] || config[:rounds])&.to_i,
-          executor:  Executor.new(root:,
+          executor:  Execution.executor(root:,
             timeout:,
             dry_run:      !commit?(options),
             instructions: instructions_from(options[:prompt]),
@@ -172,7 +172,7 @@ module Agentilda
         started  = UI.monotonic
         attempts = begin
           screen&.open
-          Control.on_interrupt { runner.call { |dispatcher| console&.attach(dispatcher) } }
+          Execution.on_interrupt { runner.call { |dispatcher| console&.attach(dispatcher) } }
         ensure
           screen&.close
           keyboard&.stop
@@ -192,7 +192,7 @@ module Agentilda
       # from the rows themselves, so the columns are as narrow as the run
       # allows and still square.
       #
-      # @param attempts [Array<Agentilda::Runner::Attempt>]
+      # @param attempts [Array<Agentilda::Engine::Runner::Attempt>]
       # @return [Array<String>] one line per attempt, indented by two
       def attempt_lines(attempts)
         rows   = attempts.map { |a| [a.ordinal.to_s, a.agent.to_s, "[R:#{a.round}]", mark(a), a.note.to_s] }
@@ -205,7 +205,7 @@ module Agentilda
         end
       end
 
-      # @param attempt [Agentilda::Runner::Attempt]
+      # @param attempt [Agentilda::Engine::Runner::Attempt]
       # @return [String] what the attempt did to its plan's state
       def mark(attempt)
         return "FAIL" unless attempt.ok
@@ -228,9 +228,9 @@ module Agentilda
         File.read(prompt)
       end
 
-      # @param agents [Agentilda::Agents]
+      # @param agents [Agentilda::Agents::Registry]
       # @param name [String]
-      # @return [Agentilda::Agents] holding only the agent named — the
+      # @return [Agentilda::Agents::Registry] holding only the agent named — the
       #   restriction has to reach assignments, not just chaining, or a flag
       #   like `--prompt` aimed at one agent leaks to the whole round
       def filtered(agents, name)
@@ -243,12 +243,12 @@ module Agentilda
       # already-restricted one, so `--skip` misspelled is a refusal rather
       # than a silent no-op — the same reasoning `--plan` applies to numbers.
       #
-      # @param agents [Agentilda::Agents]
+      # @param agents [Agentilda::Agents::Registry]
       # @param text [String] comma-separated agent names
       # @param restricted [String, nil] what `--agent` asked for, if anything
-      # @return [Agentilda::Agents] without the agents named
+      # @return [Agentilda::Agents::Registry] without the agents named
       def skipped(agents, text, restricted)
-        roster = Agentilda::Agents.new
+        roster = Agentilda::Agents.registry
         names  = text.split(",").map(&:strip).reject(&:empty?)
         names.each do |name|
           roster.find(name) or
@@ -268,13 +268,13 @@ module Agentilda
       # this exists to prevent, so an unknown one is refused rather than
       # dropped.
       #
-      # @param tree [Agentilda::Tree]
+      # @param tree [Agentilda::Plans::Tree]
       # @param text [String]
-      # @return [Array<Agentilda::Ordinal>]
+      # @return [Array<Agentilda::Plans::Ordinal>]
       def scoped(tree, text)
         known = tree.subjects.map { |s| s.feature.ordinal }
         text.split(",").map(&:strip).reject(&:empty?).map { |token|
-          ordinal = Ordinal.parse(token)
+          ordinal = Plans::Ordinal.parse(token)
           unless ordinal && known.include?(ordinal)
             refuse("No plan #{token} in #{tree.dir}.\n\n" \
                    "Known: #{known.join(", ")}",
@@ -290,34 +290,34 @@ module Agentilda
       # agent and a plan meant them to meet, so a pairing that cannot happen
       # is refused up front with the agent that would actually take each plan.
       #
-      # @param agents [Agentilda::Agents] already narrowed to the one agent
-      # @param tree [Agentilda::Tree]
-      # @param plans [Array<Agentilda::Ordinal>, nil]
+      # @param agents [Agentilda::Agents::Registry] already narrowed to the one agent
+      # @param tree [Agentilda::Plans::Tree]
+      # @param plans [Array<Agentilda::Plans::Ordinal>, nil]
       # @param name [String]
       # @return [void]
       def assignable!(agents, tree, plans, name)
         agent  = agents.find(name)
         active = tree.subjects.select { |s|
           (plans.nil? || plans.include?(s.feature.ordinal)) &&
-            !StateMachine::SETTLED.include?(s.status.key)
+            !Plans::StateMachine::SETTLED.include?(s.status.key)
         }
         return if active.empty? || active.any? { |s| agent.handles?(s.status) }
 
-        roster  = Agentilda::Agents.new
+        roster  = Agentilda::Agents.registry
         lines   = active.map { |s|
           takers = roster.for_status(s.status).map(&:name)
           verb   = takers.size == 1 ? "takes" : "take"
           "  #{s.feature.ordinal} is #{s.status.emoji} #{s.status.label}" \
             "#{" - #{takers.join(" and ")} #{verb} it" unless takers.empty?}"
         }
-        handled = agent.handles.map { |k| Agentilda::STATUS_BY_KEY[k]&.then { |st| "#{st.emoji} #{st.label}" } || k }
+        handled = agent.handles.map { |k| Agentilda::Plans::STATUS_BY_KEY[k]&.then { |st| "#{st.emoji} #{st.label}" } || k }
         refuse("#{name} handles #{handled.join(", ")}, and no plan in scope is there:\n\n" \
                "#{lines.join("\n")}\n\nName the agent that takes these states, or drop --agent.",
           65)
       end
 
-      # @param attempts [Array<Agentilda::Runner::Attempt>]
-      # @return [Array<Agentilda::Runner::Attempt>]
+      # @param attempts [Array<Agentilda::Engine::Runner::Attempt>]
+      # @return [Array<Agentilda::Engine::Runner::Attempt>]
       def failures(attempts) = attempts.reject(&:ok)
 
       # The one thing this harness does that leaves the machine — pushing a
@@ -332,11 +332,11 @@ module Agentilda
       # @param root [String]
       # @param isolation [Symbol]
       # @param options [Hash]
-      # @return [Agentilda::Publisher, nil]
+      # @return [Agentilda::Vcs::Publisher, nil]
       def publisher_for(root, isolation, options)
         return nil if isolation != :worktree || options[:git_push] == false
 
-        Publisher.new(root:, dry_run: !commit?(options))
+        Vcs.publisher(root:, dry_run: !commit?(options))
       end
 
       # One line per attempt: the plan, who ran, which of that agent's rounds
@@ -344,8 +344,8 @@ module Agentilda
       # because the loop has no rounds of its own: each agent counts its own
       # per plan, so two agents on one plan can be on different numbers.
       #
-      # @param runner [Agentilda::Runner]
-      # @param attempts [Array<Agentilda::Runner::Attempt>]
+      # @param runner [Agentilda::Engine::Runner]
+      # @param attempts [Array<Agentilda::Engine::Runner::Attempt>]
       # @param options [Hash]
       # @param seconds [Float] wall clock for the whole loop
       # @return [void]
@@ -360,12 +360,12 @@ module Agentilda
         # What the run cost, on STDOUT with the attempts it belongs to, so a run
         # redirected to a file keeps its bill. A dry run spent nothing and gets
         # none of this.
-        tally = Tally.new(attempts:, seconds:)
+        tally = Engine.tally(attempts:, seconds:)
         puts("", tally.render) if commit?(options)
 
         return if quiet?(options)
 
-        if Control.quit?
+        if Execution::Control.quit?
           warn("Stopped from the keyboard — q. Unfinished plans keep their state; " \
                "re-run to resume where they stand.")
         end

data/lib/agentilda/cli/states/states.rb

@@ -9,7 +9,7 @@ module Agentilda
       example [""]
 
       # @return [void]
-      def call(**) = $stdout.write(Diagram.new.render)
+      def call(**) = $stdout.write(Presentation.diagram)
     end
   end
 end

data/lib/agentilda/cli/unblock/unblock.rb

@@ -47,11 +47,11 @@ module Agentilda
       def call(plans:, **options)
         tree = tree_for(options)
         quiet?(options)
-        unblocker = Unblocker.new(tree:,
+        unblocker = Lifecycle.unblocker(tree:,
           agent: agent_for(options),
           root: options[:root],
           commit: commit?(options),
-          executor: Executor.new(root: options[:root] || File.dirname(tree.dir),
+          executor: Execution.executor(root: options[:root] || File.dirname(tree.dir),
             dry_run: !commit?(options)))
 
         targets = unblocker.resolve(plans)
@@ -62,7 +62,7 @@ module Agentilda
         credentials_warning if commit?(options) && !quiet?(options)
         preflight(subjects, unblocker, options)
 
-        outcomes = Control.on_interrupt { unblocker.call(subjects) }
+        outcomes = Execution.on_interrupt { unblocker.call(subjects) }
         outcomes.each { |outcome| report(outcome, options) }
         footer(outcomes, options) unless quiet?(options)
         exit(worst(targets, outcomes))
@@ -71,10 +71,10 @@ module Agentilda
       private
 
       # @param options [Hash]
-      # @return [Agentilda::Agent]
+      # @return [Agentilda::Agents::Agent]
       def agent_for(options)
         name = options.fetch(:agent, DEFAULT_AGENT)
-        agents = Agentilda::Agents.new
+        agents = Agentilda::Agents.registry
         agents.find(name) or
           refuse("No agent called #{name}.\n\nKnown: #{agents.all.map(&:name).join(", ")}", 65)
       end
@@ -87,8 +87,8 @@ module Agentilda
       # Every bad token is reported, not just the first, because stopping at
       # the first one hides the rest of the answer.
       #
-      # @param targets [Array<Agentilda::Unblocker::Target>]
-      # @param tree [Agentilda::Tree]
+      # @param targets [Array<Agentilda::Lifecycle::Unblocker::Target>]
+      # @param tree [Agentilda::Plans::Tree]
       # @param options [Hash]
       # @return [void]
       def refused(targets, tree, options)
@@ -113,15 +113,15 @@ module Agentilda
       # terminal showed nothing at all — a run that had found nothing to do and
       # a run still working looked exactly alike.
       #
-      # @param subjects [Array<Agentilda::Subject>]
-      # @param unblocker [Agentilda::Unblocker]
+      # @param subjects [Array<Agentilda::Plans::Subject>]
+      # @param unblocker [Agentilda::Lifecycle::Unblocker]
       # @param options [Hash]
       # @return [void]
       def preflight(subjects, _unblocker, options)
         return if quiet?(options)
 
         subjects.each do |subject|
-          questions = Unblocker.questions(subject)
+          questions = Lifecycle::Unblocker.questions(subject)
           answered = questions.count(&:answered)
           say("#{paint(subject.feature.ordinal.to_s, :bright_black)} #{subject.status.emoji} " \
               "#{subject.feature.title} — #{summary(questions.size, answered)}")
@@ -138,8 +138,8 @@ module Agentilda
         "#{open} open, #{answered.zero? ? "none answered yet" : "#{answered} with an answer waiting"}"
       end
 
-      # @param subject [Agentilda::Subject]
-      # @param questions [Array<Agentilda::Unblocker::Question>]
+      # @param subject [Agentilda::Plans::Subject]
+      # @param questions [Array<Agentilda::Lifecycle::Unblocker::Question>]
       # @return [void]
       def detail(subject, questions)
         if subject.unreadable_block?
@@ -157,7 +157,7 @@ module Agentilda
       # One plan, after the fact: the deliverable line on STDOUT, and what
       # changed on STDERR.
       #
-      # @param outcome [Agentilda::Unblocker::Outcome]
+      # @param outcome [Agentilda::Lifecycle::Unblocker::Outcome]
       # @param options [Hash]
       # @return [void]
       def report(outcome, options)
@@ -177,7 +177,7 @@ module Agentilda
       # What the file says happened, rather than what the agent claims. The
       # questions are counted off disk on both sides of the run.
       #
-      # @param outcome [Agentilda::Unblocker::Outcome]
+      # @param outcome [Agentilda::Lifecycle::Unblocker::Outcome]
       # @param commit [Boolean]
       # @return [String]
       def movement(outcome, commit)
@@ -189,7 +189,7 @@ module Agentilda
         "folded #{outcome.folded.map { |n| "B#{n}" }.join(", ")}"
       end
 
-      # @param outcomes [Array<Agentilda::Unblocker::Outcome>]
+      # @param outcomes [Array<Agentilda::Lifecycle::Unblocker::Outcome>]
       # @param options [Hash]
       # @return [void]
       def footer(outcomes, options)
@@ -222,8 +222,8 @@ module Agentilda
       # The most serious thing that happened, as an exit status. A tree that
       # was partly drained still exits non-zero when part of it could not be.
       #
-      # @param targets [Array<Agentilda::Unblocker::Target>]
-      # @param outcomes [Array<Agentilda::Unblocker::Outcome>]
+      # @param targets [Array<Agentilda::Lifecycle::Unblocker::Target>]
+      # @param outcomes [Array<Agentilda::Lifecycle::Unblocker::Outcome>]
       # @return [Integer]
       def worst(targets, outcomes)
         problems = targets.map(&:problem)

data/lib/agentilda/cli/worktree/worktree.rb

@@ -35,7 +35,7 @@ module Agentilda
         end
 
         root = File.dirname(tree.dir)
-        worktree = ::Agentilda::Worktree.new(root:)
+        worktree = Agentilda::Vcs.worktree(root:)
 
         checkout = worktree.checkout_for(feature)
 
@@ -66,12 +66,12 @@ module Agentilda
 
       # Find the plan that matches the given identifier.
       #
-      # @param tree [Agentilda::Tree] plans directory wrapper
+      # @param tree [Agentilda::Plans::Tree] plans directory wrapper
       # @param plan [String] ordinal, folder name, or slug
-      # @return [Agentilda::Feature, nil]
+      # @return [Agentilda::Plans::Feature, nil]
       def resolve_plan(tree, plan)
         # Try parsing as an ordinal first
-        ordinal = ::Agentilda::Ordinal.parse(plan)
+        ordinal = ::Agentilda::Plans::Ordinal.parse(plan)
         if ordinal
           found = tree.features.find { |f| f.ordinal == ordinal }
           return found if found

data/lib/agentilda/cli.rb

@@ -106,7 +106,7 @@ module Agentilda
       prefix.register "projects", Linear::Projects
     end
 
-    # What a paired agent shells out to between steps. See {Agentilda::Mailbox}.
+    # What a paired agent shells out to between steps. See {Agentilda::Plans::Mailbox}.
     register "mail" do |prefix|
       prefix.register "send", Mail::Send
       prefix.register "read", Mail::Read

data/lib/agentilda/engine/board.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Engine
+    # What the screen draws: everything about the run, as values, refreshed
+    # once a second by the dispatcher. The screen paints it and knows nothing
+    # about threads; the dispatcher builds it and knows nothing about cells.
+    #
+    # @!attribute [r] rows
+    #   @return [Array<Agentilda::Engine::Board::Row>] one per agent invocation still
+    #     worth showing: running, or finished within the last few seconds
+    Board = Data.define(:started_at,
+      :status,
+      :plans,
+      :up,
+      :down,
+      :rows,
+      :root,
+      :running,
+      :live_up,
+      :live_down,
+      :selected,
+      :dialog,
+      :help,
+      :about,
+      :hidden) do
+      def initialize(selected: nil, dialog: nil, help: false, about: nil, hidden: 0, **rest) = super
+    end
+
+    # @!attribute [r] key
+    #   @return [String] `"001.00/leah-researcher"`, what selection and the
+    #     keyboard address a row by
+    # @!attribute [r] file
+    #   @return [String] the document holding the agent's latest ledger line
+    # @!attribute [r] pr
+    #   @return [Hash, nil] `{number:, url:, rejected:}` once the plan is at
+    #     the review stage
+    # @!attribute [r] state
+    #   @return [Symbol] :running, :done, :failed or :stuck
+    # @!attribute [r] phase
+    #   @return [Symbol, nil] the clock's phase while running
+    # @!attribute [r] frame
+    #   @return [Integer] spinner frame counter
+    # @!attribute [r] history
+    #   @return [Array<String>] what the agent has said, newest first, for
+    #     `run --scroll-height` to show more than the latest line of
+    Board::Row = Data.define(:key,
+      :at,
+      :ordinal,
+      :file,
+      :agent,
+      :role,
+      :round,
+      :rounds,
+      :model,
+      :remaining,
+      :phase,
+      :up,
+      :down,
+      :message,
+      :state,
+      :pr,
+      :frame,
+      :bold,
+      :elapsed,
+      :subagents,
+      :history) do
+      def initialize(pr: nil, phase: nil, remaining: nil, frame: 0, bold: false, message: nil,
+        elapsed: 0, subagents: 0, history: [], **rest)
+        super
+      end
+
+      # @param history [Array<String>] newest first
+      # @param text [String, nil]
+      # @return [Array<String>] +text+ on top, unless it is empty or repeats
+      #   the newest line: an agent restating its activity is not news
+      def self.remember(history, text)
+        text = text.to_s.strip
+        return history if text.empty? || history.first == text
+
+        [text, *history].first(Board::Row::HISTORY)
+      end
+
+      # @return [Boolean]
+      def running? = state == :running
+    end
+
+    # Statuses a row keeps, whatever the screen shows of them. A cap, so a
+    # long-running agent's chatter cannot grow without bound. Outside the
+    # `Data.define` block, whose constants would land on Agentilda instead.
+    Board::Row::HISTORY = 50
+  end
+end