@tanstack/ai 0.23.1 → 0.25.0

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

@@ -1,5 +1,5 @@
 import { Context as AGUIContext } from '@ag-ui/core';
-import { JSONSchema, ModelMessage, Tool, UIMessage } from '../types.js';
+import { JSONSchema, ModelMessage, SchemaInput, Tool, UIMessage } from '../types.js';
 /**
  * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.
  *
@@ -24,7 +24,12 @@ export declare function chatParamsFromRequestBody(body: unknown): Promise<{
     }>;
     forwardedProps: Record<string, unknown>;
     state: unknown;
+    /**
+     * @deprecated Use `aguiContext` instead. This alias will be removed in a
+     * future release.
+     */
     context: Array<AGUIContext>;
+    aguiContext: Array<AGUIContext>;
 }>;
 /**
  * Read an HTTP `Request`, parse its JSON body, and validate it as an
@@ -73,8 +78,8 @@ export declare function chatParamsFromRequest(req: Request): Promise<Awaited<Ret
  *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
  * @returns A merged array suitable for `chat({ tools })`.
  */
-export declare function mergeAgentTools(serverTools: ReadonlyArray<Tool>, clientTools: ReadonlyArray<{
+export declare function mergeAgentTools<TContext = unknown>(serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>, clientTools: ReadonlyArray<{
     name: string;
     description: string;
     parameters: JSONSchema;
-}>): Array<Tool>;
+}>): Array<Tool<SchemaInput, SchemaInput, string, TContext>>;

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

@@ -28,6 +28,7 @@ function chatParamsFromRequestBody(body) {
     );
   }
   const parsed = parseResult.data;
