diff --git a/src/agenthub/channels/_nats_sync.py b/src/agenthub/channels/_nats_sync.py new file mode 100644 index 0000000..54afd90 --- /dev/null +++ b/src/agenthub/channels/_nats_sync.py @@ -0,0 +1,249 @@ +"""Synchronous wrapper over nats-py. + +nats-py is asyncio-only (no official sync client exists). This module runs +the entire client on a dedicated background event-loop thread and exposes +blocking, thread-safe calls: the same pub/sub semantics as ``nats.connect`` +without requiring the caller to have an event loop. + +Not affiliated with nats-py; requires ``nats-py>=2.6.0`` to be installed. +""" + +from __future__ import annotations + +import asyncio +import threading +from typing import Any, Callable + +__all__ = ["SyncNATS", "SyncMsg"] + +ConnectCallback = Callable[[], None] +MessageCallback = Callable[["SyncMsg"], None] + + +class SyncMsg: + """A received message. ``data`` is raw bytes, ``subject`` the topic.""" + + __slots__ = ("subject", "data", "reply", "_ack") + + def __init__(self, subject: str, data: bytes, reply: str = "") -> None: + self.subject = subject + self.data = data + self.reply = reply + + def decode(self) -> str: + return self.data.decode("utf-8", errors="replace") + + def __repr__(self) -> str: # pragma: no cover + return f"" + + +class SyncNATS: + """Blocking NATS client. Create one per process (or per connection). + + Example: + nc = SyncNATS("nats://localhost:4222") + nc.subscribe("bots.*.in", callback=lambda m: print(m.decode())) + nc.publish("bots.x.out", b"hello") + nc.close() + """ + + def __init__( + self, + servers: str = "nats://localhost:4222", + *, + username: str = "", + password: str = "", + connect_timeout: float = 10.0, + on_connect: ConnectCallback | None = None, + on_disconnect: ConnectCallback | None = None, + ) -> None: + self._servers = servers + self._username = username + self._password = password + self._connect_timeout = connect_timeout + self._on_connect = on_connect + self._on_disconnect = on_disconnect + + self._ready = threading.Event() + self._connect_error: BaseException | None = None + + self._loop = asyncio.new_event_loop() + self._thread = threading.Thread( + target=self._thread_main, name="sync-nats", daemon=True + ) + self._thread.start() + # Wait for connect to finish (success or failure) before returning. + self._ready.wait(timeout=self._connect_timeout + 5) + if self._connect_error is not None: + self._shutdown_loop() + raise self._connect_error + + # ------------------------------------------------------------------ + # Background loop thread + # ------------------------------------------------------------------ + + def _thread_main(self) -> None: + asyncio.set_event_loop(self._loop) + self._loop.run_until_complete(self._connect()) + self._loop.run_forever() + # Loop stopped: drain remaining callbacks then close. + pending = asyncio.all_tasks(self._loop) + if pending: + self._loop.run_until_complete( + asyncio.gather(*pending, return_exceptions=True) + ) + self._loop.close() + + async def _connect(self) -> None: + import nats + + servers = [s.strip() for s in self._servers.split(",") if s.strip()] + + async def _disc() -> None: + if self._on_disconnect: + try: + self._on_disconnect() + except Exception: + pass + + async def _reconn() -> None: + if self._on_connect: + try: + self._on_connect() + except Exception: + pass + + try: + self._nc = await nats.connect( + servers=servers, + user=self._username or None, + password=self._password or None, + connect_timeout=int(self._connect_timeout), + reconnect_time_wait=1, + max_reconnect_attempts=-1, + disconnected_cb=_disc, + reconnected_cb=_reconn, + ) + except BaseException as exc: # propagate to the constructing thread + self._connect_error = exc + finally: + self._ready.set() + + def _shutdown_loop(self) -> None: + if self._loop.is_running(): + self._loop.call_soon_threadsafe(self._loop.stop) + if self._thread.is_alive(): + self._thread.join(timeout=5) + + # ------------------------------------------------------------------ + # Public blocking API + # ------------------------------------------------------------------ + + def publish(self, subject: str, data: bytes | str) -> None: + """Publish and flush before returning (send-and-forget semantics).""" + if isinstance(data, str): + data = data.encode("utf-8") + + done = threading.Event() + err: list[BaseException] = [] + + async def _pub() -> None: + try: + await self._nc.publish(subject, data) + await self._nc.flush() + except BaseException as exc: + err.append(exc) + finally: + done.set() + + self._loop.call_soon_threadsafe(self._loop.create_task, _pub()) + if not done.wait(timeout=30): + raise TimeoutError(f"publish timed out to {subject}") + if err: + raise err[0] + + def subscribe(self, subject: str, callback: MessageCallback) -> str: + """Subscribe with a sync callback invoked on the NATS thread.""" + done = threading.Event() + err: list[BaseException] = [] + sid_box: list[str] = [] + + async def _sub() -> None: + try: + sub = await self._nc.subscribe(subject, cb=self._make_cb(callback)) + sid_box.append(str(sub._id)) + except BaseException as exc: + err.append(exc) + finally: + done.set() + + self._loop.call_soon_threadsafe(self._loop.create_task, _sub()) + if not done.wait(timeout=10): + raise TimeoutError(f"subscribe timed out for {subject}") + if err: + raise err[0] + return sid_box[0] + + def unsubscribe(self, sid: str) -> None: + done = threading.Event() + + async def _unsub() -> None: + try: + sub = self._nc._subs.get(int(sid)) + if sub is not None: + await sub.unsubscribe() + finally: + done.set() + + self._loop.call_soon_threadsafe(self._loop.create_task, _unsub()) + done.wait(timeout=10) + + def request(self, subject: str, data: bytes | str, timeout: float = 5.0) -> SyncMsg: + """Blocking request/reply using nats-py's inbox machinery.""" + if isinstance(data, str): + data = data.encode("utf-8") + + fut: asyncio.Future = self._loop.create_future() + + async def _req() -> None: + try: + msg = await self._nc.request(subject, data, timeout=timeout) + if not fut.done(): + fut.set_result(msg) + except BaseException as exc: + if not fut.done(): + fut.set_exception(exc) + + self._loop.call_soon_threadsafe(self._loop.create_task, _req()) + msg = fut.result(timeout=timeout + 5) # may raise TimeoutError / Error + return SyncMsg(msg.subject, msg.data, msg.reply or "") + + def is_connected(self) -> bool: + return self._nc is not None and self._nc.is_connected + + def close(self) -> None: + """Flush pending publishes and stop the background thread.""" + if getattr(self, "_nc", None) is not None: + nc, self._nc = self._nc, None + fut = asyncio.run_coroutine_threadsafe(nc.drain(), self._loop) + try: + fut.result(timeout=5) + except Exception: + pass + self._shutdown_loop() + + # ------------------------------------------------------------------ + + def _make_cb(self, user_cb: MessageCallback) -> Callable: + async def _cb(msg: Any) -> None: + sync_msg = SyncMsg(msg.subject, msg.data, msg.reply or "") + # Run the user callback off the loop thread (it may block). + await asyncio.get_running_loop().run_in_executor(None, user_cb, sync_msg) + + return _cb + + def __enter__(self) -> "SyncNATS": + return self + + def __exit__(self, *exc: Any) -> None: + self.close() diff --git a/src/agenthub/channels/nats.py b/src/agenthub/channels/nats.py new file mode 100644 index 0000000..e789c08 --- /dev/null +++ b/src/agenthub/channels/nats.py @@ -0,0 +1,168 @@ +"""NATS channel for agenthub: request/reply over NATS subjects. + +M1 channel. NATS is a peer front-end (same IMChannel contract as wecom/ +weixin); agenthub is a NATS client. Protocol: + +- inbound: subscribe to ``subject_prefix`` (default ``agenthub.in.>``). + Message body = JSON {"chat_id", "user_id"?, "text"} (extra fields kept + in raw). If the message carries a ``reply`` subject, final answers are + published back to it; otherwise to ``subject_prefix`` with ``.out`` + semantics (see below). +- outbound: reply(chat_id, text) publishes JSON {"chat_id", "text"} to + ``out_subject`` (default ``agenthub.out.``). + +Channel name is "nats"; chat keys become "nats:" downstream. + +Config (dict): + servers: str = "nats://localhost:4222" # comma separated + username / password: str = "" + in_subject: str = "agenthub.in.>" # subscription pattern + out_subject: str = "agenthub.out" # replies published to out_subject. + allowed_users: list[str] = [] + +Requires the ``nats`` extra (nats-py). Reuses octop-gateway's SyncNATS +wrapper (vendored copy, asyncio-only nats-py behind a thread). +""" + +from __future__ import annotations + +import json +import logging +import threading +from typing import Any, Callable + +from .base import ( + IMChannel, + InboundMessage, + _command_result_text, + _interaction_text, + clean_control_chars, + split_message_text, +) + +log = logging.getLogger("agenthub.nats") + +MAX_TEXT_BYTES = 900_000 # NATS default max_payload is 1MB; stay under it + + +def _log(): + return logging.getLogger("agenthub.nats") + + +class NatsChannel: + name = "nats" + + def __init__( + self, + config: dict[str, Any], + nats_factory: Callable[..., Any] | None = None, + logger: Any = None, + ): + self.servers = (config.get("servers") or "nats://localhost:4222").strip() + self.username = config.get("username", "") + self.password = config.get("password", "") + self.in_subject = config.get("in_subject", "agenthub.in.>") + self.out_subject = (config.get("out_subject") or "agenthub.out").rstrip(".") + self.allowed_users = set(config.get("allowed_users") or []) + self._nats_factory = nats_factory # injectable for tests + self._nc: Any = None + self._sub_id: str | None = None + self._msg_cb: Callable[[InboundMessage], None] | None = None + self._sink: Callable[[str, str, dict], None] | None = None + self._logger = logger or _log() + self._stop = threading.Event() + + # -- IMChannel --------------------------------------------------------- + def start(self) -> None: + from ._nats_sync import SyncNATS # vendored sync wrapper + + factory = self._nats_factory or SyncNATS + self._nc = factory( + self.servers, + username=self.username, + password=self.password, + on_connect=lambda: self._logger.info("[nats] connected"), + on_disconnect=lambda: self._logger.warning("[nats] disconnected; reconnecting"), + ) + self._sub_id = self._nc.subscribe(self.in_subject, self._on_nats_msg) + self._logger.info(f"[nats] subscribed {self.in_subject} (out: {self.out_subject}.*)") + + def stop(self) -> None: + self._stop.set() + if self._nc: + try: + if self._sub_id: + self._nc.unsubscribe(self._sub_id) + self._nc.close() + except Exception as e: # noqa: BLE001 + self._logger.warning(f"[nats] close error: {e}") + self._nc = None + + def on_message(self, cb: Callable[[InboundMessage], None]) -> None: + self._msg_cb = cb + + def set_event_sink(self, sink: Callable[[str, str, dict], None]) -> None: + self._sink = sink + + # -- inbound ----------------------------------------------------------- + def _on_nats_msg(self, msg: Any) -> None: + """NATS thread callback — must never raise (sync wrapper logs).""" + try: + data = json.loads(msg.decode()) + chat_id = str(data.get("chat_id") or "").strip() + if not chat_id: + # fall back to the subject's last token as chat id + chat_id = msg.subject.rsplit(".", 1)[-1] + user_id = str(data.get("user_id") or chat_id) + if self.allowed_users and user_id not in self.allowed_users: + self._logger.warning(f"[nats] user {user_id!r} not allowed; drop") + return + text = clean_control_chars(str(data.get("text") or ""), max_len=100_000).strip() + if not text: + return + if self._msg_cb: + self._msg_cb( + InboundMessage( + channel=self.name, + chat_id=chat_id, + user_id=user_id, + text=text, + raw={"subject": msg.subject, "reply": msg.reply or ""}, + ) + ) + except Exception as e: # noqa: BLE001 — never kill the subscription + self._logger.error(f"[nats] inbound dispatch failed: {e}") + + # -- outbound ---------------------------------------------------------- + def _publish_out(self, chat_id: str, payload: dict[str, Any]) -> None: + if not self._nc: + return + subject = f"{self.out_subject}.{chat_id}" + body = json.dumps(payload, ensure_ascii=False).encode() + if len(body) > MAX_TEXT_BYTES: + self._logger.warning(f"[nats] payload {len(body)}B > {MAX_TEXT_BYTES}B; dropping") + return + try: + self._nc.publish(subject, body) + except Exception as e: # noqa: BLE001 + self._logger.error(f"[nats] publish to {subject} failed: {e}") + + def reply(self, chat_id: str, text: str) -> None: + # split under the per-message byte budget (envelope counts too) + budget = MAX_TEXT_BYTES - 200 + for chunk in split_message_text(text, budget): + self._publish_out(chat_id, {"chat_id": chat_id, "text": chunk}) + + def push_event(self, chat_id: str, kind: str, payload: dict[str, Any]) -> None: + if kind == "delta": + # NATS has no edit semantics; stream deltas as status lines is + # noise — accumulate and deliver on final only. + return + if kind == "final": + self.reply(chat_id, str(payload.get("text", ""))) + elif kind == "status": + self._publish_out(chat_id, {"chat_id": chat_id, "status": str(payload.get("text", ""))}) + elif kind in ("interaction", "permission"): + self.reply(chat_id, _interaction_text(payload)) + elif kind == "command_result": + self.reply(chat_id, _command_result_text(payload)) diff --git a/src/agenthub/runtime.py b/src/agenthub/runtime.py index 412e22f..021cab4 100644 --- a/src/agenthub/runtime.py +++ b/src/agenthub/runtime.py @@ -84,6 +84,10 @@ def build_channels(cfg: dict[str, Any], mgr: SessionManager) -> list: sink_and_inbound(WecomAppChannel(ccfg["wecom-app"])) if "weixin" in ccfg: sink_and_inbound(WeixinChannel(ccfg["weixin"])) + if "nats" in ccfg: + from .channels.nats import NatsChannel + + sink_and_inbound(NatsChannel(ccfg["nats"])) # ONE dispatch-all event sink (per-channel sinks would overwrite each # other; _safe_event filters per channel name anyway). Approvals diff --git a/tests/test_channel_nats.py b/tests/test_channel_nats.py new file mode 100644 index 0000000..61411fe --- /dev/null +++ b/tests/test_channel_nats.py @@ -0,0 +1,138 @@ +"""Tests for the NATS channel (mocked transport, no network).""" + +from __future__ import annotations + +import json +from typing import Any + +import pytest + +from agenthub.channels.nats import NatsChannel +from agenthub.channels.base import InboundMessage + + +class FakeMsg: + def __init__(self, subject: str, data: bytes, reply: str = ""): + self.subject = subject + self.data = data + self.reply = reply + + def decode(self) -> str: + return self.data.decode() + + +class FakeNATS: + """Minimal SyncNATS stand-in: records subs/pubs, replays on demand.""" + + def __init__(self, *a, **kw): + self.subs: dict[str, Any] = {} + self.pubs: list[tuple[str, bytes]] = [] + self.closed = False + + def subscribe(self, subject, cb): + self.subs[subject] = cb + return f"sid-{len(self.subs)}" + + def unsubscribe(self, sid): + pass + + def publish(self, subject, data): + self.pubs.append((subject, data)) + + def close(self): + self.closed = True + + +@pytest.fixture() +def ch_and_nc(): + nc = FakeNATS() + ch = NatsChannel({"servers": "nats://x:4222"}, nats_factory=lambda *a, **kw: nc) + inbound: list[InboundMessage] = [] + ch.on_message(inbound.append) + ch.start() + yield ch, nc, inbound + ch.stop() + + +def _feed(nc: FakeNATS, subject: str, payload: dict, reply: str = ""): + cb = next(iter(nc.subs.values())) + cb(FakeMsg(subject, json.dumps(payload).encode(), reply)) + + +def test_start_subscribes_and_stop_closes(ch_and_nc): + ch, nc, _ = ch_and_nc + assert "agenthub.in.>" in nc.subs + ch.stop() + assert nc.closed + + +def test_inbound_message_dispatch(ch_and_nc): + ch, nc, inbound = ch_and_nc + _feed(nc, "agenthub.in.chat1", {"chat_id": "chat1", "user_id": "u1", "text": "hello"}) + assert len(inbound) == 1 + m = inbound[0] + assert m.channel == "nats" + assert m.chat_id == "chat1" + assert m.user_id == "u1" + assert m.text == "hello" + assert m.raw["subject"] == "agenthub.in.chat1" + + +def test_inbound_chat_id_falls_back_to_subject(ch_and_nc): + ch, nc, inbound = ch_and_nc + _feed(nc, "agenthub.in.room9", {"text": "hi"}) + assert inbound[0].chat_id == "room9" + assert inbound[0].user_id == "room9" + + +def test_inbound_allowed_users_gate(ch_and_nc): + ch, nc, inbound = ch_and_nc + ch.allowed_users = {"alice"} + _feed(nc, "agenthub.in.c1", {"chat_id": "c1", "user_id": "bob", "text": "x"}) + assert inbound == [] + _feed(nc, "agenthub.in.c1", {"chat_id": "c1", "user_id": "alice", "text": "x"}) + assert len(inbound) == 1 + + +def test_inbound_bad_json_does_not_raise(ch_and_nc): + ch, nc, inbound = ch_and_nc + cb = next(iter(nc.subs.values())) + cb(FakeMsg("agenthub.in.c1", b"not json")) + cb(FakeMsg("agenthub.in.c1", json.dumps({"text": " "}).encode())) # empty text + assert inbound == [] + + +def test_final_event_publishes_to_out_subject(ch_and_nc): + ch, nc, _ = ch_and_nc + ch.push_event("chat1", "final", {"text": "answer"}) + assert nc.pubs == [("agenthub.out.chat1", json.dumps({"chat_id": "chat1", "text": "answer"}, ensure_ascii=False).encode())] + + +def test_delta_dropped_status_published(ch_and_nc): + ch, nc, _ = ch_and_nc + ch.push_event("c", "delta", {"text": "partial"}) + assert nc.pubs == [] + ch.push_event("c", "status", {"text": "running..."}) + assert nc.pubs[0][0] == "agenthub.out.c" + assert b"running..." in nc.pubs[0][1] + + +def test_interaction_renders_numbered_options(ch_and_nc): + ch, nc, _ = ch_and_nc + ch.push_event("c", "interaction", { + "interaction_type": "permission", "tool": "execute", + "options": [{"option_id": "allow", "name": "Allow once", "kind": "allow_once"}], + "request_id": "req-1", + }) + subject, body = nc.pubs[0] + assert subject == "agenthub.out.c" + text = json.loads(body)["text"] + assert "execute" in text and "Allow once" in text and "req-1" in text + + +def test_reply_splits_long_text(ch_and_nc): + ch, nc, _ = ch_and_nc + ch.reply("c", "x" * 1_200_000) # > 900k budget -> 2 chunks + assert len(nc.pubs) == 2 + total = sum(len(json.loads(b)["text"]) for _, b in nc.pubs) + assert total >= 1_199_000