ace-hitl 0.24.2 → 0.25.0

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "ace/support/items"
+
+module Ace
+  module Hitl
+    module Molecules
+      # The one crash-atomic writer for HITL case files (re-review R2):
+      # every mutation locks a STABLE sidecar (`<case>.lock`, a file that
+      # is never renamed) and replaces the case file via tmp+fsync+rename.
+      # A process killed mid-write leaves either the old or the new
+      # content — never a truncated or zero-byte case — and mutual
+      # exclusion survives the rename (a lock on the case file itself
+      # would break the moment its inode is replaced).
+      module CaseFileWriter
+        module_function
+
+        # Exclusive sidecar lock around a case-file mutation.
+        def with_case_lock(file_path)
+          File.open("#{file_path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # Crash-atomic replace of the whole case file (fsynced tmp +
+        # rename). Callers hold the sidecar lock.
+        def write_atomic(file_path, new_content)
+          tmp_path = "#{file_path}.tmp.#{Process.pid}.#{Thread.current.object_id}"
+          File.open(tmp_path, "w", 0o600) do |tmp|
+            tmp.write(new_content)
+            tmp.flush
+            tmp.fsync
+          end
+          File.rename(tmp_path, file_path)
+        ensure
+          File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
+        end
+
+        # Field-only update under the sidecar lock: one locked
+        # read-modify-write, replaced atomically — never the shared
+        # FieldUpdater's in-place truncate(0) write.
+        def apply_fields(file_path, set: {}, add: {}, remove: {})
+          with_case_lock(file_path) do
+            content = File.read(file_path)
+            begin
+              frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse!(content)
+            rescue Psych::Exception => e
+              # Same error shape as FieldUpdater.parse_strict: a corrupt
+              # case file is a named, path-carrying refusal to rewrite —
+              # never a raw parser error escaping the writer.
+              raise ArgumentError, "#{file_path}: refusing to rewrite the file (#{e.message})"
+            end
+            # Strip the body's leading newline: rebuild re-inserts the
+            # frontmatter/body separator, so keeping it would add one
+            # blank line per write — compounding on every field update.
+            body = body.sub(/\A\n/, "")
+            Ace::Support::Items::Molecules::FieldUpdater.apply_set(frontmatter, set)
+            Ace::Support::Items::Molecules::FieldUpdater.apply_add(frontmatter, add)
+            Ace::Support::Items::Molecules::FieldUpdater.apply_remove(frontmatter, remove)
+            write_atomic(file_path,
+              Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -29,6 +29,7 @@ module Ace
           step: nil,
           step_name: nil,
           resume_instructions: nil,
+          secret: nil,
           move_to: nil,
           recipient: nil,
           reply_to: nil,
@@ -80,6 +81,7 @@ module Ace
               "step_name" => step_name,
               "resume_instructions" => resume_instructions,
               "answered" => false,
+              "secret" => secret == true ? true : nil,
               "created_at" => time
             }.merge(recipient_keys(recipient, id))
               .merge(reply_to_keys(reply_to, id))
@@ -91,7 +93,10 @@ module Ace
           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)
+          # 0600 from the first byte: a HITL case can carry secret
+          # material (secret asks), so it is never world-readable — even
+          # between creation and any later hardening write.
+          File.open(item_file, "w", 0o600) { |file| file.write(content) }
 
           loader = HitlLoader.new
           special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Molecules
+      # Lesson editor (task 8xs.t.pu0.c): the takeaway the advisory agent
+      # draws from comparing the human decision with its suggestion — its
+      # OWN `## Lesson` section at the same case, inserted BEFORE the
+      # `## Answer` section like the suggestion (answer rewrites can never
+      # remove history). A lesson references the exact question/suggestion/
+      # decision revisions it compared; it is not a new decision and never
+      # changes the answer's authorship.
+      class HitlLessonEditor
+        ANSWER_HEADER = /^## Answer\s*$/m
+
+        # @param body [String] current case body
+        # @param lesson [Hash] {"id","author","relation","takeaway",
+        #   "refs","at"}
+        def self.apply(body, lesson)
+          block = render(lesson)
+          source = body.to_s.rstrip
+          return block if source.empty?
+
+          if source.match?(ANSWER_HEADER)
+            source.sub(ANSWER_HEADER) { "#{block}\n\n## Answer" }
+          else
+            "#{source}\n\n#{block}"
+          end
+        end
+
+        def self.render(lesson)
+          lines = ["## Lesson"]
+          lines << "author: #{lesson.fetch("author")}"
+          lines << "at: #{lesson.fetch("at")}"
+          lines << "relation: #{lesson.fetch("relation")}"
+          lines << "refs: #{Array(lesson["refs"]).join(", ")}" if lesson["refs"]
+          lines << "" << "takeaway: #{lesson.fetch("takeaway")}"
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Molecules
+      # Marked-suggestion editor (task 8xs.t.pu0.b): a suggestion is its
+      # OWN section in the canonical case file — never the Answer. It is
+      # inserted BEFORE the `## Answer` section (or appended at the end
+      # when no answer exists), so the Answer editor's tail replacement
+      # can never remove a suggestion, and an answer written after a
+      # suggestion preserves it. Pure string surgery — atomicity and
+      # locking belong to the manager's transition helper.
+      class HitlSuggestionEditor
+        ANSWER_HEADER = /^## Answer\s*$/m
+        SUGGESTION_HEADER = "## Suggestion"
+
+        # @param body [String] current case body (frontmatter stripped)
+        # @param suggestion [Hash] {"id","author","text","rationale",
+        #   "refs","at"}
+        # @return [String] the updated body
+        def self.apply(body, suggestion)
+          block = render(suggestion)
+          source = body.to_s.rstrip
+          return block if source.empty?
+
+          if source.match?(ANSWER_HEADER)
+            # Insert strictly before the Answer section: the answer tail
+            # replacement never touches what precedes it.
+            source.sub(ANSWER_HEADER) { "#{block}\n\n## Answer" }
+          else
+            "#{source}\n\n#{block}"
+          end
+        end
+
+        # @return [String] the rendered marked suggestion block
+        def self.render(suggestion)
+          lines = [SUGGESTION_HEADER]
+          lines << "author: #{suggestion.fetch("author")}"
+          lines << "at: #{suggestion.fetch("at")}"
+          lines << "refs: #{Array(suggestion["refs"]).join(", ")}" if suggestion["refs"]
+          lines << "" << "proposal: #{suggestion.fetch("text")}" << ""
+          lines << "rationale: #{suggestion.fetch("rationale")}"
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end