@tanstack/ai 0.36.0 → 0.37.0

package/dist/esm/utilities/ag-ui-wire.d.ts

@@ -0,0 +1,44 @@
+import { ContentPart, UIMessage } from '../types.js';
+type AGUITextInputContent = {
+    type: 'text';
+    text: string;
+};
+type AGUIInputContent = AGUITextInputContent | (ContentPart & {
+    type: 'image' | 'audio' | 'video' | 'document';
+});
+type AGUIToolCallMirror = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+type AGUIToolMessage = {
+    role: 'tool';
+    id: string;
+    toolCallId: string;
+    content: string;
+    error?: string;
+};
+type AGUIReasoningMessage = {
+    role: 'reasoning';
+    id: string;
+    content: string;
+};
+type WireAnchorMessage = UIMessage & {
+    content?: string | Array<AGUIInputContent>;
+    toolCalls?: Array<AGUIToolCallMirror>;
+};
+export type WireMessage = WireAnchorMessage | AGUIToolMessage | AGUIReasoningMessage;
+/**
+ * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`
+ * wire shape. Each anchor (system/user/assistant) carries the canonical
+ * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)
+ * so AG-UI Zod parsing succeeds. Tool results and thinking parts on
+ * assistant messages are additionally emitted as fan-out
+ * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict
+ * AG-UI server consumers.
+ */
+export declare function uiMessagesToWire(messages: Array<UIMessage>): Array<WireMessage>;
+export {};

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

