llm-exe 2.3.11 → 3.0.0-beta.1

package/dist/index.d.mts

@@ -68,20 +68,18 @@ type OpenAIConversationModelName = "davinci" | "text-curie-001" | "text-babbage-
 type OpenAIEmbeddingModelName = "text-embedding-ada-002";
 type OpenAIModelName = OpenAIChatModelName | OpenAIConversationModelName | OpenAIEmbeddingModelName;
 
-type ParserInput = string | OutputResult;
 /**
  * BaseParser is an abstract class for parsing text and enforcing JSON schema on the parsed data.
  */
-declare abstract class BaseParser<T = any> {
+declare abstract class BaseParser<T = any, TInput = string> {
     name: string;
-    options: BaseParserOptions;
     target: "text" | "function_call";
     /**
      * Create a new BaseParser.
      * @param name - The name of the parser.
-     * @param  options - options
+     * @param target - Whether the parser consumes text or function-call output.
      */
-    constructor(name: string, options?: BaseParserOptions, target?: "text" | "function_call");
+    constructor(name: string, target?: "text" | "function_call");
     /**
      * Parse the given text and return the parsed data.
      * @abstract
@@ -89,59 +87,128 @@ declare abstract class BaseParser<T = any> {
      * @param [attributes] - Optional attributes to use during parsing.
      * @returns The parsed data.
      */
-    abstract parse(text: ParserInput, attributes?: Record<string, any>): T;
+    abstract parse(text: TInput, attributes?: Record<string, any>): T;
 }
-declare abstract class BaseParserWithJson<S extends JSONSchema | undefined = undefined, T = S extends JSONSchema ? FromSchema<S> : Record<string, any>> extends BaseParser<T> {
+declare abstract class BaseParserWithJson<S extends JSONSchema | undefined = undefined, T = S extends JSONSchema ? FromSchema<S> : Record<string, any>, TInput = string> extends BaseParser<T, TInput> {
     schema: S;
     validateSchema: boolean;
-    /**
-     * Create a new BaseParser.
-     * @param name - The name of the parser.
-     * @param  options - options
-     */
-    constructor(name: string, options: BaseParserOptionsWithSchema<S>);
+    constructor(name: string, options: JsonParserOptions<S>);
 }
 
-interface StringParserOptions extends BaseParserOptions {
-}
+/**
+ * v3 parser contract:
+ * Category: pass-through
+ * Mode: string pass-through
+ *
+ * Accepts any string and returns it exactly.
+ * Throws LlmExeError(parser.parse_failed) for non-string input.
+ * Executor output normalization owns OutputResult handling before parser
+ * invocation.
+ *
+ */
 declare class StringParser extends BaseParser<string> {
-    constructor(options?: StringParserOptions);
-    parse(text: string | OutputResult, _options?: Record<string, any>): string;
+    constructor();
+    parse(text: string, _attributes?: Record<string, any>): string;
 }
 
-interface BooleanParserOptions extends BaseParserOptions {
-}
+/**
+ * v3 parser contract:
+ * Category: strict
+ * Mode: whole-output
+ *
+ * Accepts only documented boolean literals after trim/lowercase.
+ * Returns true/false only when input is recognized.
+ * Throws LlmExeError(parser.parse_failed) for empty, invalid-type, or
+ * unrecognized input. Does not extract booleans from prose.
+ * Error context does not include input content unless LLM_EXE_DEBUG is enabled.
+ *
+ */
 declare class BooleanParser extends BaseParser<boolean> {
-    constructor(options?: BooleanParserOptions);
-    parse(text: string): boolean;
+    constructor();
+    private getInputErrorContext;
+    parse(text: string, _attributes?: Record<string, any>): boolean;
 }
 
-interface NumberParserOptions extends BaseParserOptions {
+type NumberParserMatch = "extract" | "whole";
+interface NumberParserOptions {
+    match?: NumberParserMatch;
 }
+/**
+ * v3 parser contract:
+ * Category: extractor
+ * Mode: numeric token extraction
+ *
+ * Extracts one documented numeric token from text. Pass match: "whole" to
+ * require the input to consist of exactly one numeric token (after trim) with
+ * no surrounding prose.
+ *
+ * Throws LlmExeError(parser.parse_failed) for empty input, no numeric token,
+ * multiple numeric tokens, invalid conversion. Invalid input type throws
+ * LlmExeError(parser.invalid_input).
+ */
 declare class NumberParser extends BaseParser<number> {
+    private match;
     constructor(options?: NumberParserOptions);
-    parse(text: string): number;
+    parse(text: string, _attributes?: Record<string, any>): number;
 }
 
-declare class JsonParser<S extends JSONSchema | undefined = undefined> extends BaseParserWithJson<S> {
-    constructor(options?: BaseParserOptionsWithSchema<S>);
-    parse(text: string, _attributes?: Record<string, any>): ParserOutput<BaseParserWithJson<S>>;
+type JsonParserInput = string | Record<string, unknown> | unknown[];
+type JsonParserOutput<S extends JSONSchema | undefined> = S extends JSONSchema ? FromSchema<S> : Record<string, any>;
+declare class JsonParser<S extends JSONSchema | undefined = undefined> extends BaseParserWithJson<S, JsonParserOutput<S>, JsonParserInput> {
+    private shouldValidateSchema;
+    constructor(options?: JsonParserOptions<S>);
+    /**
+     * v3 parser contract:
+     * Category: strict
+     * Mode: whole-output
+     *
+     * Parses strict JSON object/array output only. Invalid JSON, empty input,
+     * JSON primitives, and non-plain runtime objects throw typed parser errors.
+     * Schema validation is on by default when a schema is provided unless
+     * validateSchema: false is explicitly set.
+     *
+     */
+    parse(text: JsonParserInput, _attributes?: Record<string, any>): JsonParserOutput<S>;
 }
 
 declare class ListToJsonParser<S extends JSONSchema | undefined = undefined> extends BaseParserWithJson<S> {
     private keyTransform;
+    private shouldValidateSchema;
     constructor(options?: ListToJsonParserOptions<S>);
+    /**
+     * v3 parser contract:
+     * Category: converter
+     * Mode: line-oriented format conversion
+     *
+     * Uses the shared list boundary. Parses normalized lines as key/value pairs
+     * split at the first colon. Duplicate keys throw because object output would
+     * overwrite data.
+     *
+     */
     parse(text: string): ParserOutput<BaseParserWithJson<S>>;
 }
 
-interface ListToKeyValueParserOptions extends BaseParserOptions {
+interface ListToKeyValueParserOptions {
+    keyTransform?: "preserve" | "camelCase";
 }
 declare class ListToKeyValueParser extends BaseParser<Array<{
     key: string;
     value: string;
 }>> {
+    private keyTransform;
     constructor(options?: ListToKeyValueParserOptions);
-    parse(text: string): {
+    /**
+     * v3 parser contract:
+     * Category: converter
+     * Mode: line-oriented collector
+     *
+     * Uses the shared list boundary. Parses normalized lines as key/value pairs
+     * split at the first colon. Preserves duplicate keys because output is an
+     * ordered array. Keys are returned as written by default; pass
+     * keyTransform: "camelCase" to match listToJson's key normalization.
+     *
+     */
+    parse(text: string, _attributes?: Record<string, any>): {
         key: string;
         value: string;
     }[];
@@ -149,180 +216,171 @@ declare class ListToKeyValueParser extends BaseParser<Array<{
 
 /**
  * CustomParser class, extending the BaseParser class.
- * @template I The expected type of the input
  * @template O The type of the parsed value (output)
- * @extends {BaseParser<T>}
+ * @extends {BaseParser<O>}
+ *
+ * v3 parser contract:
+ * Category: pass-through extension point
+ * Mode: user-defined
+ *
+ * Calls the user parser function with text and the per-call ExecutionContext.
+ * Returns the user parser result exactly.
+ * Does not wrap user parser errors.
+ *
+ * When invoked through an executor, `context` includes the resolved trace ID,
+ * stable executor metadata, current execution metadata, and the attributes
+ * extension bag. When parse() is called directly without a context, callers
+ * may pass any shape they want; the type widens to allow that.
  */
 declare class CustomParser<O = any> extends BaseParser<O> {
-    /**
-     * Custom parsing function.
-     * @type {any}
-     */
-    parserFn: (text: string, inputValues: ExecutorContext<any, any>) => O;
-    /**
-     * Creates a new CustomParser instance.
-     * @param {string} name The name of the parser.
-     * @param {any} parserFn The custom parsing function.
-     */
-    constructor(name: string, parserFn: (text: string, inputValues: ExecutorContext<any, any>) => O);
-    /**
-     * Parses the text using the custom parsing function.
-     * @param {string} text The text to be parsed.
-     * @param {any} inputValues Additional input values for the parser function.
-     * @returns {O} The parsed value.
-     */
-    parse(text: string, inputValues: ExecutorContext<any, O>): O;
+    parserFn: (text: string, context: ExecutionContext<any, O>) => O;
+    constructor(name: string, parserFn: (text: string, context: ExecutionContext<any, O>) => O);
+    parse(text: string, context?: ExecutionContext<any, O>): O;
 }
 
+/**
+ * v3 parser contract:
+ * Category: converter
+ * Mode: line-oriented collection conversion
+ *
+ * Uses the shared list boundary. Returns normalized item text exactly.
+ * Throws for empty input, invalid input type, mixed marked/unmarked lines, or
+ * a single unmarked prose line.
+ *
+ */
 declare class ListToArrayParser extends BaseParser<string[]> {
     constructor();
-    parse(text: string): string[];
+    parse(text: string, _attributes?: Record<string, any>): string[];
 }
 
-interface ReplaceStringTemplateParserOptions extends BaseParserOptions {
-}
+/**
+ * v3 parser contract:
+ * Category: pass-through transformation
+ * Mode: template replacement
+ *
+ * Accepts a string template and optional attributes object.
+ * Returns the helper replacement result.
+ * Throws LlmExeError(parser.parse_failed) for invalid input type,
+ * invalid attributes, or template helper failures.
+ *
+ */
 declare class ReplaceStringTemplateParser extends BaseParser<string> {
-    constructor(options?: ReplaceStringTemplateParserOptions);
+    constructor();
     parse(text: string, attributes?: Record<string, any>): string;
 }
 
-interface MarkdownCodeBlockParserOptions extends BaseParserOptions {
-}
+/**
+ * v3 parser contract:
+ * Category: strict
+ * Mode: singular fenced block
+ *
+ * Accepts input containing exactly one complete fenced markdown code block.
+ * Returns that block with exact code content and language string.
+ * Throws LlmExeError(parser.parse_failed) for empty input, no block, multiple
+ * blocks, malformed fences, or invalid input type.
+ *
+ */
 declare class MarkdownCodeBlockParser extends BaseParser<{
     language: string;
     code: string;
 }> {
-    constructor(options?: MarkdownCodeBlockParserOptions);
-    parse(input: string): {
+    constructor();
+    parse(input: string, _attributes?: Record<string, any>): {
         code: string;
         language: string;
     };
 }
 
-interface MarkdownCodeBlocksParserOptions extends BaseParserOptions {
-}
+/**
+ * v3 parser contract:
+ * Category: collector
+ * Mode: markdown fenced block collection
+ *
+ * Accepts text containing zero or more complete fenced code blocks.
+ * Returns all complete blocks in source order.
+ * Returns [] when no complete block exists.
+ * Throws LlmExeError(parser.parse_failed) for invalid input type or malformed
+ * fence structure. Does not unwrap stringified JSON.
+ *
+ */
 declare class MarkdownCodeBlocksParser extends BaseParser<{
     language: string;
     code: string;
 }[]> {
-    constructor(options?: MarkdownCodeBlocksParserOptions);
-    parse(input: string): {
+    constructor();
+    parse(input: string, _attributes?: Record<string, any>): {
         code: string;
         language: string;
     }[];
 }
 
-interface StringExtractParserOptions extends BaseParserOptions {
-    enum: string[];
+type StringExtractMatch = "word" | "whole" | "substring";
+interface StringExtractParserOptions<E extends readonly string[] = readonly string[]> {
+    enum: E;
     ignoreCase?: boolean;
+    match?: StringExtractMatch;
 }
-declare class StringExtractParser extends BaseParser<string> {
+declare class StringExtractParser<E extends readonly string[] = readonly string[]> extends BaseParser<E[number]> {
     private enum;
     private ignoreCase;
-    constructor(options?: StringExtractParserOptions);
-    parse(text: string): string;
+    private match;
+    constructor(options?: StringExtractParserOptions<E>);
+    /**
+     * v3 parser contract:
+     * Category: extractor
+     * Mode: configured value extraction
+     *
+     * Returns the single configured enum value found in input. Matching is
+     * word-bounded by default; pass match: "whole" to require exact input or
+     * match: "substring" for legacy contains() behavior. Case-insensitive by
+     * default.
+     *
+     */
+    parse(text: string, _attributes?: Record<string, any>): E[number];
+    private findMatches;
+    private matchWhole;
+    private matchSubstring;
+    private matchWord;
 }
 
 /**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @returns An instance of MarkdownCodeBlocksParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "markdownCodeBlocks">>(type: T, options?: BaseParserOptions): MarkdownCodeBlocksParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @returns An instance of MarkdownCodeBlockParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "markdownCodeBlock">>(type: T, options?: BaseParserOptions): MarkdownCodeBlockParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @returns An instance of ListToKeyValueParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "listToKeyValue">>(type: T, options?: BaseParserOptions): ListToKeyValueParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param  type - The type of parser to create.
- * @returns An instance of ListToArrayParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "listToArray">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptions): ListToArrayParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @returns An instance of NumberParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "number">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptions): NumberParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param  type - The type of parser to create.
- * @returns An instance of NumberParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "boolean">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptions): BooleanParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param  type - The type of parser to create.
- * @returns  An instance of ReplaceStringTemplateParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "replaceStringTemplate">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptions): ReplaceStringTemplateParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @returns  An instance of StringParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "string">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptions): StringParser;
-/**
- * Creates a parser based on the given type.
- * @template S - JSON schema type.
- * @param  type - The type of parser to create.
- * @returns  An instance of StringParser.
+ * Labeled-tuple union for `createParser` arguments. Each branch enumerates
+ * exactly what's valid for one parser type. TypeScript validates the whole
+ * argument tuple against this union, which produces useful error messages
+ * (e.g. "Source has 1 element(s) but target requires 2" when stringExtract
+ * is called without options) instead of overload-resolution mystery.
  */
-declare function createParser<T extends Extract<CreateParserType, "stringExtract">, S extends JSONSchema | undefined = undefined>(type: T, options?: StringExtractParserOptions): StringExtractParser;
+type CreateParserArgs = [type: "string", options?: never] | [type: "boolean", options?: never] | [type: "listToArray", options?: never] | [type: "markdownCodeBlock", options?: never] | [type: "markdownCodeBlocks", options?: never] | [type: "replaceStringTemplate", options?: never] | [type: "number", options?: NumberParserOptions] | [type: "listToKeyValue", options?: ListToKeyValueParserOptions] | [type: "json", options?: JsonParserOptions<JSONSchema | undefined>] | [
+    type: "listToJson",
+    options?: ListToJsonParserOptions<JSONSchema | undefined>
+] | [type: "stringExtract", options: StringExtractParserOptions<readonly string[]>];
 /**
- * Creates a parser based on the given type and schema.
- * @template S - JSON schema type.
- * @param type - The type of parser to create.
- * @param options - The JSON schema.
- * @returns An instance of ListToJsonParser.
+ * Maps a concrete argument tuple back to the parser instance type, preserving
+ * schema inference for json/listToJson and enum literal narrowing for
+ * stringExtract.
  */
-declare function createParser<T extends Extract<CreateParserType, "listToJson">, S extends JSONSchema | undefined = undefined>(type: T, options?: ListToJsonParserOptions<S>): ListToJsonParser<S>;
-/**
- * Creates a parser based on the given type and schema.
- * @template S - JSON schema type.
- * @param  type - The type of parser to create.
- * @param [options] - The JSON schema.
- * @returns An instance of JsonParser.
- */
-declare function createParser<T extends Extract<CreateParserType, "json">, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptionsWithSchema<S>): JsonParser<S>;
-declare function createParser<T extends CreateParserType, S extends JSONSchema | undefined = undefined>(type: T, options?: BaseParserOptionsWithSchema<S> | BaseParserOptions): JsonParser<S> | ListToJsonParser<S> | StringParser | NumberParser | BooleanParser | ListToArrayParser | ListToKeyValueParser | ReplaceStringTemplateParser | MarkdownCodeBlockParser | MarkdownCodeBlocksParser | StringExtractParser;
-declare function createCustomParser<O>(name: string, parserFn: (text: string, inputValues: ExecutorContext<any, any>) => O): CustomParser<ReturnType<typeof parserFn>>;
+type CreateParserReturn<A extends readonly unknown[]> = A extends readonly ["string", ...unknown[]] ? StringParser : A extends readonly ["boolean", ...unknown[]] ? BooleanParser : A extends readonly ["number", ...unknown[]] ? NumberParser : A extends readonly ["listToArray", ...unknown[]] ? ListToArrayParser : A extends readonly ["listToKeyValue", ...unknown[]] ? ListToKeyValueParser : A extends readonly ["markdownCodeBlock", ...unknown[]] ? MarkdownCodeBlockParser : A extends readonly ["markdownCodeBlocks", ...unknown[]] ? MarkdownCodeBlocksParser : A extends readonly ["replaceStringTemplate", ...unknown[]] ? ReplaceStringTemplateParser : A extends readonly ["json"] | readonly ["json", undefined] ? JsonParser<undefined> : A extends readonly ["json", JsonParserOptions<infer S>] ? JsonParser<S> : A extends readonly ["listToJson"] | readonly ["listToJson", undefined] ? ListToJsonParser<undefined> : A extends readonly ["listToJson", ListToJsonParserOptions<infer S>] ? ListToJsonParser<S> : A extends readonly [
+    "stringExtract",
+    StringExtractParserOptions<infer E extends readonly string[]>
+] ? StringExtractParser<E> : never;
+declare function createParser<const A extends CreateParserArgs>(...args: A): CreateParserReturn<A>;
+declare function createCustomParser<O>(name: string, parserFn: (text: string, context: ExecutionContext<any, any>) => O): CustomParser<ReturnType<typeof parserFn>>;
 
-declare class LlmFunctionParser<T extends BaseParser<any>> extends BaseParser<ParserOutput<T> | OutputResultContent[]> {
+interface LlmNativeFunctionParserOptions<T extends BaseParser<any, any>> {
     parser: T;
-    constructor(options: LlmNativeFunctionParserOptions<T>);
-    parse(text: OutputResult, _options?: Record<string, any>): OutputResultContent[] | ParserOutput<T>;
 }
-interface LlmNativeFunctionParserOptions<T extends BaseParser<any>> extends BaseParserOptions {
-    parser: T;
-}
-interface LlmNativeFunctionParserOptions<T extends BaseParser<any>> extends BaseParserOptions {
+declare class LlmFunctionParser<T extends BaseParser<any, any>> extends BaseParser<ParserOutput<T> | OutputResultContent[], OutputResult | string> {
     parser: T;
+    constructor(options: LlmNativeFunctionParserOptions<T>);
+    parse(text: OutputResult, _options?: Record<string, any>): ParserOutput<T> | OutputResultContent[];
 }
 /**
  * @deprecated Use `LlmFunctionParser` instead.
  */
-declare class LlmNativeFunctionParser<T extends BaseParser<any>> extends BaseParser<ParserOutput<T> | {
+declare class LlmNativeFunctionParser<T extends BaseParser<any, any>> extends BaseParser<ParserOutput<T> | {
     name: any;
     arguments: any;
-}> {
+}, OutputResult | string> {
     parser: T;
     constructor(options: LlmNativeFunctionParserOptions<T>);
     parse(text: OutputResult, _options?: Record<string, any>): ParserOutput<T> | {
@@ -347,6 +405,7 @@ declare abstract class BasePrompt<I extends Record<string, any>> {
     messages: IPromptMessages | IPromptChatMessages;
     partials: PromptPartial[];
     helpers: PromptHelper[];
+    validateInput: ValidateInputMode;
     replaceTemplateString: typeof replaceTemplateString;
     replaceTemplateStringAsync: typeof replaceTemplateStringAsync;
     filters: {
@@ -383,6 +442,16 @@ declare abstract class BasePrompt<I extends Record<string, any>> {
      * @return BasePrompt so it can be chained.
      */
     registerHelpers(helperOrHelpers: PromptHelper | PromptHelper[]): this;
+    /**
+     * Returns the Handlebars-bearing strings that should be validated, along
+     * with a location label used for error context. Subclasses with structured
+     * message content (e.g. ChatPrompt) should override.
+     */
+    protected getTemplateContents(): {
+        content: string;
+        location: string;
+    }[];
+    protected preflightValidate(values: I): void;
     /**
      * format description
      * @param values The message content
@@ -403,10 +472,17 @@ declare abstract class BasePrompt<I extends Record<string, any>> {
         _input: any;
     };
     /**
-     * Validates the prompt structure.
-     * @return {boolean} Returns false if the prompt has no messages defined.
+     * Validates that `input` provides every variable referenced by this prompt's
+     * templates, and that every identifiable helper call is registered.
+     *
+     * @breaking v3: previously returned `this.messages.length > 0` with no
+     * `input` parameter. For the old behavior, read `prompt.messages.length > 0`
+     * directly.
+     *
+     * @throws LlmExeError with code `"prompt.missing_template_variable"` listing
+     * all missing variables and helpers.
      */
-    validate(): boolean;
+    validate(input: I): void;
 }
 
 /**
@@ -535,6 +611,7 @@ type PromptPartial = {
     name: string;
     template: string;
 };
+type ValidateInputMode = false | "strict" | "warn";
 interface PromptTemplateOptions {
     partials?: PromptPartial[];
     helpers?: PromptHelper[];
@@ -543,6 +620,15 @@ interface PromptOptions extends PromptTemplateOptions {
     preFilters?: ((prompt: string) => string)[];
     postFilters?: ((prompt: string) => string)[];
     replaceTemplateString?: (...args: any[]) => string;
+    /**
+     * Controls whether `format()` preflights input against the variables
+     * referenced by the prompt's templates. See `validate(input)`.
+     *
+     * - `false` (default): no preflight; rendering proceeds.
+     * - `"strict"`: throw `LlmExeError("prompt.missing_template_variable")` before rendering.
+     * - `"warn"`: emit a Node warning via `process.emitWarning` and continue rendering.
+     */
+    validateInput?: ValidateInputMode;
 }
 interface ChatPromptOptions extends PromptOptions {
     allowUnsafeUserTemplate?: boolean;
@@ -602,10 +688,27 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      */
     readonly maxHooksPerEvent: number;
     constructor(name: string, type: string, options?: CoreExecutorExecuteOptions<H>);
-    abstract handler(input: I, _options?: any): Promise<any>;
+    abstract handler(input: I, _options?: any, _context?: ExecutionContext<I, O>): Promise<any>;
+    /**
+     * Build a per-call execution context snapshot. Captures the current
+     * execution metadata so the snapshot reflects state at the time it was
+     * taken (e.g. `handlerInput` becomes available after `getHandlerInput`).
+     */
+    protected snapshotContext(execution: ExecutorExecutionMetadata<I, O>): ExecutionContext<I, O>;
     /**
      *
-     * Used to filter the input of the handler
+     * Used to filter the input of the handler.
+     *
+     * Throws a `TypeError` if `_input` is `null` or `undefined`. The declared
+     * input type is `I extends PlainObject`; omitting input or passing an
+     * explicit `null` is a contract violation with no valid coercion, so we
+     * surface it loudly rather than silently wrapping it.
+     *
+     * Non-object inputs (strings, numbers, arrays) are intentionally coerced
+     * to `{ input: value }` via {@link ensureInputIsObject}. This preserves the
+     * convenience pattern used by tool/function callables, which forward raw
+     * string arguments into an executor.
+     *
      * @param _input
      * @returns original input formatted for handler
      */
@@ -616,7 +719,7 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      * @param _input
      * @returns output O
      */
-    getHandlerOutput(out: any, _metadata: ExecutorExecutionMetadata<any, O>, _options?: any): O;
+    getHandlerOutput(out: any, _metadata: ExecutorExecutionMetadata<any, O>, _options?: any, _context?: ExecutionContext<I, O>): O;
     /**
      *
      * execute - Runs the executor
@@ -624,9 +727,10 @@ declare abstract class BaseExecutor<I extends PlainObject, O = any, H extends Ba
      * @returns handler output
      */
     execute(_input: I, _options?: any): Promise<O>;
+    private collectHookErrors;
     metadata(): Record<string, any>;
     getMetadata(metadata?: Record<string, any>): ExecutorMetadata;
-    runHook(hook: keyof H, _metadata: ExecutorExecutionMetadata): void;
+    runHook(hook: keyof H, _metadata: ExecutorExecutionMetadata): HookErrorRecord[];
     setHooks(hooks?: CoreExecutorHookInput<H>): this;
     removeHook(eventName: keyof H, fn: ListenerFunction): this;
     on(eventName: keyof H, fn: ListenerFunction): this;
@@ -785,16 +889,24 @@ 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, 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> {
     llm: Llm;
     prompt: Prompt | undefined;
     promptFn: any;
     parser: StringParser | Parser;
     constructor(llmConfiguration: ExecutorWithLlmOptions<Llm, Prompt, Parser, State>, options?: CoreExecutorExecuteOptions<LlmExecutorHooks>);
+    /**
+     * Runs the executor against the configured LLM and prompt.
+     *
+     * `null` and `undefined` are rejected with a `TypeError`: the declared
+     * input type requires an object, and silently coercing missing input hides a
+     * clear contract violation. Use `{}` for prompts that declare no template
+     * variables. See issue #410.
+     */
     execute(_input: PromptInput<Prompt>, _options?: LlmExecutorExecuteOptions): Promise<ParserOutput<Parser>>;
-    handler(_input: PromptInput<Prompt>, ..._args: any[]): Promise<any>;
+    handler(_input: PromptInput<Prompt>, _options?: LlmExecutorExecuteOptions, _context?: ExecutionContext<PromptInput<Prompt>, ParserOutput<Parser>>): Promise<any>;
     getHandlerInput(_input: PromptInput<Prompt>): Promise<any>;
-    getHandlerOutput(out: BaseLlCall, _metadata: ExecutorExecutionMetadata<PromptInput<Prompt>, ParserOutput<Parser>>): ParserOutput<Parser>;
+    getHandlerOutput(out: BaseLlCall, _metadata: ExecutorExecutionMetadata<PromptInput<Prompt>, ParserOutput<Parser>>, _options?: LlmExecutorExecuteOptions, _context?: ExecutionContext<PromptInput<Prompt>, ParserOutput<Parser>>): ParserOutput<Parser>;
     metadata(): {
         llm: Record<string, any>;
     };
@@ -844,7 +956,7 @@ declare const hookOnError = "onError";
 declare const hookOnSuccess = "onSuccess";
 
 type ListenerFunction = (...args: any[]) => void;
-type ParserOutput<P> = P extends BaseParser<infer T> ? T : never;
+type ParserOutput<P> = P extends BaseParser<infer T, any> ? T : never;
 type PromptInput<P> = P extends BasePrompt<infer T> ? T : never;
 interface ExecutorWithLlmOptions<Llm, Prompt, Parser, State> {
     name?: string;
@@ -871,6 +983,15 @@ interface ExecutorMetadata {
     executions: number;
     metadata?: Record<string, any>;
 }
+interface HookErrorRecord {
+    hook: string;
+    error: unknown;
+    errorMessage: string;
+    errorCategory?: string;
+    errorCode?: string;
+    errorContext?: unknown;
+    errorCause?: unknown;
+}
 interface ExecutorExecutionMetadata<I = any, O = any> {
     start: null | number;
     end: null | number;
@@ -880,12 +1001,29 @@ interface ExecutorExecutionMetadata<I = any, O = any> {
     output?: O;
     errorMessage?: string;
     error?: Error;
+    errorCategory?: string;
+    errorCode?: string;
+    errorContext?: unknown;
+    errorCause?: unknown;
+    hookErrors?: HookErrorRecord[];
     metadata?: null | ExecutorMetadata;
 }
 interface ExecutorContext<I = any, O = any, A = Record<string, any>> extends ExecutorExecutionMetadata<I, O> {
     metadata: ExecutorMetadata;
     attributes: A;
 }
+/**
+ * Per-call execution context. Built by `BaseExecutor.execute()` and threaded
+ * through `handler()`, `llm.call()`, parsers, and warnings. Provides a single
+ * place to read the resolved trace ID, stable executor identity, and the
+ * mutable execution state for the current run.
+ */
+interface ExecutionContext<I = any, O = any, A = Record<string, any>> {
+    traceId?: string;
+    executor: ExecutorMetadata;
+    execution: ExecutorExecutionMetadata<I, O>;
+    attributes: A;
+}
 interface BaseExecutorHooks {
     [hookOnError]: ListenerFunction[];
     [hookOnSuccess]: ListenerFunction[];
@@ -919,14 +1057,11 @@ interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"
     jsonSchema?: Record<string, any>;
 }
 
-type CreateParserType = "json" | "string" | "boolean" | "number" | "stringExtract" | "listToArray" | "listToJson" | "listToKeyValue" | "replaceStringTemplate" | "markdownCodeBlocks" | "markdownCodeBlock";
-interface BaseParserOptions {
-}
-interface BaseParserOptionsWithSchema<S extends JSONSchema | undefined = undefined> extends BaseParserOptions {
+interface JsonParserOptions<S extends JSONSchema | undefined = undefined> {
     schema?: S;
     validateSchema?: boolean;
 }
-interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends BaseParserOptionsWithSchema<S> {
+interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends JsonParserOptions<S> {
     keyTransform?: "camelCase" | "preserve";
 }
 
@@ -1397,8 +1532,224 @@ interface Config<Pk = LlmProviderKey> {
      * `getEmbeddingOutputParser` instead.
      */
     transformResponse?: (result: any, _config?: Config<any>) => OutputResult;
+    /**
+     * Marks this config as deprecated. When set, useLlm() will emit a one-time
+     * deprecation warning to inform users about upcoming model shutdowns.
+     */
+    deprecated?: {
+        shorthand: string;
+        message: string;
+    };
 }
 
+type JsonSafe = string | number | boolean | null | JsonSafe[] | {
+    [key: string]: JsonSafe;
+};
+type ErrorCategory = "unknown" | "configuration" | "llm" | "embedding" | "prompt" | "parser" | "executor" | "callable" | "state" | "request" | "auth" | "template" | "internal";
+type BaseErrorContext = {
+    operation?: string;
+    provider?: string;
+    model?: string;
+    key?: string;
+    input?: unknown;
+    output?: unknown;
+    response?: unknown;
+    status?: number;
+    url?: string;
+    parser?: string;
+    promptType?: string;
+    functionName?: string;
+    hook?: string;
+    expected?: unknown;
+    received?: unknown;
+    resolution?: string;
+    docsPath?: string;
+    docsUrl?: string;
+};
+type ConfigurationProviderContext = BaseErrorContext & {
+    provider?: string;
+    availableProviders?: string[];
+};
+type MissingConfigurationContext = BaseErrorContext & {
+    provider?: string;
+    key?: string;
+    option?: string;
+    envVar?: string;
+};
+type InvalidHeadersContext = BaseErrorContext & {
+    provider?: string;
+    key?: string;
+    headerTemplate?: string;
+    replacedHeadersExcerpt?: string;
+};
+type ParserInvalidTypeContext = BaseErrorContext & {
+    parser?: unknown;
+    availableParsers?: string[];
+};
+type ParserSchemaValidationContext = BaseErrorContext & {
+    parser?: string;
+    schemaErrors?: unknown;
+    outputExcerpt?: string;
+};
+type ParserParseFailedContext = BaseErrorContext & {
+    parser?: string;
+    reason?: string;
+    inputExcerpt?: string;
+    inputExcerptTruncated?: boolean;
+    inputLength?: number;
+    matchCount?: number;
+    match?: string;
+    outputExcerpt?: string;
+};
+type PromptInputContext = BaseErrorContext & {
+    promptType?: string;
+};
+type PromptMessagesContext = BaseErrorContext & {
+    provider?: string;
+};
+type PromptMissingTemplateVariableContext = BaseErrorContext & {
+    promptType?: string;
+    missingVariables: string[];
+    missingHelpers: string[];
+};
+type NormalizedProviderError = {
+    message?: string;
+    providerType?: string;
+    providerCode?: string;
+    status?: number;
+    statusText?: string;
+    retryable?: boolean;
+    retryAfterMs?: number;
+};
+type ProviderErrorContext = BaseErrorContext & {
+    provider?: string;
+    model?: string;
+    status?: number;
+    statusText?: string;
+    url?: string;
+    providerError?: NormalizedProviderError;
+    providerErrorBody?: unknown;
+    providerErrorRaw?: string;
+    responseHeaders?: Record<string, string>;
+};
+type ProviderResponseContext = BaseErrorContext & {
+    provider?: string;
+    model?: string;
+    responseExcerpt?: string;
+    lineNumber?: number;
+    lineExcerpt?: string;
+    lineCount?: number;
+    availableProviders?: string[];
+};
+type EmbeddingDimensionsContext = BaseErrorContext & {
+    provider?: string;
+    model?: string;
+    dimensions?: number;
+};
+type ExecutorErrorContext = BaseErrorContext & {
+    executorName?: string;
+    executorType?: string;
+    traceId?: string;
+};
+type ExecutorHookContext = ExecutorErrorContext & {
+    hook?: string;
+    hookCount?: number;
+    maxHooksPerEvent?: number;
+};
+type CallableErrorContext = BaseErrorContext & {
+    functionName?: string;
+    availableFunctions?: string[];
+};
+type TemplateHelperContext = BaseErrorContext & {
+    helper?: string;
+};
+type StateErrorContext = BaseErrorContext & {
+    module?: string;
+};
+type AwsAuthContext = BaseErrorContext & {
+    url?: string;
+    regionName?: string;
+};
+type RequestErrorContext = BaseErrorContext & {
+    url?: string;
+    status?: number;
+    statusText?: string;
+    providerError?: NormalizedProviderError;
+    providerErrorBody?: unknown;
+    providerErrorRaw?: string;
+    responseHeaders?: Record<string, string>;
+};
+type InternalErrorContext = BaseErrorContext & {
+    invariant?: string;
+};
+type ErrorContextByCode = {
+    "configuration.missing_provider": ConfigurationProviderContext;
+    "configuration.invalid_provider": ConfigurationProviderContext;
+    "configuration.missing_env": MissingConfigurationContext;
+    "configuration.missing_option": MissingConfigurationContext;
+    "configuration.invalid_headers": InvalidHeadersContext;
+    "parser.invalid_type": ParserInvalidTypeContext;
+    "parser.invalid_input": ParserParseFailedContext;
+    "parser.parse_failed": ParserParseFailedContext;
+    "parser.schema_validation_failed": ParserSchemaValidationContext;
+    "prompt.missing_input": PromptInputContext;
+    "prompt.invalid_messages": PromptMessagesContext;
+    "prompt.missing_template_variable": PromptMissingTemplateVariableContext;
+    "llm.provider_http_error": ProviderErrorContext;
+    "llm.provider_rate_limited": ProviderErrorContext;
+    "llm.provider_auth_failed": ProviderErrorContext;
+    "llm.provider_invalid_request": ProviderErrorContext;
+    "llm.provider_unavailable": ProviderErrorContext;
+    "llm.invalid_response_shape": ProviderResponseContext;
+    "llm.invalid_jsonl_response": ProviderResponseContext;
+    "embedding.provider_http_error": ProviderErrorContext;
+    "embedding.provider_rate_limited": ProviderErrorContext;
+    "embedding.provider_auth_failed": ProviderErrorContext;
+    "embedding.provider_invalid_request": ProviderErrorContext;
+    "embedding.provider_unavailable": ProviderErrorContext;
+    "embedding.missing_provider": ConfigurationProviderContext;
+    "embedding.invalid_provider": ConfigurationProviderContext;
+    "embedding.unsupported_dimensions": EmbeddingDimensionsContext;
+    "embedding.invalid_response_shape": ProviderResponseContext;
+    "executor.missing_prompt": ExecutorErrorContext;
+    "executor.hook_limit_reached": ExecutorHookContext;
+    "executor.hook_failed": ExecutorHookContext;
+    "callable.invalid_handler": CallableErrorContext;
+    "callable.handler_not_found": CallableErrorContext;
+    "callable.validation_failed": CallableErrorContext;
+    "template.invalid_helper_arguments": TemplateHelperContext;
+    "state.invalid_arguments": StateErrorContext;
+    "auth.aws_signing_input_missing": AwsAuthContext;
+    "request.invalid_url": RequestErrorContext;
+    "request.http_error": RequestErrorContext;
+    "internal.invariant_failed": InternalErrorContext;
+    "unknown.unclassified": Record<string, unknown>;
+};
+type ErrorCodes = keyof ErrorContextByCode;
+type CategoryFor<C extends ErrorCodes> = C extends `${infer Category}.${string}` ? Category & ErrorCategory : never;
+type SerializableCause = {
+    name?: string;
+    message?: string;
+    category?: string;
+    code?: string;
+    context?: unknown;
+    cause?: unknown;
+} | JsonSafe;
+type LlmExeErrorOptions<C extends ErrorCodes = ErrorCodes> = {
+    code: C;
+    context?: ErrorContextByCode[C];
+    cause?: unknown;
+};
+type LlmExeErrorJson<C extends ErrorCodes = ErrorCodes> = {
+    name: "LlmExeError";
+    message: string;
+    category: CategoryFor<C>;
+    code: C;
+    context?: ErrorContextByCode[C];
+    cause?: SerializableCause;
+    truncated?: boolean;
+};
+
 declare function enforceResultAttributes<O>(input: any): {
     result: O;
     attributes: Record<string, any>;
@@ -1513,6 +1864,20 @@ declare function assert(condition: any, message?: string | Error | undefined): a
 
 declare function defineSchema<T>(obj: Narrow<T>): Narrow<T>;
 
+declare const LLM_EXE_ERROR_SYMBOL: unique symbol;
+declare class LlmExeError<C extends ErrorCodes = "unknown.unclassified"> extends Error {
+    readonly name: "LlmExeError";
+    readonly isLlmExeError: true;
+    readonly [LLM_EXE_ERROR_SYMBOL]: true;
+    readonly category: CategoryFor<C>;
+    readonly code: C;
+    readonly context?: ErrorContextByCode[C];
+    constructor(message: string, options: LlmExeErrorOptions<C>);
+    toJSON(): LlmExeErrorJson<C>;
+}
+
+declare function isLlmExeError<C extends ErrorCodes>(error: unknown, code?: C | readonly C[]): error is LlmExeError<C>;
+
 declare function importPartials(_partials: {
     [key in string]: string;
 }): PromptPartial[];
@@ -1536,6 +1901,9 @@ declare function isObjectStringified(maybeObject: string): boolean;
 declare function registerHelpers(helpers: any[]): void;
 declare function registerPartials(partials: any[]): void;
 
+declare const index_LLM_EXE_ERROR_SYMBOL: typeof LLM_EXE_ERROR_SYMBOL;
+type index_LlmExeError<C extends ErrorCodes = "unknown.unclassified"> = LlmExeError<C>;
+declare const index_LlmExeError: typeof LlmExeError;
 declare const index_assert: typeof assert;
 declare const index_asyncCallWithTimeout: typeof asyncCallWithTimeout;
 declare const index_defineSchema: typeof defineSchema;
@@ -1543,6 +1911,7 @@ declare const index_filterObjectOnSchema: typeof filterObjectOnSchema;
 declare const index_guessProviderFromModel: typeof guessProviderFromModel;
 declare const index_importHelpers: typeof importHelpers;
 declare const index_importPartials: typeof importPartials;
+declare const index_isLlmExeError: typeof isLlmExeError;
 declare const index_isObjectStringified: typeof isObjectStringified;
 declare const index_maybeParseJSON: typeof maybeParseJSON;
 declare const index_maybeStringifyJSON: typeof maybeStringifyJSON;
@@ -1551,7 +1920,7 @@ declare const index_registerPartials: typeof registerPartials;
 declare const index_replaceTemplateString: typeof replaceTemplateString;
 declare const index_replaceTemplateStringAsync: typeof replaceTemplateStringAsync;
 declare namespace index {
-  export { 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_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_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;
@@ -1588,15 +1957,15 @@ declare const configs: {
     "deepseek.chat": Config<keyof AllLlm>;
     "deepseek.v4-flash": Config<keyof AllLlm>;
     "deepseek.v4-pro": Config<keyof AllLlm>;
-    "google.chat.v1": Config<keyof AllLlm>;
-    "google.gemini-2.5-flash": Config<keyof AllLlm>;
-    "google.gemini-2.5-flash-lite": Config<keyof AllLlm>;
-    "google.gemini-2.5-pro": Config<keyof AllLlm>;
-    "google.gemini-3.1-flash-lite": Config<keyof AllLlm>;
-    "google.gemini-3.5-flash": Config<keyof AllLlm>;
     "google.gemini-2.0-flash": Config<keyof AllLlm>;
     "google.gemini-2.0-flash-lite": Config<keyof AllLlm>;
     "google.gemini-1.5-pro": Config<keyof AllLlm>;
+    "google.gemini-2.5-pro": Config<any>;
+    "google.gemini-2.5-flash-lite": Config<any>;
+    "google.gemini-2.5-flash": Config<any>;
+    "google.chat.v1": Config<keyof AllLlm>;
+    "google.gemini-3.1-flash-lite": Config<keyof AllLlm>;
+    "google.gemini-3.5-flash": Config<keyof AllLlm>;
     "ollama.chat.v1": Config<keyof AllLlm>;
     "ollama.deepseek-r1": Config<keyof AllLlm>;
     "ollama.llama3.3": Config<keyof AllLlm>;
@@ -1622,20 +1991,21 @@ declare const configs: {
     "xai.grok-4.20-reasoning": Config<keyof AllLlm>;
     "amazon:anthropic.chat.v1": Config<keyof AllLlm>;
     "amazon:meta.chat.v1": Config<keyof AllLlm>;
+    "anthropic.claude-3-opus": Config<any>;
+    "anthropic.claude-3-5-haiku": Config<any>;
+    "anthropic.claude-3-5-sonnet": Config<any>;
+    "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-opus-4-7": Config<keyof AllLlm>;
     "anthropic.claude-sonnet-4-6": Config<keyof AllLlm>;
     "anthropic.claude-opus-4-5": Config<keyof AllLlm>;
     "anthropic.claude-haiku-4-5": Config<keyof AllLlm>;
     "anthropic.claude-sonnet-4-5": Config<keyof AllLlm>;
-    "anthropic.claude-opus-4-6": Config<keyof AllLlm>;
-    "anthropic.claude-opus-4-1": Config<keyof AllLlm>;
-    "anthropic.claude-sonnet-4": Config<keyof AllLlm>;
-    "anthropic.claude-opus-4": Config<keyof AllLlm>;
-    "anthropic.claude-3-7-sonnet": Config<keyof AllLlm>;
-    "anthropic.claude-3-5-sonnet": Config<keyof AllLlm>;
-    "anthropic.claude-3-5-haiku": Config<keyof AllLlm>;
-    "anthropic.claude-3-opus": Config<keyof AllLlm>;
+    "openai.o4-mini": Config<any>;
     "openai.chat.v1": Config<keyof AllLlm>;
     "openai.chat-mock.v1": Config<keyof AllLlm>;
     "openai.gpt-5.2": Config<keyof AllLlm>;
@@ -1648,12 +2018,11 @@ declare const configs: {
     "openai.gpt-4": Config<keyof AllLlm>;
     "openai.gpt-4o": Config<keyof AllLlm>;
     "openai.gpt-4o-mini": Config<keyof AllLlm>;
-    "openai.o4-mini": Config<keyof AllLlm>;
 };
 
 declare function useLlm<T extends keyof typeof configs>(provider: T, options?: AllUseLlmOptions[T]["input"]): BaseLlm;
 declare function useLlmConfiguration<T extends keyof typeof configs>(config: Config<any>): (options?: AllUseLlmOptions[T]["input"]) => {
-    call: (messages: string | IChatMessages, options?: LlmExecutorWithFunctionsOptions) => Promise<{
+    call: (messages: string | IChatMessages, options?: LlmExecutorWithFunctionsOptions, context?: ExecutionContext) => Promise<{
         getResultContent: (index?: number) => OutputResultContent[];
         getResultText: (index?: number) => string;
         getResult: () => OutputResult;
@@ -1682,7 +2051,7 @@ declare function createOpenAiCompatibleConfiguration<K extends Config["key"]>(ov
 }): Config<keyof AllLlm>;
 
 declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, options: AllEmbedding[T]["input"]): {
-    call: (messages: string | string[], options?: LlmExecutorWithFunctionsOptions) => Promise<{
+    call: (messages: string | string[], options?: LlmExecutorWithFunctionsOptions, context?: ExecutionContext) => Promise<{
         getEmbedding: (index?: number) => number[];
         getResult: () => EmbeddingOutputResult;
     }>;
@@ -1700,4 +2069,4 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ExecutorContext, type IChatMessages, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type OpenAIModelName, OpenAiFunctionParser, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, 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 };