ace-hitl 0.24.0 → 0.24.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066770bf07c22e97f6d1571d8d7697a9681df2872102b9454e26dc934d494162
-  data.tar.gz: 398b6537945687a92f34a0284d9e687f7b41cfea777352c9b7046a07ef45cd9a
+  metadata.gz: 18d85dc5d580a07b84780113776f166ded716932248787002ada4f483113b468
+  data.tar.gz: 1744b1e6259e9b19cf17e4f184d54be65494b6221462f46afc421c8f8e953f68
 SHA512:
-  metadata.gz: cb37ecff31019de3e8007964a8631e9f8e33c7dd5ba4be5505b84a4172c030e7eadf4580e8e70b962b8d26942a4b1a6221ed9a7641adb8726e4dce408b11c734
-  data.tar.gz: a7ecb1759adaa8e6ae5dae068eb556bc0f094cd905a11b12f30f1f1bd6012ea61f68487eeeddf48298ee92de212b7b5c57c893e371a2234b20b9ca18f1475035
+  metadata.gz: 6e37a7a6c0b60ac6a7b91b3059548de70d0966ff775175f5044f7e220fe1e498268bad443a8c3d5ef3c82e93cdf2dbb7865a047024e4d1cf0e1d46465dc9a21c
+  data.tar.gz: c48874a7f7e4177e54b358f31e1e4b3660d08165cc4f194613d8a8dbca45ccf6e47a4fc6e5f212ab9379dbcb1a9aaa426a80812576134f516014d47f979daacb

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.2] - 2026-10-27
+
+### Added
+
+- Add the one-turn `ask` command: create + send the question through the configured route, auto-arm the asking agent's own answer wake (ace.wake.ask/v1 request delivered through the ace-wake bridge), print the bare case id as the final stdout line, and end the turn — never block, never poll, no asker-side timeouts; undelivered routes exit 1 before any wake request is dropped, and `ask` completes on accepted-queued frames.
+
+### Changed
+
+- Formalize route recipients as first-class ordered data in the route loader.
+
+## [0.24.1] - 2026-10-25
+
+### Changed
+
+- Replace wait-by-polling with the semantic wake contract in the HITL workflow (PR74): one scoped watch per pending answer, end the turn, reconcile on wake.
+
 ## [0.24.0] - 2026-10-23
 
 ### Added

data/docs/usage.md

@@ -159,7 +159,10 @@ hitl:
   adapters:
     routes:
       - route: overseer-terminal   # display name; defaults to the adapter name
-        recipients: [overseer]     # configured names resolved to the stored destination
+        recipients: [overseer]     # ordered: configured names, primary first;
+                                   # resolved to the stored destination before
+                                   # any adapter runs; appending a name extends
+                                   # coverage with zero code change
         adapter: terminal          # built-in: any ace-runtime terminal
         runtime: herdr             # tmux | herdr
         pane: p5                   # opaque pane handle (runtime-owned)
@@ -304,6 +307,38 @@ ace-hitl wait abc123 --scope current
 The default wait is indefinite; a positive `--timeout` bounds only this call
 and never expires the request. `wait` never invents an answer.
 
+## Ask
+
+One-turn ask: create the question, send it through the configured routes,
+arm the asking agent's own wake for the case answer, and END THE TURN. ask
+glues `create` + `send` + wake-arming into one command for the common case
+where asking is the last action of a turn:
+
+```bash
+ace-hitl ask "Continue with batch 2?" --to captain --kind approval --question "Proceed?"
+ace-hitl ask "Auth strategy?" --to overseer --task 8xg.t.sbz.1.1
+```
+
+```
+HITL event created: 8xhkep Continue with batch 2?
+HITL event 8xhkep sent through 1 route(s):
+  captain (hermes_native): delivered - native transport ...
+8xhkep
+```
+
+The final stdout line is always the bare case id. ask never blocks and never
+polls, carries no urgency language, and has no asker-side timeouts — the
+Captain replies whenever he wants. The answer is delivered TO the agent as
+an ace-wake wake carrying the answer content (see the ace-wake README's ask
+bridge contract); on wake, the agent acts immediately.
+
+Exit 0 when the question was created, the routes accepted the frame, and
+the wake was armed — including the native-style accepted-queued case (a
+stderr warning notes that delivery is unconfirmed; confirmation is
+asynchronous). Exit 1 only for genuine rejects (a route refusing the
+frame, or a concrete configuration error); no wake request is dropped for
+a rejected ask.
+
 ## Lifecycle event names
 
 HITL lifecycle signals use this namespace:

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-10-18'
-  last-checked: '2026-10-18'
+  last-updated: '2026-10-23'
+  last-checked: '2026-10-23'
 ---
 
 # HITL Workflow
