@langchain/core 1.0.0-alpha.2 → 1.0.0-alpha.4

package/dist/messages/message.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.cts","names":["ContentBlock","ResponseMetadata","UsageMetadata","$MergeDiscriminatedUnion","$MergeObjects","MessageType","NonNullable","MessageOutputVersion","MessageToolDefinition","TInput","TOutput","MessageToolSet","$MessageToolCallBlock","MessageStructure","TStructure","K","Tools","ToolCall","Partial","Record","$NormalizeMessageOutputVersion","T","Extract","$MergeOutputVersion","U","TV","UV","Exclude","$MergeContentDefinition","$MergeMessageStructure","StandardMessageStructure","Text","$NormalizedMessageStructure","$InferMessageContentBlocks","S","C","PropertyKey","TRole","$InferMessageContent","Array","$InferMessageProperties","P","Omit","$InferMessageProperty","$InferResponseMetadata","Message","isMessage"],"sources":["../../src/messages/message.d.ts"],"sourcesContent":["import type { ContentBlock } from \"./content/index.js\";\nimport type { ResponseMetadata, UsageMetadata } from \"./metadata.js\";\nimport type { $MergeDiscriminatedUnion, $MergeObjects } from \"./utils.js\";\n/**\n * Represents the possible types of messages in the system.\n * Includes standard message types (\"ai\", \"human\", \"tool\", \"system\")\n * and allows for custom string types that are non-null.\n *\n * @example\n * ```ts\n * // Standard message types\n * const messageType1: MessageType = \"ai\";\n * const messageType2: MessageType = \"human\";\n *\n * // Custom message type\n * const messageType3: MessageType = \"custom_type\";\n * ```\n */\nexport type MessageType = \"ai\" | \"human\" | \"tool\" | \"system\" | (string & NonNullable<unknown>);\n/**\n * Represents the output version format for message content.\n *\n * This type determines how the content field is structured in a message:\n * - \"v0\": Content is represented as a simple string or array of content blocks\n *   - provides backward compatibility with simpler content representations\n * - \"v1\": Content follows the structured ContentBlock format with typed discriminated unions\n *   - enables full type safety and structured content block handling\n *\n * @example\n * ```ts\n * // v0 format - simple content representation\n * const v0Message: Message<{ outputVersion: \"v0\", content: ... }> = {\n *   type: \"human\",\n *   content: \"Hello world\" // string | Array<ContentBlock | ContentBlock.Text>\n * };\n *\n * // v1 format - structured content blocks\n * const v1Message: Message<{ outputVersion: \"v1\", content: ... }> = {\n *   type: \"human\",\n *   content: [\n *     { type: \"text\", text: \"Hello world\" },\n *     { type: \"image\", image_url: \"...\" }\n *   ] // Array<ContentBlock | ...> (determined by the structure)\n * };\n * ```\n */\nexport type MessageOutputVersion = \"v0\" | \"v1\";\n/**\n * Represents the input and output types of a tool that can be used in messages.\n *\n * @template TInput - The type of input the tool accepts.\n * @template TOutput - The type of output the tool produces.\n *\n * @example\n * ```ts\n * // Tool that takes a string input and returns a number\n * interface StringToNumberTool extends MessageToolDefinition<string, number> {\n *   input: string;\n *   output: number;\n * }\n * ```\n */\nexport interface MessageToolDefinition<TInput = unknown, TOutput = unknown> {\n    input: TInput;\n    output: TOutput;\n}\n/**\n * Represents a structured set of tools by mapping tool names to definitions\n * that can be used in messages.\n *\n * @example\n * ```ts\n * interface MyToolSet extends MessageToolSet {\n *   calculator: MessageToolDefinition<\n *     { operation: string; numbers: number[] },\n *     number\n *   >;\n *   translator: MessageToolDefinition<\n *     { text: string; targetLanguage: string },\n *     string\n *   >;\n * }\n * ```\n */\nexport interface MessageToolSet {\n    [key: string]: MessageToolDefinition;\n}\n/**\n * Represents a tool call block within a message structure by mapping tool names to their\n * corresponding tool call formats, including the input arguments and an optional identifier.\n *\n * @template TStructure - A message structure type that may contain tool definitions\n *\n * @example\n * ```ts\n * // Given a message structure with a calculator tool:\n * interface MyStructure extends MessageStructure {\n *   tools: {\n *     calculator: MessageToolDefinition<{ operation: string, numbers: number[] }, number>\n *   }\n * }\n *\n * // The tool call block would be:\n * type CalcToolCall = $MessageToolCallBlock<MyStructure>;\n * // Resolves to:\n * // {\n * //   type: \"tool_call\";\n * //   name: \"calculator\";\n * //   args: { operation: string, numbers: number[] };\n * //   id?: string;\n * // }\n * ```\n */\nexport type $MessageToolCallBlock<TStructure extends MessageStructure> = TStructure[\"tools\"] extends MessageToolSet ? {\n    [K in keyof TStructure[\"tools\"]]: K extends string ? TStructure[\"tools\"][K] extends MessageToolDefinition ? ContentBlock.Tools.ToolCall<K, TStructure[\"tools\"][K][\"input\"]> : never : never;\n}[keyof TStructure[\"tools\"]] : never;\n/**\n * Core interface that defines the structure of messages.\n *\n * @example\n * ```ts\n * // Basic message structure with just content blocks\n * interface SimpleMessageStructure extends MessageStructure {\n *   content: {\n *     human: ContentBlock.Text;\n *     // allows for text + reasoning blocks in ai messages\n *     ai: ContentBlock.Text | ContentBlock.Reasoning;\n *   }\n * }\n *\n * // Message structure with tools and properties\n * interface AdvancedMessageStructure extends MessageStructure {\n *   tools: {\n *     calculator: MessageToolDefinition<\n *       { operation: string; numbers: number[] },\n *       number\n *     >;\n *   };\n *   content: {\n *     // allows for text + image blocks in human messages\n *     human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n *     // only allows for text blocks in ai messages\n *     ai: ContentBlock.Text;\n *   };\n *   properties: {\n *     // pins properties to ai messages\n *     ai: {\n *       response_metadata: {\n *         confidence: number;\n *         model: string;\n *       };\n *     };\n *   }\n * }\n *\n * // Using with $MergeMessageStructure to combine structures\n * // The resulting type when passed into BaseMessage will have a calculator tool,\n * // allow for text + image blocks in human messages,\n * // and text + reasoning blocks + additional arbitrary properties in ai messages.\n * type CombinedStructure = $MergeMessageStructure<\n *   SimpleMessageStructure,\n *   AdvancedMessageStructure\n * >;\n *\n * // Using in a Message object\n * const message: Message<CombinedStructure> = {\n *   id: \"msg-123\",\n *   type: \"human\",\n *   content: [\n *     { type: \"text\", text: \"Hello!\" }\n *     { type: \"image\", mimeType: \"image/jpeg\", url: \"https://example.com/image.jpg\" }\n *     // this block will throw an error because it's not defined in the structure\n *     { type: \"reasoning\", reasoning: \"The answer is 42\" }\n *   ]\n * };\n * ```\n */\nexport interface MessageStructure {\n    /**\n     * Optional output version for the message structure.\n     * If not provided, defaults to \"v0\".\n     */\n    readonly outputVersion?: MessageOutputVersion;\n    /**\n     * Optional set of tool definitions that can be used in messages.\n     * Each tool is defined with input/output types and can be referenced in tool messages.\n     */\n    readonly tools?: MessageToolSet;\n    /**\n     * Optional mapping of message types to their allowed content blocks.\n     * Each message type can specify what content block types it supports (text, images, etc).\n     */\n    readonly content?: Partial<{\n        [key in MessageType]: ContentBlock;\n    }>;\n    /**\n     * Optional mapping of message types to arbitrary property objects.\n     * Allows attaching custom metadata or other information to specific message types.\n     */\n    readonly properties?: Partial<{\n        [key in MessageType]: Record<string, unknown>;\n    }>;\n}\n/**\n * Normalizes an arbitrary type to a message output version or undefined.\n * Accepts unknown and narrows to a valid MessageOutputVersion if present.\n */\ntype $NormalizeMessageOutputVersion<T> = Extract<T, MessageOutputVersion> | undefined;\n/**\n * Merges two output version types from message structures.\n *\n * This utility type determines the resulting output version when combining two message structures.\n * The merge logic follows these rules:\n *\n * - If both T and U are undefined, defaults to \"v0\" for backwards compatibility\n * - If T is undefined but U is defined, uses U's version\n * - If U is undefined but T is defined, uses T's version\n * - If both T and U are defined, U takes precedence (later structure wins)\n *\n * @template T - The output version from the first message structure\n * @template U - The output version from the second message structure\n *\n * @example\n * ```ts\n * // Both undefined - defaults to \"v0\"\n * type Result1 = $MergeOutputVersion<undefined, undefined>; // \"v0\"\n *\n * // One defined - uses the defined version\n * type Result2 = $MergeOutputVersion<undefined, \"v1\">; // \"v1\"\n * type Result3 = $MergeOutputVersion<\"v0\", undefined>; // \"v0\"\n *\n * // Both defined - second takes precedence\n * type Result4 = $MergeOutputVersion<\"v0\", \"v1\">; // \"v1\"\n * ```\n */\nexport type $MergeOutputVersion<T, U> = $NormalizeMessageOutputVersion<T> extends infer TV ? $NormalizeMessageOutputVersion<U> extends infer UV ? [TV, UV] extends [undefined, undefined] ? \"v0\" : [TV] extends [undefined] ? Exclude<UV, undefined> : [UV] extends [undefined] ? Exclude<TV, undefined> : UV : never : never;\n/**\n * Merges two content definition objects from message structures.\n *\n * This utility type combines content definitions from two message structures, handling\n * the merging of content block types for each message type. The merge logic follows\n * these rules:\n *\n * - For keys that exist in both T and U: Merges the content blocks using discriminated\n *   union merging based on the \"type\" property. This allows combining different content\n *   block types (e.g., text + image) for the same message type.\n * - For keys that exist only in T: Uses T's content definition as-is\n * - For keys that exist only in U: Uses U's content definition as-is\n *\n * @template T - The content definition from the first message structure\n * @template U - The content definition from the second message structure\n *\n * @example\n * ```ts\n * // T allows text content for human messages\n * type ContentA = {\n *   human: ContentBlock.Text;\n * };\n *\n * // U allows image content for human messages and text for AI messages\n * type ContentB = {\n *   human: ContentBlock.Multimodal.Image;\n *   ai: ContentBlock.Text;\n * };\n *\n * // Merged result allows both text and images for human messages, text for AI\n * type Merged = $MergeContentDefinition<ContentA, ContentB>;\n * // Result: {\n * //   human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n * //   ai: ContentBlock.Text;\n * // }\n * ```\n */\nexport type $MergeContentDefinition<T, U> = {\n    [K in keyof T | keyof U as Extract<(K extends keyof T ? T[K] : never) | (K extends keyof U ? U[K] : never), ContentBlock> extends never ? never : K]: K extends keyof T ? K extends keyof U ? $MergeDiscriminatedUnion<Extract<T[K], ContentBlock>, Extract<U[K], ContentBlock>, \"type\"> : Extract<T[K], ContentBlock> : K extends keyof U ? Extract<U[K], ContentBlock> : never;\n};\n/**\n * Merges two message structures A and B into a combined structure.\n * This is a type utility that handles merging of tools, content blocks, and properties\n * from two message structures. The resulting type is usable as its own message structure.\n *\n * @example\n * ```ts\n * // Structure A allows text in human messages and has a confidence property on AI messages\n * interface StructureA extends MessageStructure {\n *   content: {\n *     human: ContentBlock.Text;\n *   };\n *   properties: {\n *     ai: { confidence: number };\n *   }\n * }\n *\n * // Structure B allows images in human messages and has a model property on AI messages\n * interface StructureB extends MessageStructure {\n *   content: {\n *     human: ContentBlock.Multimodal.Image;\n *   };\n *   properties: {\n *     ai: { model: string };\n *   }\n * }\n *\n * // Merged structure allows both text and images in human messages\n * // AI messages have both confidence and model properties\n * type Merged = $MergeMessageStructure<StructureA, StructureB>;\n * ```\n *\n * @template A - First message structure to merge\n * @template B - Second message structure to merge (takes precedence over A)\n */\nexport type $MergeMessageStructure<T extends MessageStructure, U extends MessageStructure> = {\n    outputVersion: $MergeOutputVersion<T[\"outputVersion\"], U[\"outputVersion\"]>;\n    tools: $MergeObjects<T[\"tools\"], U[\"tools\"]>;\n    content: $MergeContentDefinition<T[\"content\"], U[\"content\"]>;\n    properties: $MergeObjects<T[\"properties\"], U[\"properties\"]>;\n};\n/**\n * Standard message structured used to define the most basic message structure that's\n * used throughout the library.\n *\n * This is also the message structure that's used when a message structure is not provided.\n */\nexport interface StandardMessageStructure extends MessageStructure {\n    content: {\n        /** Text content for AI messages */\n        ai: ContentBlock.Text;\n        /** Text content for human messages */\n        human: ContentBlock.Text;\n        /** Text content for system messages */\n        system: ContentBlock.Text;\n        /** Text content for tool messages */\n        tool: ContentBlock.Text;\n    };\n    properties: {\n        /** Properties specific to AI messages */\n        ai: {\n            /** Metadata about the AI model response */\n            response_metadata?: ResponseMetadata;\n            /** Usage statistics for the AI response */\n            usage_metadata?: UsageMetadata;\n        };\n        human: {\n            /** Metadata about the human message */\n            response_metadata?: Record<string, unknown>;\n        };\n        system: {\n            /** Metadata about the system message */\n            response_metadata?: Record<string, unknown>;\n        };\n        tool: {\n            /** Metadata about the tool message */\n            response_metadata?: Record<string, unknown>;\n        };\n    };\n}\n/**\n * Takes a message structure type T and normalizes it by merging it with the standard message structure.\n * If T is already a standard message structure, returns T unchanged.\n *\n * This ensures that any custom message structure includes all the standard message structure fields\n * by default while allowing overrides and extensions.\n *\n * @template T - The message structure type to normalize, must extend MessageStructure\n * @returns Either T if it's already a standard structure, or the merged result of T with standard structure\n */\nexport type $NormalizedMessageStructure<T extends MessageStructure> = T extends StandardMessageStructure ? T : $MergeMessageStructure<StandardMessageStructure, T>;\n/**\n * Infers the content blocks for a specific message type in a message structure.\n *\n * This utility type extracts the content block type that corresponds to a given message type\n * from the message structure's content definition.\n *\n * @template TStructure - The message structure to infer content from\n * @template TRole - The message role/type to get content for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The content block type for the specified type, or never if its not defined in the structure\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n *   content: {\n *     human: ContentBlock.Text;\n *     ai: ContentBlock.Text | ContentBlock.ToolCall;\n *   };\n * }\n *\n * type HumanContent = $InferMessageContentBlocks<MyStructure, \"human\">;\n * // HumanContent = ContentBlock.Text\n *\n * type AIContent = $InferMessageContentBlocks<MyStructure, \"ai\">;\n * // AIContent = ContentBlock.Text | ContentBlock.ToolCall\n * ```\n */\nexport type $InferMessageContentBlocks<TStructure extends MessageStructure, TRole extends MessageType> = $NormalizedMessageStructure<TStructure> extends infer S ? S extends MessageStructure ? S[\"content\"] extends infer C ? C extends Record<PropertyKey, ContentBlock> ? TRole extends keyof C ? [$MessageToolCallBlock<TStructure>] extends [never] ? C[TRole] : $MergeDiscriminatedUnion<NonNullable<C[TRole]>, $MessageToolCallBlock<TStructure>, \"type\"> : never : never : never : never : never;\n/**\n * Infers the content type for a specific message type from a message structure.\n *\n * This utility type determines the appropriate content type based on the message structure's\n * output version and the specified message type. The content type varies depending on the\n * output version (see {@link MessageOutputVersion})\n *\n * @template TStructure - The message structure to infer content from\n * @template TRole - The message role/type to get content for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The content type for the specified role based on the output version\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n *   outputVersion: \"v0\";\n *   content: {\n *     human: ContentBlock.Text;\n *     ai: ContentBlock.Text | ContentBlock.ToolCall;\n *   };\n * }\n *\n * type HumanContentV0 = $InferMessageContent<MyStructure, \"human\">;\n * // HumanContentV0 = string | Array<ContentBlock | ContentBlock.Text>\n *\n * interface MyStructureV1 extends MessageStructure {\n *   outputVersion: \"v1\";\n *   content: {\n *     human: ContentBlock.Text;\n *     ai: ContentBlock.Text | ContentBlock.Reasoning;\n *   };\n * }\n *\n * type HumanContentV1 = $InferMessageContent<MyStructureV1, \"human\">;\n * // HumanContentV1 = ContentBlock.Text\n *\n * type AIContentV1 = $InferMessageContent<MyStructureV1, \"ai\">;\n * // AIContentV1 = ContentBlock.Text | ContentBlock.Reasoning\n * ```\n */\nexport type $InferMessageContent<TStructure extends MessageStructure, TRole extends MessageType> = TStructure[\"outputVersion\"] extends \"v1\" ? Array<$InferMessageContentBlocks<TStructure, TRole>> : string | Array<ContentBlock | ContentBlock.Text>;\n/**\n * Infers the properties for a specific message type from a message structure.\n *\n * This utility type extracts the properties object that corresponds to a given message type\n * from the message structure's properties definition, and excludes the reserved\n * \"content\" and \"type\" properties to avoid conflicts with the core message structure.\n *\n * If the specified type is not defined in the message structure's properties, it returns\n * a generic Record<string, unknown> type to allow for arbitrary properties.\n *\n * @template TStructure - The message structure to infer properties from\n * @template TRole - The message type/role to get properties for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The properties object type for the specified type, excluding \"content\" and \"type\"\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n *   properties: {\n *     ai: {\n *       response_metadata: { model: string };\n *       usage_metadata: { tokens: number };\n *       content: string; // This will be omitted\n *       type: string;    // This will be omitted\n *     };\n *     human: { metadata: Record<string, unknown> };\n *   };\n * }\n *\n * type AIProperties = $InferMessageProperties<MyStructure, \"ai\">;\n * // AIProperties = { response_metadata: { model: string }; usage_metadata: { tokens: number } }\n *\n * type HumanProperties = $InferMessageProperties<MyStructure, \"human\">;\n * // HumanProperties = { metadata: Record<string, unknown> }\n *\n * type SystemProperties = $InferMessageProperties<MyStructure, \"system\">;\n * // SystemProperties = Record<string, unknown> (fallback for undefined role)\n * ```\n */\nexport type $InferMessageProperties<TStructure extends MessageStructure, TRole extends MessageType> = $NormalizedMessageStructure<TStructure> extends infer S ? S extends MessageStructure ? S[\"properties\"] extends infer P | undefined ? P extends Record<PropertyKey, unknown> ? TRole extends keyof P ? Omit<P[TRole], \"content\" | \"type\"> : Record<string, unknown> : Record<string, unknown> : Record<string, unknown> : never : never;\n/**\n * Infers the type of a specific property for a message type from a message structure.\n *\n * This utility type extracts the type of a single property by name from the properties\n * object that corresponds to a given message type. If the specified property key does\n * not exist in the type's properties, it returns `never`.\n *\n * @template TStructure - The message structure to infer the property from\n * @template TRole - The message type/role to get the property for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @template K - The property key to extract the type for\n * @returns The type of the specified property, or `never` if the property doesn't exist\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n *   properties: {\n *     ai: {\n *       response_metadata: { model: string; temperature: number };\n *       usage_metadata: { input_tokens: number; output_tokens: number };\n *     };\n *     human: { metadata: Record<string, unknown> };\n *   };\n * }\n *\n * type ResponseMetadata = $InferMessageProperty<MyStructure, \"ai\", \"response_metadata\">;\n * // ResponseMetadata = { model: string; temperature: number }\n *\n * type UsageMetadata = $InferMessageProperty<MyStructure, \"ai\", \"usage_metadata\">;\n * // UsageMetadata = { input_tokens: number; output_tokens: number }\n *\n * type NonExistentProperty = $InferMessageProperty<MyStructure, \"ai\", \"nonExistent\">;\n * // NonExistentProperty = Record<string, unknown>\n *\n * type HumanMetadata = $InferMessageProperty<MyStructure, \"human\", \"metadata\">;\n * // HumanMetadata = Record<string, unknown>\n * ```\n */\nexport type $InferMessageProperty<TStructure extends MessageStructure, TRole extends MessageType, K extends string> = K extends keyof $InferMessageProperties<TStructure, TRole> ? $InferMessageProperties<TStructure, TRole>[K] : never;\n/**\n * Infers the response metadata type for a specific message type from a message structure.\n *\n * This utility type extracts the `response_metadata` property type for a given message type.\n *\n * @template TStructure - The message structure to infer the response metadata from\n * @template TRole - The message type/role to get the response metadata for (e.g., \"ai\", \"human\", \"system\", \"tool\")\n * @returns The type of the response_metadata property, or `Record<string, unknown>` as fallback\n *\n * @example\n * ```ts\n * interface MyStructure extends MessageStructure {\n *   properties: {\n *     ai: {\n *       response_metadata: { model: string; temperature: number; tokens: number };\n *     };\n *     human: { metadata: Record<string, unknown> };\n *   };\n * }\n *\n * type AIResponseMetadata = $InferResponseMetadata<MyStructure, \"ai\">;\n * // AIResponseMetadata = { model: string; temperature: number; tokens: number }\n *\n * type HumanResponseMetadata = $InferResponseMetadata<MyStructure, \"human\">;\n * // HumanResponseMetadata = Record<string, unknown> (fallback since not defined)\n * ```\n */\nexport type $InferResponseMetadata<TStructure extends MessageStructure, TRole extends MessageType> = $InferMessageProperty<TStructure, TRole, \"response_metadata\"> extends infer P ? [P] extends [unknown] ? Record<string, unknown> : P : never;\n/**\n * Represents a message object that organizes context for an LLM.\n *\n * @example\n * ```ts\n * // Basic message with text content\n * const message: Message = {\n *   id: \"msg-123\",\n *   name: \"user\",\n *   type: \"human\",\n *   content: [{ type: \"text\", text: \"Hello!\" }]\n * };\n *\n * // Basic ai message interface extension\n * interface MyMessage extends Message<StandardMessageStructure, \"ai\"> {\n *   // Additional AI-specific properties can be added here\n * }\n *`\n * // Custom message structure\n * interface CustomStructure extends MessageStructure {\n *   content: {\n *     ai: ContentBlock.Text | ContentBlock.ToolCall<\"search\", { query: string }>;\n *     human: ContentBlock.Text | ContentBlock.Multimodal.Image;\n *   };\n * }\n *\n * // Create a message with custom structure\n * const message: Message<CustomStructure> = {\n *   id: \"msg-123\",\n *   name: \"user\",\n *   type: \"ai\",\n *   content: [\n *     { type: \"text\", text: \"Hello!\" },\n *     {\n *       type: \"tool_call\",\n *       name: \"search\",\n *       args: { query: \"What is the capital of France?\" }\n *     }\n *   ]\n * };\n * ```\n */\nexport interface Message<TStructure extends MessageStructure = StandardMessageStructure, TRole extends MessageType = MessageType> {\n    /** The message type/role */\n    readonly type: TRole;\n    /** Unique identifier for this message */\n    id?: string;\n    /** Optional name/identifier for the entity that created this message */\n    name?: string;\n    /** Array of content blocks that make up the message content */\n    content: $InferMessageContent<TStructure, TRole>;\n    /** Metadata about the message */\n    response_metadata?: Partial<$InferResponseMetadata<TStructure, TRole>>;\n}\n/**\n * Type guard to check if a value is a valid Message object.\n *\n * @param message - The value to check\n * @returns true if the value is a valid Message object, false otherwise\n */\nexport declare function isMessage(message: unknown): message is Message;\nexport {};\n"],"mappings":";;;;;;;;AAkBA;AA4BA;AAgBA;;;;AAEmB;AAoBnB;AA6BA;;;;;AACgBc,KAhGJT,WAAAA,GAgGIS,IAAAA,GAAAA,OAAAA,GAAAA,MAAAA,GAAAA,QAAAA,GAAAA,CAAAA,MAAAA,GAhGyDR,WAgGzDQ,CAAAA,OAAAA,CAAAA,CAAAA;;;;;;;;;;AACE;AA8DlB;;;;;;;;;;AAsBiC;AAGhC;;;;;AAK+C;AA4BpCS,KA7LAhB,oBAAAA,GA6LmB,IAAA,GAAA,IAAA;;;;;;;;;;;;;;;AAA8Q;AAsCjSqB,UAnNKpB,qBAmNkB,CAAA,SAAA,OAAA,EAAA,UAAA,OAAA,CAAA,CAAA;EAAA,KAAA,EAlNxBC,MAkNwB;EAAA,MACnBY,EAlNJX,OAkNIW;;;;;;;;;;;;;;;;;;;;AAA2MC,UA9L1MX,cAAAA,CA8L0MW;EAAO,CAAA,GAA8BE,EAAAA,MAAAA,CAAAA,EA7L7OhB,qBA6L6OgB;;;;;;;;;;;;;;;AAAwF;AAqCxV;;;;;;;;;;;;AAGaI,KAzMDhB,qBAyMCgB,CAAAA,mBAzMwCf,gBAyMxCe,CAAAA,GAzM4Dd,UAyM5Dc,CAAAA,OAAAA,CAAAA,SAzMwFjB,cAyMxFiB,GAAAA,QACiBP,MAzMdP,UAyMcO,CAAAA,OAAAA,CAAAA,GAzMQN,CAyMRM,SAAAA,MAAAA,GAzM2BP,UAyM3BO,CAAAA,OAAAA,CAAAA,CAzM+CN,CAyM/CM,CAAAA,SAzM0Db,qBAyM1Da,GAzMkFrB,YAAAA,CAAagB,KAAAA,CAAMC,QAyMrGI,CAzM8GN,CAyM9GM,EAzMiHP,UAyMjHO,CAAAA,OAAAA,CAAAA,CAzMqIN,CAyMrIM,CAAAA,CAAAA,OAAAA,CAAAA,CAAAA,GAAAA,KAAAA,GAAAA,KAAAA,EAAC,CAAA,MAxMvBP,UAwMuCU,CAAAA,OAAAA,CAAAA,CAAAA,GAAAA,KAAAA;;AAAlB;AAQ7B;;;;;;;;;;;;AAAkE;AA2ClE;;;;;;;;;AAAqI;AA2BrI;;;;;;;;;;;;;;;;;;;;;;;;;AAA8X;AAwC9X;;;;;;;;;;AAAmOxB,UAhQlNa,gBAAAA,CAgQ+NkB;EAAI;AAAjC;AAuCnN;;EAAmC,SAAoBlB,aAAAA,CAAAA,EAlS1BN,oBAkS0BM;EAAgB;;;;EAA0F,SAASA,KAAAA,CAAAA,EA7RrJF,cA6RqJE;EAAgB;;;;EAAiE,SAAyBwB,OAAAA,CAAAA,EAxR7PnB,OAwR6PmB,CAAAA,UAvRpQhC,WAuRwRoC,GAvR1QzC,YAuR0QyC,EAAC,CAAA;EAAS;;;;EAA+D,SAAoBtB,UAAAA,CAAAA,EAjR3WD,OAiR2WC,CAAAA,UAhRrXd,WAgR2X,GAhR7Wc,MAgR6W,CAAA,MAAA,EAAA,OAAA,CAAA,EAsC/XwB,CAAAA;;;;;;KA/SPvB,8BA+SqKiB,CAAAA,CAAAA,CAAAA,GA/SjIf,OA+SiIe,CA/SzHhB,CA+SyHgB,EA/StH9B,oBA+SsH8B,CAAAA,GAAAA,SAAAA;;;;;;AAAqD;AA4B/N;;;;;;;;;;AAAwO;AA2CxO;;;;;;;;;;AAUuDvB,KApW3CS,mBAoW2CT,CAAAA,CAAAA,EAAAA,CAAAA,CAAAA,GApWfM,8BAoWeN,CApWgBO,CAoWhBP,CAAAA,SAAAA,KAAAA,GAAAA,GApWsCM,8BAoWtCN,CApWqEU,CAoWrEV,CAAAA,SAAAA,KAAAA,GAAAA,GAAAA,CApW4FW,EAoW5FX,EApWgGY,EAoWhGZ,CAAAA,SAAAA,CAAAA,SAAAA,EAAAA,SAAAA,CAAAA,GAAAA,IAAAA,GAAAA,CApW6IW,EAoW7IX,CAAAA,SAAAA,CAAAA,SAAAA,CAAAA,GApWuKa,OAoWvKb,CApW+KY,EAoW/KZ,EAAAA,SAAAA,CAAAA,GAAAA,CApWiMY,EAoWjMZ,CAAAA,SAAAA,CAAAA,SAAAA,CAAAA,GApW2Na,OAoW3Nb,CApWmOW,EAoWnOX,EAAAA,SAAAA,CAAAA,GApWoPY,EAoWpPZ,GAAAA,KAAAA,GAAAA,KAAAA;;;;AAAxB;AAQ/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAtUYc,8CACIP,UAAUG,KAAKF,SAASP,gBAAgBM,IAAIA,EAAEN,eAAeA,gBAAgBS,IAAIA,EAAET,aAAaf,sCAAsCe,IAAIA,gBAAgBM,IAAIN,gBAAgBS,IAAIrB,yBAAyBmB,QAAQD,EAAEN,IAAIf,eAAesB,QAAQE,EAAET,IAAIf,yBAAyBsB,QAAQD,EAAEN,IAAIf,gBAAgBe,gBAAgBS,IAAIF,QAAQE,EAAET,IAAIf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAqCnV6B,iCAAiChB,4BAA4BA;iBACtDU,oBAAoBF,oBAAoBG;SAChDpB,cAAciB,YAAYG;WACxBI,wBAAwBP,cAAcG;cACnCpB,cAAciB,iBAAiBG;;;;;;;;UAQ9BM,wBAAAA,SAAiCjB;;;QAGtCb,YAAAA,CAAa+B;;WAEV/B,YAAAA,CAAa+B;;YAEZ/B,YAAAA,CAAa+B;;UAEf/B,YAAAA,CAAa+B;;;;;;0BAMK9B;;uBAEHC;;;;0BAIGiB;;;;0BAIAA;;;;0BAIAA;;;;;;;;;;;;;;KAcpBa,sCAAsCnB,oBAAoBQ,UAAUS,2BAA2BT,IAAIQ,uBAAuBC,0BAA0BT;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2BpJY,8CAA8CpB,gCAAgCR,eAAe2B,4BAA4BlB,8BAA8BoB,UAAUrB,mBAAmBqB,+BAA+BC,UAAUhB,OAAOiB,aAAapC,gBAAgBqC,oBAAoBF,KAAKvB,sBAAsBE,+BAA+BqB,EAAEE,SAASlC,yBAAyBG,YAAY6B,EAAEE,SAASzB,sBAAsBE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAwChawB,wCAAwCzB,gCAAgCR,eAAeS,2CAA2CyB,MAAMN,2BAA2BnB,YAAYuB,mBAAmBE,MAAMvC,eAAeA,YAAAA,CAAa+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAuCpOS,2CAA2C3B,gCAAgCR,eAAe2B,4BAA4BlB,8BAA8BoB,UAAUrB,mBAAmBqB,8CAA8CO,UAAUtB,OAAOiB,wBAAwBC,oBAAoBI,IAAIC,KAAKD,EAAEJ,8BAA8BlB,0BAA0BA,0BAA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCzXwB,yCAAyC9B,gCAAgCR,iCAAiCU,gBAAgByB,wBAAwB1B,YAAYuB,SAASG,wBAAwB1B,YAAYuB,OAAOtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BlN6B,0CAA0C/B,gCAAgCR,eAAesC,sBAAsB7B,YAAYuB,+CAA+CI,uBAAuBtB,0BAA0BsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA2CtNI,2BAA2BhC,mBAAmBiB,wCAAwCzB,cAAcA;;iBAElGgC;;;;;;WAMNC,qBAAqBxB,YAAYuB;;sBAEtBnB,QAAQ0B,uBAAuB9B,YAAYuB;;;;;;;;iBAQ3CS,SAAAA,+BAAwCD"}

