code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/chatgpt_oauth/IMAGEGEN_SKILL.md

@@ -0,0 +1,83 @@
+---
+name: codex-imagegen
+description: Generate raster images with gpt-image-2 through Codex OAuth. Activate when the user asks to create a photo, illustration, icon, sprite, texture, product image, banner, or other raster artwork.
+version: "1.0"
+author: code-puppy
+tags:
+  - image-generation
+  - codex
+  - gpt-image
+  - artwork
+---
+
+# Codex Image Generation
+
+Use the `codex_imagegen` tool when the user asks you to create raster artwork.
+The tool uses `gpt-image-2` through the user's existing Codex OAuth session,
+saves the resulting PNG, and displays it inline when iTerm2 supports doing so.
+
+## Decision rules
+
+1. Generate an image when creation of a photo, illustration, icon, sprite,
+   texture, product image, banner, concept art, or similar raster asset is an
+   explicit part of the user's request.
+2. Do not generate an image merely because one might decorate an otherwise
+   unrelated answer.
+3. Prefer ordinary code tools for diagrams that should remain editable as
+   source, such as Mermaid, SVG, charts, or HTML/CSS layouts.
+4. Before calling the tool, turn the user's request into a complete standalone
+   visual prompt. Include subject, composition, style, lighting, colors,
+   perspective, mood, and important exclusions when those details are known.
+5. Do not claim that generation succeeded until the tool returns `success: true`.
+6. Report the saved path after success. The image may already be visible inline,
+   so do not redundantly embed it unless the user asks.
+7. If authentication is missing, tell the user to run `/codex-auth`.
+
+## Reference images (visual consistency)
+
+Pass `reference_images` to condition the result on images that already exist,
+instead of generating from text alone. Use it whenever the output has to stay
+visually consistent with something:
+
+- **Same character across many images.** Conditioning on one canonical
+  reference holds a face/outfit together far better than re-describing it in
+  words. This is the reliable way to produce a set of portraits, expressions,
+  or poses that are recognizably the same person.
+- **Matching an established style,** palette, or lighting across a set of
+  assets.
+- **Iterating on an existing asset** — "same logo, dark background".
+
+When references are supplied, write the `prompt` as the CHANGE you want; the
+references supply the subject and style to preserve.
+
+```text
+codex_imagegen(
+    prompt="Same man, same clothing and lighting, now glancing over his shoulder, anxious",
+    reference_images=["portraits/sandoval/_ref.png"],
+)
+```
+
+Guidance:
+
+1. Prefer one strong reference over several weak ones; extra references dilute
+   the conditioning.
+2. Do not re-describe what the reference already shows unless you want it
+   changed — describing the face again can fight the reference.
+3. Paths must exist and be readable image files, else the call fails with a
+   clear error.
+
+## Tool
+
+Call:
+
+```text
+codex_imagegen(prompt="A complete standalone image prompt")
+codex_imagegen(prompt="The change you want", reference_images=["path/to/ref.png"])
+```
+
+The result contains:
+
+- `success`: whether generation completed
+- `path`: saved PNG path on success
+- `displayed_inline`: whether iTerm2 inline display was attempted successfully
+- `error`: safe failure text when generation fails

code_puppy_core_plugins/chatgpt_oauth/__init__.py

@@ -0,0 +1,8 @@
+"""ChatGPT OAuth plugin package."""
+
+from __future__ import annotations
+
+from . import register_callbacks  # noqa: F401
+from .oauth_flow import run_oauth_flow
+
+__all__ = ["run_oauth_flow"]

