letsdo 0.3.0 → 0.5.0

data/lib/letsdo/metrics/fanout.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Metrics
+    # A small fan-out facade that forwards the loop-driver events to a
+    # list of observers.  Used in TUI mode so the session recorder and
+    # the header metrics facade both receive the same callbacks from
+    # Letsdo::AgentLoop.
+    #
+    # Each observer must respond to provider_result, run_started and
+    # run_finished (the same interface Tui::Metrics and SessionRecorder
+    # implement).  The exit code is forwarded to every observer so the
+    # session recorder can classify outcomes; Tui::Metrics ignores it.
+    class Fanout
+      # @param observers [Array<Object>] each must implement the three
+      #        callback methods (provider_result, run_started, run_finished)
+      def initialize(*observers)
+        @observers = observers
+      end
+
+      # Forwards the provider open-task count to every observer.
+      #
+      # @param count [Integer, nil] number of open tasks; nil = the
+      #        backlog state is unreadable
+      # @return [void]
+      def provider_result(count)
+        @observers.each { |observer| observer.provider_result(count) }
+      end
+
+      # Forwards a run-started event (task label) to every observer.
+      #
+      # @param task [String] task label
+      # @return [void]
+      def run_started(task)
+        @observers.each { |observer| observer.run_started(task) }
+      end
+
+      # Forwards a run-finished event (exit code) to every observer.
+      #
+      # @param exit_code [Integer, nil] the run exit code
+      # @return [void]
+      def run_finished(exit_code = nil)
+        @observers.each { |observer| observer.run_finished(exit_code) }
+      end
+    end
+  end
+end

data/lib/letsdo/prompt_store.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'yaml'
 
 module Letsdo
   # Access to agent prompts: the agents/<name>.md directory in the project
@@ -40,7 +41,22 @@ module Letsdo
       path = agent_path(name)
       return nil unless File.file?(path)
 
-      File.read(path)
+      content = File.read(path)
+      self.class.strip_front_matter(content)
+    end
+
+    # Parsed launch configuration for an agent.
+    #
+    # Returns a hash with symbolised keys. An empty hash when the file
+    # is missing or has no YAML front matter.
+    #
+    # @param name [String] agent name
+    # @return [Hash{Symbol => Object}]
+    def config(name)
+      path = agent_path(name)
+      return {} unless File.file?(path)
+
+      self.class.parse_front_matter(File.read(path))
     end
 
     # Absolute path of an agent's prompt file, whether or not it exists.
@@ -69,6 +85,37 @@ module Letsdo
       true
     end
 
+    # Strips an optional YAML front matter block delimited by `---` at
+    # the very start of a prompt file. Returns the remaining content.
+    #
+    # @param content [String] full file content
+    # @return [String] content without front matter
+    def self.strip_front_matter(content)
+      content.sub(/\A---\n.+?\n---\n?/m, '')
+    end
+
+    FRONT_MATTER = /\A---\n?\n(.+?)\n?\n---\n?\n/m
+
+    # Parses an optional YAML front matter block delimited by `---` at
+    # the very start of a prompt file. Returns the keys symbolised;
+    # returns an empty hash when there is no front matter or it is
+    # invalid.
+    #
+    # @param content [String] full file content
+    # @return [Hash{Symbol => Object}]
+    def self.parse_front_matter(content)
+      match = content.match(FRONT_MATTER)
+      return {} unless match
+
+      symbolize_keys(YAML.safe_load(match[1], permitted_classes: []))
+    rescue StandardError
+      {}
+    end
+
+    def self.symbolize_keys(parsed)
+      parsed.is_a?(Hash) ? parsed.transform_keys(&:to_sym) : {}
+    end
+
     private
 
     def agents_dir

