ace-runtime 0.1.0

data/lib/ace/runtime/cli/commands/send.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Runtime
+    module CLI
+      module Commands
+        # The neutral callback passthrough (Fork Callback Rule). Resolves
+        # the configured runtime and delegates to runtime.send with the
+        # normative send-matrix semantics: ordered delivery on plain
+        # panes, single self-submitting prompt shapes on agent panes.
+        # Rejected input fails before any transport call.
+        class Send < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Send a submitted command, text chunks, or named keys to a pane via the resolved terminal runtime
+
+            Runtime resolution: --runtime > ACE_RUNTIME > configured runtime > auto-detection
+            (tmux wins when both environments are live). Rejected sends make no transport call.
+          DESC
+
+          example [
+            "--pane %1 --cmd 'bundle exec rake test'",
+            "--pane %1 --msg 'Reply with exactly: pong' --key Enter",
+            "--runtime herdr --pane w1:p1 --msg 'hello'",
+            "--pane %1 --key C-c"
+          ]
+
+          option :runtime, type: :string, desc: "Terminal runtime name (tmux, herdr); overrides ACE_RUNTIME, config, and detection"
+          option :pane, type: :string, required: true, desc: "Target pane handle as exposed by the runtime (opaque, adapter-owned)"
+          option :cmd, type: :string, aliases: %w[-c], desc: "Command text to submit once (declare before any --key)"
+          option :msg, type: :string, aliases: %w[-m], repeat: true, desc: "Literal text chunk to deliver without implicit submission"
+          option :key, type: :string, aliases: %w[-k], repeat: true, desc: "Named key to deliver (for example Enter, C-c)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            command, items = build_request(options)
+            selector = Molecules::RuntimeSelector.new(config: Ace::Runtime.config)
+            runtime = selector.resolve(explicit: options[:runtime])
+            result = runtime.send(pane: options[:pane], command: command, items: items)
+
+            report(selector.selected_name, command, items, result) unless quiet?(options)
+          rescue Ace::Runtime::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          # The callback CLI builds direct-API items as all supplied
+          # messages followed by all supplied keys; direct Ruby callers
+          # use send(items:) when they need arbitrary interleaving.
+          def build_request(options)
+            reject_leading_keys!
+
+            command = normalize_cmd(options[:cmd])
+            items = Array(options[:msg]).map { |text| {message: text} } +
+              Array(options[:key]).map { |name| {key: name} }
+
+            if command.nil? && items.empty?
+              raise Ace::Support::Cli::Error, "provide at least one of --cmd, --msg, or --key"
+            end
+
+            [command, items]
+          end
+
+          # Leading keys (--key Esc --cmd run) are a normative usage
+          # error: --cmd must be declared before every key.
+          def reject_leading_keys!
+            cmd_index = first_flag_index(%w[--cmd -c])
+            key_indices = flag_indices(%w[--key -k])
+            return if cmd_index.nil? || key_indices.empty? || key_indices.min > cmd_index
+
+            raise Ace::Support::Cli::Error,
+              "--key before --cmd is a usage error: --cmd must be declared before every key"
+          end
+
+          def flag_indices(flags)
+            Ace::Runtime::CLI.last_invocation_args.each_index.select do |index|
+              token = Ace::Runtime::CLI.last_invocation_args[index]
+              flags.any? { |flag| token == flag || token.start_with?("#{flag}=") }
+            end
+          end
+
+          def first_flag_index(flags)
+            list = flag_indices(flags)
+            list.empty? ? nil : list.min
+          end
+
+          def normalize_cmd(value)
+            text = value.to_s
+            return nil if text.strip.empty?
+
+            text
+          end
+
+          def report(runtime_name, command, items, result)
+            parts = []
+            parts << "command" if command
+            message_count = items.count { |item| item.key?(:message) }
+            key_count = items.count { |item| item.key?(:key) }
+            parts << pluralize(message_count, "message") if message_count.positive?
+            parts << pluralize(key_count, "key") if key_count.positive?
+
+            line = "Sent via #{runtime_name}: #{parts.join(' + ')}"
+            line += " (dropped trailing Enter for agent pane)" if result&.dropped_trailing_enter
+
+            puts line
+          end
+
+          def pluralize(count, noun)
+            "#{count} #{noun}#{count == 1 ? '' : 's'}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/cli.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../runtime"
+require_relative "cli/commands/send"
+
+module Ace
+  module Runtime
+    # ace-support-cli based CLI registry for ace-runtime. The contract
+    # ships exactly one agent-facing command: the neutral send
+    # passthrough (Fork Callback Rule decision, 2026-09-27).
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-runtime"
+
+      # Application commands with descriptions (for help output)
+      REGISTERED_COMMANDS = [
+        ["send", "Send a submitted command, text chunks, or named keys to a pane via the resolved terminal runtime"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-runtime send --pane %1 --cmd 'bundle exec rake test'                  # Submit a command",
+        "ace-runtime send --pane %1 --msg 'Reply with exactly: pong' --key Enter   # Callback form: submits exactly once",
+        "ace-runtime send --runtime herdr --pane w1:p1 --msg 'hello'               # Explicit runtime selection",
+        "ace-runtime send --pane %1 --key C-c                                      # Keys-only send"
+      ].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)
+        @last_invocation_args = args
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+
+      # Raw arguments of the current invocation. The send command reads
+      # these for flag declaration order (--cmd before every --key);
+      # falls back to ARGV when the CLI was not started through #start.
+      def self.last_invocation_args
+        @last_invocation_args || ARGV
+      end
+
+      # Register commands
+      register "send", CLI::Commands::Send.new
+
+      # Register version command
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-runtime",
+        version: Ace::Runtime::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::Runtime::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/runtime/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    # Contract error hierarchy. Every runtime failure surfaces as one of
+    # these typed errors; adapters translate their native failures into
+    # them at the boundary.
+    class Error < StandardError; end
+
+    # The requested runtime name has no registered adapter (after the
+    # convention-based entrypoint load attempt). Fails closed and names
+    # the available runtimes.
+    class UnknownRuntimeError < Error
+      attr_reader :requested, :available
+
+      def initialize(requested:, available:)
+        @requested = requested
+        @available = Array(available).sort.freeze
+        super("unknown runtime '#{requested}' (available: #{@available.join(', ')})")
+      end
+    end
+
+    # The runtime is known but not usable right now (server unreachable,
+    # no live session/workspace). Never silently downgraded to another
+    # runtime or to a headless mode.
+    class RuntimeUnavailableError < Error; end
+
+    # A window/pane target does not exist. Target values are opaque,
+    # adapter-owned handles; the contract never predicts or formats them.
+    class TargetNotFoundError < Error; end
+
+    # ensure_window found an existing window with the same normalized
+    # name scoped to the current session/workspace but an incompatible
+    # root or preset.
+    class WindowConflictError < Error; end
+
+    # Pre-send rejection (invalid send shape or an agent pane blocking
+    # the delivery). Raised before any transport call; terminal.
+    class SendRejectedError < Error; end
+
+    # The submission was accepted but the target did not start
+    # processing it. The outcome is uncertain: callers must not
+    # auto-resend the same content.
+    class SendStalledError < Error; end
+
+    # A wait exceeded its deadline. Timeout units at the contract level
+    # are SECONDS; adapters convert to native units internally.
+    class WaitTimeoutError < Error
+      attr_reader :condition, :target, :timeout
+
+      def initialize(condition:, timeout:, target: nil)
+        @condition = condition
+        @target = target
+        @timeout = timeout
+        target_part = target ? " on '#{target}'" : ""
+        super("timed out waiting for #{condition}#{target_part} after #{timeout}s")
+      end
+    end
+  end
+end

