langchain 1.4.6-dev-1781485641139 → 1.4.6

package/dist/agents/middleware/provider/aws/promptCaching.js

@@ -0,0 +1,208 @@
+import { createMiddleware } from "../../../middleware.js";
+import { z } from "zod/v3";
+//#region src/agents/middleware/provider/aws/promptCaching.ts
+const DEFAULT_ENABLE_CACHING = true;
+const DEFAULT_TTL = "5m";
+const DEFAULT_MIN_MESSAGES_TO_CACHE = 1;
+const DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR = "warn";
+const contextSchema = z.object({
+	/**
+	* Whether to enable prompt caching.
+	* @default true
+	*/
+	enableCaching: z.boolean().optional(),
+	/**
+	* The time-to-live for the cached prompt.
+	* @default "5m"
+	*/
+	ttl: z.enum(["5m", "1h"]).optional(),
+	/**
+	* The minimum number of messages required before caching is applied.
+	* @default 1
+	*/
+	minMessagesToCache: z.number().optional(),
+	/**
+	* The behavior to take when an unsupported model is used.
+	* - "ignore" will ignore the unsupported model and continue without caching.
+	* - "warn" will warn the user and continue without caching.
+	* - "raise" will raise an error and stop the agent.
+	* @default "warn"
+	*/
+	unsupportedModelBehavior: z.enum([
+		"ignore",
+		"warn",
+		"raise"
+	]).optional()
+});
+var BedrockPromptCachingMiddlewareError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BedrockPromptCachingMiddlewareError";
+	}
+};
+/**
+* Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.
+*
+* This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse
+* models. This can significantly reduce costs for applications with repetitive prompts, long
+* system messages, or extensive conversation histories.
+*
+* ## How It Works
+*
+* The middleware intercepts model requests and sets a cache control signal that
+* `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are
+* inserted after the system prompt, after the tool definitions, and after the final message, so
+* the stable prefix of each request is cached. On subsequent requests with a matching prefix, the
+* cached representations are reused, skipping redundant token processing. Exact placement varies
+* by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `"1h"` TTL).
+*
+* ## Benefits
+*
+* - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly
+* - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed
+* - **Better Scalability**: Reduced computational load enables handling more requests
+* - **Consistent Performance**: Stable response times for repetitive queries
+*
+* @param middlewareOptions - Configuration options for the caching behavior
+* @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)
+* @param middlewareOptions.ttl - Cache time-to-live: `"5m"` for 5 minutes or `"1h"` for 1 hour (default: `"5m"`)
+* @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)
+* @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `"warn"`)
+*
+* @returns A middleware instance that can be passed to `createAgent`
+*
+* @throws {Error} When `unsupportedModelBehavior` is `"raise"` and the model is not a
+* cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock
+* Converse model outside the Anthropic Claude / Amazon Nova families.
+*
+* @example
+* Basic usage with default settings
+* ```typescript
+* import { createAgent } from "langchain";
+* import { bedrockPromptCachingMiddleware } from "langchain";
+*
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   middleware: [
+*     bedrockPromptCachingMiddleware()
+*   ]
+* });
+* ```
+*
+* @example
+* Custom configuration for longer conversations
+* ```typescript
+* const cachingMiddleware = bedrockPromptCachingMiddleware({
+*   ttl: "1h",  // Cache for 1 hour instead of default 5 minutes
+*   minMessagesToCache: 5  // Only cache after 5 messages
+* });
+*
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   systemPrompt: "You are a helpful assistant with deep knowledge of...", // Long system prompt
+*   middleware: [cachingMiddleware]
+* });
+* ```
+*
+* @example
+* Conditional caching based on runtime context
+* ```typescript
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   middleware: [
+*     bedrockPromptCachingMiddleware({
+*       enableCaching: true,
+*       ttl: "5m"
+*     })
+*   ]
+* });
+*
+* // Disable caching for specific requests
+* await agent.invoke(
+*   { messages: [new HumanMessage("Process this without caching")] },
+*   {
+*     configurable: {
+*       middleware_context: { enableCaching: false }
+*     }
+*   }
+* );
+* ```
+*
+* @example
+* Optimal setup for customer support chatbot
+* ```typescript
+* const supportAgent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   systemPrompt: `You are a customer support agent for ACME Corp.
+*
+*     Company policies:
+*     - Always be polite and professional
+*     - Refer to knowledge base for product information
+*     - Escalate billing issues to human agents
+*     ... (extensive policies and guidelines)
+*   `,
+*   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],
+*   middleware: [
+*     bedrockPromptCachingMiddleware({
+*       ttl: "1h",  // Long TTL for stable system prompt
+*       minMessagesToCache: 1  // Cache immediately due to large system prompt
+*     })
+*   ]
+* });
+* ```
+*
+* @remarks
+* - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`
+* - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`
+* - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`
+* - **TTL Options**: Only supports "5m" (5 minutes) and "1h" (1 hour) as TTL values; actual support varies by model
+* - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications
+*
+* @see {@link createAgent} for agent creation
+* @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation
+* @public
+*/
+function bedrockPromptCachingMiddleware(middlewareOptions) {
+	return createMiddleware({
+		name: "BedrockPromptCachingMiddleware",
+		contextSchema,
+		wrapModelCall: (request, handler) => {
+			const enableCaching = request.runtime.context.enableCaching ?? middlewareOptions?.enableCaching ?? DEFAULT_ENABLE_CACHING;
+			const ttl = request.runtime.context.ttl ?? middlewareOptions?.ttl ?? DEFAULT_TTL;
+			const minMessagesToCache = request.runtime.context.minMessagesToCache ?? middlewareOptions?.minMessagesToCache ?? DEFAULT_MIN_MESSAGES_TO_CACHE;
+			const unsupportedModelBehavior = request.runtime.context.unsupportedModelBehavior ?? middlewareOptions?.unsupportedModelBehavior ?? DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR;
+			if (!enableCaching || !request.model) return handler(request);
+			const modelName = request.model.getName();
+			const isBedrockConverseModel = modelName === "ChatBedrockConverse" || modelName === "ConfigurableModel" && (request.model._defaultConfig?.modelProvider === "bedrock" || request.model._defaultConfig?.modelProvider === "aws");
+			const modelId = modelName === "ConfigurableModel" ? request.model._defaultConfig?.model : request.model.model;
+			if (!(isBedrockConverseModel && typeof modelId === "string" && (modelId.toLowerCase().includes("anthropic.claude") || modelId.toLowerCase().includes("amazon.nova")))) {
+				const modelInfo = modelName === "ConfigurableModel" ? `${modelName} (${request.model._defaultConfig?.modelProvider})` : modelName;
+				const baseMessage = isBedrockConverseModel ? `Unsupported model '${modelInfo}'. Bedrock prompt caching is only supported on Anthropic Claude and Amazon Nova models` : `Unsupported model '${modelInfo}'. Prompt caching requires an AWS Bedrock Converse model`;
+				if (unsupportedModelBehavior === "raise") throw new BedrockPromptCachingMiddlewareError(`${baseMessage} (e.g., 'bedrock:anthropic.claude-haiku-4-5-20251001-v1:0').`);
+				else if (unsupportedModelBehavior === "warn") console.warn(`BedrockPromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic Claude or Amazon Nova model for caching benefits.`);
+				return handler(request);
+			}
+			if (request.state.messages.length + (request.systemPrompt ? 1 : 0) < minMessagesToCache) return handler(request);
+			/**
+			* The cache_control is applied at the final message formatting layer in
+			* ChatBedrockConverse (translated into Converse `cachePoint` blocks).
+			*
+			* @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
+			*/
+			return handler({
+				...request,
+				modelSettings: {
+					...request.modelSettings,
+					cache_control: {
+						type: "ephemeral",
+						ttl
+					}
+				}
+			});
+		}
+	});
+}
+//#endregion
+export { bedrockPromptCachingMiddleware };
+
+//# sourceMappingURL=promptCaching.js.map