@@ -0,0 +1,107 @@
+function uiMessagesToWire(messages) {
+  const wire = [];
+  for (const msg of messages) {
+    const parts = (
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- runtime input may be ModelMessage-shaped (no `parts`); cast forces the optional-chain fallback below to remain in scope
+      msg.parts ?? []
+    );
+    if (msg.role === "system") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectText(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    if (msg.role === "user") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectUserContent(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    for (const part of parts) {
+      if (part.type === "thinking") {
+        wire.push({
+          role: "reasoning",
+          id: deriveReasoningId(msg.id, part),
+          content: part.content
+        });
+      }
+    }
+    const text = collectText(parts);
+    const toolCalls = collectToolCalls(parts);
+    wire.push({
+      ...msg,
+      ...text !== "" && { content: text },
+      ...toolCalls && { toolCalls }
+    });
+    for (const part of parts) {
+      if (part.type === "tool-result") {
+        wire.push({
+          role: "tool",
+          id: deriveToolMessageId(part.toolCallId),
+          toolCallId: part.toolCallId,
+          content: typeof part.content === "string" ? part.content : JSON.stringify(part.content),
+          ...part.error !== void 0 && { error: part.error }
+        });
+      }
+    }
+  }
+  return wire;
+}
+function collectText(parts) {
+  const out = [];
+  for (const p of parts) {
+    if (p.type === "text") {
+      out.push(p.content);
+    } else if (p.type === "structured-output" && p.status === "complete" && p.raw !== "") {
+      out.push(p.raw);
+    }
+  }
+  return out.join("");
+}
+function collectUserContent(parts) {
+  const hasMultimodal = parts.some(
+    (p) => p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document"
+  );
+  if (!hasMultimodal) {
+    return collectText(parts);
+  }
+  const out = [];
+  for (const p of parts) {
+    if (p.type === "text") {
+      out.push({ type: "text", text: p.content });
+    } else if (p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document") {
+      out.push(p);
+    }
+  }
+  return out;
+}
+function collectToolCalls(parts) {
+  const calls = [];
+  for (const p of parts) {
+    if (p.type === "tool-call") {
+      calls.push({
+        id: p.id,
+        type: "function",
+        function: { name: p.name, arguments: p.arguments }
+      });
+    }
+  }
+  return calls.length > 0 ? calls : void 0;
+}
+function deriveReasoningId(messageId, part) {
+  return `${messageId}-reasoning-${part.id ?? hashContent(part.content)}`;
+}
+function deriveToolMessageId(toolCallId) {
+  return `tool-${toolCallId}`;
+}
+function hashContent(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) | 0;
+  return Math.abs(h).toString(36);
+}
+export {
+  uiMessagesToWire
+};
+//# sourceMappingURL=ag-ui-wire.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui-wire.js","sources":["../../../src/utilities/ag-ui-wire.ts"],"sourcesContent":["import type { ContentPart, MessagePart, 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      // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- runtime input may be ModelMessage-shaped (no `parts`); cast forces the optional-chain fallback below to remain in scope\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 { 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 { 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:\n            typeof part.content === 'string'\n              ? part.content\n              : JSON.stringify(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  // The streamed JSON of a completed structured-output part is the source of\n  // truth for multi-turn coherence — emitting it back as assistant content\n  // lets the LLM see its own prior structured response. Streaming/errored\n  // parts are skipped: they'd ship malformed JSON fragments and confuse the\n  // model. `completeStructuredOutputPart` tries hard to populate `raw`\n  // (caller → existing buffer → `JSON.stringify(data)`), but the stringify\n  // fallback can leave it empty when `data` is unserializable (BigInt,\n  // circular). The `p.raw !== ''` guard below is what enforces \"no malformed\n  // round-trip\" in that case — without it we'd ship `''` and the model would\n  // see an empty assistant turn.\n  const out: Array<string> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push(p.content)\n    } else if (\n      p.type === 'structured-output' &&\n      p.status === 'complete' &&\n      p.raw !== ''\n    ) {\n      out.push(p.raw)\n    }\n  }\n  return out.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)\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,85 @@
+import { Context as AGUIContext } from '@ag-ui/core';
+import { JSONSchema, ModelMessage, SchemaInput, 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;
+    /**
+     * @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
+ * 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<TContext = unknown>(serverTools: ReadonlyArray<Tool<SchemaInput, SchemaInput, string, TContext>>, clientTools: ReadonlyArray<{
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+}>): Array<Tool<SchemaInput, SchemaInput, string, TContext>>;

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

@@ -0,0 +1,100 @@
+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 aguiContext = parsed.context;
+  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: aguiContext,
+    aguiContext
+  });
+}
+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 {\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/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Best-effort extraction of a human-readable message from an unknown thrown
+ * value, returning `undefined` when none can be found.
+ *
+ * Used by `otelMiddleware` so error reporting stays identical across chat and
+ * media spans.
+ */
+export declare function errorMessage(err: unknown): string | undefined;
+/**
+ * Best-effort extraction of an error's type name (used for the `error.type`
+ * metric attribute), falling back to `'Error'` when no name is available.
+ */
+export declare function errorTypeName(err: unknown): string;

package/dist/esm/utilities/errors.js

@@ -0,0 +1,22 @@
+function errorMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object" && "message" in err) {
+    const m = err.message;
+    if (typeof m === "string") return m;
+  }
+  return void 0;
+}
+function errorTypeName(err) {
+  if (err instanceof Error) return err.name || "Error";
+  if (err && typeof err === "object" && "name" in err) {
+    const n = err.name;
+    if (typeof n === "string") return n;
+  }
+  return "Error";
+}
+export {
+  errorMessage,
+  errorTypeName
+};
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sources":["../../../src/utilities/errors.ts"],"sourcesContent":["/**\n * Best-effort extraction of a human-readable message from an unknown thrown\n * value, returning `undefined` when none can be found.\n *\n * Used by `otelMiddleware` so error reporting stays identical across chat and\n * media spans.\n */\nexport function errorMessage(err: unknown): string | undefined {\n  if (err instanceof Error) return err.message\n  if (typeof err === 'string') return err\n  if (err && typeof err === 'object' && 'message' in err) {\n    const m = (err as { message?: unknown }).message\n    if (typeof m === 'string') return m\n  }\n  return undefined\n}\n\n/**\n * Best-effort extraction of an error's type name (used for the `error.type`\n * metric attribute), falling back to `'Error'` when no name is available.\n */\nexport function errorTypeName(err: unknown): string {\n  if (err instanceof Error) return err.name || 'Error'\n  if (err && typeof err === 'object' && 'name' in err) {\n    const n = (err as { name?: unknown }).name\n    if (typeof n === 'string') return n\n  }\n  return 'Error'\n}\n"],"names":[],"mappings":"AAOO,SAAS,aAAa,KAAkC;AAC7D,MAAI,eAAe,MAAO,QAAO,IAAI;AACrC,MAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,MAAI,OAAO,OAAO,QAAQ,YAAY,aAAa,KAAK;AACtD,UAAM,IAAK,IAA8B;AACzC,QAAI,OAAO,MAAM,SAAU,QAAO;AAAA,EACpC;AACA,SAAO;AACT;AAMO,SAAS,cAAc,KAAsB;AAClD,MAAI,eAAe,MAAO,QAAO,IAAI,QAAQ;AAC7C,MAAI,OAAO,OAAO,QAAQ,YAAY,UAAU,KAAK;AACnD,UAAM,IAAK,IAA2B;AACtC,QAAI,OAAO,MAAM,SAAU,QAAO;AAAA,EACpC;AACA,SAAO;AACT;"}

