@tanstack/ai-client 0.29.2 → 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/ui/selectors.d.ts

@@ -0,0 +1,11 @@
+import { UIMessage } from '../types.js';
+import { ChatUIInterrupt, ChatUIPartKey, ChatUISelectInput, ChatUISelectedMessage, ChatUISelectedPart, ChatUISelection } from './types.js';
+export declare function partTypeToKey(type: string): ChatUIPartKey | string;
+export declare function collectInlineToolNames(toolInterrupts?: Record<string, unknown>, mappedToolNames?: ReadonlyArray<string>): Array<string>;
+export declare function resolveInterruptComponent(interrupt: ChatUIInterrupt, interruptsMap: {
+    tools?: Record<string, unknown>;
+    generic?: Record<string, unknown>;
+} | undefined): unknown;
+export declare function selectChatUI(input: ChatUISelectInput): ChatUISelection;
+export declare function automaticPartsForMessage(selected: ChatUISelectedMessage): Array<ChatUISelectedPart>;
+export declare function selectMessageUI(message: UIMessage, input: Omit<ChatUISelectInput, 'messages'>): ChatUISelectedMessage;

package/dist/esm/ui/selectors.js

@@ -0,0 +1,106 @@
+//#region src/ui/selectors.ts
+var PART_KEY_BY_TYPE = {
+	text: "text",
+	image: "image",
+	audio: "audio",
+	video: "video",
+	document: "document",
+	thinking: "thinking",
+	"tool-call": "toolCall",
+	"tool-result": "toolResult",
+	"structured-output": "structuredOutput",
+	"ui-resource": "uiResource"
+};
+function partTypeToKey(type) {
+	const mapped = PART_KEY_BY_TYPE[type];
+	if (mapped) return mapped;
+	return type.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function collectInlineToolNames(toolInterrupts, mappedToolNames) {
+	const listPlaced = new Set(Object.keys(toolInterrupts ?? {}));
+	return (mappedToolNames ?? []).filter((name) => !listPlaced.has(name));
+}
+function resolveInterruptComponent(interrupt, interruptsMap) {
+	if (!interruptsMap) return void 0;
+	if (interrupt.kind === "tool-approval") return interruptsMap.tools?.[interrupt.toolName];
+	const generic = interruptsMap.generic;
+	if (!generic) return void 0;
+	const definitionId = "definitionId" in interrupt && typeof interrupt.definitionId === "string" ? interrupt.definitionId : void 0;
+	if (definitionId && definitionId !== "fallback") {
+		const registered = generic[definitionId];
+		if (registered) return registered;
+	}
+	return generic.fallback;
+}
+function isToolCallPart(part) {
+	return part.type === "tool-call";
+}
+function isToolResultPart(part) {
+	return part.type === "tool-result";
+}
+function isToolApproval(interrupt) {
+	return interrupt.kind === "tool-approval";
+}
+function selectChatUI(input) {
+	const messages = input.messages;
+	const interrupts = input.interrupts ?? [];
+	const inlineToolNames = new Set(input.inlineToolNames ?? []);
+	const resultsByCallId = /* @__PURE__ */ new Map();
+	const callIds = /* @__PURE__ */ new Set();
+	for (const message of messages) for (const part of message.parts) {
+		if (isToolCallPart(part)) callIds.add(part.id);
+		if (isToolResultPart(part)) resultsByCallId.set(part.toolCallId, part);
+	}
+	const approvalByCallId = /* @__PURE__ */ new Map();
+	for (const interrupt of interrupts) if (isToolApproval(interrupt)) approvalByCallId.set(interrupt.toolCallId, interrupt);
+	return {
+		messages: messages.map((message) => ({
+			message,
+			parts: message.parts.map((part) => toSelectedPart(part, resultsByCallId, approvalByCallId, callIds))
+		})),
+		interrupts: interrupts.filter((interrupt) => {
+			if (!isToolApproval(interrupt)) return true;
+			if (!inlineToolNames.has(interrupt.toolName)) return true;
+			return !callIds.has(interrupt.toolCallId);
+		})
+	};
+}
+function toSelectedPart(part, resultsByCallId, approvalByCallId, callIds) {
+	if (isToolCallPart(part)) {
+		const result = resultsByCallId.get(part.id);
+		const interrupt = approvalByCallId.get(part.id);
+		return {
+			key: "toolCall",
+			part,
+			...result ? { result } : {},
+			...interrupt ? { interrupt } : {},
+			input: part.input,
+			output: part.output
+		};
+	}
+	if (isToolResultPart(part)) return {
+		key: "toolResult",
+		part,
+		matched: callIds.has(part.toolCallId)
+	};
+	return {
+		key: partTypeToKey(part.type),
+		part
+	};
+}
+function automaticPartsForMessage(selected) {
+	return selected.parts.filter((part) => !(part.key === "toolResult" && part.matched));
+}
+function selectMessageUI(message, input) {
+	return selectChatUI({
+		...input,
+		messages: [message]
+	}).messages[0] ?? {
+		message,
+		parts: []
+	};
+}
+//#endregion
+export { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI };
+
+//# sourceMappingURL=selectors.js.map

package/dist/esm/ui/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","names":[],"sources":["../../../src/ui/selectors.ts"],"sourcesContent":["import type {\n  MessagePart,\n  ToolApprovalInterrupt,\n  ToolCallPart,\n  ToolResultPart,\n  UIMessage,\n} from '../types'\nimport type {\n  ChatUIInterrupt,\n  ChatUIPartKey,\n  ChatUISelectInput,\n  ChatUISelectedMessage,\n  ChatUISelectedPart,\n  ChatUISelection,\n} from './types'\n\nconst PART_KEY_BY_TYPE: Record<string, ChatUIPartKey> = {\n  text: 'text',\n  image: 'image',\n  audio: 'audio',\n  video: 'video',\n  document: 'document',\n  thinking: 'thinking',\n  'tool-call': 'toolCall',\n  'tool-result': 'toolResult',\n  'structured-output': 'structuredOutput',\n  'ui-resource': 'uiResource',\n}\n\nexport function partTypeToKey(type: string): ChatUIPartKey | string {\n  const mapped = PART_KEY_BY_TYPE[type]\n  if (mapped) return mapped\n  return type.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())\n}\n\nexport function collectInlineToolNames(\n  toolInterrupts?: Record<string, unknown>,\n  mappedToolNames?: ReadonlyArray<string>,\n): Array<string> {\n  const listPlaced = new Set(Object.keys(toolInterrupts ?? {}))\n  return (mappedToolNames ?? []).filter((name) => !listPlaced.has(name))\n}\n\nexport function resolveInterruptComponent(\n  interrupt: ChatUIInterrupt,\n  interruptsMap:\n    | {\n        tools?: Record<string, unknown>\n        generic?: Record<string, unknown>\n      }\n    | undefined,\n): unknown {\n  if (!interruptsMap) return undefined\n  if (interrupt.kind === 'tool-approval') {\n    return interruptsMap.tools?.[interrupt.toolName]\n  }\n  const generic = interruptsMap.generic\n  if (!generic) return undefined\n  const definitionId =\n    'definitionId' in interrupt && typeof interrupt.definitionId === 'string'\n      ? interrupt.definitionId\n      : undefined\n  if (definitionId && definitionId !== 'fallback') {\n    const registered = generic[definitionId]\n    if (registered) return registered\n  }\n  return generic.fallback\n}\n\nfunction isToolCallPart(part: MessagePart): part is ToolCallPart {\n  return part.type === 'tool-call'\n}\n\nfunction isToolResultPart(part: MessagePart): part is ToolResultPart {\n  return part.type === 'tool-result'\n}\n\nfunction isToolApproval(\n  interrupt: ChatUIInterrupt,\n): interrupt is ToolApprovalInterrupt {\n  return interrupt.kind === 'tool-approval'\n}\n\nexport function selectChatUI(input: ChatUISelectInput): ChatUISelection {\n  const messages = input.messages\n  const interrupts = input.interrupts ?? []\n  const inlineToolNames = new Set(input.inlineToolNames ?? [])\n\n  const resultsByCallId = new Map<string, ToolResultPart>()\n  const callIds = new Set<string>()\n  for (const message of messages) {\n    for (const part of message.parts) {\n      if (isToolCallPart(part)) callIds.add(part.id)\n      if (isToolResultPart(part)) resultsByCallId.set(part.toolCallId, part)\n    }\n  }\n\n  const approvalByCallId = new Map<string, ToolApprovalInterrupt>()\n  for (const interrupt of interrupts) {\n    if (isToolApproval(interrupt)) {\n      approvalByCallId.set(interrupt.toolCallId, interrupt)\n    }\n  }\n\n  const selectedMessages: Array<ChatUISelectedMessage> = messages.map(\n    (message) => ({\n      message,\n      parts: message.parts.map((part) =>\n        toSelectedPart(part, resultsByCallId, approvalByCallId, callIds),\n      ),\n    }),\n  )\n\n  return {\n    messages: selectedMessages,\n    interrupts: interrupts.filter((interrupt) => {\n      if (!isToolApproval(interrupt)) return true\n      if (!inlineToolNames.has(interrupt.toolName)) return true\n      return !callIds.has(interrupt.toolCallId)\n    }),\n  }\n}\n\nfunction toSelectedPart(\n  part: MessagePart,\n  resultsByCallId: Map<string, ToolResultPart>,\n  approvalByCallId: Map<string, ToolApprovalInterrupt>,\n  callIds: Set<string>,\n): ChatUISelectedPart {\n  if (isToolCallPart(part)) {\n    const result = resultsByCallId.get(part.id)\n    const interrupt = approvalByCallId.get(part.id)\n    return {\n      key: 'toolCall',\n      part,\n      ...(result ? { result } : {}),\n      ...(interrupt ? { interrupt } : {}),\n      input: part.input,\n      output: part.output,\n    }\n  }\n\n  if (isToolResultPart(part)) {\n    return {\n      key: 'toolResult',\n      part,\n      matched: callIds.has(part.toolCallId),\n    }\n  }\n\n  return {\n    key: partTypeToKey(part.type) as Exclude<\n      ChatUIPartKey,\n      'toolCall' | 'toolResult'\n    >,\n    part,\n  }\n}\n\nexport function automaticPartsForMessage(\n  selected: ChatUISelectedMessage,\n): Array<ChatUISelectedPart> {\n  return selected.parts.filter(\n    (part) => !(part.key === 'toolResult' && part.matched),\n  )\n}\n\nexport function selectMessageUI(\n  message: UIMessage,\n  input: Omit<ChatUISelectInput, 'messages'>,\n): ChatUISelectedMessage {\n  return (\n    selectChatUI({ ...input, messages: [message] }).messages[0] ?? {\n      message,\n      parts: [],\n    }\n  )\n}\n"],"mappings":"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"}

