fix: 补全 vendor 快照（model_tools/utils/toolsets/gateway/cron/hermes_time）+ python-dotenv 依赖

- vendor_hermes.sh: 补全遗漏的单文件模块和目录
- pyproject.toml: 添加 python-dotenv 隐性依赖
- 全量 import 测试通过（216 .py, 180K 行）
- firecrawl/fal_client 为可选工具，缺失时优雅跳过

mindcli/_vendor/gateway/platforms/ADDING_A_PLATFORM.md

@@ -0,0 +1,313 @@
+# Adding a New Messaging Platform
+
+Checklist for integrating a new messaging platform into the Hermes gateway.
+Use this as a reference when building a new adapter — every item here is a
+real integration point that exists in the codebase. Missing any of them will
+cause broken functionality, missing features, or inconsistent behavior.
+
+---
+
+## 1. Core Adapter (`gateway/platforms/<platform>.py`)
+
+The adapter is a subclass of `BasePlatformAdapter` from `gateway/platforms/base.py`.
+
+### Required methods
+
+| Method | Purpose |
+|--------|---------|
+| `__init__(self, config)` | Parse config, init state. Call `super().__init__(config, Platform.YOUR_PLATFORM)` |
+| `connect() -> bool` | Connect to the platform, start listeners. Return True on success |
+| `disconnect()` | Stop listeners, close connections, cancel tasks |
+| `send(chat_id, text, ...) -> SendResult` | Send a text message |
+| `send_typing(chat_id)` | Send typing indicator |
+| `send_image(chat_id, image_url, caption) -> SendResult` | Send an image |
+| `get_chat_info(chat_id) -> dict` | Return `{name, type, chat_id}` for a chat |
+
+### Optional methods (have default stubs in base)
+
+| Method | Purpose |
+|--------|---------|
+| `send_document(chat_id, path, caption)` | Send a file attachment |
+| `send_voice(chat_id, path)` | Send a voice message |
+| `send_video(chat_id, path, caption)` | Send a video |
+| `send_animation(chat_id, path, caption)` | Send a GIF/animation |
+| `send_image_file(chat_id, path, caption)` | Send image from local file |
+
+### Required function
+
+```python
+def check_<platform>_requirements() -> bool:
+    """Check if this platform's dependencies are available."""
+```
+
+### Key patterns to follow
+
+- Use `self.build_source(...)` to construct `SessionSource` objects
+- Call `self.handle_message(event)` to dispatch inbound messages to the gateway
+- Use `MessageEvent`, `MessageType`, `SendResult` from base
+- Use `cache_image_from_bytes`, `cache_audio_from_bytes`, `cache_document_from_bytes` for attachments
+- Filter self-messages (prevent reply loops)
+- Filter sync/echo messages if the platform has them
+- Redact sensitive identifiers (phone numbers, tokens) in all log output
+- Implement reconnection with exponential backoff + jitter for streaming connections
+- Set `MAX_MESSAGE_LENGTH` if the platform has message size limits
+
+---
+
+## 2. Platform Enum (`gateway/config.py`)
+
+Add the platform to the `Platform` enum:
+
+```python
+class Platform(Enum):
+    ...
+    YOUR_PLATFORM = "your_platform"
+```
+
+Add env var loading in `_apply_env_overrides()`:
+
+```python
+# Your Platform
+your_token = os.getenv("YOUR_PLATFORM_TOKEN")
+if your_token:
+    if Platform.YOUR_PLATFORM not in config.platforms:
+        config.platforms[Platform.YOUR_PLATFORM] = PlatformConfig()
+    config.platforms[Platform.YOUR_PLATFORM].enabled = True
+    config.platforms[Platform.YOUR_PLATFORM].token = your_token
+```
+
+Update `get_connected_platforms()` if your platform doesn't use token/api_key
+(e.g., WhatsApp uses `enabled` flag, Signal uses `extra` dict).
+
+---
+
+## 3. Adapter Factory (`gateway/run.py`)
+
+Add to `_create_adapter()`:
+
+```python
+elif platform == Platform.YOUR_PLATFORM:
+    from gateway.platforms.your_platform import YourAdapter, check_your_requirements
+    if not check_your_requirements():
+        logger.warning("Your Platform: dependencies not met")
+        return None
+    return YourAdapter(config)
+```
+
+---
+
+## 4. Authorization Maps (`gateway/run.py`)
+
+Add to BOTH dicts in `_is_user_authorized()`:
+
+```python
+platform_env_map = {
+    ...
+    Platform.YOUR_PLATFORM: "YOUR_PLATFORM_ALLOWED_USERS",
+}
+platform_allow_all_map = {
+    ...
+    Platform.YOUR_PLATFORM: "YOUR_PLATFORM_ALLOW_ALL_USERS",
+}
+```
+
+---
+
+## 5. Session Source (`gateway/session.py`)
+
+If your platform needs extra identity fields (e.g., Signal's UUID alongside
+phone number), add them to the `SessionSource` dataclass with `Optional` defaults,
+and update `to_dict()`, `from_dict()`, and `build_source()` in base.py.
+
+---
+
+## 6. System Prompt Hints (`agent/prompt_builder.py`)
+
+Add a `PLATFORM_HINTS` entry so the agent knows what platform it's on:
+
+```python
+PLATFORM_HINTS = {
+    ...
+    "your_platform": (
+        "You are on Your Platform. "
+        "Describe formatting capabilities, media support, etc."
+    ),
+}
+```
+
+Without this, the agent won't know it's on your platform and may use
+inappropriate formatting (e.g., markdown on platforms that don't render it).
+
+---
+
+## 7. Toolset (`toolsets.py`)
+
+Add a named toolset for your platform:
+
+```python
+"hermes-your-platform": {
+    "description": "Your Platform bot toolset",
+    "tools": _HERMES_CORE_TOOLS,
+    "includes": []
+},
+```
+
+And add it to the `hermes-gateway` composite:
+
+```python
+"hermes-gateway": {
+    "includes": [..., "hermes-your-platform"]
+}
+```
+
+---
+
+## 8. Cron Delivery (`cron/scheduler.py`)
+
+Add to `platform_map` in `_deliver_result()`:
+
+```python
+platform_map = {
+    ...
+    "your_platform": Platform.YOUR_PLATFORM,
+}
+```
+
+Without this, `cronjob(action="create", deliver="your_platform", ...)` silently fails.
+
+---
+
+## 9. Send Message Tool (`tools/send_message_tool.py`)
+
+Add to `platform_map` in `send_message_tool()`:
+
+```python
+platform_map = {
+    ...
+    "your_platform": Platform.YOUR_PLATFORM,
+}
+```
+
+Add routing in `_send_to_platform()`:
+
+```python
+elif platform == Platform.YOUR_PLATFORM:
+    return await _send_your_platform(pconfig, chat_id, message)
+```
+
+Implement `_send_your_platform()` — a standalone async function that sends
+a single message without requiring the full adapter (for use by cron jobs
+and the send_message tool outside the gateway process).
+
+Update the tool schema `target` description to include your platform example.
+
+---
+
+## 10. Cronjob Tool Schema (`tools/cronjob_tools.py`)
+
+Update the `deliver` parameter description and docstring to mention your
+platform as a delivery option.
+
+---
+
+## 11. Channel Directory (`gateway/channel_directory.py`)
+
+If your platform can't enumerate chats (most can't), add it to the
+session-based discovery list:
+
+```python
+for plat_name in ("telegram", "whatsapp", "signal", "your_platform"):
+```
+
+---
+
+## 12. Status Display (`hermes_cli/status.py`)
+
+Add to the `platforms` dict in the Messaging Platforms section:
+
+```python
+platforms = {
+    ...
+    "Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
+}
+```
+
+---
+
+## 13. Gateway Setup Wizard (`hermes_cli/gateway.py`)
+
+Add to the `_PLATFORMS` list:
+
+```python
+{
+    "key": "your_platform",
+    "label": "Your Platform",
+    "emoji": "📱",
+    "token_var": "YOUR_PLATFORM_TOKEN",
+    "setup_instructions": [...],
+    "vars": [...],
+}
+```
+
+If your platform needs custom setup logic (connectivity testing, QR codes,
+policy choices), add a `_setup_your_platform()` function and route to it
+in the platform selection switch.
+
+Update `_platform_status()` if your platform's "configured" check differs
+from the standard `bool(get_env_value(token_var))`.
+
+---
+
+## 14. Phone/ID Redaction (`agent/redact.py`)
+
+If your platform uses sensitive identifiers (phone numbers, etc.), add a
+regex pattern and redaction function to `agent/redact.py`. This ensures
+identifiers are masked in ALL log output, not just your adapter's logs.
+
+---
+
+## 15. Documentation
+
+| File | What to update |
+|------|---------------|
+| `README.md` | Platform list in feature table + documentation table |
+| `AGENTS.md` | Gateway description + env var config section |
+| `website/docs/user-guide/messaging/<platform>.md` | **NEW** — Full setup guide (see existing platform docs for template) |
+| `website/docs/user-guide/messaging/index.md` | Architecture diagram, toolset table, security examples, Next Steps links |
+| `website/docs/reference/environment-variables.md` | All env vars for the platform |
+
+---
+
+## 16. Tests (`tests/gateway/test_<platform>.py`)
+
+Recommended test coverage:
+
+- Platform enum exists with correct value
+- Config loading from env vars via `_apply_env_overrides`
+- Adapter init (config parsing, allowlist handling, default values)
+- Helper functions (redaction, parsing, file type detection)
+- Session source round-trip (to_dict → from_dict)
+- Authorization integration (platform in allowlist maps)
+- Send message tool routing (platform in platform_map)
+
+Optional but valuable:
+- Async tests for message handling flow (mock the platform API)
+- SSE/WebSocket reconnection logic
+- Attachment processing
+- Group message filtering
+
+---
+
+## Quick Verification
+
+After implementing everything, verify with:
+
+```bash
+# All tests pass
+python -m pytest tests/ -q
+
+# Grep for your platform name to find any missed integration points
+grep -r "telegram\|discord\|whatsapp\|slack" gateway/ tools/ agent/ cron/ hermes_cli/ toolsets.py \
+  --include="*.py" -l | sort -u
+# Check each file in the output — if it mentions other platforms but not yours, you missed it
+```

mindcli/_vendor/gateway/platforms/__init__.py

@@ -0,0 +1,19 @@
+"""
+Platform adapters for messaging integrations.
+
+Each adapter handles:
+- Receiving messages from a platform
+- Sending messages/responses back
+- Platform-specific authentication
+- Message formatting and media handling
+"""
+
+from .base import BasePlatformAdapter, MessageEvent, SendResult
+from .qqbot import QQAdapter
+
+__all__ = [
+    "BasePlatformAdapter",
+    "MessageEvent",
+    "SendResult",
+    "QQAdapter",
+]

mindcli/_vendor/gateway/platforms/bluebubbles.py