package/dist/esm/utilities/media-prompt.d.ts

@@ -0,0 +1,35 @@
+import { AudioPart, ImagePart, MediaInputMetadata, MediaPrompt, MediaPromptPart, VideoPart } from '../types.js';
+/**
+ * A {@link MediaPrompt} decomposed into the views adapters consume.
+ *
+ * Adapters with native multimodal prompts (Gemini `contents`, OpenRouter
+ * chat content parts) consume `parts` to preserve interleaving; named-field
+ * providers (fal, OpenAI) consume `text` plus the typed media buckets.
+ *
+ * Prompt text is **never rewritten**: text parts are concatenated verbatim.
+ * Providers that support referencing inputs from the prompt (e.g. fal's
+ * `@Image1`, OpenAI's "image 1" prose) expect the user to write that syntax
+ * themselves — the SDK does not inject or substitute markers.
+ */
+export interface ResolvedMediaPrompt {
+    /**
+     * Text parts concatenated verbatim (paragraph-separated). Empty string
+     * for media-only prompts.
+     */
+    text: string;
+    /** The prompt as ordered parts; a string prompt becomes one text part. */
+    parts: Array<MediaPromptPart>;
+    /** Image parts in prompt order. */
+    images: Array<ImagePart<MediaInputMetadata>>;
+    /** Video parts in prompt order. */
+    videos: Array<VideoPart<MediaInputMetadata>>;
+    /** Audio parts in prompt order. */
+    audios: Array<AudioPart<MediaInputMetadata>>;
+}
+/**
+ * Decompose a {@link MediaPrompt} into flattened text and per-modality part
+ * buckets, preserving prompt order everywhere. This is the single downrev
+ * point from the canonical interleaved prompt shape to the named-field
+ * request shapes most providers expose.
+ */
+export declare function resolveMediaPrompt(prompt: MediaPrompt): ResolvedMediaPrompt;

package/dist/esm/utilities/media-prompt.js

@@ -0,0 +1,43 @@
+function resolveMediaPrompt(prompt) {
+  if (typeof prompt === "string") {
+    const textPart = { type: "text", content: prompt };
+    return {
+      text: prompt,
+      parts: [textPart],
+      images: [],
+      videos: [],
+      audios: []
+    };
+  }
+  const images = [];
+  const videos = [];
+  const audios = [];
+  const textSegments = [];
+  for (const part of prompt) {
+    switch (part.type) {
+      case "text":
+        if (part.content) textSegments.push(part.content);
+        break;
+      case "image":
+        images.push(part);
+        break;
+      case "video":
+        videos.push(part);
+        break;
+      case "audio":
+        audios.push(part);
+        break;
+    }
+  }
+  return {
+    text: textSegments.join("\n\n"),
+    parts: prompt,
+    images,
+    videos,
+    audios
+  };
+}
+export {
+  resolveMediaPrompt
+};
+//# sourceMappingURL=media-prompt.js.map

