@tanstack/ai 0.58.0 → 0.61.0

package/dist/esm/utilities/subagent-wire.d.ts

@@ -0,0 +1,36 @@
+import { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core';
+import { SubagentHandleData } from '../types.js';
+/**
+ * Card data that travels on each child wire message, in
+ * `metadata.tanstack.subagent`. The messages carry the AG-UI `subagentRunId`.
+ */
+export interface SubagentWireInfo extends AGUISubagentInfo, Pick<SubagentHandleData, 'status' | 'error' | 'interruptIds' | 'parentSubagentRunId' | 'parentToolCallId' | 'metadata'> {
+    /** The child has no messages yet. This wire message only holds the card. */
+    placeholder?: true;
+}
+export interface SubagentWireGroup<T> {
+    id: string;
+    info: SubagentWireInfo;
+    /** The child's messages without its own tag. Nested children keep theirs. */
+    messages: Array<T>;
+    /** Index in `top` of the last message before this child, or -1. */
+    hostIndex: number;
+}
+export declare function wireSubagentRunId(message: unknown): string | undefined;
+export declare function wireSubagentInfo(message: unknown): SubagentWireInfo | undefined;
+/**
+ * Split wire messages into the parent's own messages and one group per direct
+ * child. A nested child's messages stay inside its parent's group.
+ */
+export declare function splitSubagentWire<T>(messages: ReadonlyArray<T>): {
+    top: Array<T>;
+    groups: Array<SubagentWireGroup<T>>;
+};
+/** Text a child wrote, for the parent model and for a later child. */
+export declare function subagentWireText(messages: ReadonlyArray<unknown>): string;
+/**
+ * The id of the parent assistant message that hosts a routed turn's cards.
+ * The persistence recorder writes that message, and a handoff run passes the
+ * same id so the stored thread keeps one copy.
+ */
+export declare function subagentHostMessageId(runId: string): string;

package/dist/esm/utilities/subagent-wire.js

@@ -0,0 +1,131 @@
+//#region src/utilities/subagent-wire.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function wireSubagentRunId(message) {
+	if (!isRecord(message) || "parts" in message) return void 0;
+	const id = message.subagentRunId;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function wireSubagentInfo(message) {
+	if (!isRecord(message) || !isRecord(message.metadata)) return void 0;
+	const tanstack = message.metadata.tanstack;
+	if (!isRecord(tanstack) || !isRecord(tanstack.subagent)) return void 0;
+	const { name, status, error, interruptIds } = tanstack.subagent;
+	if (typeof name !== "string" || !isStatus(status)) return void 0;
+	const { description, parentSubagentRunId, parentToolCallId, metadata, placeholder } = tanstack.subagent;
+	return {
+		name,
+		status,
+		...typeof description === "string" && { description },
+		...isRecord(error) && typeof error.message === "string" && { error: {
+			message: error.message,
+			...typeof error.code === "string" && { code: error.code }
+		} },
+		...Array.isArray(interruptIds) && { interruptIds: interruptIds.filter((id) => typeof id === "string") },
+		...typeof parentSubagentRunId === "string" && { parentSubagentRunId },
+		...typeof parentToolCallId === "string" && { parentToolCallId },
+		...isRecord(metadata) && { metadata },
+		...placeholder === true && { placeholder: true }
+	};
+}
+function isStatus(value) {
+	return value === "running" || value === "finished" || value === "error" || value === "suspended";
+}
+function untag(message) {
+	if (!isRecord(message)) return message;
+	const { subagentRunId: _id, ...rest } = message;
+	const metadata = isRecord(rest.metadata) ? rest.metadata : void 0;
+	const tanstack = isRecord(metadata?.tanstack) ? metadata.tanstack : void 0;
+	if (!metadata || !tanstack || !("subagent" in tanstack)) return rest;
+	const { subagent: _info, ...tanstackRest } = tanstack;
+	return {
+		...rest,
+		metadata: {
+			...metadata,
+			tanstack: tanstackRest
+		}
+	};
+}
+/**
+* Split wire messages into the parent's own messages and one group per direct
+* child. A nested child's messages stay inside its parent's group.
+*/
+function splitSubagentWire(messages) {
+	const parentOf = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		const id = wireSubagentRunId(message);
+		if (id !== void 0 && !parentOf.has(id)) parentOf.set(id, wireSubagentInfo(message)?.parentSubagentRunId);
+	}
+	const rootOf = (id) => {
+		let current = id;
+		for (let depth = 0; depth < 64; depth++) {
+			const parent = parentOf.get(current);
+			if (parent === void 0 || !parentOf.has(parent)) return current;
+			current = parent;
+		}
+		return current;
+	};
+	const top = [];
+	const groups = /* @__PURE__ */ new Map();
+	for (const message of messages) {
+		const id = wireSubagentRunId(message);
+		if (id === void 0) {
+			top.push(message);
+			continue;
+		}
+		const root = rootOf(id);
+		let group = groups.get(root);
+		if (!group) {
+			group = {
+				id: root,
+				info: {
+					name: "subagent",
+					status: "finished"
+				},
+				messages: [],
+				hostIndex: top.length - 1
+			};
+			groups.set(root, group);
+		}
+		if (id !== root) {
+			group.messages.push(message);
+			continue;
+		}
+		const info = wireSubagentInfo(message);
+		if (info) group.info = info;
+		if (!info?.placeholder) group.messages.push(untag(message));
+	}
+	return {
+		top,
+		groups: [...groups.values()]
+	};
+}
+/** Text a child wrote, for the parent model and for a later child. */
+function subagentWireText(messages) {
+	const blocks = [];
+	for (const message of messages) {
+		if (!isRecord(message) || message.role !== "assistant") continue;
+		if (wireSubagentRunId(message) !== void 0) continue;
+		const content = message.content;
+		if (typeof content === "string" && content.trim() !== "") blocks.push(content.trim());
+	}
+	const nested = splitSubagentWire(messages).groups;
+	for (const group of nested) {
+		const text = subagentWireText(group.messages);
+		if (text !== "") blocks.push(`${group.info.name}:\n${text}`);
+	}
+	return blocks.join("\n\n");
+}
+/**
+* The id of the parent assistant message that hosts a routed turn's cards.
+* The persistence recorder writes that message, and a handoff run passes the
+* same id so the stored thread keeps one copy.
+*/
+function subagentHostMessageId(runId) {
+	return `assistant:${runId}`;
+}
+//#endregion
+export { splitSubagentWire, subagentHostMessageId, subagentWireText, wireSubagentInfo, wireSubagentRunId };
+
+//# sourceMappingURL=subagent-wire.js.map

