openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/extensions/experimental/codex/events.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Union, cast
+
+from typing_extensions import Literal, TypeAlias
+
+from .items import ThreadItem, coerce_thread_item
+from .payloads import _DictLike
+
+# Event payloads emitted by the Codex CLI JSONL stream.
+
+
+@dataclass(frozen=True)
+class ThreadStartedEvent(_DictLike):
+    thread_id: str
+    type: Literal["thread.started"] = field(default="thread.started", init=False)
+
+
+@dataclass(frozen=True)
+class TurnStartedEvent(_DictLike):
+    type: Literal["turn.started"] = field(default="turn.started", init=False)
+
+
+@dataclass(frozen=True)
+class Usage(_DictLike):
+    input_tokens: int
+    cached_input_tokens: int
+    output_tokens: int
+
+
+@dataclass(frozen=True)
+class TurnCompletedEvent(_DictLike):
+    usage: Usage | None = None
+    type: Literal["turn.completed"] = field(default="turn.completed", init=False)
+
+
+@dataclass(frozen=True)
+class ThreadError(_DictLike):
+    message: str
+
+
+@dataclass(frozen=True)
+class TurnFailedEvent(_DictLike):
+    error: ThreadError
+    type: Literal["turn.failed"] = field(default="turn.failed", init=False)
+
+
+@dataclass(frozen=True)
+class ItemStartedEvent(_DictLike):
+    item: ThreadItem
+    type: Literal["item.started"] = field(default="item.started", init=False)
+
+
+@dataclass(frozen=True)
+class ItemUpdatedEvent(_DictLike):
+    item: ThreadItem
+    type: Literal["item.updated"] = field(default="item.updated", init=False)
+
+
+@dataclass(frozen=True)
+class ItemCompletedEvent(_DictLike):
+    item: ThreadItem
+    type: Literal["item.completed"] = field(default="item.completed", init=False)
+
+
+@dataclass(frozen=True)
+class ThreadErrorEvent(_DictLike):
+    message: str
+    type: Literal["error"] = field(default="error", init=False)
+
+
+@dataclass(frozen=True)
+class _UnknownThreadEvent(_DictLike):
+    type: str
+    payload: Mapping[str, Any] = field(default_factory=dict)
+
+
+ThreadEvent: TypeAlias = Union[
+    ThreadStartedEvent,
+    TurnStartedEvent,
+    TurnCompletedEvent,
+    TurnFailedEvent,
+    ItemStartedEvent,
+    ItemUpdatedEvent,
+    ItemCompletedEvent,
+    ThreadErrorEvent,
+    _UnknownThreadEvent,
+]
+
+
+def _coerce_thread_error(raw: ThreadError | Mapping[str, Any]) -> ThreadError:
+    if isinstance(raw, ThreadError):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("ThreadError must be a mapping.")
+    return ThreadError(message=cast(str, raw.get("message", "")))
+
+
+def coerce_usage(raw: Usage | Mapping[str, Any]) -> Usage:
+    if isinstance(raw, Usage):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("Usage must be a mapping.")
+    return Usage(
+        input_tokens=cast(int, raw["input_tokens"]),
+        cached_input_tokens=cast(int, raw["cached_input_tokens"]),
+        output_tokens=cast(int, raw["output_tokens"]),
+    )
+
+
+def coerce_thread_event(raw: ThreadEvent | Mapping[str, Any]) -> ThreadEvent:
+    if isinstance(raw, _DictLike):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("Thread event payload must be a mapping.")
+
+    event_type = raw.get("type")
+    if event_type == "thread.started":
+        return ThreadStartedEvent(thread_id=cast(str, raw["thread_id"]))
+    if event_type == "turn.started":
+        return TurnStartedEvent()
+    if event_type == "turn.completed":
+        usage_raw = raw.get("usage")
+        usage = coerce_usage(cast(Mapping[str, Any], usage_raw)) if usage_raw is not None else None
+        return TurnCompletedEvent(usage=usage)
+    if event_type == "turn.failed":
+        error_raw = raw.get("error", {})
+        error = _coerce_thread_error(cast(Mapping[str, Any], error_raw))
+        return TurnFailedEvent(error=error)
+    if event_type == "item.started":
+        item_raw = raw.get("item")
+        item = (
+            coerce_thread_item(cast(Union[ThreadItem, Mapping[str, Any]], item_raw))
+            if item_raw is not None
+            else coerce_thread_item({"type": "unknown"})
+        )
+        return ItemStartedEvent(item=item)
+    if event_type == "item.updated":
+        item_raw = raw.get("item")
+        item = (
+            coerce_thread_item(cast(Union[ThreadItem, Mapping[str, Any]], item_raw))
+            if item_raw is not None
+            else coerce_thread_item({"type": "unknown"})
+        )
+        return ItemUpdatedEvent(item=item)
+    if event_type == "item.completed":
+        item_raw = raw.get("item")
+        item = (
+            coerce_thread_item(cast(Union[ThreadItem, Mapping[str, Any]], item_raw))
+            if item_raw is not None
+            else coerce_thread_item({"type": "unknown"})
+        )
+        return ItemCompletedEvent(item=item)
+    if event_type == "error":
+        return ThreadErrorEvent(message=cast(str, raw.get("message", "")))
+
+    return _UnknownThreadEvent(
+        type=cast(str, event_type) if event_type is not None else "unknown",
+        payload=dict(raw),
+    )

