letsdo 0.1.0 → 0.2.0

data/lib/letsdo/cli.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'shellwords'
+require_relative 'cli/launch'
+require_relative 'cli/init'
 
 module Letsdo
   # Command-line argument parsing and running an agent orchestrator loop.
@@ -10,46 +12,26 @@ module Letsdo
   #   letsdo --version             — version, exit code 0;
   #   letsdo --help                — usage, exit code 0;
   #   letsdo <name>                — run the <name> agent in the orchestrator
-  #                                    loop until SIGINT/SIGTERM: all open
-  #                                    tasks assigned to the agent are done
-  #                                    one run per task, the loop waits for
-  #                                    new ones; clean exit code 0;
-  #   letsdo <unknown name>        — "Unknown agent: <name>" + list,
-  #                                    exit code 1.
-  #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage,
-  #                                    exit code 1.
-  #
-  # Environment:
-  #   LETSDO_ROOT              project root (agents/ lives there); default — pwd.
-  #   LETSDO_PI_FLAGS          extra pi flags (split on whitespace; if unset —
-  #                            AGENT_PI_FLAGS is used for bin/agent
-  #                            compatibility).
-  #   LETSDO_PI_COMMAND        the pi command (default "pi"); overridable for
-  #                            tests/fake pi.
-  #   AGENT_ASSIGNEE_HANDLE    the agent's backlog assignee handle; default
-  #                            "@<name>" (the one rule: handle = name).
-  #   LETSDO_WAIT_SECONDS      retry interval when no tasks are open (if
-  #                            unset — AGENT_WAIT_SECONDS, default 10).
-  #   LETSDO_BACKLOG_COMMAND   the backlog CLI command (default "backlog");
-  #                            overridable for tests/fake backlog.
+  #                                    loop until SIGINT/SIGTERM;
+  #   letsdo <name> (no prompt)    — same, but on the built-in default prompt;
+  #                                    one-time notification on stderr
+  #                                    (path checked + 'letsdo <name> --init' hint);
+  #   letsdo <name> --init         — create agents/<name>.md with the starter
+  #                                    default prompt, never runs the agent;
+  #   letsdo --init <name>         — same, flag-first form;
+  #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage, exit 1.
   class CLI
+    include CLILaunch
+    include CLIInit
+
     USAGE = 'Usage: letsdo <agent_name>'
     AGENTS_HEADER = 'Available agents:'
     DEFAULT_WAIT_SECONDS = 10.0
 
-    # @param argv [Array<String>] command-line arguments
-    # @param env [Hash] process environment (LETSDO_ROOT, LETSDO_PI_FLAGS,
-    #        AGENT_PI_FLAGS, AGENT_ASSIGNEE_HANDLE, LETSDO_WAIT_SECONDS,
-    #        LETSDO_BACKLOG_COMMAND); injected in tests
-    # @param stdout [IO] stream for normal output (usage, --help, list)
-    # @param stderr [IO] stream for service output
-    # @param stdin [IO] keyboard stream (the TUI reads keys from it)
-    # @param sleeper [Proc, nil] waiting procedure for the loop (callable
-    #        with the interval); injected in tests for deterministic stops
-    # @return [Integer] exit code: 0 — success (incl. loop stop), 1 — error,
-    #         otherwise — pi exit code
-    def self.run(argv, env: ENV, stdout: $stdout, stderr: $stderr, stdin: $stdin, sleeper: nil)
-      new(env: env, stdout: stdout, stderr: stderr, stdin: stdin, sleeper: sleeper).run(argv)
+    def self.run(argv, **opts)
+      new(env: opts.fetch(:env, ENV), stdout: opts.fetch(:stdout, $stdout),
+          stderr: opts.fetch(:stderr, $stderr), stdin: opts.fetch(:stdin, $stdin),
+          sleeper: opts[:sleeper]).run(argv)
     end
 
     def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
@@ -61,103 +43,66 @@ module Letsdo
       @root = env.fetch('LETSDO_ROOT', Dir.pwd)
     end
 
-    # @param argv [Array<String>] command-line arguments
-    # @return [Integer] exit code
     def run(argv)
       arg = argv[0]
