ha-mcp-dev 9.1.0.dev3302__tar.gz → 9.1.0.dev3307__tar.gz

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3302
+Version: 9.1.0.dev3307
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3302"
+version = "9.1.0.dev3307"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3302"
+version = "9.1.0.dev3307"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/src/ha_mcp/backup_dashboards.py

@@ -21,8 +21,10 @@ from typing import Any
 from .backup_entity_ids import _manager
 from .client.rest_client import HomeAssistantCommandError, HomeAssistantError
 
-# Core's DASHBOARD_BASE_UPDATE_FIELDS: what lovelace/dashboards/update accepts.
-_SETTINGS_FIELDS = ("title", "icon", "require_admin", "show_in_sidebar")
+# Keys of Core's stored dashboard item that lovelace/dashboards/update does not
+# take. Without the component, which reads Core's update schema, a restore sends
+# back the rest of the item.
+_ROW_ONLY_FIELDS = ("id", "url_path", "mode")
 _DASHBOARD_KIND = "dashboard_settings"
 
 
@@ -169,16 +171,17 @@ async def restore_dashboard(client: Any, entity_id: str, config: Any) -> Any:
 async def _recreate(client: Any, row: dict[str, Any], body: Any) -> Any:
     bm = _manager()
     url_path = row["url_path"]
-    # The component's rows carry ``icon: None`` for an unset icon, which Core's
-    # create schema rejects; an omitted field takes Core's default.
+    # Rows captured by an older component carry ``icon: None`` for an unset
+    # icon, which Core's create schema rejects; an omitted field takes Core's
+    # default.
     fields = bm._strip_readonly(row, "id", "mode")
     create = {
         "type": "lovelace/dashboards/create",
         **{key: value for key, value in fields.items() if value is not None},
+        # The row is one Core already accepted, so its path needs no hyphen
+        # check (Core's own single-word dashboards: ``lovelace``, ``map``).
+        "allow_single_word": True,
     }
-    if "-" not in url_path:
-        # Core's own single-word dashboards (``lovelace``, ``map``) need this.
-        create["allow_single_word"] = True
     try:
         await bm._ws_send(client, create)
     except HomeAssistantCommandError as err:
@@ -197,21 +200,36 @@ async def _restore_settings(
 ) -> None:
     """Put back the row's settings after its config; ``icon: None`` clears it."""
     bm = _manager()
-    fields = {key: row[key] for key in _SETTINGS_FIELDS if key in row}
-    # Core's own list omits ``icon`` when none is stored; the component's sends None.
-    fields.setdefault("icon", None)
+    update_fields = await _update_fields(client)
+    if update_fields:
+        fields = {k: v for k, v in row.items() if k in update_fields}
+    else:
+        fields = {k: v for k, v in row.items() if k not in _ROW_ONLY_FIELDS}
+    if not update_fields or "icon" in update_fields:
+        # Core's list omits ``icon`` when none is stored; None clears a live one.
+        fields.setdefault("icon", None)
     update = {"type": "lovelace/dashboards/update", "dashboard_id": dashboard_id}
     try:
         await bm._ws_send(client, {**update, **fields})
     except bm._CAPTURE_TRANSIENT_ERRORS as err:
         raise bm.BackupRestoreError(
             f"The config of dashboard {row['url_path']} was restored, but its "
-            "settings (title, icon, sidebar, admin) may not have been.",
+            "settings may not have been.",
             apply_status="unknown",
             reason="settings_not_restored",
         ) from err
 
 
+async def _update_fields(client: Any) -> list[str] | None:
+    """The keys Core's ``lovelace/dashboards/update`` schema accepts, from the
+    component; ``None`` without a component that reports them."""
+    from .tools.tools_config_dashboards import _dashboards_via_component
+
+    result = await _dashboards_via_component(client, "list")
+    fields = result.get("update_fields") if result else None
+    return fields if isinstance(fields, list) else None
+
+
 async def _restore_default_store(client: Any, body: Any) -> dict[str, Any]:
     """Put the body in Core's default store, which the built-in panel reads."""
     if body is None:

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/src/ha_mcp/backup_manager.py

@@ -2179,16 +2179,16 @@ async def _dashboard_resource_like(client: Any, config: dict[str, Any]) -> Any:
 
 
 async def _restore_dashboard_resource(client: Any, entity_id: str, config: Any) -> Any:
