ace-hitl 0.8.0

data/lib/ace/hitl/molecules/hitl_creator.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "yaml"
+require "ace/support/items"
+require_relative "../atoms/hitl_file_pattern"
+require_relative "../atoms/hitl_id_formatter"
+require_relative "hitl_loader"
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlCreator
+        def initialize(root_dir:, config: {})
+          @root_dir = root_dir
+          @config = config
+        end
+
+        def create(title,
+          kind: nil,
+          questions: [],
+          tags: [],
+          assignment: nil,
+          step: nil,
+          step_name: nil,
+          resume_instructions: nil,
+          move_to: nil,
+          time: Time.now.utc)
+          raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
+
+          effective_kind = kind || @config.dig("hitl", "default_kind") || "clarification"
+          id = generate_unique_id(time)
+          folder_slug = generate_folder_slug(title)
+          file_slug = generate_file_slug(title)
+
+          target_dir = determine_target_dir(move_to)
+          FileUtils.mkdir_p(target_dir)
+
+          folder_name, _ = unique_folder_name(id, folder_slug, target_dir)
+          item_dir = File.join(target_dir, folder_name)
+          FileUtils.mkdir_p(item_dir)
+
+          frontmatter = {
+            "id" => id,
+            "title" => title,
+            "kind" => effective_kind,
+            "status" => "pending",
+            "tags" => tags,
+            "questions" => questions,
+            "assignment" => assignment,
+            "step" => step,
+            "step_name" => step_name,
+            "resume_instructions" => resume_instructions,
+            "answered" => false,
+            "created_at" => time
+          }.merge(infer_requester_context(assignment: assignment, step: step)).compact
+
+          body = build_body(title: title, questions: questions)
+          content = Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body)
+
+          item_file = File.join(item_dir, Atoms::HitlFilePattern.filename(id, file_slug))
+          File.write(item_file, content)
+
+          loader = HitlLoader.new
+          special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+            item_dir,
+            root: @root_dir
+          )
+          loader.load(item_dir, id: id, special_folder: special_folder)
+        end
+
+        private
+
+        def generate_unique_id(base_time)
+          time = base_time
+          1000.times do
+            id = Atoms::HitlIdFormatter.generate(time)
+            return id unless hitl_id_exists?(id)
+
+            time += 2
+          end
+
+          raise "Failed to generate unique HITL ID after 1000 attempts"
+        end
+
+        def hitl_id_exists?(id)
+          pattern = File.join(@root_dir, "**", "#{id}-*")
+          !Dir.glob(pattern).empty?
+        end
+
+        def unique_folder_name(id, slug, target_dir)
+          folder_name = Atoms::HitlFilePattern.folder_name(id, slug)
+          candidate_dir = File.join(target_dir, folder_name)
+          return [folder_name, slug] unless Dir.exist?(candidate_dir)
+
+          counter = 2
+          loop do
+            unique_slug = "#{slug}-#{counter}"
+            folder_name = Atoms::HitlFilePattern.folder_name(id, unique_slug)
+            candidate_dir = File.join(target_dir, folder_name)
+            break [folder_name, unique_slug] unless Dir.exist?(candidate_dir)
+
+            counter += 1
+          end
+        end
+
+        def generate_folder_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title.to_s)
+          words = sanitized.split("-")
+          words.take(6).join("-").then { |s| s.empty? ? "hitl" : s }
+        end
+
+        def generate_file_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title.to_s)
+          words = sanitized.split("-")
+          words.take(8).join("-").then { |s| s.empty? ? "hitl" : s }
+        end
+
+        def determine_target_dir(move_to)
+          return @root_dir unless move_to
+
+          normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(move_to)
+          candidate = File.expand_path(File.join(@root_dir, normalized))
+          root_real = File.expand_path(@root_dir)
+
+          unless candidate.start_with?(root_real + File::SEPARATOR) || candidate == root_real
+            raise ArgumentError, "Path traversal detected in --move-to option"
+          end
+
+          candidate
+        end
+
+        def build_body(title:, questions: [])
+          question_lines = if questions.empty?
+            "- (pending human input)"
+          else
+            questions.map { |q| "- #{q}" }.join("\n")
+          end
+
+          <<~BODY
+            # #{title}
+
+            ## Questions
+
+            #{question_lines}
+
+            ## Answer
+
+          BODY
+        end
+
+        def infer_requester_context(assignment:, step:)
+          assignment_id = assignment.to_s.split("@", 2).first.to_s.strip
+          return {} if assignment_id.empty?
+
+          sessions_dir = File.join(project_root, ".ace-local", "assign", assignment_id, "sessions")
+          return {} unless Dir.exist?(sessions_dir)
+
+          candidates = []
+          ancestors_for_step(step).each do |number|
+            path = File.join(sessions_dir, "#{number}-session.yml")
+            candidates << path if File.exist?(path)
+          end
+          newest = Dir.glob(File.join(sessions_dir, "*-session.yml")).sort_by { |path| File.mtime(path) }.reverse
+          candidates.concat(newest)
+
+          candidates.uniq.each do |path|
+            data = YAML.safe_load_file(path, permitted_classes: [Time], aliases: false) || {}
+            next unless data.is_a?(Hash)
+
+            provider = data["provider"].to_s.strip
+            model = data["model"].to_s.strip
+            session_id = data["session_id"].to_s.strip
+            next if provider.empty? && model.empty? && session_id.empty?
+
+            return {
+              "requester_provider" => (provider.empty? ? nil : provider),
+              "requester_model" => (model.empty? ? nil : model),
+              "requester_session_id" => (session_id.empty? ? nil : session_id)
+            }.compact
+          end
+
+          {}
+        rescue StandardError
+          {}
+        end
+
+        def ancestors_for_step(step)
+          raw = step.to_s.strip
+          return [] if raw.empty?
+
+          parts = raw.split(".")
+          (1..parts.length).map { |count| parts[0, count].join(".") }.reverse
+        end
+
+        def project_root
+          expanded = File.expand_path(@root_dir)
+          suffix = "#{File::SEPARATOR}.ace-local#{File::SEPARATOR}hitl"
+          return expanded[0...-suffix.length] if expanded.end_with?(suffix)
+
+          Dir.pwd
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_display_formatter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Molecules
+      # Formats HITL events for list output with stats footer.
+      class HitlDisplayFormatter
+        C = Ace::Support::Items::Atoms::AnsiColors
+
+        STATUS_SYMBOLS = {
+          "pending" => "○",
+          "answered" => "✓"
+        }.freeze
+
+        STATUS_ORDER = %w[pending answered].freeze
+
+        def self.format_list(events, total_count: nil, global_folder_stats: nil)
+          body = if events.empty?
+            "No HITL events found"
+          else
+            events.sort_by(&:id).map { |event| format_list_line(event) }.join("\n")
+          end
+
+          stats = Ace::Support::Items::Atoms::ItemStatistics.count_by(events, :status)
+          folder_stats = Ace::Support::Items::Atoms::ItemStatistics.count_by(events, :special_folder)
+          footer = Ace::Support::Items::Atoms::StatsLineFormatter.format(
+            label: "HITL Events",
+            stats: stats,
+            status_order: STATUS_ORDER,
+            status_icons: STATUS_SYMBOLS,
+            folder_stats: folder_stats,
+            total_count: total_count,
+            global_folder_stats: global_folder_stats
+          )
+
+          "#{body}\n\n#{footer}"
+        end
+
+        def self.format_list_line(event)
+          status_sym = STATUS_SYMBOLS[event.status] || "○"
+          id_str = C.colorize(event.id, C::DIM)
+          tags_str = event.tags.any? ? C.colorize(" [#{event.tags.join(", ")}]", C::DIM) : ""
+          folder_label = event.special_folder ? Ace::Support::Items::Atoms::SpecialFolderDetector.short_name(event.special_folder) : nil
+          folder_str = folder_label ? C.colorize(" (#{folder_label})", C::DIM) : ""
+
+          "#{status_sym}   #{id_str}  #{event.title}#{tags_str}#{folder_str}"
+        end
+
+        private_class_method :format_list_line
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_loader.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "time"
+require "ace/support/items"
+require_relative "../atoms/hitl_file_pattern"
+require_relative "../models/hitl_event"
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlLoader
+        def load(dir_path, id: nil, special_folder: nil)
+          return nil unless Dir.exist?(dir_path)
+
+          hitl_file = Dir.glob(File.join(dir_path, Atoms::HitlFilePattern::FILE_GLOB)).first
+          return nil unless hitl_file
+
+          folder_name = File.basename(dir_path)
+          id ||= extract_id(folder_name)
+
+          content = File.read(hitl_file)
+          frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          answer = extract_answer(body)
+
+          title = frontmatter["title"] ||
+            Ace::Support::Items::Atoms::TitleExtractor.extract(body) ||
+            folder_name
+
+          created_at = parse_created_at(frontmatter["created_at"])
+
+          known_keys = %w[
+            id status title kind tags questions assignment step step_name
+            resume_instructions created_at answered answered_at
+            requester_provider requester_model requester_session_id
+            waiter_state waiter_session_id waiter_provider waiter_last_seen_at
+            waiter_poll_every_sec waiter_timeout_at
+            resume_dispatch_status resume_dispatch_attempted_at resumed_at resumed_by
+            resume_dispatch_error
+          ]
+          extra_metadata = frontmatter.reject { |k, _| known_keys.include?(k) }
+
+          Models::HitlEvent.new(
+            id: id || frontmatter["id"],
+            status: frontmatter["status"] || "pending",
+            kind: frontmatter["kind"] || "clarification",
+            title: title,
+            tags: Array(frontmatter["tags"]),
+            questions: Array(frontmatter["questions"]),
+            answer: answer,
+            content: body.to_s.strip,
+            path: dir_path,
+            file_path: hitl_file,
+            special_folder: special_folder,
+            created_at: created_at,
+            metadata: extra_metadata.merge(
+              "assignment" => frontmatter["assignment"],
+              "step" => frontmatter["step"],
+              "step_name" => frontmatter["step_name"],
+              "resume_instructions" => frontmatter["resume_instructions"],
+              "answered" => frontmatter["answered"],
+              "answered_at" => frontmatter["answered_at"],
+              "requester_provider" => frontmatter["requester_provider"],
+              "requester_model" => frontmatter["requester_model"],
+              "requester_session_id" => frontmatter["requester_session_id"],
+              "waiter_state" => frontmatter["waiter_state"],
+              "waiter_session_id" => frontmatter["waiter_session_id"],
+              "waiter_provider" => frontmatter["waiter_provider"],
+              "waiter_last_seen_at" => frontmatter["waiter_last_seen_at"],
+              "waiter_poll_every_sec" => frontmatter["waiter_poll_every_sec"],
+              "waiter_timeout_at" => frontmatter["waiter_timeout_at"],
+              "resume_dispatch_status" => frontmatter["resume_dispatch_status"],
+              "resume_dispatch_attempted_at" => frontmatter["resume_dispatch_attempted_at"],
+              "resumed_at" => frontmatter["resumed_at"],
+              "resumed_by" => frontmatter["resumed_by"],
+              "resume_dispatch_error" => frontmatter["resume_dispatch_error"]
+            ).compact
+          )
+        rescue SystemCallError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+          warn "Warning: Failed to load HITL event from #{dir_path}: #{e.class}: #{e.message}"
+          nil
+        end
+
+        private
+
+        def extract_id(folder_name)
+          match = folder_name.match(/^([0-9a-z]{6})/)
+          match ? match[1] : nil
+        end
+
+        def extract_answer(body)
+          text = body.to_s
+          match = text.match(/^## Answer[ \t]*(?:\n(.*))?\z/m)
+          return nil unless match
+
+          answer = match[1].to_s.strip
+          answer.empty? ? nil : answer
+        end
+
+        def parse_created_at(value)
+          return Time.now unless value
+
+          case value
+          when Time then value
+          when String then Time.parse(value)
+          else Time.now
+          end
+        rescue StandardError
+          Time.now
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_resolver.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+require_relative "hitl_scanner"
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlResolver
+        def initialize(root_dir)
+          @scanner = HitlScanner.new(root_dir)
+        end
+
+        def resolve(ref, warn_on_ambiguity: true)
+          scan_results = @scanner.scan
+          resolver = Ace::Support::Items::Molecules::ShortcutResolver.new(scan_results)
+
+          on_ambiguity = if warn_on_ambiguity
+            ->(matches) {
+              ids = matches.map(&:id).join(", ")
+              warn "Warning: Ambiguous shortcut '#{ref}' matches #{matches.size} HITL events: #{ids}. Using most recent."
+            }
+          end
+
+          resolver.resolve(ref, on_ambiguity: on_ambiguity)
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_scanner.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+require_relative "../atoms/hitl_file_pattern"
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlScanner
+        attr_reader :last_scan_total, :last_folder_counts
+
+        def initialize(root_dir)
+          @root_dir = root_dir
+          @scanner = Ace::Support::Items::Molecules::DirectoryScanner.new(
+            root_dir,
+            file_pattern: Atoms::HitlFilePattern::FILE_GLOB
+          )
+        end
+
+        def scan
+          @scanner.scan
+        end
+
+        def scan_in_folder(folder)
+          results = scan
+          @last_scan_total = results.size
+          @last_folder_counts = results.group_by(&:special_folder).transform_values(&:size)
+          return results if folder.nil?
+
+          virtual = Ace::Support::Items::Atoms::SpecialFolderDetector.virtual_filter?(folder)
+          case virtual
+          when :all then results
+          when :next then results.select { |r| r.special_folder.nil? }
+          else
+            normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(folder)
+            results.select { |r| r.special_folder == normalized }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/resume_dispatcher.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Dispatches resume signals to waiting agents.
+      # Primary path is provider/session resume; fallback path executes resume instructions.
+      class ResumeDispatcher
+        Result = Struct.new(:success?, :mode, :details, :error, keyword_init: true)
+
+        def dispatch(event:, answer:, now: Time.now.utc)
+          session_id = event.metadata["requester_session_id"].to_s.strip
+          provider = event.metadata["requester_provider"].to_s.strip
+          instructions = event.metadata["resume_instructions"].to_s.strip
+
+          payload = build_payload(event: event, answer: answer, now: now)
+
+          if !session_id.empty? && !provider.empty?
+            resumed = dispatch_to_session(provider: provider, session_id: session_id, payload: payload)
+            return resumed if resumed.success?
+          end
+
+          return failed("No resume instructions available") if instructions.empty?
+
+          shell = run_shell(instructions)
+          return ok(mode: "command", details: "resume_instructions") if shell[:status].success?
+
+          failed("Resume command failed: #{stderr_or_stdout(shell)}")
+        rescue StandardError => e
+          failed("Resume dispatch exception: #{e.class}: #{e.message}")
+        end
+
+        private
+
+        def build_payload(event:, answer:, now:)
+          lines = []
+          lines << "HITL event answer received."
+          lines << "id: #{event.id}"
+          assignment = event.metadata["assignment"]
+          step = event.metadata["step"]
+          lines << "assignment: #{assignment}" if assignment
+          lines << "step: #{step}" if step
+          lines << "answered_at: #{now.iso8601}"
+          lines << ""
+          lines << "answer:"
+          lines << answer.to_s
+          lines << ""
+          resume = event.metadata["resume_instructions"].to_s
+          lines << "resume_instructions: #{resume}" unless resume.strip.empty?
+          lines.join("\n")
+        end
+
+        def dispatch_to_session(provider:, session_id:, payload:)
+          case provider
+          when /\Acodex\z/i
+            cmd = ["codex", "exec", "resume", session_id]
+            io = run_command(cmd, stdin_data: payload)
+            return ok(mode: "session", details: "codex:#{session_id}") if io[:status].success?
+            failed("Codex session resume failed: #{stderr_or_stdout(io)}")
+          when /\Aclaude\z/i
+            cmd = ["claude", "-p", "--resume", session_id]
+            io = run_command(cmd, stdin_data: payload)
+            return ok(mode: "session", details: "claude:#{session_id}") if io[:status].success?
+            failed("Claude session resume failed: #{stderr_or_stdout(io)}")
+          else
+            failed("Unsupported resume provider '#{provider}'")
+          end
+        end
+
+        def run_shell(command)
+          stdout, stderr, status = Open3.capture3("bash", "-lc", command.to_s)
+          {stdout: stdout, stderr: stderr, status: status}
+        end
+
+        def run_command(cmd, stdin_data: nil)
+          stdout, stderr, status = Open3.capture3(*cmd, stdin_data: stdin_data.to_s)
+          {stdout: stdout, stderr: stderr, status: status}
+        end
+
+        def stderr_or_stdout(io)
+          out = io[:stderr].to_s.strip
+          out = io[:stdout].to_s.strip if out.empty?
+          out.empty? ? "(no output)" : out
+        end
+
+        def ok(mode:, details:)
+          Result.new(success?: true, mode: mode, details: details, error: nil)
+        end
+
+        def failed(error)
+          Result.new(success?: false, mode: nil, details: nil, error: error)
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/worktree_scope_resolver.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Hitl
+    module Molecules
+      class WorktreeScopeResolver
+        VALID_SCOPES = %w[current all].freeze
+
+        def default_scope
+          main_checkout? ? "all" : "current"
+        end
+
+        def effective_scope(requested_scope)
+          requested_scope || default_scope
+        end
+
+        def current_worktree_root
+          @current_worktree_root ||= git_output("rev-parse", "--show-toplevel")
+        end
+
+        def worktree_roots(scope:)
+          case scope
+          when "current"
+            [current_worktree_root].compact
+          when "all"
+            roots = parse_worktree_list
+            roots = [current_worktree_root].compact if roots.empty?
+            roots
+          else
+            []
+          end
+        end
+
+        private
+
+        def main_checkout?
+          current = current_worktree_root
+          common_root = git_common_root
+          return false if current.nil? || common_root.nil?
+
+          File.expand_path(current) == File.expand_path(common_root)
+        end
+
+        def parse_worktree_list
+          output = git_output("worktree", "list", "--porcelain")
+          return [] if output.nil? || output.empty?
+
+          roots = output.lines.filter_map do |line|
+            next unless line.start_with?("worktree ")
+
+            line.sub("worktree ", "").strip
+          end
+          roots.uniq
+        end
+
+        def git_common_root
+          common_dir = git_output("rev-parse", "--path-format=absolute", "--git-common-dir")
+          return nil if common_dir.nil? || common_dir.empty?
+
+          File.dirname(common_dir)
+        end
+
+        def git_output(*args)
+          stdout, status = Open3.capture2("git", *args)
+          return nil unless status.success?
+
+          output = stdout.to_s.strip
+          output.empty? ? nil : output
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end