@tanstack/ai-client 0.29.2 → 0.31.0

package/src/ui/selectors.ts

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

package/src/ui/types.ts

@@ -0,0 +1,243 @@
+import type {
+  AnyClientTool,
+  InferSchemaType,
+  InferToolInput,
+  InferToolOutput,
+  InterruptDefinition,
+  SchemaInput,
+} from '@tanstack/ai/client'
+import type {
+  ChatInterrupt,
+  MessagePart,
+  RegisteredGenericInterrupt,
+  StructuredOutputPart,
+  ToolApprovalInterrupt,
+  ToolCallPart,
+  ToolResultPart,
+  UIMessage,
+} from '../types'
+
+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>
+>

package/src/ui.ts

@@ -0,0 +1,37 @@
+export { partTypeToKey, selectChatUI } from './ui/selectors'
+export {
+  automaticPartsForMessage,
+  collectInlineToolNames,
+  resolveInterruptComponent,
+  selectMessageUI,
+} from './ui/selectors'
+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'

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
+  }
+}