@langchain/core 0.3.79 → 0.3.80

package/dist/load/index.cjs

@@ -1,4 +1,39 @@
 "use strict";
+/**
+ * Load LangChain objects from JSON strings or objects.
+ *
+ * ## How it works
+ *
+ * Each `Serializable` LangChain object has a unique identifier (its "class path"),
+ * which is a list of strings representing the module path and class name. For example:
+ *
+ * - `AIMessage` -> `["langchain_core", "messages", "ai", "AIMessage"]`
+ * - `ChatPromptTemplate` -> `["langchain_core", "prompts", "chat", "ChatPromptTemplate"]`
+ *
+ * When deserializing, the class path is validated against supported namespaces.
+ *
+ * ## Security model
+ *
+ * The `secretsFromEnv` parameter controls whether secrets can be loaded from environment
+ * variables:
+ *
+ * - `false` (default): Secrets must be provided in `secretsMap`. If a secret is not
+ *   found, `null` is returned instead of loading from environment variables.
+ * - `true`: If a secret is not found in `secretsMap`, it will be loaded from
+ *   environment variables. Use this only in trusted environments.
+ *
+ * ### Injection protection (escape-based)
+ *
+ * During serialization, plain objects that contain an `'lc'` key are escaped by wrapping
+ * them: `{"__lc_escaped__": {...}}`. During deserialization, escaped objects are unwrapped
+ * and returned as plain objects, NOT instantiated as LC objects.
+ *
+ * This is an allowlist approach: only objects explicitly produced by
+ * `Serializable.toJSON()` (which are NOT escaped) are treated as LC objects;
+ * everything else is user data.
+ *
+ * @module
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -39,6 +74,12 @@ const import_constants_js_1 = require("./import_constants.cjs");
 const coreImportMap = __importStar(require("./import_map.cjs"));
 const map_keys_js_1 = require("./map_keys.cjs");
 const env_js_1 = require("../utils/env.cjs");
+const validation_js_1 = require("./validation.cjs");
+/**
+ * Default maximum recursion depth for deserialization.
+ * This provides protection against DoS attacks via deeply nested structures.
+ */
+const DEFAULT_MAX_DEPTH = 50;
 function combineAliasesAndInvert(constructor) {
     const aliases = {};
     for (
@@ -51,53 +92,74 @@ function combineAliasesAndInvert(constructor) {
         return acc;
     }, {});
 }
+/**
+ * Recursively revive a value, handling escape markers and LC objects.
+ *
+ * This function handles:
+ * 1. Escaped dicts - unwrapped and returned as plain objects
+ * 2. LC secret objects - resolved from secretsMap or env
+ * 3. LC constructor objects - instantiated
+ * 4. Regular objects/arrays - recursed into
+ */
 async function reviver(value) {
-    const { optionalImportsMap = {}, optionalImportEntrypoints = [], importMap = {}, secretsMap = {}, path = ["$"], } = this;
+    const { optionalImportsMap, optionalImportEntrypoints, importMap, secretsMap, secretsFromEnv, path, depth, maxDepth, } = this;
     const pathStr = path.join(".");
-    if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        value.lc === 1 &&
-        value.type === "secret") {
-        const serialized = value;
+    // Check recursion depth to prevent DoS via deeply nested structures
+    if (depth > maxDepth) {
+        throw new Error(`Maximum recursion depth (${maxDepth}) exceeded during deserialization. ` +
+            `This may indicate a malicious payload or you may need to increase maxDepth.`);
+    }
+    // If not an object, return as-is
+    if (typeof value !== "object" || value == null) {
+        return value;
+    }
+    // Handle arrays - recurse into elements
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((v, i) => reviver.call({ ...this, path: [...path, `${i}`], depth: depth + 1 }, v)));
+    }
+    // It's an object - check for escape marker FIRST
+    const record = value;
+    if ((0, validation_js_1.isEscapedObject)(record)) {
+        // This is an escaped user object - unwrap and return as-is (no LC processing)
+        return (0, validation_js_1.unescapeValue)(record);
+    }
+    // Check for LC secret object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        record.lc === 1 &&
+        record.type === "secret") {
+        const serialized = record;
         const [key] = serialized.id;
         if (key in secretsMap) {
             return secretsMap[key];
         }
-        else {
+        else if (secretsFromEnv) {
             const secretValueInEnv = (0, env_js_1.getEnvironmentVariable)(key);
             if (secretValueInEnv) {
                 return secretValueInEnv;
             }
-            else {
-                throw new Error(`Missing key "${key}" for ${pathStr} in load(secretsMap={})`);
-            }
         }
+        throw new Error(`Missing secret "${key}" at ${pathStr}`);
     }
-    else if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        value.lc === 1 &&
-        value.type === "not_implemented") {
-        const serialized = value;
+    // Check for LC not_implemented object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        record.lc === 1 &&
+        record.type === "not_implemented") {
+        const serialized = record;
         const str = JSON.stringify(serialized);
         throw new Error(`Trying to load an object that doesn't implement serialization: ${pathStr} -> ${str}`);
     }
