deepagents 1.7.5 → 1.8.0

package/dist/index.js

@@ -1,18 +1,19 @@
-import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, createAgent, createMiddleware, humanInTheLoopMiddleware, summarizationMiddleware, todoListMiddleware, tool } from "langchain";
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
 import { Runnable } from "@langchain/core/runnables";
 import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getCurrentTaskInput, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
 import { basename } from "path";
-import { HumanMessage as HumanMessage$1, RemoveMessage } from "@langchain/core/messages";
+import { HumanMessage as HumanMessage$1, RemoveMessage, getBufferString } from "@langchain/core/messages";
 import { z as z$1 } from "zod";
 import yaml from "yaml";
-import "uuid";
-import "langchain/chat_models/universal";
+import { v4 } from "uuid";
+import { ContextOverflowError } from "@langchain/core/errors";
+import { initChatModel } from "langchain/chat_models/universal";
 import fs from "node:fs/promises";
 import fs$1 from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import cp, { spawn } from "node:child_process";
 import fg from "fast-glob";
 import os from "node:os";
 
@@ -219,7 +220,7 @@ function performStringReplacement(content, oldString, newString, replaceAll) {
 	if (oldString === "") return "Error: oldString cannot be empty when file has content";
 	const occurrences = content.split(oldString).length - 1;
 	if (occurrences === 0) return `Error: String not found in file: '${oldString}'`;
-	if (occurrences > 1 && !replaceAll) return `Error: String '${oldString}' appears ${occurrences} times in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context.`;
+	if (occurrences > 1 && !replaceAll) return `Error: String '${oldString}' has multiple occurrences (appears ${occurrences} times) in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context.`;
 	return [content.split(oldString).join(newString), occurrences];
 }
 /**
@@ -868,7 +869,7 @@ function createWriteFileTool(backend, options) {
 		description: customDescription || WRITE_FILE_TOOL_DESCRIPTION,
 		schema: z.object({
 			file_path: z.string().describe("Absolute path to the file to write"),
-			content: z.string().describe("Content to write to the file")
+			content: z.string().default("").describe("Content to write to the file")
 		})
 	});
 }
@@ -1357,7 +1358,8 @@ function getSubagents(options) {
 			model: defaultModel,
 			systemPrompt: DEFAULT_SUBAGENT_PROMPT,
 			tools: defaultTools,
-			middleware: generalPurposeMiddleware
+			middleware: generalPurposeMiddleware,
+			name: "general-purpose"
 		});
 		subagentDescriptions.push(`- general-purpose: ${DEFAULT_GENERAL_PURPOSE_DESCRIPTION}`);
 	}
@@ -1372,7 +1374,8 @@ function getSubagents(options) {
 				model: agentParams.model ?? defaultModel,
 				systemPrompt: agentParams.systemPrompt,
 				tools: agentParams.tools ?? defaultTools,
-				middleware
+				middleware,
+				name: agentParams.name
 			});
 		}
 	}
@@ -2234,6 +2237,76 @@ function createSkillsMiddleware(options) {
 * For simple use cases without backend offloading, use `summarizationMiddleware`
 * from `langchain` directly.
 */
