| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124 |
- """MCP Events deliveries on routes that ``tools/mcp_tool_events.py`` created (the route carries an
- ``mcp_event`` block). The endpoint-verification echo and the ``terminated`` / ``gap`` control
- envelopes are answered here without an agent run; an event occurrence continues through the normal
- route pipeline, keyed for idempotency by its ``eventId``. Signatures (Standard Webhooks, ``whsec_``)
- are already verified by the adapter before any of this runs."""
- import asyncio
- import json
- import logging
- from typing import Any, Optional
- logger = logging.getLogger(__name__)
- _MAX_CHALLENGE_CHARS = 512
- _MAX_NOTICE_DETAIL_CHARS = 200
- _MAX_EVENT_DATA_CHARS = 32_000
- def _json(body: dict, status: int = 200):
- from aiohttp import web # lazy: the adapter is only constructed when aiohttp is installed
- return web.json_response(body, status=status)
- def _mcp_event(route_config: dict) -> Optional[dict]:
- event = route_config.get("mcp_event")
- return event if isinstance(event, dict) else None
- def render_mcp_event_prompt(adapter, route_config: dict, payload: Any, event_type: str,
- route_name: str) -> Optional[str]:
- """The prompt for an occurrence on an MCP event route whose template uses ``{data}``; None otherwise.
- ``{data}`` takes the whole payload (up to ``_MAX_EVENT_DATA_CHARS``, with a note when cut) instead of
- the 2,000-character cap other placeholders get, and the JSON goes in after the rest of the template
- renders, so text inside the payload is never read as a placeholder."""
- if _mcp_event(route_config) is None or not isinstance(payload, dict):
- return None
- template = route_config.get("prompt")
- if not isinstance(template, str) or "{data}" not in template:
- return None
- data = json.dumps(payload.get("data"), indent=2, ensure_ascii=False)
- if len(data) > _MAX_EVENT_DATA_CHARS:
- data = (f"{data[:_MAX_EVENT_DATA_CHARS]}\n[truncated: the first {_MAX_EVENT_DATA_CHARS:,} of "
- f"{len(data):,} characters]")
- return data.join(adapter._render_prompt(part, payload, event_type, route_name) if part else ""
- for part in template.split("{data}"))
- def mcp_event_delivery_id(route_config: dict, payload: Any) -> Optional[str]:
- """``eventId`` is the sketch's dedup key (stable across retries and redeliveries), unlike the
- per-attempt ``webhook-id``."""
- if _mcp_event(route_config) is None or not isinstance(payload, dict):
- return None
- event_id = payload.get("eventId")
- return f"mcp-event:{event_id}" if isinstance(event_id, str) and event_id else None
- def _store_cursor(route_name: str, cursor: str) -> None:
- # Subscription state lives beside the route, never in it: an admitted run's reply is checked against
- # a digest of the route config, so a cursor written there would strand every run still in flight.
- from tools.mcp_tool_events import store_cursor
- store_cursor(route_name, cursor)
- def _remove_route(route_name: str) -> None:
- from hermes_cli.webhook import _mutate_subscriptions
- from tools.mcp_tool_events import drop_state
- _mutate_subscriptions(lambda subscriptions: subscriptions.pop(route_name, None))
- drop_state(route_name)
- async def _verification(adapter, route_name: str, route_config: dict, payload: dict, profile) -> Any:
- challenge = payload.get("challenge")
- if not isinstance(challenge, str) or not challenge or len(challenge) > _MAX_CHALLENGE_CHARS:
- return _json({"error": "Invalid verification challenge"}, status=400)
- logger.info("[webhook] MCP event route %s answered the server's verification challenge", route_name)
- return _json({"challenge": challenge})
- async def _terminated(adapter, route_name: str, route_config: dict, payload: dict, profile) -> Any:
- event = _mcp_event(route_config) or {}
- error = payload.get("error") if isinstance(payload.get("error"), dict) else {}
- await asyncio.to_thread(_remove_route, route_name)
- logger.warning("[webhook] MCP server '%s' ended event subscription %s (%s): %s", event.get("server"),
- route_name, event.get("name"), error)
- if route_config.get("deliver", "log") != "log":
- detail = str(error.get("message") or "no reason given")[:_MAX_NOTICE_DETAIL_CHARS]
- notice = (f"MCP server '{event.get('server')}' ended the subscription to '{event.get('name')}': "
- f"{detail} (code {error.get('code')}). Subscribe again to keep receiving these events.")
- await adapter._handle_deliver_only(notice, payload, route_config, route_name, "terminated",
- f"mcp-terminated:{route_name}", profile)
- return _json({"status": "terminated"})
- async def _gap(adapter, route_name: str, route_config: dict, payload: dict, profile) -> Any:
- cursor = payload.get("cursor")
- if isinstance(cursor, str) and cursor:
- await asyncio.to_thread(_store_cursor, route_name, cursor)
- logger.warning("[webhook] MCP event route %s: the server skipped events (gap); resuming from a fresh cursor",
- route_name)
- return _json({"status": "gap"})
- _CONTROL_HANDLERS = {"verification": _verification, "terminated": _terminated, "gap": _gap}
- async def handle_mcp_event_control(adapter, route_name: str, route_config: dict, payload: Any,
- profile) -> Any:
- """The response for a control envelope on an MCP event route; None lets the delivery continue
- as an event occurrence (whose replay cursor, when the server sends one, is remembered first)."""
- if _mcp_event(route_config) is None or not isinstance(payload, dict):
- return None
- kind = payload.get("type")
- handler = _CONTROL_HANDLERS.get(kind) if isinstance(kind, str) else None
- if handler is not None:
- return await handler(adapter, route_name, route_config, payload, profile)
- if "type" in payload:
- # The sketch: a body with a top-level ``type`` is a control envelope. Acknowledge one this client
- # does not know (a later revision's) so the server stops retrying it; it never starts a run.
- logger.info("[webhook] MCP event route %s: ignoring a control envelope of unknown type %r", route_name, kind)
- return _json({"status": "ignored", "type": kind if isinstance(kind, str) else None})
- cursor = payload.get("cursor")
- if isinstance(cursor, str) and cursor:
- await asyncio.to_thread(_store_cursor, route_name, cursor)
- return None
|