-      case arg
-      when '--version', '-v'
-        @stdout.puts(VERSION)
-        0
-      when '--help', '-h'
-        print_usage(@stdout)
-        0
-      when nil
-        print_usage(@stderr)
-        1
-      else
-        if arg.start_with?('-')
-          @stderr.puts("letsdo: unknown option: #{arg}")
-          print_usage(@stderr)
-          1
-        else
-          run_agent(arg)
-        end
-      end
+      return print_version if version_flag?(arg)
+      return print_help if help_flag?(arg)
+      return usage_error if arg.nil?
+      return init_command(argv) if argv.include?('--init')
+      return unknown_option(arg) if arg.start_with?('-')
+
+      run_agent(arg)
     end
 
     private
 
-    def run_agent(name)
-      # The prompt must exist before the loop starts: an unknown agent fails
-      # fast (exit 1) instead of spinning in the loop.
-      PromptStore.new(root: @root).read(name)
-
-      if tui?
-        run_agent_tui(name)
-      else
-        run_agent_plain(name)
-      end
-    rescue UnknownAgentError => e
-      @stderr.puts(e.message)
-      print_agents
+    def version_flag?(arg)
+      ['--version', '-v'].include?(arg)
+    end
+
+    def help_flag?(arg)
+      ['--help', '-h'].include?(arg)
+    end
+
+    def print_version
+      @stdout.puts(VERSION)
+      0
+    end
+
+    def print_help
+      print_usage(@stdout)
+      0
+    end
+
+    def usage_error
+      print_usage(@stderr)
+      1
+    end
+
+    def unknown_option(arg)
+      @stderr.puts("letsdo: unknown option: #{arg}")
+      print_usage(@stderr)
       1
     end
 
-    # The non-interactive path: the plain line-stream output, byte-identical
-    # to the pre-TUI behavior (pipes, CI, tests, TERM=dumb).
-    def run_agent_plain(name)
-      streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
-      agent = Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
-                        command: pi_command)
-      handle = assignee_handle(name)
-      provider = BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
-                                  env: ENV.to_h.merge(@env))
-      loop = AgentLoop.new(name: name, handle: handle, agent: agent,
-                           task_provider: -> { provider.call },
-                           wait_seconds: wait_seconds, sleeper: @sleeper, stderr: @stderr)
-      loop.run
-    end
-
-    # The interactive path: full-screen TUI over the same orchestrator loop.
-    # The streamer and the loop's service messages land in one combined log
-    # buffer; the loop driver feeds the header metrics facade; the session
-    # controller renders everything from a background input thread and
-    # restores the terminal on every exit path. The loop itself runs on the
-    # calling thread exactly as in plain mode.
-    def run_agent_tui(name)
-      clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
-      handle = assignee_handle(name)
-      log = Tui::LogBuffer.new
-      metrics = Tui::Metrics.new(name: name, handle: handle, clock: clock,
-                                 on_run_start: ->(_label) { log.divider })
-      terminal = Tui::Terminal.new(stream: @stdout)
-      input = Tui::Input.new(stdin: @stdin)
-      streamer = OutputStreamer.new(log: log)
-      agent = Agent.new(name: name, root: @root, flags: parse_pi_flags, streamer: streamer,
-                        command: pi_command)
-      provider = BacklogTasks.new(handle: handle, command: backlog_command, cwd: @root,
-                                  env: ENV.to_h.merge(@env))
-      loop = AgentLoop.new(name: name, handle: handle, agent: agent,
-                           task_provider: -> { provider.call },
-                           wait_seconds: wait_seconds, sleeper: @sleeper, stderr: log,
-                           metrics: metrics)
-      session = Tui::Session.new(name: name, handle: handle, log: log, metrics: metrics,
-                                 terminal: terminal, input: input,
-                                 refresh: -> { provider.call },
-                                 wait_seconds: wait_seconds, clock: clock)
-      session.run { loop.run }
-    end
-
-    # The TUI is engaged only when stdout and stdin are terminals and TERM
-    # is not dumb; otherwise the plain line-stream output (pipes, CI,
-    # tests) — no escape codes, no TUI.
+    def run_agent(name)
+      store = PromptStore.new(root: @root)
+      announce_default_prompt(name, store) if store.read(name).nil?
+      tui? ? run_agent_tui(name) : run_agent_plain(name)
+    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
 
-    # The agent's assignee handle: AGENT_ASSIGNEE_HANDLE override, otherwise
-    # the one rule — '@' + agent name.
     def assignee_handle(name)
       env_handle = @env['AGENT_ASSIGNEE_HANDLE']
       env_handle && !env_handle.strip.empty? ? env_handle : "@#{name}"
