@tanstack/ai-client 0.30.0 → 0.31.0

package/dist/esm/index.d.ts

@@ -5,6 +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 { RealtimeClient } from './realtime-client.js';
 export { GenerationClient } from './generation-client.js';
 export { VideoGenerationClient } from './video-generation-client.js';

package/dist/esm/index.js

@@ -4,6 +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 { RealtimeClient } from "./realtime-client.js";
 import { GENERATION_EVENTS } from "./generation-types.js";
 import { GenerationClient } from "./generation-client.js";
@@ -13,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, 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, indexedDBPersistence, localStoragePersistence, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, reconstructAudioResult, reconstructImageResult, reconstructSpeechResult, reconstructSummarizeResult, reconstructTranscriptionResult, registerWebMCPTools, rpcStream, sessionStoragePersistence, stream, uiMessageToModelMessages, webSocket, xhrHttpStream, xhrServerSentEvents };

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

@@ -0,0 +1,49 @@
+import { AnyClientTool } from '@tanstack/ai/client';
+import { ClientContextOptionFromTools, InferredClientContext } from './types.js';
+/** WebMCP behavior hints for one registered tool. */
+export interface WebMCPToolAnnotations {
+    /** Indicates that the tool does not modify state. */
+    readOnlyHint?: boolean;
+    /** Indicates that the tool can return content that the application does not trust. */
+    untrustedContentHint?: boolean;
+}
+/** Display and behavior options for one WebMCP tool. */
+export interface WebMCPToolOptions {
+    /** A human-readable title for browser user interfaces. */
+    title?: string;
+    /** Optional behavior hints for browser agents. */
+    annotations?: WebMCPToolAnnotations;
+}
+/** WebMCP options keyed by the inferred names in a client tool list. */
+export type WebMCPToolOptionsByName<TTools extends ReadonlyArray<AnyClientTool>> = Partial<{
+    [TName in TTools[number]['name']]: WebMCPToolOptions;
+}>;
+/**
+ * Options for {@link registerWebMCPTools}.
+ *
+ * The signal controls the registration lifetime. Context is required when a
+ * client tool declares a required runtime context.
+ */
+export type RegisterWebMCPToolsOptions<TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>> = {
+    /** Removes all tools from this call when the signal aborts. */
+    signal: AbortSignal;
+    /** Per-tool display and behavior options. */
+    toolOptions?: WebMCPToolOptionsByName<TTools>;
+} & ClientContextOptionFromTools<TTools, TContext>;
+/**
+ * Registers executable TanStack client tools with the browser WebMCP API.
+ *
+ * Unsupported browsers and server environments resolve without registration.
+ * Abort `options.signal` to remove every tool registered by this call.
+ *
+ * @param tools - The executable client tools to expose through WebMCP.
+ * @param options - The registration signal, runtime context, and per-tool options.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * await registerWebMCPTools(tools, { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+export declare function registerWebMCPTools<const TTools extends ReadonlyArray<AnyClientTool>, TContext = InferredClientContext<TTools>>(tools: TTools, options: RegisterWebMCPToolsOptions<TTools, TContext>): Promise<void>;

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

@@ -0,0 +1,80 @@
+import { convertSchemaToJsonSchema, validateWithStandardSchema } from "@tanstack/ai/client";
+//#region src/web-mcp-tools.ts
+function isWebMCPModelContext(value) {
+	return value !== null && typeof value === "object" && "registerTool" in value && typeof value.registerTool === "function";
+}
+function getToolOptions(toolOptions, name) {
+	return toolOptions?.[name];
+}
+async function validateSchemaValue(schema, value) {
+	const result = await validateWithStandardSchema(schema, value);
+	if (result.success) return result.data;
+	throw new Error(`Validation failed: ${result.issues.map((issue) => issue.message).join(", ")}`);
+}
+/**
+* Registers executable TanStack client tools with the browser WebMCP API.
+*
+* Unsupported browsers and server environments resolve without registration.
+* Abort `options.signal` to remove every tool registered by this call.
+*
+* @param tools - The executable client tools to expose through WebMCP.
+* @param options - The registration signal, runtime context, and per-tool options.
+*
+* @example
+* ```ts
+* const controller = new AbortController()
+* await registerWebMCPTools(tools, { signal: controller.signal })
+* controller.abort()
+* ```
+*/
+async function registerWebMCPTools(tools, options) {
+	if (typeof document === "undefined" || typeof isSecureContext !== "undefined" && !isSecureContext || !("modelContext" in document) || !isWebMCPModelContext(document.modelContext)) return;
+	if (tools.length === 0) return;
+	const names = /* @__PURE__ */ new Set();
+	const webMCPTools = tools.map((tool) => {
+		if (!/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name)) throw new Error(`WebMCP tool name "${tool.name}" must contain 1 to 128 ASCII letters, numbers, underscores, hyphens, or periods.`);
+		if (names.has(tool.name)) throw new Error(`Duplicate WebMCP tool name "${tool.name}".`);
+		if (tool.description.trim() === "") throw new Error(`WebMCP tool "${tool.name}" must have a description.`);
+		if (typeof tool.execute !== "function") throw new Error(`WebMCP tool "${tool.name}" must have an execute handler.`);
+		if (tool.needsApproval === true) throw new Error(`WebMCP tool "${tool.name}" cannot use needsApproval: true.`);
+		names.add(tool.name);
+		const toolOptions = getToolOptions(options.toolOptions, tool.name);
+		const inputSchema = tool.inputSchema;
+		const outputSchema = tool.outputSchema;
+		const convertedInputSchema = convertSchemaToJsonSchema(inputSchema);
+		const inputSchemaType = convertedInputSchema?.type;
+		if (typeof inputSchemaType === "string" && inputSchemaType !== "object" || Array.isArray(inputSchemaType) && !inputSchemaType.includes("object")) throw new Error(`WebMCP tool "${tool.name}" input schema must accept an object.`);
+		const execute = tool.execute;
+		return {
+			name: tool.name,
+			description: tool.description,
+			...toolOptions?.title !== void 0 ? { title: toolOptions.title } : {},
+			...convertedInputSchema !== void 0 ? { inputSchema: convertedInputSchema } : {},
+			...toolOptions?.annotations !== void 0 ? { annotations: toolOptions.annotations } : {},
+			async execute(input, executionOptions) {
+				const validatedInput = await validateSchemaValue(inputSchema, input);
+				const output = await execute(validatedInput, {
+					abortSignal: executionOptions?.signal,
+					context: options.context,
+					emitCustomEvent() {}
+				});
+				return validateSchemaValue(outputSchema, output);
+			}
+		};
+	});
+	const registrationController = new AbortController();
+	const abortRegistration = () => registrationController.abort(options.signal.reason);
+	if (options.signal.aborted) abortRegistration();
+	else options.signal.addEventListener("abort", abortRegistration, { once: true });
+	try {
+		for (const tool of webMCPTools) await document.modelContext.registerTool(tool, { signal: registrationController.signal });
+	} catch (error) {
+		registrationController.abort(error);
+		options.signal.removeEventListener("abort", abortRegistration);
+		throw error;
+	}
+}
+//#endregion
+export { registerWebMCPTools };
+
+//# sourceMappingURL=web-mcp-tools.js.map

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

