ace-hitl 0.23.2 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 973228979e65843573a7dc67bc91566a22478ca762f3751babdbd269e0960ca9
-  data.tar.gz: c4b09f84c60c2bfb225294d56c4bfa4abded7ced7ecc75fe830ecc8987e239ee
+  metadata.gz: 066770bf07c22e97f6d1571d8d7697a9681df2872102b9454e26dc934d494162
+  data.tar.gz: 398b6537945687a92f34a0284d9e687f7b41cfea777352c9b7046a07ef45cd9a
 SHA512:
-  metadata.gz: f08442f7582db2b088cbaa5f0af24d9d81bc7caccdf5e2bdfc9de5feb6a9ee9f5125f541f02e9585f4921933fa08a712fe47e80e8c668dd89330084654e13984
-  data.tar.gz: c3ad787393cc3c045efda84016b9e2783fa8fb5f3696e4a9da9e072840dfb99e12f706c79bafc6b655f90f4ccd35f661d0f3b05932a96d00d17ed563a63b27c1
+  metadata.gz: cb37ecff31019de3e8007964a8631e9f8e33c7dd5ba4be5505b84a4172c030e7eadf4580e8e70b962b8d26942a4b1a6221ed9a7641adb8726e4dce408b11c734
+  data.tar.gz: a7ecb1759adaa8e6ae5dae068eb556bc0f094cd905a11b12f30f1f1bd6012ea61f68487eeeddf48298ee92de212b7b5c57c893e371a2234b20b9ca18f1475035

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-10-23
+
+### Added
+
+- Add read-only semantic event observations with configured-owner filtering; exclude delivery metadata and unrelated recipients.
+
 ## [0.23.2] - 2026-10-20
 
 ### Fixed

data/README.md

@@ -78,3 +78,15 @@ bin/ace-test ace-hitl all
 `ace-hitl` owns HITL event semantics and the markdown contract.
 `ace-support-items` remains generic support infrastructure and does not absorb
 HITL-specific behaviour.
+
+### Read semantic event revisions
+
+`ace-hitl observe --scope current --limit 500` prints one JSON object with schema
+`ace.hitl.observation/v1` and a bounded `events` list. `--scope all` includes linked
+worktrees of this repository. Each row contains a hashed canonical file identity,
+event ID, semantic revision hash, type/status and task/assignment references.
+It emits no private message or answer text. It reads active (non-special-folder) canonical events and
+does not import transports, acknowledge, archive, resume or mutate events.
+Delivery/poll timestamps and filesystem mtime are excluded from revisions;
+content, answers and report/status changes are included. Exceeding the configured
+limit refuses the entire projection rather than silently truncating it.

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+require "ace/support/cli"
+require_relative "../../molecules/event_observation"
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Observe < Ace::Support::Cli::Command
+          desc "Read bounded semantic event revisions without private message text"
+          option :scope, type: :string, default: "current", desc: "current or all linked worktrees"
+          option :owner, type: :string, desc: "Configured recipient owning incoming events"
+          option :limit, type: :integer, default: 500, desc: "Maximum event count (1..2000)"
+          def call(**options)
+            scope = options[:scope] || "current"
+            raise Ace::Support::Cli::Error, "invalid scope" unless %w[current all].include?(scope)
+            puts JSON.generate(Molecules::EventObservation.new.call(scope: scope, limit: options[:limit] || 500, owner: options[:owner]))
+          rescue ArgumentError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli.rb

@@ -8,6 +8,7 @@ require_relative "cli/commands/operator_question"
 require_relative "cli/commands/read"
 require_relative "cli/commands/show"
 require_relative "cli/commands/list"
+require_relative "cli/commands/observe"
 require_relative "cli/commands/update"
 require_relative "cli/commands/wait"
 require_relative "cli/commands/deliver"
@@ -31,6 +32,7 @@ module Ace
         ["read", "Read authenticated lifecycle request facts"],
         ["show", "Show HITL event details"],
         ["list", "List HITL events"],
+        ["observe", "Read semantic event revisions"],
         ["update", "Update HITL event metadata or answer"],
         ["send", "Send a HITL event through the configured adapter routes"],
         ["wait", "Wait for an answer on a specific HITL event"],
@@ -58,6 +60,7 @@ module Ace
       register "read", CLI::Commands::Read
       register "show", CLI::Commands::Show
       register "list", CLI::Commands::List
