ace-hitl 0.17.0 → 0.23.2

data/handbook/workflow-instructions/hitl.wf.md

@@ -3,8 +3,8 @@ doc-type: workflow
 title: HITL Workflow
 purpose: Standardize human-attention handling for blocked and completed work using ace-hitl events.
 ace-docs:
-  last-updated: '2026-04-02'
-  last-checked: '2026-04-02'
+  last-updated: '2026-10-18'
+  last-checked: '2026-10-18'
 ---
 
 # HITL Workflow
@@ -15,12 +15,27 @@ Use `ace-hitl` as the canonical contract whenever agent flow needs explicit huma
 
 ## When To Use HITL
 
-Create a HITL event in exactly two cases:
+Create a HITL event in exactly two shapes:
 
-1. **Blocker requiring human judgment** (ambiguity, product decision, policy/approval gate).
-2. **Work is complete but explicit user attention is required** before follow-up actions.
+1. **Question requiring a decision** (blocker needing human judgment: ambiguity,
+   product decision, policy/approval gate, or completed work that needs explicit
+   confirmation). Questions stay pending and can hold the assignment until the
+   Reply arrives; no answer is never consent or success.
+2. **Report** (work done / error notification that needs no reply):
+   `--type report --result success|error` with optional `--body` lines and
+   task/assignment/step references. Reports are recorded, never pending, and
+   `wait`/`--answer`/`--resume` on them are explicit usage errors.
 
-Do not create HITL events for routine status updates that do not require user action.
+Do not create question events for routine status updates that do not require
+user action; use a report instead.
+
+## Planned surface (L2)
+
+The normal local path uses plain event files: `create`, `list`, `show`, `update`,
+`wait` below -- for both questions and reports. A `serve` boundary service,
+grants, OTP challenges and proposals are not required for this path. Reply
+routing to the correct remote case and configurable adapters (single or in a
+set) land in the remaining L2 leaves; local write is not delivery.
 
 ## Commands
 
@@ -54,6 +69,19 @@ ace-hitl create "Review completed assignment results" \
   --resume "/as-assign-drive <assignment-id>"
 ```
 
+### 2b) Create a work-done or error report (no reply expected)
+
+```bash
+ace-hitl create "Work done" \
+  --type report --result success \
+  --body "Implemented the change; tests green." \
+  --task <task-ref> --assignment <assignment-id> --step <step-number>
+```
+
+Reports land with status `recorded`; never wait on them and never answer them.
+The overseer reads them and archives processed reports with
+`ace-hitl update <hitl-id> --move-to archive`.
+
 ### 3) Discover HITL work
 
 ```bash
@@ -76,6 +104,27 @@ Polling is the default reliability path for the requesting agent:
 ace-hitl wait <hitl-id>
 ```
 
+### 4b) Remote delivery through configured adapter routes
+
+When `hitl.adapters.routes` is configured, deliver the persisted event
+before waiting. Every route reports its own result; a route failure never
+silently reroutes to another recipient.
+
+```bash
+ace-hitl send <hitl-id>
+```
+
+Per-route outcomes are retained on the event file: a later `send` retries
+only undelivered or unknown-result routes (a crashed send leaves an unknown
+result that the next `send` retries — at-least-once, recipients dedup by
+the case ID); `--force` redelivers every route; `--dry-run` previews the
+decisions. Discover retained events with `ace-hitl list --delivery
+undelivered` and inspect retained failure reasons with `ace-hitl show`.
+Redelivery retries the delivery of the same case — never the assignment.
+
+An unavailable or failed route is an escalation reason (retry or fix the
+route configuration); the local event file remains the durable record.
+
 If the waiter is no longer active, operator fallback can dispatch resume:
 
 ```bash

