letsdo 0.1.0

data/lib/letsdo/pi_runner.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Letsdo
+  # Runs pi in --mode json and hands events to the output streamer as they
+  # are generated. The pi exit code is propagated outward.
+  #
+  # pi --mode json streams events line by line: each line is parsed as JSON
+  # and reacted to:
+  #   message_update (assistantMessageEvent):
+  #     text_delta       - a fragment of the agent's answer text → stdout;
+  #     toolcall_start   - the model started emitting a tool call,
+  #                        id→name is remembered (fallback, see below);
+  #   tool_execution_start - a tool started executing: name and full
+  #                        arguments are available (e.g. bash command text);
+  #   tool_execution_end   - a tool finished: result (output) and isError;
+  #   agent_end            - the end of the run.
+  #
+  # The "HH:MM:SS ⚙ name: arguments" header is printed at execution start,
+  # the result and "✓/✖ name" completion line — at completion. If for some
+  # reason no tool_execution_* events arrive (older pi versions, etc.), "⚙ name"
+  # placeholders from remembered toolcall_start events are printed at the end
+  # of the run.
+  #
+  # pi stdout (events) is read by us; pi stderr (its own log) is inherited
+  # and goes to our stderr.
+  class PiRunner
+    COMMAND = "pi"
+    MODE = "json"
+    MESSAGE_UPDATE = "message_update"
+    TOOL_EXECUTION_START = "tool_execution_start"
+    TOOL_EXECUTION_END = "tool_execution_end"
+    AGENT_END = "agent_end"
+
+    # @param prompt [String] agent prompt text
+    # @param flags [Array<String>] extra pi flags
+    # @param streamer [OutputStreamer] where to print output
+    # @param command [String] the pi command (overridable for tests)
+    # @param debug [Boolean, nil] trace [letsdo] lines to stderr; nil = LETSDO_DEBUG
+    def initialize(prompt:, flags: [], streamer:, command: COMMAND, debug: nil)
+      @prompt = prompt
+      @flags = flags
+      @streamer = streamer
+      @command = command
+      @pending_tools = {}
+      @debug = debug.nil? ? ENV["LETSDO_DEBUG"] == "1" : debug
+    end
+
+    # Runs pi and waits for completion.
+    #
+    # pi is spawned in its own process group so the orchestrator can stop it
+    # (signal handlers interrupt the loop, not the pi child directly): a stop
+    # terminates the whole group via #terminate.
+    #
+    # The event stream is read on the main thread. A stop signal arrives as
+    # Letsdo::Stopped raised by the trap (see Letsdo::AgentLoop#on_signal):
+    # the raise interrupts the blocking read directly — no reader threads,
+    # polls or flags. Note for future work on this file: CRuby 4.0 (M:N
+    # threads) here does not execute traps while the main thread is in
+    # Thread#join, defers them with another thread blocked on IO, and does
+    # not wake IO.select on pipe data — the raise-in-trap approach avoids
+    # all of it.
+    #
+    # @return [Integer] pi exit code (128+signal if pi was killed by a signal)
+    def run
+      cmd = [@command, "--mode", MODE, *@flags, @prompt]
+      out_r, out_w = IO.pipe
+      @pid = Process.spawn(*cmd, out: out_w, err: $stderr, pgroup: true)
+      out_w.close
+      debug("spawned pid=#{@pid} (own group)")
+
+      begin
+        read_pi_stream(out_r)
+      rescue Letsdo::Stopped
+        # The signal handler already sent SIGTERM to the pi group; make sure
+        # it is gone (grace loop here runs in the main context, not a trap)
+        # and reap it before propagating the stop.
+        debug("stopped by signal, terminating pi")
+        terminate
+        status = wait_status(@pid)
+        @streamer.finish
+        raise
+      ensure
+        begin
+          out_r.close
+        rescue IOError
+          nil
+        end
+        flush_pending_tools
+      end
+
+      status = wait_status(@pid)
+      @streamer.finish
+      debug("exit status=#{status.inspect} code=#{exit_code(status)}")
+      exit_code(status)
+    ensure
+      @pid = nil
+    end
+
+    def debug(message)
+      warn("[letsdo] pi: #{message}") if @debug
+    end
+
+    # One-shot SIGTERM to the pi process group for a signal handler: no
+    # waits, sleeps or IO — safe inside a trap. The caller reaps the child
+    # afterwards (see #run).
+    def terminate_now
+      pid = @pid
+      send_signal("TERM", pid) if pid
+    end
+
+    # Stops a running pi: SIGTERM to its process group, then SIGKILL after
+    # the grace period if it did not exit. Safe to call when the run already
+    # finished (no-op).
+    #
+    # @param signal [String] the first signal to send
+    # @param grace [Float] seconds to wait before falling back to SIGKILL
+    def terminate(signal: "TERM", grace: 3.0, tick: 0.05)
+      pid = @pid
+      return true unless pid
+
+      send_signal(signal, pid)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + grace
+      loop do
+        break unless alive?(pid)
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          send_signal("KILL", pid)
+          break
+        end
+        sleep(tick)
+      end
+      true
+    end
+
+    private
+
+    # Reads the pi event stream until EOF. Runs on the main thread; a stop
+    # signal interrupts it via Letsdo::Stopped raised from the trap.
+    def read_pi_stream(out_r)
+      out_r.each_line { |line| handle_line(line) }
+      debug("stream: EOF")
+    end
+
+    # Parses one line of the pi event stream and passes it to the streamer.
+    def handle_line(line)
+      line = line.strip
+      return if line.empty?
+
+      event = parse_event(line)
+      return unless event
+
+      case event["type"]
+      when MESSAGE_UPDATE
+        handle_message_update(event)
+      when TOOL_EXECUTION_START
+        @pending_tools.delete(event["toolCallId"])
+        @streamer.tool_start(event["toolName"] || "tool", args: event["args"])
+      when TOOL_EXECUTION_END
+        handle_tool_execution_end(event)
+      when AGENT_END
+        flush_pending_tools
+      end
+    end
+
+    # Handles an assistant message update event.
+    def handle_message_update(event)
+      payload = event["assistantMessageEvent"]
+      return unless payload
+
+      case payload["type"]
+      when "text_delta"
+        delta = payload["delta"]
+        @streamer.text_delta(delta) if delta && !delta.empty?
+      when "toolcall_start"
+        # The call has just started to be generated: the name is known
+        # immediately, arguments will arrive with the execution start
+        # (tool_execution_start).
+        id = event["id"] || payload["id"]
+        name = event["toolName"] || payload["toolName"] || "tool"
+        @pending_tools[id] = name unless id.nil?
+      end
+    end
+
+    # Tool execution result: text from result.content plus the error flag.
+    # An empty error text is replaced with a clear wording. The completion
+    # line is always printed (even for an empty result), so that the action
+    # completion is visible in the service output.
+    def handle_tool_execution_end(event)
+      name = event["toolName"] || "tool"
+      text = result_text(event["result"])
+      error = event["isError"] == true
+      text = "tool failed with an error" if (text.nil? || text.empty?) && error
+      @streamer.tool_result(name, text, error: error)
+    end
+
+    # Collects the result text from {type: "text"} content blocks.
+    # Image blocks and other types do not get into the text.
+    def result_text(result)
+      return nil unless result.is_a?(Hash)
+
+      content = result["content"]
+      return nil unless content.is_a?(Array)
+
+      parts = content.filter_map do |block|
+        next nil unless block.is_a?(Hash)
+
+        text = block["text"]
+        text if text.is_a?(String) && !text.empty? &&
+                (block["type"] == "text" || !block.key?("type"))
+      end
+      text = parts.join
+      text.empty? ? nil : text
+    end
+
+    # Placeholders for calls without execution events (old pi, etc.):
+    # prints "⚙ name" without arguments. Called both on agent_end and in
+    # the ensure block after reading the stream; clear protects against
+    # duplicates.
+    def flush_pending_tools
+      @pending_tools.each_value { |name| @streamer.tool_start(name) }
+      @pending_tools.clear
+    end
+
+    # Ignores lines that are not valid JSON events.
+    def parse_event(line)
+      JSON.parse(line)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def wait_status(pid)
+      _, status = Process.wait2(pid)
+      status
+    end
+
+    # Sends a signal to the pi process group. Missing/killed groups are
+    # silently ignored.
+    def send_signal(signal, pid)
+      Process.kill(signal, -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    # Whether the pi process still exists (does not reap it).
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def exit_code(status)
+      return status.exitstatus if status.exitstatus
+
+      status.termsig ? 128 + status.termsig : 1
+    end
+  end
+end

data/lib/letsdo/prompt_store.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Access to agent prompts: the agents/<name>.md directory in the project
+  # root. A new agent = a new agents/<name>.md file, no code changes needed.
+  class PromptStore
+    AGENTS_DIR = "agents"
+
+    # @param root [String] project root (agents/ lives there)
+    def initialize(root:)
+      @root = root
+    end
+
+    # Sorted list of agent names (file names without extension).
+    #
+    # @return [Array<String>]
+    def list
+      Dir.glob(File.join(agents_dir, "*.md")).sort.map { |path| File.basename(path, ".md") }
+    end
+
+    # Reads an agent prompt.
+    #
+    # @param name [String] agent name
+    # @return [String] contents of agents/<name>.md
+    # @raise [UnknownAgentError] if there is no such agent
+    def read(name)
+      path = File.join(agents_dir, "#{name}.md")
+      raise UnknownAgentError, name unless File.file?(path)
+
+      File.read(path)
+    end
+
+    private
+
+    def agents_dir
+      File.join(@root, AGENTS_DIR)
+    end
+  end
+end

data/lib/letsdo/tui/input.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Letsdo
+  module Tui
+    # Non-blocking keyboard input for the TUI: wraps tty-reader and maps
+    # escape sequences to plain symbols (:up, :down, :page_up, :page_down,
+    # :home, :end, :p, :r, :q, :ctrl_c). Returns nil when no key is waiting
+    # within the poll timeout, so the caller can repaint on a 1s timer.
+    #
+    # Ctrl-C is read as a key (:ctrl_c → quit) instead of raising: the
+    # tty-reader raw mode disables the terminal's SIGINT generation, and
+    # external SIGINT/SIGTERM still go through the loop's signal path.
+    #
+    # Tests inject a pipe with the raw escape bytes — tty-reader's
+    # mode helpers no-op on non-tty inputs, so no real TTY is needed.
+    # tty-reader's unused echo stream is a StringIO (stdlib, required here).
+    class Input
+      # Poll timeout for readable input, seconds.
+      POLL_TIMEOUT = 0.1
+
+      KEY_BY_VALUE = {
+        "p" => :p, "r" => :r, "q" => :q,
+        "\u0003" => :ctrl_c,
+        "\e[A" => :up, "\eOA" => :up,
+        "\e[B" => :down, "\eOB" => :down,
+        "\e[5~" => :page_up,
+        "\e[6~" => :page_down,
+        "\e[H" => :home, "\e[1~" => :home, "\e[7~" => :home, "\eOH" => :home,
+        "\e[F" => :end, "\e[4~" => :end, "\e[8~" => :end, "\eOF" => :end
+      }.freeze
+
+      # The keyboard stream (exposed so the session can wrap it in raw mode).
+      attr_reader :stdin
+
+      # @param stdin [IO] the keyboard stream (a terminal when engaged)
+      # @param poll_timeout [Numeric] nil-poll interval for non-tty inputs
+      def initialize(stdin:, poll_timeout: POLL_TIMEOUT)
+        require "tty-reader"
+
+        @stdin = stdin
+        @poll_timeout = poll_timeout
+        @reader = TTY::Reader.new(input: stdin, output: StringIO.new,
+                                  interrupt: :noop, track_history: false)
+      end
+
+      # The next key, or nil when nothing was pressed in time.
+      #
+      # @return [Symbol, nil]
+      def next_key
+        return nil unless ready?
+
+        value = @reader.read_keypress(echo: false, raw: false, nonblock: false)
+        return nil if value.nil?
+
+        # tty-reader 0.9 only continues CSI (`\e[…`); SS3 (`\eO…`) stops
+        # after `\eO`. Pull the final byte so `\eOA` / `\eOH` / `\eOF` map.
+        if value == "\eO" && (final = ss3_final_byte)
+          value += final
+        end
+
+        KEY_BY_VALUE[value]
+      end
+
+      private
+
+      # Whether a key is available now (bounded wait). Real terminals use
+      # wait_readable; otherwise eof?.
+      def ready?
+        if @stdin.respond_to?(:wait_readable)
+          @stdin.wait_readable(@poll_timeout)
+        else
+          !@stdin.eof?
+        end
+      end
+
+      def ss3_final_byte
+        return nil unless byte_waiting?
+
+        @stdin.getc
+      end
+
+      def byte_waiting?
+        if @stdin.respond_to?(:wait_readable)
+          @stdin.wait_readable(0)
+        else
+          !@stdin.eof?
+        end
+      end
+    end
+  end
+end

data/lib/letsdo/tui/log_buffer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # The combined, thread-safe log behind the TUI stream.
+    #
+    # The TUI uses one buffer for everything the agent produces: answer
+    # text deltas, tool lines, loop service messages — in arrival order,
+    # exactly what Letsdo::OutputStreamer emits. The streamer (main thread)
+    # appends via #write/#puts; the TUI input thread reads a snapshot via
+    # #lines for rendering. Both operations are mutex-protected.
+    #
+    # Lines are capped (oldest dropped); a partial last line (the agent's
+    # in-progress text) is kept separately so rendering can show the live
+    # tail. #divider appends a run-boundary separator. A monotonically
+    # increasing version lets the renderer skip repaints when nothing new
+    # arrived.
+    class LogBuffer
+      # Default maximum number of complete lines kept in the buffer.
+      MAX_LINES = 2_000
+      # The run-boundary separator line.
+      DIVIDER = "─" * 40
+
+      # @param max_lines [Integer] maximum number of complete lines kept;
+      #        older lines are dropped
+      def initialize(max_lines: MAX_LINES)
+        @mutex = Mutex.new
+        @lines = []
+        @pending = +""
+        @max_lines = max_lines
+        @version = 0
+      end
+
+      # Appends raw text (IO-compatible, used by Letsdo::OutputStreamer).
+      #
+      # @param text [String] the next chunk of the stream
+      def write(text)
+        return if text.nil? || text.empty?
+
+        @mutex.synchronize { append(text) }
+        self
+      end
+
+      # Appends a complete line with a trailing newline (IO-compatible,
+      # used by Letsdo::AgentLoop service messages).
+      #
+      # @param text [String, nil] the line or nil for an empty line
+      def puts(text = nil)
+        write(text.nil? ? "\n" : "#{text}\n")
+        self
+      end
+
+      # IO-compatible no-op: an in-memory buffer never needs flushing.
+      def flush
+        self
+      end
+
+      # Appends a run-boundary divider line (skipped when the buffer is
+      # still empty — there is no boundary yet).
+      def divider
+        @mutex.synchronize do
+          @lines << DIVIDER unless @lines.empty? && @pending.empty?
+          @version += 1
+        end
+        self
+      end
+
+      # The current buffer content for rendering: complete lines plus the
+      # pending partial line, and the current version.
+      #
+      # @return [Array(Array<String>, Integer)] lines and version
+      def lines
+        @mutex.synchronize do
+          snapshot = @lines.dup
+          snapshot << @pending.dup unless @pending.empty?
+          [snapshot, @version]
+        end
+      end
+
+      # Monotonic change counter. The input thread compares this to the
+      # last rendered version so it can skip repaints when the log is idle.
+      #
+      # @return [Integer]
+      def version
+        @mutex.synchronize { @version }
+      end
+
+      private
+
+      # Splits the raw chunk on newlines: everything before the last
+      # newline becomes complete lines, the trailing fragment stays
+      # pending. The pending fragment is moved to the completed list as
+      # soon as a newline arrives, so line order is preserved.
+      def append(text)
+        chunks = text.split("\n", -1)
+        @pending << chunks.shift
+        chunks.each do |chunk|
+          @lines << @pending
+          @pending = chunk
+        end
+        trim_lines
+        @version += 1
+      end
+
+      def trim_lines
+        excess = @lines.length - @max_lines
+        @lines.shift(excess) if excess.positive?
+      end
+    end
+  end
+end

data/lib/letsdo/tui/metrics.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # The metrics facade for the TUI header, fed by the loop driver.
+    #
+    # Data sources (TASK-38 architecture survey):
+    #   done            - number of completed agent runs in this session,
+    #                     counted from the loop's run_finished events;
+    #   left            - latest open-task count from the backlog provider
+    #                     (the loop reports it per iteration; 'r' forces an
+    #                     immediate re-query);
+    #   current task    - the task the agent is running now, started by
+    #                     run_started and elapsed on a monotonic clock;
+    #   session timer   - monotonic time since this facade was created;
+    #   identity        - agent name and assignee handle (the header's
+    #                     "name (@handle)" line).
+    #
+    # All state changes happen on the loop thread; snapshots are read by
+    # the TUI input thread while the loop runs — hence the mutex. The
+    # facade is deliberately generic: Letsdo::Loop stays untouched, the
+    # events come from Letsdo::AgentLoop (wrapped_provider/wrapped_run).
+    #
+    # An optional on_run_start hook lets the caller (CLI) mark run
+    # boundaries in the log when a run starts.
+    class Metrics
+      # An immutable snapshot of the header metrics at some moment.
+      Snapshot = Struct.new(:name, :handle, :done, :left, :session_seconds,
+                            :current_task, :current_task_seconds, keyword_init: true)
+
+      # @param name [String] agent name (CLI argument)
+      # @param handle [String] assignee handle (e.g. "@developer")
+      # @param clock [Proc] monotonic clock, callable → seconds; injected
+      #        in tests
+      # @param on_run_start [Proc, nil] called with the task label when a
+      #        run starts (the CLI uses it to insert a log divider)
+      def initialize(name:, handle:, clock: nil, on_run_start: nil)
+        @name = name
+        @handle = handle
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @on_run_start = on_run_start
+        @mutex = Mutex.new
+        @done = 0
+        @left = nil
+        @current_task = nil
+        @current_started = nil
+        @session_started = @clock.call
+      end
+
+      # An agent run started for a task: records the task label and the
+      # monotonic run start time.
+      #
+      # @param task [String] task label
+      def run_started(task)
+        @on_run_start&.call(task)
+        @mutex.synchronize do
+          @current_task = task
+          @current_started = @clock.call
+        end
+      end
+
+      # An agent run finished: increments the done counter and clears the
+      # current-task state.
+      def run_finished
+        @mutex.synchronize do
+          @done += 1
+          @current_task = nil
+          @current_started = nil
+        end
+      end
+
+      # The latest open-task count from the backlog provider.
+      #
+      # @param count [Integer, nil] number of open tasks; nil = the backlog
+      #        state is unreadable
+      def provider_result(count)
+        @mutex.synchronize { @left = count }
+      end
+
+      # A point-in-time snapshot of all header metrics.
+      #
+      # @return [Snapshot]
+      def snapshot
+        now = @clock.call
+        @mutex.synchronize do
+          current_seconds = @current_started ? now - @current_started : nil
+          Snapshot.new(
+            name: @name, handle: @handle, done: @done, left: @left,
+            session_seconds: now - @session_started,
+            current_task: @current_task,
+            current_task_seconds: current_seconds
+          )
+        end
+      end
+    end
+  end
+end