agentilda 1.0.3

data/lib/agentilda/tally.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # What a `run` cost, once it is over.
+  #
+  # The loop reports movement — which plan went from ⭐️ to 🟡, which agent
+  # failed and why — and says nothing about the bill. A round of five agents
+  # against a large repository spends several million tokens and the better
+  # part of an hour, and until this existed the only record of that was a
+  # directory of trace files nobody reads.
+  #
+  # {#render} returns a string and prints nothing, so the caller decides where
+  # it goes, the same way {Reporter} works.
+  class Tally
+    # One agent's share of the run, added up across every round it ran in.
+    #
+    # @!attribute [r] name
+    #   @return [String]
+    # @!attribute [r] invocations
+    #   @return [Integer] times this agent was started
+    # @!attribute [r] subagents
+    #   @return [Integer] sub-agents it spawned, across all of them
+    # @!attribute [r] up
+    #   @return [Integer] tokens sent, sub-agent spend included
+    # @!attribute [r] down
+    #   @return [Integer] tokens generated
+    # @!attribute [r] seconds
+    #   @return [Float] how long it was running, added up
+    Row = Data.define(:name, :invocations, :subagents, :up, :down, :seconds)
+
+    # Cells per column, so the header, the rows and the rule cannot drift.
+    WIDTHS = {name: 22, invocations: 6, subagents: 11, up: 9, down: 9, seconds: 8}.freeze
+
+    # @param attempts [Array<Agentilda::Runner::Attempt>]
+    # @param seconds [Float] wall clock for the whole loop, which is not the
+    #   sum of the agents' own times: several of them run at once
+    # @param rounds [Integer]
+    def initialize(attempts:, seconds:, rounds: 0)
+      @attempts = attempts.reject { |a| a.ordinal == "?" }
+      @seconds = seconds
+      @rounds = rounds
+    end
+
+    # @return [Array<Agentilda::Runner::Attempt>]
+    attr_reader :attempts
+
+    # @return [Float] wall clock
+    attr_reader :seconds
+
+    # @return [Integer]
+    attr_reader :rounds
+
+    # Plans an agent was actually started against, counted once each however
+    # many rounds they took.
+    #
+    # @return [Integer]
+    def plans = attempts.map(&:ordinal).uniq.size
+
+    # @return [Integer] tokens sent, everything included
+    def up = attempts.sum(&:up)
+
+    # @return [Integer] tokens generated
+    def down = attempts.sum(&:down)
+
+    # @return [Integer] sub-agents spawned by every agent in the run
+    def subagents = attempts.sum(&:subagents)
+
+    # Sub-agent spend that arrived as one number. `claude` reports what a
+    # sub-agent cost without splitting it between the two directions, so this
+    # much of {#up} is really up and down together.
+    #
+    # @return [Integer]
+    def delegated = attempts.sum(&:delegated)
+
+    # @return [Float] seconds of agent time, added up across all of them
+    def busy = attempts.sum(&:seconds)
+
+    # How many agents were running at any given moment, averaged over the
+    # run: agent-seconds divided by wall-clock seconds. Below the `-j` ceiling
+    # by however much the round spent waiting for its slowest member.
+    #
+    # @return [Float]
+    def concurrency = seconds.positive? ? busy / seconds : 0.0
+
+    # @return [Array<Agentilda::Tally::Row>] one per agent, dearest first
+    def by_agent
+      attempts.group_by(&:agent).map { |name, list|
+        Row.new(name:, invocations: list.size, subagents: list.sum(&:subagents),
+          up: list.sum(&:up), down: list.sum(&:down), seconds: list.sum(&:seconds))
+      }.sort_by { |row| -row.up }
+    end
+
+    # @return [String] the table and the summary line under it
+    def render
+      return summary if attempts.empty?
+
+      ([header, rule] + by_agent.map { |row| line(row) } + [rule, totals, "", summary]).join("\n")
+    end
+
+    # @return [String] the one-line version, for a box
+    def summary
+      [
+        "#{plans} plan#{"s" unless plans == 1} addressed",
+        "#{rounds} round#{"s" unless rounds == 1}",
+        duration(seconds),
+        "#{format("%.1f", concurrency)} agents at a time",
+        "↑ #{UI.abbreviate(up)} ↓ #{UI.abbreviate(down)}"
+      ].join(" · ") + delegation
+    end
+
+    private
+
+    # @return [String] the caveat, where there is one to make
+    def delegation
+      return "" if delegated.zero?
+
+      "\n#{subagents} sub-agent#{"s" unless subagents == 1} reported #{UI.abbreviate(delegated)} " \
+      "tokens without splitting them, counted above as ↑."
+    end
+
+    # @return [String]
+    def header
+      cell("Agent", :name) + %i[invocations subagents up down seconds]
+        .zip(["runs", "sub-agents", "↑", "↓", "time"])
+        .map { |key, text| right(text, key) }.join
+    end
+
+    # @return [String]
+    def rule = WIDTHS.values.map { |width| "─" * (width - 1) + " " }.join
+
+    # @param row [Agentilda::Tally::Row]
+    # @return [String]
+    def line(row)
+      cell(row.name, :name) + right(row.invocations.to_s, :invocations) +
+        right(row.subagents.to_s, :subagents) + right(UI.abbreviate(row.up), :up) +
+        right(UI.abbreviate(row.down), :down) + right(duration(row.seconds), :seconds)
+    end
+
+    # @return [String]
+    def totals
+      cell("", :name) + right(attempts.size.to_s, :invocations) + right(subagents.to_s, :subagents) +
+        right(UI.abbreviate(up), :up) + right(UI.abbreviate(down), :down) + right(duration(busy), :seconds)
+    end
+
+    # @param text [String]
+    # @param key [Symbol]
+    # @return [String] padded to its column, left-justified
+    def cell(text, key) = UI.fit(text, WIDTHS.fetch(key))
+
+    # @param text [String]
+    # @param key [Symbol]
+    # @return [String] padded to its column, right-justified
+    def right(text, key)
+      width = WIDTHS.fetch(key) - 1
+      text = UI.fit(text, width).rstrip
+      UI.fit("", width - UI.display_width(text)) + text + " "
+    end
+
+    # @param seconds [Numeric]
+    # @return [String] e.g. "42s", "12m40s", "1h04m"
+    def duration(seconds)
+      total = seconds.to_i
+      return "#{total}s" if total < 60
+      return "#{total / 60}m#{format("%02ds", total % 60)}" if total < 3600
+
+      "#{total / 3600}h#{format("%02dm", (total % 3600) / 60)}"
+    end
+  end
+end

