ace-hitl 0.17.0 → 0.23.2

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

@@ -19,6 +19,10 @@ module Ace
 
         def create(title,
           kind: nil,
+          type: nil,
+          result: nil,
+          task: nil,
+          body: [],
           questions: [],
           tags: [],
           assignment: nil,
@@ -26,9 +30,15 @@ module Ace
           step_name: nil,
           resume_instructions: nil,
           move_to: nil,
+          recipient: nil,
+          reply_to: nil,
           time: Time.now.utc)
           raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
 
+          effective_type = type || "question"
+          validate_type!(effective_type, result: result, body: body, questions: questions,
+            resume_instructions: resume_instructions)
+
           effective_kind = kind || @config.dig("hitl", "default_kind") || "clarification"
           id = generate_unique_id(time)
           folder_slug = generate_folder_slug(title)
@@ -41,23 +51,44 @@ module Ace
           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)
+          frontmatter = if effective_type == "report"
+            {
+              "id" => id,
+              "title" => title,
+              "type" => "report",
+              "result" => result,
+              "status" => "recorded",
+              "tags" => tags,
+              "task" => task,
+              "assignment" => assignment,
+              "step" => step,
+              "step_name" => step_name,
+              "created_at" => time
+            }.merge(recipient_keys(recipient, id)).compact
+          else
+            {
+              "id" => id,
+              "title" => title,
+              "type" => "question",
+              "kind" => effective_kind,
+              "status" => "pending",
+              "tags" => tags,
+              "task" => task,
+              "questions" => questions,
+              "assignment" => assignment,
+              "step" => step,
+              "step_name" => step_name,
+              "resume_instructions" => resume_instructions,
+              "answered" => false,
+              "created_at" => time
+            }.merge(recipient_keys(recipient, id))
+              .merge(reply_to_keys(reply_to, id))
+              .merge(infer_requester_context(assignment: assignment, step: step)).compact
+          end
+
+          body_text = build_body(title: title, type: effective_type, result: result,
+            questions: questions, body: body)
+          content = Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body_text)
 
           item_file = File.join(item_dir, Atoms::HitlFilePattern.filename(id, file_slug))
           File.write(item_file, content)
@@ -72,6 +103,33 @@ module Ace
 
         private
 
+        # Flat recipient keys; the folder form stamps the new event's ID as
+        # the case id (panel form has none). Returns {} when no recipient.
+        def recipient_keys(recipient, id)
+          return {} unless recipient.is_a?(Hash)
+
+          keys = {
+            "recipient_machine" => recipient["machine"],
+            "recipient_folder" => recipient["folder"],
+            "recipient_panel" => recipient["panel"],
+            "recipient_id" => recipient["id"] || (recipient["folder"] ? id : nil)
+          }
+          keys.compact
+        end
+
+        # Flat reply keys (questions only): original sender + exact case.
+        # When the reply address carries no id, the new event's own ID is
+        # the case id the answer binds to.
+        def reply_to_keys(reply_to, id)
+          return {} unless reply_to.is_a?(Hash)
+
+          {
+            "reply_to_machine" => reply_to["machine"],
+            "reply_to_folder" => reply_to["folder"],
+            "reply_to_id" => reply_to["id"] || id
+          }.compact
+        end
+
         def generate_unique_id(base_time)
           time = base_time
           1000.times do
@@ -131,23 +189,64 @@ module Ace
           candidate
         end
 
-        def build_body(title:, questions: [])
-          question_lines = if questions.empty?
-            "- (pending human input)"
+        def validate_type!(type, result:, body:, questions:, resume_instructions:)
+          allowed = %w[question report]
+          unless allowed.include?(type)
+            raise ArgumentError, "Invalid type '#{type}'. Allowed: #{allowed.join(", ")}"
+          end
+
+          if type == "report"
+            unless %w[success error].include?(result.to_s)
+              raise ArgumentError, "Report requires result 'success' or 'error'"
+            end
+            if questions.any?
+              raise ArgumentError, "Reports cannot include questions; use body lines instead"
+            end
+            if resume_instructions
+              raise ArgumentError, "Reports do not carry resume instructions; only questions resume"
+            end
           else
-            questions.map { |q| "- #{q}" }.join("\n")
+            if result
+              raise ArgumentError, "result is only valid for reports (--type report)"
+            end
+            if body.any?
+              raise ArgumentError, "body is only valid for reports (--type report)"
+            end
           end
