codex-ruby 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03d9e3beac47546980e8b63c3051c2d5100a3f1db197cf85a43c8d7b9eaf8f56
-  data.tar.gz: 879f569d1dfadc2451c7bf2ccb6a6cc36e897d3c1644e327bc8bb3d477014e72
+  metadata.gz: db45d058e2d271fe579ab9e4a614b571e194496c70d60b36470ad5fb5a7ebcbc
+  data.tar.gz: e243fc97acdb98e1ee2aaf2554b5f13c51a98e41df256fcb9f476ce61f8bf7e3
 SHA512:
-  metadata.gz: c353524c5d986caea98150081c3efacaff18a918a643e2bf75af34f06e1b7d2c91627b433dc463d90c6f406cc20c68e8603430f2063ed6a1299ec881e19528bd
-  data.tar.gz: ad57c8fd2dd7de943f0b541930125219342fffab87ce42890e643d6590abc09deb4d03ed7876f29802d05cb73bb66fc91f0a692ec2cf902a9a1bd29264d2c36b
+  metadata.gz: 00453f4fa7796cd76712465d9830264b57b79fc8a0261ad4092889ca3387a2db5bee8ffd23ba06349930666458789eff4d95c19761de97c1460ff11c5a046a3e
+  data.tar.gz: f28130158754e20ed7bb5452e14f43f453b436184fbe25ab804cfb8f02236edca1b1968b335f512dd329715e153fc7692f18e6b00953be2c00f425e6af0e3bd2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.2 (2026-04-19)
+
+- Expose rollout-derived `context_snapshot` data on `Exec`, `AgentThread`, and blocking `Turn` results
+- Add `TokenUsage` and `ContextSnapshot` types plus rollout log parsing for Codex `token_count` events
+- Add RuboCop to the repository with a dedicated CI lint job and baseline configuration
+
+## 0.1.1 (2026-04-11)
+
+- Patch release
+
 ## 0.1.0 (2026-04-10)
 
 - Initial release

data/README.md

