ace-runtime 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d0ae5fb595d866fb47f42ed3ea0672510f5a15a6403ee41519889227929c6fe
+  data.tar.gz: 9f2271b76b6b70a18fb8b7f5c694a41bbeb40268a23b8035b9b96959c4b2faaf
+SHA512:
+  metadata.gz: a17e805f6629de33133964d6ef890f83acdddec724698a3c6dc09d069521331670284c41f7350976d2d1d85986ca4a0671bef22aca903ef0a60d867bacc14a2e
+  data.tar.gz: 0dac8a633d821dcfbdf21ca532b535d8a7aaf16c397062c2ac86ff0e8500b55f2272623f7e4b2a617f4488c3c67b4e1f72c10cf85c52dab34b387d45c61c80ea

data/.ace-defaults/runtime/config.yml

@@ -0,0 +1,7 @@
+# ace-runtime default configuration
+# Override in ~/.ace/runtime/config.yml or .ace/runtime/config.yml
+
+# Terminal runtime used by ace-runtime send when neither --runtime nor
+# ACE_RUNTIME is set. Leave null for auto-detection from the environment;
+# tmux wins when both tmux and herdr environments are live.
+runtime: null

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- Runtime-neutral terminal intent contract (spec 8wq.t.k86.0): duck-typed adapter registry with fail-closed resolution and lazy `ace/runtime/adapters/<name>` entrypoint loading.
+- Side-effect-free environment detection (`Ace::Runtime.detect`) with documented tmux precedence when both runtimes are live.
+- Shared window/tab name sanitization (`Ace::Runtime.sanitize_name`).
+- The 11-operation intent API with opaque adapter-owned target handles, seconds-based wait timeouts, and the typed error model (`UnknownRuntimeError`, `RuntimeUnavailableError`, `TargetNotFoundError`, `WindowConflictError`, `SendRejectedError`, `SendStalledError`, `WaitTimeoutError`).
+- Central send-matrix validation (`Ace::Runtime::Atoms::SendContract`) for `:plain_pane` and `:agent_aware` profiles, including ordered `{message:}/{key:}` items and the callback shapes that submit exactly once.
+- The single neutral callback CLI: `ace-runtime send`.
+- The packaged adapter contract-test suite (`Ace::Runtime::Testing::AdapterContract`) with the `ScriptedRuntime` fixture, documented as the acceptance bar for any adapter.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# ace-runtime
+
+Runtime-neutral terminal intent contract for ACE (spec 8wq.t.k86.0). One
+duck-typed intent API that terminal runtimes implement and all consumers
+call — the structural change that makes herdr an equal partner to tmux
+instead of a side gem.
+
+Adapters live INSIDE the existing wrapper gems: `ace-tmux` and `ace-herdr`
+gain a dependency on `ace-runtime` and ship an adapter entrypoint. This
+gem depends on neither (ADR-033 stability rationale; Captain decision
+2026-09-27).
+
+## The contract
+
+Eleven operations, keyword-arg surfaces mirroring today's consumer calls:
+
+| Operation | Surface |
+|-----------|---------|
+| Context | `runtime.context` → `{in_runtime:, session:, window:, pane:}` |
+| Ensure window | `runtime.ensure_window(name:, root:, preset: nil)` — idempotent by normalized name; conflicting root/preset raises `WindowConflictError` |
+| Prepare pane | `runtime.prepare_pane(window:)` — splits when needed; target stays alive after a submitted command exits |
+| Focus | `runtime.focus(window:)` |
+| Send | `runtime.send(pane:, command: nil, items: [])` — ordered `{message: String}` / `{key: String}` entries |
+| Capture | `runtime.capture(pane:, lines: 40)` → text |
+| Wait output | `runtime.wait_output(pane:, pattern:, timeout:)` |
+| Wait agent | `runtime.wait_agent(pane:, states:, timeout:)` |
+| Wait lifecycle | `runtime.wait_lifecycle(condition:, target:, timeout:)` — `window-exits`/`window-active`/`pane-exists`/`pane-exited` observations only |
+| Close | `runtime.close_window(window:)` |
+| List | `runtime.list_windows` / `runtime.list_panes(window:)` |
+
+Convenience shapes: `send_command(pane:, command:)`,
+`send_text(pane:, text:)`, `send_keys(pane:, keys:)`.
+
+Target identity is opaque adapter-owned handles at every boundary — the
+contract never predicts or formats pane ids (tmux `%id` and herdr
+`w1:p1` stay adapter-internal). Window operations take the (sanitized)
+window name; pane operations take the handle returned by the adapter.
+
+Timeouts at the contract level are SECONDS; adapters convert to native
+units internally.
+
+## Resolution and selection
+
+```ruby
+runtime = Ace::Runtime.resolve("tmux")   # fail-closed; unknown name raises
+                                         # UnknownRuntimeError (available: ...)
+name = Ace::Runtime.detect(env: ENV)     # :tmux | :herdr | nil, no side effects
+```
+
+CLI/runtime selection precedence (highest wins):
+
+1. explicit name (`ace-runtime send --runtime herdr`)
+2. `ACE_RUNTIME` environment (consumer forks set this plus target context)
+3. configured runtime — `.ace/runtime/config.yml` key `runtime`
+4. auto-detection from the environment (`TMUX` / `ACE_TMUX_SESSION`, or
+   `HERDR_SESSION` + `HERDR_PANE`). When both are live, tmux wins
+   (existing default). Only assign auto launch mode selects headless
+   outside any runtime; that decision lives above this contract.
+
+An explicitly selected runtime that turns out unknown or unavailable
+fails closed — never a silent switch or headless downgrade.
+
+## Send matrix
+
+`send` is the only submission primitive; the granular ops are shapes of
+it. `items` is an ORDERED list — the only shape that preserves
+message/key interleaving. When `command` is present, `items` holds
+exclusively post-command keys; leading keys are a usage error before any
+transport call (the CLI enforces `--cmd` before every `--key`).
+
+- **Plain-pane adapters** (`send_profile == :plain_pane`, e.g. tmux):
+  messages are raw text (no implicit submission), keys are keystrokes,
+  each Enter submits pending text; `command` submits once, then trailing
+  keys deliver.
+- **Agent-aware adapters** (`send_profile == :agent_aware`, e.g. herdr):
+  `command` or the concatenated messages become ONE prompt that submits
+  itself (message-only input DOES submit once on agent panes — intended
+  divergence); at most one trailing Enter is dropped and reported via
+  the result; keys-only sequences go to agent keys; every other
+  interleaving is rejected before any transport call.
+
+An invocation with no send content at all is a usage error on both
+profiles.
+
+## Error model
+
+All failures subclass `Ace::Runtime::Error`:
+
+- `UnknownRuntimeError` — with the sorted available list
+- `RuntimeUnavailableError` — known runtime, unusable right now
+- `TargetNotFoundError` — window/pane target does not exist
+- `WindowConflictError` — same normalized name, incompatible root/preset
+- `SendRejectedError` — pre-send rejection; terminal, no transport call
+- `SendStalledError` — submission accepted but the target never started
+  processing; OUTCOME UNCERTAIN, callers must not auto-resend
+- `WaitTimeoutError` — a wait exceeded its deadline (seconds context)
+
+`pane-exited` is a runtime observation only — never assignment success,
+receipt confirmation, or prune authorization.
+
+## Adapter contract
+
+Adapters are duck-typed (no base class, ace-hitl provider-registry
+pattern). To register:
+
+```ruby
+# lib/ace/runtime/adapters/<name>.rb in the adapter package
+Ace::Runtime.register(:<name>, -> { Ace::Tmux::RuntimeAdapter.new })
+```
+
+The contract resolves an unregistered known name by attempting to load
+that entrypoint lazily — no gem dependency in either direction.
+
+The packaged shared suite `Ace::Runtime::Testing::AdapterContract` is
+the acceptance bar for ANY adapter. See `docs/usage.md` for the
+adapter-authoring walkthrough.
+
+Note: adapters intentionally define `send` (the intent operation),
+which overrides `Object#send`. Use `__send__` for reflective dispatch
+on adapter objects.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/usage.md

