Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
29.6 KB
Raw Blame
"""Owned Codex app-server processes over bidirectional stdio JSONL."""

import asyncio
import hashlib
import json
import os
import shutil
import signal
import subprocess
import uuid
from collections.abc import Mapping
from contextlib import ExitStack, suppress
from dataclasses import dataclass, field, replace

from free_claude_code.application.code_sessions.models import (
    CodeCatalog,
    CodeConflictError,
    CodeMode,
    CodeModel,
    CodeUnavailableError,
    CodeValidationError,
    HarnessEvent,
    NativeHistoryMissing,
    NativeThread,
)
from free_claude_code.application.code_sessions.ports import EventSink, HarnessSelection
from free_claude_code.application.model_catalog import CatalogModel, read_model_catalog
from free_claude_code.application.ports import RequestRuntimePort
from free_claude_code.cli.process_registry import register_pid, unregister_pid
from free_claude_code.config.model_refs import split_provider_model_ref
from free_claude_code.config.server_urls import local_proxy_root_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.version import package_version
from free_claude_code.harnesses.codex import CODEX_INSTALL_HINT, prepare_codex_launch
from free_claude_code.harnesses.codex_model_catalog import (
    CodexModel,
    codex_model_entry,
    project_codex_models,
)
from free_claude_code.harnesses.resources import LaunchResources

from .codex_protocol import (
    CodexProtocol,
    NativePrompt,
    object_value,
    string_value,
)