-    else if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        "kwargs" in value &&
-        value.lc === 1) {
-        const serialized = value;
+    // Check for LC constructor object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        "kwargs" in record &&
+        record.lc === 1 &&
+        record.type === "constructor") {
+        const serialized = record;
         const str = JSON.stringify(serialized);
         const [name, ...namespaceReverse] = serialized.id.slice().reverse();
         const namespace = namespaceReverse.reverse();
@@ -164,35 +226,60 @@ async function reviver(value) {
             throw new Error(`Invalid identifer: ${pathStr} -> ${str}`);
         }
         // Recurse on the arguments, which may be serialized objects themselves
-        const kwargs = await reviver.call({ ...this, path: [...path, "kwargs"] }, serialized.kwargs);
+        const kwargs = await reviver.call({ ...this, path: [...path, "kwargs"], depth: depth + 1 }, serialized.kwargs);
         // Construct the object
-        if (serialized.type === "constructor") {
-            // eslint-disable-next-line new-cap, @typescript-eslint/no-explicit-any
-            const instance = new builder((0, map_keys_js_1.mapKeys)(kwargs, map_keys_js_1.keyFromJson, combineAliasesAndInvert(builder)));
-            // Minification in severless/edge runtimes will mange the
-            // name of classes presented in traces. As the names in import map
-            // are present as-is even with minification, use these names instead
-            Object.defineProperty(instance.constructor, "name", { value: name });
-            return instance;
-        }
-        else {
-            throw new Error(`Invalid type: ${pathStr} -> ${str}`);
-        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const instance = new builder((0, map_keys_js_1.mapKeys)(kwargs, map_keys_js_1.keyFromJson, combineAliasesAndInvert(builder)));
+        // Minification in severless/edge runtimes will mange the
+        // name of classes presented in traces. As the names in import map
+        // are present as-is even with minification, use these names instead
+        Object.defineProperty(instance.constructor, "name", { value: name });
+        return instance;
     }
-    else if (typeof value === "object" && value !== null) {
-        if (Array.isArray(value)) {
-            return Promise.all(value.map((v, i) => reviver.call({ ...this, path: [...path, `${i}`] }, v)));
-        }
-        else {
-            return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, value]) => [
-                key,
-                await reviver.call({ ...this, path: [...path, key] }, value),
-            ])));
-        }
+    // Regular object - recurse into values
+    const result = {};
+    for (const [key, val] of Object.entries(record)) {
+        result[key] = await reviver.call({ ...this, path: [...path, key], depth: depth + 1 }, val);
     }
-    return value;
+    return result;
 }
