@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/dist/components/WidgetHeader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetHeader.d.ts","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAElE,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,wBAAwB;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB,qEAAqE;IACrE,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,QAAoB,EACpB,KAAK,EACL,GAAG,EACH,OAAO,GACR,EAAE,iBAAiB,+BAuBnB"}
+{"version":3,"file":"WidgetHeader.d.ts","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAG5E,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAExE,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,EAAE,CAAC,EAAE,kBAAkB,CAAA;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,EAAE,EAAE,OAAc,EAClB,IAAgB,EAChB,WAAW,EACX,KAAK,EACL,GAAG,EACH,OAAO,EACP,IAAI,EACJ,QAAoB,EACpB,SAAS,GACV,EAAE,iBAAiB,+BAkCnB"}

package/dist/components/WidgetHeader.js

@@ -1,11 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { TONE_SOFT } from "../lib/tone-utils.js";
+import { resolveTone, TONE_SOFT } from "../lib/tone-utils.js";
+import { cn } from "../lib/utils.js";
+const TITLE_SIZE = {
+    default: "text-title",
+    detail: "text-section",
+};
 /**
- * Page-level header for the top of a dashboard widget: an optional tinted icon
- * tile, a large title, a subtitle/meta row, and a right-aligned actions slot.
- * Use once per widget surface to anchor it.
+ * Page-level header at the top of a widget: an optional state badge, the
+ * title (heading level per `as`, size per `size`), a subtitle/meta row and a
+ * right-aligned actions slot. Use once per widget surface to anchor it.
  */