@@ -167,8 +112,6 @@ module Letsdo
       @env.fetch('LETSDO_BACKLOG_COMMAND', 'backlog')
     end
 
-    # The retry interval when no tasks are open: LETSDO_WAIT_SECONDS, then
-    # AGENT_WAIT_SECONDS (bin/agent-loop compatibility), default 10 seconds.
     def wait_seconds
       value = @env['LETSDO_WAIT_SECONDS'].to_s.strip
       value = @env['AGENT_WAIT_SECONDS'].to_s.strip if value.empty?
@@ -193,9 +136,6 @@ module Letsdo
       PromptStore.new(root: @root).list.each { |name| @stdout.puts("  #{name}") }
     end
 
-    # LETSDO_PI_FLAGS → array of flags; empty value = no flags.
-    # For bin/agent compatibility, when LETSDO_PI_FLAGS is absent
-    # AGENT_PI_FLAGS is used.
     def parse_pi_flags
       value = @env['LETSDO_PI_FLAGS'].to_s
       value = @env['AGENT_PI_FLAGS'].to_s if value.strip.empty?

data/lib/letsdo/control.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Agent-control primitives shared by the TUI and the orchestrator loop
+  # (TASK-67 control model): pausing between runs.
+  module Control
+    # A thread-safe pause flag polled by Letsdo::AgentLoop between runs.
+    #
+    # Mid-run suspension is handled by Letsdo::PiRunner#pause (SIGSTOP to
+    # the pi group, kernel-level freeze). Between runs there is no pi to
+    # stop, so the pause lives in this gate: while #paused? is true the
+    # loop must not start a new run, and it waits until #resume.
+    #
+    # The flag is toggled from the TUI input thread ('p' key) and polled
+    # from the loop's main thread (AgentLoop#wrapped_run), so every access
+    # is mutex-guarded.
+    class PauseGate
+      def initialize
+        @mutex = Mutex.new
+        @paused = false
+      end
+
+      # Sets the paused state (a no-op when already paused).
+      def pause
+        @mutex.synchronize { @paused = true }
+      end
+
+      # Clears the paused state (a no-op when not paused).
+      def resume
+        @mutex.synchronize { @paused = false }
+      end
+
+      # @return [Boolean] whether the gate is paused
+      def paused?
+        @mutex.synchronize { @paused }
+      end
+    end
+  end
+end

data/lib/letsdo/default_prompt.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # The built-in default prompt (canonical text from the TASK-41 spike,
+  # comment "BUILT-IN DEFAULT PROMPT").
+  #
+  # Process-only: no role, project, or language specifics; one task per run
+  # (the orchestrator loop supplies one task per agent run — the prompt
+  # never picks multiple). Used as:
+  #   1. the fallback prompt when agents/<name>.md does not exist — every
+  #      agent name is a valid worker, the file is an optimization (custom
+  #      instructions), not a precondition;
+  #   2. the template that `letsdo <name> --init` writes to agents/<name>.md
+  #      (TASK-44) — a single source of truth so an initialized file always
+  #      matches what a fallback run uses.
+  module DefaultPrompt
+    # The canonical default prompt text.
+    TEXT = <<~'PROMPT'
+      # Task agent
+
+      You are an autonomous task agent. You pick up the tasks assigned to you and
+      execute them one at a time following the task-work process below. You do not
+      implement features or designs on your own initiative: your work is defined
+      by the assigned tasks, one task per run.
+
+      ## Main rule: exactly one task per run
+
+      In a single run you pick up and complete exactly one task assigned to you,
+      then stop. The next task is started only in the next run of the orchestrator
+      loop.
+
+      If there are no tasks assigned to you — do not invent work and do not create
+      tasks yourself. End the run with a message that there are no tasks.
+
+      ## Choosing a task
+
+      Take the highest priority task assigned to you in order:
+
+      0. if a task is already in progress
+      1. priority
+      2. order (ordinal), if priorities are equal
+
+      If the chosen task is currently blocked, take the task that blocks it into
+      work, using the same selection algorithm: first the highest priority, then
+      in order.
+
+      ## Task-work process
+
+      Execute the task according to the established protocol:
+
+      1. **Start**: read the task instructions, check its status and Acceptance
+         Criteria, move it to an active status and assign it to yourself.
+      2. **Plan**: study the current state of the system, draft an implementation
+         plan and record it in the task.
+      3. **Work**: do the work in short iterations, checking intermediate results
+         and recording progress in the task as you go.
+      4. **Completion**: verify each Acceptance Criterion with objective evidence,
+         mark the completed items, write a final summary and move the task to the
+         terminal status.
+      5. Commit your changes, including any project bookkeeping affected by the
+         task.
+
+      ## Prohibitions
+
+      - Do not take work that is not assigned to you.
+      - Do not complete several tasks in one run.
+    PROMPT
+  end
+end

