letsdo 0.1.0

data/lib/letsdo/cli.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Letsdo
+  # Command-line argument parsing and running an agent orchestrator loop.
+  #
+  # CLI keeps the scaffold contract (TASK-20) and adds agent launching:
+  #   letsdo                       — usage and agent list, exit code 1;
+  #   letsdo --version             — version, exit code 0;
+  #   letsdo --help                — usage, exit code 0;
+  #   letsdo <name>                — run the <name> agent in the orchestrator
+  #                                    loop until SIGINT/SIGTERM: all open
+  #                                    tasks assigned to the agent are done
+  #                                    one run per task, the loop waits for
+  #                                    new ones; clean exit code 0;
+  #   letsdo <unknown name>        — "Unknown agent: <name>" + list,
+  #                                    exit code 1.
+  #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage,
+  #                                    exit code 1.
+  #
+  # Environment:
+  #   LETSDO_ROOT              project root (agents/ lives there); default — pwd.
+  #   LETSDO_PI_FLAGS          extra pi flags (split on whitespace; if unset —
+  #                            AGENT_PI_FLAGS is used for bin/agent
+  #                            compatibility).
+  #   LETSDO_PI_COMMAND        the pi command (default "pi"); overridable for
+  #                            tests/fake pi.
+  #   AGENT_ASSIGNEE_HANDLE    the agent's backlog assignee handle; default
+  #                            "@<name>" (the one rule: handle = name).
+  #   LETSDO_WAIT_SECONDS      retry interval when no tasks are open (if
+  #                            unset — AGENT_WAIT_SECONDS, default 10).
+  #   LETSDO_BACKLOG_COMMAND   the backlog CLI command (default "backlog");
+  #                            overridable for tests/fake backlog.
+  class CLI
+    USAGE = 'Usage: letsdo <agent_name>'
+    AGENTS_HEADER = 'Available agents:'
+    DEFAULT_WAIT_SECONDS = 10.0
+
+    # @param argv [Array<String>] command-line arguments
+    # @param env [Hash] process environment (LETSDO_ROOT, LETSDO_PI_FLAGS,
+    #        AGENT_PI_FLAGS, AGENT_ASSIGNEE_HANDLE, LETSDO_WAIT_SECONDS,
+    #        LETSDO_BACKLOG_COMMAND); injected in tests
+    # @param stdout [IO] stream for normal output (usage, --help, list)
+    # @param stderr [IO] stream for service output
+    # @param stdin [IO] keyboard stream (the TUI reads keys from it)
+    # @param sleeper [Proc, nil] waiting procedure for the loop (callable
+    #        with the interval); injected in tests for deterministic stops
+    # @return [Integer] exit code: 0 — success (incl. loop stop), 1 — error,
+    #         otherwise — pi exit code
+    def self.run(argv, env: ENV, stdout: $stdout, stderr: $stderr, stdin: $stdin, sleeper: nil)
+      new(env: env, stdout: stdout, stderr: stderr, stdin: stdin, sleeper: sleeper).run(argv)
+    end
+
+    def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
+      @env = env
+      @stdout = stdout
+      @stderr = stderr
+      @stdin = stdin
+      @sleeper = sleeper
+      @root = env.fetch('LETSDO_ROOT', Dir.pwd)
+    end
+
+    # @param argv [Array<String>] command-line arguments
+    # @return [Integer] exit code
+    def run(argv)
+      arg = argv[0]
+      case arg
+      when '--version', '-v'
+        @stdout.puts(VERSION)
+        0
+      when '--help', '-h'
+        print_usage(@stdout)
+        0
+      when nil
+        print_usage(@stderr)
+        1
+      else
+        if arg.start_with?('-')
+          @stderr.puts("letsdo: unknown option: #{arg}")
+          print_usage(@stderr)
+          1
+        else
+          run_agent(arg)
+        end
+      end
+    end
+
+    private
+
+    def run_agent(name)
+      # The prompt must exist before the loop starts: an unknown agent fails
+      # fast (exit 1) instead of spinning in the loop.
+      PromptStore.new(root: @root).read(name)
+
+      if tui?
+        run_agent_tui(name)
+      else
+        run_agent_plain(name)
+      end
+    rescue UnknownAgentError => e
+      @stderr.puts(e.message)
+      print_agents
+      1
+    end
+
+    # The non-interactive path: the plain line-stream output, byte-identical
+    # to the pre-TUI behavior (pipes, CI, tests, TERM=dumb).
+    def run_agent_plain(name)
+      streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
+      agent = Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
+                        command: pi_command)
+      handle = assignee_handle(name)
+      provider = BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
+                                  env: ENV.to_h.merge(@env))
+      loop = AgentLoop.new(name: name, handle: handle, agent: agent,
+                           task_provider: -> { provider.call },
+                           wait_seconds: wait_seconds, sleeper: @sleeper, stderr: @stderr)
+      loop.run
+    end
+
+    # The interactive path: full-screen TUI over the same orchestrator loop.
+    # The streamer and the loop's service messages land in one combined log
+    # buffer; the loop driver feeds the header metrics facade; the session
+    # controller renders everything from a background input thread and
+    # restores the terminal on every exit path. The loop itself runs on the
+    # calling thread exactly as in plain mode.
+    def run_agent_tui(name)
+      clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      handle = assignee_handle(name)
+      log = Tui::LogBuffer.new
+      metrics = Tui::Metrics.new(name: name, handle: handle, clock: clock,
+                                 on_run_start: ->(_label) { log.divider })
+      terminal = Tui::Terminal.new(stream: @stdout)
+      input = Tui::Input.new(stdin: @stdin)
+      streamer = OutputStreamer.new(log: log)
+      agent = Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
+                        command: pi_command)
+      provider = BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
+                                  env: ENV.to_h.merge(@env))
+      loop = AgentLoop.new(name: name, handle: handle, agent: agent,
+                           task_provider: -> { provider.call },
+                           wait_seconds: wait_seconds, sleeper: @sleeper, stderr: log,
+                           metrics: metrics)
+      session = Tui::Session.new(name: name, handle: handle, log: log, metrics: metrics,
+                                 terminal: terminal, input: input,
+                                 refresh: -> { provider.call },
+                                 wait_seconds: wait_seconds, clock: clock)
+      session.run { loop.run }
+    end
+
+    # The TUI is engaged only when stdout and stdin are terminals and TERM
+    # is not dumb; otherwise the plain line-stream output (pipes, CI,
+    # tests) — no escape codes, no TUI.
+    def tui?
+      @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
+    end
+
+    # The agent's assignee handle: AGENT_ASSIGNEE_HANDLE override, otherwise
+    # the one rule — '@' + agent name.
+    def assignee_handle(name)
+      env_handle = @env['AGENT_ASSIGNEE_HANDLE']
+      env_handle && !env_handle.strip.empty? ? env_handle : "@#{name}"
+    end
+
+    def backlog_command
+      @env.fetch('LETSDO_BACKLOG_COMMAND', 'backlog')
+    end
+
+    # The retry interval when no tasks are open: LETSDO_WAIT_SECONDS, then
+    # AGENT_WAIT_SECONDS (bin/agent-loop compatibility), default 10 seconds.
+    def wait_seconds
+      value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
+      value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
+      return DEFAULT_WAIT_SECONDS if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_WAIT_SECONDS
+    end
+
+    def pi_command
+      @env.fetch('LETSDO_PI_COMMAND', PiRunner::COMMAND)
+    end
+
+    def print_usage(stream)
+      stream.puts(USAGE)
+      print_agents
+    end
+
+    def print_agents
+      @stdout.puts(AGENTS_HEADER)
+      PromptStore.new(root: @root).list.each { |name| @stdout.puts("  #{name}") }
+    end
+
+    # LETSDO_PI_FLAGS → array of flags; empty value = no flags.
+    # For bin/agent compatibility, when LETSDO_PI_FLAGS is absent
+    # AGENT_PI_FLAGS is used.
+    def parse_pi_flags
+      value = @env['LETSDO_PI_FLAGS'].to_s
+      value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?
+      return [] if value.strip.empty?
+
+      Shellwords.split(value)
+    end
+  end
+end