@@ -0,0 +1,189 @@
+# ace-runtime usage
+
+Runtime-neutral terminal intent contract. This document covers the
+`ace-runtime send` callback CLI, direct API send shapes, runtime
+selection, and adapter authoring against the shared contract suite.
+
+## CLI: the neutral callback passthrough
+
+The gem ships exactly one command (Fork Callback Rule decision,
+2026-09-27). It resolves the configured runtime and delegates to
+`runtime.send` with the normative matrix semantics.
+
+```bash
+# Submit a command (typed + Enter once) on the current pane's runtime
+ace-runtime send --pane %1 --cmd 'bundle exec rake test'
+
+# Callback form: submits exactly once on BOTH adapters
+ace-runtime send --pane %1 --msg 'Reply with exactly: pong' --key Enter
+
+# Explicit runtime selection
+ace-runtime send --runtime herdr --pane w1:p1 --msg 'hello'
+
+# Keys-only (valid; no implicit submission)
+ace-runtime send --pane %1 --key C-c
+
+# Command with post-submission keystrokes
+ace-runtime send --pane %1 --cmd 'vim .' --key C-w
+```
+
+Rules enforced before any transport call:
+
+- `--pane` is required; at least one of `--cmd`, `--msg`, `--key` is
+  required (none = usage error).
+- `--key` before `--cmd` is a usage error — `--cmd` must be declared
+  before every key. Keys declared after `--cmd` are post-submission
+  keystrokes.
+- The 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 (for example `msg, key, msg` on plain
+  panes).
+- On agent panes (`:agent_aware` profile) the callback shapes submit
+  exactly once: `--msg ... --key Enter` becomes one self-submitting
+  prompt with the trailing Enter dropped and reported; interleaved
+  items, multiple Enters, `--cmd` with messages, and `--cmd` with
+  non-Enter keys are rejected.
+
+Exit behavior: contract errors (`UnknownRuntimeError`,
+`RuntimeUnavailableError`, `TargetNotFoundError`, `SendRejectedError`,
+`SendStalledError`, ...) surface as CLI errors with their message;
+`--quiet` suppresses the success line.
+
+## Direct API
+
+```ruby
+runtime = Ace::Runtime.resolve(:tmux)   # or let selection resolve for you
+Ace::Runtime.detect(env: ENV)           # => :tmux | :herdr | nil (no side effects)
+
+# Ordered items preserve interleaving (plain-pane example)
+runtime.send(pane: handle, items: [
+  {message: "switch to the topics tab"},
+  {key: "C-c"},
+  {message: "then restart the worker"}
+])
+
+# Convenience shapes
+runtime.send_command(pane: handle, command: "bundle exec rake test")
+runtime.send_text(pane: handle, text: "plain text, no submission")
+runtime.send_keys(pane: handle, keys: %w[Enter C-c])
+
+# Waits: timeouts in SECONDS (adapters convert internally)
+runtime.wait_output(pane: handle, pattern: "1 example, 0 failures", timeout: 30)
+runtime.wait_agent(pane: handle, states: %w[idle working-done], timeout: 600)
+runtime.wait_lifecycle(condition: "pane-exited", target: handle, timeout: 60)
+
+# Windows and panes
+handle = runtime.ensure_window(name: "work fs", root: "/repo", preset: nil)
+pane = runtime.prepare_pane(window: "work-fs")   # split when needed, retained
+runtime.focus(window: "work-fs")
+runtime.list_windows
+runtime.list_panes(window: "work-fs")
+runtime.close_window(window: "work-fs")
+Ace::Runtime.sanitize_name("my work!")           # => "my-work"
+```
+
+`ensure_window` identity is `(resolved session/workspace, sanitized
+name)`; an existing window with an incompatible root or preset raises
+`WindowConflictError` instead of silently reusing the wrong worktree.
+
+`wait_lifecycle` accepts only `window-exists`, `window-active`,
+`pane-exists`, `pane-exited`. It reports the condition only — never
+authorizes completion, receipts, or pruning. `pane-exited` in
+particular is an observation, not assignment success or safe prune
+evidence.
+
+## Runtime selection order
+
+1. explicit name (`--runtime tmux|herdr` / programmatic explicit)
+2. `ACE_RUNTIME` (consumer forks set this plus target context to the
+   caller backend)
+3. configured `runtime:` key under the `ace-runtime` config namespace
+   (`.ace/runtime/config.yml`, `~/.ace/runtime/config.yml`)
+4. auto-detection: `TMUX` or `ACE_TMUX_SESSION` → tmux;
+   `HERDR_SESSION` + `HERDR_PANE` → herdr; both live → tmux
+   (documented default); neither → nil
+
+Explicit selections never downgrade: unknown names fail closed with
+the available list (`UnknownRuntimeError`); a selected-but-unavailable
+runtime raises `RuntimeUnavailableError` — no headless fallback, no
+silent switch. The assign auto launch mode is the only consumer that
+selects headless outside any runtime, and it does so above this
+contract.
+
+## Adapter authoring
+
+Adapters are duck-typed — no base class (ace-hitl provider-registry
+pattern). An adapter package:
+
+1. declares a dependency on `ace-runtime` (never the reverse),
+2. ships an entrypoint `lib/ace/runtime/adapters/<name>.rb`:
+
+   ```ruby
+   Ace::Runtime.register(:herdr, -> { Ace::Herdr::RuntimeAdapter.new })
+   ```
+
+3. implements the full published intent API (context, ensure_window,
+   prepare_pane, focus, send, send_command, send_text, send_keys,
+   capture, wait_output, wait_agent, wait_lifecycle, close_window,
+   list_windows, list_panes) and exposes `send_profile`
+   (`:plain_pane` or `:agent_aware`),
+4. normalizes public send input through
+   `Ace::Runtime::Atoms::SendContract.normalize!` BEFORE transport so
+   rejection never reaches native calls,
+5. translates native failures at the boundary: unknown target →
+   `TargetNotFoundError`, unreachable runtime →
+   `RuntimeUnavailableError`, accepted-but-not-processing →
+   `SendStalledError` (never auto-resend), deadline exceeded →
+   `WaitTimeoutError` with seconds context.
+
+Non-negotiables enforced by the contract suite:
+
+- target handles stay opaque at every public boundary,
+- `prepare_pane` yields a writable live shell/agent target retained
+  after a submitted command exits (bare command panes do not satisfy
+  preparation),
+- `detect` and adapter availability checks are side-effect-free; an
+  unavailable explicit runtime never becomes headless,
+- installed tests must verify both runtimes; never assert untested
+  behavior.
+
+### The acceptance bar
+
+`Ace::Runtime::Testing::AdapterContract` is the shared contract-test
+suite and the acceptance bar for ANY adapter. In your adapter's test
+helper:
+
+```ruby
+require "ace/runtime/testing"
+
+class TmuxAdapterContractTest < AceTestCase
+  include Ace::Runtime::Testing::AdapterContract
+  include Ace::Runtime::Testing::AdapterContract::PlainPaneSendMatrix
+
+  def build_fixture
+    Ace::Runtime::Testing::ScriptedRuntime.new
+  end
+
+  def build_adapter(fixture)
+    Ace::Tmux::RuntimeAdapter.new(fixture: fixture)  # thin bridge to your transport
+  end
+end
+```
+
+The suite drives your adapter over `ScriptedRuntime` — an in-memory
+terminal (windows, panes, raw text writes, named keys, capture, agent
+state) that records every mutation op so the suite can assert delivery
+ordering and rejection-before-transport. Wire your adapter's native
+transport to the fixture's primitive ops and translate its fixture
+signals at the boundary:
+
+| Fixture signal | Contract error |
+|----------------|----------------|
+| `Testing::FixtureUnavailable` | `RuntimeUnavailableError` |
+| `Testing::FixtureStall` | `SendStalledError` |
+| `Testing::FixtureTargetMissing` | `TargetNotFoundError` |
+
+The reference implementation is `test/support/fake_runtime_adapter.rb`
+in the ace-runtime gem; the in-gem suite
+(`test/contract/adapter_contract_test.rb`) proves the battery against
+it for both send profiles.

