letsdo 0.1.0 → 0.2.0

data/lib/letsdo/pi_runner.rb

@@ -1,260 +1,101 @@
 # frozen_string_literal: true
 
-require "json"
+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.
+  # Runs pi in --mode json and hands events to the output streamer.
   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"
+    COMMAND = 'pi'
+    MODE = 'json'
+    MESSAGE_UPDATE = 'message_update'
+    TOOL_EXECUTION_START = 'tool_execution_start'
+    TOOL_EXECUTION_END = 'tool_execution_end'
+    AGENT_END = 'agent_end'
+  end
+end
+
+require_relative 'pi_runner/events'
+require_relative 'pi_runner/process'
 
-    # @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)
+module Letsdo
+  # Pi process spawn, stream drain, and pause/resume signals.
+  class PiRunner
+    include PiRunnerEvents
+    include PiRunnerProcess
+
+    def initialize(prompt:, streamer:, **opts)
       @prompt = prompt
-      @flags = flags
       @streamer = streamer
-      @command = command
+      @flags = opts.fetch(:flags, [])
+      @command = opts.fetch(:command, COMMAND)
       @pending_tools = {}
-      @debug = debug.nil? ? ENV["LETSDO_DEBUG"] == "1" : debug
+      @reaped_status = nil
+      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[: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)
+      out_r = spawn_pi
+      drain_stream(out_r)
+      finish_run
     ensure
       @pid = nil
+      @reaped_status = 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
+      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)
+    def pause
       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
+      send_signal('STOP', pid) if pid
     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
+    def resume
+      pid = @pid
+      send_signal('CONT', pid) if pid
     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
+    private
 
-    # Ignores lines that are not valid JSON events.
-    def parse_event(line)
-      JSON.parse(line)
-    rescue JSON::ParserError
-      nil
+    def spawn_pi
+      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)")
+      out_r
     end
 
-    def wait_status(pid)
-      _, status = Process.wait2(pid)
-      status
+    def drain_stream(out_r)
+      read_pi_stream(out_r)
+    rescue Letsdo::Stopped
+      debug('stopped by signal, terminating pi')
+      terminate
+      wait_status(@pid)
+      @streamer.finish
+      raise
+    ensure
+      close_pipe(out_r)
+      flush_pending_tools
     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
+    def close_pipe(out_r)
+      out_r.close
+    rescue IOError
       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
+    def finish_run
+      status = wait_status(@pid)
+      @streamer.finish
+      debug("exit status=#{status.inspect} code=#{exit_code(status)}")
+      exit_code(status)
     end
   end
-end
+end

data/lib/letsdo/prompt_store.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 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"
+    AGENTS_DIR = 'agents'
+
+    # Whether a name may be used as an agent prompt file name. Refuses
+    # path separators (no writes outside agents/ via traversal) and the
+    # dot names. Shared by create_agent and the CLI so both agree.
+    #
+    # @param name [String] agent name
+    # @return [Boolean]
+    def self.unsafe_name?(name)
+      name == '.' || name == '..' || name.match?(%r{[/\\]})
+    end
 
     # @param root [String] project root (agents/ lives there)
     def initialize(root:)
@@ -15,25 +27,52 @@ module Letsdo
     #
     # @return [Array<String>]
     def list
-      Dir.glob(File.join(agents_dir, "*.md")).sort.map { |path| File.basename(path, ".md") }
+      Dir.glob(File.join(agents_dir, '*.md')).sort.map { |path| File.basename(path, '.md') }
     end
 
-    # Reads an agent prompt.
+    # Reads an agent prompt. There are no unknown agents: when
+    # agents/<name>.md is missing, the caller falls back to the built-in
+    # default prompt (Letsdo::DefaultPrompt) and announces it (see CLI).
     #
     # @param name [String] agent name
-    # @return [String] contents of agents/<name>.md
-    # @raise [UnknownAgentError] if there is no such agent
+    # @return [String, nil] contents of agents/<name>.md, nil when missing
     def read(name)
-      path = File.join(agents_dir, "#{name}.md")
-      raise UnknownAgentError, name unless File.file?(path)
+      path = agent_path(name)
+      return nil unless File.file?(path)
 
       File.read(path)
     end
 
+    # Absolute path of an agent's prompt file, whether or not it exists.
+    #
+    # @param name [String] agent name
+    # @return [String] <root>/agents/<name>.md (resolved to an absolute path)
+    def agent_path(name)
+      File.expand_path(File.join(agents_dir, "#{name}.md"))
+    end
+
+    # Creates agents/<name>.md with the given content. Never raises and
+    # never writes anything when the file already exists or the name is
+    # unsafe (contains "/" or "\\", or is "."/"..") — returns false in
+    # both cases. Otherwise mkdir_p the agents/ dir, writes the content
+    # and returns true. Creation always stays inside agents/.
+    #
+    # @param name [String] agent name (also the would-be file name)
+    # @param content [String] prompt text to write
+    # @return [Boolean] true when the file was created, false otherwise
+    def create_agent(name, content)
+      return false if self.class.unsafe_name?(name)
+      return false if File.exist?(agent_path(name))
+
+      FileUtils.mkdir_p(agents_dir)
+      File.write(agent_path(name), content)
+      true
+    end
+
     private
 
     def agents_dir
       File.join(@root, AGENTS_DIR)
     end
   end
-end
+end

data/lib/letsdo/tui/input.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "stringio"
+require 'stringio'
 
 module Letsdo
   module Tui
@@ -21,7 +21,7 @@ module Letsdo
       POLL_TIMEOUT = 0.1
 
       KEY_BY_VALUE = {
-        "p" => :p, "r" => :r, "q" => :q,
+        'p' => :p, 'r' => :r, 'q' => :q,
         "\u0003" => :ctrl_c,
         "\e[A" => :up, "\eOA" => :up,
         "\e[B" => :down, "\eOB" => :down,
@@ -37,7 +37,7 @@ module Letsdo
       # @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"
+        require 'tty-reader'
 
         @stdin = stdin
         @poll_timeout = poll_timeout
@@ -90,4 +90,4 @@ module Letsdo
       end
     end
   end
-end
+end

data/lib/letsdo/tui/log_buffer.rb

@@ -19,14 +19,14 @@ module Letsdo
       # Default maximum number of complete lines kept in the buffer.
       MAX_LINES = 2_000
       # The run-boundary separator line.
-      DIVIDER = "─" * 40
+      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 = +""
+        @pending = +''
         @max_lines = max_lines
         @version = 0
       end
@@ -108,4 +108,4 @@ module Letsdo
       end
     end
   end
-end
+end

data/lib/letsdo/tui/metrics.rb

@@ -94,4 +94,4 @@ module Letsdo
       end
     end
   end
-end
+end