Jido.Codex

Jido.Codex is the OpenAI Codex CLI adapter for Jido.Harness.

It provides:

• Jido.Harness.Adapter implementation (Jido.Codex.Adapter)
• normalized streaming event mapping (Jido.Codex.Mapper)
• exec transport (default) and app-server transport (opt-in)
• session cancellation by session_id
• compatibility/install/smoke mix tasks

Installation

defp deps do
  [
    {:jido_harness, github: "agentjido/jido_harness", branch: "main", override: true},
    {:jido_codex, github: "agentjido/jido_codex", branch: "main"}
  ]
end

This repo is currently aligned as part of the GitHub-based harness package set rather than a Hex release line.

Then:

mix deps.get

Requirements

• Elixir ~> 1.18
• Codex CLI installed and authenticated

Quick Start

1) Validate local Codex setup

mix codex.install
mix codex.compat
mix codex.compat --transport app_server

2) Run a prompt

{:ok, events} = Jido.Codex.run("Summarize this repository")

events
|> Enum.each(&IO.inspect/1)

3) Cancel an active session

:ok = Jido.Codex.cancel("session-id-from-stream")

Public API

• Jido.Codex.run/2 - build a Jido.Harness.RunRequest from prompt + opts, then run
• Jido.Codex.run_request/2 - run a pre-built %Jido.Harness.RunRequest{}
• Jido.Codex.cancel/1 - cancel active run by session id
• Jido.Codex.cli_installed?/0
• Jido.Codex.compatible?/1
• Jido.Codex.assert_compatible!/1
• Jido.Codex.version/0

Metadata Contract

Jido.Codex.Adapter reads provider-specific runtime controls from:

request.metadata["codex"]

Supported keys:

• "transport": "exec" | "app_server" (default "exec")
• "thread_id": string
• "resume_last": boolean
• "codex_opts": map (passed to Codex.Options.new/1)
• "thread_opts": map (passed to Codex.start_thread/2 or Codex.resume_thread/3)
• "turn_opts": map (passed to Codex.Thread.run_streamed/3)
• "app_server": map (init_timeout_ms, client_name, client_title, client_version)
• "cancel_mode": "immediate" | "after_turn" (default "immediate")

Precedence:

• runtime adapter opts
• metadata (metadata["codex"])
• defaults derived from RunRequest

Default mapping from RunRequest:

• prompt -> streamed turn input
• cwd -> thread_opts.working_directory
• model -> codex_opts.model and thread_opts.model
• max_turns -> turn_opts.max_turns
• timeout_ms -> turn_opts.timeout_ms
• system_prompt -> thread_opts.developer_instructions
• attachments -> thread_opts.attachments

Event Mapping

Codex stream events are normalized to Jido.Harness.Event with:

• provider: :codex
• ISO-8601 timestamp
• raw event passthrough in raw

Canonical event types include:

• :session_started
• :output_text_delta
• :output_text_final
• :thinking_delta
• :tool_call
• :tool_result
• :file_change
• :usage
• :session_completed
• :session_failed
• :session_cancelled

Extended Codex-specific types use :codex_* naming (:codex_turn_started, :codex_turn_plan_updated, etc.).

Mix Tasks

• mix codex.install - check Codex CLI discovery and print install help
• mix codex.compat [--transport exec|app_server] - run compatibility diagnostics
• mix codex.smoke "PROMPT" [--cwd ... --transport ... --timeout ...] - run minimal stream smoke test

Development

mix test
mix quality

Integration tests are opt-in and excluded by default (@tag :integration).

The primary live adapter checks are:

mix test --include integration test/jido/codex/integration/compatibility_integration_test.exs
mix test --include integration test/jido/codex/integration/run_integration_test.exs

These tests auto-load .env.

License

Apache-2.0. See LICENSE.

Package Purpose

jido_codex is the Codex CLI adapter for jido_harness, including Codex event mapping plus execution/session contract logic.

Testing Paths

• Unit/contract tests: mix test
• Full quality gate: mix quality
• Optional live checks: mix codex.install && mix codex.compat

Live Integration Test Knobs

• OPENAI_API_KEY if you want Codex to use API-key auth instead of existing CLI login state
• JIDO_CODEX_LIVE_PROMPT to override the default prompt
• JIDO_CODEX_LIVE_CWD to override the working directory
• JIDO_CODEX_LIVE_MODEL to force a specific model
• JIDO_CODEX_LIVE_TIMEOUT_MS to extend the per-run timeout
• JIDO_CODEX_REQUIRE_SUCCESS=1 to fail unless the terminal event is successful
• JIDO_CODEX_CLI_PATH to target a non-default Codex CLI binary