harnex 0.4.0 → 0.6.0

data/lib/harnex/runtime/session.rb

@@ -5,10 +5,41 @@ require "pty"
 module Harnex
   class Session
     OUTPUT_BUFFER_LIMIT = 64 * 1024
+    TRANSCRIPT_TAIL_BYTES = 16 * 1024
+    USAGE_FIELDS = %i[
+      input_tokens output_tokens reasoning_tokens cached_tokens total_tokens agent_session_id
+    ].freeze
+    class EventCounters
+      def initialize
+        @counts = {
+          stalls: 0,
+          force_resumes: 0,
+          disconnections: 0,
+          compactions: 0
+        }
+      end
 
-    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :output_log_path, :events_log_path
+      def record(type)
+        case type.to_s
+        when "log_idle"
+          @counts[:stalls] += 1
+        when "resume"
+          @counts[:force_resumes] += 1
+        when "disconnect", "disconnection", "disconnected"
+          @counts[:disconnections] += 1
+        when "compaction"
+          @counts[:compactions] += 1
+        end
+      end
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, inbox_ttl: Inbox::DEFAULT_TTL)
+      def snapshot
+        @counts.dup
+      end
+    end
+
+    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :meta, :summary_out, :output_log_path, :events_log_path
+
+    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, meta: nil, summary_out: nil, inbox_ttl: Inbox::DEFAULT_TTL)
       @adapter = adapter
       @command = command
       @repo_root = repo_root
@@ -17,6 +48,9 @@ module Harnex
       @watch = watch
       @description = description.to_s.strip
       @description = nil if @description.empty?
+      @meta = meta
+      @summary_out = summary_out.to_s.strip
+      @summary_out = nil if @summary_out.empty?
       @registry_path = Harnex.registry_path(repo_root, @id)
       @output_log_path = Harnex.output_log_path(repo_root, @id)
       @events_log_path = Harnex.events_log_path(repo_root, @id)
@@ -34,6 +68,13 @@ module Harnex
       @output_log = nil
       @events_log = nil
       @events_log_seq = 0
+      @event_counters = EventCounters.new
+      @git_start = {}
+      @git_end = {}
+      @usage_summary = {}
+      @ended_at = nil
+      @exit_reason = nil
+      @last_completed_at = nil
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -65,9 +106,17 @@ module Harnex
       validate_binary! if validate_binary
       prepare_output_log
       prepare_events_log
+
+      return run_jsonrpc if adapter.transport == :stdio_jsonrpc
+
+      run_pty
+    end
+
+    def run_pty
       @reader, @writer, @pid = PTY.spawn(child_env, *command)
       @writer.sync = true
-      emit_event("started", pid: @pid)
+      emit_started_event
+      emit_git_start_event
 
       install_signal_handlers
       sync_window_size
@@ -84,9 +133,15 @@ module Harnex
       _, status = Process.wait2(pid)
       @term_signal = status.signaled? ? status.termsig : nil
       @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
-      emit_exit_event
+      @ended_at = Time.now
 
       output_thread.join(1)
+      emit_session_end_telemetry
+      @exit_reason = classify_exit
+      summary_record = build_summary_record
+      append_summary_record(summary_record)
+      emit_summary_event
+      emit_exit_event
       input_thread&.kill
       watch_thread&.kill
       @exit_code
@@ -132,6 +187,10 @@ module Harnex
       payload[:input_state] = adapter.input_state(screen_snapshot) if include_input_state
       payload[:agent_state] = @state_machine.to_s
       payload[:inbox] = @inbox.stats
+      payload[:last_completed_at] = @last_completed_at&.iso8601
+      payload[:model] = meta_hash["model"]
+      payload[:effort] = meta_hash["effort"]
+      payload[:auto_disconnects] = @event_counters.snapshot[:disconnections]
       payload
     end
 
@@ -146,6 +205,18 @@ module Harnex
     end
 
     def inject_stop
+      if adapter.transport == :stdio_jsonrpc
+        @inject_mutex.synchronize do
+          begin
+            adapter.interrupt
+          rescue StandardError
+            nil
+          end
+          @state_machine.force_busy!
+        end
+        return { ok: true, signal: "interrupt_sent" }
+      end
+
       raise "session is not running" unless pid && Harnex.alive_pid?(pid)
 
       @inject_mutex.synchronize do
