@tanstack/ai 0.17.0 → 0.18.0

package/src/utilities/ag-ui-wire.ts

@@ -0,0 +1,182 @@
+import type { ContentPart, MessagePart, TextPart, UIMessage } from '../types'
+
+type AGUITextInputContent = { type: 'text'; text: string }
+type AGUIInputContent =
+  | AGUITextInputContent
+  | (ContentPart & { type: 'image' | 'audio' | 'video' | 'document' })
+
+type AGUIToolCallMirror = {
+  id: string
+  type: 'function'
+  function: { name: string; arguments: string }
+}
+
+type AGUIToolMessage = {
+  role: 'tool'
+  id: string
+  toolCallId: string
+  content: string
+  error?: string
+}
+
+type AGUIReasoningMessage = {
+  role: 'reasoning'
+  id: string
+  content: string
+}
+
+type WireAnchorMessage = UIMessage & {
+  content?: string | Array<AGUIInputContent>
+  toolCalls?: Array<AGUIToolCallMirror>
+}
+
+export type WireMessage =
+  | WireAnchorMessage
+  | AGUIToolMessage
+  | AGUIReasoningMessage
+
+/**
+ * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`
+ * wire shape. Each anchor (system/user/assistant) carries the canonical
+ * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)
+ * so AG-UI Zod parsing succeeds. Tool results and thinking parts on
+ * assistant messages are additionally emitted as fan-out
+ * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict
+ * AG-UI server consumers.
+ */
+export function uiMessagesToWire(
+  messages: Array<UIMessage>,
+): Array<WireMessage> {
+  const wire: Array<WireMessage> = []
+
+  for (const msg of messages) {
+    // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.
+    // UIMessage always has parts; ModelMessage uses content directly.
+    const parts: ReadonlyArray<MessagePart> =
+      (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []
+
+    if (msg.role === 'system') {
+      wire.push({
+        ...msg,
+        content:
+          parts.length > 0
+            ? collectText(parts)
+            : ((msg as unknown as { content?: string }).content ?? ''),
+      })
+      continue
+    }
+
+    if (msg.role === 'user') {
+      wire.push({
+        ...msg,
+        content:
+          parts.length > 0
+            ? collectUserContent(parts)
+            : ((msg as unknown as { content?: string }).content ?? ''),
+      })
+      continue
+    }
+
+    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs
+    for (const part of parts) {
+      if (part.type === 'thinking') {
+        wire.push({
+          role: 'reasoning',
+          id: deriveReasoningId(msg.id, part),
+          content: part.content,
+        })
+      }
+    }
+
+    const text = collectText(parts)
+    const toolCalls = collectToolCalls(parts)
+    wire.push({
+      ...msg,
+      ...(text !== '' && { content: text }),
+      ...(toolCalls && { toolCalls }),
+    })
+
+    for (const part of parts) {
+      if (part.type === 'tool-result') {
+        wire.push({
+          role: 'tool',
+          id: deriveToolMessageId(part.toolCallId),
+          toolCallId: part.toolCallId,
+          content: part.content,
+          ...(part.error !== undefined && { error: part.error }),
+        })
+      }
+    }
+  }
+
+  return wire
+}
+
+function collectText(parts: ReadonlyArray<MessagePart>): string {
+  return parts
+    .filter((p): p is TextPart => p.type === 'text')
+    .map((p) => p.content)
+    .join('')
+}
+
+function collectUserContent(
+  parts: ReadonlyArray<MessagePart>,
+): string | Array<AGUIInputContent> {
+  const hasMultimodal = parts.some(
+    (p) =>
+      p.type === 'image' ||
+      p.type === 'audio' ||
+      p.type === 'video' ||
+      p.type === 'document',
+  )
+  if (!hasMultimodal) {
+    return collectText(parts)
+  }
+  const out: Array<AGUIInputContent> = []
+  for (const p of parts) {
+    if (p.type === 'text') {
+      out.push({ type: 'text', text: p.content })
+    } else if (
+      p.type === 'image' ||
+      p.type === 'audio' ||
+      p.type === 'video' ||
+      p.type === 'document'
+    ) {
+      out.push(p as AGUIInputContent)
+    }
+  }
+  return out
+}
+
+function collectToolCalls(
+  parts: ReadonlyArray<MessagePart>,
+): Array<AGUIToolCallMirror> | undefined {
+  const calls: Array<AGUIToolCallMirror> = []
+  for (const p of parts) {
+    if (p.type === 'tool-call') {
+      calls.push({
+        id: p.id,
+        type: 'function',
+        function: { name: p.name, arguments: p.arguments },
+      })
+    }
+  }
+  return calls.length > 0 ? calls : undefined
+}
+
+function deriveReasoningId(messageId: string, part: MessagePart): string {
+  return `${messageId}-reasoning-${(part as { id?: string }).id ?? hashContent((part as { content: string }).content)}`
+}
+
+function deriveToolMessageId(toolCallId: string): string {
+  return `tool-${toolCallId}`
+}
+
+function hashContent(s: string): string {
+  // Cheap deterministic id suffix; collisions are tolerable since
+  // reasoning ids only matter for AG-UI server consumers, not for our
+  // own server's dedup logic (which keys on toolCallId, not reasoning id).
+  let h = 0
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0
+  return Math.abs(h).toString(36)
+}

package/src/utilities/chat-params.ts

@@ -0,0 +1,199 @@
+import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'
+import type { Context as AGUIContext } from '@ag-ui/core'
+import type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'
+
+const KNOWN_PART_TYPES = new Set([
+  'text',
+  'image',
+  'audio',
+  'video',
+  'document',
+  'tool-call',
+  'tool-result',
+  'thinking',
+])
+
+function isValidParts(value: unknown): value is Array<{ type: string }> {
+  if (!Array.isArray(value)) return false
+  for (const p of value) {
+    if (!p || typeof p !== 'object') return false
+    const type = (p as { type?: unknown }).type
+    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false
+  }
+  return true
+}
+
+/**
+ * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.
+ *
+ * Returns a spread-friendly object whose `messages` field is suitable for
+ * passing directly to `chat({ messages })`. The existing
+ * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and
+ * reasoning/activity/developer-role normalization internally.
+ *
+ * @throws An error with a migration-pointing message when the body does
+ *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a
+ *   400 Bad Request to the client.
+ */
+export function chatParamsFromRequestBody(body: unknown): Promise<{
+  messages: Array<UIMessage | ModelMessage>
+  threadId: string
+  runId: string
+  parentRunId?: string
+  tools: Array<{ name: string; description: string; parameters: JSONSchema }>
+  forwardedProps: Record<string, unknown>
+  state: unknown
+  context: Array<AGUIContext>
+}> {
+  const parseResult = RunAgentInputSchema.safeParse(body)
+  if (!parseResult.success) {
+    return Promise.reject(
+      new AGUIError(
+        `Request body is not a valid AG-UI RunAgentInput. ` +
+          `If you're upgrading from a previous @tanstack/ai-client release, ` +
+          `see docs/migration/ag-ui-compliance.md. ` +
+          `Validation errors: ${parseResult.error.message}`,
+      ),
+    )
+  }
+
+  const parsed = parseResult.data
+
+  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are
+  // dropped during parse. We re-attach them from the original body so the
+  // existing UIMessage path inside `chat()` can use them directly.
+  const rawMessages =
+    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []
+  const messages = parsed.messages.map((m, i) => {
+    const raw = rawMessages[i]
+    if (
+      raw &&
+      typeof raw === 'object' &&
+      'parts' in raw &&
+      isValidParts(raw.parts)
+    ) {
+      return { ...m, parts: raw.parts } as UIMessage | ModelMessage
+    }
+    return m as ModelMessage
+  })
+
+  return Promise.resolve({
+    messages,
+    threadId: parsed.threadId,
+    runId: parsed.runId,
+    parentRunId: parsed.parentRunId,
+    tools: parsed.tools as Array<{
+      name: string
+      description: string
+      parameters: JSONSchema
+    }>,
+    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,
+    state: parsed.state,
+    context: parsed.context,
+  })
+}
+
+/**
+ * Read an HTTP `Request`, parse its JSON body, and validate it as an
+ * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +
+ * `chatParamsFromRequestBody(...)` pair into a single call.
+ *
+ * On a malformed body or invalid AG-UI shape, this **throws a
+ * `Response`** with status 400 and a migration-pointing message in the
+ * body. Frameworks that natively handle thrown `Response` objects
+ * (TanStack Start, SolidStart, Remix, React Router 7) will return the
+ * 400 to the client automatically, so the handler reduces to:
+ *
+ * ```ts
+ * export async function POST(req: Request) {
+ *   const params = await chatParamsFromRequest(req)
+ *   // ...use params
+ * }
+ * ```
+ *
+ * In frameworks that do not auto-handle thrown `Response` objects
+ * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call
+ * with try/catch and return the caught Response yourself, or use
+ * `chatParamsFromRequestBody` directly with your own JSON-parsing.
+ *
+ * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.
+ */
+export async function chatParamsFromRequest(
+  req: Request,
+): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {
+  let body: unknown
+  try {
+    body = await req.json()
+  } catch (cause) {
+    // Preserve the underlying error on the thrown Response for
+    // server-side observability without leaking it to the client.
+    const res = new Response(
+      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
+      { status: 400 },
+    )
+    ;(res as unknown as { cause?: unknown }).cause = cause
+    throw res
+  }
+  try {
+    return await chatParamsFromRequestBody(body)
+  } catch (cause) {
+    // Generic public message — avoid echoing Zod paths (which can contain
+    // user payload fragments) or internal validator strings to the client.
+    // The original AGUIError is attached as `cause` so server logs can
+    // surface it without exposing it to remote callers.
+    const res = new Response(
+      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',
+      { status: 400 },
+    )
+    ;(res as unknown as { cause?: unknown }).cause = cause
+    throw res
+  }
+}
+
+/**
+ * Merge a server-side tool array with the AG-UI client-declared tools
+ * received in the request body.
+ *
+ * Rules:
+ * - Server tools win on name collision. The client's declaration is
+ *   ignored if the server already has a tool with that name. The client's
+ *   UI-side handler still fires when the streamed tool-result event comes
+ *   through (see `chat-client.ts` `onToolCall`), giving the
+ *   "after server execution the client also handles" semantic for free.
+ * - Client-only tools (name not in `serverTools`) become no-execute
+ *   entries: the runtime's existing `ClientToolRequest` path handles
+ *   them — server emits a tool-call request, client executes via its
+ *   registered handler, client posts back the result.
+ *
+ * @param serverTools - The server's tool array (e.g. from
+ *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.
+ * @param clientTools - The `tools` array received from
+ *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
+ * @returns A merged array suitable for `chat({ tools })`.
+ */
+export function mergeAgentTools(
+  serverTools: ReadonlyArray<Tool>,
+  clientTools: ReadonlyArray<{
+    name: string
+    description: string
+    parameters: JSONSchema
+  }>,
+): Array<Tool> {
+  const seen = new Set(serverTools.map((t) => t.name))
+  const merged: Array<Tool> = [...serverTools]
+  for (const ct of clientTools) {
+    if (seen.has(ct.name)) {
+      // Server wins on name collision.
+      continue
+    }
+    seen.add(ct.name)
+    merged.push({
+      name: ct.name,
+      description: ct.description,
+      inputSchema: ct.parameters,
+      // No `execute` — runtime treats this as a client-side tool and
+      // emits ClientToolRequest events.
+    } as Tool)
+  }
+  return merged
+}