class CodexAppServer:
    def __init__(
        self,
        command: list[str],
        env: Mapping[str, str],
        cwd: str,
        sink: EventSink,
        *,
        model_slugs: Mapping[str, str] | None = None,
        fingerprints: Mapping[str, str] | None = None,
        reasoning: Mapping[str, bool] | None = None,
        resources: ExitStack | None = None,
    ) -> None:
        self.generation = str(uuid.uuid4())
        self.thread_id: str | None = None
        self._owned_threads: set[str] = set()
        self._command, self._env, self._cwd, self._sink = command, dict(env), cwd, sink
        self._model_slugs = dict(model_slugs or {})
        self._fingerprints = dict(fingerprints or {})
        self._reasoning = dict(reasoning or {})
        self._resources = resources or ExitStack()
        self._protocol = CodexProtocol(self.generation)
        self._pending: dict[str, tuple[str, asyncio.Future[JsonObject]]] = {}
        self._requests: dict[str | int, NativePrompt] = {}
        self._queue: asyncio.Queue[HarnessEvent | None] = asyncio.Queue()
        self._writer_lock = asyncio.Lock()
        self._process: asyncio.subprocess.Process | None = None
        self._reader: asyncio.Task[None] | None = None
        self._stderr: asyncio.Task[None] | None = None
        self._dispatcher: asyncio.Task[None] | None = None
        self._closing: asyncio.Task[None] | None = None
        self._reaping: asyncio.Task[None] | None = None
        self._alive = False
        self._stderr_tail = bytearray()

    @property
    def process(self) -> asyncio.subprocess.Process:
        if self._process is None:
            raise CodeUnavailableError("Codex has not started.")
        return self._process

    async def start(self) -> None:
        try:
            self._process = await asyncio.create_subprocess_exec(
                *self._command,
                cwd=self._cwd,
                env=self._env,
                stdin=asyncio.subprocess.PIPE,
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE,
                creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
                start_new_session=os.name != "nt",
            )
            register_pid(self._process.pid)
            self._alive = True
            self._reader = asyncio.create_task(self._read(), name="fcc-codex-jsonl")
            self._stderr = asyncio.create_task(
                self._read_stderr(), name="fcc-codex-stderr"
            )
            self._dispatcher = asyncio.create_task(
                self._dispatch(), name="fcc-codex-events"
            )
            await self.rpc(
                "initialize",
                {
                    "clientInfo": {
                        "name": "free_claude_code",
                        "title": "Free Claude Code",
                        "version": package_version(),
                    },
                    "capabilities": {
                        "experimentalApi": True,
                        "mcpServerOpenaiFormElicitation": False,
                    },
                },
            )
            await self._write({"method": "initialized", "params": {}})
        except BaseException:
            await self.close()
            raise

    def supports(self, selection: HarnessSelection) -> bool:
        return (
            self._alive
            and self._closing is None
            and self._fingerprints.get(selection.model) == selection.configuration_key
        )

    async def create_thread(self) -> NativeThread:
        response = await self.rpc(
            "thread/start", {"cwd": self._cwd, "modelProvider": "fcc"}
        )
        native = self._thread_with_permissions(response)
        self.thread_id = native.id
        return native

    async def resume_thread(self, thread_id: str) -> NativeThread:
        response = await self.rpc(
            "thread/resume",
            {"threadId": thread_id, "cwd": self._cwd, "modelProvider": "fcc"},
        )
        native = self._thread_with_permissions(response)
        self.thread_id = native.id
        return native

    async def read_thread(self, thread_id: str) -> NativeThread:
        return self._protocol.history(
            await self.rpc("thread/read", {"threadId": thread_id, "includeTurns": True})
        )

    def _thread_with_permissions(self, response: JsonObject) -> NativeThread:
        defaults = {
            key: response.get(key)
            for key in (
                "approvalPolicy",
                "approvalsReviewer",
                "activePermissionProfile",
                "sandbox",
            )
        }
        _permission_settings("config", defaults)
        return replace(self._protocol.history(response), permission_defaults=defaults)

    async def start_turn(
        self,
        text: str,
        selection: HarnessSelection,
        client_id: str,
        permission_defaults: JsonObject,
    ) -> str:
        model = self._model_slugs.get(selection.model)
        if not self.thread_id or model is None:
            raise CodeUnavailableError(
                "Codex is not prepared for the selected FCC model."
            )
        params: JsonObject = {
            "threadId": self.thread_id,
            "input": [{"type": "text", "text": text}],
            "clientUserMessageId": client_id,
            "model": model,
            **_permission_settings(selection.mode, permission_defaults),
        }
        if self._reasoning.get(selection.model, True):
            off = selection.reasoning_effort == "off"
            params["summary"] = "none" if off else "auto"
            params["effort"] = "none" if off else selection.reasoning_effort
        result = await self.rpc("turn/start", params)
        turn_id = string_value(object_value(result.get("turn")).get("id"))
        if not turn_id:
            raise CodeUnavailableError(
                "Codex did not return a turn ID; input was not resent."
            )
        return turn_id

    async def interrupt(self, turn_id: str) -> None:
        await self.rpc(
            "turn/interrupt", {"threadId": self.thread_id, "turnId": turn_id}
        )

    def prepare_answer(self, request_id: str | int, answer: JsonObject) -> JsonObject:
        prompt = self._requests.get(request_id)
        if prompt is None:
            raise CodeConflictError("This native prompt is no longer active.")
        return prompt.answer(answer)

    async def respond(self, request_id: str | int, response: JsonObject) -> None:
        async with self._writer_lock:
            if not self._alive or request_id not in self._requests:
                raise CodeConflictError("This native prompt is no longer active.")
            self._write_frame({"id": request_id, "result": response})
            self._requests.pop(request_id, None)
            assert self.process.stdin is not None
            await self.process.stdin.drain()

    async def delete_thread(self, thread_id: str) -> None:
        await self.rpc("thread/delete", {"threadId": thread_id})

    async def rpc(self, method: str, params: JsonObject) -> JsonObject:
        if not self._alive:
            raise CodeUnavailableError("The Codex connection is closed.")
        request_id = f"fcc-{uuid.uuid4()}"
        future: asyncio.Future[JsonObject] = asyncio.get_running_loop().create_future()
        # A cancelled caller does not erase the pending native response/identity.
        future.add_done_callback(
            lambda value: value.exception() if not value.cancelled() else None
        )
        self._pending[request_id] = method, future
        try:
            await self._write({"id": request_id, "method": method, "params": params})
            async with asyncio.timeout(30):
                return await asyncio.shield(future)
        except asyncio.CancelledError:
            raise
        except TimeoutError as exc:
            raise CodeUnavailableError(
                "Codex did not acknowledge the request. It was not resent."
            ) from exc

    async def _write(self, message: JsonObject) -> None:
        async with self._writer_lock:
            self._write_frame(message)
            assert self.process.stdin is not None
            await self.process.stdin.drain()

    def _write_frame(self, message: JsonObject) -> None:
        if not self._alive or self.process.stdin is None:
            raise CodeUnavailableError("The Codex connection is closed.")
        self.process.stdin.write(
            (json.dumps(message, ensure_ascii=False, allow_nan=False) + "\n").encode(
                "utf-8"
            )
        )

    async def _read(self) -> None:
        assert self.process.stdout is not None
        buffer = bytearray()
        message = "The Codex process ended."
        discarded_output: asyncio.Task[None] | None = None
        try:
            while chunk := await self.process.stdout.read(65536):
                buffer.extend(chunk)
                while (position := buffer.find(b"\n")) >= 0:
                    frame = bytes(buffer[:position])
                    del buffer[: position + 1]
                    if frame.strip():
                        await self._packet(
                            object_value(json.loads(frame.decode("utf-8")))
                        )
            if buffer.strip():
                raise ValueError("Incomplete native JSONL frame")
        except Exception as exc:
            message = f"The Codex connection failed ({type(exc).__name__})."
            discarded_output = asyncio.create_task(self._discard_stdout())
        finally:
            self._alive = False
            for _, future in self._pending.values():
                if not future.done():
                    future.set_exception(CodeUnavailableError(message))
            self._pending.clear()
            self._requests.clear()
            self._protocol.clear()
            # A failed pipe does not prove the native agent has stopped working.
            # Keep the session reserved until its owned process is actually gone.
            await self._reap_owned_process()
            if discarded_output is not None:
                await discarded_output
            self._queue.put_nowait(
                HarnessEvent(self.generation, self.thread_id, "closed", message=message)
            )
            self._queue.put_nowait(None)

    async def _discard_stdout(self) -> None:
        # Keep draining a failed protocol stream until EOF, so a full pipe
        # cannot block native shutdown or retain its subprocess transport.
        assert self.process.stdout is not None
        while await self.process.stdout.read(65536):
            pass

    async def _packet(self, packet: JsonObject) -> None:
        method = string_value(packet.get("method"))
        if not method:
            request_id = packet.get("id")
            pending = (
                self._pending.pop(request_id, None)
                if isinstance(request_id, str)
                else None
            )
            if pending is None:
                return
            operation, future = pending
            if future.done():
                return
            if "error" in packet:
                error = object_value(packet["error"])
                message = (
                    self._redact(string_value(error.get("message")))
                    or "Codex rejected the request."
                )
                if operation in {
                    "thread/read",
                    "thread/resume",
                    "thread/delete",
                } and any(
                    phrase in message.lower()
                    for phrase in (
                        "thread not found",
                        "thread does not exist",
                        "no rollout found",
                        "not found for thread",
                    )
                ):
                    future.set_exception(NativeHistoryMissing(message))
                elif error.get("code") == -32601:
                    future.set_exception(
                        CodeUnavailableError(
                            "This Codex version lacks the required app-server method. Update Codex."
                        )
                    )
                else:
                    future.set_exception(CodeConflictError(message))
                return
            result = object_value(packet.get("result"))
            if operation in {"thread/start", "thread/resume"}:
                identity = string_value(object_value(result.get("thread")).get("id"))
                if identity:
                    self.thread_id = identity
                    self._owned_threads.add(identity)
            future.set_result(result)
            return
        params = object_value(packet.get("params"))
        if method == "thread/started":
            thread = object_value(params.get("thread"))
            source = object_value(object_value(thread.get("source")).get("subAgent"))
            parent = object_value(source.get("thread_spawn")).get("parent_thread_id")
            child = string_value(thread.get("id"))
            if child and isinstance(parent, str) and parent in self._owned_threads:
                self._owned_threads.add(child)
            return
        request_id = packet.get("id")
        if isinstance(request_id, str | int) and not isinstance(request_id, bool):
            try:
                thread_id = string_value(params.get("threadId")) or self.thread_id
                if thread_id and thread_id not in self._owned_threads:
                    raise CodeValidationError(
                        "Codex requested input for a conversation outside this Code session."
                    )
                prompt = NativePrompt(method, request_id, params)
            except CodeValidationError as exc:
                await self._write(
                    {"id": request_id, "error": {"code": -32601, "message": str(exc)}}
                )
                self._queue.put_nowait(
                    HarnessEvent(
                        self.generation, self.thread_id, "error", message=str(exc)
                    )
                )
                return
            self._requests[request_id] = prompt
            request = prompt.request()
            if thread_id != self.thread_id:
                request = replace(
                    request,
                    turn_id=None,
                    form={
                        **request.form,
                        "detail": "A Codex subagent needs your input.\n"
                        + string_value(request.form.get("detail")),
                    },
                )
            self._queue.put_nowait(
                HarnessEvent(
                    self.generation,
                    self.thread_id,
                    "prompt",
                    turn_id=request.turn_id,
                    prompt=request,
                )
            )
            return
        event = self._protocol.notification(method, params)
        if event is not None:
            if event.kind == "resolved" and event.request_id is not None:
                self._requests.pop(event.request_id, None)
                if event.thread_id in self._owned_threads:
                    event = replace(event, thread_id=self.thread_id)
            if event.kind == "turn_completed":
                for key, prompt in tuple(self._requests.items()):
                    if (
                        prompt.params.get("turnId") == event.turn_id
                        and prompt.params.get("threadId") == event.thread_id
                    ):
                        self._requests.pop(key, None)
                        if (
                            event.thread_id != self.thread_id
                            and event.thread_id in self._owned_threads
                        ):
                            self._queue.put_nowait(
                                HarnessEvent(
                                    self.generation,
                                    self.thread_id,
                                    "resolved",
                                    request_id=key,
                                )
                            )
            self._queue.put_nowait(event)

    async def _dispatch(self) -> None:
        while (event := await self._queue.get()) is not None:
            review = event.item is not None and event.item.kind == "auto_review"
            if (
                event.thread_id is not None
                and event.thread_id != self.thread_id
                and (review or (event.kind == "notice" and event.message))
                and await self._owns_thread(event.thread_id)
            ):
                if review and event.item is not None:
                    identity = json.dumps(
                        [event.thread_id, event.item.raw["reviewId"]],
                        separators=(",", ":"),
                    )
                    event = replace(
                        event,
                        thread_id=self.thread_id,
                        item=replace(
                            event.item,
                            item_id=f"subagent-auto-review:{identity}",
                            kind="subagent_auto_review",
                            title=f"Sub-agent {event.item.title}",
                        ),
                    )
                else:
                    event = replace(
                        event,
                        thread_id=self.thread_id,
                        message=f"Sub-agent: {event.message}",
                    )
            await self._sink(event)

    async def _owns_thread(self, thread_id: str) -> bool:
        # Native child listeners can deliver reviews without thread/started.
        # Resolve ancestry from metadata, outside the reader that serves the RPC.
        ancestors: set[str] = set()
        while thread_id not in self._owned_threads:
            if thread_id in ancestors:
                return False
            ancestors.add(thread_id)
            try:
                result = await self.rpc(
                    "thread/read", {"threadId": thread_id, "includeTurns": False}
                )
            except (
                CodeConflictError,
                CodeUnavailableError,
                NativeHistoryMissing,
                OSError,
            ):
                return False
            thread = object_value(result.get("thread"))
            if thread.get("id") != thread_id:
                return False
            source = object_value(object_value(thread.get("source")).get("subAgent"))
            parent = string_value(
                object_value(source.get("thread_spawn")).get("parent_thread_id")
            )
            if not parent:
                return False
            thread_id = parent
        self._owned_threads.update(ancestors)
        return True

    async def _read_stderr(self) -> None:
        assert self.process.stderr is not None
        while chunk := await self.process.stderr.read(8192):
            self._stderr_tail.extend(chunk)
            del self._stderr_tail[:-16384]

    def _redact(self, text: str) -> str:
        for key, value in self._env.items():
            if value and any(
                part in key.upper()
                for part in ("TOKEN", "API_KEY", "PASSWORD", "SECRET")
            ):
                text = text.replace(value, "[redacted]")
        return text

    async def close(self) -> None:
        if asyncio.current_task() is self._dispatcher:
            await self._reap_owned_process()
            return
        if self._closing is None:
            self._closing = asyncio.create_task(
                self._close(),
                name="fcc-codex-close",
            )
        await asyncio.shield(self._closing)

    async def _close(self) -> None:
        await self._reap_owned_process()
        if self._reader is not None:
            await self._reader
        self._protocol.clear()
        if self._dispatcher is not None:
            await self._dispatcher

    async def _reap_owned_process(self) -> None:
        if self._reaping is None:
            self._reaping = asyncio.create_task(self._reap(), name="fcc-codex-reap")
        await asyncio.shield(self._reaping)

    async def _reap(self) -> None:
        process = self._process
        if process is not None:
            if process.stdin is not None:
                process.stdin.close()
            try:
                async with asyncio.timeout(5):
                    await process.wait()
            except TimeoutError:
                await self._kill_tree(process)
            if self._stderr is not None:
                await self._stderr
            unregister_pid(process.pid)
        self._alive = False
        self._resources.close()

    @staticmethod
    async def _kill_tree(process: asyncio.subprocess.Process) -> None:
        if process.returncode is not None:
            return
        if os.name == "nt":
            killer = await asyncio.create_subprocess_exec(
                "taskkill",
                "/PID",
                str(process.pid),
                "/T",
                "/F",
                stdout=asyncio.subprocess.DEVNULL,
                stderr=asyncio.subprocess.DEVNULL,
                creationflags=subprocess.CREATE_NO_WINDOW,
            )
            await killer.wait()
        else:
            with suppress(ProcessLookupError):
                os.killpg(process.pid, signal.SIGKILL)
        if process.returncode is None:
            with suppress(ProcessLookupError):
                process.kill()
        await process.wait()