data/lib/letsdo/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Base error of the package.
+  class Error < StandardError; end
+
+  # An agent with this name was not found in agents/.
+  class UnknownAgentError < Error
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+      super("Unknown agent: #{name}")
+    end
+  end
+
+  # Raised by the signal handler to interrupt whatever the main thread is
+  # doing (reading pi output, waiting for tasks, ...) so the loop unwinds
+  # cleanly. Not a StandardError — nothing rescues it accidentally.
+  class Stopped < Exception
+  end
+end

data/lib/letsdo/loop.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Orchestrator: while the backlog has open tasks assigned to the agent,
+  # runs the agent (one run = one task). When there are no tasks — waits
+  # and checks again. Stopping — only from outside: #stop (usually by a
+  # SIGINT/SIGTERM handler, as in bin/agent-loop).
+  #
+  # The task provider and the runner are injected so the loop is testable
+  # without a real backlog and pi; by default they are assembled from the
+  # project environment (backlog CLI + Letsdo::Agent).
+  class Loop
+    # @param task_provider [Proc] callable → Array of open tasks
+    #        (empty = no tasks; nil = the backlog state is unreadable,
+    #        in this case the loop does not run the agent and retries)
+    # @param run_task [Proc] callable(task) → agent run exit code
+    # @param wait_seconds [Float] wait interval when there are no tasks
+    # @param sleeper [Proc] callable(Float) → waiting (injected in tests)
+    def initialize(task_provider:, run_task:, wait_seconds: 10.0, sleeper: nil)
+      @task_provider = task_provider
+      @run_task = run_task
+      @wait_seconds = wait_seconds
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @stopped = false
+    end
+
+    # Requests a stop after the current step.
+    def stop
+      @stopped = true
+    end
+
+    def stopped?
+      @stopped
+    end
+
+    # Runs the loop; ends only via #stop.
+    #
+    # @return [Integer] number of completed agent runs
+    def run
+      runs = 0
+      until @stopped
+        tasks = @task_provider.call
+        if tasks.nil? || tasks.empty?
+          @sleeper.call(@wait_seconds)
+          next
+        end
+
+        tasks.each do |task|
+          break if @stopped
+
+          @run_task.call(task)
+          runs += 1
+        end
+      end
+      runs
+    end
+  end
+end

