@tanstack/ai 0.17.0 → 0.19.0

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":["/* eslint-disable @typescript-eslint/no-unnecessary-condition */\n\nimport type {\n  StandardJSONSchemaV1,\n  StandardSchemaV1,\n} from '@standard-schema/spec'\nimport type { JSONSchema, SchemaInput } from '../../../types'\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  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'] === 'object' &&\n    (schema as StandardJSONSchemaV1)['~standard'].version === 1 &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema ===\n      'object' &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema.input ===\n      'function'\n  )\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    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof schema['~standard'] === 'object' &&\n    schema !== null &&\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: Record<string, any>,\n  originalRequired: Array<string> = [],\n): Record<string, any> {\n  const result = { ...schema }\n\n  // Handle object types\n  if (result.type === 'object' && result.properties) {\n    const properties = { ...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      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 transformed = {\n          ...prop,\n          items: makeStructuredOutputCompatible(\n            prop.items,\n            prop.items.required || [],\n          ),\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    result.items = makeStructuredOutputCompatible(\n      result.items,\n      result.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    let result = jsonSchema\n\n    if (typeof result === 'object' && '$schema' in result) {\n      // Remove $schema property as it's not needed for LLM providers\n      const { $schema, ...rest } = result\n      result = rest\n    }\n\n    // Ensure object schemas always have type: \"object\"\n\n    if (typeof result === '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(\n          result,\n          (result.required as Array<string>) || [],\n        )\n      }\n    }\n\n    return result as JSONSchema\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  if (forStructuredOutput && typeof schema === 'object') {\n    return makeStructuredOutputCompatible(\n      schema as Record<string, any>,\n      ((schema as JSONSchema).required as Array<string>) || [],\n    ) as JSONSchema\n  }\n\n  return schema as JSONSchema\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  | { success: false; issues: Array<{ message: string; path?: Array<string> }> }\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 * 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 Error if validation fails or if the 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  // invalid validation, throw error with all issues\n  const errorMessages = result.issues\n    .map((issue) => issue.message || 'Validation failed')\n    .join(', ')\n  throw new Error(`Validation failed: ${errorMessages}`)\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-converter.js","sources":["../../../../../src/activities/chat/tools/schema-converter.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unnecessary-condition */\n\nimport type {\n  StandardJSONSchemaV1,\n  StandardSchemaV1,\n} from '@standard-schema/spec'\nimport type { JSONSchema, SchemaInput } from '../../../types'\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  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'] === 'object' &&\n    (schema as StandardJSONSchemaV1)['~standard'].version === 1 &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema ===\n      'object' &&\n    typeof (schema as StandardJSONSchemaV1)['~standard'].jsonSchema.input ===\n      'function'\n  )\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    typeof schema === 'object' &&\n    schema !== null &&\n    '~standard' in schema &&\n    typeof schema['~standard'] === 'object' &&\n    schema !== null &&\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: Record<string, any>,\n  originalRequired: Array<string> = [],\n): Record<string, any> {\n  const result = { ...schema }\n\n  // Handle object types\n  if (result.type === 'object' && result.properties) {\n    const properties = { ...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      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 transformed = {\n          ...prop,\n          items: makeStructuredOutputCompatible(\n            prop.items,\n            prop.items.required || [],\n          ),\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    result.items = makeStructuredOutputCompatible(\n      result.items,\n      result.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    let result = jsonSchema\n\n    if (typeof result === 'object' && '$schema' in result) {\n      // Remove $schema property as it's not needed for LLM providers\n      const { $schema, ...rest } = result\n      result = rest\n    }\n\n    // Ensure object schemas always have type: \"object\"\n\n    if (typeof result === '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(\n          result,\n          (result.required as Array<string>) || [],\n        )\n      }\n    }\n\n    return result as JSONSchema\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  if (forStructuredOutput && typeof schema === 'object') {\n    return makeStructuredOutputCompatible(\n      schema as Record<string, any>,\n      ((schema as JSONSchema).required as Array<string>) || [],\n    ) as JSONSchema\n  }\n\n  return schema as JSONSchema\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  | { success: false; issues: Array<{ message: string; path?: Array<string> }> }\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 * 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 Error if validation fails or if the 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  // invalid validation, throw error with all issues\n  const errorMessages = result.issues\n    .map((issue) => issue.message || 'Validation failed')\n    .join(', ')\n  throw new Error(`Validation failed: ${errorMessages}`)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/adapter-internals.d.ts