@dataclass(frozen=True, slots=True)
class _CodexSelection:
    binary_path: str
    proxy_root_url: str
    base_env: Mapping[str, str] = field(repr=False)
    models: tuple[CatalogModel, ...]
    model: str
    configuration_key: str
    fingerprints: dict[str, str]
    reasoning_effort: str | None
    mode: CodeMode

    async def open(self, cwd: str, sink: EventSink) -> CodexAppServer:
        resources = ExitStack()
        try:
            prepared = prepare_codex_launch(
                binary_path=self.binary_path,
                proxy_root_url=self.proxy_root_url,
                model=self.model,
                models=self.models,
                base_env=self.base_env,
                args=[
                    "-c",
                    "features.default_mode_request_user_input=true",
                    "-c",
                    "tools.experimental_request_user_input.enabled=true",
                    "app-server",
                ],
                files=LaunchResources(resources),
            )
            connection = CodexAppServer(
                prepared.command,
                prepared.env,
                cwd,
                sink,
                model_slugs={
                    model.provider_model_ref: model.wire_slug for model in self.models
                },
                fingerprints=self.fingerprints,
                reasoning={
                    model.provider_model_ref: model.supports_reasoning is not False
                    for model in self.models
                },
                resources=resources,
            )
            await connection.start()
            return connection
        except BaseException:
            resources.close()
            raise


