@tanstack/ai-client 0.34.0 → 0.35.1

package/dist/esm/index.d.ts

@@ -5,8 +5,8 @@ export { InterruptManager } from './interrupt-manager.js';
 export type { InterruptManagerHydration, InterruptManagerOptions, InterruptManagerSubmission, } from './interrupt-manager.js';
 export { createMcpAppBridge } from './mcp-app-bridge.js';
 export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge.js';
-export { registerWebMCPTools } from './web-mcp-tools.js';
-export type { RegisterWebMCPToolsOptions, WebMCPToolAnnotations, WebMCPToolOptions, WebMCPToolOptionsByName, } from './web-mcp-tools.js';
+export { getWebMCPTools, registerWebMCPTools, subscribeWebMCPTools, } from './web-mcp-tools.js';
+export type { GetWebMCPToolsOptions, RegisterWebMCPToolsOptions, SubscribeWebMCPToolsOptions, WebMCPPageTool, WebMCPToolAnnotations, WebMCPToolOptions, WebMCPToolOptionsByName, } from './web-mcp-tools.js';
 export { RealtimeClient } from './realtime-client.js';
 export { GenerationClient } from './generation-client.js';
 export { VideoGenerationClient } from './video-generation-client.js';

package/dist/esm/index.js

@@ -4,7 +4,7 @@ import { DurableStreamIncompleteError, StreamReconnectLimitError, StreamTruncate
 import { InterruptManager } from "./interrupt-manager.js";
 import { ChatClient } from "./chat-client.js";
 import { createMcpAppBridge } from "./mcp-app-bridge.js";
-import { registerWebMCPTools } from "./web-mcp-tools.js";
+import { getWebMCPTools, registerWebMCPTools, subscribeWebMCPTools } from "./web-mcp-tools.js";
 import { RealtimeClient } from "./realtime-client.js";
 import { GENERATION_EVENTS } from "./generation-types.js";
 import { GenerationClient } from "./generation-client.js";
@@ -14,4 +14,4 @@ import { clientTools, createChatClientOptions } from "./types.js";
 import { StorageUnavailableError, indexedDBPersistence, localStoragePersistence, sessionStoragePersistence } from "./storage-adapters.js";
 import { createAIDevtoolsGenerationPreview } from "./devtools.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, convertMessagesToModelMessages, defaultJSONParser, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, uiMessageToModelMessages } from "@tanstack/ai/client";
-export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents };
+export { AudioRecorder, BatchStrategy, ChatClient, CompositeStrategy, DurableStreamIncompleteError, GENERATION_EVENTS, GenerationClient, ImmediateStrategy, InterruptManager, PartialJSONParser, PunctuationStrategy, RealtimeClient, StorageUnavailableError, StreamProcessor, StreamReconnectLimitError, StreamTruncatedError, UnsupportedResponseStreamError, VideoGenerationClient, WordBoundaryStrategy, clientTools, convertMessagesToModelMessages, createAIDevtoolsGenerationPreview, createChatClientOptions, createMcpAppBridge, defaultJSONParser, fetchHttpStream, fetchServerSentEvents, generateMessageId, getWebMCPTools, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, subscribeWebMCPTools, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents };

package/dist/esm/web-mcp-tools.d.ts

@@ -47,3 +47,63 @@ export type RegisterWebMCPToolsOptions<TTools extends ReadonlyArray<AnyClientToo
  * ```
  */
 export declare function registerWebMCPTools<const TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>>(tools: TTools, options: RegisterWebMCPToolsOptions<TTools, TContext>): Promise<void>;
+/** A tool that a page registered with WebMCP, as `getTools()` returns it. */
+export interface WebMCPPageTool {
+    name: string;
+    title?: string;
+    description: string;
+    /** A JSON Schema object for the tool input. */
+    inputSchema?: object;
+    /** The origin of the document that registered the tool. */
+    origin: string;
+    annotations?: WebMCPToolAnnotations;
+}
+/** Options for {@link getWebMCPTools}. */
+export interface GetWebMCPToolsOptions {
+    /** Return `false` to skip a tool. */
+    filter?: (tool: WebMCPPageTool) => boolean;
+}
+/** Options for {@link subscribeWebMCPTools}. */
+export interface SubscribeWebMCPToolsOptions extends GetWebMCPToolsOptions {
+    /** Stops the subscription when it aborts. */
+    signal: AbortSignal;
+    /** Receives a failure from the WebMCP `getTools()` call. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Reads the WebMCP tools on the page and returns them as client tools.
+ *
+ * Pass the result to a chat as `tools`. Each tool runs through the WebMCP
+ * `executeTool()` call. Unsupported browsers and server environments return
+ * an empty array.
+ *
+ * @param options - A filter that skips tools.
+ *
+ * @example
+ * ```ts
+ * const tools = await getWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * ```
+ */
+export declare function getWebMCPTools(options?: GetWebMCPToolsOptions): Promise<Array<AnyClientTool>>;
+/**
+ * Calls `listener` with the page WebMCP tools now and after each
+ * `toolchange` event, until `options.signal` aborts.
+ *
+ * Unsupported browsers and server environments call `listener` once with an
+ * empty array. When a read fails, `options.onError` gets the error and the
+ * listener keeps the last list.
+ *
+ * @param listener - Receives the current client tools.
+ * @param options - The subscription signal, a filter, and an error callback.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {
+ *   signal: controller.signal,
+ * })
+ * ```
+ */
+export declare function subscribeWebMCPTools(listener: (tools: Array<AnyClientTool>) => void, options: SubscribeWebMCPToolsOptions): void;