package/dist/esm/utilities/subagent-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wire.js","names":[],"sources":["../../../src/utilities/subagent-wire.ts"],"sourcesContent":["import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'\nimport type { SubagentHandleData } from '../types'\n\n/**\n * Card data that travels on each child wire message, in\n * `metadata.tanstack.subagent`. The messages carry the AG-UI `subagentRunId`.\n */\nexport interface SubagentWireInfo\n  extends\n    AGUISubagentInfo,\n    Pick<\n      SubagentHandleData,\n      | 'status'\n      | 'error'\n      | 'interruptIds'\n      | 'parentSubagentRunId'\n      | 'parentToolCallId'\n      | 'metadata'\n    > {\n  /** The child has no messages yet. This wire message only holds the card. */\n  placeholder?: true\n}\n\nexport interface SubagentWireGroup<T> {\n  id: string\n  info: SubagentWireInfo\n  /** The child's messages without its own tag. Nested children keep theirs. */\n  messages: Array<T>\n  /** Index in `top` of the last message before this child, or -1. */\n  hostIndex: number\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nexport function wireSubagentRunId(message: unknown): string | undefined {\n  if (!isRecord(message) || 'parts' in message) return undefined\n  const id = message.subagentRunId\n  return typeof id === 'string' && id !== '' ? id : undefined\n}\n\nexport function wireSubagentInfo(\n  message: unknown,\n): SubagentWireInfo | undefined {\n  if (!isRecord(message) || !isRecord(message.metadata)) return undefined\n  const tanstack = message.metadata.tanstack\n  if (!isRecord(tanstack) || !isRecord(tanstack.subagent)) return undefined\n  // Wire data comes from the client. Keep only well-formed fields.\n  const { name, status, error, interruptIds } = tanstack.subagent\n  if (typeof name !== 'string' || !isStatus(status)) return undefined\n  const {\n    description,\n    parentSubagentRunId,\n    parentToolCallId,\n    metadata,\n    placeholder,\n  } = tanstack.subagent\n  return {\n    name,\n    status,\n    ...(typeof description === 'string' && { description }),\n    ...(isRecord(error) &&\n      typeof error.message === 'string' && {\n        error: {\n          message: error.message,\n          ...(typeof error.code === 'string' && { code: error.code }),\n        },\n      }),\n    ...(Array.isArray(interruptIds) && {\n      interruptIds: interruptIds.filter(\n        (id): id is string => typeof id === 'string',\n      ),\n    }),\n    ...(typeof parentSubagentRunId === 'string' && { parentSubagentRunId }),\n    ...(typeof parentToolCallId === 'string' && { parentToolCallId }),\n    ...(isRecord(metadata) && { metadata }),\n    ...(placeholder === true && { placeholder: true as const }),\n  }\n}\n\nfunction isStatus(value: unknown): value is SubagentWireInfo['status'] {\n  return (\n    value === 'running' ||\n    value === 'finished' ||\n    value === 'error' ||\n    value === 'suspended'\n  )\n}\n\nfunction untag<T>(message: T): T {\n  if (!isRecord(message)) return message\n  const { subagentRunId: _id, ...rest } = message\n  void _id\n  const metadata = isRecord(rest.metadata) ? rest.metadata : undefined\n  const tanstack = isRecord(metadata?.tanstack) ? metadata.tanstack : undefined\n  if (!metadata || !tanstack || !('subagent' in tanstack)) return rest as T\n  const { subagent: _info, ...tanstackRest } = tanstack\n  void _info\n  return { ...rest, metadata: { ...metadata, tanstack: tanstackRest } } as T\n}\n\n/**\n * Split wire messages into the parent's own messages and one group per direct\n * child. A nested child's messages stay inside its parent's group.\n */\nexport function splitSubagentWire<T>(messages: ReadonlyArray<T>): {\n  top: Array<T>\n  groups: Array<SubagentWireGroup<T>>\n} {\n  const parentOf = new Map<string, string | undefined>()\n  for (const message of messages) {\n    const id = wireSubagentRunId(message)\n    if (id !== undefined && !parentOf.has(id)) {\n      parentOf.set(id, wireSubagentInfo(message)?.parentSubagentRunId)\n    }\n  }\n  const rootOf = (id: string) => {\n    let current = id\n    for (let depth = 0; depth < 64; depth++) {\n      const parent = parentOf.get(current)\n      if (parent === undefined || !parentOf.has(parent)) return current\n      current = parent\n    }\n    return current\n  }\n\n  const top: Array<T> = []\n  const groups = new Map<string, SubagentWireGroup<T>>()\n  for (const message of messages) {\n    const id = wireSubagentRunId(message)\n    if (id === undefined) {\n      top.push(message)\n      continue\n    }\n    const root = rootOf(id)\n    let group = groups.get(root)\n    if (!group) {\n      group = {\n        id: root,\n        info: { name: 'subagent', status: 'finished' },\n        messages: [],\n        hostIndex: top.length - 1,\n      }\n      groups.set(root, group)\n    }\n    if (id !== root) {\n      group.messages.push(message)\n      continue\n    }\n    const info = wireSubagentInfo(message)\n    if (info) group.info = info\n    if (!info?.placeholder) group.messages.push(untag(message))\n  }\n  return { top, groups: [...groups.values()] }\n}\n\n/** Text a child wrote, for the parent model and for a later child. */\nexport function subagentWireText(messages: ReadonlyArray<unknown>): string {\n  const blocks: Array<string> = []\n  for (const message of messages) {\n    if (!isRecord(message) || message.role !== 'assistant') continue\n    if (wireSubagentRunId(message) !== undefined) continue\n    const content = message.content\n    if (typeof content === 'string' && content.trim() !== '') {\n      blocks.push(content.trim())\n    }\n  }\n  const nested = splitSubagentWire(messages).groups\n  for (const group of nested) {\n    const text = subagentWireText(group.messages)\n    if (text !== '') blocks.push(`${group.info.name}:\\n${text}`)\n  }\n  return blocks.join('\\n\\n')\n}\n\n/**\n * The id of the parent assistant message that hosts a routed turn's cards.\n * The persistence recorder writes that message, and a handoff run passes the\n * same id so the stored thread keeps one copy.\n */\nexport function subagentHostMessageId(runId: string) {\n  return `assistant:${runId}`\n}\n"],"mappings":"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"}

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

@@ -1,8 +1,9 @@
 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`.
+ * `content`. Every other part carries a source with a string `value`; a file
+ * source's `value` is a non-empty opaque handle, and its optional `provider`
+ * is a string.
  */
 export declare function isContentPart(value: unknown): value is ContentPart;
 /**
@@ -12,6 +13,15 @@ export declare function isContentPart(value: unknown): value is ContentPart;
  * footgun narrow.
  */
 export declare function isContentPartArray(value: unknown): value is Array<ContentPart>;
+/**
+ * Error text for a failed tool result: `output.error` when it is a string,
+ * else the output itself when it is a string, else a generic message.
+ * `StreamProcessor` and `chat()` history share it, so a reload shows the
+ * same text as the live stream.
+ */
+export declare function toolResultErrorText(output: unknown): string;
+/** Parse tool result content as JSON. Plain text stays a string. */
+export declare function parseToolOutput(content: string): unknown;
 /**
  * Normalize a tool's return value for transport:
  * - string            → unchanged

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

@@ -8,8 +8,9 @@ var CONTENT_PART_TYPES = /* @__PURE__ */ new Set([
 ]);
 /**
 * 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`.
+* `content`. Every other part carries a source with a string `value`; a file
+* source's `value` is a non-empty opaque handle, and its optional `provider`
+* is a string.
 */
 function isContentPart(value) {
 	if (typeof value !== "object" || value === null) return false;
@@ -20,6 +21,7 @@ function isContentPart(value) {
 	if (typeof source !== "object" || source === null) return false;
 	const src = source;
 	if (typeof src.value !== "string") return false;
+	if (src.type === "file") return src.value.length > 0 && (src.provider === void 0 || typeof src.provider === "string");
 	if (src.type === "data") return typeof src.mimeType === "string";
 	return src.type === "url";
 }
@@ -33,6 +35,24 @@ function isContentPartArray(value) {
 	return Array.isArray(value) && value.length > 0 && value.every(isContentPart);
 }
 /**
+* Error text for a failed tool result: `output.error` when it is a string,
+* else the output itself when it is a string, else a generic message.
+* `StreamProcessor` and `chat()` history share it, so a reload shows the
+* same text as the live stream.
+*/
+function toolResultErrorText(output) {
+	if (output && typeof output === "object" && "error" in output && typeof output.error === "string") return output.error;
+	return typeof output === "string" ? output : "Tool execution failed";
+}
+/** Parse tool result content as JSON. Plain text stays a string. */
+function parseToolOutput(content) {
+	try {
+		return JSON.parse(content);
+	} catch {
+		return content;
+	}
+}
+/**
 * Normalize a tool's return value for transport:
 * - string            → unchanged
 * - ContentPart array → unchanged (multimodal, passed through to the adapter)
@@ -44,6 +64,6 @@ function normalizeToolResult(result) {
 	return JSON.stringify(result);
 }
 //#endregion
-export { isContentPart, isContentPartArray, normalizeToolResult };
+export { isContentPart, isContentPartArray, normalizeToolResult, parseToolOutput, toolResultErrorText };
 
 //# sourceMappingURL=tool-result.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-result.js","names":[],"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"],"mappings":";AAEA,IAAM,qCAAqB,IAAI,IAAI;CACjC;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;AAOD,SAAgB,cAAc,OAAsC;CAClE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,OAAO;CACb,IAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GACpE,OAAO;CAET,IAAI,KAAK,SAAS,QAChB,OAAO,OAAO,KAAK,YAAY;CAEjC,MAAM,SAAS,KAAK;CACpB,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO;CAC1D,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,UAAU,UAAU,OAAO;CAI1C,IAAI,IAAI,SAAS,QAAQ,OAAO,OAAO,IAAI,aAAa;CACxD,OAAO,IAAI,SAAS;AACtB;;;;;;;AAQA,SAAgB,mBACd,OAC6B;CAC7B,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;;;;;;;AAQA,SAAgB,oBACd,QAC6B;CAC7B,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI,mBAAmB,MAAM,GAAG,OAAO;CACvC,OAAO,KAAK,UAAU,MAAM;AAC9B"}
+{"version":3,"file":"tool-result.js","names":[],"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 part carries a source with a string `value`; a file\n * source's `value` is a non-empty opaque handle, and its optional `provider`\n * is a string.\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  // `file` sources carry an opaque handle in `value`; `provider`, when set,\n  // names the issuer.\n  if (src.type === 'file') {\n    return (\n      src.value.length > 0 &&\n      (src.provider === undefined || typeof src.provider === 'string')\n    )\n  }\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 * Error text for a failed tool result: `output.error` when it is a string,\n * else the output itself when it is a string, else a generic message.\n * `StreamProcessor` and `chat()` history share it, so a reload shows the\n * same text as the live stream.\n */\nexport function toolResultErrorText(output: unknown): string {\n  if (\n    output &&\n    typeof output === 'object' &&\n    'error' in output &&\n    typeof output.error === 'string'\n  ) {\n    return output.error\n  }\n  return typeof output === 'string' ? output : 'Tool execution failed'\n}\n\n/** Parse tool result content as JSON. Plain text stays a string. */\nexport function parseToolOutput(content: string): unknown {\n  try {\n    return JSON.parse(content)\n  } catch {\n    return content\n  }\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"],"mappings":";AAEA,IAAM,qCAAqB,IAAI,IAAI;CACjC;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;AAQD,SAAgB,cAAc,OAAsC;CAClE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,OAAO;CACb,IAAI,OAAO,KAAK,SAAS,YAAY,CAAC,mBAAmB,IAAI,KAAK,IAAI,GACpE,OAAO;CAET,IAAI,KAAK,SAAS,QAChB,OAAO,OAAO,KAAK,YAAY;CAEjC,MAAM,SAAS,KAAK;CACpB,IAAI,OAAO,WAAW,YAAY,WAAW,MAAM,OAAO;CAC1D,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,UAAU,UAAU,OAAO;CAG1C,IAAI,IAAI,SAAS,QACf,OACE,IAAI,MAAM,SAAS,MAClB,IAAI,aAAa,KAAA,KAAa,OAAO,IAAI,aAAa;CAM3D,IAAI,IAAI,SAAS,QAAQ,OAAO,OAAO,IAAI,aAAa;CACxD,OAAO,IAAI,SAAS;AACtB;;;;;;;AAQA,SAAgB,mBACd,OAC6B;CAC7B,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,KAAK,MAAM,MAAM,aAAa;AAC9E;;;;;;;AAQA,SAAgB,oBAAoB,QAAyB;CAC3D,IACE,UACA,OAAO,WAAW,YAClB,WAAW,UACX,OAAO,OAAO,UAAU,UAExB,OAAO,OAAO;CAEhB,OAAO,OAAO,WAAW,WAAW,SAAS;AAC/C;;AAGA,SAAgB,gBAAgB,SAA0B;CACxD,IAAI;EACF,OAAO,KAAK,MAAM,OAAO;CAC3B,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,oBACd,QAC6B;CAC7B,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,IAAI,mBAAmB,MAAM,GAAG,OAAO;CACvC,OAAO,KAAK,UAAU,MAAM;AAC9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.58.0",
+  "version": "0.61.0",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -85,10 +85,10 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "0.1.1-canary.beta.0",
+    "@ag-ui/core": "1.0.0",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "^0.12.1",
+    "@tanstack/ai-event-client": "^0.13.0",
     "@tanstack/ai-utils": "^0.4.1"
   },
   "peerDependencies": {

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -456,6 +456,68 @@ compatible providers speak.
 > Verify the provider's current `baseURL` and model ids against its live docs —
 > they drift. See `docs/adapters/openai-compatible.md` for the full provider table.
 
+### 7. Files Adapters (upload once, reference by handle)
+
+Four providers expose a native Files/storage API as a tree-shakeable `files`
+adapter: `openaiFiles()`, `anthropicFiles()`, `geminiFiles()` (each reads the
+same env var as the provider's text adapter; `create*Files(apiKey)` variants
+take an explicit key), and `falFiles(config)`. Upload media once with
+`uploadFile()`, then reference the returned `FileHandle` in messages via a
+`{ type: 'file' }` content source instead of re-sending base64 each request:
+
+```typescript
+import { chat, fileSourceFromHandle, uploadFile } from '@tanstack/ai'
+import { openaiFiles, openaiText } from '@tanstack/ai-openai'
+import { pdfBase64 } from './pdf-data'
+
+const handle = await uploadFile({
+  adapter: openaiFiles(),
+  input: { data: pdfBase64, mimeType: 'application/pdf' },
+})
+
+chat({
+  adapter: openaiText('gpt-5.5'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', content: 'Summarize this document' },
+        { type: 'document', source: fileSourceFromHandle(handle) },
+      ],
+    },
+  ],
+})
+```
+
+Rules agents must respect:
+
+- **The source is one opaque handle plus its issuer.** `fileSourceFromHandle`
+  builds `{ type: 'file', value: 'file-…', provider: 'openai' }`, matching the
+  AG-UI `FileSource` arm. A handle only resolves at the provider that issued
+  it, so an adapter throws when `provider` names a different adapter.
+  `provider` is optional, as on the AG-UI wire; a source without it is taken
+  as-is. To use the same bytes with two providers,
+  upload to each and send the matching handle.
+- **Adapters declare `supportsFileSources`.** For adapters that don't (Groq, Bedrock, Mistral, OpenRouter, Ollama, BytePlus, Cohere, and anything
+  written before this feature), `chat()` / `generateImage()` /
+  `generateVideo()` / `embed()` reject file sources in preflight, before any
+  request is built — pass `data`/`url` sources there instead.
+- **Lifecycle:** `getFile()` / `deleteFile()` work for OpenAI, Anthropic,
+  Gemini, and Grok, and accept the handle itself (provider-literal typed, so a
+  foreign handle is a compile error). fal storage is upload-only, so those
+  calls throw for `falFiles()`. `grokFiles().get()` mints the public URL again,
+  so do not call it after `revokePublicUrl()`.
+- **Some endpoints need raw bytes even on supporting providers:** OpenAI
+  `images/edits` + Sora `input_reference`, Gemini Veo, and Chat Completions
+  image inputs throw endpoint-specific errors for file sources.
+- **A file source crosses the chat wire.** A browser that holds a handle puts
+  `fileSourceFromHandle(handle)` straight into the `sendMessage` content, and
+  the server passes the messages to `chat()` as usual. `fileSourceFromHandle`
+  and the `FileHandle` type are exported from the browser-safe
+  `@tanstack/ai/client` entry.
+
+See `docs/advanced/files-api.md` for the full guide.
+
 ## Behind a proxy or gateway
 
 Every adapter's client config accepts `baseURL` and `defaultHeaders`. Use these

package/skills/ai-core/adapter-configuration/references/grok-adapter.md

@@ -31,7 +31,7 @@ import { grokImage } from '@tanstack/ai-grok'
 | `grok-build-0.1` | 256K           | Code-specialized; `reasoning` option is not accepted     |
 
 `GROK_CHAT_MODELS` is exactly these four ids. Image models
-(`GROK_IMAGE_MODELS`): `grok-2-image-1212`, `grok-imagine-image`,
+(`GROK_IMAGE_MODELS`): `grok-imagine-image`,
 `grok-imagine-image-2.0`, `grok-imagine-image-quality`.
 
 ## Provider-Specific modelOptions

package/skills/ai-core/chat-experience/SKILL.md

@@ -299,6 +299,8 @@ import type { UIMessage } from '@tanstack/ai-react'
 
 function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
   if (part.type !== 'image') return null
+  // A provider file handle is an opaque id, so the browser cannot load it.
+  if (part.source.type === 'file') return null
   const src =
     part.source.type === 'url'
       ? part.source.value
@@ -307,6 +309,18 @@ function ImagePart({ part }: { part: UIMessage['parts'][number] }) {
 }
 ```
 
+For media reused across turns, upload once via a provider Files adapter
+(`openaiFiles()`, `anthropicFiles()`, `geminiFiles()`, `grokFiles()`,
+`falFiles()`) and send a `{ type: 'file' }` source built with
+`fileSourceFromHandle(handle)` instead of re-sending base64 each request. The
+source is `{ type: 'file', value, provider }`: an opaque handle and the adapter
+that issued it. A different provider (or one without Files API support at all)
+rejects it with a clear error before any request is sent.
+The source crosses the chat wire, so the browser can put it straight into the
+`sendMessage` content. Import `fileSourceFromHandle` from the browser-safe
+`@tanstack/ai/client` entry. See `ai-core/adapter-configuration/SKILL.md` §7
+and `docs/advanced/files-api.md`.
+
 ### 4. Sending Audio Messages (Browser Recording)
 
 Use `useAudioRecorder` from `@tanstack/ai-react` (or `createAudioRecorder` in Svelte) to capture audio in the browser. The resolved `AudioRecording` includes a ready-to-use `part` that slots directly into `sendMessage`.

package/skills/ai-core/media-generation/SKILL.md

@@ -283,6 +283,14 @@ await generateVideo({
 })
 ```
 
+Reference images / start frames that are reused (or arrive as inline base64 on
+memory-constrained runtimes) can instead be uploaded once via the provider's
+Files adapter and referenced with `source: fileSourceFromHandle(handle)` —
+supported for Gemini image generation (`geminiFiles()`) and fal image/video
+inputs (`falFiles()`). Endpoints that require raw bytes (OpenAI `images/edits`,
+Sora `input_reference`, Gemini Veo) reject file sources with a clear error.
+See `ai-core/adapter-configuration/SKILL.md` §7.
+
 **URL inputs that require an upload throw by default.** Most adapters pass a
 `type: 'url'` source straight through to the provider. Three paths can't —
 OpenAI `images.edit()`, OpenAI Sora `input_reference`, and Gemini **Veo** —
@@ -312,7 +320,7 @@ with `allowUrlFetch: true` on the adapter config
 | OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                                                                                                                                                                     |
 | Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | Veo → first un-roled / `'start_frame'` image is the input image; `'end_frame'` → `lastFrame`; `'reference'` / `'character'` → `referenceImages`. Omni Flash sends image/video parts as interaction content blocks (no role routing).                                                                                                          |
 | fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`.                                                                                                                                            |
-| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | Un-roled / `'start_frame'` image → starting frame; `'reference'` / `'character'` → `reference_images` (1.5). On 1.5 a starting frame can be combined with reference inputs (it pins the first frame). A `video` part + `modelOptions.mode: 'edit' \| 'extend'` routes to `/videos/edits` / `/videos/extensions` on `grok-imagine-video` only. |
+| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw).                                                        | Un-roled / `'start_frame'` image → starting frame; `'reference'` / `'character'` → `reference_images` (1.5). On 1.5 a starting frame can be combined with reference inputs (it pins the first frame). A `video` part + `modelOptions.mode: 'edit' \| 'extend'` routes to `/videos/edits` / `/videos/extensions` on `grok-imagine-video` only. |
 | OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | Dedicated async API (`openRouterVideo`): `start_frame`/`end_frame` → `frame_images[]` (`first_frame`/`last_frame`); `reference`/`character` → `input_references[]`; an unroled image defaults to the start frame. Frame roles validated against the model's `supported_frame_images` metadata.                                                |
 | Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                                                                                                                                                           |
 
@@ -1174,7 +1182,7 @@ generateSpeech({
 
 Not every model accepts image-conditioned prompts. The `prompt` type is
 narrowed per model, so passing an image part to a text-only model
-(dall-e-3, Imagen, grok-2-image) is a **compile-time error**; adapters
+(dall-e-3, Imagen) is a **compile-time error**; adapters
 also throw a clear runtime error as a backstop, so users learn at call
 time rather than getting silently wrong output.
 

package/skills/ai-core/middleware/SKILL.md

@@ -55,7 +55,7 @@ export async function POST(request: Request) {
 
 Every hook receives a `ChatMiddlewareContext` as its first argument, which provides
 `requestId`, `streamId`, `phase`, `iteration`, `chunkIndex`, `model`, `provider`,
-`signal`, `abort()`, `defer()`, and more.
+`signal`, `abort()`, `defer()`, and more. `parentRunId` names the run this one continues. `subagentRunId` is set only inside a subagent and names its card.
 
 | Hook                       | When                                                                                                     | Second Argument                                     |
 | -------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
@@ -609,9 +609,12 @@ driver, or nothing fences a dead host's writes.
 a bare string: `message` is the provider's prose, `code` is the stable,
 machine-branchable classification a consumer switches on. Only
 `createOrResume`, `update`, `get`, and `findActiveRun` are required on a
-`RunStore`; `listByThread` and `listReclaimable` are optional, so a backend can
-leave either out and callers feature-detect
-(`store.listReclaimable?.(opts)`). Shape your own store with
+`RunStore`. `listByThread`, `listByParentRun`, and `listReclaimable` are
+optional, so a backend can leave any of them out and callers feature-detect
+(`store.listReclaimable?.(opts)`). A subagent child run also stores
+`parentRunId`, `subagentRunId`, and `name`. `createOrResume` writes them on
+the first insert and leaves them unchanged on resume. `reconstructChat` calls
+`listByParentRun` to put the child cards back. Shape your own store with
 `defineRunStore` for autocomplete without a separate `: RunStore` annotation,
 matching `defineLock`; `defineRunStore<const T extends RunStore>(store: T): T`
 returns the argument's own type, so an optional method your store implements

package/src/activities/chat/adapter.ts

@@ -89,6 +89,15 @@ export interface TextAdapter<
    */
   readonly requires?: ReadonlyArray<CapabilityHandle>
 
+  /**
+   * Declares that this adapter can consume `{ type: 'file' }` content sources
+   * (provider Files API references). `chat()` rejects file sources in preflight
+   * for adapters that don't declare this, so an adapter written before the
+   * file arm existed fails closed instead of silently mis-mapping a reference
+   * onto its URL/data branch.
+   */
+  readonly supportsFileSources?: boolean
+
   /**
    * @internal Type-only properties for inference. Not assigned at runtime.
    */
@@ -209,6 +218,7 @@ export abstract class BaseTextAdapter<
   abstract readonly name: string
   readonly model: TModel
   readonly requires?: ReadonlyArray<CapabilityHandle> = undefined
+  readonly supportsFileSources: boolean = false
 
   // Type-only property - never assigned at runtime
   declare '~types': {

package/src/activities/chat/agents/define-agent.ts

@@ -0,0 +1,121 @@
+import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+import type {
+  AnyTool,
+  ModelMessage,
+  RunAgentResumeItem,
+  SchemaInput,
+  StreamChunk,
+  UIMessage,
+} from '../../../types'
+import type { AnyClientTool } from '../tools/tool-definition'
+
+/**
+ * Context the library passes into {@link defineAgent} `run`.
+ */
+export interface SubagentRunContext {
+  messages: Array<UIMessage | ModelMessage>
+  abortSignal?: AbortSignal
+  threadId: string
+  /** Run id for the child `chat()`. */
+  runId: string
+  /**
+   * The run this child run continues. It is the parent chat run on the first
+   * run, and the interrupted parent run on a resume. Pass it to the child
+   * `chat()`.
+   */
+  parentRunId: string
+  /** Answers to this child's interrupts. Pass it to the child `chat()`. */
+  resume?: Array<RunAgentResumeItem>
+  /**
+   * The child's AG-UI run id. Stays the same when an interrupted child
+   * continues. Pass it to the child `chat()` so its middleware sees
+   * `ctx.subagentRunId`.
+   */
+  subagentRunId: string
+  parentSubagentRunId?: string
+}
+
+/**
+ * A tool a child agent can carry into client part types.
+ * Server tools and client tools both qualify.
+ */
+export type SubagentTool = AnyTool | AnyClientTool
+
+/**
+ * A named child agent. `run` is a `chat()` call (or any stream of AG-UI chunks).
+ * `TTools` and `TSchema` stay on the object so `useChat({ subagents })` can
+ * type that child's parts.
+ */
+export interface DefinedAgent<
+  TName extends string = string,
+  TTools extends ReadonlyArray<SubagentTool> = ReadonlyArray<SubagentTool>,
+  TSchema extends SchemaInput | undefined = SchemaInput | undefined,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> extends AGUISubagentInfo {
+  name: TName
+  /** Required here: the router and the synthetic tool both read it. */
+  description: string
+  run: (
+    ctx: SubagentRunContext,
+  ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>
+  tools?: TTools
+  interrupts?: TInterrupts
+  outputSchema?: TSchema
+  subagents?: unknown
+}
+
+/**
+ * Choice options for a `decide()` router. `main` is required plus every agent name.
+ */
+export type SubagentChoiceOptions<TAgents extends ReadonlyArray<DefinedAgent>> =
+  { main: string } & {
+    [K in TAgents[number]['name']]: string
+  }
+
+/**
+ * Define a named child agent. Pass the same object to `chat({ subagents })`.
+ * Pass the agents array to `useChat({ subagents })` when you render parts
+ * yourself. The hook uses it for types only. It does not call `run`.
+ *
+ * @example
+ * ```ts
+ * const researcher = defineAgent({
+ *   name: 'researcher',
+ *   description: 'Looks up facts',
+ *   run: (ctx) =>
+ *     chat({
+ *       adapter: openaiText('gpt-5.6'),
+ *       messages: ctx.messages,
+ *       threadId: ctx.threadId,
+ *       runId: ctx.runId,
+ *       parentRunId: ctx.parentRunId,
+ *       subagentRunId: ctx.subagentRunId,
+ *       resume: ctx.resume,
+ *     }),
+ * })
+ * ```
+ */
+export function defineAgent<
+  const TName extends string,
+  const TTools extends ReadonlyArray<SubagentTool> = readonly [],
+  TSchema extends SchemaInput | undefined = undefined,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = readonly [],
+>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>) {
+  if (agent.name.trim() === '') {
+    throw new Error('defineAgent requires a non-empty name')
+  }
+  // A router returns 'main' to keep the turn on the parent.
+  if (agent.name.trim() === 'main') {
+    throw new Error(
+      "defineAgent cannot use the name 'main'. A router uses it for the parent.",
+    )
+  }
+  if (agent.description.trim() === '') {
+    throw new Error('defineAgent requires a non-empty description')
+  }
+  return agent
+}