@tanstack/ai 0.33.0 → 0.34.0

package/dist/esm/activities/chat/tools/schema-converter.d.ts

@@ -1,4 +1,5 @@
 import { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+import { NullWideningMap } from '@tanstack/ai-utils';
 import { JSONSchema, SchemaInput } from '../../../types.js';
 /**
  * Check if a value is a Standard JSON Schema compliant schema.
@@ -86,6 +87,18 @@ export interface ConvertSchemaOptions {
  * ```
  */
 export declare function convertSchemaToJsonSchema(schema: SchemaInput | undefined, options?: ConvertSchemaOptions): JSONSchema | undefined;
+/**
+ * Convert a schema for structured output AND capture the {@link NullWideningMap}
+ * recording every `null` the strict-mode widening synthesized. The map lets the
+ * caller undo that widening on the provider's response (via `undoNullWidening`)
+ * before validating against the original schema — optional fields read back as
+ * absent while genuine `.nullable()` nulls survive. The map is `undefined` when
+ * the schema isn't a widenable object or when no field needed widening.
+ */
+export declare function convertSchemaForStructuredOutput(schema: SchemaInput | undefined): {
+    jsonSchema: JSONSchema | undefined;
+    nullWideningMap: NullWideningMap | undefined;
+};
 /**
  * Validates data against a Standard Schema compliant schema.
  *

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

@@ -20,74 +20,84 @@ function isStandardJSONSchema(schema) {
 function isStandardSchema(schema) {
   return isPropertyCarrier(schema) && "~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"] !== null && "version" in schema["~standard"] && schema["~standard"].version === 1 && "validate" in schema["~standard"] && typeof schema["~standard"].validate === "function";
 }
+function pruneMap(map) {
+  return Object.keys(map).length > 0 ? map : void 0;
+}
 function makeStructuredOutputCompatible(schema, originalRequired = []) {
   const result = { ...schema };
+  const map = {};
   if (result.type === "object" && result.properties) {
     const properties = { ...result.properties };
     const allPropertyNames = Object.keys(properties);
+    const propertyMaps = {};
     for (const propName of allPropertyNames) {
       const prop = properties[propName];
       if (!prop) continue;
       const wasOptional = !originalRequired.includes(propName);
+      let widenedHere = false;
+      let childMap;
       if (prop.type === "object" && prop.properties) {
-        const transformed = makeStructuredOutputCompatible(
-          prop,
-          prop.required || []
-        );
-        properties[propName] = wasOptional ? { ...transformed, type: ["object", "null"] } : transformed;
+        const nested = makeStructuredOutputCompatible(prop, prop.required || []);
+        properties[propName] = wasOptional ? { ...nested.schema, type: ["object", "null"] } : nested.schema;
+        widenedHere = wasOptional;
+        childMap = nested.nullWidening;
       } else if (prop.type === "array" && prop.items) {
         const items = Array.isArray(prop.items) ? prop.items[0] : prop.items;
-        const transformed = {
+        const nestedItems = items ? makeStructuredOutputCompatible(items, items.required || []) : void 0;
+        properties[propName] = {
           ...prop,
-          items: items ? makeStructuredOutputCompatible(items, items.required || []) : prop.items
+          items: nestedItems ? nestedItems.schema : prop.items,
+          ...wasOptional ? { type: ["array", "null"] } : {}
         };
-        properties[propName] = wasOptional ? { ...transformed, type: ["array", "null"] } : transformed;
+        widenedHere = wasOptional;
+        childMap = nestedItems?.nullWidening ? { items: nestedItems.nullWidening } : void 0;
       } else if (wasOptional) {
         if (prop.type && !Array.isArray(prop.type)) {
-          properties[propName] = {
-            ...prop,
-            type: [prop.type, "null"]
-          };
+          properties[propName] = { ...prop, type: [prop.type, "null"] };
+          widenedHere = true;
         } else if (Array.isArray(prop.type) && !prop.type.includes("null")) {
-          properties[propName] = {
-            ...prop,
-            type: [...prop.type, "null"]
-          };
+          properties[propName] = { ...prop, type: [...prop.type, "null"] };
+          widenedHere = true;
         }
       }
+      if (widenedHere || childMap) {
+        propertyMaps[propName] = {
+          ...childMap ?? {},
+          ...widenedHere ? { widened: true } : {}
+        };
+      }
     }
     result.properties = properties;
     result.required = allPropertyNames;
     result.additionalProperties = false;
+    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) {
-      result.items = makeStructuredOutputCompatible(items, items.required || []);
+      const nestedItems = makeStructuredOutputCompatible(
+        items,
+        items.required || []
+      );
+      result.items = nestedItems.schema;
+      if (nestedItems.nullWidening) map.items = nestedItems.nullWidening;
     }
   }
-  return result;
+  return { schema: result, nullWidening: pruneMap(map) };
 }
-function convertSchemaToJsonSchema(schema, options = {}) {
-  if (!schema) return void 0;
-  const { forStructuredOutput = false } = options;
+function toTypedJsonSchema(schema) {
   if (isStandardJSONSchema(schema)) {
     const jsonSchema = schema["~standard"].jsonSchema.input({
       target: "draft-07"
     });
-    let result = toJsonSchema(jsonSchema);
-    if ("properties" in result && !result.type) {
-      result.type = "object";
-    }
+    const result = toJsonSchema(jsonSchema);
+    if ("properties" in result && !result.type) result.type = "object";
     if (result.type === "object" && !("properties" in result)) {
       result.properties = {};
     }
     if (result.type === "object" && !("required" in result)) {
       result.required = [];
     }
-    if (forStructuredOutput) {
-      result = makeStructuredOutputCompatible(result, result.required || []);
-    }
     return result;
   }
   if (isStandardSchema(schema)) {
@@ -95,14 +105,31 @@ function convertSchemaToJsonSchema(schema, options = {}) {
       "Schema is a Standard Schema validator but does not expose a JSON Schema converter on `~standard.jsonSchema`. Use Zod v4.2+, ArkType v2.1.28+, or wrap a Valibot schema with `toStandardJsonSchema()` from `@valibot/to-json-schema` before passing it as `outputSchema`."
     );
   }
-  if (typeof schema !== "object") {
+  if (typeof schema !== "object") return schema;
+  return toJsonSchema(schema);
+}
+function convertSchemaToJsonSchema(schema, options = {}) {
+  if (!schema) return void 0;
+  const { forStructuredOutput = false } = options;
+  if (!forStructuredOutput && !isStandardJSONSchema(schema) && !isStandardSchema(schema)) {
     return schema;
   }
-  if (forStructuredOutput) {
-    const typedView = toJsonSchema(schema);
-    return makeStructuredOutputCompatible(typedView, typedView.required || []);
+  const base = toTypedJsonSchema(schema);
+  if (!base || typeof base !== "object") return base;
+  if (!forStructuredOutput) return base;
+  return makeStructuredOutputCompatible(base, base.required || []).schema;
+}
+function convertSchemaForStructuredOutput(schema) {
+  if (!schema) return { jsonSchema: void 0, nullWideningMap: void 0 };
+  const base = toTypedJsonSchema(schema);
+  if (!base || typeof base !== "object") {
+    return { jsonSchema: base, nullWideningMap: void 0 };
   }
-  return schema;
+  const { schema: jsonSchema, nullWidening } = makeStructuredOutputCompatible(
+    base,
+    base.required || []
+  );
+  return { jsonSchema, nullWideningMap: nullWidening };
 }
 class StandardSchemaValidationError extends Error {
   name = "StandardSchemaValidationError";
@@ -131,6 +158,7 @@ function parseWithStandardSchema(schema, data) {
 }
 export {
   StandardSchemaValidationError,
+  convertSchemaForStructuredOutput,
   convertSchemaToJsonSchema,
   isStandardJSONSchema,
   isStandardSchema,

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

@@ -1 +1 @@
-{"version":3,"file":"schema-converter.js","sources":["../../../../../src/activities/chat/tools/schema-converter.ts"],"sourcesContent":["import type {\n  StandardJSONSchemaV1,\n  StandardSchemaV1,\n} from '@standard-schema/spec'\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 * 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 * @param schema - JSON schema to transform\n * @param originalRequired - Original required array (to know which fields were optional)\n * @returns Transformed schema compatible with OpenAI structured output\n */\nfunction makeStructuredOutputCompatible(\n  schema: JSONSchema,\n  originalRequired: Array<string> = [],\n): JSONSchema {\n  const result: JSONSchema = { ...schema }\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\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\n      // Recursively transform nested objects/arrays\n      if (prop.type === 'object' && prop.properties) {\n        const transformed = makeStructuredOutputCompatible(\n          prop,\n          prop.required || [],\n        )\n        properties[propName] = wasOptional\n          ? { ...transformed, type: ['object', 'null'] }\n          : transformed\n      } else if (prop.type === 'array' && prop.items) {\n        const items = Array.isArray(prop.items) ? prop.items[0] : prop.items\n        const transformed: JSONSchema = {\n          ...prop,\n          items: items\n            ? makeStructuredOutputCompatible(items, items.required || [])\n            : prop.items,\n        }\n        properties[propName] = wasOptional\n          ? { ...transformed, type: ['array', 'null'] }\n          : transformed\n      } else if (wasOptional) {\n        // Make optional fields nullable by adding null to the type\n        if (prop.type && !Array.isArray(prop.type)) {\n          properties[propName] = {\n            ...prop,\n            type: [prop.type, 'null'],\n          }\n        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {\n          properties[propName] = {\n            ...prop,\n            type: [...prop.type, 'null'],\n          }\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  }\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      result.items = makeStructuredOutputCompatible(items, items.required || [])\n    }\n  }\n\n  return result\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 * 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  // If it's a Standard JSON Schema compliant schema, use the standard interface\n  if (isStandardJSONSchema(schema)) {\n    const jsonSchema = schema['~standard'].jsonSchema.input({\n      target: 'draft-07',\n    })\n\n    // Rebuild structurally so the typed JSONSchema view is acquired without\n    // a `Record<string, unknown> as JSONSchema` cast; `toJsonSchema()` also\n    // drops the `$schema` key which LLM providers don't need.\n    let result: JSONSchema = toJsonSchema(jsonSchema)\n\n    // Ensure object schemas always have type: \"object\"\n    // If it has properties (even empty), it should be an object type\n    if ('properties' in result && !result.type) {\n      result.type = 'object'\n    }\n\n    // Ensure properties exists for object types (even if empty)\n    if (result.type === 'object' && !('properties' in result)) {\n      result.properties = {}\n    }\n\n    // Ensure required exists for object types (even if empty array)\n    if (result.type === 'object' && !('required' in result)) {\n      result.required = []\n    }\n\n    // Apply structured output transformation if requested\n    if (forStructuredOutput) {\n      result = makeStructuredOutputCompatible(result, result.required || [])\n    }\n\n    return result\n  }\n\n  // Detect Standard Schema validators (Zod, ArkType, Valibot, …) that don't\n  // expose a `~standard.jsonSchema` converter. These would otherwise fall\n  // through to the JSONSchema pass-through below and ship `{ '~standard': … }`\n  // straight to the LLM provider, producing an opaque downstream error. Fail\n  // fast with actionable guidance instead.\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 it's not a Standard JSON Schema, assume it's already a JSONSchema and pass through\n  // Still apply structured output transformation if requested\n\n  // At this branch, `schema` is the plain `JSONSchema` arm of `SchemaInput`\n  // (the two `~standard` arms were handled above). When no transformation\n  // is requested we pass the schema through by reference to preserve\n  // identity for callers that compare via `===`.\n  if (typeof schema !== 'object') {\n    // The SchemaInput union is object-shaped on every arm; if we ever hit a\n    // non-object here, propagate it untouched and let the downstream\n    // provider error loudly rather than silently widen.\n    return schema\n  }\n\n  if (forStructuredOutput) {\n    // Build a typed view structurally so we don't need a SchemaInput→JSONSchema\n    // cast on the transformation path.\n    const typedView = toJsonSchema(schema)\n    return makeStructuredOutputCompatible(typedView, typedView.required || [])\n  }\n\n  return schema\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"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-converter.js","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"],"names":[],"mappings":"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"}

package/package.json

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

package/src/activities/chat/index.ts

@@ -6,6 +6,7 @@
  */
 
 import { devtoolsMiddleware } from '@tanstack/ai-event-client'
+import { undoNullWidening } from '@tanstack/ai-utils'
 import { stripToSpecMiddleware } from '../../strip-to-spec-middleware'
 import { streamToText } from '../../stream-to-response.js'
 import { resolveDebugOption } from '../../logger/resolve'
@@ -18,6 +19,7 @@ import {
   executeToolCalls,
 } from './tools/tool-calls'
 import {
+  convertSchemaForStructuredOutput,
   convertSchemaToJsonSchema,
   isStandardSchema,
   parseWithStandardSchema,
@@ -422,11 +424,21 @@ interface TextEngineConfig<
    *   (used by runStreamingStructuredOutput). When false, chunks are
    *   consumed internally for middleware visibility but not yielded
    *   (used by runAgenticStructuredOutput).
-   * - validate: optional callback invoked AFTER the structured-output result
-   *   is captured but BEFORE the terminal hook fires. If it throws, the
-   *   engine records a `finalizationError` and fires `onError` instead of
-   *   `onFinish` (per spec §7.3). On success, the returned value is stored
-   *   as the validated result and retrievable via
+   * - normalize: optional schema-aware transform applied to the captured
+   *   structured-output object the moment it enters the engine — BEFORE it is
+   *   stored, validated, or yielded. Used to undo strict-mode null-widening
+   *   (`undoNullWidening`): strict schemas widen optional fields to
+   *   `required` + nullable so the provider returns `null` for an absent
+   *   optional, and this strips exactly those synthesized nulls while keeping
+   *   the ones a `.nullable()` field genuinely allows. Applied here (not in
+   *   the adapter) because the engine is the only layer holding the original
+   *   schema's null-widening map, and applying it at capture fixes BOTH the
+   *   streaming chunk and the Promise<T> result with one transform.
+   * - validate: optional callback invoked AFTER `normalize` and AFTER the
+   *   structured-output result is captured, but BEFORE the terminal hook
+   *   fires. If it throws, the engine records a `finalizationError` and fires
+   *   `onError` instead of `onFinish` (per spec §7.3). On success, the
+   *   returned value is stored as the validated result and retrievable via
    *   `getValidatedStructuredOutput()`. Used by `runAgenticStructuredOutput`
    *   to perform Standard Schema validation inside the engine.
    * - nativeCombined: when true, the adapter declared
@@ -441,6 +453,7 @@ interface TextEngineConfig<
   finalStructuredOutput?: {
     jsonSchema: JSONSchema
     yieldChunks: boolean
+    normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
   }
@@ -546,8 +559,8 @@ class TextEngine<
   // to carry, so the client matches it to the streaming text deltas.
   private combinedStructuredMessageId: string | null = null
   // Holds the validated value when `finalStructuredOutput.validate` is provided
-  // and succeeds. Distinct from `structuredOutputResult.data` (the raw,
-  // unvalidated payload from the structured-output.complete chunk).
+  // and succeeds. Distinct from `structuredOutputResult.data` (the normalized
+  // but unvalidated payload from the structured-output.complete chunk).
   private validatedStructuredOutput: unknown = undefined
   private hasValidatedStructuredOutput = false
   private finalizationError: {
@@ -558,6 +571,7 @@ class TextEngine<
   private readonly finalStructuredOutput?: {
     jsonSchema: JSONSchema
     yieldChunks: boolean
+    normalize?: (data: unknown) => unknown
     validate?: (data: unknown) => unknown
     nativeCombined?: boolean
   }
@@ -2087,15 +2101,29 @@ class TextEngine<
       // All narrowing below is via the discriminated-union `chunk.type`
       // — no `as` casts.
 
+      // The chunk forwarded to middleware/consumers. Replaced below only for
+      // the structured-output.complete event, whose `object` we normalize
+      // (un-widen) so streaming consumers see the same cleaned payload the
+      // Promise<T> path validates and returns.
+      let outboundChunk: StreamChunk = chunk
+
       if (
         chunk.type === EventType.CUSTOM &&
         chunk.name === 'structured-output.complete'
       ) {
         const parsed = readStructuredOutputCompleteValue(chunk.value)
         if (parsed) {
-          this.structuredOutputResult = {
-            data: parsed.object,
-            rawText: parsed.raw,
+          const object = this.finalStructuredOutput.normalize
+            ? this.finalStructuredOutput.normalize(parsed.object)
+            : parsed.object
+          this.structuredOutputResult = { data: object, rawText: parsed.raw }
+          // Rewrite the outbound event so the yielded chunk carries the
+          // normalized object (the original `chunk.value` still holds the
+          // widened one). Preserve every other field — `raw`, `reasoning` —
+          // by spreading the original value.
+          const value = chunk.value
+          if (object !== parsed.object && value && typeof value === 'object') {
+            outboundChunk = { ...chunk, value: { ...value, object } }
           }
         }
       }
@@ -2119,7 +2147,7 @@ class TextEngine<
       // 7b. Pipe through middleware
       const outputChunks = await this.middlewareRunner.runOnChunk(
         this.middlewareCtx,
-        chunk,
+        outboundChunk,
       )
 
       // 7c. Decide consumer visibility — only yieldChunks=true callers get them.
@@ -2276,7 +2304,14 @@ class TextEngine<
     } else {
       try {
         const parsed: unknown = JSON.parse(rawText)
-        this.structuredOutputResult = { data: parsed, rawText }
+        // Normalize (un-widen) before storing so the synthesized
+        // structured-output.complete chunk and the Promise<T> result both
+        // carry the cleaned payload. JSON.parse preserves provider nulls, so
+        // this is where native-combined output gets its widening undone.
+        const data = this.finalStructuredOutput.normalize
+          ? this.finalStructuredOutput.normalize(parsed)
+          : parsed
+        this.structuredOutputResult = { data, rawText }
       } catch (err: unknown) {
         const detail =
           rawText.slice(0, 200) + (rawText.length > 200 ? '...' : '')
@@ -2733,18 +2768,31 @@ async function runAgenticStructuredOutput<
 
   // Same strict-conversion as the streaming path (`forStructuredOutput: true`)
   // so the same Zod schema produces the same JSON Schema regardless of
-  // stream mode — Promise<T> and stream:true must not diverge here.
-  const jsonSchema = convertSchemaToJsonSchema(outputSchema, {
-    forStructuredOutput: true,
-  })
+  // stream mode — Promise<T> and stream:true must not diverge here. The same
+  // pass also records a `nullWideningMap`: optional fields are widened to
+  // `required` + nullable for the provider, which then returns `null` for an
+  // absent optional — a `null` the original `.optional()` (`T | undefined`)
+  // schema would otherwise reject. The map pinpoints exactly those synthesized
+  // nulls so `undoNullWidening` can drop them while preserving the ones a
+  // `.nullable()` field genuinely allows.
+  const { jsonSchema, nullWideningMap } =
+    convertSchemaForStructuredOutput(outputSchema)
   if (!jsonSchema) {
     throw new Error('Failed to convert output schema to JSON Schema')
   }
 
+  // Un-widening runs in the engine the moment the structured output is
+  // captured (`finalStructuredOutput.normalize`), so it applies uniformly to
+  // every adapter and to both stream modes — the engine is the only layer
+  // holding the schema's `nullWideningMap`. Validation then runs on the
+  // already-normalized data, so `validate` is a plain Standard Schema parse.
+  const normalize = (data: unknown): unknown =>
+    undoNullWidening(data, nullWideningMap)
+
   // Validation runs INSIDE the engine (per spec §7.3) so validation failures
   // route through the engine's terminal-hook chooser as `onError`. We pass a
   // `validate` callback when the schema is a Standard Schema; otherwise we
-  // pass through the raw data and the engine returns it unchanged.
+  // pass through the (normalized) data and the engine returns it unchanged.
   const validate = isStandardSchema(outputSchema)
     ? (data: unknown): unknown =>
         parseWithStandardSchema<InferSchemaType<TSchema>>(outputSchema, data)
@@ -2776,6 +2824,7 @@ async function runAgenticStructuredOutput<
       finalStructuredOutput: {
         jsonSchema,
         yieldChunks: false,
+        normalize,
         ...(validate ? { validate } : {}),
         ...(nativeCombined ? { nativeCombined: true } : {}),
       },
@@ -2954,17 +3003,23 @@ async function* fallbackStructuredOutputStream(
  * RUN_STARTED/RUN_FINISHED are suppressed; the structured-output finalization
  * step's pair brackets the run for the consumer.
  *
- * Schema validation is intentionally NOT run on this path — it is the
- * consumer's responsibility. The `structured-output.complete` CUSTOM event
- * is forwarded with the adapter-produced `value.object` as-is. This is a
- * deliberate asymmetry vs. `runAgenticStructuredOutput` (Promise<T> path),
- * which DOES run Standard Schema validation inside the engine and routes
- * validation failures through `onError`. The reason for the asymmetry:
+ * Standard Schema *validation* is intentionally NOT run on this path — it is
+ * the consumer's responsibility. This is a deliberate asymmetry vs.
+ * `runAgenticStructuredOutput` (Promise<T> path), which DOES validate inside
+ * the engine and routes validation failures through `onError`. The reason:
  * streaming consumers typically render partial JSON progressively (via
  * `parsePartialJSON` or `useChat`'s `partial` slot) and validate downstream
  * after assembly. Running validation server-side would force a hard error
  * on partial-by-design payloads. See `docs/structured-outputs/overview.md`.
  *
+ * Null-widening normalization, however, IS run on both paths: the
+ * `structured-output.complete` CUSTOM event is forwarded with its `value.object`
+ * already un-widened (synthesized strict-mode nulls dropped, genuine
+ * `.nullable()` nulls kept), so a consumer validating the assembled object
+ * against the original schema doesn't choke on a `null` for an `.optional()`
+ * field. Same `convertSchemaForStructuredOutput` pass and same
+ * `undoNullWidening` map as the Promise<T> path — the two must not diverge.
+ *
  * Pre-flight validation (missing schema, unconvertible schema) throws
  * synchronously at call time rather than as a yielded RUN_ERROR mid-stream —
  * those are programmer errors, not runtime conditions.
@@ -2982,14 +3037,17 @@ function runStreamingStructuredOutput<
   }
 
   // forStructuredOutput strict-converts the schema once at the activity
-  // boundary. Adapters can re-convert if their wire format diverges, but the
-  // default flow hands them a strict-ready schema.
-  const jsonSchema = convertSchemaToJsonSchema(outputSchema, {
-    forStructuredOutput: true,
-  })
+  // boundary, capturing the null-widening map so the engine can un-widen the
+  // provider's response before it reaches the consumer. Adapters can re-convert
+  // if their wire format diverges, but the default flow hands them a
+  // strict-ready schema.
+  const { jsonSchema, nullWideningMap } =
+    convertSchemaForStructuredOutput(outputSchema)
   if (!jsonSchema) {
     throw new Error('Failed to convert output schema to JSON Schema')
   }
+  const normalize = (data: unknown): unknown =>
+    undoNullWidening(data, nullWideningMap)
 
   // The implementation generator yields the broader internal type
   // (`StreamChunk | StructuredOutputCompleteEvent<T>`) so agent-loop
@@ -3000,6 +3058,7 @@ function runStreamingStructuredOutput<
   return runStreamingStructuredOutputImpl(
     options,
     jsonSchema,
+    normalize,
   ) as StructuredOutputStream<InferSchemaType<TSchema>>
 }
 
@@ -3025,6 +3084,7 @@ async function* runStreamingStructuredOutputImpl<
 >(
   options: TextActivityOptions<AnyTextAdapter, TSchema, true, TContext>,
   jsonSchema: NonNullable<ReturnType<typeof convertSchemaToJsonSchema>>,
+  normalize: (data: unknown) => unknown,
 ): StructuredOutputStreamInternal<InferSchemaType<TSchema>> {
   const {
     adapter,
@@ -3069,6 +3129,7 @@ async function* runStreamingStructuredOutputImpl<
       finalStructuredOutput: {
         jsonSchema,
         yieldChunks: true,
+        normalize,
         ...(nativeCombined ? { nativeCombined: true } : {}),
       },
     },
@@ -3083,9 +3144,10 @@ async function* runStreamingStructuredOutputImpl<
     await mcpManager.dispose()
   }
 
-  // Schema validation for the streaming variant remains the consumer's
-  // responsibility — they read the CUSTOM 'structured-output.complete' from
-  // the yielded stream. Matches pre-fix behavior.
+  // Standard Schema validation for the streaming variant remains the
+  // consumer's responsibility — they read the CUSTOM 'structured-output.complete'
+  // from the yielded stream. (Null-widening normalization, by contrast, already
+  // ran inside the engine via `normalize`, so the object they read is un-widened.)
   void outputSchema
 }