-    # Core imported old ``resources:`` entries without a type (RESOURCE_FIELDS).
     payload = _strip_readonly(config, "id", "type")
-    if "type" in config:
+    if "type" in config:  # Core imported old ``resources:`` entries without one
         payload["res_type"] = config["type"]
     update = {"type": "lovelace/resources/update", "resource_id": entity_id}
-    try:
-        return await _ws_send(client, {**update, **payload})
-    except HomeAssistantCommandError as err:
-        if err.code != "not_found":  # not_found: deleted since the snapshot
-            raise
+    async with registry_update_lock("dashboard_resource", entity_id):  # the tool's lock
+        try:
+            return await _ws_send(client, {**update, **payload})
+        except HomeAssistantCommandError as err:
+            if err.code != "not_found":  # not_found: deleted since the snapshot
+                raise
     live = await _dashboard_resource_like(client, config)
     if live is not None:  # an earlier restore re-created it
         return live

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/src/ha_mcp/dashboard_screenshot/capture.py

@@ -26,6 +26,7 @@ from ..errors import ErrorCode, create_error_response
 from ..tools.helpers import raise_tool_error
 from .engine_compat import is_legacy_puppet
 from .provision import TOKEN_HINT, EngineKind, resolve_engine
+from .theme_check import check_requested_theme
 from .theme_guard import ThemeGuard
 
 logger = logging.getLogger(__name__)
@@ -886,6 +887,11 @@ async def capture_dashboard_images(
         render_timeout_seconds=render_timeout_seconds,
     )
     viewports = _capture_viewports(options)
+    theme_warnings = await check_requested_theme(
+        client, options.theme, options.dark_mode
+    )
+    if capture_warnings is not None:
+        capture_warnings.extend(theme_warnings)
 
     engine_target = await resolve_engine()
     engine_url = engine_target.url

ha_mcp_dev-9.1.0.dev3307/src/ha_mcp/dashboard_screenshot/theme_check.py

@@ -0,0 +1,78 @@
+"""Check a screenshot's requested theme against Home Assistant's own themes.
+
+The engine renders an unknown theme name as the default theme and reports no
+error, so the name is checked against Core's ``frontend/get_themes`` first.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..errors import ErrorCode, create_error_response
+from ..tools.helpers import raise_tool_error
+from ..tools.util_helpers import websocket_error_message
+
+logger = logging.getLogger(__name__)
+
+# The frontend's built-in theme; Core's theme list holds only installed ones.
+_BUILT_IN_THEME = "default"
+
+
+def _unchecked(theme: str, reason: str) -> list[str]:
+    return [
+        f"Home Assistant's theme list could not be read ({reason}), so theme "
+        f"{theme!r} was not checked; an unknown name renders the default theme."
+    ]
+
+
+async def check_requested_theme(
+    client: Any, theme: str | None, dark_mode: bool
+) -> list[str]:
+    """Refuse a theme Home Assistant does not have.
+
+    Returns warnings for a theme list that could not be read and for a
+    ``dark_mode`` naming a mode the theme's data does not define.
+    """
+    if theme is None or client is None or theme == _BUILT_IN_THEME:
+        return []
+    try:
+        result = await client.send_websocket_message({"type": "frontend/get_themes"})
+    except Exception as exc:  # an optional pre-check must not fail the render
+        logger.warning(
+            "frontend/get_themes failed; theme %r not checked: %s",
+            theme,
+            exc,
+            exc_info=True,
+        )
+        return _unchecked(theme, str(exc))
+    if isinstance(result, dict) and result.get("success") is False:
+        return _unchecked(theme, websocket_error_message(result.get("error")))
+    listing = result.get("result") if isinstance(result, dict) else None
+    themes = listing.get("themes") if isinstance(listing, dict) else None
+    if not isinstance(themes, dict):
+        return _unchecked(theme, "unexpected response")
+    if theme not in themes:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                f"Home Assistant has no theme named {theme!r}",
+                context={"installed_themes": [_BUILT_IN_THEME, *themes]},
+                suggestions=["Use one of installed_themes, or omit theme"],
+            )
+        )
+    entry = themes[theme]
+    modes = entry.get("modes") if isinstance(entry, dict) else None
+    if not isinstance(modes, dict):
+        modes = {}
+    if dark_mode and "dark" not in modes:
+        return [
+            f"Theme {theme!r} defines no dark mode in Home Assistant's theme "
+            "list, so dark_mode=true has no dark variant to use."
+        ]
+    if not dark_mode and modes and "light" not in modes:
+        return [
+            f"Theme {theme!r} defines only a dark mode in Home Assistant's theme "
+            "list, so dark_mode=false has no light variant to use."
+        ]
+    return []

{ha_mcp_dev-9.1.0.dev3302 → ha_mcp_dev-9.1.0.dev3307}/src/ha_mcp/tools/auto_backup.py

@@ -44,6 +44,7 @@ from ..backup_manager import (
 from ..config import get_global_settings
 from ..errors import TOOL_ERROR_LOG_LEVEL, ErrorCode, create_error_response
 from .helpers import raise_tool_error
+from .resource_patch import resource_write_lock
 
 logger = logging.getLogger(__name__)
 
@@ -398,11 +399,19 @@ def with_auto_backup(
 async def _template_write_context(
     client: Any, settings: Any, domain: str, entity_id: str
 ) -> AsyncIterator[None]:
-    """Keep a helper edit's capture and mutation in the restore critical section.
-
-    The lock is needed even when ordinary auto-backup is disabled: restores
-    of existing flow helpers require a safety snapshot before replacing
-    their current options.
+    """Keep a write's capture and mutation in one critical section.
+
+    Flow helpers and integrations share the restore critical section. The lock
+    is needed even when ordinary auto-backup is disabled: restores of existing
+    flow helpers require a safety snapshot before replacing their current
+    options.
+
+    Dashboard resources take their per-resource write lock here, so the
+    snapshot, the tool's own read (an ``edits=`` patch) and its write cannot
+    interleave with another write through this server. Writes from the Home
+    Assistant UI or other processes are not serialized, so the snapshot can
+    predate an edit made there that the write then replaces. The resource
+    tools must not take the lock again: ``asyncio.Lock`` is not reentrant.
     """
     # Both options-update tools take stable config-entry IDs. Alias-based helper
     # removal and dotted subentry targets have separate resolution paths.
