harnex 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d7c194ba2ba10ee075e6e53aa3eaf291cbfc08eca1d89cd291955834230c01
-  data.tar.gz: e3bafc087ae74a484be3ee121cce0d8f351c6b381ce244d5da032e48c85da4db
+  metadata.gz: 0003e780e17784a566b09e37d39ca760531d78ef8b912093944bb7f1eb65c134
+  data.tar.gz: 58f1ec4d5919c19a7b445900aff28143636a530470e7d04bf1962532661d308e
 SHA512:
-  metadata.gz: e3737c2aa49fb223c75cfc0d997a52bb72029b4c1a7a11affdd05a16c685e4edc42384ff0cfc03e63e4b4abcc9228c7f1d37c408c074538392c75d13be4e1e5e
-  data.tar.gz: 0b096fb9d95f22b812fc43fc69b4f8546e090d76c669383b8d71b34a048aa8eed46510f7ce9be27e0da3eab449a610c13fd6a338d8e1c202649d235df7052154
+  metadata.gz: f979f0c86edf2ac6a694b20e75392ed23059a43a38ea4de7a3620c3270589d08bacd880e5c4ec660859b4430528bb8ae56b90399397010fdb87e06c9ac926847
+  data.tar.gz: f109e68a8165cef5627ffa5a2a0ca1afb8e8ace1809591bdefdce6a7e7e8259c2db5e8764bbf06ec191ef7197beef45653377f7e5f0742535ffe5402f28ce12d

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.6.0 — 2026-05-06
+
+### Architectural pivot: Codex on JSON-RPC
+
+harnex now speaks `codex app-server` JSON-RPC over stdio for the
+Codex adapter. Pane-scraping is retired for Codex. Closed by
+construction:
+
+- #22 (Codex side; `--watch --stall-after` still applies to
+  claude/generic)
+- #24 (disconnect detection — `error` notifications and JSON-RPC
+  error responses replace screen-text regex)
+- #25 (first-class completion signal — `turn/completed` is it)
+
+### New
+
+- `harnex wait --until task_complete` — block until a turn completes.
+  Example: `harnex wait --id cx-i-242 --until task_complete`.
+  Adapter-agnostic; tails the events JSONL.
+- `harnex status --json` includes `last_completed_at`, `model`,
+  `effort`, `auto_disconnects`.
+- `harnex doctor` preflight checks Codex CLI ≥ 0.128.0.
+- `Adapter#transport` and `Adapter#describe` extension points so
+  callers can introspect adapter contracts. Default is
+  `:pty` for backward compatibility.
+
+### Migration
+
+- Codex CLI ≥ 0.128.0 required.
+- Existing `harnex run codex ...` invocations work unchanged.
+- Emergency fallback: `harnex run codex --legacy-pty ...` (the
+  pre-0.6.0 PTY adapter). Deprecated; will be removed in 0.7.0.
+
+### Cross-repo
+
+- Resolves holm #201 from the harnex side. holm #271 (substrate v2
+  meta) tracks the broader pivot.

data/TECHNICAL.md

@@ -321,7 +321,25 @@ The adapter reads the screen and returns a state hash:
 | `confirmation`           | `false`       | Modal confirmation    |
 | `unknown`                | `nil`         | Can't determine       |
 
-### Codex Adapter
+### Codex Adapter (default — JSON-RPC `app-server`)
+
+- `transport :stdio_jsonrpc` — speaks JSON-RPC 2.0 over the
+  subprocess's stdin/stdout, one JSON object per line.
+- Launches `codex app-server` (Codex CLI ≥ 0.128.0; verify with
+  `harnex doctor`).
+- Notifications (`turn/started`, `turn/completed`, `item/completed`,
+  `error`, `thread/compacted`, …) fan into the events log.
+  `task_complete` is the harnex-side event for `turn/completed`.
+- Disconnect is detected from JSON-RPC error responses, subprocess
+  EOF, parse errors, or a server `error` notification — no screen
+  regex required.
+- Synthesized transcript: `item/completed` text payloads stream to
+  both the output log and STDOUT so tmux/pane workflows continue to
+  work without a real PTY.
+- See `docs/codex-appserver.md` for the full mapping table and
+  troubleshooting.
+
+#### Codex Adapter (legacy PTY — `--legacy-pty`, removal in 0.7.0)
 
 - Launches with `--no-alt-screen` for inline screen output
 - Detects prompt by looking for `›` prefix in recent lines