-async function load(text, mappings) {
+/**
+ * Load a LangChain object from a JSON string.
+ *
+ * @param text - The JSON string to parse and load.
+ * @param options - Options for loading.
+ * @returns The loaded LangChain object.
+ *
+ * @example
+ * ```typescript
+ * import { load } from "@langchain/core/load";
+ * import { AIMessage } from "@langchain/core/messages";
+ *
+ * // Basic usage - secrets must be provided explicitly
+ * const msg = await load<AIMessage>(jsonString);
+ *
+ * // With secrets from a map
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsMap: { OPENAI_API_KEY: "sk-..." }
+ * });
+ *
+ * // Allow loading secrets from environment (use with caution)
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsFromEnv: true
+ * });
+ * ```
+ */
+async function load(text, options) {
     const json = JSON.parse(text);
-    return reviver.call({ ...mappings }, json);
+    const context = {
+        optionalImportsMap: options?.optionalImportsMap ?? {},
+        optionalImportEntrypoints: options?.optionalImportEntrypoints ?? [],
+        secretsMap: options?.secretsMap ?? {},
+        secretsFromEnv: options?.secretsFromEnv ?? false,
+        importMap: options?.importMap ?? {},
+        path: ["$"],
+        depth: 0,
+        maxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,
+    };
+    return reviver.call(context, json);
 }

package/dist/load/index.d.ts

@@ -1,7 +1,151 @@
+/**
+ * Load LangChain objects from JSON strings or objects.
+ *
+ * ## How it works
+ *
+ * Each `Serializable` LangChain object has a unique identifier (its "class path"),
+ * which is a list of strings representing the module path and class name. For example:
+ *
+ * - `AIMessage` -> `["langchain_core", "messages", "ai", "AIMessage"]`
+ * - `ChatPromptTemplate` -> `["langchain_core", "prompts", "chat", "ChatPromptTemplate"]`
+ *
+ * When deserializing, the class path is validated against supported namespaces.
+ *
+ * ## Security model
+ *
+ * The `secretsFromEnv` parameter controls whether secrets can be loaded from environment
+ * variables:
+ *
+ * - `false` (default): Secrets must be provided in `secretsMap`. If a secret is not
+ *   found, `null` is returned instead of loading from environment variables.
+ * - `true`: If a secret is not found in `secretsMap`, it will be loaded from
+ *   environment variables. Use this only in trusted environments.
+ *
+ * ### Injection protection (escape-based)
+ *
+ * During serialization, plain objects that contain an `'lc'` key are escaped by wrapping
+ * them: `{"__lc_escaped__": {...}}`. During deserialization, escaped objects are unwrapped
+ * and returned as plain objects, NOT instantiated as LC objects.
+ *
+ * This is an allowlist approach: only objects explicitly produced by
+ * `Serializable.toJSON()` (which are NOT escaped) are treated as LC objects;
+ * everything else is user data.
+ *
+ * @module
+ */
 import type { OptionalImportMap, SecretMap } from "./import_type.js";
-export declare function load<T>(text: string, mappings?: {
+/**
+ * Options for loading serialized LangChain objects.
+ *
+ * @remarks
+ * **Security considerations:**
+ *
+ * Deserialization can instantiate arbitrary classes from the allowed namespaces.
+ * When loading untrusted data, be aware that:
+ *
+ * 1. **`secretsFromEnv`**: Defaults to `false`. Setting to `true` allows the
+ *    deserializer to read environment variables, which could leak secrets if
+ *    the serialized data contains malicious secret references.
+ *
+ * 2. **`importMap` / `optionalImportsMap`**: These allow extending which classes
+ *    can be instantiated. Never populate these from user input. Only include
+ *    modules you explicitly trust.
+ *
+ * 3. **Class instantiation**: Allowed classes will have their constructors called
+ *    with the deserialized kwargs. If a class performs side effects in its
+ *    constructor (network calls, file I/O, etc.), those will execute.
+ */
+export interface LoadOptions {
+    /**
+     * A map of secrets to load. Keys are secret identifiers, values are the secret values.
+     *
+     * If a secret is not found in this map and `secretsFromEnv` is `false`, an error is
+     * thrown. If `secretsFromEnv` is `true`, the secret will be loaded from environment
+     * variables (if not found there either, an error is thrown).
+     */
     secretsMap?: SecretMap;
+    /**
+     * Whether to load secrets from environment variables when not found in `secretsMap`.
+     *
+     * @default false
+     *
+     * @remarks
+     * **Security warning:** Setting this to `true` allows the deserializer to read
+     * environment variables, which could be a security risk if the serialized data
+     * is not trusted. Only set this to `true` when deserializing data from trusted
+     * sources (e.g., your own database, not user input).
+     */
+    secretsFromEnv?: boolean;
+    /**
+     * A map of optional imports. Keys are namespace paths (e.g., "langchain_community/llms"),
+     * values are the imported modules.
+     *
+     * @remarks
+     * **Security warning:** This extends which classes can be instantiated during
+     * deserialization. Never populate this map with values derived from user input.
+     * Only include modules that you explicitly trust and have reviewed.
+     *
+     * Classes in these modules can be instantiated with attacker-controlled kwargs
+     * if the serialized data is untrusted.
+     */
     optionalImportsMap?: OptionalImportMap;
+    /**
+     * Additional optional import entrypoints to allow beyond the defaults.
+     *
+     * @remarks
+     * **Security warning:** This extends which namespace paths are considered valid
+     * for deserialization. Never populate this array with values derived from user
+     * input. Each entrypoint you add expands the attack surface for deserialization.
+     */
     optionalImportEntrypoints?: string[];
+    /**
+     * Additional import map for the "langchain" namespace.
+     *
+     * @remarks
+     * **Security warning:** This extends which classes can be instantiated during
+     * deserialization. Never populate this map with values derived from user input.
+     * Only include modules that you explicitly trust and have reviewed.
+     *
+     * Any class exposed through this map can be instantiated with attacker-controlled
+     * kwargs if the serialized data is untrusted.
+     */
     importMap?: Record<string, unknown>;
-}): Promise<T>;
+    /**
+     * Maximum recursion depth allowed during deserialization.
+     *
+     * @default 50
+     *
+     * @remarks
+     * This limit protects against denial-of-service attacks using deeply nested
+     * JSON structures that could cause stack overflow. If your legitimate data
+     * requires deeper nesting, you can increase this limit.
+     */
+    maxDepth?: number;
+}
+/**
+ * Load a LangChain object from a JSON string.
+ *
+ * @param text - The JSON string to parse and load.
+ * @param options - Options for loading.
+ * @returns The loaded LangChain object.
+ *
+ * @example
+ * ```typescript
+ * import { load } from "@langchain/core/load";
+ * import { AIMessage } from "@langchain/core/messages";
+ *
+ * // Basic usage - secrets must be provided explicitly
+ * const msg = await load<AIMessage>(jsonString);
+ *
+ * // With secrets from a map
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsMap: { OPENAI_API_KEY: "sk-..." }
+ * });
+ *
+ * // Allow loading secrets from environment (use with caution)
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsFromEnv: true
+ * });
+ * ```
+ */
+export declare function load<T>(text: string, options?: LoadOptions): Promise<T>;

package/dist/load/index.js

@@ -1,8 +1,49 @@
+/**
+ * Load LangChain objects from JSON strings or objects.
+ *
+ * ## How it works
+ *
+ * Each `Serializable` LangChain object has a unique identifier (its "class path"),
+ * which is a list of strings representing the module path and class name. For example:
+ *
+ * - `AIMessage` -> `["langchain_core", "messages", "ai", "AIMessage"]`
+ * - `ChatPromptTemplate` -> `["langchain_core", "prompts", "chat", "ChatPromptTemplate"]`
+ *
+ * When deserializing, the class path is validated against supported namespaces.
+ *
+ * ## Security model
+ *
+ * The `secretsFromEnv` parameter controls whether secrets can be loaded from environment
+ * variables:
+ *
+ * - `false` (default): Secrets must be provided in `secretsMap`. If a secret is not
+ *   found, `null` is returned instead of loading from environment variables.
+ * - `true`: If a secret is not found in `secretsMap`, it will be loaded from
+ *   environment variables. Use this only in trusted environments.
+ *
+ * ### Injection protection (escape-based)
+ *
+ * During serialization, plain objects that contain an `'lc'` key are escaped by wrapping
+ * them: `{"__lc_escaped__": {...}}`. During deserialization, escaped objects are unwrapped
+ * and returned as plain objects, NOT instantiated as LC objects.
+ *
+ * This is an allowlist approach: only objects explicitly produced by
+ * `Serializable.toJSON()` (which are NOT escaped) are treated as LC objects;
+ * everything else is user data.
+ *
+ * @module
+ */
 import { get_lc_unique_name, } from "./serializable.js";
 import { optionalImportEntrypoints as defaultOptionalImportEntrypoints } from "./import_constants.js";
 import * as coreImportMap from "./import_map.js";
 import { keyFromJson, mapKeys } from "./map_keys.js";
 import { getEnvironmentVariable } from "../utils/env.js";
+import { isEscapedObject, unescapeValue } from "./validation.js";
+/**
+ * Default maximum recursion depth for deserialization.
+ * This provides protection against DoS attacks via deeply nested structures.
+ */
+const DEFAULT_MAX_DEPTH = 50;
 function combineAliasesAndInvert(constructor) {
     const aliases = {};
     for (
@@ -15,53 +56,74 @@ function combineAliasesAndInvert(constructor) {
         return acc;
     }, {});
 }
+/**
+ * Recursively revive a value, handling escape markers and LC objects.
+ *
+ * This function handles:
+ * 1. Escaped dicts - unwrapped and returned as plain objects
+ * 2. LC secret objects - resolved from secretsMap or env
+ * 3. LC constructor objects - instantiated
+ * 4. Regular objects/arrays - recursed into
+ */
 async function reviver(value) {
-    const { optionalImportsMap = {}, optionalImportEntrypoints = [], importMap = {}, secretsMap = {}, path = ["$"], } = this;
+    const { optionalImportsMap, optionalImportEntrypoints, importMap, secretsMap, secretsFromEnv, path, depth, maxDepth, } = this;
     const pathStr = path.join(".");
-    if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        value.lc === 1 &&
-        value.type === "secret") {
-        const serialized = value;
+    // Check recursion depth to prevent DoS via deeply nested structures
+    if (depth > maxDepth) {
+        throw new Error(`Maximum recursion depth (${maxDepth}) exceeded during deserialization. ` +
+            `This may indicate a malicious payload or you may need to increase maxDepth.`);
+    }
+    // If not an object, return as-is
+    if (typeof value !== "object" || value == null) {
+        return value;
+    }
+    // Handle arrays - recurse into elements
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((v, i) => reviver.call({ ...this, path: [...path, `${i}`], depth: depth + 1 }, v)));
+    }
+    // It's an object - check for escape marker FIRST
+    const record = value;
+    if (isEscapedObject(record)) {
+        // This is an escaped user object - unwrap and return as-is (no LC processing)
+        return unescapeValue(record);
+    }
+    // Check for LC secret object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        record.lc === 1 &&
+        record.type === "secret") {
+        const serialized = record;
         const [key] = serialized.id;
         if (key in secretsMap) {
             return secretsMap[key];
         }
-        else {
+        else if (secretsFromEnv) {
             const secretValueInEnv = getEnvironmentVariable(key);
             if (secretValueInEnv) {
                 return secretValueInEnv;
             }
-            else {
-                throw new Error(`Missing key "${key}" for ${pathStr} in load(secretsMap={})`);
-            }
         }
+        throw new Error(`Missing secret "${key}" at ${pathStr}`);
     }
-    else if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        value.lc === 1 &&
-        value.type === "not_implemented") {
-        const serialized = value;
+    // Check for LC not_implemented object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        record.lc === 1 &&
+        record.type === "not_implemented") {
+        const serialized = record;
         const str = JSON.stringify(serialized);
         throw new Error(`Trying to load an object that doesn't implement serialization: ${pathStr} -> ${str}`);
     }
