harnex 0.2.0

data/lib/harnex/runtime/inbox.rb

@@ -0,0 +1,207 @@
+require "securerandom"
+
+module Harnex
+  class Inbox
+    DEFAULT_TTL = 120
+    MAX_PENDING = 64
+    DELIVERY_TIMEOUT = 300
+
+    def initialize(session, state_machine, ttl: DEFAULT_TTL)
+      @session = session
+      @state_machine = state_machine
+      @ttl = ttl.to_f
+      @queue = []
+      @messages = {}
+      @mutex = Mutex.new
+      @condvar = ConditionVariable.new
+      @thread = nil
+      @running = false
+      @delivered_total = 0
+      @expired_total = 0
+    end
+
+    def start
+      @running = true
+      @thread = Thread.new { delivery_loop }
+    end
+
+    def stop
+      @running = false
+      @mutex.synchronize { @condvar.broadcast }
+      @thread&.join(2)
+      @thread&.kill
+    end
+
+    def enqueue(text:, submit:, enter_only:, force: false)
+      msg = Message.new(
+        id: SecureRandom.hex(8),
+        text: text,
+        submit: submit,
+        enter_only: enter_only,
+        force: force,
+        queued_at: Time.now,
+        status: :queued
+      )
+
+      # Force messages bypass the queue entirely
+      if force
+        return deliver_now(msg)
+      end
+
+      # Fast path: prompt ready and queue empty — deliver immediately.
+      # Check under lock, then release before calling deliver_now to
+      # avoid recursive locking (deliver_now also acquires @mutex).
+      try_fast = @mutex.synchronize do
+        @queue.empty? && @state_machine.state == :prompt
+      end
+
+      if try_fast
+        begin
+          result = deliver_now(msg)
+          return result if msg.status == :delivered
+        rescue StandardError
+          # Fall through to queue if delivery failed
+        end
+        msg.status = :queued
+        msg.error = nil
+      end
+
+      @mutex.synchronize do
+        raise "inbox full (#{MAX_PENDING} pending messages)" if @queue.size >= MAX_PENDING
+
+        @queue << msg
+        @messages[msg.id] = msg
+        @condvar.broadcast
+      end
+
+      { ok: true, status: "queued", message_id: msg.id, http_status: 202 }
+    end
+
+    def message_status(id)
+      @mutex.synchronize do
+        msg = @messages[id]
+        return nil unless msg
+        msg.to_h
+      end
+    end
+
+    def stats
+      @mutex.synchronize do
+        { pending: @queue.size, delivered_total: @delivered_total, expired_total: @expired_total }
+      end
+    end
+
+    def pending_messages
+      @mutex.synchronize { @queue.map(&:to_h) }
+    end
+
+    def drop(message_id)
+      @mutex.synchronize do
+        msg = @messages[message_id]
+        return nil unless msg && @queue.any? { |queued| queued.id == message_id }
+
+        @queue.delete_if { |queued| queued.id == message_id }
+        msg.status = :dropped
+        msg.to_h
+      end
+    end
+
+    def clear
+      @mutex.synchronize do
+        count = @queue.size
+        @queue.each { |msg| msg.status = :dropped }
+        @queue.clear
+        count
+      end
+    end
+
+    private
+
+    def deliver_now(msg)
+      result = @session.inject_via_adapter(
+        text: msg.text,
+        submit: msg.submit,
+        enter_only: msg.enter_only,
+        force: msg.force
+      )
+      msg.status = :delivered
+      msg.delivered_at = Time.now
+      @mutex.synchronize do
+        @delivered_total += 1
+        @messages[msg.id] = msg
+      end
+      result.merge(ok: true, status: "delivered", message_id: msg.id, http_status: 200)
+    rescue ArgumentError => e
+      msg.status = :failed
+      msg.error = e.message
+      @mutex.synchronize { @messages[msg.id] = msg }
+      raise
+    end
+
+    def delivery_loop
+      while @running
+        msg = @mutex.synchronize do
+          expire_stale_messages_locked
+          while @queue.empty? && @running
+            @condvar.wait(@mutex, 1.0)
+            expire_stale_messages_locked
+          end
+          @queue.first
+        end
+
+        break unless @running
+        next unless msg
+
+        ready = @state_machine.wait_for_prompt(prompt_wait_timeout)
+        unless ready
+          next if @running # Keep waiting
+        end
+
+        msg = @mutex.synchronize do
+          expire_stale_messages_locked
+          @queue.first
+        end
+        next unless msg
+
+        begin
+          deliver_now(msg)
+          @mutex.synchronize { @queue.shift if @queue.first&.id == msg.id }
+        rescue ArgumentError
+          # State race — will retry on next loop iteration
+          sleep 0.1
+        rescue StandardError => e
+          msg.status = :failed
+          msg.error = e.message
+          @mutex.synchronize do
+            @queue.shift
+            @messages[msg.id] = msg
+          end
+        end
+      end
+    end
+
+    def expire_stale_messages
+      @mutex.synchronize { expire_stale_messages_locked }
+    end
+
+    def expire_stale_messages_locked(now = Time.now)
+      while (msg = @queue.first) && stale_message?(msg, now)
+        msg.status = :expired
+        @queue.shift
+        @expired_total += 1
+      end
+    end
+
+    def stale_message?(msg, now)
+      return false unless msg.queued_at
+
+      (now - msg.queued_at) > @ttl
+    end
+
+    def prompt_wait_timeout
+      return 0.1 if @ttl <= 0.0
+
+      [DELIVERY_TIMEOUT.to_f, @ttl].min
+    end
+  end
+end

