Incursa.OpenAI.Codex 2.2.0

Incursa.OpenAI.Codex

Async-only Codex runtime for .NET. It wraps the local codex executable and starts it as a subprocess, so the machine running your app must already have Codex installed and authenticated. Any ApiKey or BaseUrl settings are forwarded to that subprocess; they do not replace the local Codex installation requirement.

This package is DI-agnostic and exposes the runtime API:

• CodexClient
• CodexThread
• CodexTurn
• typed options, event, item, result, and exception models such as CodexClientOptions, CodexPlanModeOptions, CodexThreadOptions, CodexTurnOptions, CodexInputItem, CodexThreadEvent, CodexThreadItem, CodexRunResult, CodexThreadSnapshot, CodexAccountRateLimitsResult, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException

When To Use This Package

Use this package when you want a .NET wrapper around the local Codex CLI for prompt/response flows, stateful threads, or turn-level control.

• Use the OpenAI SDK when you want direct API access from .NET.
• Use ChatKit when you want a hosted chat UI surface.
• Use the Agents SDK when you want higher-level agent orchestration.
• Use this package when you specifically want Codex-backed workflows driven from a local Codex install.
• If you want a no-throw preflight for the local executable, call await client.IsCodexAvailableAsync() before InitializeAsync() or any turn operation.

Hello World

The smallest useful call starts a thread, sends one prompt, and prints the final response:

using Incursa.OpenAI.Codex;

await using var client = new CodexClient();

CodexThread thread = await client.StartThreadAsync(new CodexThreadOptions
{
    SkipGitRepoCheck = true,
});

CodexRunResult result = await thread.RunAsync("Say hello from Codex in one sentence.");
Console.WriteLine(result.FinalResponse);

CodexRunResult.FinalResponse can be null when a turn completes with commentary only and never produces a final-answer or phase-less assistant message.

CodexClient is async-only. Dispose it with await using.

If you need DI registration, use Incursa.OpenAI.Codex.Extensions and call AddCodex(...).

Backend Modes

The API supports both backend modes:

• AppServer (codex app-server --listen stdio://) for the full JSON-RPC surface, thread lifecycle operations, thread goals, model listing, account rate-limit reads, and turn steering or interruption
• Exec (codex exec --experimental-json) for the CLI-backed run and stream flow

Use AppServer when you need long-lived conversations, CodexThread management, or turn control. Use Exec when you only need prompt-in, response-out behavior.

Major API Surfaces

• CodexClient: the root entry point for runtime startup, thread management, model discovery, account rate-limit reads, and IsCodexAvailableAsync() for an executable preflight
• CodexThread: a stateful conversation handle with RunAsync, RunStreamedAsync, StartTurnAsync, ReadAsync, SetNameAsync, CompactAsync, GetGoalAsync, SetGoalAsync, SetGoalStatusAsync, ClearGoalAsync, RollbackAsync, UnsubscribeAsync, UpdateMetadataAsync, and ShellCommandAsync
• CodexTurn: a single-turn handle with StreamAsync, StreamNormalizedAsync, ObserveEventsAsync, ObserveNormalizedEventsAsync, RunAsync, RunToResultAsync, SteerAsync, and InterruptAsync
• CodexClientOptions: backend selection, executable path override, API key, configuration, plan-mode defaults, environment, and approval handler
• CodexThreadOptions, CodexThreadListOptions, and CodexTurnOptions: working directory, thread origin metadata, sandbox, approval, model, Fast mode service tier, output schema, sort, and list-filter settings
• CodexInputItem and the typed input union for text, remote image, local image, skill, and mention inputs
• CodexThreadEvent, CodexThreadItem, CodexRunResult, CodexTurnEvent, CodexTurnResult, CodexThreadGoal, CodexThreadSnapshot, CodexAccountRateLimitsResult, CodexTurnPlanUpdatedEvent, CodexAccountRateLimitsUpdatedEvent, CodexRuntimeCapabilities, CodexRuntimeMetadata, and CodexException for streamed data, results, and diagnostics. CodexRunResult.FinalResponse stays nullable for commentary-only turns.

Use CodexTurn.StreamNormalizedAsync(), CodexTurn.ObserveNormalizedEventsAsync(), or CodexTurn.RunToResultAsync() for UI clients that must distinguish Codex completion from transport or delivery behavior. ObserveEventsAsync() and ObserveNormalizedEventsAsync() expose turn-scoped observable streams that fan out from one underlying Codex reader and replay observed events to later subscribers. The detailed result exposes TerminalEventSeen, TerminalEventType, TerminalState, FinalResponseText, FinalResponseSource, and assistant output character counts so callers do not need to infer completion from silence.

Sample

The runnable sample under samples/Incursa.OpenAI.Codex.Sample shows quickstart, streaming, structured output, image input, error handling, and turn controls.

License

Apache 2.0. See the repository root LICENSE.