@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/app/mcp-app-view.tsx

@@ -1,19 +1,27 @@
-import { useState, useCallback, useMemo, type ReactNode } from "react"
+import { useState, useCallback, useEffect, useMemo, type ReactNode } from "react"
 import { LucideProvider } from "lucide-react"
-import { ToolCancelledError, useDisplayMode, useHostContext, useToolContext } from "mcp-use/react"
-import { ToastProvider, useToast } from "../components/Toast.js"
-import { ToolkitLocaleFallback, useToolkitMessages } from "../locale/locale-provider.js"
-import type { ViewMessages } from "../locale/toolkit-messages.js"
-import { AppQueryProvider, queryClient } from "../providers/query-provider.js"
+import { ToolCancelledError, useHostContext, useToolContext } from "mcp-use/react"
+import { ToastProvider } from "../components/Toast.js"
 import {
+  ToolkitLocaleFallback,
+  useToolkitLocale,
+  useToolkitMessages,
+} from "../locale/locale-provider.js"
+import { formatClockTime, resolveFormatLocale } from "../locale/toolkit-messages.js"
+import { AppQueryProvider, useAppQueryClient } from "../providers/query-provider.js"
+import { resolveToolSafety } from "../hooks/tool-result-recovery-model.js"
+import {
+  DEFAULT_ASSUME_STRIPPED_AFTER_MS,
   resolveRecoveryToolName,
   useToolResultRecovery,
+  type RecoveryPolicy,
 } from "../hooks/use-tool-result-recovery.js"
 import { ICON_STROKE } from "../lib/icon-stroke.js"
 import { useHostBridge } from "./host-bridge.js"