package/dist/agents/middleware/provider/aws/promptCaching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCaching.js","names":[],"sources":["../../../../../src/agents/middleware/provider/aws/promptCaching.ts"],"sourcesContent":["import { z } from \"zod/v3\";\nimport { InferInteropZodInput } from \"@langchain/core/utils/types\";\n\nimport type { ConfigurableModel } from \"../../../../chat_models/universal.js\";\nimport { createMiddleware } from \"../../../middleware.js\";\n\nconst DEFAULT_ENABLE_CACHING = true;\nconst DEFAULT_TTL = \"5m\";\nconst DEFAULT_MIN_MESSAGES_TO_CACHE = 1;\nconst DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR = \"warn\";\n\nconst contextSchema = z.object({\n  /**\n   * Whether to enable prompt caching.\n   * @default true\n   */\n  enableCaching: z.boolean().optional(),\n  /**\n   * The time-to-live for the cached prompt.\n   * @default \"5m\"\n   */\n  ttl: z.enum([\"5m\", \"1h\"]).optional(),\n  /**\n   * The minimum number of messages required before caching is applied.\n   * @default 1\n   */\n  minMessagesToCache: z.number().optional(),\n  /**\n   * The behavior to take when an unsupported model is used.\n   * - \"ignore\" will ignore the unsupported model and continue without caching.\n   * - \"warn\" will warn the user and continue without caching.\n   * - \"raise\" will raise an error and stop the agent.\n   * @default \"warn\"\n   */\n  unsupportedModelBehavior: z.enum([\"ignore\", \"warn\", \"raise\"]).optional(),\n});\nexport type BedrockConversePromptCachingMiddlewareConfig = Partial<\n  InferInteropZodInput<typeof contextSchema>\n>;\n\nclass BedrockPromptCachingMiddlewareError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"BedrockPromptCachingMiddlewareError\";\n  }\n}\n\n/**\n * Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.\n *\n * This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse\n * models. This can significantly reduce costs for applications with repetitive prompts, long\n * system messages, or extensive conversation histories.\n *\n * ## How It Works\n *\n * The middleware intercepts model requests and sets a cache control signal that\n * `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are\n * inserted after the system prompt, after the tool definitions, and after the final message, so\n * the stable prefix of each request is cached. On subsequent requests with a matching prefix, the\n * cached representations are reused, skipping redundant token processing. Exact placement varies\n * by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `\"1h\"` TTL).\n *\n * ## Benefits\n *\n * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly\n * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed\n * - **Better Scalability**: Reduced computational load enables handling more requests\n * - **Consistent Performance**: Stable response times for repetitive queries\n *\n * @param middlewareOptions - Configuration options for the caching behavior\n * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)\n * @param middlewareOptions.ttl - Cache time-to-live: `\"5m\"` for 5 minutes or `\"1h\"` for 1 hour (default: `\"5m\"`)\n * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)\n * @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `\"warn\"`)\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @throws {Error} When `unsupportedModelBehavior` is `\"raise\"` and the model is not a\n * cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock\n * Converse model outside the Anthropic Claude / Amazon Nova families.\n *\n * @example\n * Basic usage with default settings\n * ```typescript\n * import { createAgent } from \"langchain\";\n * import { bedrockPromptCachingMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   middleware: [\n *     bedrockPromptCachingMiddleware()\n *   ]\n * });\n * ```\n *\n * @example\n * Custom configuration for longer conversations\n * ```typescript\n * const cachingMiddleware = bedrockPromptCachingMiddleware({\n *   ttl: \"1h\",  // Cache for 1 hour instead of default 5 minutes\n *   minMessagesToCache: 5  // Only cache after 5 messages\n * });\n *\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   systemPrompt: \"You are a helpful assistant with deep knowledge of...\", // Long system prompt\n *   middleware: [cachingMiddleware]\n * });\n * ```\n *\n * @example\n * Conditional caching based on runtime context\n * ```typescript\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   middleware: [\n *     bedrockPromptCachingMiddleware({\n *       enableCaching: true,\n *       ttl: \"5m\"\n *     })\n *   ]\n * });\n *\n * // Disable caching for specific requests\n * await agent.invoke(\n *   { messages: [new HumanMessage(\"Process this without caching\")] },\n *   {\n *     configurable: {\n *       middleware_context: { enableCaching: false }\n *     }\n *   }\n * );\n * ```\n *\n * @example\n * Optimal setup for customer support chatbot\n * ```typescript\n * const supportAgent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   systemPrompt: `You are a customer support agent for ACME Corp.\n *\n *     Company policies:\n *     - Always be polite and professional\n *     - Refer to knowledge base for product information\n *     - Escalate billing issues to human agents\n *     ... (extensive policies and guidelines)\n *   `,\n *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],\n *   middleware: [\n *     bedrockPromptCachingMiddleware({\n *       ttl: \"1h\",  // Long TTL for stable system prompt\n *       minMessagesToCache: 1  // Cache immediately due to large system prompt\n *     })\n *   ]\n * });\n * ```\n *\n * @remarks\n * - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`\n * - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`\n * - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`\n * - **TTL Options**: Only supports \"5m\" (5 minutes) and \"1h\" (1 hour) as TTL values; actual support varies by model\n * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications\n *\n * @see {@link createAgent} for agent creation\n * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation\n * @public\n */\nexport function bedrockPromptCachingMiddleware(\n  middlewareOptions?: BedrockConversePromptCachingMiddlewareConfig\n) {\n  return createMiddleware({\n    name: \"BedrockPromptCachingMiddleware\",\n    contextSchema,\n    wrapModelCall: (request, handler) => {\n      const enableCaching =\n        request.runtime.context.enableCaching ??\n        middlewareOptions?.enableCaching ??\n        DEFAULT_ENABLE_CACHING;\n      const ttl =\n        request.runtime.context.ttl ?? middlewareOptions?.ttl ?? DEFAULT_TTL;\n      const minMessagesToCache =\n        request.runtime.context.minMessagesToCache ??\n        middlewareOptions?.minMessagesToCache ??\n        DEFAULT_MIN_MESSAGES_TO_CACHE;\n      const unsupportedModelBehavior =\n        request.runtime.context.unsupportedModelBehavior ??\n        middlewareOptions?.unsupportedModelBehavior ??\n        DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR;\n\n      // Skip if caching is disabled\n      if (!enableCaching || !request.model) {\n        return handler(request);\n      }\n\n      const modelName = request.model.getName();\n      const isBedrockConverseModel =\n        modelName === \"ChatBedrockConverse\" ||\n        (modelName === \"ConfigurableModel\" &&\n          ((request.model as ConfigurableModel)._defaultConfig\n            ?.modelProvider === \"bedrock\" ||\n            (request.model as ConfigurableModel)._defaultConfig\n              ?.modelProvider === \"aws\"));\n\n      // Resolve the underlying Bedrock model id for cache-capability detection.\n      const modelId =\n        modelName === \"ConfigurableModel\"\n          ? ((request.model as ConfigurableModel)._defaultConfig?.model as\n              | string\n              | undefined)\n          : (request.model as { model?: string }).model;\n\n      // Bedrock prompt caching is only supported on the Anthropic Claude and\n      // Amazon Nova model families. Other Converse models (Mistral, Cohere,\n      // Meta, etc.) reject `cachePoint` blocks with an AccessDeniedException, so\n      // they are treated as unsupported.\n      const isCacheCapableModel =\n        isBedrockConverseModel &&\n        typeof modelId === \"string\" &&\n        (modelId.toLowerCase().includes(\"anthropic.claude\") ||\n          modelId.toLowerCase().includes(\"amazon.nova\"));\n\n      if (!isCacheCapableModel) {\n        const modelInfo =\n          modelName === \"ConfigurableModel\"\n            ? `${modelName} (${\n                (request.model as ConfigurableModel)._defaultConfig\n                  ?.modelProvider\n              })`\n            : modelName;\n\n        const baseMessage = isBedrockConverseModel\n          ? `Unsupported model '${modelInfo}'. Bedrock prompt caching is only supported on Anthropic Claude and Amazon Nova models`\n          : `Unsupported model '${modelInfo}'. Prompt caching requires an AWS Bedrock Converse model`;\n\n        if (unsupportedModelBehavior === \"raise\") {\n          throw new BedrockPromptCachingMiddlewareError(\n            `${baseMessage} (e.g., 'bedrock:anthropic.claude-haiku-4-5-20251001-v1:0').`\n          );\n        } else if (unsupportedModelBehavior === \"warn\") {\n          console.warn(\n            `BedrockPromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic Claude or Amazon Nova model for caching benefits.`\n          );\n        }\n        return handler(request);\n      }\n\n      const messagesCount =\n        request.state.messages.length + (request.systemPrompt ? 1 : 0);\n\n      if (messagesCount < minMessagesToCache) {\n        return handler(request);\n      }\n\n      /**\n       * The cache_control is applied at the final message formatting layer in\n       * ChatBedrockConverse (translated into Converse `cachePoint` blocks).\n       *\n       * @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html\n       */\n      return handler({\n        ...request,\n        modelSettings: {\n          ...request.modelSettings,\n          cache_control: {\n            type: \"ephemeral\" as const,\n            ttl,\n          },\n        },\n      });\n    },\n  });\n}\n"],"mappings":";;;AAMA,MAAM,yBAAyB;AAC/B,MAAM,cAAc;AACpB,MAAM,gCAAgC;AACtC,MAAM,qCAAqC;AAE3C,MAAM,gBAAgB,EAAE,OAAO;;;;;CAK7B,eAAe,EAAE,SAAS,CAAC,UAAU;;;;;CAKrC,KAAK,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,UAAU;;;;;CAKpC,oBAAoB,EAAE,QAAQ,CAAC,UAAU;;;;;;;;CAQzC,0BAA0B,EAAE,KAAK;EAAC;EAAU;EAAQ;EAAQ,CAAC,CAAC,UAAU;CACzE,CAAC;AAKF,IAAM,sCAAN,cAAkD,MAAM;CACtD,YAAY,SAAiB;AAC3B,QAAM,QAAQ;AACd,OAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HhB,SAAgB,+BACd,mBACA;AACA,QAAO,iBAAiB;EACtB,MAAM;EACN;EACA,gBAAgB,SAAS,YAAY;GACnC,MAAM,gBACJ,QAAQ,QAAQ,QAAQ,iBACxB,mBAAmB,iBACnB;GACF,MAAM,MACJ,QAAQ,QAAQ,QAAQ,OAAO,mBAAmB,OAAO;GAC3D,MAAM,qBACJ,QAAQ,QAAQ,QAAQ,sBACxB,mBAAmB,sBACnB;GACF,MAAM,2BACJ,QAAQ,QAAQ,QAAQ,4BACxB,mBAAmB,4BACnB;AAGF,OAAI,CAAC,iBAAiB,CAAC,QAAQ,MAC7B,QAAO,QAAQ,QAAQ;GAGzB,MAAM,YAAY,QAAQ,MAAM,SAAS;GACzC,MAAM,yBACJ,cAAc,yBACb,cAAc,wBACX,QAAQ,MAA4B,gBAClC,kBAAkB,aACnB,QAAQ,MAA4B,gBACjC,kBAAkB;GAG5B,MAAM,UACJ,cAAc,sBACR,QAAQ,MAA4B,gBAAgB,QAGrD,QAAQ,MAA6B;AAY5C,OAAI,EALF,0BACA,OAAO,YAAY,aAClB,QAAQ,aAAa,CAAC,SAAS,mBAAmB,IACjD,QAAQ,aAAa,CAAC,SAAS,cAAc,IAEvB;IACxB,MAAM,YACJ,cAAc,sBACV,GAAG,UAAU,IACV,QAAQ,MAA4B,gBACjC,cACL,KACD;IAEN,MAAM,cAAc,yBAChB,sBAAsB,UAAU,0FAChC,sBAAsB,UAAU;AAEpC,QAAI,6BAA6B,QAC/B,OAAM,IAAI,oCACR,GAAG,YAAY,8DAChB;aACQ,6BAA6B,OACtC,SAAQ,KACN,wDAAwD,UAAU,wFACnE;AAEH,WAAO,QAAQ,QAAQ;;AAMzB,OAFE,QAAQ,MAAM,SAAS,UAAU,QAAQ,eAAe,IAAI,KAE1C,mBAClB,QAAO,QAAQ,QAAQ;;;;;;;AASzB,UAAO,QAAQ;IACb,GAAG;IACH,eAAe;KACb,GAAG,QAAQ;KACX,eAAe;MACb,MAAM;MACN;MACD;KACF;IACF,CAAC;;EAEL,CAAC"}

package/dist/agents/middleware/toolEmulator.cjs

@@ -75,7 +75,7 @@ function toolEmulatorMiddleware(options = {}) {
 				console.error("Error initializing emulator model, using agent model:", err);
 				return agentModel;
 			});
-			return emulatorModel;
+			return emulatorModel ?? agentModel;
 		}
 		return agentModel;
 	};