@@ -1,4 +1,5 @@
 export type { ResolvedCategories } from './logger/internal-logger.js';
 export { InternalLogger } from './logger/internal-logger.js';
+export type { Logger } from './logger/types.js';
 export { resolveDebugOption } from './logger/resolve.js';
 export { toRunErrorPayload } from './activities/error-payload.js';

package/dist/esm/index.d.ts

@@ -22,6 +22,9 @@ export type { RealtimeToken, RealtimeTokenAdapter, RealtimeTokenOptions, Realtim
 export { convertMessagesToModelMessages, generateMessageId, uiMessageToModelMessages, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, } from './activities/chat/messages.js';
 export { StreamProcessor, createReplayStream, ImmediateStrategy, PunctuationStrategy, BatchStrategy, WordBoundaryStrategy, CompositeStrategy, PartialJSONParser, defaultJSONParser, parsePartialJSON, } from './activities/chat/stream/index.js';
 export type { ChunkStrategy, ChunkRecording, InternalToolCallState, ProcessorResult, ProcessorState, StreamProcessorEvents, StreamProcessorOptions, ToolCallState, ToolResultState, JSONParser, } from './activities/chat/stream/index.js';
+export { chatParamsFromRequest, chatParamsFromRequestBody, mergeAgentTools, } from './utilities/chat-params.js';
+export { uiMessagesToWire } from './utilities/ag-ui-wire.js';
+export type { WireMessage } from './utilities/ag-ui-wire.js';
 export { createModel, extendAdapter } from './extend-adapter.js';
 export type { ExtendedModelDef } from './extend-adapter.js';
 export type { Logger, DebugCategories, DebugConfig, DebugOption, } from './logger/types.js';

package/dist/esm/index.js

@@ -14,12 +14,14 @@ import { createFrozenRegistry, createToolRegistry } from "./tool-registry.js";
 import { detectImageMimeType } from "./utils.js";
 import { realtimeToken } from "./realtime/index.js";
 import { convertMessagesToModelMessages, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, uiMessageToModelMessages } from "./activities/chat/messages.js";
+import { chatParamsFromRequest, chatParamsFromRequestBody, mergeAgentTools } from "./utilities/chat-params.js";
+import { uiMessagesToWire } from "./utilities/ag-ui-wire.js";
 import { createModel, extendAdapter } from "./extend-adapter.js";
 import { ConsoleLogger } from "./logger/console-logger.js";
-import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PunctuationStrategy, WordBoundaryStrategy } from "./activities/chat/stream/strategies.js";
-import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activities/chat/stream/json-parser.js";
 import { EventType } from "@ag-ui/core";