-    else if (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        "lc" in value &&
-        "type" in value &&
-        "id" in value &&
-        "kwargs" in value &&
-        value.lc === 1) {
-        const serialized = value;
+    // Check for LC constructor object
+    if ("lc" in record &&
+        "type" in record &&
+        "id" in record &&
+        "kwargs" in record &&
+        record.lc === 1 &&
+        record.type === "constructor") {
+        const serialized = record;
         const str = JSON.stringify(serialized);
         const [name, ...namespaceReverse] = serialized.id.slice().reverse();
         const namespace = namespaceReverse.reverse();
@@ -128,35 +190,60 @@ async function reviver(value) {
             throw new Error(`Invalid identifer: ${pathStr} -> ${str}`);
         }
         // Recurse on the arguments, which may be serialized objects themselves
-        const kwargs = await reviver.call({ ...this, path: [...path, "kwargs"] }, serialized.kwargs);
+        const kwargs = await reviver.call({ ...this, path: [...path, "kwargs"], depth: depth + 1 }, serialized.kwargs);
         // Construct the object
-        if (serialized.type === "constructor") {
-            // eslint-disable-next-line new-cap, @typescript-eslint/no-explicit-any
-            const instance = new builder(mapKeys(kwargs, keyFromJson, combineAliasesAndInvert(builder)));
-            // Minification in severless/edge runtimes will mange the
-            // name of classes presented in traces. As the names in import map
-            // are present as-is even with minification, use these names instead
-            Object.defineProperty(instance.constructor, "name", { value: name });
-            return instance;
-        }
-        else {
-            throw new Error(`Invalid type: ${pathStr} -> ${str}`);
-        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const instance = new builder(mapKeys(kwargs, keyFromJson, combineAliasesAndInvert(builder)));
+        // Minification in severless/edge runtimes will mange the
+        // name of classes presented in traces. As the names in import map
+        // are present as-is even with minification, use these names instead
+        Object.defineProperty(instance.constructor, "name", { value: name });
+        return instance;
     }
-    else if (typeof value === "object" && value !== null) {
-        if (Array.isArray(value)) {
-            return Promise.all(value.map((v, i) => reviver.call({ ...this, path: [...path, `${i}`] }, v)));
-        }
-        else {
-            return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, value]) => [
-                key,
-                await reviver.call({ ...this, path: [...path, key] }, value),
-            ])));
-        }
+    // Regular object - recurse into values
+    const result = {};
+    for (const [key, val] of Object.entries(record)) {
+        result[key] = await reviver.call({ ...this, path: [...path, key], depth: depth + 1 }, val);
     }
-    return value;
+    return result;
 }