code_puppy_core_plugins/chatgpt_oauth/config.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+from typing import Any, Dict
+
+from code_puppy import config
+
+# ChatGPT OAuth configuration based on OpenAI's Codex CLI flow
+CHATGPT_OAUTH_CONFIG: Dict[str, Any] = {
+    # OAuth endpoints from OpenAI auth service
+    "issuer": "https://auth.openai.com",
+    "auth_url": "https://auth.openai.com/oauth/authorize",
+    "token_url": "https://auth.openai.com/oauth/token",
+    # API endpoints - Codex uses chatgpt.com backend, not api.openai.com
+    "api_base_url": "https://chatgpt.com/backend-api/codex",
+    # OAuth client configuration for Code Puppy
+    "client_id": "app_EMoamEEZ73f0CkXaXp7hrann",
+    "scope": "openid profile email offline_access",
+    # Callback handling (we host a localhost callback to capture the redirect)
+    "redirect_host": "http://localhost",
+    "redirect_path": "auth/callback",
+    "required_port": 1455,
+    "callback_timeout": 120,
+    # Local configuration (uses XDG_DATA_HOME)
+    "token_storage": None,  # Set dynamically in get_token_storage_path()
+    # Model configuration
+    "prefix": "codex-",
+    "default_context_length": 272000,
+    "api_key_env_var": "CHATGPT_OAUTH_API_KEY",
+    # Codex CLI version info (for User-Agent header)
+    "client_version": "0.144.1",
+    "originator": "codex_cli_rs",
+}
+
+
+def get_token_storage_path() -> Path:
+    """Get the path for storing OAuth tokens (uses XDG_DATA_HOME)."""
+    data_dir = Path(config.DATA_DIR)
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return data_dir / "chatgpt_oauth.json"
+
+
+def get_config_dir() -> Path:
+    """Get the Code Puppy configuration directory (uses XDG_CONFIG_HOME)."""
+    config_dir = Path(config.CONFIG_DIR)
+    config_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return config_dir
+
+
+def get_chatgpt_models_path() -> Path:
+    """Get the path to the dedicated chatgpt_models.json file (uses XDG_DATA_HOME)."""
+    data_dir = Path(config.DATA_DIR)
+    data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return data_dir / "chatgpt_models.json"

code_puppy_core_plugins/chatgpt_oauth/image_generation.py

