agentilda 2.0.1 → 2.0.4

data/lib/agentilda/execution/child.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Execution
+    # 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::Execution::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
+end

data/lib/agentilda/execution/clock.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Execution
+    # 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
+end

data/lib/agentilda/execution/control.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Agentilda
+  module Execution
+    # 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
+end