@tanstack/ai 0.41.0 → 0.43.0

package/src/utilities/chat-params.ts

@@ -1,10 +1,15 @@
-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,
   ModelMessage,
-  SchemaInput,
-  Tool,
+  RunAgentResumeItem,
   UIMessage,
 } from '../types'
 
@@ -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 0.0.52 `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
@@ -49,6 +213,7 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
   tools: Array<{ name: string; description: string; parameters: JSONSchema }>
   forwardedProps: Record<string, unknown>
   state: unknown
+  resume?: Array<RunAgentResumeItem>
   /**
    * @deprecated Use `aguiContext` instead. This alias will be removed in a
    * future release.
@@ -56,54 +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,
+  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,
-  })
+  }
 }
 
 /**
@@ -163,6 +315,20 @@ export async function chatParamsFromRequest(
   }
 }
 
+/**
+ * Client-declared tool stub (no execute). `name` is `string`, so arrays that
+ * include these stubs intentionally widen `TypedStreamChunk` tool-name
+ * discrimination — pass server tools alone when you need a closed name union.
+ */
+export type ClientToolDeclaration = {
+  name: string
+  description: string
+  inputSchema: JSONSchema
+}
+
+export type MergedAgentTools<TServerTools extends ReadonlyArray<AnyTool>> =
+  ReadonlyArray<TServerTools[number] | ClientToolDeclaration>
+
 /**
  * Merge a server-side tool array with the AG-UI client-declared tools
  * received in the request body.
@@ -178,22 +344,46 @@ export async function chatParamsFromRequest(
  *   them — server emits a tool-call request, client executes via its
  *   registered handler, client posts back the result.
  *
+ * Typing:
+ * - Empty `clientTools` preserves the server tuple (closed name union).
+ * - Non-empty `clientTools` returns a widened array that honestly includes
+ *   client stubs, so `TypedStreamChunk` does not claim a closed server-only
+ *   name union.
+ *
  * @param serverTools - The server's tool array (e.g. from
  *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.
  * @param clientTools - The `tools` array received from
  *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
  * @returns A merged array suitable for `chat({ tools })`.
  */
-export function mergeAgentTools<TContext = unknown>(
-  serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>,
+export function mergeAgentTools<
+  const TServerTools extends ReadonlyArray<AnyTool>,
+>(serverTools: TServerTools, clientTools: readonly []): TServerTools
+export function mergeAgentTools<
+  const TServerTools extends ReadonlyArray<AnyTool>,
+>(
+  serverTools: TServerTools,
   clientTools: ReadonlyArray<{
     name: string
     description: string
     parameters: JSONSchema
   }>,
-): Array<Tool<SchemaInput, SchemaInput, string, TContext>> {
+): MergedAgentTools<TServerTools>
+export function mergeAgentTools<
+  const TServerTools extends ReadonlyArray<AnyTool>,
+>(
+  serverTools: TServerTools,
+  clientTools: ReadonlyArray<{
+    name: string
+    description: string
+    parameters: JSONSchema
+  }>,
+): TServerTools | MergedAgentTools<TServerTools> {
+  if (clientTools.length === 0) {
+    return serverTools
+  }
   const seen = new Set(serverTools.map((t) => t.name))
-  const merged: Array<Tool<SchemaInput, SchemaInput, string, TContext>> = [
+  const merged: Array<TServerTools[number] | ClientToolDeclaration> = [
     ...serverTools,
   ]
   for (const ct of clientTools) {
@@ -208,7 +398,7 @@ export function mergeAgentTools<TContext = unknown>(
       inputSchema: ct.parameters,
       // No `execute` — runtime treats this as a client-side tool and
       // emits ClientToolRequest events.
-    } as Tool<SchemaInput, SchemaInput, string, TContext>)
+    })
   }
   return merged
 }

package/dist/esm/activities/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;"}

package/dist/esm/adapter-internals.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter-internals.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/esm/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/middlewares/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}