+        end
+
+        def build_body(title:, type: "question", result: nil, questions: [], body: [])
+          if type == "report"
+            content_lines = body.map(&:strip).reject(&:empty?)
+            content_lines = ["(no content)"] if content_lines.empty?
 
-          <<~BODY
-            # #{title}
+            <<~BODY
+              # #{title}
 
-            ## Questions
+              ## Report
 
-            #{question_lines}
+              Result: #{result}
+
+              #{content_lines.map { |line| "- #{line}" }.join("\n")}
+            BODY
+          else
+            question_lines = if questions.empty?
+              "- (pending human input)"
+            else
+              questions.map { |q| "- #{q}" }.join("\n")
+            end
 
-            ## Answer
+            <<~BODY
+              # #{title}
 
-          BODY
+              ## Questions
+
+              #{question_lines}
+
+              ## Answer
+
+            BODY
+          end
         end
 
         def infer_requester_context(assignment:, step:)

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Molecules
+      # Pure redelivery decisions over the persisted per-route delivery map
+      # (event frontmatter `delivery.<route>`). No IO.
+      #
+      # Statuses: delivered (confirmed; skipped on default retry), failed /
+      # unavailable (failure reason retained; retried), in_flight (marker
+      # written before a delivery attempt; a stale one means the sending
+      # process died — unknown result, retried). At-least-once: a retry after
+      # an unknown result may duplicate, so recipients dedup by case ID.
+      module HitlDeliveryState
+        module_function
+
+        # @param record [Hash, nil] persisted route record
+        # @return [Boolean] true when the route must be (re)delivered;
+        #   only a confirmed delivered record is skipped
+        def retry?(record)
+          return true if record.nil? || !record.is_a?(Hash)
+
+          record["status"] != "delivered"
+        end
+
+        # A stale in_flight marker is an unknown result.
+        def unknown?(record)
+          record.is_a?(Hash) && record["status"] == "in_flight"
+        end
+
+        # @return [Boolean] some route has a delivery record and is not delivered
+        def undelivered?(delivery_map)
+          map = normalized(delivery_map)
+          return false if map.empty?
+
+          map.any? { |_route, record| record["status"] != "delivered" }
+        end
+
+        # @return [Boolean] a delivery map exists and every recorded route delivered
+        def fully_delivered?(delivery_map)
+          map = normalized(delivery_map)
+          return false if map.empty?
+
+          map.all? { |_route, record| record["status"] == "delivered" }
+        end
+
+        # Malformed entries (nil/scalar records from hand-written YAML) are
+        # dropped, never raised through: a broken record is simply not a
+        # delivery fact.
+        def normalized(delivery_map)
+          return {} unless delivery_map.is_a?(Hash)
+
+          delivery_map.select { |_route, record| record.is_a?(Hash) }
+        end
+      end
+    end
+  end
+end

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

@@ -9,10 +9,11 @@ module Ace
 
         STATUS_SYMBOLS = {
           "pending" => "○",
-          "answered" => "✓"
+          "answered" => "✓",
+          "recorded" => "▪"
         }.freeze
 
-        STATUS_ORDER = %w[pending answered].freeze
+        STATUS_ORDER = %w[pending answered recorded].freeze
 
         def self.format_list(events, total_count: nil, global_folder_stats: nil)
           body = if events.empty?

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

@@ -29,7 +29,9 @@ module Ace
           created_at = parse_created_at(frontmatter["created_at"])
 
           known_keys = %w[
-            id status title kind tags questions assignment step step_name
+            id status title kind type result task delivery tags questions assignment step step_name
+            recipient_machine recipient_folder recipient_panel recipient_id
+            reply_to_machine reply_to_folder reply_to_id
             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
@@ -39,10 +41,16 @@ module Ace
           ]
           extra_metadata = frontmatter.reject { |k, _| known_keys.include?(k) }
 