package/dist/agents/middleware/toolEmulator.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"toolEmulator.cjs","names":["initChatModel","createMiddleware","HumanMessage","ToolMessage"],"sources":["../../../src/agents/middleware/toolEmulator.ts"],"sourcesContent":["import { HumanMessage, ToolMessage } from \"@langchain/core/messages\";\nimport type { BaseChatModel } from \"@langchain/core/language_models/chat_models\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\nimport { initChatModel } from \"../../chat_models/universal.js\";\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Options for configuring the Tool Emulator middleware.\n */\nexport interface ToolEmulatorOptions {\n  /**\n   * List of tool names (string) or tool instances to emulate.\n   * - If `undefined` (default), ALL tools will be emulated.\n   * - If empty array, no tools will be emulated.\n   * - If array with tool names/instances, only those tools will be emulated.\n   */\n  tools?: (string | ClientTool | ServerTool)[];\n\n  /**\n   * Model to use for emulation.\n   * - Can be a model identifier string (e.g., \"anthropic:claude-sonnet-4-5-20250929\")\n   * - Can be a BaseChatModel instance\n   * - Defaults to agent model\n   */\n  model?: string | BaseChatModel;\n}\n\n/**\n * Middleware that emulates specified tools using an LLM instead of executing them.\n *\n * This middleware allows selective emulation of tools for testing purposes.\n * By default (when `tools` is undefined), all tools are emulated. You can specify\n * which tools to emulate by passing a list of tool names or tool instances.\n *\n * @param options - Configuration options for the middleware\n * @param options.tools - List of tool names or tool instances to emulate. If undefined, all tools are emulated.\n * @param options.model - Model to use for emulation. Defaults to \"anthropic:claude-sonnet-4-5-20250929\".\n *\n * @example Emulate all tools (default behavior)\n * ```ts\n * import { toolEmulatorMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const middleware = toolEmulatorMiddleware();\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [getWeather, getUserLocation, calculator],\n *   middleware: [middleware],\n * });\n * ```\n *\n * @example Emulate specific tools by name\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\", \"get_user_location\"]\n * });\n * ```\n *\n * @example Use a custom model for emulation\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\"],\n *   model: \"anthropic:claude-sonnet-4-5-20250929\"\n * });\n * ```\n *\n * @example Emulate specific tools by passing tool instances\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [getWeather, getUserLocation]\n * });\n * ```\n */\nexport function toolEmulatorMiddleware(options: ToolEmulatorOptions = {}) {\n  let agentModel: BaseChatModel | undefined;\n  const { tools, model } = options;\n\n  /**\n   * Extract tool names from tools\n   */\n  const emulateAll = !tools || tools.length === 0;\n  const toolsToEmulate = new Set<string>();\n\n  if (!emulateAll && tools) {\n    for (const tool of tools) {\n      if (typeof tool === \"string\") {\n        toolsToEmulate.add(tool);\n      } else {\n        // Assume tool instance with .name property\n        const toolName =\n          typeof tool.name === \"string\" ? tool.name : String(tool.name);\n        toolsToEmulate.add(toolName);\n      }\n    }\n  }\n\n  /**\n   * Initialize emulator model\n   * We'll initialize it lazily in wrapToolCall to handle async initChatModel\n   */\n  let emulatorModel: BaseChatModel | undefined;\n  const getEmulatorModel = async (): Promise<BaseChatModel> => {\n    if (typeof model === \"object\") {\n      return model;\n    }\n    if (typeof model === \"string\") {\n      emulatorModel =\n        emulatorModel ??\n        (await initChatModel(model, { temperature: 1 }).catch((err) => {\n          console.error(\n            \"Error initializing emulator model, using agent model:\",\n            err\n          );\n          return agentModel as BaseChatModel;\n        }));\n      return emulatorModel;\n    }\n    return agentModel as BaseChatModel;\n  };\n\n  return createMiddleware({\n    name: \"ToolEmulatorMiddleware\",\n    wrapModelCall: async (request, handler) => {\n      agentModel = request.model as BaseChatModel;\n      return handler(request);\n    },\n    wrapToolCall: async (request, handler) => {\n      const toolName = request.toolCall.name;\n\n      // Check if this tool should be emulated\n      const shouldEmulate = emulateAll || toolsToEmulate.has(toolName);\n\n      if (!shouldEmulate) {\n        // Let it execute normally by calling the handler\n        return handler(request);\n      }\n\n      // Extract tool information for emulation\n      const toolArgs = request.toolCall.args;\n      const toolDescription =\n        request.tool?.description || \"No description available\";\n\n      // Build prompt for emulator LLM\n      const toolArgsString =\n        typeof toolArgs === \"string\" ? toolArgs : JSON.stringify(toolArgs);\n      const prompt = `You are emulating a tool call for testing purposes.\n\nTool: ${toolName}\nDescription: ${toolDescription}\nArguments: ${toolArgsString}\n\nGenerate a realistic response that this tool would return given these arguments.\nReturn ONLY the tool's output, no explanation or preamble. Introduce variation into your responses.`;\n\n      // Get emulated response from LLM\n      const emulator = await getEmulatorModel();\n      const response = await emulator.invoke([new HumanMessage(prompt)]);\n\n      // Extract content from response\n      const content =\n        typeof response.content === \"string\"\n          ? response.content\n          : JSON.stringify(response.content);\n\n      // Short-circuit: return emulated result without executing real tool\n      return new ToolMessage({\n        content,\n        tool_call_id: request.toolCall.id ?? \"\",\n        name: toolName,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,uBAAuB,UAA+B,EAAE,EAAE;CACxE,IAAI;CACJ,MAAM,EAAE,OAAO,UAAU;;;;CAKzB,MAAM,aAAa,CAAC,SAAS,MAAM,WAAW;CAC9C,MAAM,iCAAiB,IAAI,KAAa;AAExC,KAAI,CAAC,cAAc,MACjB,MAAK,MAAM,QAAQ,MACjB,KAAI,OAAO,SAAS,SAClB,gBAAe,IAAI,KAAK;MACnB;EAEL,MAAM,WACJ,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO,OAAO,KAAK,KAAK;AAC/D,iBAAe,IAAI,SAAS;;;;;;CASlC,IAAI;CACJ,MAAM,mBAAmB,YAAoC;AAC3D,MAAI,OAAO,UAAU,SACnB,QAAO;AAET,MAAI,OAAO,UAAU,UAAU;AAC7B,mBACE,iBACC,MAAMA,8BAAAA,cAAc,OAAO,EAAE,aAAa,GAAG,CAAC,CAAC,OAAO,QAAQ;AAC7D,YAAQ,MACN,yDACA,IACD;AACD,WAAO;KACP;AACJ,UAAO;;AAET,SAAO;;AAGT,QAAOC,mBAAAA,iBAAiB;EACtB,MAAM;EACN,eAAe,OAAO,SAAS,YAAY;AACzC,gBAAa,QAAQ;AACrB,UAAO,QAAQ,QAAQ;;EAEzB,cAAc,OAAO,SAAS,YAAY;GACxC,MAAM,WAAW,QAAQ,SAAS;AAKlC,OAAI,EAFkB,cAAc,eAAe,IAAI,SAAS,EAI9D,QAAO,QAAQ,QAAQ;GAIzB,MAAM,WAAW,QAAQ,SAAS;GAOlC,MAAM,SAAS;;QAEb,SAAS;eAPT,QAAQ,MAAM,eAAe,2BAQN;aAJvB,OAAO,aAAa,WAAW,WAAW,KAAK,UAAU,SAAS,CAK9C;;;;GAOtB,MAAM,WAAW,OAAM,MADA,kBAAkB,EACT,OAAO,CAAC,IAAIC,yBAAAA,aAAa,OAAO,CAAC,CAAC;AASlE,UAAO,IAAIC,yBAAAA,YAAY;IACrB,SANA,OAAO,SAAS,YAAY,WACxB,SAAS,UACT,KAAK,UAAU,SAAS,QAAQ;IAKpC,cAAc,QAAQ,SAAS,MAAM;IACrC,MAAM;IACP,CAAC;;EAEL,CAAC"}
+{"version":3,"file":"toolEmulator.cjs","names":["initChatModel","createMiddleware","HumanMessage","ToolMessage"],"sources":["../../../src/agents/middleware/toolEmulator.ts"],"sourcesContent":["import { HumanMessage, ToolMessage } from \"@langchain/core/messages\";\nimport type { BaseChatModel } from \"@langchain/core/language_models/chat_models\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\nimport { initChatModel } from \"../../chat_models/universal.js\";\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Options for configuring the Tool Emulator middleware.\n */\nexport interface ToolEmulatorOptions {\n  /**\n   * List of tool names (string) or tool instances to emulate.\n   * - If `undefined` (default), ALL tools will be emulated.\n   * - If empty array, no tools will be emulated.\n   * - If array with tool names/instances, only those tools will be emulated.\n   */\n  tools?: (string | ClientTool | ServerTool)[];\n\n  /**\n   * Model to use for emulation.\n   * - Can be a model identifier string (e.g., \"anthropic:claude-sonnet-4-5-20250929\")\n   * - Can be a BaseChatModel instance\n   * - Defaults to agent model\n   */\n  model?: string | BaseChatModel;\n}\n\n/**\n * Middleware that emulates specified tools using an LLM instead of executing them.\n *\n * This middleware allows selective emulation of tools for testing purposes.\n * By default (when `tools` is undefined), all tools are emulated. You can specify\n * which tools to emulate by passing a list of tool names or tool instances.\n *\n * @param options - Configuration options for the middleware\n * @param options.tools - List of tool names or tool instances to emulate. If undefined, all tools are emulated.\n * @param options.model - Model to use for emulation. Defaults to \"anthropic:claude-sonnet-4-5-20250929\".\n *\n * @example Emulate all tools (default behavior)\n * ```ts\n * import { toolEmulatorMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const middleware = toolEmulatorMiddleware();\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [getWeather, getUserLocation, calculator],\n *   middleware: [middleware],\n * });\n * ```\n *\n * @example Emulate specific tools by name\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\", \"get_user_location\"]\n * });\n * ```\n *\n * @example Use a custom model for emulation\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\"],\n *   model: \"anthropic:claude-sonnet-4-5-20250929\"\n * });\n * ```\n *\n * @example Emulate specific tools by passing tool instances\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [getWeather, getUserLocation]\n * });\n * ```\n */\nexport function toolEmulatorMiddleware(options: ToolEmulatorOptions = {}) {\n  let agentModel: BaseChatModel | undefined;\n  const { tools, model } = options;\n\n  /**\n   * Extract tool names from tools\n   */\n  const emulateAll = !tools || tools.length === 0;\n  const toolsToEmulate = new Set<string>();\n\n  if (!emulateAll && tools) {\n    for (const tool of tools) {\n      if (typeof tool === \"string\") {\n        toolsToEmulate.add(tool);\n      } else {\n        // Assume tool instance with .name property\n        const toolName =\n          typeof tool.name === \"string\" ? tool.name : String(tool.name);\n        toolsToEmulate.add(toolName);\n      }\n    }\n  }\n\n  /**\n   * Initialize emulator model\n   * We'll initialize it lazily in wrapToolCall to handle async initChatModel\n   */\n  let emulatorModel: BaseChatModel | undefined;\n  const getEmulatorModel = async (): Promise<BaseChatModel> => {\n    if (typeof model === \"object\") {\n      return model;\n    }\n    if (typeof model === \"string\") {\n      emulatorModel =\n        emulatorModel ??\n        (await initChatModel(model, { temperature: 1 }).catch((err) => {\n          console.error(\n            \"Error initializing emulator model, using agent model:\",\n            err\n          );\n          return agentModel as BaseChatModel;\n        }));\n      return emulatorModel ?? (agentModel as BaseChatModel);\n    }\n    return agentModel as BaseChatModel;\n  };\n\n  return createMiddleware({\n    name: \"ToolEmulatorMiddleware\",\n    wrapModelCall: async (request, handler) => {\n      agentModel = request.model as BaseChatModel;\n      return handler(request);\n    },\n    wrapToolCall: async (request, handler) => {\n      const toolName = request.toolCall.name;\n\n      // Check if this tool should be emulated\n      const shouldEmulate = emulateAll || toolsToEmulate.has(toolName);\n\n      if (!shouldEmulate) {\n        // Let it execute normally by calling the handler\n        return handler(request);\n      }\n\n      // Extract tool information for emulation\n      const toolArgs = request.toolCall.args;\n      const toolDescription =\n        request.tool?.description || \"No description available\";\n\n      // Build prompt for emulator LLM\n      const toolArgsString =\n        typeof toolArgs === \"string\" ? toolArgs : JSON.stringify(toolArgs);\n      const prompt = `You are emulating a tool call for testing purposes.\n\nTool: ${toolName}\nDescription: ${toolDescription}\nArguments: ${toolArgsString}\n\nGenerate a realistic response that this tool would return given these arguments.\nReturn ONLY the tool's output, no explanation or preamble. Introduce variation into your responses.`;\n\n      // Get emulated response from LLM\n      const emulator = await getEmulatorModel();\n      const response = await emulator.invoke([new HumanMessage(prompt)]);\n\n      // Extract content from response\n      const content =\n        typeof response.content === \"string\"\n          ? response.content\n          : JSON.stringify(response.content);\n\n      // Short-circuit: return emulated result without executing real tool\n      return new ToolMessage({\n        content,\n        tool_call_id: request.toolCall.id ?? \"\",\n        name: toolName,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,uBAAuB,UAA+B,EAAE,EAAE;CACxE,IAAI;CACJ,MAAM,EAAE,OAAO,UAAU;;;;CAKzB,MAAM,aAAa,CAAC,SAAS,MAAM,WAAW;CAC9C,MAAM,iCAAiB,IAAI,KAAa;AAExC,KAAI,CAAC,cAAc,MACjB,MAAK,MAAM,QAAQ,MACjB,KAAI,OAAO,SAAS,SAClB,gBAAe,IAAI,KAAK;MACnB;EAEL,MAAM,WACJ,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO,OAAO,KAAK,KAAK;AAC/D,iBAAe,IAAI,SAAS;;;;;;CASlC,IAAI;CACJ,MAAM,mBAAmB,YAAoC;AAC3D,MAAI,OAAO,UAAU,SACnB,QAAO;AAET,MAAI,OAAO,UAAU,UAAU;AAC7B,mBACE,iBACC,MAAMA,8BAAAA,cAAc,OAAO,EAAE,aAAa,GAAG,CAAC,CAAC,OAAO,QAAQ;AAC7D,YAAQ,MACN,yDACA,IACD;AACD,WAAO;KACP;AACJ,UAAO,iBAAkB;;AAE3B,SAAO;;AAGT,QAAOC,mBAAAA,iBAAiB;EACtB,MAAM;EACN,eAAe,OAAO,SAAS,YAAY;AACzC,gBAAa,QAAQ;AACrB,UAAO,QAAQ,QAAQ;;EAEzB,cAAc,OAAO,SAAS,YAAY;GACxC,MAAM,WAAW,QAAQ,SAAS;AAKlC,OAAI,EAFkB,cAAc,eAAe,IAAI,SAAS,EAI9D,QAAO,QAAQ,QAAQ;GAIzB,MAAM,WAAW,QAAQ,SAAS;GAOlC,MAAM,SAAS;;QAEb,SAAS;eAPT,QAAQ,MAAM,eAAe,2BAQN;aAJvB,OAAO,aAAa,WAAW,WAAW,KAAK,UAAU,SAAS,CAK9C;;;;GAOtB,MAAM,WAAW,OAAM,MADA,kBAAkB,EACT,OAAO,CAAC,IAAIC,yBAAAA,aAAa,OAAO,CAAC,CAAC;AASlE,UAAO,IAAIC,yBAAAA,YAAY;IACrB,SANA,OAAO,SAAS,YAAY,WACxB,SAAS,UACT,KAAK,UAAU,SAAS,QAAQ;IAKpC,cAAc,QAAQ,SAAS,MAAM;IACrC,MAAM;IACP,CAAC;;EAEL,CAAC"}

package/dist/agents/middleware/toolEmulator.js

@@ -74,7 +74,7 @@ function toolEmulatorMiddleware(options = {}) {
 				console.error("Error initializing emulator model, using agent model:", err);
 				return agentModel;
 			});