package/dist/esm/web-mcp-tools.js

@@ -74,7 +74,98 @@ async function registerWebMCPTools(tools, options) {
 		throw error;
 	}
 }
+function isWebMCPToolReader(value) {
+	return value !== null && typeof value === "object" && "getTools" in value && typeof value.getTools === "function" && "executeTool" in value && typeof value.executeTool === "function" && "addEventListener" in value && typeof value.addEventListener === "function" && "removeEventListener" in value && typeof value.removeEventListener === "function";
+}
+function getWebMCPToolReader() {
+	if (typeof document === "undefined" || typeof isSecureContext !== "undefined" && !isSecureContext || !("modelContext" in document) || !isWebMCPToolReader(document.modelContext)) return;
+	return document.modelContext;
+}
+function parseToolResult(result) {
+	try {
+		return JSON.parse(result);
+	} catch {
+		return result;
+	}
+}
+async function readWebMCPTools(reader, options) {
+	const pageTools = await reader.getTools();
+	const names = /* @__PURE__ */ new Set();
+	return pageTools.filter((tool) => options?.filter?.(tool) ?? true).map((tool) => {
+		if (names.has(tool.name)) throw new Error(`Duplicate WebMCP tool name "${tool.name}". Use a filter or register tools with unique names.`);
+		names.add(tool.name);
+		return {
+			__toolSide: "client",
+			name: tool.name,
+			description: tool.description,
+			inputSchema: tool.inputSchema ?? { type: "object" },
+			async execute(input, context) {
+				return parseToolResult(await reader.executeTool(tool, input, context?.abortSignal ? { signal: context.abortSignal } : {}));
+			}
+		};
+	});
+}
+/**
+* Reads the WebMCP tools on the page and returns them as client tools.
+*
+* Pass the result to a chat as `tools`. Each tool runs through the WebMCP
+* `executeTool()` call. Unsupported browsers and server environments return
+* an empty array.
+*
+* @param options - A filter that skips tools.
+*
+* @example
+* ```ts
+* const tools = await getWebMCPTools({
+*   filter: (tool) => tool.origin === location.origin,
+* })
+* ```
+*/
+async function getWebMCPTools(options) {
+	const reader = getWebMCPToolReader();
+	return reader ? readWebMCPTools(reader, options) : [];
+}
+/**
+* Calls `listener` with the page WebMCP tools now and after each
+* `toolchange` event, until `options.signal` aborts.
+*
+* Unsupported browsers and server environments call `listener` once with an
+* empty array. When a read fails, `options.onError` gets the error and the
+* listener keeps the last list.
+*
+* @param listener - Receives the current client tools.
+* @param options - The subscription signal, a filter, and an error callback.
+*
+* @example
+* ```ts
+* const controller = new AbortController()
+* subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {
+*   signal: controller.signal,
+* })
+* ```
+*/
+function subscribeWebMCPTools(listener, options) {
+	if (options.signal.aborted) return;
+	const reader = getWebMCPToolReader();
+	if (!reader) {
+		listener([]);
+		return;
+	}
+	let latestRead = 0;
+	const refresh = () => {
+		const read = ++latestRead;
+		const isCurrent = () => read === latestRead && !options.signal.aborted;
+		readWebMCPTools(reader, options).then((tools) => {
+			if (isCurrent()) listener(tools);
+		}, (error) => {
+			if (isCurrent()) options.onError?.(error);
+		});
+	};
+	reader.addEventListener("toolchange", refresh);
+	options.signal.addEventListener("abort", () => reader.removeEventListener("toolchange", refresh), { once: true });
+	refresh();
+}
 //#endregion
-export { registerWebMCPTools };
+export { getWebMCPTools, registerWebMCPTools, subscribeWebMCPTools };
 
 //# sourceMappingURL=web-mcp-tools.js.map