@@ -0,0 +1,253 @@
+"""Image generation through the ChatGPT Codex OAuth backend.
+
+Two endpoints are used, both on the Codex backend rather than api.openai.com:
+
+``POST /images/generations``
+    Plain text-to-image. JSON body ``{model, prompt, size, quality,
+    background}``.
+
+``POST /images/edits``
+    Reference-conditioned generation — the model sees one or more input images
+    and preserves their subject/style. JSON body ``{model, prompt, images,
+    size, quality}`` where ``images`` is a list of OBJECTS, each with exactly
+    one accepted key, ``image_url``, holding a base64 data-URL string::
+
+        {"images": [{"image_url": "data:image/png;base64,iVBORw0..."}]}
+
+.. note::
+   This endpoint is undocumented and its request shape was derived empirically
+   against the live service (2026-07). Deviations are rejected with HTTP 400:
+   a singular ``image`` key reports "Missing required parameter: 'images'";
+   bare base64 strings report "expected an object, but got a string";
+   ``url`` / ``b64_json`` / ``data`` / ``type`` object keys report "Unknown
+   parameter"; and multipart/form-data uploads (the shape the public OpenAI
+   images API uses) are rejected outright. If reference conditioning starts
+   failing, re-probe those variants first — and note that unknown keys on
+   ``/images/generations`` are silently IGNORED rather than rejected, so a
+   wrong shape there fails open as an unconditioned image.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import mimetypes
+import os
+import sys
+import uuid
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+import requests
+
+from code_puppy import config
+from code_puppy.i18n import t
+
+from .config import CHATGPT_OAUTH_CONFIG
+from .utils import get_valid_access_token, load_stored_tokens
+
+_IMAGE_MODEL = "gpt-image-2"
+_REQUEST_TIMEOUT_SECONDS = 180
+
+# Guard against pathologically large payloads: references are inlined as base64
+# data URLs, so a huge file becomes a huge request body.
+_MAX_REFERENCE_BYTES = 20 * 1024 * 1024
+
+
+class CodexImageGenerationError(RuntimeError):
+    """A safe, user-displayable image generation failure."""
+
+
+def generate_image(
+    prompt: str, reference_images: Sequence[str | Path] | None = None
+) -> Path:
+    """Generate one image with Codex OAuth and save it under Code Puppy data.
+
+    Args:
+        prompt: The image description.
+        reference_images: Optional paths to existing images. When provided, the
+            request goes to ``/images/edits`` and the model conditions on them,
+            preserving subject identity and style far better than describing the
+            subject in words. When omitted, behavior is unchanged: a plain
+            text-to-image call to ``/images/generations``.
+
+    Returns:
+        Path to the saved PNG.
+    """
+    normalized_prompt = prompt.strip()
+    if not normalized_prompt:
+        raise CodexImageGenerationError(t("codex.imagegen.prompt_required"))
+
+    access_token = get_valid_access_token()
+    tokens = load_stored_tokens() or {}
+    account_id = str(tokens.get("account_id", "")).strip()
+    if not access_token or not account_id:
+        raise CodexImageGenerationError(t("codex.imagegen.auth_required"))
+
+    encoded_references = _encode_references(reference_images or ())
+    response = _post_generation_request(
+        access_token, account_id, normalized_prompt, encoded_references
+    )
+    image_bytes = _decode_first_image(response)
+    return _save_image(image_bytes)
+
+
+def _encode_references(paths: Iterable[str | Path]) -> list[str]:
+    """Read reference images and return them as base64 data-URL strings."""
+    encoded: list[str] = []
+    for raw in paths:
+        path = Path(raw).expanduser()
+        if not path.is_file():
+            raise CodexImageGenerationError(
+                t("codex.imagegen.reference_missing", path=str(path))
+            )
+        try:
+            data = path.read_bytes()
+        except OSError as exc:
+            raise CodexImageGenerationError(
+                t("codex.imagegen.reference_unreadable", path=str(path))
+            ) from exc
+        if len(data) > _MAX_REFERENCE_BYTES:
+            raise CodexImageGenerationError(
+                t("codex.imagegen.reference_too_large", path=str(path))
+            )
+        mime, _ = mimetypes.guess_type(str(path))
+        if not (mime or "").startswith("image/"):
+            mime = "image/png"
+        b64 = base64.b64encode(data).decode("ascii")
+        encoded.append(f"data:{mime};base64,{b64}")
+    return encoded
+
+
+def _post_generation_request(
+    access_token: str,
+    account_id: str,
+    prompt: str,
+    reference_data_urls: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    base_url = str(CHATGPT_OAUTH_CONFIG["api_base_url"]).rstrip("/")
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "ChatGPT-Account-Id": account_id,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "originator": CHATGPT_OAUTH_CONFIG.get("originator", "codex_cli_rs"),
+        "User-Agent": (
+            f"{CHATGPT_OAUTH_CONFIG.get('originator', 'codex_cli_rs')}/"
+            f"{CHATGPT_OAUTH_CONFIG.get('client_version', 'unknown')}"
+        ),
+    }
+    if reference_data_urls:
+        # Reference-conditioned edit: `images` entries must be `{"image_url": ...}`
+        # objects only; `background` isn't accepted on this endpoint.
+        endpoint = "/images/edits"
+        payload = {
+            "prompt": prompt,
+            "model": _IMAGE_MODEL,
+            "images": [{"image_url": url} for url in reference_data_urls],
+            "quality": "auto",
+            "size": "auto",
+        }
+    else:
+        endpoint = "/images/generations"
+        payload = {
+            "prompt": prompt,
+            "background": "auto",
+            "model": _IMAGE_MODEL,
+            "quality": "auto",
+            "size": "auto",
+        }
+
+    try:
+        response = requests.post(
+            f"{base_url}{endpoint}",
+            headers=headers,
+            json=payload,
+            timeout=_REQUEST_TIMEOUT_SECONDS,
+        )
+        response.raise_for_status()
+        body = response.json()
+    except requests.RequestException as exc:
+        detail = _response_error_detail(getattr(exc, "response", None))
+        suffix = f": {detail}" if detail else ""
+        raise CodexImageGenerationError(
+            t("codex.imagegen.request_failed", detail=suffix)
+        ) from exc
+    except ValueError as exc:
+        raise CodexImageGenerationError(t("codex.imagegen.invalid_json")) from exc
+
+    if not isinstance(body, dict):
+        raise CodexImageGenerationError(t("codex.imagegen.invalid_response"))
+    return body
+
+
+def _response_error_detail(response: requests.Response | None) -> str:
+    if response is None:
+        return ""
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text.strip()[:300]
+    if not isinstance(body, dict):
+        return ""
+    error = body.get("error")
+    if isinstance(error, dict):
+        return str(error.get("message", ""))[:300]
+    return str(error or body.get("detail", ""))[:300]
+
+
+def _decode_first_image(body: dict[str, Any]) -> bytes:
+    data = body.get("data")
+    encoded = data[0].get("b64_json") if isinstance(data, list) and data else None
+    if not isinstance(encoded, str) or not encoded:
+        raise CodexImageGenerationError(t("codex.imagegen.no_data"))
+    try:
+        return base64.b64decode(encoded, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise CodexImageGenerationError(t("codex.imagegen.malformed_data")) from exc
+
+
+def emit_iterm_image(output_path: Path) -> bool:
+    """Display a saved image with iTerm2's OSC 1337 inline-image protocol."""
+    if not _is_iterm2() or not sys.stdout.isatty():
+        return False
+
+    try:
+        image_data = base64.b64encode(output_path.read_bytes()).decode("ascii")
+        encoded_name = base64.b64encode(output_path.name.encode()).decode("ascii")
+        sequence = (
+            f"\033]1337;File=name={encoded_name};inline=1;"
+            f"preserveAspectRatio=1:{image_data}\a\n"
+        )
+        from code_puppy.messaging.run_ui import suspended_run_ui
+
+        with suspended_run_ui():
+            sys.stdout.write(sequence)
+            sys.stdout.flush()
+    except Exception:
+        # Inline display is best-effort; the image remains safely saved even if
+        # terminal detection lied or the active UI cannot be suspended.
+        return False
+    return True
+
+
+def _is_iterm2() -> bool:
+    return bool(
+        os.environ.get("ITERM_SESSION_ID")
+        or os.environ.get("TERM_PROGRAM", "").lower() == "iterm.app"
+    )
+
+
+def _save_image(image_bytes: bytes) -> Path:
+    output_dir = Path(config.DATA_DIR) / "generated_images"
+    output_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    output_path = output_dir / f"codex-{uuid.uuid4().hex}.png"
+    temporary_path = output_path.with_suffix(".tmp")
+    try:
+        temporary_path.write_bytes(image_bytes)
+        os.chmod(temporary_path, 0o600)
+        temporary_path.replace(output_path)
+    except OSError as exc:
+        temporary_path.unlink(missing_ok=True)
+        raise CodexImageGenerationError(t("codex.imagegen.save_failed")) from exc
+    return output_path

