letsdo 0.4.0 → 0.6.1

data/lib/letsdo/agent_loop.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 require_relative 'agent_loop/tasks'
+require_relative 'agent_loop/assignee_hints'
 
 module Letsdo
   # The orchestrator loop wired to the real environment for `letsdo <name>`.
   class AgentLoop
     include AgentLoopTasks
+    include AgentLoopAssigneeHints
 
     STOP = :letsdo_stop
     PAUSE_POLL_SECONDS = 0.05
@@ -18,8 +20,7 @@ module Letsdo
     end
 
     def run
-      @loop = build_loop
-      install_signal_handlers
+      prepare_run
       debug("loop start (agent=#{@name}, handle=#{@handle}, wait=#{@wait_seconds}s)")
       run_until_stopped
       debug('loop stopped')
@@ -30,6 +31,15 @@ module Letsdo
       restore_signal_handlers
     end
 
+    # The `letsdo doctor` hint rides on the first unavailable backlog call
+    # of a run only: later nils repeat the same diagnosis, and a wall of
+    # hints would just add noise (TASK-93).
+    def unavailable_message
+      hint = @unavailable_hinted ? '' : ' - run `letsdo doctor` to diagnose'
+      @unavailable_hinted = true
+      "letsdo: backlog unavailable, retrying in #{@wait_seconds}s#{hint}"
+    end
+
     def close_watcher
       @watcher&.close
     end
@@ -38,8 +48,14 @@ module Letsdo
       warn("[letsdo] loop: #{message}") if @debug
     end
 
+    # Stop the running backend immediately.  The signal handler is
+    # invoked from the main thread (Ruby 4.0) or from a dedicated signal
+    # thread (3.x fallback via AGENT_SIGNAL_THREAD=1).  Thread.raise
+    # works reliably on CRuby 4.0: M:N fibers make threads interruptible
+    # everywhere, so a trap handler may safely raise Letsdo::Stopped on
+    # the main thread to unwind the current run.
     def on_signal(_signum)
-      @agent&.runner&.terminate_now
+      @agent&.backend&.terminate_now
       raise Letsdo::Stopped
     end
 
@@ -50,9 +66,29 @@ module Letsdo
       @run_one = opts[:run_one] || ->(_task) { @agent.run }
       @wait_seconds = opts.fetch(:wait_seconds, 10.0)
       @stderr = opts.fetch(:stderr, $stderr)
+      @retry_policy = build_retry_policy(opts)
+      @last_attempted = {}
       assign_control_opts(opts)
     end
 
+    def prepare_run
+      @loop = build_loop
+      install_signal_handlers
+      @unavailable_hinted = false
+      @variants_hinted = false
+    end
+
+    def build_retry_policy(opts)
+      return opts[:retry_policy] if opts[:retry_policy]
+
+      Letsdo::RetryPolicy.new(
+        base: opts.fetch(:retry_base, @wait_seconds),
+        cap: opts.fetch(:retry_cap, Letsdo::RetryPolicy::DEFAULT_CAP),
+        max_retries: opts.fetch(:max_retries, Letsdo::RetryPolicy::DEFAULT_MAX_RETRIES),
+        clock: opts[:clock]
+      )
+    end
+
     def assign_control_opts(opts)
       @metrics = opts[:metrics]
       @pause_gate = opts[:pause_gate]

