lightclawbot 0.0.2__py3-none-any.whl

lightclawbot/__init__.py

@@ -0,0 +1,88 @@
+"""
+lightclawbot — LightClaw platform plugin for Hermes Agent.
+
+Registers the LightClaw adapter via the Hermes plugin discovery system.
+No source-code modifications to lighthouse-hermes are required — the adapter
+is discovered automatically when this package is placed under
+``~/.hermes/plugins/lightclawbot/`` or installed via pip (entry_points).
+"""
+
+import os
+
+
+def _get_version() -> str:
+    """Return package version from importlib.metadata, with fallback."""
+    try:
+        from importlib.metadata import version
+
+        return version("lightclawbot")
+    except Exception:
+        return "0.0.0"
+
+
+__version__ = _get_version()
+
+
+def _load_platform_hint() -> str:
+    """Return the LightClaw-specific LLM capability hint.
+
+    Only contents that are *unique* to LightClaw belong here.  The generic
+    ``MEDIA:/absolute/path/to/file`` protocol, supported extensions and
+    text post-processing are owned by the framework
+    (``BasePlatformAdapter.extract_media`` + ``PLATFORM_HINTS`` in
+    ``agent/prompt_builder.py``) and are intentionally NOT re-stated here.
+    """
+    return (
+        "You are on LightClaw, a WebSocket-based messaging platform. "
+        "Markdown formatting is supported (code blocks, bold, italic, tables). "
+        "You can send files natively by including MEDIA:/absolute/path/to/file "
+        "in your reply; the file is delivered to the user as an on-demand "
+        "download link (no need to upload or build https URLs yourself). "
+        "For cron jobs / reminders / scheduled tasks, always set "
+        "deliver='lightclawbot:<chat_id>' so results reach the user instead of "
+        "being saved locally."
+    )
+
+
+def _validate_config(config) -> bool:
+    """Check whether the platform config has enough info to connect."""
+    extra = getattr(config, "extra", {}) or {}
+    return bool(extra.get("api_keys") or os.getenv("LIGHTCLAW_API_KEY", ""))
+
+
+def _is_connected(config) -> bool:
+    """Check whether the platform is sufficiently configured (for status display)."""
+    extra = getattr(config, "extra", {}) or {}
+    return bool(extra.get("api_keys"))
+
+
+def register(ctx):
+    """Called by the Hermes plugin discovery system.
+
+    Registers the LightClaw platform adapter so that:
+      - Platform("lightclawbot") resolves to a dynamic enum member
+      - The gateway creates and connects a LightClawAdapter at startup
+      - send_message routes to the adapter via _send_via_adapter()
+      - Cron delivery to "lightclawbot:<chat_id>" works automatically
+      - User authorization respects LIGHTCLAW_ALLOWED_USERS env var
+    """
+    from .src import LightClawAdapter, check_lightclaw_requirements
+
+    ctx.register_platform(
+        name="lightclawbot",
+        label="LightClawBot",
+        adapter_factory=lambda cfg: LightClawAdapter(cfg),
+        check_fn=check_lightclaw_requirements,
+        validate_config=_validate_config,
+        is_connected=_is_connected,
+        required_env=["LIGHTCLAW_API_KEY"],
+        install_hint="See https://pypi.org/project/lightclawbot/",
+        allowed_users_env="LIGHTCLAW_ALLOWED_USERS",
+        allow_all_env="LIGHTCLAW_ALLOW_ALL_USERS",
+        max_message_length=4096,
+        emoji="⚡",
+        platform_hint=_load_platform_hint(),
+    )
+
+
+__all__ = ["register", "__version__"]

lightclawbot/plugin.yaml

@@ -0,0 +1,10 @@
+name: lightclawbot
+kind: platform
+version: 0.0.2
+description: >
+  LightClaw gateway adapter for Hermes Agent.
+  Connects to a LightClaw-compatible server via native WebSocket,
+  receiving user messages and sending AI responses back through the same protocol.
+author: lhanyun
+requires_env:
+  - LIGHTCLAW_API_KEY

lightclawbot/src/__init__.py

