harnex 0.5.0 → 0.6.2

data/lib/harnex/adapters/codex_appserver.rb

@@ -0,0 +1,411 @@
+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, :initial_prompt
+
+      def initialize(extra_args = [])
+        super("codex", extra_args)
+        @initial_prompt = extra_args.join(" ").strip
+        @initial_prompt = nil if @initial_prompt.empty?
+        @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 build_command
+        base_command
+      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
+
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+        state = input_state(nil)
+        if !force && submit && !enter_only && state[:input_ready] != true
+          raise ArgumentError, blocked_message(state, enter_only: enter_only)
+        end
+        raise ArgumentError, "Codex app-server cannot stage input without submitting it" unless submit || enter_only
+        raise ArgumentError, "Codex app-server does not support submit-only input" if enter_only
+
+        {
+          dispatch: { prompt: text.to_s },
+          input_state: state,
+          force: force
+        }
+      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
+
+      def blocked_message(state, enter_only:)
+        return super if enter_only
+
+        "Codex app-server is not at a prompt; wait and retry or use `harnex send --force` (state: #{state[:state]})"
+      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

@@ -29,8 +29,10 @@ module Harnex
         Recipes.new(@argv.drop(1)).run
       when "guide"
         Guide.new.run
-      when "skills"
-        Skills.new(@argv.drop(1)).run
+      when "agents-guide"
+        AgentsGuide.new(@argv.drop(1)).run
+      when "doctor"
+        Doctor.new(@argv.drop(1)).run
       when "help"
         puts help(@argv[1])
         0
@@ -69,8 +71,10 @@ module Harnex
         Recipes.usage
       when "guide"
         Guide.usage
-      when "skills"
-        Skills.usage
+      when "agents-guide"
+        AgentsGuide.usage
+      when "doctor"
+        Doctor.usage
       else
         usage
       end
@@ -87,6 +91,8 @@ module Harnex
           harnex logs --id ID [options]
           harnex events --id ID [options]
           harnex pane --id ID [options]
+          harnex agents-guide [topic]
+          harnex doctor
           harnex help [command]
 
         Commands:
@@ -100,10 +106,13 @@ module Harnex
           pane    Capture the current tmux pane for a live session
           recipes List and read workflow recipes
           guide   Show the getting started guide
-          skills  Install bundled skills into a repo or globally
+          agents-guide
+                  Show agent dispatch, chain, buddy, monitoring, and naming guides
+          doctor  Run preflight checks for adapter dependencies
           help    Show command help
 
         New to harnex? Start with: harnex guide
+        Working with agents (dispatching tasks)? Read: harnex agents-guide
 
         Notes:
           CLIs with smart prompt detection: #{Adapters.known.join(', ')}
@@ -117,8 +126,9 @@ module Harnex
           harnex logs --id main --follow
           harnex events --id main --snapshot
           harnex pane --id main --lines 40
+          harnex agents-guide dispatch
+          harnex doctor
           harnex send --id main --message "Summarize current progress."
-          harnex skills install
       TEXT
     end
   end

data/lib/harnex/commands/agents_guide.rb

@@ -0,0 +1,109 @@
+module Harnex
+  class AgentsGuide
+    GUIDES_DIR = File.expand_path("../../../../guides", __FILE__)
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex agents-guide [list|show <topic>|<topic>]
+
+        Subcommands:
+          list           List available agent guide topics (default)
+          show <topic>   Print a guide by name or number
+
+        Examples:
+          harnex agents-guide
+          harnex agents-guide list
+          harnex agents-guide show 01
+          harnex agents-guide show dispatch
+          harnex agents-guide monitoring
+
+        Common patterns:
+          harnex agents-guide dispatch
+          harnex agents-guide chain
+          harnex agents-guide naming
+
+        Gotchas:
+          Agent guides replace the old harnex skills install flow.
+          They are packaged with the gem and require no external project docs.
+      TEXT
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      subcommand = @argv.shift
+      case subcommand
+      when nil, "list"
+        list_guides
+      when "show"
+        show_guide(@argv.first)
+      when "-h", "--help"
+        puts self.class.usage
+        0
+      else
+        show_guide(subcommand)
+      end
+    end
+
+    private
+
+    def list_guides
+      files = guide_files
+      if files.empty?
+        puts "No agent guides found."
+        return 0
+      end
+
+      puts "Agent guides:\n\n"
+      files.each do |file|
+        name = File.basename(file, ".md")
+        title = extract_title(file)
+        puts "  #{name}  #{title}"
+      end
+      puts "\nRun `harnex agents-guide show <topic>` to read one."
+      0
+    end
+
+    def show_guide(query)
+      unless query
+        warn("harnex agents-guide show: topic required")
+        return 1
+      end
+
+      file = find_guide(query)
+      unless file
+        warn("harnex agents-guide: no topic matching #{query.inspect}")
+        warn("Run `harnex agents-guide list` to see available topics.")
+        return 1
+      end
+
+      puts File.read(file)
+      0
+    end
+
+    def find_guide(query)
+      files = guide_files
+
+      exact = files.find { |file| File.basename(file, ".md") == query }
+      return exact if exact
+
+      prefix = files.find { |file| File.basename(file, ".md").start_with?(query) }
+      return prefix if prefix
+
+      files.find { |file| File.basename(file, ".md").include?(query) }
+    end
+
+    def guide_files
+      return [] unless Dir.exist?(GUIDES_DIR)
+
+      Dir.glob(File.join(GUIDES_DIR, "*.md")).sort
+    end
+
+    def extract_title(file)
+      first_line = File.foreach(file).first.to_s.strip
+      first_line.start_with?("#") ? first_line.sub(/^#+\s*/, "") : ""
+    end
+  end
+end

data/lib/harnex/commands/doctor.rb

@@ -0,0 +1,83 @@
+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).
+
+        Common patterns:
+          harnex doctor
+          harnex doctor --help
+
+        Gotchas:
+          doctor validates local adapter prerequisites; it does not start sessions.
+          Run it after installing or upgrading Codex CLI.
+      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

data/lib/harnex/commands/events.rb

@@ -18,6 +18,16 @@ module Harnex
           --snapshot      Print current events and exit (alias for --no-follow)
           --from TS       Replay floor (ISO-8601, inclusive)
           -h, --help      Show this help
+
+        Common patterns:
+          #{program_name} --id cx-i-42 --snapshot
+          #{program_name} --id cx-i-42
+          #{program_name} --id cx-i-42 --from 2026-05-06T10:00:00Z --snapshot
+
+        Gotchas:
+          events is structured JSONL; logs is human transcript text.
+          Default mode follows live events. Use --snapshot to print and exit.
+          Use wait --until task_complete when you only need a completion fence.
       TEXT
     end