coding-bridge 2026.7.3.0__tar.gz → 2026.7.3.2__tar.gz

{coding_bridge-2026.7.3.0 → coding_bridge-2026.7.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-bridge
-Version: 2026.7.3.0
+Version: 2026.7.3.2
 Summary: Node daemon for AceDataCloud Coding Bridge — run Claude Code on your own machine and drive it from the web.
 Project-URL: Homepage, https://github.com/AceDataCloud/CodingBridge
 Project-URL: Issues, https://github.com/AceDataCloud/CodingBridge/issues
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Requires-Dist: claude-agent-sdk>=0.1.0
 Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Requires-Dist: websockets<14,>=12
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -25,6 +26,7 @@ Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: qr
 Requires-Dist: qrcode>=7.4; extra == 'qr'
+Provides-Extra: wechat
 Description-Content-Type: text/markdown
 
 # Coding Bridge Agent

{coding_bridge-2026.7.3.0 → coding_bridge-2026.7.3.2}/coding_bridge/channels/__init__.py

@@ -17,13 +17,25 @@ from .base import (
     MessageHandler,
     SendResult,
 )
+from .config import (
+    ChannelsConfig,
+    ConfigError,
+    WeChatInstanceConfig,
+    load_channels_config,
+    parse_channels_config,
+)
 from .dispatcher import SessionDispatcher
 
 __all__ = [
     "ChannelAdapter",
     "ChannelTarget",
+    "ChannelsConfig",
+    "ConfigError",
     "IncomingMessage",
     "MessageHandler",
     "SendResult",
     "SessionDispatcher",
+    "WeChatInstanceConfig",
+    "load_channels_config",
+    "parse_channels_config",
 ]

{coding_bridge-2026.7.3.0 → coding_bridge-2026.7.3.2}/coding_bridge/channels/base.py

@@ -1,7 +1,7 @@
 """Channel-adapter Protocol and value objects shared by every messenger.
 
-An adapter is the thin glue between one external messaging system (WeChat via
-Wisdom, later Telegram / Discord …) and the dispatcher. It never spawns provider
+An adapter is the thin glue between one external messaging system (WeChat,
+later Telegram / Discord …) and the dispatcher. It never spawns provider
 processes, tracks sessions, or evaluates prompts — those live in
 ``SessionDispatcher`` and reuse the existing ``Session`` / ``Provider`` machinery
 so the browser and WeChat paths share one coding-agent implementation.
@@ -9,7 +9,7 @@ so the browser and WeChat paths share one coding-agent implementation.
 Design invariants:
 
 * ``instance_id`` is opaque to the dispatcher but MUST be stable per adapter
-  instance (per configured Wisdom endpoint, per Bot token, …) so multi-instance
+  instance (per configured WeChat gateway endpoint, per Bot token, …) so multi-instance
   deployments can namespace dedup keys, log fields, and outbox rows.
 * ``send()`` is expected to return a ``SendResult`` — never raise on a delivery
   failure — because delivery is best-effort and the dispatcher records the
@@ -29,8 +29,8 @@ class ChannelTarget:
 
     ``conversation_id`` is the ID of the "room" — a WeChat private chat wxid, a
     group room id, a Telegram chat_id, etc. ``reply_to_id`` is set only when the
-    external protocol supports a reply-to primitive worth carrying (WeChat
-    Wisdom's ``msg_id``, Telegram's ``reply_to_message_id``); adapters that lack
+    external protocol supports a reply-to primitive worth carrying (the WeChat
+    gateway's ``msg_id``, Telegram's ``reply_to_message_id``); adapters that lack
     one leave it ``None``.
     """
 
@@ -54,7 +54,7 @@ class IncomingMessage:
     target: ChannelTarget
     text: str
     msg_type: str
-    direction: str  # ``inbound`` / ``outbound`` (per Wisdom's schema)
+    direction: str  # ``inbound`` / ``outbound`` (per the gateway's schema)
     upstream_id: str | None = None
     received_at_ms: int | None = None
     raw: dict[str, Any] = field(default_factory=dict)

coding_bridge-2026.7.3.2/coding_bridge/channels/config.py

@@ -0,0 +1,282 @@
+"""Channels config schema — parses ``~/.ace-bridge/channels.toml``.
+
+Split from ``coding_bridge.config`` on purpose: channels are optional and evolve
+independently of the core node settings. Users who never touch channels never
+load this module.
+
+Schema (fail-fast; unknown keys raise):
+
+.. code-block:: toml
+
+    [channels]
+    # (reserved for future globals)
+
+    [[channels.wechat]]
+    instance_id = "beijing-cvm"        # required, unique per file
+    base_url = "http://82.156.126.14:8000"  # required, http:// or https://
+    token_env = "WECHAT_TOKEN_BEIJING"   # required unless token_file is set
+    token_file = "/run/secrets/beijing"  # optional alternative to token_env
+    enabled = false                      # default false — explicit opt-in
+    default_provider = "claude"          # optional override for this instance
+
+Design notes:
+
+* The **token itself never lives in the TOML file** — the file references an
+  env var name (`token_env`) or a secrets-file path (`token_file`). This
+  matches the deployment templates in P8 (systemd EnvironmentFile,
+  launchd, Windows service credentials store).
+* `enabled = false` is the default so accidentally shipping a `channels.toml`
+  never puts an unsupervised bot online.
+* Unknown keys raise — a typo like `intance_id` or `allowlist_typo` should
+  fail loudly at boot, not silently degrade to unsafe defaults.
+* A hard 1 MB cap on the TOML file guards against accidentally pointing at
+  ``/dev/urandom`` or a runaway log.
+* ``base_url`` may not contain embedded userinfo (``http://user:pass@host``);
+  credentials go through ``token_env``/``token_file`` only.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+try:
+    import tomllib as _toml
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as _toml  # type: ignore[import-not-found]
+
+_WECHAT_KEYS = frozenset(
+    {"instance_id", "base_url", "token_env", "token_file", "enabled", "default_provider"}
+)
+_CHANNELS_KEYS = frozenset({"wechat"})
+
+# Cap the TOML file size so a misconfigured `channels.toml` pointing at
+# `/dev/urandom` or similar can't OOM the daemon at startup.
+_MAX_TOML_BYTES = 1_000_000
+
+# Cap the token file so `token_file = "/dev/urandom"` also can't OOM us.
+# Real API tokens are ~64–512 bytes; 64 KB is generous.
+_MAX_TOKEN_BYTES = 64 * 1024
+
+
+class ConfigError(ValueError):
+    """Raised for any schema violation — never caught silently."""
+
+
+@dataclass(frozen=True)
+class WeChatInstanceConfig:
+    """One `[[channels.wechat]]` block."""
+
+    instance_id: str
+    base_url: str
+    token_env: str | None = None
+    token_file: str | None = None
+    enabled: bool = False
+    default_provider: str | None = None
+
+    def resolve_token(self, environ: dict[str, str] | None = None) -> str:
+        """Load the token from env var or secrets file. Never logs it.
+
+        Raises ``ConfigError`` with a **redacted** message if the token can't
+        be resolved — the message references the env-var *name* or file path,
+        never the value.
+        """
+        env = environ if environ is not None else dict(os.environ)
+        if self.token_env:
+            token = env.get(self.token_env)
+            if not token:
+                raise ConfigError(
+                    f"wechat instance {self.instance_id!r}: env var "
+                    f"{self.token_env!r} is unset or empty"
+                )
+            return token
+        if self.token_file:
+            path = Path(self.token_file).expanduser()
+            try:
+                # Reject anything that isn't a regular file up front so a
+                # symlink pointing at a directory / device raises a clean
+                # ConfigError instead of a raw OSError / UnicodeDecodeError.
+                if not path.is_file():
+                    raise ConfigError(
+                        f"wechat instance {self.instance_id!r}: token_file "
+                        f"{str(path)!r} is not a regular file"
+                    )
+                size = path.stat().st_size
+                if size > _MAX_TOKEN_BYTES:
+                    raise ConfigError(
+                        f"wechat instance {self.instance_id!r}: token_file "
+                        f"{str(path)!r} exceeds {_MAX_TOKEN_BYTES}-byte limit"
+                    )
+                raw = path.read_bytes()
+            except OSError as exc:
+                raise ConfigError(
+                    f"wechat instance {self.instance_id!r}: cannot read "
+                    f"token_file {str(path)!r}: {exc.__class__.__name__}"
+                ) from None
+            try:
+                token = raw.decode("utf-8").strip()
+            except UnicodeDecodeError:
+                raise ConfigError(
+                    f"wechat instance {self.instance_id!r}: token_file "
+                    f"{str(path)!r} is not valid UTF-8"
+                ) from None
+            if not token:
+                raise ConfigError(
+                    f"wechat instance {self.instance_id!r}: token_file "
+                    f"{str(path)!r} is empty"
+                )
+            return token
+        raise ConfigError(
+            f"wechat instance {self.instance_id!r}: either token_env or "
+            "token_file must be set"
+        )
+
+
+@dataclass(frozen=True)
+class ChannelsConfig:
+    """Root of the channels config file."""
+
+    wechat: tuple[WeChatInstanceConfig, ...] = field(default_factory=tuple)
+
+    @property
+    def enabled_wechat(self) -> tuple[WeChatInstanceConfig, ...]:
+        return tuple(inst for inst in self.wechat if inst.enabled)
+
+
+def _require(kind: str, block: dict[str, Any], key: str) -> Any:
+    value = block.get(key)
+    if value is None or value == "":
+        raise ConfigError(f"{kind}: required field {key!r} is missing or empty")
+    return value
+
+
+def _parse_wechat(block: dict[str, Any], index: int) -> WeChatInstanceConfig:
+    unknown = set(block.keys()) - _WECHAT_KEYS
+    if unknown:
+        raise ConfigError(
+            f"[[channels.wechat]] #{index}: unknown key(s) {sorted(unknown)!r}"
+        )
+    instance_id = _require(f"[[channels.wechat]] #{index}", block, "instance_id")
+    base_url = _require(f"[[channels.wechat]] #{index}", block, "base_url")
+    if not isinstance(instance_id, str):
+        raise ConfigError(f"[[channels.wechat]] #{index}: instance_id must be a string")
+    if not isinstance(base_url, str):
+        raise ConfigError(f"[[channels.wechat]] #{index}: base_url must be a string")
+    if not (base_url.startswith("http://") or base_url.startswith("https://")):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: base_url must start with "
+            "http:// or https://"
+        )
+    # Reject `http://user:pass@host` so tokens never travel via base_url.
+    # `urlparse` folds userinfo into `netloc`; a bare `@` in the path segment
+    # after the host doesn't count because it's not in netloc.
+    if "@" in urlparse(base_url).netloc:
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: base_url must not contain "
+            "embedded credentials (user:pass@host); use token_env/token_file"
+        )
+    token_env = block.get("token_env")
+    token_file = block.get("token_file")
+    if token_env is not None and not isinstance(token_env, str):
+        raise ConfigError(f"[[channels.wechat]] {instance_id!r}: token_env must be a string")
+    if token_file is not None and not isinstance(token_file, str):
+        raise ConfigError(f"[[channels.wechat]] {instance_id!r}: token_file must be a string")
+    if token_env and token_file:
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: set token_env OR token_file, not both"
+        )
+    enabled = block.get("enabled", False)
+    # `isinstance(True, int) is True` in Python, so guard against the reverse
+    # (`enabled = 1` in TOML → int → we want a hard error, not a silent truthy).
+    if not isinstance(enabled, bool):
+        raise ConfigError(f"[[channels.wechat]] {instance_id!r}: enabled must be a bool")
+    default_provider = block.get("default_provider")
+    if default_provider is not None and not isinstance(default_provider, str):
+        raise ConfigError(
+            f"[[channels.wechat]] {instance_id!r}: default_provider must be a string"
+        )
+    return WeChatInstanceConfig(
+        instance_id=instance_id,
+        base_url=base_url.rstrip("/"),
+        token_env=token_env,
+        token_file=token_file,
+        enabled=enabled,
+        default_provider=default_provider,
+    )
+
+
+def parse_channels_config(data: dict[str, Any]) -> ChannelsConfig:
+    """Parse an already-decoded TOML mapping. Public for test use."""
+    channels = data.get("channels")
+    if channels is None:
+        return ChannelsConfig()
+    if not isinstance(channels, dict):
+        raise ConfigError("[channels]: must be a table")
+    unknown = set(channels.keys()) - _CHANNELS_KEYS
+    if unknown:
+        raise ConfigError(f"[channels]: unknown key(s) {sorted(unknown)!r}")
+
+    wechat_blocks = channels.get("wechat", [])
+    if not isinstance(wechat_blocks, list):
+        raise ConfigError("[[channels.wechat]]: must be an array of tables")
+
+    parsed: list[WeChatInstanceConfig] = []
+    seen_ids: set[str] = set()
+    for i, block in enumerate(wechat_blocks):
+        if not isinstance(block, dict):
+            raise ConfigError(f"[[channels.wechat]] #{i}: must be a table")
+        inst = _parse_wechat(block, i)
+        if inst.instance_id in seen_ids:
+            raise ConfigError(
+                f"[[channels.wechat]]: duplicate instance_id {inst.instance_id!r}"
+            )
+        seen_ids.add(inst.instance_id)
+        parsed.append(inst)
+    return ChannelsConfig(wechat=tuple(parsed))
+
+
+def load_channels_config(path: Path) -> ChannelsConfig:
+    """Read + parse a TOML file. Missing file → empty config (no channels).
+
+    Wraps every filesystem / decode error in ``ConfigError`` so the daemon
+    can surface a clean startup message instead of an unhandled traceback.
+    """
+    if not path.exists():
+        return ChannelsConfig()
+    if not path.is_file():
+        raise ConfigError(f"channels config {str(path)!r} is not a regular file")
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        raise ConfigError(
+            f"channels config {str(path)!r}: cannot stat: {exc.__class__.__name__}"
+        ) from None
+    if size > _MAX_TOML_BYTES:
+        raise ConfigError(
+            f"channels config {str(path)!r} exceeds {_MAX_TOML_BYTES}-byte limit "
+            f"({size} bytes)"
+        )
+    try:
+        with path.open("rb") as f:
+            data = _toml.load(f)
+    except _toml.TOMLDecodeError as exc:
+        raise ConfigError(
+            f"channels config {str(path)!r} is not valid TOML: {exc}"
+        ) from None
+    except OSError as exc:
+        raise ConfigError(
+            f"channels config {str(path)!r}: cannot read: {exc.__class__.__name__}"
+        ) from None
+    return parse_channels_config(data)
+
+
+__all__ = [
+    "ChannelsConfig",
+    "ConfigError",
+    "WeChatInstanceConfig",
+    "load_channels_config",
+    "parse_channels_config",
+]

coding_bridge-2026.7.3.2/coding_bridge/channels/wechat/__init__.py

@@ -0,0 +1,26 @@
+"""WeChat channel adapter — personal-WeChat gateway integration.
+
+The WeChat adapter is CodingBridge's first :class:`~coding_bridge.channels.ChannelAdapter`
+concrete implementation. It talks to a personal-WeChat gateway (FastAPI, hosted
+on a CVM) with two edges:
+
+* ``wss://<host>/ws?token=<TOKEN>`` — the gateway broadcasts every WeChat message
+  event as JSON ``{"event": "message.new", "data": {...}}``. The adapter
+  filters ``direction=inbound`` structurally (echoes / outbound get skipped)
+  and hands anything left to the dispatcher — policy (trigger prefix,
+  allowlist, rate limit) lives one layer up in P7.
+* ``POST /api/messages/send`` with ``Authorization: Bearer <TOKEN>`` — returns
+  ``202 Accepted`` because the gateway queues a background UI task. P2 fires and
+  forgets; P7 will poll ``/api/messages/tasks/{id}`` for delivery
+  confirmation.
+
+The adapter is import-safe without extras — it delegates to :mod:`websockets`
+and :mod:`httpx`, both already required by CodingBridge core. The
+``[wechat]`` extras marker exists only so users can express intent
+(``pip install coding-bridge[wechat]``); no additional wheels are pulled.
+"""
+
+from .adapter import WeChatAdapter
+from .client import WeChatClient
+
+__all__ = ["WeChatAdapter", "WeChatClient"]

coding_bridge-2026.7.3.2/coding_bridge/channels/wechat/adapter.py

@@ -0,0 +1,222 @@
+"""``WeChatAdapter`` — subscribes to the WeChat gateway's WS feed and dispatches messages.
+
+The adapter is a *pure wire*: it opens the WSS connection, decodes
+``message.new`` events, filters out anything that isn't a real inbound WeChat
+message (echoes, outbound, non-text types), and hands the rest to the
+dispatcher-installed handler. Policy — trigger prefix, sender allowlist, rate
+limit, dedup — lives in the abuse-control layer landing with P7.
+
+Design notes:
+
+* Reconnect loop uses bounded exponential backoff (0.5s → 30s) so a gateway
+  restart doesn't take the adapter down.
+* The token appears only in the WS query string and the REST client's
+  ``Authorization`` header. Logs redact both — every URL echoed to the logs
+  runs through :func:`_redact_url` first, and the REST client never echoes
+  the token in error messages.
+* ``aclose()`` is idempotent and reentrant — closing an already-closed
+  adapter is a no-op and never raises.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import re
+from typing import Any
+from urllib.parse import urlparse, urlunparse
+
+import websockets
+
+from ..base import ChannelTarget, IncomingMessage, MessageHandler, SendResult
+from .client import WeChatClient
+
+logger = logging.getLogger("coding-bridge.channels.wechat")
+
+_INITIAL_BACKOFF_S = 0.5
+_MAX_BACKOFF_S = 30.0
+_HTTP_TO_WS = {"http": "ws", "https": "wss"}
+# Any query-string token or password segment is redacted before logging.
+_TOKEN_QS_RE = re.compile(r"([?&](?:token|api_token|password)=)([^&]+)", re.IGNORECASE)
+# ``user:pass@`` in the netloc is also stripped — a misconfigured base_url with
+# embedded credentials would otherwise survive query-string redaction.
+_USERINFO_RE = re.compile(r"(?<=://)([^/@]+)@")
+
+
+def _redact_url(url: str) -> str:
+    """Strip token / password from URL query string + userinfo for safe logging."""
+    return _USERINFO_RE.sub("<redacted>@", _TOKEN_QS_RE.sub(r"\1<redacted>", url))
+
+
+def _build_ws_url(base_url: str, token: str) -> str:
+    parsed = urlparse(base_url.rstrip("/"))
+    scheme = _HTTP_TO_WS.get(parsed.scheme, parsed.scheme or "ws")
+    path = (parsed.path or "").rstrip("/") + "/ws"
+    return urlunparse((scheme, parsed.netloc, path, "", f"token={token}", ""))
+
+
+def _parse_incoming(payload: dict[str, Any]) -> IncomingMessage | None:
+    """Best-effort parser for the gateway's ``message.new`` event.
+
+    Returns ``None`` for anything the dispatcher should never see (outbound
+    echoes, unknown event types, missing required fields). Downstream policy
+    (allowlist / trigger prefix) runs against the returned message.
+    """
+    event = payload.get("event")
+    data = payload.get("data")
+    if event != "message.new" or not isinstance(data, dict):
+        return None
+    direction = data.get("direction")
+    if direction != "inbound":
+        return None
+    text = data.get("text")
+    if not isinstance(text, str) or not text:
+        return None
+    target = data.get("target")
+    if not isinstance(target, str) or not target:
+        return None
+
+    return IncomingMessage(
+        sender_id=str(data.get("sender_id") or target),
+        sender_name=data.get("sender_name") if isinstance(data.get("sender_name"), str) else None,
+        target=ChannelTarget(
+            conversation_id=target,
+            conversation_type=str(data.get("conversation_type") or "private"),
+            reply_to_id=data.get("msg_id") if isinstance(data.get("msg_id"), str) else None,
+        ),
+        text=text,
+        msg_type=str(data.get("msg_type") or "text"),
+        direction=direction,
+        upstream_id=data.get("msg_id") if isinstance(data.get("msg_id"), str) else None,
+        received_at_ms=int(data["timestamp"]) if isinstance(data.get("timestamp"), int) else None,
+        raw=dict(data),
+    )
+
+
+class WeChatAdapter:
+    """One WeChat gateway endpoint = one WeChat instance = one adapter.
+
+    Runs a WSS receive loop; delivery is done via the injected
+    :class:`WeChatClient`. Only intended for private / group WeChat text
+    messages — image / file / audio events are silently dropped in P2 (P8+
+    can add multi-modal handling once the dispatcher supports attachments).
+    """
+
+    name = "wechat"
+
+    def __init__(
+        self,
+        *,
+        instance_id: str,
+        base_url: str,
+        token: str,
+        client: WeChatClient | None = None,
+        ws_connect: Any | None = None,
+        stop_event: asyncio.Event | None = None,
+    ) -> None:
+        if not instance_id:
+            raise ValueError("instance_id must be a non-empty string")
+        if not base_url:
+            raise ValueError("base_url must be a non-empty string")
+        if not token:
+            raise ValueError("token must be a non-empty string")
+        self.instance_id = instance_id
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._client = client or WeChatClient(base_url, token)
+        # ``ws_connect`` is injected only by tests; production uses
+        # :func:`websockets.connect` directly.
+        self._ws_connect = ws_connect or websockets.connect
+        self._stop = stop_event or asyncio.Event()
+        self._handler: MessageHandler | None = None
+        self._owns_client = client is None
+        # Held for the lifetime of one WS session so ``aclose()`` can force
+        # the receive loop to unblock without waiting for a gateway heartbeat.
+        self._active_ws: Any | None = None
+
+    def set_handler(self, handler: MessageHandler) -> None:
+        self._handler = handler
+
+    async def run(self) -> None:
+        if self._handler is None:
+            raise RuntimeError("WeChatAdapter.run() called before set_handler()")
+        ws_url = _build_ws_url(self._base_url, self._token)
+        backoff = _INITIAL_BACKOFF_S
+        while not self._stop.is_set():
+            try:
+                logger.info(
+                    "wechat: connecting instance=%s url=%s",
+                    self.instance_id,
+                    _redact_url(ws_url),
+                )
+                async with self._ws_connect(ws_url) as ws:
+                    logger.info("wechat: connected instance=%s", self.instance_id)
+                    backoff = _INITIAL_BACKOFF_S
+                    self._active_ws = ws
+                    try:
+                        await self._consume(ws)
+                    finally:
+                        self._active_ws = None
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                if self._stop.is_set():
+                    return
+                logger.warning(
+                    "wechat: WS loop error instance=%s err=%s.%s; reconnect in %.1fs",
+                    self.instance_id,
+                    exc.__class__.__module__,
+                    exc.__class__.__name__,
+                    backoff,
+                )
+                try:
+                    await asyncio.wait_for(self._stop.wait(), timeout=backoff)
+                    return  # stop signaled during backoff
+                except asyncio.TimeoutError:
+                    pass
+                backoff = min(backoff * 2, _MAX_BACKOFF_S)
+
+    async def _consume(self, ws: Any) -> None:
+        async for raw in ws:
+            if self._stop.is_set():
+                return
+            try:
+                payload = json.loads(raw) if isinstance(raw, (str, bytes, bytearray)) else raw
+            except (ValueError, TypeError):
+                logger.debug("wechat: skipped non-JSON frame instance=%s", self.instance_id)
+                continue
+            if not isinstance(payload, dict):
+                continue
+            msg = _parse_incoming(payload)
+            if msg is None:
+                continue
+            assert self._handler is not None  # invariant checked in run()
+            try:
+                await self._handler(msg, self)
+            except Exception:
+                # A single handler failure must not kill the receive loop —
+                # the dispatcher already logs its own errors, and abusive
+                # senders shouldn't be able to DoS the adapter.
+                logger.exception("wechat: handler error instance=%s", self.instance_id)
+
+    async def send(
+        self, target: ChannelTarget, text: str, *, reply_to: str | None = None
+    ) -> SendResult:
+        return await self._client.send_message(target, text, reply_to=reply_to)
+
+    async def aclose(self) -> None:
+        """Idempotent shutdown; safe to call from multiple coroutines."""
+        self._stop.set()
+        ws = self._active_ws
+        if ws is not None:
+            close = getattr(ws, "close", None)
+            if callable(close):
+                with contextlib.suppress(Exception):
+                    result = close()
+                    if asyncio.iscoroutine(result):
+                        await result
+        if self._owns_client:
+            with contextlib.suppress(Exception):
+                await self._client.aclose()