data/exe/ace-runtime

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ace/runtime"
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start CLI with exception-based exit code handling (per ADR-023)
+begin
+  exit_code = Ace::Runtime::CLI.start(args)
+  exit(exit_code) if exit_code.is_a?(Integer) && exit_code.nonzero?
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

data/lib/ace/runtime/atoms/detector.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Atoms
+      # Pure environment detection. Reads the provided env only: no
+      # adapter loads, no transport calls, no other side effects.
+      # tmux wins when both environments are live (existing default,
+      # documented in README).
+      module Detector
+        module_function
+
+        def detect(env: ENV)
+          return :tmux if tmux_live?(env)
+          return :herdr if herdr_live?(env)
+
+          nil
+        end
+
+        def tmux_live?(env)
+          nonblank?(env["TMUX"]) || nonblank?(env["ACE_TMUX_SESSION"])
+        end
+
+        def herdr_live?(env)
+          nonblank?(env["HERDR_SESSION"]) && nonblank?(env["HERDR_PANE"])
+        end
+
+        def nonblank?(value)
+          !value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/atoms/name_sanitizer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Atoms
+      # Shared window/tab naming policy, extracted from the established
+      # tmux sanitizer so every runtime normalizes identically. The
+      # ensure_window identity is (current session/workspace, sanitized
+      # name); deterministic sanitization is what makes the idempotent
+      # by-name lookup stable.
+      module NameSanitizer
+        FALLBACK = "window"
+
+        module_function
+
+        def call(value, fallback: FALLBACK)
+          sanitized = sanitize(value)
+          return sanitized unless sanitized.empty?
+
+          fallback_result = sanitize(fallback)
+          fallback_result.empty? ? FALLBACK : fallback_result
+        end
+
+        def sanitize(value)
+          value.to_s
+            .gsub(/[^A-Za-z0-9_-]+/, "-")
+            .gsub(/-+/, "-")
+            .gsub(/\A-|-+\z/, "")
+        end
+        private_class_method :sanitize
+      end
+    end
+  end
+end