-			return emulatorModel;
+			return emulatorModel ?? agentModel;
 		}
 		return agentModel;
 	};

package/dist/agents/middleware/toolEmulator.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolEmulator.js","names":[],"sources":["../../../src/agents/middleware/toolEmulator.ts"],"sourcesContent":["import { HumanMessage, ToolMessage } from \"@langchain/core/messages\";\nimport type { BaseChatModel } from \"@langchain/core/language_models/chat_models\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\nimport { initChatModel } from \"../../chat_models/universal.js\";\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Options for configuring the Tool Emulator middleware.\n */\nexport interface ToolEmulatorOptions {\n  /**\n   * List of tool names (string) or tool instances to emulate.\n   * - If `undefined` (default), ALL tools will be emulated.\n   * - If empty array, no tools will be emulated.\n   * - If array with tool names/instances, only those tools will be emulated.\n   */\n  tools?: (string | ClientTool | ServerTool)[];\n\n  /**\n   * Model to use for emulation.\n   * - Can be a model identifier string (e.g., \"anthropic:claude-sonnet-4-5-20250929\")\n   * - Can be a BaseChatModel instance\n   * - Defaults to agent model\n   */\n  model?: string | BaseChatModel;\n}\n\n/**\n * Middleware that emulates specified tools using an LLM instead of executing them.\n *\n * This middleware allows selective emulation of tools for testing purposes.\n * By default (when `tools` is undefined), all tools are emulated. You can specify\n * which tools to emulate by passing a list of tool names or tool instances.\n *\n * @param options - Configuration options for the middleware\n * @param options.tools - List of tool names or tool instances to emulate. If undefined, all tools are emulated.\n * @param options.model - Model to use for emulation. Defaults to \"anthropic:claude-sonnet-4-5-20250929\".\n *\n * @example Emulate all tools (default behavior)\n * ```ts\n * import { toolEmulatorMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const middleware = toolEmulatorMiddleware();\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [getWeather, getUserLocation, calculator],\n *   middleware: [middleware],\n * });\n * ```\n *\n * @example Emulate specific tools by name\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\", \"get_user_location\"]\n * });\n * ```\n *\n * @example Use a custom model for emulation\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\"],\n *   model: \"anthropic:claude-sonnet-4-5-20250929\"\n * });\n * ```\n *\n * @example Emulate specific tools by passing tool instances\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [getWeather, getUserLocation]\n * });\n * ```\n */\nexport function toolEmulatorMiddleware(options: ToolEmulatorOptions = {}) {\n  let agentModel: BaseChatModel | undefined;\n  const { tools, model } = options;\n\n  /**\n   * Extract tool names from tools\n   */\n  const emulateAll = !tools || tools.length === 0;\n  const toolsToEmulate = new Set<string>();\n\n  if (!emulateAll && tools) {\n    for (const tool of tools) {\n      if (typeof tool === \"string\") {\n        toolsToEmulate.add(tool);\n      } else {\n        // Assume tool instance with .name property\n        const toolName =\n          typeof tool.name === \"string\" ? tool.name : String(tool.name);\n        toolsToEmulate.add(toolName);\n      }\n    }\n  }\n\n  /**\n   * Initialize emulator model\n   * We'll initialize it lazily in wrapToolCall to handle async initChatModel\n   */\n  let emulatorModel: BaseChatModel | undefined;\n  const getEmulatorModel = async (): Promise<BaseChatModel> => {\n    if (typeof model === \"object\") {\n      return model;\n    }\n    if (typeof model === \"string\") {\n      emulatorModel =\n        emulatorModel ??\n        (await initChatModel(model, { temperature: 1 }).catch((err) => {\n          console.error(\n            \"Error initializing emulator model, using agent model:\",\n            err\n          );\n          return agentModel as BaseChatModel;\n        }));\n      return emulatorModel;\n    }\n    return agentModel as BaseChatModel;\n  };\n\n  return createMiddleware({\n    name: \"ToolEmulatorMiddleware\",\n    wrapModelCall: async (request, handler) => {\n      agentModel = request.model as BaseChatModel;\n      return handler(request);\n    },\n    wrapToolCall: async (request, handler) => {\n      const toolName = request.toolCall.name;\n\n      // Check if this tool should be emulated\n      const shouldEmulate = emulateAll || toolsToEmulate.has(toolName);\n\n      if (!shouldEmulate) {\n        // Let it execute normally by calling the handler\n        return handler(request);\n      }\n\n      // Extract tool information for emulation\n      const toolArgs = request.toolCall.args;\n      const toolDescription =\n        request.tool?.description || \"No description available\";\n\n      // Build prompt for emulator LLM\n      const toolArgsString =\n        typeof toolArgs === \"string\" ? toolArgs : JSON.stringify(toolArgs);\n      const prompt = `You are emulating a tool call for testing purposes.\n\nTool: ${toolName}\nDescription: ${toolDescription}\nArguments: ${toolArgsString}\n\nGenerate a realistic response that this tool would return given these arguments.\nReturn ONLY the tool's output, no explanation or preamble. Introduce variation into your responses.`;\n\n      // Get emulated response from LLM\n      const emulator = await getEmulatorModel();\n      const response = await emulator.invoke([new HumanMessage(prompt)]);\n\n      // Extract content from response\n      const content =\n        typeof response.content === \"string\"\n          ? response.content\n          : JSON.stringify(response.content);\n\n      // Short-circuit: return emulated result without executing real tool\n      return new ToolMessage({\n        content,\n        tool_call_id: request.toolCall.id ?? \"\",\n        name: toolName,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,uBAAuB,UAA+B,EAAE,EAAE;CACxE,IAAI;CACJ,MAAM,EAAE,OAAO,UAAU;;;;CAKzB,MAAM,aAAa,CAAC,SAAS,MAAM,WAAW;CAC9C,MAAM,iCAAiB,IAAI,KAAa;AAExC,KAAI,CAAC,cAAc,MACjB,MAAK,MAAM,QAAQ,MACjB,KAAI,OAAO,SAAS,SAClB,gBAAe,IAAI,KAAK;MACnB;EAEL,MAAM,WACJ,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO,OAAO,KAAK,KAAK;AAC/D,iBAAe,IAAI,SAAS;;;;;;CASlC,IAAI;CACJ,MAAM,mBAAmB,YAAoC;AAC3D,MAAI,OAAO,UAAU,SACnB,QAAO;AAET,MAAI,OAAO,UAAU,UAAU;AAC7B,mBACE,iBACC,MAAM,cAAc,OAAO,EAAE,aAAa,GAAG,CAAC,CAAC,OAAO,QAAQ;AAC7D,YAAQ,MACN,yDACA,IACD;AACD,WAAO;KACP;AACJ,UAAO;;AAET,SAAO;;AAGT,QAAO,iBAAiB;EACtB,MAAM;EACN,eAAe,OAAO,SAAS,YAAY;AACzC,gBAAa,QAAQ;AACrB,UAAO,QAAQ,QAAQ;;EAEzB,cAAc,OAAO,SAAS,YAAY;GACxC,MAAM,WAAW,QAAQ,SAAS;AAKlC,OAAI,EAFkB,cAAc,eAAe,IAAI,SAAS,EAI9D,QAAO,QAAQ,QAAQ;GAIzB,MAAM,WAAW,QAAQ,SAAS;GAOlC,MAAM,SAAS;;QAEb,SAAS;eAPT,QAAQ,MAAM,eAAe,2BAQN;aAJvB,OAAO,aAAa,WAAW,WAAW,KAAK,UAAU,SAAS,CAK9C;;;;GAOtB,MAAM,WAAW,OAAM,MADA,kBAAkB,EACT,OAAO,CAAC,IAAI,aAAa,OAAO,CAAC,CAAC;AASlE,UAAO,IAAI,YAAY;IACrB,SANA,OAAO,SAAS,YAAY,WACxB,SAAS,UACT,KAAK,UAAU,SAAS,QAAQ;IAKpC,cAAc,QAAQ,SAAS,MAAM;IACrC,MAAM;IACP,CAAC;;EAEL,CAAC"}
+{"version":3,"file":"toolEmulator.js","names":[],"sources":["../../../src/agents/middleware/toolEmulator.ts"],"sourcesContent":["import { HumanMessage, ToolMessage } from \"@langchain/core/messages\";\nimport type { BaseChatModel } from \"@langchain/core/language_models/chat_models\";\nimport type { ClientTool, ServerTool } from \"@langchain/core/tools\";\nimport { initChatModel } from \"../../chat_models/universal.js\";\nimport { createMiddleware } from \"../middleware.js\";\n\n/**\n * Options for configuring the Tool Emulator middleware.\n */\nexport interface ToolEmulatorOptions {\n  /**\n   * List of tool names (string) or tool instances to emulate.\n   * - If `undefined` (default), ALL tools will be emulated.\n   * - If empty array, no tools will be emulated.\n   * - If array with tool names/instances, only those tools will be emulated.\n   */\n  tools?: (string | ClientTool | ServerTool)[];\n\n  /**\n   * Model to use for emulation.\n   * - Can be a model identifier string (e.g., \"anthropic:claude-sonnet-4-5-20250929\")\n   * - Can be a BaseChatModel instance\n   * - Defaults to agent model\n   */\n  model?: string | BaseChatModel;\n}\n\n/**\n * Middleware that emulates specified tools using an LLM instead of executing them.\n *\n * This middleware allows selective emulation of tools for testing purposes.\n * By default (when `tools` is undefined), all tools are emulated. You can specify\n * which tools to emulate by passing a list of tool names or tool instances.\n *\n * @param options - Configuration options for the middleware\n * @param options.tools - List of tool names or tool instances to emulate. If undefined, all tools are emulated.\n * @param options.model - Model to use for emulation. Defaults to \"anthropic:claude-sonnet-4-5-20250929\".\n *\n * @example Emulate all tools (default behavior)\n * ```ts\n * import { toolEmulatorMiddleware } from \"@langchain/langchain/agents/middleware\";\n * import { createAgent } from \"@langchain/langchain/agents\";\n *\n * const middleware = toolEmulatorMiddleware();\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [getWeather, getUserLocation, calculator],\n *   middleware: [middleware],\n * });\n * ```\n *\n * @example Emulate specific tools by name\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\", \"get_user_location\"]\n * });\n * ```\n *\n * @example Use a custom model for emulation\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [\"get_weather\"],\n *   model: \"anthropic:claude-sonnet-4-5-20250929\"\n * });\n * ```\n *\n * @example Emulate specific tools by passing tool instances\n * ```ts\n * const middleware = toolEmulatorMiddleware({\n *   tools: [getWeather, getUserLocation]\n * });\n * ```\n */\nexport function toolEmulatorMiddleware(options: ToolEmulatorOptions = {}) {\n  let agentModel: BaseChatModel | undefined;\n  const { tools, model } = options;\n\n  /**\n   * Extract tool names from tools\n   */\n  const emulateAll = !tools || tools.length === 0;\n  const toolsToEmulate = new Set<string>();\n\n  if (!emulateAll && tools) {\n    for (const tool of tools) {\n      if (typeof tool === \"string\") {\n        toolsToEmulate.add(tool);\n      } else {\n        // Assume tool instance with .name property\n        const toolName =\n          typeof tool.name === \"string\" ? tool.name : String(tool.name);\n        toolsToEmulate.add(toolName);\n      }\n    }\n  }\n\n  /**\n   * Initialize emulator model\n   * We'll initialize it lazily in wrapToolCall to handle async initChatModel\n   */\n  let emulatorModel: BaseChatModel | undefined;\n  const getEmulatorModel = async (): Promise<BaseChatModel> => {\n    if (typeof model === \"object\") {\n      return model;\n    }\n    if (typeof model === \"string\") {\n      emulatorModel =\n        emulatorModel ??\n        (await initChatModel(model, { temperature: 1 }).catch((err) => {\n          console.error(\n            \"Error initializing emulator model, using agent model:\",\n            err\n          );\n          return agentModel as BaseChatModel;\n        }));\n      return emulatorModel ?? (agentModel as BaseChatModel);\n    }\n    return agentModel as BaseChatModel;\n  };\n\n  return createMiddleware({\n    name: \"ToolEmulatorMiddleware\",\n    wrapModelCall: async (request, handler) => {\n      agentModel = request.model as BaseChatModel;\n      return handler(request);\n    },\n    wrapToolCall: async (request, handler) => {\n      const toolName = request.toolCall.name;\n\n      // Check if this tool should be emulated\n      const shouldEmulate = emulateAll || toolsToEmulate.has(toolName);\n\n      if (!shouldEmulate) {\n        // Let it execute normally by calling the handler\n        return handler(request);\n      }\n\n      // Extract tool information for emulation\n      const toolArgs = request.toolCall.args;\n      const toolDescription =\n        request.tool?.description || \"No description available\";\n\n      // Build prompt for emulator LLM\n      const toolArgsString =\n        typeof toolArgs === \"string\" ? toolArgs : JSON.stringify(toolArgs);\n      const prompt = `You are emulating a tool call for testing purposes.\n\nTool: ${toolName}\nDescription: ${toolDescription}\nArguments: ${toolArgsString}\n\nGenerate a realistic response that this tool would return given these arguments.\nReturn ONLY the tool's output, no explanation or preamble. Introduce variation into your responses.`;\n\n      // Get emulated response from LLM\n      const emulator = await getEmulatorModel();\n      const response = await emulator.invoke([new HumanMessage(prompt)]);\n\n      // Extract content from response\n      const content =\n        typeof response.content === \"string\"\n          ? response.content\n          : JSON.stringify(response.content);\n\n      // Short-circuit: return emulated result without executing real tool\n      return new ToolMessage({\n        content,\n        tool_call_id: request.toolCall.id ?? \"\",\n        name: toolName,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,uBAAuB,UAA+B,EAAE,EAAE;CACxE,IAAI;CACJ,MAAM,EAAE,OAAO,UAAU;;;;CAKzB,MAAM,aAAa,CAAC,SAAS,MAAM,WAAW;CAC9C,MAAM,iCAAiB,IAAI,KAAa;AAExC,KAAI,CAAC,cAAc,MACjB,MAAK,MAAM,QAAQ,MACjB,KAAI,OAAO,SAAS,SAClB,gBAAe,IAAI,KAAK;MACnB;EAEL,MAAM,WACJ,OAAO,KAAK,SAAS,WAAW,KAAK,OAAO,OAAO,KAAK,KAAK;AAC/D,iBAAe,IAAI,SAAS;;;;;;CASlC,IAAI;CACJ,MAAM,mBAAmB,YAAoC;AAC3D,MAAI,OAAO,UAAU,SACnB,QAAO;AAET,MAAI,OAAO,UAAU,UAAU;AAC7B,mBACE,iBACC,MAAM,cAAc,OAAO,EAAE,aAAa,GAAG,CAAC,CAAC,OAAO,QAAQ;AAC7D,YAAQ,MACN,yDACA,IACD;AACD,WAAO;KACP;AACJ,UAAO,iBAAkB;;AAE3B,SAAO;;AAGT,QAAO,iBAAiB;EACtB,MAAM;EACN,eAAe,OAAO,SAAS,YAAY;AACzC,gBAAa,QAAQ;AACrB,UAAO,QAAQ,QAAQ;;EAEzB,cAAc,OAAO,SAAS,YAAY;GACxC,MAAM,WAAW,QAAQ,SAAS;AAKlC,OAAI,EAFkB,cAAc,eAAe,IAAI,SAAS,EAI9D,QAAO,QAAQ,QAAQ;GAIzB,MAAM,WAAW,QAAQ,SAAS;GAOlC,MAAM,SAAS;;QAEb,SAAS;eAPT,QAAQ,MAAM,eAAe,2BAQN;aAJvB,OAAO,aAAa,WAAW,WAAW,KAAK,UAAU,SAAS,CAK9C;;;;GAOtB,MAAM,WAAW,OAAM,MADA,kBAAkB,EACT,OAAO,CAAC,IAAI,aAAa,OAAO,CAAC,CAAC;AASlE,UAAO,IAAI,YAAY;IACrB,SANA,OAAO,SAAS,YAAY,WACxB,SAAS,UACT,KAAK,UAAU,SAAS,QAAQ;IAKpC,cAAc,QAAQ,SAAS,MAAM;IACrC,MAAM;IACP,CAAC;;EAEL,CAAC"}

package/dist/agents/{transformers/tool-call.cjs → stream.cjs}

@@ -1,7 +1,19 @@
-require("../../_virtual/_rolldown/runtime.cjs");
+require("../_virtual/_rolldown/runtime.cjs");
 let _langchain_core_messages = require("@langchain/core/messages");
 let _langchain_langgraph = require("@langchain/langgraph");
-//#region src/agents/transformers/tool-call.ts
+//#region src/agents/stream.ts
+/**
+* Agent-level streaming support (experimental).
+*
+* Provides native stream transformer factories for tool calls and
+* middleware events.  When marked `__native: true`, their projections
+* are assigned directly onto the `GraphRunStream` instance by
+* `createGraphRunStream` in langgraph-core — no subclass or wrapper
+* needed.
+*
+* See protocol proposal §15 (In-Process Streaming Interface) and §16
+* (Native Stream Transformers).
+*/
 /**
 * Returns true when `ns` belongs to the agent's own graph — i.e. it
 * starts with `path` and is at most one level deeper (the agent's
@@ -161,4 +173,4 @@ function createToolCallTransformer(path) {
 //#endregion
 exports.createToolCallTransformer = createToolCallTransformer;
 
-//# sourceMappingURL=tool-call.cjs.map
+//# sourceMappingURL=stream.cjs.map

package/dist/agents/stream.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.cjs","names":["ToolMessage","StreamChannel"],"sources":["../../src/agents/stream.ts"],"sourcesContent":["/* oxlint-disable @typescript-eslint/no-explicit-any */\n\n/**\n * Agent-level streaming support (experimental).\n *\n * Provides native stream transformer factories for tool calls and\n * middleware events.  When marked `__native: true`, their projections\n * are assigned directly onto the `GraphRunStream` instance by\n * `createGraphRunStream` in langgraph-core — no subclass or wrapper\n * needed.\n *\n * See protocol proposal §15 (In-Process Streaming Interface) and §16\n * (Native Stream Transformers).\n */\n\nimport {\n  GraphRunStream,\n  StreamChannel,\n  type NativeStreamTransformer,\n  type ProtocolEvent,\n  type StreamTransformer,\n  type ToolCallStream,\n  type ToolCallStatus,\n  type ToolsEventData,\n  type Namespace,\n} from \"@langchain/langgraph\";\nimport type {\n  ClientTool,\n  ServerTool,\n  DynamicStructuredTool,\n  StructuredToolInterface,\n} from \"@langchain/core/tools\";\nimport { ToolMessage } from \"@langchain/core/messages\";\n\n/**\n * Infers the merged extensions shape from a tuple of stream transformer\n * factories. Mirrors `InferExtensions` from `@langchain/langgraph`, which\n * is not exported from the package's public surface.\n *\n * Given `[() => StreamTransformer<{ a: number }>, () => StreamTransformer<{ b: string }>]`,\n * produces `{ a: number } & { b: string }`.\n */\nexport type InferStreamExtensions<\n  T extends ReadonlyArray<() => StreamTransformer<any>>,\n> = T extends readonly []\n  ? Record<string, never>\n  : T extends readonly [\n        () => StreamTransformer<infer P>,\n        ...infer Rest extends ReadonlyArray<() => StreamTransformer<any>>,\n      ]\n    ? P & InferStreamExtensions<Rest>\n    : Record<string, unknown>;\n\n/** Extract the literal `name` string from a tool type. */\ntype ToolNameOf<T> = T extends { name: infer N extends string } ? N : string;\n\n/** Extract the parsed input type from a tool type. */\ntype ToolInputOf<T> =\n  T extends DynamicStructuredTool<any, any, infer SchemaInputT, any, any, any>\n    ? SchemaInputT\n    : T extends StructuredToolInterface<any, infer SchemaInputT, any>\n      ? SchemaInputT\n      : unknown;\n\n/** Extract the return/output type from a tool type. */\ntype ToolOutputOf<T> =\n  T extends DynamicStructuredTool<any, any, any, infer ToolOutputT, any, any>\n    ? ToolOutputT\n    : T extends StructuredToolInterface<any, any, infer ToolOutputT>\n      ? ToolOutputT\n      : unknown;\n\n/**\n * Discriminated union of {@link ToolCallStream} variants, one per tool\n * in `TTools`.  Enables TypeScript to narrow `.input` and `.output`\n * when the consumer checks `call.name === \"someToolName\"`.\n *\n * Falls back to `ToolCallStream` (untyped) when the tools tuple is a\n * plain `(ClientTool | ServerTool)[]` without literal name types.\n */\nexport type ToolCallStreamUnion<\n  TTools extends readonly (ClientTool | ServerTool)[],\n> = {\n  [K in keyof TTools]: ToolCallStream<\n    ToolNameOf<TTools[K]>,\n    ToolInputOf<TTools[K]>,\n    ToolOutputOf<TTools[K]>\n  >;\n}[number];\n\n/**\n * A {@link GraphRunStream} with native agent-level projections assigned\n * directly on the instance by `createGraphRunStream` (via `__native`\n * transformers).\n *\n * This is a pure type overlay — no runtime subclass exists.  Use the\n * `AgentRunStream` type when you need to describe the return type of\n * `streamEvents(..., { version: \"v3\" })`.\n *\n * @typeParam TValues - Shape of the graph's state values.\n * @typeParam TTools - Tuple of tools registered on the agent, used to type\n *   the per-tool `toolCalls` discriminated union.\n * @typeParam TMiddleware - Tuple of middleware registered on the agent, used\n *   to type the per-middleware `middleware` event union.\n * @typeParam TExtensions - Shape of `run.extensions` produced by user-supplied\n *   stream transformer factories. Derived via\n *   `InferExtensions<TStreamTransformers>`.\n */\nexport type AgentRunStream<\n  TValues = Record<string, unknown>,\n  TTools extends readonly (ClientTool | ServerTool)[] = readonly (\n    | ClientTool\n    | ServerTool\n  )[],\n  TExtensions extends Record<string, unknown> = Record<string, unknown>,\n> = GraphRunStream<TValues, TExtensions> & {\n  /** Tool call streams from the native ToolCallTransformer. */\n  toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;\n};\n\ninterface ToolCallProjection {\n  toolCalls: AsyncIterable<ToolCallStream>;\n}\n\n/**\n * Returns true when `ns` belongs to the agent's own graph — i.e. it\n * starts with `path` and is at most one level deeper (the agent's\n * internal nodes like `tools`, `model_request`, etc.).\n *\n * Events from subagent subgraphs (two or more levels deeper) are\n * excluded, so `run.toolCalls` / `run.middleware` only show events\n * from the agent itself, not from its subagents.\n */\nfunction isOwnEvent(ns: Namespace, path: Namespace): boolean {\n  if (ns.length < path.length || ns.length > path.length + 1) return false;\n  for (let i = 0; i < path.length; i += 1) {\n    if (ns[i] !== path[i]) return false;\n  }\n  return true;\n}\n\nfunction isHeadlessToolInterruptError(\n  message: string,\n  toolCallId: string | undefined\n): boolean {\n  try {\n    const parsed = JSON.parse(message) as unknown;\n    if (!Array.isArray(parsed)) return false;\n    return parsed.some((entry) => {\n      if (entry == null || typeof entry !== \"object\") return false;\n      const value = (entry as { value?: unknown }).value;\n      if (value == null || typeof value !== \"object\") return false;\n      const payload = value as {\n        type?: unknown;\n        toolCall?: { id?: unknown };\n      };\n      return (\n        payload.type === \"tool\" &&\n        (toolCallId == null ||\n          payload.toolCall?.id == null ||\n          payload.toolCall.id === toolCallId)\n      );\n    });\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Detects serialized LangChain `ToolMessage` values that can appear on\n * `tool-finished.output` after crossing a protocol or serialization boundary.\n *\n * @example\n * ```ts\n * {\n *   lc: 1,\n *   type: \"constructor\",\n *   id: [\"langchain_core\", \"messages\", \"ToolMessage\"],\n *   kwargs: { content: \"raw tool result\", tool_call_id: \"call_1\" }\n * }\n * ```\n */\nfunction isSerializedToolMessage(\n  value: unknown\n): value is { kwargs?: { content?: unknown } } {\n  if (value == null || typeof value !== \"object\") return false;\n  const record = value as Record<string, unknown>;\n  if (record.type !== \"constructor\" || !Array.isArray(record.id)) return false;\n  return record.id[record.id.length - 1] === \"ToolMessage\";\n}\n\nfunction normalizeToolOutput(output: unknown): unknown {\n  if (ToolMessage.isInstance(output)) {\n    return output.content;\n  }\n  if (isSerializedToolMessage(output)) {\n    return output.kwargs?.content;\n  }\n  return output;\n}\n\n/**\n * Creates a native transformer that correlates `tools` channel events\n * into per-call {@link ToolCallStream} objects.\n *\n * Marked `__native: true` — projection keys land directly on the\n * `GraphRunStream` instance as `run.toolCalls`.\n */\nexport function createToolCallTransformer(\n  path: Namespace\n): () => NativeStreamTransformer<ToolCallProjection> {\n  return () => {\n    const toolCallsLog = StreamChannel.local<ToolCallStream>();\n\n    const pendingCalls = new Map<\n      string,\n      {\n        resolveOutput: (v: unknown) => void;\n        rejectOutput: (e: unknown) => void;\n        resolveStatus: (v: ToolCallStatus) => void;\n        resolveError: (v: string | undefined) => void;\n      }\n    >();\n\n    function createToolCallEntry(\n      callId: string,\n      name: string,\n      rawInput: unknown\n    ): void {\n      if (pendingCalls.has(callId)) return;\n      const input =\n        typeof rawInput === \"string\" ? JSON.parse(rawInput) : rawInput;\n\n      let resolveOutput!: (v: unknown) => void;\n      let rejectOutput!: (e: unknown) => void;\n      let resolveStatus!: (v: ToolCallStatus) => void;\n      let resolveError!: (v: string | undefined) => void;\n\n      const output = new Promise<unknown>((res, rej) => {\n        resolveOutput = res;\n        rejectOutput = rej;\n      });\n      const status = new Promise<ToolCallStatus>((res) => {\n        resolveStatus = res;\n      });\n      const error = new Promise<string | undefined>((res) => {\n        resolveError = res;\n      });\n\n      pendingCalls.set(callId, {\n        resolveOutput,\n        rejectOutput,\n        resolveStatus,\n        resolveError,\n      });\n\n      toolCallsLog.push({\n        name,\n        callId,\n        input,\n        output,\n        status,\n        error,\n      } as ToolCallStream);\n    }\n\n    return {\n      __native: true as const,\n\n      init: () => ({\n        toolCalls: toolCallsLog,\n      }),\n\n      process(event: ProtocolEvent): boolean {\n        /**\n         * Only process events that are at the same depth as the agent's graph.\n         */\n        if (!isOwnEvent(event.params.namespace, path)) return true;\n\n        if (event.method === \"messages\") {\n          const data = event.params.data as Record<string, unknown>;\n          if (data.event === \"content-block-finish\") {\n            const cb = (data.contentBlock ?? data.content_block) as\n              | Record<string, unknown>\n              | undefined;\n            if (cb?.type === \"tool_call\") {\n              createToolCallEntry(\n                String(cb.id ?? \"\"),\n                String(cb.name ?? \"\"),\n                cb.args ?? cb.input\n              );\n            }\n          }\n        }\n\n        if (event.method === \"tools\") {\n          const data = event.params.data as ToolsEventData;\n          const toolCallId = (data as Record<string, unknown>)\n            .tool_call_id as string;\n\n          if (data.event === \"tool-started\") {\n            createToolCallEntry(\n              toolCallId,\n              ((data as Record<string, unknown>).tool_name as string) ??\n                \"unknown\",\n              (data as Record<string, unknown>).input\n            );\n          }\n\n          const pending = toolCallId ? pendingCalls.get(toolCallId) : undefined;\n\n          if (pending) {\n            if (data.event === \"tool-finished\") {\n              pending.resolveOutput(\n                normalizeToolOutput((data as Record<string, unknown>).output)\n              );\n              pending.resolveStatus(\"finished\");\n              pending.resolveError(undefined);\n              pendingCalls.delete(toolCallId);\n            } else if (data.event === \"tool-error\") {\n              const message =\n                ((data as Record<string, unknown>).message as string) ??\n                \"unknown error\";\n              if (isHeadlessToolInterruptError(message, toolCallId)) {\n                return true;\n              }\n              pending.rejectOutput(new Error(message));\n              pending.resolveStatus(\"error\");\n              pending.resolveError(message);\n              pendingCalls.delete(toolCallId);\n            }\n          }\n        }\n\n        return true;\n      },\n\n      finalize(): void {\n        for (const pending of pendingCalls.values()) {\n          pending.resolveStatus(\"finished\");\n          pending.resolveError(undefined);\n          pending.resolveOutput(undefined);\n        }\n        pendingCalls.clear();\n        toolCallsLog.close();\n      },\n\n      fail(err: unknown): void {\n        for (const pending of pendingCalls.values()) {\n          pending.resolveStatus(\"error\");\n          pending.resolveError(\n            err instanceof Error ? err.message : String(err)\n          );\n          pending.rejectOutput(err);\n        }\n        pendingCalls.clear();\n        toolCallsLog.fail(err);\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqIA,SAAS,WAAW,IAAe,MAA0B;AAC3D,KAAI,GAAG,SAAS,KAAK,UAAU,GAAG,SAAS,KAAK,SAAS,EAAG,QAAO;AACnE,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,EACpC,KAAI,GAAG,OAAO,KAAK,GAAI,QAAO;AAEhC,QAAO;;AAGT,SAAS,6BACP,SACA,YACS;AACT,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,QAAQ;AAClC,MAAI,CAAC,MAAM,QAAQ,OAAO,CAAE,QAAO;AACnC,SAAO,OAAO,MAAM,UAAU;AAC5B,OAAI,SAAS,QAAQ,OAAO,UAAU,SAAU,QAAO;GACvD,MAAM,QAAS,MAA8B;AAC7C,OAAI,SAAS,QAAQ,OAAO,UAAU,SAAU,QAAO;GACvD,MAAM,UAAU;AAIhB,UACE,QAAQ,SAAS,WAChB,cAAc,QACb,QAAQ,UAAU,MAAM,QACxB,QAAQ,SAAS,OAAO;IAE5B;SACI;AACN,SAAO;;;;;;;;;;;;;;;;;AAkBX,SAAS,wBACP,OAC6C;AAC7C,KAAI,SAAS,QAAQ,OAAO,UAAU,SAAU,QAAO;CACvD,MAAM,SAAS;AACf,KAAI,OAAO,SAAS,iBAAiB,CAAC,MAAM,QAAQ,OAAO,GAAG,CAAE,QAAO;AACvE,QAAO,OAAO,GAAG,OAAO,GAAG,SAAS,OAAO;;AAG7C,SAAS,oBAAoB,QAA0B;AACrD,KAAIA,yBAAAA,YAAY,WAAW,OAAO,CAChC,QAAO,OAAO;AAEhB,KAAI,wBAAwB,OAAO,CACjC,QAAO,OAAO,QAAQ;AAExB,QAAO;;;;;;;;;AAUT,SAAgB,0BACd,MACmD;AACnD,cAAa;EACX,MAAM,eAAeC,qBAAAA,cAAc,OAAuB;EAE1D,MAAM,+BAAe,IAAI,KAQtB;EAEH,SAAS,oBACP,QACA,MACA,UACM;AACN,OAAI,aAAa,IAAI,OAAO,CAAE;GAC9B,MAAM,QACJ,OAAO,aAAa,WAAW,KAAK,MAAM,SAAS,GAAG;GAExD,IAAI;GACJ,IAAI;GACJ,IAAI;GACJ,IAAI;GAEJ,MAAM,SAAS,IAAI,SAAkB,KAAK,QAAQ;AAChD,oBAAgB;AAChB,mBAAe;KACf;GACF,MAAM,SAAS,IAAI,SAAyB,QAAQ;AAClD,oBAAgB;KAChB;GACF,MAAM,QAAQ,IAAI,SAA6B,QAAQ;AACrD,mBAAe;KACf;AAEF,gBAAa,IAAI,QAAQ;IACvB;IACA;IACA;IACA;IACD,CAAC;AAEF,gBAAa,KAAK;IAChB;IACA;IACA;IACA;IACA;IACA;IACD,CAAmB;;AAGtB,SAAO;GACL,UAAU;GAEV,aAAa,EACX,WAAW,cACZ;GAED,QAAQ,OAA+B;;;;AAIrC,QAAI,CAAC,WAAW,MAAM,OAAO,WAAW,KAAK,CAAE,QAAO;AAEtD,QAAI,MAAM,WAAW,YAAY;KAC/B,MAAM,OAAO,MAAM,OAAO;AAC1B,SAAI,KAAK,UAAU,wBAAwB;MACzC,MAAM,KAAM,KAAK,gBAAgB,KAAK;AAGtC,UAAI,IAAI,SAAS,YACf,qBACE,OAAO,GAAG,MAAM,GAAG,EACnB,OAAO,GAAG,QAAQ,GAAG,EACrB,GAAG,QAAQ,GAAG,MACf;;;AAKP,QAAI,MAAM,WAAW,SAAS;KAC5B,MAAM,OAAO,MAAM,OAAO;KAC1B,MAAM,aAAc,KACjB;AAEH,SAAI,KAAK,UAAU,eACjB,qBACE,YACE,KAAiC,aACjC,WACD,KAAiC,MACnC;KAGH,MAAM,UAAU,aAAa,aAAa,IAAI,WAAW,GAAG,KAAA;AAE5D,SAAI;UACE,KAAK,UAAU,iBAAiB;AAClC,eAAQ,cACN,oBAAqB,KAAiC,OAAO,CAC9D;AACD,eAAQ,cAAc,WAAW;AACjC,eAAQ,aAAa,KAAA,EAAU;AAC/B,oBAAa,OAAO,WAAW;iBACtB,KAAK,UAAU,cAAc;OACtC,MAAM,UACF,KAAiC,WACnC;AACF,WAAI,6BAA6B,SAAS,WAAW,CACnD,QAAO;AAET,eAAQ,aAAa,IAAI,MAAM,QAAQ,CAAC;AACxC,eAAQ,cAAc,QAAQ;AAC9B,eAAQ,aAAa,QAAQ;AAC7B,oBAAa,OAAO,WAAW;;;;AAKrC,WAAO;;GAGT,WAAiB;AACf,SAAK,MAAM,WAAW,aAAa,QAAQ,EAAE;AAC3C,aAAQ,cAAc,WAAW;AACjC,aAAQ,aAAa,KAAA,EAAU;AAC/B,aAAQ,cAAc,KAAA,EAAU;;AAElC,iBAAa,OAAO;AACpB,iBAAa,OAAO;;GAGtB,KAAK,KAAoB;AACvB,SAAK,MAAM,WAAW,aAAa,QAAQ,EAAE;AAC3C,aAAQ,cAAc,QAAQ;AAC9B,aAAQ,aACN,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,CACjD;AACD,aAAQ,aAAa,IAAI;;AAE3B,iBAAa,OAAO;AACpB,iBAAa,KAAK,IAAI;;GAEzB"}

