deepagents 1.8.5 → 1.9.0-alpha.0

package/dist/index.cjs

@@ -28,10 +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 _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");
@@ -52,10 +54,22 @@ node_os = __toESM(node_os);
 * 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" && backend.id !== "";
+	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");
 /**
@@ -119,6 +133,19 @@ const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty conten
 const MAX_LINE_LENGTH = 1e4;
 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.
 *
@@ -180,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");
 }
 /**
-* Create a FileData object with timestamps.
+* Type guard to check if FileData contains binary content (Uint8Array).
 *
-* @param content - File content as string
-* @param createdAt - Optional creation timestamp (ISO format)
-* @returns FileData object with content and timestamps
+* @param data - FileData to check
+* @returns True if the content is a Uint8Array (binary)
 */
-function createFileData(content, createdAt) {
-	const lines = typeof content === "string" ? content.split("\n") : content;
+function isFileDataBinary(data) {
+	return ArrayBuffer.isView(data.content);
+}
+/**
+* Create a FileData object.
+*
+* 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, 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
 	};
@@ -206,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
@@ -291,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 += "/";
@@ -314,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";
 	}
@@ -343,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 [];
 	}
@@ -362,17 +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
 /**
@@ -388,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.
@@ -401,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();
@@ -417,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,
@@ -432,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.
@@ -464,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 }
@@ -488,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,
@@ -512,7 +692,7 @@ var StateBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -527,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
@@ -561,11 +743,17 @@ 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
 			});
 		}
@@ -627,6 +815,12 @@ const TOOLS_EXCLUDED_FROM_EVICTION = [
 	"write_file"
 ];
 /**
+* 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 MAX_BINARY_READ_SIZE_BYTES = 10 * 1024 * 1024;
+/**
 * Template for truncation message in read_file.
 * {file_path} will be filled in at runtime.
 */
@@ -665,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.
@@ -715,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\`
 
@@ -841,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)`);
@@ -869,15 +1078,64 @@ function createReadFileTool(backend, options) {
 			store: config.store
 		});
 		const { file_path, offset = 0, limit = 100 } = 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 >= 4 * toolTokenLimitBeforeEvict) {
+		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 = 4 * toolTokenLimitBeforeEvict - truncationMsg.length;
-			result = result.substring(0, maxContentLength) + truncationMsg;
+			formatted = formatted.substring(0, maxContentLength) + truncationMsg;
 		}
-		return result;
+		return [{
+			type: "text",
+			text: formatted
+		}];
 	}, {
 		name: "read_file",
 		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
@@ -967,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");
@@ -992,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}:`);
@@ -1820,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) {
@@ -1861,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",
@@ -2184,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 [];
 	}
@@ -2201,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);
@@ -2275,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",
@@ -2319,6 +2586,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
 /**
 * Summarization middleware with backend support for conversation history offloading.
@@ -2514,8 +3001,8 @@ 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.
@@ -3008,6 +3495,532 @@ ${summary}
 	});
 }
 //#endregion
+//#region src/middleware/async_subagents.ts
+function toolCallIdFromRuntime(runtime) {
+	return runtime.toolCall?.id ?? runtime.toolCallId ?? "";
+}
+/**
+* Zod schema for {@link AsyncTask}.
+*
+* 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.
+*
+* 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.
+*/
+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
+}) });
+/**
+* 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\-_.@+:~]+$/;
 /**
@@ -3043,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.
@@ -3082,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
 		};
@@ -3093,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
 		};
@@ -3132,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);
@@ -3153,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,
@@ -3171,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.
@@ -3209,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 {
@@ -3244,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);
@@ -3256,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);
@@ -3272,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,
@@ -3285,7 +4318,7 @@ var StoreBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -3298,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({
@@ -3333,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 {
@@ -3410,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;
@@ -3461,9 +4504,9 @@ var FilesystemBackend = class {
 				}
 			}
 			results.sort((a, b) => a.path.localeCompare(b.path));
-			return results;
+			return { files: results };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 	}
 	/**
@@ -3477,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.
@@ -3541,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.` };
@@ -3550,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,
@@ -3616,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);
@@ -3636,7 +4729,7 @@ var FilesystemBackend = class {
 			line: lineNum,
 			text: lineText
 		});
-		return matches;
+		return { matches };
 	}
 	/**
 	* Search using ripgrep with fixed-string (literal) mode.
@@ -3716,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");
@@ -3743,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 {
@@ -3789,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.
@@ -3884,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() {
@@ -3910,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,
@@ -3936,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.
@@ -3956,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);
@@ -3965,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.
@@ -4239,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;
 	}
 	/**
@@ -4256,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 = {
@@ -4316,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.
@@ -4591,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 = [];
@@ -4608,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.
@@ -4623,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.
@@ -4635,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.
@@ -4656,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.
@@ -4687,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);
@@ -4705,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.
@@ -4718,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,
@@ -5142,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)
 		*/
@@ -5239,7 +6375,8 @@ function createDeepAgent(params = {}) {
 				minMessagesToCache: 1
 			}), createCacheBreakpointMiddleware()] : [],
 			...memoryMiddlewareArray,
-			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : []
+			...interruptOn ? [(0, langchain.humanInTheLoopMiddleware)({ interruptOn })] : [],
+			...asyncSubAgents && asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : []
 		],
 		...responseFormat != null && { responseFormat },
 		contextSchema,
@@ -5778,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;
@@ -5790,7 +6931,9 @@ 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;