store.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337
  1. """On-disk pet store — install / list / resolve pets.
  2. Pets live under ``get_hermes_home()/pets/<slug>/`` (profile-scoped; NOT petdex's
  3. ``~/.codex/pets``, which its CLI owns): ``pet.json`` ({id, displayName,
  4. description, spritesheetPath}) plus ``spritesheet.webp`` (or .png). The active
  5. pet comes from the caller-supplied ``display.pet.slug`` (no config loader here).
  6. """
  7. from __future__ import annotations
  8. import contextlib
  9. import io
  10. import itertools
  11. import json
  12. import logging
  13. import re
  14. import shutil
  15. import zipfile
  16. from dataclasses import dataclass
  17. from pathlib import Path
  18. from urllib.parse import urlparse
  19. from hermes_constants import get_hermes_home
  20. logger = logging.getLogger(__name__)
  21. _DOWNLOAD_TIMEOUT = 60.0
  22. _HTTP_HEADERS = {"User-Agent": "hermes-agent-petdex"}
  23. _THUMB_FRAME_W = 192
  24. _THUMB_FRAME_H = 208
  25. _THUMB_W = 96 # rendered ~40px; 2x+ keeps it crisp on HiDPI
  26. class PetStoreError(RuntimeError):
  27. """Raised on install/IO failures."""
  28. @dataclass(frozen=True)
  29. class InstalledPet:
  30. """A pet present on disk."""
  31. slug: str
  32. display_name: str
  33. description: str
  34. directory: Path
  35. spritesheet: Path
  36. created_by: str = "" # "generator" for pets hatched locally; "" for petdex installs
  37. @property
  38. def exists(self) -> bool:
  39. return self.spritesheet.is_file()
  40. @property
  41. def generated(self) -> bool:
  42. return self.created_by == "generator"
  43. def _ensure_dir(path: Path) -> Path:
  44. path.mkdir(parents=True, exist_ok=True)
  45. return path
  46. def pets_dir() -> Path:
  47. """Return the profile-scoped pets directory (created on demand)."""
  48. return _ensure_dir(get_hermes_home() / "pets")
  49. def _thumb_path(slug: str) -> Path:
  50. """Cached thumbnail for *slug* (lives OUTSIDE the pet dir, under ``pets/.thumbs/``)."""
  51. return _ensure_dir(pets_dir() / ".thumbs") / f"{slug}.png"
  52. def _read_pet_json(directory: Path) -> dict:
  53. pet_json = directory / "pet.json"
  54. try:
  55. return json.loads(pet_json.read_text(encoding="utf-8-sig")) if pet_json.is_file() else {}
  56. except (OSError, ValueError) as exc:
  57. logger.debug("unreadable pet.json in %s: %s", directory, exc)
  58. return {}
  59. def _write_pet_json(directory: Path, meta: dict) -> None:
  60. (directory / "pet.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
  61. def _resolve_spritesheet(directory: Path, meta: dict) -> Path:
  62. """Honor ``spritesheetPath``, else probe conventional names (incl. petdex R2's ``sprite.webp``)."""
  63. declared = str(meta.get("spritesheetPath", "") or "").strip()
  64. names = ([declared] if declared else []) + ["spritesheet.webp", "spritesheet.png", "sprite.webp", "sprite.png"]
  65. return next((directory / n for n in names if (directory / n).is_file()), directory / "spritesheet.webp") # stable default
  66. def _safe_slug(slug: str) -> str:
  67. """Normalize a slug to one bare path segment so ``pets_dir()/<slug>`` can never escape the pets directory."""
  68. segment = Path(str(slug).strip()).name
  69. return "" if segment in ("", ".", "..") else segment
  70. def load_pet(slug: str) -> InstalledPet | None:
  71. """Return the :class:`InstalledPet` for *slug*, or ``None`` if absent."""
  72. if not (slug := _safe_slug(slug)) or not (directory := pets_dir() / slug).is_dir():
  73. return None
  74. meta = _read_pet_json(directory)
  75. name, desc, by = (str(meta.get(k, "") or d) for k, d in (("displayName", slug), ("description", ""), ("createdBy", "")))
  76. return InstalledPet(slug, name, desc, directory, _resolve_spritesheet(directory, meta), by)
  77. def _usable_pet(slug: str, error: str = "") -> InstalledPet | None:
  78. """:func:`load_pet` result only when its spritesheet is on disk; raises :class:`PetStoreError` *error* if given."""
  79. if (pet := load_pet(slug)) and pet.exists:
  80. return pet
  81. if error:
  82. raise PetStoreError(error)
  83. return None
  84. def installed_pets() -> list[InstalledPet]:
  85. """Return every installed pet (dirs containing a usable spritesheet)."""
  86. return [pet for child in sorted(pets_dir().iterdir()) if child.is_dir() and (pet := _usable_pet(child.name))]
  87. def resolve_active_pet(configured_slug: str | None = None) -> InstalledPet | None:
  88. """The configured slug (``display.pet.slug``) if installed, else the first pet alphabetically."""
  89. if configured_slug and (pet := _usable_pet(configured_slug.strip())):
  90. return pet
  91. return next(iter(installed_pets()), None)
  92. def install_pet(slug: str, *, force: bool = False, timeout: float = _DOWNLOAD_TIMEOUT) -> InstalledPet:
  93. """Download *slug* from the manifest; idempotent unless *force*. Raises :class:`PetStoreError` / ``ManifestError``."""
  94. from agent.pet.manifest import find_entry
  95. slug = _safe_slug(slug)
  96. if not slug:
  97. raise PetStoreError("invalid pet slug")
  98. if not force and (existing := _usable_pet(slug)):
  99. return existing
  100. entry = find_entry(slug, timeout=timeout)
  101. if entry is None:
  102. raise PetStoreError(f"pet '{slug}' is not in the petdex manifest")
  103. # Host-pin asset URLs so a compromised/spoofed manifest can't redirect the
  104. # download to an arbitrary host (matches thumbnail_png).
  105. if not _is_petdex_host(entry.spritesheet_url):
  106. raise PetStoreError(f"refusing non-petdex spritesheet host for '{slug}'")
  107. directory = _ensure_dir(pets_dir() / slug)
  108. sprite_ext = ".png" if entry.spritesheet_url.lower().split("?")[0].endswith(".png") else ".webp"
  109. sprite_path = directory / f"spritesheet{sprite_ext}"
  110. _download(entry.spritesheet_url, sprite_path, timeout=timeout)
  111. # Prefer the upstream pet.json; else synthesize one so the layout is self-describing.
  112. meta: dict = {}
  113. if entry.pet_json_url and _is_petdex_host(entry.pet_json_url):
  114. try:
  115. meta = data if isinstance(data := _http_get(entry.pet_json_url, timeout).json(), dict) else {}
  116. except Exception as exc:
  117. logger.debug("pet.json fetch failed for %s: %s", slug, exc)
  118. meta = meta or {"id": slug, "displayName": entry.display_name, "description": ""}
  119. meta["spritesheetPath"] = sprite_path.name # key order matters: pet.json is written verbatim
  120. meta.setdefault("id", slug)
  121. meta.setdefault("displayName", entry.display_name)
  122. _write_pet_json(directory, meta)
  123. return _usable_pet(slug, f"install of '{slug}' did not produce a spritesheet")
  124. def slugify(name: str) -> str:
  125. """Lowercase, hyphenate, and strip a display name into a filesystem slug."""
  126. return re.sub(r"[^a-z0-9]+", "-", (name or "").strip().lower()).strip("-") or "pet"
  127. def unique_slug(name: str) -> str:
  128. """A :func:`slugify` result that doesn't collide with an existing pet dir."""
  129. base = slugify(name)
  130. candidates = (base if i == 1 else f"{base}-{i}" for i in itertools.count(1))
  131. return next(slug for slug in candidates if not (pets_dir() / slug).exists())
  132. def register_local_pet(spritesheet, *, slug: str, display_name: str = "", description: str = "") -> InstalledPet:
  133. """Write a locally-generated pet (PIL image, WebP/PNG bytes, or path) into the store as lossless WebP.
  134. Appears in :func:`installed_pets` immediately (no manifest entry needed).
  135. """
  136. slug = slugify(slug)
  137. directory = _ensure_dir(pets_dir() / slug)
  138. sprite_path = directory / "spritesheet.webp"
  139. try:
  140. if isinstance(spritesheet, (bytes, bytearray)):
  141. sprite_path.write_bytes(bytes(spritesheet))
  142. else:
  143. from agent.pet.generate.atlas import _load_rgba
  144. _load_rgba(spritesheet).save(sprite_path, format="WEBP", lossless=True, quality=100, method=6, exact=True)
  145. except Exception as exc:
  146. raise PetStoreError(f"could not write spritesheet for '{slug}': {exc}") from exc
  147. meta = {"id": slug, "displayName": display_name or slug, "description": description or "", "spritesheetPath": sprite_path.name}
  148. _write_pet_json(directory, {**meta, "createdBy": "generator"})
  149. return _usable_pet(slug, f"register of generated pet '{slug}' did not produce a spritesheet")
  150. def export_pet(slug: str) -> tuple[str, bytes]:
  151. """Zip an installed pet's folder → ``(filename, bytes)``; dotfiles (thumbs, backups) skipped."""
  152. root = pets_dir()
  153. directory = root / slug.strip()
  154. # Traversal guard: the target must be a direct child of pets_dir.
  155. if directory.resolve().parent != root.resolve() or not directory.is_dir():
  156. raise PetStoreError(f"pet '{slug}' is not installed")
  157. buf = io.BytesIO()
  158. with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as archive:
  159. for path in sorted(directory.iterdir()):
  160. if path.is_file() and not path.name.startswith("."):
  161. archive.write(path, f"{directory.name}/{path.name}")
  162. return f"{directory.name}.zip", buf.getvalue()
  163. def _is_petdex_host(url: str) -> bool:
  164. """True only for petdex.dev hosts — bounds server-side fetch (anti-SSRF)."""
  165. try:
  166. host = (urlparse(url).hostname or "").lower()
  167. except ValueError:
  168. return False
  169. return host == "petdex.dev" or host.endswith(".petdex.dev")
  170. def thumbnail_png(slug: str, *, source_url: str = "", timeout: float = 30.0) -> bytes | None:
  171. """Small idle-frame (top-left cell) PNG for *slug*, cached on disk; ``None`` on any failure.
  172. Source: the installed sheet, else *source_url* only when petdex-hosted (the gateway
  173. never fetches arbitrary client URLs). Server-side so it rides the authenticated
  174. gateway as a same-origin data URL, sidestepping CSP/hotlink limits.
  175. """
  176. if not (slug := slug.strip()):
  177. return None
  178. if (cache := _thumb_path(slug)).is_file():
  179. with contextlib.suppress(OSError):
  180. return cache.read_bytes()
  181. sheet_bytes = None
  182. if pet := _usable_pet(slug):
  183. with contextlib.suppress(OSError):
  184. sheet_bytes = pet.spritesheet.read_bytes()
  185. if sheet_bytes is None and source_url and _is_petdex_host(source_url):
  186. try:
  187. sheet_bytes = _http_get(source_url, timeout).content
  188. except Exception as exc:
  189. logger.debug("thumb fetch failed for %s: %s", slug, exc)
  190. if not sheet_bytes:
  191. return None
  192. try:
  193. from PIL import Image
  194. with Image.open(io.BytesIO(sheet_bytes)) as im:
  195. frame = im.convert("RGBA").crop((0, 0, min(_THUMB_FRAME_W, im.width), min(_THUMB_FRAME_H, im.height)))
  196. frame = frame.resize((_THUMB_W, round(_THUMB_W * _THUMB_FRAME_H / _THUMB_FRAME_W)), Image.NEAREST)
  197. buf = io.BytesIO()
  198. frame.save(buf, format="PNG")
  199. except Exception as exc:
  200. logger.debug("thumb crop failed for %s: %s", slug, exc)
  201. return None
  202. with contextlib.suppress(OSError):
  203. cache.write_bytes(buf.getvalue())
  204. return buf.getvalue()
  205. def remove_pet(slug: str) -> bool:
  206. """Delete an installed pet directory. Returns True if anything was removed."""
  207. slug = _safe_slug(slug)
  208. if not slug:
  209. return False
  210. # Drop the cached thumb too or a later pet reusing this slug shows the stale one.
  211. with contextlib.suppress(OSError):
  212. _thumb_path(slug).unlink(missing_ok=True)
  213. if not (directory := pets_dir() / slug).is_dir():
  214. return False
  215. shutil.rmtree(directory, ignore_errors=True)
  216. return not directory.exists()
  217. def rename_pet(slug: str, display_name: str) -> str | None:
  218. """Rename a pet's ``displayName`` AND move its dir/thumb to ``slugify(name)`` when that's a free, different slug.
  219. Generated pets hatch under a provisional slug; naming makes that the identity. Returns the resulting slug, or ``None``.
  220. """
  221. slug = _safe_slug(slug)
  222. display_name = (display_name or "").strip()
  223. directory = pets_dir() / slug
  224. if not slug or not display_name or not (directory / "pet.json").is_file():
  225. return None
  226. meta = _read_pet_json(directory)
  227. meta = meta if isinstance(meta, dict) else {}
  228. meta["displayName"] = display_name
  229. new_slug = slug
  230. desired = slugify(display_name)
  231. if desired and desired != slug and not (pets_dir() / desired).exists():
  232. with contextlib.suppress(OSError): # keep the provisional slug if the move fails
  233. directory.rename(pets_dir() / desired)
  234. with contextlib.suppress(OSError):
  235. _thumb_path(slug).rename(_thumb_path(desired))
  236. directory = pets_dir() / desired
  237. new_slug = meta["id"] = desired
  238. try:
  239. _write_pet_json(directory, meta)
  240. except OSError:
  241. return None
  242. return new_slug
  243. def _http_get(url: str, timeout: float):
  244. """GET *url* with the petdex UA, following redirects; raises on HTTP errors.
  245. Manifest-derived URLs are remote-party-controlled — SSRF-checked first."""
  246. from tools.url_safety import create_ssrf_safe_client, is_safe_url
  247. if not is_safe_url(url):
  248. raise ValueError(f"Pet store URL failed the SSRF safety check: {url}")
  249. with create_ssrf_safe_client(timeout=timeout, follow_redirects=True) as client:
  250. resp = client.get(url, headers=_HTTP_HEADERS)
  251. resp.raise_for_status()
  252. return resp
  253. def _download(url: str, dest: Path, *, timeout: float) -> None:
  254. """Stream *url* to *dest* via a ``.part`` temp file so a failed download never leaves a truncated sheet."""
  255. import httpx
  256. try:
  257. from tools.url_safety import create_ssrf_safe_client, is_safe_url
  258. if not is_safe_url(url):
  259. raise ValueError(f"Pet store URL failed the SSRF safety check: {url}")
  260. with create_ssrf_safe_client(timeout=timeout, follow_redirects=True) as client, \
  261. client.stream("GET", url, headers=_HTTP_HEADERS) as resp:
  262. resp.raise_for_status()
  263. tmp = dest.with_suffix(dest.suffix + ".part")
  264. with tmp.open("wb") as fh:
  265. for chunk in resp.iter_bytes():
  266. fh.write(chunk)
  267. tmp.replace(dest)
  268. except Exception as exc:
  269. raise PetStoreError(f"download failed for {url}: {exc}") from exc