From aad5490e749319d2f8fbcce3a92ee7aaa3d2aacc Mon Sep 17 00:00:00 2001
From: qWaitCrypto <axmaiqiu@gmail.com>
Date: Fri, 8 May 2026 21:36:14 +0800
Subject: [PATCH] fix(webui): add platform hint for MEDIA rendering

WebUI sessions construct AIAgent(platform="webui") but PLATFORM_HINTS
had no "webui" entry, so the agent received no platform hint at all.
The WebUI frontend supports rich MEDIA:/absolute/path previews for
images, audio, video, PDF, HTML, CSV, diffs, and Excalidraw, but
without a hint the agent either ignores MEDIA: or falls back to
Markdown image syntax which silently fails for local files.

Add a webui hint that documents the MEDIA: render path and warns
against ![alt](/path) for local files.

Fixes #21883
---
 agent/prompt_builder.py            | 12 ++++++++++++
 tests/agent/test_prompt_builder.py |  8 ++++++++
 2 files changed, 20 insertions(+)

diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index d60c72562ff..d7542e14157 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -564,6 +564,18 @@ PLATFORM_HINTS = {
         "code fences). Treat this like a conversation, not a document. Keep responses "
         "brief and natural."
     ),
+    "webui": (
+        "You are in the Hermes WebUI, a browser-based chat interface. "
+        "Full Markdown rendering is supported — headings, bold, italic, code "
+        "blocks, tables, math (LaTeX), and Mermaid diagrams all render natively. "
+        "To display local or remote media/files inline, include "
+        "MEDIA:/absolute/path/to/file or MEDIA:https://... in your response. "
+        "Local file paths must be absolute. Images, audio (with playback speed "
+        "controls), video, PDFs, HTML, CSV, diffs/patches, and Excalidraw files "
+        "render as rich previews. Do not use Markdown image syntax like "
+        "![alt](/path) for local files; local paths are not served that way. "
+        "Use MEDIA:/path instead."
+    ),
 }
 
 # ---------------------------------------------------------------------------
diff --git a/tests/agent/test_prompt_builder.py b/tests/agent/test_prompt_builder.py
index b475c591b2c..936aff16bff 100644
--- a/tests/agent/test_prompt_builder.py
+++ b/tests/agent/test_prompt_builder.py
@@ -789,6 +789,7 @@ class TestPromptBuilderConstants:
         assert "cron" in PLATFORM_HINTS
         assert "cli" in PLATFORM_HINTS
         assert "api_server" in PLATFORM_HINTS
+        assert "webui" in PLATFORM_HINTS
 
     def test_cli_hint_does_not_suggest_media_tags(self):
         # Regression: MEDIA:/path tags are intercepted only by messaging
@@ -826,6 +827,13 @@ class TestPromptBuilderConstants:
         assert "MEDIA:" in hint
         assert "Markdown" in hint
 
+    def test_platform_hints_webui(self):
+        hint = PLATFORM_HINTS["webui"]
+        assert "WebUI" in hint
+        assert "MEDIA:" in hint
+        assert "Markdown" in hint
+        assert "absolute" in hint
+
 
 # =========================================================================
 # Environment hints