miti-agent-sdk 0.1.0__py3-none-any.whl

miti_agent_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""Miti Agent SDK – connect third-party agents to Miti IM."""
+
+import logging
+
+from .agent import MitiAgent
+from .auth import AuthClient, AuthError
+from .gateway import GatewayClient
+from .message import ApiError, HistoryClient, MessageClient
+from .models import (
+    AgentEvent,
+    EventHeader,
+    EventMessage,
+    EventSender,
+    GroupAtEvent,
+    HistoryMessage,
+    MessageEvent,
+)
+from .stream import build_stream_full_markdown
+
+__all__ = [
+    "MitiAgent",
+    "AuthClient",
+    "AuthError",
+    "GatewayClient",
+    "MessageClient",
+    "HistoryClient",
+    "ApiError",
+    "AgentEvent",
+    "EventHeader",
+    "EventMessage",
+    "EventSender",
+    "GroupAtEvent",
+    "HistoryMessage",
+    "MessageEvent",
+    "build_stream_full_markdown",
+    "enable_logging",
+]
+
+__version__ = "0.1.0"
+
+# Library best practice: NullHandler prevents "No handlers found" warnings.
+# Users must configure logging themselves or call enable_logging() below.
+logging.getLogger("miti_agent_sdk").addHandler(logging.NullHandler())
+
+
+def enable_logging(
+    level: int = logging.INFO,
+    fmt: str = "%(asctime)s [%(name)s] %(levelname)s %(message)s",
+) -> None:
+    """Enable SDK logging to stderr with a human-readable format.
+
+    Call this before ``agent.run()`` to see SDK internal activity::
+
+        import miti_agent_sdk
+        miti_agent_sdk.enable_logging()           # INFO level
+        miti_agent_sdk.enable_logging(logging.DEBUG)  # verbose
+
+    If you already have ``logging.basicConfig()`` or a framework logger
+    configured, you don't need this — SDK logs will flow through the
+    ``miti_agent_sdk.*`` logger hierarchy automatically.
+    """
+    root = logging.getLogger("miti_agent_sdk")
+    root.setLevel(level)
+    if not any(isinstance(h, logging.StreamHandler) for h in root.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(fmt))
+        root.addHandler(handler)

miti_agent_sdk/agent.py

@@ -0,0 +1,272 @@
+"""MitiAgent – top-level facade that wires AuthClient, GatewayClient,
+MessageClient, and HistoryClient together."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import signal
+from typing import Any, Callable, Optional
+
+import aiohttp
+
+from .auth import AuthClient
+from .gateway import EventHandler, GatewayClient
+from .message import HistoryClient, MessageClient
+from .models import AgentEvent, HistoryMessage
+
+logger = logging.getLogger("miti_agent_sdk")
+
+_BASE_URL_ENV = "MITI_API_BASE_URL"
+_DEFAULT_BASE_URL = "https://www.miti.chat/chat"
+
+
+class MitiAgent:
+    """One-stop entry point for third-party agents connecting to Miti.
+
+    Usage::
+
+        agent = MitiAgent(app_id="cli_xxx", app_secret="secret_xxx")
+
+        @agent.on_message
+        async def handle(event: AgentEvent):
+            await event.reply("got it!")
+
+        agent.run()
+
+    Parameters
+    ----------
+    app_id : str
+        Agent application ID.
+    app_secret : str
+        Agent application secret.
+    base_url : str
+        Miti API base URL. Defaults to the ``MITI_API_BASE_URL`` environment
+        variable when set, otherwise ``https://www.miti.chat/chat``.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        base_url: Optional[str] = None,
+    ):
+        self._base_url = (
+            base_url or os.getenv(_BASE_URL_ENV) or _DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        if not _is_tls_or_localhost(self._base_url):
+            raise ValueError(
+                f"base_url must use https:// (got {self._base_url!r}). "
+                f"Only localhost / 127.0.0.1 is allowed over http:// for local development."
+            )
+
+        self._session: Optional[aiohttp.ClientSession] = None
+
+        self._auth = AuthClient(
+            app_id=app_id,
+            app_secret=app_secret,
+            base_url=self._base_url,
+        )
+        self._gateway = GatewayClient(auth=self._auth, base_url=self._base_url)
+        self._msg_client: Optional[MessageClient] = None
+        self._history_client: Optional[HistoryClient] = None
+
+    # ------------------------------------------------------------------
+    # Decorator API
+    # ------------------------------------------------------------------
+
+    def on_message(self, fn: EventHandler) -> EventHandler:
+        """Decorator: register *fn* as the handler for single-chat messages
+        (``im.message.receive``).
+
+        ::
+
+            @agent.on_message
+            async def handle(event):
+                await event.reply("hello")
+        """
+        self._gateway.on("im.message.receive", fn)
+        return fn
+
+    def on_group_at(self, fn: EventHandler) -> EventHandler:
+        """Decorator: register *fn* as the handler for group-chat @ messages
+        (``im.message.group_at``).
+
+        ::
+
+            @agent.on_group_at
+            async def handle(event):
+                await event.reply("group reply")
+        """
+        self._gateway.on("im.message.group_at", fn)
+        return fn
+
+    def on(self, event_type: str) -> Callable[[EventHandler], EventHandler]:
+        """Generic decorator for any event type::
+
+            @agent.on("im.message.receive")
+            async def handle(event):
+                ...
+        """
+        def decorator(fn: EventHandler) -> EventHandler:
+            self._gateway.on(event_type, fn)
+            return fn
+        return decorator
+
+    # ------------------------------------------------------------------
+    # REST helpers
+    # ------------------------------------------------------------------
+
+    async def send_message(
+        self,
+        *,
+        to_user_id: Optional[str] = None,
+        to_group_id: Optional[str] = None,
+        msg_type: str = "text",
+        content: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send a message via ``POST /agent/v1/messages/send``.
+
+        Supported ``msg_type`` values:
+
+        - ``text`` — plain text (contentType 101)
+        - ``stream_full`` — Markdown reply (contentType 125); use
+          :func:`miti_agent_sdk.build_stream_full_markdown` or pass
+          ``{"markdown": "...", "ask_msg_id": "..."}``
+
+        Returns the ``data`` dict from the response.
+        """
+        client = self._ensure_msg_client()
+        return await client.send(
+            to_user_id=to_user_id,
+            to_group_id=to_group_id,
+            msg_type=msg_type,
+            content=content,
+        )
+
+    async def send_markdown_reply(
+        self,
+        markdown: str,
+        *,
+        to_user_id: Optional[str] = None,
+        to_group_id: Optional[str] = None,
+        ask_msg_id: str = "",
+    ) -> dict[str, Any]:
+        """Send a Markdown reply as ``stream_full`` (contentType 125)."""
+        from .stream import build_stream_full_markdown
+
+        return await self.send_message(
+            to_user_id=to_user_id,
+            to_group_id=to_group_id,
+            msg_type="stream_full",
+            content=build_stream_full_markdown(markdown, ask_msg_id),
+        )
+
+    async def get_history(
+        self,
+        conversation_id: str,
+        limit: int = 10,
+    ) -> list[HistoryMessage]:
+        """Fetch conversation history via ``GET /agent/v1/messages/history``."""
+        client = self._ensure_history_client()
+        return await client.get(conversation_id=conversation_id, limit=limit)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Blocking entry point.  Starts the event loop, connects the
+        WebSocket gateway, and runs until interrupted (Ctrl-C / SIGTERM).
+
+        Internally calls :meth:`run_async`.
+        """
+        try:
+            asyncio.run(self.run_async())
+        except KeyboardInterrupt:
+            logger.info("interrupted, shutting down")
+
+    async def run_async(self, *, register_signals: bool = True) -> None:
+        """Async entry point – call this if you already own the event loop.
+
+        Parameters
+        ----------
+        register_signals : bool
+            When *True* (default), register SIGINT/SIGTERM handlers to
+            gracefully stop the gateway.  Set to *False* when embedding
+            the agent inside a host process (e.g. Hermes) that manages
+            its own signal handling.
+        """
+        if register_signals:
+            loop = asyncio.get_running_loop()
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                try:
+                    loop.add_signal_handler(sig, self._gateway.stop)
+                except NotImplementedError:
+                    pass  # Windows
+
+        logger.info("MitiAgent starting")
+        self._auth.set_shared_session(self._ensure_session())
+        await self._auth.start_auto_refresh()
+        try:
+            await self._gateway.run_forever(inject_agent=self)
+        finally:
+            await self.close()
+            logger.info("MitiAgent stopped")
+
+    async def close(self) -> None:
+        """Release all resources (HTTP sessions, refresh tasks, WebSocket).
+
+        Safe to call multiple times — subsequent calls are no-ops.
+        """
+        await self._auth.close()
+        if self._msg_client:
+            await self._msg_client.close()
+        if self._history_client:
+            await self._history_client.close()
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    def _ensure_msg_client(self) -> MessageClient:
+        if self._msg_client is None:
+            self._msg_client = MessageClient(
+                auth=self._auth,
+                base_url=self._base_url,
+                session=self._ensure_session(),
+            )
+        return self._msg_client
+
+    def _ensure_history_client(self) -> HistoryClient:
+        if self._history_client is None:
+            self._history_client = HistoryClient(
+                auth=self._auth,
+                base_url=self._base_url,
+                session=self._ensure_session(),
+            )
+        return self._history_client
+
+
+_LOCAL_HOST_RE = re.compile(
+    r"^https?://(localhost|127\.0\.0\.1)(:\d+)?(/|$)", re.IGNORECASE,
+)
+
+
+def _is_tls_or_localhost(url: str) -> bool:
+    """Return True if *url* uses https:// or targets localhost over http://."""
+    if url.startswith("https://"):
+        return True
+    if url.startswith("http://") and _LOCAL_HOST_RE.match(url):
+        return True
+    return False