data/lib/letsdo/providers/backlog.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'shellwords'
+require_relative 'task'
+
+module Letsdo
+  module Providers
+    # Task provider for Letsdo::Loop backed by the real backlog CLI:
+    #
+    #   backlog task list --assignee <handle> --exclude-status Done \
+    #     --ready --sort priority --json
+    #
+    # Returns the runnable tasks assigned to the handle in the
+    # authoritative run order (an Array of Letsdo::Providers::Task), 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 Backlog
+      # Keys of the normalized Letsdo::Providers::Task shape. The backlog CLI
+      # emits more (reporter, parentTaskId, createdAt, updatedAt); the adapter
+      # projects onto these and ignores the rest so a growing CLI schema
+      # cannot crash the loop. Beyond the identity fields, the shape keeps
+      # what deterministic selection needs: ordinal (the stable tie-break) and
+      # type/labels/milestone (optional capability routing).
+      TASK_FIELDS = %w[id title status priority assignees ordinal type labels milestone].freeze
+
+      # Sort ranks for the deterministic batch order. Known priorities are
+      # compared case-insensitively; anything else (nil or a new label) ranks
+      # last instead of crashing the comparator.
+      PRIORITY_RANKS = { 'high' => 0, 'medium' => 1, 'low' => 2 }.freeze
+      UNKNOWN_RANK = PRIORITY_RANKS.size
+
+      # @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 runnable open tasks once, in deterministic run order.
+      #
+      # @return [Array<Task>, nil] runnable open tasks; nil when the backlog is
+      #         unreadable; empty array when there are no open tasks
+      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) ? sort(tasks.map { |raw| normalize(raw) }) : nil
+      rescue Errno::ENOENT, JSON::ParserError, TypeError
+        nil
+      end
+
+      private
+
+      # Deterministic run order: In Progress first (resume before starting),
+      # then priority High > Medium > Low, then ordinal ascending, then id
+      # ascending. The CLI's --sort priority does not put In Progress first
+      # and cannot express the full tie-break, so the adapter sorts the batch
+      # itself. The original index is the final tie-break, so equal keys keep
+      # the provider's (deterministic) order.
+      def sort(tasks)
+        tasks.each_with_index.sort_by do |task, index|
+          [in_progress_rank(task), priority_rank(task.priority),
+           ordinal_rank(task.ordinal), id_rank(task.id), index]
+        end.map(&:first)
+      end
+
+      def in_progress_rank(task)
+        task.status.to_s.casecmp('In Progress').zero? ? 0 : 1
+      end
+
+      def priority_rank(priority)
+        PRIORITY_RANKS[priority.to_s.downcase] || UNKNOWN_RANK
+      end
+
+      # Unknown/nil ordinals sort last (their id still orders them).
+      def ordinal_rank(ordinal)
+        value = Integer(ordinal, exception: false)
+        value.nil? ? [1, 0] : [0, value]
+      end
+
+      # An absent id (malformed task) sorts after identified ones.
+      def id_rank(id)
+        [id.to_s.empty? ? 1 : 0, id.to_s]
+      end
+
+      # Projects one raw CLI task onto the normalized shape. Unknown keys are
+      # ignored (the CLI schema grows over time); a non-Hash entry means the
+      # payload is not the expected schema and raises TypeError, which #call
+      # turns into nil.
+      def normalize(raw)
+        raise TypeError, "task is not an object: #{raw.class}" unless raw.is_a?(Hash)
+
+        Task.new(**TASK_FIELDS.to_h { |field| [field.to_sym, raw[field]] })
+      end
+
+      # [command..., task, list, --assignee <handle>, --exclude-status Done,
+      #  --ready, --sort priority, --json]
+      def command_line
+        [
+          *Shellwords.split(@command),
+          'task', 'list',
+          '--assignee', @handle,
+          '--exclude-status', 'Done',
+          '--ready',
+          '--sort', 'priority',
+          '--json'
+        ]
+      end
+    end
+  end
+end

data/lib/letsdo/providers/task.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Providers
+    # Immutable value object representing a normalized task.
+    #
+    # Adapters map tracker-specific JSON onto this shape. Business logic
+    # consumes only this interface, not the raw tracker schema.
+    #
+    # The constructor is strict on purpose: adapters project the tracker
+    # payload onto these keywords instead of forwarding it, so extra tracker
+    # fields never reach here and a wrong key is caught as a programming
+    # error instead of silently ignored.
+    #
+    # Besides the identity/routing fields, the shape carries the fields a
+    # deterministic selector needs: +ordinal+ (the stable tie-break), and
+    # +type+/+labels+/+milestone+ for optional capability routing.
+    class Task
+      attr_reader :id, :title, :status, :priority, :assignees,
+                  :ordinal, :type, :labels, :milestone
+
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the
+      # normalized shape's explicit contract; adapters project tracker
+      # payloads onto exactly these and the strict list rejects a typo.
+      def initialize(id:, title: nil, status: nil, priority: nil, assignees: [],
+                     ordinal: nil, type: nil, labels: [], milestone: nil)
+        @id = id
+        @title = title
+        @status = status
+        @priority = priority
+        @assignees = Array(assignees)
+        @ordinal = ordinal
+        @type = type
+        @labels = Array(labels)
+        @milestone = milestone
+        freeze
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def to_s
+        identifier = id.to_s
+        return identifier unless identifier.empty?
+
+        title.to_s
+      end
+    end
+  end
+end