+const DEFAULT_MESSAGES_TO_KEEP = 20;
+const DEFAULT_TRIM_TOKEN_LIMIT = 4e3;
+const FALLBACK_TRIGGER = {
+	type: "tokens",
+	value: 17e4
+};
+const FALLBACK_KEEP = {
+	type: "messages",
+	value: 6
+};
+const FALLBACK_TRUNCATE_ARGS = {
+	trigger: {
+		type: "messages",
+		value: 20
+	},
+	keep: {
+		type: "messages",
+		value: 20
+	}
+};
+const PROFILE_TRIGGER = {
+	type: "fraction",
+	value: .85
+};
+const PROFILE_KEEP = {
+	type: "fraction",
+	value: .1
+};
+const PROFILE_TRUNCATE_ARGS = {
+	trigger: {
+		type: "fraction",
+		value: .85
+	},
+	keep: {
+		type: "fraction",
+		value: .1
+	}
+};
+/**
+* Compute summarization defaults based on model profile.
+* Mirrors Python's `_compute_summarization_defaults`.
+*
+* If the model has a profile with `maxInputTokens`, uses fraction-based
+* settings. Otherwise, uses fixed token/message counts.
+*
+* @param resolvedModel - The resolved chat model instance.
+*/
+function computeSummarizationDefaults(resolvedModel) {
+	if (resolvedModel.profile && typeof resolvedModel.profile === "object" && "maxInputTokens" in resolvedModel.profile && typeof resolvedModel.profile.maxInputTokens === "number") return {
+		trigger: PROFILE_TRIGGER,
+		keep: PROFILE_KEEP,
+		truncateArgsSettings: PROFILE_TRUNCATE_ARGS
+	};
+	return {
+		trigger: FALLBACK_TRIGGER,
+		keep: FALLBACK_KEEP,
+		truncateArgsSettings: FALLBACK_TRUNCATE_ARGS
+	};
+}
+const DEFAULT_SUMMARY_PROMPT = `You are a conversation summarizer. Your task is to create a concise summary of the conversation that captures:
+1. The main topics discussed
+2. Key decisions or conclusions reached
+3. Any important context that would be needed for continuing the conversation
+
+Keep the summary focused and informative. Do not include unnecessary details.
+
+Conversation to summarize:
+{conversation}
+
+Summary:`;
 /**
 * Zod schema for a summarization event that tracks what was summarized and
 * where the cutoff is.
@@ -2254,6 +2327,548 @@ const SummarizationStateSchema = z$1.object({
 	_summarizationSessionId: z$1.string().optional(),
 	_summarizationEvent: SummarizationEventSchema.optional()
 });
+/**
+* Check if a message is a previous summarization message.
+* Summary messages are HumanMessage objects with lc_source='summarization' in additional_kwargs.
+*/
+function isSummaryMessage(msg) {
+	if (!HumanMessage.isInstance(msg)) return false;
+	return msg.additional_kwargs?.lc_source === "summarization";
+}
+/**
+* Create summarization middleware with backend support for conversation history offloading.
+*
+* This middleware:
+* 1. Monitors conversation length against configured thresholds
+* 2. When triggered, offloads old messages to backend storage
+* 3. Generates a summary of offloaded messages
+* 4. Replaces old messages with the summary, preserving recent context
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for summarization and history offloading
+*/
+function createSummarizationMiddleware(options) {
+	const { model, backend, summaryPrompt = DEFAULT_SUMMARY_PROMPT, trimTokensToSummarize = DEFAULT_TRIM_TOKEN_LIMIT, historyPathPrefix = "/conversation_history" } = options;
+	let trigger = options.trigger;
+	let keep = options.keep ?? {
+		type: "messages",
+		value: DEFAULT_MESSAGES_TO_KEEP
+	};
+	let truncateArgsSettings = options.truncateArgsSettings;
+	let defaultsComputed = trigger != null;
+	let truncateTrigger = truncateArgsSettings?.trigger;
+	let truncateKeep = truncateArgsSettings?.keep ?? {
+		type: "messages",
+		value: 20
+	};
+	let maxArgLength = truncateArgsSettings?.maxLength ?? 2e3;
+	let truncationText = truncateArgsSettings?.truncationText ?? "...(argument truncated)";
+	/**
+	* Lazily compute defaults from model profile when trigger was not provided.
+	* Called once when the model is first resolved.
+	*/
+	function applyModelDefaults(resolvedModel) {
+		if (defaultsComputed) return;
+		defaultsComputed = true;
+		const defaults = computeSummarizationDefaults(resolvedModel);
+		trigger = defaults.trigger;
+		keep = options.keep ?? defaults.keep;
+		if (!options.truncateArgsSettings) {
+			truncateArgsSettings = defaults.truncateArgsSettings;
+			truncateTrigger = defaults.truncateArgsSettings.trigger;
+			truncateKeep = defaults.truncateArgsSettings.keep ?? {
+				type: "messages",
+				value: 20
+			};
+			maxArgLength = defaults.truncateArgsSettings.maxLength ?? 2e3;
+			truncationText = defaults.truncateArgsSettings.truncationText ?? "...(argument truncated)";
+		}
+	}
+	let sessionId = null;
+	let tokenEstimationMultiplier = 1;
+	/**
+	* Resolve backend from instance or factory.
+	*/
+	function getBackend(state) {
+		if (typeof backend === "function") return backend({ state });
+		return backend;
+	}
+	/**
+	* Get or create session ID for history file naming.
+	*/
+	function getSessionId(state) {
+		if (state._summarizationSessionId) return state._summarizationSessionId;
+		if (!sessionId) sessionId = `session_${v4().substring(0, 8)}`;
+		return sessionId;
+	}
+	/**
+	* Get the history file path.
+	*/
+	function getHistoryPath(state) {
+		return `${historyPathPrefix}/${getSessionId(state)}.md`;
+	}
+	/**
+	* Cached resolved model to avoid repeated initChatModel calls
+	*/
+	let cachedModel = void 0;
+	/**
+	* Resolve the chat model.
+	* Uses initChatModel to support any model provider from a string name.
+	* The resolved model is cached for subsequent calls.
+	*/
+	async function getChatModel() {
+		if (cachedModel) return cachedModel;
+		if (typeof model === "string") cachedModel = await initChatModel(model);
+		else cachedModel = model;
+		return cachedModel;
+	}
+	/**
+	* Get the max input tokens from the model's profile.
+	* Similar to Python's _get_profile_limits.
+	*
+	* When the profile is unavailable, returns undefined. In that case the
+	* middleware uses fixed token/message-count fallback defaults for
+	* trigger/keep, and relies on the ContextOverflowError catch as a
+	* safety net if the prompt still exceeds the model's actual limit.
+	*/
+	function getMaxInputTokens(resolvedModel) {
+		const profile = resolvedModel.profile;
+		if (profile && typeof profile === "object" && "maxInputTokens" in profile && typeof profile.maxInputTokens === "number") return profile.maxInputTokens;
+	}
+	/**
+	* Check if summarization should be triggered.
+	*/
+	function shouldSummarize(messages, totalTokens, maxInputTokens) {
+		if (!trigger) return false;
+		const adjustedTokens = totalTokens * tokenEstimationMultiplier;
+		const triggers = Array.isArray(trigger) ? trigger : [trigger];
+		for (const t of triggers) {
+			if (t.type === "messages" && messages.length >= t.value) return true;
+			if (t.type === "tokens" && adjustedTokens >= t.value) return true;
+			if (t.type === "fraction" && maxInputTokens) {
+				if (adjustedTokens >= Math.floor(maxInputTokens * t.value)) return true;
+			}
+		}
+		return false;
+	}
+	/**
+	* Find a safe cutoff point that doesn't split AI/Tool message pairs.
+	*
+	* If the message at `cutoffIndex` is a ToolMessage, this adjusts the boundary
+	* so that related AI and Tool messages stay together. Two strategies are used:
+	*
+	* 1. **Move backward** to include the AIMessage that produced the tool calls,
+	*    keeping the pair in the preserved set. Preferred when it doesn't move
+	*    the cutoff too far back.
+	*
+	* 2. **Advance forward** past all consecutive ToolMessages, putting the entire
+	*    pair into the summarized set. Used when moving backward would preserve
+	*    too many messages (e.g., a single AIMessage made 20+ tool calls).
+	*/
+	function findSafeCutoffPoint(messages, cutoffIndex) {
+		if (cutoffIndex >= messages.length || !ToolMessage.isInstance(messages[cutoffIndex])) return cutoffIndex;
+		let forwardIdx = cutoffIndex;
+		while (forwardIdx < messages.length && ToolMessage.isInstance(messages[forwardIdx])) forwardIdx++;
+		const toolCallIds = /* @__PURE__ */ new Set();
+		for (let i = cutoffIndex; i < forwardIdx; i++) {
+			const toolMsg = messages[i];
+			if (toolMsg.tool_call_id) toolCallIds.add(toolMsg.tool_call_id);
+		}
+		let backwardIdx = null;
+		for (let i = cutoffIndex - 1; i >= 0; i--) {
+			const msg = messages[i];
+			if (AIMessage.isInstance(msg) && msg.tool_calls) {
+				const aiToolCallIds = new Set(msg.tool_calls.map((tc) => tc.id).filter((id) => id != null));
+				for (const id of toolCallIds) if (aiToolCallIds.has(id)) {
+					backwardIdx = i;
+					break;
+				}
+				if (backwardIdx !== null) break;
+			}
+		}
+		if (backwardIdx === null) return forwardIdx;
+		if (cutoffIndex - backwardIdx > cutoffIndex / 2 && cutoffIndex > 2) return forwardIdx;
+		return backwardIdx;
+	}
+	/**
+	* Determine cutoff index for messages to summarize.
+	* Messages at index < cutoff will be summarized.
+	* Messages at index >= cutoff will be preserved.
+	*
+	* Uses findSafeCutoffPoint to ensure tool call/result pairs stay together.
+	*/
+	function determineCutoffIndex(messages, maxInputTokens) {
+		let rawCutoff;
+		if (keep.type === "messages") {
+			if (messages.length <= keep.value) return 0;
+			rawCutoff = messages.length - keep.value;
+		} else if (keep.type === "tokens" || keep.type === "fraction") {
+			const targetTokenCount = keep.type === "fraction" && maxInputTokens ? Math.floor(maxInputTokens * keep.value) : keep.value;
+			let tokensKept = 0;
+			rawCutoff = 0;
+			for (let i = messages.length - 1; i >= 0; i--) {
+				const msgTokens = countTokensApproximately([messages[i]]);
+				if (tokensKept + msgTokens > targetTokenCount) {
+					rawCutoff = i + 1;
+					break;
+				}
+				tokensKept += msgTokens;
+			}
+		} else return 0;
+		return findSafeCutoffPoint(messages, rawCutoff);
+	}
+	/**
+	* Check if argument truncation should be triggered.
+	*/
+	function shouldTruncateArgs(messages, totalTokens, maxInputTokens) {
+		if (!truncateTrigger) return false;
+		const adjustedTokens = totalTokens * tokenEstimationMultiplier;
+		if (truncateTrigger.type === "messages") return messages.length >= truncateTrigger.value;
+		if (truncateTrigger.type === "tokens") return adjustedTokens >= truncateTrigger.value;
+		if (truncateTrigger.type === "fraction" && maxInputTokens) return adjustedTokens >= Math.floor(maxInputTokens * truncateTrigger.value);
+		return false;
+	}
+	/**
+	* Determine cutoff index for argument truncation.
+	* Uses findSafeCutoffPoint to ensure tool call/result pairs stay together.
+	*/
+	function determineTruncateCutoffIndex(messages, maxInputTokens) {
+		let rawCutoff;
+		if (truncateKeep.type === "messages") {
+			if (messages.length <= truncateKeep.value) return messages.length;
+			rawCutoff = messages.length - truncateKeep.value;
+		} else if (truncateKeep.type === "tokens" || truncateKeep.type === "fraction") {
+			const targetTokenCount = truncateKeep.type === "fraction" && maxInputTokens ? Math.floor(maxInputTokens * truncateKeep.value) : truncateKeep.value;
+			let tokensKept = 0;
+			rawCutoff = 0;
+			for (let i = messages.length - 1; i >= 0; i--) {
+				const msgTokens = countTokensApproximately([messages[i]]);
+				if (tokensKept + msgTokens > targetTokenCount) {
+					rawCutoff = i + 1;
+					break;
+				}
+				tokensKept += msgTokens;
+			}
+		} else return messages.length;
+		return findSafeCutoffPoint(messages, rawCutoff);
+	}
+	/**
+	* Count tokens including system message and tools, matching Python's approach.
+	* This gives a more accurate picture of what actually gets sent to the model.
+	*/
+	function countTotalTokens(messages, systemMessage, tools) {
+		return countTokensApproximately(systemMessage && SystemMessage.isInstance(systemMessage) ? [systemMessage, ...messages] : [...messages], tools && Array.isArray(tools) && tools.length > 0 ? tools : null);
+	}
+	/**
+	* Truncate ToolMessage content so that the total payload fits within the
+	* model's context window. Each ToolMessage gets an equal share of the
+	* remaining token budget after accounting for non-tool messages, system
+	* message, and tool schemas.
+	*
+	* This is critical for conversations where a single AIMessage triggers
+	* many tool calls whose results collectively exceed the context window.
+	* Without this, findSafeCutoffPoint cannot split the AI/Tool group and
+	* summarization would discard everything, causing the model to re-call
+	* the same tools in an infinite loop.
+	*/
+	function compactToolResults(messages, maxInputTokens, systemMessage, tools) {
+		const toolMessageIndices = [];
+		for (let i = 0; i < messages.length; i++) if (ToolMessage.isInstance(messages[i])) toolMessageIndices.push(i);
+		if (toolMessageIndices.length === 0) return {
+			messages,
+			modified: false
+		};
+		const overheadTokens = countTotalTokens(messages.filter((m) => !ToolMessage.isInstance(m)), systemMessage, tools);
+		const adjustedMax = maxInputTokens / tokenEstimationMultiplier;
+		const budgetForTools = Math.max(adjustedMax * .7 - overheadTokens, 1e3);
+		const perToolBudgetChars = Math.floor(budgetForTools / toolMessageIndices.length) * 4;
+		let modified = false;
+		const result = [...messages];
+		for (const idx of toolMessageIndices) {
+			const msg = messages[idx];
+			const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+			if (content.length > perToolBudgetChars) {
+				result[idx] = new ToolMessage({
+					content: content.substring(0, perToolBudgetChars) + "\n...(result truncated)",
+					tool_call_id: msg.tool_call_id,
+					name: msg.name
+				});
+				modified = true;
+			}
+		}
+		return {
+			messages: result,
+			modified
+		};
+	}
+	/**
+	* Truncate large tool arguments in old messages.
+	*/
+	function truncateArgs(messages, maxInputTokens, systemMessage, tools) {
+		if (!shouldTruncateArgs(messages, countTotalTokens(messages, systemMessage, tools), maxInputTokens)) return {
+			messages,
+			modified: false
+		};
+		const cutoffIndex = determineTruncateCutoffIndex(messages, maxInputTokens);
+		if (cutoffIndex >= messages.length) return {
+			messages,
+			modified: false
+		};
+		const truncatedMessages = [];
+		let modified = false;
+		for (let i = 0; i < messages.length; i++) {
+			const msg = messages[i];
+			if (i < cutoffIndex && AIMessage.isInstance(msg) && msg.tool_calls) {
+				const truncatedToolCalls = msg.tool_calls.map((toolCall) => {
+					const args = toolCall.args || {};
+					const truncatedArgs = {};
+					let toolModified = false;
+					for (const [key, value] of Object.entries(args)) if (typeof value === "string" && value.length > maxArgLength && (toolCall.name === "write_file" || toolCall.name === "edit_file")) {
+						truncatedArgs[key] = value.substring(0, 20) + truncationText;
+						toolModified = true;
+					} else truncatedArgs[key] = value;
+					if (toolModified) {
+						modified = true;
+						return {
+							...toolCall,
+							args: truncatedArgs
+						};
+					}
+					return toolCall;
+				});
+				if (modified) {
+					const truncatedMsg = new AIMessage({
+						content: msg.content,
+						tool_calls: truncatedToolCalls,
+						additional_kwargs: msg.additional_kwargs
+					});
+					truncatedMessages.push(truncatedMsg);
+				} else truncatedMessages.push(msg);
+			} else truncatedMessages.push(msg);
+		}
+		return {
+			messages: truncatedMessages,
+			modified
+		};
+	}
+	/**
+	* Filter out previous summary messages.
+	*/
+	function filterSummaryMessages(messages) {
+		return messages.filter((msg) => !isSummaryMessage(msg));
+	}
+	/**
+	* Offload messages to backend.
+	*/
+	async function offloadToBackend(resolvedBackend, messages, state) {
+		const path = getHistoryPath(state);
+		const filteredMessages = filterSummaryMessages(messages);
+		const newSection = `## Summarized at ${(/* @__PURE__ */ new Date()).toISOString()}\n\n${getBufferString(filteredMessages)}\n\n`;
+		let existingContent = "";
+		try {
+			if (resolvedBackend.downloadFiles) {
+				const responses = await resolvedBackend.downloadFiles([path]);
+				if (responses.length > 0 && responses[0].content && !responses[0].error) existingContent = new TextDecoder().decode(responses[0].content);
+			}
+		} catch {}
+		const combinedContent = existingContent + newSection;
+		try {
+			let result;
+			if (existingContent) result = await resolvedBackend.edit(path, existingContent, combinedContent);
+			else result = await resolvedBackend.write(path, combinedContent);
+			if (result.error) {
+				console.warn(`Failed to offload conversation history to ${path}: ${result.error}`);
+				return null;
+			}
+			return path;
+		} catch (e) {
+			console.warn(`Exception offloading conversation history to ${path}:`, e);
+			return null;
+		}
+	}
+	/**
+	* Create summary of messages.
+	*/
+	async function createSummary(messages, chatModel) {
+		let messagesToSummarize = messages;
+		if (countTokensApproximately(messages) > trimTokensToSummarize) {
+			let kept = 0;
+			const trimmedMessages = [];
+			for (let i = messages.length - 1; i >= 0; i--) {
+				const msgTokens = countTokensApproximately([messages[i]]);
+				if (kept + msgTokens > trimTokensToSummarize) break;
+				trimmedMessages.unshift(messages[i]);
+				kept += msgTokens;
+			}
+			messagesToSummarize = trimmedMessages;
+		}
+		const conversation = getBufferString(messagesToSummarize);
+		const prompt = summaryPrompt.replace("{conversation}", conversation);
+		const response = await chatModel.invoke([new HumanMessage({ content: prompt })]);
+		return typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+	}
+	/**
+	* Build the summary message with file path reference.
+	*/
+	function buildSummaryMessage(summary, filePath) {
+		let content;
+		if (filePath) content = `You are in the middle of a conversation that has been summarized.
+
+The full conversation history has been saved to ${filePath} should you need to refer back to it for details.
+
+A condensed summary follows:
+
+<summary>
+${summary}
+</summary>`;
+		else content = `Here is a summary of the conversation to date:\n\n${summary}`;
+		return new HumanMessage({
+			content,
+			additional_kwargs: { lc_source: "summarization" }
+		});
+	}
+	/**
+	* Reconstruct the effective message list based on any previous summarization event.
+	*
+	* After summarization, instead of using all messages from state, we use the summary
+	* message plus messages after the cutoff index. This avoids full state rewrites.
+	*/
+	function getEffectiveMessages(messages, state) {
+		const event = state._summarizationEvent;
+		if (!event) return messages;
+		const result = [event.summaryMessage];
+		result.push(...messages.slice(event.cutoffIndex));
+		return result;
+	}
+	/**
+	* Summarize a set of messages using the given model and build the
+	* summary message + backend offload. Returns the summary message,
+	* the file path, and the state cutoff index.
+	*/
+	async function summarizeMessages(messagesToSummarize, resolvedModel, state, previousCutoffIndex, cutoffIndex) {
+		const filePath = await offloadToBackend(getBackend(state), messagesToSummarize, state);
+		if (filePath === null) console.warn(`[SummarizationMiddleware] Backend offload failed during summarization. Proceeding with summary generation.`);
+		return {
+			summaryMessage: buildSummaryMessage(await createSummary(messagesToSummarize, resolvedModel), filePath),
+			filePath,
+			stateCutoffIndex: previousCutoffIndex != null ? previousCutoffIndex + cutoffIndex - 1 : cutoffIndex
+		};
+	}
+	/**
+	* Check if an error (possibly wrapped in MiddlewareError layers) is a
+	* ContextOverflowError by walking the `cause` chain.
+	*/
+	function isContextOverflow(err) {
+		let cause = err;
+		while (cause != null) {
+			if (ContextOverflowError.isInstance(cause)) return true;
+			cause = typeof cause === "object" && cause !== null && "cause" in cause ? cause.cause : void 0;
+		}
+		return false;
+	}
+	async function performSummarization(request, handler, truncatedMessages, resolvedModel, maxInputTokens) {
+		const cutoffIndex = determineCutoffIndex(truncatedMessages, maxInputTokens);
+		if (cutoffIndex <= 0) return handler({
+			...request,
+			messages: truncatedMessages
+		});
+		const messagesToSummarize = truncatedMessages.slice(0, cutoffIndex);
+		const preservedMessages = truncatedMessages.slice(cutoffIndex);
+		if (preservedMessages.length === 0 && maxInputTokens) {
+			const compact = compactToolResults(truncatedMessages, maxInputTokens, request.systemMessage, request.tools);
+			if (compact.modified) try {
+				return await handler({
+					...request,
+					messages: compact.messages
+				});
+			} catch (err) {
+				if (!isContextOverflow(err)) throw err;
+			}
+		}
+		const previousEvent = request.state._summarizationEvent;
+		const previousCutoffIndex = previousEvent != null ? previousEvent.cutoffIndex : void 0;
+		const { summaryMessage, filePath, stateCutoffIndex } = await summarizeMessages(messagesToSummarize, resolvedModel, request.state, previousCutoffIndex, cutoffIndex);
+		let modifiedMessages = [summaryMessage, ...preservedMessages];
+		const modifiedTokens = countTotalTokens(modifiedMessages, request.systemMessage, request.tools);
+		let finalStateCutoffIndex = stateCutoffIndex;
+		let finalSummaryMessage = summaryMessage;
+		let finalFilePath = filePath;
+		try {
+			await handler({
+				...request,
+				messages: modifiedMessages
+			});
+		} catch (err) {
+			if (!isContextOverflow(err)) throw err;
+			if (maxInputTokens && modifiedTokens > 0) {
+				const observedRatio = maxInputTokens / modifiedTokens;
+				if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
+			}
+			const reSumResult = await summarizeMessages([...messagesToSummarize, ...preservedMessages], resolvedModel, request.state, previousCutoffIndex, truncatedMessages.length);
+			finalSummaryMessage = reSumResult.summaryMessage;
+			finalFilePath = reSumResult.filePath;
+			finalStateCutoffIndex = reSumResult.stateCutoffIndex;
+			modifiedMessages = [reSumResult.summaryMessage];
+			await handler({
+				...request,
+				messages: modifiedMessages
+			});
+		}
+		return new Command({ update: {
+			_summarizationEvent: {
+				cutoffIndex: finalStateCutoffIndex,
+				summaryMessage: finalSummaryMessage,
+				filePath: finalFilePath
+			},
+			_summarizationSessionId: getSessionId(request.state)
+		} });
+	}
+	return createMiddleware({
+		name: "SummarizationMiddleware",
+		stateSchema: SummarizationStateSchema,
+		async wrapModelCall(request, handler) {
+			const effectiveMessages = getEffectiveMessages(request.messages ?? [], request.state);
+			if (effectiveMessages.length === 0) return handler(request);
+			/**
+			* Resolve the chat model and get max input tokens from its profile.
+			*/
+			const resolvedModel = await getChatModel();
+			const maxInputTokens = getMaxInputTokens(resolvedModel);
+			applyModelDefaults(resolvedModel);
+			/**
+			* Step 1: Truncate args if configured
+			*/
+			const { messages: truncatedMessages } = truncateArgs(effectiveMessages, maxInputTokens, request.systemMessage, request.tools);
+			/**
+			* Step 2: Check if summarization should happen.
+			* Count tokens including system message and tools to match what's
+			* actually sent to the model (matching Python implementation).
+			*/
+			const totalTokens = countTotalTokens(truncatedMessages, request.systemMessage, request.tools);
+			/**
+			* If no summarization needed, try passing through.
+			* If the handler throws a ContextOverflowError, fall back to
+			* emergency summarization (matching Python's behavior).
+			*/
+			if (!shouldSummarize(truncatedMessages, totalTokens, maxInputTokens)) try {
+				return await handler({
+					...request,
+					messages: truncatedMessages
+				});
+			} catch (err) {
+				if (!isContextOverflow(err)) throw err;
+				if (maxInputTokens && totalTokens > 0) {
+					const observedRatio = maxInputTokens / totalTokens;
+					if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
+				}
+			}
+			/**
+			* Step 3: Perform summarization
+			*/
+			return performSummarization(request, handler, truncatedMessages, resolvedModel, maxInputTokens);
+		}
+	});
+}
 
 //#endregion
 //#region src/backends/store.ts
