agent-harness 0.5.6 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 946d7c425aff8c96536bc30def7e0abdba7ff7d82020f4941674a8c93be63526
-  data.tar.gz: ffc9d707f89ab60bf9cc59b4e5ccbcd2570a3aaa07e97c5a10bfb731f5dc07a0
+  metadata.gz: 2335caa6b19fc12579028ec7c9796c89e588629c7e076b957cac4c6b563d9fdb
+  data.tar.gz: f7bbe39c811548d1f92262ece7d696d9e8486a93c3d494c7cf397c294f41901e
 SHA512:
-  metadata.gz: c7b0dcef83c7a31be09a87884211a8ba03c0c93fb845e666423cd17eb70a358dd122db7e57ce04271fa5e114013adbc0007394211286c23b03cfa6a2a600c68f
-  data.tar.gz: a8f14eb24039afd0a93ec1eb064b59ebbe6d03aafd61ab1859c64729d2253140afebacc5c8ee761578337c671c074425784c33676808534cdf7b8ad809a2df32
+  metadata.gz: e46f340daf52837fa0ae966b5bb2ce1865338b5b9d20d5901b380696e9fac91f35471ec1ef1512f08cc3305346185dfbfd20c2e4a05c2f7ac7d1b466e9dbc5f5
+  data.tar.gz: f6e5c23023174cabf7609b5bf61bc8d07e0a527fa6cc2b219eb19265c1f917897cd846360513c9819a33b970e4180443f0a98a9bc02746bf5c57bafc5ba16b1c

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.6"
+  ".": "0.5.7"
 }

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.5.7](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.6...agent-harness/v0.5.7) (2026-04-07)
+
+
+### Bug Fixes
+
+* 59: fix(codex): replace invalid '--sandbox none' for externally sandboxed runs ([#89](https://github.com/viamin/agent-harness/issues/89)) ([6b0fac5](https://github.com/viamin/agent-harness/commit/6b0fac5e9b83c70c3a55004d9c5ad354a6d3dced))
+* 60: feat: support per-request executor overrides for orchestrated send_message ([#87](https://github.com/viamin/agent-harness/issues/87)) ([7711770](https://github.com/viamin/agent-harness/commit/7711770ab3c9a6659171df1033038acf08b8d5a9))
+* 61: feat: support idle-timeout and streaming execution hooks for long-running provider runs ([#90](https://github.com/viamin/agent-harness/issues/90)) ([adf7558](https://github.com/viamin/agent-harness/commit/adf75583994f78af9d6f5b44eba729b616b46f02))
+* 62: feat: support per-request environment unsets for provider execution ([#76](https://github.com/viamin/agent-harness/issues/76)) ([2dfdb8e](https://github.com/viamin/agent-harness/commit/2dfdb8e6138f21ca0dd1a9e0b2d7cc17d1776612))
+* 63: fix(copilot): align GithubCopilot provider with a real installable CLI contract ([#75](https://github.com/viamin/agent-harness/issues/75)) ([9e585e7](https://github.com/viamin/agent-harness/commit/9e585e79252ac8431fb99bc16bc9ebbecb83439e))
+* 65: feat(installers): make Codex CLI installation/version support a first-class provider contract ([#79](https://github.com/viamin/agent-harness/issues/79)) ([a3f5849](https://github.com/viamin/agent-harness/commit/a3f5849db1bcfa162af98fa5339cf8b8f5314920))
+* 66: feat(installers): make Gemini CLI installation/version support a first-class provider contract ([#80](https://github.com/viamin/agent-harness/issues/80)) ([e349ab6](https://github.com/viamin/agent-harness/commit/e349ab64601cb2fe9bafb488e6b4f96fbcbf012b))
+* 67: feat(installers): make Kilocode CLI installation/version support a first-class provider contract ([#81](https://github.com/viamin/agent-harness/issues/81)) ([547baf5](https://github.com/viamin/agent-harness/commit/547baf5be93939a00cdac1e3d17824eb6dbfb324))
+* 68: feat(installers): make OpenCode CLI installation/version support a first-class provider contract ([#83](https://github.com/viamin/agent-harness/issues/83)) ([21caaf4](https://github.com/viamin/agent-harness/commit/21caaf4e003c41a7fa127e7244c4a61abad7f1cb))
+* 72: feat(providers): add first-class smoke-test/health-check execution contracts for CLI providers ([#85](https://github.com/viamin/agent-harness/issues/85)) ([7c0db3a](https://github.com/viamin/agent-harness/commit/7c0db3a5aa93e62e38240821dfb00b489ad3793b))
+
 ## [0.5.6](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.5...agent-harness/v0.5.6) (2026-03-30)
 
 

data/README.md

@@ -106,7 +106,25 @@ end
 | `:codex` | `codex` | OpenAI Codex CLI |
 | `:aider` | `aider` | Aider coding assistant |
 | `:opencode` | `opencode` | OpenCode CLI |
-| `:kilocode` | `kilocode` | Kilocode CLI |
+| `:kilocode` | `kilo` | Kilocode CLI |
+
+### Provider Install Contracts
+
+Provider classes can expose install metadata for downstream apps that build
+their own agent images.
+
+```ruby
+contract = AgentHarness.provider_install_contract(:gemini)
+
+contract[:package_name]
+# => "@google/gemini-cli"
+
+contract[:default_version]
+# => "0.35.3"
+
+contract[:install_command]
+# => ["npm", "install", "-g", "--ignore-scripts", "@google/gemini-cli@0.35.3"]
+```
 
 ### Direct Provider Access
 
@@ -125,6 +143,50 @@ AgentHarness::Providers::Registry.instance.all
 # => [:claude, :cursor, :gemini, :github_copilot, :codex, :opencode, :kilocode, :aider]
 ```
 
+### Provider Installation Contracts
+
+Downstream apps can ask `agent-harness` for provider-specific CLI install
+metadata instead of hardcoding package names, binary names, or supported
+versions out-of-band.
+
+```ruby
+contract = AgentHarness.provider_installation_contract(:kilocode, version: "7.1.3")
+
+contract
+# {
+#   source: { type: :npm, package: "@kilocode/cli" },
+#   install_command: ["npm", "install", "-g", "--ignore-scripts", "@kilocode/cli@7.1.3"],
+#   binary_name: "kilo",
+#   default_version: "7.1.3",
+#   supported_version_requirement: "= 7.1.3"
+# }
+```
+
+The Kilocode runtime adapter expects the `kilo` binary and executes prompts via
+`kilo run ...`, so the install contract and runtime behavior stay aligned in
+tests.
+
+Providers that expose installation contracts can also be queried through the
+generic API:
+
+```ruby
+opencode_install = AgentHarness.installation_contract(:opencode)
+
+opencode_install
+# => {
+#      source: :npm,
+#      package_name: "opencode-ai",
+#      version: "1.3.2",
+#      version_requirement: [">= 1.3.2", "< 1.4.0"],
+#      binary_name: "opencode",
+#      install_command: ["npm", "install", "-g", "--ignore-scripts", "opencode-ai@1.3.2"]
+#    }
+```
+
+For providers with install contracts, the metadata tracks the CLI version
+supported by the current `agent-harness` release, and the runtime adapter
+tests assert that the expected binary remains aligned with that contract.
+
 ### Custom Providers
 
 ```ruby
@@ -138,6 +200,19 @@ class MyProvider < AgentHarness::Providers::Base
       "my-cli"
     end
 
+    def install_contract(version: "1.2.3")
+      {
+        provider: provider_name,
+        source_type: :npm,
+        package_name: "@acme/my-cli",
+        supported_version_requirement: Gem::Requirement.new("~> 1.2"),
+        default_version: "1.2.3",
+        resolved_version: version,
+        binary_name: binary_name,
+        install_command: ["npm", "install", "-g", "@acme/my-cli@#{version}"]
+      }
+    end
+
     def available?
       system("which my-cli > /dev/null 2>&1")
     end

data/lib/agent_harness/command_executor.rb

@@ -39,23 +39,47 @@ module AgentHarness
     #
     # @param command [Array<String>, String] command to execute
     # @param timeout [Integer, nil] timeout in seconds
+    # @param idle_timeout [Integer, Float, nil] idle timeout in seconds based on output activity
     # @param env [Hash] environment variables
     # @param stdin_data [String, nil] data to send to stdin
+    # @param on_stdout_chunk [Proc, nil] callback for stdout chunks as they are produced
+    # @param on_stderr_chunk [Proc, nil] callback for stderr chunks as they are produced
+    # @param on_heartbeat [Proc, nil] callback invoked periodically while the command is running
+    # @param heartbeat_interval [Integer, Float] heartbeat interval in seconds
+    # @param observer [Object, nil] optional observer responding to
+    #   +on_stdout_chunk+, +on_stderr_chunk+, and +on_heartbeat+
     # @return [Result] execution result
     # @raise [TimeoutError] if the command times out
-    def execute(command, timeout: nil, env: {}, stdin_data: nil)
+    # @raise [IdleTimeoutError] if the command exceeds the idle timeout
+    def execute(command, timeout: nil, idle_timeout: nil, env: {}, stdin_data: nil,
+      on_stdout_chunk: nil, on_stderr_chunk: nil, on_heartbeat: nil,
+      heartbeat_interval: 1.0, observer: nil)
+      validate_duration!(timeout, name: :timeout, allow_nil: true)
+      validate_duration!(idle_timeout, name: :idle_timeout, allow_nil: true)
+      validate_duration!(heartbeat_interval, name: :heartbeat_interval, allow_nil: true)
+
       cmd_array = normalize_command(command)
       cmd_string = cmd_array.shelljoin
 
-      log_debug("Executing command", command: cmd_string, timeout: timeout)
+      log_debug("Executing command",
+        command: cmd_string,
+        timeout: timeout,
+        idle_timeout: idle_timeout)
 
       start_time = Time.now
 
-      stdout, stderr, status = if timeout
-        execute_with_timeout(cmd_array, timeout: timeout, env: env, stdin_data: stdin_data)
-      else
-        execute_without_timeout(cmd_array, env: env, stdin_data: stdin_data)
-      end
+      stdout, stderr, status = execute_streaming(
+        cmd_array,
+        timeout: timeout,
+        idle_timeout: idle_timeout,
+        env: env,
+        stdin_data: stdin_data,
+        on_stdout_chunk: on_stdout_chunk,
+        on_stderr_chunk: on_stderr_chunk,
+        on_heartbeat: on_heartbeat,
+        heartbeat_interval: heartbeat_interval,
+        observer: observer
+      )
 
       duration = Time.now - start_time
 
@@ -102,47 +126,444 @@ module AgentHarness
 
     private
 
-    def execute_with_timeout(cmd_array, timeout:, env:, stdin_data:)
-      stdout = ""
-      stderr = ""
-      status = nil
+    def execute_streaming(cmd_array, timeout:, idle_timeout:, env:, stdin_data:,
+      on_stdout_chunk:, on_stderr_chunk:, on_heartbeat:, heartbeat_interval:, observer:)
+      stdout = +""
+      stderr = +""
 
-      Timeout.timeout(timeout) do
-        Open3.popen3(env, *cmd_array) do |stdin, stdout_io, stderr_io, wait_thr|
-          if stdin_data
-            stdin.write(stdin_data)
+      Open3.popen3(env, *cmd_array, pgroup: true) do |stdin, stdout_io, stderr_io, wait_thr|
+        unless selectable_streams?(stdin, stdout_io, stderr_io)
+          return execute_buffered(
+            stdin,
+            stdout_io,
+            stderr_io,
+            wait_thr,
+            stdin_data: stdin_data,
+            stdout: stdout,
+            stderr: stderr,
+            timeout: timeout,
+            idle_timeout: idle_timeout,
+            cmd_array: cmd_array,
+            on_stdout_chunk: on_stdout_chunk,
+            on_stderr_chunk: on_stderr_chunk,
+            on_heartbeat: on_heartbeat,
+            heartbeat_interval: heartbeat_interval,
+            observer: observer
+          )
+        end
+
+        start_time = monotonic_time
+        last_output_at = start_time
+        last_heartbeat_at = start_time
+        stdin_buffer = stdin_data.is_a?(String) ? stdin_data : stdin_data.to_s
+        stdin_offset = 0
+        streams = {
+          stdout_io => [stdout, on_stdout_chunk, :on_stdout_chunk],
+          stderr_io => [stderr, on_stderr_chunk, :on_stderr_chunk]
+        }
+
+        until streams.empty? && stdin.nil?
+          ready = IO.select(streams.keys, stdin ? [stdin] : nil, nil, 0)
+
+          if ready
+            stdin, stdin_offset, last_output_at = process_ready_streams(
+              ready,
+              streams: streams,
+              stdin: stdin,
+              stdin_buffer: stdin_buffer,
+              stdin_offset: stdin_offset,
+              last_output_at: last_output_at,
+              observer: observer,
+              wait_thr: wait_thr
+            )
+
+            if process_exited?(wait_thr)
+              stdin, last_output_at = finalize_exited_process(
+                stdin, streams, observer, last_output_at, wait_thr,
+                timeout: timeout, idle_timeout: idle_timeout, start_time: start_time, cmd_array: cmd_array
+              )
+              next
+            end
+
+            now = monotonic_time
+            if should_emit_heartbeat?(on_heartbeat, observer, heartbeat_interval, now - last_heartbeat_at)
+              emit_heartbeat(
+                on_heartbeat,
+                observer,
+                elapsed: now - start_time,
+                idle_for: now - last_output_at,
+                wait_thr: wait_thr
+              )
+              last_heartbeat_at = now
+            end
+
+            check_wall_timeout!(timeout, now - start_time, wait_thr, cmd_array)
+            check_idle_timeout!(idle_timeout, now - last_output_at, wait_thr, cmd_array)
+            next
           end
-          stdin.close
 
-          # Read output streams
-          stdout = stdout_io.read
-          stderr = stderr_io.read
-          status = wait_thr.value
+          if process_exited?(wait_thr)
+            stdin, last_output_at = finalize_exited_process(
+              stdin, streams, observer, last_output_at, wait_thr,
+              timeout: timeout, idle_timeout: idle_timeout, start_time: start_time, cmd_array: cmd_array
+            )
+            next
+          end
+
+          now = monotonic_time
+          check_wall_timeout!(timeout, now - start_time, wait_thr, cmd_array)
+          check_idle_timeout!(idle_timeout, now - last_output_at, wait_thr, cmd_array)
+
+          if should_emit_heartbeat?(on_heartbeat, observer, heartbeat_interval, now - last_heartbeat_at)
+            emit_heartbeat(
+              on_heartbeat,
+              observer,
+              elapsed: now - start_time,
+              idle_for: now - last_output_at,
+              wait_thr: wait_thr
+            )
+            last_heartbeat_at = now
+          end
+
+          ready = IO.select(
+            streams.keys,
+            stdin ? [stdin] : nil,
+            nil,
+            select_timeout(
+              timeout,
+              idle_timeout,
+              heartbeat_interval,
+              elapsed: now - start_time,
+              idle_for: now - last_output_at,
+              heartbeat_age: now - last_heartbeat_at,
+              heartbeat_requested: on_heartbeat || observer_responds_to?(observer, :on_heartbeat)
+            )
+          )
+
+          unless ready
+            if process_exited?(wait_thr)
+              stdin, last_output_at = finalize_exited_process(
+                stdin, streams, observer, last_output_at, wait_thr,
+                timeout: timeout, idle_timeout: idle_timeout, start_time: start_time, cmd_array: cmd_array
+              )
+            end
+            next
+          end
+
+          stdin, stdin_offset, last_output_at = process_ready_streams(
+            ready,
+            streams: streams,
+            stdin: stdin,
+            stdin_buffer: stdin_buffer,
+            stdin_offset: stdin_offset,
+            last_output_at: last_output_at,
+            observer: observer,
+            wait_thr: wait_thr
+          )
+
+          if process_exited?(wait_thr)
+            stdin, last_output_at = finalize_exited_process(
+              stdin, streams, observer, last_output_at, wait_thr,
+              timeout: timeout, idle_timeout: idle_timeout, start_time: start_time, cmd_array: cmd_array
+            )
+          end
         end
+
+        # Supervise the wait for process exit so a child that closed its
+        # stdio but keeps running cannot hang past the configured timeouts.
+        unless process_exited?(wait_thr)
+          supervise_process_exit(
+            wait_thr,
+            timeout: timeout,
+            idle_timeout: idle_timeout,
+            start_time: start_time,
+            last_output_at: last_output_at,
+            cmd_array: cmd_array,
+            on_heartbeat: on_heartbeat,
+            observer: observer,
+            heartbeat_interval: heartbeat_interval,
+            last_heartbeat_at: last_heartbeat_at
+          )
+        end
+
+        [stdout, stderr, wait_thr.value]
       end
+    end
 
-      [stdout, stderr, status]
+    def log_debug(message, **context)
+      @logger&.debug("[AgentHarness::CommandExecutor] #{message}: #{context.inspect}")
+    end
+
+    def selectable_streams?(*streams)
+      streams.all? { |stream| stream.is_a?(IO) }
+    end
+
+    def execute_buffered(stdin, stdout_io, stderr_io, wait_thr, stdin_data:, stdout:, stderr:, timeout:, idle_timeout:,
+      cmd_array:, on_stdout_chunk:, on_stderr_chunk:, on_heartbeat:, heartbeat_interval:, observer:)
+      validate_buffered_execution_support!(
+        idle_timeout: idle_timeout,
+        on_heartbeat: on_heartbeat,
+        heartbeat_interval: heartbeat_interval,
+        observer: observer
+      )
+
+      result = lambda do
+        write_stdin_buffered(stdin, stdin_data)
+
+        stdout_chunk = stdout_io.read.to_s
+        stderr_chunk = stderr_io.read.to_s
+
+        unless stdout_chunk.empty?
+          stdout << stdout_chunk
+          emit_chunk(on_stdout_chunk, observer, :on_stdout_chunk, stdout_chunk, wait_thr: wait_thr)
+        end
+
+        unless stderr_chunk.empty?
+          stderr << stderr_chunk
+          emit_chunk(on_stderr_chunk, observer, :on_stderr_chunk, stderr_chunk, wait_thr: wait_thr)
+        end
+
+        [stdout, stderr, wait_thr.value]
+      end
+
+      return result.call unless timeout
+
+      Timeout.timeout(timeout) do
+        result.call
+      end
     rescue Timeout::Error
+      terminate_process(wait_thr)
       raise TimeoutError, "Command timed out after #{timeout} seconds: #{cmd_array.first}"
     end
 
-    def execute_without_timeout(cmd_array, env:, stdin_data:)
-      Open3.popen3(env, *cmd_array) do |stdin, stdout_io, stderr_io, wait_thr|
-        if stdin_data
-          stdin.write(stdin_data)
+    def write_stdin_buffered(stdin, stdin_data)
+      return unless stdin
+
+      stdin.write(stdin_data.to_s)
+      close_stream(stdin)
+    rescue Errno::EPIPE, IOError
+      close_stream(stdin)
+    end
+
+    def write_stdin_nonblock(stdin, stdin_buffer, stdin_offset)
+      return stdin_buffer.bytesize if stdin_offset >= stdin_buffer.bytesize
+
+      chunk = stdin_buffer.byteslice(stdin_offset, 4096)
+      written = stdin.write_nonblock(chunk, exception: false)
+      return stdin_offset if written == :wait_writable
+
+      stdin_offset + written
+    end
+
+    def process_ready_streams(ready, streams:, stdin:, stdin_buffer:, stdin_offset:, last_output_at:, observer:, wait_thr:)
+      ready[1]&.each do |io|
+        stdin_offset = write_stdin_nonblock(io, stdin_buffer, stdin_offset)
+        next unless stdin_offset >= stdin_buffer.bytesize
+
+        close_stream(io)
+        stdin = nil
+      rescue Errno::EPIPE, IOError
+        close_stream(io)
+        stdin = nil
+      end
+
+      ready[0]&.each do |io|
+        chunk = io.read_nonblock(4096, exception: false)
+
+        case chunk
+        when :wait_readable
+          next
+        when nil
+          streams.delete(io)
+          io.close
+        else
+          buffer, callback, observer_method = streams.fetch(io) do
+            raise KeyError, "Unexpected ready stream for command execution"
+          end
+          buffer << chunk
+          last_output_at = monotonic_time
+          emit_chunk(callback, observer, observer_method, chunk, wait_thr: wait_thr)
         end
-        stdin.close
+      end
+
+      [stdin, stdin_offset, last_output_at]
+    end
+
+    def close_stream(stream)
+      return unless stream
+
+      stream.close
+    rescue IOError
+      nil
+    end
+
+    def process_exited?(wait_thr)
+      !wait_thr.join(0).nil?
+    end
+
+    # Drain remaining output from an exited process's streams.
+    #
+    # Uses nonblocking reads with timeout supervision so that descendant
+    # processes holding stdout/stderr open cannot hang past the configured
+    # wall-clock or idle timeout.
+    def finalize_exited_process(stdin, streams, observer, last_output_at, wait_thr,
+      timeout: nil, idle_timeout: nil, start_time: nil, cmd_array: nil)
+      close_stream(stdin) if stdin
+
+      until streams.empty?
+        ready = IO.select(streams.keys, nil, nil, 0.1)
+
+        if ready
+          ready[0].each do |io|
+            chunk = io.read_nonblock(4096, exception: false)
+
+            case chunk
+            when :wait_readable
+              next
+            when nil
+              streams.delete(io)
+              close_stream(io)
+            else
+              buffer, callback, observer_method = streams.fetch(io)
+              buffer << chunk
+              last_output_at = monotonic_time
+              emit_chunk(callback, observer, observer_method, chunk, wait_thr: wait_thr)
+            end
+          end
+        end
+
+        now = monotonic_time
+        check_wall_timeout!(timeout, now - start_time, wait_thr, cmd_array) if start_time
+        check_idle_timeout!(idle_timeout, now - last_output_at, wait_thr, cmd_array)
+      end
+
+      [nil, last_output_at]
+    end
+
+    # Poll for process exit with timeout and heartbeat supervision.
+    # Called after all streams are closed when the child is still running.
+    def supervise_process_exit(wait_thr, timeout:, idle_timeout:, start_time:,
+      last_output_at:, cmd_array:, on_heartbeat:, observer:,
+      heartbeat_interval:, last_heartbeat_at:)
+      loop do
+        break if process_exited?(wait_thr)
 
-        stdout = stdout_io.read
-        stderr = stderr_io.read
-        status = wait_thr.value
+        now = monotonic_time
+        check_wall_timeout!(timeout, now - start_time, wait_thr, cmd_array)
+        check_idle_timeout!(idle_timeout, now - last_output_at, wait_thr, cmd_array)
 
-        [stdout, stderr, status]
+        if should_emit_heartbeat?(on_heartbeat, observer, heartbeat_interval, now - last_heartbeat_at)
+          emit_heartbeat(
+            on_heartbeat,
+            observer,
+            elapsed: now - start_time,
+            idle_for: now - last_output_at,
+            wait_thr: wait_thr
+          )
+          last_heartbeat_at = now
+        end
+
+        wait_timeout = select_timeout(
+          timeout, idle_timeout, heartbeat_interval,
+          elapsed: now - start_time,
+          idle_for: now - last_output_at,
+          heartbeat_age: now - last_heartbeat_at,
+          heartbeat_requested: on_heartbeat || observer_responds_to?(observer, :on_heartbeat)
+        )
+        # Sleep briefly before re-checking, bounded by the next deadline
+        sleep([wait_timeout || 0.1, 0.1].min)
       end
     end
 
-    def log_debug(message, **context)
-      @logger&.debug("[AgentHarness::CommandExecutor] #{message}: #{context.inspect}")
+    def validate_duration!(value, name:, allow_nil: false)
+      return if allow_nil && value.nil?
+      return if value.is_a?(Numeric) && value.positive?
+
+      raise InvalidDurationError, "#{name} must be a positive number"
+    end
+
+    def validate_buffered_execution_support!(idle_timeout:, on_heartbeat:, heartbeat_interval:, observer:)
+      heartbeat_requested = on_heartbeat || observer_responds_to?(observer, :on_heartbeat)
+      unsupported_supervision = idle_timeout || (heartbeat_requested && !heartbeat_interval.nil?)
+      return unless unsupported_supervision
+
+      raise ArgumentError, "Buffered command execution does not support idle timeouts or heartbeats"
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def check_wall_timeout!(timeout, elapsed, wait_thr, cmd_array)
+      return unless timeout && elapsed >= timeout
+
+      terminate_process(wait_thr)
+      raise TimeoutError, "Command timed out after #{timeout} seconds: #{cmd_array.first}"
+    end
+
+    def check_idle_timeout!(idle_timeout, idle_for, wait_thr, cmd_array)
+      return unless idle_timeout && idle_for >= idle_timeout
+
+      terminate_process(wait_thr)
+      raise IdleTimeoutError,
+        "Command exceeded idle timeout after #{idle_timeout} seconds: #{cmd_array.first}"
+    end
+
+    def should_emit_heartbeat?(callback, observer, heartbeat_interval, heartbeat_age)
+      return false unless callback || observer_responds_to?(observer, :on_heartbeat)
+      return false if heartbeat_interval.nil?
+
+      heartbeat_age >= heartbeat_interval
+    end
+
+    def emit_chunk(callback, observer, observer_method, chunk, wait_thr: nil)
+      callback&.call(chunk)
+      observer.public_send(observer_method, chunk) if observer_responds_to?(observer, observer_method)
+    rescue
+      terminate_process(wait_thr) if wait_thr
+      raise
+    end
+
+    def emit_heartbeat(callback, observer, elapsed:, idle_for:, wait_thr: nil)
+      callback&.call(elapsed: elapsed, idle_for: idle_for)
+      observer.on_heartbeat(elapsed: elapsed, idle_for: idle_for) if observer_responds_to?(observer, :on_heartbeat)
+    rescue
+      terminate_process(wait_thr) if wait_thr
+      raise
+    end
+
+    def observer_responds_to?(observer, method_name)
+      observer&.respond_to?(method_name)
+    end
+
+    def select_timeout(timeout, idle_timeout, heartbeat_interval, elapsed:, idle_for:, heartbeat_age:, heartbeat_requested:)
+      timeouts = []
+      timeouts << (timeout - elapsed) if timeout
+      timeouts << (idle_timeout - idle_for) if idle_timeout
+      timeouts << (heartbeat_interval - heartbeat_age) if heartbeat_requested && heartbeat_interval
+
+      min_timeout = timeouts.min
+      return nil unless min_timeout
+
+      [min_timeout, 0].max
+    end
+
+    def terminate_process(wait_thr)
+      pid = wait_thr.pid
+      signal_process("TERM", pid)
+      Timeout.timeout(1) { wait_thr.join }
+    rescue Errno::ESRCH, Timeout::Error
+      begin
+        signal_process("KILL", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+
+    def signal_process(signal, pid)
+      Process.kill(signal, -pid)
+    rescue Errno::ESRCH
+      Process.kill(signal, pid)
     end
   end
 end