package/dist/esm/ui/types.d.ts

@@ -0,0 +1,103 @@
+import { AnyClientTool, InferSchemaType, InferToolInput, InferToolOutput, InterruptDefinition, SchemaInput } from '@tanstack/ai/client';
+import { ChatInterrupt, MessagePart, RegisteredGenericInterrupt, StructuredOutputPart, ToolApprovalInterrupt, ToolCallPart, ToolResultPart, UIMessage } from '../types.js';
+export type ChatUIPartKey = 'text' | 'image' | 'audio' | 'video' | 'document' | 'thinking' | 'toolCall' | 'toolResult' | 'structuredOutput' | 'uiResource';
+export type ChatUIPartTypeByKey = {
+    text: 'text';
+    image: 'image';
+    audio: 'audio';
+    video: 'video';
+    document: 'document';
+    thinking: 'thinking';
+    toolCall: 'tool-call';
+    toolResult: 'tool-result';
+    structuredOutput: 'structured-output';
+    uiResource: 'ui-resource';
+};
+export type ChatUIPartOf<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = TKey extends ChatUIPartKey ? Extract<MessagePart<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>, {
+    type: ChatUIPartTypeByKey[TKey];
+}> : never;
+export type ChatUIToolsOf<TOptions> = TOptions extends {
+    tools: infer TTools;
+} ? TTools extends ReadonlyArray<AnyClientTool> ? TTools : any : any;
+export type ChatUIInterruptsOf<TOptions> = TOptions extends {
+    interrupts: infer TInterrupts;
+} ? TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> ? TInterrupts : readonly [] : readonly [];
+export type ChatUISchemaOf<TOptions> = TOptions extends {
+    outputSchema: infer TSchema;
+} ? TSchema extends SchemaInput ? TSchema : undefined : undefined;
+export type ChatUIData<TOptions> = TOptions extends {
+    outputSchema: infer TSchema;
+} ? TSchema extends SchemaInput ? InferSchemaType<TSchema> : unknown : unknown;
+export type ChatUIToolName<TOptions> = ChatUIToolsOf<TOptions>[number] extends infer TTool ? TTool extends AnyClientTool ? TTool['name'] : string : string;
+export type ChatUIRegisteredInterruptId<TOptions> = ChatUIInterruptsOf<TOptions>[number] extends infer TDefinition ? TDefinition extends InterruptDefinition<infer TId, any, any, any> ? TId : string : string;
+export type ChatUIHasNamedTools<TOptions> = [ChatUIToolName<TOptions>] extends [
+    never
+] ? false : [string] extends [ChatUIToolName<TOptions>] ? false : true;
+export type ChatUIHasNamedInterrupts<TOptions> = [
+    ChatUIRegisteredInterruptId<TOptions>
+] extends [never] ? false : [string] extends [ChatUIRegisteredInterruptId<TOptions>] ? false : true;
+export type ChatUINamedInterruptId<TOptions> = Exclude<ChatUIRegisteredInterruptId<TOptions>, 'fallback'>;
+export type ChatUIInterruptName<TOptions> = (ChatUIHasNamedTools<TOptions> extends true ? ChatUIToolName<TOptions> : never) | (ChatUIHasNamedInterrupts<TOptions> extends true ? ChatUINamedInterruptId<TOptions> : never);
+type ToolByName<TOptions, TName> = Extract<ChatUIToolsOf<TOptions> extends ReadonlyArray<infer TTool> ? TTool : never, {
+    name: TName;
+}>;
+export type ChatUIInterrupt = ChatInterrupt | ToolApprovalInterrupt;
+export type ChatUIToolApproval<TOptions, TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>> = Extract<ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>, {
+    kind: 'tool-approval';
+    toolName: TName;
+}>;
+export type ChatUIToolPart<TOptions, TName extends ChatUIToolName<TOptions> = ChatUIToolName<TOptions>> = {
+    key: 'toolCall';
+    part: Extract<ToolCallPart<ChatUIToolsOf<TOptions>>, {
+        name: TName;
+    }>;
+    result?: ToolResultPart;
+    interrupt?: Extract<ChatInterrupt<ChatUIToolsOf<TOptions>, ChatUIInterruptsOf<TOptions>>, {
+        kind: 'tool-approval';
+        toolName: TName;
+    }>;
+    input?: InferToolInput<ToolByName<TOptions, TName>>;
+    output?: InferToolOutput<ToolByName<TOptions, TName>>;
+};
+export type RegisteredUIInterrupt<TOptions, TId extends ChatUIRegisteredInterruptId<TOptions> = ChatUIRegisteredInterruptId<TOptions>> = Extract<RegisteredGenericInterrupt<ChatUIInterruptsOf<TOptions>>, {
+    definitionId: TId;
+}>;
+export type ChatUIInterruptOf<TOptions, TName extends ChatUIInterruptName<TOptions> = never> = [TName] extends [never] ? ChatUIInterrupt : TName extends (ChatUIHasNamedTools<TOptions> extends true ? ChatUIToolName<TOptions> : never) ? ChatUIToolApproval<TOptions, TName> : TName extends ChatUINamedInterruptId<TOptions> ? RegisteredUIInterrupt<TOptions, TName> : ChatUIInterrupt;
+export type ChatUISelectedToolPart = {
+    key: 'toolCall';
+    part: ToolCallPart;
+    result?: ToolResultPart;
+    interrupt?: ChatUIInterrupt;
+    input?: unknown;
+    output?: unknown;
+};
+export type ChatUISelectedResultPart = {
+    key: 'toolResult';
+    part: ToolResultPart;
+    matched: boolean;
+};
+export type ChatUISelectedGenericPart = {
+    key: Exclude<ChatUIPartKey, 'toolCall' | 'toolResult'>;
+    part: MessagePart;
+};
+export type ChatUISelectedPart = ChatUISelectedToolPart | ChatUISelectedResultPart | ChatUISelectedGenericPart;
+export type ChatUISelectedPartOf<TOptions, TKey extends ChatUIPartKey = ChatUIPartKey> = TKey extends 'toolCall' ? ChatUIToolPart<TOptions> : TKey extends 'toolResult' ? ChatUISelectedResultPart : {
+    key: TKey;
+    part: ChatUIPartOf<TOptions, TKey>;
+};
+export type ChatUISelectedMessage = {
+    message: UIMessage;
+    parts: Array<ChatUISelectedPart>;
+};
+export type ChatUISelection = {
+    messages: Array<ChatUISelectedMessage>;
+    interrupts: Array<ChatUIInterrupt>;
+};
+export type ChatUISelectInput = {
+    messages: ReadonlyArray<UIMessage>;
+    interrupts?: ReadonlyArray<ChatUIInterrupt>;
+    inlineToolNames?: ReadonlyArray<string>;
+};
+export type ChatUIMessages<TOptions> = Array<UIMessage<ChatUIToolsOf<TOptions>, ChatUIData<TOptions>>>;
+export type ChatUIStructuredPart<TOptions> = StructuredOutputPart<ChatUIData<TOptions>>;
+export {};