+import { PartialJSONParser, defaultJSONParser, parsePartialJSON } from "./activities/chat/stream/json-parser.js";
+import { StreamProcessor, createReplayStream } from "./activities/chat/stream/processor.js";
 export {
   BatchStrategy,
   CompositeStrategy,
@@ -32,6 +34,8 @@ export {
   ToolCallManager,
   WordBoundaryStrategy,
   chat,
+  chatParamsFromRequest,
+  chatParamsFromRequestBody,
   combineStrategies,
   convertMessagesToModelMessages,
   convertSchemaToJsonSchema,
@@ -57,6 +61,7 @@ export {
   generateVideo,
   getVideoJobStatus,
   maxIterations,
+  mergeAgentTools,
   modelMessageToUIMessage,
   modelMessagesToUIMessages,
   normalizeToUIMessage,
@@ -70,6 +75,7 @@ export {
   toServerSentEventsStream,
   toolDefinition,
   uiMessageToModelMessages,
+  uiMessagesToWire,
   untilFinishReason
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/types.d.ts

@@ -1,4 +1,4 @@
-import { StandardJSONSchemaV1 } from '@standard-schema/spec';
+import { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 import { InternalLogger } from './logger/internal-logger.js';
 import { BaseEvent as AGUIBaseEvent, CustomEvent as AGUICustomEvent, MessagesSnapshotEvent as AGUIMessagesSnapshotEvent, ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent, ReasoningEndEvent as AGUIReasoningEndEvent, ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent, ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent, ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent, ReasoningStartEvent as AGUIReasoningStartEvent, RunErrorEvent as AGUIRunErrorEvent, RunFinishedEvent as AGUIRunFinishedEvent, RunStartedEvent as AGUIRunStartedEvent, StateDeltaEvent as AGUIStateDeltaEvent, StateSnapshotEvent as AGUIStateSnapshotEvent, StepFinishedEvent as AGUIStepFinishedEvent, StepStartedEvent as AGUIStepStartedEvent, TextMessageContentEvent as AGUITextMessageContentEvent, TextMessageEndEvent as AGUITextMessageEndEvent, TextMessageStartEvent as AGUITextMessageStartEvent, ToolCallArgsEvent as AGUIToolCallArgsEvent, ToolCallEndEvent as AGUIToolCallEndEvent, ToolCallResultEvent as AGUIToolCallResultEvent, ToolCallStartEvent as AGUIToolCallStartEvent, EventType } from '@ag-ui/core';
 /**
@@ -54,22 +54,32 @@ export interface JSONSchema {
     [key: string]: any;
 }
 /**
- * Union type for schema input - can be any Standard JSON Schema compliant schema or a plain JSONSchema object.
+ * Union type for schema input - can be any Standard Schema compliant validator,
+ * any Standard JSON Schema compliant schema, or a plain JSONSchema object.
  *
- * Standard JSON Schema compliant libraries include:
+ * Standard JSON Schema compliant libraries (carry the JSON-schema converter):
  * - Zod v4.2+ (natively supports StandardJSONSchemaV1)
  * - ArkType v2.1.28+ (natively supports StandardJSONSchemaV1)
  * - Valibot v1.2+ (via `toStandardJsonSchema()` from `@valibot/to-json-schema`)
  *
+ * StandardSchemaV1 covers libraries whose published types only expose the
+ * validator surface — Zod's core `$ZodType['~standard']` is currently typed
+ * as `StandardSchemaV1.Props` even though the runtime attaches the
+ * `jsonSchema` converter, so this branch is what makes `InferSchemaType`
+ * recover the inferred type for callers using `z.ZodType<T>`.
+ *
  * @see https://standardschema.dev/json-schema
  */
-export type SchemaInput = StandardJSONSchemaV1<any, any> | JSONSchema;
+export type SchemaInput = StandardJSONSchemaV1<any, any> | StandardSchemaV1<any, any> | JSONSchema;
 /**
  * Infer the TypeScript type from a schema.
  * For Standard JSON Schema compliant schemas, extracts the input type.
- * For plain JSONSchema, returns `any` since we can't infer types from JSON Schema at compile time.
+ * For Standard Schema validators (e.g. Zod's `~standard` surface), extracts
+ * the input type from the `StandardSchemaV1` shape.
+ * For plain JSONSchema, returns `unknown` since we can't infer types from
+ * JSON Schema at compile time.
  */
-export type InferSchemaType<T> = T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : unknown;
+export type InferSchemaType<T> = T extends StandardJSONSchemaV1<infer TInput, unknown> ? TInput : T extends StandardSchemaV1<infer TInput, unknown> ? TInput : unknown;
 export interface ToolCall<TMetadata = unknown> {
     id: string;
     type: 'function';
@@ -254,15 +264,49 @@ export interface ThinkingPart {
     stepId?: string;
     signature?: string;
 }
-export type MessagePart = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart;
+/**
+ * Recursive `Partial` — every nested field becomes optional. Used as the
+ * `partial` type on a streaming structured-output part since the progressive
+ * JSON parse hands back objects whose fields are only filled in as bytes
+ * arrive. Defaulted in `DeepPartial<unknown>` → `unknown` so untyped parts
+ * keep their existing shape.
+ */
+export type DeepPartial<T> = T extends ReadonlyArray<infer U> ? Array<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * StructuredOutputPart — a typed structured response attached to the assistant
+ * message that produced it. Generic over the schema-inferred data type so
+ * consumers can thread `useChat({ outputSchema })`'s schema all the way down
+ * to `messages[i].parts[j].data`. Defaults to `unknown` so untyped consumers
+ * (e.g. internal codepaths that don't know about TSchema) keep working.
+ */
+export interface StructuredOutputPart<TData = unknown> {
+    type: 'structured-output';
+    status: 'streaming' | 'complete' | 'error';
+    /** Progressive parse of `raw` via parsePartialJSON — populated while streaming and after complete. */
+    partial?: DeepPartial<TData>;
+    /** Validated final object — only set when `status === 'complete'`. */
+    data?: TData;
+    /** Accumulating JSON buffer. Source of truth for wire round-trip. */
+    raw: string;
+    /** Optional chain-of-thought surfaced by reasoning models alongside the structured output. */
+    reasoning?: string;
+    /** Populated when `status === 'error'`. */
+    errorMessage?: string;
+}
+export type MessagePart<TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart | ToolResultPart | ThinkingPart | StructuredOutputPart<TData>;
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
- * Contains parts that can be text, tool calls, or tool results
+ * Contains parts that can be text, tool calls, or tool results. Generic over
+ * the structured-output data type so `useChat({ outputSchema })`'s schema
+ * narrows `parts.find(p => p.type === 'structured-output').data` on the
+ * consumer side without manual casts.
  */
-export interface UIMessage {
+export interface UIMessage<TData = unknown> {
     id: string;
     role: 'system' | 'user' | 'assistant';
-    parts: Array<MessagePart>;
+    parts: Array<MessagePart<TData>>;
     createdAt?: Date;
 }
 export type InputModalitiesTypes = {
@@ -598,8 +642,14 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      */
     outputSchema?: SchemaInput;
     /**
-     * Conversation ID for correlating client and server-side devtools events.
-     * When provided, server-side events will be linked to the client conversation in devtools.
+     * @deprecated Use `threadId` instead. `conversationId` is the legacy
+     * pre-AG-UI name for the same concept (a stable per-conversation
+     * identifier used to correlate client/server devtools events). When
+     * `conversationId` is omitted, the runtime falls back to `threadId`
+     * automatically, so most callers can simply pass `threadId` (or rely
+     * on `chatParamsFromRequest`, which surfaces it on `params`).
+     *
+     * Will be removed in a future major release.
      */
     conversationId?: string;
     /**
@@ -633,6 +683,11 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
      * If not provided, a unique ID will be generated.
      */
     runId?: string;
+    /**
+     * Parent run ID for AG-UI protocol nested run correlation.
+     * Surfaced for observability/middleware; not consumed by the LLM call.
+     */
+    parentRunId?: string;
 }
 /**
  * Re-export EventType enum from @ag-ui/core for use in event creation.
@@ -921,11 +976,26 @@ export interface StructuredOutputCompleteEvent<T = unknown> extends Omit<CustomE
         reasoning?: string;
     };
 }
+/**
+ * Emitted at the start of a streaming structured-output run, before the JSON
+ * deltas. Tells consumers that the upcoming `TEXT_MESSAGE_CONTENT` deltas
+ * belong to a structured response so they can route those bytes into a
+ * `StructuredOutputPart` instead of building a `TextPart`. Carries the
+ * `messageId` the deltas will be tagged with so the routing decision can be
+ * made per-message rather than globally.
+ */
+export interface StructuredOutputStartEvent extends Omit<CustomEvent, 'name' | 'value'> {
+    name: 'structured-output.start';
+    value: {
+        messageId: string;
+    };
+}
 /**
  * Emitted when a server tool requires approval before execution. The agent
  * loop yields this and pauses — `structured-output.complete` will not fire
  * for that run. The shape is fixed by the orchestrator's tool-approval flow
- * (see `buildApprovalChunks` in `activities/chat/index.ts`).
+ * (the agent-loop branch of `runStreamingStructuredOutputImpl` in
+ * `activities/chat/index.ts` forwards CUSTOM events from `TextEngine.run()`).
  */
 export interface ApprovalRequestedEvent extends Omit<CustomEvent, 'name' | 'value'> {
     name: 'approval-requested';
@@ -942,8 +1012,8 @@ export interface ApprovalRequestedEvent extends Omit<CustomEvent, 'name' | 'valu
 /**
  * Emitted when a client tool is invoked. The agent loop yields this and
  * pauses to let the caller run the tool client-side — `structured-output.complete`
- * will not fire for that run. Shape fixed by `buildClientToolChunks` in
- * `activities/chat/index.ts`.
+ * will not fire for that run. Shape fixed by the agent-loop forwarding in
+ * `runStreamingStructuredOutputImpl` in `activities/chat/index.ts`.
  */
 export interface ToolInputAvailableEvent extends Omit<CustomEvent, 'name' | 'value'> {
     name: 'tool-input-available';
@@ -983,7 +1053,7 @@ export interface ToolInputAvailableEvent extends Omit<CustomEvent, 'name' | 'val
  * `emitCustomEvent` plus `outputSchema + stream: true`, branch on `CUSTOM`
  * outside the literal-`name` narrows or cast explicitly.
  */
-export type StructuredOutputStream<T = unknown> = AsyncIterable<Exclude<StreamChunk, CustomEvent> | StructuredOutputCompleteEvent<T> | ApprovalRequestedEvent | ToolInputAvailableEvent>;
+export type StructuredOutputStream<T = unknown> = AsyncIterable<Exclude<StreamChunk, CustomEvent> | StructuredOutputStartEvent | StructuredOutputCompleteEvent<T> | ApprovalRequestedEvent | ToolInputAvailableEvent>;
 /**
  * Emitted when reasoning starts for a message.
  *

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

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

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

@@ -0,0 +1,104 @@
+function uiMessagesToWire(messages) {
+  const wire = [];
+  for (const msg of messages) {
+    const parts = msg.parts ?? [];
+    if (msg.role === "system") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectText(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    if (msg.role === "user") {
+      wire.push({
+        ...msg,
+        content: parts.length > 0 ? collectUserContent(parts) : msg.content ?? ""
+      });
+      continue;
+    }
+    for (const part of parts) {
+      if (part.type === "thinking") {
+        wire.push({
+          role: "reasoning",
+          id: deriveReasoningId(msg.id, part),
+          content: part.content
+        });
+      }
+    }
+    const text = collectText(parts);
+    const toolCalls = collectToolCalls(parts);
+    wire.push({
+      ...msg,
+      ...text !== "" && { content: text },
+      ...toolCalls && { toolCalls }
+    });
+    for (const part of parts) {
+      if (part.type === "tool-result") {
+        wire.push({
+          role: "tool",
+          id: deriveToolMessageId(part.toolCallId),
+          toolCallId: part.toolCallId,
+          content: part.content,
+          ...part.error !== void 0 && { error: part.error }
+        });
+      }
+    }
+  }
+  return wire;
+}
+function collectText(parts) {
+  const out = [];
+  for (const p of parts) {
+    if (p.type === "text") {
+      out.push(p.content);
+    } else if (p.type === "structured-output" && p.status === "complete" && p.raw !== "") {
+      out.push(p.raw);
+    }
+  }
+  return out.join("");
+}
+function collectUserContent(parts) {
+  const hasMultimodal = parts.some(
+    (p) => p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document"
+  );
+  if (!hasMultimodal) {
+    return collectText(parts);
+  }
+  const out = [];
+  for (const p of parts) {
+    if (p.type === "text") {
+      out.push({ type: "text", text: p.content });
+    } else if (p.type === "image" || p.type === "audio" || p.type === "video" || p.type === "document") {
+      out.push(p);
+    }
+  }
+  return out;
+}
+function collectToolCalls(parts) {
+  const calls = [];
+  for (const p of parts) {
+    if (p.type === "tool-call") {
+      calls.push({
+        id: p.id,
+        type: "function",
+        function: { name: p.name, arguments: p.arguments }
+      });
+    }
+  }
+  return calls.length > 0 ? calls : void 0;
+}
+function deriveReasoningId(messageId, part) {
+  return `${messageId}-reasoning-${part.id ?? hashContent(part.content)}`;
+}
+function deriveToolMessageId(toolCallId) {
+  return `tool-${toolCallId}`;
+}
+function hashContent(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) | 0;
+  return Math.abs(h).toString(36);
+}
+export {
+  uiMessagesToWire
+};
+//# sourceMappingURL=ag-ui-wire.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui-wire.js","sources":["../../../src/utilities/ag-ui-wire.ts"],"sourcesContent":["import type { ContentPart, MessagePart, UIMessage } from '../types'\n\ntype AGUITextInputContent = { type: 'text'; text: string }\ntype AGUIInputContent =\n  | AGUITextInputContent\n  | (ContentPart & { type: 'image' | 'audio' | 'video' | 'document' })\n\ntype AGUIToolCallMirror = {\n  id: string\n  type: 'function'\n  function: { name: string; arguments: string }\n}\n\ntype AGUIToolMessage = {\n  role: 'tool'\n  id: string\n  toolCallId: string\n  content: string\n  error?: string\n}\n\ntype AGUIReasoningMessage = {\n  role: 'reasoning'\n  id: string\n  content: string\n}\n\ntype WireAnchorMessage = UIMessage & {\n  content?: string | Array<AGUIInputContent>\n  toolCalls?: Array<AGUIToolCallMirror>\n}\n\nexport type WireMessage =\n  | WireAnchorMessage\n  | AGUIToolMessage\n  | AGUIReasoningMessage\n\n/**\n * Serialize TanStack `UIMessage`s into the AG-UI `RunAgentInput.messages`\n * wire shape. Each anchor (system/user/assistant) carries the canonical\n * `parts` array verbatim plus AG-UI mirror fields (`content`, `toolCalls`)\n * so AG-UI Zod parsing succeeds. Tool results and thinking parts on\n * assistant messages are additionally emitted as fan-out\n * `{role:'tool',...}` and `{role:'reasoning',...}` entries for strict\n * AG-UI server consumers.\n */\nexport function uiMessagesToWire(\n  messages: Array<UIMessage>,\n): Array<WireMessage> {\n  const wire: Array<WireMessage> = []\n\n  for (const msg of messages) {\n    // Defensive: if parts is missing (ModelMessage-shaped input), pass through as-is.\n    // UIMessage always has parts; ModelMessage uses content directly.\n    const parts: ReadonlyArray<MessagePart> =\n      (msg.parts as ReadonlyArray<MessagePart> | undefined) ?? []\n\n    if (msg.role === 'system') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectText(parts)\n            : ((msg as unknown as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    if (msg.role === 'user') {\n      wire.push({\n        ...msg,\n        content:\n          parts.length > 0\n            ? collectUserContent(parts)\n            : ((msg as unknown as { content?: string }).content ?? ''),\n      })\n      continue\n    }\n\n    // assistant: emit reasoning fan-outs first, then anchor, then tool fan-outs\n    for (const part of parts) {\n      if (part.type === 'thinking') {\n        wire.push({\n          role: 'reasoning',\n          id: deriveReasoningId(msg.id, part),\n          content: part.content,\n        })\n      }\n    }\n\n    const text = collectText(parts)\n    const toolCalls = collectToolCalls(parts)\n    wire.push({\n      ...msg,\n      ...(text !== '' && { content: text }),\n      ...(toolCalls && { toolCalls }),\n    })\n\n    for (const part of parts) {\n      if (part.type === 'tool-result') {\n        wire.push({\n          role: 'tool',\n          id: deriveToolMessageId(part.toolCallId),\n          toolCallId: part.toolCallId,\n          content: part.content,\n          ...(part.error !== undefined && { error: part.error }),\n        })\n      }\n    }\n  }\n\n  return wire\n}\n\nfunction collectText(parts: ReadonlyArray<MessagePart>): string {\n  // The streamed JSON of a completed structured-output part is the source of\n  // truth for multi-turn coherence — emitting it back as assistant content\n  // lets the LLM see its own prior structured response. Streaming/errored\n  // parts are skipped: they'd ship malformed JSON fragments and confuse the\n  // model. `completeStructuredOutputPart` tries hard to populate `raw`\n  // (caller → existing buffer → `JSON.stringify(data)`), but the stringify\n  // fallback can leave it empty when `data` is unserializable (BigInt,\n  // circular). The `p.raw !== ''` guard below is what enforces \"no malformed\n  // round-trip\" in that case — without it we'd ship `''` and the model would\n  // see an empty assistant turn.\n  const out: Array<string> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push(p.content)\n    } else if (\n      p.type === 'structured-output' &&\n      p.status === 'complete' &&\n      p.raw !== ''\n    ) {\n      out.push(p.raw)\n    }\n  }\n  return out.join('')\n}\n\nfunction collectUserContent(\n  parts: ReadonlyArray<MessagePart>,\n): string | Array<AGUIInputContent> {\n  const hasMultimodal = parts.some(\n    (p) =>\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document',\n  )\n  if (!hasMultimodal) {\n    return collectText(parts)\n  }\n  const out: Array<AGUIInputContent> = []\n  for (const p of parts) {\n    if (p.type === 'text') {\n      out.push({ type: 'text', text: p.content })\n    } else if (\n      p.type === 'image' ||\n      p.type === 'audio' ||\n      p.type === 'video' ||\n      p.type === 'document'\n    ) {\n      out.push(p as AGUIInputContent)\n    }\n  }\n  return out\n}\n\nfunction collectToolCalls(\n  parts: ReadonlyArray<MessagePart>,\n): Array<AGUIToolCallMirror> | undefined {\n  const calls: Array<AGUIToolCallMirror> = []\n  for (const p of parts) {\n    if (p.type === 'tool-call') {\n      calls.push({\n        id: p.id,\n        type: 'function',\n        function: { name: p.name, arguments: p.arguments },\n      })\n    }\n  }\n  return calls.length > 0 ? calls : undefined\n}\n\nfunction deriveReasoningId(messageId: string, part: MessagePart): string {\n  return `${messageId}-reasoning-${(part as { id?: string }).id ?? hashContent((part as { content: string }).content)}`\n}\n\nfunction deriveToolMessageId(toolCallId: string): string {\n  return `tool-${toolCallId}`\n}\n\nfunction hashContent(s: string): string {\n  // Cheap deterministic id suffix; collisions are tolerable since\n  // reasoning ids only matter for AG-UI server consumers, not for our\n  // own server's dedup logic (which keys on toolCallId, not reasoning id).\n  let h = 0\n  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0\n  return Math.abs(h).toString(36)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/utilities/chat-params.d.ts

@@ -0,0 +1,80 @@
+import { Context as AGUIContext } from '@ag-ui/core';
+import { JSONSchema, ModelMessage, Tool, UIMessage } from '../types.js';
+/**
+ * Parse and validate an HTTP request body as an AG-UI `RunAgentInput`.
+ *
+ * Returns a spread-friendly object whose `messages` field is suitable for
+ * passing directly to `chat({ messages })`. The existing
+ * `convertMessagesToModelMessages` handles AG-UI fan-out dedup and
+ * reasoning/activity/developer-role normalization internally.
+ *
+ * @throws An error with a migration-pointing message when the body does
+ *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a
+ *   400 Bad Request to the client.
+ */
+export declare function chatParamsFromRequestBody(body: unknown): Promise<{
+    messages: Array<UIMessage | ModelMessage>;
+    threadId: string;
+    runId: string;
+    parentRunId?: string;
+    tools: Array<{
+        name: string;
+        description: string;
+        parameters: JSONSchema;
+    }>;
+    forwardedProps: Record<string, unknown>;
+    state: unknown;
+    context: Array<AGUIContext>;
+}>;
+/**
+ * Read an HTTP `Request`, parse its JSON body, and validate it as an
+ * AG-UI `RunAgentInput` — collapsing the standard `req.json()` +
+ * `chatParamsFromRequestBody(...)` pair into a single call.
+ *
+ * On a malformed body or invalid AG-UI shape, this **throws a
+ * `Response`** with status 400 and a migration-pointing message in the
+ * body. Frameworks that natively handle thrown `Response` objects
+ * (TanStack Start, SolidStart, Remix, React Router 7) will return the
+ * 400 to the client automatically, so the handler reduces to:
+ *
+ * ```ts
+ * export async function POST(req: Request) {
+ *   const params = await chatParamsFromRequest(req)
+ *   // ...use params
+ * }
+ * ```
+ *
+ * In frameworks that do not auto-handle thrown `Response` objects
+ * (Next.js Route Handlers, SvelteKit, Hono, raw Node), wrap the call
+ * with try/catch and return the caught Response yourself, or use
+ * `chatParamsFromRequestBody` directly with your own JSON-parsing.
+ *
+ * @throws {Response} 400 on malformed JSON or invalid AG-UI shape.
+ */
+export declare function chatParamsFromRequest(req: Request): Promise<Awaited<ReturnType<typeof chatParamsFromRequestBody>>>;
+/**
+ * Merge a server-side tool array with the AG-UI client-declared tools
+ * received in the request body.
+ *
+ * Rules:
+ * - Server tools win on name collision. The client's declaration is
+ *   ignored if the server already has a tool with that name. The client's
+ *   UI-side handler still fires when the streamed tool-result event comes
+ *   through (see `chat-client.ts` `onToolCall`), giving the
+ *   "after server execution the client also handles" semantic for free.
+ * - Client-only tools (name not in `serverTools`) become no-execute
+ *   entries: the runtime's existing `ClientToolRequest` path handles
+ *   them — server emits a tool-call request, client executes via its
+ *   registered handler, client posts back the result.
+ *
+ * @param serverTools - The server's tool array (e.g. from
+ *   `[myToolDef.server(...)]`). Pass directly to `chat({ tools })`.
+ * @param clientTools - The `tools` array received from
+ *   `chatParamsFromRequest(...)` / `chatParamsFromRequestBody(...)`.
+ * @returns A merged array suitable for `chat({ tools })`.
+ */
+export declare function mergeAgentTools(serverTools: ReadonlyArray<Tool>, clientTools: ReadonlyArray<{
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+}>): Array<Tool>;