class CodexHarnessFactory:
    def __init__(
        self,
        runtime: RequestRuntimePort,
        *,
        binary: str | None = None,
        env: Mapping[str, str] | None = None,
    ) -> None:
        self._runtime, self._binary, self._env = runtime, binary, env

    def availability(self) -> tuple[bool, str | None]:
        if self._binary or shutil.which("codex"):
            return True, None
        return False, "Codex is not installed. " + CODEX_INSTALL_HINT

    def catalog(self) -> CodeCatalog:
        settings = self._runtime.current_settings()
        catalog = read_model_catalog(self._runtime, settings)
        return CodeCatalog(
            settings.model,
            tuple(
                _model_option(model) for model in project_codex_models(catalog.models)
            ),
        )

    async def prepare(
        self, model: str, reasoning_effort: str | None, mode: CodeMode
    ) -> _CodexSelection:
        binary = self._binary or shutil.which("codex")
        if binary is None:
            raise CodeUnavailableError("Codex is not installed. " + CODEX_INSTALL_HINT)
        snapshot = await self._runtime.wait_for_model_catalog(model)
        settings = snapshot.settings
        models = read_model_catalog(snapshot, settings).models
        projected = project_codex_models(models)
        selected = next(
            (
                candidate
                for candidate in projected
                if candidate.model.provider_model_ref == model
            ),
            None,
        )
        if selected is None:
            raise CodeValidationError(
                "This model is unavailable. Choose another model."
            )
        option = _model_option(selected)
        if (
            reasoning_effort is not None
            and reasoning_effort not in option.reasoning_efforts
        ):
            raise CodeValidationError(
                "This effort is unavailable. Choose another effort."
            )
        effort = reasoning_effort or option.default_reasoning_effort
        fingerprints = {
            entry.model.provider_model_ref: _fingerprint(codex_model_entry(entry))
            for entry in projected
        }
        return _CodexSelection(
            binary_path=binary,
            proxy_root_url=local_proxy_root_url(settings),
            base_env=dict(self._env if self._env is not None else os.environ),
            models=models,
            model=model,
            configuration_key=fingerprints[model],
            fingerprints=fingerprints,
            reasoning_effort=effort,
            mode=mode,
        )

    async def open_history(self, cwd: str, sink: EventSink) -> CodexAppServer:
        binary = self._binary or shutil.which("codex")
        if binary is None:
            raise CodeUnavailableError(
                "Codex is needed to remove its native conversation. "
                + CODEX_INSTALL_HINT
            )
        connection = CodexAppServer(
            [binary, "app-server"],
            dict(self._env if self._env is not None else os.environ),
            cwd,
            sink,
        )
        await connection.start()
        return connection


