fix(image_gen): cache xAI ephemeral URL responses to disk (#26942) (#31759)

xAI's grok-imagine-image API returns ephemeral imgen.x.ai/xai-tmp-* URLs
that 404 within minutes — long before downstream consumers (Telegram
send_photo, browser preview, multi-tier delivery fallback) get a chance
to fetch them.  The xAI image_gen provider was passing those URLs
through unchanged on the elif url: branch; b64 responses were already
cached locally via save_b64_image.  Result: every image_generate call
on a Telegram-routed xai-oauth profile delivered no image, falling
through to text-only.

Adds agent.image_gen_provider.save_url_image() — a sibling helper to
save_b64_image that downloads URL bytes to $HERMES_HOME/cache/images/.
Content-type-aware extension inference with URL-suffix fallback;
oversize cap (25MB default) with partial-write cleanup; empty-body
refusal.  Mirrors the audio_cache pattern used by text_to_speech.

Wires save_url_image into both the xAI and OpenAI providers' URL
branches.  When the download fails (network blip, 404 in-flight) we
log a warning and fall back to the bare URL rather than turning the
tool call into a hard error — the gateway's existing URL-send fallback
then gets a chance to surface the original error legibly.

Test plan:
- tests/agent/test_save_url_image.py — 8 direct tests against a real
  in-process HTTP server: bytes round-trip, content-type → extension,
  URL-suffix fallback, default-to-png, 404 propagation, empty-body
  refusal, oversize cap + cleanup, filename uniqueness.
- tests/plugins/image_gen/test_xai_provider.py — flip
  test_successful_url_response (was asserting the bug), add
  test_url_response_falls_back_to_bare_url_when_download_fails.
- tests/plugins/image_gen/test_openai_provider.py — symmetric pair.

160/160 in the broader image_gen test surface.

tests/plugins/image_gen/test_openai_provider.py

@@ -229,14 +229,43 @@ class TestGenerate:
         assert result["success"] is False
         assert result["error_type"] == "empty_response"
 
-    def test_url_fallback_if_api_changes(self, provider):
-        """Defensive: if OpenAI ever returns URL instead of b64, pass through."""
+    def test_url_response_is_cached_locally(self, provider):
+        """OpenAI URL response (if API ever returns one) is cached locally.
+
+        Pre-fix this asserted the bare URL passed through; symmetric to the
+        xAI #26942 fix.  Even though gpt-image-2 returns b64 today, every
+        ``image_gen`` provider must guarantee the gateway gets a stable
+        file path so ephemeral signed URLs can't expire mid-flight.
+        """
         fake_client = MagicMock()
         fake_client.images.generate.return_value = _fake_response(
             b64=None, url="https://example.com/img.png",
         )
 
-        with _patched_openai(fake_client):
+        with _patched_openai(fake_client), patch(
+            "plugins.image_gen.openai.save_url_image",
+            return_value=Path("/tmp/openai_gpt-image-2_20260524_000000_deadbeef.png"),
+        ) as mock_save_url:
+            result = provider.generate("a cat")
+
+        assert result["success"] is True
+        assert result["image"].startswith("/")
+        assert "example.com" not in result["image"]
+        mock_save_url.assert_called_once()
+
+    def test_url_response_falls_back_to_bare_url_when_download_fails(self, provider):
+        """Cache failure must not turn into a tool error — symmetric with xAI."""
+        import requests as req_lib
+
+        fake_client = MagicMock()
+        fake_client.images.generate.return_value = _fake_response(
+            b64=None, url="https://example.com/img.png",
+        )
+
+        with _patched_openai(fake_client), patch(
+            "plugins.image_gen.openai.save_url_image",
+            side_effect=req_lib.HTTPError("404 from CDN"),
+        ):
             result = provider.generate("a cat")
 
         assert result["success"] is True

tests/plugins/image_gen/test_xai_provider.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import json
 import os
+from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -142,21 +143,75 @@ class TestGenerate:
         assert result["model"] == "grok-imagine-image"
 
     def test_successful_url_response(self):
+        """xAI URL response is cached locally — #26942 contract.
+
+        Pre-fix this asserted ``result["image"] == "<the bare URL>"``, which
+        was exactly the bug: xAI's ``imgen.x.ai/xai-tmp-*`` URLs expire fast
+        and the gateway 404'd by ``send_photo`` time.  Post-fix the URL
+        bytes are downloaded at tool-completion and the result carries an
+        absolute filesystem path the gateway can upload from.
+        """
         from plugins.image_gen.xai import XAIImageGenProvider
 
         mock_resp = MagicMock()
         mock_resp.status_code = 200
         mock_resp.raise_for_status = MagicMock()
         mock_resp.json.return_value = {
-            "data": [{"url": "https://xai.image/result.png"}],
+            "data": [{"url": "https://imgen.x.ai/xai-tmp-imgen-test.jpeg"}],
         }
 
-        with patch("plugins.image_gen.xai.requests.post", return_value=mock_resp):
+        with patch("plugins.image_gen.xai.requests.post", return_value=mock_resp), \
+             patch(
+                 "plugins.image_gen.xai.save_url_image",
+                 return_value=Path("/tmp/xai_grok-imagine-image_20260524_000000_deadbeef.jpg"),
+             ) as mock_save_url:
             provider = XAIImageGenProvider()
             result = provider.generate(prompt="A cat playing piano")
 
         assert result["success"] is True
-        assert result["image"] == "https://xai.image/result.png"
+        assert result["image"].startswith("/"), (
+            f"URL response must be cached to an absolute path, got {result['image']!r}"
+        )
+        assert "imgen.x.ai" not in result["image"], (
+            "ephemeral xAI URL must not leak into result.image — caller will 404"
+        )
+        # The downloader should have been called exactly once with the URL
+        # and an xai-prefixed cache filename.
+        mock_save_url.assert_called_once()
+        call_args, call_kwargs = mock_save_url.call_args
+        assert call_args[0] == "https://imgen.x.ai/xai-tmp-imgen-test.jpeg"
+        assert call_kwargs.get("prefix", "").startswith("xai_")
+
+    def test_url_response_falls_back_to_bare_url_when_download_fails(self):
+        """If caching the URL fails (network blip, 404 in-flight), the
+        provider must NOT hard-error — fall through to returning the bare
+        URL so the agent surface at least sees *something*.  The gateway's
+        existing URL-send fallback then has a chance to succeed; if it
+        too 404s, the user gets the original (now legible) error rather
+        than an opaque "image generation failed" tool result.
+        """
+        import requests as req_lib
+        from plugins.image_gen.xai import XAIImageGenProvider
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.raise_for_status = MagicMock()
+        mock_resp.json.return_value = {
+            "data": [{"url": "https://imgen.x.ai/xai-tmp-imgen-already-404.jpeg"}],
+        }
+
+        with patch("plugins.image_gen.xai.requests.post", return_value=mock_resp), \
+             patch(
+                 "plugins.image_gen.xai.save_url_image",
+                 side_effect=req_lib.HTTPError("404 from CDN"),
+             ):
+            provider = XAIImageGenProvider()
+            result = provider.generate(prompt="A cat playing piano")
+
+        assert result["success"] is True, (
+            "Cache failure must not turn into a tool error — gateway gets a chance to retry"
+        )
+        assert result["image"] == "https://imgen.x.ai/xai-tmp-imgen-already-404.jpeg"
 
     def test_api_error(self):
         import requests as req_lib