agentilda 2.0.1 → 2.0.4

data/lib/agentilda/control.rb

@@ -1,178 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-
-module Agentilda
-  # The side channel between a keypress and a running agent.
-  #
-  # `claude -p` takes no input once it starts, so the only way to reach an
-  # agent mid-flight is a file it has been told to poll: each invocation gets
-  # a control file of its own, named in its prompt, and a keypress writes a
-  # word into every file currently registered. Like everything else about the
-  # prompt this is a request — an agent deep in a tool call reads the file at
-  # its next step, not instantly — which is why {#quit!} also arms a deadline
-  # the {Executor} checks, so "quit" is eventually a guarantee too.
-  module Control
-    # What a keypress writes into a control file. One word, one line, so an
-    # agent can act on `File.read(path).strip` and nothing subtler.
-    WRAP_UP = "WRAP_UP"
-    STOP = "STOP"
-
-    # Ctrl-C: STOP, and the run will be started again, so the agent leaves
-    # a resume note before it goes. The prompt says what that note is.
-    INTERRUPT = "INTERRUPT"
-
-    # The clock's warnings start with this; the agent's prompt explains them.
-    WARN = "WARN"
-
-    # Seconds between {#quit!} and the harness terminating whatever is still
-    # running. Long enough to write files and a handoff note; short enough
-    # that q means quit rather than "quit eventually".
-    GRACE = 60
-
-    @mutex = Mutex.new
-    @files = []
-    @quit = false
-    @interrupted = false
-    @deadline = nil
-
-    class << self
-      # Register a fresh control file for one invocation and hand back its
-      # path, to be named in the agent's prompt.
-      #
-      # @param dir [String] where the file lives (the trace dir — outside the
-      #   repository for the same reason traces are)
-      # @param name [String] something findable: plan ordinal and agent name
-      # @return [String]
-      def register(dir, name)
-        FileUtils.mkdir_p(dir)
-        path = File.join(dir, "control-#{name}-#{Process.pid}-#{format("%04x", rand(0x10000))}")
-        File.write(path, "")
-        @mutex.synchronize { @files << path }
-        path
-      end
-
-      # Forget a finished invocation's file. The file itself is removed so a
-      # crashed run does not leave stale STOPs for the next one to find.
-      #
-      # @param path [String]
-      # @return [void]
-      def release(path)
-        @mutex.synchronize { @files.delete(path) }
-        FileUtils.rm_f(path)
-      end
-
-      # One line into one file, from the clock. Not a broadcast: a warning is
-      # about one agent's own deadline.
-      #
-      # @param path [String]
-      # @param text [String]
-      # @return [void]
-      def write(path, text)
-        File.write(path, text.empty? ? "" : "#{text}\n")
-      rescue SystemCallError
-        # The invocation finished and released its file; nothing to warn.
-      end
-
-      # `w`: every running agent is asked to finish the essential remainder
-      # as fast as it can. The loop itself keeps going.
-      #
-      # @return [void]
-      def wrap_up! = broadcast(WRAP_UP)
-
-      # `n`: every running agent is asked to write out what it has and end
-      # its turn. The loop keeps going — under chaining that is exactly what
-      # hands the plan to the next agent.
-      #
-      # @return [void]
-      def stop! = broadcast(STOP)
-
-      # `q`: {#stop!}, plus the loop ends after this round, plus a deadline —
-      # {GRACE} seconds from now — after which the {Executor} aborts whatever
-      # is still running rather than waiting on its goodwill.
-      #
-      # @return [void]
-      def quit!
-        stop!
-        @mutex.synchronize {
-          @quit = true
-          @deadline ||= UI.monotonic + GRACE
-        }
-      end
-
-      # Ctrl-C, the first time: {#quit!}, except that every running agent is
-      # told the run is being interrupted rather than stopped, so it writes
-      # down where it got to. A restart then reads that note instead of
-      # redoing, or half-redoing, the work.
-      #
-      # @return [void]
-      def interrupt!
-        broadcast(INTERRUPT)
-        @mutex.synchronize {
-          @quit = true
-          @interrupted = true
-          @deadline ||= UI.monotonic + GRACE
-        }
-      end
-
-      # @return [Boolean] whether `q` has been pressed
-      def quit? = @mutex.synchronize { @quit }
-
-      # @return [Boolean] whether Ctrl-C has been pressed
-      def interrupted? = @mutex.synchronize { @interrupted }
-
-      # Ctrl-C where no keyboard reads it: a run with no terminal to put in
-      # raw mode still gets the graceful first press and the hard second.
-      #
-      # A trap handler may not take a mutex, so the first press hands
-      # {#interrupt!} to a thread; the second raises, as Ctrl-C always has.
-      #
-      # @yieldreturn [Object]
-      # @return [Object] the block's value
-      def on_interrupt
-        previous = Signal.trap("INT") do
-          # A plain read, not {#interrupted?}: a trap handler may not lock.
-          raise Interrupt if @interrupted || @pending_interrupt
-
-          @pending_interrupt = true
-          Thread.new { interrupt! }
-        end
-        yield
-      ensure
-        @pending_interrupt = false
-        Signal.trap("INT", previous || "DEFAULT")
-      end
-
-      # @return [Boolean] whether the grace period after `q` has run out
-      def overdue?
-        @mutex.synchronize { !@deadline.nil? && UI.monotonic > @deadline }
-      end
-
-      # Back to rest, for the next `Runner#call` — and for the suite, where
-      # one example's q must not quit every example after it.
-      #
-      # @return [void]
-      def reset!
-        @mutex.synchronize {
-          @files.each { |f| FileUtils.rm_f(f) }
-          @files.clear
-          @quit = false
-          @interrupted = false
-          @deadline = nil
-        }
-      end
-
-      private
-
-      # @param word [String]
-      # @return [void]
-      def broadcast(word)
-        @mutex.synchronize { @files.dup }.each do |path|
-          File.write(path, "#{word}\n")
-        rescue SystemCallError
-          # A file whose invocation just finished is not an error to miss.
-        end
-      end
-    end
-  end
-end