-export async function load(text, mappings) {
+/**
+ * Load a LangChain object from a JSON string.
+ *
+ * @param text - The JSON string to parse and load.
+ * @param options - Options for loading.
+ * @returns The loaded LangChain object.
+ *
+ * @example
+ * ```typescript
+ * import { load } from "@langchain/core/load";
+ * import { AIMessage } from "@langchain/core/messages";
+ *
+ * // Basic usage - secrets must be provided explicitly
+ * const msg = await load<AIMessage>(jsonString);
+ *
+ * // With secrets from a map
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsMap: { OPENAI_API_KEY: "sk-..." }
+ * });
+ *
+ * // Allow loading secrets from environment (use with caution)
+ * const msg = await load<AIMessage>(jsonString, {
+ *   secretsFromEnv: true
+ * });
+ * ```
+ */
+export async function load(text, options) {
     const json = JSON.parse(text);
-    return reviver.call({ ...mappings }, json);
+    const context = {
+        optionalImportsMap: options?.optionalImportsMap ?? {},
+        optionalImportEntrypoints: options?.optionalImportEntrypoints ?? [],
+        secretsMap: options?.secretsMap ?? {},
+        secretsFromEnv: options?.secretsFromEnv ?? false,
+        importMap: options?.importMap ?? {},
+        path: ["$"],
+        depth: 0,
+        maxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,
+    };
+    return reviver.call(context, json);
 }

package/dist/load/serializable.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Serializable = void 0;
 exports.get_lc_unique_name = get_lc_unique_name;
 const map_keys_js_1 = require("./map_keys.cjs");
+const validation_js_1 = require("./validation.cjs");
 function shallowCopy(obj) {
     return Array.isArray(obj) ? [...obj] : { ...obj };
 }
@@ -174,11 +175,21 @@ class Serializable {
                 write[last] = write[last] || read[last];
             }
         });
+        const escapedKwargs = {};
+        for (const [key, value] of Object.entries(kwargs)) {
+            escapedKwargs[key] = (0, validation_js_1.escapeIfNeeded)(value);
+        }
+        // Now add secret markers - these are added AFTER escaping so they won't be escaped
+        const kwargsWithSecrets = Object.keys(secrets).length
+            ? replaceSecrets(escapedKwargs, secrets)
+            : escapedKwargs;
+        // Finally transform keys to JSON format
+        const processedKwargs = (0, map_keys_js_1.mapKeys)(kwargsWithSecrets, map_keys_js_1.keyToJson, aliases);
         return {
             lc: 1,
             type: "constructor",
             id: this.lc_id,
-            kwargs: (0, map_keys_js_1.mapKeys)(Object.keys(secrets).length ? replaceSecrets(kwargs, secrets) : kwargs, map_keys_js_1.keyToJson, aliases),
+            kwargs: processedKwargs,
         };
     }
     toJSONNotImplemented() {

package/dist/load/serializable.d.ts

@@ -19,6 +19,20 @@ export type Serialized = SerializedConstructor | SerializedSecret | SerializedNo
  * Should not be subclassed, subclass lc_name above instead.
  */
 export declare function get_lc_unique_name(serializableClass: typeof Serializable): string;
+/**
+ * Interface for objects that can be serialized.
+ * This is a duck-typed interface to avoid circular imports.
+ */
+export interface SerializableLike {
+    lc_serializable: boolean;
+    lc_secrets?: Record<string, string>;
+    toJSON(): {
+        lc: number;
+        type: string;
+        id: string[];
+        kwargs?: Record<string, unknown>;
+    };
+}
 export interface SerializableInterface {
     get lc_id(): string[];
 }

package/dist/load/serializable.js

@@ -1,4 +1,5 @@
 import { keyToJson, mapKeys } from "./map_keys.js";
+import { escapeIfNeeded } from "./validation.js";
 function shallowCopy(obj) {
     return Array.isArray(obj) ? [...obj] : { ...obj };
 }
@@ -170,11 +171,21 @@ export class Serializable {
                 write[last] = write[last] || read[last];
             }
         });
