feat(pets): polish generate flow and reduce hatch CPU pressure

Ship the final pet-generation UX polish (provider picker behavior, step-2 cancel flow, banner integration, and visual consistency) and make saturated-chroma background removal C-op driven so hatch processing no longer hammers the machine during long runs.

tests/agent/test_pet_generate.py

@@ -106,6 +106,23 @@ def test_extract_strip_frames_drops_small_side_lobes_from_adjacent_frames():
     assert right_edge_mass == 0
 
 
+def test_extract_strip_frames_uses_real_gutters_when_spacing_is_uneven():
+    # gpt-image often returns a square chroma strip whose poses are separated but
+    # not laid out on exact equal-width slots. Equal slot slicing would include
+    # the next pose's wing/cape in frame 0; gutter-derived crops keep it out.
+    img = Image.new("RGBA", (600, 208), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(img)
+    draw.rectangle((40, 58, 140, 178), fill=(80, 120, 220, 255))
+    draw.rectangle((182, 58, 282, 178), fill=(220, 120, 80, 255))
+    draw.rectangle((430, 58, 530, 178), fill=(80, 220, 120, 255))
+
+    frames = atlas.extract_strip_frames(img, 3, method="auto", fit=False)
+
+    assert len(frames) == 3
+    assert frames[0].getbbox()[2] <= 120
+    assert frames[1].getbbox()[0] <= 16
+
+
 def test_extract_strip_frames_slot_fallback_when_unsegmentable():
     # A single connected smear can't be split into 5 components → slot fallback.
     img = Image.new("RGBA", (200 * 5, 208), (0, 0, 0, 0))
@@ -181,6 +198,27 @@ def test_single_frame_fits_cell():
     assert frame.getchannel("A").getextrema()[1] > 0
 
 
+def test_normalize_cells_uses_consistent_pose_scale_for_motion_rows():
+    # A jump row needs a taller union crop than idle, but the pet itself should
+    # not shrink just because the motion envelope is taller.
+    idle = Image.new("RGBA", (160, 180), (0, 0, 0, 0))
+    jump_low = Image.new("RGBA", (160, 180), (0, 0, 0, 0))
+    jump_high = Image.new("RGBA", (160, 180), (0, 0, 0, 0))
+    ImageDraw.Draw(idle).rectangle((50, 80, 110, 160), fill=(80, 120, 220, 255))
+    ImageDraw.Draw(jump_low).rectangle((50, 80, 110, 160), fill=(220, 120, 80, 255))
+    ImageDraw.Draw(jump_high).rectangle((50, 60, 110, 140), fill=(220, 120, 80, 255))
+
+    normalized = atlas.normalize_cells({"idle": [idle], "jumping": [jump_low, jump_high]})
+    idle_box = normalized["idle"][0].getbbox()
+    jump_box = normalized["jumping"][0].getbbox()
+
+    assert idle_box is not None
+    assert jump_box is not None
+    idle_h = idle_box[3] - idle_box[1]
+    jump_h = jump_box[3] - jump_box[1]
+    assert abs(idle_h - jump_h) <= 8
+
+
 # ───────────────────────── store register / adopt ─────────────────────────
 
 
@@ -252,7 +290,7 @@ def test_generate_base_drafts_returns_n(monkeypatch, tmp_path):
 
     calls = {"n": 0}
 
-    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet"):
+    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet", aspect_ratio="square"):
         paths = []
         for i in range(n):
             calls["n"] += 1
@@ -272,7 +310,7 @@ def test_generate_base_drafts_hardens_opaque_background(monkeypatch, tmp_path):
     """A provider that ignores background=transparent still yields a cutout."""
     from agent.pet.generate import imagegen, orchestrate
 
-    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet"):
+    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet", aspect_ratio="square"):
         # Solid-green backdrop with a blob — i.e. the provider painted a backdrop.
         p = tmp_path / f"{prefix}_opaque.png"
         _strip(1, transparent=False, bg=(0, 255, 0, 255)).save(p)
@@ -300,7 +338,7 @@ def test_hatch_pet_end_to_end(monkeypatch, tmp_path):
     base = tmp_path / "base.png"
     _strip(1).save(base)
 
-    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet"):
+    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet", aspect_ratio="square"):
         # Return a synthetic row strip; frame count is inferable from the spec.
         state = prefix.replace("pet_row_", "")
         count = atlas_mod.FRAME_COUNTS.get(state, 6)
@@ -337,7 +375,7 @@ def test_hatch_pet_idle_fallback_when_row_fails(monkeypatch, tmp_path):
     base = tmp_path / "base.png"
     _strip(1).save(base)
 
-    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet"):
+    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet", aspect_ratio="square"):
         if prefix == "pet_row_idle":
             raise GenerationError("boom")
         state = prefix.replace("pet_row_", "")
@@ -361,7 +399,7 @@ def test_hatch_pet_rejects_missing_required_animation_rows(monkeypatch, tmp_path
     base = tmp_path / "base.png"
     _strip(1).save(base)
 
-    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet"):
+    def fake_generate(prompt, *, n=1, reference_images=None, provider=None, prefix="pet", aspect_ratio="square"):
         if prefix == "pet_row_running-right":
             raise GenerationError("bad row")
         state = prefix.replace("pet_row_", "")
@@ -388,6 +426,48 @@ def test_resolve_provider_errors_without_backend(monkeypatch):
         imagegen.resolve_provider(require_references=True)
 
 
+class _FakeImgProvider:
+    def __init__(self, name, available=True):
+        self.name = name
+        self._available = available
+
+    def is_available(self):
+        return self._available
+
+
+def test_resolve_provider_honors_available_preference(monkeypatch):
+    """An explicit, configured, ref-capable preference wins over the active one."""
+    from agent.pet.generate import imagegen
+
+    registry = {"openai": _FakeImgProvider("openai"), "openrouter": _FakeImgProvider("openrouter")}
+    monkeypatch.setattr(imagegen, "_discover", lambda: None)
+    monkeypatch.setattr("agent.image_gen_registry.get_active_provider", lambda: registry["openai"])
+    monkeypatch.setattr("agent.image_gen_registry.get_provider", lambda name: registry.get(name))
+
+    assert imagegen.resolve_provider(prefer="openrouter").name == "openrouter"
+    # An unavailable / unknown preference is ignored — fall back to the active one.
+    registry["openrouter"]._available = False
+    assert imagegen.resolve_provider(prefer="openrouter").name == "openai"
+    assert imagegen.resolve_provider(prefer="not-a-provider").name == "openai"
+
+
+def test_list_sprite_providers_marks_default(monkeypatch):
+    """Lists only available ref-capable backends, flagging the default pick."""
+    from agent.pet.generate import imagegen
+
+    registry = {"openai": _FakeImgProvider("openai"), "nous": _FakeImgProvider("nous")}
+    monkeypatch.setattr(imagegen, "_discover", lambda: None)
+    monkeypatch.setattr("agent.image_gen_registry.get_active_provider", lambda: registry["openai"])
+    monkeypatch.setattr("agent.image_gen_registry.get_provider", lambda name: registry.get(name))
+
+    listed = imagegen.list_sprite_providers()
+    names = {p["name"] for p in listed}
+    assert names == {"openai", "nous"}
+    # Every entry carries display metadata, and exactly one is the default.
+    assert all(p["label"] and "note" in p for p in listed)
+    assert [p["name"] for p in listed if p["default"]] == ["openai"]
+
+
 def test_generate_retries_without_transparent_background(monkeypatch, tmp_path):
     """A model that rejects background=transparent still produces images."""
     from agent.pet.generate import imagegen

tests/tui_gateway/test_pet_generate_rpc.py

@@ -23,10 +23,32 @@ def test_pet_generate_requires_prompt():
     assert "error" in resp
 
 
+def test_pet_generate_rejects_invalid_reference_image():
+    resp = server._methods["pet.generate"](
+        "r_invalid_ref",
+        {"referenceImage": "data:image/svg+xml;base64,PHN2Zy8+"},
+    )
+    assert "error" in resp
+    assert "unsupported reference image type" in resp["error"]["message"]
+
+
+def test_pet_generate_rejects_oversized_reference_image(monkeypatch):
+    import base64
+
+    monkeypatch.setattr(server, "_PET_REFERENCE_MAX_BYTES", 8)
+    payload = base64.b64encode(b"0123456789").decode("ascii")
+    resp = server._methods["pet.generate"](
+        "r_big_ref",
+        {"referenceImage": f"data:image/png;base64,{payload}"},
+    )
+    assert "error" in resp
+    assert "too large" in resp["error"]["message"].lower()
+
+
 def test_pet_generate_returns_token_and_previews(monkeypatch, tmp_path):
     import agent.pet.generate as gen
 
-    def fake_drafts(prompt, *, n=4, style="auto", on_draft=None, is_cancelled=None):
+    def fake_drafts(prompt, *, n=4, style="auto", reference_images=None, provider=None, on_draft=None, is_cancelled=None):
         paths = []
         for i in range(n):
             p = tmp_path / f"d{i}.png"
@@ -66,7 +88,7 @@ def test_pet_generate_cancel_stops_run(monkeypatch, tmp_path):
 
     monkeypatch.setattr(server, "_emit", cap_emit)
 
-    def fake_drafts(prompt, *, n=4, style="auto", on_draft=None, is_cancelled=None):
+    def fake_drafts(prompt, *, n=4, style="auto", reference_images=None, provider=None, on_draft=None, is_cancelled=None):
         # Simulate a Stop landing mid-run: the cooperative flag must read True.
         server._pet_cancel_request(seen["token"])
         assert is_cancelled() is True
@@ -93,7 +115,7 @@ def test_pet_hatch_expired_draft():
 
 
 def _fake_drafts_factory(tmp_path):
-    def fake_drafts(prompt, *, n=4, style="auto", on_draft=None, is_cancelled=None):
+    def fake_drafts(prompt, *, n=4, style="auto", reference_images=None, provider=None, on_draft=None, is_cancelled=None):
         paths = []
         for i in range(n):
             p = tmp_path / f"d{i}.png"
@@ -178,3 +200,46 @@ def test_pet_hatch_then_adopt_activates(monkeypatch, tmp_path):
     adopt = server._methods["pet.select"]("r3", {"slug": hatched["slug"]})["result"]
     assert adopt["ok"]
     assert activated["slug"] == "my-fox"
+
+
+def test_pet_sprite_payload_includes_concrete_row_counts():
+    from agent.pet import constants, store
+
+    cols, rows = 8, 9
+    sheet = Image.new("RGBA", (constants.FRAME_W * cols, constants.FRAME_H * rows), (0, 0, 0, 0))
+    # Current Codex rows can have more/fewer frames than Hermes' generic
+    # FRAMES_PER_STATE. The desktop preview needs the concrete row count.
+    real = {0: 6, 1: 8, 3: 4, 4: 5, 7: 6}
+    for row, count in real.items():
+        for col in range(count):
+            block = Image.new("RGBA", (constants.FRAME_W, constants.FRAME_H), (80, 120, 220, 255))
+            sheet.paste(block, (col * constants.FRAME_W, row * constants.FRAME_H))
+
+    pet = store.register_local_pet(sheet, slug="row-counts", display_name="Row Counts")
+    payload = server._pet_sprite_payload(pet, scale=0.7)
+
+    assert payload["framesByRow"]["running-right"] == 8
+    assert payload["framesByRow"]["waving"] == 4
+    assert payload["framesByRow"]["jumping"] == 5
+    assert payload["framesByState"]["run"] == 6
+
+
+def test_pet_info_meta_avoids_full_payload(monkeypatch):
+    import hermes_cli.config as cli_config
+    from agent.pet import constants, store
+
+    sheet = Image.new("RGBA", (constants.FRAME_W * 8, constants.FRAME_H * 9), (80, 120, 220, 255))
+    pet = store.register_local_pet(sheet, slug="meta-pet", display_name="Meta Pet")
+    monkeypatch.setattr(
+        cli_config,
+        "load_config",
+        lambda: {"display": {"pet": {"enabled": True, "slug": pet.slug, "scale": 0.7}}},
+    )
+
+    resp = server._methods["pet.info.meta"]("r_meta", {})
+    result = resp["result"]
+    assert result["enabled"] is True
+    assert result["slug"] == pet.slug
+    assert result["displayName"] == "Meta Pet"
+    assert result["scale"] == 0.7
+    assert ":" in result["spritesheetRevision"]