+          event_type = frontmatter["type"] || "question"
+
           Models::HitlEvent.new(
             id: id || frontmatter["id"],
             status: frontmatter["status"] || "pending",
-            kind: frontmatter["kind"] || "clarification",
+            # Kinds apply to questions only; reports carry no kind so
+            # question-oriented --kind filters never mix them in.
+            kind: event_type == "report" ? nil : (frontmatter["kind"] || "clarification"),
+            type: event_type,
+            result: frontmatter["result"],
             title: title,
             tags: Array(frontmatter["tags"]),
             questions: Array(frontmatter["questions"]),
@@ -53,9 +61,18 @@ module Ace
             special_folder: special_folder,
             created_at: created_at,
             metadata: extra_metadata.merge(
+              "task" => frontmatter["task"],
+              "delivery" => frontmatter["delivery"],
               "assignment" => frontmatter["assignment"],
               "step" => frontmatter["step"],
               "step_name" => frontmatter["step_name"],
+              "recipient_machine" => frontmatter["recipient_machine"],
+              "recipient_folder" => frontmatter["recipient_folder"],
+              "recipient_panel" => frontmatter["recipient_panel"],
+              "recipient_id" => frontmatter["recipient_id"],
+              "reply_to_machine" => frontmatter["reply_to_machine"],
+              "reply_to_folder" => frontmatter["reply_to_folder"],
+              "reply_to_id" => frontmatter["reply_to_id"],
               "resume_instructions" => frontmatter["resume_instructions"],
               "answered" => frontmatter["answered"],
               "answered_at" => frontmatter["answered_at"],

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "hitl_address_resolver"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Loads and validates the configured adapter route set from the hitl
+      # cascade (`hitl.adapters.routes`). Fail-closed: no routes, malformed
+      # entries, and duplicate route names are actionable errors raised
+      # before any delivery is attempted.
+      class HitlRouteLoader
+        CONFIG_LOCATION = "hitl.adapters.routes (.ace/hitl/config.yml)"
+
+        class NoRoutesError < StandardError; end
+        class InvalidRouteError < StandardError; end
+
+        # Delivery retention persists `delivery.<route>` as nested dot-keys
+        # and reads back the literal route key, so route names must be a
+        # single path segment (no dots).
+        ROUTE_NAME_PATTERN = /\A[a-z0-9][a-z0-9_-]*\z/i.freeze
+
+        # @param config [Hash] merged hitl namespace config
+        # @return [Array<Hash>] validated string-keyed routes
+        # @raise [NoRoutesError, InvalidRouteError]
+        def self.load(config)
+          routes = config.is_a?(Hash) ? config.dig("hitl", "adapters", "routes") : nil
+          if routes.nil?
+            raise NoRoutesError,
+              "no adapter routes configured; set #{CONFIG_LOCATION}"
+          end
+          unless routes.is_a?(Array) && !routes.empty?
+            raise NoRoutesError,
+              "no adapter routes configured; set #{CONFIG_LOCATION}"
+          end
+
+          validated = routes.map { |entry| validate_entry(entry) }
+          names = validated.map { |route| route["route"] }
+          duplicates = names.tally.select { |_, count| count > 1 }.keys
+          unless duplicates.empty?
+            raise InvalidRouteError,
+              "duplicate route name(s) #{duplicates.sort.join(", ")} in #{CONFIG_LOCATION}"
+          end
+
+          validated
+        end
+
+        def self.validate_entry(entry)
+          unless entry.is_a?(Hash)
+            raise InvalidRouteError, "route entry must be a mapping, got #{entry.class} in #{CONFIG_LOCATION}"
+          end
+
+          normalized = stringified(entry)
+          adapter = normalized["adapter"].to_s.strip
+          if adapter.empty?
+            raise InvalidRouteError, "route entry missing required 'adapter' in #{CONFIG_LOCATION}"
+          end
+
+          route = normalized["route"].to_s.strip
+          route = adapter if route.empty?
+          unless route.match?(ROUTE_NAME_PATTERN)
+            raise InvalidRouteError,
+              "route name '#{route}' is invalid in #{CONFIG_LOCATION}: must match #{ROUTE_NAME_PATTERN.source} " \
+              "(delivery retention keys route names literally; a dot would nest frontmatter keys and break retry/skip)"
+          end
+
+          normalized["route"] = route
+          normalized["adapter"] = adapter
+          if normalized.key?("recipients") &&
+              (!normalized["recipients"].is_a?(Array) || normalized["recipients"].empty? ||
+               !normalized["recipients"].all? { |name| name.is_a?(String) && !name.strip.empty? })
+            raise InvalidRouteError, "route '#{route}' recipients must be a non-empty list of configured recipient names"
+          end
+          normalized
+        end
+
+        # Selection happens before adapter construction or delivery-state writes.
+        # Names are configuration references, not labels copied onto an event:
+        # compare their resolved addresses to the event's immutable destination.
+        def self.for_recipient(routes, recipient:, config:)
+          return routes if recipient.nil?
+
+          resolver = HitlAddressResolver.new(config: config)
+          destination = recipient.reject { |key, _| key == "id" }
+          selected = routes.select do |route|
+            addresses = Array(route["recipients"]).map do |name|
+              resolver.resolve(name).reject { |key, _| key == "id" }
+            end
+            addresses.include?(destination)
+          end
+          if selected.empty?
+            raise NoRoutesError, "no adapter route matches recipient #{Atoms::HitlAddress.to_s(recipient)}; " \
+              "set route recipients to configured recipient names in #{CONFIG_LOCATION}"
+          end
+          selected
+        rescue HitlAddressResolver::UnknownRecipientError, HitlAddressResolver::InvalidAddressError => e
+          raise InvalidRouteError, e.message
+        end
+
+        def self.stringified(entry)
+          entry.each_with_object({}) do |(key, value), memo|
+            memo[key.to_s] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/organisms/hitl_manager.rb

@@ -26,20 +26,46 @@ module Ace
           end
         end
 
-        attr_reader :root_dir, :last_list_total, :last_folder_counts
+        class NotAnswerableError < StandardError; end
+        class AnswerConflictError < StandardError; end
 
-        def initialize(root_dir: nil, config: nil, scope_resolver: nil, resume_dispatcher: nil)
+        attr_reader :root_dir, :last_list_total, :last_folder_counts, :config
+
+        def initialize(root_dir: nil, config: nil, scope_resolver: nil, resume_dispatcher: nil,
+          address_resolver: nil)
           @config = config || load_config
           @configured_root_setting = @config.dig("hitl", "root_dir") || Molecules::HitlConfigLoader::DEFAULT_ROOT_DIR
           @root_dir = root_dir || resolve_root_dir
           @scope_resolver = scope_resolver || Molecules::WorktreeScopeResolver.new
           @resume_dispatcher = resume_dispatcher || Molecules::ResumeDispatcher.new
+          @address_resolver = address_resolver || Molecules::HitlAddressResolver.new(config: @config)
         end
 
-        def create(title, **options)
+        def create(title, to: nil, **options)
+          # Resolve the recipient address before any I/O: unknown names and
+          # malformed addresses fail closed with nothing written. The reply
+          # address (sender machine + events folder) applies to questions
+          # only — a report carries the recipient but never awaits a reply,
+          # so hitl.machine is not required for report+--to.
+          recipient = nil
+          reply_to = nil
+          effective_to = to || @address_resolver.default_recipient
+          event_type = options[:type] || "question"
+          if effective_to
+            recipient = @address_resolver.resolve(effective_to)
+            if event_type == "question"
+              # The reply address must identify THIS sender folder: use the
+              # resolved root (absolute), not the configured setting — a
+              # relative value like `.ace-local/hitl` is identical across
+              # worktrees and gives the reply no base to resolve against.
+              reply_to = @address_resolver.sender_address(folder: File.expand_path(@root_dir), id: "pending")
+                .reject { |key, _| key == "id" }
+            end
+          end
+
           ensure_root_dir
           creator = Molecules::HitlCreator.new(root_dir: @root_dir, config: @config)
-          creator.create(title, **options)
+          creator.create(title, **options, recipient: recipient, reply_to: reply_to)
         end
 
         def show(ref, scope: nil)
@@ -68,13 +94,15 @@ module Ace
           }
         end
 
-        def list(status: nil, kind: nil, in_folder: "next", tags: [], scope: nil)
+        def list(status: nil, kind: nil, type: nil, delivery: nil, in_folder: "next", tags: [], scope: nil)
           effective_scope = @scope_resolver.effective_scope(scope)
           scan_results = scan_results_for_scope(effective_scope, in_folder: in_folder)
           events = load_events(scan_results)
 
           events = events.select { |event| event.status == status } if status
           events = events.select { |event| event.kind == kind } if kind
+          events = events.select { |event| event.type == type } if type
+          events = filter_by_delivery(events, delivery) if delivery
           events = filter_by_tags(events, tags) if tags.any?
 
           events
@@ -87,6 +115,11 @@ module Ace
           event = resolved[:event]
           hitl_root = resolved[:hitl_root] || @root_dir
 
+          if !answer.nil? && event.report?
+            raise NotAnswerableError,
+              "HITL event '#{event.id}' is a report; reports do not await an answer"
+          end
+
           has_field_updates = [set, add, remove].any? { |h| h && !h.empty? }
           if has_field_updates && !answer.nil?
             apply_field_and_answer_updates(event.file_path, set: set, add: add, remove: remove, answer: answer)
@@ -121,6 +154,21 @@ module Ace
           loader.load(current_path, id: event.id, special_folder: current_special)
         end
 
+        # Transport imports are first-answer-wins. The case's own write lock
+        # checks the answer again, so replay cannot overwrite a human answer.
+        # Explicit `update --answer` remains an intentional editing operation.
+        def accept_answer(ref, answer:, scope: nil)
+          resolved = resolve_for_mutation(ref, scope: scope)
+          return nil unless resolved
+          event = resolved[:event]
+          raise NotAnswerableError, "reports do not await an answer" if event.report?
+          raise NotAnswerableError, "managed requests require their authenticated lifecycle" if event.metadata["lab_request_id"]
+          raise ArgumentError, "answer is empty" if answer.to_s.strip.empty?
+          apply_field_and_answer_updates(event.file_path, set: {}, add: {}, remove: {},
+            answer: answer, first_answer: true)
+          Molecules::HitlLoader.new.load(event.path, id: event.id, special_folder: event.special_folder)
+        end
+
         def wait_for_answer(ref, scope: nil, poll_every: 600, timeout: 14_400, waiter: {}, now_proc: nil, sleeper: nil)
           poll_every = normalize_poll_seconds(poll_every)
           timeout = normalize_timeout_seconds(timeout)
@@ -137,6 +185,8 @@ module Ace
             return {status: :not_found} unless current
 
             event = current[:event]
+            return {status: :report, event: event} if event.report?
+
             if event.metadata["lab_request_id"]
               raise Lifecycle::StateError, "managed requests require authenticated scoped wait"
             end
@@ -179,6 +229,7 @@ module Ace
           return {status: :not_found} unless current
 
           event = current[:event]
+          return {status: :report, event: event} if event.report?
           return {status: :managed_request, event: event} if event.metadata["lab_request_id"]
 
           answer = event.answer.to_s
@@ -344,6 +395,17 @@ module Ace
           events.select { |event| tags.any? { |tag| event.tags.include?(tag) } }
         end
 
+        def filter_by_delivery(events, delivery)
+          case delivery.to_s
+          when "undelivered"
+            events.select { |event| Molecules::HitlDeliveryState.undelivered?(event.metadata["delivery"]) }
+          when "delivered"
+            events.select { |event| Molecules::HitlDeliveryState.fully_delivered?(event.metadata["delivery"]) }
+          else
+            raise Error, "invalid delivery filter '#{delivery}' (undelivered, delivered)"
+          end
+        end
+
         def apply_answer_update(file_path, answer)
           content = File.read(file_path)
           frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
@@ -362,7 +424,7 @@ module Ace
           File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
         end
 
-        def apply_field_and_answer_updates(file_path, set:, add:, remove:, answer:)
+        def apply_field_and_answer_updates(file_path, set:, add:, remove:, answer:, first_answer: false)
           File.open(file_path, File::RDWR) do |file|
             file.flock(File::LOCK_EX)
             file.rewind
@@ -370,6 +432,11 @@ module Ace
             content = file.read
             frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
             body = body.sub(/\A\n/, "")
+            previous = body.match(/^## Answer[ \t]*(?:\n(.*))?\z/m)&.[](1).to_s.strip
+            if first_answer && (frontmatter["answered"] == true || !previous.empty?)
+              raise AnswerConflictError, "case already has a different answer" unless previous == answer.to_s.strip
+              return
+            end
 
             Ace::Support::Items::Molecules::FieldUpdater.apply_set(frontmatter, set)
             Ace::Support::Items::Molecules::FieldUpdater.apply_add(frontmatter, add)