data/lib/harnex/adapters/base.rb

@@ -20,6 +20,16 @@ module Harnex
         @extra_args = extra_args.dup
       end
 
+      # Default transport. Adapters speaking JSON-RPC override to
+      # :stdio_jsonrpc; Session#run uses this to pick the I/O path.
+      def transport
+        :pty
+      end
+
+      def describe
+        { transport: transport }
+      end
+
       def build_command
         base_command + @extra_args
       end
@@ -39,6 +49,10 @@ module Harnex
         }
       end
 
+      def parse_session_summary(_transcript_tail)
+        {}
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         0.0
       end

data/lib/harnex/adapters/codex.rb

@@ -56,6 +56,25 @@ module Harnex
         end
       end
 
+      def parse_session_summary(transcript_tail)
+        summary = empty_session_summary
+        text = transcript_tail.to_s
+
+        if (match = text.match(/Token usage:\s+total=([\d,]+)\s+input=([\d,]+)(?:\s+\(\+\s+([\d,]+)\s+cached\))?\s+output=([\d,]+)(?:\s+\(reasoning\s+([\d,]+)\))?/))
+          summary[:total_tokens] = parse_token_count(match[1])
+          summary[:input_tokens] = parse_token_count(match[2])
+          summary[:cached_tokens] = parse_token_count(match[3])
+          summary[:output_tokens] = parse_token_count(match[4])
+          summary[:reasoning_tokens] = parse_token_count(match[5])
+        end
+
+        if (match = text.match(/codex resume\s+([0-9a-f-]{36})/))
+          summary[:agent_session_id] = match[1]
+        end
+
+        summary
+      end
+
       def send_wait_seconds(submit:, enter_only:)
         return 0.0 unless submit
         return 0.0 if enter_only
@@ -101,6 +120,23 @@ module Harnex
 
       protected
 
+      def empty_session_summary
+        {
+          input_tokens: nil,
+          output_tokens: nil,
+          reasoning_tokens: nil,
+          cached_tokens: nil,
+          total_tokens: nil,
+          agent_session_id: nil
+        }
+      end
+
+      def parse_token_count(value)
+        return nil if value.nil?
+
+        Integer(value.delete(","))
+      end
+
       def submit_delay_ms(text)
         extra = (text.to_s.bytesize / 1024.0 * SUBMIT_DELAY_PER_KB_MS).ceil
         SUBMIT_DELAY_MS + extra

data/lib/harnex/adapters/codex_appserver.rb