data/lib/ace/runtime/atoms/send_contract.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Atoms
+      # Central send-shape validation and normalization. Runs BEFORE any
+      # adapter transport call: a SendRejectedError guarantees the
+      # adapter made no native call. Adapters declare exactly one
+      # send_profile (:plain_pane or :agent_aware) and normalize their
+      # public send input through this contract; the shared adapter
+      # contract suite (Ace::Runtime::Testing::AdapterContract) enforces
+      # the normative matrix for both profiles.
+      #
+      # Normalized request shape:
+      # - plain_pane: `command` is submitted once (with Enter); `items`
+      #   are delivered afterwards in order — messages as raw text
+      #   (no implicit submission), keys as keystrokes.
+      # - agent_aware: `command` is always nil; the prompt (from
+      #   `command` or the concatenated messages) is the single leading
+      #   `{message:}` entry and submits itself; remaining items are
+      #   trailing keys. At most one trailing Enter is dropped and
+      #   reported via `dropped_trailing_enter`.
+      module SendContract
+        PROFILES = %i[plain_pane agent_aware].freeze
+
+        # The four lifecycle observations wait_lifecycle accepts; a wait
+        # reports the condition only and never authorizes completion,
+        # receipts, or pruning.
+        LIFECYCLE_CONDITIONS = %w[window-exists window-active pane-exists pane-exited].freeze
+
+        Request = Struct.new(:profile, :command, :items, :dropped_trailing_enter, keyword_init: true)
+        Result = Struct.new(:dropped_trailing_enter, keyword_init: true)
+
+        ENTER_PATTERN = /\Aenter\z/i
+        PROMPT_JOIN = "\n"
+
+        module_function
+
+        def normalize!(command:, items:, profile:)
+          unless PROFILES.include?(profile)
+            raise ArgumentError, "unknown send profile '#{profile}' (expected one of: #{PROFILES.join(', ')})"
+          end
+
+          normalized_command = normalize_command(command)
+          normalized_items = normalize_items(items)
+          require_content!(normalized_command, normalized_items)
+          command_requires_key_items!(normalized_command, normalized_items)
+
+          return plain_request(normalized_command, normalized_items) if profile == :plain_pane
+
+          agent_aware_request(normalized_command, normalized_items)
+        end
+
+        # Convenience shape: send(command:) — submit once.
+        def command_request(command:, profile:)
+          normalize!(command: command, items: [], profile: profile)
+        end
+
+        # Convenience shape: send(items: keys.map { {key: _1} }).
+        def keys_request(keys, profile:)
+          items = Array(keys).map { |name| {key: name} }
+          normalize!(command: nil, items: items, profile: profile)
+        end
+
+        def normalize_command(command)
+          text = command.to_s
+          return nil if text.strip.empty?
+
+          text
+        end
+
+        def normalize_items(items)
+          Array(items).each_with_index.map { |item, index| normalize_item(item, index) }
+        end
+
+        private_class_method def self.normalize_item(item, index)
+          unless item.is_a?(Hash) && item.size == 1
+            raise SendRejectedError,
+              "items[#{index}] must be a single-key {message: String} or {key: String} hash"
+          end
+
+          name, value = item.first
+          case name.to_s
+          when "message"
+            unless value.is_a?(String) && !value.empty?
+              raise SendRejectedError, "items[#{index}] message must be a non-empty String"
+            end
+
+            {message: value}
+          when "key"
+            key_name = value.to_s.strip
+            raise SendRejectedError, "items[#{index}] key must be a non-empty key name" if key_name.empty?
+
+            {key: key_name}
+          else
+            raise SendRejectedError, "items[#{index}] must use :message or :key (got :#{name})"
+          end
+        end
+
+        def require_content!(command, items)
+          return if command || !items.empty?
+
+          raise SendRejectedError, "send requires content: a nonblank command or at least one message/key item"
+        end
+
+        def command_requires_key_items!(command, items)
+          return unless command
+          return if items.all? { |item| item.key?(:key) }
+
+          raise SendRejectedError,
+            "command submits on its own: when command is present, items must be post-command keys only"
+        end
+
+        def plain_request(command, items)
+          Request.new(profile: :plain_pane, command: command, items: items, dropped_trailing_enter: false)
+        end
+
+        def agent_aware_request(command, items)
+          messages = items.select { |item| item.key?(:message) }
+          keys = items.select { |item| item.key?(:key) }
+          enter_count = keys.count { |item| enter?(item[:key]) }
+          raise SendRejectedError, "agent panes accept at most one Enter per send" if enter_count > 1
+
+          if command
+            non_enter_keys = keys.reject { |item| enter?(item[:key]) }
+            unless non_enter_keys.empty?
+              raise SendRejectedError, "command on an agent pane only supports a single trailing Enter key"
+            end
+
+            return prompt_request(command, dropped: enter_count == 1)
+          end
+
+          if messages.any?
+            if keys.length > 1 || (keys.length == 1 && !enter?(keys.first[:key]))
+              raise SendRejectedError,
+                "agent panes reject interleaved input: messages may only be followed by a single Enter"
+            end
+
+            return prompt_request(messages.map { |item| item[:message] }.join(PROMPT_JOIN), dropped: enter_count == 1)
+          end
+
+          Request.new(profile: :agent_aware, command: nil, items: keys, dropped_trailing_enter: false)
+        end
+
+        def prompt_request(prompt, dropped:)
+          Request.new(
+            profile: :agent_aware,
+            command: nil,
+            items: [{message: prompt}],
+            dropped_trailing_enter: dropped
+          )
+        end
+
+        def enter?(key_name)
+          !key_name.to_s.strip.match(ENTER_PATTERN).nil?
+        end
+      end
+    end
+  end
+end