Class: AgentHarness::Providers::Codex

Inherits:
Base
  • Object
show all
Includes:
McpConfigFileSupport, RateLimitResetParsing
Defined in:
lib/agent_harness/providers/codex.rb

Overview

OpenAI Codex CLI provider

Provides integration with the OpenAI Codex CLI tool.

Defined Under Namespace

Classes: StreamingEvent

Constant Summary collapse

SUPPORTED_CLI_VERSION = 
"0.116.0"
SUPPORTED_CLI_REQUIREMENT = 
Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.117.0").freeze
OAUTH_REFRESH_FAILURE_PATTERNS = 
[
  /refresh_token_reused/i,
  /failed to refresh token\b.*\b401\b/im,
  /failed to refresh token\b.*unauthorized/im,
  /failed to refresh token\b.*\binvalid_client\b/im,
  /failed to refresh token\b.*\binvalid_grant\b/im,
  /failed to refresh token\b.*invalid.*refresh.*token/im,
  /failed to refresh token\b.*refresh.*token.*invalid/im,
  /your access token could not be refreshed because\b.*\b401\b/im,
  /your access token could not be refreshed because\b.*unauthorized/im,
  /your access token could not be refreshed because\b.*\binvalid_client\b/im,
  /your access token could not be refreshed because\b.*\binvalid_grant\b/im,
  /your access token could not be refreshed because\b.*invalid.*refresh.*token/im,
  /your access token could not be refreshed because\b.*refresh.*token.*invalid/im,
  /your access token could not be refreshed because\s+your refresh token .*already (?:been )?used/im,
  /refresh token .*already (?:been )?used/im
].freeze
OAUTH_REFRESH_TRANSIENT_PATTERNS = 
[
  /your access token could not be refreshed because\s+(?:the\s+)?auth(?:entication)? service(?:\s+(?:is|was))?\s+(?:temporarily\s+)?unavailable/im,
  /your access token could not be refreshed because .*connection.*error/im,
  /failed to refresh token\b.*connection.*error/im,
  /failed to refresh token\b.*service(?:\s+(?:is|was))?\s+(?:temporarily\s+)?unavailable/im
].freeze
SHARED_OUTPUT_ERROR_PATTERNS = 
{
  quota_exceeded: [
    /free tier limit reached/i,
    /please upgrade to a paid plan/i,
    /quota.*exceeded/i,
    /insufficient.*quota/i,
    /billing/i
  ],
  rate_limited: [
    /rate.?limit/i,
    /too.?many.?requests/i,
    /\b429\b/
  ],
  auth_expired: [
    /authentication_error/i,
    /invalid_grant/i,
    /Token is expired or invalid/i,
    /unauthorized/i
  ],
  sandbox_failure: [
    /bwrap.*no permissions/i,
    /no permissions to create a new namespace/i,
    /unprivileged.*namespace/i
  ],
  transient_error: [
    /timeout/i,
    /connection.*error/i,
    /service.*unavailable/i,
    /\b503\b/,
    /\b502\b/,
    /connection.*reset/i
  ]
}.tap { |h| h.each_value(&:freeze) }.freeze
STDOUT_ERROR_PATTERNS = 
SHARED_OUTPUT_ERROR_PATTERNS.merge(
  auth_expired: [
    /authentication_error/i,
    /invalid_grant/i,
    /Token is expired or invalid/i,
    /unauthorized/i
  ]
).tap { |h| h.each_value(&:freeze) }.freeze
STDERR_ERROR_PATTERNS = 
SHARED_OUTPUT_ERROR_PATTERNS.merge(
  auth_expired: OAUTH_REFRESH_FAILURE_PATTERNS + [
    /invalid.*api.*key/i,
    /unauthorized/i,
    /authentication_error/i,
    /invalid_grant/i,
    /Token is expired or invalid/i,
    /\b401\b/,
    /incorrect.*api.*key/i
  ],
  transient_error: OAUTH_REFRESH_TRANSIENT_PATTERNS + SHARED_OUTPUT_ERROR_PATTERNS[:transient_error]
).tap { |h| h.each_value(&:freeze) }.freeze

Constants inherited from Base

Base::COMMON_ERROR_PATTERNS, Base::DEFAULT_SMOKE_TEST_CONTRACT

