@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/dist/hooks/use-tool-result-recovery.d.ts

@@ -1,48 +1,49 @@
+import { type ToolResultObserver } from "../lib/tool-result-observer.js";
+import { type RecoveryPolicy, type ToolResultRecoveryState } from "./tool-result-recovery-model.js";
+export { decodeRecoveredResult } from "./tool-result-recovery-model.js";
+export type { RecoveryBlockReason, RecoveryPolicy, ToolResultRecoveryState, ToolSafety, } from "./tool-result-recovery-model.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). 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.
+ * Desktop, which forward only the model-facing `content` blocks). mcp-use
+ * 2.x's `useToolContext` latch ignores such a content-only result, so its
+ * status stays `"pending"` forever and the shell would idle on its skeleton.
  *
- * 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.
+ * The hook re-executes the originating tool once via the host bridge's
+ * `callTool` — tool-call RESPONSES carry `structuredContent` intact on those
+ * hosts — and exposes the decoded payload. When it does so (toolkit#176):
  *
- * A call the host cancelled is never recovered: since mcp-use 2.7.1 the
- * cancellation latches as `status: "error"` (a `ToolCancelledError`), which
- * would otherwise count as a ready-but-invalid result — re-executing it would
- * override the user's decision to stop the call. Neither is a call that
- * failed (`isError` or a transport error, {@link ToolResultRecoveryOptions.errored}):
- * re-running it only repeats the failure, so the shell renders the error and
- * offers an explicit retry instead (toolkit#176).
+ * - **Only when the host stripped the result.** A passive observer of the
+ *   host's lifecycle notifications (`installToolResultObserver`) sees the
+ *   content-only result itself, so the recovery fires as it arrives, and a
+ *   slow tool on a compliant host is never re-run (K13): no result has
+ *   arrived because none was sent. Where the observer cannot vouch for that
+ *   (no browser frame, or installed after the handshake), the 2.x grace timer
+ *   ({@link ToolResultRecoveryOptions.assumeStrippedAfterMs}) still infers a
+ *   stripped result, once the call's arguments arrived.
+ * - **With the call's complete arguments** (N21): the observer's complete
+ *   `tool-input`, never a partial stream; an equal re-delivery is the same run.
+ * - **Never for a cancelled or failed call:** re-running repeats the failure
+ *   or overrides the user's stop; the shell renders that state and offers an
+ *   explicit retry.
+ * - **Only for a tool the policy allows** ({@link ToolResultRecoveryOptions.policy}):
+ *   by default never one the host reports as writing (`readOnlyHint: false`
+ *   or `destructiveHint: true` in `hostContext.toolInfo.tool.annotations`).
+ *   A blocked recovery is reported (`blocked`) so the view can show its error.
  *
- * 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, and may rarely run concurrently with the original invocation when
- * the grace timer beats a slow but conforming host.
+ * The decision and its timer live in `createRecoveryController`; this hook
+ * only binds it to React.
  */
 /**
- * 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.
+ * Default grace period before a silent latch counts as a stripped result —
+ * used only where the transport observer cannot vouch that nothing arrived.
  */
 export declare const DEFAULT_ASSUME_STRIPPED_AFTER_MS = 2500;
 export interface ToolResultRecoveryOptions {
     /**
      * The latch fired (`useToolContext().status !== "pending"`) — a structured
      * result, a tool error, or a host cancellation arrived. On hosts that strip
-     * `structuredContent` this never turns true; the grace timer below covers
-     * that case.
+     * `structuredContent` this never turns true.
      */
     resultReady: boolean;
     /**
@@ -61,10 +62,7 @@ export interface ToolResultRecoveryOptions {
     errored?: boolean;
     /** 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.
-     */
+    /** Validates a candidate payload. */
     isValid: (value: unknown) => boolean;
     /** The tool arguments from `ui/notifications/tool-input` (`useToolContext().toolInput`). */
     toolInput: Record<string, unknown> | null | undefined;
@@ -74,18 +72,19 @@ export interface ToolResultRecoveryOptions {
     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
+     * result. Applies only where the transport observer cannot vouch that no
+     * result arrived (see above); restarts for new arguments. Defaults to
      * {@link DEFAULT_ASSUME_STRIPPED_AFTER_MS}.
      */
     assumeStrippedAfterMs?: number;
-}
-export interface ToolResultRecoveryState<T> {
-    /** The recovered payload, `null` until the re-execution resolved (or when it failed). */
-    data: T | null;
-    /** `true` when the single recovery attempt failed — the shell keeps its skeleton, no retry loop. */
-    failed: boolean;
+    /** Which tools may be re-executed on their own. Default `"auto"`. */
+    policy?: RecoveryPolicy;
+    /**
+     * The transport observer. Defaults to the document's
+     * (`installToolResultObserver()`); `null` disables it, leaving the grace
+     * timer to decide alone (the 2.x behaviour).
+     */
+    observer?: ToolResultObserver | null;
 }
 /**
  * Resolves the originating tool name from the host context's `toolInfo`.
@@ -94,14 +93,10 @@ export interface ToolResultRecoveryState<T> {
  */
 export declare function resolveRecoveryToolName(hostContext: unknown): string | undefined;
 /**
- * Decodes a re-executed tool result and validates it. Exposed for tests;
- * the hook uses it on the `callTool` response.
- */
-export declare function decodeRecoveredResult<T>(result: unknown, isValid: (value: unknown) => boolean): T | null;
-/**
- * Whether the recovery may fire: the result latched (or is assumed stripped)
- * and the call was neither cancelled nor failed. Exported for tests — this is
- * the #176 rule "never recover on an error status".
+ * Whether a latched or assumed-stripped result may be recovered at all: the
+ * call was neither cancelled nor failed. Kept for existing imports; the full
+ * rule (observer, policy, arguments) is `decideRecovery`.
+ * @deprecated Use `decideRecovery` from the recovery model.
  */
 export declare function isRecoveryReady(state: {
     resultReady: boolean;

package/dist/hooks/use-tool-result-recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-tool-result-recovery.d.ts","sourceRoot":"","sources":["../../src/hooks/use-tool-result-recovery.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,OAAO,CAAA;AAEpD,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACpC,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;IACrD,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;IACvD,oCAAoC;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3E;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,yFAAyF;IACzF,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,oGAAoG;IACpG,MAAM,EAAE,OAAO,CAAA;CAChB;AAID;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAehF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GACnC,CAAC,GAAG,IAAI,CAQV;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,WAAW,EAAE,OAAO,CAAA;IACpB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,OAAO,CAGV;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,yBAAyB,GACjC,uBAAuB,CAAC,CAAC,CAAC,CAwF5B"}
+{"version":3,"file":"use-tool-result-recovery.d.ts","sourceRoot":"","sources":["../../src/hooks/use-tool-result-recovery.ts"],"names":[],"mappings":"AACA,OAAO,EAA6B,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACnG,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AACvE,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,UAAU,GACX,MAAM,iCAAiC,CAAA;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;GAGG;AACH,eAAO,MAAM,gCAAgC,OAAO,CAAA;AAEpD,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAA;IACd,qCAAqC;IACrC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACpC,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;IACrD,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;IACvD,oCAAoC;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3E;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qEAAqE;IACrE,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAehF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,WAAW,EAAE,OAAO,CAAA;IACpB,YAAY,EAAE,OAAO,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;CACjB,GAAG,OAAO,CAGV;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,yBAAyB,GACjC,uBAAuB,CAAC,CAAC,CAAC,CAyC5B"}

package/dist/hooks/use-tool-result-recovery.js

@@ -1,45 +1,44 @@
-import { useEffect, useRef, useState } from "react";
-import { parseToolResult } from "../lib/parse-tool-result.js";
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { installToolResultObserver } from "../lib/tool-result-observer.js";
+import { createRecoveryController, } from "./tool-result-recovery-model.js";
+export { decodeRecoveredResult } from "./tool-result-recovery-model.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). 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.
+ * Desktop, which forward only the model-facing `content` blocks). mcp-use
+ * 2.x's `useToolContext` latch ignores such a content-only result, so its
+ * status stays `"pending"` forever and the shell would idle on its skeleton.
  *
- * 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.
+ * The hook re-executes the originating tool once via the host bridge's
+ * `callTool` — tool-call RESPONSES carry `structuredContent` intact on those
+ * hosts — and exposes the decoded payload. When it does so (toolkit#176):
  *
- * A call the host cancelled is never recovered: since mcp-use 2.7.1 the
- * cancellation latches as `status: "error"` (a `ToolCancelledError`), which
- * would otherwise count as a ready-but-invalid result — re-executing it would
- * override the user's decision to stop the call. Neither is a call that
- * failed (`isError` or a transport error, {@link ToolResultRecoveryOptions.errored}):
- * re-running it only repeats the failure, so the shell renders the error and
- * offers an explicit retry instead (toolkit#176).
+ * - **Only when the host stripped the result.** A passive observer of the
+ *   host's lifecycle notifications (`installToolResultObserver`) sees the
+ *   content-only result itself, so the recovery fires as it arrives, and a
+ *   slow tool on a compliant host is never re-run (K13): no result has
+ *   arrived because none was sent. Where the observer cannot vouch for that
+ *   (no browser frame, or installed after the handshake), the 2.x grace timer
+ *   ({@link ToolResultRecoveryOptions.assumeStrippedAfterMs}) still infers a
+ *   stripped result, once the call's arguments arrived.
+ * - **With the call's complete arguments** (N21): the observer's complete
+ *   `tool-input`, never a partial stream; an equal re-delivery is the same run.
+ * - **Never for a cancelled or failed call:** re-running repeats the failure
+ *   or overrides the user's stop; the shell renders that state and offers an
+ *   explicit retry.
+ * - **Only for a tool the policy allows** ({@link ToolResultRecoveryOptions.policy}):
+ *   by default never one the host reports as writing (`readOnlyHint: false`
+ *   or `destructiveHint: true` in `hostContext.toolInfo.tool.annotations`).
+ *   A blocked recovery is reported (`blocked`) so the view can show its error.
  *
- * 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, and may rarely run concurrently with the original invocation when
- * the grace timer beats a slow but conforming host.
+ * The decision and its timer live in `createRecoveryController`; this hook
+ * only binds it to React.
  */
 /**
- * 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.
+ * Default grace period before a silent latch counts as a stripped result —
+ * used only where the transport observer cannot vouch that nothing arrived.
  */
 export const DEFAULT_ASSUME_STRIPPED_AFTER_MS = 2500;
-const IDLE = { data: null, failed: false };
 /**
  * Resolves the originating tool name from the host context's `toolInfo`.
  * Reads the SEP-1865 shape first (`toolInfo.tool.name`), then the flattened
@@ -65,23 +64,10 @@ export function resolveRecoveryToolName(hostContext) {
     return undefined;
 }
 /**
- * Decodes a re-executed tool result and validates it. Exposed for tests;
- * the hook uses it on the `callTool` response.
- */
-export function decodeRecoveredResult(result, isValid) {
-    let decoded;
-    try {
-        decoded = parseToolResult(result);
-    }
-    catch {
-        return null;
-    }
-    return decoded !== null && isValid(decoded) ? decoded : null;
-}
-/**
- * Whether the recovery may fire: the result latched (or is assumed stripped)
- * and the call was neither cancelled nor failed. Exported for tests — this is
- * the #176 rule "never recover on an error status".
+ * Whether a latched or assumed-stripped result may be recovered at all: the
+ * call was neither cancelled nor failed. Kept for existing imports; the full
+ * rule (observer, policy, arguments) is `decideRecovery`.
+ * @deprecated Use `decideRecovery` from the recovery model.
  */
 export function isRecoveryReady(state) {
     if (state.cancelled || state.errored)
@@ -89,79 +75,31 @@ export function isRecoveryReady(state) {
     return state.resultReady || state.assumedReady;
 }
 export function useToolResultRecovery(options) {
-    const { resultReady, cancelled = false, errored = false, props, isValid, toolInput, hostContext, callTool, assumeStrippedAfterMs = DEFAULT_ASSUME_STRIPPED_AFTER_MS, } = options;
-    const [state, setState] = useState(IDLE);
-    // Single-flight: the promise ref survives StrictMode's dev-mode
-    // effect re-run (cleanup + setup on the same instance), so the re-run
-    // re-subscribes to the SAME in-flight call instead of firing a second one.
-    const flightRef = useRef(null);
-    const flightInputRef = useRef(null);
-    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(toolInput);
-    if (prevTimerInput !== toolInput) {
-        setPrevTimerInput(toolInput);
-        if (assumedReady)
-            setAssumedReady(false);
-    }
-    const suppressed = cancelled || errored;
+    const { resultReady, cancelled = false, errored = false, props, isValid, toolInput, hostContext, callTool, assumeStrippedAfterMs = DEFAULT_ASSUME_STRIPPED_AFTER_MS, policy = "auto", observer, } = options;
+    // One controller per mount; it survives StrictMode's effect re-run, so an
+    // in-flight call is never fired twice.
+    const [controller] = useState(() => createRecoveryController({
+        observer: observer === undefined ? installToolResultObserver() : observer,
+    }));
     useEffect(() => {
-        if (resultReady || suppressed || toolName === undefined)
-            return;
-        const timer = setTimeout(() => setAssumedReady(true), assumeStrippedAfterMs);
-        return () => clearTimeout(timer);
-    }, [resultReady, suppressed, toolName, toolInput, assumeStrippedAfterMs]);
-    // A cancelled or failed call never counts as ready, so the effect below
-    // invalidates any in-flight attempt the same way it does for a superseded run.
-    const ready = isRecoveryReady({ resultReady, assumedReady, cancelled, errored });
+        controller.start();
+        return () => controller.stop();
+    }, [controller]);
     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 && (!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 (!ready || isValid(props) || toolName === undefined)
-            return;
-        if (!flightRef.current) {
-            flightInputRef.current = toolInput;
-            flightRef.current = (async () => {
-                try {
-                    const result = await callTool(toolName, toolInput ?? {});
-                    const data = decodeRecoveredResult(result, isValid);
-                    if (data !== null)
-                        return { data, failed: false };
-                    console.warn(`[mcp-toolkit] tool-result recovery: re-executing "${toolName}" returned no usable payload`);
-                    return { data: null, failed: true };
-                }
-                catch (err) {
-                    console.warn(`[mcp-toolkit] tool-result recovery for "${toolName}" failed:`, err);
-                    return { data: null, failed: true };
-                }
-            })();
-        }
-        const flight = flightRef.current;
-        let stale = false;
-        void flight.then((outcome) => {
-            // Drop the outcome when this subscription was superseded or the flight
-            // was invalidated by a newer tool run.
-            if (!stale && flightRef.current === flight)
-                setState(outcome);
+        controller.update({
+            resultReady,
+            cancelled,
+            errored,
+            props,
+            isValid,
+            toolInput,
+            hostContext,
+            callTool,
+            policy,
+            graceMs: assumeStrippedAfterMs,
+            resolveToolName: resolveRecoveryToolName,
         });
-        return () => {
-            stale = true;
-        };
-    }, [ready, props, isValid, toolName, toolInput, callTool]);
-    return state;
+    });
+    return useSyncExternalStore(controller.subscribe, controller.getState, controller.getState);
 }
 //# sourceMappingURL=use-tool-result-recovery.js.map

package/dist/hooks/use-tool-result-recovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-tool-result-recovery.js","sourceRoot":"","sources":["../../src/hooks/use-tool-result-recovery.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"use-tool-result-recovery.js","sourceRoot":"","sources":["../../src/hooks/use-tool-result-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AACjE,OAAO,EAAE,yBAAyB,EAA2B,MAAM,gCAAgC,CAAA;AACnG,OAAO,EACL,wBAAwB,GAGzB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAQvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAA;AAkDpD;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAoB;IAC1D,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACrE,MAAM,IAAI,GAAI,WAAuC,CAAC,QAAQ,CAAA;IAC9D,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACvD,MAAM,GAAG,GAAG,IAA+B,CAAA;IAC3C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAA;IACrB,MAAM,UAAU,GAAG;QACjB,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAgC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACrF,GAAG,CAAC,IAAI;QACR,GAAG,CAAC,QAAQ;KACb,CAAA;IACD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,CAAA;IAC7E,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAK/B;IACC,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO;QAAE,OAAO,KAAK,CAAA;IAClD,OAAO,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,YAAY,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAAkC;IAElC,MAAM,EACJ,WAAW,EACX,SAAS,GAAG,KAAK,EACjB,OAAO,GAAG,KAAK,EACf,KAAK,EACL,OAAO,EACP,SAAS,EACT,WAAW,EACX,QAAQ,EACR,qBAAqB,GAAG,gCAAgC,EACxD,MAAM,GAAG,MAAM,EACf,QAAQ,GACT,GAAG,OAAO,CAAA;IACX,0EAA0E;IAC1E,uCAAuC;IACvC,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CACjC,wBAAwB,CAAI;QAC1B,QAAQ,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,yBAAyB,EAAE,CAAC,CAAC,CAAC,QAAQ;KAC1E,CAAC,CACH,CAAA;IACD,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,KAAK,EAAE,CAAA;QAClB,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,CAAA;IAChC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IAChB,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,MAAM,CAAC;YAChB,WAAW;YACX,SAAS;YACT,OAAO;YACP,KAAK;YACL,OAAO;YACP,SAAS;YACT,WAAW;YACX,QAAQ;YACR,MAAM;YACN,OAAO,EAAE,qBAAqB;YAC9B,eAAe,EAAE,uBAAuB;SACzC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACF,OAAO,oBAAoB,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;AAC7F,CAAC"}

package/dist/hooks/use-view-data.d.ts

@@ -1,25 +1,67 @@
+import { type UseToolQueryOptions } from "../lib/tool-query.js";
 export interface ViewDataResult<T> {
     data: T | null;
     /** True while self-fetching with no data yet — the first paint of a cockpit cell. */
     loading: boolean;
     error: Error | null;
     /**
-     * Fetch `tool` again: the retry of an error state
-     * (`<ErrorState onRetry={refetch} … />`). Host-pushed data, when present,
-     * stays what `data` returns.
+     * Fetch `tool` again now: the retry of an error state
+     * (`<ErrorState onRetry={refetch} … />`) or a manual refresh — a new read
+     * even while a failed fetch still waits on its retry backoff. In `"static"`
+     * mode host-pushed data, when present, stays what `data` returns.
      */
     refetch: () => void;
+    /** Failed attempts of the current fetch (0 once it succeeds). */
+    failureCount: number;
+    /**
+     * The current fetch's last failed attempt — set from the first failure on,
+     * while the query still retries (`error` waits for the last retry).
+     */
+    failureReason: Error | null;
+    /** A fetch is in flight (the first one or a refetch). */
+    isFetching: boolean;
+    /**
+     * `data` is a placeholder (`placeholderData`, e.g. `keepPreviousData`):
+     * the previous args' answer while the current args' fetch runs or failed.
+     */
+    isPlaceholderData: boolean;
 }
+/**
+ * How {@link useViewData} treats host-pushed `initialData`.
+ *
+ * - `"static"` (default): returned verbatim; the feed query stays off while
+ *   it is present.
+ * - `"seed"`: it becomes the feed query's cached answer, and the query stays
+ *   live (once `ready`): an invalidation after a write, a `refetch` or a
+ *   retry re-reads the feed. A fresh seed is not refetched on mount (it is
+ *   younger than `staleTime`); a payload delivered anew (content not seeded
+ *   for the key before) replaces the cached answer, while a re-rendered or
+ *   remounted old one never rolls a refetched answer back.
+ */
+export type ViewDataMode = "static" | "seed";
+/**
+ * Options of {@link useViewData}: TanStack's query options for the feed
+ * (`retry`, `retryDelay`, `staleTime`, `placeholderData` /
+ * `keepPreviousData`, `enabled` as an extra gate next to `ready`, …),
+ * plus how host data seeds it.
+ */
+export type UseViewDataOptions<T> = Omit<UseToolQueryOptions<T>, "initialData" | "select"> & {
+    initialDataMode?: ViewDataMode;
+};
 /**
  * The seam that lets one widget component serve both modes without a duplicate UI.
  *
  * Standalone (a `*_show_*` widget) the agent's tool result is handed in via
- * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`) and
- * returned verbatim. Embedded in a self-fetching cockpit only scope params are
- * passed, so the component fetches `tool` with `args` under `key` — disabled
- * unless data is absent AND `ready` (i.e. the required id/key is present).
- * Sibling widgets sharing `key` dedupe to a single call, so a composed view of
- * N widgets over one data feed fetches once.
+ * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`).
+ * Embedded in a self-fetching cockpit only scope params are passed, so the
+ * component fetches `tool` with `args` under `key`, gated on `ready` (i.e.
+ * the required id/key is present). Sibling widgets sharing `key` and `args`
+ * dedupe to a single call, so a composed view of N widgets over one data
+ * feed fetches once.
+ *
+ * By default host data is returned verbatim and switches the query off;
+ * `initialDataMode: "seed"` keeps the query live over it instead (see
+ * {@link ViewDataMode}). `options` passes TanStack's query options through.
  */
-export declare function useViewData<T>(initialData: T | null | undefined, key: ReadonlyArray<unknown>, tool: string, args: Record<string, unknown>, ready: boolean): ViewDataResult<T>;
+export declare function useViewData<T>(initialData: T | null | undefined, key: ReadonlyArray<unknown>, tool: string, args: Record<string, unknown>, ready: boolean, options?: UseViewDataOptions<T>): ViewDataResult<T>;
 //# sourceMappingURL=use-view-data.d.ts.map

package/dist/hooks/use-view-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-view-data.d.ts","sourceRoot":"","sources":["../../src/hooks/use-view-data.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB;;;;OAIG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,WAAW,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EACjC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,OAAO,GACb,cAAc,CAAC,CAAC,CAAC,CAQnB"}
+{"version":3,"file":"use-view-data.d.ts","sourceRoot":"","sources":["../../src/hooks/use-view-data.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAG9E,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;IACd,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,aAAa,EAAE,KAAK,GAAG,IAAI,CAAA;IAC3B,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC,GAAG;IAC3F,eAAe,CAAC,EAAE,YAAY,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,WAAW,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EACjC,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC9B,cAAc,CAAC,CAAC,CAAC,CA0BnB"}

package/dist/hooks/use-view-data.js

@@ -1,23 +1,88 @@
-import { useCallback } from "react";
-import { useToolQuery } from "./use-tool-query.js";
+import { useCallback, useState } from "react";
+import { hashKey, useQueryClient } from "@tanstack/react-query";
+import { seedToolQuery } from "../lib/tool-query.js";
+import { useToolQuery, useToolQueryKey } from "./use-tool-query.js";
 /**
  * The seam that lets one widget component serve both modes without a duplicate UI.
  *
  * Standalone (a `*_show_*` widget) the agent's tool result is handed in via
- * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`) and
- * returned verbatim. Embedded in a self-fetching cockpit only scope params are
- * passed, so the component fetches `tool` with `args` under `key` — disabled
- * unless data is absent AND `ready` (i.e. the required id/key is present).
- * Sibling widgets sharing `key` dedupe to a single call, so a composed view of
- * N widgets over one data feed fetches once.
+ * `initialData` (from the view's stepData, e.g. through `adaptDataWidget`).
+ * Embedded in a self-fetching cockpit only scope params are passed, so the
+ * component fetches `tool` with `args` under `key`, gated on `ready` (i.e.
+ * the required id/key is present). Sibling widgets sharing `key` and `args`
+ * dedupe to a single call, so a composed view of N widgets over one data
+ * feed fetches once.
+ *
+ * By default host data is returned verbatim and switches the query off;
+ * `initialDataMode: "seed"` keeps the query live over it instead (see
+ * {@link ViewDataMode}). `options` passes TanStack's query options through.
+ */
+export function useViewData(initialData, key, tool, args, ready, options) {
+    const { initialDataMode = "static", enabled, ...queryOptions } = options ?? {};
+    const seeding = initialDataMode === "seed";
+    const cacheKey = useStableKey(useToolQueryKey(key, tool, args));
+    useSeed(seeding ? initialData : null, cacheKey, queryOptions.initialDataUpdatedAt);
+    const active = ready && enabled !== false;
+    const fetches = active && (seeding || !initialData);
+    const query = useToolQuery([...key], tool, args, {
+        ...queryOptions,
+        enabled: typeof enabled === "function" ? (q) => fetches && enabled(q) : fetches,
+    });
+    const data = seeding ? (query.data ?? initialData) : (initialData ?? query.data);
+    const refetch = useFreshRefetch(cacheKey, query.refetch);
+    return {
+        data: data ?? null,
+        // The query's own verdict: a function `enabled` that returns false idles
+        // like `enabled: false`, never an endless skeleton.
+        loading: !data && query.isEnabled && !query.isError,
+        error: query.error,
+        refetch,
+        failureCount: query.failureCount,
+        failureReason: query.failureReason,
+        isFetching: query.isFetching,
+        isPlaceholderData: query.isPlaceholderData,
+    };
+}
+/** `key`, kept by content: callers build `key`/`args` anew every render. */
+function useStableKey(key) {
+    const id = hashKey(key);
+    const [stable, setStable] = useState({ id, key });
+    if (stable.id !== id)
+        setStable({ id, key });
+    return stable.id === id ? stable.key : key;
+}
+/**
+ * `"seed"` mode: write the host's payload into the feed's cache entry in the
+ * render phase, before the query's observer reads the cache — what TanStack's
+ * own `initialData` does (see {@link seedToolQuery} for when it wins over a
+ * cached answer). The last processed seed skips the content check while the
+ * same object comes in render after render.
+ */
+function useSeed(seed, cacheKey, updatedAt) {
+    const client = useQueryClient();
+    const keyId = hashKey(cacheKey);
+    const [seen, setSeen] = useState(null);
+    if (seed == null || (seen?.seed === seed && seen.keyId === keyId))
+        return;
+    const at = typeof updatedAt === "function" ? updatedAt() : updatedAt;
+    const written = seedToolQuery(client, cacheKey, seed, at);
+    // Only a real change re-renders: an equal new object per render must not loop.
+    if (written || seen?.keyId !== keyId)
+        setSeen({ seed, keyId });
+}
+/**
+ * A refetch that reads anew at once. TanStack restarts an in-flight fetch only
+ * over data (`cancelRefetch`); a key without data joins the running retry
+ * chain and waits out its backoff. So cancel that chain first, then read.
  */
-export function useViewData(initialData, key, tool, args, ready) {
-    const query = useToolQuery([...key], tool, args, { enabled: !initialData && ready });
-    const data = initialData ?? query.data ?? null;
-    const { refetch: refetchQuery } = query;
-    const refetch = useCallback(() => {
-        void refetchQuery();
-    }, [refetchQuery]);
-    return { data, loading: !data && ready && !query.isError, error: query.error ?? null, refetch };
+function useFreshRefetch(cacheKey, refetchQuery) {
+    const client = useQueryClient();
+    return useCallback(() => {
+        if (client.getQueryData(cacheKey) !== undefined) {
+            void refetchQuery();
+            return;
+        }
+        void client.cancelQueries({ queryKey: cacheKey, exact: true }).then(() => refetchQuery());
+    }, [client, cacheKey, refetchQuery]);
 }
 //# sourceMappingURL=use-view-data.js.map

package/dist/hooks/use-view-data.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-view-data.js","sourceRoot":"","sources":["../../src/hooks/use-view-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAelD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,WAAiC,EACjC,GAA2B,EAC3B,IAAY,EACZ,IAA6B,EAC7B,KAAc;IAEd,MAAM,KAAK,GAAG,YAAY,CAAI,CAAC,GAAG,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,WAAW,IAAI,KAAK,EAAE,CAAC,CAAA;IACvF,MAAM,IAAI,GAAG,WAAW,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,CAAA;IAC9C,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,KAAK,CAAA;IACvC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,KAAK,YAAY,EAAE,CAAA;IACrB,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAA;IAClB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,IAAI,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI,EAAE,OAAO,EAAE,CAAA;AACjG,CAAC"}
+{"version":3,"file":"use-view-data.js","sourceRoot":"","sources":["../../src/hooks/use-view-data.ts"],"names":[],"mappings":"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"}