Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

23.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Codex `image_gen` provider (ChatGPT OAuth, no API key).

Ported from the standalone `image-gen` skill (MIT, aldegad/image-gen). codex
does not persist a discrete file; `image_gen` returns the PNG **inline as base64**
inside the session rollout jsonl. We spawn a fresh `codex exec` in an empty
sandbox (fresh session breaks OpenAI's prompt cache so repeat prompts don't drag
in a previous image), parse the session id from stdout, then decode the inline
base64 deterministically. The model-reported path is never trusted.

Decisive flags (each verified in the image-gen skill):
- `--sandbox workspace-write`  image_gen needs write access, else the tool never registers.
- `--add-dir <Codex state root>/generated_images`  not in the default writable set; the root is `CODEX_HOME` when set and `~/.codex` otherwise.
- `--skip-git-repo-check`  the sandbox dir is not a git repo.
- NO `--ephemeral`  the session jsonl must survive on disk so we can extract from it.

How codex is signed in is one question, `codex_login`, asked by every caller: the default
provider resolution, `generate`, the facing check and the guided workflow. Signed in with
ChatGPT it runs on the subscription; signed in with an API key it bills that key per call,
said on stderr before the request leaves like every metered route (`announce_api_billing`).
Whether `codex exec` ended on codex's usage limit is the other, `usage_limit`: a codex that is
not signed in or whose usage is used up is what a call that names no provider turns into the
user's choice (`gen.run_on_default`).
"""

from __future__ import annotations

import base64
import json
import os
import re
import subprocess
import time
from dataclasses import dataclass
from pathlib import Path

from .base import (
    GEN_TIMEOUT_SECONDS,
    LOGINS_OFF,
    PROVIDER_CODEX,
    TRANSPARENCY_NATIVE,
    announce_api_billing,
    GenRequest,
    GenTimeoutError,
    ProviderRun,
    logins_on,
    provider_binary,
    provider_subprocess_env,
    verify_png,
)

AUTH_SOURCE_LOGIN = "codex-login"  # signed in with ChatGPT: the subscription
AUTH_SOURCE_API_KEY = "codex-api-key"  # signed in with an API key: billed per call
LOGIN_PROBE_TIMEOUT_SECONDS = 15
BINARY = "codex"
LOGIN_HINT = "`codex login` signs your ChatGPT subscription in"


# What `codex exec` says when the codex usage of the account behind it is used up (2026-10-16, codex-rs source at
# rust-v0.160.1 and rust-v0.153.4). codex classes three of its errors as its usage limit
# (`CodexErr::to_codex_protocol_error` -> `CodexErrorInfo::UsageLimitExceeded`, codex-rs/protocol/src/error.rs):
# `UsageLimitReached` (a 429 `usage_limit_reached`; its message names the plan, a workspace out of credits or a
# spend cap), `QuotaExceeded` (a 429 `insufficient_quota` and its billing codes) and `UsageNotIncluded` (a 429
# `usage_not_included`). That class reaches `codex exec --json` only as the message text: the `error` and
# `turn.failed` events carry `message` alone (codex-rs/exec/src/event_processor_with_jsonl_output.rs, exec_events.rs),
# the error event is not kept in the rollout (codex-rs/rollout/src/policy.rs), and codex exits 1. So the signal is
# the start of each message, as codex's own tests pin it (codex-rs/protocol/src/error_tests.rs); 0.160.1 writes the
# apostrophe of "You've" as U+2019, 0.153.4 as an ASCII one. A message is matched anywhere in what codex said,
# since a remote compaction puts its own words before it. No other failure is read as the usage limit.
USAGE_LIMIT_MESSAGES = (
    "You've hit your usage limit",  # UsageLimitReached, codex 0.153.4 and before
    "You’ve hit your usage limit",  # UsageLimitReached, codex 0.160.1
    "Your workspace is out of credits.",  # UsageLimitReached, a workspace's credits
    "You hit your spend cap set",  # UsageLimitReached, a workspace's spend cap
    "Quota exceeded. Check your plan and billing details.",  # QuotaExceeded
    "To use Codex with your ChatGPT plan, upgrade to Plus",  # UsageNotIncluded
)


def usage_limit(said: list[str]) -> str | None:
    """The first of what codex said (`_extract_stream_errors`) that is its usage limit (USAGE_LIMIT_MESSAGES), or
    None."""
    return next((message for message in said if any(words in message for words in USAGE_LIMIT_MESSAGES)), None)


class CodexUsageLimit(SystemExit):
    """`codex exec` ended on its usage limit. The failure of a named `--provider codex` as before (same message,
    exit 1); a call that named no provider turns it into the user's choice (`gen.run_on_default`). `said` is codex's
    message."""

    def __init__(self, message: str, said: str) -> None:
        super().__init__(message)
        self.said = said


@dataclass(frozen=True)
class CodexLogin:
    source: str | None  # AUTH_SOURCE_LOGIN | AUTH_SOURCE_API_KEY | None (not usable here)
    reason: str = ""  # why it is not usable


def codex_login() -> CodexLogin:
    """How `codex` is signed in here, by `codex login status`: exit 0 and "ChatGPT" in what it
    says is the subscription; exit 0 otherwise is signed in with an API key. No CLI, a probe that
    fails or does not answer, and a non-zero exit are not usable, with the reason. What the CLI
    says is never repeated: an API-key login can name its key. With SPRITE_GEN_LOGINS=off codex is
    not asked and is not usable: its login is all it runs on."""
    if not logins_on():
        return CodexLogin(None, LOGINS_OFF)
    binary = provider_binary(BINARY)
    try:
        completed = subprocess.run([binary, "login", "status"], capture_output=True, text=True, encoding="utf-8",
                                   errors="replace", env=provider_subprocess_env(),
                                   timeout=LOGIN_PROBE_TIMEOUT_SECONDS)
    except FileNotFoundError:
        return CodexLogin(None, "codex CLI not found on PATH")
    except (OSError, subprocess.SubprocessError) as exc:
        return CodexLogin(None, f"codex login-status probe failed: {type(exc).__name__}")
    if completed.returncode != 0:
        return CodexLogin(None, f"codex not logged in (codex login status exit {completed.returncode})")
    said = (completed.stdout + completed.stderr).lower()
    return CodexLogin(AUTH_SOURCE_LOGIN if "chatgpt" in said else AUTH_SOURCE_API_KEY)


def announce_codex_billing(login: CodexLogin, what: str = "") -> None:
    """The stderr charge line for a codex signed in with an API key; nothing on the subscription."""
    if login.source == AUTH_SOURCE_API_KEY:
        announce_api_billing("codex", "the API key codex is signed in with", f"{what} — {LOGIN_HINT}.")


# codex carries the inline base64 on a version-specific record. All are
# first-class canonical records (not fallbacks) — read whichever the running
# codex emits. v0.140.0: response_item `image_generation_call`. v0.144.1:
# event_msg `image_generation_end` (+status, saved_path — saved_path untrusted).
# v0.149.1: event_msg `item_completed` wrapping an Extension item with kind
# `image_gen.generation`.
_RESULT_TYPES = ("image_generation_call", "image_generation_end")
_IMAGE_GEN_EXTENSION_KIND = "image_gen.generation"
# The session id that names the rollout jsonl. v0.144.1 `codex exec --json` emits
# it as `{"type":"thread.started","thread_id":"<uuid>"}` on stdout; older codex
# printed a `session id: <uuid>` text line. Both are canonical per version.
_SID_RE = re.compile(r"session id: ([0-9a-f-]+)")
# The official way to invoke a codex skill explicitly is the `$<skill>` prompt
# mention, and image generation lives in the bundled `imagegen` system skill
# (`<Codex state root>/skills/.system/imagegen/agents/openai.yaml` ships
# `default_prompt: "Use $imagegen to make or edit an image for this project."`).
# We state the trigger rather than describing the tool in prose so the invocation
# contract is explicit and single-owned here.
#
# Scope of the trigger: naming the skill does not create the tool. Whether the
# built-in `image_gen` tool is offered to the session at all is a capability of
# the account behind the active Codex state root (see `_no_image_records_message`),
# so this trigger is an alignment with the official invocation contract, not a fix
# for a session that is never offered the tool.
_SKILL_TRIGGER = "$imagegen"
# Native transparency (2026-09-08 실측, codex 0.153.4): the bundled `imagegen` skill
# says "For transparent images, ask built-in image_gen for a transparent background
# and preserve the generated alpha", and the completed `image_gen.generation` item
# reports `transparentBackground: true` next to the real RGBA PNG. There is no
# tool parameter — the request rides on the prompt, so this adapter owns the
# exact wording (the caller's prompt is still passed through verbatim).
_NATIVE_ALPHA_INSTRUCTION = (
    "배경은 진짜 투명(알파 채널이 있는 PNG)으로 만들어라 — image_gen 에 transparent "
    "background 를 요청하고 생성된 알파를 그대로 보존해라. 체커보드 무늬·흰색·단색 배경을 "
    "그림으로 그려 넣는 것은 금지다."
)


@dataclass(frozen=True)
class InlineResult:
    """One completed image_gen call as recorded in the rollout."""

    result: str  # inline base64 PNG
    # `transparentBackground` as codex reported it (0.149+ Extension item);
    # None when the record type does not carry the field. Reported, never trusted —
    # the orchestrator measures the decoded PNG's alpha itself.
    transparent_background: bool | None = None


def _parse_session_id(stdout: str) -> str | None:
    for line in stdout.splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            event = json.loads(line)
        except json.JSONDecodeError:
            continue
        if isinstance(event, dict) and event.get("thread_id"):
            return str(event["thread_id"])
    hits = _SID_RE.findall(stdout)
    return hits[-1] if hits else None


def _extract_stream_errors(stdout: str) -> list[str]:
    """Pull the human-readable failure cause out of the `codex exec --json` stream.

    codex reports a fatal error (e.g. an unsupported model) as a `turn.failed` or
    top-level `error` event on **stdout**, not stderr — so surfacing only the exit
    code and stderr leaves the real reason invisible. Unwraps the API error JSON
    that codex nests inside `message`."""
    msgs: list[str] = []
    for line in stdout.splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            event = json.loads(line)
        except json.JSONDecodeError:
            continue
        if not isinstance(event, dict):
            continue
        if event.get("type") == "turn.failed":
            raw = (event.get("error") or {}).get("message")
        elif event.get("type") == "error":
            raw = event.get("message")
        else:
            continue
        if not raw:
            continue
        text = raw
        try:
            inner = json.loads(raw)
            if isinstance(inner, dict):
                text = (inner.get("error") or {}).get("message") or inner.get("message") or raw
        except (json.JSONDecodeError, TypeError):
            pass
        text = str(text).strip()
        if text and text not in msgs:
            msgs.append(text)
    return msgs


def _resolve_codex_home() -> Path:
    """Return the one state root used by both the Codex child and this adapter."""
    configured = os.environ.get("CODEX_HOME")
    if configured is None:
        return Path.home() / ".codex"
    if not configured.strip():
        raise SystemExit("codex-gen: CODEX_HOME is set but empty; refusing to use the default root")
    return Path(configured).expanduser().resolve()


def _rollout_files(sessions_root: Path) -> tuple[Path, ...]:
    """List rollout files deterministically without following a second state root."""
    if not sessions_root.exists():
        return ()
    if not sessions_root.is_dir():
        raise SystemExit(f"codex-gen: Codex sessions root is not a directory: {sessions_root}")
    try:
        return tuple(
            sorted(
                (path.resolve() for path in sessions_root.rglob("rollout-*.jsonl") if path.is_file()),
                key=lambda path: str(path),
            )
        )
    except OSError as exc:
        raise SystemExit(f"codex-gen: cannot scan Codex sessions root {sessions_root}: {exc}") from exc


def _resolve_rollout(
    session_id: str,
    sessions_root: Path,
    *,
    preexisting: set[Path] | frozenset[Path] | None = None,
) -> Path:
    """Resolve exactly one newly-created rollout for one Codex session."""
    suffix = f"-{session_id}.jsonl"
    hits = [path for path in _rollout_files(sessions_root) if path.name.endswith(suffix)]
    if not hits:
        raise SystemExit(
            f"codex-gen: no rollout jsonl for session {session_id!r} under {sessions_root}"
        )
    if len(hits) > 1:
        rendered = "\n".join(f"  - {path}" for path in hits)
        raise SystemExit(
            f"codex-gen: multiple rollout jsonl files for session {session_id!r} under "
            f"{sessions_root}; refusing to choose by mtime:\n{rendered}"
        )
    rollout = hits[0]
    stale = {path.resolve() for path in (preexisting or ())}
    if rollout in stale:
        raise SystemExit(
            f"codex-gen: pre-existing stale rollout for session {session_id!r}: {rollout}"
        )
    return rollout


def _collect_inline_results(rollout: Path) -> list[InlineResult]:
    results: list[InlineResult] = []
    with rollout.open(encoding="utf-8") as handle:
        for line in handle:
            line = line.strip()
            if not line:
                continue
            try:
                record = json.loads(line)
            except json.JSONDecodeError:
                continue
            payload = record.get("payload", {}) or {}
            if payload.get("type") == "item_completed":
                item = payload.get("item", {}) or {}
                if item.get("type") != "Extension" or item.get("kind") != _IMAGE_GEN_EXTENSION_KIND:
                    continue
                status = item.get("status")
                if status != "completed":
                    raise SystemExit(
                        f"codex-gen: image_gen call ended with status={status!r} in {rollout}"
                    )
                result = item.get("result")
                if not result:
                    raise SystemExit(
                        f"codex-gen: completed image_gen call has no result in {rollout}"
                    )
                reported = item.get("transparentBackground")
                results.append(
                    InlineResult(
                        result=result,
                        transparent_background=reported if isinstance(reported, bool) else None,
                    )
                )
                continue
            if payload.get("type") not in _RESULT_TYPES or not payload.get("result"):
                continue
            status = payload.get("status")
            if status is not None and status != "completed":
                raise SystemExit(f"codex-gen: image_gen call ended with status={status!r} in {rollout}")
            results.append(InlineResult(result=payload["result"]))
    return results


def _decode_png(b64: str, dest: Path) -> None:
    raw = base64.b64decode(b64)
    dest.parent.mkdir(parents=True, exist_ok=True)
    dest.write_bytes(raw)
    verify_png(dest)


def _build_prompt(user_prompt: str, *, native_alpha: bool = False) -> str:
    """Wrap the caller's prompt in the transport-level skill trigger.

    The sprite-request prompt is the caller's SSoT and is passed through verbatim;
    this adapter is the one place that owns the codex invocation contract. With
    `native_alpha` the transport also carries the transparent-background request
    (`_NATIVE_ALPHA_INSTRUCTION`) — that is how image_gen is told to return alpha.
    """
    alpha_line = f"{_NATIVE_ALPHA_INSTRUCTION}\n" if native_alpha else ""
    return (
        f"{_SKILL_TRIGGER} 스킬로 built-in image_gen 도구를 정확히 1번 호출해서 "
        "다음 프롬프트의 이미지 1장만 생성해줘.\n"
        "미리보기 전용이라 생성된 파일은 기본 경로에 그대로 두면 된다.\n"
        "파일 저장·이동·복사·셸 명령·코드 작성·경로 보고 전부 금지. 생성만 하고 끝.\n"
        f"{alpha_line}\n"
        "프롬프트:\n"
        f"{user_prompt}\n"
    )


def _no_image_records_message(rollout: Path, codex_home: Path) -> str:
    """State an empty rollout as a capability failure, not a list of guesses.

    Built-in image generation is a capability of the account behind the active
    Codex state root. When the session is not offered the tool, it cannot be
    talked into it: not by the prompt, not by the model, and not by a config
    toggle. The only remedy is to run against a state root whose account provides
    it, so that is what this message says.
    """
    return (
        "codex-gen: the built-in image_gen tool never ran in this codex session — "
        f"zero {' / '.join((*_RESULT_TYPES, _IMAGE_GEN_EXTENSION_KIND))} records in {rollout}\n"
        f"  the prompt carries the official {_SKILL_TRIGGER} skill trigger, so the tool was "
        "not offered to the session rather than merely not chosen.\n"
        f"  the account behind this Codex state root ({codex_home}) does not provide the "
        "built-in image_gen capability.\n"
        "  select a Codex state root whose account provides it (`codex login status`), or "
        "generate with another provider. A config feature toggle does not grant it."
    )


class CodexProvider:
    """Generate one image through codex `image_gen`."""

    name = PROVIDER_CODEX
    transparency = TRANSPARENCY_NATIVE

    def __init__(self, *, keep_session: bool = False) -> None:
        self.keep_session = keep_session

    def inspect_facing(self, path: Path, workdir: Path) -> tuple[str, dict]:
        from .facing_vision import codex_inspect
        return codex_inspect(path, workdir)

    def inspect_image(self, path: Path, workdir: Path, prompt: str, *, label: str = "vision check") -> tuple[str, dict]:
        from .facing_vision import CODEX_READ_EFFORT, CODEX_READ_MODEL, codex_inspect
        return codex_inspect(path, workdir, prompt=prompt, label=label, model=CODEX_READ_MODEL,
                             effort=CODEX_READ_EFFORT)

    def generate(self, request: GenRequest, workdir: Path) -> ProviderRun:
        # `image_gen` exposes no effort or size dial, so neither knob is carried
        # into the prompt. Refusing beats returning a default-effort image under a
        # level the caller chose and believes they got (No Silent Fallback).
        for flag, value in (("--quality", request.quality), ("--resolution", request.resolution)):
            if value is not None:
                raise SystemExit(
                    f"codex-gen: {flag} is not carried into codex image_gen; "
                    "drop it or use --provider openai"
                )
        if not logins_on():
            raise SystemExit(f"codex-gen: {LOGINS_OFF}; codex runs on its own login only — "
                             "name --provider openai or grok, which run on an API key")
        codex_home = _resolve_codex_home()
        if not codex_home.is_dir():
            raise SystemExit(
                f"codex-gen: Codex state root does not exist or is not a directory: {codex_home}"
            )
        login = codex_login()
        if login.source is None:
            raise SystemExit(f"codex-gen: {login.reason}; {LOGIN_HINT}")
        announce_codex_billing(login)
        sessions_root = codex_home / "sessions"
        preexisting_rollouts = set(_rollout_files(sessions_root))
        gen_dir = codex_home / "generated_images"
        try:
            gen_dir.mkdir(parents=True, exist_ok=True)
        except OSError as exc:
            raise SystemExit(f"codex-gen: cannot create Codex generated-images dir {gen_dir}: {exc}") from exc
        cmd = [
            provider_binary(BINARY),
            "exec",
            "--json",
            "--sandbox",
            "workspace-write",
            "--skip-git-repo-check",
            "--color",
            "never",
            "--add-dir",
            str(gen_dir),
            "-C",
            str(workdir),
        ]
        if request.model:
            cmd += ["--model", request.model]
        for ref in request.refs:
            cmd += ["-i", str(Path(ref).expanduser().resolve())]
        cmd += ["-", ]

        prompt = _build_prompt(request.prompt, native_alpha=request.native_alpha)
        started = time.monotonic()
        child_env = provider_subprocess_env()
        if "CODEX_HOME" in os.environ:
            child_env["CODEX_HOME"] = str(codex_home)
        # A headless provider must not inherit parent orchestration identity or
        # lifecycle controls (see base.provider_subprocess_env).
        try:
            completed = subprocess.run(
                cmd, input=prompt, capture_output=True, text=True, encoding="utf-8", env=child_env,
                timeout=GEN_TIMEOUT_SECONDS,
            )
        except subprocess.TimeoutExpired:
            raise GenTimeoutError(
                f"codex-gen: no completion within {GEN_TIMEOUT_SECONDS}s — "
                "provider stream stalled; child killed (gen-timeout)")
        elapsed = time.monotonic() - started
        stdout = completed.stdout or ""
        if completed.returncode != 0:
            stream_errors = _extract_stream_errors(stdout)
            tail = (completed.stderr or "").strip().splitlines()[-20:]
            detail = "\n".join(stream_errors + tail).strip() or "(no error detail on stdout/stderr)"
            message = f"codex-gen: codex exec exited {completed.returncode}\n{detail}"
            said = usage_limit(stream_errors)
            raise CodexUsageLimit(message, said) if said else SystemExit(message)

        session_id = _parse_session_id(stdout)
        if not session_id:
            raise SystemExit(
                "codex-gen: no thread/session id in codex stdout — image_gen was not reached.\n"
                "  check `codex login status` and `--sandbox workspace-write`."
            )
        rollout = _resolve_rollout(
            session_id,
            sessions_root,
            preexisting=preexisting_rollouts,
        )
        results = _collect_inline_results(rollout)
        if not results:
            raise SystemExit(_no_image_records_message(rollout, codex_home))
        final = results[-1]
        _decode_png(final.result, request.raw)

        if not self.keep_session:
            try:
                rollout.unlink()
            except OSError as exc:
                raise SystemExit(f"codex-gen: failed to remove consumed rollout {rollout}: {exc}") from exc

        return ProviderRun(
            provider=self.name,
            elapsed_seconds=elapsed,
            model=request.model,
            session_id=session_id,
            extra={
                "auth_source": login.source,
                "inline_results": len(results),
                "rollout_cleaned": not self.keep_session,
                # codex's own claim about the output; the orchestrator measures
                # the real alpha and publishes that, not this flag.
                "transparent_background_reported": final.transparent_background,
            },
        )