package/dist/agents/{transformers/types.d.ts → stream.d.cts}

@@ -1,10 +1,11 @@
 import { ClientTool, DynamicStructuredTool, ServerTool, StructuredToolInterface } from "@langchain/core/tools";
-import { ChatModelStream, GraphRunStream, LifecycleCause, StreamTransformer, ToolCallStream } from "@langchain/langgraph";
+import { GraphRunStream, Namespace, NativeStreamTransformer, StreamTransformer, ToolCallStream } from "@langchain/langgraph";
 
-//#region src/agents/transformers/types.d.ts
+//#region src/agents/stream.d.ts
 /**
  * Infers the merged extensions shape from a tuple of stream transformer
- * factories.
+ * factories. Mirrors `InferExtensions` from `@langchain/langgraph`, which
+ * is not exported from the package's public surface.
  *
  * Given `[() => StreamTransformer<{ a: number }>, () => StreamTransformer<{ b: string }>]`,
  * produces `{ a: number } & { b: string }`.
@@ -27,41 +28,6 @@ type ToolOutputOf<T> = T extends DynamicStructuredTool<any, any, any, infer Tool
  * plain `(ClientTool | ServerTool)[]` without literal name types.
  */
 type ToolCallStreamUnion<TTools extends readonly (ClientTool | ServerTool)[]> = { [K in keyof TTools]: ToolCallStream<ToolNameOf<TTools[K]>, ToolInputOf<TTools[K]>, ToolOutputOf<TTools[K]>> }[number];
