refactor(ai): remove zod from the dependency graph

.changeset/ag-ui-core-zod-free.md

@@ -0,0 +1,25 @@
+---
+'@tanstack/ai': minor
+---
+
+Remove zod from `@tanstack/ai`'s dependency graph entirely.
+
+`@ag-ui/core` is bumped to `0.1.1-canary.beta.0`, which drops zod from its
+runtime dependencies and declares it as an optional peer instead. Previously
+every `@tanstack/ai` install pulled zod in transitively through it.
+
+`chatParamsFromRequest` / `chatParamsFromRequestBody` were the only zod
+consumers in this package — they validated request bodies with AG-UI's
+`RunAgentInputSchema`. They now validate the same `RunAgentInput` contract
+structurally, so `@tanstack/ai` ships with no schema-validation runtime at all
+and neither requires nor suggests zod.
+
+No API change: both helpers keep their signatures, still reject non-conforming
+bodies with a migration-pointing `AGUIError` (`chatParamsFromRequest` still
+throws a 400 `Response`), and still carry TanStack's canonical `parts` field
+through on messages. Validation errors now name the offending field —
+`messages[1].content must be a string` instead of a zod issue dump.
+
+zod remains fully supported for defining tools; it is simply no longer
+installed on your behalf. If you relied on getting zod transitively without
+declaring it, add it explicitly: `npm install zod`.

docs/comparison/vercel-ai-sdk.md