-export function WidgetHeader({ icon, iconTone = "neutral", title, sub, actions, }) {
-    return (_jsxs("header", { className: "flex flex-wrap items-start justify-between gap-4", children: [_jsxs("div", { className: "min-w-0", children: [icon && (_jsx("div", { className: `mb-3.5 grid size-11 place-items-center rounded-xl text-xl ${TONE_SOFT[iconTone]}`, children: icon })), _jsx("h1", { className: "text-foreground mb-1.5 text-3xl leading-tight font-bold tracking-tight", children: title }), sub && (_jsx("div", { className: "text-muted-foreground flex flex-wrap items-center gap-2 text-sm", children: sub }))] }), actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }));
+export function WidgetHeader({ title, as: Heading = "h1", size = "default", titleSuffix, badge, sub, actions, icon, iconTone = "neutral", className, }) {
+    return (_jsxs("header", { "data-slot": "widget-header", className: cn("flex flex-wrap items-start justify-between gap-4", className), children: [_jsxs("div", { className: "min-w-0", children: [icon && (_jsx("div", { "aria-hidden": "true", className: cn("text-section mb-3.5 grid size-11 place-items-center rounded-md", TONE_SOFT[resolveTone(iconTone)]), children: icon })), badge && _jsx("div", { className: "mb-3", children: badge }), _jsxs(Heading, { className: cn("text-foreground mb-1.5 tracking-tight break-words", TITLE_SIZE[size]), children: [title, titleSuffix] }), sub && (_jsx("div", { className: "text-muted-foreground text-small flex flex-wrap items-center gap-2", children: sub }))] }), actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }));
 }
 //# sourceMappingURL=WidgetHeader.js.map

package/dist/components/WidgetHeader.js.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetHeader.js","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAoB,MAAM,sBAAsB,CAAA;AAelE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,IAAI,EACJ,QAAQ,GAAG,SAAS,EACpB,KAAK,EACL,GAAG,EACH,OAAO,GACW;IAClB,OAAO,CACL,kBAAQ,SAAS,EAAC,kDAAkD,aAClE,eAAK,SAAS,EAAC,SAAS,aACrB,IAAI,IAAI,CACP,cACE,SAAS,EAAE,6DAA6D,SAAS,CAAC,QAAQ,CAAC,EAAE,YAE5F,IAAI,GACD,CACP,EACD,aAAI,SAAS,EAAC,wEAAwE,YACnF,KAAK,GACH,EACJ,GAAG,IAAI,CACN,cAAK,SAAS,EAAC,iEAAiE,YAC7E,GAAG,GACA,CACP,IACG,EACL,OAAO,IAAI,cAAK,SAAS,EAAC,mCAAmC,YAAE,OAAO,GAAO,IACvE,CACV,CAAA;AACH,CAAC"}
+{"version":3,"file":"WidgetHeader.js","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAiB,MAAM,sBAAsB,CAAA;AAC5E,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAwCpC,MAAM,UAAU,GAA2D;IACzE,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,cAAc;CACvB,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,KAAK,EACL,EAAE,EAAE,OAAO,GAAG,IAAI,EAClB,IAAI,GAAG,SAAS,EAChB,WAAW,EACX,KAAK,EACL,GAAG,EACH,OAAO,EACP,IAAI,EACJ,QAAQ,GAAG,SAAS,EACpB,SAAS,GACS;IAClB,OAAO,CACL,+BACY,eAAe,EACzB,SAAS,EAAE,EAAE,CAAC,kDAAkD,EAAE,SAAS,CAAC,aAE5E,eAAK,SAAS,EAAC,SAAS,aACrB,IAAI,IAAI,CACP,6BACc,MAAM,EAClB,SAAS,EAAE,EAAE,CACX,gEAAgE,EAChE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CACjC,YAEA,IAAI,GACD,CACP,EACA,KAAK,IAAI,cAAK,SAAS,EAAC,MAAM,YAAE,KAAK,GAAO,EAC7C,MAAC,OAAO,IACN,SAAS,EAAE,EAAE,CAAC,mDAAmD,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,aAEnF,KAAK,EACL,WAAW,IACJ,EACT,GAAG,IAAI,CACN,cAAK,SAAS,EAAC,oEAAoE,YAChF,GAAG,GACA,CACP,IACG,EACL,OAAO,IAAI,cAAK,SAAS,EAAC,mCAAmC,YAAE,OAAO,GAAO,IACvE,CACV,CAAA;AACH,CAAC"}

package/dist/hooks/index.d.ts

@@ -1,11 +1,11 @@
 export { useIsMobile } from "./use-mobile.js";
 export { useDebouncedValue } from "./use-debounced-value.js";
-export { useToolQuery, useToolMutation } from "./use-tool-query.js";
-export type { UseToolQueryOptions } from "./use-tool-query.js";
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./use-tool-query.js";
+export type { UseToolQueryOptions, UseToolMutationOptions } from "./use-tool-query.js";
 export { useViewToolQuery } from "./use-view-tool-query.js";
 export type { UseViewToolQueryOptions } from "./use-view-tool-query.js";
 export { useViewData } from "./use-view-data.js";
-export type { ViewDataResult } from "./use-view-data.js";
+export type { ViewDataResult, UseViewDataOptions, ViewDataMode } from "./use-view-data.js";
 export { useToolResultRecovery, resolveRecoveryToolName, decodeRecoveredResult, } from "./use-tool-result-recovery.js";
-export type { ToolResultRecoveryOptions, ToolResultRecoveryState, } from "./use-tool-result-recovery.js";
+export type { RecoveryBlockReason, RecoveryPolicy, ToolResultRecoveryOptions, ToolResultRecoveryState, ToolSafety, } from "./use-tool-result-recovery.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACpF,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,GACX,MAAM,+BAA+B,CAAA"}

package/dist/hooks/index.js

@@ -1,6 +1,6 @@
 export { useIsMobile } from "./use-mobile.js";
 export { useDebouncedValue } from "./use-debounced-value.js";
-export { useToolQuery, useToolMutation } from "./use-tool-query.js";
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./use-tool-query.js";
 export { useViewToolQuery } from "./use-view-tool-query.js";
 export { useViewData } from "./use-view-data.js";
 export { useToolResultRecovery, resolveRecoveryToolName, decodeRecoveredResult, } from "./use-tool-result-recovery.js";

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA"}

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

@@ -0,0 +1,155 @@
+import type { ToolObservation, ToolResultObserver } from "../lib/tool-result-observer.js";
+/**
+ * What the host's tool annotations say about re-running the originating
+ * tool: `readOnlyHint: true` is `"read-only"`, `readOnlyHint: false` or
+ * `destructiveHint: true` is `"writes"`, anything else (no tool definition,
+ * no annotations, no read-only hint) is `"unknown"`.
+ */
+export type ToolSafety = "read-only" | "writes" | "unknown";
+/**
+ * Which tools the view may re-execute on its own to recover a stripped result.
+ *
+ * - `"auto"` (default): any tool the host does not report as writing — a
+ *   view tool is a read by the toolkit's render contract, so a missing hint
+ *   counts as one.
+ * - `"read-only"`: only a tool the host reports with `readOnlyHint: true`.
+ * - `"never"`: never; a stripped result shows the error state, whose retry
+ *   runs the tool on the user's click.
+ */
+export type RecoveryPolicy = "auto" | "read-only" | "never";
+/** Why a needed recovery did not run: the policy forbids it, or the host names no tool. */
+export type RecoveryBlockReason = "policy" | "no-tool";
+/** Read {@link ToolSafety} from `hostContext.toolInfo.tool.annotations` (SEP-1865). */
+export declare function resolveToolSafety(hostContext: unknown): ToolSafety;
+/** Whether `policy` lets the view re-execute a tool of this `safety` on its own. */
+export declare function policyAllows(policy: RecoveryPolicy, safety: ToolSafety): boolean;
+export interface RecoveryDecisionInput {
+    /** The latch fired (`useToolContext().status !== "pending"`). */
+    resultReady: boolean;
+    /** The latched payload is renderable (a conforming host delivered it). */
+    payloadValid: boolean;
+    /** The host cancelled the call. */
+    cancelled: boolean;
+    /** The call latched a tool error (an `isError` result or a failed call). */
+    errored: boolean;
+    /** What the transport observer saw; `null` when none listens. */
+    observation: ToolObservation | null;
+    /** The call's arguments arrived (any tool-input, partial or complete). */
+    hasInput: boolean;
+    /** The originating tool (`hostContext.toolInfo`), when the host names it. */
+    toolName: string | undefined;
+    safety: ToolSafety;
+    policy: RecoveryPolicy;
+    /** The fallback grace period passed for the current arguments. */
+    graceElapsed: boolean;
+}
+export type RecoveryDecision = 
+/** Delivered, failed or cancelled: nothing to recover. */
+{
+    action: "none";
+}
+/** The result is not in yet; `armGrace` starts the fallback timer (observer cannot vouch). */
+ | {
+    action: "wait";
+    armGrace: boolean;
+}
+/** Re-execute the originating tool now. */
+ | {
+    action: "recover";
+}
+/** A recovery is needed but must not run. */
+ | {
+    action: "blocked";
+    reason: RecoveryBlockReason;
+};
+/** The recovery rule (see the module comment). Pure: every input is explicit. */
+export declare function decideRecovery(input: RecoveryDecisionInput): RecoveryDecision;
+/**
+ * The arguments a re-execution runs with: the complete tool-input the
+ * observer saw, else the view runtime's latest input, else none.
+ */
+export declare function recoveryArgs(observation: ToolObservation | null, toolInput: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Content identity of a JSON value, independent of key order and object
+ * identity: a re-delivered equal input is the same input (N21).
+ */
+export declare function stableKey(value: unknown): string;
+/**
+ * Decodes a re-executed tool result and validates it: the payload, or `null`
+ * for an error result, an empty one or one the validator refuses.
+ */
+export declare function decodeRecoveredResult<T>(result: unknown, isValid: (value: unknown) => boolean): T | null;
+export interface ToolResultRecoveryState<T> {
+    /** The recovered payload, `null` until the re-execution resolved (or when it failed). */
+    data: T | null;
+    /** The single recovery attempt failed — the view shows its error state, no retry loop. */
+    failed: boolean;
+    /**
+     * A recovery was needed but did not run: the policy forbids re-executing
+     * this tool, or the host names no tool. `null` otherwise.
+     */
+    blocked: RecoveryBlockReason | null;
+    /** When the recovered payload arrived (epoch ms) — its data is live as of then (N23). */
+    recoveredAt: number | null;
+    /** The arguments the recovered payload was computed for. */
+    args: Record<string, unknown> | null;
+}
+export declare const RECOVERY_IDLE: ToolResultRecoveryState<never>;
+/** What the view knows about the rendering call on each render. */
+export interface RecoveryInputs {
+    resultReady: boolean;
+    cancelled: boolean;
+    errored: boolean;
+    /** The payload the host delivered (`useToolContext().toolOutput`). */
+    props: unknown;
+    isValid: (value: unknown) => boolean;
+    toolInput: Record<string, unknown> | null | undefined;
+    /** Raw host context; `toolInfo` names the originating tool and its annotations. */
+    hostContext: Record<string, unknown> | null | undefined;
+    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    policy: RecoveryPolicy;
+    /** The fallback grace period (observer cannot vouch). */
+    graceMs: number;
+    /** Resolves the originating tool name from the host context. */
+    resolveToolName: (hostContext: unknown) => string | undefined;
+}
+export interface RecoveryController<T> {
+    subscribe: (listener: () => void) => () => void;
+    getState: () => ToolResultRecoveryState<T>;
+    /** Feed the latest inputs (every commit) and act on the decision. */
+    update: (inputs: RecoveryInputs) => void;
+    /** Listen to the observer (mount). */
+    start: () => void;
+    /** Stop listening and drop the grace timer; an in-flight call still lands (StrictMode re-runs). */
+    stop: () => void;
+}
+export interface RecoveryControllerOptions {
+    /** The transport observer; `null` when none listens (the grace timer decides alone). */
+    observer: ToolResultObserver | null;
+    /** Clock for {@link ToolResultRecoveryState.recoveredAt}. Default `Date.now`. */
+    now?: () => number;
+}
+/** One evaluation of the inputs: the decision plus the run it concerns. */
+interface Evaluation {
+    decision: RecoveryDecision;
+    toolName: string | undefined;
+    args: Record<string, unknown>;
+    /** Content identity of `args` (the grace timer's key). */
+    argsKey: string;
+    /** Identity of the run: the tool and its arguments (the single flight's key). */
+    runKey: string;
+}
+/** Run {@link decideRecovery} on the controller's current knowledge. */
+export declare function evaluateRecovery(inputs: RecoveryInputs, observation: ToolObservation | null, grace: {
+    key: string | null;
+    elapsed: boolean;
+}): Evaluation;
+/**
+ * Runs {@link decideRecovery} for the view: re-evaluates on every input
+ * update and observer change, arms the fallback grace timer per argument set,
+ * and makes at most one call per run (single flight, keyed by the tool and
+ * its arguments; a newer run drops an older call's outcome).
+ */
+export declare function createRecoveryController<T>(options: RecoveryControllerOptions): RecoveryController<T>;
+export {};
+//# sourceMappingURL=tool-result-recovery-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-recovery-model.d.ts","sourceRoot":"","sources":["../../src/hooks/tool-result-recovery-model.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,273 @@
+/**
+ * The stripped-result recovery of `McpAppView` as plain logic (toolkit#176):
+ * WHEN the originating tool may be re-executed ({@link decideRecovery}) and a
+ * framework-free controller that runs that decision against the transport
+ * observer, a fallback grace timer and a single-flight call
+ * ({@link createRecoveryController}). `useToolResultRecovery` only binds the
+ * controller to React, so the scenarios here (keep / strip / slow / late
+ * observer) are the hook's behaviour.
+ *
+ * The rule, in order:
+ *
+ * 1. Never recover a call that was cancelled or failed: the view renders that
+ *    state (an `isError` is an error, K14).
+ * 2. Recover when the host delivered a result the view cannot render: the
+ *    latch fired with an invalid payload, or the observer saw the stripped,
+ *    content-only result claude.ai sends. The re-run uses the COMPLETE
+ *    arguments of the call (N21), never a partial stream.
+ * 3. Otherwise wait. A slow tool on a compliant host is simply still running
+ *    (K13): the observer, listening since the handshake, would have seen its
+ *    result. Only when it cannot vouch for that (no observer, or installed
+ *    after the handshake) does the 2.x grace timer still infer a stripped
+ *    result, and only once the call's arguments arrived.
+ * 4. A needed recovery runs only for a tool the policy allows
+ *    ({@link RecoveryPolicy}: by default never one the host reports as
+ *    writing) and only when the host names the tool; else it is `blocked`,
+ *    which the view renders as an error whose retry is the user's own call.
+ */
+import { parseToolResult } from "../lib/parse-tool-result.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read {@link ToolSafety} from `hostContext.toolInfo.tool.annotations` (SEP-1865). */
+export function resolveToolSafety(hostContext) {
+    if (!isRecord(hostContext) || !isRecord(hostContext.toolInfo))
+        return "unknown";
+    const tool = hostContext.toolInfo.tool;
+    const annotations = isRecord(tool) ? tool.annotations : undefined;
+    if (!isRecord(annotations))
+        return "unknown";
+    if (annotations.destructiveHint === true || annotations.readOnlyHint === false)
+        return "writes";
+    return annotations.readOnlyHint === true ? "read-only" : "unknown";
+}
+/** Whether `policy` lets the view re-execute a tool of this `safety` on its own. */
+export function policyAllows(policy, safety) {
+    if (policy === "never")
+        return false;
+    if (policy === "read-only")
+        return safety === "read-only";
+    return safety !== "writes";
+}
+const NONE = { action: "none" };
+const WAIT = { action: "wait", armGrace: false };
+const WAIT_ARMED = { action: "wait", armGrace: true };
+const RECOVER = { action: "recover" };
+/** Rules 1–3: does the result need recovering, or is it delivered / still on its way? */
+function recoveryNeed(input) {
+    if (input.resultReady)
+        return input.payloadValid ? NONE : "needed";
+    const observed = input.observation?.result ?? "none";
+    if (observed === "stripped")
+        return "needed";
+    // A structured result or an error: the latch is about to follow.
+    if (observed !== "none")
+        return NONE;
+    // Listening since the handshake: nothing arrived because nothing was sent.
+    if (input.observation?.sawHandshake)
+        return WAIT;
+    if (input.toolName === undefined || !input.hasInput)
+        return WAIT;
+    return input.graceElapsed ? "needed" : WAIT_ARMED;
+}
+/** The recovery rule (see the module comment). Pure: every input is explicit. */
+export function decideRecovery(input) {
+    if (input.cancelled || input.errored || input.observation?.cancelled)
+        return NONE;
+    const need = recoveryNeed(input);
+    if (need !== "needed")
+        return need;
+    if (input.toolName === undefined)
+        return { action: "blocked", reason: "no-tool" };
+    if (!policyAllows(input.policy, input.safety))
+        return { action: "blocked", reason: "policy" };
+    return RECOVER;
+}
+/**
+ * The arguments a re-execution runs with: the complete tool-input the
+ * observer saw, else the view runtime's latest input, else none.
+ */
+export function recoveryArgs(observation, toolInput) {
+    return observation?.completeInput ?? toolInput ?? {};
+}
+/**
+ * Content identity of a JSON value, independent of key order and object
+ * identity: a re-delivered equal input is the same input (N21).
+ */
+export function stableKey(value) {
+    return (JSON.stringify(value, (_key, v) => isRecord(v)
+        ? Object.fromEntries(Object.keys(v)
+            .sort()
+            .map((k) => [k, v[k]]))
+        : v) ?? "undefined");
+}
+/**
+ * Decodes a re-executed tool result and validates it: the payload, or `null`
+ * for an error result, an empty one or one the validator refuses.
+ */
+export function decodeRecoveredResult(result, isValid) {
+    let decoded;
+    try {
+        decoded = parseToolResult(result);
+    }
+    catch {
+        return null;
+    }
+    return decoded !== null && isValid(decoded) ? decoded : null;
+}
+export const RECOVERY_IDLE = Object.freeze({
+    data: null,
+    failed: false,
+    blocked: null,
+    recoveredAt: null,
+    args: null,
+});
+/** Run {@link decideRecovery} on the controller's current knowledge. */
+export function evaluateRecovery(inputs, observation, grace) {
+    const toolName = inputs.resolveToolName(inputs.hostContext);
+    const args = recoveryArgs(observation, inputs.toolInput);
+    const argsKey = stableKey(args);
+    const decision = decideRecovery({
+        resultReady: inputs.resultReady,
+        payloadValid: inputs.isValid(inputs.props),
+        cancelled: inputs.cancelled,
+        errored: inputs.errored,
+        observation,
+        hasInput: inputs.toolInput != null || observation?.completeInput !== undefined,
+        toolName,
+        safety: resolveToolSafety(inputs.hostContext),
+        policy: inputs.policy,
+        graceElapsed: grace.elapsed && grace.key === argsKey,
+    });
+    return { decision, toolName, args, argsKey, runKey: `${toolName ?? ""}\u0000${argsKey}` };
+}
+/** Re-execute the tool and decode its answer; `null` for anything unusable. */
+async function rerun(callTool, isValid, toolName, args) {
+    try {
+        const data = decodeRecoveredResult(await callTool(toolName, args), isValid);
+        if (data === null) {
+            console.warn(`[mcp-toolkit] tool-result recovery: re-executing "${toolName}" returned no usable payload`);
+        }
+        return data;
+    }
+    catch (err) {
+        console.warn(`[mcp-toolkit] tool-result recovery for "${toolName}" failed:`, err);
+        return null;
+    }
+}
+/**
+ * Runs {@link decideRecovery} for the view: re-evaluates on every input
+ * update and observer change, arms the fallback grace timer per argument set,
+ * and makes at most one call per run (single flight, keyed by the tool and
+ * its arguments; a newer run drops an older call's outcome).
+ */
+export function createRecoveryController(options) {
+    const { observer } = options;
+    const now = options.now ?? Date.now;
+    const listeners = new Set();
+    let state = RECOVERY_IDLE;
+    let inputs = null;
+    let unsubscribe = null;
+    let flight = null;
+    // The fallback grace timer: armed per argument set, elapsed once it fired.
+    const grace = { key: null, elapsed: false };
+    let graceTimer = null;
+    const setState = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const clearGraceTimer = () => {
+        if (graceTimer !== null)
+            clearTimeout(graceTimer);
+        graceTimer = null;
+    };
+    const armGrace = (key, ms) => {
+        if (grace.key === key && (grace.elapsed || graceTimer !== null))
+            return;
+        clearGraceTimer();
+        grace.key = key;
+        grace.elapsed = false;
+        graceTimer = setTimeout(() => {
+            graceTimer = null;
+            grace.elapsed = true;
+            evaluate();
+        }, ms);
+    };
+    const launch = (current, run, toolName) => {
+        const own = {
+            key: run.runKey,
+            promise: rerun(current.callTool, current.isValid, toolName, run.args),
+        };
+        flight = own;
+        void own.promise.then((data) => {
+            // A newer run superseded this call: its outcome is stale.
+            if (flight !== own)
+                return;
+            setState(data === null
+                ? { ...RECOVERY_IDLE, failed: true, args: run.args }
+                : { data: data, failed: false, blocked: null, recoveredAt: now(), args: run.args });
+        });
+    };
+    /** Act on one evaluation: drop a superseded attempt, launch, block or settle. */
+    const apply = (current, run) => {
+        const { decision } = run;
+        // A new run (the need went away, or new arguments) drops the previous
+        // attempt and its outcome.
+        if (flight && (decision.action !== "recover" || flight.key !== run.runKey)) {
+            flight = null;
+            setState(RECOVERY_IDLE);
+        }
+        if (decision.action === "blocked") {
+            if (state.blocked !== decision.reason) {
+                setState({ ...RECOVERY_IDLE, blocked: decision.reason });
+            }
+            return;
+        }
+        // A lifted block (the tool got named, the policy changed) is gone at once,
+        // also while the re-run it allows is still in flight.
+        if (state.blocked !== null)
+            setState(RECOVERY_IDLE);
+        if (decision.action === "recover" && !flight && run.toolName !== undefined) {
+            launch(current, run, run.toolName);
+        }
+    };
+    function evaluate() {
+        if (!inputs)
+            return;
+        const run = evaluateRecovery(inputs, observer?.getSnapshot() ?? null, grace);
+        if (run.decision.action === "wait" && run.decision.armGrace)
+            armGrace(run.argsKey, inputs.graceMs);
+        else
+            clearGraceTimer();
+        apply(inputs, run);
+    }
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getState: () => state,
+        update: (next) => {
+            inputs = next;
+            evaluate();
+        },
+        start: () => {
+            if (!unsubscribe && observer)
+                unsubscribe = observer.subscribe(evaluate);
+            evaluate();
+        },
+        stop: () => {
+            unsubscribe?.();
+            unsubscribe = null;
+            // A stopped timer restarts in full on the next start (armGrace re-arms
+            // a key whose timer is gone); an elapsed grace stays elapsed.
+            clearGraceTimer();
+        },
+    };
+}
+//# sourceMappingURL=tool-result-recovery-model.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-recovery-model.js","sourceRoot":"","sources":["../../src/hooks/tool-result-recovery-model.ts"],"names":[],"mappings":"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"}

package/dist/hooks/use-tool-query.d.ts

@@ -1,21 +1,63 @@
-export interface UseToolQueryOptions<TData = unknown, TSelected = TData> {
-    enabled?: boolean;
-    select?: (data: TData) => TSelected;
-}
+import { type UseMutationOptions, type UseMutationResult, type UseQueryResult } from "@tanstack/react-query";
+import { type UseToolQueryOptions } from "../lib/tool-query.js";
+export type { UseToolQueryOptions } from "../lib/tool-query.js";
+/**
+ * The exact cache key `useToolQuery`, `useViewToolQuery` and `useViewData`
+ * use for this tool and args under the nearest `AppQueryProvider`:
+ * `toolQueryKey` with the provider's `toolNameInQueryKey` setting. For
+ * `getQueryData`, `setQueryData` or `cancelQueries({ exact: true })`; prefix
+ * invalidation needs only the caller's `queryKey`. A new array per render.
+ */
+export declare function useToolQueryKey(queryKey: readonly unknown[], toolName: string, args: object): unknown[];
+/**
+ * Warns when two tools use one cache key (toolkit#176 K18): their answers
+ * would overwrite each other. Only the 2.x key can collide: with the tool
+ * name in the key (`toolNameInQueryKey`), two tools never share one.
+ */
+export declare function useToolKeyGuard(queryKey: readonly unknown[], toolName: string, args: object): void;
+/**
+ * Fetches a query again once a tool transport arrives, when it failed for
+ * want of one ({@link NoToolTransportError}): a `callTool` that resolves
+ * after the first render. TanStack refetches on a new key or `enabled`,
+ * never on a new fetcher, so the query would keep the error until a remount.
+ */
+export declare function useRefetchOnTransport(callTool: unknown, query: Pick<UseQueryResult<unknown, Error>, "error" | "refetch">): void;
 /**
  * Loads data from a widget tool via TanStack Query.
  *
- * `args` is appended to the effective query key so two callers that share
- * the supplied `queryKey` but pass different `args` get separate cache
- * entries (otherwise the second caller silently reads stale data from the
- * first — the classic queryKey-vs-args trap). `select` transforms data on
- * each read without mutating the cache.
+ * The effective cache key is `[...queryKey, args]` (`toolQueryKey`): two
+ * callers that share `queryKey` but pass different `args` get separate
+ * entries. Two tools must not share a key and args; the hook warns when they
+ * do. Under an `AppQueryProvider` with `toolNameInQueryKey` (opt-in in 2.x,
+ * the default from the next major) the key is `[...queryKey, toolName,
+ * args]` and two tools never collide; `useToolQueryKey` returns the key in
+ * force. `opts` passes TanStack's query options through (`retry`,
+ * `retryDelay`, `staleTime`, `placeholderData` / `keepPreviousData`,
+ * `initialData` + `initialDataUpdatedAt`, `enabled`, `select`, …), and the
+ * result exposes `refetch`, `failureCount` and `failureReason`. `retry`
+ * defaults to the client's; `retry: shouldRetryToolCall` stops retrying a
+ * tool's own `isError` answer.
+ *
+ * The tool goes through `AppQueryProvider`'s `callTool`, else the nearest
+ * `HostBridgeProvider`'s bridge; with neither, the query fails with a
+ * "no tool transport" error instead of idling, and fetches once one arrives.
  */
-export declare function useToolQuery<TData = unknown, TSelected = TData>(queryKey: unknown[], toolName: string, args: object, opts?: UseToolQueryOptions<TData, TSelected>): import("@tanstack/react-query").UseQueryResult<TSelected, Error>;
+export declare function useToolQuery<TData = unknown, TSelected = TData>(queryKey: readonly unknown[], toolName: string, args: object, opts?: UseToolQueryOptions<TData, TSelected>): UseQueryResult<TSelected, Error>;
+/** Options of {@link useToolMutation}: TanStack's mutation options plus `invalidateKeys`. */
+export type UseToolMutationOptions<TData = unknown> = Omit<UseMutationOptions<TData, Error, Record<string, unknown>, unknown>, "mutationFn" | "onMutate"> & {
+    /** Query keys (prefixes) to invalidate after a successful call. */
+    invalidateKeys?: unknown[][];
+};
 /**
- * Executes a mutation via a widget tool and invalidates configured query keys.
+ * Executes a mutation via a widget tool and invalidates `invalidateKeys`
+ * after each successful call (`invalidateQueries`: active queries refetch,
+ * inactive ones are marked stale and refetch when they are next used).
+ *
+ * `mutate(args, { onSuccess, onError, onSettled })` fires its per-call
+ * callbacks for EVERY call while the component is mounted, not only for the
+ * latest one (TanStack's own rule), so two quick calls each get their
+ * confirmation. The hook-level callbacks in `opts` run first; the
+ * invalidation runs before the hook-level `onSuccess`.
  */
-export declare function useToolMutation<TData = unknown>(toolName: string, opts?: {
-    invalidateKeys?: unknown[][];
-}): import("@tanstack/react-query").UseMutationResult<TData, Error, Record<string, unknown>, unknown>;
+export declare function useToolMutation<TData = unknown>(toolName: string, opts?: UseToolMutationOptions<TData>): UseMutationResult<TData, Error, Record<string, unknown>>;
 //# sourceMappingURL=use-tool-query.d.ts.map

package/dist/hooks/use-tool-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-tool-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-tool-query.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,KAAK;IACrE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAA;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,KAAK,EAC7D,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,oEAc7C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAG,OAAO,EAC7C,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE,CAAA;CAAE,qGAmBxC"}
+{"version":3,"file":"use-tool-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-tool-query.ts"],"names":[],"mappings":"AACA,OAAO,EAML,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EASL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAA;AAE7B,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAE/D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,EAAE,CAEX;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,GAC/D,IAAI,CAKN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAG,OAAO,EAAE,SAAS,GAAG,KAAK,EAC7D,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,GAC3C,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAWlC;AAED,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,OAAO,IAAI,IAAI,CACxD,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAClE,YAAY,GAAG,UAAU,CAC1B,GAAG;IACF,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAG,OAAO,EAC7C,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,GACnC,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgD1D"}