harnex 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7c3f452ed6de7b0468cbafff82c603beb7f880458168a9acf433d4f2747bbd9
-  data.tar.gz: 24ff11cfd9f02d509e7f0720589dc4658c7acff5eefea78029146f292b3010e7
+  metadata.gz: 354a4709831de10c8d19c40fbc4efa5b6df3d3fb1d0459fe1f4960b986eef8ad
+  data.tar.gz: 43e0617dac379a90281798fb7f1bd6973177111341d25cd29a1f0c6166580ada
 SHA512:
-  metadata.gz: 7d401086cf7cc01a563a34901076175c769ceb06165ef5d875dc5f1ebb722b241ec02b43d7d086575ef2fb78186f30ba3f427fc8dcd0984d44c8ce5accf13527
-  data.tar.gz: 10927dc8202b920ef3cdd5dd0a9e728c56e6673bc19cf5fac58f3aea85a52a6ac4b5cabd8a11f856152c3f492241c17e11e1b7a155809283554894784eb301a5
+  metadata.gz: 3213b7c38243f315b9cb3dfed677c63211d7148e166393f8b599088c14d7d0128ebfd0e583068182c0fff8419e483abd8f0e0f2230c37a25beb4bb6d812d0463
+  data.tar.gz: 1aeb182b6e355df8dce1f8445ebfcc3bedea8c7a5655590ca3eeac900b5fdcbef38786a88ef9dc8d3d0eaf2717dc330a3e34e98965ef18af6ef6f5b105d50e95

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.6.4] — 2026-05-06
+
+### Fixed
+
+- JSON-RPC adapter (`codex app-server`): harnex now mediates Codex's
+  server-to-client approval requests via the protocol — auto-approves
+  `applyPatchApproval`, `execCommandApproval`,
+  `item/commandExecution/requestApproval`, and
+  `item/fileChange/requestApproval`. Previously the adapter rejected
+  every server-side request with `-32601 "Unsupported server request"`,
+  which meant Codex's default sandbox blocked shell exec, file changes,
+  git commits, and package-manager invocations whenever a dispatched
+  worker tried to do real work. Autonomous worker dispatches now run
+  cleanly under the default sandbox without needing
+  `--dangerously-bypass-approvals-and-sandbox` or
+  `-c sandbox_mode=danger-full-access`.
+- `CodexAppServer#build_command` now appends operator-supplied codex
+  flags (passed via `harnex run codex -- -c key=value`) while still
+  filtering out the harnex-context entry that `--context` smuggles
+  through `@extra_args` (codex `app-server` rejects positional input).
+
+### Changed
+
+- `--legacy-pty` is now a long-term supported fallback rather than a
+  deprecated path. The 0.7.0-removal plan is dropped — the legacy PTY
+  adapter remains the right tool for interactive/TUI use cases and for
+  any operator who prefers terminal-native Codex chrome. JSON-RPC
+  remains the default for autonomous worker dispatches and structured
+  observability.
+
+### Added
+
+- JSON-RPC adapter: classify sub-5s pre-turn exits as `boot_failure`
+  (vs the existing `disconnected` terminal state), tracked by latching
+  on `turn/started`. `build_summary_actual` counts `boot_failure` exits
+  in `actual.disconnections` so early-boot deaths are not lost from
+  dispatch telemetry. First of three planned commits for issue #32;
+  remaining work (ensure-block telemetry write + optional `last_error`
+  capture) tracked separately.
+
+## [0.6.3] — 2026-05-06
+
+### Fixed
+
+- JSON-RPC adapter (`codex app-server`): `--context` boot injection now
+  succeeds against real Codex CLI. Three schema mismatches in
+  `Adapters::CodexAppServer` caused 100% session disconnect on boot
+  with `"Invalid request: invalid type: null, expected a string"`:
+  - `ensure_thread!` and the `thread/started` notification handler read
+    `result["threadId"]`, but Codex's actual `thread/start` response is
+    `{"thread": {"id": "..."}}`. With `@thread_id = nil`, the subsequent
+    `turn/start` sent `threadId: null` and Codex's serde rejected it.
+  - `dispatch` sent `input: { content: [{type, text}] }`, but
+    `TurnStartParams.input` is an **array** of `UserInput`. Now sends
+    `input: [{type: "text", text: "..."}]`.
+  - `initialize` joined ALL `extra_args` into `@initial_prompt`, which
+    prepended Codex CLI flags (e.g. `-m gpt-5.5-mini -c
+    model_reasoning_effort=low`) into the prompt content. Now extracts
+    only the harnex-prefixed context element.
+
+  Re-opens and properly closes #29. The 0.6.2 fix shipped clean tests
+  but the test stubs mirrored harnex's wrong assumptions instead of
+  Codex's actual JSON-RPC schema, so production was 100% broken on the
+  default JSON-RPC path.
+
+### Notes
+
+- Test stubs in `codex_appserver_lifecycle_test.rb` and
+  `session_jsonrpc_test.rb` still mirror harnex's old assumptions.
+  Tracked as a follow-up (test rewrite using `codex app-server
+  generate-json-schema` as the source of truth, plus a contract-test
+  gate). Existing tests remain green; the structural improvement does
+  not block this release.
+- `--legacy-pty` remains as the documented fallback. Removal still
+  scheduled for 0.7.0 once test-rewrite + contract gate land.
+
 ## [0.6.2] — 2026-05-06
 
 ### Fixed