agents/extensions/experimental/codex/exec.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import platform
+import shutil
+import sys
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from pathlib import Path
+
+from .thread_options import ApprovalMode, ModelReasoningEffort, SandboxMode, WebSearchMode
+
+_INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE"
+_TYPESCRIPT_SDK_ORIGINATOR = "codex_sdk_ts"
+
+
+@dataclass(frozen=True)
+class CodexExecArgs:
+    input: str
+    base_url: str | None = None
+    api_key: str | None = None
+    thread_id: str | None = None
+    images: list[str] | None = None
+    model: str | None = None
+    sandbox_mode: SandboxMode | None = None
+    working_directory: str | None = None
+    additional_directories: list[str] | None = None
+    skip_git_repo_check: bool | None = None
+    output_schema_file: str | None = None
+    model_reasoning_effort: ModelReasoningEffort | None = None
+    signal: asyncio.Event | None = None
+    idle_timeout_seconds: float | None = None
+    network_access_enabled: bool | None = None
+    web_search_mode: WebSearchMode | None = None
+    web_search_enabled: bool | None = None
+    approval_policy: ApprovalMode | None = None
+
+
+class CodexExec:
+    def __init__(
+        self,
+        *,
+        executable_path: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        self._executable_path = executable_path or find_codex_path()
+        self._env_override = env
+
+    async def run(self, args: CodexExecArgs) -> AsyncGenerator[str, None]:
+        # Build the CLI args for `codex exec --experimental-json`.
+        command_args: list[str] = ["exec", "--experimental-json"]
+
+        if args.model:
+            command_args.extend(["--model", args.model])
+
+        if args.sandbox_mode:
+            command_args.extend(["--sandbox", args.sandbox_mode])
+
+        if args.working_directory:
+            command_args.extend(["--cd", args.working_directory])
+
+        if args.additional_directories:
+            for directory in args.additional_directories:
+                command_args.extend(["--add-dir", directory])
+
+        if args.skip_git_repo_check:
+            command_args.append("--skip-git-repo-check")
+
+        if args.output_schema_file:
+            command_args.extend(["--output-schema", args.output_schema_file])
+
+        if args.model_reasoning_effort:
+            command_args.extend(
+                ["--config", f'model_reasoning_effort="{args.model_reasoning_effort}"']
+            )
+
+        if args.network_access_enabled is not None:
+            command_args.extend(
+                [
+                    "--config",
+                    f"sandbox_workspace_write.network_access={str(args.network_access_enabled).lower()}",
+                ]
+            )
+
+        if args.web_search_mode:
+            command_args.extend(["--config", f'web_search="{args.web_search_mode}"'])
+        elif args.web_search_enabled is True:
+            command_args.extend(["--config", 'web_search="live"'])
+        elif args.web_search_enabled is False:
+            command_args.extend(["--config", 'web_search="disabled"'])
+
+        if args.approval_policy:
+            command_args.extend(["--config", f'approval_policy="{args.approval_policy}"'])
+
+        if args.thread_id:
+            command_args.extend(["resume", args.thread_id])
+
+        if args.images:
+            for image in args.images:
+                command_args.extend(["--image", image])
+
+        # Codex CLI expects a prompt argument; "-" tells it to read from stdin.
+        command_args.append("-")
+
+        env = self._build_env(args)
+
+        process = await asyncio.create_subprocess_exec(
+            self._executable_path,
+            *command_args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+
+        stderr_chunks: list[bytes] = []
+
+        async def _drain_stderr() -> None:
+            # Preserve stderr for error reporting without blocking stdout reads.
+            if process.stderr is None:
+                return
+            while True:
+                chunk = await process.stderr.read(1024)
+                if not chunk:
+                    break
+                stderr_chunks.append(chunk)
+
+        stderr_task = asyncio.create_task(_drain_stderr())
+
+        if process.stdin is None:
+            process.kill()
+            raise RuntimeError("Codex subprocess has no stdin")
+
+        process.stdin.write(args.input.encode("utf-8"))
+        await process.stdin.drain()
+        process.stdin.close()
+
+        if process.stdout is None:
+            process.kill()
+            raise RuntimeError("Codex subprocess has no stdout")
+        stdout = process.stdout
+
+        cancel_task: asyncio.Task[None] | None = None
+        if args.signal is not None:
+            # Mirror AbortSignal semantics by terminating the subprocess.
+            cancel_task = asyncio.create_task(_watch_signal(args.signal, process))
+
+        async def _read_stdout_line() -> bytes:
+            if args.idle_timeout_seconds is None:
+                return await stdout.readline()
+
+            read_task: asyncio.Task[bytes] = asyncio.create_task(stdout.readline())
+            done, _ = await asyncio.wait(
+                {read_task}, timeout=args.idle_timeout_seconds, return_when=asyncio.FIRST_COMPLETED
+            )
+            if read_task in done:
+                return read_task.result()
+
+            if args.signal is not None:
+                args.signal.set()
+            if process.returncode is None:
+                process.terminate()
+
+            read_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError):
+                await asyncio.wait_for(read_task, timeout=1)
+
+            raise RuntimeError(f"Codex stream idle for {args.idle_timeout_seconds} seconds.")
+
+        try:
+            while True:
+                line = await _read_stdout_line()
+                if not line:
+                    break
+                yield line.decode("utf-8").rstrip("\n")
+
+            await process.wait()
+            if cancel_task is not None:
+                cancel_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await cancel_task
+
+            if process.returncode not in (0, None):
+                await stderr_task
+                stderr_text = b"".join(stderr_chunks).decode("utf-8")
+                raise RuntimeError(
+                    f"Codex exec exited with code {process.returncode}: {stderr_text}"
+                )
+        finally:
+            if cancel_task is not None and not cancel_task.done():
+                cancel_task.cancel()
+            await stderr_task
+            if process.returncode is None:
+                process.kill()
+
+    def _build_env(self, args: CodexExecArgs) -> dict[str, str]:
+        # Respect env overrides when provided; otherwise copy from os.environ.
+        env: dict[str, str] = {}
+        if self._env_override is not None:
+            env.update(self._env_override)
+        else:
+            env.update({key: value for key, value in os.environ.items() if value is not None})
+
+        # Preserve originator metadata used by the CLI.
+        if _INTERNAL_ORIGINATOR_ENV not in env:
+            env[_INTERNAL_ORIGINATOR_ENV] = _TYPESCRIPT_SDK_ORIGINATOR
+
+        if args.base_url:
+            env["OPENAI_BASE_URL"] = args.base_url
+        if args.api_key:
+            env["CODEX_API_KEY"] = args.api_key
+
+        return env
+
+
+async def _watch_signal(signal: asyncio.Event, process: asyncio.subprocess.Process) -> None:
+    await signal.wait()
+    if process.returncode is None:
+        process.terminate()
+
+
+def _platform_target_triple() -> str:
+    # Map the running platform to the vendor layout used in Codex releases.
+    system = sys.platform
+    arch = platform.machine().lower()
+
+    if system.startswith("linux"):
+        if arch in {"x86_64", "amd64"}:
+            return "x86_64-unknown-linux-musl"
+        if arch in {"aarch64", "arm64"}:
+            return "aarch64-unknown-linux-musl"
+    if system == "darwin":
+        if arch in {"x86_64", "amd64"}:
+            return "x86_64-apple-darwin"
+        if arch in {"arm64", "aarch64"}:
+            return "aarch64-apple-darwin"
+    if system in {"win32", "cygwin"}:
+        if arch in {"x86_64", "amd64"}:
+            return "x86_64-pc-windows-msvc"
+        if arch in {"arm64", "aarch64"}:
+            return "aarch64-pc-windows-msvc"
+
+    raise RuntimeError(f"Unsupported platform: {system} ({arch})")
+
+
+def find_codex_path() -> str:
+    # Resolution order: CODEX_PATH env, PATH lookup, bundled vendor binary.
+    path_override = os.environ.get("CODEX_PATH")
+    if path_override:
+        return path_override
+
+    which_path = shutil.which("codex")
+    if which_path:
+        return which_path
+
+    target_triple = _platform_target_triple()
+    vendor_root = Path(__file__).resolve().parent.parent.parent / "vendor"
+    arch_root = vendor_root / target_triple
+    binary_name = "codex.exe" if sys.platform.startswith("win") else "codex"
+    binary_path = arch_root / "codex" / binary_name
+    return str(binary_path)

agents/extensions/experimental/codex/items.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
+
+from typing_extensions import Literal, TypeAlias, TypeGuard
+
+from .payloads import _DictLike
+
+# Item payloads are emitted inside item.* events from the Codex CLI JSONL stream.
+
+if TYPE_CHECKING:
+    from mcp.types import ContentBlock as McpContentBlock
+else:
+    McpContentBlock = Any  # type: ignore[assignment]
+
+CommandExecutionStatus = Literal["in_progress", "completed", "failed"]
+PatchChangeKind = Literal["add", "delete", "update"]
+PatchApplyStatus = Literal["completed", "failed"]
+McpToolCallStatus = Literal["in_progress", "completed", "failed"]
+
+
+@dataclass(frozen=True)
+class CommandExecutionItem(_DictLike):
+    id: str
+    command: str
+    status: CommandExecutionStatus
+    aggregated_output: str = ""
+    exit_code: int | None = None
+    type: Literal["command_execution"] = field(default="command_execution", init=False)
+
+
+@dataclass(frozen=True)
+class FileUpdateChange(_DictLike):
+    path: str
+    kind: PatchChangeKind
+
+
+@dataclass(frozen=True)
+class FileChangeItem(_DictLike):
+    id: str
+    changes: list[FileUpdateChange]
+    status: PatchApplyStatus
+    type: Literal["file_change"] = field(default="file_change", init=False)
+
+
+@dataclass(frozen=True)
+class McpToolCallResult(_DictLike):
+    content: list[McpContentBlock]
+    structured_content: Any
+
+
+@dataclass(frozen=True)
+class McpToolCallError(_DictLike):
+    message: str
+
+
+@dataclass(frozen=True)
+class McpToolCallItem(_DictLike):
+    id: str
+    server: str
+    tool: str
+    arguments: Any
+    status: McpToolCallStatus
+    result: McpToolCallResult | None = None
+    error: McpToolCallError | None = None
+    type: Literal["mcp_tool_call"] = field(default="mcp_tool_call", init=False)
+
+
+@dataclass(frozen=True)
+class AgentMessageItem(_DictLike):
+    id: str
+    text: str
+    type: Literal["agent_message"] = field(default="agent_message", init=False)
+
+
+@dataclass(frozen=True)
+class ReasoningItem(_DictLike):
+    id: str
+    text: str
+    type: Literal["reasoning"] = field(default="reasoning", init=False)
+
+
+@dataclass(frozen=True)
+class WebSearchItem(_DictLike):
+    id: str
+    query: str
+    type: Literal["web_search"] = field(default="web_search", init=False)
+
+
+@dataclass(frozen=True)
+class ErrorItem(_DictLike):
+    id: str
+    message: str
+    type: Literal["error"] = field(default="error", init=False)
+
+
+@dataclass(frozen=True)
+class TodoItem(_DictLike):
+    text: str
+    completed: bool
+
+
+@dataclass(frozen=True)
+class TodoListItem(_DictLike):
+    id: str
+    items: list[TodoItem]
+    type: Literal["todo_list"] = field(default="todo_list", init=False)
+
+
+@dataclass(frozen=True)
+class _UnknownThreadItem(_DictLike):
+    type: str
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    id: str | None = None
+
+
+ThreadItem: TypeAlias = Union[
+    AgentMessageItem,
+    ReasoningItem,
+    CommandExecutionItem,
+    FileChangeItem,
+    McpToolCallItem,
+    WebSearchItem,
+    TodoListItem,
+    ErrorItem,
+    _UnknownThreadItem,
+]
+
+
+def is_agent_message_item(item: ThreadItem) -> TypeGuard[AgentMessageItem]:
+    return isinstance(item, AgentMessageItem)
+
+
+def _coerce_file_update_change(
+    raw: FileUpdateChange | Mapping[str, Any],
+) -> FileUpdateChange:
+    if isinstance(raw, FileUpdateChange):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("FileUpdateChange must be a mapping.")
+    return FileUpdateChange(
+        path=cast(str, raw["path"]),
+        kind=cast(PatchChangeKind, raw["kind"]),
+    )
+
+
+def _coerce_mcp_tool_call_result(
+    raw: McpToolCallResult | Mapping[str, Any],
+) -> McpToolCallResult:
+    if isinstance(raw, McpToolCallResult):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("McpToolCallResult must be a mapping.")
+    content = cast(list[McpContentBlock], raw.get("content", []))
+    return McpToolCallResult(
+        content=content,
+        structured_content=raw.get("structured_content"),
+    )
+
+
+def _coerce_mcp_tool_call_error(
+    raw: McpToolCallError | Mapping[str, Any],
+) -> McpToolCallError:
+    if isinstance(raw, McpToolCallError):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("McpToolCallError must be a mapping.")
+    return McpToolCallError(message=cast(str, raw.get("message", "")))
+
+
+def coerce_thread_item(raw: ThreadItem | Mapping[str, Any]) -> ThreadItem:
+    if isinstance(raw, _DictLike):
+        return raw
+    if not isinstance(raw, Mapping):
+        raise TypeError("Thread item payload must be a mapping.")
+
+    item_type = raw.get("type")
+    if item_type == "command_execution":
+        return CommandExecutionItem(
+            id=cast(str, raw["id"]),
+            command=cast(str, raw["command"]),
+            aggregated_output=cast(str, raw.get("aggregated_output", "")),
+            status=cast(CommandExecutionStatus, raw["status"]),
+            exit_code=cast(Optional[int], raw.get("exit_code")),
+        )
+    if item_type == "file_change":
+        changes = [_coerce_file_update_change(change) for change in raw.get("changes", [])]
+        return FileChangeItem(
+            id=cast(str, raw["id"]),
+            changes=changes,
+            status=cast(PatchApplyStatus, raw["status"]),
+        )
+    if item_type == "mcp_tool_call":
+        result_raw = raw.get("result")
+        error_raw = raw.get("error")
+        result = None
+        error = None
+        if result_raw is not None:
+            result = _coerce_mcp_tool_call_result(cast(Mapping[str, Any], result_raw))
+        if error_raw is not None:
+            error = _coerce_mcp_tool_call_error(cast(Mapping[str, Any], error_raw))
+        return McpToolCallItem(
+            id=cast(str, raw["id"]),
+            server=cast(str, raw["server"]),
+            tool=cast(str, raw["tool"]),
+            arguments=raw.get("arguments"),
+            status=cast(McpToolCallStatus, raw["status"]),
+            result=result,
+            error=error,
+        )
+    if item_type == "agent_message":
+        return AgentMessageItem(
+            id=cast(str, raw["id"]),
+            text=cast(str, raw.get("text", "")),
+        )
+    if item_type == "reasoning":
+        return ReasoningItem(
+            id=cast(str, raw["id"]),
+            text=cast(str, raw.get("text", "")),
+        )
+    if item_type == "web_search":
+        return WebSearchItem(
+            id=cast(str, raw["id"]),
+            query=cast(str, raw.get("query", "")),
+        )
+    if item_type == "todo_list":
+        items_raw = raw.get("items", [])
+        items = [
+            TodoItem(text=cast(str, item.get("text", "")), completed=bool(item.get("completed")))
+            for item in cast(list[Mapping[str, Any]], items_raw)
+        ]
+        return TodoListItem(id=cast(str, raw["id"]), items=items)
+    if item_type == "error":
+        return ErrorItem(
+            id=cast(str, raw.get("id", "")),
+            message=cast(str, raw.get("message", "")),
+        )
+
+    return _UnknownThreadItem(
+        type=cast(str, item_type) if item_type is not None else "unknown",
+        payload=dict(raw),
+        id=cast(Optional[str], raw.get("id")),
+    )