Files
hermes-agent/tools/mcp_tool_sampling.py
Teknium 9cf5278eee fix(mcp-elicit): no form question opens after the elicitation has ended
When the elicitation deadline passed, the server got "cancel" but the form
worker (a to_thread call cancellation cannot stop) went on to ask the next
batch or re-ask. The handler now ends one shared form deadline when its wait
ends, and the form checks it before every prompt.
2026-11-14 11:26:33 -08:00

404 lines
23 KiB
Python

"""MCP client-side handlers for server-initiated requests: sampling
(sampling/createMessage, text and tool-use results) and elicitation."""
import asyncio
import functools
import json
import logging
import threading
import time
from contextvars import Context
from typing import TYPE_CHECKING, Callable, List, Optional
from utils import is_truthy_value
from tools.mcp_tool_common import _MISSING, _exc_str, _safe_numeric, _sanitize_error, exact_mcp_identifier, mcp_field, _core
from tools.mcp_tool_schema import _normalize_mcp_input_schema, strip_schema_annotations
from tools.ansi_strip import strip_tool_metadata_text, strip_unicode_tags, strip_unicode_tags_deep
logger = logging.getLogger("tools.mcp_tool")
def _tool_use_id(block):
"""Tool-use id (marks a tool *result* block) under both SDK spellings — on mcp 2.x a bare
``hasattr(b, "toolUseId")`` is False and would silently drop tool results."""
return mcp_field(block, "tool_use_id", "toolUseId", _MISSING)
def _tool_result_text(block) -> str:
"""Text of a ToolResultContent block ("" when it carries no content)."""
content = getattr(block, "content", None)
if content is None:
return ""
items = content if isinstance(content, list) else [content]
return "\n".join(strip_unicode_tags(item.text) for item in items if hasattr(item, "text"))
def _content_part(block) -> Optional[dict]:
"""One OpenAI content part for a text/image block; None when unsupported."""
if hasattr(block, "text"):
return {"type": "text", "text": strip_unicode_tags(block.text)}
mime = mcp_field(block, "mime_type", "mimeType", _MISSING)
if hasattr(block, "data") and mime is not _MISSING:
return {"type": "image_url", "image_url": {"url": f"data:{strip_unicode_tags(str(mime))};base64,{block.data}"}}
logger.warning("Unsupported sampling content block type: %s (skipped)", type(block).__name__)
return None
def _tool_call_dict(tu, index: int) -> dict:
args = tu.input
# Same conversion as the matching tool result's ``tool_call_id``, so the pair still matches. The
# name and arguments are what the tool was really called with: they stay exact, like the tool's
# schema names and enums, so the history matches the advertised contract.
return {"id": strip_unicode_tags(str(getattr(tu, "id", f"call_{index}"))), "type": "function", "function": {
"name": exact_mcp_identifier(str(tu.name), "sampling tool name"),
"arguments": json.dumps(args, ensure_ascii=False) if isinstance(args, dict) else str(args)}}
def _convert_sampling_message(msg) -> list[dict]:
"""One MCP SamplingMessage -> OpenAI messages: tool results first, then either an assistant
tool_calls message or plain content."""
blocks = msg.content_as_list if hasattr(msg, "content_as_list") else (
msg.content if isinstance(msg.content, list) else [msg.content])
tool_results = [b for b in blocks if _tool_use_id(b) is not _MISSING]
others = [b for b in blocks if _tool_use_id(b) is _MISSING]
tool_uses = [b for b in others if hasattr(b, "name") and hasattr(b, "input")]
content_blocks = [b for b in others if not (hasattr(b, "name") and hasattr(b, "input"))]
role = strip_unicode_tags(str(msg.role))
out = [{"role": "tool", "tool_call_id": strip_unicode_tags(str(_tool_use_id(tr))), "content": _tool_result_text(tr)} for tr in tool_results]
if tool_uses:
msg_dict: dict = {"role": role, "tool_calls": [_tool_call_dict(tu, i) for i, tu in enumerate(tool_uses)]}
text_parts = [strip_unicode_tags(b.text) for b in content_blocks if hasattr(b, "text")]
if text_parts:
msg_dict["content"] = "\n".join(text_parts)
out.append(msg_dict)
elif len(content_blocks) == 1 and hasattr(content_blocks[0], "text"):
out.append({"role": role, "content": strip_unicode_tags(content_blocks[0].text)})
elif content_blocks:
parts = [p for p in map(_content_part, content_blocks) if p is not None]
if parts:
out.append({"role": role, "content": parts})
return out
def _parse_tool_call_arguments(server_name: str, args) -> dict:
"""LLM tool_calls arguments -> dict; malformed JSON / non-dicts become ``{"_raw": ...}``, not dropped."""
if isinstance(args, str):
try:
return json.loads(args)
except (json.JSONDecodeError, ValueError):
logger.warning("MCP server '%s': malformed tool_calls arguments from LLM (wrapping as raw): %.100s",
server_name, args)
return {"_raw": args}
return args if isinstance(args, dict) else {"_raw": str(args)}
class SamplingHandler:
"""``sampling_callback`` for one MCP server (per-instance rate-limit, metrics, tool-loop state).
Runs on the MCP loop; the sync LLM call is offloaded via ``asyncio.to_thread``. Deprecated
upstream (MCP 2026-07-28, SEP-2577): stays functional for handshake-era servers, but do NOT grow
new capability here — modern servers use MRTR, handled by the SDK session layer."""
_STOP_REASON_MAP = {"stop": "endTurn", "length": "maxTokens", "tool_calls": "toolUse"}
_LOG_LEVELS = {"debug": logging.DEBUG, "info": logging.INFO, "warning": logging.WARNING}
def __init__(self, server_name: str, config: dict):
self.server_name = server_name
self.max_rpm = _safe_numeric(config.get("max_rpm", 10), 10, int)
self.timeout = _safe_numeric(config.get("timeout", 30), 30, float)
self.max_tokens_cap = _safe_numeric(config.get("max_tokens_cap", 4096), 4096, int)
self.max_tool_rounds = _safe_numeric(config.get("max_tool_rounds", 5), 5, int, minimum=0)
# Strict MCP servers reject the unknown sampling.tools sub-capability during
# initialization, so it is opt-in per server (default: plain sampling). (#5468)
self.expose_client_tools = is_truthy_value(config.get("expose_client_tools"), default=False)
self.model_override = config.get("model")
self.allowed_models = config.get("allowed_models", [])
self.audit_level = self._LOG_LEVELS.get(str(config.get("log_level", "info")).lower(), logging.INFO)
self._rate_timestamps: list[float] = []
self._tool_loop_count = 0
self.metrics = {"requests": 0, "errors": 0, "tokens_used": 0, "tool_use_count": 0}
def _check_rate_limit(self) -> bool:
"""Sliding-window (60s) limiter; True if the request is allowed."""
now = time.time()
self._rate_timestamps[:] = [t for t in self._rate_timestamps if t > now - 60]
if len(self._rate_timestamps) >= self.max_rpm:
return False
self._rate_timestamps.append(now)
return True
def _resolve_model(self, preferences) -> Optional[str]:
"""Config override > server hint > None (use default)."""
if self.model_override:
return self.model_override
hints = getattr(preferences, "hints", None) or []
return next((hint.name for hint in hints if getattr(hint, "name", None)), None)
def _convert_messages(self, params) -> list[dict]:
"""MCP SamplingMessages -> OpenAI format (per-block duck-typed dispatch)."""
return [m for msg in params.messages for m in _convert_sampling_message(msg)]
@staticmethod
def _error(message: str, code: int = -1):
"""Return ErrorData (MCP spec) or raise as fallback."""
if not _core._MCP_SAMPLING_TYPES:
raise Exception(message)
return _core.ErrorData(code=code, message=message)
def _fail(self, message: str):
"""Count an error and return the ErrorData for it."""
self.metrics["errors"] += 1
return self._error(message)
def _log_response(self, response, suffix: str = "", *args) -> None:
logger.log(self.audit_level, "MCP server '%s' sampling response: model=%s, tokens=%s" + suffix,
self.server_name, response.model, getattr(getattr(response, "usage", None), "total_tokens", "?"), *args)
def _build_tool_use_result(self, choice, response):
"""CreateMessageResultWithTools from a tool_calls response, under ``max_tool_rounds`` (0 disables)."""
self.metrics["tool_use_count"] += 1
self._tool_loop_count += 1
if self.max_tool_rounds == 0 or self._tool_loop_count > self.max_tool_rounds:
self._tool_loop_count = 0
return self._error(
f"Tool loops disabled for server '{self.server_name}' (max_tool_rounds=0)" if self.max_tool_rounds == 0
else f"Tool loop limit exceeded for server '{self.server_name}' (max {self.max_tool_rounds} rounds)")
content_blocks = [_core.ToolUseContent(type="tool_use", id=tc.id, name=tc.function.name,
input=_parse_tool_call_arguments(self.server_name, tc.function.arguments))
for tc in choice.message.tool_calls]
self._log_response(response, ", tool_calls=%d", len(content_blocks))
return _core.CreateMessageResultWithTools(
role="assistant", content=content_blocks, model=response.model, stopReason="toolUse")
def _build_text_result(self, choice, response):
"""CreateMessageResult from a normal text response (resets the tool loop)."""
self._tool_loop_count = 0
self._log_response(response)
return _core.CreateMessageResult(
role="assistant", model=response.model,
content=_core.TextContent(type="text", text=_sanitize_error(choice.message.content or "")),
stopReason=self._STOP_REASON_MAP.get(choice.finish_reason, "endTurn"))
def session_kwargs(self) -> dict:
"""Kwargs to pass to ClientSession for sampling support."""
sampling_capabilities = (
_core.SamplingCapability(tools=_core.SamplingToolsCapability())
if self.expose_client_tools
else _core.SamplingCapability()
)
return {"sampling_callback": self,
"sampling_capabilities": sampling_capabilities}
def _admit(self, params):
"""Rate-limit + allowed_models gate. Returns ``(resolved_model, None)`` or ``(None, ErrorData)``."""
if not self._check_rate_limit():
logger.warning("MCP server '%s' sampling rate limit exceeded (%d/min)", self.server_name, self.max_rpm)
return None, self._fail(
f"Sampling rate limit exceeded for server '{self.server_name}' ({self.max_rpm} requests/minute)")
resolved_model = self._resolve_model(mcp_field(params, "model_preferences", "modelPreferences")) or ""
if self.allowed_models and resolved_model and resolved_model not in self.allowed_models:
logger.warning("MCP server '%s' requested model '%s' not in allowed_models",
self.server_name, resolved_model)
return None, self._fail(f"Model '{resolved_model}' not allowed for server "
f"'{self.server_name}'. Allowed: {', '.join(self.allowed_models)}")
return resolved_model, None
def _build_llm_call(self, params, resolved_model: str) -> Callable[[], object]:
"""Sampling params -> zero-arg sync ``call_llm`` thunk (run off-loop); server tools are forwarded."""
from agent.auxiliary_client import call_llm
messages = self._convert_messages(params)
system_prompt = mcp_field(params, "system_prompt", "systemPrompt")
if system_prompt:
messages.insert(0, {"role": "system", "content": strip_unicode_tags(str(system_prompt))})
max_tokens = min(mcp_field(params, "max_tokens", "maxTokens", self.max_tokens_cap), self.max_tokens_cap)
server_tools = getattr(params, "tools", None)
tools = [{"type": "function", "function": {
"name": exact_mcp_identifier(str(getattr(t, "name", "")), "sampling tool name"), # tool_calls echo it
"description": strip_tool_metadata_text(str(getattr(t, "description", "") or "")),
"parameters": strip_schema_annotations(
_normalize_mcp_input_schema(mcp_field(t, "input_schema", "inputSchema")), getattr(t, "name", ""))}}
for t in server_tools] if server_tools else None
logger.log(self.audit_level, "MCP server '%s' sampling request: model=%s, max_tokens=%d, messages=%d",
self.server_name, resolved_model, max_tokens, len(messages))
return lambda: call_llm(task="mcp", model=resolved_model or None, messages=messages, max_tokens=max_tokens,
temperature=getattr(params, "temperature", None), tools=tools, timeout=self.timeout)
async def __call__(self, context, params):
"""SDK ``SamplingFnT``: CreateMessageResult, CreateMessageResultWithTools, or ErrorData."""
resolved_model, err = self._admit(params)
if err is not None:
return err
sync_call = self._build_llm_call(params, resolved_model) # outside the try: its errors propagate, not _fail
try:
response = await asyncio.wait_for(asyncio.to_thread(sync_call), timeout=self.timeout)
except TimeoutError:
return self._fail(f"Sampling LLM call timed out after {self.timeout}s for server '{self.server_name}'")
except Exception as exc:
return self._fail(f"Sampling LLM call failed: {_sanitize_error(_exc_str(exc))}")
# Empty choices happen on content filtering / provider errors.
if not getattr(response, "choices", None):
return self._fail(f"LLM returned empty response (no choices) for server '{self.server_name}'")
choice = response.choices[0]
self.metrics["requests"] += 1
total_tokens = getattr(getattr(response, "usage", None), "total_tokens", 0)
self.metrics["tokens_used"] += total_tokens if isinstance(total_tokens, int) else 0
if choice.finish_reason == "tool_calls" and getattr(choice.message, "tool_calls", None):
return self._build_tool_use_result(choice, response)
return self._build_text_result(choice, response)
def _format_elicitation_schema_summary(schema: dict, server_name: str) -> str:
"""Flat-object requested_schema -> readable field list so the user knows what they're approving."""
props = schema.get("properties") if isinstance(schema, dict) else None
if not isinstance(props, dict) or not props:
return f"Approval requested by MCP server '{server_name}'."
lines = [f"Fields requested by MCP server '{server_name}':"]
for field_name, field_spec in props.items():
spec = field_spec if isinstance(field_spec, dict) else {}
field_type, field_desc = str(spec.get("type", "") or ""), str(spec.get("description", "") or "")
lines.append(f" - {strip_unicode_tags(str(field_name))}"
+ (f" ({strip_unicode_tags(field_type)})" if field_type else "")
+ (f": {strip_unicode_tags(field_desc)}" if field_desc else ""))
return "\n".join(lines)
def _accepted_consent_content(schema: dict) -> Optional[dict]:
"""Translate a binary approval into a safe, schema-valid consent form.
Hermes' approval surfaces can answer yes/no, not collect arbitrary form
fields. A required single boolean is unambiguous. A required single
enum is only unambiguous when it offers the conventional one-shot
``allow_once`` choice; choosing a session-wide grant would silently
broaden the user's approval. Every other form must be declined rather
than submitted with the historical (and invalid) empty object.
"""
if not isinstance(schema, dict):
return None
props = schema.get("properties")
required = schema.get("required")
# No required fields: the empty object already satisfies the form.
if required in (None, []):
return {}
if not isinstance(props, dict) or not isinstance(required, list) or len(required) != 1:
return None
field = required[0]
spec = props.get(field)
if not isinstance(field, str) or not isinstance(spec, dict):
return None
if spec.get("type") == "boolean":
return {field: True}
choices = spec.get("enum")
if not isinstance(choices, list):
choices = [choice.get("const") for choice in spec.get("oneOf", [])
if isinstance(choice, dict) and "const" in choice]
return {field: "allow_once"} if "allow_once" in choices else None
class ElicitationHandler:
"""``elicitation_callback`` for one MCP server. Form-mode asks the user for the requested fields on
the agent's own surface (CLI, TUI, Desktop, messaging); URL-mode is declined. Fail-closed: any
timeout, exception or unexpected state returns decline/cancel, never a silent accept."""
# asyncio-side safety net over the approval's own input() timeout so the MCP loop never blocks
# indefinitely if the inner timeout is bypassed.
_OUTER_TIMEOUT_GRACE_SECONDS = 5
# answer -> (ElicitResult action, metric); anything else declines.
_ANSWER_RESULTS = {"accept": ("accept", "accepted"), "cancel": ("cancel", "errors")}
def __init__(self, server_name: str, config: dict,
call_context: Callable[[], Optional[Context]] = lambda: None,
call_callbacks: Callable[[], tuple] = lambda: ()):
self.server_name = server_name
# 5 min mirrors the gateway approval default so async surfaces (Telegram, Slack) can respond.
self.timeout = _safe_numeric(config.get("timeout", 300), 300, float)
# Returns the owning MCPServerTask's contextvars snapshot for the in-flight tool call (None
# between calls). A thunk, not the task: mcp_tool_server_run imports this module, so
# MCPServerTask cannot be named here.
self._call_context = call_context
# Same-call ``(setter, callback)`` pairs for the turn thread's prompt callbacks
# (approval/sudo/vault) — ``asyncio.to_thread`` does not carry ``threading.local``.
self._call_callbacks = call_callbacks
self.metrics = {"requests": 0, "accepted": 0, "declined": 0, "errors": 0}
def session_kwargs(self) -> dict:
"""Kwargs to pass to ClientSession for elicitation support."""
return {"elicitation_callback": self}
def _result(self, action: str, metric: str, content: Optional[dict] = None):
"""Count *metric* and return an ``ElicitResult``."""
self.metrics[metric] += 1
return _core.ElicitResult(action=action, **({"content": content or {}} if action == "accept" else {}))
def _on_turn_thread(self, fn: Callable[[], object]) -> Callable[[], object]:
"""*fn* replaying the agent's contextvars snapshot when the owning task captured one (the
recv-loop task does NOT inherit them; gateway-platform detection and the bound form asker need
them) and installing the captured per-thread prompt callbacks for the duration (the executor
thread has none of its own). ``Context.run`` runs a context once, so it is copied per call."""
# Outside a tool call (resources/read, prompts/get) nothing was captured: an empty slot.
captured, installs = self._call_context(), self._call_callbacks() or ()
def _invoke():
for setter, cb in installs:
setter(cb)
try: # executor threads are reused: never leak an install past this call
return fn() if captured is None else captured.copy().run(fn)
finally:
for setter, _cb in installs:
setter(None)
return _invoke
def _ask(self, message: str, schema: dict, ended: Callable[[], bool] = lambda: False):
"""Collect the answer on the agent's own surface: the form through the turn's clarify callback
when one is bound and a user can answer, else the yes/no approval prompt (headless sessions
decline there) with the consent content that answer can honestly fill."""
from tools import approval_context as _ctx
from tools.approval_prompt import request_elicitation_consent
from tools.mcp_elicitation_form import FormOutcome, ask_form, current_form_asker
asker = current_form_asker()
if asker is not None and not _ctx._no_user_can_answer():
return ask_form(asker, self.server_name, message, schema, ended)
answer = request_elicitation_consent(message, _format_elicitation_schema_summary(schema, self.server_name),
timeout_seconds=int(self.timeout),
surface=f"mcp-elicitation/{self.server_name}")
if answer != "accept":
return FormOutcome("cancel" if answer == "cancel" else "decline")
content = _accepted_consent_content(schema)
if content is None:
logger.warning("MCP server '%s' elicitation requires form input this surface cannot collect; "
"declining", self.server_name)
return FormOutcome("decline")
return FormOutcome("accept", content)
async def __call__(self, context, params):
"""SDK elicitation callback (``ElicitationFnT``). Returns ElicitResult or ErrorData."""
self.metrics["requests"] += 1
if getattr(params, "mode", "form") == "url": # OAuth/payment: needs a browser + elicitation/complete; unsupported
logger.info("MCP server '%s' requested URL-mode elicitation; declining "
"(URL-mode elicitation not implemented)", self.server_name)
return self._result("decline", "declined")
message = strip_unicode_tags(str(getattr(params, "message", "") or f"MCP server '{self.server_name}' is requesting your approval"))
# ``requestedSchema`` on mcp 1.x, ``requested_schema`` on 2.0 (aliases don't apply to attribute
# access) — read both or the user approves without seeing the fields.
schema = getattr(params, "requestedSchema", None) or getattr(params, "requested_schema", None) or {}
logger.info("MCP server '%s' elicitation request: %s", self.server_name, _sanitize_error(message)[:200])
# One deadline for the whole form: once this wait ends the worker (which cancellation cannot
# stop) opens no further batch or re-ask, so the user is not asked after the server has its answer.
ended = threading.Event()
ask = self._on_turn_thread(functools.partial(self._ask, message, schema, ended.is_set))
try: # off-thread: inline, the sync prompt would freeze the MCP loop and every RPC on it
outcome = await asyncio.wait_for(
asyncio.to_thread(ask), timeout=self.timeout + self._OUTER_TIMEOUT_GRACE_SECONDS)
except TimeoutError:
logger.warning("MCP server '%s' elicitation timed out after %ds", self.server_name, int(self.timeout))
return self._result("cancel", "errors")
except Exception as exc:
logger.error("MCP server '%s' elicitation failed: %s", self.server_name, exc, exc_info=True)
return self._result("decline", "errors")
finally:
ended.set()
action, metric = self._ANSWER_RESULTS.get(outcome.action, ("decline", "declined"))
return self._result(action, metric, outcome.content)