letsdo 0.4.0 → 0.6.1

data/lib/letsdo/tui/window_title.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Letsdo
+  module Tui
+    # Names the tmux window after the running agent (TASK-90) and restores
+    # the previous label on exit.
+    #
+    # tmux labels a window after its foreground process (automatic-rename),
+    # which for letsdo is always "ruby" — useless when one agent runs per
+    # pane. Two tmux facts (verified against tmux 3.4) shape this class:
+    #
+    #   * an OSC-2 title escape only sets the *pane* title; the window label
+    #     still follows the process name;
+    #   * so the window must be renamed explicitly and automatic-rename
+    #     disabled for the session, or tmux overwrites the label.
+    #
+    # Every tmux call goes through an injectable runner (tests stub it) and
+    # every failure is swallowed: title handling may never break a session.
+    # Being inside tmux on a TTY stream is the gate, so outside tmux nothing
+    # is written and the tmux binary is never invoked.
+    class WindowTitle
+      # OSC-2 title escape; only emitted inside tmux (see #install).
+      TITLE_TEMPLATE = "\e]2;%s\a"
+      # automatic-rename value meaning "no explicit setting" (tmux default on).
+      UNSET = ''
+
+      # @param stream [IO] terminal output stream (title escapes go here)
+      # @param env [Hash, ENV] source of TMUX / TMUX_PANE
+      # @param runner [Proc, nil] callable(Array<String>) → stdout String;
+      #        defaults to the real tmux binary, stubbed in tests
+      def initialize(stream:, env:, runner: nil)
+        @stream = stream
+        @env = env
+        @runner = runner || method(:run_tmux)
+        @previous = nil
+      end
+
+      # Saves the current window label and labels the window with `name`.
+      # No-op outside tmux, or when the stream is not a TTY.
+      def install(name)
+        return unless tmux?
+
+        state = capture
+        return unless state
+
+        label(name)
+        write_title(name)
+        @previous = state
+      end
+
+      # Puts the saved label back and restores automatic-rename, unsetting
+      # the option when it had no explicit value before (no leftover state).
+      def restore
+        state = @previous
+        return unless state
+
+        @previous = nil
+        label(state[:name])
+        restore_automatic_rename(state[:automatic_rename])
+        write_title(state[:name])
+      end
+
+      # Whether a tmux session hosts this process and titles can be set.
+      def tmux?
+        return false unless @stream.respond_to?(:tty?) && @stream.tty?
+
+        !@env['TMUX'].to_s.empty?
+      end
+
+      private
+
+      # Renames the window, then disables automatic-rename so tmux keeps the
+      # label for the whole session.
+      def label(name)
+        tmux('rename-window', name)
+        tmux('set-option', '-w', 'automatic-rename', 'off')
+      end
+
+      def restore_automatic_rename(value)
+        return tmux('set-option', '-w', '-u', 'automatic-rename') if value == UNSET
+
+        tmux('set-option', '-w', 'automatic-rename', value)
+      end
+
+      # The current window label and automatic-rename value, or nil when the
+      # label cannot be read (no tmux, no server, failed command).
+      def capture
+        name = tmux('display-message', '-p', "\#{window_name}").to_s.strip
+        return nil if name.empty?
+
+        { name: name, automatic_rename: automatic_rename_option }
+      end
+
+      def automatic_rename_option
+        tmux('show-window-options', '-v', 'automatic-rename').to_s.strip
+      end
+
+      def write_title(text)
+        @stream.write(format(TITLE_TEMPLATE, text))
+        @stream.flush
+      end
+
+      # One tmux command through the injected runner; a missing binary, an
+      # unreachable server or a failed command all yield nil.
+      def tmux(*args)
+        @runner.call(window_args(*args))
+      rescue StandardError
+        nil
+      end
+
+      # Targets the pane letsdo runs in, so the commands act on the right
+      # window even when the tmux server has no attached client. `-t` is a
+      # command option and must follow the subcommand.
+      def window_args(*args)
+        pane = @env['TMUX_PANE'].to_s
+        return args if pane.empty?
+
+        [args.first, '-t', pane, *args.drop(1)]
+      end
+
+      # @param args [Array<String>] tmux arguments
+      # @return [String] the command's stdout
+      def run_tmux(args)
+        out, _err, status = Open3.capture3('tmux', *args)
+        raise "tmux failed: #{args.join(' ')}" unless status.success?
+
+        out
+      end
+    end
+  end
+end

