@miragon/mcp-toolkit-ui 0.10.1 → 1.0.1

package/src/app/mcp-use-host-bridge.tsx

@@ -0,0 +1,164 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+import {
+  useDynamicTool,
+  useHostContext,
+  useOpenExternal,
+  useSendFollowUp,
+  useToolContext,
+  useViewState,
+  useViewTheme,
+} from "mcp-use/react"
+import { HostBridgeProvider, toHostBridge, type HostBridge } from "./host-bridge.js"
+
+/**
+ * `true` inside an mcp-use 2.x view — i.e. under a
+ * {@link McpUseHostBridgeProvider}, which itself only renders under a
+ * `bootstrapView`-mounted tree. Components that want to use `mcp-use/react`
+ * primitives (which throw outside a view) branch on this instead of probing
+ * mcp-use internals; see `adaptDataWidget`'s ModelContext handling.
+ */
+const McpUseViewContext = createContext(false)
+
+/** Whether the subtree runs inside an mcp-use view (see {@link McpUseViewContext}). */
+export function useIsInsideMcpUseView(): boolean {
+  return useContext(McpUseViewContext)
+}
+
+type DynamicCallTool = (name: string, args: Record<string, unknown>) => Promise<unknown>
+type BoundCall = (args: Record<string, unknown>) => Promise<unknown>
+
+/**
+ * Mounts one `useDynamicTool` handle and hands its stable `callTool` up to the
+ * pool. This rendered indirection exists because mcp-use 2.x has no public
+ * "call any tool by name" API — `useDynamicTool(name)` is fixed per hook
+ * instance, so a generic `(name, args)` caller needs one mounted hook per
+ * distinct name.
+ */
+function ToolBinder({
+  name,
+  onBind,
+}: {
+  name: string
+  onBind: (name: string, call: BoundCall) => void
+}): null {
+  const { callTool } = useDynamicTool<Record<string, unknown>, unknown>(name)
+  useEffect(() => {
+    onBind(name, callTool)
+  }, [name, callTool, onBind])
+  return null
+}
+
+/**
+ * A generic `(name, args)` tool caller over mcp-use 2.x's per-name hooks.
+ *
+ * The first call for a given name mounts a {@link ToolBinder} (one render
+ * tick) and resolves once its handle is bound; later calls hit the bound
+ * handle directly. Binders accumulate for the mount's lifetime — tool names in
+ * a view are a small closed set. Calls left waiting when the view unmounts
+ * never settle, which is moot because their callers unmounted with it.
+ */
+function useDynamicToolPool(): { callTool: DynamicCallTool; binders: ReactNode } {
+  const [names, setNames] = useState<readonly string[]>([])
+  const boundRef = useRef(new Map<string, BoundCall>())
+  const waitersRef = useRef(new Map<string, ((call: BoundCall) => void)[]>())
+
+  const onBind = useCallback((name: string, call: BoundCall) => {
+    boundRef.current.set(name, call)
+    const waiters = waitersRef.current.get(name)
+    if (!waiters) return
+    waitersRef.current.delete(name)
+    for (const resolve of waiters) resolve(call)
+  }, [])
+
+  const callTool = useCallback<DynamicCallTool>((name, args) => {
+    const bound = boundRef.current.get(name)
+    if (bound) return bound(args)
+    const pending = new Promise<BoundCall>((resolve) => {
+      const waiters = waitersRef.current.get(name) ?? []
+      waiters.push(resolve)
+      waitersRef.current.set(name, waiters)
+    })
+    setNames((prev) => (prev.includes(name) ? prev : [...prev, name]))
+    return pending.then((call) => call(args))
+  }, [])
+
+  const binders = useMemo(
+    () => names.map((name) => <ToolBinder key={name} name={name} onBind={onBind} />),
+    [names, onBind],
+  )
+
+  return { callTool, binders }
+}
+
+/**
+ * Install the `mcp-use` {@link HostBridge} (plus the view-scope flag) for a
+ * subtree inside an mcp-use 2.x view.
+ *
+ * Composes the 2.x view hooks into the `McpUseWidgetSurface` shape and maps it
+ * through {@link toHostBridge}, so the fail-soft bridge contract widgets rely
+ * on is exactly the pinned one:
+ *
+ * - `callTool` — the dynamic-tool pool above; resolves with the raw
+ *   `CallToolResult` envelope, rejects on tool errors.
+ * - `sendFollowup` / `openExternal` — `useSendFollowUp` / `useOpenExternal`;
+ *   while the bridge is not connected (local `file://` preview), `openExternal`
+ *   throws into `toHostBridge`'s documented `window.open` fallback.
+ * - `setModelContext` — writes `{ __model_context }` into the view state,
+ *   which hosts receive via `ui/update-model-context` (ext-apps) or
+ *   `widgetState` (ChatGPT). The key is a toolkit-owned convention since 2.x.
+ * - `getWidgetData` — the rendering tool's `structuredContent` once ready.
+ *
+ * Must render inside a `bootstrapView`-mounted tree (the mcp-use hooks throw
+ * otherwise) — `McpToolkitApp` does this for the standard bundle; use it
+ * directly only when composing a custom shell under `bootstrapView`.
+ */
+export function McpUseHostBridgeProvider({ children }: { children: ReactNode }): ReactNode {
+  const { callTool, binders } = useDynamicToolPool()
+  const sendFollowUp = useSendFollowUp()
+  const openExternal = useOpenExternal()
+  const tool = useToolContext()
+  const theme = useViewTheme()
+  const { isAvailable } = useHostContext()
+  const [, setViewState] = useViewState<Record<string, unknown>>({})
+
+  const output = tool.status === "ready" ? tool.toolOutput : undefined
+
+  const bridge = useMemo<HostBridge>(
+    () =>
+      toHostBridge({
+        callTool,
+        sendFollowUpMessage: (prompt) => sendFollowUp({ prompt }),
+        openExternal: (url) => {
+          // Not connected (e.g. the bundle opened straight in a browser):
+          // throw synchronously so toHostBridge's window.open fallback fires.
+          if (!isAvailable) throw new Error("mcp-use view bridge is not connected")
+          void openExternal({ url }).catch((err: unknown) => {
+            console.warn("[host-bridge] openExternal failed:", err)
+          })
+        },
+        output,
+        theme,
+        setState: (state) => {
+          setViewState((prev) => ({ ...prev, ...state }))
+          return Promise.resolve()
+        },
+      }),
+    [callTool, sendFollowUp, openExternal, output, theme, isAvailable, setViewState],
+  )
+
+  return (
+    <McpUseViewContext.Provider value={true}>
+      {binders}
+      <HostBridgeProvider bridge={bridge}>{children}</HostBridgeProvider>
+    </McpUseViewContext.Provider>
+  )
+}

