@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/client/remote_backend.py

@@ -0,0 +1,498 @@
+"""MÁY KHÁCH: mượn tài khoản sinh ảnh + GPU từ MỘT CỤM node (remote_host.py).
+
+Bật bằng env, KHÔNG đổi dòng code nào và KHÔNG đổi tên tool:
+
+    GAMEART_REMOTE_NODES = http://192.168.1.50:8765/mcp,http://192.168.1.51:8765/mcp
+    GAMEART_REMOTE_TOKEN = <token dùng chung>
+
+Mỗi mục có thể mang token riêng: "http://.../mcp|token-rieng-cua-node-nay". Một node thì
+dùng `GAMEART_REMOTE_URL` như cũ vẫn chạy.
+
+CHỌN NODE — ba tầng, mỗi tầng giải một bài khác nhau:
+  1. `status` (nhẹ, KHÔNG khoá) cho biết node nào rảnh và còn quota -> xếp hạng, thử node
+     rảnh nhất trước. Cache STATUS_TTL giây để việc chọn không tốn hơn việc làm.
+  2. Node trả "bận"/"hết quota" -> phạt riêng node đó rồi ĐỔI NGAY sang node kế. Đây là lý
+     do máy chủ phải từ chối tức thì thay vì ngậm kết nối: ngậm thì máy khách mất quyền đổi.
+  3. Hết node dùng được -> CHỜ rồi thử lại, tối đa GAMEART_REMOTE_WAIT (mặc định 15 phút),
+     sau đó báo lại kèm lý do TỪNG node.
+
+Phạt "bận" ngắn (vài giây, node sắp rảnh) còn phạt lỗi thật dài (60s) — gộp chung là hoặc
+bỏ oan node tốt, hoặc quay lại liên tục một node hỏng.
+
+Thiết kế: chỉ ba SEAM đi qua mạng — sinh ảnh, BEN2, ESRGAN. Đó là ba thứ cần tài khoản
+hoặc GPU. Toàn bộ phần còn lại (dò màu nền, unmix, chấm điểm chọn cách tách nền, chấm điểm
+chọn cách phóng to, cắt bbox, bám size gốc, dựng sheet, ghi file) vẫn chạy TẠI MÁY KHÁCH
+bằng imglib. Ba hệ quả đáng giá:
+  - máy khách giữ nguyên quyền quyết định: nó tự chấm điểm rồi tự chọn bản thắng;
+  - file của máy khách không bao giờ rời máy khách trừ đúng ảnh cần model xử lý;
+  - máy chủ hỏng/tắt thì chỉ mất ứng viên BEN2/ESRGAN, các cách theo màu và LANCZOS vẫn
+    chạy đủ — pipeline KHÔNG chết.
+
+Rớt mềm ở mọi tầng: thiếu env -> tắt hẳn; thiếu httpx -> tắt; máy chủ lỗi/timeout -> ném
+RemoteError để caller quay về đường local.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import time
+
+import numpy as np
+from PIL import Image
+
+import remote_proto as P
+
+# Cho gemini_image_mcp tham chiếu hằng số env qua RB.P mà không phải import thêm module.
+__all__ = ["P"]
+
+_probe: dict | None = None      # cache kết quả health() của node đầu tiên dùng được
+
+# Cache trạng thái từng node. Hỏi status trước MỖI lời gọi thì đúng nhưng tốn một vòng mạng
+# cho mỗi việc; cache vài giây là đủ tươi để chọn node mà không biến việc chọn thành gánh nặng.
+STATUS_TTL = float(os.environ.get("GAMEART_STATUS_TTL", "4"))
+_status: dict[str, tuple[float, dict]] = {}      # url -> (thời điểm, status)
+_cooldown: dict[str, float] = {}                 # url -> monotonic time hết phạt
+
+
+def enabled() -> bool:
+    """Có cấu hình node nào không. KHÔNG kiểm mạng — xem `probe()`."""
+    return bool(P.nodes())
+
+
+def _client(tok: str):
+    import httpx
+    return httpx.AsyncClient(timeout=P.DEFAULT_TIMEOUT,
+                             headers={P.TOKEN_HEADER: tok})
+
+
+def _force_curl() -> bool:
+    """macOS thường chặn Local Network với Python do uv — `/usr/bin/curl` vẫn vào được LAN."""
+    v = (os.environ.get("GAMEART_HTTP_VIA") or "").strip().lower()
+    if v in ("curl", "1", "true", "yes"):
+        return True
+    if v in ("httpx", "0", "false", "no"):
+        return False
+    return sys.platform == "darwin"
+
+
+async def _post_rpc_httpx(node: dict, body: dict, timeout: float) -> tuple[int, str, str]:
+    import httpx
+    hdr = {"content-type": "application/json",
+           "accept": "application/json, text/event-stream"}
+    c = _client(node["token"])
+    c.timeout = timeout
+    async with c:
+        r = await c.post(node["url"], headers=hdr, json=body)
+        return r.status_code, r.text, r.headers.get("content-type", "")
+
+
+async def _post_rpc_curl(node: dict, body: dict, timeout: float) -> tuple[int, str, str]:
+    """POST JSON-RPC qua /usr/bin/curl — né chặn Local Network của binary Python trên macOS."""
+    import tempfile
+    curl = "/usr/bin/curl" if os.path.isfile("/usr/bin/curl") else "curl"
+    raw = json.dumps(body, ensure_ascii=False).encode("utf-8")
+    # Body có thể rất lớn (ảnh base64) — không nhét argv; ghi file tạm.
+    fd, path = tempfile.mkstemp(prefix="gameart-rpc-", suffix=".json")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(raw)
+        cmd = [
+            curl, "-sS", "-X", "POST",
+            "--connect-timeout", str(max(1, min(30, int(timeout)))),
+            "--max-time", str(max(1, int(timeout))),
+            "-H", f"{P.TOKEN_HEADER}: {node['token']}",
+            "-H", "Content-Type: application/json",
+            "-H", "Accept: application/json, text/event-stream",
+            "--data-binary", f"@{path}",
+            "-w", "\n__HTTP_STATUS__:%{http_code}\n__CONTENT_TYPE__:%{content_type}",
+            node["url"],
+        ]
+        proc = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        out_b, err_b = await proc.communicate()
+        if proc.returncode != 0:
+            err = (err_b or out_b or b"").decode("utf-8", "replace")[:300]
+            raise P.RemoteError(f"curl lỗi (exit {proc.returncode}): {err}")
+        text = out_b.decode("utf-8", "replace")
+        # Tách trailer status/content-type mà curl -w gắn cuối stdout.
+        status, ctype = 0, ""
+        if "__HTTP_STATUS__:" in text:
+            body_txt, _, trailer = text.rpartition("\n__HTTP_STATUS__:")
+            # trailer: "<code>\n__CONTENT_TYPE__:<ctype>"
+            parts = trailer.strip().split("\n__CONTENT_TYPE__:", 1)
+            try:
+                status = int(parts[0].strip())
+            except ValueError:
+                status = 0
+            if len(parts) > 1:
+                ctype = parts[1].strip()
+            text = body_txt
+        else:
+            raise P.RemoteError(f"curl không trả status: {text[:200]}")
+        return status, text, ctype
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+
+async def _post_rpc(node: dict, body: dict, timeout: float) -> tuple[int, str, str]:
+    if _force_curl():
+        return await _post_rpc_curl(node, body, timeout)
+    try:
+        return await _post_rpc_httpx(node, body, timeout)
+    except Exception as e:
+        # Errno 65 No route to host / ConnectError trên macOS khi TCC chặn Python.
+        name = type(e).__name__
+        msg = str(e)
+        if name in ("ConnectError", "ConnectTimeout", "OSError") or "No route to host" in msg \
+                or "All connection attempts failed" in msg:
+            return await _post_rpc_curl(node, body, timeout)
+        raise
+
+
+def _parse_rpc_response(status: int, txt: str, content_type: str, tool: str) -> dict:
+    if status == 401:
+        raise P.RemoteError("từ chối token (401) — kiểm GAMEART_REMOTE_TOKEN hai đầu")
+    if status == 421:
+        # "Misdirected Request" không gợi ý gì cả. Dịch ra nguyên nhân thật.
+        raise P.RemoteError(
+            "node từ chối header Host (421) — lớp chống DNS-rebinding của MCP chỉ cho "
+            "host trong allowlist. Chạy node bằng bản mới (nó tự mở IP LAN), hoặc thêm "
+            "host đang gọi vào GAMEART_ALLOWED_HOSTS TRÊN NODE rồi khởi động lại.")
+    if status < 200 or status >= 300:
+        raise P.RemoteError(f"HTTP {status}: {txt[:200]}")
+    if (content_type or "").startswith("text/event-stream"):
+        # Máy chủ đang chạy chế độ luồng — lấy dòng `data:` cuối.
+        data = [l[5:].strip() for l in txt.splitlines() if l.startswith("data:")]
+        if not data:
+            raise P.RemoteError(f"trả SSE rỗng: {txt[:200]}")
+        txt = data[-1]
+    try:
+        msg = json.loads(txt)
+    except Exception as e:
+        raise P.RemoteError(f"JSON hỏng: {e}; body={txt[:200]}") from e
+
+    if "error" in msg:
+        raise P.RemoteError(f"báo lỗi: {msg['error']}")
+    res = msg.get("result") or {}
+    if res.get("isError"):
+        raise P.RemoteError(f"tool {tool} lỗi: {res.get('content')}")
+    out = res.get("structuredContent")
+    if out is None:
+        # FastMCP trả kết quả dict trong content[0].text khi không có structuredContent.
+        for c0 in res.get("content") or []:
+            if c0.get("type") == "text":
+                try:
+                    out = json.loads(c0["text"])
+                    break
+                except Exception:
+                    pass
+    if not isinstance(out, dict):
+        raise P.RemoteError(f"tool {tool} trả về không đọc được: {str(res)[:300]}")
+    if out.get("busy"):
+        raise P.NodeBusy(f"{tool}: {out.get('error')}", float(out.get("retry_after") or 5))
+    if out.get("exhausted"):
+        raise P.NodeExhausted(f"{tool}: {out.get('error')}", float(out.get("retry_after") or 300))
+    if out.get("error"):
+        raise P.RemoteError(f"{tool}: {out['error']}")
+    return out
+
+
+async def _call_node(node: dict, tool: str, args: dict, timeout: float | None = None) -> dict:
+    """Gọi 1 tool trên MỘT node qua streamable-http. Trả dict kết quả.
+
+    Nói chuyện JSON-RPC ở mức thô thay vì kéo cả client SDK: một lượt request duy nhất, và
+    không ràng buộc phiên bản SDK giữa hai máy. Làm được vậy vì `remote_host.py` chạy
+    KHÔNG PHIÊN (`stateless_http`) — mỗi lời gọi độc lập nên không cần bắt tay `initialize`.
+
+    Ném NodeBusy / NodeExhausted riêng biệt để tầng chọn node xử lý khác nhau.
+
+    Trên macOS mặc định đi qua `/usr/bin/curl` vì Python cài bằng uv thường bị TCC
+    Local Network chặn (errno 65), trong khi curl/system python vẫn vào LAN được.
+    """
+    to = float(timeout if timeout is not None else P.DEFAULT_TIMEOUT)
+    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {"name": tool, "arguments": args}}
+    status, txt, ctype = await _post_rpc(node, body, to)
+    return _parse_rpc_response(status, txt, ctype, tool)
+
+
+# ------------------------------------------------------- chọn node trong cụm
+
+async def _fetch_status(node: dict) -> dict:
+    """Hỏi status MỘT node, timeout ngắn. Hỏng thì trả {"ok": False, "error": ...}.
+
+    Timeout ngắn là cố ý: một node chết không được phép làm chậm việc chọn node cho cả cụm.
+    GIỮ LẠI LÝ DO thay vì nuốt đi — không có nó thì `remote_nodes()` chỉ báo "không gọi được"
+    và người dùng không phân biệt nổi sai token với sai IP với node quá tải.
+    """
+    try:
+        return await _call_node(node, "status", {}, timeout=float(
+            os.environ.get("GAMEART_STATUS_TIMEOUT", "10")))
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+
+async def _statuses(force: bool = False) -> list[tuple[dict, dict | None]]:
+    """Trạng thái mọi node, hỏi SONG SONG, có cache TTL."""
+    now = time.monotonic()
+    todo, out = [], {}
+    for n in P.nodes():
+        c = _status.get(n["url"])
+        if c and not force and now - c[0] < STATUS_TTL:
+            out[n["url"]] = c[1]
+        else:
+            todo.append(n)
+    if todo:
+        got = await asyncio.gather(*[_fetch_status(n) for n in todo])
+        for n, st in zip(todo, got):
+            if st.get("ok"):
+                _status[n["url"]] = (now, st)      # chỉ cache bản LÀNH
+            out[n["url"]] = st
+    return [(n, out.get(n["url"])) for n in P.nodes()]
+
+
+def _score(st: dict, cap: str) -> float:
+    """Điểm chọn node — THẤP hơn thì ưu tiên hơn. inf = không dùng được lúc này."""
+    if not st or not st.get("ok"):
+        return float("inf")
+    if not (st.get("available") or {}).get(cap):
+        return float("inf")
+    slot = {"gemini": "gemini", "codex": "codex", "ben2": "gpu", "esrgan": "gpu"}[cap]
+    s = (st.get("slots") or {}).get(slot) or {}
+    if s.get("full"):
+        return float("inf")
+    load = float(s.get("load", 0.0))
+    # Ưu tiên node RẢNH. Cộng thêm mức đã tiêu quota trong giờ để san đều giữa các tài khoản
+    # thay vì vắt kiệt một node rồi mới chuyển — vắt kiệt là cách nhanh nhất để bị khoá.
+    q = (st.get("quota") or {}).get(cap if cap in ("gemini", "codex") else "", {}) or {}
+    lim = q.get("limit_hour")
+    frac = (q.get("used_hour", 0) / lim) if lim else 0.0
+    return load + 0.25 * float(frac)
+
+
+async def _pick(cap: str, force: bool = False) -> list[dict]:
+    """Node dùng được cho `cap`, đã sắp theo thứ tự nên thử."""
+    now = time.monotonic()
+    rank = []
+    for n, st in await _statuses(force=force):
+        if _cooldown.get(n["url"], 0) > now:      # vừa báo bận/hết quota -> tạm bỏ qua
+            continue
+        sc = _score(st or {}, cap)
+        if sc < float("inf"):
+            rank.append((sc, n))
+    rank.sort(key=lambda x: x[0])
+    return [n for _, n in rank]
+
+
+async def _call(tool: str, args: dict, cap: str | None = None) -> dict:
+    """Gọi `tool` trên node phù hợp; bận thì đổi node; hết node thì CHỜ rồi thử lại.
+
+    Chờ tối đa `GAMEART_REMOTE_WAIT` (mặc định 900s = 15 phút) rồi báo lại kèm lý do của
+    từng node — im lặng chờ mãi còn tệ hơn dừng, vì người dùng không biết còn sống hay đã treo.
+    """
+    cap = cap or {"gen_gemini": "gemini", "gen_codex": "codex",
+                  "ben2_cutout": "ben2", "esrgan_x4": "esrgan"}.get(tool, "gemini")
+    if not P.nodes():
+        raise P.RemoteError(f"chưa cấu hình node nào ({P.ENV_NODES}/{P.ENV_URL})")
+
+    deadline = time.monotonic() + P.DEFAULT_WAIT
+    last: dict[str, str] = {}
+    waited = False
+    while True:
+        for n in await _pick(cap, force=waited):
+            try:
+                out = await _call_node(n, tool, args)
+                out["_node"] = n["url"]
+                _cooldown.pop(n["url"], None)
+                return out
+            except (P.NodeBusy, P.NodeExhausted) as e:
+                # Node vẫn KHOẺ, chỉ không nhận việc lúc này -> phạt nhẹ rồi thử node khác.
+                _cooldown[n["url"]] = time.monotonic() + e.retry_after
+                _status.pop(n["url"], None)
+                last[n["url"]] = str(e)
+            except Exception as e:
+                # Lỗi thật -> phạt nặng hơn để không quay lại liên tục một node hỏng.
+                _cooldown[n["url"]] = time.monotonic() + 60
+                _status.pop(n["url"], None)
+                last[n["url"]] = f"{type(e).__name__}: {e}"
+
+        left = deadline - time.monotonic()
+        if left <= 0:
+            why = "; ".join(f"{u} -> {m}" for u, m in last.items()) or "không node nào phản hồi"
+            w = P.DEFAULT_WAIT
+            dur = f"{w / 60:.0f} phút" if w >= 60 else f"{w:.0f} giây"
+            raise P.RemoteError(
+                f"mọi node bận/không dùng được cho `{cap}` sau {dur} chờ "
+                f"({len(P.nodes())} node). Chi tiết: {why}")
+        # Ngủ tới lúc node sớm nhất hết phạt, nhưng đừng quá 15s để còn bắt kịp node vừa rảnh.
+        nxt = min([t - time.monotonic() for t in _cooldown.values()] or [5.0])
+        await asyncio.sleep(max(1.0, min(15.0, nxt, left)))
+        waited = True
+
+
+def _run(coro):
+    """Chạy coroutine từ ngữ cảnh ĐỒNG BỘ (bgremove/upscale seam là hàm thường).
+
+    Bên trong MCP server, vòng lặp sự kiện ĐANG chạy — `asyncio.run` sẽ nổ. Nên đẩy sang
+    một luồng riêng có vòng lặp của nó.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    import concurrent.futures
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
+        return ex.submit(asyncio.run, coro).result()
+
+
+async def _health_all() -> list[dict]:
+    """health() của MỌI node, hỏi song song. Node chết vẫn có một dòng ghi rõ lý do."""
+    async def one(n):
+        try:
+            h = await _call_node(n, "health", {}, timeout=float(
+                os.environ.get("GAMEART_STATUS_TIMEOUT", "6")))
+            h["url"] = n["url"]
+            h.setdefault("ok", True)
+            return h
+        except Exception as e:
+            return {"url": n["url"], "ok": False, "error": f"{type(e).__name__}: {e}"}
+    return list(await asyncio.gather(*[one(n) for n in P.nodes()]))
+
+
+def probe(force: bool = False) -> dict:
+    """Cụm này có gì. Gộp khả năng của MỌI node: một cái nào có là dùng được.
+
+    Cache lại; không node nào phản hồi thì trả {"ok": False, ...} chứ KHÔNG ném lỗi.
+    """
+    global _probe
+    if _probe is not None and not force:
+        return _probe
+    if not enabled():
+        _probe = {"ok": False, "error": f"chưa đặt {P.ENV_NODES} hoặc {P.ENV_URL}/{P.ENV_TOKEN}"}
+        return _probe
+    try:
+        nodes = _run(_health_all())
+    except Exception as e:
+        _probe = {"ok": False, "error": f"{type(e).__name__}: {e}"}
+        return _probe
+    alive = [h for h in nodes if h.get("ok")]
+    _probe = {
+        "ok": bool(alive),
+        "nodes": nodes,
+        "n_nodes": len(nodes),
+        "n_alive": len(alive),
+        # Khả năng của CỤM = hợp của các node. Một node có GPU là cả cụm phóng to được.
+        **{k: any(bool(h.get(k)) for h in alive) for k in ("gemini", "codex", "ben2", "esrgan")},
+    }
+    if not alive:
+        _probe["error"] = "; ".join(f"{h['url']}: {h.get('error')}" for h in nodes) or "không có node"
+    return _probe
+
+
+def status_all(force: bool = True) -> list[dict]:
+    """Bảng tải + quota của mọi node — để người dùng NHÌN được vì sao node này được chọn."""
+    if not enabled():
+        return []
+    out = []
+    for n, st in _run(_statuses(force=force)):
+        row = {"url": n["url"]}
+        if not st or not st.get("ok"):
+            row.update({"ok": False, "error": (st or {}).get("error") or "không gọi được"})
+        else:
+            row.update({"ok": True, "name": st.get("name"),
+                        "available": st.get("available"),
+                        "slots": st.get("slots"), "quota": st.get("quota")})
+        cd = _cooldown.get(n["url"], 0) - time.monotonic()
+        if cd > 0:
+            row["client_cooldown_left"] = round(cd, 1)
+        out.append(row)
+    return out
+
+
+def info() -> dict:
+    """Tóm tắt để nhét vào report của tool — máy khách phải NHÌN THẤY nó đang mượn máy nào."""
+    ns = P.nodes()
+    d: dict = {"enabled": bool(ns), "nodes": [n["url"] for n in ns]}
+    if ns:
+        p = probe()
+        d.update({k: p.get(k) for k in
+                  ("ok", "n_nodes", "n_alive", "gemini", "codex", "ben2", "esrgan", "error")})
+    return d
+
+
+# ------------------------------------------------------------------ ba seam
+
+async def generate(prompt: str, image_paths: list[str] | None, out_dir: str) -> list[str]:
+    """Seam 1 — sinh ảnh Gemini. Đọc ref từ đĩa KHÁCH, ghi kết quả xuống đĩa KHÁCH.
+
+    Giữ nguyên hợp đồng của gemini_image_mcp._generate: trả danh sách đường dẫn đã lưu.
+    """
+    from pathlib import Path
+    import time
+
+    refs = [P.path_to_b64(p) for p in (image_paths or [])]
+    out = await _call("gen_gemini", {"prompt": prompt, "images_b64": refs}, cap="gemini")
+    imgs = out.get("images_b64") or []
+    if not imgs:
+        raise P.RemoteError("máy chủ không trả ảnh nào")
+    dest = Path(out_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    saved = []
+    for i, b in enumerate(imgs, start=1):
+        p = dest / f"{stamp}_{i}.png"
+        p.write_bytes(P.b64_to_bytes(b))
+        saved.append(str(p))
+    return saved
+
+
+async def generate_codex(prompt: str, image_paths: list[str] | None, out_path: str,
+                         timeout_sec: int = 600) -> str:
+    """Sinh 1 ảnh qua Codex trên máy chủ, lưu vào `out_path` của máy khách."""
+    from pathlib import Path
+
+    refs = [P.path_to_b64(p) for p in (image_paths or [])]
+    out = await _call("gen_codex", {"prompt": prompt, "images_b64": refs,
+                                    "timeout_sec": int(timeout_sec)}, cap="codex")
+    b = out.get("image_b64")
+    if not b:
+        raise P.RemoteError("máy chủ không trả ảnh")
+    p = Path(out_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_bytes(P.b64_to_bytes(b))
+    return str(p)
+
+
+def cutout(img: Image.Image) -> Image.Image:
+    """Seam 2 — BEN2 trên máy chủ. Cùng chữ ký với bgremove.remove_background."""
+    out = _run(_call("ben2_cutout", {"image_b64": P.img_to_b64(img.convert("RGB"))},
+                     cap="ben2"))
+    return P.b64_to_img(out["image_b64"]).convert("RGBA")
+
+
+def upscale_rgb(arr: np.ndarray) -> np.ndarray:
+    """Seam 3 — Real-ESRGAN 4x trên máy chủ. Cùng chữ ký với upscale.upscale_rgb."""
+    if arr.ndim != 3 or arr.shape[2] != 3:
+        raise ValueError(f"cần mảng HxWx3, nhận {arr.shape}")
+    b = P.img_to_b64(Image.fromarray(np.ascontiguousarray(arr), "RGB"))
+    out = _run(_call("esrgan_x4", {"image_b64": b}, cap="esrgan"))
+    big = np.asarray(P.b64_to_img(out["image_b64"]).convert("RGB"), dtype=np.uint8)
+    if big.shape[0] != arr.shape[0] * 4 or big.shape[1] != arr.shape[1] * 4:
+        raise P.RemoteError(
+            f"máy chủ trả sai kích thước: {big.shape} thay vì {(arr.shape[0]*4, arr.shape[1]*4, 3)}")
+    return big
+
+
+def cutout_backend():
+    """Trả callable BEN2 nếu máy chủ có, không thì None."""
+    return cutout if (enabled() and probe().get("ben2")) else None
+
+
+def upscale_backend():
+    """Trả callable ESRGAN nếu máy chủ có, không thì None."""
+    return upscale_rgb if (enabled() and probe().get("esrgan")) else None

package/plugins/phaser-casual-game-factory/skills/game-art/client/remote_codex.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Bản thay thế `codex_gen.sh` khi chạy CHẾ ĐỘ MƯỢN MÁY — `codex_gen.sh` tự exec vào đây.
+
+Giữ NGUYÊN dòng lệnh và NGUYÊN bảng exit code của codex_gen.sh, để bảng "Khi hỏng" trong
+SKILL.md tra được y như cũ và người dùng không phải nhớ hai cách gọi:
+    0 xong   2 sai tham số   3 thiếu công cụ   5 codex hỏng   7 không móc được ảnh
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import envfile as _envfile          # noqa: E402
+_envfile.load(base=Path(__file__).resolve().parent)  # .env cùng thư mục entry
+
+import remote_proto as P            # noqa: E402
+import remote_backend as RB         # noqa: E402
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument("--prompt", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--ref", action="append", default=[])
+    ap.add_argument("--timeout-sec", type=int, default=300)
+    try:
+        a = ap.parse_args()
+    except SystemExit:
+        return 2
+
+    if not RB.enabled():
+        print(f"remote mode: thieu {P.ENV_URL} hoac {P.ENV_TOKEN}", file=sys.stderr)
+        return 3
+    for r in a.ref:
+        if not Path(r).exists():
+            print(f"khong thay anh tham chieu: {r}", file=sys.stderr)
+            return 2
+
+    try:
+        out = asyncio.run(RB.generate_codex(a.prompt, a.ref, a.out, a.timeout_sec))
+    except P.RemoteError as e:
+        msg = str(e)
+        print(f"remote codex loi: {msg}", file=sys.stderr)
+        # Giữ đúng ngữ nghĩa mã lỗi cũ: "chay duoc nhung khong ra anh" là 7, chứ không phải 5.
+        return 7 if "khong tra anh" in msg or "không trả ảnh" in msg else 5
+    except Exception as e:
+        print(f"remote codex loi: {type(e).__name__}: {e}", file=sys.stderr)
+        return 5
+
+    print(out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())