@@ -0,0 +1,390 @@
+require "json"
+require "open3"
+
+module Harnex
+  module Adapters
+    # Codex `app-server` adapter — JSON-RPC over stdio.
+    #
+    # Talks to a spawned `codex app-server` subprocess by writing
+    # newline-delimited JSON-RPC messages on stdin and reading
+    # responses + notifications from stdout. Replaces the pane-scraping
+    # heuristics in `Adapters::Codex` (legacy, kept behind --legacy-pty).
+    class CodexAppServer < Base
+      CLIENT_TITLE = "harnex"
+      CLIENT_NAME = "harnex"
+
+      OPT_OUT_NOTIFICATIONS = %w[
+        item/agentMessage/delta
+        item/reasoning/summaryTextDelta
+        item/reasoning/summaryPartAdded
+        item/reasoning/textDelta
+      ].freeze
+
+      REQUEST_METHODS = %w[
+        initialize thread/start turn/start turn/interrupt thread/resume
+      ].freeze
+
+      NOTIFICATION_METHODS = %w[
+        thread/started turn/started turn/completed
+        item/started item/completed
+        thread/status/changed thread/tokenUsage/updated
+        thread/compacted account/rateLimits/updated
+        error
+      ].freeze
+
+      EVENTS = %w[task_complete turn_started item_completed disconnected].freeze
+
+      attr_reader :thread_id, :current_turn_id, :last_completed_at
+
+      def initialize(extra_args = [])
+        super("codex", extra_args)
+        @client = nil
+        @thread_id = nil
+        @current_turn_id = nil
+        @state = :disconnected
+        @last_completed_at = nil
+        @notification_handler = nil
+        @disconnect_handler = nil
+      end
+
+      def transport
+        :stdio_jsonrpc
+      end
+
+      def base_command
+        ["codex", "app-server"]
+      end
+
+      def describe
+        {
+          transport: transport,
+          request_methods: REQUEST_METHODS,
+          notification_methods: NOTIFICATION_METHODS,
+          events: EVENTS
+        }
+      end
+
+      def state
+        @state
+      end
+
+      # Override: state is RPC-driven, screen text is ignored.
+      def input_state(_screen_text = nil)
+        {
+          state: @state.to_s,
+          input_ready: @state == :prompt
+        }
+      end
+
+      # The screen-based send path is not used for stdio_jsonrpc.
+      # Session#run_jsonrpc routes through #dispatch instead.
+      def build_send_payload(*)
+        raise NotImplementedError, "codex_appserver uses #dispatch, not screen-based send"
+      end
+
+      # No-op: closing the subprocess is handled via #close.
+      def inject_exit(_writer, **_kwargs)
+        nil
+      end
+
+      def on_notification(&block)
+        @notification_handler = block
+      end
+
+      def on_disconnect(&block)
+        @disconnect_handler = block
+      end
+
+      # Start the JSON-RPC client. In production, spawns the codex
+      # subprocess. In tests, callers may pass pre-built IO objects.
+      def start_rpc(env: nil, cwd: nil, read_io: nil, write_io: nil, pid: nil)
+        if read_io && write_io
+          @client = JsonRpcClient.new(read_io: read_io, write_io: write_io, pid: pid)
+        else
+          spawn_pid, child_stdin, child_stdout = spawn_subprocess(env, cwd)
+          @client = JsonRpcClient.new(read_io: child_stdout, write_io: child_stdin, pid: spawn_pid)
+        end
+
+        @client.on_notification { |msg| handle_notification(msg) }
+        @client.on_disconnect { |err| handle_disconnect(err) }
+        @client.start
+        perform_handshake
+        @state = :prompt
+        self
+      end
+
+      def dispatch(prompt:, model: nil, effort: nil)
+        ensure_open!
+        ensure_thread!
+        params = {
+          threadId: @thread_id,
+          input: { content: [{ type: "text", text: prompt.to_s }] }
+        }
+        params[:model] = model if model
+        params[:effort] = effort if effort
+
+        result = @client.request("turn/start", params)
+        @current_turn_id = result["turnId"] || result["turn_id"] || result["id"]
+        @state = :busy
+        @current_turn_id
+      end
+
+      def interrupt(turn_id: nil)
+        ensure_open!
+        target = turn_id || @current_turn_id
+        return nil if target.nil?
+
+        @client.request("turn/interrupt", { threadId: @thread_id, turnId: target })
+      end
+
+      def resume(thread_id:)
+        ensure_open!
+        result = @client.request("thread/resume", { threadId: thread_id })
+        @thread_id = thread_id
+        @state = :prompt
+        result
+      end
+
+      def close
+        return unless @client
+
+        @client.close
+        @client = nil
+        @state = :disconnected
+      end
+
+      def pid
+        @client&.pid
+      end
+
+      private
+
+      def ensure_open!
+        raise "codex_appserver: client not started" unless @client
+        raise "codex_appserver: disconnected" if @state == :disconnected
+      end
+
+      def ensure_thread!
+        return if @thread_id
+
+        result = @client.request("thread/start", {})
+        @thread_id = result["threadId"] || result["thread_id"]
+      end
+
+      def perform_handshake
+        @client.request("initialize", {
+          clientInfo: {
+            title: CLIENT_TITLE,
+            name: CLIENT_NAME,
+            version: Harnex::VERSION
+          },
+          capabilities: {
+            experimentalApi: false,
+            optOutNotificationMethods: OPT_OUT_NOTIFICATIONS
+          }
+        })
+        @client.notify("initialized", {})
+      end
+
+      def handle_notification(message)
+        method = message["method"]
+        params = message["params"] || {}
+
+        case method
+        when "thread/started"
+          @thread_id ||= params["threadId"] || params["thread_id"]
+        when "turn/started"
+          @current_turn_id = params["turnId"] || params["turn_id"]
+          @state = :busy
+        when "turn/completed"
+          @last_completed_at = Time.now
+          @current_turn_id = nil
+          @state = :prompt
+        when "error"
+          @state = :disconnected
+        end
+
+        @notification_handler&.call(message)
+      end
+
+      def handle_disconnect(error)
+        @state = :disconnected
+        @disconnect_handler&.call(error)
+      end
+
+      def spawn_subprocess(env, cwd)
+        spawn_env = env || {}
+        opts = {}
+        opts[:chdir] = cwd if cwd
+        stdin_io, stdout_io, _stderr_io, wait_thr =
+          Open3.popen3(spawn_env, *build_command, **opts)
+        [wait_thr.pid, stdin_io, stdout_io]
+      end
+
+      # Minimal JSON-RPC 2.0 client. One JSON object per line.
+      # Responses keyed by id; everything else is a notification.
+      class JsonRpcClient
+        attr_reader :pid
+
+        def initialize(read_io:, write_io:, pid: nil)
+          @read_io = read_io
+          @write_io = write_io
+          @pid = pid
+          @next_id = 1
+          @pending = {}
+          @id_mutex = Mutex.new
+          @write_mutex = Mutex.new
+          @notification_handler = nil
+          @disconnect_handler = nil
+          @disconnect_signaled = false
+          @closed = false
+          @reader_thread = nil
+        end
+
+        def on_notification(&block)
+          @notification_handler = block
+        end
+
+        def on_disconnect(&block)
+          @disconnect_handler = block
+        end
+
+        def start
+          @reader_thread = Thread.new { read_loop }
+        end
+
+        def request(method, params = {})
+          raise "codex_appserver client is closed" if @closed
+
+          queue = Queue.new
+          id = @id_mutex.synchronize do
+            assigned = @next_id
+            @next_id += 1
+            @pending[assigned] = queue
+            assigned
+          end
+
+          write_line({ jsonrpc: "2.0", id: id, method: method, params: params })
+          result = queue.pop
+          raise result if result.is_a?(Exception)
+
+          result
+        end
+
+        def notify(method, params = {})
+          return if @closed
+
+          write_line({ jsonrpc: "2.0", method: method, params: params })
+        end
+
+        def close
+          return if @closed
+
+          @closed = true
+
+          @id_mutex.synchronize do
+            @pending.each_value { |q| q.push(StandardError.new("codex_appserver client closed")) }
+            @pending.clear
+          end
+
+          begin
+            @write_io.close unless @write_io.closed?
+          rescue IOError
+            nil
+          end
+
+          if @pid && process_alive?(@pid)
+            sleep 0.05
+            begin
+              Process.kill("TERM", @pid)
+            rescue Errno::ESRCH
+              nil
+            end
+          end
+
+          @reader_thread&.join(2)
+        end
+
+        private
+
+        def write_line(message)
+          @write_mutex.synchronize do
+            @write_io.write(JSON.generate(message))
+            @write_io.write("\n")
+            @write_io.flush
+          end
+        rescue Errno::EPIPE, IOError
+          signal_disconnect(nil)
+        end
+
+        def read_loop
+          buffer = +""
+          loop do
+            chunk = @read_io.readpartial(4096)
+            buffer << chunk
+            while (idx = buffer.index("\n"))
+              line = buffer.slice!(0, idx + 1).chomp
+              next if line.strip.empty?
+
+              handle_line(line)
+            end
+          end
+        rescue EOFError, IOError, Errno::EIO
+          nil
+        ensure
+          signal_disconnect(nil)
+        end
+
+        def handle_line(line)
+          message = JSON.parse(line)
+        rescue JSON::ParserError => e
+          signal_disconnect(e)
+          return
+        else
+          dispatch_message(message)
+        end
+
+        def dispatch_message(message)
+          if message["id"] && message["method"]
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
+            })
+            return
+          end
+
+          if message.key?("id")
+            pending = @id_mutex.synchronize { @pending.delete(message["id"]) }
+            return unless pending
+
+            if message["error"]
+              err_msg = message.dig("error", "message") || "RPC error"
+              pending.push(StandardError.new("codex_appserver RPC error: #{err_msg}"))
+              signal_disconnect(message["error"])
+            else
+              pending.push(message["result"] || {})
+            end
+            return
+          end
+
+          @notification_handler&.call(message) if message["method"]
+        end
+
+        def signal_disconnect(error)
+          return if @disconnect_signaled
+
+          @disconnect_signaled = true
+          @disconnect_handler&.call(error)
+        end
+
+        def process_alive?(pid)
+          Process.kill(0, pid)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          false
+        end
+      end
+    end
+  end
+end

