agentilda 2.0.3 → 2.0.4

data/lib/agentilda/brief.rb

@@ -1,283 +0,0 @@
-# frozen_string_literal: true
-
-require "tty/command"
-
-module Agentilda
-  # A new plan's opening brief: four questions, and a best-effort first pass
-  # at answering them from what the project already has on disk.
-  #
-  # This is for work that does not exist yet. A plan created `--after` a
-  # shipped pull request already has its facts — {CLI::Create} hands those to
-  # `yoda-writer`, which reconstructs a specification from a diff, not this.
-  # Guessing at a diff and guessing at a feature nobody has built are
-  # different jobs, and conflating them is how a retroactive spec ends up
-  # full of hedges about something that already, provably, happened.
-  #
-  # The four headings are the brief `leah-researcher` and `yoda-writer` both
-  # read *before* their own chapters: what research needs to settle is a
-  # question about the gaps in `## What already exists`, so a scaffold
-  # missing that heading forces both of them to first reconstruct a boundary
-  # this class already had for free — it just created the folder.
-  class Brief
-    # The half-agent's name. It has no `agents/*.md` of its own on purpose —
-    # a roster entry would put it in `Runner`'s routing, and this pass runs
-    # only inside `create`. The name exists so the UI can show it the same
-    # way it shows `leah-researcher` and `yoda-writer` on their spinner lines.
-    AGENT_NAME = "anakin-briefster"
-
-    HEADINGS = [
-      "What we are trying to achieve",
-      "Why it matters",
-      "What already exists",
-      "What research needs to settle"
-    ].freeze
-
-    # Read whole into the drafting prompt, in order, so the model sees the
-    # project's own account of itself before it sees the topic.
-    CONTEXT_FILES = %w[CLAUDE.md AGENTS.md README.md].freeze
-
-    # Relative to the repository root. Not every project keeps one — a
-    # missing backlog is silently skipped, not an error.
-    BACKLOG_FILE = File.join(Agentilda::PLANS_DIR, "BACKLOG.md")
-
-    # Long enough for a handful of Read/Grep/Glob calls over a local
-    # checkout; short enough that a hung `claude` does not stall `create`
-    # past the point where the scaffold is already there to open by hand.
-    TIMEOUT = 60
-
-    # The fastest model, and the draft is disposable: the prompt prefers an
-    # honest blank over a clever inference, so there is no reasoning premium
-    # worth paying a larger model for inside a 60-second budget.
-    BRIEF_MODEL = "haiku"
-
-    # Read-only, and no `Bash` — this pass surveys what the repository
-    # already says about itself, it does not go looking further. That is
-    # `leah-researcher`'s job, and denying her tools here is what keeps the
-    # two from quietly doing the same work twice.
-    ALLOWED_TOOLS = %w[Read Grep Glob Edit].freeze
-    DENIED_TOOLS = %w[WebFetch WebSearch Bash].freeze
-
-    # The `stdout:` and `stderr:` sections of a {TTY::Command::ExitError}
-    # message. stdout runs until stderr starts; stderr runs to the end, because
-    # what `claude` prints there is not guaranteed to be one line.
-    STDOUT_SECTION = /^[ \t]*stdout:[ \t]*(.*?)(?=\n[ \t]*stderr:|\z)/m
-    STDERR_SECTION = /^[ \t]*stderr:[ \t]*(.*)\z/m
-
-    # How much of what `claude` said survives into a one-line report.
-    REASON_LIMIT = 300
-
-    # A one-line account of a failed `claude` run, built from the error rather
-    # than its first line: that first line is the escaped prompt, several
-    # thousand characters of it, and reporting it says an invocation failed,
-    # at length, and never why.
-    #
-    # Both streams are kept because they carry different halves. `claude`
-    # reports its own failures on stdout; the line naming the *cause* of a 401
-    # (`ANTHROPIC_API_KEY ... takes precedence over your claude.ai login`) is
-    # on stderr. {Executor} used to own this; it now reads a child process
-    # directly and has no exit error to parse, so the briefer keeps it.
-    #
-    # @param error [TTY::Command::ExitError]
-    # @return [String]
-    def self.failure_reason(error)
-      status = error.message[/^[ \t]*exit status:[ \t]*(\S+)/, 1]
-      outcome = status ? "exited #{status}" : "failed"
-      said = [STDOUT_SECTION, STDERR_SECTION]
-             .filter_map { |section| tail(error.message[section, 1]) }
-             .join(" | ")
-
-      said.empty? ? "#{outcome} and said nothing" : "#{outcome}: #{said}"
-    end
-
-    # @param text [String, nil]
-    # @return [String, nil] the last few meaningful lines, on one line
-    def self.tail(text)
-      lines = text.to_s.split("\n").map(&:strip).reject { |line| line.empty? || line == "Nothing written" }
-      return nil if lines.empty?
-
-      joined = lines.last(3).join(" ")
-      joined.length > REASON_LIMIT ? "#{joined[0, REASON_LIMIT - 1]}..." : joined
-    end
-    private_class_method :tail
-
-    # @param path [String] the new plan folder, absolute
-    # @param title [String] the feature's proper name, e.g. "Tax Rule DSL"
-    # @param root [String] repository root, for project context and `--add-dir`
-    # @param command [TTY::Command]
-    # @param timeout [Integer] seconds before the drafting attempt is abandoned
-    # @param dry_run [Boolean] plan the invocation, do not run it
-    # @param seed [String, nil] what the author already wrote about the
-    #   feature (`create --from`); opens spec.md and outranks the repo survey
-    def initialize(
-      path:,
-      title:,
-      root:,
-      command: TTY::Command.new(printer: :null),
-      timeout: TIMEOUT,
-      dry_run: false,
-      seed: nil
-    )
-      @path = path
-      @title = title
-      @root = File.expand_path(root)
-      @command = command
-      @timeout = timeout
-      @dry_run = dry_run
-      @seed = seed.to_s.strip.then { |s| s.empty? ? nil : s }
-    end
-
-    # @return [String]
-    attr_reader :path, :title, :root
-
-    # @return [String, nil]
-    attr_reader :seed
-
-    # @return [String] absolute path to the spec, whether or not it exists yet
-    def spec_path = File.join(path, "spec.md")
-
-    # The title and four empty headings — and, when `create --from` supplied
-    # one, the author's own prose between them, so the file already says
-    # something even if the drafting attempt never returns.
-    #
-    # @return [String]
-    def scaffold
-      opening = seed ? "#{seed}\n\n" : ""
-      "# #{title}\n\n#{opening}" + HEADINGS.map { |h| "## #{h}\n\n" }.join("\n")
-    end
-
-    # @return [String] where it was written
-    def write_scaffold!
-      File.write(spec_path, scaffold)
-      spec_path
-    end
-
-    # Make a best-effort attempt at the four headings, in place, by shelling
-    # out to `claude` the same way {Executor} does for a specialist agent.
-    # A failure here is not this method's to hide: the scaffold {#write_scaffold!}
-    # already wrote stands on its own, so the caller reports the failure and
-    # moves on rather than treating it as fatal to `create`.
-    #
-    # @return [Array(Boolean, String)] ok, and a one-line note
-    def attempt!
-      return [true, "dry run — would draft from project context"] if @dry_run
-
-      begin
-        @command.run(*invocation, timeout: @timeout)
-      rescue TTY::Command::TimeoutExceeded
-        return [false, "timed out after #{@timeout}s"]
-      rescue TTY::Command::ExitError => e
-        return [false, "claude #{self.class.failure_reason(e)}"]
-      end
-
-      [true, "drafted"]
-    end
-
-    # Exposed so a spec can assert the boundary without running anything.
-    #
-    # @return [Array<String>]
-    def invocation
-      ["claude",
-       "-p", prompt, "--add-dir", root,
-       "--model", BRIEF_MODEL,
-       "--allowedTools", ALLOWED_TOOLS.join(","),
-       "--disallowedTools", DENIED_TOOLS.join(",")]
-    end
-
-    private
-
-    # @return [String]
-    def prompt
-      <<~PROMPT
-        #{author_statement}A new plan folder was just created for a feature that does not exist
-        yet: "#{title}".
-
-        You have 50 seconds. Explore the codebase for the first thirty and
-        write for the last twenty; the process is killed at sixty and an
-        unwritten draft is lost.
-
-        #{spec_path} holds a title and four empty headings:
-
-        #{HEADINGS.map { |h| "  * #{h}" }.join("\n")}
-
-        Make a best-effort first pass at each, drawn only from what THIS
-        project already has on disk under #{root} — its own docs, its own
-        conventions, code already built, and anything already downloaded or
-        gathered that bears on "#{title}". Read/Grep/Glob freely to look for
-        it; do not invent facts and do not research the web. Where the
-        repository gives you nothing to go on, leave that heading's body as
-        a short, honest one-line note saying so, e.g. "_Nothing in the repo
-        speaks to this yet — needs research._" A human completes this
-        afterward, and a confident-sounding guess costs them more to unwind
-        than an honest blank.
-
-        `## What already exists` matters most: name specific files, modules
-        or prior work you found, not just that "some code exists" — that is
-        exactly the context a researcher picking this up next cannot see for
-        themselves without being told where to look.
-
-        #{context}
-        #{backlog}
-        Edit #{spec_path} in place. Keep the title#{", the author's opening prose" if seed} and the four `##`
-        headings exactly as they are, in order; add prose under them; write
-        nothing outside them; touch no other file.
-      PROMPT
-    end
-
-    # The author's own words lead the prompt, ahead of even the feature's
-    # announcement, because they outrank everything this pass could survey:
-    # where the seed and the repository disagree, the seed is the intent and
-    # the repository is merely the past.
-    #
-    # @return [String] empty without a seed
-    def author_statement
-      return "" unless seed
-
-      <<~STATEMENT
-        The author has already written the following about this feature. It
-        is the primary source: where it answers one of the headings, draw
-        from it first, and use the repository survey below only to supplement
-        it — never to contradict it.
-
-        #{seed}
-
-      STATEMENT
-    end
-
-    # AGENTS.md is commonly a symlink to CLAUDE.md; realpath-deduping keeps
-    # the shared content from being inlined twice into every drafting prompt.
-    #
-    # @return [String]
-    def context
-      seen = []
-      found = CONTEXT_FILES.filter_map { |name|
-        file = File.join(root, name)
-        next unless File.file?(file)
-
-        real = File.realpath(file)
-        next if seen.include?(real)
-
-        seen << real
-        "### #{name}\n\n#{File.read(file, encoding: "UTF-8")}"
-      }
-      return "" if found.empty?
-
-      "## Project context\n\n#{found.join("\n\n")}\n"
-    end
-
-    # A relevant line in the project's own backlog is worth more than
-    # anything this pass could infer on its own — it is the one place "why
-    # now" might already be written down.
-    #
-    # @return [String]
-    def backlog
-      file = File.join(root, BACKLOG_FILE)
-      return "" unless File.file?(file)
-
-      "## #{BACKLOG_FILE}\n\n" \
-        "If this backlog mentions \"#{title}\", treat that entry as " \
-        "authoritative for `## Why it matters` — it is the project's own " \
-        "statement of intent.\n\n" \
-        "#{File.read(file, encoding: "UTF-8")}\n"
-    end
-  end
-end

