@tanstack/ai 0.42.0 → 0.43.0

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

@@ -1,167 +1,314 @@
+//#region src/activities/chat/tools/schema-converter.ts
+/**
+* Build a JSONSchema object from any plain key/value source. The `JSONSchema`
+* interface's `[key: string]: any` index signature makes every property
+* assignable through bracket access without a type cast — copying keys here
+* lets us narrow either `Record<string, unknown>` (returned by
+* `~standard.jsonSchema.input()`) or a `JSONSchema` (from the SchemaInput
+* pass-through arm) into the typed view used by the rest of this module.
+*
+* Accepts `object` so callers don't need a cast when narrowing from union
+* types like `SchemaInput`.
+*/
 function toJsonSchema(obj) {
-  const result = {};
-  for (const [key, value] of Object.entries(obj)) {
-    if (key === "$schema") continue;
-    result[key] = value;
-  }
-  return result;
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (key === "$schema") continue;
+		result[key] = value;
+	}
+	return result;
 }
+/**
+* Whether a value can carry a `~standard` property. Most schema libraries
+* (Zod, Valibot) return plain objects, but ArkType's `type()` returns a
+* *callable function* with `~standard` attached — so `typeof` must accept
+* both `'object'` and `'function'` or ArkType schemas are missed entirely
+* (issue #276).
+*/
 function isPropertyCarrier(schema) {
-  return (typeof schema === "object" || typeof schema === "function") && schema !== null;
+	return (typeof schema === "object" || typeof schema === "function") && schema !== null;
 }
+/**
+* Check if a value is a Standard JSON Schema compliant schema.
+* Standard JSON Schema compliant libraries (Zod v4+, ArkType, Valibot with toStandardJsonSchema, etc.)
+* implement the '~standard' property with jsonSchema converter methods.
+*/
 function isStandardJSONSchema(schema) {
-  if (!isPropertyCarrier(schema) || !("~standard" in schema)) return false;
-  const standard = schema["~standard"];
-  if (typeof standard !== "object" || standard === null || !("version" in standard) || standard.version !== 1 || !("jsonSchema" in standard) || typeof standard.jsonSchema !== "object" || standard.jsonSchema === null || !("input" in standard.jsonSchema)) {
-    return false;
-  }
-  return typeof standard.jsonSchema.input === "function";
+	if (!isPropertyCarrier(schema) || !("~standard" in schema)) return false;
+	const standard = schema["~standard"];
+	if (typeof standard !== "object" || standard === null || !("version" in standard) || standard.version !== 1 || !("jsonSchema" in standard) || typeof standard.jsonSchema !== "object" || standard.jsonSchema === null || !("input" in standard.jsonSchema)) return false;
+	return typeof standard.jsonSchema.input === "function";
 }
+/**
+* Check if a value is a Standard Schema compliant schema (for validation).
+* Standard Schema compliant libraries implement the '~standard' property with a validate function.
+*/
 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";
+	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";
 }
+/** Drop an empty map to `undefined` so leaf/no-op subtrees don't litter it. */
 function pruneMap(map) {
-  return Object.keys(map).length > 0 ? map : void 0;
+	return Object.keys(map).length > 0 ? map : void 0;
 }
+/**
+* Transform a JSON schema to be compatible with OpenAI's structured output requirements.
+* OpenAI requires:
+* - All properties must be in the `required` array
+* - Optional fields should have null added to their type union
+* - additionalProperties must be false for objects
+*
+* Alongside the transformed schema it returns a {@link NullWideningMap} marking
+* exactly the positions where `null` was added, so `undoNullWidening` can strip
+* those synthesized nulls (and only those) from the provider's response.
+*
+* @param schema - JSON schema to transform
+* @param originalRequired - Original required array (to know which fields were optional)
+* @returns Transformed schema + the null-widening map for the round trip
+*/
 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 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 nestedItems = items ? makeStructuredOutputCompatible(items, items.required || []) : void 0;