@@ -0,0 +1,37 @@
+"""
+LightClaw platform adapter for Hermes Agent.
+
+Connects to a LightClaw-compatible server via native WebSocket,
+receiving user messages and sending AI responses back through the same protocol.
+
+Protocol (post socket-rewrite):
+- Auth:      POST /cgi/ticket  → { code:0, data:{ client:{ extra:'{"botId":"..."}' }, ticket:"..." } }
+- Transport: Native WebSocket  wss://<domain>/ws/agent?ticket=<ticket>&enableMultiLogin=false
+- Framing:   Raw JSON  { "event": "<name>", "data": {...} }
+- Handshake: server sends { "event": "__handshake__", "data": { "id": "<socket_id>" } }
+- ACK:       server sends { "event": "message:ack", "data": { "relatedMsgId": "<msgId>" } }
+- Events:    message:private (bidirectional), history/sessions request/response
+- Kinds:     text, typing_start, stream_chunk, stream_end, typing_stop
+
+Package layout (mirrors lightclaw/src/):
+    config.py                ← constants + utils           (config.ts)
+    socket/reliable_emitter.py ← ACK-based send            (socket/reliable-emitter.ts)
+    socket/native_socket.py  ← connection loop             (socket/native-socket.ts)
+    inbound.py               ← inbound handler + media     (inbound.ts + media.ts)
+    outbound.py              ← send API                    (outbound.ts)
+    adapter.py               ← LightClawAdapter + singleton (gateway.ts)
+"""
+
+# Public API — kept stable so existing callers need no changes:
+#   gateway/platforms/__init__.py  → from .lightclaw import LightClawAdapter
+#   gateway/run.py                 → from gateway.platforms.lightclaw import LightClawAdapter, check_lightclaw_requirements
+#   tools/send_message_tool.py     → from gateway.platforms.lightclaw import get_active_adapter
+
+from .adapter import LightClawAdapter, get_active_adapter
+from .config import check_lightclaw_requirements
+
+__all__ = [
+    "LightClawAdapter",
+    "check_lightclaw_requirements",
+    "get_active_adapter",
+]

lightclawbot/src/adapter.py