+        const escapedKwargs = {};
+        for (const [key, value] of Object.entries(kwargs)) {
+            escapedKwargs[key] = escapeIfNeeded(value);
+        }
+        // Now add secret markers - these are added AFTER escaping so they won't be escaped
+        const kwargsWithSecrets = Object.keys(secrets).length
+            ? replaceSecrets(escapedKwargs, secrets)
+            : escapedKwargs;
+        // Finally transform keys to JSON format
+        const processedKwargs = mapKeys(kwargsWithSecrets, keyToJson, aliases);
         return {
             lc: 1,
             type: "constructor",
             id: this.lc_id,
-            kwargs: mapKeys(Object.keys(secrets).length ? replaceSecrets(kwargs, secrets) : kwargs, keyToJson, aliases),
+            kwargs: processedKwargs,
         };
     }
     toJSONNotImplemented() {

package/dist/load/validation.cjs

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LC_ESCAPED_KEY = void 0;
+exports.needsEscaping = needsEscaping;
+exports.escapeObject = escapeObject;
+exports.isEscapedObject = isEscapedObject;
+exports.serializeValue = serializeValue;
+exports.serializeLcObject = serializeLcObject;
+exports.escapeIfNeeded = escapeIfNeeded;
+exports.unescapeValue = unescapeValue;
+/**
+ * Sentinel key used to mark escaped user objects during serialization.
+ *
+ * When a plain object contains 'lc' key (which could be confused with LC objects),
+ * we wrap it as `{"__lc_escaped__": {...original...}}`.
+ */
+exports.LC_ESCAPED_KEY = "__lc_escaped__";
+/**
+ * Check if an object needs escaping to prevent confusion with LC objects.
+ *
+ * An object needs escaping if:
+ * 1. It has an `'lc'` key (could be confused with LC serialization format)
+ * 2. It has only the escape key (would be mistaken for an escaped object)
+ */
+function needsEscaping(obj) {
+    return ("lc" in obj || (Object.keys(obj).length === 1 && exports.LC_ESCAPED_KEY in obj));
+}
+/**
+ * Wrap an object in the escape marker.
+ *
+ * @example
+ * ```typescript
+ * {"key": "value"}  // becomes {"__lc_escaped__": {"key": "value"}}
+ * ```
+ */
+function escapeObject(obj) {
+    return { [exports.LC_ESCAPED_KEY]: obj };
+}
+/**
+ * Check if an object is an escaped user object.
+ *
+ * @example
+ * ```typescript
+ * {"__lc_escaped__": {...}}  // is an escaped object
+ * ```
+ */
+function isEscapedObject(obj) {
+    return Object.keys(obj).length === 1 && exports.LC_ESCAPED_KEY in obj;
+}
+/**
+ * Check if an object looks like a Serializable instance (duck typing).
+ */
+function isSerializableLike(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "lc_serializable" in obj &&
+        typeof obj.toJSON === "function");
+}
+/**
+ * Create a "not_implemented" serialization result for objects that cannot be serialized.
+ */
+function createNotImplemented(obj) {
+    let id;
+    if (obj !== null && typeof obj === "object") {
+        if ("lc_id" in obj && Array.isArray(obj.lc_id)) {
+            id = obj.lc_id;
+        }
+        else {
+            id = [obj.constructor?.name ?? "Object"];
+        }
+    }
+    else {
+        id = [typeof obj];
+    }
+    return {
+        lc: 1,
+        type: "not_implemented",
+        id,
+    };
+}
+/**
+ * Serialize a value with escaping of user objects.
+ *
+ * Called recursively on kwarg values to escape any plain objects that could be
+ * confused with LC objects.
+ *
+ * @param obj - The value to serialize.
+ * @returns The serialized value with user objects escaped as needed.
+ */
+function serializeValue(obj) {
+    if (isSerializableLike(obj)) {
+        // This is an LC object - serialize it properly (not escaped)
+        return serializeLcObject(obj);
+    }
+    if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+        const record = obj;
+        // Check if object needs escaping BEFORE recursing into values.
+        // If it needs escaping, wrap it as-is - the contents are user data that
+        // will be returned as-is during deserialization (no instantiation).
+        // This prevents re-escaping of already-escaped nested content.
+        if (needsEscaping(record)) {
+            return escapeObject(record);
+        }
+        // Safe object (no 'lc' key) - recurse into values
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            result[key] = serializeValue(value);
+        }
+        return result;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => serializeValue(item));
+    }
+    if (typeof obj === "string" ||
+        typeof obj === "number" ||
+        typeof obj === "boolean" ||
+        obj === null) {
+        return obj;
+    }
+    // Non-JSON-serializable object (Date, custom objects, etc.)
+    return createNotImplemented(obj);
+}
+/**
+ * Serialize a `Serializable` object with escaping of user data in kwargs.
+ *
+ * @param obj - The `Serializable` object to serialize.
+ * @returns The serialized object with user data in kwargs escaped as needed.
+ *
+ * @remarks
+ * Kwargs values are processed with `serializeValue` to escape user data (like
+ * metadata) that contains `'lc'` keys. Secret fields (from `lc_secrets`) are
+ * skipped because `toJSON()` replaces their values with secret markers.
+ */
+function serializeLcObject(obj) {
+    // Secret fields are handled by toJSON() - it replaces values with secret markers
+    const secretFields = new Set(Object.keys(obj.lc_secrets ?? {}));
+    const serialized = { ...obj.toJSON() };
+    // Process kwargs to escape user data that could be confused with LC objects
+    // Skip secret fields - toJSON() already converted them to secret markers
+    if (serialized.type === "constructor" && serialized.kwargs) {
+        const newKwargs = {};
+        for (const [key, value] of Object.entries(serialized.kwargs)) {
+            if (secretFields.has(key)) {
+                newKwargs[key] = value;
+            }
+            else {
+                newKwargs[key] = serializeValue(value);
+            }
+        }
+        serialized.kwargs = newKwargs;
+    }
+    return serialized;
+}
+/**
+ * Escape a value if it needs escaping (contains `lc` key).
+ *
+ * This is a simpler version of `serializeValue` that doesn't handle Serializable
+ * objects - it's meant to be called on kwargs values that have already been
+ * processed by `toJSON()`.
+ *
+ * @param value - The value to potentially escape.
+ * @returns The value with any `lc`-containing objects wrapped in escape markers.
+ */
+function escapeIfNeeded(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        // Preserve Serializable objects - they have their own toJSON() that will be
+        // called by JSON.stringify. We don't want to convert them to plain objects.
+        if (isSerializableLike(value)) {
+            return value;
+        }
+        const record = value;
+        // Check if object needs escaping BEFORE recursing into values.
+        // If it needs escaping, wrap it as-is - the contents are user data that
+        // will be returned as-is during deserialization (no instantiation).
+        if (needsEscaping(record)) {
+            return escapeObject(record);
+        }
+        // Safe object (no 'lc' key) - recurse into values
+        const result = {};
+        for (const [key, val] of Object.entries(record)) {
+            result[key] = escapeIfNeeded(val);
+        }
+        return result;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => escapeIfNeeded(item));
+    }
+    return value;
+}
+/**
+ * Unescape a value, processing escape markers in object values and arrays.
+ *
+ * When an escaped object is encountered (`{"__lc_escaped__": ...}`), it's
+ * unwrapped and the contents are returned AS-IS (no further processing).
+ * The contents represent user data that should not be modified.
+ *
+ * For regular objects and arrays, we recurse to find any nested escape markers.
+ *
+ * @param obj - The value to unescape.
+ * @returns The unescaped value.
+ */
+function unescapeValue(obj) {
+    if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+        const record = obj;
+        if (isEscapedObject(record)) {
+            // Unwrap and return the user data as-is (no further unescaping).
+            // The contents are user data that may contain more escape keys,
+            // but those are part of the user's actual data.
+            return record[exports.LC_ESCAPED_KEY];
+        }
+        // Regular object - recurse into values to find nested escape markers
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            result[key] = unescapeValue(value);
+        }
+        return result;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => unescapeValue(item));
+    }
+    return obj;
+}

