The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
feat(mcp): forward MCP notifications/progress as live tool.progress events
Teknium60affe7fe2ce
diff --git a/agent/tool_executor.py b/agent/tool_executor.pyindex b454e593b5d..da36c6a2d13 100644--- a/agent/tool_executor.py+++ b/agent/tool_executor.py@@ -749,7 +749,9 @@ def _dispatch_authorized_once(from agent.terminal_approval_batch import prepare_current_terminalprepare_current_terminal(ref)_advance_start_order(lambda: _begin_tool_execution(agent, ref, display_index))- return _run_with_activity_heartbeat(agent, ref.name, lambda: execute(ref.args))+ from agent.tool_progress_relay import bound_tool_progress+ with bound_tool_progress(agent.tool_progress_callback, ref.name, ref.call_id):+ return _run_with_activity_heartbeat(agent, ref.name, lambda: execute(ref.args))def _run_agent_tool_execution_middleware(diff --git a/agent/tool_progress_relay.py b/agent/tool_progress_relay.pynew file mode 100644index 00000000000..a7f24f7dd86--- /dev/null+++ b/agent/tool_progress_relay.py@@ -0,0 +1,68 @@+"""Live progress from inside a running tool call (MCP ``notifications/progress``) onto the agent's+``tool_progress_callback`` as ``tool.progress`` events.++The executor binds a relay for each dispatched call (``bound_tool_progress``); a tool reads it on its+own thread with ``current_tool_progress()`` and may invoke the result from any thread (the MCP client+fires it on the MCP event loop). Emission is throttled per call so a chatty server cannot flood the+UI; the first update and the one reaching ``total`` always pass.+"""++from __future__ import annotations++import contextlib+import contextvars+import logging+import threading+import time+from typing import Callable, Iterator, Optional++logger = logging.getLogger(__name__)++TOOL_PROGRESS_EVENT = "tool.progress"+_MIN_INTERVAL_S = 0.5++ProgressReporter = Callable[[float, Optional[float], Optional[str]], None]+_current: contextvars.ContextVar[Optional[ProgressReporter]] = contextvars.ContextVar("tool_progress_reporter", default=None)+++def _reporter(callback, tool_name: str, tool_call_id: str) -> ProgressReporter:+ lock = threading.Lock()+ last = [0.0]++ def report(progress: float, total: Optional[float] = None, message: Optional[str] = None) -> None:+ done = total is not None and total > 0 and progress >= total+ now = time.monotonic()+ with lock:+ if last[0] and not done and now - last[0] < _MIN_INTERVAL_S:+ return+ last[0] = now+ percent = round(min(max(progress / total, 0.0), 1.0) * 100) if total else None+ try:+ callback(TOOL_PROGRESS_EVENT, tool_name, message or None, None, tool_call_id=tool_call_id,+ progress=float(progress), total=None if total is None else float(total), percent=percent)+ except Exception: # health: allow BLE001 -- a UI sink failing must never fail the tool call+ logger.debug("tool.progress callback failed for %s", tool_name, exc_info=True)+ return report+++def bound_tool_progress(callback, tool_name: str, tool_call_id: str) -> Iterator[None]:+ """Bind this call's relay for the block (no-op when the agent has no progress callback)."""+ token = _current.set(_reporter(callback, tool_name, tool_call_id or "") if callback else None)+ try:+ yield+ finally:+ _current.reset(token)+++def current_tool_progress() -> Optional[ProgressReporter]:+ """The running call's reporter, or None outside a dispatched tool call."""+ return _current.get()+++def tool_progress_payload(name: Optional[str], message: Optional[str], kwargs: dict) -> dict:+ """The ``tool.progress`` wire payload every viewer surface publishes (gateway event stream and+ the legacy TUI gateway): ``percent`` is 0-100 when the server sent a ``total``, else None."""+ return {"tool_id": str(kwargs.get("tool_call_id") or ""), "name": str(name or ""),+ "progress": float(kwargs.get("progress") or 0.0), "total": kwargs.get("total"),+ "percent": kwargs.get("percent"), "message": str(message) if message else None}diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.tsindex 88646d431af..6cd610631d2 100644--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/index.ts@@ -27,7 +27,7 @@ import { handleOnboardingEvent } from './onboarding'import { handleControlEvent } from './session-control'import { handleSessionInfoEvent } from './session-info'import { handleStatusEvent } from './status'-import { handleToolEvent } from './tools'+import { handleToolEvent, handleToolProgressEvent } from './tools'import type { GatewayEventContext, GatewayEventDeps, GatewayEventHandler } from './types'export type { GatewayEventDeps } from './types'@@ -91,6 +91,7 @@ const HANDLERS: GatewayEventHandler[] = [handleDeferredPickEvent,handleControlEvent,handleMessageStreamEvent,+ handleToolProgressEvent,handleToolEvent,handleInputRequestEvent,handleDesktopBridgeEvent,diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools-progress.test.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools-progress.test.tsnew file mode 100644index 00000000000..98a6e5b5697--- /dev/null+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools-progress.test.ts@@ -0,0 +1,41 @@+import type { GatewayEvent } from '@hermes/shared'+import { afterEach, expect, it, vi } from 'vitest'++import { $toolProgress, $toolProgressFor, formatToolProgress } from '@/store/tool-progress'++import { handleToolProgressEvent } from './tools'+import type { GatewayEventContext } from './types'++function deliver(event: GatewayEvent) {+ return handleToolProgressEvent({+ event,+ payload: event.payload,+ sessionId: 's1',+ occurredAt: 1,+ isActiveEvent: true,+ deps: {+ flushQueuedDeltas: vi.fn(),+ updateSessionState: vi.fn(),+ sessionInterrupted: () => false,+ upsertToolCall: vi.fn(),+ nativeSubagentSessionsRef: { current: new Set() }+ }+ } as unknown as GatewayEventContext)+}++afterEach(() => $toolProgress.set({}))++it('shows tool.progress on its running row and drops it when the call completes', () => {+ const progress = {+ type: 'tool.progress',+ session_id: 's1',+ payload: { tool_id: 'c1', name: 'mcp__meshy__refine', progress: 42, total: 100, percent: 42, message: 'refining' }+ } as unknown as GatewayEvent++ expect(deliver(progress)).toBe(true)+ // MCP rows render each batched call as `<call id>:<index>`.+ expect(formatToolProgress($toolProgressFor('c1:0').get())).toBe('42% · refining')++ deliver({ type: 'tool.complete', session_id: 's1', payload: { tool_id: 'c1', name: 'mcp__meshy__refine' } } as GatewayEvent)+ expect($toolProgressFor('c1:0').get()).toBeUndefined()+})diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.tsindex 4815d498527..a04ad8bfd24 100644--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/tools.ts@@ -15,6 +15,7 @@ import { reportMcpToolResult } from '@/store/suggestion-providers/repair'import { invalidateSkillSuggestionIndex } from '@/store/suggestion-providers/skill'import { restoreSessionTodosFromSnapshot } from '@/store/todos'import { setSessionDraftingTool } from '@/store/tool-drafting'+import { clearToolProgress, setToolProgress } from '@/store/tool-progress'import { notifyWorkspaceChanged, toolChangedPath, toolMayMutateFiles } from '@/store/workspace-events'import { SUBAGENT_EVENT_TYPES, toTodoPayload } from '../utils'@@ -69,6 +70,31 @@ function appliedLayout(name: string | undefined, result: ToolCallMessagePart['rereturn undefined}+/** tool.progress (live MCP progress for a running call): a row annotation, never a transcript+ * mutation. Also retires it on tool.complete, which then falls through to handleToolEvent. */+export function handleToolProgressEvent({ deps, event, payload, sessionId }: GatewayEventContext): boolean {+ const toolId = typeof payload?.tool_id === 'string' ? payload.tool_id : ''++ if (event.type === 'tool.complete') {+ clearToolProgress(toolId)++ return false+ }++ if (event.type !== 'tool.progress') {+ return false+ }++ if (sessionId && !deps.sessionInterrupted(sessionId)) {+ setToolProgress(toolId, {+ message: typeof payload?.message === 'string' && payload.message ? payload.message : null,+ percent: typeof payload?.percent === 'number' ? payload.percent : null+ })+ }++ return true+}+/** tool.generating / tool.start / tool.complete / subagent.*. */export function handleToolEvent(ctx: GatewayEventContext): boolean {const { deps, event, payload, sessionId, isActiveEvent, occurredAt } = ctxdiff --git a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx b/apps/desktop/src/components/assistant-ui/tool/fallback.tsxindex 312506f7d98..6b05f7d8006 100644--- a/apps/desktop/src/components/assistant-ui/tool/fallback.tsx+++ b/apps/desktop/src/components/assistant-ui/tool/fallback.tsx@@ -52,6 +52,7 @@ import { recordPreviewArtifact } from '@/store/preview-status'import { sessionApprovalRequest } from '@/store/prompts'import { $showToolActivity } from '@/store/tool-activity'import { $toolRowDismissed, dismissToolRow } from '@/store/tool-dismiss'+import { $toolProgressFor, formatToolProgress } from '@/store/tool-progress'import {$anyToolDisclosureOpen,$hideCodeDiffs,@@ -344,6 +345,22 @@ function useDisclosureOpen(disclosureId: string, fallbackOpen = false): booleanreturn persistedOpen ?? fallbackOpen}+/** A running row's trailing meta: live MCP progress (`42% · message`, when the server sends it) + the timer. */+function ToolRunningMeta({ seconds, toolCallId = '' }: { seconds: number; toolCallId?: string }) {+ const progressText = formatToolProgress(useStore($toolProgressFor(toolCallId)))++ return (+ <>+ {progressText && (+ <span className={cn(SCAFFOLD_META_CLASS, 'max-w-64 truncate')} data-slot="tool-progress" title={progressText}>+ {progressText}+ </span>+ )}+ <ActivityTimerText className={SCAFFOLD_META_CLASS} seconds={seconds} />+ </>+ )+}+function ToolEntry({ part }: ToolEntryProps) {const { t } = useI18n()const copy = t.assistant.tool@@ -541,7 +558,7 @@ function ToolEntry({ part }: ToolEntryProps) {const trailing = !embedded ? (<span className="flex shrink-0 items-center gap-1.5"><TimelineTimestamp className={SCAFFOLD_META_CLASS} completedAt={completedAt} timestamp={timestamp} />- {isPending && <ActivityTimerText className={SCAFFOLD_META_CLASS} seconds={elapsed} />}+ {isPending && <ToolRunningMeta seconds={elapsed} toolCallId={toolCallId} />}</span>) : undefineddiff --git a/apps/desktop/src/lib/chat-messages/types.ts b/apps/desktop/src/lib/chat-messages/types.tsindex 4e10210e454..2473f0ce2a5 100644--- a/apps/desktop/src/lib/chat-messages/types.ts+++ b/apps/desktop/src/lib/chat-messages/types.ts@@ -87,6 +87,8 @@ export type GatewayEventPayload = {name?: stringtool_id?: stringtool_call_id?: string+ /** tool.progress: 0-100 when the MCP server sent a total. */+ percent?: number | nullargs?: unknownarguments?: unknowncontext?: stringdiff --git a/apps/desktop/src/lib/gateway-events.ts b/apps/desktop/src/lib/gateway-events.tsindex d775343ec39..c1de3fdd45f 100644--- a/apps/desktop/src/lib/gateway-events.ts+++ b/apps/desktop/src/lib/gateway-events.ts@@ -39,6 +39,7 @@ export const UNSCOPED_STREAM_EVENT_TYPES = new Set(['thinking.delta','tool.complete','tool.generating',+ 'tool.progress','tool.start','vault.code.expire','vault.code.request',diff --git a/apps/desktop/src/store/tool-progress.ts b/apps/desktop/src/store/tool-progress.tsnew file mode 100644index 00000000000..d90a6d61e4a--- /dev/null+++ b/apps/desktop/src/store/tool-progress.ts@@ -0,0 +1,50 @@+import { atom, computed, type ReadableAtom } from 'nanostores'++/** Latest live progress of a running tool call (`tool.progress`, from MCP `notifications/progress`). */+export interface ToolProgress {+ message: null | string+ percent: null | number+}++// Keyed by tool call id. Ephemeral by design: progress only exists while a call+// runs, so it is never persisted and the row drops it once the call completes.+export const $toolProgress = atom<Record<string, ToolProgress>>({})++const progressCache = new Map<string, ReadableAtom<ToolProgress | undefined>>()++export function $toolProgressFor(toolCallId: string): ReadableAtom<ToolProgress | undefined> {+ let cached = progressCache.get(toolCallId)++ if (!cached) {+ // MCP rows render per batched call as `<call id>:<index>`; progress is reported for the call.+ const callId = toolCallId.replace(/:\d+$/, '')+ cached = computed($toolProgress, rows => rows[toolCallId] ?? rows[callId])+ progressCache.set(toolCallId, cached)+ }++ return cached+}++export function setToolProgress(toolCallId: string, progress: ToolProgress): void {+ if (toolCallId) {+ $toolProgress.set({ ...$toolProgress.get(), [toolCallId]: progress })+ }+}++export function clearToolProgress(toolCallId: string): void {+ const rows = $toolProgress.get()++ if (toolCallId && rows[toolCallId]) {+ const { [toolCallId]: _done, ...rest } = rows+ $toolProgress.set(rest)+ }+}++/** `42% · refining mesh` — the text a running tool row shows beside its timer. */+export function formatToolProgress(progress: ToolProgress | undefined): string {+ if (!progress) {+ return ''+ }++ return [progress.percent === null ? '' : `${progress.percent}%`, progress.message ?? ''].filter(Boolean).join(' · ')+}diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.tsindex 639c49f98ab..5a3f082e551 100644--- a/apps/shared/src/gateway-contract.generated.ts+++ b/apps/shared/src/gateway-contract.generated.ts@@ -5748,6 +5748,15 @@ export interface ToolOutputRiskPayload {findings: string[]redacted: boolean}+/** ``agent.tool_progress_relay.tool_progress_payload`` — an MCP server's ``notifications/progress`` for a running call, throttled to one per 500 ms per call. */+export interface ToolProgressPayload {+ tool_id: string+ name: string+ progress: number+ total?: number | null+ percent?: number | null+ message?: string | null+}/** ``tool_progress._normalize_todo_state`` — full task snapshot. */export interface TodoUpdatedPayload {todos: unknown[]@@ -7081,6 +7090,8 @@ export interface BackendGatewayEventMap {'tool.generating': ToolGeneratingPayload/** Tool output was classified as risky (prompt-injection / secret findings). */'tool.output_risk': ToolOutputRiskPayload+ /** Live progress of a running tool call (MCP notifications/progress). */+ 'tool.progress': ToolProgressPayload/** A tool call began (stable id + full args). */'tool.start': ToolStartPayload/** Barge-in: the spoken interjection interrupted the turn; no payload. */@@ -7169,6 +7180,7 @@ export const GATEWAY_EVENT_TYPES = ['tool.complete','tool.generating','tool.output_risk',+ 'tool.progress','tool.start','voice.interrupted','voice.partial',diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.jsonindex 0d8c05765f9..bea828a5c28 100644--- a/apps/shared/src/gateway-contract.openrpc.json+++ b/apps/shared/src/gateway-contract.openrpc.json@@ -43809,6 +43809,67 @@"title": "ToolOutputRiskPayload","type": "object"},+ "ToolProgressPayload": {+ "additionalProperties": false,+ "description": "``agent.tool_progress_relay.tool_progress_payload`` \u2014 an MCP server's\n``notifications/progress`` for a running call, throttled to one per 500 ms per call.",+ "properties": {+ "tool_id": {+ "title": "Tool Id",+ "type": "string"+ },+ "name": {+ "title": "Name",+ "type": "string"+ },+ "progress": {+ "title": "Progress",+ "type": "number"+ },+ "total": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Total"+ },+ "percent": {+ "anyOf": [+ {+ "type": "integer"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Percent"+ },+ "message": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Message"+ }+ },+ "required": [+ "tool_id",+ "name",+ "progress"+ ],+ "title": "ToolProgressPayload",+ "type": "object"+ },"ToolShowRow": {"additionalProperties": false,"properties": {@@ -49177,6 +49238,18 @@}]},+ {+ "name": "tool.progress",+ "summary": "Live progress of a running tool call (MCP notifications/progress).",+ "params": [+ {+ "name": "payload",+ "schema": {+ "$ref": "#/components/schemas/ToolProgressPayload"+ }+ }+ ]+ },{"name": "tool.start","summary": "A tool call began (stable id + full args).",diff --git a/gateway/local_viewer_events.py b/gateway/local_viewer_events.pyindex de6bec9a747..c3353f94f06 100644--- a/gateway/local_viewer_events.py+++ b/gateway/local_viewer_events.py@@ -135,6 +135,10 @@ def publish_progress(turn, event_type, name, preview, kwargs) -> None:_publish_subagent(turn, event_type, _subagent_payload(event_type, name, preview, kwargs, show_reasoning=show_reasoning(turn)))return+ if event_type == "tool.progress":+ from agent.tool_progress_relay import tool_progress_payload+ turn._publish_execution(event_type, tool_progress_payload(name, preview, kwargs))+ returnif event_type != "reasoning.available" and event_type not in _MOA_KEYS:returnfrom gateway.session_cli_turn import classic_cli_turndiff --git a/hermes_cli/cli_stream_mixin.py b/hermes_cli/cli_stream_mixin.pyindex 00ed37e8f7c..a00e1890c50 100644--- a/hermes_cli/cli_stream_mixin.py+++ b/hermes_cli/cli_stream_mixin.py@@ -763,6 +763,7 @@ class CLIStreamMixin:if event_type == "tool.completed":self._tool_start_time = 0.0+ self.__dict__.pop("_tool_spinner_base", None)self._turn_summary_record(function_name, kwargs.get("result"), kwargs.get("is_error", False))# Focus view: count the hidden scrollback line for the post-turn recovery report.@@ -810,20 +811,28 @@ class CLIStreamMixin:self._invalidate()returnif event_type != "tool.started":- return+ return self._show_tool_progress(event_type, preview, kwargs.get("percent"))if function_name and not function_name.startswith("_"):from agent.display import get_tool_preview_max_len, tool_row_emojilabel = preview or function_name_pl = get_tool_preview_max_len()if _pl > 0 and len(label) > _pl:label = label[:_pl - 3] + "..."- self._spinner_text = f"{tool_row_emoji(function_name, function_args)} {label}"+ self._spinner_text = self._tool_spinner_base = f"{tool_row_emoji(function_name, function_args)} {label}"self._tool_start_time = time.monotonic()# Store args for stacked scrollback line on completionself._pending_tool_info.setdefault(function_name, []).append(function_args if function_args is not None else {})self._invalidate()+ def _show_tool_progress(self, event_type, message, percent) -> None:+ """Live MCP progress rides the running tool's spinner line: ``<tool label> · 42% · message``."""+ base = self.__dict__.get("_tool_spinner_base")+ if event_type == "tool.progress" and base:+ parts = [base] + ([f"{percent}%"] if percent is not None else []) + ([message] if message else [])+ self._spinner_text = " · ".join(parts)+ self._invalidate()+def _on_tool_start(self, tool_call_id: str, function_name: str, function_args: dict):"""Capture local before-state for write-capable tools."""from cli import loggerdiff --git a/hermes_cli/gateway_agent.py b/hermes_cli/gateway_agent.pyindex 9a1a086702f..14214673a71 100644--- a/hermes_cli/gateway_agent.py+++ b/hermes_cli/gateway_agent.py@@ -952,6 +952,12 @@ class GatewayAgent:if self.tool_gen_callback is not None:self.tool_gen_callback(payload.get("name"))+ def _on_tool_progress(self, payload, stream_callback, starts):+ if self.tool_progress_callback is not None:+ self.tool_progress_callback("tool.progress", payload.get("name"), payload.get("message"), None,+ tool_call_id=payload.get("tool_id"), progress=payload.get("progress"),+ total=payload.get("total"), percent=payload.get("percent"))+def _on_tool_start(self, payload, stream_callback, starts):self._close_segment(starts)name = payload.get("name") or payload.get("tool_name") or "tool"@@ -1386,6 +1392,7 @@ _HANDLERS = {"message.delta": GatewayAgent._on_delta,"message.interim": GatewayAgent._on_interim,"tool.generating": GatewayAgent._on_tool_generating,+ "tool.progress": GatewayAgent._on_tool_progress,"tool.start": GatewayAgent._on_tool_start,"tool.complete": GatewayAgent._on_tool_complete,"todo.updated": GatewayAgent._on_todo,diff --git a/tests/tools/test_mcp_tool_progress.py b/tests/tools/test_mcp_tool_progress.pynew file mode 100644index 00000000000..5e051534cfc--- /dev/null+++ b/tests/tools/test_mcp_tool_progress.py@@ -0,0 +1,59 @@+"""An MCP server's ``notifications/progress`` during ``tools/call`` reaches the agent's+``tool_progress_callback`` as throttled ``tool.progress`` events for that call id. Real stdio child,+real config, real SDK progress token round trip."""++import json+import sys+import textwrap++import pytest++SERVER = textwrap.dedent('''\+ import asyncio+ from mcp.server.mcpserver import MCPServer, Context+ app = MCPServer("prog")++ @app.tool()+ async def slow(ctx: Context) -> str:+ for i in range(1, 21):+ await asyncio.sleep(0.1)+ await ctx.report_progress(i * 5, 100, f"stage {i}")+ return "done"++ app.run()+''')++[email protected]_isolate[email protected]("posix")+def test_mcp_progress_notifications_reach_tool_progress_callback(monkeypatch, tmp_path):+ pytest.importorskip("mcp.server.mcpserver")+ home = tmp_path / "home"+ home.mkdir()+ (home / "server.py").write_text(SERVER, encoding="utf-8")+ (home / "config.yaml").write_text(+ f"mcp_servers:\n prog:\n command: {json.dumps(sys.executable)}\n args: [{json.dumps(str(home / 'server.py'))}]\n",+ encoding="utf-8")+ monkeypatch.setenv("HERMES_HOME", str(home))++ from agent.tool_progress_relay import bound_tool_progress+ from tools import mcp_tool_discovery as disc+ from tools import mcp_tool_loop as _loop+ from tools.registry import registry++ events = []+ try:+ assert "mcp__prog__slow" in disc.discover_mcp_tools()+ with bound_tool_progress(lambda *a, **kw: events.append((a, kw)), "mcp__prog__slow", "call-7"):+ result = registry.dispatch("mcp__prog__slow", {})+ assert "done" in result+ finally:+ from tools.mcp_tool_lifecycle import shutdown_mcp_servers+ shutdown_mcp_servers()+ _loop._stop_mcp_loop()++ assert events and all(a[0] == "tool.progress" and a[1] == "mcp__prog__slow" for a, _ in events)+ assert {kw["tool_call_id"] for _, kw in events} == {"call-7"}+ # 20 notifications over ~2 s, throttled to <= one per 500 ms, the final 100% always delivered.+ assert 2 <= len(events) <= 8+ assert events[-1][1]["percent"] == 100 and events[-1][0][2] == "stage 20"diff --git a/tools/mcp_tool_handlers.py b/tools/mcp_tool_handlers.pyindex e5c4de2de05..3723e119183 100644--- a/tools/mcp_tool_handlers.py+++ b/tools/mcp_tool_handlers.py@@ -379,7 +379,7 @@ async def _track_inflight_rpc(server: Any, server_name: str, op: str, *, retry_sinflight.discard(task)-async def _call_tool_racing_stdio_death(server, server_name: str, tool_name: str, args: dict):+async def _call_tool_racing_stdio_death(server, server_name: str, tool_name: str, args: dict, progress_callback=None):"""``session.call_tool`` that fails fast when the stdio child is/gets dead: pre-call (a deadchild must not hold the slot for the full timeout) and mid-call (race against``_watch_stdio_children``). Both raise :class:`_StdioChildExited` for the respawn path, which@@ -393,7 +393,10 @@ async def _call_tool_racing_stdio_death(server, server_name: str, tool_name: strf"MCP stdio subprocess for '{server_name}' had already exited when the call was dispatched",in_flight=False,)- _call_coro = server.session.call_tool(tool_name, arguments=args)+ # A progress callback makes the SDK send ``_meta.progressToken``, the spec's opt-in for+ # ``notifications/progress``; without one the server must stay silent.+ extra = {"progress_callback": progress_callback} if progress_callback is not None else {}+ _call_coro = server.session.call_tool(tool_name, arguments=args, **extra)_watch_children = getattr(server, "_watch_stdio_children", None)if not (inspect.iscoroutinefunction(_watch_children) and asyncio.iscoroutine(_call_coro)):# Stubbed sessions return a non-awaitable, or there is no child-watcher to race: plain await.@@ -582,12 +585,20 @@ def _make_tool_handler(server_name: str, tool_name: str, tool_timeout: float, *,# pre-dispatch so the auth recoverer keeps its retry for every tool.read_only = _tool_is_read_only(server_name, tool_name)image_paths: list[str] = [] # the LAST attempt's cached images (a recoverer may retry _call)+ # Read on the agent's thread: the coroutine below runs on the MCP loop, outside this context.+ from agent.tool_progress_relay import current_tool_progress+ report = current_tool_progress()++ async def _on_progress(progress, total, message):+ if report is not None:+ report(progress, total, message)async def _call():async with server._rpc_lock, _track_inflight_rpc(server, server_name, op, retry_safe=read_only):server._pending_call_context = contextvars.copy_context() # for the elicitation callbacktry:- result = await _call_tool_racing_stdio_death(server, server_name, tool_name, args)+ result = await _call_tool_racing_stdio_death(+ server, server_name, tool_name, args, _on_progress if report is not None else None)finally:server._pending_call_context = Noneif getattr(server, "_mark_session_proven", None) is not None: # round-trip done: transport healthydiff --git a/tui_gateway/contracts/events.py b/tui_gateway/contracts/events.pyindex b44328f5f04..5ab556f2f73 100644--- a/tui_gateway/contracts/events.py+++ b/tui_gateway/contracts/events.py@@ -409,6 +409,21 @@ class ToolOutputRiskPayload(Payload):event("tool.output_risk", ToolOutputRiskPayload, doc="Tool output was classified as risky (prompt-injection / secret findings).")+class ToolProgressPayload(Payload):+ """``agent.tool_progress_relay.tool_progress_payload`` — an MCP server's+ ``notifications/progress`` for a running call, throttled to one per 500 ms per call."""++ tool_id: str+ name: str+ progress: float+ total: float | None = None+ percent: int | None = None+ message: str | None = None+++event("tool.progress", ToolProgressPayload, doc="Live progress of a running tool call (MCP notifications/progress).")++class TodoUpdatedPayload(Payload):"""``tool_progress._normalize_todo_state`` — full task snapshot."""@@ -846,7 +861,8 @@ __all__ = ["SetupReadyPayload", "SideAgentCompletePayload", "SkinPayload", "StatusUpdatePayload","StreamDeltaPayload", "SubagentEventPayload", "SubagentOutputTailEntry", "TerminalClosePayload","TerminalOutputPayload", "TipShowPayload", "TodoUpdatedPayload", "ToolCompletePayload",- "ToolGeneratingPayload", "ToolLabel", "ToolLabelKind", "ToolOutputRiskPayload", "ToolStartPayload",+ "ToolGeneratingPayload", "ToolLabel", "ToolLabelKind", "ToolOutputRiskPayload", "ToolProgressPayload",+ "ToolStartPayload","TurnStatus", "VoicePartialPayload", "VoiceStatusPayload","VoiceTranscriptPayload", "WakeDetectedPayload",]diff --git a/tui_gateway/tool_progress.py b/tui_gateway/tool_progress.pyindex 8e427a9ae44..db024b80a4e 100644--- a/tui_gateway/tool_progress.py+++ b/tui_gateway/tool_progress.py@@ -380,6 +380,13 @@ def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result# `tool.started` is dropped on purpose: _on_tool_start already emits the authoritative tool.start with# the stable id and args; an id-less duplicate row makes the desktop live view diverge from history.+def _progress_tool_progress(sid, name, preview, kw):+ # Live MCP progress on a running tool row: tool chrome, so it follows display.tool_progress.+ if _tool_progress_enabled(sid):+ from agent.tool_progress_relay import tool_progress_payload+ _emit("tool.progress", sid, tool_progress_payload(name, preview, kw))++def _progress_output_risk(sid, name, preview, kw):# A risk badge on a tool row: tool chrome, so it follows display.tool_progress.metadata = kw.get("risk_metadata")@@ -494,7 +501,8 @@ def _progress_subagent(sid: str, name: str, preview, kw, event_type):# event_type -> (handler, requires): `requires` names the arg that must be truthy for the row to be# emitted at all ("name" / "preview" / None)._PROGRESS_HANDLERS = {- "tool.output_risk": (_progress_output_risk, "name"), "reasoning.available": (_progress_reasoning, "preview"),+ "tool.output_risk": (_progress_output_risk, "name"), "tool.progress": (_progress_tool_progress, "name"),+ "reasoning.available": (_progress_reasoning, "preview"),"moa.reference": (_progress_moa_reference, "name"),# Answer-only drops MoA content (references, progress/phase lines that land in the reasoning# disclosure or activity log) but keeps this: a bare state transition both clients use onlydiff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.mdindex 24a0e136b83..2b2eb438b77 100644--- a/website/docs/developer-guide/desktop-plugin-sdk.md+++ b/website/docs/developer-guide/desktop-plugin-sdk.md@@ -1223,6 +1223,35 @@ listener can't affect app dispatch. Every `host` door is async-safe: a sync throfrom an internal helper (e.g. no desktop bridge in a plain browser) becomes arejection your `.catch()` sees, never an error-boundary crash.+#### Live tool progress — `tool.progress` {#tool-progress-event}++While a tool call runs, an MCP server that sends `notifications/progress` (the+MCP spec's progress channel; Hermes opts in by sending `_meta.progressToken` on+every `tools/call`) reaches the renderer as a `tool.progress` event. The native+tool row shows it as `42% · <message>` next to its timer; a plugin can render+its own view:++```javascript+ctx.onEvent('tool.progress', ({ session_id, payload }) => {+ // payload: { tool_id, name, progress, total, percent, message }+ if (payload.name.startsWith('mcp__meshy__')) showRefineProgress(payload.tool_id, payload.percent, payload.message)+})+ctx.onEvent('tool.complete', ({ payload }) => clearRefineProgress(payload.tool_id))+```++| Field | Type | Meaning |+|---|---|---|+| `tool_id` | `string` | The call id; the same `tool_id` as the call's `tool.start` / `tool.complete` |+| `name` | `string` | Registered tool name (`mcp__<server>__<tool>`) |+| `progress` | `number` | The server's raw progress value |+| `total` | `number \| null` | The server's total, when it sent one |+| `percent` | `number \| null` | `0`–`100` (rounded, clamped) when `total` is set, else `null` |+| `message` | `string \| null` | The server's progress message |++Events are throttled to at most one per 500 ms per call; the first update and+the one that reaches `total` always arrive. They are never stored in the+transcript, so a reopened session shows only the finished row.+`ctx.os` is the curated OS door — every way a plugin reaches outside the appwindow, in one namespace attributed to your plugin. `ctx.os.notify` posts a**native OS notification** — the same Electron pipeline the app's own