chore: import upstream snapshot with attribution

src/agents/extensions/experimental/codex/codex_options.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from typing import Any
+
+from agents.exceptions import UserError
+
+
+@dataclass(frozen=True)
+class CodexOptions:
+    # Optional absolute path to the codex CLI binary.
+    codex_path_override: str | None = None
+    # Override OpenAI base URL for the Codex CLI process.
+    base_url: str | None = None
+    # API key passed to the Codex CLI (CODEX_API_KEY).
+    api_key: str | None = None
+    # Environment variables for the Codex CLI process (do not inherit os.environ).
+    env: Mapping[str, str] | None = None
+    # StreamReader byte limit used for Codex subprocess stdout/stderr pipes.
+    codex_subprocess_stream_limit_bytes: int | None = None
+
+
+def coerce_codex_options(
+    options: CodexOptions | Mapping[str, Any] | None,
+) -> CodexOptions | None:
+    if options is None or isinstance(options, CodexOptions):
+        return options
+    if not isinstance(options, Mapping):
+        raise UserError("CodexOptions must be a CodexOptions or a mapping.")
+
+    allowed = {field.name for field in fields(CodexOptions)}
+    unknown = set(options.keys()) - allowed
+    if unknown:
+        raise UserError(f"Unknown CodexOptions field(s): {sorted(unknown)}")
+
+    return CodexOptions(**dict(options))