@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/gateway/platforms/yuanbao.py

@@ -18,6 +18,8 @@ Configuration in config.yaml (or via env vars):
 from __future__ import annotations
 
 import asyncio
+import base64
+import binascii
 import collections
 import dataclasses
 import hashlib
@@ -31,9 +33,10 @@ import time
 import urllib.parse
 import uuid
 from datetime import datetime, timezone, timedelta
+from enum import Enum
 from pathlib import Path
 from abc import ABC, abstractmethod
-from typing import Any, Callable, ClassVar, Dict, List, Optional, Tuple
+from typing import Any, Callable, ClassVar, Dict, Iterator, List, Optional, Tuple
 
 import sys
 
@@ -55,6 +58,7 @@ from gateway.platforms.base import (
     SendResult,
     cache_document_from_bytes,
     cache_image_from_bytes,
+    cache_video_from_bytes,
 )
 from gateway.platforms.helpers import MessageDeduplicator
 from gateway.platforms.yuanbao_media import (
@@ -77,6 +81,7 @@ from gateway.platforms.yuanbao_proto import (
     HERMES_INSTANCE_ID,
     decode_conn_msg,
     decode_inbound_push,
+    decode_forward_msg_data,
     decode_query_group_info_rsp,
     decode_get_group_member_list_rsp,
     encode_auth_bind,
@@ -120,6 +125,16 @@ AUTH_TIMEOUT_SECONDS = 10.0
 MAX_RECONNECT_ATTEMPTS = 100
 DEFAULT_SEND_TIMEOUT = 30.0  # WS biz request timeout
 
+# Upper bound on the WS close handshake during teardown (#40383). The
+# websockets connection's own close_timeout (5s) blocks until the server
+# echoes the close frame; an idle/unresponsive server never replies, stalling
+# gateway shutdown by the full timeout. Bounding the close await here keeps
+# teardown fast — a responsive server completes the handshake in well under a
+# second, so this only caps the pathological hang. Also bounds the reconnect /
+# connect-failure cleanup paths that reuse _cleanup_ws(), where a graceful
+# close is unnecessary anyway (the socket is being discarded to redial).
+WS_CLOSE_TIMEOUT_S = 1.0
+
 # Close codes that indicate permanent errors — do NOT reconnect.
 NO_RECONNECT_CLOSE_CODES = {4012, 4013, 4014, 4018, 4019, 4021}
 
@@ -147,8 +162,14 @@ _YB_RES_REF_RE = re.compile(
     r"\[(image|voice|video|file(?::[^|\]]*)?)\|ybres:([A-Za-z0-9_\-]+)\]"
 )
 
+# Patched local-media anchors once an inbound resource has been downloaded to the local cache. 
+#   [image: /opt/data/image_cache/img_xxx.bmp]
+#   [file: report.pdf → /opt/data/.../report.pdf]
+#   (and any future kind, e.g. [video: /opt/.../clip.mp4])
+_YB_LOCAL_MEDIA_RE = re.compile(r"\[(\w+):[^\]]*?(/[^\]]+?)\s*\]")
+
 # Media kinds that can be resolved and injected into the model context
-_RESOLVABLE_MEDIA_KINDS = frozenset({"image", "file"})
+_RESOLVABLE_MEDIA_KINDS = frozenset({"image", "file", "video"})
 
 # Strip page indicators like (1/3) appended by BasePlatformAdapter
 _INDICATOR_RE = re.compile(r'\s*\(\d+/\d+\)$')
@@ -916,6 +937,10 @@ class InboundContext:
     raw_text: str = ""
     media_refs: list = dc_field(default_factory=list)
 
+    # Populated by ExtractContentMiddleware for elem_type 1009 (WeChat forward).
+    # Contains the parsed ForwardMsgData dict (sub_type / nick_name / msg list).
+    forwarded_records: Optional[dict] = None
+
     # Owner command detection
     owner_command: Optional[str] = None
 
@@ -923,14 +948,18 @@ class InboundContext:
     source: Optional[Any] = None  # SessionSource
 
     # Populated by ClassifyMessageTypeMiddleware
-    msg_type: Optional[Any] = None  # MessageType
+    msg_type: Optional[Any] = None  # MessageType | YuanbaoMessageType
 
     # Populated by QuoteContextMiddleware
     reply_to_message_id: Optional[str] = None
     reply_to_text: Optional[str] = None
     quote_media_refs: list = dc_field(default_factory=list)  # List of (rid, kind, filename)
 
-    # Populated by MediaResolveMiddleware
+    # Populated by MediaResolveMiddleware. Combined list of resolved local
+    # paths from up to three sources (deduped, in this order):
+    #   1) media carried by the current message (always),
+    #   2) media from the quoted message (when reply_to_message_id is set),
+    #   3) recent group-observed media (only when chat_type == "group" and no quote is present).
     media_urls: list = dc_field(default_factory=list)
     media_types: list = dc_field(default_factory=list)
 
@@ -1675,10 +1704,10 @@ class ExtractContentMiddleware(InboundMiddleware):
         """Extract plain text content from MsgBody.
 
         - TIMTextElem      -> text field
-        - TIMImageElem     -> "[image]"
-        - TIMFileElem      -> "[file: {filename}]"
-        - TIMSoundElem     -> "[voice]"
-        - TIMVideoFileElem -> "[video]"
+        - TIMImageElem     -> "[image]" / "[image|ybres:RID]"
+        - TIMFileElem      -> "[file: {filename}]" / "[file:{name}|ybres:RID]"
+        - TIMSoundElem     -> "[voice]" / "[voice|ybres:RID]"
+        - TIMVideoFileElem -> "[video]" / "[video|ybres:RID]"
         - TIMFaceElem      -> "[emoji: {name}]" or "[emoji]"
         - TIMCustomElem    -> try to extract data field, otherwise "[custom message]"
         - Multiple elems joined with spaces
@@ -1741,6 +1770,9 @@ class ExtractContentMiddleware(InboundMiddleware):
                                 parts.append(text)
                             else:
                                 parts.append("[unsupported message type]")
+                        elif ctype == 1009:
+                            # WeChat forwarded chat record: use the truncated summary text.
+                            parts.append(custom.get("text", "[chat record]"))
                         else:
                             parts.append("[unsupported message type]")
                     except (json.JSONDecodeError, TypeError):
@@ -1852,10 +1884,70 @@ class ExtractContentMiddleware(InboundMiddleware):
                         pass
         return urls
 
+    @staticmethod
+    def _extract_forwarded_records(msg_body: list, user_id: str = "") -> Optional[dict]:
+        """Extract ForwardMsgData from ext_map for elem_type 1009 (WeChat forward).
+
+        The detailed chat-record payload lives in ``msg_content.ext_map``
+        (protobuf field 999, ``map<string, string>``):
+          - key format: ``wexin_forward_msg_[forward_msg_id]_[userid]``
+          - value: a **base64-encoded protobuf** ``ForwardMsgData`` (NOT JSON).
+            Decode with base64 then ``decode_forward_msg_data`` to recover the
+            ``sub_type`` / ``nick_name`` / ``msg`` structure.
+
+        Matching strategy: take the first ``wexin_forward_msg_`` entry whose
+        decoded payload is a valid ``ForwardMsgData`` (``sub_type == 1``).
+
+        Returns the parsed ``ForwardMsgData`` dict or ``None``.
+        """
+        for elem in msg_body or []:
+            if not isinstance(elem, dict) or elem.get("msg_type") != "TIMCustomElem":
+                continue
+            content = elem.get("msg_content", {}) or {}
+            if not isinstance(content, dict):
+                continue
+            data_str = content.get("data", "")
+            if not data_str:
+                continue
+            try:
+                custom = json.loads(data_str)
+            except (json.JSONDecodeError, TypeError):
+                continue
+            if not (isinstance(custom, dict) and custom.get("elem_type") == 1009):
+                continue
+
+            ext_map = content.get("ext_map") or {}
+            if not isinstance(ext_map, dict) or not ext_map:
+                return None
+
+            def _parse_value(value):
+                # ext_map values are base64-encoded ForwardMsgData protobuf.
+                if not isinstance(value, str) or not value:
+                    return None
+                try:
+                    pb = base64.b64decode(value)
+                except (binascii.Error, ValueError):
+                    return None
+                data = decode_forward_msg_data(pb)
+                if isinstance(data, dict) and data.get("sub_type") == 1:
+                    return data
+                return None
+
+            # Take the first valid wexin_forward_msg_ entry.
+            for key, value in ext_map.items():
+                if not key.startswith("wexin_forward_msg_"):
+                    continue
+                parsed = _parse_value(value)
+                if parsed is not None:
+                    return parsed
+
+        return None
+
     async def handle(self, ctx: InboundContext, next_fn) -> None:
         ctx.raw_text = self._rewrite_slash_command(self._extract_text(ctx.msg_body))
         ctx.media_refs = self._extract_inbound_media_refs(ctx.msg_body)
         ctx.link_urls = self._extract_link_urls(ctx.msg_body)
+        ctx.forwarded_records = self._extract_forwarded_records(ctx.msg_body, ctx.from_account)
         await next_fn()
 
 class PlaceholderFilterMiddleware(InboundMiddleware):
@@ -2065,10 +2157,14 @@ class GroupAtGuardMiddleware(InboundMiddleware):
             "and answer it directly."
         )
 
-    @staticmethod
+    @classmethod
     def _observe_group_message(
+        cls,
         adapter, source, sender_display: str, text: str,
-        *, msg_id: Optional[str] = None,
+        *,
+        ctx: InboundContext,
+        msg_id: Optional[str] = None,
+        forwarded_records: Optional[dict] = None,
     ) -> None:
         """Write a group message into the session transcript without triggering the agent.
 
@@ -2083,7 +2179,14 @@ class GroupAtGuardMiddleware(InboundMiddleware):
         try:
             session_entry = store.get_or_create_session(source)
             user_id = source.user_id or "unknown"
-            attributed = f"[{sender_display}|{user_id}]\n{text}"
+            body_text = text
+            if forwarded_records:
+                summary = ForwardedRecordsParseMiddleware.build_forward_text(
+                    forwarded_records, ctx=ctx, is_dispatch=False,
+                )
+                if summary:
+                    body_text = f"{text}\n{summary}" if text else summary
+            attributed = f"[{sender_display}|{user_id}]\n{body_text}"
             entry: dict = {
                 "role": "user",
                 "content": attributed,
@@ -2105,6 +2208,8 @@ class GroupAtGuardMiddleware(InboundMiddleware):
             self._observe_group_message(
                 adapter, ctx.source, ctx.sender_nickname or ctx.from_account, ctx.raw_text,
                 msg_id=ctx.msg_id or None,
+                forwarded_records=ctx.forwarded_records,
+                ctx=ctx,
             )
             logger.info(
                 "[%s] Group message observed (no @bot): chat=%s from=%s",
@@ -2145,14 +2250,26 @@ class GroupAttributionMiddleware(InboundMiddleware):
         await next_fn()
 
 
+class YuanbaoMessageType(Enum):
+    """Yuanbao-local message subtypes; coerced back to :class:`MessageType`
+    before leaving the adapter (see :class:`DispatchMiddleware`)."""
+
+    # WeChat forwarded chat records (TIMCustomElem, elem_type 1009).
+    CHAT_RECORD = "chat_record"
+
+
 class ClassifyMessageTypeMiddleware(InboundMiddleware):
     """Determine MessageType from text content and msg_body elements."""
 
     name = "classify-msg-type"
 
     @staticmethod
-    def _classify(text: str, msg_body: list) -> MessageType:
-        """Classify message type based on text and msg_body."""
+    def _classify(text: str, msg_body: list):
+        """Classify message type based on text and msg_body.
+
+        Returns a base :class:`MessageType`, or a yuanbao-local
+        :class:`YuanbaoMessageType` for platform-specific subtypes.
+        """
         if text.startswith("/"):
             return MessageType.COMMAND
         for elem in msg_body:
@@ -2165,6 +2282,14 @@ class ClassifyMessageTypeMiddleware(InboundMiddleware):
                 return MessageType.VIDEO
             if etype == "TIMFileElem":
                 return MessageType.DOCUMENT
+            if etype == "TIMCustomElem":
+                data_str = (elem.get("msg_content") or {}).get("data", "")
+                try:
+                    custom = json.loads(data_str)
+                except (json.JSONDecodeError, TypeError):
+                    custom = None
+                if isinstance(custom, dict) and custom.get("elem_type") == 1009:
+                    return YuanbaoMessageType.CHAT_RECORD
         return MessageType.TEXT
 
     async def handle(self, ctx: InboundContext, next_fn) -> None:
@@ -2177,53 +2302,248 @@ class QuoteContextMiddleware(InboundMiddleware):
 
     name = "quote-context"
 
-    @staticmethod
-    def _extract_quote_context(cloud_custom_data: str) -> Tuple[Optional[str], Optional[str], list]:
-        """Extract quote context, mapping to MessageEvent.reply_to_*.
-
-        Returns:
-          (reply_to_message_id, reply_to_text, quote_media_refs)
-          where quote_media_refs is a list of (rid, kind, filename) tuples
+    def _extract_quote_context(self, cloud_custom_data: str) -> Tuple[Optional[str], Optional[str]]:
+        """Extract quote text context, mapping to MessageEvent.reply_to_*.
         """
         if not cloud_custom_data:
-            return None, None, []
+            return None, None
         try:
             parsed = json.loads(cloud_custom_data)
         except (json.JSONDecodeError, TypeError):
-            return None, None, []
+            return None, None
 
         quote = parsed.get("quote") if isinstance(parsed, dict) else None
         if not isinstance(quote, dict):
-            return None, None, []
-
-        # type=2 corresponds to image reference; desc may be empty, provide a placeholder.
-        quote_type = int(quote.get("type") or 0)
-        desc = str(quote.get("desc") or "").strip()
-        if quote_type == 2 and not desc:
-            desc = "[image]"
-        if not desc:
-            return None, None, []
+            return None, None
 
         quote_id = str(quote.get("id") or "").strip() or None
+        desc = str(quote.get("desc") or "").strip()
         sender = str(quote.get("sender_nickname") or quote.get("sender_id") or "").strip()
-        quote_text = f"{sender}: {desc}" if sender else desc
+        quote_text = (f"{sender}: {desc}" if sender else desc) if desc else None
 
-        # Extract media references from desc using _YB_RES_REF_RE regex
-        media_refs: list = []
-        for m in _YB_RES_REF_RE.finditer(desc):
-            head = m.group(1)  # "image" | "file:<name>" | "voice" | "video"
-            rid = m.group(2)
-            kind, _, filename = head.partition(":")
-            kind = kind.strip()
-            media_refs.append((rid, kind, filename.strip()))
+        return quote_id, quote_text
+
+    async def _extract_media_refs_from_transcript(
+        self, ctx: InboundContext
+    ) -> List[Tuple[str, str, str]]:
+        """Look up the quoted message in the transcript history and return any
+        ``[kind|ybres:RID]`` anchors found in its content as
+        ``(rid, kind, filename)`` tuples.
+
+        Returns ``[]`` when ``ctx.reply_to_message_id`` is unset, when the
+        transcript store / source is unavailable, or when the quoted message
+        carries no resolvable media anchors.
+        """
+        if ctx.reply_to_message_id is None:
+            return []
+        adapter = ctx.adapter
+        media_refs: List[Tuple[str, str, str]] = []
+        try:
+            store = getattr(adapter, "_session_store", None)
+            if not store or ctx.source is None:
+                return []
+            session_entry = store.get_or_create_session(ctx.source)
+            history = store.load_transcript(session_entry.session_id)
+            for msg in reversed(history or []):
+                mid = msg.get("message_id", "")
+                if not mid or mid != ctx.reply_to_message_id:
+                    continue
+                _content = msg.get("content", "")
+                if isinstance(_content, str) and "|ybres:" in _content:
+                    for m in _YB_RES_REF_RE.finditer(_content):
+                        head = m.group(1)
+                        rid = m.group(2)
+                        kind, _, filename = head.partition(":")
+                        kind = kind.strip()
+                        if kind in _RESOLVABLE_MEDIA_KINDS:
+                            media_refs.append((rid, kind, filename.strip()))
+                break
+        except Exception as exc:
+            logger.warning(
+                "[%s] quote transcript lookup failed: %s",
+                getattr(adapter, "name", "yuanbao"), exc,
+            )
+        return media_refs
+
+    async def handle(self, ctx: InboundContext, next_fn) -> None:
+        ctx.reply_to_message_id, ctx.reply_to_text = self._extract_quote_context(ctx.cloud_custom_data)
+        ctx.quote_media_refs = await self._extract_media_refs_from_transcript(ctx)
+        await next_fn()
+
+
+class ForwardedRecordsParseMiddleware(InboundMiddleware):
+    """Deep-parse WeChat forwarded chat records (elem_type 1009) for dispatch.
+
+    Activates when a full ``ForwardMsgData`` dict is available on the current
+    turn, carried by the current message (``ctx.forwarded_records``).
+    Resolves media to ``[kind|ybres:RID]``
+    placeholders, appends downloadable refs to ``ctx.media_refs`` (for
+    :class:`MediaResolveMiddleware`), and rewrites ``ctx.raw_text``.
+
+    Group @bot turns *without* a forward on the current message rely on the
+    eagerly-rendered summaries that :class:`GroupAtGuardMiddleware` writes to
+    the transcript at observe time — there is no run-time summary fallback
+    here.
+
+    On any failure the middleware leaves ``ctx.raw_text`` untouched
+    (graceful degradation, design §2.8).
+    """
 
-        return quote_id, quote_text, media_refs
+    name = "forwarded-records-parse"
 
     async def handle(self, ctx: InboundContext, next_fn) -> None:
-        ctx.reply_to_message_id, ctx.reply_to_text, ctx.quote_media_refs = self._extract_quote_context(ctx.cloud_custom_data)
+        try:
+            if ctx.forwarded_records:
+                self._send_loading_heartbeat(ctx)
+                ctx.raw_text = self.build_forward_text(ctx.forwarded_records, ctx=ctx, is_dispatch=True)
+        except Exception as exc:
+            # Degrade gracefully: leave ctx.raw_text as-is.
+            logger.warning(
+                "[%s] forwarded-records deep parse failed: %s",
+                getattr(ctx.adapter, "name", "yuanbao"), exc,
+            )
 
         await next_fn()
 
+    # -- Heartbeat ---------------------------------------------------------
+
+    @staticmethod
+    async def _send_loading_heartbeat(ctx: InboundContext) -> None:
+        """Best-effort RUNNING heartbeat so the user sees a loading bubble."""
+        try:
+            await ctx.adapter._outbound.heartbeat.send_heartbeat_once(
+                ctx.chat_id, WS_HEARTBEAT_RUNNING,
+            )
+        except Exception:
+            pass
+
+    # -- Record rendering helpers -----------------------------------------
+
+    @classmethod
+    def _media_marker(
+        cls, media: dict, plain_text: str = "",
+    ) -> Tuple[str, Optional[Dict[str, str]]]:
+        """Render one ``msgContent.multimedia`` entry as a textual marker.
+
+        Returns ``(marker, ref)``. Downloadable media emits a
+        ``[kind|ybres:RID]`` marker and a ``ctx.media_refs`` ref dict when a
+        usable RID/URL is present; otherwise a plain ``[kind] name`` marker
+        and ``ref=None``.
+        """
+        media_type = (media.get("type", "") or media.get("doc_type", "")).strip().lower()
+        url = str(media.get("url") or "").strip()
+        media_id = str(media.get("media_id") or "").strip()
+        file_name = str(media.get("file_name") or "").strip()
+        # media_id is directly usable as a ybres RID (design §2.10.9);
+        # fall back to parsing the resourceId out of the URL.
+        rid = media_id or ExtractContentMiddleware._parse_resource_id(url)
+
+        if media_type == "image":
+            if url and rid:
+                return f"[image|ybres:{rid}] {file_name}".rstrip(), {"kind": "image", "url": url}
+            return f"[image] {file_name or plain_text}".rstrip(), None
+
+        if media_type in ("file", "document", "code"):
+            if url and rid:
+                ref: Dict[str, str] = {"kind": "file", "url": url}
+                if file_name:
+                    ref["name"] = file_name
+                return f"[file|ybres:{rid}] {file_name}".rstrip(), ref
+            return f"[file] {file_name}".rstrip(), None
+
+        if media_type == "url":
+            # Link share (e.g. WeChat article) — keep URL for the agent.
+            link_title = file_name or str(media.get("title") or "")
+            return f"[link] {link_title} {url}".rstrip(), None
+
+        if media_type == "video":
+            if url and rid:
+                return f"[video|ybres:{rid}] {file_name}".rstrip(), {"kind": "video", "url": url}
+            return f"[video] {file_name or url}".rstrip(), None
+
+        return f"[{media_type or 'media'}] {url or file_name}".rstrip(), None
+
+    # Per-record combined-text cap; record count is NOT capped (design §2.10.3).
+    FORWARD_MSG_TEXT_MAX_CHARS = 1000
+
+    @classmethod
+    def _walk_forward_msgs(
+        cls,
+        forward_data: dict,
+    ) -> Iterator[Tuple[str, str, List[Dict[str, str]]]]:
+        """Walk ``ForwardMsgData['msg']`` and yield ``(sender, body, refs)``.
+
+        Per-record dispatch over ``msgContent`` (text / multimedia / nested
+        forward / fallback); ``body`` is capped at
+        :attr:`FORWARD_MSG_TEXT_MAX_CHARS`. Media goes through
+        :meth:`_media_marker`, always building full ``[kind|ybres:RID]``
+        markers; ``refs`` holds that record's downloadable ``ctx.media_refs``
+        entries in textual order — the order PatchAnchorsMiddleware relies on
+        (design §2.10.6). Headers / footers are the caller's job.
+        """
+        for msg in (forward_data.get("msg") if isinstance(forward_data, dict) else None) or []:
+            if not isinstance(msg, dict):
+                continue
+            sender = msg.get("sender", "")
+            plain_text = msg.get("plainText", "")
+            msg_contents = msg.get("msgContent", []) or []
+
+            refs: List[Dict[str, str]] = []
+            if not msg_contents:
+                rendered = plain_text
+            else:
+                parts: List[str] = []
+                for mc in msg_contents:
+                    if not isinstance(mc, dict):
+                        continue
+                    mc_type = mc.get("type", 0)  # EnumMsgContentType
+                    if mc_type == 1:  # TEXT
+                        parts.append(mc.get("text", ""))
+                    elif mc_type == 2:  # MULTIMEDIA
+                        for media in mc.get("multimedia", []) or []:
+                            if isinstance(media, dict):
+                                marker, ref = cls._media_marker(
+                                    media, plain_text,
+                                )
+                                parts.append(marker)
+                                if ref is not None:
+                                    refs.append(ref)
+                    elif mc_type == 3:  # nested FORWARD_MSG (design §2.10.10)
+                        parts.append("[嵌套聊天记录]")
+                    else:
+                        if plain_text:
+                            parts.append(plain_text)
+                rendered = "  ".join(p for p in parts if p) or plain_text
+
+            if len(rendered) > cls.FORWARD_MSG_TEXT_MAX_CHARS:
+                rendered = rendered[: cls.FORWARD_MSG_TEXT_MAX_CHARS] + "…(已截断)"
+            yield sender, rendered, refs
+
+    # -- Prompt builders ---------------------------------------------------
+
+    @classmethod
+    def build_forward_text(
+        cls, forward_data: dict, *, ctx: InboundContext, is_dispatch: bool,
+    ) -> str:
+        """Render ``ForwardMsgData`` into forward text.
+
+        Body lines are ``发送人：正文`` with full ``[kind|ybres:RID]`` media
+        markers preserved. When ``is_dispatch`` is true, refs are appended to
+        ``ctx.media_refs`` for downstream resolution and a ``用户附言：
+        {ctx.raw_text}`` footer is added; observed callers skip both since
+        no later middleware runs.
+        """
+        nickname = ctx.sender_nickname or "用户"
+        lines = [f"当前用户的昵称为{nickname}", "以下为用户的聊天记录"]
+        for sender, body, refs in cls._walk_forward_msgs(forward_data):
+            lines.append(f"{sender}：{body}")
+            if is_dispatch:
+                ctx.media_refs.extend(refs)
+        text = "\n".join(lines)
+        if is_dispatch and ctx.raw_text.strip():
+            text += f"\n\n用户附言：{ctx.raw_text.strip()}"
+        return text
+
 
 class MediaResolveMiddleware(InboundMiddleware):
     """Resolve inbound media references to downloadable URLs."""
@@ -2232,9 +2552,6 @@ class MediaResolveMiddleware(InboundMiddleware):
 
     # --- Resource download cache (keyed by resourceId) ---
     # Avoids redundant downloads of the same resource within the TTL window.
-    # The same resourceId can be referenced multiple times in a session (own
-    # attachment, then quoted again, then observed in a group backfill); each
-    # reference otherwise triggers a fresh token exchange + download.
     _resource_cache: ClassVar[Dict[str, Tuple[str, str, float]]] = {}  # rid -> (local_path, mime, ts)
     _RESOURCE_CACHE_TTL_S: ClassVar[int] = 24 * 60 * 60  # 24 hours
     _RESOURCE_CACHE_MAX_SIZE: ClassVar[int] = 256
@@ -2410,6 +2727,15 @@ class MediaResolveMiddleware(InboundMiddleware):
             cls._put_cached_resource(resource_id, local_path, mime)
             return local_path, mime
 
+        if kind == "video":
+            # Yuanbao video resources carry no reliable extension; default to mp4.
+            local_path = cache_video_from_bytes(file_bytes)
+            mime = guess_mime_type(local_path) or (
+                content_type if content_type.startswith("video/") else "video/mp4"
+            )
+            cls._put_cached_resource(resource_id, local_path, mime)
+            return local_path, mime
+
         # kind == "file"
         if not file_name:
             parsed = urllib.parse.urlparse(fetch_url)
@@ -2426,11 +2752,6 @@ class MediaResolveMiddleware(InboundMiddleware):
         cls._put_cached_resource(resource_id, local_path, mime)
         return local_path, mime
 
-    @classmethod
-    async def _resolve_by_resource_id(cls, adapter, resource_id: str) -> str:
-        """Exchange a Yuanbao ``resourceId`` for a short-lived direct download URL. Raises on failure."""
-        return await cls._fetch_resource_url(adapter, resource_id)
-
     @classmethod
     async def _resolve_media_urls(
         cls, adapter, media_refs: List[Dict[str, str]]
@@ -2446,6 +2767,7 @@ class MediaResolveMiddleware(InboundMiddleware):
         for ref in media_refs:
             kind = str(ref.get("kind") or "").strip().lower()
             url = str(ref.get("url") or "").strip()
+            filename = str(ref.get("name") or "").strip()
             if kind not in _RESOLVABLE_MEDIA_KINDS or not url:
                 continue
 
@@ -2465,7 +2787,7 @@ class MediaResolveMiddleware(InboundMiddleware):
                 adapter,
                 fetch_url=fetch_url,
                 kind=kind,
-                file_name=str(ref.get("name") or "").strip() or None,
+                file_name=filename or None,
                 log_tag=f"placeholder_url={url[:80]}",
                 resource_id=rid,
             )
@@ -2477,6 +2799,44 @@ class MediaResolveMiddleware(InboundMiddleware):
 
         return media_urls, media_types
 
+    @classmethod
+    async def _resolve_ybres_refs(
+        cls,
+        adapter,
+        refs: List[Tuple[str, str, str]],
+        *,
+        log_prefix: str,
+    ) -> Tuple[List[str], List[str]]:
+        """Resolve a list of ``(rid, kind, filename)`` ybres tuples to local paths.
+        """
+        media_paths: List[str] = []
+        mimes: List[str] = []
+        for rid, kind, filename in refs:
+            if kind not in _RESOLVABLE_MEDIA_KINDS:
+                continue
+            try:
+                fresh_url = await cls._fetch_resource_url(adapter, rid)
+            except Exception as exc:
+                logger.warning(
+                    "[%s] %s resolve failed: rid=%s kind=%s err=%s",
+                    adapter.name, log_prefix, rid, kind, exc,
+                )
+                continue
+            cached = await cls._download_and_cache(
+                adapter,
+                fetch_url=fresh_url,
+                kind=kind,
+                file_name=filename or None,
+                log_tag=f"{log_prefix} rid={rid}",
+                resource_id=rid,
+            )
+            if cached is None:
+                continue
+            path, mime = cached
+            media_paths.append(path)
+            mimes.append(mime)
+        return media_paths, mimes
+
     @classmethod
     async def _collect_observed_media(
         cls, adapter, source,
@@ -2497,14 +2857,22 @@ class MediaResolveMiddleware(InboundMiddleware):
         if not history:
             return [], []
 
-        start = max(0, len(history) - OBSERVED_MEDIA_BACKFILL_LOOKBACK)
+        # Walk the most recent LOOKBACK messages newest→oldest so that when we
+        # hit the per-turn resolve cap we keep the *latest* media references,
+        # not the oldest ones in the window. Within a single message, also
+        # iterate matches in reverse so the last-added image wins on ties.
+        # Final ``order`` is reversed back to chronological (old→new) before
+        # handing off to ``_resolve_ybres_refs`` so downstream prompt insertion
+        # preserves natural reading order.
+        window = history[-OBSERVED_MEDIA_BACKFILL_LOOKBACK:]
         order: List[Tuple[str, str, str]] = []  # (rid, kind, filename)
         seen: set = set()
-        for msg in history[start:]:
+        for msg in reversed(window):
             content = msg.get("content")
             if not isinstance(content, str) or "|ybres:" not in content:
                 continue
-            for m in _YB_RES_REF_RE.finditer(content):
+            matches = list(_YB_RES_REF_RE.finditer(content))
+            for m in reversed(matches):
                 head = m.group(1)  # "image" | "file:<name>" | "voice" | "video"
                 rid = m.group(2)
                 kind, _, filename = head.partition(":")
@@ -2520,45 +2888,184 @@ class MediaResolveMiddleware(InboundMiddleware):
             if len(order) >= OBSERVED_MEDIA_BACKFILL_MAX_RESOLVE_PER_TURN:
                 break
 
+        # Restore chronological order (oldest→newest) for downstream resolution.
+        order.reverse()
+
         if not order:
             return [], []
 
-        media_paths: List[str] = []
+        return await cls._resolve_ybres_refs(
+            adapter, order, log_prefix="observed-media",
+        )
+
+    @classmethod
+    async def _resolve_quote_media(
+        cls, adapter, quote_media_refs: List[Tuple[str, str, str]],
+    ) -> Tuple[List[str], List[str]]:
+        """Resolve media anchors carried by the quoted message.
+
+        ``quote_media_refs`` is a list of ``(rid, kind, filename)`` tuples
+        produced by :class:`QuoteContextMiddleware` from the transcript.
+        """
+        return await cls._resolve_ybres_refs(
+            adapter, quote_media_refs, log_prefix="quote",
+        )
+
+    @staticmethod
+    def _collect_quote_local_media(ctx: InboundContext) -> Tuple[List[str], List[str]]:
+        """Private-chat fallback for recovering already-local quoted media.
+
+        Only already-local media is handled here: by the time a turn is cached,
+        ``PatchAnchorsMiddleware`` has rewritten resolved ``|ybres:`` anchors to
+        ``[image: /path]`` / ``[file: name → /path]``. Unresolved anchors are an
+        original-turn resolution failure and belong to that turn's handling, not
+        this quote fallback — so no re-download happens here.
+
+        Returns ``(local_paths, mimes)`` for media already downloaded to the
+        local cache on its original turn, ready to inject as-is.
+        """
+        paths: List[str] = []
         mimes: List[str] = []
-        for rid, kind, filename in order:
-            try:
-                fresh_url = await cls._resolve_by_resource_id(adapter, rid)
-            except Exception as exc:
-                logger.warning(
-                    "[%s] observed-media resolve failed: rid=%s kind=%s err=%s",
-                    adapter.name, rid, kind, exc,
-                )
+        rid_key = ctx.reply_to_message_id
+        if not rid_key:
+            return paths, mimes
+        cache = getattr(ctx.adapter, "_msg_content_cache", None)
+        if not cache:
+            return paths, mimes
+        text = cache.get(rid_key)
+        if not isinstance(text, str) or not text:
+            return paths, mimes
+
+        # Already-local media paths written by PatchAnchorsMiddleware.
+        seen: set = set()
+        for m in _YB_LOCAL_MEDIA_RE.finditer(text):
+            kind = (m.group(1) or "").strip().lower()
+            path = (m.group(2) or "").strip()
+            if not path or path in seen:
                 continue
-            cached = await cls._download_and_cache(
-                adapter,
-                fetch_url=fresh_url,
-                kind=kind,
-                file_name=filename or None,
-                log_tag=f"rid={rid}",
-                resource_id=rid,
-            )
-            if cached is None:
+            if not os.path.exists(path):
                 continue
-            path, mime = cached
-            media_paths.append(path)
+            seen.add(path)
+            mime = guess_mime_type(os.path.basename(path)) or (
+                "image/jpeg" if kind == "image" else "application/octet-stream"
+            )
+            paths.append(path)
             mimes.append(mime)
-        return media_paths, mimes
+
+        return paths, mimes
 
     async def handle(self, ctx: InboundContext, next_fn) -> None:
+        # NOTE: Reaching this middleware in a group chat implies the message has
+        # @-mentioned the bot (or is an owner command). GroupAtGuardMiddleware
+        # short-circuits non-@bot group messages earlier in the pipeline, so we
+        # don't need to re-check @bot status here before downloading media.
         adapter = ctx.adapter
-        ctx.media_urls, ctx.media_types = await self._resolve_media_urls(adapter, ctx.media_refs)
-        # Re-check placeholder after media resolution
-        if PlaceholderFilterMiddleware.is_skippable_placeholder(ctx.raw_text, len(ctx.media_urls)):
+
+        urls: List[str] = []
+        types: List[str] = []
+        seen: set = set()
+
+        def _add_unique_pairs(pair_lists: Tuple[List[str], List[str]]) -> None:
+            u_list, m_list = pair_lists
+            for u, m in zip(u_list, m_list):
+                if not u or u in seen:
+                    continue
+                seen.add(u)
+                urls.append(u)
+                types.append(m)
+
+        # 1) Media carried by the current message itself.
+        own_pairs = await self._resolve_media_urls(adapter, ctx.media_refs)
+        own_count = sum(1 for u in own_pairs[0] if u)
+        _add_unique_pairs(own_pairs)
+
+        # 2) Second source — quoted media takes priority; otherwise fall back
+        #    to observed-media backfill in groups only (DMs already had their
+        #    media resolved on the turn it was sent).
+        if ctx.reply_to_message_id is not None:
+            if ctx.quote_media_refs:
+                _add_unique_pairs(await self._resolve_quote_media(adapter, ctx.quote_media_refs))
+            else:
+                # DM quote fallback: no transcript message_id match (DM user rows
+                # carry no platform message_id), so recover already-local media
+                # from the adapter msg cache. Patched on its original turn — no
+                # re-download needed, inject as-is.
+                _add_unique_pairs(self._collect_quote_local_media(ctx))
+        elif ctx.chat_type == "group":
+            # Group chats: only @-bot turns reach this middleware
+            # (see GroupAtGuardMiddleware note at top of handle()),
+            # so unconditional observed-media hydration is safe here.
+            try:
+                _add_unique_pairs(await self._collect_observed_media(adapter, ctx.source))
+            except Exception as exc:
+                logger.warning(
+                    "[%s] observed-image hydration raised, continuing anyway: %s",
+                    adapter.name, exc,
+                )
+
+        ctx.media_urls = urls
+        ctx.media_types = types
+
+        # Re-check placeholder after media resolution.
+        # Use ``own_count`` (not ``len(urls)``) to preserve the original
+        # semantics: a placeholder text accompanied only by quote/observed
+        # media (i.e. no fresh attachment of its own) is still skippable.
+        if PlaceholderFilterMiddleware.is_skippable_placeholder(ctx.raw_text, own_count):
             logger.debug("[%s] Skip placeholder after media download: %r", adapter.name, ctx.raw_text)
             return  # Stop pipeline
         await next_fn()
 
 
+class PatchAnchorsMiddleware(InboundMiddleware):
+    """Replace ``[kind|ybres:RID]`` anchors in ``ctx.raw_text`` with local paths.
+
+    Runs after :class:`MediaResolveMiddleware` so that ``ctx.media_urls`` /
+    ``ctx.media_types`` are already populated with downloaded resources
+    (own media + quote media or group-observed media).  The transcript
+    written downstream then records usable local paths for the model
+    instead of opaque ``ybres:`` references.
+
+    Only resolved media (paths starting with ``/``) are substituted; any
+    anchor without a corresponding local resource is left untouched.
+    """
+
+    name = "patch-anchors"
+
+    @staticmethod
+    def _patch(text: str, urls: List[str], types: List[str]) -> str:
+        if not text or not urls:
+            return text
+        patched = text
+        for u, m in zip(urls, types):
+            if not u.startswith("/"):
+                continue
+            anchor_match = _YB_RES_REF_RE.search(patched)
+            if not anchor_match:
+                break
+            head = anchor_match.group(1)
+            kind, _, filename = head.partition(":")
+            kind = kind.strip()
+            if kind == "image" and m.startswith("image/"):
+                replacement = f"[image: {u}]"
+            elif kind == "file":
+                label = filename.strip() or os.path.basename(u)
+                replacement = f"[file: {label} → {u}]"
+            elif kind == "video":
+                replacement = f"[video: {u}]"
+            else:
+                continue
+            patched = (
+                patched[: anchor_match.start()]
+                + replacement
+                + patched[anchor_match.end():]
+            )
+        return patched
+
+    async def handle(self, ctx: InboundContext, next_fn) -> None:
+        ctx.raw_text = self._patch(ctx.raw_text, ctx.media_urls, ctx.media_types)
+        await next_fn()
+
+
 class DispatchMiddleware(InboundMiddleware):
     """Build MessageEvent and dispatch to AI handler."""
 
@@ -2574,124 +3081,22 @@ class DispatchMiddleware(InboundMiddleware):
         )
 
         async def _dispatch_inbound_event() -> None:
-            media_urls = list(ctx.media_urls)
-            media_types = list(ctx.media_types)
-
-            # If user quoted a message (reply_to_message_id is set), resolve only
-            # quote_media_refs to avoid injecting unrelated history media.
-            # Otherwise, backfill observed media from recent transcript history.
-            if ctx.reply_to_message_id is not None:
-                # Fallback: if desc didn't contain ybres refs, look up transcript
-                if not ctx.quote_media_refs:
-                    try:
-                        store = getattr(adapter, "_session_store", None)
-                        if store:
-                            session_entry = store.get_or_create_session(ctx.source)
-                            history = store.load_transcript(session_entry.session_id)
-                            for msg in reversed(history or []):
-                                mid = msg.get("message_id", "")
-                                if mid and mid == ctx.reply_to_message_id:
-                                    _content = msg.get("content", "")
-                                    if isinstance(_content, str) and "|ybres:" in _content:
-                                        for m in _YB_RES_REF_RE.finditer(_content):
-                                            head = m.group(1)
-                                            rid = m.group(2)
-                                            kind, _, filename = head.partition(":")
-                                            kind = kind.strip()
-                                            if kind in _RESOLVABLE_MEDIA_KINDS:
-                                                ctx.quote_media_refs.append((rid, kind, filename.strip()))
-                                    break
-                    except Exception as exc:
-                        logger.warning(
-                            "[%s] quote transcript lookup failed: %s",
-                            adapter.name, exc,
-                        )
-                # User quoted a message — resolve only media from the quote
-                for rid, kind, filename in ctx.quote_media_refs:
-                    if kind not in _RESOLVABLE_MEDIA_KINDS:
-                        continue
-                    try:
-                        fresh_url = await MediaResolveMiddleware._resolve_by_resource_id(adapter, rid)
-                    except Exception as exc:
-                        logger.warning(
-                            "[%s] quote media resolve failed: rid=%s kind=%s err=%s",
-                            adapter.name, rid, kind, exc,
-                        )
-                        continue
-                    cached = await MediaResolveMiddleware._download_and_cache(
-                        adapter,
-                        fetch_url=fresh_url,
-                        kind=kind,
-                        file_name=filename or None,
-                        log_tag=f"quote rid={rid}",
-                        resource_id=rid,
-                    )
-                    if cached is None:
-                        continue
-                    path, mime = cached
-                    # Avoid duplicates
-                    if path not in media_urls:
-                        media_urls.append(path)
-                        media_types.append(mime)
-            else:
-                # No quote — backfill observed media from recent transcript history
-                extra_img_urls: List[str] = []
-                extra_img_mimes: List[str] = []
-                try:
-                    extra_img_urls, extra_img_mimes = await MediaResolveMiddleware._collect_observed_media(
-                        adapter, ctx.source,
-                    )
-                except Exception as exc:
-                    logger.warning(
-                        "[%s] observed-image hydration raised, continuing anyway: %s",
-                        adapter.name, exc,
-                    )
-                if extra_img_urls:
-                    current = set(media_urls)
-                    for u, m in zip(extra_img_urls, extra_img_mimes):
-                        if u in current:
-                            continue
-                        media_urls.append(u)
-                        media_types.append(m)
-                        current.add(u)
-
-            # Replace [kind|ybres:xxx] anchors with local cache paths so
-            # the transcript records usable paths for the model.
-            _patched_event_text = ctx.raw_text
-            for u, m in zip(media_urls, media_types):
-                if not u.startswith("/"):
-                    continue
-                anchor_match = _YB_RES_REF_RE.search(_patched_event_text)
-                if not anchor_match:
-                    continue
-                head = anchor_match.group(1)
-                kind, _, filename = head.partition(":")
-                kind = kind.strip()
-                if kind == "image" and m.startswith("image/"):
-                    replacement = f"[image: {u}]"
-                elif kind == "file":
-                    label = filename.strip() or os.path.basename(u)
-                    replacement = f"[file: {label} → {u}]"
-                else:
-                    continue
-                _patched_event_text = (
-                    _patched_event_text[:anchor_match.start()]
-                    + replacement
-                    + _patched_event_text[anchor_match.end():]
-                )
-
             event = MessageEvent(
-                text=_patched_event_text,
+                text=ctx.raw_text,
                 message_type=(
                     MessageType.DOCUMENT
-                    if any(mt.startswith(("application/", "text/")) for mt in media_types)
-                    else ctx.msg_type
+                    if any(mt.startswith(("application/", "text/")) for mt in ctx.media_types)
+                    # Coerce yuanbao-local subtypes (e.g. CHAT_RECORD) back to a
+                    # base MessageType: chat records are deep-parsed into a text
+                    # prompt, so TEXT is the right kind for downstream routing.
+                    else ctx.msg_type if isinstance(ctx.msg_type, MessageType)
+                    else MessageType.TEXT
                 ),
                 source=ctx.source,
                 message_id=ctx.msg_id or None,
                 raw_message=ctx.push,
-                media_urls=media_urls,
-                media_types=media_types,
+                media_urls=list(ctx.media_urls),
+                media_types=list(ctx.media_types),
                 reply_to_message_id=ctx.reply_to_message_id,
                 reply_to_text=ctx.reply_to_text,
                 channel_prompt=ctx.channel_prompt,
@@ -2784,7 +3189,9 @@ class InboundPipelineBuilder:
         GroupAttributionMiddleware,
         ClassifyMessageTypeMiddleware,
         QuoteContextMiddleware,
+        ForwardedRecordsParseMiddleware,
         MediaResolveMiddleware,
+        PatchAnchorsMiddleware,
         DispatchMiddleware,
     ]
 
@@ -3445,12 +3852,22 @@ class ConnectionManager:
         return False
 
     async def _cleanup_ws(self) -> None:
-        """Close and clear the WebSocket connection."""
+        """Close and clear the WebSocket connection, bounded by
+        ``WS_CLOSE_TIMEOUT_S`` so an unresponsive server can't stall teardown
+        (see the constant's definition for the full rationale)."""
         ws = self._ws
         self._ws = None
         if ws is not None:
             try:
-                await ws.close()
+                await asyncio.wait_for(ws.close(), timeout=WS_CLOSE_TIMEOUT_S)
+            except asyncio.TimeoutError:
+                # Server never echoed the close frame within the bound; drop the
+                # connection. websockets force-closes the transport on cancel,
+                # and at shutdown the loop is tearing down anyway.
+                logger.debug(
+                    "[%s] WS close handshake exceeded %.1fs — dropping connection",
+                    self._adapter.name, WS_CLOSE_TIMEOUT_S,
+                )
             except Exception:
                 pass