+import { useViewResultSink } from "./mcp-use-host-bridge.js"
+import { HostModelContext } from "./model-context.js"
 import {
   applyBuilderCommit,
-  fullscreenAvailable,
   isCompleteViewData,
   StepErrors,
   ViewBody,
@@ -27,13 +35,22 @@ import {
 } from "./mcp-app-view-chrome.js"
 import { ViewPlaceholder, type DescribeViewError } from "./mcp-app-view-states.js"
 import type { LayoutBuilderLabels } from "./layout-builder.js"
+import { useBuildModeFocus } from "./use-build-mode-focus.js"
+import { useFullscreenToggle, useViewRefresh } from "./use-view-actions.js"
 import { useRetryFocus, useViewLifecycle } from "./use-view-lifecycle.js"
-import { DEFAULT_SLOW_HINT_MS, decodeViewResult } from "./view-lifecycle.js"
+import {
+  DEFAULT_SLOW_HINT_MS,
+  describeViewForModel,
+  reloadedAtOf,
+  type ViewLifecycle,
+  type ViewSource,
+} from "./view-lifecycle.js"
 import type { WidgetComponent } from "./widget-renderer.js"
 
 export type { McpAppViewLabels, ViewTitleLevel, ViewTitleMode } from "./mcp-app-view-chrome.js"
 export type { DescribeStep } from "./mcp-app-view-chrome.js"
-export type { DescribeViewError } from "./mcp-app-view-states.js"
+export type { DescribeViewError, ViewErrorKind } from "./mcp-app-view-states.js"
+export type { RecoveryPolicy } from "../hooks/use-tool-result-recovery.js"
 
 export interface McpAppViewProps {
   /**
@@ -88,6 +105,34 @@ export interface McpAppViewProps {
   describeError?: DescribeViewError
   /** Human title of a pipeline step in the failed-steps alert (default: the step id). */
   describeStep?: DescribeStep
+  /**
+   * Which originating tools the view may re-execute on its own when the host
+   * strips the result's `structuredContent` (claude.ai, Claude Desktop).
+   * `"auto"` (default): any tool the host does not report as writing
+   * (`readOnlyHint: false` or `destructiveHint: true`); `"read-only"`: only
+   * tools reported with `readOnlyHint: true`; `"never"`: none. A recovery
+   * the policy forbids shows a note that the chat did not pass the result to
+   * the view. It offers to load the view only for a tool the host does not
+   * report as writing; for a writing tool it asks for the current state in
+   * the chat, so one click never runs the write a second time.
+   */
+  recoverStrippedResult?: RecoveryPolicy
+  /**
+   * Grace period (ms) after which a silent call counts as a stripped result.
+   * Only used where the view could not watch the host's notifications from
+   * the start (e.g. a custom shell mounted under its own `bootstrapView`
+   * without `installToolResultObserver`); a view mounted by
+   * `mountMcpToolkitApp` sees the stripped result itself and never guesses,
+   * so a slow tool is never re-run. Default 2500 ms.
+   */
+  strippedResultGraceMs?: number
+  /**
+   * Put the tool name into the cache keys of the data hooks inside the view
+   * (`[...queryKey, toolName, args]`, see `toolQueryKey`), so two tools never
+   * share an entry. Omitted: an enclosing `AppQueryProvider`'s setting, else
+   * the 2.x key `[...queryKey, args]`. The next major makes it the default.
+   */
+  toolNameInQueryKey?: boolean
 }
 
 /**
@@ -97,6 +142,8 @@ export interface McpAppViewProps {
  * the host's locale unless a `LocaleProvider` sets one, so the chrome follows
  * the host language; `useLocale()` in consumer widgets is unaffected. Lucide
  * icons draw at the CI stroke (2.5) throughout, the toast stack included.
+ * The widgets' data hooks fetch through an enclosing `AppQueryProvider`'s
+ * client, else the toolkit's shared `queryClient`.
  */
 export function McpAppView(props: McpAppViewProps) {
   const { locale } = useHostContext()
@@ -112,17 +159,32 @@ export function McpAppView(props: McpAppViewProps) {
   )
 }
 
+/** The payload the view shows, where it came from, and when the view loaded it itself. */
+interface ShownView {
+  data: ViewData | null
+  source: ViewSource | null
+  /**
+   * When the view re-loaded the payload itself (epoch ms), so its figures can
+   * differ from the result the chat answered from (`reloadedAtOf`); `null`
+   * otherwise.
+   */
+  reloadedAt: number | null
+}
+
+const NO_VIEW: ShownView = { data: null, source: null, reloadedAt: null }
+
 /**
- * Host-delivered payload → local `viewData`, recovered payloads included.
- * Render-phase setState (not an effect) so the React Compiler doesn't flag a
- * cascading render.
+ * Host-delivered payload → the shown view, recovered payloads included, each
+ * tagged with its source. Render-phase setState (not an effect) so the React
+ * Compiler doesn't flag a cascading render.
  */
 function useHostViewData(
   initialViewData: ViewData | undefined,
   isPending: boolean,
   recovered: ViewData | null,
+  recoveredAt: number | null,
 ) {
-  const [viewData, setViewData] = useState<ViewData | null>(null)
+  const [view, setView] = useState<ShownView>(NO_VIEW)
   // `prev` MUST start as `null`, not `initialViewData`: hosts that expose the
   // complete tool output before the app's first render (e.g. window.openai
   // globals injected ahead of script execution) would otherwise never trip the
@@ -132,95 +194,148 @@ function useHostViewData(
   const [prevInitial, setPrevInitial] = useState<ViewData | undefined | null>(null)
   if (initialViewData !== prevInitial) {
     setPrevInitial(initialViewData)
-    if (!isPending && isCompleteViewData(initialViewData)) setViewData(initialViewData)
+    if (!isPending && isCompleteViewData(initialViewData)) {
+      setView({ data: initialViewData, source: "host", reloadedAt: null })
+    }
   }
   const [prevRecovered, setPrevRecovered] = useState<ViewData | null>(null)
   if (recovered !== prevRecovered) {
     setPrevRecovered(recovered)
-    // The host-delivered payload always wins; recovery only fills the gap.
-    if (recovered && !viewData) setViewData(recovered)
+    // The host-delivered payload always wins; a recovery fills the gap, and a
+    // recovery for newer arguments replaces an older recovered payload (N21).
+    if (recovered) {
+      setView((prev) =>
+        prev.data === null || prev.source === "recovered"
+          ? { data: recovered, source: "recovered", reloadedAt: recoveredAt }
+          : prev,
+      )
+    }
   }
-  return [viewData, setViewData] as const
+  return [view, setView] as const
 }
 
 /**
- * Refresh via the refresh tool. A failure keeps the data and says so in a
- * toast in catalog words only; the raw reason goes to the console, never to
- * the user.
+ * Hands the payload the view shows (the host's, its own recovery's, the
+ * user's retry or refresh) to the host bridge, so `HostBridge.getWidgetData()`
+ * returns what the view shows (toolkit#176 K15), also after a latch the view
+ * could not render.
  */
-function useViewRefresh(options: {
-  viewData: ViewData | null
-  setViewData: (next: ViewData) => void
-  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
-  refreshToolName: string
-  labels: Pick<ViewMessages, "refreshFailed" | "refreshFailedHint">
-}) {
-  const { viewData, setViewData, callTool, refreshToolName, labels } = options
-  const toast = useToast()
-  const [isRefreshing, setIsRefreshing] = useState(false)
-  const refreshView = useCallback(async () => {
-    if (!viewData?._refreshParams) return
-    setIsRefreshing(true)
-    let failure: unknown = null
-    try {
-      const result = await callTool(
-        refreshToolName,
-        viewData._refreshParams as unknown as Record<string, unknown>,
-      )
-      // One decoding convention with `useToolQuery` (structured-first), with a
-      // typed outcome: an unusable payload is a failure, never exception text.
-      const outcome = decodeViewResult(result, isCompleteViewData)
-      if (outcome.ok) setViewData(outcome.data)
-      else failure = outcome.reason ?? "the refresh tool returned no view"
-      // The call went through, so self-fetching widgets refresh as well;
-      // a tool error refreshes nothing.
-      if (outcome.ok || !outcome.isError) void queryClient.invalidateQueries()
-    } catch (e) {
-      failure = e
-    } finally {
-      setIsRefreshing(false)
-    }
-    if (failure === null) return
-    console.warn("[mcp-toolkit] refresh failed:", failure)
-    toast.show({
-      tone: "danger",
-      title: labels.refreshFailed,
-      description: labels.refreshFailedHint,
-    })
-  }, [callTool, labels, refreshToolName, setViewData, toast, viewData])
-  return { isRefreshing, refreshView }
+function useReportShownPayload(view: ShownView) {
+  const report = useViewResultSink()
+  const payload = view.data
+  useEffect(() => {
+    if (payload) report?.(payload)
+  }, [payload, report])
+}
+
+/** The rendering call as mcp-use 2.x latches it, plus the tool the host names. */
+function useRenderCall() {
+  const tool = useToolContext()
+  const { hostContext } = useHostContext()
+  // Since mcp-use 2.7.1 a host cancellation latches as `status: "error"`.
+  const isCancelled = tool.status === "error" && tool.error instanceof ToolCancelledError
+  const isCallError = tool.status === "error" && !isCancelled
+  return {
+    tool,
+    hostContext,
+    isPending: tool.status === "pending",
+    isCancelled,
+    isCallError,
+    callError: isCallError ? tool.error : undefined,
+    initialViewData: tool.status === "ready" ? (tool.toolOutput as ViewData) : undefined,
+    toolName: resolveRecoveryToolName(hostContext),
+    /** The host reports the tool as writing: the view never offers to re-run it after a block. */
+    toolWrites: resolveToolSafety(hostContext) === "writes",
+  }
 }
 
 /**
- * The fullscreen toggle, gated on the host's offer. A rejected request shows
- * a toast in catalog words; the raw reason goes to the console.
+ * The payload the view shows: the host's, else the stripped-result recovery's.
+ * Hosts that strip `structuredContent` (claude.ai) never latch a result under
+ * mcp-use 2.x; the recovery re-executes the call once when the stripped
+ * result arrives. It never fires on a cancelled or failed call, nor while a
+ * slow tool is still running (#176): those render their state.
  */
-function useFullscreenToggle(
-  labels: Pick<ViewMessages, "fullscreenFailed" | "fullscreenFailedHint">,
+function useShownView(
+  call: ReturnType<typeof useRenderCall>,
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>,
+  policy: RecoveryPolicy = "auto",
+  graceMs: number = DEFAULT_ASSUME_STRIPPED_AFTER_MS,
 ) {
-  const { displayMode, availableDisplayModes, requestDisplayMode } = useDisplayMode()
-  const toast = useToast()
-  const toggle = useCallback(async () => {
-    const mode = displayMode === "fullscreen" ? "inline" : "fullscreen"
-    try {
-      // Advisory since 2.x: `displayMode` updates when the host applies it.
-      await requestDisplayMode({ mode })
-    } catch (e) {
-      console.warn("[mcp-toolkit] display-mode request failed:", e)
-      toast.show({
-        tone: "danger",
-        title: labels.fullscreenFailed,
-        description: labels.fullscreenFailedHint,
-      })
-    }
-  }, [displayMode, labels, requestDisplayMode, toast])
+  const recovery = useToolResultRecovery<ViewData>({
+    resultReady: !call.isPending,
+    cancelled: call.isCancelled,
+    errored: call.isCallError,
+    props: call.initialViewData,
+    isValid: isCompleteViewData,
+    toolInput: call.tool.toolInput,
+    hostContext: call.hostContext,
+    callTool,
+    policy,
+    assumeStrippedAfterMs: graceMs,
+  })
+  const [view, setView] = useHostViewData(
+    call.initialViewData,
+    call.isPending,
+    recovery.data,
+    recovery.recoveredAt,
+  )
+  useReportShownPayload(view)
+  // A re-run's figures can differ from the answer in the chat (N23): stamp
+  // it, unless the original call failed and the chat never had figures.
+  const callFailed = call.isCallError || call.isCancelled
+  const showRetried = useCallback(
+    (data: ViewData) =>
+      setView({ data, source: "retry", reloadedAt: reloadedAtOf("retry", Date.now(), callFailed) }),
+    [setView, callFailed],
+  )
+  const showRefreshed = useCallback(
+    (data: ViewData) =>
+      setView({
+        data,
+        source: "refresh",
+        reloadedAt: reloadedAtOf("refresh", Date.now(), callFailed),
+      }),
+    [setView, callFailed],
+  )
   return {
-    isFullscreen: displayMode === "fullscreen",
-    canFullscreen: fullscreenAvailable(displayMode, availableDisplayModes),
-    toggle,
+    view,
+    setView,
+    showRetried,
+    showRefreshed,
+    // Without a named tool nothing can re-run it: a plain failure. A policy
+    // block is its own state: the tool ran, and the view must not repeat it.
+    recoveryFailed: recovery.failed || recovery.blocked === "no-tool",
+    recoveryBlocked: recovery.blocked === "policy",
   }
 }
 
+/**
+ * The view's own line of model context (toolkit#176 K20, N23): an error the
+ * user sees instead of the view, failed data steps, or data the view
+ * re-loaded itself (a recovery, a retry, a refresh). Renders nothing while
+ * there is nothing to report.
+ */
+function ViewModelContext({
+  lifecycle,
+  toolName,
+  view,
+}: {
+  lifecycle: ViewLifecycle
+  toolName: string | undefined
+  view: ShownView
+}) {
+  const content = describeViewForModel({
+    lifecycle,
+    toolName,
+    stepErrors: view.data?.context.errors,
+    stepsRetryable: Boolean(view.data?._refreshParams),
+    reloadedAt: view.reloadedAt,
+    reloadedBy: reloadedByOf(view.source),
+  })
+  return content ? <HostModelContext content={content} /> : null
+}
+
 function McpAppViewShell({
   widgets,
   refreshToolName = "refresh-view",
@@ -233,13 +348,21 @@ function McpAppViewShell({
   slowHintAfterMs = DEFAULT_SLOW_HINT_MS,
   describeError,
   describeStep,
+  recoverStrippedResult,
+  strippedResultGraceMs,
+  toolNameInQueryKey,
 }: McpAppViewProps) {
   const messages = useToolkitMessages()
   const L = useMemo(() => ({ ...messages.view, ...labels }), [messages.view, labels])
   // The mcp-use 2.x view channels (all need the `bootstrapView` mount
   // `mountMcpToolkitApp` provides); tools go through the HostBridge.
-  const tool = useToolContext()
-  const { safeArea, hostContext } = useHostContext()
+  const call = useRenderCall()
+  const { safeArea, locale, timeZone } = useHostContext()
+  // A time in the language of the sentence around it, in the host's zone.
+  const formatLocale = resolveFormatLocale(useToolkitLocale(), locale)
+  // The client the view's widgets fetch through (an enclosing
+  // AppQueryProvider's, else the shared one): a refresh invalidates it.
+  const viewClient = useAppQueryClient()
   const bridge = useHostBridge()
   const callTool = useCallback(
     (name: string, args: Record<string, unknown>) => bridge.callTool(name, args),
@@ -251,56 +374,46 @@ function McpAppViewShell({
     (name: string, args: object) => bridge.callTool(name, args as Record<string, unknown>),
     [bridge],
   )
-  const isPending = tool.status === "pending"
-  // Since mcp-use 2.7.1 a host cancellation latches as `status: "error"`.
-  const isCancelled = tool.status === "error" && tool.error instanceof ToolCancelledError
-  const isCallError = tool.status === "error" && !isCancelled
-  const initialViewData = tool.status === "ready" ? (tool.toolOutput as ViewData) : undefined
-
-  // Hosts that strip `structuredContent` (claude.ai) never latch a result under
-  // mcp-use 2.x; the recovery re-executes the call once to fill the gap. It
-  // never fires on a cancelled or failed call (#176): those render their state.
-  const recovery = useToolResultRecovery<ViewData>({
-    resultReady: !isPending,
-    cancelled: isCancelled,
-    errored: isCallError,
-    props: initialViewData,
-    isValid: isCompleteViewData,
-    toolInput: tool.toolInput,
-    hostContext,
-    callTool,
-  })
-  const [viewData, setViewData] = useHostViewData(initialViewData, isPending, recovery.data)
+  const shown = useShownView(call, callTool, recoverStrippedResult, strippedResultGraceMs)
+  const { view, setView } = shown
+  const viewData = view.data
   const { lifecycle, retry: retryCall } = useViewLifecycle({
     hasViewData: viewData !== null,
-    callStatus: tool.status,
-    cancelled: isCancelled,
-    callError: isCallError ? tool.error : undefined,
-    recoveryFailed: recovery.failed,
-    toolName: resolveRecoveryToolName(hostContext),
-    toolInput: tool.toolInput,
+    callStatus: call.tool.status,
+    cancelled: call.isCancelled,
+    callError: call.callError,
+    recoveryFailed: shown.recoveryFailed,
+    recoveryBlocked: shown.recoveryBlocked,
+    toolWrites: call.toolWrites,
+    toolName: call.toolName,
+    toolInput: call.tool.toolInput,
     callTool,
     isValid: isCompleteViewData,
-    onResult: setViewData,
+    onResult: shown.showRetried,
     slowHintAfterMs,
   })
   const { frameRef, retry } = useRetryFocus(lifecycle.phase, retryCall)
   const { isRefreshing, refreshView } = useViewRefresh({
     viewData,
-    setViewData,
+    setViewData: shown.showRefreshed,
     callTool,
     refreshToolName,
     labels: L,
+    client: viewClient,
   })
   const fullscreen = useFullscreenToggle(L)
   // In-iframe build mode is purely a UI state — the LLM never sees the catalogue.
   const [buildMode, setBuildMode] = useState(false)
+  useBuildModeFocus(buildMode, frameRef)
   const exitBuildMode = useCallback(
     (commit?: BuilderCommit) => {
-      if (commit) setViewData((prev) => (prev ? applyBuilderCommit(prev, commit) : prev))
+      if (commit) setView((prev) => withBuilderCommit(prev, commit))
       setBuildMode(false)
     },
-    [setViewData],
+    [setView],
+  )
+  const viewContext = (
+    <ViewModelContext lifecycle={lifecycle} toolName={call.toolName} view={view} />
   )
 
   // `isPending` must not gate the render: on stripping hosts the latch stays
@@ -309,6 +422,7 @@ function McpAppViewShell({
   if (!viewData) {
     return (
       <div ref={frameRef} tabIndex={-1} data-slot="mcp-app-view" className="outline-hidden">
+        {viewContext}
         <ViewPlaceholder
           lifecycle={lifecycle}
           labels={L}
@@ -321,6 +435,7 @@ function McpAppViewShell({
 
   return (
     <div ref={frameRef} tabIndex={-1} data-slot="mcp-app-view" className="outline-hidden">
+      {viewContext}
       <main
         style={{
           // Fullscreen: the view owns the viewport and scrolls itself. Inline:
@@ -347,6 +462,7 @@ function McpAppViewShell({
           onRefresh={refreshView}
           onEnterBuildMode={() => setBuildMode(true)}
           onToggleFullscreen={fullscreen.toggle}
+          dataAsOf={formatDataAsOf(view.reloadedAt, formatLocale, timeZone)}
         />
 
         <StepErrors
@@ -358,7 +474,11 @@ function McpAppViewShell({
           onRetry={viewData._refreshParams ? () => void refreshView() : undefined}
         />
 
-        <AppQueryProvider callTool={callToolFn}>
+        <AppQueryProvider
+          callTool={callToolFn}
+          client={viewClient}
+          toolNameInQueryKey={toolNameInQueryKey}
+        >
           <ViewBody
             buildMode={buildMode}
             viewData={viewData}
@@ -372,3 +492,33 @@ function McpAppViewShell({
     </div>
   )
 }
+
+/** How the model line names the view's own re-load of the shown payload. */
+function reloadedByOf(source: ViewSource | null): "recovery" | "refresh" | "builder" {
+  if (source === "refresh" || source === "builder") return source
+  return "recovery"
+}
+
+/**
+ * The shown view with a builder commit applied (nothing to apply without
+ * data). A commit that carries the builder's live context shows figures the
+ * builder loaded itself (its catalogue call ran the steps again), so it is
+ * stamped like a refresh: the toolbar says when, and the model learns that
+ * they can differ from the result the chat answered from. A commit without a
+ * context keeps the shown figures, and with them their source and stamp.
+ */
+function withBuilderCommit(view: ShownView, commit: BuilderCommit): ShownView {
+  if (!view.data) return view
+  const data = applyBuilderCommit(view.data, commit)
+  if (!commit.context) return { ...view, data }
+  return { data, source: "builder", reloadedAt: reloadedAtOf("builder", Date.now(), false) }
+}
+
+/** The toolbar's "as of" time of a re-loaded payload, `undefined` for any other. */
+function formatDataAsOf(
+  reloadedAt: number | null,
+  locale: string,
+  timeZone: string | undefined,
+): string | undefined {
+  return reloadedAt === null ? undefined : formatClockTime(reloadedAt, locale, timeZone)
+}

package/src/app/mcp-toolkit-app.test.tsx

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from "vitest"
+import { mountMcpToolkitApp } from "./mcp-toolkit-app.js"
+
+/**
+ * The mount order behind K13 (toolkit#176): `mountMcpToolkitApp` installs the
+ * tool-result observer BEFORE `bootstrapView` connects the view to its host,
+ * so the observer sees the handshake and the view never mistakes a slow tool
+ * for a stripped result.
+ */
+
+const calls = vi.hoisted(() => ({ order: [] as string[] }))
+
+vi.mock(import("../lib/tool-result-observer.js"), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    installToolResultObserver: () => {
+      calls.order.push("installToolResultObserver")
+      return null
+    },
+  }
+})
+
+vi.mock(import("mcp-use/react"), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    bootstrapView: (() => {
+      calls.order.push("bootstrapView")
+    }) as unknown as typeof actual.bootstrapView,
+  }
+})
+
+describe("mountMcpToolkitApp", () => {
+  it("installs the tool-result observer before bootstrapView connects to the host", () => {
+    calls.order = []
+    mountMcpToolkitApp({ widgets: {} })
+    expect(calls.order).toEqual(["installToolResultObserver", "bootstrapView"])
+  })
+})

package/src/app/mcp-toolkit-app.tsx

@@ -1,5 +1,6 @@
 import { useLayoutEffect, type ReactNode } from "react"
 import { ThemeProvider, bootstrapView, useHostContext } from "mcp-use/react"
+import { installToolResultObserver } from "../lib/tool-result-observer.js"
 import { adoptHostFontVariables } from "../theme/host-fonts.js"
 import { McpAppView, type McpAppViewProps } from "./mcp-app-view.js"
 import { McpUseHostBridgeProvider } from "./mcp-use-host-bridge.js"
@@ -54,7 +55,12 @@ export function McpToolkitApp(props: McpAppViewProps) {
  *
  * `bootstrapView` owns the mount: it connects the ext-apps postMessage bridge
  * to the host, installs an error boundary, and auto-reports size changes
- * (replacing 1.x's `createRoot` + `McpUseProvider` pair).
+ * (replacing 1.x's `createRoot` + `McpUseProvider` pair). The tool-result
+ * observer goes in first, so it sees the whole host lifecycle from the
+ * handshake on: the view then tells a stripped result from a slow tool and
+ * never re-runs a call the host is still answering (toolkit#176). A custom
+ * shell under its own `bootstrapView` calls `installToolResultObserver()`
+ * before it for the same effect.
  *
  * ```tsx
  * // main.tsx of the widget bundle
@@ -62,5 +68,6 @@ export function McpToolkitApp(props: McpAppViewProps) {
  * ```
  */
 export function mountMcpToolkitApp(props: McpAppViewProps): void {
+  installToolResultObserver()
   bootstrapView({ default: () => <McpToolkitApp {...props} /> })
 }