ace-herdr 0.1.0 → 0.3.0

data/lib/ace/herdr/molecules/herdr_executor.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require "json"
+require "timeout"
 
 module Ace
   module Herdr
@@ -12,6 +13,8 @@ module Ace
       # binary; tests substitute this class.
       class HerdrExecutor
         DEFAULT_BINARY = "herdr"
+        WAKE_OUTPUT_LIMIT = 65_536
+        DEFAULT_PROBE_TIMEOUT_S = 60
 
         def initialize(binary: DEFAULT_BINARY)
           @binary = binary
@@ -22,6 +25,28 @@ module Ace
           run!([@binary, "agent", "get", pane])
         end
 
+        # Structured live pane observation for the inbox: the caller holds
+        # its per-event lock across this probe, so a stalled herdr child is
+        # killed at the deadline and the timeout classifies as a retryable
+        # pre-submission failure.
+        def pane_get_bounded(pane, timeout_s: DEFAULT_PROBE_TIMEOUT_S)
+          result = BoundedProcess.call([@binary, "pane", "get", pane], stdin_data: "",
+            timeout_s: timeout_s, output_limit: WAKE_OUTPUT_LIMIT)
+          execution = ExecutionResult.new(
+            stdout: result.stdout.strip, stderr: result.stderr.strip,
+            success: result.status.success?, exit_code: result.status.exitstatus || -1
+          )
+          raise classify(execution, [@binary, "pane", "get", pane]) unless execution.success?
+
+          execution
+        rescue Timeout::Error
+          raise AgentNotReadyError, "pane probe timed out after #{timeout_s}s"
+        rescue BoundedProcess::PostLaunchError => e
+          raise AgentNotReadyError, "pane probe failed after launch: #{e.message}"
+        rescue SystemCallError
+          raise ExecutorUnavailableError, "herdr CLI not found or not executable: #{@binary}"
+        end
+
         # Start an agent in a pane at an interactive shell prompt.
         # Success means the agent was detected and is ready for input.
         def agent_start(name:, kind:, pane:, timeout_ms:)
@@ -35,6 +60,34 @@ module Ace
           run!([@binary, "agent", "prompt", pane, text])
         end
 
+        # A bounded, payload-free wake. The child deadline is managed by
+        # BoundedProcess (process-group kill), so a stalled process cannot
+        # keep the inbox event lock through Open3.capture3 cleanup.
+        def agent_prompt_bounded(pane:, text:, timeout_ms:)
+          cmd = [@binary, "agent", "prompt", pane, text]
+          result = BoundedProcess.call(cmd, stdin_data: "",
+            timeout_s: timeout_ms / 1000.0, output_limit: WAKE_OUTPUT_LIMIT)
+          execution = ExecutionResult.new(
+            stdout: result.stdout.strip, stderr: result.stderr.strip,
+            success: result.status.success?, exit_code: result.status.exitstatus || -1
+          )
+          unless execution.success?
+            error = classify(execution, cmd)
+            if result.oversized && error.is_a?(CommandError)
+              raise CommandError, "herdr wake output exceeded #{WAKE_OUTPUT_LIMIT} bytes (exit #{execution.exit_code})"
+            end
+            raise error
+          end
+
+          execution
+        rescue Timeout::Error
+          raise AgentNotReadyError, "herdr wake timed out after #{timeout_ms}ms"
+        rescue BoundedProcess::PostLaunchError => e
+          raise AgentNotReadyError, "herdr wake failed after launch: #{e.message}"
+        rescue SystemCallError => e
+          raise ExecutorUnavailableError, e.message
+        end
+
         # Wait until the agent reaches one of the requested states
         def agent_wait(pane:, until_states:, timeout_ms:)
           cmd = [@binary, "agent", "wait", pane]
@@ -60,6 +113,12 @@ module Ace
           run!([@binary, "pane", "current", "--current"])
         end
 
+        # Structured live pane observation; callers must verify all identity
+        # fields before using a native queue target.
+        def pane_get(pane)
+          run!([@binary, "pane", "get", pane])
+        end
+
         # Inspect a pane's processes (positive proof of process exit for tidy)
         def pane_process_info(pane)
           run!([@binary, "pane", "process-info", "--pane", pane])
@@ -73,6 +132,18 @@ module Ace
           run!(cmd)
         end
 
