llm-exe 2.3.10 → 3.0.0-beta.1

package/dist/index.js

@@ -46,6 +46,8 @@ __export(index_exports, {
   CustomParser: () => CustomParser,
   DefaultState: () => DefaultState,
   DefaultStateItem: () => DefaultStateItem,
+  LLM_EXE_ERROR_SYMBOL: () => LLM_EXE_ERROR_SYMBOL,
+  LlmExeError: () => LlmExeError,
   LlmExecutorOpenAiFunctions: () => LlmExecutorOpenAiFunctions,
   LlmExecutorWithFunctions: () => LlmExecutorWithFunctions,
   LlmNativeFunctionParser: () => LlmNativeFunctionParser,
@@ -66,6 +68,7 @@ __export(index_exports, {
   createStateItem: () => createStateItem,
   defineSchema: () => defineSchema,
   guards: () => guards_exports,
+  isLlmExeError: () => isLlmExeError,
   registerHelpers: () => registerHelpers,
   registerPartials: () => registerPartials,
   useExecutors: () => useExecutors,
@@ -118,6 +121,11 @@ var ExecutorExecutionMetadataState = class {
       output: void 0,
       errorMessage: void 0,
       error: void 0,
+      errorCategory: void 0,
+      errorCode: void 0,
+      errorContext: void 0,
+      errorCause: void 0,
+      hookErrors: void 0,
       metadata: null
     });
     if (items) {
@@ -145,6 +153,11 @@ var ExecutorExecutionMetadataState = class {
       output: __privateGet(this, _state).output,
       errorMessage: __privateGet(this, _state).errorMessage,
       error: __privateGet(this, _state).error,
+      errorCategory: __privateGet(this, _state).errorCategory,
+      errorCode: __privateGet(this, _state).errorCode,
+      errorContext: __privateGet(this, _state).errorContext,
+      errorCause: __privateGet(this, _state).errorCause,
+      hookErrors: __privateGet(this, _state).hookErrors,
       metadata: __privateGet(this, _state).metadata
     });
   }
@@ -159,6 +172,653 @@ var hookOnComplete = `onComplete`;
 var hookOnError = `onError`;
 var hookOnSuccess = `onSuccess`;
 
+// src/errors/knownCodes.ts
+var ALL_CODES = [
+  "configuration.missing_provider",
+  "configuration.invalid_provider",
+  "configuration.missing_env",
+  "configuration.missing_option",
+  "configuration.invalid_headers",
+  "parser.invalid_type",
+  "parser.invalid_input",
+  "parser.parse_failed",
+  "parser.schema_validation_failed",
+  "prompt.missing_input",
+  "prompt.invalid_messages",
+  "prompt.missing_template_variable",
+  "llm.provider_http_error",
+  "llm.provider_rate_limited",
+  "llm.provider_auth_failed",
+  "llm.provider_invalid_request",
+  "llm.provider_unavailable",
+  "llm.invalid_response_shape",
+  "llm.invalid_jsonl_response",
+  "embedding.provider_http_error",
+  "embedding.provider_rate_limited",
+  "embedding.provider_auth_failed",
+  "embedding.provider_invalid_request",
+  "embedding.provider_unavailable",
+  "embedding.missing_provider",
+  "embedding.invalid_provider",
+  "embedding.unsupported_dimensions",
+  "embedding.invalid_response_shape",
+  "executor.missing_prompt",
+  "executor.hook_limit_reached",
+  "executor.hook_failed",
+  "callable.invalid_handler",
+  "callable.handler_not_found",
+  "callable.validation_failed",
+  "template.invalid_helper_arguments",
+  "state.invalid_arguments",
+  "auth.aws_signing_input_missing",
+  "request.invalid_url",
+  "request.http_error",
+  "internal.invariant_failed",
+  "unknown.unclassified"
+];
+var KNOWN_ERROR_CODES = new Set(ALL_CODES);
+
+// src/errors/serialize.ts
+var MAX_VALUE_DEPTH = 5;
+var MAX_CAUSE_DEPTH = 5;
+var CIRCULAR = "[Circular]";
+var SYMBOL = Symbol.for("llm-exe.error");
+function isLlmExeErrorLike(value) {
+  if (!value || typeof value !== "object") return false;
+  return value[SYMBOL] === true || value.isLlmExeError === true;
+}
+function isErrorLike(value) {
+  if (value instanceof Error) return true;
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.message === "string" && typeof v.name === "string";
+}
+function isResponseLike(value) {
+  if (!value || typeof value !== "object") return false;
+  if (typeof Response !== "undefined" && value instanceof Response) return true;
+  return false;
+}
+function describeOpaque(value) {
+  const tag = Object.prototype.toString.call(value).slice(8, -1);
+  if (tag === "Object") return "[object Object]";
+  return `[object ${tag}]`;
+}
+function safeValue(value, seen, depth) {
+  if (value === null) return null;
+  if (value === void 0) return null;
+  const t = typeof value;
+  if (t === "string") return value;
+  if (t === "boolean") return value;
+  if (t === "number") {
+    const n = value;
+    return Number.isFinite(n) ? n : null;
+  }
+  if (t === "bigint") return value.toString();
+  if (t === "symbol") return String(value);
+  if (t === "function") {
+    const name = value.name;
+    return name ? `[Function ${name}]` : "[Function]";
+  }
+  if (depth >= MAX_VALUE_DEPTH) {
+    return describeOpaque(value);
+  }
+  if (seen.has(value)) return CIRCULAR;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const arr = [];
+      for (let i = 0; i < value.length; i++) {
+        arr.push(safeValue(value[i], seen, depth + 1));
+      }
+      return arr;
+    }
+    if (value instanceof Date) {
+      const ts = value.getTime();
+      return Number.isFinite(ts) ? new Date(ts).toISOString() : null;
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(value)) {
+      return `[Buffer length=${value.length}]`;
+    }
+    if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
+      return describeOpaque(value);
+    }
+    if (isResponseLike(value)) {
+      return {
+        name: "Response",
+        status: value.status,
+        statusText: value.statusText ?? "",
+        url: value.url ?? ""
+      };
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+      const ctor = value.constructor;
+      if (ctor && ctor.name && ctor.name !== "Object") {
+        const out2 = {};
+        for (const key of Object.keys(value)) {
+          const v = value[key];
+          if (v === void 0) continue;
+          out2[key] = safeValue(v, seen, depth + 1);
+        }
+        return Object.keys(out2).length > 0 ? out2 : describeOpaque(value);
+      }
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+      const v = value[key];
+      if (v === void 0) continue;
+      out[key] = safeValue(v, seen, depth + 1);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+function freshSafeValue(value) {
+  return safeValue(value, /* @__PURE__ */ new WeakSet(), 0);
+}
+function serializeOne(error, errorSeen, causeDepth, options) {
+  if (error === null || error === void 0) return null;
+  if (typeof error !== "object") return freshSafeValue(error);
+  if (errorSeen.has(error)) return CIRCULAR;
+  errorSeen.add(error);
+  try {
+    if (isLlmExeErrorLike(error)) {
+      const e = error;
+      const out = {
+        name: "LlmExeError",
+        message: typeof e.message === "string" ? e.message : "",
+        category: typeof e.category === "string" ? e.category : "unknown",
+        code: typeof e.code === "string" ? e.code : "unknown.unclassified"
+      };
+      if (e.context !== void 0) {
+        out.context = freshSafeValue(e.context);
+      }
+      if (options.includeStack && typeof e.stack === "string") {
+        out.stack = e.stack;
+      }
+      if (e.cause !== void 0) {
+        if (causeDepth + 1 >= MAX_CAUSE_DEPTH) {
+          out.cause = { truncated: true };
+        } else {
+          out.cause = serializeOne(e.cause, errorSeen, causeDepth + 1, options);
+        }
+      }
+      return out;
+    }
+    if (isResponseLike(error)) {
+      return {
+        name: "Response",
+        status: error.status,
+        statusText: error.statusText ?? "",
+        url: error.url ?? ""
+      };
+    }
+    if (isErrorLike(error)) {
+      const e = error;
+      const out = {
+        name: typeof e.name === "string" && e.name ? e.name : "Error",
+        message: typeof e.message === "string" ? e.message : ""
+      };
+      if (options.includeStack && typeof e.stack === "string") {
+        out.stack = e.stack;
+      }
+      if (e.cause !== void 0) {
+        if (causeDepth + 1 >= MAX_CAUSE_DEPTH) {
+          out.cause = { truncated: true };
+        } else {
+          out.cause = serializeOne(e.cause, errorSeen, causeDepth + 1, options);
+        }
+      }
+      return out;
+    }
+    return freshSafeValue(error);
+  } finally {
+    errorSeen.delete(error);
+  }
+}
+function serializeLlmExeError(error, options) {
+  return serializeOne(error, /* @__PURE__ */ new WeakSet(), 0, options ?? {});
+}
+
+// src/errors/LlmExeError.ts
+var LLM_EXE_ERROR_SYMBOL = Symbol.for("llm-exe.error");
+function deriveCategory(code) {
+  if (typeof code !== "string") return void 0;
+  if (!KNOWN_ERROR_CODES.has(code)) return void 0;
+  const dot = code.indexOf(".");
+  return code.slice(0, dot);
+}
+var LlmExeError = class _LlmExeError extends Error {
+  constructor(message, options) {
+    super(message);
+    __publicField(this, "category");
+    __publicField(this, "code");
+    __publicField(this, "context");
+    Object.defineProperties(this, {
+      name: {
+        value: "LlmExeError",
+        configurable: true,
+        writable: false,
+        enumerable: false
+      },
+      isLlmExeError: {
+        value: true,
+        configurable: false,
+        writable: false,
+        enumerable: false
+      },
+      [LLM_EXE_ERROR_SYMBOL]: {
+        value: true,
+        configurable: false,
+        writable: false,
+        enumerable: false
+      }
+    });
+    const providedCode = options ? options.code : void 0;
+    const category = deriveCategory(providedCode);
+    if (!category) {
+      this.code = "internal.invariant_failed";
+      this.category = "internal";
+      this.context = {
+        invariant: "invalid_error_code",
+        received: providedCode
+      };
+    } else {
+      this.code = providedCode;
+      this.category = category;
+      if (options.context !== void 0) {
+        this.context = options.context;
+      }
+    }
+    if (options && options.cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: options.cause,
+        configurable: true,
+        writable: true,
+        enumerable: false
+      });
+    }
+    const capture = Error.captureStackTrace;
+    if (typeof capture === "function") {
+      capture(this, _LlmExeError);
+    }
+  }
+  toJSON() {
+    return serializeLlmExeError(this);
+  }
+};
+Object.defineProperty(LlmExeError, "name", {
+  value: "LlmExeError",
+  configurable: true
+});
+
+// src/errors/isLlmExeError.ts
+function isLlmExeError(error, code) {
+  if (!error || typeof error !== "object") return false;
+  const marked = error instanceof LlmExeError || error[LLM_EXE_ERROR_SYMBOL] === true || error.isLlmExeError === true;
+  if (!marked) return false;
+  if (code === void 0) return true;
+  const errorCode = error.code;
+  if (Array.isArray(code)) {
+    return code.includes(errorCode);
+  }
+  return errorCode === code;
+}
+
+// src/errors/format.ts
+var DEFAULT_VALUE_MAX_LENGTH = 200;
+var DEFAULT_LIST_MAX_ITEMS = 8;
+function truncate(s, maxLength) {
+  if (s.length <= maxLength) return s;
+  return s.slice(0, Math.max(0, maxLength - 1)) + "\u2026";
+}
+function compactJson(value) {
+  try {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const replacer = (_key, val) => {
+      if (typeof val === "bigint") return val.toString();
+      if (typeof val === "function") return "[Function]";
+      if (typeof val === "symbol") return String(val);
+      if (val && typeof val === "object") {
+        if (seen.has(val)) return "[Circular]";
+        seen.add(val);
+      }
+      return val;
+    };
+    return JSON.stringify(value, replacer);
+  } catch {
+    return void 0;
+  }
+}
+function formatErrorValue(value, options) {
+  const maxLength = options?.maxLength ?? DEFAULT_VALUE_MAX_LENGTH;
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  const t = typeof value;
+  if (t === "string") {
+    const s = value;
+    return `"${truncate(s, Math.max(2, maxLength - 2))}"`;
+  }
+  if (t === "number") {
+    const n = value;
+    return Number.isFinite(n) ? String(n) : "null";
+  }
+  if (t === "boolean") return value ? "true" : "false";
+  if (t === "bigint") return value.toString();
+  if (t === "symbol") return String(value);
+  if (t === "function") {
+    const name = value.name;
+    return name ? `[Function ${name}]` : "[Function]";
+  }
+  const json = compactJson(value);
+  if (json !== void 0) return truncate(json, maxLength);
+  const tag = Object.prototype.toString.call(value).slice(8, -1);
+  return `[object ${tag}]`;
+}
+function formatErrorList(values, options) {
+  const maxItems = options?.maxItems ?? DEFAULT_LIST_MAX_ITEMS;
+  const maxLength = options?.maxLength;
+  if (!values || values.length === 0) return "";
+  const limit = Math.min(values.length, maxItems);
+  const parts = [];
+  for (let i = 0; i < limit; i++) {
+    parts.push(formatErrorValue(values[i], maxLength ? { maxLength } : void 0));
+  }
+  if (values.length > limit) {
+    parts.push(`\u2026 (${values.length - limit} more)`);
+  }
+  return parts.join(", ");
+}
+
+// src/errors/createLlmExeError.ts
+var DOCS_BASE_URL = "https://llm-exe.com";
+function resolveDefinitionValue(value, context) {
+  if (value === void 0) return void 0;
+  return typeof value === "function" ? value(context) : value;
+}
+function resolveDocsUrl(docsPath) {
+  if (/^https?:\/\//i.test(docsPath)) return docsPath;
+  return `${DOCS_BASE_URL}${docsPath.startsWith("/") ? "" : "/"}${docsPath}`;
+}
+function createLlmExeError(definition, context, options) {
+  const message = definition.message(context);
+  const resolution = resolveDefinitionValue(definition.resolution, context);
+  const docsPath = resolveDefinitionValue(definition.docsPath, context);
+  const docsUrl = docsPath ? resolveDocsUrl(docsPath) : void 0;
+  const mergedContext = {
+    ...context,
+    ...resolution !== void 0 ? { resolution } : null,
+    ...docsPath !== void 0 ? { docsPath } : null,
+    ...docsUrl !== void 0 ? { docsUrl } : null
+  };
+  return new LlmExeError(message, {
+    code: definition.code,
+    context: mergedContext,
+    cause: options?.cause
+  });
+}
+
+// src/utils/modules/redactSecrets.ts
+var TOKEN_MASK_REGEX = /\b(Bearer\s+[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|Bearer\s+[A-Za-z0-9_-]{20,}|sk-ant-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9]{20,}|AIza[0-9A-Za-z_-]{30,}|AKIA[A-Z0-9]{16}|[A-Za-z0-9]{32,})\b/g;
+var FULL_REDACTION_PATTERNS = [
+  // Alternate auth schemes.
+  [/\b(Basic|Digest|AWS4-HMAC-SHA256)\s+[A-Za-z0-9+/=._-]+/g, "$1 [redacted]"],
+  // Header- or query-style key/value pairs. Preserves the original separator
+  // ("Authorization: ..." stays colon, "?token=..." stays equals).
+  [
+    /(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-amz-security-token|x-amz-signature|api[-_]?key|access[-_]?token|token|secret|password)(\s*[:=]\s*)[^\r\n,;&]+/gi,
+    "$1$2[redacted]"
+  ],
+  // JSON-shaped fields.
+  [
+    /"(authorization|api[-_]?key|secret[-_]?key|access[-_]?key|secret|token|password|cookie|x-amz[a-z-]*)"\s*:\s*"[^"]*"/gi,
+    '"$1": "[redacted]"'
+  ]
+];
+function maskToken(match) {
+  if (match.length <= 8) return match;
+  const prefix = match.substring(0, 4);
+  const suffix = match.substring(match.length - 4);
+  return `${prefix}${"*".repeat(match.length - 8)}${suffix}`;
+}
+function redactSecrets(input) {
+  let out = input.replace(TOKEN_MASK_REGEX, maskToken);
+  for (const [pattern, replacement] of FULL_REDACTION_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+var maskApiKeys = redactSecrets;
+var SECRET_URL_QUERY_KEYS = /* @__PURE__ */ new Set([
+  "key",
+  "api_key",
+  "apikey",
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "secret",
+  "client_secret",
+  "password",
+  "x-amz-signature",
+  "x-amz-security-token",
+  "x-amz-credential",
+  "signature"
+]);
+function safeRequestUrl(url) {
+  if (typeof url !== "string" || !url) return url;
+  let working = url;
+  try {
+    const parsed = new URL(url);
+    for (const key of Array.from(parsed.searchParams.keys())) {
+      if (SECRET_URL_QUERY_KEYS.has(key.toLowerCase())) {
+        parsed.searchParams.set(key, "[redacted]");
+      }
+    }
+    working = parsed.toString();
+  } catch {
+  }
+  return redactSecrets(working);
+}
+
+// src/errors/providerErrors.ts
+var PROVIDER_MESSAGE_MAX_LENGTH = 240;
+function safeProviderString(value, maxLength = PROVIDER_MESSAGE_MAX_LENGTH) {
+  if (typeof value !== "string" || value.length === 0) return void 0;
+  const scrubbed = redactSecrets(value);
+  return scrubbed.length > maxLength ? scrubbed.slice(0, maxLength) + "\u2026(truncated)" : scrubbed;
+}
+var SECRET_KEY_REGEX = /authorization|api[-_]?key|secret|token|password|cookie|set-cookie|x-amz/i;
+var REDACTED = "[redacted]";
+var DEFAULT_MAX_BODY_BYTES = 8192;
+var DEFAULT_MAX_STRING_LENGTH = 2e3;
+var MAX_SCRUB_DEPTH = 8;
+var ALLOWED_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
+  // Generic diagnostic headers
+  "content-type",
+  "retry-after",
+  // Request/correlation IDs
+  "request-id",
+  "x-request-id",
+  "x-amzn-requestid",
+  "x-amz-request-id",
+  "x-goog-request-id",
+  // OpenAI-style rate-limit headers
+  "x-ratelimit-limit-requests",
+  "x-ratelimit-remaining-requests",
+  "x-ratelimit-reset-requests",
+  "x-ratelimit-limit-tokens",
+  "x-ratelimit-remaining-tokens",
+  "x-ratelimit-reset-tokens",
+  // Anthropic-style rate-limit headers
+  "anthropic-ratelimit-requests-limit",
+  "anthropic-ratelimit-requests-remaining",
+  "anthropic-ratelimit-requests-reset",
+  "anthropic-ratelimit-tokens-limit",
+  "anthropic-ratelimit-tokens-remaining",
+  "anthropic-ratelimit-tokens-reset"
+]);
+function truncateString(value, max) {
+  if (value.length <= max) return value;
+  return value.slice(0, max) + "\u2026(truncated)";
+}
+function scrub(value, seen, depth, maxStringLength) {
+  if (value === null || value === void 0) return value;
+  const t = typeof value;
+  if (t === "string")
+    return redactSecrets(truncateString(value, maxStringLength));
+  if (t === "number" || t === "boolean") return value;
+  if (t === "bigint") return value.toString();
+  if (t === "symbol") return String(value);
+  if (t === "function") return "[Function]";
+  if (depth >= MAX_SCRUB_DEPTH) return "[deep]";
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const arr = [];
+      for (let i = 0; i < value.length; i++) {
+        arr.push(scrub(value[i], seen, depth + 1, maxStringLength));
+      }
+      return arr;
+    }
+    const out = {};
+    for (const key of Object.keys(value)) {
+      if (SECRET_KEY_REGEX.test(key)) {
+        out[key] = REDACTED;
+        continue;
+      }
+      const v = value[key];
+      out[key] = scrub(v, seen, depth + 1, maxStringLength);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+function safeProviderErrorBody(value, options) {
+  const maxStringLength = options?.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+  const maxBodyBytes = options?.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  if (typeof value === "string") {
+    return redactSecrets(truncateString(value, maxBodyBytes));
+  }
+  return scrub(value, /* @__PURE__ */ new WeakSet(), 0, maxStringLength);
+}
+function safeResponseHeaders(headers) {
+  const out = {};
+  if (!headers) return out;
+  if (typeof headers.forEach === "function" && typeof headers.get === "function") {
+    headers.forEach((value, key) => {
+      const lower = key.toLowerCase();
+      if (ALLOWED_RESPONSE_HEADERS.has(lower) && typeof value === "string") {
+        out[lower] = value;
+      }
+    });
+    return out;
+  }
+  for (const key of Object.keys(headers)) {
+    const value = headers[key];
+    const lower = key.toLowerCase();
+    if (ALLOWED_RESPONSE_HEADERS.has(lower) && typeof value === "string") {
+      out[lower] = value;
+    }
+  }
+  return out;
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed) return void 0;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (!Number.isFinite(seconds)) return void 0;
+    return Math.max(0, Math.round(seconds * 1e3));
+  }
+  const dateMs = Date.parse(trimmed);
+  if (Number.isFinite(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return void 0;
+}
+function readStringField(obj, key) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const v = obj[key];
+  return typeof v === "string" ? v : void 0;
+}
+function readStringOrNumberField(obj, key) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const v = obj[key];
+  if (typeof v === "string") return v;
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return void 0;
+}
+var parseProviderErrorGeneric = (input) => {
+  const status = input.status ?? input.response?.status;
+  const statusText = input.statusText ?? input.response?.statusText;
+  const headers = input.headers ?? {};
+  let message;
+  let providerType;
+  let providerCode;
+  const body = input.bodyJson;
+  if (body && typeof body === "object") {
+    const root = body;
+    const errVal = root.error;
+    const errObj = errVal && typeof errVal === "object" ? errVal : void 0;
+    message = readStringField(errObj, "message") ?? readStringField(root, "message") ?? (typeof errVal === "string" ? errVal : void 0);
+    providerType = readStringField(errObj, "type") ?? readStringField(root, "type") ?? // Bedrock-style: top-level "__type" carries the exception class.
+    readStringField(root, "__type") ?? readStringField(errObj, "status");
+    providerCode = // Accept numeric codes too (Gemini emits error.code: 400 as a number).
+    readStringOrNumberField(errObj, "code") ?? readStringOrNumberField(root, "code") ?? readStringField(errObj, "status");
+  }
+  if (!message && typeof input.bodyText === "string" && input.bodyText.length > 0) {
+    message = input.bodyText;
+  }
+  const retryAfterRaw = headers["retry-after"] ?? headers["Retry-After"];
+  const retryAfterMs = parseRetryAfter(retryAfterRaw);
+  let retryable;
+  if (typeof status === "number") {
+    retryable = status === 408 || status === 429 || status >= 500 && status < 600;
+  }
+  return {
+    message: safeProviderString(message),
+    providerType: safeProviderString(providerType),
+    providerCode: safeProviderString(providerCode),
+    status,
+    statusText,
+    retryable,
+    retryAfterMs
+  };
+};
+function statusToLlmProviderCode(status) {
+  if (status === 429) return "llm.provider_rate_limited";
+  if (status === 401 || status === 403) return "llm.provider_auth_failed";
+  if (status === 400 || status === 422) return "llm.provider_invalid_request";
+  if (status === 408 || status >= 500 && status < 600)
+    return "llm.provider_unavailable";
+  return "llm.provider_http_error";
+}
+function statusToEmbeddingProviderCode(status) {
+  if (status === 429) return "embedding.provider_rate_limited";
+  if (status === 401 || status === 403) return "embedding.provider_auth_failed";
+  if (status === 400 || status === 422)
+    return "embedding.provider_invalid_request";
+  if (status === 408 || status >= 500 && status < 600)
+    return "embedding.provider_unavailable";
+  return "embedding.provider_http_error";
+}
+
+// src/errors/getErrorMetadata.ts
+function getErrorMetadata(error) {
+  if (!isLlmExeError(error)) return {};
+  return {
+    errorCategory: error.category,
+    errorCode: error.code,
+    errorContext: error.context,
+    errorCause: error.cause
+  };
+}
+
 // src/executor/_base.ts
 var BaseExecutor = class {
   constructor(name, type, options) {
@@ -207,12 +867,41 @@ var BaseExecutor = class {
     }
   }
   /**
+   * 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`).
+   */
+  snapshotContext(execution) {
+    return {
+      traceId: this.getTraceId() ?? void 0,
+      executor: this.getMetadata(),
+      execution,
+      attributes: {}
+    };
+  }
+  /**
+   *
+   * 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.
    *
-   * Used to filter the input of the handler
    * @param _input
    * @returns original input formatted for handler
    */
   async getHandlerInput(_input, _metadata, _options) {
+    if (_input === null || typeof _input === "undefined") {
+      throw new TypeError(
+        `[llm-exe] Executor "${this.name}" received null or undefined as input. execute() expects an object matching the prompt's input type.`
+      );
+    }
     return ensureInputIsObject(_input);
   }
   /**
@@ -221,7 +910,7 @@ var BaseExecutor = class {
    * @param _input
    * @returns output O
    */
-  getHandlerOutput(out, _metadata, _options) {
+  getHandlerOutput(out, _metadata, _options, _context) {
     return out;
   }
   /**
@@ -243,25 +932,45 @@ var BaseExecutor = class {
         _options
       );
       _metadata.setItem({ handlerInput: input });
-      let result = await this.handler(input, _options);
+      let result = await this.handler(
+        input,
+        _options,
+        this.snapshotContext(_metadata.asPlainObject())
+      );
       _metadata.setItem({ handlerOutput: result });
       const output = this.getHandlerOutput(
         result,
         _metadata.asPlainObject(),
-        _options
+        _options,
+        this.snapshotContext(_metadata.asPlainObject())
       );
       _metadata.setItem({ output });
-      this.runHook("onSuccess", _metadata.asPlainObject());
+      this.collectHookErrors(
+        this.runHook("onSuccess", _metadata.asPlainObject()),
+        _metadata
+      );
       return output;
     } catch (error) {
-      _metadata.setItem({ error, errorMessage: error.message });
-      this.runHook("onError", _metadata.asPlainObject());
+      _metadata.setItem({
+        error,
+        errorMessage: error.message,
+        ...getErrorMetadata(error)
+      });
+      this.collectHookErrors(
+        this.runHook("onError", _metadata.asPlainObject()),
+        _metadata
+      );
       throw error;
     } finally {
       _metadata.setItem({ end: (/* @__PURE__ */ new Date()).getTime() });
       this.runHook("onComplete", _metadata.asPlainObject());
     }
   }