data/lib/agentilda/transcript.rb

@@ -0,0 +1,435 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Agentilda
+  # What an agent is doing, while it is still doing it.
+  #
+  # `claude -p` prints nothing until it exits, so a fifteen-minute agent used to
+  # sit behind a spinner that said only its name. Asked for `--output-format
+  # stream-json` it emits one JSON object per line as it works, and this turns
+  # that stream into the short phrase a spinner line has room for: "editing
+  # spec.md", "reading plan.md", whatever the agent last said about itself.
+  #
+  # Three things make this less trivial than parsing JSON.
+  #
+  # Chunks arrive from `readpartial`, so a line is split across two of them as
+  # often as not. {#push} buffers and only ever parses whole lines.
+  #
+  # Not every line is JSON. `claude` reports its own failures as prose on
+  # stdout, and the 401 that cost a whole run three minutes an agent was one of
+  # those. Those lines are kept in {#plain} so a failure can still be explained
+  # by what was actually printed.
+  #
+  # The reader runs on its own thread, so {#activity} is written from one
+  # thread and read from another. It is a single assignment of an immutable
+  # string, which is why there is no lock here.
+  #
+  # Every line is also kept verbatim in an optional trace file, written before
+  # anything is made of it, so a run that failed can be read back afterwards
+  # even where this parser made nothing of an event it had never seen. See
+  # {Executor::TRACE_DIR} for where those land and how to read one.
+  class Transcript
+    # What one line of the display knows: the phrase, and the meter beside it.
+    #
+    # Yielded whole rather than as loose arguments so a caller cannot render
+    # half an update, and frozen so the reader thread and the drawing thread
+    # are never looking at the same mutable object.
+    #
+    # @!attribute [r] activity
+    #   @return [String, nil] the last thing the agent was seen doing
+    # @!attribute [r] up
+    #   @return [Integer] tokens sent, cache reads included
+    # @!attribute [r] down
+    #   @return [Integer] tokens generated
+    # @!attribute [r] subagents
+    #   @return [Integer] sub-agents spawned so far
+    # @!attribute [r] pid
+    #   @return [Integer, nil] the `claude` process, once the harness has
+    #     found it — nil until then, and for callers that never look
+    Progress = Data.define(:activity, :up, :down, :subagents, :pid) do
+      def initialize(pid: nil, **rest) = super
+    end
+
+    # The one kind of line the trace does not keep.
+    #
+    # `--include-partial-messages` is what makes {#meter} possible, and it
+    # also emits one event per handful of generated characters. Those are the
+    # bulk of the stream and the only part of it nothing reads back: a
+    # fifteen-minute agent writes thousands of them, and they would bury the
+    # events a failed run is actually read for. Matched as a substring rather
+    # than parsed because the trace is written before a line is understood,
+    # which is what makes it complete when the process dies mid-invocation.
+    DELTA_NOISE = '"content_block_delta"'
+
+    # Longest phrase a spinner line can carry without wrapping into the next.
+    LIMIT = 56
+
+    # How each tool reads as something being done, rather than as a tool name.
+    # A spinner says what is happening; "Edit" is a noun and says nothing.
+    VERBS = {
+      "Read" => "reading", "Write" => "writing", "Edit" => "editing",
+      "MultiEdit" => "editing", "NotebookEdit" => "editing",
+      "Bash" => "running", "Grep" => "searching for", "Glob" => "looking for",
+      "Task" => "delegating", "TodoWrite" => "planning",
+      "WebFetch" => "fetching", "WebSearch" => "searching the web for"
+    }.freeze
+
+    # The input key worth naming, per tool, in the order we would rather say it.
+    # `description` outranks `command` deliberately: Claude's Bash tool carries
+    # a written summary of why it is running something, and "Read NOTES.md" is
+    # a better spinner line than sixty characters of absolute path.
+    SUBJECTS = %w[file_path pattern description command query url].freeze
+
+    # @param trace [String, nil] a file to keep the raw stream in, or nil to
+    #   keep none. Every line is written before anything is made of it, so a
+    #   run that failed can be read back afterwards even where this parser made
+    #   nothing of an event it had never seen.
+    # @yieldparam progress [Agentilda::Transcript::Progress] each time the
+    #   agent moves on to something new, and each time the meter moves
+    def initialize(trace: nil, &on_progress)
+      @on_progress = on_progress
+      @buffer = +""
+      @plain = []
+      @activity = nil
+      @result = nil
+      @error = nil
+      @trace_path = trace
+      @trace = trace && File.open(trace, "a")
+      @tools = 0
+      @main = {up: 0, down: 0}
+      @streamed = {}
+      @tasks = {}
+      @spawned = 0
+    end
+
+    # Everything sent to the model, which on any turn after the first is
+    # mostly cache reads: a typical agent turn is two fresh input tokens
+    # against a quarter of a million read back from cache. Counting only the
+    # fresh ones would report a fifteen-minute agent as having said nothing.
+    #
+    # @return [Integer]
+    def up = @main[:up] + streamed[:up] + delegated
+
+    # @return [Integer] tokens the model generated, thinking included
+    def down = @main[:down] + streamed[:down]
+
+    # @return [Integer] sub-agents this invocation started
+    attr_reader :spawned
+
+    # The `claude` process this transcript is reading, set by the {Executor}
+    # once it has found the child, so the spinner line can name a pid someone
+    # can actually `ps` while the agent runs.
+    #
+    # @return [Integer, nil]
+    attr_accessor :pid
+
+    # Sub-agent totals arrive as one number with no split between what went up
+    # and what came back, so they are counted as {#up}. They are held here as
+    # well, unmixed, because a report that says "of which N could not be
+    # split" is honest and one that quietly rounds is not.
+    #
+    # @return [Integer]
+    def delegated
+      @tasks.reject { |_, task| @streamed.key?(task[:tool_use_id]) }
+        .sum { |_, task| task[:total] }
+    end
+
+    # @return [Agentilda::Transcript::Progress] a snapshot, safe to keep
+    def progress = Progress.new(activity: @activity, up:, down:, subagents: @spawned, pid: @pid)
+
+    # @return [Integer] how many tool calls have gone past, which is the one
+    #   honest measure of how much work an agent that says "done" actually did
+    attr_reader :tools
+
+    # @return [String, nil] the file the raw stream is being kept in
+    attr_reader :trace_path
+
+    # @return [String, nil] the last thing the agent was seen doing
+    attr_reader :activity
+
+    # @return [String, nil] the final text, from the `result` event
+    attr_reader :result
+
+    # @return [Array<String>] lines that were not JSON, in order
+    attr_reader :plain
+
+    # @return [Boolean] whether the stream reported its own failure
+    def failed? = !@error.nil?
+
+    # @return [String, nil] what the agent said went wrong
+    attr_reader :error
+
+    # Feed one chunk of stdout. Safe to call with a partial line, which is the
+    # normal case.
+    #
+    # @param chunk [String, nil]
+    # @return [void]
+    def push(chunk)
+      return if chunk.nil?
+
+      @buffer << chunk
+      while (index = @buffer.index("\n"))
+        line = @buffer.slice!(0..index).chomp
+        consume(line)
+      end
+    end
+
+    # Whatever is left when the process exits, which may be a last line with no
+    # newline after it.
+    #
+    # @return [void]
+    def finish
+      consume(@buffer.slice!(0..-1).to_s)
+      @trace&.close
+      @trace = nil
+    end
+
+    private
+
+    # @param line [String]
+    # @return [void]
+    def consume(line)
+      text = line.strip
+      return if text.empty?
+
+      record(text)
+
+      unless text.start_with?("{")
+        @plain << text
+        return
+      end
+
+      event = begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        @plain << text
+        return
+      end
+
+      handle(event)
+    end
+
+    # Written before the line is understood, and flushed, so the file is a
+    # complete record even when the process dies mid-invocation.
+    #
+    # @param text [String]
+    # @return [void]
+    def record(text)
+      return unless @trace
+      return if text.include?(DELTA_NOISE)
+
+      @trace.write("#{text}\n")
+      @trace.flush
+    end
+
+    # @param event [Hash]
+    # @return [void]
+    def handle(event)
+      case event["type"]
+      when "assistant"
+        @tools += tool_calls(event)
+        announce(phrase_for(event))
+      when "stream_event" then meter(event)
+      when "system" then delegation(event)
+      when "result" then record_result(event)
+      end
+    end
+
+    # @param event [Hash]
+    # @return [Integer] how many tools this one message called
+    def tool_calls(event)
+      blocks = event.dig("message", "content")
+      return 0 unless blocks.is_a?(Array)
+
+      blocks.count { |block| block.is_a?(Hash) && block["type"] == "tool_use" }
+    end
+
+    # Where the token count comes from.
+    #
+    # Only `message_delta` is trusted. The `assistant` events carry a usage
+    # block too, and its input side is right, but its `output_tokens` is the
+    # placeholder the API sends when a message *starts*: a four-thousand-token
+    # answer reports 2 there. `message_delta` closes each message with the
+    # settled figure for both directions, which is why {Executor} asks for
+    # `--include-partial-messages` at all.
+    #
+    # A message from a sub-agent carries `parent_tool_use_id`, and is kept in
+    # its own bucket so {#delegated} knows not to count that sub-agent twice.
+    #
+    # @param event [Hash]
+    # @return [void]
+    def meter(event)
+      return unless event.dig("event", "type") == "message_delta"
+
+      usage = event.dig("event", "usage") or return
+      bucket = bucket_for(event["parent_tool_use_id"])
+      bucket[:up] += usage.values_at("input_tokens", "cache_creation_input_tokens",
+        "cache_read_input_tokens").compact.sum
+      bucket[:down] += usage["output_tokens"].to_i
+      publish
+    end
+
+    # @param parent [String, nil] the tool call a sub-agent's message belongs to
+    # @return [Hash] the counters that message belongs in
+    def bucket_for(parent)
+      return @main if parent.nil?
+
+      @streamed[parent] ||= {up: 0, down: 0}
+    end
+
+    # @return [Hash] every streamed sub-agent's counters, added together
+    def streamed
+      @streamed.values.each_with_object({up: 0, down: 0}) do |b, sum|
+        sum[:up] += b[:up]
+        sum[:down] += b[:down]
+      end
+    end
+
+    # A sub-agent starting, and a sub-agent reporting what it spent.
+    #
+    # `claude` reports a sub-agent's spend as a single `total_tokens` with no
+    # split, and reports it cumulatively: the last number for a task is the
+    # whole of it, not an increment. So the total is stored per task and
+    # replaced rather than added, which also makes a `task_progress` stream
+    # and a closing `task_notification` for the same task agree instead of
+    # counting it twice.
+    #
+    # @param event [Hash]
+    # @return [void]
+    def delegation(event)
+      case event["subtype"]
+      when "task_started" then start_task(event)
+      when "task_progress", "task_notification" then update_task(event)
+      end
+    end
+
+    # @param event [Hash]
+    # @return [void]
+    def start_task(event)
+      id = event["task_id"] or return
+
+      @tasks[id] ||= {tool_use_id: event["tool_use_id"], total: 0}
+      @spawned = @tasks.size
+      publish
+    end
+
+    # @param event [Hash]
+    # @return [void]
+    def update_task(event)
+      id = event["task_id"] or return
+
+      task = (@tasks[id] ||= {tool_use_id: event["tool_use_id"], total: 0})
+      task[:tool_use_id] ||= event["tool_use_id"]
+      task[:total] = event.dig("usage", "total_tokens").to_i
+      @spawned = @tasks.size
+      publish
+    end
+
+    # The `result` event settles what the stream could only accumulate: its
+    # usage is the invocation's own final accounting, so it replaces the
+    # running total rather than adding to it. Sub-agent spend is left alone,
+    # because `claude` leaves it out of this figure — a run whose two
+    # sub-agents burned 34k each reported 493 output tokens here.
+    #
+    # @param event [Hash]
+    # @return [void]
+    def record_result(event)
+      @result = event["result"].to_s
+      @error = @result if event["is_error"]
+      settle(event["usage"])
+      @spawned = [@spawned, event.dig("subagent_stats", "spawned").to_i].max
+      publish
+    end
+
+    # The most recent block wins: an agent that says "now I'll edit the spec"
+    # and then edits it is more usefully reported as editing it.
+    #
+    # @param event [Hash]
+    # @return [String, nil]
+    def phrase_for(event)
+      blocks = event.dig("message", "content")
+      return nil unless blocks.is_a?(Array)
+
+      blocks.reverse.filter_map { |block| block_phrase(block) }.first
+    end
+
+    # @param block [Hash]
+    # @return [String, nil]
+    def block_phrase(block)
+      case block["type"]
+      when "tool_use" then tool_phrase(block)
+      when "text" then sentence(block["text"])
+      end
+    end
+
+    # @param block [Hash]
+    # @return [String]
+    def tool_phrase(block)
+      verb = VERBS.fetch(block["name"].to_s, "using #{block["name"]}")
+      input = block["input"]
+      return verb unless input.is_a?(Hash)
+
+      key = SUBJECTS.find { |k| input[k].to_s.strip != "" }
+      return verb unless key
+      # A description is already a phrase. Prefixing it with a verb gives
+      # "running Read NOTES.md", which reads worse than either half alone.
+      return clip(noun(key, input[key])) if key == "description"
+
+      clip("#{verb} #{noun(key, input[key])}")
+    end
+
+    # A path is only ever interesting by its last segment on a line this short.
+    #
+    # @param key [String]
+    # @param value [Object]
+    # @return [String]
+    def noun(key, value)
+      text = value.to_s.strip.tr("\n", " ").squeeze(" ")
+      (key == "file_path") ? File.basename(text) : text
+    end
+
+    # The agent's own narration, first sentence only. Everything after it is
+    # detail the spinner has no room for.
+    #
+    # @param text [String, nil]
+    # @return [String, nil]
+    def sentence(text)
+      line = text.to_s.split("\n").map(&:strip).find { |l| !l.empty? } or return nil
+      line = line.sub(/\A[#>*\-\s]+/, "").split(/(?<=[.!?])\s/).first.to_s.strip
+      line.empty? ? nil : clip(line)
+    end
+
+    # @param text [String]
+    # @return [String]
+    def clip(text) = (text.length > LIMIT) ? "#{text[0, LIMIT - 1]}…" : text
+
+    # @param usage [Hash, nil] the `result` event's own accounting
+    # @return [void]
+    def settle(usage)
+      return unless usage.is_a?(Hash)
+
+      @main = {
+        up: usage.values_at("input_tokens", "cache_creation_input_tokens",
+          "cache_read_input_tokens").compact.sum,
+        down: usage["output_tokens"].to_i
+      }
+    end
+
+    # @param phrase [String, nil]
+    # @return [void]
+    def announce(phrase)
+      return if phrase.nil? || phrase == @activity
+
+      @activity = phrase
+      publish
+    end
+
+    # Hand the caller a whole snapshot rather than the one field that moved.
+    # A spinner line draws the phrase and the meter together, and a caller
+    # given only the half that changed would have to remember the other.
+    #
+    # @return [void]
+    def publish = @on_progress&.call(progress)
+  end
+end

data/lib/agentilda/tree.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # A project's `.plans` directory: the folders in it, decoded and ordered.
+  class Tree
+    # @param dir [String] the `.plans` directory
+    def initialize(dir:)
+      @dir = File.expand_path(dir)
+    end
+
+    # @return [String] absolute path to the `.plans` directory
+    attr_reader :dir
+
+    # @return [Boolean]
+    def exist? = File.directory?(dir)
+
+    # @return [Array<Agentilda::Feature>] ordered by number
+    def features = @features ||= directories.filter_map { |p| Feature.parse(p) }.sort
+
+    # @return [Array<Agentilda::Subject>] ordered by number
+    def subjects = @subjects ||= features.map { |f| Subject.new(f) }
+
+    # @return [Array<Agentilda::Ordinal>]
+    def ordinals = features.map(&:ordinal)
+
+    # Directories that carry no plan number. Reported, never processed.
+    #
+    # @return [Array<String>]
+    def skipped = @skipped ||= directories.reject { |p| Feature.parse(p) }.map { |p| File.basename(p) }
+
+    # Numbers claimed by more than one folder.
+    #
+    # A plan's number is its identity: branch names, pull request titles and
+    # every `pull-requests.md` join on it. Two folders wearing the same number
+    # make every one of those joins ambiguous, and nothing downstream can tell
+    # which folder a `[002.00]` pull request belongs to.
+    #
+    # @return [Hash{Agentilda::Ordinal => Array<String>}] number => dirnames
+    def duplicates
+      features.group_by(&:ordinal)
+        .select { |_, group| group.size > 1 }
+        .transform_values { |group| group.map(&:dirname) }
+    end
+
+    # @param ordinal [Agentilda::Ordinal, String]
+    # @return [Agentilda::Subject, nil]
+    def find(ordinal)
+      wanted = ordinal.is_a?(Ordinal) ? ordinal : Ordinal.parse(ordinal)
+      subjects.find { |s| s.feature.ordinal == wanted }
+    end
+
+    # @return [Boolean] whether a plan with this number exists on disk
+    def include?(ordinal) = !find(ordinal).nil?
+
+    # Forget everything read from disk, so a caller that has just renamed
+    # folders sees the new state.
+    #
+    # @return [self]
+    def reload
+      @features = @subjects = @skipped = nil
+      self
+    end
+
+    private
+
+    # @return [Array<String>] absolute paths of every subdirectory
+    def directories
+      return [] unless exist?
+
+      Dir.children(dir)
+        .map { |c| File.join(dir, c) }
+        .select { |p| File.directory?(p) }
+        .reject { |p| File.basename(p).start_with?(".") }
+        .sort
+    end
+  end
+end