@@ -157,6 +228,10 @@ module Harnex
     end
 
     def inject_via_adapter(text:, submit:, enter_only:, force: false)
+      if adapter.transport == :stdio_jsonrpc
+        return inject_via_jsonrpc(text: text, force: force)
+      end
+
       snapshot = adapter.wait_for_sendable(method(:screen_snapshot), submit: submit, enter_only: enter_only, force: force)
       payload = adapter.build_send_payload(
         text: text,
@@ -181,8 +256,32 @@ module Harnex
         .tap { emit_send_event(text, force: payload[:force]) }
     end
 
+    def inject_via_jsonrpc(text:, force: false)
+      turn_id = nil
+      @inject_mutex.synchronize do
+        turn_id = adapter.dispatch(prompt: text)
+        @state_machine.force_busy!
+        @injected_count += 1
+        @last_injected_at = Time.now
+        persist_registry
+      end
+
+      emit_send_event(text, force: force)
+      {
+        ok: true,
+        cli: adapter.key,
+        bytes_written: text.to_s.bytesize,
+        injected_count: @injected_count,
+        newline: false,
+        input_state: adapter.input_state(nil),
+        force: force,
+        turn_id: turn_id
+      }
+    end
+
     def sync_window_size
       return unless STDIN.tty?
+      return unless @writer
 
       @writer.winsize = STDIN.winsize
     rescue StandardError
@@ -195,6 +294,154 @@ module Harnex
 
     private
 
+    def run_jsonrpc
+      adapter.on_notification { |msg| handle_rpc_notification(msg) }
+      adapter.on_disconnect { |err| handle_rpc_disconnect(err) }
+
+      adapter.start_rpc(env: child_env, cwd: repo_root)
+      @pid = adapter.pid
+      emit_started_event
+      emit_git_start_event
+
+      install_signal_handlers
+      @server = ApiServer.new(self)
+      @server.start
+      persist_registry
+
+      watch_thread = start_watch_thread
+      @inbox.start
+
+      if @pid
+        begin
+          _, status = Process.wait2(@pid)
+          @term_signal = status.signaled? ? status.termsig : nil
+          @exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+        rescue Errno::ECHILD
+          @exit_code = 0
+        end
+      else
+        @rpc_done_lock = Mutex.new
+        @rpc_done_cond = ConditionVariable.new
+        @rpc_done_lock.synchronize { @rpc_done_cond.wait(@rpc_done_lock) until @rpc_done }
+        @exit_code = 0
+      end
+      @ended_at = Time.now
+
+      emit_session_end_telemetry
+      @exit_reason = classify_exit
+      summary_record = build_summary_record
+      append_summary_record(summary_record)
+      emit_summary_event
+      emit_exit_event
+      watch_thread&.kill
+      @exit_code
+    ensure
+      @inbox.stop
+      @server&.stop
+      begin
+        adapter.close
+      rescue StandardError
+        nil
+      end
+      persist_exit_status
+      cleanup_registry
+      @output_log&.close unless @output_log&.closed?
+      @events_log&.close unless @events_log&.closed?
+    end
+
+    def signal_rpc_done!
+      @rpc_done = true
+      if defined?(@rpc_done_lock) && @rpc_done_lock
+        @rpc_done_lock.synchronize { @rpc_done_cond&.signal }
+      end
+    end
+
+    def handle_rpc_notification(message)
+      method = message["method"]
+      params = message["params"] || {}
+
+      case method
+      when "thread/started"
+        @rpc_thread_id = params["threadId"] || params["thread_id"]
+      when "turn/started"
+        emit_event("turn_started", turnId: params["turnId"] || params["turn_id"])
+      when "turn/completed"
+        @last_completed_at = Time.now
+        payload = { turnId: params["turnId"] || params["turn_id"] }
+        payload[:status] = params["status"] if params["status"]
+        payload[:tokenUsage] = params["tokenUsage"] if params["tokenUsage"]
+        emit_event("task_complete", **payload)
+      when "item/completed"
+        emit_event("item_completed", item: params["item"])
+        text = render_item_text(params["item"])
+        record_synthesized(text) if text
+      when "thread/compacted"
+        emit_event("compaction", **params)
+      when "thread/tokenUsage/updated"
+        # Surfaced via status fields in Phase 4; no event spam.
+        @token_usage = params["usage"] || params
+      when "thread/status/changed"
+        # State machine reflects RPC state; no event needed.
+        nil
+      when "account/rateLimits/updated"
+        @rate_limits = params
+      when "error"
+        emit_event("disconnected", source: "error_notification", message: params["message"])
+        signal_rpc_done!
+      end
+    rescue StandardError => e
+      warn("harnex: rpc notification handler error: #{e.message}")
+    end
+
+    def handle_rpc_disconnect(error)
+      msg = error.is_a?(Hash) ? error["message"] : error&.message
+      emit_event("disconnected", source: "transport", message: msg) rescue nil
+      signal_rpc_done!
+    end
+
+    def render_item_text(item)
+      return nil unless item.is_a?(Hash)
+
+      type = item["type"] || item["kind"]
+      case type
+      when "agent_message", "assistant_message"
+        item["text"] || item.dig("message", "text")
+      when "tool_call"
+        name = item["name"] || item.dig("tool", "name") || "tool"
+        params = item["params"] || item["arguments"]
+        "tool: #{name}#{params ? " #{summarize(params)}" : ""}"
+      else
+        item["text"]
+      end
+    end
+
+    def summarize(value)
+      str = value.is_a?(String) ? value : JSON.generate(value)
+      str.length > 120 ? "#{str[0, 117]}..." : str
+    rescue StandardError
+      ""
+    end
+
+    def record_synthesized(text)
+      return if text.nil? || text.to_s.empty?
+
+      payload = text.to_s.dup
+      payload << "\n" unless payload.end_with?("\n")
+      bytes = payload.b
+      @mutex.synchronize do
+        append_output_log(bytes)
+        @output_buffer << bytes
+        overflow = @output_buffer.bytesize - OUTPUT_BUFFER_LIMIT
+        @output_buffer = @output_buffer.byteslice(overflow, OUTPUT_BUFFER_LIMIT) if overflow.positive?
+      end
+      begin
+        STDOUT.write(payload)
+        STDOUT.flush
+      rescue StandardError
+        nil
+      end
+    end
+
     def child_env
       env = {
         "HARNEX_SESSION_ID" => session_id,
@@ -390,13 +637,170 @@ module Harnex
       emit_event("send", msg: preview, msg_truncated: truncated, forced: !!force)
     end
 
+    def emit_started_event
+      payload = { pid: @pid }
+      payload[:meta] = meta if meta
+      emit_event("started", **payload)
+    end
+
+    def emit_git_start_event
+      @git_start = Harnex.git_capture_start(repo_root)
+      return if @git_start.empty?
+
+      emit_event("git", phase: "start", sha: @git_start[:sha], branch: @git_start[:branch])
+    end
+
+    def emit_session_end_telemetry
+      @usage_summary = normalized_usage_summary(adapter.parse_session_summary(transcript_tail))
+      emit_event("usage", **@usage_summary)
+
+      @git_end = Harnex.git_capture_end(repo_root, @git_start[:sha])
+      return if @git_end.empty?
+
+      emit_event(
+        "git",
+        phase: "end",
+        sha: @git_end[:sha],
+        loc_added: @git_end[:loc_added],
+        loc_removed: @git_end[:loc_removed],
+        files_changed: @git_end[:files_changed],
+        commits: @git_end[:commits]
+      )
+    end
+
+    def emit_summary_event
+      emit_event("summary", path: summary_out, exit: @exit_reason)
+    end
+
     def emit_exit_event
       payload = { code: @exit_code }
       payload[:signal] = @term_signal if @term_signal
+      payload[:reason] = @exit_reason if @exit_reason
       emit_event("exited", **payload)
     end
 
+    def classify_exit
+      return "timeout" if @exit_code == 124
+      return "failure" unless @exit_code == 0
+      return "success" if session_summary_present?
+
+      "disconnected"
+    end
+
+    def session_summary_present?
+      @usage_summary.values.any? { |value| !value.nil? }
+    end
+
+    def build_summary_record
+      {
+        meta: build_summary_meta,
+        predicted: summary_predicted_payload,
+        actual: build_summary_actual
+      }
+    end
+
+    def build_summary_meta
+      info = Harnex.host_info
+      passthrough = meta_hash
+
+      {
+        id: id,
+        tmux_session: id,
+        description: description,
+        started_at: @started_at.iso8601,
+        ended_at: @ended_at&.iso8601,
+        harness: "harnex",
+        harness_version: Harnex.harness_version,
+        agent: adapter.key,
+        agent_version: nil,
+        agent_provider: nil,
+        agent_deployment: nil,
+        host: info[:host],
+        platform: info[:platform],
+        orchestrator: passthrough["orchestrator"],
+        orchestrator_session: passthrough["orchestrator_session"],
+        chain_id: passthrough["chain_id"],
+        parent_dispatch_id: passthrough["parent_dispatch_id"],
+        tier: passthrough["tier"],
+        phase: passthrough["phase"],
+        issue: passthrough["issue"],
+        plan: passthrough["plan"],
+        task_brief: passthrough["task_brief"],
+        repo: repo_root,
+        branch: @git_start[:branch],
+        start_sha: @git_start[:sha],
+        end_sha: @git_end[:sha]
+      }
+    end
+
+    def build_summary_actual
+      counters = @event_counters.snapshot
+      counters[:disconnections] = [counters[:disconnections], 1].max if @exit_reason == "disconnected"
+
+      {
+        model: meta_hash["model"],
+        effort: meta_hash["effort"],
+        duration_s: @ended_at ? (@ended_at - @started_at).to_i : nil,
+        input_tokens: @usage_summary[:input_tokens],
+        output_tokens: @usage_summary[:output_tokens],
+        reasoning_tokens: @usage_summary[:reasoning_tokens],
+        cached_tokens: @usage_summary[:cached_tokens],
+        cost_usd: nil,
+        loc_added: @git_end[:loc_added],
+        loc_removed: @git_end[:loc_removed],
+        files_changed: @git_end[:files_changed],
+        commits: @git_end[:commits],
+        exit: @exit_reason,
+        stalls: counters[:stalls],
+        force_resumes: counters[:force_resumes],
+        disconnections: counters[:disconnections],
+        compactions: counters[:compactions],
+        tests_run: nil,
+        tests_passed: nil,
+        tests_failed: nil
+      }
+    end
+
+    def summary_predicted_payload
+      predicted = meta_hash["predicted"]
+      predicted.is_a?(Hash) ? predicted : {}
+    end
+
+    def meta_hash
+      meta.is_a?(Hash) ? meta : {}
+    end
+
+    def append_summary_record(record)
+      return unless summary_out
+
+      FileUtils.mkdir_p(File.dirname(summary_out))
+      File.open(summary_out, "ab") do |file|
+        file.write(JSON.generate(record))
+        file.write("\n")
+      end
+    rescue StandardError => e
+      warn("harnex: failed to write dispatch summary #{summary_out}: #{e.message}")
+    end
+
+    def normalized_usage_summary(summary)
+      summary ||= {}
+      USAGE_FIELDS.to_h { |field| [field, summary[field] || summary[field.to_s]] }
+    end
+
+    def transcript_tail
+      return "" unless File.file?(output_log_path)
+
+      File.open(output_log_path, "rb") do |file|
+        size = file.size
+        file.seek([size - TRANSCRIPT_TAIL_BYTES, 0].max)
+        Harnex.strip_ansi(file.read.to_s)
+      end
+    rescue StandardError
+      ""
+    end
+
     def emit_event(type, **payload)
+      @event_counters.record(type)
       @events_mutex.synchronize do
         return unless @events_log
 

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.4.0"
-  RELEASE_DATE = "2026-04-30"
+  VERSION = "0.6.0"
+  RELEASE_DATE = "2026-05-06"
 end

data/lib/harnex.rb

@@ -25,4 +25,5 @@ require_relative "harnex/commands/pane"
 require_relative "harnex/commands/recipes"
 require_relative "harnex/commands/guide"
 require_relative "harnex/commands/skills"
+require_relative "harnex/commands/doctor"
 require_relative "harnex/cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex) and
   adds a control plane for discovery, messaging, and coordination.
@@ -19,6 +19,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - GUIDE.md
 - LICENSE
 - README.md
@@ -30,8 +31,10 @@ files:
 - lib/harnex/adapters/base.rb
 - lib/harnex/adapters/claude.rb
 - lib/harnex/adapters/codex.rb
+- lib/harnex/adapters/codex_appserver.rb
 - lib/harnex/adapters/generic.rb
 - lib/harnex/cli.rb
+- lib/harnex/commands/doctor.rb
 - lib/harnex/commands/events.rb
 - lib/harnex/commands/guide.rb
 - lib/harnex/commands/logs.rb