package/dist/esm/utilities/media-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-prompt.js","sources":["../../../src/utilities/media-prompt.ts"],"sourcesContent":["import type {\n  AudioPart,\n  ImagePart,\n  MediaInputMetadata,\n  MediaPrompt,\n  MediaPromptPart,\n  TextPart,\n  VideoPart,\n} from '../types'\n\n/**\n * A {@link MediaPrompt} decomposed into the views adapters consume.\n *\n * Adapters with native multimodal prompts (Gemini `contents`, OpenRouter\n * chat content parts) consume `parts` to preserve interleaving; named-field\n * providers (fal, OpenAI) consume `text` plus the typed media buckets.\n *\n * Prompt text is **never rewritten**: text parts are concatenated verbatim.\n * Providers that support referencing inputs from the prompt (e.g. fal's\n * `@Image1`, OpenAI's \"image 1\" prose) expect the user to write that syntax\n * themselves — the SDK does not inject or substitute markers.\n */\nexport interface ResolvedMediaPrompt {\n  /**\n   * Text parts concatenated verbatim (paragraph-separated). Empty string\n   * for media-only prompts.\n   */\n  text: string\n  /** The prompt as ordered parts; a string prompt becomes one text part. */\n  parts: Array<MediaPromptPart>\n  /** Image parts in prompt order. */\n  images: Array<ImagePart<MediaInputMetadata>>\n  /** Video parts in prompt order. */\n  videos: Array<VideoPart<MediaInputMetadata>>\n  /** Audio parts in prompt order. */\n  audios: Array<AudioPart<MediaInputMetadata>>\n}\n\n/**\n * Decompose a {@link MediaPrompt} into flattened text and per-modality part\n * buckets, preserving prompt order everywhere. This is the single downrev\n * point from the canonical interleaved prompt shape to the named-field\n * request shapes most providers expose.\n */\nexport function resolveMediaPrompt(prompt: MediaPrompt): ResolvedMediaPrompt {\n  if (typeof prompt === 'string') {\n    const textPart: TextPart = { type: 'text', content: prompt }\n    return {\n      text: prompt,\n      parts: [textPart],\n      images: [],\n      videos: [],\n      audios: [],\n    }\n  }\n\n  const images: Array<ImagePart<MediaInputMetadata>> = []\n  const videos: Array<VideoPart<MediaInputMetadata>> = []\n  const audios: Array<AudioPart<MediaInputMetadata>> = []\n  const textSegments: Array<string> = []\n\n  for (const part of prompt) {\n    switch (part.type) {\n      case 'text':\n        if (part.content) textSegments.push(part.content)\n        break\n      case 'image':\n        images.push(part)\n        break\n      case 'video':\n        videos.push(part)\n        break\n      case 'audio':\n        audios.push(part)\n        break\n    }\n  }\n\n  return {\n    text: textSegments.join('\\n\\n'),\n    parts: prompt,\n    images,\n    videos,\n    audios,\n  }\n}\n"],"names":[],"mappings":"AA4CO,SAAS,mBAAmB,QAA0C;AAC3E,MAAI,OAAO,WAAW,UAAU;AAC9B,UAAM,WAAqB,EAAE,MAAM,QAAQ,SAAS,OAAA;AACpD,WAAO;AAAA,MACL,MAAM;AAAA,MACN,OAAO,CAAC,QAAQ;AAAA,MAChB,QAAQ,CAAA;AAAA,MACR,QAAQ,CAAA;AAAA,MACR,QAAQ,CAAA;AAAA,IAAC;AAAA,EAEb;AAEA,QAAM,SAA+C,CAAA;AACrD,QAAM,SAA+C,CAAA;AACrD,QAAM,SAA+C,CAAA;AACrD,QAAM,eAA8B,CAAA;AAEpC,aAAW,QAAQ,QAAQ;AACzB,YAAQ,KAAK,MAAA;AAAA,MACX,KAAK;AACH,YAAI,KAAK,QAAS,cAAa,KAAK,KAAK,OAAO;AAChD;AAAA,MACF,KAAK;AACH,eAAO,KAAK,IAAI;AAChB;AAAA,MACF,KAAK;AACH,eAAO,KAAK,IAAI;AAChB;AAAA,MACF,KAAK;AACH,eAAO,KAAK,IAAI;AAChB;AAAA,IAAA;AAAA,EAEN;AAEA,SAAO;AAAA,IACL,MAAM,aAAa,KAAK,MAAM;AAAA,IAC9B,OAAO;AAAA,IACP;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAEJ;"}

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

@@ -0,0 +1,8 @@
+/**
+ * Return the first candidate that is a finite `number`, or `undefined`.
+ *
+ * Handy for picking a value from among several possible spellings/sources where
+ * only some are populated — e.g. the provider-native sampling option names read
+ * by the OTel middleware, or the optional numeric fields on `TokenUsage`.
+ */
+export declare function firstNumber(...candidates: Array<unknown>): number | undefined;

package/dist/esm/utilities/numbers.js