Instance Attribute Summary

Attributes inherited from Base

#config, #executor, #logger

Class Method Summary collapse

Instance Method Summary collapse

Methods included from McpConfigFileSupport

#cleanup_mcp_tempfiles!, #write_mcp_config_file

Methods included from RateLimitResetParsing

#parse_rate_limit_reset

Methods inherited from Base

#configure, #initialize, #parse_container_output, #parse_rate_limit_reset, #parse_test_error, #sandboxed_environment?, #send_chat_message

Methods included from Adapter

#auth_type, #chat_transport, #chat_transport_type, #fetch_mcp_servers, included, metadata_package_name, #noisy_error_patterns, normalize_metadata_installation, normalize_metadata_source_type, normalize_metadata_version_requirement, #parse_rate_limit_reset, #smoke_test, #smoke_test_contract, #supports_chat?, #supports_dangerous_mode?, #supports_text_mode?, #supports_token_counting?, #supports_tool_control?, #validate_mcp_servers!

Constructor Details

This class inherits a constructor from AgentHarness::Providers::Base

Class Method Details

.available? ⇒ Boolean

Returns:

  • (Boolean) 


138
139
140
141
 
# File 'lib/agent_harness/providers/codex.rb', line 138

def available?
  executor = AgentHarness.configuration.command_executor
  !!executor.which(binary_name)
end

.binary_name ⇒ Object 



106
107
108
 
# File 'lib/agent_harness/providers/codex.rb', line 106

def binary_name
  "codex"
end

.classify_output_chunk(text, stream:, stdout_buffer: nil) ⇒ nil, Hash

Classify a chunk of output text from the provider CLI in real-time

Can be called during streaming to classify both stdout and stderr chunks as they arrive. For stdout, attempts to parse JSONL events and extract error information from structured output.

Because CommandExecutor reads arbitrary 4096-byte chunks, a single JSONL event may be split across consecutive calls. Pass a String buffer via stdout_buffer that persists across calls so incomplete trailing lines are re-assembled before parsing.

Parameters:

  • text (String) —

    the output chunk to classify

  • stream (:stdout, :stderr) —

    which stream the text came from

  • stdout_buffer (String, nil) (defaults to: nil) —

    mutable String accumulator for incomplete stdout lines across calls (ignored for stderr)

Returns:

  • (nil, Hash) —

    nil if no error detected, or a Hash with :reason (Symbol)



127
128
129
130
131
132
133
134
135
136
 
# File 'lib/agent_harness/providers/codex.rb', line 127

def classify_output_chunk(text, stream:, stdout_buffer: nil)
  return nil if text.nil? || text.strip.empty?

  case normalize_output_stream(stream)
  when :stdout
    classify_stdout_chunk(text, stdout_buffer)
  when :stderr
    classify_stderr_chunk(text)
  end
end

.discover_models ⇒ Object 



172
173
174
175
176
177
178
 
# File 'lib/agent_harness/providers/codex.rb', line 172

def discover_models
  return [] unless available?

  [
    {name: "codex", family: "codex", tier: "standard", provider: "codex"}
  ]
end

.firewall_requirements ⇒ Object 



152
153
154
155
156
157
158
159
160
 
# File 'lib/agent_harness/providers/codex.rb', line 152

def firewall_requirements
  {
    domains: [
      "api.openai.com",
      "openai.com"
    ],
    ip_ranges: []
  }
end

.installation_contract(version: SUPPORTED_CLI_VERSION) ⇒ Object 



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/agent_harness/providers/codex.rb', line 180

def installation_contract(version: SUPPORTED_CLI_VERSION)
  version = version.strip if version.respond_to?(:strip)

  unless version.is_a?(String) && !version.empty?
    raise ArgumentError,
      "Unsupported Codex CLI version #{version.inspect}; " \
      "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
  end

  parsed_version = begin
    Gem::Version.new(version)
  rescue ArgumentError
    raise ArgumentError,
      "Unsupported Codex CLI version #{version.inspect}; " \
      "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
  end

  unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(parsed_version)
    raise ArgumentError,
      "Unsupported Codex CLI version #{version.inspect}; " \
      "supported versions must satisfy #{SUPPORTED_CLI_REQUIREMENT}"
  end

  default_package = "@openai/codex@#{version}".freeze
  install_command_prefix = ["npm", "install", "-g", "--ignore-scripts"].freeze
  install_command = (install_command_prefix + [default_package]).freeze
  supported_versions = [version].freeze
  version_requirement = SUPPORTED_CLI_REQUIREMENT.requirements
    .map { |op, ver| "#{op} #{ver}".freeze }
    .freeze

  contract = {
    source: :npm,
    package: default_package,
    package_name: "@openai/codex",
    version: version,
    version_requirement: version_requirement,
    binary_name: binary_name,
    install_command_prefix: install_command_prefix,
    install_command: install_command,
    supported_versions: supported_versions
  }

  contract.each_value do |value|
    value.freeze if value.is_a?(String)
  end
  contract.freeze
end

.instruction_file_paths ⇒ Object 



162
163
164
165
166
167
168
169
170
 
# File 'lib/agent_harness/providers/codex.rb', line 162

def instruction_file_paths
  [
    {
      path: "AGENTS.md",
      description: "OpenAI Codex agent instructions",
      symlink: false
    }
  ]
end

.parse_cli_jsonl_transcript(raw_output, max_events: nil) ⇒ Object 



233
234
235
236
237
238
239
 
# File 'lib/agent_harness/providers/codex.rb', line 233

def parse_cli_jsonl_transcript(raw_output, max_events: nil)
  return parser_instance.send(:parse_jsonl_output, "") if max_events && max_events <= 0

  output = max_events ? tail_nonempty_lines(raw_output, limit: max_events).join("\n") : raw_output

  parser_instance.send(:parse_jsonl_output, output)
end

.parse_streaming_event(line) ⇒ Object

Parse a single Codex JSONL event as it arrives on stdout and classify it for real-time progress tracking. Returns nil for malformed JSON, scalar JSON values, plain-text output, or unsupported event types.



244
245
246
247
248
249
250
251
 
# File 'lib/agent_harness/providers/codex.rb', line 244

def parse_streaming_event(line)
  event = JSON.parse(line.to_s)
  return unless event.is_a?(Hash)

  parser_instance.send(:build_streaming_event, event)
rescue JSON::ParserError, TypeError
  nil
end

.provider_metadata_overrides ⇒ Object 



143
144
145
146
147
148
149
150
 
# File 'lib/agent_harness/providers/codex.rb', line 143

def provider_metadata_overrides
  {
    auth: {
      service: :openai,
      api_family: :openai
    }
  }
end

.provider_name ⇒ Object 



102
103
104
 
# File 'lib/agent_harness/providers/codex.rb', line 102

def provider_name
  :codex
end

.smoke_test_contract ⇒ Object 



229
230
231
 
# File 'lib/agent_harness/providers/codex.rb', line 229

def smoke_test_contract
  Base::DEFAULT_SMOKE_TEST_CONTRACT
end

Instance Method Details

#api_key_env_var_names ⇒ Object 



419
 
# File 'lib/agent_harness/providers/codex.rb', line 419

def api_key_env_var_names = ["OPENAI_API_KEY"]

#api_key_unset_vars ⇒ Object 



421
 
# File 'lib/agent_harness/providers/codex.rb', line 421

def api_key_unset_vars = ["OPENAI_BASE_URL", "OPENAI_HEADER_X_AGENT_RUN_ID", "OPENAI_HEADER_X_PROXY_TOKEN"]

#auth_lock_config ⇒ Object 



613
614
615
 
# File 'lib/agent_harness/providers/codex.rb', line 613

def auth_lock_config
  {path: "/tmp/codex-auth.lock", timeout: 30}
end

#auth_status ⇒ Object 



539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
 
# File 'lib/agent_harness/providers/codex.rb', line 539

def auth_status
  api_key = ENV["OPENAI_API_KEY"]
  if api_key && !api_key.strip.empty?
    if api_key.strip.start_with?("sk-")
      return {valid: true, expires_at: nil, error: nil, auth_method: :api_key}
    else
      return {valid: false, expires_at: nil, error: "OPENAI_API_KEY is set but does not appear to be a valid OpenAI API key", auth_method: nil}
    end
  end

  credentials = read_codex_credentials
  if credentials
    key = credentials["api_key"] || credentials["apiKey"] || credentials["OPENAI_API_KEY"]
    if key.is_a?(String) && !key.strip.empty?
      if key.strip.start_with?("sk-")
        return {valid: true, expires_at: nil, error: nil, auth_method: :config_file}
      else
        return {valid: false, expires_at: nil, error: "Config file API key is set but does not appear to be a valid OpenAI API key", auth_method: nil}
      end
    end
  end

  {valid: false, expires_at: nil, error: "No OpenAI API key found. Set OPENAI_API_KEY or configure in #{codex_config_path}", auth_method: nil}
rescue IOError, JSON::ParserError => e
  {valid: false, expires_at: nil, error: e.message, auth_method: nil}
end

#build_mcp_flags(mcp_servers, working_dir: nil) ⇒ Object 



441
442
443
444
445
446
 
# File 'lib/agent_harness/providers/codex.rb', line 441

def build_mcp_flags(mcp_servers, working_dir: nil)
  return [] if mcp_servers.empty?

  config_path = write_mcp_config_file(mcp_servers, working_dir: working_dir)
  ["--mcp-config", config_path]
end

#capabilities ⇒ Object 



407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/agent_harness/providers/codex.rb', line 407

def capabilities
  {
    streaming: false,
    file_upload: false,
    vision: false,
    tool_use: true,
    json_mode: false,
    mcp: true,
    dangerous_mode: true
  }
end

#cli_env_overrides ⇒ Object 



425
 
# File 'lib/agent_harness/providers/codex.rb', line 425

def cli_env_overrides = {"PAID_CODEX_SUBSCRIPTION_AUTH" => "1"}

#config_file_content(options = {}) ⇒ Object 



595
596
597
598
599
600
601
602
603
 
# File 'lib/agent_harness/providers/codex.rb', line 595

def config_file_content(options = {})
  <<~TOML
    [chatgpt]
    model_provider = "#{escape_toml_string(options[:model_provider])}"
    base_url = "#{escape_toml_string(options[:base_url])}"
    env_key = "#{escape_toml_string(options[:env_key])}"
    wire_api = "#{escape_toml_string(options[:wire_api])}"
  TOML
end

#configuration_schema ⇒ Object 



399
400
401
402
403
404
405
 
# File 'lib/agent_harness/providers/codex.rb', line 399

def configuration_schema
  {
    fields: [],
    auth_modes: [:api_key],
    openai_compatible: true
  }
end

#dangerous_mode_flags ⇒ Object 



452
453
454
 
# File 'lib/agent_harness/providers/codex.rb', line 452

def dangerous_mode_flags
  ["--full-auto"]
end

#display_name ⇒ Object 



395
396
397
 
# File 'lib/agent_harness/providers/codex.rb', line 395

def display_name
  "OpenAI Codex CLI"
end

#error_classification_patterns ⇒ Object 



511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'lib/agent_harness/providers/codex.rb', line 511

def error_classification_patterns
  super.merge(
    auth_expired: [
      /refresh_token_reused/i,
      /refresh token has already been used/i,
      /Please log out and sign in again/i,
      /authentication_error/i,
      /invalid_grant/i,
      /Token is expired or invalid/i
    ],
    abort: [
      /free tier limit reached/i,
      /please upgrade to a paid plan/i,
      /bwrap.*no permissions/i,
      /no permissions to create a new namespace/i,
      /unprivileged.*namespace/i
    ]
  )
end

#error_patterns ⇒ Object 



488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
 
# File 'lib/agent_harness/providers/codex.rb', line 488

def error_patterns
  {
    rate_limited: COMMON_ERROR_PATTERNS[:rate_limited],
    timeout: [
      /your access token could not be refreshed.*(?:timeout|timed.?out)/im,
      /failed to refresh token\b.*(?:timeout|timed.?out)/im
    ],
    transient: COMMON_ERROR_PATTERNS[:transient] + [
      /connection.*reset/i
    ] + OAUTH_REFRESH_TRANSIENT_PATTERNS,
    auth_expired: COMMON_ERROR_PATTERNS[:auth_expired] + [
      /\b401\b/,
      /incorrect.*api.*key/i
    ] + OAUTH_REFRESH_FAILURE_PATTERNS,
    quota_exceeded: COMMON_ERROR_PATTERNS[:quota_exceeded],
    sandbox_failure: [
      /bwrap.*no permissions/i,
      /no permissions to create a new namespace/i,
      /unprivileged.*namespace/i
    ]
  }
end

#execution_semantics ⇒ Object 



466
467
468
469
470
471
472
473
474
475
476
477
 
# File 'lib/agent_harness/providers/codex.rb', line 466

def execution_semantics
  {
    prompt_delivery: :arg,
    output_format: :json,
    sandbox_aware: true,
    uses_subcommand: true,
    non_interactive_flag: nil,
    legitimate_exit_codes: [0],
    stderr_is_diagnostic: true,
    parses_rate_limit_reset: false
  }
end

#health_status ⇒ Object 



566
567
568
569
570
571
572
573
574
575
576
577
 
# File 'lib/agent_harness/providers/codex.rb', line 566

def health_status
  unless self.class.available?
    return {healthy: false, message: "Codex CLI not found in PATH. Install from https://github.com/openai/codex"}
  end

  auth = auth_status
  unless auth[:valid]
    return {healthy: false, message: auth[:error]}
  end

  {healthy: true, message: "Codex CLI available and authenticated"}
end

#name ⇒ Object 



391
392
393
 
# File 'lib/agent_harness/providers/codex.rb', line 391

def name
  "codex"
end

#notify_hook_content ⇒ Object 



605
606
607
608
609
610
611
 
# File 'lib/agent_harness/providers/codex.rb', line 605

def notify_hook_content
  <<~TOML

    [notify]
    # Paid notification hook
  TOML
end

#send_message(prompt:, **options) ⇒ Object 



427
428
429
430
431
 
# File 'lib/agent_harness/providers/codex.rb', line 427

def send_message(prompt:, **options)
  super
ensure
  cleanup_mcp_tempfiles!
end

#session_flags(session_id) ⇒ Object 



483
484
485
486
 
# File 'lib/agent_harness/providers/codex.rb', line 483

def session_flags(session_id)
  return [] unless session_id && !session_id.empty?
  ["--session", session_id]
end

#subscription_unset_vars ⇒ Object 



423
 
# File 'lib/agent_harness/providers/codex.rb', line 423

def subscription_unset_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL"] + api_key_unset_vars

#supported_mcp_transports ⇒ Object 



437
438
439
 
# File 'lib/agent_harness/providers/codex.rb', line 437

def supported_mcp_transports
  %w[stdio http sse]
end

#supports_mcp? ⇒ Boolean

Returns:

  • (Boolean) 


433
434
435
 
# File 'lib/agent_harness/providers/codex.rb', line 433

def supports_mcp?
  true
end

#supports_sessions? ⇒ Boolean

Returns:

  • (Boolean) 


479
480
481
 
# File 'lib/agent_harness/providers/codex.rb', line 479

def supports_sessions?
  true
end

#test_command_overrides ⇒ Object 



448
449
450
 
# File 'lib/agent_harness/providers/codex.rb', line 448

def test_command_overrides
  ["--skip-git-repo-check", "--output-last-message"]
end

#token_usage_from_api_response(body) ⇒ Object 



456
457
458
459
460
461
462
463
464
 
# File 'lib/agent_harness/providers/codex.rb', line 456

def token_usage_from_api_response(body)
  usage = body&.dig("usage")
  return {} unless usage

  {
    input_tokens: usage["prompt_tokens"].to_i,
    output_tokens: usage["completion_tokens"].to_i
  }
end

#translate_error(message) ⇒ Object 



531
532
533
534
535
536
537
 
# File 'lib/agent_harness/providers/codex.rb', line 531

def translate_error(message)
  case message
  when /refresh_token_reused/i then "Codex authentication expired. Please re-authenticate."
  when /free tier limit/i then "Codex free tier limit reached."
  else message
  end
end

#validate_config ⇒ Object 



579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
 
# File 'lib/agent_harness/providers/codex.rb', line 579

def validate_config
  errors = []

  flags = @config.default_flags
  unless flags.nil?
    if flags.is_a?(Array)
      invalid = flags.reject { |f| f.is_a?(String) }
      errors << "default_flags contains non-string values" if invalid.any?
    else
      errors << "default_flags must be an array of strings"
    end
  end

  {valid: errors.empty?, errors: errors}
end