harnex 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d7c194ba2ba10ee075e6e53aa3eaf291cbfc08eca1d89cd291955834230c01
-  data.tar.gz: e3bafc087ae74a484be3ee121cce0d8f351c6b381ce244d5da032e48c85da4db
+  metadata.gz: 2b38fbca70a1ec608f414f362bb16bff85bdb5c279a5c562c4dc7048fa6acb41
+  data.tar.gz: 7a9048de3efb9461489ab0678683e0d245e60e2ac3a1dd7e617d868fce927a51
 SHA512:
-  metadata.gz: e3737c2aa49fb223c75cfc0d997a52bb72029b4c1a7a11affdd05a16c685e4edc42384ff0cfc03e63e4b4abcc9228c7f1d37c408c074538392c75d13be4e1e5e
-  data.tar.gz: 0b096fb9d95f22b812fc43fc69b4f8546e090d76c669383b8d71b34a048aa8eed46510f7ce9be27e0da3eab449a610c13fd6a338d8e1c202649d235df7052154
+  metadata.gz: a222bd5df7a1e02e7b6cebb2e0a63649b4433baef17be35a3dd03b4128e9b406af52ae71e9c063a6912dbb9af04b187072a693271fb72f24e4d61de462a7bf1c
+  data.tar.gz: eb2ca6564d079b0e162e72e9d07d01239ba2ce0c5b118fbd4360671d555c452571b2c64cb0f5a4be3c0b23c13e57b606d7ca98632d345f7570d5c69caacc9ad8

data/lib/harnex/adapters/base.rb

@@ -39,6 +39,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/commands/run.rb

@@ -7,11 +7,12 @@ module Harnex
     DEFAULT_TIMEOUT = 5.0
     KNOWN_FLAGS = %w[
       --id --description --detach --tmux --host --port --watch --watch-file
-      --stall-after --max-resumes --preset --context --timeout --inbox-ttl --help
+      --stall-after --max-resumes --preset --context --meta --summary-out
+      --timeout --inbox-ttl --help
     ].freeze
     VALUE_FLAGS = %w[
       --id --description --host --port --watch --watch-file --stall-after
-      --max-resumes --preset --context --timeout --inbox-ttl
+      --max-resumes --preset --context --meta --summary-out --timeout --inbox-ttl
     ].freeze
 
     def self.usage(program_name = "harnex run")
@@ -31,6 +32,8 @@ module Harnex
           --preset NAME      Watch preset: impl, plan, gate (requires --watch)
           --watch-file PATH  Auto-send a file-change hook on modification
           --context TEXT     Inject as the initial prompt (prepends session header)
+          --meta JSON        Attach parsed JSON metadata to the started event
+          --summary-out PATH Append dispatch telemetry summary JSONL to PATH
           --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})
           -h, --help         Show this help
@@ -60,6 +63,8 @@ module Harnex
         preset: nil,
         watch: nil,
         context: nil,
+        meta: nil,
+        summary_out: nil,
         detach: false,
         tmux: false,
         tmux_name: nil,
@@ -79,6 +84,7 @@ module Harnex
       raise OptionParser::MissingArgument, "cli" if cli_name.nil?
 
       repo_root = Harnex.resolve_repo_root(adapter_repo_path(cli_name, child_args))
+      @options[:summary_out] = resolve_summary_out(repo_root)
       @options[:id] ||= Harnex.generate_id(repo_root)
       validate_unique_id!(repo_root)
       effective_child_args = apply_context(child_args)
@@ -137,6 +143,8 @@ module Harnex
       tmux_cmd += ["--port", @options[:port].to_s] if @options[:port]
       tmux_cmd += ["--watch-file", @options[:watch]] if @options[:watch]
       tmux_cmd += ["--context", @options[:context]] if @options[:context]
+      tmux_cmd += ["--meta", JSON.generate(@options[:meta])] if @options[:meta]
+      tmux_cmd += ["--summary-out", @options[:summary_out]] if @options[:summary_out]
       tmux_cmd += ["--inbox-ttl", @options[:inbox_ttl].to_s]
       tmux_cmd += ["--"] + child_args unless child_args.empty?
 
@@ -239,6 +247,8 @@ module Harnex
         id: @options[:id],
         watch: watch,
         description: @options[:description],
+        meta: @options[:meta],
+        summary_out: @options[:summary_out],
         inbox_ttl: @options[:inbox_ttl]
       )
     end
@@ -385,6 +395,16 @@ module Harnex
           @options[:context] = required_option_value(arg, argv[index])
         when /\A--context=(.+)\z/
           @options[:context] = required_option_value("--context", Regexp.last_match(1))
+        when "--meta"
+          index += 1
+          @options[:meta] = parse_meta(required_option_value(arg, argv[index]))
+        when /\A--meta=(.+)\z/
+          @options[:meta] = parse_meta(required_option_value("--meta", Regexp.last_match(1)))
+        when "--summary-out"
+          index += 1
+          @options[:summary_out] = required_option_value(arg, argv[index])
+        when /\A--summary-out=(.+)\z/
+          @options[:summary_out] = required_option_value("--summary-out", Regexp.last_match(1))
         when "--timeout"
           index += 1
           @options[:timeout] = Float(required_option_value(arg, argv[index]))
@@ -440,7 +460,7 @@ module Harnex
           nil
         when *VALUE_FLAGS
           index += 1
