@cotal-ai/connector-hermes 0.1.0

package/plugin/cotal/adapter.py

@@ -0,0 +1,114 @@
+"""Cotal gateway platform adapter.
+
+Inbound: the sidecar pushes mesh messages over the bridge; the adapter builds a ``MessageEvent``
+and calls ``handle_message`` — which wakes an idle session or **queues + interrupts a running one**
+(the gateway's own busy handling), so a peer can DRIVE a live turn, not just leave a message.
+Outbound: the gateway hands a turn's reply to ``send()``, which the adapter routes back to that
+message's mesh origin (the channel it came in on, or a DM to the sender).
+"""
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any, Optional
+
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+from gateway.config import Platform, PlatformConfig
+
+from . import hooks
+from .bridge_client import get_client
+
+
+def _target_for(chat_id: str) -> dict:
+    """Reverse the chat_id minted on inbound back into a mesh reply target."""
+    if chat_id.startswith("channel:"):
+        return {"channel": chat_id[len("channel:"):]}
+    if chat_id.startswith("dm:"):
+        return {"peerId": chat_id[len("dm:"):]}
+    return {}
+
+
+class CotalAdapter(BasePlatformAdapter):
+    def __init__(self, config: PlatformConfig) -> None:
+        super().__init__(config, Platform("cotal"))
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._client = get_client()
+
+    async def connect(self) -> bool:
+        self._loop = asyncio.get_running_loop()
+        self._client.start(self._on_incoming)  # reader thread → _on_incoming
+        self._mark_connected()
+        hooks.relay("gateway_startup")  # present + free
+        return True
+
+    async def disconnect(self) -> None:
+        hooks.relay("gateway_shutdown")
+        self._client.close()
+        self._mark_disconnected()
+
+    async def send(
+        self, chat_id: str, content: str, reply_to: Any = None, metadata: Any = None
+    ) -> SendResult:
+        # The gateway delivers a turn's reply here → route it back to the message's mesh origin.
+        self._client.reply(_target_for(chat_id), content)
+        return SendResult(success=True, message_id=uuid.uuid4().hex)
+
+    async def get_chat_info(self, chat_id: str) -> dict:
+        if chat_id.startswith("channel:"):
+            return {"name": "#" + chat_id[len("channel:"):], "type": "group"}
+        return {"name": chat_id, "type": "dm"}
+
+    # ---- inbound (bridge reader thread → gateway loop) -----------------------
+
+    def _on_incoming(self, msg: dict) -> None:
+        """Called off-loop by the bridge reader; hop onto the gateway loop to inject the turn."""
+        loop = self._loop
+        if loop is None:
+            return
+        fut = asyncio.run_coroutine_threadsafe(self._inject(msg), loop)
+        fut.add_done_callback(lambda f: self._maybe_ack(msg, f))
+
+    def _maybe_ack(self, msg: dict, fut: Any) -> None:
+        """Ack a message on the mesh stream once it has been surfaced into a turn.
+
+        VALIDATION GATE (open confirmation #4): ``handle_message`` returning means the event was
+        *queued*, not necessarily *consumed into a turn*. On the pinned Hermes line, confirm the
+        completion point and, if needed, move this ack to a real processing-complete hook/wrapper —
+        do NOT relax it to ack-on-queue (a mesh message that never reaches the model must redeliver
+        after a crash). Until proven, this acks on the inject coroutine completing without error.
+        """
+        mid = msg.get("id")
+        if mid and not fut.cancelled() and fut.exception() is None:
+            self._client.delivered(mid)
+
+    async def _inject(self, msg: dict) -> None:
+        kind = msg.get("kind")
+        sender = msg.get("fromName") or "peer"
+        role = msg.get("fromRole")
+        tag = f"[{kind} from {sender}{f' / {role}' if role else ''}] "
+
+        if kind == "channel":
+            ch = msg.get("channel") or "general"
+            chat_id, chat_type, chat_name = f"channel:{ch}", "group", f"#{ch}"
+        else:  # dm / anycast → a turn whose reply goes straight back to the sender
+            chat_id, chat_type, chat_name = f"dm:{msg.get('fromId')}", "dm", sender
+
+        source = self.build_source(
+            chat_id=chat_id,
+            chat_name=chat_name,
+            chat_type=chat_type,
+            user_id=msg.get("fromId"),
+            user_name=sender,
+        )
+        event = MessageEvent(
+            text=tag + (msg.get("text") or ""),
+            message_type=MessageType.TEXT,
+            source=source,
+            message_id=msg.get("id"),
+        )
+        await self.handle_message(event)