miti_agent_sdk/auth.py

@@ -0,0 +1,156 @@
+"""AuthClient – obtain and auto-refresh Miti Agent access tokens."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Optional
+
+import aiohttp
+
+logger = logging.getLogger("miti_agent_sdk.auth")
+
+# Refresh 10 minutes before expiry to avoid edge-case rejections.
+_REFRESH_MARGIN_S = 10 * 60
+
+
+class AuthError(Exception):
+    """Raised when token acquisition fails."""
+
+    def __init__(self, code: int, message: str):
+        self.code = code
+        super().__init__(f"[{code}] {message}")
+
+
+class AuthClient:
+    """Handles ``POST /agent/v1/auth/token`` and transparent token caching.
+
+    Parameters
+    ----------
+    app_id : str
+        Agent application ID (``cli_xxx``).
+    app_secret : str
+        Agent application secret.
+    base_url : str
+        Miti API base URL (no trailing slash).
+    session : aiohttp.ClientSession | None
+        Shared HTTP session.  If *None*, one is created internally.
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        base_url: str,
+        session: Optional[aiohttp.ClientSession] = None,
+    ):
+        self._app_id = app_id
+        self._app_secret = app_secret
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+
+        self._token: Optional[str] = None
+        self._expires_at: float = 0.0  # unix timestamp
+        self._lock = asyncio.Lock()
+        self._refresh_task: Optional[asyncio.Task] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def get_token(self) -> str:
+        """Return a valid access token, fetching or refreshing as needed."""
+        if self._token and time.time() < self._expires_at:
+            return self._token
+        async with self._lock:
+            # Double-check after acquiring lock.
+            if self._token and time.time() < self._expires_at:
+                return self._token
+            await self._fetch_token()
+        return self._token  # type: ignore[return-value]
+
+    async def start_auto_refresh(self) -> None:
+        """Start a background task that refreshes the token before expiry."""
+        if self._refresh_task is not None:
+            return
+        await self.get_token()  # ensure first token
+        self._refresh_task = asyncio.create_task(self._auto_refresh_loop())
+
+    def set_shared_session(self, session: aiohttp.ClientSession) -> None:
+        """Inject an externally-owned session (won't be closed by this client)."""
+        if self._session is None or self._session.closed:
+            self._session = session
+            self._owns_session = False
+
+    async def close(self) -> None:
+        if self._refresh_task is not None:
+            self._refresh_task.cancel()
+            try:
+                await self._refresh_task
+            except asyncio.CancelledError:
+                pass
+            self._refresh_task = None
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def _fetch_token(self) -> None:
+        url = f"{self._base_url}/agent/v1/auth/token"
+        payload = {"app_id": self._app_id, "app_secret": self._app_secret}
+        session = self._ensure_session()
+
+        logger.debug("requesting token from %s", url)
+        async with session.post(url, json=payload) as resp:
+            if resp.status != 200:
+                text = await resp.text()
+                logger.warning("auth token HTTP error: status=%d body=%s", resp.status, text[:200])
+                raise AuthError(resp.status, f"HTTP {resp.status}: {text[:200]}")
+            body = await resp.json()
+
+        code = body.get("errCode", body.get("code", -1))
+        if code != 0:
+            msg = body.get("errMsg", body.get("message", "unknown error"))
+            logger.warning("auth token API error: code=%d msg=%s", code, msg)
+            raise AuthError(code, msg)
+
+        data = body.get("data", {})
+        token = data.get("token") or data.get("access_token")
+        if not token:
+            raise AuthError(-1, "server returned code=0 but missing token")
+        self._token = token
+        expires_in = data.get("expires_in", 7200)
+        self._expires_at = time.time() + expires_in - _REFRESH_MARGIN_S
+        logger.info("token acquired, expires_in=%ds", expires_in)
+
+    async def _auto_refresh_loop(self) -> None:
+        """Sleep until close to expiry, then refresh."""
+        retry_backoff = 0.0
+        while True:
+            if retry_backoff > 0:
+                logger.debug("auto-refresh retry backoff %.0fs", retry_backoff)
+                await asyncio.sleep(retry_backoff)
+            else:
+                sleep_for = max(self._expires_at - time.time(), 1.0)
+                logger.debug("auto-refresh sleeping %.0fs", sleep_for)
+                await asyncio.sleep(sleep_for)
+            try:
+                async with self._lock:
+                    await self._fetch_token()
+                logger.info("token auto-refreshed")
+                retry_backoff = 0.0
+            except Exception:
+                retry_backoff = min((retry_backoff or 15) * 2, 120)
+                logger.exception(
+                    "auto-refresh failed, will retry in %.0fs", retry_backoff,
+                )