-        properties[propName] = {
-          ...prop,
-          items: nestedItems ? nestedItems.schema : prop.items,
-          ...wasOptional ? { type: ["array", "null"] } : {}
-        };
-        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"] };
-          widenedHere = true;
-        } else if (Array.isArray(prop.type) && !prop.type.includes("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) {
-      const nestedItems = makeStructuredOutputCompatible(
-        items,
-        items.required || []
-      );
-      result.items = nestedItems.schema;
-      if (nestedItems.nullWidening) map.items = nestedItems.nullWidening;
-    }
-  }
-  return { schema: result, nullWidening: pruneMap(map) };
+	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 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 nestedItems = items ? makeStructuredOutputCompatible(items, items.required || []) : void 0;
+				properties[propName] = {
+					...prop,
+					items: nestedItems ? nestedItems.schema : prop.items,
+					...wasOptional ? { type: ["array", "null"] } : {}
+				};
+				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"]
+					};
+					widenedHere = true;
+				} else if (Array.isArray(prop.type) && !prop.type.includes("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) {
+			const nestedItems = makeStructuredOutputCompatible(items, items.required || []);
+			result.items = nestedItems.schema;
+			if (nestedItems.nullWidening) map.items = nestedItems.nullWidening;
+		}
+	}
+	return {
+		schema: result,
+		nullWidening: pruneMap(map)
+	};
 }
+/**
+* Normalize any supported schema input to a typed, UN-widened `JSONSchema` —
+* the shared first half of conversion, before any structured-output widening.
+*
+* - Standard JSON Schemas are rebuilt structurally (dropping `$schema`, which
+*   LLM providers ignore) and given the explicit `type`/`properties`/`required`
+*   defaults object shapes need downstream.
+* - Plain `JSONSchema` inputs are rebuilt into the typed view; non-object inputs
+*   are surfaced untouched (they can't be widened).
+* - Standard Schema validators lacking a `~standard.jsonSchema` converter throw
+*   with actionable guidance, rather than shipping `{ '~standard': … }` to the
+*   provider and producing an opaque downstream error.
+*/
 function toTypedJsonSchema(schema) {
-  if (isStandardJSONSchema(schema)) {
-    const jsonSchema = schema["~standard"].jsonSchema.input({
-      target: "draft-07"
-    });
-    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 = [];
-    }
-    return result;
-  }
-  if (isStandardSchema(schema)) {
-    throw new Error(
-      "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") return schema;
-  return toJsonSchema(schema);
+	if (isStandardJSONSchema(schema)) {
+		const result = toJsonSchema(schema["~standard"].jsonSchema.input({ target: "draft-07" }));
+		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 = [];
+		return result;
+	}
+	if (isStandardSchema(schema)) throw new Error("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") return schema;
+	return toJsonSchema(schema);
 }