data/lib/agentilda/creator.rb

@@ -1,125 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/monads"
-require "fileutils"
-
-require "agentilda/status"
-
-module Agentilda
-  # Mints new plan folders. Backs `/spec-create`.
-  #
-  # Every failure is a `Failure`, never an exception: creating a folder is the
-  # one place a typo becomes permanent, so the caller is made to look.
-  class Creator
-    include Dry::Monads[:result]
-
-    # The state a new plan opens in — a specification and nothing else yet.
-    DEFAULT_STATUS = :new
-
-    # The state a retroactive plan is born in: the work is live, but it has
-    # neither a specification nor a plan.
-    RETROACTIVE_STATUS = :retroactive
-
-    # @param dir [String] the `.plans` directory
-    def initialize(dir:)
-      @dir = File.expand_path(dir)
-    end
-
-    # @return [String] the `.plans` directory
-    attr_reader :dir
-
-    # Create a plan folder.
-    #
-    # @param words [Array<String>] the topic; becomes the slug
-    # @param after [String, nil] anchor for a retroactive plan, e.g. "002"
-    # @param status [String, Symbol, nil] override the default state
-    # @param prs [Array<Hash>, nil] pull requests to record, already fetched;
-    #   their presence is what makes the folder 🕰️ Retroactive rather than ⚪️
-    # @return [Dry::Monads::Result] Success(absolute path) or Failure(message)
-    def create(words:, after: nil, status: nil, prs: nil)
-      resolved = resolve_status(status, after) or
-        return Failure("unknown status: #{status}")
-
-      slug = self.class.slugify(words)
-      return Failure("the topic produced an empty slug") if slug.empty?
-
-      ordinal = after ? retroactive_ordinal(after) : Ordinal.next_major(existing)
-      return ordinal if ordinal.is_a?(Dry::Monads::Result)
-
-      build(ordinal, resolved, slug).fmap { |path| record_pull_requests(path, prs) }
-    rescue Agentilda::Error => e
-      Failure(e.message)
-    end
-
-    # @return [Array<Agentilda::Ordinal>] every number already taken
-    def existing
-      @existing ||= begin
-        return [] unless File.directory?(dir)
-
-        Dir.children(dir)
-           .select { |c| File.directory?(File.join(dir, c)) }
-           .filter_map { |c| Ordinal.from_dirname(c) }
-      end
-    end
-
-    # Turn free text into the kebab tail of a folder name.
-    #
-    # @param words [Array<String>, String]
-    # @return [String] possibly empty, which the caller must reject
-    def self.slugify(words)
-      Array(words).join(" ").downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
-    end
-
-    private
-
-    # @param status [String, Symbol, nil]
-    # @param after [String, nil]
-    # @return [Agentilda::Status, nil]
-    def resolve_status(status, after)
-      return Agentilda.status(status) if status
-
-      STATUS_BY_KEY.fetch(after ? RETROACTIVE_STATUS : DEFAULT_STATUS)
-    end
-
-    # @param after [String]
-    # @return [Agentilda::Ordinal, Dry::Monads::Result]
-    def retroactive_ordinal(after)
-      anchor = Ordinal.parse(after) or return Failure("not a plan number: #{after}")
-
-      unless existing.any? { |o| o.major == anchor.major }
-        return Failure("no plan #{format("%03d", anchor.major)} to anchor against — " \
-                       "a retroactive plan names the plan its work landed after")
-      end
-
-      Ordinal.next_minor(existing, major: anchor.major)
-    end
-
-    # Write the pull requests the folder was created from, so 🕰️ Retroactive
-    # is justified the moment the folder exists — that state means "the work is
-    # live and undocumented", and it is the recorded pull requests that make
-    # the first half of that true.
-    #
-    # @param path [String] the new folder
-    # @param prs [Array<Hash>, nil]
-    # @return [String] the path, unchanged
-    def record_pull_requests(path, prs)
-      return path if prs.nil? || prs.empty?
-
-      File.write(File.join(path, PullRequests::FILENAME), PullRequests.render(prs))
-      path
-    end
-
-    # @param ordinal [Agentilda::Ordinal]
-    # @param status [Agentilda::Status]
-    # @param slug [String]
-    # @return [Dry::Monads::Result]
-    def build(ordinal, status, slug)
-      target = File.join(dir, Agentilda.plan_dirname(ordinal, status, slug))
-      return Failure("already exists: #{File.basename(target)}") if File.exist?(target)
-
-      FileUtils.mkdir_p(target)
-      @existing = nil
-      Success(target)
-    end
-  end
-end