miti_agent_sdk/gateway.py

@@ -0,0 +1,159 @@
+"""GatewayClient – WebSocket connection to Miti Event Gateway with
+automatic keep-alive and exponential-backoff reconnection."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+import websockets
+import websockets.exceptions
+
+from .auth import AuthClient
+from .models import AgentEvent, parse_event
+
+logger = logging.getLogger("miti_agent_sdk.gateway")
+
+_INITIAL_BACKOFF_S = 1.0
+_MAX_BACKOFF_S = 60.0
+_BACKOFF_FACTOR = 2.0
+
+
+EventHandler = Callable[[AgentEvent], Awaitable[None]]
+
+
+class GatewayClient:
+    """Manages the WebSocket lifecycle: connect, receive, ping/pong,
+    and exponential-backoff reconnect.
+
+    Parameters
+    ----------
+    auth : AuthClient
+        Provides Bearer tokens for the ``Authorization`` header.
+    base_url : str
+        HTTP(S) base URL; scheme is converted to ``ws`` / ``wss``.
+    """
+
+    def __init__(self, auth: AuthClient, base_url: str):
+        self._auth = auth
+        self._ws_url = self._to_ws_url(base_url.rstrip("/") + "/agent/gateway")
+        self._handlers: dict[str, list[EventHandler]] = {}
+        self._ws: Optional[websockets.WebSocketClientProtocol] = None
+        self._running = False
+
+    # ------------------------------------------------------------------
+    # Handler registration
+    # ------------------------------------------------------------------
+
+    def on(self, event_type: str, handler: EventHandler) -> None:
+        """Register *handler* for events of *event_type*."""
+        self._handlers.setdefault(event_type, []).append(handler)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def run_forever(self, inject_agent: Any = None) -> None:
+        """Connect and reconnect in a loop until :meth:`stop` is called.
+
+        Parameters
+        ----------
+        inject_agent :
+            If provided, set as ``event._agent`` before dispatching so that
+            ``event.reply()`` works.
+        """
+        self._running = True
+        backoff = _INITIAL_BACKOFF_S
+
+        while self._running:
+            try:
+                await self._connect_and_listen(inject_agent)
+                backoff = _INITIAL_BACKOFF_S
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                if not self._running:
+                    break
+                logger.exception(
+                    "gateway connection lost, reconnecting in %.0fs", backoff,
+                )
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * _BACKOFF_FACTOR, _MAX_BACKOFF_S)
+
+        logger.info("gateway run_forever exited")
+
+    def stop(self) -> None:
+        """Signal the run loop to exit after the current iteration."""
+        self._running = False
+        if self._ws:
+            asyncio.ensure_future(self._ws.close())
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _connect_and_listen(self, inject_agent: Any) -> None:
+        token = await self._auth.get_token()
+        headers = {"Authorization": f"Bearer {token}"}
+
+        logger.info("connecting to %s", self._ws_url)
+        async with websockets.connect(
+            self._ws_url,
+            additional_headers=headers,
+            ping_interval=25,
+            ping_timeout=30,
+        ) as ws:
+            self._ws = ws
+            logger.info("gateway connected")
+            try:
+                async for raw in ws:
+                    await self._dispatch(raw, inject_agent)
+            except websockets.exceptions.ConnectionClosedError as exc:
+                logger.warning("gateway connection closed: %s", exc)
+                raise
+            finally:
+                self._ws = None
+
+    async def _dispatch(self, raw: str | bytes, inject_agent: Any) -> None:
+        try:
+            data: dict[str, Any] = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("received non-JSON frame, ignoring: %s", raw[:200])
+            return
+
+        try:
+            event = parse_event(data)
+        except Exception:
+            logger.exception("failed to parse event: %s", raw[:500])
+            return
+
+        if inject_agent is not None:
+            event._agent = inject_agent
+
+        event_type = event.header.event_type
+        logger.info("event received: type=%s id=%s", event_type, event.header.event_id)
+        handlers = self._handlers.get(event_type, [])
+        if not handlers:
+            logger.warning("no handler for event_type=%s, ignoring event_id=%s",
+                           event_type, event.header.event_id)
+            return
+
+        for handler in handlers:
+            try:
+                await handler(event)
+            except Exception:
+                logger.exception(
+                    "handler error for event_type=%s event_id=%s",
+                    event_type,
+                    event.header.event_id,
+                )
+
+    @staticmethod
+    def _to_ws_url(http_url: str) -> str:
+        if http_url.startswith("https://"):
+            return "wss://" + http_url[len("https://"):]
+        if http_url.startswith("http://"):
+            return "ws://" + http_url[len("http://"):]
+        return http_url

miti_agent_sdk/message.py

@@ -0,0 +1,197 @@
+"""MessageClient and HistoryClient – REST API wrappers for sending messages
+and fetching conversation history."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+import aiohttp
+
+from .auth import AuthClient
+from .models import HistoryMessage
+
+logger = logging.getLogger("miti_agent_sdk.message")
+
+
+class ApiError(Exception):
+    """Raised when a Miti REST API returns a non-zero code."""
+
+    def __init__(self, code: int, message: str):
+        self.code = code
+        super().__init__(f"[{code}] {message}")
+
+
+class MessageClient:
+    """``POST /agent/v1/messages/send`` – send a message to a user or group.
+
+    Parameters
+    ----------
+    auth : AuthClient
+        Provides Bearer tokens.
+    base_url : str
+        Miti API base URL (no trailing slash).
+    session : aiohttp.ClientSession | None
+        Shared HTTP session.
+    """
+
+    def __init__(
+        self,
+        auth: AuthClient,
+        base_url: str,
+        session: Optional[aiohttp.ClientSession] = None,
+    ):
+        self._auth = auth
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def send(
+        self,
+        *,
+        to_user_id: Optional[str] = None,
+        to_group_id: Optional[str] = None,
+        msg_type: str = "text",
+        content: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send a message and return the response ``data`` dict.
+
+        Exactly one of *to_user_id* or *to_group_id* must be provided.
+
+        Returns
+        -------
+        dict
+            ``{"message_id": "...", "server_time": "..."}``
+        """
+        if not to_user_id and not to_group_id:
+            raise ValueError("to_user_id or to_group_id required")
+        if to_user_id and to_group_id:
+            raise ValueError("only one of to_user_id or to_group_id is allowed")
+
+        token = await self._auth.get_token()
+        url = f"{self._base_url}/agent/v1/messages/send"
+        payload: dict[str, Any] = {
+            "msg_type": msg_type,
+            "content": content or {},
+        }
+        if to_user_id:
+            payload["to_user_id"] = to_user_id
+        else:
+            payload["to_group_id"] = to_group_id
+
+        session = self._ensure_session()
+        headers = {"Authorization": f"Bearer {token}"}
+
+        target = to_user_id or to_group_id
+        logger.debug("POST %s  target=%s", url, target)
+        async with session.post(url, json=payload, headers=headers) as resp:
+            if resp.status != 200:
+                text = await resp.text()
+                logger.warning("send_message HTTP error: status=%d target=%s body=%s",
+                               resp.status, target, text[:200])
+                raise ApiError(resp.status, f"HTTP {resp.status}: {text[:200]}")
+            body = await resp.json()
+
+        code = body.get("errCode", body.get("code", -1))
+        if code != 0:
+            msg = body.get("errMsg", body.get("message", "unknown error"))
+            logger.warning("send_message API error: code=%d target=%s msg=%s",
+                           code, target, msg)
+            raise ApiError(code, msg)
+
+        data = body.get("data", {})
+        logger.info("send_message success: target=%s message_id=%s",
+                     target, data.get("message_id", ""))
+        return data
+
+    async def close(self) -> None:
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()
+
+
+class HistoryClient:
+    """``GET /agent/v1/messages/history`` – fetch conversation history.
+
+    Parameters
+    ----------
+    auth : AuthClient
+        Provides Bearer tokens.
+    base_url : str
+        Miti API base URL (no trailing slash).
+    session : aiohttp.ClientSession | None
+        Shared HTTP session.
+    """
+
+    def __init__(
+        self,
+        auth: AuthClient,
+        base_url: str,
+        session: Optional[aiohttp.ClientSession] = None,
+    ):
+        self._auth = auth
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+        self._owns_session = session is None
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def get(
+        self,
+        conversation_id: str,
+        limit: int = 10,
+    ) -> list[HistoryMessage]:
+        """Fetch recent messages for a conversation.
+
+        Parameters
+        ----------
+        conversation_id : str
+            The ``si_...`` or ``sg_...`` conversation identifier.
+        limit : int
+            Maximum number of messages to return (server caps at 50).
+
+        Returns
+        -------
+        list[HistoryMessage]
+        """
+        token = await self._auth.get_token()
+        url = f"{self._base_url}/agent/v1/messages/history"
+        params = {"conversation_id": conversation_id, "limit": str(limit)}
+        headers = {"Authorization": f"Bearer {token}"}
+
+        session = self._ensure_session()
+        logger.debug("GET %s  conversation_id=%s limit=%d", url, conversation_id, limit)
+        async with session.get(url, params=params, headers=headers) as resp:
+            if resp.status != 200:
+                text = await resp.text()
+                logger.warning("get_history HTTP error: status=%d conversation_id=%s body=%s",
+                               resp.status, conversation_id, text[:200])
+                raise ApiError(resp.status, f"HTTP {resp.status}: {text[:200]}")
+            body = await resp.json()
+
+        code = body.get("errCode", body.get("code", -1))
+        if code != 0:
+            msg = body.get("errMsg", body.get("message", "unknown error"))
+            logger.warning("get_history API error: code=%d conversation_id=%s msg=%s",
+                           code, conversation_id, msg)
+            raise ApiError(code, msg)
+
+        data = body.get("data", {})
+        raw_messages = data.get("messages", [])
+        return [
+            HistoryMessage(role=m.get("role", ""), content=m.get("content", {}))
+            for m in raw_messages
+        ]
+
+    async def close(self) -> None:
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()

miti_agent_sdk/models.py

@@ -0,0 +1,156 @@
+"""Data models for Miti Agent SDK events and messages."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from .stream import build_stream_full_markdown
+
+
+@dataclass
+class EventSender:
+    user_id: str
+
+
+@dataclass
+class EventMessage:
+    message_id: str
+    conversation_id: str
+    session_type: str  # "single" | "group"
+    msg_type: str      # "text" | "image" | "multimodal" | "at_text" | ...
+    content: dict[str, Any] = field(default_factory=dict)
+    send_time: str = ""
+
+
+@dataclass
+class EventHeader:
+    event_id: str
+    event_type: str  # "im.message.receive" | "im.message.group_at"
+    app_id: str
+    create_time: str
+
+
+@dataclass
+class MessageEvent:
+    """im.message.receive – single-chat message."""
+    sender: EventSender
+    message: EventMessage
+
+
+@dataclass
+class GroupAtEvent:
+    """im.message.group_at – group-chat @ message."""
+    group_id: str
+    at_user_id: str
+    sender: EventSender
+    message: EventMessage
+
+
+@dataclass
+class AgentEvent:
+    """Top-level event envelope pushed via WebSocket."""
+    schema: str
+    header: EventHeader
+    event: MessageEvent | GroupAtEvent
+
+    # --- back-references injected by MitiAgent before dispatching ---
+    _agent: Any = field(default=None, repr=False, compare=False)
+
+    @property
+    def is_single(self) -> bool:
+        return self.header.event_type == "im.message.receive"
+
+    @property
+    def is_group_at(self) -> bool:
+        return self.header.event_type == "im.message.group_at"
+
+    async def reply(self, text: str, *, use_markdown: bool = True) -> dict[str, Any]:
+        """Reply to the sender (single) or group (group_at).
+
+        By default sends ``stream_full`` (contentType 125) so the Miti App
+        renders Markdown.  Set ``use_markdown=False`` for plain text (101).
+        """
+        if self._agent is None:
+            raise RuntimeError("reply() requires event._agent to be set by MitiAgent")
+
+        ask_msg_id = getattr(getattr(self.event, "message", None), "message_id", "")
+
+        if use_markdown:
+            content = build_stream_full_markdown(text, ask_msg_id)
+            msg_type = "stream_full"
+        else:
+            content = {"text": text}
+            msg_type = "text"
+
+        if self.is_group_at:
+            evt: GroupAtEvent = self.event  # type: ignore[assignment]
+            return await self._agent.send_message(
+                to_group_id=evt.group_id,
+                msg_type=msg_type,
+                content=content,
+            )
+        return await self._agent.send_message(
+            to_user_id=self.event.sender.user_id,
+            msg_type=msg_type,
+            content=content,
+        )
+
+
+@dataclass
+class HistoryMessage:
+    """A single message in conversation history (OpenAI messages style)."""
+    role: str       # "user" | "assistant"
+    content: Any    # {"text": "..."} etc.
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+def _parse_sender(raw: dict) -> EventSender:
+    return EventSender(user_id=raw.get("user_id", ""))
+
+
+def _parse_message(raw: dict) -> EventMessage:
+    return EventMessage(
+        message_id=raw.get("message_id", ""),
+        conversation_id=raw.get("conversation_id", ""),
+        session_type=raw.get("session_type", ""),
+        msg_type=raw.get("msg_type", ""),
+        content=raw.get("content", {}),
+        send_time=raw.get("send_time", ""),
+    )
+
+
+def parse_event(raw: dict) -> AgentEvent:
+    """Parse a raw JSON dict into an :class:`AgentEvent`."""
+    header_raw = raw.get("header", {})
+    header = EventHeader(
+        event_id=header_raw.get("event_id", ""),
+        event_type=header_raw.get("event_type", ""),
+        app_id=header_raw.get("app_id", ""),
+        create_time=header_raw.get("create_time", ""),
+    )
+
+    event_raw = raw.get("event", {})
+    event_type = header.event_type
+
+    if event_type == "im.message.group_at":
+        event: MessageEvent | GroupAtEvent = GroupAtEvent(
+            group_id=event_raw.get("group_id", ""),
+            at_user_id=event_raw.get("at_user_id", ""),
+            sender=_parse_sender(event_raw.get("sender", {})),
+            message=_parse_message(event_raw.get("message", {})),
+        )
+    else:
+        event = MessageEvent(
+            sender=_parse_sender(event_raw.get("sender", {})),
+            message=_parse_message(event_raw.get("message", {})),
+        )
+
+    return AgentEvent(
+        schema=raw.get("schema", ""),
+        header=header,
+        event=event,
+    )

miti_agent_sdk/stream.py

@@ -0,0 +1,53 @@
+"""Helpers for MessageStreamFull (contentType 125) outbound messages."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def build_stream_full_markdown(
+    markdown: str,
+    ask_msg_id: str = "",
+    *,
+    seq: int = 1,
+) -> dict[str, Any]:
+    """Build Agent API ``stream_full`` content for a single Markdown reply.
+
+    The server converts this to IM ``MessageStreamFull`` (125), which the
+    Miti App renders via ``ChatStream`` + Markdown.
+
+    Parameters
+    ----------
+    markdown:
+        Full Markdown body (not incremental).
+    ask_msg_id:
+        Server message ID of the user's question; links reply to the ask
+        bubble in the App UI.  Pass ``event.event.message.message_id`` from
+        an inbound event when available.
+    seq:
+        Event sequence number inside ``content_list`` (default 1).
+    """
+    delta_payload = json.dumps(
+        {"markdown": {"delta": markdown}},
+        ensure_ascii=False,
+    )
+    content: dict[str, Any] = {
+        "content_list": [
+            {
+                "event": "delta",
+                "seq": seq,
+                "content": delta_payload,
+                "desc": {
+                    "isIncrease": False,
+                    "isCompleted": True,
+                    "isShow": True,
+                    "history": True,
+                    "showType": "markdown",
+                },
+            }
+        ],
+    }
+    if ask_msg_id:
+        content["ask_msg_id"] = ask_msg_id
+    return content

miti_agent_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: miti-agent-sdk
+Version: 0.1.0
+Summary: Miti Agent SDK – connect third-party agents to Miti IM
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# miti-agent-sdk
+
+Connect third-party agents (Hermes, OpenClaw, Claude Code, etc.) to the Miti IM platform.
+
+## Installation
+
+```bash
+pip install miti-agent-sdk
+```
+
+## Quick Start
+
+```python
+from miti_agent_sdk import MitiAgent
+
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+)
+
+# 单聊消息
+@agent.on_message
+async def handle(event):
+    user_text = event.event.message.content.get("text", "")
+    await event.reply(f"收到：{user_text}")
+
+# 群 @ 消息
+@agent.on_group_at
+async def handle_group(event):
+    text = event.event.message.content.get("text", "")
+    await event.reply(f"群收到：{text}")
+
+agent.run()
+```
+
+SDK 内部自动处理：Token 获取/刷新、WebSocket 保活、指数退避重连。
+
+## 环境配置
+
+`base_url` 按以下优先级决定（先找到先用）：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1（最高） | 构造函数 `base_url=` 参数 | `MitiAgent(base_url="https://...")` |
+| 2 | 环境变量 `MITI_API_BASE_URL` | `export MITI_API_BASE_URL="https://..."` |
+| 3（默认） | 正式环境 | `https://www.miti.chat/chat` |
+
+大多数场景下**不需要配置任何东西**，SDK 自动连接正式环境。
+
+本地开发调试时，通过环境变量指向本地 appserver 即可，无需改业务代码：
+
+```bash
+export MITI_API_BASE_URL="http://localhost:10006/chat"
+```
+
+也可以在初始化时显式传入：
+
+```python
+agent = MitiAgent(
+    app_id="cli_xxx",
+    app_secret="secret_xxx",
+    base_url="http://localhost:10006/chat",
+)
+```
+
+## 拉取历史记录
+
+```python
+@agent.on_message
+async def handle(event):
+    history = await agent.get_history(
+        event.event.message.conversation_id, limit=10
+    )
+    # history: list[HistoryMessage]  each has .role and .content
+```
+
+## 日志 & 问题排查
+
+SDK 使用 Python 标准 `logging` 模块，logger 层级为 `miti_agent_sdk.*`。
+
+### 快速开启日志
+
+```python
+import miti_agent_sdk
+
+# INFO 级别：token 获取/刷新、WebSocket 连接/断开/重连、事件收发、消息发送
+miti_agent_sdk.enable_logging()
+
+# DEBUG 级别：额外输出每次 HTTP 请求 URL/参数、自动刷新 sleep 倒计时
+miti_agent_sdk.enable_logging(logging.DEBUG)
+```
+
+日志输出到 **stderr**（默认），格式示例：
+
+```
+2026-06-18 18:00:01 [miti_agent_sdk.auth] INFO token acquired, expires_in=7200s
+2026-06-18 18:00:01 [miti_agent_sdk.gateway] INFO connecting to wss://www.miti.chat/chat/agent/gateway
+2026-06-18 18:00:02 [miti_agent_sdk.gateway] INFO gateway connected
+2026-06-18 18:00:05 [miti_agent_sdk.gateway] INFO event received: type=im.message.receive id=evt-xxx
+2026-06-18 18:00:05 [miti_agent_sdk.message] INFO send_message success: target=user-abc message_id=msg-xxx
+```
+
+### 日志存储
+
+SDK 本身不写日志文件。日志的最终存储取决于宿主进程：
+
+| 方式 | 配置 | 适用场景 |
+|------|------|----------|
+| 控制台 | `miti_agent_sdk.enable_logging()` | 本地开发调试 |
+| 文件 | `logging.basicConfig(filename="agent.log", level=logging.INFO)` | 单机部署 |
+| 结构化日志 | 宿主框架的 JSON handler（如 `python-json-logger`） | 生产环境 / 接入 ELK 等 |
+| 容器 stdout | 不做额外配置，`enable_logging()` 输出到 stderr 即可 | Docker / K8s |
+
+### 排查常见问题
+
+| 现象 | 排查方向 | 关键日志 |
+|------|----------|----------|
+| 启动后无反应 | Token 获取失败 | `auth token API error: code=... msg=...` |
+| 连接后收不到消息 | WebSocket 断开或无事件推送 | `gateway connection lost` / `no handler for event_type` |
+| 回复消息失败 | 权限不足或目标不存在 | `send_message API error: code=10012 msg=no permission` |
+| Token 过期后断连 | 自动刷新失败 | `auto-refresh failed, will retry in ...s` |
+| WebSocket 频繁重连 | 网络不稳或服务端问题 | `reconnecting in Xs`（观察退避时间是否递增） |
+
+## 安全注意事项
+
+### 日志安全
+
+SDK 自身**不会**在日志中输出 `app_secret` 或 `access_token`。但如果你开启了
+`aiohttp` 的 trace/debug 日志（如 `AIOHTTP_TRACE=1`），HTTP 请求体会被底层框架
+打印出来，其中包含 `app_secret`。**生产环境请勿开启 aiohttp trace 日志。**
+
+### 凭证内存存储
+
+`app_secret` 和 `access_token` 在 SDK 运行期间以明文存储在进程内存中。
+这是 Python SDK 的通用模式（与飞书 SDK、Slack SDK 一致），无法避免。
+请确保：
+
+- 不要在多租户共享环境中运行 agent 进程
+- 不要将进程 memory dump 输出到不安全的位置
+- 进程退出后凭证自动释放，无需手动清理
+
+### TLS 要求
+
+SDK 强制要求 `base_url` 使用 `https://`（对应 WebSocket `wss://`）。
+本地开发调试时 `localhost` / `127.0.0.1` 可使用 `http://`，其他地址会被拒绝。
+
+## Requirements
+
+- Python 3.9+
+- `aiohttp >= 3.9`
+- `websockets >= 12.0`

miti_agent_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+miti_agent_sdk/__init__.py,sha256=-dObqlDNi50TLh6YaWMsuHKqiy41K-IsUcrcEeesKS8,1934
+miti_agent_sdk/agent.py,sha256=l9kbsuhTmtdyoMwS0gkPm_ckmgBnqKM4QeyRrRfvYVc,8878
+miti_agent_sdk/auth.py,sha256=5L-eUFORU88wpHESUSmAAXt2o16OhIFn7XQGL4IpORA,5814
+miti_agent_sdk/gateway.py,sha256=p-0T9eNVxZf6j6Uh-mxU7Sbts3i6gx-FxS5clB0UnJI,5431
+miti_agent_sdk/message.py,sha256=B-eI0WOvp_uLLnautnSK1FnJhzBep7Mqa88M2IpUETA,6615
+miti_agent_sdk/models.py,sha256=UnAFZxUVJ7X7v3whhjXVfdidP4KW2UTpsx0O236g3Qk,4637
+miti_agent_sdk/stream.py,sha256=JWbuyQTnd3teU6gt06BZwAjeWrcUDG2dQAWRlgakm6A,1495
+miti_agent_sdk-0.1.0.dist-info/METADATA,sha256=GPwlTMwZ7bDhkmAkDp6uBByaBTkCjGT5-okXMogkAvw,5275
+miti_agent_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+miti_agent_sdk-0.1.0.dist-info/top_level.txt,sha256=qJCgD-F4MvjqxZovxzd_iN6fTCQjWQbVbLn_YuANi4k,15
+miti_agent_sdk-0.1.0.dist-info/RECORD,,

miti_agent_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

miti_agent_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+miti_agent_sdk