data/lib/letsdo/output_streamer.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Letsdo
+  # Routes pi output across two streams:
+  #   stdout — only the agent's answer text (text_delta), no service lines;
+  #   stderr — service lines: tool calls (name, arguments, result) as
+  #            execution progress.
+  #
+  # Every action line gets a shared HH:MM:SS time prefix: the difference
+  # between prefixes shows how long ago an action happened and how long
+  # a tool ran. Format of service tool lines:
+  #   HH:MM:SS ⚙ name: arguments    — tool call on one line (for bash the
+  #                                   command text, for read/write/edit the
+  #                                   path, etc.);
+  #   indented "  " lines           — execution result (stdout/stderr),
+  #                                   no time prefix (data, not actions);
+  #   HH:MM:SS ✓ name: done (Xs)    — tool completion (success), printed
+  #                                   after the result block;
+  #   HH:MM:SS ✖ name: error (Xs)   — tool completion (error);
+  #   ✖ Error: ...                  — error result marked explicitly;
+  #   … [output truncated: N lines, M] — big output → summary note.
+  # Remembers the last response character so that on finish a final newline
+  # is guaranteed — output must not break in the middle.
+  class OutputStreamer
+    # Max lines of a tool result in service output.
+    MAX_RESULT_LINES = 100
+    # Max characters of a tool result in service output.
+    MAX_RESULT_CHARS = 4_000
+    # Max characters of a short call-arguments representation.
+    MAX_ARGS_CHARS = 300
+
+    # @param stdout [IO] stream for the agent's answer text
+    # @param stderr [IO] stream for service lines
+    # @param log [Object, nil] an alternate log target (TUI mode): when
+    #        given, ALL output — answer text and service tool lines — is
+    #        written there as one combined stream (a
+    #        Letsdo::Tui::LogBuffer); without it the plain stdout/stderr
+    #        split is byte-identical to before
+    # @param clock [Proc] callable → Time, the source of time for prefixes
+    #        (injected in tests for deterministic HH:MM:SS)
+    def initialize(stdout: $stdout, stderr: $stderr, log: nil, clock: nil)
+      @stdout = stdout
+      @stderr = stderr
+      @log = log
+      @clock = clock || -> { Time.now }
+      @last_char = nil
+      @action_started_at = nil
+    end
+
+    # Prints a chunk of the agent's answer text immediately.
+    #
+    # @param delta [String] the next text fragment
+    def text_delta(delta)
+      return if delta.nil? || delta.empty?
+
+      text_sink.write(delta)
+      text_sink.flush unless @log
+      @last_char = delta[-1]
+    end
+
+    # A service line about a tool call: HH:MM:SS time prefix, tool name and
+    # short arguments (e.g. the executed bash command text). One line without
+    # empty placeholders, to stderr so it does not mix with the agent text
+    # on stdout. The call moment is remembered — the action duration in the
+    # completion line is measured from it.
+    #
+    # @param name [String] tool name
+    # @param args [Hash, String, nil] call arguments (pi event)
+    def tool_start(name, args: nil)
+      @action_started_at = @clock.call
+      line = +"#{timestamp} ⚙ #{name}"
+      summary = summarize_args(name, args)
+      line << ": #{summary}" if summary
+      write_service("#{line}\n")
+    end
+
+    # Service lines of the tool result (command/file output): an indented
+    # block without a time prefix (action data) plus a completion line with
+    # the HH:MM:SS prefix, name, verdict and duration. Very large output is
+    # trimmed neatly with a summary note, errors are marked explicitly.
+    # An empty result yields only the completion line.
+    #
+    # @param name [String] tool name
+    # @param text [String] result text
+    # @param error [Boolean] whether the execution failed
+    def tool_result(name, text, error: false)
+      out = String.new
+      unless text.nil? || text.empty?
+        lines = text.lines
+        kept, truncated = truncate_result(text)
+        kept.each_with_index do |line, index|
+          line = line.chomp
+          next if line.empty? && index == kept.length - 1 # no trailing empty line
+
+          prefix = index.zero? ? (error ? "  ✖ Error: " : "  ") : "  "
+          out << "#{prefix}#{line}\n"
+        end
+        out << result_note(lines) if truncated
+      end
+      out << completion_line(name, error)
+      write_service(out)
+    end
+
+    # Finishes the output: if the answer did not end with a newline — adds
+    # one so the next terminal output does not stick to the agent's answer.
+    def finish
+      return unless @last_char && @last_char != "\n"
+
+      text_sink.write("\n")
+      text_sink.flush unless @log
+    end
+
+    private
+
+    # Shared time prefix for all action lines: HH:MM:SS.
+    #
+    # @return [String] local time as hours:minutes:seconds
+    def timestamp
+      @clock.call.strftime("%H:%M:%S")
+    end
+
+    # Tool completion line: time prefix, verdict, name and action duration
+    # (seconds between call and completion). The duration is not printed
+    # when no action start was recorded (e.g. a result without a preceding
+    # call).
+    #
+    # @param name [String] tool name
+    # @param error [Boolean] whether the execution failed
+    # @return [String] completion line with a trailing newline
+    def completion_line(name, error)
+      mark = error ? "✖" : "✓"
+      verdict = error ? "error" : "done"
+      elapsed = elapsed_seconds
+      duration = elapsed ? " (#{format_elapsed(elapsed)})" : ""
+      "#{timestamp} #{mark} #{name}: #{verdict}#{duration}\n"
+    end
+
+    # Seconds from the current action start to its completion.
+    #
+    # @return [Float, nil] duration, or nil if there was no start
+    def elapsed_seconds
+      return nil unless @action_started_at
+
+      @clock.call - @action_started_at
+    end
+
+    # A neat duration: seconds with one decimal place up to 10s, whole
+    # seconds after.
+    def format_elapsed(seconds)
+      seconds < 10 ? format("%.1fs", seconds) : "#{seconds.round}s"
+    end
+
+    # Truncates the result text by line and character limits.
+    #
+    # @param text [String] the whole result text
+    # @return [Array(Array<String>, Boolean)] kept lines and truncation flag
+    def truncate_result(text)
+      lines = text.lines
+      kept = []
+      chars = 0
+      truncated = false
+      lines.each do |line|
+        if kept.length >= MAX_RESULT_LINES || (!kept.empty? && chars + line.length > MAX_RESULT_CHARS)
+          truncated = true
+          break
+        end
+        kept << line
+        chars += line.length
+      end
+      # A single line longer than the char limit — cut the line itself.
+      if kept.first && kept.first.length > MAX_RESULT_CHARS
+        kept[0] = kept[0].slice(0, MAX_RESULT_CHARS)
+        truncated = true
+      end
+      [kept, truncated]
+    end
+
+    # Summary note about the truncated result.
+    def result_note(lines)
+      total_lines = lines.length
+      total_chars = lines.sum(&:length)
+      lines_word = plural(total_lines, "line", "lines")
+      chars_word = plural(total_chars, "character", "characters")
+      "  … [output truncated: #{total_lines} #{lines_word}, #{total_chars} #{chars_word}]\n"
+    end
+
+    # English singular/plural for a noun after a number.
+    def plural(count, singular, plural_form)
+      count == 1 ? singular : plural_form
+    end
+
+    # Short one-line representation of the tool call arguments.
+    #
+    # @param name [String] tool name
+    # @param args [Hash, String, nil] call arguments
+    # @return [String, nil] arguments string or nil (print nothing)
+    def summarize_args(name, args)
+      case name
+      when "bash", "powershell"
+        one_line(args_value(args, "command"))
+      when "read"
+        path = args_value(args, "path") || args_value(args, "file_path")
+        return nil unless path
+
+        range = read_range(args)
+        "#{path}#{range}"
+      when "write", "edit", "find", "ls"
+        args_value(args, "path") || args_value(args, "file_path")
+      when "grep"
+        pattern = one_line(args_value(args, "pattern"))
+        path = args_value(args, "path") || args_value(args, "file_path")
+        return nil unless pattern
+
+        path ? "#{pattern} #{path}" : pattern
+      else
+        summarize_generic(args)
+      end
+    end
+
+    # Read line range (offset/limit) as ":N-M", when given.
+    def read_range(args)
+      return nil unless args.is_a?(Hash)
+
+      offset = args["offset"]
+      return nil unless offset
+
+      limit = args["limit"]
+      limit ? ":#{offset}-#{offset + limit - 1}" : ":#{offset}"
+    end
+
+    # Tool argument value as a string; nil when absent.
+    def args_value(args, key)
+      return nil unless args.is_a?(Hash)
+
+      value = args[key]
+      value.nil? ? nil : value.to_s
+    end
+
+    # Universal arguments representation (other tools): short JSON on one line.
+    def summarize_generic(args)
+      return nil if args.nil? || (args.is_a?(Hash) && args.empty?)
+
+      text =
+        case args
+        when String then args
+        when Hash then JSON.generate(args)
+        else args.to_s
+        end
+      one_line(text)
+    end
+
+    # Collapses whitespace into a single line and cuts by the limit.
+    def one_line(value, max: MAX_ARGS_CHARS)
+      return nil if value.nil?
+
+      text = value.to_s.gsub(/\s+/, " ").strip
+      return nil if text.empty?
+
+      text.length > max ? "#{text.slice(0, max)}…" : text
+    end
+
+    # Writes a service line to stderr and flushes immediately so output
+    # appears as it is produced; in TUI mode the line goes to the shared
+    # log buffer instead.
+    def write_service(text)
+      if @log
+        @log.write(text)
+      else
+        @stderr.write(text)
+        @stderr.flush
+      end
+    end
+
+    # Where the agent's answer text goes: the shared log in TUI mode,
+    # stdout otherwise.
+    def text_sink
+      @log || @stdout
+    end
+  end
+end