data/lib/letsdo/tui.rb

@@ -7,6 +7,8 @@
 # timer, tasks remaining, current-task elapsed, waiting/PAUSED states), a
 # scrollable combined log and a key-help footer, and repaints from a
 # background input thread. Non-TTY output stays the plain line-stream.
+# Inside tmux the window is labeled with the agent name for the session and
+# the previous label is restored on exit (TASK-90).
 #
 # Components:
 #   Letsdo::Tui::LogBuffer  - thread-safe combined log (streamer target)
@@ -14,11 +16,13 @@
 #   Letsdo::Tui::Renderer   - pure function: state → framed String
 #   Letsdo::Tui::Terminal   - alt screen, cursor, frame rendering
 #   Letsdo::Tui::Input      - tty-reader key decoding (injectable)
+#   Letsdo::Tui::WindowTitle - names the tmux window after the agent
 #   Letsdo::Tui::Session    - controller: terminal lifecycle + input thread
 
 require_relative 'tui/log_buffer'
 require_relative 'tui/metrics'
 require_relative 'tui/renderer'
 require_relative 'tui/terminal'
+require_relative 'tui/window_title'
 require_relative 'tui/input'
 require_relative 'tui/session'

data/lib/letsdo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letsdo
-  VERSION = '0.4.0'
+  VERSION = '0.6.1'
 end

data/lib/letsdo.rb

@@ -6,33 +6,44 @@
 #   Letsdo::Errors           - error hierarchy (Letsdo::Error and others)
 #   Letsdo::PromptStore      - access to agents/*.md prompts
 #   Letsdo::DefaultPrompt    - the built-in default prompt (fallback run, --init template)
+#   Letsdo::AgentIdentity    - the identity block injected into every agent prompt
 #   Letsdo::OutputStreamer   - where and how agent text and service lines are printed
-#   Letsdo::PiRunner         - running pi --mode json and parsing the event stream
+#   Letsdo::Backends::Pi     - running pi --mode json and parsing the event stream
 #   Letsdo::Agent            - a single agent run: prompt from agents/ or default + pi
 #   Letsdo::Capture          - interruption-safe child stdout/stderr capture
 #   Letsdo::BacklogTasks     - open tasks from the backlog CLI (the task provider)
 #   Letsdo::Loop             - generic orchestrator: tasks → runs → waiting
+#   Letsdo::RetryPolicy      - per-task retry/backoff/give-up policy (used at AgentLoop level)
 #   Letsdo::AgentLoop        - letsdo wiring: provider + agent + signals + messages
-#   Letsdo::Control          - agent-control primitives (PauseGate)
+#   Letsdo::Control          - agent-control primitives (PauseGate, Reader)
+#   Letsdo::Doctor           - `letsdo doctor` environment self-check
 #   Letsdo::Tui              - the interactive TUI (LogBuffer, Metrics,
-#                              Renderer, Terminal, Input, Session)
+#                              Renderer, Terminal, WindowTitle, Input, Session)
 #   Letsdo::CLI              - command-line arguments, usage, exit code
 #
 # Entry point — bin/letsdo (a thin wrapper over Letsdo::CLI).
 
 require_relative 'letsdo/version'
 require_relative 'letsdo/errors'