data/lib/agentilda/child.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # One `claude` process the harness started and therefore owns.
-  #
-  # `TTY::Command` never exposes the pid it spawned, so the executor used to
-  # find its child by scraping `ps` for a fresh `claude` under this process
-  # and could never safely signal it. Kill (`k`) and the sixty-second
-  # backstop after STOP both need a pid that is certainly ours, so the
-  # process is spawned here and the pid kept.
-  #
-  # stderr is folded into the same pipe as stdout: `claude` prints the cause
-  # of a failure there, and the transcript keeps non-JSON lines for exactly
-  # that reason.
-  class Child
-    # @param argv [Array<String>]
-    # @param chdir [String, nil]
-    # @return [Agentilda::Child]
-    def self.spawn(argv, chdir: nil)
-      reader, writer = IO.pipe
-      options = { out: writer, err: writer, in: File::NULL, unsetenv_others: true }
-      options[:chdir] = chdir if chdir
-      pid = Process.spawn(environment, *argv, **options)
-      writer.close
-      new(pid:, reader:)
-    end
-
-    # The environment the child starts in: the one Bundler was loaded under,
-    # less what Bundler itself put there. `exe/agentilda` pins `BUNDLE_GEMFILE`
-    # to its own Gemfile and `bundler/setup` adds `-rbundler/setup` to
-    # `RUBYOPT`; a child that inherited them would run every `bundle exec`,
-    # `standardrb` and `alock` against the harness's checkout instead of the
-    # worktree it was handed, and be told the gems that worktree's Gemfile adds
-    # are "not currently included in the bundle". Bundler knows exactly what it
-    # changed, so it is asked; without Bundler there is nothing to strip.
-    #
-    # @return [Hash{String => String}]
-    def self.environment
-      defined?(::Bundler) ? ::Bundler.unbundled_env : ENV.to_h
-    end
-
-    # @param pid [Integer]
-    # @param reader [IO]
-    def initialize(pid:, reader:)
-      @pid = pid
-      @reader = reader
-      @status = nil
-    end
-
-    # @return [Integer]
-    attr_reader :pid
-
-    # Read until the process closes its end. Runs on the caller's thread;
-    # the executor reads on the same thread it always did.
-    #
-    # @yieldparam text [String] whatever arrived, possibly a partial line
-    # @return [void]
-    def each_chunk
-      loop { yield @reader.readpartial(65_536) }
-    rescue IOError
-      @reader.close unless @reader.closed?
-    end
-
-    # @return [Process::Status]
-    def wait
-      @status ||= begin
-        _, status = Process.wait2(pid)
-        status
-      end
-    rescue Errno::ECHILD
-      @status
-    end
-
-    # @param signal [String]
-    # @return [void]
-    def kill(signal = "KILL")
-      Process.kill(signal, pid)
-    rescue Errno::ESRCH
-      # Already gone, which is what was wanted.
-    end
-
-    # @return [Boolean]
-    def alive?
-      return false if @status
-
-      Process.kill(0, pid)
-      true
-    rescue Errno::ESRCH
-      false
-    end
-  end
-end