data/lib/letsdo/backends/backend.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative '../config'
+
+module Letsdo
+  module Backends
+    # The documented backend protocol plus shared process-lifecycle helpers.
+    #
+    # Concrete adapters (Pi) add subprocess management and streaming.
+    # In-process fakes (test helpers) override terminate_now and skip
+    # spawning entirely.
+    #
+    # Protocol:
+    #   run                              → Integer child exit code
+    #   terminate_now                    trap-safe, no waits/IO
+    #   terminate(signal:, grace:, tick:) → no-op when already finished
+    #   pause / resume                   SIGSTOP/SIGCONT to the process group
+    #   debug(message)                   '[letsdo] pi:' when debug is on
+    #
+    # Normalized events emitted at the injected streamer:
+    #   text_delta(delta)        tool_start(name, args: nil)
+    #   tool_result(name, text)  finish
+    # finish is called exactly once per run.
+    class Backend
+      # @param prompt [String] the stripped prompt text (no front-matter).
+      # @param streamer [Letsdo::OutputStreamer] normalized event sink.
+      # @param debug  [Boolean, nil] trace override; nil → check env.
+      # @param config [Letsdo::Config, nil] debug source (LETSDO_DEBUG);
+      #        nil → Config.new for env-only lookups.
+      def initialize(prompt:, streamer:, debug: nil, config: nil)
+        @prompt   = prompt
+        @streamer = streamer
+        @debug    = debug.nil? ? (config || Config.new).debug? : debug
+        @pid = nil
+        @reaped_status = nil
+      end
+
+      # Run the backend.  Subclasses must override; the base returns nil.
+      def run
+        raise NotImplementedError,
+              "#{self.class.name} must implement #run"
+      end
+
+      # ── signal helpers ────────────────────────────────────────────
+      # All are trap-safe (no waits, no IO) and swallow ESRCH/EPERM.
+
+      def terminate_now
+        pid = @pid
+        send_signal('TERM', pid) if pid
+      end
+
+      def pause
+        pid = @pid
+        send_signal('CONT', pid) if pid
+        send_signal('SIGSTOP', pid) if pid
+      end
+
+      def resume
+        pid = @pid
+        send_signal('SIGCONT', pid) if pid
+      end
+
+      # Graceful stop, then SIGKILL after *grace* seconds.
+      # Returns true when the process already finished.
+      def terminate(signal: 'TERM', grace: 3.0, tick: 0.05)
+        pid = @pid
+        return true unless pid
+
+        send_signal('CONT', pid)
+        send_signal(signal, pid)
+        wait_for_exit(pid, grace, tick)
+      end
+
+      # ── tracing ───────────────────────────────────────────────────
+
+      def debug(message)
+        warn("[letsdo] pi: #{message}") if @debug
+      end
+
+      private
+
+      # ── process-lifecycle helpers (shared with concrete adapters) ──
+
+      def wait_status(pid, nonblock: false)
+        _, status = Process.wait2(pid, nonblock ? Process::WNOHANG : 0)
+        @reaped_status = status if status
+        status
+      rescue Errno::ECHILD
+        @reaped_status
+      end
+
+      def wait_for_exit(pid, grace, tick)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + grace
+        loop do
+          status = wait_status(pid, nonblock: true)
+          return status if status
+          break unless alive?(pid)
+          return kill_and_reap(pid, tick) if overdue_deadline?(deadline)
+
+          sleep(tick)
+        end
+        true
+      end
+
+      def overdue_deadline?(deadline)
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+      end
+
+      def kill_and_reap(pid, tick)
+        send_signal('KILL', pid)
+        sleep(tick)
+        wait_status(pid, nonblock: true) || true
+      end
+
+      def send_signal(signal, pid)
+        Process.kill(signal, -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def alive?(pid)
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+
+      # 0/N from a clean exit; 128+signal for a killed run; 1 when unknown.
+      def exit_code(status)
+        return 1 if status.nil?
+        return status.exitstatus if status.exitstatus
+
+        status.termsig ? 128 + status.termsig : 1
+      end
+    end
+  end
+end

data/lib/letsdo/backends/pi/events.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Backends
+    # Pi JSON event-stream handlers used by Letsdo::Backends::Pi.
+    module PiEvents
+      private
+
+      def read_pi_stream(out_r)
+        out_r.each_line { |line| handle_line(line) }
+        debug('stream: EOF')
+      end
+
+      def handle_line(line)
+        line = line.strip
+        return if line.empty?
+
+        event = parse_event(line)
+        dispatch_event(event) if event
+      end
+
+      def dispatch_event(event)
+        case event['type']
+        when 'message_update' then handle_message_update(event)
+        when 'tool_execution_start' then handle_tool_start(event)
+        when 'tool_execution_end' then handle_tool_execution_end(event)
+        when 'agent_end' then flush_pending_tools
+        end
+      end
+
+      def handle_tool_start(event)
+        @pending_tools.delete(event['toolCallId'])
+        @streamer.tool_start(event['toolName'] || 'tool', args: event['args'])
+      end
+
+      def handle_message_update(event)
+        payload = event['assistantMessageEvent']
+        return unless payload
+
+        handle_text_delta(payload) || remember_toolcall(event, payload)
+      end
+
+      def handle_text_delta(payload)
+        return unless payload['type'] == 'text_delta'
+
+        delta = payload['delta']
+        @streamer.text_delta(delta) if delta && !delta.empty?
+        true
+      end
+
+      def remember_toolcall(event, payload)
+        return unless payload['type'] == 'toolcall_start'
+
+        id = event['id'] || payload['id']
+        name = event['toolName'] || payload['toolName'] || 'tool'
+        @pending_tools[id] = name unless id.nil?
+      end
+
+      def handle_tool_execution_end(event)
+        name = event['toolName'] || 'tool'
+        error = event['isError'] == true
+        @streamer.tool_result(name, error: error)
+      end
+
+      def flush_pending_tools
+        @pending_tools.each_value { |name| @streamer.tool_start(name) }
+        @pending_tools.clear
+      end
+
+      def parse_event(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/letsdo/backends/pi.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'pi/events'
+
+module Letsdo
+  module Backends
+    # Runs pi --mode json and hands normalized events to the streamer.
+    #
+    # Pi-specific knowledge lives here (spawn command, JSON event schema,
+    # exit-code mapping, process-group termination) -- the business layer
+    # sees only the backend protocol.
+    class Pi < Backend
+      COMMAND = 'pi'
+      MODE    = 'json'
+
+      def initialize(prompt:, streamer:, **options)
+        flags   = options.fetch(:flags, [])
+        command = options.fetch(:command, COMMAND)
+        model   = options[:model]
+        super(prompt: prompt, streamer: streamer, debug: options[:debug],
+              config: options[:config])
+        @command = command
+        @flags = flags.dup
+        @flags.unshift('--model', model) if model && !@flags.include?('--model')
+        @pending_tools = {}
+      end
+
+      def run
+        out_r = spawn_pi
+        drain_stream(out_r)
+        finish_run
+      ensure
+        @pid = nil
+        @reaped_status = nil
+      end
+
+      private
+
+      # spawn / drain / finish
+
+      def spawn_pi
+        cmd = [@command, '--mode', MODE, *@flags, @prompt]
+        out_r, out_w = IO.pipe
+        spawn_process(cmd, out_r, out_w)
+      end
+
+      def spawn_process(cmd, out_r, out_w)
+        @pid = Process.spawn(*cmd, out: out_w, err: $stderr, pgroup: true)
+        out_w.close
+        debug("spawned pid=#{@pid} (own group)")
+        out_r
+      rescue Errno::ENOENT, Errno::EACCES => e
+        out_w.close
+        out_r.close
+        raise Letsdo::BackendUnavailableError, "cannot start AI backend '#{@command}': #{e.message}"
+      end
+
+      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
+
+      def close_pipe(out_r)
+        out_r.close
+      rescue IOError
+        nil
+      end
+
+      def finish_run
+        status = wait_status(@pid)
+        @streamer.finish
+        debug("exit status=#{status.inspect} code=#{exit_code(status)}")
+        exit_code(status)
+      end
+
+      include PiEvents
+    end
+  end
+end

data/lib/letsdo/cli/builder.rb

@@ -1,38 +1,67 @@
 # frozen_string_literal: true
 
+require_relative 'builder_assembly'
+require_relative 'builder_metrics'
+
 module Letsdo
   class CLI
     # TUI component assembly used by Letsdo::CLI::Builder. Kept in its own
     # module so Builder stays within the class-length limit; mirrors the
     # CLILaunch/CLIInit split pattern.
     module BuilderTui
-      def run_tui(name)
-        ctx = tui_context(name)
+      def run_tui(name, recorder)
+        ctx = tui_context(name, recorder)
         session = Tui::Session.new(**ctx[:session])
         session.run { ctx[:loop].run }
+      ensure
+        finish_session(name, recorder)
       end
 
-      def tui_context(name)
-        parts = tui_parts(name)
+      def tui_context(name, recorder)
+        parts = tui_parts(name, recorder)
         {
           loop: tui_loop(name, parts),
           session: tui_session_args(name, **parts)
         }
       end
 
-      def tui_parts(name)
+      def tui_parts(name, recorder)
         clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
         handle = assignee_handle(name)
         log = Tui::LogBuffer.new
+        tui_parts_hash(name, recorder, clock, handle, log)
+      end
+
+      # Assembles the parts hash. The header facade (Tui::Metrics — the only
+      # object answering #snapshot, which the renderer needs) and the Fanout
+      # that forwards loop events to both recorder and header share the same
+      # header instance (TASK-92).
+      def tui_parts_hash(name, recorder, clock, handle, log)
+        header = tui_metrics(name, handle, clock, log)
+        provider = provider_for(handle)
         {
-          clock: clock, handle: handle, log: log,
-          metrics: tui_metrics(name, handle, clock, log),
+          clock: clock, handle: handle, log: log, header: header,
+          metrics: Letsdo::Metrics::Fanout.new(recorder, header),
           agent: agent_for(name, OutputStreamer.new(log: log)),
-          provider: provider_for(handle),
-          pause_gate: Control::PauseGate.new
+          provider: provider,
+          pause_gate: Control::PauseGate.new,
+          refresh: tui_refresh(provider, recorder)
         }
       end
 
+      # The manual 'r' refresh (TASK-42) queries the provider immediately.
+      # Its return value feeds the header; the same count is handed to the
+      # session recorder so the stop summary reports a fresh 'left' value
+      # (TASK-69).
+      def tui_refresh(provider, recorder)
+        lambda do
+          tasks = provider.call
+          count = tasks&.length
+          recorder.provider_result(count)
+          count
+        end
+      end
+
       def tui_loop(name, parts)
         agent_loop(name, nil, agent: parts[:agent], provider: parts[:provider],
                               handle: parts[:handle], stderr: parts[:log],
@@ -46,105 +75,28 @@ module Letsdo
 
       def tui_session_args(name, **parts)
         {
-          name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:metrics],
+          name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:header],
           terminal: Tui::Terminal.new(stream: @stdout),
           input: Tui::Input.new(stdin: @stdin),
-          refresh: -> { parts[:provider].call },
+          title: Tui::WindowTitle.new(stream: @stdout, env: @env),
+          refresh: parts[:refresh],
           wait_seconds: wait_seconds, clock: parts[:clock],
-          pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
+          pause_gate: parts[:pause_gate], runner: -> { parts[:agent].backend }
         }
       end
     end
 
     # Owns all component assembly for running an agent (TASK-54): builds the
-    # streamer, agent, backlog provider, orchestrator loop and the whole TUI,
+    # streamer, agent, task provider, orchestrator loop and the whole TUI,
     # and decides plain vs TUI mode via stdout/stdin TTY + TERM. Parsing stays
     # in Letsdo::CLI (TASK-54); this class is the wiring half — independently
     # testable and free to grow with provider/backend selection (TASK-51/52)
-    # without bloating the parser.
+    # without bloating the parser. The wiring lives in BuilderAssembly so the
+    # class stays within the class-length limit.
     class Builder
       include BuilderTui
-
-      def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
-        @env = env
-        @stdout = stdout
-        @stderr = stderr
-        @stdin = stdin
-        @sleeper = sleeper
-        @config = Config.new(env: env)
-        @root = @config.root
-      end
-
-      # Runs <name> in plain or TUI mode; returns the process exit code.
-      def run(name)
-        store = PromptStore.new(root: @root)
-        announce_default_prompt(name, store) if store.read(name).nil?
-        tui? ? run_tui(name) : run_plain(name)
-      end
-
-      private
-
-      def run_plain(name)
-        streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
-        agent_loop(name, streamer, stderr: @stderr).run
-      end
-
-      def agent_for(name, streamer)
-        Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
-                  command: pi_command)
-      end
-
-      def provider_for(handle)
-        BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
-                         env: ENV.to_h.merge(@env))
-      end
-
-      def agent_loop(name, streamer, **opts)
-        handle = opts[:handle] || assignee_handle(name)
-        agent = opts[:agent] || agent_for(name, streamer)
-        provider = opts[:provider] || provider_for(handle)
-        AgentLoop.new(name: name, handle: handle, agent: agent,
-                      task_provider: -> { provider.call },
-                      wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
-                      metrics: opts[:metrics], pause_gate: opts[:pause_gate],
-                      watcher: backlog_watcher)
-      end
-
-      def backlog_watcher
-        Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
-      end
-
-      # One-time fallback notification (before the first loop message): names
-      # the exact path checked and the placement hint. The agent still starts
-      # — Letsdo::Agent falls back to the built-in default prompt itself.
-      def announce_default_prompt(name, store)
-        @stderr.puts("letsdo: no prompt for #{name} at #{store.agent_path(name)}")
-        @stderr.puts("letsdo: using the built-in default prompt (create a prompt file with 'letsdo #{name} --init')")
-      end
-
-      def tui?
-        @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
-      end
-
-      def assignee_handle(name)
-        @config.assignee_handle(name)
-      end
-
-      def backlog_command
-        @config.backlog_command
-      end
-
-      def wait_seconds
-        @config.wait_seconds
-      end
-
-      def pi_command
-        @config.pi_command
-      end
-
-      def parse_pi_flags
-        @config.pi_flags
-      end
+      include BuilderAssembly
+      include BuilderMetrics
     end
   end
 end