code_puppy_core_plugins/chatgpt_oauth/image_tool.py

@@ -0,0 +1,70 @@
+"""Agent-facing Codex OAuth image-generation tool."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from pydantic_ai import RunContext
+
+from .image_generation import (
+    CodexImageGenerationError,
+    emit_iterm_image,
+    generate_image,
+)
+
+TOOL_NAME = "codex_imagegen"
+
+
+def register_codex_imagegen(agent: Any) -> None:
+    """Register image generation on a pydantic-ai agent."""
+
+    @agent.tool
+    async def codex_imagegen(
+        context: RunContext,
+        prompt: str,
+        reference_images: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Generate a raster image using gpt-image-2 and Codex OAuth.
+
+        Use this when the user asks you to create a photo, illustration, icon,
+        sprite, texture, product image, banner, or other raster artwork. Write a
+        complete standalone visual prompt because the image model does not see
+        the conversation. The PNG is saved automatically and displayed inline
+        in iTerm2 when supported.
+
+        Pass ``reference_images`` to condition the result on existing images
+        instead of generating from text alone. Reach for it whenever the output
+        must stay visually consistent with something that already exists:
+
+        * the SAME character across multiple images (portraits, expressions,
+          poses) — conditioning on a canonical reference holds identity far
+          better than re-describing the face in words;
+        * matching an established art style, palette, or lighting;
+        * iterating on an existing asset ("same logo, but on a dark
+          background").
+
+        Args:
+            prompt: Detailed standalone description of the image to generate.
+            reference_images: Optional paths to existing image files to
+                condition on. Describe the CHANGE you want in ``prompt``; the
+                references supply the subject and style to preserve.
+        """
+        del context
+        try:
+            output_path = await asyncio.to_thread(
+                generate_image, prompt, reference_images
+            )
+        except CodexImageGenerationError as exc:
+            return {"success": False, "error": str(exc)}
+
+        displayed_inline = emit_iterm_image(output_path)
+        return {
+            "success": True,
+            "path": str(output_path),
+            "displayed_inline": displayed_inline,
+        }
+
+
+def register_tools_callback() -> list[dict[str, Any]]:
+    return [{"name": TOOL_NAME, "register_func": register_codex_imagegen}]