@tanstack/ai 0.16.0 → 0.18.0

package/dist/esm/utilities/ag-ui-wire.js

@@ -0,0 +1,96 @@
+function uiMessagesToWire(messages) {
+  const wire = [];
+  for (const msg of messages) {
+    const parts = msg.parts ?? [];
+    if (msg.role === "system") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectText(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    if (msg.role === "user") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectUserContent(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    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 !== void 0 && { error: part.error }
+        });
+      }
+    }
+  }
+  return wire;
+}
+function collectText(parts) {
+  return parts.filter((p) => p.type === "text").map((p) => p.content).join("");
+}
+function collectUserContent(parts) {
+  const hasMultimodal = parts.some(
+    (p) => p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document"
+  );
+  if (!hasMultimodal) {
+    return collectText(parts);
+  }
+  const out = [];
+  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);
+    }
+  }
+  return out;
+}
+function collectToolCalls(parts) {
+  const calls = [];
+  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 : void 0;
+}
+function deriveReasoningId(messageId, part) {
+  return `${messageId}-reasoning-${part.id ?? hashContent(part.content)}`;
+}
+function deriveToolMessageId(toolCallId) {
+  return `tool-${toolCallId}`;
+}
+function hashContent(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) | 0;
+  return Math.abs(h).toString(36);
+}
+export {
+  uiMessagesToWire
+};
+//# sourceMappingURL=ag-ui-wire.js.map

package/dist/esm/utilities/ag-ui-wire.js.map

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

package/dist/esm/utilities/chat-params.d.ts