package/src/app/use-host-actions.tsx

@@ -53,12 +53,12 @@ export function buildShowWidgetIntent(toolName: string, description: string): st
  * because they cross the UI→chat boundary for different reasons — see above).
  *
  * Relationship to {@link useHostBridge}: this hook resolves the active bridge
- * through `useHostBridge()`, so it honours an explicit `HostBridgeProvider`
- * (ChatGPT / standalone) when one is present, and otherwise falls back to the
- * default `mcp-use` bridge — exactly the behaviour widgets had before the bridge
- * abstraction existed, so no existing widget or test breaks. Prefer
- * `useHostBridge` directly in new portable widgets; `useHostActions` stays for
- * its named affordances and backward compatibility.
+ * through `useHostBridge()`, so it uses whatever the nearest
+ * `HostBridgeProvider` supplies — the toolkit shell installs the `mcp-use`
+ * bridge via `McpUseHostBridgeProvider`, ChatGPT / standalone mounts wrap
+ * their root themselves — and, like `useHostBridge`, it throws when no
+ * provider is present. Prefer `useHostBridge` directly in new portable
+ * widgets; `useHostActions` stays for its named affordances.
  */
 export function useHostActions(): HostActions {
   const bridge = useHostBridge()

package/src/app/widget-fixture.tsx

@@ -1,26 +1,8 @@
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useSyncExternalStore,
-  type ComponentType,
-  type ReactNode,
-} from "react"
-import { useWidget } from "mcp-use/react"
+import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from "react"
 import type { PipelineContext, StepResult, WidgetProps } from "@miragon/mcp-toolkit-core"
 import { AppQueryProvider } from "../providers/query-provider.js"
 import { HostBridgeProvider, createStandaloneHostBridge } from "./host-bridge.js"
 
