@tanstack/ai 0.16.0 → 0.18.0

package/src/types.ts

@@ -1,4 +1,7 @@
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from '@standard-schema/spec'
 import type { InternalLogger } from './logger/internal-logger'
 import type {
   BaseEvent as AGUIBaseEvent,
@@ -91,25 +94,42 @@ export interface JSONSchema {
 }
 
 /**
- * Union type for schema input - can be any Standard JSON Schema compliant schema or a plain JSONSchema object.
+ * Union type for schema input - can be any Standard Schema compliant validator,
+ * any Standard JSON Schema compliant schema, or a plain JSONSchema object.
  *
- * Standard JSON Schema compliant libraries include:
+ * Standard JSON Schema compliant libraries (carry the JSON-schema converter):
  * - Zod v4.2+ (natively supports StandardJSONSchemaV1)
  * - ArkType v2.1.28+ (natively supports StandardJSONSchemaV1)
  * - Valibot v1.2+ (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
  *
+ * StandardSchemaV1 covers libraries whose published types only expose the
+ * validator surface — Zod's core `$ZodType['~standard']` is currently typed
+ * as `StandardSchemaV1.Props` even though the runtime attaches the
+ * `jsonSchema` converter, so this branch is what makes `InferSchemaType`
+ * recover the inferred type for callers using `z.ZodType<T>`.
+ *
  * @see https://standardschema.dev/json-schema
  */
 
-export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema
+export type SchemaInput =
+  | StandardJSONSchemaV1<any, any>
+  | StandardSchemaV1<any, any>
+  | JSONSchema
 
 /**
  * Infer the TypeScript type from a schema.
  * For Standard JSON Schema compliant schemas, extracts the input type.
- * For plain JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
+ * For Standard Schema validators (e.g. Zod's `~standard` surface), extracts
+ * the input type from the `StandardSchemaV1` shape.
+ * For plain JSONSchema, returns `unknown` since we can't infer types from
+ * JSON Schema at compile time.
  */
 export type InferSchemaType<T> =
-  T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown
+  T extends StandardJSONSchemaV1<infer TInput, unknown>
+    ? TInput
+    : T extends StandardSchemaV1<infer TInput, unknown>
+      ? TInput
+      : unknown
 
 export interface ToolCall<TMetadata = unknown> {
   id: string
@@ -729,8 +749,14 @@ export interface TextOptions<
    */
   outputSchema?: SchemaInput
   /**
-   * Conversation ID for correlating client and server-side devtools events.
-   * When provided, server-side events will be linked to the client conversation in devtools.
+   * @deprecated Use `threadId` instead. `conversationId` is the legacy
+   * pre-AG-UI name for the same concept (a stable per-conversation
+   * identifier used to correlate client/server devtools events). When
+   * `conversationId` is omitted, the runtime falls back to `threadId`
+   * automatically, so most callers can simply pass `threadId` (or rely
+   * on `chatParamsFromRequest`, which surfaces it on `params`).
+   *
+   * Will be removed in a future major release.
    */
   conversationId?: string
   /**
@@ -766,6 +792,11 @@ export interface TextOptions<
    * If not provided, a unique ID will be generated.
    */
   runId?: string
+  /**
+   * Parent run ID for AG-UI protocol nested run correlation.
+   * Surfaced for observability/middleware; not consumed by the LLM call.
+   */
+  parentRunId?: string
 }
 
 // ============================================================================
@@ -1057,6 +1088,106 @@ export interface CustomEvent extends AGUICustomEvent {
   model?: string
 }
 
+/**
+ * Final event of a streaming structured-output run. Carries the validated
+ * `object` (typed as `T` after the orchestrator runs Standard Schema parsing),
+ * the `raw` JSON text that produced it, and — for thinking/reasoning models —
+ * the accumulated reasoning text. Adapters emit this with `T = unknown`; the
+ * chat orchestrator narrows to the schema's inferred type after validation.
+ *
+ * `reasoning` is `undefined` when the model produced none (most non-thinking
+ * models) and when the underlying adapter doesn't expose reasoning streams.
+ *
+ * `name` is a string literal so consumers can narrow directly:
+ *
+ * ```ts
+ * if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
+ *   chunk.value.object // typed as T
+ * }
+ * ```
+ */
+export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'structured-output.complete'
+  value: { object: T; raw: string; reasoning?: string }
+}
+
+/**
+ * Emitted when a server tool requires approval before execution. The agent
+ * loop yields this and pauses — `structured-output.complete` will not fire
+ * for that run. The shape is fixed by the orchestrator's tool-approval flow
+ * (see `buildApprovalChunks` in `activities/chat/index.ts`).
+ */
+export interface ApprovalRequestedEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'approval-requested'
+  value: {
+    toolCallId: string
+    toolName: string
+    input: unknown
+    approval: { id: string; needsApproval: true }
+  }
+}
+
+/**
+ * Emitted when a client tool is invoked. The agent loop yields this and
+ * pauses to let the caller run the tool client-side — `structured-output.complete`
+ * will not fire for that run. Shape fixed by `buildClientToolChunks` in
+ * `activities/chat/index.ts`.
+ */
+export interface ToolInputAvailableEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'tool-input-available'
+  value: {
+    toolCallId: string
+    toolName: string
+    input: unknown
+  }
+}
+
+/**
+ * Public type for streams returned by `chat({ outputSchema, stream: true })`.
+ *
+ * Yields all standard `StreamChunk` lifecycle events plus the three tagged
+ * `CUSTOM` events the orchestrator can emit through this path:
+ * - `structured-output.complete` — terminal event with typed `value.object: T`
+ * - `approval-requested` — server tool needs approval (pauses the run)
+ * - `tool-input-available` — client tool invocation (pauses the run)
+ *
+ * Each variant has a literal `name`, so a single discriminated narrow gives
+ * you a typed `value` with no helper or cast:
+ *
+ * ```ts
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
+ *     chunk.value.object // typed as T
+ *   } else if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') {
+ *     chunk.value.toolCallId // typed as string
+ *   }
+ * }
+ * ```
+ *
+ * Caveat: tools can emit arbitrary user-defined custom events via the
+ * `emitCustomEvent(name, value)` context API. Those flow through this stream
+ * at runtime but are intentionally absent from this type — including a bare
+ * `CustomEvent` (whose `value: any` would poison the union) would collapse
+ * `chunk.value` back to `any` after the narrow. If you rely on
+ * `emitCustomEvent` plus `outputSchema + stream: true`, branch on `CUSTOM`
+ * outside the literal-`name` narrows or cast explicitly.
+ */
+export type StructuredOutputStream<T = unknown> = AsyncIterable<
+  | Exclude<StreamChunk, CustomEvent>
+  | StructuredOutputCompleteEvent<T>
+  | ApprovalRequestedEvent
+  | ToolInputAvailableEvent
+>
+
 // ============================================================================
 // AG-UI Reasoning Event Interfaces
 // ============================================================================
@@ -1179,12 +1310,16 @@ export interface TextCompletionChunk {
   }
 }
 
-export interface SummarizationOptions {
+export interface SummarizationOptions<
+  TProviderOptions extends object = Record<string, unknown>,
+> {
   model: string
   text: string
   maxLength?: number
   style?: 'bullet-points' | 'paragraph' | 'concise'
   focus?: Array<string>
+  /** Provider-specific options forwarded by the summarize() activity. */
+  modelOptions?: TProviderOptions
   /**
    * Internal logger threaded from the summarize() entry point. Adapters must
    * call logger.request() before the SDK call and logger.errors() in catch blocks.
@@ -1213,7 +1348,7 @@ export interface SummarizationResult {
  */
 export interface ImageGenerationOptions<
   TProviderOptions extends object = object,
-  TSize extends string = string,
+  TSize extends string | undefined = string,
 > {
   /** The model to use for image generation */
   model: string
@@ -1343,7 +1478,7 @@ export interface AudioGenerationResult {
  */
 export interface VideoGenerationOptions<
   TProviderOptions extends object = object,
-  TSize extends string = string,
+  TSize extends string | undefined = string,
 > {
   /** The model to use for video generation */
   model: string

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