+require_relative 'letsdo/duration'
 require_relative 'letsdo/config'
 require_relative 'letsdo/prompt_store'
 require_relative 'letsdo/default_prompt'
+require_relative 'letsdo/agent_identity'
 require_relative 'letsdo/output_streamer'
-require_relative 'letsdo/pi_runner'
+require_relative 'letsdo/backends/backend'
+require_relative 'letsdo/backends/pi'
 require_relative 'letsdo/agent'
 require_relative 'letsdo/capture'
-require_relative 'letsdo/backlog_tasks'
+require_relative 'letsdo/providers/backlog'
 require_relative 'letsdo/loop'
+require_relative 'letsdo/retry_policy'
 require_relative 'letsdo/watcher'
 require_relative 'letsdo/agent_loop'
+require_relative 'letsdo/session_recorder'
+require_relative 'letsdo/task_time_writeback'
+require_relative 'letsdo/metrics/fanout'
 require_relative 'letsdo/control'
+require_relative 'letsdo/doctor'
 require_relative 'letsdo/tui'
 require_relative 'letsdo/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -95,27 +95,46 @@ files:
 - LICENSE
 - README.md
 - bin/letsdo
+- docs/config.md
+- docs/prompts.md
+- docs/task-selection.md
+- docs/usage.md
 - letsdo.gemspec
 - lib/letsdo.rb
 - lib/letsdo/agent.rb
+- lib/letsdo/agent_identity.rb
 - lib/letsdo/agent_loop.rb
+- lib/letsdo/agent_loop/assignee_hints.rb
 - lib/letsdo/agent_loop/tasks.rb
-- lib/letsdo/backlog_tasks.rb
+- lib/letsdo/backends/backend.rb
+- lib/letsdo/backends/pi.rb
+- lib/letsdo/backends/pi/events.rb
 - lib/letsdo/capture.rb
 - lib/letsdo/cli.rb
 - lib/letsdo/cli/builder.rb
+- lib/letsdo/cli/builder_assembly.rb
+- lib/letsdo/cli/builder_metrics.rb
+- lib/letsdo/cli/doctor.rb
 - lib/letsdo/cli/init.rb
 - lib/letsdo/config.rb
 - lib/letsdo/control.rb
+- lib/letsdo/control/reader.rb
 - lib/letsdo/default_prompt.rb
+- lib/letsdo/doctor.rb
+- lib/letsdo/doctor/checks.rb
+- lib/letsdo/duration.rb
 - lib/letsdo/errors.rb
 - lib/letsdo/loop.rb
+- lib/letsdo/metrics/fanout.rb
 - lib/letsdo/output_streamer.rb
 - lib/letsdo/output_streamer/arg_summary.rb
-- lib/letsdo/pi_runner.rb
-- lib/letsdo/pi_runner/events.rb
-- lib/letsdo/pi_runner/process.rb
 - lib/letsdo/prompt_store.rb
+- lib/letsdo/providers/backlog.rb
+- lib/letsdo/providers/task.rb
+- lib/letsdo/retry_policy.rb
+- lib/letsdo/session_recorder.rb
+- lib/letsdo/session_recorder/jsonl_writer.rb
+- lib/letsdo/task_time_writeback.rb
 - lib/letsdo/tui.rb
 - lib/letsdo/tui/input.rb
 - lib/letsdo/tui/log_buffer.rb
@@ -123,8 +142,10 @@ files:
 - lib/letsdo/tui/renderer.rb
 - lib/letsdo/tui/session.rb
 - lib/letsdo/tui/session/keys.rb
+- lib/letsdo/tui/session/terminal.rb
 - lib/letsdo/tui/session/view.rb
 - lib/letsdo/tui/terminal.rb
+- lib/letsdo/tui/window_title.rb
 - lib/letsdo/version.rb
 - lib/letsdo/watcher.rb
 homepage: https://github.com/sergio-fry/letsdo