@@ -98,11 +98,19 @@ ace-hitl show <hitl-id>
 ace-hitl update <hitl-id> --answer "<human decision>"
 ```
 
-Polling is the default reliability path for the requesting agent:
-
-```bash
-ace-hitl wait <hitl-id>
-```
+Waiting on a pending answer is semantic, never a blocking poll. While an
+answer is pending (for example a RubyGems OTP window of ~30–45 s), the
+waiting session registers exactly ONE in-process `/watch` scoped to the
+project ace-hitl transport folder (the folder holding that case's
+request/reply files, e.g. `.ace-local/hitl`), then ends its turn. On wake:
+run the project `ace-hitl-hermes sync` ONCE, reconcile the exact case state
+(`ace-hitl show <hitl-id>` — answered, not merely replies>0), and act within
+the answer window or report the precise blocker. Never block a model turn
+with sleep/poll loops (`ace-hitl wait` blocks the turn — it is a sleep/poll
+command, not a waiting strategy), and never introduce cron, systemd, or any
+external heartbeat — none exists and none may be added. Observed defect
+(eyes-20261023 OTP wait): the supervising session blocked its turn with a
+36x sleep-8 poll loop.
 
 ### 4b) Remote delivery through configured adapter routes
 

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+require "ace/support/cli"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # One-turn ask: create the question, deliver it through the configured
+        # adapter routes, arm the asking agent's own wake for the case answer,
+        # and END THE TURN. ask never blocks and never polls: the answer is
+        # delivered TO the agent as an ace-wake wake carrying the content, and
+        # the agent acts on it immediately. Asks carry no urgency language and
+        # no asker-side timeouts — the Captain replies whenever he wants.
+        class Ask < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          # Shared with ace-wake's ask bridge (wake/ask-bridge.js): the drop-file
+          # contract that arms the asking agent's scoped answer watch.
+          WAKE_REQUEST_SCHEMA = "ace.wake.ask/v1"
+
+          desc "Ask: create, send, arm the answer wake, and end the turn"
+
+          example [
+            "ask \"Continue with batch 2?\" --to captain --kind approval --question \"Proceed?\"",
+            "ask \"Auth strategy?\" --to overseer --task 8xg.t.sbz.1.1"
+          ]
+
+          argument :title, required: false, desc: "HITL event title"
+
+          option :to, type: :string, required: true, desc: "Configured recipient name (required)"
+          option :kind, type: :string, aliases: %w[-k], desc: "Kind: clarification, decision, approval"
+          option :question, type: :string, repeat: true, aliases: %w[-Q], desc: "Question line (repeatable)"
+          option :task, type: :string, desc: "Task reference"
+          option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(title: nil, **options)
+            unless title && !title.strip.empty?
+              raise Ace::Support::Cli::Error.new("Title required")
+            end
+
+            kind = options[:kind]
+            validate_kind!(kind) if kind
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            event = create_question(manager, title, options)
+            unless options[:quiet]
+              puts "HITL event created: #{event.id} #{event.title}"
+            end
+
+            deliver(event, options)
+            arm_wake(event, manager)
+            # The final stdout line is always the bare case id.
+            puts event.id
+          rescue Ace::Hitl::Molecules::HitlAddressResolver::UnknownRecipientError,
+            Ace::Hitl::Molecules::HitlAddressResolver::InvalidAddressError,
+            Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError,
+            Ace::Hitl::Adapters::Error,
+            Ace::Hitl::Molecules::HitlRouteLoader::NoRoutesError,
+            Ace::Hitl::Molecules::HitlRouteLoader::InvalidRouteError => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          private
+
+          def create_question(manager, title, options)
+            manager.create(
+              title,
+              to: options[:to],
+              kind: options[:kind],
+              type: "question",
+              task: options[:task],
+              questions: Array(options[:question]).map(&:strip).reject(&:empty?),
+              tags: parse_tags(options[:tags])
+            )
+          end
+
+          def deliver(event, options)
+            report = Organisms::HitlSender.new.send(event.id)
+            rejected = report.results.select { |result| result.status == :failed }
+            unless rejected.empty?
+              # A genuine reject (ContractError, unknown adapter): the frame
+              # never went through, so arming a wake would strand the ask.
+              detail = rejected.map { |result| "#{result.route}: #{result.detail}" }.join("; ")
+              raise Ace::Support::Cli::Error.new("HITL event '#{event.id}' rejected: #{detail}")
+            end
+            unless options[:quiet]
+              puts "HITL event #{report.event_id} sent through #{report.results.size} route(s):"
+              report.results.each do |result|
+                detail = result.detail ? " - #{result.detail}" : ""
+                puts "  #{result.route} (#{result.adapter}): #{result.status}#{detail}"
+              end
+            end
+            # Native-style transports accept first and confirm later: an
+            # ACCEPTED QUEUED frame is ask-complete. The answer wake fires
+            # whenever the transport confirms — delivered-later states are
+            # asynchronous, never an asker-side failure.
+            queued = report.results.select { |result| result.status == :unavailable }
+            unless queued.empty?
+              warn "ace-hitl: warning: delivery unconfirmed (queued on " \
+                "#{queued.map { |result| result.route }.join(", ")}); the answer wake fires when the transport delivers"
+            end
+          end
+
+          # Drop the wake request the ace-wake extension consumes through its
+          # own reconcile pass and turns into a scoped watch on the case file:
+          # when the answer lands, the wake carries the answer content. The
+          # atomic replace keeps the consumer from reading a torn request.
+          def arm_wake(event, manager)
+            requests_dir = File.join(File.expand_path(manager.root_dir), "wake-requests")
+            FileUtils.mkdir_p(requests_dir)
+            request = {
+              "schema" => WAKE_REQUEST_SCHEMA,
+              "kind" => "ask",
+              "case_id" => event.id,
+              "case_path" => File.expand_path(event.file_path)
+            }
+            temporary = File.join(requests_dir, ".#{event.id}-#{SecureRandom.hex(8)}.tmp")
+            final = File.join(requests_dir, "#{event.id}.json")
+            File.write(temporary, JSON.generate(request))
+            File.rename(temporary, final)
+            final
+          ensure
+            File.unlink(temporary) if temporary && File.exist?(temporary)
+          end
+
+          def validate_kind!(kind)
+            allowed = %w[clarification decision approval]
+            return if allowed.include?(kind)
+
+            raise Ace::Support::Cli::Error.new("Invalid kind '#{kind}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def parse_tags(raw)
+            return [] unless raw
+
+            raw.split(",").map(&:strip).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli.rb

@@ -3,6 +3,7 @@
 require "ace/support/cli"
 require_relative "../hitl/version"
 require_relative "cli/commands/create"
+require_relative "cli/commands/ask"
 require_relative "cli/commands/send"
 require_relative "cli/commands/operator_question"
 require_relative "cli/commands/read"
@@ -34,6 +35,7 @@ module Ace
         ["list", "List HITL events"],
         ["observe", "Read semantic event revisions"],
         ["update", "Update HITL event metadata or answer"],
+        ["ask", "Ask: create, send, arm the answer wake, and end the turn"],
         ["send", "Send a HITL event through the configured adapter routes"],
         ["wait", "Wait for an answer on a specific HITL event"],
         ["deliver", "Deliver an answer (stdin) to a pending HITL relay request"],
@@ -52,7 +54,9 @@ module Ace
         "ace-hitl create \"Work done\" --type report --result success --task 8xg.t.sbz.1.0",
         "ace-hitl update abc123 --answer \"Use JWT with refresh tokens\"",
         "ace-hitl send 8xhkep",
-        "ace-hitl wait abc123 --poll-every 600 --timeout 14400"
+        "ace-hitl wait abc123 --poll-every 600 --timeout 14400",
+        "ace-hitl ask \"Continue?\" --to captain --kind approval --question \"Proceed?\"",
+        "ace-hitl ask \"Auth strategy?\" --to overseer --task 8xg.t.sbz.1.1"
       ].freeze
 
       register "create", CLI::Commands::Create
@@ -62,6 +66,7 @@ module Ace
       register "list", CLI::Commands::List
       register "observe", CLI::Commands::Observe
       register "update", CLI::Commands::Update
+      register "ask", CLI::Commands::Ask
       register "send", CLI::Commands::Send
       register "wait", CLI::Commands::Wait
       register "deliver", CLI::Commands::Deliver

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

@@ -20,6 +20,15 @@ module Ace
         # single path segment (no dots).
         ROUTE_NAME_PATTERN = /\A[a-z0-9][a-z0-9_-]*\z/i.freeze
 
+        # A route's `recipients` list is first-class ORDERED data: each entry
+        # is a configured recipient name, position is meaningful (primary
+        # first), and the loader preserves the list verbatim — never
+        # reordered, never deduped. Selection matches an event addressed to
+        # ANY listed name, so extending coverage (a second-captain entry
+        # tomorrow) is a configuration change only: add the name under
+        # `hitl.recipients` and append it to the route's list. Duplicates
+        # carry no order meaning and are rejected as invalid.
+
         # @param config [Hash] merged hitl namespace config
         # @return [Array<Hash>] validated string-keyed routes
         # @raise [NoRoutesError, InvalidRouteError]
@@ -66,10 +75,19 @@ module Ace
 
           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"
+          if normalized.key?("recipients")
+            list = normalized["recipients"]
+            unless list.is_a?(Array) && !list.empty? && list.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
+            names = list.map(&:strip)
+            duplicates = names.tally.select { |_, count| count > 1 }.keys
+            unless duplicates.empty?
+              raise InvalidRouteError,
+                "route '#{route}' recipients list repeats #{duplicates.join(", ")}: recipients are ordered data " \
+                "and must list each configured name once"
+            end
+            normalized["recipients"] = names
           end
           normalized
         end

data/lib/ace/hitl/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Hitl
-    VERSION = "0.24.0"
+    VERSION = "0.24.2"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.24.2
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract
@@ -153,6 +153,7 @@ files:
 - lib/ace/hitl/atoms/hitl_file_pattern.rb
 - lib/ace/hitl/atoms/hitl_id_formatter.rb
 - lib/ace/hitl/cli.rb
+- lib/ace/hitl/cli/commands/ask.rb
 - lib/ace/hitl/cli/commands/cancel.rb
 - lib/ace/hitl/cli/commands/consume.rb
 - lib/ace/hitl/cli/commands/create.rb