def _model_option(entry: CodexModel) -> CodeModel:
    model = entry.model
    provider_id, model_name = split_provider_model_ref(model.provider_model_ref)
    return CodeModel(
        id=model.provider_model_ref,
        display_name=model.display_name,
        provider_id=provider_id,
        model_name=model_name,
        reasoning_efforts=tuple(
            "off" if effort == "none" else effort for effort in entry.reasoning_levels
        )
        or ("off",),
        default_reasoning_effort=entry.default_reasoning_level or "off",
        context_window_tokens=model.context_window_tokens,
    )


def _permission_settings(mode: CodeMode, defaults: JsonObject) -> JsonObject:
    if mode != "config":
        return {
            "approvalPolicy": "never" if mode == "full_access" else "on-request",
            "approvalsReviewer": "auto_review" if mode == "auto_review" else "user",
            "permissions": ":danger-full-access"
            if mode == "full_access"
            else ":workspace",
        }
    policy = defaults.get("approvalPolicy")
    reviewer = string_value(defaults.get("approvalsReviewer"))
    profile = string_value(
        object_value(defaults.get("activePermissionProfile")).get("id")
    )
    sandbox = object_value(defaults.get("sandbox"))
    if (
        not isinstance(policy, str | dict)
        or not policy
        or not reviewer
        or (not profile and not sandbox.get("type"))
    ):
        raise CodeUnavailableError(
            "Codex did not return complete native permission settings. Your input was not sent."
        )
    return {
        "approvalPolicy": policy,
        "approvalsReviewer": reviewer,
        **({"permissions": profile} if profile else {"sandboxPolicy": sandbox}),
    }


def _fingerprint(entry: JsonObject) -> str:
    behavior = {
        key: value
        for key, value in entry.items()
        if key not in {"display_name", "description", "priority", "visibility"}
    }
    return hashlib.sha256(
        json.dumps(behavior, sort_keys=True, ensure_ascii=True).encode()
    ).hexdigest()