painapple-code 1.0.0__py3-none-any.whl

painapple_code/providers/claude_sdk/__init__.py

@@ -0,0 +1,139 @@
+"""
+Claude Code via the Claude Agent SDK — SDK-backed provider.
+
+Same engine as `ClaudeProvider`, but the subprocess the server spawns is a
+thin Python *driver* (`providers/claude_sdk/driver.py`) that runs
+`ClaudeSDKClient` in-process instead of exec'ing `claude -p` directly:
+
+    server ──stream-json lines──> driver ──SDK control protocol──> claude CLI
+
+The driver tees the CLI's raw stream-json verbatim onto its own stdout and
+forwards the server's canonical user messages from stdin into the SDK, so
+from the session layer's point of view this provider is wire-identical to
+`ClaudeProvider`: same "lines" transport, same events, same stderr strings,
+same signal semantics (SIGINT/SIGTERM → clean exit). Everything Claude-shaped
+(cost normalization, stderr classification, summary fork, /context probe,
+models/accounts/permission vocab) is inherited unchanged.
+
+What the extra hop buys is the SDK's control plane — a first-class seam for
+interactive permissions (`can_use_tool`), native interrupt, and mid-session
+mode/model changes. See docs-ai/plans/2026-07-07-agent-sdk-migration.md.
+
+Selection: this is the default provider (DEFAULT_PROVIDER) — new sessions adopt
+it, and sessions that record no provider fall back to it. Sessions persist
+`provider: "claude-sdk"` in meta. A tier can pin the line-protocol `claude`
+provider instead via the `default_provider` config key or the
+`--default-provider` server flag.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+
+from painapple_code.providers.base import LaunchOptions
+from painapple_code.providers.claude import ClaudeProvider
+
+
+class ClaudeSdkProvider(ClaudeProvider):
+    """Claude Code driven through `claude-agent-sdk` in a driver subprocess."""
+
+    name = "claude-sdk"
+    display_name = "Claude Code (SDK)"
+    description = "Anthropic Claude Code via the Agent SDK — live controls, ask-mode cards"
+    # The preferred Claude driver — in the picker out of the box (ClaudeProvider
+    # sets False to keep the plainer CLI variant hidden; undo that here).
+    default_enabled = True
+    # Same engine, same feature surface as Claude — plus the SDK's
+    # can_use_tool permission round-trip (driver ⇄ server ⇄ client) and its
+    # control plane (live permission-mode/model switches, warm-process
+    # interrupt) via control_request/control_done frames on the same pipe.
+    capabilities = replace(ClaudeProvider.capabilities,
+                           interactive_permissions=True,
+                           live_controls=True)
+
+    def permission_modes(self) -> list[dict]:
+        # Claude's modes plus "Ask" (CLI mode `default`) — the manual-accept
+        # mode: reads are auto-allowed, everything else surfaces a permission
+        # card. Only offered here: on the line-protocol provider `default`
+        # just auto-denies (nothing can answer the prompt), so exposing it
+        # there would be a trap.
+        modes = ClaudeProvider.permission_modes(self)
+        ask = {"value": "default", "label": "Ask",
+               "desc": "Approve each edit/command via permission card",
+               "color": "#2dd4bf"}
+        modes.insert(1, ask)  # right after Plan
+        # The base `claude` provider's Accept Edits desc says "deny others" —
+        # accurate for line-protocol `claude -p`, where there's no can_use_tool
+        # gate so out-of-workspace ops hard-deny (surface as is_error results).
+        # Here the SDK's can_use_tool gate is wired for acceptEdits too
+        # (driver.py), so those ops surface an approve/deny card instead of
+        # denying. Patch the one field the interactive-permissions seam made
+        # stale, leaving the rest of the inherited vocab untouched.
+        for m in modes:
+            if m["value"] == "acceptEdits":
+                m["desc"] = "Auto-approve workspace edits; others prompt for approval"
+        return modes
+
+    def default_permission_mode(self) -> str:
+        # Ask, not the base "dontAsk". The SDK engine can actually answer a
+        # prompt (can_use_tool → permission card), so the sane out-of-the-box
+        # default is manual-accept — reads flow, edits/commands surface a card —
+        # rather than auto-denying. (On the line-protocol provider "default"
+        # would be a trap: nothing can answer, so every ask becomes a denial;
+        # that's why the base stays "dontAsk".)
+        return "default"
+
+    def build_command(self, opts: LaunchOptions) -> list[str]:
+        # The server's venv python, not "python" off PATH — the driver imports
+        # both painapple_code and claude_agent_sdk from this environment.
+        cmd = [
+            sys.executable, "-u", "-m",
+            "painapple_code.providers.claude_sdk.driver",
+        ]
+        # win32 + bare default: omit --cli-path so the SDK's _find_cli()
+        # discovers the CLI — it prefers a native claude.exe (bundled or
+        # installed) and refuses npm's claude.cmd shim with a curated
+        # remediation (CVE-2024-27980 class); which-resolving "claude" here
+        # would hand the SDK exactly the shim it's designed to reject.
+        # POSIX keeps passing the resolved system binary unconditionally —
+        # omitting it would let the SDK prefer its _bundled/ CLI over the
+        # user's installed claude, a silent version switch.
+        if sys.platform != "win32" or self.binary() != self.default_binary:
+            cmd.extend(["--cli-path", self.binary()])
+
+        if opts.model:
+            cmd.extend(["--model", opts.model])
+
+        if opts.fallback_model:
+            cmd.extend(["--fallback-model", opts.fallback_model])
+
+        # "high" is the CLI default; skip to avoid noise (mirrors launch.py).
+        if opts.effort and opts.effort != "high":
+            cmd.extend(["--effort", opts.effort])
+
+        cmd.extend(["--permission-mode", opts.permission_mode or self.default_permission_mode()])
+
+        if opts.fork_from_session_id:
+            cmd.extend(["--resume", opts.fork_from_session_id, "--fork-session"])
+        elif opts.session_id:
+            cmd.extend(["--resume", opts.session_id])
+
+        return cmd
+
+    def binary_not_found_hint(self) -> str:
+        return ("The SDK driver spawns the Claude CLI; install it and make "
+                "sure it's on the server's PATH (or set claude_path in config).")
+
+    def is_available(self) -> tuple[bool, str | None]:
+        try:
+            import claude_agent_sdk  # noqa: F401
+        except ImportError:
+            return False, ("claude-agent-sdk not installed in the server venv "
+                           "(pip install claude-agent-sdk)")
+        # SDK present — availability then hinges on the claude CLI, same as
+        # the line-protocol provider.
+        return super().is_available()
+
+
+PROVIDERS = [ClaudeSdkProvider()]

painapple_code/providers/claude_sdk/driver.py

@@ -0,0 +1,412 @@
+"""
+Agent-SDK driver subprocess for the `claude-sdk` provider.
+
+The server spawns this module (`python -u -m painapple_code.providers.claude_sdk.driver`)
+exactly where it would spawn `claude -p`, and speaks the same wire protocol to
+it: canonical stream-json user messages in on stdin, canonical stream-json
+events out on stdout, CLI diagnostics on stderr. Internally it drives the
+Claude Code CLI through `ClaudeSDKClient` and *tees the raw stream-json dicts
+off the SDK transport verbatim*, so the bytes the server reads are the CLI's
+own output, not a lossy reconstruction from the SDK's typed objects — event
+parity with the line-protocol provider holds by construction.
+
+Signal contract (matches what the session layer expects of the CLI):
+  SIGINT  → abort the turn, shut the SDK client down, exit 130
+  SIGTERM → shut down, exit 143
+  stdin EOF (server died/closed) → shut down, exit 0
+Closing the client terminates the CLI child, so no orphan is left behind.
+
+stdout is protocol-only — never print anything else to it. Driver-side
+diagnostics go to stderr, where the server's stderr reader forwards/classifies
+them like any CLI stderr line.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import dataclasses
+import itertools
+import json
+import os
+import shutil
+import signal
+import sys
+import threading
+from collections.abc import AsyncIterator
+from typing import Any
+
+# Matches the server reader's MAX_LINE_SIZE ceiling (utils/agent_cli.py); the
+# stdin limit is higher because pasted/uploaded base64 images ride in the user
+# message envelope.
+MAX_EVENT_SIZE = 10 * 1024 * 1024
+MAX_STDIN_LINE = 64 * 1024 * 1024
+
+# Stream event types forwarded to the server. Everything else on the transport
+# (control_request/control_response handshakes, keep-alives) is SDK plumbing
+# the server must not see.
+_STREAM_TYPES = frozenset({"system", "assistant", "user", "result"})
+
+# Tools whose "ask" the server already handles with its own chat-UI flow
+# (question wizard / plan-approval card + SIGINT auto-stop). Deny them here
+# with a steering message instead of surfacing a permission card, so both
+# providers keep the identical UX for these two.
+_UI_FLOW_TOOLS = frozenset({"AskUserQuestion", "ExitPlanMode"})
+_UI_FLOW_DENY = ("The user will respond through the chat UI. Stop and wait "
+                 "for their reply instead of retrying this tool.")
+
+
+def _jsonable(obj: Any) -> Any:
+    """Best-effort conversion of SDK dataclasses/enums for the wire."""
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _jsonable(v) for k, v in dataclasses.asdict(obj).items() if v is not None}
+    if isinstance(obj, dict):
+        return {k: _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    return str(obj)
+
+
+def _emit(msg: dict) -> None:
+    """Write one canonical event line to the server."""
+    sys.stdout.write(json.dumps(msg, ensure_ascii=False, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def _note(text: str) -> None:
+    """Driver-side diagnostic → server stderr reader."""
+    print(f"claude-sdk driver: {text}", file=sys.stderr, flush=True)
+
+
+def _make_tee_transport(options):
+    """Subclass the SDK's subprocess transport to tee raw dicts to stdout.
+
+    Built lazily inside a function so importing this module never hard-requires
+    the SDK internals; version drift in `SubprocessCLITransport` surfaces here
+    as a loud startup error, not a wedged session.
+    """
+    from claude_agent_sdk._internal.transport.subprocess_cli import (
+        SubprocessCLITransport,
+    )
+
+    class _TeeTransport(SubprocessCLITransport):
+        def read_messages(self) -> AsyncIterator[dict[str, Any]]:
+            return self._tee(super().read_messages())
+
+        @staticmethod
+        async def _tee(inner: AsyncIterator[dict[str, Any]]) -> AsyncIterator[dict[str, Any]]:
+            async for msg in inner:
+                if msg.get("type") in _STREAM_TYPES:
+                    _emit(msg)
+                yield msg
+
+    async def _pending() -> AsyncIterator[dict[str, Any]]:
+        # Never yields; marks streaming-input mode so the CLI's stdin stays
+        # open for the queries we write per server message.
+        return
+        yield {}  # pragma: no cover
+
+    return _TeeTransport(prompt=_pending(), options=options)
+
+
+async def _amain(args: argparse.Namespace) -> int:
+    from claude_agent_sdk import (
+        ClaudeAgentOptions,
+        ClaudeSDKClient,
+        PermissionResultAllow,
+        PermissionResultDeny,
+    )
+
+    loop = asyncio.get_running_loop()
+
+    # Interactive permissions: `can_use_tool` fires whenever the CLI's
+    # permission flow resolves to a prompt. We round-trip the decision to the
+    # server as a `permission_request` stdout line and await the matching
+    # `permission_response` stdin line (routed by the stdin loop below).
+    pending_permissions: dict[str, asyncio.Future] = {}
+    request_ids = (f"perm-{n}" for n in itertools.count(1))
+
+    async def on_permission(tool_name: str, tool_input: dict, context) -> Any:
+        if tool_name in _UI_FLOW_TOOLS:
+            return PermissionResultDeny(message=_UI_FLOW_DENY)
+        req_id = next(request_ids)
+        fut: asyncio.Future = loop.create_future()
+        pending_permissions[req_id] = fut
+        suggestions = list(getattr(context, "suggestions", []) or [])
+        _emit({
+            "type": "permission_request",
+            "request_id": req_id,
+            "tool_name": tool_name,
+            "input": _jsonable(tool_input),
+            "tool_use_id": getattr(context, "tool_use_id", None),
+            "title": getattr(context, "title", None),
+            "description": getattr(context, "description", None),
+            "display_name": getattr(context, "display_name", None),
+            "decision_reason": _jsonable(getattr(context, "decision_reason", None)),
+            "blocked_path": getattr(context, "blocked_path", None),
+            "suggestions": _jsonable(suggestions),
+        })
+        try:
+            resp = await fut
+        finally:
+            pending_permissions.pop(req_id, None)
+        if resp.get("behavior") == "allow":
+            # "Always allow": the client picked one of the CLI's own permission
+            # suggestions (addRules / addDirectories / setMode). Hand the
+            # original PermissionUpdate object back and the CLI applies it —
+            # rule persistence is entirely engine-side, nothing reimplemented.
+            updated_permissions = None
+            idx = resp.get("suggestion_index")
+            if isinstance(idx, int) and 0 <= idx < len(suggestions):
+                updated_permissions = [suggestions[idx]]
+            return PermissionResultAllow(
+                updated_input=resp.get("updated_input"),
+                updated_permissions=updated_permissions,
+            )
+        # Attribute the guidance to the user explicitly — a bare denial string
+        # in an error-shaped tool result reads like injected tool output and
+        # the model may distrust it.
+        guidance = resp.get("message")
+        return PermissionResultDeny(
+            message=(f"The user denied this tool call and said: {guidance}"
+                     if guidance else "The user denied this tool call."),
+            interrupt=bool(resp.get("interrupt")),
+        )
+
+    # bypassPermissions (YOLO) auto-approves every tool call before can_use_tool
+    # is ever consulted, so wiring the callback does nothing except trip the
+    # SDK's CanUseToolShadowedWarning — which the server's stderr reader surfaces
+    # as a scary (but harmless) error line. Only attach the permission gate for
+    # modes that can actually prompt.
+    gate = None if args.permission_mode == "bypassPermissions" else on_permission
+
+    options = ClaudeAgentOptions(
+        can_use_tool=gate,
+        model=args.model,
+        fallback_model=args.fallback_model,
+        effort=args.effort,
+        permission_mode=args.permission_mode,
+        resume=args.resume,
+        fork_session=args.fork_session,
+        # The server already sets cwd on the driver process; pin the CLI to it.
+        cwd=os.getcwd(),
+        # None → the SDK's _find_cli() discovers (and on win32 vets) the CLI;
+        # an explicit config value is which-resolved as before.
+        cli_path=(shutil.which(args.cli_path) or args.cli_path) if args.cli_path else None,
+        # Restore thinking summaries on all models (see providers/claude/launch.py).
+        extra_args={"thinking-display": "summarized"},
+        # Mirror CLI stderr onto ours so the server's classifier sees the exact
+        # strings it matches today (stale session, API 5xx, compaction, …).
+        stderr=lambda line: print(line, file=sys.stderr, flush=True),
+        max_buffer_size=MAX_EVENT_SIZE,
+    )
+
+    stop = asyncio.Event()
+    exit_code = 0
+
+    def _shutdown(code: int) -> None:
+        nonlocal exit_code
+        exit_code = code
+        stop.set()
+
+    if sys.platform == "win32":
+        # Proactor has no add_signal_handler (NotImplementedError — a Windows 11
+        # probe). signal.signal works: CPython's wakeup channel rouses the
+        # loop, and call_soon_threadsafe hops back onto it. The server's
+        # interrupt_process() sends CTRL_BREAK → SIGBREAK here (SIGTERM is
+        # undeliverable on win32; parent terminate() covers that path).
+        def _sig_handler(signum, frame):
+            loop.call_soon_threadsafe(
+                _shutdown, 130 if signum == signal.SIGINT else 143
+            )
+        signal.signal(signal.SIGINT, _sig_handler)
+        signal.signal(signal.SIGBREAK, _sig_handler)
+    else:
+        loop.add_signal_handler(signal.SIGINT, _shutdown, 130)
+        loop.add_signal_handler(signal.SIGTERM, _shutdown, 143)
+
+    # With a custom transport, ClaudeSDKClient skips its own
+    # `permission_prompt_tool_name="stdio"` injection (it only applies it to
+    # the transport it would have built itself), so set it on the *transport's*
+    # options copy here. It must NOT go on the client's options — the client
+    # rejects it alongside `can_use_tool`. Pair it with the gate: in bypass mode
+    # there's nothing to route to stdio, so keep that path a clean pass-through.
+    transport_opts = dataclasses.replace(options, can_use_tool=None)
+    if gate is not None:
+        transport_opts = dataclasses.replace(transport_opts, permission_prompt_tool_name="stdio")
+    transport = _make_tee_transport(transport_opts)
+    client = ClaudeSDKClient(options=options, transport=transport)
+    try:
+        await client.connect()
+    except Exception as e:
+        _note(f"failed to start Claude CLI via SDK: {e}")
+        return 1
+
+    async def stdin_loop() -> None:
+        """Forward each canonical user-message line from the server into the SDK."""
+        if sys.platform == "win32":
+            # connect_read_pipe on an inherited stdin HALF-works under
+            # Proactor: it connects, then the first read dies with
+            # OSError WinError 6 and leaves stdin unusable (a Windows 11 probe
+            # 3). Don't attempt it — a daemon thread doing blocking
+            # readline feeds the loop through an asyncio queue instead.
+            queue: asyncio.Queue = asyncio.Queue()
+
+            def _pump() -> None:
+                try:
+                    while True:
+                        raw = sys.stdin.buffer.readline()
+                        loop.call_soon_threadsafe(queue.put_nowait, raw)
+                        if not raw:  # EOF — server closed our stdin
+                            return
+                except Exception:
+                    loop.call_soon_threadsafe(queue.put_nowait, b"")
+
+            threading.Thread(target=_pump, daemon=True, name="stdin-pump").start()
+
+            async def _readline() -> bytes:
+                return await queue.get()
+        else:
+            reader = asyncio.StreamReader(limit=MAX_STDIN_LINE)
+            await loop.connect_read_pipe(
+                lambda: asyncio.StreamReaderProtocol(reader), sys.stdin
+            )
+
+            async def _readline() -> bytes:
+                return await reader.readline()
+
+        while True:
+            line = await _readline()
+            if not line:
+                # Server closed stdin. Mirror `claude -p` one-shot semantics:
+                # close the CLI's stdin and let it finish in-flight work; the
+                # drain loop shuts us down when the CLI exits.
+                try:
+                    await transport.end_input()
+                except Exception:
+                    _shutdown(0)
+                return
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                _note("dropping non-JSON stdin line")
+                continue
+
+            # Server frames ride the same pipe: permission decisions resolve
+            # the future the matching can_use_tool callback is awaiting.
+            if msg.get("type") == "permission_response":
+                fut = pending_permissions.get(msg.get("request_id"))
+                if fut and not fut.done():
+                    fut.set_result(msg)
+                else:
+                    _note(f"permission_response for unknown request "
+                          f"{msg.get('request_id')!r}")
+                continue
+
+            # Control plane (Capabilities.live_controls): live mode/model
+            # switches and warm-process interrupt via the SDK client. Every
+            # request is acked with `control_done` — the server treats a
+            # nack/timeout as "fall back to kill+respawn", so failing loudly
+            # here is always safe. Ordering with user messages is enforced
+            # server-side (it awaits the ack before writing the message).
+            if msg.get("type") == "control_request":
+                action = msg.get("action")
+                ok, err = True, None
+                try:
+                    if action == "interrupt":
+                        # Unblock pending can_use_tool callbacks first so they
+                        # unwind as clean user denials instead of being
+                        # cancelled mid-await by the abort.
+                        for fut in list(pending_permissions.values()):
+                            if not fut.done():
+                                fut.set_result({"behavior": "deny", "interrupt": True})
+                        await client.interrupt()
+                    elif action == "set_permission_mode":
+                        await client.set_permission_mode(msg.get("mode"))
+                    elif action == "set_model":
+                        # None = revert to the CLI/account default model.
+                        await client.set_model(msg.get("model"))
+                    else:
+                        ok, err = False, f"unknown control action {action!r}"
+                except Exception as e:
+                    ok, err = False, str(e)
+                    _note(f"control {action} failed: {e}")
+                _emit({
+                    "type": "control_done",
+                    "control_id": msg.get("control_id"),
+                    "action": action,
+                    "ok": ok,
+                    "error": err,
+                })
+                continue
+
+            async def _one(m=msg) -> AsyncIterator[dict[str, Any]]:
+                yield m
+
+            await client.query(_one())
+
+    async def drain_loop() -> None:
+        """Keep the SDK's parsed-message queue drained (the tee already emitted
+        the raw dicts); surface transport/process failures as an exit."""
+        try:
+            async for _ in client.receive_messages():
+                pass
+            _shutdown(0)
+        except Exception as e:
+            _note(str(e))
+            code = getattr(e, "exit_code", None)
+            _shutdown(code if isinstance(code, int) and code > 0 else 1)
+
+    tasks = [asyncio.create_task(stdin_loop()), asyncio.create_task(drain_loop())]
+    try:
+        await stop.wait()
+    finally:
+        for t in tasks:
+            t.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        try:
+            await client.disconnect()  # terminates the CLI child
+        except Exception as e:
+            _note(f"error during shutdown: {e}")
+    return exit_code
+
+
+def main() -> None:
+    if sys.platform == "win32":
+        # stdout is the wire to the server and emit() uses ensure_ascii=False —
+        # a cp1252 pipe would corrupt the first non-ASCII assistant token.
+        from painapple_code.utils.proc import force_utf8_stdio
+        force_utf8_stdio()
+    parser = argparse.ArgumentParser(description="painapple-code Agent SDK driver")
+    parser.add_argument("--cli-path", default=None)  # None → SDK _find_cli()
+    parser.add_argument("--model", default=None)
+    parser.add_argument("--fallback-model", default=None)
+    parser.add_argument("--effort", default=None)
+    parser.add_argument("--permission-mode", default=None)
+    parser.add_argument("--resume", default=None)
+    parser.add_argument("--fork-session", action="store_true")
+    args = parser.parse_args()
+    code = asyncio.run(_amain(args))
+    if sys.platform == "win32":
+        # The win32 stdin pump is a daemon thread parked in a blocking
+        # readline(), so it owns the <stdin> BufferedReader lock at exit.
+        # Normal interpreter finalization waits for that lock and instead
+        # aborts with "Fatal Python error: _enter_buffered_busy" on stderr —
+        # which the server forwards verbatim, painting three red error
+        # bubbles into the chat on every AskUserQuestion auto-stop.
+        # _amain's finally already disconnected the CLI child and cancelled
+        # the loop tasks, so finalization has nothing left to do; skip it
+        # rather than lose a race it cannot win. os._exit does not flush.
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os._exit(code)
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

painapple_code/providers/codex/__init__.py

@@ -0,0 +1,87 @@
+"""
+OpenAI Codex CLI provider (`codex exec --json`).
+
+Unlike Claude (one persistent `claude -p` process streaming stream-json over
+stdin/stdout across many turns), Codex runs **one `codex exec` process per
+turn**: the prompt is a positional argv, the run emits newline-delimited JSON
+events to stdout, and the process exits when the turn ends. Continuation is a
+fresh `codex exec resume <thread_id> "<prompt>"`. So this provider declares
+`persistent_process=False` and the session layer drives a per-turn spawn loop.
+
+The adapter is assembled from focused mixins (this file is the combiner — see
+`session_store.py` / `shadow_git.py` for the same pattern in this codebase):
+
+    capabilities.py  → _CapabilitiesMixin  binary, availability, effort/perm
+                                            vocabularies, skill/agent/plugin
+                                            roots, context metering
+    launch.py        → _LaunchMixin         build_command + image materialization
+    translate.py     → _TranslateMixin      Codex events → canonical Claude shape
+    summary.py       → _SummaryMixin         rich-commit summary fork (rollout copy)
+    errors.py        → _ErrorsMixin          stderr classification / retry policy
+
+Codex reports token counts but no per-turn USD cost, so result cost is left at 0
+(see the step-two plan: tokens-only, cost null). Token usage is per-turn already,
+so no cumulative→delta conversion is needed.
+"""
+
+from __future__ import annotations
+
+from painapple_code.providers.base import Provider, Capabilities
+from painapple_code.providers.codex.capabilities import _CapabilitiesMixin
+from painapple_code.providers.codex.launch import _LaunchMixin
+from painapple_code.providers.codex.translate import _TranslateMixin
+from painapple_code.providers.codex.summary import _SummaryMixin
+from painapple_code.providers.codex.errors import _ErrorsMixin
+
+
+class CodexProvider(
+    _CapabilitiesMixin,
+    _LaunchMixin,
+    _TranslateMixin,
+    _SummaryMixin,
+    _ErrorsMixin,
+    Provider,
+):
+    """Adapter for the OpenAI Codex CLI (`codex exec --json`).
+
+    The behaviour lives in the mixins above; this class only carries the static
+    identity + capability flags and the MRO that composes them (mixins first, so
+    their overrides win over the `Provider` defaults, with `super()` calls — e.g.
+    `is_available` — still reaching the base implementation).
+    """
+
+    name = "codex"
+    display_name = "Codex CLI"
+    description = "OpenAI Codex CLI — one exec process per turn"
+    # Same engine as codex-app-server but the plainer per-turn exec driver
+    # (no native fork, no live interrupt) — kept out of the picker by default
+    # so Codex appears once. Flip it on in Settings → Engines.
+    default_enabled = False
+    capabilities = Capabilities(
+        resume=True,
+        fork=False,                # no --fork-session equivalent
+        permission_modes=True,
+        effort=True,
+        thinking_display=True,     # native `reasoning` items
+        context_command=False,     # no /context equivalent in exec mode
+        cumulative_cost=False,     # per-turn usage, and no USD figure at all
+        # The post-turn fork summarizes the turn with Codex itself (see
+        # summary.py / build_summary_fork). Codex has no `--fork-session`, and
+        # `codex exec resume` writes in place, so the fork copies the thread's
+        # rollout under a fresh id and resumes the copy — branching like Claude's
+        # --fork-session without polluting the user's real thread.
+        rich_commit_summaries=True,
+        persistent_process=False,  # one `codex exec` per turn
+        forward_plain_stderr=False,  # codex prints human progress to stderr
+        # `codex exec` has no stdin protocol — frame_input() raises to say so —
+        # so build_command appends the prompt as a positional arg. Nothing here
+        # can route around it; the sibling codex-app-server driver speaks stdio
+        # and is the engine to prefer on a shared host.
+        prompt_in_argv=True,
+    )
+
+
+# Registry contribution — see providers/claude.py for the convention. The
+# package scanner in providers/__init__.py discovers this exactly like a flat
+# module (pkgutil.iter_modules lists subpackages too).
+PROVIDERS = [CodexProvider()]