data/lib/agentilda/clock.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # The advisory clock one invocation runs against.
-  #
-  # It never terminates the agent on its own. It writes into the control file
-  # the agent polls: a warning ten and five minutes out, a wrap-up request at
-  # one, STOP at zero. Only a process still alive {GRACE} seconds after STOP
-  # is killed, and that is the executor's act on this clock's say-so, so the
-  # agent has every chance to write its ledger line first.
-  #
-  # `now` is injectable so the moments can be tested without sleeping.
-  class Clock
-    # Seconds before the deadline, and what the control file says then.
-    # A moment already in the past when the clock starts is skipped: a five
-    # minute agent told "10 minutes left" at t=0 has been lied to.
-    WARNINGS = [
-      [600, "WARN: 10 minutes left"],
-      [300, "WARN: 5 minutes left"],
-      [60, "WRAP_UP: 1 minute left, write to disk now"]
-    ].freeze
-
-    # Seconds after STOP before {#on_expire} fires.
-    GRACE = 60
-
-    # @param seconds [Integer] the budget
-    # @param control [String] the invocation's control file
-    # @param on_expire [Proc] called once, GRACE seconds after STOP
-    # @param now [Proc] a monotonic clock reading
-    def initialize(seconds:, control:, on_expire:, now: -> { UI.monotonic })
-      @control = control
-      @on_expire = on_expire
-      @now = now
-      @mutex = Mutex.new
-      arm(seconds)
-    end
-
-    # @return [Integer] whole seconds left, floored at zero
-    def remaining = [@deadline - @now.call, 0].max.round
-
-    # @return [Symbol] :calm, :warned, :wrap_up, :stopped or :expired
-    attr_reader :phase
-
-    # Evaluate every moment once. Idempotent within a phase.
-    #
-    # @return [void]
-    def tick
-      @mutex.synchronize do
-        left = @deadline - @now.call
-        WARNINGS.each do |before, text|
-          next if @fired.include?(before) || left > before
-
-          @fired << before
-          Control.write(@control, text)
-          @phase = before == 60 ? :wrap_up : :warned
-        end
-        if left <= 0 && !@fired.include?(:stop)
-          @fired << :stop
-          Control.write(@control, Control::STOP)
-          @phase = :stopped
-        end
-        if @fired.include?(:stop) && !@fired.include?(:expired) && left <= -GRACE
-          @fired << :expired
-          @phase = :expired
-          @on_expire.call
-        end
-      end
-    end
-
-    # @return [self]
-    def start
-      @thread ||= Thread.new do
-        Thread.current.report_on_exception = false
-        loop do
-          tick
-          break if phase == :expired
-
-          sleep(1)
-        end
-      end
-      self
-    end
-
-    # @return [void]
-    def stop
-      @thread&.kill
-      @thread = nil
-    end
-
-    # Ten more minutes, or however many. The file is emptied so the next poll
-    # reads a reprieve, and every moment is re-armed against the new deadline.
-    #
-    # @param seconds [Integer]
-    # @return [void]
-    def extend!(seconds)
-      @mutex.synchronize do
-        @deadline += seconds
-        @fired = []
-        @phase = :calm
-        Control.write(@control, "")
-      end
-    end
-
-    private
-
-    # @param seconds [Integer]
-    # @return [void]
-    def arm(seconds)
-      @deadline = @now.call + seconds
-      @fired = WARNINGS.map(&:first).select { |before| before >= seconds }
-      @phase = :calm
-    end
-  end
-end

data/lib/agentilda/console.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # 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::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::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::Dispatcher]
-    # @return [void]
-    def attach(dispatcher) = @dispatcher = dispatcher
-
-    # Called by the dispatcher each tick.
-    #
-    # @param board [Agentilda::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