@@ -151,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.21
 specification_version: 4
 summary: A local agent worker for Backlog.md/markdown tasks
 test_files: []

data/lib/letsdo/backlog_tasks.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'shellwords'
-
-module Letsdo
-  # Task provider for Letsdo::Loop backed by the real backlog CLI:
-  #
-  #   backlog task list --assignee <handle> --exclude-status Done --json
-  #
-  # Returns the list of open tasks assigned to the handle (an Array, empty
-  # when there are none), or nil when the backlog state is unreadable — the
-  # CLI is not on PATH, failed, or its output is not the expected JSON. The
-  # loop treats nil as "pause and retry, do not run the agent".
-  #
-  # The command runs in the project root (cwd), where the backlog CLI finds
-  # the backlog/ folder — the same context as a single agent run.
-  class BacklogTasks
-    # @param handle [String] assignee handle to filter by (e.g. "@developer")
-    # @param command [String] backlog CLI command (overridable for tests)
-    # @param cwd [String, nil] project root for the CLI; nil = inherit cwd
-    # @param env [Hash, nil] environment for the CLI child (nil = inherit
-    #        the process environment; injected in tests to control the
-    #        fake backlog scenarios)
-    def initialize(handle:, command: 'backlog', cwd: nil, env: nil)
-      @handle = handle
-      @command = command
-      @cwd = cwd
-      @env = env
-    end
-
-    # Reads the open tasks once.
-    #
-    # @return [Array<Hash>, nil] open tasks; nil when the backlog is unreadable
-    def call
-      args = @env ? [@env, *command_line] : command_line
-      out, _err, status = Letsdo::Capture.new(*args, chdir: @cwd).run
-      return nil unless status.success?
-
-      tasks = JSON.parse(out)['tasks']
-      tasks.is_a?(Array) ? tasks : nil
-    rescue Errno::ENOENT, JSON::ParserError, TypeError
-      nil
-    end
-
-    private
-
-    # [command..., task, list, --assignee <handle>, --exclude-status Done, --json]
-    def command_line
-      [
-        *Shellwords.split(@command),
-        'task', 'list',
-        '--assignee', @handle,
-        '--exclude-status', 'Done',
-        '--json'
-      ]
-    end
-  end
-end

data/lib/letsdo/pi_runner/events.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Letsdo
-  # Pi JSON event-stream handlers used by PiRunner.
-  module PiRunnerEvents
-    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

data/lib/letsdo/pi_runner/process.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Letsdo
-  # Process-group control for a running pi child.
-  module PiRunnerProcess
-    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
-
-    private
-
-    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 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 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
-
-    def exit_code(status)
-      return 1 if status.nil?
-      return status.exitstatus if status.exitstatus
-
-      status.termsig ? 128 + status.termsig : 1
-    end
-  end
-end

data/lib/letsdo/pi_runner.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module Letsdo
-  # 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'
-  end
-end
-
-require_relative 'pi_runner/events'
-require_relative 'pi_runner/process'
-
-module Letsdo
-  # Pi process spawn, stream drain, and pause/resume signals.
-  class PiRunner
-    include PiRunnerEvents
-    include PiRunnerProcess
-
-    def initialize(prompt:, streamer:, **opts)
-      @prompt = prompt
-      @streamer = streamer
-      @flags = opts.fetch(:flags, [])
-      @command = opts.fetch(:command, COMMAND)
-      @pending_tools = {}
-      @reaped_status = nil
-      @debug = opts[:debug].nil? ? (opts[:config] || Config.new).debug? : opts[:debug]
-    end
-
-    def run
-      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
-
-    def terminate_now
-      pid = @pid
-      send_signal('TERM', pid) if pid
-    end
-
-    def pause
-      pid = @pid
-      send_signal('STOP', pid) if pid
-    end
-
-    def resume
-      pid = @pid
-      send_signal('CONT', pid) if pid
-    end
-
-    private
-
-    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 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
-  end
-end