ace-herdr 0.1.0

data/lib/ace/herdr/cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../herdr"
+require_relative "cli/commands/deliver"
+require_relative "cli/commands/dispatch"
+require_relative "cli/commands/wait"
+require_relative "cli/commands/close"
+require_relative "cli/commands/tidy"
+require_relative "cli/commands/list"
+require_relative "cli/commands/send"
+require_relative "cli/commands/capture"
+require_relative "cli/commands/workspace"
+require_relative "cli/commands/tab"
+require_relative "cli/commands/list_presets"
+
+module Ace
+  module Herdr
+    # ace-support-cli based CLI registry for ace-herdr
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-herdr"
+
+      # Application commands with descriptions (for help output)
+      REGISTERED_COMMANDS = [
+        ["deliver", "Push an answer to an agent pane (ace-hitl delivery contract)"],
+        ["dispatch", "Start an agent in one command: tab + agent + prompt"],
+        ["list", "List live panes, tabs, or workspaces as one JSON line"],
+        ["send", "Send a command, raw text, or named keys to a pane"],
+        ["capture", "Print recent pane output as raw text"],
+        ["wait", "Wait for an agent state or matching pane output"],
+        ["close", "Rename and/or close a finished agent pane"],
+        ["tidy", "Report cleanable panes/delivery records; close and archive with --apply"],
+        ["workspace", "Create a workspace from a preset"],
+        ["tab", "Create a tab from a preset"],
+        ["--list-presets", "List available workspace/tab presets"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-herdr deliver --session ws-1 --pane p5 --event-id evt-1 --answer-file answer.md",
+        "echo 'the answer' | ace-herdr deliver --pane p5",
+        "ace-herdr dispatch --label 8wm.t.vs0 --kind pi --prompt-file prompt.md",
+        "ace-herdr list --workspace w1",
+        "ace-herdr send --pane p5 --cmd 'bundle exec rake test'",
+        "ace-herdr send --pane p5 --msg 'continue' --key Enter",
+        "ace-herdr capture --pane p5 --lines 40",
+        "ace-herdr wait --pane p5 --for output --pattern done --timeout 30",
+        "ace-herdr workspace development",
+        "ace-herdr tab agent --workspace w1",
+        "ace-herdr --list-presets",
+        "ace-herdr close --pane p5 --rename done",
+        "ace-herdr tidy --apply"
+      ].freeze
+
+      # Start the CLI
+      #
+      # @param args [Array<String>] Command-line arguments
+      # @return [Integer] Exit code (0 for success, non-zero for failure)
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+
+      # Register commands
+      register "deliver", CLI::Commands::Deliver.new
+      register "dispatch", CLI::Commands::Dispatch.new
+      register "list", CLI::Commands::List.new
+      register "send", CLI::Commands::Send.new
+      register "capture", CLI::Commands::Capture.new
+      register "wait", CLI::Commands::Wait.new
+      register "close", CLI::Commands::Close.new
+      register "tidy", CLI::Commands::Tidy.new
+      register "workspace", CLI::Commands::Workspace.new
+      register "tab", CLI::Commands::Tab.new
+      register "--list-presets", CLI::Commands::ListPresets.new
+
+      # Register version command
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-herdr",
+        version: Ace::Herdr::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      # Register help command
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Herdr::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+    end
+  end
+end

data/lib/ace/herdr/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ace
+  module Herdr
+    # Base for herdr CLI executor failures; retry classification drives the
+    # ace-hitl DeliverResult state mapping (retryable vs terminal).
+    class ExecutorError < Error
+      # Terminal by default: retrying with identical content cannot succeed
+      def retryable?
+        false
+      end
+    end
+
+    # Agent rejected the prompt before any input was sent (agent_blocked)
+    class AgentBlockedError < ExecutorError; end
+
+    # Accepted prompt did not observe a working/blocked state in time
+    # (agent_prompt_stalled / wait timeout) — transient, safe to re-push
+    class AgentNotReadyError < ExecutorError
+      def retryable?
+        true
+      end
+    end
+
+    # Target pane does not exist (pane_not_found)
+    class PaneNotFoundError < ExecutorError; end
+
+    # Target tab does not exist (tab_not_found)
+    class TabNotFoundError < ExecutorError; end
+
+    # Target workspace does not exist (workspace_not_found)
+    class WorkspaceNotFoundError < ExecutorError; end
+
+    # No agent detected in the target pane
+    class AgentNotFoundError < ExecutorError; end
+
+    # herdr CLI binary or its socket is unreachable — transient
+    class ExecutorUnavailableError < ExecutorError
+      def retryable?
+        true
+      end
+    end
+
+    # Unclassified herdr CLI failure — treated as transient within retry limits
+    class CommandError < ExecutorError
+      def retryable?
+        true
+      end
+    end
+  end
+end

data/lib/ace/herdr/models/delivery_record.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Herdr
+    module Models
+      # Write-ahead record of one push delivery. Immutable value object:
+      # state transitions return new instances; persistence lives in
+      # Molecules::DeliveryRecordStore.
+      #
+      # States: pending (written before first herdr contact), delivered,
+      # retryable (exhausted transient attempts; safe to re-push identical
+      # content), failed (terminal).
+      #
+      # The record carries the full answer so a crash after write-ahead but
+      # before the prompt never loses the content; it can be re-delivered
+      # via resume. Record files are 0600 (answers may be sensitive).
+      class DeliveryRecord
+        STATES = %w[pending delivered retryable failed].freeze
+
+        attr_reader :event_id, :session, :pane, :answer_digest, :answer,
+          :state, :attempts, :history, :created_at, :updated_at
+
+        def initialize(event_id:, session:, pane:, answer_digest:, answer: nil,
+          state: "pending", attempts: 0, history: [], created_at: nil, updated_at: nil)
+          raise ArgumentError, "unknown state: #{state}" unless STATES.include?(state)
+
+          @event_id = event_id
+          @session = session
+          @pane = pane
+          @answer_digest = answer_digest
+          @answer = answer
+          @state = state
+          @attempts = attempts
+          @history = history.dup.freeze
+          @created_at = created_at
+          @updated_at = updated_at
+          freeze
+        end
+
+        def self.from_h(hash)
+          new(
+            event_id: hash["event_id"], session: hash["session"], pane: hash["pane"],
+            answer_digest: hash["answer_digest"], answer: hash["answer"],
+            state: hash["state"] || "pending",
+            attempts: hash["attempts"] || 0, history: hash["history"] || [],
+            created_at: hash["created_at"], updated_at: hash["updated_at"]
+          )
+        end
+
+        def self.from_json(json)
+          from_h(JSON.parse(json))
+        end
+
+        def to_h
+          {
+            "event_id" => event_id, "session" => session, "pane" => pane,
+            "answer_digest" => answer_digest, "answer" => answer,
+            "state" => state,
+            "attempts" => attempts, "history" => history,
+            "created_at" => created_at, "updated_at" => updated_at
+          }
+        end
+
+        def delivered?
+          state == "delivered"
+        end
+
+        # A "submitting" history entry without a matching outcome means the
+        # previous run crashed between prompt submission and persistence;
+        # resending could duplicate the answer, so the outcome is ambiguous.
+        def ambiguous_submission?
+          last = history.last
+          last.is_a?(Hash) && last["action"] == "prompt" && last["outcome"] == "submitting"
+        end
+
+        # Return a copy with a history entry appended (no attempt counted);
+        # used for non-prompt events such as bootstrap actions
+        def append_event(detail:, timestamp:, state: nil)
+          self.class.new(
+            event_id: event_id, session: session, pane: pane,
+            answer_digest: answer_digest, answer: answer,
+            state: state || self.state,
+            attempts: attempts,
+            history: history + [detail.merge("at" => timestamp)],
+            created_at: created_at || timestamp, updated_at: timestamp
+          )
+        end
+
+        # Return a copy advanced to the next attempt with a history entry
+        # @param state [String] resulting state after the attempt
+        # @param detail [Hash] attempt detail (action, outcome, error)
+        # @param timestamp [String] RFC 3339 timestamp of the transition
+        def record_attempt(state:, detail:, timestamp:)
+          appended = append_event(state: state, detail: detail, timestamp: timestamp)
+          self.class.new(
+            event_id: event_id, session: session, pane: pane,
+            answer_digest: answer_digest, answer: answer,
+            state: state,
+            attempts: attempts + 1,
+            history: appended.history,
+            created_at: appended.created_at, updated_at: appended.updated_at
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/models/dispatch_outcome.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ace
+  module Herdr
+    module Models
+      # Outcome of a one-command agent dispatch: pure data carrier
+      class DispatchOutcome
+        attr_reader :workspace_id, :pane, :agent_name, :kind, :tab_created, :prompted
+
+        def initialize(workspace_id:, pane:, agent_name:, kind:, tab_created:, prompted:)
+          @workspace_id = workspace_id
+          @pane = pane
+          @agent_name = agent_name
+          @kind = kind
+          @tab_created = tab_created
+          @prompted = prompted
+          freeze
+        end
+
+        def to_h
+          {
+            "workspace" => workspace_id, "pane" => pane, "agent" => agent_name,
+            "kind" => kind, "tab_created" => tab_created, "prompted" => prompted
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Persists DeliveryRecord JSON files under a deliveries directory.
+      # Writes are atomic (temp file + rename, mode 0600) so a crash never
+      # yields a torn record and the answer stays re-deliverable. A per-event
+      # flock serializes concurrent deliveries of the same event.
+      module DeliveryRecordStore
+        module_function
+
+        # @return [Models::DeliveryRecord, nil] the record, falling back to
+        #   the archive copy when the live record is gone — delivery
+        #   idempotency (identical short-circuit, conflict fail-closed) must
+        #   survive tidy archival
+        # @raise on malformed/unreadable content (fail closed: callers must
+        #   not treat a corrupt record as absent)
+        def load(deliveries_dir, event_id)
+          path = resolve_record_path(deliveries_dir, event_id)
+          return nil unless path
+
+          Models::DeliveryRecord.from_json(File.read(path))
+        end
+
+        # Tidy's lock-guarded revalidation load: like load, but a malformed
+        # or unreadable record decodes as :unreadable instead of raising
+        # (reported as preserved, never archived on unprovable evidence)
+        # @return [Models::DeliveryRecord, nil, :unreadable]
+        def load_revalidated(deliveries_dir, event_id)
+          path = resolve_record_path(deliveries_dir, event_id)
+          return nil unless path
+
+          Models::DeliveryRecord.from_h(JSON.parse(File.read(path)))
+        rescue JSON::ParserError, ArgumentError, TypeError, NoMethodError, Errno::EACCES
+          :unreadable
+        end
+
+        # @return [String] path the record was written to
+        def save(record, deliveries_dir)
+          FileUtils.mkdir_p(deliveries_dir)
+          path = path_for(deliveries_dir, record.event_id)
+          tmp = "#{path}.tmp.#{Process.pid}"
+          File.open(tmp, IO::CREAT | IO::TRUNC | IO::WRONLY, 0o600) do |file|
+            file.write(JSON.generate(record.to_h))
+          end
+          File.rename(tmp, path)
+          path
+        end
+
+        # Hold the exclusive per-event lock while delivering; concurrent
+        # callers block until the winner finishes, then observe its record.
+        def with_lock(deliveries_dir, event_id)
+          FileUtils.mkdir_p(deliveries_dir)
+          File.open(lock_path(deliveries_dir, event_id), "a") do |lock|
+            lock.flock(File::LOCK_EX)
+            begin
+              return yield
+            ensure
+              lock.flock(File::LOCK_UN)
+            end
+          end
+        end
+
+        def path_for(deliveries_dir, event_id)
+          File.join(deliveries_dir, "#{event_id}.json")
+        end
+
+        def lock_path(deliveries_dir, event_id)
+          File.join(deliveries_dir, ".#{event_id}.lock")
+        end
+
+        # --- tidy (spec 8wq.t.1w0) -------------------------------------------
+
+        # Enumerate the top-level delivery records, sorted by event id.
+        # Lock files, temp files, and the archive directory are ignored;
+        # a malformed or unreadable file yields an entry with record: nil
+        # (reported as preserved, never removed).
+        # @return [Array<{event_id: String, record: Models::DeliveryRecord, nil}>]
+        def list_records(deliveries_dir)
+          return [] unless Dir.exist?(deliveries_dir)
+
+          Dir.children(deliveries_dir).sort.filter_map do |name|
+            next nil unless name.end_with?(".json")
+            next nil unless record_file?(File.join(deliveries_dir, name))
+
+            event_id = name.delete_suffix(".json")
+            record =
+              begin
+                read_record(File.join(deliveries_dir, name))
+              rescue Errno::EACCES
+                nil # unreadable: reported as preserved, never removed
+              rescue Errno::ENOENT
+                next nil # vanished between listing and read: nothing to preserve
+              end
+            {event_id: event_id, record: record}
+          end
+        end
+
+        # Archive directory for retired delivered records (inside the
+        # deliveries dir so a same-filesystem rename stays atomic)
+        def archive_dir(deliveries_dir)
+          File.join(deliveries_dir, "archive")
+        end
+
+        # Atomically move one record file into the archive directory
+        # (rename preserves the 0600 mode). Callers must hold the per-event
+        # lock and re-check eligibility under it. Idempotent: an already
+        # archived event just reports its archive path.
+        # @return [String] the archive path the record lives at
+        def archive(deliveries_dir, event_id)
+          dest = File.join(archive_dir(deliveries_dir), "#{event_id}.json")
+          return dest if !File.exist?(path_for(deliveries_dir, event_id)) && File.exist?(dest)
+
+          FileUtils.mkdir_p(archive_dir(deliveries_dir))
+          File.rename(path_for(deliveries_dir, event_id), dest)
+          dest
+        end
+
+        def record_file?(path)
+          File.file?(path) && !File.basename(path).start_with?(".")
+        end
+
+        # Live record path, falling back to the archive copy
+        def resolve_record_path(deliveries_dir, event_id)
+          live = path_for(deliveries_dir, event_id)
+          return live if File.exist?(live)
+
+          archived = File.join(archive_dir(deliveries_dir), "#{event_id}.json")
+          File.exist?(archived) ? archived : nil
+        end
+
+        # Decode a record file fail-closed: anything that is not a decodable
+        # delivery record (malformed JSON, non-object JSON, unknown state)
+        # reads as nil (preserved/unreadable), never raises
+        def read_record(path)
+          parsed = JSON.parse(File.read(path))
+          return nil unless parsed.is_a?(Hash)
+
+          Models::DeliveryRecord.from_h(parsed)
+        rescue JSON::ParserError, ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end