@@ -0,0 +1,897 @@
+"""BlueBubbles iMessage platform adapter.
+
+Uses the local BlueBubbles macOS server for outbound REST sends and inbound
+webhooks.  Supports text messaging, media attachments (images, voice, video,
+documents), tapback reactions, typing indicators, and read receipts.
+
+Architecture based on PR #5869 (benjaminsehl) with inbound attachment
+downloading from PR #4588 (YuhangLin).
+"""
+
+import asyncio
+import json
+import logging
+import os
+import re
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import httpx
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+    cache_image_from_bytes,
+    cache_audio_from_bytes,
+    cache_document_from_bytes,
+)
+from gateway.platforms.helpers import strip_markdown
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_WEBHOOK_HOST = "127.0.0.1"
+DEFAULT_WEBHOOK_PORT = 8645
+DEFAULT_WEBHOOK_PATH = "/bluebubbles-webhook"
+MAX_TEXT_LENGTH = 4000
+
+# Tapback reaction codes (BlueBubbles associatedMessageType values)
+_TAPBACK_ADDED = {
+    2000: "love", 2001: "like", 2002: "dislike",
+    2003: "laugh", 2004: "emphasize", 2005: "question",
+}
+_TAPBACK_REMOVED = {
+    3000: "love", 3001: "like", 3002: "dislike",
+    3003: "laugh", 3004: "emphasize", 3005: "question",
+}
+
+# Webhook event types that carry user messages
+_MESSAGE_EVENTS = {"new-message", "message", "updated-message"}
+
+# Log redaction patterns
+_PHONE_RE = re.compile(r"\+?\d{7,15}")
+_EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")
+
+
+def _redact(text: str) -> str:
+    """Redact phone numbers and emails from log output."""
+    text = _PHONE_RE.sub("[REDACTED]", text)
+    text = _EMAIL_RE.sub("[REDACTED]", text)
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def check_bluebubbles_requirements() -> bool:
+    try:
+        import aiohttp  # noqa: F401
+        import httpx as _httpx  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _normalize_server_url(raw: str) -> str:
+    value = (raw or "").strip()
+    if not value:
+        return ""
+    if not re.match(r"^https?://", value, flags=re.I):
+        value = f"http://{value}"
+    return value.rstrip("/")
+
+
+
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+class BlueBubblesAdapter(BasePlatformAdapter):
+    platform = Platform.BLUEBUBBLES
+    MAX_MESSAGE_LENGTH = MAX_TEXT_LENGTH
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.BLUEBUBBLES)
+        extra = config.extra or {}
+        self.server_url = _normalize_server_url(
+            extra.get("server_url") or os.getenv("BLUEBUBBLES_SERVER_URL", "")
+        )
+        self.password = extra.get("password") or os.getenv("BLUEBUBBLES_PASSWORD", "")
+        self.webhook_host = (
+            extra.get("webhook_host")
+            or os.getenv("BLUEBUBBLES_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST)
+        )
+        self.webhook_port = int(
+            extra.get("webhook_port")
+            or os.getenv("BLUEBUBBLES_WEBHOOK_PORT", str(DEFAULT_WEBHOOK_PORT))
+        )
+        self.webhook_path = (
+            extra.get("webhook_path")
+            or os.getenv("BLUEBUBBLES_WEBHOOK_PATH", DEFAULT_WEBHOOK_PATH)
+        )
+        if not str(self.webhook_path).startswith("/"):
+            self.webhook_path = f"/{self.webhook_path}"
+        self.send_read_receipts = bool(extra.get("send_read_receipts", True))
+        self.client: Optional[httpx.AsyncClient] = None
+        self._runner = None
+        self._private_api_enabled: Optional[bool] = None
+        self._helper_connected: bool = False
+        self._guid_cache: Dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # API helpers
+    # ------------------------------------------------------------------
+
+    def _api_url(self, path: str) -> str:
+        sep = "&" if "?" in path else "?"
+        return f"{self.server_url}{path}{sep}password={quote(self.password, safe='')}"
+
+    async def _api_get(self, path: str) -> Dict[str, Any]:
+        assert self.client is not None
+        res = await self.client.get(self._api_url(path))
+        res.raise_for_status()
+        return res.json()
+
+    async def _api_post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        assert self.client is not None
+        res = await self.client.post(self._api_url(path), json=payload)
+        res.raise_for_status()
+        return res.json()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        if not self.server_url or not self.password:
+            logger.error(
+                "[bluebubbles] BLUEBUBBLES_SERVER_URL and BLUEBUBBLES_PASSWORD are required"
+            )
+            return False
+        from aiohttp import web
+
+        self.client = httpx.AsyncClient(timeout=30.0)
+        try:
+            await self._api_get("/api/v1/ping")
+            info = await self._api_get("/api/v1/server/info")
+            server_data = (info or {}).get("data", {})
+            self._private_api_enabled = bool(server_data.get("private_api"))
+            self._helper_connected = bool(server_data.get("helper_connected"))
+            logger.info(
+                "[bluebubbles] connected to %s (private_api=%s, helper=%s)",
+                self.server_url,
+                self._private_api_enabled,
+                self._helper_connected,
+            )
+        except Exception as exc:
+            logger.error(
+                "[bluebubbles] cannot reach server at %s: %s", self.server_url, exc
+            )
+            if self.client:
+                await self.client.aclose()
+                self.client = None
+            return False
+
+        app = web.Application()
+        app.router.add_get("/health", lambda _: web.Response(text="ok"))
+        app.router.add_post(self.webhook_path, self._handle_webhook)
+        self._runner = web.AppRunner(app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, self.webhook_host, self.webhook_port)
+        await site.start()
+        self._mark_connected()
+        logger.info(
+            "[bluebubbles] webhook listening on http://%s:%s%s",
+            self.webhook_host,
+            self.webhook_port,
+            self.webhook_path,
+        )
+
+        # Register webhook with BlueBubbles server
+        # This is required for the server to know where to send events
+        await self._register_webhook()
+
+        return True
+
+    async def disconnect(self) -> None:
+        # Unregister webhook before cleaning up
+        await self._unregister_webhook()
+
+        if self.client:
+            await self.client.aclose()
+            self.client = None
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+        self._mark_disconnected()
+
+    @property
+    def _webhook_url(self) -> str:
+        """Compute the external webhook URL for BlueBubbles registration."""
+        host = self.webhook_host
+        if host in ("0.0.0.0", "127.0.0.1", "localhost", "::"):
+            host = "localhost"
+        return f"http://{host}:{self.webhook_port}{self.webhook_path}"
+
+    async def _find_registered_webhooks(self, url: str) -> list:
+        """Return list of BB webhook entries matching *url*."""
+        try:
+            res = await self._api_get("/api/v1/webhook")
+            data = res.get("data")
+            if isinstance(data, list):
+                return [wh for wh in data if wh.get("url") == url]
+        except Exception:
+            pass
+        return []
+
+    async def _register_webhook(self) -> bool:
+        """Register this webhook URL with the BlueBubbles server.
+
+        BlueBubbles requires webhooks to be registered via API before
+        it will send events.  Checks for an existing registration first
+        to avoid duplicates (e.g. after a crash without clean shutdown).
+        """
+        if not self.client:
+            return False
+
+        webhook_url = self._webhook_url
+
+        # Crash resilience — reuse an existing registration if present
+        existing = await self._find_registered_webhooks(webhook_url)
+        if existing:
+            logger.info(
+                "[bluebubbles] webhook already registered: %s", webhook_url
+            )
+            return True
+
+        payload = {
+            "url": webhook_url,
+            "events": ["new-message", "updated-message", "message"],
+        }
+
+        try:
+            res = await self._api_post("/api/v1/webhook", payload)
+            status = res.get("status", 0)
+            if 200 <= status < 300:
+                logger.info(
+                    "[bluebubbles] webhook registered with server: %s",
+                    webhook_url,
+                )
+                return True
+            else:
+                logger.warning(
+                    "[bluebubbles] webhook registration returned status %s: %s",
+                    status,
+                    res.get("message"),
+                )
+                return False
+        except Exception as exc:
+            logger.warning(
+                "[bluebubbles] failed to register webhook with server: %s",
+                exc,
+            )
+            return False
+
+    async def _unregister_webhook(self) -> bool:
+        """Unregister this webhook URL from the BlueBubbles server.
+
+        Removes *all* matching registrations to clean up any duplicates
+        left by prior crashes.
+        """
+        if not self.client:
+            return False
+
+        webhook_url = self._webhook_url
+        removed = False
+
+        try:
+            for wh in await self._find_registered_webhooks(webhook_url):
+                wh_id = wh.get("id")
+                if wh_id:
+                    res = await self.client.delete(
+                        self._api_url(f"/api/v1/webhook/{wh_id}")
+                    )
+                    res.raise_for_status()
+                    removed = True
+            if removed:
+                logger.info(
+                    "[bluebubbles] webhook unregistered: %s", webhook_url
+                )
+        except Exception as exc:
+            logger.debug(
+                "[bluebubbles] failed to unregister webhook (non-critical): %s",
+                exc,
+            )
+        return removed
+
+    # ------------------------------------------------------------------
+    # Chat GUID resolution
+    # ------------------------------------------------------------------
+
+    async def _resolve_chat_guid(self, target: str) -> Optional[str]:
+        """Resolve an email/phone to a BlueBubbles chat GUID.
+
+        If *target* already contains a semicolon (raw GUID format like
+        ``iMessage;-;user@example.com``), it is returned as-is.  Otherwise
+        the adapter queries the BlueBubbles chat list and matches on
+        ``chatIdentifier`` or participant address.
+        """
+        target = (target or "").strip()
+        if not target:
+            return None
+        # Already a raw GUID
+        if ";" in target:
+            return target
+        if target in self._guid_cache:
+            return self._guid_cache[target]
+        try:
+            payload = await self._api_post(
+                "/api/v1/chat/query",
+                {"limit": 100, "offset": 0, "with": ["participants"]},
+            )
+            for chat in payload.get("data", []) or []:
+                guid = chat.get("guid") or chat.get("chatGuid")
+                identifier = chat.get("chatIdentifier") or chat.get("identifier")
+                if identifier == target:
+                    if guid:
+                        self._guid_cache[target] = guid
+                    return guid
+                for part in chat.get("participants", []) or []:
+                    if (part.get("address") or "").strip() == target and guid:
+                        self._guid_cache[target] = guid
+                        return guid
+        except Exception:
+            pass
+        return None
+
+    async def _create_chat_for_handle(
+        self, address: str, message: str
+    ) -> SendResult:
+        """Create a new chat by sending the first message to *address*."""
+        payload = {
+            "addresses": [address],
+            "message": message,
+            "tempGuid": f"temp-{datetime.utcnow().timestamp()}",
+        }
+        try:
+            res = await self._api_post("/api/v1/chat/new", payload)
+            data = res.get("data") or {}
+            msg_id = data.get("guid") or data.get("messageGuid") or "ok"
+            return SendResult(success=True, message_id=str(msg_id), raw_response=res)
+        except Exception as exc:
+            return SendResult(success=False, error=str(exc))
+
+    # ------------------------------------------------------------------
+    # Text sending
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        text = strip_markdown(content or "")
+        if not text:
+            return SendResult(success=False, error="BlueBubbles send requires text")
+        chunks = self.truncate_message(text, max_length=self.MAX_MESSAGE_LENGTH)
+        last = SendResult(success=True)
+        for chunk in chunks:
+            guid = await self._resolve_chat_guid(chat_id)
+            if not guid:
+                # If the target looks like an address, try creating a new chat
+                if self._private_api_enabled and (
+                    "@" in chat_id or re.match(r"^\+\d+", chat_id)
+                ):
+                    return await self._create_chat_for_handle(chat_id, chunk)
+                return SendResult(
+                    success=False,
+                    error=f"BlueBubbles chat not found for target: {chat_id}",
+                )
+            payload: Dict[str, Any] = {
+                "chatGuid": guid,
+                "tempGuid": f"temp-{datetime.utcnow().timestamp()}",
+                "message": chunk,
+            }
+            if reply_to and self._private_api_enabled and self._helper_connected:
+                payload["method"] = "private-api"
+                payload["selectedMessageGuid"] = reply_to
+                payload["partIndex"] = 0
+            try:
+                res = await self._api_post("/api/v1/message/text", payload)
+                data = res.get("data") or {}
+                msg_id = data.get("guid") or data.get("messageGuid") or "ok"
+                last = SendResult(
+                    success=True, message_id=str(msg_id), raw_response=res
+                )
+            except Exception as exc:
+                return SendResult(success=False, error=str(exc))
+        return last
+
+    # ------------------------------------------------------------------
+    # Media sending (outbound)
+    # ------------------------------------------------------------------
+
+    async def _send_attachment(
+        self,
+        chat_id: str,
+        file_path: str,
+        filename: Optional[str] = None,
+        caption: Optional[str] = None,
+        is_audio_message: bool = False,
+    ) -> SendResult:
+        """Send a file attachment via BlueBubbles multipart upload."""
+        if not self.client:
+            return SendResult(success=False, error="Not connected")
+        if not os.path.isfile(file_path):
+            return SendResult(success=False, error=f"File not found: {file_path}")
+
+        guid = await self._resolve_chat_guid(chat_id)
+        if not guid:
+            return SendResult(success=False, error=f"Chat not found: {chat_id}")
+
+        fname = filename or os.path.basename(file_path)
+        try:
+            with open(file_path, "rb") as f:
+                files = {"attachment": (fname, f, "application/octet-stream")}
+                data: Dict[str, str] = {
+                    "chatGuid": guid,
+                    "name": fname,
+                    "tempGuid": uuid.uuid4().hex,
+                }
+                if is_audio_message:
+                    data["isAudioMessage"] = "true"
+                res = await self.client.post(
+                    self._api_url("/api/v1/message/attachment"),
+                    files=files,
+                    data=data,
+                    timeout=120,
+                )
+                res.raise_for_status()
+                result = res.json()
+
+            if caption:
+                await self.send(chat_id, caption)
+
+            if result.get("status") == 200:
+                rdata = result.get("data") or {}
+                msg_id = rdata.get("guid") if isinstance(rdata, dict) else None
+                return SendResult(
+                    success=True, message_id=msg_id, raw_response=result
+                )
+            return SendResult(
+                success=False,
+                error=result.get("message", "Attachment upload failed"),
+            )
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        try:
+            from gateway.platforms.base import cache_image_from_url
+
+            local_path = await cache_image_from_url(image_url)
+            return await self._send_attachment(chat_id, local_path, caption=caption)
+        except Exception:
+            return await super().send_image(chat_id, image_url, caption, reply_to)
+
+    async def send_image_file(
+        self,
+        chat_id: str,
+        image_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        return await self._send_attachment(chat_id, image_path, caption=caption)
+
+    async def send_voice(
+        self,
+        chat_id: str,
+        audio_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        return await self._send_attachment(
+            chat_id, audio_path, caption=caption, is_audio_message=True
+        )
+
+    async def send_video(
+        self,
+        chat_id: str,
+        video_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        return await self._send_attachment(chat_id, video_path, caption=caption)
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        return await self._send_attachment(
+            chat_id, file_path, filename=file_name, caption=caption
+        )
+
+    async def send_animation(
+        self,
+        chat_id: str,
+        animation_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        return await self.send_image(
+            chat_id, animation_url, caption, reply_to, metadata
+        )
+
+    # ------------------------------------------------------------------
+    # Typing indicators
+    # ------------------------------------------------------------------
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        if not self._private_api_enabled or not self._helper_connected or not self.client:
+            return
+        try:
+            guid = await self._resolve_chat_guid(chat_id)
+            if guid:
+                encoded = quote(guid, safe="")
+                await self.client.post(
+                    self._api_url(f"/api/v1/chat/{encoded}/typing"), timeout=5
+                )
+        except Exception:
+            pass
+
+    async def stop_typing(self, chat_id: str) -> None:
+        if not self._private_api_enabled or not self._helper_connected or not self.client:
+            return
+        try:
+            guid = await self._resolve_chat_guid(chat_id)
+            if guid:
+                encoded = quote(guid, safe="")
+                await self.client.delete(
+                    self._api_url(f"/api/v1/chat/{encoded}/typing"), timeout=5
+                )
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # Read receipts
+    # ------------------------------------------------------------------
+
+    async def mark_read(self, chat_id: str) -> bool:
+        if not self._private_api_enabled or not self._helper_connected or not self.client:
+            return False
+        try:
+            guid = await self._resolve_chat_guid(chat_id)
+            if guid:
+                encoded = quote(guid, safe="")
+                await self.client.post(
+                    self._api_url(f"/api/v1/chat/{encoded}/read"), timeout=5
+                )
+                return True
+        except Exception:
+            pass
+        return False
+
+    # ------------------------------------------------------------------
+    # Tapback reactions
+    # ------------------------------------------------------------------
+
+    # ------------------------------------------------------------------
+    # Chat info
+    # ------------------------------------------------------------------
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        is_group = ";+;" in (chat_id or "")
+        info: Dict[str, Any] = {
+            "name": chat_id,
+            "type": "group" if is_group else "dm",
+        }
+        try:
+            guid = await self._resolve_chat_guid(chat_id)
+            if guid:
+                encoded = quote(guid, safe="")
+                res = await self._api_get(
+                    f"/api/v1/chat/{encoded}?with=participants"
+                )
+                data = (res or {}).get("data", {})
+                display_name = (
+                    data.get("displayName")
+                    or data.get("chatIdentifier")
+                    or chat_id
+                )
+                participants = []
+                for p in data.get("participants", []) or []:
+                    addr = (p.get("address") or "").strip()
+                    if addr:
+                        participants.append(addr)
+                info["name"] = display_name
+                if participants:
+                    info["participants"] = participants
+        except Exception:
+            pass
+        return info
+
+    def format_message(self, content: str) -> str:
+        return strip_markdown(content)
+
+    # ------------------------------------------------------------------
+    # Inbound attachment downloading (from #4588)
+    # ------------------------------------------------------------------
+
+    async def _download_attachment(
+        self, att_guid: str, att_meta: Dict[str, Any]
+    ) -> Optional[str]:
+        """Download an attachment from BlueBubbles and cache it locally.
+
+        Returns the local file path on success, None on failure.
+        """
+        if not self.client:
+            return None
+        try:
+            encoded = quote(att_guid, safe="")
+            resp = await self.client.get(
+                self._api_url(f"/api/v1/attachment/{encoded}/download"),
+                timeout=60,
+                follow_redirects=True,
+            )
+            resp.raise_for_status()
+            data = resp.content
+
+            mime = (att_meta.get("mimeType") or "").lower()
+            transfer_name = att_meta.get("transferName", "")
+
+            if mime.startswith("image/"):
+                ext_map = {
+                    "image/jpeg": ".jpg",
+                    "image/png": ".png",
+                    "image/gif": ".gif",
+                    "image/webp": ".webp",
+                    "image/heic": ".jpg",
+                    "image/heif": ".jpg",
+                    "image/tiff": ".jpg",
+                }
+                ext = ext_map.get(mime, ".jpg")
+                return cache_image_from_bytes(data, ext)
+
+            if mime.startswith("audio/"):
+                ext_map = {
+                    "audio/mp3": ".mp3",
+                    "audio/mpeg": ".mp3",
+                    "audio/ogg": ".ogg",
+                    "audio/wav": ".wav",
+                    "audio/x-caf": ".mp3",
+                    "audio/mp4": ".m4a",
+                    "audio/aac": ".m4a",
+                }
+                ext = ext_map.get(mime, ".mp3")
+                return cache_audio_from_bytes(data, ext)
+
+            # Videos, documents, and everything else
+            filename = transfer_name or f"file_{uuid.uuid4().hex[:8]}"
+            return cache_document_from_bytes(data, filename)
+
+        except Exception as exc:
+            logger.warning(
+                "[bluebubbles] failed to download attachment %s: %s",
+                _redact(att_guid),
+                exc,
+            )
+            return None
+
+    # ------------------------------------------------------------------
+    # Webhook handling
+    # ------------------------------------------------------------------
+
+    def _extract_payload_record(
+        self, payload: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        data = payload.get("data")
+        if isinstance(data, dict):
+            return data
+        if isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    return item
+        if isinstance(payload.get("message"), dict):
+            return payload.get("message")
+        return payload if isinstance(payload, dict) else None
+
+    @staticmethod
+    def _value(*candidates: Any) -> Optional[str]:
+        for candidate in candidates:
+            if isinstance(candidate, str) and candidate.strip():
+                return candidate.strip()
+        return None
+
+    async def _handle_webhook(self, request):
+        from aiohttp import web
+
+        token = (
+            request.query.get("password")
+            or request.query.get("guid")
+            or request.headers.get("x-password")
+            or request.headers.get("x-guid")
+            or request.headers.get("x-bluebubbles-guid")
+        )
+        if token != self.password:
+            return web.json_response({"error": "unauthorized"}, status=401)
+        try:
+            raw = await request.read()
+            body = raw.decode("utf-8", errors="replace")
+            try:
+                payload = json.loads(body)
+            except Exception:
+                from urllib.parse import parse_qs
+
+                form = parse_qs(body)
+                payload_str = (
+                    form.get("payload")
+                    or form.get("data")
+                    or form.get("message")
+                    or [""]
+                )[0]
+                payload = json.loads(payload_str) if payload_str else {}
+        except Exception as exc:
+            logger.error("[bluebubbles] webhook parse error: %s", exc)
+            return web.json_response({"error": "invalid payload"}, status=400)
+
+        event_type = self._value(payload.get("type"), payload.get("event")) or ""
+        # Only process message events; silently acknowledge everything else
+        if event_type and event_type not in _MESSAGE_EVENTS:
+            return web.Response(text="ok")
+
+        record = self._extract_payload_record(payload) or {}
+        is_from_me = bool(
+            record.get("isFromMe")
+            or record.get("fromMe")
+            or record.get("is_from_me")
+        )
+        if is_from_me:
+            return web.Response(text="ok")
+
+        # Skip tapback reactions delivered as messages
+        assoc_type = record.get("associatedMessageType")
+        if isinstance(assoc_type, int) and assoc_type in {
+            **_TAPBACK_ADDED,
+            **_TAPBACK_REMOVED,
+        }:
+            return web.Response(text="ok")
+
+        text = (
+            self._value(
+                record.get("text"), record.get("message"), record.get("body")
+            )
+            or ""
+        )
+
+        # --- Inbound attachment handling ---
+        attachments = record.get("attachments") or []
+        media_urls: List[str] = []
+        media_types: List[str] = []
+        msg_type = MessageType.TEXT
+
+        for att in attachments:
+            att_guid = att.get("guid", "")
+            if not att_guid:
+                continue
+            cached = await self._download_attachment(att_guid, att)
+            if cached:
+                mime = (att.get("mimeType") or "").lower()
+                media_urls.append(cached)
+                media_types.append(mime)
+                if mime.startswith("image/"):
+                    msg_type = MessageType.PHOTO
+                elif mime.startswith("audio/") or (att.get("uti") or "").endswith(
+                    "caf"
+                ):
+                    msg_type = MessageType.VOICE
+                elif mime.startswith("video/"):
+                    msg_type = MessageType.VIDEO
+                else:
+                    msg_type = MessageType.DOCUMENT
+
+        # With multiple attachments, prefer PHOTO if any images present
+        if len(media_urls) > 1:
+            mime_prefixes = {(m or "").split("/")[0] for m in media_types}
+            if "image" in mime_prefixes:
+                msg_type = MessageType.PHOTO
+
+        if not text and media_urls:
+            text = "(attachment)"
+        # --- End attachment handling ---
+
+        chat_guid = self._value(
+            record.get("chatGuid"),
+            payload.get("chatGuid"),
+            record.get("chat_guid"),
+            payload.get("chat_guid"),
+            payload.get("guid"),
+        )
+        chat_identifier = self._value(
+            record.get("chatIdentifier"),
+            record.get("identifier"),
+            payload.get("chatIdentifier"),
+            payload.get("identifier"),
+        )
+        sender = (
+            self._value(
+                record.get("handle", {}).get("address")
+                if isinstance(record.get("handle"), dict)
+                else None,
+                record.get("sender"),
+                record.get("from"),
+                record.get("address"),
+            )
+            or chat_identifier
+            or chat_guid
+        )
+        if not (chat_guid or chat_identifier) and sender:
+            chat_identifier = sender
+        if not sender or not (chat_guid or chat_identifier) or not text:
+            return web.json_response({"error": "missing message fields"}, status=400)
+
+        session_chat_id = chat_guid or chat_identifier
+        is_group = bool(record.get("isGroup")) or (";+;" in (chat_guid or ""))
+        source = self.build_source(
+            chat_id=session_chat_id,
+            chat_name=chat_identifier or sender,
+            chat_type="group" if is_group else "dm",
+            user_id=sender,
+            user_name=sender,
+            chat_id_alt=chat_identifier,
+        )
+        event = MessageEvent(
+            text=text,
+            message_type=msg_type,
+            source=source,
+            raw_message=payload,
+            message_id=self._value(
+                record.get("guid"),
+                record.get("messageGuid"),
+                record.get("id"),
+            ),
+            reply_to_message_id=self._value(
+                record.get("threadOriginatorGuid"),
+                record.get("associatedMessageGuid"),
+            ),
+            media_urls=media_urls,
+            media_types=media_types,
+        )
+        task = asyncio.create_task(self.handle_message(event))
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+        # Fire-and-forget read receipt
+        if self.send_read_receipts and session_chat_id:
+            asyncio.create_task(self.mark_read(session_chat_id))
+
+        return web.Response(text="ok")
+

mindcli/_vendor/gateway/platforms/dashscope_realtime.py

@@ -0,0 +1,359 @@
+"""
+MIND OS 3.0 — 实时录音 WS 管线 (Phase B)
+
+从 V2 asr-proxy.cjs 移植到 Python asyncio + aiohttp。
+
+端点：GET /mindos-next/ws/record?token={JWT}&chatId={chatId}
+
+协议（与 V2 客户端兼容）：
+  客户端 → 服务端:  binary PCM16 帧 / {"type":"stop"}
+  服务端 → 客户端:  {"type":"proxy_connected","chatId":"..."}
+                   {"type":"partial","text":"..."}
+                   {"type":"final","text":"..."}
+                   {"type":"speech_started"/"speech_stopped"}
+                   {"type":"asr_reconnecting","attempt":N}
+                   {"type":"error","message":"..."}
+
+DashScope Realtime API（V5 协议，与 V2 asr-proxy.cjs 完全相同）：
+  wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen3-asr-flash-realtime
+  Auth: Authorization: bearer {DASHSCOPE_API_KEY}
+  发送: {"type":"input_audio_buffer.append","audio":"<base64>"}
+  停止: {"type":"input_audio_buffer.commit"} + {"type":"session.finish"}
+  接收: session.created / conversation.item.input_audio_transcription.* /
+        input_audio_buffer.speech_* / session.finished / error
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import time
+from datetime import datetime
+from pathlib import Path
+
+from aiohttp import web
+
+logger = logging.getLogger("dashscope_realtime")
+
+DASHSCOPE_ASR_URL   = "wss://dashscope.aliyuncs.com/api-ws/v1/realtime"
+DASHSCOPE_ASR_MODEL = os.getenv("DASHSCOPE_REALTIME_MODEL", "qwen3-asr-flash-realtime")
+MAX_RECONNECTS      = 3
+RECONNECT_BASE_MS   = 1000
+
+# ★ 架构修复：这里直接存放 MindOSSSEServer 实例的引用。
+# mindos_sse.py 在 start() 里导入本模块时调用 register_server(self)，
+# 始终使用同一个对象，彻底绕开 sys.modules 命名空间问题。
+_sse_server = None
+
+def register_server(server) -> None:
+    global _sse_server
+    _sse_server = server
+    logger.info("[Realtime] SSE server 已注入: %s", type(server).__name__)
+
+
+# ─── 公开入口（由 mindos_sse.py 注册为路由） ─────────────────
+
+async def handleWsRecord(request: web.Request) -> web.WebSocketResponse:
+    """
+    GET /mindos-next/ws/record?token={JWT}&chatId={chatId}
+    aiohttp WS handler。
+    """
+    from gateway.platforms.mindos_sse import _verifyTokenAsync, _CORS_HEADERS  # type: ignore
+
+    # 1. Auth via ?token= query param
+    token = request.rel_url.query.get("token", "")
+    chatId = request.rel_url.query.get("chatId", "")
+    if not token:
+        raise web.HTTPForbidden()
+
+    user = await _verifyTokenAsync(token)
+    if not user:
+        raise web.HTTPUnauthorized()
+    userId = user.get("sub") or user.get("userId", "")
+
+    if not chatId:
+        chatId = f"chat_{int(time.time() * 1000)}"
+
+    meetingId = request.rel_url.query.get("meetingId") or f"rec_{int(time.time() * 1000)}"
+    source   = request.rel_url.query.get("source", "mic")  # "mic" | "system"
+
+    logger.info("[Realtime] 客户端连接 userId=%s chatId=%s meeting=%s source=%s", userId, chatId, meetingId, source)
+
+    # 2. 升级到 WS
+    clientWs = web.WebSocketResponse(heartbeat=30)
+    await clientWs.prepare(request)
+
+    # 3. 初始化 MD 文件（wiki/{userId}/raw/）
+    wiki_root = os.getenv("MINDOS_WIKI_DIR", os.path.expanduser("~/.hermes/wiki"))
+    wiki_dir  = Path(wiki_root) / userId / "raw"
+    wiki_dir.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now()
+    suffix = "system" if source == "system" else "mic"
+    md_filename = f"{now.strftime('%Y-%m-%d_%H%M')}_{suffix}_recording.md"
+    md_file     = wiki_dir / md_filename
+    rel_path    = f"raw/{md_filename}"
+
+    # 写文件头
+    source_label = "系统拾音" if source == "system" else "麦克风"
+    md_file.write_text(
+        f"# 录音转写 {now.strftime('%Y-%m-%d %H:%M')}（{source_label}）\n\n> 实时录制于 MindOS\n\n",
+        encoding="utf-8",
+    )
+
+    total_chars  = 0
+    sentences    = []          # 收集完整句子
+    reconnects   = 0
+    ds_ready     = asyncio.Event()
+    stop_event   = asyncio.Event()
+    audio_queue: asyncio.Queue[bytes | None] = asyncio.Queue()
+
+    # ─── DashScope WS 协程 ──────────────────────────────────
+
+    async def run_dashscope():
+        nonlocal reconnects, total_chars
+
+        api_key = os.getenv("DASHSCOPE_API_KEY", "")
+        if not api_key:
+            await _send_client(clientWs, {"type": "error", "message": "ASR 未配置 DASHSCOPE_API_KEY"})
+            return
+
+        import aiohttp as _aio
+        url = f"{DASHSCOPE_ASR_URL}?model={DASHSCOPE_ASR_MODEL}"
+        headers = {"Authorization": f"bearer {api_key}"}
+
+        while reconnects <= MAX_RECONNECTS and not stop_event.is_set():
+            try:
+                async with _aio.ClientSession() as session:
+                    async with session.ws_connect(url, headers=headers) as dsWs:
+                        ds_ready.clear()   # 连接成功，但等 session.created 后再就绪
+                        reconnects = 0  # 连上就重置
+                        logger.info("[Realtime] DashScope 已连接 meeting=%s", meetingId)
+
+                        async def send_audio_loop():
+                            """从队列取音频帧发给 DashScope"""
+                            while True:
+                                chunk = await audio_queue.get()
+                                if chunk is None:
+                                    # stop 信号
+                                    try:
+                                        await dsWs.send_str(json.dumps(
+                                            {"type": "input_audio_buffer.commit"}))
+                                        await dsWs.send_str(json.dumps(
+                                            {"type": "session.finish"}))
+                                    except Exception:
+                                        pass
+                                    return
+                                if dsWs.closed:
+                                    return
+                                try:
+                                    b64 = base64.b64encode(chunk).decode()
+                                    await dsWs.send_str(json.dumps(
+                                        {"type": "input_audio_buffer.append", "audio": b64}))
+                                except Exception as e:
+                                    logger.warning("[Realtime] send audio err: %s", e)
+
+                        # 并发：发音频 + 收结果
+                        send_task = asyncio.create_task(send_audio_loop())
+
+                        async for msg in dsWs:
+                            if msg.type != _aio.WSMsgType.TEXT:
+                                continue
+                            try:
+                                evt = json.loads(msg.data)
+                            except Exception:
+                                continue
+
+                            etype = evt.get("type", "")
+
+                            if etype == "session.created":
+                                # V2 验证：DashScope V5 Realtime 不需要 session.update
+                                # 直接就绪，开始接收音频帧
+                                ds_ready.set()
+                                await _send_client(clientWs, {
+                                    "type": "proxy_connected", "chatId": chatId})
+
+                            elif etype == "conversation.item.input_audio_transcription.completed":
+                                text = (evt.get("transcript") or "").strip()
+                                if text:
+                                    sentences.append(text)
+                                    total_chars += len(text)
+                                    elapsed = int(time.time() * 1000 - start_ms) // 1000
+                                    mm, ss = divmod(elapsed, 60)
+                                    # 实时写 MD
+                                    with md_file.open("a", encoding="utf-8") as f:
+                                        f.write(f"[{mm:02d}:{ss:02d}] {text}\n")
+                                    await _send_client(clientWs, {"type": "final", "text": text})
+
+                            elif etype == "conversation.item.input_audio_transcription.text":
+                                text = (evt.get("transcript") or "").strip()
+                                if text:
+                                    await _send_client(clientWs, {"type": "partial", "text": text})
+
+                            elif etype in (
+                                "input_audio_buffer.speech_started",
+                                "input_audio_buffer.speech_stopped",
+                            ):
+                                short = "speech_started" if "started" in etype else "speech_stopped"
+                                await _send_client(clientWs, {"type": short})
+
+                            elif etype == "session.finished":
+                                logger.info("[Realtime] session.finished meeting=%s", meetingId)
+                                send_task.cancel()
+                                stop_event.set()
+                                return
+
+                            elif etype == "error":
+                                err_msg = evt.get("error", {}).get("message") or str(evt)
+                                logger.error("[Realtime] DashScope error: %s", err_msg)
+                                await _send_client(clientWs, {"type": "error", "message": err_msg})
+
+                        send_task.cancel()
+
+            except Exception as e:
+                logger.warning("[Realtime] DashScope 连接异常: %s", e)
+
+            if stop_event.is_set():
+                return
+
+            # 重连
+            reconnects += 1
+            if reconnects > MAX_RECONNECTS:
+                logger.error("[Realtime] 重连次数耗尽 meeting=%s", meetingId)
+                break
+
+            delay = RECONNECT_BASE_MS * (2 ** (reconnects - 1)) / 1000
+            logger.warning("[Realtime] %ss 后重连(%d/%d) meeting=%s",
+                           delay, reconnects, MAX_RECONNECTS, meetingId)
+            await _send_client(clientWs, {
+                "type": "asr_reconnecting",
+                "attempt": reconnects,
+                "maxAttempts": MAX_RECONNECTS,
+            })
+            ds_ready.clear()
+            await asyncio.sleep(delay)
+
+    # ─── 主循环：接收客户端消息 ──────────────────────────────
+
+    start_ms = int(time.time() * 1000)
+    ds_task  = asyncio.create_task(run_dashscope())
+
+    import aiohttp as _aio2
+    async for msg in clientWs:
+        if msg.type == _aio2.WSMsgType.BINARY:
+            # PCM16 帧 → 入队
+            await ds_ready.wait()   # 等 DashScope 握手完成再转发
+            await audio_queue.put(msg.data)
+
+        elif msg.type == _aio2.WSMsgType.TEXT:
+            try:
+                cmd = json.loads(msg.data)
+                if cmd.get("type") == "stop":
+                    logger.info("[Realtime] 收到 stop 命令 meeting=%s", meetingId)
+                    await audio_queue.put(None)   # 通知 send_audio_loop 发 commit+finish
+            except Exception:
+                pass
+
+        elif msg.type in (_aio2.WSMsgType.ERROR, _aio2.WSMsgType.CLOSE):
+            break
+
+    # 客户端断开：确保停止
+    stop_event.set()
+    await audio_queue.put(None)
+    try:
+        await asyncio.wait_for(ds_task, timeout=10)
+    except (asyncio.TimeoutError, Exception):
+        pass
+
+    # ─── Finalize：写 MD 结尾 + 写 DB + 推 SSE ──────────────
+
+    # P0-4: 计算实时录音总时长
+    duration_seconds = (time.time() * 1000 - start_ms) / 1000.0
+
+    await _finalize(
+        md_file=md_file,
+        rel_path=rel_path,
+        sentences=sentences,
+        total_chars=total_chars,
+        chatId=chatId,
+        meetingId=meetingId,
+        userId=userId,
+        duration_seconds=duration_seconds,
+        source=source,
+    )
+
+    logger.info("[Realtime] 会话结束 meeting=%s chars=%d", meetingId, total_chars)
+    return clientWs
+
+
+# ─── 内部工具函数 ─────────────────────────────────────────────
+
+async def _send_client(ws: web.WebSocketResponse, data: dict) -> None:
+    """安全发送 JSON 到客户端"""
+    if ws.closed:
+        return
+    try:
+        await ws.send_str(json.dumps(data, ensure_ascii=False))
+    except Exception:
+        pass
+
+
+async def _finalize(
+    md_file: Path,
+    rel_path: str,
+    sentences: list[str],
+    total_chars: int,
+    chatId: str,
+    meetingId: str,
+    userId: str,
+    duration_seconds: float = 0.0,
+    source: str = "mic",
+) -> None:
+    """写 MD 结尾、持久化到 DB、推送 SSE md:appended。
+
+    使用 voice2md_atoms 共享原子层（④ db_persist + ⑤ sse_push）。
+    """
+    from voice2md_atoms import (  # type: ignore
+        persist_audio_result, push_md_appended, deduct_asr_credits,
+    )
+
+    # 写结尾标记
+    try:
+        with md_file.open("a", encoding="utf-8") as f:
+            f.write("\n---（录音结束）\n")
+    except Exception as e:
+        logger.warning("[Realtime] 写 MD 结尾失败: %s", e)
+
+    # 读完整内容（用于内嵌推送）
+    md_content = ""
+    try:
+        md_content = md_file.read_text(encoding="utf-8")
+    except Exception:
+        pass
+
+    # ④ db_persist（chars=0 也写 DB，确保刷新后可恢复）
+    persist_audio_result(
+        chat_id=chatId, user_id=userId,
+        file_name=md_file.name, md_path=rel_path,
+        chars=total_chars, md_content=md_content,
+        oss_read_url="",  # 实时录音无 OSS URL
+    )
+
+    # 积分扣减（实时录音：2 credits/秒）
+    asr_credits = max(1, int(duration_seconds * 2))
+    deduct_asr_credits(
+        user_id=userId, chat_id=chatId, credits=asr_credits,
+        tx_type="asr_realtime", model="qwen3-asr-flash-realtime",
+        seconds=duration_seconds,
+    )
+
+    # ⑤ sse_push
+    # ★ 使用模块级 _sse_server（由 mindos_sse.start() 直接注入）
+    push_md_appended(
+        sse_server=_sse_server, user_id=userId, chat_id=chatId,
+        file=rel_path, chars=total_chars, md_content=md_content,
+        message=f"✅ 录音转写完成（{total_chars} 字）",
+        source=source,
+    )
+

mindcli/_vendor/gateway/platforms/deepview_materials.py

@@ -0,0 +1,425 @@
+"""
+⚠️ DEPRECATED（文档解析部分）— 请勿复制或修改以下函数 ⚠️
+
+以下函数已被 infra.pipelines.anyfile2md 统一管线取代：
+  - _is_vlm_needed()        → infra.atoms.text_sniffer
+  - _extract_pdf_vlm()      → infra.atoms.page_rasterizer + vlm_ocr + oss_presign
+  - _extract_pdf_to_md()    → infra.atoms.text_extractor
+  - _extract_docx()         → infra.atoms.text_extractor
+  - _extract_txt()          → infra.atoms.text_extractor
+  - _simulate_extract()     → 不再需要
+
+✅ _extract_audio_asr() 是 deepview 专有的音频 ASR 管线，不在废弃范围。
+
+迁移方式参考 xinzong_materials.py（2026-04-20 已完成迁移）：
+  from infra.pipelines.anyfile2md import parseLocal
+  result = await parseLocal(str(raw_path), original_filename)
+
+新的统一管线位于：
+  mindOSv2/hermes-overlay/infra/pipelines/anyfile2md.py
+  mindOSv2/hermes-overlay/infra/atoms/  （6 个原子操作）
+"""
+
+import asyncio
+import hashlib
+import os
+import time
+import logging
+import json
+import re
+from pathlib import Path
+from hermes_constants import get_hermes_home
+
+logger = logging.getLogger(__name__)
+
+async def process_uploaded_material_oss(
+    oss_key: str, 
+    original_filename: str, 
+    context_id: str, 
+    push_event_fn, 
+    user_id: str,
+    org_id: str = "org_001"
+):
+    """
+    1. Downloads native PDF from OSS
+    2. Runs deduplication
+    3. Sniffs doc to decide between VLM or pure text
+    4. Executes the relevant pipeline to produce .md
+    """
+    from hermes_constants import get_hermes_home
+    # 1. Fetch from OSS
+    oss_ak = os.getenv("ALIYUN_ACCESS_KEY_ID", "")
+    oss_sk = os.getenv("ALIYUN_ACCESS_KEY_SECRET", "")
+    oss_bucket = os.getenv("OSS_BUCKET", "meetings-dev")
+    oss_endpoint = os.getenv("OSS_ENDPOINT", "oss-cn-beijing.aliyuncs.com")
+
+    if not all([oss_ak, oss_sk]):
+        logger.error("[DeepviewMaterials] Missing OSS keys in backend .env. Skipping ingestion.")
+        return
+        
+    try:
+        import oss2
+        auth = oss2.Auth(oss_ak, oss_sk)
+        bucket = oss2.Bucket(auth, oss_endpoint, oss_bucket)
+        
+        logger.info(f"[DeepviewMaterials] Over internal network fetching {oss_key}...")
+        result = bucket.get_object(oss_key)
+        file_bytes = result.read()
+    except Exception as e:
+        logger.error(f"[DeepviewMaterials] OSS Download failed: {e}")
+        return
+
+    # 2. Hashing
+    file_hash = hashlib.md5(file_bytes).hexdigest()
+    
+    # 3. 解析 Context 路由（深维专属双上下文 FS-as-Database 管线）
+    storageDir = os.getenv("DEEPVIEW_STORAGE_DIR", os.path.expanduser("~/Downloads/Coding/医生助理智能体/backend/storage"))
+    storage_root = Path(storageDir)
+    user_id_safe = user_id if user_id else "unknown"
+    org_id_safe = org_id if org_id else "org_001"
+    
+    user_dir = storage_root / "users" / user_id_safe
+    org_dir = storage_root / "orgs" / org_id_safe
+    platform_dir = storage_root / "platform"
+    
+    ext = os.path.splitext(original_filename)[1].lower()
+    
+    # 过滤恶意文件
+    if ext == '.url' or ext == '.exe' or ext == '.sh':
+        logger.warning(f"Rejected unsafe file: {original_filename}")
+        return
+        
+    # 定义路由目标
+    if context_id.startswith("recording:"):
+        recordingId = context_id.split(":", 1)[1]
+        parts = recordingId.split("/")
+        if len(parts) > 1:
+            # 旧格式（已归档）：recording:clientId/asrId
+            clientId = parts[0]
+            asrId = parts[-1]
+            base_dir = user_dir / "clients" / clientId / "history"
+            raw_path = base_dir / f"{asrId}_raw{ext}"
+            md_path = base_dir / f"{asrId}.md"
+        else:
+            # 新格式（Inbox）：recording:asrId
+            asrId = parts[0]
+            base_dir = user_dir / "inbox" / asrId
+            raw_path = base_dir / f"asr_raw{ext}"
+            md_path = base_dir / "asr.md"
+    elif context_id.startswith("client:"):
+        clientId = context_id.split(":", 1)[1]
+        base_dir = user_dir / "clients" / clientId
+        # 客户全景上下文：碎片化资料存档（可能是合同、病历单据等）
+        raw_path = base_dir / f"{file_hash}_raw{ext}"
+        md_path = base_dir / f"{file_hash}.md"
+    elif context_id.startswith("wiki:") or context_id == "deepview":
+        # 存入本机构域的 wiki 库
+        base_dir = org_dir / "wiki"
+        raw_path = base_dir / f"{file_hash}_raw{ext}"
+        md_path = base_dir / f"{file_hash}.md"
+    elif context_id.startswith("platform:"):
+        # 预留平台运维口
+        base_dir = platform_dir / "wiki"
+        raw_path = base_dir / f"{file_hash}_raw{ext}"
+        md_path = base_dir / f"{file_hash}.md"
+    elif context_id.startswith("doctor:"):
+        base_dir = user_dir
+        raw_path = base_dir / f"doctor_profile_raw{ext}"
+        md_path = base_dir / "doctor_profile.md"
+    else:
+        # Fallback 容错隔离区
+        base_dir = user_dir / "misc" / context_id.replace(":", "_")
+        raw_path = base_dir / f"{file_hash}_raw{ext}"
+        md_path = base_dir / f"{file_hash}.md"
+
+    base_dir.mkdir(parents=True, exist_ok=True)
+    
+    # 幂等性检查：文件是否已经存在
+    if md_path.exists():
+        logger.info(f"[DeepviewMaterials] File {original_filename} already processed for {context_id}.")
+        push_event_fn(user_id, "material:done", {
+            "projectId": context_id,
+            "filename": original_filename,
+            "fileId": file_hash
+        })
+        return
+        
+    # 存储原始二进制文件（用于溯源和重试）
+    with open(raw_path, "wb") as f:
+        f.write(file_bytes)
+        
+    # Process
+    loop = asyncio.get_event_loop()
+    try:
+        if ext == ".pdf":
+            # Sniffer
+            if _is_vlm_needed(str(raw_path)):
+                logger.info("[DeepviewMaterials] Sniffer: Routing to OSS+VLM Pipeline.")
+                await loop.run_in_executor(None, _extract_pdf_vlm, str(raw_path), str(md_path), bucket, file_hash, original_filename)
+            else:
+                logger.info("[DeepviewMaterials] Sniffer: Routing to Pymupdf4llm text Pipeline.")
+                await loop.run_in_executor(None, _extract_pdf_to_md, str(raw_path), str(md_path), original_filename)
+        elif ext in [".docx", ".doc"]:
+            await loop.run_in_executor(None, _extract_docx, str(raw_path), str(md_path), original_filename)
+        elif ext in [".txt", ".md", ".csv"]:
+            await loop.run_in_executor(None, _extract_txt, str(raw_path), str(md_path), original_filename)
+        elif ext in [".m4a", ".mp3", ".wav", ".webm", ".ogg"]:
+            await loop.run_in_executor(None, _extract_audio_asr, str(raw_path), str(md_path), original_filename, bucket, oss_key)
+        else:
+            await loop.run_in_executor(None, _simulate_extract, str(md_path), original_filename)
+        
+        # ★ 持久化到 deepview_materials 表（DB 唯一真相）
+        try:
+            from hermes_state import SessionDB
+            db = SessionDB()
+            def _do(conn):
+                conn.execute(
+                    "INSERT OR IGNORE INTO deepview_materials (id, filename, context_id, user_id, source, created_at) "
+                    "VALUES (?, ?, ?, ?, 'upload', ?)",
+                    (file_hash, original_filename, context_id, user_id, time.time())
+                )
+            db._execute_write(_do)
+        except Exception as e:
+            logger.warning(f"[DeepviewMaterials] Failed to persist to DB: {e}")
+
+        # Emit SSE success
+        logger.info(f"[DeepviewMaterials] Successfully ingested {original_filename}")
+        push_event_fn(user_id, "material:done", {
+            "projectId": context_id,
+            "filename": original_filename,
+            "fileId": file_hash
+        })
+        
+    except Exception as e:
+        logger.error(f"[DeepviewMaterials] Failed to extract {original_filename}: {e}", exc_info=True)
+
+
+def _is_vlm_needed(pdf_path: str) -> bool:
+    try:
+        import fitz
+        doc = fitz.open(pdf_path)
+        if len(doc) == 0: return False
+        
+        check_pages = min(2, len(doc))
+        total_text_len = 0
+        vlm_vote = 0
+        
+        for i in range(check_pages):
+            page = doc[i]
+            rect = page.rect
+            width, height = rect.width, rect.height
+            if width > height and (width / height) > 1.2:
+                vlm_vote += 1
+            text = page.get_text()
+            total_text_len += len(text.strip())
+            
+        doc.close()
+        
+        # If any page is landscape => PPT => VLM
+        if vlm_vote > 0:
+            return True
+            
+        # If extremely low text density => Scanned => VLM
+        if check_pages > 0 and (total_text_len / check_pages) < 100:
+            return True
+            
+        return False
+    except Exception as e:
+        logger.error(f"Sniffer error: {e}")
+        return False # Fallback to pymupdf text
+
+def _extract_pdf_vlm(pdf_path: str, md_path: str, bucket, file_hash: str, original_filename: str):
+    import fitz
+    import tempfile
+    from openai import OpenAI
+    
+    # 统一收拢于服务端的 LiteLLM 代理管线（彻底废弃单独的 DASHSCOPE 授权）
+    litellm_key = os.getenv("GEMINI_API_KEY")
+    litellm_base = os.getenv("GEMINI_BASE_URL", "http://127.0.0.1:4000/v1")
+    vlm_model = os.getenv("DEEPVIEW_MODEL", "gemini3.1pro-vertex") 
+    
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        doc = fitz.open(pdf_path)
+        zoom = 200 / 72
+        mat = fitz.Matrix(zoom, zoom)
+        
+        urls = []
+        for i, page in enumerate(doc):
+            pix = page.get_pixmap(matrix=mat)
+            img_path = os.path.join(tmp_dir, f"page_{i + 1:03d}.png")
+            pix.save(img_path)
+            pix = None
+            
+            oss_key = f"deepview-assets/{file_hash}/slides/page_{i+1:03d}.png"
+            bucket.put_object_from_file(oss_key, img_path)
+            url = bucket.sign_url('GET', oss_key, 3600*24)
+            urls.append(url)
+            
+        doc.close()
+        
+        if not litellm_key or not litellm_base:
+            with open(md_path, "w", encoding="utf-8") as f:
+                f.write(f"# Document: VLM Extraction Skipped\n\n缺少LiteLLM网关配置 (GEMINI_API_KEY/GEMINI_BASE_URL)。已将 {len(urls)} 页图片传至 OSS。")
+            return
+
+        client = OpenAI(base_url=litellm_base, api_key=litellm_key, timeout=120)
+        
+        markdown_blocks = []
+        for i, u in enumerate(urls):
+            prompt = "详细分析这张页面图片。如果是PPT请提炼核心观点、标题和要素。如果是扫描件请保留每一段具体文字。用纯粹的Markdown格式输出，不要使用```markdown包裹。"
+            try:
+                resp = client.chat.completions.create(
+                    model=vlm_model,
+                    messages=[{
+                        "role": "user",
+                        "content": [
+                            {"type": "image_url", "image_url": {"url": u}},
+                            {"type": "text", "text": prompt}
+                        ]
+                    }],
+                    max_tokens=2048,
+                    temperature=0.1
+                )
+                txt = resp.choices[0].message.content.strip()
+                if txt.startswith("```markdown"):
+                    txt = txt[11:]
+                txt = txt.strip("`\n ")
+                markdown_blocks.append(f"## 第 {i+1} 页\n\n{txt}\n")
+            except Exception as e:
+                logger.error(f"LiteLLM VLM error page {i+1}: {e}")
+                markdown_blocks.append(f"## 第 {i+1} 页\n*(视觉提取超时或失败)*\n")
+                
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(f"# Document: {original_filename}\n\n")
+            f.write("\n---\n".join(markdown_blocks))
+
+def _extract_pdf_to_md(pdf_path: str, md_path: str, original_filename: str):
+    try:
+        import pymupdf4llm
+        md_text = pymupdf4llm.to_markdown(pdf_path)
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(f"# Document: {original_filename}\n\n")
+            f.write(md_text)
+    except Exception as e:
+        logger.error(f"pymupdf4llm error: {e}")
+        _simulate_extract(md_path, os.path.basename(pdf_path))
+
+def _extract_docx(docx_path: str, md_path: str, original_filename: str):
+    try:
+        import docx
+        doc = docx.Document(docx_path)
+        text = "\n\n".join([p.text for p in doc.paragraphs if p.text.strip()])
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(f"# Document: {original_filename}\n\n")
+            f.write(text)
+    except Exception as e:
+        logger.error(f"docx error: {e}")
+        _simulate_extract(md_path, os.path.basename(docx_path))
+
+def _extract_txt(txt_path: str, md_path: str, original_filename: str):
+    try:
+        with open(txt_path, "r", encoding="utf-8") as f:
+            text = f.read()
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(f"# Document: {original_filename}\n\n")
+            f.write(text)
+    except Exception as e:
+        logger.error(f"txt error: {e}")
+        _simulate_extract(md_path, os.path.basename(txt_path))
+
+def _extract_audio_asr(audio_path: str, md_path: str, original_filename: str, bucket, oss_key: str):
+    import requests
+    import time
+    try:
+        dashscope_key = os.getenv("DASHSCOPE_API_KEY", "")
+        if not dashscope_key:
+            logger.error("[DeepviewMaterials] Missing DASHSCOPE_API_KEY for ASR.")
+            _simulate_extract(md_path, f"{original_filename} (ASR Failed: No DASHSCOPE_API_KEY)")
+            return
+
+        logger.info(f"[DeepviewMaterials] Submitting Long Audio ASR Task for {original_filename}")
+        
+        # 1. 签名前端传上来的 OSS URL (给阿里大模型长音频异步读取用)
+        audio_url = bucket.sign_url('GET', oss_key, 3600 * 24)
+        
+        # 2. 提交异步听写任务
+        headers = {
+            "Authorization": f"Bearer {dashscope_key}",
+            "Content-Type": "application/json",
+            "X-DashScope-Async": "enable"
+        }
+        payload = {
+            "model": "paraformer-v2", # qwen-audio 长语音引擎（唯一支持说话人分离的离线异步服务）
+            "input": {"file_urls": [audio_url]},
+            "parameters": {
+                "diarization_enabled": True # 开启说话人角色分离 (音色解析)
+            }
+        }
+        
+        resp = requests.post("https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription", json=payload, headers=headers)
+        if resp.status_code != 200:
+            logger.error(f"[DeepviewMaterials] ASR Submit Failed: {resp.text}")
+            _simulate_extract(md_path, f"{original_filename} (ASR Submit Failed)")
+            return
+            
+        task_id = resp.json()["output"]["task_id"]
+        logger.info(f"[DeepviewMaterials] ASR Task Submitted: {task_id}. Polling...")
+        
+        # 3. 轮询结果
+        polling_url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
+        while True:
+            status_resp = requests.get(polling_url, headers=headers)
+            if status_resp.status_code != 200:
+                logger.error(f"[DeepviewMaterials] ASR Polling HTTP Error: {status_resp.text}")
+                break
+                
+            data = status_resp.json()
+            status = data["output"]["task_status"]
+            
+            if status == "SUCCEEDED":
+                result_url = data["output"]["results"][0]["transcription_url"]
+                result_resp = requests.get(result_url)
+                transcripts = result_resp.json().get("transcripts", [])
+                
+                if not transcripts:
+                    with open(md_path, "w", encoding="utf-8") as f:
+                        f.write(f"# 🎵 面诊录音: {original_filename}\n\n*(未能提取出任何语音)*")
+                    return
+                    
+                sentences = transcripts[0].get("sentences", [])
+                
+                # 4. 格式化落盘：音色换行隔离
+                with open(md_path, "w", encoding="utf-8") as f:
+                    f.write(f"# 🎵 面诊录音: {original_filename}\n\n")
+                    last_speaker = None
+                    for s in sentences:
+                        spk = s.get("speaker_id", "Unknown")
+                        # Paraformer 通常返回 spk_0, spk_1 或者根据音色聚类
+                        spk_label = f"**说话人 {spk}**" if spk != "Unknown" else "**未知说话人**"
+                        text = s.get("text", "")
+                        
+                        if spk != last_speaker:
+                            f.write(f"\n\n{spk_label}: {text}")
+                            last_speaker = spk
+                        else:
+                            f.write(f" {text}")
+                
+                logger.info(f"[DeepviewMaterials] ASR Diarization successfully completed for {original_filename}")
+                return
+                
+            elif status == "FAILED":
+                logger.error(f"[DeepviewMaterials] ASR Task Failed Internally: {data}")
+                break
+                
+            time.sleep(3) # 轮询间隔
+            
+        # 兜底
+        _simulate_extract(md_path, f"{original_filename} (ASR Polling Failed or Timeout)")
+        
+    except Exception as e:
+        logger.error(f"[DeepviewMaterials] audio error: {e}", exc_info=True)
+        _simulate_extract(md_path, os.path.basename(audio_path))
+
+def _simulate_extract(md_path: str, original_filename: str):
+    with open(md_path, "w", encoding="utf-8") as f:
+        f.write(f"# Document: {original_filename}\n\nNotice: Extracted via simple fallback parser.")

mindcli/_vendor/gateway/platforms/dingtalk.py

@@ -0,0 +1,333 @@
+"""
+DingTalk platform adapter using Stream Mode.
+
+Uses dingtalk-stream SDK for real-time message reception without webhooks.
+Responses are sent via DingTalk's session webhook (markdown format).
+
+Requires:
+    pip install dingtalk-stream httpx
+    DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET env vars
+
+Configuration in config.yaml:
+    platforms:
+      dingtalk:
+        enabled: true
+        extra:
+          client_id: "your-app-key"      # or DINGTALK_CLIENT_ID env var
+          client_secret: "your-secret"   # or DINGTALK_CLIENT_SECRET env var
+"""
+
+import asyncio
+import logging
+import os
+import re
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+try:
+    import dingtalk_stream
+    from dingtalk_stream import ChatbotHandler, ChatbotMessage
+    DINGTALK_STREAM_AVAILABLE = True
+except ImportError:
+    DINGTALK_STREAM_AVAILABLE = False
+    dingtalk_stream = None  # type: ignore[assignment]
+
+try:
+    import httpx
+    HTTPX_AVAILABLE = True
+except ImportError:
+    HTTPX_AVAILABLE = False
+    httpx = None  # type: ignore[assignment]
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.helpers import MessageDeduplicator
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+MAX_MESSAGE_LENGTH = 20000
+RECONNECT_BACKOFF = [2, 5, 10, 30, 60]
+_SESSION_WEBHOOKS_MAX = 500
+_DINGTALK_WEBHOOK_RE = re.compile(r'^https://api\.dingtalk\.com/')
+
+
+def check_dingtalk_requirements() -> bool:
+    """Check if DingTalk dependencies are available and configured."""
+    if not DINGTALK_STREAM_AVAILABLE or not HTTPX_AVAILABLE:
+        return False
+    if not os.getenv("DINGTALK_CLIENT_ID") or not os.getenv("DINGTALK_CLIENT_SECRET"):
+        return False
+    return True
+
+
+class DingTalkAdapter(BasePlatformAdapter):
+    """DingTalk chatbot adapter using Stream Mode.
+
+    The dingtalk-stream SDK maintains a long-lived WebSocket connection.
+    Incoming messages arrive via a ChatbotHandler callback. Replies are
+    sent via the incoming message's session_webhook URL using httpx.
+    """
+
+    MAX_MESSAGE_LENGTH = MAX_MESSAGE_LENGTH
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.DINGTALK)
+
+        extra = config.extra or {}
+        self._client_id: str = extra.get("client_id") or os.getenv("DINGTALK_CLIENT_ID", "")
+        self._client_secret: str = extra.get("client_secret") or os.getenv("DINGTALK_CLIENT_SECRET", "")
+
+        self._stream_client: Any = None
+        self._stream_task: Optional[asyncio.Task] = None
+        self._http_client: Optional["httpx.AsyncClient"] = None
+
+        # Message deduplication
+        self._dedup = MessageDeduplicator(max_size=1000)
+        # Map chat_id -> session_webhook for reply routing
+        self._session_webhooks: Dict[str, str] = {}
+
+    # -- Connection lifecycle -----------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to DingTalk via Stream Mode."""
+        if not DINGTALK_STREAM_AVAILABLE:
+            logger.warning("[%s] dingtalk-stream not installed. Run: pip install dingtalk-stream", self.name)
+            return False
+        if not HTTPX_AVAILABLE:
+            logger.warning("[%s] httpx not installed. Run: pip install httpx", self.name)
+            return False
+        if not self._client_id or not self._client_secret:
+            logger.warning("[%s] DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required", self.name)
+            return False
+
+        try:
+            self._http_client = httpx.AsyncClient(timeout=30.0)
+
+            credential = dingtalk_stream.Credential(self._client_id, self._client_secret)
+            self._stream_client = dingtalk_stream.DingTalkStreamClient(credential)
+
+            # Capture the current event loop for cross-thread dispatch
+            loop = asyncio.get_running_loop()
+            handler = _IncomingHandler(self, loop)
+            self._stream_client.register_callback_handler(
+                dingtalk_stream.ChatbotMessage.TOPIC, handler
+            )
+
+            self._stream_task = asyncio.create_task(self._run_stream())
+            self._mark_connected()
+            logger.info("[%s] Connected via Stream Mode", self.name)
+            return True
+        except Exception as e:
+            logger.error("[%s] Failed to connect: %s", self.name, e)
+            return False
+
+    async def _run_stream(self) -> None:
+        """Run the blocking stream client with auto-reconnection."""
+        backoff_idx = 0
+        while self._running:
+            try:
+                logger.debug("[%s] Starting stream client...", self.name)
+                await asyncio.to_thread(self._stream_client.start)
+            except asyncio.CancelledError:
+                return
+            except Exception as e:
+                if not self._running:
+                    return
+                logger.warning("[%s] Stream client error: %s", self.name, e)
+
+            if not self._running:
+                return
+
+            delay = RECONNECT_BACKOFF[min(backoff_idx, len(RECONNECT_BACKOFF) - 1)]
+            logger.info("[%s] Reconnecting in %ds...", self.name, delay)
+            await asyncio.sleep(delay)
+            backoff_idx += 1
+
+    async def disconnect(self) -> None:
+        """Disconnect from DingTalk."""
+        self._running = False
+        self._mark_disconnected()
+
+        if self._stream_task:
+            self._stream_task.cancel()
+            try:
+                await self._stream_task
+            except asyncio.CancelledError:
+                pass
+            self._stream_task = None
+
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+        self._stream_client = None
+        self._session_webhooks.clear()
+        self._dedup.clear()
+        logger.info("[%s] Disconnected", self.name)
+
+    # -- Inbound message processing -----------------------------------------
+
+    async def _on_message(self, message: "ChatbotMessage") -> None:
+        """Process an incoming DingTalk chatbot message."""
+        msg_id = getattr(message, "message_id", None) or uuid.uuid4().hex
+        if self._dedup.is_duplicate(msg_id):
+            logger.debug("[%s] Duplicate message %s, skipping", self.name, msg_id)
+            return
+
+        text = self._extract_text(message)
+        if not text:
+            logger.debug("[%s] Empty message, skipping", self.name)
+            return
+
+        # Chat context
+        conversation_id = getattr(message, "conversation_id", "") or ""
+        conversation_type = getattr(message, "conversation_type", "1")
+        is_group = str(conversation_type) == "2"
+        sender_id = getattr(message, "sender_id", "") or ""
+        sender_nick = getattr(message, "sender_nick", "") or sender_id
+        sender_staff_id = getattr(message, "sender_staff_id", "") or ""
+
+        chat_id = conversation_id or sender_id
+        chat_type = "group" if is_group else "dm"
+
+        # Store session webhook for reply routing (validate origin to prevent SSRF)
+        session_webhook = getattr(message, "session_webhook", None) or ""
+        if session_webhook and chat_id and _DINGTALK_WEBHOOK_RE.match(session_webhook):
+            if len(self._session_webhooks) >= _SESSION_WEBHOOKS_MAX:
+                # Evict oldest entry to cap memory growth
+                try:
+                    self._session_webhooks.pop(next(iter(self._session_webhooks)))
+                except StopIteration:
+                    pass
+            self._session_webhooks[chat_id] = session_webhook
+
+        source = self.build_source(
+            chat_id=chat_id,
+            chat_name=getattr(message, "conversation_title", None),
+            chat_type=chat_type,
+            user_id=sender_id,
+            user_name=sender_nick,
+            user_id_alt=sender_staff_id if sender_staff_id else None,
+        )
+
+        # Parse timestamp
+        create_at = getattr(message, "create_at", None)
+        try:
+            timestamp = datetime.fromtimestamp(int(create_at) / 1000, tz=timezone.utc) if create_at else datetime.now(tz=timezone.utc)
+        except (ValueError, OSError, TypeError):
+            timestamp = datetime.now(tz=timezone.utc)
+
+        event = MessageEvent(
+            text=text,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=msg_id,
+            raw_message=message,
+            timestamp=timestamp,
+        )
+
+        logger.debug("[%s] Message from %s in %s: %s",
+                      self.name, sender_nick, chat_id[:20] if chat_id else "?", text[:50])
+        await self.handle_message(event)
+
+    @staticmethod
+    def _extract_text(message: "ChatbotMessage") -> str:
+        """Extract plain text from a DingTalk chatbot message."""
+        text = getattr(message, "text", None) or ""
+        if isinstance(text, dict):
+            content = text.get("content", "").strip()
+        else:
+            content = str(text).strip()
+
+        # Fall back to rich text if present
+        if not content:
+            rich_text = getattr(message, "rich_text", None)
+            if rich_text and isinstance(rich_text, list):
+                parts = [item["text"] for item in rich_text
+                         if isinstance(item, dict) and item.get("text")]
+                content = " ".join(parts).strip()
+        return content
+
+    # -- Outbound messaging -------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a markdown reply via DingTalk session webhook."""
+        metadata = metadata or {}
+
+        session_webhook = metadata.get("session_webhook") or self._session_webhooks.get(chat_id)
+        if not session_webhook:
+            return SendResult(success=False,
+                              error="No session_webhook available. Reply must follow an incoming message.")
+
+        if not self._http_client:
+            return SendResult(success=False, error="HTTP client not initialized")
+
+        payload = {
+            "msgtype": "markdown",
+            "markdown": {"title": "Hermes", "text": content[:self.MAX_MESSAGE_LENGTH]},
+        }
+
+        try:
+            resp = await self._http_client.post(session_webhook, json=payload, timeout=15.0)
+            if resp.status_code < 300:
+                return SendResult(success=True, message_id=uuid.uuid4().hex[:12])
+            body = resp.text
+            logger.warning("[%s] Send failed HTTP %d: %s", self.name, resp.status_code, body[:200])
+            return SendResult(success=False, error=f"HTTP {resp.status_code}: {body[:200]}")
+        except httpx.TimeoutException:
+            return SendResult(success=False, error="Timeout sending message to DingTalk")
+        except Exception as e:
+            logger.error("[%s] Send error: %s", self.name, e)
+            return SendResult(success=False, error=str(e))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """DingTalk does not support typing indicators."""
+        pass
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return basic info about a DingTalk conversation."""
+        return {"name": chat_id, "type": "group" if "group" in chat_id.lower() else "dm"}
+
+
+# ---------------------------------------------------------------------------
+# Internal stream handler
+# ---------------------------------------------------------------------------
+
+class _IncomingHandler(ChatbotHandler if DINGTALK_STREAM_AVAILABLE else object):
+    """dingtalk-stream ChatbotHandler that forwards messages to the adapter."""
+
+    def __init__(self, adapter: DingTalkAdapter, loop: asyncio.AbstractEventLoop):
+        if DINGTALK_STREAM_AVAILABLE:
+            super().__init__()
+        self._adapter = adapter
+        self._loop = loop
+
+    def process(self, message: "ChatbotMessage"):
+        """Called by dingtalk-stream in its thread when a message arrives.
+
+        Schedules the async handler on the main event loop.
+        """
+        loop = self._loop
+        if loop is None or loop.is_closed():
+            logger.error("[DingTalk] Event loop unavailable, cannot dispatch message")
+            return dingtalk_stream.AckMessage.STATUS_OK, "OK"
+
+        future = asyncio.run_coroutine_threadsafe(self._adapter._on_message(message), loop)
+        try:
+            future.result(timeout=60)
+        except Exception:
+            logger.exception("[DingTalk] Error processing incoming message")
+
+        return dingtalk_stream.AckMessage.STATUS_OK, "OK"

mindcli/_vendor/gateway/platforms/doc_parser.py

@@ -0,0 +1,335 @@
+"""
+⚠️ DEPRECATED — 请勿修改、复制或引用此文件 ⚠️
+
+本文件已被 infra.pipelines.anyfile2md 统一管线取代。
+mindos_sse.py 已完成迁移（2026-04-20），不再调用此模块。
+
+新的统一管线位于：
+  mindOSv2/hermes-overlay/infra/pipelines/anyfile2md.py
+  mindOSv2/hermes-overlay/infra/atoms/  （6 个原子操作）
+
+原始文件保留仅供参考，下次部署时将删除。
+
+──────────────────────────────────────────────────────
+以下为原始 docstring（仅供考古）：
+
+doc_parser.py — AnyFile2MD 通用文件解析模块（已废弃）
+
+架构约束（SPEC_anyfile2md_doc_parser.md v1.1）：
+  ❌ 不依赖 LLMAgno（V2 遗留）——前代隔离铁律
+  ❌ 不调用 LLM（VL 降级除外），不写 DB，不持久化任何状态
+  ✅ VL 调用直接走 LiteLLM Gateway（OpenAI SDK）
+  ✅ 封闭函数（铁律 1）：只做格式分发 + 文本提取 + 返回 Markdown
+
+公开接口：
+  parse_to_markdown(read_url, filename, ...) → str
+  is_supported_doc(filename) → bool
+  SUPPORTED_DOC_EXTS → set
+
+依赖：
+  python-docx    （≈V2 mammoth —— DOCX 文本提取）
+  pdfplumber     （≈V2 pdf-parse —— PDF 文字提取）
+  PyMuPDF (fitz) （≈V2 pdf-to-img —— PDF 逐页光栅化，VL 降级用）
+  openai         （VL 调用，hermes 已有）
+  httpx          （OSS 下载/上传，hermes 已有）
+"""
+
+import logging
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# ─── 格式分类（移植自 V2 normalize-manager.cjs L14-30） ─────
+
+AUDIO_EXTS = {
+    ".mp3", ".mp4", ".m4a", ".wav", ".webm",
+    ".ogg", ".aac", ".flac", ".opus", ".amr",
+}
+IMAGE_EXTS = {
+    ".png", ".jpg", ".jpeg", ".bmp", ".gif",
+    ".webp", ".tiff", ".tif",
+}
+DOCX_EXTS = {".docx", ".doc"}
+PDF_EXTS = {".pdf"}
+TEXT_EXTS = {".txt", ".md", ".markdown", ".rst", ".log"}
+
+# 所有支持的非音频格式（前端 accept 属性用）
+SUPPORTED_DOC_EXTS = IMAGE_EXTS | DOCX_EXTS | PDF_EXTS | TEXT_EXTS
+
+
+def is_supported_doc(filename: str) -> bool:
+    """判断文件是否为支持的文档/图片格式。"""
+    ext = Path(filename).suffix.lower()
+    return ext in SUPPORTED_DOC_EXTS
+
+
+# ─── VL 提示词（从 LLMAgno/server.py 复制并固化） ────────────
+
+VL_EXTRACT_PROMPT = """请仔细阅读这张图片中的所有内容，并以结构化的纯文本形式输出：
+
+1. 完整转录图片中的所有文字内容，保留原始排版结构（标题、段落、列表等）
+2. 如果图片包含表格，用 Markdown 表格格式输出
+3. 如果图片包含图表（柱状图、折线图、饼图等），用文字描述图表的数据和趋势
+4. 如果图片包含流程图或示意图，用文字描述其结构和逻辑关系
+5. 忽略页眉页脚、页码、水印等装饰性元素
+
+直接输出内容，不要加任何前缀说明或总结。"""
+
+
+# ─── 主函数 ─────────────────────────────────────────────────
+
+async def parse_to_markdown(
+    read_url: str,
+    filename: str,
+    *,
+    max_pages: int = 30,
+    vl_model: str = "qwen-vl",
+) -> dict:
+    """
+    下载 OSS 文件 → 按扩展名分流解析 → 返回解析结果。
+
+    封闭函数（铁律 1）：不写 DB，不持久化状态。
+    VL 调用直接走 LiteLLM Gateway（前代隔离铁律）。
+
+    Args:
+        read_url:  OSS 可读 URL（由 generate_oss_presign 返回）
+        filename:  原始文件名（用于判断扩展名）
+        max_pages: PDF 最大处理页数（安全守卫，V2 验证值=30）
+        vl_model:  VL 模型别名（LiteLLM 标准别名）
+
+    Returns:
+        {
+            "text": str,        # Markdown 格式的文本内容
+            "provider": str,    # 使用的解析方式
+            "vl_pages": int,    # VL 识别的页数（用于积分计算）
+        }
+
+    Raises:
+        ValueError: 不支持的文件格式
+        RuntimeError: 解析失败
+    """
+    ext = Path(filename).suffix.lower()
+
+    if ext in AUDIO_EXTS:
+        raise ValueError(f"音频文件请走 /api/audio/transcribe 管线: {ext}")
+
+    if ext not in SUPPORTED_DOC_EXTS:
+        raise ValueError(f"不支持的文件格式: {ext}")
+
+    # 1. 下载到临时文件
+    tmp_path = await _download_to_temp(read_url, filename)
+
+    try:
+        if ext in TEXT_EXTS:
+            text = _read_text_file(tmp_path)
+            return {"text": text, "provider": "text_read", "vl_pages": 0}
+
+        if ext in IMAGE_EXTS:
+            text = await _vl_extract_image(read_url, filename, vl_model)
+            return {"text": text, "provider": "vl_image", "vl_pages": 1}
+
+        if ext in DOCX_EXTS:
+            text = _extract_docx(tmp_path)
+            return {"text": text, "provider": "python_docx", "vl_pages": 0}
+
+        if ext in PDF_EXTS:
+            # PDF 双策略降级（移植自 V2 normalize-manager L260-280）
+            text = _extract_pdf_text(tmp_path)
+            if len(text.strip()) >= 50:
+                return {"text": text, "provider": "pdfplumber", "vl_pages": 0}
+
+            logger.info(
+                "[DocParser] PDF 文字过少 (%d字)，降级到 VL 逐页识别",
+                len(text.strip()),
+            )
+            text, page_count = await _vl_extract_pdf_pages(
+                tmp_path, filename, max_pages, vl_model,
+            )
+            return {"text": text, "provider": "vl_pdf_pages", "vl_pages": page_count}
+
+        # 兜底：尝试直读
+        text = _read_text_file(tmp_path)
+        return {"text": text, "provider": "text_fallback", "vl_pages": 0}
+
+    finally:
+        _cleanup_temp(tmp_path)
+
+
+# ─── 各格式解析函数 ──────────────────────────────────────────
+
+def _extract_docx(file_path: str) -> str:
+    """DOCX → Markdown 文本。等价于 V2 mammoth.extractRawText()。"""
+    import docx  # python-docx
+
+    doc = docx.Document(file_path)
+    paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
+    return "\n\n".join(paragraphs)
+
+
+def _extract_pdf_text(file_path: str) -> str:
+    """PDF 文字提取。等价于 V2 pdf-parse。"""
+    import pdfplumber
+
+    texts = []
+    with pdfplumber.open(file_path) as pdf:
+        for page in pdf.pages:
+            text = page.extract_text()
+            if text:
+                texts.append(text)
+    return "\n\n".join(texts)
+
+
+async def _vl_extract_image(
+    image_url: str,
+    filename: str,
+    model: str = "qwen-vl",
+) -> str:
+    """单张图片 VL 识别。直接走 LiteLLM Gateway（前代隔离铁律）。"""
+    import openai
+
+    client = openai.AsyncOpenAI(
+        base_url=os.getenv("LITELLM_BASE_URL", "http://127.0.0.1:4000/v1"),
+        api_key=os.getenv("LITELLM_API_KEY", ""),
+    )
+
+    start = time.time()
+    response = await client.chat.completions.create(
+        model=model,
+        messages=[{
+            "role": "user",
+            "content": [
+                {"type": "image_url", "image_url": {"url": image_url}},
+                {"type": "text", "text": VL_EXTRACT_PROMPT},
+            ],
+        }],
+        max_tokens=4096,
+        temperature=0.1,
+    )
+
+    text = response.choices[0].message.content or ""
+    elapsed = int((time.time() - start) * 1000)
+    logger.info(
+        "[DocParser] VL ✅ model=%s, text_len=%d, elapsed=%dms, file=%s",
+        model, len(text), elapsed, filename,
+    )
+    return text
+
+
+async def _vl_extract_pdf_pages(
+    file_path: str,
+    filename: str,
+    max_pages: int,
+    model: str,
+) -> tuple[str, int]:
+    """扫描型 PDF 逐页 VL 识别。移植自 V2 extractPdfViaVL。
+
+    Returns:
+        (markdown_text, page_count) — page_count 用于积分计算
+    """
+    import fitz  # PyMuPDF
+
+    doc = fitz.open(file_path)
+    total_pages = len(doc)
+    pages = []
+    processed_count = 0
+
+    for i, page in enumerate(doc):
+        if i >= max_pages:
+            logger.warning(
+                "[DocParser] PDF 页数超限 (%d/%d)，截断", max_pages, total_pages,
+            )
+            break
+
+        # 光栅化 → PNG 字节
+        pix = page.get_pixmap(dpi=200)
+        img_bytes = pix.tobytes("png")
+
+        # 每页独立 try-except（V2 验证的韧性策略）
+        try:
+            img_url = await _upload_temp_image(
+                img_bytes, f"{filename}_p{i}.png",
+            )
+            text = await _vl_extract_image(img_url, f"{filename}_p{i}", model)
+            if text.strip():
+                pages.append(f"## 第 {i + 1} 页\n\n{text}")
+                processed_count += 1
+        except Exception as e:
+            logger.warning(
+                "[DocParser] PDF 第%d页 VL 失败（跳过）: %s", i + 1, e,
+            )
+
+    doc.close()
+    return "\n\n".join(pages), processed_count
+
+
+# ─── 辅助函数 ────────────────────────────────────────────────
+
+def _read_text_file(file_path: str) -> str:
+    """直读文本文件，含二进制安全检查（移植自 V2 normalize-manager L287-299）。"""
+    with open(file_path, "rb") as f:
+        raw = f.read()
+
+    # null 字节检测：防止二进制文件误读
+    if b"\x00" in raw[:1024]:
+        raise ValueError("文件包含二进制内容，无法作为文本处理")
+
+    return raw.decode("utf-8", errors="replace")
+
+
+async def _download_to_temp(read_url: str, filename: str) -> str:
+    """从 OSS URL 下载到临时文件，返回临时路径。"""
+    suffix = Path(filename).suffix or ".bin"
+
+    async with httpx.AsyncClient(timeout=120) as client:
+        resp = await client.get(read_url)
+        resp.raise_for_status()
+
+    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=suffix)
+    tmp.write(resp.content)
+    tmp.close()
+
+    logger.info(
+        "[DocParser] 下载完成: %s → %s (%d bytes)",
+        filename, tmp.name, len(resp.content),
+    )
+    return tmp.name
+
+
+async def _upload_temp_image(img_bytes: bytes, filename: str) -> str:
+    """上传临时图片到 OSS，返回可读 URL（VL 逐页降级用）。
+
+    复用 flash_asr.generate_oss_presign + httpx PUT。
+    """
+    from flash_asr import generate_oss_presign  # type: ignore
+
+    ext = Path(filename).suffix or ".png"
+    # 使用独立的 OSS 前缀，与音频/文档区分
+    presign = generate_oss_presign(
+        user_id="vl_temp", ext=ext,
+        prefix="mindos-next/vl-temp",
+    )
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.put(
+            presign["upload_url"],
+            content=img_bytes,
+            headers={"Content-Type": presign["content_type"]},
+        )
+        resp.raise_for_status()
+
+    logger.debug("[DocParser] 临时图片已上传: %s", presign["oss_key"])
+    return presign["read_url"]
+
+
+def _cleanup_temp(tmp_path: str) -> None:
+    """删除临时文件，fire-and-forget。"""
+    try:
+        os.unlink(tmp_path)
+    except Exception:
+        pass

mindcli/_vendor/gateway/platforms/email.py

@@ -0,0 +1,625 @@
+"""
+Email platform adapter for the Hermes gateway.
+
+Allows users to interact with Hermes by sending emails.
+Uses IMAP to receive and SMTP to send messages.
+
+Environment variables:
+    EMAIL_IMAP_HOST     — IMAP server host (e.g., imap.gmail.com)
+    EMAIL_IMAP_PORT     — IMAP server port (default: 993)
+    EMAIL_SMTP_HOST     — SMTP server host (e.g., smtp.gmail.com)
+    EMAIL_SMTP_PORT     — SMTP server port (default: 587)
+    EMAIL_ADDRESS       — Email address for the agent
+    EMAIL_PASSWORD      — Email password or app-specific password
+    EMAIL_POLL_INTERVAL — Seconds between mailbox checks (default: 15)
+    EMAIL_ALLOWED_USERS — Comma-separated list of allowed sender addresses
+"""
+
+import asyncio
+import email as email_lib
+import imaplib
+import logging
+import os
+import re
+import smtplib
+import ssl
+import uuid
+from email.header import decode_header
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.base import MIMEBase
+from email import encoders
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+    cache_document_from_bytes,
+    cache_image_from_bytes,
+)
+from gateway.config import Platform, PlatformConfig
+
+logger = logging.getLogger(__name__)
+# Automated sender patterns — emails from these are silently ignored
+_NOREPLY_PATTERNS = (
+    "noreply", "no-reply", "no_reply", "donotreply", "do-not-reply",
+    "mailer-daemon", "postmaster", "bounce", "notifications@",
+    "automated@", "auto-confirm", "auto-reply", "automailer",
+)
+
+# RFC headers that indicate bulk/automated mail
+_AUTOMATED_HEADERS = {
+    "Auto-Submitted": lambda v: v.lower() != "no",
+    "Precedence": lambda v: v.lower() in ("bulk", "list", "junk"),
+    "X-Auto-Response-Suppress": lambda v: bool(v),
+    "List-Unsubscribe": lambda v: bool(v),
+}
+
+# Gmail-safe max length per email body
+MAX_MESSAGE_LENGTH = 50_000
+
+# Supported image extensions for inline detection
+_IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
+
+def _is_automated_sender(address: str, headers: dict) -> bool:
+    """Return True if this email is from an automated/noreply source."""
+    addr = address.lower()
+    if any(pattern in addr for pattern in _NOREPLY_PATTERNS):
+        return True
+    for header, check in _AUTOMATED_HEADERS.items():
+        value = headers.get(header, "")
+        if value and check(value):
+            return True
+    return False
+    
+def check_email_requirements() -> bool:
+    """Check if email platform dependencies are available."""
+    addr = os.getenv("EMAIL_ADDRESS")
+    pwd = os.getenv("EMAIL_PASSWORD")
+    imap = os.getenv("EMAIL_IMAP_HOST")
+    smtp = os.getenv("EMAIL_SMTP_HOST")
+    if not all([addr, pwd, imap, smtp]):
+        return False
+    return True
+
+
+def _decode_header_value(raw: str) -> str:
+    """Decode an RFC 2047 encoded email header into a plain string."""
+    parts = decode_header(raw)
+    decoded = []
+    for part, charset in parts:
+        if isinstance(part, bytes):
+            decoded.append(part.decode(charset or "utf-8", errors="replace"))
+        else:
+            decoded.append(part)
+    return " ".join(decoded)
+
+
+def _extract_text_body(msg: email_lib.message.Message) -> str:
+    """Extract the plain-text body from a potentially multipart email."""
+    if msg.is_multipart():
+        for part in msg.walk():
+            content_type = part.get_content_type()
+            disposition = str(part.get("Content-Disposition", ""))
+            # Skip attachments
+            if "attachment" in disposition:
+                continue
+            if content_type == "text/plain":
+                payload = part.get_payload(decode=True)
+                if payload:
+                    charset = part.get_content_charset() or "utf-8"
+                    return payload.decode(charset, errors="replace")
+        # Fallback: try text/html and strip tags
+        for part in msg.walk():
+            content_type = part.get_content_type()
+            disposition = str(part.get("Content-Disposition", ""))
+            if "attachment" in disposition:
+                continue
+            if content_type == "text/html":
+                payload = part.get_payload(decode=True)
+                if payload:
+                    charset = part.get_content_charset() or "utf-8"
+                    html = payload.decode(charset, errors="replace")
+                    return _strip_html(html)
+        return ""
+    else:
+        payload = msg.get_payload(decode=True)
+        if payload:
+            charset = msg.get_content_charset() or "utf-8"
+            text = payload.decode(charset, errors="replace")
+            if msg.get_content_type() == "text/html":
+                return _strip_html(text)
+            return text
+        return ""
+
+
+def _strip_html(html: str) -> str:
+    """Naive HTML tag stripper for fallback text extraction."""
+    text = re.sub(r"<br\s*/?>", "\n", html, flags=re.IGNORECASE)
+    text = re.sub(r"<p[^>]*>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"</p>", "\n", text, flags=re.IGNORECASE)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = re.sub(r"&nbsp;", " ", text)
+    text = re.sub(r"&amp;", "&", text)
+    text = re.sub(r"&lt;", "<", text)
+    text = re.sub(r"&gt;", ">", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def _extract_email_address(raw: str) -> str:
+    """Extract bare email address from 'Name <addr>' format."""
+    match = re.search(r"<([^>]+)>", raw)
+    if match:
+        return match.group(1).strip().lower()
+    return raw.strip().lower()
+
+
+def _extract_attachments(
+    msg: email_lib.message.Message,
+    skip_attachments: bool = False,
+) -> List[Dict[str, Any]]:
+    """Extract attachment metadata and cache files locally.
+
+    When *skip_attachments* is True, all attachment/inline parts are ignored
+    (useful for malware protection or bandwidth savings).
+    """
+    attachments = []
+    if not msg.is_multipart():
+        return attachments
+
+    for part in msg.walk():
+        disposition = str(part.get("Content-Disposition", ""))
+        if skip_attachments and ("attachment" in disposition or "inline" in disposition):
+            continue
+        if "attachment" not in disposition and "inline" not in disposition:
+            continue
+        # Skip text/plain and text/html body parts
+        content_type = part.get_content_type()
+        if content_type in ("text/plain", "text/html") and "attachment" not in disposition:
+            continue
+
+        filename = part.get_filename()
+        if filename:
+            filename = _decode_header_value(filename)
+        else:
+            ext = part.get_content_subtype() or "bin"
+            filename = f"attachment.{ext}"
+
+        payload = part.get_payload(decode=True)
+        if not payload:
+            continue
+
+        ext = Path(filename).suffix.lower()
+        if ext in _IMAGE_EXTS:
+            try:
+                cached_path = cache_image_from_bytes(payload, ext)
+            except ValueError:
+                logger.debug("Skipping non-image attachment %s (invalid magic bytes)", filename)
+                continue
+            attachments.append({
+                "path": cached_path,
+                "filename": filename,
+                "type": "image",
+                "media_type": content_type,
+            })
+        else:
+            cached_path = cache_document_from_bytes(payload, filename)
+            attachments.append({
+                "path": cached_path,
+                "filename": filename,
+                "type": "document",
+                "media_type": content_type,
+            })
+
+    return attachments
+
+
+class EmailAdapter(BasePlatformAdapter):
+    """Email gateway adapter using IMAP (receive) and SMTP (send)."""
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.EMAIL)
+
+        self._address = os.getenv("EMAIL_ADDRESS", "")
+        self._password = os.getenv("EMAIL_PASSWORD", "")
+        self._imap_host = os.getenv("EMAIL_IMAP_HOST", "")
+        self._imap_port = int(os.getenv("EMAIL_IMAP_PORT", "993"))
+        self._smtp_host = os.getenv("EMAIL_SMTP_HOST", "")
+        self._smtp_port = int(os.getenv("EMAIL_SMTP_PORT", "587"))
+        self._poll_interval = int(os.getenv("EMAIL_POLL_INTERVAL", "15"))
+
+        # Skip attachments — configured via config.yaml:
+        #   platforms:
+        #     email:
+        #       skip_attachments: true
+        extra = config.extra or {}
+        self._skip_attachments = extra.get("skip_attachments", False)
+
+        # Track message IDs we've already processed to avoid duplicates
+        self._seen_uids: set = set()
+        self._seen_uids_max: int = 2000   # cap to prevent unbounded memory growth
+        self._poll_task: Optional[asyncio.Task] = None
+
+        # Map chat_id (sender email) -> last subject + message-id for threading
+        self._thread_context: Dict[str, Dict[str, str]] = {}
+
+        logger.info("[Email] Adapter initialized for %s", self._address)
+
+    def _trim_seen_uids(self) -> None:
+        """Keep only the most recent UIDs to prevent unbounded memory growth.
+
+        IMAP UIDs are monotonically increasing integers. When the set grows
+        beyond the cap, we keep only the highest half — old UIDs are safe to
+        drop because new messages always have higher UIDs and IMAP's UNSEEN
+        flag prevents re-delivery regardless.
+        """
+        if len(self._seen_uids) <= self._seen_uids_max:
+            return
+        try:
+            # UIDs are bytes like b'1234' — sort numerically and keep top half
+            sorted_uids = sorted(self._seen_uids, key=lambda u: int(u))
+            keep = self._seen_uids_max // 2
+            self._seen_uids = set(sorted_uids[-keep:])
+            logger.debug("[Email] Trimmed seen UIDs to %d entries", len(self._seen_uids))
+        except (ValueError, TypeError):
+            # Fallback: just clear old entries if sort fails
+            self._seen_uids = set(list(self._seen_uids)[-self._seen_uids_max // 2:])
+
+    async def connect(self) -> bool:
+        """Connect to the IMAP server and start polling for new messages."""
+        try:
+            # Test IMAP connection
+            imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port, timeout=30)
+            imap.login(self._address, self._password)
+            # Mark all existing messages as seen so we only process new ones
+            imap.select("INBOX")
+            status, data = imap.uid("search", None, "ALL")
+            if status == "OK" and data and data[0]:
+                for uid in data[0].split():
+                    self._seen_uids.add(uid)
+            # Keep only the most recent UIDs to prevent unbounded growth
+            self._trim_seen_uids()
+            imap.logout()
+            logger.info("[Email] IMAP connection test passed. %d existing messages skipped.", len(self._seen_uids))
+        except Exception as e:
+            logger.error("[Email] IMAP connection failed: %s", e)
+            return False
+
+        try:
+            # Test SMTP connection
+            smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
+            smtp.starttls(context=ssl.create_default_context())
+            smtp.login(self._address, self._password)
+            smtp.quit()
+            logger.info("[Email] SMTP connection test passed.")
+        except Exception as e:
+            logger.error("[Email] SMTP connection failed: %s", e)
+            return False
+
+        self._running = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+        print(f"[Email] Connected as {self._address}")
+        return True
+
+    async def disconnect(self) -> None:
+        """Stop polling and disconnect."""
+        self._running = False
+        if self._poll_task:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+        logger.info("[Email] Disconnected.")
+
+    async def _poll_loop(self) -> None:
+        """Poll IMAP for new messages at regular intervals."""
+        while self._running:
+            try:
+                await self._check_inbox()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("[Email] Poll error: %s", e)
+            await asyncio.sleep(self._poll_interval)
+
+    async def _check_inbox(self) -> None:
+        """Check INBOX for unseen messages and dispatch them."""
+        # Run IMAP operations in a thread to avoid blocking the event loop
+        loop = asyncio.get_running_loop()
+        messages = await loop.run_in_executor(None, self._fetch_new_messages)
+        for msg_data in messages:
+            await self._dispatch_message(msg_data)
+
+    def _fetch_new_messages(self) -> List[Dict[str, Any]]:
+        """Fetch new (unseen) messages from IMAP. Runs in executor thread."""
+        results = []
+        try:
+            imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port, timeout=30)
+            try:
+                imap.login(self._address, self._password)
+                imap.select("INBOX")
+
+                status, data = imap.uid("search", None, "UNSEEN")
+                if status != "OK" or not data or not data[0]:
+                    return results
+
+                for uid in data[0].split():
+                    if uid in self._seen_uids:
+                        continue
+                    self._seen_uids.add(uid)
+                    # Trim periodically to prevent unbounded memory growth
+                    if len(self._seen_uids) > self._seen_uids_max:
+                        self._trim_seen_uids()
+
+                    status, msg_data = imap.uid("fetch", uid, "(RFC822)")
+                    if status != "OK":
+                        continue
+
+                    raw_email = msg_data[0][1]
+                    msg = email_lib.message_from_bytes(raw_email)
+
+                    sender_raw = msg.get("From", "")
+                    sender_addr = _extract_email_address(sender_raw)
+                    sender_name = _decode_header_value(sender_raw)
+                    # Remove email from name if present
+                    if "<" in sender_name:
+                        sender_name = sender_name.split("<")[0].strip().strip('"')
+
+                    subject = _decode_header_value(msg.get("Subject", "(no subject)"))
+                    message_id = msg.get("Message-ID", "")
+                    in_reply_to = msg.get("In-Reply-To", "")
+                    # Skip automated/noreply senders before any processing
+                    msg_headers = dict(msg.items())
+                    if _is_automated_sender(sender_addr, msg_headers):
+                        logger.debug("[Email] Skipping automated sender: %s", sender_addr)
+                        continue
+                    body = _extract_text_body(msg)
+                    attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)
+
+                    results.append({
+                        "uid": uid,
+                        "sender_addr": sender_addr,
+                        "sender_name": sender_name,
+                        "subject": subject,
+                        "message_id": message_id,
+                        "in_reply_to": in_reply_to,
+                        "body": body,
+                        "attachments": attachments,
+                        "date": msg.get("Date", ""),
+                    })
+            finally:
+                try:
+                    imap.logout()
+                except Exception:
+                    pass
+        except Exception as e:
+            logger.error("[Email] IMAP fetch error: %s", e)
+        return results
+
+    async def _dispatch_message(self, msg_data: Dict[str, Any]) -> None:
+        """Convert a fetched email into a MessageEvent and dispatch it."""
+        sender_addr = msg_data["sender_addr"]
+
+        # Skip self-messages
+        if sender_addr == self._address.lower():
+            return
+
+        # Never reply to automated senders
+        if _is_automated_sender(sender_addr, {}):
+            logger.debug("[Email] Dropping automated sender at dispatch: %s", sender_addr)
+            return
+
+        subject = msg_data["subject"]
+        body = msg_data["body"].strip()
+        attachments = msg_data["attachments"]
+
+        # Build message text: include subject as context
+        text = body
+        if subject and not subject.startswith("Re:"):
+            text = f"[Subject: {subject}]\n\n{body}"
+
+        # Determine message type and media
+        media_urls = []
+        media_types = []
+        msg_type = MessageType.TEXT
+
+        for att in attachments:
+            media_urls.append(att["path"])
+            media_types.append(att["media_type"])
+            if att["type"] == "image":
+                msg_type = MessageType.PHOTO
+
+        # Store thread context for reply threading
+        self._thread_context[sender_addr] = {
+            "subject": subject,
+            "message_id": msg_data["message_id"],
+        }
+
+        source = self.build_source(
+            chat_id=sender_addr,
+            chat_name=msg_data["sender_name"] or sender_addr,
+            chat_type="dm",
+            user_id=sender_addr,
+            user_name=msg_data["sender_name"] or sender_addr,
+        )
+
+        event = MessageEvent(
+            text=text or "(empty email)",
+            message_type=msg_type,
+            source=source,
+            message_id=msg_data["message_id"],
+            media_urls=media_urls,
+            media_types=media_types,
+            reply_to_message_id=msg_data["in_reply_to"] or None,
+        )
+
+        logger.info("[Email] New message from %s: %s", sender_addr, subject)
+        await self.handle_message(event)
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send an email reply to the given address."""
+        try:
+            loop = asyncio.get_running_loop()
+            message_id = await loop.run_in_executor(
+                None, self._send_email, chat_id, content, reply_to
+            )
+            return SendResult(success=True, message_id=message_id)
+        except Exception as e:
+            logger.error("[Email] Send failed to %s: %s", chat_id, e)
+            return SendResult(success=False, error=str(e))
+
+    def _send_email(
+        self,
+        to_addr: str,
+        body: str,
+        reply_to_msg_id: Optional[str] = None,
+    ) -> str:
+        """Send an email via SMTP. Runs in executor thread."""
+        msg = MIMEMultipart()
+        msg["From"] = self._address
+        msg["To"] = to_addr
+
+        # Thread context for reply
+        ctx = self._thread_context.get(to_addr, {})
+        subject = ctx.get("subject", "Hermes Agent")
+        if not subject.startswith("Re:"):
+            subject = f"Re: {subject}"
+        msg["Subject"] = subject
+
+        # Threading headers
+        original_msg_id = reply_to_msg_id or ctx.get("message_id")
+        if original_msg_id:
+            msg["In-Reply-To"] = original_msg_id
+            msg["References"] = original_msg_id
+
+        msg_id = f"<hermes-{uuid.uuid4().hex[:12]}@{self._address.split('@')[1]}>"
+        msg["Message-ID"] = msg_id
+
+        msg.attach(MIMEText(body, "plain", "utf-8"))
+
+        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
+        try:
+            smtp.starttls(context=ssl.create_default_context())
+            smtp.login(self._address, self._password)
+            smtp.send_message(msg)
+        finally:
+            try:
+                smtp.quit()
+            except Exception:
+                smtp.close()
+
+        logger.info("[Email] Sent reply to %s (subject: %s)", to_addr, subject)
+        return msg_id
+
+    async def send_typing(self, chat_id: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Email has no typing indicator — no-op."""
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+    ) -> SendResult:
+        """Send an image URL as part of an email body."""
+        text = caption or ""
+        text += f"\n\nImage: {image_url}"
+        return await self.send(chat_id, text.strip(), reply_to)
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+    ) -> SendResult:
+        """Send a file as an email attachment."""
+        try:
+            loop = asyncio.get_running_loop()
+            message_id = await loop.run_in_executor(
+                None,
+                self._send_email_with_attachment,
+                chat_id,
+                caption or "",
+                file_path,
+                file_name,
+            )
+            return SendResult(success=True, message_id=message_id)
+        except Exception as e:
+            logger.error("[Email] Send document failed: %s", e)
+            return SendResult(success=False, error=str(e))
+
+    def _send_email_with_attachment(
+        self,
+        to_addr: str,
+        body: str,
+        file_path: str,
+        file_name: Optional[str] = None,
+    ) -> str:
+        """Send an email with a file attachment via SMTP."""
+        msg = MIMEMultipart()
+        msg["From"] = self._address
+        msg["To"] = to_addr
+
+        ctx = self._thread_context.get(to_addr, {})
+        subject = ctx.get("subject", "Hermes Agent")
+        if not subject.startswith("Re:"):
+            subject = f"Re: {subject}"
+        msg["Subject"] = subject
+
+        original_msg_id = ctx.get("message_id")
+        if original_msg_id:
+            msg["In-Reply-To"] = original_msg_id
+            msg["References"] = original_msg_id
+
+        msg_id = f"<hermes-{uuid.uuid4().hex[:12]}@{self._address.split('@')[1]}>"
+        msg["Message-ID"] = msg_id
+
+        if body:
+            msg.attach(MIMEText(body, "plain", "utf-8"))
+
+        # Attach file
+        p = Path(file_path)
+        fname = file_name or p.name
+        with open(p, "rb") as f:
+            part = MIMEBase("application", "octet-stream")
+            part.set_payload(f.read())
+            encoders.encode_base64(part)
+            part.add_header("Content-Disposition", f"attachment; filename={fname}")
+            msg.attach(part)
+
+        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
+        try:
+            smtp.starttls(context=ssl.create_default_context())
+            smtp.login(self._address, self._password)
+            smtp.send_message(msg)
+        finally:
+            try:
+                smtp.quit()
+            except Exception:
+                smtp.close()
+
+        return msg_id
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return basic info about the email chat."""
+        ctx = self._thread_context.get(chat_id, {})
+        return {
+            "name": chat_id,
+            "type": "dm",
+            "chat_id": chat_id,
+            "subject": ctx.get("subject", ""),
+        }

mindcli/_vendor/gateway/platforms/flash_asr.py

@@ -0,0 +1,193 @@
+"""
+flash_asr.py — AnyFile2MD 音频转写模块 v2.0
+
+架构修正（2026-04-15）：
+  ❌ 旧方案：base64 multipart → DashScope 同步 API（10MB 限制）
+  ✅ 新方案：OSS 签名 URL → DashScope paraformer-v2 异步任务（无大小限制）
+
+职责（封闭函数，铁律 1）：
+  transcribe_from_oss_url(url) → AsyncIterator[{"text", "begin_ms", "end_ms"}]
+  generate_oss_presign(user_id, ext) → {"upload_url", "oss_key", "read_url"}
+  is_supported_audio(filename) → bool
+
+不调用 LLM，不写 DB，不持久化任何状态。
+"""
+
+import asyncio
+import hmac
+import hashlib
+import base64
+import os
+import time
+import logging
+from datetime import datetime, timezone
+from typing import AsyncIterator
+from urllib.parse import quote
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# ─── 支持格式 ────────────────────────────────────────────────
+SUPPORTED_EXTENSIONS = {
+    ".mp3", ".mp4", ".m4a", ".wav", ".webm",
+    ".ogg", ".aac", ".flac", ".opus", ".amr",
+}
+
+def is_supported_audio(filename: str) -> bool:
+    ext = os.path.splitext(filename)[1].lower()
+    return ext in SUPPORTED_EXTENSIONS
+
+
+# ─── OSS 配置 ─────────────────────────────────────────────────
+def _oss_config() -> dict:
+    return {
+        "access_key_id":     os.getenv("OSS_ACCESS_KEY_ID", ""),
+        "access_key_secret": os.getenv("OSS_ACCESS_KEY_SECRET", ""),
+        "bucket":            os.getenv("OSS_BUCKET", "meetings-dev"),
+        "endpoint":          os.getenv("OSS_ENDPOINT", "oss-cn-guangzhou.aliyuncs.com"),
+        "prefix":            os.getenv("OSS_AUDIO_PREFIX", "mindos-next/audio"),
+    }
+
+
+def generate_oss_presign(user_id: str, ext: str, expire_seconds: int = 3600,
+                         prefix: str | None = None) -> dict:
+    """
+    生成 OSS 预签名 URL（使用 oss2 SDK，V2 验证过的可靠方式）。
+    返回：{ upload_url, oss_key, read_url, content_type }
+      - upload_url ：前端直传用（HTTP PUT，必须带 Content-Type: application/octet-stream）
+      - read_url   ：交给 DashScope paraformer-v2 下载用
+      - content_type：前端 PUT 时必须传此 Content-Type
+
+    Args:
+        prefix: OSS 路径前缀。默认 None 时使用 OSS_AUDIO_PREFIX 环境变量。
+                文档管线传 "mindos-next/docs"，音频管线不传（使用默认值）。
+    """
+    import oss2  # type: ignore
+
+    cfg = _oss_config()
+    if not cfg["access_key_id"] or not cfg["access_key_secret"]:
+        raise RuntimeError("[FlashASR] OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 未配置")
+
+    actual_prefix = prefix or cfg["prefix"]
+    ts = int(time.time())
+    oss_key = f"{actual_prefix}/{user_id}/{ts}_{user_id[:8]}{ext}"
+
+    auth   = oss2.Auth(cfg["access_key_id"], cfg["access_key_secret"])
+    bucket = oss2.Bucket(auth, f"https://{cfg['endpoint']}", cfg["bucket"])
+
+    # Content-Type 必须写入签名，前端 PUT 时须传相同值
+    content_type = "application/octet-stream"
+    upload_url = bucket.sign_url(
+        "PUT", oss_key, expire_seconds,
+        slash_safe=True,
+        headers={"Content-Type": content_type},
+    )
+    read_url = bucket.sign_url("GET", oss_key, expire_seconds, slash_safe=True)
+
+    host = f"{cfg['bucket']}.{cfg['endpoint']}"
+    logger.info("[FlashASR] presign ok oss_key=%s", oss_key)
+
+    return {
+        "upload_url":   upload_url,
+        "read_url":     read_url,
+        "oss_key":      oss_key,
+        "host":         host,
+        "content_type": content_type,
+    }
+
+
+# ─── DashScope paraformer-v2 异步任务 ─────────────────────────
+DASHSCOPE_API_KEY = lambda: os.getenv("DASHSCOPE_API_KEY", "")
+DASHSCOPE_HOST    = "https://dashscope.aliyuncs.com"
+TRANSCRIPTION_URL = f"{DASHSCOPE_HOST}/api/v1/services/audio/asr/transcription"
+
+_HEADERS = lambda: {
+    "Authorization": f"Bearer {DASHSCOPE_API_KEY()}",
+    "Content-Type":  "application/json",
+    "X-DashScope-Async": "enable",
+}
+
+
+async def _submit_task(file_url: str) -> str:
+    """提交 paraformer-v2 异步转写任务，返回 task_id。"""
+    body = {
+        "model": "paraformer-v2",
+        "input": {"file_urls": [file_url]},
+        "parameters": {
+            "language_hints": ["zh", "en"],
+            "timestamp_alignment": True,
+        },
+    }
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.post(TRANSCRIPTION_URL, json=body, headers=_HEADERS())
+        resp.raise_for_status()
+        data = resp.json()
+
+    task_id = data.get("output", {}).get("task_id")
+    if not task_id:
+        raise RuntimeError(f"[FlashASR] 提交任务失败: {data}")
+    logger.info("[FlashASR] 任务已提交 task_id=%s", task_id)
+    return task_id
+
+
+async def _poll_task(task_id: str, poll_interval: float = 5.0, timeout: float = 600.0) -> dict:
+    """轮询任务状态，返回完成后的 output。"""
+    url = f"{DASHSCOPE_HOST}/api/v1/tasks/{task_id}"
+    deadline = time.monotonic() + timeout
+
+    async with httpx.AsyncClient(timeout=30) as client:
+        while time.monotonic() < deadline:
+            resp = await client.get(url, headers=_HEADERS())
+            resp.raise_for_status()
+            data = resp.json()
+            status = data.get("output", {}).get("task_status", "")
+
+            if status == "SUCCEEDED":
+                logger.info("[FlashASR] 任务完成 task_id=%s", task_id)
+                return data["output"]
+            elif status in ("FAILED", "CANCELED"):
+                raise RuntimeError(f"[FlashASR] 任务失败 task_id={task_id} status={status}: {data}")
+
+            logger.debug("[FlashASR] 轮询中 task_id=%s status=%s", task_id, status)
+            await asyncio.sleep(poll_interval)
+
+    raise RuntimeError(f"[FlashASR] 任务超时 task_id={task_id} (>{timeout}s)")
+
+
+async def transcribe_from_oss_url(read_url: str) -> AsyncIterator[dict]:
+    """
+    调用 DashScope paraformer-v2 异步转写。
+    yield {"text": str, "begin_ms": int, "end_ms": int}
+    """
+    if not DASHSCOPE_API_KEY():
+        raise RuntimeError("[FlashASR] DASHSCOPE_API_KEY 未配置")
+
+    task_id = await _submit_task(read_url)
+    output  = await _poll_task(task_id)
+
+    # 下载转写结果 JSON
+    result_url = output.get("results", [{}])[0].get("transcription_url", "")
+    if not result_url:
+        raise RuntimeError(f"[FlashASR] 未找到 transcription_url: {output}")
+
+    async with httpx.AsyncClient(timeout=60) as client:
+        resp = await client.get(result_url)
+        resp.raise_for_status()
+        transcript_data = resp.json()
+
+    # 解析句子列表
+    sentences = transcript_data.get("transcripts", [{}])[0].get("sentences", [])
+    if not sentences:
+        # fallback：整段文本
+        text = transcript_data.get("transcripts", [{}])[0].get("text", "")
+        if text:
+            yield {"text": text, "begin_ms": 0, "end_ms": 0}
+        return
+
+    for s in sentences:
+        yield {
+            "text":     s.get("text", "").strip(),
+            "begin_ms": int(s.get("begin_time", 0)),
+            "end_ms":   int(s.get("end_time", 0)),
+        }

mindcli/_vendor/gateway/platforms/helpers.py

@@ -0,0 +1,261 @@
+"""Shared helper classes for gateway platform adapters.
+
+Extracts common patterns that were duplicated across 5-7 adapters:
+message deduplication, text batch aggregation, markdown stripping,
+and thread participation tracking.
+"""
+
+import asyncio
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, Optional
+
+if TYPE_CHECKING:
+    from gateway.platforms.base import BasePlatformAdapter, MessageEvent
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Message Deduplication ────────────────────────────────────────────────────
+
+
+class MessageDeduplicator:
+    """TTL-based message deduplication cache.
+
+    Replaces the identical ``_seen_messages`` / ``_is_duplicate()`` pattern
+    previously duplicated in discord, slack, dingtalk, wecom, weixin,
+    mattermost, and feishu adapters.
+
+    Usage::
+
+        self._dedup = MessageDeduplicator()
+
+        # In message handler:
+        if self._dedup.is_duplicate(msg_id):
+            return
+    """
+
+    def __init__(self, max_size: int = 2000, ttl_seconds: float = 300):
+        self._seen: Dict[str, float] = {}
+        self._max_size = max_size
+        self._ttl = ttl_seconds
+
+    def is_duplicate(self, msg_id: str) -> bool:
+        """Return True if *msg_id* was already seen within the TTL window."""
+        if not msg_id:
+            return False
+        now = time.time()
+        if msg_id in self._seen:
+            return True
+        self._seen[msg_id] = now
+        if len(self._seen) > self._max_size:
+            cutoff = now - self._ttl
+            self._seen = {k: v for k, v in self._seen.items() if v > cutoff}
+        return False
+
+    def clear(self):
+        """Clear all tracked messages."""
+        self._seen.clear()
+
+
+# ─── Text Batch Aggregation ──────────────────────────────────────────────────
+
+
+class TextBatchAggregator:
+    """Aggregates rapid-fire text events into single messages.
+
+    Replaces the ``_enqueue_text_event`` / ``_flush_text_batch`` pattern
+    previously duplicated in telegram, discord, matrix, wecom, and feishu.
+
+    Usage::
+
+        self._text_batcher = TextBatchAggregator(
+            handler=self._message_handler,
+            batch_delay=0.6,
+            split_threshold=1900,
+        )
+
+        # In message dispatch:
+        if msg_type == MessageType.TEXT and self._text_batcher.is_enabled():
+            self._text_batcher.enqueue(event, session_key)
+            return
+    """
+
+    def __init__(
+        self,
+        handler,
+        *,
+        batch_delay: float = 0.6,
+        split_delay: float = 2.0,
+        split_threshold: int = 4000,
+    ):
+        self._handler = handler
+        self._batch_delay = batch_delay
+        self._split_delay = split_delay
+        self._split_threshold = split_threshold
+        self._pending: Dict[str, "MessageEvent"] = {}
+        self._pending_tasks: Dict[str, asyncio.Task] = {}
+
+    def is_enabled(self) -> bool:
+        """Return True if batching is active (delay > 0)."""
+        return self._batch_delay > 0
+
+    def enqueue(self, event: "MessageEvent", key: str) -> None:
+        """Add *event* to the pending batch for *key*."""
+        chunk_len = len(event.text or "")
+        existing = self._pending.get(key)
+        if not existing:
+            event._last_chunk_len = chunk_len  # type: ignore[attr-defined]
+            self._pending[key] = event
+        else:
+            existing.text = f"{existing.text}\n{event.text}"
+            existing._last_chunk_len = chunk_len  # type: ignore[attr-defined]
+
+        # Cancel prior flush timer, start a new one
+        prior = self._pending_tasks.get(key)
+        if prior and not prior.done():
+            prior.cancel()
+        self._pending_tasks[key] = asyncio.create_task(self._flush(key))
+
+    async def _flush(self, key: str) -> None:
+        """Wait then dispatch the batched event for *key*."""
+        current_task = self._pending_tasks.get(key)
+        pending = self._pending.get(key)
+        last_len = getattr(pending, "_last_chunk_len", 0) if pending else 0
+
+        # Use longer delay when the last chunk looks like a split message
+        delay = self._split_delay if last_len >= self._split_threshold else self._batch_delay
+        await asyncio.sleep(delay)
+
+        event = self._pending.pop(key, None)
+        if event:
+            try:
+                await self._handler(event)
+            except Exception:
+                logger.exception("[TextBatchAggregator] Error dispatching batched event for %s", key)
+
+        if self._pending_tasks.get(key) is current_task:
+            self._pending_tasks.pop(key, None)
+
+    def cancel_all(self) -> None:
+        """Cancel all pending flush tasks."""
+        for task in self._pending_tasks.values():
+            if not task.done():
+                task.cancel()
+        self._pending_tasks.clear()
+        self._pending.clear()
+
+
+# ─── Markdown Stripping ──────────────────────────────────────────────────────
+
+# Pre-compiled regexes for performance
+_RE_BOLD = re.compile(r"\*\*(.+?)\*\*", re.DOTALL)
+_RE_ITALIC_STAR = re.compile(r"\*(.+?)\*", re.DOTALL)
+_RE_BOLD_UNDER = re.compile(r"__(.+?)__", re.DOTALL)
+_RE_ITALIC_UNDER = re.compile(r"_(.+?)_", re.DOTALL)
+_RE_CODE_BLOCK = re.compile(r"```[a-zA-Z0-9_+-]*\n?")
+_RE_INLINE_CODE = re.compile(r"`(.+?)`")
+_RE_HEADING = re.compile(r"^#{1,6}\s+", re.MULTILINE)
+_RE_LINK = re.compile(r"\[([^\]]+)\]\([^\)]+\)")
+_RE_MULTI_NEWLINE = re.compile(r"\n{3,}")
+
+
+def strip_markdown(text: str) -> str:
+    """Strip markdown formatting for plain-text platforms (SMS, iMessage, etc.).
+
+    Replaces the identical ``_strip_markdown()`` functions previously
+    duplicated in sms.py, bluebubbles.py, and feishu.py.
+    """
+    text = _RE_BOLD.sub(r"\1", text)
+    text = _RE_ITALIC_STAR.sub(r"\1", text)
+    text = _RE_BOLD_UNDER.sub(r"\1", text)
+    text = _RE_ITALIC_UNDER.sub(r"\1", text)
+    text = _RE_CODE_BLOCK.sub("", text)
+    text = _RE_INLINE_CODE.sub(r"\1", text)
+    text = _RE_HEADING.sub("", text)
+    text = _RE_LINK.sub(r"\1", text)
+    text = _RE_MULTI_NEWLINE.sub("\n\n", text)
+    return text.strip()
+
+
+# ─── Thread Participation Tracking ───────────────────────────────────────────
+
+
+class ThreadParticipationTracker:
+    """Persistent tracking of threads the bot has participated in.
+
+    Replaces the identical ``_load/_save_participated_threads`` +
+    ``_mark_thread_participated`` pattern previously duplicated in
+    discord.py and matrix.py.
+
+    Usage::
+
+        self._threads = ThreadParticipationTracker("discord")
+
+        # Check membership:
+        if thread_id in self._threads:
+            ...
+
+        # Mark participation:
+        self._threads.mark(thread_id)
+    """
+
+    _MAX_TRACKED = 500
+
+    def __init__(self, platform_name: str, max_tracked: int = 500):
+        self._platform = platform_name
+        self._max_tracked = max_tracked
+        self._threads: set = self._load()
+
+    def _state_path(self) -> Path:
+        from hermes_constants import get_hermes_home
+        return get_hermes_home() / f"{self._platform}_threads.json"
+
+    def _load(self) -> set:
+        path = self._state_path()
+        if path.exists():
+            try:
+                return set(json.loads(path.read_text(encoding="utf-8")))
+            except Exception:
+                pass
+        return set()
+
+    def _save(self) -> None:
+        path = self._state_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        thread_list = list(self._threads)
+        if len(thread_list) > self._max_tracked:
+            thread_list = thread_list[-self._max_tracked:]
+            self._threads = set(thread_list)
+        path.write_text(json.dumps(thread_list), encoding="utf-8")
+
+    def mark(self, thread_id: str) -> None:
+        """Mark *thread_id* as participated and persist."""
+        if thread_id not in self._threads:
+            self._threads.add(thread_id)
+            self._save()
+
+    def __contains__(self, thread_id: str) -> bool:
+        return thread_id in self._threads
+
+    def clear(self) -> None:
+        self._threads.clear()
+
+
+# ─── Phone Number Redaction ──────────────────────────────────────────────────
+
+
+def redact_phone(phone: str) -> str:
+    """Redact a phone number for logging, preserving country code and last 4.
+
+    Replaces the identical ``_redact_phone()`` functions in signal.py,
+    sms.py, and bluebubbles.py.
+    """
+    if not phone:
+        return "<none>"
+    if len(phone) <= 8:
+        return phone[:2] + "****" + phone[-2:] if len(phone) > 4 else "****"
+    return phone[:4] + "****" + phone[-4:]

mindcli/_vendor/gateway/platforms/homeassistant.py

@@ -0,0 +1,449 @@
+"""
+Home Assistant platform adapter.
+
+Connects to the HA WebSocket API for real-time event monitoring.
+State-change events are converted to MessageEvent objects and forwarded
+to the agent for processing.  Outbound messages are delivered as HA
+persistent notifications.
+
+Requires:
+- aiohttp (already in messaging extras)
+- HASS_TOKEN env var (Long-Lived Access Token)
+- HASS_URL env var (default: http://homeassistant.local:8123)
+"""
+
+import asyncio
+import json
+import logging
+import os
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, Optional, Set
+
+try:
+    import aiohttp
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    AIOHTTP_AVAILABLE = False
+    aiohttp = None  # type: ignore[assignment]
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def check_ha_requirements() -> bool:
+    """Check if Home Assistant dependencies are available and configured."""
+    if not AIOHTTP_AVAILABLE:
+        return False
+    if not os.getenv("HASS_TOKEN"):
+        return False
+    return True
+
+
+class HomeAssistantAdapter(BasePlatformAdapter):
+    """
+    Home Assistant WebSocket adapter.
+
+    Subscribes to ``state_changed`` events and forwards them as
+    MessageEvent objects.  Supports domain/entity filtering and
+    per-entity cooldowns to avoid event floods.
+    """
+
+    MAX_MESSAGE_LENGTH = 4096
+
+    # Reconnection backoff schedule (seconds)
+    _BACKOFF_STEPS = [5, 10, 30, 60]
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.HOMEASSISTANT)
+
+        # Connection state
+        self._session: Optional["aiohttp.ClientSession"] = None
+        self._ws: Optional["aiohttp.ClientWebSocketResponse"] = None
+        self._rest_session: Optional["aiohttp.ClientSession"] = None
+        self._listen_task: Optional[asyncio.Task] = None
+        self._msg_id: int = 0
+
+        # Configuration from extra
+        extra = config.extra or {}
+        token = config.token or os.getenv("HASS_TOKEN", "")
+        url = extra.get("url") or os.getenv("HASS_URL", "http://homeassistant.local:8123")
+        self._hass_url: str = url.rstrip("/")
+        self._hass_token: str = token
+
+        # Event filtering
+        self._watch_domains: Set[str] = set(extra.get("watch_domains", []))
+        self._watch_entities: Set[str] = set(extra.get("watch_entities", []))
+        self._ignore_entities: Set[str] = set(extra.get("ignore_entities", []))
+        self._watch_all: bool = bool(extra.get("watch_all", False))
+        self._cooldown_seconds: int = int(extra.get("cooldown_seconds", 30))
+
+        # Cooldown tracking: entity_id -> last_event_timestamp
+        self._last_event_time: Dict[str, float] = {}
+
+    def _next_id(self) -> int:
+        """Return the next WebSocket message ID."""
+        self._msg_id += 1
+        return self._msg_id
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to HA WebSocket API and subscribe to events."""
+        if not AIOHTTP_AVAILABLE:
+            logger.warning("[%s] aiohttp not installed. Run: pip install aiohttp", self.name)
+            return False
+
+        if not self._hass_token:
+            logger.warning("[%s] No HASS_TOKEN configured", self.name)
+            return False
+
+        try:
+            success = await self._ws_connect()
+            if not success:
+                return False
+
+            # Dedicated REST session for send() calls
+            self._rest_session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=30)
+            )
+
+            # Warn if no event filters are configured
+            if not self._watch_domains and not self._watch_entities and not self._watch_all:
+                logger.warning(
+                    "[%s] No watch_domains, watch_entities, or watch_all configured. "
+                    "All state_changed events will be dropped. Configure filters in "
+                    "your HA platform config to receive events.",
+                    self.name,
+                )
+
+            # Start background listener
+            self._listen_task = asyncio.create_task(self._listen_loop())
+            self._running = True
+            logger.info("[%s] Connected to %s", self.name, self._hass_url)
+            return True
+
+        except Exception as e:
+            logger.error("[%s] Failed to connect: %s", self.name, e)
+            return False
+
+    async def _ws_connect(self) -> bool:
+        """Establish WebSocket connection and authenticate."""
+        ws_url = self._hass_url.replace("http://", "ws://").replace("https://", "wss://")
+        ws_url = f"{ws_url}/api/websocket"
+
+        self._session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30)
+        )
+        self._ws = await self._session.ws_connect(ws_url, heartbeat=30, timeout=30)
+
+        # Step 1: Receive auth_required
+        msg = await self._ws.receive_json()
+        if msg.get("type") != "auth_required":
+            logger.error("Expected auth_required, got: %s", msg.get("type"))
+            await self._cleanup_ws()
+            return False
+
+        # Step 2: Send auth
+        await self._ws.send_json({
+            "type": "auth",
+            "access_token": self._hass_token,
+        })
+
+        # Step 3: Wait for auth_ok
+        msg = await self._ws.receive_json()
+        if msg.get("type") != "auth_ok":
+            logger.error("Auth failed: %s", msg)
+            await self._cleanup_ws()
+            return False
+
+        # Step 4: Subscribe to state_changed events
+        sub_id = self._next_id()
+        await self._ws.send_json({
+            "id": sub_id,
+            "type": "subscribe_events",
+            "event_type": "state_changed",
+        })
+
+        # Verify subscription acknowledgement
+        msg = await self._ws.receive_json()
+        if not msg.get("success"):
+            logger.error("Failed to subscribe to events: %s", msg)
+            await self._cleanup_ws()
+            return False
+
+        return True
+
+    async def _cleanup_ws(self) -> None:
+        """Close WebSocket and session."""
+        if self._ws and not self._ws.closed:
+            await self._ws.close()
+        self._ws = None
+        if self._session and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def disconnect(self) -> None:
+        """Disconnect from Home Assistant."""
+        self._running = False
+        if self._listen_task:
+            self._listen_task.cancel()
+            try:
+                await self._listen_task
+            except asyncio.CancelledError:
+                pass
+            self._listen_task = None
+
+        await self._cleanup_ws()
+        if self._rest_session and not self._rest_session.closed:
+            await self._rest_session.close()
+        self._rest_session = None
+        logger.info("[%s] Disconnected", self.name)
+
+    # ------------------------------------------------------------------
+    # Event listener
+    # ------------------------------------------------------------------
+
+    async def _listen_loop(self) -> None:
+        """Main event loop with automatic reconnection."""
+        backoff_idx = 0
+
+        while self._running:
+            try:
+                await self._read_events()
+            except asyncio.CancelledError:
+                return
+            except Exception as e:
+                logger.warning("[%s] WebSocket error: %s", self.name, e)
+
+            if not self._running:
+                return
+
+            # Reconnect with backoff
+            delay = self._BACKOFF_STEPS[min(backoff_idx, len(self._BACKOFF_STEPS) - 1)]
+            logger.info("[%s] Reconnecting in %ds...", self.name, delay)
+            await asyncio.sleep(delay)
+            backoff_idx += 1
+
+            try:
+                await self._cleanup_ws()
+                success = await self._ws_connect()
+                if success:
+                    backoff_idx = 0  # Reset on successful reconnect
+                    logger.info("[%s] Reconnected", self.name)
+            except Exception as e:
+                logger.warning("[%s] Reconnection failed: %s", self.name, e)
+
+    async def _read_events(self) -> None:
+        """Read events from WebSocket until disconnected."""
+        if self._ws is None or self._ws.closed:
+            return
+        async for ws_msg in self._ws:
+            if ws_msg.type == aiohttp.WSMsgType.TEXT:
+                try:
+                    data = json.loads(ws_msg.data)
+                    if data.get("type") == "event":
+                        await self._handle_ha_event(data.get("event", {}))
+                except json.JSONDecodeError:
+                    logger.debug("Invalid JSON from HA WS: %s", ws_msg.data[:200])
+            elif ws_msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.ERROR):
+                break
+
+    async def _handle_ha_event(self, event: Dict[str, Any]) -> None:
+        """Process a state_changed event from Home Assistant."""
+        event_data = event.get("data", {})
+        entity_id: str = event_data.get("entity_id", "")
+
+        if not entity_id:
+            return
+
+        # Apply ignore filter
+        if entity_id in self._ignore_entities:
+            return
+
+        # Apply domain/entity watch filters (closed by default — require
+        # explicit watch_domains, watch_entities, or watch_all to forward)
+        domain = entity_id.split(".")[0] if "." in entity_id else ""
+        if self._watch_domains or self._watch_entities:
+            domain_match = domain in self._watch_domains if self._watch_domains else False
+            entity_match = entity_id in self._watch_entities if self._watch_entities else False
+            if not domain_match and not entity_match:
+                return
+        elif not self._watch_all:
+            # No filters configured and watch_all is off — drop the event
+            return
+
+        # Apply cooldown
+        now = time.time()
+        last = self._last_event_time.get(entity_id, 0)
+        if (now - last) < self._cooldown_seconds:
+            return
+        self._last_event_time[entity_id] = now
+
+        # Build human-readable message
+        old_state = event_data.get("old_state", {})
+        new_state = event_data.get("new_state", {})
+        message = self._format_state_change(entity_id, old_state, new_state)
+
+        if not message:
+            return
+
+        # Build MessageEvent and forward to handler
+        source = self.build_source(
+            chat_id="ha_events",
+            chat_name="Home Assistant Events",
+            chat_type="channel",
+            user_id="homeassistant",
+            user_name="Home Assistant",
+        )
+
+        msg_event = MessageEvent(
+            text=message,
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=f"ha_{entity_id}_{int(now)}",
+            timestamp=datetime.now(),
+        )
+
+        await self.handle_message(msg_event)
+
+    @staticmethod
+    def _format_state_change(
+        entity_id: str,
+        old_state: Dict[str, Any],
+        new_state: Dict[str, Any],
+    ) -> Optional[str]:
+        """Convert a state_changed event into a human-readable description."""
+        if not new_state:
+            return None
+
+        old_val = old_state.get("state", "unknown") if old_state else "unknown"
+        new_val = new_state.get("state", "unknown")
+
+        # Skip if state didn't actually change
+        if old_val == new_val:
+            return None
+
+        friendly_name = new_state.get("attributes", {}).get("friendly_name", entity_id)
+        domain = entity_id.split(".")[0] if "." in entity_id else ""
+
+        # Domain-specific formatting
+        if domain == "climate":
+            attrs = new_state.get("attributes", {})
+            temp = attrs.get("current_temperature", "?")
+            target = attrs.get("temperature", "?")
+            return (
+                f"[Home Assistant] {friendly_name}: HVAC mode changed from "
+                f"'{old_val}' to '{new_val}' (current: {temp}, target: {target})"
+            )
+
+        if domain == "sensor":
+            unit = new_state.get("attributes", {}).get("unit_of_measurement", "")
+            return (
+                f"[Home Assistant] {friendly_name}: changed from "
+                f"{old_val}{unit} to {new_val}{unit}"
+            )
+
+        if domain == "binary_sensor":
+            return (
+                f"[Home Assistant] {friendly_name}: "
+                f"{'triggered' if new_val == 'on' else 'cleared'} "
+                f"(was {'triggered' if old_val == 'on' else 'cleared'})"
+            )
+
+        if domain in ("light", "switch", "fan"):
+            return (
+                f"[Home Assistant] {friendly_name}: turned "
+                f"{'on' if new_val == 'on' else 'off'}"
+            )
+
+        if domain == "alarm_control_panel":
+            return (
+                f"[Home Assistant] {friendly_name}: alarm state changed from "
+                f"'{old_val}' to '{new_val}'"
+            )
+
+        # Generic fallback
+        return (
+            f"[Home Assistant] {friendly_name} ({entity_id}): "
+            f"changed from '{old_val}' to '{new_val}'"
+        )
+
+    # ------------------------------------------------------------------
+    # Outbound messaging
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a notification via HA REST API (persistent_notification.create).
+
+        Uses the REST API instead of WebSocket to avoid a race condition
+        with the event listener loop that reads from the same WS connection.
+        """
+        url = f"{self._hass_url}/api/services/persistent_notification/create"
+        headers = {
+            "Authorization": f"Bearer {self._hass_token}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "title": "Hermes Agent",
+            "message": content[:self.MAX_MESSAGE_LENGTH],
+        }
+
+        try:
+            if self._rest_session:
+                async with self._rest_session.post(
+                    url,
+                    headers=headers,
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=10),
+                ) as resp:
+                    if resp.status < 300:
+                        return SendResult(success=True, message_id=uuid.uuid4().hex[:12])
+                    else:
+                        body = await resp.text()
+                        return SendResult(success=False, error=f"HTTP {resp.status}: {body}")
+            else:
+                async with aiohttp.ClientSession() as session:
+                    async with session.post(
+                        url,
+                        headers=headers,
+                        json=payload,
+                        timeout=aiohttp.ClientTimeout(total=10),
+                    ) as resp:
+                        if resp.status < 300:
+                            return SendResult(success=True, message_id=uuid.uuid4().hex[:12])
+                        else:
+                            body = await resp.text()
+                            return SendResult(success=False, error=f"HTTP {resp.status}: {body}")
+
+        except asyncio.TimeoutError:
+            return SendResult(success=False, error="Timeout sending notification to HA")
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """No typing indicator for Home Assistant."""
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return basic info about the HA event channel."""
+        return {
+            "name": "Home Assistant Events",
+            "type": "channel",
+            "url": self._hass_url,
+        }

mindcli/_vendor/gateway/platforms/mattermost.py

@@ -0,0 +1,733 @@
+"""Mattermost gateway adapter.
+
+Connects to a self-hosted (or cloud) Mattermost instance via its REST API
+(v4) and WebSocket for real-time events.  No external Mattermost library
+required — uses aiohttp which is already a Hermes dependency.
+
+Environment variables:
+    MATTERMOST_URL              Server URL (e.g. https://mm.example.com)
+    MATTERMOST_TOKEN            Bot token or personal-access token
+    MATTERMOST_ALLOWED_USERS    Comma-separated user IDs
+    MATTERMOST_HOME_CHANNEL     Channel ID for cron/notification delivery
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.helpers import MessageDeduplicator
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+# Mattermost post size limit (server default is 16383, but 4000 is the
+# practical limit for readable messages — matching OpenClaw's choice).
+MAX_POST_LENGTH = 4000
+
+# Channel type codes returned by the Mattermost API.
+_CHANNEL_TYPE_MAP = {
+    "D": "dm",
+    "G": "group",
+    "P": "group",   # private channel → treat as group
+    "O": "channel",
+}
+
+# Reconnect parameters (exponential backoff).
+_RECONNECT_BASE_DELAY = 2.0
+_RECONNECT_MAX_DELAY = 60.0
+_RECONNECT_JITTER = 0.2
+
+
+def check_mattermost_requirements() -> bool:
+    """Return True if the Mattermost adapter can be used."""
+    token = os.getenv("MATTERMOST_TOKEN", "")
+    url = os.getenv("MATTERMOST_URL", "")
+    if not token:
+        logger.debug("Mattermost: MATTERMOST_TOKEN not set")
+        return False
+    if not url:
+        logger.warning("Mattermost: MATTERMOST_URL not set")
+        return False
+    try:
+        import aiohttp  # noqa: F401
+        return True
+    except ImportError:
+        logger.warning("Mattermost: aiohttp not installed")
+        return False
+
+
+class MattermostAdapter(BasePlatformAdapter):
+    """Gateway adapter for Mattermost (self-hosted or cloud)."""
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.MATTERMOST)
+
+        self._base_url: str = (
+            config.extra.get("url", "")
+            or os.getenv("MATTERMOST_URL", "")
+        ).rstrip("/")
+        self._token: str = config.token or os.getenv("MATTERMOST_TOKEN", "")
+
+        self._bot_user_id: str = ""
+        self._bot_username: str = ""
+
+        # aiohttp session + websocket handle
+        self._session: Any = None  # aiohttp.ClientSession
+        self._ws: Any = None       # aiohttp.ClientWebSocketResponse
+        self._ws_task: Optional[asyncio.Task] = None
+        self._reconnect_task: Optional[asyncio.Task] = None
+        self._closing = False
+
+        # Reply mode: "thread" to nest replies, "off" for flat messages.
+        self._reply_mode: str = (
+            config.extra.get("reply_mode", "")
+            or os.getenv("MATTERMOST_REPLY_MODE", "off")
+        ).lower()
+
+        # Dedup cache (prevent reprocessing)
+        self._dedup = MessageDeduplicator()
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+        }
+
+    async def _api_get(self, path: str) -> Dict[str, Any]:
+        """GET /api/v4/{path}."""
+        import aiohttp
+        url = f"{self._base_url}/api/v4/{path.lstrip('/')}"
+        try:
+            async with self._session.get(url, headers=self._headers(), timeout=aiohttp.ClientTimeout(total=30)) as resp:
+                if resp.status >= 400:
+                    body = await resp.text()
+                    logger.error("MM API GET %s → %s: %s", path, resp.status, body[:200])
+                    return {}
+                return await resp.json()
+        except aiohttp.ClientError as exc:
+            logger.error("MM API GET %s network error: %s", path, exc)
+            return {}
+
+    async def _api_post(
+        self, path: str, payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """POST /api/v4/{path} with JSON body."""
+        import aiohttp
+        url = f"{self._base_url}/api/v4/{path.lstrip('/')}"
+        try:
+            async with self._session.post(
+                url, headers=self._headers(), json=payload,
+                timeout=aiohttp.ClientTimeout(total=30)
+            ) as resp:
+                if resp.status >= 400:
+                    body = await resp.text()
+                    logger.error("MM API POST %s → %s: %s", path, resp.status, body[:200])
+                    return {}
+                return await resp.json()
+        except aiohttp.ClientError as exc:
+            logger.error("MM API POST %s network error: %s", path, exc)
+            return {}
+
+    async def _api_put(
+        self, path: str, payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """PUT /api/v4/{path} with JSON body."""
+        import aiohttp
+        url = f"{self._base_url}/api/v4/{path.lstrip('/')}"
+        try:
+            async with self._session.put(
+                url, headers=self._headers(), json=payload
+            ) as resp:
+                if resp.status >= 400:
+                    body = await resp.text()
+                    logger.error("MM API PUT %s → %s: %s", path, resp.status, body[:200])
+                    return {}
+                return await resp.json()
+        except aiohttp.ClientError as exc:
+            logger.error("MM API PUT %s network error: %s", path, exc)
+            return {}
+
+    async def _upload_file(
+        self, channel_id: str, file_data: bytes, filename: str, content_type: str = "application/octet-stream"
+    ) -> Optional[str]:
+        """Upload a file and return its file ID, or None on failure."""
+        import aiohttp
+
+        url = f"{self._base_url}/api/v4/files"
+        form = aiohttp.FormData()
+        form.add_field("channel_id", channel_id)
+        form.add_field(
+            "files",
+            file_data,
+            filename=filename,
+            content_type=content_type,
+        )
+        headers = {"Authorization": f"Bearer {self._token}"}
+        async with self._session.post(url, headers=headers, data=form, timeout=aiohttp.ClientTimeout(total=60)) as resp:
+            if resp.status >= 400:
+                body = await resp.text()
+                logger.error("MM file upload → %s: %s", resp.status, body[:200])
+                return None
+            data = await resp.json()
+            infos = data.get("file_infos", [])
+            return infos[0]["id"] if infos else None
+
+    # ------------------------------------------------------------------
+    # Required overrides
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to Mattermost and start the WebSocket listener."""
+        import aiohttp
+
+        if not self._base_url or not self._token:
+            logger.error("Mattermost: URL or token not configured")
+            return False
+
+        self._session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30)
+        )
+        self._closing = False
+
+        # Verify credentials and fetch bot identity.
+        me = await self._api_get("users/me")
+        if not me or "id" not in me:
+            logger.error("Mattermost: failed to authenticate — check MATTERMOST_TOKEN and MATTERMOST_URL")
+            await self._session.close()
+            return False
+
+        self._bot_user_id = me["id"]
+        self._bot_username = me.get("username", "")
+        logger.info(
+            "Mattermost: authenticated as @%s (%s) on %s",
+            self._bot_username,
+            self._bot_user_id,
+            self._base_url,
+        )
+
+        # Start WebSocket in background.
+        self._ws_task = asyncio.create_task(self._ws_loop())
+        self._mark_connected()
+        return True
+
+    async def disconnect(self) -> None:
+        """Disconnect from Mattermost."""
+        self._closing = True
+
+        if self._ws_task and not self._ws_task.done():
+            self._ws_task.cancel()
+            try:
+                await self._ws_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+        if self._reconnect_task and not self._reconnect_task.done():
+            self._reconnect_task.cancel()
+
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+        logger.info("Mattermost: disconnected")
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a message (or multiple chunks) to a channel."""
+        if not content:
+            return SendResult(success=True)
+
+        formatted = self.format_message(content)
+        chunks = self.truncate_message(formatted, MAX_POST_LENGTH)
+
+        last_id = None
+        for chunk in chunks:
+            payload: Dict[str, Any] = {
+                "channel_id": chat_id,
+                "message": chunk,
+            }
+            # Thread support: reply_to is the root post ID.
+            if reply_to and self._reply_mode == "thread":
+                payload["root_id"] = reply_to
+
+            data = await self._api_post("posts", payload)
+            if not data or "id" not in data:
+                return SendResult(success=False, error="Failed to create post")
+            last_id = data["id"]
+
+        return SendResult(success=True, message_id=last_id)
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Return channel name and type."""
+        data = await self._api_get(f"channels/{chat_id}")
+        if not data:
+            return {"name": chat_id, "type": "channel"}
+
+        ch_type = _CHANNEL_TYPE_MAP.get(data.get("type", "O"), "channel")
+        display_name = data.get("display_name") or data.get("name") or chat_id
+        return {"name": display_name, "type": ch_type}
+
+    # ------------------------------------------------------------------
+    # Optional overrides
+    # ------------------------------------------------------------------
+
+    async def send_typing(
+        self, chat_id: str, metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Send a typing indicator."""
+        await self._api_post(
+            f"users/{self._bot_user_id}/typing",
+            {"channel_id": chat_id},
+        )
+
+    async def edit_message(
+        self, chat_id: str, message_id: str, content: str
+    ) -> SendResult:
+        """Edit an existing post."""
+        formatted = self.format_message(content)
+        data = await self._api_put(
+            f"posts/{message_id}/patch",
+            {"message": formatted},
+        )
+        if not data or "id" not in data:
+            return SendResult(success=False, error="Failed to edit post")
+        return SendResult(success=True, message_id=data["id"])
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Download an image and upload it as a file attachment."""
+        return await self._send_url_as_file(
+            chat_id, image_url, caption, reply_to, "image"
+        )
+
+    async def send_image_file(
+        self,
+        chat_id: str,
+        image_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Upload a local image file."""
+        return await self._send_local_file(
+            chat_id, image_path, caption, reply_to
+        )
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Upload a local file as a document."""
+        return await self._send_local_file(
+            chat_id, file_path, caption, reply_to, file_name
+        )
+
+    async def send_voice(
+        self,
+        chat_id: str,
+        audio_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Upload an audio file."""
+        return await self._send_local_file(
+            chat_id, audio_path, caption, reply_to
+        )
+
+    async def send_video(
+        self,
+        chat_id: str,
+        video_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Upload a video file."""
+        return await self._send_local_file(
+            chat_id, video_path, caption, reply_to
+        )
+
+    def format_message(self, content: str) -> str:
+        """Mattermost uses standard Markdown — mostly pass through.
+
+        Strip image markdown into plain links (files are uploaded separately).
+        """
+        # Convert ![alt](url) to just the URL — Mattermost renders
+        # image URLs as inline previews automatically.
+        content = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", r"\2", content)
+        return content
+
+    # ------------------------------------------------------------------
+    # File helpers
+    # ------------------------------------------------------------------
+
+    async def _send_url_as_file(
+        self,
+        chat_id: str,
+        url: str,
+        caption: Optional[str],
+        reply_to: Optional[str],
+        kind: str = "file",
+    ) -> SendResult:
+        """Download a URL and upload it as a file attachment."""
+        from tools.url_safety import is_safe_url
+        if not is_safe_url(url):
+            logger.warning("Mattermost: blocked unsafe URL (SSRF protection)")
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+
+        import asyncio
+        import aiohttp
+
+        last_exc = None
+        file_data = None
+        ct = "application/octet-stream"
+        fname = url.rsplit("/", 1)[-1].split("?")[0] or f"{kind}.png"
+
+        for attempt in range(3):
+            try:
+                async with self._session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as resp:
+                    if resp.status >= 500 or resp.status == 429:
+                        if attempt < 2:
+                            logger.debug("Mattermost download retry %d/2 for %s (status %d)",
+                                         attempt + 1, url[:80], resp.status)
+                            await asyncio.sleep(1.5 * (attempt + 1))
+                            continue
+                    if resp.status >= 400:
+                        return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+                    file_data = await resp.read()
+                    ct = resp.content_type or "application/octet-stream"
+                    break
+            except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+                if attempt < 2:
+                    await asyncio.sleep(1.5 * (attempt + 1))
+                    continue
+                logger.warning("Mattermost: failed to download %s after %d attempts: %s", url, attempt + 1, exc)
+                return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+
+        if file_data is None:
+            logger.warning("Mattermost: download returned no data for %s", url)
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+
+        file_id = await self._upload_file(chat_id, file_data, fname, ct)
+        if not file_id:
+            return await self.send(chat_id, f"{caption or ''}\n{url}".strip(), reply_to)
+
+        payload: Dict[str, Any] = {
+            "channel_id": chat_id,
+            "message": caption or "",
+            "file_ids": [file_id],
+        }
+        if reply_to and self._reply_mode == "thread":
+            payload["root_id"] = reply_to
+
+        data = await self._api_post("posts", payload)
+        if not data or "id" not in data:
+            return SendResult(success=False, error="Failed to post with file")
+        return SendResult(success=True, message_id=data["id"])
+
+    async def _send_local_file(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str],
+        reply_to: Optional[str],
+        file_name: Optional[str] = None,
+    ) -> SendResult:
+        """Upload a local file and attach it to a post."""
+        import mimetypes
+
+        p = Path(file_path)
+        if not p.exists():
+            return await self.send(
+                chat_id, f"{caption or ''}\n(file not found: {file_path})", reply_to
+            )
+
+        fname = file_name or p.name
+        ct = mimetypes.guess_type(fname)[0] or "application/octet-stream"
+        file_data = p.read_bytes()
+
+        file_id = await self._upload_file(chat_id, file_data, fname, ct)
+        if not file_id:
+            return SendResult(success=False, error="File upload failed")
+
+        payload: Dict[str, Any] = {
+            "channel_id": chat_id,
+            "message": caption or "",
+            "file_ids": [file_id],
+        }
+        if reply_to and self._reply_mode == "thread":
+            payload["root_id"] = reply_to
+
+        data = await self._api_post("posts", payload)
+        if not data or "id" not in data:
+            return SendResult(success=False, error="Failed to post with file")
+        return SendResult(success=True, message_id=data["id"])
+
+    # ------------------------------------------------------------------
+    # WebSocket
+    # ------------------------------------------------------------------
+
+    async def _ws_loop(self) -> None:
+        """Connect to the WebSocket and listen for events, reconnecting on failure."""
+        delay = _RECONNECT_BASE_DELAY
+        while not self._closing:
+            try:
+                await self._ws_connect_and_listen()
+                # Clean disconnect — reset delay.
+                delay = _RECONNECT_BASE_DELAY
+            except asyncio.CancelledError:
+                return
+            except Exception as exc:
+                if self._closing:
+                    return
+                # Detect permanent auth/permission failures that will never
+                # succeed on retry — stop reconnecting instead of looping forever.
+                import aiohttp
+                err_str = str(exc).lower()
+                if isinstance(exc, aiohttp.WSServerHandshakeError) and exc.status in (401, 403):
+                    logger.error("Mattermost WS auth failed (HTTP %d) — stopping reconnect", exc.status)
+                    return
+                if "401" in err_str or "403" in err_str or "unauthorized" in err_str:
+                    logger.error("Mattermost WS permanent error: %s — stopping reconnect", exc)
+                    return
+                logger.warning("Mattermost WS error: %s — reconnecting in %.0fs", exc, delay)
+
+            if self._closing:
+                return
+
+            # Exponential backoff with jitter.
+            import random
+            jitter = delay * _RECONNECT_JITTER * random.random()
+            await asyncio.sleep(delay + jitter)
+            delay = min(delay * 2, _RECONNECT_MAX_DELAY)
+
+    async def _ws_connect_and_listen(self) -> None:
+        """Single WebSocket session: connect, authenticate, process events."""
+        # Build WS URL: https:// → wss://, http:// → ws://
+        ws_url = re.sub(r"^http", "ws", self._base_url) + "/api/v4/websocket"
+        logger.info("Mattermost: connecting to %s", ws_url)
+
+        self._ws = await self._session.ws_connect(ws_url, heartbeat=30.0)
+
+        # Authenticate via the WebSocket.
+        auth_msg = {
+            "seq": 1,
+            "action": "authentication_challenge",
+            "data": {"token": self._token},
+        }
+        await self._ws.send_json(auth_msg)
+        logger.info("Mattermost: WebSocket connected and authenticated")
+
+        async for raw_msg in self._ws:
+            if self._closing:
+                return
+
+            if raw_msg.type in (
+                raw_msg.type.TEXT,
+                raw_msg.type.BINARY,
+            ):
+                try:
+                    event = json.loads(raw_msg.data)
+                except (json.JSONDecodeError, TypeError):
+                    continue
+                await self._handle_ws_event(event)
+            elif raw_msg.type in (
+                raw_msg.type.ERROR,
+                raw_msg.type.CLOSE,
+                raw_msg.type.CLOSING,
+                raw_msg.type.CLOSED,
+            ):
+                logger.info("Mattermost: WebSocket closed (%s)", raw_msg.type)
+                break
+
+    async def _handle_ws_event(self, event: Dict[str, Any]) -> None:
+        """Process a single WebSocket event."""
+        event_type = event.get("event")
+        if event_type != "posted":
+            return
+
+        data = event.get("data", {})
+        raw_post_str = data.get("post")
+        if not raw_post_str:
+            return
+
+        try:
+            post = json.loads(raw_post_str)
+        except (json.JSONDecodeError, TypeError):
+            return
+
+        # Ignore own messages.
+        if post.get("user_id") == self._bot_user_id:
+            return
+
+        # Ignore system posts.
+        if post.get("type"):
+            return
+
+        post_id = post.get("id", "")
+
+        # Dedup.
+        if self._dedup.is_duplicate(post_id):
+            return
+
+        # Build message event.
+        channel_id = post.get("channel_id", "")
+        channel_type_raw = data.get("channel_type", "O")
+        chat_type = _CHANNEL_TYPE_MAP.get(channel_type_raw, "channel")
+
+        # For DMs, user_id is sufficient.  For channels, check for @mention.
+        message_text = post.get("message", "")
+
+        # Mention-gating for non-DM channels.
+        # Config (env vars):
+        #   MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
+        #   MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
+        if channel_type_raw != "D":
+            require_mention = os.getenv(
+                "MATTERMOST_REQUIRE_MENTION", "true"
+            ).lower() not in ("false", "0", "no")
+
+            free_channels_raw = os.getenv("MATTERMOST_FREE_RESPONSE_CHANNELS", "")
+            free_channels = {ch.strip() for ch in free_channels_raw.split(",") if ch.strip()}
+            is_free_channel = channel_id in free_channels
+
+            mention_patterns = [
+                f"@{self._bot_username}",
+                f"@{self._bot_user_id}",
+            ]
+            has_mention = any(
+                pattern.lower() in message_text.lower()
+                for pattern in mention_patterns
+            )
+
+            if require_mention and not is_free_channel and not has_mention:
+                logger.debug(
+                    "Mattermost: skipping non-DM message without @mention (channel=%s)",
+                    channel_id,
+                )
+                return
+
+            # Strip @mention from the message text so the agent sees clean input.
+            if has_mention:
+                for pattern in mention_patterns:
+                    message_text = re.sub(
+                        re.escape(pattern), "", message_text, flags=re.IGNORECASE
+                    ).strip()
+
+        # Resolve sender info.
+        sender_id = post.get("user_id", "")
+        sender_name = data.get("sender_name", "").lstrip("@") or sender_id
+
+        # Thread support: if the post is in a thread, use root_id.
+        thread_id = post.get("root_id") or None
+
+        # Determine message type.
+        file_ids = post.get("file_ids") or []
+        msg_type = MessageType.TEXT
+        if message_text.startswith("/"):
+            msg_type = MessageType.COMMAND
+
+        # Download file attachments immediately (URLs require auth headers
+        # that downstream tools won't have).
+        media_urls: List[str] = []
+        media_types: List[str] = []
+        for fid in file_ids:
+            try:
+                file_info = await self._api_get(f"files/{fid}/info")
+                fname = file_info.get("name", f"file_{fid}")
+                ext = Path(fname).suffix or ""
+                mime = file_info.get("mime_type", "application/octet-stream")
+
+                import aiohttp
+                dl_url = f"{self._base_url}/api/v4/files/{fid}"
+                async with self._session.get(
+                    dl_url,
+                    headers={"Authorization": f"Bearer {self._token}"},
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    if resp.status < 400:
+                        file_data = await resp.read()
+                        from gateway.platforms.base import cache_image_from_bytes, cache_document_from_bytes
+                        if mime.startswith("image/"):
+                            local_path = cache_image_from_bytes(file_data, ext or ".png")
+                            media_urls.append(local_path)
+                            media_types.append(mime)
+                        elif mime.startswith("audio/"):
+                            from gateway.platforms.base import cache_audio_from_bytes
+                            local_path = cache_audio_from_bytes(file_data, ext or ".ogg")
+                            media_urls.append(local_path)
+                            media_types.append(mime)
+                        else:
+                            local_path = cache_document_from_bytes(file_data, fname)
+                            media_urls.append(local_path)
+                            media_types.append(mime)
+                    else:
+                        logger.warning("Mattermost: failed to download file %s: HTTP %s", fid, resp.status)
+            except Exception as exc:
+                logger.warning("Mattermost: error downloading file %s: %s", fid, exc)
+
+        # Set message type based on downloaded media types.
+        if media_types and msg_type == MessageType.TEXT:
+            if any(m.startswith("image/") for m in media_types):
+                msg_type = MessageType.PHOTO
+            elif any(m.startswith("audio/") for m in media_types):
+                msg_type = MessageType.VOICE
+            elif media_types:
+                msg_type = MessageType.DOCUMENT
+
+        source = self.build_source(
+            chat_id=channel_id,
+            chat_type=chat_type,
+            user_id=sender_id,
+            user_name=sender_name,
+            thread_id=thread_id,
+        )
+
+        msg_event = MessageEvent(
+            text=message_text,
+            message_type=msg_type,
+            source=source,
+            raw_message=post,
+            message_id=post_id,
+            media_urls=media_urls if media_urls else None,
+            media_types=media_types if media_types else None,
+        )
+
+        await self.handle_message(msg_event)
+
+

mindcli/_vendor/gateway/platforms/md_converter.py

@@ -0,0 +1,113 @@
+"""
+MindOS NEXT — mdConverter：transcript 片段 → Markdown 文件追加
+
+封闭函数（铁律 1）：
+  输入：transcript 文本片段（str）+ 可选毫秒偏移（int）
+  输出：追加到 wiki/meetings/*.md
+  副作用：仅磁盘文件写入；不调用 LLM，不写 DB。
+
+MD-First（铁律 6）：
+  音频/文件的唯一持久化形式就是这个 .md 文件。
+  无 DB 记录，无 UUID，文件名即身份。
+"""
+
+import os
+import time
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+_MIME_TO_EXT = {
+    "audio/mpeg": "mp3", "audio/mp4": "m4a", "audio/mp3": "mp3",
+    "audio/wav": "wav", "audio/webm": "webm", "audio/ogg": "ogg",
+    "audio/aac": "aac", "audio/flac": "flac",
+}
+
+_SUPPORTED_EXTS = {".mp3", ".mp4", ".m4a", ".wav", ".webm", ".ogg", ".aac", ".flac"}
+
+
+def is_supported_audio(filename: str) -> bool:
+    return Path(filename).suffix.lower() in _SUPPORTED_EXTS
+
+
+class MdConverter:
+    """transcript 片段追加为 Markdown 文件（L0 原文层）。"""
+
+    def __init__(self, wiki_dir: str):
+        self.meetings_dir = Path(wiki_dir) / "raw"
+        self.meetings_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def new_file(
+        self,
+        title: str = "未命名",
+        source_filename: str = "",
+        duration_hint: str = "",
+    ) -> Path:
+        """
+        创建新 MD 文件，写入 YAML-style header，返回文件路径。
+        文件名：YYYY-MM-DD_HHmm_<title>.md
+        """
+        now = datetime.now()
+        safe_title = title.replace("/", "-").replace("\\", "-")[:20]
+        filename = f"{now.strftime('%Y-%m-%d_%H%M')}_{safe_title}.md"
+        file_path = self.meetings_dir / filename
+
+        source_line = f"来源：`{source_filename}` | " if source_filename else ""
+        duration_line = f"时长：{duration_hint} | " if duration_hint else ""
+
+        header = (
+            f"# {now.strftime('%Y-%m-%d %H:%M')} {title}\n\n"
+            f"> {source_line}{duration_line}"
+            f"转写模型：qwen3-asr-flash | 入库时间：{now.strftime('%Y-%m-%d %H:%M')}\n\n"
+            f"---\n\n"
+        )
+        with self._lock:
+            file_path.write_text(header, encoding="utf-8")
+
+        return file_path
+
+    def append_segment(
+        self,
+        file_path: Path,
+        text: str,
+        offset_ms: int = 0,
+    ) -> int:
+        """
+        追加一个 transcript 片段。
+        格式：[MM:SS] 文字内容
+        返回追加的字符数。
+        """
+        text = text.strip()
+        if not text:
+            return 0
+
+        if offset_ms > 0:
+            total_s = offset_ms // 1000
+            mm, ss = divmod(total_s, 60)
+            timestamp = f"[{mm:02d}:{ss:02d}] "
+        else:
+            timestamp = ""
+
+        line = f"{timestamp}{text}\n\n"
+        with self._lock:
+            with file_path.open("a", encoding="utf-8") as f:
+                f.write(line)
+
+        return len(text)
+
+    def finalize(self, file_path: Path, char_count: int = 0) -> None:
+        """写入结束标记。"""
+        summary = f"\n---\n\n> ✅ 转写完成，共 {char_count} 字\n"
+        with self._lock:
+            with file_path.open("a", encoding="utf-8") as f:
+                f.write(summary)
+
+    def relative_path(self, file_path: Path) -> str:
+        """返回相对于 meetings_dir 父目录的路径，用于日志/SSE。"""
+        try:
+            return str(file_path.relative_to(self.meetings_dir.parent))
+        except ValueError:
+            return str(file_path)

mindcli/_vendor/gateway/platforms/mindcli_bridge.py

@@ -0,0 +1,249 @@
+"""
+Mind CLI Bridge — Cloud 端 WebSocket Tunnel 管理器。
+
+管理所有 Mind CLI 用户的 Tunnel 连接：
+- 接收 CLI 的 WebSocket 握手 + JWT 认证
+- 能力审计（审批通过的工具白名单）
+- 工具调用派发（Cloud LLM → Tunnel → CLI → 结果）
+"""
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from typing import Any
+
+from aiohttp import web
+
+logger = logging.getLogger("mindcli_bridge")
+
+# ── 初版白名单（所有内置工具默认通过） ────────────────────
+DEFAULT_APPROVED_TOOLS = [
+    "terminal",
+    "file_read",
+    "file_write",
+    "file_ops",
+    "grep",
+    "code_execution",
+]
+
+# 工具调用超时
+TOOL_CALL_TIMEOUT = 120  # 秒
+# 心跳检测：60s 无消息判定离线
+HEARTBEAT_TIMEOUT = 60
+
+
+class MindCLIBridge:
+    """
+    管理所有 CLI 用户的 Tunnel 连接。
+
+    每个 userId 最多维持一个活跃 WebSocket 连接。
+    """
+
+    def __init__(self):
+        # userId → WebSocketResponse
+        self._connections: dict[str, web.WebSocketResponse] = {}
+        # userId → 能力报告
+        self._capabilities: dict[str, dict] = {}
+        # userId → 最后心跳时间
+        self._last_heartbeat: dict[str, float] = {}
+        # 待处理的 tool_call 请求
+        self._pending: dict[str, asyncio.Future] = {}
+
+    async def handle_tunnel_connect(self, request: web.Request) -> web.WebSocketResponse:
+        """
+        WebSocket 握手入口。
+
+        路由：GET /mindos-next/ws/cli-tunnel
+        认证：Header Authorization: Bearer <JWT>
+        """
+        ws = web.WebSocketResponse(heartbeat=30, autoping=True)
+        await ws.prepare(request)
+
+        # ── JWT 认证 ──
+        token = _extract_token(request)
+        if not token:
+            await ws.send_json({"type": "error", "message": "Missing Authorization header"})
+            await ws.close()
+            return ws
+
+        # 使用 MindPass 认证策略
+        user = await self._verify_token(token, request)
+        if not user:
+            await ws.send_json({"type": "error", "message": "Invalid or expired token"})
+            await ws.close()
+            return ws
+
+        user_id = user["userId"]
+
+        # 关闭旧连接
+        old_ws = self._connections.get(user_id)
+        if old_ws and not old_ws.closed:
+            logger.info("[Bridge] 关闭 %s 的旧连接", user_id)
+            await old_ws.close()
+
+        self._connections[user_id] = ws
+        self._last_heartbeat[user_id] = time.time()
+        logger.info("[Bridge] CLI 连接: userId=%s", user_id)
+
+        # ── 发送连接确认 ──
+        await ws.send_json({
+            "type": "connected",
+            "userId": user_id,
+        })
+
+        # ── 等待能力报告 ──
+        try:
+            msg = await asyncio.wait_for(ws.receive_json(), timeout=10)
+            if msg.get("type") == "capability_report":
+                self._capabilities[user_id] = msg
+                logger.info(
+                    "[Bridge] 能力报告: userId=%s, tools=%d, mcp=%d",
+                    user_id,
+                    len(msg.get("tools", [])),
+                    len(msg.get("mcp_servers", [])),
+                )
+
+                # 审批工具
+                approved = self._audit_capabilities(msg)
+                await ws.send_json({
+                    "type": "approved_tools",
+                    "tools": approved,
+                })
+        except asyncio.TimeoutError:
+            logger.warning("[Bridge] %s 未在 10s 内发送能力报告", user_id)
+
+        # ── 消息循环 ──
+        try:
+            async for msg in ws:
+                if msg.type == web.WSMsgType.TEXT:
+                    data = json.loads(msg.data)
+                    await self._handle_message(user_id, data)
+                elif msg.type in (web.WSMsgType.ERROR, web.WSMsgType.CLOSE):
+                    break
+        except Exception as e:
+            logger.warning("[Bridge] %s 连接异常: %s", user_id, e)
+        finally:
+            self._cleanup(user_id)
+
+        return ws
+
+    def is_connected(self, user_id: str) -> bool:
+        """检查用户的 CLI 是否在线。"""
+        ws = self._connections.get(user_id)
+        return ws is not None and not ws.closed
+
+    def get_capabilities(self, user_id: str) -> dict | None:
+        """获取用户 CLI 的能力报告。"""
+        return self._capabilities.get(user_id)
+
+    async def dispatch_tool_call(
+        self, user_id: str, tool_name: str, args: dict
+    ) -> dict:
+        """
+        派发工具调用：Cloud LLM → Tunnel → CLI → 结果。
+
+        Args:
+            user_id: 用户 ID
+            tool_name: 工具名（如 "terminal"）
+            args: 工具参数
+
+        Returns:
+            {"output": "...", "exit_code": 0} 或 {"error": "..."}
+        """
+        ws = self._connections.get(user_id)
+        if not ws or ws.closed:
+            return {"error": "CLI not connected"}
+
+        call_id = str(uuid.uuid4())[:8]
+
+        # 创建 Future 等待 CLI 响应
+        future: asyncio.Future = asyncio.get_event_loop().create_future()
+        self._pending[call_id] = future
+
+        try:
+            # 发送 JSON-RPC tool_call
+            await ws.send_json({
+                "jsonrpc": "2.0",
+                "method": "tool_call",
+                "params": {"tool": tool_name, "args": args},
+                "id": call_id,
+            })
+            logger.info("[Bridge] → %s: %s (id=%s)", user_id, tool_name, call_id)
+
+            # 等待结果
+            result = await asyncio.wait_for(future, timeout=TOOL_CALL_TIMEOUT)
+            logger.info("[Bridge] ← %s: %s 完成 (id=%s)", user_id, tool_name, call_id)
+            return result
+
+        except asyncio.TimeoutError:
+            logger.warning("[Bridge] %s: %s 超时 (id=%s)", user_id, tool_name, call_id)
+            return {"error": f"Tool call timed out after {TOOL_CALL_TIMEOUT}s"}
+        finally:
+            self._pending.pop(call_id, None)
+
+    # ── 内部方法 ──────────────────────────────────────
+
+    async def _verify_token(self, token: str, request: web.Request) -> dict | None:
+        """JWT 验证（复用 MindPass 认证策略）。"""
+        try:
+            from platforms.sse_base.auth_strategies import MindPassAuth
+            auth = MindPassAuth()
+            return await auth.verify(token)
+        except Exception as e:
+            logger.error("[Bridge] Token 验证失败: %s", e)
+            return None
+
+    def _audit_capabilities(self, report: dict) -> list[str]:
+        """
+        审计 CLI 上报的能力，返回审批通过的工具列表。
+
+        初版：白名单 = DEFAULT_APPROVED_TOOLS 与上报工具的交集。
+        后续：从 DB 读取 per-user 配置。
+        """
+        reported_tools = {t["name"] for t in report.get("tools", [])}
+        approved = [t for t in DEFAULT_APPROVED_TOOLS if t in reported_tools]
+        return approved
+
+    async def _handle_message(self, user_id: str, data: dict) -> None:
+        """处理 CLI 发来的消息。"""
+        self._last_heartbeat[user_id] = time.time()
+
+        # JSON-RPC 响应（工具调用结果）
+        if data.get("jsonrpc") == "2.0" and "id" in data:
+            call_id = data["id"]
+            future = self._pending.get(call_id)
+            if future and not future.done():
+                result = data.get("result", {"error": "Empty result"})
+                future.set_result(result)
+            return
+
+        # 心跳 pong
+        if data.get("type") == "pong":
+            return
+
+        logger.debug("[Bridge] %s 未知消息: %s", user_id, data.get("type"))
+
+    def _cleanup(self, user_id: str) -> None:
+        """连接关闭时清理。"""
+        self._connections.pop(user_id, None)
+        self._capabilities.pop(user_id, None)
+        self._last_heartbeat.pop(user_id, None)
+
+        # 取消所有待处理的 Future
+        to_cancel = [k for k, v in self._pending.items() if not v.done()]
+        for k in to_cancel:
+            self._pending[k].set_exception(ConnectionError("CLI disconnected"))
+            del self._pending[k]
+
+        logger.info("[Bridge] CLI 断开: userId=%s", user_id)
+
+
+def _extract_token(request: web.Request) -> str | None:
+    """从 Authorization header 或 query 参数提取 token。"""
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return auth_header[7:]
+    # 备选：query 参数（WebSocket 某些客户端不支持 header）
+    return request.query.get("token")

mindcli/_vendor/gateway/platforms/signal.py

@@ -0,0 +1,825 @@
+"""Signal messenger platform adapter.
+
+Connects to a signal-cli daemon running in HTTP mode.
+Inbound messages arrive via SSE (Server-Sent Events) streaming.
+Outbound messages and actions use JSON-RPC 2.0 over HTTP.
+
+Based on PR #268 by ibhagwan, rebuilt with bug fixes.
+
+Requires:
+  - signal-cli installed and running: signal-cli daemon --http 127.0.0.1:8080
+  - SIGNAL_HTTP_URL and SIGNAL_ACCOUNT environment variables set
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import random
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+from urllib.parse import quote, unquote
+
+import httpx
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+    cache_image_from_bytes,
+    cache_audio_from_bytes,
+    cache_document_from_bytes,
+    cache_image_from_url,
+)
+from gateway.platforms.helpers import redact_phone
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+SIGNAL_MAX_ATTACHMENT_SIZE = 100 * 1024 * 1024  # 100 MB
+MAX_MESSAGE_LENGTH = 8000  # Signal message size limit
+TYPING_INTERVAL = 8.0  # seconds between typing indicator refreshes
+SSE_RETRY_DELAY_INITIAL = 2.0
+SSE_RETRY_DELAY_MAX = 60.0
+HEALTH_CHECK_INTERVAL = 30.0  # seconds between health checks
+HEALTH_CHECK_STALE_THRESHOLD = 120.0  # seconds without SSE activity before concern
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_comma_list(value: str) -> List[str]:
+    """Split a comma-separated string into a list, stripping whitespace."""
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _guess_extension(data: bytes) -> str:
+    """Guess file extension from magic bytes."""
+    if data[:4] == b"\x89PNG":
+        return ".png"
+    if data[:2] == b"\xff\xd8":
+        return ".jpg"
+    if data[:4] == b"GIF8":
+        return ".gif"
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return ".webp"
+    if data[:4] == b"%PDF":
+        return ".pdf"
+    if len(data) >= 8 and data[4:8] == b"ftyp":
+        return ".mp4"
+    if data[:4] == b"OggS":
+        return ".ogg"
+    if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+        return ".mp3"
+    if data[:2] == b"PK":
+        return ".zip"
+    return ".bin"
+
+
+def _is_image_ext(ext: str) -> bool:
+    return ext.lower() in (".jpg", ".jpeg", ".png", ".gif", ".webp")
+
+
+def _is_audio_ext(ext: str) -> bool:
+    return ext.lower() in (".mp3", ".wav", ".ogg", ".m4a", ".aac")
+
+
+_EXT_TO_MIME = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
+    ".gif": "image/gif", ".webp": "image/webp",
+    ".ogg": "audio/ogg", ".mp3": "audio/mpeg", ".wav": "audio/wav",
+    ".m4a": "audio/mp4", ".aac": "audio/aac",
+    ".mp4": "video/mp4", ".pdf": "application/pdf", ".zip": "application/zip",
+}
+
+
+def _ext_to_mime(ext: str) -> str:
+    """Map file extension to MIME type."""
+    return _EXT_TO_MIME.get(ext.lower(), "application/octet-stream")
+
+
+def _render_mentions(text: str, mentions: list) -> str:
+    """Replace Signal mention placeholders (\\uFFFC) with readable @identifiers.
+
+    Signal encodes @mentions as the Unicode object replacement character
+    with out-of-band metadata containing the mentioned user's UUID/number.
+    """
+    if not mentions or "\uFFFC" not in text:
+        return text
+    # Sort mentions by start position (reverse) to replace from end to start
+    # so indices don't shift as we replace
+    sorted_mentions = sorted(mentions, key=lambda m: m.get("start", 0), reverse=True)
+    for mention in sorted_mentions:
+        start = mention.get("start", 0)
+        length = mention.get("length", 1)
+        # Use the mention's number or UUID as the replacement
+        identifier = mention.get("number") or mention.get("uuid") or "user"
+        replacement = f"@{identifier}"
+        text = text[:start] + replacement + text[start + length:]
+    return text
+
+
+def check_signal_requirements() -> bool:
+    """Check if Signal is configured (has URL and account)."""
+    return bool(os.getenv("SIGNAL_HTTP_URL") and os.getenv("SIGNAL_ACCOUNT"))
+
+
+# ---------------------------------------------------------------------------
+# Signal Adapter
+# ---------------------------------------------------------------------------
+
+class SignalAdapter(BasePlatformAdapter):
+    """Signal messenger adapter using signal-cli HTTP daemon."""
+
+    platform = Platform.SIGNAL
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.SIGNAL)
+
+        extra = config.extra or {}
+        self.http_url = extra.get("http_url", "http://127.0.0.1:8080").rstrip("/")
+        self.account = extra.get("account", "")
+        self.ignore_stories = extra.get("ignore_stories", True)
+
+        # Parse allowlists — group policy is derived from presence of group allowlist
+        group_allowed_str = os.getenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+        self.group_allow_from = set(_parse_comma_list(group_allowed_str))
+
+        # HTTP client
+        self.client: Optional[httpx.AsyncClient] = None
+
+        # Background tasks
+        self._sse_task: Optional[asyncio.Task] = None
+        self._health_monitor_task: Optional[asyncio.Task] = None
+        self._typing_tasks: Dict[str, asyncio.Task] = {}
+        self._running = False
+        self._last_sse_activity = 0.0
+        self._sse_response: Optional[httpx.Response] = None
+
+        # Normalize account for self-message filtering
+        self._account_normalized = self.account.strip()
+
+        # Track recently sent message timestamps to prevent echo-back loops
+        # in Note to Self / self-chat mode (mirrors WhatsApp recentlySentIds)
+        self._recent_sent_timestamps: set = set()
+        self._max_recent_timestamps = 50
+
+        logger.info("Signal adapter initialized: url=%s account=%s groups=%s",
+                     self.http_url, redact_phone(self.account),
+                     "enabled" if self.group_allow_from else "disabled")
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to signal-cli daemon and start SSE listener."""
+        if not self.http_url or not self.account:
+            logger.error("Signal: SIGNAL_HTTP_URL and SIGNAL_ACCOUNT are required")
+            return False
+
+        # Acquire scoped lock to prevent duplicate Signal listeners for the same phone
+        try:
+            if not self._acquire_platform_lock('signal-phone', self.account, 'Signal account'):
+                return False
+        except Exception as e:
+            logger.warning("Signal: Could not acquire phone lock (non-fatal): %s", e)
+
+        self.client = httpx.AsyncClient(timeout=30.0)
+
+        # Health check — verify signal-cli daemon is reachable
+        try:
+            resp = await self.client.get(f"{self.http_url}/api/v1/check", timeout=10.0)
+            if resp.status_code != 200:
+                logger.error("Signal: health check failed (status %d)", resp.status_code)
+                return False
+        except Exception as e:
+            logger.error("Signal: cannot reach signal-cli at %s: %s", self.http_url, e)
+            return False
+
+        self._running = True
+        self._last_sse_activity = time.time()
+        self._sse_task = asyncio.create_task(self._sse_listener())
+        self._health_monitor_task = asyncio.create_task(self._health_monitor())
+
+        logger.info("Signal: connected to %s", self.http_url)
+        return True
+
+    async def disconnect(self) -> None:
+        """Stop SSE listener and clean up."""
+        self._running = False
+
+        if self._sse_task:
+            self._sse_task.cancel()
+            try:
+                await self._sse_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._health_monitor_task:
+            self._health_monitor_task.cancel()
+            try:
+                await self._health_monitor_task
+            except asyncio.CancelledError:
+                pass
+
+        # Cancel all typing tasks
+        for task in self._typing_tasks.values():
+            task.cancel()
+        self._typing_tasks.clear()
+
+        if self.client:
+            await self.client.aclose()
+            self.client = None
+
+        self._release_platform_lock()
+
+        logger.info("Signal: disconnected")
+
+    # ------------------------------------------------------------------
+    # SSE Streaming (inbound messages)
+    # ------------------------------------------------------------------
+
+    async def _sse_listener(self) -> None:
+        """Listen for SSE events from signal-cli daemon."""
+        url = f"{self.http_url}/api/v1/events?account={quote(self.account, safe='')}"
+        backoff = SSE_RETRY_DELAY_INITIAL
+
+        while self._running:
+            try:
+                logger.debug("Signal SSE: connecting to %s", url)
+                async with self.client.stream(
+                    "GET", url,
+                    headers={"Accept": "text/event-stream"},
+                    timeout=None,
+                ) as response:
+                    self._sse_response = response
+                    backoff = SSE_RETRY_DELAY_INITIAL  # Reset on successful connection
+                    self._last_sse_activity = time.time()
+                    logger.info("Signal SSE: connected")
+
+                    buffer = ""
+                    async for chunk in response.aiter_text():
+                        if not self._running:
+                            break
+                        buffer += chunk
+                        while "\n" in buffer:
+                            line, buffer = buffer.split("\n", 1)
+                            line = line.strip()
+                            if not line:
+                                continue
+                            # SSE keepalive comments (":") prove the connection
+                            # is alive — update activity so the health monitor
+                            # doesn't report false idle warnings.
+                            if line.startswith(":"):
+                                self._last_sse_activity = time.time()
+                                continue
+                            # Parse SSE data lines
+                            if line.startswith("data:"):
+                                data_str = line[5:].strip()
+                                if not data_str:
+                                    continue
+                                self._last_sse_activity = time.time()
+                                try:
+                                    data = json.loads(data_str)
+                                    await self._handle_envelope(data)
+                                except json.JSONDecodeError:
+                                    logger.debug("Signal SSE: invalid JSON: %s", data_str[:100])
+                                except Exception:
+                                    logger.exception("Signal SSE: error handling event")
+
+            except asyncio.CancelledError:
+                break
+            except httpx.HTTPError as e:
+                if self._running:
+                    logger.warning("Signal SSE: HTTP error: %s (reconnecting in %.0fs)", e, backoff)
+            except Exception as e:
+                if self._running:
+                    logger.warning("Signal SSE: error: %s (reconnecting in %.0fs)", e, backoff)
+
+            if self._running:
+                # Add 20% jitter to prevent thundering herd on reconnection
+                jitter = backoff * 0.2 * random.random()
+                await asyncio.sleep(backoff + jitter)
+                backoff = min(backoff * 2, SSE_RETRY_DELAY_MAX)
+
+        self._sse_response = None
+
+    # ------------------------------------------------------------------
+    # Health Monitor
+    # ------------------------------------------------------------------
+
+    async def _health_monitor(self) -> None:
+        """Monitor SSE connection health and force reconnect if stale."""
+        while self._running:
+            await asyncio.sleep(HEALTH_CHECK_INTERVAL)
+            if not self._running:
+                break
+
+            elapsed = time.time() - self._last_sse_activity
+            if elapsed > HEALTH_CHECK_STALE_THRESHOLD:
+                logger.warning("Signal: SSE idle for %.0fs, checking daemon health", elapsed)
+                try:
+                    resp = await self.client.get(
+                        f"{self.http_url}/api/v1/check", timeout=10.0
+                    )
+                    if resp.status_code == 200:
+                        # Daemon is alive but SSE is idle — update activity to
+                        # avoid repeated warnings (connection may just be quiet)
+                        self._last_sse_activity = time.time()
+                        logger.debug("Signal: daemon healthy, SSE idle")
+                    else:
+                        logger.warning("Signal: health check failed (%d), forcing reconnect", resp.status_code)
+                        self._force_reconnect()
+                except Exception as e:
+                    logger.warning("Signal: health check error: %s, forcing reconnect", e)
+                    self._force_reconnect()
+
+    def _force_reconnect(self) -> None:
+        """Force SSE reconnection by closing the current response."""
+        if self._sse_response and not self._sse_response.is_stream_consumed:
+            try:
+                task = asyncio.create_task(self._sse_response.aclose())
+                self._background_tasks.add(task)
+                task.add_done_callback(self._background_tasks.discard)
+            except Exception:
+                pass
+            self._sse_response = None
+
+    # ------------------------------------------------------------------
+    # Message Handling
+    # ------------------------------------------------------------------
+
+    async def _handle_envelope(self, envelope: dict) -> None:
+        """Process an incoming signal-cli envelope."""
+        # Unwrap nested envelope if present
+        envelope_data = envelope.get("envelope", envelope)
+
+        # Handle syncMessage: extract "Note to Self" messages (sent to own account)
+        # while still filtering other sync events (read receipts, typing, etc.)
+        is_note_to_self = False
+        if "syncMessage" in envelope_data:
+            sync_msg = envelope_data.get("syncMessage")
+            if sync_msg and isinstance(sync_msg, dict):
+                sent_msg = sync_msg.get("sentMessage")
+                if sent_msg and isinstance(sent_msg, dict):
+                    dest = sent_msg.get("destinationNumber") or sent_msg.get("destination")
+                    sent_ts = sent_msg.get("timestamp")
+                    if dest == self._account_normalized:
+                        # Check if this is an echo of our own outbound reply
+                        if sent_ts and sent_ts in self._recent_sent_timestamps:
+                            self._recent_sent_timestamps.discard(sent_ts)
+                            return
+                        # Genuine user Note to Self — promote to dataMessage
+                        is_note_to_self = True
+                        envelope_data = {**envelope_data, "dataMessage": sent_msg}
+            if not is_note_to_self:
+                return
+
+        # Extract sender info
+        sender = (
+            envelope_data.get("sourceNumber")
+            or envelope_data.get("sourceUuid")
+            or envelope_data.get("source")
+        )
+        sender_name = envelope_data.get("sourceName", "")
+        sender_uuid = envelope_data.get("sourceUuid", "")
+
+        if not sender:
+            logger.debug("Signal: ignoring envelope with no sender")
+            return
+
+        # Self-message filtering — prevent reply loops (but allow Note to Self)
+        if self._account_normalized and sender == self._account_normalized and not is_note_to_self:
+            return
+
+        # Filter stories
+        if self.ignore_stories and envelope_data.get("storyMessage"):
+            return
+
+        # Get data message — also check editMessage (edited messages contain
+        # their updated dataMessage inside editMessage.dataMessage)
+        data_message = (
+            envelope_data.get("dataMessage")
+            or (envelope_data.get("editMessage") or {}).get("dataMessage")
+        )
+        if not data_message:
+            return
+
+        # Check for group message
+        group_info = data_message.get("groupInfo")
+        group_id = group_info.get("groupId") if group_info else None
+        is_group = bool(group_id)
+
+        # Group message filtering — derived from SIGNAL_GROUP_ALLOWED_USERS:
+        # - No env var set → groups disabled (default safe behavior)
+        # - Env var set with group IDs → only those groups allowed
+        # - Env var set with "*" → all groups allowed
+        # DM auth is fully handled by run.py (_is_user_authorized)
+        if is_group:
+            if not self.group_allow_from:
+                logger.debug("Signal: ignoring group message (no SIGNAL_GROUP_ALLOWED_USERS)")
+                return
+            if "*" not in self.group_allow_from and group_id not in self.group_allow_from:
+                logger.debug("Signal: group %s not in allowlist", group_id[:8] if group_id else "?")
+                return
+
+        # Build chat info
+        chat_id = sender if not is_group else f"group:{group_id}"
+        chat_type = "group" if is_group else "dm"
+
+        # Extract text and render mentions
+        text = data_message.get("message", "")
+        mentions = data_message.get("mentions", [])
+        if text and mentions:
+            text = _render_mentions(text, mentions)
+
+        # Process attachments
+        attachments_data = data_message.get("attachments", [])
+        media_urls = []
+        media_types = []
+
+        if attachments_data and not getattr(self, "ignore_attachments", False):
+            for att in attachments_data:
+                att_id = att.get("id")
+                att_size = att.get("size", 0)
+                if not att_id:
+                    continue
+                if att_size > SIGNAL_MAX_ATTACHMENT_SIZE:
+                    logger.warning("Signal: attachment too large (%d bytes), skipping", att_size)
+                    continue
+                try:
+                    cached_path, ext = await self._fetch_attachment(att_id)
+                    if cached_path:
+                        # Use contentType from Signal if available, else map from extension
+                        content_type = att.get("contentType") or _ext_to_mime(ext)
+                        media_urls.append(cached_path)
+                        media_types.append(content_type)
+                except Exception:
+                    logger.exception("Signal: failed to fetch attachment %s", att_id)
+
+        # Build session source
+        source = self.build_source(
+            chat_id=chat_id,
+            chat_name=group_info.get("groupName") if group_info else sender_name,
+            chat_type=chat_type,
+            user_id=sender,
+            user_name=sender_name or sender,
+            user_id_alt=sender_uuid if sender_uuid else None,
+            chat_id_alt=group_id if is_group else None,
+        )
+
+        # Determine message type from media
+        msg_type = MessageType.TEXT
+        if media_types:
+            if any(mt.startswith("audio/") for mt in media_types):
+                msg_type = MessageType.VOICE
+            elif any(mt.startswith("image/") for mt in media_types):
+                msg_type = MessageType.PHOTO
+
+        # Parse timestamp from envelope data (milliseconds since epoch)
+        ts_ms = envelope_data.get("timestamp", 0)
+        if ts_ms:
+            try:
+                timestamp = datetime.fromtimestamp(ts_ms / 1000, tz=timezone.utc)
+            except (ValueError, OSError):
+                timestamp = datetime.now(tz=timezone.utc)
+        else:
+            timestamp = datetime.now(tz=timezone.utc)
+
+        # Build and dispatch event
+        event = MessageEvent(
+            source=source,
+            text=text or "",
+            message_type=msg_type,
+            media_urls=media_urls,
+            media_types=media_types,
+            timestamp=timestamp,
+        )
+
+        logger.debug("Signal: message from %s in %s: %s",
+                      redact_phone(sender), chat_id[:20], (text or "")[:50])
+
+        await self.handle_message(event)
+
+    # ------------------------------------------------------------------
+    # Attachment Handling
+    # ------------------------------------------------------------------
+
+    async def _fetch_attachment(self, attachment_id: str) -> tuple:
+        """Fetch an attachment via JSON-RPC and cache it. Returns (path, ext)."""
+        result = await self._rpc("getAttachment", {
+            "account": self.account,
+            "id": attachment_id,
+        })
+
+        if not result:
+            return None, ""
+
+        # Handle dict response (signal-cli returns {"data": "base64..."})
+        if isinstance(result, dict):
+            result = result.get("data")
+            if not result:
+                logger.warning("Signal: attachment response missing 'data' key")
+                return None, ""
+
+        # Result is base64-encoded file content
+        raw_data = base64.b64decode(result)
+        ext = _guess_extension(raw_data)
+
+        if _is_image_ext(ext):
+            path = cache_image_from_bytes(raw_data, ext)
+        elif _is_audio_ext(ext):
+            path = cache_audio_from_bytes(raw_data, ext)
+        else:
+            path = cache_document_from_bytes(raw_data, ext)
+
+        return path, ext
+
+    # ------------------------------------------------------------------
+    # JSON-RPC Communication
+    # ------------------------------------------------------------------
+
+    async def _rpc(self, method: str, params: dict, rpc_id: str = None) -> Any:
+        """Send a JSON-RPC 2.0 request to signal-cli daemon."""
+        if not self.client:
+            logger.warning("Signal: RPC called but client not connected")
+            return None
+
+        if rpc_id is None:
+            rpc_id = f"{method}_{int(time.time() * 1000)}"
+
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+            "id": rpc_id,
+        }
+
+        try:
+            resp = await self.client.post(
+                f"{self.http_url}/api/v1/rpc",
+                json=payload,
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+            if "error" in data:
+                logger.warning("Signal RPC error (%s): %s", method, data["error"])
+                return None
+
+            return data.get("result")
+
+        except Exception as e:
+            logger.warning("Signal RPC %s failed: %s", method, e)
+            return None
+
+    # ------------------------------------------------------------------
+    # Sending
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Send a text message."""
+        await self._stop_typing_indicator(chat_id)
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": content,
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+
+        if result is not None:
+            self._track_sent_timestamp(result)
+            # Use the timestamp from the RPC result as a pseudo message_id.
+            # Signal doesn't have real message IDs, but the stream consumer
+            # needs a truthy value to follow its edit→fallback path correctly.
+            _msg_id = str(result.get("timestamp", "")) if isinstance(result, dict) else None
+            return SendResult(success=True, message_id=_msg_id or None)
+        return SendResult(success=False, error="RPC send failed")
+
+    def _track_sent_timestamp(self, rpc_result) -> None:
+        """Record outbound message timestamp for echo-back filtering."""
+        ts = rpc_result.get("timestamp") if isinstance(rpc_result, dict) else None
+        if ts:
+            self._recent_sent_timestamps.add(ts)
+            if len(self._recent_sent_timestamps) > self._max_recent_timestamps:
+                self._recent_sent_timestamps.pop()
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """Send a typing indicator."""
+        params: Dict[str, Any] = {
+            "account": self.account,
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        await self._rpc("sendTyping", params, rpc_id="typing")
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send an image. Supports http(s):// and file:// URLs."""
+        await self._stop_typing_indicator(chat_id)
+
+        # Resolve image to local path
+        if image_url.startswith("file://"):
+            file_path = unquote(image_url[7:])
+        else:
+            # Download remote image to cache
+            try:
+                file_path = await cache_image_from_url(image_url)
+            except Exception as e:
+                logger.warning("Signal: failed to download image: %s", e)
+                return SendResult(success=False, error=str(e))
+
+        if not file_path or not Path(file_path).exists():
+            return SendResult(success=False, error="Image file not found")
+
+        # Validate size
+        file_size = Path(file_path).stat().st_size
+        if file_size > SIGNAL_MAX_ATTACHMENT_SIZE:
+            return SendResult(success=False, error=f"Image too large ({file_size} bytes)")
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": caption or "",
+            "attachments": [file_path],
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+        if result is not None:
+            self._track_sent_timestamp(result)
+            return SendResult(success=True)
+        return SendResult(success=False, error="RPC send with attachment failed")
+
+    async def _send_attachment(
+        self,
+        chat_id: str,
+        file_path: str,
+        media_label: str,
+        caption: Optional[str] = None,
+    ) -> SendResult:
+        """Send any file as a Signal attachment via RPC.
+
+        Shared implementation for send_document, send_image_file, send_voice,
+        and send_video — avoids duplicating the validation/routing/RPC logic.
+        """
+        await self._stop_typing_indicator(chat_id)
+
+        try:
+            file_size = Path(file_path).stat().st_size
+        except FileNotFoundError:
+            return SendResult(success=False, error=f"{media_label} file not found: {file_path}")
+
+        if file_size > SIGNAL_MAX_ATTACHMENT_SIZE:
+            return SendResult(success=False, error=f"{media_label} too large ({file_size} bytes)")
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": caption or "",
+            "attachments": [file_path],
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+        if result is not None:
+            self._track_sent_timestamp(result)
+            return SendResult(success=True)
+        return SendResult(success=False, error=f"RPC send {media_label.lower()} failed")
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a document/file attachment."""
+        return await self._send_attachment(chat_id, file_path, "File", caption)
+
+    async def send_image_file(
+        self,
+        chat_id: str,
+        image_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local image file as a native Signal attachment.
+
+        Called by the gateway media delivery flow when MEDIA: tags containing
+        image paths are extracted from agent responses.
+        """
+        return await self._send_attachment(chat_id, image_path, "Image", caption)
+
+    async def send_voice(
+        self,
+        chat_id: str,
+        audio_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send an audio file as a Signal attachment.
+
+        Signal does not distinguish voice messages from file attachments at
+        the API level, so this routes through the same RPC send path.
+        """
+        return await self._send_attachment(chat_id, audio_path, "Audio", caption)
+
+    async def send_video(
+        self,
+        chat_id: str,
+        video_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a video file as a Signal attachment."""
+        return await self._send_attachment(chat_id, video_path, "Video", caption)
+
+    # ------------------------------------------------------------------
+    # Typing Indicators
+    # ------------------------------------------------------------------
+
+    async def _stop_typing_indicator(self, chat_id: str) -> None:
+        """Stop a typing indicator loop for a chat."""
+        task = self._typing_tasks.pop(chat_id, None)
+        if task:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    async def stop_typing(self, chat_id: str) -> None:
+        """Public interface for stopping typing — called by base adapter's
+        _keep_typing finally block to clean up platform-level typing tasks."""
+        await self._stop_typing_indicator(chat_id)
+
+    # ------------------------------------------------------------------
+    # Chat Info
+    # ------------------------------------------------------------------
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Get information about a chat/contact."""
+        if chat_id.startswith("group:"):
+            return {
+                "name": chat_id,
+                "type": "group",
+                "chat_id": chat_id,
+            }
+
+        # Try to resolve contact name
+        result = await self._rpc("getContact", {
+            "account": self.account,
+            "contactAddress": chat_id,
+        })
+
+        name = chat_id
+        if result and isinstance(result, dict):
+            name = result.get("name") or result.get("profileName") or chat_id
+
+        return {
+            "name": name,
+            "type": "dm",
+            "chat_id": chat_id,
+        }

mindcli/_vendor/gateway/platforms/sms.py

@@ -0,0 +1,373 @@
+"""SMS (Twilio) platform adapter.
+
+Connects to the Twilio REST API for outbound SMS and runs an aiohttp
+webhook server to receive inbound messages.
+
+Shares credentials with the optional telephony skill — same env vars:
+  - TWILIO_ACCOUNT_SID
+  - TWILIO_AUTH_TOKEN
+  - TWILIO_PHONE_NUMBER  (E.164 from-number, e.g. +15551234567)
+
+Gateway-specific env vars:
+  - SMS_WEBHOOK_PORT     (default 8080)
+  - SMS_WEBHOOK_HOST     (default 0.0.0.0)
+  - SMS_WEBHOOK_URL      (public URL for Twilio signature validation — required)
+  - SMS_INSECURE_NO_SIGNATURE  (true to disable signature validation — dev only)
+  - SMS_ALLOWED_USERS    (comma-separated E.164 phone numbers)
+  - SMS_ALLOW_ALL_USERS  (true/false)
+  - SMS_HOME_CHANNEL     (phone number for cron delivery)
+"""
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import logging
+import os
+import urllib.parse
+from typing import Any, Dict, Optional
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+from gateway.platforms.helpers import redact_phone, strip_markdown
+
+logger = logging.getLogger(__name__)
+
+TWILIO_API_BASE = "https://api.twilio.com/2010-04-01/Accounts"
+MAX_SMS_LENGTH = 1600  # ~10 SMS segments
+DEFAULT_WEBHOOK_PORT = 8080
+DEFAULT_WEBHOOK_HOST = "0.0.0.0"
+
+
+def check_sms_requirements() -> bool:
+    """Check if SMS adapter dependencies are available."""
+    try:
+        import aiohttp  # noqa: F401
+    except ImportError:
+        return False
+    return bool(os.getenv("TWILIO_ACCOUNT_SID") and os.getenv("TWILIO_AUTH_TOKEN"))
+
+
+class SmsAdapter(BasePlatformAdapter):
+    """
+    Twilio SMS <-> Hermes gateway adapter.
+
+    Each inbound phone number gets its own Hermes session (multi-tenant).
+    Replies are always sent from the configured TWILIO_PHONE_NUMBER.
+    """
+
+    MAX_MESSAGE_LENGTH = MAX_SMS_LENGTH
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.SMS)
+        self._account_sid: str = os.environ["TWILIO_ACCOUNT_SID"]
+        self._auth_token: str = os.environ["TWILIO_AUTH_TOKEN"]
+        self._from_number: str = os.getenv("TWILIO_PHONE_NUMBER", "")
+        self._webhook_port: int = int(
+            os.getenv("SMS_WEBHOOK_PORT", str(DEFAULT_WEBHOOK_PORT))
+        )
+        self._webhook_host: str = os.getenv("SMS_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST)
+        self._webhook_url: str = os.getenv("SMS_WEBHOOK_URL", "").strip()
+        self._runner = None
+        self._http_session: Optional["aiohttp.ClientSession"] = None
+
+    def _basic_auth_header(self) -> str:
+        """Build HTTP Basic auth header value for Twilio."""
+        creds = f"{self._account_sid}:{self._auth_token}"
+        encoded = base64.b64encode(creds.encode("ascii")).decode("ascii")
+        return f"Basic {encoded}"
+
+    # ------------------------------------------------------------------
+    # Required abstract methods
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        import aiohttp
+        from aiohttp import web
+
+        if not self._from_number:
+            logger.error("[sms] TWILIO_PHONE_NUMBER not set — cannot send replies")
+            return False
+
+        insecure_no_sig = os.getenv("SMS_INSECURE_NO_SIGNATURE", "").lower() == "true"
+
+        if not self._webhook_url and not insecure_no_sig:
+            logger.error(
+                "[sms] Refusing to start: SMS_WEBHOOK_URL is required for Twilio "
+                "signature validation. Set it to the public URL configured in your "
+                "Twilio console (e.g. https://example.com/webhooks/twilio). "
+                "For local development without validation, set "
+                "SMS_INSECURE_NO_SIGNATURE=true (NOT recommended for production).",
+            )
+            return False
+
+        if insecure_no_sig and not self._webhook_url:
+            logger.warning(
+                "[sms] SMS_INSECURE_NO_SIGNATURE=true — Twilio signature validation "
+                "is DISABLED. Any client that can reach port %d can inject messages. "
+                "Do NOT use this in production.",
+                self._webhook_port,
+            )
+
+        app = web.Application()
+        app.router.add_post("/webhooks/twilio", self._handle_webhook)
+        app.router.add_get("/health", lambda _: web.Response(text="ok"))
+
+        self._runner = web.AppRunner(app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, self._webhook_host, self._webhook_port)
+        await site.start()
+        self._http_session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30),
+        )
+        self._running = True
+
+        logger.info(
+            "[sms] Twilio webhook server listening on %s:%d, from: %s",
+            self._webhook_host,
+            self._webhook_port,
+            redact_phone(self._from_number),
+        )
+        return True
+
+    async def disconnect(self) -> None:
+        if self._http_session:
+            await self._http_session.close()
+            self._http_session = None
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+        self._running = False
+        logger.info("[sms] Disconnected")
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        import aiohttp
+
+        formatted = self.format_message(content)
+        chunks = self.truncate_message(formatted)
+        last_result = SendResult(success=True)
+
+        url = f"{TWILIO_API_BASE}/{self._account_sid}/Messages.json"
+        headers = {
+            "Authorization": self._basic_auth_header(),
+        }
+
+        session = self._http_session or aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=30),
+        )
+        try:
+            for chunk in chunks:
+                form_data = aiohttp.FormData()
+                form_data.add_field("From", self._from_number)
+                form_data.add_field("To", chat_id)
+                form_data.add_field("Body", chunk)
+
+                try:
+                    async with session.post(url, data=form_data, headers=headers) as resp:
+                        body = await resp.json()
+                        if resp.status >= 400:
+                            error_msg = body.get("message", str(body))
+                            logger.error(
+                                "[sms] send failed to %s: %s %s",
+                                redact_phone(chat_id),
+                                resp.status,
+                                error_msg,
+                            )
+                            return SendResult(
+                                success=False,
+                                error=f"Twilio {resp.status}: {error_msg}",
+                            )
+                        msg_sid = body.get("sid", "")
+                        last_result = SendResult(success=True, message_id=msg_sid)
+                except Exception as e:
+                    logger.error("[sms] send error to %s: %s", redact_phone(chat_id), e)
+                    return SendResult(success=False, error=str(e))
+        finally:
+            # Close session only if we created a fallback (no persistent session)
+            if not self._http_session and session:
+                await session.close()
+
+        return last_result
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        return {"name": chat_id, "type": "dm"}
+
+    # ------------------------------------------------------------------
+    # SMS-specific formatting
+    # ------------------------------------------------------------------
+
+    def format_message(self, content: str) -> str:
+        """Strip markdown — SMS renders it as literal characters."""
+        return strip_markdown(content)
+
+    # ------------------------------------------------------------------
+    # Twilio signature validation
+    # ------------------------------------------------------------------
+
+    def _validate_twilio_signature(
+        self, url: str, post_params: dict, signature: str,
+    ) -> bool:
+        """Validate ``X-Twilio-Signature`` header (HMAC-SHA1, base64).
+
+        Tries both with and without the default port for the URL scheme,
+        since Twilio may sign with either variant.
+
+        Algorithm: https://www.twilio.com/docs/usage/security#validating-requests
+        """
+        if self._check_signature(url, post_params, signature):
+            return True
+
+        variant = self._port_variant_url(url)
+        if variant and self._check_signature(variant, post_params, signature):
+            return True
+
+        return False
+
+    def _check_signature(
+        self, url: str, post_params: dict, signature: str,
+    ) -> bool:
+        """Compute and compare a single Twilio signature."""
+        data_to_sign = url
+        for key in sorted(post_params.keys()):
+            data_to_sign += key + post_params[key]
+        mac = hmac.new(
+            self._auth_token.encode("utf-8"),
+            data_to_sign.encode("utf-8"),
+            hashlib.sha1,
+        )
+        computed = base64.b64encode(mac.digest()).decode("utf-8")
+        return hmac.compare_digest(computed, signature)
+
+    @staticmethod
+    def _port_variant_url(url: str) -> str | None:
+        """Return the URL with the default port toggled, or None.
+
+        Only toggles default ports (443 for https, 80 for http).
+        Non-standard ports are never modified.
+        """
+        parsed = urllib.parse.urlparse(url)
+        default_ports = {"https": 443, "http": 80}
+        default_port = default_ports.get(parsed.scheme)
+        if default_port is None:
+            return None
+
+        if parsed.port == default_port:
+            # Has explicit default port → strip it
+            return urllib.parse.urlunparse(
+                (parsed.scheme, parsed.hostname, parsed.path,
+                 parsed.params, parsed.query, parsed.fragment)
+            )
+        elif parsed.port is None:
+            # No port → add default
+            netloc = f"{parsed.hostname}:{default_port}"
+            return urllib.parse.urlunparse(
+                (parsed.scheme, netloc, parsed.path,
+                 parsed.params, parsed.query, parsed.fragment)
+            )
+
+        # Non-standard port — no variant
+        return None
+
+    # ------------------------------------------------------------------
+    # Twilio webhook handler
+    # ------------------------------------------------------------------
+
+    async def _handle_webhook(self, request) -> "aiohttp.web.Response":
+        from aiohttp import web
+
+        try:
+            raw = await request.read()
+            # Twilio sends form-encoded data, not JSON
+            form = urllib.parse.parse_qs(raw.decode("utf-8"), keep_blank_values=True)
+        except Exception as e:
+            logger.error("[sms] webhook parse error: %s", e)
+            return web.Response(
+                text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+                content_type="application/xml",
+                status=400,
+            )
+
+        # Validate Twilio request signature when SMS_WEBHOOK_URL is configured
+        if self._webhook_url:
+            twilio_sig = request.headers.get("X-Twilio-Signature", "")
+            if not twilio_sig:
+                logger.warning("[sms] Rejected: missing X-Twilio-Signature header")
+                return web.Response(
+                    text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+                    content_type="application/xml",
+                    status=403,
+                )
+            flat_params = {k: v[0] for k, v in form.items() if v}
+            if not self._validate_twilio_signature(
+                self._webhook_url, flat_params, twilio_sig
+            ):
+                logger.warning("[sms] Rejected: invalid Twilio signature")
+                return web.Response(
+                    text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+                    content_type="application/xml",
+                    status=403,
+                )
+
+        # Extract fields (parse_qs returns lists)
+        from_number = (form.get("From", [""]))[0].strip()
+        to_number = (form.get("To", [""]))[0].strip()
+        text = (form.get("Body", [""]))[0].strip()
+        message_sid = (form.get("MessageSid", [""]))[0].strip()
+
+        if not from_number or not text:
+            return web.Response(
+                text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+                content_type="application/xml",
+            )
+
+        # Ignore messages from our own number (echo prevention)
+        if from_number == self._from_number:
+            logger.debug("[sms] ignoring echo from own number %s", redact_phone(from_number))
+            return web.Response(
+                text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+                content_type="application/xml",
+            )
+
+        logger.info(
+            "[sms] inbound from %s -> %s: %s",
+            redact_phone(from_number),
+            redact_phone(to_number),
+            text[:80],
+        )
+
+        source = self.build_source(
+            chat_id=from_number,
+            chat_name=from_number,
+            chat_type="dm",
+            user_id=from_number,
+            user_name=from_number,
+        )
+        event = MessageEvent(
+            text=text,
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=form,
+            message_id=message_sid,
+        )
+
+        # Non-blocking: Twilio expects a fast response
+        task = asyncio.create_task(self.handle_message(event))
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+        # Return empty TwiML — we send replies via the REST API, not inline TwiML
+        return web.Response(
+            text='<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
+            content_type="application/xml",
+        )

mindcli/_vendor/gateway/platforms/telegram_network.py

@@ -0,0 +1,246 @@
+"""Telegram-specific network helpers.
+
+Provides a hostname-preserving fallback transport for networks where
+api.telegram.org resolves to an endpoint that is unreachable from the current
+host. The transport keeps the logical request host and TLS SNI as
+api.telegram.org while retrying the TCP connection against one or more fallback
+IPv4 addresses.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import logging
+import socket
+from typing import Iterable, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_TELEGRAM_API_HOST = "api.telegram.org"
+
+# DNS-over-HTTPS providers used to discover Telegram API IPs that may differ
+# from the (potentially unreachable) IP returned by the local system resolver.
+_DOH_TIMEOUT = 4.0  # seconds — bounded so connect() isn't noticeably delayed
+
+_DOH_PROVIDERS: list[dict] = [
+    {
+        "url": "https://dns.google/resolve",
+        "params": {"name": _TELEGRAM_API_HOST, "type": "A"},
+        "headers": {},
+    },
+    {
+        "url": "https://cloudflare-dns.com/dns-query",
+        "params": {"name": _TELEGRAM_API_HOST, "type": "A"},
+        "headers": {"Accept": "application/dns-json"},
+    },
+]
+
+# Last-resort IPs when DoH is also blocked.  These are stable Telegram Bot API
+# endpoints in the 149.154.160.0/20 block (same seed used by OpenClaw).
+_SEED_FALLBACK_IPS: list[str] = ["149.154.167.220"]
+
+
+def _resolve_proxy_url() -> str | None:
+    # Delegate to shared implementation (env vars + macOS system proxy detection)
+    from gateway.platforms.base import resolve_proxy_url
+    return resolve_proxy_url()
+
+
+class TelegramFallbackTransport(httpx.AsyncBaseTransport):
+    """Retry Telegram Bot API requests via fallback IPs while preserving TLS/SNI.
+
+    Requests continue to target https://api.telegram.org/... logically, but on
+    connect failures the underlying TCP connection is retried against a known
+    reachable IP. This is effectively the programmatic equivalent of
+    ``curl --resolve api.telegram.org:443:<ip>``.
+    """
+
+    def __init__(self, fallback_ips: Iterable[str], **transport_kwargs):
+        self._fallback_ips = [ip for ip in dict.fromkeys(_normalize_fallback_ips(fallback_ips))]
+        proxy_url = _resolve_proxy_url()
+        if proxy_url and "proxy" not in transport_kwargs:
+            transport_kwargs["proxy"] = proxy_url
+        self._primary = httpx.AsyncHTTPTransport(**transport_kwargs)
+        self._fallbacks = {
+            ip: httpx.AsyncHTTPTransport(**transport_kwargs) for ip in self._fallback_ips
+        }
+        self._sticky_ip: Optional[str] = None
+        self._sticky_lock = asyncio.Lock()
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        if request.url.host != _TELEGRAM_API_HOST or not self._fallback_ips:
+            return await self._primary.handle_async_request(request)
+
+        sticky_ip = self._sticky_ip
+        attempt_order: list[Optional[str]] = [sticky_ip] if sticky_ip else [None]
+        for ip in self._fallback_ips:
+            if ip != sticky_ip:
+                attempt_order.append(ip)
+
+        last_error: Exception | None = None
+        for ip in attempt_order:
+            candidate = request if ip is None else _rewrite_request_for_ip(request, ip)
+            transport = self._primary if ip is None else self._fallbacks[ip]
+            try:
+                response = await transport.handle_async_request(candidate)
+                if ip is not None and self._sticky_ip != ip:
+                    async with self._sticky_lock:
+                        if self._sticky_ip != ip:
+                            self._sticky_ip = ip
+                            logger.warning(
+                                "[Telegram] Primary api.telegram.org path unreachable; using sticky fallback IP %s",
+                                ip,
+                            )
+                return response
+            except Exception as exc:
+                last_error = exc
+                if not _is_retryable_connect_error(exc):
+                    raise
+                if ip is None:
+                    logger.warning(
+                        "[Telegram] Primary api.telegram.org connection failed (%s); trying fallback IPs %s",
+                        exc,
+                        ", ".join(self._fallback_ips),
+                    )
+                    continue
+                logger.warning("[Telegram] Fallback IP %s failed: %s", ip, exc)
+                continue
+
+        if last_error is None:
+            raise RuntimeError("All Telegram fallback IPs exhausted but no error was recorded")
+        raise last_error
+
+    async def aclose(self) -> None:
+        await self._primary.aclose()
+        for transport in self._fallbacks.values():
+            await transport.aclose()
+
+
+def _normalize_fallback_ips(values: Iterable[str]) -> list[str]:
+    normalized: list[str] = []
+    for value in values:
+        raw = str(value).strip()
+        if not raw:
+            continue
+        try:
+            addr = ipaddress.ip_address(raw)
+        except ValueError:
+            logger.warning("Ignoring invalid Telegram fallback IP: %r", raw)
+            continue
+        if addr.version != 4:
+            logger.warning("Ignoring non-IPv4 Telegram fallback IP: %s", raw)
+            continue
+        if addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_unspecified:
+            logger.warning("Ignoring private/internal Telegram fallback IP: %s", raw)
+            continue
+        normalized.append(str(addr))
+    return normalized
+
+
+def parse_fallback_ip_env(value: str | None) -> list[str]:
+    if not value:
+        return []
+    parts = [part.strip() for part in value.split(",")]
+    return _normalize_fallback_ips(parts)
+
+
+def _resolve_system_dns() -> set[str]:
+    """Return the IPv4 addresses that the OS resolver gives for api.telegram.org."""
+    try:
+        results = socket.getaddrinfo(_TELEGRAM_API_HOST, 443, socket.AF_INET)
+        return {addr[4][0] for addr in results}
+    except Exception:
+        return set()
+
+
+async def _query_doh_provider(
+    client: httpx.AsyncClient, provider: dict
+) -> list[str]:
+    """Query one DoH provider and return A-record IPs."""
+    try:
+        resp = await client.get(
+            provider["url"], params=provider["params"], headers=provider["headers"]
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        ips: list[str] = []
+        for answer in data.get("Answer", []):
+            if answer.get("type") != 1:  # A record
+                continue
+            raw = answer.get("data", "").strip()
+            try:
+                ipaddress.ip_address(raw)
+                ips.append(raw)
+            except ValueError:
+                continue
+        return ips
+    except Exception as exc:
+        logger.debug("DoH query to %s failed: %s", provider["url"], exc)
+        return []
+
+
+async def discover_fallback_ips() -> list[str]:
+    """Auto-discover Telegram API IPs via DNS-over-HTTPS.
+
+    Resolves api.telegram.org through Google and Cloudflare DoH, collects all
+    unique IPs, and excludes the system-DNS-resolved IP (which is presumably
+    unreachable on this network).  Falls back to a hardcoded seed list when DoH
+    is also unavailable.
+    """
+    async with httpx.AsyncClient(timeout=httpx.Timeout(_DOH_TIMEOUT)) as client:
+        doh_tasks = [_query_doh_provider(client, p) for p in _DOH_PROVIDERS]
+        system_dns_task = asyncio.to_thread(_resolve_system_dns)
+        results = await asyncio.gather(system_dns_task, *doh_tasks, return_exceptions=True)
+
+    # results[0] = system DNS IPs (set), results[1:] = DoH IP lists
+    system_ips: set[str] = results[0] if isinstance(results[0], set) else set()
+
+    doh_ips: list[str] = []
+    for r in results[1:]:
+        if isinstance(r, list):
+            doh_ips.extend(r)
+
+    # Deduplicate preserving order, exclude system-DNS IPs
+    seen: set[str] = set()
+    candidates: list[str] = []
+    for ip in doh_ips:
+        if ip not in seen and ip not in system_ips:
+            seen.add(ip)
+            candidates.append(ip)
+
+    # Validate through existing normalization
+    validated = _normalize_fallback_ips(candidates)
+
+    if validated:
+        logger.debug("Discovered Telegram fallback IPs via DoH: %s", ", ".join(validated))
+        return validated
+
+    logger.info(
+        "DoH discovery yielded no new IPs (system DNS: %s); using seed fallback IPs %s",
+        ", ".join(system_ips) or "unknown",
+        ", ".join(_SEED_FALLBACK_IPS),
+    )
+    return list(_SEED_FALLBACK_IPS)
+
+
+def _rewrite_request_for_ip(request: httpx.Request, ip: str) -> httpx.Request:
+    original_host = request.url.host or _TELEGRAM_API_HOST
+    url = request.url.copy_with(host=ip)
+    headers = request.headers.copy()
+    headers["host"] = original_host
+    extensions = dict(request.extensions)
+    extensions["sni_hostname"] = original_host
+    return httpx.Request(
+        method=request.method,
+        url=url,
+        headers=headers,
+        stream=request.stream,
+        extensions=extensions,
+    )
+
+
+def _is_retryable_connect_error(exc: Exception) -> bool:
+    return isinstance(exc, (httpx.ConnectTimeout, httpx.ConnectError))

mindcli/_vendor/gateway/platforms/voice2md_atoms.py

@@ -0,0 +1,136 @@
+"""
+voice2md_atoms.py — Voice2MD 共享原子层
+
+Spec 来源: docs/SPEC_voice2md_atomization_design.md §九
+提取自: mindos_sse.py._runOssTranscribePipeline (管线A)
+        dashscope_realtime._finalize (管线B)
+
+共享原子:
+  ④ persist_audio_result()  — 统一 DB 持久化
+  ⑤ push_md_appended()      — 统一 SSE 推送
+"""
+
+import json
+import logging
+
+logger = logging.getLogger("voice2md_atoms")
+
+
+# ─── ④ db_persist: 统一音频结果持久化 ─────────────────────────
+
+def persist_audio_result(
+    chat_id: str,
+    user_id: str,
+    file_name: str,
+    md_path: str,
+    chars: int,
+    md_content: str,
+    oss_read_url: str = "",
+) -> None:
+    """将音频转写结果写入 SessionDB。
+
+    管线 A (Import) 和管线 B (Live) 共用此函数。
+    payload 结构统一为 {type:"audio", fileName, mdPath, chars, ossReadUrl, mdContent}。
+
+    Raises:
+        不抛出异常。失败仅 logger.warning。
+    """
+    try:
+        from hermes_state import SessionDB  # type: ignore
+        db = SessionDB()
+        db.create_session(
+            session_id=chat_id, source="mindos",
+            user_id=user_id, model="audio",
+        )
+        db.append_message(
+            session_id=chat_id,
+            role="assistant",
+            content=json.dumps({
+                "type":       "audio",
+                "fileName":   file_name,
+                "mdPath":     md_path,
+                "chars":      chars,
+                "ossReadUrl": oss_read_url,
+                "mdContent":  md_content,
+            }, ensure_ascii=False),
+        )
+        logger.info("[voice2md] DB persist ok chatId=%s chars=%d", chat_id, chars)
+    except Exception as e:
+        logger.warning("[voice2md] DB persist failed (non-fatal): %s", e)
+
+
+# ─── ⑤ sse_push: 统一 SSE md:appended 推送 ──────────────────
+
+def push_md_appended(
+    sse_server,
+    user_id: str,
+    chat_id: str,
+    file: str,
+    chars: int,
+    md_content: str,
+    message: str = "",
+    source: str = "mic",
+) -> None:
+    """推送 SSE md:appended 事件到前端。
+
+    管线 A 和管线 B 共用此函数。
+    chars=0 时跳过推送（无内容不扰前端）。
+
+    Args:
+        sse_server: MindOSSSEServer 实例（具有 _pushEvent 方法）。
+                    管线 A 传 self，管线 B 传 _sse_server 模块级变量。
+        source: 音频来源标识（"mic" 或 "system"），前端据此区分气泡类型。
+    """
+    if chars == 0:
+        logger.info("[voice2md] 无转写内容，跳过 SSE 推送 chatId=%s", chat_id)
+        return
+
+    if not sse_server:
+        logger.warning("[voice2md] SSE push 跳过: sse_server 未注入")
+        return
+
+    if not message:
+        message = f"✅ 转写完成（{chars} 字）"
+
+    try:
+        sse_server._pushEvent(user_id, "md:appended", {
+            "chatId":    chat_id,
+            "file":      file,
+            "chars":     chars,
+            "mdContent": md_content,
+            "message":   message,
+            "source":    source,
+        })
+        logger.info("[voice2md] SSE md:appended pushed userId=%s chars=%d source=%s", user_id, chars, source)
+    except Exception as e:
+        logger.warning("[voice2md] SSE push failed: %s", e)
+
+
+# ─── ASR 积分扣减（管线 A/B 各自计费方式不同，不统一） ─────────
+
+def deduct_asr_credits(
+    user_id: str,
+    chat_id: str,
+    credits: int,
+    tx_type: str,
+    model: str,
+    seconds: float,
+) -> None:
+    """ASR 积分扣减。管线 A 和 B 调用时传不同的 tx_type 和 model。"""
+    try:
+        from hermes_state import SessionDB  # type: ignore
+        db = SessionDB()
+        db.deduct_credits(
+            user_id=user_id,
+            credits=credits,
+            tx_type=tx_type,
+            session_id=chat_id,
+            model=model,
+            raw_metric=json.dumps({"seconds": round(seconds, 1)}),
+        )
+        logger.info(
+            "[ASR Cost] userId=%s model=%s type=%s seconds=%.1f credits=%d chatId=%s",
+            user_id, model, tx_type, seconds, credits, chat_id,
+        )
+    except Exception as e:
+        logger.warning("[voice2md] credit deduction failed: %s", e)

mindcli/_vendor/gateway/platforms/voice_import.py

@@ -0,0 +1,99 @@
+"""
+voice_import.py — Voice2MD 管线 A：离线导入（原子组合器）
+
+Spec 来源: docs/SPEC_voice2md_atomization_design.md §二
+提取自: mindos_sse.py._runOssTranscribePipeline() 82 行 → 本文件 ~30 行编排
+
+原子组合:
+  ⑦ asr_batch   (flash_asr.transcribe_from_oss_url)
+  ⑧ md_writer   (md_converter.MdConverter)
+  ④ db_persist  (voice2md_atoms.persist_audio_result)
+  ⑤ sse_push    (voice2md_atoms.push_md_appended)
+  + 积分扣减    (voice2md_atoms.deduct_asr_credits)
+"""
+
+import json
+import logging
+import os
+
+logger = logging.getLogger("voice_import")
+
+
+async def run(
+    *,
+    sse_server,
+    user_id: str,
+    chat_id: str,
+    read_url: str,
+    oss_key: str,
+    title: str,
+) -> None:
+    """离线音频文件 → Markdown。管线只做编排，不做逻辑。
+
+    调用方: mindos_sse.py 的音频转写路由，通过 asyncio.create_task(voice_import.run(...))
+    """
+    from flash_asr import transcribe_from_oss_url      # type: ignore  ⑦ asr_batch
+    from md_converter import MdConverter                # type: ignore  ⑧ md_writer
+    from voice2md_atoms import (                        # type: ignore  ④⑤ 共享终点
+        persist_audio_result, push_md_appended, deduct_asr_credits,
+    )
+
+    wiki_root = os.getenv("MINDOS_WIKI_DIR", os.path.expanduser("~/.hermes/wiki"))
+    wiki_dir  = os.path.join(wiki_root, user_id)
+    converter = MdConverter(wiki_dir)
+
+    original_filename = oss_key.split("/")[-1]
+
+    # 进度推送：开始
+    sse_server._pushEvent(user_id, "md:progress", {
+        "chatId": chat_id, "stage": "asr_start", "filename": original_filename,
+    })
+
+    # ⑧ md_writer: 创建文件
+    md_file     = converter.new_file(title=title, source_filename=original_filename)
+    total_chars = 0
+    last_offset_ms = 0
+
+    # ⑦ asr_batch: paraformer-v2 异步转写
+    async for seg in transcribe_from_oss_url(read_url):
+        if seg.get("text"):
+            offset_ms = seg.get("begin_ms", 0)
+            if offset_ms > last_offset_ms:
+                last_offset_ms = offset_ms
+            total_chars += converter.append_segment(
+                md_file, seg["text"], offset_ms=offset_ms,
+            )
+
+    # ⑧ md_writer: 写结束标记
+    converter.finalize(md_file, char_count=total_chars)
+    rel_path = converter.relative_path(md_file)
+
+    # 积分扣减
+    audio_seconds = last_offset_ms / 1000.0
+    asr_credits = max(1, int(audio_seconds))
+    deduct_asr_credits(
+        user_id=user_id, chat_id=chat_id, credits=asr_credits,
+        tx_type="asr_file", model="paraformer-v2", seconds=audio_seconds,
+    )
+
+    # 读取完整 MD 内容
+    md_content = ""
+    try:
+        md_content = md_file.read_text(encoding="utf-8")
+    except Exception:
+        pass
+
+    # ④ db_persist
+    persist_audio_result(
+        chat_id=chat_id, user_id=user_id,
+        file_name=title, md_path=rel_path,
+        chars=total_chars, md_content=md_content,
+        oss_read_url=read_url,
+    )
+
+    # ⑤ sse_push
+    push_md_appended(
+        sse_server=sse_server, user_id=user_id, chat_id=chat_id,
+        file=rel_path, chars=total_chars, md_content=md_content,
+        message=f"✅ 会议记录已入库：{md_file.name}（{total_chars} 字）",
+    )

mindcli/_vendor/gateway/platforms/webhook.py

@@ -0,0 +1,672 @@
+"""Generic webhook platform adapter.
+
+Runs an aiohttp HTTP server that receives webhook POSTs from external
+services (GitHub, GitLab, JIRA, Stripe, etc.), validates HMAC signatures,
+transforms payloads into agent prompts, and routes responses back to the
+source or to another configured platform.
+
+Configuration lives in config.yaml under platforms.webhook.extra.routes.
+Each route defines:
+  - events: which event types to accept (header-based filtering)
+  - secret: HMAC secret for signature validation (REQUIRED)
+  - prompt: template string formatted with the webhook payload
+  - skills: optional list of skills to load for the agent
+  - deliver: where to send the response (github_comment, telegram, etc.)
+  - deliver_extra: additional delivery config (repo, pr_number, chat_id)
+
+Security:
+  - HMAC secret is required per route (validated at startup)
+  - Rate limiting per route (fixed-window, configurable)
+  - Idempotency cache prevents duplicate agent runs on webhook retries
+  - Body size limits checked before reading payload
+  - Set secret to "INSECURE_NO_AUTH" to skip validation (testing only)
+"""
+
+import asyncio
+import hashlib
+import hmac
+import json
+import logging
+import re
+import subprocess
+import time
+from typing import Any, Dict, List, Optional
+
+try:
+    from aiohttp import web
+
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    AIOHTTP_AVAILABLE = False
+    web = None  # type: ignore[assignment]
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8644
+_INSECURE_NO_AUTH = "INSECURE_NO_AUTH"
+_DYNAMIC_ROUTES_FILENAME = "webhook_subscriptions.json"
+
+
+def check_webhook_requirements() -> bool:
+    """Check if webhook adapter dependencies are available."""
+    return AIOHTTP_AVAILABLE
+
+
+class WebhookAdapter(BasePlatformAdapter):
+    """Generic webhook receiver that triggers agent runs from HTTP POSTs."""
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.WEBHOOK)
+        self._host: str = config.extra.get("host", DEFAULT_HOST)
+        self._port: int = int(config.extra.get("port", DEFAULT_PORT))
+        self._global_secret: str = config.extra.get("secret", "")
+        self._static_routes: Dict[str, dict] = config.extra.get("routes", {})
+        self._dynamic_routes: Dict[str, dict] = {}
+        self._dynamic_routes_mtime: float = 0.0
+        self._routes: Dict[str, dict] = dict(self._static_routes)
+        self._runner = None
+
+        # Delivery info keyed by session chat_id.
+        #
+        # Read by every send() invocation for the chat_id (status messages
+        # AND the final response).  Cleaned up via TTL on each POST so the
+        # dict stays bounded — see _prune_delivery_info().  Do NOT pop on
+        # send(), or interim status messages (e.g. fallback notifications,
+        # context-pressure warnings) will consume the entry before the
+        # final response arrives, causing the response to silently fall
+        # back to the "log" deliver type.
+        self._delivery_info: Dict[str, dict] = {}
+        self._delivery_info_created: Dict[str, float] = {}
+
+        # Reference to gateway runner for cross-platform delivery (set externally)
+        self.gateway_runner = None
+
+        # Idempotency: TTL cache of recently processed delivery IDs.
+        # Prevents duplicate agent runs when webhook providers retry.
+        self._seen_deliveries: Dict[str, float] = {}
+        self._idempotency_ttl: int = 3600  # 1 hour
+
+        # Rate limiting: per-route timestamps in a fixed window.
+        self._rate_counts: Dict[str, List[float]] = {}
+        self._rate_limit: int = int(config.extra.get("rate_limit", 30))  # per minute
+
+        # Body size limit (auth-before-body pattern)
+        self._max_body_bytes: int = int(
+            config.extra.get("max_body_bytes", 1_048_576)
+        )  # 1MB
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        # Load agent-created subscriptions before validating
+        self._reload_dynamic_routes()
+
+        # Validate routes at startup — secret is required per route
+        for name, route in self._routes.items():
+            secret = route.get("secret", self._global_secret)
+            if not secret:
+                raise ValueError(
+                    f"[webhook] Route '{name}' has no HMAC secret. "
+                    f"Set 'secret' on the route or globally. "
+                    f"For testing without auth, set secret to '{_INSECURE_NO_AUTH}'."
+                )
+
+        app = web.Application()
+        app.router.add_get("/health", self._handle_health)
+        app.router.add_post("/webhooks/{route_name}", self._handle_webhook)
+
+        # Port conflict detection — fail fast if port is already in use
+        import socket as _socket
+        try:
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
+                _s.settimeout(1)
+                _s.connect(('127.0.0.1', self._port))
+            logger.error('[webhook] Port %d already in use. Set a different port in config.yaml: platforms.webhook.port', self._port)
+            return False
+        except (ConnectionRefusedError, OSError):
+            pass  # port is free
+
+        self._runner = web.AppRunner(app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, self._host, self._port)
+        await site.start()
+        self._mark_connected()
+
+        route_names = ", ".join(self._routes.keys()) or "(none configured)"
+        logger.info(
+            "[webhook] Listening on %s:%d — routes: %s",
+            self._host,
+            self._port,
+            route_names,
+        )
+        return True
+
+    async def disconnect(self) -> None:
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+        self._mark_disconnected()
+        logger.info("[webhook] Disconnected")
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        """Deliver the agent's response to the configured destination.
+
+        chat_id is ``webhook:{route}:{delivery_id}``.  The delivery info
+        stored during webhook receipt is read with ``.get()`` (not popped)
+        so that interim status messages emitted before the final response
+        — fallback-model notifications, context-pressure warnings, etc. —
+        do not consume the entry and silently downgrade the final response
+        to the ``log`` deliver type.  TTL cleanup happens on POST.
+        """
+        delivery = self._delivery_info.get(chat_id, {})
+        deliver_type = delivery.get("deliver", "log")
+
+        if deliver_type == "log":
+            logger.info("[webhook] Response for %s: %s", chat_id, content[:200])
+            return SendResult(success=True)
+
+        if deliver_type == "github_comment":
+            return await self._deliver_github_comment(content, delivery)
+
+        # Cross-platform delivery — any platform with a gateway adapter
+        if self.gateway_runner and deliver_type in (
+            "telegram",
+            "discord",
+            "slack",
+            "signal",
+            "sms",
+            "whatsapp",
+            "matrix",
+            "mattermost",
+            "homeassistant",
+            "email",
+            "dingtalk",
+            "feishu",
+            "wecom",
+            "wecom_callback",
+            "weixin",
+            "bluebubbles",
+            "qqbot",
+        ):
+            return await self._deliver_cross_platform(
+                deliver_type, content, delivery
+            )
+
+        logger.warning("[webhook] Unknown deliver type: %s", deliver_type)
+        return SendResult(
+            success=False, error=f"Unknown deliver type: {deliver_type}"
+        )
+
+    def _prune_delivery_info(self, now: float) -> None:
+        """Drop delivery_info entries older than the idempotency TTL.
+
+        Mirrors the cleanup pattern used for ``_seen_deliveries``.  Called
+        on each POST so the dict size is bounded by ``rate_limit * TTL``
+        even if many webhooks fire and never receive a final response.
+        """
+        cutoff = now - self._idempotency_ttl
+        stale = [
+            k
+            for k, t in self._delivery_info_created.items()
+            if t < cutoff
+        ]
+        for k in stale:
+            self._delivery_info.pop(k, None)
+            self._delivery_info_created.pop(k, None)
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        return {"name": chat_id, "type": "webhook"}
+
+    # ------------------------------------------------------------------
+    # HTTP handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_health(self, request: "web.Request") -> "web.Response":
+        """GET /health — simple health check."""
+        return web.json_response({"status": "ok", "platform": "webhook"})
+
+    def _reload_dynamic_routes(self) -> None:
+        """Reload agent-created subscriptions from disk if the file changed."""
+        from hermes_constants import get_hermes_home
+        hermes_home = get_hermes_home()
+        subs_path = hermes_home / _DYNAMIC_ROUTES_FILENAME
+        if not subs_path.exists():
+            if self._dynamic_routes:
+                self._dynamic_routes = {}
+                self._routes = dict(self._static_routes)
+                logger.debug("[webhook] Dynamic subscriptions file removed, cleared dynamic routes")
+            return
+        try:
+            mtime = subs_path.stat().st_mtime
+            if mtime <= self._dynamic_routes_mtime:
+                return  # No change
+            data = json.loads(subs_path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return
+            # Merge: static routes take precedence over dynamic ones
+            self._dynamic_routes = {
+                k: v for k, v in data.items()
+                if k not in self._static_routes
+            }
+            self._routes = {**self._dynamic_routes, **self._static_routes}
+            self._dynamic_routes_mtime = mtime
+            logger.info(
+                "[webhook] Reloaded %d dynamic route(s): %s",
+                len(self._dynamic_routes),
+                ", ".join(self._dynamic_routes.keys()) or "(none)",
+            )
+        except Exception as e:
+            logger.error("[webhook] Failed to reload dynamic routes: %s", e)
+
+    async def _handle_webhook(self, request: "web.Request") -> "web.Response":
+        """POST /webhooks/{route_name} — receive and process a webhook event."""
+        # Hot-reload dynamic subscriptions on each request (mtime-gated, cheap)
+        self._reload_dynamic_routes()
+
+        route_name = request.match_info.get("route_name", "")
+        route_config = self._routes.get(route_name)
+
+        if not route_config:
+            return web.json_response(
+                {"error": f"Unknown route: {route_name}"}, status=404
+            )
+
+        # ── Auth-before-body ─────────────────────────────────────
+        # Check Content-Length before reading the full payload.
+        content_length = request.content_length or 0
+        if content_length > self._max_body_bytes:
+            return web.json_response(
+                {"error": "Payload too large"}, status=413
+            )
+
+        # ── Rate limiting ────────────────────────────────────────
+        now = time.time()
+        window = self._rate_counts.setdefault(route_name, [])
+        window[:] = [t for t in window if now - t < 60]
+        if len(window) >= self._rate_limit:
+            return web.json_response(
+                {"error": "Rate limit exceeded"}, status=429
+            )
+        window.append(now)
+
+        # Read body
+        try:
+            raw_body = await request.read()
+        except Exception as e:
+            logger.error("[webhook] Failed to read body: %s", e)
+            return web.json_response({"error": "Bad request"}, status=400)
+
+        # Validate HMAC signature (skip for INSECURE_NO_AUTH testing mode)
+        secret = route_config.get("secret", self._global_secret)
+        if secret and secret != _INSECURE_NO_AUTH:
+            if not self._validate_signature(request, raw_body, secret):
+                logger.warning(
+                    "[webhook] Invalid signature for route %s", route_name
+                )
+                return web.json_response(
+                    {"error": "Invalid signature"}, status=401
+                )
+
+        # Parse payload
+        try:
+            payload = json.loads(raw_body)
+        except json.JSONDecodeError:
+            # Try form-encoded as fallback
+            try:
+                import urllib.parse
+
+                payload = dict(
+                    urllib.parse.parse_qsl(raw_body.decode("utf-8"))
+                )
+            except Exception:
+                return web.json_response(
+                    {"error": "Cannot parse body"}, status=400
+                )
+
+        # Check event type filter
+        event_type = (
+            request.headers.get("X-GitHub-Event", "")
+            or request.headers.get("X-GitLab-Event", "")
+            or payload.get("event_type", "")
+            or "unknown"
+        )
+        allowed_events = route_config.get("events", [])
+        if allowed_events and event_type not in allowed_events:
+            logger.debug(
+                "[webhook] Ignoring event %s for route %s (allowed: %s)",
+                event_type,
+                route_name,
+                allowed_events,
+            )
+            return web.json_response(
+                {"status": "ignored", "event": event_type}
+            )
+
+        # Format prompt from template
+        prompt_template = route_config.get("prompt", "")
+        prompt = self._render_prompt(
+            prompt_template, payload, event_type, route_name
+        )
+
+        # Inject skill content if configured.
+        # We call build_skill_invocation_message() directly rather than
+        # using /skill-name slash commands — the gateway's command parser
+        # would intercept those and break the flow.
+        skills = route_config.get("skills", [])
+        if skills:
+            try:
+                from agent.skill_commands import (
+                    build_skill_invocation_message,
+                    get_skill_commands,
+                )
+
+                skill_cmds = get_skill_commands()
+                for skill_name in skills:
+                    cmd_key = f"/{skill_name}"
+                    if cmd_key in skill_cmds:
+                        skill_content = build_skill_invocation_message(
+                            cmd_key, user_instruction=prompt
+                        )
+                        if skill_content:
+                            prompt = skill_content
+                            break  # Load the first matching skill
+                    else:
+                        logger.warning(
+                            "[webhook] Skill '%s' not found", skill_name
+                        )
+            except Exception as e:
+                logger.warning("[webhook] Skill loading failed: %s", e)
+
+        # Build a unique delivery ID
+        delivery_id = request.headers.get(
+            "X-GitHub-Delivery",
+            request.headers.get("X-Request-ID", str(int(time.time() * 1000))),
+        )
+
+        # ── Idempotency ─────────────────────────────────────────
+        # Skip duplicate deliveries (webhook retries).
+        now = time.time()
+        # Prune expired entries
+        self._seen_deliveries = {
+            k: v
+            for k, v in self._seen_deliveries.items()
+            if now - v < self._idempotency_ttl
+        }
+        if delivery_id in self._seen_deliveries:
+            logger.info(
+                "[webhook] Skipping duplicate delivery %s", delivery_id
+            )
+            return web.json_response(
+                {"status": "duplicate", "delivery_id": delivery_id},
+                status=200,
+            )
+        self._seen_deliveries[delivery_id] = now
+
+        # Use delivery_id in session key so concurrent webhooks on the
+        # same route get independent agent runs (not queued/interrupted).
+        session_chat_id = f"webhook:{route_name}:{delivery_id}"
+
+        # Store delivery info for send().  Read by every send() invocation
+        # for this chat_id (interim status messages and the final response),
+        # so we do NOT pop on send.  TTL-based cleanup keeps the dict bounded.
+        deliver_config = {
+            "deliver": route_config.get("deliver", "log"),
+            "deliver_extra": self._render_delivery_extra(
+                route_config.get("deliver_extra", {}), payload
+            ),
+            "payload": payload,
+        }
+        self._delivery_info[session_chat_id] = deliver_config
+        self._delivery_info_created[session_chat_id] = now
+        self._prune_delivery_info(now)
+
+        # Build source and event
+        source = self.build_source(
+            chat_id=session_chat_id,
+            chat_name=f"webhook/{route_name}",
+            chat_type="webhook",
+            user_id=f"webhook:{route_name}",
+            user_name=route_name,
+        )
+        event = MessageEvent(
+            text=prompt,
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=payload,
+            message_id=delivery_id,
+        )
+
+        logger.info(
+            "[webhook] %s event=%s route=%s prompt_len=%d delivery=%s",
+            request.method,
+            event_type,
+            route_name,
+            len(prompt),
+            delivery_id,
+        )
+
+        # Non-blocking — return 202 Accepted immediately
+        task = asyncio.create_task(self.handle_message(event))
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+
+        return web.json_response(
+            {
+                "status": "accepted",
+                "route": route_name,
+                "event": event_type,
+                "delivery_id": delivery_id,
+            },
+            status=202,
+        )
+
+    # ------------------------------------------------------------------
+    # Signature validation
+    # ------------------------------------------------------------------
+
+    def _validate_signature(
+        self, request: "web.Request", body: bytes, secret: str
+    ) -> bool:
+        """Validate webhook signature (GitHub, GitLab, generic HMAC-SHA256)."""
+        # GitHub: X-Hub-Signature-256 = sha256=<hex>
+        gh_sig = request.headers.get("X-Hub-Signature-256", "")
+        if gh_sig:
+            expected = "sha256=" + hmac.new(
+                secret.encode(), body, hashlib.sha256
+            ).hexdigest()
+            return hmac.compare_digest(gh_sig, expected)
+
+        # GitLab: X-Gitlab-Token = <plain secret>
+        gl_token = request.headers.get("X-Gitlab-Token", "")
+        if gl_token:
+            return hmac.compare_digest(gl_token, secret)
+
+        # Generic: X-Webhook-Signature = <hex HMAC-SHA256>
+        generic_sig = request.headers.get("X-Webhook-Signature", "")
+        if generic_sig:
+            expected = hmac.new(
+                secret.encode(), body, hashlib.sha256
+            ).hexdigest()
+            return hmac.compare_digest(generic_sig, expected)
+
+        # No recognised signature header but secret is configured → reject
+        logger.debug(
+            "[webhook] Secret configured but no signature header found"
+        )
+        return False
+
+    # ------------------------------------------------------------------
+    # Prompt rendering
+    # ------------------------------------------------------------------
+
+    def _render_prompt(
+        self,
+        template: str,
+        payload: dict,
+        event_type: str,
+        route_name: str,
+    ) -> str:
+        """Render a prompt template with the webhook payload.
+
+        Supports dot-notation access into nested dicts:
+        ``{pull_request.title}`` → ``payload["pull_request"]["title"]``
+
+        Special token ``{__raw__}`` dumps the entire payload as indented
+        JSON (truncated to 4000 chars).  Useful for monitoring alerts or
+        any webhook where the agent needs to see the full payload.
+        """
+        if not template:
+            truncated = json.dumps(payload, indent=2)[:4000]
+            return (
+                f"Webhook event '{event_type}' on route "
+                f"'{route_name}':\n\n```json\n{truncated}\n```"
+            )
+
+        def _resolve(match: re.Match) -> str:
+            key = match.group(1)
+            # Special token: dump the entire payload as JSON
+            if key == "__raw__":
+                return json.dumps(payload, indent=2)[:4000]
+            value: Any = payload
+            for part in key.split("."):
+                if isinstance(value, dict):
+                    value = value.get(part, f"{{{key}}}")
+                else:
+                    return f"{{{key}}}"
+            if isinstance(value, (dict, list)):
+                return json.dumps(value, indent=2)[:2000]
+            return str(value)
+
+        return re.sub(r"\{([a-zA-Z0-9_.]+)\}", _resolve, template)
+
+    def _render_delivery_extra(
+        self, extra: dict, payload: dict
+    ) -> dict:
+        """Render delivery_extra template values with payload data."""
+        rendered: Dict[str, Any] = {}
+        for key, value in extra.items():
+            if isinstance(value, str):
+                rendered[key] = self._render_prompt(value, payload, "", "")
+            else:
+                rendered[key] = value
+        return rendered
+
+    # ------------------------------------------------------------------
+    # Response delivery
+    # ------------------------------------------------------------------
+
+    async def _deliver_github_comment(
+        self, content: str, delivery: dict
+    ) -> SendResult:
+        """Post agent response as a GitHub PR/issue comment via ``gh`` CLI."""
+        extra = delivery.get("deliver_extra", {})
+        repo = extra.get("repo", "")
+        pr_number = extra.get("pr_number", "")
+
+        if not repo or not pr_number:
+            logger.error(
+                "[webhook] github_comment delivery missing repo or pr_number"
+            )
+            return SendResult(
+                success=False, error="Missing repo or pr_number"
+            )
+
+        try:
+            result = subprocess.run(
+                [
+                    "gh",
+                    "pr",
+                    "comment",
+                    str(pr_number),
+                    "--repo",
+                    repo,
+                    "--body",
+                    content,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode == 0:
+                logger.info(
+                    "[webhook] Posted comment on %s#%s", repo, pr_number
+                )
+                return SendResult(success=True)
+            else:
+                logger.error(
+                    "[webhook] gh pr comment failed: %s", result.stderr
+                )
+                return SendResult(success=False, error=result.stderr)
+        except FileNotFoundError:
+            logger.error(
+                "[webhook] 'gh' CLI not found — install GitHub CLI for "
+                "github_comment delivery"
+            )
+            return SendResult(
+                success=False, error="gh CLI not installed"
+            )
+        except Exception as e:
+            logger.error("[webhook] github_comment delivery error: %s", e)
+            return SendResult(success=False, error=str(e))
+
+    async def _deliver_cross_platform(
+        self, platform_name: str, content: str, delivery: dict
+    ) -> SendResult:
+        """Route response to another platform (telegram, discord, etc.)."""
+        if not self.gateway_runner:
+            return SendResult(
+                success=False,
+                error="No gateway runner for cross-platform delivery",
+            )
+
+        try:
+            target_platform = Platform(platform_name)
+        except ValueError:
+            return SendResult(
+                success=False, error=f"Unknown platform: {platform_name}"
+            )
+
+        adapter = self.gateway_runner.adapters.get(target_platform)
+        if not adapter:
+            return SendResult(
+                success=False,
+                error=f"Platform {platform_name} not connected",
+            )
+
+        # Use home channel if no specific chat_id in deliver_extra
+        extra = delivery.get("deliver_extra", {})
+        chat_id = extra.get("chat_id", "")
+        if not chat_id:
+            home = self.gateway_runner.config.get_home_channel(target_platform)
+            if home:
+                chat_id = home.chat_id
+            else:
+                return SendResult(
+                    success=False,
+                    error=f"No chat_id or home channel for {platform_name}",
+                )
+
+        # Pass thread_id from deliver_extra so Telegram forum topics work
+        metadata = None
+        thread_id = extra.get("message_thread_id") or extra.get("thread_id")
+        if thread_id:
+            metadata = {"thread_id": thread_id}
+
+        return await adapter.send(chat_id, content, metadata=metadata)

mindcli/_vendor/gateway/platforms/wecom_callback.py

@@ -0,0 +1,387 @@
+"""WeCom callback-mode adapter for self-built enterprise applications.
+
+Unlike the bot/websocket adapter in ``wecom.py``, this handles the standard
+WeCom callback flow: WeCom POSTs encrypted XML to an HTTP endpoint, the
+adapter decrypts it, queues the message for the agent, and immediately
+acknowledges.  The agent's reply is delivered later via the proactive
+``message/send`` API using an access-token.
+
+Supports multiple self-built apps under one gateway instance, scoped by
+``corp_id:user_id`` to avoid cross-corp collisions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket as _socket
+import time
+from typing import Any, Dict, List, Optional
+from xml.etree import ElementTree as ET
+
+try:
+    from aiohttp import web
+
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    web = None  # type: ignore[assignment]
+    AIOHTTP_AVAILABLE = False
+
+try:
+    import httpx
+
+    HTTPX_AVAILABLE = True
+except ImportError:
+    httpx = None  # type: ignore[assignment]
+    HTTPX_AVAILABLE = False
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageType, SendResult
+from gateway.platforms.wecom_crypto import WXBizMsgCrypt, WeComCryptoError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8645
+DEFAULT_PATH = "/wecom/callback"
+ACCESS_TOKEN_TTL_SECONDS = 7200
+MESSAGE_DEDUP_TTL_SECONDS = 300
+
+
+def check_wecom_callback_requirements() -> bool:
+    return AIOHTTP_AVAILABLE and HTTPX_AVAILABLE
+
+
+class WecomCallbackAdapter(BasePlatformAdapter):
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.WECOM_CALLBACK)
+        extra = config.extra or {}
+        self._host = str(extra.get("host") or DEFAULT_HOST)
+        self._port = int(extra.get("port") or DEFAULT_PORT)
+        self._path = str(extra.get("path") or DEFAULT_PATH)
+        self._apps: List[Dict[str, Any]] = self._normalize_apps(extra)
+        self._runner: Optional[web.AppRunner] = None
+        self._site: Optional[web.TCPSite] = None
+        self._app: Optional[web.Application] = None
+        self._http_client: Optional[httpx.AsyncClient] = None
+        self._message_queue: asyncio.Queue[MessageEvent] = asyncio.Queue()
+        self._poll_task: Optional[asyncio.Task] = None
+        self._seen_messages: Dict[str, float] = {}
+        self._user_app_map: Dict[str, str] = {}
+        self._access_tokens: Dict[str, Dict[str, Any]] = {}
+
+    # ------------------------------------------------------------------
+    # App normalisation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _user_app_key(corp_id: str, user_id: str) -> str:
+        return f"{corp_id}:{user_id}" if corp_id else user_id
+
+    @staticmethod
+    def _normalize_apps(extra: Dict[str, Any]) -> List[Dict[str, Any]]:
+        apps = extra.get("apps")
+        if isinstance(apps, list) and apps:
+            return [dict(app) for app in apps if isinstance(app, dict)]
+        if extra.get("corp_id"):
+            return [
+                {
+                    "name": extra.get("name") or "default",
+                    "corp_id": extra.get("corp_id", ""),
+                    "corp_secret": extra.get("corp_secret", ""),
+                    "agent_id": str(extra.get("agent_id", "")),
+                    "token": extra.get("token", ""),
+                    "encoding_aes_key": extra.get("encoding_aes_key", ""),
+                }
+            ]
+        return []
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        if not self._apps:
+            logger.warning("[WecomCallback] No callback apps configured")
+            return False
+        if not check_wecom_callback_requirements():
+            logger.warning("[WecomCallback] aiohttp/httpx not installed")
+            return False
+
+        # Quick port-in-use check.
+        try:
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as sock:
+                sock.settimeout(1)
+                sock.connect(("127.0.0.1", self._port))
+            logger.error("[WecomCallback] Port %d already in use", self._port)
+            return False
+        except (ConnectionRefusedError, OSError):
+            pass
+
+        try:
+            self._http_client = httpx.AsyncClient(timeout=20.0)
+            self._app = web.Application()
+            self._app.router.add_get("/health", self._handle_health)
+            self._app.router.add_get(self._path, self._handle_verify)
+            self._app.router.add_post(self._path, self._handle_callback)
+            self._runner = web.AppRunner(self._app)
+            await self._runner.setup()
+            self._site = web.TCPSite(self._runner, self._host, self._port)
+            await self._site.start()
+            self._poll_task = asyncio.create_task(self._poll_loop())
+            self._mark_connected()
+            logger.info(
+                "[WecomCallback] HTTP server listening on %s:%s%s",
+                self._host, self._port, self._path,
+            )
+            for app in self._apps:
+                try:
+                    await self._refresh_access_token(app)
+                except Exception as exc:
+                    logger.warning(
+                        "[WecomCallback] Initial token refresh failed for app '%s': %s",
+                        app.get("name", "default"), exc,
+                    )
+            return True
+        except Exception:
+            await self._cleanup()
+            logger.exception("[WecomCallback] Failed to start")
+            return False
+
+    async def disconnect(self) -> None:
+        self._running = False
+        if self._poll_task:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+        await self._cleanup()
+        self._mark_disconnected()
+        logger.info("[WecomCallback] Disconnected")
+
+    async def _cleanup(self) -> None:
+        self._site = None
+        if self._runner:
+            await self._runner.cleanup()
+            self._runner = None
+        self._app = None
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    # ------------------------------------------------------------------
+    # Outbound: proactive send via access-token API
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        app = self._resolve_app_for_chat(chat_id)
+        touser = chat_id.split(":", 1)[1] if ":" in chat_id else chat_id
+        try:
+            token = await self._get_access_token(app)
+            payload = {
+                "touser": touser,
+                "msgtype": "text",
+                "agentid": int(str(app.get("agent_id") or 0)),
+                "text": {"content": content[:2048]},
+                "safe": 0,
+            }
+            resp = await self._http_client.post(
+                f"https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={token}",
+                json=payload,
+            )
+            data = resp.json()
+            if data.get("errcode") != 0:
+                return SendResult(success=False, error=str(data))
+            return SendResult(
+                success=True,
+                message_id=str(data.get("msgid", "")),
+                raw_response=data,
+            )
+        except Exception as exc:
+            return SendResult(success=False, error=str(exc))
+
+    def _resolve_app_for_chat(self, chat_id: str) -> Dict[str, Any]:
+        """Pick the app associated with *chat_id*, falling back sensibly."""
+        app_name = self._user_app_map.get(chat_id)
+        if not app_name and ":" not in chat_id:
+            # Legacy bare user_id — try to find a unique match.
+            matching = [k for k in self._user_app_map if k.endswith(f":{chat_id}")]
+            if len(matching) == 1:
+                app_name = self._user_app_map.get(matching[0])
+        app = self._get_app_by_name(app_name) if app_name else None
+        return app or self._apps[0]
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        return {"name": chat_id, "type": "dm"}
+
+    # ------------------------------------------------------------------
+    # Inbound: HTTP callback handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_health(self, request: web.Request) -> web.Response:
+        return web.json_response({"status": "ok", "platform": "wecom_callback"})
+
+    async def _handle_verify(self, request: web.Request) -> web.Response:
+        """GET endpoint — WeCom URL verification handshake."""
+        msg_signature = request.query.get("msg_signature", "")
+        timestamp = request.query.get("timestamp", "")
+        nonce = request.query.get("nonce", "")
+        echostr = request.query.get("echostr", "")
+        for app in self._apps:
+            try:
+                crypt = self._crypt_for_app(app)
+                plain = crypt.verify_url(msg_signature, timestamp, nonce, echostr)
+                return web.Response(text=plain, content_type="text/plain")
+            except Exception:
+                continue
+        return web.Response(status=403, text="signature verification failed")
+
+    async def _handle_callback(self, request: web.Request) -> web.Response:
+        """POST endpoint — receive an encrypted message callback."""
+        msg_signature = request.query.get("msg_signature", "")
+        timestamp = request.query.get("timestamp", "")
+        nonce = request.query.get("nonce", "")
+        body = await request.text()
+
+        for app in self._apps:
+            try:
+                decrypted = self._decrypt_request(
+                    app, body, msg_signature, timestamp, nonce,
+                )
+                event = self._build_event(app, decrypted)
+                if event is not None:
+                    # Record which app this user belongs to.
+                    if event.source and event.source.user_id:
+                        map_key = self._user_app_key(
+                            str(app.get("corp_id") or ""), event.source.user_id,
+                        )
+                        self._user_app_map[map_key] = app["name"]
+                    await self._message_queue.put(event)
+                # Immediately acknowledge — the agent's reply will arrive
+                # later via the proactive message/send API.
+                return web.Response(text="success", content_type="text/plain")
+            except WeComCryptoError:
+                continue
+            except Exception:
+                logger.exception("[WecomCallback] Error handling message")
+                break
+        return web.Response(status=400, text="invalid callback payload")
+
+    async def _poll_loop(self) -> None:
+        """Drain the message queue and dispatch to the gateway runner."""
+        while True:
+            event = await self._message_queue.get()
+            try:
+                task = asyncio.create_task(self.handle_message(event))
+                self._background_tasks.add(task)
+                task.add_done_callback(self._background_tasks.discard)
+            except Exception:
+                logger.exception("[WecomCallback] Failed to enqueue event")
+
+    # ------------------------------------------------------------------
+    # XML / crypto helpers
+    # ------------------------------------------------------------------
+
+    def _decrypt_request(
+        self, app: Dict[str, Any], body: str,
+        msg_signature: str, timestamp: str, nonce: str,
+    ) -> str:
+        root = ET.fromstring(body)
+        encrypt = root.findtext("Encrypt", default="")
+        crypt = self._crypt_for_app(app)
+        return crypt.decrypt(msg_signature, timestamp, nonce, encrypt).decode("utf-8")
+
+    def _build_event(self, app: Dict[str, Any], xml_text: str) -> Optional[MessageEvent]:
+        root = ET.fromstring(xml_text)
+        msg_type = (root.findtext("MsgType") or "").lower()
+        # Silently acknowledge lifecycle events.
+        if msg_type == "event":
+            event_name = (root.findtext("Event") or "").lower()
+            if event_name in {"enter_agent", "subscribe"}:
+                return None
+        if msg_type not in {"text", "event"}:
+            return None
+
+        user_id = root.findtext("FromUserName", default="")
+        corp_id = root.findtext("ToUserName", default=app.get("corp_id", ""))
+        scoped_chat_id = self._user_app_key(corp_id, user_id)
+        content = root.findtext("Content", default="").strip()
+        if not content and msg_type == "event":
+            content = "/start"
+        msg_id = (
+            root.findtext("MsgId")
+            or f"{user_id}:{root.findtext('CreateTime', default='0')}"
+        )
+        source = self.build_source(
+            chat_id=scoped_chat_id,
+            chat_name=user_id,
+            chat_type="dm",
+            user_id=user_id,
+            user_name=user_id,
+        )
+        return MessageEvent(
+            text=content,
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=xml_text,
+            message_id=msg_id,
+        )
+
+    def _crypt_for_app(self, app: Dict[str, Any]) -> WXBizMsgCrypt:
+        return WXBizMsgCrypt(
+            token=str(app.get("token") or ""),
+            encoding_aes_key=str(app.get("encoding_aes_key") or ""),
+            receive_id=str(app.get("corp_id") or ""),
+        )
+
+    def _get_app_by_name(self, name: Optional[str]) -> Optional[Dict[str, Any]]:
+        if not name:
+            return None
+        for app in self._apps:
+            if app.get("name") == name:
+                return app
+        return None
+
+    # ------------------------------------------------------------------
+    # Access-token management
+    # ------------------------------------------------------------------
+
+    async def _get_access_token(self, app: Dict[str, Any]) -> str:
+        cached = self._access_tokens.get(app["name"])
+        now = time.time()
+        if cached and cached.get("expires_at", 0) > now + 60:
+            return cached["token"]
+        return await self._refresh_access_token(app)
+
+    async def _refresh_access_token(self, app: Dict[str, Any]) -> str:
+        resp = await self._http_client.get(
+            "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+            params={
+                "corpid": app.get("corp_id"),
+                "corpsecret": app.get("corp_secret"),
+            },
+        )
+        data = resp.json()
+        if data.get("errcode") != 0:
+            raise RuntimeError(f"WeCom token refresh failed: {data}")
+        token = data["access_token"]
+        expires_in = int(data.get("expires_in", ACCESS_TOKEN_TTL_SECONDS))
+        self._access_tokens[app["name"]] = {
+            "token": token,
+            "expires_at": time.time() + expires_in,
+        }
+        logger.info(
+            "[WecomCallback] Token refreshed for app '%s' (corp=%s), expires in %ss",
+            app.get("name", "default"),
+            app.get("corp_id", ""),
+            expires_in,
+        )
+        return token

mindcli/_vendor/gateway/platforms/wecom_crypto.py

@@ -0,0 +1,142 @@
+"""WeCom BizMsgCrypt-compatible AES-CBC encryption for callback mode.
+
+Implements the same wire format as Tencent's official ``WXBizMsgCrypt``
+SDK so that WeCom can verify, encrypt, and decrypt callback payloads.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import secrets
+import socket
+import struct
+from typing import Optional
+from xml.etree import ElementTree as ET
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+
+class WeComCryptoError(Exception):
+    pass
+
+
+class SignatureError(WeComCryptoError):
+    pass
+
+
+class DecryptError(WeComCryptoError):
+    pass
+
+
+class EncryptError(WeComCryptoError):
+    pass
+
+
+class PKCS7Encoder:
+    block_size = 32
+
+    @classmethod
+    def encode(cls, text: bytes) -> bytes:
+        amount_to_pad = cls.block_size - (len(text) % cls.block_size)
+        if amount_to_pad == 0:
+            amount_to_pad = cls.block_size
+        pad = bytes([amount_to_pad]) * amount_to_pad
+        return text + pad
+
+    @classmethod
+    def decode(cls, decrypted: bytes) -> bytes:
+        if not decrypted:
+            raise DecryptError("empty decrypted payload")
+        pad = decrypted[-1]
+        if pad < 1 or pad > cls.block_size:
+            raise DecryptError("invalid PKCS7 padding")
+        if decrypted[-pad:] != bytes([pad]) * pad:
+            raise DecryptError("malformed PKCS7 padding")
+        return decrypted[:-pad]
+
+
+def _sha1_signature(token: str, timestamp: str, nonce: str, encrypt: str) -> str:
+    parts = sorted([token, timestamp, nonce, encrypt])
+    return hashlib.sha1("".join(parts).encode("utf-8")).hexdigest()
+
+
+class WXBizMsgCrypt:
+    """Minimal WeCom callback crypto helper compatible with BizMsgCrypt semantics."""
+
+    def __init__(self, token: str, encoding_aes_key: str, receive_id: str):
+        if not token:
+            raise ValueError("token is required")
+        if not encoding_aes_key:
+            raise ValueError("encoding_aes_key is required")
+        if len(encoding_aes_key) != 43:
+            raise ValueError("encoding_aes_key must be 43 chars")
+        if not receive_id:
+            raise ValueError("receive_id is required")
+
+        self.token = token
+        self.receive_id = receive_id
+        self.key = base64.b64decode(encoding_aes_key + "=")
+        self.iv = self.key[:16]
+
+    def verify_url(self, msg_signature: str, timestamp: str, nonce: str, echostr: str) -> str:
+        plain = self.decrypt(msg_signature, timestamp, nonce, echostr)
+        return plain.decode("utf-8")
+
+    def decrypt(self, msg_signature: str, timestamp: str, nonce: str, encrypt: str) -> bytes:
+        expected = _sha1_signature(self.token, timestamp, nonce, encrypt)
+        if expected != msg_signature:
+            raise SignatureError("signature mismatch")
+        try:
+            cipher_text = base64.b64decode(encrypt)
+        except Exception as exc:
+            raise DecryptError(f"invalid base64 payload: {exc}") from exc
+        try:
+            cipher = Cipher(algorithms.AES(self.key), modes.CBC(self.iv), backend=default_backend())
+            decryptor = cipher.decryptor()
+            padded = decryptor.update(cipher_text) + decryptor.finalize()
+            plain = PKCS7Encoder.decode(padded)
+            content = plain[16:]  # skip 16-byte random prefix
+            xml_length = socket.ntohl(struct.unpack("I", content[:4])[0])
+            xml_content = content[4:4 + xml_length]
+            receive_id = content[4 + xml_length:].decode("utf-8")
+        except WeComCryptoError:
+            raise
+        except Exception as exc:
+            raise DecryptError(f"decrypt failed: {exc}") from exc
+
+        if receive_id != self.receive_id:
+            raise DecryptError("receive_id mismatch")
+        return xml_content
+
+    def encrypt(self, plaintext: str, nonce: Optional[str] = None, timestamp: Optional[str] = None) -> str:
+        nonce = nonce or self._random_nonce()
+        timestamp = timestamp or str(int(__import__("time").time()))
+        encrypt = self._encrypt_bytes(plaintext.encode("utf-8"))
+        signature = _sha1_signature(self.token, timestamp, nonce, encrypt)
+        root = ET.Element("xml")
+        ET.SubElement(root, "Encrypt").text = encrypt
+        ET.SubElement(root, "MsgSignature").text = signature
+        ET.SubElement(root, "TimeStamp").text = timestamp
+        ET.SubElement(root, "Nonce").text = nonce
+        return ET.tostring(root, encoding="unicode")
+
+    def _encrypt_bytes(self, raw: bytes) -> str:
+        try:
+            random_prefix = os.urandom(16)
+            msg_len = struct.pack("I", socket.htonl(len(raw)))
+            payload = random_prefix + msg_len + raw + self.receive_id.encode("utf-8")
+            padded = PKCS7Encoder.encode(payload)
+            cipher = Cipher(algorithms.AES(self.key), modes.CBC(self.iv), backend=default_backend())
+            encryptor = cipher.encryptor()
+            encrypted = encryptor.update(padded) + encryptor.finalize()
+            return base64.b64encode(encrypted).decode("utf-8")
+        except Exception as exc:
+            raise EncryptError(f"encrypt failed: {exc}") from exc
+
+    @staticmethod
+    def _random_nonce(length: int = 10) -> str:
+        alphabet = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        return "".join(secrets.choice(alphabet) for _ in range(length))

mindcli/_vendor/gateway/platforms/whatsapp.py

@@ -0,0 +1,989 @@
+"""
+WhatsApp platform adapter.
+
+WhatsApp integration is more complex than Telegram/Discord because:
+- No official bot API for personal accounts
+- Business API requires Meta Business verification
+- Most solutions use web-based automation
+
+This adapter supports multiple backends:
+1. WhatsApp Business API (requires Meta verification)
+2. whatsapp-web.js (via Node.js subprocess) - for personal accounts
+3. Baileys (via Node.js subprocess) - alternative for personal accounts
+
+For simplicity, we'll implement a generic interface that can work
+with different backends via a bridge pattern.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import platform
+import re
+import subprocess
+
+_IS_WINDOWS = platform.system() == "Windows"
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+from hermes_constants import get_hermes_dir
+
+logger = logging.getLogger(__name__)
+
+
+def _kill_port_process(port: int) -> None:
+    """Kill any process listening on the given TCP port."""
+    try:
+        if _IS_WINDOWS:
+            # Use netstat to find the PID bound to this port, then taskkill
+            result = subprocess.run(
+                ["netstat", "-ano", "-p", "TCP"],
+                capture_output=True, text=True, timeout=5,
+            )
+            for line in result.stdout.splitlines():
+                parts = line.split()
+                if len(parts) >= 5 and parts[3] == "LISTENING":
+                    local_addr = parts[1]
+                    if local_addr.endswith(f":{port}"):
+                        try:
+                            subprocess.run(
+                                ["taskkill", "/PID", parts[4], "/F"],
+                                capture_output=True, timeout=5,
+                            )
+                        except subprocess.SubprocessError:
+                            pass
+        else:
+            result = subprocess.run(
+                ["fuser", f"{port}/tcp"],
+                capture_output=True, timeout=5,
+            )
+            if result.returncode == 0:
+                subprocess.run(
+                    ["fuser", "-k", f"{port}/tcp"],
+                    capture_output=True, timeout=5,
+                )
+    except Exception:
+        pass
+
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+    SUPPORTED_DOCUMENT_TYPES,
+    cache_image_from_url,
+    cache_audio_from_url,
+)
+
+
+def check_whatsapp_requirements() -> bool:
+    """
+    Check if WhatsApp dependencies are available.
+    
+    WhatsApp requires a Node.js bridge for most implementations.
+    """
+    # Check for Node.js
+    try:
+        result = subprocess.run(
+            ["node", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+class WhatsAppAdapter(BasePlatformAdapter):
+    """
+    WhatsApp adapter.
+    
+    This implementation uses a simple HTTP bridge pattern where:
+    1. A Node.js process runs the WhatsApp Web client
+    2. Messages are forwarded via HTTP/IPC to this Python adapter
+    3. Responses are sent back through the bridge
+    
+    The actual Node.js bridge implementation can vary:
+    - whatsapp-web.js based
+    - Baileys based
+    - Business API based
+    
+    Configuration:
+    - bridge_script: Path to the Node.js bridge script
+    - bridge_port: Port for HTTP communication (default: 3000)
+    - session_path: Path to store WhatsApp session data
+    """
+    
+    # WhatsApp message limits — practical UX limit, not protocol max.
+    # WhatsApp allows ~65K but long messages are unreadable on mobile.
+    MAX_MESSAGE_LENGTH = 4096
+    
+    # Default bridge location relative to the hermes-agent install
+    _DEFAULT_BRIDGE_DIR = Path(__file__).resolve().parents[2] / "scripts" / "whatsapp-bridge"
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.WHATSAPP)
+        self._bridge_process: Optional[subprocess.Popen] = None
+        self._bridge_port: int = config.extra.get("bridge_port", 3000)
+        self._bridge_script: Optional[str] = config.extra.get(
+            "bridge_script",
+            str(self._DEFAULT_BRIDGE_DIR / "bridge.js"),
+        )
+        self._session_path: Path = Path(config.extra.get(
+            "session_path",
+            get_hermes_dir("platforms/whatsapp/session", "whatsapp/session")
+        ))
+        self._reply_prefix: Optional[str] = config.extra.get("reply_prefix")
+        self._mention_patterns = self._compile_mention_patterns()
+        self._message_queue: asyncio.Queue = asyncio.Queue()
+        self._bridge_log_fh = None
+        self._bridge_log: Optional[Path] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._http_session: Optional["aiohttp.ClientSession"] = None
+
+    def _whatsapp_require_mention(self) -> bool:
+        configured = self.config.extra.get("require_mention")
+        if configured is not None:
+            if isinstance(configured, str):
+                return configured.lower() in ("true", "1", "yes", "on")
+            return bool(configured)
+        return os.getenv("WHATSAPP_REQUIRE_MENTION", "false").lower() in ("true", "1", "yes", "on")
+
+    def _whatsapp_free_response_chats(self) -> set[str]:
+        raw = self.config.extra.get("free_response_chats")
+        if raw is None:
+            raw = os.getenv("WHATSAPP_FREE_RESPONSE_CHATS", "")
+        if isinstance(raw, list):
+            return {str(part).strip() for part in raw if str(part).strip()}
+        return {part.strip() for part in str(raw).split(",") if part.strip()}
+
+    def _compile_mention_patterns(self):
+        patterns = self.config.extra.get("mention_patterns")
+        if patterns is None:
+            raw = os.getenv("WHATSAPP_MENTION_PATTERNS", "").strip()
+            if raw:
+                try:
+                    patterns = json.loads(raw)
+                except Exception:
+                    patterns = [part.strip() for part in raw.splitlines() if part.strip()]
+                    if not patterns:
+                        patterns = [part.strip() for part in raw.split(",") if part.strip()]
+        if patterns is None:
+            return []
+        if isinstance(patterns, str):
+            patterns = [patterns]
+        if not isinstance(patterns, list):
+            logger.warning("[%s] whatsapp mention_patterns must be a list or string; got %s", self.name, type(patterns).__name__)
+            return []
+
+        compiled = []
+        for pattern in patterns:
+            if not isinstance(pattern, str) or not pattern.strip():
+                continue
+            try:
+                compiled.append(re.compile(pattern, re.IGNORECASE))
+            except re.error as exc:
+                logger.warning("[%s] Invalid WhatsApp mention pattern %r: %s", self.name, pattern, exc)
+        if compiled:
+            logger.info("[%s] Loaded %d WhatsApp mention pattern(s)", self.name, len(compiled))
+        return compiled
+
+    @staticmethod
+    def _normalize_whatsapp_id(value: Optional[str]) -> str:
+        if not value:
+            return ""
+        normalized = str(value).strip()
+        if ":" in normalized and "@" in normalized:
+            normalized = normalized.replace(":", "@", 1)
+        return normalized
+
+    def _bot_ids_from_message(self, data: Dict[str, Any]) -> set[str]:
+        bot_ids = set()
+        for candidate in data.get("botIds") or []:
+            normalized = self._normalize_whatsapp_id(candidate)
+            if normalized:
+                bot_ids.add(normalized)
+        return bot_ids
+
+    def _message_is_reply_to_bot(self, data: Dict[str, Any]) -> bool:
+        quoted_participant = self._normalize_whatsapp_id(data.get("quotedParticipant"))
+        if not quoted_participant:
+            return False
+        return quoted_participant in self._bot_ids_from_message(data)
+
+    def _message_mentions_bot(self, data: Dict[str, Any]) -> bool:
+        bot_ids = self._bot_ids_from_message(data)
+        if not bot_ids:
+            return False
+        mentioned_ids = {
+            nid
+            for candidate in (data.get("mentionedIds") or [])
+            if (nid := self._normalize_whatsapp_id(candidate))
+        }
+        if mentioned_ids & bot_ids:
+            return True
+
+        body = str(data.get("body") or "")
+        lower_body = body.lower()
+        for bot_id in bot_ids:
+            bare_id = bot_id.split("@", 1)[0].lower()
+            if bare_id and (f"@{bare_id}" in lower_body or bare_id in lower_body):
+                return True
+        return False
+
+    def _message_matches_mention_patterns(self, data: Dict[str, Any]) -> bool:
+        if not self._mention_patterns:
+            return False
+        body = str(data.get("body") or "")
+        return any(pattern.search(body) for pattern in self._mention_patterns)
+
+    def _clean_bot_mention_text(self, text: str, data: Dict[str, Any]) -> str:
+        if not text:
+            return text
+        bot_ids = self._bot_ids_from_message(data)
+        cleaned = text
+        for bot_id in bot_ids:
+            bare_id = bot_id.split("@", 1)[0]
+            if bare_id:
+                cleaned = re.sub(rf"@{re.escape(bare_id)}\b[,:\-]*\s*", "", cleaned)
+        return cleaned.strip() or text
+
+    def _should_process_message(self, data: Dict[str, Any]) -> bool:
+        if not data.get("isGroup"):
+            return True
+        chat_id = str(data.get("chatId") or "")
+        if chat_id in self._whatsapp_free_response_chats():
+            return True
+        if not self._whatsapp_require_mention():
+            return True
+        body = str(data.get("body") or "").strip()
+        if body.startswith("/"):
+            return True
+        if self._message_is_reply_to_bot(data):
+            return True
+        if self._message_mentions_bot(data):
+            return True
+        return self._message_matches_mention_patterns(data)
+    
+    async def connect(self) -> bool:
+        """
+        Start the WhatsApp bridge.
+        
+        This launches the Node.js bridge process and waits for it to be ready.
+        """
+        if not check_whatsapp_requirements():
+            logger.warning("[%s] Node.js not found. WhatsApp requires Node.js.", self.name)
+            return False
+        
+        bridge_path = Path(self._bridge_script)
+        if not bridge_path.exists():
+            logger.warning("[%s] Bridge script not found: %s", self.name, bridge_path)
+            return False
+        
+        logger.info("[%s] Bridge found at %s", self.name, bridge_path)
+        
+        # Acquire scoped lock to prevent duplicate sessions
+        try:
+            if not self._acquire_platform_lock('whatsapp-session', str(self._session_path), 'WhatsApp session'):
+                return False
+        except Exception as e:
+            logger.warning("[%s] Could not acquire session lock (non-fatal): %s", self.name, e)
+
+        # Auto-install npm dependencies if node_modules doesn't exist
+        bridge_dir = bridge_path.parent
+        if not (bridge_dir / "node_modules").exists():
+            print(f"[{self.name}] Installing WhatsApp bridge dependencies...")
+            try:
+                install_result = subprocess.run(
+                    ["npm", "install", "--silent"],
+                    cwd=str(bridge_dir),
+                    capture_output=True,
+                    text=True,
+                    timeout=60,
+                )
+                if install_result.returncode != 0:
+                    print(f"[{self.name}] npm install failed: {install_result.stderr}")
+                    return False
+                print(f"[{self.name}] Dependencies installed")
+            except Exception as e:
+                print(f"[{self.name}] Failed to install dependencies: {e}")
+                return False
+        
+        try:
+            # Ensure session directory exists
+            self._session_path.mkdir(parents=True, exist_ok=True)
+            
+            # Check if bridge is already running and connected
+            import aiohttp
+            import asyncio
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.get(
+                        f"http://127.0.0.1:{self._bridge_port}/health",
+                        timeout=aiohttp.ClientTimeout(total=2)
+                    ) as resp:
+                        if resp.status == 200:
+                            data = await resp.json()
+                            bridge_status = data.get("status", "unknown")
+                            if bridge_status == "connected":
+                                print(f"[{self.name}] Using existing bridge (status: {bridge_status})")
+                                self._mark_connected()
+                                self._bridge_process = None  # Not managed by us
+                                self._http_session = aiohttp.ClientSession()
+                                self._poll_task = asyncio.create_task(self._poll_messages())
+                                return True
+                            else:
+                                print(f"[{self.name}] Bridge found but not connected (status: {bridge_status}), restarting")
+            except Exception:
+                pass  # Bridge not running, start a new one
+            
+            # Kill any orphaned bridge from a previous gateway run
+            _kill_port_process(self._bridge_port)
+            await asyncio.sleep(1)
+            
+            # Start the bridge process in its own process group.
+            # Route output to a log file so QR codes, errors, and reconnection
+            # messages are preserved for troubleshooting.
+            whatsapp_mode = os.getenv("WHATSAPP_MODE", "self-chat")
+            self._bridge_log = self._session_path.parent / "bridge.log"
+            bridge_log_fh = open(self._bridge_log, "a")
+            self._bridge_log_fh = bridge_log_fh
+
+            # Build bridge subprocess environment.
+            # Pass WHATSAPP_REPLY_PREFIX from config.yaml so the Node bridge
+            # can use it without the user needing to set a separate env var.
+            bridge_env = os.environ.copy()
+            if self._reply_prefix is not None:
+                bridge_env["WHATSAPP_REPLY_PREFIX"] = self._reply_prefix
+
+            self._bridge_process = subprocess.Popen(
+                [
+                    "node",
+                    str(bridge_path),
+                    "--port", str(self._bridge_port),
+                    "--session", str(self._session_path),
+                    "--mode", whatsapp_mode,
+                ],
+                stdout=bridge_log_fh,
+                stderr=bridge_log_fh,
+                preexec_fn=None if _IS_WINDOWS else os.setsid,
+                env=bridge_env,
+            )
+            
+            # Wait for the bridge to connect to WhatsApp.
+            # Phase 1: wait for the HTTP server to come up (up to 15s).
+            # Phase 2: wait for WhatsApp status: connected (up to 15s more).
+            import aiohttp
+            http_ready = False
+            data = {}
+            for attempt in range(15):
+                await asyncio.sleep(1)
+                if self._bridge_process.poll() is not None:
+                    print(f"[{self.name}] Bridge process died (exit code {self._bridge_process.returncode})")
+                    print(f"[{self.name}] Check log: {self._bridge_log}")
+                    self._close_bridge_log()
+                    return False
+                try:
+                    async with aiohttp.ClientSession() as session:
+                        async with session.get(
+                            f"http://127.0.0.1:{self._bridge_port}/health",
+                            timeout=aiohttp.ClientTimeout(total=2)
+                        ) as resp:
+                            if resp.status == 200:
+                                http_ready = True
+                                data = await resp.json()
+                                if data.get("status") == "connected":
+                                    print(f"[{self.name}] Bridge ready (status: connected)")
+                                    break
+                except Exception:
+                    continue
+
+            if not http_ready:
+                print(f"[{self.name}] Bridge HTTP server did not start in 15s")
+                print(f"[{self.name}] Check log: {self._bridge_log}")
+                self._close_bridge_log()
+                return False
+            
+            # Phase 2: HTTP is up but WhatsApp may still be connecting.
+            # Give it more time to authenticate with saved credentials.
+            if data.get("status") != "connected":
+                print(f"[{self.name}] Bridge HTTP ready, waiting for WhatsApp connection...")
+                for attempt in range(15):
+                    await asyncio.sleep(1)
+                    if self._bridge_process.poll() is not None:
+                        print(f"[{self.name}] Bridge process died during connection")
+                        print(f"[{self.name}] Check log: {self._bridge_log}")
+                        self._close_bridge_log()
+                        return False
+                    try:
+                        async with aiohttp.ClientSession() as session:
+                            async with session.get(
+                                f"http://127.0.0.1:{self._bridge_port}/health",
+                                timeout=aiohttp.ClientTimeout(total=2)
+                            ) as resp:
+                                if resp.status == 200:
+                                    data = await resp.json()
+                                    if data.get("status") == "connected":
+                                        print(f"[{self.name}] Bridge ready (status: connected)")
+                                        break
+                    except Exception:
+                        continue
+                else:
+                    # Still not connected — warn but proceed (bridge may
+                    # auto-reconnect later, e.g. after a code 515 restart).
+                    print(f"[{self.name}] ⚠ WhatsApp not connected after 30s")
+                    print(f"[{self.name}]   Bridge log: {self._bridge_log}")
+                    print(f"[{self.name}]   If session expired, re-pair: hermes whatsapp")
+            
+            # Create a persistent HTTP session for all bridge communication
+            self._http_session = aiohttp.ClientSession()
+
+            # Start message polling task
+            self._poll_task = asyncio.create_task(self._poll_messages())
+            
+            self._mark_connected()
+            print(f"[{self.name}] Bridge started on port {self._bridge_port}")
+            return True
+            
+        except Exception as e:
+            self._release_platform_lock()
+            logger.error("[%s] Failed to start bridge: %s", self.name, e, exc_info=True)
+            self._close_bridge_log()
+            return False
+    
+    def _close_bridge_log(self) -> None:
+        """Close the bridge log file handle if open."""
+        if self._bridge_log_fh:
+            try:
+                self._bridge_log_fh.close()
+            except Exception:
+                pass
+            self._bridge_log_fh = None
+
+    async def _check_managed_bridge_exit(self) -> Optional[str]:
+        """Return a fatal error message if the managed bridge child exited."""
+        if self._bridge_process is None:
+            return None
+
+        returncode = self._bridge_process.poll()
+        if returncode is None:
+            return None
+
+        message = f"WhatsApp bridge process exited unexpectedly (code {returncode})."
+        if not self.has_fatal_error:
+            logger.error("[%s] %s", self.name, message)
+            self._set_fatal_error("whatsapp_bridge_exited", message, retryable=True)
+            self._close_bridge_log()
+            await self._notify_fatal_error()
+        return self.fatal_error_message or message
+
+    async def disconnect(self) -> None:
+        """Stop the WhatsApp bridge and clean up any orphaned processes."""
+        if self._bridge_process:
+            try:
+                # Kill the entire process group so child node processes die too
+                import signal
+                try:
+                    if _IS_WINDOWS:
+                        self._bridge_process.terminate()
+                    else:
+                        os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGTERM)
+                except (ProcessLookupError, PermissionError):
+                    self._bridge_process.terminate()
+                await asyncio.sleep(1)
+                if self._bridge_process.poll() is None:
+                    try:
+                        if _IS_WINDOWS:
+                            self._bridge_process.kill()
+                        else:
+                            os.killpg(os.getpgid(self._bridge_process.pid), signal.SIGKILL)
+                    except (ProcessLookupError, PermissionError):
+                        self._bridge_process.kill()
+            except Exception as e:
+                print(f"[{self.name}] Error stopping bridge: {e}")
+        else:
+            # Bridge was not started by us, don't kill it
+            print(f"[{self.name}] Disconnecting (external bridge left running)")
+
+        # Cancel the poll task explicitly
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        self._poll_task = None
+
+        # Close the persistent HTTP session
+        if self._http_session and not self._http_session.closed:
+            await self._http_session.close()
+        self._http_session = None
+
+        self._release_platform_lock()
+
+        self._mark_disconnected()
+        self._bridge_process = None
+        self._close_bridge_log()
+        print(f"[{self.name}] Disconnected")
+    
+    def format_message(self, content: str) -> str:
+        """Convert standard markdown to WhatsApp-compatible formatting.
+
+        WhatsApp supports: *bold*, _italic_, ~strikethrough~, ```code```,
+        and monospaced `inline`. Standard markdown uses different syntax
+        for bold/italic/strikethrough, so we convert here.
+
+        Code blocks (``` fenced) and inline code (`) are protected from
+        conversion via placeholder substitution.
+        """
+        if not content:
+            return content
+
+        # --- 1. Protect fenced code blocks from formatting changes ---
+        _FENCE_PH = "\x00FENCE"
+        fences: list[str] = []
+
+        def _save_fence(m: re.Match) -> str:
+            fences.append(m.group(0))
+            return f"{_FENCE_PH}{len(fences) - 1}\x00"
+
+        result = re.sub(r"```[\s\S]*?```", _save_fence, content)
+
+        # --- 2. Protect inline code ---
+        _CODE_PH = "\x00CODE"
+        codes: list[str] = []
+
+        def _save_code(m: re.Match) -> str:
+            codes.append(m.group(0))
+            return f"{_CODE_PH}{len(codes) - 1}\x00"
+
+        result = re.sub(r"`[^`\n]+`", _save_code, result)
+
+        # --- 3. Convert markdown formatting to WhatsApp syntax ---
+        # Bold: **text** or __text__ → *text*
+        result = re.sub(r"\*\*(.+?)\*\*", r"*\1*", result)
+        result = re.sub(r"__(.+?)__", r"*\1*", result)
+        # Strikethrough: ~~text~~ → ~text~
+        result = re.sub(r"~~(.+?)~~", r"~\1~", result)
+        # Italic: *text* is already WhatsApp italic — leave as-is
+        # _text_ is already WhatsApp italic — leave as-is
+
+        # --- 4. Convert markdown headers to bold text ---
+        # # Header → *Header*
+        result = re.sub(r"^#{1,6}\s+(.+)$", r"*\1*", result, flags=re.MULTILINE)
+
+        # --- 5. Convert markdown links: [text](url) → text (url) ---
+        result = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"\1 (\2)", result)
+
+        # --- 6. Restore protected sections ---
+        for i, fence in enumerate(fences):
+            result = result.replace(f"{_FENCE_PH}{i}\x00", fence)
+        for i, code in enumerate(codes):
+            result = result.replace(f"{_CODE_PH}{i}\x00", code)
+
+        return result
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> SendResult:
+        """Send a message via the WhatsApp bridge.
+
+        Formats markdown for WhatsApp, splits long messages into chunks
+        that preserve code block boundaries, and sends each chunk sequentially.
+        """
+        if not self._running or not self._http_session:
+            return SendResult(success=False, error="Not connected")
+        bridge_exit = await self._check_managed_bridge_exit()
+        if bridge_exit:
+            return SendResult(success=False, error=bridge_exit)
+
+        if not content or not content.strip():
+            return SendResult(success=True, message_id=None)
+
+        try:
+            import aiohttp
+
+            # Format and chunk the message
+            formatted = self.format_message(content)
+            chunks = self.truncate_message(formatted, self.MAX_MESSAGE_LENGTH)
+
+            last_message_id = None
+            for chunk in chunks:
+                payload: Dict[str, Any] = {
+                    "chatId": chat_id,
+                    "message": chunk,
+                }
+                if reply_to and last_message_id is None:
+                    # Only reply-to on the first chunk
+                    payload["replyTo"] = reply_to
+
+                async with self._http_session.post(
+                    f"http://127.0.0.1:{self._bridge_port}/send",
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=30)
+                ) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        last_message_id = data.get("messageId")
+                    else:
+                        error = await resp.text()
+                        return SendResult(success=False, error=error)
+
+                # Small delay between chunks to avoid rate limiting
+                if len(chunks) > 1:
+                    await asyncio.sleep(0.3)
+
+            return SendResult(
+                success=True,
+                message_id=last_message_id,
+            )
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+    ) -> SendResult:
+        """Edit a previously sent message via the WhatsApp bridge."""
+        if not self._running or not self._http_session:
+            return SendResult(success=False, error="Not connected")
+        bridge_exit = await self._check_managed_bridge_exit()
+        if bridge_exit:
+            return SendResult(success=False, error=bridge_exit)
+        try:
+            import aiohttp
+            async with self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/edit",
+                json={
+                    "chatId": chat_id,
+                    "messageId": message_id,
+                    "message": content,
+                },
+                timeout=aiohttp.ClientTimeout(total=15)
+            ) as resp:
+                if resp.status == 200:
+                    return SendResult(success=True, message_id=message_id)
+                else:
+                    error = await resp.text()
+                    return SendResult(success=False, error=error)
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def _send_media_to_bridge(
+        self,
+        chat_id: str,
+        file_path: str,
+        media_type: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+    ) -> SendResult:
+        """Send any media file via bridge /send-media endpoint."""
+        if not self._running or not self._http_session:
+            return SendResult(success=False, error="Not connected")
+        bridge_exit = await self._check_managed_bridge_exit()
+        if bridge_exit:
+            return SendResult(success=False, error=bridge_exit)
+        try:
+            import aiohttp
+
+            if not os.path.exists(file_path):
+                return SendResult(success=False, error=f"File not found: {file_path}")
+
+            payload: Dict[str, Any] = {
+                "chatId": chat_id,
+                "filePath": file_path,
+                "mediaType": media_type,
+            }
+            if caption:
+                payload["caption"] = caption
+            if file_name:
+                payload["fileName"] = file_name
+
+            async with self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/send-media",
+                json=payload,
+                timeout=aiohttp.ClientTimeout(total=120),
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return SendResult(
+                        success=True,
+                        message_id=data.get("messageId"),
+                        raw_response=data,
+                    )
+                else:
+                    error = await resp.text()
+                    return SendResult(success=False, error=error)
+
+        except Exception as e:
+            return SendResult(success=False, error=str(e))
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+    ) -> SendResult:
+        """Download image URL to cache, send natively via bridge."""
+        try:
+            local_path = await cache_image_from_url(image_url)
+            return await self._send_media_to_bridge(chat_id, local_path, "image", caption)
+        except Exception:
+            return await super().send_image(chat_id, image_url, caption, reply_to)
+
+    async def send_image_file(
+        self,
+        chat_id: str,
+        image_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a local image file natively via bridge."""
+        return await self._send_media_to_bridge(chat_id, image_path, "image", caption)
+
+    async def send_video(
+        self,
+        chat_id: str,
+        video_path: str,
+        caption: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a video natively via bridge — plays inline in WhatsApp."""
+        return await self._send_media_to_bridge(chat_id, video_path, "video", caption)
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        file_name: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a document/file as a downloadable attachment via bridge."""
+        return await self._send_media_to_bridge(
+            chat_id, file_path, "document", caption,
+            file_name or os.path.basename(file_path),
+        )
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """Send typing indicator via bridge."""
+        if not self._running or not self._http_session:
+            return
+        if await self._check_managed_bridge_exit():
+            return
+        
+        try:
+            import aiohttp
+
+            await self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/typing",
+                json={"chatId": chat_id},
+                timeout=aiohttp.ClientTimeout(total=5)
+            )
+        except Exception:
+            pass  # Ignore typing indicator failures
+    
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Get information about a WhatsApp chat."""
+        if not self._running or not self._http_session:
+            return {"name": "Unknown", "type": "dm"}
+        if await self._check_managed_bridge_exit():
+            return {"name": chat_id, "type": "dm"}
+        
+        try:
+            import aiohttp
+
+            async with self._http_session.get(
+                f"http://127.0.0.1:{self._bridge_port}/chat/{chat_id}",
+                timeout=aiohttp.ClientTimeout(total=10)
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return {
+                        "name": data.get("name", chat_id),
+                        "type": "group" if data.get("isGroup") else "dm",
+                        "participants": data.get("participants", []),
+                    }
+        except Exception as e:
+            logger.debug("Could not get WhatsApp chat info for %s: %s", chat_id, e)
+        
+        return {"name": chat_id, "type": "dm"}
+    
+    async def _poll_messages(self) -> None:
+        """Poll the bridge for incoming messages."""
+        import aiohttp
+
+        while self._running:
+            if not self._http_session:
+                break
+            bridge_exit = await self._check_managed_bridge_exit()
+            if bridge_exit:
+                print(f"[{self.name}] {bridge_exit}")
+                break
+            try:
+                async with self._http_session.get(
+                    f"http://127.0.0.1:{self._bridge_port}/messages",
+                    timeout=aiohttp.ClientTimeout(total=30)
+                ) as resp:
+                    if resp.status == 200:
+                        messages = await resp.json()
+                        for msg_data in messages:
+                            event = await self._build_message_event(msg_data)
+                            if event:
+                                await self.handle_message(event)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                bridge_exit = await self._check_managed_bridge_exit()
+                if bridge_exit:
+                    print(f"[{self.name}] {bridge_exit}")
+                    break
+                print(f"[{self.name}] Poll error: {e}")
+                await asyncio.sleep(5)
+            
+            await asyncio.sleep(1)  # Poll interval
+    
+    async def _build_message_event(self, data: Dict[str, Any]) -> Optional[MessageEvent]:
+        """Build a MessageEvent from bridge message data, downloading images to cache."""
+        try:
+            if not self._should_process_message(data):
+                return None
+
+            # Determine message type
+            msg_type = MessageType.TEXT
+            if data.get("hasMedia"):
+                media_type = data.get("mediaType", "")
+                if "image" in media_type:
+                    msg_type = MessageType.PHOTO
+                elif "video" in media_type:
+                    msg_type = MessageType.VIDEO
+                elif "audio" in media_type or "ptt" in media_type:  # ptt = voice note
+                    msg_type = MessageType.VOICE
+                else:
+                    msg_type = MessageType.DOCUMENT
+            
+            # Determine chat type
+            is_group = data.get("isGroup", False)
+            chat_type = "group" if is_group else "dm"
+            
+            # Build source
+            source = self.build_source(
+                chat_id=data.get("chatId", ""),
+                chat_name=data.get("chatName"),
+                chat_type=chat_type,
+                user_id=data.get("senderId"),
+                user_name=data.get("senderName"),
+            )
+            
+            # Download media URLs to the local cache so agent tools
+            # can access them reliably regardless of URL expiration.
+            raw_urls = data.get("mediaUrls", [])
+            cached_urls = []
+            media_types = []
+            for url in raw_urls:
+                if msg_type == MessageType.PHOTO and url.startswith(("http://", "https://")):
+                    try:
+                        cached_path = await cache_image_from_url(url, ext=".jpg")
+                        cached_urls.append(cached_path)
+                        media_types.append("image/jpeg")
+                        print(f"[{self.name}] Cached user image: {cached_path}", flush=True)
+                    except Exception as e:
+                        print(f"[{self.name}] Failed to cache image: {e}", flush=True)
+                        cached_urls.append(url)
+                        media_types.append("image/jpeg")
+                elif msg_type == MessageType.PHOTO and os.path.isabs(url):
+                    # Local file path — bridge already downloaded the image
+                    cached_urls.append(url)
+                    media_types.append("image/jpeg")
+                    print(f"[{self.name}] Using bridge-cached image: {url}", flush=True)
+                elif msg_type == MessageType.VOICE and url.startswith(("http://", "https://")):
+                    try:
+                        cached_path = await cache_audio_from_url(url, ext=".ogg")
+                        cached_urls.append(cached_path)
+                        media_types.append("audio/ogg")
+                        print(f"[{self.name}] Cached user voice: {cached_path}", flush=True)
+                    except Exception as e:
+                        print(f"[{self.name}] Failed to cache voice: {e}", flush=True)
+                        cached_urls.append(url)
+                        media_types.append("audio/ogg")
+                elif msg_type == MessageType.VOICE and os.path.isabs(url):
+                    # Local file path — bridge already downloaded the audio
+                    cached_urls.append(url)
+                    media_types.append("audio/ogg")
+                    print(f"[{self.name}] Using bridge-cached audio: {url}", flush=True)
+                elif msg_type == MessageType.DOCUMENT and os.path.isabs(url):
+                    # Local file path — bridge already downloaded the document
+                    cached_urls.append(url)
+                    ext = Path(url).suffix.lower()
+                    mime = SUPPORTED_DOCUMENT_TYPES.get(ext, "application/octet-stream")
+                    media_types.append(mime)
+                    print(f"[{self.name}] Using bridge-cached document: {url}", flush=True)
+                elif msg_type == MessageType.VIDEO and os.path.isabs(url):
+                    cached_urls.append(url)
+                    media_types.append("video/mp4")
+                    print(f"[{self.name}] Using bridge-cached video: {url}", flush=True)
+                else:
+                    cached_urls.append(url)
+                    media_types.append("unknown")
+
+            # For text-readable documents, inject file content directly into
+            # the message text so the agent can read it inline.
+            # Cap at 100KB to match Telegram/Discord/Slack behaviour.
+            body = data.get("body", "")
+            if data.get("isGroup"):
+                body = self._clean_bot_mention_text(body, data)
+            MAX_TEXT_INJECT_BYTES = 100 * 1024
+            if msg_type == MessageType.DOCUMENT and cached_urls:
+                for doc_path in cached_urls:
+                    ext = Path(doc_path).suffix.lower()
+                    if ext in (".txt", ".md", ".csv", ".json", ".xml", ".yaml", ".yml", ".log", ".py", ".js", ".ts", ".html", ".css"):
+                        try:
+                            file_size = Path(doc_path).stat().st_size
+                            if file_size > MAX_TEXT_INJECT_BYTES:
+                                print(f"[{self.name}] Skipping text injection for {doc_path} ({file_size} bytes > {MAX_TEXT_INJECT_BYTES})", flush=True)
+                                continue
+                            content = Path(doc_path).read_text(errors="replace")
+                            fname = Path(doc_path).name
+                            # Remove the doc_<hex>_ prefix for display
+                            display_name = fname
+                            if "_" in fname:
+                                parts = fname.split("_", 2)
+                                if len(parts) >= 3:
+                                    display_name = parts[2]
+                            injection = f"[Content of {display_name}]:\n{content}"
+                            if body:
+                                body = f"{injection}\n\n{body}"
+                            else:
+                                body = injection
+                            print(f"[{self.name}] Injected text content from: {doc_path}", flush=True)
+                        except Exception as e:
+                            print(f"[{self.name}] Failed to read document text: {e}", flush=True)
+
+            return MessageEvent(
+                text=body,
+                message_type=msg_type,
+                source=source,
+                raw_message=data,
+                message_id=data.get("messageId"),
+                media_urls=cached_urls,
+                media_types=media_types,
+            )
+        except Exception as e:
+            print(f"[{self.name}] Error building event: {e}")
+            return None