-/**
- * Key `mcp-use` writes the serialized model-context string under when it flushes
- * to `window.openai.setWidgetState`. Mirrors `MODEL_CONTEXT_KEY` in
- * `mcp-use/react` (not exported, so duplicated here). The harness intercepts
- * `setWidgetState` and reads this field to surface what the model would see.
- */
-const MODEL_CONTEXT_KEY = "__model_context"
-
 /**
  * Minimal shape of a tool-call response the harness hands back to widgets.
  * Mirrors `mcp-use`'s `CallToolResponse` closely enough that both the toolkit's
@@ -132,8 +114,11 @@ function toToolResult(raw: unknown): FixtureToolResult {
 
 /**
  * A host action a widget asked the host to perform, surfaced to the harness so
- * it can render an activity log. Mirrors the `mcp-use` bridge verbs that
- * {@link useHostActions} and `useWidget` route through `window.openai`.
+ * it can render an activity log. The `HostBridge` verbs (`callTool`,
+ * `sendFollowup`, `openExternal`) fire in the harness; `requestDisplayMode` /
+ * `setWidgetState` remain in the union for log-renderer compatibility but no
+ * longer fire — they belonged to the 1.x `window.openai` shim this harness
+ * used to install.
  */
 export type HostActionLog =
   | { type: "callTool"; name: string; args: Record<string, unknown> }
@@ -158,9 +143,10 @@ export function useFixtureHost(): FixtureHostValue | null {
 }
 
 /**
- * Default host-context globals a widget sees in the harness. Chosen to be
- * harmless and inert: inline display, light theme, desktop, no safe-area
- * insets. Overridable per-mount via {@link WidgetFixtureHostProps.globals}.
+ * Default host-context values the harness reports. Only `theme` is read since
+ * the mcp-use 2.x move (the other host globals were consumed by the 1.x
+ * `window.openai` shim); the object keeps its shape so existing playground
+ * setups that spread overrides keep compiling.
  */
 const DEFAULT_GLOBALS = {
   theme: "light",
@@ -174,67 +160,6 @@ const DEFAULT_GLOBALS = {
   },
 } as const
 