package/plugin/cotal/bridge_client.py

@@ -0,0 +1,153 @@
+"""Persistent client to the Cotal sidecar's bridge socket.
+
+The sidecar (``src/sidecar.ts``) owns the mesh endpoint and exposes a unix-socket bridge; this is
+the in-gateway half. One background thread owns a blocking ``AF_UNIX`` connection and dispatches
+frames — inbound mesh messages go to the adapter's callback, tool results resolve pending calls.
+Writes are newline-delimited JSON under a lock; it reconnects with backoff so a sidecar restart
+self-heals (re-subscribing on every (re)connect). Wire format mirrors ``src/bridge.ts``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import threading
+import time
+import uuid
+from typing import Any, Callable, Optional
+
+_BACKOFF_S = 2.0
+
+
+class BridgeClient:
+    def __init__(self, socket_path: str) -> None:
+        self._path = socket_path
+        self._sock: Optional[socket.socket] = None
+        self._lock = threading.Lock()
+        self._pending: dict[str, tuple[threading.Event, dict]] = {}
+        self._on_incoming: Optional[Callable[[dict], None]] = None
+        self._stop = threading.Event()
+        self._reader: Optional[threading.Thread] = None
+
+    def start(self, on_incoming: Callable[[dict], None]) -> None:
+        """Begin the reader thread. ``on_incoming`` is called (off-loop) for each mesh message."""
+        self._on_incoming = on_incoming
+        if self._reader is None:
+            self._reader = threading.Thread(target=self._run, name="cotal-bridge", daemon=True)
+            self._reader.start()
+
+    # ---- reader thread -------------------------------------------------------
+
+    def _run(self) -> None:
+        buf = b""
+        while not self._stop.is_set():
+            if self._sock is None:
+                self._connect()
+                if self._sock is None:
+                    continue
+                self._send({"t": "subscribe"})  # (re)subscribe after every (re)connect
+            try:
+                data = self._sock.recv(65536)
+            except OSError:
+                data = b""
+            if not data:
+                with self._lock:
+                    self._sock = None
+                continue
+            buf += data
+            while b"\n" in buf:
+                line, buf = buf.split(b"\n", 1)
+                if line.strip():
+                    self._dispatch(line)
+
+    def _connect(self) -> None:
+        while not self._stop.is_set():
+            try:
+                s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                s.connect(self._path)
+                with self._lock:
+                    self._sock = s
+                return
+            except OSError:
+                time.sleep(_BACKOFF_S)
+
+    def _dispatch(self, line: bytes) -> None:
+        try:
+            frame = json.loads(line)
+        except ValueError:
+            return
+        t = frame.get("t")
+        if t == "incoming":
+            cb = self._on_incoming
+            if cb:
+                cb(frame.get("msg") or {})
+        elif t == "tool_result":
+            entry = self._pending.get(frame.get("id"))
+            if entry:
+                entry[1].update(frame)
+                entry[0].set()
+
+    # ---- writes --------------------------------------------------------------
+
+    def _send(self, frame: dict) -> None:
+        data = (json.dumps(frame) + "\n").encode()
+        with self._lock:
+            if self._sock is None:
+                return
+            try:
+                self._sock.sendall(data)
+            except OSError:
+                self._sock = None
+
+    def delivered(self, msg_id: str) -> None:
+        """Ack a message on the stream — call only once it has been surfaced into a turn."""
+        self._send({"t": "delivered", "id": msg_id})
+
+    def reply(self, target: dict, text: str) -> None:
+        """Route a turn's reply back to its mesh origin (channel broadcast or DM to the sender)."""
+        self._send({"t": "reply", "target": target, "text": text})
+
+    def call_tool(self, name: str, args: dict, timeout: float = 30.0) -> str:
+        """Invoke a cotal_* tool on the sidecar and block for its text result (raises on transport
+        error/timeout). The sidecar runs the shared spec, so the text is already model-ready; an
+        in-tool logical error comes back flagged and is prefixed for the model."""
+        rid = uuid.uuid4().hex
+        ev = threading.Event()
+        box: dict = {}
+        self._pending[rid] = (ev, box)
+        try:
+            self._send({"t": "tool", "id": rid, "name": name, "args": args})
+            if not ev.wait(timeout):
+                raise TimeoutError(f"cotal tool '{name}' timed out")
+            if not box.get("ok"):
+                raise RuntimeError(box.get("error") or "tool failed")
+            text = box.get("text") or ""
+            return f"⚠ {text}" if box.get("isError") else text
+        finally:
+            self._pending.pop(rid, None)
+
+    def close(self) -> None:
+        self._stop.set()
+        with self._lock:
+            if self._sock is not None:
+                try:
+                    self._sock.close()
+                except OSError:
+                    pass
+                self._sock = None
+
+
+_client: Optional[BridgeClient] = None
+
+
+def get_client() -> BridgeClient:
+    """Process-wide singleton, bound to ``COTAL_BRIDGE_SOCKET`` (set by the launcher/bootstrap)."""
+    global _client
+    if _client is None:
+        path = os.environ.get("COTAL_BRIDGE_SOCKET")
+        if not path:
+            raise RuntimeError(
+                "COTAL_BRIDGE_SOCKET not set — the Cotal launcher or standalone bootstrap must set it"
+            )
+        _client = BridgeClient(path)
+    return _client

