deepagents 1.8.4 → 1.9.0-alpha.0

package/dist/index.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -7,16 +7,12 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
 	}
 	return to;
 };
@@ -24,7 +20,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-
 //#endregion
 let langchain = require("langchain");
 let _langchain_core_runnables = require("@langchain/core/runnables");
@@ -33,11 +28,12 @@ let zod_v4 = require("zod/v4");
 let micromatch = require("micromatch");
 micromatch = __toESM(micromatch);
 let path = require("path");
+path = __toESM(path);
 let _langchain_core_messages = require("@langchain/core/messages");
 let zod = require("zod");
 let yaml = require("yaml");
 yaml = __toESM(yaml);
-let uuid = require("uuid");
+let _langchain_langgraph_sdk = require("@langchain/langgraph-sdk");
 let _langchain_core_errors = require("@langchain/core/errors");
 let langchain_chat_models_universal = require("langchain/chat_models/universal");
 let node_fs_promises = require("node:fs/promises");
@@ -50,18 +46,30 @@ let node_child_process = require("node:child_process");
 node_child_process = __toESM(node_child_process);
 let fast_glob = require("fast-glob");
 fast_glob = __toESM(fast_glob);
+let langsmith_experimental_sandbox = require("langsmith/experimental/sandbox");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-
 //#region src/backends/protocol.ts
 /**
 * Type guard to check if a backend supports execution.
 *
 * @param backend - Backend instance to check
-* @returns True if the backend implements SandboxBackendProtocol
+* @returns True if the backend implements SandboxBackendProtocolV2
 */
 function isSandboxBackend(backend) {
-	return typeof backend.execute === "function" && typeof backend.id === "string";
+	return backend != null && typeof backend === "object" && typeof backend.execute === "function" && typeof backend.id === "string" && backend.id !== "";
+}
+/**
+* Type guard to check if a backend is a sandbox protocol (v1 or v2).
+*
+* Checks for the presence of `execute` function and `id` string,
+* which are the defining features of sandbox protocols.
+*
+* @param backend - Backend instance to check
+* @returns True if the backend implements sandbox protocol (v1 or v2)
+*/
+function isSandboxProtocol(backend) {
+	return backend != null && typeof backend === "object" && typeof backend.execute === "function" && typeof backend.id === "string" && backend.id !== "";
 }
 const SANDBOX_ERROR_SYMBOL = Symbol.for("sandbox.error");
 /**
@@ -112,7 +120,6 @@ var SandboxError = class SandboxError extends Error {
 		return typeof error === "object" && error !== null && error[SANDBOX_ERROR_SYMBOL] === true;
 	}
 };
-
 //#endregion
 //#region src/backends/utils.ts
 /**
@@ -124,9 +131,21 @@ var SandboxError = class SandboxError extends Error {
 */
 const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
 const MAX_LINE_LENGTH = 1e4;
-const LINE_NUMBER_WIDTH = 6;
 const TOOL_RESULT_TOKEN_LIMIT = 2e4;
 const TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]";
+const MIME_TYPES = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".svg": "image/svg+xml",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".pdf": "application/pdf"
+};
 /**
 * Sanitize tool_call_id to prevent path traversal and separator issues.
 *
@@ -154,17 +173,17 @@ function formatContentWithLineNumbers(content, startLine = 1) {
 	for (let i = 0; i < lines.length; i++) {
 		const line = lines[i];
 		const lineNum = i + startLine;
-		if (line.length <= MAX_LINE_LENGTH) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${line}`);
+		if (line.length <= 1e4) resultLines.push(`${lineNum.toString().padStart(6)}\t${line}`);
 		else {
 			const numChunks = Math.ceil(line.length / MAX_LINE_LENGTH);
 			for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
 				const start = chunkIdx * MAX_LINE_LENGTH;
 				const end = Math.min(start + MAX_LINE_LENGTH, line.length);
 				const chunk = line.substring(start, end);
-				if (chunkIdx === 0) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+				if (chunkIdx === 0) resultLines.push(`${lineNum.toString().padStart(6)}\t${chunk}`);
 				else {
 					const continuationMarker = `${lineNum}.${chunkIdx}`;
-					resultLines.push(`${continuationMarker.padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+					resultLines.push(`${continuationMarker.padStart(6)}\t${chunk}`);
 				}
 			}
 		}
@@ -188,20 +207,50 @@ function checkEmptyContent(content) {
 * @returns Content as string with lines joined by newlines
 */
 function fileDataToString(fileData) {
-	return fileData.content.join("\n");
+	if (Array.isArray(fileData.content)) return fileData.content.join("\n");
+	if (typeof fileData.content === "string") return fileData.content;
+	throw new Error("Cannot convert binary FileData to string");
+}
+/**
+* Type guard to check if FileData contains binary content (Uint8Array).
+*
+* @param data - FileData to check
+* @returns True if the content is a Uint8Array (binary)
+*/
+function isFileDataBinary(data) {
+	return ArrayBuffer.isView(data.content);
 }
 /**
-* Create a FileData object with timestamps.
+* Create a FileData object.
 *
-* @param content - File content as string
-* @param createdAt - Optional creation timestamp (ISO format)
-* @returns FileData object with content and timestamps
+* Defaults to v2 format (content as single string). Pass `fileFormat: "v1"` for
+* backward compatibility with older readers during a rolling deployment.
+* Binary content (Uint8Array) is only supported with v2.
+*
+* @param content - File content as a string or binary Uint8Array (v2 only)
+* @param createdAt - Optional creation timestamp (ISO format), defaults to now
+* @param fileFormat - Storage format: "v2" (default) or "v1" (legacy line array)
+* @returns FileData in the requested format
 */