@@ -413,6 +422,9 @@ async def _template_write_context(
         manager = get_backup_manager(client, settings)
         async with manager.config_entry_write_guard(entity_id):
             yield
+    elif domain == "dashboard_resource" and entity_id:
+        async with resource_write_lock(entity_id):
+            yield
     else:
         yield
 

ha_mcp_dev-9.1.0.dev3307/src/ha_mcp/tools/resource_codec.py

@@ -0,0 +1,356 @@
+"""Inline dashboard-resource codec: ``data:`` URI encoding/decoding and list rendering.
+
+Pure functions shared by the resource tools. Kept apart from
+``tools_resources`` so the tool module holds only the MCP surface.
+"""
+
+import base64
+import hashlib
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+from ..errors import ErrorCode, create_error_response
+from .helpers import raise_tool_error
+
+# Legacy Cloudflare Worker URL. Only used to recognize and locally decode
+# inline resources created before the data: URI switch (#2060) — this server
+# never fetches it. The worker deployment stays up so pre-existing dashboards
+# keep loading until their resources are converted.
+LEGACY_WORKER_BASE_URL = "https://ha-mcp-resources.rapid-math-bbad.workers.dev"
+
+# data: URI media types per inline resource_type ('js'/'html' are url-mode
+# only). CSS carries an explicit charset because stylesheets, unlike module
+# scripts, have no spec-mandated UTF-8 fallback.
+_DATA_URI_MIME: dict[str, str] = {
+    "module": "text/javascript",
+    "css": "text/css;charset=utf-8",
+}
+
+# URL prefixes recognized as ha-mcp inline resources — DERIVED from the media
+# types above rather than restated, so the read side cannot drift from the
+# write side (a desync would make the server fail to recognize its own
+# output, leaking raw base64 URLs into list responses). Each media type is
+# accepted with and without the charset parameter so resources written
+# before and after a charset change both still decode. Foreign data: URLs
+# match nothing here and pass through untouched instead of being claimed.
+_ALLOWED_DATA_URI_PREFIXES = tuple(
+    f"data:{base}{charset};base64,"
+    # dict.fromkeys dedupes while keeping a deterministic order.
+    for base in dict.fromkeys(mime.split(";", 1)[0] for mime in _DATA_URI_MIME.values())
+    for charset in ("", ";charset=utf-8")
+)
+# Scheme and media type are case-insensitive (RFC 3986/2397); prefixes are
+# lowercase, so matching lowercases the URL head. Longest prefix is 42 chars.
+_DATA_URI_HEAD = max(len(p) for p in _ALLOWED_DATA_URI_PREFIXES)
+
+_B64_URLSAFE_RE = re.compile(r"[A-Za-z0-9_-]*={0,2}")
+
+# Longest data: URL echoed verbatim for a resource we cannot decode.
+# Beyond this the value is truncated: a corrupt or foreign payload can be
+# ~171KB of base64, and echoing it whole would flood the response.
+_MAX_ECHOED_URL = 300
+
+# Characters of decoded content shown in list previews.
+_PREVIEW_LENGTH = 150
+
+# Total decoded content emitted per include_content=True response. A page
+# of max-size resources would otherwise return limit x MAX_CONTENT_SIZE
+# (up to ~64MB). Rows past the budget are FLAGGED, never shortened —
+# handing back a silently-truncated payload is how a resource gets
+# destroyed on write-back.
+_MAX_CONTENT_BUDGET = 512_000
+
+# Maximum inline content size, in UTF-8 bytes. The old 24KB bound was the
+# content budget derived from the worker's ~32KB encoded URL-path limit;
+# data: URIs impose no comparable limit, so the cap is now sized to fit
+# established single-file card bundles without truncation while bounding
+# what every dashboard load ships (the registered URL rides the Lovelace
+# bootstrap to every browser) and what auto-backup snapshots per edit.
+MAX_CONTENT_SIZE = 128_000
+
+
+def content_sha256(content: str) -> str:
+    """SHA-256 hex digest over the UTF-8 bytes of decoded resource content."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _data_uri_for(content: str, resource_type: str) -> str:
+    """Encode content as a base64 ``data:`` URI for the given resource type.
+
+    Standard base64 (not URL-safe): browsers decode data: URIs with the
+    standard alphabet. Deterministic — same content, same URI.
+    """
+    mime = _DATA_URI_MIME.get(resource_type)
+    if mime is None:
+        raise_tool_error(
+            create_error_response(
+                code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                message=f"Inline content does not support resource_type={resource_type!r}",
+                suggestions=["Use resource_type='module' or 'css' for inline content"],
+            )
+        )
+    encoded = base64.b64encode(content.encode("utf-8")).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+
+def _match_data_uri_prefix(url: str) -> str | None:
+    """Return the matched ha-mcp inline data: prefix of ``url``, else None.
+
+    Prefix matching is case-insensitive (scheme and media type are
+    case-insensitive per RFC 3986/2397); the payload's case is preserved.
+    """
+    head = url[:_DATA_URI_HEAD].lower()
+    for prefix in _ALLOWED_DATA_URI_PREFIXES:
+        if head.startswith(prefix):
+            return prefix
+    return None
+
+
+def _decode_data_uri(url: str) -> str | None:
+    """Decode one of our base64 ``data:`` URIs back to content.
+
+    None for foreign data: URLs (other media types, percent-encoded form) —
+    those are passed through untouched, not claimed as inline resources —
+    and for corrupt payloads (``validate=True``: a payload the browser's
+    forgiving-base64 would reject must not be reported as valid content).
+    """
+    prefix = _match_data_uri_prefix(url)
+    if prefix is None:
+        return None
+    try:
+        return base64.b64decode(url[len(prefix) :], validate=True).decode("utf-8")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _is_data_url(url: str) -> bool:
+    """True when ``url`` parses as the ``data:`` scheme in a browser.
+
+    ``urlsplit`` applies WHATWG's leading C0-control-or-space strip and
+    ASCII tab/newline/CR removal before reading the scheme (the
+    CVE-2023-24329 hardening; this package requires Python >=3.13), and
+    lowercases it. A raw ``url[:5]`` check would miss ``" data:..."`` and
+    ``"da\\tta:..."``, which browsers still load.
+    """
+    return urlsplit(url).scheme == "data"
+
+
+def _pad_b64(encoded: str) -> str:
+    """Reject non-alphabet characters, then restore any stripped ``=`` padding.
+
+    ``urlsafe_b64decode`` has no ``validate=`` parameter, so strictness has
+    to be enforced here; the padding fix-up keeps genuine worker URLs (which
+    always carried padding) working either way.
+    """
+    if not _B64_URLSAFE_RE.fullmatch(encoded):
+        raise ValueError("non-base64 characters in payload")
+    return encoded + "=" * (-len(encoded) % 4)
+
+
+def _has_inline_url_shape(url: str) -> bool:
+    """True when ``url`` LOOKS like one of ours, regardless of decodability.
+
+    Only used to flag a recognized-but-corrupt payload; the decode result
+    itself (never this) decides what counts as an inline resource.
+    """
+    if _match_data_uri_prefix(url) is not None:
+        return True
+    prefix = f"{LEGACY_WORKER_BASE_URL}/"
+    return url[: len(prefix)].lower() == prefix.lower()
+
+
+def _looks_like_preview(content: str) -> bool:
+    """Cheap pre-filter: could ``content`` be a list-tool ``_preview``?
+
+    Previews are ``_PREVIEW_LENGTH`` characters plus a trailing ``"..."``.
+    Two shapes qualify: that signature itself (tolerating surrounding
+    whitespace), and exactly ``_PREVIEW_LENGTH`` characters, which is what
+    an agent produces by stripping the ellipsis.
+
+    Deliberately narrow. Everything matching pays a WS round-trip and, if
+    that round-trip fails, is refused — so matching ordinary short content
+    (a legitimate 20-character CSS tweak) would make routine updates
+    fragile for no safety gain, since such content cannot be a preview of
+    anything.
+    """
+    stripped = content.strip()
+    if stripped.endswith("...") and len(stripped) <= _PREVIEW_LENGTH + 3:
+        return True
+    return len(stripped) == _PREVIEW_LENGTH
+
+
+def _is_preview_of(content: str, stored: str) -> bool:
+    """True when ``content`` is the truncated preview of ``stored``.
+
+    Tolerates the ellipsis being stripped and surrounding whitespace, so a
+    lightly-mangled preview writeback is still caught.
+    """
+    if len(stored) <= _PREVIEW_LENGTH:
+        # Short resources have no truncated preview to confuse with.
+        return False
+    candidate = content.strip().removesuffix("...")
+    return bool(candidate) and stored.startswith(candidate)
+
+
+def _decode_inline_content(url: str) -> tuple[str, bool] | None:
+    """Decode an inline resource URL to ``(content, is_legacy_worker)``.
+
+    ``None`` when the URL is not one of ours, or is one of ours but holds
+    an empty/corrupt payload. This is the single source of truth for "is
+    this an inline resource we can show", so the list summary counts and
+    the per-resource markers can never disagree. Returning one ``None``
+    rather than a ``(None, bool)`` pair keeps the meaningless
+    "not-ours-but-legacy" combination unrepresentable and forces callers
+    through one check instead of indexing the tuple.
+    """
+    content = _decode_data_uri(url)
+    if content:
+        return content, False
+    legacy = _decode_legacy_worker_url(url)
+    if legacy:
+        return legacy, True
+    return None
+
+
+def _decode_legacy_worker_url(url: str) -> str | None:
+    """Decode a legacy worker inline URL back to content (pure local base64).
+
+    The worker embedded URL-safe base64 in its path; decoding needs no
+    network. Anchored to the worker origin — lookalike hosts that merely
+    contain the worker host string are not decoded. Returns None if the URL
+    is not a legacy worker URL.
+    """
+    prefix = f"{LEGACY_WORKER_BASE_URL}/"
+    # Scheme and host are case-insensitive; the base64 payload is not.
+    if url[: len(prefix)].lower() != prefix.lower():
+        return None
+    try:
+        # Extract base64 part: https://worker.dev/{base64}?type=module
+        encoded = url[len(prefix) :].split("?", maxsplit=1)[0]
+        # validate=True mirrors _decode_data_uri: urlsafe_b64decode otherwise
+        # silently DISCARDS non-alphabet characters, so a junk path could
+        # decode to plausible text and be masked as inline content.
+        return base64.urlsafe_b64decode(_pad_b64(encoded)).decode("utf-8")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _summarize_resources(
+    resources: list[Any],
+    keep_start: int,
+    keep_stop: int,
+) -> tuple[dict[str, int], int, dict[int, tuple[str, bool]]]:
+    """Count resources by type, and decode every inline one exactly once.
+
+    Returns ``(by_type_counts, inline_count, {index: (content, is_legacy)})``.
+
+    Decoding is deliberately WHOLE-SET: ``inline_count`` reports the full
+    registry and must agree with the per-resource ``_inline`` markers, and
+    only a real decode can tell a genuine inline resource from a corrupt
+    payload that merely looks like one.
+
+    RETENTION, by contrast, is page-scoped: only indices in
+    ``[keep_start, keep_stop)`` are kept in the returned map. Holding every
+    decoded payload would mean a ``limit=1`` call sat on the whole
+    registry's content — up to ``MAX_CONTENT_SIZE`` per resource — for a
+    one-row response. Because the page's entries are retained, nothing is
+    decoded twice.
+    """
+    by_type_counts: dict[str, int] = {}
+    inline_count = 0
+    decoded_by_index: dict[int, tuple[str, bool]] = {}
+    for index, resource in enumerate(resources):
+        res = resource if isinstance(resource, dict) else {}
+        res_type = res.get("type")
+        if isinstance(res_type, str):
+            by_type_counts[res_type] = by_type_counts.get(res_type, 0) + 1
+        url = res.get("url", "")
+        if isinstance(url, str):
+            decoded = _decode_inline_content(url)
+            if decoded:
+                inline_count += 1
+                if keep_start <= index < keep_stop:
+                    decoded_by_index[index] = decoded
+    return by_type_counts, inline_count, decoded_by_index
+
+
+def _process_resource_list(
+    resources: list[Any],
+    decoded_page: list[tuple[str, bool] | None],
+    include_content: bool,
+    *,
+    include_hash: bool = False,
+) -> tuple[list[dict[str, Any]], int]:
+    """Render one page of resources. Returns ``(rows, truncated_count)``.
+
+    ``decoded_page`` carries the already-decoded ``(content, is_legacy)`` for
+    each row (``None`` when the resource is not a decodable inline one), so
+    this never re-decodes and can never classify a resource differently than
+    the caller's summary did.
+
+    With ``include_content``, content is emitted until the per-response byte
+    budget is spent; rows past it are marked ``_content_truncated`` rather
+    than silently shortened, because a truncated value written back would
+    destroy the resource.
+    """
+    processed: list[dict[str, Any]] = []
+    truncated_count = 0
+    content_budget = _MAX_CONTENT_BUDGET
+
+    for resource, decoded in zip(resources, decoded_page, strict=True):
+        res = dict(resource) if isinstance(resource, dict) else {"url": resource}
+        url = res.get("url", "")
+        content, is_legacy = decoded if decoded else (None, False)
+
+        if content:
+            content_bytes = len(content.encode("utf-8"))
+            res["_inline"] = True
+            res["_size"] = content_bytes
+            if include_hash:
+                res["_config_hash"] = content_sha256(content)
+            if is_legacy:
+                # The full remediation text lives once at response level;
+                # repeating it per resource wasted ~330 chars each.
+                res["_legacy_worker"] = True
+
+            if include_content:
+                cost = content_bytes
+                if cost <= content_budget:
+                    res["_content"] = content
+                    content_budget -= cost
+                else:
+                    res["_content_truncated"] = True
+                    truncated_count += 1
+            else:
+                preview = content[:_PREVIEW_LENGTH]
+                if len(content) > _PREVIEW_LENGTH:
+                    preview += "..."
+                res["_preview"] = preview
+
+            res["url"] = "[inline]"
+        elif isinstance(url, str) and _has_inline_url_shape(url):
+            # Recognized as one of ours but the payload does not decode
+            # (empty, corrupt, or not UTF-8). Say so explicitly: without a
+            # marker this reads as "an external resource, not my problem",
+            # which is the wrong conclusion for someone debugging a card
+            # that stopped rendering. The real URL stays visible (truncated
+            # if huge) because that is what diagnosis needs.
+            res["_decode_error"] = True
+            if len(url) > _MAX_ECHOED_URL:
+                res["_url_length"] = len(url)
+                res["url"] = url[:_MAX_ECHOED_URL] + "…[truncated]"
+
+        processed.append(res)
+    return processed, truncated_count
+
+
+def _check_ws_error(result: Any) -> str | None:
+    """Check a WebSocket result for errors. Returns error message or None."""
+    if isinstance(result, dict) and not result.get("success", True):
+        error = result.get("error", {})
+        if isinstance(error, dict):
+            msg: str = error.get("message", str(error)) or "Unknown error"
+            return msg
+        return str(error) or "Unknown error"
+    return None