letsdo 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a847d927396a19813b8b643486bddabe1f9264f9ba38c6618110e24cc67b55d
-  data.tar.gz: 6d8ad205231a4e833694d7471efffe40dfd8a1f5bea89c45fdf1babb099fbdfa
+  metadata.gz: 9576e7f61d65dbf1379b3e4fcce4831f3162432b9039dc2153f7952201420091
+  data.tar.gz: 679c98fd2628270bb62cf2f35c6a9d13653dd75a3ebe48aa83abc77c3aeccd97
 SHA512:
-  metadata.gz: 39ba23f90a1c8c4add2bce03e9443071a7cb57dd0458c64e7be96ec0c803ff098cea7fbd0d4a9d37eb94050aa470e142f7820643d6738be759176424e2387b98
-  data.tar.gz: 6bc4f0e7f03e01963bfb44d305e0ca76082727643a061eb042a58f71f49fce415a4616a4e6374c7461575ec28458f66c51fa864abc81048751367cf2ba4549a8
+  metadata.gz: 8a6744c21cd6681ac8fde456977962f8a1c8a79cfd8e8157091b0d3ba42848d29f982dd622880e7b7c03f82ec065d014d56da1b61a2f9cd954f3693fc2218f21
+  data.tar.gz: 2925952a1d86f40fc54d1e20e57c83cec89e0f07579c2a0336e2cc370b94c462516c9686c981aedc4b456120ec42fcd51859386685be342c8999ca5bcc3d53d7

data/README.md

@@ -70,9 +70,9 @@ generation, any repeatable task flow you can express as assignee + prompt.
   and stops instantly on `Ctrl+C`.
 - **Streaming output** — agent text streams to stdout as it is generated;
   service and tool lines go to stderr with a shared `HH:MM:SS` prefix:
-  tool start (`⚙ name: args`), completion with duration
-  (`✓/✖ name: … (3s)`), indented results (trimmed with a summary note
-  when large), and error results marked (`✖ Error: ...`).
+  tool start (`⚙ name: args`) and completion with duration
+  (`✓/✖ name: done/error (3s)`). Tool result bodies are not printed, so
+  the stream stays readable while the agent works.
 - **`--version` / `--help`** — `Letsdo::VERSION` and usage, exit 0.
 - **Available as a library** — `require "letsdo"` exposes the
   `Letsdo` module (`Letsdo::VERSION`, `Letsdo::PromptStore`, `Letsdo::Agent`,
@@ -99,7 +99,7 @@ The gem is built from the repository:
 git clone git@github.com:sergio-fry/letsdo.git
 cd letsdo
 gem build letsdo.gemspec
-gem install letsdo-0.1.0.gem
+gem install letsdo-0.2.0.gem
 ```
 
 or run it straight from the checkout without installing:

data/bin/letsdo

@@ -4,18 +4,26 @@
 #
 # letsdo — a local agent worker for Backlog.md/markdown tasks.
 #
-# A thin wrapper over Letsdo::CLI: runs an agent by name (prompt from
-# agents/<name>.md in the project root) as an orchestrator loop — all open
-# tasks assigned to the agent are done one after another (one agent run =
-# one task), then the loop waits for new ones until stopped with
-# SIGINT/SIGTERM (clean exit, code 0).
+# A thin wrapper over Letsdo::CLI: runs an agent by name as an orchestrator
+# loop — all open tasks assigned to the agent are done one after another
+# (one agent run = one task), then the loop waits for new ones until stopped
+# with SIGINT/SIGTERM (clean exit, code 0). The agent's prompt comes from
+# agents/<name>.md in the project root; when that file is missing the agent
+# still starts on the built-in default prompt (Letsdo::DefaultPrompt) and a
+# one-time notification is printed on stderr naming the looked-up path and
+# the 'letsdo <name> --init' hint. --init creates agents/<name>.md with the
+# starter default prompt (letsdo itself never runs the agent in that case,
+# so the prompt can be customized before the first run).
 #
 # Usage:
-#   ./bin/letsdo <name>    # run the <name> agent in the loop (exit 0 on stop)
-#   ./bin/letsdo --version # version, exit 0
-#   ./bin/letsdo --help    # help, exit 0
-#   ./bin/letsdo           # usage and agent list, exit 1
-#   ./bin/letsdo --badopt  # "unknown option" + usage, exit 1
+#   ./bin/letsdo <name>       # run the <name> agent in the loop (exit 0 on stop)
+#   ./bin/letsdo <name> --init # create agents/<name>.md with the starter
+#                               #   default prompt, never run the agent (exit 0)
+#   ./bin/letsdo --init <name>  # same, flag-first form
+#   ./bin/letsdo --version    # version, exit 0
+#   ./bin/letsdo --help       # help, exit 0
+#   ./bin/letsdo              # usage and agent list, exit 1
+#   ./bin/letsdo --badopt     # "unknown option" + usage, exit 1
 #
 # Environment:
 #   LETSDO_ROOT             project root with agents/ (default — current folder)
@@ -28,6 +36,6 @@
 # A new agent = a new agents/<name>.md file, no code changes needed.
 #
 
-require_relative "../lib/letsdo"
+require_relative '../lib/letsdo'
 
-exit Letsdo::CLI.run(ARGV)
+exit Letsdo::CLI.run(ARGV)

data/lib/letsdo/agent.rb

@@ -2,7 +2,10 @@
 
 module Letsdo
   # A single agent run: reads the prompt from agents/<name>.md by agent name
-  # and runs pi with that prompt. Returns the pi exit code.
+  # (falling back to the built-in default prompt when the file is missing)
+  # and runs pi with that prompt. Returns the pi exit code. There are no
+  # unknown agents — every name runs, with the file prompt when present and
+  # with Letsdo::DefaultPrompt::TEXT otherwise.
   #
   # This is the logic of one bin/agent run: a prompt store + an output
   # streamer + a pi runner. The orchestrator (a loop while tasks exist)
@@ -29,9 +32,8 @@ module Letsdo
     # Runs the agent once.
     #
     # @return [Integer] pi exit code
-    # @raise [UnknownAgentError] if the agent is not in agents/
     def run
-      prompt = prompt_store.read(@name)
+      prompt = prompt_store.read(@name) || Letsdo::DefaultPrompt::TEXT
       @runner = PiRunner.new(prompt: prompt, flags: @flags, streamer: @streamer, command: @command)
       @runner.run
     end
@@ -42,4 +44,4 @@ module Letsdo
       @prompt_store ||= PromptStore.new(root: @root)
     end
   end
-end
+end

data/lib/letsdo/agent_loop/tasks.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Provider reporting and per-task run wrapping for AgentLoop.
+  module AgentLoopTasks
+    private
+
+    def wrapped_provider
+      lambda do
+        tasks = @task_provider.call
+        @metrics&.provider_result(tasks&.length)
+        report_provider(tasks)
+        tasks
+      end
+    end
+
+    def report_provider(tasks)
+      if tasks.nil?
+        debug('provider: backlog unavailable')
+        @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
+      elsif tasks.empty?
+        debug('provider: no open tasks')
+        @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
+      else
+        debug("provider: #{tasks.length} open task(s)")
+        @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
+      end
+    end
+
+    def wrapped_run
+      lambda do |task|
+        wait_while_paused
+        run_one_task(task)
+      end
+    end
+
+    def run_one_task(task)
+      label = task_label(task)
+      @metrics&.run_started(label)
+      @stderr.puts("letsdo: running #{@name} for #{label}")
+      debug("running agent for task #{label}")
+      code = @run_one.call(task)
+      debug("agent run exit #{code}")
+      @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
+    ensure
+      @metrics&.run_finished
+    end
+
+    def task_label(task)
+      id = task.respond_to?(:[]) ? task['id'] : nil
+      return id.to_s unless id.nil? || id.to_s.empty?
+
+      task.to_s
+    end
+
+    def wait_while_paused
+      return unless @pause_gate
+
+      @sleeper.call(AgentLoop::PAUSE_POLL_SECONDS) while @pause_gate.paused?
+    end
+  end
+end

data/lib/letsdo/agent_loop.rb

@@ -1,81 +1,29 @@
 # frozen_string_literal: true
 
+require_relative 'agent_loop/tasks'
+
 module Letsdo
-  # The orchestrator loop wired to the real environment for `letsdo <name>`:
-  #
-  #   Letsdo::Loop        — while the provider gives open tasks, runs the
-  #                         agent (one run = one task); no tasks (or the
-  #                         backlog is unreadable) — waits and checks again;
-  #   task provider       — open tasks assigned to the agent's handle
-  #                         (Letsdo::BacklogTasks by default);
-  #   agent run           — one Letsdo::Agent run per open task;
-  #   signals             — SIGINT/SIGTERM stop the loop: a running pi child
-  #                         is terminated and the process exits with 0.
-  #
-  # Waiting is interruptible: stop signals are delivered as
-  # Letsdo::Stopped raised from the trap, so the loop unwinds right away
-  # instead of waiting out the retry interval (see #on_signal).
-  #
-  # Service output goes to stderr: started, running <name> for <task>, no
-  # open tasks / backlog unavailable with the retry interval, non-zero agent
-  # exit codes, stopped.
+  # The orchestrator loop wired to the real environment for `letsdo <name>`.
   class AgentLoop
+    include AgentLoopTasks
+
     STOP = :letsdo_stop
+    PAUSE_POLL_SECONDS = 0.05
 
-    # @param name [String] agent name (for messages)
-    # @param handle [String] assignee handle of the agent (e.g. "@developer")
-    # @param agent [Letsdo::Agent, nil] agent to run once per task (its
-    #        current runner is terminated on stop); ignored when run_one is
-    #        given
-    # @param run_one [Proc, nil] callable(task) → agent exit code; by default
-    #        the injected agent's #run
-    # @param task_provider [Proc] callable → Array of open tasks (empty = no
-    #        tasks) or nil (backlog unreadable — pause)
-    # @param wait_seconds [Float] retry interval when there are no tasks
-    # @param sleeper [Proc, nil] callable(Float) → waiting; injectable for
-    #        deterministic stops in tests (throw Letsdo::AgentLoop::STOP)
-    # @param stderr [IO] service output stream
-    # @param metrics [Object, nil] optional header-metrics facade
-    #        (Letsdo::Tui::Metrics in TUI mode): receives provider_result
-    #        on every provider call and run_started/run_finished around
-    #        each agent run; nil in plain mode, so plain behavior is
-    #        byte-identical
-    # @param debug [Boolean, nil] trace [letsdo] lines to stderr; nil = LETSDO_DEBUG
-    def initialize(name:, handle:, agent: nil, run_one: nil, task_provider:,
-                   wait_seconds: 10.0, sleeper: nil, stderr: $stderr, metrics: nil, debug: nil)
+    def initialize(name:, handle:, task_provider:, **opts)
       @name = name
       @handle = handle
-      @agent = agent
-      @run_one = run_one || ->(_task) { @agent.run }
       @task_provider = task_provider
-      @wait_seconds = wait_seconds
-      @stderr = stderr
-      @metrics = metrics
-      @debug = debug.nil? ? ENV["LETSDO_DEBUG"] == "1" : debug
-      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      assign_opts(opts)
     end
 
-    # Runs the loop until stopped (SIGINT/SIGTERM).
-    # Runs the loop until stopped (SIGINT/SIGTERM).
-    #
-    # Stopping is done by raising Letsdo::Stopped from the signal handler:
-    # the raise interrupts whatever the main thread is doing (reading pi
-    # output, waiting for new tasks, running the backlog CLI) and unwinds
-    # the loop. The handler itself only sends SIGTERM to a running pi group
-    # (no waits or IO — safe from a trap) and raises.
-    #
-    # @return [Integer] exit code — always 0 when stopped cleanly
     def run
       @loop = build_loop
       install_signal_handlers
       debug("loop start (agent=#{@name}, handle=#{@handle}, wait=#{@wait_seconds}s)")
-      begin
-        catch(STOP) { @loop.run }
-      rescue Letsdo::Stopped
-        debug("stopped by signal")
-      end
-      debug("loop stopped")
-      @stderr.puts("letsdo: stopped")
+      run_until_stopped
+      debug('loop stopped')
+      @stderr.puts('letsdo: stopped')
       0
     ensure
       restore_signal_handlers
@@ -85,86 +33,53 @@ module Letsdo
       warn("[letsdo] loop: #{message}") if @debug
     end
 
-    # Signal handler: sends SIGTERM to a running pi group and raises
-    # Letsdo::Stopped to interrupt the main thread. Nothing else — no IO,
-    # no sleeps (a trap writing to a busy stream deadlocks; the pi is
-    # reaped by Letsdo::PiRunner#run after the unwind).
     def on_signal(_signum)
-      runner = @agent&.runner
-      runner&.terminate_now
+      @agent&.runner&.terminate_now
       raise Letsdo::Stopped
     end
 
     private
 
-    def build_loop
-      @loop = Letsdo::Loop.new(
-        task_provider: wrapped_provider,
-        run_task: wrapped_run,
-        wait_seconds: @wait_seconds,
-        sleeper: @sleeper
-      )
+    def assign_opts(opts)
+      @agent = opts[:agent]
+      @run_one = opts[:run_one] || ->(_task) { @agent.run }
+      @wait_seconds = opts.fetch(:wait_seconds, 10.0)
+      @stderr = opts.fetch(:stderr, $stderr)
+      assign_control_opts(opts)
     end
 
-    # Messages on stderr: open task count before the batch and the wait
-    # reason (no tasks vs unreadable backlog) before every wait.
-    def wrapped_provider
-      lambda do
-        tasks = @task_provider.call
-        @metrics&.provider_result(tasks.nil? ? nil : tasks.length)
-        if tasks.nil?
-          debug("provider: backlog unavailable")
-          @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
-        elsif tasks.empty?
-          debug("provider: no open tasks")
-          @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
-        else
-          debug("provider: #{tasks.length} open task(s)")
-          @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
-        end
-        tasks
-      end
+    def assign_control_opts(opts)
+      @metrics = opts[:metrics]
+      @pause_gate = opts[:pause_gate]
+      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @sleeper = opts[:sleeper] || ->(seconds) { sleep(seconds) }
     end
 
-    # One agent run per task; a non-zero exit code is noted but the loop
-    # continues. Metrics events bracket the run so the TUI can count done
-    # tasks and show the running one with its elapsed time.
-    def wrapped_run
-      lambda do |task|
-        @metrics&.run_started(task_label(task))
-        @stderr.puts("letsdo: running #{@name} for #{task_label(task)}")
-        debug("running agent for task #{task_label(task)}")
-        code = @run_one.call(task)
-        debug("agent run exit #{code}")
-        @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
-      ensure
-        @metrics&.run_finished
-      end
+    def run_until_stopped
+      catch(STOP) { @loop.run }
+    rescue Letsdo::Stopped
+      debug('stopped by signal')
     end
 
-    # A human-readable label of a task for messages: the id field when
-    # present, the object as-is otherwise.
-    def task_label(task)
-      id = task.respond_to?(:[]) ? task["id"] : nil
-      return id.to_s unless id.nil? || id.to_s.empty?
-
-      task.to_s
-    end
-
-    # The default waiting blocks only for the retry interval: a stop signal
-    # interrupts it as Letsdo::Stopped raised from the trap.
-    def interruptible_sleeper
-      ->(seconds) { sleep(seconds) }
+    def build_loop
+      Letsdo::Loop.new(
+        task_provider: wrapped_provider,
+        run_task: wrapped_run,
+        wait_seconds: @wait_seconds,
+        sleeper: @sleeper
+      )
     end
 
     def install_signal_handlers
-      Signal.trap("SIGINT", method(:on_signal))
-      Signal.trap("SIGTERM", method(:on_signal))
+      Signal.trap('SIGINT', method(:on_signal))
+      Signal.trap('SIGTERM', method(:on_signal))
+      Signal.trap('SIGHUP', method(:on_signal))
     end
 
     def restore_signal_handlers
-      Signal.trap("SIGINT", "DEFAULT")
-      Signal.trap("SIGTERM", "DEFAULT")
+      Signal.trap('SIGINT', 'DEFAULT')
+      Signal.trap('SIGTERM', 'DEFAULT')
+      Signal.trap('SIGHUP', 'DEFAULT')
     end
   end
-end
+end

data/lib/letsdo/backlog_tasks.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
-require "open3"
-require "shellwords"
+require 'json'
+require 'shellwords'
 
 module Letsdo
   # Task provider for Letsdo::Loop backed by the real backlog CLI:
@@ -23,7 +22,7 @@ module Letsdo
     # @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)
+    def initialize(handle:, command: 'backlog', cwd: nil, env: nil)
       @handle = handle
       @command = command
       @cwd = cwd
@@ -35,10 +34,10 @@ module Letsdo
     # @return [Array<Hash>, nil] open tasks; nil when the backlog is unreadable
     def call
       args = @env ? [@env, *command_line] : command_line
-      out, _err, status = Open3.capture3(*args, chdir: @cwd)
+      out, _err, status = Letsdo::Capture.new(*args, chdir: @cwd).run
       return nil unless status.success?
 
-      tasks = JSON.parse(out)["tasks"]
+      tasks = JSON.parse(out)['tasks']
       tasks.is_a?(Array) ? tasks : nil
     rescue Errno::ENOENT, JSON::ParserError, TypeError
       nil
@@ -50,11 +49,11 @@ module Letsdo
     def command_line
       [
         *Shellwords.split(@command),
-        "task", "list",
-        "--assignee", @handle,
-        "--exclude-status", "Done",
-        "--json"
+        'task', 'list',
+        '--assignee', @handle,
+        '--exclude-status', 'Done',
+        '--json'
       ]
     end
   end
-end
+end

data/lib/letsdo/capture.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Captures a child command's stdout and stderr (like Open3.capture3)
+  # while tolerating an asynchronous Letsdo::Stopped that lands mid-call —
+  # a TUI quit or a signal raised into the main thread. Open3's capture3
+  # is not interruption-safe: its ensure closes the pipes while its reader
+  # threads are still blocked in IO#read, and each reader then dies with
+  # "stream closed in another thread" and prints a report_on_exception dump.
+  #
+  # Here the reader threads report no exception and rescue that benign
+  # IOError, and the child is reaped even when the wait is interrupted, so
+  # a stop can never leave dumps or zombies. Other reader errors still
+  # re-raise through Thread#value, keeping real failures visible.
+  class Capture
+    # @param args [Array] command arguments for Process.spawn (an optional
+    #        leading environment hash is preserved)
+    # @param chdir [String, nil] working directory for the child (nil =
+    #        inherit the current one)
+    def initialize(*args, chdir: nil)
+      @args = args
+      @chdir = chdir
+      @out_r, @out_w = IO.pipe
+      @err_r, @err_w = IO.pipe
+    end
+
+    # Runs the command.
+    #
+    # @return [Array(String, String, Process::Status)] stdout, stderr, status
+    def run
+      @pid = spawn_child
+      @out_w.close
+      @err_w.close
+      readers = [quiet_reader(@out_r), quiet_reader(@err_r)]
+      status = wait_and_reap(@pid)
+      [readers[0].value, readers[1].value, status]
+    ensure
+      cleanup
+    end
+
+    private
+
+    def spawn_child
+      opts = { out: @out_w, err: @err_w }
+      opts[:chdir] = @chdir if @chdir
+      Process.spawn(*@args, **opts)
+    end
+
+    # A stdout/stderr reader thread that stays silent when its pipe is
+    # closed while still reading (the stop path) and returns nil instead.
+    def quiet_reader(pipe)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        pipe.read
+      rescue IOError
+        nil
+      end
+    end
+
+    def wait_and_reap(pid)
+      _, status = Process.wait2(pid)
+      status
+    end
+
+    # Reaps pid if the normal wait never ran (the wait was interrupted by a
+    # stop); a no-op when the child was already reaped.
+    def reattach_reaper(pid)
+      return unless pid
+
+      Process.detach(pid)
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def cleanup
+      close_quietly(@out_w)
+      close_quietly(@err_w)
+      close_quietly(@out_r)
+      close_quietly(@err_r)
+      reattach_reaper(@pid)
+    end
+
+    def close_quietly(io)
+      io.close unless io.nil? || io.closed?
+    rescue IOError
+      nil
+    end
+  end
+end

data/lib/letsdo/cli/init.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # The --init scaffold command (TASK-44): `letsdo <name> --init` and
+  # `letsdo --init <name>` create agents/<name>.md with the starter default
+  # prompt (Letsdo::DefaultPrompt::TEXT) so the agent can be customized
+  # later. The agent itself is never started. PromptStore#create_agent
+  # already guarantees no overwrite and nothing outside agents/ — this
+  # module only maps the results to messages and exit codes.
+  module CLIInit
+    private
+
+    # Creates agents/<name>.md. Success prints "created <path>" (stdout),
+    # exit 0; an unsafe name or an already existing file prints the error
+    # on stderr, exit 1; a missing name falls back to usage, exit 1.
+    def init_command(argv)
+      name = argv[0] == '--init' ? argv[1] : argv[0]
+      return usage_error if name.nil?
+      return init_error("invalid agent name: #{name}") if PromptStore.unsafe_name?(name)
+
+      store = PromptStore.new(root: @root)
+      return init_error("agents/#{name}.md already exists") unless store.create_agent(name, Letsdo::DefaultPrompt::TEXT)
+
+      @stdout.puts("created #{store.agent_path(name)}")
+      0
+    end
+
+    def init_error(message)
+      @stderr.puts("letsdo: #{message}")
+      1
+    end
+  end
+end

data/lib/letsdo/cli/launch.rb

@@ -0,0 +1,82 @@
+# 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])
+    end
+  end
+end