Universal.OpenAI.CodexSdk 1.0.2

Universal.OpenAI.CodexSdk

A .NET client for embedding OpenAI Codex through the supported codex app-server protocol. The SDK provisions a pinned official native Codex runtime by default, or connects to a caller-provided executable or transport. Codex itself remains responsible for ChatGPT and API-key authentication, credential refresh, model access, and policy enforcement.

Isolated runtime

The default CodexExecutableSource.Download behavior downloads the official platform-specific @openai/codex package, verifies its npm SHA-512 integrity value, extracts the complete native runtime, and caches it under the SDK's local application-data directory. The runtime version is pinned by CodexRuntimeDownloader.DefaultVersion; latest is deliberately rejected so a test or deployment cannot silently change versions.

The default CodexHome is also private to this SDK. It does not reuse the user's normal Codex configuration or credentials, and ambient OpenAI authentication environment variables are not inherited unless InheritOpenAIAuthenticationEnvironment is explicitly enabled.

Set UseAmbientCodexHome only when intentionally delegating configuration and authentication to the process owner's normal Codex home. CODEX_HOME cannot be supplied through EnvironmentVariables; use CodexHome so isolation cannot be bypassed accidentally.

Typed protocol information

Stable information surfaces are exposed as .NET models: ReadAccountAsync, ReadAccountUsageAsync, ReadAccountRateLimitsAsync, and ListModelsAsync. Core turn and item lifecycle notifications, text/plan/reasoning/command deltas, warnings, errors, diffs, plans, and token usage have typed accessors. Final item state is represented by the polymorphic CodexThreadItem hierarchy with CodexUnknownThreadItem as its forward-compatible fallback. Schema-defined unions such as user inputs, command actions, permission paths, web-search actions, error information, and request identifiers are also discriminated .NET models.

Typed protocol models inherit CodexExtensibleModel. Fields introduced by a newer runtime are retained in AdditionalProperties through Newtonsoft.Json extension-data handling. Unknown discriminator variants retain their payload without forcing known models back to raw JSON.

Server-initiated dynamic-tool, approval, user-input, permission, and MCP elicitation requests expose typed parameter models through CodexServerRequest.Parameters. Register ServerRequestHandler to return a typed CodexServerResponse. CodexRawServerResponse, SendRequestAsync, and retained raw protocol data remain available for experimental or newly added fields.

Each ReadNotificationsAsync call creates an independent live subscription. Per-turn ReadEventsAsync remains separately buffered, so telemetry and UI observers do not steal events from one another.

Disposing an active CodexTurn releases its event subscription and requests turn/interrupt, bounded by TurnDisposeTimeout. Read the event stream through turn/completed, or dispose explicitly when abandoning a turn. Only one active turn per thread is supported by a client instance.

Dynamic tool input schemas and structured turn output schemas use Universal.Common.Json.JsonSchema. Dynamic tools and externally managed ChatGPT tokens require ExperimentalApi = true. Stable and experimental protocol escape hatches are named explicitly with Raw; prefer typed models where they are available.

Prompt behavior

CodexThreadStartOptions.PromptMode makes the base prompt policy explicit:

• RuntimeDefault (the default) omits baseInstructions, selecting the default instructions shipped with the installed Codex runtime.
• None sends an empty baseInstructions value.
• Custom sends BaseInstructions supplied by the caller.

DeveloperInstructions is separate and additive in every mode. The package deliberately does not copy a static Codex system prompt, because the official runtime prompt can evolve independently of the SDK.

Basic use

await using var client = await CodexAppServerClient.StartAsync(new CodexAppServerOptions
{
    // Optional: override RuntimeVersion, DownloadCacheDirectory, or CodexHome here.
});

var login = await client.StartChatGptLoginAsync();
// Open login.AuthUrl in the user's browser and wait for account/login/completed.

var thread = await client.StartThreadAsync(new CodexThreadStartOptions
{
    PromptMode = CodexPromptMode.RuntimeDefault,
    DeveloperInstructions = "Keep changes focused and run relevant tests.",
    Ephemeral = true
});

var turnOptions = new CodexTurnStartOptions();
turnOptions.Input.Add(new CodexTextInput("Inspect this repository."));
await using var turn = await client.StartTurnAsync(thread.Id, turnOptions);

await foreach (var notification in turn.ReadEventsAsync())
{
    if (notification.TryGetAgentMessageDelta(out var delta))
        Console.Write(delta.Delta);
    if (notification.TryGetItemCompleted(out var completed) &&
        completed.Item is CodexCommandExecutionItem command)
        Console.WriteLine($"Command exited with {command.ExitCode}");
}

The Codex executable is intentionally not redistributed inside this NuGet package. Set ExecutablePath to use a caller-managed binary, select CodexExecutableSource.SystemPath explicitly, or provide an ICodexAppServerTransport implementation when automatic isolated provisioning is not desired.