letsdo 0.3.0 → 0.6.1

data/lib/letsdo.rb

@@ -6,32 +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.3.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -79,10 +79,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.77.0
-description: 'letsdo — a local agent worker for Backlog.md/markdown tasks. OOP structure:
-  Letsdo::PromptStore (agents/), Letsdo::OutputStreamer and Letsdo::PiRunner (pi --mode
-  json), Letsdo::Agent (one run), Letsdo::Loop (orchestrator loop), Letsdo::CLI. Minitest
-  tests. Will later be split into a separate repository.'
+description: letsdo turns a plain markdown backlog into a team of autonomous local
+  agents. Each agent is just a prompt file in agents/; run `letsdo <name>` and it
+  works through every open task assigned to that agent, one task per run, and stops
+  cleanly on Ctrl+C. No framework, no hosted platform — the backlog folder is the
+  single source of truth and task data never leaves your machine.
 email:
 - udalov.x@mail.ru
 executables:
@@ -90,28 +91,50 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - 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/cli/launch.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
@@ -119,17 +142,20 @@ 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
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sergio-fry/letsdo
   source_code_uri: https://github.com/sergio-fry/letsdo
+  bug_tracker_uri: https://github.com/sergio-fry/letsdo/issues
   changelog_uri: https://github.com/sergio-fry/letsdo/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/sergio-fry/letsdo/blob/main/README.md
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
 rdoc_options: []
@@ -139,14 +165,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !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/cli/launch.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-module Letsdo
-  # Builds the agent, provider, and orchestrator loop for CLI run paths.
-  module CLILaunch
-    private
-
-    def run_agent_plain(name)
-      streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
-      agent_loop(name, streamer, stderr: @stderr).run
-    end
-
-    def run_agent_tui(name)
-      ctx = tui_context(name)
-      session = Tui::Session.new(**ctx[:session])
-      session.run { ctx[:loop].run }
-    end
-
-    def tui_context(name)
-      parts = tui_parts(name)
-      {
-        loop: tui_loop(name, parts),
-        session: tui_session_args(name, **parts)
-      }
-    end
-
-    def tui_parts(name)
-      clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
-      handle = assignee_handle(name)
-      log = Tui::LogBuffer.new
-      {
-        clock: clock, handle: handle, log: log,
-        metrics: tui_metrics(name, handle, clock, log),
-        agent: agent_for(name, OutputStreamer.new(log: log)),
-        provider: provider_for(handle),
-        pause_gate: Control::PauseGate.new
-      }
-    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[:metrics],
-        terminal: Tui::Terminal.new(stream: @stdout),
-        input: Tui::Input.new(stdin: @stdin),
-        refresh: -> { parts[:provider].call },
-        wait_seconds: wait_seconds, clock: parts[:clock],
-        pause_gate: parts[:pause_gate], runner: -> { parts[:agent].runner }
-      }
-    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
-  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? ? ENV['LETSDO_DEBUG'] == '1' : 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