package/dist/esm/ui.d.ts

@@ -0,0 +1,3 @@
+export { partTypeToKey, selectChatUI } from './ui/selectors.js';
+export { automaticPartsForMessage, collectInlineToolNames, resolveInterruptComponent, selectMessageUI, } from './ui/selectors.js';
+export type { ChatUIData, ChatUIHasNamedInterrupts, ChatUIHasNamedTools, ChatUIInterrupt, ChatUIInterruptName, ChatUIInterruptOf, ChatUIInterruptsOf, ChatUINamedInterruptId, ChatUIMessages, ChatUIPartKey, ChatUIPartOf, ChatUIPartTypeByKey, ChatUIRegisteredInterruptId, ChatUISchemaOf, ChatUISelectInput, ChatUISelectedGenericPart, ChatUISelectedMessage, ChatUISelectedPart, ChatUISelectedPartOf, ChatUISelectedResultPart, ChatUISelectedToolPart, ChatUISelection, ChatUIStructuredPart, ChatUIToolApproval, ChatUIToolName, ChatUIToolPart, ChatUIToolsOf, RegisteredUIInterrupt, } from './ui/types.js';

package/dist/esm/ui.js

@@ -0,0 +1,2 @@
+import { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI } from "./ui/selectors.js";
+export { automaticPartsForMessage, collectInlineToolNames, partTypeToKey, resolveInterruptComponent, selectChatUI, selectMessageUI };

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.29.2",
+  "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",
@@ -46,6 +46,10 @@
     "./byok": {
       "types": "./dist/esm/byok.d.ts",
       "import": "./dist/esm/byok.js"
+    },
+    "./ui": {
+      "types": "./dist/esm/ui.d.ts",
+      "import": "./dist/esm/ui.js"
     }
   },
   "files": [
@@ -53,7 +57,7 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "^0.52.0",
+    "@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'