@tanstack/ai 0.17.0 → 0.18.0

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.17.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.1"
+    "@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/src/activities/chat/index.ts

@@ -48,6 +48,7 @@ import type {
   ToolCallArgsEvent,
   ToolCallEndEvent,
   ToolCallStartEvent,
+  UIMessage,
 } from '../../types'
 import type {
   ChatMiddleware,
@@ -85,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']
@@ -128,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:
@@ -313,6 +325,7 @@ class TextEngine<
   // AG-UI protocol IDs
   private threadId: string
   private runIdOverride?: string
+  private parentRunIdOverride?: string
 
   // Middleware support
   private readonly middlewareRunner: MiddlewareRunner
@@ -364,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
@@ -381,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,
@@ -429,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 {
@@ -508,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,
@@ -634,6 +657,7 @@ class TextEngine<
       logger: this.logger,
       threadId: this.threadId,
       runId: this.runIdOverride,
+      parentRunId: this.parentRunIdOverride,
     })) {
       if (this.isCancelled()) {
         break

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
 

package/src/index.ts

@@ -168,6 +168,17 @@ export type {
   JSONParser,
 } from './activities/chat/stream/index'
 
+// Chat utilities
+export {
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
+  mergeAgentTools,
+} from './utilities/chat-params'
+
+// AG-UI wire serialization (used internally by @tanstack/ai-client)
+export { uiMessagesToWire } from './utilities/ag-ui-wire'
+export type { WireMessage } from './utilities/ag-ui-wire'
+
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
 export type { ExtendedModelDef } from './extend-adapter'

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
 }
 
 // ============================================================================