ruby_llm-codex 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60eb34388c3f961cfbfa0604dfc757b407b781108bf9b33c1280bbb07c4a76e4
-  data.tar.gz: 5c4c9e0a38ced5c2bfd8d67cad4d135100bc55f4107479fcea3bb3e0cca37bfc
+  metadata.gz: b423cd9ecec786bde4858cfd86a5f2d010853925f341668a9a27ee46ce1e13c6
+  data.tar.gz: 1e9b7ee463ee62cd2a916979e36df16d3cd2270ea26d521b6f5bc8c16a85a11d
 SHA512:
-  metadata.gz: b22b44093a68b3c5d9c9c73fe533ef304d1aa7aa2408ede897940b78fc2cf2e23953237de4107b3a95f56a3b25cc72a06b9a2d67d554e7c81a968b5854d3122a
-  data.tar.gz: f6db93982d737c0769485f00c15c05ce48f182b394b594ea87bf2426add6e0f25eacca7e876ada5abdd8020a809ffe029193ee018bdc360929f7f2d6f310a173
+  metadata.gz: 5802a69971bc7798b5abe3317cc125db21f2bd7db1be86bf27cb4afaec3c4d57408d948d486268552a24d1726b3bddfc5f6b13ec24172d376b364d38e8b8883e
+  data.tar.gz: 877c1bb90fcf5e7c6a1f522a6adc163fcc6be5268e1baed14169dc40e0cd640f469a698a451b6e3e527198ef6cc098a1e0151ea86c9dacd4e4328bfe115932a6

data/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-10-12
+
+
+### feat
+
+- migrate Codex provider to RubyLLM 2.1
+
+
+
 ## [0.2.1] - 2026-07-17
 
 

data/README.md

@@ -19,8 +19,8 @@ supported mapping but not an identical wire-level request.
 ## Requirements
 
 - Ruby 3.3 or newer
-- RubyLLM 1.16.0 or newer, below 2.0
-- Codex CLI 0.144.5 or newer, available as `codex`
+- RubyLLM 2.1.1 or newer, below 2.2
+- Codex CLI 0.162.1 or newer, available as `codex`
 - Linux or macOS (timeout cleanup relies on POSIX process groups)
 - A completed ChatGPT login: `codex login`
 
@@ -34,6 +34,8 @@ codex login
 Check the model list in your installed Codex version before a large run. Model
 availability depends on the account and currently installed CLI.
 
+For migration steps from RubyLLM 1.x, see [UPGRADE.md](UPGRADE.md).
+
 ## Installation
 
 Add the gem to your application's `Gemfile`:
@@ -55,7 +57,7 @@ Require the gem and use Codex as an explicit RubyLLM provider:
 ```ruby
 require "ruby_llm-codex"
 
-class SummarySchema < RubyLLM::Schema
+class SummarySchema < Schematist::Schema
   string :summary
 end
 
@@ -65,11 +67,11 @@ response = RubyLLM.chat(model: ENV.fetch("CODEX_MODEL"), provider: :codex)
   .with_thinking(effort: :medium)
   .ask("The text to summarize")
 
-pp response.content
+pp response.parsed
 ```
 
-`response.content` is normalized by RubyLLM into the same Hash shape returned
-for structured outputs from its other providers.
+`response.content` contains the JSON string. Read `response.parsed` for the
+structured Hash, and `response.tokens` for token counts.
 
 ## Isolation and reproducibility
 
@@ -97,7 +99,7 @@ saved session history from quietly affecting a request.
 To deliberately let Codex inspect a repository or use selected configuration:
 
 ```ruby
-chat.with_params(
+chat.with_provider_options(
   codex: {
     working_directory: "/path/to/project",
     sandbox: "read-only",
@@ -126,8 +128,8 @@ RubyLLM.configure do |config|
 end
 ```
 
-Only the nested `codex` namespace is accepted by `with_params`; unsupported
-generic params raise an error instead of being silently ignored. Use
+Only the nested `codex` namespace is accepted by `with_provider_options`; unsupported
+generic provider options raise an error instead of being silently ignored. Use
 `with_thinking` for reasoning effort and `with_instructions` for developer
 instructions. Those settings, plus `features.shell_snapshot` and
 `shell_environment_policy.inherit`, are reserved from the arbitrary