data/lib/ace/hitl/adapters/registry.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Adapters
+      # Duck-typed adapter registry with lazy entrypoint loading.
+      # Semantics mirror Ace::Runtime::Registry (kept independent on
+      # purpose): fail-closed resolution carrying the available list;
+      # only a missing entrypoint counts as unknown — a LoadError raised
+      # inside an installed entrypoint propagates so a broken adapter is
+      # never misreported as unknown.
+      class Registry
+        NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+        ADAPTER_ENTRYPOINT_FORMAT = "ace/hitl/adapters/%s"
+
+        def initialize
+          @factories = {}
+        end
+
+        def register(name, factory = nil, &block)
+          key = name.to_s
+          callable = factory || block
+          unless callable.respond_to?(:call)
+            raise ArgumentError, "adapter factory for '#{key}' must respond to #call"
+          end
+
+          @factories[key] = callable
+          nil
+        end
+
+        def registered?(name)
+          @factories.key?(name.to_s)
+        end
+
+        def available
+          @factories.keys.sort
+        end
+
+        # @return [Object] the built adapter (factory receives the route
+        #   configuration hash)
+        # @raise [UnknownAdapterError] when the name cannot be resolved
+        def resolve(name, route: {})
+          key = name.to_s
+          load_adapter_entrypoint(key) unless @factories.key?(key)
+
+          factory = @factories[key]
+          raise UnknownAdapterError.new(requested: key, available: available) unless factory
+
+          factory.call(route)
+        end
+
+        private
+
+        def load_adapter_entrypoint(name)
+          return unless name.match?(NAME_PATTERN)
+
+          entrypoint = format(ADAPTER_ENTRYPOINT_FORMAT, name)
+          require entrypoint
+        rescue LoadError => e
+          raise unless e.path == entrypoint
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/adapters/terminal.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ace/runtime"
+require_relative "../adapters"
+
+module Ace
+  module Hitl
+    module Adapters
+      # Built-in terminal adapter: pushes the shared event text to a pane
+      # through any Ace::Runtime terminal (tmux, herdr). The runtime is
+      # named by the route configuration, so switching transports is pure
+      # configuration — no sender or coworker change.
+      #
+      # The event's recipient steers the target: a panel-form address on
+      # the route's machine names the pane the text goes to (the route
+      # `pane` is only the fallback for legacy recipient-less events).
+      # Every other recipient — folder form, or a panel on a different
+      # machine — is an explicit per-route refusal, never a silent send
+      # to the route's own pane.
+      class TerminalAdapter
+        def initialize(route)
+          @route_name = route["route"].to_s.strip
+          @runtime_name = route["runtime"].to_s.strip
+          @pane = route["pane"].to_s.strip
+          @machine = route["machine"].to_s
+          if @runtime_name.empty?
+            raise Error, "terminal route '#{@route_name}' missing required 'runtime' (tmux|herdr)"
+          end
+          if @pane.empty?
+            raise Error, "terminal route '#{@route_name}' missing required 'pane' handle"
+          end
+        end
+
+        def deliver(event:, text:, recipient:, reply_to:)
+          pane = target_pane(recipient)
+          unless pane
+            return RouteResult.new(route: @route_name, adapter: "terminal", status: :failed,
+              detail: "terminal route '#{@route_name}' on machine '#{@machine}' cannot serve " \
+                      "recipient #{Atoms::HitlAddress.to_s(recipient)} (panel-form recipient " \
+                      "on this machine required; route pane '#{@pane}' not used)")
+          end
+
+          runtime = Ace::Runtime.resolve(@runtime_name)
+          runtime.send_text(pane: pane, text: text)
+          RouteResult.new(route: @route_name, adapter: "terminal", status: :delivered,
+            detail: "text pushed to #{@runtime_name} pane #{pane}")
+        rescue Ace::Runtime::UnknownRuntimeError,
+          Ace::Runtime::RuntimeUnavailableError => e
+          RouteResult.new(route: @route_name, adapter: "terminal", status: :unavailable,
+            detail: e.message)
+        rescue Ace::Runtime::Error => e
+          RouteResult.new(route: @route_name, adapter: "terminal", status: :failed,
+            detail: e.message)
+        end
+
+        private
+
+        # The recipient's panel names the target pane, but only when the
+        # recipient lives on this route's machine (route `machine`,
+        # defaulting to hitl.machine) — a same-named pane on another
+        # machine is not the recipient. Without a recipient (legacy
+        # local-only events) the route's configured pane is used.
+        def target_pane(recipient)
+          return @pane if recipient.nil?
+          return nil unless recipient["machine"] == @machine
+
+          panel = recipient["panel"].to_s
+          panel.empty? ? nil : panel
+        end
+      end
+    end
+  end
+end
+
+Ace::Hitl::Adapters.register(:terminal, ->(route) { Ace::Hitl::Adapters::TerminalAdapter.new(route) })

data/lib/ace/hitl/adapters.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "adapters/registry"
+
+module Ace
+  module Hitl
+    # Duck-typed HITL delivery-adapter registry (mirrors Ace::Runtime).
+    #
+    # Adapter contract (transport translation only — never role rules):
+    #
+    #   Ace::Hitl::Adapters.register(:name, ->(route) { adapter })
+    #   adapter.deliver(event:, text:, recipient:, reply_to:)
+    #     -> Adapters::RouteResult(route:, adapter:, status:, detail:)
+    #   status: :delivered | :failed | :unavailable
+    #
+    # `text` is the shared rendering from Atoms::HitlEventText — identical
+    # for every adapter. `recipient`/`reply_to` are the address hashes from
+    # the event (nil for legacy local-only events). A route delivers only
+    # to its own configured destination and never reroutes on any status.
+    #
+    # Adapter packages ship a lib/ace/hitl/adapters/<name>.rb entrypoint
+    # that calls Adapters.register; it is loaded lazily on first resolve,
+    # so a future adapter (e.g. nervus) needs no ace-hitl change.
+    module Adapters
+      class Error < StandardError; end
+
+      # Unknown adapter name; carries the requested name and the sorted
+      # list of currently available adapters.
+      class UnknownAdapterError < Error
+        attr_reader :requested, :available
+
+        def initialize(requested:, available:)
+          @requested = requested
+          @available = available
+          super("unknown HITL adapter '#{requested}' (available: #{available.sort.join(", ")})")
+        end
+      end
+
+      # Per-route delivery outcome. `detail` is a human-readable,
+      # single-line explanation (may be nil for a plain success).
+      RouteResult = Struct.new(:route, :adapter, :status, :detail, keyword_init: true) do
+        def delivered?
+          status == :delivered
+        end
+      end
+
+      class << self
+        def register(name, factory = nil, &block)
+          registry.register(name, factory, &block)
+        end
+
+        def registry
+          @registry ||= Registry.new
+        end
+
+        # Resetting re-registers the built-in adapters: a plain Registry.new
+        # would permanently lose :terminal (the entrypoint require is a
+        # no-op once loaded), breaking registry-level resolution in tests
+        # and long-lived processes.
+        def reset_registry!
+          @registry = Registry.new
+          register(:terminal, ->(route) { TerminalAdapter.new(route) })
+          nil
+        end
+
+        def available
+          registry.available
+        end
+
+        def registered?(name)
+          registry.registered?(name)
+        end
+
+        def resolve(name, route: {})
+          registry.resolve(name, route: route)
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/atoms/hitl_address.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Atoms
+      # Pure recipient/reply address validation and formatting. No IO.
+      #
+      # Two forms (program contract 8xg.t.sbz.1.1):
+      # - folder: machine + events folder + case id (id stamped at create)
+      # - panel:  machine + panel
+      # Display strings align with the hermes <machine>/<name>/<id> shape.
+      class HitlAddress
+        TOKEN_PATTERN = /\A[a-z0-9][a-z0-9_-]*\z/i.freeze
+        PANEL_PATTERN = /\A[a-z0-9][a-z0-9_:-]{0,127}\z/i.freeze
+
+        class InvalidAddress < StandardError; end
+
+        # @param hash [Hash] symbol or string keys: machine, folder/panel, id
+        # @return [Hash] validated string-keyed address
+        # @raise [InvalidAddress] with an actionable message
+        def self.validate!(hash)
+          raise InvalidAddress, "address must be a mapping" unless hash.is_a?(Hash)
+
+          machine = hash[:machine] || hash["machine"]
+          folder = hash[:folder] || hash["folder"]
+          panel = hash[:panel] || hash["panel"]
+          id = hash[:id] || hash["id"]
+
+          unless machine.to_s.match?(TOKEN_PATTERN)
+            raise InvalidAddress, "address machine '#{machine}' is not a valid token"
+          end
+
+          if folder.to_s.strip.empty? && panel.to_s.strip.empty?
+            raise InvalidAddress, "address needs exactly one of folder or panel"
+          end
+          unless folder.to_s.strip.empty? || panel.to_s.strip.empty?
+            raise InvalidAddress, "address cannot have both folder and panel"
+          end
+
+          address = {"machine" => machine.to_s}
+          unless folder.to_s.strip.empty?
+            folder = folder.to_s
+            if folder.split(File::SEPARATOR).include?("..")
+              raise InvalidAddress, "address folder '#{folder}' must not traverse outside its root"
+            end
+
+            address["folder"] = folder
+            if id && !id.to_s.empty?
+              address["id"] = id.to_s
+            end
+          else
+            unless panel.to_s.match?(PANEL_PATTERN)
+              raise InvalidAddress, "address panel '#{panel}' is not a valid terminal handle"
+            end
+
+            address["panel"] = panel.to_s
+          end
+
+          address
+        end
+
+        # @return [Boolean] true when the address carries an events folder
+        def self.folder_form?(address)
+          address.is_a?(Hash) && !address["folder"].to_s.empty?
+        end
+
+        # @return [Boolean] true when the address carries a panel
+        def self.panel_form?(address)
+          address.is_a?(Hash) && !address["panel"].to_s.empty?
+        end
+
+        # @return [String] canonical display form
+        def self.to_s(address)
+          return "" unless address.is_a?(Hash)
+
+          if folder_form?(address)
+            parts = [address["machine"], address["folder"]]
+            parts << address["id"] unless address["id"].to_s.empty?
+            parts.join("/")
+          elsif panel_form?(address)
+            "#{address["machine"]}/panel/#{address["panel"]}"
+          else
+            address["machine"].to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/atoms/hitl_event_text.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "hitl_address"
+
+module Ace
+  module Hitl
+    module Atoms
+      # Shared, adapter-independent rendering of a HITL event for delivery.
+      # Every route receives the identical text — the adapter translates
+      # transport, not role rules. Pure; no IO.
+      class HitlEventText
+        # @param event [Models::HitlEvent]
+        # @return [String] single rendered message body
+        def self.call(event)
+          lines = []
+          if event.report?
+            lines << "[HITL report #{event.result}] #{event.title} (case #{event.id})"
+            body_lines(event).each { |line| lines << line }
+          else
+            lines << "[HITL question] #{event.title} (case #{event.id})"
+            questions = event.questions.empty? ? ["(pending human input)"] : event.questions
+            questions.each { |q| lines << "Q: #{q}" }
+            if event.reply_to
+              lines << "Reply-To: #{HitlAddress.to_s(event.reply_to)}"
+            end
+          end
+
+          context_lines(event).each { |line| lines << line }
+          lines.join("\n")
+        end
+
+        # Report body = the `## Report` section the creator writes. The
+        # section boundary is the next `## ` heading; reports are created by
+        # HitlCreator with plain `- ` content lines only, so nothing is lost
+        # for creator-written reports (documented boundary).
+        def self.body_lines(event)
+          body = event.content.to_s
+          report_section = body.split(/^## Report\s*$/m, 2)[1].to_s
+          report_section = report_section.sub(/\A\n+/, "").split(/^## /m, 2)[0].to_s
+          lines = report_section.lines.map(&:strip).reject(&:empty?)
+          lines.empty? ? ["(no content)"] : lines
+        end
+
+        def self.context_lines(event)
+          lines = []
+          lines << "Task: #{event.metadata["task"]}" if event.metadata["task"].to_s.strip != ""
+          lines << "Assignment: #{event.metadata["assignment"]}" if event.metadata["assignment"].to_s.strip != ""
+          lines << "Step: #{event.metadata["step"]}" if event.metadata["step"].to_s.strip != ""
+          lines
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/create.rb

@@ -13,7 +13,12 @@ module Ace
 
           argument :title, required: false, desc: "HITL event title"
 
-          option :kind, type: :string, aliases: %w[-k], desc: "Kind: clarification, decision, approval"
+          option :kind, type: :string, aliases: %w[-k], desc: "Kind: clarification, decision, approval (questions only)"
+          option :type, type: :string, aliases: %w[-t], desc: "Type: question (default), report"
+          option :result, type: :string, desc: "Report result: success, error (reports only)"
+          option :to, type: :string, desc: "Configured recipient name (machine+folder+ID or machine+panel)"
+          option :body, type: :string, repeat: true, aliases: %w[-b], desc: "Report content line (repeatable, reports only)"
+          option :task, type: :string, desc: "Task reference"
           option :question, type: :string, repeat: true, aliases: %w[-Q], desc: "Question line (repeatable)"
           option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
           option :assignment, type: :string, desc: "Assignment reference"
@@ -34,25 +39,50 @@ module Ace
             kind = options[:kind]
             validate_kind!(kind) if kind
 
+            type = options[:type]
+            validate_type!(type) if type
+
             questions = Array(options[:question]).map(&:strip).reject(&:empty?)
+            body = Array(options[:body]).map(&:strip).reject(&:empty?)
+            result = options[:result]
+            validate_combinations!(type, result: result, body: body, questions: questions,
+              resume: options[:resume], kind: kind)
+            validate_result!(result) if result
+
             tags = parse_tags(options[:tags])
 
             manager = Ace::Hitl::Organisms::HitlManager.new
-            event = manager.create(
-              title,
-              kind: kind,
-              questions: questions,
-              tags: tags,
-              assignment: options[:assignment],
-              step: options[:step],
-              step_name: options[:"step-name"],
-              resume_instructions: options[:resume],
-              move_to: options[:"move-to"]
-            )
+            event = begin
+              manager.create(
+                title,
+                to: options[:to],
+                kind: kind,
+                type: type,
+                result: result,
+                task: options[:task],
+                body: body,
+                questions: questions,
+                tags: tags,
+                assignment: options[:assignment],
+                step: options[:step],
+                step_name: options[:"step-name"],
+                resume_instructions: options[:resume],
+                move_to: options[:"move-to"]
+              )
+            rescue Ace::Hitl::Molecules::HitlAddressResolver::UnknownRecipientError,
+              Ace::Hitl::Molecules::HitlAddressResolver::InvalidAddressError => e
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
 
             folder_info = event.special_folder ? " (#{event.special_folder})" : ""
             puts "HITL event created: #{event.id} #{event.title}#{folder_info}"
             puts "  Path: #{event.file_path}"
+            if event.recipient
+              puts "  Recipient: #{Atoms::HitlAddress.to_s(event.recipient)}"
+            end
+            if event.reply_to
+              puts "  Reply-To: #{Atoms::HitlAddress.to_s(event.reply_to)}"
+            end
           end
 
           private
@@ -64,6 +94,45 @@ module Ace
             raise Ace::Support::Cli::Error.new("Invalid kind '#{kind}'. Allowed: #{allowed.join(", ")}")
           end
 
+          def validate_type!(type)
+            allowed = %w[question report]
+            return if allowed.include?(type)
+
+            raise Ace::Support::Cli::Error.new("Invalid type '#{type}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def validate_result!(result)
+            allowed = %w[success error]
+            return if allowed.include?(result)
+
+            raise Ace::Support::Cli::Error.new("Invalid result '#{result}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def validate_combinations!(type, result:, body:, questions:, resume:, kind: nil)
+            report = type == "report"
+            if report
+              unless result
+                raise Ace::Support::Cli::Error.new("--type report requires --result success|error")
+              end
+              if questions.any?
+                raise Ace::Support::Cli::Error.new("--question cannot be combined with --type report; use --body lines")
+              end
+              if resume
+                raise Ace::Support::Cli::Error.new("--resume cannot be combined with --type report; reports do not resume")
+              end
+              if kind
+                raise Ace::Support::Cli::Error.new("--kind cannot be combined with --type report; kinds apply to questions only")
+              end
+            else
+              if result
+                raise Ace::Support::Cli::Error.new("--result is only valid with --type report")
+              end
+              if body.any?
+                raise Ace::Support::Cli::Error.new("--body is only valid with --type report")
+              end
+            end
+          end
+
           def parse_tags(raw)
             return [] unless raw
 

data/lib/ace/hitl/cli/commands/lifecycle_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../providers/lab"
 
 module Ace
   module Hitl
@@ -13,17 +14,10 @@ module Ace
         # are one JSON line, byte-compatible with the migrated CLI
         # contract.
         module LifecycleCommand
-          STDIN_READER = ->(limit) { $stdin.read(limit) }.freeze
-
           def lifecycle_client
             Providers::Lab.boundary_client
           end
 
-          def overseer
-            channel_root = ENV.fetch("ACE_HITL_OVERSEER_CHANNEL_ROOT", "/lab/state/overseer-channel")
-            Lifecycle::Overseer.new(outbox_dir: File.join(channel_root, "outbox"))
-          end
-
           def emit(result)
             puts JSON.generate(result)
           end

data/lib/ace/hitl/cli/commands/list.rb

@@ -14,6 +14,8 @@ module Ace
 
           option :status, type: :string, aliases: %w[-s], desc: "Filter by status"
           option :kind, type: :string, aliases: %w[-k], desc: "Filter by kind"
+          option :type, type: :string, desc: "Filter by type (question, report)"
+          option :delivery, type: :string, desc: "Filter by delivery state (undelivered, delivered)"
           option :tags, type: :string, aliases: %w[-T], desc: "Filter by tags (comma-separated)"
           option :in, type: :string, aliases: %w[-i], desc: "Folder filter (next, all, archive)"
           option :scope, type: :string, desc: "Scope (current, all)"
@@ -26,11 +28,16 @@ module Ace
             scope = validate_scope(options[:scope])
             status = options[:status]
             kind = options[:kind]
+            type = options[:type]
+            validate_type!(type) if type
+            delivery = options[:delivery]
+            validate_delivery!(delivery) if delivery
             tags = parse_tags(options[:tags])
             in_folder = options[:in] || "next"
 
             manager = Ace::Hitl::Organisms::HitlManager.new
-            events = manager.list(status: status, kind: kind, tags: tags, in_folder: in_folder, scope: scope)
+            events = manager.list(status: status, kind: kind, type: type, delivery: delivery,
+              tags: tags, in_folder: in_folder, scope: scope)
 
             puts Ace::Hitl::Molecules::HitlDisplayFormatter.format_list(
               events,
@@ -47,6 +54,20 @@ module Ace
             raw.split(",").map(&:strip).reject(&:empty?)
           end
 
+          def validate_type!(type)
+            allowed = %w[question report]
+            return if allowed.include?(type)
+
+            raise Ace::Support::Cli::Error.new("Invalid type '#{type}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def validate_delivery!(delivery)
+            allowed = %w[undelivered delivered]
+            return if allowed.include?(delivery)
+
+            raise Ace::Support::Cli::Error.new("Invalid delivery filter '#{delivery}'. Allowed: #{allowed.join(", ")}")
+          end
+
           def validate_scope(raw_scope)
             return nil if raw_scope.nil?