+  const aguiContext = parsed.context;
   const rawMessages = body.messages ?? [];
   const messages = parsed.messages.map((m, i) => {
     const raw = rawMessages[i];
@@ -44,7 +45,8 @@ function chatParamsFromRequestBody(body) {
     tools: parsed.tools,
     forwardedProps: parsed.forwardedProps ?? {},
     state: parsed.state,
-    context: parsed.context
+    context: aguiContext,
+    aguiContext
   });
 }
 async function chatParamsFromRequest(req) {
@@ -72,7 +74,9 @@ async function chatParamsFromRequest(req) {
 }
 function mergeAgentTools(serverTools, clientTools) {
   const seen = new Set(serverTools.map((t) => t.name));
-  const merged = [...serverTools];
+  const merged = [
+    ...serverTools
+  ];
   for (const ct of clientTools) {
     if (seen.has(ct.name)) {
       continue;

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

@@ -1 +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 { 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 { 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,QAA4B,QAAQ;AACtC,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,QAA4B,QAAQ;AACtC,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;"}
+{"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 {\n  JSONSchema,\n  ModelMessage,\n  SchemaInput,\n  Tool,\n  UIMessage,\n} 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  /**\n   * @deprecated Use `aguiContext` instead. This alias will be removed in a\n   * future release.\n   */\n  context: Array<AGUIContext>\n  aguiContext: 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  const aguiContext = parsed.context\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: aguiContext,\n    aguiContext,\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 { 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 { 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<TContext = unknown>(\n  serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>,\n  clientTools: ReadonlyArray<{\n    name: string\n    description: string\n    parameters: JSONSchema\n  }>,\n): Array<Tool<SchemaInput, SchemaInput, string, TContext>> {\n  const seen = new Set(serverTools.map((t) => t.name))\n  const merged: Array<Tool<SchemaInput, SchemaInput, string, TContext>> = [\n    ...serverTools,\n  ]\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<SchemaInput, SchemaInput, string, TContext>)\n  }\n  return merged\n}\n"],"names":[],"mappings":";AAUA,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,MAcvC;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;AAC3B,QAAM,cAAc,OAAO;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;AAAA,IACT;AAAA,EAAA,CACD;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,QAA4B,QAAQ;AACtC,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,QAA4B,QAAQ;AACtC,UAAM;AAAA,EACR;AACF;AAuBO,SAAS,gBACd,aACA,aAKyD;AACzD,QAAM,OAAO,IAAI,IAAI,YAAY,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC;AACnD,QAAM,SAAkE;AAAA,IACtE,GAAG;AAAA,EAAA;AAEL,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,CAGmC;AAAA,EACvD;AACA,SAAO;AACT;"}

package/dist/esm/utilities/tool-result.d.ts

@@ -0,0 +1,21 @@
+import { ContentPart } from '../types.js';
+/**
+ * Structural check for a single `ContentPart`. A text part must carry a string
+ * `content`; every other modality must carry a `source` with `type` of
+ * `'url' | 'data'` and a string `value`.
+ */
+export declare function isContentPart(value: unknown): value is ContentPart;
+/**
+ * True iff `value` is a NON-EMPTY array whose every element is a valid
+ * `ContentPart`. Empty arrays and mixed arrays return false so they continue
+ * to be treated as ordinary (stringified) data — this keeps the auto-detection
+ * footgun narrow.
+ */
+export declare function isContentPartArray(value: unknown): value is Array<ContentPart>;
+/**
+ * Normalize a tool's return value for transport:
+ * - string            → unchanged
+ * - ContentPart array → unchanged (multimodal, passed through to the adapter)
+ * - anything else     → `JSON.stringify`
+ */
+export declare function normalizeToolResult(result: unknown): string | Array<ContentPart>;

package/dist/esm/utilities/tool-result.js

@@ -0,0 +1,37 @@
+const CONTENT_PART_TYPES = /* @__PURE__ */ new Set([
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document"
+]);
+function isContentPart(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const part = value;
+  if (typeof part.type !== "string" || !CONTENT_PART_TYPES.has(part.type)) {
+    return false;
+  }
+  if (part.type === "text") {
+    return typeof part.content === "string";
+  }
+  const source = part.source;
+  if (typeof source !== "object" || source === null) return false;
+  const src = source;
+  if (typeof src.value !== "string") return false;
+  if (src.type === "data") return typeof src.mimeType === "string";
+  return src.type === "url";
+}
+function isContentPartArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isContentPart);
+}
+function normalizeToolResult(result) {
+  if (typeof result === "string") return result;
+  if (isContentPartArray(result)) return result;
+  return JSON.stringify(result);
+}
+export {
+  isContentPart,
+  isContentPartArray,
+  normalizeToolResult
+};
+//# sourceMappingURL=tool-result.js.map

package/dist/esm/utilities/tool-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.js","sources":["../../../src/utilities/tool-result.ts"],"sourcesContent":["import type { ContentPart } from '../types'\n\nconst CONTENT_PART_TYPES = new Set([\n  'text',\n  'image',\n  'audio',\n  'video',\n  'document',\n])\n\n/**\n * Structural check for a single `ContentPart`. A text part must carry a string\n * `content`; every other modality must carry a `source` with `type` of\n * `'url' | 'data'` and a string `value`.\n */\nexport function isContentPart(value: unknown): value is ContentPart {\n  if (typeof value !== 'object' || value === null) return false\n  const part = value as Record<string, unknown>\n  if (typeof part.type !== 'string' || !CONTENT_PART_TYPES.has(part.type)) {\n    return false\n  }\n  if (part.type === 'text') {\n    return typeof part.content === 'string'\n  }\n  const source = part.source\n  if (typeof source !== 'object' || source === null) return false\n  const src = source as Record<string, unknown>\n  if (typeof src.value !== 'string') return false\n  // `data` sources require a mimeType (matches ContentPartDataSource); `url`\n  // sources don't. Requiring it here keeps the runtime guard consistent with\n  // the type and avoids emitting `data:undefined;base64,...` downstream.\n  if (src.type === 'data') return typeof src.mimeType === 'string'\n  return src.type === 'url'\n}\n\n/**\n * True iff `value` is a NON-EMPTY array whose every element is a valid\n * `ContentPart`. Empty arrays and mixed arrays return false so they continue\n * to be treated as ordinary (stringified) data — this keeps the auto-detection\n * footgun narrow.\n */\nexport function isContentPartArray(\n  value: unknown,\n): value is Array<ContentPart> {\n  return Array.isArray(value) && value.length > 0 && value.every(isContentPart)\n}\n\n/**\n * Normalize a tool's return value for transport:\n * - string            → unchanged\n * - ContentPart array → unchanged (multimodal, passed through to the adapter)\n * - anything else     → `JSON.stringify`\n */\nexport function normalizeToolResult(\n  result: unknown,\n): string | Array<ContentPart> {\n  if (typeof result === 'string') return result\n  if (isContentPartArray(result)) return result\n  return JSON.stringify(result)\n}\n"],"names":[],"mappings":"AAEA,MAAM,yCAAyB,IAAI;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAOM,SAAS,cAAc,OAAsC;AAClE,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,OAAO;AACb,MAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GAAG;AACvE,WAAO;AAAA,EACT;AACA,MAAI,KAAK,SAAS,QAAQ;AACxB,WAAO,OAAO,KAAK,YAAY;AAAA,EACjC;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;AAC1D,QAAM,MAAM;AACZ,MAAI,OAAO,IAAI,UAAU,SAAU,QAAO;AAI1C,MAAI,IAAI,SAAS,OAAQ,QAAO,OAAO,IAAI,aAAa;AACxD,SAAO,IAAI,SAAS;AACtB;AAQO,SAAS,mBACd,OAC6B;AAC7B,SAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;AAQO,SAAS,oBACd,QAC6B;AAC7B,MAAI,OAAO,WAAW,SAAU,QAAO;AACvC,MAAI,mBAAmB,MAAM,EAAG,QAAO;AACvC,SAAO,KAAK,UAAU,MAAM;AAC9B;"}

package/dist/esm/utilities/usage.d.ts

@@ -0,0 +1,31 @@
+import { ProviderUsageDetails, TokenUsage } from '../types.js';
+/**
+ * Input parameters for building base TokenUsage.
+ * Provider functions should extract these from their SDK's response.
+ */
+export interface BaseUsageInput {
+    /** Total input/prompt tokens */
+    promptTokens: number;
+    /** Total output/completion tokens */
+    completionTokens: number;
+    /** Total tokens (prompt + completion) */
+    totalTokens: number;
+}
+/**
+ * Builds the base TokenUsage object with core fields.
+ * Provider-specific functions should use this and then add their own details.
+ *
+ * @param input - The base token counts
+ * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens
+ *
+ * @example
+ * ```typescript
+ * const base = buildBaseUsage({
+ *   promptTokens: 100,
+ *   completionTokens: 50,
+ *   totalTokens: 150
+ * });
+ * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }
+ * ```
+ */
+export declare function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(input: BaseUsageInput): TokenUsage<TProviderDetails>;

package/dist/esm/utilities/usage.js

@@ -0,0 +1,11 @@
+function buildBaseUsage(input) {
+  return {
+    promptTokens: input.promptTokens,
+    completionTokens: input.completionTokens,
+    totalTokens: input.totalTokens
+  };
+}
+export {
+  buildBaseUsage
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/utilities/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../../src/utilities/usage.ts"],"sourcesContent":["import type { ProviderUsageDetails, TokenUsage } from '../types'\n\n/**\n * Input parameters for building base TokenUsage.\n * Provider functions should extract these from their SDK's response.\n */\nexport interface BaseUsageInput {\n  /** Total input/prompt tokens */\n  promptTokens: number\n  /** Total output/completion tokens */\n  completionTokens: number\n  /** Total tokens (prompt + completion) */\n  totalTokens: number\n}\n\n/**\n * Builds the base TokenUsage object with core fields.\n * Provider-specific functions should use this and then add their own details.\n *\n * @param input - The base token counts\n * @returns A TokenUsage object with promptTokens, completionTokens, totalTokens\n *\n * @example\n * ```typescript\n * const base = buildBaseUsage({\n *   promptTokens: 100,\n *   completionTokens: 50,\n *   totalTokens: 150\n * });\n * // Returns: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }\n * ```\n */\nexport function buildBaseUsage<TProviderDetails = ProviderUsageDetails>(\n  input: BaseUsageInput,\n): TokenUsage<TProviderDetails> {\n  return {\n    promptTokens: input.promptTokens,\n    completionTokens: input.completionTokens,\n    totalTokens: input.totalTokens,\n  }\n}\n"],"names":[],"mappings":"AAgCO,SAAS,eACd,OAC8B;AAC9B,SAAO;AAAA,IACL,cAAc,MAAM;AAAA,IACpB,kBAAkB,MAAM;AAAA,IACxB,aAAa,MAAM;AAAA,EAAA;AAEvB;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.23.1",
+  "version": "0.25.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.4.2"
+    "@tanstack/ai-event-client": "0.5.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/src/activities/chat/adapter.ts

@@ -4,6 +4,7 @@ import type {
   Modality,
   StreamChunk,
   TextOptions,
+  TokenUsage,
 } from '../../types'
 
 /**
@@ -40,6 +41,8 @@ export interface StructuredOutputResult<T = unknown> {
   data: T
   /** The raw text response from the model before parsing */
   rawText: string
+  /** Token usage information (if provided by the adapter) */
+  usage?: TokenUsage
 }
 
 /**