data/lib/harnex/adapters.rb

@@ -1,6 +1,7 @@
 require_relative "adapters/base"
 require_relative "adapters/generic"
 require_relative "adapters/codex"
+require_relative "adapters/codex_appserver"
 require_relative "adapters/claude"
 
 module Harnex
@@ -15,11 +16,23 @@ module Harnex
       !key.to_s.strip.empty?
     end
 
-    def build(key, extra_args = [])
-      adapter_class = registry[key.to_s]
+    # Phase 3 flipped the default — `codex` resolves to CodexAppServer.
+    # Legacy PTY adapter is reachable via `legacy_pty: true` (driven by
+    # `harnex run codex --legacy-pty`). Will be removed in 0.7.0.
+    def codex_appserver_enabled?
+      true
+    end
+
+    def build(key, extra_args = [], legacy_pty: false)
+      key_str = key.to_s
+      if key_str == "codex"
+        return legacy_pty ? Codex.new(extra_args) : CodexAppServer.new(extra_args)
+      end
+
+      adapter_class = registry[key_str]
       return adapter_class.new(extra_args) if adapter_class
 
-      Generic.new(key.to_s, extra_args)
+      Generic.new(key_str, extra_args)
     end
 
     def registry

data/lib/harnex/cli.rb

@@ -31,6 +31,8 @@ module Harnex
         Guide.new.run
       when "skills"
         Skills.new(@argv.drop(1)).run