+  collectHookErrors(fresh, state) {
+    if (fresh.length === 0) return;
+    const existing = state.asPlainObject().hookErrors ?? [];
+    state.setItem({ hookErrors: [...existing, ...fresh] });
+  }
   metadata() {
     return {};
   }
@@ -278,18 +987,23 @@ var BaseExecutor = class {
   }
   runHook(hook, _metadata) {
     const { [hook]: hooks = [] } = pick(this.hooks, this.allowedHooks);
+    const errors = [];
     for (const hookFn of [...hooks]) {
       if (typeof hookFn === "function") {
         try {
           hookFn(_metadata, this.getMetadata());
         } catch (error) {
-          console.warn(
-            `[llm-exe] Error in "${String(hook)}" hook:`,
-            error
-          );
+          const message = error instanceof Error ? error.message : String(error);
+          errors.push({
+            hook: String(hook),
+            error,
+            errorMessage: message,
+            ...getErrorMetadata(error)
+          });
         }
       }
     }
+    return errors;
   }
   setHooks(hooks = {}) {
     const hookKeys = Object.keys(hooks);
@@ -302,8 +1016,19 @@ var BaseExecutor = class {
         for (const hook of _hooks) {
           if (hook && typeof hook === "function" && !this.hooks[hookKey].find((h) => h === hook)) {
             if (this.hooks[hookKey].length >= this.maxHooksPerEvent) {
-              throw new Error(
-                `Maximum number of hooks (${this.maxHooksPerEvent}) reached for event "${String(hookKey)}". Consider removing unused hooks or increasing the limit.`
+              throw new LlmExeError(
+                `Maximum number of hooks (${this.maxHooksPerEvent}) reached for event "${String(hookKey)}". Consider removing unused hooks or increasing the limit.`,
+                {
+                  code: "executor.hook_limit_reached",
+                  context: {
+                    operation: "BaseExecutor.setHooks",
+                    executorName: this.name,
+                    executorType: this.type,
+                    hook: String(hookKey),
+                    hookCount: this.hooks[hookKey].length,
+                    maxHooksPerEvent: this.maxHooksPerEvent
+                  }
+                }
               );
             }
             this.hooks[hookKey].push(hook);
@@ -334,13 +1059,27 @@ var BaseExecutor = class {
   once(eventName, fn) {
     if (typeof fn !== "function") return this;
     if (this.hooks[eventName] && this.hooks[eventName].length >= this.maxHooksPerEvent) {
-      throw new Error(
-        `Maximum number of hooks (${this.maxHooksPerEvent}) reached for event "${String(eventName)}". Consider removing unused hooks or increasing the limit.`
+      throw new LlmExeError(
+        `Maximum number of hooks (${this.maxHooksPerEvent}) reached for event "${String(eventName)}". Consider removing unused hooks or increasing the limit.`,
+        {
+          code: "executor.hook_limit_reached",
+          context: {
+            operation: "BaseExecutor.once",
+            executorName: this.name,
+            executorType: this.type,
+            hook: String(eventName),
+            hookCount: this.hooks[eventName].length,
+            maxHooksPerEvent: this.maxHooksPerEvent
+          }
+        }
       );
     }
     const onceWrapper = (...args) => {
-      fn(...args);
-      this.off(eventName, onceWrapper);
+      try {
+        fn(...args);
+      } finally {
+        this.off(eventName, onceWrapper);
+      }
     };
     if (!this.hooks[eventName]) {
       this.hooks[eventName] = [];
@@ -420,25 +1159,16 @@ var BaseParser = class {
   /**
    * 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, options = {}, target = "text") {
+  constructor(name, target = "text") {
     __publicField(this, "name");
-    __publicField(this, "options");
     __publicField(this, "target", "text");
     this.name = name;
     this.target = target;
-    if (options) {
-      this.options = options;
-    }
   }
 };
 var BaseParserWithJson = class extends BaseParser {
-  /**
-   * Create a new BaseParser.
-   * @param name - The name of the parser.
-   * @param  options - options
-   */
   constructor(name, options) {
     super(name);
     __publicField(this, "schema");
@@ -451,212 +1181,285 @@ var BaseParserWithJson = class extends BaseParser {
   }
 };
 
-// src/utils/modules/assert.ts
-function assert(condition, message) {
-  if (condition === void 0 || condition === null || condition === false) {
-    if (typeof message === "string") {
-      throw new Error(message);
-    } else if (message instanceof Error) {
-      throw message;
-    } else {
-      throw new Error(`Assertion error`);
-    }
-  }
-}
-
-// src/utils/guards.ts
-var guards_exports = {};
-__export(guards_exports, {
-  hasFunctionCall: () => hasFunctionCall,
-  hasToolCall: () => hasToolCall,
-  isAssistantMessage: () => isAssistantMessage,
-  isFunctionCall: () => isFunctionCall,
-  isOutputResult: () => isOutputResult,
-  isOutputResultContentText: () => isOutputResultContentText,
-  isSystemMessage: () => isSystemMessage,
-  isToolCall: () => isToolCall,
-  isUserMessage: () => isUserMessage
-});
-function isOutputResult(obj) {
-  return !!(obj && typeof obj === "object" && "id" in obj && "stopReason" in obj && "content" in obj && Array.isArray(obj.content));
-}
-function isOutputResultContentText(obj) {
-  return !!(obj && typeof obj === "object" && "text" in obj && "type" in obj && obj.type === "text" && typeof obj.text === "string");
-}
-function isFunctionCall(result) {
-  return !!(result && typeof result === "object" && "functionId" in result && "type" in result && result.type === "function_use");
-}
-function isToolCall(result) {
-  return isFunctionCall(result);
-}
-function hasFunctionCall(results) {
-  return !!(results && Array.isArray(results) && results.some(isToolCall));
-}
-function hasToolCall(results) {
-  return hasFunctionCall(results);
-}
-function isUserMessage(message) {
-  return message.role === "user";
-}
-function isAssistantMessage(message) {
-  return message.role === "assistant" || message.role === "model";
-}
-function isSystemMessage(message) {
-  return message.role === "system";
-}
-
 // src/parser/parsers/StringParser.ts
 var StringParser = class extends BaseParser {
-  constructor(options) {
-    super("string", options);
+  constructor() {
+    super("string");
   }
-  parse(text, _options) {
-    if (isOutputResult(text)) {
-      return text.content?.[0]?.text ?? "";
+  parse(text, _attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "StringParser.parse",
+            parser: "string",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
+      );
     }
-    assert(
-      typeof text === "string",
-      `Invalid input. Expected string. Received ${typeof text}.`
-    );
-    const parsed = text.toString();
-    return parsed;
+    return text;
   }
 };
 
-// src/parser/parsers/BooleanParser.ts
-var BooleanParser = class extends BaseParser {
-  constructor(options) {
-    super("boolean", options);
-  }
-  parse(text) {
-    assert(
-      typeof text === "string",
-      `Invalid input. Expected string. Received ${typeof text}.`
-    );
-    const clean = text.toLowerCase().trim();
-    if (clean === "true" || clean === "yes" || clean === "y" || clean === "1") {
-      return true;
-    }
-    return false;
+// src/utils/modules/getEnvironmentVariable.ts
+function getEnvironmentVariable(name) {
+  if (typeof process === "object" && process?.env) {
+    return process.env[name];
+  } else {
+    return void 0;
   }
-};
-
-// src/utils/modules/isFinite.ts
-function isFinite(value) {
-  return typeof value === "number" && Number.isFinite(value);
 }
 
-// src/utils/modules/toNumber.ts
-function toNumber(value) {
-  if (typeof value === "number") {
-    return value;
-  }
-  if (typeof value === "string" && value.trim() !== "") {
-    return Number(value);
-  }
-  return NaN;
+// src/utils/modules/debug.ts
+function isDebugEnabled() {
+  const debugValue = getEnvironmentVariable("LLM_EXE_DEBUG");
+  return typeof debugValue === "string" && debugValue !== "" && debugValue.toLowerCase() !== "undefined" && debugValue.toLowerCase() !== "null";
 }
-
-// src/utils/modules/errors.ts
-var LlmExeError = class extends Error {
-  constructor(message, code, context) {
-    super(message ?? "");
-    __publicField(this, "code");
-    __publicField(this, "context");
-    this.name = this.constructor.name;
-    this.code = code ?? "unknown";
-    this.context = context;
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, this.constructor);
-    }
-  }
-};
-
-// src/parser/parsers/NumberParser.ts
-var NumberParser = class extends BaseParser {
-  constructor(options) {
-    super("number", options);
+function debug(...args) {
+  if (!isDebugEnabled()) {
+    return;
   }
-  parse(text) {
-    const match = text.match(/-?\d+(\.\d+)?/);
-    if (match && isFinite(toNumber(match[0]))) {
-      return toNumber(match[0]);
-    }
-    throw new LlmExeError(
-      `No numeric value found in input.`,
-      "parser",
-      {
-        parser: "number",
-        output: text,
-        error: `No numeric value found in input.`
+  const logs = [];
+  for (const arg of args) {
+    if (arg && typeof arg === "object") {
+      if (arg instanceof Error) {
+      } else if (arg instanceof Array) {
+        logs.push(arg.map((item) => JSON.stringify(item, null, 2)));
+      } else if (arg instanceof Map) {
+        logs.push(
+          Array.from(arg.entries()).map(
+            ([key, value]) => `${key}: ${JSON.stringify(value, null, 2)}`
+          )
+        );
+      } else if (arg instanceof Set) {
+        logs.push(Array.from(arg).map((item) => JSON.stringify(item, null, 2)));
+      } else if (arg instanceof Date) {
+        logs.push(arg.toISOString());
+      } else if (arg instanceof RegExp) {
+        logs.push(arg.toString());
+      } else {
+        try {
+          const str = maskApiKeys(JSON.stringify(arg, null, 2));
+          logs.push(str);
+        } catch (error) {
+          console.error("Error parsing object:", error);
+        }
       }
-    );
+    } else if (typeof arg === "string") {
+      logs.push(safeRequestUrl(arg));
+    } else {
+      logs.push(arg);
+    }
   }
-};
+  if (isDebugEnabled()) {
+    console.debug(...logs);
+  }
+}
 
-// src/utils/index.ts
-var utils_exports = {};
-__export(utils_exports, {
-  assert: () => assert,
-  asyncCallWithTimeout: () => asyncCallWithTimeout,
-  defineSchema: () => defineSchema,
-  filterObjectOnSchema: () => filterObjectOnSchema,
-  guessProviderFromModel: () => guessProviderFromModel,
-  importHelpers: () => importHelpers,
-  importPartials: () => importPartials,
-  isObjectStringified: () => isObjectStringified,
-  maybeParseJSON: () => maybeParseJSON,
-  maybeStringifyJSON: () => maybeStringifyJSON,
-  registerHelpers: () => registerHelpers,
-  registerPartials: () => registerPartials,
-  replaceTemplateString: () => replaceTemplateString,
-  replaceTemplateStringAsync: () => replaceTemplateStringAsync
-});
+// src/parser/parsers/BooleanParser.ts
+var BOOLEAN_VALUES = ["true", "false", "yes", "no", "y", "n", "1", "0"];
+var TRUTHY_VALUES = /* @__PURE__ */ new Set(["true", "yes", "y", "1"]);
+var FALSY_VALUES = /* @__PURE__ */ new Set(["false", "no", "n", "0"]);
+var MAX_ERROR_INPUT_EXCERPT_LENGTH = 500;
+var BooleanParser = class extends BaseParser {
+  constructor() {
+    super("boolean");
+  }
+  getInputErrorContext(text) {
+    const context = {
+      inputLength: text.length
+    };
+    if (isDebugEnabled()) {
+      const truncated = text.length > MAX_ERROR_INPUT_EXCERPT_LENGTH;
+      context.inputExcerpt = truncated ? text.slice(0, MAX_ERROR_INPUT_EXCERPT_LENGTH) : text;
+      context.inputExcerptTruncated = truncated;
+    }
+    return context;
+  }
+  parse(text, _attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "BooleanParser.parse",
+            parser: "boolean",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : typeof text
+          }
+        }
+      );
+    }
+    const clean = text.toLowerCase().trim();
+    if (!clean) {
+      throw new LlmExeError(`No boolean value found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "BooleanParser.parse",
+          parser: "boolean",
+          reason: "empty_input",
+          expected: BOOLEAN_VALUES,
+          ...this.getInputErrorContext(text)
+        }
+      });
+    }
+    if (TRUTHY_VALUES.has(clean)) {
+      return true;
+    }
+    if (FALSY_VALUES.has(clean)) {
+      return false;
+    }
+    throw new LlmExeError(`No boolean value found in input.`, {
+      code: "parser.parse_failed",
+      context: {
+        operation: "BooleanParser.parse",
+        parser: "boolean",
+        reason: "unrecognized_boolean",
+        expected: BOOLEAN_VALUES,
+        ...this.getInputErrorContext(text)
+      }
+    });
+  }
+};
 
-// src/utils/modules/defineSchema.ts
-var import_json_schema_to_ts = require("json-schema-to-ts");
-function defineSchema(obj) {
-  obj.additionalProperties = false;
-  return (0, import_json_schema_to_ts.asConst)(obj);
+// src/utils/modules/isFinite.ts
+function isFinite(value) {
+  return typeof value === "number" && Number.isFinite(value);
 }
 
-// src/utils/modules/handlebars/utils/importPartials.ts
-function importPartials(_partials) {
-  let partials2 = [];
-  if (_partials) {
-    const externalPartialKeys = Object.keys(
-      _partials
-    );
-    for (const externalPartialKey of externalPartialKeys) {
-      if (typeof externalPartialKey === "string") {
-        partials2.push({
-          name: externalPartialKey,
-          template: _partials[externalPartialKey]
-        });
-      }
-    }
+// src/utils/modules/toNumber.ts
+function toNumber(value) {
+  if (typeof value === "number") {
+    return value;
   }
-  return partials2;
+  if (typeof value === "string" && value.trim() !== "") {
+    return Number(value);
+  }
+  return NaN;
 }
 
-// src/utils/modules/handlebars/utils/importHelpers.ts
-function importHelpers(_helpers) {
-  let helpers = [];
-  if (_helpers) {
-    const externalHelperKeys = Object.keys(
-      _helpers
-    );
-    for (const externalHelperKey of externalHelperKeys) {
-      if (typeof externalHelperKey === "string") {
-        helpers.push({
-          name: externalHelperKey,
-          handler: _helpers[externalHelperKey]
+// src/parser/parsers/NumberParser.ts
+var NUMERIC_TOKEN_PATTERN = /(^|[^\w.,])([+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?)(?![\w,])/g;
+var WHOLE_NUMERIC_PATTERN = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+var NumberParser = class extends BaseParser {
+  constructor(options) {
+    super("number");
+    __publicField(this, "match");
+    this.match = options?.match ?? "extract";
+  }
+  parse(text, _attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "NumberParser.parse",
+            parser: "number",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
+      );
+    }
+    if (text.trim() === "") {
+      throw new LlmExeError(`No numeric value found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "NumberParser.parse",
+          parser: "number",
+          reason: "empty_input",
+          expected: "number",
+          inputLength: text.length
+        }
+      });
+    }
+    if (this.match === "whole") {
+      const trimmed = text.trim();
+      if (!WHOLE_NUMERIC_PATTERN.test(trimmed)) {
+        throw new LlmExeError(`Input is not a whole numeric value.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "NumberParser.parse",
+            parser: "number",
+            reason: "no_numeric_value",
+            expected: "whole number",
+            match: this.match,
+            inputLength: text.length
+          }
+        });
+      }
+      const value2 = toNumber(trimmed.replace(/,/g, ""));
+      if (!isFinite(value2)) {
+        throw new LlmExeError(`Invalid numeric value found in input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "NumberParser.parse",
+            parser: "number",
+            reason: "invalid_number",
+            expected: "finite number",
+            match: this.match,
+            inputLength: text.length
+          }
         });
       }
+      return value2;
+    }
+    const matches = Array.from(text.matchAll(NUMERIC_TOKEN_PATTERN)).map(
+      (match) => match[2]
+    );
+    if (matches.length === 0) {
+      throw new LlmExeError(`No numeric value found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "NumberParser.parse",
+          parser: "number",
+          reason: "no_numeric_value",
+          expected: "number",
+          match: this.match,
+          inputLength: text.length
+        }
+      });
+    }
+    if (matches.length > 1) {
+      throw new LlmExeError(`Multiple numeric values found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "NumberParser.parse",
+          parser: "number",
+          reason: "ambiguous_number",
+          expected: "one numeric value",
+          match: this.match,
+          inputLength: text.length,
+          matchCount: matches.length
+        }
+      });
     }
+    const value = toNumber(matches[0].replace(/,/g, ""));
+    if (!isFinite(value)) {
+      throw new LlmExeError(`Invalid numeric value found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "NumberParser.parse",
+          parser: "number",
+          reason: "invalid_number",
+          expected: "finite number",
+          match: this.match,
+          inputLength: text.length
+        }
+      });
+    }
+    return value;
   }
-  return helpers;
-}
+};
 
 // src/utils/modules/get.ts
 function get(obj, path, defaultValue) {
@@ -710,10 +1513,22 @@ function filterObjectOnSchema(schema, doc, detach, property) {
             return;
           }
         } else {
-          if (sp.type === "integer" || sp.type === "number") {
+          var childType = getType(sp.type);
+          if (childType === "integer" || childType === "number") {
             result[key] = toNumber(filteredChild);
-          } else if (sp.type === "boolean") {
-            result[key] = !!filteredChild;
+          } else if (childType === "boolean") {
+            if (typeof filteredChild === "string") {
+              const normalized = filteredChild.trim().toLowerCase();
+              if (normalized === "true") {
+                result[key] = true;
+              } else if (normalized === "false") {
+                result[key] = false;
+              } else {
+                result[key] = filteredChild;
+              }
+            } else {
+              result[key] = filteredChild;
+            }
           } else {
             result[key] = filteredChild;
           }
@@ -733,67 +1548,566 @@ function filterObjectOnSchema(schema, doc, detach, property) {
   return result;
 }
 
-// src/utils/modules/handlebars/hbs.ts
-var import_handlebars = __toESM(require("handlebars"));
-
-// src/utils/modules/handlebars/utils/registerHelpers.ts
-function _registerHelpers(helpers, instance) {
-  if (helpers && Array.isArray(helpers)) {
-    for (const helper of helpers) {
-      if (helper.name && typeof helper.name === "string" && typeof helper.handler === "function") {
-        if (instance) {
-          instance.registerHelper(helper.name, helper.handler);
-        }
+// src/parser/_utils.ts
+var import_jsonschema = require("jsonschema");
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function getSchemaType(schemaType) {
+  if (!Array.isArray(schemaType)) {
+    return schemaType;
+  }
+  return schemaType.find((type) => type !== "null");
+}
+function enforceParserSchema(schema, parsed) {
+  if (!schema || !parsed || typeof parsed !== "object") {
+    return parsed;
+  }
+  return filterObjectOnSchema(schema, parsed);
+}
+function validateParserSchema(schema, parsed) {
+  if (!schema || !parsed || typeof parsed !== "object") {
+    return null;
+  }
+  const validate = (0, import_jsonschema.validate)(parsed, schema);
+  if (validate.errors.length) {
+    return validate.errors;
+  }
+  return null;
+}
+function coerceParserSchemaValues(schema, parsed) {
+  if (!schema || parsed === null || typeof parsed === "undefined") {
+    return parsed;
+  }
+  const type = getSchemaType(schema.type);
+  if (type === "object" && isPlainObject(parsed)) {
+    const properties = schema.properties || {};
+    return Object.keys(parsed).reduce((output, key) => {
+      const propertySchema = properties[key];
+      output[key] = propertySchema ? coerceParserSchemaValues(propertySchema, parsed[key]) : parsed[key];
+      return output;
+    }, {});
+  }
+  if (type === "array" && Array.isArray(parsed) && schema.items) {
+    return parsed.map(
+      (item) => coerceParserSchemaValues(schema.items, item)
+    );
+  }
+  if ((type === "number" || type === "integer") && typeof parsed === "string") {
+    const trimmed = parsed.trim();
+    if (trimmed !== "") {
+      const value = Number(trimmed);
+      if (Number.isFinite(value)) {
+        return value;
       }
     }
   }
+  if (type === "boolean" && typeof parsed === "string") {
+    const normalized = parsed.trim().toLowerCase();
+    if (normalized === "true") {
+      return true;
+    }
+    if (normalized === "false") {
+      return false;
+    }
+  }
+  return parsed;
+}
+function applyParserSchemaDefaultsAndFilter(schema, parsed) {
+  if (!schema || parsed === null || typeof parsed === "undefined") {
+    return parsed;
+  }
+  const type = getSchemaType(schema.type);
+  if (type === "object" && isPlainObject(parsed)) {
+    const properties = schema.properties;
+    if (!properties) {
+      return parsed;
+    }
+    const keepAdditionalProperties = schema.additionalProperties !== false;
+    const initialOutput = keepAdditionalProperties ? { ...parsed } : {};
+    return Object.keys(properties).reduce((output, key) => {
+      const propertySchema = properties[key];
+      const value = parsed[key];
+      if (typeof value === "undefined") {
+        if (typeof propertySchema?.default !== "undefined") {
+          output[key] = propertySchema.default;
+        }
+        return output;
+      }
+      output[key] = applyParserSchemaDefaultsAndFilter(propertySchema, value);
+      return output;
+    }, initialOutput);
+  }
+  if (type === "array" && Array.isArray(parsed) && schema.items) {
+    return parsed.map(
+      (item) => applyParserSchemaDefaultsAndFilter(schema.items, item)
+    );
+  }
+  return parsed;
 }
 
-// src/utils/modules/handlebars/templates/index.ts
-var MarkdownCode = `{{#if code}}\`\`\`{{#if language}}{{language}}{{/if}}
-{{{code}}}
-\`\`\`{{/if}}`;
-var ThoughtActionResult = `
-{{#if title}}{{#if attributes.stepsTaken.length}}{{title}}
-{{/if}}{{/if}}
-{{#each attributes.stepsTaken as | step |}}
-{{#if step.thought}}Thought: {{step.result}}{{/if}}
-{{#if step.result}}Action: {{step.action}}{{/if}}
-{{#if step.result}}Result: {{step.result}}{{/if}}
-{{/each}}`;
-var ChatConversationHistory = `{{~#if title}}{{~#if chat_history.length}}{{title}}
-{{~/if}}{{~/if}}
-{{#each chat_history as | item |}}
-{{~#eq item.role 'user'}}{{#if @last}}{{../mostRecentRolePrefix}}{{../userName}}{{../mostRecentRoleSuffix}}{{else}}{{../userName}}{{/if}}: {{#if @last}}{{../mostRecentMessagePrefix}}{{/if}}{{{item.content}}}{{#if @last}}{{../mostRecentMessageSuffix}}{{/if}}
-{{/eq}}
-{{~#eq item.role 'assistant'}}{{#if @last}}{{../mostRecentRolePrefix}}{{../assistantName}}{{../mostRecentRoleSuffix}}{{else}}{{../assistantName}}{{/if}}: {{#if @last}}{{../mostRecentMessagePrefix}}{{/if}}{{{item.content}}}{{#if @last}}{{../mostRecentMessageSuffix}}{{/if}}
-{{/eq}}
-{{~#eq item.role 'system'}}{{../systemName}}: {{{item.content}}}
-{{/eq}}
-{{~/each}}`;
-var DialogueHistory = `{{>ChatConversationHistory title=title chat_history=(getKeyOr key []) assistantName=(getOr assistant 'Assistant') userName=(getOr user 'User') systemName=(getOr system 'System') mostRecentRolePrefix=mostRecentRolePrefix mostRecentRoleSuffix=mostRecentRoleSuffix mostRecentMessagePrefix=mostRecentMessagePrefix mostRecentMessageSuffix=mostRecentMessageSuffix}}`;
-var SingleChatMessage = `{{~#eq role 'user'}}{{getOr name 'User'}}: {{{content}}}{{~/eq}}
-{{~#eq role 'assistant'}}{{getOr assistant 'Assistant'}}: {{{content}}}{{~/eq}}
-{{~#eq role 'system'}}{{getOr system 'System'}}: {{{content}}}{{~/eq}}`;
-var ThoughtsAndObservations = `{{~#each thoughts as | step |}}
-{{~#if step.thought}}Thought: {{{step.thought}}}
-{{/if}}
-{{~#if step.observation}}Observation: {{{step.observation}}}
-{{/if}}
-{{~/each}}`;
-var JsonSchema = `{{#if (getKeyOr key false)}}
-\`\`\`json
-{{{indentJson (getKeyOr key) collapse}}}
-\`\`\`
-{{~/if}}`;
-var JsonSchemaExampleJson = `{{#if (getOr key false)}}
-\`\`\`json
-{{{jsonSchemaExample key (getOr property '') collapse}}}
-\`\`\`
-{{~/if}}`;
-var partials = {
-  JsonSchema,
-  JsonSchemaExampleJson,
+// src/parser/parsers/JsonParser.ts
+function isPlainObject2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function normalizeWholeResponseJsonText(input) {
+  const trimmed = input.trim();
+  const fenceMatch = trimmed.match(/^```([a-zA-Z]*)[^\S\r\n]*\r?\n([\s\S]*)```$/);
+  if (!fenceMatch) {
+    return trimmed;
+  }
+  const [, language, body] = fenceMatch;
+  if (language && language.toLowerCase() !== "json") {
+    return trimmed;
+  }
+  return body.trim();
+}
+var JsonParser = class extends BaseParserWithJson {
+  constructor(options = {}) {
+    super("json", options);
+    __publicField(this, "shouldValidateSchema");
+    this.shouldValidateSchema = !!options.schema && options.validateSchema !== false;
+  }
+  /**
+   * 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, _attributes) {
+    let parsed;
+    let inputLength;
+    if (typeof text === "string") {
+      inputLength = text.length;
+      if (text.trim() === "") {
+        throw new LlmExeError(`No JSON value found in input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "JsonParser.parse",
+            parser: "json",
+            reason: "empty_input",
+            expected: "JSON object or array",
+            inputLength
+          }
+        });
+      }
+      try {
+        parsed = JSON.parse(normalizeWholeResponseJsonText(text));
+      } catch (cause) {
+        throw new LlmExeError(`Invalid JSON input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "JsonParser.parse",
+            parser: "json",
+            reason: "invalid_json",
+            expected: "JSON object or array",
+            inputLength
+          },
+          cause
+        });
+      }
+    } else if (Array.isArray(text) || isPlainObject2(text)) {
+      parsed = text;
+    } else {
+      throw new LlmExeError(
+        `Invalid input. Expected JSON string, plain object, or array. Received ${text === null ? "null" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "JsonParser.parse",
+            parser: "json",
+            reason: "invalid_input_type",
+            expected: "JSON string, plain object, or array",
+            received: text === null ? "null" : typeof text
+          }
+        }
+      );
+    }
+    if (!Array.isArray(parsed) && !isPlainObject2(parsed)) {
+      throw new LlmExeError(`Invalid JSON root type.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "JsonParser.parse",
+          parser: "json",
+          reason: "invalid_json_root_type",
+          expected: "JSON object or array",
+          received: parsed === null ? "null" : typeof parsed,
+          inputLength
+        }
+      });
+    }
+    if (this.schema) {
+      if (this.shouldValidateSchema) {
+        const valid = validateParserSchema(this.schema, parsed);
+        if (valid && valid.length) {
+          throw new LlmExeError(valid[0].message, {
+            code: "parser.schema_validation_failed",
+            context: {
+              operation: "JsonParser.parse",
+              parser: "json",
+              schemaErrors: valid.map((error) => error.message)
+            }
+          });
+        }
+      }
+      if (this.shouldValidateSchema) {
+        return applyParserSchemaDefaultsAndFilter(
+          this.schema,
+          parsed
+        );
+      }
+      return enforceParserSchema(this.schema, parsed);
+    }
+    return parsed;
+  }
+};
+
+// src/utils/modules/camelCase.ts
+function camelCase(input) {
+  if (!input) return input;
+  input = input.replace(/[^a-zA-Z0-9_]+/g, " ").trim();
+  const words = input.split(/\s+|_/);
+  return words.map((word, index) => {
+    if (index === 0) {
+      return word.toLowerCase();
+    } else {
+      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+    }
+  }).join("");
+}
+
+// src/parser/_listBoundary.ts
+var LIST_MARKER_PATTERN = /^(?:[-*]\s+|\d+\.\s+|•\s*)/;
+function normalizeListLines(input, context) {
+  const lines = input.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0) {
+    throw new LlmExeError(`No list items found in input.`, {
+      code: "parser.parse_failed",
+      context: {
+        operation: context.operation,
+        parser: context.parser,
+        reason: "empty_input",
+        inputLength: input.length
+      }
+    });
+  }
+  const markedStates = lines.map((line) => LIST_MARKER_PATTERN.test(line));
+  const hasMarked = markedStates.some(Boolean);
+  const hasUnmarked = markedStates.some((marked) => !marked);
+  if (hasMarked && hasUnmarked) {
+    throw new LlmExeError(`Mixed marked and unmarked list items found.`, {
+      code: "parser.parse_failed",
+      context: {
+        operation: context.operation,
+        parser: context.parser,
+        reason: "mixed_list_markers",
+        inputLength: input.length
+      }
+    });
+  }
+  return {
+    lines: hasMarked ? lines.map((line) => line.replace(LIST_MARKER_PATTERN, "").trim()) : lines,
+    marked: hasMarked
+  };
+}
+
+// src/parser/parsers/ListToJsonParser.ts
+var ListToJsonParser = class extends BaseParserWithJson {
+  constructor(options = {}) {
+    super("listToJson", options);
+    __publicField(this, "keyTransform");
+    __publicField(this, "shouldValidateSchema");
+    this.keyTransform = options.keyTransform ?? "camelCase";
+    this.shouldValidateSchema = !!options.schema && options.validateSchema !== false;
+  }
+  /**
+   * 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) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "ListToJsonParser.parse",
+            parser: "listToJson",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
+      );
+    }
+    const { lines } = normalizeListLines(text, {
+      operation: "ListToJsonParser.parse",
+      parser: "listToJson"
+    });
+    const output = {};
+    lines.forEach((line) => {
+      const colonIndex = line.indexOf(":");
+      if (colonIndex === -1) {
+        throw new LlmExeError(`Malformed key/value line.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "ListToJsonParser.parse",
+            parser: "listToJson",
+            reason: "malformed_line",
+            inputLength: text.length
+          }
+        });
+      }
+      const key = line.slice(0, colonIndex).trim();
+      if (!key) {
+        throw new LlmExeError(`Empty key in key/value line.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "ListToJsonParser.parse",
+            parser: "listToJson",
+            reason: "empty_key",
+            inputLength: text.length
+          }
+        });
+      }
+      const transformedKey = this.keyTransform === "preserve" ? key : camelCase(key);
+      if (Object.prototype.hasOwnProperty.call(output, transformedKey)) {
+        throw new LlmExeError(`Duplicate key in key/value input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "ListToJsonParser.parse",
+            parser: "listToJson",
+            reason: "duplicate_key",
+            inputLength: text.length
+          }
+        });
+      }
+      output[transformedKey] = line.slice(colonIndex + 1).trim();
+    });
+    if (this.schema) {
+      const coerced = coerceParserSchemaValues(this.schema, output);
+      if (this.shouldValidateSchema) {
+        const valid = validateParserSchema(this.schema, coerced);
+        if (valid && valid.length) {
+          throw new LlmExeError(valid[0].message, {
+            code: "parser.schema_validation_failed",
+            context: {
+              operation: "ListToJsonParser.parse",
+              parser: "listToJson",
+              schemaErrors: valid.map((error) => error.message)
+            }
+          });
+        }
+      }
+      return applyParserSchemaDefaultsAndFilter(this.schema, coerced);
+    }
+    return output;
+  }
+};
+
+// src/parser/parsers/ListToKeyValueParser.ts
+var ListToKeyValueParser = class extends BaseParser {
+  constructor(options) {
+    super("listToKeyValue");
+    __publicField(this, "keyTransform");
+    this.keyTransform = options?.keyTransform ?? "preserve";
+  }
+  /**
+   * 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, _attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "ListToKeyValueParser.parse",
+            parser: "listToKeyValue",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
+      );
+    }
+    const { lines } = normalizeListLines(text, {
+      operation: "ListToKeyValueParser.parse",
+      parser: "listToKeyValue"
+    });
+    let res = [];
+    for (const line of lines) {
+      const colonIndex = line.indexOf(":");
+      if (colonIndex === -1) {
+        throw new LlmExeError(`Malformed key/value line.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "ListToKeyValueParser.parse",
+            parser: "listToKeyValue",
+            reason: "malformed_line",
+            inputLength: text.length
+          }
+        });
+      }
+      const rawKey = line.slice(0, colonIndex).trim();
+      if (!rawKey) {
+        throw new LlmExeError(`Empty key in key/value line.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "ListToKeyValueParser.parse",
+            parser: "listToKeyValue",
+            reason: "empty_key",
+            inputLength: text.length
+          }
+        });
+      }
+      const key = this.keyTransform === "camelCase" ? camelCase(rawKey) : rawKey;
+      res.push({ key, value: line.slice(colonIndex + 1).trim() });
+    }
+    return res;
+  }
+};
+
+// src/parser/parsers/CustomParser.ts
+var CustomParser = class extends BaseParser {
+  constructor(name, parserFn) {
+    super(name);
+    __publicField(this, "parserFn");
+    this.parserFn = parserFn;
+  }
+  parse(text, context) {
+    return this.parserFn.call(this, text, context);
+  }
+};
+
+// src/parser/parsers/ListToArrayParser.ts
+var ListToArrayParser = class extends BaseParser {
+  constructor() {
+    super("listToArray");
+  }
+  parse(text, _attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "ListToArrayParser.parse",
+            parser: "listToArray",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
+      );
+    }
+    const normalized = normalizeListLines(text, {
+      operation: "ListToArrayParser.parse",
+      parser: "listToArray"
+    });
+    if (!normalized.marked && normalized.lines.length === 1) {
+      throw new LlmExeError(`Input is not list-like.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "ListToArrayParser.parse",
+          parser: "listToArray",
+          reason: "not_list_like",
+          inputLength: text.length
+        }
+      });
+    }
+    return normalized.lines;
+  }
+};
+
+// src/utils/modules/handlebars/hbs.ts
+var import_handlebars = __toESM(require("handlebars"));
+
+// src/utils/modules/handlebars/utils/registerHelpers.ts
+function _registerHelpers(helpers, instance) {
+  if (helpers && Array.isArray(helpers)) {
+    for (const helper of helpers) {
+      if (helper.name && typeof helper.name === "string" && typeof helper.handler === "function") {
+        if (instance) {
+          instance.registerHelper(helper.name, helper.handler);
+        }
+      }
+    }
+  }
+}
+
+// src/utils/modules/handlebars/templates/index.ts
+var MarkdownCode = `{{#if code}}\`\`\`{{#if language}}{{language}}{{/if}}
+{{{code}}}
+\`\`\`{{/if}}`;
+var ThoughtActionResult = `
+{{#if title}}{{#if attributes.stepsTaken.length}}{{title}}
+{{/if}}{{/if}}
+{{#each attributes.stepsTaken as | step |}}
+{{#if step.thought}}Thought: {{step.result}}{{/if}}
+{{#if step.result}}Action: {{step.action}}{{/if}}
+{{#if step.result}}Result: {{step.result}}{{/if}}
+{{/each}}`;
+var ChatConversationHistory = `{{~#if title}}{{~#if chat_history.length}}{{title}}
+{{~/if}}{{~/if}}
+{{#each chat_history as | item |}}
+{{~#eq item.role 'user'}}{{#if @last}}{{../mostRecentRolePrefix}}{{../userName}}{{../mostRecentRoleSuffix}}{{else}}{{../userName}}{{/if}}: {{#if @last}}{{../mostRecentMessagePrefix}}{{/if}}{{{item.content}}}{{#if @last}}{{../mostRecentMessageSuffix}}{{/if}}
+{{/eq}}
+{{~#eq item.role 'assistant'}}{{#if @last}}{{../mostRecentRolePrefix}}{{../assistantName}}{{../mostRecentRoleSuffix}}{{else}}{{../assistantName}}{{/if}}: {{#if @last}}{{../mostRecentMessagePrefix}}{{/if}}{{{item.content}}}{{#if @last}}{{../mostRecentMessageSuffix}}{{/if}}
+{{/eq}}
+{{~#eq item.role 'system'}}{{../systemName}}: {{{item.content}}}
+{{/eq}}
+{{~/each}}`;
+var DialogueHistory = `{{>ChatConversationHistory title=title chat_history=(getKeyOr key []) assistantName=(getOr assistant 'Assistant') userName=(getOr user 'User') systemName=(getOr system 'System') mostRecentRolePrefix=mostRecentRolePrefix mostRecentRoleSuffix=mostRecentRoleSuffix mostRecentMessagePrefix=mostRecentMessagePrefix mostRecentMessageSuffix=mostRecentMessageSuffix}}`;
+var SingleChatMessage = `{{~#eq role 'user'}}{{getOr name 'User'}}: {{{content}}}{{~/eq}}
+{{~#eq role 'assistant'}}{{getOr assistant 'Assistant'}}: {{{content}}}{{~/eq}}
+{{~#eq role 'system'}}{{getOr system 'System'}}: {{{content}}}{{~/eq}}`;
+var ThoughtsAndObservations = `{{~#each thoughts as | step |}}
+{{~#if step.thought}}Thought: {{{step.thought}}}
+{{/if}}
+{{~#if step.observation}}Observation: {{{step.observation}}}
+{{/if}}
+{{~/each}}`;
+var JsonSchema = `{{#if (getKeyOr key false)}}
+\`\`\`json
+{{{indentJson (getKeyOr key) collapse}}}
+\`\`\`
+{{~/if}}`;
+var JsonSchemaExampleJson = `{{#if (getOr key false)}}
+\`\`\`json
+{{{jsonSchemaExample key (getOr property '') collapse}}}
+\`\`\`
+{{~/if}}`;
+var partials = {
+  JsonSchema,
+  JsonSchemaExampleJson,
   MarkdownCode,
   DialogueHistory,
   SingleChatMessage,
@@ -1110,7 +2424,15 @@ function isEmpty(value) {
 // src/utils/modules/handlebars/helpers/async/with.ts
 async function withFnAsync(context, options) {
   if (arguments.length !== 2) {
-    throw new Error("#with requires exactly one argument");
+    throw new LlmExeError("#with requires exactly one argument", {
+      code: "template.invalid_helper_arguments",
+      context: {
+        operation: "handlebars.asyncHelper.with",
+        helper: "with",
+        expected: 1,
+        received: arguments.length
+      }
+    });
   }
   if (isPromise(context)) {
     context = await context;
@@ -1138,7 +2460,15 @@ async function withFnAsync(context, options) {
 // src/utils/modules/handlebars/helpers/async/if.ts
 async function ifFnAsync(conditional, options) {
   if (arguments.length !== 2) {
-    throw new Error("#if requires exactly one argument");
+    throw new LlmExeError("#if requires exactly one argument", {
+      code: "template.invalid_helper_arguments",
+      context: {
+        operation: "handlebars.asyncHelper.if",
+        helper: "if",
+        expected: 1,
+        received: arguments.length
+      }
+    });
   }
   if (isPromise(conditional)) {
     conditional = await conditional;
@@ -1160,7 +2490,15 @@ function isReadableStream(obj) {
 // src/utils/modules/handlebars/helpers/async/each.ts
 async function eachFnAsync(arg1, options) {
   if (!options) {
-    throw new Error("Must pass iterator to #each");
+    throw new LlmExeError("Must pass iterator to #each", {
+      code: "template.invalid_helper_arguments",
+      context: {
+        operation: "handlebars.asyncHelper.each",
+        helper: "each",
+        expected: "an iterator",
+        received: typeof options
+      }
+    });
   }
   const { fn } = options;
   const { inverse } = options;
@@ -1256,7 +2594,15 @@ async function eachFnAsync(arg1, options) {
 // src/utils/modules/handlebars/helpers/async/unless.ts
 async function unlessFnAsync(conditional, options) {
   if (arguments.length !== 2) {
-    throw new Error("#unless requires exactly one argument");
+    throw new LlmExeError("#unless requires exactly one argument", {
+      code: "template.invalid_helper_arguments",
+      context: {
+        operation: "handlebars.asyncHelper.unless",
+        helper: "unless",
+        expected: 1,
+        received: arguments.length
+      }
+    });
   }
   return ifFnAsync.call(this, conditional, {
     fn: options.inverse,
@@ -1450,434 +2796,609 @@ function replaceTemplateString(templateString, substitutions = {}, configuration
   return res;
 }
 
-// src/utils/modules/replaceTemplateStringAsync.ts
-async function replaceTemplateStringAsync(templateString, substitutions = {}, configuration = {
-  helpers: [],
-  partials: []
-}) {
-  if (!templateString) return Promise.resolve(templateString || "");
-  const tempHelpers = [];
-  const tempPartials = [];
-  if (Array.isArray(configuration.helpers)) {
-    hbsAsync.registerHelpers(configuration.helpers);
-    tempHelpers.push(...configuration.helpers.map((a) => a.name));
-  }
-  if (Array.isArray(configuration.partials)) {
-    hbsAsync.registerPartials(configuration.partials);
-    tempPartials.push(...configuration.partials.map((a) => a.name));
+// src/parser/parsers/ReplaceStringTemplateParser.ts
+var ReplaceStringTemplateParser = class extends BaseParser {
+  constructor() {
+    super("replaceStringTemplate");
   }
-  const template = hbsAsync.handlebars.compile(templateString);
-  const res = await template(substitutions, {
-    allowedProtoMethods: {
-      substring: true
-    }
-  });
-  tempHelpers.forEach(function(n) {
-    hbsAsync.handlebars.unregisterHelper(n);
-  });
-  tempPartials.forEach(function(n) {
-    hbsAsync.handlebars.unregisterPartial(n);
-  });
-  return res;
-}
-
-// src/utils/modules/asyncCallWithTimeout.ts
-var asyncCallWithTimeout = async (asyncPromise, timeLimit = 1e4) => {
-  let timeoutHandle;
-  const timeoutPromise = new Promise((_resolve, reject) => {
-    timeoutHandle = setTimeout(() => {
-      return reject(
-        new Error(`LLM call timed out after ${timeLimit}ms`)
+  parse(text, attributes) {
+    if (typeof text !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${text === null ? "null" : Array.isArray(text) ? "array" : typeof text}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "ReplaceStringTemplateParser.parse",
+            parser: "replaceStringTemplate",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: text === null ? "null" : Array.isArray(text) ? "array" : typeof text
+          }
+        }
       );
-    }, timeLimit);
-  });
-  return Promise.race([asyncPromise, timeoutPromise]).finally(() => {
-    clearTimeout(timeoutHandle);
-  });
-};
-
-// src/utils/modules/guessProviderFromModel.ts
-function isModelKnownOpenAi(payload) {
-  const model = payload.model.toLowerCase();
-  if (model.startsWith("gpt-") || model.startsWith("chatgpt-")) {
-    return true;
-  }
-  if (model === "o1" || model.startsWith("o1-")) {
-    return true;
-  }
-  if (model === "o3-mini") {
-    return true;
-  }
-  return false;
-}
-function isModelKnownAnthropic(payload) {
-  const model = payload.model.toLowerCase();
-  if (model.startsWith("claude-")) {
-    return true;
-  }
-  return false;
-}
-function isModelKnownXai(payload) {
-  const model = payload.model.toLowerCase();
-  if (model.startsWith("grok-")) {
-    return true;
-  }
-  return false;
-}
-function isModelKnownBedrockAnthropic(payload) {
-  const model = payload.model.toLowerCase();
-  if (model.startsWith("anthropic.claude-")) {
-    return true;
-  }
-  return false;
-}
-function guessProviderFromModel(payload) {
-  switch (true) {
-    case isModelKnownOpenAi(payload):
-      return "openai";
-    case isModelKnownXai(payload):
-      return "xai";
-    case isModelKnownBedrockAnthropic(payload):
-      return "bedrock:anthropic";
-    case isModelKnownAnthropic(payload):
-      return "anthropic";
-    default:
-      throw new Error("Unsupported model");
-  }
-}
-
-// src/utils/modules/index.ts
-function registerHelpers(helpers) {
-  hbs.registerHelpers(helpers);
-  hbsAsync.registerHelpers(helpers);
-}
-function registerPartials(partials2) {
-  hbs.registerPartials(partials2);
-  hbsAsync.registerPartials(partials2);
-}
-
-// src/parser/_utils.ts
-var import_jsonschema = require("jsonschema");
-function enforceParserSchema(schema, parsed) {
-  if (!schema || !parsed || typeof parsed !== "object") {
-    return parsed;
-  }
-  return filterObjectOnSchema(schema, parsed);
-}
-function validateParserSchema(schema, parsed) {
-  if (!schema || !parsed || typeof parsed !== "object") {
-    return null;
-  }
-  const validate = (0, import_jsonschema.validate)(parsed, schema);
-  if (validate.errors.length) {
-    return validate.errors;
-  }
-  return null;
-}
-
-// src/parser/parsers/JsonParser.ts
-var JsonParser = class extends BaseParserWithJson {
-  constructor(options = {}) {
-    super("json", options);
-  }
-  parse(text, _attributes) {
-    const parsed = maybeParseJSON(helpJsonMarkup(text));
-    if (this.schema) {
-      const enforce = enforceParserSchema(this.schema, parsed);
-      if (this.validateSchema) {
-        const valid = validateParserSchema(this.schema, enforce);
-        if (valid && valid.length) {
-          throw new LlmExeError(valid[0].message, "parser", {
-            parser: "json",
-            output: parsed,
-            error: valid[0].message
-          });
+    }
+    if (attributes !== void 0 && (attributes === null || typeof attributes !== "object" || Array.isArray(attributes))) {
+      throw new LlmExeError(`Invalid attributes. Expected object.`, {
+        code: "parser.invalid_input",
+        context: {
+          operation: "ReplaceStringTemplateParser.parse",
+          parser: "replaceStringTemplate",
+          reason: "invalid_attributes",
+          expected: "object",
+          received: attributes === null ? "null" : Array.isArray(attributes) ? "array" : typeof attributes
         }
+      });
+    }
+    try {
+      return replaceTemplateString(text, attributes);
+    } catch (cause) {
+      let received = typeof cause;
+      if (cause instanceof Error) {
+        received = cause.name;
       }
-      return enforce;
+      throw new LlmExeError(`Template replacement failed.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "ReplaceStringTemplateParser.parse",
+          parser: "replaceStringTemplate",
+          reason: "template_replacement_failed",
+          inputLength: text.length,
+          received
+        },
+        cause
+      });
     }
-    return parsed;
   }
 };
 
-// src/utils/modules/camelCase.ts
-function camelCase(input) {
-  if (!input) return input;
-  input = input.replace(/[^a-zA-Z0-9_]+/g, " ").trim();
-  const words = input.split(/\s+|_/);
-  return words.map((word, index) => {
-    if (index === 0) {
-      return word.toLowerCase();
-    } else {
-      return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-    }
-  }).join("");
-}
-
-// src/parser/parsers/ListToJsonParser.ts
-var ListToJsonParser = class extends BaseParserWithJson {
-  constructor(options = {}) {
-    super("listToJson", options);
-    __publicField(this, "keyTransform");
-    this.keyTransform = options.keyTransform ?? "camelCase";
+// src/parser/parsers/MarkdownCodeBlocks.ts
+var MarkdownCodeBlocksParser = class extends BaseParser {
+  constructor() {
+    super("markdownCodeBlocks");
   }
-  parse(text) {
-    const lines = text.split("\n");
-    const output = {};
-    lines.forEach((line) => {
-      const colonIndex = line.indexOf(":");
-      if (colonIndex !== -1) {
-        const key = line.slice(0, colonIndex);
-        const value = line.slice(colonIndex + 1).trim();
-        if (value) {
-          const transformedKey = this.keyTransform === "preserve" ? key.trim() : camelCase(key);
-          output[transformedKey] = value;
+  parse(input, _attributes) {
+    if (typeof input !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${input === null ? "null" : Array.isArray(input) ? "array" : typeof input}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "MarkdownCodeBlocksParser.parse",
+            parser: "markdownCodeBlocks",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: input === null ? "null" : Array.isArray(input) ? "array" : typeof input
+          }
         }
-      }
-    });
-    if (this.schema) {
-      const parsed = enforceParserSchema(this.schema, output);
-      if (this?.validateSchema) {
-        const valid = validateParserSchema(this.schema, parsed);
-        if (valid && valid.length) {
-          throw new LlmExeError(valid[0].message, "parser", {
-            parser: "json",
-            output: parsed,
-            error: valid[0].message
-          });
+      );
+    }
+    const out = [];
+    const fenceCount = input.match(/```/g)?.length ?? 0;
+    if (fenceCount % 2 !== 0) {
+      throw new LlmExeError(`Malformed markdown code block.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "MarkdownCodeBlocksParser.parse",
+          parser: "markdownCodeBlocks",
+          reason: "malformed_code_block",
+          inputLength: input.length
         }
+      });
+    }
+    const regex = input.matchAll(new RegExp(/```(\w*)\n([\s\S]*?)```/, "g"));
+    for (const iterator of regex) {
+      if (iterator) {
+        const [_input, language, code] = iterator;
+        out.push({
+          language,
+          code
+        });
       }
-      return parsed;
     }
-    return output;
+    return out;
   }
 };
 
-// src/parser/parsers/ListToKeyValueParser.ts
-var ListToKeyValueParser = class extends BaseParser {
-  constructor(options) {
-    super("listToKeyValue", options);
+// src/parser/parsers/MarkdownCodeBlock.ts
+var MarkdownCodeBlockParser = class extends BaseParser {
+  constructor() {
+    super("markdownCodeBlock");
   }
-  parse(text) {
-    const lines = text.split("\n").map((s) => s.replace("- ", "").replace(/'/g, "'"));
-    let res = [];
-    for (const line of lines) {
-      const [key, value] = line.split(":");
-      if (key && value) {
-        res.push({ key: key?.trim(), value: value?.trim() });
-      }
+  parse(input, _attributes) {
+    if (typeof input !== "string") {
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${input === null ? "null" : Array.isArray(input) ? "array" : typeof input}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "MarkdownCodeBlockParser.parse",
+            parser: "markdownCodeBlock",
+            reason: "invalid_input_type",
+            expected: "string",
+            received: input === null ? "null" : Array.isArray(input) ? "array" : typeof input
+          }
+        }
+      );
     }
-    return res;
+    if (input.trim() === "") {
+      throw new LlmExeError(`No markdown code block found.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "MarkdownCodeBlockParser.parse",
+          parser: "markdownCodeBlock",
+          reason: "empty_input",
+          inputLength: input.length
+        }
+      });
+    }
+    const blocks = new MarkdownCodeBlocksParser().parse(input);
+    if (blocks.length === 0) {
+      throw new LlmExeError(`No markdown code block found.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "MarkdownCodeBlockParser.parse",
+          parser: "markdownCodeBlock",
+          reason: "no_code_block",
+          inputLength: input.length
+        }
+      });
+    }
+    if (blocks.length > 1) {
+      throw new LlmExeError(`Multiple markdown code blocks found.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "MarkdownCodeBlockParser.parse",
+          parser: "markdownCodeBlock",
+          reason: "multiple_code_blocks",
+          inputLength: input.length,
+          matchCount: blocks.length
+        }
+      });
+    }
+    return blocks[0];
   }
 };
 
-// src/parser/parsers/CustomParser.ts
-var CustomParser = class extends BaseParser {
-  /**
-   * Creates a new CustomParser instance.
-   * @param {string} name The name of the parser.
-   * @param {any} parserFn The custom parsing function.
-   */
-  constructor(name, parserFn) {
-    super(name);
-    /**
-     * Custom parsing function.
-     * @type {any}
-     */
-    __publicField(this, "parserFn");
-    this.parserFn = parserFn;
+// src/parser/parsers/StringExtractParser.ts
+var REGEX_METACHAR = /[.*+?^${}()|[\]\\]/g;
+var WORD_CHAR = "[\\p{L}\\p{N}]";
+function escapeRegex(value) {
+  return value.replace(REGEX_METACHAR, "\\$&");
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+var StringExtractParser = class extends BaseParser {
+  constructor(options) {
+    super("stringExtract");
+    __publicField(this, "enum", []);
+    __publicField(this, "ignoreCase");
+    __publicField(this, "match");
+    if (options?.enum) {
+      this.enum.push(...options.enum);
+    }
+    this.ignoreCase = options?.ignoreCase ?? true;
+    this.match = options?.match ?? "word";
   }
   /**
-   * 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.
+   * 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, inputValues) {
-    return this.parserFn.call(this, text, inputValues);
+  parse(text, _attributes) {
+    if (typeof text !== "string") {
+      const received = describeType(text);
+      throw new LlmExeError(
+        `Invalid input. Expected string. Received ${received}.`,
+        {
+          code: "parser.invalid_input",
+          context: {
+            operation: "StringExtractParser.parse",
+            parser: "stringExtract",
+            reason: "invalid_input_type",
+            expected: "string",
+            received
+          }
+        }
+      );
+    }
+    if (this.enum.length === 0) {
+      throw new LlmExeError(`No enum values configured.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "StringExtractParser.parse",
+          parser: "stringExtract",
+          reason: "no_enum_values",
+          expected: "non-empty enum",
+          inputLength: text.length
+        }
+      });
+    }
+    if (text.length === 0) {
+      if (this.enum.includes("")) {
+        return "";
+      }
+      throw new LlmExeError(`No matching enum value found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "StringExtractParser.parse",
+          parser: "stringExtract",
+          reason: "empty_input",
+          expected: this.enum,
+          inputLength: text.length
+        }
+      });
+    }
+    const matches = this.findMatches(text);
+    const uniqueMatches = Array.from(new Set(matches));
+    if (uniqueMatches.length === 1) {
+      return uniqueMatches[0];
+    }
+    if (uniqueMatches.length > 1) {
+      throw new LlmExeError(`Multiple enum values found in input.`, {
+        code: "parser.parse_failed",
+        context: {
+          operation: "StringExtractParser.parse",
+          parser: "stringExtract",
+          reason: "ambiguous_enum_match",
+          expected: this.enum,
+          match: this.match,
+          inputLength: text.length,
+          matchCount: uniqueMatches.length
+        }
+      });
+    }
+    throw new LlmExeError(`No matching enum value found in input.`, {
+      code: "parser.parse_failed",
+      context: {
+        operation: "StringExtractParser.parse",
+        parser: "stringExtract",
+        reason: "no_enum_match",
+        expected: this.enum,
+        match: this.match,
+        inputLength: text.length
+      }
+    });
   }
-};
-
-// src/parser/parsers/ListToArrayParser.ts
-var ListToArrayParser = class extends BaseParser {
-  constructor() {
-    super("listToArray");
+  findMatches(text) {
+    switch (this.match) {
+      case "whole":
+        return this.matchWhole(text);
+      case "substring":
+        return this.matchSubstring(text);
+      case "word":
+      default:
+        return this.matchWord(text);
+    }
+  }
+  matchWhole(text) {
+    const candidate = this.ignoreCase ? text.trim().toLowerCase() : text.trim();
+    return this.enum.filter((option) => {
+      if (option === "") return false;
+      const normalized = this.ignoreCase ? option.toLowerCase() : option;
+      return candidate === normalized;
+    });
   }
-  parse(text) {
-    const lines = text.split("\n").map((s) => s.replace(/^(?:[-*] |\d+\. )/, "").replace(/'/g, "\u2019").trim());
-    return lines;
+  matchSubstring(text) {
+    const haystack = this.ignoreCase ? text.toLowerCase() : text;
+    return this.enum.filter((option) => {
+      if (option === "") return false;
+      const needle = this.ignoreCase ? option.toLowerCase() : option;
+      return haystack.includes(needle);
+    });
+  }
+  matchWord(text) {
+    const flags = this.ignoreCase ? "iu" : "u";
+    return this.enum.filter((option) => {
+      if (option === "") return false;
+      const pattern = new RegExp(
+        `(?<!${WORD_CHAR})${escapeRegex(option)}(?!${WORD_CHAR})`,
+        flags
+      );
+      return pattern.test(text);
+    });
   }
 };
 
-// src/parser/parsers/ReplaceStringTemplateParser.ts
-var ReplaceStringTemplateParser = class extends BaseParser {
-  constructor(options) {
-    super("replaceStringTemplate", options);
+// src/parser/_functions.ts
+function createParser(...args) {
+  const [type, options] = args;
+  switch (type) {
+    case "json":
+      return new JsonParser(options);
+    case "listToJson":
+      return new ListToJsonParser(options);
+    case "stringExtract":
+      return new StringExtractParser(options);
+    case "markdownCodeBlocks":
+      return new MarkdownCodeBlocksParser();
+    case "markdownCodeBlock":
+      return new MarkdownCodeBlockParser();
+    case "listToArray":
+      return new ListToArrayParser();
+    case "listToKeyValue":
+      return new ListToKeyValueParser(options);
+    case "replaceStringTemplate":
+      return new ReplaceStringTemplateParser();
+    case "boolean":
+      return new BooleanParser();
+    case "number":
+      return new NumberParser(options);
+    case "string":
+      return new StringParser();
+    default:
+      throw new LlmExeError(
+        `Invalid parser type: "${type}"`,
+        {
+          code: "parser.invalid_type",
+          context: {
+            operation: "createParser",
+            parser: type,
+            availableParsers: [
+              "json",
+              "string",
+              "boolean",
+              "number",
+              "stringExtract",
+              "listToArray",
+              "listToJson",
+              "listToKeyValue",
+              "replaceStringTemplate",
+              "markdownCodeBlock",
+              "markdownCodeBlocks"
+            ],
+            resolution: "Use a registered parser type, or define a custom parser."
+          }
+        }
+      );
   }
-  parse(text, attributes) {
-    return replaceTemplateString(text, attributes);
+}
+function createCustomParser(name, parserFn) {
+  return new CustomParser(name, parserFn);
+}
+
+// src/utils/index.ts
+var utils_exports = {};
+__export(utils_exports, {
+  LLM_EXE_ERROR_SYMBOL: () => LLM_EXE_ERROR_SYMBOL,
+  LlmExeError: () => LlmExeError,
+  assert: () => assert,
+  asyncCallWithTimeout: () => asyncCallWithTimeout,
+  defineSchema: () => defineSchema,
+  filterObjectOnSchema: () => filterObjectOnSchema,
+  guessProviderFromModel: () => guessProviderFromModel,
+  importHelpers: () => importHelpers,
+  importPartials: () => importPartials,
+  isLlmExeError: () => isLlmExeError,
+  isObjectStringified: () => isObjectStringified,
+  maybeParseJSON: () => maybeParseJSON,
+  maybeStringifyJSON: () => maybeStringifyJSON,
+  registerHelpers: () => registerHelpers,
+  registerPartials: () => registerPartials,
+  replaceTemplateString: () => replaceTemplateString,
+  replaceTemplateStringAsync: () => replaceTemplateStringAsync
+});
+
+// src/utils/modules/assert.ts
+function assert(condition, message) {
+  if (condition === void 0 || condition === null || condition === false) {
+    if (typeof message === "string") {
+      throw new Error(message);
+    } else if (message instanceof Error) {
+      throw message;
+    } else {
+      throw new Error(`Assertion error`);
+    }
   }
-};
+}
 
-// src/parser/singleKeyObjectToString.ts
-function singleKeyObjectToString(input) {
-  try {
-    const parsed = JSON.parse(input);
-    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-      const keys = Object.keys(parsed);
-      if (keys.length === 1) {
-        const value = parsed[keys[0]];
-        if (typeof value === "string") {
-          return value;
-        } else {
-          return input;
-        }
+// src/utils/modules/defineSchema.ts
+var import_json_schema_to_ts = require("json-schema-to-ts");
+function defineSchema(obj) {
+  obj.additionalProperties = false;
+  return (0, import_json_schema_to_ts.asConst)(obj);
+}
+
+// src/utils/modules/handlebars/utils/importPartials.ts
+function importPartials(_partials) {
+  let partials2 = [];
+  if (_partials) {
+    const externalPartialKeys = Object.keys(
+      _partials
+    );
+    for (const externalPartialKey of externalPartialKeys) {
+      if (typeof externalPartialKey === "string") {
+        partials2.push({
+          name: externalPartialKey,
+          template: _partials[externalPartialKey]
+        });
       }
     }
-  } catch {
   }
-  return input;
+  return partials2;
 }
 
-// src/parser/parsers/MarkdownCodeBlocks.ts
-var MarkdownCodeBlocksParser = class extends BaseParser {
-  constructor(options) {
-    super("markdownCodeBlocks", options);
-  }
-  parse(input) {
-    const out = [];
-    if (isObjectStringified(input)) {
-      input = singleKeyObjectToString(input);
-    }
-    const regex = input.matchAll(new RegExp(/```(\w*)\n([\s\S]*?)```/, "g"));
-    for (const iterator of regex) {
-      if (iterator) {
-        const [_input, language, code] = iterator;
-        out.push({
-          language,
-          code
+// src/utils/modules/handlebars/utils/importHelpers.ts
+function importHelpers(_helpers) {
+  let helpers = [];
+  if (_helpers) {
+    const externalHelperKeys = Object.keys(
+      _helpers
+    );
+    for (const externalHelperKey of externalHelperKeys) {
+      if (typeof externalHelperKey === "string") {
+        helpers.push({
+          name: externalHelperKey,
+          handler: _helpers[externalHelperKey]
         });
       }
     }
-    return out;
   }
-};
+  return helpers;
+}
 
-// src/parser/parsers/MarkdownCodeBlock.ts
-var MarkdownCodeBlockParser = class extends BaseParser {
-  constructor(options) {
-    super("markdownCodeBlock", options);
+// src/utils/modules/replaceTemplateStringAsync.ts
+async function replaceTemplateStringAsync(templateString, substitutions = {}, configuration = {
+  helpers: [],
+  partials: []
+}) {
+  if (!templateString) return Promise.resolve(templateString || "");
+  const tempHelpers = [];
+  const tempPartials = [];
+  if (Array.isArray(configuration.helpers)) {
+    hbsAsync.registerHelpers(configuration.helpers);
+    tempHelpers.push(...configuration.helpers.map((a) => a.name));
   }
-  parse(input) {
-    const [block] = new MarkdownCodeBlocksParser().parse(input);
-    if (!block) {
-      return {
-        code: "",
-        language: ""
-      };
-    }
-    return block;
+  if (Array.isArray(configuration.partials)) {
+    hbsAsync.registerPartials(configuration.partials);
+    tempPartials.push(...configuration.partials.map((a) => a.name));
   }
+  const template = hbsAsync.handlebars.compile(templateString);
+  const res = await template(substitutions, {
+    allowedProtoMethods: {
+      substring: true
+    }
+  });
+  tempHelpers.forEach(function(n) {
+    hbsAsync.handlebars.unregisterHelper(n);
+  });
+  tempPartials.forEach(function(n) {
+    hbsAsync.handlebars.unregisterPartial(n);
+  });
+  return res;
+}
+
+// src/utils/modules/asyncCallWithTimeout.ts
+var asyncCallWithTimeout = async (asyncPromise, timeLimit = 1e4) => {
+  let timeoutHandle;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timeoutHandle = setTimeout(() => {
+      return reject(
+        new Error(`LLM call timed out after ${timeLimit}ms`)
+      );
+    }, timeLimit);
+  });
+  return Promise.race([asyncPromise, timeoutPromise]).finally(() => {
+    clearTimeout(timeoutHandle);
+  });
 };
 
-// src/parser/parsers/StringExtractParser.ts
-var StringExtractParser = class extends BaseParser {
-  constructor(options) {
-    super("stringExtract", options);
-    __publicField(this, "enum", []);
-    __publicField(this, "ignoreCase");
-    if (options?.enum) {
-      this.enum.push(...options.enum);
-    }
-    if (options?.ignoreCase) {
-      this.ignoreCase = true;
-    }
+// src/utils/modules/guessProviderFromModel.ts
+function isModelKnownOpenAi(payload) {
+  const model = payload.model.toLowerCase();
+  if (model.startsWith("gpt-") || model.startsWith("chatgpt-")) {
+    return true;
   }
-  parse(text) {
-    assert(
-      typeof text === "string",
-      `Invalid input. Expected string. Received ${typeof text}.`
-    );
-    for (const option of this.enum) {
-      const regex = this.ignoreCase ? new RegExp(option.toLowerCase(), "i") : new RegExp(option);
-      if (regex.test(text)) {
-        return option;
-      }
-    }
-    throw new LlmExeError(
-      `No matching enum value found in input.`,
-      "parser",
-      {
-        parser: "stringExtract",
-        output: text,
-        error: `No matching enum value found in input. Expected one of: ${this.enum.join(", ")}`
-      }
-    );
+  if (model === "o1" || model.startsWith("o1-")) {
+    return true;
   }
-};
-
-// src/parser/_functions.ts
-function createParser(type, options = {}) {
-  switch (type) {
-    case "json":
-      return new JsonParser(options);
-    case "markdownCodeBlocks":
-      return new MarkdownCodeBlocksParser();
-    case "markdownCodeBlock":
-      return new MarkdownCodeBlockParser();
-    case "listToArray":
-      return new ListToArrayParser();
-    case "listToJson":
-      return new ListToJsonParser(options);
-    case "listToKeyValue":
-      return new ListToKeyValueParser();
-    case "replaceStringTemplate":
-      return new ReplaceStringTemplateParser();
-    case "boolean":
-      return new BooleanParser();
-    case "number":
-      return new NumberParser();
-    case "stringExtract":
-      return new StringExtractParser(options);
-    case "string":
-      return new StringParser();
+  if (model === "o3-mini") {
+    return true;
+  }
+  return false;
+}
+function isModelKnownAnthropic(payload) {
+  const model = payload.model.toLowerCase();
+  if (model.startsWith("claude-")) {
+    return true;
+  }
+  return false;
+}
+function isModelKnownXai(payload) {
+  const model = payload.model.toLowerCase();
+  if (model.startsWith("grok-")) {
+    return true;
+  }
+  return false;
+}
+function isModelKnownBedrockAnthropic(payload) {
+  const model = payload.model.toLowerCase();
+  if (model.startsWith("anthropic.claude-")) {
+    return true;
+  }
+  return false;
+}
+function guessProviderFromModel(payload) {
+  switch (true) {
+    case isModelKnownOpenAi(payload):
+      return "openai";
+    case isModelKnownXai(payload):
+      return "xai";
+    case isModelKnownBedrockAnthropic(payload):
+      return "bedrock:anthropic";
+    case isModelKnownAnthropic(payload):
+      return "anthropic";
     default:
-      throw new Error(
-        `Invalid parser type: "${type}". Valid types are: json, string, boolean, number, stringExtract, listToArray, listToJson, listToKeyValue, replaceStringTemplate, markdownCodeBlock, markdownCodeBlocks`
-      );
+      throw new LlmExeError("Unsupported model", {
+        code: "configuration.invalid_provider",
+        context: {
+          operation: "guessProviderFromModel",
+          model: payload.model,
+          // Mirrors the switch above. Keep these in sync when adding a new
+          // isModelKnown* case.
+          availableProviders: [
+            "openai",
+            "xai",
+            "bedrock:anthropic",
+            "anthropic"
+          ],
+          resolution: "Pass a known model prefix (gpt-, chatgpt-, o1, o3-mini, claude-, grok-, anthropic.claude-) or specify the provider explicitly."
+        }
+      });
   }
 }
-function createCustomParser(name, parserFn) {
-  return new CustomParser(name, parserFn);
+
+// src/utils/modules/index.ts
+function registerHelpers(helpers) {
+  hbs.registerHelpers(helpers);
+  hbsAsync.registerHelpers(helpers);
+}
+function registerPartials(partials2) {
+  hbs.registerPartials(partials2);
+  hbsAsync.registerPartials(partials2);
 }
 
 // src/parser/parsers/LlmNativeFunctionParser.ts
 var LlmFunctionParser = class extends BaseParser {
   constructor(options) {
-    super("functionCall", options, "function_call");
+    super("functionCall", "function_call");
     __publicField(this, "parser");
     this.parser = options.parser;
   }
   parse(text, _options) {
     if (typeof text === "string") {
-      return this.parser.parse(text);
+      return this.parser.parse(text, _options);
     }
     const { content } = text;
     const functionUses = content?.filter((a) => a.type === "function_use") || [];
     if (functionUses.length === 0) {
       const [item] = content;
-      return this.parser.parse(item.text);
+      return this.parser.parse(item.text, _options);
     }
     return content;
   }
 };
 var LlmNativeFunctionParser = class extends BaseParser {
   constructor(options) {
-    super("openAiFunction", options, "function_call");
+    super("openAiFunction", "function_call");
     __publicField(this, "parser");
     this.parser = options.parser;
   }
   parse(text, _options) {
+    if (typeof text === "string") {
+      return this.parser.parse(text, _options);
+    }
+    if (typeof text?.text === "string") {
+      return this.parser.parse(text.text, _options);
+    }
     const { content } = text;
     const functionUse = content?.find((a) => a.type === "function_use");
     if (functionUse && "name" in functionUse && "input" in functionUse) {
@@ -1886,7 +3407,10 @@ var LlmNativeFunctionParser = class extends BaseParser {
         arguments: maybeParseJSON(functionUse.input)
       };
     }
-    return this.parser.parse(text?.text ?? text);
+    const textContent = content?.find(
+      (item) => item.type === "text" && typeof item.text === "string"
+    );
+    return this.parser.parse(textContent?.text, _options);
   }
 };
 var OpenAiFunctionParser = LlmNativeFunctionParser;
@@ -1913,17 +3437,29 @@ var LlmExecutor = class extends BaseExecutor {
       this.promptFn = null;
     }
   }
+  /**
+   * 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.
+   */
   async execute(_input, _options) {
-    const input = _input ?? {};
+    if (_input === null || typeof _input === "undefined") {
+      throw new TypeError(
+        `[llm-exe] Executor "${this.name}" received null or undefined as input. execute() expects an object matching the prompt's input type.`
+      );
+    }
     if (this?.parser instanceof JsonParser && this.parser.schema) {
       _options = Object.assign(_options || {}, {
         jsonSchema: this.parser.schema
       });
     }
-    return super.execute(input, _options);
+    return super.execute(_input, _options);
   }
-  async handler(_input, ..._args) {
-    const call = await this.llm.call(_input, ..._args);
+  async handler(_input, _options, _context) {
+    const call = await this.llm.call(_input, _options, _context);
     return call;
   }
   async getHandlerInput(_input) {
@@ -1942,15 +3478,26 @@ var LlmExecutor = class extends BaseExecutor {
         return prompt.format(_input);
       }
     }
-    throw new Error("Missing prompt");
+    throw new LlmExeError("Missing prompt", {
+      code: "executor.missing_prompt",
+      context: {
+        operation: "LlmExecutor.getHandlerInput",
+        executorName: this.name,
+        executorType: this.type,
+        traceId: this.getTraceId() ?? void 0,
+        resolution: "Provide a prompt (or prompt factory) when constructing the LLM executor."
+      }
+    });
   }
-  getHandlerOutput(out, _metadata) {
+  getHandlerOutput(out, _metadata, _options, _context) {
+    const parse = this.parser.parse.bind(this.parser);
+    const parserArg = _context ?? _metadata;
     if (this.parser.target === "function_call") {
       const outToStr = out.getResult();
-      return this.parser.parse(outToStr, _metadata);
+      return parse(outToStr, parserArg);
     } else {
       const outToStr = out.getResultText();
-      return this.parser.parse(outToStr, _metadata);
+      return parse(outToStr, parserArg);
     }
   }
   metadata() {
@@ -2052,7 +3599,17 @@ var CallableExecutor = class {
     } else if (typeof options.handler === "function") {
       this._handler = createCoreExecutor(options.handler);
     } else {
-      throw new Error("Invalid handler");
+      throw new LlmExeError("Invalid handler", {
+        code: "callable.invalid_handler",
+        context: {
+          operation: "CallableExecutor.constructor",
+          functionName: options.name,
+          key: options?.key || options.name,
+          expected: "function or BaseExecutor",
+          received: typeof options.handler,
+          resolution: "Pass a function or a BaseExecutor instance as the handler."
+        }
+      });
     }
   }
   async execute(input) {
@@ -2070,7 +3627,16 @@ var CallableExecutor = class {
       }
       return { result: true, attributes: {} };
     } catch (error) {
-      return { result: false, attributes: { error: error.message } };
+      const wrapped = error instanceof LlmExeError ? error : new LlmExeError(error?.message ?? String(error), {
+        code: "callable.validation_failed",
+        context: {
+          operation: "CallableExecutor.validateInput",
+          functionName: this.name,
+          key: this.key
+        },
+        cause: error
+      });
+      return { result: false, attributes: { error: wrapped.message } };
     }
   }
   visibilityHandler(input, attributes) {
@@ -2107,10 +3673,19 @@ var UseExecutorsBase = class {
   async callFunction(name, input) {
     try {
       const handler = this.getFunction(name);
-      assert(
-        handler,
-        `[invalid handler] The handler (${name}) does not exist.`
-      );
+      if (!handler) {
+        throw new LlmExeError(
+          `[invalid handler] The handler (${name}) does not exist.`,
+          {
+            code: "callable.handler_not_found",
+            context: {
+              operation: "UseExecutorsBase.callFunction",
+              functionName: name,
+              availableFunctions: this.handlers.map((h) => h.name)
+            }
+          }
+        );
+      }
       const result = await handler.execute(ensureInputIsObject(input));
       return result;
     } catch (error) {
@@ -2120,10 +3695,19 @@ var UseExecutorsBase = class {
   async validateFunctionInput(name, input) {
     try {
       const handler = this.getFunction(name);
-      assert(
-        handler,
-        `[invalid handler] The handler (${name}) does not exist.`
-      );
+      if (!handler) {
+        throw new LlmExeError(
+          `[invalid handler] The handler (${name}) does not exist.`,
+          {
+            code: "callable.handler_not_found",
+            context: {
+              operation: "UseExecutorsBase.validateFunctionInput",
+              functionName: name,
+              availableFunctions: this.handlers.map((h) => h.name)
+            }
+          }
+        );
+      }
       const result = await handler.validateInput(
         ensureInputIsObject(input)
       );
@@ -2138,18 +3722,59 @@ var UseExecutorsBase = class {
 function createCallableExecutor(options) {
   return new CallableExecutor(options);
 }
-var UseExecutors = class extends UseExecutorsBase {
-  constructor(handlers) {
-    super(handlers);
-  }
-};
-function useExecutors(executors) {
-  return new UseExecutors(
-    executors.map((e) => {
-      if (e instanceof CallableExecutor) return e;
-      return createCallableExecutor(e);
-    })
-  );
+var UseExecutors = class extends UseExecutorsBase {
+  constructor(handlers) {
+    super(handlers);
+  }
+};
+function useExecutors(executors) {
+  return new UseExecutors(
+    executors.map((e) => {
+      if (e instanceof CallableExecutor) return e;
+      return createCallableExecutor(e);
+    })
+  );
+}
+
+// src/utils/guards.ts
+var guards_exports = {};
+__export(guards_exports, {
+  hasFunctionCall: () => hasFunctionCall,
+  hasToolCall: () => hasToolCall,
+  isAssistantMessage: () => isAssistantMessage,
+  isFunctionCall: () => isFunctionCall,
+  isOutputResult: () => isOutputResult,
+  isOutputResultContentText: () => isOutputResultContentText,
+  isSystemMessage: () => isSystemMessage,
+  isToolCall: () => isToolCall,
+  isUserMessage: () => isUserMessage
+});
+function isOutputResult(obj) {
+  return !!(obj && typeof obj === "object" && "id" in obj && "stopReason" in obj && "content" in obj && Array.isArray(obj.content));
+}
+function isOutputResultContentText(obj) {
+  return !!(obj && typeof obj === "object" && "text" in obj && "type" in obj && obj.type === "text" && typeof obj.text === "string");
+}
+function isFunctionCall(result) {
+  return !!(result && typeof result === "object" && "functionId" in result && "type" in result && result.type === "function_use");
+}
+function isToolCall(result) {
+  return isFunctionCall(result);
+}
+function hasFunctionCall(results) {
+  return !!(results && Array.isArray(results) && results.some(isToolCall));
+}
+function hasToolCall(results) {
+  return hasFunctionCall(results);
+}
+function isUserMessage(message) {
+  return message.role === "user";
+}
+function isAssistantMessage(message) {
+  return message.role === "assistant" || message.role === "model";
+}
+function isSystemMessage(message) {
+  return message.role === "system";
 }
 
 // src/utils/modules/deepClone.ts
@@ -2194,13 +3819,38 @@ function withDefaultModel(obj1, model) {
   return copy;
 }
 
-// src/utils/modules/getEnvironmentVariable.ts
-function getEnvironmentVariable(name) {
-  if (typeof process === "object" && process?.env) {
-    return process.env[name];
-  } else {
-    return void 0;
+// src/llm/_utils.deprecationWarning.ts
+var warned = /* @__PURE__ */ new Set();
+function emitDeprecationWarning(config, context) {
+  if (!config.deprecated) return;
+  if (typeof process !== "object" || typeof process?.emitWarning !== "function") {
+    return;
   }
+  const { shorthand, message } = config.deprecated;
+  if (warned.has(shorthand)) return;
+  warned.add(shorthand);
+  const detail = JSON.stringify({
+    shorthand,
+    model: config.options?.model?.default,
+    provider: config.provider,
+    executorName: context?.executorName,
+    traceId: context?.traceId
+  });
+  process.emitWarning(message, {
+    type: "DeprecationWarning",
+    code: "LLM_EXE_DEPRECATED",
+    detail
+  });
+}
+function deprecateShorthand(shorthand, args) {
+  const entry = {
+    ...args.config,
+    deprecated: Object.freeze({
+      shorthand,
+      message: args.message
+    })
+  };
+  return { [shorthand]: entry };
 }
 
 // src/llm/output/_util.ts
@@ -2482,7 +4132,10 @@ var openai = {
   "openai.gpt-4o": withDefaultModel(openAiChatV1, "gpt-4o"),
   "openai.gpt-4o-mini": withDefaultModel(openAiChatV1, "gpt-4o-mini"),
   // Deprecated
-  "openai.o4-mini": withDefaultModel(openAiChatV1, "o4-mini")
+  ...deprecateShorthand("openai.o4-mini", {
+    config: withDefaultModel(openAiChatV1, "o4-mini"),
+    message: 'Shorthand "openai.o4-mini" is deprecated and may be removed in a future release.'
+  })
 };
 
 // src/llm/config/anthropic/promptSanitizeMessageCallback.ts
@@ -2851,38 +4504,38 @@ var anthropic = {
     "claude-sonnet-4-5"
   ),
   // Deprecated
-  "anthropic.claude-opus-4-6": withDefaultModel(
-    anthropicChatV1,
-    "claude-opus-4-6"
-  ),
-  "anthropic.claude-opus-4-1": withDefaultModel(
-    anthropicChatV1,
-    "claude-opus-4-1-20250805"
-  ),
-  "anthropic.claude-sonnet-4": withDefaultModel(
-    anthropicChatV1,
-    "claude-sonnet-4-0"
-  ),
-  "anthropic.claude-opus-4": withDefaultModel(
-    anthropicChatV1,
-    "claude-opus-4-0"
-  ),
-  "anthropic.claude-3-7-sonnet": withDefaultModel(
-    anthropicChatV1,
-    "claude-3-7-sonnet-20250219"
-  ),
-  "anthropic.claude-3-5-sonnet": withDefaultModel(
-    anthropicChatV1,
-    "claude-3-5-sonnet-latest"
-  ),
-  "anthropic.claude-3-5-haiku": withDefaultModel(
-    anthropicChatV1,
-    "claude-3-5-haiku-latest"
-  ),
-  "anthropic.claude-3-opus": withDefaultModel(
-    anthropicChatV1,
-    "claude-3-opus-20240229"
-  )
+  ...deprecateShorthand("anthropic.claude-opus-4-6", {
+    config: withDefaultModel(anthropicChatV1, "claude-opus-4-6"),
+    message: 'Shorthand "anthropic.claude-opus-4-6" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-opus-4-1", {
+    config: withDefaultModel(anthropicChatV1, "claude-opus-4-1-20250805"),
+    message: 'Shorthand "anthropic.claude-opus-4-1" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-sonnet-4", {
+    config: withDefaultModel(anthropicChatV1, "claude-sonnet-4-0"),
+    message: 'Shorthand "anthropic.claude-sonnet-4" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-opus-4", {
+    config: withDefaultModel(anthropicChatV1, "claude-opus-4-0"),
+    message: 'Shorthand "anthropic.claude-opus-4" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-3-7-sonnet", {
+    config: withDefaultModel(anthropicChatV1, "claude-3-7-sonnet-20250219"),
+    message: 'Shorthand "anthropic.claude-3-7-sonnet" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-3-5-sonnet", {
+    config: withDefaultModel(anthropicChatV1, "claude-3-5-sonnet-latest"),
+    message: 'Shorthand "anthropic.claude-3-5-sonnet" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-3-5-haiku", {
+    config: withDefaultModel(anthropicChatV1, "claude-3-5-haiku-latest"),
+    message: 'Shorthand "anthropic.claude-3-5-haiku" is deprecated and may be removed in a future release.'
+  }),
+  ...deprecateShorthand("anthropic.claude-3-opus", {
+    config: withDefaultModel(anthropicChatV1, "claude-3-opus-20240229"),
+    message: 'Shorthand "anthropic.claude-3-opus" is deprecated and may be removed in a future release.'
+  })
 };
 
 // src/llm/config/x/index.ts
@@ -2901,20 +4554,41 @@ var xai = {
   "xai.grok-4": withDefaultModel(xaiChatV1, "grok-4"),
   "xai.grok-4-fast": withDefaultModel(xaiChatV1, "grok-4-fast-non-reasoning"),
   "xai.grok-4-1-fast": withDefaultModel(xaiChatV1, "grok-4-1-fast-non-reasoning"),
-  "xai.grok-4.3": withDefaultModel(xaiChatV1, "grok-4.3")
+  "xai.grok-4.3": withDefaultModel(xaiChatV1, "grok-4.3"),
+  "xai.grok-4.20": withDefaultModel(xaiChatV1, "grok-4.20-0309-non-reasoning"),
+  "xai.grok-4.20-reasoning": withDefaultModel(
+    xaiChatV1,
+    "grok-4.20-0309-reasoning"
+  )
 };
 
 // src/llm/output/_utils/combineJsonl.ts
 function combineJsonl(jsonl) {
-  const lines = jsonl.trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => {
+  const rawLines = jsonl.trim().split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  const lines = rawLines.map((line, idx) => {
     try {
       return JSON.parse(line);
     } catch (e) {
-      throw new Error(`Invalid JSON: ${line}`);
+      throw new LlmExeError(`Invalid JSON: ${line}`, {
+        code: "llm.invalid_jsonl_response",
+        context: {
+          operation: "combineJsonl",
+          lineNumber: idx + 1,
+          lineExcerpt: line
+        },
+        cause: e
+      });
     }
   });
   if (lines.length === 0) {
-    throw new Error("No JSON lines provided.");
+    throw new LlmExeError("No JSON lines provided.", {
+      code: "llm.invalid_jsonl_response",
+      context: {
+        operation: "combineJsonl",
+        received: 0,
+        expected: "at least one JSONL line"
+      }
+    });
   }
   lines.sort(
     (a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime()
@@ -2923,7 +4597,14 @@ function combineJsonl(jsonl) {
   combinedContent = combinedContent.replace(/\\u003c/g, "<").replace(/\\u003e/g, ">");
   const finalLine = lines.find((line) => line.done === true);
   if (!finalLine) {
-    throw new Error("No line found where done = true.");
+    throw new LlmExeError("No line found where done = true.", {
+      code: "llm.invalid_jsonl_response",
+      context: {
+        operation: "combineJsonl",
+        lineCount: lines.length,
+        expected: "a final line with done = true"
+      }
+    });
   }
   const result = {
     model: finalLine.model,
@@ -3012,7 +4693,10 @@ var ollama = {
   "ollama.gemma3": withDefaultModel(ollamaChatV1, "gemma3"),
   "ollama.mistral": withDefaultModel(ollamaChatV1, "mistral"),
   "ollama.qwen2.5": withDefaultModel(ollamaChatV1, "qwen2.5"),
-  "ollama.qwen3": withDefaultModel(ollamaChatV1, "qwen3")
+  "ollama.qwen3": withDefaultModel(ollamaChatV1, "qwen3"),
+  "ollama.qwen3.5": withDefaultModel(ollamaChatV1, "qwen3.5"),
+  "ollama.gemma4": withDefaultModel(ollamaChatV1, "gemma4"),
+  "ollama.gpt-oss": withDefaultModel(ollamaChatV1, "gpt-oss")
 };
 
 // src/llm/config/google/promptSanitizeMessageCallback.ts
@@ -3085,7 +4769,16 @@ function googleGeminiPromptSanitize(_messages, _inputBodyObj, _outputObj) {
   }
   if (Array.isArray(_messages)) {
     if (_messages.length === 0) {
-      throw new Error("Empty messages array");
+      throw new LlmExeError("Empty messages array", {
+        code: "prompt.invalid_messages",
+        context: {
+          operation: "googleGeminiPromptSanitize",
+          provider: "google",
+          received: "empty array",
+          expected: "a non-empty messages array",
+          resolution: "Pass at least one message to the prompt."
+        }
+      });
     }
     if (_messages.length === 1 && _messages[0].role === "system") {
       return [{ role: "user", parts: [{ text: _messages[0].content }] }];
@@ -3113,7 +4806,16 @@ function googleGeminiPromptSanitize(_messages, _inputBodyObj, _outputObj) {
     const result = _messages.map(googleGeminiPromptMessageCallback);
     return mergeConsecutiveSameRole2(result);
   }
-  throw new Error("Invalid messages format");
+  throw new LlmExeError("Invalid messages format", {
+    code: "prompt.invalid_messages",
+    context: {
+      operation: "googleGeminiPromptSanitize",
+      provider: "google",
+      received: typeof _messages,
+      expected: "string or messages array",
+      resolution: "Pass a string or an array of chat messages."
+    }
+  });
 }
 
 // src/llm/output/google.gemini/formatResult.ts
@@ -3229,23 +4931,27 @@ var googleGeminiChatV1 = {
 };
 var google = {
   "google.chat.v1": googleGeminiChatV1,
-  "google.gemini-2.5-flash": withDefaultModel(
-    googleGeminiChatV1,
-    "gemini-2.5-flash"
-  ),
-  "google.gemini-2.5-flash-lite": withDefaultModel(
-    googleGeminiChatV1,
-    "gemini-2.5-flash-lite"
-  ),
-  "google.gemini-2.5-pro": withDefaultModel(
-    googleGeminiChatV1,
-    "gemini-2.5-pro"
-  ),
   "google.gemini-3.1-flash-lite": withDefaultModel(
     googleGeminiChatV1,
     "gemini-3.1-flash-lite"
   ),
+  "google.gemini-3.5-flash": withDefaultModel(
+    googleGeminiChatV1,
+    "gemini-3.5-flash"
+  ),
   // Deprecated
+  ...deprecateShorthand("google.gemini-2.5-flash", {
+    config: withDefaultModel(googleGeminiChatV1, "gemini-2.5-flash"),
+    message: 'Model "google.gemini-2.5-flash" is deprecated and will shut down on 2026-06-17.'
+  }),
+  ...deprecateShorthand("google.gemini-2.5-flash-lite", {
+    config: withDefaultModel(googleGeminiChatV1, "gemini-2.5-flash-lite"),
+    message: 'Model "google.gemini-2.5-flash-lite" is deprecated and will shut down on 2026-07-22.'
+  }),
+  ...deprecateShorthand("google.gemini-2.5-pro", {
+    config: withDefaultModel(googleGeminiChatV1, "gemini-2.5-pro"),
+    message: 'Model "google.gemini-2.5-pro" is deprecated and will shut down on 2026-06-17.'
+  }),
   "google.gemini-2.0-flash": withDefaultModel(
     googleGeminiChatV1,
     "gemini-2.0-flash"
@@ -3286,81 +4992,28 @@ var configs = {
 };
 function getLlmConfig(provider) {
   if (!provider) {
-    throw new LlmExeError(`Missing provider`, "unknown", {
-      error: "Missing provider",
-      resolution: "Provide a valid provider"
+    throw new LlmExeError(`Missing provider`, {
+      code: "configuration.missing_provider",
+      context: {
+        operation: "getLlmConfig",
+        availableProviders: Object.keys(configs),
+        resolution: "Provide a valid provider"
+      }
     });
   }
   const pick2 = configs[provider];
   if (pick2) {
     return pick2;
   }
-  throw new LlmExeError(`Invalid provider: ${provider}`, "unknown", {
-    provider,
-    error: `Invalid provider: ${provider}`,
-    resolution: "Provide a valid provider"
-  });
-}
-
-// src/utils/modules/maskApiKeysInDebug.ts
-function maskApiKeys(log) {
-  return log.replace(
-    /\b(Bearer\s+[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+|Bearer\s+[A-Za-z0-9\-_]{20,}|sk-[A-Za-z0-9]{20,}|AKIA[A-Z0-9]{16}|[A-Za-z0-9]{32,})\b/g,
-    (match) => {
-      if (match.length <= 8) return match;
-      const prefix = match.substring(0, 4);
-      const suffix = match.substring(match.length - 4);
-      const maskLength = match.length - 8;
-      return `${prefix}${"*".repeat(maskLength)}${suffix}`;
-    }
-  );
-}
-
-// src/utils/modules/debug.ts
-function debug(...args) {
-  const debugValue = getEnvironmentVariable("LLM_EXE_DEBUG");
-  const logs = [];
-  for (const arg of args) {
-    if (arg && typeof arg === "object") {
-      if (arg instanceof Error) {
-      } else if (arg instanceof Array) {
-        logs.push(arg.map((item) => JSON.stringify(item, null, 2)));
-      } else if (arg instanceof Map) {
-        logs.push(
-          Array.from(arg.entries()).map(
-            ([key, value]) => `${key}: ${JSON.stringify(value, null, 2)}`
-          )
-        );
-      } else if (arg instanceof Set) {
-        logs.push(Array.from(arg).map((item) => JSON.stringify(item, null, 2)));
-      } else if (arg instanceof Date) {
-        logs.push(arg.toISOString());
-      } else if (arg instanceof RegExp) {
-        logs.push(arg.toString());
-      } else {
-        try {
-          let shouldMask = false;
-          if (arg.headers && arg.headers.Authorization) {
-            shouldMask = true;
-          }
-          let str = JSON.stringify(arg, null, 2);
-          if (shouldMask) {
-            str = maskApiKeys(str);
-          }
-          logs.push(str);
-        } catch (error) {
-          console.error("Error parsing object:", error);
-        }
-      }
-    } else if (typeof arg === "string") {
-      logs.push(arg);
-    } else {
-      logs.push(arg);
+  throw new LlmExeError(`Invalid provider: ${provider}`, {
+    code: "configuration.invalid_provider",
+    context: {
+      operation: "getLlmConfig",
+      provider,
+      availableProviders: Object.keys(configs),
+      resolution: "Provide a valid provider"
     }
-  }
-  if (typeof debugValue === "string" && debugValue !== "" && debugValue.toLowerCase() !== "undefined" && debugValue.toLowerCase() !== "null") {
-    console.debug(...logs);
-  }
+  });
 }
 
 // src/utils/modules/isValidUrl.ts
@@ -3378,41 +5031,93 @@ async function apiRequest(url, options) {
   const finalOptions = {
     ...options
   };
+  debug(url, finalOptions);
+  if (!url || !isValidUrl(url)) {
+    const safeUrl = safeRequestUrl(url);
+    throw new LlmExeError("Invalid URL", {
+      code: "request.invalid_url",
+      context: {
+        operation: "apiRequest",
+        url: safeUrl,
+        expected: "valid URL"
+      }
+    });
+  }
+  let response;
   try {
-    debug(url, finalOptions);
-    if (!url || !isValidUrl(url)) {
-      throw new Error("Invalid URL");
-    }
-    const response = await fetch(url, finalOptions);
-    if (!response.ok) {
-      let message = `HTTP error. Status: ${response.status}. Error Message: ${response?.statusText || "Unknown error."}`;
-      try {
-        const text = await response.text();
-        if (text) {
-          let detail = text;
-          try {
-            const body = JSON.parse(text);
-            detail = body?.error?.message || body?.error || body?.message || text;
-            if (typeof detail !== "string") detail = JSON.stringify(detail);
-          } catch {
-          }
-          message = `HTTP error. Status Code: ${response.status}. Error Message: ${detail}`;
+    response = await fetch(url, finalOptions);
+  } catch (fetchError) {
+    const innerMsg = fetchError instanceof Error ? fetchError.message : "Error";
+    const safeUrl = safeRequestUrl(url);
+    throw new LlmExeError(`Request to ${safeUrl} failed: ${innerMsg}`, {
+      code: "request.http_error",
+      context: {
+        operation: "apiRequest",
+        url: safeUrl
+      },
+      cause: fetchError
+    });
+  }
+  if (!response.ok) {
+    let bodyText = "";
+    let bodyJson = void 0;
+    let bodyReadError = void 0;
+    try {
+      bodyText = await response.text();
+      if (bodyText) {
+        try {
+          bodyJson = JSON.parse(bodyText);
+        } catch {
         }
-      } catch {
       }
-      throw new Error(message);
-    }
-    const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      const responseData = await response.json();
-      return responseData;
+    } catch (e) {
+      bodyReadError = e;
+    }
+    let message;
+    if (bodyText) {
+      let detail = bodyText;
+      if (bodyJson) {
+        const b = bodyJson;
+        detail = b.error?.message || b.error || b.message || bodyText;
+        if (typeof detail !== "string") detail = JSON.stringify(detail);
+      }
+      const safeDetail = safeProviderString(detail) ?? "";
+      message = `HTTP error. Status Code: ${response.status}. Error Message: ${safeDetail}`;
     } else {
-      const responseData = await response.text();
-      return responseData;
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Error";
-    throw new Error(`Request to ${url} failed: ${message}`);
+      message = `HTTP error. Status: ${response.status}. Error Message: ${response.statusText || "Unknown error."}`;
+    }
+    const safeUrl = safeRequestUrl(url);
+    const wrappedMessage = `Request to ${safeUrl} failed: ${message}`;
+    const safeHeaders = safeResponseHeaders(response.headers);
+    const providerError = parseProviderErrorGeneric({
+      status: response.status,
+      statusText: response.statusText,
+      headers: safeHeaders,
+      bodyJson,
+      bodyText
+    });
+    throw new LlmExeError(wrappedMessage, {
+      code: "request.http_error",
+      context: {
+        operation: "apiRequest",
+        url: safeUrl,
+        status: response.status,
+        statusText: response.statusText,
+        responseHeaders: safeHeaders,
+        providerError,
+        providerErrorBody: bodyJson !== void 0 ? safeProviderErrorBody(bodyJson) : void 0,
+        providerErrorRaw: bodyText ? safeProviderErrorBody(bodyText) : void 0
+      },
+      cause: bodyReadError
+    });
+  }
+  const contentType = response.headers.get("content-type");
+  if (contentType?.includes("application/json")) {
+    const responseData = await response.json();
+    return responseData;
+  } else {
+    const responseData = await response.text();
+    return responseData;
   }
 }
 
@@ -3533,7 +5238,19 @@ async function runWithTemporaryEnv(env, handler) {
 // src/utils/modules/getAwsAuthorizationHeaders.ts
 async function getAwsAuthorizationHeaders(req, props) {
   if (!props.url || !props.regionName) {
-    throw new Error("URL and region name are required for AWS authorization");
+    throw new LlmExeError(
+      "URL and region name are required for AWS authorization",
+      {
+        code: "auth.aws_signing_input_missing",
+        context: {
+          operation: "getAwsAuthorizationHeaders",
+          url: props.url,
+          regionName: props.regionName,
+          expected: "both url and regionName to be set",
+          resolution: "Set AWS_REGION as an environment variable (or pass regionName) and provide a valid request URL."
+        }
+      }
+    );
   }
   const providerChain = (0, import_credential_providers.fromNodeProviderChain)();
   const credentials = await runWithTemporaryEnv(
@@ -3572,6 +5289,12 @@ async function getAwsAuthorizationHeaders(req, props) {
 }
 
 // src/llm/_utils.parseHeaders.ts
+var REPLACED_HEADERS_EXCERPT_MAX = 500;
+function safeReplacedHeaders(value) {
+  if (!value) return "";
+  const truncated = value.length > REPLACED_HEADERS_EXCERPT_MAX ? value.slice(0, REPLACED_HEADERS_EXCERPT_MAX) + "\u2026(truncated)" : value;
+  return redactSecrets(truncated);
+}
 async function parseHeaders(config, replacements, payload) {
   const replace = replaceTemplateStringSimple(config.headers, replacements);
   let parsedHeaders = {};
@@ -3583,8 +5306,21 @@ async function parseHeaders(config, replacements, payload) {
       }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      throw new Error(
-        `Failed to parse headers configuration: ${errorMessage}. Headers template: "${config.headers}". After replacement: "${replace}"`
+      const safeReplaced = safeReplacedHeaders(replace);
+      throw new LlmExeError(
+        `Failed to parse headers configuration: ${errorMessage}. Headers template: "${config.headers}". After replacement: "${safeReplaced}"`,
+        {
+          code: "configuration.invalid_headers",
+          context: {
+            operation: "parseHeaders",
+            provider: config.provider,
+            key: config.key,
+            headerTemplate: config.headers,
+            replacedHeadersExcerpt: safeReplaced,
+            resolution: "Fix the headers template so replacement produces a JSON object."
+          },
+          cause: error
+        }
       );
     }
   }
@@ -3738,29 +5474,47 @@ async function useLlm_call(state, messages, _options) {
     headers: {},
     body
   });
-  const response = config.provider === "openai.chat-mock" ? {
-    id: "0123-45-6789",
-    model: "model",
-    created: (/* @__PURE__ */ new Date()).getTime(),
-    usage: { completion_tokens: 0, prompt_tokens: 0, total_tokens: 0 },
-    choices: [
-      {
-        message: {
-          role: "assistant",
-          content: `Hello world from LLM! The input was ${JSON.stringify(
-            messages
-          )}`
-        }
-      }
-    ]
-  } : await apiRequest(url, {
-    method: config.method,
-    body,
-    headers
-  });
   const { transformResponse = OutputDefault } = config;
-  const normalized = transformResponse(response, config);
-  return BaseLlmOutput(normalized);
+  if (config.provider === "openai.chat-mock") {
+    const mockResponse = {
+      id: "0123-45-6789",
+      model: "model",
+      created: (/* @__PURE__ */ new Date()).getTime(),
+      usage: { completion_tokens: 0, prompt_tokens: 0, total_tokens: 0 },
+      choices: [
+        {
+          message: {
+            role: "assistant",
+            content: `Hello world from LLM! The input was ${JSON.stringify(messages)}`
+          }
+        }
+      ]
+    };
+    return BaseLlmOutput(transformResponse(mockResponse, config));
+  }
+  try {
+    const response = await apiRequest(url, {
+      method: config.method,
+      body,
+      headers
+    });
+    return BaseLlmOutput(transformResponse(response, config));
+  } catch (e) {
+    if (!isLlmExeError(e, "request.http_error")) throw e;
+    const ctx = e.context ?? {};
+    const status = typeof ctx.status === "number" ? ctx.status : void 0;
+    const code = status ? statusToLlmProviderCode(status) : "llm.provider_http_error";
+    throw new LlmExeError(e.message, {
+      code,
+      context: {
+        ...ctx,
+        operation: "useLlm_call",
+        provider: state.provider,
+        model: state.model
+      },
+      cause: e
+    });
+  }
 }
 
 // src/llm/_utils.stateFromOptions.ts
@@ -3784,7 +5538,16 @@ function stateFromOptions(options, config) {
     if (Array.isArray(thisConfig?.required)) {
       const [required, message = `Error: [${key}] is required`] = thisConfig.required;
       if (required && typeof value === "undefined") {
-        throw new Error(message);
+        throw new LlmExeError(message, {
+          code: "configuration.missing_option",
+          context: {
+            operation: "stateFromOptions",
+            provider: config.provider,
+            key: config.key,
+            option: String(key),
+            resolution: `Provide a value for "${String(key)}" via options or environment.`
+          }
+        });
       }
     }
   }
@@ -3831,8 +5594,12 @@ function apiRequestWrapper(config, options, handler, doNotRetryErrorMessages = [
   const numOfAttempts = options.numOfAttempts || 2;
   const jitter = options.jitter || "none";
   let traceId = options?.traceId || null;
-  async function call(messages, options2) {
+  async function call(messages, options2, context) {
     try {
+      emitDeprecationWarning(config, {
+        executorName: context?.executor?.name,
+        traceId: context?.traceId ?? getTraceId() ?? void 0
+      });
       metrics.total_calls++;
       const result = await (0, import_exponential_backoff.backOff)(
         () => asyncCallWithTimeout(
@@ -4010,8 +5777,19 @@ var embeddingConfigs = {
           const isV3 = /embed-(english|multilingual)-v3/.test(model);
           if (isV3) {
             if (value === 1024) return void 0;
-            throw new Error(
-              `Cohere Embed v3 only supports 1024-dimensional output (model: "${model}", requested: ${value}). Use cohere.embed-v4:0 for configurable dimensions.`
+            throw new LlmExeError(
+              `Cohere Embed v3 only supports 1024-dimensional output (model: "${model}", requested: ${value}). Use cohere.embed-v4:0 for configurable dimensions.`,
+              {
+                code: "embedding.unsupported_dimensions",
+                context: {
+                  operation: "embedding.dimensionTransform",
+                  provider: "amazon:cohere.embedding",
+                  model,
+                  dimensions: value,
+                  expected: 1024,
+                  resolution: "Use cohere.embed-v4:0 for configurable dimensions."
+                }
+              }
             );
           }
           return value;
@@ -4022,13 +5800,28 @@ var embeddingConfigs = {
 };
 function getEmbeddingConfig(provider) {
   if (!provider) {
-    throw new Error(`Missing provider`);
+    throw new LlmExeError(`Missing provider`, {
+      code: "embedding.missing_provider",
+      context: {
+        operation: "getEmbeddingConfig",
+        availableProviders: Object.keys(embeddingConfigs),
+        resolution: "Provide a valid embedding provider key."
+      }
+    });
   }
   const pick2 = embeddingConfigs[provider];
   if (pick2) {
     return pick2;
   }
-  throw new Error(`Invalid provider: ${provider}`);
+  throw new LlmExeError(`Invalid provider: ${provider}`, {
+    code: "embedding.invalid_provider",
+    context: {
+      operation: "getEmbeddingConfig",
+      provider,
+      availableProviders: Object.keys(embeddingConfigs),
+      resolution: "Provide a valid embedding provider key."
+    }
+  });
 }
 
 // src/embedding/output/BaseEmbeddingOutput.ts
@@ -4132,7 +5925,16 @@ function getEmbeddingOutputParser(config, response) {
     case "amazon:cohere.embedding.v1":
       return CohereBedrockEmbedding(response, config);
     default:
-      throw new Error("Unsupported provider");
+      throw new LlmExeError("Unsupported provider", {
+        code: "embedding.invalid_response_shape",
+        context: {
+          operation: "getEmbeddingOutputParser",
+          provider: config.key,
+          model: config.model,
+          availableProviders: Object.keys(embeddingConfigs),
+          resolution: "Use a supported embedding provider key."
+        }
+      });
   }
 }
 
@@ -4152,12 +5954,29 @@ async function createEmbedding_call(state, _input, _options) {
     headers: {},
     body
   });
-  const request = await apiRequest(url, {
-    method: config.method,
-    body,
-    headers
-  });
-  return getEmbeddingOutputParser(state, request);
+  try {
+    const request = await apiRequest(url, {
+      method: config.method,
+      body,
+      headers
+    });
+    return getEmbeddingOutputParser(state, request);
+  } catch (e) {
+    if (!isLlmExeError(e, "request.http_error")) throw e;
+    const ctx = e.context ?? {};
+    const status = typeof ctx.status === "number" ? ctx.status : void 0;
+    const code = status ? statusToEmbeddingProviderCode(status) : "embedding.provider_http_error";
+    throw new LlmExeError(e.message, {
+      code,
+      context: {
+        ...ctx,
+        operation: "createEmbedding_call",
+        provider: state.provider,
+        model: state.model
+      },
+      cause: e
+    });
+  }
 }
 
 // src/embedding/embedding.ts
@@ -4166,6 +5985,245 @@ function createEmbedding(provider, options) {
   return apiRequestWrapper(config, options, createEmbedding_call);
 }
 
+// src/prompt/_templateValidation.ts
+var BUILT_IN_HELPERS = /* @__PURE__ */ new Set([
+  "if",
+  "unless",
+  "each",
+  "with",
+  "lookup",
+  "log",
+  "blockHelperMissing",
+  "helperMissing"
+]);
+function isKnownHelper(name, customHelpers) {
+  if (BUILT_IN_HELPERS.has(name)) return true;
+  if (customHelpers && Object.prototype.hasOwnProperty.call(customHelpers, name)) {
+    return true;
+  }
+  return false;
+}
+function pathRootSegment(path) {
+  if (path.depth > 0) return null;
+  if (path.data) return null;
+  if (path.parts.length === 0) return null;
+  return path.parts[0];
+}
+function pathToCollectedString(path) {
+  const parts = path.parts.slice();
+  return parts.join(".");
+}
+function collectFromPath(path, source, locals, options, references, seen) {
+  const root = pathRootSegment(path);
+  if (!root) return;
+  if (locals.has(root)) return;
+  const collected = pathToCollectedString(path);
+  const dedupKey = `${source}::${collected}`;
+  if (seen.has(dedupKey)) return;
+  seen.add(dedupKey);
+  references.push({
+    path: collected,
+    source,
+    location: options.location
+  });
+}
+function collectFromExpression(expr, source, locals, options, references, missingHelpers, seen) {
+  if (expr.type === "PathExpression") {
+    collectFromPath(expr, source, locals, options, references, seen);
+    return;
+  }
+  if (expr.type === "SubExpression") {
+    walkCall(
+      expr.path,
+      expr.params,
+      expr.hash,
+      locals,
+      options,
+      references,
+      missingHelpers,
+      seen
+    );
+    return;
+  }
+}
+function walkHash(hash, locals, options, references, missingHelpers, seen) {
+  if (!hash || !hash.pairs) return;
+  for (const pair of hash.pairs) {
+    collectFromExpression(
+      pair.value,
+      "hash",
+      locals,
+      options,
+      references,
+      missingHelpers,
+      seen
+    );
+  }
+}
+function walkCall(path, params, hash, locals, options, references, missingHelpers, seen) {
+  const root = pathRootSegment(path);
+  const hasArgs = params.length > 0 || hash !== void 0 && hash.pairs.length > 0;
+  if (hasArgs) {
+    if (root) {
+      if (!isKnownHelper(path.original, options.helpers) && !locals.has(root)) {
+        missingHelpers.add(path.original);
+      }
+    }
+    for (const param of params) {
+      collectFromExpression(
+        param,
+        "helper-param",
+        locals,
+        options,
+        references,
+        missingHelpers,
+        seen
+      );
+    }
+    walkHash(hash, locals, options, references, missingHelpers, seen);
+    return;
+  }
+  if (root && isKnownHelper(path.original, options.helpers)) {
+    return;
+  }
+  collectFromPath(path, "mustache", locals, options, references, seen);
+}
+function walkProgram(program, parentLocals, options, references, missingHelpers, seen) {
+  if (!program) return;
+  const locals = new Set(parentLocals);
+  if (program.blockParams) {
+    for (const bp of program.blockParams) {
+      locals.add(bp);
+    }
+  }
+  for (const node of program.body) {
+    walkStatement(node, locals, options, references, missingHelpers, seen);
+  }
+}
+function walkStatement(node, locals, options, references, missingHelpers, seen) {
+  switch (node.type) {
+    case "MustacheStatement": {
+      const m = node;
+      if (m.path.type === "PathExpression") {
+        walkCall(
+          m.path,
+          m.params,
+          m.hash,
+          locals,
+          options,
+          references,
+          missingHelpers,
+          seen
+        );
+      }
+      return;
+    }
+    case "BlockStatement": {
+      const b = node;
+      const root = pathRootSegment(b.path);
+      if (root && !isKnownHelper(b.path.original, options.helpers) && !locals.has(root)) {
+        missingHelpers.add(b.path.original);
+      }
+      for (const param of b.params) {
+        collectFromExpression(
+          param,
+          "block-param",
+          locals,
+          options,
+          references,
+          missingHelpers,
+          seen
+        );
+      }
+      walkHash(b.hash, locals, options, references, missingHelpers, seen);
+      const isEach = b.path.original === "each";
+      const hasBlockParams = b.program?.blockParams && b.program.blockParams.length > 0 || b.inverse?.blockParams && b.inverse.blockParams.length > 0;
+      if (isEach && !hasBlockParams) {
+        return;
+      }
+      walkProgram(b.program, locals, options, references, missingHelpers, seen);
+      walkProgram(b.inverse, locals, options, references, missingHelpers, seen);
+      return;
+    }
+    case "PartialStatement": {
+      const p = node;
+      for (const param of p.params) {
+        collectFromExpression(
+          param,
+          "helper-param",
+          locals,
+          options,
+          references,
+          missingHelpers,
+          seen
+        );
+      }
+      walkHash(p.hash, locals, options, references, missingHelpers, seen);
+      return;
+    }
+  }
+}
+function collectAll(template, options) {
+  const references = [];
+  const missingHelpers = /* @__PURE__ */ new Set();
+  let ast;
+  try {
+    ast = hbs.handlebars.parse(template);
+  } catch {
+    return { references, missingHelpers: [] };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  walkProgram(ast, /* @__PURE__ */ new Set(), options, references, missingHelpers, seen);
+  return { references, missingHelpers: Array.from(missingHelpers) };
+}
+function hasInputPath(input, path) {
+  if (!input || typeof input !== "object") return false;
+  let current = input;
+  for (const part of path.split(".")) {
+    if (!current || typeof current !== "object") return false;
+    if (!Object.prototype.hasOwnProperty.call(current, part)) return false;
+    current = current[part];
+  }
+  return current !== void 0;
+}
+function validateTemplateInputReferences(template, input, options = {}) {
+  const { references, missingHelpers } = collectAll(template, options);
+  const missingVariables = [];
+  const seenMissing = /* @__PURE__ */ new Set();
+  for (const ref of references) {
+    if (hasInputPath(input, ref.path)) continue;
+    const key = ref.path;
+    if (seenMissing.has(key)) continue;
+    seenMissing.add(key);
+    missingVariables.push(ref);
+  }
+  return { references, missingVariables, missingHelpers };
+}
+
+// src/prompt/errors.ts
+function buildMessage(context) {
+  const { missingVariables, missingHelpers } = context;
+  const vars = missingVariables.length ? `Missing variables: ${formatErrorList(missingVariables)}.` : "";
+  const helpers = missingHelpers.length ? `Missing helpers: ${formatErrorList(missingHelpers)}.` : "";
+  if (vars && helpers) {
+    return `Prompt template has unresolved references. ${vars} ${helpers}`;
+  }
+  if (vars) {
+    return `Prompt template references variables not provided. ${vars}`;
+  }
+  return `Prompt template references helpers not registered. ${helpers}`;
+}
+function missingTemplateReferencesError(context) {
+  return createLlmExeError(
+    {
+      code: "prompt.missing_template_variable",
+      message: buildMessage,
+      resolution: "Pass every variable referenced by the prompt template, or register any custom helpers used."
+    },
+    context
+  );
+}
+
 // src/prompt/_base.ts
 var BasePrompt = class {
   /**
@@ -4177,6 +6235,7 @@ var BasePrompt = class {
     __publicField(this, "messages", []);
     __publicField(this, "partials", []);
     __publicField(this, "helpers", []);
+    __publicField(this, "validateInput", false);
     __publicField(this, "replaceTemplateString", replaceTemplateString);
     __publicField(this, "replaceTemplateStringAsync", replaceTemplateStringAsync);
     __publicField(this, "filters", {
@@ -4202,6 +6261,9 @@ var BasePrompt = class {
       if (options.replaceTemplateString) {
         this.replaceTemplateString = options.replaceTemplateString;
       }
+      if (options.validateInput !== void 0) {
+        this.validateInput = options.validateInput;
+      }
     }
   }
   /**
@@ -4253,6 +6315,40 @@ var BasePrompt = class {
     this.helpers.push(...helpers);
     return 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.
+   */
+  getTemplateContents() {
+    return this.messages.map((message, index) => {
+      if (!message.content || Array.isArray(message.content)) {
+        return null;
+      }
+      return {
+        content: message.content,
+        location: `messages[${index}].content`
+      };
+    }).filter(
+      (entry) => entry !== null
+    );
+  }
+  preflightValidate(values) {
+    if (this.validateInput === false || !this.validateInput) {
+      return;
+    }
+    try {
+      this.validate(values);
+    } catch (error) {
+      if (this.validateInput === "warn" && isLlmExeError(error, "prompt.missing_template_variable")) {
+        if (typeof process === "object" && typeof process?.emitWarning === "function") {
+          process.emitWarning(error);
+        }
+        return;
+      }
+      throw error;
+    }
+  }
   /**
    * format description
    * @param values The message content
@@ -4260,6 +6356,7 @@ var BasePrompt = class {
    * @return returns messages formatted with template replacement
    */
   format(values, separator = "\n\n") {
+    this.preflightValidate(values);
     const replacements = this.getReplacements(values);
     const messages = this.messages.map((message) => {
       return message.content && !Array.isArray(message.content) ? this.replaceTemplateString(
@@ -4280,6 +6377,7 @@ var BasePrompt = class {
    * @return returns messages formatted with template replacement
    */
   async formatAsync(values, separator = "\n\n") {
+    this.preflightValidate(values);
     const replacements = this.getReplacements(values);
     const _messages = await Promise.all(this.messages.map((message) => {
       return message.content && !Array.isArray(message.content) ? this.replaceTemplateStringAsync(
@@ -4303,8 +6401,18 @@ var BasePrompt = class {
   }
   getReplacements(values) {
     if (values === void 0 || values === null) {
-      throw new Error(
-        "format() requires an input object. Did you forget to pass arguments?"
+      throw new LlmExeError(
+        "format() requires an input object. Did you forget to pass arguments?",
+        {
+          code: "prompt.missing_input",
+          context: {
+            operation: "BasePrompt.getReplacements",
+            promptType: this.type,
+            expected: "object",
+            received: values === null ? "null" : "undefined",
+            resolution: "Pass an object of template values to format()."
+          }
+        }
       );
     }
     const { input = "", ...restOfValues } = values;
@@ -4319,11 +6427,52 @@ var BasePrompt = class {
     return replacements;
   }
   /**
-   * 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() {
-    return this.messages.length > 0;
+  validate(input) {
+    const allMissingVariables = [];
+    const allMissingHelpers = /* @__PURE__ */ new Set();
+    const registeredHelpers = this.helpers.reduce(
+      (acc, h) => {
+        acc[h.name] = h.handler;
+        return acc;
+      },
+      {}
+    );
+    const knownHelpers = {
+      ...hbs.handlebars.helpers,
+      ...registeredHelpers
+    };
+    for (const template of this.getTemplateContents()) {
+      const result = validateTemplateInputReferences(template.content, input, {
+        helpers: knownHelpers,
+        location: template.location
+      });
+      allMissingVariables.push(...result.missingVariables);
+      for (const helper of result.missingHelpers) {
+        allMissingHelpers.add(helper);
+      }
+    }
+    if (allMissingVariables.length === 0 && allMissingHelpers.size === 0) {
+      return;
+    }
+    const dedupedVariables = Array.from(
+      new Set(allMissingVariables.map((r) => r.path))
+    );
+    throw missingTemplateReferencesError({
+      operation: "Prompt.validate",
+      promptType: this.type,
+      missingVariables: dedupedVariables,
+      missingHelpers: Array.from(allMissingHelpers)
+    });
   }
 };
 
@@ -4625,6 +6774,7 @@ var ChatPrompt = class extends BasePrompt {
    * @return formatted prompt.
    */
   format(values) {
+    this.preflightValidate(values);
     const messagesOut = [];
     const replacements = this.getReplacements(values);
     const safeToParseTemplate = ["assistant", "system"];
@@ -4750,6 +6900,7 @@ var ChatPrompt = class extends BasePrompt {
    * @return formatted prompt.
    */
   async formatAsync(values) {
+    this.preflightValidate(values);
     const messagesOut = [];
     const replacements = this.getReplacements(values);
     const safeToParseTemplate = ["assistant", "system"];
@@ -5052,16 +7203,26 @@ var Dialogue = class extends BaseStateItem {
   }
   setFunctionCallMessage(input) {
     if (!input || typeof input !== "object") {
-      throw new LlmExeError(`Invalid arguments`, "state", {
-        error: `Invalid arguments: input must be an object`,
-        module: "dialogue"
+      throw new LlmExeError(`Invalid arguments`, {
+        code: "state.invalid_arguments",
+        context: {
+          operation: "Dialogue.setFunctionCallMessage",
+          module: "dialogue",
+          expected: "object",
+          received: typeof input
+        }
       });
     }
     if ("function_call" in input) {
       if (!input.function_call || typeof input.function_call !== "object") {
-        throw new LlmExeError(`Invalid arguments`, "state", {
-          error: `Invalid arguments: input must be an object`,
-          module: "dialogue"
+        throw new LlmExeError(`Invalid arguments`, {
+          code: "state.invalid_arguments",
+          context: {
+            operation: "Dialogue.setFunctionCallMessage",
+            module: "dialogue",
+            expected: "object",
+            received: typeof input.function_call
+          }
         });
       }
       this.value.push({
@@ -5297,6 +7458,8 @@ function createStateItem(name, defaultValue) {
   CustomParser,
   DefaultState,
   DefaultStateItem,
+  LLM_EXE_ERROR_SYMBOL,
+  LlmExeError,
   LlmExecutorOpenAiFunctions,
   LlmExecutorWithFunctions,
   LlmNativeFunctionParser,
@@ -5317,6 +7480,7 @@ function createStateItem(name, defaultValue) {
   createStateItem,
   defineSchema,
   guards,
+  isLlmExeError,
   registerHelpers,
   registerPartials,
   useExecutors,