data/lib/ace/runtime/molecules/runtime_selector.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Molecules
+      # Runtime selection precedence: explicit name > ACE_RUNTIME >
+      # configured runtime > side-effect-free environment detection.
+      # Resolution happens only after selection. An explicitly selected
+      # runtime that turns out unknown or unavailable fails closed via
+      # the registry — never headless, never a silent switch to another
+      # runtime. Only the assign auto launch mode selects headless
+      # outside any runtime; that decision lives above this selector.
+      class RuntimeSelector
+        ENV_RUNTIME_KEY = "ACE_RUNTIME"
+
+        attr_reader :selected_name
+
+        def initialize(config: nil, registry: nil, env: ENV)
+          @config = config
+          @registry = registry
+          @env = env
+          @selected_name = nil
+        end
+
+        def resolve(explicit: nil)
+          name = select_name(explicit: explicit)
+
+          if name.nil? || name.empty?
+            raise RuntimeUnavailableError,
+              "no terminal runtime selected: pass --runtime, set #{ENV_RUNTIME_KEY}, " \
+              "configure runtime under the ace-runtime config namespace, or run inside tmux/herdr"
+          end
+
+          @selected_name = name
+          registry.resolve(name)
+        end
+
+        private
+
+        attr_reader :config, :env
+
+        def registry
+          @registry || Ace::Runtime.registry
+        end
+
+        def select_name(explicit:)
+          name = explicit.to_s.strip
+          name = env_value(ENV_RUNTIME_KEY) if name.empty?
+          name = configured_runtime if name.empty?
+          name = detected_name if name.empty?
+
+          name
+        end
+
+        def env_value(key)
+          env[key].to_s.strip
+        end
+
+        def configured_runtime
+          return "" unless config.is_a?(Hash)
+
+          value = config.key?("runtime") ? config["runtime"] : config[:runtime]
+          value.to_s.strip
+        end
+
+        def detected_name
+          detected = Atoms::Detector.detect(env: env)
+          detected ? detected.to_s : ""
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    # Duck-typed adapter registry (ace-hitl Providers pattern). Runtime
+    # adapters register a factory under a simple name; resolution is
+    # fail-closed: an unknown name raises UnknownRuntimeError carrying
+    # the sorted available list. There is no base class — an adapter is
+    # whatever object implements the published intent operations.
+    class Registry
+      # Only identifier-shaped names may trigger the convention-based
+      # entrypoint load, so a hostile runtime name can never traverse
+      # the Ruby load path.
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+      ADAPTER_ENTRYPOINT_FORMAT = "ace/runtime/adapters/%s"
+
+      def initialize
+        @factories = {}
+      end
+
+      def register(name, factory = nil, &block)
+        key = name.to_s
+        callable = factory || block
+        raise ArgumentError, "adapter factory for '#{key}' must respond to #call" unless callable.respond_to?(:call)
+
+        @factories[key] = callable
+        nil
+      end
+
+      def registered?(name)
+        @factories.key?(name.to_s)
+      end
+
+      def available
+        @factories.keys.sort
+      end
+
+      def resolve(name)
+        key = name.to_s
+        load_adapter_entrypoint(key) unless @factories.key?(key)
+
+        factory = @factories[key]
+        raise UnknownRuntimeError.new(requested: key, available: available) unless factory
+
+        factory.call
+      end
+
+      private
+
+      # Convention: adapter packages ship a lib/ace/runtime/adapters/<name>.rb
+      # entrypoint that calls Ace::Runtime.register. It is attempted
+      # lazily on first resolve so the contract gem keeps no dependency
+      # on either adapter package. Only a missing entrypoint counts as
+      # "not installed"; a LoadError raised INSIDE an installed
+      # entrypoint (for example its own missing dependency) propagates
+      # so a broken adapter is never misreported as unknown.
+      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