-/**
- * A nested named-agent execution surfaced on `run.subagents`.
- *
- * A subagent is a nested `createAgent` run whose `lc_agent_name` differs from
- * its parent's — e.g. a `createAgent({ name })` invoked inside a tool body. The
- * handle exposes scoped projections (`messages`, `toolCalls`, nested
- * `subagents`) plus the resolved {@link name}, the {@link cause} that triggered
- * it, and the subagent's final {@link output} state.
- *
- * This is a self-contained handle (no subclass of `SubgraphRunStream`): its
- * projections are produced by per-subagent transformer instances that
- * {@link createSubagentTransformer} drives directly.
- *
- * @typeParam TValues - Shape of the subagent's final output state.
- * @typeParam TTools - Tuple of tools the subagent may call, used to type
- *   {@link toolCalls}.
- */
-interface SubagentRunStream<TValues = Record<string, unknown>, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[]> {
-  /** The subagent's `lc_agent_name` (set by `createAgent({ name })`). */
-  readonly name: string;
-  /**
-   * The tool call that dispatched this subagent, as
-   * `{ type: "toolCall", tool_call_id }`, or `undefined` when the originating
-   * tool call could not be recovered (e.g. it was not triggered from a tool).
-   */
-  readonly cause: LifecycleCause | undefined;
-  /** Resolves with the subagent's final state once it completes. */
-  readonly output: Promise<TValues>;
-  /** Per-message chat-model token streams scoped to this subagent. */
-  readonly messages: AsyncIterable<Omit<ChatModelStream, "then">>;
-  /** The subagent's own tool-call streams. */
-  readonly toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;
-  /** Nested subagents this subagent dispatches from its own tools. */
-  readonly subagents: AsyncIterable<SubagentRunStream>;
-}
 /**
  * A {@link GraphRunStream} with native agent-level projections assigned
  * directly on the instance by `createGraphRunStream` (via `__native`
@@ -74,22 +40,26 @@ interface SubagentRunStream<TValues = Record<string, unknown>, TTools extends re
  * @typeParam TValues - Shape of the graph's state values.
  * @typeParam TTools - Tuple of tools registered on the agent, used to type
  *   the per-tool `toolCalls` discriminated union.
+ * @typeParam TMiddleware - Tuple of middleware registered on the agent, used
+ *   to type the per-middleware `middleware` event union.
  * @typeParam TExtensions - Shape of `run.extensions` produced by user-supplied
  *   stream transformer factories. Derived via
- *   `InferStreamExtensions<TStreamTransformers>`.
+ *   `InferExtensions<TStreamTransformers>`.
  */
 type AgentRunStream<TValues = Record<string, unknown>, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TExtensions extends Record<string, unknown> = Record<string, unknown>> = GraphRunStream<TValues, TExtensions> & {
   /** Tool call streams from the native ToolCallTransformer. */toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;
-  /**
-   * Named subagent runs dispatched from tools, surfaced by the native
-   * {@link createSubagentTransformer}.  Each yielded {@link SubagentRunStream}
-   * is a nested `createAgent` run whose `lc_agent_name` differs from this
-   * agent's — for example a `createAgent({ name })` invoked inside a tool body.
-   * Unlike `run.subgraphs` (which also yields the agent's own internal nodes),
-   * `run.subagents` only yields real named-agent invocations.
-   */
-  subagents: AsyncIterable<SubagentRunStream<TValues>>;
 };
