deepagents 1.8.8 → 1.9.0-alpha.1

package/dist/index.js

@@ -1,92 +1,23 @@
-import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
-import { Runnable } from "@langchain/core/runnables";
-import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getCurrentTaskInput, isCommand } from "@langchain/langgraph";
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage, anthropicPromptCachingMiddleware, context, countTokensApproximately, createAgent, createMiddleware, humanInTheLoopMiddleware, todoListMiddleware, tool } from "langchain";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { Command, REMOVE_ALL_MESSAGES, ReducedValue, StateSchema, getConfig, getCurrentTaskInput, getStore, isCommand } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import micromatch from "micromatch";
-import { basename } from "path";
-import { HumanMessage as HumanMessage$1, RemoveMessage, getBufferString } from "@langchain/core/messages";
+import path, { basename } from "path";
+import { AIMessage as AIMessage$1, HumanMessage as HumanMessage$1, RemoveMessage, getBufferString } from "@langchain/core/messages";
+import * as z$2 from "zod";
 import { z as z$1 } from "zod";
 import yaml from "yaml";
+import { Client } from "@langchain/langgraph-sdk";
 import { ContextOverflowError } from "@langchain/core/errors";
 import { initChatModel } from "langchain/chat_models/universal";
 import fs from "node:fs/promises";
 import fs$1 from "node:fs";
-import path from "node:path";
+import path$1 from "node:path";
 import cp, { spawn } from "node:child_process";
 import fg from "fast-glob";
 import { LangSmithResourceNotFoundError, LangSmithSandboxError, SandboxClient } from "langsmith/experimental/sandbox";
 import os from "node:os";
-//#region src/backends/protocol.ts
-/**
-* Type guard to check if a backend supports execution.
-*
-* @param backend - Backend instance to check
-* @returns True if the backend implements SandboxBackendProtocol
-*/
-function isSandboxBackend(backend) {
-	return typeof backend.execute === "function" && typeof backend.id === "string" && backend.id !== "";
-}
-const SANDBOX_ERROR_SYMBOL = Symbol.for("sandbox.error");
-/**
-* Custom error class for sandbox operations.
-*
-* @param message - Human-readable error description
-* @param code - Structured error code for programmatic handling
-* @returns SandboxError with message and code
-*
-* @example
-* ```typescript
-* try {
-*   await sandbox.execute("some command");
-* } catch (error) {
-*   if (error instanceof SandboxError) {
-*     switch (error.code) {
-*       case "NOT_INITIALIZED":
-*         await sandbox.initialize();
-*         break;
-*       case "COMMAND_TIMEOUT":
-*         console.error("Command took too long");
-*         break;
-*       default:
-*         throw error;
-*     }
-*   }
-* }
-* ```
-*/
-var SandboxError = class SandboxError extends Error {
-	/** Symbol for identifying sandbox error instances */
-	[SANDBOX_ERROR_SYMBOL] = true;
-	/** Error name for instanceof checks and logging */
-	name = "SandboxError";
-	/**
-	* Creates a new SandboxError.
-	*
-	* @param message - Human-readable error description
-	* @param code - Structured error code for programmatic handling
-	*/
-	constructor(message, code, cause) {
-		super(message);
-		this.code = code;
-		this.cause = cause;
-		Object.setPrototypeOf(this, SandboxError.prototype);
-	}
-	static isInstance(error) {
-		return typeof error === "object" && error !== null && error[SANDBOX_ERROR_SYMBOL] === true;
-	}
-};
-/**
-* Resolve a backend instance or await a {@link BackendFactory}.
-*
-* Accepts {@link BackendRuntime} or {@link ToolRuntime} — store typing differs
-* between LangGraph checkpoint stores and core `ToolRuntime`; factories receive
-* a value that is structurally compatible at runtime.
-*/
-async function resolveBackend(backend, runtime) {
-	if (typeof backend === "function") return await backend(runtime);
-	return backend;
-}
-//#endregion
 //#region src/backends/utils.ts
 /**
 * Shared utility functions for memory backend implementations.
@@ -96,9 +27,37 @@ async function resolveBackend(backend, runtime) {
 * enable composition without fragile string parsing.
 */
 const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
-const MAX_LINE_LENGTH = 1e4;
+const MAX_LINE_LENGTH = 5e3;
 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",
+	".heic": "image/heic",
+	".heif": "image/heif",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".aiff": "audio/aiff",
+	".aac": "audio/aac",
+	".ogg": "audio/ogg",
+	".flac": "audio/flac",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".mpeg": "video/mpeg",
+	".mov": "video/quicktime",
+	".avi": "video/x-msvideo",
+	".flv": "video/x-flv",
+	".mpg": "video/mpeg",
+	".wmv": "video/x-ms-wmv",
+	".3gpp": "video/3gpp",
+	".pdf": "application/pdf",
+	".ppt": "application/vnd.ms-powerpoint",
+	".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+};
 /**
 * Sanitize tool_call_id to prevent path traversal and separator issues.
 *
@@ -126,7 +85,7 @@ function formatContentWithLineNumbers(content, startLine = 1) {
 	for (let i = 0; i < lines.length; i++) {
 		const line = lines[i];
 		const lineNum = i + startLine;
-		if (line.length <= 1e4) resultLines.push(`${lineNum.toString().padStart(6)}\t${line}`);
+		if (line.length <= 5e3) resultLines.push(`${lineNum.toString().padStart(6)}\t${line}`);
 		else {
 			const numChunks = Math.ceil(line.length / MAX_LINE_LENGTH);
 			for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
@@ -160,20 +119,50 @@ function checkEmptyContent(content) {
 * @returns Content as string with lines joined by newlines
 */
 function fileDataToString(fileData) {
-	return fileData.content.join("\n");
+	if (Array.isArray(fileData.content)) return fileData.content.join("\n");
+	if (typeof fileData.content === "string") return fileData.content;
+	throw new Error("Cannot convert binary FileData to string");
+}
+/**
+* Type guard to check if FileData contains binary content (Uint8Array).
+*
+* @param data - FileData to check
+* @returns True if the content is a Uint8Array (binary)
+*/
+function isFileDataBinary(data) {
+	return ArrayBuffer.isView(data.content);
 }
 /**
-* Create a FileData object with timestamps.
+* Create a FileData object.
 *
-* @param content - File content as string
-* @param createdAt - Optional creation timestamp (ISO format)
-* @returns FileData object with content and timestamps
+* Defaults to v2 format (content as single string). Pass `fileFormat: "v1"` for
+* backward compatibility with older readers during a rolling deployment.
+* Binary content (Uint8Array) is only supported with v2.
+*
+* @param content - File content as a string or binary Uint8Array (v2 only)
+* @param createdAt - Optional creation timestamp (ISO format), defaults to now
+* @param fileFormat - Storage format: "v2" (default) or "v1" (legacy line array)
+* @returns FileData in the requested format
 */