package/plugin/cotal/hooks.py

@@ -0,0 +1,74 @@
+"""Hermes lifecycle hooks → Cotal presence (the relay.ts pattern, in Python).
+
+Each hook makes a one-shot connection to connector-core's control socket
+(``COTAL_CONTROL_SOCKET``), sends ``{"hook_event_name": ...}``, and ignores the reply — the TS
+``hermesHookHandle`` turns it into a presence change. Hooks must never block the gateway, so the
+connection has a short timeout and every error is swallowed.
+
+Hermes hook callback signatures vary by version; these take ``*args, **kwargs`` and best-effort
+extract what they need, so a signature change degrades to "no detail" rather than an exception.
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+from typing import Any
+
+_TIMEOUT_S = 2.0
+
+
+def relay(event_name: str, **fields: Any) -> None:
+    """Forward one lifecycle event to the connector's control socket; fire-and-forget."""
+    path = os.environ.get("COTAL_CONTROL_SOCKET")
+    if not path:
+        return
+    payload = {"hook_event_name": event_name, **fields}
+    try:
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(_TIMEOUT_S)
+        s.connect(path)
+        s.sendall((json.dumps(payload) + "\n").encode())
+        try:
+            s.recv(65536)  # read + discard the reply
+        except OSError:
+            pass
+        s.close()
+    except OSError:
+        pass
+
+
+def _extract_tool(args: tuple, kwargs: dict) -> tuple[str, Any]:
+    """Best-effort tool name + input from whatever Hermes passes the pre_tool_call hook."""
+    ctx: dict = {}
+    for a in args:
+        if isinstance(a, dict):
+            ctx = a
+            break
+    ctx = {**ctx, **kwargs}
+    name = ctx.get("tool_name") or ctx.get("name") or ctx.get("tool") or ""
+    inp = ctx.get("tool_input") or ctx.get("arguments") or ctx.get("input") or ctx.get("args")
+    return str(name), inp
+
+
+# ---- hook callbacks (registered in __init__.register) -----------------------
+
+def on_session_start(*args: Any, **kwargs: Any) -> None:
+    relay("on_session_start")
+
+
+def pre_llm_call(*args: Any, **kwargs: Any) -> None:
+    relay("pre_llm_call")
+
+
+def pre_tool_call(*args: Any, **kwargs: Any) -> None:
+    name, inp = _extract_tool(args, kwargs)
+    relay("pre_tool_call", tool_name=name, tool_input=inp)
+
+
+def post_llm_call(*args: Any, **kwargs: Any) -> None:
+    relay("post_llm_call")
+
+
+def on_session_end(*args: Any, **kwargs: Any) -> None:
+    relay("on_session_end")