data/lib/letsdo/retry_policy.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Pure policy object for per-task retry, exponential backoff and give-up.
+  #
+  # Letsdo::Loop stays generic and untouched; this object is wired at the
+  # AgentLoop level. The loop filters attempt batches through #cooldown? and
+  # records outcomes with #record_failure / #record_success.
+  #
+  # State is per-task (keyed by task id) and in-memory only: a fresh letsdo
+  # session starts with zero failures, so a broken task yields instead of
+  # hammering, and a temporarily-failing task is retried next session.
+  #
+  # The clock is injectable (monotonic, as in Tui::Metrics) for
+  # deterministic tests.
+  class RetryPolicy
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_CAP = 300.0
+    DEFAULT_BASE = 10.0
+
+    # Tunables exposed for the reconciliation logic (give-up checks).
+    attr_reader :max_retries
+
+    # @param base [Float] base backoff seconds; default wait_seconds (10.0)
+    # @param cap [Float] maximum backoff seconds (default 300)
+    # @param max_retries [Integer] give-up after N consecutive failures
+    # @param clock [Proc] callable → monotonic epoch seconds
+    def initialize(base: nil, cap: nil, max_retries: nil, clock: nil)
+      @base = base || DEFAULT_BASE
+      @cap = cap || DEFAULT_CAP
+      @max_retries = max_retries || DEFAULT_MAX_RETRIES
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @state = {}
+    end
+
+    # Consecutive failures recorded for task_key (0 when none).
+    def failures(task_key)
+      info = @state[task_key]
+      info ? info[:failures] : 0
+    end
+
+    # Records a failed run: bumps the failure count and (re)arms the cooldown
+    # deadline for exponential backoff.
+    def record_failure(task_key)
+      info = (@state[task_key] ||= { failures: 0, cool_until: 0 })
+      info[:failures] += 1
+      info[:cool_until] = cooldown_deadline(info[:failures])
+      info
+    end
+
+    # Records a successful run: clears the per-task retry state.
+    def record_success(task_key)
+      @state.delete(task_key)
+    end
+
+    # Clears all per-task retry state (fresh session).
+    def reset
+      @state.clear
+    end
+
+    # Whether the task is cooling down and must be excluded from attempt
+    # batches. Tasks skipped by cooldown are NOT re-recorded as failed.
+    def cooldown?(task_key, now = nil)
+      info = @state[task_key]
+      return false unless info
+
+      cool_until(info) > current_time(now)
+    end
+
+    # Whether the task has hit the give-up limit: it must not be attempted
+    # again for the rest of the session.
+    def gave_up?(task_key)
+      failures(task_key) >= @max_retries
+    end
+
+    # Earliest cooldown deadline across all tasks (for a bounded wait); nil
+    # when nothing is cooling down.
+    def earliest_cooldown(now = nil)
+      current = current_time(now)
+      deadlines = @state.values.map { |info| info[:cool_until] }.select { |d| d > current }
+      deadlines.empty? ? nil : deadlines.min
+    end
+
+    private
+
+    def current_time(now)
+      now.nil? ? @clock.call : now
+    end
+
+    def cooldown_deadline(failure_count)
+      @clock.call + [@base * (2**(failure_count - 1)), @cap].min
+    end
+
+    def cool_until(info)
+      info[:cool_until]
+    end
+  end
+end