-function createFileData(content, createdAt) {
-	const lines = typeof content === "string" ? content.split("\n") : content;
+function createFileData(content, createdAt, fileFormat = "v2", mimeType) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
+	if (fileFormat === "v1" && ArrayBuffer.isView(content)) throw new Error("Binary data is not supported with v1 file formats. Please use v2 file format");
+	if (fileFormat === "v2") {
+		if (ArrayBuffer.isView(content)) return {
+			content: new Uint8Array(content.buffer, content.byteOffset, content.byteLength),
+			mimeType: mimeType ?? "application/octet-stream",
+			created_at: createdAt || now,
+			modified_at: now
+		};
+		return {
+			content,
+			mimeType: mimeType ?? "text/plain",
+			created_at: createdAt || now,
+			modified_at: now
+		};
+	}
 	return {
-		content: lines,
+		content: typeof content === "string" ? content.split("\n") : content,
 		created_at: createdAt || now,
 		modified_at: now
 	};
@@ -186,33 +175,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
@@ -323,11 +299,8 @@ function globSearchFiles(files, pattern, path = "/") {
 /**
 * 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 = null, glob = null) {
 	let normalizedPath;
@@ -342,19 +315,231 @@ function grepMatchesFromFiles(files, pattern, path = 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.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) {
+			const result = await ("ls" in backend ? backend.ls(path) : backend.lsInfo(path));
+			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) {
+			const result = await ("glob" in backend ? backend.glob(pattern, path) : backend.globInfo(pattern, path));
+			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, glob) {
+			const result = await ("grep" in backend ? backend.grep(pattern, path, glob) : backend.grepRaw(pattern, path, 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/protocol.ts
+/**
+* Type guard to check if a backend supports execution.
+*
+* @param backend - Backend instance to check
+* @returns True if the backend implements SandboxBackendProtocolV2
+*/
+function isSandboxBackend(backend) {
+	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");
+/**
+* Custom error class for sandbox operations.
+*
+* @param message - Human-readable error description
+* @param code - Structured error code for programmatic handling
+* @returns SandboxError with message and code
+*
+* @example
+* ```typescript
+* try {
+*   await sandbox.execute("some command");
+* } catch (error) {
+*   if (error instanceof SandboxError) {
+*     switch (error.code) {
+*       case "NOT_INITIALIZED":
+*         await sandbox.initialize();
+*         break;
+*       case "COMMAND_TIMEOUT":
+*         console.error("Command took too long");
+*         break;
+*       default:
+*         throw error;
+*     }
+*   }
+* }
+* ```
+*/
+var SandboxError = class SandboxError extends Error {
+	/** Symbol for identifying sandbox error instances */
+	[SANDBOX_ERROR_SYMBOL] = true;
+	/** Error name for instanceof checks and logging */
+	name = "SandboxError";
+	/**
+	* Creates a new SandboxError.
+	*
+	* @param message - Human-readable error description
+	* @param code - Structured error code for programmatic handling
+	*/
+	constructor(message, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, SandboxError.prototype);
+	}
+	static isInstance(error) {
+		return typeof error === "object" && error !== null && error[SANDBOX_ERROR_SYMBOL] === true;
+	}
+};
+/**
+* Resolve a backend instance or await a {@link BackendFactory}.
+*
+* Accepts {@link BackendRuntime} or {@link ToolRuntime} — store typing differs
+* between LangGraph checkpoint stores and core `ToolRuntime`; factories receive
+* a value that is structurally compatible at runtime.
+*
+* @internal
+*/
+async function resolveBackend(backend, runtime) {
+	if (typeof backend === "function") {
+		const resolved = await backend(runtime);
+		return isSandboxProtocol(resolved) ? adaptSandboxProtocol(resolved) : adaptBackendProtocol(resolved);
+	}
+	return isSandboxProtocol(backend) ? adaptSandboxProtocol(backend) : adaptBackendProtocol(backend);
+}
 //#endregion
 //#region src/backends/state.ts
+const PREGEL_SEND_KEY = "__pregel_send";
 /**
 * Backend that stores files in agent state (ephemeral).
 *
@@ -368,23 +553,60 @@ function grepMatchesFromFiles(files, pattern, path = null, glob = null) {
 */
 var StateBackend = class {
 	runtime;
-	constructor(runtime) {
-		this.runtime = runtime;
+	fileFormat;
+	constructor(runtimeOrOptions, options) {
+		if (runtimeOrOptions != null && typeof runtimeOrOptions === "object" && "state" in runtimeOrOptions) {
+			this.runtime = runtimeOrOptions;
+			this.fileFormat = options?.fileFormat ?? "v2";
+		} else {
+			this.runtime = void 0;
+			this.fileFormat = runtimeOrOptions?.fileFormat ?? "v2";
+		}
+	}
+	/**
+	* Whether this instance was constructed with the legacy factory pattern.
+	*
+	* When true, state is read from the injected `runtime` and `filesUpdate`
+	* is returned to the caller. When false, state is read from LangGraph's
+	* execution context and updates are sent via `__pregel_send`.
+	*/
+	get isLegacy() {
+		return this.runtime !== void 0;
 	}
 	/**
 	* Get files from current state.
+	*
+	* In legacy mode, reads from the injected {@link BackendRuntime}.
+	* In zero-arg mode, reads from the LangGraph execution context via
+	* {@link getCurrentTaskInput}.
 	*/
 	getFiles() {
-		return this.runtime.state.files || {};
+		if (this.runtime) return this.runtime.state.files || {};
+		return getCurrentTaskInput()?.files || {};
+	}
+	/**
+	* Push a files state update through LangGraph's internal send channel.
+	*
+	* In zero-arg mode, sends the update via the `__pregel_send` function
+	* from {@link getConfig}, mirroring Python's `CONFIG_KEY_SEND`.
+	* In legacy mode, this is a no-op — the caller uses `filesUpdate`
+	* from the return value instead.
+	*
+	* @param update - Map of file paths to their updated {@link FileData}
+	*/
+	sendFilesUpdate(update) {
+		if (this.isLegacy) return;
+		const send = getConfig().configurable?.[PREGEL_SEND_KEY];
+		if (typeof send === "function") send([["files", update]]);
 	}
 	/**
 	* 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();
@@ -397,7 +619,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,
@@ -412,31 +634,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.
@@ -444,7 +678,13 @@ 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);
+		const update = { [filePath]: newFileData };
+		if (!this.isLegacy) {
+			this.sendFilesUpdate(update);
+			return { path: filePath };
+		}
 		return {
 			path: filePath,
 			filesUpdate: { [filePath]: newFileData }
@@ -461,6 +701,14 @@ var StateBackend = class {
 		if (typeof result === "string") return { error: result };
 		const [newContent, occurrences] = result;
 		const newFileData = updateFileData(fileData, newContent);
+		const update = { [filePath]: newFileData };
+		if (!this.isLegacy) {
+			this.sendFilesUpdate(update);
+			return {
+				path: filePath,
+				occurrences
+			};
+		}
 		return {
 			path: filePath,
 			filesUpdate: { [filePath]: newFileData },
@@ -468,23 +716,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,
@@ -492,7 +741,7 @@ var StateBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -507,7 +756,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
@@ -518,6 +769,10 @@ var StateBackend = class {
 				error: "invalid_path"
 			});
 		}
+		if (!this.isLegacy) {
+			if (Object.keys(updates).length > 0) this.sendFilesUpdate(updates);
+			return responses;
+		}
 		const result = responses;
 		result.filesUpdate = updates;
 		return result;
@@ -541,11 +796,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
 			});
 		}
@@ -561,6 +822,7 @@ var StateBackend = class {
 * - Pluggable backends (StateBackend, StoreBackend, FilesystemBackend, CompositeBackend)
 * - Tool result eviction for large outputs
 */
+const INT_FORMATTER = new Intl.NumberFormat("en-US");
 /**
 * Tools that should be excluded from the large result eviction logic.
 *
@@ -607,6 +869,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.
 */
@@ -616,16 +884,18 @@ const READ_FILE_TRUNCATION_MSG = `
 /**
 * Message template for evicted tool results.
 */
-const TOO_LARGE_TOOL_MSG = `Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
-You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
-You can do this by specifying an offset and limit in the read_file tool call.
-For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
+const TOO_LARGE_TOOL_MSG = context`
+  Tool result too large, the result of this tool call {tool_call_id} was saved in the filesystem at this path: {file_path}
+  You can read the result from the filesystem by using the read_file tool, but make sure to only read part of the result at a time.
+  You can do this by specifying an offset and limit in the read_file tool call.
+  For example, to read the first 100 lines, you can use the read_file tool with offset=0 and limit=100.
 
-Here is a preview showing the head and tail of the result (lines of the form
-... [N lines truncated] ...
-indicate omitted lines in the middle of the content):
+  Here is a preview showing the head and tail of the result (lines of the form
+  ... [N lines truncated] ...
+  indicate omitted lines in the middle of the content):
 
-{content_sample}`;
+  {content_sample}
+`;
 /**
 * Message template for evicted HumanMessages.
 */
@@ -701,14 +971,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 = z.object({
+const FileDataV1Schema = z.object({
 	content: z.array(z.string()),
 	created_at: z.string(),
 	modified_at: z.string()
 });
 /**
+* Zod schema for FileDataV2 (content as string for text or Uint8Array for binary).
+*/
+const FileDataV2Schema = z.object({
+	content: z.union([z.string(), z.instanceof(Uint8Array)]),
+	mimeType: z.string(),
+	created_at: z.string(),
+	modified_at: z.string()
+});
+/**
+* Zod v3 schema for FileData (re-export from backends)
+*/
+const FileDataSchema = 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.
@@ -744,118 +1027,141 @@ const FilesystemStateSchema = new StateSchema({ files: new ReducedValue(z.record
 	inputSchema: z.record(z.string(), FileDataSchema.nullable()).optional(),
 	reducer: fileDataReducer
 }) });
-const FILESYSTEM_SYSTEM_PROMPT = `## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
+const FILESYSTEM_SYSTEM_PROMPT = context`
+  ## Following Conventions
 
-You have access to a filesystem which you can interact with using these tools.
-All file paths must start with a /.
+  - Read files before editing — understand existing content before making changes
+  - Mimic existing style, naming conventions, and patterns
 
-- ls: list files in a directory (requires absolute path)
-- read_file: read a file from the filesystem
-- write_file: write to a file in the filesystem
-- edit_file: edit a file in the filesystem
-- glob: find files matching a pattern (e.g., "**/*.py")
-- grep: search for text within files`;
-const LS_TOOL_DESCRIPTION = `Lists all files in a directory.
+  ## Filesystem Tools \`ls\`, \`read_file\`, \`write_file\`, \`edit_file\`, \`glob\`, \`grep\`
 
-This is useful for exploring the filesystem and finding the right file to read or edit.
-You should almost ALWAYS use this tool before using the read_file or edit_file tools.`;
-const READ_FILE_TOOL_DESCRIPTION = `Reads a file from the filesystem.
+  You have access to a filesystem which you can interact with using these tools.
+  All file paths must start with a /.
 
-Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+  - ls: list files in a directory (requires absolute path)
+  - read_file: read a file from the filesystem
+  - write_file: write to a file in the filesystem
+  - edit_file: edit a file in the filesystem
+  - glob: find files matching a pattern (e.g., "**/*.py")
+  - grep: search for text within files
+`;
+const LS_TOOL_DESCRIPTION = context`
+  Lists all files in a directory.
 
-Usage:
-- By default, it reads up to 100 lines starting from the beginning of the file
-- **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
-  - First scan: read_file(path, limit=100) to see file structure
-  - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
-  - Only omit limit (read full file) when necessary for editing
-- Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
-- Results are returned using cat -n format, with line numbers starting at 1
-- Lines longer than 10,000 characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
-- You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
-- If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
-- You should ALWAYS make sure a file has been read before editing it.`;
-const WRITE_FILE_TOOL_DESCRIPTION = `Writes to a new file in the filesystem.
+  This is useful for exploring the filesystem and finding the right file to read or edit.
+  You should almost ALWAYS use this tool before using the read_file or edit_file tools.
+`;
+const READ_FILE_TOOL_DESCRIPTION = context`
+  Reads a file from the filesystem.
+
+  Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+
+  Usage:
+  - By default, it reads up to 100 lines starting from the beginning of the file
+  - **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
+    - First scan: read_file(path, limit=100) to see file structure
+    - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
+    - Only omit limit (read full file) when necessary for editing
+  - Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
+  - Results are returned using cat -n format, with line numbers starting at 1
+- Lines longer than ${INT_FORMATTER.format(MAX_LINE_LENGTH)} characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
+  - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.
+  - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
+  - You should ALWAYS make sure a file has been read before editing it.
+`;
+const WRITE_FILE_TOOL_DESCRIPTION = context`
+  Writes to a new file in the filesystem.
 
-Usage:
-- The write_file tool will create a new file.
-- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.`;
-const EDIT_FILE_TOOL_DESCRIPTION = `Performs exact string replacements in files.
+  Usage:
+  - The write_file tool will create a new file.
+  - Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
+`;
+const EDIT_FILE_TOOL_DESCRIPTION = context`
+  Performs exact string replacements in files.
 
-Usage:
-- You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
-- When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
-- ALWAYS prefer editing existing files over creating new ones.
-- Only use emojis if the user explicitly requests it.`;
-const GLOB_TOOL_DESCRIPTION = `Find files matching a glob pattern.
+  Usage:
+  - You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
+  - When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
+  - ALWAYS prefer editing existing files over creating new ones.
+  - Only use emojis if the user explicitly requests it.
+`;
+const GLOB_TOOL_DESCRIPTION = context`
+  Find files matching a glob pattern.
 
-Supports standard glob patterns: \`*\` (any characters), \`**\` (any directories), \`?\` (single character).
-Returns a list of absolute file paths that match the pattern.
+  Supports standard glob patterns: \`*\` (any characters), \`**\` (any directories), \`?\` (single character).
+  Returns a list of absolute file paths that match the pattern.
 
-Examples:
-- \`**/*.py\` - Find all Python files
-- \`*.txt\` - Find all text files in root
-- \`/subdir/**/*.md\` - Find all markdown files under /subdir`;
-const GREP_TOOL_DESCRIPTION = `Search for a text pattern across files.
+  Examples:
+  - \`**/*.py\` - Find all Python files
+  - \`*.txt\` - Find all text files in root
+  - \`/subdir/**/*.md\` - Find all markdown files under /subdir
+`;
+const GREP_TOOL_DESCRIPTION = context`
+  Search for a text pattern across files.
 
-Searches for literal text (not regex) and returns matching files or content based on output_mode.
-Special characters like parentheses, brackets, pipes, etc. are treated as literal characters, not regex operators.
+  Searches for literal text (not regex) and returns matching files or content based on output_mode.
+  Special characters like parentheses, brackets, pipes, etc. are treated as literal characters, not regex operators.
 
-Examples:
-- Search all files: \`grep(pattern="TODO")\`
-- Search Python files only: \`grep(pattern="import", glob="*.py")\`
-- Show matching lines: \`grep(pattern="error", output_mode="content")\`
-- Search for code with special chars: \`grep(pattern="def __init__(self):")\``;
-const EXECUTE_TOOL_DESCRIPTION = `Executes a shell command in an isolated sandbox environment.
+  Examples:
+  - Search all files: \`grep(pattern="TODO")\`
+  - Search Python files only: \`grep(pattern="import", glob="*.py")\`
+  - Show matching lines: \`grep(pattern="error", output_mode="content")\`
+  - Search for code with special chars: \`grep(pattern="def __init__(self):")\`
+`;
+const EXECUTE_TOOL_DESCRIPTION = context`
+  Executes a shell command in an isolated sandbox environment.
 
-Usage:
-Executes a given command in the sandbox environment with proper handling and security measures.
-Before executing the command, please follow these steps:
+  Usage:
+  Executes a given command in the sandbox environment with proper handling and security measures.
+  Before executing the command, please follow these steps:
 
-1. Directory Verification:
-   - If the command will create new directories or files, first use the ls tool to verify the parent directory exists and is the correct location
-   - For example, before running "mkdir foo/bar", first use ls to check that "foo" exists and is the intended parent directory
+  1. Directory Verification:
+    - If the command will create new directories or files, first use the ls tool to verify the parent directory exists and is the correct location
+    - For example, before running "mkdir foo/bar", first use ls to check that "foo" exists and is the intended parent directory
 
-2. Command Execution:
-   - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
-   - Examples of proper quoting:
-     - cd "/Users/name/My Documents" (correct)
-     - cd /Users/name/My Documents (incorrect - will fail)
-     - python "/path/with spaces/script.py" (correct)
-     - python /path/with spaces/script.py (incorrect - will fail)
-   - After ensuring proper quoting, execute the command
-   - Capture the output of the command
+  2. Command Execution:
+    - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
+    - Examples of proper quoting:
+      - cd "/Users/name/My Documents" (correct)
+      - cd /Users/name/My Documents (incorrect - will fail)
+      - python "/path/with spaces/script.py" (correct)
+      - python /path/with spaces/script.py (incorrect - will fail)
+    - After ensuring proper quoting, execute the command
+    - Capture the output of the command
 
-Usage notes:
-  - Commands run in an isolated sandbox environment
-  - Returns combined stdout/stderr output with exit code
-  - If the output is very large, it may be truncated
-  - VERY IMPORTANT: You MUST avoid using search commands like find and grep. Instead use the grep, glob tools to search. You MUST avoid read tools like cat, head, tail, and use read_file to read files.
-  - When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines are ok in quoted strings)
-    - Use '&&' when commands depend on each other (e.g., "mkdir dir && cd dir")
-    - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
-  - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of cd
+  Usage notes:
+    - Commands run in an isolated sandbox environment
+    - Returns combined stdout/stderr output with exit code
+    - If the output is very large, it may be truncated
+    - VERY IMPORTANT: You MUST avoid using search commands like find and grep. Instead use the grep, glob tools to search. You MUST avoid read tools like cat, head, tail, and use read_file to read files.
+    - When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines are ok in quoted strings)
+      - Use '&&' when commands depend on each other (e.g., "mkdir dir && cd dir")
+      - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
+    - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of cd
 
-Examples:
-  Good examples:
-    - execute(command="pytest /foo/bar/tests")
-    - execute(command="python /path/to/script.py")
-    - execute(command="npm install && npm test")
+  Examples:
+    Good examples:
+      - execute(command="pytest /foo/bar/tests")
+      - execute(command="python /path/to/script.py")
+      - execute(command="npm install && npm test")
 
-  Bad examples (avoid these):
-    - execute(command="cd /foo/bar && pytest tests")  # Use absolute path instead
-    - execute(command="cat file.txt")  # Use read_file tool instead
-    - execute(command="find . -name '*.py'")  # Use glob tool instead
-    - execute(command="grep -r 'pattern' .")  # Use grep tool instead
+    Bad examples (avoid these):
+      - execute(command="cd /foo/bar && pytest tests")  # Use absolute path instead
+      - execute(command="cat file.txt")  # Use read_file tool instead
+      - execute(command="find . -name '*.py'")  # Use glob tool instead
+      - execute(command="grep -r 'pattern' .")  # Use grep tool instead
 
-Note: This tool is only available if the backend supports execution (SandboxBackendProtocol).
-If execution is not supported, the tool will return an error message.`;
-const EXECUTION_SYSTEM_PROMPT = `## Execute Tool \`execute\`
+  Note: This tool is only available if the backend supports execution (SandboxBackendProtocol).
+  If execution is not supported, the tool will return an error message.
+`;
+const EXECUTION_SYSTEM_PROMPT = context`
+  ## Execute Tool \`execute\`
 
-You have access to an \`execute\` tool for running shell commands in a sandboxed environment.
-Use this tool to run commands, scripts, tests, builds, and other shell operations.
+  You have access to an \`execute\` tool for running shell commands in a sandboxed environment.
+  Use this tool to run commands, scripts, tests, builds, and other shell operations.
 
-- execute: run a shell command in the sandbox (returns output and exit code)`;
+  - execute: run a shell command in the sandbox (returns output and exit code)
+`;
 /**
 * Create ls tool using backend.
 */
@@ -864,7 +1170,9 @@ function createLsTool(backend, options) {
 	return tool(async (input, runtime) => {
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		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)`);
@@ -889,15 +1197,64 @@ function createReadFileTool(backend, options) {
 	return tool(async (input, runtime) => {
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		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,
@@ -978,7 +1335,9 @@ function createGlobTool(backend, options) {
 	return tool(async (input, runtime) => {
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		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");
@@ -1000,12 +1359,13 @@ function createGrepTool(backend, options) {
 	return tool(async (input, runtime) => {
 		const resolvedBackend = await resolveBackend(backend, runtime);
 		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}:`);
@@ -1021,7 +1381,7 @@ function createGrepTool(backend, options) {
 		schema: z.object({
 			pattern: z.string().describe("Regex pattern to search for"),
 			path: z.string().optional().default("/").describe("Base path to search from (default: /)"),
-			glob: z.string().optional().nullable().describe("Optional glob pattern to filter files (e.g., '*.py')")
+			glob: z.string().optional().nullable().default(null).describe("Optional glob pattern to filter files (e.g., '*.py')")
 		})
 	});
 }
@@ -1221,117 +1581,117 @@ const EXCLUDED_STATE_KEYS = [
 */
 const DEFAULT_GENERAL_PURPOSE_DESCRIPTION = "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
 function getTaskToolDescription(subagentDescriptions) {
-	return `
-Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.
+	return context`
+    Launch an ephemeral subagent to handle complex, multi-step independent tasks with isolated context windows.
 
-Available agent types and the tools they have access to:
-${subagentDescriptions.join("\n")}
+    Available agent types and the tools they have access to:
+    ${subagentDescriptions.join("\n")}
 
-When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+    When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
 
-## Usage notes:
-1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
-4. The agent's outputs should generally be trusted
-5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
-6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-7. When only the general-purpose agent is provided, you should use it for all tasks. It is great for isolating context and token usage, and completing specific, complex tasks, as it has all the same capabilities as the main agent.
+    ## Usage notes:
+    1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+    2. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+    3. Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report. Therefore, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+    4. The agent's outputs should generally be trusted
+    5. Clearly tell the agent whether you expect it to create content, perform analysis, or just do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+    6. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+    7. When only the general-purpose agent is provided, you should use it for all tasks. It is great for isolating context and token usage, and completing specific, complex tasks, as it has all the same capabilities as the main agent.
 
-### Example usage of the general-purpose agent:
+    ### Example usage of the general-purpose agent:
 
-<example_agent_descriptions>
-"general-purpose": use this agent for general purpose tasks, it has access to all tools as the main agent.
-</example_agent_descriptions>
+    <example_agent_descriptions>
+    "general-purpose": use this agent for general purpose tasks, it has access to all tools as the main agent.
+    </example_agent_descriptions>
 
-<example>
-User: "I want to conduct research on the accomplishments of Lebron James, Michael Jordan, and Kobe Bryant, and then compare them."
-Assistant: *Uses the task tool in parallel to conduct isolated research on each of the three players*
-Assistant: *Synthesizes the results of the three isolated research tasks and responds to the User*
-<commentary>
-Research is a complex, multi-step task in it of itself.
-The research of each individual player is not dependent on the research of the other players.
-The assistant uses the task tool to break down the complex objective into three isolated tasks.
-Each research task only needs to worry about context and tokens about one player, then returns synthesized information about each player as the Tool Result.
-This means each research task can dive deep and spend tokens and context deeply researching each player, but the final result is synthesized information, and saves us tokens in the long run when comparing the players to each other.
-</commentary>
-</example>
+    <example>
+    User: "I want to conduct research on the accomplishments of Lebron James, Michael Jordan, and Kobe Bryant, and then compare them."
+    Assistant: *Uses the task tool in parallel to conduct isolated research on each of the three players*
+    Assistant: *Synthesizes the results of the three isolated research tasks and responds to the User*
+    <commentary>
+    Research is a complex, multi-step task in it of itself.
+    The research of each individual player is not dependent on the research of the other players.
+    The assistant uses the task tool to break down the complex objective into three isolated tasks.
+    Each research task only needs to worry about context and tokens about one player, then returns synthesized information about each player as the Tool Result.
+    This means each research task can dive deep and spend tokens and context deeply researching each player, but the final result is synthesized information, and saves us tokens in the long run when comparing the players to each other.
+    </commentary>
+    </example>
 
-<example>
-User: "Analyze a single large code repository for security vulnerabilities and generate a report."
-Assistant: *Launches a single \`task\` subagent for the repository analysis*
-Assistant: *Receives report and integrates results into final summary*
-<commentary>
-Subagent is used to isolate a large, context-heavy task, even though there is only one. This prevents the main thread from being overloaded with details.
-If the user then asks followup questions, we have a concise report to reference instead of the entire history of analysis and tool calls, which is good and saves us time and money.
-</commentary>
-</example>
+    <example>
+    User: "Analyze a single large code repository for security vulnerabilities and generate a report."
+    Assistant: *Launches a single \`task\` subagent for the repository analysis*
+    Assistant: *Receives report and integrates results into final summary*
+    <commentary>
+    Subagent is used to isolate a large, context-heavy task, even though there is only one. This prevents the main thread from being overloaded with details.
+    If the user then asks followup questions, we have a concise report to reference instead of the entire history of analysis and tool calls, which is good and saves us time and money.
+    </commentary>
+    </example>
 
-<example>
-User: "Schedule two meetings for me and prepare agendas for each."
-Assistant: *Calls the task tool in parallel to launch two \`task\` subagents (one per meeting) to prepare agendas*
-Assistant: *Returns final schedules and agendas*
-<commentary>
-Tasks are simple individually, but subagents help silo agenda preparation.
-Each subagent only needs to worry about the agenda for one meeting.
-</commentary>
-</example>
+    <example>
+    User: "Schedule two meetings for me and prepare agendas for each."
+    Assistant: *Calls the task tool in parallel to launch two \`task\` subagents (one per meeting) to prepare agendas*
+    Assistant: *Returns final schedules and agendas*
+    <commentary>
+    Tasks are simple individually, but subagents help silo agenda preparation.
+    Each subagent only needs to worry about the agenda for one meeting.
+    </commentary>
+    </example>
 
-<example>
-User: "I want to order a pizza from Dominos, order a burger from McDonald's, and order a salad from Subway."
-Assistant: *Calls tools directly in parallel to order a pizza from Dominos, a burger from McDonald's, and a salad from Subway*
-<commentary>
-The assistant did not use the task tool because the objective is super simple and clear and only requires a few trivial tool calls.
-It is better to just complete the task directly and NOT use the \`task\`tool.
-</commentary>
-</example>
+    <example>
+    User: "I want to order a pizza from Dominos, order a burger from McDonald's, and order a salad from Subway."
+    Assistant: *Calls tools directly in parallel to order a pizza from Dominos, a burger from McDonald's, and a salad from Subway*
+    <commentary>
+    The assistant did not use the task tool because the objective is super simple and clear and only requires a few trivial tool calls.
+    It is better to just complete the task directly and NOT use the \`task\`tool.
+    </commentary>
+    </example>
 
-### Example usage with custom agents:
+    ### Example usage with custom agents:
 
-<example_agent_descriptions>
-"content-reviewer": use this agent after you are done creating significant content or documents
-"greeting-responder": use this agent when to respond to user greetings with a friendly joke
-"research-analyst": use this agent to conduct thorough research on complex topics
-</example_agent_description>
+    <example_agent_descriptions>
+    "content-reviewer": use this agent after you are done creating significant content or documents
+    "greeting-responder": use this agent when to respond to user greetings with a friendly joke
+    "research-analyst": use this agent to conduct thorough research on complex topics
+    </example_agent_description>
 
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: Sure let me write a function that checks if a number is prime
-assistant: First let me use the Write tool to write a function that checks if a number is prime
-assistant: I'm going to use the Write tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since significant content was created and the task was completed, now use the content-reviewer agent to review the work
-</commentary>
-assistant: Now let me use the content-reviewer agent to review the code
-assistant: Uses the Task tool to launch with the content-reviewer agent
-</example>
+    <example>
+    user: "Please write a function that checks if a number is prime"
+    assistant: Sure let me write a function that checks if a number is prime
+    assistant: First let me use the Write tool to write a function that checks if a number is prime
+    assistant: I'm going to use the Write tool to write the following code:
+    <code>
+    function isPrime(n) {{
+      if (n <= 1) return false
+      for (let i = 2; i * i <= n; i++) {{
+        if (n % i === 0) return false
+      }}
+      return true
+    }}
+    </code>
+    <commentary>
+    Since significant content was created and the task was completed, now use the content-reviewer agent to review the work
+    </commentary>
+    assistant: Now let me use the content-reviewer agent to review the code
+    assistant: Uses the Task tool to launch with the content-reviewer agent
+    </example>
 
-<example>
-user: "Can you help me research the environmental impact of different renewable energy sources and create a comprehensive report?"
-<commentary>
-This is a complex research task that would benefit from using the research-analyst agent to conduct thorough analysis
-</commentary>
-assistant: I'll help you research the environmental impact of renewable energy sources. Let me use the research-analyst agent to conduct comprehensive research on this topic.
-assistant: Uses the Task tool to launch with the research-analyst agent, providing detailed instructions about what research to conduct and what format the report should take
-</example>
+    <example>
+    user: "Can you help me research the environmental impact of different renewable energy sources and create a comprehensive report?"
+    <commentary>
+    This is a complex research task that would benefit from using the research-analyst agent to conduct thorough analysis
+    </commentary>
+    assistant: I'll help you research the environmental impact of renewable energy sources. Let me use the research-analyst agent to conduct comprehensive research on this topic.
+    assistant: Uses the Task tool to launch with the research-analyst agent, providing detailed instructions about what research to conduct and what format the report should take
+    </example>
 
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the Task tool to launch with the greeting-responder agent"
-</example>
-  `.trim();
+    <example>
+    user: "Hello"
+    <commentary>
+    Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+    </commentary>
+    assistant: "I'm going to use the Task tool to launch with the greeting-responder agent"
+    </example>
+  `;
 }
 /**
 * System prompt section that explains how to use the task tool for spawning subagents.
@@ -1346,33 +1706,35 @@ assistant: "I'm going to use the Task tool to launch with the greeting-responder
 * You can provide a custom `systemPrompt` to `createSubAgentMiddleware` to override
 * or extend this default.
 */
-const TASK_SYSTEM_PROMPT = `## \`task\` (subagent spawner)
+const TASK_SYSTEM_PROMPT = context`
+  ## \`task\` (subagent spawner)
 
-You have access to a \`task\` tool to launch short-lived subagents that handle isolated tasks. These agents are ephemeral — they live only for the duration of the task and return a single result.
+  You have access to a \`task\` tool to launch short-lived subagents that handle isolated tasks. These agents are ephemeral — they live only for the duration of the task and return a single result.
 
-When to use the task tool:
-- When a task is complex and multi-step, and can be fully delegated in isolation
-- When a task is independent of other tasks and can run in parallel
-- When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread
-- When sandboxing improves reliability (e.g. code execution, structured searches, data formatting)
-- When you only care about the output of the subagent, and not the intermediate steps (ex. performing a lot of research and then returned a synthesized report, performing a series of computations or lookups to achieve a concise, relevant answer.)
+  When to use the task tool:
+  - When a task is complex and multi-step, and can be fully delegated in isolation
+  - When a task is independent of other tasks and can run in parallel
+  - When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread
+  - When sandboxing improves reliability (e.g. code execution, structured searches, data formatting)
+  - When you only care about the output of the subagent, and not the intermediate steps (ex. performing a lot of research and then returned a synthesized report, performing a series of computations or lookups to achieve a concise, relevant answer.)
 
-Subagent lifecycle:
-1. **Spawn** → Provide clear role, instructions, and expected output
-2. **Run** → The subagent completes the task autonomously
-3. **Return** → The subagent provides a single structured result
-4. **Reconcile** → Incorporate or synthesize the result into the main thread
+  Subagent lifecycle:
+  1. **Spawn** → Provide clear role, instructions, and expected output
+  2. **Run** → The subagent completes the task autonomously
+  3. **Return** → The subagent provides a single structured result
+  4. **Reconcile** → Incorporate or synthesize the result into the main thread
 
-When NOT to use the task tool:
-- If you need to see the intermediate reasoning or steps after the subagent has completed (the task tool hides them)
-- If the task is trivial (a few tool calls or simple lookup)
-- If delegating does not reduce token usage, complexity, or context switching
-- If splitting would add latency without benefit
+  When NOT to use the task tool:
+  - If you need to see the intermediate reasoning or steps after the subagent has completed (the task tool hides them)
+  - If the task is trivial (a few tool calls or simple lookup)
+  - If delegating does not reduce token usage, complexity, or context switching
+  - If splitting would add latency without benefit
 
-## Important Task Tool Usage Notes to Remember
-- Whenever possible, parallelize the work that you do. This is true for both tool_calls, and for tasks. Whenever you have independent steps to complete - make tool_calls, or kick off tasks (subagents) in parallel to accomplish them faster. This saves time for the user, which is incredibly important.
-- Remember to use the \`task\` tool to silo independent tasks within a multi-part objective.
-- You should use the \`task\` tool whenever you have a complex task that will take multiple steps, and is independent from other tasks that the agent needs to complete. These agents are highly competent and efficient.`;
+  ## Important Task Tool Usage Notes to Remember
+  - Whenever possible, parallelize the work that you do. This is true for both tool_calls, and for tasks. Whenever you have independent steps to complete - make tool_calls, or kick off tasks (subagents) in parallel to accomplish them faster. This saves time for the user, which is incredibly important.
+  - Remember to use the \`task\` tool to silo independent tasks within a multi-part objective.
+  - You should use the \`task\` tool whenever you have a complex task that will take multiple steps, and is independent from other tasks that the agent needs to complete. These agents are highly competent and efficient.
+`;
 /**
 * Base specification for the general-purpose subagent.
 *
@@ -1781,65 +2143,67 @@ const MemoryStateSchema = new StateSchema({
 * Default system prompt template for memory.
 * Ported from Python's comprehensive memory guidelines.
 */
-const MEMORY_SYSTEM_PROMPT = `<agent_memory>
-{memory_contents}
-</agent_memory>
+const MEMORY_SYSTEM_PROMPT = context`
+  <agent_memory>
+  {memory_contents}
+  </agent_memory>
 
-<memory_guidelines>
-    The above <agent_memory> was loaded in from files in your filesystem. As you learn from your interactions with the user, you can save new knowledge by calling the \`edit_file\` tool.
+  <memory_guidelines>
+      The above <agent_memory> was loaded in from files in your filesystem. As you learn from your interactions with the user, you can save new knowledge by calling the \`edit_file\` tool.
 
-    **Learning from feedback:**
-    - One of your MAIN PRIORITIES is to learn from your interactions with the user. These learnings can be implicit or explicit. This means that in the future, you will remember this important information.
-    - When you need to remember something, updating memory must be your FIRST, IMMEDIATE action - before responding to the user, before calling other tools, before doing anything else. Just update memory immediately.
-    - When user says something is better/worse, capture WHY and encode it as a pattern.
-    - Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions.
-    - A great opportunity to update your memories is when the user interrupts a tool call and provides feedback. You should update your memories immediately before revising the tool call.
-    - Look for the underlying principle behind corrections, not just the specific mistake.
-    - The user might not explicitly ask you to remember something, but if they provide information that is useful for future use, you should update your memories immediately.
+      **Learning from feedback:**
+      - One of your MAIN PRIORITIES is to learn from your interactions with the user. These learnings can be implicit or explicit. This means that in the future, you will remember this important information.
+      - When you need to remember something, updating memory must be your FIRST, IMMEDIATE action - before responding to the user, before calling other tools, before doing anything else. Just update memory immediately.
+      - When user says something is better/worse, capture WHY and encode it as a pattern.
+      - Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions.
+      - A great opportunity to update your memories is when the user interrupts a tool call and provides feedback. You should update your memories immediately before revising the tool call.
+      - Look for the underlying principle behind corrections, not just the specific mistake.
+      - The user might not explicitly ask you to remember something, but if they provide information that is useful for future use, you should update your memories immediately.
 
-    **Asking for information:**
-    - If you lack context to perform an action (e.g. send a Slack DM, requires a user ID/email) you should explicitly ask the user for this information.
-    - It is preferred for you to ask for information, don't assume anything that you do not know!
-    - When the user provides information that is useful for future use, you should update your memories immediately.
+      **Asking for information:**
+      - If you lack context to perform an action (e.g. send a Slack DM, requires a user ID/email) you should explicitly ask the user for this information.
+      - It is preferred for you to ask for information, don't assume anything that you do not know!
+      - When the user provides information that is useful for future use, you should update your memories immediately.
 
-    **When to update memories:**
-    - When the user explicitly asks you to remember something (e.g., "remember my email", "save this preference")
-    - When the user describes your role or how you should behave (e.g., "you are a web researcher", "always do X")
-    - When the user gives feedback on your work - capture what was wrong and how to improve
-    - When the user provides information required for tool use (e.g., slack channel ID, email addresses)
-    - When the user provides context useful for future tasks, such as how to use tools, or which actions to take in a particular situation
-    - When you discover new patterns or preferences (coding styles, conventions, workflows)
+      **When to update memories:**
+      - When the user explicitly asks you to remember something (e.g., "remember my email", "save this preference")
+      - When the user describes your role or how you should behave (e.g., "you are a web researcher", "always do X")
+      - When the user gives feedback on your work - capture what was wrong and how to improve
+      - When the user provides information required for tool use (e.g., slack channel ID, email addresses)
+      - When the user provides context useful for future tasks, such as how to use tools, or which actions to take in a particular situation
+      - When you discover new patterns or preferences (coding styles, conventions, workflows)
 
-    **When to NOT update memories:**
-    - When the information is temporary or transient (e.g., "I'm running late", "I'm on my phone right now")
-    - When the information is a one-time task request (e.g., "Find me a recipe", "What's 25 * 4?")
-    - When the information is a simple question that doesn't reveal lasting preferences (e.g., "What day is it?", "Can you explain X?")
-    - When the information is an acknowledgment or small talk (e.g., "Sounds good!", "Hello", "Thanks for that")
-    - When the information is stale or irrelevant in future conversations
-    - Never store API keys, access tokens, passwords, or any other credentials in any file, memory, or system prompt.
-    - If the user asks where to put API keys or provides an API key, do NOT echo or save it.
+      **When to NOT update memories:**
+      - When the information is temporary or transient (e.g., "I'm running late", "I'm on my phone right now")
+      - When the information is a one-time task request (e.g., "Find me a recipe", "What's 25 * 4?")
+      - When the information is a simple question that doesn't reveal lasting preferences (e.g., "What day is it?", "Can you explain X?")
+      - When the information is an acknowledgment or small talk (e.g., "Sounds good!", "Hello", "Thanks for that")
+      - When the information is stale or irrelevant in future conversations
+      - Never store API keys, access tokens, passwords, or any other credentials in any file, memory, or system prompt.
+      - If the user asks where to put API keys or provides an API key, do NOT echo or save it.
 
-    **Examples:**
-    Example 1 (remembering user information):
-    User: Can you connect to my google account?
-    Agent: Sure, I'll connect to your google account, what's your google account email?
-    User: john@example.com
-    Agent: Let me save this to my memory.
-    Tool Call: edit_file(...) -> remembers that the user's google account email is john@example.com
+      **Examples:**
+      Example 1 (remembering user information):
+      User: Can you connect to my google account?
+      Agent: Sure, I'll connect to your google account, what's your google account email?
+      User: john@example.com
+      Agent: Let me save this to my memory.
+      Tool Call: edit_file(...) -> remembers that the user's google account email is john@example.com
 
-    Example 2 (remembering implicit user preferences):
-    User: Can you write me an example for creating a deep agent in LangChain?
-    Agent: Sure, I'll write you an example for creating a deep agent in LangChain <example code in Python>
-    User: Can you do this in JavaScript
-    Agent: Let me save this to my memory.
-    Tool Call: edit_file(...) -> remembers that the user prefers to get LangChain code examples in JavaScript
-    Agent: Sure, here is the JavaScript example<example code in JavaScript>
+      Example 2 (remembering implicit user preferences):
+      User: Can you write me an example for creating a deep agent in LangChain?
+      Agent: Sure, I'll write you an example for creating a deep agent in LangChain <example code in Python>
+      User: Can you do this in JavaScript
+      Agent: Let me save this to my memory.
+      Tool Call: edit_file(...) -> remembers that the user prefers to get LangChain code examples in JavaScript
+      Agent: Sure, here is the JavaScript example<example code in JavaScript>
 
-    Example 3 (do not remember transient information):
-    User: I'm going to play basketball tonight so I will be offline for a few hours.
-    Agent: Okay I'll add a block to your calendar.
-    Tool Call: create_calendar_event(...) -> just calls a tool, does not commit anything to memory, as it is transient information
-</memory_guidelines>`;
+      Example 3 (do not remember transient information):
+      User: I'm going to play basketball tonight so I will be offline for a few hours.
+      Agent: Okay I'll add a block to your calendar.
+      Tool Call: create_calendar_event(...) -> just calls a tool, does not commit anything to memory, as it is transient information
+  </memory_guidelines>
+`;
 /**
 * Format loaded memory contents for injection into prompt.
 * Pairs memory locations with their contents for clarity.
@@ -1859,12 +2223,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) {
@@ -2035,7 +2401,7 @@ Skills follow a **progressive disclosure** pattern - you know they exist (name +
 1. **Recognize when a skill applies**: Check if the user's task matches any skill's description
 2. **Read the skill's full instructions**: The skill list above shows the exact path to use with read_file
 3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
-4. **Access supporting files**: Skills may include Python scripts, configs, or reference docs - use absolute paths
+4. **Access supporting files**: Skills may include scripts, configs, or reference docs - use absolute paths
 
 **When to Use Skills:**
 - When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
@@ -2047,7 +2413,7 @@ Skills follow a **progressive disclosure** pattern - you know they exist (name +
 - The skill list above shows the full path for each skill's SKILL.md file
 
 **Executing Skill Scripts:**
-Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.
+Skills may contain scripts or other executable files. Always use absolute paths from the skill list.
 
 **Example Workflow:**
 
@@ -2216,12 +2582,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 [];
 	}
@@ -2233,16 +2602,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);
@@ -2265,74 +2635,302 @@ function formatSkillsLocations(sources) {
 	return lines.join("\n");
 }
 /**
-* Format skills metadata for display in system prompt.
-* Shows allowed tools for each skill if specified.
+* Format skills metadata for display in system prompt.
+* Shows allowed tools for each skill if specified.
+*/
+function formatSkillsList(skills, sources) {
+	if (skills.length === 0) return `(No skills available yet. You can create skills in ${sources.map((s) => `\`${s}\``).join(" or ")})`;
+	const lines = [];
+	for (const skill of skills) {
+		const annotations = formatSkillAnnotations(skill);
+		let descLine = `- **${skill.name}**: ${skill.description}`;
+		if (annotations) descLine += ` (${annotations})`;
+		lines.push(descLine);
+		if (skill.allowedTools && skill.allowedTools.length > 0) lines.push(`  → Allowed tools: ${skill.allowedTools.join(", ")}`);
+		lines.push(`  → Read \`${skill.path}\` for full instructions`);
+	}
+	return lines.join("\n");
+}
+/**
+* Create backend-agnostic middleware for loading and exposing agent skills.
+*
+* This middleware loads skills from configurable backend sources and injects
+* skill metadata into the system prompt. It implements the progressive disclosure
+* pattern: skill names and descriptions are shown in the prompt, but the agent
+* reads full SKILL.md content only when needed.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for skills loading and injection
+*
+* @example
+* ```typescript
+* const middleware = createSkillsMiddleware({
+*   backend: new FilesystemBackend({ rootDir: "/" }),
+*   sources: ["/skills/user/", "/skills/project/"],
+* });
+* ```
+*/
+function createSkillsMiddleware(options) {
+	const { backend, sources } = options;
+	let loadedSkills = [];
+	return createMiddleware({
+		name: "SkillsMiddleware",
+		stateSchema: SkillsStateSchema,
+		async beforeAgent(state) {
+			if (loadedSkills.length > 0) return;
+			if ("skillsMetadata" in state && Array.isArray(state.skillsMetadata) && state.skillsMetadata.length > 0) {
+				loadedSkills = state.skillsMetadata;
+				return;
+			}
+			const resolvedBackend = await resolveBackend(backend, { state });
+			const allSkills = /* @__PURE__ */ new Map();
+			for (const sourcePath of sources) try {
+				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
+				for (const skill of skills) allSkills.set(skill.name, skill);
+			} catch (error) {
+				console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
+			}
+			loadedSkills = Array.from(allSkills.values());
+			return { skillsMetadata: loadedSkills };
+		},
+		wrapModelCall(request, handler) {
+			const skillsMetadata = loadedSkills.length > 0 ? loadedSkills : request.state?.skillsMetadata || [];
+			const skillsLocations = formatSkillsLocations(sources);
+			const skillsList = formatSkillsList(skillsMetadata, sources);
+			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
+			const newSystemMessage = request.systemMessage.concat(skillsSection);
+			return handler({
+				...request,
+				systemMessage: newSystemMessage
+			});
+		}
+	});
+}
+//#endregion
+//#region src/middleware/completion_callback.ts
+/**
+* Callback middleware for async subagents.
+*
+* @experimental - this middleware is experimental and may change in future releases.
+*
+* This middleware sends a notification to a callback thread when a subagent
+* completes successfully or raises an error. The callback agent can then
+* process that notification instead of relying only on polling via
+* `check_async_task`.
+*
+* ## Architecture
+*
+* A parent agent launches a subagent with `start_async_task` and can later
+* inspect task state with `check_async_task`. This middleware adds an optional
+* completion signal by creating a run on the callback thread when the subagent
+* finishes.
+*
+* ```
+* Parent                        Subagent
+*     |                            |
+*     |--- start_async_task -----> |
+*     |<-- task_id (immediately) - |
+*     |                            |  (working...)
+*     |                            |  (done!)
+*     |                            |
+*     |<-- runs.create(            |
+*     |      callback_thread,      |
+*     |      "completed: ...")     |
+*     |                            |
+*     |  (processes result)        |
+* ```
+*
+* The middleware calls `runs.create()` on the callback thread. From the
+* callback agent's perspective, this appears as a new user message containing
+* structured output from the subagent.
+*
+* ## Callback context
+*
+* - `callbackGraphId` identifies the callback graph or assistant. It is
+*   provided when the middleware is constructed.
+* - `url` and `headers` optionally configure a remote callback destination.
+*   Omit `url` for same-deployment ASGI transport.
+* - `callback_thread_id` is stored in the subagent state by the parent's
+*   `start_async_task` tool. Because it is stored in state rather than config,
+*   it survives thread updates and interrupts.
+* - If `callback_thread_id` is not present in state, the middleware does
+*   nothing.
+*
+* ## Usage
+*
+* ```typescript
+* import { createCompletionCallbackMiddleware } from "deepagents";
+*
+* // Same deployment (callback agent and subagent share a server):
+* const notifier = createCompletionCallbackMiddleware({
+*   callbackGraphId: "supervisor",
+* });
+*
+* // Remote deployment (callback destination on a different server):
+* const notifier = createCompletionCallbackMiddleware({
+*   callbackGraphId: "supervisor",
+*   url: "https://my-deployment.langsmith.dev",
+* });
+*
+* const agent = createDeepAgent({
+*   model,
+*   middleware: [notifier],
+* });
+* ```
+*
+* The middleware reads `callbackThreadId` from the agent state at the end of
+* execution. This value is injected by the parent's `start_async_task` tool
+* when it creates the run.
+*
+* @module
+*/
+/** Maximum characters to include from the last message in notifications. */
+const MAX_MESSAGE_LENGTH = 500;
+/** Suffix appended when truncating long messages. */
+const TRUNCATION_SUFFIX = "... [full result truncated]";
+/** State key for the callback thread ID. */
+const CALLBACK_THREAD_ID_KEY = "callbackThreadId";
+/**
+* State extension for subagents that use completion callbacks.
+*
+* @experimental - this state schema is experimental and may change in future releases.
+*
+* `callbackThreadId` is written by the parent's `start_async_task` tool
+* and read by `CompletionCallbackMiddleware` when sending callback
+* notifications.
+*/
+const CompletionCallbackStateSchema = z$2.object({ [CALLBACK_THREAD_ID_KEY]: z$2.string().optional() });
+/**
+* Build headers for the callback 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 callback thread.
+*
+* @param callbackGraphId - The callback graph ID used as `assistant_id`
+*   in the `runs.create` call.
+* @param callbackThreadId - The callback thread ID.
+* @param message - The message content to send.
+* @param options - Optional url and headers for the callback server.
 */
-function formatSkillsList(skills, sources) {
-	if (skills.length === 0) return `(No skills available yet. You can create skills in ${sources.map((s) => `\`${s}\``).join(" or ")})`;
-	const lines = [];
-	for (const skill of skills) {
-		const annotations = formatSkillAnnotations(skill);
-		let descLine = `- **${skill.name}**: ${skill.description}`;
-		if (annotations) descLine += ` (${annotations})`;
-		lines.push(descLine);
-		if (skill.allowedTools && skill.allowedTools.length > 0) lines.push(`  → Allowed tools: ${skill.allowedTools.join(", ")}`);
-		lines.push(`  → Read \`${skill.path}\` for full instructions`);
+async function notifyParent(callbackGraphId, callbackThreadId, message, options) {
+	try {
+		await new Client({
+			apiUrl: options?.url ?? void 0,
+			apiKey: null,
+			defaultHeaders: resolveHeaders(options?.headers)
+		}).runs.create(callbackThreadId, callbackGraphId, { input: { messages: [{
+			role: "user",
+			content: message
+		}] } });
+	} catch (e) {
+		console.warn(`[CompletionCallbackMiddleware] Failed to notify callback thread ${callbackThreadId}:`, e);
 	}
-	return lines.join("\n");
 }
 /**
-* Create backend-agnostic middleware for loading and exposing agent skills.
+* Extract a summary from the subagent's final message.
 *
-* This middleware loads skills from configurable backend sources and injects
-* skill metadata into the system prompt. It implements the progressive disclosure
-* pattern: skill names and descriptions are shown in the prompt, but the agent
-* reads full SKILL.md content only when needed.
+* Returns at most 500 characters from the last message's content.
+* Throws if no messages exist or if the last message is not an AIMessage.
 *
-* @param options - Configuration options
-* @returns AgentMiddleware for skills loading and injection
+* @param state - The agent state dict.
+* @param taskId - Optional task ID to include in truncation hint.
+*/
+function extractLastMessage(state, taskId) {
+	const messages = state.messages;
+	if (!messages || messages.length === 0) throw new Error(`Expected at least one message in state ${JSON.stringify(state)}`);
+	const last = messages[messages.length - 1];
+	if (!AIMessage$1.isInstance(last)) throw new TypeError(`Expected an AIMessage, got ${typeof last === "object" && last !== null ? last.constructor?.name ?? typeof last : typeof last} instead`);
+	let textContent = last.text;
+	if (textContent.length > MAX_MESSAGE_LENGTH) {
+		textContent = textContent.slice(0, MAX_MESSAGE_LENGTH) + TRUNCATION_SUFFIX;
+		if (taskId) textContent += ` Result truncated. Use \`check_async_task(task_id='${taskId}')\` to retrieve the full result if needed.`;
+	}
+	return textContent;
+}
+/**
+* Create a completion callback middleware for async subagents.
+*
+* **Experimental** — this middleware is experimental and may change.
+*
+* This middleware is added to a subagent's middleware stack. On success or
+* model-call error, it sends a notification to the configured callback
+* thread by calling `runs.create()`.
+*
+* The callback destination is configured with `callbackGraphId` and
+* optional `url` and `headers`. The target thread is read from
+* `callbackThreadId` in the subagent state.
+*
+* If `callbackThreadId` is not present in state, the middleware does
+* nothing.
+*
+* @param options - Configuration options.
+* @returns An `AgentMiddleware` instance.
 *
 * @example
 * ```typescript
-* const middleware = createSkillsMiddleware({
-*   backend: new FilesystemBackend({ rootDir: "/" }),
-*   sources: ["/skills/user/", "/skills/project/"],
+* import { createCompletionCallbackMiddleware } from "deepagents";
+*
+* const notifier = createCompletionCallbackMiddleware({
+*   callbackGraphId: "supervisor",
+* });
+*
+* const agent = createDeepAgent({
+*   model: "claude-sonnet-4-5-20250929",
+*   middleware: [notifier],
 * });
 * ```
 */
-function createSkillsMiddleware(options) {
-	const { backend, sources } = options;
-	let loadedSkills = [];
+function createCompletionCallbackMiddleware(options) {
+	const { callbackGraphId, url, headers } = options;
+	/**
+	* Send a notification to the callback destination.
+	*/
+	async function sendNotification(callbackThreadId, message) {
+		await notifyParent(callbackGraphId, callbackThreadId, 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
+	* parent'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 createMiddleware({
-		name: "SkillsMiddleware",
-		stateSchema: SkillsStateSchema,
-		async beforeAgent(state) {
-			if (loadedSkills.length > 0) return;
-			if ("skillsMetadata" in state && Array.isArray(state.skillsMetadata) && state.skillsMetadata.length > 0) {
-				loadedSkills = state.skillsMetadata;
-				return;
-			}
-			const resolvedBackend = await resolveBackend(backend, { state });
-			const allSkills = /* @__PURE__ */ new Map();
-			for (const sourcePath of sources) try {
-				const skills = await listSkillsFromBackend(resolvedBackend, sourcePath);
-				for (const skill of skills) allSkills.set(skill.name, skill);
-			} catch (error) {
-				console.debug(`[BackendSkillsMiddleware] Failed to load skills from ${sourcePath}:`, error);
-			}
-			loadedSkills = Array.from(allSkills.values());
-			return { skillsMetadata: loadedSkills };
+		name: "CompletionCallbackMiddleware",
+		stateSchema: CompletionCallbackStateSchema,
+		async afterAgent(state, runtime) {
+			const callbackThreadId = state[CALLBACK_THREAD_ID_KEY];
+			if (callbackThreadId == null) throw new Error(`Missing required state key '${CALLBACK_THREAD_ID_KEY}'`);
+			const taskId = getTaskId(runtime);
+			await sendNotification(callbackThreadId, formatNotification(`Completed. Result: ${extractLastMessage(state, typeof taskId === "string" ? taskId : void 0)}`, runtime));
 		},
-		wrapModelCall(request, handler) {
-			const skillsMetadata = loadedSkills.length > 0 ? loadedSkills : request.state?.skillsMetadata || [];
-			const skillsLocations = formatSkillsLocations(sources);
-			const skillsList = formatSkillsList(skillsMetadata, sources);
-			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
-			const newSystemMessage = request.systemMessage.concat(skillsSection);
-			return handler({
-				...request,
-				systemMessage: newSystemMessage
-			});
+		async wrapModelCall(request, handler) {
+			try {
+				return await handler(request);
+			} catch (e) {
+				const callbackThreadId = request.state[CALLBACK_THREAD_ID_KEY];
+				if (typeof callbackThreadId === "string") await sendNotification(callbackThreadId, formatNotification("The agent encountered an error while calling the model.", request.runtime));
+				throw e;
+			}
 		}
 	});
 }
@@ -2860,15 +3458,17 @@ function createSummarizationMiddleware(options) {
 	*/
 	function buildSummaryMessage(summary, filePath) {
 		let content;
-		if (filePath) content = `You are in the middle of a conversation that has been summarized.
+		if (filePath) content = context`
+        You are in the middle of a conversation that has been summarized.
 
-The full conversation history has been saved to ${filePath} should you need to refer back to it for details.
+        The full conversation history has been saved to ${filePath} should you need to refer back to it for details.
 
-A condensed summary follows:
+        A condensed summary follows:
 
-<summary>
-${summary}
-</summary>`;
+        <summary>
+        ${summary}
+        </summary>
+      `;
 		else content = `Here is a summary of the conversation to date:\n\n${summary}`;
 		return new HumanMessage({
 			content,
@@ -2934,92 +3534,661 @@ ${summary}
 				if (!isContextOverflow(err)) throw err;
 			}
 		}
-		const previousEvent = request.state._summarizationEvent;
-		const previousCutoffIndex = previousEvent != null ? previousEvent.cutoffIndex : void 0;
-		const { summaryMessage, filePath, stateCutoffIndex } = await summarizeMessages(messagesToSummarize, resolvedModel, request.state, previousCutoffIndex, cutoffIndex);
-		let modifiedMessages = [summaryMessage, ...preservedMessages];
-		const modifiedTokens = countTotalTokens(modifiedMessages, request.systemMessage, request.tools);
-		let finalStateCutoffIndex = stateCutoffIndex;
-		let finalSummaryMessage = summaryMessage;
-		let finalFilePath = filePath;
+		const previousEvent = request.state._summarizationEvent;
+		const previousCutoffIndex = previousEvent != null ? previousEvent.cutoffIndex : void 0;
+		const { summaryMessage, filePath, stateCutoffIndex } = await summarizeMessages(messagesToSummarize, resolvedModel, request.state, previousCutoffIndex, cutoffIndex);
+		let modifiedMessages = [summaryMessage, ...preservedMessages];
+		const modifiedTokens = countTotalTokens(modifiedMessages, request.systemMessage, request.tools);
+		let finalStateCutoffIndex = stateCutoffIndex;
+		let finalSummaryMessage = summaryMessage;
+		let finalFilePath = filePath;
+		try {
+			await handler({
+				...request,
+				messages: modifiedMessages
+			});
+		} catch (err) {
+			if (!isContextOverflow(err)) throw err;
+			if (maxInputTokens && modifiedTokens > 0) {
+				const observedRatio = maxInputTokens / modifiedTokens;
+				if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
+			}
+			const reSumResult = await summarizeMessages([...messagesToSummarize, ...preservedMessages], resolvedModel, request.state, previousCutoffIndex, truncatedMessages.length);
+			finalSummaryMessage = reSumResult.summaryMessage;
+			finalFilePath = reSumResult.filePath;
+			finalStateCutoffIndex = reSumResult.stateCutoffIndex;
+			modifiedMessages = [reSumResult.summaryMessage];
+			await handler({
+				...request,
+				messages: modifiedMessages
+			});
+		}
+		return new Command({ update: {
+			_summarizationEvent: {
+				cutoffIndex: finalStateCutoffIndex,
+				summaryMessage: finalSummaryMessage,
+				filePath: finalFilePath
+			},
+			_summarizationSessionId: getSessionId(request.state)
+		} });
+	}
+	return createMiddleware({
+		name: "SummarizationMiddleware",
+		stateSchema: SummarizationStateSchema,
+		async wrapModelCall(request, handler) {
+			const effectiveMessages = getEffectiveMessages(request.messages ?? [], request.state);
+			if (effectiveMessages.length === 0) return handler(request);
+			/**
+			* Resolve the chat model and get max input tokens from its profile.
+			*/
+			const resolvedModel = await getChatModel();
+			const maxInputTokens = getMaxInputTokens(resolvedModel);
+			applyModelDefaults(resolvedModel);
+			/**
+			* Step 1: Truncate args if configured
+			*/
+			const { messages: truncatedMessages } = truncateArgs(effectiveMessages, maxInputTokens, request.systemMessage, request.tools);
+			/**
+			* Step 2: Check if summarization should happen.
+			* Count tokens including system message and tools to match what's
+			* actually sent to the model (matching Python implementation).
+			*/
+			const totalTokens = countTotalTokens(truncatedMessages, request.systemMessage, request.tools);
+			/**
+			* If no summarization needed, try passing through.
+			* If the handler throws a ContextOverflowError, fall back to
+			* emergency summarization (matching Python's behavior).
+			*/
+			if (!shouldSummarize(truncatedMessages, totalTokens, maxInputTokens)) try {
+				return await handler({
+					...request,
+					messages: truncatedMessages
+				});
+			} catch (err) {
+				if (!isContextOverflow(err)) throw err;
+				if (maxInputTokens && totalTokens > 0) {
+					const observedRatio = maxInputTokens / totalTokens;
+					if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
+				}
+			}
+			/**
+			* Step 3: Perform summarization
+			*/
+			return performSummarization(request, handler, truncatedMessages, resolvedModel, maxInputTokens);
+		}
+	});
+}
+//#endregion
+//#region src/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 = z.object({
+	taskId: z.string(),
+	agentName: z.string(),
+	threadId: z.string(),
+	runId: z.string(),
+	status: z.string(),
+	createdAt: z.string(),
+	description: z.string().optional(),
+	updatedAt: z.string().optional(),
+	checkedAt: 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 StateSchema({ asyncTasks: new ReducedValue(z.record(z.string(), AsyncTaskSchema).default(() => ({})), {
+	inputSchema: z.record(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 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 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 servers)
+
+You have access to async subagent tools that launch background tasks on remote 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.
+*/
+/**
+* Names of the tools added by the async subagent middleware.
+*
+* Exported so `agent.ts` can include them in `BUILTIN_TOOL_NAMES` and
+* surface a `ConfigurationError` if a user-provided tool collides.
+*/
+const ASYNC_TASK_TOOL_NAMES = [
+	"start_async_task",
+	"check_async_task",
+	"update_async_task",
+	"cancel_async_task",
+	"list_async_tasks"
+];
+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 Agent Protocol server.
+	*
+	* Adds `x-auth-scheme: langsmith` by default unless already provided.
+	* For self-hosted servers that don't require this header, it is typically
+	* ignored. Override via the `headers` field on the AsyncSubAgent config.
+	*/
+	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 Client({
+			apiUrl: spec.url,
+			defaultHeaders: headers
+		});
+		this.clients.set(key, client);
+		return client;
+	}
+};
+/**
+* Extract the callback thread ID from the tool runtime.
+*
+* The thread ID is included in the subagent's input state so the subagent
+* can notify the parent when it completes (via
+* `CompletionCallbackMiddleware`).
+*
+* @returns Object with `callbackThreadId` if available. Empty object otherwise.
+*/
+function extractCallbackContext(runtime) {
+	const threadId = (runtime.config?.configurable)?.thread_id;
+	if (typeof threadId === "string" && threadId) return { callbackThreadId: threadId };
+	return {};
+}
+/**
+* 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 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];
+		const callbackContext = extractCallbackContext(runtime);
 		try {
-			await handler({
-				...request,
-				messages: modifiedMessages
-			});
-		} catch (err) {
-			if (!isContextOverflow(err)) throw err;
-			if (maxInputTokens && modifiedTokens > 0) {
-				const observedRatio = maxInputTokens / modifiedTokens;
-				if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
-			}
-			const reSumResult = await summarizeMessages([...messagesToSummarize, ...preservedMessages], resolvedModel, request.state, previousCutoffIndex, truncatedMessages.length);
-			finalSummaryMessage = reSumResult.summaryMessage;
-			finalFilePath = reSumResult.filePath;
-			finalStateCutoffIndex = reSumResult.stateCutoffIndex;
-			modifiedMessages = [reSumResult.summaryMessage];
-			await handler({
-				...request,
-				messages: modifiedMessages
+			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
+				}],
+				...callbackContext
+			} });
+			const taskId = thread.thread_id;
+			const task = {
+				taskId,
+				agentName: input.agentName,
+				threadId: taskId,
+				runId: run.run_id,
+				status: "running",
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				description: input.description
+			};
+			return new Command({ update: {
+				messages: [new 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: z.object({
+			description: z.string().describe("A detailed description of the task for the async subagent to perform."),
+			agentName: 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 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: result.status !== task.status ? (/* @__PURE__ */ new Date()).toISOString() : task.updatedAt,
+			checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		return new Command({ update: {
+			messages: [new 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: z.object({ taskId: 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 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,
+				description: input.message,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				checkedAt: tracked.checkedAt
+			};
+			return new Command({ update: {
+				messages: [new 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: z.object({
+			taskId: z.string().describe("The exact taskId string returned by start_async_task. Pass it verbatim."),
+			message: 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 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: (/* @__PURE__ */ new Date()).toISOString(),
+			checkedAt: tracked.checkedAt
+		};
 		return new Command({ update: {
-			_summarizationEvent: {
-				cutoffIndex: finalStateCutoffIndex,
-				summaryMessage: finalSummaryMessage,
-				filePath: finalFilePath
-			},
-			_summarizationSessionId: getSessionId(request.state)
+			messages: [new 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: z.object({ taskId: 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 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: status !== task.status ? (/* @__PURE__ */ new Date()).toISOString() : task.updatedAt,
+				checkedAt: task.checkedAt
+			};
+		}
+		return new Command({ update: {
+			messages: [new 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: z.object({ statusFilter: 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 Agent Protocol servers. Task state is
+* persisted in the `asyncTasks` state channel so it survives
+* context compaction.
+*
+* Works with any Agent Protocol-compliant server — LangGraph Platform (managed)
+* or self-hosted (e.g. a Hono/Express server implementing the Agent Protocol spec).
+*
+* @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-agent-protocol-server.example.com",
+*     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 createMiddleware({
-		name: "SummarizationMiddleware",
-		stateSchema: SummarizationStateSchema,
-		async wrapModelCall(request, handler) {
-			const effectiveMessages = getEffectiveMessages(request.messages ?? [], request.state);
-			if (effectiveMessages.length === 0) return handler(request);
-			/**
-			* Resolve the chat model and get max input tokens from its profile.
-			*/
-			const resolvedModel = await getChatModel();
-			const maxInputTokens = getMaxInputTokens(resolvedModel);
-			applyModelDefaults(resolvedModel);
-			/**
-			* Step 1: Truncate args if configured
-			*/
-			const { messages: truncatedMessages } = truncateArgs(effectiveMessages, maxInputTokens, request.systemMessage, request.tools);
-			/**
-			* Step 2: Check if summarization should happen.
-			* Count tokens including system message and tools to match what's
-			* actually sent to the model (matching Python implementation).
-			*/
-			const totalTokens = countTotalTokens(truncatedMessages, request.systemMessage, request.tools);
-			/**
-			* If no summarization needed, try passing through.
-			* If the handler throws a ContextOverflowError, fall back to
-			* emergency summarization (matching Python's behavior).
-			*/
-			if (!shouldSummarize(truncatedMessages, totalTokens, maxInputTokens)) try {
-				return await handler({
-					...request,
-					messages: truncatedMessages
-				});
-			} catch (err) {
-				if (!isContextOverflow(err)) throw err;
-				if (maxInputTokens && totalTokens > 0) {
-					const observedRatio = maxInputTokens / totalTokens;
-					if (observedRatio > tokenEstimationMultiplier) tokenEstimationMultiplier = observedRatio * 1.1;
-				}
-			}
-			/**
-			* Step 3: Perform summarization
-			*/
-			return performSummarization(request, handler, truncatedMessages, resolvedModel, maxInputTokens);
+		name: "asyncSubAgentMiddleware",
+		stateSchema: AsyncTaskStateSchema,
+		tools,
+		wrapModelCall: async (request, handler) => {
+			if (fullSystemPrompt !== null) return handler({
+				...request,
+				systemMessage: request.systemMessage.concat(new SystemMessage({ content: fullSystemPrompt }))
+			});
+			return handler(request);
 		}
 	});
 }
 //#endregion
 //#region src/backends/store.ts
+/**
+* StoreBackend: Adapter for LangGraph's BaseStore (persistent, cross-thread).
+*/
 const NAMESPACE_COMPONENT_RE = /^[A-Za-z0-9\-_.@+:~]+$/;
 /**
 * Validate a namespace array.
@@ -3054,34 +4223,55 @@ function validateNamespace(namespace) {
 var StoreBackend = class {
 	stateAndStore;
 	_namespace;
-	constructor(stateAndStore, options) {
-		this.stateAndStore = stateAndStore;
-		if (options?.namespace) this._namespace = validateNamespace(options.namespace);
+	fileFormat;
+	constructor(stateAndStoreOrOptions, options) {
+		let opts;
+		if (stateAndStoreOrOptions != null && typeof stateAndStoreOrOptions === "object" && "state" in stateAndStoreOrOptions) {
+			this.stateAndStore = stateAndStoreOrOptions;
+			opts = options;
+		} else {
+			this.stateAndStore = void 0;
+			opts = stateAndStoreOrOptions;
+		}
+		if (opts?.namespace) this._namespace = validateNamespace(opts.namespace);
+		this.fileFormat = opts?.fileFormat ?? "v2";
 	}
 	/**
-	* Get the store instance.
+	* Get the BaseStore instance for persistent storage operations.
+	*
+	* In legacy mode, reads from the injected {@link StateAndStore}.
+	* In zero-arg mode, retrieves the store from the LangGraph execution
+	* context via {@link getLangGraphStore}.
 	*
 	* @returns BaseStore instance
-	* @throws Error if no store is available
+	* @throws Error if no store is available in either mode
 	*/
 	getStore() {
-		const store = this.stateAndStore.store;
-		if (!store) throw new Error("Store is required but not available in StateAndStore");
+		if (this.stateAndStore) {
+			const store = this.stateAndStore.store;
+			if (!store) throw new Error("Store is required but not available in runtime");
+			return store;
+		}
+		const store = getStore();
+		if (!store) throw new Error("Store is required but not available in LangGraph execution context. Ensure the graph was configured with a store.");
 		return store;
 	}
 	/**
 	* Get the namespace for store operations.
 	*
-	* If a custom namespace was provided, returns it directly.
-	*
-	* Otherwise, falls back to legacy behavior:
-	* - If assistantId is set: [assistantId, "filesystem"]
-	* - Otherwise: ["filesystem"]
+	* Resolution order:
+	* 1. Explicit namespace from constructor options (both modes)
+	* 2. Legacy mode: `[assistantId, "filesystem"]` fallback from {@link StateAndStore}
+	* 3. Zero-arg mode without namespace: `["filesystem"]` with a deprecation warning
+	*    nudging callers to pass an explicit namespace
+	* 4. Legacy mode without assistantId: `["filesystem"]`
 	*/
 	getNamespace() {
 		if (this._namespace) return this._namespace;
-		const assistantId = this.stateAndStore.assistantId;
-		if (assistantId) return [assistantId, "filesystem"];
+		if (this.stateAndStore) {
+			const assistantId = this.stateAndStore.assistantId;
+			if (assistantId) return [assistantId, "filesystem"];
+		}
 		return ["filesystem"];
 	}
 	/**
@@ -3093,9 +4283,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
 		};
@@ -3104,11 +4295,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
 		};
@@ -3143,10 +4335,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);
@@ -3164,7 +4356,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,
@@ -3182,35 +4374,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.
@@ -3220,7 +4426,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 {
@@ -3255,9 +4462,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);
@@ -3267,12 +4475,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);
@@ -3283,12 +4491,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,
@@ -3296,7 +4504,7 @@ var StoreBackend = class {
 				modified_at: fd?.modified_at || ""
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Upload multiple files.
@@ -3309,7 +4517,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({
@@ -3344,11 +4556,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 {
@@ -3386,7 +4604,7 @@ var FilesystemBackend = class {
 	maxFileSizeBytes;
 	constructor(options = {}) {
 		const { rootDir, virtualMode = false, maxFileSizeMb = 10 } = options;
-		this.cwd = rootDir ? path.resolve(rootDir) : process.cwd();
+		this.cwd = rootDir ? path$1.resolve(rootDir) : process.cwd();
 		this.virtualMode = virtualMode;
 		this.maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
 	}
@@ -3406,13 +4624,13 @@ var FilesystemBackend = class {
 		if (this.virtualMode) {
 			const vpath = key.startsWith("/") ? key : "/" + key;
 			if (vpath.includes("..") || vpath.startsWith("~")) throw new Error("Path traversal not allowed");
-			const full = path.resolve(this.cwd, vpath.substring(1));
-			const relative = path.relative(this.cwd, full);
-			if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
+			const full = path$1.resolve(this.cwd, vpath.substring(1));
+			const relative = path$1.relative(this.cwd, full);
+			if (relative.startsWith("..") || path$1.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
 			return full;
 		}
-		if (path.isAbsolute(key)) return key;
-		return path.resolve(this.cwd, key);
+		if (path$1.isAbsolute(key)) return key;
+		return path$1.resolve(this.cwd, key);
 	}
 	/**
 	* List files and directories in the specified directory (non-recursive).
@@ -3421,15 +4639,15 @@ 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 fs.stat(resolvedPath)).isDirectory()) return [];
+			if (!(await fs.stat(resolvedPath)).isDirectory()) return { files: [] };
 			const entries = await fs.readdir(resolvedPath, { withFileTypes: true });
 			const results = [];
-			const cwdStr = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+			const cwdStr = this.cwd.endsWith(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
 			for (const entry of entries) {
-				const fullPath = path.join(resolvedPath, entry.name);
+				const fullPath = path$1.join(resolvedPath, entry.name);
 				try {
 					const entryStat = await fs.stat(fullPath);
 					const isFile = entryStat.isFile();
@@ -3442,7 +4660,7 @@ var FilesystemBackend = class {
 							modified_at: entryStat.mtime.toISOString()
 						});
 						else if (isDir) results.push({
-							path: fullPath + path.sep,
+							path: fullPath + path$1.sep,
 							is_dir: true,
 							size: 0,
 							modified_at: entryStat.mtime.toISOString()
@@ -3452,7 +4670,7 @@ var FilesystemBackend = class {
 						if (fullPath.startsWith(cwdStr)) relativePath = fullPath.substring(cwdStr.length);
 						else if (fullPath.startsWith(this.cwd)) relativePath = fullPath.substring(this.cwd.length).replace(/^[/\\]/, "");
 						else relativePath = fullPath;
-						relativePath = relativePath.split(path.sep).join("/");
+						relativePath = relativePath.split(path$1.sep).join("/");
 						const virtPath = "/" + relativePath;
 						if (isFile) results.push({
 							path: virtPath,
@@ -3472,9 +4690,9 @@ var FilesystemBackend = class {
 				}
 			}
 			results.sort((a, b) => a.path.localeCompare(b.path));
-			return results;
+			return { files: results };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 	}
 	/**
@@ -3488,62 +4706,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 fs.stat(resolvedPath)).isFile()) return `Error: File '${filePath}' not found`;
+				if (!(await fs.stat(resolvedPath)).isFile()) return { error: `File '${filePath}' not found` };
 				const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.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 fs.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 fs.readFile(resolvedPath);
+					return {
+						content: new Uint8Array(buffer),
+						mimeType
+					};
+				}
 				content = await fs.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 fs.stat(resolvedPath);
-			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			if (!stat.isFile()) return { error: `File '${filePath}' not found` };
 			const fd = await fs.open(resolvedPath, fs$1.constants.O_RDONLY | fs$1.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 fs.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 fs.readFile(resolvedPath);
+				return { data: {
+					content: new Uint8Array(buffer),
+					mimeType,
+					created_at: stat.ctime.toISOString(),
+					modified_at: stat.mtime.toISOString()
+				} };
+			}
 			content = await fs.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.
@@ -3552,19 +4813,26 @@ var FilesystemBackend = class {
 	async write(filePath, content) {
 		try {
 			const resolvedPath = this.resolvePath(filePath);
+			const isBinary = !isTextMimeType(getMimeType(filePath));
 			try {
 				if ((await fs.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.` };
 			} catch {}
-			await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
 			if (SUPPORTS_NOFOLLOW) {
 				const flags = fs$1.constants.O_WRONLY | fs$1.constants.O_CREAT | fs$1.constants.O_TRUNC | fs$1.constants.O_NOFOLLOW;
 				const fd = await fs.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 fs.writeFile(resolvedPath, buffer);
 			} else await fs.writeFile(resolvedPath, content, "utf-8");
 			return {
 				path: filePath,
@@ -3627,17 +4895,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 fs.stat(baseFull);
 		} catch {
-			return [];
+			return { matches: [] };
 		}
 		let results = await this.ripgrepSearch(pattern, baseFull, glob);
 		if (results === null) results = await this.literalSearch(pattern, baseFull, glob);
@@ -3647,7 +4915,7 @@ var FilesystemBackend = class {
 			line: lineNum,
 			text: lineText
 		});
-		return matches;
+		return { matches };
 	}
 	/**
 	* Search using ripgrep with fixed-string (literal) mode.
@@ -3684,10 +4952,10 @@ var FilesystemBackend = class {
 						if (!ftext) continue;
 						let virtPath;
 						if (this.virtualMode) try {
-							const resolved = path.resolve(ftext);
-							const relative = path.relative(this.cwd, resolved);
+							const resolved = path$1.resolve(ftext);
+							const relative = path$1.relative(this.cwd, resolved);
 							if (relative.startsWith("..")) continue;
-							virtPath = "/" + relative.split(path.sep).join("/");
+							virtPath = "/" + relative.split(path$1.sep).join("/");
 						} catch {
 							continue;
 						}
@@ -3721,13 +4989,14 @@ var FilesystemBackend = class {
 	async literalSearch(pattern, baseFull, includeGlob) {
 		const results = {};
 		const files = await fg("**/*", {
-			cwd: (await fs.stat(baseFull)).isDirectory() ? baseFull : path.dirname(baseFull),
+			cwd: (await fs.stat(baseFull)).isDirectory() ? baseFull : path$1.dirname(baseFull),
 			absolute: true,
 			onlyFiles: true,
 			dot: true
 		});
 		for (const fp of files) try {
-			if (includeGlob && !micromatch.isMatch(path.basename(fp), includeGlob)) continue;
+			if (!isTextMimeType(getMimeType(fp))) continue;
+			if (includeGlob && !micromatch.isMatch(path$1.basename(fp), includeGlob)) continue;
 			if ((await fs.stat(fp)).size > this.maxFileSizeBytes) continue;
 			const lines = (await fs.readFile(fp, "utf-8")).split("\n");
 			for (let i = 0; i < lines.length; i++) {
@@ -3735,9 +5004,9 @@ var FilesystemBackend = class {
 				if (line.includes(pattern)) {
 					let virtPath;
 					if (this.virtualMode) try {
-						const relative = path.relative(this.cwd, fp);
+						const relative = path$1.relative(this.cwd, fp);
 						if (relative.startsWith("..")) continue;
-						virtPath = "/" + relative.split(path.sep).join("/");
+						virtPath = "/" + relative.split(path$1.sep).join("/");
 					} catch {
 						continue;
 					}
@@ -3754,13 +5023,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 fs.stat(resolvedSearchPath)).isDirectory()) return [];
+			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 		const results = [];
 		try {
@@ -3773,7 +5042,7 @@ var FilesystemBackend = class {
 			for (const matchedPath of matches) try {
 				const stat = await fs.stat(matchedPath);
 				if (!stat.isFile()) continue;
-				const normalizedPath = matchedPath.split("/").join(path.sep);
+				const normalizedPath = matchedPath.split("/").join(path$1.sep);
 				if (!this.virtualMode) results.push({
 					path: normalizedPath,
 					is_dir: false,
@@ -3781,12 +5050,12 @@ var FilesystemBackend = class {
 					modified_at: stat.mtime.toISOString()
 				});
 				else {
-					const cwdStr = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
+					const cwdStr = this.cwd.endsWith(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
 					let relativePath;
 					if (normalizedPath.startsWith(cwdStr)) relativePath = normalizedPath.substring(cwdStr.length);
 					else if (normalizedPath.startsWith(this.cwd)) relativePath = normalizedPath.substring(this.cwd.length).replace(/^[/\\]/, "");
 					else relativePath = normalizedPath;
-					relativePath = relativePath.split(path.sep).join("/");
+					relativePath = relativePath.split(path$1.sep).join("/");
 					const virt = "/" + relativePath;
 					results.push({
 						path: virt,
@@ -3800,7 +5069,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.
@@ -3812,7 +5081,7 @@ var FilesystemBackend = class {
 		const responses = [];
 		for (const [filePath, content] of files) try {
 			const resolvedPath = this.resolvePath(filePath);
-			await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+			await fs.mkdir(path$1.dirname(resolvedPath), { recursive: true });
 			await fs.writeFile(resolvedPath, content);
 			responses.push({
 				path: filePath,
@@ -3895,9 +5164,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() {
@@ -3921,25 +5190,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,
@@ -3947,9 +5218,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.
@@ -3967,7 +5238,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);
@@ -3976,53 +5247,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.
@@ -4250,7 +5527,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;
 	}
 	/**
@@ -4267,25 +5544,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;
-		const cwdPrefix = this.cwd.endsWith(path.sep) ? this.cwd : this.cwd + path.sep;
-		return results.map((info) => ({
+	async ls(dirPath) {
+		const result = await super.ls(dirPath);
+		if (result.error) return result;
+		if (this.virtualMode) return result;
+		const cwdPrefix = this.cwd.endsWith(path$1.sep) ? this.cwd : this.cwd + path$1.sep;
+		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 ? path.resolve(this.cwd, searchPath.replace(/^\//, "")) : path.resolve(this.cwd, searchPath);
+		const resolvedSearchPath = searchPath === "/" || searchPath === "" ? this.cwd : this.virtualMode ? path$1.resolve(this.cwd, searchPath.replace(/^\//, "")) : path$1.resolve(this.cwd, searchPath);
 		try {
-			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return [];
+			if (!(await fs.stat(resolvedSearchPath)).isDirectory()) return { files: [] };
 		} catch {
-			return [];
+			return { files: [] };
 		}
 		const formatPath = (rel) => this.virtualMode ? `/${rel}` : rel;
 		const globOpts = {
@@ -4302,7 +5580,7 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 		})]);
 		const statFile = async (match) => {
 			try {
-				const entryStat = await fs.stat(path.join(resolvedSearchPath, match));
+				const entryStat = await fs.stat(path$1.join(resolvedSearchPath, match));
 				if (entryStat.isFile()) return {
 					path: formatPath(match),
 					is_dir: false,
@@ -4314,7 +5592,7 @@ var LocalShellBackend = class LocalShellBackend extends FilesystemBackend {
 		};
 		const statDir = async (match) => {
 			try {
-				const entryStat = await fs.stat(path.join(resolvedSearchPath, match));
+				const entryStat = await fs.stat(path$1.join(resolvedSearchPath, match));
 				if (entryStat.isDirectory()) return {
 					path: formatPath(match),
 					is_dir: true,
@@ -4327,7 +5605,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.
@@ -4602,9 +5880,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 = [];
@@ -4619,7 +5897,7 @@ var BaseSandbox = class {
 				modified_at: (/* @__PURE__ */ new Date(parsed.mtime * 1e3)).toISOString()
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Read file content with line numbers.
@@ -4634,11 +5912,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.
@@ -4646,18 +5939,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.
@@ -4667,23 +5967,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.
@@ -4698,7 +6000,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);
@@ -4716,7 +6018,7 @@ var BaseSandbox = class {
 				modified_at: (/* @__PURE__ */ new Date(parsed.mtime * 1e3)).toISOString()
 			});
 		}
-		return infos;
+		return { files: infos };
 	}
 	/**
 	* Create a new file with content.
@@ -4729,8 +6031,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,
@@ -5065,9 +6370,44 @@ function createCacheBreakpointMiddleware() {
 }
 //#endregion
 //#region src/agent.ts
-const BASE_PROMPT = `In order to complete the objective that the user asks of you, you have access to a number of standard tools.`;
+const BASE_AGENT_PROMPT = context`
+  You are a Deep Agent, an AI assistant that helps users accomplish tasks using tools. You respond with text and tool calls. The user can see your responses and tool outputs in real time.
+
+  ## Core Behavior
+
+  - Be concise and direct. Don't over-explain unless asked.
+  - NEVER add unnecessary preamble (\"Sure!\", \"Great question!\", \"I'll now...\").
+  - Don't say \"I'll now do X\" — just do it.
+  - If the request is ambiguous, ask questions before acting.
+  - If asked how to approach something, explain first, then act.
+
+  ## Professional Objectivity
+
+  - Prioritize accuracy over validating the user's beliefs
+  - Disagree respectfully when the user is incorrect
+  - Avoid unnecessary superlatives, praise, or emotional validation
+
+  ## Doing Tasks
+
+  When the user asks you to do something:
+
+  1. **Understand first** — read relevant files, check existing patterns. Quick but thorough — gather enough evidence to start, then iterate.
+  2. **Act** — implement the solution. Work quickly but accurately.
+  3. **Verify** — check your work against what was asked, not against your own output. Your first attempt is rarely correct — iterate.
+
+  Keep working until the task is fully complete. Don't stop partway and explain what you would do — just do it. Only yield back to the user when the task is done or you're genuinely blocked.
+
+  **When things go wrong:**
+  - If something fails repeatedly, stop and analyze *why* — don't keep retrying the same approach.
+  - If you're blocked, tell the user what's wrong and ask for guidance.
+
+  ## Progress Updates
+
+  For longer tasks, provide brief progress updates at reasonable intervals — a concise sentence recapping what you've done and what's next.
+`;
 const BUILTIN_TOOL_NAMES = new Set([
 	...FILESYSTEM_TOOL_NAMES,
+	...ASYNC_TASK_TOOL_NAMES,
 	"task",
 	"write_todos"
 ]);
@@ -5084,19 +6424,18 @@ function isAnthropicModel(model) {
 	return model.getName() === "ChatAnthropic";
 }
 /**
-* Create a Deep Agent with middleware-based architecture.
+* Create a Deep Agent.
 *
-* Matches Python's create_deep_agent function, using middleware for all features:
-* - Todo management (todoListMiddleware)
-* - Filesystem tools (createFilesystemMiddleware)
-* - Subagent delegation (createSubAgentMiddleware)
-* - Conversation summarization (createSummarizationMiddleware) with backend offloading
-* - Prompt caching (anthropicPromptCachingMiddleware)
-* - Tool call patching (createPatchToolCallsMiddleware)
-* - Human-in-the-loop (humanInTheLoopMiddleware) - optional
+* This is the main entry point for building a production-style agent with
+* deepagents. It gives you a strong default runtime (filesystem, tasks,
+* subagents, summarization) and lets you opt into skills, memory,
+* human-in-the-loop interrupts, async subagents, and custom middleware.
+*
+* The runtime is intentionally opinionated: defaults work out of the box, and
+* when you customize behavior, the middleware ordering stays deterministic.
 *
 * @param params Configuration parameters for the agent
-* @returns ReactAgent instance ready for invocation with properly inferred state types
+* @returns Deep Agent instance with inferred state/response types
 *
 * @example
 * ```typescript
@@ -5115,92 +6454,92 @@ function isAnthropicModel(model) {
 * ```
 */
 function createDeepAgent(params = {}) {
-	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name, memory, skills } = params;
+	const { model = new ChatAnthropic("claude-sonnet-4-6"), tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend = (config) => new StateBackend(config), interruptOn, name, memory, skills } = params;
 	const collidingTools = tools.map((t) => t.name).filter((n) => typeof n === "string" && BUILTIN_TOOL_NAMES.has(n));
 	if (collidingTools.length > 0) throw new ConfigurationError(`Tool name(s) [${collidingTools.join(", ")}] conflict with built-in tools. Rename your custom tools to avoid this.`, "TOOL_NAME_COLLISION");
 	const anthropicModel = isAnthropicModel(model);
-	const finalSystemPrompt = new SystemMessage({ content: systemPrompt ? typeof systemPrompt === "string" ? [{
-		type: "text",
-		text: `${systemPrompt}\n\n${BASE_PROMPT}`
-	}] : [{
-		type: "text",
-		text: BASE_PROMPT
-	}, ...typeof systemPrompt.content === "string" ? [{
-		type: "text",
-		text: systemPrompt.content
-	}] : systemPrompt.content] : [{
-		type: "text",
-		text: BASE_PROMPT
-	}] });
-	/**
-	* Create backend configuration for filesystem middleware
-	* If no backend is provided, use a factory that creates a StateBackend
-	*/
-	const filesystemBackend = backend ? backend : (runtime) => new StateBackend(runtime);
-	/**
-	* Skills middleware (created conditionally for runtime use)
-	*/
-	const skillsMiddlewareArray = skills != null && skills.length > 0 ? [createSkillsMiddleware({
-		backend: filesystemBackend,
-		sources: skills
-	})] : [];
-	/**
-	* Memory middleware (created conditionally for runtime use)
-	*/
-	const memoryMiddlewareArray = memory != null && memory.length > 0 ? [createMemoryMiddleware({
-		backend: filesystemBackend,
-		sources: memory,
-		addCacheControl: anthropicModel
-	})] : [];
+	const cacheMiddleware = anthropicModel ? [anthropicPromptCachingMiddleware({
+		unsupportedModelBehavior: "ignore",
+		minMessagesToCache: 1
+	}), createCacheBreakpointMiddleware()] : [];
 	/**
 	* 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).
+	* Only the general-purpose subagent inherits the main agent's skills.
 	* If a custom subagent needs skills, it must specify its own `skills` array.
 	*/
-	const processedSubagents = subagents.map((subagent) => {
-		/**
-		* CompiledSubAgent - use as-is (already has its own middleware baked in)
-		*/
-		if (Runnable.isRunnable(subagent)) return subagent;
-		/**
-		* SubAgent without skills - use as-is
-		*/
-		if (!("skills" in subagent) || subagent.skills?.length === 0) return subagent;
-		/**
-		* SubAgent with skills - add SkillsMiddleware BEFORE user's middleware
-		* Order: base middleware (via defaultMiddleware) → skills → user's middleware
-		* This matches Python's ordering in create_deep_agent
-		*/
-		const subagentSkillsMiddleware = createSkillsMiddleware({
-			backend: filesystemBackend,
-			sources: subagent.skills ?? []
-		});
+	const normalizeSubagentSpec = (input) => {
+		const subagentMiddleware = [
+			todoListMiddleware(),
+			createFilesystemMiddleware({ backend }),
+			createSummarizationMiddleware({
+				backend,
+				model
+			}),
+			createPatchToolCallsMiddleware(),
+			...input.skills != null && input.skills.length > 0 ? [createSkillsMiddleware({
+				backend,
+				sources: input.skills
+			})] : [],
+			...input.middleware ?? [],
+			...cacheMiddleware
+		];
 		return {
-			...subagent,
-			middleware: [subagentSkillsMiddleware, ...subagent.middleware || []]
+			...input,
+			tools: input.tools ?? [],
+			middleware: subagentMiddleware
 		};
-	});
-	/**
-	* Middleware for custom subagents (does NOT include skills from main agent).
-	* Custom subagents must define their own `skills` property to get skills.
-	*
-	* Uses createSummarizationMiddleware (deepagents version) with backend support
-	* and auto-computed defaults from model profile, matching Python's create_deep_agent.
-	* When trigger is not provided, defaults are lazily computed:
-	*   - With model profile: fraction-based (trigger=0.85, keep=0.10)
-	*   - Without profile: fixed (trigger=170k tokens, keep=6 messages)
-	*/
-	const subagentMiddleware = [
+	};
+	const allSubagents = subagents;
+	const asyncSubAgents = allSubagents.filter((item) => isAsyncSubAgent(item));
+	const inlineSubagents = allSubagents.filter((item) => !isAsyncSubAgent(item)).map((item) => "runnable" in item ? item : normalizeSubagentSpec(item));
+	if (!inlineSubagents.some((item) => item.name === GENERAL_PURPOSE_SUBAGENT["name"])) {
+		const generalPurposeSpec = normalizeSubagentSpec({
+			...GENERAL_PURPOSE_SUBAGENT,
+			model,
+			skills,
+			tools
+		});
+		inlineSubagents.unshift(generalPurposeSpec);
+	}
+	const skillsMiddleware = skills != null && skills.length > 0 ? [createSkillsMiddleware({
+		backend,
+		sources: skills
+	})] : [];
+	const [todoMiddleware, fsMiddleware, subagentMiddleware, summarizationMiddleware, patchToolCallsMiddleware] = [
 		todoListMiddleware(),
-		createFilesystemMiddleware({ backend: filesystemBackend }),
+		createFilesystemMiddleware({ backend }),
+		createSubAgentMiddleware({
+			defaultModel: model,
+			defaultTools: tools,
+			defaultInterruptOn: interruptOn,
+			subagents: inlineSubagents,
+			generalPurposeAgent: false
+		}),
 		createSummarizationMiddleware({
 			model,
-			backend: filesystemBackend
+			backend
 		}),
 		createPatchToolCallsMiddleware()
 	];
+	const middleware = [
+		todoMiddleware,
+		...skillsMiddleware,
+		fsMiddleware,
+		subagentMiddleware,
+		summarizationMiddleware,
+		patchToolCallsMiddleware,
+		...asyncSubAgents.length > 0 ? [createAsyncSubAgentMiddleware({ asyncSubAgents })] : [],
+		...customMiddleware,
+		...cacheMiddleware,
+		...memory && memory.length > 0 ? [createMemoryMiddleware({
+			backend,
+			sources: memory,
+			addCacheControl: anthropicModel
+		})] : [],
+		...interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : []
+	];
 	/**
 	* Return as DeepAgent with proper DeepAgentTypeConfig
 	* - Response: InferStructuredResponse<TResponse> (unwraps ToolStrategy<T>/ProviderStrategy<T> → T)
@@ -5212,54 +6551,32 @@ function createDeepAgent(params = {}) {
 	*/
 	return createAgent({
 		model,
-		systemPrompt: finalSystemPrompt,
+		systemPrompt: typeof systemPrompt === "string" ? new SystemMessage({ contentBlocks: [{
+			type: "text",
+			text: systemPrompt
+		}, {
+			type: "text",
+			text: BASE_AGENT_PROMPT
+		}] }) : SystemMessage.isInstance(systemPrompt) ? new SystemMessage({ contentBlocks: [...systemPrompt.contentBlocks, {
+			type: "text",
+			text: BASE_AGENT_PROMPT
+		}] }) : new SystemMessage({ contentBlocks: [{
+			type: "text",
+			text: BASE_AGENT_PROMPT
+		}] }),
 		tools,
-		middleware: [
-			...[
-				todoListMiddleware(),
-				createFilesystemMiddleware({ backend: filesystemBackend }),
-				createSubAgentMiddleware({
-					defaultModel: model,
-					defaultTools: tools,
-					defaultMiddleware: [...subagentMiddleware, ...anthropicModel ? [anthropicPromptCachingMiddleware({
-						unsupportedModelBehavior: "ignore",
-						minMessagesToCache: 1
-					}), createCacheBreakpointMiddleware()] : []],
-					generalPurposeMiddleware: [
-						...subagentMiddleware,
-						...skillsMiddlewareArray,
-						...anthropicModel ? [anthropicPromptCachingMiddleware({
-							unsupportedModelBehavior: "ignore",
-							minMessagesToCache: 1
-						}), createCacheBreakpointMiddleware()] : []
-					],
-					defaultInterruptOn: interruptOn,
-					subagents: processedSubagents,
-					generalPurposeAgent: true
-				}),
-				createSummarizationMiddleware({
-					model,
-					backend: filesystemBackend
-				}),
-				createPatchToolCallsMiddleware()
-			],
-			...skillsMiddlewareArray,
-			...customMiddleware,
-			...anthropicModel ? [anthropicPromptCachingMiddleware({
-				unsupportedModelBehavior: "ignore",
-				minMessagesToCache: 1
-			}), createCacheBreakpointMiddleware()] : [],
-			...memoryMiddlewareArray,
-			...interruptOn ? [humanInTheLoopMiddleware({ interruptOn })] : []
-		],
-		...responseFormat != null && { responseFormat },
+		middleware,
+		...responseFormat !== null && { responseFormat },
 		contextSchema,
 		checkpointer,
 		store,
 		name
 	}).withConfig({
 		recursionLimit: 1e4,
-		metadata: { ls_integration: "deepagents" }
+		metadata: {
+			ls_integration: "deepagents",
+			lc_agent_name: name
+		}
 	});
 }
 //#endregion
@@ -5280,13 +6597,13 @@ function createDeepAgent(params = {}) {
 * @returns Path to the project root if found, null otherwise.
 */
 function findProjectRoot(startPath) {
-	let current = path.resolve(startPath || process.cwd());
-	while (current !== path.dirname(current)) {
-		const gitDir = path.join(current, ".git");
+	let current = path$1.resolve(startPath || process.cwd());
+	while (current !== path$1.dirname(current)) {
+		const gitDir = path$1.join(current, ".git");
 		if (fs$1.existsSync(gitDir)) return current;
-		current = path.dirname(current);
+		current = path$1.dirname(current);
 	}
-	const rootGitDir = path.join(current, ".git");
+	const rootGitDir = path$1.join(current, ".git");
 	if (fs$1.existsSync(rootGitDir)) return current;
 	return null;
 }
@@ -5308,14 +6625,14 @@ function isValidAgentName(agentName) {
 */
 function createSettings(options = {}) {
 	const projectRoot = findProjectRoot(options.startPath);
-	const userDeepagentsDir = path.join(os.homedir(), ".deepagents");
+	const userDeepagentsDir = path$1.join(os.homedir(), ".deepagents");
 	return {
 		projectRoot,
 		userDeepagentsDir,
 		hasProject: projectRoot !== null,
 		getAgentDir(agentName) {
 			if (!isValidAgentName(agentName)) throw new Error(`Invalid agent name: ${JSON.stringify(agentName)}. Agent names can only contain letters, numbers, hyphens, underscores, and spaces.`);
-			return path.join(userDeepagentsDir, agentName);
+			return path$1.join(userDeepagentsDir, agentName);
 		},
 		ensureAgentDir(agentName) {
 			const agentDir = this.getAgentDir(agentName);
@@ -5323,14 +6640,14 @@ function createSettings(options = {}) {
 			return agentDir;
 		},
 		getUserAgentMdPath(agentName) {
-			return path.join(this.getAgentDir(agentName), "agent.md");
+			return path$1.join(this.getAgentDir(agentName), "agent.md");
 		},
 		getProjectAgentMdPath() {
 			if (!projectRoot) return null;
-			return path.join(projectRoot, ".deepagents", "agent.md");
+			return path$1.join(projectRoot, ".deepagents", "agent.md");
 		},
 		getUserSkillsDir(agentName) {
-			return path.join(this.getAgentDir(agentName), "skills");
+			return path$1.join(this.getAgentDir(agentName), "skills");
 		},
 		ensureUserSkillsDir(agentName) {
 			const skillsDir = this.getUserSkillsDir(agentName);
@@ -5339,7 +6656,7 @@ function createSettings(options = {}) {
 		},
 		getProjectSkillsDir() {
 			if (!projectRoot) return null;
-			return path.join(projectRoot, ".deepagents", "skills");
+			return path$1.join(projectRoot, ".deepagents", "skills");
 		},
 		ensureProjectSkillsDir() {
 			const skillsDir = this.getProjectSkillsDir();
@@ -5349,7 +6666,7 @@ function createSettings(options = {}) {
 		},
 		ensureProjectDeepagentsDir() {
 			if (!projectRoot) return null;
-			const deepagentsDir = path.join(projectRoot, ".deepagents");
+			const deepagentsDir = path$1.join(projectRoot, ".deepagents");
 			fs$1.mkdirSync(deepagentsDir, { recursive: true });
 			return deepagentsDir;
 		}
@@ -5601,7 +6918,7 @@ function isSafePath(targetPath, baseDir) {
 	try {
 		const resolvedPath = fs$1.realpathSync(targetPath);
 		const resolvedBase = fs$1.realpathSync(baseDir);
-		return resolvedPath.startsWith(resolvedBase + path.sep) || resolvedPath === resolvedBase;
+		return resolvedPath.startsWith(resolvedBase + path$1.sep) || resolvedPath === resolvedBase;
 	} catch {
 		return false;
 	}
@@ -5680,7 +6997,7 @@ function parseSkillMetadata(skillMdPath, source) {
 			console.warn(`Skipping ${skillMdPath}: missing required 'name' or 'description'`);
 			return null;
 		}
-		const directoryName = path.basename(path.dirname(skillMdPath));
+		const directoryName = path$1.basename(path$1.dirname(skillMdPath));
 		const validation = validateSkillName(String(name), directoryName);
 		if (!validation.valid) console.warn(`Skill '${name}' in ${skillMdPath} does not follow Agent Skills spec: ${validation.error}. Consider renaming to be spec-compliant.`);
 		let descriptionStr = String(description);
@@ -5723,7 +7040,7 @@ function parseSkillMetadata(skillMdPath, source) {
 * @returns List of skill metadata
 */
 function listSkillsFromDir(skillsDir, source) {
-	const expandedDir = skillsDir.startsWith("~") ? path.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
+	const expandedDir = skillsDir.startsWith("~") ? path$1.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
 	if (!fs$1.existsSync(expandedDir)) return [];
 	let resolvedBase;
 	try {
@@ -5739,10 +7056,10 @@ function listSkillsFromDir(skillsDir, source) {
 		return [];
 	}
 	for (const entry of entries) {
-		const skillDir = path.join(resolvedBase, entry.name);
+		const skillDir = path$1.join(resolvedBase, entry.name);
 		if (!isSafePath(skillDir, resolvedBase)) continue;
 		if (!entry.isDirectory()) continue;
-		const skillMdPath = path.join(skillDir, "SKILL.md");
+		const skillMdPath = path$1.join(skillDir, "SKILL.md");
 		if (!fs$1.existsSync(skillMdPath)) continue;
 		if (!isSafePath(skillMdPath, resolvedBase)) continue;
 		const metadata = parseSkillMetadata(skillMdPath, source);
@@ -5773,6 +7090,6 @@ function listSkills(options) {
 	return Array.from(allSkills.values());
 }
 //#endregion
-export { BaseSandbox, CompositeBackend, ConfigurationError, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, LangSmithSandbox, LocalShellBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata, resolveBackend };
+export { BaseSandbox, CompositeBackend, ConfigurationError, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, FilesystemBackend, GENERAL_PURPOSE_SUBAGENT, LangSmithSandbox, LocalShellBackend, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, SandboxError, StateBackend, StoreBackend, TASK_SYSTEM_PROMPT, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
 
 //# sourceMappingURL=index.js.map