data/lib/letsdo/errors.rb

@@ -4,19 +4,9 @@ module Letsdo
   # Base error of the package.
   class Error < StandardError; end
 
-  # An agent with this name was not found in agents/.
-  class UnknownAgentError < Error
-    attr_reader :name
-
-    def initialize(name)
-      @name = name
-      super("Unknown agent: #{name}")
-    end
-  end
-
   # Raised by the signal handler to interrupt whatever the main thread is
   # doing (reading pi output, waiting for tasks, ...) so the loop unwinds
   # cleanly. Not a StandardError — nothing rescues it accidentally.
-  class Stopped < Exception
+  class Stopped < StandardError
   end
-end
+end

data/lib/letsdo/loop.rb

@@ -38,21 +38,37 @@ module Letsdo
     # @return [Integer] number of completed agent runs
     def run
       runs = 0
-      until @stopped
-        tasks = @task_provider.call
-        if tasks.nil? || tasks.empty?
-          @sleeper.call(@wait_seconds)
-          next
-        end
-
-        tasks.each do |task|
-          break if @stopped
-
-          @run_task.call(task)
-          runs += 1
-        end
-      end
+      runs += process_tasks_batch(@task_provider.call) until @stopped
       runs
     end
+
+    private
+
+    # One provider batch: when there are no tasks the loop waits and
+    # retries; otherwise it runs the agent once per task.
+    #
+    # @return [Integer] number of agent runs completed in this batch
+    def process_tasks_batch(tasks)
+      return wait_for_tasks if tasks.nil? || tasks.empty?
+
+      run_batch(tasks)
+    end
+
+    def wait_for_tasks
+      @sleeper.call(@wait_seconds)
+      0
+    end
+
+    # Runs the agent once per task, stopping early if the loop is stopped.
+    def run_batch(tasks)
+      batch_runs = 0
+      tasks.each do |task|
+        break if @stopped
+
+        @run_task.call(task)
+        batch_runs += 1
+      end
+      batch_runs
+    end
   end
-end
+end

data/lib/letsdo/output_streamer/arg_summary.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Letsdo
+  class OutputStreamer
+    # Short one-line representations of tool-call arguments.
+    class ArgSummary
+      MAX_ARGS_CHARS = OutputStreamer::MAX_ARGS_CHARS
+
+      def self.call(name, args)
+        new(name, args).to_s
+      end
+
+      def initialize(name, args)
+        @name = name
+        @args = args
+      end
+
+      def to_s
+        case @name
+        when 'bash', 'powershell' then one_line(value('command'))
+        when 'read' then read_summary
+        when 'write', 'edit', 'find', 'ls' then value('path') || value('file_path')
+        when 'grep' then grep_summary
+        else generic
+        end
+      end
+
+      def read_summary
+        path = value('path') || value('file_path')
+        path && "#{path}#{read_range}"
+      end
+
+      def grep_summary
+        pattern = one_line(value('pattern'))
+        return nil unless pattern
+
+        path = value('path') || value('file_path')
+        path ? "#{pattern} #{path}" : pattern
+      end
+
+      def generic
+        return nil if @args.nil? || (@args.is_a?(Hash) && @args.empty?)
+
+        one_line(generic_text)
+      end
+
+      def generic_text
+        case @args
+        when String then @args
+        when Hash then JSON.generate(@args)
+        else @args.to_s
+        end
+      end
+
+      def read_range
+        return nil unless @args.is_a?(Hash)
+
+        offset = @args['offset']
+        return nil unless offset
+
+        limit = @args['limit']
+        limit ? ":#{offset}-#{offset + limit - 1}" : ":#{offset}"
+      end
+
+      def value(key)
+        @args.is_a?(Hash) ? @args[key]&.to_s : nil
+      end
+
+      def one_line(raw, max: MAX_ARGS_CHARS)
+        return nil if raw.nil?
+
+        text = raw.to_s.gsub(/\s+/, ' ').strip
+        return nil if text.empty?
+
+        text.length > max ? "#{text.slice(0, max)}…" : text
+      end
+    end
+  end
+end