@tanstack/ai 0.51.0 → 0.52.1

package/dist/esm/activities/chat/tools/schema-converter.js

@@ -50,6 +50,21 @@ function isStandardSchema(schema) {
 function pruneMap(map) {
 	return Object.keys(map).length > 0 ? map : void 0;
 }
+function coerceArrayItems(items) {
+	if (Array.isArray(items)) {
+		const nested = items.map((item) => makeStructuredOutputCompatible(item, item.required || []));
+		const itemMaps = nested.map((entry) => entry.nullWidening ?? {});
+		return {
+			schema: nested.map((entry) => entry.schema),
+			itemMap: itemMaps.some((entry) => Object.keys(entry).length > 0) ? itemMaps : void 0
+		};
+	}
+	const nested = makeStructuredOutputCompatible(items, items.required || []);
+	return {
+		schema: nested.schema,
+		itemMap: nested.nullWidening
+	};
+}
 /**
 * Transform a JSON schema to be compatible with OpenAI's structured output requirements.
 * OpenAI requires:
@@ -87,15 +102,14 @@ function makeStructuredOutputCompatible(schema, originalRequired = []) {
 				widenedHere = wasOptional;
 				childMap = nested.nullWidening;
 			} else if (prop.type === "array" && prop.items) {
-				const items = Array.isArray(prop.items) ? prop.items[0] : prop.items;
-				const nestedItems = items ? makeStructuredOutputCompatible(items, items.required || []) : void 0;
+				const nestedItems = coerceArrayItems(prop.items);
 				properties[propName] = {
 					...prop,
-					items: nestedItems ? nestedItems.schema : prop.items,
+					items: nestedItems.schema,
 					...wasOptional ? { type: ["array", "null"] } : {}
 				};
 				widenedHere = wasOptional;
-				childMap = nestedItems?.nullWidening ? { items: nestedItems.nullWidening } : void 0;
+				childMap = nestedItems.itemMap ? { items: nestedItems.itemMap } : void 0;
 			} else if (wasOptional) {
 				if (prop.type && !Array.isArray(prop.type)) {
 					properties[propName] = {
@@ -122,12 +136,9 @@ function makeStructuredOutputCompatible(schema, originalRequired = []) {
 		if (Object.keys(propertyMaps).length > 0) map.properties = propertyMaps;
 	}
 	if (result.type === "array" && result.items) {
-		const items = Array.isArray(result.items) ? result.items[0] : result.items;
-		if (items) {
-			const nestedItems = makeStructuredOutputCompatible(items, items.required || []);
-			result.items = nestedItems.schema;
-			if (nestedItems.nullWidening) map.items = nestedItems.nullWidening;
-		}
+		const nestedItems = coerceArrayItems(result.items);
+		result.items = nestedItems.schema;
+		if (nestedItems.itemMap) map.items = nestedItems.itemMap;
 	}
 	return {
 		schema: result,

package/dist/esm/activities/chat/tools/schema-converter.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema-converter.js","names":[],"sources":["../../../../../src/activities/chat/tools/schema-converter.ts"],"sourcesContent":["import type {\n  StandardJSONSchemaV1,\n  StandardSchemaV1,\n} from '@standard-schema/spec'\nimport type { NullWideningMap } from '@tanstack/ai-utils'\nimport type { JSONSchema, SchemaInput } from '../../../types'\n\n/**\n * Build a JSONSchema object from any plain key/value source. The `JSONSchema`\n * interface's `[key: string]: any` index signature makes every property\n * assignable through bracket access without a type cast — copying keys here\n * lets us narrow either `Record<string, unknown>` (returned by\n * `~standard.jsonSchema.input()`) or a `JSONSchema` (from the SchemaInput\n * pass-through arm) into the typed view used by the rest of this module.\n *\n * Accepts `object` so callers don't need a cast when narrowing from union\n * types like `SchemaInput`.\n */\nfunction toJsonSchema(obj: object): JSONSchema {\n  const result: JSONSchema = {}\n  for (const [key, value] of Object.entries(obj)) {\n    if (key === '$schema') continue // not needed by LLM providers\n    result[key] = value\n  }\n  return result\n}\n\n/**\n * Whether a value can carry a `~standard` property. Most schema libraries\n * (Zod, Valibot) return plain objects, but ArkType's `type()` returns a\n * *callable function* with `~standard` attached — so `typeof` must accept\n * both `'object'` and `'function'` or ArkType schemas are missed entirely\n * (issue #276).\n */\nfunction isPropertyCarrier(schema: unknown): schema is Record<string, unknown> {\n  return (\n    (typeof schema === 'object' || typeof schema === 'function') &&\n    schema !== null\n  )\n}\n\n/**\n * Check if a value is a Standard JSON Schema compliant schema.\n * Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)\n * implement the '~standard' property with jsonSchema converter methods.\n */\nexport function isStandardJSONSchema(\n  schema: unknown,\n): schema is StandardJSONSchemaV1 {\n  if (!isPropertyCarrier(schema) || !('~standard' in schema)) return false\n\n  const standard = schema['~standard']\n  if (\n    typeof standard !== 'object' ||\n    standard === null ||\n    !('version' in standard) ||\n    standard.version !== 1 ||\n    !('jsonSchema' in standard) ||\n    typeof standard.jsonSchema !== 'object' ||\n    standard.jsonSchema === null ||\n    !('input' in standard.jsonSchema)\n  ) {\n    return false\n  }\n\n  return typeof standard.jsonSchema.input === 'function'\n}\n\n/**\n * Check if a value is a Standard Schema compliant schema (for validation).\n * Standard Schema compliant libraries implement the '~standard' property with a validate function.\n */\nexport function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {\n  return (\n    isPropertyCarrier(schema) &&\n    '~standard' in schema &&\n    typeof schema['~standard'] === 'object' &&\n    schema['~standard'] !== null &&\n    'version' in schema['~standard'] &&\n    schema['~standard'].version === 1 &&\n    'validate' in schema['~standard'] &&\n    typeof schema['~standard'].validate === 'function'\n  )\n}\n\n/**\n * Result of {@link makeStructuredOutputCompatible}: the strict-ready schema plus\n * a {@link NullWideningMap} recording every position where a `null` was\n * synthesized, so the response can be un-widened before validation without\n * re-deriving (or guessing) which nulls were synthetic.\n */\ninterface StructuredOutputConversion {\n  schema: JSONSchema\n  nullWidening: NullWideningMap | undefined\n}\n\n/** Drop an empty map to `undefined` so leaf/no-op subtrees don't litter it. */\nfunction pruneMap(map: NullWideningMap): NullWideningMap | undefined {\n  return Object.keys(map).length > 0 ? map : undefined\n}\n\n/**\n * Transform a JSON schema to be compatible with OpenAI's structured output requirements.\n * OpenAI requires:\n * - All properties must be in the `required` array\n * - Optional fields should have null added to their type union\n * - additionalProperties must be false for objects\n *\n * Alongside the transformed schema it returns a {@link NullWideningMap} marking\n * exactly the positions where `null` was added, so `undoNullWidening` can strip\n * those synthesized nulls (and only those) from the provider's response.\n *\n * @param schema - JSON schema to transform\n * @param originalRequired - Original required array (to know which fields were optional)\n * @returns Transformed schema + the null-widening map for the round trip\n */\nfunction makeStructuredOutputCompatible(\n  schema: JSONSchema,\n  originalRequired: Array<string> = [],\n): StructuredOutputConversion {\n  const result: JSONSchema = { ...schema }\n  const map: NullWideningMap = {}\n\n  // Handle object types\n  if (result.type === 'object' && result.properties) {\n    const properties: Record<string, JSONSchema> = { ...result.properties }\n    const allPropertyNames = Object.keys(properties)\n    const propertyMaps: Record<string, NullWideningMap> = {}\n\n    // Transform each property\n    for (const propName of allPropertyNames) {\n      const prop = properties[propName]\n      if (!prop) continue\n      const wasOptional = !originalRequired.includes(propName)\n      // `null` synthesized AT this property (the field itself can come back null).\n      let widenedHere = false\n      // Map describing widened positions INSIDE this property.\n      let childMap: NullWideningMap | undefined\n\n      // Recursively transform nested objects/arrays\n      if (prop.type === 'object' && prop.properties) {\n        const nested = makeStructuredOutputCompatible(prop, prop.required || [])\n        properties[propName] = wasOptional\n          ? { ...nested.schema, type: ['object', 'null'] }\n          : nested.schema\n        widenedHere = wasOptional\n        childMap = nested.nullWidening\n      } else if (prop.type === 'array' && prop.items) {\n        const items = Array.isArray(prop.items) ? prop.items[0] : prop.items\n        const nestedItems = items\n          ? makeStructuredOutputCompatible(items, items.required || [])\n          : undefined\n        properties[propName] = {\n          ...prop,\n          items: nestedItems ? nestedItems.schema : prop.items,\n          ...(wasOptional ? { type: ['array', 'null'] } : {}),\n        }\n        widenedHere = wasOptional\n        childMap = nestedItems?.nullWidening\n          ? { items: nestedItems.nullWidening }\n          : undefined\n      } else if (wasOptional) {\n        // Make optional fields nullable by adding null to the type. Mark\n        // `widenedHere` only where we actually add `null`; a field already\n        // typed nullable (`.nullish()`) is left as-is and keeps its null.\n        if (prop.type && !Array.isArray(prop.type)) {\n          properties[propName] = { ...prop, type: [prop.type, 'null'] }\n          widenedHere = true\n        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {\n          properties[propName] = { ...prop, type: [...prop.type, 'null'] }\n          widenedHere = true\n        }\n      }\n\n      if (widenedHere || childMap) {\n        propertyMaps[propName] = {\n          ...(childMap ?? {}),\n          ...(widenedHere ? { widened: true } : {}),\n        }\n      }\n    }\n\n    result.properties = properties\n    // ALL properties must be required for OpenAI structured output\n    result.required = allPropertyNames\n    // additionalProperties must be false\n    result.additionalProperties = false\n    if (Object.keys(propertyMaps).length > 0) map.properties = propertyMaps\n  }\n\n  // Handle array types with object items\n  if (result.type === 'array' && result.items) {\n    const items = Array.isArray(result.items) ? result.items[0] : result.items\n    if (items) {\n      const nestedItems = makeStructuredOutputCompatible(\n        items,\n        items.required || [],\n      )\n      result.items = nestedItems.schema\n      if (nestedItems.nullWidening) map.items = nestedItems.nullWidening\n    }\n  }\n\n  return { schema: result, nullWidening: pruneMap(map) }\n}\n\n/**\n * Options for schema conversion\n */\nexport interface ConvertSchemaOptions {\n  /**\n   * When true, transforms the schema to be compatible with OpenAI's structured output requirements:\n   * - All properties are added to the `required` array\n   * - Optional fields get null added to their type union\n   * - additionalProperties is set to false for all objects\n   *\n   * @default false\n   */\n  forStructuredOutput?: boolean\n}\n\n/**\n * Normalize any supported schema input to a typed, UN-widened `JSONSchema` —\n * the shared first half of conversion, before any structured-output widening.\n *\n * - Standard JSON Schemas are rebuilt structurally (dropping `$schema`, which\n *   LLM providers ignore) and given the explicit `type`/`properties`/`required`\n *   defaults object shapes need downstream.\n * - Plain `JSONSchema` inputs are rebuilt into the typed view; non-object inputs\n *   are surfaced untouched (they can't be widened).\n * - Standard Schema validators lacking a `~standard.jsonSchema` converter throw\n *   with actionable guidance, rather than shipping `{ '~standard': … }` to the\n *   provider and producing an opaque downstream error.\n */\nfunction toTypedJsonSchema(schema: SchemaInput): JSONSchema | undefined {\n  if (isStandardJSONSchema(schema)) {\n    const jsonSchema = schema['~standard'].jsonSchema.input({\n      target: 'draft-07',\n    })\n    const result: JSONSchema = toJsonSchema(jsonSchema)\n    if ('properties' in result && !result.type) result.type = 'object'\n    if (result.type === 'object' && !('properties' in result)) {\n      result.properties = {}\n    }\n    if (result.type === 'object' && !('required' in result)) {\n      result.required = []\n    }\n    return result\n  }\n\n  if (isStandardSchema(schema)) {\n    throw new Error(\n      'Schema is a Standard Schema validator but does not expose a JSON Schema ' +\n        'converter on `~standard.jsonSchema`. Use Zod v4.2+, ArkType v2.1.28+, ' +\n        'or wrap a Valibot schema with `toStandardJsonSchema()` from ' +\n        '`@valibot/to-json-schema` before passing it as `outputSchema`.',\n    )\n  }\n\n  if (typeof schema !== 'object') return schema\n  return toJsonSchema(schema)\n}\n\n/**\n * Converts a Standard JSON Schema compliant schema or plain JSONSchema to JSON Schema format\n * compatible with LLM providers.\n *\n * Supports any schema library that implements the Standard JSON Schema spec (v1):\n * - Zod v4+ (natively supports StandardJSONSchemaV1)\n * - ArkType (natively supports StandardJSONSchemaV1)\n * - Valibot (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)\n *\n * If the input is already a plain JSONSchema object, it is returned as-is.\n *\n * @param schema - Standard JSON Schema compliant schema or plain JSONSchema object to convert\n * @param options - Conversion options\n * @returns JSON Schema object that can be sent to LLM providers\n *\n * @example\n * ```typescript\n * // Using Zod v4+ (natively supports Standard JSON Schema)\n * import * as z from 'zod';\n *\n * const zodSchema = z.object({\n *   location: z.string().describe('City name'),\n *   unit: z.enum(['celsius', 'fahrenheit']).optional()\n * });\n *\n * const jsonSchema = convertSchemaToJsonSchema(zodSchema);\n *\n * @example\n * // Using ArkType (natively supports Standard JSON Schema)\n * import { type } from 'arktype';\n *\n * const arkSchema = type({\n *   location: 'string',\n *   unit: \"'celsius' | 'fahrenheit'\"\n * });\n *\n * const jsonSchema = convertSchemaToJsonSchema(arkSchema);\n *\n * @example\n * // Using Valibot (via toStandardJsonSchema)\n * import * as v from 'valibot';\n * import { toStandardJsonSchema } from '@valibot/to-json-schema';\n *\n * const valibotSchema = toStandardJsonSchema(v.object({\n *   location: v.string(),\n *   unit: v.optional(v.picklist(['celsius', 'fahrenheit']))\n * }));\n *\n * const jsonSchema = convertSchemaToJsonSchema(valibotSchema);\n *\n * @example\n * // Using JSONSchema directly (passes through unchanged)\n * const rawSchema = {\n *   type: 'object',\n *   properties: { location: { type: 'string' } },\n *   required: ['location']\n * };\n * const result = convertSchemaToJsonSchema(rawSchema);\n * ```\n */\nexport function convertSchemaToJsonSchema(\n  schema: SchemaInput | undefined,\n  options: ConvertSchemaOptions = {},\n): JSONSchema | undefined {\n  if (!schema) return undefined\n\n  const { forStructuredOutput = false } = options\n\n  // Plain-JSONSchema passthrough: with no widening requested, return the schema\n  // by reference so callers comparing via `===` keep identity. Only the widening\n  // path needs the rebuilt, normalized view from `toTypedJsonSchema`.\n  if (\n    !forStructuredOutput &&\n    !isStandardJSONSchema(schema) &&\n    !isStandardSchema(schema)\n  ) {\n    return schema\n  }\n\n  const base = toTypedJsonSchema(schema)\n  // Non-object inputs can't be widened; surface them untouched.\n  if (!base || typeof base !== 'object') return base\n  if (!forStructuredOutput) return base\n  return makeStructuredOutputCompatible(base, base.required || []).schema\n}\n\n/**\n * Convert a schema for structured output AND capture the {@link NullWideningMap}\n * recording every `null` the strict-mode widening synthesized. The map lets the\n * caller undo that widening on the provider's response (via `undoNullWidening`)\n * before validating against the original schema — optional fields read back as\n * absent while genuine `.nullable()` nulls survive. The map is `undefined` when\n * the schema isn't a widenable object or when no field needed widening.\n */\nexport function convertSchemaForStructuredOutput(\n  schema: SchemaInput | undefined,\n): {\n  jsonSchema: JSONSchema | undefined\n  nullWideningMap: NullWideningMap | undefined\n} {\n  if (!schema) return { jsonSchema: undefined, nullWideningMap: undefined }\n  const base = toTypedJsonSchema(schema)\n  if (!base || typeof base !== 'object') {\n    return { jsonSchema: base, nullWideningMap: undefined }\n  }\n  const { schema: jsonSchema, nullWidening } = makeStructuredOutputCompatible(\n    base,\n    base.required || [],\n  )\n  return { jsonSchema, nullWideningMap: nullWidening }\n}\n\n/**\n * Validates data against a Standard Schema compliant schema.\n *\n * @param schema - Standard Schema compliant schema\n * @param data - Data to validate\n * @returns Validation result with success status, data or issues\n */\nexport async function validateWithStandardSchema<T>(\n  schema: unknown,\n  data: unknown,\n): Promise<\n  | { success: true; data: T }\n  | {\n      success: false\n      issues: Array<{ message: string; path?: Array<string> | undefined }>\n    }\n> {\n  if (!isStandardSchema(schema)) {\n    // If it's not a Standard Schema, just return the data as-is\n    return { success: true, data: data as T }\n  }\n\n  const result = await schema['~standard'].validate(data)\n\n  if (!result.issues) {\n    return { success: true, data: result.value as T }\n  }\n\n  return {\n    success: false,\n    issues: result.issues.map((issue) => ({\n      message: issue.message || 'Validation failed',\n      path: issue.path?.map(String),\n    })),\n  }\n}\n\n/**\n * Error thrown when Standard Schema validation fails. Carries the original\n * `issues` array so consumers (middleware `onError`, callers catching from\n * `chat({ outputSchema })`) can programmatically inspect each failure.\n */\nexport class StandardSchemaValidationError extends Error {\n  override readonly name = 'StandardSchemaValidationError'\n  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>\n\n  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>) {\n    super(\n      `Validation failed: ${issues\n        .map((i) => i.message || 'Validation failed')\n        .join(', ')}`,\n    )\n    this.issues = issues\n  }\n}\n\n/**\n * Synchronously validates data against a Standard Schema compliant schema.\n * Note: Some Standard Schema implementations may only support async validation.\n * In those cases, this function will throw.\n *\n * @param schema - Standard Schema compliant schema\n * @param data - Data to validate\n * @returns Parsed/validated data\n * @throws StandardSchemaValidationError if validation fails; Error if the\n *         schema only supports async validation.\n */\nexport function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {\n  if (!isStandardSchema(schema)) {\n    // If it's not a Standard Schema, just return the data as-is\n    return data as T\n  }\n\n  const result = schema['~standard'].validate(data)\n\n  // Handle async result (Promise)\n  if (result instanceof Promise) {\n    throw new Error(\n      'Schema validation returned a Promise. Use validateWithStandardSchema for async validation.',\n    )\n  }\n  // Standard Schema validation returns { value } for success or { issues } for failure\n  if (!result.issues) {\n    return result.value as T\n  }\n\n  throw new StandardSchemaValidationError(result.issues)\n}\n"],"mappings":"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"}
+{"version":3,"file":"schema-converter.js","names":[],"sources":["../../../../../src/activities/chat/tools/schema-converter.ts"],"sourcesContent":["import type {\n  StandardJSONSchemaV1,\n  StandardSchemaV1,\n} from '@standard-schema/spec'\nimport type { NullWideningMap } from '@tanstack/ai-utils'\nimport type { JSONSchema, SchemaInput } from '../../../types'\n\n/**\n * Build a JSONSchema object from any plain key/value source. The `JSONSchema`\n * interface's `[key: string]: any` index signature makes every property\n * assignable through bracket access without a type cast — copying keys here\n * lets us narrow either `Record<string, unknown>` (returned by\n * `~standard.jsonSchema.input()`) or a `JSONSchema` (from the SchemaInput\n * pass-through arm) into the typed view used by the rest of this module.\n *\n * Accepts `object` so callers don't need a cast when narrowing from union\n * types like `SchemaInput`.\n */\nfunction toJsonSchema(obj: object): JSONSchema {\n  const result: JSONSchema = {}\n  for (const [key, value] of Object.entries(obj)) {\n    if (key === '$schema') continue // not needed by LLM providers\n    result[key] = value\n  }\n  return result\n}\n\n/**\n * Whether a value can carry a `~standard` property. Most schema libraries\n * (Zod, Valibot) return plain objects, but ArkType's `type()` returns a\n * *callable function* with `~standard` attached — so `typeof` must accept\n * both `'object'` and `'function'` or ArkType schemas are missed entirely\n * (issue #276).\n */\nfunction isPropertyCarrier(schema: unknown): schema is Record<string, unknown> {\n  return (\n    (typeof schema === 'object' || typeof schema === 'function') &&\n    schema !== null\n  )\n}\n\n/**\n * Check if a value is a Standard JSON Schema compliant schema.\n * Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)\n * implement the '~standard' property with jsonSchema converter methods.\n */\nexport function isStandardJSONSchema(\n  schema: unknown,\n): schema is StandardJSONSchemaV1 {\n  if (!isPropertyCarrier(schema) || !('~standard' in schema)) return false\n\n  const standard = schema['~standard']\n  if (\n    typeof standard !== 'object' ||\n    standard === null ||\n    !('version' in standard) ||\n    standard.version !== 1 ||\n    !('jsonSchema' in standard) ||\n    typeof standard.jsonSchema !== 'object' ||\n    standard.jsonSchema === null ||\n    !('input' in standard.jsonSchema)\n  ) {\n    return false\n  }\n\n  return typeof standard.jsonSchema.input === 'function'\n}\n\n/**\n * Check if a value is a Standard Schema compliant schema (for validation).\n * Standard Schema compliant libraries implement the '~standard' property with a validate function.\n */\nexport function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {\n  return (\n    isPropertyCarrier(schema) &&\n    '~standard' in schema &&\n    typeof schema['~standard'] === 'object' &&\n    schema['~standard'] !== null &&\n    'version' in schema['~standard'] &&\n    schema['~standard'].version === 1 &&\n    'validate' in schema['~standard'] &&\n    typeof schema['~standard'].validate === 'function'\n  )\n}\n\n/**\n * Result of {@link makeStructuredOutputCompatible}: the strict-ready schema plus\n * a {@link NullWideningMap} recording every position where a `null` was\n * synthesized, so the response can be un-widened before validation without\n * re-deriving (or guessing) which nulls were synthetic.\n */\ninterface StructuredOutputConversion {\n  schema: JSONSchema\n  nullWidening: NullWideningMap | undefined\n}\n\n/** Drop an empty map to `undefined` so leaf/no-op subtrees don't litter it. */\nfunction pruneMap(map: NullWideningMap): NullWideningMap | undefined {\n  return Object.keys(map).length > 0 ? map : undefined\n}\n\nfunction coerceArrayItems(items: JSONSchema | Array<JSONSchema>): {\n  schema: JSONSchema | Array<JSONSchema>\n  itemMap: NullWideningMap | Array<NullWideningMap> | undefined\n} {\n  if (Array.isArray(items)) {\n    const nested = items.map((item) =>\n      makeStructuredOutputCompatible(item, item.required || []),\n    )\n    const itemMaps = nested.map((entry) => entry.nullWidening ?? {})\n    return {\n      schema: nested.map((entry) => entry.schema),\n      itemMap: itemMaps.some((entry) => Object.keys(entry).length > 0)\n        ? itemMaps\n        : undefined,\n    }\n  }\n  const nested = makeStructuredOutputCompatible(items, items.required || [])\n  return { schema: nested.schema, itemMap: nested.nullWidening }\n}\n\n/**\n * Transform a JSON schema to be compatible with OpenAI's structured output requirements.\n * OpenAI requires:\n * - All properties must be in the `required` array\n * - Optional fields should have null added to their type union\n * - additionalProperties must be false for objects\n *\n * Alongside the transformed schema it returns a {@link NullWideningMap} marking\n * exactly the positions where `null` was added, so `undoNullWidening` can strip\n * those synthesized nulls (and only those) from the provider's response.\n *\n * @param schema - JSON schema to transform\n * @param originalRequired - Original required array (to know which fields were optional)\n * @returns Transformed schema + the null-widening map for the round trip\n */\nfunction makeStructuredOutputCompatible(\n  schema: JSONSchema,\n  originalRequired: Array<string> = [],\n): StructuredOutputConversion {\n  const result: JSONSchema = { ...schema }\n  const map: NullWideningMap = {}\n\n  // Handle object types\n  if (result.type === 'object' && result.properties) {\n    const properties: Record<string, JSONSchema> = { ...result.properties }\n    const allPropertyNames = Object.keys(properties)\n    const propertyMaps: Record<string, NullWideningMap> = {}\n\n    // Transform each property\n    for (const propName of allPropertyNames) {\n      const prop = properties[propName]\n      if (!prop) continue\n      const wasOptional = !originalRequired.includes(propName)\n      // `null` synthesized AT this property (the field itself can come back null).\n      let widenedHere = false\n      // Map describing widened positions INSIDE this property.\n      let childMap: NullWideningMap | undefined\n\n      // Recursively transform nested objects/arrays\n      if (prop.type === 'object' && prop.properties) {\n        const nested = makeStructuredOutputCompatible(prop, prop.required || [])\n        properties[propName] = wasOptional\n          ? { ...nested.schema, type: ['object', 'null'] }\n          : nested.schema\n        widenedHere = wasOptional\n        childMap = nested.nullWidening\n      } else if (prop.type === 'array' && prop.items) {\n        const nestedItems = coerceArrayItems(prop.items)\n        properties[propName] = {\n          ...prop,\n          items: nestedItems.schema,\n          ...(wasOptional ? { type: ['array', 'null'] } : {}),\n        }\n        widenedHere = wasOptional\n        childMap = nestedItems.itemMap\n          ? { items: nestedItems.itemMap }\n          : undefined\n      } else if (wasOptional) {\n        // Make optional fields nullable by adding null to the type. Mark\n        // `widenedHere` only where we actually add `null`; a field already\n        // typed nullable (`.nullish()`) is left as-is and keeps its null.\n        if (prop.type && !Array.isArray(prop.type)) {\n          properties[propName] = { ...prop, type: [prop.type, 'null'] }\n          widenedHere = true\n        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {\n          properties[propName] = { ...prop, type: [...prop.type, 'null'] }\n          widenedHere = true\n        }\n      }\n\n      if (widenedHere || childMap) {\n        propertyMaps[propName] = {\n          ...(childMap ?? {}),\n          ...(widenedHere ? { widened: true } : {}),\n        }\n      }\n    }\n\n    result.properties = properties\n    // ALL properties must be required for OpenAI structured output\n    result.required = allPropertyNames\n    // additionalProperties must be false\n    result.additionalProperties = false\n    if (Object.keys(propertyMaps).length > 0) map.properties = propertyMaps\n  }\n\n  // Handle array item schemas. A tuple (`items: [a, b, …]`) keeps every\n  // position. A homogeneous schema stays a single items map so\n  // `undoNullWidening` applies it to every element.\n  if (result.type === 'array' && result.items) {\n    const nestedItems = coerceArrayItems(result.items)\n    result.items = nestedItems.schema\n    if (nestedItems.itemMap) map.items = nestedItems.itemMap\n  }\n\n  return { schema: result, nullWidening: pruneMap(map) }\n}\n\n/**\n * Options for schema conversion\n */\nexport interface ConvertSchemaOptions {\n  /**\n   * When true, transforms the schema to be compatible with OpenAI's structured output requirements:\n   * - All properties are added to the `required` array\n   * - Optional fields get null added to their type union\n   * - additionalProperties is set to false for all objects\n   *\n   * @default false\n   */\n  forStructuredOutput?: boolean\n}\n\n/**\n * Normalize any supported schema input to a typed, UN-widened `JSONSchema` —\n * the shared first half of conversion, before any structured-output widening.\n *\n * - Standard JSON Schemas are rebuilt structurally (dropping `$schema`, which\n *   LLM providers ignore) and given the explicit `type`/`properties`/`required`\n *   defaults object shapes need downstream.\n * - Plain `JSONSchema` inputs are rebuilt into the typed view; non-object inputs\n *   are surfaced untouched (they can't be widened).\n * - Standard Schema validators lacking a `~standard.jsonSchema` converter throw\n *   with actionable guidance, rather than shipping `{ '~standard': … }` to the\n *   provider and producing an opaque downstream error.\n */\nfunction toTypedJsonSchema(schema: SchemaInput): JSONSchema | undefined {\n  if (isStandardJSONSchema(schema)) {\n    const jsonSchema = schema['~standard'].jsonSchema.input({\n      target: 'draft-07',\n    })\n    const result: JSONSchema = toJsonSchema(jsonSchema)\n    if ('properties' in result && !result.type) result.type = 'object'\n    if (result.type === 'object' && !('properties' in result)) {\n      result.properties = {}\n    }\n    if (result.type === 'object' && !('required' in result)) {\n      result.required = []\n    }\n    return result\n  }\n\n  if (isStandardSchema(schema)) {\n    throw new Error(\n      'Schema is a Standard Schema validator but does not expose a JSON Schema ' +\n        'converter on `~standard.jsonSchema`. Use Zod v4.2+, ArkType v2.1.28+, ' +\n        'or wrap a Valibot schema with `toStandardJsonSchema()` from ' +\n        '`@valibot/to-json-schema` before passing it as `outputSchema`.',\n    )\n  }\n\n  if (typeof schema !== 'object') return schema\n  return toJsonSchema(schema)\n}\n\n/**\n * Converts a Standard JSON Schema compliant schema or plain JSONSchema to JSON Schema format\n * compatible with LLM providers.\n *\n * Supports any schema library that implements the Standard JSON Schema spec (v1):\n * - Zod v4+ (natively supports StandardJSONSchemaV1)\n * - ArkType (natively supports StandardJSONSchemaV1)\n * - Valibot (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)\n *\n * If the input is already a plain JSONSchema object, it is returned as-is.\n *\n * @param schema - Standard JSON Schema compliant schema or plain JSONSchema object to convert\n * @param options - Conversion options\n * @returns JSON Schema object that can be sent to LLM providers\n *\n * @example\n * ```typescript\n * // Using Zod v4+ (natively supports Standard JSON Schema)\n * import * as z from 'zod';\n *\n * const zodSchema = z.object({\n *   location: z.string().describe('City name'),\n *   unit: z.enum(['celsius', 'fahrenheit']).optional()\n * });\n *\n * const jsonSchema = convertSchemaToJsonSchema(zodSchema);\n *\n * @example\n * // Using ArkType (natively supports Standard JSON Schema)\n * import { type } from 'arktype';\n *\n * const arkSchema = type({\n *   location: 'string',\n *   unit: \"'celsius' | 'fahrenheit'\"\n * });\n *\n * const jsonSchema = convertSchemaToJsonSchema(arkSchema);\n *\n * @example\n * // Using Valibot (via toStandardJsonSchema)\n * import * as v from 'valibot';\n * import { toStandardJsonSchema } from '@valibot/to-json-schema';\n *\n * const valibotSchema = toStandardJsonSchema(v.object({\n *   location: v.string(),\n *   unit: v.optional(v.picklist(['celsius', 'fahrenheit']))\n * }));\n *\n * const jsonSchema = convertSchemaToJsonSchema(valibotSchema);\n *\n * @example\n * // Using JSONSchema directly (passes through unchanged)\n * const rawSchema = {\n *   type: 'object',\n *   properties: { location: { type: 'string' } },\n *   required: ['location']\n * };\n * const result = convertSchemaToJsonSchema(rawSchema);\n * ```\n */\nexport function convertSchemaToJsonSchema(\n  schema: SchemaInput | undefined,\n  options: ConvertSchemaOptions = {},\n): JSONSchema | undefined {\n  if (!schema) return undefined\n\n  const { forStructuredOutput = false } = options\n\n  // Plain-JSONSchema passthrough: with no widening requested, return the schema\n  // by reference so callers comparing via `===` keep identity. Only the widening\n  // path needs the rebuilt, normalized view from `toTypedJsonSchema`.\n  if (\n    !forStructuredOutput &&\n    !isStandardJSONSchema(schema) &&\n    !isStandardSchema(schema)\n  ) {\n    return schema\n  }\n\n  const base = toTypedJsonSchema(schema)\n  // Non-object inputs can't be widened; surface them untouched.\n  if (!base || typeof base !== 'object') return base\n  if (!forStructuredOutput) return base\n  return makeStructuredOutputCompatible(base, base.required || []).schema\n}\n\n/**\n * Convert a schema for structured output AND capture the {@link NullWideningMap}\n * recording every `null` the strict-mode widening synthesized. The map lets the\n * caller undo that widening on the provider's response (via `undoNullWidening`)\n * before validating against the original schema — optional fields read back as\n * absent while genuine `.nullable()` nulls survive. The map is `undefined` when\n * the schema isn't a widenable object or when no field needed widening.\n */\nexport function convertSchemaForStructuredOutput(\n  schema: SchemaInput | undefined,\n): {\n  jsonSchema: JSONSchema | undefined\n  nullWideningMap: NullWideningMap | undefined\n} {\n  if (!schema) return { jsonSchema: undefined, nullWideningMap: undefined }\n  const base = toTypedJsonSchema(schema)\n  if (!base || typeof base !== 'object') {\n    return { jsonSchema: base, nullWideningMap: undefined }\n  }\n  const { schema: jsonSchema, nullWidening } = makeStructuredOutputCompatible(\n    base,\n    base.required || [],\n  )\n  return { jsonSchema, nullWideningMap: nullWidening }\n}\n\n/**\n * Validates data against a Standard Schema compliant schema.\n *\n * @param schema - Standard Schema compliant schema\n * @param data - Data to validate\n * @returns Validation result with success status, data or issues\n */\nexport async function validateWithStandardSchema<T>(\n  schema: unknown,\n  data: unknown,\n): Promise<\n  | { success: true; data: T }\n  | {\n      success: false\n      issues: Array<{ message: string; path?: Array<string> | undefined }>\n    }\n> {\n  if (!isStandardSchema(schema)) {\n    // If it's not a Standard Schema, just return the data as-is\n    return { success: true, data: data as T }\n  }\n\n  const result = await schema['~standard'].validate(data)\n\n  if (!result.issues) {\n    return { success: true, data: result.value as T }\n  }\n\n  return {\n    success: false,\n    issues: result.issues.map((issue) => ({\n      message: issue.message || 'Validation failed',\n      path: issue.path?.map(String),\n    })),\n  }\n}\n\n/**\n * Error thrown when Standard Schema validation fails. Carries the original\n * `issues` array so consumers (middleware `onError`, callers catching from\n * `chat({ outputSchema })`) can programmatically inspect each failure.\n */\nexport class StandardSchemaValidationError extends Error {\n  override readonly name = 'StandardSchemaValidationError'\n  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>\n\n  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>) {\n    super(\n      `Validation failed: ${issues\n        .map((i) => i.message || 'Validation failed')\n        .join(', ')}`,\n    )\n    this.issues = issues\n  }\n}\n\n/**\n * Synchronously validates data against a Standard Schema compliant schema.\n * Note: Some Standard Schema implementations may only support async validation.\n * In those cases, this function will throw.\n *\n * @param schema - Standard Schema compliant schema\n * @param data - Data to validate\n * @returns Parsed/validated data\n * @throws StandardSchemaValidationError if validation fails; Error if the\n *         schema only supports async validation.\n */\nexport function parseWithStandardSchema<T>(schema: unknown, data: unknown): T {\n  if (!isStandardSchema(schema)) {\n    // If it's not a Standard Schema, just return the data as-is\n    return data as T\n  }\n\n  const result = schema['~standard'].validate(data)\n\n  // Handle async result (Promise)\n  if (result instanceof Promise) {\n    throw new Error(\n      'Schema validation returned a Promise. Use validateWithStandardSchema for async validation.',\n    )\n  }\n  // Standard Schema validation returns { value } for success or { issues } for failure\n  if (!result.issues) {\n    return result.value as T\n  }\n\n  throw new StandardSchemaValidationError(result.issues)\n}\n"],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -41,8 +41,8 @@ export type { InterruptDefinition, GenericInterruptRequest, InterruptDefinitionO
 export { INTERRUPT_BINDING_VERSION, canonicalizeInterruptResolutions, } from './interrupts.js';
 export type { BatchInterruptError, BatchInterruptErrorCode, InterruptBinding, InterruptCorrelation, InterruptSubmissionError, ItemInterruptError, ItemInterruptErrorCode, ToolApprovalResolution, UnopenedInterruptBinding, } from './interrupts.js';
 export type { GenerationMiddleware, GenerationMiddlewareContext, GenerationActivity, GenerationUsageInfo, GenerationFinishInfo, GenerationAbortInfo, GenerationErrorInfo, AnyGenerationMiddleware, GenerationResultTransform, GenerationResultTransformContext, } from './activities/middleware/index.js';
-export { createCapability, defineChatMiddleware, createChatMiddleware, } from './activities/chat/middleware/index.js';
-export type { Capability, CapabilityHandle, CapabilityContext, CapabilityGetter, CapabilityProvider, DefinedChatMiddleware, AnyChatMiddleware, } from './activities/chat/middleware/index.js';
+export { createCapability, defineChatMiddleware, createChatMiddleware, MetadataCapability, getMetadata, provideMetadata, } from './activities/chat/middleware/index.js';
+export type { Capability, CapabilityHandle, CapabilityContext, CapabilityGetter, CapabilityProvider, DefinedChatMiddleware, AnyChatMiddleware, MetadataStore, } from './activities/chat/middleware/index.js';
 export { isRunStatus, isTerminalRunStatus, defineRunStore, InMemoryRunStore, } from './activities/chat/middleware/index.js';
 export type { RunStatus, TerminalRunStatus, RunRecord, RunError, RunStore, } from './activities/chat/middleware/index.js';
 export { DetachableRunCapability, getDetachableRun, provideDetachableRun, } from './activities/chat/middleware/run-store.js';

package/dist/esm/index.js

@@ -46,6 +46,7 @@ import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
 import { INTERRUPT_BOUNDARY_PHASES, INTERRUPT_TOOL_RESUMES } from "./activities/chat/middleware/types.js";
 import { defineChatMiddleware } from "./activities/chat/middleware/define.js";
 import { createChatMiddleware } from "./activities/chat/middleware/builder.js";
+import { MetadataCapability, getMetadata, provideMetadata } from "./activities/chat/middleware/metadata.js";
 import { CUSTOM_EVENT, isCustomEvent } from "./custom-events.js";
 import { buildBaseUsage } from "./utilities/usage.js";
 import { normalizeSystemPrompts } from "./system-prompts.js";
@@ -58,4 +59,4 @@ import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrateg
 import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
 import { generationParamsFromBody, generationParamsFromRequest } from "./client.js";
 import { createModel, extendAdapter } from "./extend-adapter.js";
-export { BaseRerankAdapter, BatchStrategy, CUSTOM_EVENT, CompositeStrategy, ConsoleLogger, DISCOVERY_TOOL_NAME, DetachableRunCapability, DuplicateToolNameError, EventType, INTERRUPT_BINDING_METADATA_KEY, INTERRUPT_BINDING_VERSION, INTERRUPT_BOUNDARY_PHASES, INTERRUPT_CONTINUATION_METADATA_KEY, INTERRUPT_CONTINUATION_VERSION, INTERRUPT_PAYLOAD_METADATA_KEY, INTERRUPT_TOOL_RESUMES, ImmediateStrategy, InMemoryRunStore, InterruptResumeValidationError, MCPDuplicateToolNameError, PartialJSONParser, PunctuationStrategy, RUN_ACCEPTED_EVENT, RUN_CANCEL_REASON, RunDetachedCapability, SkillLimitError, StandardSchemaValidationError, StreamProcessor, ToolCallManager, WordBoundaryStrategy, brandProviderTool, buildBaseUsage, canonicalInterruptJson, canonicalizeInterruptResolutions, chat, chatParamsFromRequest, chatParamsFromRequestBody, cloneAndDeepFreezeJson, combineStrategies, convertMessagesToModelMessages, convertSchemaToJsonSchema, countEmbeddingInputModalities, createAudioOptions, createCapability, createChatMiddleware, createChatOptions, createEmbedOptions, createFrozenRegistry, createImageOptions, createInterruptBinding, createModel, createRealtimeEventEmitter, createReplayStream, createRerankOptions, createSpeechOptions, createSummarizeOptions, createToolRegistry, createTranscriptionOptions, createVideoOptions, decodeWsFrame, defaultJSONParser, defineChatMiddleware, defineInterrupt, defineRunStore, detectImageMimeType, digestInterruptJson, embed, encodeWsFrame, extendAdapter, firstSentence, fromSpecTokenUsage, generateAudio, generateImage, generateMessageId, generateSpeech, generateTranscription, generateVideo, generationParamsFromBody, generationParamsFromRequest, genericInterruptContinuationFromDescriptor, getChunkRunId, getChunkThreadId, getDetachableRun, getProviderExecutedMetadata, getRunDetached, getVideoJobStatus, hashSchemaInput, interruptItemError, isCancelRequestedReason, isContentPart, isContentPartArray, isCustomEvent, isProviderExecutedToolCall, isRunStatus, isStandardSchema, isTerminalRunStatus, maxIterations, memoryStream, mergeAgentTools, mergeMetadata, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeApprovalSchema, normalizeStreamChunk, normalizeSystemPrompts, normalizeToUIMessage, normalizeToolResult, parsePartialJSON, parseWithStandardSchema, provideDetachableRun, provideRunDetached, readGenericInterruptContinuation, readInterruptBinding, readUnopenedInterruptBinding, realtimeToken, renderLazyCatalogEntry, replayRunStream, requestRunCancel, requireTextOnlyEmbeddingInput, rerank, resolveEmbeddingInput, resolveMediaPrompt, resolveResumeRunId, resumeHttpResponse, resumeServerSentEventsResponse, resumeWebSocketResponse, resumeWebSocketStream, streamToText, summarize, toHttpResponse, toHttpStream, toServerSentEventsResponse, toServerSentEventsStream, toSpecTokenUsage, toWebSocketResponse, toWebSocketStream, toolDefinition, uiMessageToModelMessages, uiMessagesToWire, untilFinishReason, validateInterruptResumeBatch, validateWithStandardSchema, wasCancelRequested, withInterruptBinding, withTanstackMetadata, withoutInterruptBinding, wrapGenericInterruptContinuation };
+export { BaseRerankAdapter, BatchStrategy, CUSTOM_EVENT, CompositeStrategy, ConsoleLogger, DISCOVERY_TOOL_NAME, DetachableRunCapability, DuplicateToolNameError, EventType, INTERRUPT_BINDING_METADATA_KEY, INTERRUPT_BINDING_VERSION, INTERRUPT_BOUNDARY_PHASES, INTERRUPT_CONTINUATION_METADATA_KEY, INTERRUPT_CONTINUATION_VERSION, INTERRUPT_PAYLOAD_METADATA_KEY, INTERRUPT_TOOL_RESUMES, ImmediateStrategy, InMemoryRunStore, InterruptResumeValidationError, MCPDuplicateToolNameError, MetadataCapability, PartialJSONParser, PunctuationStrategy, RUN_ACCEPTED_EVENT, RUN_CANCEL_REASON, RunDetachedCapability, SkillLimitError, StandardSchemaValidationError, StreamProcessor, ToolCallManager, WordBoundaryStrategy, brandProviderTool, buildBaseUsage, canonicalInterruptJson, canonicalizeInterruptResolutions, chat, chatParamsFromRequest, chatParamsFromRequestBody, cloneAndDeepFreezeJson, combineStrategies, convertMessagesToModelMessages, convertSchemaToJsonSchema, countEmbeddingInputModalities, createAudioOptions, createCapability, createChatMiddleware, createChatOptions, createEmbedOptions, createFrozenRegistry, createImageOptions, createInterruptBinding, createModel, createRealtimeEventEmitter, createReplayStream, createRerankOptions, createSpeechOptions, createSummarizeOptions, createToolRegistry, createTranscriptionOptions, createVideoOptions, decodeWsFrame, defaultJSONParser, defineChatMiddleware, defineInterrupt, defineRunStore, detectImageMimeType, digestInterruptJson, embed, encodeWsFrame, extendAdapter, firstSentence, fromSpecTokenUsage, generateAudio, generateImage, generateMessageId, generateSpeech, generateTranscription, generateVideo, generationParamsFromBody, generationParamsFromRequest, genericInterruptContinuationFromDescriptor, getChunkRunId, getChunkThreadId, getDetachableRun, getMetadata, getProviderExecutedMetadata, getRunDetached, getVideoJobStatus, hashSchemaInput, interruptItemError, isCancelRequestedReason, isContentPart, isContentPartArray, isCustomEvent, isProviderExecutedToolCall, isRunStatus, isStandardSchema, isTerminalRunStatus, maxIterations, memoryStream, mergeAgentTools, mergeMetadata, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeApprovalSchema, normalizeStreamChunk, normalizeSystemPrompts, normalizeToUIMessage, normalizeToolResult, parsePartialJSON, parseWithStandardSchema, provideDetachableRun, provideMetadata, provideRunDetached, readGenericInterruptContinuation, readInterruptBinding, readUnopenedInterruptBinding, realtimeToken, renderLazyCatalogEntry, replayRunStream, requestRunCancel, requireTextOnlyEmbeddingInput, rerank, resolveEmbeddingInput, resolveMediaPrompt, resolveResumeRunId, resumeHttpResponse, resumeServerSentEventsResponse, resumeWebSocketResponse, resumeWebSocketStream, streamToText, summarize, toHttpResponse, toHttpStream, toServerSentEventsResponse, toServerSentEventsStream, toSpecTokenUsage, toWebSocketResponse, toWebSocketStream, toolDefinition, uiMessageToModelMessages, uiMessagesToWire, untilFinishReason, validateInterruptResumeBatch, validateWithStandardSchema, wasCancelRequested, withInterruptBinding, withTanstackMetadata, withoutInterruptBinding, wrapGenericInterruptContinuation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.51.0",
+  "version": "0.52.1",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -88,7 +88,7 @@
     "@ag-ui/core": "0.1.1-canary.beta.0",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "^0.11.1",
+    "@tanstack/ai-event-client": "^0.11.2",
     "@tanstack/ai-utils": "^0.4.0"
   },
   "peerDependencies": {

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

@@ -521,23 +521,26 @@ const { jobId } = await generateVideo({
 // (x-goog-api-key header or ?key= query parameter).
 ```
 
-Gemini Omni Flash (`geminiVideo('gemini-omni-flash-preview')`) is served by
+Gemini Omni Flash (`geminiVideo('gemini-omni-1.1-flash')`) is served by
 the Interactions API instead of Veo's operations flow — same adapter, routed
-by model. Clips are 720p; `duration` is any number of seconds in the 3–10
+by model. `duration` is any number of seconds in the 3–10
 range (fractional ok, default 10 — availableDurations() reports the range),
-`size` is the aspect ratio (`'16:9' | '9:16'`), and the finished video arrives
+`size` is an `aspectRatio_resolution` template (`'16:9'` or `'16:9_1080p'`;
+suffix `'360p' | '720p' | '1080p' | '4k'`, default 720p), and the finished video arrives
 **inline** as a `data:video/mp4;base64,…` URL (no key needed to use it).
 Image/video prompt parts are sent as interaction content blocks, grouped
 as images, then videos, then text (no
 `metadata.role` routing); `data` sources go inline, `url` sources pass
 through as-is (never downloaded — use Gemini Files API URIs for remote
 media). For conversational editing, pass a prior generation's `jobId` as
-`modelOptions.previous_interaction_id` with a prompt describing the change:
+`modelOptions.previous_interaction_id` with a prompt describing the change.
+`gemini-omni-flash-preview` remains a deprecated alias until it shuts down
+on 2026-09-30.
 
 ```typescript
 import { geminiVideo } from '@tanstack/ai-gemini'
 
-const omni = geminiVideo('gemini-omni-flash-preview')
+const omni = geminiVideo('gemini-omni-1.1-flash')
 const first = await generateVideo({
   adapter: omni,
   prompt: 'A violinist outdoors',

package/src/activities/chat/index.ts

@@ -788,6 +788,7 @@ class TextEngine<
   private readonly effectiveSignal?: AbortSignal
 
   private messages: Array<ModelMessage>
+  private providerMessages: Array<ModelMessage>
   private iterationCount = 0
   /** Cumulative tool calls counted in this run (emitted + pending resume). */
   private toolCallCount = 0
@@ -845,6 +846,9 @@ class TextEngine<
   >
   private readonly middlewareCtx: ChatMiddlewareContext<TContext>
   private readonly sandboxFileQueue: Array<StreamChunk> = []
+  private readonly middlewareCustomQueue: Array<StreamChunk> = []
+  private middlewareCustomWaiters: Array<() => void> = []
+  private drainingMiddlewareCustom = false
   private readonly deferredPromises: Array<Promise<unknown>> = []
   private abortReason?: string
   private readonly middlewareAbortController?: AbortController
@@ -935,6 +939,7 @@ class TextEngine<
     // Convert messages to ModelMessage format (handles both UIMessage and ModelMessage input)
     // This ensures consistent internal format regardless of what the client sends
     this.messages = convertMessagesToModelMessages(config.params.messages)
+    this.providerMessages = this.messages
 
     // Initialize lazy tool manager after messages are converted (needs message history for scanning)
     assertUniqueToolNames(config.params.tools || [])
@@ -993,6 +998,14 @@ class TextEngine<
         this.abortReason = reason
         this.middlewareAbortController?.abort(reason)
       },
+      emitCustomEvent: (name, value) => {
+        this.middlewareCustomQueue.push(
+          this.createCustomEventChunk(name, value),
+        )
+        const waiters = this.middlewareCustomWaiters
+        this.middlewareCustomWaiters = []
+        for (const waiter of waiters) waiter()
+      },
       context: config.context as TContext,
       defer: (promise: Promise<unknown>) => {
         this.deferredPromises.push(promise)
@@ -1128,21 +1141,24 @@ class TextEngine<
 
     try {
       // Provision capabilities before any consumer (onConfig onward) can read them
-      await this.middlewareRunner.runSetup(this.middlewareCtx)
+      yield* this.runWhileYielding(
+        this.middlewareRunner.runSetup(this.middlewareCtx),
+      )
 
       // Run initial onConfig (phase = init)
       this.middlewareCtx.phase = 'init'
       const initialConfig = this.buildMiddlewareConfig()
-      const transformedConfig = await this.middlewareRunner.runOnConfig(
-        this.middlewareCtx,
-        initialConfig,
+      const transformedConfig = yield* this.runWhileYielding(
+        this.middlewareRunner.runOnConfig(this.middlewareCtx, initialConfig),
       )
       this.applyMiddlewareConfig(transformedConfig)
       await this.applyEphemeralInterruptResume(transformedConfig)
       await this.applyDurableGenericInterruptResolution()
 
       // Run onStart (devtools middleware emits text:request:started and initial messages here)
-      await this.middlewareRunner.runOnStart(this.middlewareCtx)
+      yield* this.runWhileYielding(
+        this.middlewareRunner.runOnStart(this.middlewareCtx),
+      )
 
       if (this.earlyTermination) {
         yield* this.emitSuccessfulEarlyTermination()
@@ -1189,18 +1205,16 @@ class TextEngine<
             iteration: this.middlewareCtx.iteration,
           })
 
-          await this.beginCycle()
+          yield* this.runWhileYielding(this.beginCycle())
 
           if (this.cyclePhase === 'processText') {
             // Run onConfig before each model call (phase = beforeModel)
             this.middlewareCtx.phase = 'beforeModel'
             this.middlewareCtx.iteration = this.iterationCount
             const iterConfig = this.buildMiddlewareConfig()
-            const iterTransformedConfig =
-              await this.middlewareRunner.runOnConfig(
-                this.middlewareCtx,
-                iterConfig,
-              )
+            const iterTransformedConfig = yield* this.runWhileYielding(
+              this.middlewareRunner.runOnConfig(this.middlewareCtx, iterConfig),
+            )
             this.applyMiddlewareConfig(iterTransformedConfig)
 
             if (
@@ -1239,7 +1253,7 @@ class TextEngine<
           }
 
           this.endCycle()
-        } while (await this.shouldContinue())
+        } while (yield* this.runWhileYielding(this.shouldContinue()))
       }
 
       this.logger.agentLoop('run finished', {
@@ -1497,7 +1511,7 @@ class TextEngine<
 
     for await (const raw of this.adapter.chatStream({
       model: this.params.model,
-      messages: this.messages,
+      messages: this.providerMessages,
       tools: toolsWithJsonSchemas,
       metadata,
       request: this.effectiveRequest,
@@ -1632,6 +1646,7 @@ class TextEngine<
             continue
           }
           if (spec.type === EventType.RUN_STARTED) {
+            if (this.hasPublicRunStarted) continue
             this.hasPublicRunStarted = true
           }
           this.logger.output(`type=${spec.type}`, { chunk: spec })
@@ -1646,6 +1661,7 @@ class TextEngine<
 
       // Drain any sandbox.file events emitted while processing this chunk.
       yield* this.drainSandboxFileQueue()
+      yield* this.drainMiddlewareCustomQueue()
 
       if (this.earlyTermination) {
         break
@@ -1654,6 +1670,7 @@ class TextEngine<
 
     // Drain any remaining sandbox.file events emitted after the stream ended.
     yield* this.drainSandboxFileQueue()
+    yield* this.drainMiddlewareCustomQueue()
   }
 
   private handleStreamChunk(chunk: AdapterYieldChunk): void {
@@ -2047,12 +2064,14 @@ class TextEngine<
     const allResults = [...executionResult.results, ...deferredErrorResults]
 
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
-    await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
-      toolCalls: pendingToolCalls,
-      results: allResults,
-      needsApproval: executionResult.needsApproval,
-      needsClientExecution: executionResult.needsClientExecution,
-    })
+    yield* this.runWhileYielding(
+      this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+        toolCalls: pendingToolCalls,
+        results: allResults,
+        needsApproval: executionResult.needsApproval,
+        needsClientExecution: executionResult.needsClientExecution,
+      }),
+    )
 
     if (
       executionResult.needsApproval.length > 0 ||
@@ -2228,23 +2247,26 @@ class TextEngine<
     const allResults = [...executionResult.results, ...deferredErrorResults]
 
     // Notify middleware of tool phase completion (devtools emits aggregate events here)
-    await this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
-      toolCalls,
-      results: allResults,
-      needsApproval: executionResult.needsApproval,
-      needsClientExecution: executionResult.needsClientExecution,
-    })
+    yield* this.runWhileYielding(
+      this.middlewareRunner.runOnToolPhaseComplete(this.middlewareCtx, {
+        toolCalls,
+        results: allResults,
+        needsApproval: executionResult.needsApproval,
+        needsClientExecution: executionResult.needsClientExecution,
+      }),
+    )
 
     const afterToolBoundaryChunks = this.buildToolResultChunks(
       allResults,
       finishEvent,
     )
-    const afterToolRequests =
-      await this.middlewareRunner.runOnInterruptBoundary(
+    const afterToolRequests = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnInterruptBoundary(
         this.middlewareCtx as ChatMiddlewareContext<TContext> & {
           phase: 'afterTools'
         },
-      )
+      ),
+    )
     if (afterToolRequests.length > 0) {
       for (const chunk of afterToolBoundaryChunks) {
         yield* this.pipeThroughMiddleware(chunk)
@@ -2924,10 +2946,12 @@ class TextEngine<
     this.middlewareCtx.phase = phase
     const boundaryRequests =
       requests ??
-      (await this.middlewareRunner.runOnInterruptBoundary(
-        this.middlewareCtx as ChatMiddlewareContext<TContext> & {
-          phase: typeof phase
-        },
+      (yield* this.runWhileYielding(
+        this.middlewareRunner.runOnInterruptBoundary(
+          this.middlewareCtx as ChatMiddlewareContext<TContext> & {
+            phase: typeof phase
+          },
+        ),
       ))
     if (boundaryRequests.length === 0) return false
     for (const request of boundaryRequests) {
@@ -3445,9 +3469,11 @@ class TextEngine<
     }
 
     // 1) onStructuredOutputConfig — middleware can transform messages, options, outputSchema
-    structuredConfig = await this.middlewareRunner.runOnStructuredOutputConfig(
-      this.middlewareCtx,
-      structuredConfig,
+    structuredConfig = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnStructuredOutputConfig(
+        this.middlewareCtx,
+        structuredConfig,
+      ),
     )
 
     // 2) onConfig — phase-aware general-purpose middleware re-runs at the
@@ -3456,9 +3482,11 @@ class TextEngine<
     // call — same constraint applies — but the view is consistent with the
     // ChatMiddlewareConfig shape).
     const { outputSchema: pinnedSchema, ...chatConfigSlice } = structuredConfig
-    const postOnConfig = await this.middlewareRunner.runOnConfig(
-      this.middlewareCtx,
-      { ...chatConfigSlice, tools: baseConfig.tools },
+    const postOnConfig = yield* this.runWhileYielding(
+      this.middlewareRunner.runOnConfig(this.middlewareCtx, {
+        ...chatConfigSlice,
+        tools: baseConfig.tools,
+      }),
     )
 
     // Apply merged config back to engine state
@@ -3470,7 +3498,7 @@ class TextEngine<
     const structuredCallOptions = {
       chatOptions: {
         model: this.params.model,
-        messages: this.messages,
+        messages: this.providerMessages,
         metadata: postOnConfig.metadata,
         modelOptions: postOnConfig.modelOptions,
         systemPrompts: postOnConfig.systemPrompts,
@@ -3949,6 +3977,7 @@ class TextEngine<
   private buildMiddlewareConfig(): ChatMiddlewareConfig {
     return {
       messages: this.messages,
+      providerMessages: this.messages,
       systemPrompts: [...this.systemPrompts],
       tools: [...this.tools],
       resume: this.params.resume,
@@ -4367,6 +4396,7 @@ class TextEngine<
   private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
     this.applyResumeToolState(config.resumeToolState)
     this.messages = config.messages
+    this.providerMessages = config.providerMessages ?? config.messages
     this.systemPrompts = config.systemPrompts
     assertUniqueToolNames(config.tools)
     this.tools = config.tools
@@ -4399,6 +4429,7 @@ class TextEngine<
       for (const spec of normalizeStreamChunk(output as AdapterYieldChunk)) {
         restorePublicUsage(spec)
         if (spec.type === EventType.RUN_STARTED) {
+          if (this.hasPublicRunStarted) continue
           this.hasPublicRunStarted = true
         }
         yield spec
@@ -4419,6 +4450,69 @@ class TextEngine<
       chunk,
     )
     yield* this.emitPublicChunks(afterMw)
+    if (!this.drainingMiddlewareCustom) {
+      yield* this.drainMiddlewareCustomQueue()
+    }
+  }
+
+  /**
+   * Drain CUSTOM chunks pushed by `ctx.emitCustomEvent` through middleware
+   * and into the public stream. If the run has not yet sent `RUN_STARTED`,
+   * emit that first so CUSTOM events are not the first wire event.
+   */
+  private async *drainMiddlewareCustomQueue(): AsyncGenerator<StreamChunk> {
+    if (this.drainingMiddlewareCustom) return
+    if (this.middlewareCustomQueue.length === 0) return
+    this.drainingMiddlewareCustom = true
+    try {
+      yield* this.emitSyntheticRunStarted(this.createSyntheticFinishedEvent())
+      while (this.middlewareCustomQueue.length > 0) {
+        const chunk = this.middlewareCustomQueue.shift()
+        if (chunk) yield* this.pipeThroughMiddleware(chunk)
+      }
+    } finally {
+      this.drainingMiddlewareCustom = false
+    }
+  }
+
+  /**
+   * Await `work` while yielding any `emitCustomEvent` chunks as they arrive.
+   */
+  private async *runWhileYielding<T>(
+    work: Promise<T>,
+  ): AsyncGenerator<StreamChunk, T> {
+    let settled = false
+    let result: T | undefined
+    let error: unknown
+    const done = work.then(
+      (value) => {
+        settled = true
+        result = value
+      },
+      (err: unknown) => {
+        settled = true
+        error = err
+      },
+    )
+
+    while (!settled) {
+      yield* this.drainMiddlewareCustomQueue()
+      if (settled) break
+      await Promise.race([
+        done,
+        new Promise<void>((resolve) => {
+          if (this.middlewareCustomQueue.length > 0) {
+            resolve()
+            return
+          }
+          this.middlewareCustomWaiters.push(resolve)
+        }),
+      ])
+    }
+
+    yield* this.drainMiddlewareCustomQueue()
+    if (error !== undefined) throw error
+    return result as T
   }
 
   /**
@@ -4455,17 +4549,18 @@ class TextEngine<
     },
     void
   > {
-    let next = await generator.next()
-    while (!next.done) {
+    let pending = generator.next()
+    while (true) {
+      const next = yield* this.runWhileYielding(pending)
+      if (next.done) return next.value
       yield* this.pipeThroughMiddleware(next.value)
-      next = await generator.next()
+      pending = generator.next()
     }
-    return next.value
   }
 
   private createCustomEventChunk(
     eventName: string,
-    value: Record<string, any>,
+    value: Record<string, unknown>,
   ): CustomEvent {
     return {
       type: EventType.CUSTOM,

package/src/activities/chat/middleware/compose.ts

@@ -166,7 +166,13 @@ export class MiddlewareRunner<
         const result = await mw.onConfig(ctx, current)
         const hasTransform = result !== undefined && result !== null
         if (hasTransform) {
-          current = { ...current, ...result }
+          current = {
+            ...current,
+            ...result,
+            ...('messages' in result && !('providerMessages' in result)
+              ? { providerMessages: result.messages }
+              : {}),
+          }
           if (!skip) {
             this.logger.config(
               `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,
@@ -221,7 +227,13 @@ export class MiddlewareRunner<
         const result = await mw.onStructuredOutputConfig(ctx, current)
         const hasTransform = result !== undefined && result !== null
         if (hasTransform) {
-          current = { ...current, ...result }
+          current = {
+            ...current,
+            ...result,
+            ...('messages' in result && !('providerMessages' in result)
+              ? { providerMessages: result.messages }
+              : {}),
+          }
           if (!skip) {
             this.logger.config(
               `middleware=${mw.name ?? 'unnamed'} keys=${Object.keys(result).join(',')}`,