codex-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03d9e3beac47546980e8b63c3051c2d5100a3f1db197cf85a43c8d7b9eaf8f56
+  data.tar.gz: 879f569d1dfadc2451c7bf2ccb6a6cc36e897d3c1644e327bc8bb3d477014e72
+SHA512:
+  metadata.gz: c353524c5d986caea98150081c3efacaff18a918a643e2bf75af34f06e1b7d2c91627b433dc463d90c6f406cc20c68e8603430f2063ed6a1299ec881e19528bd
+  data.tar.gz: ad57c8fd2dd7de943f0b541930125219342fffab87ce42890e643d6590abc09deb4d03ed7876f29802d05cb73bb66fc91f0a692ec2cf902a9a1bd29264d2c36b

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-04-10)
+
+- Initial release
+- Client with `start_thread` and `resume_thread`
+- Blocking and streaming execution modes
+- JSONL event parsing (thread, turn, item, error events)
+- Item types: agent message, reasoning, command execution, file change, MCP tool call, web search, todo list
+- Config serialization to TOML CLI flags
+- Subprocess lifecycle management with graceful shutdown
+- API key redaction in inspect output

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Anton Kopylov
+
+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,145 @@
+# codex-ruby
+
+Ruby SDK for the [Codex CLI](https://github.com/openai/codex). Provides subprocess management, JSONL event parsing, and a clean API for building AI-powered applications.
+
+## Prerequisites
+
+[Codex CLI](https://github.com/openai/codex) must be installed and available in your PATH.
+
+```sh
+npm install -g @openai/codex
+```
+
+Supported platforms: macOS, Linux.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "codex-ruby"
+```
+
+Requires Ruby 3.2+.
+
+## Usage
+
+```ruby
+require "codex_sdk"
+
+client = CodexSDK::Client.new(
+  api_key: "your-api-key",      # or set CODEX_API_KEY env var
+  base_url: "https://api.openai.com/v1"  # optional
+)
+
+# Start a new thread
+thread = client.start_thread(
+  model: "o4-mini",
+  sandbox_mode: "read-only",
+  working_directory: "/path/to/project"
+)
+
+# Blocking run - returns a Turn with all items
+turn = thread.run("Explain this codebase")
+puts turn.final_response
+puts "Tokens used: #{turn.usage.input_tokens} in, #{turn.usage.output_tokens} out"
+
+# Streaming run - yields events as they arrive
+thread.run_streamed("Fix the failing tests") do |event|
+  case event
+  when CodexSDK::Events::ItemCompleted
+    case event.item
+    when CodexSDK::Items::AgentMessage
+      puts event.item.text
+    when CodexSDK::Items::CommandExecution
+      puts "Ran: #{event.item.command} (exit #{event.item.exit_code})"
+    when CodexSDK::Items::FileChange
+      event.item.changes.each { |c| puts "#{c[:kind]}: #{c[:path]}" }
+    end
+  when CodexSDK::Events::TurnCompleted
+    puts "Done! Used #{event.usage.output_tokens} output tokens"
+  when CodexSDK::Events::TurnFailed
+    puts "Error: #{event.error_message}"
+  end
+end
+```
+
+### Resume a thread
+
+```ruby
+thread = client.resume_thread("thread_abc123", model: "o4-mini")
+turn = thread.run("Now add tests for the changes")
+```
+
+### Interrupt
+
+```ruby
+# From another Ruby thread
+thread.interrupt
+```
+
+### Thread options
+
+```ruby
+client.start_thread(
+  model: "o4-mini",
+  sandbox_mode: "read-only",      # or "read-write"
+  working_directory: "/path",
+  approval_policy: "unless-allow-listed",
+  reasoning_effort: "high",
+  network_access: true,
+  web_search: true,
+  additional_directories: ["/other/path"],
+  skip_git_repo_check: false
+)
+```
+
+### Config overrides
+
+```ruby
+client = CodexSDK::Client.new(
+  api_key: "key",
+  config: {
+    mcp_servers: {
+      my_server: { url: "http://localhost:3000/mcp" }
+    }
+  }
+)
+```
+
+## Event types
+
+| Event | Description |
+|-------|-------------|
+| `Events::ThreadStarted` | Thread created, provides `thread_id` |
+| `Events::TurnStarted` | Turn began processing |
+| `Events::TurnCompleted` | Turn finished, provides `usage` |
+| `Events::TurnFailed` | Turn failed, provides `error_message` |
+| `Events::ItemStarted` | Item processing started |
+| `Events::ItemUpdated` | Item updated with partial data |
+| `Events::ItemCompleted` | Item finished, provides typed `item` |
+| `Events::Error` | Stream-level error, provides `message` |
+
+## Item types
+
+| Item | Fields |
+|------|--------|
+| `Items::AgentMessage` | `id`, `text` |
+| `Items::Reasoning` | `id`, `text` |
+| `Items::CommandExecution` | `id`, `command`, `aggregated_output`, `exit_code`, `status` |
+| `Items::FileChange` | `id`, `changes` (array of `{path:, kind:}`), `status` |
+| `Items::McpToolCall` | `id`, `server`, `tool`, `arguments`, `result`, `error`, `status` |
+| `Items::WebSearch` | `id`, `query` |
+| `Items::TodoList` | `id`, `items` (array of `{text:, completed:}`) |
+| `Items::Error` | `id`, `message` |
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/codex_sdk/agent_thread.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module CodexSDK
+  class AgentThread
+    attr_reader :id
+
+    def initialize(options, thread_options:, resume_id: nil)
+      @options = options
+      @thread_options = thread_options
+      @id = resume_id
+      @exec = nil
+    end
+
+    # Blocking run: sends prompt, collects all events, returns a Turn.
+    def run(input, turn_options: TurnOptions.new)
+      items = []
+      final_response = ""
+      usage = nil
+
+      run_streamed(input, turn_options: turn_options) do |event|
+        case event
+        when Events::ItemCompleted
+          items << event.item
+          final_response = event.item.text if event.item.is_a?(Items::AgentMessage)
+        when Events::TurnCompleted
+          usage = event.usage
+        when Events::TurnFailed
+          raise Error, event.error_message
+        when Events::Error
+          items << Items::Error.new(id: nil, message: event.message)
+        end
+      end
+
+      Turn.new(items: items, final_response: final_response, usage: usage)
+    end
+
+    # Streaming run: yields each event to the block as it arrives.
+    def run_streamed(input, turn_options: TurnOptions.new, &block)
+      prompt = normalize_input(input)
+
+      output_schema_path = nil
+      if turn_options.output_schema
+        output_schema_path = write_output_schema(turn_options.output_schema)
+      end
+
+      @exec = Exec.new(
+        @options,
+        thread_options: @thread_options
+      )
+
+      @exec.run(
+        prompt,
+        resume_thread_id: @id,
+        output_schema_path: output_schema_path
+      ) do |event|
+        # Capture thread ID from first event
+        @id = event.thread_id if event.is_a?(Events::ThreadStarted)
+
+        block.call(event)
+      end
+    ensure
+      cleanup_output_schema(output_schema_path)
+    end
+
+    # Interrupt the running subprocess.
+    def interrupt
+      @exec&.interrupt
+    end
+
+    private
+
+    def normalize_input(input)
+      case input
+      when String
+        input
+      when Array
+        input.filter_map { |entry|
+          entry[:text] if entry[:type] == "text"
+        }.join("\n\n")
+      else
+        input.to_s
+      end
+    end
+
+    def write_output_schema(schema)
+      dir = Dir.mktmpdir("codex-output-schema")
+      path = File.join(dir, "schema.json")
+      File.write(path, JSON.generate(schema))
+      path
+    end
+
+    def cleanup_output_schema(path)
+      return unless path
+      dir = File.dirname(path)
+      FileUtils.rm_rf(dir)
+    rescue StandardError
+      # best effort
+    end
+  end
+end

data/lib/codex_sdk/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CodexSDK
+  class Client
+    def initialize(codex_path: nil, base_url: nil, api_key: nil, config: {}, env: nil)
+      @options = Options.new(
+        codex_path: codex_path,
+        base_url: base_url,
+        api_key: api_key,
+        config: config,
+        env: env
+      )
+    end
+
+    # Start a new thread with the given options.
+    def start_thread(**kwargs)
+      thread_options = ThreadOptions.new(**kwargs)
+      AgentThread.new(@options, thread_options: thread_options)
+    end
+
+    # Resume an existing thread by ID.
+    def resume_thread(thread_id, **kwargs)
+      thread_options = ThreadOptions.new(**kwargs)
+      AgentThread.new(@options, thread_options: thread_options, resume_id: thread_id)
+    end
+  end
+end

data/lib/codex_sdk/config_serializer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CodexSDK
+  # Serializes Ruby hashes into --config CLI flags using TOML value syntax.
+  # Mirrors the TypeScript SDK's toTomlValue() and flattenConfig() logic.
+  module ConfigSerializer
+    BARE_KEY_PATTERN = /\A[A-Za-z0-9_-]+\z/
+
+    module_function
+
+    # Converts a nested hash into an array of ["--config", "key=value"] pairs.
+    #
+    #   to_flags({ sandbox_workspace_write: { network_access: true } })
+    #   # => ["--config", "sandbox_workspace_write.network_access=true"]
+    def to_flags(config)
+      flatten(config).flat_map { |key, value| ["--config", "#{key}=#{to_toml_value(value)}"] }
+    end
+
+    # Flattens a nested hash into dotted key paths.
+    #
+    #   flatten({ a: { b: 1, c: { d: 2 } } })
+    #   # => { "a.b" => 1, "a.c.d" => 2 }
+    def flatten(hash, prefix: nil)
+      hash.each_with_object({}) do |(key, value), result|
+        full_key = prefix ? "#{prefix}.#{key}" : key.to_s
+        if value.is_a?(Hash)
+          result.merge!(flatten(value, prefix: full_key))
+        else
+          result[full_key] = value
+        end
+      end
+    end
+
+    # Converts a Ruby value to a TOML literal string.
+    def to_toml_value(value)
+      case value
+      when String
+        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
+      when Array
+        "[#{value.map { |v| to_toml_value(v) }.join(", ")}]"
+      when Hash
+        inner = value.map { |k, v| "#{format_key(k)} = #{to_toml_value(v)}" }.join(", ")
+        "{#{inner}}"
+      when nil
+        raise ArgumentError, "cannot serialize nil to TOML"
+      else
+        raise ArgumentError, "unsupported type: #{value.class}"
+      end
+    end
+
+    def format_key(key)
+      str = key.to_s
+      str.match?(BARE_KEY_PATTERN) ? str : str.to_json
+    end
+  end
+end

data/lib/codex_sdk/events.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CodexSDK
+  module Events
+    # Parse a JSON hash into a typed event.
+    def self.parse(data)
+      case data["type"]
+      when "thread.started"  then ThreadStarted.new(thread_id: data["thread_id"])
+      when "turn.started"    then TurnStarted.new
+      when "turn.completed"  then TurnCompleted.from_json(data)
+      when "turn.failed"     then TurnFailed.new(error_message: data.dig("error", "message").to_s)
+      when "item.started"    then ItemStarted.new(item: Items.parse(data["item"]))
+      when "item.updated"    then ItemUpdated.new(item: Items.parse(data["item"]))
+      when "item.completed"  then ItemCompleted.new(item: Items.parse(data["item"]))
+      when "error"           then Error.new(message: data["message"].to_s)
+      else Unknown.new(type: data["type"], data: data)
+      end
+    end
+
+    ThreadStarted = Data.define(:thread_id)
+
+    TurnStarted = Data.define do
+      def initialize; super(); end
+    end
+
+    TurnCompleted = Data.define(:usage) do
+      def self.from_json(data)
+        usage_data = data["usage"]
+        return new(usage: nil) unless usage_data.is_a?(Hash) && usage_data.any?
+
+        usage = ::CodexSDK::Usage.new(
+          input_tokens: usage_data["input_tokens"].to_i,
+          cached_input_tokens: usage_data["cached_input_tokens"].to_i,
+          output_tokens: usage_data["output_tokens"].to_i
+        )
+        new(usage: usage)
+      end
+    end
+
+    TurnFailed = Data.define(:error_message)
+
+    ItemStarted = Data.define(:item)
+    ItemUpdated = Data.define(:item)
+    ItemCompleted = Data.define(:item)
+
+    Error = Data.define(:message)
+
+    Unknown = Data.define(:type, :data)
+  end
+end

data/lib/codex_sdk/exec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module CodexSDK
+  # Internal: manages the codex CLI subprocess.
+  # Spawns `codex exec --experimental-json`, writes prompt to stdin,
+  # reads JSONL events from stdout.
+  class Exec
+    SHUTDOWN_TIMEOUT = 10 # seconds to wait after SIGTERM before SIGKILL
+
+    attr_reader :pid
+
+    def initialize(options, thread_options: ThreadOptions.new)
+      @options = options
+      @thread_options = thread_options
+      @stdin = nil
+      @stdout = nil
+      @stderr = nil
+      @wait_thread = nil
+      @mutex = Mutex.new
+    end
+
+    # Spawns the subprocess, writes the prompt, reads JSONL events.
+    # Yields each parsed event hash to the block.
+    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
+
+      @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(env, *args)
+
+      # Write prompt and close stdin (one-shot, matching TypeScript SDK)
+      @stdin.write(prompt.to_s)
+      @stdin.close
+
+      # Read stderr in background thread
+      stderr_reader = ::Thread.new { @stderr.read rescue "" }
+
+      # Read JSONL from stdout line by line
+      @stdout.each_line do |line|
+        line = line.strip
+        next if line.empty?
+
+        begin
+          data = JSON.parse(line)
+        rescue JSON::ParserError => e
+          raise ParseError.new("Failed to parse event: #{e.message}", line: line)
+        end
+
+        event = Events.parse(data)
+        block.call(event)
+      end
+
+      stderr_buf = stderr_reader.value.to_s
+      status = @wait_thread.value
+
+      unless status.success?
+        code = status.exitstatus || status.termsig
+        truncated = stderr_buf.length > 500 ? "#{stderr_buf[0, 497]}..." : stderr_buf
+        raise ExecError.new(
+          "Codex exited with code #{code}: #{truncated}",
+          exit_code: code,
+          stderr: stderr_buf
+        )
+      end
+    ensure
+      cleanup
+    end
+
+    # Sends SIGTERM to the subprocess, waits, then SIGKILL if needed.
+    def interrupt
+      @mutex.synchronize do
+        return unless @wait_thread&.alive?
+
+        begin
+          Process.kill("TERM", @wait_thread.pid)
+        rescue Errno::ESRCH
+          return
+        end
+
+        # Wait for graceful shutdown
+        unless wait_for_exit(SHUTDOWN_TIMEOUT)
+          begin
+            Process.kill("KILL", @wait_thread.pid)
+          rescue Errno::ESRCH
+            # already gone
+          end
+        end
+      end
+    end
+
+    private
+
+    def build_args(resume_thread_id: nil, images: [], output_schema_path: nil)
+      codex_path = @options.codex_path || find_codex_path
+      args = [codex_path, "exec", "--experimental-json"]
+
+      # Global config overrides
+      args.concat(ConfigSerializer.to_flags(@options.config)) if @options.config.any?
+
+      # Base URL
+      if @options.base_url
+        args.concat(["--config", "openai_base_url=#{ConfigSerializer.to_toml_value(@options.base_url)}"])
+      end
+
+      # Thread options -> CLI flags
+      to = @thread_options
+      args.concat(["--model", to.model]) if to.model
+      args.concat(["--sandbox", to.sandbox_mode]) if to.sandbox_mode
+      args.concat(["--cd", to.working_directory]) if to.working_directory
+      args << "--dangerously-bypass-approvals-and-sandbox" if to.dangerously_bypass_approvals_and_sandbox
+      args << "--skip-git-repo-check" if to.skip_git_repo_check
+
+      to.additional_directories.each { |dir| args.concat(["--add-dir", dir]) }
+
+      if to.reasoning_effort
+        args.concat(["--config", "model_reasoning_effort=#{ConfigSerializer.to_toml_value(to.reasoning_effort)}"])
+      end
+
+      unless to.network_access.nil?
+        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
+
+      if to.approval_policy
+        args.concat(["--config", "approval_policy=#{ConfigSerializer.to_toml_value(to.approval_policy)}"])
+      end
+
+      # Output schema
+      args.concat(["--output-schema", output_schema_path]) if output_schema_path
+
+      # Resume
+      args.concat(["resume", resume_thread_id]) if resume_thread_id
+
+      # Images (always last)
+      images.each { |path| args.concat(["--image", path]) }
+
+      args
+    end
+
+    def build_env
+      base_env = @options.env || ENV.to_h
+      env = base_env.dup
+      env["CODEX_API_KEY"] = @options.api_key if @options.api_key
+      env["CODEX_INTERNAL_ORIGINATOR_OVERRIDE"] ||= "codex_sdk_rb"
+      env
+    end
+
+    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 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
+
+    def cleanup
+      @stdin&.close unless @stdin&.closed?
+      @stdout&.close unless @stdout&.closed?
+      @stderr&.close unless @stderr&.closed?
+    end
+  end
+end

data/lib/codex_sdk/items.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CodexSDK
+  module Items
+    # Parse a JSON hash into a typed item.
+    def self.parse(data)
+      case data["type"]
+      when "agent_message"   then AgentMessage.from_json(data)
+      when "reasoning"       then Reasoning.from_json(data)
+      when "command_execution" then CommandExecution.from_json(data)
+      when "file_change"     then FileChange.from_json(data)
+      when "mcp_tool_call"   then McpToolCall.from_json(data)
+      when "web_search"      then WebSearch.from_json(data)
+      when "todo_list"       then TodoList.from_json(data)
+      when "error"           then Error.from_json(data)
+      else Unknown.new(id: data["id"], type: data["type"], data: data)
+      end
+    end
+
+    AgentMessage = Data.define(:id, :text) do
+      def self.from_json(data)
+        new(id: data["id"], text: data["text"].to_s)
+      end
+    end
+
+    Reasoning = Data.define(:id, :text) do
+      def self.from_json(data)
+        new(id: data["id"], text: data["text"].to_s)
+      end
+    end
+
+    CommandExecution = Data.define(:id, :command, :aggregated_output, :exit_code, :status) do
+      def self.from_json(data)
+        new(
+          id: data["id"],
+          command: data["command"].to_s,
+          aggregated_output: data["aggregated_output"].to_s,
+          exit_code: data["exit_code"],
+          status: data["status"].to_s
+        )
+      end
+    end
+
+    FileChange = Data.define(:id, :changes, :status) do
+      def self.from_json(data)
+        changes = (data["changes"] || []).map do |c|
+          { path: c["path"], kind: c["kind"] }
+        end
+        new(id: data["id"], changes: changes, status: data["status"].to_s)
+      end
+    end
+
+    McpToolCall = Data.define(:id, :server, :tool, :arguments, :result, :error, :status) do
+      def self.from_json(data)
+        new(
+          id: data["id"],
+          server: data["server"].to_s,
+          tool: data["tool"].to_s,
+          arguments: data["arguments"],
+          result: data["result"],
+          error: data["error"],
+          status: data["status"].to_s
+        )
+      end
+    end
+
+    WebSearch = Data.define(:id, :query) do
+      def self.from_json(data)
+        new(id: data["id"], query: data["query"].to_s)
+      end
+    end
+
+    TodoList = Data.define(:id, :items) do
+      def self.from_json(data)
+        items = (data["items"] || []).map do |item|
+          { text: item["text"], completed: item["completed"] }
+        end
+        new(id: data["id"], items: items)
+      end
+    end
+
+    Error = Data.define(:id, :message) do
+      def self.from_json(data)
+        new(id: data["id"], message: data["message"].to_s)
+      end
+    end
+
+    Unknown = Data.define(:id, :type, :data)
+  end
+end

data/lib/codex_sdk/options.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module CodexSDK
+  # Constructor options for CodexSDK::Client.
+  Options = Data.define(
+    :codex_path,  # Override path to codex binary
+    :base_url,    # OpenAI API base URL
+    :api_key,     # API key (set as CODEX_API_KEY env var)
+    :config,      # Arbitrary --config key=value overrides (Hash)
+    :env          # Full env replacement (no ENV inheritance when set)
+  ) do
+    def initialize(codex_path: nil, base_url: nil, api_key: nil, config: {}, env: nil)
+      super
+    end
+
+    def inspect
+      redacted_key = api_key ? "[REDACTED]" : "nil"
+      "#<#{self.class} codex_path=#{codex_path.inspect} base_url=#{base_url.inspect} " \
+        "api_key=#{redacted_key} config=#{config.inspect} env=#{env ? "[SET]" : "nil"}>"
+    end
+  end
+
+  # Per-thread options controlling model, sandbox, and behavior.
+  ThreadOptions = Data.define(
+    :model,
+    :sandbox_mode,
+    :working_directory,
+    :approval_policy,
+    :dangerously_bypass_approvals_and_sandbox,
+    :reasoning_effort,
+    :network_access,
+    :web_search,
+    :additional_directories,
+    :skip_git_repo_check
+  ) do
+    def initialize(
+      model: nil,
+      sandbox_mode: nil,
+      working_directory: nil,
+      approval_policy: nil,
+      dangerously_bypass_approvals_and_sandbox: false,
+      reasoning_effort: nil,
+      network_access: nil,
+      web_search: nil,
+      additional_directories: [],
+      skip_git_repo_check: false
+    )
+      super
+    end
+  end
+
+  # Per-turn options (output schema, abort).
+  TurnOptions = Data.define(:output_schema) do
+    def initialize(output_schema: nil)
+      super
+    end
+  end
+
+  # Token usage from a completed turn.
+  Usage = Data.define(:input_tokens, :cached_input_tokens, :output_tokens) do
+    def initialize(input_tokens: 0, cached_input_tokens: 0, output_tokens: 0)
+      super
+    end
+  end
+
+  # Result of a blocking Thread#run call.
+  Turn = Data.define(:items, :final_response, :usage) do
+    def initialize(items: [], final_response: "", usage: nil)
+      super
+    end
+  end
+end

data/lib/codex_sdk/version.rb

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

data/lib/codex_sdk.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "codex_sdk/version"
+
+module CodexSDK
+  class Error < StandardError; end
+
+  class ExecError < Error
+    attr_reader :exit_code, :stderr
+
+    def initialize(message, exit_code: nil, stderr: nil)
+      @exit_code = exit_code
+      @stderr = stderr
+      super(message)
+    end
+  end
+
+  class ParseError < Error
+    attr_reader :line
+
+    def initialize(message, line: nil)
+      @line = line
+      super(message)
+    end
+  end
+end
+
+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/exec"
+require_relative "codex_sdk/agent_thread"
+require_relative "codex_sdk/client"

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: codex-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+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'
+description: A Ruby client for the Codex CLI, providing subprocess management, JSONL
+  event parsing, and a clean API for building AI-powered applications.
+email:
+- anton@tonic20.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/codex_sdk.rb
+- lib/codex_sdk/agent_thread.rb
+- lib/codex_sdk/client.rb
+- lib/codex_sdk/config_serializer.rb
+- lib/codex_sdk/events.rb
+- lib/codex_sdk/exec.rb
+- lib/codex_sdk/items.rb
+- lib/codex_sdk/options.rb
+- lib/codex_sdk/version.rb
+homepage: https://github.com/tonic20/codex-ruby
+licenses:
+- MIT
+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
+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: 3.7.2
+specification_version: 4
+summary: Ruby SDK for the Codex CLI
+test_files: []