kojee-mcp 0.5.13 → 0.5.14

package/dist/plugins/hermes/kojee_tandem_core.py

@@ -0,0 +1,344 @@
+"""Pure logic for the ``kojee-tandem`` Hermes platform adapter.
+
+This module has ZERO Hermes imports (stdlib only) so the mapping, signature
+verification, dedupe, and outbound-payload contracts are unit-testable on any
+box — including one where neither Hermes nor aiohttp is installed.
+``adapter.py`` (the Hermes-facing shim) imports from here.
+
+Wire contracts pinned against:
+  - TandemEvent: kojee-mcp-server src/types/tandem.ts (0.5.3)
+  - Webhook signature: src/tandem/webhook-sink.ts computeWebhookSignature()
+    (hex SHA-256 HMAC of the RAW body bytes) + the emission knobs in
+    src/tandem/webhook-config.ts (default header X-Kojee-Signature with a bare
+    hex digest; "github" preset = X-Hub-Signature-256 with "sha256=" prefix).
+  - Session id derivation: src/gateway-client.ts deriveSessionId()
+    (sha256(token + "proxy") hex, first 16 chars).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from collections import OrderedDict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+# ── Signature verification ──────────────────────────────────────────────────
+
+# Default kojee-mcp emission (0.5.2 wire contract): bare hex digest.
+KOJEE_SIGNATURE_HEADER = "X-Kojee-Signature"
+# The "github" preset (KOJEE_WEBHOOK_SIGNATURE_FORMAT=github): sha256=<hex>.
+GITHUB_SIGNATURE_HEADER = "X-Hub-Signature-256"
+GITHUB_SIGNATURE_PREFIX = "sha256="
+# Delivery id header the sink sets on every POST (event id, receiver dedupe key).
+DELIVERY_ID_HEADER = "X-Kojee-Delivery"
+
+
+def compute_signature(secret: str, raw_body: bytes) -> str:
+    """Hex SHA-256 HMAC of the raw request-body bytes (mirror of
+    webhook-sink.ts computeWebhookSignature — same bytes, same key)."""
+    return hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+
+
+def _header_lookup(headers: Mapping[str, str], name: str) -> Optional[str]:
+    """Case-insensitive header fetch from a plain mapping (aiohttp's CIMultiDict
+    is already case-insensitive, but tests use plain dicts)."""
+    getter = getattr(headers, "get", None)
+    if getter is not None:
+        direct = getter(name)
+        if direct is not None:
+            return direct
+    lowered = name.lower()
+    for key in headers:
+        if key.lower() == lowered:
+            return headers[key]
+    return None
+
+
+def verify_signature(headers: Mapping[str, str], raw_body: bytes, secret: str) -> bool:
+    """True when the request carries a valid HMAC for ``raw_body``.
+
+    Accepts EITHER emission the kojee-mcp daemon can be configured for —
+    the default ``X-Kojee-Signature: <hex>`` or the github preset
+    ``X-Hub-Signature-256: sha256=<hex>`` — so a header/prefix mismatch
+    between the daemon env and the adapter config is not a bug class here.
+    Fails closed: no secret or no recognized header ⇒ False.
+    """
+    if not secret:
+        return False
+    expected = compute_signature(secret, raw_body)
+
+    bare = _header_lookup(headers, KOJEE_SIGNATURE_HEADER)
+    if bare is not None and hmac.compare_digest(bare.strip(), expected):
+        return True
+
+    github = _header_lookup(headers, GITHUB_SIGNATURE_HEADER)
+    if github is not None:
+        value = github.strip()
+        if value.startswith(GITHUB_SIGNATURE_PREFIX):
+            value = value[len(GITHUB_SIGNATURE_PREFIX):]
+        if hmac.compare_digest(value, expected):
+            return True
+
+    return False
+
+
+# ── Inbound: TandemEvent → normalized message ───────────────────────────────
+
+@dataclass
+class NormalizedTandemMessage:
+    """A TandemEvent reduced to what a Hermes MessageEvent needs."""
+
+    chat_id: str            # tandem_id — the per-tandem chat id
+    message_id: str         # cursor (stringified) — stable per-tandem ordering
+    event_id: str           # ULID — globally unique, the dedupe key
+    text: str               # content.body
+    sender_id: str          # from.principal (falls back to member_id)
+    sender_name: str        # from.displayname (falls back to principal)
+    sender_session_id: Optional[str]  # from.session_id (self-echo filter)
+    reply_to: Optional[str]
+    kind: str
+    severity: Optional[str]
+
+
+def normalize_event(event: Mapping[str, Any]) -> Optional[NormalizedTandemMessage]:
+    """Map a TandemEvent JSON body to a normalized message, or None when the
+    event is not an injectable chat message (state_change, empty body,
+    missing tandem_id). The adapter ACKs-and-ignores None — a non-message
+    event must never 4xx (the sink would classify it permanent and drop it,
+    or retry-burn on 5xx)."""
+    if not isinstance(event, Mapping):
+        return None
+    if event.get("type") != "message":
+        return None
+    tandem_id = event.get("tandem_id")
+    if not tandem_id or not isinstance(tandem_id, str):
+        return None
+    content = event.get("content") or {}
+    body = content.get("body") if isinstance(content, Mapping) else None
+    if not body or not isinstance(body, str):
+        return None
+
+    sender = event.get("from") or {}
+    if not isinstance(sender, Mapping):
+        sender = {}
+    principal = sender.get("principal") or sender.get("member_id") or "unknown"
+    displayname = sender.get("displayname") or principal
+
+    cursor = event.get("cursor")
+    event_id = str(event.get("id") or "")
+    # cursor is the per-tandem message id (the directive's mapping); fall back
+    # to the ULID when a wire frame omits it so message_id is never empty.
+    message_id = str(cursor) if cursor is not None else event_id
+
+    reply_to = event.get("reply_to")
+    severity = event.get("severity")
+
+    return NormalizedTandemMessage(
+        chat_id=tandem_id,
+        message_id=message_id,
+        event_id=event_id or message_id,
+        text=body,
+        sender_id=str(principal),
+        sender_name=str(displayname),
+        sender_session_id=(
+            str(sender["session_id"]) if sender.get("session_id") else None
+        ),
+        reply_to=str(reply_to) if reply_to else None,
+        kind=str(event.get("kind") or "message"),
+        severity=str(severity) if severity else None,
+    )
+
+
+# ── Dedupe (the receiver side of the sink's at-least-once contract) ─────────
+
+class EventDeduper:
+    """Bounded insertion-ordered set of seen event ids.
+
+    The webhook sink is at-least-once: after a daemon restart the
+    resubscribe-replay REDELIVERS recent events, and retries can double-send.
+    The receiver contract (recipe.ts) says: dedupe by event id / cursor.
+    """
+
+    def __init__(self, maxlen: int = 4096):
+        self._maxlen = max(1, maxlen)
+        self._seen: "OrderedDict[str, None]" = OrderedDict()
+
+    def seen_before(self, event_id: str) -> bool:
+        """Mark ``event_id`` seen; True when it had already been seen."""
+        if event_id in self._seen:
+            self._seen.move_to_end(event_id)
+            return True
+        self._seen[event_id] = None
+        while len(self._seen) > self._maxlen:
+            self._seen.popitem(last=False)
+        return False
+
+
+# ── Filters ─────────────────────────────────────────────────────────────────
+
+def parse_allowlist(raw: Optional[str]) -> frozenset:
+    """Comma-separated tandem ids → set. Empty/None ⇒ empty set = allow all."""
+    if not raw:
+        return frozenset()
+    return frozenset(part.strip() for part in raw.split(",") if part.strip())
+
+
+def tandem_allowed(tandem_id: str, allowlist: frozenset) -> bool:
+    """Empty allowlist ⇒ every tandem is allowed (Hermes's per-user
+    authorization still applies downstream via KOJEE_TANDEM_ALLOWED_USERS)."""
+    return not allowlist or tandem_id in allowlist
+
+
+def is_self_event(
+    msg: NormalizedTandemMessage,
+    self_session_id: Optional[str],
+    self_principal: Optional[str],
+) -> bool:
+    """Self-echo filter (reply-loop prevention, ADDING_A_PLATFORM checklist).
+
+    The daemon and the send helper share ONE deterministic session id
+    (sha256(token+"proxy")[:16] — gateway-client.ts deriveSessionId), so a
+    fan-out echo of our own tandem_send carries from.session_id == ours.
+    The principal check is the operator-config fallback for wire frames
+    that omit session_id.
+    """
+    if self_session_id and msg.sender_session_id == self_session_id:
+        return True
+    if self_principal and msg.sender_id == self_principal:
+        return True
+    return False
+
+
+def derive_session_id(token: str) -> str:
+    """Mirror of GatewayClient.deriveSessionId (src/gateway-client.ts):
+    session_id = sha256(token + "proxy") hex, first 16 chars."""
+    return hashlib.sha256((token + "proxy").encode("utf-8")).hexdigest()[:16]
+
+
+def load_self_session_id(kojee_dir: Path) -> Optional[str]:
+    """Best-effort: read ~/.kojee/config.json (paired mode) and derive the
+    daemon/helper session id for the self-echo filter. None when unpaired or
+    unreadable — the adapter then relies on KOJEE_TANDEM_SELF_PRINCIPAL."""
+    try:
+        raw = (kojee_dir / "config.json").read_text(encoding="utf-8")
+        token = json.loads(raw).get("token")
+        if token and isinstance(token, str):
+            return derive_session_id(token)
+    except (OSError, ValueError):
+        pass
+    return None
+
+
+# ── Outbound: send → `kojee-mcp send` CLI contract ──────────────────────────
+#
+# T10: outbound moved from kojee_send.mjs (tsx + dynamic source imports →
+# REQUIRED a kojee-mcp source checkout) to the shipped `kojee-mcp send`
+# sub-command (0.5.4+). This kills the "needs a checkout" requirement — the
+# adapter now needs only a paired ~/.kojee + the kojee-mcp binary on PATH.
+#
+# CLI contract (src/cli.ts + src/tandem/send.ts):
+#   kojee-mcp send <tandem_id> --body <text> [--reply-to <id>] [--kind <kind>]
+#   stdout: one JSON envelope.
+#     success: {ok:true,  tandem_id, message_id, cursor, text}  (exit 0)
+#     failure: {ok:false, error:<typed code>, message:<human text>}  (exit 1)
+
+KOJEE_MCP_BIN_ENV = "KOJEE_MCP_BIN"
+# PATH fallback when KOJEE_MCP_BIN is unset (fold B).
+DEFAULT_KOJEE_MCP_BIN = "kojee-mcp"
+
+
+def resolve_kojee_mcp_bin(env: Mapping[str, str]) -> str:
+    """The kojee-mcp binary the outbound send shells.
+
+    Fold B: the plugin runs inside the gateway process, where the login-shell
+    PATH may not apply — so the installer writes an ABSOLUTE path into
+    ``KOJEE_MCP_BIN``. When that env is unset/empty we fall back to the bare
+    ``kojee-mcp`` name and rely on PATH resolution.
+    """
+    # TODO(hermes-installer): wizard writes KOJEE_MCP_BIN at install
+    # (src/wizard/installers/hermes.ts) — until then this fallback carries it.
+    return env.get(KOJEE_MCP_BIN_ENV) or DEFAULT_KOJEE_MCP_BIN
+
+
+def build_send_command(
+    bin_path: str,
+    tandem_id: str,
+    body: str,
+    reply_to: Optional[str] = None,
+    kind: Optional[str] = None,
+) -> list:
+    """Argv for `kojee-mcp send <tandem_id> --body <text> [--reply-to] [--kind]`.
+
+    ``bin_path`` is the caller-resolved kojee-mcp binary (see
+    resolve_kojee_mcp_bin). body/reply_to/kind ride argv directly (asyncio's
+    exec passes argv to the kernel — no shell, so no quoting hazard).
+    reply_to/kind are OMITTED when absent, never passed empty.
+    """
+    argv = [bin_path, "send", tandem_id, "--body", body]
+    if reply_to:
+        argv += ["--reply-to", reply_to]
+    if kind:
+        argv += ["--kind", kind]
+    return argv
+
+
+def parse_send_envelope(stdout: str) -> dict:
+    """Parse the `kojee-mcp send` JSON envelope from stdout.
+
+    Returns a normalized dict::
+
+        {"ok": bool,
+         "message_id": Optional[str],
+         "cursor": Optional[int],
+         "error": Optional[str],        # human-readable failure text
+         "error_code": Optional[str]}   # the typed SendErrorCode
+
+    Tolerates noise lines before the envelope (node warnings) by scanning for
+    the LAST parseable JSON object carrying ``ok``. No envelope ⇒ ok=False with
+    the raw tail as the error — a CLI crash must surface, not masquerade as a
+    delivered send.
+    """
+    envelope = None
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            candidate = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(candidate, dict) and "ok" in candidate:
+            envelope = candidate
+    if envelope is None:
+        tail = stdout.strip()[-300:] if stdout.strip() else "(no output)"
+        return {
+            "ok": False,
+            "message_id": None,
+            "cursor": None,
+            "error": f"kojee-mcp send produced no envelope: {tail}",
+            "error_code": None,
+        }
+    if envelope.get("ok"):
+        raw_cursor = envelope.get("cursor")
+        return {
+            "ok": True,
+            "message_id": (
+                str(envelope["message_id"]) if envelope.get("message_id") else None
+            ),
+            "cursor": raw_cursor if isinstance(raw_cursor, int) else None,
+            "error": None,
+            "error_code": None,
+        }
+    # Failure envelope: {ok:false, error:<typed code>, message:<human text>}.
+    code = str(envelope["error"]) if envelope.get("error") else None
+    message = str(envelope["message"]) if envelope.get("message") else None
+    return {
+        "ok": False,
+        "message_id": None,
+        "cursor": None,
+        "error": message or code or "kojee-mcp send failed",
+        "error_code": code,
+    }

package/dist/plugins/hermes/plugin.yaml

@@ -0,0 +1,58 @@
+name: kojee-tandem
+label: Kojee Tandem
+kind: platform
+version: 0.1.0
+description: >
+  Kojee Tandem gateway adapter for Hermes Agent (v1, sidecar architecture).
+  Makes Tandem — Kojee's shared human+agent conversations — a first-class
+  Hermes channel: the kojee-mcp daemon (DPoP auth, SSE event stream) delivers
+  Tandem messages to this adapter's loopback webhook listener, and replies go
+  out through the shipped `kojee-mcp send` CLI via tandem_send. Needs a paired
+  ~/.kojee and the kojee-mcp binary on the box (no source checkout required).
+author: Kojee
+requires_env:
+  - name: KOJEE_WEBHOOK_SECRET
+    description: "HMAC secret shared with the kojee-mcp daemon's webhook sink (the adapter rejects unsigned events)"
+    prompt: "Webhook HMAC secret"
+    password: true
+optional_env:
+  - name: KOJEE_MCP_BIN
+    description: "Absolute path to the kojee-mcp binary the outbound `send` shells (default: `kojee-mcp` on PATH). Set when the binary is not on the gateway process PATH."
+    prompt: "kojee-mcp binary path (optional)"
+    password: false
+  - name: KOJEE_TANDEM_LISTEN_HOST
+    description: "Webhook listener bind host (default 127.0.0.1 — keep it loopback)"
+    prompt: "Listen host"
+    password: false
+  - name: KOJEE_TANDEM_LISTEN_PORT
+    description: "Webhook listener port (default 8645); the daemon's KOJEE_WEBHOOK_URL must point here"
+    prompt: "Listen port"
+    password: false
+  - name: KOJEE_TANDEM_LISTEN_PATH
+    description: "Webhook listener path (default /kojee-tandem)"
+    prompt: "Listen path"
+    password: false
+  - name: KOJEE_TANDEM_ALLOWLIST
+    description: "Comma-separated tandem ids allowed to wake the agent (empty = all tandems)"
+    prompt: "Tandem allowlist (comma-separated, or empty)"
+    password: false
+  - name: KOJEE_TANDEM_ALLOWED_USERS
+    description: "Comma-separated Tandem principals allowed to talk to the bot (e.g. user:daria@cohen.io)"
+    prompt: "Allowed principals (comma-separated)"
+    password: false
+  - name: KOJEE_TANDEM_ALLOW_ALL_USERS
+    description: "Allow every tandem member to talk to the bot (1/true/yes)"
+    prompt: "Allow all users? (true/false)"
+    password: false
+  - name: KOJEE_TANDEM_SELF_PRINCIPAL
+    description: "Extra self-echo filter for wire frames without sender session_id. WARNING: setting this to the shared account principal silences EVERYONE sharing it, including your owner (the principal is shared by the human owner and all sibling agents) — defaults are safe, leave unset"
+    prompt: "Self principal (optional)"
+    password: false
+  - name: KOJEE_TANDEM_HOME_CHANNEL
+    description: "Default tandem id for cron / notification delivery (deliver=kojee-tandem)"
+    prompt: "Home tandem id (optional)"
+    password: false
+  - name: KOJEE_DIR
+    description: "Kojee state dir holding config.json + keypair.json (default ~/.kojee)"
+    prompt: "Kojee dir (optional)"
+    password: false