tool_progress_relay.py 3.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768
  1. """Live progress from inside a running tool call (MCP ``notifications/progress``) onto the agent's
  2. ``tool_progress_callback`` as ``tool.progress`` events.
  3. The executor binds a relay for each dispatched call (``bound_tool_progress``); a tool reads it on its
  4. own thread with ``current_tool_progress()`` and may invoke the result from any thread (the MCP client
  5. fires it on the MCP event loop). Emission is throttled per call so a chatty server cannot flood the
  6. UI; the first update and the one reaching ``total`` always pass.
  7. """
  8. from __future__ import annotations
  9. import contextlib
  10. import contextvars
  11. import logging
  12. import threading
  13. import time
  14. from typing import Callable, Iterator, Optional
  15. logger = logging.getLogger(__name__)
  16. TOOL_PROGRESS_EVENT = "tool.progress"
  17. _MIN_INTERVAL_S = 0.5
  18. ProgressReporter = Callable[[float, Optional[float], Optional[str]], None]
  19. _current: contextvars.ContextVar[Optional[ProgressReporter]] = contextvars.ContextVar("tool_progress_reporter", default=None)
  20. def _reporter(callback, tool_name: str, tool_call_id: str) -> ProgressReporter:
  21. lock = threading.Lock()
  22. last = [0.0]
  23. def report(progress: float, total: Optional[float] = None, message: Optional[str] = None) -> None:
  24. done = total is not None and total > 0 and progress >= total
  25. now = time.monotonic()
  26. with lock:
  27. if last[0] and not done and now - last[0] < _MIN_INTERVAL_S:
  28. return
  29. last[0] = now
  30. percent = round(min(max(progress / total, 0.0), 1.0) * 100) if total else None
  31. try:
  32. callback(TOOL_PROGRESS_EVENT, tool_name, message or None, None, tool_call_id=tool_call_id,
  33. progress=float(progress), total=None if total is None else float(total), percent=percent)
  34. except Exception: # health: allow BLE001 -- a UI sink failing must never fail the tool call
  35. logger.debug("tool.progress callback failed for %s", tool_name, exc_info=True)
  36. return report
  37. @contextlib.contextmanager
  38. def bound_tool_progress(callback, tool_name: str, tool_call_id: str) -> Iterator[None]:
  39. """Bind this call's relay for the block (no-op when the agent has no progress callback)."""
  40. token = _current.set(_reporter(callback, tool_name, tool_call_id or "") if callback else None)
  41. try:
  42. yield
  43. finally:
  44. _current.reset(token)
  45. def current_tool_progress() -> Optional[ProgressReporter]:
  46. """The running call's reporter, or None outside a dispatched tool call."""
  47. return _current.get()
  48. def tool_progress_payload(name: Optional[str], message: Optional[str], kwargs: dict) -> dict:
  49. """The ``tool.progress`` wire payload every viewer surface publishes (gateway event stream and
  50. the legacy TUI gateway): ``percent`` is 0-100 when the server sent a ``total``, else None."""
  51. return {"tool_id": str(kwargs.get("tool_call_id") or ""), "name": str(name or ""),
  52. "progress": float(kwargs.get("progress") or 0.0), "total": kwargs.get("total"),
  53. "percent": kwargs.get("percent"), "message": str(message) if message else None}