+      when "doctor"
+        Doctor.new(@argv.drop(1)).run
       when "help"
         puts help(@argv[1])
         0
@@ -101,6 +103,7 @@ module Harnex
           recipes List and read workflow recipes
           guide   Show the getting started guide
           skills  Install bundled skills into a repo or globally
+          doctor  Run preflight checks for adapter dependencies
           help    Show command help
 
         New to harnex? Start with: harnex guide

data/lib/harnex/commands/doctor.rb

@@ -0,0 +1,75 @@
+require "json"
+
+module Harnex
+  class Doctor
+    MIN_CODEX_VERSION = Gem::Version.new("0.128.0")
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex doctor
+
+        Runs preflight checks for harnex's adapter dependencies.
+        Currently verifies that Codex CLI is installed and at version
+        >= #{MIN_CODEX_VERSION} (required for the JSON-RPC `app-server`
+        adapter).
+      TEXT
+    end
+
+    def initialize(argv = [])
+      @argv = argv.dup
+    end
+
+    def run
+      if @argv.include?("-h") || @argv.include?("--help")
+        puts self.class.usage
+        return 0
+      end
+
+      checks = [check_codex]
+      summary = {
+        ok: checks.all? { |c| c[:ok] },
+        checks: checks
+      }
+      puts JSON.generate(summary)
+      summary[:ok] ? 0 : 1
+    end
+
+    private
+
+    def check_codex
+      result = { name: "codex", required: ">= #{MIN_CODEX_VERSION}" }
+
+      version_output, status = capture("codex --version")
+      if status.nil?
+        return result.merge(ok: false, error: "codex CLI not found on PATH")
+      end
+      unless status.success?
+        return result.merge(ok: false, error: "codex --version failed: #{version_output.strip}")
+      end
+
+      version = parse_version(version_output)
+      if version.nil?
+        return result.merge(ok: false, found: version_output.strip, error: "could not parse codex version output")
+      end
+
+      if version < MIN_CODEX_VERSION
+        return result.merge(ok: false, found: version.to_s,
+                            error: "codex #{version} < required #{MIN_CODEX_VERSION}; upgrade with `npm i -g @openai/codex` or your platform package manager")
+      end
+
+      result.merge(ok: true, found: version.to_s)
+    end
+
+    def capture(command)
+      output = `#{command} 2>&1`
+      [output, $?]
+    rescue StandardError => e
+      [e.message, nil]
+    end
+
+    def parse_version(text)
+      match = text.match(/(\d+\.\d+\.\d+)/)
+      match ? Gem::Version.new(match[1]) : nil
+    end
+  end
+end