@@ -43,6 +43,7 @@ thread = client.start_thread(
 turn = thread.run("Explain this codebase")
 puts turn.final_response
 puts "Tokens used: #{turn.usage.input_tokens} in, #{turn.usage.output_tokens} out"
+puts "Final context: #{turn.context_snapshot.context_tokens} / #{turn.context_snapshot.model_context_window}"
 
 # Streaming run - yields events as they arrive
 thread.run_streamed("Fix the failing tests") do |event|
@@ -62,6 +63,8 @@ thread.run_streamed("Fix the failing tests") do |event|
     puts "Error: #{event.error_message}"
   end
 end
+
+puts "Final context: #{thread.context_snapshot.context_tokens} / #{thread.context_snapshot.model_context_window}"
 ```
 
 ### Resume a thread
@@ -120,6 +123,20 @@ client = CodexSDK::Client.new(
 | `Events::ItemCompleted` | Item finished, provides typed `item` |
 | `Events::Error` | Stream-level error, provides `message` |
 
+## Context snapshots
+
+Codex CLI writes richer rollout logs under `~/.codex/sessions` (or `CODEX_HOME/sessions`). After a run completes, `Thread#run` and `Thread#run_streamed` expose a final `context_snapshot` derived from the latest `token_count` entry in those rollout files.
+
+```ruby
+snapshot = thread.context_snapshot
+snapshot.context_tokens          # => current prompt/context footprint
+snapshot.model_context_window    # => model max context window
+snapshot.last_token_usage.total_tokens
+snapshot.total_token_usage.total_tokens
+```
+
+This is separate from `turn.completed.usage`, which is still the per-turn API usage reported by the JSON event stream.
+
 ## Item types
 
 | Item | Fields |

data/lib/codex_sdk/agent_thread.rb

@@ -4,7 +4,7 @@ require "fileutils"
 
 module CodexSDK
   class AgentThread
-    attr_reader :id
+    attr_reader :id, :context_snapshot
 
     def initialize(options, thread_options:, resume_id: nil)
       @options = options
@@ -33,7 +33,7 @@ module CodexSDK
         end
       end
 
-      Turn.new(items: items, final_response: final_response, usage: usage)
+      Turn.new(items: items, final_response: final_response, usage: usage, context_snapshot: @context_snapshot)
     end
 
     # Streaming run: yields each event to the block as it arrives.
@@ -41,9 +41,7 @@ module CodexSDK
       prompt = normalize_input(input)
 
       output_schema_path = nil
-      if turn_options.output_schema
-        output_schema_path = write_output_schema(turn_options.output_schema)
-      end
+      output_schema_path = write_output_schema(turn_options.output_schema) if turn_options.output_schema
 
       @exec = Exec.new(
         @options,
@@ -61,6 +59,7 @@ module CodexSDK
         block.call(event)
       end
     ensure
+      @context_snapshot = @exec&.context_snapshot
       cleanup_output_schema(output_schema_path)
     end
 
@@ -76,9 +75,9 @@ module CodexSDK
       when String
         input
       when Array
-        input.filter_map { |entry|
+        input.filter_map do |entry|
           entry[:text] if entry[:type] == "text"
-        }.join("\n\n")
+        end.join("\n\n")
       else
         input.to_s
       end
@@ -93,6 +92,7 @@ module CodexSDK
 
     def cleanup_output_schema(path)
       return unless path
+
       dir = File.dirname(path)
       FileUtils.rm_rf(dir)
     rescue StandardError

data/lib/codex_sdk/config_serializer.rb

@@ -38,6 +38,7 @@ module CodexSDK
         value.to_json
       when Integer, Float
         raise ArgumentError, "cannot serialize non-finite number" unless value.to_f.finite?
+
         value.to_s
       when true, false
         value.to_s

data/lib/codex_sdk/events.rb

@@ -19,9 +19,7 @@ module CodexSDK
 
     ThreadStarted = Data.define(:thread_id)
 
-    TurnStarted = Data.define do
-      def initialize; super(); end
-    end
+    TurnStarted = Data.define
 
     TurnCompleted = Data.define(:usage) do
       def self.from_json(data)

data/lib/codex_sdk/exec.rb

@@ -10,7 +10,7 @@ module CodexSDK
   class Exec
     SHUTDOWN_TIMEOUT = 10 # seconds to wait after SIGTERM before SIGKILL
 
-    attr_reader :pid
+    attr_reader :pid, :context_snapshot
 
     def initialize(options, thread_options: ThreadOptions.new)
       @options = options
@@ -27,6 +27,9 @@ module CodexSDK
     def run(prompt, resume_thread_id: nil, images: [], output_schema_path: nil, &block)
       args = build_args(resume_thread_id: resume_thread_id, images: images, output_schema_path: output_schema_path)
       env = build_env
+      sessions_root = codex_sessions_root(env)
+      started_at = Time.now
+      @context_snapshot = nil
 
       @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(env, *args)
 
@@ -35,7 +38,11 @@ module CodexSDK
       @stdin.close
 
       # Read stderr in background thread
-      stderr_reader = ::Thread.new { @stderr.read rescue "" }
+      stderr_reader = ::Thread.new do
+        @stderr.read
+      rescue StandardError
+        ""
+      end
 
       # Read JSONL from stdout line by line
       @stdout.each_line do |line|
@@ -64,6 +71,11 @@ module CodexSDK
           stderr: stderr_buf
         )
       end
+
+      @context_snapshot = read_context_snapshot(
+        sessions_root: sessions_root,
+        started_at: started_at
+      )
     ensure
       cleanup
     end
@@ -122,9 +134,7 @@ module CodexSDK
         args.concat(["--config", "sandbox_workspace_write.network_access=#{to.network_access}"])
       end
 
-      if to.web_search
-        args.concat(["--config", "web_search=#{ConfigSerializer.to_toml_value(to.web_search)}"])
-      end
+      args.concat(["--config", "web_search=#{ConfigSerializer.to_toml_value(to.web_search)}"]) if to.web_search
 
       if to.approval_policy
         args.concat(["--config", "approval_policy=#{ConfigSerializer.to_toml_value(to.approval_policy)}"])
@@ -153,15 +163,37 @@ module CodexSDK
     def find_codex_path
       path = `which codex 2>/dev/null`.strip
       raise Error, "codex binary not found in PATH" if path.empty?
+
       path
     end
 
+    def codex_sessions_root(env)
+      return File.join(env["CODEX_HOME"], "sessions") if env["CODEX_HOME"] && !env["CODEX_HOME"].empty?
+
+      return unless env["HOME"] && !env["HOME"].empty?
+
+      File.join(env["HOME"], ".codex", "sessions")
+    end
+
+    def read_context_snapshot(sessions_root:, started_at:)
+      return unless sessions_root
+
+      RolloutContextSnapshotReader.new(
+        sessions_root: sessions_root,
+        started_at: started_at
+      ).read
+    rescue StandardError
+      nil
+    end
+
     def wait_for_exit(timeout)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       loop do
         return true unless @wait_thread&.alive?
+
         remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         return false if remaining <= 0
+
         sleep([0.1, remaining].min)
       end
     end

data/lib/codex_sdk/options.rb

@@ -63,9 +63,43 @@ module CodexSDK
     end
   end
 
+  # Detailed token usage from rollout token_count snapshots.
+  TokenUsage = Data.define(
+    :input_tokens,
+    :cached_input_tokens,
+    :output_tokens,
+    :reasoning_output_tokens,
+    :total_tokens
+  ) do
+    def initialize(
+      input_tokens: 0,
+      cached_input_tokens: 0,
+      output_tokens: 0,
+      reasoning_output_tokens: 0,
+      total_tokens: 0
+    )
+      super
+    end
+  end
+
+  # Final context snapshot derived from Codex rollout logs.
+  ContextSnapshot = Data.define(:model_context_window, :last_token_usage, :total_token_usage) do
+    def initialize(
+      model_context_window: 0,
+      last_token_usage: TokenUsage.new,
+      total_token_usage: TokenUsage.new
+    )
+      super
+    end
+
+    def context_tokens
+      last_token_usage.total_tokens
+    end
+  end
+
   # Result of a blocking Thread#run call.
-  Turn = Data.define(:items, :final_response, :usage) do
-    def initialize(items: [], final_response: "", usage: nil)
+  Turn = Data.define(:items, :final_response, :usage, :context_snapshot) do
+    def initialize(items: [], final_response: "", usage: nil, context_snapshot: nil)
       super
     end
   end

data/lib/codex_sdk/rollout_context_snapshot_reader.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CodexSDK
+  class RolloutContextSnapshotReader
+    def initialize(sessions_root:, started_at:)
+      @sessions_root = sessions_root
+      @started_at = started_at
+    end
+
+    def read
+      candidate_rollouts.reverse_each do |path|
+        snapshot = read_rollout(path)
+        return snapshot if snapshot
+      end
+
+      nil
+    end
+
+    private
+
+    def candidate_rollouts
+      return [] unless Dir.exist?(@sessions_root)
+
+      Dir.glob(File.join(@sessions_root, "**", "rollout-*.jsonl"))
+         .select { |path| candidate_rollout?(path) }
+         .sort_by { |path| File.mtime(path) }
+    end
+
+    def candidate_rollout?(path)
+      return true unless @started_at
+
+      File.mtime(path) >= (@started_at - 1)
+    end
+
+    def read_rollout(path)
+      snapshot = nil
+
+      File.foreach(path) do |line|
+        event = JSON.parse(line)
+        next unless event["type"] == "event_msg"
+
+        payload = event["payload"]
+        next unless payload.is_a?(Hash) && payload["type"] == "token_count"
+
+        info = payload["info"]
+        next unless info.is_a?(Hash)
+
+        snapshot = ContextSnapshot.new(
+          model_context_window: info["model_context_window"].to_i,
+          last_token_usage: parse_usage(info["last_token_usage"]),
+          total_token_usage: parse_usage(info["total_token_usage"])
+        )
+      end
+
+      snapshot
+    rescue Errno::ENOENT, JSON::ParserError
+      nil
+    end
+
+    def parse_usage(data)
+      return TokenUsage.new unless data.is_a?(Hash)
+
+      TokenUsage.new(
+        input_tokens: data["input_tokens"].to_i,
+        cached_input_tokens: data["cached_input_tokens"].to_i,
+        output_tokens: data["output_tokens"].to_i,
+        reasoning_output_tokens: data["reasoning_output_tokens"].to_i,
+        total_tokens: data["total_tokens"].to_i
+      )
+    end
+  end
+end

data/lib/codex_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CodexSDK
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/codex_sdk.rb

@@ -29,6 +29,7 @@ require_relative "codex_sdk/options"
 require_relative "codex_sdk/config_serializer"
 require_relative "codex_sdk/items"
 require_relative "codex_sdk/events"
+require_relative "codex_sdk/rollout_context_snapshot_reader"
 require_relative "codex_sdk/exec"
 require_relative "codex_sdk/agent_thread"
 require_relative "codex_sdk/client"

metadata

@@ -1,42 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: codex-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Anton Kopylov
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
+dependencies: []
 description: A Ruby client for the Codex CLI, providing subprocess management, JSONL
   event parsing, and a clean API for building AI-powered applications.
 email:
@@ -56,6 +28,7 @@ files:
 - lib/codex_sdk/exec.rb
 - lib/codex_sdk/items.rb
 - lib/codex_sdk/options.rb
+- lib/codex_sdk/rollout_context_snapshot_reader.rb
 - lib/codex_sdk/version.rb
 homepage: https://github.com/tonic20/codex-ruby
 licenses:
@@ -64,6 +37,7 @@ metadata:
   homepage_uri: https://github.com/tonic20/codex-ruby
   source_code_uri: https://github.com/tonic20/codex-ruby
   changelog_uri: https://github.com/tonic20/codex-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib