kojee-mcp 0.5.13 → 0.5.14

package/dist/cli.js

@@ -140,7 +140,7 @@ program.command("init").description(
     console.error("Not paired. Run `kojee-mcp pair <code> --url <broker>` first, then re-run `init` \u2014 or pass --token/--pair-code, or run `init` in a terminal for the guided wizard.");
     process.exit(1);
   }
-  const { runWizard } = await import("./wizard-L4MYRLJI.js");
+  const { runWizard } = await import("./wizard-5ILBK6YD.js");
   const result = await runWizard({
     ...opts.runtime !== void 0 ? { runtime: opts.runtime } : {},
     ...opts.uninstall ? { uninstall: true } : {},

package/dist/plugins/hermes/__init__.py

@@ -0,0 +1,21 @@
+"""Hermes plugin package entry for kojee-tandem.
+
+Inside Hermes, hermes_cli/plugins.py loads this dir as the package
+``hermes_plugins.kojee_tandem`` and calls ``register(ctx)``.
+
+FAIL-SOFT IMPORT: outside that loader (e.g. pytest collecting this dir as a
+Package on a box without Hermes) the relative import below cannot resolve —
+``gateway.*`` doesn't exist and there is no parent package. We degrade to
+``register = None`` instead of raising so tooling can walk the tree; the
+Hermes loader itself would surface a real adapter bug as a loud
+"Plugin 'kojee-tandem' has no register() function" + this module's import
+error in the gateway log, not as a silent no-op.
+"""
+
+try:
+    from .adapter import register
+except ImportError as _exc:  # pragma: no cover — outside the Hermes loader
+    register = None
+    _IMPORT_ERROR = _exc
+
+__all__ = ["register"]

package/dist/plugins/hermes/adapter.py

@@ -0,0 +1,481 @@
+"""Kojee Tandem platform adapter for the Hermes agent gateway (v1, sidecar).
+
+Makes Tandem a first-class Hermes channel: install this plugin dir as
+``~/.hermes/plugins/kojee-tandem/`` and Tandem messages wake the agent exactly
+like a Telegram DM — per-tandem chat ids, Hermes-native sessions, allowlists.
+
+Architecture (v1 — the kojee-mcp daemon is the sidecar, never forked):
+
+    Tandem cloud ──SSE──> kojee-mcp daemon ──signed webhook POST──>
+        this adapter's loopback HTTP listener ──MessageEvent──> Hermes agent
+    agent reply ──send()──> `kojee-mcp send` CLI (0.5.4+, the shipped local
+        SEND control surface; same paired ~/.kojee creds + DPoP keystore the
+        daemon uses) ──tandem_send──> Tandem cloud
+
+Outbound (T10): the reply path shells the shipped ``kojee-mcp send``
+sub-command rather than a tsx helper that dynamically imports source modules,
+so the install no longer requires a kojee-mcp SOURCE checkout — only the
+``kojee-mcp`` binary (KOJEE_MCP_BIN, with a PATH fallback) and a paired
+``~/.kojee``.
+
+Coded against (pinned upstream source, NousResearch/hermes-agent @ main):
+  - gateway/platforms/base.py: BasePlatformAdapter.__init__(config, platform)
+    (line 1826), abstract connect (2244) / disconnect (2253) / send (2258) /
+    get_chat_info (4709); send_typing default no-op (2534); build_source
+    (4669); handle_message (3839); MessageEvent (1413); SendResult (1542).
+  - gateway/config.py Platform._missing_ (167): "kojee-tandem" resolves as a
+    runtime-registered pseudo-member AFTER register() runs — registration
+    precedes adapter construction, so Platform("kojee-tandem") is safe here.
+  - hermes_cli/plugins.py PluginContext.register_platform (770) forwarding
+    **entry_kwargs to gateway/platform_registry.py PlatformEntry (39).
+  - plugins/platforms/irc/ — the bundled-plugin idiom this file mirrors.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+)
+from gateway.config import Platform
+
+from .kojee_tandem_core import (
+    EventDeduper,
+    build_send_command,
+    is_self_event,
+    load_self_session_id,
+    normalize_event,
+    parse_allowlist,
+    parse_send_envelope,
+    resolve_kojee_mcp_bin,
+    tandem_allowed,
+    verify_signature,
+)
+
+logger = logging.getLogger(__name__)
+
+PLATFORM_NAME = "kojee-tandem"
+
+# Loopback listener defaults. 8645 sits next to Hermes's own webhook platform
+# (8644) — same box, same loopback-only posture, never exposed publicly.
+DEFAULT_LISTEN_HOST = "127.0.0.1"
+DEFAULT_LISTEN_PORT = 8645
+DEFAULT_LISTEN_PATH = "/kojee-tandem"
+DEFAULT_SEND_TIMEOUT_S = 45.0
+
+
+def _env_or_extra(extra: dict, env_name: str, extra_key: str, default: str = "") -> str:
+    """env var wins over config.yaml extra (Hermes precedence convention)."""
+    return os.getenv(env_name) or str(extra.get(extra_key, "") or "") or default
+
+
+class KojeeTandemAdapter(BasePlatformAdapter):
+    """Tandem as a Hermes platform, driving the kojee-mcp daemon as a sidecar."""
+
+    def __init__(self, config, **kwargs):
+        platform = Platform(PLATFORM_NAME)
+        super().__init__(config=config, platform=platform)
+
+        extra = getattr(config, "extra", {}) or {}
+
+        self.listen_host = _env_or_extra(
+            extra, "KOJEE_TANDEM_LISTEN_HOST", "listen_host", DEFAULT_LISTEN_HOST
+        )
+        try:
+            self.listen_port = int(
+                _env_or_extra(
+                    extra, "KOJEE_TANDEM_LISTEN_PORT", "listen_port", str(DEFAULT_LISTEN_PORT)
+                )
+            )
+        except (TypeError, ValueError):
+            self.listen_port = DEFAULT_LISTEN_PORT
+        self.listen_path = _env_or_extra(
+            extra, "KOJEE_TANDEM_LISTEN_PATH", "listen_path", DEFAULT_LISTEN_PATH
+        )
+        if not self.listen_path.startswith("/"):
+            self.listen_path = "/" + self.listen_path
+
+        # The HMAC secret MUST equal the daemon's KOJEE_WEBHOOK_SECRET — both
+        # ends of one wire. Never logged.
+        self.webhook_secret = _env_or_extra(
+            extra, "KOJEE_WEBHOOK_SECRET", "webhook_secret"
+        )
+
+        # Outbound (T10): shell the shipped `kojee-mcp send` CLI. The binary is
+        # KOJEE_MCP_BIN (absolute — fold B, login-shell PATH may not apply inside
+        # the gateway process) with a `kojee-mcp`-on-PATH fallback. No source
+        # checkout required anymore.
+        # TODO(hermes-installer): wizard writes KOJEE_MCP_BIN at install
+        # (src/wizard/installers/hermes.ts); until then the PATH fallback carries it.
+        self.kojee_mcp_bin = resolve_kojee_mcp_bin(os.environ)
+        self.kojee_dir = Path(
+            _env_or_extra(extra, "KOJEE_DIR", "kojee_dir", str(Path.home() / ".kojee"))
+        )
+
+        # Tandem allowlist (which tandems may inject). Empty = all tandems;
+        # per-USER authorization stays with Hermes via KOJEE_TANDEM_ALLOWED_USERS.
+        self.tandem_allowlist = parse_allowlist(
+            _env_or_extra(extra, "KOJEE_TANDEM_ALLOWLIST", "tandem_allowlist")
+        )
+
+        # Self-echo filters: derived session id (paired config) + optional principal.
+        self.self_principal = _env_or_extra(
+            extra, "KOJEE_TANDEM_SELF_PRINCIPAL", "self_principal"
+        ) or None
+        self._self_session_id = load_self_session_id(self.kojee_dir)
+
+        try:
+            self.send_timeout_s = float(
+                _env_or_extra(
+                    extra, "KOJEE_TANDEM_SEND_TIMEOUT_S", "send_timeout_s",
+                    str(DEFAULT_SEND_TIMEOUT_S),
+                )
+            )
+        except (TypeError, ValueError):
+            self.send_timeout_s = DEFAULT_SEND_TIMEOUT_S
+
+        self._deduper = EventDeduper()
+        self._runner = None  # aiohttp.web.AppRunner
+        self._site = None    # aiohttp.web.TCPSite
+
+    @property
+    def name(self) -> str:
+        return "Kojee Tandem"
+
+    # ── Connection lifecycle ────────────────────────────────────────────
+
+    async def connect(self) -> bool:
+        """Start the loopback webhook listener the kojee-mcp daemon POSTs to."""
+        if not self.webhook_secret:
+            logger.error("kojee-tandem: KOJEE_WEBHOOK_SECRET must be set (signed-only inbound)")
+            self._set_fatal_error(
+                "config_missing",
+                "KOJEE_WEBHOOK_SECRET must be set — the adapter never accepts unsigned events",
+                retryable=False,
+            )
+            return False
+
+        logger.info(
+            "kojee-tandem: outbound via `%s send` (set KOJEE_MCP_BIN to an "
+            "absolute path if `kojee-mcp` is not on the gateway process PATH)",
+            self.kojee_mcp_bin,
+        )
+
+        try:
+            from aiohttp import web
+        except ImportError:
+            logger.error("kojee-tandem: aiohttp not available (pip install aiohttp)")
+            self._set_fatal_error(
+                "missing_dependency", "aiohttp is required", retryable=False
+            )
+            return False
+
+        app = web.Application()
+        app.router.add_post(self.listen_path, self._handle_webhook)
+        app.router.add_get("/health", self._handle_health)
+
+        try:
+            self._runner = web.AppRunner(app)
+            await self._runner.setup()
+            self._site = web.TCPSite(self._runner, self.listen_host, self.listen_port)
+            await self._site.start()
+        except OSError as e:
+            logger.error(
+                "kojee-tandem: cannot bind %s:%s — %s",
+                self.listen_host, self.listen_port, e,
+            )
+            self._set_fatal_error("bind_failed", str(e), retryable=True)
+            return False
+
+        self._mark_connected()
+        logger.info(
+            "kojee-tandem: listening on http://%s:%s%s (point the kojee-mcp "
+            "daemon's KOJEE_WEBHOOK_URL here)",
+            self.listen_host, self.listen_port, self.listen_path,
+        )
+        return True
+
+    async def disconnect(self) -> None:
+        self._mark_disconnected()
+        if self._runner is not None:
+            try:
+                await self._runner.cleanup()
+            except Exception:
+                pass
+        self._runner = None
+        self._site = None
+
+    # ── Inbound: webhook → MessageEvent ─────────────────────────────────
+
+    async def _handle_health(self, request):
+        from aiohttp import web
+        return web.json_response({"ok": True, "platform": PLATFORM_NAME})
+
+    async def _handle_webhook(self, request):
+        """One TandemEvent per POST (webhook-sink contract). Verify HMAC over
+        the RAW bytes, normalize, filter, inject. Filtered events are ACKed
+        with 200 — a 4xx would make the sink drop-as-permanent or retry-burn,
+        and redelivery on daemon restart is NORMAL (at-least-once)."""
+        from aiohttp import web
+
+        raw = await request.read()
+        if not verify_signature(request.headers, raw, self.webhook_secret):
+            # 401 is correct here: a bad signature is never OUR event.
+            # (4xx = permanent drop in the sink — desired for forged traffic.)
+            return web.json_response({"error": "invalid signature"}, status=401)
+
+        try:
+            payload = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return web.json_response({"error": "invalid json"}, status=400)
+
+        msg = normalize_event(payload)
+        if msg is None:
+            return web.json_response({"ok": True, "ignored": "not an injectable message"})
+        if self._deduper.seen_before(msg.event_id):
+            return web.json_response({"ok": True, "ignored": "duplicate"})
+        if not tandem_allowed(msg.chat_id, self.tandem_allowlist):
+            logger.debug("kojee-tandem: tandem %s not in allowlist — ignored", msg.chat_id)
+            return web.json_response({"ok": True, "ignored": "tandem not allowed"})
+        if is_self_event(msg, self._self_session_id, self.self_principal):
+            return web.json_response({"ok": True, "ignored": "self echo"})
+
+        source = self.build_source(
+            chat_id=msg.chat_id,                 # tandem_id = the chat id
+            chat_name=f"Tandem {msg.chat_id}",
+            chat_type="group",                   # tandems are multi-member rooms
+            user_id=msg.sender_id,               # principal — Hermes authz key
+            user_name=msg.sender_name,           # sender display
+            message_id=msg.message_id,           # cursor
+        )
+        event = MessageEvent(
+            text=msg.text,
+            message_type=MessageType.TEXT,
+            source=source,
+            raw_message=payload,
+            message_id=msg.message_id,           # cursor as the message id
+            reply_to_message_id=msg.reply_to,
+        )
+        # handle_message returns fast (spawns background tasks) — base.py:3839.
+        await self.handle_message(event)
+        return web.json_response({"ok": True})
+
+    # ── Outbound: send → `kojee-mcp send` CLI → tandem_send ─────────────
+
+    async def send(
+        self,
+        chat_id: str,
+        content: str,
+        reply_to: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SendResult:
+        return await _cli_send(
+            kojee_mcp_bin=self.kojee_mcp_bin,
+            kojee_dir=self.kojee_dir,
+            tandem_id=chat_id,
+            body=content,
+            reply_to=reply_to,
+            timeout_s=self.send_timeout_s,
+        )
+
+    async def send_typing(self, chat_id: str, metadata=None) -> None:
+        """v1 no-op: the helper does not expose a Tandem typing call yet."""
+        pass
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        return {
+            "name": f"Tandem {chat_id}",
+            "type": "group",
+            "chat_id": chat_id,
+        }
+
+
+def _send_env(kojee_dir: Path) -> Dict[str, str]:
+    """Subprocess env for the `kojee-mcp send` CLI.
+
+    The CLI resolves paired credentials from ``os.homedir()/.kojee`` with no
+    flag/env override on the `send` sub-command. To honor a configured KOJEE_DIR
+    of the form ``<base>/.kojee`` we point HOME at ``<base>`` so the CLI's
+    ``~/.kojee`` resolves to the configured dir; otherwise the inherited HOME
+    (default ``~/.kojee``) applies."""
+    env = dict(os.environ)
+    if kojee_dir.name == ".kojee":
+        env["HOME"] = str(kojee_dir.parent)
+    return env
+
+
+async def _cli_send(
+    kojee_mcp_bin: str,
+    kojee_dir: Path,
+    tandem_id: str,
+    body: str,
+    reply_to: Optional[str],
+    timeout_s: float,
+) -> SendResult:
+    """Shell `kojee-mcp send <tandem_id> --body <text> [--reply-to]`; the CLI
+    signs with the same paired ~/.kojee creds + DPoP keystore the daemon uses
+    and prints one JSON envelope on stdout. Shared by the live adapter send()
+    and the standalone cron sender. No source checkout required (T10)."""
+    argv = build_send_command(kojee_mcp_bin, tandem_id, body, reply_to)
+    env = _send_env(kojee_dir)
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+        stdout_b, stderr_b = await asyncio.wait_for(
+            proc.communicate(), timeout=timeout_s
+        )
+    except asyncio.TimeoutError:
+        try:
+            proc.kill()
+        except ProcessLookupError:
+            pass
+        return SendResult(success=False, error=f"`kojee-mcp send` timed out after {timeout_s}s")
+    except FileNotFoundError:
+        return SendResult(
+            success=False,
+            error=(
+                f"`kojee-mcp` binary not found ({kojee_mcp_bin}) — set KOJEE_MCP_BIN "
+                "to an absolute path or put kojee-mcp on PATH"
+            ),
+        )
+    except OSError as e:
+        return SendResult(success=False, error=f"failed to launch `kojee-mcp send`: {e}")
+
+    verdict = parse_send_envelope(stdout_b.decode("utf-8", errors="replace"))
+    if verdict["ok"]:
+        return SendResult(
+            success=True,
+            message_id=verdict["message_id"] or str(int(time.time() * 1000)),
+        )
+    stderr_tail = stderr_b.decode("utf-8", errors="replace").strip()[-300:]
+    error = verdict["error"] or "tandem_send failed"
+    if stderr_tail:
+        error = f"{error} | stderr: {stderr_tail}"
+    return SendResult(success=False, error=error)
+
+
+# ── Registration plumbing (mirrors plugins/platforms/irc/adapter.py) ────────
+
+def check_requirements() -> bool:
+    """Dependencies + minimal config: aiohttp importable and a secret set.
+    (Config-yaml-only setups validate via validate_config instead.)"""
+    try:
+        import aiohttp  # noqa: F401
+    except ImportError:
+        return False
+    return bool(os.getenv("KOJEE_WEBHOOK_SECRET"))
+
+
+def validate_config(config) -> bool:
+    extra = getattr(config, "extra", {}) or {}
+    secret = os.getenv("KOJEE_WEBHOOK_SECRET") or extra.get("webhook_secret", "")
+    return bool(secret)
+
+
+def is_connected(config) -> bool:
+    return validate_config(config)
+
+
+def _env_enablement() -> Optional[dict]:
+    """Seed PlatformConfig.extra from env BEFORE adapter construction so
+    env-only setups surface in `hermes gateway status` (registry hook —
+    see ADDING_A_PLATFORM.md optional hooks)."""
+    secret = os.getenv("KOJEE_WEBHOOK_SECRET", "").strip()
+    if not secret:
+        return None
+    seed: dict = {"webhook_secret": secret}
+    for env_name, key in (
+        ("KOJEE_TANDEM_LISTEN_HOST", "listen_host"),
+        ("KOJEE_TANDEM_LISTEN_PORT", "listen_port"),
+        ("KOJEE_TANDEM_LISTEN_PATH", "listen_path"),
+        ("KOJEE_DIR", "kojee_dir"),
+        ("KOJEE_TANDEM_ALLOWLIST", "tandem_allowlist"),
+        ("KOJEE_TANDEM_SELF_PRINCIPAL", "self_principal"),
+    ):
+        value = os.getenv(env_name, "").strip()
+        if value:
+            seed[key] = value
+    home = os.getenv("KOJEE_TANDEM_HOME_CHANNEL", "").strip()
+    if home:
+        # Handled by the core hook: becomes a HomeChannel on the PlatformConfig.
+        seed["home_channel"] = {"chat_id": home, "name": f"Tandem {home}"}
+    return seed
+
+
+async def _standalone_send(
+    pconfig,
+    chat_id: str,
+    message: str,
+    *,
+    thread_id: Optional[str] = None,
+    media_files: Optional[List[str]] = None,
+    force_document: bool = False,
+) -> Dict[str, Any]:
+    """Out-of-process delivery for `deliver=kojee-tandem` cron jobs (the
+    standalone_sender_fn registry hook). Reuses the same `kojee-mcp send` CLI —
+    no live adapter, no source checkout needed. thread_id/media_files accepted
+    for signature parity; Tandem has no native thread/attachment primitive in v1."""
+    kojee_mcp_bin = resolve_kojee_mcp_bin(os.environ)
+    extra = getattr(pconfig, "extra", {}) or {}
+    kojee_dir = Path(os.getenv("KOJEE_DIR") or extra.get("kojee_dir", "") or (Path.home() / ".kojee"))
+    result = await _cli_send(
+        kojee_mcp_bin=kojee_mcp_bin,
+        kojee_dir=kojee_dir,
+        tandem_id=chat_id,
+        body=message,
+        reply_to=None,
+        timeout_s=DEFAULT_SEND_TIMEOUT_S,
+    )
+    if result.success:
+        return {"success": True, "message_id": result.message_id}
+    return {"error": result.error or "kojee-tandem standalone send failed"}
+
+
+def register(ctx):
+    """Plugin entry point — called by the Hermes plugin system
+    (hermes_cli/plugins.py _load_plugin → register(ctx))."""
+    ctx.register_platform(
+        name=PLATFORM_NAME,
+        label="Kojee Tandem",
+        adapter_factory=lambda cfg: KojeeTandemAdapter(cfg),
+        check_fn=check_requirements,
+        validate_config=validate_config,
+        is_connected=is_connected,
+        required_env=["KOJEE_WEBHOOK_SECRET"],
+        install_hint=(
+            "pip install aiohttp; install + pair kojee-mcp (`npm i -g kojee-mcp` "
+            "or set KOJEE_MCP_BIN to its absolute path); set KOJEE_WEBHOOK_SECRET"
+        ),
+        env_enablement_fn=_env_enablement,
+        cron_deliver_env_var="KOJEE_TANDEM_HOME_CHANNEL",
+        standalone_sender_fn=_standalone_send,
+        # Hermes-side per-user authorization (gateway _is_user_authorized):
+        # user_id is the Tandem principal (e.g. "user:daria@cohen.io").
+        allowed_users_env="KOJEE_TANDEM_ALLOWED_USERS",
+        allow_all_env="KOJEE_TANDEM_ALLOW_ALL_USERS",
+        emoji="🤝",
+        pii_safe=False,
+        allow_update_command=False,
+        platform_hint=(
+            "You are in a Kojee Tandem — a shared conversation that can include "
+            "humans and other agents. Messages render as plain text (no markdown "
+            "guarantees). Be concise. The chat id is the tandem id; replies go "
+            "to the whole tandem, not just the sender."
+        ),
+    )