codex-auth-helper

# codex-auth-helper Skill Use this skill when the task is centered on the `codex-auth-helper` package. This package exists so the repo does not re-implement Codex auth and Responses wiring ad hoc in examples, adapters, or one-off scripts. It is intentionally narrow: - read existing Codex auth state - refresh tokens when needed - derive account-scoped request headers - build a Codex-specific async OpenAI client - build a `pydantic-ai` Responses model on top of that client - build a LangChain `ChatOpenAI` model on top of the same auth/session flow ## Start Here If you only need the shortest high-signal path: 1. read `Quick Routing` 2. open the [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py) for public constructor behavior 3. open the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) for refresh logic 4. open the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) for auth payload shape and persistence ## Quick Routing | If the task is about... | Use this skill? | Open first | | --- | --- | --- | | `~/.codex/auth.json` parsing | Yes | [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py) | | token refresh timing or refresh requests | Yes | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) | | Codex-specific request headers or account id | Yes | [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py), [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) | | building a `CodexResponsesModel` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py) | | building a LangChain `ChatOpenAI` | Yes | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | | exposing that model through ACP | Pair with `pydantic-acp` | [Pydantic adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/pydantic-acp) | | exposing a Codex-backed LangChain graph through ACP | Pair with `langchain-acp` | [LangChain adapter package](https://github.com/vcoderun/acpkit/tree/main/packages/adapters/langchain-acp) | | outbound Codex Responses WebSocket | Yes, Pydantic and async LangChain | [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [LangChain module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/langchain.py), [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py) | | exposing an ACP runtime over WebSocket | No, pair with `acpremote` | [remote transport package](https://github.com/vcoderun/acpkit/tree/main/packages/transports/acpremote) | ## Package Boundary This package is not: - an ACP adapter - a CLI package - an ACP transport package It is a helper for turning a local Codex login into a reusable `pydantic-ai` Responses model. That means it owns: - auth file parsing - token refresh timing - account-id extraction - Codex request header shaping - Responses-model construction - optional outbound Responses connection/session ownership ## Do Not Confuse With - `codex-auth-helper` vs `pydantic-acp` this package builds the model/client; `pydantic-acp` exposes the runtime through ACP - `codex-auth-helper` vs `acpkit-sdk` this package has no CLI target-loading role - `codex-auth-helper` vs `acpremote` this package can select the model's outbound Responses connection; it does not expose an ACP runtime over a remote transport It does not own: - ACP session lifecycle - approvals - ACP transport - CLI dispatch ## Primary References Package references: - [Raw skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/codex-auth-helper/SKILL.md) - [Raw helpers docs](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/helpers.md) - [Raw API docs page](https://raw.githubusercontent.com/vcoderun/acpkit/main/docs/api/codex_auth_helper.md) - [Rendered helper docs](https://vcoderun.github.io/acpkit/helpers/) - [Source tree](https://github.com/vcoderun/acpkit/tree/main/packages/helpers/codex-auth-helper) Cross-skill reference: - [Pydantic adapter skill](https://raw.githubusercontent.com/vcoderun/acpkit/main/.agents/skills/pydantic-acp/SKILL.md) ## Public Surface High-value public seams: - `create_codex_responses_model(...)` - `create_codex_async_openai(...)` - `create_codex_openai(...)` - `create_codex_chat_openai(...)` - `CodexAsyncOpenAI` - `CodexOpenAI` - `CodexResponsesModel` - `CodexResponsesConnection` - `CodexResponsesFallback` - `CodexResponsesSessionInfo` - `CodexResponsesConnectionError` - `CodexResponsesProtocolError` - `CodexResponsesTransportEvent` - `CodexResponsesTransportObserver` - `CodexAuthConfig` - `CodexAuthState` - `CodexAuthStore` - `CodexTokenManager` Package entrypoint: - [Package entrypoint](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/__init__.py) ## Module Guide | Subsystem | Key files | Use them for | | --- | --- | --- | | top-level constructors and model surface | [factory module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/factory.py), [model module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/model.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | building public client/model objects and default request behavior | | Responses WebSocket | [WebSocket module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/_responses_websocket.py), [Codex client module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/client.py) | outbound connection lifecycle, event mapping, and continuation safety | | auth state and persistence | [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py), [auth-store module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/store.py), [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py) | parsing auth payloads, persistence, path config | | token refresh | [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py) | deciding whether refresh is needed and performing refresh | ## What It Does It: - reads an existing Codex auth file - refreshes tokens when needed - derives `ChatGPT-Account-Id` - builds a Codex-specific Responses client - returns a `pydantic-ai` model configured for Codex usage - returns a LangChain `ChatOpenAI` configured for the Responses API - optionally keeps one outbound Responses WebSocket for a Pydantic logical run It does not: - perform `codex login` - create a login session from nothing - support unrelated OpenAI Chat Completions flows - adapt a runtime to ACP - expose an ACP runtime over WebSocket ## Common Integration Pattern The most important package combinations are: - `codex-auth-helper` + `pydantic-acp` - `codex-auth-helper` + `langchain-acp` Normal flow: 1. call `create_codex_responses_model(...)` 2. construct a `pydantic_ai.Agent` 3. expose that agent through `pydantic-acp` This helper is usually upstream of the adapter, not a replacement for it. ## Common Workflows ### Build a Codex-backed `pydantic-ai` model Use `create_codex_responses_model(...)` and pass explicit `instructions=...`. Use `Agent.run_stream(...)` when the caller needs incremental text; `CodexResponsesModel` forwards Responses API deltas as they arrive instead of buffering the completed response. ### Build a lower-level client first Use `create_codex_async_openai(...)` when you need the transport/client object explicitly. ### Keep one Responses connection for a Pydantic run Install the `websocket` extra, pass `connection="websocket"`, and wrap the whole async agent run in `model.responses_session()`. Keep strict fallback for measurements. Non-streaming responses recover transient failures with bounded reconnects; opt-in HTTP fallback follows exhaustion. Exposed streams are not replayed. ### Build a LangChain model Use `create_codex_chat_openai(...)` when the upstream runtime is LangChain or LangGraph and you want the Responses API path instead of hand-wiring `langchain-openai`. Pass explicit `instructions=...` here too. WebSocket factories leave stream selection automatic: ordinary `ainvoke` buffers the response for recovery and `astream` receives live chunks. Explicit streaming settings/callbacks can bypass response recovery. HTTP factories retain their `streaming=True` default. ### Debug refresh behavior Start from the [token manager](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/manager.py), then inspect the [auth-state module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/state.py) and the [auth-config module](https://github.com/vcoderun/acpkit/blob/main/packages/helpers/codex-auth-helper/src/codex_auth_helper/auth/config.py). ## Skill-Bundled Example Skill-local example: - [Codex-backed agent example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_responses_agent.py) - [Codex-backed LangChain graph example](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/codex_chat_openai_graph.py) - [Example notes](https://github.com/vcoderun/acpkit/blob/main/.agents/skills/codex-auth-helper/examples/README.md) This example demonstrates: - creating the Codex-backed model - constructing a Pydantic agent - exposing that agent through `pydantic-acp` - constructing a LangChain graph with `ChatOpenAI` ## Handoff Rules Pair or switch to: - `pydantic-acp` when the Codex-backed model is being exposed through ACP - `langchain-acp` when the Codex-backed LangChain graph is being exposed through ACP - `acpkit-sdk` only when that Pydantic agent is invoked through `acpkit run ...` or `acpkit serve ...` Stay in this skill when the main issue is: - auth parsing - refresh behavior - client header behavior - model construction ## Guardrails - Do not call this package an adapter. - Do not claim it supports generic Chat Completions if it does not. - Do not describe auth refresh logic that is not present in the package source. - If the task shifts into ACP adapter runtime behavior, move to `pydantic-acp`. ## Production Baseline - Require explicit `instructions=` for Codex-backed Pydantic AI and LangChain factories. - Never log access tokens, refresh tokens, account ids, or the contents of `auth.json`. - Keep auth-file replacement atomic and private, and serialize sync and async refreshes that share one auth store. - Preserve the enforced Responses settings, including disabled server-side storage and streaming behavior. - Keep `request()` and `request_stream()` distinct: `request()` may collect a required SSE response, while `request_stream()` must expose deltas before the terminal response event. - Keep HTTP as the default; WebSocket continuation must be explicitly selected and scoped to one logical run. - Treat local Codex auth as machine-local user state; do not bake it into images, artifacts, CI logs, or shared volumes.