-function createFileData(content, createdAt) {
-	const lines = typeof content === "string" ? content.split("\n") : content;
+function createFileData(content, createdAt, fileFormat = "v2", mimeType) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
+	if (fileFormat === "v1" && ArrayBuffer.isView(content)) throw new Error("Binary data is not supported with v1 file formats. Please use v2 file format");
+	if (fileFormat === "v2") {
+		if (ArrayBuffer.isView(content)) return {
+			content: new Uint8Array(content.buffer, content.byteOffset, content.byteLength),
+			mimeType: mimeType ?? "application/octet-stream",
+			created_at: createdAt || now,
+			modified_at: now
+		};
+		return {
+			content,
+			mimeType: mimeType ?? "text/plain",
+			created_at: createdAt || now,
+			modified_at: now
+		};
+	}
 	return {
-		content: lines,
+		content: typeof content === "string" ? content.split("\n") : content,
 		created_at: createdAt || now,
 		modified_at: now
 	};
@@ -214,33 +263,20 @@ function createFileData(content, createdAt) {
 * @returns Updated FileData object
 */
 function updateFileData(fileData, content) {
-	const lines = typeof content === "string" ? content.split("\n") : content;
 	const now = (/* @__PURE__ */ new Date()).toISOString();
+	if (isFileDataV1(fileData)) return {
+		content: typeof content === "string" ? content.split("\n") : content,
+		created_at: fileData.created_at,
+		modified_at: now
+	};
 	return {
-		content: lines,
+		content,
+		mimeType: fileData.mimeType,
 		created_at: fileData.created_at,
 		modified_at: now
 	};
 }
 /**
-* Format file data for read response with line numbers.
-*
-* @param fileData - FileData object
-* @param offset - Line offset (0-indexed)
-* @param limit - Maximum number of lines
-* @returns Formatted content or error message
-*/
-function formatReadResponse(fileData, offset, limit) {
-	const content = fileDataToString(fileData);
-	const emptyMsg = checkEmptyContent(content);
-	if (emptyMsg) return emptyMsg;
-	const lines = content.split("\n");
-	const startIdx = offset;
-	const endIdx = Math.min(startIdx + limit, lines.length);
-	if (startIdx >= lines.length) return `Error: Line offset ${offset} exceeds file length (${lines.length} lines)`;
-	return formatContentWithLineNumbers(lines.slice(startIdx, endIdx), startIdx + 1);
-}
-/**
 * Perform string replacement with occurrence validation.
 *
 * @param content - Original content
@@ -267,13 +303,13 @@ function performStringReplacement(content, oldString, newString, replaceAll) {
 function truncateIfTooLong(result) {
 	if (Array.isArray(result)) {
 		const totalChars = result.reduce((sum, item) => sum + item.length, 0);
-		if (totalChars > TOOL_RESULT_TOKEN_LIMIT * 4) {
+		if (totalChars > 2e4 * 4) {
 			const truncateAt = Math.floor(result.length * TOOL_RESULT_TOKEN_LIMIT * 4 / totalChars);
 			return [...result.slice(0, truncateAt), TRUNCATION_GUIDANCE];
 		}
 		return result;
 	}
-	if (result.length > TOOL_RESULT_TOKEN_LIMIT * 4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
+	if (result.length > 2e4 * 4) return result.substring(0, TOOL_RESULT_TOKEN_LIMIT * 4) + "\n... [results truncated, try being more specific with your parameters]";
 	return result;
 }
 /**
@@ -299,8 +335,8 @@ function truncateIfTooLong(result) {
 * validatePath("C:\\Users\\file")  // Throws: Windows absolute paths not supported
 * ```
 */
-function validatePath(path$5) {
-	const pathStr = path$5 || "/";
+function validatePath(path$6) {
+	const pathStr = path$6 || "/";
 	if (!pathStr || pathStr.trim() === "") throw new Error("Path cannot be empty");
 	let normalized = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
 	if (!normalized.endsWith("/")) normalized += "/";
@@ -322,10 +358,10 @@ function validatePath(path$5) {
 * // Returns: "/test.py\n/src/main.py" (sorted by modified_at)
 * ```
 */
-function globSearchFiles(files, pattern, path$7 = "/") {
+function globSearchFiles(files, pattern, path$8 = "/") {
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path$7);
+		normalizedPath = validatePath(path$8);
 	} catch {
 		return "No files found";
 	}
@@ -351,16 +387,13 @@ function globSearchFiles(files, pattern, path$7 = "/") {
 /**
 * Return structured grep matches from an in-memory files mapping.
 *
-* Performs literal text search (not regex).
-*
-* Returns a list of GrepMatch on success, or a string for invalid inputs.
-* We deliberately do not raise here to keep backends non-throwing in tool
-* contexts and preserve user-facing error messages.
+* Performs literal text search (not regex). Binary files are skipped.
+* Returns an empty array when no matches are found or on invalid input.
 */
-function grepMatchesFromFiles(files, pattern, path$9 = null, glob = null) {
+function grepMatchesFromFiles(files, pattern, path$10 = null, glob = null) {
 	let normalizedPath;
 	try {
-		normalizedPath = validatePath(path$9);
+		normalizedPath = validatePath(path$10);
 	} catch {
 		return [];
 	}
@@ -370,18 +403,140 @@ function grepMatchesFromFiles(files, pattern, path$9 = null, glob = null) {
 		nobrace: false
 	})));
 	const matches = [];
-	for (const [filePath, fileData] of Object.entries(filtered)) for (let i = 0; i < fileData.content.length; i++) {
-		const line = fileData.content[i];
-		const lineNum = i + 1;
-		if (line.includes(pattern)) matches.push({
-			path: filePath,
-			line: lineNum,
-			text: line
-		});
+	for (const [filePath, fileData] of Object.entries(filtered)) {
+		if (!isTextMimeType(migrateToFileDataV2(fileData, filePath).mimeType)) continue;
+		const lines = fileDataToString(fileData).split("\n");
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			const lineNum = i + 1;
+			if (line.includes(pattern)) matches.push({
+				path: filePath,
+				line: lineNum,
+				text: line
+			});
+		}
 	}
 	return matches;
 }
-
+/**
+* Determine MIME type from a file path's extension.
+*
+* Returns "text/plain" for unknown extensions.
+*
+* @param filePath - File path to inspect
+* @returns MIME type string (e.g., "image/png", "text/plain")
+*/
+function getMimeType(filePath) {
+	return MIME_TYPES[path.default.extname(filePath).toLocaleLowerCase()] || "text/plain";
+}
+/**
+* Check whether a MIME type represents text content.
+*
+* @param mimeType - MIME type string to check
+* @returns True if the MIME type is text-based
+*/
+function isTextMimeType(mimeType) {
+	return mimeType.startsWith("text/") || mimeType === "application/json" || mimeType === "application/javascript" || mimeType === "image/svg+xml";
+}
+/**
+* Type guard to check if FileData is v1 format (content as line array).
+*
+* @param data - FileData to check
+* @returns True if data is FileDataV1
+*/
+function isFileDataV1(data) {
+	return Array.isArray(data.content);
+}
+/**
+* Convert FileData to v2 format, joining v1 line arrays into a single string.
+*
+* If the data is already v2, returns it unchanged.
+*
+* @param data - FileData in either format
+* @returns FileDataV2 with content as string (text) or Uint8Array (binary)
+*/
+function migrateToFileDataV2(data, filePath) {
+	if (isFileDataV1(data)) return {
+		content: data.content.join("\n"),
+		mimeType: getMimeType(filePath),
+		created_at: data.created_at,
+		modified_at: data.modified_at
+	};
+	if (!("mimeType" in data) || !data.mimeType) return {
+		...data,
+		mimeType: getMimeType(filePath)
+	};
+	return data;
+}
+/**
+* Adapt a v1 {@link BackendProtocol} to {@link BackendProtocolV2}.
+*
+* If the backend already implements v2, it is returned as-is.
+* For v1 backends, wraps returns in Result types:
+* - `read()` string returns wrapped in {@link ReadResult}
+* - `readRaw()` FileData returns wrapped in {@link ReadRawResult}
+* - `grep()` returns wrapped in {@link GrepResult}
+* - `ls()` FileInfo[] returns wrapped in {@link LsResult}
+* - `glob()` FileInfo[] returns wrapped in {@link GlobResult}
+*
+* Note: For sandbox instances, use {@link adaptSandboxProtocol} instead.
+*
+* @param backend - Backend instance (v1 or v2)
+* @returns BackendProtocolV2-compatible backend
+*/
+function adaptBackendProtocol(backend) {
+	return {
+		async ls(path$11) {
+			const result = await ("ls" in backend ? backend.ls(path$11) : backend.lsInfo(path$11));
+			if (Array.isArray(result)) return { files: result };
+			return result;
+		},
+		async readRaw(filePath) {
+			const result = await backend.readRaw(filePath);
+			if ("data" in result || "error" in result) return result;
+			return { data: migrateToFileDataV2(result, filePath) };
+		},
+		async glob(pattern, path$12) {
+			const result = await ("glob" in backend ? backend.glob(pattern, path$12) : backend.globInfo(pattern, path$12));
+			if (Array.isArray(result)) return { files: result };
+			return result;
+		},
+		write: (filePath, content) => backend.write(filePath, content),
+		edit: (filePath, oldString, newString, replaceAll) => backend.edit(filePath, oldString, newString, replaceAll),
+		uploadFiles: backend.uploadFiles ? (files) => backend.uploadFiles(files) : void 0,
+		downloadFiles: backend.downloadFiles ? (paths) => backend.downloadFiles(paths) : void 0,
+		async read(filePath, offset, limit) {
+			const result = await backend.read(filePath, offset, limit);
+			if (typeof result === "string") return { content: result };
+			return result;
+		},
+		async grep(pattern, path$13, glob) {
+			const result = await ("grep" in backend ? backend.grep(pattern, path$13, glob) : backend.grepRaw(pattern, path$13, glob));
+			if (Array.isArray(result)) return { matches: result };
+			if (typeof result === "string") return { error: result };
+			return result;
+		}
+	};
+}
+/**
+* Adapt a sandbox backend from v1 to v2 interface.
+*
+* This extends {@link adaptBackendProtocol} to also preserve sandbox-specific
+* properties from {@link SandboxBackendProtocol}: `execute` and `id`.
+*
+* @param sandbox - Sandbox backend (v1 or v2)
+* @returns SandboxBackendProtocolV2-compatible sandbox
+*/
+function adaptSandboxProtocol(sandbox) {
+	const adapted = adaptBackendProtocol(sandbox);
+	adapted.execute = (cmd) => sandbox.execute(cmd);
+	Object.defineProperty(adapted, "id", {
+		value: sandbox.id,
+		enumerable: true,
+		configurable: true
+	});
+	return adapted;
+}
 //#endregion
 //#region src/backends/state.ts
 /**
@@ -397,8 +552,10 @@ function grepMatchesFromFiles(files, pattern, path$9 = null, glob = null) {
 */
 var StateBackend = class {
 	stateAndStore;
-	constructor(stateAndStore) {
+	fileFormat;
+	constructor(stateAndStore, options) {
 		this.stateAndStore = stateAndStore;
+		this.fileFormat = options?.fileFormat ?? "v2";
 	}
 	/**
 	* Get files from current state.
@@ -410,10 +567,10 @@ var StateBackend = class {
 	* List files and directories in the specified directory (non-recursive).
 	*
 	* @param path - Absolute path to directory
-	* @returns List of FileInfo objects for files and directories directly in the directory.
+	* @returns LsResult with list of FileInfo objects on success or error on failure.
 	*          Directories have a trailing / in their path and is_dir=true.
 	*/
-	lsInfo(path) {
+	ls(path) {
 		const files = this.getFiles();
 		const infos = [];
 		const subdirs = /* @__PURE__ */ new Set();
@@ -426,7 +583,7 @@ var StateBackend = class {
 				subdirs.add(normalizedPath + subdirName + "/");
 				continue;
 			}
-			const size = fd.content.join("\n").length;
+			const size = isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length;
 			infos.push({
 				path: k,
 				is_dir: false,
@@ -441,31 +598,43 @@ var StateBackend = class {
 			modified_at: ""
 		});
 		infos.sort((a, b) => a.path.localeCompare(b.path));
-		return infos;
+		return { files: infos };
 	}
 	/**
-	* Read file content with line numbers.
+	* Read file content.
+	*
+	* Text files are paginated by line offset/limit.
+	* Binary files return full Uint8Array content (offset/limit ignored).
 	*
 	* @param filePath - Absolute file path
 	* @param offset - Line offset to start reading from (0-indexed)
 	* @param limit - Maximum number of lines to read
-	* @returns Formatted file content with line numbers, or error message
+	* @returns ReadResult with content on success or error on failure
 	*/
 	read(filePath, offset = 0, limit = 500) {
 		const fileData = this.getFiles()[filePath];
-		if (!fileData) return `Error: File '${filePath}' not found`;
-		return formatReadResponse(fileData, offset, limit);
+		if (!fileData) return { error: `File '${filePath}' not found` };
+		const fileDataV2 = migrateToFileDataV2(fileData, filePath);
+		if (!isTextMimeType(fileDataV2.mimeType)) return {
+			content: fileDataV2.content,
+			mimeType: fileDataV2.mimeType
+		};
+		if (typeof fileDataV2.content !== "string") return { error: `File '${filePath}' has binary content but text MIME type` };
+		return {
+			content: fileDataV2.content.split("\n").slice(offset, offset + limit).join("\n"),
+			mimeType: fileDataV2.mimeType
+		};
 	}
 	/**
 	* Read file content as raw FileData.
 	*
 	* @param filePath - Absolute file path
-	* @returns Raw file content as FileData
+	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	readRaw(filePath) {
 		const fileData = this.getFiles()[filePath];
-		if (!fileData) throw new Error(`File '${filePath}' not found`);
-		return fileData;
+		if (!fileData) return { error: `File '${filePath}' not found` };
+		return { data: fileData };
 	}
 	/**
 	* Create a new file with content.
@@ -473,7 +642,8 @@ var StateBackend = class {
 	*/
 	write(filePath, content) {
 		if (filePath in this.getFiles()) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
-		const newFileData = createFileData(content);
+		const mimeType = getMimeType(filePath);
+		const newFileData = createFileData(content, void 0, this.fileFormat, mimeType);
 		return {
 			path: filePath,
 			filesUpdate: { [filePath]: newFileData }
@@ -497,23 +667,24 @@ var StateBackend = class {
 		};
 	}
 	/**
-	* Structured search results or error string for invalid input.
+	* Search file contents for a literal text pattern.
+	* Binary files are skipped.
 	*/
-	grepRaw(pattern, path = "/", glob = null) {
-		return grepMatchesFromFiles(this.getFiles(), pattern, path, glob);
+	grep(pattern, path = "/", glob = null) {
+		return { matches: grepMatchesFromFiles(this.getFiles(), pattern, path, glob) };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	globInfo(pattern, path = "/") {
+	glob(pattern, path = "/") {
 		const files = this.getFiles();
 		const result = globSearchFiles(files, pattern, path);
-		if (result === "No files found") return [];
+		if (result === "No files found") return { files: [] };
 		const paths = result.split("\n");
 		const infos = [];
 		for (const p of paths) {
 			const fd = files[p];
-			const size = fd ? fd.content.join("\n").length : 0;
+			const size = fd ? isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length : 0;
 			infos.push({
 				path: p,
 				is_dir: false,
@@ -521,7 +692,7 @@ var StateBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -536,7 +707,9 @@ var StateBackend = class {
 		const responses = [];
 		const updates = {};
 		for (const [path, content] of files) try {
-			updates[path] = createFileData(new TextDecoder().decode(content));
+			const mimeType = getMimeType(path);
+			if (this.fileFormat === "v2" && !isTextMimeType(mimeType)) updates[path] = createFileData(content, void 0, "v2", mimeType);
+			else updates[path] = createFileData(new TextDecoder().decode(content), void 0, this.fileFormat, mimeType);
 			responses.push({
 				path,
 				error: null
@@ -570,18 +743,23 @@ var StateBackend = class {
 				});
 				continue;
 			}
-			const contentStr = fileDataToString(fileData);
-			const content = new TextEncoder().encode(contentStr);
-			responses.push({
+			const fileDataV2 = migrateToFileDataV2(fileData, path);
+			if (typeof fileDataV2.content === "string") {
+				const content = new TextEncoder().encode(fileDataV2.content);
+				responses.push({
+					path,
+					content,
+					error: null
+				});
+			} else responses.push({
 				path,
-				content,
+				content: fileDataV2.content,
 				error: null
 			});
 		}
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/middleware/fs.ts
 /**
@@ -614,6 +792,20 @@ var StateBackend = class {
 *    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.
 */
+/**
+* All tool names registered by FilesystemMiddleware.
+* This is the single source of truth — used by createDeepAgent to detect
+* collisions with user-supplied tools at construction time.
+*/
+const FILESYSTEM_TOOL_NAMES = [
+	"ls",
+	"read_file",
+	"write_file",
+	"edit_file",
+	"glob",
+	"grep",
+	"execute"
+];
 const TOOLS_EXCLUDED_FROM_EVICTION = [
 	"ls",
 	"glob",
@@ -623,16 +815,11 @@ const TOOLS_EXCLUDED_FROM_EVICTION = [
 	"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;
-/**
-* Default values for read_file tool pagination (in lines).
+* Maximum size for binary (non-text) files read via read_file, in bytes.
+* Base64-encoded content is ~33% larger, so 10MB raw ≈ 13.3MB in context.
+* This keeps inline multimodal payloads within all major provider limits.
 */
-const DEFAULT_READ_LINE_OFFSET = 0;
-const DEFAULT_READ_LINE_LIMIT = 100;
+const MAX_BINARY_READ_SIZE_BYTES = 10 * 1024 * 1024;
 /**
 * Template for truncation message in read_file.
 * {file_path} will be filled in at runtime.
@@ -672,14 +859,27 @@ function createContentPreview(contentStr, headLines = 5, tailLines = 5) {
 	return headSample + truncationNotice + tailSample;
 }
 /**
-* Zod v3 schema for FileData (re-export from backends)
+* Zod schema for legacy FileDataV1 (content as line array).
 */
-const FileDataSchema = zod_v4.z.object({
+const FileDataV1Schema = zod_v4.z.object({
 	content: zod_v4.z.array(zod_v4.z.string()),
 	created_at: zod_v4.z.string(),
 	modified_at: zod_v4.z.string()
 });
 /**
+* Zod schema for FileDataV2 (content as string for text or Uint8Array for binary).
+*/
+const FileDataV2Schema = zod_v4.z.object({
+	content: zod_v4.z.union([zod_v4.z.string(), zod_v4.z.instanceof(Uint8Array)]),
+	mimeType: zod_v4.z.string(),
+	created_at: zod_v4.z.string(),
+	modified_at: zod_v4.z.string()
+});
+/**
+* Zod v3 schema for FileData (re-export from backends)
+*/
+const FileDataSchema = zod_v4.z.union([FileDataV1Schema, FileDataV2Schema]);
+/**
 * 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.
@@ -722,8 +922,8 @@ const FilesystemStateSchema = new _langchain_langgraph.StateSchema({ files: new
 * @param stateAndStore - State and store container for backend initialization
 */
 function getBackend(backend, stateAndStore) {
-	if (typeof backend === "function") return backend(stateAndStore);
-	return backend;
+	const actualBackend = typeof backend === "function" ? backend(stateAndStore) : backend;
+	return isSandboxProtocol(actualBackend) ? adaptSandboxProtocol(actualBackend) : adaptBackendProtocol(actualBackend);
 }
 const FILESYSTEM_SYSTEM_PROMPT = `## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
 
@@ -848,7 +1048,9 @@ function createLsTool(backend, options) {
 			store: config.store
 		});
 		const path = input.path || "/";
-		const infos = await resolvedBackend.lsInfo(path);
+		const lsResult = await resolvedBackend.ls(path);
+		if (lsResult.error) return `Error listing files: ${lsResult.error}`;
+		const infos = lsResult.files || [];
 		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)`);
@@ -875,23 +1077,72 @@ function createReadFileTool(backend, options) {
 			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
 			store: config.store
 		});
-		const { file_path, offset = DEFAULT_READ_LINE_OFFSET, limit = DEFAULT_READ_LINE_LIMIT } = input;
-		let result = await resolvedBackend.read(file_path, offset, limit);
-		const lines = result.split("\n");
-		if (lines.length > limit) result = lines.slice(0, limit).join("\n");
-		if (toolTokenLimitBeforeEvict && result.length >= NUM_CHARS_PER_TOKEN * toolTokenLimitBeforeEvict) {
+		const { file_path, offset = 0, limit = 100 } = input;
+		const readResult = await resolvedBackend.read(file_path, offset, limit);
+		if (readResult.error) return [{
+			type: "text",
+			text: `Error: ${readResult.error}`
+		}];
+		const mimeType = readResult.mimeType ?? getMimeType(file_path);
+		if (!isTextMimeType(mimeType)) {
+			const binaryContent = readResult.content;
+			if (!binaryContent) return [{
+				type: "text",
+				text: `Error: expected binary content for '${file_path}'`
+			}];
+			let base64Data;
+			if (typeof binaryContent === "string") base64Data = binaryContent;
+			else if (ArrayBuffer.isView(binaryContent)) base64Data = Buffer.from(binaryContent).toString("base64");
+			else {
+				const values = Object.values(binaryContent);
+				base64Data = Buffer.from(new Uint8Array(values)).toString("base64");
+			}
+			const sizeBytes = Math.ceil(base64Data.length * 3 / 4);
+			if (sizeBytes > 10485760) return [{
+				type: "text",
+				text: `Error: file too large to read (${Math.round(sizeBytes / (1024 * 1024))}MB exceeds ${MAX_BINARY_READ_SIZE_BYTES / (1024 * 1024)}MB limit for binary files)`
+			}];
+			if (mimeType.startsWith("image/")) return [{
+				type: "image",
+				mimeType,
+				data: base64Data
+			}];
+			if (mimeType.startsWith("audio/")) return [{
+				type: "audio",
+				mimeType,
+				data: base64Data
+			}];
+			if (mimeType.startsWith("video/")) return [{
+				type: "video",
+				mimeType,
+				data: base64Data
+			}];
+			return [{
+				type: "file",
+				mimeType,
+				data: base64Data
+			}];
+		}
+		let content = typeof readResult.content === "string" ? readResult.content : "";
+		const lines = content.split("\n");
+		if (lines.length > limit) content = lines.slice(0, limit).join("\n");
+		let formatted = formatContentWithLineNumbers(content, offset + 1);
+		if (toolTokenLimitBeforeEvict && formatted.length >= 4 * toolTokenLimitBeforeEvict) {
 			const truncationMsg = READ_FILE_TRUNCATION_MSG.replace("{file_path}", file_path);
-			const maxContentLength = NUM_CHARS_PER_TOKEN * toolTokenLimitBeforeEvict - truncationMsg.length;
-			result = result.substring(0, maxContentLength) + truncationMsg;
+			const maxContentLength = 4 * toolTokenLimitBeforeEvict - truncationMsg.length;
+			formatted = formatted.substring(0, maxContentLength) + truncationMsg;
 		}
-		return result;
+		return [{
+			type: "text",
+			text: formatted
+		}];
 	}, {
 		name: "read_file",
 		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
 		schema: zod_v4.z.object({
 			file_path: zod_v4.z.string().describe("Absolute path to the file to read"),
-			offset: zod_v4.z.coerce.number().optional().default(DEFAULT_READ_LINE_OFFSET).describe("Line offset to start reading from (0-indexed)"),
-			limit: zod_v4.z.coerce.number().optional().default(DEFAULT_READ_LINE_LIMIT).describe("Maximum number of lines to read")
+			offset: zod_v4.z.coerce.number().optional().default(0).describe("Line offset to start reading from (0-indexed)"),
+			limit: zod_v4.z.coerce.number().optional().default(100).describe("Maximum number of lines to read")
 		})
 	});
 }
@@ -974,7 +1225,9 @@ function createGlobTool(backend, options) {
 			store: config.store
 		});
 		const { pattern, path = "/" } = input;
-		const infos = await resolvedBackend.globInfo(pattern, path);
+		const globResult = await resolvedBackend.glob(pattern, path);
+		if (globResult.error) return `Error finding files: ${globResult.error}`;
+		const infos = globResult.files || [];
 		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
 		const result = truncateIfTooLong(infos.map((info) => info.path));
 		if (Array.isArray(result)) return result.join("\n");
@@ -999,12 +1252,13 @@ function createGrepTool(backend, options) {
 			store: config.store
 		});
 		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 result = await resolvedBackend.grep(pattern, path, glob);
+		if (result.error) return result.error;
+		const matches = result.matches ?? [];
+		if (matches.length === 0) return `No matches found for pattern '${pattern}'`;
 		const lines = [];
 		let currentFile = null;
-		for (const match of result) {
+		for (const match of matches) {
 			if (match.path !== currentFile) {
 				currentFile = match.path;
 				lines.push(`\n${currentFile}:`);
@@ -1055,21 +1309,22 @@ function createExecuteTool(backend, options) {
 function createFilesystemMiddleware(options = {}) {
 	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
 	const baseSystemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
+	const allToolsByName = {
+		ls: createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+		read_file: createReadFileTool(backend, {
+			customDescription: customToolDescriptions?.read_file,
+			toolTokenLimitBeforeEvict
+		}),
+		write_file: createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
+		edit_file: createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
+		glob: createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
+		grep: createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
+		execute: createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
+	};
 	return (0, langchain.createMiddleware)({
 		name: "FilesystemMiddleware",
 		stateSchema: FilesystemStateSchema,
-		tools: [
-			createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
-			createReadFileTool(backend, {
-				customDescription: customToolDescriptions?.read_file,
-				toolTokenLimitBeforeEvict
-			}),
-			createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
-			createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
-			createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
-			createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
-			createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
-		],
+		tools: Object.values(allToolsByName),
 		wrapModelCall: async (request, handler) => {
 			const supportsExecution = isSandboxBackend(getBackend(backend, {
 				state: request.state || {},
@@ -1092,7 +1347,7 @@ function createFilesystemMiddleware(options = {}) {
 			if (toolName && TOOLS_EXCLUDED_FROM_EVICTION.includes(toolName)) return handler(request);
 			const result = await handler(request);
 			async function processToolMessage(msg, toolTokenLimitBeforeEvict) {
-				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * NUM_CHARS_PER_TOKEN) {
+				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * 4) {
 					const resolvedBackend = getBackend(backend, {
 						state: request.state || {},
 						store: request.runtime?.store
@@ -1156,7 +1411,6 @@ function createFilesystemMiddleware(options = {}) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/subagents.ts
 /**
@@ -1537,12 +1791,23 @@ function createSubAgentMiddleware(options) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/patch_tool_calls.ts
 /**
-* Patch dangling tool calls in a messages array.
-* Returns the patched messages array and a flag indicating if patching was needed.
+* Patch tool call / tool response parity in a messages array.
+*
+* Ensures strict 1:1 correspondence between AIMessage tool_calls and
+* ToolMessage responses:
+*
+* 1. **Dangling tool_calls** — an AIMessage contains a tool_call with no
+*    matching ToolMessage anywhere after it. A synthetic cancellation
+*    ToolMessage is inserted immediately after the AIMessage.
+*
+* 2. **Orphaned ToolMessages** — a ToolMessage whose `tool_call_id` does not
+*    match any tool_call in a preceding AIMessage. The ToolMessage is removed.
+*
+* Both directions are required for providers that enforce strict parity
+* (e.g. Google Gemini returns 400 INVALID_ARGUMENT otherwise).
 *
 * @param messages - The messages array to patch
 * @returns Object with patched messages and needsPatch flag
@@ -1552,13 +1817,23 @@ function patchDanglingToolCalls(messages) {
 		patchedMessages: [],
 		needsPatch: false
 	};
+	const allToolCallIds = /* @__PURE__ */ new Set();
+	for (const msg of messages) if (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
+		for (const tc of msg.tool_calls) if (tc.id) allToolCallIds.add(tc.id);
+	}
 	const patchedMessages = [];
 	let needsPatch = false;
 	for (let i = 0; i < messages.length; i++) {
 		const msg = messages[i];
+		if (langchain.ToolMessage.isInstance(msg)) {
+			if (!allToolCallIds.has(msg.tool_call_id)) {
+				needsPatch = true;
+				continue;
+			}
+		}
 		patchedMessages.push(msg);
 		if (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
-			for (const toolCall of msg.tool_calls) if (!messages.slice(i).find((m) => langchain.ToolMessage.isInstance(m) && m.tool_call_id === toolCall.id)) {
+			for (const toolCall of msg.tool_calls) if (!messages.slice(i + 1).find((m) => langchain.ToolMessage.isInstance(m) && m.tool_call_id === toolCall.id)) {
 				needsPatch = true;
 				const toolMsg = `Tool call ${toolCall.name} with id ${toolCall.id} was cancelled - another message came in before it could be completed.`;
 				patchedMessages.push(new langchain.ToolMessage({
@@ -1575,11 +1850,18 @@ function patchDanglingToolCalls(messages) {
 	};
 }
 /**
-* Create middleware that patches dangling tool calls in the messages history.
+* Create middleware that enforces strict tool call / tool response parity in
+* the messages history.
+*
+* Two kinds of violations are repaired:
+* 1. **Dangling tool_calls** — an AIMessage contains tool_calls with no
+*    matching ToolMessage responses. Synthetic cancellation ToolMessages are
+*    injected so every tool_call has a response.
+* 2. **Orphaned ToolMessages** — a ToolMessage exists whose `tool_call_id`
+*    does not match any tool_call in a preceding AIMessage. These are removed.
 *
-* When an AI message contains tool_calls but subsequent messages don't include
-* the corresponding ToolMessage responses, this middleware adds synthetic
-* ToolMessages saying the tool call was cancelled.
+* This is critical for providers like Google Gemini that reject requests with
+* mismatched function call / function response counts (400 INVALID_ARGUMENT).
 *
 * This middleware patches in two places:
 * 1. `beforeAgent`: Patches state at the start of the agent loop (handles most cases)
@@ -1587,7 +1869,7 @@ function patchDanglingToolCalls(messages) {
 *    edge cases like HITL rejection during graph resume where state updates from
 *    beforeAgent may not be applied in time)
 *
-* @returns AgentMiddleware that patches dangling tool calls
+* @returns AgentMiddleware that enforces tool call / response parity
 *
 * @example
 * ```typescript
@@ -1625,7 +1907,6 @@ function createPatchToolCallsMiddleware() {
 		}
 	});
 }