@@ -0,0 +1,12 @@
+function firstNumber(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+export {
+  firstNumber
+};
+//# sourceMappingURL=numbers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.js","sources":["../../../src/utilities/numbers.ts"],"sourcesContent":["/**\n * Return the first candidate that is a finite `number`, or `undefined`.\n *\n * Handy for picking a value from among several possible spellings/sources where\n * only some are populated — e.g. the provider-native sampling option names read\n * by the OTel middleware, or the optional numeric fields on `TokenUsage`.\n */\nexport function firstNumber(...candidates: Array<unknown>): number | undefined {\n  for (const candidate of candidates) {\n    if (typeof candidate === 'number' && Number.isFinite(candidate)) {\n      return candidate\n    }\n  }\n  return undefined\n}\n"],"names":[],"mappings":"AAOO,SAAS,eAAe,YAAgD;AAC7E,aAAW,aAAa,YAAY;AAClC,QAAI,OAAO,cAAc,YAAY,OAAO,SAAS,SAAS,GAAG;AAC/D,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;"}

package/dist/esm/utilities/sampling-keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Single source of truth for the provider-native key spellings that cap output
+ * tokens. Sampling options live in opaque, provider-native `modelOptions`, and
+ * every provider spells the token cap differently. Two call sites must agree on
+ * this set or they silently drift:
+ *
+ * - `activities/summarize/chat-stream-summarize.ts` — detects a caller-supplied
+ *   token limit so the summarize default never overrides it.
+ * - `middlewares/otel.ts` — picks the first numeric spelling to populate the
+ *   `gen_ai.request.max_tokens` attribute across providers.
+ *
+ * Keep this list in lockstep with `MAX_TOKENS_KEY_BY_ADAPTER` (the adapter →
+ * native-key map) in the summarize wrapper.
+ */
+export declare const MAX_TOKENS_KEYS: readonly ["max_output_tokens", "max_tokens", "max_completion_tokens", "maxOutputTokens", "maxCompletionTokens", "maxTokens"];
+/**
+ * Ollama nests sampling under `options`; its token cap is `options.num_predict`
+ * rather than a flat key.
+ */
+export declare const NESTED_MAX_TOKENS_KEY: "num_predict";

package/dist/esm/utilities/sampling-keys.js

@@ -0,0 +1,20 @@
+const MAX_TOKENS_KEYS = [
+  "max_output_tokens",
+  // OpenAI (Responses)
+  "max_tokens",
+  // Anthropic / Grok
+  "max_completion_tokens",
+  // Groq
+  "maxOutputTokens",
+  // Gemini
+  "maxCompletionTokens",
+  // OpenRouter
+  "maxTokens"
+  // generic / migration leftover (no adapter reads it)
+];
+const NESTED_MAX_TOKENS_KEY = "num_predict";
+export {
+  MAX_TOKENS_KEYS,
+  NESTED_MAX_TOKENS_KEY
+};
+//# sourceMappingURL=sampling-keys.js.map

package/dist/esm/utilities/sampling-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling-keys.js","sources":["../../../src/utilities/sampling-keys.ts"],"sourcesContent":["/**\n * Single source of truth for the provider-native key spellings that cap output\n * tokens. Sampling options live in opaque, provider-native `modelOptions`, and\n * every provider spells the token cap differently. Two call sites must agree on\n * this set or they silently drift:\n *\n * - `activities/summarize/chat-stream-summarize.ts` — detects a caller-supplied\n *   token limit so the summarize default never overrides it.\n * - `middlewares/otel.ts` — picks the first numeric spelling to populate the\n *   `gen_ai.request.max_tokens` attribute across providers.\n *\n * Keep this list in lockstep with `MAX_TOKENS_KEY_BY_ADAPTER` (the adapter →\n * native-key map) in the summarize wrapper.\n */\nexport const MAX_TOKENS_KEYS = [\n  'max_output_tokens', // OpenAI (Responses)\n  'max_tokens', // Anthropic / Grok\n  'max_completion_tokens', // Groq\n  'maxOutputTokens', // Gemini\n  'maxCompletionTokens', // OpenRouter\n  'maxTokens', // generic / migration leftover (no adapter reads it)\n] as const\n\n/**\n * Ollama nests sampling under `options`; its token cap is `options.num_predict`\n * rather than a flat key.\n */\nexport const NESTED_MAX_TOKENS_KEY = 'num_predict' as const\n"],"names":[],"mappings":"AAcO,MAAM,kBAAkB;AAAA,EAC7B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAMO,MAAM,wBAAwB;"}

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