Skip to content

The agent that grows with you

fix(webhook): acknowledge unknown MCP event control envelopes

emozillab6a14c3b1846
diff --git a/gateway/platforms/webhook_mcp_events.py b/gateway/platforms/webhook_mcp_events.py
index c723a109187..0c112834c11 100644
--- a/gateway/platforms/webhook_mcp_events.py
+++ b/gateway/platforms/webhook_mcp_events.py
@@ -88,9 +88,15 @@ async def handle_mcp_event_control(adapter, route_name: str, route_config: dict,
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
- handler = _CONTROL_HANDLERS.get(payload.get("type"))
+ 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)
diff --git a/tests/gateway/test_webhook_mcp_events.py b/tests/gateway/test_webhook_mcp_events.py
index 72585b12dd9..013a6679a6a 100644
--- a/tests/gateway/test_webhook_mcp_events.py
+++ b/tests/gateway/test_webhook_mcp_events.py
@@ -134,3 +134,16 @@ async def test_subscription_state_changes_do_not_strand_an_admitted_run(home):
assert retry.status == 200 and (await retry.json())["status"] == "duplicate"
assert _routes(home)[ROUTE] == routes[ROUTE]
+
+async def test_an_unknown_control_envelope_is_acknowledged_without_a_run(home):
+ # The sketch: any body with a top-level ``type`` is a control envelope, including types a later
+ # revision adds. None of them may start an agent run.
+ adapter = _adapter()
+ async with TestClient(TestServer(_app(adapter))) as cli:
+ resp = await _post(cli, {"type": "paused", "reason": "maintenance"})
+ assert resp.status == 200 and (await resp.json())["status"] == "ignored"
+ odd = await _post(cli, {"type": {"not": "a string"}})
+ assert odd.status == 200
+ adapter.handle_message.assert_not_called()
+