ruby_llm-providers-codex 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7149ed6c601a6f26fc7d68cfe3a483584df57c32f48d221d9ad310e8852a533f
+  data.tar.gz: 079a0430624bc19c0aad5dd6f43c85a46db6fcf57aab6e37024985bf1596ba1d
+SHA512:
+  metadata.gz: 621b30e493e839e04d344c9be10b31ed76010f6b5077937bfea55f40b0c26a3571e8ca292e98884bcf8078a47073ca095a9b24668ef3223f7cf5766223179361
+  data.tar.gz: 7110983729be2b679856e5bc561b0340663c30037174cf2a675703129f75788d8b3ef0a0aa54d9c5bd9eb8413e98baf2fa3c77bc67a39ba615042c16bfec73c7

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-11-06
+
+- Initial release: `codex exec` as a RubyLLM provider with resumable threads,
+  per-message streaming, structured output, reasoning effort and attachment notes.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# ruby_llm-providers-codex
+
+A [RubyLLM](https://rubyllm.com) provider that uses the **OpenAI Codex agent**
+as the model. Each completion runs `codex exec` non-interactively, writes the
+prompt to its stdin and reads the JSON event stream from stdout.
+
+This is deliberately *not* an isolated stand-in for the OpenAI API. The agent
+keeps what makes it an agent: its own tools, sandbox, config and MCP servers,
+and it works in the current directory. Multi-turn chats resume the same Codex
+thread, so the agent keeps its context between turns.
+
+```ruby
+require 'ruby_llm/providers/codex'
+
+chat = RubyLLM.chat(model: 'default', provider: :codex)
+chat.ask('What does the Rakefile in this directory do?')
+chat.ask('Add a `lint` task to it') { |chunk| print chunk.content }
+```
+
+With [aia](https://github.com/madbomber/aia) the provider is picked from the
+model prefix:
+
+```bash
+aia --model codex/default review_prompt
+aia --model claude_code/sonnet=implementer,codex/default=reviewer --consensus review
+```
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RubyLLM 2.1 or newer
+- The Codex CLI on your PATH (`codex --version`), logged in with
+  `codex login`. No API key is read by this gem.
+
+## Installation
+
+```ruby
+gem 'ruby_llm-providers-codex', require: 'ruby_llm/providers/codex'
+```
+
+The provider registers itself as `:codex` when required.
+
+## Models
+
+The part after the slash goes straight to `codex --model`. The id `default`
+(or an empty id) sends no `--model` flag and lets the CLI choose.
+
+## Sessions
+
+RubyLLM hands the provider the whole transcript on every turn. When the
+transcript minus the newest message matches what the Codex thread already
+saw, only the new message is sent with `codex exec resume <thread id>`. Any
+other shape (rewound or edited history, a cleared chat, a changed system
+prompt) starts a fresh thread with the conversation replayed as a tagged
+transcript.
+
+```ruby
+chat.with_provider_options(codex: { resume: false })      # fresh thread every turn
+chat.with_provider_options(codex: { session_id: 'uuid' }) # continue a known thread
+```
+
+## Configuration
+
+Global options are `RubyLLM.config.codex_*`; the same keys can be set per
+chat with `with_provider_options(codex: { ... })`.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `command` | `codex` | CLI executable |
+| `cwd` | current directory | Directory the agent works in |
+| `timeout` | `600` | Seconds before the process group is killed; `nil` or `0` disables |
+| `sandbox` | CLI default | `--sandbox`: `read-only`, `workspace-write` or `danger-full-access` (new threads only) |
+| `args` | none | Extra CLI arguments, array or shell string (`--profile`, `-c key=value`, ...) |
+| `env` | none | Extra environment variables for the process |
+| `resume` | `true` | Reuse the thread across turns |
+| `session_id` | none | Per-request only: resume this thread id |
+
+## What is supported
+
+| Feature | How |
+|---|---|
+| Text, system prompts, multi-turn | Instructions go in as `developer_instructions`; see Sessions |
+| Streaming | Each completed agent message is yielded as one chunk; the last one is the reply |
+| Structured output (`with_schema`) | `--output-schema` via a temporary file |
+| `with_thinking(effort:)` | `model_reasoning_effort` (minimal, low, medium, high, xhigh) |
+| Token counts | From `turn.completed`: input, cached input, output and reasoning tokens |
+| Attachments | Noted in the prompt as `[Attached file 'name': path]`; the agent opens local files itself |
+| RubyLLM tools (`with_tools`) | **Not supported**: raises `UnsupportedFeatureError`. The provider class answers `accepts_tools?` with `false` so hosts such as aia can skip attaching tools |
+| temperature, max tokens | Ignored (logged at debug level) |
+
+## Safety
+
+Codex runs model-generated commands under its sandbox policy. Set `sandbox`
+explicitly for anything beyond read-only work.
+
+## Development
+
+```bash
+bundle install
+asgard test_verbose       # offline: the CLI is replaced by a fake runner
+asgard quality            # tests, rubocop, flog, flay, reek, ...
+```

data/lib/ruby_llm/providers/codex/command.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Builds the argv for one `codex exec` (or `codex exec resume`) call.
+      # The prompt itself always arrives on stdin, signalled by the final "-".
+      class Command
+        EFFORTS = %w[minimal low medium high xhigh].freeze
+
+        def initialize(settings)
+          @settings = settings
+        end
+
+        # @param model [String, nil] model id; "default" means the CLI's own choice
+        # @param resume_id [String, nil] thread id to continue
+        # @param system_prompt [String, nil] sent as developer_instructions when starting a thread
+        # @param schema_path [String, nil] file holding a JSON Schema for --output-schema
+        # @param effort [String, nil] one of EFFORTS
+        # @return [Array<String>]
+        def build(model: nil, resume_id: nil, system_prompt: nil, schema_path: nil, effort: nil)
+          argv = [@settings.command, 'exec']
+          argv << 'resume' if resume_id
+          argv.push('--json', '--skip-git-repo-check')
+          argv.push('--model', model.to_s) if self.class.named?(model)
+          argv.concat(fresh_thread_args(system_prompt, schema_path)) unless resume_id
+          argv.push('--config', self.class.toml_assignment('model_reasoning_effort', effort)) if effort
+          argv.concat(@settings.args)
+          argv << resume_id if resume_id
+          argv << '-'
+        end
+
+        class << self
+          def named?(model)
+            !(model.nil? || model.to_s.empty? || model.to_s == DEFAULT_MODEL)
+          end
+
+          # key=value for codex --config, with the value as a TOML literal.
+          def toml_assignment(key, value)
+            "#{key}=#{toml_literal(value)}"
+          end
+
+          def toml_literal(value)
+            case value
+            when String, Symbol then JSON.generate(value.to_s)
+            when true, false, Integer, Float then value.to_s
+            when Array then "[#{value.map { |item| toml_literal(item) }.join(', ')}]"
+            else raise ArgumentError, "unsupported codex config value: #{value.inspect}"
+            end
+          end
+
+          # The bare JSON Schema from RubyLLM's payload.
+          def schema_definition(schema)
+            schema[:schema] || schema['schema'] || schema
+          end
+        end
+
+        private
+
+        def fresh_thread_args(system_prompt, schema_path)
+          argv = []
+          argv.push('--sandbox', @settings.sandbox) if @settings.sandbox
+          if system_prompt && !system_prompt.strip.empty?
+            argv.push('--config', self.class.toml_assignment('developer_instructions', system_prompt))
+          end
+          argv.push('--output-schema', schema_path) if schema_path
+          argv
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Raised when the codex CLI cannot be run, exits without a result, or
+      # reports an error of its own.
+      class Error < RubyLLM::Error; end
+
+      # Raised when the CLI runs past the configured timeout and is killed.
+      class TimeoutError < Error; end
+
+      # Raised for RubyLLM features the CLI cannot honour, such as tools.
+      class UnsupportedFeatureError < Error; end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/response.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Reads `codex exec --json` events line by line. Each completed
+      # agent_message item is streamed as a Chunk; the last one is the reply.
+      # turn.completed carries the token usage.
+      class Response
+        attr_reader :session_id, :model_id, :events
+
+        def initialize(model:, schema: nil)
+          @model  = model
+          @schema = schema
+          @events = []
+          @text   = nil
+          @usage  = {}
+          @error  = nil
+        end
+
+        # @param line [String] one line of stdout
+        # @yield [RubyLLM::Chunk] a completed agent message
+        # @return [Hash, nil] the parsed event, or nil for non-JSON lines
+        def ingest(line)
+          event = self.class.parse(line)
+          return nil unless event
+
+          @events << event
+          case event['type']
+          when 'thread.started' then @session_id = event['thread_id']
+          when 'item.completed'
+            text = agent_text(event)
+            if text
+              @text = text
+              yield chunk(text) if block_given?
+            end
+          when 'turn.completed' then @usage = event['usage'] || {}
+          when 'turn.failed' then @error = event.dig('error', 'message') || event['error'].to_s
+          when 'error' then @error = event['message'].to_s
+          end
+          event
+        end
+
+        # @param run [Runner::Result, nil] used for diagnostics when no reply arrived
+        # @return [RubyLLM::Message]
+        def message(run = nil)
+          raise Error, "codex exec failed: #{@error}" if @error
+
+          raise_without_result!(run) if @text.nil?
+
+          total_input = @usage['input_tokens']
+          cached = @usage['cached_input_tokens']
+          Message.new(
+            role: :assistant,
+            content: @text,
+            model: @model,
+            input_tokens: total_input && [total_input.to_i - cached.to_i, 0].max,
+            output_tokens: @usage['output_tokens'],
+            cache_read_tokens: cached,
+            cache_write_tokens: @usage['cache_write_input_tokens'],
+            thinking_tokens: @usage['reasoning_output_tokens'],
+            finish_reason: :stop,
+            raw: { 'thread_id' => @session_id, 'usage' => @usage, 'events' => @events }
+          )
+        end
+
+        def self.parse(line)
+          text = line.to_s.strip
+          return nil unless text.start_with?('{')
+
+          JSON.parse(text)
+        rescue JSON::ParserError
+          RubyLLM.logger.debug { "codex: non-JSON output #{text.inspect}" }
+          nil
+        end
+
+        private
+
+        def agent_text(event)
+          item = event['item'] || {}
+          item['text'] if item['type'] == 'agent_message'
+        end
+
+        def raise_without_result!(run)
+          status = run&.status&.exitstatus
+          stderr = run&.stderr.to_s.strip
+          raise Error,
+                "codex exec exited#{" (#{status})" if status} without a reply#{": #{stderr}" unless stderr.empty?}"
+        end
+
+        def chunk(text)
+          Chunk.new(role: :assistant, content: text, model: @model)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/runner.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Spawns the CLI, feeds it stdin, and yields each stdout line on the
+      # caller's thread as it arrives. The process group is killed when the
+      # timeout passes.
+      class Runner
+        # What the process produced: full stdout, full stderr, and its exit status.
+        Result = Data.define(:stdout, :stderr, :status)
+        GRACE_SECONDS = 2
+        EOF = Object.new.freeze
+
+        # @param argv [Array<String>] command and arguments
+        # @param stdin [String] text written to the process's stdin
+        # @param cwd [String, nil] working directory (default: Dir.pwd)
+        # @param timeout [Numeric, nil] seconds before the process is killed
+        # @param env [Hash] extra environment variables
+        # @yield [String] each line of stdout
+        # @return [Result]
+        def run(argv, stdin: '', cwd: nil, timeout: nil, env: {}, &block)
+          Open3.popen3(env.to_h, *argv, chdir: cwd || Dir.pwd, pgroup: true) do |input, output, error, wait|
+            collect(input, output, error, wait, stdin:, timeout:, &block)
+          rescue TimeoutError
+            terminate(wait)
+            raise TimeoutError, "#{argv.first} did not finish within #{timeout}s"
+          end
+        rescue Errno::ENOENT => e
+          raise Error, "cannot run #{argv.first.inspect}: #{e.message}"
+        end
+
+        private
+
+        # Drives one spawned process: feeds stdin and reads stderr on their own
+        # threads, pumps stdout through a queue so each line can be yielded
+        # before the process exits, and assembles the Result once it does.
+        def collect(input, output, error, wait, stdin:, timeout:)
+          feeder = Thread.new { feed(input, stdin) }
+          errors = Thread.new { error.read }
+          queue  = Queue.new
+          reader = Thread.new { pump(output, queue) }
+          lines  = []
+          drain(queue, deadline(timeout)) do |line|
+            lines << line
+            yield line if block_given?
+          end
+          [feeder, reader].each(&:join)
+          Result.new(stdout: lines.join, stderr: errors.value.to_s, status: wait.value)
+        end
+
+        def deadline(timeout)
+          timeout && (now + timeout)
+        end
+
+        def feed(input, text)
+          input.binmode
+          input.write(text.to_s)
+        rescue Errno::EPIPE, IOError
+          nil
+        ensure
+          input.close unless input.closed?
+        end
+
+        def pump(output, queue)
+          output.each_line { |line| queue << line }
+        ensure
+          queue << EOF
+        end
+
+        # Pops lines until EOF, raising TimeoutError once the deadline passes.
+        def drain(queue, deadline)
+          loop do
+            remaining = deadline && [deadline - now, 0].max
+            line = remaining ? queue.pop(timeout: remaining) : queue.pop
+            raise TimeoutError if line.nil?
+            break if line.equal?(EOF)
+
+            yield line
+          end
+        end
+
+        def terminate(wait)
+          pgid = -wait.pid
+          Process.kill('TERM', pgid)
+          return if wait.join(GRACE_SECONDS)
+
+          Process.kill('KILL', pgid)
+          wait.join
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/session.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Decides, per completion, whether to resume the CLI session that
+      # answered the previous turn or to start a new one. A session is resumed
+      # only when the transcript RubyLLM hands over, minus the newest message,
+      # is exactly what that session already saw. A rewound, edited or cleared
+      # history gets a fresh session replayed from the whole transcript.
+      class Session
+        Plan = Data.define(:messages, :resume_id) do
+          def resume?
+            !resume_id.nil?
+          end
+        end
+
+        attr_reader :id
+
+        def initialize
+          reset!
+        end
+
+        # @param messages [Array<RubyLLM::Message>] the full RubyLLM transcript
+        # @param session_id [String, nil] a caller-chosen session to continue
+        # @param resume [Boolean] false forces a fresh session every time
+        # @return [Plan] the messages to send and the session to resume, if any
+        def plan(messages, session_id: nil, resume: true)
+          raise ArgumentError, 'no messages to send' if messages.empty?
+          return Plan.new(messages: [messages.last], resume_id: session_id) if session_id
+          return Plan.new(messages: messages, resume_id: nil) unless resume && continues?(messages)
+
+          Plan.new(messages: [messages.last], resume_id: @id)
+        end
+
+        # Remember which session answered, and what it has now seen.
+        def record(messages, reply, id:)
+          @id = id
+          @fingerprint = id ? Transcript.fingerprint(messages + [reply]) : nil
+        end
+
+        def reset!
+          @id = nil
+          @fingerprint = nil
+        end
+
+        private
+
+        def continues?(messages)
+          return false unless @id && @fingerprint && messages.size > 1
+
+          Transcript.fingerprint(messages[0...-1]) == @fingerprint
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/settings.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # The settings for one completion. Each value comes from, in order of
+      # precedence, chat.with_provider_options(codex: {...}), the
+      # RubyLLM.config.codex_* option, then the default here.
+      class Settings
+        DEFAULT_COMMAND = 'codex'
+        DEFAULT_TIMEOUT = 600
+        SANDBOXES = %w[read-only workspace-write danger-full-access].freeze
+
+        attr_reader :command, :cwd, :timeout, :sandbox, :args, :env, :session_id
+
+        def initialize(config, provider_options = {})
+          opts = self.class.namespaced(provider_options)
+          @command    = opts.fetch(:command) { config.codex_command } || DEFAULT_COMMAND
+          @cwd        = opts.fetch(:cwd) { config.codex_cwd }
+          @timeout    = self.class.positive_or_nil(opts.fetch(:timeout) { timeout_default(config) })
+          @sandbox    = self.class.sandbox(opts.fetch(:sandbox) { config.codex_sandbox })
+          @args       = self.class.split_args(opts.fetch(:args) { config.codex_args })
+          @env        = self.class.stringify(opts.fetch(:env) { config.codex_env })
+          @session_id = opts[:session_id]
+          @resume     = opts.fetch(:resume) { config.codex_resume.nil? || config.codex_resume }
+        end
+
+        # False when every completion must start a fresh CLI session.
+        def resume?
+          @resume ? true : false
+        end
+
+        class << self
+          # The codex: sub-hash of provider_options with symbol keys.
+          def namespaced(provider_options)
+            return {} unless provider_options.is_a?(Hash)
+
+            raw = provider_options[:codex] || provider_options['codex'] || {}
+            raise ArgumentError, 'provider_options[:codex] must be a Hash' unless raw.is_a?(Hash)
+
+            raw.transform_keys(&:to_sym)
+          end
+
+          # A positive number of seconds, or nil for "no timeout".
+          def positive_or_nil(value)
+            return nil if value.nil?
+
+            number = Float(value)
+            number.positive? ? number : nil
+          end
+
+          # Extra CLI arguments given as an array or a shell-style string.
+          def split_args(value)
+            case value
+            when nil then []
+            when String then Shellwords.split(value)
+            else Array(value).map(&:to_s)
+            end
+          end
+
+          def sandbox(value)
+            return nil if value.nil?
+
+            text = value.to_s
+            return text if SANDBOXES.include?(text)
+
+            raise ArgumentError, "codex sandbox must be one of #{SANDBOXES.join(', ')}"
+          end
+
+          def stringify(value)
+            (value || {}).to_h.to_h { |key, item| [key.to_s, item.to_s] }
+          end
+        end
+
+        private
+
+        def timeout_default(config)
+          config.codex_timeout.nil? ? DEFAULT_TIMEOUT : config.codex_timeout
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/transcript.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module RubyLLM
+  module Providers
+    class Codex < Provider
+      # Renders RubyLLM messages into the text the CLI reads from stdin, and
+      # fingerprints transcripts so Session can tell whether a CLI session
+      # already holds the earlier turns.
+      class Transcript
+        REPLAY_PREAMBLE = "The conversation so far follows. Continue it by writing the assistant's next reply " \
+                          "to the last turn. Do not repeat the tags.\n\n"
+        EMPTY = '(empty message)'
+
+        class << self
+          def fingerprint(messages)
+            Digest::SHA256.hexdigest(JSON.generate(messages.map { |message| summary(message) }))
+          end
+
+          def summary(message)
+            {
+              role: message.role.to_s,
+              content: message.content.to_s,
+              tool_call_id: message.tool_call_id,
+              tool_calls: tool_calls(message).map { |call| [call.id, call.name, call.arguments] },
+              attachments: attachments(message).map { |attachment| attachment_note(attachment) }
+            }
+          end
+
+          # The message text plus a note per attachment naming its location;
+          # the agent can open local files with its own tools.
+          def text_of(message)
+            parts = [message.content.to_s]
+            attachments(message).each { |attachment| parts << attachment_note(attachment) }
+            parts.reject(&:empty?).join("\n").strip
+          end
+
+          def attachment_note(attachment)
+            source = attachment.respond_to?(:source) ? attachment.source : attachment
+            name = attachment.respond_to?(:filename) ? attachment.filename : nil
+            location = source.respond_to?(:to_path) ? source.to_path : source.to_s
+            "[Attached file#{" '#{name}'" if name}: #{location}]"
+          end
+
+          def attachments(message)
+            message.respond_to?(:attachments) ? Array(message.attachments) : []
+          end
+
+          def tool_calls(message)
+            calls = message.respond_to?(:tool_calls) ? message.tool_calls : nil
+            calls.respond_to?(:values) ? calls.values : Array(calls)
+          end
+        end
+
+        def initialize(messages)
+          @system, @turns = messages.partition { |message| message.role == :system }
+        end
+
+        # All system messages joined, or nil when there are none.
+        def system_prompt
+          text = @system.map { |message| self.class.text_of(message) }.reject(&:empty?).join("\n\n")
+          text.empty? ? nil : text
+        end
+
+        # A lone user turn goes through as-is; anything longer becomes a
+        # tagged replay of the conversation.
+        def prompt
+          return EMPTY if @turns.empty?
+          return single_turn if @turns.one? && @turns.first.role == :user
+
+          REPLAY_PREAMBLE + @turns.map { |message| turn(message) }.join("\n")
+        end
+
+        private
+
+        def single_turn
+          text = self.class.text_of(@turns.first)
+          text.empty? ? EMPTY : text
+        end
+
+        def turn(message)
+          body = self.class.text_of(message)
+          case message.role
+          when :tool then "<tool_result id=\"#{message.tool_call_id}\">\n#{body}\n</tool_result>"
+          when :assistant then "<assistant>\n#{body}#{tool_calls_text(message)}\n</assistant>"
+          else "<user>\n#{body}\n</user>"
+          end
+        end
+
+        def tool_calls_text(message)
+          self.class.tool_calls(message).map do |call|
+            "\n<tool_call id=\"#{call.id}\" name=\"#{call.name}\">#{JSON.generate(call.arguments)}</tool_call>"
+          end.join
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    # Version of the ruby_llm-providers-codex gem. Kept in its own file
+    # so the gemspec can read the literal without loading the provider.
+    class Codex < Provider
+      VERSION = '0.0.1'
+
+      def self.version
+        VERSION
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/codex.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'tempfile'
+require 'ruby_llm/providers/codex/version'
+require 'ruby_llm/providers/codex/errors'
+require 'ruby_llm/providers/codex/settings'
+require 'ruby_llm/providers/codex/command'
+require 'ruby_llm/providers/codex/transcript'
+require 'ruby_llm/providers/codex/session'
+require 'ruby_llm/providers/codex/runner'
+require 'ruby_llm/providers/codex/response'
+
+module RubyLLM
+  module Providers
+    # Codex: the OpenAI Codex agent (`codex exec`) as a RubyLLM provider.
+    #
+    # Each completion spawns the codex CLI non-interactively, writes the
+    # prompt to its stdin and reads its JSON event stream from stdout. The
+    # agent keeps its own tools, config and MCP servers and works in the
+    # current directory (or config.codex_cwd). Multi-turn chats resume the
+    # same thread (`codex exec resume`) as long as the RubyLLM transcript
+    # still matches what that thread has seen; otherwise a fresh thread is
+    # started from the whole transcript.
+    #
+    #   require 'ruby_llm/providers/codex'
+    #   chat = RubyLLM.chat(model: 'default', provider: :codex)
+    #   chat.ask('Summarise the README in this directory')
+    class Codex < Provider
+      DEFAULT_MODEL = 'default'
+      MODELS = %w[default].freeze
+      CAPABILITIES = %w[streaming structured_output].freeze
+
+      # Satisfies RubyLLM's protocol lookups; every request goes through
+      # #complete below, never through a wire protocol.
+      protocol :codex, RubyLLM::Protocol
+
+      class << self
+        # Anything responding to #run like Runner; tests inject fakes here.
+        attr_accessor :runner
+
+        def configuration_options
+          %i[codex_command codex_cwd codex_timeout codex_sandbox codex_args codex_env codex_resume]
+        end
+
+        def configuration_requirements
+          []
+        end
+
+        def local?
+          true
+        end
+
+        # Any id goes straight to --model, so there is no catalog to check.
+        def assume_models_exist?
+          true
+        end
+
+        # The agent runs its own tools; RubyLLM tools cannot be handed to it.
+        # Hosts such as aia check this before attaching tools or MCP servers.
+        def accepts_tools?
+          false
+        end
+
+        def display_name
+          'Codex'
+        end
+
+        def model_id(model)
+          model.respond_to?(:id) ? model.id : model.to_s
+        end
+
+        def effort_for(thinking)
+          return nil unless thinking.respond_to?(:effort) && thinking.effort
+
+          value = thinking.effort.to_s
+          Command::EFFORTS.include?(value) ? value : nil
+        end
+      end
+
+      attr_reader :session
+
+      def initialize(config)
+        super
+        @session = Session.new
+      end
+
+      # Never contacted; the transport layer only needs a base URL.
+      def api_base
+        'cli://codex'
+      end
+
+      # Messages go to the CLI as text, so there is nothing to upload or
+      # convert beforehand.
+      def preprocess_messages(messages, **)
+        messages
+      end
+
+      def discard_missing_uploads(_messages, _error, **)
+        []
+      end
+
+      # :reek:LongParameterList -- the keyword set is RubyLLM's Provider#complete contract
+      def complete(messages, model:, tools: {}, provider_options: {}, schema: nil, thinking: nil,
+                   temperature: nil, max_output_tokens: nil, before_request: [], **, &block)
+        reject_tools!(tools)
+        log_ignored(temperature:, max_output_tokens:)
+        settings   = Settings.new(@config, provider_options)
+        plan       = session.plan(messages, session_id: settings.session_id, resume: settings.resume?)
+        transcript = Transcript.new(plan.messages)
+        with_schema_file(schema) do |schema_path|
+          argv = build_argv(settings, model, transcript, plan, schema_path, thinking)
+          before_request.each { |hook| hook.call({ argv: argv, prompt: transcript.prompt }) }
+          response = Response.new(model: model, schema: schema)
+          run = runner.run(argv, stdin: transcript.prompt, cwd: settings.cwd, timeout: settings.timeout,
+                                 env: settings.env) do |line|
+            response.ingest(line) { |chunk| block&.call(chunk) }
+          end
+          message = response.message(run)
+          session.record(messages, message, id: response.session_id)
+          message
+        end
+      end
+
+      # A static catalog: "default" stands for the CLI's own model choice;
+      # any other id is passed through to --model.
+      def list_models
+        MODELS.map { |id| static_model(id) }
+      end
+
+      private
+
+      def runner
+        self.class.runner || Runner.new
+      end
+
+      def build_argv(settings, model, transcript, plan, schema_path, thinking)
+        Command.new(settings).build(
+          model: self.class.model_id(model),
+          resume_id: plan.resume_id,
+          system_prompt: transcript.system_prompt,
+          schema_path: schema_path,
+          effort: self.class.effort_for(thinking)
+        )
+      end
+
+      # codex reads --output-schema from a file, so the schema is written to
+      # a temporary one for the length of the call.
+      def with_schema_file(schema)
+        return yield nil unless schema
+
+        Tempfile.create(['ruby_llm-codex-schema-', '.json']) do |file|
+          file.write(JSON.generate(Command.schema_definition(schema)))
+          file.flush
+          yield file.path
+        end
+      end
+
+      def static_model(id)
+        Model.new(
+          id: id,
+          name: "Codex (#{id})",
+          provider: slug,
+          capabilities: CAPABILITIES,
+          modalities: { input: %w[text], output: %w[text] },
+          metadata: { source: 'ruby_llm-providers-codex' }
+        )
+      end
+
+      def reject_tools!(tools)
+        return if tools.nil? || tools.empty?
+
+        raise UnsupportedFeatureError,
+              'RubyLLM tools cannot be handed to the codex CLI; the agent brings its own tools. ' \
+              'Remove with_tools or choose another provider.'
+      end
+
+      def log_ignored(**options)
+        ignored = options.compact.keys
+        return if ignored.empty?
+
+        RubyLLM.logger.debug { "codex: ignoring #{ignored.join(', ')} (not supported by codex exec)" }
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :codex, RubyLLM::Providers::Codex unless RubyLLM::Provider.resolve(:codex)

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-providers-codex
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+  - Dewayne VanHoozer
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+  - !ruby/object:Gem::Dependency
+    name: ruby_llm
+    requirement: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "2.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+    type: :runtime
+    prerelease: false
+    version_requirements: !ruby/object:Gem::Requirement
+      requirements:
+        -
+          - ">="
+          - !ruby/object:Gem::Version
+            version: "2.1"
+        -
+          - "<"
+          - !ruby/object:Gem::Version
+            version: "3"
+description: "Adds a codex provider to RubyLLM. Prompts are written to the Codex CLI's stdin in non-interactive mode and its JSON events are read back from stdout, so the agent (with its own tools, config and resumable threads) can be used wherever RubyLLM expects a model, e.g. `--model codex/default` in aia."
+email:
+  - dvanhoozer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+  - CHANGELOG.md
+  - LICENSE.txt
+  - README.md
+  - lib/ruby_llm/providers/codex.rb
+  - lib/ruby_llm/providers/codex/command.rb
+  - lib/ruby_llm/providers/codex/errors.rb
+  - lib/ruby_llm/providers/codex/response.rb
+  - lib/ruby_llm/providers/codex/runner.rb
+  - lib/ruby_llm/providers/codex/session.rb
+  - lib/ruby_llm/providers/codex/settings.rb
+  - lib/ruby_llm/providers/codex/transcript.rb
+  - lib/ruby_llm/providers/codex/version.rb
+homepage: "https://github.com/madbomber/ruby_llm-providers-codex"
+licenses:
+  - MIT
+metadata:
+  homepage_uri: "https://github.com/madbomber/ruby_llm-providers-codex"
+  source_code_uri: "https://github.com/madbomber/ruby_llm-providers-codex"
+  changelog_uri: "https://github.com/madbomber/ruby_llm-providers-codex/blob/main/CHANGELOG.md"
+  bug_tracker_uri: "https://github.com/madbomber/ruby_llm-providers-codex/issues"
+  rubygems_mfa_required: "true"
+rdoc_options: []
+require_paths:
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "3.2"
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+    -
+      - ">="
+      - !ruby/object:Gem::Version
+        version: "0"
+requirements: []
+rubygems_version: 4.1.0.beta3
+specification_version: 4
+summary: RubyLLM provider that drives the OpenAI Codex agent through `codex exec`.
+test_files: []