Codex-Authenticated Models¶

Codex Responses provides model access inside a framework adapter. This is different from Codex App Server, which runs an agent harness. Choosing a model route does not switch the surrounding agent framework.

Codex Responses Connections¶

The factory signature is codex_responses_model(model_id, adapter, *, connection="http", fallback="error", transport_observer=None). adapter must be "pydantic" or "langchain". The identifier may include the codex/ prefix. fallback="http" is valid only with WebSocket. transport_observer receives content-free transport events. The helper reads existing Codex login credentials; KEDI_CODEX_AUTH_FILE selects an explicit auth file. Do not include that file in source, logs, or published examples.

codex_responses_model() builds a Codex-authenticated Pydantic model. HTTP is the default. Install kedi[codex-model] on Python 3.11 or newer for the pinned codex-auth-helper[websocket]==1.8.0. Select WebSocket explicitly; it is not enabled just by installing the extra.

from kedi import codex_responses_model
from kedi.agent_adapter import PydanticAdapter

model = codex_responses_model(
    "gpt-5.6-luna",
    adapter="pydantic",
    connection="websocket",
    fallback="error",
)
adapter = PydanticAdapter(model)

async def review():
    async with adapter.responses_session():
        first = await adapter.run("The current release is amber. Acknowledge it.")
        second = await adapter.run(
            "Which release is current?",
            message_history=first.all_messages(),
        )
    return second.output

An ordinary adapter run keeps its connection across model/tool turns. The explicit session above also retains it across sequential adapter calls. It owns the connection, not the history: supply native message history as shown or use Kedi's normal stateful-history surface. Concurrent child tasks remain isolated, and exit, errors, and cancellation clean up the connection.

Updated helper builds scope a separate routing turn to every adapter run. HTTP and WebSocket echo the first server-provided x-codex-turn-state within its tool loop, but discard it before the next run, even on a shared connection. Kedi does not put this opaque value in history or transport metrics. Prompt-cache keys and native history remain unchanged; provider cache hits are not guaranteed.

Auth recovery reloads same-account credentials after an explicit 401, then allows one refresh if necessary. Account changes require a new client; permanent auth failures and exhausted 401s do not trigger HTTP fallback. Same-file refresh locking is in-process only. Older helper builds work without the new turn-state feature.

Append-only requests can transmit only their new suffix. History edits or changed request settings reset continuation. If the socket is already known to be closed before the next request, a new connection receives full history. Changing handshake headers also replaces the connection.

With helper 1.8.0, non-streaming model requests recover transient WebSocket send/receive failures by discarding incomplete output and rebuilding full history on a new connection. Completed local tools are not rerun by recovery. The client max_retries controls reconnects (default two), with bounded backoff. fallback="http" permits HTTP after retries are exhausted, as well as initial-handshake fallback. The model can still choose another tool call, and lost provider work may incur unreported cost.

Raw client calls and exposed streams are not replayed; cancellation, permanent auth/permission failures and provider-hosted tools also prevent response replay. Install the pinned helper with uv add 'kedi[codex-model]'. Stream consumers can stop on response.completed without discarding the completed response; stopping before completion abandons it. The closing handshake has a 250 ms timeout, separate from generation and tool execution.

Connection reuse can improve provider cache reads, but does not guarantee a particular hit rate or lower latency. Cached input is part of total input, not an additional token count.