@@ -0,0 +1,391 @@
+"""
+LightClaw adapter — main coordinator class and module singleton.
+Mirrors: src/gateway.ts
+"""
+
+import asyncio
+import json
+import logging
+import os
+from typing import Dict, List, Optional
+
+from gateway.platforms.base import BasePlatformAdapter
+from gateway.config import PlatformConfig
+
+from .config import (
+    API_PATH_TICKET,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_WS_BASE_URL,
+    EVENT_HANDSHAKE,
+    EVENT_HISTORY_REQUEST,
+    EVENT_MESSAGE_ACK,
+    EVENT_MESSAGE_PRIVATE,
+    EVENT_SESSIONS_REQUEST,
+    FileDownloadStatus,
+    KIND_FILE_DOWNLOAD,
+    generate_msg_id,
+)
+from .socket.reliable_emitter import ReliableEmitter
+from .socket.native_socket import NativeSocketMixin
+from .inbound import InboundMixin
+from .outbound import OutboundMixin
+from .download_handler import DownloadHandlerMixin
+from .tenancy import set_api_key_map
+
+logger = logging.getLogger(__name__)
+
+
+class LightClawAdapter(
+    NativeSocketMixin,
+    InboundMixin,
+    OutboundMixin,
+    DownloadHandlerMixin,
+    BasePlatformAdapter,
+):
+    """
+    Hermes gateway adapter for LightClaw-compatible servers.
+
+    Connects via native WebSocket (aiohttp), receives message:private events,
+    dispatches them to Hermes AIAgent, and sends responses back.
+
+    Protocol:
+    - Auth:      POST /cgi/ticket  → { code:0, data:{ client:{ extra:'{"botId":"..."}' }, ticket:"..." } }
+    - Transport: Native WebSocket  wss://<domain>/ws/agent?ticket=<ticket>&enableMultiLogin=false
+    - Framing:   Raw JSON  { "event": "<name>", "data": {...} }
+    - Handshake: server sends { "event": "__handshake__", "data": { "id": "<socket_id>" } }
+    - ACK:       server sends { "event": "message:ack", "data": { "relatedMsgId": "<msgId>" } }
+    """
+
+    # LightClaw uses non-streaming mode: edit_message is a no-op.
+    # Gateway won't create GatewayStreamConsumer when SUPPORTS_MESSAGE_EDITING=False.
+    SUPPORTS_MESSAGE_EDITING = False
+
+    def __init__(self, config: PlatformConfig):
+        from gateway.config import Platform
+        super().__init__(config, Platform.LIGHTCLAW)
+
+        extra = config.extra or {}
+
+        # API key — single source: env LIGHTCLAW_API_KEY.
+        # `extra.api_keys` (yaml list) is kept as a forward-compat hook for
+        # future multi-tenant deployments; not used in current deployments.
+        if extra.get("api_keys"):
+            self._api_keys: List[str] = list(extra["api_keys"])
+        else:
+            single = os.getenv("LIGHTCLAW_API_KEY", "").strip()
+            self._api_keys = [single] if single else []
+
+        # Server URLs — default to config.py constants; env overrides are kept
+        # as an operational escape hatch for private deployments / staging.
+        self._ws_base_url: str  = os.getenv("LIGHTCLAW_WS_URL",       DEFAULT_WS_BASE_URL)
+        self._api_base_url: str = os.getenv("LIGHTCLAW_API_BASE_URL", DEFAULT_API_BASE_URL)
+
+        # Identity (resolved on connect, stable across reconnects)
+        self._bot_client_id: str        = ""
+        self._api_key_map: Dict[str, str] = {}   # uin → apiKey (populated during _resolve_identity)
+
+        # Per-chat round msgId
+        self._round_ids: Dict[str, str] = {}
+
+        # Per-chat flag: whether the current round has already emitted a
+        # stream_chunk.  Used by OutboundMixin.send() to prepend "\n\n"
+        # before non-first chunks so front-end concatenation matches the
+        # visual breaks seen in the history view.
+        self._round_has_content: Dict[str, bool] = {}
+
+        # Per-chat agentId received from inbound messages (used by outbound to echo back)
+        self._incoming_agent_ids: Dict[str, str] = {}
+
+        # Per-chat list of attachments seen on inbound messages.
+        # Used by history persistence / outbound enrichment.  Entries are
+        # dicts of shape {"name", "mimeType", "url"} where url is always
+        # a `localfile://` URI (mirrors TS `publicMediaUrls`).
+        self._inbound_attachments: Dict[str, list] = {}
+
+        # Sessions directory for history reading
+        hermes_home = os.environ.get("HERMES_HOME") or os.path.expanduser("~/.hermes")
+        self._sessions_dir: str = (
+            extra.get("sessions_dir")
+            or os.getenv("LIGHTCLAW_SESSIONS_DIR")
+            or os.path.join(hermes_home, "sessions")
+        )
+
+        # Per-agent system prompts (multi-agent support)
+        # Configured in config.yaml → platforms.lightclaw.extra.agent_prompts
+        self._agent_prompts: Dict[str, str] = extra.get("agent_prompts") or {}
+
+        # Connection state
+        self._stopped           = False
+        self._socket_id: str    = ""
+        self._ws                = None          # aiohttp.ClientWebSocketResponse
+        self._session           = None          # aiohttp.ClientSession
+        self._connection_task: Optional[asyncio.Task] = None
+        self._reliable: Optional[ReliableEmitter]     = None
+        self._first_connect_event: asyncio.Event      = asyncio.Event()
+
+        # Pending ACK table (owned by NativeSocketMixin)
+        self._init_pending_acks()
+
+    # ------------------------------------------------------------------
+    # Identity resolution
+    # ------------------------------------------------------------------
+
+    async def _resolve_identity(self) -> None:
+        """
+        POST /cgi/ticket for each API key to get botClientId and the tenant's uin.
+
+        Response shape::
+
+            { code: 0,
+              data: {
+                id: "<uin>",                               # tenant user id
+                client: { extra: '{"botId":"<botId>"}' },  # JSON string
+                ticket: "..."
+              }
+            }
+
+        Populates:
+            self._bot_client_id   — any non-empty botId (first key wins)
+            self._api_key_map     — { uin: apiKey, ... }  (plus apiKey→apiKey
+                                     as a safety fallback when uin missing)
+
+        And pushes the result into :mod:`.tenancy` so tool handlers and the
+        download signal handler can resolve the correct apiKey per session.
+        """
+        import aiohttp
+
+        url = f"{self._api_base_url}{API_PATH_TICKET}"
+        bot_client_id = ""
+        api_key_map: Dict[str, str] = {}
+
+        async with aiohttp.ClientSession() as session:
+            for key in self._api_keys:
+                try:
+                    headers = {
+                        "authorization": f"Bearer {key}",
+                        "x-product":     "channel",
+                    }
+                    async with session.post(
+                        url, headers=headers,
+                        timeout=aiohttp.ClientTimeout(total=15),
+                    ) as resp:
+                        if resp.status != 200:
+                            logger.warning(
+                                "[lightclaw] %s HTTP %d for key ***%s",
+                                API_PATH_TICKET, resp.status, key[-4:],
+                            )
+                            continue
+                        data = await resp.json()
+                        if data.get("code") != 0:
+                            logger.warning(
+                                "[lightclaw] %s error for key ***%s: %s",
+                                API_PATH_TICKET, key[-4:], data.get("message"),
+                            )
+                            continue
+
+                        payload = data.get("data") or {}
+
+                        # Extract botClientId from data.client.extra (JSON-encoded)
+                        extra_str = (payload.get("client") or {}).get("extra", "")
+                        try:
+                            parsed = json.loads(extra_str) if extra_str else {}
+                            bid    = parsed.get("botId", "")
+                        except (json.JSONDecodeError, TypeError):
+                            bid = ""
+
+                        if bid and not bot_client_id:
+                            bot_client_id = bid
+
+                        # Extract the uin — this is what inbound messages use
+                        # as their `from` field and what we use to route the
+                        # per-tenant apiKey.
+                        uin = str(payload.get("id") or "").strip()
+                        if uin:
+                            api_key_map[uin] = key
+                            logger.info(
+                                "[lightclaw] Key ***%s mapped to uin=%s (botId=%s)",
+                                key[-4:], uin, bid or "?",
+                            )
+                        else:
+                            # No uin exposed → fall back to key→key so
+                            # resolve_effective_api_key() always finds
+                            # *something* for single-tenant deployments.
+                            api_key_map[key] = key
+                            logger.info(
+                                "[lightclaw] Key ***%s mapped (botId=%s, no uin returned)",
+                                key[-4:], bid or "?",
+                            )
+                except Exception as exc:
+                    logger.warning(
+                        "[lightclaw] Identity resolve failed for key ***%s: %s",
+                        key[-4:], exc,
+                    )
+
+        if not bot_client_id:
+            raise RuntimeError(
+                "Failed to resolve botClientId from any API key via POST /cgi/ticket"
+            )
+
+        self._bot_client_id = bot_client_id
+        self._api_key_map   = api_key_map
+
+        # Publish the map into the tenancy module so inbound/outbound/tool
+        # code can resolve the correct apiKey for a given sessionKey/senderId.
+        default_key = self._api_keys[0] if self._api_keys else ""
+        set_api_key_map(api_key_map, default_key)
+
+        logger.info(
+            "[lightclaw] Bot clientId: %s, %d key(s) mapped",
+            bot_client_id, len(api_key_map),
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        if not self._api_keys:
+            logger.error("[lightclaw] No API keys configured")
+            self._set_fatal_error("no_api_keys", "No API keys configured", retryable=False)
+            return False
+
+        try:
+            import aiohttp  # noqa: F401
+        except ImportError:
+            logger.error("[lightclaw] aiohttp not installed")
+            self._set_fatal_error("missing_deps", "aiohttp not installed", retryable=False)
+            return False
+
+        try:
+            await self._resolve_identity()
+        except Exception as exc:
+            logger.error("[lightclaw] Identity resolution failed: %s", exc)
+            self._set_fatal_error("identity_failed", str(exc), retryable=True)
+            return False
+
+        import aiohttp
+        self._stopped            = False
+        self._first_connect_event.clear()
+        self._session            = aiohttp.ClientSession()
+        self._reliable           = ReliableEmitter(
+            ws_emit=self._ws_emit,
+            ws_emit_with_timeout=self._ws_emit_with_timeout,
+            prefix="[lightclaw]",
+        )
+        self._connection_task    = asyncio.create_task(self._connection_loop())
+
+        # Wait for first successful WS connect
+        try:
+            await asyncio.wait_for(self._first_connect_event.wait(), timeout=20.0)
+        except asyncio.TimeoutError:
+            logger.error("[lightclaw] Timed out waiting for initial connection")
+            self._set_fatal_error("connect_timeout", "Initial connection timeout", retryable=True)
+            return False
+
+        _set_active_adapter(self)
+        return True
+
+    async def disconnect(self) -> None:
+        self._stopped = True
+        self._flush_pending_acks(ConnectionError("adapter disconnect"))
+        if self._reliable:
+            self._reliable.destroy()
+            self._reliable = None
+        if self._connection_task:
+            self._connection_task.cancel()
+            try:
+                await self._connection_task
+            except asyncio.CancelledError:
+                pass
+            self._connection_task = None
+        if self._ws and not self._ws.closed:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self._session = None
+        _set_active_adapter(None)
+        self._mark_disconnected()
+
+    # ------------------------------------------------------------------
+    # Raw message dispatch
+    # ------------------------------------------------------------------
+
+    async def _handle_raw(self, raw: str) -> None:
+        """
+        Dispatch incoming WebSocket frames.
+        Mirrors: src/socket/handlers.ts
+        """
+        try:
+            msg = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return
+
+        event = msg.get("event", "")
+        data  = msg.get("data") or {}
+
+        if event == EVENT_HANDSHAKE:
+            self._socket_id = data.get("id", "")
+            logger.info("[lightclaw] Handshake, socket_id=%s", self._socket_id)
+            return
+
+        if event == EVENT_MESSAGE_ACK:
+            related = data.get("relatedMsgId", "")
+            logger.debug("[lightclaw] ACK received: relatedMsgId=%s", related)
+            if related:
+                self._on_ws_ack(related)
+            return
+
+        if event == EVENT_MESSAGE_PRIVATE:
+            # ── file:download signalling — separate from the AI pipeline ──
+            # The front-end issues `kind=file:download, status=download_req`
+            # when the user clicks on a `localfile://` markdown link.  We
+            # handle it inline, never forwarding to handle_message().
+            if data.get("kind") == KIND_FILE_DOWNLOAD:
+                td = (data.get("extra") or {}).get("transferData") or {}
+                if td.get("status") == FileDownloadStatus.REQ:
+                    asyncio.create_task(self._handle_file_download_req(data))
+                # Any other status on a client→adapter frame is ignored:
+                # ready / url / error are only ever sent adapter→client.
+                return
+
+            # Spawn as background task: handle_message triggers the full
+            # agent pipeline (seconds to minutes), must not block the WS
+            # read loop.  Matches TS: void (async () => { await handler(msg); })()
+            asyncio.create_task(self._handle_incoming_message(data))
+            return
+
+        if event == EVENT_HISTORY_REQUEST:
+            await self._handle_history_request(data)
+            return
+
+        if event == EVENT_SESSIONS_REQUEST:
+            await self._handle_sessions_request(data)
+            return
+
+    # ------------------------------------------------------------------
+    # Misc
+    # ------------------------------------------------------------------
+
+    async def get_chat_info(self, chat_id: str) -> dict:
+        return {"name": f"LightClaw DM ({chat_id})", "type": "dm", "chat_id": chat_id}
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton accessor
+# ---------------------------------------------------------------------------
+
+_active_adapter: Optional[LightClawAdapter] = None
+
+
+def _set_active_adapter(adapter: Optional[LightClawAdapter]) -> None:
+    global _active_adapter
+    _active_adapter = adapter
+
+
+def get_active_adapter() -> Optional[LightClawAdapter]:
+    """Return the running LightClawAdapter singleton, or None if not started."""
+    return _active_adapter

lightclawbot/src/config.py

@@ -0,0 +1,149 @@
+"""
+LightClaw adapter — constants and utility functions.
+Mirrors: src/config.ts
+"""
+
+import os
+import time
+import uuid
+
+# ---------------------------------------------------------------------------
+# Channel key
+# ---------------------------------------------------------------------------
+
+CHANNEL_KEY = "lightclaw"
+
+# ---------------------------------------------------------------------------
+# Event names
+# ---------------------------------------------------------------------------
+
+EVENT_MESSAGE_PRIVATE   = "message:private"
+EVENT_MESSAGE_ACK       = "message:ack"
+EVENT_HANDSHAKE         = "__handshake__"
+EVENT_HISTORY_REQUEST   = "message:history:request"
+EVENT_HISTORY_RESPONSE  = "message:history:response"
+EVENT_SESSIONS_REQUEST  = "sessions:request"
+EVENT_SESSIONS_RESPONSE = "sessions:response"
+
+# ---------------------------------------------------------------------------
+# Server URLs / paths
+# ---------------------------------------------------------------------------
+
+DEFAULT_WS_BASE_URL  = "wss://lightai.cloud.tencent.com"
+DEFAULT_API_BASE_URL = "https://lightai.cloud.tencent.com"
+SOCKET_PATH          = "/ws/agent"
+API_PATH_TICKET      = "/cgi/ticket"
+
+# ---------------------------------------------------------------------------
+# Protocol limits
+# ---------------------------------------------------------------------------
+
+MAX_MESSAGE_LENGTH = 4096
+
+# Default agentId (mirrors DEFAULT_AGENT_ID in config.ts)
+DEFAULT_AGENT_ID = "main"
+
+# ---------------------------------------------------------------------------
+# Reconnect strategy (mirrors NativeSocketClient)
+# ---------------------------------------------------------------------------
+
+RECONNECT_DELAY_BASE = 1.0   # seconds
+RECONNECT_DELAY_MAX  = 30.0  # seconds
+
+# ---------------------------------------------------------------------------
+# ReliableEmitter config (mirrors reliable-emitter.ts)
+# ---------------------------------------------------------------------------
+
+EMIT_ACK_TIMEOUT      = 5.0   # seconds
+EMIT_MAX_RETRIES      = 3
+EMIT_RETRY_BASE_DELAY = 2.0   # seconds
+EMIT_RETRY_MAX_DELAY  = 15.0  # seconds
+EMIT_PENDING_MAX      = 500
+
+# ---------------------------------------------------------------------------
+# Media / file storage (mirrors src/config.ts media section)
+# ---------------------------------------------------------------------------
+
+# Remote file storage service base URL
+SERVER_UPLOAD_BASE_URL = "https://lightai.cloud.tencent.com"
+API_PATH_UPLOAD        = "/drive/save"       # POST multipart/form-data
+API_PATH_DOWNLOAD      = "/drive/preview"    # GET ?filePath=...
+
+# Single-file hard limit: 100 MB (mirrors MEDIA_MAX_BYTES)
+MEDIA_MAX_BYTES = 100 * 1024 * 1024
+# Upload/download timeout in seconds (mirrors UPLOAD_TIMEOUT=120_000ms)
+UPLOAD_TIMEOUT   = 120.0
+DOWNLOAD_TIMEOUT = 60.0
+
+# URI scheme for local-file references embedded in AI replies.
+# Front-end recognises this prefix and issues a file:download signal to
+# trigger on-demand upload + download.
+LOCALFILE_SCHEME = "localfile://"
+
+# Auth header `x-product` value (mirrors TS X_PRODUCT)
+X_PRODUCT = "channel"
+
+# ---------------------------------------------------------------------------
+# file:download signalling (kind field value + status enum)
+# ---------------------------------------------------------------------------
+
+KIND_FILE_DOWNLOAD = "file:download"
+
+
+class FileDownloadStatus:
+    """Lifecycle statuses carried inside `extra.transferData.status`.
+
+    Mirrors TS FILE_DOWNLOAD_STATUS enum.
+    """
+    REQ   = "download_req"    # client → bot
+    READY = "download_ready"  # bot → client (file confirmed, upload starting)
+    URL   = "download_url"    # bot → client (upload done, public URL ready)
+    ERROR = "download_error"  # bot → client (any failure)
+
+
+# ---------------------------------------------------------------------------
+# MIME type lookup (aligned 1:1 with TS guessMimeByExt)
+# ---------------------------------------------------------------------------
+
+_MIME_MAP = {
+    # image
+    ".png":  "image/png",
+    ".jpg":  "image/jpeg", ".jpeg": "image/jpeg",
+    ".gif":  "image/gif",
+    ".webp": "image/webp",
+    ".svg":  "image/svg+xml",
+    # audio
+    ".mp3":  "audio/mpeg",
+    ".wav":  "audio/wav",
+    ".ogg":  "audio/ogg",
+    # video
+    ".mp4":  "video/mp4",
+    ".webm": "video/webm",
+    # documents
+    ".pdf":  "application/pdf",
+    ".txt":  "text/plain",
+}
+
+
+# ---------------------------------------------------------------------------
+# Utility functions
+# ---------------------------------------------------------------------------
+
+def generate_msg_id() -> str:
+    """Generate a unique message ID."""
+    return f"hermes_{int(time.time() * 1000)}_{uuid.uuid4().hex[:8]}"
+
+
+def guess_mime(filename: str) -> str:
+    """Guess MIME type from file extension."""
+    ext = os.path.splitext(filename)[1].lower()
+    return _MIME_MAP.get(ext, "application/octet-stream")
+
+
+def check_lightclaw_requirements() -> bool:
+    """Check if aiohttp is available (python-socketio no longer needed)."""
+    try:
+        import aiohttp  # noqa: F401
+        return True
+    except ImportError:
+        return False