Class: AgentHarness::Providers::Codex

Inherits:
Base
  • Object
show all
Includes:
CodexModelDiscovery, 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: ModelDiscovery, StreamingEvent

Constant Summary collapse

SUPPORTED_CLI_VERSION = 
"0.149.1"
SUPPORTED_CLI_REQUIREMENT = 
Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 0.150.0").freeze
MODEL_REJECTION_CACHE_TTL = 
300
MODEL_REJECTION_CACHE_LIMIT = 
128
MODEL_REJECTION_CACHE = 
{}
MODEL_REJECTION_PATTERNS = 
[
  /The ['"](?<model>[^'"]+)['"] model is not supported when using Codex with a ChatGPT account/i,
  /model ['"](?<model>[^'"]+)['"] is not supported.*ChatGPT account/i
].freeze
DEFAULT_COMPATIBLE_MODEL_ID =

Default model recommended by the Codex runner contract when callers have no explicit preference. Used as the ModelCompatibility::Result#fallback_model_id for unsupported/unknown model lookups so downstream orchestrators (smoke tests, tier fallback) have a stable, contract-backed choice instead of relying on whichever model the CLI's default points at.

"gpt-5.2-codex"
MODEL_COMPATIBILITY_FACTS =

Known CLI-gated model facts. Each entry may express a minimum Codex CLI version required to drive the model, and/or auth-mode restrictions that are part of the durable runner contract. Keep entries here only when the requirement is durable runner contract knowledge — not provider-side experiments or one-off CLI defaults.

The gpt-5.5 entry tracks the failure class observed in viamin/agent-harness#245 and viamin/agent-harness#250: older Codex CLI builds (e.g. 0.115.x) could not drive the gpt-5.5 family.

{
  "gpt-5.5" => {minimum_cli_version: "0.116.0"},
  "gpt-5.5-codex" => {minimum_cli_version: "0.116.0"},
  "gpt-5.5-pro" => {auth_modes: [:api_key].freeze},
  "gpt-5.6" => {auth_modes: [:api_key].freeze},
  "gpt-5.6-luna" => {auth_modes: %i[api_key subscription].freeze},
  "gpt-5.6-sol" => {auth_modes: %i[api_key subscription].freeze},
  "gpt-5.6-terra" => {auth_modes: %i[api_key subscription].freeze},
  "gpt-5.3-codex" => {auth_modes: [:api_key].freeze}
}.each_value(&:freeze).freeze
BASELINE_SUPPORTED_MODELS =

Models that the runner contract considers supported on every Codex CLI release we ship. Used by model_compatibility so callers can distinguish "unknown to the contract" from "explicitly supported."

%w[
  gpt-5
  gpt-5.2-codex
  gpt-5-codex
  gpt-5-mini
  gpt-4o
  gpt-4o-mini
  o4-mini
].freeze
SUPPORTED_AUTH_MODES =

Auth modes the Codex runner accepts. Compatibility checks for an unrecognised auth mode return :auth_mode_not_supported rather than silently approving the request.

%i[api_key subscription].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
MODEL_LIST_REQUESTS = 
[
  {
    method: "initialize",
    id: 1,
    params: {
      clientInfo: {
        name: "agent_harness",
        title: "Agent Harness",
        version: "0.1.0"
      }
    }
  },
  {
    method: "initialized",
    params: {}
  },
  {
    method: "model/list",
    id: 2,
    params: {
      limit: 100,
      includeHidden: false
    }
  }
].freeze

Constants included from CodexModelDiscovery

AgentHarness::Providers::CodexModelDiscovery::SCRIPT

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 CodexModelDiscovery

#discover_available_models

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_test_error, #plan_execution, #sandboxed_environment?, #send_chat_message, #update_quota_from_headers

Methods included from Adapter

#auth_type, #chat_transport, #chat_transport_type, #fetch_mcp_servers, #heartbeat_integration, included, metadata_package_name, #noisy_error_patterns, normalize_metadata_installation, normalize_metadata_runtime_requirements, normalize_metadata_source_type, normalize_metadata_version_requirement, #parse_rate_limit_reset, #plan_execution, #smoke_test, #smoke_test_contract, #supports_activity_heartbeat?, #supports_chat?, #supports_dangerous_mode?, #supports_message_tool_injection?, #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) 


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

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

.binary_name ⇒ Object 



204
205
206
 
# File 'lib/agent_harness/providers/codex.rb', line 204

def binary_name
  "codex"
end

.classify_model_rejection(output, configured_model: nil) ⇒ Object 



547
548
549
 
# File 'lib/agent_harness/providers/codex.rb', line 547

def classify_model_rejection(output, configured_model: nil)
  parser_instance.send(:classify_model_rejection, output, configured_model: configured_model)
end

.classify_model_rejection_from_result(stdout:, stderr:, configured_model: nil) ⇒ Object

Successful assistant/tool output can quote the exact rejection text. Only CLI stderr and explicit JSONL error envelopes are evidence.



553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
 
# File 'lib/agent_harness/providers/codex.rb', line 553

def classify_model_rejection_from_result(stdout:, stderr:, configured_model: nil)
  texts = stdout.to_s.each_line.filter_map do |line|
    event = parse_stdout_jsonl_event(line.strip)
    next unless event.is_a?(Hash)

    event = unwrap_classification_event(event)
    extract_jsonl_error_text(event) if event.is_a?(Hash)
  end
  texts << stderr.to_s
  texts.each do |text|
    rejection = classify_model_rejection(text, configured_model: configured_model)
    return rejection if rejection
  end
  nil
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)



225
226
227
228
229
230
231
232
233
234
 
# File 'lib/agent_harness/providers/codex.rb', line 225

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

.comparable_cli_version(value) ⇒ Object

Coerce normalized CLI version into a Gem::Version usable for requirement comparison. Returns nil when the value is missing or cannot be parsed — callers treat that as "no installed-version signal," not as a failure.



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

def comparable_cli_version(value)
  return value if value.is_a?(Gem::Version)
  return nil if value.nil?

  str = value.respond_to?(:strip) ? value.strip : value.to_s
  return nil if str.empty?

  begin
    Gem::Version.new(str)
  rescue ArgumentError
    nil
  end
end

.default_compatible_model_id ⇒ Object 



331
332
333
 
# File 'lib/agent_harness/providers/codex.rb', line 331

def default_compatible_model_id
  DEFAULT_COMPATIBLE_MODEL_ID
end

.discover_models ⇒ Object 



270
271
272
273
274
275
276
 
# File 'lib/agent_harness/providers/codex.rb', line 270

def discover_models
  return [] unless available?

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

.firewall_requirements ⇒ Object 



250
251
252
253
254
255
256
257
258
 
# File 'lib/agent_harness/providers/codex.rb', line 250

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

.installation_contract(version: SUPPORTED_CLI_VERSION) ⇒ Object 



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/agent_harness/providers/codex.rb', line 278

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 



260
261
262
263
264
265
266
267
268
 
# File 'lib/agent_harness/providers/codex.rb', line 260

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

.model_compatibility(model_id:, auth_mode: nil, cli_version: nil) ⇒ AgentHarness::ModelCompatibility::Result

Structured Codex compatibility contract.

Returns an ModelCompatibility::Result for the combination of model_id, auth_mode, and installed cli_version. The contract surfaces these concrete outcomes:

  1. Supported — the model is in BASELINE_SUPPORTED_MODELS, or a known CLI-gated model whose stated restrictions are met (a minimum Codex CLI version and/or an auth-mode restriction; some gated models express only one of these).
  2. Unsupported due to auth mode — the requested auth mode is not accepted by the runner at all, or is not available for the specific model (e.g. an api-key-only model requested with subscription auth).
  3. Unsupported due to CLI version — the model is known to need a newer Codex CLI than was supplied; the result carries :minimum_cli_version so callers can act on it.
  4. Unknown / dynamic — the model is not in this static contract, or a gated model was queried without the gating input needed to answer definitively (an auth mode for an auth-restricted model, or an installed CLI version for a version-gated model). Callers must treat this as "ask the provider" rather than as approval.

Parameters:

  • model_id (String, Symbol)
  • auth_mode (Symbol, nil) (defaults to: nil) —

    :api_key or :subscription

  • cli_version (String, Gem::Version, nil) (defaults to: nil)

Returns:



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/agent_harness/providers/codex.rb', line 363

def model_compatibility(model_id:, auth_mode: nil, cli_version: nil)
  normalized_model_id = model_id.to_s
  normalized_auth_mode = auth_mode&.to_sym
  normalized_cli_version = normalize_cli_version_for_compatibility(cli_version)

  if normalized_auth_mode && !SUPPORTED_AUTH_MODES.include?(normalized_auth_mode)
    return AgentHarness::ModelCompatibility.build_result(
      runner: provider_name,
      model_id: normalized_model_id,
      auth_mode: normalized_auth_mode,
      cli_version: normalized_cli_version,
      supported: false,
      reason: AgentHarness::ModelCompatibility::UNSUPPORTED_AUTH_MODE_REASON,
      fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID,
      source: :static_contract,
      details: {supported_auth_modes: SUPPORTED_AUTH_MODES}
    )
  end

  gated_fact = MODEL_COMPATIBILITY_FACTS[normalized_model_id]
  if gated_fact
    supported_auth_modes = gated_fact[:auth_modes]
    if normalized_auth_mode && supported_auth_modes && !supported_auth_modes.include?(normalized_auth_mode)
      return AgentHarness::ModelCompatibility.build_result(
        runner: provider_name,
        model_id: normalized_model_id,
        auth_mode: normalized_auth_mode,
        cli_version: normalized_cli_version,
        supported: false,
        reason: AgentHarness::ModelCompatibility::UNSUPPORTED_AUTH_MODE_FOR_MODEL_REASON,
        fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID,
        source: :static_contract,
        details: {supported_auth_modes: supported_auth_modes}
      )
    end

    # An auth-gated model queried without an auth mode must stay
    # explicit. Returning :supported here would re-introduce the
    # exact permissive false-positive this contract is designed to
    # prevent — `auth_mode` defaults to nil on the public API, so a
    # caller that queries availability without an auth mode and
    # treats `supported? == true` as approval could then schedule an
    # api-key-only model (e.g. gpt-5.5-pro) under subscription. This
    # mirrors the sibling CLI-version dimension below: when the
    # gating input is missing, surface :unknown with the allowed
    # auth modes attached so callers can decide deliberately.
    if supported_auth_modes && normalized_auth_mode.nil?
      return AgentHarness::ModelCompatibility.unknown_result(
        runner: provider_name,
        model_id: normalized_model_id,
        auth_mode: normalized_auth_mode,
        cli_version: normalized_cli_version,
        reason: AgentHarness::ModelCompatibility::UNKNOWN_AUTH_MODE_REASON,
        fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID,
        source: :static_contract,
        details: {supported_auth_modes: supported_auth_modes}
      )
    end

    minimum_version = gated_fact[:minimum_cli_version]
    if minimum_version
      requirement = Gem::Requirement.new(">= #{minimum_version}")
      comparable_version = comparable_cli_version(normalized_cli_version)

      # A CLI-gated model without a comparable installed version must
      # stay explicit. Returning :supported here would re-introduce the
      # exact `gpt-5.5` failure class this contract is designed to
      # prevent — a caller that cannot supply a version would get
      # `supported? == true` and may still schedule a run onto an old
      # CLI (e.g. 0.115.x). Surface :unknown with the requirement
      # attached so callers can decide deliberately.
      if comparable_version.nil?
        return AgentHarness::ModelCompatibility.unknown_result(
          runner: provider_name,
          model_id: normalized_model_id,
          auth_mode: normalized_auth_mode,
          cli_version: normalized_cli_version,
          reason: AgentHarness::ModelCompatibility::UNKNOWN_CLI_VERSION_REASON,
          minimum_cli_version: minimum_version,
          cli_version_requirement: requirement.to_s,
          fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID,
          source: :static_contract
        )
      end

      unless requirement.satisfied_by?(comparable_version)
        return AgentHarness::ModelCompatibility.build_result(
          runner: provider_name,
          model_id: normalized_model_id,
          auth_mode: normalized_auth_mode,
          cli_version: normalized_cli_version,
          supported: false,
          reason: AgentHarness::ModelCompatibility::UNSUPPORTED_CLI_VERSION_REASON,
          minimum_cli_version: minimum_version,
          cli_version_requirement: requirement.to_s,
          fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID,
          source: :static_contract
        )
      end

      return AgentHarness::ModelCompatibility.build_result(
        runner: provider_name,
        model_id: normalized_model_id,
        auth_mode: normalized_auth_mode,
        cli_version: normalized_cli_version,
        supported: true,
        reason: AgentHarness::ModelCompatibility::SUPPORTED_REASON,
        minimum_cli_version: minimum_version,
        cli_version_requirement: requirement.to_s,
        source: :static_contract
      )
    end

    return AgentHarness::ModelCompatibility.build_result(
      runner: provider_name,
      model_id: normalized_model_id,
      auth_mode: normalized_auth_mode,
      cli_version: normalized_cli_version,
      supported: true,
      reason: AgentHarness::ModelCompatibility::SUPPORTED_REASON,
      source: :static_contract
    )
  end

  if BASELINE_SUPPORTED_MODELS.include?(normalized_model_id)
    return AgentHarness::ModelCompatibility.build_result(
      runner: provider_name,
      model_id: normalized_model_id,
      auth_mode: normalized_auth_mode,
      cli_version: normalized_cli_version,
      supported: true,
      reason: AgentHarness::ModelCompatibility::SUPPORTED_REASON,
      source: :static_contract
    )
  end

  AgentHarness::ModelCompatibility.unknown_result(
    runner: provider_name,
    model_id: normalized_model_id,
    auth_mode: normalized_auth_mode,
    cli_version: normalized_cli_version,
    reason: AgentHarness::ModelCompatibility::UNKNOWN_MODEL_REASON,
    fallback_model_id: DEFAULT_COMPATIBLE_MODEL_ID
  )
end

.parse_cli_jsonl_transcript(raw_output, max_events: nil) ⇒ Object 



527
528
529
530
531
532
533
 
# File 'lib/agent_harness/providers/codex.rb', line 527

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.



538
539
540
541
542
543
544
545
 
# File 'lib/agent_harness/providers/codex.rb', line 538

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 



241
242
243
244
245
246
247
248
 
# File 'lib/agent_harness/providers/codex.rb', line 241

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

.provider_name ⇒ Object 



200
201
202
 
# File 'lib/agent_harness/providers/codex.rb', line 200

def provider_name
  :codex
end

.smoke_test_contract ⇒ Object 



327
328
329
 
# File 'lib/agent_harness/providers/codex.rb', line 327

def smoke_test_contract
  Base::DEFAULT_SMOKE_TEST_CONTRACT
end

Instance Method Details

#api_key_env_var_names ⇒ Object 



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

def api_key_env_var_names = ["OPENAI_API_KEY"]

#api_key_unset_vars ⇒ Object 



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

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

#auth_lock_config ⇒ Object 



974
975
976
 
# File 'lib/agent_harness/providers/codex.rb', line 974

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

#auth_status ⇒ Object 



897
898
899
 
# File 'lib/agent_harness/providers/codex.rb', line 897

def auth_status
  auth_status_for_env({})
end

#build_mcp_flags(mcp_servers, working_dir: nil) ⇒ Object 



798
799
800
801
802
803
 
# File 'lib/agent_harness/providers/codex.rb', line 798

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 



723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/agent_harness/providers/codex.rb', line 723

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

#check_quota(env:, timeout: QuotaCheckers::OpenRouter::DEFAULT_TIMEOUT) ⇒ AgentHarness::QuotaStatus

Proactively check quota for Codex's configured backend.

Codex runners frequently route through OpenRouter by setting OPENAI_BASE_URL=https://openrouter.ai/api/v1. When the request env indicates OpenRouter, the check is delegated to QuotaCheckers::OpenRouter, which queries the /credits endpoint. Otherwise OpenAI's quota API is not publicly exposed, so the check returns unavailable and callers fall back to TokenUsageTracker.

Parameters:

  • env (Hash{String=>String}) —

    request-scoped environment

  • timeout (Numeric) (defaults to: QuotaCheckers::OpenRouter::DEFAULT_TIMEOUT) —

    time budget in seconds

Returns:



755
756
757
758
759
760
761
 
# File 'lib/agent_harness/providers/codex.rb', line 755

def check_quota(env:, timeout: QuotaCheckers::OpenRouter::DEFAULT_TIMEOUT)
  if QuotaCheckers::OpenRouter.routes_through_open_router?(env)
    return QuotaCheckers::OpenRouter.check(env: env, timeout: timeout, logger: @logger)
  end

  QuotaStatus.unavailable
end

#cli_env_overrides ⇒ Object 



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

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

#config_file_content(options = {}) ⇒ Object 



956
957
958
959
960
961
962
963
964
 
# File 'lib/agent_harness/providers/codex.rb', line 956

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 



715
716
717
718
719
720
721
 
# File 'lib/agent_harness/providers/codex.rb', line 715

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

#dangerous_mode_flags ⇒ Object 



809
810
811
 
# File 'lib/agent_harness/providers/codex.rb', line 809

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

#display_name ⇒ Object 



711
712
713
 
# File 'lib/agent_harness/providers/codex.rb', line 711

def display_name
  "OpenAI Codex CLI"
end

#error_classification_patterns ⇒ Object 



869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
 
# File 'lib/agent_harness/providers/codex.rb', line 869

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 



845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
 
# File 'lib/agent_harness/providers/codex.rb', line 845

def error_patterns
  {
    subscription_model_rejected: MODEL_REJECTION_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 



823
824
825
826
827
828
829
830
831
832
833
834
 
# File 'lib/agent_harness/providers/codex.rb', line 823

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 



901
902
903
904
905
906
907
908
909
910
911
912
 
# File 'lib/agent_harness/providers/codex.rb', line 901

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 



707
708
709
 
# File 'lib/agent_harness/providers/codex.rb', line 707

def name
  "codex"
end

#notify_hook_content ⇒ Object 



966
967
968
969
970
971
972
 
# File 'lib/agent_harness/providers/codex.rb', line 966

def notify_hook_content
  <<~TOML

    [notify]
    # Paid notification hook
  TOML
end

#preflight_check(env:, timeout: 10) ⇒ Object 



914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
 
# File 'lib/agent_harness/providers/codex.rb', line 914

def preflight_check(env:, timeout: 10)
  auth = auth_status_for_env(env)
  return {healthy: false, reason: auth[:error], error_category: :authentication} unless auth[:valid]

  version = codex_cli_version(env: env, timeout: timeout)
  unless version
    return {
      healthy: false,
      reason: "Codex CLI version check failed. Ensure 'codex' is installed and available in PATH.",
      error_category: :installation
    }
  end

  unless SUPPORTED_CLI_REQUIREMENT.satisfied_by?(version)
    return {
      healthy: false,
      reason: "Unsupported Codex CLI version #{version}. Expected #{SUPPORTED_CLI_REQUIREMENT}.",
      error_category: :installation
    }
  end

  check_base_url_reachability(env: env, timeout: timeout)
rescue => e
  {healthy: false, reason: "Codex preflight failed: #{e.message}"}
end

#resolve_model_rejection_recovery(failure:, provider_runtime:, env:, timeout:) ⇒ Object 



763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
 
# File 'lib/agent_harness/providers/codex.rb', line 763

def resolve_model_rejection_recovery(failure:, provider_runtime:, env:, timeout:)
  rejection = model_rejection_from_failure(failure, provider_runtime)
  return unless rejection

  record_model_rejection(rejection, env: env)
  allowed_model_ids = recovery_allowed_model_ids(provider_runtime)
  discovery = discover_compatible_model(
    rejected_model_id: rejection[:model],
    allowed_model_ids: allowed_model_ids,
    env: env,
    timeout: timeout,
    refresh: true
  )
  {
    rejection: rejection,
    discovery: discovery.to_h,
    provider_runtime: replacement_runtime(provider_runtime, discovery, rejection),
    message: model_rejection_recovery_message(rejection, discovery)
  }
end

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



784
785
786
787
788
 
# File 'lib/agent_harness/providers/codex.rb', line 784

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

#session_flags(session_id) ⇒ Object 



840
841
842
843
 
# File 'lib/agent_harness/providers/codex.rb', line 840

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

#subscription_unset_vars ⇒ Object 



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

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

#supported_mcp_transports ⇒ Object 



794
795
796
 
# File 'lib/agent_harness/providers/codex.rb', line 794

def supported_mcp_transports
  %w[stdio http sse]
end

#supports_mcp? ⇒ Boolean

Returns:

  • (Boolean) 


790
791
792
 
# File 'lib/agent_harness/providers/codex.rb', line 790

def supports_mcp?
  true
end

#supports_sessions? ⇒ Boolean

Returns:

  • (Boolean) 


836
837
838
 
# File 'lib/agent_harness/providers/codex.rb', line 836

def supports_sessions?
  true
end

#test_command_overrides ⇒ Object 



805
806
807
 
# File 'lib/agent_harness/providers/codex.rb', line 805

def test_command_overrides
  ["--skip-git-repo-check", "--output-last-message", "/tmp/codex-smoke-output.txt"]
end

#token_usage_from_api_response(body) ⇒ Object 



813
814
815
816
817
818
819
820
821
 
# File 'lib/agent_harness/providers/codex.rb', line 813

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 



889
890
891
892
893
894
895
 
# File 'lib/agent_harness/providers/codex.rb', line 889

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 



940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
 
# File 'lib/agent_harness/providers/codex.rb', line 940

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