package/dist/load/validation.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Sentinel key used to mark escaped user objects during serialization.
+ *
+ * When a plain object contains 'lc' key (which could be confused with LC objects),
+ * we wrap it as `{"__lc_escaped__": {...original...}}`.
+ */
+export declare const LC_ESCAPED_KEY = "__lc_escaped__";
+/**
+ * Check if an object needs escaping to prevent confusion with LC objects.
+ *
+ * An object needs escaping if:
+ * 1. It has an `'lc'` key (could be confused with LC serialization format)
+ * 2. It has only the escape key (would be mistaken for an escaped object)
+ */
+export declare function needsEscaping(obj: Record<string, unknown>): boolean;
+/**
+ * Wrap an object in the escape marker.
+ *
+ * @example
+ * ```typescript
+ * {"key": "value"}  // becomes {"__lc_escaped__": {"key": "value"}}
+ * ```
+ */
+export declare function escapeObject(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Check if an object is an escaped user object.
+ *
+ * @example
+ * ```typescript
+ * {"__lc_escaped__": {...}}  // is an escaped object
+ * ```
+ */
+export declare function isEscapedObject(obj: Record<string, unknown>): boolean;
+/**
+ * Interface for objects that can be serialized.
+ * This is a duck-typed interface to avoid circular imports.
+ */
+interface SerializableLike {
+    lc_serializable: boolean;
+    lc_secrets?: Record<string, string>;
+    toJSON(): {
+        lc: number;
+        type: string;
+        id: string[];
+        kwargs?: Record<string, unknown>;
+    };
+}
+/**
+ * Serialize a value with escaping of user objects.
+ *
+ * Called recursively on kwarg values to escape any plain objects that could be
+ * confused with LC objects.
+ *
+ * @param obj - The value to serialize.
+ * @returns The serialized value with user objects escaped as needed.
+ */
+export declare function serializeValue(obj: unknown): unknown;
+/**
+ * Serialize a `Serializable` object with escaping of user data in kwargs.
+ *
+ * @param obj - The `Serializable` object to serialize.
+ * @returns The serialized object with user data in kwargs escaped as needed.
+ *
+ * @remarks
+ * Kwargs values are processed with `serializeValue` to escape user data (like
+ * metadata) that contains `'lc'` keys. Secret fields (from `lc_secrets`) are
+ * skipped because `toJSON()` replaces their values with secret markers.
+ */
+export declare function serializeLcObject(obj: SerializableLike): {
+    lc: number;
+    type: string;
+    id: string[];
+    kwargs?: Record<string, unknown>;
+};
+/**
+ * Escape a value if it needs escaping (contains `lc` key).
+ *
+ * This is a simpler version of `serializeValue` that doesn't handle Serializable
+ * objects - it's meant to be called on kwargs values that have already been
+ * processed by `toJSON()`.
+ *
+ * @param value - The value to potentially escape.
+ * @returns The value with any `lc`-containing objects wrapped in escape markers.
+ */
+export declare function escapeIfNeeded(value: unknown): unknown;
+/**
+ * Unescape a value, processing escape markers in object values and arrays.
+ *
+ * When an escaped object is encountered (`{"__lc_escaped__": ...}`), it's
+ * unwrapped and the contents are returned AS-IS (no further processing).
+ * The contents represent user data that should not be modified.
+ *
+ * For regular objects and arrays, we recurse to find any nested escape markers.
+ *
+ * @param obj - The value to unescape.
+ * @returns The unescaped value.
+ */
+export declare function unescapeValue(obj: unknown): unknown;
+export {};

package/dist/load/validation.js

@@ -0,0 +1,212 @@
+/**
+ * Sentinel key used to mark escaped user objects during serialization.
+ *
+ * When a plain object contains 'lc' key (which could be confused with LC objects),
+ * we wrap it as `{"__lc_escaped__": {...original...}}`.
+ */
+export const LC_ESCAPED_KEY = "__lc_escaped__";
+/**
+ * Check if an object needs escaping to prevent confusion with LC objects.
+ *
+ * An object needs escaping if:
+ * 1. It has an `'lc'` key (could be confused with LC serialization format)
+ * 2. It has only the escape key (would be mistaken for an escaped object)
+ */
+export function needsEscaping(obj) {
+    return ("lc" in obj || (Object.keys(obj).length === 1 && LC_ESCAPED_KEY in obj));
+}
+/**
+ * Wrap an object in the escape marker.
+ *
+ * @example
+ * ```typescript
+ * {"key": "value"}  // becomes {"__lc_escaped__": {"key": "value"}}
+ * ```
+ */
+export function escapeObject(obj) {
+    return { [LC_ESCAPED_KEY]: obj };
+}
+/**
+ * Check if an object is an escaped user object.
+ *
+ * @example
+ * ```typescript
+ * {"__lc_escaped__": {...}}  // is an escaped object
+ * ```
+ */
+export function isEscapedObject(obj) {
+    return Object.keys(obj).length === 1 && LC_ESCAPED_KEY in obj;
+}
+/**
+ * Check if an object looks like a Serializable instance (duck typing).
+ */
+function isSerializableLike(obj) {
+    return (obj !== null &&
+        typeof obj === "object" &&
+        "lc_serializable" in obj &&
+        typeof obj.toJSON === "function");
+}
+/**
+ * Create a "not_implemented" serialization result for objects that cannot be serialized.
+ */
+function createNotImplemented(obj) {
+    let id;
+    if (obj !== null && typeof obj === "object") {
+        if ("lc_id" in obj && Array.isArray(obj.lc_id)) {
+            id = obj.lc_id;
+        }
+        else {
+            id = [obj.constructor?.name ?? "Object"];
+        }
+    }
+    else {
+        id = [typeof obj];
+    }
+    return {
+        lc: 1,
+        type: "not_implemented",
+        id,
+    };
+}
+/**
+ * Serialize a value with escaping of user objects.
+ *
+ * Called recursively on kwarg values to escape any plain objects that could be
+ * confused with LC objects.
+ *
+ * @param obj - The value to serialize.
+ * @returns The serialized value with user objects escaped as needed.
+ */
+export function serializeValue(obj) {
+    if (isSerializableLike(obj)) {
+        // This is an LC object - serialize it properly (not escaped)
+        return serializeLcObject(obj);
+    }
+    if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+        const record = obj;
+        // Check if object needs escaping BEFORE recursing into values.
+        // If it needs escaping, wrap it as-is - the contents are user data that
+        // will be returned as-is during deserialization (no instantiation).
+        // This prevents re-escaping of already-escaped nested content.
+        if (needsEscaping(record)) {
+            return escapeObject(record);
+        }
+        // Safe object (no 'lc' key) - recurse into values
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            result[key] = serializeValue(value);
+        }
+        return result;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => serializeValue(item));
+    }
+    if (typeof obj === "string" ||
+        typeof obj === "number" ||
+        typeof obj === "boolean" ||
+        obj === null) {
+        return obj;
+    }
+    // Non-JSON-serializable object (Date, custom objects, etc.)
+    return createNotImplemented(obj);
+}
+/**
+ * Serialize a `Serializable` object with escaping of user data in kwargs.
+ *
+ * @param obj - The `Serializable` object to serialize.
+ * @returns The serialized object with user data in kwargs escaped as needed.
+ *
+ * @remarks
+ * Kwargs values are processed with `serializeValue` to escape user data (like
+ * metadata) that contains `'lc'` keys. Secret fields (from `lc_secrets`) are
+ * skipped because `toJSON()` replaces their values with secret markers.
+ */
+export function serializeLcObject(obj) {
+    // Secret fields are handled by toJSON() - it replaces values with secret markers
+    const secretFields = new Set(Object.keys(obj.lc_secrets ?? {}));
+    const serialized = { ...obj.toJSON() };
+    // Process kwargs to escape user data that could be confused with LC objects
+    // Skip secret fields - toJSON() already converted them to secret markers
+    if (serialized.type === "constructor" && serialized.kwargs) {
+        const newKwargs = {};
+        for (const [key, value] of Object.entries(serialized.kwargs)) {
+            if (secretFields.has(key)) {
+                newKwargs[key] = value;
+            }
+            else {
+                newKwargs[key] = serializeValue(value);
+            }
+        }
+        serialized.kwargs = newKwargs;
+    }
+    return serialized;
+}
+/**
+ * Escape a value if it needs escaping (contains `lc` key).
+ *
+ * This is a simpler version of `serializeValue` that doesn't handle Serializable
+ * objects - it's meant to be called on kwargs values that have already been
+ * processed by `toJSON()`.
+ *
+ * @param value - The value to potentially escape.
+ * @returns The value with any `lc`-containing objects wrapped in escape markers.
+ */
+export function escapeIfNeeded(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        // Preserve Serializable objects - they have their own toJSON() that will be
+        // called by JSON.stringify. We don't want to convert them to plain objects.
+        if (isSerializableLike(value)) {
+            return value;
+        }
+        const record = value;
+        // Check if object needs escaping BEFORE recursing into values.
+        // If it needs escaping, wrap it as-is - the contents are user data that
+        // will be returned as-is during deserialization (no instantiation).
+        if (needsEscaping(record)) {
+            return escapeObject(record);
+        }
+        // Safe object (no 'lc' key) - recurse into values
+        const result = {};
+        for (const [key, val] of Object.entries(record)) {
+            result[key] = escapeIfNeeded(val);
+        }
+        return result;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => escapeIfNeeded(item));
+    }
+    return value;
+}
+/**
+ * Unescape a value, processing escape markers in object values and arrays.
+ *
+ * When an escaped object is encountered (`{"__lc_escaped__": ...}`), it's
+ * unwrapped and the contents are returned AS-IS (no further processing).
+ * The contents represent user data that should not be modified.
+ *
+ * For regular objects and arrays, we recurse to find any nested escape markers.
+ *
+ * @param obj - The value to unescape.
+ * @returns The unescaped value.
+ */
+export function unescapeValue(obj) {
+    if (obj !== null && typeof obj === "object" && !Array.isArray(obj)) {
+        const record = obj;
+        if (isEscapedObject(record)) {
+            // Unwrap and return the user data as-is (no further unescaping).
+            // The contents are user data that may contain more escape keys,
+            // but those are part of the user's actual data.
+            return record[LC_ESCAPED_KEY];
+        }
+        // Regular object - recurse into values to find nested escape markers
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            result[key] = unescapeValue(value);
+        }
+        return result;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => unescapeValue(item));
+    }
+    return obj;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/core",
-  "version": "0.3.79",
+  "version": "0.3.80",
   "description": "Core LangChain.js abstractions and schemas",
   "type": "module",
   "engines": {