deepagents 1.5.1 → 1.6.1

package/dist/index.cjs

@@ -35,6 +35,8 @@ let _langchain_core_messages = require("@langchain/core/messages");
 let zod = require("zod");
 let yaml = require("yaml");
 yaml = __toESM(yaml);
+require("uuid");
+require("@langchain/openai");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_fs = require("node:fs");
@@ -199,14 +201,30 @@ function performStringReplacement(content, oldString, newString, replaceAll) {
 	return [content.split(oldString).join(newString), occurrences];
 }
 /**
-* Validate and normalize a path.
+* Validate and normalize a directory path.
+*
+* Ensures paths are safe to use by preventing directory traversal attacks
+* and enforcing consistent formatting. All paths are normalized to use
+* forward slashes and start with a leading slash.
+*
+* This function is designed for virtual filesystem paths and rejects
+* Windows absolute paths (e.g., C:/..., F:/...) to maintain consistency
+* and prevent path format ambiguity.
 *
 * @param path - Path to validate
 * @returns Normalized path starting with / and ending with /
 * @throws Error if path is invalid
+*
+* @example
+* ```typescript
+* validatePath("foo/bar")  // Returns: "/foo/bar/"
+* validatePath("/./foo//bar")  // Returns: "/foo/bar/"
+* validatePath("../etc/passwd")  // Throws: Path traversal not allowed
+* validatePath("C:\\Users\\file")  // Throws: Windows absolute paths not supported
+* ```
 */