package/dist/messages/message.d.ts

@@ -0,0 +1,598 @@
+import { ContentBlock } from "./content/index.js";
+import { ResponseMetadata, UsageMetadata } from "./metadata.js";
+import { $MergeDiscriminatedUnion, $MergeObjects } from "./utils.js";
+
+//#region src/messages/message.d.ts
+
+/**
+ * Represents the possible types of messages in the system.
+ * Includes standard message types ("ai", "human", "tool", "system")
+ * and allows for custom string types that are non-null.
+ *
+ * @example
+ * ```ts
+ * // Standard message types
+ * const messageType1: MessageType = "ai";
+ * const messageType2: MessageType = "human";
+ *
+ * // Custom message type
+ * const messageType3: MessageType = "custom_type";
+ * ```
+ */
+type MessageType = "ai" | "human" | "tool" | "system" | (string & NonNullable<unknown>);
+/**
+ * Represents the output version format for message content.
+ *
+ * This type determines how the content field is structured in a message:
+ * - "v0": Content is represented as a simple string or array of content blocks
+ *   - provides backward compatibility with simpler content representations
+ * - "v1": Content follows the structured ContentBlock format with typed discriminated unions
+ *   - enables full type safety and structured content block handling
+ *
+ * @example
+ * ```ts
+ * // v0 format - simple content representation
+ * const v0Message: Message<{ outputVersion: "v0", content: ... }> = {
+ *   type: "human",
+ *   content: "Hello world" // string | Array<ContentBlock | ContentBlock.Text>
+ * };
+ *
+ * // v1 format - structured content blocks
+ * const v1Message: Message<{ outputVersion: "v1", content: ... }> = {
+ *   type: "human",
+ *   content: [
+ *     { type: "text", text: "Hello world" },
+ *     { type: "image", image_url: "..." }
+ *   ] // Array<ContentBlock | ...> (determined by the structure)
+ * };
+ * ```
+ */
+type MessageOutputVersion = "v0" | "v1";
+/**
+ * Represents the input and output types of a tool that can be used in messages.
+ *
+ * @template TInput - The type of input the tool accepts.
+ * @template TOutput - The type of output the tool produces.
+ *
+ * @example
+ * ```ts
+ * // Tool that takes a string input and returns a number
+ * interface StringToNumberTool extends MessageToolDefinition<string, number> {
+ *   input: string;
+ *   output: number;
+ * }
+ * ```
+ */
+interface MessageToolDefinition<TInput = unknown, TOutput = unknown> {
+  input: TInput;
+  output: TOutput;
+}
+/**
+ * Represents a structured set of tools by mapping tool names to definitions
+ * that can be used in messages.
+ *
+ * @example
+ * ```ts
+ * interface MyToolSet extends MessageToolSet {
+ *   calculator: MessageToolDefinition<
+ *     { operation: string; numbers: number[] },
+ *     number
+ *   >;
+ *   translator: MessageToolDefinition<
+ *     { text: string; targetLanguage: string },
+ *     string
+ *   >;
+ * }
+ * ```
+ */
+interface MessageToolSet {
+  [key: string]: MessageToolDefinition;
+}
+/**
+ * Represents a tool call block within a message structure by mapping tool names to their
+ * corresponding tool call formats, including the input arguments and an optional identifier.
+ *
+ * @template TStructure - A message structure type that may contain tool definitions
+ *
+ * @example
+ * ```ts
+ * // Given a message structure with a calculator tool:
+ * interface MyStructure extends MessageStructure {
+ *   tools: {
+ *     calculator: MessageToolDefinition<{ operation: string, numbers: number[] }, number>
+ *   }
+ * }
+ *
+ * // The tool call block would be:
+ * type CalcToolCall = $MessageToolCallBlock<MyStructure>;
+ * // Resolves to:
+ * // {
+ * //   type: "tool_call";
+ * //   name: "calculator";
+ * //   args: { operation: string, numbers: number[] };
+ * //   id?: string;
+ * // }
+ * ```
+ */
+type $MessageToolCallBlock<TStructure extends MessageStructure> = TStructure["tools"] extends MessageToolSet ? { [K in keyof TStructure["tools"]]: K extends string ? TStructure["tools"][K] extends MessageToolDefinition ? ContentBlock.Tools.ToolCall<K, TStructure["tools"][K]["input"]> : never : never }[keyof TStructure["tools"]] : never;
+/**
+ * Core interface that defines the structure of messages.
+ *
+ * @example
+ * ```ts
+ * // Basic message structure with just content blocks
+ * interface SimpleMessageStructure extends MessageStructure {
+ *   content: {
+ *     human: ContentBlock.Text;
+ *     // allows for text + reasoning blocks in ai messages
+ *     ai: ContentBlock.Text | ContentBlock.Reasoning;
+ *   }
+ * }
+ *
+ * // Message structure with tools and properties
+ * interface AdvancedMessageStructure extends MessageStructure {
+ *   tools: {
+ *     calculator: MessageToolDefinition<
+ *       { operation: string; numbers: number[] },
+ *       number
+ *     >;
+ *   };
+ *   content: {
+ *     // allows for text + image blocks in human messages
+ *     human: ContentBlock.Text | ContentBlock.Multimodal.Image;
+ *     // only allows for text blocks in ai messages
+ *     ai: ContentBlock.Text;
+ *   };
+ *   properties: {
+ *     // pins properties to ai messages
+ *     ai: {
+ *       response_metadata: {
+ *         confidence: number;
+ *         model: string;
+ *       };
+ *     };
+ *   }
+ * }
+ *
+ * // Using with $MergeMessageStructure to combine structures
+ * // The resulting type when passed into BaseMessage will have a calculator tool,
+ * // allow for text + image blocks in human messages,
+ * // and text + reasoning blocks + additional arbitrary properties in ai messages.
+ * type CombinedStructure = $MergeMessageStructure<
+ *   SimpleMessageStructure,
+ *   AdvancedMessageStructure
+ * >;
+ *
+ * // Using in a Message object
+ * const message: Message<CombinedStructure> = {
+ *   id: "msg-123",
+ *   type: "human",
+ *   content: [
+ *     { type: "text", text: "Hello!" }
+ *     { type: "image", mimeType: "image/jpeg", url: "https://example.com/image.jpg" }
+ *     // this block will throw an error because it's not defined in the structure
+ *     { type: "reasoning", reasoning: "The answer is 42" }
+ *   ]
+ * };
+ * ```
+ */
+interface MessageStructure {
+  /**
+   * Optional output version for the message structure.
+   * If not provided, defaults to "v0".
+   */
+  readonly outputVersion?: MessageOutputVersion;
+  /**
+   * Optional set of tool definitions that can be used in messages.
+   * Each tool is defined with input/output types and can be referenced in tool messages.
+   */
+  readonly tools?: MessageToolSet;
+  /**
+   * Optional mapping of message types to their allowed content blocks.
+   * Each message type can specify what content block types it supports (text, images, etc).
+   */
+  readonly content?: Partial<{ [key in MessageType]: ContentBlock }>;
+  /**
+   * Optional mapping of message types to arbitrary property objects.
+   * Allows attaching custom metadata or other information to specific message types.
+   */
+  readonly properties?: Partial<{ [key in MessageType]: Record<string, unknown> }>;
+}
+/**
+ * Normalizes an arbitrary type to a message output version or undefined.
+ * Accepts unknown and narrows to a valid MessageOutputVersion if present.
+ */
+type $NormalizeMessageOutputVersion<T> = Extract<T, MessageOutputVersion> | undefined;
+/**
+ * Merges two output version types from message structures.
+ *
+ * This utility type determines the resulting output version when combining two message structures.
+ * The merge logic follows these rules:
+ *
+ * - If both T and U are undefined, defaults to "v0" for backwards compatibility
+ * - If T is undefined but U is defined, uses U's version
+ * - If U is undefined but T is defined, uses T's version
+ * - If both T and U are defined, U takes precedence (later structure wins)
+ *
+ * @template T - The output version from the first message structure
+ * @template U - The output version from the second message structure
+ *
+ * @example
+ * ```ts
+ * // Both undefined - defaults to "v0"
+ * type Result1 = $MergeOutputVersion<undefined, undefined>; // "v0"
+ *
+ * // One defined - uses the defined version
+ * type Result2 = $MergeOutputVersion<undefined, "v1">; // "v1"
+ * type Result3 = $MergeOutputVersion<"v0", undefined>; // "v0"
+ *
+ * // Both defined - second takes precedence
+ * type Result4 = $MergeOutputVersion<"v0", "v1">; // "v1"
+ * ```
+ */
+type $MergeOutputVersion<T, U> = $NormalizeMessageOutputVersion<T> extends infer TV ? $NormalizeMessageOutputVersion<U> extends infer UV ? [TV, UV] extends [undefined, undefined] ? "v0" : [TV] extends [undefined] ? Exclude<UV, undefined> : [UV] extends [undefined] ? Exclude<TV, undefined> : UV : never : never;
+/**
+ * Merges two content definition objects from message structures.
+ *
+ * This utility type combines content definitions from two message structures, handling
+ * the merging of content block types for each message type. The merge logic follows
+ * these rules:
+ *
+ * - For keys that exist in both T and U: Merges the content blocks using discriminated
+ *   union merging based on the "type" property. This allows combining different content
+ *   block types (e.g., text + image) for the same message type.
+ * - For keys that exist only in T: Uses T's content definition as-is
+ * - For keys that exist only in U: Uses U's content definition as-is
+ *
+ * @template T - The content definition from the first message structure
+ * @template U - The content definition from the second message structure
+ *
+ * @example
+ * ```ts
+ * // T allows text content for human messages
+ * type ContentA = {
+ *   human: ContentBlock.Text;
+ * };
+ *
+ * // U allows image content for human messages and text for AI messages
+ * type ContentB = {
+ *   human: ContentBlock.Multimodal.Image;
+ *   ai: ContentBlock.Text;
+ * };
+ *
+ * // Merged result allows both text and images for human messages, text for AI
+ * type Merged = $MergeContentDefinition<ContentA, ContentB>;
+ * // Result: {
+ * //   human: ContentBlock.Text | ContentBlock.Multimodal.Image;
+ * //   ai: ContentBlock.Text;
+ * // }
+ * ```
+ */
+type $MergeContentDefinition<T, U> = { [K in keyof T | keyof U as Extract<(K extends keyof T ? T[K] : never) | (K extends keyof U ? U[K] : never), ContentBlock> extends never ? never : K]: K extends keyof T ? K extends keyof U ? $MergeDiscriminatedUnion<Extract<T[K], ContentBlock>, Extract<U[K], ContentBlock>, "type"> : Extract<T[K], ContentBlock> : K extends keyof U ? Extract<U[K], ContentBlock> : never };
+/**
+ * Merges two message structures A and B into a combined structure.
+ * This is a type utility that handles merging of tools, content blocks, and properties
+ * from two message structures. The resulting type is usable as its own message structure.
+ *
+ * @example
+ * ```ts
+ * // Structure A allows text in human messages and has a confidence property on AI messages
+ * interface StructureA extends MessageStructure {
+ *   content: {
+ *     human: ContentBlock.Text;
+ *   };
+ *   properties: {
+ *     ai: { confidence: number };
+ *   }
+ * }
+ *
+ * // Structure B allows images in human messages and has a model property on AI messages
+ * interface StructureB extends MessageStructure {
+ *   content: {
+ *     human: ContentBlock.Multimodal.Image;
+ *   };
+ *   properties: {
+ *     ai: { model: string };
+ *   }
+ * }
+ *
+ * // Merged structure allows both text and images in human messages
+ * // AI messages have both confidence and model properties
+ * type Merged = $MergeMessageStructure<StructureA, StructureB>;
+ * ```
+ *
+ * @template A - First message structure to merge
+ * @template B - Second message structure to merge (takes precedence over A)
+ */
+type $MergeMessageStructure<T extends MessageStructure, U extends MessageStructure> = {
+  outputVersion: $MergeOutputVersion<T["outputVersion"], U["outputVersion"]>;
+  tools: $MergeObjects<T["tools"], U["tools"]>;
+  content: $MergeContentDefinition<T["content"], U["content"]>;
+  properties: $MergeObjects<T["properties"], U["properties"]>;
+};
+/**
+ * Standard message structured used to define the most basic message structure that's
+ * used throughout the library.
+ *
+ * This is also the message structure that's used when a message structure is not provided.
+ */
+interface StandardMessageStructure extends MessageStructure {
+  content: {
+    /** Text content for AI messages */
+    ai: ContentBlock.Text;
+    /** Text content for human messages */
+    human: ContentBlock.Text;
+    /** Text content for system messages */
+    system: ContentBlock.Text;
+    /** Text content for tool messages */
+    tool: ContentBlock.Text;
+  };
+  properties: {
+    /** Properties specific to AI messages */
+    ai: {
+      /** Metadata about the AI model response */
+      response_metadata?: ResponseMetadata;
+      /** Usage statistics for the AI response */
+      usage_metadata?: UsageMetadata;
+    };
+    human: {
+      /** Metadata about the human message */
+      response_metadata?: Record<string, unknown>;
+    };
+    system: {
+      /** Metadata about the system message */
+      response_metadata?: Record<string, unknown>;
+    };
+    tool: {
+      /** Metadata about the tool message */
+      response_metadata?: Record<string, unknown>;
+    };
+  };
+}
+/**
+ * Takes a message structure type T and normalizes it by merging it with the standard message structure.
+ * If T is already a standard message structure, returns T unchanged.
+ *
+ * This ensures that any custom message structure includes all the standard message structure fields
+ * by default while allowing overrides and extensions.
+ *
+ * @template T - The message structure type to normalize, must extend MessageStructure
+ * @returns Either T if it's already a standard structure, or the merged result of T with standard structure
+ */
+type $NormalizedMessageStructure<T extends MessageStructure> = T extends StandardMessageStructure ? T : $MergeMessageStructure<StandardMessageStructure, T>;
+/**
+ * Infers the content blocks for a specific message type in a message structure.
+ *
+ * This utility type extracts the content block type that corresponds to a given message type
+ * from the message structure's content definition.
+ *
+ * @template TStructure - The message structure to infer content from
+ * @template TRole - The message role/type to get content for (e.g., "ai", "human", "system", "tool")
+ * @returns The content block type for the specified type, or never if its not defined in the structure
+ *
+ * @example
+ * ```ts
+ * interface MyStructure extends MessageStructure {
+ *   content: {
+ *     human: ContentBlock.Text;
+ *     ai: ContentBlock.Text | ContentBlock.ToolCall;
+ *   };
+ * }
+ *
+ * type HumanContent = $InferMessageContentBlocks<MyStructure, "human">;
+ * // HumanContent = ContentBlock.Text
+ *
+ * type AIContent = $InferMessageContentBlocks<MyStructure, "ai">;
+ * // AIContent = ContentBlock.Text | ContentBlock.ToolCall
+ * ```
+ */
+type $InferMessageContentBlocks<TStructure extends MessageStructure, TRole extends MessageType> = $NormalizedMessageStructure<TStructure> extends infer S ? S extends MessageStructure ? S["content"] extends infer C ? C extends Record<PropertyKey, ContentBlock> ? TRole extends keyof C ? [$MessageToolCallBlock<TStructure>] extends [never] ? C[TRole] : $MergeDiscriminatedUnion<NonNullable<C[TRole]>, $MessageToolCallBlock<TStructure>, "type"> : never : never : never : never : never;
+/**
+ * Infers the content type for a specific message type from a message structure.
+ *
+ * This utility type determines the appropriate content type based on the message structure's
+ * output version and the specified message type. The content type varies depending on the
+ * output version (see {@link MessageOutputVersion})
+ *
+ * @template TStructure - The message structure to infer content from
+ * @template TRole - The message role/type to get content for (e.g., "ai", "human", "system", "tool")
+ * @returns The content type for the specified role based on the output version
+ *
+ * @example
+ * ```ts
+ * interface MyStructure extends MessageStructure {
+ *   outputVersion: "v0";
+ *   content: {
+ *     human: ContentBlock.Text;
+ *     ai: ContentBlock.Text | ContentBlock.ToolCall;
+ *   };
+ * }
+ *
+ * type HumanContentV0 = $InferMessageContent<MyStructure, "human">;
+ * // HumanContentV0 = string | Array<ContentBlock | ContentBlock.Text>
+ *
+ * interface MyStructureV1 extends MessageStructure {
+ *   outputVersion: "v1";
+ *   content: {
+ *     human: ContentBlock.Text;
+ *     ai: ContentBlock.Text | ContentBlock.Reasoning;
+ *   };
+ * }
+ *
+ * type HumanContentV1 = $InferMessageContent<MyStructureV1, "human">;
+ * // HumanContentV1 = ContentBlock.Text
+ *
+ * type AIContentV1 = $InferMessageContent<MyStructureV1, "ai">;
+ * // AIContentV1 = ContentBlock.Text | ContentBlock.Reasoning
+ * ```
+ */
+type $InferMessageContent<TStructure extends MessageStructure, TRole extends MessageType> = TStructure["outputVersion"] extends "v1" ? Array<$InferMessageContentBlocks<TStructure, TRole>> : string | Array<ContentBlock | ContentBlock.Text>;
+/**
+ * Infers the properties for a specific message type from a message structure.
+ *
+ * This utility type extracts the properties object that corresponds to a given message type
+ * from the message structure's properties definition, and excludes the reserved
+ * "content" and "type" properties to avoid conflicts with the core message structure.
+ *
+ * If the specified type is not defined in the message structure's properties, it returns
+ * a generic Record<string, unknown> type to allow for arbitrary properties.
+ *
+ * @template TStructure - The message structure to infer properties from
+ * @template TRole - The message type/role to get properties for (e.g., "ai", "human", "system", "tool")
+ * @returns The properties object type for the specified type, excluding "content" and "type"
+ *
+ * @example
+ * ```ts
+ * interface MyStructure extends MessageStructure {
+ *   properties: {
+ *     ai: {
+ *       response_metadata: { model: string };
+ *       usage_metadata: { tokens: number };
+ *       content: string; // This will be omitted
+ *       type: string;    // This will be omitted
+ *     };
+ *     human: { metadata: Record<string, unknown> };
+ *   };
+ * }
+ *
+ * type AIProperties = $InferMessageProperties<MyStructure, "ai">;
+ * // AIProperties = { response_metadata: { model: string }; usage_metadata: { tokens: number } }
+ *
+ * type HumanProperties = $InferMessageProperties<MyStructure, "human">;
+ * // HumanProperties = { metadata: Record<string, unknown> }
+ *
+ * type SystemProperties = $InferMessageProperties<MyStructure, "system">;
+ * // SystemProperties = Record<string, unknown> (fallback for undefined role)
+ * ```
+ */
+type $InferMessageProperties<TStructure extends MessageStructure, TRole extends MessageType> = $NormalizedMessageStructure<TStructure> extends infer S ? S extends MessageStructure ? S["properties"] extends infer P | undefined ? P extends Record<PropertyKey, unknown> ? TRole extends keyof P ? Omit<P[TRole], "content" | "type"> : Record<string, unknown> : Record<string, unknown> : Record<string, unknown> : never : never;
+/**
+ * Infers the type of a specific property for a message type from a message structure.
+ *
+ * This utility type extracts the type of a single property by name from the properties
+ * object that corresponds to a given message type. If the specified property key does
+ * not exist in the type's properties, it returns `never`.
+ *
+ * @template TStructure - The message structure to infer the property from
+ * @template TRole - The message type/role to get the property for (e.g., "ai", "human", "system", "tool")
+ * @template K - The property key to extract the type for
+ * @returns The type of the specified property, or `never` if the property doesn't exist
+ *
+ * @example
+ * ```ts
+ * interface MyStructure extends MessageStructure {
+ *   properties: {
+ *     ai: {
+ *       response_metadata: { model: string; temperature: number };
+ *       usage_metadata: { input_tokens: number; output_tokens: number };
+ *     };
+ *     human: { metadata: Record<string, unknown> };
+ *   };
+ * }
+ *
+ * type ResponseMetadata = $InferMessageProperty<MyStructure, "ai", "response_metadata">;
+ * // ResponseMetadata = { model: string; temperature: number }
+ *
+ * type UsageMetadata = $InferMessageProperty<MyStructure, "ai", "usage_metadata">;
+ * // UsageMetadata = { input_tokens: number; output_tokens: number }
+ *
+ * type NonExistentProperty = $InferMessageProperty<MyStructure, "ai", "nonExistent">;
+ * // NonExistentProperty = Record<string, unknown>
+ *
+ * type HumanMetadata = $InferMessageProperty<MyStructure, "human", "metadata">;
+ * // HumanMetadata = Record<string, unknown>
+ * ```
+ */
+type $InferMessageProperty<TStructure extends MessageStructure, TRole extends MessageType, K extends string> = K extends keyof $InferMessageProperties<TStructure, TRole> ? $InferMessageProperties<TStructure, TRole>[K] : never;
+/**
+ * Infers the response metadata type for a specific message type from a message structure.
+ *
+ * This utility type extracts the `response_metadata` property type for a given message type.
+ *
+ * @template TStructure - The message structure to infer the response metadata from
+ * @template TRole - The message type/role to get the response metadata for (e.g., "ai", "human", "system", "tool")
+ * @returns The type of the response_metadata property, or `Record<string, unknown>` as fallback
+ *
+ * @example
+ * ```ts
+ * interface MyStructure extends MessageStructure {
+ *   properties: {
+ *     ai: {
+ *       response_metadata: { model: string; temperature: number; tokens: number };
+ *     };
+ *     human: { metadata: Record<string, unknown> };
+ *   };
+ * }
+ *
+ * type AIResponseMetadata = $InferResponseMetadata<MyStructure, "ai">;
+ * // AIResponseMetadata = { model: string; temperature: number; tokens: number }
+ *
+ * type HumanResponseMetadata = $InferResponseMetadata<MyStructure, "human">;
+ * // HumanResponseMetadata = Record<string, unknown> (fallback since not defined)
+ * ```
+ */
+type $InferResponseMetadata<TStructure extends MessageStructure, TRole extends MessageType> = $InferMessageProperty<TStructure, TRole, "response_metadata"> extends infer P ? [P] extends [unknown] ? Record<string, unknown> : P : never;
+/**
+ * Represents a message object that organizes context for an LLM.
+ *
+ * @example
+ * ```ts
+ * // Basic message with text content
+ * const message: Message = {
+ *   id: "msg-123",
+ *   name: "user",
+ *   type: "human",
+ *   content: [{ type: "text", text: "Hello!" }]
+ * };
+ *
+ * // Basic ai message interface extension
+ * interface MyMessage extends Message<StandardMessageStructure, "ai"> {
+ *   // Additional AI-specific properties can be added here
+ * }
+ *`
+ * // Custom message structure
+ * interface CustomStructure extends MessageStructure {
+ *   content: {
+ *     ai: ContentBlock.Text | ContentBlock.ToolCall<"search", { query: string }>;
+ *     human: ContentBlock.Text | ContentBlock.Multimodal.Image;
+ *   };
+ * }
+ *
+ * // Create a message with custom structure
+ * const message: Message<CustomStructure> = {
+ *   id: "msg-123",
+ *   name: "user",
+ *   type: "ai",
+ *   content: [
+ *     { type: "text", text: "Hello!" },
+ *     {
+ *       type: "tool_call",
+ *       name: "search",
+ *       args: { query: "What is the capital of France?" }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
+interface Message<TStructure extends MessageStructure = StandardMessageStructure, TRole extends MessageType = MessageType> {
+  /** The message type/role */
+  readonly type: TRole;
+  /** Unique identifier for this message */
+  id?: string;
+  /** Optional name/identifier for the entity that created this message */
+  name?: string;
+  /** Array of content blocks that make up the message content */
+  content: $InferMessageContent<TStructure, TRole>;
+  /** Metadata about the message */
+  response_metadata?: Partial<$InferResponseMetadata<TStructure, TRole>>;
+}
+/**
+ * Type guard to check if a value is a valid Message object.
+ *
+ * @param message - The value to check
+ * @returns true if the value is a valid Message object, false otherwise
+ */
+declare function isMessage(message: unknown): message is Message;
+//#endregion
+export { $InferMessageContent, $InferMessageContentBlocks, $InferMessageProperties, $InferMessageProperty, $InferResponseMetadata, $MergeContentDefinition, $MergeMessageStructure, $MergeOutputVersion, $MessageToolCallBlock, $NormalizedMessageStructure, Message, MessageOutputVersion, MessageStructure, MessageToolDefinition, MessageToolSet, MessageType, StandardMessageStructure, isMessage };
+//# sourceMappingURL=message.d.ts.map