data/lib/harnex/runtime/message.rb

@@ -0,0 +1,23 @@
+module Harnex
+  Message = Struct.new(:id, :text, :submit, :enter_only, :force, :queued_at, :status, :delivered_at, :error, keyword_init: true) do
+    def to_h
+      {
+        id: id,
+        status: status.to_s,
+        queued_at: queued_at&.iso8601,
+        delivered_at: delivered_at&.iso8601,
+        text_preview: preview_text,
+        error: error
+      }
+    end
+
+    private
+
+    def preview_text(limit = 80)
+      compact = text.to_s.gsub(/\s+/, " ").strip
+      return compact if compact.length <= limit
+
+      "#{compact[0, limit - 3]}..."
+    end
+  end
+end

data/lib/harnex/runtime/session.rb

@@ -0,0 +1,380 @@
+require "io/console"
+require "json"
+require "pty"
+
+module Harnex
+  class Session
+    OUTPUT_BUFFER_LIMIT = 64 * 1024
+
+    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :output_log_path
+
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, inbox_ttl: Inbox::DEFAULT_TTL)
+      @adapter = adapter
+      @command = command
+      @repo_root = repo_root
+      @host = host
+      @id = Harnex.normalize_id(id)
+      @watch = watch
+      @description = description.to_s.strip
+      @description = nil if @description.empty?
+      @registry_path = Harnex.registry_path(repo_root, @id)
+      @output_log_path = Harnex.output_log_path(repo_root, @id)
+      @session_id = SecureRandom.hex(8)
+      @token = SecureRandom.hex(16)
+      @port = Harnex.allocate_port(repo_root, @id, port, host: host)
+      @mutex = Mutex.new
+      @inject_mutex = Mutex.new
+      @injected_count = 0
+      @last_injected_at = nil
+      @started_at = Time.now
+      @server = nil
+      @reader = nil
+      @output_log = nil
+      @writer = nil
+      @pid = nil
+      @term_signal = nil
+      @output_buffer = +""
+      @output_buffer.force_encoding(Encoding::BINARY)
+      @state_machine = SessionState.new(adapter)
+      @inbox = Inbox.new(self, @state_machine, ttl: inbox_ttl)
+    end
+
+    def self.validate_binary!(command)
+      binary = Array(command).first.to_s
+      raise BinaryNotFound, "\"\" not found — is it installed and on your PATH?" if binary.empty?
+
+      if binary.include?("/")
+        return binary if File.executable?(binary) && !File.directory?(binary)
+
+        raise BinaryNotFound, "\"#{binary}\" not found — is it installed and on your PATH?"
+      end
+
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        path = File.join(dir, binary)
+        return path if File.executable?(path) && !File.directory?(path)
+      end
+
+      raise BinaryNotFound, "\"#{binary}\" not found — is it installed and on your PATH?"
+    end
+
+    def run(validate_binary: true)
+      validate_binary! if validate_binary
+      prepare_output_log
+      @reader, @writer, @pid = PTY.spawn(child_env, *command)
+      @writer.sync = true
+
+      install_signal_handlers
+      sync_window_size
+      @server = ApiServer.new(self)
+      @server.start
+      persist_registry
+
+      stdin_state = STDIN.tty? ? STDIN.raw! : nil
+      watch_thread = start_watch_thread
+      @inbox.start
+      input_thread = start_input_thread
+      output_thread = start_output_thread
+
+      _, status = Process.wait2(pid)
+      @term_signal = status.signaled? ? status.termsig : nil
+      @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+
+      output_thread.join(1)
+      input_thread&.kill
+      watch_thread&.kill
+      @exit_code
+    ensure
+      @inbox.stop
+      STDIN.cooked! if STDIN.tty? && stdin_state
+      @server&.stop
+      persist_exit_status
+      cleanup_registry
+      @reader&.close unless @reader&.closed?
+      @output_log&.close unless @output_log&.closed?
+      @writer&.close unless @writer&.closed?
+    end
+
+    def status_payload(include_input_state: true)
+      payload = {
+        ok: true,
+        session_id: session_id,
+        repo_root: repo_root,
+        repo_key: Harnex.repo_key(repo_root),
+        cli: adapter.key,
+        id: id,
+        pid: pid,
+        host: host,
+        port: port,
+        command: command,
+        started_at: @started_at.iso8601,
+        last_injected_at: @last_injected_at&.iso8601,
+        injected_count: @injected_count,
+        output_log_path: output_log_path
+      }
+      payload[:description] = description if description
+
+      if watch
+        payload[:watch_path] = watch.display_path
+        payload[:watch_absolute_path] = watch.absolute_path
+        payload[:watch_debounce_seconds] = watch.debounce_seconds
+      end
+
+      payload[:input_state] = adapter.input_state(screen_snapshot) if include_input_state
+      payload[:agent_state] = @state_machine.to_s
+      payload[:inbox] = @inbox.stats
+      payload
+    end
+
+    def auth_ok?(header)
+      header == "Bearer #{token}"
+    end
+
+    def inject(text, newline: true)
+      raise "session is not running" unless pid && Harnex.alive_pid?(pid)
+
+      inject_sequence([{ text: text, newline: newline }])
+    end
+
+    def inject_stop
+      raise "session is not running" unless pid && Harnex.alive_pid?(pid)
+
+      @inject_mutex.synchronize do
+        adapter.inject_exit(@writer)
+        @state_machine.force_busy!
+      end
+
+      { ok: true, signal: "exit_sequence_sent" }
+    end
+
+    def inject_via_adapter(text:, submit:, enter_only:, force: false)
+      snapshot = adapter.wait_for_sendable(method(:screen_snapshot), submit: submit, enter_only: enter_only, force: force)
+      payload = adapter.build_send_payload(
+        text: text,
+        submit: submit,
+        enter_only: enter_only,
+        screen_text: snapshot,
+        force: force
+      )
+
+      result =
+        if payload[:steps]
+          inject_sequence(payload.fetch(:steps))
+        else
+          inject(payload.fetch(:text), newline: payload.fetch(:newline, false))
+        end
+
+      result.merge(
+        cli: adapter.key,
+        input_state: payload[:input_state],
+        force: payload[:force]
+      )
+    end
+
+    def sync_window_size
+      return unless STDIN.tty?
+
+      @writer.winsize = STDIN.winsize
+    rescue StandardError
+      nil
+    end
+
+    def validate_binary!
+      self.class.validate_binary!(command)
+    end
+
+    private
+
+    def child_env
+      env = {
+        "HARNEX_SESSION_ID" => session_id,
+        "HARNEX_SESSION_CLI" => adapter.key,
+        "HARNEX_ID" => id,
+        "HARNEX_SESSION_REPO_ROOT" => repo_root
+      }
+      env["HARNEX_DESCRIPTION"] = description if description
+      env
+    end
+
+    def inject_sequence(steps)
+      @inject_mutex.synchronize do
+        total_bytes = 0
+        newline = false
+
+        steps.each do |step|
+          delay_ms = step[:delay_ms].to_i
+          sleep(delay_ms / 1000.0) if delay_ms.positive?
+
+          payload = step.fetch(:text, "").dup
+          newline = step.fetch(:newline, false)
+          payload << "\n" if newline
+          total_bytes += write_payload(payload)
+        end
+
+        result = finish_injection(bytes_written: total_bytes, newline: newline)
+        @state_machine.force_busy!
+        result
+      end
+    end
+
+    def write_payload(payload)
+      @mutex.synchronize do
+        bytes = @writer.write(payload)
+        @writer.flush
+        bytes
+      end
+    end
+
+    def finish_injection(bytes_written:, newline:)
+      injected_count = @mutex.synchronize do
+        @injected_count += 1
+        @last_injected_at = Time.now
+        persist_registry
+        @injected_count
+      end
+
+      {
+        ok: true,
+        bytes_written: bytes_written,
+        injected_count: injected_count,
+        newline: newline
+      }
+    end
+
+    def registry_payload
+      status_payload(include_input_state: false).merge(
+        token: token,
+        cwd: Dir.pwd
+      )
+    end
+
+    def persist_registry
+      payload = registry_payload
+      preserved = load_existing_registry_metadata
+      payload = payload.merge(preserved) unless preserved.empty?
+      Harnex.write_registry(@registry_path, payload)
+    end
+
+    def persist_exit_status
+      return unless defined?(@exit_code) && !@exit_code.nil?
+
+      exit_path = Harnex.exit_status_path(repo_root, id)
+      payload = {
+        ok: true,
+        id: id,
+        cli: adapter.key,
+        session_id: session_id,
+        repo_root: repo_root,
+        exit_code: @exit_code,
+        started_at: @started_at.iso8601,
+        exited_at: Time.now.iso8601,
+        injected_count: @injected_count
+      }
+      payload[:signal] = @term_signal if @term_signal
+      Harnex.write_registry(exit_path, payload)
+    rescue StandardError
+      nil
+    end
+
+    def cleanup_registry
+      current = File.exist?(@registry_path) ? JSON.parse(File.read(@registry_path)) : nil
+      return unless current && current["session_id"] == session_id
+
+      FileUtils.rm_f(@registry_path)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def start_input_thread
+      Thread.new do
+        loop do
+          chunk = STDIN.readpartial(4096)
+          @inject_mutex.synchronize do
+            @mutex.synchronize do
+              @writer.write(chunk)
+              @writer.flush
+            end
+          end
+        rescue EOFError, Errno::EIO, IOError
+          break
+        end
+      end
+    end
+
+    def start_output_thread
+      Thread.new do
+        loop do
+          chunk = @reader.readpartial(4096)
+          record_output(chunk)
+          STDOUT.write(chunk)
+          STDOUT.flush
+        rescue EOFError, Errno::EIO, IOError
+          break
+        end
+      end
+    end
+
+    def start_watch_thread
+      return nil unless watch
+
+      FileChangeHook.new(self, watch).start
+    end
+
+    def prepare_output_log
+      @output_log&.close unless @output_log&.closed?
+      @output_log = File.open(output_log_path, "ab")
+      @output_log.sync = true
+      @output_log_failed = false
+    end
+
+    def install_signal_handlers
+      %w[INT TERM HUP QUIT].each do |signal_name|
+        Signal.trap(signal_name) { forward_signal(signal_name) }
+      end
+      Signal.trap("WINCH") { sync_window_size }
+    end
+
+    def forward_signal(signal_name)
+      return unless pid
+
+      Process.kill(signal_name, pid)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def record_output(chunk)
+      snapshot = @mutex.synchronize do
+        append_output_log(chunk)
+        @output_buffer << chunk
+        overflow = @output_buffer.bytesize - OUTPUT_BUFFER_LIMIT
+        @output_buffer = @output_buffer.byteslice(overflow, OUTPUT_BUFFER_LIMIT) if overflow.positive?
+        @output_buffer.dup
+      end
+      @state_machine.update(snapshot)
+    end
+
+    def append_output_log(chunk)
+      return unless @output_log
+
+      @output_log.write(chunk)
+    rescue StandardError => e
+      return if defined?(@output_log_failed) && @output_log_failed
+
+      @output_log_failed = true
+      warn("harnex: failed to write output log #{output_log_path}: #{e.message}")
+    end
+
+    def screen_snapshot
+      @mutex.synchronize { @output_buffer.dup }
+    end
+
+    def load_existing_registry_metadata
+      return {} unless File.exist?(@registry_path)
+
+      JSON.parse(File.read(@registry_path)).each_with_object({}) do |(key, value), memo|
+        memo[key] = value if key.start_with?("tmux_")
+      end
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/harnex/runtime/session_state.rb

