deepagents 1.3.0 → 1.4.0

package/dist/index.cjs

@@ -0,0 +1,3431 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let langchain = require("langchain");
+let _langchain_langgraph = require("@langchain/langgraph");
+let zod_v4 = require("zod/v4");
+let micromatch = require("micromatch");
+micromatch = __toESM(micromatch);
+let path = require("path");
+let zod_v3 = require("zod/v3");
+let _langchain_core_messages = require("@langchain/core/messages");
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let node_child_process = require("node:child_process");
+let fast_glob = require("fast-glob");
+fast_glob = __toESM(fast_glob);
+let node_os = require("node:os");
+node_os = __toESM(node_os);
+let zod = require("zod");
+let yaml = require("yaml");
+yaml = __toESM(yaml);
+
+//#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";
+}
+
+//#endregion
+//#region src/backends/utils.ts
+/**
+* Shared utility functions for memory backend implementations.
+*
+* This module contains both user-facing string formatters and structured
+* helpers used by backends and the composite router. Structured helpers
+* enable composition without fragile string parsing.
+*/
+const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
+const MAX_LINE_LENGTH = 1e4;
+const LINE_NUMBER_WIDTH = 6;
+/**
+* Sanitize tool_call_id to prevent path traversal and separator issues.
+*
+* Replaces dangerous characters (., /, \) with underscores.
+*/
+function sanitizeToolCallId(toolCallId) {
+	return toolCallId.replace(/\./g, "_").replace(/\//g, "_").replace(/\\/g, "_");
+}
+/**
+* Format file content with line numbers (cat -n style).
+*
+* Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2).
+*
+* @param content - File content as string or list of lines
+* @param startLine - Starting line number (default: 1)
+* @returns Formatted content with line numbers and continuation markers
+*/
+function formatContentWithLineNumbers(content, startLine = 1) {
+	let lines;
+	if (typeof content === "string") {
+		lines = content.split("\n");
+		if (lines.length > 0 && lines[lines.length - 1] === "") lines = lines.slice(0, -1);
+	} else lines = content;
+	const resultLines = [];
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const lineNum = i + startLine;
+		if (line.length <= MAX_LINE_LENGTH) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${line}`);
+		else {
+			const numChunks = Math.ceil(line.length / MAX_LINE_LENGTH);
+			for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
+				const start = chunkIdx * MAX_LINE_LENGTH;
+				const end = Math.min(start + MAX_LINE_LENGTH, line.length);
+				const chunk = line.substring(start, end);
+				if (chunkIdx === 0) resultLines.push(`${lineNum.toString().padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+				else {
+					const continuationMarker = `${lineNum}.${chunkIdx}`;
+					resultLines.push(`${continuationMarker.padStart(LINE_NUMBER_WIDTH)}\t${chunk}`);
+				}
+			}
+		}
+	}
+	return resultLines.join("\n");
+}
+/**
+* Check if content is empty and return warning message.
+*
+* @param content - Content to check
+* @returns Warning message if empty, null otherwise
+*/
+function checkEmptyContent(content) {
+	if (!content || content.trim() === "") return EMPTY_CONTENT_WARNING;
+	return null;
+}
+/**
+* Convert FileData to plain string content.
+*
+* @param fileData - FileData object with 'content' key
+* @returns Content as string with lines joined by newlines
+*/
+function fileDataToString(fileData) {
+	return fileData.content.join("\n");
+}
+/**
+* Create a FileData object with timestamps.
+*
+* @param content - File content as string
+* @param createdAt - Optional creation timestamp (ISO format)
+* @returns FileData object with content and timestamps
+*/
+function createFileData(content, createdAt) {
+	const lines = typeof content === "string" ? content.split("\n") : content;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		content: lines,
+		created_at: createdAt || now,
+		modified_at: now
+	};
+}
+/**
+* Update FileData with new content, preserving creation timestamp.
+*
+* @param fileData - Existing FileData object
+* @param content - New content as string
+* @returns Updated FileData object
+*/
+function updateFileData(fileData, content) {
+	const lines = typeof content === "string" ? content.split("\n") : content;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		content: lines,
+		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
+* @param oldString - String to replace
+* @param newString - Replacement string
+* @param replaceAll - Whether to replace all occurrences
+* @returns Tuple of [new_content, occurrences] on success, or error message string
+*/
+function performStringReplacement(content, oldString, newString, replaceAll) {
+	const occurrences = content.split(oldString).length - 1;
+	if (occurrences === 0) return `Error: String not found in file: '${oldString}'`;
+	if (occurrences > 1 && !replaceAll) return `Error: String '${oldString}' appears ${occurrences} times in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context.`;
+	return [content.split(oldString).join(newString), occurrences];
+}
+/**
+* Validate and normalize a path.
+*
+* @param path - Path to validate
+* @returns Normalized path starting with / and ending with /
+* @throws Error if path is invalid
+*/
+function validatePath(path$4) {
+	const pathStr = path$4 || "/";
+	if (!pathStr || pathStr.trim() === "") throw new Error("Path cannot be empty");
+	let normalized = pathStr.startsWith("/") ? pathStr : "/" + pathStr;
+	if (!normalized.endsWith("/")) normalized += "/";
+	return normalized;
+}
+/**
+* Search files dict for paths matching glob pattern.
+*
+* @param files - Dictionary of file paths to FileData
+* @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
+* @param path - Base path to search from
+* @returns Newline-separated file paths, sorted by modification time (most recent first).
+*          Returns "No files found" if no matches.
+*
+* @example
+* ```typescript
+* const files = {"/src/main.py": FileData(...), "/test.py": FileData(...)};
+* globSearchFiles(files, "*.py", "/");
+* // Returns: "/test.py\n/src/main.py" (sorted by modified_at)
+* ```
+*/
+function globSearchFiles(files, pattern, path$4 = "/") {
+	let normalizedPath;
+	try {
+		normalizedPath = validatePath(path$4);
+	} catch {
+		return "No files found";
+	}
+	const filtered = Object.fromEntries(Object.entries(files).filter(([fp]) => fp.startsWith(normalizedPath)));
+	const effectivePattern = pattern;
+	const matches = [];
+	for (const [filePath, fileData] of Object.entries(filtered)) {
+		let relative = filePath.substring(normalizedPath.length);
+		if (relative.startsWith("/")) relative = relative.substring(1);
+		if (!relative) {
+			const parts = filePath.split("/");
+			relative = parts[parts.length - 1] || "";
+		}
+		if (micromatch.default.isMatch(relative, effectivePattern, {
+			dot: true,
+			nobrace: false
+		})) matches.push([filePath, fileData.modified_at]);
+	}
+	matches.sort((a, b) => b[1].localeCompare(a[1]));
+	if (matches.length === 0) return "No files found";
+	return matches.map(([fp]) => fp).join("\n");
+}
+/**
+* Return structured grep matches from an in-memory files mapping.
+*
+* Returns a list of GrepMatch on success, or a string for invalid inputs
+* (e.g., invalid regex). We deliberately do not raise here to keep backends
+* non-throwing in tool contexts and preserve user-facing error messages.
+*/
+function grepMatchesFromFiles(files, pattern, path$4 = null, glob = null) {
+	let regex;
+	try {
+		regex = new RegExp(pattern);
+	} catch (e) {
+		return `Invalid regex pattern: ${e.message}`;
+	}
+	let normalizedPath;
+	try {
+		normalizedPath = validatePath(path$4);
+	} catch {
+		return [];
+	}
+	let filtered = Object.fromEntries(Object.entries(files).filter(([fp]) => fp.startsWith(normalizedPath)));
+	if (glob) filtered = Object.fromEntries(Object.entries(filtered).filter(([fp]) => micromatch.default.isMatch((0, path.basename)(fp), glob, {
+		dot: true,
+		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 (regex.test(line)) matches.push({
+			path: filePath,
+			line: lineNum,
+			text: line
+		});
+	}
+	return matches;
+}
+
+//#endregion
+//#region src/backends/state.ts
+/**
+* Backend that stores files in agent state (ephemeral).
+*
+* Uses LangGraph's state management and checkpointing. Files persist within
+* a conversation thread but not across threads. State is automatically
+* checkpointed after each agent step.
+*
+* Special handling: Since LangGraph state must be updated via Command objects
+* (not direct mutation), operations return filesUpdate in WriteResult/EditResult
+* for the middleware to apply via Command.
+*/
+var StateBackend = class {
+	stateAndStore;
+	constructor(stateAndStore) {
+		this.stateAndStore = stateAndStore;
+	}
+	/**
+	* Get files from current state.
+	*/
+	getFiles() {
+		return this.stateAndStore.state.files || {};
+	}
+	/**
+	* 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.
+	*          Directories have a trailing / in their path and is_dir=true.
+	*/
+	lsInfo(path$4) {
+		const files = this.getFiles();
+		const infos = [];
+		const subdirs = /* @__PURE__ */ new Set();
+		const normalizedPath = path$4.endsWith("/") ? path$4 : path$4 + "/";
+		for (const [k, fd] of Object.entries(files)) {
+			if (!k.startsWith(normalizedPath)) continue;
+			const relative = k.substring(normalizedPath.length);
+			if (relative.includes("/")) {
+				const subdirName = relative.split("/")[0];
+				subdirs.add(normalizedPath + subdirName + "/");
+				continue;
+			}
+			const size = fd.content.join("\n").length;
+			infos.push({
+				path: k,
+				is_dir: false,
+				size,
+				modified_at: fd.modified_at
+			});
+		}
+		for (const subdir of Array.from(subdirs).sort()) infos.push({
+			path: subdir,
+			is_dir: true,
+			size: 0,
+			modified_at: ""
+		});
+		infos.sort((a, b) => a.path.localeCompare(b.path));
+		return infos;
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @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
+	*/
+	read(filePath, offset = 0, limit = 2e3) {
+		const fileData = this.getFiles()[filePath];
+		if (!fileData) return `Error: File '${filePath}' not found`;
+		return formatReadResponse(fileData, offset, limit);
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	readRaw(filePath) {
+		const fileData = this.getFiles()[filePath];
+		if (!fileData) throw new Error(`File '${filePath}' not found`);
+		return fileData;
+	}
+	/**
+	* Create a new file with content.
+	* Returns WriteResult with filesUpdate to update LangGraph state.
+	*/
+	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);
+		return {
+			path: filePath,
+			filesUpdate: { [filePath]: newFileData }
+		};
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	* Returns EditResult with filesUpdate and occurrences.
+	*/
+	edit(filePath, oldString, newString, replaceAll = false) {
+		const fileData = this.getFiles()[filePath];
+		if (!fileData) return { error: `Error: File '${filePath}' not found` };
+		const result = performStringReplacement(fileDataToString(fileData), oldString, newString, replaceAll);
+		if (typeof result === "string") return { error: result };
+		const [newContent, occurrences] = result;
+		const newFileData = updateFileData(fileData, newContent);
+		return {
+			path: filePath,
+			filesUpdate: { [filePath]: newFileData },
+			occurrences
+		};
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	grepRaw(pattern, path$4 = "/", glob = null) {
+		return grepMatchesFromFiles(this.getFiles(), pattern, path$4, glob);
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	globInfo(pattern, path$4 = "/") {
+		const files = this.getFiles();
+		const result = globSearchFiles(files, pattern, path$4);
+		if (result === "No files found") return [];
+		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;
+			infos.push({
+				path: p,
+				is_dir: false,
+				size,
+				modified_at: fd?.modified_at || ""
+			});
+		}
+		return infos;
+	}
+	/**
+	* Upload multiple files.
+	*
+	* Note: Since LangGraph state must be updated via Command objects,
+	* the caller must apply filesUpdate via Command after calling this method.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	uploadFiles(files) {
+		const responses = [];
+		const updates = {};
+		for (const [path$4, content] of files) try {
+			updates[path$4] = createFileData(new TextDecoder().decode(content));
+			responses.push({
+				path: path$4,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$4,
+				error: "invalid_path"
+			});
+		}
+		const result = responses;
+		result.filesUpdate = updates;
+		return result;
+	}
+	/**
+	* Download multiple files.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	downloadFiles(paths) {
+		const files = this.getFiles();
+		const responses = [];
+		for (const path$4 of paths) {
+			const fileData = files[path$4];
+			if (!fileData) {
+				responses.push({
+					path: path$4,
+					content: null,
+					error: "file_not_found"
+				});
+				continue;
+			}
+			const contentStr = fileDataToString(fileData);
+			const content = new TextEncoder().encode(contentStr);
+			responses.push({
+				path: path$4,
+				content,
+				error: null
+			});
+		}
+		return responses;
+	}
+};
+
+//#endregion
+//#region src/middleware/fs.ts
+/**
+* Middleware for providing filesystem tools to an agent.
+*
+* Provides ls, read_file, write_file, edit_file, glob, and grep tools with support for:
+* - Pluggable backends (StateBackend, StoreBackend, FilesystemBackend, CompositeBackend)
+* - Tool result eviction for large outputs
+*/
+/**
+* Zod v3 schema for FileData (re-export from backends)
+*/
+const FileDataSchema = zod_v4.z.object({
+	content: zod_v4.z.array(zod_v4.z.string()),
+	created_at: zod_v4.z.string(),
+	modified_at: zod_v4.z.string()
+});
+/**
+* Merge file updates with support for deletions.
+*/
+function fileDataReducer(left, right) {
+	if (left === void 0) {
+		const result$1 = {};
+		for (const [key, value] of Object.entries(right)) if (value !== null) result$1[key] = value;
+		return result$1;
+	}
+	const result = { ...left };
+	for (const [key, value] of Object.entries(right)) if (value === null) delete result[key];
+	else result[key] = value;
+	return result;
+}
+/**
+* Shared filesystem state schema.
+* Defined at module level to ensure the same object identity is used across all agents,
+* preventing "Channel already exists with different type" errors when multiple agents
+* use createFilesystemMiddleware.
+*/
+const FilesystemStateSchema = zod_v4.z.object({ files: zod_v4.z.record(zod_v4.z.string(), FileDataSchema).default({}).meta({ reducer: {
+	fn: fileDataReducer,
+	schema: zod_v4.z.record(zod_v4.z.string(), FileDataSchema.nullable())
+} }) });
+/**
+* Resolve backend from factory or instance.
+*
+* @param backend - Backend instance or factory function
+* @param stateAndStore - State and store container for backend initialization
+*/
+function getBackend(backend, stateAndStore) {
+	if (typeof backend === "function") return backend(stateAndStore);
+	return backend;
+}
+const FILESYSTEM_SYSTEM_PROMPT = `You have access to a virtual filesystem. All file paths must start with a /.
+
+- 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 = "List files and directories in a directory";
+const READ_FILE_TOOL_DESCRIPTION = "Read the contents of a file";
+const WRITE_FILE_TOOL_DESCRIPTION = "Write content to a new file. Returns an error if the file already exists";
+const EDIT_FILE_TOOL_DESCRIPTION = "Edit a file by replacing a specific string with a new string";
+const GLOB_TOOL_DESCRIPTION = "Find files matching a glob pattern (e.g., '**/*.py' for all Python files)";
+const GREP_TOOL_DESCRIPTION = "Search for a regex pattern in files. Returns matching files and line numbers";
+const EXECUTE_TOOL_DESCRIPTION = `Executes a given command in the sandbox environment with proper handling and security measures.
+
+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
+
+2. Command Execution:
+   - Always quote file paths that contain spaces with double quotes
+   - Commands run in an isolated sandbox environment
+   - Returns combined stdout/stderr output with exit code
+
+Usage notes:
+  - The command parameter is required
+  - If the output is very large, it may be truncated
+  - IMPORTANT: Avoid using search commands like find and grep. Use the grep, glob tools instead.
+  - Avoid read tools like cat, head, tail - use read_file instead.
+  - Use '&&' to chain dependent commands, ';' for independent commands
+  - Try to use absolute paths to avoid cd`;
+const EXECUTION_SYSTEM_PROMPT = `## 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.
+
+- execute: run a shell command in the sandbox (returns output and exit code)`;
+/**
+* Create ls tool using backend.
+*/
+function createLsTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const path$4 = input.path || "/";
+		const infos = await resolvedBackend.lsInfo(path$4);
+		if (infos.length === 0) return `No files found in ${path$4}`;
+		const lines = [];
+		for (const info of infos) if (info.is_dir) lines.push(`${info.path} (directory)`);
+		else {
+			const size = info.size ? ` (${info.size} bytes)` : "";
+			lines.push(`${info.path}${size}`);
+		}
+		return lines.join("\n");
+	}, {
+		name: "ls",
+		description: customDescription || LS_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({ path: zod_v4.z.string().optional().default("/").describe("Directory path to list (default: /)") })
+	});
+}
+/**
+* Create read_file tool using backend.
+*/
+function createReadFileTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const { file_path, offset = 0, limit = 2e3 } = input;
+		return await resolvedBackend.read(file_path, offset, limit);
+	}, {
+		name: "read_file",
+		description: customDescription || READ_FILE_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({
+			file_path: zod_v4.z.string().describe("Absolute path to the file to read"),
+			offset: zod_v4.z.coerce.number().optional().default(0).describe("Line offset to start reading from (0-indexed)"),
+			limit: zod_v4.z.coerce.number().optional().default(2e3).describe("Maximum number of lines to read")
+		})
+	});
+}
+/**
+* Create write_file tool using backend.
+*/
+function createWriteFileTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const { file_path, content } = input;
+		const result = await resolvedBackend.write(file_path, content);
+		if (result.error) return result.error;
+		const message = new langchain.ToolMessage({
+			content: `Successfully wrote to '${file_path}'`,
+			tool_call_id: config.toolCall?.id,
+			name: "write_file",
+			metadata: result.metadata
+		});
+		if (result.filesUpdate) return new _langchain_langgraph.Command({ update: {
+			files: result.filesUpdate,
+			messages: [message]
+		} });
+		return message;
+	}, {
+		name: "write_file",
+		description: customDescription || WRITE_FILE_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({
+			file_path: zod_v4.z.string().describe("Absolute path to the file to write"),
+			content: zod_v4.z.string().describe("Content to write to the file")
+		})
+	});
+}
+/**
+* Create edit_file tool using backend.
+*/
+function createEditFileTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const { file_path, old_string, new_string, replace_all = false } = input;
+		const result = await resolvedBackend.edit(file_path, old_string, new_string, replace_all);
+		if (result.error) return result.error;
+		const message = new langchain.ToolMessage({
+			content: `Successfully replaced ${result.occurrences} occurrence(s) in '${file_path}'`,
+			tool_call_id: config.toolCall?.id,
+			name: "edit_file",
+			metadata: result.metadata
+		});
+		if (result.filesUpdate) return new _langchain_langgraph.Command({ update: {
+			files: result.filesUpdate,
+			messages: [message]
+		} });
+		return message;
+	}, {
+		name: "edit_file",
+		description: customDescription || EDIT_FILE_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({
+			file_path: zod_v4.z.string().describe("Absolute path to the file to edit"),
+			old_string: zod_v4.z.string().describe("String to be replaced (must match exactly)"),
+			new_string: zod_v4.z.string().describe("String to replace with"),
+			replace_all: zod_v4.z.boolean().optional().default(false).describe("Whether to replace all occurrences")
+		})
+	});
+}
+/**
+* Create glob tool using backend.
+*/
+function createGlobTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const { pattern, path: path$4 = "/" } = input;
+		const infos = await resolvedBackend.globInfo(pattern, path$4);
+		if (infos.length === 0) return `No files found matching pattern '${pattern}'`;
+		return infos.map((info) => info.path).join("\n");
+	}, {
+		name: "glob",
+		description: customDescription || GLOB_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({
+			pattern: zod_v4.z.string().describe("Glob pattern (e.g., '*.py', '**/*.ts')"),
+			path: zod_v4.z.string().optional().default("/").describe("Base path to search from (default: /)")
+		})
+	});
+}
+/**
+* Create grep tool using backend.
+*/
+function createGrepTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		const { pattern, path: path$4 = "/", glob = null } = input;
+		const result = await resolvedBackend.grepRaw(pattern, path$4, glob);
+		if (typeof result === "string") return result;
+		if (result.length === 0) return `No matches found for pattern '${pattern}'`;
+		const lines = [];
+		let currentFile = null;
+		for (const match of result) {
+			if (match.path !== currentFile) {
+				currentFile = match.path;
+				lines.push(`\n${currentFile}:`);
+			}
+			lines.push(`  ${match.line}: ${match.text}`);
+		}
+		return lines.join("\n");
+	}, {
+		name: "grep",
+		description: customDescription || GREP_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({
+			pattern: zod_v4.z.string().describe("Regex pattern to search for"),
+			path: zod_v4.z.string().optional().default("/").describe("Base path to search from (default: /)"),
+			glob: zod_v4.z.string().optional().nullable().describe("Optional glob pattern to filter files (e.g., '*.py')")
+		})
+	});
+}
+/**
+* Create execute tool using backend.
+*/
+function createExecuteTool(backend, options) {
+	const { customDescription } = options;
+	return (0, langchain.tool)(async (input, config) => {
+		const resolvedBackend = getBackend(backend, {
+			state: (0, _langchain_langgraph.getCurrentTaskInput)(config),
+			store: config.store
+		});
+		if (!isSandboxBackend(resolvedBackend)) return "Error: Execution not available. This agent's backend does not support command execution (SandboxBackendProtocol). To use the execute tool, provide a backend that implements SandboxBackendProtocol.";
+		const result = await resolvedBackend.execute(input.command);
+		const parts = [result.output];
+		if (result.exitCode !== null) {
+			const status = result.exitCode === 0 ? "succeeded" : "failed";
+			parts.push(`\n[Command ${status} with exit code ${result.exitCode}]`);
+		}
+		if (result.truncated) parts.push("\n[Output was truncated due to size limits]");
+		return parts.join("");
+	}, {
+		name: "execute",
+		description: customDescription || EXECUTE_TOOL_DESCRIPTION,
+		schema: zod_v4.z.object({ command: zod_v4.z.string().describe("The shell command to execute") })
+	});
+}
+/**
+* Create filesystem middleware with all tools and features.
+*/
+function createFilesystemMiddleware(options = {}) {
+	const { backend = (stateAndStore) => new StateBackend(stateAndStore), systemPrompt: customSystemPrompt = null, customToolDescriptions = null, toolTokenLimitBeforeEvict = 2e4 } = options;
+	const baseSystemPrompt = customSystemPrompt || FILESYSTEM_SYSTEM_PROMPT;
+	return (0, langchain.createMiddleware)({
+		name: "FilesystemMiddleware",
+		stateSchema: FilesystemStateSchema,
+		tools: [
+			createLsTool(backend, { customDescription: customToolDescriptions?.ls }),
+			createReadFileTool(backend, { customDescription: customToolDescriptions?.read_file }),
+			createWriteFileTool(backend, { customDescription: customToolDescriptions?.write_file }),
+			createEditFileTool(backend, { customDescription: customToolDescriptions?.edit_file }),
+			createGlobTool(backend, { customDescription: customToolDescriptions?.glob }),
+			createGrepTool(backend, { customDescription: customToolDescriptions?.grep }),
+			createExecuteTool(backend, { customDescription: customToolDescriptions?.execute })
+		],
+		wrapModelCall: async (request, handler) => {
+			const supportsExecution = isSandboxBackend(getBackend(backend, {
+				state: request.state || {},
+				store: request.config?.store
+			}));
+			let tools = request.tools;
+			if (!supportsExecution) tools = tools.filter((t) => t.name !== "execute");
+			let systemPrompt = baseSystemPrompt;
+			if (supportsExecution) systemPrompt = `${systemPrompt}\n\n${EXECUTION_SYSTEM_PROMPT}`;
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${systemPrompt}` : systemPrompt;
+			return handler({
+				...request,
+				tools,
+				systemPrompt: newSystemPrompt
+			});
+		},
+		wrapToolCall: toolTokenLimitBeforeEvict ? async (request, handler) => {
+			const result = await handler(request);
+			async function processToolMessage(msg) {
+				if (typeof msg.content === "string" && msg.content.length > toolTokenLimitBeforeEvict * 4) {
+					const resolvedBackend = getBackend(backend, {
+						state: request.state || {},
+						store: request.config?.store
+					});
+					const evictPath = `/large_tool_results/${sanitizeToolCallId(request.toolCall?.id || msg.tool_call_id)}`;
+					const writeResult = await resolvedBackend.write(evictPath, msg.content);
+					if (writeResult.error) return {
+						message: msg,
+						filesUpdate: null
+					};
+					return {
+						message: new langchain.ToolMessage({
+							content: `Tool result too large (${Math.round(msg.content.length / 4)} tokens). Content saved to ${evictPath}`,
+							tool_call_id: msg.tool_call_id,
+							name: msg.name
+						}),
+						filesUpdate: writeResult.filesUpdate
+					};
+				}
+				return {
+					message: msg,
+					filesUpdate: null
+				};
+			}
+			if (result instanceof langchain.ToolMessage) {
+				const processed = await processToolMessage(result);
+				if (processed.filesUpdate) return new _langchain_langgraph.Command({ update: {
+					files: processed.filesUpdate,
+					messages: [processed.message]
+				} });
+				return processed.message;
+			}
+			if ((0, _langchain_langgraph.isCommand)(result)) {
+				const update = result.update;
+				if (!update?.messages) return result;
+				let hasLargeResults = false;
+				const accumulatedFiles = { ...update.files || {} };
+				const processedMessages = [];
+				for (const msg of update.messages) if (msg instanceof langchain.ToolMessage) {
+					const processed = await processToolMessage(msg);
+					processedMessages.push(processed.message);
+					if (processed.filesUpdate) {
+						hasLargeResults = true;
+						Object.assign(accumulatedFiles, processed.filesUpdate);
+					}
+				} else processedMessages.push(msg);
+				if (hasLargeResults) return new _langchain_langgraph.Command({ update: {
+					...update,
+					messages: processedMessages,
+					files: accumulatedFiles
+				} });
+			}
+			return result;
+		} : void 0
+	});
+}
+
+//#endregion
+//#region src/middleware/subagents.ts
+const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
+const EXCLUDED_STATE_KEYS = [
+	"messages",
+	"todos",
+	"jumpTo",
+	"files"
+];
+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.
+
+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.
+
+## 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_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: "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: "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_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: "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();
+}
+const TASK_SYSTEM_PROMPT = `## \`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.
+
+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
+
+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.`;
+/**
+* Filter state to exclude certain keys when passing to subagents
+*/
+function filterStateForSubagent(state) {
+	const filtered = {};
+	for (const [key, value] of Object.entries(state)) if (!EXCLUDED_STATE_KEYS.includes(key)) filtered[key] = value;
+	return filtered;
+}
+/**
+* Create Command with filtered state update from subagent result
+*/
+function returnCommandWithStateUpdate(result, toolCallId) {
+	const stateUpdate = filterStateForSubagent(result);
+	const messages = result.messages;
+	const lastMessage = messages?.[messages.length - 1];
+	return new _langchain_langgraph.Command({ update: {
+		...stateUpdate,
+		messages: [new langchain.ToolMessage({
+			content: lastMessage?.content || "Task completed",
+			tool_call_id: toolCallId,
+			name: "task"
+		})]
+	} });
+}
+/**
+* Create subagent instances from specifications
+*/
+function getSubagents(options) {
+	const { defaultModel, defaultTools, defaultMiddleware, defaultInterruptOn, subagents, generalPurposeAgent } = options;
+	const defaultSubagentMiddleware = defaultMiddleware || [];
+	const agents = {};
+	const subagentDescriptions = [];
+	if (generalPurposeAgent) {
+		const generalPurposeMiddleware = [...defaultSubagentMiddleware];
+		if (defaultInterruptOn) generalPurposeMiddleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn: defaultInterruptOn }));
+		agents["general-purpose"] = (0, langchain.createAgent)({
+			model: defaultModel,
+			systemPrompt: DEFAULT_SUBAGENT_PROMPT,
+			tools: defaultTools,
+			middleware: generalPurposeMiddleware
+		});
+		subagentDescriptions.push(`- general-purpose: ${DEFAULT_GENERAL_PURPOSE_DESCRIPTION}`);
+	}
+	for (const agentParams of subagents) {
+		subagentDescriptions.push(`- ${agentParams.name}: ${agentParams.description}`);
+		if ("runnable" in agentParams) agents[agentParams.name] = agentParams.runnable;
+		else {
+			const middleware = agentParams.middleware ? [...defaultSubagentMiddleware, ...agentParams.middleware] : [...defaultSubagentMiddleware];
+			const interruptOn = agentParams.interruptOn || defaultInterruptOn;
+			if (interruptOn) middleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn }));
+			agents[agentParams.name] = (0, langchain.createAgent)({
+				model: agentParams.model ?? defaultModel,
+				systemPrompt: agentParams.systemPrompt,
+				tools: agentParams.tools ?? defaultTools,
+				middleware
+			});
+		}
+	}
+	return {
+		agents,
+		descriptions: subagentDescriptions
+	};
+}
+/**
+* Create the task tool for invoking subagents
+*/
+function createTaskTool(options) {
+	const { defaultModel, defaultTools, defaultMiddleware, defaultInterruptOn, subagents, generalPurposeAgent, taskDescription } = options;
+	const { agents: subagentGraphs, descriptions: subagentDescriptions } = getSubagents({
+		defaultModel,
+		defaultTools,
+		defaultMiddleware,
+		defaultInterruptOn,
+		subagents,
+		generalPurposeAgent
+	});
+	return (0, langchain.tool)(async (input, config) => {
+		const { description, subagent_type } = input;
+		if (!(subagent_type in subagentGraphs)) {
+			const allowedTypes = Object.keys(subagentGraphs).map((k) => `\`${k}\``).join(", ");
+			throw new Error(`Error: invoked agent of type ${subagent_type}, the only allowed types are ${allowedTypes}`);
+		}
+		const subagent = subagentGraphs[subagent_type];
+		const subagentState = filterStateForSubagent((0, _langchain_langgraph.getCurrentTaskInput)());
+		subagentState.messages = [new _langchain_core_messages.HumanMessage({ content: description })];
+		const result = await subagent.invoke(subagentState, config);
+		if (!config.toolCall?.id) throw new Error("Tool call ID is required for subagent invocation");
+		return returnCommandWithStateUpdate(result, config.toolCall.id);
+	}, {
+		name: "task",
+		description: taskDescription ? taskDescription : getTaskToolDescription(subagentDescriptions),
+		schema: zod_v3.z.object({
+			description: zod_v3.z.string().describe("The task to execute with the selected agent"),
+			subagent_type: zod_v3.z.string().describe(`Name of the agent to use. Available: ${Object.keys(subagentGraphs).join(", ")}`)
+		})
+	});
+}
+/**
+* Create subagent middleware with task tool
+*/
+function createSubAgentMiddleware(options) {
+	const { defaultModel, defaultTools = [], defaultMiddleware = null, defaultInterruptOn = null, subagents = [], systemPrompt = TASK_SYSTEM_PROMPT, generalPurposeAgent = true, taskDescription = null } = options;
+	return (0, langchain.createMiddleware)({
+		name: "subAgentMiddleware",
+		tools: [createTaskTool({
+			defaultModel,
+			defaultTools,
+			defaultMiddleware,
+			defaultInterruptOn,
+			subagents,
+			generalPurposeAgent,
+			taskDescription
+		})],
+		wrapModelCall: async (request, handler) => {
+			if (systemPrompt !== null) {
+				const currentPrompt = request.systemPrompt || "";
+				const newPrompt = currentPrompt ? `${currentPrompt}\n\n${systemPrompt}` : systemPrompt;
+				return handler({
+					...request,
+					systemPrompt: newPrompt
+				});
+			}
+			return handler(request);
+		}
+	});
+}
+
+//#endregion
+//#region src/middleware/patch_tool_calls.ts
+/**
+* Create middleware that patches dangling tool calls in the messages history.
+*
+* When an AI message contains tool_calls but subsequent messages don't include
+* the corresponding ToolMessage responses, this middleware adds synthetic
+* ToolMessages saying the tool call was cancelled.
+*
+* @returns AgentMiddleware that patches dangling tool calls
+*
+* @example
+* ```typescript
+* import { createAgent } from "langchain";
+* import { createPatchToolCallsMiddleware } from "./middleware/patch_tool_calls";
+*
+* const agent = createAgent({
+*   model: "claude-sonnet-4-5-20250929",
+*   middleware: [createPatchToolCallsMiddleware()],
+* });
+* ```
+*/
+function createPatchToolCallsMiddleware() {
+	return (0, langchain.createMiddleware)({
+		name: "patchToolCallsMiddleware",
+		beforeAgent: async (state) => {
+			const messages = state.messages;
+			if (!messages || messages.length === 0) return;
+			const patchedMessages = [];
+			for (let i = 0; i < messages.length; i++) {
+				const msg = messages[i];
+				patchedMessages.push(msg);
+				if (langchain.AIMessage.isInstance(msg) && msg.tool_calls != null) {
+					for (const toolCall of msg.tool_calls) if (!messages.slice(i).find((m) => langchain.ToolMessage.isInstance(m) && m.tool_call_id === toolCall.id)) {
+						const toolMsg = `Tool call ${toolCall.name} with id ${toolCall.id} was cancelled - another message came in before it could be completed.`;
+						patchedMessages.push(new langchain.ToolMessage({
+							content: toolMsg,
+							name: toolCall.name,
+							tool_call_id: toolCall.id
+						}));
+					}
+				}
+			}
+			return { messages: [new _langchain_core_messages.RemoveMessage({ id: _langchain_langgraph.REMOVE_ALL_MESSAGES }), ...patchedMessages] };
+		}
+	});
+}
+
+//#endregion
+//#region src/backends/store.ts
+/**
+* Backend that stores files in LangGraph's BaseStore (persistent).
+*
+* Uses LangGraph's Store for persistent, cross-conversation storage.
+* Files are organized via namespaces and persist across all threads.
+*
+* The namespace can include an optional assistant_id for multi-agent isolation.
+*/
+var StoreBackend = class {
+	stateAndStore;
+	constructor(stateAndStore) {
+		this.stateAndStore = stateAndStore;
+	}
+	/**
+	* Get the store instance.
+	*
+	* @returns BaseStore instance
+	* @throws Error if no store is available
+	*/
+	getStore() {
+		const store = this.stateAndStore.store;
+		if (!store) throw new Error("Store is required but not available in StateAndStore");
+		return store;
+	}
+	/**
+	* Get the namespace for store operations.
+	*
+	* If an assistant_id is available in stateAndStore, return
+	* [assistant_id, "filesystem"] to provide per-assistant isolation.
+	* Otherwise return ["filesystem"].
+	*/
+	getNamespace() {
+		const namespace = "filesystem";
+		const assistantId = this.stateAndStore.assistantId;
+		if (assistantId) return [assistantId, namespace];
+		return [namespace];
+	}
+	/**
+	* Convert a store Item to FileData format.
+	*
+	* @param storeItem - The store Item containing file data
+	* @returns FileData object
+	* @throws Error if required fields are missing or have incorrect types
+	*/
+	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(", ")}`);
+		return {
+			content: value.content,
+			created_at: value.created_at,
+			modified_at: value.modified_at
+		};
+	}
+	/**
+	* 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
+	*/
+	convertFileDataToStoreValue(fileData) {
+		return {
+			content: fileData.content,
+			created_at: fileData.created_at,
+			modified_at: fileData.modified_at
+		};
+	}
+	/**
+	* Search store with automatic pagination to retrieve all results.
+	*
+	* @param store - The store to search
+	* @param namespace - Hierarchical path prefix to search within
+	* @param options - Optional query, filter, and page_size
+	* @returns List of all items matching the search criteria
+	*/
+	async searchStorePaginated(store, namespace, options = {}) {
+		const { query, filter, pageSize = 100 } = options;
+		const allItems = [];
+		let offset = 0;
+		while (true) {
+			const pageItems = await store.search(namespace, {
+				query,
+				filter,
+				limit: pageSize,
+				offset
+			});
+			if (!pageItems || pageItems.length === 0) break;
+			allItems.push(...pageItems);
+			if (pageItems.length < pageSize) break;
+			offset += pageSize;
+		}
+		return allItems;
+	}
+	/**
+	* 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.
+	*          Directories have a trailing / in their path and is_dir=true.
+	*/
+	async lsInfo(path$4) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const items = await this.searchStorePaginated(store, namespace);
+		const infos = [];
+		const subdirs = /* @__PURE__ */ new Set();
+		const normalizedPath = path$4.endsWith("/") ? path$4 : path$4 + "/";
+		for (const item of items) {
+			const itemKey = String(item.key);
+			if (!itemKey.startsWith(normalizedPath)) continue;
+			const relative = itemKey.substring(normalizedPath.length);
+			if (relative.includes("/")) {
+				const subdirName = relative.split("/")[0];
+				subdirs.add(normalizedPath + subdirName + "/");
+				continue;
+			}
+			try {
+				const fd = this.convertStoreItemToFileData(item);
+				const size = fd.content.join("\n").length;
+				infos.push({
+					path: itemKey,
+					is_dir: false,
+					size,
+					modified_at: fd.modified_at
+				});
+			} catch {
+				continue;
+			}
+		}
+		for (const subdir of Array.from(subdirs).sort()) infos.push({
+			path: subdir,
+			is_dir: true,
+			size: 0,
+			modified_at: ""
+		});
+		infos.sort((a, b) => a.path.localeCompare(b.path));
+		return infos;
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @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
+	*/
+	async read(filePath, offset = 0, limit = 2e3) {
+		try {
+			return formatReadResponse(await this.readRaw(filePath), offset, limit);
+		} catch (e) {
+			return `Error: ${e.message}`;
+		}
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	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);
+	}
+	/**
+	* Create a new file with content.
+	* Returns WriteResult. External storage sets filesUpdate=null.
+	*/
+	async write(filePath, content) {
+		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 storeValue = this.convertFileDataToStoreValue(fileData);
+		await store.put(namespace, filePath, storeValue);
+		return {
+			path: filePath,
+			filesUpdate: null
+		};
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	* Returns EditResult. External storage sets filesUpdate=null.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const item = await store.get(namespace, filePath);
+		if (!item) return { error: `Error: File '${filePath}' not found` };
+		try {
+			const fileData = this.convertStoreItemToFileData(item);
+			const result = performStringReplacement(fileDataToString(fileData), oldString, newString, replaceAll);
+			if (typeof result === "string") return { error: result };
+			const [newContent, occurrences] = result;
+			const newFileData = updateFileData(fileData, newContent);
+			const storeValue = this.convertFileDataToStoreValue(newFileData);
+			await store.put(namespace, filePath, storeValue);
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences
+			};
+		} catch (e) {
+			return { error: `Error: ${e.message}` };
+		}
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grepRaw(pattern, path$4 = "/", glob = null) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const items = await this.searchStorePaginated(store, namespace);
+		const files = {};
+		for (const item of items) try {
+			files[item.key] = this.convertStoreItemToFileData(item);
+		} catch {
+			continue;
+		}
+		return grepMatchesFromFiles(files, pattern, path$4, glob);
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async globInfo(pattern, path$4 = "/") {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const items = await this.searchStorePaginated(store, namespace);
+		const files = {};
+		for (const item of items) try {
+			files[item.key] = this.convertStoreItemToFileData(item);
+		} catch {
+			continue;
+		}
+		const result = globSearchFiles(files, pattern, path$4);
+		if (result === "No files found") return [];
+		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;
+			infos.push({
+				path: p,
+				is_dir: false,
+				size,
+				modified_at: fd?.modified_at || ""
+			});
+		}
+		return infos;
+	}
+	/**
+	* Upload multiple files.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const responses = [];
+		for (const [path$4, content] of files) try {
+			const fileData = createFileData(new TextDecoder().decode(content));
+			const storeValue = this.convertFileDataToStoreValue(fileData);
+			await store.put(namespace, path$4, storeValue);
+			responses.push({
+				path: path$4,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$4,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Download multiple files.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const store = this.getStore();
+		const namespace = this.getNamespace();
+		const responses = [];
+		for (const path$4 of paths) try {
+			const item = await store.get(namespace, path$4);
+			if (!item) {
+				responses.push({
+					path: path$4,
+					content: null,
+					error: "file_not_found"
+				});
+				continue;
+			}
+			const contentStr = fileDataToString(this.convertStoreItemToFileData(item));
+			const content = new TextEncoder().encode(contentStr);
+			responses.push({
+				path: path$4,
+				content,
+				error: null
+			});
+		} catch {
+			responses.push({
+				path: path$4,
+				content: null,
+				error: "file_not_found"
+			});
+		}
+		return responses;
+	}
+};
+
+//#endregion
+//#region src/backends/filesystem.ts
+/**
+* FilesystemBackend: Read and write files directly from the filesystem.
+*
+* Security and search upgrades:
+* - Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
+* - Prevent symlink-following on file I/O using O_NOFOLLOW when available
+* - Ripgrep-powered grep with JSON parsing, plus regex fallback
+*   and optional glob include filtering, while preserving virtual path behavior
+*/
+const SUPPORTS_NOFOLLOW = node_fs.default.constants.O_NOFOLLOW !== void 0;
+/**
+* Backend that reads and writes files directly from the filesystem.
+*
+* Files are accessed using their actual filesystem paths. Relative paths are
+* resolved relative to the current working directory. Content is read/written
+* as plain text, and metadata (timestamps) are derived from filesystem stats.
+*/
+var FilesystemBackend = class {
+	cwd;
+	virtualMode;
+	maxFileSizeBytes;
+	constructor(options = {}) {
+		const { rootDir, virtualMode = false, maxFileSizeMb = 10 } = options;
+		this.cwd = rootDir ? node_path.default.resolve(rootDir) : process.cwd();
+		this.virtualMode = virtualMode;
+		this.maxFileSizeBytes = maxFileSizeMb * 1024 * 1024;
+	}
+	/**
+	* Resolve a file path with security checks.
+	*
+	* When virtualMode=true, treat incoming paths as virtual absolute paths under
+	* this.cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
+	* When virtualMode=false, preserve legacy behavior: absolute paths are allowed
+	* as-is; relative paths resolve under cwd.
+	*
+	* @param key - File path (absolute, relative, or virtual when virtualMode=true)
+	* @returns Resolved absolute path string
+	* @throws Error if path traversal detected or path outside root
+	*/
+	resolvePath(key) {
+		if (this.virtualMode) {
+			const vpath = key.startsWith("/") ? key : "/" + key;
+			if (vpath.includes("..") || vpath.startsWith("~")) throw new Error("Path traversal not allowed");
+			const full = node_path.default.resolve(this.cwd, vpath.substring(1));
+			const relative = node_path.default.relative(this.cwd, full);
+			if (relative.startsWith("..") || node_path.default.isAbsolute(relative)) throw new Error(`Path: ${full} outside root directory: ${this.cwd}`);
+			return full;
+		}
+		if (node_path.default.isAbsolute(key)) return key;
+		return node_path.default.resolve(this.cwd, key);
+	}
+	/**
+	* List files and directories in the specified directory (non-recursive).
+	*
+	* @param dirPath - Absolute directory path to list files from
+	* @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) {
+		try {
+			const resolvedPath = this.resolvePath(dirPath);
+			if (!(await node_fs_promises.default.stat(resolvedPath)).isDirectory()) return [];
+			const entries = await node_fs_promises.default.readdir(resolvedPath, { withFileTypes: true });
+			const results = [];
+			const cwdStr = this.cwd.endsWith(node_path.default.sep) ? this.cwd : this.cwd + node_path.default.sep;
+			for (const entry of entries) {
+				const fullPath = node_path.default.join(resolvedPath, entry.name);
+				try {
+					const entryStat = await node_fs_promises.default.stat(fullPath);
+					const isFile = entryStat.isFile();
+					const isDir = entryStat.isDirectory();
+					if (!this.virtualMode) {
+						if (isFile) results.push({
+							path: fullPath,
+							is_dir: false,
+							size: entryStat.size,
+							modified_at: entryStat.mtime.toISOString()
+						});
+						else if (isDir) results.push({
+							path: fullPath + node_path.default.sep,
+							is_dir: true,
+							size: 0,
+							modified_at: entryStat.mtime.toISOString()
+						});
+					} else {
+						let relativePath;
+						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(node_path.default.sep).join("/");
+						const virtPath = "/" + relativePath;
+						if (isFile) results.push({
+							path: virtPath,
+							is_dir: false,
+							size: entryStat.size,
+							modified_at: entryStat.mtime.toISOString()
+						});
+						else if (isDir) results.push({
+							path: virtPath + "/",
+							is_dir: true,
+							size: 0,
+							modified_at: entryStat.mtime.toISOString()
+						});
+					}
+				} catch {
+					continue;
+				}
+			}
+			results.sort((a, b) => a.path.localeCompare(b.path));
+			return results;
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @param filePath - Absolute or relative 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
+	*/
+	async read(filePath, offset = 0, limit = 2e3) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			let content;
+			if (SUPPORTS_NOFOLLOW) {
+				if (!(await node_fs_promises.default.stat(resolvedPath)).isFile()) return `Error: File '${filePath}' not found`;
+				const fd = await node_fs_promises.default.open(resolvedPath, node_fs.default.constants.O_RDONLY | node_fs.default.constants.O_NOFOLLOW);
+				try {
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await node_fs_promises.default.lstat(resolvedPath);
+				if (stat.isSymbolicLink()) return `Error: Symlinks are not allowed: ${filePath}`;
+				if (!stat.isFile()) return `Error: File '${filePath}' not found`;
+				content = await node_fs_promises.default.readFile(resolvedPath, "utf-8");
+			}
+			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);
+		} catch (e) {
+			return `Error reading file '${filePath}': ${e.message}`;
+		}
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const resolvedPath = this.resolvePath(filePath);
+		let content;
+		let stat;
+		if (SUPPORTS_NOFOLLOW) {
+			stat = await node_fs_promises.default.stat(resolvedPath);
+			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			const fd = await node_fs_promises.default.open(resolvedPath, node_fs.default.constants.O_RDONLY | node_fs.default.constants.O_NOFOLLOW);
+			try {
+				content = await fd.readFile({ encoding: "utf-8" });
+			} finally {
+				await fd.close();
+			}
+		} else {
+			stat = await node_fs_promises.default.lstat(resolvedPath);
+			if (stat.isSymbolicLink()) throw new Error(`Symlinks are not allowed: ${filePath}`);
+			if (!stat.isFile()) throw new Error(`File '${filePath}' not found`);
+			content = await node_fs_promises.default.readFile(resolvedPath, "utf-8");
+		}
+		return {
+			content: content.split("\n"),
+			created_at: stat.ctime.toISOString(),
+			modified_at: stat.mtime.toISOString()
+		};
+	}
+	/**
+	* Create a new file with content.
+	* Returns WriteResult. External storage sets filesUpdate=null.
+	*/
+	async write(filePath, content) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			try {
+				if ((await node_fs_promises.default.lstat(resolvedPath)).isSymbolicLink()) return { error: `Cannot write to ${filePath} because it is a symlink. Symlinks are not allowed.` };
+				return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
+			} catch {}
+			await node_fs_promises.default.mkdir(node_path.default.dirname(resolvedPath), { recursive: true });
+			if (SUPPORTS_NOFOLLOW) {
+				const flags = node_fs.default.constants.O_WRONLY | node_fs.default.constants.O_CREAT | node_fs.default.constants.O_TRUNC | node_fs.default.constants.O_NOFOLLOW;
+				const fd = await node_fs_promises.default.open(resolvedPath, flags, 420);
+				try {
+					await fd.writeFile(content, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else await node_fs_promises.default.writeFile(resolvedPath, content, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null
+			};
+		} catch (e) {
+			return { error: `Error writing file '${filePath}': ${e.message}` };
+		}
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	* Returns EditResult. External storage sets filesUpdate=null.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		try {
+			const resolvedPath = this.resolvePath(filePath);
+			let content;
+			if (SUPPORTS_NOFOLLOW) {
+				if (!(await node_fs_promises.default.stat(resolvedPath)).isFile()) return { error: `Error: File '${filePath}' not found` };
+				const fd = await node_fs_promises.default.open(resolvedPath, node_fs.default.constants.O_RDONLY | node_fs.default.constants.O_NOFOLLOW);
+				try {
+					content = await fd.readFile({ encoding: "utf-8" });
+				} finally {
+					await fd.close();
+				}
+			} else {
+				const stat = await node_fs_promises.default.lstat(resolvedPath);
+				if (stat.isSymbolicLink()) return { error: `Error: Symlinks are not allowed: ${filePath}` };
+				if (!stat.isFile()) return { error: `Error: File '${filePath}' not found` };
+				content = await node_fs_promises.default.readFile(resolvedPath, "utf-8");
+			}
+			const result = performStringReplacement(content, oldString, newString, replaceAll);
+			if (typeof result === "string") return { error: result };
+			const [newContent, occurrences] = result;
+			if (SUPPORTS_NOFOLLOW) {
+				const flags = node_fs.default.constants.O_WRONLY | node_fs.default.constants.O_TRUNC | node_fs.default.constants.O_NOFOLLOW;
+				const fd = await node_fs_promises.default.open(resolvedPath, flags);
+				try {
+					await fd.writeFile(newContent, "utf-8");
+				} finally {
+					await fd.close();
+				}
+			} else await node_fs_promises.default.writeFile(resolvedPath, newContent, "utf-8");
+			return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences
+			};
+		} catch (e) {
+			return { error: `Error editing file '${filePath}': ${e.message}` };
+		}
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grepRaw(pattern, dirPath = "/", glob = null) {
+		try {
+			new RegExp(pattern);
+		} catch (e) {
+			return `Invalid regex pattern: ${e.message}`;
+		}
+		let baseFull;
+		try {
+			baseFull = this.resolvePath(dirPath || ".");
+		} catch {
+			return [];
+		}
+		try {
+			await node_fs_promises.default.stat(baseFull);
+		} catch {
+			return [];
+		}
+		let results = await this.ripgrepSearch(pattern, baseFull, glob);
+		if (results === null) results = await this.pythonSearch(pattern, baseFull, glob);
+		const matches = [];
+		for (const [fpath, items] of Object.entries(results)) for (const [lineNum, lineText] of items) matches.push({
+			path: fpath,
+			line: lineNum,
+			text: lineText
+		});
+		return matches;
+	}
+	/**
+	* Try to use ripgrep for fast searching.
+	* Returns null if ripgrep is not available or fails.
+	*/
+	async ripgrepSearch(pattern, baseFull, includeGlob) {
+		return new Promise((resolve) => {
+			const args = ["--json"];
+			if (includeGlob) args.push("--glob", includeGlob);
+			args.push("--", pattern, baseFull);
+			const proc = (0, node_child_process.spawn)("rg", args, { timeout: 3e4 });
+			const results = {};
+			let output = "";
+			proc.stdout.on("data", (data) => {
+				output += data.toString();
+			});
+			proc.on("close", (code) => {
+				if (code !== 0 && code !== 1) {
+					resolve(null);
+					return;
+				}
+				for (const line of output.split("\n")) {
+					if (!line.trim()) continue;
+					try {
+						const data = JSON.parse(line);
+						if (data.type !== "match") continue;
+						const pdata = data.data || {};
+						const ftext = pdata.path?.text;
+						if (!ftext) continue;
+						let virtPath;
+						if (this.virtualMode) try {
+							const resolved = node_path.default.resolve(ftext);
+							const relative = node_path.default.relative(this.cwd, resolved);
+							if (relative.startsWith("..")) continue;
+							virtPath = "/" + relative.split(node_path.default.sep).join("/");
+						} catch {
+							continue;
+						}
+						else virtPath = ftext;
+						const ln = pdata.line_number;
+						const lt = pdata.lines?.text?.replace(/\n$/, "") || "";
+						if (ln === void 0) continue;
+						if (!results[virtPath]) results[virtPath] = [];
+						results[virtPath].push([ln, lt]);
+					} catch {
+						continue;
+					}
+				}
+				resolve(results);
+			});
+			proc.on("error", () => {
+				resolve(null);
+			});
+		});
+	}
+	/**
+	* Fallback regex search implementation.
+	*/
+	async pythonSearch(pattern, baseFull, includeGlob) {
+		let regex;
+		try {
+			regex = new RegExp(pattern);
+		} catch {
+			return {};
+		}
+		const results = {};
+		const files = await (0, fast_glob.default)("**/*", {
+			cwd: (await node_fs_promises.default.stat(baseFull)).isDirectory() ? baseFull : node_path.default.dirname(baseFull),
+			absolute: true,
+			onlyFiles: true,
+			dot: true
+		});
+		for (const fp of files) try {
+			if (includeGlob && !micromatch.default.isMatch(node_path.default.basename(fp), includeGlob)) continue;
+			if ((await node_fs_promises.default.stat(fp)).size > this.maxFileSizeBytes) continue;
+			const lines = (await node_fs_promises.default.readFile(fp, "utf-8")).split("\n");
+			for (let i = 0; i < lines.length; i++) {
+				const line = lines[i];
+				if (regex.test(line)) {
+					let virtPath;
+					if (this.virtualMode) try {
+						const relative = node_path.default.relative(this.cwd, fp);
+						if (relative.startsWith("..")) continue;
+						virtPath = "/" + relative.split(node_path.default.sep).join("/");
+					} catch {
+						continue;
+					}
+					else virtPath = fp;
+					if (!results[virtPath]) results[virtPath] = [];
+					results[virtPath].push([i + 1, line]);
+				}
+			}
+		} catch {
+			continue;
+		}
+		return results;
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async globInfo(pattern, searchPath = "/") {
+		if (pattern.startsWith("/")) pattern = pattern.substring(1);
+		const resolvedSearchPath = searchPath === "/" ? this.cwd : this.resolvePath(searchPath);
+		try {
+			if (!(await node_fs_promises.default.stat(resolvedSearchPath)).isDirectory()) return [];
+		} catch {
+			return [];
+		}
+		const results = [];
+		try {
+			const matches = await (0, fast_glob.default)(pattern, {
+				cwd: resolvedSearchPath,
+				absolute: true,
+				onlyFiles: true,
+				dot: true
+			});
+			for (const matchedPath of matches) try {
+				const stat = await node_fs_promises.default.stat(matchedPath);
+				if (!stat.isFile()) continue;
+				const normalizedPath = matchedPath.split("/").join(node_path.default.sep);
+				if (!this.virtualMode) results.push({
+					path: normalizedPath,
+					is_dir: false,
+					size: stat.size,
+					modified_at: stat.mtime.toISOString()
+				});
+				else {
+					const cwdStr = this.cwd.endsWith(node_path.default.sep) ? this.cwd : this.cwd + node_path.default.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(node_path.default.sep).join("/");
+					const virt = "/" + relativePath;
+					results.push({
+						path: virt,
+						is_dir: false,
+						size: stat.size,
+						modified_at: stat.mtime.toISOString()
+					});
+				}
+			} catch {
+				continue;
+			}
+		} catch {}
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return results;
+	}
+	/**
+	* Upload multiple files to the filesystem.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const responses = [];
+		for (const [filePath, content] of files) try {
+			const resolvedPath = this.resolvePath(filePath);
+			await node_fs_promises.default.mkdir(node_path.default.dirname(resolvedPath), { recursive: true });
+			await node_fs_promises.default.writeFile(resolvedPath, content);
+			responses.push({
+				path: filePath,
+				error: null
+			});
+		} catch (e) {
+			if (e.code === "ENOENT") responses.push({
+				path: filePath,
+				error: "file_not_found"
+			});
+			else if (e.code === "EACCES") responses.push({
+				path: filePath,
+				error: "permission_denied"
+			});
+			else if (e.code === "EISDIR") responses.push({
+				path: filePath,
+				error: "is_directory"
+			});
+			else responses.push({
+				path: filePath,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+	/**
+	* Download multiple files from the filesystem.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const responses = [];
+		for (const filePath of paths) try {
+			const resolvedPath = this.resolvePath(filePath);
+			const content = await node_fs_promises.default.readFile(resolvedPath);
+			responses.push({
+				path: filePath,
+				content,
+				error: null
+			});
+		} catch (e) {
+			if (e.code === "ENOENT") responses.push({
+				path: filePath,
+				content: null,
+				error: "file_not_found"
+			});
+			else if (e.code === "EACCES") responses.push({
+				path: filePath,
+				content: null,
+				error: "permission_denied"
+			});
+			else if (e.code === "EISDIR") responses.push({
+				path: filePath,
+				content: null,
+				error: "is_directory"
+			});
+			else responses.push({
+				path: filePath,
+				content: null,
+				error: "invalid_path"
+			});
+		}
+		return responses;
+	}
+};
+
+//#endregion
+//#region src/backends/composite.ts
+/**
+* Backend that routes file operations to different backends based on path prefix.
+*
+* This enables hybrid storage strategies like:
+* - `/memories/` → StoreBackend (persistent, cross-thread)
+* - Everything else → StateBackend (ephemeral, per-thread)
+*
+* The CompositeBackend handles path prefix stripping/re-adding transparently.
+*/
+var CompositeBackend = class {
+	default;
+	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);
+	}
+	/**
+	* Determine which backend handles this key and strip prefix.
+	*
+	* @param key - Original file path
+	* @returns Tuple of [backend, stripped_key] where stripped_key has the route
+	*          prefix removed (but keeps leading slash).
+	*/
+	getBackendAndKey(key) {
+		for (const [prefix, backend] of this.sortedRoutes) if (key.startsWith(prefix)) {
+			const suffix = key.substring(prefix.length);
+			return [backend, suffix ? "/" + suffix : "/"];
+		}
+		return [this.default, key];
+	}
+	/**
+	* 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.
+	*/
+	async lsInfo(path$4) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const suffix = path$4.substring(routePrefix.length);
+			const searchPath = suffix ? "/" + suffix : "/";
+			const infos = await backend.lsInfo(searchPath);
+			const prefixed = [];
+			for (const fi of infos) prefixed.push({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			});
+			return prefixed;
+		}
+		if (path$4 === "/") {
+			const results = [];
+			const defaultInfos = await this.default.lsInfo(path$4);
+			results.push(...defaultInfos);
+			for (const [routePrefix] of this.sortedRoutes) results.push({
+				path: routePrefix,
+				is_dir: true,
+				size: 0,
+				modified_at: ""
+			});
+			results.sort((a, b) => a.path.localeCompare(b.path));
+			return results;
+		}
+		return await this.default.lsInfo(path$4);
+	}
+	/**
+	* Read file content, routing to appropriate backend.
+	*
+	* @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
+	*/
+	async read(filePath, offset = 0, limit = 2e3) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.read(strippedKey, offset, limit);
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.readRaw(strippedKey);
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grepRaw(pattern, path$4 = "/", glob = null) {
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path$4.substring(routePrefix.length - 1);
+			const raw = await backend.grepRaw(pattern, searchPath || "/", glob);
+			if (typeof raw === "string") return raw;
+			return raw.map((m) => ({
+				...m,
+				path: routePrefix.slice(0, -1) + m.path
+			}));
+		}
+		const allMatches = [];
+		const rawDefault = await this.default.grepRaw(pattern, path$4, glob);
+		if (typeof rawDefault === "string") return rawDefault;
+		allMatches.push(...rawDefault);
+		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) => ({
+				...m,
+				path: routePrefix.slice(0, -1) + m.path
+			})));
+		}
+		return allMatches;
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async globInfo(pattern, path$4 = "/") {
+		const results = [];
+		for (const [routePrefix, backend] of this.sortedRoutes) if (path$4.startsWith(routePrefix.replace(/\/$/, ""))) {
+			const searchPath = path$4.substring(routePrefix.length - 1);
+			return (await backend.globInfo(pattern, searchPath || "/")).map((fi) => ({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			}));
+		}
+		const defaultInfos = await this.default.globInfo(pattern, path$4);
+		results.push(...defaultInfos);
+		for (const [routePrefix, backend] of Object.entries(this.routes)) {
+			const infos = await backend.globInfo(pattern, "/");
+			results.push(...infos.map((fi) => ({
+				...fi,
+				path: routePrefix.slice(0, -1) + fi.path
+			})));
+		}
+		results.sort((a, b) => a.path.localeCompare(b.path));
+		return results;
+	}
+	/**
+	* Create a new file, routing to appropriate backend.
+	*
+	* @param filePath - Absolute file path
+	* @param content - File content as string
+	* @returns WriteResult with path or error
+	*/
+	async write(filePath, content) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.write(strippedKey, content);
+	}
+	/**
+	* Edit a file, routing to appropriate backend.
+	*
+	* @param filePath - Absolute file path
+	* @param oldString - String to find and replace
+	* @param newString - Replacement string
+	* @param replaceAll - If true, replace all occurrences
+	* @returns EditResult with path, occurrences, or error
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const [backend, strippedKey] = this.getBackendAndKey(filePath);
+		return await backend.edit(strippedKey, oldString, newString, replaceAll);
+	}
+	/**
+	* Execute a command via the default backend.
+	* Execution is not path-specific, so it always delegates to the default backend.
+	*
+	* @param command - Full shell command string to execute
+	* @returns ExecuteResponse with combined output, exit code, and truncation flag
+	* @throws Error if the default backend doesn't support command execution
+	*/
+	execute(command) {
+		if (!isSandboxBackend(this.default)) throw new Error("Default backend doesn't support command execution (SandboxBackendProtocol). To enable execution, provide a default backend that implements SandboxBackendProtocol.");
+		return Promise.resolve(this.default.execute(command));
+	}
+	/**
+	* Upload multiple files, batching by backend for efficiency.
+	*
+	* @param files - List of [path, content] tuples to upload
+	* @returns List of FileUploadResponse objects, one per input file
+	*/
+	async uploadFiles(files) {
+		const results = new Array(files.length).fill(null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < files.length; idx++) {
+			const [path$4, content] = files[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path$4);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath,
+				content
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			const batchFiles = batch.map((b) => [b.path, b.content]);
+			const batchResponses = await backend.uploadFiles(batchFiles);
+			for (let i = 0; i < batch.length; i++) {
+				const originalIdx = batch[i].idx;
+				results[originalIdx] = {
+					path: files[originalIdx][0],
+					error: batchResponses[i]?.error ?? null
+				};
+			}
+		}
+		return results;
+	}
+	/**
+	* Download multiple files, batching by backend for efficiency.
+	*
+	* @param paths - List of file paths to download
+	* @returns List of FileDownloadResponse objects, one per input path
+	*/
+	async downloadFiles(paths) {
+		const results = new Array(paths.length).fill(null);
+		const batchesByBackend = /* @__PURE__ */ new Map();
+		for (let idx = 0; idx < paths.length; idx++) {
+			const path$4 = paths[idx];
+			const [backend, strippedPath] = this.getBackendAndKey(path$4);
+			if (!batchesByBackend.has(backend)) batchesByBackend.set(backend, []);
+			batchesByBackend.get(backend).push({
+				idx,
+				path: strippedPath
+			});
+		}
+		for (const [backend, batch] of batchesByBackend) {
+			const batchPaths = batch.map((b) => b.path);
+			const batchResponses = await backend.downloadFiles(batchPaths);
+			for (let i = 0; i < batch.length; i++) {
+				const originalIdx = batch[i].idx;
+				results[originalIdx] = {
+					path: paths[originalIdx],
+					content: batchResponses[i]?.content ?? null,
+					error: batchResponses[i]?.error ?? null
+				};
+			}
+		}
+		return results;
+	}
+};
+
+//#endregion
+//#region src/backends/sandbox.ts
+/**
+* Node.js command template for glob operations.
+* Uses web-standard atob() for base64 decoding.
+*/
+function buildGlobCommand(searchPath, pattern) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const searchPath = atob('${btoa(searchPath)}');
+const pattern = atob('${btoa(pattern)}');
+
+function globMatch(relativePath, pattern) {
+  const regexPattern = pattern
+    .replace(/\\*\\*/g, '<<<GLOBSTAR>>>')
+    .replace(/\\*/g, '[^/]*')
+    .replace(/\\?/g, '.')
+    .replace(/<<<GLOBSTAR>>>/g, '.*');
+  return new RegExp('^' + regexPattern + '$').test(relativePath);
+}
+
+function walkDir(dir, baseDir, results) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(baseDir, fullPath);
+      if (entry.isDirectory()) {
+        walkDir(fullPath, baseDir, results);
+      } else if (globMatch(relativePath, pattern)) {
+        const stat = fs.statSync(fullPath);
+        console.log(JSON.stringify({
+          path: relativePath,
+          size: stat.size,
+          mtime: stat.mtimeMs,
+          isDir: false
+        }));
+      }
+    }
+  } catch (e) {
+    // Silent failure for non-existent paths
+  }
+}
+
+try {
+  process.chdir(searchPath);
+  walkDir('.', '.', []);
+} catch (e) {
+  // Silent failure for non-existent paths
+}
+"`;
+}
+/**
+* Node.js command template for listing directory contents.
+*/
+function buildLsCommand(dirPath) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const dirPath = atob('${btoa(dirPath)}');
+
+try {
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+    const stat = fs.statSync(fullPath);
+    console.log(JSON.stringify({
+      path: entry.isDirectory() ? fullPath + '/' : fullPath,
+      size: stat.size,
+      mtime: stat.mtimeMs,
+      isDir: entry.isDirectory()
+    }));
+  }
+} catch (e) {
+  console.error('Error: ' + e.message);
+  process.exit(1);
+}
+"`;
+}
+/**
+* Node.js command template for reading files.
+*/
+function buildReadCommand(filePath, offset, limit) {
+	return `node -e "
+const fs = require('fs');
+
+const filePath = atob('${btoa(filePath)}');
+const offset = ${Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0};
+const limit = ${Number.isFinite(limit) && limit > 0 && limit < Number.MAX_SAFE_INTEGER ? Math.floor(limit) : 0};
+
+if (!fs.existsSync(filePath)) {
+  console.log('Error: File not found');
+  process.exit(1);
+}
+
+const stat = fs.statSync(filePath);
+if (stat.size === 0) {
+  console.log('System reminder: File exists but has empty contents');
+  process.exit(0);
+}
+
+const content = fs.readFileSync(filePath, 'utf-8');
+const lines = content.split('\\n');
+const selected = lines.slice(offset, offset + limit);
+
+for (let i = 0; i < selected.length; i++) {
+  const lineNum = offset + i + 1;
+  console.log(String(lineNum).padStart(6) + '\\t' + selected[i]);
+}
+"`;
+}
+/**
+* Node.js command template for writing files.
+*/
+function buildWriteCommand(filePath, content) {
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const filePath = atob('${btoa(filePath)}');
+const content = atob('${btoa(content)}');
+
+if (fs.existsSync(filePath)) {
+  console.error('Error: File already exists');
+  process.exit(1);
+}
+
+const parentDir = path.dirname(filePath) || '.';
+fs.mkdirSync(parentDir, { recursive: true });
+
+fs.writeFileSync(filePath, content, 'utf-8');
+console.log('OK');
+"`;
+}
+/**
+* Node.js command template for editing files.
+*/
+function buildEditCommand(filePath, oldStr, newStr, replaceAll) {
+	return `node -e "
+const fs = require('fs');
+
+const filePath = atob('${btoa(filePath)}');
+const oldStr = atob('${btoa(oldStr)}');
+const newStr = atob('${btoa(newStr)}');
+const replaceAll = ${Boolean(replaceAll)};
+
+let text;
+try {
+  text = fs.readFileSync(filePath, 'utf-8');
+} catch (e) {
+  process.exit(3);
+}
+
+const count = text.split(oldStr).length - 1;
+
+if (count === 0) {
+  process.exit(1);
+}
+if (count > 1 && !replaceAll) {
+  process.exit(2);
+}
+
+const result = text.split(oldStr).join(newStr);
+fs.writeFileSync(filePath, result, 'utf-8');
+console.log(count);
+"`;
+}
+/**
+* Node.js command template for grep operations.
+*/
+function buildGrepCommand(pattern, searchPath, globPattern) {
+	const patternB64 = btoa(pattern);
+	const pathB64 = btoa(searchPath);
+	const globB64 = globPattern ? btoa(globPattern) : "";
+	return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const pattern = atob('${patternB64}');
+const searchPath = atob('${pathB64}');
+const globPattern = ${globPattern ? `atob('${globB64}')` : "null"};
+
+let regex;
+try {
+  regex = new RegExp(pattern);
+} catch (e) {
+  console.error('Invalid regex: ' + e.message);
+  process.exit(1);
+}
+
+function globMatch(filePath, pattern) {
+  if (!pattern) return true;
+  const regexPattern = pattern
+    .replace(/\\*\\*/g, '<<<GLOBSTAR>>>')
+    .replace(/\\*/g, '[^/]*')
+    .replace(/\\?/g, '.')
+    .replace(/<<<GLOBSTAR>>>/g, '.*');
+  return new RegExp('^' + regexPattern + '$').test(filePath);
+}
+
+function walkDir(dir, results) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkDir(fullPath, results);
+      } else {
+        const relativePath = path.relative(searchPath, fullPath);
+        if (globMatch(relativePath, globPattern)) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const lines = content.split('\\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (regex.test(lines[i])) {
+                console.log(JSON.stringify({
+                  path: fullPath,
+                  line: i + 1,
+                  text: lines[i]
+                }));
+              }
+            }
+          } catch (e) {
+            // Skip unreadable files
+          }
+        }
+      }
+    }
+  } catch (e) {
+    // Skip unreadable directories
+  }
+}
+
+try {
+  walkDir(searchPath, []);
+} catch (e) {
+  // Silent failure
+}
+"`;
+}
+/**
+* Base sandbox implementation with execute() as the only abstract method.
+*
+* This class provides default implementations for all SandboxBackendProtocol
+* methods using shell commands executed via execute(). Concrete implementations
+* only need to implement the execute() method.
+*
+* Requires Node.js 20+ on the sandbox host.
+*/
+var BaseSandbox = 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.
+	*/
+	async lsInfo(path$4) {
+		const command = buildLsCommand(path$4);
+		const result = await this.execute(command);
+		if (result.exitCode !== 0) return [];
+		const infos = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			infos.push({
+				path: parsed.path,
+				is_dir: parsed.isDir,
+				size: parsed.size,
+				modified_at: parsed.mtime ? new Date(parsed.mtime).toISOString() : void 0
+			});
+		} catch {}
+		return infos;
+	}
+	/**
+	* Read file content with line numbers.
+	*
+	* @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
+	*/
+	async read(filePath, offset = 0, limit = 2e3) {
+		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;
+	}
+	/**
+	* Read file content as raw FileData.
+	*
+	* @param filePath - Absolute file path
+	* @returns Raw file content as FileData
+	*/
+	async readRaw(filePath) {
+		const command = buildReadCommand(filePath, 0, Number.MAX_SAFE_INTEGER);
+		const result = await this.execute(command);
+		if (result.exitCode !== 0) throw new Error(`File '${filePath}' not found`);
+		const lines = [];
+		for (const line of result.output.split("\n")) {
+			const tabIndex = line.indexOf("	");
+			if (tabIndex !== -1) lines.push(line.substring(tabIndex + 1));
+		}
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		return {
+			content: lines,
+			created_at: now,
+			modified_at: now
+		};
+	}
+	/**
+	* Structured search results or error string for invalid input.
+	*/
+	async grepRaw(pattern, path$4 = "/", glob = null) {
+		const command = buildGrepCommand(pattern, path$4, glob);
+		const result = await this.execute(command);
+		if (result.exitCode === 1) {
+			if (result.output.includes("Invalid regex:")) return result.output.trim();
+		}
+		const matches = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			matches.push({
+				path: parsed.path,
+				line: parsed.line,
+				text: parsed.text
+			});
+		} catch {}
+		return matches;
+	}
+	/**
+	* Structured glob matching returning FileInfo objects.
+	*/
+	async globInfo(pattern, path$4 = "/") {
+		const command = buildGlobCommand(path$4, pattern);
+		const result = await this.execute(command);
+		const infos = [];
+		const lines = result.output.trim().split("\n").filter(Boolean);
+		for (const line of lines) try {
+			const parsed = JSON.parse(line);
+			infos.push({
+				path: parsed.path,
+				is_dir: parsed.isDir,
+				size: parsed.size,
+				modified_at: parsed.mtime ? new Date(parsed.mtime).toISOString() : void 0
+			});
+		} catch {}
+		return infos;
+	}
+	/**
+	* Create a new file with content.
+	*/
+	async write(filePath, content) {
+		const command = buildWriteCommand(filePath, content);
+		if ((await this.execute(command)).exitCode !== 0) return { error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.` };
+		return {
+			path: filePath,
+			filesUpdate: null
+		};
+	}
+	/**
+	* Edit a file by replacing string occurrences.
+	*/
+	async edit(filePath, oldString, newString, replaceAll = false) {
+		const command = buildEditCommand(filePath, oldString, newString, replaceAll);
+		const result = await this.execute(command);
+		switch (result.exitCode) {
+			case 0: return {
+				path: filePath,
+				filesUpdate: null,
+				occurrences: parseInt(result.output.trim(), 10) || 1
+			};
+			case 1: return { error: `String not found in file '${filePath}'` };
+			case 2: return { error: `Multiple occurrences found in '${filePath}'. Use replaceAll=true to replace all.` };
+			case 3: return { error: `Error: File '${filePath}' not found` };
+			default: return { error: `Unknown error editing file '${filePath}'` };
+		}
+	}
+};
+
+//#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.`;
+/**
+* Create a Deep Agent with middleware-based architecture.
+*
+* Matches Python's create_deep_agent function, using middleware for all features:
+* - Todo management (todoListMiddleware)
+* - Filesystem tools (createFilesystemMiddleware)
+* - Subagent delegation (createSubAgentMiddleware)
+* - Conversation summarization (summarizationMiddleware)
+* - Prompt caching (anthropicPromptCachingMiddleware)
+* - Tool call patching (createPatchToolCallsMiddleware)
+* - Human-in-the-loop (humanInTheLoopMiddleware) - optional
+*
+* @param params Configuration parameters for the agent
+* @returns ReactAgent instance ready for invocation
+*/
+function createDeepAgent(params = {}) {
+	const { model = "claude-sonnet-4-5-20250929", tools = [], systemPrompt, middleware: customMiddleware = [], subagents = [], responseFormat, contextSchema, checkpointer, store, backend, interruptOn, name } = params;
+	const finalSystemPrompt = systemPrompt ? `${systemPrompt}\n\n${BASE_PROMPT}` : BASE_PROMPT;
+	const filesystemBackend = backend ? backend : (config) => new StateBackend(config);
+	const middleware = [
+		(0, langchain.todoListMiddleware)(),
+		createFilesystemMiddleware({ backend: filesystemBackend }),
+		createSubAgentMiddleware({
+			defaultModel: model,
+			defaultTools: tools,
+			defaultMiddleware: [
+				(0, langchain.todoListMiddleware)(),
+				createFilesystemMiddleware({ backend: filesystemBackend }),
+				(0, langchain.summarizationMiddleware)({
+					model,
+					trigger: { tokens: 17e4 },
+					keep: { messages: 6 }
+				}),
+				(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+				createPatchToolCallsMiddleware()
+			],
+			defaultInterruptOn: interruptOn,
+			subagents,
+			generalPurposeAgent: true
+		}),
+		(0, langchain.summarizationMiddleware)({
+			model,
+			trigger: { tokens: 17e4 },
+			keep: { messages: 6 }
+		}),
+		(0, langchain.anthropicPromptCachingMiddleware)({ unsupportedModelBehavior: "ignore" }),
+		createPatchToolCallsMiddleware()
+	];
+	if (interruptOn) middleware.push((0, langchain.humanInTheLoopMiddleware)({ interruptOn }));
+	middleware.push(...customMiddleware);
+	return (0, langchain.createAgent)({
+		model,
+		systemPrompt: finalSystemPrompt,
+		tools,
+		middleware,
+		responseFormat,
+		contextSchema,
+		checkpointer,
+		store,
+		name
+	});
+}
+
+//#endregion
+//#region src/config.ts
+/**
+* Configuration and settings for deepagents.
+*
+* Provides project detection, path management, and environment configuration
+* for skills and agent memory middleware.
+*/
+/**
+* Find the project root by looking for .git directory.
+*
+* Walks up the directory tree from startPath (or cwd) looking for a .git
+* directory, which indicates the project root.
+*
+* @param startPath - Directory to start searching from. Defaults to current working directory.
+* @returns Path to the project root if found, null otherwise.
+*/
+function findProjectRoot(startPath) {
+	let current = node_path.default.resolve(startPath || process.cwd());
+	while (current !== node_path.default.dirname(current)) {
+		const gitDir = node_path.default.join(current, ".git");
+		if (node_fs.default.existsSync(gitDir)) return current;
+		current = node_path.default.dirname(current);
+	}
+	const rootGitDir = node_path.default.join(current, ".git");
+	if (node_fs.default.existsSync(rootGitDir)) return current;
+	return null;
+}
+/**
+* Validate agent name to prevent invalid filesystem paths and security issues.
+*
+* @param agentName - The agent name to validate
+* @returns True if valid, false otherwise
+*/
+function isValidAgentName(agentName) {
+	if (!agentName || !agentName.trim()) return false;
+	return /^[a-zA-Z0-9_\-\s]+$/.test(agentName);
+}
+/**
+* Create a Settings instance with detected environment.
+*
+* @param options - Configuration options
+* @returns Settings instance with project detection and path management
+*/
+function createSettings(options = {}) {
+	const projectRoot = findProjectRoot(options.startPath);
+	const userDeepagentsDir = node_path.default.join(node_os.default.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 node_path.default.join(userDeepagentsDir, agentName);
+		},
+		ensureAgentDir(agentName) {
+			const agentDir = this.getAgentDir(agentName);
+			node_fs.default.mkdirSync(agentDir, { recursive: true });
+			return agentDir;
+		},
+		getUserAgentMdPath(agentName) {
+			return node_path.default.join(this.getAgentDir(agentName), "agent.md");
+		},
+		getProjectAgentMdPath() {
+			if (!projectRoot) return null;
+			return node_path.default.join(projectRoot, ".deepagents", "agent.md");
+		},
+		getUserSkillsDir(agentName) {
+			return node_path.default.join(this.getAgentDir(agentName), "skills");
+		},
+		ensureUserSkillsDir(agentName) {
+			const skillsDir = this.getUserSkillsDir(agentName);
+			node_fs.default.mkdirSync(skillsDir, { recursive: true });
+			return skillsDir;
+		},
+		getProjectSkillsDir() {
+			if (!projectRoot) return null;
+			return node_path.default.join(projectRoot, ".deepagents", "skills");
+		},
+		ensureProjectSkillsDir() {
+			const skillsDir = this.getProjectSkillsDir();
+			if (!skillsDir) return null;
+			node_fs.default.mkdirSync(skillsDir, { recursive: true });
+			return skillsDir;
+		},
+		ensureProjectDeepagentsDir() {
+			if (!projectRoot) return null;
+			const deepagentsDir = node_path.default.join(projectRoot, ".deepagents");
+			node_fs.default.mkdirSync(deepagentsDir, { recursive: true });
+			return deepagentsDir;
+		}
+	};
+}
+
+//#endregion
+//#region src/skills/loader.ts
+/**
+* Skill loader for parsing and loading agent skills from SKILL.md files.
+*
+* This module implements Anthropic's agent skills pattern with YAML frontmatter parsing.
+* Each skill is a directory containing a SKILL.md file with:
+* - YAML frontmatter (name, description required)
+* - Markdown instructions for the agent
+* - Optional supporting files (scripts, configs, etc.)
+*
+* @example
+* ```markdown
+* ---
+* name: web-research
+* description: Structured approach to conducting thorough web research
+* ---
+*
+* # Web Research Skill
+*
+* ## When to Use
+* - User asks you to research a topic
+* ...
+* ```
+*
+* @see https://agentskills.io/specification
+*/
+/** Maximum size for SKILL.md files (10MB) */
+const MAX_SKILL_FILE_SIZE = 10 * 1024 * 1024;
+/** Agent Skills spec constraints */
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_SKILL_DESCRIPTION_LENGTH = 1024;
+/** Pattern for validating skill names per Agent Skills spec */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** Pattern for extracting YAML frontmatter */
+const FRONTMATTER_PATTERN = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+/**
+* Check if a path is safely contained within base_dir.
+*
+* This prevents directory traversal attacks via symlinks or path manipulation.
+* The function resolves both paths to their canonical form (following symlinks)
+* and verifies that the target path is within the base directory.
+*
+* @param targetPath - The path to validate
+* @param baseDir - The base directory that should contain the path
+* @returns True if the path is safely within baseDir, false otherwise
+*/
+function isSafePath(targetPath, baseDir) {
+	try {
+		const resolvedPath = node_fs.default.realpathSync(targetPath);
+		const resolvedBase = node_fs.default.realpathSync(baseDir);
+		return resolvedPath.startsWith(resolvedBase + node_path.default.sep) || resolvedPath === resolvedBase;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate skill name per Agent Skills spec.
+*
+* Requirements:
+* - Max 64 characters
+* - Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
+* - Cannot start or end with hyphen
+* - No consecutive hyphens
+* - Must match parent directory name
+*
+* @param name - The skill name from YAML frontmatter
+* @param directoryName - The parent directory name
+* @returns Validation result with error message if invalid
+*/
+function validateSkillName(name, directoryName) {
+	if (!name) return {
+		valid: false,
+		error: "name is required"
+	};
+	if (name.length > MAX_SKILL_NAME_LENGTH) return {
+		valid: false,
+		error: "name exceeds 64 characters"
+	};
+	if (!SKILL_NAME_PATTERN.test(name)) return {
+		valid: false,
+		error: "name must be lowercase alphanumeric with single hyphens only"
+	};
+	if (name !== directoryName) return {
+		valid: false,
+		error: `name '${name}' must match directory name '${directoryName}'`
+	};
+	return { valid: true };
+}
+/**
+* Parse YAML frontmatter from content.
+*
+* @param content - The file content
+* @returns Parsed frontmatter object, or null if parsing fails
+*/
+function parseFrontmatter(content) {
+	const match = content.match(FRONTMATTER_PATTERN);
+	if (!match) return null;
+	try {
+		const parsed = yaml.default.parse(match[1]);
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse YAML frontmatter from a SKILL.md file per Agent Skills spec.
+*
+* @param skillMdPath - Path to the SKILL.md file
+* @param source - Source of the skill ('user' or 'project')
+* @returns SkillMetadata with all fields, or null if parsing fails
+*/
+function parseSkillMetadata(skillMdPath, source) {
+	try {
+		const stats = node_fs.default.statSync(skillMdPath);
+		if (stats.size > MAX_SKILL_FILE_SIZE) {
+			console.warn(`Skipping ${skillMdPath}: file too large (${stats.size} bytes)`);
+			return null;
+		}
+		const frontmatter = parseFrontmatter(node_fs.default.readFileSync(skillMdPath, "utf-8"));
+		if (!frontmatter) {
+			console.warn(`Skipping ${skillMdPath}: no valid YAML frontmatter found`);
+			return null;
+		}
+		const name = frontmatter.name;
+		const description = frontmatter.description;
+		if (!name || !description) {
+			console.warn(`Skipping ${skillMdPath}: missing required 'name' or 'description'`);
+			return null;
+		}
+		const directoryName = node_path.default.basename(node_path.default.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);
+		if (descriptionStr.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+			console.warn(`Description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} chars in ${skillMdPath}, truncating`);
+			descriptionStr = descriptionStr.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+		}
+		return {
+			name: String(name),
+			description: descriptionStr,
+			path: skillMdPath,
+			source,
+			license: frontmatter.license ? String(frontmatter.license) : void 0,
+			compatibility: frontmatter.compatibility ? String(frontmatter.compatibility) : void 0,
+			metadata: frontmatter.metadata && typeof frontmatter.metadata === "object" ? frontmatter.metadata : void 0,
+			allowedTools: frontmatter["allowed-tools"] ? String(frontmatter["allowed-tools"]) : void 0
+		};
+	} catch (error) {
+		console.warn(`Error reading ${skillMdPath}: ${error}`);
+		return null;
+	}
+}
+/**
+* List all skills from a single skills directory (internal helper).
+*
+* Scans the skills directory for subdirectories containing SKILL.md files,
+* parses YAML frontmatter, and returns skill metadata.
+*
+* Skills are organized as:
+* ```
+* skills/
+* ├── skill-name/
+* │   ├── SKILL.md        # Required: instructions with YAML frontmatter
+* │   ├── script.py       # Optional: supporting files
+* │   └── config.json     # Optional: supporting files
+* ```
+*
+* @param skillsDir - Path to the skills directory
+* @param source - Source of the skills ('user' or 'project')
+* @returns List of skill metadata
+*/
+function listSkillsFromDir(skillsDir, source) {
+	const expandedDir = skillsDir.startsWith("~") ? node_path.default.join(process.env.HOME || process.env.USERPROFILE || "", skillsDir.slice(1)) : skillsDir;
+	if (!node_fs.default.existsSync(expandedDir)) return [];
+	let resolvedBase;
+	try {
+		resolvedBase = node_fs.default.realpathSync(expandedDir);
+	} catch {
+		return [];
+	}
+	const skills = [];
+	let entries;
+	try {
+		entries = node_fs.default.readdirSync(resolvedBase, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	for (const entry of entries) {
+		const skillDir = node_path.default.join(resolvedBase, entry.name);
+		if (!isSafePath(skillDir, resolvedBase)) continue;
+		if (!entry.isDirectory()) continue;
+		const skillMdPath = node_path.default.join(skillDir, "SKILL.md");
+		if (!node_fs.default.existsSync(skillMdPath)) continue;
+		if (!isSafePath(skillMdPath, resolvedBase)) continue;
+		const metadata = parseSkillMetadata(skillMdPath, source);
+		if (metadata) skills.push(metadata);
+	}
+	return skills;
+}
+/**
+* List skills from user and/or project directories.
+*
+* When both directories are provided, project skills with the same name as
+* user skills will override them.
+*
+* @param options - Options specifying which directories to search
+* @returns Merged list of skill metadata from both sources, with project skills
+*          taking precedence over user skills when names conflict
+*/
+function listSkills(options) {
+	const allSkills = /* @__PURE__ */ new Map();
+	if (options.userSkillsDir) {
+		const userSkills = listSkillsFromDir(options.userSkillsDir, "user");
+		for (const skill of userSkills) allSkills.set(skill.name, skill);
+	}
+	if (options.projectSkillsDir) {
+		const projectSkills = listSkillsFromDir(options.projectSkillsDir, "project");
+		for (const skill of projectSkills) allSkills.set(skill.name, skill);
+	}
+	return Array.from(allSkills.values());
+}
+
+//#endregion
+//#region src/middleware/skills.ts
+/**
+* Middleware for loading and exposing agent skills to the system prompt.
+*
+* This middleware implements Anthropic's "Agent Skills" pattern with progressive disclosure:
+* 1. Parse YAML frontmatter from SKILL.md files at session start
+* 2. Inject skills metadata (name + description) into system prompt
+* 3. Agent reads full SKILL.md content when relevant to a task
+*
+* Skills directory structure (per-agent + project):
+* User-level: ~/.deepagents/{AGENT_NAME}/skills/
+* Project-level: {PROJECT_ROOT}/.deepagents/skills/
+*
+* @example
+* ```
+* ~/.deepagents/{AGENT_NAME}/skills/
+* ├── web-research/
+* │   ├── SKILL.md        # Required: YAML frontmatter + instructions
+* │   └── helper.py       # Optional: supporting files
+* ├── code-review/
+* │   ├── SKILL.md
+* │   └── checklist.md
+*
+* .deepagents/skills/
+* ├── project-specific/
+* │   └── SKILL.md        # Project-specific skills
+* ```
+*/
+/**
+* State schema for skills middleware.
+*/
+const SkillsStateSchema = zod.z.object({ skillsMetadata: zod.z.array(zod.z.object({
+	name: zod.z.string(),
+	description: zod.z.string(),
+	path: zod.z.string(),
+	source: zod.z.enum(["user", "project"]),
+	license: zod.z.string().optional(),
+	compatibility: zod.z.string().optional(),
+	metadata: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+	allowedTools: zod.z.string().optional()
+})).optional() });
+/**
+* Skills System Documentation prompt template.
+*/
+const SKILLS_SYSTEM_PROMPT = `
+
+## Skills System
+
+You have access to a skills library that provides specialized capabilities and domain knowledge.
+
+{skills_locations}
+
+**Available Skills:**
+
+{skills_list}
+
+**How to Use Skills (Progressive Disclosure):**
+
+Skills follow a **progressive disclosure** pattern - you know they exist (name + description above), but you only read the full instructions when needed:
+
+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
+
+**When to Use Skills:**
+- When the user's request matches a skill's domain (e.g., "research X" → web-research skill)
+- When you need specialized knowledge or structured workflows
+- When a skill provides proven patterns for complex tasks
+
+**Skills are Self-Documenting:**
+- Each SKILL.md tells you exactly what the skill does and how to use it
+- 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.
+
+**Example Workflow:**
+
+User: "Can you research the latest developments in quantum computing?"
+
+1. Check available skills above → See "web-research" skill with its full path
+2. Read the skill using the path shown in the list
+3. Follow the skill's research workflow (search → organize → synthesize)
+4. Use any helper scripts with absolute paths
+
+Remember: Skills are tools to make you more capable and consistent. When in doubt, check if a skill exists for the task!
+`;
+/**
+* Format skills locations for display in system prompt.
+*/
+function formatSkillsLocations(userSkillsDisplay, projectSkillsDir) {
+	const locations = [`**User Skills**: \`${userSkillsDisplay}\``];
+	if (projectSkillsDir) locations.push(`**Project Skills**: \`${projectSkillsDir}\` (overrides user skills)`);
+	return locations.join("\n");
+}
+/**
+* Format skills metadata for display in system prompt.
+*/
+function formatSkillsList(skills, userSkillsDisplay, projectSkillsDir) {
+	if (skills.length === 0) {
+		const locations = [userSkillsDisplay];
+		if (projectSkillsDir) locations.push(projectSkillsDir);
+		return `(No skills available yet. You can create skills in ${locations.join(" or ")})`;
+	}
+	const userSkills = skills.filter((s) => s.source === "user");
+	const projectSkills = skills.filter((s) => s.source === "project");
+	const lines = [];
+	if (userSkills.length > 0) {
+		lines.push("**User Skills:**");
+		for (const skill of userSkills) {
+			lines.push(`- **${skill.name}**: ${skill.description}`);
+			lines.push(`  → Read \`${skill.path}\` for full instructions`);
+		}
+		lines.push("");
+	}
+	if (projectSkills.length > 0) {
+		lines.push("**Project Skills:**");
+		for (const skill of projectSkills) {
+			lines.push(`- **${skill.name}**: ${skill.description}`);
+			lines.push(`  → Read \`${skill.path}\` for full instructions`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Create middleware for loading and exposing agent skills.
+*
+* This middleware implements Anthropic's agent skills pattern:
+* - Loads skills metadata (name, description) from YAML frontmatter at session start
+* - Injects skills list into system prompt for discoverability
+* - Agent reads full SKILL.md content when a skill is relevant (progressive disclosure)
+*
+* Supports both user-level and project-level skills:
+* - User skills: ~/.deepagents/{AGENT_NAME}/skills/
+* - Project skills: {PROJECT_ROOT}/.deepagents/skills/
+* - Project skills override user skills with the same name
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for skills loading and injection
+*/
+function createSkillsMiddleware(options) {
+	const { skillsDir, assistantId, projectSkillsDir } = options;
+	const userSkillsDisplay = `~/.deepagents/${assistantId}/skills`;
+	return (0, langchain.createMiddleware)({
+		name: "SkillsMiddleware",
+		stateSchema: SkillsStateSchema,
+		beforeAgent() {
+			return { skillsMetadata: listSkills({
+				userSkillsDir: skillsDir,
+				projectSkillsDir
+			}) };
+		},
+		wrapModelCall(request, handler) {
+			const skillsMetadata = request.state?.skillsMetadata || [];
+			const skillsLocations = formatSkillsLocations(userSkillsDisplay, projectSkillsDir);
+			const skillsList = formatSkillsList(skillsMetadata, userSkillsDisplay, projectSkillsDir);
+			const skillsSection = SKILLS_SYSTEM_PROMPT.replace("{skills_locations}", skillsLocations).replace("{skills_list}", skillsList);
+			const currentSystemPrompt = request.systemPrompt || "";
+			const newSystemPrompt = currentSystemPrompt ? `${currentSystemPrompt}\n\n${skillsSection}` : skillsSection;
+			return handler({
+				...request,
+				systemPrompt: newSystemPrompt
+			});
+		}
+	});
+}
+
+//#endregion
+//#region src/middleware/agent-memory.ts
+/**
+* Middleware for loading agent-specific long-term memory into the system prompt.
+*
+* This middleware loads the agent's long-term memory from agent.md files
+* and injects it into the system prompt. Memory is loaded from:
+* - User memory: ~/.deepagents/{agent_name}/agent.md
+* - Project memory: {project_root}/.deepagents/agent.md
+*/
+/**
+* State schema for agent memory middleware.
+*/
+const AgentMemoryStateSchema = zod.z.object({
+	userMemory: zod.z.string().optional(),
+	projectMemory: zod.z.string().optional()
+});
+/**
+* Default template for memory injection.
+*/
+const DEFAULT_MEMORY_TEMPLATE = `<user_memory>
+{user_memory}
+</user_memory>
+
+<project_memory>
+{project_memory}
+</project_memory>`;
+/**
+* Long-term Memory Documentation system prompt.
+*/
+const LONGTERM_MEMORY_SYSTEM_PROMPT = `
+
+## Long-term Memory
+
+Your long-term memory is stored in files on the filesystem and persists across sessions.
+
+**User Memory Location**: \`{agent_dir_absolute}\` (displays as \`{agent_dir_display}\`)
+**Project Memory Location**: {project_memory_info}
+
+Your system prompt is loaded from TWO sources at startup:
+1. **User agent.md**: \`{agent_dir_absolute}/agent.md\` - Your personal preferences across all projects
+2. **Project agent.md**: Loaded from project root if available - Project-specific instructions
+
+Project-specific agent.md is loaded from these locations (both combined if both exist):
+- \`[project-root]/.deepagents/agent.md\` (preferred)
+- \`[project-root]/agent.md\` (fallback, but also included if both exist)
+
+**When to CHECK/READ memories (CRITICAL - do this FIRST):**
+- **At the start of ANY new session**: Check both user and project memories
+  - User: \`ls {agent_dir_absolute}\`
+  - Project: \`ls {project_deepagents_dir}\` (if in a project)
+- **BEFORE answering questions**: If asked "what do you know about X?" or "how do I do Y?", check project memories FIRST, then user
+- **When user asks you to do something**: Check if you have project-specific guides or examples
+- **When user references past work**: Search project memory files for related context
+
+**Memory-first response pattern:**
+1. User asks a question → Check project directory first: \`ls {project_deepagents_dir}\`
+2. If relevant files exist → Read them with \`read_file '{project_deepagents_dir}/[filename]'\`
+3. Check user memory if needed → \`ls {agent_dir_absolute}\`
+4. Base your answer on saved knowledge supplemented by general knowledge
+
+**When to update memories:**
+- **IMMEDIATELY when the user describes your role or how you should behave**
+- **IMMEDIATELY when the user gives feedback on your work** - Update memories to capture what was wrong and how to do it better
+- When the user explicitly asks you to remember something
+- When patterns or preferences emerge (coding styles, conventions, workflows)
+- After significant work where context would help in future sessions
+
+**Learning from feedback:**
+- 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
+- When user says "you should remember X" or "be careful about Y", treat this as HIGH PRIORITY - update memories IMMEDIATELY
+- Look for the underlying principle behind corrections, not just the specific mistake
+
+## Deciding Where to Store Memory
+
+When writing or updating agent memory, decide whether each fact, configuration, or behavior belongs in:
+
+### User Agent File: \`{agent_dir_absolute}/agent.md\`
+→ Describes the agent's **personality, style, and universal behavior** across all projects.
+
+**Store here:**
+- Your general tone and communication style
+- Universal coding preferences (formatting, comment style, etc.)
+- General workflows and methodologies you follow
+- Tool usage patterns that apply everywhere
+- Personal preferences that don't change per-project
+
+**Examples:**
+- "Be concise and direct in responses"
+- "Always use type hints in Python"
+- "Prefer functional programming patterns"
+
+### Project Agent File: \`{project_deepagents_dir}/agent.md\`
+→ Describes **how this specific project works** and **how the agent should behave here only.**
+
+**Store here:**
+- Project-specific architecture and design patterns
+- Coding conventions specific to this codebase
+- Project structure and organization
+- Testing strategies for this project
+- Deployment processes and workflows
+- Team conventions and guidelines
+
+**Examples:**
+- "This project uses FastAPI with SQLAlchemy"
+- "Tests go in tests/ directory mirroring src/ structure"
+- "All API changes require updating OpenAPI spec"
+
+### Project Memory Files: \`{project_deepagents_dir}/*.md\`
+→ Use for **project-specific reference information** and structured notes.
+
+**Store here:**
+- API design documentation
+- Architecture decisions and rationale
+- Deployment procedures
+- Common debugging patterns
+- Onboarding information
+
+**Examples:**
+- \`{project_deepagents_dir}/api-design.md\` - REST API patterns used
+- \`{project_deepagents_dir}/architecture.md\` - System architecture overview
+- \`{project_deepagents_dir}/deployment.md\` - How to deploy this project
+
+### File Operations:
+
+**User memory:**
+\`\`\`
+ls {agent_dir_absolute}                              # List user memory files
+read_file '{agent_dir_absolute}/agent.md'            # Read user preferences
+edit_file '{agent_dir_absolute}/agent.md' ...        # Update user preferences
+\`\`\`
+
+**Project memory (preferred for project-specific information):**
+\`\`\`
+ls {project_deepagents_dir}                          # List project memory files
+read_file '{project_deepagents_dir}/agent.md'        # Read project instructions
+edit_file '{project_deepagents_dir}/agent.md' ...    # Update project instructions
+write_file '{project_deepagents_dir}/agent.md' ...  # Create project memory file
+\`\`\`
+
+**Important**:
+- Project memory files are stored in \`.deepagents/\` inside the project root
+- Always use absolute paths for file operations
+- Check project memories BEFORE user when answering project-specific questions`;
+/**
+* Create middleware for loading agent-specific long-term memory.
+*
+* This middleware loads the agent's long-term memory from a file (agent.md)
+* and injects it into the system prompt. The memory is loaded once at the
+* start of the conversation and stored in state.
+*
+* @param options - Configuration options
+* @returns AgentMiddleware for memory loading and injection
+*/
+function createAgentMemoryMiddleware(options) {
+	const { settings, assistantId, systemPromptTemplate } = options;
+	const agentDir = settings.getAgentDir(assistantId);
+	const agentDirDisplay = `~/.deepagents/${assistantId}`;
+	const agentDirAbsolute = agentDir;
+	const projectRoot = settings.projectRoot;
+	const projectMemoryInfo = projectRoot ? `\`${projectRoot}\` (detected)` : "None (not in a git project)";
+	const projectDeepagentsDir = projectRoot ? `${projectRoot}/.deepagents` : "[project-root]/.deepagents (not in a project)";
+	const template = systemPromptTemplate || DEFAULT_MEMORY_TEMPLATE;
+	return (0, langchain.createMiddleware)({
+		name: "AgentMemoryMiddleware",
+		stateSchema: AgentMemoryStateSchema,
+		beforeAgent(state) {
+			const result = {};
+			if (!("userMemory" in state)) {
+				const userPath = settings.getUserAgentMdPath(assistantId);
+				if (node_fs.default.existsSync(userPath)) try {
+					result.userMemory = node_fs.default.readFileSync(userPath, "utf-8");
+				} catch {}
+			}
+			if (!("projectMemory" in state)) {
+				const projectPath = settings.getProjectAgentMdPath();
+				if (projectPath && node_fs.default.existsSync(projectPath)) try {
+					result.projectMemory = node_fs.default.readFileSync(projectPath, "utf-8");
+				} catch {}
+			}
+			return Object.keys(result).length > 0 ? result : void 0;
+		},
+		wrapModelCall(request, handler) {
+			const userMemory = request.state?.userMemory;
+			const projectMemory = request.state?.projectMemory;
+			const baseSystemPrompt = request.systemPrompt || "";
+			const memorySection = template.replace("{user_memory}", userMemory || "(No user agent.md)").replace("{project_memory}", projectMemory || "(No project agent.md)");
+			const memoryDocs = LONGTERM_MEMORY_SYSTEM_PROMPT.replaceAll("{agent_dir_absolute}", agentDirAbsolute).replaceAll("{agent_dir_display}", agentDirDisplay).replaceAll("{project_memory_info}", projectMemoryInfo).replaceAll("{project_deepagents_dir}", projectDeepagentsDir);
+			let systemPrompt = memorySection;
+			if (baseSystemPrompt) systemPrompt += "\n\n" + baseSystemPrompt;
+			systemPrompt += "\n\n" + memoryDocs;
+			return handler({
+				...request,
+				systemPrompt
+			});
+		}
+	});
+}
+
+//#endregion
+exports.BaseSandbox = BaseSandbox;
+exports.CompositeBackend = CompositeBackend;
+exports.FilesystemBackend = FilesystemBackend;
+exports.MAX_SKILL_DESCRIPTION_LENGTH = MAX_SKILL_DESCRIPTION_LENGTH;
+exports.MAX_SKILL_FILE_SIZE = MAX_SKILL_FILE_SIZE;
+exports.MAX_SKILL_NAME_LENGTH = MAX_SKILL_NAME_LENGTH;
+exports.StateBackend = StateBackend;
+exports.StoreBackend = StoreBackend;
+exports.createAgentMemoryMiddleware = createAgentMemoryMiddleware;
+exports.createDeepAgent = createDeepAgent;
+exports.createFilesystemMiddleware = createFilesystemMiddleware;
+exports.createPatchToolCallsMiddleware = createPatchToolCallsMiddleware;
+exports.createSettings = createSettings;
+exports.createSkillsMiddleware = createSkillsMiddleware;
+exports.createSubAgentMiddleware = createSubAgentMiddleware;
+exports.findProjectRoot = findProjectRoot;
+exports.isSandboxBackend = isSandboxBackend;
+exports.listSkills = listSkills;
+exports.parseSkillMetadata = parseSkillMetadata;
+//# sourceMappingURL=index.cjs.map