@tanstack/ai 0.16.0 → 0.18.0

package/src/activities/chat/index.ts

@@ -9,6 +9,7 @@ import { devtoolsMiddleware } from '@tanstack/ai-event-client'
 import { stripToSpecMiddleware } from '../../strip-to-spec-middleware'
 import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import { EventType } from '../../types'
 import { LazyToolManager } from './tools/lazy-tool-manager'
 import {
   MiddlewareAbortError,
@@ -28,7 +29,7 @@ import type {
   ClientToolRequest,
   ToolResult,
 } from './tools/tool-calls'
-import type { AnyTextAdapter } from './adapter'
+import type { AnyTextAdapter, StructuredOutputOptions } from './adapter'
 import type {
   AgentLoopStrategy,
   ConstrainedModelMessage,
@@ -38,6 +39,8 @@ import type {
   RunFinishedEvent,
   SchemaInput,
   StreamChunk,
+  StructuredOutputCompleteEvent,
+  StructuredOutputStream,
   TextMessageContentEvent,
   TextOptions,
   Tool,
@@ -45,6 +48,7 @@ import type {
   ToolCallArgsEvent,
   ToolCallEndEvent,
   ToolCallStartEvent,
+  UIMessage,
 } from '../../types'
 import type {
   ChatMiddleware,
@@ -82,12 +86,21 @@ export interface TextActivityOptions<
 > {
   /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
   adapter: TAdapter
-  /** Conversation messages - content types are constrained by the adapter's input modalities and metadata */
+  /**
+   * Conversation messages. Accepts:
+   * - `ConstrainedModelMessage` — content types constrained by the adapter's input modalities.
+   * - `ModelMessage` — unconstrained model message (e.g., forwarded from an AG-UI wire payload).
+   * - `UIMessage` — parts-based UI representation; converted internally via `convertMessagesToModelMessages`.
+   *
+   * The three shapes can be mixed in a single array (e.g., when forwarding a wire payload that includes both anchor UIMessages and AG-UI fan-out ModelMessages).
+   */
   messages?: Array<
-    ConstrainedModelMessage<{
-      inputModalities: TAdapter['~types']['inputModalities']
-      messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
-    }>
+    | UIMessage
+    | ModelMessage
+    | ConstrainedModelMessage<{
+        inputModalities: TAdapter['~types']['inputModalities']
+        messageMetadataByModality: TAdapter['~types']['messageMetadataByModality']
+      }>
   >
   /** System prompts to prepend to the conversation */
   systemPrompts?: TextOptions['systemPrompts']
@@ -125,6 +138,8 @@ export interface TextActivityOptions<
   threadId?: TextOptions['threadId']
   /** Run ID override for AG-UI protocol. Auto-generated by adapter if not provided. */
   runId?: TextOptions['runId']
+  /** Parent run ID for AG-UI protocol nested run correlation. */
+  parentRunId?: TextOptions['parentRunId']
   /**
    * Optional Standard Schema for structured output.
    * When provided, the activity will:
@@ -226,16 +241,28 @@ export function createChatOptions<
 
 /**
  * Result type for the text activity.
- * - If outputSchema is provided: Promise<InferSchemaType<TSchema>>
- * - If stream is false: Promise<string>
- * - Otherwise (stream is true, default): AsyncIterable<StreamChunk>
+ * - If outputSchema is provided AND stream is explicitly true:
+ *   StructuredOutputStream<InferSchemaType<TSchema>> — yields raw JSON deltas
+ *   via TEXT_MESSAGE_CONTENT plus a terminal StructuredOutputCompleteEvent
+ *   carrying the validated object.
+ * - If outputSchema is provided without explicit stream:true:
+ *   Promise<InferSchemaType<TSchema>>.
+ * - If stream is explicitly false (no schema): Promise<string>.
+ * - Otherwise (default): AsyncIterable<StreamChunk>.
+ *
+ * `[TStream] extends [true]` is used (not `TStream extends true`) so that the
+ * default `boolean` value of `TStream` does *not* match the streaming branch.
+ * Without this, plain `chat({ outputSchema })` would type as a stream while
+ * the runtime returns a Promise — see issue #526.
  */
 export type TextActivityResult<
   TSchema extends SchemaInput | undefined,
-  TStream extends boolean = true,
+  TStream extends boolean = boolean,
 > = TSchema extends SchemaInput
-  ? Promise<InferSchemaType<TSchema>>
-  : TStream extends false
+  ? [TStream] extends [true]
+    ? StructuredOutputStream<InferSchemaType<TSchema>>
+    : Promise<InferSchemaType<TSchema>>
+  : [TStream] extends [false]
     ? Promise<string>
     : AsyncIterable<StreamChunk>
 
@@ -298,6 +325,7 @@ class TextEngine<
   // AG-UI protocol IDs
   private threadId: string
   private runIdOverride?: string
+  private parentRunIdOverride?: string
 
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner
@@ -349,8 +377,15 @@ class TextEngine<
       ? { signal: config.params.abortController.signal }
       : undefined
     this.effectiveSignal = config.params.abortController?.signal
-    this.threadId = config.params.threadId || this.createId('thread')
+    // `conversationId` is the legacy alias of `threadId` — accept it
+    // as a fallback so `chat({ conversationId })` keeps working, with
+    // explicit `threadId` winning when both are set.
+    this.threadId =
+      config.params.threadId ||
+      config.params.conversationId ||
+      this.createId('thread')
     this.runIdOverride = config.params.runId
+    this.parentRunIdOverride = config.params.parentRunId
 
     // Initialize middleware — devtools first, strip-to-spec always last.
     // handleStreamChunk processes raw chunks BEFORE middleware, so internal
@@ -366,7 +401,10 @@ class TextEngine<
     this.middlewareCtx = {
       requestId: this.requestId,
       streamId: this.streamId,
-      conversationId: config.params.conversationId,
+      threadId: this.threadId,
+      // Legacy alias kept on the ctx so middleware that reads
+      // `ctx.conversationId` keeps working. Always equals `threadId`.
+      conversationId: this.threadId,
       phase: 'init' as ChatMiddlewarePhase,
       iteration: 0,
       chunkIndex: 0,
@@ -414,7 +452,7 @@ class TextEngine<
   async *run(): AsyncGenerator<StreamChunk> {
     this.beforeRun()
     this.logger.agentLoop('run started', {
-      conversationId: this.middlewareCtx.conversationId,
+      threadId: this.middlewareCtx.threadId,
     })
 
     try {
@@ -493,7 +531,7 @@ class TextEngine<
           // Genuine error — call onError
           this.logger.errors('chat run failed', {
             error,
-            conversationId: this.middlewareCtx.conversationId,
+            threadId: this.middlewareCtx.threadId,
           })
           await this.middlewareRunner.runOnError(this.middlewareCtx, {
             error,
@@ -619,6 +657,7 @@ class TextEngine<
       logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
+      parentRunId: this.parentRunIdOverride,
     })) {
       if (this.isCancelled()) {
         break
@@ -1575,38 +1614,46 @@ class TextEngine<
 export function chat<
   TAdapter extends AnyTextAdapter,
   TSchema extends SchemaInput | undefined = undefined,
-  TStream extends boolean = true,
+  TStream extends boolean = boolean,
 >(
   options: TextActivityOptions<TAdapter, TSchema, TStream>,
 ): TextActivityResult<TSchema, TStream> {
   const { outputSchema, stream } = options
 
-  // If outputSchema is provided, run agentic structured output
+  // outputSchema + stream:true is the only branch that streams structured
+  // output. Without an explicit `stream: true`, schema-bearing calls run the
+  // agent loop and resolve to a typed Promise<InferSchemaType<TSchema>>.
+  if (outputSchema && stream === true) {
+    return runStreamingStructuredOutput({
+      ...options,
+      outputSchema,
+      stream,
+    }) as TextActivityResult<TSchema, TStream>
+  }
+
+  // If outputSchema is provided, run agentic structured output (Promise<T>)
   if (outputSchema) {
-    return runAgenticStructuredOutput(
-      options as unknown as TextActivityOptions<
-        AnyTextAdapter,
-        SchemaInput,
-        boolean
-      >,
-    ) as TextActivityResult<TSchema, TStream>
+    return runAgenticStructuredOutput({
+      ...options,
+      outputSchema,
+    }) as TextActivityResult<TSchema, TStream>
   }
 
   // If stream is explicitly false, run non-streaming text
   if (stream === false) {
-    return runNonStreamingText(
-      options as unknown as TextActivityOptions<
-        AnyTextAdapter,
-        undefined,
-        false
-      >,
-    ) as TextActivityResult<TSchema, TStream>
+    return runNonStreamingText({
+      ...options,
+      outputSchema: undefined,
+      stream,
+    }) as TextActivityResult<TSchema, TStream>
   }
 
   // Otherwise, run streaming text (default)
-  return runStreamingText(
-    options as unknown as TextActivityOptions<AnyTextAdapter, undefined, true>,
-  ) as TextActivityResult<TSchema, TStream>
+  return runStreamingText({
+    ...options,
+    outputSchema: undefined,
+    stream,
+  }) as TextActivityResult<TSchema, TStream>
 }
 
 /**
@@ -1741,6 +1788,325 @@ async function runAgenticStructuredOutput<TSchema extends SchemaInput>(
   return result.data as InferSchemaType<TSchema>
 }
 
+/**
+ * Synthesize a streaming structured-output stream by wrapping a non-streaming
+ * `structuredOutput` call. Used when an adapter doesn't implement
+ * `structuredOutputStream` natively.
+ */
+async function* fallbackStructuredOutputStream(
+  adapter: AnyTextAdapter,
+  options: StructuredOutputOptions<Record<string, unknown>>,
+): AsyncIterable<StreamChunk> {
+  const { chatOptions } = options
+  const runId = chatOptions.runId ?? `mock-${Date.now()}`
+  const threadId = chatOptions.threadId ?? `mock-${Date.now()}`
+  const messageId = `mock-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  const model = chatOptions.model
+  const timestamp = Date.now()
+
+  yield {
+    type: EventType.RUN_STARTED,
+    runId,
+    threadId,
+    model,
+    timestamp,
+  }
+
+  let result: { data: unknown; rawText: string }
+  try {
+    result = await adapter.structuredOutput(options)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error'
+    yield {
+      type: EventType.RUN_ERROR,
+      runId,
+      model,
+      timestamp,
+      message,
+      error: { message },
+    }
+    return
+  }
+
+  yield {
+    type: EventType.TEXT_MESSAGE_START,
+    messageId,
+    role: 'assistant',
+    model,
+    timestamp,
+  }
+
+  yield {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId,
+    delta: result.rawText,
+    model,
+    timestamp,
+  }
+
+  yield {
+    type: EventType.TEXT_MESSAGE_END,
+    messageId,
+    model,
+    timestamp,
+  }
+
+  yield {
+    type: EventType.CUSTOM,
+    name: 'structured-output.complete',
+    value: { object: result.data, raw: result.rawText },
+    model,
+    timestamp,
+  }
+
+  yield {
+    type: EventType.RUN_FINISHED,
+    runId,
+    threadId,
+    model,
+    timestamp,
+    finishReason: 'stop',
+  }
+}
+
+/**
+ * Run streaming structured output:
+ * - Without tools: call adapter.structuredOutputStream directly (single
+ *   provider request emitting JSON deltas + a final CUSTOM event).
+ * - With tools: run the agent loop, yield its non-terminal chunks, then call
+ *   structuredOutputStream on the final messages so the structured stream's
+ *   own RUN_STARTED/RUN_FINISHED bracket the run.
+ *
+ * Validates the parsed object against the original Standard Schema (if
+ * applicable) when forwarding the final `structured-output.complete` event.
+ *
+ * Pre-flight validation (missing schema, unconvertible schema) throws
+ * synchronously at call time rather than as a yielded RUN_ERROR mid-stream —
+ * those are programmer errors, not runtime conditions.
+ */
+function runStreamingStructuredOutput<TSchema extends SchemaInput>(
+  options: TextActivityOptions<AnyTextAdapter, TSchema, true>,
+): StructuredOutputStream<InferSchemaType<TSchema>> {
+  const { outputSchema } = options
+
+  if (!outputSchema) {
+    throw new Error('outputSchema is required for streaming structured output')
+  }
+
+  // forStructuredOutput strict-converts the schema once at the activity
+  // boundary. Adapters can re-convert if their wire format diverges, but the
+  // default flow hands them a strict-ready schema.
+  const jsonSchema = convertSchemaToJsonSchema(outputSchema, {
+    forStructuredOutput: true,
+  })
+  if (!jsonSchema) {
+    throw new Error('Failed to convert output schema to JSON Schema')
+  }
+
+  // The implementation generator yields the broader internal type
+  // (`StreamChunk | StructuredOutputCompleteEvent<T>`) so agent-loop
+  // CustomEvents can flow through; the public-facing type narrows to
+  // `Exclude<StreamChunk, CustomEvent> | StructuredOutputCompleteEvent<T>`
+  // which lets consumers narrow `chunk.value` cleanly. The widen→narrow
+  // is contained here so consumers see only the strict type.
+  return runStreamingStructuredOutputImpl(
+    options,
+    jsonSchema,
+  ) as StructuredOutputStream<InferSchemaType<TSchema>>
+}
+
+/**
+ * Internal generator return type — broader than the public
+ * `StructuredOutputStream<T>`. The public type pins three tagged `CUSTOM`
+ * events (`structured-output.complete`, `approval-requested`,
+ * `tool-input-available`) so consumers can narrow `chunk.value` cleanly by
+ * literal `name`. At runtime, tools can also emit arbitrary user-defined
+ * `CustomEvent`s through the `emitCustomEvent` context API; those flow
+ * through this generator with `name: string` and are widened out at the
+ * public boundary because keeping them would collapse the typed narrow back
+ * to `any`. The cast inside `runStreamingStructuredOutput` is where that
+ * widening happens.
+ */
+type StructuredOutputStreamInternal<T> = AsyncIterable<
+  StreamChunk | StructuredOutputCompleteEvent<T>
+>
+
+async function* runStreamingStructuredOutputImpl<TSchema extends SchemaInput>(
+  options: TextActivityOptions<AnyTextAdapter, TSchema, true>,
+  jsonSchema: NonNullable<ReturnType<typeof convertSchemaToJsonSchema>>,
+): StructuredOutputStreamInternal<InferSchemaType<TSchema>> {
+  const { adapter, outputSchema, middleware, context, debug, ...textOptions } =
+    options
+  const model = adapter.model
+  const logger = resolveDebugOption(debug)
+  const runId = textOptions.runId
+
+  // Inputs may be UIMessages (from useChat) or ModelMessages (from server-side
+  // callers). The agent-loop branch converts via TextEngine; the no-tools
+  // branch must convert here so the adapter sees a uniform ModelMessage shape.
+  let finalMessages = convertMessagesToModelMessages(textOptions.messages ?? [])
+
+  if (textOptions.tools?.length) {
+    const engine = new TextEngine(
+      {
+        adapter,
+        params: { ...textOptions, model, logger, messages: finalMessages },
+        middleware,
+        context,
+      },
+      logger,
+    )
+
+    // The structured-output stream emits its own RUN_STARTED + RUN_FINISHED
+    // pair to bracket the run — drop both from the engine's output so
+    // consumers see exactly one terminal lifecycle pair.
+    let agentLoopErrored = false
+    try {
+      for await (const chunk of engine.run()) {
+        if (chunk.type === 'RUN_STARTED' || chunk.type === 'RUN_FINISHED') {
+          continue
+        }
+        if (chunk.type === 'RUN_ERROR') {
+          // The engine yielded RUN_ERROR without throwing (provider error mid
+          // agent loop). Forward it once and short-circuit before invoking
+          // structuredOutputStream — otherwise consumers would see a confusing
+          // RUN_ERROR → RUN_STARTED → structured-output.complete sequence and
+          // we would bill another provider call after a failed run.
+          agentLoopErrored = true
+          yield chunk
+          continue
+        }
+        yield chunk
+      }
+    } catch (engineError) {
+      const message = (engineError as Error).message || 'Agent loop failed'
+      logger.errors('runStreamingStructuredOutput agent loop failed', {
+        error: engineError,
+        source: 'runStreamingStructuredOutput',
+      })
+      yield {
+        type: EventType.RUN_ERROR,
+        runId,
+        model,
+        timestamp: Date.now(),
+        message,
+        code: 'agent-loop-failed',
+        error: { message, code: 'agent-loop-failed' },
+      }
+      return
+    }
+
+    if (agentLoopErrored) {
+      return
+    }
+
+    finalMessages = engine.getMessages()
+  }
+
+  const {
+    tools: _tools,
+    agentLoopStrategy: _als,
+    ...structuredTextOptions
+  } = textOptions
+
+  logger.request(
+    `activity=chat-structured-stream provider=${adapter.name} model=${model} messages=${finalMessages.length}`,
+    {
+      provider: adapter.name,
+      model,
+      messageCount: finalMessages.length,
+    },
+  )
+
+  // Adapters consume the abort signal via `chatOptions.request?.signal` and
+  // pass it to the underlying network call. Without this, aborting the SSE
+  // response never cancels the upstream provider request and a terminal
+  // structured-output.complete event still gets yielded after stop.
+  const structuredChatOptions = {
+    ...structuredTextOptions,
+    model,
+    messages: finalMessages,
+    logger,
+    request: textOptions.abortController
+      ? { signal: textOptions.abortController.signal }
+      : undefined,
+  }
+
+  // Adapters that don't implement structuredOutputStream natively fall back
+  // to wrapping the non-streaming `structuredOutput` — `fallbackStructuredOutputStream`
+  // synthesizes the AG-UI lifecycle events around it.
+  const stream = adapter.structuredOutputStream
+    ? adapter.structuredOutputStream({
+        chatOptions: structuredChatOptions,
+        outputSchema: jsonSchema,
+      })
+    : fallbackStructuredOutputStream(adapter, {
+        chatOptions: structuredChatOptions,
+        outputSchema: jsonSchema,
+      })
+
+  for await (const chunk of stream) {
+    if (
+      chunk.type === EventType.CUSTOM &&
+      chunk.name === 'structured-output.complete'
+    ) {
+      const value = chunk.value as {
+        object: unknown
+        raw: string
+        reasoning?: string
+      }
+      if (isStandardSchema(outputSchema)) {
+        try {
+          const validated = parseWithStandardSchema<InferSchemaType<TSchema>>(
+            outputSchema,
+            value.object,
+          )
+          yield {
+            ...chunk,
+            // Forward `reasoning` through schema validation so consumers that
+            // only listen for the terminal event don't lose chain-of-thought.
+            value: {
+              object: validated,
+              raw: value.raw,
+              ...(value.reasoning ? { reasoning: value.reasoning } : {}),
+            },
+          }
+          continue
+        } catch (err) {
+          const message = (err as Error).message || 'Schema validation failed'
+          logger.errors(
+            'runStreamingStructuredOutput schema validation failed',
+            {
+              error: err,
+              source: 'runStreamingStructuredOutput',
+              // Include reasoning in error meta so post-mortems can recover
+              // what the model thought through before producing invalid JSON.
+              ...(value.reasoning ? { reasoning: value.reasoning } : {}),
+            },
+          )
+          yield {
+            type: EventType.RUN_ERROR,
+            runId,
+            model: chunk.model ?? model,
+            timestamp: chunk.timestamp ?? Date.now(),
+            message,
+            code: 'schema-validation',
+            error: {
+              message,
+              code: 'schema-validation',
+              ...(value.reasoning ? { reasoning: value.reasoning } : {}),
+            },
+          }
+          return
+        }
+      }
+      yield chunk
+      continue
+    }
+    yield chunk
+  }
+}
+
 // Re-export adapter types
 export type {
   TextAdapter,

package/src/activities/chat/messages.ts

@@ -63,15 +63,55 @@ function getTextContent(content: string | null | Array<ContentPart>): string {
 export function convertMessagesToModelMessages(
   messages: Array<UIMessage | ModelMessage>,
 ): Array<ModelMessage> {
+  // Pre-pass: collect toolCallIds already represented in anchor UIMessage parts.
+  // Fan-out tool messages whose toolCallId matches an anchored ToolResultPart
+  // are AG-UI duplicates and must be dropped to avoid double-feeding the LLM.
+  const anchoredToolCallIds = new Set<string>()
+  for (const msg of messages) {
+    if ('parts' in msg) {
+      for (const part of msg.parts) {
+        if (part.type === 'tool-result') {
+          anchoredToolCallIds.add(part.toolCallId)
+        }
+      }
+    }
+  }
+
   const modelMessages: Array<ModelMessage> = []
   for (const msg of messages) {
     if ('parts' in msg) {
-      // UIMessage - convert to ModelMessages
+      // UIMessage anchor — existing fan-out path
       modelMessages.push(...uiMessageToModelMessages(msg))
-    } else {
-      // Already ModelMessage
-      modelMessages.push(msg)
+      continue
+    }
+
+    const role = (msg as { role: string }).role
+
+    // AG-UI tool fan-out duplicate — drop if anchor already covers it
+    if (
+      role === 'tool' &&
+      msg.toolCallId &&
+      anchoredToolCallIds.has(msg.toolCallId)
+    ) {
+      continue
     }
+
+    // AG-UI reasoning and activity — no ModelMessage equivalent today
+    if (role === 'reasoning' || role === 'activity') {
+      continue
+    }
+
+    // AG-UI developer — collapse to system
+    if (role === 'developer') {
+      modelMessages.push({
+        role: 'system' as ModelMessage['role'],
+        content: (msg as { content: string }).content,
+      } as ModelMessage)
+      continue
+    }
+
+    // Already a ModelMessage (user, assistant, system, tool with no anchor) — pass through
+    modelMessages.push(msg)
   }
   return modelMessages
 }

package/src/activities/chat/middleware/compose.ts

@@ -26,7 +26,7 @@ function instrumentCtx(ctx: ChatMiddlewareContext) {
   return {
     requestId: ctx.requestId,
     streamId: ctx.streamId,
-    clientId: ctx.conversationId,
+    clientId: ctx.threadId,
     timestamp: Date.now(),
   }
 }

package/src/activities/chat/middleware/types.ts

@@ -28,7 +28,18 @@ export interface ChatMiddlewareContext {
   requestId: string
   /** Unique identifier for this stream */
   streamId: string
-  /** Conversation identifier, if provided by the caller */
+  /**
+   * AG-UI thread identifier — a stable per-conversation ID used to
+   * correlate client and server devtools events. Resolves to the
+   * caller-provided `threadId` (or legacy `conversationId`), or an
+   * auto-generated value when neither is supplied.
+   */
+  threadId: string
+  /**
+   * @deprecated Use `threadId` instead. Retained as an alias of
+   * `threadId` so middleware written before the AG-UI rename keeps
+   * working unchanged. Will be removed in a future major release.
+   */
   conversationId?: string
   /** Current lifecycle phase */
   phase: ChatMiddlewarePhase

package/src/activities/chat/tools/schema-converter.ts

@@ -254,6 +254,20 @@ export function convertSchemaToJsonSchema(
     return result as JSONSchema
   }
 
+  // Detect Standard Schema validators (Zod, ArkType, Valibot, …) that don't
+  // expose a `~standard.jsonSchema` converter. These would otherwise fall
+  // through to the JSONSchema pass-through below and ship `{ '~standard': … }`
+  // straight to the LLM provider, producing an opaque downstream error. Fail
+  // fast with actionable guidance instead.
+  if (isStandardSchema(schema)) {
+    throw new Error(
+      'Schema is a Standard Schema validator but does not expose a JSON Schema ' +
+        'converter on `~standard.jsonSchema`. Use Zod v4.2+, ArkType v2.1.28+, ' +
+        'or wrap a Valibot schema with `toStandardJsonSchema()` from ' +
+        '`@valibot/to-json-schema` before passing it as `outputSchema`.',
+    )
+  }
+
   // If it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through
   // Still apply structured output transformation if requested