package/plugin/cotal/plugin.yaml

@@ -0,0 +1,10 @@
+name: cotal
+label: Cotal
+kind: platform
+version: 0.1.0
+description: Join the Cotal mesh — coordinate with other AI agents as lateral peers over NATS.
+author: Cotal
+# COTAL_BRIDGE_SOCKET is intentionally NOT declared as a required/prompted env var: in managed
+# mode the Cotal launcher always presets it, and in standalone mode (a user's own `hermes`) the
+# plugin spawns the bundled sidecar itself and derives it — see __init__.register(). The platform's
+# check_fn gates enablement instead, so an unrelated gateway never gets prompted for it.

package/plugin/cotal/tools.py

@@ -0,0 +1,62 @@
+"""cotal_* tools — the deliberate, proactive mesh actions, exposed to the Hermes agent.
+
+A turn's *reply* is delivered automatically (the adapter routes it back to whoever messaged), so
+these tools are for reaching OTHER peers/channels, seeing who's around, reporting status, and
+growing the team. We do NOT hand-write the list: the TS sidecar renders it once from the shared
+``cotalToolSpecs`` and writes the descriptors to ``COTAL_TOOLS_FILE``; this reads that file and
+registers each as a Hermes plugin tool whose handler forwards the call (by name) over the bridge
+and returns the sidecar's already-formatted text result.
+
+The exact ``ctx.register_tool`` schema/handler contract is the Hermes 0.16 plugin API; adjust the
+``_spec`` shape if a pinned version differs.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Callable
+
+from .bridge_client import get_client
+
+
+def _spec(descriptor: dict) -> dict:
+    """A Hermes tool spec from a sidecar descriptor ({name, description, parameters})."""
+    params = descriptor.get("parameters") or {"type": "object", "properties": {}, "required": []}
+    return {
+        "name": descriptor["name"],
+        "description": descriptor.get("description", ""),
+        "parameters": params,
+    }
+
+
+def _handler(name: str) -> Callable[[dict], str]:
+    """Forward a tool call to the sidecar; the sidecar runs the shared spec and returns the text."""
+    def run(args: dict) -> str:
+        try:
+            return get_client().call_tool(name, args or {})
+        except Exception as e:  # surfaced back to the model as the tool result
+            return f"cotal error: {e}"
+
+    return run
+
+
+def _load_descriptors() -> list[dict]:
+    path = os.environ.get("COTAL_TOOLS_FILE")
+    if not path:
+        raise RuntimeError("COTAL_TOOLS_FILE not set — the sidecar must publish the tool descriptors")
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, list):
+        raise RuntimeError(f"COTAL_TOOLS_FILE {path} did not contain a tool list")
+    return data
+
+
+def register_tools(ctx: Any) -> None:
+    for descriptor in _load_descriptors():
+        name = descriptor["name"]
+        ctx.register_tool(
+            name=name,
+            toolset="cotal",
+            schema=_spec(descriptor),
+            handler=_handler(name),
+        )

package/pyproject.toml

@@ -0,0 +1,19 @@
+# The managed launcher runs the gateway via `uv run --project <this dir> hermes gateway run`,
+# so uv provisions an env that provides the `hermes` CLI. This is NOT a Python package itself
+# (the plugin dir is copied into HERMES_HOME at launch) — `package = false` keeps uv from
+# building it.
+#
+# Pin: the connector is written against the Hermes 0.16 plugin/platform API. The TS sidecar
+# asserts the installed version is on that line at startup and fails loudly on a mismatch
+# (no silent degrade) — keep this pin and the assertion in src/launch.ts in sync.
+[project]
+name = "cotal-connector-hermes"
+version = "0.1.0"
+description = "Run the Hermes (Nous Research) agent as a Cotal mesh peer."
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "hermes-agent>=0.16,<0.17",
+]
+
+[tool.uv]
+package = false