data/lib/agentilda/dashboard.rb

@@ -1,219 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # 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::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 = Executor::Handle.new
-        @state = :running
-        @update = nil
-        @history = []
-        @finished_at = nil
-      end
-
-      # @param update [Agentilda::Transcript::Progress]
-      # @return [void]
-      def call(update)
-        super
-        @update = update
-        return unless update.activity
-
-        @message = update.activity
-        @history = 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 = Board::Row.remember(@history, reason)
-        finish(:failed)
-      end
-
-      # @return [Agentilda::Board::Row]
-      def row
-        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::Screen::Ratatui]
-    # @yieldparam dashboard [Agentilda::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::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::Board]
-    def board
-      rows = visible.map(&:row)
-      running = rows.select(&:running?)
-      Board.new(started_at: @started_at,
-        status: 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

data/lib/agentilda/dev_work.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require "agentilda/status"
-
-module Agentilda
-  # Telling "this belongs to no specification" apart from "nobody could tell".
-  #
-  # Both end up without a plan number, and filing them under one marker loses
-  # the difference between a finished thought and an open question. A
-  # dependency bump genuinely implements no specification and never will —
-  # that is an assertion, and `[dev]` records it. A pull request that adds
-  # Schedule K-1 for four tax years plainly implements *something*; nothing
-  # here could work out what, and `[none]` records that instead, as a job left
-  # for a human rather than a verdict.
-  #
-  # The bar for `[dev]` is deliberately high. Marking real work as `[dev]`
-  # tells everyone afterwards it was never worth a plan, and nobody re-opens a
-  # question that looks settled. `[none]` is visibly unfinished, so the cost of
-  # guessing wrong in that direction is somebody spending a minute on it.
-  module DevWork
-    module_function
-
-    # Titles that say what they are: dependency bumps, release chores, CI.
-    TITLES = [
-      /\Abump\s+\S+\s+from\s+\S+\s+to\s+\S+/i,
-      /\A(?:chore|ci|build|deps|style|refactor)(?:\([^)]*\))?:/i,
-      /\Abump\s+(?:to\s+)?v?\d+\.\d+/i
-    ].freeze
-
-    # Paths that are how the project is built rather than what it does.
-    PLUMBING = %r{\A(?:\.github/|\.circleci/|\.devcontainer/|bin/|scripts/|
-                       Dockerfile|\.dockerignore|Gemfile(?:\.lock)?|justfile|Rakefile|
-                       \.rubocop\.ya?ml|\.standard\.ya?ml|\.gitignore|\.tool-versions)}x
-
-    # Files that say nothing either way, so they neither prove plumbing nor
-    # disprove it — every pull request in this tool's world touches `.plans`.
-    NEUTRAL = %r{\A(?:#{PLANS_DIR}/|CHANGELOG|README)}
-
-    # @param title [String]
-    # @param files [Array<String>] paths in the diff
-    # @return [Boolean] whether this can be *asserted* to implement no plan
-    def developer?(title, files = [])
-      return true if TITLES.any? { |pattern| title.to_s.match?(pattern) }
-
-      judged = Array(files).reject { |path| path.match?(NEUTRAL) }
-      return false if judged.empty?
-
-      judged.all? { |path| path.match?(PLUMBING) }
-    end
-
-    # @param title [String]
-    # @param files [Array<String>]
-    # @return [String] the marker to stamp on it
-    def marker(title, files = []) = developer?(title, files) ? NO_PLAN_PREFIX : NONE_PREFIX
-  end
-end