data/UPGRADE.md

@@ -0,0 +1,28 @@
+# Upgrade Guide
+
+## RubyLLM 2.1
+
+This provider now requires RubyLLM `~> 2.1.1` and Codex CLI 0.162.1 or newer.
+RubyLLM 1.x and 2.0 are no longer supported. Upgrade the CLI with
+`npm install -g @openai/codex` and check `codex --version`.
+
+Host applications must:
+
+- Replace `with_params(codex: ...)` with `with_provider_options(codex: ...)`.
+- Replace `RubyLLM::Schema` with `Schematist::Schema`.
+- Read structured results through `response.parsed`; `response.content` is
+  now a JSON string.
+- Read the model ID from `response.model` and usage from `response.tokens`:
+  `input`, `output`, `cache_read`, and `thinking`. Input excludes cached tokens;
+  output includes thinking tokens. Unreported counts remain `nil`.
+
+Plain Ruby consumers can update directly after adapting these calls. Rails
+hosts using RubyLLM persistence must complete the
+[2.0 upgrade](https://github.com/crmne/ruby_llm/blob/v2.0.0/docs/_reference/upgrading.md)
+on 2.0, including cleanup, before following the
+[2.1 upgrade](https://rubyllm.com/upgrading/). On Rails below 8.1.4, pin `json`
+to `< 3` before updating.
+
+Each Codex invocation records successful or failed usage attempts in RubyLLM.
+Timeouts cover process exit and pipe draining, including descendants that keep
+output pipes open after the CLI exits. Process-group cleanup remains bounded.

data/lib/ruby_llm/codex/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Codex
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/ruby_llm/providers/codex.rb

@@ -13,6 +13,8 @@ module RubyLLM
     # This provider is deliberately narrow: non-streaming text generation and
     # structured output are supported; RubyLLM tools and attachments are not.
     class Codex < Provider
+      protocol :codex, ::RubyLLM::Protocol
+
       class Error < RubyLLM::Error; end
       class TimeoutError < Error; end
       class UnsupportedFeatureError < Error; end
@@ -20,7 +22,7 @@ module RubyLLM
       DEFAULT_SANDBOX = "read-only"
       DEFAULT_TIMEOUT = 300
       DEFAULT_SHELL_ENVIRONMENT_INHERIT = "none"
-      MINIMUM_CLI_VERSION = "0.144.5"
+      MINIMUM_CLI_VERSION = "0.162.1"
       RESERVED_CONFIG_KEYS = %w[
         developer_instructions
         features.shell_snapshot
@@ -37,11 +39,23 @@ module RubyLLM
       end
 
       # rubocop:disable Metrics/ParameterLists
-      def complete(messages, tools:, temperature:, model:, params: {}, headers: {},
-        schema: nil, thinking: nil, tool_prefs: nil, &stream)
+      def complete(messages, tools:, temperature:, model:, provider_options: {}, headers: {},
+        schema: nil, thinking: nil, tool_prefs: nil, max_output_tokens: nil,
+        citations: false, caching: nil, protocol: nil, before_request: [],
+        usage_recorder: nil, provider_tools: [], compaction: nil, end_user: nil, &stream)
         validate_request!(tools:, temperature:, headers:, stream:)
 
-        options = codex_options(params)
+        unsupported = {
+          max_output_tokens:, citations: citations || nil, caching:,
+          provider_tools: provider_tools.empty? ? nil : provider_tools,
+          compaction:, end_user:, tool_prefs: (tool_prefs if tool_prefs&.values&.any?)
+        }.compact
+        unless unsupported.empty?
+          raise UnsupportedFeatureError,
+            "Unsupported Codex request options: #{unsupported.keys.join(", ")}"
+        end
+
+        options = codex_options(provider_options)
         developer_instructions, prompt = build_prompt(messages)
         request = {
           model: model.id,
@@ -51,9 +65,22 @@ module RubyLLM
           thinking:
         }
 
+        before_request.each { |hook| hook.call(request) }
+        tracker = Accounting::Usage::Tracker.new(
+          operation: :chat, provider: self, model:, config: @config, on_finish: usage_recorder
+        )
         with_working_directory(options) do |working_directory|
-          run_codex(request, working_directory:, options:)
+          ensure_cli_compatible!(working_directory, options)
+          tracker.start
+          response = run_codex(request, working_directory:, options:)
+          tracker.succeed(response)
         end
+      rescue Errno::ENOENT => error
+        tracker&.fail_pending(error)
+        raise Error, "Could not execute Codex CLI: #{error.message}. Install it or set codex_cli_path."
+      rescue => error
+        tracker&.fail_pending(error)
+        raise
       end
       # rubocop:enable Metrics/ParameterLists
 
@@ -109,11 +136,11 @@ module RubyLLM
           "Per-request HTTP headers do not apply to the local Codex provider"
       end
 
-      def codex_options(params)
-        validate_params!(params)
-        raw = params.is_a?(Hash) ? (params[:codex] || params["codex"] || {}) : {}
+      def codex_options(provider_options)
+        validate_provider_options!(provider_options)
+        raw = provider_options.is_a?(Hash) ? (provider_options[:codex] || provider_options["codex"] || {}) : {}
         unless raw.is_a?(Hash)
-          raise ArgumentError, "Codex params must be a Hash"
+          raise ArgumentError, "Codex provider_options must be a Hash"
         end
 
         raw = raw.transform_keys(&:to_sym)
@@ -144,16 +171,16 @@ module RubyLLM
         }
       end
 
-      def validate_params!(params)
-        unless params.is_a?(Hash)
-          raise ArgumentError, "RubyLLM params must be a Hash"
+      def validate_provider_options!(provider_options)
+        unless provider_options.is_a?(Hash)
+          raise ArgumentError, "RubyLLM provider_options must be a Hash"
         end
 
-        unsupported = params.keys.reject { |key| key.to_s == "codex" }
+        unsupported = provider_options.keys.reject { |key| key.to_s == "codex" }
         return if unsupported.empty?
 
         raise UnsupportedFeatureError,
-          "Unsupported params for the local Codex provider: #{unsupported.map(&:inspect).join(", ")}"
+          "Unsupported provider_options for the local Codex provider: #{unsupported.map(&:inspect).join(", ")}"
       end
 
       def validate_config!(config)
@@ -168,7 +195,7 @@ module RubyLLM
         value = raw.key?(:timeout) ? raw[:timeout] : @config.codex_timeout
         value = DEFAULT_TIMEOUT if value.nil?
         timeout = Float(value)
-        raise ArgumentError, "Codex timeout must be greater than zero" unless timeout.positive?
+        raise ArgumentError, "Codex timeout must be greater than zero" unless timeout.finite? && timeout.positive?
 
         timeout
       rescue TypeError, ArgumentError
@@ -200,8 +227,6 @@ module RubyLLM
       end
 
       def run_codex(request, working_directory:, options:)
-        ensure_cli_compatible!(working_directory, options)
-
         Tempfile.create(["ruby-llm-codex-output-", ".txt"]) do |output_file|
           with_schema_file(request[:schema]) do |schema_path|
             output_file.close
@@ -295,7 +320,7 @@ module RubyLLM
           chdir: working_directory,
           pgroup: true
         )
-        threads << writer = Thread.new do
+        threads << Thread.new do
           stdin.write(prompt)
         rescue Errno::EPIPE, IOError
           nil
@@ -306,12 +331,15 @@ module RubyLLM
         threads << stderr_reader = Thread.new { stderr.read }
         threads.each { |thread| thread.report_on_exception = false }
 
-        unless wait_thread.join(options[:timeout])
-          terminate_process_group(wait_thread)
-          raise TimeoutError, "Codex CLI timed out after #{options[:timeout]} seconds"
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + options[:timeout]
+        [wait_thread, *threads].each do |thread|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          unless thread.join([remaining, 0].max)
+            terminate_process_group(wait_thread, threads)
+            raise TimeoutError, "Codex CLI timed out after #{options[:timeout]} seconds"
+          end
         end
 
-        writer.join
         [stdout_reader.value, stderr_reader.value, wait_thread.value]
       ensure
         [stdin, stdout, stderr].compact.each do |io|
@@ -322,10 +350,13 @@ module RubyLLM
         threads.each { |thread| thread.kill if thread.alive? }
       end
 
-      def terminate_process_group(wait_thread)
+      def terminate_process_group(wait_thread, threads)
         Process.kill("TERM", -wait_thread.pid)
-        return if wait_thread.join(2)
-
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
+        [wait_thread, *threads].each do |thread|
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          thread.join([remaining, 0].max)
+        end
         Process.kill("KILL", -wait_thread.pid)
         wait_thread.join
       rescue Errno::ESRCH, Errno::ECHILD
@@ -335,7 +366,7 @@ module RubyLLM
       def add_reasoning_config(command, thinking)
         return unless thinking
 
-        effort = thinking.respond_to?(:effort) ? thinking.effort : thinking
+        effort = thinking.effort
         if effort
           add_config(command, "model_reasoning_effort", effort.to_s)
           return
@@ -387,7 +418,7 @@ module RubyLLM
       end
 
       def raise_invocation_error!(status, events, stderr)
-        event = events.reverse.find { |item| %w[turn.failed error].include?(item["type"]) }
+        event = events.reverse_each.find { |item| %w[turn.failed error].include?(item["type"]) }
         detail = event && (event["message"] || event["error"] || event).to_s
         detail = stderr.strip if detail.to_s.strip.empty?
         detail = "Codex exited with status #{status.exitstatus}" if detail.to_s.strip.empty?
@@ -395,14 +426,14 @@ module RubyLLM
       end
 
       def final_agent_message(events)
-        event = events.reverse.find do |item|
+        event = events.reverse_each.find do |item|
           item["type"] == "item.completed" && item.dig("item", "type") == "agent_message"
         end
         event&.dig("item", "text")
       end
 
       def build_message(content, model, events, stderr)
-        usage = events.reverse.find { |event| event["type"] == "turn.completed" }&.fetch("usage", {}) || {}
+        usage = events.reverse_each.find { |event| event["type"] == "turn.completed" }&.fetch("usage", {}) || {}
         cached = integer_or_nil(usage["cached_input_tokens"])
         total_input = integer_or_nil(usage["input_tokens"])
         uncached_input = total_input && [total_input - cached.to_i, 0].max
@@ -410,11 +441,14 @@ module RubyLLM
         Message.new(
           role: :assistant,
           content: content,
-          model_id: model,
-          input_tokens: uncached_input,
-          cached_tokens: cached,
-          output_tokens: integer_or_nil(usage["output_tokens"]),
-          thinking_tokens: integer_or_nil(usage["reasoning_output_tokens"]),
+          model:,
+          tokens: Tokens.new(
+            input: uncached_input,
+            cache_read: cached,
+            output: integer_or_nil(usage["output_tokens"]),
+            thinking: integer_or_nil(usage["reasoning_output_tokens"])
+          ),
+          finish_reason: :stop,
           raw: {events:, stderr: stderr.empty? ? nil : stderr}
         )
       end
@@ -449,23 +483,12 @@ module RubyLLM
       end
 
       def text_content(message)
-        content = message.content
-        return content if content.is_a?(String)
-
-        if content.is_a?(RubyLLM::Content)
-          unless content.attachments.empty?
-            raise UnsupportedFeatureError,
-              "Attachments are not supported by the Codex comparison provider"
-          end
-          return content.text.to_s
-        end
-
-        if defined?(RubyLLM::Content::Raw) && content.is_a?(RubyLLM::Content::Raw)
+        unless message.attachments.empty?
           raise UnsupportedFeatureError,
-            "Raw provider content is not supported by the Codex comparison provider"
+            "Attachments are not supported by the Codex comparison provider"
         end
 
-        content.respond_to?(:to_json) ? content.to_json : content.to_s
+        message.content
       end
 
       def present?(value)

data/lib/ruby_llm-codex.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "ruby_llm"
-require "ruby_llm/schema"
 require_relative "ruby_llm/codex/version"
 require_relative "ruby_llm/providers/codex"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-codex
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Paulo Fidalgo
@@ -14,22 +14,16 @@ dependencies:
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.16'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '1.16'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -85,6 +79,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- UPGRADE.md
 - lib/ruby_llm-codex.rb
 - lib/ruby_llm/codex/version.rb
 - lib/ruby_llm/providers/codex.rb
@@ -115,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Use a local, ChatGPT-authenticated Codex CLI as a RubyLLM provider
 test_files: []