+        def tab_get(tab)
+          run!([@binary, "tab", "get", tab])
+        end
+
+        def tab_focus(tab)
+          run!([@binary, "tab", "focus", tab])
+        end
+
+        def api_snapshot
+          run!([@binary, "api", "snapshot"])
+        end
+
         # --- terminal-control surface (spec 8wq.t.k84) -----------------------
 
         # List workspaces (tmux sessions analogue)
@@ -181,8 +252,8 @@ module Ace
             stdout: stdout.strip, stderr: stderr.strip,
             success: status.success?, exit_code: status.exitstatus || -1
           )
-        rescue Errno::ENOENT
-          raise ExecutorUnavailableError, "herdr CLI not found on PATH: #{@binary}"
+        rescue SystemCallError
+          raise ExecutorUnavailableError, "herdr CLI not found or not executable: #{@binary}"
         end
 
         def run_raw_stdout(cmd)
@@ -191,8 +262,8 @@ module Ace
             stdout: stdout, stderr: stderr.strip,
             success: status.success?, exit_code: status.exitstatus || -1
           )
-        rescue Errno::ENOENT
-          raise ExecutorUnavailableError, "herdr CLI not found on PATH: #{@binary}"
+        rescue SystemCallError
+          raise ExecutorUnavailableError, "herdr CLI not found or not executable: #{@binary}"
         end
 
         # Map a failed result to a typed error from herdr's error codes
@@ -200,6 +271,25 @@ module Ace
         # code is kept in the message so CLI failures carry it.
         def classify(result, cmd)
           code, message = error_code(result)
+          if code
+            return classify_code(code, message, result: result, cmd: cmd)
+          end
+
+          # No structured code: first nonempty of stderr/stdout — herdr
+          # writes some failures (socket errors) to stdout with an empty
+          # stderr, and empty strings are truthy in Ruby, so `||` chaining
+          # would hide the detail.
+          detail = [result.stderr, result.stdout].reject { |value| value.to_s.empty? }.first
+          if detail.to_s.match?(/no herdr server is running|cannot connect|connection refused|socket.*unavailable/i)
+            return ExecutorUnavailableError.new(detail)
+          end
+
+          CommandError.new(
+            "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")} #{detail}".strip
+          )
+        end
+
+        def classify_code(code, message, result:, cmd:)
           case code
           when "agent_blocked" then AgentBlockedError.new(tag_code(code, message))
           when "agent_prompt_stalled" then AgentNotReadyError.new(tag_code(code, message))
@@ -207,11 +297,10 @@ module Ace
           when "agent_not_found" then AgentNotFoundError.new(tag_code(code, message))
           when "tab_not_found" then TabNotFoundError.new(tag_code(code, message))
           when "workspace_not_found" then WorkspaceNotFoundError.new(tag_code(code, message))
-          when "timeout" then AgentNotReadyError.new(tag_code(code, message))
+          when "timeout" then ExecutorTimeoutError.new(tag_code(code, message))
           else
             CommandError.new(
-              "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")} " \
-              "#{message || result.stderr}".strip
+              "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")}: #{tag_code(code, message)}"
             )
           end
         end

data/lib/ace/herdr/molecules/native_queue_executor.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ace
+  module Herdr
+    module Molecules
+      # The provider-native submission boundary. A failed process does not
+      # prove that a message was not accepted, so only validation failures
+      # raised before this boundary are retryable without reconciliation.
+      #
+      # Child processes run under BoundedProcess: the deadline is enforced at
+      # the child boundary (process-group kill), never via a cleanup-blocking
+      # Timeout.timeout around capture3, so a stalled child cannot hold the
+      # inbox event lock past the configured timeout.
+      class NativeQueueExecutor
+        DEFAULT_SUBMIT_TIMEOUT_S = 60
+        DEFAULT_IDENTITY_TIMEOUT_S = 20
+        # Codex payloads ride in argv; a single argument beyond the OS
+        # per-argument limit fails at exec with E2BIG — before any client
+        # code ran — so the payload is bounded pre-launch and any E2BIG
+        # escape is classified as a proven pre-submission rejection.
+        MAX_ARG_PAYLOAD_BYTES = 65_536
+        PI_PAYLOAD_LIMIT_BYTES = 65_536
+
+        # runner: test seam. Callable (argv, stdin_data:, timeout_s:) ->
+        # [stdout, stderr, status]. Defaults to the bounded runner.
+        def initialize(codex: "codex", pi_client: nil, runner: nil,
+          submit_timeout_s: DEFAULT_SUBMIT_TIMEOUT_S,
+          identity_timeout_s: DEFAULT_IDENTITY_TIMEOUT_S)
+          @codex = codex
+          @pi_client = pi_client || ENV["ACE_HERDR_PI_QUEUE_CLIENT"] || "pi-overseer-queue-client"
+          @runner = runner
+          @submit_timeout_s = submit_timeout_s
+          @identity_timeout_s = identity_timeout_s
+        end
+
+        def pi_identity
+          result = execute([@pi_client, "--identity"], stdin_data: "",
+            timeout_s: @identity_timeout_s)
+          raise ExecutorError, "Pi identity probe failed: #{result.stderr}" unless result.status.success?
+
+          identity = JSON.parse(result.stdout)
+          raise ExecutorError, "Pi identity probe returned invalid JSON" unless identity.is_a?(Hash)
+
+          identity.fetch("session_id")
+        rescue Errno::ENOENT, Errno::EACCES => e
+          raise ExecutorUnavailableError, e.message
+        rescue JSON::ParserError, KeyError, TypeError
+          raise ExecutorError, "Pi identity probe returned invalid JSON"
+        rescue Timeout::Error
+          raise ExecutorError, "Pi identity probe timed out"
+        end
+
+        def submit(agent:, thread:, event_id:, digest:, payload:)
+          if agent == "pi" && (payload.empty? || payload.bytesize > PI_PAYLOAD_LIMIT_BYTES)
+            return {"accepted" => false, "pre_submit" => true, "error" => "Pi payload must be 1..65536 bytes"}
+          end
+          if agent == "codex" && payload.bytesize > MAX_ARG_PAYLOAD_BYTES
+            return {"accepted" => false, "pre_submit" => true,
+                    "error" => "Codex payload must be at most #{MAX_ARG_PAYLOAD_BYTES} bytes for argv delivery"}
+          end
+          argv = if agent == "codex"
+            [@codex, "queue", "--thread", thread, "--message", payload]
+          elsif agent == "pi"
+            [@pi_client, "--delivery", event_id, "--session-id", thread,
+              "--payload-sha256", digest, "--payload-bytes", payload.bytesize.to_s]
+          else
+            raise ValidationError, "unsupported native queue agent: #{agent}"
+          end
+          result = execute(argv, stdin_data: agent == "pi" ? payload : "",
+            timeout_s: @submit_timeout_s)
+          raise ExecutorError, "native queue output exceeded the retained limit" if result.oversized
+          unless result.status.success?
+            return {"accepted" => false, "exit_code" => result.status.exitstatus,
+                    "error" => result.stderr.strip}
+          end
+
+          if agent == "pi"
+            receipt = JSON.parse(result.stdout)
+            unless receipt.is_a?(Hash) && receipt["ok"] == true && receipt["id"] == event_id &&
+                receipt["session_id"] == thread && receipt["payload_sha256"] == digest
+              return {"accepted" => false, "error" => "Pi queue receipt identity or digest mismatch"}
+            end
+          end
+          {"accepted" => true, "exit_code" => result.status.exitstatus, "stdout" => result.stdout.strip}
+        rescue Errno::ENOENT, Errno::EACCES, Errno::E2BIG, ExecutorUnavailableError => e
+          # The executable never launched (or exec rejected the argv). No
+          # submission could have occurred, so this stays retryable.
+          {"accepted" => false, "pre_submit" => true, "error" => e.message}
+        rescue JSON::ParserError
+          {"accepted" => false, "error" => "Pi queue returned invalid receipt JSON"}
+        rescue Timeout::Error
+          {"accepted" => false, "error" => "native queue timed out after submission may have begun"}
+        end
+
+        private
+
+        def execute(argv, stdin_data:, timeout_s:)
+          if @runner
+            stdout, stderr, status = @runner.call(argv, stdin_data: stdin_data, timeout_s: timeout_s)
+            return BoundedProcess::Result.new(stdout, stderr, status, false)
+          end
+
+          BoundedProcess.call(argv, stdin_data: stdin_data, timeout_s: timeout_s)
+        rescue SystemCallError => e
+          # popen3 raises spawn failures before the child exists, so no
+          # submission can have begun: proven pre-launch, retryable.
+          # (Post-launch I/O failures arrive as PostLaunchError instead.)
+          raise ExecutorUnavailableError, e.message
+        rescue BoundedProcess::PostLaunchError => e
+          # The child was live, so the message may already have been accepted:
+          # keep this uncertain, never pre-submit retryable.
+          raise ExecutorError, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/organisms/control_surface.rb

@@ -146,9 +146,10 @@ module Ace
         # Create a tab from a preset (tmux `window` analogue) in the given
         # or resolved workspace; --cwd overrides the resolved tab cwd. The
         # layout is validated before the tab is created.
-        def create_tab(preset_name, workspace_id: nil, cwd: nil)
+        def create_tab(preset_name, workspace_id: nil, cwd: nil, label: nil)
           workspace_id = resolve_workspace_id(workspace_id)
           resolved = resolve_tab_preset(preset_name)
+          resolved = resolved.merge("label" => label) if label
           preflight_tab!(resolved)
           instantiate_tab(
             resolved, workspace_id: workspace_id,
@@ -248,13 +249,20 @@ module Ace
           tab_id = dig_value(tab_json, %w[result tab tab_id]) ||
             raise(TargetResolutionError, "could not read the new tab id from herdr tab create output")
 
-          pane_specs = Array(tab_spec["panes"])
-          root_pane_id = dig_value(tab_json, %w[result root_pane pane_id]) ||
-            raise(TargetResolutionError, "could not read the root pane id from herdr tab create output")
-          placed = place_panes(tab_spec, pane_specs, tab_cwd, root_pane_id)
-
-          commands = run_pane_commands(placed)
-          agents = start_pane_agents(placed, workspace_id: workspace_id)
+          begin
+            pane_specs = Array(tab_spec["panes"])
+            root_pane_id = dig_value(tab_json, %w[result root_pane pane_id]) ||
+              raise(TargetResolutionError, "could not read the root pane id from herdr tab create output")
+            placed = place_panes(tab_spec, pane_specs, tab_cwd, root_pane_id)
+
+            commands = run_pane_commands(placed)
+            agents = start_pane_agents(placed, workspace_id: workspace_id)
+          rescue StandardError => e
+            # Surface the created tab id and the original error class so
+            # the owner can roll back exactly this tab and keep
+            # mapping-relevant semantics (e.g. AgentBlockedError).
+            raise TabMaterializationError.new(tab_id: tab_id, message: "#{e.class}: #{e.message}")
+          end
 
           {
             tab: tab_id,
@@ -386,33 +394,13 @@ module Ace
         end
 
         def dig_value(json, path)
-          current = json
-          path.each do |key|
-            return nil unless current.is_a?(Hash)
-
-            current = current[key]
-          end
-          current.is_a?(String) && !current.empty? ? current : nil
+          Atoms::JsonFind.dig_value(json, path)
         end
 
-        # Recursive search mirroring the Dispatcher's tolerant extraction of
-        # ids from native responses (native shapes nest under result.*)
+        # Tolerant extraction of ids from native responses (native shapes
+        # nest under result.*); shared atom, same semantics as Dispatcher.
         def find_value(json, keys)
-          case json
-          when Hash
-            keys.each { |key| return json[key] if json[key].is_a?(String) && !json[key].empty? }
-            json.each_value do |value|
-              found = find_value(value, keys)
-              return found if found
-            end
-            nil
-          when Array
-            json.each do |value|
-              found = find_value(value, keys)
-              return found if found
-            end
-            nil
-          end
+          Atoms::JsonFind.find_value(json, keys)
         end
 
         # --- send: validation -------------------------------------------------

data/lib/ace/herdr/organisms/deliverer.rb

@@ -81,6 +81,7 @@ module Ace
 
           Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event_id) do
             record = Molecules::DeliveryRecordStore.load(@deliveries_dir, event_id)
+            raise ValidationError, "event belongs to the agent inbox" if record&.inbox
             validate_existing_record(record, ref, digest) if record
             record ||= Models::DeliveryRecord.new(
               event_id: event_id, session: ref.session, pane: ref.pane,
@@ -98,6 +99,7 @@ module Ace
           validate_event_id!(event_id)
           Molecules::DeliveryRecordStore.with_lock(@deliveries_dir, event_id) do
             record = Molecules::DeliveryRecordStore.load(@deliveries_dir, event_id)
+            raise ValidationError, "event belongs to the agent inbox" if record&.inbox
             if record.nil? || record.answer.to_s.empty?
               raise ValidationError,
                 "no recoverable answer stored for event #{event_id.inspect}"