@@ -0,0 +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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "^0.52.1",
+    "@tanstack/ai": "^0.53.0",
     "@tanstack/ai-event-client": "^0.11.2",
     "@tanstack/ai-utils": "^0.4.0"
   },

package/src/byok/client.ts

@@ -5,7 +5,7 @@ import {
   maskKey,
 } from '@tanstack/ai/byok'
 import { memoryStorage } from './storage'
-import type { ProviderId } from '@tanstack/ai/byok'
+import type { ByokProvider, ProviderId } from '@tanstack/ai/byok'
 import type { Keyring, KeyringStorage } from './storage'
 
 export type KeyStatus =
@@ -28,6 +28,11 @@ export type ByokSnapshot = {
 
 export interface DefineByokOptions {
   storage?: KeyringStorage
+  /**
+   * Descriptors whose `with` companions the store expands: `headers()` and
+   * `prepare()` for such a provider cover its companions too.
+   */
+  providers?: ReadonlyArray<ByokProvider>
 }
 
 export const EMPTY_BYOK_SNAPSHOT: ByokSnapshot = {
@@ -85,6 +90,7 @@ export class ByokClient {
   #prompt: ByokPrompt | null = null
   #coverageAll = false
   #coverage: Record<string, boolean> = {}
+  readonly #companions: Record<string, Array<ProviderId>> = {}
   readonly #listeners = new Set<() => void>()
   #snapshot: ByokSnapshot
   #storageError: string | null = null
@@ -92,6 +98,13 @@ export class ByokClient {
 
   constructor(options: DefineByokOptions = {}) {
     this.storage = options.storage ?? memoryStorage()
+    for (const provider of options.providers ?? []) {
+      if (provider.with?.length) {
+        this.#companions[requireProviderId(provider.id)] = provider.with.map(
+          (companion) => requireProviderId(companion.id),
+        )
+      }
+    }
     this.#locked = Boolean(this.storage.unlockable)
     this.#snapshot = this.#buildSnapshot()
     this.#ready = this.#hydrate()
@@ -146,12 +159,19 @@ export class ByokClient {
     return this.#coverageAll || this.#coverage[provider] === true
   }
 
+  /** The slug plus every companion declared on its descriptor. */
+  #expand(provider: ProviderId): Array<ProviderId> {
+    return [provider, ...(this.#companions[provider] ?? [])]
+  }
+
   headers(provider?: ProviderId): Record<string, string> {
     const headers: Record<string, string> = {}
     if (provider) {
       requireProviderId(provider)
-      const key = this.#keys[provider]
-      if (key) headers[byokHeaderName(provider)] = key
+      for (const id of this.#expand(provider)) {
+        const key = this.#keys[id]
+        if (key) headers[byokHeaderName(id)] = key
+      }
       return headers
     }
     for (const [id, key] of Object.entries(this.#keys)) {
@@ -167,10 +187,11 @@ export class ByokClient {
     }
     if (!provider) return
     requireProviderId(provider)
-    if (this.#keys[provider]) return
-    if (this.#hasCoverage(provider)) return
-    this.request(provider, 'missing')
-    throw new ByokBlockedError(provider, 'missing')
+    for (const id of this.#expand(provider)) {
+      if (this.#keys[id] || this.#hasCoverage(id)) continue
+      this.request(id, 'missing')
+      throw new ByokBlockedError(id, 'missing')
+    }
   }
 
   async update(

package/src/chat-client.ts

@@ -2023,7 +2023,7 @@ export class ChatClient<
     if (emptyMessage) {
       return
     }
-    if (this.hasBlockingInterrupts()) {
+    if (this.hasPendingInterrupts()) {
       throw new Error(
         'ChatClient: cannot send normal input while pending interrupts exist. Use resumeInterrupts() instead.',
       )
@@ -2065,14 +2065,6 @@ export class ChatClient<
     return this.interruptManager.getDescriptors().length > 0
   }
 
-  /** True while an interrupt batch owns the next user turn. */
-  private hasBlockingInterrupts(): boolean {
-    return (
-      this.activeInterruptSubmission !== undefined ||
-      this.hasPendingInterrupts()
-    )
-  }
-
   /** True while a stream is active, a send is claiming the client, or the queue is draining. */
   private isSendBusy(): boolean {
     return this.isLoading || this.sendInFlight || this.messageQueueDraining
@@ -2188,7 +2180,7 @@ export class ChatClient<
    */
   async append(message: UIMessage | ModelMessage): Promise<void> {
     this.mountDevtools()
-    if (this.hasBlockingInterrupts()) {
+    if (this.hasPendingInterrupts()) {
       throw new Error(
         'ChatClient: cannot append normal input while pending interrupts exist. Use resumeInterrupts() instead.',
       )

package/src/index.ts

@@ -14,6 +14,13 @@ 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 type {
+  RegisterWebMCPToolsOptions,
+  WebMCPToolAnnotations,
+  WebMCPToolOptions,
+  WebMCPToolOptionsByName,
+} from './web-mcp-tools'
 export { RealtimeClient } from './realtime-client'
 export { GenerationClient } from './generation-client'
 export { VideoGenerationClient } from './video-generation-client'

package/src/web-mcp-tools.ts

@@ -0,0 +1,211 @@
+import {
+  convertSchemaToJsonSchema,
+  validateWithStandardSchema,
+} from '@tanstack/ai/client'
+import type { AnyClientTool } from '@tanstack/ai/client'
+import type {
+  ClientContextOptionFromTools,
+  InferredClientContext,
+} from './types'
+
+interface WebMCPTool {
+  name: string
+  title?: string
+  description: string
+  inputSchema?: object
+  annotations?: WebMCPToolAnnotations
+  execute: (input: object, options: { signal: AbortSignal }) => Promise<unknown>
+}
+
+interface WebMCPModelContext {
+  registerTool: (
+    tool: WebMCPTool,
+    options: { signal: AbortSignal },
+  ) => Promise<void>
+}
+
+/** WebMCP behavior hints for one registered tool. */
+export interface WebMCPToolAnnotations {
+  /** Indicates that the tool does not modify state. */
+  readOnlyHint?: boolean
+  /** Indicates that the tool can return content that the application does not trust. */
+  untrustedContentHint?: boolean
+}
+
+/** Display and behavior options for one WebMCP tool. */
+export interface WebMCPToolOptions {
+  /** A human-readable title for browser user interfaces. */
+  title?: string
+  /** Optional behavior hints for browser agents. */
+  annotations?: WebMCPToolAnnotations
+}
+
+/** WebMCP options keyed by the inferred names in a client tool list. */
+export type WebMCPToolOptionsByName<
+  TTools extends ReadonlyArray<AnyClientTool>,
+> = Partial<{
+  [TName in TTools[number]['name']]: WebMCPToolOptions
+}>
+
+/**
+ * Options for {@link registerWebMCPTools}.
+ *
+ * The signal controls the registration lifetime. Context is required when a
+ * client tool declares a required runtime context.
+ */
+export type RegisterWebMCPToolsOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+> = {
+  /** Removes all tools from this call when the signal aborts. */
+  signal: AbortSignal
+  /** Per-tool display and behavior options. */
+  toolOptions?: WebMCPToolOptionsByName<TTools>
+} & ClientContextOptionFromTools<TTools, TContext>
+
+function isWebMCPModelContext(value: unknown): value is WebMCPModelContext {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'registerTool' in value &&
+    typeof value.registerTool === 'function'
+  )
+}
+
+function getToolOptions<TName extends string>(
+  toolOptions: Partial<Record<TName, WebMCPToolOptions>> | undefined,
+  name: TName,
+) {
+  return toolOptions?.[name]
+}
+
+async function validateSchemaValue(schema: unknown, value: unknown) {
+  const result = await validateWithStandardSchema(schema, value)
+  if (result.success) {
+    return result.data
+  }
+
+  throw new Error(
+    `Validation failed: ${result.issues.map((issue) => issue.message).join(', ')}`,
+  )
+}
+
+/**
+ * Registers executable TanStack client tools with the browser WebMCP API.
+ *
+ * Unsupported browsers and server environments resolve without registration.
+ * Abort `options.signal` to remove every tool registered by this call.
+ *
+ * @param tools - The executable client tools to expose through WebMCP.
+ * @param options - The registration signal, runtime context, and per-tool options.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * await registerWebMCPTools(tools, { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+export async function registerWebMCPTools<
+  const TTools extends ReadonlyArray<AnyClientTool>,
+  TContext = InferredClientContext<TTools>,
+>(tools: TTools, options: RegisterWebMCPToolsOptions<TTools, TContext>) {
+  if (
+    typeof document === 'undefined' ||
+    (typeof isSecureContext !== 'undefined' && !isSecureContext) ||
+    !('modelContext' in document) ||
+    !isWebMCPModelContext(document.modelContext)
+  ) {
+    return
+  }
+  if (tools.length === 0) {
+    return
+  }
+
+  const names = new Set<string>()
+  const webMCPTools = tools.map((tool) => {
+    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(tool.name)) {
+      throw new Error(
+        `WebMCP tool name "${tool.name}" must contain 1 to 128 ASCII letters, numbers, underscores, hyphens, or periods.`,
+      )
+    }
+    if (names.has(tool.name)) {
+      throw new Error(`Duplicate WebMCP tool name "${tool.name}".`)
+    }
+    if (tool.description.trim() === '') {
+      throw new Error(`WebMCP tool "${tool.name}" must have a description.`)
+    }
+    if (typeof tool.execute !== 'function') {
+      throw new Error(
+        `WebMCP tool "${tool.name}" must have an execute handler.`,
+      )
+    }
+    if (tool.needsApproval === true) {
+      throw new Error(
+        `WebMCP tool "${tool.name}" cannot use needsApproval: true.`,
+      )
+    }
+
+    names.add(tool.name)
+    const toolOptions = getToolOptions(options.toolOptions, tool.name)
+    const inputSchema = tool.inputSchema
+    const outputSchema = tool.outputSchema
+    const convertedInputSchema = convertSchemaToJsonSchema(inputSchema)
+    const inputSchemaType = convertedInputSchema?.type
+    const requiresNonObjectInput =
+      (typeof inputSchemaType === 'string' && inputSchemaType !== 'object') ||
+      (Array.isArray(inputSchemaType) && !inputSchemaType.includes('object'))
+    if (requiresNonObjectInput) {
+      throw new Error(
+        `WebMCP tool "${tool.name}" input schema must accept an object.`,
+      )
+    }
+    const execute = tool.execute
+
+    return {
+      name: tool.name,
+      description: tool.description,
+      ...(toolOptions?.title !== undefined ? { title: toolOptions.title } : {}),
+      ...(convertedInputSchema !== undefined
+        ? { inputSchema: convertedInputSchema }
+        : {}),
+      ...(toolOptions?.annotations !== undefined
+        ? { annotations: toolOptions.annotations }
+        : {}),
+      async execute(
+        input: object,
+        executionOptions?: { signal?: AbortSignal },
+      ) {
+        const validatedInput = await validateSchemaValue(inputSchema, input)
+        const output = await execute(validatedInput, {
+          abortSignal: executionOptions?.signal,
+          context: options.context,
+          emitCustomEvent() {},
+        })
+        return validateSchemaValue(outputSchema, output)
+      },
+    }
+  })
+
+  const registrationController = new AbortController()
+  const abortRegistration = () =>
+    registrationController.abort(options.signal.reason)
+
+  if (options.signal.aborted) {
+    abortRegistration()
+  } else {
+    options.signal.addEventListener('abort', abortRegistration, { once: true })
+  }
+
+  try {
+    for (const tool of webMCPTools) {
+      await document.modelContext.registerTool(tool, {
+        signal: registrationController.signal,
+      })
+    }
+  } catch (error) {
+    registrationController.abort(error)
+    options.signal.removeEventListener('abort', abortRegistration)
+    throw error
+  }
+}