data/lib/letsdo/session_recorder/jsonl_writer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Letsdo
+  class SessionRecorder
+    # Writes the optional JSON Lines metrics stream for a session recorder:
+    # a session_start line on construction, one run_finished line per closed
+    # run and a session_stop line at the end. With a nil IO the writer is a
+    # no-op, so callers need no nil checks.
+    class JsonlWriter
+      # @param io [IO, nil] append-only target; nil disables the writer
+      # @param name [String] agent name
+      # @param handle [String] assignee handle
+      # @param wall_clock [Proc] -> ISO8601 UTC timestamp string
+      def initialize(io, name:, handle:, wall_clock:)
+        @io = io
+        @name = name
+        @handle = handle
+        @wall_clock = wall_clock
+        session_start if enabled?
+      end
+
+      # @return [Boolean] whether an output target is configured
+      def enabled?
+        !@io.nil?
+      end
+
+      # Writes the opening session_start line (no-op when disabled).
+      #
+      # @return [void]
+      def session_start
+        write(session_start_payload)
+      end
+
+      # @param run [SessionRecorder::Run] a closed run record
+      # @return [void]
+      def run_finished(run)
+        write(
+          'event' => 'run_finished', 'task' => run.task_id, 'exit' => run.exit_code,
+          'outcome' => run.outcome.to_s, 'elapsed_s' => run.elapsed_s,
+          'ts' => @wall_clock.call
+        )
+      end
+
+      # @param summary [SessionRecorder::Summary] the final aggregate
+      # @return [void]
+      def session_stop(summary)
+        write(
+          'event' => 'session_stop', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call, 'done' => summary.done, 'failed' => summary.failed,
+          'interrupted' => summary.interrupted, 'left' => summary.left,
+          'session_s' => summary.session_s, 'runs_s' => summary.active_s
+        )
+      end
+
+      private
+
+      def session_start_payload
+        { 'event' => 'session_start', 'agent' => @name, 'handle' => @handle,
+          'ts' => @wall_clock.call }
+      end
+
+      def write(payload)
+        return unless enabled?
+
+        @io.puts(JSON.generate(payload))
+        @io.flush if @io.respond_to?(:flush)
+      end
+    end
+  end
+end

