letsdo 0.3.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,13 +66,33 @@ 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]
-      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @debug = resolve_debug(opts)
       @watcher = opts[:watcher] || (Watcher.new(path: opts[:watch_path]) if opts[:watch_path])
       # Precedence is deliberate: an explicitly injected sleeper always wins
       # over the watcher idle path — tests inject a stop/control sleeper that
@@ -64,6 +100,12 @@ module Letsdo
       @sleeper = opts[:sleeper] || watcher_sleeper || ->(seconds) { sleep(seconds) }
     end
 
+    def resolve_debug(opts)
+      return opts[:debug] unless opts[:debug].nil?
+
+      (opts[:config] || Config.new).debug?
+    end
+
     def watcher_sleeper
       @watcher && ->(seconds) { @watcher.wait(seconds) }
     end

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

@@ -0,0 +1,102 @@
+# 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, 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, recorder)
+        parts = tui_parts(name, recorder)
+        {
+          loop: tui_loop(name, parts),
+          session: tui_session_args(name, **parts)
+        }
+      end
+
+      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, header: header,
+          metrics: Letsdo::Metrics::Fanout.new(recorder, header),
+          agent: agent_for(name, OutputStreamer.new(log: log)),
+          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],
+                              metrics: parts[:metrics], pause_gate: parts[:pause_gate])
+      end
+
+      def tui_metrics(name, handle, clock, log)
+        Tui::Metrics.new(name: name, handle: handle, clock: clock,
+                         on_run_start: ->(_label) { log.divider })
+      end
+
+      def tui_session_args(name, **parts)
+        {
+          name: name, handle: parts[:handle], log: parts[:log], metrics: parts[:header],
+          terminal: Tui::Terminal.new(stream: @stdout),
+          input: Tui::Input.new(stdin: @stdin),
+          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].backend }
+        }
+      end
+    end
+
+    # Owns all component assembly for running an agent (TASK-54): builds the
+    # 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. The wiring lives in BuilderAssembly so the
+    # class stays within the class-length limit.
+    class Builder
+      include BuilderTui
+      include BuilderAssembly
+      include BuilderMetrics
+    end
+  end
+end

data/lib/letsdo/cli/builder_assembly.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # Provider and backend registries used by Letsdo::CLI::Builder: name ->
+    # factory maps, injectable via the constructor for tests. Kept separate so
+    # the assembly module stays within the module-length limit.
+    module BuilderRegistries
+      # Provider registry: maps LETSDO_PROVIDER names to factories that build
+      # a provider from handle, command, cwd, and env.  Inject a custom
+      # registry via the constructor for tests.
+      PROVIDERS = {
+        'backlog' => lambda do |handle:, command:, cwd:, env:|
+          Providers::Backlog.new(handle: handle, command: command, cwd: cwd, env: env)
+        end
+      }.freeze
+
+      # Backend registry: maps LETSDO_BACKEND names to factory builders that
+      # take the Letsdo::Config and return a backend_factory (callable with
+      # prompt:, streamer:, model:). The pi entry captures the pi command and
+      # flags from Config (LETSDO_PI_COMMAND / LETSDO_PI_FLAGS with the
+      # AGENT_PI_FLAGS fallback), keeping pi vocabulary out of the business
+      # layer.  Inject a custom registry via the constructor for tests.
+      BACKENDS = {
+        'pi' => lambda do |config:|
+          command = config.pi_command
+          flags = config.pi_flags
+          lambda { |prompt:, streamer:, model: nil|
+            Letsdo::Backends::Pi.new(prompt: prompt, streamer: streamer,
+                                     flags: flags, command: command,
+                                     model: model, config: config)
+          }
+        end
+      }.freeze
+    end
+
+    # Registry-driven component wiring for Letsdo::CLI::Builder: the run
+    # entry point, agent/provider/loop assembly and the plain-mode run path.
+    # Extracted into its own module so Builder stays within the class-length
+    # limit (same reason as the BuilderTui split).
+    module BuilderAssembly
+      include BuilderRegistries
+
+      def initialize(env:, stdout:, stderr:, **rest)
+        @env = env
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = rest[:stdin] || $stdin
+        @sleeper = rest[:sleeper]
+        @config = Config.new(env: env)
+        @root = @config.root
+        @provider_registry = rest[:provider_registry] || PROVIDERS
+        @backend_registry = rest[:backend_registry] || BACKENDS
+      end
+
+      # Runs <name> in plain or TUI mode; returns the process exit code.
+      def run(name)
+        return 1 unless resolve_provider!
+        return 1 unless resolve_backend!
+
+        store = PromptStore.new(root: @root)
+        announce_default_prompt(name, store) if store.read(name).nil?
+        recorder = build_recorder(name)
+        tui? ? run_tui(name, recorder) : run_plain(name, recorder)
+      end
+
+      private
+
+      def agent_for(name, streamer)
+        Agent.new(name: name, root: @root, handle: assignee_handle(name),
+                  backend_factory: @selected_backend_factory,
+                  streamer: streamer)
+      end
+
+      # Resolves LETSDO_BACKEND through the backend registry once per run,
+      # so both wiring paths (plain and TUI) build the Agent's
+      # backend_factory through the same registry entry.  An unknown backend
+      # name fails fast instead of silently falling back.
+      def resolve_backend!
+        builder = @backend_registry[@config.backend]
+        if builder
+          @selected_backend_factory = builder.call(config: @config)
+          return true
+        end
+
+        @stderr.puts("letsdo: unknown AI backend: #{@config.backend}")
+        false
+      end
+
+      def resolve_provider!
+        @selected_provider_factory = @provider_registry[@config.provider]
+        return true if @selected_provider_factory
+
+        @stderr.puts("letsdo: unknown task provider: #{@config.provider}")
+        false
+      end
+
+      def provider_for(handle)
+        @selected_provider_factory.call(
+          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)
+        # The provider object itself (not a wrapping lambda) reaches the loop
+        # so the once-per-run assignee mismatch hint can read its
+        # #assignee_variants (TASK-96).
+        AgentLoop.new(name: name, handle: handle, agent: agent,
+                      task_provider: provider,
+                      wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
+                      metrics: opts[:metrics], pause_gate: opts[:pause_gate],
+                      watcher: backlog_watcher, **retry_options)
+      end
+
+      def retry_options
+        { retry_base: @config.retry_base, retry_cap: @config.retry_cap, max_retries: @config.max_retries }
+      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
+    end
+  end
+end