@@ -379,9 +379,10 @@ const logger: ChatMiddleware = {
     console.log(`[${ctx.requestId}] Chat started`)
   },
   onChunk: (ctx, chunk) => {
-    // Transform, expand, or drop chunks
-    if ('delta' in chunk && 'messageId' in chunk) {
-      return { ...chunk, delta: chunk.delta!.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[REDACTED]') }
+    // Transform, expand, or drop chunks. `type` is the discriminant, so it
+    // narrows `chunk` to the matching event and types `delta` as `string`.
+    if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+      return { ...chunk, delta: chunk.delta.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[REDACTED]') }
     }
   },
   onBeforeToolCall: (ctx, hookCtx) => {

docs/config.json

@@ -660,7 +660,7 @@
           "label": "AG-UI Client Compliance",
           "to": "migration/ag-ui-compliance",
           "addedAt": "2026-05-16",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-31"
         },
         {
           "label": "Sampling → modelOptions",

docs/migration/ag-ui-compliance.md

@@ -363,7 +363,37 @@ Pure AG-UI `RunAgentInput` payloads (no TanStack `parts` field) work end-to-end:
 
 ## `@ag-ui/core` bump
 
-`@tanstack/ai` now depends on `@ag-ui/core@^0.0.52`. If your code imports types from `@tanstack/ai` that re-export AG-UI types, you may need minor type adjustments — see the changeset for specifics.
+`@tanstack/ai` now depends on `@ag-ui/core@0.1.1-canary.beta.0`. If your code imports types from `@tanstack/ai` that re-export AG-UI types, you may need minor type adjustments — see the changeset for specifics.
+
+### zod is no longer installed for you
+
+`@ag-ui/core` used to list `zod` as a runtime dependency, so every
+`@tanstack/ai` install pulled zod in transitively. As of `0.1.x` it declares zod
+as an optional peer instead, and `@tanstack/ai` no longer uses zod anywhere —
+the package now ships with no schema-validation runtime at all.
+
+`chatParamsFromRequest` / `chatParamsFromRequestBody` were the only zod
+consumers: they validated the request body with AG-UI's `RunAgentInputSchema`.
+They now validate the same `RunAgentInput` contract structurally. Their
+signatures, their thrown types (`AGUIError`, and a 400 `Response` from
+`chatParamsFromRequest`), and the `parts` passthrough on messages are all
+unchanged. The one visible difference is friendlier failures — the error names
+the offending field, e.g.:
+
+```
+Request body is not a valid AG-UI RunAgentInput. ... Validation errors: messages[1].content must be a string
+```
+
+zod is still fully supported for defining tools; it is just no longer installed
+on your behalf. If your project used zod without declaring it — relying on the
+transitive copy — add it explicitly:
+
+```bash
+npm install zod
+```
+
+If you define tools with a different Standard Schema library (ArkType, Valibot),
+you can now drop zod entirely.
 
 ## Out of scope (existing behavior preserved)
 

packages/ai/package.json

@@ -89,7 +89,7 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "^0.0.57",
+    "@ag-ui/core": "0.1.1-canary.beta.0",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/ai-event-client": "workspace:*",
     "@tanstack/ai-utils": "workspace:*",

packages/ai/src/utilities/chat-params.ts

@@ -1,5 +1,10 @@
-import { AGUIError, RunAgentInputSchema } from '@ag-ui/core'
-import type { Context as AGUIContext } from '@ag-ui/core'
+import { AGUIError } from '@ag-ui/core'
+import type {
+  Context as AGUIContext,
+  Message as AGUIMessage,
+  ResumeEntry as AGUIResumeEntry,
+  Role as AGUIRole,
+} from '@ag-ui/core'
 import type {
   AnyTool,
   JSONSchema,
@@ -29,6 +34,162 @@ function isValidParts(value: unknown): value is Array<{ type: string }> {
   return true
 }
 
+/**
+ * Keyed by `AGUIRole` so a role added upstream fails to compile here until it
+ * is handled, rather than silently falling through as an unknown role.
+ */
+const AGUI_ROLES: Record<AGUIRole, true> = {
+  developer: true,
+  system: true,
+  assistant: true,
+  user: true,
+  tool: true,
+  activity: true,
+  reasoning: true,
+}
+
+function isAGUIRole(value: unknown): value is AGUIRole {
+  return typeof value === 'string' && value in AGUI_ROLES
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Reject the request body, pointing at the migration guide. Mirrors the
+ * message the previous `RunAgentInputSchema.safeParse` failure produced.
+ */
+function invalidBody(reason: string): never {
+  throw 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: ${reason}`,
+  )
+}
+
+function requireString(value: unknown, at: string): string {
+  if (typeof value !== 'string') invalidBody(`${at} must be a string`)
+  return value
+}
+
+function requireArray(value: unknown, at: string): Array<unknown> {
+  if (!Array.isArray(value)) invalidBody(`${at} must be an array`)
+  return value
+}
+
+/**
+ * Assert one AG-UI `Message`, discriminating on `role` exactly as the upstream
+ * `MessageSchema` discriminated union does. The record view is retained on the
+ * asserted type so callers can still inspect non-AG-UI extras like `parts`.
+ */
+function assertAGUIMessage(
+  value: Record<string, unknown>,
+  at: string,
+): asserts value is Record<string, unknown> & AGUIMessage {
+  requireString(value.id, `${at}.id`)
+
+  const role = value.role
+  if (!isAGUIRole(role)) {
+    invalidBody(
+      `${at}.role must be one of ${Object.keys(AGUI_ROLES).join(' | ')}`,
+    )
+  }
+
+  switch (role) {
+    case 'assistant':
+      // Both optional: a tool-calling turn carries no text content.
+      if (value.content !== undefined) {
+        requireString(value.content, `${at}.content`)
+      }
+      if (value.toolCalls !== undefined) {
+        requireArray(value.toolCalls, `${at}.toolCalls`)
+      }
+      break
+    case 'user':
+      if (typeof value.content !== 'string' && !Array.isArray(value.content)) {
+        invalidBody(
+          `${at}.content must be a string or an array of content parts`,
+        )
+      }
+      break
+    case 'tool':
+      requireString(value.content, `${at}.content`)
+      requireString(value.toolCallId, `${at}.toolCallId`)
+      break
+    case 'activity':
+      requireString(value.activityType, `${at}.activityType`)
+      if (!isRecord(value.content)) {
+        invalidBody(`${at}.content must be an object`)
+      }
+      break
+    case 'developer':
+    case 'system':
+    case 'reasoning':
+      requireString(value.content, `${at}.content`)
+      break
+  }
+}
+
+function validateMessage(value: unknown, index: number): AGUIMessage {
+  const at = `messages[${index}]`
+  if (!isRecord(value)) invalidBody(`${at} must be an object`)
+  assertAGUIMessage(value, at)
+
+  // `parts` is TanStack's canonical extra, carried through so the UIMessage
+  // path inside `chat()` can use it. Keep it only when it holds recognized
+  // part types — the previous schema-based path dropped `parts` during parse
+  // and re-attached it from the raw body behind this same check.
+  if ('parts' in value && !isValidParts(value.parts)) {
+    const withoutParts = { ...value }
+    Reflect.deleteProperty(withoutParts, 'parts')
+    return withoutParts
+  }
+  return value
+}
+
+function validateTool(
+  value: unknown,
+  index: number,
+): { name: string; description: string; parameters: JSONSchema } {
+  const at = `tools[${index}]`
+  if (!isRecord(value)) invalidBody(`${at} must be an object`)
+  return {
+    name: requireString(value.name, `${at}.name`),
+    description: requireString(value.description, `${at}.description`),
+    // Upstream `ToolSchema` types this as optional `any`; it reaches the
+    // provider as a raw JSON Schema either way.
+    parameters: value.parameters as JSONSchema,
+  }
+}
+
+function validateContext(value: unknown, index: number): AGUIContext {
+  const at = `context[${index}]`
+  if (!isRecord(value)) invalidBody(`${at} must be an object`)
+  return {
+    description: requireString(value.description, `${at}.description`),
+    value: requireString(value.value, `${at}.value`),
+  }
+}
+
+function validateResumeEntry(value: unknown, index: number): AGUIResumeEntry {
+  const at = `resume[${index}]`
+  if (!isRecord(value)) invalidBody(`${at} must be an object`)
+  const status = value.status
+  if (status !== 'resolved' && status !== 'cancelled') {
+    invalidBody(`${at}.status must be "resolved" or "cancelled"`)
+  }
+  const entry: AGUIResumeEntry = {
+    interruptId: requireString(value.interruptId, `${at}.interruptId`),
+    status,
+  }
+  // Omit the key entirely when absent, matching the optional-field shape the
+  // schema produced.
+  if (value.payload !== undefined) entry.payload = value.payload
+  return entry
+}
+
 /**
  * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.
  *
@@ -37,11 +198,14 @@ function isValidParts(value: unknown): value is Array<{ type: string }> {
  * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and
  * reasoning/activity/developer-role normalization internally.
  *
+ * Validated structurally against the AG-UI `RunAgentInput` contract without a
+ * schema library, so this package pulls in no validation runtime of its own.
+ *
  * @throws An error with a migration-pointing message when the body does
- *   not conform to AG-UI `RunAgentInputSchema`. Surface this as a
+ *   not conform to AG-UI `RunAgentInput`. Surface this as a
  *   400 Bad Request to the client.
  */
-export function chatParamsFromRequestBody(body: unknown): Promise<{
+export async function chatParamsFromRequestBody(body: unknown): Promise<{
   messages: Array<UIMessage | ModelMessage>
   threadId: string
   runId: string
@@ -57,55 +221,41 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
   context: Array<AGUIContext>
   aguiContext: Array<AGUIContext>
 }> {
-  const parseResult = RunAgentInputSchema.safeParse(body)
-  if (!parseResult.success) {
-    return Promise.reject(
-      new AGUIError(
-        `Request body is not a valid AG-UI RunAgentInput. ` +
-          `If you're upgrading from a previous @tanstack/ai-client release, ` +
-          `see docs/migration/ag-ui-compliance.md. ` +
-          `Validation errors: ${parseResult.error.message}`,
-      ),
-    )
+  if (!isRecord(body)) invalidBody('body must be a JSON object')
+
+  const threadId = requireString(body.threadId, 'threadId')
+  const runId = requireString(body.runId, 'runId')
+  const parentRunId =
+    body.parentRunId === undefined
+      ? undefined
+      : requireString(body.parentRunId, 'parentRunId')
+
+  const messages = requireArray(body.messages, 'messages').map(validateMessage)
+  const tools = requireArray(body.tools, 'tools').map(validateTool)
+  const aguiContext = requireArray(body.context, 'context').map(validateContext)
+  const resume =
+    body.resume === undefined
+      ? undefined
+      : requireArray(body.resume, 'resume').map(validateResumeEntry)
+
+  if (body.forwardedProps !== undefined && !isRecord(body.forwardedProps)) {
+    invalidBody('forwardedProps must be an object')
   }
 
-  const parsed = parseResult.data
-  const aguiContext = parsed.context
-
-  // AG-UI Zod uses `.strip()` so extra fields like `parts` on messages are
-  // dropped during parse. We re-attach them from the original body so the
-  // existing UIMessage path inside `chat()` can use them directly.
-  const rawMessages =
-    (body as { messages?: Array<Record<string, unknown>> }).messages ?? []
-  const messages = parsed.messages.map((m, i) => {
-    const raw = rawMessages[i]
-    if (
-      raw &&
-      typeof raw === 'object' &&
-      'parts' in raw &&
-      isValidParts(raw.parts)
-    ) {
-      return { ...m, parts: raw.parts } as UIMessage | ModelMessage
-    }
-    return m as ModelMessage
-  })
-
-  return Promise.resolve({
-    messages,
-    threadId: parsed.threadId,
-    runId: parsed.runId,
-    parentRunId: parsed.parentRunId,
-    tools: parsed.tools as Array<{
-      name: string
-      description: string
-      parameters: JSONSchema
-    }>,
-    forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,
-    state: parsed.state,
-    resume: parsed.resume,
+  return {
+    // Unknown top-level fields (e.g. a legacy `cursor`) are dropped by
+    // construction: only the fields below are copied onto the result.
+    messages: messages as Array<UIMessage | ModelMessage>,
+    threadId,
+    runId,
+    parentRunId,
+    tools,
+    forwardedProps: (body.forwardedProps ?? {}) as Record<string, unknown>,
+    state: body.state,
+    resume: resume as Array<RunAgentResumeItem> | undefined,
     context: aguiContext,
     aguiContext,
-  })
+  }
 }
 
 /**