-/**
- * Build the `window.openai` shim the `mcp-use` React hooks read from. Routes
- * `callTool` through the fixture registry and reports every other bridge verb
- * to `onHostAction`. Returns `null` outside a browser-like environment (SSR)
- * so the harness degrades to a plain render rather than throwing.
- */
-function buildOpenAiShim(
-  registry: FixtureCallToolRegistry,
-  toolOutput: Record<string, unknown> | null,
-  toolInput: Record<string, unknown>,
-  globals: Record<string, unknown>,
-  onHostAction?: (action: HostActionLog) => void,
-  onModelContext?: (text: string) => void,
-): Record<string, unknown> | null {
-  if (typeof window === "undefined") return null
-  return {
-    ...DEFAULT_GLOBALS,
-    ...globals,
-    toolInput,
-    toolOutput,
-    toolResponseMetadata: null,
-    widgetState: null,
-    callTool: async (name: string, args: Record<string, unknown>) => {
-      onHostAction?.({ type: "callTool", name, args })
-      return registry.call(name, args)
-    },
-    sendFollowUpMessage: (args: { prompt: string }) => {
-      onHostAction?.({ type: "sendFollowUpMessage", prompt: args.prompt })
-      return Promise.resolve()
-    },
-    openExternal: (payload: { href: string }) => {
-      onHostAction?.({ type: "openExternal", href: payload.href })
-    },
-    requestDisplayMode: (args: { mode: string }) => {
-      onHostAction?.({ type: "requestDisplayMode", mode: args.mode })
-      return Promise.resolve({ mode: args.mode })
-    },
-    setWidgetState: (state: Record<string, unknown>) => {
-      onHostAction?.({ type: "setWidgetState", state })
-      // `mcp-use` flushes the serialized `<ModelContext>` tree through
-      // setWidgetState under MODEL_CONTEXT_KEY — surface it as the model view.
-      const ctx = state?.[MODEL_CONTEXT_KEY]
-      if (typeof ctx === "string") onModelContext?.(ctx)
-      return Promise.resolve()
-    },
-    notifyIntrinsicHeight: () => Promise.resolve(),
-  }
-}
-
-/**
- * Renders nothing but mounts a `useWidget()` so `mcp-use` registers its
- * model-context flush handler — even for widgets that never call `useWidget`
- * themselves (e.g. a simple `({ keys })` card). Without this, a widget's
- * `<ModelContext>` would render but never flush, and `onModelContext` would
- * stay silent. The flush routes through our `setWidgetState` shim above.
- */
-function ModelContextPump(): null {
-  useWidget()
-  return null
-}
-
 /**
  * Either an `adaptDataWidget`-style component (receives {@link WidgetProps}) or
  * a "raw" single-data component (`({ data }) | ({ keys })`). The harness builds
@@ -262,13 +187,14 @@ export interface WidgetFixtureHostProps {
   dataType?: string
   /**
    * Tool fixtures keyed by tool name. Each value is a static result or a
-   * handler — see {@link FixtureToolEntry}. Drives both `mcp-use`'s
-   * `useCallTool` and the toolkit's `useToolQuery`.
+   * handler — see {@link FixtureToolEntry}. Drives the simulated
+   * `HostBridge.callTool` and the toolkit's `useToolQuery`.
    */
   tools?: Record<string, FixtureToolEntry>
   /**
-   * Host context globals to override (theme, displayMode, locale, …). Merged
-   * over {@link DEFAULT_GLOBALS}.
+   * Host context overrides, merged over {@link DEFAULT_GLOBALS}. Since the
+   * mcp-use 2.x move only `theme` influences the simulated host; the other
+   * keys are accepted for compatibility with existing playground setups.
    */
   globals?: Record<string, unknown>
   /**
@@ -313,25 +239,24 @@ export function buildFixtureWidgetProps(
  * without booting a real MCP host or backend.
  *
  * ### What it mocks
- * - **`window.openai`** — the `mcp-use` Apps-SDK bridge `useWidget`/`useCallTool`
- *   read from. Installed on mount, removed on unmount. `callTool` is routed to a
- *   {@link FixtureCallToolRegistry} built from `tools`; `sendFollowUpMessage`,
- *   `openExternal`, etc. are reported to `onHostAction`.
+ * - **A {@link HostBridge}** — a `createStandaloneHostBridge` over the fixture
+ *   registry and callbacks, provided via `HostBridgeProvider`. `callTool`
+ *   resolves against the {@link FixtureCallToolRegistry} built from `tools`;
+ *   `sendFollowup` / `openExternal` are reported to `onHostAction`;
+ *   `setModelContext` feeds `onModelContext`, so you can *see* what the model
+ *   would (adapted widgets report through this bridge outside a real view).
  * - **The toolkit `AppQueryProvider`** — so widgets that fetch via `useToolQuery`
  *   (e.g. generated `use*` hooks) resolve against the same registry.
- * - **`ModelContext`** — a flush handler captures the serialized context string
- *   and forwards it to `onModelContext`, so you can *see* what the model would.
- * - **A {@link HostBridge}** — a `createStandaloneHostBridge` over the same
- *   registry and callbacks, provided via `HostBridgeProvider`, so widgets
- *   written against `useHostBridge` (the host-portable pattern) are simulated
- *   from the same single source as the `window.openai` shim above.
  *
  * ### Boundaries
- * `mcp-use`'s hooks select their provider from `window.openai` presence; this
- * harness deliberately drives the Apps-SDK path (sets `window.openai`) rather
- * than the `postMessage` bridge, which only activates inside a cross-origin
- * iframe. The shim is intentionally minimal — it is not a host, and host
- * features beyond the bridge verbs above are out of scope.
+ * The harness simulates the **host-portable pattern** (`useHostBridge`,
+ * `useToolQuery`) — the surface the toolkit's skills teach. It does not
+ * simulate the mcp-use 2.x view runtime: since 2.x the `mcp-use/react` hooks
+ * only run under a `bootstrapView`-mounted view speaking the ext-apps
+ * postMessage protocol (the 1.x `window.openai` shim this harness used to
+ * install has no equivalent seam). A widget that calls `mcp-use/react` hooks
+ * directly must be exercised against a real host — or rewritten against
+ * `useHostBridge`, which is the portable contract anyway.
  */
 export function WidgetFixtureHost({
   widget: Widget,
@@ -346,54 +271,20 @@ export function WidgetFixtureHost({
   // edits in the playground take effect without a full remount.
   const registry = useMemo(() => new FixtureCallToolRegistry(tools), [tools])
 
-  // Latest callbacks without re-installing the shim on every render. Updated in
-  // an effect (not during render) so the shim's closures always see the newest
-  // handler while the `window.openai` install effect stays stable.
-  const onHostActionRef = useRef(onHostAction)
-  const onModelContextRef = useRef(onModelContext)
-  useEffect(() => {
-    onHostActionRef.current = onHostAction
-    onModelContextRef.current = onModelContext
-  })
-
   const widgetProps = useMemo(() => buildFixtureWidgetProps(data, dataType), [data, dataType])
 
-  // Install the `window.openai` shim for the lifetime of this mount. Wake any
-  // already-mounted `mcp-use` hooks via the `set_globals` event they listen for.
-  useEffect(() => {
-    if (typeof window === "undefined") return
-    const shim = buildOpenAiShim(
-      registry,
-      data ?? null,
-      data ?? {},
-      globals ?? {},
-      (action) => onHostActionRef.current?.(action),
-      (text) => onModelContextRef.current?.(text),
-    )
-    if (!shim) return
-    const prev = (window as { openai?: unknown }).openai
-    ;(window as { openai?: unknown }).openai = shim
-    window.dispatchEvent(new CustomEvent("openai:set_globals", { detail: { globals: shim } }))
-    return () => {
-      ;(window as { openai?: unknown }).openai = prev
-    }
-  }, [registry, data, globals])
-
   const callTool = useMemo(
     () => async (name: string, args: object) =>
       registry.call(name, (args as Record<string, unknown>) ?? {}),
     [registry],
   )
 
-  // A standalone host bridge over the same registry + callbacks, so portable
-  // widgets written against `useHostBridge` (rather than the `mcp-use` host
-  // hooks) are simulated from the *same* source as the `window.openai` shim.
-  // It logs through the same `HostActionLog` channel, so the playground's
-  // activity log shows tool calls, follow-ups, and links identically whether the
-  // widget uses the mcp-use path or the host bridge. Reading globals.theme keeps
-  // the bridge's reported theme in sync with the shim. Depends on the callback
-  // props directly (not the refs) — a fresh Provider value on callback change is
-  // fine for a dev harness, and keeps the bridge's closures pure of ref reads.
+  // The standalone host bridge is the harness's single simulation source: it
+  // logs every verb through the `HostActionLog` channel for the playground's
+  // activity log. Depends on the callback props directly — a fresh Provider
+  // value on callback change is fine for a dev harness. Only `globals.theme`
+  // still influences the simulated host (the remaining globals fed the 1.x
+  // `window.openai` shim).
   const bridgeTheme = (globals?.theme ?? DEFAULT_GLOBALS.theme) === "dark" ? "dark" : "light"
   const bridge = useMemo(
     () =>
@@ -413,24 +304,12 @@ export function WidgetFixtureHost({
 
   const value = useMemo<FixtureHostValue>(() => ({ registry }), [registry])
 
-  // Mount the model-context pump only on the client. The pump calls `mcp-use`'s
-  // `useWidget`, whose `useSyncExternalStore` lacks a server snapshot and throws
-  // under `react-dom/server` — gating it keeps the harness (and any widget
-  // rendered through it) SSR-safe. `useSyncExternalStore` with a `false` server
-  // snapshot is the idiomatic "are we on the client?" check (no setState-in-effect).
-  const isClient = useSyncExternalStore(
-    () => () => {},
-    () => true,
-    () => false,
-  )
-
   // Spread `widgetProps` (keys/context) AND a `data` alias so both adapted
   // widgets and raw `({ data })` widgets read their fixture from one mount.
   const RenderWidget = Widget as ComponentType<Record<string, unknown>>
 
   return (
     <FixtureHostContext.Provider value={value}>
-      {isClient && <ModelContextPump />}
       <HostBridgeProvider bridge={bridge}>
         <AppQueryProvider callTool={callTool}>
           <RenderWidget {...widgetProps} data={data} />

package/src/hooks/use-tool-result-recovery.ts

@@ -4,38 +4,64 @@ import { parseToolResult } from "../lib/parse-tool-result.js"
 /**
  * Recovery for hosts that deliver the `ui/notifications/tool-result`
  * notification without `structuredContent` (observed on claude.ai and Claude
- * Desktop, which forward only the model-facing `content` blocks). The
- * mcp-use bridge then hands the widget an empty props object and the shell
- * would idle on its loading skeleton forever.
+ * Desktop, which forward only the model-facing `content` blocks). Since
+ * mcp-use 2.x such a result is not even observable: the `useToolContext`
+ * latch ignores content-only successes, so the tool status stays `"pending"`
+ * forever and the shell would idle on its loading skeleton.
  *
- * When the result is ready but the payload is invalid, the hook re-executes
- * the originating tool once via the host bridge's official `callTool` —
- * tool-call RESPONSES carry `structuredContent` intact on those hosts — and
- * exposes the decoded payload. Spec-conforming hosts (e.g. the mcp-use
- * inspector) deliver a valid payload up front, so the recovery never fires
- * there.
+ * Because the stripped notification is invisible, readiness is inferred two
+ * ways: the hard `resultReady` signal (the latch fired but the payload is
+ * invalid), or a grace timer — once the originating tool is known and no
+ * result has latched within
+ * {@link ToolResultRecoveryOptions.assumeStrippedAfterMs}, the result is
+ * assumed delivered-but-stripped. Either way the hook re-executes the
+ * originating tool once via the host bridge's official `callTool` — tool-call
+ * RESPONSES carry `structuredContent` intact on those hosts — and exposes the
+ * decoded payload. Spec-conforming hosts (e.g. the mcp-use inspector) deliver
+ * a valid payload up front, so the recovery never fires there.
  *
  * Assumes the originating tool is a read-only render pipeline (true for all
  * toolkit `render-view`/`show_*` tools) — the re-execution must be safe to
- * repeat.
+ * repeat, and may rarely run concurrently with the original invocation when
+ * the grace timer beats a slow but conforming host.
  */
 
+/**
+ * Default grace period before a silent latch counts as a stripped result.
+ * Long enough for a conforming host to latch a typical render tool first,
+ * short enough that users on stripping hosts are not left staring at the
+ * skeleton noticeably.
+ */
+export const DEFAULT_ASSUME_STRIPPED_AFTER_MS = 2500
+
 export interface ToolResultRecoveryOptions {
-  /** `!isPending` from `useWidget` — the host reported a finished tool call. */
+  /**
+   * The latch fired (`useToolContext().status !== "pending"`) — a structured
+   * result or tool error arrived. On hosts that strip `structuredContent`
+   * this never turns true; the grace timer below covers that case.
+   */
   resultReady: boolean
-  /** The props the host delivered (`useWidget().props`). */
+  /** The payload the host delivered (`useToolContext().toolOutput`). */
   props: unknown
   /**
    * Validates a candidate payload. MUST be referentially stable (module-level
    * function or memoised) — it is an effect dependency.
    */
   isValid: (value: unknown) => boolean
-  /** The tool arguments from `ui/notifications/tool-input` (`useWidget().toolInput`). */
+  /** The tool arguments from `ui/notifications/tool-input` (`useToolContext().toolInput`). */
   toolInput: Record<string, unknown> | null | undefined
-  /** Raw host context (`useWidget().hostContext`); `toolInfo` names the originating tool. */
+  /** Raw host context (`useHostContext().hostContext`); `toolInfo` names the originating tool. */
   hostContext: Record<string, unknown> | null | undefined
-  /** The bridge's `callTool` (`useWidget().callTool`). */
+  /** The host bridge's `callTool`. */
   callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+  /**
+   * Grace period in ms after which a silent latch counts as a stripped
+   * result. Armed once the originating tool is known while `resultReady` is
+   * still false; re-armed on every `toolInput` update, because streaming
+   * arguments mean the invocation may not have finished yet. Defaults to
+   * {@link DEFAULT_ASSUME_STRIPPED_AFTER_MS}.
+   */
+  assumeStrippedAfterMs?: number
 }
 
 export interface ToolResultRecoveryState<T> {
@@ -89,7 +115,15 @@ export function decodeRecoveredResult<T>(
 export function useToolResultRecovery<T>(
   options: ToolResultRecoveryOptions,
 ): ToolResultRecoveryState<T> {
-  const { resultReady, props, isValid, toolInput, hostContext, callTool } = options
+  const {
+    resultReady,
+    props,
+    isValid,
+    toolInput,
+    hostContext,
+    callTool,
+    assumeStrippedAfterMs = DEFAULT_ASSUME_STRIPPED_AFTER_MS,
+  } = options
   const [state, setState] = useState<ToolResultRecoveryState<T>>(IDLE)
   // Single-flight: the promise ref survives StrictMode's dev-mode
   // effect re-run (cleanup + setup on the same instance), so the re-run
@@ -99,16 +133,38 @@ export function useToolResultRecovery<T>(
 
   const toolName = resolveRecoveryToolName(hostContext)
 
+  // A stripped result is unobservable (the 2.x latch ignores content-only
+  // results), so infer it: once a recovery could fire but the latch has been
+  // silent for the grace period, treat the result as delivered-but-stripped.
+  // Re-armed on every toolInput identity change — streaming arguments mean
+  // the invocation may still be running, so the grace period starts over.
+  // The re-arm is a render-phase reset (not an effect) so the cascading-
+  // render lint stays satisfied; the timer effect below restarts anyway
+  // because toolInput is one of its dependencies.
+  const [assumedReady, setAssumedReady] = useState(false)
+  const [prevTimerInput, setPrevTimerInput] = useState<unknown>(toolInput)
+  if (prevTimerInput !== toolInput) {
+    setPrevTimerInput(toolInput)
+    if (assumedReady) setAssumedReady(false)
+  }
+  useEffect(() => {
+    if (resultReady || toolName === undefined) return
+    const timer = setTimeout(() => setAssumedReady(true), assumeStrippedAfterMs)
+    return () => clearTimeout(timer)
+  }, [resultReady, toolName, toolInput, assumeStrippedAfterMs])
+
+  const ready = resultReady || assumedReady
+
   useEffect(() => {
     // A new tool run (result no longer ready, or fresh tool-input identity)
     // invalidates any previous recovery attempt and re-arms the single-flight.
-    if (flightRef.current && (!resultReady || flightInputRef.current !== toolInput)) {
+    if (flightRef.current && (!ready || flightInputRef.current !== toolInput)) {
       flightRef.current = null
       setState((prev) => (prev.data === null && !prev.failed ? prev : IDLE))
     }
     // Never fire on conforming hosts (valid payload) or before the
     // originating tool is known.
-    if (!resultReady || isValid(props) || toolName === undefined) return
+    if (!ready || isValid(props) || toolName === undefined) return
 
     if (!flightRef.current) {
       flightInputRef.current = toolInput
@@ -138,7 +194,7 @@ export function useToolResultRecovery<T>(
     return () => {
       stale = true
     }
-  }, [resultReady, props, isValid, toolName, toolInput, callTool])
+  }, [ready, props, isValid, toolName, toolInput, callTool])
 
   return state
 }

package/src/index.ts

@@ -126,7 +126,7 @@ export type { LocaleContextValue, LocaleProviderProps, BoundTranslate } from "./
 // NOTE: MCP App shell (McpAppView, WidgetRenderer) is exported from the
 // `./app` subpath only. Keeping it out of the main barrel prevents consumers
 // that only need primitives (e.g. an admin portal) from pulling `mcp-use/react`
-// and its langchain transitive peer into their Vite bundle.
+// — the 2.x view runtime and its ext-apps transitive — into their Vite bundle.
 
 // Utils
 export { cn } from "./lib/utils.js"