@@ -3336,6 +3951,311 @@ var CompositeBackend = class {
 	}
 };
 
+//#endregion
+//#region src/backends/local-shell.ts
+/**
+* LocalShellBackend: Node.js implementation of the filesystem backend with unrestricted local shell execution.
+*
+* This backend extends FilesystemBackend to add shell command execution on the local
+* host system. It provides NO sandboxing or isolation - all operations run directly
+* on the host machine with full system access.
+*
+* @module
+*/
+/**
+* Filesystem backend with unrestricted local shell command execution.
+*
+* This backend extends FilesystemBackend to add shell command execution
+* capabilities. Commands are executed directly on the host system without any
+* sandboxing, process isolation, or security restrictions.
+*
+* **Security Warning:**
+* This backend grants agents BOTH direct filesystem access AND unrestricted
+* shell execution on your local machine. Use with extreme caution and only in
+* appropriate environments.
+*
+* **Appropriate use cases:**
+* - Local development CLIs (coding assistants, development tools)
+* - Personal development environments where you trust the agent's code
+* - CI/CD pipelines with proper secret management
+*
+* **Inappropriate use cases:**
+* - Production environments (e.g., web servers, APIs, multi-tenant systems)
+* - Processing untrusted user input or executing untrusted code
+*
+* Use StateBackend, StoreBackend, or extend BaseSandbox for production.
+*
+* @example
+* ```typescript
+* import { LocalShellBackend } from "@langchain/deepagents";
+*
+* // Create backend with explicit environment
+* const backend = new LocalShellBackend({
+*   rootDir: "/home/user/project",
+*   env: { PATH: "/usr/bin:/bin" },
+* });
+*
+* // Execute shell commands (runs directly on host)
+* const result = await backend.execute("ls -la");
+* console.log(result.output);
+* console.log(result.exitCode);
+*
+* // Use filesystem operations (inherited from FilesystemBackend)
+* const content = await backend.read("/README.md");
+* await backend.write("/output.txt", "Hello world");
+*
+* // Inherit all environment variables
+* const backend2 = new LocalShellBackend({
+*   rootDir: "/home/user/project",
+*   inheritEnv: true,
+* });
+* ```
+*/
+var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
+	#timeout;
+	#maxOutputBytes;
+	#env;
+	#sandboxId;
+	#initialized = false;
+	constructor(options = {}) {
+		const { rootDir, virtualMode = false, timeout = 120, maxOutputBytes = 1e5, env, inheritEnv = false } = options;
+		super({
+			rootDir,
+			virtualMode,
+			maxFileSizeMb: 10
+		});
+		this.#timeout = timeout;
+		this.#maxOutputBytes = maxOutputBytes;
+		const bytes = new Uint8Array(4);
+		crypto.getRandomValues(bytes);
+		this.#sandboxId = `local-${[...bytes].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+		if (inheritEnv) {
+			this.#env = { ...process.env };
+			if (env) Object.assign(this.#env, env);
+		} else this.#env = env ?? {};
+	}
+	/** Unique identifier for this backend instance (format: "local-{random_hex}"). */
+	get id() {
+		return this.#sandboxId;
+	}
+	/** Whether the backend has been initialized and is ready to use. */
+	get isInitialized() {
+		return this.#initialized;
+	}
+	/** Alias for `isInitialized`, matching the standard sandbox interface. */
+	get isRunning() {
+		return this.#initialized;
+	}
+	/**
+	* Initialize the backend by ensuring the rootDir exists.
+	*
+	* Creates the rootDir (and any parent directories) if it does not already
+	* exist. Safe to call on an existing directory. Must be called before
+	* `execute()`, or use the static `LocalShellBackend.create()` factory.
+	*
+	* @throws {SandboxError} If already initialized (`ALREADY_INITIALIZED`)
+	*/
+	async initialize() {
+		if (this.#initialized) throw new SandboxError("Backend is already initialized. Each LocalShellBackend instance can only be initialized once.", "ALREADY_INITIALIZED");
+		await fs.mkdir(this.cwd, { recursive: true });
+		this.#initialized = true;
+	}
+	/**
+	* Mark the backend as no longer running.
+	*
+	* For local shell backends there is no remote resource to tear down,
+	* so this simply flips the `isRunning` / `isInitialized` flag.
+	*/
+	async close() {
+		this.#initialized = false;
+	}
+	/**
+	* Read a file, adapting error messages to the standard sandbox format.
+	*/
+	async read(filePath, offset = 0, limit = 500) {
+		const result = await super.read(filePath, offset, limit);
+		if (typeof result === "string" && result.startsWith("Error reading file") && result.includes("ENOENT")) return `Error: File '${filePath}' not found`;
+		return result;
+	}
+	/**
+	* Edit a file, adapting error messages to the standard sandbox format.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const result = await super.edit(filePath, oldString, newString, replaceAll);
+		if (result.error?.includes("ENOENT")) return {
+			...result,
+			error: `Error: File '${filePath}' not found`
+		};
+		return result;
+	}
+	/**
+	* List directory contents, returning paths relative to rootDir.
+	*/
+	async lsInfo(dirPath) {
+		const results = await super.lsInfo(dirPath);
+		if (this.virtualMode) return results;
+		const cwdPrefix = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+		return results.map((info) => ({
+			...info,
+			path: info.path.startsWith(cwdPrefix) ? info.path.slice(cwdPrefix.length) : info.path
+		}));
+	}
+	/**
+	* Glob matching that returns relative paths and includes directories.
+	*/
+	async globInfo(pattern, searchPath = "/") {
+		if (pattern.startsWith("/")) pattern = pattern.substring(1);
+		const resolvedSearchPath = searchPath === "/" || searchPath === "" ? this.cwd : this.virtualMode ? path.resolve(this.cwd, searchPath.replace(/^\//, "")) : path.resolve(this.cwd, searchPath);
+		try {
+			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return [];
+		} catch {
+			return [];
+		}
+		const formatPath = (rel) => this.virtualMode ? `/${rel}` : rel;
+		const globOpts = {
+			cwd: resolvedSearchPath,
+			absolute: false,
+			dot: true
+		};
+		const [fileMatches, dirMatches] = await Promise.all([fg(pattern, {
+			...globOpts,
+			onlyFiles: true
+		}), fg(pattern, {
+			...globOpts,
+			onlyDirectories: true
+		})]);
+		const statFile = async (match) => {
+			try {
+				const entryStat = await fs.stat(path.join(resolvedSearchPath, match));
+				if (entryStat.isFile()) return {
+					path: formatPath(match),
+					is_dir: false,
+					size: entryStat.size,
+					modified_at: entryStat.mtime.toISOString()
+				};
+			} catch {}
+			return null;
+		};
+		const statDir = async (match) => {
+			try {
+				const entryStat = await fs.stat(path.join(resolvedSearchPath, match));
+				if (entryStat.isDirectory()) return {
+					path: formatPath(match),
+					is_dir: true,
+					size: 0,
+					modified_at: entryStat.mtime.toISOString()
+				};
+			} catch {}
+			return null;
+		};
+		const [fileInfos, dirInfos] = await Promise.all([Promise.all(fileMatches.map(statFile)), Promise.all(dirMatches.map(statDir))]);
+		const results = [...fileInfos, ...dirInfos].filter((info) => info !== null);
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return results;
+	}
+	/**
+	* Execute a shell command directly on the host system.
+	*
+	* Commands are executed directly on your host system using `spawn()`
+	* with `shell: true`. There is NO sandboxing, isolation, or security
+	* restrictions. The command runs with your user's full permissions.
+	*
+	* The command is executed using the system shell with the working directory
+	* set to the backend's rootDir. Stdout and stderr are combined into a single
+	* output stream, with stderr lines prefixed with `[stderr]`.
+	*
+	* @param command - Shell command string to execute
+	* @returns ExecuteResponse containing output, exit code, and truncation flag
+	*/
+	async execute(command) {
+		if (!command || typeof command !== "string") return {
+			output: "Error: Command must be a non-empty string.",
+			exitCode: 1,
+			truncated: false
+		};
+		return new Promise((resolve) => {
+			let stdout = "";
+			let stderr = "";
+			let timedOut = false;
+			const child = cp.spawn(command, {
+				shell: true,
+				env: this.#env,
+				cwd: this.cwd
+			});
+			const timer = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+			}, this.#timeout * 1e3);
+			child.stdout.on("data", (data) => {
+				stdout += data.toString();
+			});
+			child.stderr.on("data", (data) => {
+				stderr += data.toString();
+			});
+			child.on("error", (err) => {
+				clearTimeout(timer);
+				resolve({
+					output: `Error executing command: ${err.message}`,
+					exitCode: 1,
+					truncated: false
+				});
+			});
+			child.on("close", (code, signal) => {
+				clearTimeout(timer);
+				if (timedOut || signal === "SIGTERM") {
+					resolve({
+						output: `Error: Command timed out after ${this.#timeout.toFixed(1)} seconds.`,
+						exitCode: 124,
+						truncated: false
+					});
+					return;
+				}
+				const outputParts = [];
+				if (stdout) outputParts.push(stdout);
+				if (stderr) {
+					const stderrLines = stderr.trim().split("\n");
+					outputParts.push(...stderrLines.map((line) => `[stderr] ${line}`));
+				}
+				let output = outputParts.length > 0 ? outputParts.join("\n") : "<no output>";
+				let truncated = false;
+				if (output.length > this.#maxOutputBytes) {
+					output = output.slice(0, this.#maxOutputBytes);
+					output += `\n\n... Output truncated at ${this.#maxOutputBytes} bytes.`;
+					truncated = true;
+				}
+				const exitCode = code ?? 1;
+				if (exitCode !== 0) output = `${output.trimEnd()}\n\nExit code: ${exitCode}`;
+				resolve({
+					output,
+					exitCode,
+					truncated
+				});
+			});
+		});
+	}
+	/**
+	* Create and initialize a new LocalShellBackend in one step.
+	*
+	* This is the recommended way to create a backend when the rootDir may
+	* not exist yet. It combines construction and initialization (ensuring
+	* rootDir exists) into a single async operation.
+	*
+	* @param options - Configuration options for the backend
+	* @returns An initialized and ready-to-use backend
+	*/
+	static async create(options = {}) {
+		const { initialFiles, ...backendOptions } = options;
+		const backend = new LocalShellBackend(backendOptions);
+		await backend.initialize();
+		if (initialFiles) {
+			const encoder = new TextEncoder();
+			const files = Object.entries(initialFiles).map(([filePath, content]) => [filePath, encoder.encode(content)]);
+			await backend.uploadFiles(files);
+		}
+		return backend;
+	}
+};
+
 //#endregion
 //#region src/backends/sandbox.ts
 /**
@@ -3677,7 +4597,7 @@ const BASE_PROMPT = `In order to complete the objective that the user asks of yo
 * - Todo management (todoListMiddleware)
 * - Filesystem tools (createFilesystemMiddleware)
 * - Subagent delegation (createSubAgentMiddleware)
-* - Conversation summarization (summarizationMiddleware)
+* - Conversation summarization (createSummarizationMiddleware) with backend offloading
 * - Prompt caching (anthropicPromptCachingMiddleware)
 * - Tool call patching (createPatchToolCallsMiddleware)
 * - Human-in-the-loop (humanInTheLoopMiddleware) - optional
@@ -3765,21 +4685,26 @@ function createDeepAgent(params = {}) {
 	/**
 	* Middleware for custom subagents (does NOT include skills from main agent).
 	* Custom subagents must define their own `skills` property to get skills.
+	*
+	* Uses createSummarizationMiddleware (deepagents version) with backend support
+	* and auto-computed defaults from model profile, matching Python's create_deep_agent.
+	* When trigger is not provided, defaults are lazily computed:
+	*   - With model profile: fraction-based (trigger=0.85, keep=0.10)
+	*   - Without profile: fixed (trigger=170k tokens, keep=6 messages)
 	*/
 	const subagentMiddleware = [
 		todoListMiddleware(),
 		createFilesystemMiddleware({ backend: filesystemBackend }),
-		summarizationMiddleware({
+		createSummarizationMiddleware({
 			model,
-			trigger: { tokens: 17e4 },
-			keep: { messages: 6 }
+			backend: filesystemBackend
 		}),
 		anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
 		createPatchToolCallsMiddleware()
 	];
 	/**
 	* Return as DeepAgent with proper DeepAgentTypeConfig
-	* - Response: TResponse (from responseFormat parameter)
+	* - Response: InferStructuredResponse<TResponse> (unwraps ToolStrategy<T>/ProviderStrategy<T> → T)
 	* - State: undefined (state comes from middleware)
 	* - Context: ContextSchema
 	* - Middleware: AllMiddleware (built-in + custom + subagent middleware for state inference)
@@ -3803,10 +4728,9 @@ function createDeepAgent(params = {}) {
 					subagents: processedSubagents,
 					generalPurposeAgent: true
 				}),
-				summarizationMiddleware({
+				createSummarizationMiddleware({
 					model,
-					trigger: { tokens: 17e4 },
-					keep: { messages: 6 }
+					backend: filesystemBackend
 				}),
 				anthropicPromptCachingMiddleware({ unsupportedModelBehavior: "ignore" }),
 				createPatchToolCallsMiddleware()
@@ -3816,7 +4740,7 @@ function createDeepAgent(params = {}) {
 			...interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : [],
 			...customMiddleware
 		],
-		responseFormat,
+		...responseFormat != null && { responseFormat },
 		contextSchema,
 		checkpointer,
 		store,
@@ -4369,5 +5293,5 @@ function listSkills(options) {
 }
 
 //#endregion
-export { BaseSandbox, CompositeBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { BaseSandbox, CompositeBackend, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, LocalShellBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.js.map