data/TECHNICAL.md

@@ -330,6 +330,16 @@ The adapter reads the screen and returns a state hash:
 - 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`.
+- **Approval mediation**: Codex's app-server protocol delegates
+  sandbox/approval decisions to the JSON-RPC client via server-to-
+  client requests. Harnex auto-approves `applyPatchApproval`,
+  `execCommandApproval`, `item/commandExecution/requestApproval`, and
+  `item/fileChange/requestApproval`, so autonomous workers can run
+  shell commands, write files, commit, and invoke package managers
+  under Codex's default sandbox without any bypass flag. Other
+  server-to-client requests (permissions, user-input, dynamic-tool,
+  auth-refresh) currently fall through to `-32601` until use cases
+  appear.
 - Disconnect is detected from JSON-RPC error responses, subprocess
   EOF, parse errors, or a server `error` notification — no screen
   regex required.
@@ -339,7 +349,7 @@ The adapter reads the screen and returns a state hash:
 - See `docs/codex-appserver.md` for the full mapping table and
   troubleshooting.
 
-#### Codex Adapter (legacy PTY — `--legacy-pty`, removal in 0.7.0)
+#### Codex Adapter (legacy PTY — `--legacy-pty`, long-term fallback)
 
 - Launches with `--no-alt-screen` for inline screen output
 - Detects prompt by looking for `›` prefix in recent lines

data/lib/harnex/adapters/codex_appserver.rb

@@ -34,12 +34,25 @@ module Harnex
 
       EVENTS = %w[task_complete turn_started item_completed disconnected].freeze
 
+      # Server→client approval requests harnex auto-approves so dispatched
+      # codex workers can run autonomously. Codex sends these via JSON-RPC
+      # when its sandbox/approval policy needs a client decision; without
+      # a handler the client returns -32601 and codex blocks the operation.
+      # Permissions / user-input / dynamic-tool / auth-refresh requests
+      # have richer response shapes and are deliberately not auto-handled
+      # — they fall through to -32601 until a use case appears.
+      APPROVAL_RESPONSES = {
+        "applyPatchApproval"                    => { decision: "approved" },
+        "execCommandApproval"                   => { decision: "approved" },
+        "item/commandExecution/requestApproval" => { decision: "approved" },
+        "item/fileChange/requestApproval"       => { decision: "accept" }
+      }.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?
+        @initial_prompt = extract_initial_prompt(extra_args)
         @client = nil
         @thread_id = nil
         @current_turn_id = nil
@@ -57,8 +70,13 @@ module Harnex
         ["codex", "app-server"]
       end
 
+      # The harnex-context entry (set by `--context`) is delivered via
+      # JSON-RPC `turn/start`, not as a CLI argument — codex app-server
+      # rejects positional input and would exit immediately. Operator-
+      # supplied codex flags (passed via `harnex run codex -- ...`) are
+      # appended so e.g. `-c sandbox_mode=danger-full-access` works.
       def build_command
-        base_command
+        base_command + cli_extra_args
       end
 
       def describe
@@ -121,6 +139,7 @@ module Harnex
         end
 
         @client.on_notification { |msg| handle_notification(msg) }
+        @client.on_request { |method, params| handle_server_request(method, params) }
         @client.on_disconnect { |err| handle_disconnect(err) }
         @client.start
         perform_handshake
@@ -128,12 +147,19 @@ module Harnex
         self
       end
 
+      # Auto-approve known approval-style requests so dispatched workers
+      # can run without a human-in-the-loop. Returns the response body to
+      # serialize as JSON-RPC `result`, or `nil` to fall through to -32601.
+      def handle_server_request(method, _params)
+        APPROVAL_RESPONSES[method]
+      end
+
       def dispatch(prompt:, model: nil, effort: nil)
         ensure_open!
         ensure_thread!
         params = {
           threadId: @thread_id,
-          input: { content: [{ type: "text", text: prompt.to_s }] }
+          input: [{ type: "text", text: prompt.to_s }]
         }
         params[:model] = model if model
         params[:effort] = effort if effort
@@ -183,7 +209,28 @@ module Harnex
         return if @thread_id
 
         result = @client.request("thread/start", {})
-        @thread_id = result["threadId"] || result["thread_id"]
+        @thread_id = extract_thread_id(result)
+      end
+
+      def extract_thread_id(payload)
+        return nil unless payload.is_a?(Hash)
+
+        payload.dig("thread", "id") || payload["threadId"] || payload["thread_id"]
+      end
+
+      def extract_initial_prompt(extra_args)
+        return nil unless extra_args.is_a?(Array)
+
+        prefixed = extra_args.find { |a| a.is_a?(String) && a.start_with?("[harnex session id=") }
+        return prefixed if prefixed && !prefixed.empty?
+
+        nil
+      end
+
+      # Codex CLI flags only — strips the harnex-context entry that
+      # `--context` smuggles through @extra_args.
+      def cli_extra_args
+        @extra_args.reject { |a| a.is_a?(String) && a.start_with?("[harnex session id=") }
       end
 
       def perform_handshake
@@ -207,7 +254,7 @@ module Harnex
 
         case method
         when "thread/started"
-          @thread_id ||= params["threadId"] || params["thread_id"]
+          @thread_id ||= extract_thread_id(params)
         when "turn/started"
           @current_turn_id = params["turnId"] || params["turn_id"]
           @state = :busy
@@ -256,6 +303,7 @@ module Harnex
           @id_mutex = Mutex.new
           @write_mutex = Mutex.new
           @notification_handler = nil
+          @request_handler = nil
           @disconnect_handler = nil
           @disconnect_signaled = false
           @closed = false
@@ -266,6 +314,13 @@ module Harnex
           @notification_handler = block
         end
 
+        # Handler for server-initiated requests (id + method). The block
+        # receives (method, params) and returns the response body for the
+        # JSON-RPC `result` field, or nil to reject with -32601.
+        def on_request(&block)
+          @request_handler = block
+        end
+
         def on_disconnect(&block)
           @disconnect_handler = block
         end
@@ -367,11 +422,7 @@ module Harnex
 
         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']}" }
-            })
+            handle_server_request(message)
             return
           end
 
@@ -392,6 +443,29 @@ module Harnex
           @notification_handler&.call(message) if message["method"]
         end
 
+        def handle_server_request(message)
+          result =
+            begin
+              @request_handler&.call(message["method"], message["params"] || {})
+            rescue StandardError
+              nil
+            end
+
+          if result.nil?
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              error: { code: -32601, message: "Unsupported server request: #{message['method']}" }
+            })
+          else
+            write_line({
+              jsonrpc: "2.0",
+              id: message["id"],
+              result: result
+            })
+          end
+        end
+
         def signal_disconnect(error)
           return if @disconnect_signaled
 

data/lib/harnex/adapters.rb

@@ -18,7 +18,8 @@ module Harnex
 
     # 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.
+    # `harnex run codex --legacy-pty`); kept as a long-term supported
+    # fallback for interactive/TUI use cases.
     def codex_appserver_enabled?
       true
     end

data/lib/harnex/commands/run.rb

@@ -37,8 +37,9 @@ module Harnex
           --timeout SECS     Max seconds to wait for detached registration (default: #{DEFAULT_TIMEOUT})
           --inbox-ttl SECS   Expire queued inbox messages after SECS (default: #{Inbox::DEFAULT_TTL})
           --legacy-pty       (codex only) Use the legacy PTY adapter instead of
-                             the JSON-RPC `app-server` adapter. Deprecated; will
-                             be removed in 0.7.0.
+                             the JSON-RPC `app-server` adapter. Long-term
+                             supported fallback for interactive/TUI use; JSON-RPC
+                             remains the default for autonomous dispatches.
           -h, --help         Show this help
 
         Notes:

data/lib/harnex/runtime/session.rb

@@ -74,6 +74,7 @@ module Harnex
       @usage_summary = {}
       @ended_at = nil
       @exit_reason = nil
+      @turn_started_seen = false
       @last_completed_at = nil
       @writer = nil
       @pid = nil
@@ -377,6 +378,7 @@ module Harnex
       when "thread/started"
         @rpc_thread_id = params["threadId"] || params["thread_id"]
       when "turn/started"
+        @turn_started_seen = true
         @state_machine.force_busy!
         emit_event("turn_started", turnId: params["turnId"] || params["turn_id"])
       when "turn/completed"
@@ -707,12 +709,21 @@ module Harnex
 
     def classify_exit
       return "timeout" if @exit_code == 124
+      return "success" if @exit_code == 0 && session_summary_present?
+      return "boot_failure" if boot_failure_exit?
       return "failure" unless @exit_code == 0
-      return "success" if session_summary_present?
 
       "disconnected"
     end
 
+    def boot_failure_exit?
+      return false unless adapter.transport == :stdio_jsonrpc
+      return false if @turn_started_seen
+
+      lifetime = (@ended_at || Time.now) - @started_at
+      lifetime <= 5
+    end
+
     def session_summary_present?
       @usage_summary.values.any? { |value| !value.nil? }
     end
@@ -761,7 +772,9 @@ module Harnex
 
     def build_summary_actual
       counters = @event_counters.snapshot
-      counters[:disconnections] = [counters[:disconnections], 1].max if @exit_reason == "disconnected"
+      if %w[disconnected boot_failure].include?(@exit_reason)
+        counters[:disconnections] = [counters[:disconnections], 1].max
+      end
 
       {
         model: meta_hash["model"],

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.6.2"
+  VERSION = "0.6.4"
   RELEASE_DATE = "2026-05-06"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.4
 platform: ruby
 authors:
 - Jikku Jose