@@ -0,0 +1,55 @@
+module Harnex
+  class SessionState
+    STATES = %i[prompt busy blocked unknown].freeze
+
+    attr_reader :state
+
+    def initialize(adapter)
+      @adapter = adapter
+      @state = :unknown
+      @mutex = Mutex.new
+      @condvar = ConditionVariable.new
+    end
+
+    def update(screen_snapshot)
+      input = @adapter.input_state(screen_snapshot)
+      new_state =
+        case input[:input_ready]
+        when true  then :prompt
+        when false then :blocked
+        else            :unknown
+        end
+
+      @mutex.synchronize do
+        old = @state
+        @state = new_state
+        @condvar.broadcast if old != new_state
+      end
+
+      new_state
+    end
+
+    def force_busy!
+      @mutex.synchronize do
+        @state = :busy
+        @condvar.broadcast
+      end
+    end
+
+    def wait_for_prompt(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        loop do
+          return true if @state == :prompt
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return false if remaining <= 0
+          @condvar.wait(@mutex, remaining)
+        end
+      end
+    end
+
+    def to_s
+      @mutex.synchronize { @state.to_s }
+    end
+  end
+end

data/lib/harnex/version.rb

@@ -0,0 +1,3 @@
+module Harnex
+  VERSION = "0.2.0"
+end

data/lib/harnex/watcher/inotify.rb

@@ -0,0 +1,43 @@
+require "fiddle/import"
+
+module Harnex
+  module Inotify
+    extend Fiddle::Importer
+
+    IN_ATTRIB = 0x00000004
+    IN_CLOSE_WRITE = 0x00000008
+    IN_CREATE = 0x00000100
+    IN_MOVED_TO = 0x00000080
+
+    @available = false
+    begin
+      dlload Fiddle.dlopen(nil)
+      extern "int inotify_init(void)"
+      extern "int inotify_add_watch(int, const char*, unsigned int)"
+      @available = true
+    rescue Fiddle::DLError
+      @available = false
+    end
+
+    class << self
+      def available?
+        @available
+      end
+
+      def directory_io(path, mask)
+        raise "inotify is not available on this system" unless available?
+
+        fd = inotify_init
+        raise "could not initialize file watch" if fd.negative?
+
+        watch_id = inotify_add_watch(fd, path, mask)
+        if watch_id.negative?
+          IO.for_fd(fd, autoclose: true)&.close
+          raise "could not watch #{path}"
+        end
+
+        IO.for_fd(fd, "rb", autoclose: true)
+      end
+    end
+  end
+end