llm-exe 3.0.0 → 3.0.1

package/dist/index.d.mts

@@ -14,11 +14,18 @@ interface Serializable {
 }
 
 type IChatMessageRole = "system" | "model" | "assistant" | "user" | "function" | "function_call";
+/**
+ * Loose content-block shape accepted everywhere content blocks are taken.
+ * Prefer `IChatMessageContent`; this stays loose (`type: string`) for
+ * backwards compatibility with previously-accepted shapes like
+ * `{ type: "image", image_url: {...} }`, which providers normalize.
+ */
 interface IChatMessageContentDetailed {
     type: string;
     text?: string;
     image_url?: {
         url: string;
+        detail?: "low" | "high" | "auto";
     };
 }
 interface IChatMessageBase {
@@ -670,7 +677,7 @@ declare function createChatPrompt<I extends Record<string, any>>(initialSystemPr
  * @template O - Output type.
  * @template H - Hooks type.
  */
-declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends BaseExecutorHooks = BaseExecutorHooks> {
+declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends BaseExecutorHooks = BaseExecutorHooks, R = any, HI = any> {
     /**
      * @property id - internal id of the executor
      */
@@ -701,7 +708,7 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      * @property maxHooksPerEvent - Maximum number of hooks allowed per event
      */
     readonly maxHooksPerEvent: number;
-    constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<H>);
+    constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<I, O, R, HI, H>);
     abstract handler(input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<any>;
     /**
      * Build a per-call execution context snapshot. Captures the current
@@ -745,7 +752,7 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
     metadata(): Record<string, any>;
     getMetadata(metadata?: Record<string, any>): ExecutorMetadata;
     runHook(hook: keyof H, _metadata: ExecutorExecutionMetadata): HookErrorRecord[];
-    setHooks(hooks?: CoreExecutorHookInput<H>): this;
+    setHooks(hooks?: CoreExecutorHookInput<I, O, R, HI, H>): this;
     removeHook(eventName: keyof H, fn: ListenerFunction): this;
     on(eventName: keyof H, fn: ListenerFunction): this;
     off(eventName: keyof H, fn: ListenerFunction): this;
@@ -770,9 +777,9 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
  * Core Function Executor
  */
 declare class CoreExecutor<I extends PlainObject, O> extends BaseExecutor<I, O> {
-    _handler: (input: I) => Promise<any> | any;
-    constructor(fn: CoreExecutorInput<I, O>, options?: CoreExecutorExecuteOptions);
-    handler(_input: I): Promise<O>;
+    _handler: (input: I, context?: ExecutionContext<I, O>) => Promise<any> | any;
+    constructor(fn: CoreExecutorInput<I, O>, options?: CoreExecutorExecuteOptions<I, O>);
+    handler(_input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<O>;
 }
 
 declare abstract class BaseStateItem<T> implements Serializable {
@@ -903,12 +910,12 @@ declare function createStateItem<T>(name: string, defaultValue: T): DefaultState
 /**
  * Core Executor With LLM
  */
-declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser<any, any>, State extends BaseState> extends BaseExecutor<PromptInput<Prompt>, ParserOutput<Parser>, LlmExecutorHooks> {
+declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser<any, any>, State extends BaseState> extends BaseExecutor<PromptInput<Prompt>, ParserOutput<Parser>, LlmExecutorHooks, BaseLlCall, ReturnType<Prompt["format"]>> {
     llm: Llm;
     prompt: Prompt | undefined;
     promptFn: any;
     parser: StringParser | Parser;
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<Parser>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     /**
      * Runs the executor against the configured LLM and prompt.
      *
@@ -931,14 +938,14 @@ declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Re
  * Core Executor With LLM
  */
 declare class LlmExecutorWithFunctions<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState = BaseState> extends LlmExecutor<Llm, Prompt, LlmFunctionParser<Parser>, State> {
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     execute<T extends GenericFunctionCall>(_input: PromptInput<Prompt>, _options: LlmExecutorWithFunctionsOptions<T>): Promise<OutputResultContent[] | ParserOutput<Parser>>;
 }
 /**
  * @deprecated Use `LlmExecutorWithFunctions` instead.
  */
 declare class LlmExecutorOpenAiFunctions<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState = BaseState> extends LlmExecutor<Llm, Prompt, LlmNativeFunctionParser<Parser>, State> {
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmNativeFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     execute<T extends GenericFunctionCall>(_input: PromptInput<Prompt>, _options: LlmExecutorWithFunctionsOptions<T>): Promise<ParserOutput<Parser> | {
         name: string;
         arguments: any;
@@ -952,7 +959,7 @@ declare class LlmExecutorOpenAiFunctions<Llm extends BaseLlm, Prompt extends Bas
  * @param handler - The handler function.
  * @returns - A new CoreExecutor instance.
  */
-declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I) => Promise<O> | O, options?: CoreExecutorExecuteOptions): CoreExecutor<I, O>;
+declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I, context?: ExecutionContext<I, O>) => Promise<O> | O, options?: CoreExecutorExecuteOptions<I, O>): CoreExecutor<I, O>;
 /**
  * Function to create a core executor with Llm.
  * @template Llm - Llm type.
@@ -962,8 +969,8 @@ declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I
  * @param options - Options for BaseExecutorV3.
  * @returns  - A new LlmExecutor instance.
  */
-declare function createLlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<any>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>): LlmExecutor<Llm, Prompt, Parser, State>;
-declare function createLlmFunctionExecutor<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>): LlmExecutorWithFunctions<Llm, Prompt, Parser, State>;
+declare function createLlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<any>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<Parser>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>): LlmExecutor<Llm, Prompt, Parser, State>;
+declare function createLlmFunctionExecutor<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>): LlmExecutorWithFunctions<Llm, Prompt, Parser, State>;
 
 declare const hookOnComplete = "onComplete";
 declare const hookOnError = "onError";
@@ -982,7 +989,7 @@ interface ExecutorWithLlmOptions<Llm, Prompt, Parser, State> {
 }
 interface CoreExecutorInput<I, O> {
     name?: string;
-    handler: (input: I) => Promise<O> | O;
+    handler: (input: I, context?: ExecutionContext<I, O>) => Promise<O> | O;
     getHandlerInput?(input: I): Promise<any>;
     getHandlerOutput?(out: any): O;
 }
@@ -1006,12 +1013,12 @@ interface HookErrorRecord {
     errorContext?: unknown;
     errorCause?: unknown;
 }
-interface ExecutorExecutionMetadata<I = any, O = any> {
+interface ExecutorExecutionMetadata<I = any, O = any, R = any, HI = any> {
     start: null | number;
     end: null | number;
     input: I;
-    handlerInput?: any;
-    handlerOutput?: any;
+    handlerInput?: HI;
+    handlerOutput?: R;
     output?: O;
     errorMessage?: string;
     error?: Error;
@@ -1045,11 +1052,20 @@ interface BaseExecutorHooks {
 }
 interface LlmExecutorHooks extends BaseExecutorHooks {
 }
-type CoreExecutorHookInput<H = BaseExecutorHooks> = {
-    [key in keyof H]?: ListenerFunction | ListenerFunction[];
+/**
+ * A single executor hook callback. Receives the per-run execution metadata
+ * (input/output/error fields typed via I/O) followed by the executor's own
+ * identity metadata. This is the shape fired for onSuccess / onError /
+ * onComplete — the metadata fields that are populated differ per event
+ * (`output` on success, `error` on failure), but all are optional on
+ * {@link ExecutorExecutionMetadata}, so one signature covers every hook.
+ */
+type ExecutorHookFunction<I = any, O = any, R = any, HI = any> = (metadata: ExecutorExecutionMetadata<I, O, R, HI>, executor: ExecutorMetadata) => void;
+type CoreExecutorHookInput<I = any, O = any, R = any, HI = any, H = BaseExecutorHooks> = {
+    [key in keyof H]?: ExecutorHookFunction<I, O, R, HI> | ExecutorHookFunction<I, O, R, HI>[];
 };
-interface CoreExecutorExecuteOptions<T = BaseExecutorHooks> {
-    hooks?: CoreExecutorHookInput<T>;
+interface CoreExecutorExecuteOptions<I = any, O = any, R = any, HI = any, T = BaseExecutorHooks> {
+    hooks?: CoreExecutorHookInput<I, O, R, HI, T>;
 }
 interface CallableExecutorCore {
     name: string;
@@ -1073,6 +1089,18 @@ interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"
 
 interface ParserSchemaOptions<S extends JSONSchema | undefined = undefined> {
     schema?: S;
+    /**
+     * Controls schema enforcement when `schema` is provided. Validation —
+     * including `required` fields and type/constraint checks — is **on by
+     * default** whenever a schema is set; invalid or incomplete input throws a
+     * `parser.schema_validation_failed` error.
+     *
+     * Set `validateSchema: false` to opt out into the legacy filter/default-only
+     * behavior: unknown keys are stripped and defaults applied, but `required`
+     * fields and constraints are NOT checked. Has no effect when no schema is set.
+     *
+     * @default true (when `schema` is provided)
+     */
     validateSchema?: boolean;
 }
 type JsonParserMatch = "exact" | "extract";
@@ -1771,6 +1799,9 @@ type LlmExeErrorJson<C extends ErrorCodes = ErrorCodes> = {
     cause?: SerializableCause;
     truncated?: boolean;
 };
+type SerializeOptions = {
+    includeStack?: boolean;
+};
 
 declare function enforceResultAttributes<O>(input: any): {
     result: O;
@@ -1910,6 +1941,8 @@ declare function importHelpers(_helpers: {
 
 declare function filterObjectOnSchema(schema: any, doc: any, detach?: any, property?: string): any;
 
+declare function escapeTemplateString(input: string): string;
+
 declare const asyncCallWithTimeout: <T = any>(asyncPromise: Promise<T>, timeLimit?: number) => Promise<T>;
 
 declare function guessProviderFromModel(payload: {
@@ -1929,6 +1962,7 @@ declare const index_LlmExeError: typeof LlmExeError;
 declare const index_assert: typeof assert;
 declare const index_asyncCallWithTimeout: typeof asyncCallWithTimeout;
 declare const index_defineSchema: typeof defineSchema;
+declare const index_escapeTemplateString: typeof escapeTemplateString;
 declare const index_filterObjectOnSchema: typeof filterObjectOnSchema;
 declare const index_guessProviderFromModel: typeof guessProviderFromModel;
 declare const index_importHelpers: typeof importHelpers;
@@ -1942,7 +1976,7 @@ declare const index_registerPartials: typeof registerPartials;
 declare const index_replaceTemplateString: typeof replaceTemplateString;
 declare const index_replaceTemplateStringAsync: typeof replaceTemplateStringAsync;
 declare namespace index {
-  export { index_LLM_EXE_ERROR_SYMBOL as LLM_EXE_ERROR_SYMBOL, index_LlmExeError as LlmExeError, index_assert as assert, index_asyncCallWithTimeout as asyncCallWithTimeout, index_defineSchema as defineSchema, index_filterObjectOnSchema as filterObjectOnSchema, index_guessProviderFromModel as guessProviderFromModel, index_importHelpers as importHelpers, index_importPartials as importPartials, index_isLlmExeError as isLlmExeError, index_isObjectStringified as isObjectStringified, index_maybeParseJSON as maybeParseJSON, index_maybeStringifyJSON as maybeStringifyJSON, index_registerHelpers as registerHelpers, index_registerPartials as registerPartials, index_replaceTemplateString as replaceTemplateString, index_replaceTemplateStringAsync as replaceTemplateStringAsync };
+  export { index_LLM_EXE_ERROR_SYMBOL as LLM_EXE_ERROR_SYMBOL, index_LlmExeError as LlmExeError, index_assert as assert, index_asyncCallWithTimeout as asyncCallWithTimeout, index_defineSchema as defineSchema, index_escapeTemplateString as escapeTemplateString, index_filterObjectOnSchema as filterObjectOnSchema, index_guessProviderFromModel as guessProviderFromModel, index_importHelpers as importHelpers, index_importPartials as importPartials, index_isLlmExeError as isLlmExeError, index_isObjectStringified as isObjectStringified, index_maybeParseJSON as maybeParseJSON, index_maybeStringifyJSON as maybeStringifyJSON, index_registerHelpers as registerHelpers, index_registerPartials as registerPartials, index_replaceTemplateString as replaceTemplateString, index_replaceTemplateStringAsync as replaceTemplateStringAsync };
 }
 
 declare function isOutputResult(obj: any): obj is OutputResult;
@@ -2092,4 +2126,8 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };
+declare function serializeLlmExeError(error: unknown, options?: SerializeOptions): JsonSafe;
+
+declare function formatLlmExeErrorForLog(error: unknown): string;
+
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, formatLlmExeErrorForLog, guards, isLlmExeError, registerHelpers, registerPartials, serializeLlmExeError, useExecutors, useLlm, useLlmConfiguration, index as utils };

package/dist/index.d.ts

@@ -14,11 +14,18 @@ interface Serializable {
 }
 
 type IChatMessageRole = "system" | "model" | "assistant" | "user" | "function" | "function_call";
+/**
+ * Loose content-block shape accepted everywhere content blocks are taken.
+ * Prefer `IChatMessageContent`; this stays loose (`type: string`) for
+ * backwards compatibility with previously-accepted shapes like
+ * `{ type: "image", image_url: {...} }`, which providers normalize.
+ */
 interface IChatMessageContentDetailed {
     type: string;
     text?: string;
     image_url?: {
         url: string;
+        detail?: "low" | "high" | "auto";
     };
 }
 interface IChatMessageBase {
@@ -670,7 +677,7 @@ declare function createChatPrompt<I extends Record<string, any>>(initialSystemPr
  * @template O - Output type.
  * @template H - Hooks type.
  */
-declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends BaseExecutorHooks = BaseExecutorHooks> {
+declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends BaseExecutorHooks = BaseExecutorHooks, R = any, HI = any> {
     /**
      * @property id - internal id of the executor
      */
@@ -701,7 +708,7 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      * @property maxHooksPerEvent - Maximum number of hooks allowed per event
      */
     readonly maxHooksPerEvent: number;
-    constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<H>);
+    constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<I, O, R, HI, H>);
     abstract handler(input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<any>;
     /**
      * Build a per-call execution context snapshot. Captures the current
@@ -745,7 +752,7 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
     metadata(): Record<string, any>;
     getMetadata(metadata?: Record<string, any>): ExecutorMetadata;
     runHook(hook: keyof H, _metadata: ExecutorExecutionMetadata): HookErrorRecord[];
-    setHooks(hooks?: CoreExecutorHookInput<H>): this;
+    setHooks(hooks?: CoreExecutorHookInput<I, O, R, HI, H>): this;
     removeHook(eventName: keyof H, fn: ListenerFunction): this;
     on(eventName: keyof H, fn: ListenerFunction): this;
     off(eventName: keyof H, fn: ListenerFunction): this;
@@ -770,9 +777,9 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
  * Core Function Executor
  */
 declare class CoreExecutor<I extends PlainObject, O> extends BaseExecutor<I, O> {
-    _handler: (input: I) => Promise<any> | any;
-    constructor(fn: CoreExecutorInput<I, O>, options?: CoreExecutorExecuteOptions);
-    handler(_input: I): Promise<O>;
+    _handler: (input: I, context?: ExecutionContext<I, O>) => Promise<any> | any;
+    constructor(fn: CoreExecutorInput<I, O>, options?: CoreExecutorExecuteOptions<I, O>);
+    handler(_input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<O>;
 }
 
 declare abstract class BaseStateItem<T> implements Serializable {
@@ -903,12 +910,12 @@ declare function createStateItem<T>(name: string, defaultValue: T): DefaultState
 /**
  * Core Executor With LLM
  */
-declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser<any, any>, State extends BaseState> extends BaseExecutor<PromptInput<Prompt>, ParserOutput<Parser>, LlmExecutorHooks> {
+declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser<any, any>, State extends BaseState> extends BaseExecutor<PromptInput<Prompt>, ParserOutput<Parser>, LlmExecutorHooks, BaseLlCall, ReturnType<Prompt["format"]>> {
     llm: Llm;
     prompt: Prompt | undefined;
     promptFn: any;
     parser: StringParser | Parser;
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<Parser>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     /**
      * Runs the executor against the configured LLM and prompt.
      *
@@ -931,14 +938,14 @@ declare class LlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<Re
  * Core Executor With LLM
  */
 declare class LlmExecutorWithFunctions<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState = BaseState> extends LlmExecutor<Llm, Prompt, LlmFunctionParser<Parser>, State> {
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     execute<T extends GenericFunctionCall>(_input: PromptInput<Prompt>, _options: LlmExecutorWithFunctionsOptions<T>): Promise<OutputResultContent[] | ParserOutput<Parser>>;
 }
 /**
  * @deprecated Use `LlmExecutorWithFunctions` instead.
  */
 declare class LlmExecutorOpenAiFunctions<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState = BaseState> extends LlmExecutor<Llm, Prompt, LlmNativeFunctionParser<Parser>, State> {
-    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmNativeFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>);
     execute<T extends GenericFunctionCall>(_input: PromptInput<Prompt>, _options: LlmExecutorWithFunctionsOptions<T>): Promise<ParserOutput<Parser> | {
         name: string;
         arguments: any;
@@ -952,7 +959,7 @@ declare class LlmExecutorOpenAiFunctions<Llm extends BaseLlm, Prompt extends Bas
  * @param handler - The handler function.
  * @returns - A new CoreExecutor instance.
  */
-declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I) => Promise<O> | O, options?: CoreExecutorExecuteOptions): CoreExecutor<I, O>;
+declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I, context?: ExecutionContext<I, O>) => Promise<O> | O, options?: CoreExecutorExecuteOptions<I, O>): CoreExecutor<I, O>;
 /**
  * Function to create a core executor with Llm.
  * @template Llm - Llm type.
@@ -962,8 +969,8 @@ declare function createCoreExecutor<I extends PlainObject, O>(handler: (input: I
  * @param options - Options for BaseExecutorV3.
  * @returns  - A new LlmExecutor instance.
  */
-declare function createLlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<any>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>): LlmExecutor<Llm, Prompt, Parser, State>;
-declare function createLlmFunctionExecutor<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>): LlmExecutorWithFunctions<Llm, Prompt, Parser, State>;
+declare function createLlmExecutor<Llm extends BaseLlm<any>, Prompt extends BasePrompt<any>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<Parser>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>): LlmExecutor<Llm, Prompt, Parser, State>;
+declare function createLlmFunctionExecutor<Llm extends BaseLlm, Prompt extends BasePrompt<Record<string, any>>, Parser extends BaseParser, State extends BaseState>(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<PromptInput<Prompt>, ParserOutput<LlmFunctionParser<Parser>>, BaseLlCall, ReturnType<Prompt["format"]>, LlmExecutorHooks>): LlmExecutorWithFunctions<Llm, Prompt, Parser, State>;
 
 declare const hookOnComplete = "onComplete";
 declare const hookOnError = "onError";
@@ -982,7 +989,7 @@ interface ExecutorWithLlmOptions<Llm, Prompt, Parser, State> {
 }
 interface CoreExecutorInput<I, O> {
     name?: string;
-    handler: (input: I) => Promise<O> | O;
+    handler: (input: I, context?: ExecutionContext<I, O>) => Promise<O> | O;
     getHandlerInput?(input: I): Promise<any>;
     getHandlerOutput?(out: any): O;
 }
@@ -1006,12 +1013,12 @@ interface HookErrorRecord {
     errorContext?: unknown;
     errorCause?: unknown;
 }
-interface ExecutorExecutionMetadata<I = any, O = any> {
+interface ExecutorExecutionMetadata<I = any, O = any, R = any, HI = any> {
     start: null | number;
     end: null | number;
     input: I;
-    handlerInput?: any;
-    handlerOutput?: any;
+    handlerInput?: HI;
+    handlerOutput?: R;
     output?: O;
     errorMessage?: string;
     error?: Error;
@@ -1045,11 +1052,20 @@ interface BaseExecutorHooks {
 }
 interface LlmExecutorHooks extends BaseExecutorHooks {
 }
-type CoreExecutorHookInput<H = BaseExecutorHooks> = {
-    [key in keyof H]?: ListenerFunction | ListenerFunction[];
+/**
+ * A single executor hook callback. Receives the per-run execution metadata
+ * (input/output/error fields typed via I/O) followed by the executor's own
+ * identity metadata. This is the shape fired for onSuccess / onError /
+ * onComplete — the metadata fields that are populated differ per event
+ * (`output` on success, `error` on failure), but all are optional on
+ * {@link ExecutorExecutionMetadata}, so one signature covers every hook.
+ */
+type ExecutorHookFunction<I = any, O = any, R = any, HI = any> = (metadata: ExecutorExecutionMetadata<I, O, R, HI>, executor: ExecutorMetadata) => void;
+type CoreExecutorHookInput<I = any, O = any, R = any, HI = any, H = BaseExecutorHooks> = {
+    [key in keyof H]?: ExecutorHookFunction<I, O, R, HI> | ExecutorHookFunction<I, O, R, HI>[];
 };
-interface CoreExecutorExecuteOptions<T = BaseExecutorHooks> {
-    hooks?: CoreExecutorHookInput<T>;
+interface CoreExecutorExecuteOptions<I = any, O = any, R = any, HI = any, T = BaseExecutorHooks> {
+    hooks?: CoreExecutorHookInput<I, O, R, HI, T>;
 }
 interface CallableExecutorCore {
     name: string;
@@ -1073,6 +1089,18 @@ interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"
 
 interface ParserSchemaOptions<S extends JSONSchema | undefined = undefined> {
     schema?: S;
+    /**
+     * Controls schema enforcement when `schema` is provided. Validation —
+     * including `required` fields and type/constraint checks — is **on by
+     * default** whenever a schema is set; invalid or incomplete input throws a
+     * `parser.schema_validation_failed` error.
+     *
+     * Set `validateSchema: false` to opt out into the legacy filter/default-only
+     * behavior: unknown keys are stripped and defaults applied, but `required`
+     * fields and constraints are NOT checked. Has no effect when no schema is set.
+     *
+     * @default true (when `schema` is provided)
+     */
     validateSchema?: boolean;
 }
 type JsonParserMatch = "exact" | "extract";
@@ -1771,6 +1799,9 @@ type LlmExeErrorJson<C extends ErrorCodes = ErrorCodes> = {
     cause?: SerializableCause;
     truncated?: boolean;
 };
+type SerializeOptions = {
+    includeStack?: boolean;
+};
 
 declare function enforceResultAttributes<O>(input: any): {
     result: O;
@@ -1910,6 +1941,8 @@ declare function importHelpers(_helpers: {
 
 declare function filterObjectOnSchema(schema: any, doc: any, detach?: any, property?: string): any;
 
+declare function escapeTemplateString(input: string): string;
+
 declare const asyncCallWithTimeout: <T = any>(asyncPromise: Promise<T>, timeLimit?: number) => Promise<T>;
 
 declare function guessProviderFromModel(payload: {
@@ -1929,6 +1962,7 @@ declare const index_LlmExeError: typeof LlmExeError;
 declare const index_assert: typeof assert;
 declare const index_asyncCallWithTimeout: typeof asyncCallWithTimeout;
 declare const index_defineSchema: typeof defineSchema;
+declare const index_escapeTemplateString: typeof escapeTemplateString;
 declare const index_filterObjectOnSchema: typeof filterObjectOnSchema;
 declare const index_guessProviderFromModel: typeof guessProviderFromModel;
 declare const index_importHelpers: typeof importHelpers;
@@ -1942,7 +1976,7 @@ declare const index_registerPartials: typeof registerPartials;
 declare const index_replaceTemplateString: typeof replaceTemplateString;
 declare const index_replaceTemplateStringAsync: typeof replaceTemplateStringAsync;
 declare namespace index {
-  export { index_LLM_EXE_ERROR_SYMBOL as LLM_EXE_ERROR_SYMBOL, index_LlmExeError as LlmExeError, index_assert as assert, index_asyncCallWithTimeout as asyncCallWithTimeout, index_defineSchema as defineSchema, index_filterObjectOnSchema as filterObjectOnSchema, index_guessProviderFromModel as guessProviderFromModel, index_importHelpers as importHelpers, index_importPartials as importPartials, index_isLlmExeError as isLlmExeError, index_isObjectStringified as isObjectStringified, index_maybeParseJSON as maybeParseJSON, index_maybeStringifyJSON as maybeStringifyJSON, index_registerHelpers as registerHelpers, index_registerPartials as registerPartials, index_replaceTemplateString as replaceTemplateString, index_replaceTemplateStringAsync as replaceTemplateStringAsync };
+  export { index_LLM_EXE_ERROR_SYMBOL as LLM_EXE_ERROR_SYMBOL, index_LlmExeError as LlmExeError, index_assert as assert, index_asyncCallWithTimeout as asyncCallWithTimeout, index_defineSchema as defineSchema, index_escapeTemplateString as escapeTemplateString, index_filterObjectOnSchema as filterObjectOnSchema, index_guessProviderFromModel as guessProviderFromModel, index_importHelpers as importHelpers, index_importPartials as importPartials, index_isLlmExeError as isLlmExeError, index_isObjectStringified as isObjectStringified, index_maybeParseJSON as maybeParseJSON, index_maybeStringifyJSON as maybeStringifyJSON, index_registerHelpers as registerHelpers, index_registerPartials as registerPartials, index_replaceTemplateString as replaceTemplateString, index_replaceTemplateStringAsync as replaceTemplateStringAsync };
 }
 
 declare function isOutputResult(obj: any): obj is OutputResult;
@@ -2092,4 +2126,8 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };
+declare function serializeLlmExeError(error: unknown, options?: SerializeOptions): JsonSafe;
+
+declare function formatLlmExeErrorForLog(error: unknown): string;
+
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, formatLlmExeErrorForLog, guards, isLlmExeError, registerHelpers, registerPartials, serializeLlmExeError, useExecutors, useLlm, useLlmConfiguration, index as utils };

package/dist/index.js

@@ -67,10 +67,12 @@ __export(index_exports, {
   createState: () => createState,
   createStateItem: () => createStateItem,
   defineSchema: () => defineSchema,
+  formatLlmExeErrorForLog: () => formatLlmExeErrorForLog,
   guards: () => guards_exports,
   isLlmExeError: () => isLlmExeError,
   registerHelpers: () => registerHelpers,
   registerPartials: () => registerPartials,
+  serializeLlmExeError: () => serializeLlmExeError,
   useExecutors: () => useExecutors,
   useLlm: () => useLlm,
   useLlmConfiguration: () => useLlmConfiguration,
@@ -530,6 +532,48 @@ function formatErrorList(values, options) {
   }
   return parts.join(", ");
 }
+function formatLlmExeErrorForLog(error) {
+  if (!error || typeof error !== "object") {
+    return formatErrorValue(error);
+  }
+  const e = error;
+  const name = typeof e.name === "string" && e.name ? e.name : "Error";
+  const message = typeof e.message === "string" ? e.message : "";
+  const code = typeof e.code === "string" ? e.code : void 0;
+  const category = typeof e.category === "string" ? e.category : void 0;
+  let header;
+  if (code) {
+    header = `${name} [${code}]: ${message}`;
+  } else if (category) {
+    header = `${name} [${category}]: ${message}`;
+  } else {
+    header = `${name}: ${message}`;
+  }
+  const chain = [];
+  let current = e.cause;
+  let depth = 0;
+  const seen = /* @__PURE__ */ new WeakSet();
+  while (current && depth < 5) {
+    if (typeof current === "object") {
+      if (seen.has(current)) {
+        chain.push("Caused by: [Circular]");
+        break;
+      }
+      seen.add(current);
+    }
+    const c = current;
+    const cName = typeof c.name === "string" && c.name ? c.name : "Error";
+    const cMsg = typeof c.message === "string" ? c.message : String(current);
+    const cCode = typeof c.code === "string" ? c.code : void 0;
+    chain.push(
+      cCode ? `Caused by: ${cName} [${cCode}]: ${cMsg}` : `Caused by: ${cName}: ${cMsg}`
+    );
+    current = c.cause;
+    depth++;
+  }
+  return chain.length > 0 ? `${header}
+${chain.join("\n")}` : header;
+}
 
 // src/errors/createLlmExeError.ts
 var DOCS_BASE_URL = "https://llm-exe.com";
@@ -1051,7 +1095,9 @@ var BaseExecutor = class {
     return this;
   }
   on(eventName, fn) {
-    return this.setHooks({ [eventName]: fn });
+    return this.setHooks({
+      [eventName]: fn
+    });
   }
   off(eventName, fn) {
     return this.removeHook(eventName, fn);
@@ -1149,8 +1195,8 @@ var CoreExecutor = class extends BaseExecutor {
     __publicField(this, "_handler");
     this._handler = fn.handler.bind(null);
   }
-  async handler(_input) {
-    return this._handler.call(null, _input);
+  async handler(_input, _options, _context) {
+    return this._handler.call(null, _input, _context);
   }
 };
 
@@ -3302,6 +3348,7 @@ __export(utils_exports, {
   assert: () => assert,
   asyncCallWithTimeout: () => asyncCallWithTimeout,
   defineSchema: () => defineSchema,
+  escapeTemplateString: () => escapeTemplateString,
   filterObjectOnSchema: () => filterObjectOnSchema,
   guessProviderFromModel: () => guessProviderFromModel,
   importHelpers: () => importHelpers,
@@ -3374,6 +3421,12 @@ function importHelpers(_helpers) {
   return helpers;
 }
 
+// src/utils/modules/escapeTemplateString.ts
+function escapeTemplateString(input) {
+  if (typeof input !== "string") return input;
+  return input.replace(/\{\{/g, "\\{{");
+}
+
 // src/utils/modules/replaceTemplateStringAsync.ts
 async function replaceTemplateStringAsync(templateString, substitutions = {}, configuration = {
   helpers: [],
@@ -4039,9 +4092,53 @@ function OutputOpenAIChat(result, _config) {
   };
 }
 
+// src/llm/config/_utils/imageContent.ts
+function isImageUrlContentBlock(block) {
+  if (typeof block !== "object" || block === null) {
+    return false;
+  }
+  const imageUrl = block.image_url;
+  return typeof imageUrl === "object" && imageUrl !== null && typeof imageUrl.url === "string";
+}
+var DATA_URI_PATTERN = /^data:([^;,]+);base64,(.+)$/;
+function parseImageUrl(url, context) {
+  if (typeof url !== "string" || url.trim() === "") {
+    throw new LlmExeError("Image content block has an empty url", {
+      code: "prompt.invalid_messages",
+      context: {
+        ...context,
+        received: url,
+        expected: "an https URL or a data: URI",
+        resolution: "Set image_url.url to an https URL or a base64 data: URI (data:image/png;base64,...)."
+      }
+    });
+  }
+  if (url.startsWith("data:")) {
+    const match = url.match(DATA_URI_PATTERN);
+    if (!match) {
+      throw new LlmExeError("Malformed data: URI in image content block", {
+        code: "prompt.invalid_messages",
+        context: {
+          ...context,
+          received: `${url.slice(0, 48)}...`,
+          expected: "data:<media-type>;base64,<data>",
+          resolution: "Images must be base64-encoded with an explicit media type, e.g. data:image/png;base64,iVBOR..."
+        }
+      });
+    }
+    return { kind: "base64", mediaType: match[1], data: match[2] };
+  }
+  return { kind: "url", url };
+}
+
 // src/llm/config/openai/promptSanitizeMessageCallback.ts
 function openaiPromptMessageCallback(_message) {
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map(
+      (block) => isImageUrlContentBlock(block) && block.type !== "image_url" ? { ...block, type: "image_url" } : block
+    );
+  }
   if (message.role === "function") {
     message.role = "tool";
     message.tool_call_id = message.id;
@@ -4268,8 +4365,46 @@ var openai = {
 };
 
 // src/llm/config/anthropic/promptSanitizeMessageCallback.ts
-function anthropicPromptMessageCallback(_message) {
+function anthropicPromptMessageCallback(_message, options = {}) {
+  const { provider = "anthropic.chat", allowImageUrlSources = true } = options;
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map((block) => {
+      if (!isImageUrlContentBlock(block)) {
+        return block;
+      }
+      const parsed = parseImageUrl(block.image_url.url, {
+        operation: "anthropicPromptMessageCallback",
+        provider
+      });
+      if (parsed.kind === "base64") {
+        return {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: parsed.mediaType,
+            data: parsed.data
+          }
+        };
+      }
+      if (!allowImageUrlSources) {
+        throw new LlmExeError("Image URLs are not supported by this provider", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "anthropicPromptMessageCallback",
+            provider,
+            received: parsed.url,
+            expected: "a base64 data: URI",
+            resolution: "Bedrock does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+          }
+        });
+      }
+      return {
+        type: "image",
+        source: { type: "url", url: parsed.url }
+      };
+    });
+  }
   if (message.role === "function") {
     message.role = "user";
     message.content = [
@@ -4315,10 +4450,11 @@ function mergeConsecutiveSameRole(messages) {
   }
   return merged;
 }
-function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
+function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj, _options = {}) {
+  const toAnthropicMessage = (m) => anthropicPromptMessageCallback(m, _options);
   if (typeof _messages === "string") {
     return [{ role: "user", content: _messages }].map(
-      anthropicPromptMessageCallback
+      toAnthropicMessage
     );
   }
   const [first, ...messages] = [
@@ -4328,7 +4464,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
     return [
       { role: "user", content: first.content },
       ...messages
-    ].map(anthropicPromptMessageCallback);
+    ].map(toAnthropicMessage);
   }
   if (first.role === "system" && messages.length > 0) {
     _outputObj.system = first.content;
@@ -4337,7 +4473,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
         return { ...m, role: "user" };
       }
       return m;
-    }).map(anthropicPromptMessageCallback);
+    }).map(toAnthropicMessage);
     return mergeConsecutiveSameRole(result2);
   }
   const result = [
@@ -4348,7 +4484,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
       }
       return m;
     })
-  ].map(anthropicPromptMessageCallback);
+  ].map(toAnthropicMessage);
   return mergeConsecutiveSameRole(result);
 }
 
@@ -4461,7 +4597,11 @@ var amazonAnthropicChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: anthropicPromptSanitize
+      transform: (v, i, o) => anthropicPromptSanitize(v, i, o, {
+        provider: "amazon:anthropic.chat",
+        // Bedrock's invoke API only accepts base64 image sources
+        allowImageUrlSources: false
+      })
     },
     topP: {
       key: "top_p"
@@ -4517,6 +4657,21 @@ var amazonMetaChatV1 = {
         if (typeof messages === "string") {
           return messages;
         } else {
+          const hasImageContent = messages.some(
+            (message) => Array.isArray(message?.content) && message.content.some(isImageUrlContentBlock)
+          );
+          if (hasImageContent) {
+            throw new LlmExeError("Image content is not supported", {
+              code: "prompt.invalid_messages",
+              context: {
+                operation: "amazonMetaChatV1.prompt.transform",
+                provider: "amazon:meta.chat",
+                received: "a message with image content",
+                expected: "text-only messages",
+                resolution: "This model accepts a flattened text prompt and cannot receive images."
+              }
+            });
+          }
           return replaceTemplateString(`{{>DialogueHistory key='messages'}}`, {
             messages
           });
@@ -4811,6 +4966,60 @@ function OutputOllamaChat(result, _config) {
   };
 }
 
+// src/llm/config/ollama/promptSanitize.ts
+function ollamaPromptSanitize(_messages) {
+  if (typeof _messages === "string") {
+    return [{ role: "user", content: _messages }];
+  }
+  return _messages.map((_message) => {
+    if (!Array.isArray(_message.content)) {
+      return _message;
+    }
+    const message = { ..._message };
+    const textParts = [];
+    const images = [];
+    for (const block of message.content) {
+      if (isImageUrlContentBlock(block)) {
+        const parsed = parseImageUrl(block.image_url.url, {
+          operation: "ollamaPromptSanitize",
+          provider: "ollama.chat"
+        });
+        if (parsed.kind === "url") {
+          throw new LlmExeError("Image URLs are not supported by ollama", {
+            code: "prompt.invalid_messages",
+            context: {
+              operation: "ollamaPromptSanitize",
+              provider: "ollama.chat",
+              received: parsed.url,
+              expected: "a base64 data: URI",
+              resolution: "Ollama does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+            }
+          });
+        }
+        images.push(parsed.data);
+      } else if (typeof block?.text === "string") {
+        textParts.push(block.text);
+      } else {
+        throw new LlmExeError("Unsupported content block for ollama", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "ollamaPromptSanitize",
+            provider: "ollama.chat",
+            received: block,
+            expected: "text or image_url content blocks",
+            resolution: "Ollama messages only support text and base64 images."
+          }
+        });
+      }
+    }
+    message.content = textParts.join("\n");
+    if (images.length > 0) {
+      message.images = images;
+    }
+    return message;
+  });
+}
+
 // src/llm/config/ollama/index.ts
 var ollamaChatV1 = {
   key: "ollama.chat.v1",
@@ -4828,12 +5037,7 @@ var ollamaChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: (v) => {
-        if (typeof v === "string") {
-          return [{ role: "user", content: v }];
-        }
-        return v;
-      }
+      transform: (v) => ollamaPromptSanitize(v)
     },
     model: {
       key: "model"
@@ -4870,6 +5074,37 @@ var ollama = {
 };
 
 // src/llm/config/google/promptSanitizeMessageCallback.ts
+var GOOGLE_SUPPORTED_FILE_URI = /^(gs:\/\/|https:\/\/generativelanguage\.googleapis\.com\/)/;
+function googleGeminiContentBlockToPart(block) {
+  if (isImageUrlContentBlock(block)) {
+    const parsed = parseImageUrl(block.image_url.url, {
+      operation: "googleGeminiPromptMessageCallback",
+      provider: "google.chat"
+    });
+    if (parsed.kind === "base64") {
+      return {
+        inlineData: { mimeType: parsed.mediaType, data: parsed.data }
+      };
+    }
+    if (GOOGLE_SUPPORTED_FILE_URI.test(parsed.url)) {
+      return { fileData: { fileUri: parsed.url } };
+    }
+    throw new LlmExeError("Gemini cannot load images from arbitrary URLs", {
+      code: "prompt.invalid_messages",
+      context: {
+        operation: "googleGeminiPromptMessageCallback",
+        provider: "google.chat",
+        received: parsed.url,
+        expected: "a base64 data: URI, a Files API URI, or a gs:// URI",
+        resolution: "Pass the image as a data: URI (data:image/png;base64,...), or upload it with the Gemini Files API and pass the returned file URI."
+      }
+    });
+  }
+  if (typeof block?.text === "string") {
+    return { text: block.text };
+  }
+  return block;
+}
 function googleGeminiPromptMessageCallback(_message) {
   let message = { ..._message };
   const parts = [];
@@ -4883,6 +5118,9 @@ function googleGeminiPromptMessageCallback(_message) {
   if (typeof payload.content === "string" && message.role !== "function") {
     parts.push({ text: message.content });
   }
+  if (Array.isArray(payload.content) && message.role !== "function") {
+    parts.push(...payload.content.map(googleGeminiContentBlockToPart));
+  }
   if (message.role === "function") {
     role = "user";
     parts.push({
@@ -7700,10 +7938,12 @@ function createStateItem(name, defaultValue) {
   createState,
   createStateItem,
   defineSchema,
+  formatLlmExeErrorForLog,
   guards,
   isLlmExeError,
   registerHelpers,
   registerPartials,
+  serializeLlmExeError,
   useExecutors,
   useLlm,
   useLlmConfiguration,

package/dist/index.mjs

@@ -464,6 +464,48 @@ function formatErrorList(values, options) {
   }
   return parts.join(", ");
 }
+function formatLlmExeErrorForLog(error) {
+  if (!error || typeof error !== "object") {
+    return formatErrorValue(error);
+  }
+  const e = error;
+  const name = typeof e.name === "string" && e.name ? e.name : "Error";
+  const message = typeof e.message === "string" ? e.message : "";
+  const code = typeof e.code === "string" ? e.code : void 0;
+  const category = typeof e.category === "string" ? e.category : void 0;
+  let header;
+  if (code) {
+    header = `${name} [${code}]: ${message}`;
+  } else if (category) {
+    header = `${name} [${category}]: ${message}`;
+  } else {
+    header = `${name}: ${message}`;
+  }
+  const chain = [];
+  let current = e.cause;
+  let depth = 0;
+  const seen = /* @__PURE__ */ new WeakSet();
+  while (current && depth < 5) {
+    if (typeof current === "object") {
+      if (seen.has(current)) {
+        chain.push("Caused by: [Circular]");
+        break;
+      }
+      seen.add(current);
+    }
+    const c = current;
+    const cName = typeof c.name === "string" && c.name ? c.name : "Error";
+    const cMsg = typeof c.message === "string" ? c.message : String(current);
+    const cCode = typeof c.code === "string" ? c.code : void 0;
+    chain.push(
+      cCode ? `Caused by: ${cName} [${cCode}]: ${cMsg}` : `Caused by: ${cName}: ${cMsg}`
+    );
+    current = c.cause;
+    depth++;
+  }
+  return chain.length > 0 ? `${header}
+${chain.join("\n")}` : header;
+}
 
 // src/errors/createLlmExeError.ts
 var DOCS_BASE_URL = "https://llm-exe.com";
@@ -985,7 +1027,9 @@ var BaseExecutor = class {
     return this;
   }
   on(eventName, fn) {
-    return this.setHooks({ [eventName]: fn });
+    return this.setHooks({
+      [eventName]: fn
+    });
   }
   off(eventName, fn) {
     return this.removeHook(eventName, fn);
@@ -1083,8 +1127,8 @@ var CoreExecutor = class extends BaseExecutor {
     __publicField(this, "_handler");
     this._handler = fn.handler.bind(null);
   }
-  async handler(_input) {
-    return this._handler.call(null, _input);
+  async handler(_input, _options, _context) {
+    return this._handler.call(null, _input, _context);
   }
 };
 
@@ -3236,6 +3280,7 @@ __export(utils_exports, {
   assert: () => assert,
   asyncCallWithTimeout: () => asyncCallWithTimeout,
   defineSchema: () => defineSchema,
+  escapeTemplateString: () => escapeTemplateString,
   filterObjectOnSchema: () => filterObjectOnSchema,
   guessProviderFromModel: () => guessProviderFromModel,
   importHelpers: () => importHelpers,
@@ -3308,6 +3353,12 @@ function importHelpers(_helpers) {
   return helpers;
 }
 
+// src/utils/modules/escapeTemplateString.ts
+function escapeTemplateString(input) {
+  if (typeof input !== "string") return input;
+  return input.replace(/\{\{/g, "\\{{");
+}
+
 // src/utils/modules/replaceTemplateStringAsync.ts
 async function replaceTemplateStringAsync(templateString, substitutions = {}, configuration = {
   helpers: [],
@@ -3973,9 +4024,53 @@ function OutputOpenAIChat(result, _config) {
   };
 }
 
+// src/llm/config/_utils/imageContent.ts
+function isImageUrlContentBlock(block) {
+  if (typeof block !== "object" || block === null) {
+    return false;
+  }
+  const imageUrl = block.image_url;
+  return typeof imageUrl === "object" && imageUrl !== null && typeof imageUrl.url === "string";
+}
+var DATA_URI_PATTERN = /^data:([^;,]+);base64,(.+)$/;
+function parseImageUrl(url, context) {
+  if (typeof url !== "string" || url.trim() === "") {
+    throw new LlmExeError("Image content block has an empty url", {
+      code: "prompt.invalid_messages",
+      context: {
+        ...context,
+        received: url,
+        expected: "an https URL or a data: URI",
+        resolution: "Set image_url.url to an https URL or a base64 data: URI (data:image/png;base64,...)."
+      }
+    });
+  }
+  if (url.startsWith("data:")) {
+    const match = url.match(DATA_URI_PATTERN);
+    if (!match) {
+      throw new LlmExeError("Malformed data: URI in image content block", {
+        code: "prompt.invalid_messages",
+        context: {
+          ...context,
+          received: `${url.slice(0, 48)}...`,
+          expected: "data:<media-type>;base64,<data>",
+          resolution: "Images must be base64-encoded with an explicit media type, e.g. data:image/png;base64,iVBOR..."
+        }
+      });
+    }
+    return { kind: "base64", mediaType: match[1], data: match[2] };
+  }
+  return { kind: "url", url };
+}
+
 // src/llm/config/openai/promptSanitizeMessageCallback.ts
 function openaiPromptMessageCallback(_message) {
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map(
+      (block) => isImageUrlContentBlock(block) && block.type !== "image_url" ? { ...block, type: "image_url" } : block
+    );
+  }
   if (message.role === "function") {
     message.role = "tool";
     message.tool_call_id = message.id;
@@ -4202,8 +4297,46 @@ var openai = {
 };
 
 // src/llm/config/anthropic/promptSanitizeMessageCallback.ts
-function anthropicPromptMessageCallback(_message) {
+function anthropicPromptMessageCallback(_message, options = {}) {
+  const { provider = "anthropic.chat", allowImageUrlSources = true } = options;
   let message = { ..._message };
+  if (Array.isArray(message.content)) {
+    message.content = message.content.map((block) => {
+      if (!isImageUrlContentBlock(block)) {
+        return block;
+      }
+      const parsed = parseImageUrl(block.image_url.url, {
+        operation: "anthropicPromptMessageCallback",
+        provider
+      });
+      if (parsed.kind === "base64") {
+        return {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: parsed.mediaType,
+            data: parsed.data
+          }
+        };
+      }
+      if (!allowImageUrlSources) {
+        throw new LlmExeError("Image URLs are not supported by this provider", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "anthropicPromptMessageCallback",
+            provider,
+            received: parsed.url,
+            expected: "a base64 data: URI",
+            resolution: "Bedrock does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+          }
+        });
+      }
+      return {
+        type: "image",
+        source: { type: "url", url: parsed.url }
+      };
+    });
+  }
   if (message.role === "function") {
     message.role = "user";
     message.content = [
@@ -4249,10 +4382,11 @@ function mergeConsecutiveSameRole(messages) {
   }
   return merged;
 }
-function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
+function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj, _options = {}) {
+  const toAnthropicMessage = (m) => anthropicPromptMessageCallback(m, _options);
   if (typeof _messages === "string") {
     return [{ role: "user", content: _messages }].map(
-      anthropicPromptMessageCallback
+      toAnthropicMessage
     );
   }
   const [first, ...messages] = [
@@ -4262,7 +4396,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
     return [
       { role: "user", content: first.content },
       ...messages
-    ].map(anthropicPromptMessageCallback);
+    ].map(toAnthropicMessage);
   }
   if (first.role === "system" && messages.length > 0) {
     _outputObj.system = first.content;
@@ -4271,7 +4405,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
         return { ...m, role: "user" };
       }
       return m;
-    }).map(anthropicPromptMessageCallback);
+    }).map(toAnthropicMessage);
     return mergeConsecutiveSameRole(result2);
   }
   const result = [
@@ -4282,7 +4416,7 @@ function anthropicPromptSanitize(_messages, _inputBodyObj, _outputObj) {
       }
       return m;
     })
-  ].map(anthropicPromptMessageCallback);
+  ].map(toAnthropicMessage);
   return mergeConsecutiveSameRole(result);
 }
 
@@ -4395,7 +4529,11 @@ var amazonAnthropicChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: anthropicPromptSanitize
+      transform: (v, i, o) => anthropicPromptSanitize(v, i, o, {
+        provider: "amazon:anthropic.chat",
+        // Bedrock's invoke API only accepts base64 image sources
+        allowImageUrlSources: false
+      })
     },
     topP: {
       key: "top_p"
@@ -4451,6 +4589,21 @@ var amazonMetaChatV1 = {
         if (typeof messages === "string") {
           return messages;
         } else {
+          const hasImageContent = messages.some(
+            (message) => Array.isArray(message?.content) && message.content.some(isImageUrlContentBlock)
+          );
+          if (hasImageContent) {
+            throw new LlmExeError("Image content is not supported", {
+              code: "prompt.invalid_messages",
+              context: {
+                operation: "amazonMetaChatV1.prompt.transform",
+                provider: "amazon:meta.chat",
+                received: "a message with image content",
+                expected: "text-only messages",
+                resolution: "This model accepts a flattened text prompt and cannot receive images."
+              }
+            });
+          }
           return replaceTemplateString(`{{>DialogueHistory key='messages'}}`, {
             messages
           });
@@ -4745,6 +4898,60 @@ function OutputOllamaChat(result, _config) {
   };
 }
 
+// src/llm/config/ollama/promptSanitize.ts
+function ollamaPromptSanitize(_messages) {
+  if (typeof _messages === "string") {
+    return [{ role: "user", content: _messages }];
+  }
+  return _messages.map((_message) => {
+    if (!Array.isArray(_message.content)) {
+      return _message;
+    }
+    const message = { ..._message };
+    const textParts = [];
+    const images = [];
+    for (const block of message.content) {
+      if (isImageUrlContentBlock(block)) {
+        const parsed = parseImageUrl(block.image_url.url, {
+          operation: "ollamaPromptSanitize",
+          provider: "ollama.chat"
+        });
+        if (parsed.kind === "url") {
+          throw new LlmExeError("Image URLs are not supported by ollama", {
+            code: "prompt.invalid_messages",
+            context: {
+              operation: "ollamaPromptSanitize",
+              provider: "ollama.chat",
+              received: parsed.url,
+              expected: "a base64 data: URI",
+              resolution: "Ollama does not fetch remote images. Base64-encode the image and pass it as a data: URI (data:image/png;base64,...)."
+            }
+          });
+        }
+        images.push(parsed.data);
+      } else if (typeof block?.text === "string") {
+        textParts.push(block.text);
+      } else {
+        throw new LlmExeError("Unsupported content block for ollama", {
+          code: "prompt.invalid_messages",
+          context: {
+            operation: "ollamaPromptSanitize",
+            provider: "ollama.chat",
+            received: block,
+            expected: "text or image_url content blocks",
+            resolution: "Ollama messages only support text and base64 images."
+          }
+        });
+      }
+    }
+    message.content = textParts.join("\n");
+    if (images.length > 0) {
+      message.images = images;
+    }
+    return message;
+  });
+}
+
 // src/llm/config/ollama/index.ts
 var ollamaChatV1 = {
   key: "ollama.chat.v1",
@@ -4762,12 +4969,7 @@ var ollamaChatV1 = {
   mapBody: {
     prompt: {
       key: "messages",
-      transform: (v) => {
-        if (typeof v === "string") {
-          return [{ role: "user", content: v }];
-        }
-        return v;
-      }
+      transform: (v) => ollamaPromptSanitize(v)
     },
     model: {
       key: "model"
@@ -4804,6 +5006,37 @@ var ollama = {
 };
 
 // src/llm/config/google/promptSanitizeMessageCallback.ts
+var GOOGLE_SUPPORTED_FILE_URI = /^(gs:\/\/|https:\/\/generativelanguage\.googleapis\.com\/)/;
+function googleGeminiContentBlockToPart(block) {
+  if (isImageUrlContentBlock(block)) {
+    const parsed = parseImageUrl(block.image_url.url, {
+      operation: "googleGeminiPromptMessageCallback",
+      provider: "google.chat"
+    });
+    if (parsed.kind === "base64") {
+      return {
+        inlineData: { mimeType: parsed.mediaType, data: parsed.data }
+      };
+    }
+    if (GOOGLE_SUPPORTED_FILE_URI.test(parsed.url)) {
+      return { fileData: { fileUri: parsed.url } };
+    }
+    throw new LlmExeError("Gemini cannot load images from arbitrary URLs", {
+      code: "prompt.invalid_messages",
+      context: {
+        operation: "googleGeminiPromptMessageCallback",
+        provider: "google.chat",
+        received: parsed.url,
+        expected: "a base64 data: URI, a Files API URI, or a gs:// URI",
+        resolution: "Pass the image as a data: URI (data:image/png;base64,...), or upload it with the Gemini Files API and pass the returned file URI."
+      }
+    });
+  }
+  if (typeof block?.text === "string") {
+    return { text: block.text };
+  }
+  return block;
+}
 function googleGeminiPromptMessageCallback(_message) {
   let message = { ..._message };
   const parts = [];
@@ -4817,6 +5050,9 @@ function googleGeminiPromptMessageCallback(_message) {
   if (typeof payload.content === "string" && message.role !== "function") {
     parts.push({ text: message.content });
   }
+  if (Array.isArray(payload.content) && message.role !== "function") {
+    parts.push(...payload.content.map(googleGeminiContentBlockToPart));
+  }
   if (message.role === "function") {
     role = "user";
     parts.push({
@@ -7633,10 +7869,12 @@ export {
   createState,
   createStateItem,
   defineSchema,
+  formatLlmExeErrorForLog,
   guards_exports as guards,
   isLlmExeError,
   registerHelpers,
   registerPartials,
+  serializeLlmExeError,
   useExecutors,
   useLlm,
   useLlmConfiguration,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-exe",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Simplify building LLM-powered apps with easy-to-use base components, supporting text and chat-based prompts with handlebars template engine, output parsers, and flexible function calling capabilities.",
   "keywords": [
     "ai",

package/readme.md

@@ -14,7 +14,7 @@ A package that provides simplified base components to make building and maintain
 - Allow LLM's to call functions (or call other LLM executors).
 - Not very opinionated. You have control on how you use it.
 
-![llm-exe](https://assets.llm-exe.com/llm-exe-featured-2025.png)
+![llm-exe project logo](https://assets.llm-exe.com/llm-exe-featured-2025.png)
 
 See full docs here: [https://llm-exe.com](https://llm-exe.com)