package/dist/esm/web-mcp-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-mcp-tools.js","names":[],"sources":["../../src/web-mcp-tools.ts"],"sourcesContent":["import {\n  convertSchemaToJsonSchema,\n  validateWithStandardSchema,\n} from '@tanstack/ai/client'\nimport type { AnyClientTool } from '@tanstack/ai/client'\nimport type {\n  ClientContextOptionFromTools,\n  InferredClientContext,\n} from './types'\n\ninterface WebMCPTool {\n  name: string\n  title?: string\n  description: string\n  inputSchema?: object\n  annotations?: WebMCPToolAnnotations\n  execute: (input: object, options: { signal: AbortSignal }) => Promise<unknown>\n}\n\ninterface WebMCPModelContext {\n  registerTool: (\n    tool: WebMCPTool,\n    options: { signal: AbortSignal },\n  ) => Promise<void>\n}\n\n/** WebMCP behavior hints for one registered tool. */\nexport interface WebMCPToolAnnotations {\n  /** Indicates that the tool does not modify state. */\n  readOnlyHint?: boolean\n  /** Indicates that the tool can return content that the application does not trust. */\n  untrustedContentHint?: boolean\n}\n\n/** Display and behavior options for one WebMCP tool. */\nexport interface WebMCPToolOptions {\n  /** A human-readable title for browser user interfaces. */\n  title?: string\n  /** Optional behavior hints for browser agents. */\n  annotations?: WebMCPToolAnnotations\n}\n\n/** WebMCP options keyed by the inferred names in a client tool list. */\nexport type WebMCPToolOptionsByName<\n  TTools extends ReadonlyArray<AnyClientTool>,\n> = Partial<{\n  [TName in TTools[number]['name']]: WebMCPToolOptions\n}>\n\n/**\n * Options for {@link registerWebMCPTools}.\n *\n * The signal controls the registration lifetime. Context is required when a\n * client tool declares a required runtime context.\n */\nexport type RegisterWebMCPToolsOptions<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n> = {\n  /** Removes all tools from this call when the signal aborts. */\n  signal: AbortSignal\n  /** Per-tool display and behavior options. */\n  toolOptions?: WebMCPToolOptionsByName<TTools>\n} & ClientContextOptionFromTools<TTools, TContext>\n\nfunction isWebMCPModelContext(value: unknown): value is WebMCPModelContext {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'registerTool' in value &&\n    typeof value.registerTool === 'function'\n  )\n}\n\nfunction getToolOptions<TName extends string>(\n  toolOptions: Partial<Record<TName, WebMCPToolOptions>> | undefined,\n  name: TName,\n) {\n  return toolOptions?.[name]\n}\n\nasync function validateSchemaValue(schema: unknown, value: unknown) {\n  const result = await validateWithStandardSchema(schema, value)\n  if (result.success) {\n    return result.data\n  }\n\n  throw new Error(\n    `Validation failed: ${result.issues.map((issue) => issue.message).join(', ')}`,\n  )\n}\n\n/**\n * Registers executable TanStack client tools with the browser WebMCP API.\n *\n * Unsupported browsers and server environments resolve without registration.\n * Abort `options.signal` to remove every tool registered by this call.\n *\n * @param tools - The executable client tools to expose through WebMCP.\n * @param options - The registration signal, runtime context, and per-tool options.\n *\n * @example\n * ```ts\n * const controller = new AbortController()\n * await registerWebMCPTools(tools, { signal: controller.signal })\n * controller.abort()\n * ```\n */\nexport async function registerWebMCPTools<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(tools: TTools, options: RegisterWebMCPToolsOptions<TTools, TContext>) {\n  if (\n    typeof document === 'undefined' ||\n    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||\n    !('modelContext' in document) ||\n    !isWebMCPModelContext(document.modelContext)\n  ) {\n    return\n  }\n  if (tools.length === 0) {\n    return\n  }\n\n  const names = new Set<string>()\n  const webMCPTools = tools.map((tool) => {\n    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name)) {\n      throw new Error(\n        `WebMCP tool name \"${tool.name}\" must contain 1 to 128 ASCII letters, numbers, underscores, hyphens, or periods.`,\n      )\n    }\n    if (names.has(tool.name)) {\n      throw new Error(`Duplicate WebMCP tool name \"${tool.name}\".`)\n    }\n    if (tool.description.trim() === '') {\n      throw new Error(`WebMCP tool \"${tool.name}\" must have a description.`)\n    }\n    if (typeof tool.execute !== 'function') {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" must have an execute handler.`,\n      )\n    }\n    if (tool.needsApproval === true) {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" cannot use needsApproval: true.`,\n      )\n    }\n\n    names.add(tool.name)\n    const toolOptions = getToolOptions(options.toolOptions, tool.name)\n    const inputSchema = tool.inputSchema\n    const outputSchema = tool.outputSchema\n    const convertedInputSchema = convertSchemaToJsonSchema(inputSchema)\n    const inputSchemaType = convertedInputSchema?.type\n    const requiresNonObjectInput =\n      (typeof inputSchemaType === 'string' && inputSchemaType !== 'object') ||\n      (Array.isArray(inputSchemaType) && !inputSchemaType.includes('object'))\n    if (requiresNonObjectInput) {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" input schema must accept an object.`,\n      )\n    }\n    const execute = tool.execute\n\n    return {\n      name: tool.name,\n      description: tool.description,\n      ...(toolOptions?.title !== undefined ? { title: toolOptions.title } : {}),\n      ...(convertedInputSchema !== undefined\n        ? { inputSchema: convertedInputSchema }\n        : {}),\n      ...(toolOptions?.annotations !== undefined\n        ? { annotations: toolOptions.annotations }\n        : {}),\n      async execute(\n        input: object,\n        executionOptions?: { signal?: AbortSignal },\n      ) {\n        const validatedInput = await validateSchemaValue(inputSchema, input)\n        const output = await execute(validatedInput, {\n          abortSignal: executionOptions?.signal,\n          context: options.context,\n          emitCustomEvent() {},\n        })\n        return validateSchemaValue(outputSchema, output)\n      },\n    }\n  })\n\n  const registrationController = new AbortController()\n  const abortRegistration = () =>\n    registrationController.abort(options.signal.reason)\n\n  if (options.signal.aborted) {\n    abortRegistration()\n  } else {\n    options.signal.addEventListener('abort', abortRegistration, { once: true })\n  }\n\n  try {\n    for (const tool of webMCPTools) {\n      await document.modelContext.registerTool(tool, {\n        signal: registrationController.signal,\n      })\n    }\n  } catch (error) {\n    registrationController.abort(error)\n    options.signal.removeEventListener('abort', abortRegistration)\n    throw error\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"web-mcp-tools.js","names":[],"sources":["../../src/web-mcp-tools.ts"],"sourcesContent":["import {\n  convertSchemaToJsonSchema,\n  validateWithStandardSchema,\n} from '@tanstack/ai/client'\nimport type { AnyClientTool } from '@tanstack/ai/client'\nimport type {\n  ClientContextOptionFromTools,\n  InferredClientContext,\n} from './types'\n\ninterface WebMCPTool {\n  name: string\n  title?: string\n  description: string\n  inputSchema?: object\n  annotations?: WebMCPToolAnnotations\n  execute: (input: object, options: { signal: AbortSignal }) => Promise<unknown>\n}\n\ninterface WebMCPModelContext {\n  registerTool: (\n    tool: WebMCPTool,\n    options: { signal: AbortSignal },\n  ) => Promise<void>\n}\n\n/** WebMCP behavior hints for one registered tool. */\nexport interface WebMCPToolAnnotations {\n  /** Indicates that the tool does not modify state. */\n  readOnlyHint?: boolean\n  /** Indicates that the tool can return content that the application does not trust. */\n  untrustedContentHint?: boolean\n}\n\n/** Display and behavior options for one WebMCP tool. */\nexport interface WebMCPToolOptions {\n  /** A human-readable title for browser user interfaces. */\n  title?: string\n  /** Optional behavior hints for browser agents. */\n  annotations?: WebMCPToolAnnotations\n}\n\n/** WebMCP options keyed by the inferred names in a client tool list. */\nexport type WebMCPToolOptionsByName<\n  TTools extends ReadonlyArray<AnyClientTool>,\n> = Partial<{\n  [TName in TTools[number]['name']]: WebMCPToolOptions\n}>\n\n/**\n * Options for {@link registerWebMCPTools}.\n *\n * The signal controls the registration lifetime. Context is required when a\n * client tool declares a required runtime context.\n */\nexport type RegisterWebMCPToolsOptions<\n  TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n> = {\n  /** Removes all tools from this call when the signal aborts. */\n  signal: AbortSignal\n  /** Per-tool display and behavior options. */\n  toolOptions?: WebMCPToolOptionsByName<TTools>\n} & ClientContextOptionFromTools<TTools, TContext>\n\nfunction isWebMCPModelContext(value: unknown): value is WebMCPModelContext {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'registerTool' in value &&\n    typeof value.registerTool === 'function'\n  )\n}\n\nfunction getToolOptions<TName extends string>(\n  toolOptions: Partial<Record<TName, WebMCPToolOptions>> | undefined,\n  name: TName,\n) {\n  return toolOptions?.[name]\n}\n\nasync function validateSchemaValue(schema: unknown, value: unknown) {\n  const result = await validateWithStandardSchema(schema, value)\n  if (result.success) {\n    return result.data\n  }\n\n  throw new Error(\n    `Validation failed: ${result.issues.map((issue) => issue.message).join(', ')}`,\n  )\n}\n\n/**\n * Registers executable TanStack client tools with the browser WebMCP API.\n *\n * Unsupported browsers and server environments resolve without registration.\n * Abort `options.signal` to remove every tool registered by this call.\n *\n * @param tools - The executable client tools to expose through WebMCP.\n * @param options - The registration signal, runtime context, and per-tool options.\n *\n * @example\n * ```ts\n * const controller = new AbortController()\n * await registerWebMCPTools(tools, { signal: controller.signal })\n * controller.abort()\n * ```\n */\nexport async function registerWebMCPTools<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(tools: TTools, options: RegisterWebMCPToolsOptions<TTools, TContext>) {\n  if (\n    typeof document === 'undefined' ||\n    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||\n    !('modelContext' in document) ||\n    !isWebMCPModelContext(document.modelContext)\n  ) {\n    return\n  }\n  if (tools.length === 0) {\n    return\n  }\n\n  const names = new Set<string>()\n  const webMCPTools = tools.map((tool) => {\n    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name)) {\n      throw new Error(\n        `WebMCP tool name \"${tool.name}\" must contain 1 to 128 ASCII letters, numbers, underscores, hyphens, or periods.`,\n      )\n    }\n    if (names.has(tool.name)) {\n      throw new Error(`Duplicate WebMCP tool name \"${tool.name}\".`)\n    }\n    if (tool.description.trim() === '') {\n      throw new Error(`WebMCP tool \"${tool.name}\" must have a description.`)\n    }\n    if (typeof tool.execute !== 'function') {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" must have an execute handler.`,\n      )\n    }\n    if (tool.needsApproval === true) {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" cannot use needsApproval: true.`,\n      )\n    }\n\n    names.add(tool.name)\n    const toolOptions = getToolOptions(options.toolOptions, tool.name)\n    const inputSchema = tool.inputSchema\n    const outputSchema = tool.outputSchema\n    const convertedInputSchema = convertSchemaToJsonSchema(inputSchema)\n    const inputSchemaType = convertedInputSchema?.type\n    const requiresNonObjectInput =\n      (typeof inputSchemaType === 'string' && inputSchemaType !== 'object') ||\n      (Array.isArray(inputSchemaType) && !inputSchemaType.includes('object'))\n    if (requiresNonObjectInput) {\n      throw new Error(\n        `WebMCP tool \"${tool.name}\" input schema must accept an object.`,\n      )\n    }\n    const execute = tool.execute\n\n    return {\n      name: tool.name,\n      description: tool.description,\n      ...(toolOptions?.title !== undefined ? { title: toolOptions.title } : {}),\n      ...(convertedInputSchema !== undefined\n        ? { inputSchema: convertedInputSchema }\n        : {}),\n      ...(toolOptions?.annotations !== undefined\n        ? { annotations: toolOptions.annotations }\n        : {}),\n      async execute(\n        input: object,\n        executionOptions?: { signal?: AbortSignal },\n      ) {\n        const validatedInput = await validateSchemaValue(inputSchema, input)\n        const output = await execute(validatedInput, {\n          abortSignal: executionOptions?.signal,\n          context: options.context,\n          emitCustomEvent() {},\n        })\n        return validateSchemaValue(outputSchema, output)\n      },\n    }\n  })\n\n  const registrationController = new AbortController()\n  const abortRegistration = () =>\n    registrationController.abort(options.signal.reason)\n\n  if (options.signal.aborted) {\n    abortRegistration()\n  } else {\n    options.signal.addEventListener('abort', abortRegistration, { once: true })\n  }\n\n  try {\n    for (const tool of webMCPTools) {\n      await document.modelContext.registerTool(tool, {\n        signal: registrationController.signal,\n      })\n    }\n  } catch (error) {\n    registrationController.abort(error)\n    options.signal.removeEventListener('abort', abortRegistration)\n    throw error\n  }\n}\n\n/** A tool that a page registered with WebMCP, as `getTools()` returns it. */\nexport interface WebMCPPageTool {\n  name: string\n  title?: string\n  description: string\n  /** A JSON Schema object for the tool input. */\n  inputSchema?: object\n  /** The origin of the document that registered the tool. */\n  origin: string\n  annotations?: WebMCPToolAnnotations\n}\n\ninterface WebMCPToolReader {\n  getTools: () => Promise<Array<WebMCPPageTool>>\n  executeTool: (\n    tool: WebMCPPageTool,\n    input: unknown,\n    options: { signal?: AbortSignal },\n  ) => Promise<string>\n  addEventListener: EventTarget['addEventListener']\n  removeEventListener: EventTarget['removeEventListener']\n}\n\n/** Options for {@link getWebMCPTools}. */\nexport interface GetWebMCPToolsOptions {\n  /** Return `false` to skip a tool. */\n  filter?: (tool: WebMCPPageTool) => boolean\n}\n\n/** Options for {@link subscribeWebMCPTools}. */\nexport interface SubscribeWebMCPToolsOptions extends GetWebMCPToolsOptions {\n  /** Stops the subscription when it aborts. */\n  signal: AbortSignal\n  /** Receives a failure from the WebMCP `getTools()` call. */\n  onError?: (error: unknown) => void\n}\n\nfunction isWebMCPToolReader(value: unknown): value is WebMCPToolReader {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'getTools' in value &&\n    typeof value.getTools === 'function' &&\n    'executeTool' in value &&\n    typeof value.executeTool === 'function' &&\n    'addEventListener' in value &&\n    typeof value.addEventListener === 'function' &&\n    'removeEventListener' in value &&\n    typeof value.removeEventListener === 'function'\n  )\n}\n\nfunction getWebMCPToolReader() {\n  if (\n    typeof document === 'undefined' ||\n    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||\n    !('modelContext' in document) ||\n    !isWebMCPToolReader(document.modelContext)\n  ) {\n    return undefined\n  }\n  return document.modelContext\n}\n\nfunction parseToolResult(result: string): unknown {\n  try {\n    return JSON.parse(result)\n  } catch {\n    return result\n  }\n}\n\nasync function readWebMCPTools(\n  reader: WebMCPToolReader,\n  options: GetWebMCPToolsOptions | undefined,\n): Promise<Array<AnyClientTool>> {\n  const pageTools = await reader.getTools()\n  const names = new Set<string>()\n  return pageTools\n    .filter((tool) => options?.filter?.(tool) ?? true)\n    .map((tool) => {\n      if (names.has(tool.name)) {\n        throw new Error(\n          `Duplicate WebMCP tool name \"${tool.name}\". Use a filter or register tools with unique names.`,\n        )\n      }\n      names.add(tool.name)\n      return {\n        __toolSide: 'client' as const,\n        name: tool.name,\n        description: tool.description,\n        inputSchema: tool.inputSchema ?? { type: 'object' },\n        async execute(input: unknown, context?: { abortSignal?: AbortSignal }) {\n          const result = await reader.executeTool(\n            tool,\n            input,\n            context?.abortSignal ? { signal: context.abortSignal } : {},\n          )\n          return parseToolResult(result)\n        },\n      }\n    })\n}\n\n/**\n * Reads the WebMCP tools on the page and returns them as client tools.\n *\n * Pass the result to a chat as `tools`. Each tool runs through the WebMCP\n * `executeTool()` call. Unsupported browsers and server environments return\n * an empty array.\n *\n * @param options - A filter that skips tools.\n *\n * @example\n * ```ts\n * const tools = await getWebMCPTools({\n *   filter: (tool) => tool.origin === location.origin,\n * })\n * ```\n */\nexport async function getWebMCPTools(\n  options?: GetWebMCPToolsOptions,\n): Promise<Array<AnyClientTool>> {\n  const reader = getWebMCPToolReader()\n  return reader ? readWebMCPTools(reader, options) : []\n}\n\n/**\n * Calls `listener` with the page WebMCP tools now and after each\n * `toolchange` event, until `options.signal` aborts.\n *\n * Unsupported browsers and server environments call `listener` once with an\n * empty array. When a read fails, `options.onError` gets the error and the\n * listener keeps the last list.\n *\n * @param listener - Receives the current client tools.\n * @param options - The subscription signal, a filter, and an error callback.\n *\n * @example\n * ```ts\n * const controller = new AbortController()\n * subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {\n *   signal: controller.signal,\n * })\n * ```\n */\nexport function subscribeWebMCPTools(\n  listener: (tools: Array<AnyClientTool>) => void,\n  options: SubscribeWebMCPToolsOptions,\n): void {\n  if (options.signal.aborted) return\n  const reader = getWebMCPToolReader()\n  if (!reader) {\n    listener([])\n    return\n  }\n\n  let latestRead = 0\n  const refresh = () => {\n    const read = ++latestRead\n    const isCurrent = () => read === latestRead && !options.signal.aborted\n    readWebMCPTools(reader, options).then(\n      (tools) => {\n        if (isCurrent()) listener(tools)\n      },\n      (error: unknown) => {\n        if (isCurrent()) options.onError?.(error)\n      },\n    )\n  }\n\n  // Remove the listener by hand: Zone.js breaks the `signal` listener option.\n  reader.addEventListener('toolchange', refresh)\n  options.signal.addEventListener(\n    'abort',\n    () => reader.removeEventListener('toolchange', refresh),\n    { once: true },\n  )\n  refresh()\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -57,8 +57,8 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "^0.59.0",
-    "@tanstack/ai-event-client": "^0.12.1",
+    "@tanstack/ai": "^0.61.0",
+    "@tanstack/ai-event-client": "^0.13.0",
     "@tanstack/ai-utils": "^0.4.1"
   },
   "devDependencies": {

package/src/chat-client.ts

@@ -330,6 +330,7 @@ const REJOIN_CONNECT_DEADLINE_MS = 2000
 const REJOIN_REBUILD_TRIGGERS = new Set<string>([
   'TEXT_MESSAGE_START',
   'TEXT_MESSAGE_CONTENT',
+  'REASONING_MESSAGE_CONTENT',
   'TOOL_CALL_START',
   'MESSAGES_SNAPSHOT',
   // Drop the hydrated card before this chunk creates it again. A subagent
@@ -337,6 +338,20 @@ const REJOIN_REBUILD_TRIGGERS = new Set<string>([
   'SUBAGENT_STARTED',
 ])
 
+function rebuildsAssistantMessage(chunk: StreamChunk): boolean {
+  if (chunk.type === 'REASONING_ENCRYPTED_VALUE') {
+    return (
+      chunk.subtype === 'message' &&
+      typeof chunk.encryptedValue === 'string' &&
+      chunk.encryptedValue.length > 0
+    )
+  }
+  if (chunk.type === 'STEP_FINISHED') {
+    return 'signature' in chunk && Boolean(chunk.signature)
+  }
+  return REJOIN_REBUILD_TRIGGERS.has(chunk.type)
+}
+
 type SubagentCard = Extract<UIMessage['parts'][number], { type: 'subagent' }>
 
 /** Every subagent card in the messages, nested cards included. */
@@ -506,6 +521,8 @@ export class ChatClient<
   private readonly activeRunIds = new Set<string>()
   /** Latched by `dispose()`; stops any late async callback starting new work. */
   private disposed = false
+  /** The error a failed mount hydration set, cleared by the next successful one. */
+  private hydrationError: Error | undefined
   /** Whether a view is currently watching. See `attach` / `detach`. */
   private tailing = false
   /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
@@ -1124,7 +1141,10 @@ export class ChatClient<
       const generation = this.historyGeneration
       try {
         result = await hydrate(this.threadId, hydrateOptions)
-      } catch {
+      } catch (cause) {
+        // Same staleness guard as the success path below: a failure from an
+        // older attempt must not touch the state of a newer one.
+        if (generation === this.historyGeneration) this.failHydration(cause)
         return
       }
       if (generation !== this.historyGeneration) return
@@ -1140,6 +1160,13 @@ export class ChatClient<
       if (this.disposed || !this.tailing) return
       // A send may have started while the fetch was in flight — don't stomp it.
       if (this.isLoading || this.abortController) return
+      // A retry after a failed load succeeded: drop that failure, but not an
+      // error something else set since.
+      if (this.hydrationError && this.error === this.hydrationError) {
+        this.setError(undefined)
+        this.setStatus('ready')
+      }
+      this.hydrationError = undefined
       this.applyHydrationPage(result.page)
       if (result.messages.length > 0) {
         const windowMessages = normalizeMessagesDates(result.messages)
@@ -1170,6 +1197,36 @@ export class ChatClient<
     })()
   }
 
+  /**
+   * Surface a mount-hydration failure (`persistence: true`) on the observable
+   * fields, mirroring `GenerationClient.failHydration`, so "this thread failed
+   * to load" is distinguishable from "this thread has no messages" and the app
+   * can show an error / offer a retry. A genuine miss — the server having no
+   * record for a fresh thread — resolves normally and never reaches here; only a
+   * thrown transport / authorize-gate error does.
+   *
+   * Skipped when the view unmounted (`!tailing`) or a `sendMessage` took
+   * ownership while the hydrate GET was in flight, so a live run's state always
+   * wins over a stale mount-time failure — same guard as the success path above.
+   */
+  private failHydration(cause: unknown): void {
+    if (this.disposed || !this.tailing) return
+    if (this.isLoading || this.abortController) return
+    const error = cause instanceof Error ? cause : new Error(String(cause))
+    // Mirror the send path: a BYOK key that is missing / locked must still
+    // trigger the key-request flow on thread load, not just be reported.
+    if (error instanceof ByokMissingError) {
+      this.byok?.request(error.provider, 'missing')
+    }
+    if (error instanceof ByokBlockedError && error.reason === 'locked') {
+      this.byok?.request(error.provider, 'locked')
+    }
+    this.hydrationError = error
+    this.setStatus('error')
+    this.setError(error)
+    this.callbacksRef.current.onError(error)
+  }
+
   mountDevtools(): void {
     this.ensureThreadId()
     if (this.devtoolsMounted) {
@@ -1923,7 +1980,7 @@ export class ChatClient<
             attached = true
             clearTimeout(connectTimer)
           }
-          if (!rebuilt && REJOIN_REBUILD_TRIGGERS.has(chunk.type)) {
+          if (!rebuilt && rebuildsAssistantMessage(chunk)) {
             rebuilt = true
             this.dropTrailingInFlightAssistant()
           }

package/src/index.ts

@@ -14,9 +14,16 @@ export type {
 } from './interrupt-manager'
 export { createMcpAppBridge } from './mcp-app-bridge'
 export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge'
-export { registerWebMCPTools } from './web-mcp-tools'
+export {
+  getWebMCPTools,
+  registerWebMCPTools,
+  subscribeWebMCPTools,
+} from './web-mcp-tools'
 export type {
+  GetWebMCPToolsOptions,
   RegisterWebMCPToolsOptions,
+  SubscribeWebMCPToolsOptions,
+  WebMCPPageTool,
   WebMCPToolAnnotations,
   WebMCPToolOptions,
   WebMCPToolOptionsByName,

package/src/web-mcp-tools.ts

@@ -209,3 +209,184 @@ export async function registerWebMCPTools<
     throw error
   }
 }
+
+/** A tool that a page registered with WebMCP, as `getTools()` returns it. */
+export interface WebMCPPageTool {
+  name: string
+  title?: string
+  description: string
+  /** A JSON Schema object for the tool input. */
+  inputSchema?: object
+  /** The origin of the document that registered the tool. */
+  origin: string
+  annotations?: WebMCPToolAnnotations
+}
+
+interface WebMCPToolReader {
+  getTools: () => Promise<Array<WebMCPPageTool>>
+  executeTool: (
+    tool: WebMCPPageTool,
+    input: unknown,
+    options: { signal?: AbortSignal },
+  ) => Promise<string>
+  addEventListener: EventTarget['addEventListener']
+  removeEventListener: EventTarget['removeEventListener']
+}
+
+/** Options for {@link getWebMCPTools}. */
+export interface GetWebMCPToolsOptions {
+  /** Return `false` to skip a tool. */
+  filter?: (tool: WebMCPPageTool) => boolean
+}
+
+/** Options for {@link subscribeWebMCPTools}. */
+export interface SubscribeWebMCPToolsOptions extends GetWebMCPToolsOptions {
+  /** Stops the subscription when it aborts. */
+  signal: AbortSignal
+  /** Receives a failure from the WebMCP `getTools()` call. */
+  onError?: (error: unknown) => void
+}
+
+function isWebMCPToolReader(value: unknown): value is WebMCPToolReader {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'getTools' in value &&
+    typeof value.getTools === 'function' &&
+    'executeTool' in value &&
+    typeof value.executeTool === 'function' &&
+    'addEventListener' in value &&
+    typeof value.addEventListener === 'function' &&
+    'removeEventListener' in value &&
+    typeof value.removeEventListener === 'function'
+  )
+}
+
+function getWebMCPToolReader() {
+  if (
+    typeof document === 'undefined' ||
+    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||
+    !('modelContext' in document) ||
+    !isWebMCPToolReader(document.modelContext)
+  ) {
+    return undefined
+  }
+  return document.modelContext
+}
+
+function parseToolResult(result: string): unknown {
+  try {
+    return JSON.parse(result)
+  } catch {
+    return result
+  }
+}
+
+async function readWebMCPTools(
+  reader: WebMCPToolReader,
+  options: GetWebMCPToolsOptions | undefined,
+): Promise<Array<AnyClientTool>> {
+  const pageTools = await reader.getTools()
+  const names = new Set<string>()
+  return pageTools
+    .filter((tool) => options?.filter?.(tool) ?? true)
+    .map((tool) => {
+      if (names.has(tool.name)) {
+        throw new Error(
+          `Duplicate WebMCP tool name "${tool.name}". Use a filter or register tools with unique names.`,
+        )
+      }
+      names.add(tool.name)
+      return {
+        __toolSide: 'client' as const,
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema ?? { type: 'object' },
+        async execute(input: unknown, context?: { abortSignal?: AbortSignal }) {
+          const result = await reader.executeTool(
+            tool,
+            input,
+            context?.abortSignal ? { signal: context.abortSignal } : {},
+          )
+          return parseToolResult(result)
+        },
+      }
+    })
+}
+
+/**
+ * Reads the WebMCP tools on the page and returns them as client tools.
+ *
+ * Pass the result to a chat as `tools`. Each tool runs through the WebMCP
+ * `executeTool()` call. Unsupported browsers and server environments return
+ * an empty array.
+ *
+ * @param options - A filter that skips tools.
+ *
+ * @example
+ * ```ts
+ * const tools = await getWebMCPTools({
+ *   filter: (tool) => tool.origin === location.origin,
+ * })
+ * ```
+ */
+export async function getWebMCPTools(
+  options?: GetWebMCPToolsOptions,
+): Promise<Array<AnyClientTool>> {
+  const reader = getWebMCPToolReader()
+  return reader ? readWebMCPTools(reader, options) : []
+}
+
+/**
+ * Calls `listener` with the page WebMCP tools now and after each
+ * `toolchange` event, until `options.signal` aborts.
+ *
+ * Unsupported browsers and server environments call `listener` once with an
+ * empty array. When a read fails, `options.onError` gets the error and the
+ * listener keeps the last list.
+ *
+ * @param listener - Receives the current client tools.
+ * @param options - The subscription signal, a filter, and an error callback.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * subscribeWebMCPTools((tools) => client.updateOptions({ tools }), {
+ *   signal: controller.signal,
+ * })
+ * ```
+ */
+export function subscribeWebMCPTools(
+  listener: (tools: Array<AnyClientTool>) => void,
+  options: SubscribeWebMCPToolsOptions,
+): void {
+  if (options.signal.aborted) return
+  const reader = getWebMCPToolReader()
+  if (!reader) {
+    listener([])
+    return
+  }
+
+  let latestRead = 0
+  const refresh = () => {
+    const read = ++latestRead
+    const isCurrent = () => read === latestRead && !options.signal.aborted
+    readWebMCPTools(reader, options).then(
+      (tools) => {
+        if (isCurrent()) listener(tools)
+      },
+      (error: unknown) => {
+        if (isCurrent()) options.onError?.(error)
+      },
+    )
+  }
+
+  // Remove the listener by hand: Zone.js breaks the `signal` listener option.
+  reader.addEventListener('toolchange', refresh)
+  options.signal.addEventListener(
+    'abort',
+    () => reader.removeEventListener('toolchange', refresh),
+    { once: true },
+  )
+  refresh()
+}