data/lib/letsdo/session_recorder.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative 'duration'
+require_relative 'session_recorder/jsonl_writer'
+
+module Letsdo
+  # A mode-independent session metrics recorder. It receives the same
+  # loop-driver events as the TUI metrics facade, records per-run outcomes
+  # and durations, and can optionally emit a JSONL event stream.
+  #
+  # The recorder is intentionally free of TUI dependencies so it can be
+  # used in plain mode, TUI mode, or embedded contexts.
+  class SessionRecorder
+    Run = Struct.new(:task_id, :started_mono, :finished_mono, :elapsed_s,
+                     :exit_code, :outcome, keyword_init: true)
+
+    Summary = Struct.new(:done, :failed, :interrupted, :left, :session_s,
+                         :active_s, :waiting_s, :avg_s, :runs,
+                         keyword_init: true)
+
+    MAX_SUMMARY_RUNS = 10
+
+    HEADLINE = 'letsdo: session: %<done>d done, %<failed>d failed, ' \
+               '%<interrupted>d interrupted, %<left>s left open, %<session>s ' \
+               '(%<active>s in runs, %<waiting>s waiting, avg %<avg>s)'
+
+    # Rendering of the human-readable stop summary (TASK-63 C3). Kept nested
+    # so SessionRecorder stays within the class-length limit.
+    module SummaryFormat
+      private
+
+      def headline(summary)
+        left = summary.left.nil? ? 'unknown' : summary.left
+        format(HEADLINE, done: summary.done, failed: summary.failed,
+                         interrupted: summary.interrupted, left: left,
+                         session: format_duration(summary.session_s),
+                         active: format_duration(summary.active_s),
+                         waiting: format_duration(summary.waiting_s),
+                         avg: format_duration(summary.avg_s))
+      end
+
+      def run_lines(summary)
+        lines = summary.runs.first(MAX_SUMMARY_RUNS).map { |run| format_run(run) }
+        return lines unless summary.runs.length > MAX_SUMMARY_RUNS
+
+        lines << "letsdo:   … and #{summary.runs.length - MAX_SUMMARY_RUNS} more"
+      end
+
+      def format_run(run)
+        return "letsdo:   #{run.task_id} interrupted" if run.finished_mono.nil?
+
+        outcome = run.outcome == :done ? 'done' : 'failed'
+        "letsdo:   #{run.task_id} #{outcome} in #{format_duration(run.elapsed_s)}"
+      end
+
+      # Shared with the task-time write-back so summary and task record agree.
+      def format_duration(seconds)
+        Duration.format(seconds)
+      end
+    end
+    include SummaryFormat
+
+    # @param name [String] agent name
+    # @param handle [String] assignee handle
+    # @param clock [Proc] monotonic clock -> seconds; default
+    #        Process.clock_gettime(CLOCK_MONOTONIC)
+    # @param wall_clock [Proc] wall clock -> ISO8601 UTC string; default
+    #        Time.now.utc.iso8601
+    # @param metrics_io [IO, nil] optional append-only JSONL target
+    def initialize(name:, handle:, clock: nil, wall_clock: nil, metrics_io: nil)
+      @name = name
+      @handle = handle
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @wall_clock = wall_clock || -> { Time.now.utc.iso8601 }
+      @writer = JsonlWriter.new(metrics_io, name: name, handle: handle, wall_clock: @wall_clock)
+      @mutex = Mutex.new
+      @runs = []
+      @left = nil
+      @session_started = @clock.call
+      @session_stopped = false
+    end
+
+    # A run started for a task.
+    #
+    # @param task_id [String] task label
+    # @return [void]
+    def run_started(task_id)
+      @mutex.synchronize do
+        @runs << Run.new(task_id: task_id, started_mono: @clock.call)
+      end
+    end
+
+    # A run finished. The last still-open run is closed with the given
+    # exit code. If no run is open, this is a no-op.
+    #
+    # @param exit_code [Integer, nil] the run exit code
+    # @return [void]
+    def run_finished(exit_code = nil)
+      @mutex.synchronize do
+        run = @runs.reverse.find { |candidate| candidate.finished_mono.nil? }
+        return unless run
+
+        close_run(run, exit_code)
+        @writer.run_finished(run)
+      end
+    end
+
+    # The latest open-task count from the backlog provider.
+    #
+    # @param count [Integer, nil] number of open tasks; nil = the backlog
+    #        state is unreadable
+    # @return [void]
+    def provider_result(count)
+      @mutex.synchronize { @left = count }
+    end
+
+    # A point-in-time summary of the session metrics.
+    #
+    # waiting_s is a derived approximation: session time minus the sum of
+    # run durations. It therefore also includes polling, backlog reads and
+    # stop overhead, not only idle waiting for new tasks.
+    #
+    # @return [Summary] aggregate counts and durations
+    def summary
+      @mutex.synchronize { build_summary }
+    end
+
+    # Writes the session_stop JSONL event and returns the summary.
+    # The event is written only once per recorder instance.
+    #
+    # @return [Summary]
+    def session_stop
+      emit = claim_stop_event
+      result = summary
+      @writer.session_stop(result) if emit
+      result
+    end
+
+    # A human-readable summary suitable for stderr.
+    #
+    # @return [String]
+    def summary_line
+      s = summary
+      lines = [headline(s)] + run_lines(s)
+      lines.join("\n")
+    end
+
+    private
+
+    def close_run(run, exit_code)
+      run.finished_mono = @clock.call
+      run.elapsed_s = run.finished_mono - run.started_mono
+      run.exit_code = exit_code
+      run.outcome = exit_code&.zero? ? :done : :failed
+    end
+
+    def build_summary
+      session_s = @clock.call - @session_started
+      active_s = @runs.sum { |run| run.elapsed_s || 0.0 }
+      Summary.new(
+        done: count_outcome(:done), failed: count_outcome(:failed),
+        interrupted: @runs.count { |run| run.finished_mono.nil? }, left: @left,
+        session_s: session_s, active_s: active_s, waiting_s: session_s - active_s,
+        avg_s: average_done_run, runs: @runs.dup
+      )
+    end
+
+    def count_outcome(outcome)
+      @runs.count { |run| run.outcome == outcome }
+    end
+
+    def average_done_run
+      done = @runs.select { |run| run.outcome == :done }
+      return 0.0 if done.empty?
+
+      done.sum { |run| run.elapsed_s || 0.0 } / done.size
+    end
+
+    def claim_stop_event
+      @mutex.synchronize do
+        return false if @session_stopped
+
+        @session_stopped = true
+        @writer.enabled?
+      end
+    end
+  end
+end