+interface ToolCallProjection {
+  toolCalls: AsyncIterable<ToolCallStream>;
+}
+/**
+ * Creates a native transformer that correlates `tools` channel events
+ * into per-call {@link ToolCallStream} objects.
+ *
+ * Marked `__native: true` — projection keys land directly on the
+ * `GraphRunStream` instance as `run.toolCalls`.
+ */
+declare function createToolCallTransformer(path: Namespace): () => NativeStreamTransformer<ToolCallProjection>;
 //#endregion
-export { AgentRunStream, InferStreamExtensions, SubagentRunStream, ToolCallStreamUnion };
-//# sourceMappingURL=types.d.ts.map
+export { AgentRunStream, InferStreamExtensions, ToolCallStreamUnion, createToolCallTransformer };
+//# sourceMappingURL=stream.d.cts.map

package/dist/agents/stream.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.cts","names":[],"sources":["../../src/agents/stream.ts"],"mappings":";;;;;;;;;;;;KA0CY,qBAAA,WACA,aAAA,OAAoB,iBAAA,UAC5B,CAAA,uBACA,MAAA,kBACA,CAAA,yBACU,iBAAA,iCACgB,aAAA,OAAoB,iBAAA,UAE5C,CAAA,GAAI,qBAAA,CAAsB,IAAA,IAC1B,MAAA;;KAGD,UAAA,MAAgB,CAAA;EAAY,IAAA;AAAA,IAAiC,CAAA;;KAG7D,WAAA,MACH,CAAA,SAAU,qBAAA,gDACN,YAAA,GACA,CAAA,SAAU,uBAAA,iCACR,YAAA;;KAIH,YAAA,MACH,CAAA,SAAU,qBAAA,+CACN,WAAA,GACA,CAAA,SAAU,uBAAA,gCACR,WAAA;;;;;AAlBsB;;;;KA6BlB,mBAAA,0BACe,UAAA,GAAa,UAAA,qBAE1B,MAAA,GAAS,cAAA,CACnB,UAAA,CAAW,MAAA,CAAO,CAAA,IAClB,WAAA,CAAY,MAAA,CAAO,CAAA,IACnB,YAAA,CAAa,MAAA,CAAO,CAAA;;;;;AAhC2C;;;;;;;;;;;;;;KAsDvD,cAAA,WACA,MAAA,4CACe,UAAA,GAAa,UAAA,gBAClC,UAAA,GACA,UAAA,yBAEgB,MAAA,oBAA0B,MAAA,qBAC5C,cAAA,CAAe,OAAA,EAAS,WAAA;EAvDZ,6DAyDd,SAAA,EAAW,aAAA,CAAc,mBAAA,CAAoB,MAAA;AAAA;AAAA,UAGrC,kBAAA;EACR,SAAA,EAAW,aAAA,CAAc,cAAA;AAAA;;;;;;;;iBAuFX,yBAAA,CACd,IAAA,EAAM,SAAA,SACC,uBAAA,CAAwB,kBAAA"}