+      register "observe", CLI::Commands::Observe
       register "update", CLI::Commands::Update
       register "send", CLI::Commands::Send
       register "wait", CLI::Commands::Wait

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+require "digest"
+require "json"
+
+module Ace
+  module Hitl
+    module Molecules
+      # Read-only semantic projection. No private text is emitted; delivery
+      # timestamps, filesystem metadata and observer acknowledgements are not
+      # decision changes. Canonical HITL remains the only event owner.
+      class EventObservation
+        def initialize(manager: Organisms::HitlManager.new)
+          @manager = manager
+        end
+
+        def call(scope: "current", limit: 500, owner: nil)
+          raise ArgumentError, "invalid observation limit" unless (1..2000).cover?(limit)
+          events = @manager.list(in_folder: "next", scope: scope, limit: limit, strict: true)
+          raise ArgumentError, "observation exceeds configured event budget" if events.size > limit
+          address = owner && Molecules::HitlAddressResolver.new(config: @manager.config).resolve(owner)
+          events = events.select { |event| incoming?(event, address) } if address
+          rows = events.map do |event|
+            semantic = [event.id, event.type, event.status, event.result, event.kind,
+              event.title, event.content, event.answer, event.questions,
+              Array(event.tags).sort, canonical(event.recipient), canonical(event.reply_to),
+              event.metadata.values_at("task", "assignment", "step", "step_name", "resume_instructions")]
+            {"key" => Digest::SHA256.hexdigest(event.file_path.to_s),
+             "id" => event.id, "revision" => Digest::SHA256.hexdigest(JSON.generate(canonical(semantic))),
+             "type" => event.type, "status" => event.status, "result" => event.result,
+             "task" => event.metadata["task"], "assignment" => event.metadata["assignment"]}
+          end
+          {"schema" => "ace.hitl.observation/v1", "events" => rows.sort_by { |row| row["key"] }}
+        end
+
+        private
+
+        # Questions created locally are outbound until actually answered. A
+        # worker's reply belongs to that worker, not every linked-worktree actor.
+        # Native instructions have no recipient; their explicit import root owns them.
+        def incoming?(event, address)
+          local = File.expand_path(event.file_path).start_with?(File.expand_path(@manager.root_dir) + File::SEPARATOR)
+          return local if Array(event.tags).include?("hermes-instruction")
+          if event.question? && event.answered?
+            return local && event.reply_to &&
+              event.reply_to["machine"] == @manager.config.dig("hitl", "machine") &&
+              File.expand_path(event.reply_to["folder"].to_s) == File.expand_path(@manager.root_dir)
+          end
+          recipient = event.recipient
+          recipient && address.all? { |key, value| recipient[key] == value }
+        end
+
+        def canonical(value)
+          case value
+          when Hash then value.sort.to_h.transform_values { |item| canonical(item) }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -94,10 +94,12 @@ module Ace
           }
         end
 
-        def list(status: nil, kind: nil, type: nil, delivery: nil, in_folder: "next", tags: [], scope: nil)
+        def list(status: nil, kind: nil, type: nil, delivery: nil, in_folder: "next", tags: [], scope: nil, limit: nil, strict: false)
           effective_scope = @scope_resolver.effective_scope(scope)
           scan_results = scan_results_for_scope(effective_scope, in_folder: in_folder)
+          raise ArgumentError, "observation exceeds configured event budget" if limit && scan_results.size > limit
           events = load_events(scan_results)
+          raise ArgumentError, "incomplete HITL observation" if strict && events.size != scan_results.size
 
           events = events.select { |event| event.status == status } if status
           events = events.select { |event| event.kind == kind } if kind

data/lib/ace/hitl/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl
 version: !ruby/object:Gem::Version
-  version: 0.23.2
+  version: 0.24.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-hitl-contract
@@ -160,6 +160,7 @@ files:
 - lib/ace/hitl/cli/commands/duty.rb
 - lib/ace/hitl/cli/commands/lifecycle_command.rb
 - lib/ace/hitl/cli/commands/list.rb
+- lib/ace/hitl/cli/commands/observe.rb
 - lib/ace/hitl/cli/commands/operator_question.rb
 - lib/ace/hitl/cli/commands/pending.rb
 - lib/ace/hitl/cli/commands/read.rb
@@ -198,6 +199,7 @@ files:
 - lib/ace/hitl/lifecycle/tls_service.rb
 - lib/ace/hitl/live_client.rb
 - lib/ace/hitl/models/hitl_event.rb
+- lib/ace/hitl/molecules/event_observation.rb
 - lib/ace/hitl/molecules/hitl_address_resolver.rb
 - lib/ace/hitl/molecules/hitl_answer_editor.rb
 - lib/ace/hitl/molecules/hitl_config_loader.rb