llm-exe 3.0.0 → 3.0.2

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";
@@ -1251,6 +1279,15 @@ type AllLlm = {
     };
 };
 type AllUseLlmOptions = AllLlm & {
+    "openai.gpt-5.5": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5.4": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5.4-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
     "openai.gpt-5.2": {
         input: Omit<OpenAiRequest, "model">;
     };
@@ -1284,6 +1321,9 @@ type AllUseLlmOptions = AllLlm & {
     "openai.o4-mini": {
         input: Omit<OpenAiRequest, "model">;
     };
+    "anthropic.claude-fable-5": {
+        input: Omit<AnthropicRequest, "model">;
+    };
     "anthropic.claude-opus-4-8": {
         input: Omit<AnthropicRequest, "model">;
     };
@@ -1305,9 +1345,6 @@ type AllUseLlmOptions = AllLlm & {
     "anthropic.claude-opus-4-6": {
         input: Omit<AnthropicRequest, "model">;
     };
-    "anthropic.claude-opus-4-1": {
-        input: Omit<AnthropicRequest, "model">;
-    };
     "anthropic.claude-sonnet-4-0": {
         input: Omit<AnthropicRequest, "model">;
     };
@@ -1771,6 +1808,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 +1950,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 +1971,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 +1985,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;
@@ -2019,9 +2062,9 @@ declare const configs: {
     "anthropic.claude-3-7-sonnet": Config<any>;
     "anthropic.claude-opus-4": Config<any>;
     "anthropic.claude-sonnet-4": Config<any>;
-    "anthropic.claude-opus-4-1": Config<any>;
     "anthropic.claude-opus-4-6": Config<any>;
     "anthropic.chat.v1": Config<keyof AllLlm>;
+    "anthropic.claude-fable-5": Config<keyof AllLlm>;
     "anthropic.claude-opus-4-8": Config<keyof AllLlm>;
     "anthropic.claude-opus-4-7": Config<keyof AllLlm>;
     "anthropic.claude-sonnet-4-6": Config<keyof AllLlm>;
@@ -2031,6 +2074,9 @@ declare const configs: {
     "openai.o4-mini": Config<any>;
     "openai.chat.v1": Config<keyof AllLlm>;
     "openai.chat-mock.v1": Config<keyof AllLlm>;
+    "openai.gpt-5.5": Config<keyof AllLlm>;
+    "openai.gpt-5.4": Config<keyof AllLlm>;
+    "openai.gpt-5.4-mini": Config<keyof AllLlm>;
     "openai.gpt-5.2": Config<keyof AllLlm>;
     "openai.gpt-5-mini": Config<keyof AllLlm>;
     "openai.gpt-5-nano": Config<keyof AllLlm>;
@@ -2092,4 +2138,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";
@@ -1251,6 +1279,15 @@ type AllLlm = {
     };
 };
 type AllUseLlmOptions = AllLlm & {
+    "openai.gpt-5.5": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5.4": {
+        input: Omit<OpenAiRequest, "model">;
+    };
+    "openai.gpt-5.4-mini": {
+        input: Omit<OpenAiRequest, "model">;
+    };
     "openai.gpt-5.2": {
         input: Omit<OpenAiRequest, "model">;
     };
@@ -1284,6 +1321,9 @@ type AllUseLlmOptions = AllLlm & {
     "openai.o4-mini": {
         input: Omit<OpenAiRequest, "model">;
     };
+    "anthropic.claude-fable-5": {
+        input: Omit<AnthropicRequest, "model">;
+    };
     "anthropic.claude-opus-4-8": {
         input: Omit<AnthropicRequest, "model">;
     };
@@ -1305,9 +1345,6 @@ type AllUseLlmOptions = AllLlm & {
     "anthropic.claude-opus-4-6": {
         input: Omit<AnthropicRequest, "model">;
     };
-    "anthropic.claude-opus-4-1": {
-        input: Omit<AnthropicRequest, "model">;
-    };
     "anthropic.claude-sonnet-4-0": {
         input: Omit<AnthropicRequest, "model">;
     };
@@ -1771,6 +1808,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 +1950,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 +1971,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 +1985,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;
@@ -2019,9 +2062,9 @@ declare const configs: {
     "anthropic.claude-3-7-sonnet": Config<any>;
     "anthropic.claude-opus-4": Config<any>;
     "anthropic.claude-sonnet-4": Config<any>;
-    "anthropic.claude-opus-4-1": Config<any>;
     "anthropic.claude-opus-4-6": Config<any>;
     "anthropic.chat.v1": Config<keyof AllLlm>;
+    "anthropic.claude-fable-5": Config<keyof AllLlm>;
     "anthropic.claude-opus-4-8": Config<keyof AllLlm>;
     "anthropic.claude-opus-4-7": Config<keyof AllLlm>;
     "anthropic.claude-sonnet-4-6": Config<keyof AllLlm>;
@@ -2031,6 +2074,9 @@ declare const configs: {
     "openai.o4-mini": Config<any>;
     "openai.chat.v1": Config<keyof AllLlm>;
     "openai.chat-mock.v1": Config<keyof AllLlm>;
+    "openai.gpt-5.5": Config<keyof AllLlm>;
+    "openai.gpt-5.4": Config<keyof AllLlm>;
+    "openai.gpt-5.4-mini": Config<keyof AllLlm>;
     "openai.gpt-5.2": Config<keyof AllLlm>;
     "openai.gpt-5-mini": Config<keyof AllLlm>;
     "openai.gpt-5-nano": Config<keyof AllLlm>;
@@ -2092,4 +2138,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 };