-function validatePath(path$4) {
-	const pathStr = path$4 || "/";
+function validatePath(path) {
+	const pathStr = path || "/";
 	if (!pathStr || pathStr.trim() === "") throw new Error("Path cannot be empty");
 	let normalized = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
 	if (!normalized.endsWith("/")) normalized += "/";
@@ -228,10 +246,10 @@ function validatePath(path$4) {
 * // Returns: "/test.py\n/src/main.py" (sorted by modified_at)
 * ```
 */
-function globSearchFiles(files, pattern, path$4 = "/") {
+function globSearchFiles(files, pattern, path = "/") {
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path$4);
+		normalizedPath = validatePath(path);
 	} catch {
 		return "No files found";
 	}
@@ -261,7 +279,7 @@ function globSearchFiles(files, pattern, path$4 = "/") {
 * (e.g., invalid regex). We deliberately do not raise here to keep backends
 * non-throwing in tool contexts and preserve user-facing error messages.
 */
-function grepMatchesFromFiles(files, pattern, path$4 = null, glob = null) {
+function grepMatchesFromFiles(files, pattern, path = null, glob = null) {
 	let regex;
 	try {
 		regex = new RegExp(pattern);
@@ -270,7 +288,7 @@ function grepMatchesFromFiles(files, pattern, path$4 = null, glob = null) {
 	}
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path$4);
+		normalizedPath = validatePath(path);
 	} catch {
 		return [];
 	}
@@ -323,11 +341,11 @@ var StateBackend = class {
 	* @returns List of FileInfo objects for files and directories directly in the directory.
 	*          Directories have a trailing / in their path and is_dir=true.
 	*/
-	lsInfo(path$4) {
+	lsInfo(path) {
 		const files = this.getFiles();
 		const infos = [];
 		const subdirs = /* @__PURE__ */ new Set();
-		const normalizedPath = path$4.endsWith("/") ? path$4 : path$4 + "/";
+		const normalizedPath = path.endsWith("/") ? path : path + "/";
 		for (const [k, fd] of Object.entries(files)) {
 			if (!k.startsWith(normalizedPath)) continue;
 			const relative = k.substring(normalizedPath.length);
@@ -409,15 +427,15 @@ var StateBackend = class {
 	/**
 	* Structured search results or error string for invalid input.
 	*/
-	grepRaw(pattern, path$4 = "/", glob = null) {
-		return grepMatchesFromFiles(this.getFiles(), pattern, path$4, glob);
+	grepRaw(pattern, path = "/", glob = null) {
+		return grepMatchesFromFiles(this.getFiles(), pattern, path, glob);
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	globInfo(pattern, path$4 = "/") {
+	globInfo(pattern, path = "/") {
 		const files = this.getFiles();
-		const result = globSearchFiles(files, pattern, path$4);
+		const result = globSearchFiles(files, pattern, path);
 		if (result === "No files found") return [];
 		const paths = result.split("\n");
 		const infos = [];
@@ -445,15 +463,15 @@ var StateBackend = class {
 	uploadFiles(files) {
 		const responses = [];
 		const updates = {};
-		for (const [path$4, content] of files) try {
-			updates[path$4] = createFileData(new TextDecoder().decode(content));
+		for (const [path, content] of files) try {
+			updates[path] = createFileData(new TextDecoder().decode(content));
 			responses.push({
-				path: path$4,
+				path,
 				error: null
 			});
 		} catch {
 			responses.push({
-				path: path$4,
+				path,
 				error: "invalid_path"
 			});
 		}
@@ -470,11 +488,11 @@ var StateBackend = class {
 	downloadFiles(paths) {
 		const files = this.getFiles();
 		const responses = [];
-		for (const path$4 of paths) {
-			const fileData = files[path$4];
+		for (const path of paths) {
+			const fileData = files[path];
 			if (!fileData) {
 				responses.push({
-					path: path$4,
+					path,
 					content: null,
 					error: "file_not_found"
 				});
@@ -483,7 +501,7 @@ var StateBackend = class {
 			const contentStr = fileDataToString(fileData);
 			const content = new TextEncoder().encode(contentStr);
 			responses.push({
-				path: path$4,
+				path,
 				content,
 				error: null
 			});
@@ -502,6 +520,74 @@ var StateBackend = class {
 * - Tool result eviction for large outputs
 */
 /**
+* Tools that should be excluded from the large result eviction logic.
+*
+* This array contains tools that should NOT have their results evicted to the filesystem
+* when they exceed token limits. Tools are excluded for different reasons:
+*
+* 1. Tools with built-in truncation (ls, glob, grep):
+*    These tools truncate their own output when it becomes too large. When these tools
+*    produce truncated output due to many matches, it typically indicates the query
+*    needs refinement rather than full result preservation. In such cases, the truncated
+*    matches are potentially more like noise and the LLM should be prompted to narrow
+*    its search criteria instead.
+*
+* 2. Tools with problematic truncation behavior (read_file):
+*    read_file is tricky to handle as the failure mode here is single long lines
+*    (e.g., imagine a jsonl file with very long payloads on each line). If we try to
+*    truncate the result of read_file, the agent may then attempt to re-read the
+*    truncated file using read_file again, which won't help.
+*
+* 3. Tools that never exceed limits (edit_file, write_file):
+*    These tools return minimal confirmation messages and are never expected to produce
+*    output large enough to exceed token limits, so checking them would be unnecessary.
+*/
+const TOOLS_EXCLUDED_FROM_EVICTION = [
+	"ls",
+	"glob",
+	"grep",
+	"read_file",
+	"edit_file",
+	"write_file"
+];
+/**
+* Approximate number of characters per token for truncation calculations.
+* Using 4 chars per token as a conservative approximation (actual ratio varies by content)
+* This errs on the high side to avoid premature eviction of content that might fit.
+*/
+const NUM_CHARS_PER_TOKEN = 4;
+/**
+* Message template for evicted tool results.
+*/
+const TOO_LARGE_TOOL_MSG = `Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
+You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
+You can do this by specifying an offset and limit in the read_file tool call.
+For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
+
+Here is a preview showing the head and tail of the result (lines of the form
+... [N lines truncated] ...
+indicate omitted lines in the middle of the content):
+
+{content_sample}`;
+/**
+* Create a preview of content showing head and tail with truncation marker.
+*
+* @param contentStr - The full content string to preview.
+* @param headLines - Number of lines to show from the start (default: 5).
+* @param tailLines - Number of lines to show from the end (default: 5).
+* @returns Formatted preview string with line numbers.
+*/
+function createContentPreview(contentStr, headLines = 5, tailLines = 5) {
+	const lines = contentStr.split("\n");
+	if (lines.length <= headLines + tailLines) return formatContentWithLineNumbers(lines.map((line) => line.substring(0, 1e3)), 1);
+	const head = lines.slice(0, headLines).map((line) => line.substring(0, 1e3));
+	const tail = lines.slice(-tailLines).map((line) => line.substring(0, 1e3));
+	const headSample = formatContentWithLineNumbers(head, 1);
+	const truncationNotice = `\n... [${lines.length - headLines - tailLines} lines truncated] ...\n`;
+	const tailSample = formatContentWithLineNumbers(tail, lines.length - tailLines + 1);
+	return headSample + truncationNotice + tailSample;
+}
+/**
 * Zod v3 schema for FileData (re-export from backends)
 */
 const FileDataSchema = zod_v4.z.object({
@@ -510,16 +596,26 @@ const FileDataSchema = zod_v4.z.object({
 	modified_at: zod_v4.z.string()
 });
 /**
-* Merge file updates with support for deletions.
+* Reducer for files state that merges file updates with support for deletions.
+* When a file value is null, the file is deleted from state.
+* When a file value is non-null, it is added or updated in state.
+*
+* This reducer enables concurrent updates from parallel subagents by properly
+* merging their file changes instead of requiring LastValue semantics.
+*
+* @param current - The current files record (from state)
+* @param update - The new files record (from a subagent update), with null values for deletions
+* @returns Merged files record with deletions applied
 */
-function fileDataReducer(left, right) {
-	if (left === void 0) {
-		const result$1 = {};
-		for (const [key, value] of Object.entries(right)) if (value !== null) result$1[key] = value;
-		return result$1;
+function fileDataReducer(current, update) {
+	if (update === void 0) return current || {};
+	if (current === void 0) {
+		const result = {};
+		for (const [key, value] of Object.entries(update)) if (value !== null) result[key] = value;
+		return result;
 	}
-	const result = { ...left };
-	for (const [key, value] of Object.entries(right)) if (value === null) delete result[key];
+	const result = { ...current };
+	for (const [key, value] of Object.entries(update)) if (value === null) delete result[key];
 	else result[key] = value;
 	return result;
 }
@@ -528,11 +624,13 @@ function fileDataReducer(left, right) {
 * Defined at module level to ensure the same object identity is used across all agents,
 * preventing "Channel already exists with different type" errors when multiple agents
 * use createFilesystemMiddleware.
+*
+* Uses ReducedValue for files to allow concurrent updates from parallel subagents.
 */
-const FilesystemStateSchema = zod_v4.z.object({ files: zod_v4.z.record(zod_v4.z.string(), FileDataSchema).default({}).meta({ reducer: {
-	fn: fileDataReducer,
-	schema: zod_v4.z.record(zod_v4.z.string(), FileDataSchema.nullable())
-} }) });
+const FilesystemStateSchema = new _langchain_langgraph.StateSchema({ files: new _langchain_langgraph.ReducedValue(zod_v4.z.record(zod_v4.z.string(), FileDataSchema).default(() => ({})), {
+	inputSchema: zod_v4.z.record(zod_v4.z.string(), FileDataSchema.nullable()).optional(),
+	reducer: fileDataReducer
+}) });
 /**
 * Resolve backend from factory or instance.
 *
@@ -543,7 +641,10 @@ function getBackend(backend, stateAndStore) {
 	if (typeof backend === "function") return backend(stateAndStore);
 	return backend;
 }
-const FILESYSTEM_SYSTEM_PROMPT = `You have access to a virtual filesystem. All file paths must start with a /.
+const FILESYSTEM_SYSTEM_PROMPT = `## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
+
+You have access to a filesystem which you can interact with using these tools.
+All file paths must start with a /.
 
 - ls: list files in a directory (requires absolute path)
 - read_file: read a file from the filesystem
@@ -551,31 +652,99 @@ const FILESYSTEM_SYSTEM_PROMPT = `You have access to a virtual filesystem. All f
 - edit_file: edit a file in the filesystem
 - glob: find files matching a pattern (e.g., "**/*.py")
 - grep: search for text within files`;
-const LS_TOOL_DESCRIPTION = "List files and directories in a directory";
-const READ_FILE_TOOL_DESCRIPTION = "Read the contents of a file";
-const WRITE_FILE_TOOL_DESCRIPTION = "Write content to a new file. Returns an error if the file already exists";
-const EDIT_FILE_TOOL_DESCRIPTION = "Edit a file by replacing a specific string with a new string";
-const GLOB_TOOL_DESCRIPTION = "Find files matching a glob pattern (e.g., '**/*.py' for all Python files)";
-const GREP_TOOL_DESCRIPTION = "Search for a regex pattern in files. Returns matching files and line numbers";
-const EXECUTE_TOOL_DESCRIPTION = `Executes a given command in the sandbox environment with proper handling and security measures.
-
+const LS_TOOL_DESCRIPTION = `Lists all files in a directory.
+
+This is useful for exploring the filesystem and finding the right file to read or edit.
+You should almost ALWAYS use this tool before using the read_file or edit_file tools.`;
+const READ_FILE_TOOL_DESCRIPTION = `Reads a file from the filesystem.
+
+Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+Usage:
+- By default, it reads up to 500 lines starting from the beginning of the file
+- **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
+  - First scan: read_file(path, limit=100) to see file structure
+  - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
+  - Only omit limit (read full file) when necessary for editing
+- Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
+- Results are returned using cat -n format, with line numbers starting at 1
+- Lines longer than 10,000 characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
+- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
+- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+- You should ALWAYS make sure a file has been read before editing it.`;
+const WRITE_FILE_TOOL_DESCRIPTION = `Writes to a new file in the filesystem.
+
+Usage:
+- The write_file tool will create a new file.
+- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.`;
+const EDIT_FILE_TOOL_DESCRIPTION = `Performs exact string replacements in files.
+
+Usage:
+- You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
+- When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
+- ALWAYS prefer editing existing files over creating new ones.
+- Only use emojis if the user explicitly requests it.`;
+const GLOB_TOOL_DESCRIPTION = `Find files matching a glob pattern.
+
+Supports standard glob patterns: \`*\` (any characters), \`**\` (any directories), \`?\` (single character).
+Returns a list of absolute file paths that match the pattern.
+
+Examples:
+- \`**/*.py\` - Find all Python files
+- \`*.txt\` - Find all text files in root
+- \`/subdir/**/*.md\` - Find all markdown files under /subdir`;
+const GREP_TOOL_DESCRIPTION = `Search for a text pattern across files.
+
+Searches for literal text (not regex) and returns matching files or content based on output_mode.
+
+Examples:
+- Search all files: \`grep(pattern="TODO")\`
+- Search Python files only: \`grep(pattern="import", glob="*.py")\`
+- Show matching lines: \`grep(pattern="error", output_mode="content")\``;
+const EXECUTE_TOOL_DESCRIPTION = `Executes a shell command in an isolated sandbox environment.
+
+Usage:
+Executes a given command in the sandbox environment with proper handling and security measures.
 Before executing the command, please follow these steps:
 
 1. Directory Verification:
-   - If the command will create new directories or files, first use the ls tool to verify the parent directory exists
+   - If the command will create new directories or files, first use the ls tool to verify the parent directory exists and is the correct location
+   - For example, before running "mkdir foo/bar", first use ls to check that "foo" exists and is the intended parent directory
 
 2. Command Execution:
-   - Always quote file paths that contain spaces with double quotes
-   - Commands run in an isolated sandbox environment
-   - Returns combined stdout/stderr output with exit code
+   - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
+   - Examples of proper quoting:
+     - cd "/Users/name/My Documents" (correct)
+     - cd /Users/name/My Documents (incorrect - will fail)
+     - python "/path/with spaces/script.py" (correct)
+     - python /path/with spaces/script.py (incorrect - will fail)
+   - After ensuring proper quoting, execute the command
+   - Capture the output of the command
 
 Usage notes:
-  - The command parameter is required
+  - Commands run in an isolated sandbox environment
+  - Returns combined stdout/stderr output with exit code
   - If the output is very large, it may be truncated
-  - IMPORTANT: Avoid using search commands like find and grep. Use the grep, glob tools instead.
-  - Avoid read tools like cat, head, tail - use read_file instead.
-  - Use '&&' to chain dependent commands, ';' for independent commands
-  - Try to use absolute paths to avoid cd`;
+  - VERY IMPORTANT: You MUST avoid using search commands like find and grep. Instead use the grep, glob tools to search. You MUST avoid read tools like cat, head, tail, and use read_file to read files.
+  - When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines are ok in quoted strings)
+    - Use '&&' when commands depend on each other (e.g., "mkdir dir && cd dir")
+    - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
+  - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of cd
+
+Examples:
+  Good examples:
+    - execute(command="pytest /foo/bar/tests")
+    - execute(command="python /path/to/script.py")
+    - execute(command="npm install && npm test")
+
+  Bad examples (avoid these):
+    - execute(command="cd /foo/bar && pytest tests")  # Use absolute path instead
+    - execute(command="cat file.txt")  # Use read_file tool instead
+    - execute(command="find . -name '*.py'")  # Use glob tool instead
+    - execute(command="grep -r 'pattern' .")  # Use grep tool instead
+
+Note: This tool is only available if the backend supports execution (SandboxBackendProtocol).
+If execution is not supported, the tool will return an error message.`;
 const EXECUTION_SYSTEM_PROMPT = `## Execute Tool \`execute\`
 
 You have access to an \`execute\` tool for running shell commands in a sandboxed environment.
@@ -592,9 +761,9 @@ function createLsTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const path$4 = input.path || "/";
-		const infos = await resolvedBackend.lsInfo(path$4);
-		if (infos.length === 0) return `No files found in ${path$4}`;
+		const path = input.path || "/";
+		const infos = await resolvedBackend.lsInfo(path);
+		if (infos.length === 0) return `No files found in ${path}`;
 		const lines = [];
 		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
 		else {
@@ -708,8 +877,8 @@ function createGlobTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { pattern, path: path$4 = "/" } = input;
-		const infos = await resolvedBackend.globInfo(pattern, path$4);
+		const { pattern, path = "/" } = input;
+		const infos = await resolvedBackend.globInfo(pattern, path);
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		return infos.map((info) => info.path).join("\n");
 	}, {
@@ -731,8 +900,8 @@ function createGrepTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { pattern, path: path$4 = "/", glob = null } = input;
-		const result = await resolvedBackend.grepRaw(pattern, path$4, glob);
+		const { pattern, path = "/", glob = null } = input;
+		const result = await resolvedBackend.grepRaw(pattern, path, glob);
 		if (typeof result === "string") return result;
 		if (result.length === 0) return `No matches found for pattern '${pattern}'`;
 		const lines = [];
@@ -815,10 +984,13 @@ function createFilesystemMiddleware(options = {}) {
 				systemPrompt: newSystemPrompt
 			});
 		},
-		wrapToolCall: toolTokenLimitBeforeEvict ? async (request, handler) => {
+		wrapToolCall: async (request, handler) => {
+			if (!toolTokenLimitBeforeEvict) return handler(request);
+			const toolName = request.toolCall?.name;
+			if (toolName && TOOLS_EXCLUDED_FROM_EVICTION.includes(toolName)) return handler(request);
 			const result = await handler(request);
-			async function processToolMessage(msg) {
-				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * 4) {
+			async function processToolMessage(msg, toolTokenLimitBeforeEvict) {
+				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * NUM_CHARS_PER_TOKEN) {
 					const resolvedBackend = getBackend(backend, {
 						state: request.state || {},
 						store: request.config?.store
@@ -829,9 +1001,10 @@ function createFilesystemMiddleware(options = {}) {
 						message: msg,
 						filesUpdate: null
 					};
+					const contentSample = createContentPreview(msg.content);
 					return {
 						message: new langchain.ToolMessage({
-							content: `Tool result too large (${Math.round(msg.content.length / 4)} tokens). Content saved to ${evictPath}`,
+							content: TOO_LARGE_TOOL_MSG.replace("{tool_call_id}", msg.tool_call_id).replace("{file_path}", evictPath).replace("{content_sample}", contentSample),
 							tool_call_id: msg.tool_call_id,
 							name: msg.name
 						}),
@@ -844,7 +1017,7 @@ function createFilesystemMiddleware(options = {}) {
 				};
 			}
 			if (langchain.ToolMessage.isInstance(result)) {
-				const processed = await processToolMessage(result);
+				const processed = await processToolMessage(result, toolTokenLimitBeforeEvict);
 				if (processed.filesUpdate) return new _langchain_langgraph.Command({ update: {
 					files: processed.filesUpdate,
 					messages: [processed.message]
@@ -855,10 +1028,10 @@ function createFilesystemMiddleware(options = {}) {
 				const update = result.update;
 				if (!update?.messages) return result;
 				let hasLargeResults = false;
-				const accumulatedFiles = { ...update.files || {} };
+				const accumulatedFiles = update.files ? { ...update.files } : {};
 				const processedMessages = [];
 				for (const msg of update.messages) if (langchain.ToolMessage.isInstance(msg)) {
-					const processed = await processToolMessage(msg);
+					const processed = await processToolMessage(msg, toolTokenLimitBeforeEvict);
 					processedMessages.push(processed.message);
 					if (processed.filesUpdate) {
 						hasLargeResults = true;
@@ -872,7 +1045,7 @@ function createFilesystemMiddleware(options = {}) {
 				} });
 			}
 			return result;
-		} : void 0
+		}
 	});
 }
 
@@ -882,8 +1055,7 @@ const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the use
 const EXCLUDED_STATE_KEYS = [
 	"messages",
 	"todos",
-	"structuredResponse",
-	"files"
+	"structuredResponse"
 ];
 const DEFAULT_GENERAL_PURPOSE_DESCRIPTION = "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
 function getTaskToolDescription(subagentDescriptions) {
@@ -1322,7 +1494,7 @@ const MEMORY_SYSTEM_PROMPT = `<agent_memory>
 function formatMemoryContents(contents, sources) {
 	if (Object.keys(contents).length === 0) return "(No memory loaded)";
 	const sections = [];
-	for (const path$4 of sources) if (contents[path$4]) sections.push(`${path$4}\n${contents[path$4]}`);
+	for (const path of sources) if (contents[path]) sections.push(`${path}\n${contents[path]}`);
 	if (sections.length === 0) return "(No memory loaded)";
 	return sections.join("\n\n");
 }
@@ -1333,18 +1505,18 @@ function formatMemoryContents(contents, sources) {
 * @param path - Path to the AGENTS.md file.
 * @returns File content if found, null otherwise.
 */
-async function loadMemoryFromBackend(backend, path$4) {
+async function loadMemoryFromBackend(backend, path) {
 	if (!backend.downloadFiles) {
-		const content = await backend.read(path$4);
+		const content = await backend.read(path);
 		if (content.startsWith("Error:")) return null;
 		return content;
 	}
-	const results = await backend.downloadFiles([path$4]);
-	if (results.length !== 1) throw new Error(`Expected 1 response for path ${path$4}, got ${results.length}`);
+	const results = await backend.downloadFiles([path]);
+	if (results.length !== 1) throw new Error(`Expected 1 response for path ${path}, got ${results.length}`);
 	const response = results[0];
 	if (response.error != null) {
 		if (response.error === "file_not_found") return null;
-		throw new Error(`Failed to download ${path$4}: ${response.error}`);
+		throw new Error(`Failed to download ${path}: ${response.error}`);
 	}
 	if (response.content != null) return new TextDecoder().decode(response.content);
 	return null;
@@ -1374,7 +1546,7 @@ function createMemoryMiddleware(options) {
 	/**
 	* Resolve backend from instance or factory.
 	*/
-	function getBackend$1(state) {
+	function getBackend(state) {
 		if (typeof backend === "function") return backend({ state });
 		return backend;
 	}
@@ -1383,13 +1555,13 @@ function createMemoryMiddleware(options) {
 		stateSchema: MemoryStateSchema,
 		async beforeAgent(state) {
 			if ("memoryContents" in state && state.memoryContents != null) return;
-			const resolvedBackend = getBackend$1(state);
+			const resolvedBackend = getBackend(state);
 			const contents = {};
-			for (const path$4 of sources) try {
-				const content = await loadMemoryFromBackend(resolvedBackend, path$4);
-				if (content) contents[path$4] = content;
+			for (const path of sources) try {
+				const content = await loadMemoryFromBackend(resolvedBackend, path);
+				if (content) contents[path] = content;
 			} catch (error) {
-				console.debug(`Failed to load memory from ${path$4}:`, error);
+				console.debug(`Failed to load memory from ${path}:`, error);
 			}
 			return { memoryContents: contents };
 		},
@@ -1452,9 +1624,9 @@ const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
 /**
-* State schema for skills middleware.
+* Zod schema for a single skill metadata entry.
 */
-const SkillsStateSchema = zod.z.object({ skillsMetadata: zod.z.array(zod.z.object({
+const SkillMetadataEntrySchema = zod.z.object({
 	name: zod.z.string(),
 	description: zod.z.string(),
 	path: zod.z.string(),
@@ -1462,7 +1634,31 @@ const SkillsStateSchema = zod.z.object({ skillsMetadata: zod.z.array(zod.z.objec
 	compatibility: zod.z.string().nullable().optional(),
 	metadata: zod.z.record(zod.z.string(), zod.z.string()).optional(),
 	allowedTools: zod.z.array(zod.z.string()).optional()
-})).optional() });
+});
+/**
+* Reducer for skillsMetadata that merges arrays from parallel subagents.
+* Skills are deduplicated by name, with later values overriding earlier ones.
+*
+* @param current - The current skillsMetadata array (from state)
+* @param update - The new skillsMetadata array (from a subagent update)
+* @returns Merged array with duplicates resolved by name (later values win)
+*/
+function skillsMetadataReducer(current, update) {
+	if (!update || update.length === 0) return current || [];
+	if (!current || current.length === 0) return update;
+	const merged = /* @__PURE__ */ new Map();
+	for (const skill of current) merged.set(skill.name, skill);
+	for (const skill of update) merged.set(skill.name, skill);
+	return Array.from(merged.values());
+}
+/**
+* State schema for skills middleware.
+* Uses ReducedValue for skillsMetadata to allow concurrent updates from parallel subagents.
+*/
+const SkillsStateSchema = new _langchain_langgraph.StateSchema({ skillsMetadata: new _langchain_langgraph.ReducedValue(zod.z.array(SkillMetadataEntrySchema).default(() => []), {
+	inputSchema: zod.z.array(SkillMetadataEntrySchema).optional(),
+	reducer: skillsMetadataReducer
+}) });
 /**
 * Skills System Documentation prompt template.
 */
@@ -1589,7 +1785,7 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 */
 async function listSkillsFromBackend(backend, sourcePath) {
 	const skills = [];
-	const normalizedPath = sourcePath.endsWith("/") ? sourcePath : `${sourcePath}/`;
+	const normalizedPath = sourcePath.endsWith("/") || sourcePath.endsWith("\\") ? sourcePath : `${sourcePath}/`;
 	let fileInfos;
 	try {
 		fileInfos = await backend.lsInfo(normalizedPath);
@@ -1597,7 +1793,7 @@ async function listSkillsFromBackend(backend, sourcePath) {
 		return [];
 	}
 	const entries = fileInfos.map((info) => ({
-		name: info.path.replace(/\/$/, "").split("/").pop() || "",
+		name: info.path.replace(/[/\\]$/, "").split(/[/\\]/).pop() || "",
 		type: info.is_dir ? "directory" : "file"
 	}));
 	for (const entry of entries) {
@@ -1622,21 +1818,29 @@ async function listSkillsFromBackend(backend, sourcePath) {
 }
 /**
 * Format skills locations for display in system prompt.
+* Shows priority indicator for the last source (highest priority).
 */
 function formatSkillsLocations(sources) {
 	if (sources.length === 0) return "**Skills Sources:** None configured";
-	const lines = ["**Skills Sources:**"];
-	for (const source of sources) lines.push(`- \`${source}\``);
+	const lines = [];
+	for (let i = 0; i < sources.length; i++) {
+		const sourcePath = sources[i];
+		const name = sourcePath.replace(/[/\\]$/, "").split(/[/\\]/).filter(Boolean).pop()?.replace(/^./, (c) => c.toUpperCase()) || "Skills";
+		const suffix = i === sources.length - 1 ? " (higher priority)" : "";
+		lines.push(`**${name} Skills**: \`${sourcePath}\`${suffix}`);
+	}
 	return lines.join("\n");
 }
 /**
 * Format skills metadata for display in system prompt.
+* Shows allowed tools for each skill if specified.
 */
 function formatSkillsList(skills, sources) {
-	if (skills.length === 0) return `(No skills available yet. Skills can be created in ${sources.join(" or ")})`;
+	if (skills.length === 0) return `(No skills available yet. You can create skills in ${sources.map((s) => `\`${s}\``).join(" or ")})`;
 	const lines = [];
 	for (const skill of skills) {
 		lines.push(`- **${skill.name}**: ${skill.description}`);
+		if (skill.allowedTools && skill.allowedTools.length > 0) lines.push(`  → Allowed tools: ${skill.allowedTools.join(", ")}`);
 		lines.push(`  → Read \`${skill.path}\` for full instructions`);
 	}
 	return lines.join("\n");
@@ -1666,7 +1870,7 @@ function createSkillsMiddleware(options) {
 	/**
 	* Resolve backend from instance or factory.
 	*/
-	function getBackend$1(state) {
+	function getBackend(state) {
 		if (typeof backend === "function") return backend({ state });
 		return backend;
 	}
@@ -1679,7 +1883,7 @@ function createSkillsMiddleware(options) {
 				loadedSkills = state.skillsMetadata;
 				return;
 			}
-			const resolvedBackend = getBackend$1(state);
+			const resolvedBackend = getBackend(state);
 			const allSkills = /* @__PURE__ */ new Map();
 			for (const sourcePath of sources) try {
 				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
@@ -1705,6 +1909,62 @@ function createSkillsMiddleware(options) {
 	});
 }
 
+//#endregion
+//#region src/middleware/utils.ts
+/**
+* Utility functions for middleware.
+*
+* This module provides shared helpers used across middleware implementations.
+*/
+
+//#endregion
+//#region src/middleware/summarization.ts
+/**
+* Summarization middleware with backend support for conversation history offloading.
+*
+* This module extends the base LangChain summarization middleware with additional
+* backend-based features for persisting conversation history before summarization.
+*
+* ## Usage
+*
+* ```typescript
+* import { createSummarizationMiddleware } from "@anthropic/deepagents";
+* import { FilesystemBackend } from "@anthropic/deepagents";
+*
+* const backend = new FilesystemBackend({ rootDir: "/data" });
+*
+* const middleware = createSummarizationMiddleware({
+*   model: "gpt-4o-mini",
+*   backend,
+*   trigger: { type: "fraction", value: 0.85 },
+*   keep: { type: "fraction", value: 0.10 },
+* });
+*
+* const agent = createDeepAgent({ middleware: [middleware] });
+* ```
+*
+* ## Storage
+*
+* Offloaded messages are stored as markdown at `/conversation_history/{thread_id}.md`.
+*
+* Each summarization event appends a new section to this file, creating a running log
+* of all evicted messages.
+*
+* ## Relationship to LangChain Summarization Middleware
+*
+* The base `summarizationMiddleware` from `langchain` provides core summarization
+* functionality. This middleware adds:
+* - Backend-based conversation history offloading
+* - Tool argument truncation for old messages
+*
+* For simple use cases without backend offloading, use `summarizationMiddleware`
+* from `langchain` directly.
+*/
+/**
+* State schema for summarization middleware.
+*/
+const SummarizationStateSchema = zod.z.object({ _summarizationSessionId: zod.z.string().optional() });
+
 //#endregion
 //#region src/backends/store.ts
 /**
@@ -1806,13 +2066,13 @@ var StoreBackend = class {
 	* @returns List of FileInfo objects for files and directories directly in the directory.
 	*          Directories have a trailing / in their path and is_dir=true.
 	*/
-	async lsInfo(path$4) {
+	async lsInfo(path) {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
 		const infos = [];
 		const subdirs = /* @__PURE__ */ new Set();
-		const normalizedPath = path$4.endsWith("/") ? path$4 : path$4 + "/";
+		const normalizedPath = path.endsWith("/") ? path : path + "/";
 		for (const item of items) {
 			const itemKey = String(item.key);
 			if (!itemKey.startsWith(normalizedPath)) continue;
@@ -1917,7 +2177,7 @@ var StoreBackend = class {
 	/**
 	* Structured search results or error string for invalid input.
 	*/
-	async grepRaw(pattern, path$4 = "/", glob = null) {
+	async grepRaw(pattern, path = "/", glob = null) {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
@@ -1927,12 +2187,12 @@ var StoreBackend = class {
 		} catch {
 			continue;
 		}
-		return grepMatchesFromFiles(files, pattern, path$4, glob);
+		return grepMatchesFromFiles(files, pattern, path, glob);
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, path$4 = "/") {
+	async globInfo(pattern, path = "/") {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
@@ -1942,7 +2202,7 @@ var StoreBackend = class {
 		} catch {
 			continue;
 		}
-		const result = globSearchFiles(files, pattern, path$4);
+		const result = globSearchFiles(files, pattern, path);
 		if (result === "No files found") return [];
 		const paths = result.split("\n");
 		const infos = [];
@@ -1968,17 +2228,17 @@ var StoreBackend = class {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const responses = [];
-		for (const [path$4, content] of files) try {
+		for (const [path, content] of files) try {
 			const fileData = createFileData(new TextDecoder().decode(content));
 			const storeValue = this.convertFileDataToStoreValue(fileData);
-			await store.put(namespace, path$4, storeValue);
+			await store.put(namespace, path, storeValue);
 			responses.push({
-				path: path$4,
+				path,
 				error: null
 			});
 		} catch {
 			responses.push({
-				path: path$4,
+				path,
 				error: "invalid_path"
 			});
 		}
@@ -1994,11 +2254,11 @@ var StoreBackend = class {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const responses = [];
-		for (const path$4 of paths) try {
-			const item = await store.get(namespace, path$4);
+		for (const path of paths) try {
+			const item = await store.get(namespace, path);
 			if (!item) {
 				responses.push({
-					path: path$4,
+					path,
 					content: null,
 					error: "file_not_found"
 				});
@@ -2007,13 +2267,13 @@ var StoreBackend = class {
 			const contentStr = fileDataToString(this.convertStoreItemToFileData(item));
 			const content = new TextEncoder().encode(contentStr);
 			responses.push({
-				path: path$4,
+				path,
 				content,
 				error: null
 			});
 		} catch {
 			responses.push({
-				path: path$4,
+				path,
 				content: null,
 				error: "file_not_found"
 			});
@@ -2574,9 +2834,9 @@ var CompositeBackend = class {
 	* @returns List of FileInfo objects with route prefixes added, for files and directories
 	*          directly in the directory. Directories have a trailing / in their path and is_dir=true.
 	*/
-	async lsInfo(path$4) {
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const suffix = path$4.substring(routePrefix.length);
+	async lsInfo(path) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const suffix = path.substring(routePrefix.length);
 			const searchPath = suffix ? "/" + suffix : "/";
 			const infos = await backend.lsInfo(searchPath);
 			const prefixed = [];
@@ -2586,9 +2846,9 @@ var CompositeBackend = class {
 			});
 			return prefixed;
 		}
-		if (path$4 === "/") {
+		if (path === "/") {
 			const results = [];
-			const defaultInfos = await this.default.lsInfo(path$4);
+			const defaultInfos = await this.default.lsInfo(path);
 			results.push(...defaultInfos);
 			for (const [routePrefix] of this.sortedRoutes) results.push({
 				path: routePrefix,
@@ -2599,7 +2859,7 @@ var CompositeBackend = class {
 			results.sort((a, b) => a.path.localeCompare(b.path));
 			return results;
 		}
-		return await this.default.lsInfo(path$4);
+		return await this.default.lsInfo(path);
 	}
 	/**
 	* Read file content, routing to appropriate backend.
@@ -2626,9 +2886,9 @@ var CompositeBackend = class {
 	/**
 	* Structured search results or error string for invalid input.
 	*/
-	async grepRaw(pattern, path$4 = "/", glob = null) {
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const searchPath = path$4.substring(routePrefix.length - 1);
+	async grepRaw(pattern, path = "/", glob = null) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path.substring(routePrefix.length - 1);
 			const raw = await backend.grepRaw(pattern, searchPath || "/", glob);
 			if (typeof raw === "string") return raw;
 			return raw.map((m) => ({
@@ -2637,7 +2897,7 @@ var CompositeBackend = class {
 			}));
 		}
 		const allMatches = [];
-		const rawDefault = await this.default.grepRaw(pattern, path$4, glob);
+		const rawDefault = await this.default.grepRaw(pattern, path, glob);
 		if (typeof rawDefault === "string") return rawDefault;
 		allMatches.push(...rawDefault);
 		for (const [routePrefix, backend] of Object.entries(this.routes)) {
@@ -2653,16 +2913,16 @@ var CompositeBackend = class {
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, path$4 = "/") {
+	async globInfo(pattern, path = "/") {
 		const results = [];
-		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
-			const searchPath = path$4.substring(routePrefix.length - 1);
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path.substring(routePrefix.length - 1);
 			return (await backend.globInfo(pattern, searchPath || "/")).map((fi) => ({
 				...fi,
 				path: routePrefix.slice(0, -1) + fi.path
 			}));
 		}
-		const defaultInfos = await this.default.globInfo(pattern, path$4);
+		const defaultInfos = await this.default.globInfo(pattern, path);
 		results.push(...defaultInfos);
 		for (const [routePrefix, backend] of Object.entries(this.routes)) {
 			const infos = await backend.globInfo(pattern, "/");
@@ -2717,11 +2977,11 @@ var CompositeBackend = class {
 	* @returns List of FileUploadResponse objects, one per input file
 	*/
 	async uploadFiles(files) {
-		const results = new Array(files.length).fill(null);
+		const results = Array.from({ length: files.length }, () => null);
 		const batchesByBackend = /* @__PURE__ */ new Map();
 		for (let idx = 0; idx < files.length; idx++) {
-			const [path$4, content] = files[idx];
-			const [backend, strippedPath] = this.getBackendAndKey(path$4);
+			const [path, content] = files[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path);
 			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
 			batchesByBackend.get(backend).push({
 				idx,
@@ -2750,11 +3010,11 @@ var CompositeBackend = class {
 	* @returns List of FileDownloadResponse objects, one per input path
 	*/
 	async downloadFiles(paths) {
-		const results = new Array(paths.length).fill(null);
+		const results = Array.from({ length: paths.length }, () => null);
 		const batchesByBackend = /* @__PURE__ */ new Map();
 		for (let idx = 0; idx < paths.length; idx++) {
-			const path$4 = paths[idx];
-			const [backend, strippedPath] = this.getBackendAndKey(path$4);
+			const path = paths[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path);
 			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
 			batchesByBackend.get(backend).push({
 				idx,
@@ -3037,8 +3297,8 @@ var BaseSandbox = class {
 	* @param path - Absolute path to directory
 	* @returns List of FileInfo objects for files and directories directly in the directory.
 	*/
-	async lsInfo(path$4) {
-		const command = buildLsCommand(path$4);
+	async lsInfo(path) {
+		const command = buildLsCommand(path);
 		const result = await this.execute(command);
 		if (result.exitCode !== 0) return [];
 		const infos = [];
@@ -3093,8 +3353,8 @@ var BaseSandbox = class {
 	/**
 	* Structured search results or error string for invalid input.
 	*/
-	async grepRaw(pattern, path$4 = "/", glob = null) {
-		const command = buildGrepCommand(pattern, path$4, glob);
+	async grepRaw(pattern, path = "/", glob = null) {
+		const command = buildGrepCommand(pattern, path, glob);
 		const result = await this.execute(command);
 		if (result.exitCode === 1) {
 			if (result.output.includes("Invalid regex:")) return result.output.trim();
@@ -3114,8 +3374,8 @@ var BaseSandbox = class {
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, path$4 = "/") {
-		const command = buildGlobCommand(path$4, pattern);
+	async globInfo(pattern, path = "/") {
+		const command = buildGlobCommand(path, pattern);
 		const result = await this.execute(command);
 		const infos = [];
 		const lines = result.output.trim().split("\n").filter(Boolean);
@@ -3361,6 +3621,30 @@ function createSettings(options = {}) {
 * and injects it into the system prompt. Memory is loaded from:
 * - User memory: ~/.deepagents/{agent_name}/agent.md
 * - Project memory: {project_root}/.deepagents/agent.md
+*
+* @deprecated Use `createMemoryMiddleware` from `./memory.js` instead.
+* This middleware uses direct filesystem access (Node.js fs module) which is not
+* portable across backends. The `createMemoryMiddleware` function uses the
+* `BackendProtocol` abstraction and follows the AGENTS.md specification.
+*
+* Migration example:
+* ```typescript
+* // Before (deprecated):
+* import { createAgentMemoryMiddleware } from "./agent-memory.js";
+* const middleware = createAgentMemoryMiddleware({ settings, assistantId });
+*
+* // After (recommended):
+* import { createMemoryMiddleware } from "./memory.js";
+* import { FilesystemBackend } from "../backends/filesystem.js";
+*
+* const middleware = createMemoryMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: [
+*     `~/.deepagents/${assistantId}/AGENTS.md`,
+*     `${projectRoot}/.deepagents/AGENTS.md`,
+*   ],
+* });
+* ```
 */
 /**
 * State schema for agent memory middleware.
@@ -3506,6 +3790,9 @@ write_file '{project_deepagents_dir}/agent.md' ...  # Create project memory file
 *
 * @param options - Configuration options
 * @returns AgentMiddleware for memory loading and injection
+*
+* @deprecated Use `createMemoryMiddleware` from `./memory.js` instead.
+* This function uses direct filesystem access which limits portability.
 */
 function createAgentMemoryMiddleware(options) {
 	const { settings, assistantId, systemPromptTemplate } = options;