@@ -0,0 +1,80 @@
+import { Context as AGUIContext } from '@ag-ui/core';
+import { JSONSchema, ModelMessage, Tool, UIMessage } from '../types.js';
+/**
+ * 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 declare 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>;
+}>;
+/**
+ * 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 declare function chatParamsFromRequest(req: Request): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>>;
+/**
+ * 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 declare function mergeAgentTools(serverTools: ReadonlyArray<Tool>, clientTools: ReadonlyArray<{
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+}>): Array<Tool>;

package/dist/esm/utilities/chat-params.js

@@ -0,0 +1,96 @@
+import { RunAgentInputSchema, AGUIError } from "@ag-ui/core";
+const KNOWN_PART_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document",
+  "tool-call",
+  "tool-result",
+  "thinking"
+]);
+function isValidParts(value) {
+  if (!Array.isArray(value)) return false;
+  for (const p of value) {
+    if (!p || typeof p !== "object") return false;
+    const type = p.type;
+    if (typeof type !== "string" || !KNOWN_PART_TYPES.has(type)) return false;
+  }
+  return true;
+}
+function chatParamsFromRequestBody(body) {
+  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;
+  const rawMessages = body.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 };
+    }
+    return m;
+  });
+  return Promise.resolve({
+    messages,
+    threadId: parsed.threadId,
+    runId: parsed.runId,
+    parentRunId: parsed.parentRunId,
+    tools: parsed.tools,
+    forwardedProps: parsed.forwardedProps ?? {},
+    state: parsed.state,
+    context: parsed.context
+  });
+}
+async function chatParamsFromRequest(req) {
+  let body;
+  try {
+    body = await req.json();
+  } catch (cause) {
+    const res = new Response(
+      "Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.",
+      { status: 400 }
+    );
+    res.cause = cause;
+    throw res;
+  }
+  try {
+    return await chatParamsFromRequestBody(body);
+  } catch (cause) {
+    const res = new Response(
+      "Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.",
+      { status: 400 }
+    );
+    res.cause = cause;
+    throw res;
+  }
+}
+function mergeAgentTools(serverTools, clientTools) {
+  const seen = new Set(serverTools.map((t) => t.name));
+  const merged = [...serverTools];
+  for (const ct of clientTools) {
+    if (seen.has(ct.name)) {
+      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.
+    });
+  }
+  return merged;
+}
+export {
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  mergeAgentTools
+};
+//# sourceMappingURL=chat-params.js.map

package/dist/esm/utilities/chat-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-params.js","sources":["../../../src/utilities/chat-params.ts"],"sourcesContent":["import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'\nimport type { Context as AGUIContext } from '@ag-ui/core'\nimport type { JSONSchema, ModelMessage, Tool, UIMessage } from '../types'\n\nconst KNOWN_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n  'tool-call',\n  'tool-result',\n  'thinking',\n])\n\nfunction isValidParts(value: unknown): value is Array<{ type: string }> {\n  if (!Array.isArray(value)) return false\n  for (const p of value) {\n    if (!p || typeof p !== 'object') return false\n    const type = (p as { type?: unknown }).type\n    if (typeof type !== 'string' || !KNOWN_PART_TYPES.has(type)) return false\n  }\n  return true\n}\n\n/**\n * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.\n *\n * Returns a spread-friendly object whose `messages` field is suitable for\n * passing directly to `chat({ messages })`. The existing\n * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and\n * reasoning/activity/developer-role normalization internally.\n *\n * @throws An error with a migration-pointing message when the body does\n *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a\n *   400 Bad Request to the client.\n */\nexport function chatParamsFromRequestBody(body: unknown): Promise<{\n  messages: Array<UIMessage | ModelMessage>\n  threadId: string\n  runId: string\n  parentRunId?: string\n  tools: Array<{ name: string; description: string; parameters: JSONSchema }>\n  forwardedProps: Record<string, unknown>\n  state: unknown\n  context: Array<AGUIContext>\n}> {\n  const parseResult = RunAgentInputSchema.safeParse(body)\n  if (!parseResult.success) {\n    return Promise.reject(\n      new AGUIError(\n        `Request body is not a valid AG-UI RunAgentInput. ` +\n          `If you're upgrading from a previous @tanstack/ai-client release, ` +\n          `see docs/migration/ag-ui-compliance.md. ` +\n          `Validation errors: ${parseResult.error.message}`,\n      ),\n    )\n  }\n\n  const parsed = parseResult.data\n\n  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are\n  // dropped during parse. We re-attach them from the original body so the\n  // existing UIMessage path inside `chat()` can use them directly.\n  const rawMessages =\n    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []\n  const messages = parsed.messages.map((m, i) => {\n    const raw = rawMessages[i]\n    if (\n      raw &&\n      typeof raw === 'object' &&\n      'parts' in raw &&\n      isValidParts(raw.parts)\n    ) {\n      return { ...m, parts: raw.parts } as UIMessage | ModelMessage\n    }\n    return m as ModelMessage\n  })\n\n  return Promise.resolve({\n    messages,\n    threadId: parsed.threadId,\n    runId: parsed.runId,\n    parentRunId: parsed.parentRunId,\n    tools: parsed.tools as Array<{\n      name: string\n      description: string\n      parameters: JSONSchema\n    }>,\n    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,\n    state: parsed.state,\n    context: parsed.context,\n  })\n}\n\n/**\n * Read an HTTP `Request`, parse its JSON body, and validate it as an\n * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +\n * `chatParamsFromRequestBody(...)` pair into a single call.\n *\n * On a malformed body or invalid AG-UI shape, this **throws a\n * `Response`** with status 400 and a migration-pointing message in the\n * body. Frameworks that natively handle thrown `Response` objects\n * (TanStack Start, SolidStart, Remix, React Router 7) will return the\n * 400 to the client automatically, so the handler reduces to:\n *\n * ```ts\n * export async function POST(req: Request) {\n *   const params = await chatParamsFromRequest(req)\n *   // ...use params\n * }\n * ```\n *\n * In frameworks that do not auto-handle thrown `Response` objects\n * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call\n * with try/catch and return the caught Response yourself, or use\n * `chatParamsFromRequestBody` directly with your own JSON-parsing.\n *\n * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.\n */\nexport async function chatParamsFromRequest(\n  req: Request,\n): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    // Preserve the underlying error on the thrown Response for\n    // server-side observability without leaking it to the client.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n  try {\n    return await chatParamsFromRequestBody(body)\n  } catch (cause) {\n    // Generic public message — avoid echoing Zod paths (which can contain\n    // user payload fragments) or internal validator strings to the client.\n    // The original AGUIError is attached as `cause` so server logs can\n    // surface it without exposing it to remote callers.\n    const res = new Response(\n      'Invalid AG-UI request body. See docs/migration/ag-ui-compliance.md.',\n      { status: 400 },\n    )\n    ;(res as unknown as { cause?: unknown }).cause = cause\n    throw res\n  }\n}\n\n/**\n * Merge a server-side tool array with the AG-UI client-declared tools\n * received in the request body.\n *\n * Rules:\n * - Server tools win on name collision. The client's declaration is\n *   ignored if the server already has a tool with that name. The client's\n *   UI-side handler still fires when the streamed tool-result event comes\n *   through (see `chat-client.ts` `onToolCall`), giving the\n *   \"after server execution the client also handles\" semantic for free.\n * - Client-only tools (name not in `serverTools`) become no-execute\n *   entries: the runtime's existing `ClientToolRequest` path handles\n *   them — server emits a tool-call request, client executes via its\n *   registered handler, client posts back the result.\n *\n * @param serverTools - The server's tool array (e.g. from\n *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.\n * @param clientTools - The `tools` array received from\n *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.\n * @returns A merged array suitable for `chat({ tools })`.\n */\nexport function mergeAgentTools(\n  serverTools: ReadonlyArray<Tool>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool> = [...serverTools]\n  for (const ct of clientTools) {\n    if (seen.has(ct.name)) {\n      // Server wins on name collision.\n      continue\n    }\n    seen.add(ct.name)\n    merged.push({\n      name: ct.name,\n      description: ct.description,\n      inputSchema: ct.parameters,\n      // No `execute` — runtime treats this as a client-side tool and\n      // emits ClientToolRequest events.\n    } as Tool)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAIA,MAAM,uCAAuB,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,SAAS,aAAa,OAAkD;AACtE,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,aAAW,KAAK,OAAO;AACrB,QAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,UAAM,OAAQ,EAAyB;AACvC,QAAI,OAAO,SAAS,YAAY,CAAC,iBAAiB,IAAI,IAAI,EAAG,QAAO;AAAA,EACtE;AACA,SAAO;AACT;AAcO,SAAS,0BAA0B,MASvC;AACD,QAAM,cAAc,oBAAoB,UAAU,IAAI;AACtD,MAAI,CAAC,YAAY,SAAS;AACxB,WAAO,QAAQ;AAAA,MACb,IAAI;AAAA,QACF,gLAGwB,YAAY,MAAM,OAAO;AAAA,MAAA;AAAA,IACnD;AAAA,EAEJ;AAEA,QAAM,SAAS,YAAY;AAK3B,QAAM,cACH,KAAuD,YAAY,CAAA;AACtE,QAAM,WAAW,OAAO,SAAS,IAAI,CAAC,GAAG,MAAM;AAC7C,UAAM,MAAM,YAAY,CAAC;AACzB,QACE,OACA,OAAO,QAAQ,YACf,WAAW,OACX,aAAa,IAAI,KAAK,GACtB;AACA,aAAO,EAAE,GAAG,GAAG,OAAO,IAAI,MAAA;AAAA,IAC5B;AACA,WAAO;AAAA,EACT,CAAC;AAED,SAAO,QAAQ,QAAQ;AAAA,IACrB;AAAA,IACA,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,aAAa,OAAO;AAAA,IACpB,OAAO,OAAO;AAAA,IAKd,gBAAiB,OAAO,kBAAkB,CAAA;AAAA,IAC1C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,EAAA,CACjB;AACH;AA2BA,eAAsB,sBACpB,KACgE;AAChE,MAAI;AACJ,MAAI;AACF,WAAO,MAAM,IAAI,KAAA;AAAA,EACnB,SAAS,OAAO;AAGd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACA,MAAI;AACF,WAAO,MAAM,0BAA0B,IAAI;AAAA,EAC7C,SAAS,OAAO;AAKd,UAAM,MAAM,IAAI;AAAA,MACd;AAAA,MACA,EAAE,QAAQ,IAAA;AAAA,IAAI;AAEd,QAAuC,QAAQ;AACjD,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKa;AACb,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAsB,CAAC,GAAG,WAAW;AAC3C,aAAW,MAAM,aAAa;AAC5B,QAAI,KAAK,IAAI,GAAG,IAAI,GAAG;AAErB;AAAA,IACF;AACA,SAAK,IAAI,GAAG,IAAI;AAChB,WAAO,KAAK;AAAA,MACV,MAAM,GAAG;AAAA,MACT,aAAa,GAAG;AAAA,MAChB,aAAa,GAAG;AAAA;AAAA;AAAA,IAAA,CAGT;AAAA,EACX;AACA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -53,9 +53,9 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "0.0.49",
+    "@ag-ui/core": "^0.0.52",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.3.0"
+    "@tanstack/ai-event-client": "0.3.2"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/ag-ui-protocol/SKILL.md

@@ -39,6 +39,47 @@ export async function POST(request: Request) {
 typed AG-UI event (discriminated union on `type`). The `toServerSentEventsResponse()`
 helper encodes that iterable into an SSE-formatted `Response` with correct headers.
 
+## Setup — Receiving AG-UI RunAgentInput on the Server
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequestBody,
+  mergeAgentTools,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai/adapters'
+import { serverTools } from './tools'
+
+export async function POST(req: Request) {
+  let params
+  try {
+    params = await chatParamsFromRequestBody(await req.json())
+  } catch (error) {
+    return new Response(
+      error instanceof Error ? error.message : 'Bad request',
+      { status: 400 },
+    )
+  }
+
+  const stream = chat({
+    adapter: openaiText('gpt-4o'),
+    messages: params.messages,
+    tools: mergeAgentTools(serverTools, params.tools),
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`chatParamsFromRequestBody` validates the body against `RunAgentInputSchema` from `@ag-ui/core`. `mergeAgentTools` merges the server's tool registry with client-declared tools (server wins on collision; client-only tools become no-execute stubs that flow through the runtime's `ClientToolRequest` path).
+
+`params.messages` is a mixed array of TanStack `UIMessage` anchors (with `parts`) and AG-UI fan-out duplicates (`{role:'tool',...}`, `{role:'reasoning',...}`). The existing `convertMessagesToModelMessages` (called inside `chat()`) handles dedup automatically.
+
+**Wire shape (POST body):** AG-UI `RunAgentInput` — `{threadId, runId, parentRunId?, state, messages, tools, context, forwardedProps}`. The `messages` array carries TanStack `UIMessage` anchors with their canonical `parts` plus AG-UI mirror fields (`content`, `toolCalls`) inline; tool results and thinking parts are additionally emitted as fan-out `{role:'tool',...}` and `{role:'reasoning',...}` entries.
+
+**`forwardedProps` security:** Don't spread it directly into `chat()` — clients could override `adapter`, `model`, `tools`, etc. Always allowlist specific fields.
+
 ## Core Patterns
 
 ### 1. SSE Format — toServerSentEventsStream / toServerSentEventsResponse
@@ -223,9 +264,11 @@ Source: docs/protocol/chunk-definitions.md
 
 ## Tension
 
-HIGH Tension: AG-UI protocol compliance vs. internal message format -- TanStack
-AI's `UIMessage` format (parts-based) diverges from AG-UI spec (content-based).
-Full compliance would require a different message structure.
+RESOLVED: TanStack AI is fully AG-UI compliant on both axes (server→client events
+AND client→server `RunAgentInput`). The wire format carries TanStack `UIMessage`
+anchors with their parts intact alongside AG-UI fan-out messages, so strict AG-UI
+servers see role-based messages while TanStack-aware servers read parts directly
+without transformation. See `docs/migration/ag-ui-compliance.md` for details.
 
 ## Cross-References
 

package/skills/ai-core/structured-outputs/SKILL.md

@@ -4,7 +4,9 @@ description: >
   Type-safe JSON schema responses from LLMs using outputSchema on chat().
   Supports Zod, ArkType, and Valibot schemas. The adapter handles
   provider-specific strategies transparently — never configure structured
-  output at the provider level. convertSchemaToJsonSchema() for manual
+  output at the provider level. Pass stream:true alongside outputSchema for
+  incremental JSON deltas + a terminal validated object via the
+  `structured-output.complete` event. convertSchemaToJsonSchema() for manual
   schema conversion.
 type: sub-skill
 library: tanstack-ai
@@ -46,6 +48,8 @@ const stream = chat({
 
 When `outputSchema` is provided, `chat()` returns `Promise<InferSchemaType<TSchema>>` instead of `AsyncIterable<StreamChunk>`. The result is fully typed based on the schema.
 
+Adding `stream: true` switches the return to `StructuredOutputStream<InferSchemaType<TSchema>>` — incremental JSON deltas plus a terminal validated object. See **Pattern 3** below.
+
 ## Core Patterns
 
 ### Pattern 1: Basic structured output with Zod
@@ -128,8 +132,94 @@ console.log(company.employees[0].role)
 console.log(company.financials?.revenue)
 ```
 
+### Pattern 3: Streaming structured output
+
+Pass `stream: true` alongside `outputSchema` to receive incremental JSON deltas while the model generates, plus a final validated typed object. Useful for streaming partial UI (progress views, typewriter previews, partially-filled forms).
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { z } from 'zod'
+
+const PersonSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.string().email(),
+})
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages: [
+    { role: 'user', content: 'Extract: John Doe is 30, john@example.com' },
+  ],
+  outputSchema: PersonSchema,
+  stream: true,
+})
+
+let raw = ''
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    // Partial JSON text — drive progress UI only. Do NOT JSON.parse.
+    raw += chunk.delta
+  } else if (
+    chunk.type === 'CUSTOM' &&
+    chunk.name === 'structured-output.complete'
+  ) {
+    // Terminal event. `chunk.value.object` is fully validated and typed
+    // against the schema you passed in — no helper or cast required.
+    chunk.value.object.name // string
+    chunk.value.object.age // number
+    chunk.value.reasoning // string | undefined (thinking models only)
+  }
+}
+```
+
+The terminal event is a `CUSTOM` chunk: `{ type: 'CUSTOM', name: 'structured-output.complete', value: { object: T, raw: string, reasoning?: string } }`. The return type of `chat({ outputSchema, stream: true })` carries `T` through to the terminal event, so a plain discriminated narrow (`chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete'`) is enough — no type guard helper needed.
+
+**Adapter coverage for streaming:**
+
+| Adapter                                           | `outputSchema` + `stream: true`                                                               |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@tanstack/ai-openai`                             | Native single-request stream (Responses API)                                                  |
+| `@tanstack/ai-openrouter`                         | Native single-request stream                                                                  |
+| `@tanstack/ai-grok`                               | Native single-request stream (Chat Completions)                                               |
+| `@tanstack/ai-groq`                               | Native single-request stream (Chat Completions)                                               |
+| All other adapters (anthropic, gemini, ollama, …) | Fallback: runs non-streaming `structuredOutput`, emits one `structured-output.complete` event |
+
+The consumer code is identical across providers — always read the final object off `structured-output.complete`. You only see incremental deltas when the adapter implements `structuredOutputStream` natively.
+
 ## Common Mistakes
 
+### HIGH: Parsing streaming JSON deltas yourself
+
+When using `chat({ outputSchema, stream: true })`, the `TEXT_MESSAGE_CONTENT` chunks contain _partial_ JSON fragments — they are not valid JSON until the stream completes. Always read the validated object from the terminal `structured-output.complete` event. Validation runs once, on the complete payload.
+
+```typescript
+// WRONG -- partial JSON, throws SyntaxError mid-stream, no schema validation
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    const obj = JSON.parse(chunk.delta) // ❌ partial, invalid
+  }
+}
+
+// CORRECT -- accumulate deltas only for UX progress; trust the terminal event
+let raw = ''
+for await (const chunk of stream) {
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+    raw += chunk.delta // optional: render a "streaming JSON" preview
+  } else if (
+    chunk.type === 'CUSTOM' &&
+    chunk.name === 'structured-output.complete'
+  ) {
+    const result = chunk.value.object // ✅ typed and validated
+  }
+}
+```
+
+If you need progressive _parsed_ state (e.g. show fields as they arrive), use a partial-JSON parser on the accumulated `raw` string at render time — but do NOT treat the result as schema-validated; only the terminal event is.
+
+Source: maintainer interview
+
 ### HIGH: Trying to implement provider-specific structured output strategies
 
 The adapter already handles provider differences (OpenAI uses `response_format`, Anthropic uses tool-based extraction, Gemini uses `responseSchema`). Never configure this yourself.
@@ -201,3 +291,4 @@ Source: maintainer interview
 ## Cross-References
 
 - See also: ai-core/adapter-configuration/SKILL.md -- Adapter handles structured output strategy transparently
+- See also: ai-core/chat-experience/SKILL.md -- Consuming `StreamChunk` events on the client (the streaming variant uses the same chunk model plus the terminal `structured-output.complete` custom event)

package/src/activities/chat/adapter.ts

@@ -100,6 +100,23 @@ export interface TextAdapter<
   structuredOutput: (
     options: StructuredOutputOptions<TProviderOptions>,
   ) => Promise<StructuredOutputResult<unknown>>
+
+  /**
+   * Stream structured output using the provider's native streaming structured
+   * output API (stream + response_format json_schema in a single request).
+   *
+   * Optional — adapters without native streaming JSON omit this method and the
+   * activity layer synthesizes a stream around the non-streaming
+   * `structuredOutput` call.
+   *
+   * Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,
+   * TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final
+   * `CUSTOM` event named `structured-output.complete` whose `value` is
+   * `{ object, raw, reasoning? }`.
+   */
+  structuredOutputStream?: (
+    options: StructuredOutputOptions<TProviderOptions>,
+  ) => AsyncIterable<StreamChunk>
 }
 
 /**