+/**
+* Converts a Standard JSON Schema compliant schema or plain JSONSchema to JSON Schema format
+* compatible with LLM providers.
+*
+* Supports any schema library that implements the Standard JSON Schema spec (v1):
+* - Zod v4+ (natively supports StandardJSONSchemaV1)
+* - ArkType (natively supports StandardJSONSchemaV1)
+* - Valibot (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
+*
+* If the input is already a plain JSONSchema object, it is returned as-is.
+*
+* @param schema - Standard JSON Schema compliant schema or plain JSONSchema object to convert
+* @param options - Conversion options
+* @returns JSON Schema object that can be sent to LLM providers
+*
+* @example
+* ```typescript
+* // Using Zod v4+ (natively supports Standard JSON Schema)
+* import * as z from 'zod';
+*
+* const zodSchema = z.object({
+*   location: z.string().describe('City name'),
+*   unit: z.enum(['celsius', 'fahrenheit']).optional()
+* });
+*
+* const jsonSchema = convertSchemaToJsonSchema(zodSchema);
+*
+* @example
+* // Using ArkType (natively supports Standard JSON Schema)
+* import { type } from 'arktype';
+*
+* const arkSchema = type({
+*   location: 'string',
+*   unit: "'celsius' | 'fahrenheit'"
+* });
+*
+* const jsonSchema = convertSchemaToJsonSchema(arkSchema);
+*
+* @example
+* // Using Valibot (via toStandardJsonSchema)
+* import * as v from 'valibot';
+* import { toStandardJsonSchema } from '@valibot/to-json-schema';
+*
+* const valibotSchema = toStandardJsonSchema(v.object({
+*   location: v.string(),
+*   unit: v.optional(v.picklist(['celsius', 'fahrenheit']))
+* }));
+*
+* const jsonSchema = convertSchemaToJsonSchema(valibotSchema);
+*
+* @example
+* // Using JSONSchema directly (passes through unchanged)
+* const rawSchema = {
+*   type: 'object',
+*   properties: { location: { type: 'string' } },
+*   required: ['location']
+* };
+* const result = convertSchemaToJsonSchema(rawSchema);
+* ```
+*/
 function convertSchemaToJsonSchema(schema, options = {}) {
-  if (!schema) return void 0;
-  const { forStructuredOutput = false } = options;
-  if (!forStructuredOutput && !isStandardJSONSchema(schema) && !isStandardSchema(schema)) {
-    return schema;
-  }
-  const base = toTypedJsonSchema(schema);
-  if (!base || typeof base !== "object") return base;
-  if (!forStructuredOutput) return base;
-  return makeStructuredOutputCompatible(base, base.required || []).schema;
+	if (!schema) return void 0;
+	const { forStructuredOutput = false } = options;
+	if (!forStructuredOutput && !isStandardJSONSchema(schema) && !isStandardSchema(schema)) return schema;
+	const base = toTypedJsonSchema(schema);
+	if (!base || typeof base !== "object") return base;
+	if (!forStructuredOutput) return base;
+	return makeStructuredOutputCompatible(base, base.required || []).schema;
 }
+/**
+* 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.
+*/
 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 };
-  }
-  const { schema: jsonSchema, nullWidening } = makeStructuredOutputCompatible(
-    base,
-    base.required || []
-  );
-  return { jsonSchema, nullWideningMap: nullWidening };
+	if (!schema) return {
+		jsonSchema: void 0,
+		nullWideningMap: void 0
+	};
+	const base = toTypedJsonSchema(schema);
+	if (!base || typeof base !== "object") return {
+		jsonSchema: base,
+		nullWideningMap: void 0
+	};
+	const { schema: jsonSchema, nullWidening } = makeStructuredOutputCompatible(base, base.required || []);
+	return {
+		jsonSchema,
+		nullWideningMap: nullWidening
+	};
 }