-
 //#endregion
 //#region src/values.ts
 /**
@@ -1660,7 +1941,6 @@ const filesValue = new _langchain_langgraph.ReducedValue(zod.z.record(zod.z.stri
 	inputSchema: zod.z.record(zod.z.string(), FileDataSchema.nullable()).optional(),
 	reducer: fileDataReducer
 });
-
 //#endregion
 //#region src/middleware/memory.ts
 /**
@@ -1801,12 +2081,14 @@ function formatMemoryContents(contents, sources) {
 * @returns File content if found, null otherwise.
 */
 async function loadMemoryFromBackend(backend, path) {
-	if (!backend.downloadFiles) {
-		const content = await backend.read(path);
-		if (content.startsWith("Error:")) return null;
-		return content;
-	}
-	const results = await backend.downloadFiles([path]);
+	const adaptedBackend = adaptBackendProtocol(backend);
+	if (!adaptedBackend.downloadFiles) {
+		const content = await adaptedBackend.read(path);
+		if (content.error) return null;
+		if (typeof content.content !== "string") return null;
+		return content.content;
+	}
+	const results = await adaptedBackend.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) {
@@ -1842,8 +2124,8 @@ function createMemoryMiddleware(options) {
 	* Resolve backend from instance or factory.
 	*/
 	function getBackend(state) {
-		if (typeof backend === "function") return backend({ state });
-		return backend;
+		if (typeof backend === "function") return adaptBackendProtocol(backend({ state }));
+		return adaptBackendProtocol(backend);
 	}
 	return (0, langchain.createMiddleware)({
 		name: "MemoryMiddleware",
@@ -1879,7 +2161,6 @@ function createMemoryMiddleware(options) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/skills.ts
 /**
@@ -1925,7 +2206,6 @@ function createMemoryMiddleware(options) {
 const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
 const MAX_SKILL_NAME_LENGTH = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
-const MAX_SKILL_COMPATIBILITY_LENGTH = 500;
 /**
 * Zod schema for a single skill metadata entry.
 */
@@ -2035,7 +2315,7 @@ function validateSkillName$1(name, directoryName) {
 		valid: false,
 		error: "name is required"
 	};
-	if (name.length > MAX_SKILL_NAME_LENGTH) return {
+	if (name.length > 64) return {
 		valid: false,
 		error: "name exceeds 64 characters"
 	};
@@ -2109,7 +2389,7 @@ function formatSkillAnnotations(skill) {
 *   validation errors occur
 */
 function parseSkillMetadataFromContent(content, skillPath, directoryName) {
-	if (content.length > MAX_SKILL_FILE_SIZE) {
+	if (content.length > 10485760) {
 		console.warn(`Skipping ${skillPath}: content too large (${content.length} bytes)`);
 		return null;
 	}
@@ -2139,7 +2419,7 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 	const validation = validateSkillName$1(name, directoryName);
 	if (!validation.valid) console.warn(`Skill '${name}' in ${skillPath} does not follow Agent Skills specification: ${validation.error}. Consider renaming for spec compliance.`);
 	let descriptionStr = description;
-	if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+	if (descriptionStr.length > 1024) {
 		console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} characters in ${skillPath}, truncating`);
 		descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
 	}
@@ -2149,9 +2429,9 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 	else allowedTools = String(rawTools).split(/\s+/).filter(Boolean);
 	else allowedTools = [];
 	let compatibilityStr = String(frontmatterData.compatibility ?? "").trim() || null;
-	if (compatibilityStr && compatibilityStr.length > MAX_SKILL_COMPATIBILITY_LENGTH) {
-		console.warn(`Compatibility exceeds ${MAX_SKILL_COMPATIBILITY_LENGTH} characters in ${skillPath}, truncating`);
-		compatibilityStr = compatibilityStr.slice(0, MAX_SKILL_COMPATIBILITY_LENGTH);
+	if (compatibilityStr && compatibilityStr.length > 500) {
+		console.warn(`Compatibility exceeds 500 characters in ${skillPath}, truncating`);
+		compatibilityStr = compatibilityStr.slice(0, 500);
 	}
 	return {
 		name,
@@ -2167,12 +2447,15 @@ function parseSkillMetadataFromContent(content, skillPath, directoryName) {
 * List all skills from a backend source.
 */
 async function listSkillsFromBackend(backend, sourcePath) {
+	const adaptedBackend = adaptBackendProtocol(backend);
 	const skills = [];
 	const pathSep = sourcePath.includes("\\") ? "\\" : "/";
 	const normalizedPath = sourcePath.endsWith("/") || sourcePath.endsWith("\\") ? sourcePath : `${sourcePath}${pathSep}`;
 	let fileInfos;
 	try {
-		fileInfos = await backend.lsInfo(normalizedPath);
+		const lsResult = await adaptedBackend.ls(normalizedPath);
+		if (lsResult.error || !lsResult.files) return [];
+		fileInfos = lsResult.files;
 	} catch {
 		return [];
 	}
@@ -2184,16 +2467,17 @@ async function listSkillsFromBackend(backend, sourcePath) {
 		if (entry.type !== "directory") continue;
 		const skillMdPath = `${normalizedPath}${entry.name}${pathSep}SKILL.md`;
 		let content;
-		if (backend.downloadFiles) {
-			const results = await backend.downloadFiles([skillMdPath]);
+		if (adaptedBackend.downloadFiles) {
+			const results = await adaptedBackend.downloadFiles([skillMdPath]);
 			if (results.length !== 1) continue;
 			const response = results[0];
 			if (response.error != null || response.content == null) continue;
 			content = new TextDecoder().decode(response.content);
 		} else {
-			const readResult = await backend.read(skillMdPath);
-			if (readResult.startsWith("Error:")) continue;
-			content = readResult;
+			const readResult = await adaptedBackend.read(skillMdPath);
+			if (readResult.error) continue;
+			if (typeof readResult.content !== "string") continue;
+			content = readResult.content;
 		}
 		const metadata = parseSkillMetadataFromContent(content, skillMdPath, entry.name);
 		if (metadata) skills.push(metadata);
@@ -2258,8 +2542,8 @@ function createSkillsMiddleware(options) {
 	* Resolve backend from instance or factory.
 	*/
 	function getBackend(state) {
-		if (typeof backend === "function") return backend({ state });
-		return backend;
+		if (typeof backend === "function") return adaptBackendProtocol(backend({ state }));
+		return adaptBackendProtocol(backend);
 	}
 	return (0, langchain.createMiddleware)({
 		name: "SkillsMiddleware",
@@ -2294,7 +2578,6 @@ function createSkillsMiddleware(options) {
 		}
 	});
 }
-
 //#endregion
 //#region src/middleware/utils.ts
 /**
@@ -2302,7 +2585,226 @@ function createSkillsMiddleware(options) {
 *
 * This module provides shared helpers used across middleware implementations.
 */
-
+//#endregion
+//#region src/middleware/completion_notifier.ts
+/**
+* Completion notifier middleware for async subagents.
+*
+* **Experimental** — this middleware is experimental and may change in future releases.
+*
+* When an async subagent finishes (success or error), this middleware sends a
+* message back to the **supervisor's** thread so the supervisor wakes up and can
+* proactively relay results to the user — without the user having to poll via
+* `check_async_task`.
+*
+* ## Architecture
+*
+* The async subagent protocol is inherently fire-and-forget: the supervisor
+* launches a job via `start_async_task` and only learns about completion
+* when someone calls `check_async_task`. This middleware closes that gap.
+*
+* ```
+* Supervisor                    Subagent
+*     |                            |
+*     |--- start_async_task -----> |
+*     |<-- task_id (immediately) - |
+*     |                            |  (working...)
+*     |                            |  (done!)
+*     |                            |
+*     |<-- runs.create(            |
+*     |      supervisor_thread,    |
+*     |      "completed: ...")     |
+*     |                            |
+*     |  (wakes up, sees result)   |
+* ```
+*
+* The notifier calls `runs.create()` on the supervisor's thread, which
+* queues a new run. From the supervisor's perspective, it looks like a new
+* user message arrived — except the content is a structured notification
+* from the subagent.
+*
+* ## How parent context is propagated
+*
+* - `parentGraphId` is passed as a **constructor argument** to the middleware.
+*   This is the supervisor's graph ID (or assistant ID), which the subagent
+*   developer knows at configuration time.
+* - `url` is the URL of the LangGraph server where the supervisor is deployed.
+*   This is required since JS does not support in-process ASGI transport.
+* - `headers` are optional additional headers for authenticating with the
+*   supervisor's server.
+* - `parent_thread_id` is injected into the subagent's input state by the
+*   supervisor's `start_async_task` tool. It survives thread interrupts and
+*   updates because it lives in state, not config.
+* - If `parent_thread_id` is not present in state, the notifier silently no-ops.
+*
+* ## Usage
+*
+* ```typescript
+* import { createCompletionNotifierMiddleware } from "deepagents";
+*
+* const notifier = createCompletionNotifierMiddleware({
+*   parentGraphId: "supervisor",
+*   url: "https://my-deployment.langsmith.dev",
+* });
+*
+* const agent = createDeepAgent({
+*   model: "claude-sonnet-4-5-20250929",
+*   middleware: [notifier],
+* });
+* ```
+*
+* The middleware will read `parent_thread_id` from the agent's state at the
+* end of execution. This is injected automatically by the supervisor's
+* `start_async_task` tool when it creates the run.
+*
+* @module
+*/
+/** State key where the supervisor's launch tool stores the parent thread ID. */
+const PARENT_THREAD_ID_KEY = "parent_thread_id";
+/** Maximum characters to include from the last message in notifications. */
+const MAX_SUMMARY_LENGTH = 500;
+/**
+* State extension for subagents that use the completion notifier.
+*
+* These fields are injected by the supervisor's `start_async_task`
+* tool and read by the completion notifier middleware to send notifications
+* back to the supervisor's thread.
+*/
+const CompletionNotifierStateSchema = zod_v4.z.object({ parent_thread_id: zod_v4.z.string().nullish() });
+/**
+* Build headers for the supervisor's LangGraph server.
+*
+* Ensures `x-auth-scheme: langsmith` is present unless explicitly overridden.
+*/
+function resolveHeaders(headers) {
+	const resolved = { ...headers };
+	if (!("x-auth-scheme" in resolved)) resolved["x-auth-scheme"] = "langsmith";
+	return resolved;
+}
+/**
+* Send a notification run to the parent supervisor's thread.
+*/
+async function notifyParent(parentThreadId, parentGraphId, notification, options) {
+	try {
+		await new _langchain_langgraph_sdk.Client({
+			apiUrl: options.url,
+			apiKey: null,
+			defaultHeaders: resolveHeaders(options.headers)
+		}).runs.create(parentThreadId, parentGraphId, { input: { messages: [{
+			role: "user",
+			content: notification
+		}] } });
+	} catch (e) {
+		console.warn(`[CompletionNotifierMiddleware] Failed to notify parent thread ${parentThreadId}:`, e);
+	}
+}
+/**
+* Extract a summary from the subagent's final message.
+*
+* Returns at most 500 characters from the last message's content.
+*/
+function extractLastMessage(state) {
+	const messages = state.messages;
+	if (!messages || messages.length === 0) return "(no output)";
+	const last = messages[messages.length - 1];
+	if (last && typeof last === "object" && "content" in last) {
+		const content = last.content;
+		if (typeof content === "string") return content.slice(0, MAX_SUMMARY_LENGTH);
+		return JSON.stringify(content).slice(0, MAX_SUMMARY_LENGTH);
+	}
+	return String(last).slice(0, MAX_SUMMARY_LENGTH);
+}
+/**
+* Create a completion notifier middleware for async subagents.
+*
+* **Experimental** — this middleware is experimental and may change.
+*
+* This middleware is added to the **subagent's** middleware stack (not the
+* supervisor's). When the subagent finishes, it sends a message to the
+* supervisor's thread via `runs.create()`, waking the supervisor so it can
+* proactively relay results.
+*
+* The supervisor's `parent_thread_id` is read from the subagent's own state
+* (injected by the supervisor's `start_async_task` tool at launch time).
+* The `parentGraphId` is provided as a constructor argument since it's static
+* configuration known at deployment time.
+*
+* If `parent_thread_id` is not present in state (e.g., the subagent was
+* launched manually without a supervisor), the middleware silently does
+* nothing.
+*
+* @param options - Configuration options.
+* @returns An `AgentMiddleware` instance.
+*
+* @example
+* ```typescript
+* import { createCompletionNotifierMiddleware } from "deepagents";
+*
+* const notifier = createCompletionNotifierMiddleware({
+*   parentGraphId: "supervisor",
+*   url: "https://my-deployment.langsmith.dev",
+* });
+*
+* const agent = createDeepAgent({
+*   model: "claude-sonnet-4-5-20250929",
+*   middleware: [notifier],
+* });
+* ```
+*/
+function createCompletionNotifierMiddleware(options) {
+	const { parentGraphId, url, headers } = options;
+	let notified = false;
+	/**
+	* Check whether we should send a notification.
+	*/
+	function shouldNotify(state) {
+		if (notified) return false;
+		return Boolean(state[PARENT_THREAD_ID_KEY]);
+	}
+	/**
+	* Send a notification to the parent if conditions are met.
+	*/
+	async function sendNotification(state, message) {
+		if (!shouldNotify(state)) return;
+		notified = true;
+		await notifyParent(state[PARENT_THREAD_ID_KEY], parentGraphId, message, {
+			url,
+			headers
+		});
+	}
+	/**
+	* Read the subagent's own thread_id from runtime config.
+	*
+	* The subagent's `thread_id` is the same as the `task_id` from the
+	* supervisor's perspective.
+	*/
+	function getTaskId(runtime) {
+		return runtime?.configurable?.thread_id;
+	}
+	/**
+	* Build a notification string with task_id prefix.
+	*/
+	function formatNotification(body, runtime) {
+		const taskId = getTaskId(runtime);
+		return `${taskId ? `[task_id=${taskId}]` : ""}${body}`;
+	}
+	return (0, langchain.createMiddleware)({
+		name: "CompletionNotifierMiddleware",
+		stateSchema: CompletionNotifierStateSchema,
+		async afterAgent(state, runtime) {
+			await sendNotification(state, formatNotification(`Completed. Result: ${extractLastMessage(state)}`, runtime));
+		},
+		async wrapModelCall(request, handler) {
+			try {
+				return await handler(request);
+			} catch (e) {
+				const notification = formatNotification(`Error: ${e instanceof Error ? e.message : String(e)}`, request.runtime);
+				await sendNotification(request.state, notification);
+				throw e;
+			}
+		}
+	});
+}
 //#endregion
 //#region src/middleware/summarization.ts
 /**
@@ -2499,15 +3001,15 @@ function createSummarizationMiddleware(options) {
 	* Resolve backend from instance or factory.
 	*/
 	function getBackend(state) {
-		if (typeof backend === "function") return backend({ state });
-		return backend;
+		if (typeof backend === "function") return adaptBackendProtocol(backend({ state }));
+		return adaptBackendProtocol(backend);
 	}
 	/**
 	* Get or create session ID for history file naming.
 	*/
 	function getSessionId(state) {
 		if (state._summarizationSessionId) return state._summarizationSessionId;
-		if (!sessionId) sessionId = `session_${(0, uuid.v4)().substring(0, 8)}`;
+		if (!sessionId) sessionId = `session_${crypto.randomUUID().substring(0, 8)}`;
 		return sessionId;
 	}
 	/**
@@ -2992,32 +3494,557 @@ ${summary}
 		}
 	});
 }
-
 //#endregion
-//#region src/backends/store.ts
-const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
+//#region src/middleware/async_subagents.ts
+function toolCallIdFromRuntime(runtime) {
+	return runtime.toolCall?.id ?? runtime.toolCallId ?? "";
+}
 /**
-* Validate a namespace array.
+* Zod schema for {@link AsyncTask}.
 *
-* Each component must be a non-empty string containing only safe characters:
-* alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),
-* at sign (@), plus (+), colon (:), and tilde (~).
+* Used by the {@link ReducedValue} in the state schema so that LangGraph
+* can validate and serialize task records stored in `asyncTasks`.
+*/
+const AsyncTaskSchema = zod_v4.z.object({
+	taskId: zod_v4.z.string(),
+	agentName: zod_v4.z.string(),
+	threadId: zod_v4.z.string(),
+	runId: zod_v4.z.string(),
+	status: zod_v4.z.string(),
+	createdAt: zod_v4.z.string(),
+	updatedAt: zod_v4.z.string().optional(),
+	checkedAt: zod_v4.z.string().optional()
+});
+/**
+* State schema for the async subagent middleware.
 *
-* Characters like *, ?, [, ], {, } etc. are rejected to prevent
-* wildcard or glob injection in store lookups.
+* Declares `asyncTasks` as a reduced state channel so that individual
+* tool updates (launch, check, update, cancel, list) merge into the existing
+* tasks dict rather than replacing it wholesale.
 */
-function validateNamespace(namespace) {
-	if (namespace.length === 0) throw new Error("Namespace array must not be empty.");
-	for (let i = 0; i < namespace.length; i++) {
-		const component = namespace[i];
-		if (typeof component !== "string") throw new TypeError(`Namespace component at index ${i} must be a string, got ${typeof component}.`);
-		if (!component) throw new Error(`Namespace component at index ${i} must not be empty.`);
-		if (!NAMESPACE_COMPONENT_RE.test(component)) throw new Error(`Namespace component at index ${i} contains disallowed characters: "${component}". Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.`);
-	}
-	return namespace;
-}
+const AsyncTaskStateSchema = new _langchain_langgraph.StateSchema({ asyncTasks: new _langchain_langgraph.ReducedValue(zod_v4.z.record(zod_v4.z.string(), AsyncTaskSchema).default(() => ({})), {
+	inputSchema: zod_v4.z.record(zod_v4.z.string(), AsyncTaskSchema).optional(),
+	reducer: asyncTasksReducer
+}) });
 /**
-* Backend that stores files in LangGraph's BaseStore (persistent).
+* Reducer for the `asyncTasks` state channel.
+*
+* Merges task updates into the existing tasks dict using shallow spread.
+* This allows individual tools to update a single task without overwriting
+* the full map — only the keys present in `update` are replaced.
+*
+* @param existing - The current tasks dict from state (may be undefined on first write).
+* @param update - New or updated task entries to merge in.
+* @returns Merged tasks dict.
+*/
+function asyncTasksReducer(existing, update) {
+	return {
+		...existing || {},
+		...update || {}
+	};
+}
+/**
+* Description template for the `start_async_task` tool.
+*
+* The `{available_agents}` placeholder is replaced at middleware creation
+* time with a formatted list of configured async subagent names and descriptions.
+*/
+const ASYNC_TASK_TOOL_DESCRIPTION = `Launch an async subagent on a remote LangGraph server. The subagent runs in the background and returns a task ID immediately.
+
+Available async agent types:
+{available_agents}
+
+## Usage notes:
+1. This tool launches a background task and returns immediately with a task ID. Report the task ID to the user and stop — do NOT immediately check status.
+2. Use \`check_async_task\` only when the user asks for a status update or result.
+3. Use \`update_async_task\` to send new instructions to a running task.
+4. Multiple async subagents can run concurrently — launch several and let them run in the background.
+5. The subagent runs on a remote LangGraph server, so it has its own tools and capabilities.`;
+/**
+* Default system prompt appended to the main agent's system message when
+* async subagent middleware is active.
+*
+* Provides the agent with instructions on how to use the five async subagent
+* tools (launch, check, update, cancel, list) including workflow ordering,
+* critical rules about polling behavior, and guidance on when to use async
+* subagents vs. synchronous delegation.
+*/
+const ASYNC_TASK_SYSTEM_PROMPT = `## Async subagents (remote LangGraph servers)
+
+You have access to async subagent tools that launch background tasks on remote LangGraph servers.
+
+### Tools:
+- \`start_async_task\`: Start a new background task. Returns a task ID immediately.
+- \`check_async_task\`: Check the status of a running task. Returns status and result if complete.
+- \`update_async_task\`: Send an update or new instructions to a running task.
+- \`cancel_async_task\`: Cancel a running task that is no longer needed.
+- \`list_async_tasks\`: List all tracked tasks with live statuses. Use this to check all tasks at once.
+
+### Workflow:
+1. **Launch** — Use \`start_async_task\` to start a task. Report the task ID to the user and stop.
+   Do NOT immediately check the status — the task runs in the background while you and the user continue other work.
+2. **Check (on request)** — Only use \`check_async_task\` when the user explicitly asks for a status update or
+   result. If the status is "running", report that and stop — do not poll in a loop.
+3. **Update** (optional) — Use \`update_async_task\` to send new instructions to a running task. This interrupts
+   the current run and starts a fresh one on the same thread. The task_id stays the same.
+4. **Cancel** (optional) — Use \`cancel_async_task\` to stop a task that is no longer needed.
+5. **Collect** — When \`check_async_task\` returns status "success", the result is included in the response.
+6. **List** — Use \`list_async_tasks\` to see live statuses for all tasks at once, or to recall task IDs after context compaction.
+
+### Critical rules:
+- After launching, ALWAYS return control to the user immediately. Never auto-check after launching.
+- Never poll \`check_async_task\` in a loop. Check once per user request, then stop.
+- If a check returns "running", tell the user and wait for them to ask again.
+- Task statuses in conversation history are ALWAYS stale — a task that was "running" may now be done.
+  NEVER report a status from a previous tool result. ALWAYS call a tool to get the current status:
+  use \`list_async_tasks\` when the user asks about multiple tasks or "all tasks",
+  use \`check_async_task\` when the user asks about a specific task.
+- Always show the full task_id — never truncate or abbreviate it.
+
+### When to use async subagents:
+- Long-running tasks that would block the main agent
+- Tasks that benefit from running on specialized remote deployments
+- When you want to run multiple tasks concurrently and collect results later`;
+/**
+* Task statuses that will never change.
+*
+* When listing tasks, live-status fetches are skipped for tasks whose
+* cached status is in this set, since they are guaranteed to be final.
+*/
+const TERMINAL_STATUSES = new Set([
+	"cancelled",
+	"success",
+	"error",
+	"timeout",
+	"interrupted"
+]);
+/**
+* Look up a tracked task from state by its `taskId`.
+*
+* @param taskId - The task ID to look up (will be trimmed).
+* @param state - The current agent state containing `asyncTasks`.
+* @returns The tracked task on success, or an error string.
+*/
+function resolveTrackedTask(taskId, state) {
+	const tracked = (state.asyncTasks ?? {})[taskId.trim()];
+	if (!tracked) return `No tracked task found for taskId: '${taskId}'`;
+	return tracked;
+}
+/**
+* Build a check result from a run's current status and thread state values.
+*
+* For successful runs, extracts the last message's content from the remote
+* thread's state values. For errored runs, includes a generic error message.
+*
+* @param run - The run object from the SDK.
+* @param threadId - The thread ID for the run.
+* @param threadValues - The `values` from `ThreadState` (the remote subagent's state).
+*/
+function buildCheckResult(run, threadId, threadValues) {
+	const checkResult = {
+		status: run.status,
+		threadId
+	};
+	if (run.status === "success") {
+		const messages = (Array.isArray(threadValues) ? {} : threadValues)?.messages ?? [];
+		if (messages.length > 0) {
+			const last = messages[messages.length - 1];
+			const rawContent = typeof last === "object" && last !== null && "content" in last ? last.content : last;
+			checkResult.result = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent);
+		} else checkResult.result = "Completed with no output messages.";
+	} else if (run.status === "error") checkResult.error = "The async subagent encountered an error.";
+	return checkResult;
+}
+/**
+* Filter tasks by cached status from agent state.
+*
+* Filtering uses the cached status, not live server status. Live statuses
+* are fetched after filtering by the calling tool.
+*
+* @param tasks - All tracked tasks from state.
+* @param statusFilter - If nullish or `'all'`, return all tasks.
+*   Otherwise return only tasks whose cached status matches.
+*/
+function filterTasks(tasks, statusFilter) {
+	if (!statusFilter || statusFilter === "all") return Object.values(tasks);
+	return Object.values(tasks).filter((task) => task.status === statusFilter);
+}
+/**
+* Fetch the current run status from the server.
+*
+* Returns the cached status immediately for terminal tasks (avoiding
+* unnecessary API calls). Falls back to the cached status on SDK errors.
+*/
+async function fetchLiveTaskStatus(clients, task) {
+	if (TERMINAL_STATUSES.has(task.status)) return task.status;
+	try {
+		return (await clients.getClient(task.agentName).runs.get(task.threadId, task.runId)).status;
+	} catch {
+		return task.status;
+	}
+}
+/**
+* Format a single task as a display string for list output.
+*/
+function formatTaskEntry(task, status) {
+	return `- taskId: ${task.taskId} agent: ${task.agentName} status: ${status}`;
+}
+/**
+* Lazily-created, cached LangGraph SDK clients keyed by (url, headers).
+*
+* Agents that share the same URL and headers will reuse a single `Client`
+* instance, avoiding unnecessary connections.
+*/
+var ClientCache = class {
+	agents;
+	clients = /* @__PURE__ */ new Map();
+	constructor(agents) {
+		this.agents = agents;
+	}
+	/**
+	* Build headers for a remote LangGraph server, adding the default
+	* `x-auth-scheme: langsmith` header if not already present.
+	*/
+	resolveHeaders(spec) {
+		const headers = { ...spec.headers || {} };
+		if (!("x-auth-scheme" in headers)) headers["x-auth-scheme"] = "langsmith";
+		return headers;
+	}
+	/**
+	* Build a stable cache key from a spec's url and resolved headers.
+	*/
+	cacheKey(spec) {
+		const headers = this.resolveHeaders(spec);
+		const headerStr = Object.entries(headers).sort().flat().join(":");
+		return `${spec.url ?? ""}|${headerStr}`;
+	}
+	/**
+	* Get or create a `Client` for the named agent.
+	*/
+	getClient(name) {
+		const spec = this.agents[name];
+		const key = this.cacheKey(spec);
+		const existing = this.clients.get(key);
+		if (existing) return existing;
+		const headers = this.resolveHeaders(spec);
+		const client = new _langchain_langgraph_sdk.Client({
+			apiUrl: spec.url,
+			defaultHeaders: headers
+		});
+		this.clients.set(key, client);
+		return client;
+	}
+};
+/**
+* Build the `start_async_task` tool.
+*
+* Creates a thread on the remote server, starts a run, and returns a
+* `Command` that persists the new task in state.
+*/
+function buildStartTool(agentMap, clients, toolDescription) {
+	return (0, langchain.tool)(async (input, runtime) => {
+		if (!(input.agentName in agentMap)) {
+			const allowed = Object.keys(agentMap).map((k) => `\`${k}\``).join(", ");
+			return `Unknown async subagent type \`${input.agentName}\`. Available types: ${allowed}`;
+		}
+		const spec = agentMap[input.agentName];
+		try {
+			const client = clients.getClient(input.agentName);
+			const thread = await client.threads.create();
+			const run = await client.runs.create(thread.thread_id, spec.graphId, { input: { messages: [{
+				role: "user",
+				content: input.description
+			}] } });
+			const taskId = thread.thread_id;
+			const task = {
+				taskId,
+				agentName: input.agentName,
+				threadId: taskId,
+				runId: run.run_id,
+				status: "running",
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			return new _langchain_langgraph.Command({ update: {
+				messages: [new langchain.ToolMessage({
+					content: `Launched async subagent. taskId: ${taskId}`,
+					tool_call_id: toolCallIdFromRuntime(runtime)
+				})],
+				asyncTasks: { [taskId]: task }
+			} });
+		} catch (e) {
+			return `Failed to launch async subagent '${input.agentName}': ${e}`;
+		}
+	}, {
+		name: "start_async_task",
+		description: toolDescription,
+		schema: zod_v4.z.object({
+			description: zod_v4.z.string().describe("A detailed description of the task for the async subagent to perform."),
+			agentName: zod_v4.z.string().describe("The type of async subagent to use. Must be one of the available types listed in the tool description.")
+		})
+	});
+}
+/**
+* Build the `check_async_task` tool.
+*
+* Fetches the current run status from the remote server and, if the run
+* succeeded, retrieves the thread state to extract the result.
+*/
+function buildCheckTool(clients) {
+	return (0, langchain.tool)(async (input, runtime) => {
+		const task = resolveTrackedTask(input.taskId, runtime.state);
+		if (typeof task === "string") return task;
+		const client = clients.getClient(task.agentName);
+		let run;
+		try {
+			run = await client.runs.get(task.threadId, task.runId);
+		} catch (e) {
+			return `Failed to get run status: ${e}`;
+		}
+		let threadValues = {};
+		if (run.status === "success") try {
+			threadValues = (await client.threads.getState(task.threadId)).values || {};
+		} catch {}
+		const result = buildCheckResult(run, task.threadId, threadValues);
+		const updatedTask = {
+			taskId: task.taskId,
+			agentName: task.agentName,
+			threadId: task.threadId,
+			runId: task.runId,
+			status: result.status,
+			createdAt: task.createdAt,
+			updatedAt: task.updatedAt,
+			checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		return new _langchain_langgraph.Command({ update: {
+			messages: [new langchain.ToolMessage({
+				content: JSON.stringify(result),
+				tool_call_id: toolCallIdFromRuntime(runtime)
+			})],
+			asyncTasks: { [task.taskId]: updatedTask }
+		} });
+	}, {
+		name: "check_async_task",
+		description: "Check the status of an async subagent task. Returns the current status and, if complete, the result.",
+		schema: zod_v4.z.object({ taskId: zod_v4.z.string().describe("The exact taskId string returned by start_async_task. Pass it verbatim.") })
+	});
+}
+/**
+* Build the `update_async_task` tool.
+*
+* Sends a follow-up message to a running async subagent by creating a new
+* run on the same thread with `multitaskStrategy: "interrupt"`. The subagent
+* sees the full conversation history plus the new message. The `taskId`
+* remains the same; only the internal `runId` is updated.
+*/
+function buildUpdateTool(agentMap, clients) {
+	return (0, langchain.tool)(async (input, runtime) => {
+		const tracked = resolveTrackedTask(input.taskId, runtime.state);
+		if (typeof tracked === "string") return tracked;
+		const spec = agentMap[tracked.agentName];
+		try {
+			const run = await clients.getClient(tracked.agentName).runs.create(tracked.threadId, spec.graphId, {
+				input: { messages: [{
+					role: "user",
+					content: input.message
+				}] },
+				multitaskStrategy: "interrupt"
+			});
+			const task = {
+				taskId: tracked.taskId,
+				agentName: tracked.agentName,
+				threadId: tracked.threadId,
+				runId: run.run_id,
+				status: "running",
+				createdAt: tracked.createdAt,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				checkedAt: tracked.checkedAt
+			};
+			return new _langchain_langgraph.Command({ update: {
+				messages: [new langchain.ToolMessage({
+					content: `Updated async subagent. taskId: ${tracked.taskId}`,
+					tool_call_id: toolCallIdFromRuntime(runtime)
+				})],
+				asyncTasks: { [tracked.taskId]: task }
+			} });
+		} catch (e) {
+			return `Failed to update async subagent: ${e}`;
+		}
+	}, {
+		name: "update_async_task",
+		description: "send updated instructions to an async subagent. Interrupts the current run and starts a new one on the same thread so the subagent sees the full conversation history plus your new message. The taskId remains the same.",
+		schema: zod_v4.z.object({
+			taskId: zod_v4.z.string().describe("The exact taskId string returned by start_async_task. Pass it verbatim."),
+			message: zod_v4.z.string().describe("Follow-up instructions or context to send to the subagent")
+		})
+	});
+}
+/**
+* Build the `cancel_async_task` tool.
+*
+* Cancels the current run on the remote server and updates the task's
+* cached status to `"cancelled"`.
+*/
+function buildCancelTool(clients) {
+	return (0, langchain.tool)(async (input, runtime) => {
+		const tracked = resolveTrackedTask(input.taskId, runtime.state);
+		if (typeof tracked === "string") return tracked;
+		const client = clients.getClient(tracked.agentName);
+		try {
+			await client.runs.cancel(tracked.threadId, tracked.runId);
+		} catch (e) {
+			return `Failed to cancel run: ${e}`;
+		}
+		const updated = {
+			taskId: tracked.taskId,
+			agentName: tracked.agentName,
+			threadId: tracked.threadId,
+			runId: tracked.runId,
+			status: "cancelled",
+			createdAt: tracked.createdAt,
+			updatedAt: tracked.updatedAt,
+			checkedAt: tracked.checkedAt
+		};
+		return new _langchain_langgraph.Command({ update: {
+			messages: [new langchain.ToolMessage({
+				content: `Cancelled async subagent task: ${tracked.taskId}`,
+				tool_call_id: toolCallIdFromRuntime(runtime)
+			})],
+			asyncTasks: { [tracked.taskId]: updated }
+		} });
+	}, {
+		name: "cancel_async_task",
+		description: "Cancel a running async subagent task. Use this to stop a task that is no longer needed.",
+		schema: zod_v4.z.object({ taskId: zod_v4.z.string().describe("The exact taskId string returned by start_async_task. Pass it verbatim.") })
+	});
+}
+/**
+* Build the `list_async_tasks` tool.
+*
+* Lists all tracked tasks with their live statuses fetched in parallel.
+* Supports optional filtering by cached status.
+*/
+function buildListTool(clients) {
+	return (0, langchain.tool)(async (input, runtime) => {
+		const filtered = filterTasks(runtime.state.asyncTasks ?? {}, input.statusFilter ?? void 0);
+		if (filtered.length === 0) return "No async subagent tasks tracked";
+		const statuses = await Promise.all(filtered.map((task) => fetchLiveTaskStatus(clients, task)));
+		const updatedTasks = {};
+		const entries = [];
+		for (let idx = 0; idx < filtered.length; idx++) {
+			const task = filtered[idx];
+			const status = statuses[idx];
+			const taskEntry = formatTaskEntry(task, status);
+			entries.push(taskEntry);
+			updatedTasks[task.taskId] = {
+				taskId: task.taskId,
+				agentName: task.agentName,
+				threadId: task.threadId,
+				runId: task.runId,
+				status,
+				createdAt: task.createdAt,
+				updatedAt: task.updatedAt,
+				checkedAt: task.checkedAt
+			};
+		}
+		return new _langchain_langgraph.Command({ update: {
+			messages: [new langchain.ToolMessage({
+				content: `${entries.length} tracked task(s):\n${entries.join("\n")}`,
+				tool_call_id: toolCallIdFromRuntime(runtime)
+			})],
+			asyncTasks: updatedTasks
+		} });
+	}, {
+		name: "list_async_tasks",
+		description: "List tracked async subagent tasks with their current live statuses. Be default shows all tasks. Use `statusFilter` to narrow by status (e.g., 'running', 'success', 'error', 'cancelled'). Use `check_async_task` to get the full result of a specific completed task.",
+		schema: zod_v4.z.object({ statusFilter: zod_v4.z.string().nullish().describe("Filter tasks by status. One of: 'running', 'success', 'error', 'cancelled', 'all'. Defaults to 'all'.") })
+	});
+}
+/**
+* Create middleware that adds async subagent tools to an agent.
+*
+* Provides five tools for launching, checking, updating, cancelling, and
+* listing background tasks on remote LangGraph deployments. Task state is
+* persisted in the `asyncTasks` state channel so it survives
+* context compaction.
+*
+* @throws {Error} If no async subagents are provided or names are duplicated.
+*
+* @example
+* ```ts
+* const middleware = createAsyncSubAgentMiddleware({
+*   asyncSubAgents: [{
+*     name: "researcher",
+*     description: "Research agent for deep analysis",
+*     url: "https://my-deployment.langsmith.dev",
+*     graphId: "research_agent",
+*   }],
+* });
+* ```
+*/
+/**
+* Type guard to distinguish async SubAgents from sync SubAgents/CompiledSubAgents.
+*
+* Uses the presence of the `graphId` field as the runtime discriminant —
+* `AsyncSubAgent` requires it, while `SubAgent` and `CompiledSubAgent` do not have it.
+*/
+function isAsyncSubAgent(subAgent) {
+	return "graphId" in subAgent;
+}
+function createAsyncSubAgentMiddleware(options) {
+	const { asyncSubAgents, systemPrompt = ASYNC_TASK_SYSTEM_PROMPT } = options;
+	if (!asyncSubAgents || asyncSubAgents.length === 0) throw new Error("At least one async subagent must be specified");
+	const names = asyncSubAgents.map((a) => a.name);
+	const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
+	if (duplicates.length > 0) throw new Error(`Duplicate async subagent names: ${[...new Set(duplicates)].join(", ")}`);
+	const agentMap = Object.fromEntries(asyncSubAgents.map((a) => [a.name, a]));
+	const clients = new ClientCache(agentMap);
+	const agentsDescription = asyncSubAgents.map((a) => `- ${a.name}: ${a.description}`).join("\n");
+	const tools = [
+		buildStartTool(agentMap, clients, ASYNC_TASK_TOOL_DESCRIPTION.replace("{available_agents}", agentsDescription)),
+		buildCheckTool(clients),
+		buildUpdateTool(agentMap, clients),
+		buildCancelTool(clients),
+		buildListTool(clients)
+	];
+	const fullSystemPrompt = systemPrompt ? `${systemPrompt}\n\nAvailable async subagent types:\n${agentsDescription}` : null;
+	return (0, langchain.createMiddleware)({
+		name: "asyncSubAgentMiddleware",
+		stateSchema: AsyncTaskStateSchema,
+		tools,
+		wrapModelCall: async (request, handler) => {
+			if (fullSystemPrompt !== null) return handler({
+				...request,
+				systemMessage: request.systemMessage.concat(new langchain.SystemMessage({ content: fullSystemPrompt }))
+			});
+			return handler(request);
+		}
+	});
+}
+//#endregion
+//#region src/backends/store.ts
+const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
+/**
+* Validate a namespace array.
+*
+* Each component must be a non-empty string containing only safe characters:
+* alphanumeric (a-z, A-Z, 0-9), hyphen (-), underscore (_), dot (.),
+* at sign (@), plus (+), colon (:), and tilde (~).
+*
+* Characters like *, ?, [, ], {, } etc. are rejected to prevent
+* wildcard or glob injection in store lookups.
+*/
+function validateNamespace(namespace) {
+	if (namespace.length === 0) throw new Error("Namespace array must not be empty.");
+	for (let i = 0; i < namespace.length; i++) {
+		const component = namespace[i];
+		if (typeof component !== "string") throw new TypeError(`Namespace component at index ${i} must be a string, got ${typeof component}.`);
+		if (!component) throw new Error(`Namespace component at index ${i} must not be empty.`);
+		if (!NAMESPACE_COMPONENT_RE.test(component)) throw new Error(`Namespace component at index ${i} contains disallowed characters: "${component}". Only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes are allowed.`);
+	}
+	return namespace;
+}
+/**
+* Backend that stores files in LangGraph's BaseStore (persistent).
 *
 * Uses LangGraph's Store for persistent, cross-conversation storage.
 * Files are organized via namespaces and persist across all threads.
@@ -3029,9 +4056,11 @@ function validateNamespace(namespace) {
 var StoreBackend = class {
 	stateAndStore;
 	_namespace;
+	fileFormat;
 	constructor(stateAndStore, options) {
 		this.stateAndStore = stateAndStore;
 		if (options?.namespace) this._namespace = validateNamespace(options.namespace);
+		this.fileFormat = options?.fileFormat ?? "v2";
 	}
 	/**
 	* Get the store instance.
@@ -3068,9 +4097,10 @@ var StoreBackend = class {
 	*/
 	convertStoreItemToFileData(storeItem) {
 		const value = storeItem.value;
-		if (!value.content || !Array.isArray(value.content) || typeof value.created_at !== "string" || typeof value.modified_at !== "string") throw new Error(`Store item does not contain valid FileData fields. Got keys: ${Object.keys(value).join(", ")}`);
+		if (!(value.content !== void 0 && (Array.isArray(value.content) || typeof value.content === "string" || ArrayBuffer.isView(value.content))) || typeof value.created_at !== "string" || typeof value.modified_at !== "string") throw new Error(`Store item does not contain valid FileData fields. Got keys: ${Object.keys(value).join(", ")}`);
 		return {
 			content: value.content,
+			...value.mimeType ? { mimeType: value.mimeType } : {},
 			created_at: value.created_at,
 			modified_at: value.modified_at
 		};
@@ -3079,11 +4109,12 @@ var StoreBackend = class {
 	* Convert FileData to a value suitable for store.put().
 	*
 	* @param fileData - The FileData to convert
-	* @returns Object with content, created_at, and modified_at fields
+	* @returns Object with content, mimeType, created_at, and modified_at fields
 	*/
 	convertFileDataToStoreValue(fileData) {
 		return {
 			content: fileData.content,
+			..."mimeType" in fileData ? { mimeType: fileData.mimeType } : {},
 			created_at: fileData.created_at,
 			modified_at: fileData.modified_at
 		};
@@ -3118,10 +4149,10 @@ var StoreBackend = class {
 	* List files and directories in the specified directory (non-recursive).
 	*
 	* @param path - Absolute path to directory
-	* @returns List of FileInfo objects for files and directories directly in the directory.
+	* @returns LsResult with list of FileInfo objects on success or error on failure.
 	*          Directories have a trailing / in their path and is_dir=true.
 	*/
-	async lsInfo(path) {
+	async ls(path) {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
@@ -3139,7 +4170,7 @@ var StoreBackend = class {
 			}
 			try {
 				const fd = this.convertStoreItemToFileData(item);
-				const size = fd.content.join("\n").length;
+				const size = isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length;
 				infos.push({
 					path: itemKey,
 					is_dir: false,
@@ -3157,35 +4188,49 @@ var StoreBackend = class {
 			modified_at: ""
 		});
 		infos.sort((a, b) => a.path.localeCompare(b.path));
-		return infos;
+		return { files: infos };
 	}
 	/**
-	* Read file content with line numbers.
+	* Read file content.
+	*
+	* Text files are paginated by line offset/limit.
+	* Binary files return full Uint8Array content (offset/limit ignored).
 	*
 	* @param filePath - Absolute file path
 	* @param offset - Line offset to start reading from (0-indexed)
 	* @param limit - Maximum number of lines to read
-	* @returns Formatted file content with line numbers, or error message
+	* @returns ReadResult with content on success or error on failure
 	*/
 	async read(filePath, offset = 0, limit = 500) {
 		try {
-			return formatReadResponse(await this.readRaw(filePath), offset, limit);
+			const readRawResult = await this.readRaw(filePath);
+			if (readRawResult.error || !readRawResult.data) return { error: readRawResult.error || "File data not found" };
+			const fileDataV2 = migrateToFileDataV2(readRawResult.data, filePath);
+			if (!isTextMimeType(fileDataV2.mimeType)) return {
+				content: fileDataV2.content,
+				mimeType: fileDataV2.mimeType
+			};
+			if (typeof fileDataV2.content !== "string") return { error: `File '${filePath}' has binary content but text MIME type` };
+			return {
+				content: fileDataV2.content.split("\n").slice(offset, offset + limit).join("\n"),
+				mimeType: fileDataV2.mimeType
+			};
 		} catch (e) {
-			return `Error: ${e.message}`;
+			return { error: e.message };
 		}
 	}
 	/**
 	* Read file content as raw FileData.
 	*
 	* @param filePath - Absolute file path
-	* @returns Raw file content as FileData
+	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const item = await store.get(namespace, filePath);
-		if (!item) throw new Error(`File '${filePath}' not found`);
-		return this.convertStoreItemToFileData(item);
+		if (!item) return { error: `File '${filePath}' not found` };
+		return { data: this.convertStoreItemToFileData(item) };
 	}
 	/**
 	* Create a new file with content.
@@ -3195,7 +4240,8 @@ var StoreBackend = class {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		if (await store.get(namespace, filePath)) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
-		const fileData = createFileData(content);
+		const mimeType = getMimeType(filePath);
+		const fileData = createFileData(content, void 0, this.fileFormat, mimeType);
 		const storeValue = this.convertFileDataToStoreValue(fileData);
 		await store.put(namespace, filePath, storeValue);
 		return {
@@ -3230,9 +4276,10 @@ var StoreBackend = class {
 		}
 	}
 	/**
-	* Structured search results or error string for invalid input.
+	* Search file contents for a literal text pattern.
+	* Binary files are skipped.
 	*/
-	async grepRaw(pattern, path = "/", glob = null) {
+	async grep(pattern, path = "/", glob = null) {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
@@ -3242,12 +4289,12 @@ var StoreBackend = class {
 		} catch {
 			continue;
 		}
-		return grepMatchesFromFiles(files, pattern, path, glob);
+		return { matches: grepMatchesFromFiles(files, pattern, path, glob) };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, path = "/") {
+	async glob(pattern, path = "/") {
 		const store = this.getStore();
 		const namespace = this.getNamespace();
 		const items = await this.searchStorePaginated(store, namespace);
@@ -3258,12 +4305,12 @@ var StoreBackend = class {
 			continue;
 		}
 		const result = globSearchFiles(files, pattern, path);
-		if (result === "No files found") return [];
+		if (result === "No files found") return { files: [] };
 		const paths = result.split("\n");
 		const infos = [];
 		for (const p of paths) {
 			const fd = files[p];
-			const size = fd ? fd.content.join("\n").length : 0;
+			const size = fd ? isFileDataV1(fd) ? fd.content.join("\n").length : isFileDataBinary(fd) ? fd.content.byteLength : fd.content.length : 0;
 			infos.push({
 				path: p,
 				is_dir: false,
@@ -3271,7 +4318,7 @@ var StoreBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -3284,7 +4331,11 @@ var StoreBackend = class {
 		const namespace = this.getNamespace();
 		const responses = [];
 		for (const [path, content] of files) try {
-			const fileData = createFileData(new TextDecoder().decode(content));
+			const mimeType = getMimeType(path);
+			const isBinary = this.fileFormat === "v2" && !isTextMimeType(mimeType);
+			let fileData;
+			if (isBinary) fileData = createFileData(content, void 0, "v2", mimeType);
+			else fileData = createFileData(new TextDecoder().decode(content), void 0, this.fileFormat, mimeType);
 			const storeValue = this.convertFileDataToStoreValue(fileData);
 			await store.put(namespace, path, storeValue);
 			responses.push({
@@ -3319,11 +4370,17 @@ var StoreBackend = class {
 				});
 				continue;
 			}
-			const contentStr = fileDataToString(this.convertStoreItemToFileData(item));
-			const content = new TextEncoder().encode(contentStr);
-			responses.push({
+			const fileDataV2 = migrateToFileDataV2(this.convertStoreItemToFileData(item), path);
+			if (typeof fileDataV2.content === "string") {
+				const content = new TextEncoder().encode(fileDataV2.content);
+				responses.push({
+					path,
+					content,
+					error: null
+				});
+			} else responses.push({
 				path,
-				content,
+				content: fileDataV2.content,
 				error: null
 			});
 		} catch {
@@ -3336,7 +4393,6 @@ var StoreBackend = class {
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/backends/filesystem.ts
 /**
@@ -3397,10 +4453,10 @@ var FilesystemBackend = 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(dirPath) {
+	async ls(dirPath) {
 		try {
 			const resolvedPath = this.resolvePath(dirPath);
-			if (!(await node_fs_promises.default.stat(resolvedPath)).isDirectory()) return [];
+			if (!(await node_fs_promises.default.stat(resolvedPath)).isDirectory()) return { files: [] };
 			const entries = await node_fs_promises.default.readdir(resolvedPath, { withFileTypes: true });
 			const results = [];
 			const cwdStr = this.cwd.endsWith(node_path.default.sep) ? this.cwd : this.cwd + node_path.default.sep;
@@ -3448,9 +4504,9 @@ var FilesystemBackend = class {
 				}
 			}
 			results.sort((a, b) => a.path.localeCompare(b.path));
-			return results;
+			return { files: results };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 	}
 	/**
@@ -3464,62 +4520,105 @@ var FilesystemBackend = class {
 	async read(filePath, offset = 0, limit = 500) {
 		try {
 			const resolvedPath = this.resolvePath(filePath);
+			const mimeType = getMimeType(filePath);
+			const isBinary = !isTextMimeType(mimeType);
 			let content;
 			if (SUPPORTS_NOFOLLOW) {
-				if (!(await node_fs_promises.default.stat(resolvedPath)).isFile()) return `Error: File '${filePath}' not found`;
+				if (!(await node_fs_promises.default.stat(resolvedPath)).isFile()) return { error: `File '${filePath}' not found` };
 				const fd = await node_fs_promises.default.open(resolvedPath, node_fs.default.constants.O_RDONLY | node_fs.default.constants.O_NOFOLLOW);
 				try {
+					if (isBinary) {
+						const buffer = await fd.readFile();
+						return {
+							content: new Uint8Array(buffer),
+							mimeType
+						};
+					}
 					content = await fd.readFile({ encoding: "utf-8" });
 				} finally {
 					await fd.close();
 				}
 			} else {
 				const stat = await node_fs_promises.default.lstat(resolvedPath);
-				if (stat.isSymbolicLink()) return `Error: Symlinks are not allowed: ${filePath}`;
-				if (!stat.isFile()) return `Error: File '${filePath}' not found`;
+				if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+				if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+				if (isBinary) {
+					const buffer = await node_fs_promises.default.readFile(resolvedPath);
+					return {
+						content: new Uint8Array(buffer),
+						mimeType
+					};
+				}
 				content = await node_fs_promises.default.readFile(resolvedPath, "utf-8");
 			}
 			const emptyMsg = checkEmptyContent(content);
-			if (emptyMsg) return emptyMsg;
+			if (emptyMsg) return {
+				content: emptyMsg,
+				mimeType
+			};
 			const lines = content.split("\n");
 			const startIdx = offset;
 			const endIdx = Math.min(startIdx + limit, lines.length);
-			if (startIdx >= lines.length) return `Error: Line offset ${offset} exceeds file length (${lines.length} lines)`;
-			return formatContentWithLineNumbers(lines.slice(startIdx, endIdx), startIdx + 1);
+			if (startIdx >= lines.length) return { error: `Line offset ${offset} exceeds file length (${lines.length} lines)` };
+			return {
+				content: lines.slice(startIdx, endIdx).join("\n"),
+				mimeType
+			};
 		} catch (e) {
-			return `Error reading file '${filePath}': ${e.message}`;
+			return { error: `Error reading file '${filePath}': ${e.message}` };
 		}
 	}
 	/**
 	* Read file content as raw FileData.
 	*
 	* @param filePath - Absolute file path
-	* @returns Raw file content as FileData
+	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
 		const resolvedPath = this.resolvePath(filePath);
+		const mimeType = getMimeType(filePath);
+		const isBinary = !isTextMimeType(mimeType);
 		let content;
 		let stat;
 		if (SUPPORTS_NOFOLLOW) {
 			stat = await node_fs_promises.default.stat(resolvedPath);
-			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
 			const fd = await node_fs_promises.default.open(resolvedPath, node_fs.default.constants.O_RDONLY | node_fs.default.constants.O_NOFOLLOW);
 			try {
+				if (isBinary) {
+					const buffer = await fd.readFile();
+					return { data: {
+						content: new Uint8Array(buffer),
+						mimeType,
+						created_at: stat.ctime.toISOString(),
+						modified_at: stat.mtime.toISOString()
+					} };
+				}
 				content = await fd.readFile({ encoding: "utf-8" });
 			} finally {
 				await fd.close();
 			}
 		} else {
 			stat = await node_fs_promises.default.lstat(resolvedPath);
-			if (stat.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${filePath}`);
-			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			if (stat.isSymbolicLink()) return { error: `Symlinks are not allowed: ${filePath}` };
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
+			if (isBinary) {
+				const buffer = await node_fs_promises.default.readFile(resolvedPath);
+				return { data: {
+					content: new Uint8Array(buffer),
+					mimeType,
+					created_at: stat.ctime.toISOString(),
+					modified_at: stat.mtime.toISOString()
+				} };
+			}
 			content = await node_fs_promises.default.readFile(resolvedPath, "utf-8");
 		}
-		return {
-			content: content.split("\n"),
+		return { data: {
+			content,
+			mimeType,
 			created_at: stat.ctime.toISOString(),
 			modified_at: stat.mtime.toISOString()
-		};
+		} };
 	}
 	/**
 	* Create a new file with content.
@@ -3528,6 +4627,7 @@ var FilesystemBackend = class {
 	async write(filePath, content) {
 		try {
 			const resolvedPath = this.resolvePath(filePath);
+			const isBinary = !isTextMimeType(getMimeType(filePath));
 			try {
 				if ((await node_fs_promises.default.lstat(resolvedPath)).isSymbolicLink()) return { error: `Cannot write to ${filePath} because it is a symlink. Symlinks are not allowed.` };
 				return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
@@ -3537,10 +4637,16 @@ var FilesystemBackend = class {
 				const flags = node_fs.default.constants.O_WRONLY | node_fs.default.constants.O_CREAT | node_fs.default.constants.O_TRUNC | node_fs.default.constants.O_NOFOLLOW;
 				const fd = await node_fs_promises.default.open(resolvedPath, flags, 420);
 				try {
-					await fd.writeFile(content, "utf-8");
+					if (isBinary) {
+						const buffer = Buffer.from(content, "base64");
+						await fd.writeFile(buffer);
+					} else await fd.writeFile(content, "utf-8");
 				} finally {
 					await fd.close();
 				}
+			} else if (isBinary) {
+				const buffer = Buffer.from(content, "base64");
+				await node_fs_promises.default.writeFile(resolvedPath, buffer);
 			} else await node_fs_promises.default.writeFile(resolvedPath, content, "utf-8");
 			return {
 				path: filePath,
@@ -3603,17 +4709,17 @@ var FilesystemBackend = class {
 	* @param glob - Optional glob pattern to filter which files to search.
 	* @returns List of GrepMatch dicts containing path, line number, and matched text.
 	*/
-	async grepRaw(pattern, dirPath = "/", glob = null) {
+	async grep(pattern, dirPath = "/", glob = null) {
 		let baseFull;
 		try {
 			baseFull = this.resolvePath(dirPath || ".");
 		} catch {
-			return [];
+			return { matches: [] };
 		}
 		try {
 			await node_fs_promises.default.stat(baseFull);
 		} catch {
-			return [];
+			return { matches: [] };
 		}
 		let results = await this.ripgrepSearch(pattern, baseFull, glob);
 		if (results === null) results = await this.literalSearch(pattern, baseFull, glob);
@@ -3623,7 +4729,7 @@ var FilesystemBackend = class {
 			line: lineNum,
 			text: lineText
 		});
-		return matches;
+		return { matches };
 	}
 	/**
 	* Search using ripgrep with fixed-string (literal) mode.
@@ -3703,6 +4809,7 @@ var FilesystemBackend = class {
 			dot: true
 		});
 		for (const fp of files) try {
+			if (!isTextMimeType(getMimeType(fp))) continue;
 			if (includeGlob && !micromatch.default.isMatch(node_path.default.basename(fp), includeGlob)) continue;
 			if ((await node_fs_promises.default.stat(fp)).size > this.maxFileSizeBytes) continue;
 			const lines = (await node_fs_promises.default.readFile(fp, "utf-8")).split("\n");
@@ -3730,13 +4837,13 @@ var FilesystemBackend = class {
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, searchPath = "/") {
+	async glob(pattern, searchPath = "/") {
 		if (pattern.startsWith("/")) pattern = pattern.substring(1);
 		const resolvedSearchPath = searchPath === "/" ? this.cwd : this.resolvePath(searchPath);
 		try {
-			if (!(await node_fs_promises.default.stat(resolvedSearchPath)).isDirectory()) return [];
+			if (!(await node_fs_promises.default.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 		const results = [];
 		try {
@@ -3776,7 +4883,7 @@ var FilesystemBackend = class {
 			}
 		} catch {}
 		results.sort((a, b) => a.path.localeCompare(b.path));
-		return results;
+		return { files: results };
 	}
 	/**
 	* Upload multiple files to the filesystem.
@@ -3855,7 +4962,6 @@ var FilesystemBackend = class {
 		return responses;
 	}
 };
-
 //#endregion
 //#region src/backends/composite.ts
 /**
@@ -3872,9 +4978,9 @@ var CompositeBackend = class {
 	routes;
 	sortedRoutes;
 	constructor(defaultBackend, routes) {
-		this.default = defaultBackend;
-		this.routes = routes;
-		this.sortedRoutes = Object.entries(routes).sort((a, b) => b[0].length - a[0].length);
+		this.default = isSandboxProtocol(defaultBackend) ? adaptSandboxProtocol(defaultBackend) : adaptBackendProtocol(defaultBackend);
+		this.routes = Object.fromEntries(Object.entries(routes).map(([k, v]) => [k, isSandboxProtocol(v) ? adaptSandboxProtocol(v) : adaptBackendProtocol(v)]));
+		this.sortedRoutes = Object.entries(this.routes).sort((a, b) => b[0].length - a[0].length);
 	}
 	/** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
 	get id() {
@@ -3898,25 +5004,27 @@ var CompositeBackend = class {
 	* List files and directories in the specified directory (non-recursive).
 	*
 	* @param path - Absolute path to directory
-	* @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.
+	* @returns LsResult with list of FileInfo objects (with route prefixes added) on success or error on failure.
+	*          Directories have a trailing / in their path and is_dir=true.
 	*/
-	async lsInfo(path) {
+	async ls(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 result = await backend.ls(searchPath);
+			if (result.error) return result;
 			const prefixed = [];
-			for (const fi of infos) prefixed.push({
+			for (const fi of result.files || []) prefixed.push({
 				...fi,
 				path: routePrefix.slice(0, -1) + fi.path
 			});
-			return prefixed;
+			return { files: prefixed };
 		}
 		if (path === "/") {
 			const results = [];
-			const defaultInfos = await this.default.lsInfo(path);
-			results.push(...defaultInfos);
+			const defaultResult = await this.default.ls(path);
+			if (defaultResult.error) return defaultResult;
+			results.push(...defaultResult.files || []);
 			for (const [routePrefix] of this.sortedRoutes) results.push({
 				path: routePrefix,
 				is_dir: true,
@@ -3924,9 +5032,9 @@ var CompositeBackend = class {
 				modified_at: ""
 			});
 			results.sort((a, b) => a.path.localeCompare(b.path));
-			return results;
+			return { files: results };
 		}
-		return await this.default.lsInfo(path);
+		return await this.default.ls(path);
 	}
 	/**
 	* Read file content, routing to appropriate backend.
@@ -3944,7 +5052,7 @@ var CompositeBackend = class {
 	* Read file content as raw FileData.
 	*
 	* @param filePath - Absolute file path
-	* @returns Raw file content as FileData
+	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
 		const [backend, strippedKey] = this.getBackendAndKey(filePath);
@@ -3953,53 +5061,59 @@ var CompositeBackend = class {
 	/**
 	* Structured search results or error string for invalid input.
 	*/
-	async grepRaw(pattern, path = "/", glob = null) {
+	async grep(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) => ({
+			const raw = await backend.grep(pattern, searchPath || "/", glob);
+			if (raw.error) return raw;
+			return { matches: (raw.matches || []).map((m) => ({
 				...m,
 				path: routePrefix.slice(0, -1) + m.path
-			}));
+			})) };
 		}
 		const allMatches = [];
-		const rawDefault = await this.default.grepRaw(pattern, path, glob);
-		if (typeof rawDefault === "string") return rawDefault;
-		allMatches.push(...rawDefault);
+		const rawDefault = await this.default.grep(pattern, path, glob);
+		if (rawDefault.error) return rawDefault;
+		allMatches.push(...rawDefault.matches || []);
 		for (const [routePrefix, backend] of Object.entries(this.routes)) {
-			const raw = await backend.grepRaw(pattern, "/", glob);
-			if (typeof raw === "string") return raw;
-			allMatches.push(...raw.map((m) => ({
+			const raw = await backend.grep(pattern, "/", glob);
+			if (raw.error) return raw;
+			const matches = (raw.matches || []).map((m) => ({
 				...m,
 				path: routePrefix.slice(0, -1) + m.path
-			})));
+			}));
+			allMatches.push(...matches);
 		}
-		return allMatches;
+		return { matches: allMatches };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
 	*/
-	async globInfo(pattern, path = "/") {
+	async glob(pattern, path = "/") {
 		const results = [];
 		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) => ({
+			const result = await backend.glob(pattern, searchPath || "/");
+			if (result.error) return result;
+			return { files: (result.files || []).map((fi) => ({
 				...fi,
 				path: routePrefix.slice(0, -1) + fi.path
-			}));
+			})) };
 		}
-		const defaultInfos = await this.default.globInfo(pattern, path);
-		results.push(...defaultInfos);
+		const defaultResult = await this.default.glob(pattern, path);
+		if (defaultResult.error) return defaultResult;
+		results.push(...defaultResult.files || []);
 		for (const [routePrefix, backend] of Object.entries(this.routes)) {
-			const infos = await backend.globInfo(pattern, "/");
-			results.push(...infos.map((fi) => ({
+			const result = await backend.glob(pattern, "/");
+			if (result.error) continue;
+			const files = (result.files || []).map((fi) => ({
 				...fi,
 				path: routePrefix.slice(0, -1) + fi.path
-			})));
+			}));
+			results.push(...files);
 		}
 		results.sort((a, b) => a.path.localeCompare(b.path));
-		return results;
+		return { files: results };
 	}
 	/**
 	* Create a new file, routing to appropriate backend.
@@ -4104,7 +5218,6 @@ var CompositeBackend = class {
 		return results;
 	}
 };
-
 //#endregion
 //#region src/backends/local-shell.ts
 /**
@@ -4228,7 +5341,7 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 	*/
 	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`;
+		if (result.error?.includes("ENOENT")) return { error: `File '${filePath}' not found` };
 		return result;
 	}
 	/**
@@ -4245,25 +5358,26 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 	/**
 	* List directory contents, returning paths relative to rootDir.
 	*/
-	async lsInfo(dirPath) {
-		const results = await super.lsInfo(dirPath);
-		if (this.virtualMode) return results;
+	async ls(dirPath) {
+		const result = await super.ls(dirPath);
+		if (result.error) return result;
+		if (this.virtualMode) return result;
 		const cwdPrefix = this.cwd.endsWith(node_path.default.sep) ? this.cwd : this.cwd + node_path.default.sep;
-		return results.map((info) => ({
+		return { files: (result.files || []).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 = "/") {
+	async glob(pattern, searchPath = "/") {
 		if (pattern.startsWith("/")) pattern = pattern.substring(1);
 		const resolvedSearchPath = searchPath === "/" || searchPath === "" ? this.cwd : this.virtualMode ? node_path.default.resolve(this.cwd, searchPath.replace(/^\//, "")) : node_path.default.resolve(this.cwd, searchPath);
 		try {
-			if (!(await node_fs_promises.default.stat(resolvedSearchPath)).isDirectory()) return [];
+			if (!(await node_fs_promises.default.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 		const formatPath = (rel) => this.virtualMode ? `/${rel}` : rel;
 		const globOpts = {
@@ -4305,7 +5419,7 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 		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;
+		return { files: results };
 	}
 	/**
 	* Execute a shell command directly on the host system.
@@ -4409,7 +5523,6 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 		return backend;
 	}
 };
-
 //#endregion
 //#region src/backends/sandbox.ts
 /**
@@ -4581,9 +5694,9 @@ var BaseSandbox = class {
 	* including Alpine. No Python or Node.js needed.
 	*
 	* @param path - Absolute path to directory
-	* @returns List of FileInfo objects for files and directories directly in the directory.
+	* @returns LsResult with list of FileInfo objects on success or error on failure.
 	*/
-	async lsInfo(path) {
+	async ls(path) {
 		const command = buildLsCommand(path);
 		const result = await this.execute(command);
 		const infos = [];
@@ -4598,7 +5711,7 @@ var BaseSandbox = class {
 				modified_at: (/* @__PURE__ */ new Date(parsed.mtime * 1e3)).toISOString()
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Read file content with line numbers.
@@ -4613,11 +5726,26 @@ var BaseSandbox = class {
 	* @returns Formatted file content with line numbers, or error message
 	*/
 	async read(filePath, offset = 0, limit = 500) {
-		if (limit === 0) return "";
+		const mimeType = getMimeType(filePath);
+		if (!isTextMimeType(mimeType)) {
+			const results = await this.downloadFiles([filePath]);
+			if (results[0].error || !results[0].content) return { error: `File '${filePath}' not found` };
+			return {
+				content: results[0].content,
+				mimeType
+			};
+		}
+		if (limit === 0) return {
+			content: "",
+			mimeType
+		};
 		const command = buildReadCommand(filePath, offset, limit);
 		const result = await this.execute(command);
-		if (result.exitCode !== 0) return `Error: File '${filePath}' not found`;
-		return result.output;
+		if (result.exitCode !== 0) return { error: `File '${filePath}' not found` };
+		return {
+			content: result.output,
+			mimeType
+		};
 	}
 	/**
 	* Read file content as raw FileData.
@@ -4625,18 +5753,25 @@ var BaseSandbox = class {
 	* Uses downloadFiles() directly — no runtime needed on the sandbox host.
 	*
 	* @param filePath - Absolute file path
-	* @returns Raw file content as FileData
+	* @returns ReadRawResult with raw file data on success or error on failure
 	*/
 	async readRaw(filePath) {
 		const results = await this.downloadFiles([filePath]);
-		if (results[0].error || !results[0].content) throw new Error(`File '${filePath}' not found`);
-		const lines = new TextDecoder().decode(results[0].content).split("\n");
+		if (results[0].error || !results[0].content) return { error: `File '${filePath}' not found` };
 		const now = (/* @__PURE__ */ new Date()).toISOString();
-		return {
-			content: lines,
+		const mimeType = getMimeType(filePath);
+		if (!isTextMimeType(mimeType)) return { data: {
+			content: results[0].content,
+			mimeType,
 			created_at: now,
 			modified_at: now
-		};
+		} };
+		return { data: {
+			content: new TextDecoder().decode(results[0].content),
+			mimeType,
+			created_at: now,
+			modified_at: now
+		} };
 	}
 	/**
 	* Search for a literal text pattern in files using grep.
@@ -4646,23 +5781,25 @@ var BaseSandbox = class {
 	* @param glob - Optional glob pattern to filter which files to search.
 	* @returns List of GrepMatch dicts containing path, line number, and matched text.
 	*/
-	async grepRaw(pattern, path = "/", glob = null) {
+	async grep(pattern, path = "/", glob = null) {
 		const command = buildGrepCommand(pattern, path, glob);
 		const output = (await this.execute(command)).output.trim();
-		if (!output) return [];
+		if (!output) return { matches: [] };
 		const matches = [];
 		for (const line of output.split("\n")) {
 			const parts = line.split(":");
 			if (parts.length >= 3) {
+				const filePath = parts[0];
+				if (!isTextMimeType(getMimeType(filePath))) continue;
 				const lineNum = parseInt(parts[1], 10);
 				if (!isNaN(lineNum)) matches.push({
-					path: parts[0],
+					path: filePath,
 					line: lineNum,
 					text: parts.slice(2).join(":")
 				});
 			}
 		}
-		return matches;
+		return { matches };
 	}
 	/**
 	* Structured glob matching returning FileInfo objects.
@@ -4677,7 +5814,7 @@ var BaseSandbox = class {
 	* - `?`  matches a single character except `/`
 	* - `[...]` character classes
 	*/
-	async globInfo(pattern, path = "/") {
+	async glob(pattern, path = "/") {
 		const command = buildFindCommand(path);
 		const result = await this.execute(command);
 		const regex = globToPathRegex(pattern);
@@ -4695,7 +5832,7 @@ var BaseSandbox = class {
 				modified_at: (/* @__PURE__ */ new Date(parsed.mtime * 1e3)).toISOString()
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Create a new file with content.
@@ -4708,8 +5845,11 @@ var BaseSandbox = class {
 			const existCheck = await this.downloadFiles([filePath]);
 			if (existCheck[0].content !== null && existCheck[0].error === null) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
 		} catch {}
-		const encoder = new TextEncoder();
-		const results = await this.uploadFiles([[filePath, encoder.encode(content)]]);
+		const mimeType = getMimeType(filePath);
+		let fileContent;
+		if (isTextMimeType(mimeType)) fileContent = new TextEncoder().encode(content);
+		else fileContent = Buffer.from(content, "base64");
+		const results = await this.uploadFiles([[filePath, fileContent]]);
 		if (results[0].error) return { error: `Failed to write to ${filePath}: ${results[0].error}` };
 		return {
 			path: filePath,
@@ -4808,7 +5948,197 @@ var BaseSandbox = class {
 		};
 	}
 };
-
+//#endregion
+//#region src/backends/langsmith.ts
+/**
+* LangSmith Sandbox backend for deepagents.
+*
+* @example
+* ```typescript
+* import { LangSmithSandbox, createDeepAgent } from "deepagents";
+*
+* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents-cli" });
+*
+* const agent = createDeepAgent({ model, backend: sandbox });
+*
+* try {
+*   await agent.invoke({ messages: [...] });
+* } finally {
+*   await sandbox.close();
+* }
+* ```
+*/
+/**
+* LangSmith Sandbox backend for deepagents.
+*
+* Extends `BaseSandbox` to provide command execution and file operations
+* via the LangSmith Sandbox API.
+*
+* Use the static `LangSmithSandbox.create()` factory for the simplest setup,
+* or construct directly with an existing `Sandbox` instance.
+*/
+var LangSmithSandbox = class LangSmithSandbox extends BaseSandbox {
+	#sandbox;
+	#defaultTimeout;
+	#isRunning = true;
+	constructor(options) {
+		super();
+		this.#sandbox = options.sandbox;
+		this.#defaultTimeout = options.defaultTimeout ?? 1800;
+	}
+	/** Whether the sandbox is currently active. */
+	get isRunning() {
+		return this.#isRunning;
+	}
+	/** Return the LangSmith sandbox name as the unique identifier. */
+	get id() {
+		return this.#sandbox.name;
+	}
+	/**
+	* Execute a shell command in the LangSmith sandbox.
+	*
+	* @param command - Shell command string to execute
+	* @param options.timeout - Override timeout in seconds; 0 disables timeout
+	*/
+	async execute(command, options) {
+		const effectiveTimeout = options?.timeout !== void 0 ? options.timeout : this.#defaultTimeout;
+		const result = await this.#sandbox.run(command, { timeout: effectiveTimeout });
+		const out = result.stdout ?? "";
+		return {
+			output: result.stderr ? out ? `${out}\n${result.stderr}` : result.stderr : out,
+			exitCode: result.exit_code,
+			truncated: false
+		};
+	}
+	/**
+	* Download files from the sandbox using LangSmith's native file read API.
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const responses = [];
+		for (const path of paths) try {
+			const content = await this.#sandbox.read(path);
+			responses.push({
+				path,
+				content,
+				error: null
+			});
+		} catch (err) {
+			if (err instanceof langsmith_experimental_sandbox.LangSmithResourceNotFoundError) responses.push({
+				path,
+				content: null,
+				error: "file_not_found"
+			});
+			else if (err instanceof langsmith_experimental_sandbox.LangSmithSandboxError) {
+				const error = String(err.message).toLowerCase().includes("is a directory") ? "is_directory" : "file_not_found";
+				responses.push({
+					path,
+					content: null,
+					error
+				});
+			} else responses.push({
+				path,
+				content: null,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Upload files to the sandbox using LangSmith's native file write API.
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const responses = [];
+		for (const [path, content] of files) try {
+			await this.#sandbox.write(path, content);
+			responses.push({
+				path,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path,
+				error: "permission_denied"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Delete this sandbox and mark it as no longer running.
+	*
+	* After calling this, `isRunning` will be `false` and the sandbox
+	* cannot be used again.
+	*/
+	async close() {
+		await this.#sandbox.delete();
+		this.#isRunning = false;
+	}
+	/**
+	* Create and return a new LangSmithSandbox in one step.
+	*
+	* This is the recommended way to create a sandbox — no need to import
+	* anything from `langsmith/experimental/sandbox` directly.
+	*
+	* @example
+	* ```typescript
+	* const sandbox = await LangSmithSandbox.create({ templateName: "deepagents" });
+	* try {
+	*   const agent = createDeepAgent({ model, backend: sandbox });
+	*   await agent.invoke({ messages: [...] });
+	* } finally {
+	*   await sandbox.close();
+	* }
+	* ```
+	*/
+	static async create(options = {}) {
+		const { templateName = "deepagents", apiKey = process.env.LANGSMITH_API_KEY, defaultTimeout } = options;
+		return new LangSmithSandbox({
+			sandbox: await new langsmith_experimental_sandbox.SandboxClient({ apiKey }).createSandbox(templateName),
+			defaultTimeout
+		});
+	}
+};
+//#endregion
+//#region src/errors.ts
+const CONFIGURATION_ERROR_SYMBOL = Symbol.for("deepagents.configuration_error");
+/**
+* Thrown when `createDeepAgent` receives invalid configuration.
+*
+* Follows the same pattern as {@link SandboxError}: a human-readable
+* `message`, a structured `code` for programmatic handling, and a
+* static `isInstance` guard that works across realms.
+*
+* @example
+* ```typescript
+* try {
+*   createDeepAgent({ tools: [myTool] });
+* } catch (error) {
+*   if (ConfigurationError.isInstance(error)) {
+*     switch (error.code) {
+*       case "TOOL_NAME_COLLISION":
+*         console.error("Rename your tool:", error.message);
+*         break;
+*     }
+*   }
+* }
+* ```
+*/
+var ConfigurationError = class ConfigurationError extends Error {
+	[CONFIGURATION_ERROR_SYMBOL] = true;
+	name = "ConfigurationError";
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, ConfigurationError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[CONFIGURATION_ERROR_SYMBOL] === true;
+	}
+};
 //#endregion
 //#region src/middleware/cache.ts
 /**
@@ -4852,10 +6182,14 @@ function createCacheBreakpointMiddleware() {
 		}
 	});
 }
-
 //#endregion
 //#region src/agent.ts
 const BASE_PROMPT = `In order to complete the objective that the user asks of you, you have access to a number of standard tools.`;
+const BUILTIN_TOOL_NAMES = new Set([
+	...FILESYSTEM_TOOL_NAMES,
+	"task",
+	"write_todos"
+]);
 /**
 * Detect whether a model is an Anthropic model.
 * Used to gate Anthropic-specific prompt caching optimizations (cache_control breakpoints).
@@ -4901,6 +6235,8 @@ function isAnthropicModel(model) {
 */
 function createDeepAgent(params = {}) {
 	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name, memory, skills } = params;
+	const collidingTools = tools.map((t) => t.name).filter((n) => typeof n === "string" && BUILTIN_TOOL_NAMES.has(n));
+	if (collidingTools.length > 0) throw new ConfigurationError(`Tool name(s) [${collidingTools.join(", ")}] conflict with built-in tools. Rename your custom tools to avoid this.`, "TOOL_NAME_COLLISION");
 	const anthropicModel = isAnthropicModel(model);
 	const finalSystemPrompt = new langchain.SystemMessage({ content: systemPrompt ? typeof systemPrompt === "string" ? [{
 		type: "text",
@@ -4936,13 +6272,19 @@ function createDeepAgent(params = {}) {
 		addCacheControl: anthropicModel
 	})] : [];
 	/**
+	* Split the unified subagents array into sync and async subagents.
+	* AsyncSubAgents are identified by the presence of a `graphId` field.
+	*/
+	const syncSubAgents = subagents.filter((a) => !isAsyncSubAgent(a));
+	const asyncSubAgents = subagents.filter((a) => isAsyncSubAgent(a));
+	/**
 	* Process subagents to add SkillsMiddleware for those with their own skills.
 	*
 	* Custom subagents do NOT inherit skills from the main agent by default.
 	* Only the general-purpose subagent inherits the main agent's skills (via defaultMiddleware).
 	* If a custom subagent needs skills, it must specify its own `skills` array.
 	*/
-	const processedSubagents = subagents.map((subagent) => {
+	const processedSubagents = syncSubAgents.map((subagent) => {
 		/**
 		* CompiledSubAgent - use as-is (already has its own middleware baked in)
 		*/
@@ -4982,10 +6324,6 @@ function createDeepAgent(params = {}) {
 			model,
 			backend: filesystemBackend
 		}),
-		(0, langchain.anthropicPromptCachingMiddleware)({
-			unsupportedModelBehavior: "ignore",
-			minMessagesToCache: 1
-		}),
 		createPatchToolCallsMiddleware()
 	];
 	/**
@@ -5008,11 +6346,17 @@ function createDeepAgent(params = {}) {
 				createSubAgentMiddleware({
 					defaultModel: model,
 					defaultTools: tools,
-					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [createCacheBreakpointMiddleware()] : []],
+					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+						unsupportedModelBehavior: "ignore",
+						minMessagesToCache: 1
+					}), createCacheBreakpointMiddleware()] : []],
 					generalPurposeMiddleware: [
 						...subagentMiddleware,
 						...skillsMiddlewareArray,
-						...anthropicModel ? [createCacheBreakpointMiddleware()] : []
+						...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+							unsupportedModelBehavior: "ignore",
+							minMessagesToCache: 1
+						}), createCacheBreakpointMiddleware()] : []
 					],
 					defaultInterruptOn: interruptOn,
 					subagents: processedSubagents,
@@ -5022,17 +6366,17 @@ function createDeepAgent(params = {}) {
 					model,
 					backend: filesystemBackend
 				}),
-				(0, langchain.anthropicPromptCachingMiddleware)({
-					unsupportedModelBehavior: "ignore",
-					minMessagesToCache: 1
-				}),
 				createPatchToolCallsMiddleware()
 			],
 			...skillsMiddlewareArray,
-			...anthropicModel ? [createCacheBreakpointMiddleware()] : [],
+			...customMiddleware,
+			...anthropicModel ? [(0, langchain.anthropicPromptCachingMiddleware)({
+				unsupportedModelBehavior: "ignore",
+				minMessagesToCache: 1
+			}), createCacheBreakpointMiddleware()] : [],
 			...memoryMiddlewareArray,
 			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : [],
-			...customMiddleware
+			...asyncSubAgents && asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 		],
 		...responseFormat != null && { responseFormat },
 		contextSchema,
@@ -5044,7 +6388,6 @@ function createDeepAgent(params = {}) {
 		metadata: { ls_integration: "deepagents" }
 	});
 }
-
 //#endregion
 //#region src/config.ts
 /**
@@ -5138,7 +6481,6 @@ function createSettings(options = {}) {
 		}
 	};
 }
-
 //#endregion
 //#region src/middleware/agent-memory.ts
 /**
@@ -5365,38 +6707,6 @@ function createAgentMemoryMiddleware(options) {
 		}
 	});
 }
-
-//#endregion
-//#region src/skills/loader.ts
-/**
-* Skill loader for parsing and loading agent skills from SKILL.md files.
-*
-* This module implements Anthropic's agent skills pattern with YAML frontmatter parsing.
-* Each skill is a directory containing a SKILL.md file with:
-* - YAML frontmatter (name, description required)
-* - Markdown instructions for the agent
-* - Optional supporting files (scripts, configs, etc.)
-*
-* @example
-* ```markdown
-* ---
-* name: web-research
-* description: Structured approach to conducting thorough web research
-* ---
-*
-* # Web Research Skill
-*
-* ## When to Use
-* - User asks you to research a topic
-* ...
-* ```
-*
-* @see https://agentskills.io/specification
-*/
-/** Maximum size for SKILL.md files (10MB) */
-const MAX_SKILL_FILE_SIZE$1 = 10 * 1024 * 1024;
-/** Agent Skills spec constraints */
-const MAX_SKILL_NAME_LENGTH$1 = 64;
 const MAX_SKILL_DESCRIPTION_LENGTH$1 = 1024;
 /** Pattern for validating skill names per Agent Skills spec */
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -5441,7 +6751,7 @@ function validateSkillName(name, directoryName) {
 		valid: false,
 		error: "name is required"
 	};
-	if (name.length > MAX_SKILL_NAME_LENGTH$1) return {
+	if (name.length > 64) return {
 		valid: false,
 		error: "name exceeds 64 characters"
 	};
@@ -5481,7 +6791,7 @@ function parseFrontmatter(content) {
 function parseSkillMetadata(skillMdPath, source) {
 	try {
 		const stats = node_fs.default.statSync(skillMdPath);
-		if (stats.size > MAX_SKILL_FILE_SIZE$1) {
+		if (stats.size > 10485760) {
 			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
 			return null;
 		}
@@ -5500,7 +6810,7 @@ function parseSkillMetadata(skillMdPath, source) {
 		const validation = validateSkillName(String(name), directoryName);
 		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
 		let descriptionStr = String(description);
-		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH$1) {
+		if (descriptionStr.length > 1024) {
 			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH$1} chars in ${skillMdPath}, truncating`);
 			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH$1);
 		}
@@ -5588,14 +6898,15 @@ function listSkills(options) {
 	}
 	return Array.from(allSkills.values());
 }
-
 //#endregion
 exports.BaseSandbox = BaseSandbox;
 exports.CompositeBackend = CompositeBackend;
+exports.ConfigurationError = ConfigurationError;
 exports.DEFAULT_GENERAL_PURPOSE_DESCRIPTION = DEFAULT_GENERAL_PURPOSE_DESCRIPTION;
 exports.DEFAULT_SUBAGENT_PROMPT = DEFAULT_SUBAGENT_PROMPT;
 exports.FilesystemBackend = FilesystemBackend;
 exports.GENERAL_PURPOSE_SUBAGENT = GENERAL_PURPOSE_SUBAGENT;
+exports.LangSmithSandbox = LangSmithSandbox;
 exports.LocalShellBackend = LocalShellBackend;
 exports.MAX_SKILL_DESCRIPTION_LENGTH = MAX_SKILL_DESCRIPTION_LENGTH;
 exports.MAX_SKILL_FILE_SIZE = MAX_SKILL_FILE_SIZE;
@@ -5604,8 +6915,12 @@ exports.SandboxError = SandboxError;
 exports.StateBackend = StateBackend;
 exports.StoreBackend = StoreBackend;
 exports.TASK_SYSTEM_PROMPT = TASK_SYSTEM_PROMPT;
+exports.adaptBackendProtocol = adaptBackendProtocol;
+exports.adaptSandboxProtocol = adaptSandboxProtocol;
 exports.computeSummarizationDefaults = computeSummarizationDefaults;
 exports.createAgentMemoryMiddleware = createAgentMemoryMiddleware;
+exports.createAsyncSubAgentMiddleware = createAsyncSubAgentMiddleware;
+exports.createCompletionNotifierMiddleware = createCompletionNotifierMiddleware;
 exports.createDeepAgent = createDeepAgent;
 exports.createFilesystemMiddleware = createFilesystemMiddleware;
 exports.createMemoryMiddleware = createMemoryMiddleware;
@@ -5616,7 +6931,10 @@ exports.createSubAgentMiddleware = createSubAgentMiddleware;
 exports.createSummarizationMiddleware = createSummarizationMiddleware;
 exports.filesValue = filesValue;
 exports.findProjectRoot = findProjectRoot;
+exports.isAsyncSubAgent = isAsyncSubAgent;
 exports.isSandboxBackend = isSandboxBackend;
+exports.isSandboxProtocol = isSandboxProtocol;
 exports.listSkills = listSkills;
 exports.parseSkillMetadata = parseSkillMetadata;
+
 //# sourceMappingURL=index.cjs.map