package/dist/agents/{transformers/types.d.cts → stream.d.ts}

@@ -1,10 +1,11 @@
 import { ClientTool, DynamicStructuredTool, ServerTool, StructuredToolInterface } from "@langchain/core/tools";
-import { ChatModelStream, GraphRunStream, LifecycleCause, StreamTransformer, ToolCallStream } from "@langchain/langgraph";
+import { GraphRunStream, Namespace, NativeStreamTransformer, StreamTransformer, ToolCallStream } from "@langchain/langgraph";
 
-//#region src/agents/transformers/types.d.ts
+//#region src/agents/stream.d.ts
 /**
  * Infers the merged extensions shape from a tuple of stream transformer
- * factories.
+ * factories. Mirrors `InferExtensions` from `@langchain/langgraph`, which
+ * is not exported from the package's public surface.
  *
  * Given `[() => StreamTransformer<{ a: number }>, () => StreamTransformer<{ b: string }>]`,
  * produces `{ a: number } & { b: string }`.
@@ -27,41 +28,6 @@ type ToolOutputOf<T> = T extends DynamicStructuredTool<any, any, any, infer Tool
  * plain `(ClientTool | ServerTool)[]` without literal name types.
  */
 type ToolCallStreamUnion<TTools extends readonly (ClientTool | ServerTool)[]> = { [K in keyof TTools]: ToolCallStream<ToolNameOf<TTools[K]>, ToolInputOf<TTools[K]>, ToolOutputOf<TTools[K]>> }[number];
-/**
- * A nested named-agent execution surfaced on `run.subagents`.
- *
- * A subagent is a nested `createAgent` run whose `lc_agent_name` differs from
- * its parent's — e.g. a `createAgent({ name })` invoked inside a tool body. The
- * handle exposes scoped projections (`messages`, `toolCalls`, nested
- * `subagents`) plus the resolved {@link name}, the {@link cause} that triggered
- * it, and the subagent's final {@link output} state.
- *
- * This is a self-contained handle (no subclass of `SubgraphRunStream`): its
- * projections are produced by per-subagent transformer instances that
- * {@link createSubagentTransformer} drives directly.
- *
- * @typeParam TValues - Shape of the subagent's final output state.
- * @typeParam TTools - Tuple of tools the subagent may call, used to type
- *   {@link toolCalls}.
- */
-interface SubagentRunStream<TValues = Record<string, unknown>, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[]> {
-  /** The subagent's `lc_agent_name` (set by `createAgent({ name })`). */
-  readonly name: string;
-  /**
-   * The tool call that dispatched this subagent, as
-   * `{ type: "toolCall", tool_call_id }`, or `undefined` when the originating
-   * tool call could not be recovered (e.g. it was not triggered from a tool).
-   */
-  readonly cause: LifecycleCause | undefined;
-  /** Resolves with the subagent's final state once it completes. */
-  readonly output: Promise<TValues>;
-  /** Per-message chat-model token streams scoped to this subagent. */
-  readonly messages: AsyncIterable<Omit<ChatModelStream, "then">>;
-  /** The subagent's own tool-call streams. */
-  readonly toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;
-  /** Nested subagents this subagent dispatches from its own tools. */
-  readonly subagents: AsyncIterable<SubagentRunStream>;
-}
 /**
  * A {@link GraphRunStream} with native agent-level projections assigned
  * directly on the instance by `createGraphRunStream` (via `__native`
@@ -74,22 +40,26 @@ interface SubagentRunStream<TValues = Record<string, unknown>, TTools extends re
  * @typeParam TValues - Shape of the graph's state values.
  * @typeParam TTools - Tuple of tools registered on the agent, used to type
  *   the per-tool `toolCalls` discriminated union.
+ * @typeParam TMiddleware - Tuple of middleware registered on the agent, used
+ *   to type the per-middleware `middleware` event union.
  * @typeParam TExtensions - Shape of `run.extensions` produced by user-supplied
  *   stream transformer factories. Derived via
- *   `InferStreamExtensions<TStreamTransformers>`.
+ *   `InferExtensions<TStreamTransformers>`.
  */
 type AgentRunStream<TValues = Record<string, unknown>, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TExtensions extends Record<string, unknown> = Record<string, unknown>> = GraphRunStream<TValues, TExtensions> & {
   /** Tool call streams from the native ToolCallTransformer. */toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;
-  /**
-   * Named subagent runs dispatched from tools, surfaced by the native
-   * {@link createSubagentTransformer}.  Each yielded {@link SubagentRunStream}
-   * is a nested `createAgent` run whose `lc_agent_name` differs from this
-   * agent's — for example a `createAgent({ name })` invoked inside a tool body.
-   * Unlike `run.subgraphs` (which also yields the agent's own internal nodes),
-   * `run.subagents` only yields real named-agent invocations.
-   */
-  subagents: AsyncIterable<SubagentRunStream<TValues>>;
 };
+interface ToolCallProjection {
+  toolCalls: AsyncIterable<ToolCallStream>;
+}
+/**
+ * Creates a native transformer that correlates `tools` channel events
+ * into per-call {@link ToolCallStream} objects.
+ *
+ * Marked `__native: true` — projection keys land directly on the
+ * `GraphRunStream` instance as `run.toolCalls`.
+ */
+declare function createToolCallTransformer(path: Namespace): () => NativeStreamTransformer<ToolCallProjection>;
 //#endregion
-export { AgentRunStream, InferStreamExtensions, SubagentRunStream, ToolCallStreamUnion };
-//# sourceMappingURL=types.d.cts.map
+export { AgentRunStream, InferStreamExtensions, ToolCallStreamUnion, createToolCallTransformer };
+//# sourceMappingURL=stream.d.ts.map

package/dist/agents/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","names":[],"sources":["../../src/agents/stream.ts"],"mappings":";;;;;;;;;;;;KA0CY,qBAAA,WACA,aAAA,OAAoB,iBAAA,UAC5B,CAAA,uBACA,MAAA,kBACA,CAAA,yBACU,iBAAA,iCACgB,aAAA,OAAoB,iBAAA,UAE5C,CAAA,GAAI,qBAAA,CAAsB,IAAA,IAC1B,MAAA;;KAGD,UAAA,MAAgB,CAAA;EAAY,IAAA;AAAA,IAAiC,CAAA;;KAG7D,WAAA,MACH,CAAA,SAAU,qBAAA,gDACN,YAAA,GACA,CAAA,SAAU,uBAAA,iCACR,YAAA;;KAIH,YAAA,MACH,CAAA,SAAU,qBAAA,+CACN,WAAA,GACA,CAAA,SAAU,uBAAA,gCACR,WAAA;;;;;AAlBsB;;;;KA6BlB,mBAAA,0BACe,UAAA,GAAa,UAAA,qBAE1B,MAAA,GAAS,cAAA,CACnB,UAAA,CAAW,MAAA,CAAO,CAAA,IAClB,WAAA,CAAY,MAAA,CAAO,CAAA,IACnB,YAAA,CAAa,MAAA,CAAO,CAAA;;;;;AAhC2C;;;;;;;;;;;;;;KAsDvD,cAAA,WACA,MAAA,4CACe,UAAA,GAAa,UAAA,gBAClC,UAAA,GACA,UAAA,yBAEgB,MAAA,oBAA0B,MAAA,qBAC5C,cAAA,CAAe,OAAA,EAAS,WAAA;EAvDZ,6DAyDd,SAAA,EAAW,aAAA,CAAc,mBAAA,CAAoB,MAAA;AAAA;AAAA,UAGrC,kBAAA;EACR,SAAA,EAAW,aAAA,CAAc,cAAA;AAAA;;;;;;;;iBAuFX,yBAAA,CACd,IAAA,EAAM,SAAA,SACC,uBAAA,CAAwB,kBAAA"}

package/dist/agents/{transformers/tool-call.js → stream.js}

@@ -1,6 +1,18 @@
 import { ToolMessage } from "@langchain/core/messages";
 import { StreamChannel } from "@langchain/langgraph";
-//#region src/agents/transformers/tool-call.ts
+//#region src/agents/stream.ts
+/**
+* Agent-level streaming support (experimental).
+*
+* Provides native stream transformer factories for tool calls and
+* middleware events.  When marked `__native: true`, their projections
+* are assigned directly onto the `GraphRunStream` instance by
+* `createGraphRunStream` in langgraph-core — no subclass or wrapper
+* needed.
+*
+* See protocol proposal §15 (In-Process Streaming Interface) and §16
+* (Native Stream Transformers).
+*/
 /**
 * Returns true when `ns` belongs to the agent's own graph — i.e. it
 * starts with `path` and is at most one level deeper (the agent's
@@ -160,4 +172,4 @@ function createToolCallTransformer(path) {
 //#endregion
 export { createToolCallTransformer };
 
-//# sourceMappingURL=tool-call.js.map
+//# sourceMappingURL=stream.js.map