-class StandardSchemaValidationError extends Error {
-  name = "StandardSchemaValidationError";
-  issues;
-  constructor(issues) {
-    super(
-      `Validation failed: ${issues.map((i) => i.message || "Validation failed").join(", ")}`
-    );
-    this.issues = issues;
-  }
+/**
+* Validates data against a Standard Schema compliant schema.
+*
+* @param schema - Standard Schema compliant schema
+* @param data - Data to validate
+* @returns Validation result with success status, data or issues
+*/
+async function validateWithStandardSchema(schema, data) {
+	if (!isStandardSchema(schema)) return {
+		success: true,
+		data
+	};
+	const result = await schema["~standard"].validate(data);
+	if (!result.issues) return {
+		success: true,
+		data: result.value
+	};
+	return {
+		success: false,
+		issues: result.issues.map((issue) => ({
+			message: issue.message || "Validation failed",
+			path: issue.path?.map(String)
+		}))
+	};
 }
+/**
+* Error thrown when Standard Schema validation fails. Carries the original
+* `issues` array so consumers (middleware `onError`, callers catching from
+* `chat({ outputSchema })`) can programmatically inspect each failure.
+*/
+var StandardSchemaValidationError = class extends Error {
+	name = "StandardSchemaValidationError";
+	issues;
+	constructor(issues) {
+		super(`Validation failed: ${issues.map((i) => i.message || "Validation failed").join(", ")}`);
+		this.issues = issues;
+	}
+};
+/**
+* Synchronously validates data against a Standard Schema compliant schema.
+* Note: Some Standard Schema implementations may only support async validation.
+* In those cases, this function will throw.
+*
+* @param schema - Standard Schema compliant schema
+* @param data - Data to validate
+* @returns Parsed/validated data
+* @throws StandardSchemaValidationError if validation fails; Error if the
+*         schema only supports async validation.
+*/
 function parseWithStandardSchema(schema, data) {
-  if (!isStandardSchema(schema)) {
-    return data;
-  }
-  const result = schema["~standard"].validate(data);
-  if (result instanceof Promise) {
-    throw new Error(
-      "Schema validation returned a Promise. Use validateWithStandardSchema for async validation."
-    );
-  }
-  if (!result.issues) {
-    return result.value;
-  }
-  throw new StandardSchemaValidationError(result.issues);
+	if (!isStandardSchema(schema)) return data;
+	const result = schema["~standard"].validate(data);
+	if (result instanceof Promise) throw new Error("Schema validation returned a Promise. Use validateWithStandardSchema for async validation.");
+	if (!result.issues) return result.value;
+	throw new StandardSchemaValidationError(result.issues);
 }
-export {
-  StandardSchemaValidationError,
-  convertSchemaForStructuredOutput,
-  convertSchemaToJsonSchema,
-  isStandardJSONSchema,
-  isStandardSchema,
-  parseWithStandardSchema
-};
-//# sourceMappingURL=schema-converter.js.map
+//#endregion
+export { StandardSchemaValidationError, convertSchemaForStructuredOutput, convertSchemaToJsonSchema, isStandardJSONSchema, isStandardSchema, parseWithStandardSchema, validateWithStandardSchema };
+
+//# sourceMappingURL=schema-converter.js.map

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 { 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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"}
+{"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":";;;;;;;;;;;;AAkBA,SAAS,aAAa,KAAyB;CAC7C,MAAM,SAAqB,CAAC;CAC5B,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAAG;EAC9C,IAAI,QAAQ,WAAW;EACvB,OAAO,OAAO;CAChB;CACA,OAAO;AACT;;;;;;;;AASA,SAAS,kBAAkB,QAAoD;CAC7E,QACG,OAAO,WAAW,YAAY,OAAO,WAAW,eACjD,WAAW;AAEf;;;;;;AAOA,SAAgB,qBACd,QACgC;CAChC,IAAI,CAAC,kBAAkB,MAAM,KAAK,EAAE,eAAe,SAAS,OAAO;CAEnE,MAAM,WAAW,OAAO;CACxB,IACE,OAAO,aAAa,YACpB,aAAa,QACb,EAAE,aAAa,aACf,SAAS,YAAY,KACrB,EAAE,gBAAgB,aAClB,OAAO,SAAS,eAAe,YAC/B,SAAS,eAAe,QACxB,EAAE,WAAW,SAAS,aAEtB,OAAO;CAGT,OAAO,OAAO,SAAS,WAAW,UAAU;AAC9C;;;;;AAMA,SAAgB,iBAAiB,QAA6C;CAC5E,OACE,kBAAkB,MAAM,KACxB,eAAe,UACf,OAAO,OAAO,iBAAiB,YAC/B,OAAO,iBAAiB,QACxB,aAAa,OAAO,gBACpB,OAAO,YAAY,CAAC,YAAY,KAChC,cAAc,OAAO,gBACrB,OAAO,OAAO,YAAY,CAAC,aAAa;AAE5C;;AAcA,SAAS,SAAS,KAAmD;CACnE,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,SAAS,IAAI,MAAM,KAAA;AAC7C;;;;;;;;;;;;;;;;AAiBA,SAAS,+BACP,QACA,mBAAkC,CAAC,GACP;CAC5B,MAAM,SAAqB,EAAE,GAAG,OAAO;CACvC,MAAM,MAAuB,CAAC;CAG9B,IAAI,OAAO,SAAS,YAAY,OAAO,YAAY;EACjD,MAAM,aAAyC,EAAE,GAAG,OAAO,WAAW;EACtE,MAAM,mBAAmB,OAAO,KAAK,UAAU;EAC/C,MAAM,eAAgD,CAAC;EAGvD,KAAK,MAAM,YAAY,kBAAkB;GACvC,MAAM,OAAO,WAAW;GACxB,IAAI,CAAC,MAAM;GACX,MAAM,cAAc,CAAC,iBAAiB,SAAS,QAAQ;GAEvD,IAAI,cAAc;GAElB,IAAI;GAGJ,IAAI,KAAK,SAAS,YAAY,KAAK,YAAY;IAC7C,MAAM,SAAS,+BAA+B,MAAM,KAAK,YAAY,CAAC,CAAC;IACvE,WAAW,YAAY,cACnB;KAAE,GAAG,OAAO;KAAQ,MAAM,CAAC,UAAU,MAAM;IAAE,IAC7C,OAAO;IACX,cAAc;IACd,WAAW,OAAO;GACpB,OAAO,IAAI,KAAK,SAAS,WAAW,KAAK,OAAO;IAC9C,MAAM,QAAQ,MAAM,QAAQ,KAAK,KAAK,IAAI,KAAK,MAAM,KAAK,KAAK;IAC/D,MAAM,cAAc,QAChB,+BAA+B,OAAO,MAAM,YAAY,CAAC,CAAC,IAC1D,KAAA;IACJ,WAAW,YAAY;KACrB,GAAG;KACH,OAAO,cAAc,YAAY,SAAS,KAAK;KAC/C,GAAI,cAAc,EAAE,MAAM,CAAC,SAAS,MAAM,EAAE,IAAI,CAAC;IACnD;IACA,cAAc;IACd,WAAW,aAAa,eACpB,EAAE,OAAO,YAAY,aAAa,IAClC,KAAA;GACN,OAAO,IAAI;QAIL,KAAK,QAAQ,CAAC,MAAM,QAAQ,KAAK,IAAI,GAAG;KAC1C,WAAW,YAAY;MAAE,GAAG;MAAM,MAAM,CAAC,KAAK,MAAM,MAAM;KAAE;KAC5D,cAAc;IAChB,OAAO,IAAI,MAAM,QAAQ,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,MAAM,GAAG;KAClE,WAAW,YAAY;MAAE,GAAG;MAAM,MAAM,CAAC,GAAG,KAAK,MAAM,MAAM;KAAE;KAC/D,cAAc;IAChB;;GAGF,IAAI,eAAe,UACjB,aAAa,YAAY;IACvB,GAAI,YAAY,CAAC;IACjB,GAAI,cAAc,EAAE,SAAS,KAAK,IAAI,CAAC;GACzC;EAEJ;EAEA,OAAO,aAAa;EAEpB,OAAO,WAAW;EAElB,OAAO,uBAAuB;EAC9B,IAAI,OAAO,KAAK,YAAY,CAAC,CAAC,SAAS,GAAG,IAAI,aAAa;CAC7D;CAGA,IAAI,OAAO,SAAS,WAAW,OAAO,OAAO;EAC3C,MAAM,QAAQ,MAAM,QAAQ,OAAO,KAAK,IAAI,OAAO,MAAM,KAAK,OAAO;EACrE,IAAI,OAAO;GACT,MAAM,cAAc,+BAClB,OACA,MAAM,YAAY,CAAC,CACrB;GACA,OAAO,QAAQ,YAAY;GAC3B,IAAI,YAAY,cAAc,IAAI,QAAQ,YAAY;EACxD;CACF;CAEA,OAAO;EAAE,QAAQ;EAAQ,cAAc,SAAS,GAAG;CAAE;AACvD;;;;;;;;;;;;;;AA8BA,SAAS,kBAAkB,QAA6C;CACtE,IAAI,qBAAqB,MAAM,GAAG;EAIhC,MAAM,SAAqB,aAHR,OAAO,YAAY,CAAC,WAAW,MAAM,EACtD,QAAQ,WACV,CACwC,CAAU;EAClD,IAAI,gBAAgB,UAAU,CAAC,OAAO,MAAM,OAAO,OAAO;EAC1D,IAAI,OAAO,SAAS,YAAY,EAAE,gBAAgB,SAChD,OAAO,aAAa,CAAC;EAEvB,IAAI,OAAO,SAAS,YAAY,EAAE,cAAc,SAC9C,OAAO,WAAW,CAAC;EAErB,OAAO;CACT;CAEA,IAAI,iBAAiB,MAAM,GACzB,MAAM,IAAI,MACR,0QAIF;CAGF,IAAI,OAAO,WAAW,UAAU,OAAO;CACvC,OAAO,aAAa,MAAM;AAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAAgB,0BACd,QACA,UAAgC,CAAC,GACT;CACxB,IAAI,CAAC,QAAQ,OAAO,KAAA;CAEpB,MAAM,EAAE,sBAAsB,UAAU;CAKxC,IACE,CAAC,uBACD,CAAC,qBAAqB,MAAM,KAC5B,CAAC,iBAAiB,MAAM,GAExB,OAAO;CAGT,MAAM,OAAO,kBAAkB,MAAM;CAErC,IAAI,CAAC,QAAQ,OAAO,SAAS,UAAU,OAAO;CAC9C,IAAI,CAAC,qBAAqB,OAAO;CACjC,OAAO,+BAA+B,MAAM,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;AACnE;;;;;;;;;AAUA,SAAgB,iCACd,QAIA;CACA,IAAI,CAAC,QAAQ,OAAO;EAAE,YAAY,KAAA;EAAW,iBAAiB,KAAA;CAAU;CACxE,MAAM,OAAO,kBAAkB,MAAM;CACrC,IAAI,CAAC,QAAQ,OAAO,SAAS,UAC3B,OAAO;EAAE,YAAY;EAAM,iBAAiB,KAAA;CAAU;CAExD,MAAM,EAAE,QAAQ,YAAY,iBAAiB,+BAC3C,MACA,KAAK,YAAY,CAAC,CACpB;CACA,OAAO;EAAE;EAAY,iBAAiB;CAAa;AACrD;;;;;;;;AASA,eAAsB,2BACpB,QACA,MAOA;CACA,IAAI,CAAC,iBAAiB,MAAM,GAE1B,OAAO;EAAE,SAAS;EAAY;CAAU;CAG1C,MAAM,SAAS,MAAM,OAAO,YAAY,CAAC,SAAS,IAAI;CAEtD,IAAI,CAAC,OAAO,QACV,OAAO;EAAE,SAAS;EAAM,MAAM,OAAO;CAAW;CAGlD,OAAO;EACL,SAAS;EACT,QAAQ,OAAO,OAAO,KAAK,WAAW;GACpC,SAAS,MAAM,WAAW;GAC1B,MAAM,MAAM,MAAM,IAAI,MAAM;EAC9B,EAAE;CACJ;AACF;;;;;;AAOA,IAAa,gCAAb,cAAmD,MAAM;CACvD,OAAyB;CACzB;CAEA,YAAY,QAA+C;EACzD,MACE,sBAAsB,OACnB,KAAK,MAAM,EAAE,WAAW,mBAAmB,CAAC,CAC5C,KAAK,IAAI,GACd;EACA,KAAK,SAAS;CAChB;AACF;;;;;;;;;;;;AAaA,SAAgB,wBAA2B,QAAiB,MAAkB;CAC5E,IAAI,CAAC,iBAAiB,MAAM,GAE1B,OAAO;CAGT,MAAM,SAAS,OAAO,YAAY,CAAC,SAAS,IAAI;CAGhD,IAAI,kBAAkB,SACpB,MAAM,IAAI,MACR,4FACF;CAGF,IAAI,CAAC,OAAO,QACV,OAAO,OAAO;CAGhB,MAAM,IAAI,8BAA8B,OAAO,MAAM;AACvD"}

package/dist/esm/activities/chat/tools/tool-calls.d.ts

@@ -1,3 +1,4 @@
+import { ToolApprovalResolution } from '../../../interrupts.js';
 import { AnyTool, CustomEvent, ModelMessage, RunFinishedEvent, Tool, ToolCall, ToolCallArgsEvent, ToolCallEndEvent, ToolCallStartEvent, ToolExecutionContext } from '../../../types.js';
 import { AfterToolCallInfo, BeforeToolCallDecision } from '../middleware/types.js';
 import { ContextFromTool, DefinedContext, MergeContext, UnionToIntersection } from '../runtime-context-types.js';
@@ -101,6 +102,17 @@ export interface ToolResult {
     state?: 'output-available' | 'output-error';
     /** Duration of tool execution in milliseconds (only for server-executed tools) */
     duration?: number;
+    /**
+     * Parsed tool input (after JSON parse + optional Standard Schema validation).
+     * Surfaced on engine-emitted `TOOL_CALL_END` events for TypedStreamChunk consumers.
+     */
+    input?: unknown;
+    /**
+     * Parsed tool output before wire serialization. Surfaced on engine-emitted
+     * `TOOL_CALL_END` events so consumers can read typed `output` without
+     * re-parsing `result`. Undefined on error paths and when execution is skipped.
+     */
+    output?: unknown;
 }
 export interface ApprovalRequest {
     toolCallId: string;
@@ -113,6 +125,10 @@ export interface ClientToolRequest {
     toolName: string;
     input: any;
 }
+export interface ToolResumeExecutionState {
+    deniedToolResults?: ReadonlyMap<string, unknown>;
+    cancelledToolCallIds?: ReadonlySet<string>;
+}
 interface ExecuteToolCallsResult {
     /** Tool results ready to send to LLM */
     results: Array<ToolResult>;
@@ -137,9 +153,9 @@ export declare function executeServerTool<TContext = unknown>(toolCall: ToolCall
  *
  * @param toolCalls - Tool calls from the LLM
  * @param tools - Available tools with their configurations
- * @param approvals - Map of approval decisions (approval.id -> approved boolean)
+ * @param approvals - Map keyed by toolCallId (or `approval_${toolCallId}`) → ToolApprovalResolution
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
  */
-export declare function executeToolCalls<TContext = unknown>(toolCalls: Array<ToolCall>, tools: ReadonlyArray<AnyTool>, approvals?: Map<string, boolean>, clientResults?: Map<string, any>, createCustomEventChunk?: (eventName: string, value: Record<string, any>) => CustomEvent, middlewareHooks?: ToolExecutionMiddlewareHooks, userContext?: TContext, abortSignal?: AbortSignal): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void>;
+export declare function executeToolCalls<TContext = unknown>(toolCalls: Array<ToolCall>, tools: ReadonlyArray<AnyTool>, approvals?: Map<string, ToolApprovalResolution>, clientResults?: Map<string, any>, createCustomEventChunk?: (eventName: string, value: Record<string, any>) => CustomEvent, middlewareHooks?: ToolExecutionMiddlewareHooks, userContext?: TContext, abortSignal?: AbortSignal, resumeState?: ToolResumeExecutionState): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void>;
 export {};