-        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|timeout|inbox-ttl)=/
+        when /\A--(?:id|description|host|port|watch|watch-file|stall-after|max-resumes|context|meta|summary-out|timeout|inbox-ttl)=/
           nil
         when /\A--preset=/
           nil
@@ -458,7 +478,8 @@ module Harnex
         arg == "-h" ||
         arg.start_with?(
           "--id=", "--description=", "--tmux=", "--host=", "--port=", "--watch=", "--watch-file=",
-          "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--timeout=", "--inbox-ttl="
+          "--stall-after=", "--max-resumes=", "--preset=", "--context=", "--meta=", "--summary-out=",
+          "--timeout=", "--inbox-ttl="
         )
     end
 
@@ -489,6 +510,22 @@ module Harnex
       raise OptionParser::InvalidArgument, "#{option_name} must be an integer"
     end
 
+    def parse_meta(value)
+      parsed = JSON.parse(value)
+      return parsed if parsed.is_a?(Hash)
+
+      raise OptionParser::InvalidOption, "--meta must be a JSON object"
+    rescue JSON::ParserError => e
+      raise OptionParser::InvalidOption, "--meta must be valid JSON: #{e.message}"
+    end
+
+    def resolve_summary_out(repo_root)
+      configured = @options[:summary_out]
+      return Harnex.default_summary_out_path(repo_root) if configured.nil?
+
+      File.expand_path(configured, repo_root)
+    end
+
     def default_inbox_ttl
       value = ENV["HARNEX_INBOX_TTL"]
       return Inbox::DEFAULT_TTL.to_f if value.nil? || value.strip.empty?

data/lib/harnex/core.rb

@@ -64,6 +64,67 @@ module Harnex
     seconds
   end
 
+  def harness_version
+    VERSION
+  end
+
+  def host_info
+    {
+      host: Socket.gethostname,
+      platform: RUBY_PLATFORM
+    }
+  rescue StandardError
+    {
+      host: nil,
+      platform: RUBY_PLATFORM
+    }
+  end
+
+  def strip_ansi(text)
+    text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
+  end
+
+  def default_summary_out_path(repo_root)
+    koder_dir = File.join(repo_root.to_s, "koder")
+    return nil unless File.directory?(koder_dir)
+
+    File.join(koder_dir, "DISPATCH.jsonl")
+  end
+
+  def git_capture_start(repo_root)
+    sha = git_output(repo_root, "rev-parse", "HEAD")
+    branch = git_output(repo_root, "rev-parse", "--abbrev-ref", "HEAD")
+    return {} if sha.empty? || branch.empty?
+
+    {
+      sha: sha,
+      branch: branch
+    }
+  rescue StandardError
+    {}
+  end
+
+  def git_capture_end(repo_root, start_sha)
+    start_sha = start_sha.to_s.strip
+    return {} if start_sha.empty?
+
+    end_sha = git_output(repo_root, "rev-parse", "HEAD")
+    range = "#{start_sha}..#{end_sha}"
+    shortstat = git_output(repo_root, "diff", "--shortstat", range)
+    commits = Integer(git_output(repo_root, "rev-list", "--count", range))
+    stats = parse_git_shortstat(shortstat)
+
+    {
+      sha: end_sha,
+      loc_added: stats.fetch(:loc_added),
+      loc_removed: stats.fetch(:loc_removed),
+      files_changed: stats.fetch(:files_changed),
+      commits: commits
+    }
+  rescue StandardError
+    {}
+  end
+
   def repo_key(repo_root)
     Digest::SHA256.hexdigest(repo_root)[0, 16]
   end
@@ -316,4 +377,19 @@ module Harnex
       debounce_seconds: WATCH_DEBOUNCE_SECONDS
     )
   end
+
+  def git_output(repo_root, *args)
+    stdout, _stderr, status = Open3.capture3("git", "-C", repo_root.to_s, *args)
+    raise "git #{args.join(' ')} failed" unless status.success?
+
+    stdout.strip
+  end
+
+  def parse_git_shortstat(text)
+    {
+      files_changed: text.to_s[/(\d+)\s+files?\s+changed/, 1].to_i,
+      loc_added: text.to_s[/(\d+)\s+insertions?\(\+\)/, 1].to_i,
+      loc_removed: text.to_s[/(\d+)\s+deletions?\(-\)/, 1].to_i
+    }
+  end
 end

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
+
+      def record(type)
+        case type.to_s
+        when "log_idle"
+          @counts[:stalls] += 1
+        when "resume"
+          @counts[:force_resumes] += 1
+        when "disconnect", "disconnection"
+          @counts[:disconnections] += 1
+        when "compaction"
+          @counts[:compactions] += 1
+        end
+      end
 
-    attr_reader :repo_root, :host, :port, :session_id, :token, :command, :pid, :id, :adapter, :watch, :inbox, :description, :output_log_path, :events_log_path
+      def snapshot
+        @counts.dup
+      end
+    end
 
-    def initialize(adapter:, command:, repo_root:, host:, port: nil, id: DEFAULT_ID, watch: nil, description: nil, inbox_ttl: Inbox::DEFAULT_TTL)
+    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,12 @@ 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
       @writer = nil
       @pid = nil
       @term_signal = nil
@@ -67,7 +107,8 @@ module Harnex
       prepare_events_log
       @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 +125,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
@@ -390,13 +437,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.5.0"
+  RELEASE_DATE = "2026-05-01"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-05-01 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.